Standardize props, events, and slots

[theetrain]

Status: 🟡 Proposal

We have several props and dispatched event names that are reused across components. Let's improve their consistency in naming and intent.

Todo

• Combobox: change titleText to labelText

Prop ordering

Rather than alphabetical order, props SHOULD be ordered in a manner that is intuitive and useful to users. Sveld will generate documentation in the order props are defined within components.

Proposed ordering:

1. ref or [elementName]Ref props
2. Props that support 2-way binding ("reactive" variables)
3. kind
4. size
5. Most important props, grouped with their complements such as labelText and hideLabel
6. Least-used props
7. "Pass-through" props (see $$restProps below)

Prop names

Props that have different intent follow different aspirational rules.

The following MUST be followed:

• Variants: use the name kind to represent a set of other named options for visual or interactive component representations
• Use camelCase for multi-word prop names, but prefer single-word names
• skeleton variants should be separate components; and not a prop toggle

The following SHOULD be followed:

• Flags: props that toggle a feature via true or false values are represented as plain adjectives without an is prefix. Examples: expandable, selectable, selected. Prefer to have them default to false for easy truthy flagging. i.e. absense of selectable implies selectable == false, but the presence of selected toggles to true.
• HTML attributes are provided via Type declarations and should not be included as explicit props unless it has special treatment as part of a component.
  • Appropriate: disabled for <Button>
  • Inappropriate: aria-label for <TextInput>
• If a component contains an underlying interactive element, then a ref prop with 2-way binding should be provided to allow focusing via JS. Appropriate elements include, but aren't limited to:
  • input
  • button
  • inline notification
• Props with multiple options such as size should have all possible values explicitly typed, including defaults, such as 'sm' | 'md' | 'lg' instead of 'sm' | 'lg'. Components impacted:
  • TreeView size
  • ContentSwitcher size
  • ExpandableTile...
  • MultiSelect size
  • OverflowMenu size
  • Search size

Form components

Components that render form inputs MUST have the following props:

• labelText for the label
• helperText for any helpful or hint text placement
• HTML attributes: name, id, value, checked
• readonly should be readOnly

Prop behaviours SHOULD include:

• value is bindable, and can be instantiated (currently not the case for Combobox)

Events

Demo: https://svelte.dev/repl/9b1e3a7822bb4aac9418c95f518523e7?version=3.55.1

In general:

• prefer pointer events over mouse events to ensure cross-compatibility with touch and desktop devices. Use mouse or touch only when necessary

Dispatched events

• Dispatched events MUST be named differently from native events

Forwarded events

• Always forward useful native events. It would be nice if we had a way to forward all events easily (see RFC)
• input-like components SHOULD forward on:input, on:submit, and on:change; this includes TextInput, ComboBox, and others

$$restProps

See #1064 (comment)

• Avoid use of $$restProps since it's a discouraged feature of Svelte
• Components SHOULD include a named prop for spreading element attributes, such as buttonAttributes for <Button>; and labelAttributes and inputAttributes for <TextInput>
• See demo of "pass-through" props https://svelte.dev/repl/f6c1779a4b924686af69a4e9def81621?version=3.56.0

Slots

• All props that accept copy SHOULD have named slots with the same name as their respective prop provided, to allow formatted text or icons to be added.
• If a prop and named slot is provided, the slot has priority and should render instead

### Related tickets
- [ ] #1643
- [ ] #1611
- [ ] #950
- [ ] #314
- [ ] #925
- [ ] #1325
- [ ] #534
- [ ] Apply pass-through props to InlineNotification's NotificationActionButton
- [ ] #461

[metonym]

Linking this: #1420

[brunnerh]

Also related:

• Modal prop names redundant #1325
• Inconsistent label property names? #534

[metonym]

I agree that we should only forward useful events.

A lot of components have a wrapping div in which many events are forwarded to. We should not forward events in these cases as it generates a lot of boilerplate code. A user can always wrap the component with a div and listen to events as they bubble up.

Furthermore, it can be confusing if we forward events to different elements.

Example:

<!-- events forwarded to the div are not useful and can be done by the consumer -->
<div
    on:click
    on:mouseover
    on:mouseenter
    on:mouseleave
>
   <input on:input />
</div>