@adobe/spectrum-design-data 0.4.0 → 0.7.0

package/components/slider.json

@@ -9,169 +9,168 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/slider/"
   },
-  "options": {
-    "label": {
-      "type": "string"
-    },
-    "labelPosition": {
-      "type": "string",
-      "default": "top",
-      "values": [
-        {
-          "value": "top"
-        },
-        {
-          "value": "side"
-        }
-      ]
-    },
-    "value": {
-      "type": "number",
-      "description": "from minValue to maxValue"
-    },
-    "minValue": {
-      "type": "number",
-      "default": 0
-    },
-    "maxValue": {
-      "type": "number",
-      "default": 100
-    },
-    "isRange": {
-      "type": "boolean",
-      "default": false,
-      "description": "If true, the slider will allow selection of a range of values by displaying two handles."
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Sliders allow users to quickly select a value within a range. They should be used when the upper and lower bounds to the range are invariable."
     },
-    "step": {
-      "type": "number",
-      "default": 1
+    {
+      "type": "guideline",
+      "content": "Sliders select a value along a continuous range. They’re ideal when upper and lower limits are fixed. Use when approximate or fast selection is more important than precision."
     },
-    "valueFormat": {
-      "type": "string",
-      "description": "This will vary depending on implementation."
+    {
+      "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 text, localization, and responsive layouts. Side labels are most useful when vertical space is limited."
     },
-    "progressionScale": {
-      "type": "string",
-      "default": "linear",
-      "values": [
-        {
-          "value": "linear"
-        },
-        {
-          "value": "log"
-        }
-      ]
-    },
-    "width": {
-      "type": "number"
-    },
-    "hasFill": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "The value is the number selected within the slider’s range, from the min value to max value."
     },
-    "fillStart": {
-      "type": "number",
-      "default": 0
+    {
+      "type": "guideline",
+      "content": "The min and max values can also be customized appropriately for whatever the slider is showing. By default, the min value starts at 0 and the max value is set to 100."
     },
-    "hasGradient": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "More information about a design scenario, to use this option in the component."
     },
-    "isEditable": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "The step is the increment by which these values increase or decrease. A step value of 1 (the default) lets a user only select whole numbers within the min and max range."
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "states": [
     {
-      "name": "hover",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "Sometimes a value needs to be formatted for localization or for clearer communication such as currencies or percentages. Formatting can involve rounding, mathematical transformations, number formatting, or displaying a prefix or suffix, such as “+/-” or “px.”"
     },
     {
-      "name": "down",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "Sliders use a linear progression scale by default which means that value is directly correlated to the position of the handle along the track. In some cases, sliders can use a logarithmic (log) progression scale, which is helpful when users need finer control over small values."
     },
     {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
-  ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
+      "type": "guideline",
+      "content": "The width of a slider can be customized appropriately for its context."
+    },
     {
-      "token": "field-default-width-small",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "The track of the slider can have a fill. By default, the fill originates from the left side of the track."
     },
     {
-      "token": "field-default-width-medium",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "If the value represents an offset, the fill start can be set to represent the point of origin. This allows the slider fill to start from inside the track."
     },
     {
-      "token": "field-default-width-large",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "A gradient can be added to the track of any slider to give more meaning to the range of values. Tracks with a gradient can also have a fill. A gradient track should not be used for choosing a precise color; use a color slider, color area, or color wheel instead."
     },
     {
-      "token": "field-default-width-extra-large",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "In situations where users should be able to precisely input a value, the value can be editable within a text field."
     },
     {
-      "token": "component-size-difference-down",
-      "context": "Component size (down)"
+      "type": "guideline",
+      "content": "A disabled slider shows that an input exists but is not available in the current context. This helps maintain layout continuity and signals that the slider may become available later."
     },
     {
-      "token": "component-size-width-ratio-down",
-      "context": "Component size (down)"
+      "type": "guideline",
+      "content": "A slider can be navigated using a keyboard. The keyboard focus state takes the slider’s visual hover state and adds a blue ring to the slider handle in focus."
     },
     {
-      "token": "component-size-minimum-perspective-down",
-      "context": "Component size (down)"
+      "type": "guideline",
+      "content": "A slider representing multiple non-identical values appears as indeterminate, with an en dash (–) in place of the value. The handle position corresponds to the first selected value."
     },
     {
-      "token": "slider-track-height-medium",
-      "context": "Track (height)"
+      "type": "guideline",
+      "content": "When the label is too long for the available horizontal space, it wraps to form another line."
     },
     {
-      "token": "slider-track-height-large",
-      "context": "Track (height)"
+      "type": "guideline",
+      "content": "After a slider has been adjusted, it can be reset to the default value by double-clicking the handle."
     },
     {
-      "token": "component-height-75",
-      "context": "Height (slider control) "
+      "type": "guideline",
+      "content": "Every slider should have a label. A slider without a label is ambiguous and not accessible. Write the label in sentence case."
     },
     {
-      "token": "component-height-100",
-      "context": "Height (slider control) "
+      "type": "guideline",
+      "content": "In addition to dragging the handle, sliders can offer other ways to change the value, known as “hot text.” Users can click the value text and drag up or down, or scroll up or down while hovering over the value text."
     },
     {
-      "token": "component-height-200",
-      "context": "Height (slider control) "
+      "type": "guideline",
+      "content": "Slider values can include a unit when it adds context, such as “%” or “px.” When the value is shown within a text field, the unit disappears on focus."
     },
     {
-      "token": "component-height-300",
-      "context": "Height (slider control) "
+      "type": "guideline",
+      "content": "If the value ranges from negative to positive, prefix the value with a plus (+) or minus (-) sign. When the sign is shown within a text field, it remains visible on focus. When the sign is shown outside the text field, there should be a space between the sign and the numerical value for readability."
+    }
+  ],
+  "options": {
+    "label": { "type": "string" },
+    "labelPosition": {
+      "type": "string",
+      "default": "top",
+      "values": [{ "value": "top" }, { "value": "side" }]
+    },
+    "value": { "type": "number", "description": "from minValue to maxValue" },
+    "minValue": { "type": "number", "default": 0 },
+    "maxValue": { "type": "number", "default": 100 },
+    "isRange": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, the slider will allow selection of a range of values by displaying two handles."
     },
+    "step": { "type": "number", "default": 1 },
+    "valueFormat": {
+      "type": "string",
+      "description": "This will vary depending on implementation."
+    },
+    "progressionScale": {
+      "type": "string",
+      "default": "linear",
+      "values": [{ "value": "linear" }, { "value": "log" }]
+    },
+    "width": { "type": "number" },
+    "hasFill": { "type": "boolean", "default": false },
+    "fillStart": { "type": "number", "default": 0 },
+    "hasGradient": { "type": "boolean", "default": false },
+    "isEditable": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false }
+  },
+  "states": [
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "down", "trigger": "interaction" },
+    { "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": "slider-handle-small",
-      "context": "Handle (size)"
+      "token": "field-default-width-extra-large",
+      "context": "Width (default)"
     },
     {
-      "token": "slider-handle-medium",
-      "context": "Handle (size)"
+      "token": "component-size-difference-down",
+      "context": "Component size (down)"
     },
     {
-      "token": "slider-handle-large",
-      "context": "Handle (size)"
+      "token": "component-size-width-ratio-down",
+      "context": "Component size (down)"
     },
     {
-      "token": "slider-handle-extra-large",
-      "context": "Handle (size)"
+      "token": "component-size-minimum-perspective-down",
+      "context": "Component size (down)"
     },
+    { "token": "slider-track-height-medium", "context": "Track (height)" },
+    { "token": "slider-track-height-large", "context": "Track (height)" },
+    { "token": "component-height-75", "context": "Height (slider control) " },
+    { "token": "component-height-100", "context": "Height (slider control) " },
+    { "token": "component-height-200", "context": "Height (slider control) " },
+    { "token": "component-height-300", "context": "Height (slider control) " },
+    { "token": "slider-handle-small", "context": "Handle (size)" },
+    { "token": "slider-handle-medium", "context": "Handle (size)" },
+    { "token": "slider-handle-large", "context": "Handle (size)" },
+    { "token": "slider-handle-extra-large", "context": "Handle (size)" },
     {
       "token": "slider-precision-handle-height-small",
       "context": "Handle (size)"
@@ -188,22 +187,10 @@
       "token": "slider-precision-handle-height-extra-large",
       "context": "Handle (size)"
     },
-    {
-      "token": "slider-precision-handle-width",
-      "context": "Handle (size)"
-    },
-    {
-      "token": "border-width-200",
-      "context": "Handle (border)"
-    },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus ring"
-    },
-    {
-      "token": "focus-indicator-gap",
-      "context": "Focus ring"
-    },
+    { "token": "slider-precision-handle-width", "context": "Handle (size)" },
+    { "token": "border-width-200", "context": "Handle (border)" },
+    { "token": "focus-indicator-thickness", "context": "Focus ring" },
+    { "token": "focus-indicator-gap", "context": "Focus ring" },
     {
       "token": "component-top-to-text-75",
       "context": "Spacing (top/bottom edge to label)"
@@ -300,86 +287,26 @@
       "token": "slider-control-to-text-field-extra-large",
       "context": "Spacing (slider to field)"
     },
-    {
-      "token": "neutral-subdued-content-color-default",
-      "context": "Value"
-    },
-    {
-      "token": "alias-track-default",
-      "context": "Track"
-    },
-    {
-      "token": "gray-700",
-      "context": "Track"
-    },
-    {
-      "token": "accent-content-color-default",
-      "context": "Track"
-    },
-    {
-      "token": "gray-800",
-      "context": "Handle"
-    },
-    {
-      "token": "gray-900",
-      "context": "Handle"
-    },
-    {
-      "token": "gray-25",
-      "context": "Handle"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    },
-    {
-      "token": "disabled-content-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "disabled-background-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "disabled-border-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "default-font-family",
-      "context": "Label"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Label"
-    },
-    {
-      "token": "default-font-style",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-75",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-100",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-200",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-300",
-      "context": "Label"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Label"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Label"
-    }
+    { "token": "neutral-subdued-content-color-default", "context": "Value" },
+    { "token": "alias-track-default", "context": "Track" },
+    { "token": "gray-700", "context": "Track" },
+    { "token": "accent-content-color-default", "context": "Track" },
+    { "token": "gray-800", "context": "Handle" },
+    { "token": "gray-900", "context": "Handle" },
+    { "token": "gray-25", "context": "Handle" },
+    { "token": "focus-indicator-color", "context": "Focus ring" },
+    { "token": "disabled-content-color", "context": "Disabled" },
+    { "token": "disabled-background-color", "context": "Disabled" },
+    { "token": "disabled-border-color", "context": "Disabled" },
+    { "token": "default-font-family", "context": "Label" },
+    { "token": "regular-font-weight", "context": "Label" },
+    { "token": "default-font-style", "context": "Label" },
+    { "token": "font-size-75", "context": "Label" },
+    { "token": "font-size-100", "context": "Label" },
+    { "token": "font-size-200", "context": "Label" },
+    { "token": "font-size-300", "context": "Label" },
+    { "token": "line-height-100", "context": "Label" },
+    { "token": "cjk-line-height-100", "context": "Label" }
   ],
   "accessibility": {
     "role": "slider",
@@ -387,21 +314,9 @@
     "focusable": true,
     "keyboardIntents": ["increment", "decrement"],
     "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" }
     ]
   }
 }