@warp-ds/elements 2.11.0 → 2.12.0-next.1

package/dist/custom-elements.json

@@ -252,6 +252,16 @@
               "attribute": "autocomplete",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "tooltip",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Suplementary information that should show in a tooltip behind an information icon after the label.\n\nUse the `tooltip` slot if you need markup and not just text.\n\nYou must provide a label to be able to show an info icon with a tooltip.",
+              "attribute": "tooltip",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "formatter",
@@ -512,6 +522,14 @@
               },
               "description": "A space-separated string that hints to browsers [what type of content it can suggest](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete#value) to autofill.",
               "fieldName": "autocomplete"
+            },
+            {
+              "name": "tooltip",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Suplementary information that should show in a tooltip behind an information icon after the label.\n\nUse the `tooltip` slot if you need markup and not just text.\n\nYou must provide a label to be able to show an info icon with a tooltip.",
+              "fieldName": "tooltip"
             }
           ],
           "mixins": [
@@ -9310,6 +9328,311 @@
           }
         }
       ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "packages/tooltip/tooltip.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A tooltip is a message box that is displayed when a user hovers over or gives focus to a UI element.\n\nTooltips should be used sparingly and contain succinct, supplementary information.",
+          "name": "WarpTooltip",
+          "members": [
+            {
+              "kind": "field",
+              "name": "for",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "ID of the element that triggers the tooltip on hover or focus.",
+              "attribute": "for"
+            },
+            {
+              "kind": "field",
+              "name": "noArrow",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Hide the arrow pointing toward the tooltip target.",
+              "attribute": "no-arrow"
+            },
+            {
+              "kind": "field",
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Indicates whether the tooltip is visible or not.",
+              "attribute": "open"
+            },
+            {
+              "kind": "field",
+              "name": "placement",
+              "type": {
+                "text": "TooltipPlacement"
+              },
+              "default": "\"top\"",
+              "description": "Sets the placement of the tooltip relative to its target.\n\nThe tooltip will try to position itself at the given placement. If there is no room it will flip to the opposite side automatically.",
+              "attribute": "placement",
+              "parsedType": {
+                "text": "'top' | 'right' | 'bottom' | 'left'"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "#actualPlacement",
+              "privacy": "private",
+              "type": {
+                "text": "Placement"
+              },
+              "default": "\"top\""
+            },
+            {
+              "kind": "field",
+              "name": "showDelay",
+              "type": {
+                "text": "number"
+              },
+              "default": "150",
+              "description": "Milliseconds to wait before showing the tooltip on hover.\n\nKeep at a non-zero value to avoid flickering the tooltip on and off when cursors move quickly past the target element.\n\nFocusing the target element shows the tooltip immediately.",
+              "attribute": "show-delay",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "hideDelay",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "Milliseconds to wait before hiding the tooltip on mouseout.",
+              "attribute": "hide-delay",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "target",
+              "type": {
+                "text": "Element | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "tooltip",
+              "type": {
+                "text": "HTMLDivElement"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "hoverBridge",
+              "type": {
+                "text": "HTMLDivElement"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "arrow",
+              "type": {
+                "text": "HTMLDivElement"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "beak",
+              "type": {
+                "text": "HTMLDivElement"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "#accessibleDescription",
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "#cleanup",
+              "privacy": "private",
+              "type": {
+                "text": "ReturnType<typeof autoUpdate> | null"
+              },
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "#hoverTimeout",
+              "privacy": "private",
+              "type": {
+                "text": "number | undefined"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "handleBlur",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "handleFocus",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "handleMouseOver",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "handleKeydown",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "handleMouseOut",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "#handleForChange",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "hide",
+              "type": {
+                "text": "hide() => void"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "show",
+              "type": {
+                "text": "show() => void"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "#handleOpenChange",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "#startPositioning",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "#stopPositioning",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "#updatePosition",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "#updateHoverBridge",
+              "privacy": "private"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "for",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "ID of the element that triggers the tooltip on hover or focus.",
+              "fieldName": "for"
+            },
+            {
+              "name": "no-arrow",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Hide the arrow pointing toward the tooltip target.",
+              "fieldName": "noArrow"
+            },
+            {
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Indicates whether the tooltip is visible or not.",
+              "fieldName": "open"
+            },
+            {
+              "name": "placement",
+              "type": {
+                "text": "TooltipPlacement"
+              },
+              "default": "\"top\"",
+              "description": "Sets the placement of the tooltip relative to its target.\n\nThe tooltip will try to position itself at the given placement. If there is no room it will flip to the opposite side automatically.",
+              "fieldName": "placement",
+              "parsedType": {
+                "text": "'top' | 'right' | 'bottom' | 'left'"
+              }
+            },
+            {
+              "name": "show-delay",
+              "type": {
+                "text": "number"
+              },
+              "default": "150",
+              "description": "Milliseconds to wait before showing the tooltip on hover.\n\nKeep at a non-zero value to avoid flickering the tooltip on and off when cursors move quickly past the target element.\n\nFocusing the target element shows the tooltip immediately.",
+              "fieldName": "showDelay"
+            },
+            {
+              "name": "hide-delay",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "Milliseconds to wait before hiding the tooltip on mouseout.",
+              "fieldName": "hideDelay"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "w-tooltip",
+          "customElement": true,
+          "modulePath": "packages/tooltip/tooltip.ts",
+          "definitionPath": "packages/tooltip/tooltip.ts"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "WarpTooltip",
+          "declaration": {
+            "name": "WarpTooltip",
+            "module": "packages/tooltip/tooltip.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "w-tooltip",
+          "declaration": {
+            "name": "WarpTooltip",
+            "module": "packages/tooltip/tooltip.ts"
+          }
+        }
+      ]
     }
   ]
 }

package/dist/docs/index.md

@@ -47,3 +47,4 @@ Generated by `pnpm build:docs`. This file indexes the Markdown documentation shi
 | Textarea | `<w-textarea>` | `textarea` | A multi-line text input with built-in form validation, auto-resizing, and styling support. Warp component reference | [textarea.md](./textarea/textarea.md) |
 | Textfield | `<w-textfield>` | `textfield` | A single-line input component used for entering and editing textual or numeric data. Warp component reference | [textfield.md](./textfield/textfield.md) |
 | Toast | `@warp-ds/elements/toast` | `toast` | Toasts are brief user feedback messages that overlay content. | [toast.md](./toast/toast.md) |
+| Tooltip | `<w-tooltip>` | `tooltip` | A tooltip is a message box that is displayed when a user hovers over or gives focus to a UI element. Tooltips should be used sparingly and contain succinct, supplementary information. | [tooltip.md](./tooltip/tooltip.md) |

package/dist/docs/textfield/api.md

@@ -31,6 +31,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | size | `string \| undefined` | `-` | Sets the [size](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#size) (width) of the input field to fit the expected length of inputs. |
 | step | `number \| undefined` | `-` | Forces `number` inputs to be a whole number of `step` |
 | suffixSlotChange (JS only) | `suffixSlotChange() => void` | `-` | - |
+| tooltip | `string \| undefined` | `-` | Suplementary information that should show in a tooltip behind an information icon after the label. |
 | type | `string \| undefined` | `-` | The [type of input](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types). |
 | value | `string \| undefined` | `-` | Lets you set the current value. |
 
@@ -230,6 +231,17 @@ Using arrow up and down in the input field increments and decrements by 5.
 - Type: `suffixSlotChange() => void`
 - Default: `-`
 
+#### tooltip
+
+Suplementary information that should show in a tooltip behind an information icon after the label.
+
+Use the `tooltip` slot if you need markup and not just text.
+
+You must provide a label to be able to show an info icon with a tooltip.
+
+- Type: `string | undefined`
+- Default: `-`
+
 #### type
 
 The [type of input](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types).

package/dist/docs/textfield/textfield.md

@@ -313,6 +313,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | size | `string \| undefined` | `-` | Sets the [size](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#size) (width) of the input field to fit the expected length of inputs. |
 | step | `number \| undefined` | `-` | Forces `number` inputs to be a whole number of `step` |
 | suffixSlotChange (JS only) | `suffixSlotChange() => void` | `-` | - |
+| tooltip | `string \| undefined` | `-` | Suplementary information that should show in a tooltip behind an information icon after the label. |
 | type | `string \| undefined` | `-` | The [type of input](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types). |
 | value | `string \| undefined` | `-` | Lets you set the current value. |
 
@@ -512,6 +513,17 @@ Using arrow up and down in the input field increments and decrements by 5.
 - Type: `suffixSlotChange() => void`
 - Default: `-`
 
+#### tooltip
+
+Suplementary information that should show in a tooltip behind an information icon after the label.
+
+Use the `tooltip` slot if you need markup and not just text.
+
+You must provide a label to be able to show an info icon with a tooltip.
+
+- Type: `string | undefined`
+- Default: `-`
+
 #### type
 
 The [type of input](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types).

package/dist/docs/tooltip/accessibility.md

@@ -0,0 +1,9 @@
+## Accessibility
+
+### ARIA attribute
+
+We use `aria-labelledby` instead of `aria-describedby` to create the relationship between the tooltip and its target.
+
+The ARIA Authoring Practices Guide (APG) recommends `aria-describedby`, but at time of writing that must be set directly on the focusable element. Since `w-button`'s focusable `button` element is inside a shadow root we can't set up that relationship. Cross-root references by ID is impossible and the related ARIA properties on the `Element` are read only.
+
+We might revisit this design later should cross-root ARIA references become supported.

package/dist/docs/tooltip/api.md

@@ -0,0 +1,87 @@
+## `<w-tooltip>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| for | `string` | `""` | ID of the element that triggers the tooltip on hover or focus. |
+| hide (JS only) | `hide() => void` | `-` | - |
+| hide-delay | `number` | `0` | Milliseconds to wait before hiding the tooltip on mouseout. |
+| no-arrow | `boolean` | `false` | Hide the arrow pointing toward the tooltip target. |
+| open | `boolean` | `false` | Indicates whether the tooltip is visible or not. |
+| placement | [`TooltipPlacement`](#tooltipplacement) | `"top"` | Sets the placement of the tooltip relative to its target. |
+| show (JS only) | `show() => void` | `-` | - |
+| show-delay | `number` | `150` | Milliseconds to wait before showing the tooltip on hover. |
+
+### Property Details
+
+#### for
+
+ID of the element that triggers the tooltip on hover or focus.
+
+- Type: `string`
+- Default: `""`
+
+#### hide (JS only)
+
+
+
+- Type: `hide() => void`
+- Default: `-`
+
+#### hide-delay
+
+Milliseconds to wait before hiding the tooltip on mouseout.
+
+- Type: `number`
+- Default: `0`
+
+#### no-arrow
+
+Hide the arrow pointing toward the tooltip target.
+
+- Type: `boolean`
+- Default: `false`
+
+#### open
+
+Indicates whether the tooltip is visible or not.
+
+- Type: `boolean`
+- Default: `false`
+
+#### placement
+
+Sets the placement of the tooltip relative to its target.
+
+The tooltip will try to position itself at the given placement. If there is no room it will flip to the opposite side automatically.
+
+- Type: [`TooltipPlacement`](#tooltipplacement)
+- Default: `"top"`
+
+#### show (JS only)
+
+
+
+- Type: `show() => void`
+- Default: `-`
+
+#### show-delay
+
+Milliseconds to wait before showing the tooltip on hover.
+
+Keep at a non-zero value to avoid flickering the tooltip on and off when cursors move quickly past the target element.
+
+Focusing the target element shows the tooltip immediately.
+
+- Type: `number`
+- Default: `150`
+
+### Types
+
+#### TooltipPlacement
+
+`'top' | 'right' | 'bottom' | 'left'`
+

package/dist/docs/tooltip/examples.md

@@ -0,0 +1,32 @@
+## Examples
+
+By default the tooltip is placed above the target element if there is room. If there's no room above it flips side and is placed below the target.
+
+<elements-example>
+  
+```html
+<w-button id="basic-button" aria-labelledby="basic-tooltip">Hover over me</w-button>
+<w-tooltip id="basic-tooltip" for="basic-button">I am a tooltip</w-tooltip>
+```
+
+</elements-example>
+
+### Adjust placement
+
+You can specify a different initial placement. If there's no room the tooltip flips to the opposite side of the target.
+
+Available positions:
+
+- `top` (this is the default)
+- `bottom`
+- `left`
+- `right`
+
+<elements-example>
+  
+```html
+<w-button id="placed-button" aria-labelledby="placed-tooltip">Hover over me</w-button>
+<w-tooltip id="placed-tooltip" for="placed-button" placement="right">I am a tooltip</w-tooltip>
+```
+
+</elements-example>

package/dist/docs/tooltip/styling.md

@@ -0,0 +1,47 @@
+## Styling API
+
+This component supports styling through **component tokens** (CSS custom properties with a --w-c- prefix) and **parts**.
+
+### Parts
+
+Use `::part(...)` from outside the component.
+
+- `tooltip` - the tooltip container with background color, padding etc.
+- `arrow` - a square container used for positioning the visual part of the arrow
+- `beak` - the visual part of the arrow pointing at the target
+- `hover-bridge` - an invisible element there to ensure the tooltip doesn't close when moving the cursor from the target to the tooltip
+
+Example:
+
+```css
+w-tooltip::part(tooltip) {
+  text-transform: uppercase;
+}
+```
+
+### Component tokens
+
+Set these on `w-tooltip` to override visuals.
+
+```css
+w-tooltip {
+    --w-c-tooltip-bg: lime;
+    --w-c-tooltip-color: black;
+}
+```
+
+#### Layout & typography
+
+- `--w-c-tooltip-z-index`
+
+#### Background
+
+- `--w-c-tooltip-bg`
+
+#### Text color
+
+- `--w-c-tooltip-color`
+
+##### Shadow
+
+- `--w-c-tooltip-box-shadow`