@warp-ds/elements 2.9.0-next.6 → 2.9.1-next.1

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@warp-ds/elements",
-  "version": "2.9.0-next.5",
+  "version": "2.9.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -473,78 +473,143 @@
         },
         {
           "name": "w-attention",
-          "description": "\n---\n",
+          "description": "Attention is a versatile component for displaying contextual information and messages. It can be used for a wide range of purposes, such as tooltips, callouts, popovers, and highlights.\n\nThe component is designed to be anchored to a trigger element, providing contextual information related to that element. It supports various placements and styling options to accommodate different use cases and design needs.\n\nNote: attention will soon be split into multiple components (tooltip, callout, popover, highlight) at which time this component will be deprecated. For now, use the `tooltip`, `callout`, `popover`, and `highlight` boolean properties to achieve the desired style and behavior.\n---\n",
           "doc-url": "",
           "attributes": [
             {
               "name": "show",
+              "description": "Controls whether the attention panel is visible.\nSet to `true` to show the attention content and `false` to hide it.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "placement",
+              "description": "Preferred placement relative to the trigger element.\nSets the initial direction for positioning, for example `top`, `right`, `bottom`, or `left` variants.",
               "value": { "type": "Directions", "default": "'bottom'" }
             },
             {
               "name": "tooltip",
+              "description": "Renders the component with tooltip styling and behavior.\nUse for compact, non-modal contextual hints anchored to another element.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "callout",
+              "description": "Renders the component as an inline callout.\nCallout mode is used for always-in-flow informational content instead of floating overlay behavior.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "popover",
+              "description": "Enables native popover behavior for the attention element.\nWhen enabled, the component uses popover semantics and styling suitable for floating surface UI.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "highlight",
+              "description": "Renders the component with highlight styling.\nUse highlight mode to visually emphasize important contextual information.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "can-close",
+              "description": "Shows a close button inside the attention component.\nAdds an internal dismiss action that lets users close the attention panel.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "no-arrow",
+              "description": "Hides the directional arrow of the attention component.\nDisable the arrow when the visual connection to the trigger should not be shown.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "distance",
+              "description": "Distance offset between trigger and attention panel.\nDefines the main-axis spacing in pixels from the anchor element.",
               "value": { "type": "number", "default": "8" }
             },
             {
               "name": "skidding",
+              "description": "Cross-axis offset for fine-grained positioning.\nMoves the panel along the cross axis in pixels to adjust alignment with the trigger.",
               "value": { "type": "number", "default": "0" }
             },
             {
               "name": "flip",
+              "description": "Enables automatic flipping when placement has no space.\nAllows the component to choose an alternative side if the preferred placement would overflow.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "cross-axis",
+              "description": "Allows overflow checks on the cross axis when flipping.\nUse with `flip` to improve collision handling when space is constrained horizontally or vertically.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "fallback-placements",
-              "value": { "type": "Directions[]" }
+              "description": "Ordered list of fallback placements.\nProvides explicit alternative placements to try when `flip` is enabled and the preferred placement does not fit.",
+              "value": { "type": "Directions[]", "default": "[]" }
             }
           ],
           "events": [],
           "js": {
             "properties": [
-              { "name": "show", "type": "boolean" },
-              { "name": "placement", "type": "Directions" },
-              { "name": "tooltip", "type": "boolean" },
-              { "name": "callout", "type": "boolean" },
-              { "name": "popover", "type": "boolean" },
-              { "name": "highlight", "type": "boolean" },
-              { "name": "canClose", "type": "boolean" },
-              { "name": "noArrow", "type": "boolean" },
-              { "name": "distance", "type": "number" },
-              { "name": "skidding", "type": "number" },
-              { "name": "flip", "type": "boolean" },
-              { "name": "crossAxis", "type": "boolean" },
-              { "name": "fallbackPlacements", "type": "Directions[]" },
+              {
+                "name": "show",
+                "description": "Controls whether the attention panel is visible.\nSet to `true` to show the attention content and `false` to hide it.",
+                "type": "boolean"
+              },
+              {
+                "name": "placement",
+                "description": "Preferred placement relative to the trigger element.\nSets the initial direction for positioning, for example `top`, `right`, `bottom`, or `left` variants.",
+                "type": "Directions"
+              },
+              {
+                "name": "tooltip",
+                "description": "Renders the component with tooltip styling and behavior.\nUse for compact, non-modal contextual hints anchored to another element.",
+                "type": "boolean"
+              },
+              {
+                "name": "callout",
+                "description": "Renders the component as an inline callout.\nCallout mode is used for always-in-flow informational content instead of floating overlay behavior.",
+                "type": "boolean"
+              },
+              {
+                "name": "popover",
+                "description": "Enables native popover behavior for the attention element.\nWhen enabled, the component uses popover semantics and styling suitable for floating surface UI.",
+                "type": "boolean"
+              },
+              {
+                "name": "highlight",
+                "description": "Renders the component with highlight styling.\nUse highlight mode to visually emphasize important contextual information.",
+                "type": "boolean"
+              },
+              {
+                "name": "canClose",
+                "description": "Shows a close button inside the attention component.\nAdds an internal dismiss action that lets users close the attention panel.",
+                "type": "boolean"
+              },
+              {
+                "name": "noArrow",
+                "description": "Hides the directional arrow of the attention component.\nDisable the arrow when the visual connection to the trigger should not be shown.",
+                "type": "boolean"
+              },
+              {
+                "name": "distance",
+                "description": "Distance offset between trigger and attention panel.\nDefines the main-axis spacing in pixels from the anchor element.",
+                "type": "number"
+              },
+              {
+                "name": "skidding",
+                "description": "Cross-axis offset for fine-grained positioning.\nMoves the panel along the cross axis in pixels to adjust alignment with the trigger.",
+                "type": "number"
+              },
+              {
+                "name": "flip",
+                "description": "Enables automatic flipping when placement has no space.\nAllows the component to choose an alternative side if the preferred placement would overflow.",
+                "type": "boolean"
+              },
+              {
+                "name": "crossAxis",
+                "description": "Allows overflow checks on the cross axis when flipping.\nUse with `flip` to improve collision handling when space is constrained horizontally or vertically.",
+                "type": "boolean"
+              },
+              {
+                "name": "fallbackPlacements",
+                "description": "Ordered list of fallback placements.\nProvides explicit alternative placements to try when `flip` is enabled and the preferred placement does not fit.",
+                "type": "Directions[]"
+              },
               { "name": "_initialPlacement" },
               { "name": "_actualDirection" }
             ],
@@ -601,30 +666,58 @@
           "attributes": [
             {
               "name": "bleed",
+              "description": "Makes the box bleed to the container edge.\nExtends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "bordered",
+              "description": "Shows the box as a bordered surface.\nUse this when the content needs a clear visual boundary from the surrounding page.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "info",
+              "description": "Shows the box with information styling.\nUse this for supporting informational content that should be visually separated from the surrounding page.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "neutral",
+              "description": "Shows the box with neutral styling.\nUse this for quiet grouped content that needs a background without strong emphasis.",
               "value": { "type": "boolean", "default": "false" }
             },
-            { "name": "role", "value": { "type": "string" } }
+            {
+              "name": "role",
+              "description": "ARIA role for the box wrapper.\nDefaults to a role of `region`. Set `role=\"none\"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.",
+              "value": { "type": "string", "default": "'region'" }
+            }
           ],
           "events": [],
           "js": {
             "properties": [
-              { "name": "bleed", "type": "boolean" },
-              { "name": "bordered", "type": "boolean" },
-              { "name": "info", "type": "boolean" },
-              { "name": "neutral", "type": "boolean" },
-              { "name": "role", "type": "string" }
+              {
+                "name": "bleed",
+                "description": "Makes the box bleed to the container edge.\nExtends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.",
+                "type": "boolean"
+              },
+              {
+                "name": "bordered",
+                "description": "Shows the box as a bordered surface.\nUse this when the content needs a clear visual boundary from the surrounding page.",
+                "type": "boolean"
+              },
+              {
+                "name": "info",
+                "description": "Shows the box with information styling.\nUse this for supporting informational content that should be visually separated from the surrounding page.",
+                "type": "boolean"
+              },
+              {
+                "name": "neutral",
+                "description": "Shows the box with neutral styling.\nUse this for quiet grouped content that needs a background without strong emphasis.",
+                "type": "boolean"
+              },
+              {
+                "name": "role",
+                "description": "ARIA role for the box wrapper.\nDefaults to a role of `region`. Set `role=\"none\"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.",
+                "type": "string"
+              }
             ],
             "events": []
           }
@@ -1944,59 +2037,138 @@
         },
         {
           "name": "w-textarea",
-          "description": "A single line text input element.\n\n[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-textfield--docs)\n---\n\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Checks whether the textarea passes constraint validation\n- **reportValidity(): _boolean_** - Checks validity and shows the browser's validation message if invalid\n- **setCustomValidity(message: _string_): _void_** - Sets a custom validation message. Pass an empty string to clear.",
+          "description": "A multi-line text input with built-in form validation, auto-resizing, and styling support.\n\nThe component automatically handles:\n - Form integration\n - Auto-resizing based on content and row constraints\n - Built-in validation with customizable error messages\n - Accessibility attributes and labeling\n---\n\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Checks whether the textarea passes constraint validation\n- **reportValidity(): _boolean_** - Checks validity and shows the browser's validation message if invalid\n- **setCustomValidity(message: _string_): _void_** - Sets a custom validation message. Pass an empty string to clear.",
           "doc-url": "",
           "attributes": [
             {
               "name": "disabled",
+              "description": "Keep in mind that using disabled in its current form is an anti-pattern.\n\nThere will always be users who don't understand why an element is disabled, or users who can't even see that it is disabled because of poor lighting conditions or other reasons.\n\nPlease consider more informative alternatives before choosing to use disabled on an element.",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "invalid",
+              "description": "Mark the form field as invalid.\n\nMake sure to also set a `help-text` to help users fix the validation problem.",
               "value": { "type": "boolean", "default": "false" }
             },
-            { "name": "label", "value": { "type": "string" } },
-            { "name": "help-text", "value": { "type": "string" } },
-            { "name": "maximum-rows", "value": { "type": "number" } },
-            { "name": "minimum-rows", "value": { "type": "number" } },
-            { "name": "name", "value": { "type": "string" } },
-            { "name": "placeholder", "value": { "type": "string" } },
+            {
+              "name": "label",
+              "description": "Either a `label` or an `aria-label` must be provided.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "help-text",
+              "description": "Use in combination with `invalid` to show as a validation error message,\nor on its own to show a help text.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "maximum-rows",
+              "description": "Sets the maximum number of text rows before the content starts scrolling.",
+              "value": { "type": "number" }
+            },
+            {
+              "name": "minimum-rows",
+              "description": "Sets the minimum number of text rows the textarea should display",
+              "value": { "type": "number" }
+            },
+            {
+              "name": "name",
+              "description": "The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "placeholder",
+              "description": "Set a text that is shown in the textarea when it doesn't have a value.\n\nPlaceholder text should not be used as a substitute for labeling the element with a visible label.",
+              "value": { "type": "string" }
+            },
             {
               "name": "read-only",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "readonly",
+              "description": "Whether the input can be selected but not changed by the user",
               "value": { "type": "boolean", "default": "false" }
             },
             {
               "name": "required",
+              "description": "Whether user input is required on the input before form submission",
               "value": { "type": "boolean", "default": "false" }
             },
-            { "name": "value", "value": { "type": "string" } },
+            {
+              "name": "value",
+              "description": "Lets you set the current value",
+              "value": { "type": "string" }
+            },
             {
               "name": "optional",
+              "description": "Show an icon behind the label indicating the field is optional",
               "value": { "type": "boolean", "default": "false" }
             }
           ],
           "events": [],
           "js": {
             "properties": [
-              { "name": "disabled", "type": "boolean" },
-              { "name": "invalid", "type": "boolean" },
-              { "name": "label", "type": "string" },
-              { "name": "helpText", "type": "string" },
-              { "name": "maxRows", "type": "number" },
-              { "name": "minRows", "type": "number" },
-              { "name": "name", "type": "string" },
-              { "name": "placeholder", "type": "string" },
+              {
+                "name": "disabled",
+                "description": "Keep in mind that using disabled in its current form is an anti-pattern.\n\nThere will always be users who don't understand why an element is disabled, or users who can't even see that it is disabled because of poor lighting conditions or other reasons.\n\nPlease consider more informative alternatives before choosing to use disabled on an element.",
+                "type": "boolean"
+              },
+              {
+                "name": "invalid",
+                "description": "Mark the form field as invalid.\n\nMake sure to also set a `help-text` to help users fix the validation problem.",
+                "type": "boolean"
+              },
+              {
+                "name": "label",
+                "description": "Either a `label` or an `aria-label` must be provided.",
+                "type": "string"
+              },
+              {
+                "name": "helpText",
+                "description": "Use in combination with `invalid` to show as a validation error message,\nor on its own to show a help text.",
+                "type": "string"
+              },
+              {
+                "name": "maxRows",
+                "description": "Sets the maximum number of text rows before the content starts scrolling.",
+                "type": "number"
+              },
+              {
+                "name": "minRows",
+                "description": "Sets the minimum number of text rows the textarea should display",
+                "type": "number"
+              },
+              {
+                "name": "name",
+                "description": "The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form",
+                "type": "string"
+              },
+              {
+                "name": "placeholder",
+                "description": "Set a text that is shown in the textarea when it doesn't have a value.\n\nPlaceholder text should not be used as a substitute for labeling the element with a visible label.",
+                "type": "string"
+              },
               { "name": "readOnly", "type": "boolean" },
-              { "name": "readonly", "type": "boolean" },
-              { "name": "required", "type": "boolean" },
-              { "name": "value", "type": "string" },
-              { "name": "optional", "type": "boolean" },
-              { "name": "minHeight" },
-              { "name": "maxHeight" },
+              {
+                "name": "readonly",
+                "description": "Whether the input can be selected but not changed by the user",
+                "type": "boolean"
+              },
+              {
+                "name": "required",
+                "description": "Whether user input is required on the input before form submission",
+                "type": "boolean"
+              },
+              {
+                "name": "value",
+                "description": "Lets you set the current value",
+                "type": "string"
+              },
+              {
+                "name": "optional",
+                "description": "Show an icon behind the label indicating the field is optional",
+                "type": "boolean"
+              },
               {
                 "name": "validationMessage",
                 "description": "Returns the validation message if the textarea is invalid, otherwise an empty string",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warp-ds/elements",
   "type": "module",
-  "version": "2.9.0-next.6",
+  "version": "2.9.1-next.1",
   "packageManager": "pnpm@10.33.0",
   "description": "Custom elements for Warp",
   "exports": {
@@ -344,7 +344,6 @@
     "@warp-ds/css": "2.1.1",
     "@warp-ds/uno": "2.1.0",
     "@wc-toolkit/cem-validator": "^1.0.3",
-    "@wc-toolkit/jsdoc-tags": "^1.2.0",
     "@wc-toolkit/jsx-types": "^1.4.2",
     "@wc-toolkit/storybook-helpers": "^10.0.0",
     "@wc-toolkit/type-parser": "^1.2.0",