@adobe/spectrum-design-data 0.4.0 → 0.7.0

package/components/tooltip.json

@@ -9,23 +9,93 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/tooltip/"
   },
-  "options": {
-    "label": {
-      "type": "string"
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Tooltips show contextual help or information about specific components when a user hovers or focuses on them."
+    },
+    {
+      "type": "guideline",
+      "content": "Tooltips display contextual information related to a specific component. They appear on hover or focus to clarify purpose or behavior."
+    },
+    {
+      "type": "guideline",
+      "content": "All tooltips have a label. The label communicates the contextual help or information about specific components when a user hovers over or focuses on them."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, tooltips are the neutral variant. These are the most common variant because most tooltips are used to only disclose additional information, without conveying a semantic meaning. The neutral variant never includes an icon."
+    },
+    {
+      "type": "guideline",
+      "content": "Tooltips also come in semantic variants: informative (blue), and negative (red). An icon is required for these variants to ensure information isn’t conveyed by color alone."
+    },
+    {
+      "type": "guideline",
+      "content": "2 of the 3 tooltip variants (informative and negative) can include an icon to supplement the messaging. These icons are predefined and can not be customized. Unless it's being used to provide context about the exact same icon, a semantic tooltip should always show an icon. Doing this is essential for helping users with color vision deficiency to discern the message tone."
+    },
+    {
+      "type": "guideline",
+      "content": "A tooltip is positioned in relation to its target."
+    },
+    {
+      "type": "guideline",
+      "content": "This option determines whether or not a tooltip should be able to switch sides when constrained by space. A tooltip placed at the top would flip to be placed at the bottom (and vice versa), and a tooltip placed at the left would flip to be placed at the right (and vice versa)."
+    },
+    {
+      "type": "guideline",
+      "content": "The offset is the distance between the end of the tip and the target."
+    },
+    {
+      "type": "guideline",
+      "content": "To make sure that the tooltip will stay within certain boundaries (e.g., a browser window) it’s possible to define a container and a container padding value to respect."
+    },
+    {
+      "type": "guideline",
+      "content": "When the label is too long for the available horizontal space, it wraps to form another line."
+    },
+    {
+      "type": "guideline",
+      "content": "A tooltip fades in and out when showing and hiding, and slides a short distance from the source to indicate its origin. The direction of the slide (left, right, top, bottom) depends on the placement of the tooltip. The animation attributes (duration, easing, offset) are the same whether it’s showing or hiding."
     },
+    {
+      "type": "guideline",
+      "content": "Tooltips attached to help icons appear immediately. For conventional UI elements where a tooltip appearing immediately would be intrusive, delay appearance with a warmup period."
+    },
+    {
+      "type": "guideline",
+      "content": "The warmup period is a global timer that requires the cursor to remain on a UI element for the allotted time before a tooltip appears. Once this period is complete, a tooltip appears instantly on any hovered-upon UI element until the cursor is in an area that does not trigger a tooltip for the duration of the cooldown period."
+    },
+    {
+      "type": "guideline",
+      "content": "Icons are not always easy to identify on their own. When you use components that don’t have labels — for example, icon-only action buttons and tabs — make sure to use tooltips to provide context for the icons."
+    },
+    {
+      "type": "guideline",
+      "content": "For example, in a scenario where a user is entering their password into a field, the crucial information would be to state the password requirements. Supplementary context would be a message about how to get help if they have forgotten their password."
+    },
+    {
+      "type": "guideline",
+      "content": "Tooltips should be as concise and clear as possible. Keep the text to 1 or 2 short sentences. If the information you need to communicate is longer than that, look into using a different design."
+    },
+    {
+      "type": "guideline",
+      "content": "If a tooltip is written in a full sentence (or is 2 or more sentences), include a period at the end. If it's a short phrase or is only the name of a tool, action, or icon, don't add a period to the end."
+    },
+    {
+      "type": "guideline",
+      "content": "Tooltips appear only on hover or when in keyboard focus. They should not contain actions or links."
+    }
+  ],
+  "options": {
+    "label": { "type": "string" },
     "variant": {
       "type": "string",
       "default": "neutral",
       "values": [
-        {
-          "value": "neutral"
-        },
-        {
-          "value": "informative"
-        },
-        {
-          "value": "negative"
-        }
+        { "value": "neutral" },
+        { "value": "informative" },
+        { "value": "negative" }
       ]
     },
     "hasIcon": {
@@ -42,24 +112,13 @@
       "type": "string",
       "default": "top",
       "values": [
-        {
-          "value": "top"
-        },
-        {
-          "value": "bottom"
-        },
-        {
-          "value": "left"
-        },
-        {
-          "value": "right"
-        }
+        { "value": "top" },
+        { "value": "bottom" },
+        { "value": "left" },
+        { "value": "right" }
       ]
     },
-    "shouldFlip": {
-      "type": "boolean",
-      "default": false
-    },
+    "shouldFlip": { "type": "boolean", "default": false },
     "offset": {
       "type": "number",
       "default": 4,
@@ -71,34 +130,14 @@
       "description": "units: pixels"
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "component-height-75",
-      "context": "Minimum height"
-    },
-    {
-      "token": "tooltip-maximum-width",
-      "context": "Maximum width"
-    },
-    {
-      "token": "corner-radius-500",
-      "context": "Rounding"
-    },
-    {
-      "token": "tooltip-tip-width",
-      "context": "Tip"
-    },
-    {
-      "token": "tooltip-tip-height",
-      "context": "Tip"
-    },
-    {
-      "token": "tooltip-tip-corner-radius",
-      "context": "Rounding (tip)"
-    },
+    { "token": "component-height-75", "context": "Minimum height" },
+    { "token": "tooltip-maximum-width", "context": "Maximum width" },
+    { "token": "corner-radius-500", "context": "Rounding" },
+    { "token": "tooltip-tip-width", "context": "Tip" },
+    { "token": "tooltip-tip-height", "context": "Tip" },
+    { "token": "tooltip-tip-corner-radius", "context": "Rounding (tip)" },
     {
       "token": "component-edge-to-text-75",
       "context": "Spacing (start/end edges)"
@@ -111,42 +150,15 @@
       "token": "component-bottom-to-text-75",
       "context": "Spacing (top/bottom edge to text)"
     },
-    {
-      "token": "spacing-75",
-      "context": "Spacing (tip to source)"
-    },
-    {
-      "token": "spacing-100",
-      "context": "Container padding"
-    },
-    {
-      "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": "line-height-100",
-      "context": "Label"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Label"
-    },
-    {
-      "token": "gray-25",
-      "context": "Text"
-    },
+    { "token": "spacing-75", "context": "Spacing (tip to source)" },
+    { "token": "spacing-100", "context": "Container padding" },
+    { "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": "line-height-100", "context": "Label" },
+    { "token": "cjk-line-height-100", "context": "Label" },
+    { "token": "gray-25", "context": "Text" },
     {
       "token": "neutral-background-color-default",
       "context": "Background (Neutral)"
@@ -169,11 +181,7 @@
         "level": "AA",
         "title": "Content on Hover or Focus"
       },
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }

package/components/tree-view.json

@@ -9,108 +9,173 @@
     "category": "navigation",
     "documentationUrl": "https://spectrum.adobe.com/page/tree-view/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "A tree view provides users with a way to navigate nested hierarchical information."
+    },
+    {
+      "type": "guideline",
+      "content": "Tree views display nested, hierarchical content in a collapsible structure. They allow for navigation through multiple levels of grouped information."
+    },
+    {
+      "type": "guideline",
+      "content": "A tree view offers four sizes: small, medium, large and extra-large. Medium is the default and most common. Use other sizes sparingly to create a visual hierarchy of importance on the page."
+    },
+    {
+      "type": "guideline",
+      "content": "When placed outside a panel, a tree view uses the detached style with rounded corners. Inside a panel, it spans edge to edge by default and does not include rounded corners."
+    },
+    {
+      "type": "guideline",
+      "content": "Tree view items can include a drag icon when needed. The icon serves as a keyboard-navigable indicator for items that support multiple actions. It appears only on hover, active and keyboard focus states."
+    },
+    {
+      "type": "guideline",
+      "content": "The type of selection allowed in a collection can be none, single or multiple."
+    },
+    {
+      "type": "guideline",
+      "content": "Checkbox With checkboxes, both single-select and multi-select views display boxes on the left of each item. Clicking another item adds it to the selection, and clicking a selected item removes it."
+    },
+    {
+      "type": "guideline",
+      "content": "Highlight Use highlight selection when checkboxes add clutter or unnecessary controls. This style shows a highlighted state for selected items, and clicking a new item replaces the previous selection by default."
+    },
+    {
+      "type": "guideline",
+      "content": "All tree views have a hover state, regardless of whether actions or selections can be made."
+    },
+    {
+      "type": "guideline",
+      "content": "Tree views support both single-select and multi-select modes, using either checkbox or highlight styles. In multi-select mode, selecting an item toggles its selection on or off. In single-select mode, selecting an item replaces the current selection."
+    },
+    {
+      "type": "guideline",
+      "content": "Clicking the collapse and expand button will expand or collapse a tree view item that contains child tree view items."
+    },
+    {
+      "type": "guideline",
+      "content": "Tree view items can be dragged and dropped to reorder or restructure the hierarchy, including multiple items at once. Dropping items from different hierarchies into a new location flattens them as sibling children. Tree views should also accept external drops, such as files, to create new items."
+    },
+    {
+      "type": "guideline",
+      "content": "When a tree view item label is too long for the available horizontal space, it truncates. The full label appears in a tooltip on hover or keyboard focus."
+    },
+    {
+      "type": "guideline",
+      "content": "For proper functionality, a parent-level tree view must include a collapse-and-expand button that uses a chevron icon - regardless of its nesting level. This makes the expected behavior clear when users click an item icon."
+    },
+    {
+      "type": "guideline",
+      "content": "When displaying hierarchical information from different sources, use a single tree view with separate sections and headings. Do not cross-reference sources to avoid confusing users. Single and multi-selection should work as expected within one tree view component."
+    },
+    {
+      "type": "guideline",
+      "content": "The root (topmost) level of the hierarchy does not always need to be shown or displayed as a tree view item. If the root provides no useful context, hide it or replace it with a section header. In cases such as mixed tree views, the root can serve as a “Back” button."
+    },
+    {
+      "type": "guideline",
+      "content": "In some cases, users may need to view different hierarchies depending on context. To support this, let users drill into a tree view item to display a different variation of the tree view within the same panel. Use a navigation controller with a “Back” button to let users return to the previous view."
+    },
+    {
+      "type": "guideline",
+      "content": "Choose icons that match the object type represented in the tree view. Icons can be unique to specific data types to help clarify meaning for users."
+    },
+    {
+      "type": "guideline",
+      "content": "Tree view items can display thumbnails instead of icons when users need a content preview. Use icons as a fallback when an image is unavailable, and size them to match the thumbnail. Thumbnails should scale appropriately to the tree view size. For example, an extra-large tree view should not use small thumbnails; in that case, icons may work better."
+    },
+    {
+      "type": "guideline",
+      "content": "One way to manage overflow is to limit how many levels of hierarchy users can create in a tree view. Some products use this approach to reduce the complexity of deeply nested hierarchies. Setting limits helps when a complex hierarchy is unnecessary for the experience."
+    },
+    {
+      "type": "guideline",
+      "content": "When a label is too long to fit in the tree view, it truncates with an ellipsis. Hovering over or focusing on the item reveals a tooltip with the full label text."
+    },
+    {
+      "type": "guideline",
+      "content": "When a tree view hierarchy may extend beyond the available layout space, use an adjustable layout mechanism such as panels or rails. This lets users modify the layout while preserving visibility of the tree view."
+    },
+    {
+      "type": "guideline",
+      "content": "If you have a layout that doesn't allow for users to adjust the width of the container for a tree view, allow them to horizontally scroll in order to see the full depth of the hierarchy."
+    },
+    {
+      "type": "guideline",
+      "content": "When tree views are very large, use a progress circle or a “Show more” control to reveal additional parts when contextually relevant. These loading patterns can apply to the entire tree view or to nested items."
+    },
+    {
+      "type": "guideline",
+      "content": "If system processes are delaying the display of child tree view items when a parent tree view item is expanded, show a clear indication that the items are in the process of loading."
+    },
+    {
+      "type": "guideline",
+      "content": "Users should be able to sort a tree view. Sorting should not affect the hierarchical structure since each layer of the hierarchy is sorted individually."
+    },
+    {
+      "type": "guideline",
+      "content": "Users may need to modify a tree view directly. They should be able to create new parent or child items, such as groups or folders, and flatten the hierarchy at the item level, such as ungrouping layers. In some cases, users should be able to edit item labels directly."
+    },
+    {
+      "type": "guideline",
+      "content": "Any action for modifying the hierarchy should be offered as an explicit control and, if needed, as a keyboard shortcut — but never as a shortcut alone."
+    },
+    {
+      "type": "guideline",
+      "content": "Allow users to enter multiple-selection mode explicitly when keyboard shortcuts such as Shift + click are unavailable or when you need to show a different selection type. Do this by toggling the selection style from highlight to checkbox."
+    },
+    {
+      "type": "guideline",
+      "content": "The checkbox selection style is intended for performing bulk actions on tree view items. Use this option when selection corresponds to bulk actions."
+    },
+    {
+      "type": "guideline",
+      "content": "When you need to provide selection controls within a hierarchy, use a checkbox component instead of the tree view item’s label. This should not correspond to selecting specific content and works best for cases like categorized filtering."
+    }
+  ],
   "options": {
     "size": {
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
-    "isDetached": {
-      "type": "boolean",
-      "default": false
-    },
-    "isEmphasized": {
-      "type": "boolean",
-      "default": false
-    },
-    "showDragIcon": {
-      "type": "boolean",
-      "default": false
-    },
+    "isDetached": { "type": "boolean", "default": false },
+    "isEmphasized": { "type": "boolean", "default": false },
+    "showDragIcon": { "type": "boolean", "default": false },
     "selectionMode": {
       "type": "string",
       "default": "multiple",
-      "values": [
-        {
-          "value": "single"
-        },
-        {
-          "value": "multiple"
-        }
-      ]
+      "values": [{ "value": "single" }, { "value": "multiple" }]
     },
     "selectionStyle": {
       "type": "string",
       "default": "checkbox",
-      "values": [
-        {
-          "value": "checkbox"
-        },
-        {
-          "value": "highlight"
-        }
-      ]
+      "values": [{ "value": "checkbox" }, { "value": "highlight" }]
     },
     "selectionBehavior": {
       "type": "string",
       "default": "toggle",
-      "values": [
-        {
-          "value": "toggle"
-        },
-        {
-          "value": "replace"
-        }
-      ]
+      "values": [{ "value": "toggle" }, { "value": "replace" }]
     }
   },
   "states": [
-    {
-      "name": "hover",
-      "trigger": "interaction"
-    },
-    {
-      "name": "down",
-      "trigger": "interaction"
-    },
-    {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "down", "trigger": "interaction" },
+    { "name": "keyboard-focus", "trigger": "interaction" }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "workflow-icon-size-100",
-      "context": "Icon"
-    },
-    {
-      "token": "tree-view-minimum-height",
-      "context": "Height (minimum)"
-    },
-    {
-      "token": "tree-view-minimum-width",
-      "context": "Width (minimum)"
-    },
-    {
-      "token": "corner-radius-medium-default",
-      "context": "Rounding"
-    },
+    { "token": "workflow-icon-size-100", "context": "Icon" },
+    { "token": "tree-view-minimum-height", "context": "Height (minimum)" },
+    { "token": "tree-view-minimum-width", "context": "Width (minimum)" },
+    { "token": "corner-radius-medium-default", "context": "Rounding" },
     {
       "token": "tree-view-disclosure-indicator-height",
       "context": "Spacing (disclosure indicator)"
@@ -151,10 +216,7 @@
       "token": "tree-view-level-increment",
       "context": "Spacing (indentation)"
     },
-    {
-      "token": "vertical-align-items",
-      "context": "Spacing (vertical)"
-    },
+    { "token": "vertical-align-items", "context": "Spacing (vertical)" },
     {
       "token": "stack-item-minimum-padding-vertical",
       "context": "Spacing (vertical)"
@@ -163,18 +225,9 @@
       "token": "border-width-100",
       "context": "Border width (selected, highlight)"
     },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus "
-    },
-    {
-      "token": "focus-indicator-gap",
-      "context": "Focus (drag handle)"
-    },
-    {
-      "token": "component-height-200",
-      "context": "Height"
-    },
+    { "token": "focus-indicator-thickness", "context": "Focus " },
+    { "token": "focus-indicator-gap", "context": "Focus (drag handle)" },
+    { "token": "component-height-200", "context": "Height" },
     {
       "token": "stack-item-minimum-vertical-padding",
       "context": "Spacing (vertical)"
@@ -287,78 +340,24 @@
       "token": "disabled-content-color",
       "context": "Label and icon (disabled)"
     },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus indicator"
-    },
-    {
-      "token": "title-content-color",
-      "context": "Label and icon"
-    },
-    {
-      "token": "default-font-family",
-      "context": "Text (tree view item)"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Text (tree view item)"
-    },
-    {
-      "token": "default-font-style",
-      "context": "Text (tree view item)"
-    },
-    {
-      "token": "font-size-100",
-      "context": "Text (tree view item)"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Text (tree view item)"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Text (tree view item)"
-    },
-    {
-      "token": "bold-font-weight",
-      "context": "Text (tree view title)"
-    },
-    {
-      "token": "thumbnail-size-75",
-      "context": "Size"
-    },
-    {
-      "token": "thumbnail-size-300",
-      "context": "Size"
-    },
-    {
-      "token": "thumbnail-size-1000",
-      "context": "Size"
-    },
-    {
-      "token": "thumbnail-corner-radius",
-      "context": "Rounding (default)"
-    },
-    {
-      "token": "spacing-75",
-      "context": "Opacity checkerboard (layer)"
-    },
-    {
-      "token": "corner-radius-0",
-      "context": "Rounding (layer)"
-    },
-    {
-      "token": "thumbnail-border-color",
-      "context": "Border (default)"
-    },
-    {
-      "token": "thumbnail-border-opacity",
-      "context": "Border (default)"
-    },
-    {
-      "token": "gray-500",
-      "context": "Border (layer)"
-    },
+    { "token": "focus-indicator-color", "context": "Focus indicator" },
+    { "token": "title-content-color", "context": "Label and icon" },
+    { "token": "default-font-family", "context": "Text (tree view item)" },
+    { "token": "regular-font-weight", "context": "Text (tree view item)" },
+    { "token": "default-font-style", "context": "Text (tree view item)" },
+    { "token": "font-size-100", "context": "Text (tree view item)" },
+    { "token": "line-height-100", "context": "Text (tree view item)" },
+    { "token": "cjk-line-height-100", "context": "Text (tree view item)" },
+    { "token": "bold-font-weight", "context": "Text (tree view title)" },
+    { "token": "thumbnail-size-75", "context": "Size" },
+    { "token": "thumbnail-size-300", "context": "Size" },
+    { "token": "thumbnail-size-1000", "context": "Size" },
+    { "token": "thumbnail-corner-radius", "context": "Rounding (default)" },
+    { "token": "spacing-75", "context": "Opacity checkerboard (layer)" },
+    { "token": "corner-radius-0", "context": "Rounding (layer)" },
+    { "token": "thumbnail-border-color", "context": "Border (default)" },
+    { "token": "thumbnail-border-opacity", "context": "Border (default)" },
+    { "token": "gray-500", "context": "Border (layer)" },
     {
       "token": "opacity-checkerboard-square-light",
       "context": "Checkerboard colors "
@@ -367,10 +366,7 @@
       "token": "opacity-checkerboard-square-dark",
       "context": "Checkerboard colors "
     },
-    {
-      "token": "thumbnail-opacity-disabled",
-      "context": "Disabled"
-    }
+    { "token": "thumbnail-opacity-disabled", "context": "Disabled" }
   ],
   "accessibility": {
     "role": "tree",
@@ -378,16 +374,8 @@
     "focusable": true,
     "keyboardIntents": ["navigate-items", "expand", "collapse", "activate"],
     "wcag": [
-      {
-        "criterion": "2.1.1",
-        "level": "A",
-        "title": "Keyboard"
-      },
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }