Storybook property name inconsistencies

[rajsite]

🐛 Bug Report

The property name documentation in storybook is inconsistent. For example see how in the following screenshot how some properties are kebab-case and some are camelCase.

💻 Repro or Code Sample

🤔 Expected Behavior

The storybook documentation should be consistent and make it clear when what is the difference between attributes, properties, events, slot configuration, generic storybook controls

😯 Current Behavior

See repro above.

💁 Possible Solution

Current proposal after discussing at standup:

• Use grouping in the args table: https://storybook.js.org/docs/react/writing-docs/doc-block-argstable#grouping
• Create categories: Attributes/Properties, Slots, Methods, Events
• Use just the name within the categories without syntax embellishment: content-hidden, indeterminate, close, click
• Most closely aligns with the shoelace format: https://shoelace.style/components/alert?id=properties

Alternatives:

• attributes:
  • Show the attribute names content-hidden
  • Show attribute names with the CSS selection syntax to emphasize it is an attribute [content-hidden]
• For properties that do not have corresponding attribute
  • Prepend the name with a period .indeterminate
  • Use the prototype syntax common on mdn to emphasize it is a property Radio.prototype.indeterminate
• For detailed topics that require a discussion and are not coupled to a property or attribute,
  • Topic: Start Icon, Discussion: Start Icon, wrap in quotes "Start Icon", just rely on sentence case Start Icon
• Slots
  • Treat as topic Icon
  • Treat as part of the API: slot="start" or slot "start"
• Events
  • Event close
• Method
  • Method close, close(), or show full type signature: close(result: T): T | USER_DISMISSED

Another alternative:

• Do not expose full API, only attributes and properties

🔦 Context

Current documentation can lead to confusion as discussed in this teams thread.

🌍 Your Environment

N/a

Remaining tasks

• make it clear that the default slot isn't slot="default" and preferably show it as the first slot in the docs
• consistent ordering of table categories in stories and in "Component APIs" docs (probably slots, attributes, properties, methods, events, and localizable labels) A way to sort categories in controls table storybookjs/storybook#27520
• consistent language in docs
  • don't start descriptions with "This attribute..."
  • consistent way to mark attributes as required (*? text?)
  • events start with "Event emitted...". Maybe remove the word "Event"?
  • get rid of "A function that"
• document using forms instead of binding to change events and value attributes
• update incubating and spright components
• Improve API documentation for input components #2132
• API docs for additional components #2135
• update table components
• update banner
• consistently document default values for attributes
• consistently document the type name for enum attributes and see if we can link to their type nicely
• Prettier not running on storybook files #2136
• improve heading hierarchy for pages that document multiple components API docs for additional components #2135 (comment)
• icon slot should use radio instead of boolean controls
• consider hiding stories as children of mdx files (by moving to Internal)
• capture more of these standards in CONTRIBUTING

[rajsite]

• Looked at the following custom element framework docs (@nate-ni are there other examples worth comparing to?):
  • FAST: https://explore.fast.design/components/fast-number-field
    • cons: story names do not align with property names, does not have additional descriptions
  • Shoelace: https://shoelace.style/components/alert?id=properties
    • pros: clearly separates properties, methods, events, slots
    • cons: dedicated docs page / not a storybook pattern, cannot directly play with a property to see the effect
  • Carbon:
    • docs page: https://carbondesignsystem.com/components/number-input/code/ that links to storybook for code:
    • has external link to code as storybook: https://web-components.carbondesignsystem.com/?path=/story/components-number-input--default
    • have to use the separate docs tab to see the properties and attributes: https://web-components.carbondesignsystem.com/?path=/docs/components-number-input--default#bx-number-input-attributes-and-properties
    • cons: lots of links to click through (feels buried), cannot see interactively what the property changes and the documentation at the same time (need to switch between the canvas and docs tabs)

[nate-ni]

@rajsite , I think what we have today (direct controls), mixed with the grouping like Carbon is a great step forward. It also nice that Carbon provides that alternate syntax in the description, when appropriate (supports good ole copy/paste).

Looks like the grouping you mentioned from storybook would provide that as a solution for us.

🤔 Question

Does it have to be the same layout on both the "Controls" tab shown in the "Canvas" view AND the "Docs" view?

If so, no big deal. If not, might be nice to show the simplified (non-grouped) version in the Controls tab for simpler manipulation and the grouped version for the Docs view.