Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Core: Add args feature #10014

Merged
merged 43 commits into from
Mar 10, 2020
Merged

Core: Add args feature #10014

merged 43 commits into from
Mar 10, 2020

Conversation

tmeasday
Copy link
Member

@tmeasday tmeasday commented Mar 2, 2020

Issue: #9811

What I did

Added a new feature to stories called "args"

The idea of this feature is to allow addons to control rendering of stories via "inputs" (and capture "outputs"). Args are initialized by type inference (when available, eg. from TypeScript in your stories, or PropTypes on your components), or by user configuration (via parameters) and can be controlled in various ways in the Storybook UI.

Args map to the rows in the props table in docs mode.

Basic DX of using args:

export const MyStory = ({ primary, size }) => <MyComponent primary={primary} size={size} />;

More info:

  • See the README in this PR

Naming

There has been a bit of back and forth on names and I thought it was useful to outline why we settled on "args" in this PR.

We wanted to capture the idea of "arguments to the story function". It is worth considering that in different frameworks there can be different "categories" of arguments of your component.

  • Although in React there is only "props", capturing both inputs and outputs from the component;
  • in Angular, there are "properties" and "events"
  • in Vue, there are "props" and "events", and "slots", etc etc [apologies if I have details wrong here].

So, although we considered "inputs" it felt like it only captured one side of the picture.

"Properties" seemed a bit long, and "props" seemed a bit React-specific.

Another option considered was "controls" but that seemed too specific to the use case of wanting to change the value of these things via a UI element, which isn't the whole story here.

Sub features.

There are a few things in this PR that enable follow on features built using args:

  • Parameter enhancers -- allow an addon to generate parameters for a story at runtime. This allows complex configuration of arg "types" to be built up from the component type definitions, amongst other things

  • parameters.passArgsFirst -- a new setting (currently defaulting to false, although that may change in 6.0 based on feedback), which means args are seperated from the larger story context and passed first into stories.

  • useArgs() -- a simple hooks API available on client and server for addons to read and set arg values.

@tmeasday tmeasday changed the title Feature/args Add args feature Mar 3, 2020
lib/client-api/README.md Outdated Show resolved Hide resolved
@shilman shilman changed the title Add args feature Core: Add args feature Mar 3, 2020
Copy link
Member

@shilman shilman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great aside from a few naming issues!

lib/api/src/index.tsx Outdated Show resolved Hide resolved
lib/api/src/index.tsx Outdated Show resolved Hide resolved
lib/api/src/index.tsx Outdated Show resolved Hide resolved
lib/api/src/modules/stories.ts Outdated Show resolved Hide resolved
lib/api/src/tests/stories.test.js Outdated Show resolved Hide resolved
lib/client-api/src/story_store.test.ts Outdated Show resolved Hide resolved
lib/client-api/src/story_store.test.ts Outdated Show resolved Hide resolved
lib/client-api/src/story_store.test.ts Outdated Show resolved Hide resolved
lib/client-api/src/story_store.test.ts Outdated Show resolved Hide resolved
lib/client-api/src/story_store.ts Outdated Show resolved Hide resolved
tmeasday and others added 2 commits March 4, 2020 17:23
Thanks @shilman!

Co-Authored-By: Michael Shilman <shilman@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants