@adobe/spectrum-design-data 0.3.0 → 0.6.0

package/components/picker.json

@@ -9,173 +9,211 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/picker/"
   },
-  "options": {
-    "label": {
-      "type": "string"
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Pickers (sometimes known as \"dropdowns\" or \"selects\") allow users to choose from a list of options in a limited space. The list of options can change based on the context."
     },
-    "labelPosition": {
-      "type": "string",
-      "default": "top",
-      "values": [
-        {
-          "value": "top"
-        },
-        {
-          "value": "side"
-        }
-      ]
+    {
+      "type": "guideline",
+      "content": "Pickers present a list of options in a compact format for selection. They’re sometimes called “dropdowns” or “selects,” and the available options may change based on context."
     },
-    "placeholder": {
-      "type": "string"
+    {
+      "type": "guideline",
+      "content": "The error message communicates an error for when the selection requirements aren’t met, prompting a user to adjust what they had originally selected."
     },
-    "value": {
-      "type": "string"
+    {
+      "type": "guideline",
+      "content": "A picker can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field."
     },
-    "width": {
-      "type": "number",
-      "description": "Not applicable to quiet picker."
+    {
+      "type": "guideline",
+      "content": "A picker can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid."
     },
-    "size": {
-      "type": "string",
-      "default": "m",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
-      ]
+    {
+      "type": "guideline",
+      "content": "A picker in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later."
     },
-    "isQuiet": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "The picker menu is a menu element that is used to display the options for the picker. A picker menu can include menu items, menu dividers, and menu groups. A picker menu should never contain submenus, as doing so would render it inaccessible."
     },
-    "necessityIndicator": {
-      "type": "string",
-      "default": "icon",
-      "values": [
-        {
-          "value": "text"
-        },
-        {
-          "value": "icon"
-        }
-      ]
+    {
+      "type": "guideline",
+      "content": "For required pickers, you have two options:"
     },
-    "isRequired": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "For optional pickers, you have two options:"
     },
-    "menuContainer": {
-      "type": "string",
-      "default": "popover",
-      "values": [
-        {
-          "value": "popover"
-        },
-        {
-          "value": "tray"
-        }
-      ]
+    {
+      "type": "guideline",
+      "content": "By default, pickers have a visible background. This style works best in a dense array of controls where the background helps to separate the input from the surrounding container, or to give visibility to isolated buttons."
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "Alternatively, quiet pickers can have no visible background. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read."
     },
-    "isError": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "Pickers come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page."
     },
-    "description": {
-      "type": "string",
-      "default": null
+    {
+      "type": "guideline",
+      "content": "The width of a picker can be customized appropriately for its context. This option is not applicable to quiet pickers."
     },
-    "errorMessage": {
-      "type": "string",
-      "default": null
-    }
-  },
-  "states": [
     {
-      "name": "hover",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "The value shows the option that a user has selected."
     },
     {
-      "name": "focus-+-hover",
-      "trigger": "prop"
+      "type": "guideline",
+      "content": "Placeholder text provides hints about expected input values. It disappears once a user selects an option."
     },
     {
-      "name": "focus-+-not-hover",
-      "trigger": "prop"
+      "type": "guideline",
+      "content": "Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited."
     },
     {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
-  ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
+      "type": "guideline",
+      "content": "Pickers should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These pickers without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”)."
+    },
     {
-      "token": "field-default-width-small",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "When the field label and menu text are too long for the available horizontal space, they wrap to form another line. The field text itself truncates at the end, but the text can be shown in full in the menu."
     },
     {
-      "token": "field-default-width-medium",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "When the help or error text is too long for the available horizontal space, it wraps to form another line."
     },
     {
-      "token": "field-default-width-large",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "The picker menu can be as tall as necessary to show as many options as possible in the available space. There is no maximum height."
     },
     {
-      "token": "field-default-width-extra-large",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "Every picker should have a label. A picker without a label is ambiguous and not accessible."
     },
     {
-      "token": "picker-minimum-width-multiplier",
-      "context": "Width (minimum)"
+      "type": "guideline",
+      "content": "In rare cases where context is sufficient and a label could be absent, make sure to have the design reviewed and approved by an accessibility expert. These should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”)."
+    },
+    {
+      "type": "guideline",
+      "content": "Keep menu items short and concise. Long menu items that cause text to wrap to multiple lines are discouraged. If text wrapping becomes a frequent concern, consider revising the text or use alternative UI patterns that will give your content more space."
+    },
+    {
+      "type": "guideline",
+      "content": "When possible, the field button width should be wide enough so that any chosen menu items can be displayed in full."
+    },
+    {
+      "type": "guideline",
+      "content": "Field labels, placeholder text, and menu items should be in sentence case."
+    },
+    {
+      "type": "guideline",
+      "content": "When labeling pickers in a form, only mark the minority type — either required or optional — to reduce visual clutter:"
     },
     {
-      "token": "component-height-75",
-      "context": "Height"
+      "type": "guideline",
+      "content": "Never use an asterisk to indicate an optional picker."
     },
     {
-      "token": "component-height-100",
-      "context": "Height"
+      "type": "guideline",
+      "content": "A picker’s description in the help text is can communicate what to select or how to select an option. This includes information such as:"
     },
     {
-      "token": "component-height-200",
-      "context": "Height"
+      "type": "guideline",
+      "content": "The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with a picker. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text."
     },
     {
-      "token": "component-height-300",
-      "context": "Height"
+      "type": "guideline",
+      "content": "The help text area also displays an error message. When a picker already includes help text and an error is triggered, the help text is replaced with error text. Once the error is resolved, the help text description reappears below the picker."
     },
     {
-      "token": "corner-radius-medium-size-small",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "Since one gets replaced by the other, the language of the help text and error text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to complete the interaction. Error text tells a user how to fix the error by re-stating the selection requirements or describing the necessary interaction. Make sure that the help text and the error text include the same essential information so that it isn’t lost if one replaces the other like minimum requirements."
     },
     {
-      "token": "corner-radius-medium-size-medium",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user."
     },
     {
-      "token": "corner-radius-medium-size-large",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "Error text should be written in 1-2 short, complete sentences and in a clear and straightforward way. End sentences with a period, and never with an exclamation point. For pickers, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss selecting an option to note as their preferred contact method, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to be selected: “Select a contact method.”"
     },
     {
-      "token": "corner-radius-medium-size-extra-large",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "Placeholder text provides hints about expected input values. When implemented properly, it enhances usability without compromising accessibility."
+    }
+  ],
+  "options": {
+    "label": { "type": "string" },
+    "labelPosition": {
+      "type": "string",
+      "default": "top",
+      "values": [{ "value": "top" }, { "value": "side" }]
+    },
+    "placeholder": { "type": "string" },
+    "value": { "type": "string" },
+    "width": {
+      "type": "number",
+      "description": "Not applicable to quiet picker."
+    },
+    "size": {
+      "type": "string",
+      "default": "m",
+      "values": [
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
+      ]
+    },
+    "isQuiet": { "type": "boolean", "default": false },
+    "necessityIndicator": {
+      "type": "string",
+      "default": "icon",
+      "values": [{ "value": "text" }, { "value": "icon" }]
+    },
+    "isRequired": { "type": "boolean", "default": false },
+    "menuContainer": {
+      "type": "string",
+      "default": "popover",
+      "values": [{ "value": "popover" }, { "value": "tray" }]
+    },
+    "isDisabled": { "type": "boolean", "default": false },
+    "isError": { "type": "boolean", "default": false },
+    "description": { "type": "string", "default": null },
+    "errorMessage": { "type": "string", "default": null }
+  },
+  "states": [
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "focus-+-hover", "trigger": "prop" },
+    { "name": "focus-+-not-hover", "trigger": "prop" },
+    { "name": "keyboard-focus", "trigger": "interaction" }
+  ],
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "tokenBindings": [
+    { "token": "field-default-width-small", "context": "Width (default)" },
+    { "token": "field-default-width-medium", "context": "Width (default)" },
+    { "token": "field-default-width-large", "context": "Width (default)" },
+    {
+      "token": "field-default-width-extra-large",
+      "context": "Width (default)"
+    },
+    {
+      "token": "picker-minimum-width-multiplier",
+      "context": "Width (minimum)"
     },
+    { "token": "component-height-75", "context": "Height" },
+    { "token": "component-height-100", "context": "Height" },
+    { "token": "component-height-200", "context": "Height" },
+    { "token": "component-height-300", "context": "Height" },
+    { "token": "corner-radius-medium-size-small", "context": "Rounding" },
+    { "token": "corner-radius-medium-size-medium", "context": "Rounding" },
+    { "token": "corner-radius-medium-size-large", "context": "Rounding" },
+    { "token": "corner-radius-medium-size-extra-large", "context": "Rounding" },
     {
       "token": "component-edge-to-text-75",
       "context": "Spacing (start/end edge to value)"
@@ -196,14 +234,8 @@
       "token": "field-edge-to-text-quiet",
       "context": "Spacing (start/end edge to value)"
     },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus indicator"
-    },
-    {
-      "token": "focus-indicator-gap",
-      "context": "Focus indicator"
-    },
+    { "token": "focus-indicator-thickness", "context": "Focus indicator" },
+    { "token": "focus-indicator-gap", "context": "Focus indicator" },
     {
       "token": "component-size-difference-down",
       "context": "Component size (down)"
@@ -216,22 +248,10 @@
       "token": "component-size-minimum-perspective-down",
       "context": "Component size (down)"
     },
-    {
-      "token": "workflow-icon-size-75",
-      "context": "Prefix min-width"
-    },
-    {
-      "token": "workflow-icon-size-100",
-      "context": "Prefix min-width"
-    },
-    {
-      "token": "workflow-icon-size-200",
-      "context": "Prefix min-width"
-    },
-    {
-      "token": "workflow-icon-size-300",
-      "context": "Prefix min-width"
-    },
+    { "token": "workflow-icon-size-75", "context": "Prefix min-width" },
+    { "token": "workflow-icon-size-100", "context": "Prefix min-width" },
+    { "token": "workflow-icon-size-200", "context": "Prefix min-width" },
+    { "token": "workflow-icon-size-300", "context": "Prefix min-width" },
     {
       "token": "picker-end-edge-to-disclosure-icon-quiet",
       "context": "Spacing (start/end edge to prefix)"
@@ -252,22 +272,10 @@
       "token": "text-to-visual-300",
       "context": "Spacing (prefix to value/placeholder)"
     },
-    {
-      "token": "chevron-icon-size-75",
-      "context": "Chevron/disclosure icon"
-    },
-    {
-      "token": "chevron-icon-size-100",
-      "context": "Chevron/disclosure icon"
-    },
-    {
-      "token": "chevron-icon-size-200",
-      "context": "Chevron/disclosure icon"
-    },
-    {
-      "token": "chevron-icon-size-300",
-      "context": "Chevron/disclosure icon"
-    },
+    { "token": "chevron-icon-size-75", "context": "Chevron/disclosure icon" },
+    { "token": "chevron-icon-size-100", "context": "Chevron/disclosure icon" },
+    { "token": "chevron-icon-size-200", "context": "Chevron/disclosure icon" },
+    { "token": "chevron-icon-size-300", "context": "Chevron/disclosure icon" },
     {
       "token": "field-top-to-disclosure-icon-75",
       "context": "Spacing (top/bottom to disclosure icon)"
@@ -404,154 +412,46 @@
       "token": "field-top-to-progress-circle-extra-large",
       "context": "Spacing (top/bottom edge to progress circle icon)"
     },
-    {
-      "token": "gray-100",
-      "context": "Background"
-    },
-    {
-      "token": "gray-200",
-      "context": "Background"
-    },
-    {
-      "token": "negative-border-color-default",
-      "context": "Border (error)"
-    },
-    {
-      "token": "negative-border-color-hover",
-      "context": "Border (error)"
-    },
-    {
-      "token": "negative-border-color-down",
-      "context": "Border (error)"
-    },
+    { "token": "gray-100", "context": "Background" },
+    { "token": "gray-200", "context": "Background" },
+    { "token": "negative-border-color-default", "context": "Border (error)" },
+    { "token": "negative-border-color-hover", "context": "Border (error)" },
+    { "token": "negative-border-color-down", "context": "Border (error)" },
     {
       "token": "negative-border-color-focus-hover",
       "context": "Border (error)"
     },
-    {
-      "token": "negative-border-color-focus",
-      "context": "Border (error)"
-    },
-    {
-      "token": "negative-border-color-key-focus",
-      "context": "Border (error)"
-    },
-    {
-      "token": "neutral-content-color-default",
-      "context": "Value"
-    },
-    {
-      "token": "neutral-content-color-hover",
-      "context": "Value"
-    },
-    {
-      "token": "neutral-content-color-down",
-      "context": "Value"
-    },
-    {
-      "token": "neutral-content-color-focus-hover",
-      "context": "Value"
-    },
-    {
-      "token": "neutral-content-color-focus",
-      "context": "Value"
-    },
-    {
-      "token": "neutral-content-color-key-focus",
-      "context": "Value"
-    },
-    {
-      "token": "neutral-subdued-content-color-default",
-      "context": "Label"
-    },
-    {
-      "token": "negative-visual-color",
-      "context": "Alert icon"
-    },
-    {
-      "token": "disabled-background-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "disabled-content-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    },
-    {
-      "token": "gray-700",
-      "context": "Prefix"
-    },
-    {
-      "token": "default-font-family",
-      "context": "Value"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Value"
-    },
-    {
-      "token": "default-font-style",
-      "context": "Value"
-    },
-    {
-      "token": "component-s-regular",
-      "context": "Value"
-    },
-    {
-      "token": "component-m-regular",
-      "context": "Value"
-    },
-    {
-      "token": "component-l-regular",
-      "context": "Value"
-    },
-    {
-      "token": "component-xl-regular",
-      "context": "Value"
-    },
-    {
-      "token": "line-height-font-size-75",
-      "context": "Value"
-    },
-    {
-      "token": "line-height-font-size-100",
-      "context": "Value"
-    },
-    {
-      "token": "line-height-font-size-200",
-      "context": "Value"
-    },
-    {
-      "token": "line-height-font-size-300",
-      "context": "Value"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Value"
-    },
-    {
-      "token": "medium-font-weight",
-      "context": "Prefix"
-    },
-    {
-      "token": "component-s-medium",
-      "context": "Prefix"
-    },
-    {
-      "token": "component-m-medium",
-      "context": "Prefix"
-    },
-    {
-      "token": "component-l-medium",
-      "context": "Prefix"
-    },
-    {
-      "token": "component-xl-medium",
-      "context": "Prefix"
-    }
+    { "token": "negative-border-color-focus", "context": "Border (error)" },
+    { "token": "negative-border-color-key-focus", "context": "Border (error)" },
+    { "token": "neutral-content-color-default", "context": "Value" },
+    { "token": "neutral-content-color-hover", "context": "Value" },
+    { "token": "neutral-content-color-down", "context": "Value" },
+    { "token": "neutral-content-color-focus-hover", "context": "Value" },
+    { "token": "neutral-content-color-focus", "context": "Value" },
+    { "token": "neutral-content-color-key-focus", "context": "Value" },
+    { "token": "neutral-subdued-content-color-default", "context": "Label" },
+    { "token": "negative-visual-color", "context": "Alert icon" },
+    { "token": "disabled-background-color", "context": "Disabled" },
+    { "token": "disabled-content-color", "context": "Disabled" },
+    { "token": "focus-indicator-color", "context": "Focus ring" },
+    { "token": "gray-700", "context": "Prefix" },
+    { "token": "default-font-family", "context": "Value" },
+    { "token": "regular-font-weight", "context": "Value" },
+    { "token": "default-font-style", "context": "Value" },
+    { "token": "component-s-regular", "context": "Value" },
+    { "token": "component-m-regular", "context": "Value" },
+    { "token": "component-l-regular", "context": "Value" },
+    { "token": "component-xl-regular", "context": "Value" },
+    { "token": "line-height-font-size-75", "context": "Value" },
+    { "token": "line-height-font-size-100", "context": "Value" },
+    { "token": "line-height-font-size-200", "context": "Value" },
+    { "token": "line-height-font-size-300", "context": "Value" },
+    { "token": "cjk-line-height-100", "context": "Value" },
+    { "token": "medium-font-weight", "context": "Prefix" },
+    { "token": "component-s-medium", "context": "Prefix" },
+    { "token": "component-m-medium", "context": "Prefix" },
+    { "token": "component-l-medium", "context": "Prefix" },
+    { "token": "component-xl-medium", "context": "Prefix" }
   ],
   "accessibility": {
     "role": "combobox",
@@ -559,21 +459,9 @@
     "focusable": true,
     "keyboardIntents": ["expand", "collapse", "navigate-options"],
     "wcag": [
-      {
-        "criterion": "1.3.1",
-        "level": "A",
-        "title": "Info and Relationships"
-      },
-      {
-        "criterion": "2.1.1",
-        "level": "A",
-        "title": "Keyboard"
-      },
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
+      { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }