From e7e84a337717b0c0b47d59bdb48ade274670907d Mon Sep 17 00:00:00 2001 From: Philipp Gfeller Date: Sat, 15 Jul 2023 22:16:33 +0200 Subject: [PATCH 01/35] chore: initialize switch explainer --- .../src/pages/components/switch.explainer.mdx | 224 ++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 site/src/pages/components/switch.explainer.mdx diff --git a/site/src/pages/components/switch.explainer.mdx b/site/src/pages/components/switch.explainer.mdx new file mode 100644 index 000000000..2a64b5134 --- /dev/null +++ b/site/src/pages/components/switch.explainer.mdx @@ -0,0 +1,224 @@ +--- +name: { ComponentName } + +showInMenu: false +layout: ../layouts/ComponentLayout.astro +--- + +> This document represents a component specification template. Its purpose +> is to provide a point-in-time guide as to how a component should be +> authored, in light of common anatomies, behaviors, and accessibility. +> The primary audience is a developer authoring a given component. + +# `{ComponentName}` Component Specification + +## Overview + +_The name of the component, along with a high-level description._ + +### Background + +_Relevant historical or background information, related existing issues, etc._ + +### Use Cases + +_Primary use cases for this component._ + +### Non-goals + +_A list of use cases, features, or functionality which are **not** goals for the component._ + +### Features + +_A list of the key features unique to this component._ + +### Risks and Challenges + +_Notable risks or challenges associated with the component. Link issues related to platform blockers._ + +### Prior Art/Examples + +_Link to the OpenUI research page for the component. If any existing, canonical, or exemplary implementations of the component are found beyond what is documented in the research page, make a separate PR to add them there._ + +--- + +## Design + +_Describe the design of the component, thinking through several perspectives:_ + +- _A customer using the component on a web page._ +- _A developer building an app with the component and interacting through HTML/CSS/JavaScript._ +- _A designer customizing the component._ + +### APIs + +_Outline the key elements of the component's public API surface, taking into consideration conformance guidelines. Make sure to discuss differences and rationalizations. Consider high and low-level APIs. Attempt to design a powerful and extensible low-level API with a high-level API for developer/designer ergonomics and simplicity._ + +#### Properties and Attributes + +_Example Table_ + +| Property Name | Attribute Name | Type | Default Value | Description | +| ------------- | -------------- | -------- | -------------- | -------------------------------- | +| `value` | `value` | `number` | Value of `min` | The current value of the slider. | +| `min` | `min` | `number` | `0` | The minimum value of the slider. | + +#### Methods + +_Example Table_ + +| Signature | Description | +| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `increment(value: number = this.step): void` | Increments the `value` of the component by the amount specified by `step`, clamped within `min`/`max` values. | +| `decrement(value: number = this.step): void` | Decrements the `value` of the component by the amount specified by `step`, clamped within `min`/`max` values. | + +#### Events + +_Example Table_ + +| Event Name | Detail Type | Bubbles | Composed | Cancellable | Dispatch Behavior | +| ---------- | ----------- | ------- | -------- | ----------- | ---------------------------------------- | +| `change` | none | `true` | `true` | `false` | Fired when the slider's `value` changes. | + +### Appearance + +_Screenshots and/or description of the basic appearance of the component._ + +### Anatomy + +_Outline the component's structure with a diagram of its render tree. Enumerate key areas of visual composition and customization._ + +#### Diagram + +_Example_ + +![Example Diagram](../images/spec-diagram-example.png) + +#### DOM Structure + +_Define the recommended DOM to represent the component's anatomy, as shown above. Show how important attributes (aria attributes especially) are applied to the various parts. In cases where a component nests other components, expand the full DOM structure to understand the expectation and any shortcomings in the child components' customizability._ + +#### Slots + +_What parts of the component are composable or replaceable?_ + +_Example Table_ + +| Slot Name | Description | Fallback Content | +| --------- | ------------------------------------------------------------------ | ------------------------------------------- | +| `thumb` | Enables replacing the component's `thumb` part with custom markup. | A default thumb implementation is provided. | + +#### Host Classes + +_What classes does the component add to the host element?_ + +| Class Name | Description | +| ---------- | ----------- | + +#### Slotted Content Classes + +_What classes on slotted content does the component respond to?_ + +| Class Name | Description | +| ---------- | ----------- | + +#### CSS Parts + +_What parts of the component are exposed for styling?_ + +_Example Table_ + +| Part Name | Description | +| --------- | --------------------------------------------------------------------------------------------- | +| `thumb` | Enables styling the `thumb` part without requiring it to be completely replaced via its slot. | + +--- + +## Behavior + +### States and Interactions + +_List key component states, valid state transitions, and how interactions trigger state transitions._ + +- _Are states changed as a result of keyboard? mouse? touch?_ +- _Are there corresponding keyboard interactions for mouse/touch interactions?_ +- _Are some events triggered on key down vs key press?_ + +_Example Table_ + +| State Group | States | Initial State | Description | Interaction/Transition | +| ----------- | -------------- | ------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| `disabled` | `true`/`false` | `false` | When `true`, disables the control, preventing user interaction and displaying the control with a disabled appearance. | No interaction. Controlled programmatically. | + +### Accessibility + +_Consider the accessibility of the component._ + +#### Keyboard Navigation and Focus + +- _Arrow vs tabbing key behavior_ +- _Modifier key effects (e.g. shift, ctrl, meta)_ +- _Does this component use focus delegation?_ + +_Example Table_ + +| Key | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Up/Right | Increments the value of the component by calling the `increment` method. If the `shift` modifier is pressed, increases by 10x the `step` value. | +| Down/Left | Decrements the value of the component by calling the `decrement` method. If the `shift` modifier is pressed, decreases by 10x the `step` value. | + +#### Form Input + +_Does this component integrate with form submission, form validation, etc.? Can integration be accomplish with standard APIs or are special work-arounds required?_ + +#### Use with Assistive Technology + +_Are there any details about shadow dom, focus delegation, or aria attributes that need special attention?_ + +### Globalization + +_Consider whether the component has any special globalization needs such as:_ + +- _Special RTL handling_ +- _Swapping of internal icons/visuals_ +- _Localization_ + +### Security + +_Are there any security implications surrounding the component?_ + +### Performance + +_Are there any performance pitfalls or challenges with implementing the component? (examples below)_ + +- If the component renders a loop of items, should certain areas be considered for virtualization? +- If the component needs to measure an area before rendering, how will jank be avoided? +- If any measuring is needed at all, can rAF techniques help queue measures and prevent synchronous reflows? + +## Dependencies + +_Will implementing the component require taking on any dependencies?_ + +- _3rd party libraries_ +- _Upcoming standards we need to polyfill_ +- _Do any dependencies bring along an associated timeline?_ + +### Platform Requirements + +_Are there any core web platform features that are needed to implement this component well?_ + +### Tooling + +_Are there any special considerations for DevTools? Will tooling changes need to be made? Is there a special way to light up this component in DevTools that would be compelling for developers/designers?_ + +--- + +## Resources + +_Any related resource links such as web standards, discussion threads, diagrams, etc._ + +--- + +## Next Steps + +_What next steps, if any, are there? Is there some functionality that would be a nice-to-have or a common feature in other implementations that could be added but is not considered part of the MVP? Link all feature additions, modifications, bugs, or editorial change issues._ From c59f4cde6a6e8bf6287685488a847c106c158efe Mon Sep 17 00:00:00 2001 From: Philipp Gfeller Date: Wed, 19 Jul 2023 09:36:53 +0200 Subject: [PATCH 02/35] Update switch explainer --- .../src/pages/components/switch.explainer.mdx | 159 ++++++++++++++---- 1 file changed, 127 insertions(+), 32 deletions(-) diff --git a/site/src/pages/components/switch.explainer.mdx b/site/src/pages/components/switch.explainer.mdx index 2a64b5134..44fe57462 100644 --- a/site/src/pages/components/switch.explainer.mdx +++ b/site/src/pages/components/switch.explainer.mdx @@ -1,8 +1,9 @@ --- -name: { ComponentName } - -showInMenu: false -layout: ../layouts/ComponentLayout.astro +menu: Proposals +name: Switch Component Specification +path: /components/switch.explainer +pathToResearch: /components/switch +layout: ../../layouts/ComponentLayout.astro --- > This document represents a component specification template. Its purpose @@ -10,32 +11,58 @@ layout: ../layouts/ComponentLayout.astro > authored, in light of common anatomies, behaviors, and accessibility. > The primary audience is a developer authoring a given component. -# `{ComponentName}` Component Specification - ## Overview -_The name of the component, along with a high-level description._ +A switch toggles a binary state on or off. Other names include "toggle", "lightswitch", "toggle switch" or "toggle button"[^1]. ### Background _Relevant historical or background information, related existing issues, etc._ +https://www.behance.net/gallery/70302039/History-Of-Toggle-UIUX-Case-Study-UI-Samples + ### Use Cases _Primary use cases for this component._ +A switch can be used to indicate and toggle the state of a binary state. Popular use-cases inlcude switching dark mode on or off, switching WiFi on or off and extends to any kind of setting where a user is limited to a binary state - true or false, on or off. + +![Switch example by Material Design, Google Inc.](https://lh3.googleusercontent.com/9ZiRb_i7vCmW5HZ_uu-WNFljJQUnVSMY9ZOnku7ZknH0t9J0AkZwU7NcowggDruiZ6_bwUru_B1QxLq87L6a5NLVlJns4-8aSvq8aYUCFh28=s0) + +Toggling a switch always has an immediate effect. + +It's not recommended to use a switch to toggle between two opposite states. This could include a list vs. map view or, confusingly, switching between light and dark mode (switch light or dark mode on or off, but don't toggle between these opposing states). + ### Non-goals _A list of use cases, features, or functionality which are **not** goals for the component._ +The switch is not a checkbox or radiobutton alternative. + ### Features _A list of the key features unique to this component._ +#### Interaction + +- `click`/`touch`: the switch can be toggled by clicking it +- `drag&drop`: the switch can be toggled by dragging the thumb + +#### Animation + +- background fade +- track slide + +#### Form element + +The switch is also a form element, but should not be used to replace a checkbox or radio buttons in a form. In most modern applications, a JavaScript action will be triggered when the switch toggles. For a more traditional, non-JavaScript approach, it's necessary to receive the state of the switch on the server. In order to facilitate the directness of the action, a switch can be of type "submit". Like a submit button, toggling the switch will immediately submit the associated form to the server. This enables creating a HTML/CSS only settings page while staying true to user expectations of how the component should behave. + ### Risks and Challenges _Notable risks or challenges associated with the component. Link issues related to platform blockers._ +Implementing the switch as a form element could lead developers to use it as a checkbox replacement. + ### Prior Art/Examples _Link to the OpenUI research page for the component. If any existing, canonical, or exemplary implementations of the component are found beyond what is documented in the research page, make a separate PR to add them there._ @@ -58,27 +85,37 @@ _Outline the key elements of the component's public API surface, taking into con _Example Table_ -| Property Name | Attribute Name | Type | Default Value | Description | -| ------------- | -------------- | -------- | -------------- | -------------------------------- | -| `value` | `value` | `number` | Value of `min` | The current value of the slider. | -| `min` | `min` | `number` | `0` | The minimum value of the slider. | +**Open questions:** + +- If form associated, should default value of "on" be submitted if switch is on and the user did not specify a value to align with the [checkbox default value behavior](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value:~:text=If%20the%20value%20attribute%20was%20omitted%2C%20the%20default%20value%20for%20the%20checkbox%20is%20on%2C%20so%20the%20submitted%20data%20in%20that%20case%20would%20be%20subscribe%3Don.)? +- Should a custom "activate initially" attribute be used with the switch (`toggled`) or should the checkbox `checked` attribute be used as a standard? + `` seems more natural while `` is already an established standard + +| Property Name | Attribute Name | Type | Default Value | Description | +| ------------- | -------------- | --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `toggled`(?) | `toggled` | `boolean` | `false` | Indicates if the switch should be "on" initially (similar to the `checked` attribute on the checkbox). | +| `value` | `value` | `string` | `"on"` (?) | The current value of the slider. Only set if the switch is toggled/on on form submission. | +| `name` | `name` | `string` | `""` | The name of the component. | +| `id` | `id` | `string` | `""` | The unique identifier of the component. | +| `type` | `type` | `string` | `button` | Similar to the ` + +``` + +- ` + + + + + ``` -- `