npm - @warp-ds/elements - Versions diffs - 2.10.0-next.1 → 2.10.0-next.3 - Mend

@warp-ds/elements 2.10.0-next.1 → 2.10.0-next.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (84) hide show

package/dist/custom-elements.json +146 -69
package/dist/docs/card/accessibility.md +74 -0
package/dist/docs/card/api.md +9 -3
package/dist/docs/card/card.md +234 -3
package/dist/docs/card/examples.md +75 -0
package/dist/docs/card/usage.md +76 -0
package/dist/docs/combobox/accessibility.md +71 -0
package/dist/docs/combobox/api.md +60 -30
package/dist/docs/combobox/combobox.md +203 -30
package/dist/docs/combobox/examples.md +44 -0
package/dist/docs/combobox/usage.md +28 -0
package/dist/docs/icon/accessibility.md +5 -0
package/dist/docs/icon/api.md +37 -0
package/dist/docs/icon/examples.md +45 -0
package/dist/docs/icon/icon.md +107 -0
package/dist/docs/icon/usage.md +11 -0
package/dist/docs/link/api.md +18 -22
package/dist/docs/link/examples.md +75 -0
package/dist/docs/link/link.md +111 -22
package/dist/docs/link/usage.md +18 -0
package/dist/index.d.ts +479 -183
package/dist/packages/affix/affix.js +3 -3
package/dist/packages/affix/affix.js.map +4 -4
package/dist/packages/alert/alert.js +1 -1
package/dist/packages/alert/alert.js.map +3 -3
package/dist/packages/attention/attention.js.map +4 -4
package/dist/packages/attention/attention.test.js +1 -1
package/dist/packages/breadcrumbs/breadcrumbs.js.map +1 -1
package/dist/packages/button/button.js.map +3 -3
package/dist/packages/card/card.d.ts +9 -6
package/dist/packages/card/card.js.map +3 -3
package/dist/packages/checkbox/checkbox.d.ts +40 -11
package/dist/packages/checkbox/checkbox.js.map +2 -2
package/dist/packages/checkbox/checkbox.test.js +1 -1
package/dist/packages/checkbox-group/checkbox-group.a11y.test.js +1 -1
package/dist/packages/checkbox-group/checkbox-group.d.ts +30 -5
package/dist/packages/checkbox-group/checkbox-group.js.map +3 -3
package/dist/packages/combobox/combobox.a11y.test.js +24 -0
package/dist/packages/combobox/combobox.d.ts +65 -45
package/dist/packages/combobox/combobox.hydration.test.js +39 -1
package/dist/packages/combobox/combobox.js +13 -13
package/dist/packages/combobox/combobox.js.map +4 -4
package/dist/packages/combobox/combobox.stories.js +28 -15
package/dist/packages/combobox/combobox.test.js +110 -0
package/dist/packages/datepicker/DatePicker.test.js +1 -1
package/dist/packages/datepicker/datepicker.js.map +4 -4
package/dist/packages/datepicker/datepicker.test.js +1 -1
package/dist/packages/expandable/expandable.js +2 -2
package/dist/packages/expandable/expandable.js.map +3 -3
package/dist/packages/icon/icon.d.ts +13 -3
package/dist/packages/icon/icon.js +2 -2
package/dist/packages/icon/icon.js.map +3 -3
package/dist/packages/icon/icon.react.stories.d.ts +1 -1
package/dist/packages/icon/react.d.ts +2 -2
package/dist/packages/link/link.d.ts +15 -16
package/dist/packages/link/link.js.map +2 -2
package/dist/packages/link/link.test.js +1 -1
package/dist/packages/modal-header/modal-header.js +3 -1
package/dist/packages/modal-header/modal-header.js.map +4 -4
package/dist/packages/page-indicator/page-indicator.js.map +1 -1
package/dist/packages/pagination/pagination.js.map +4 -4
package/dist/packages/pagination/pagination.test.js +1 -1
package/dist/packages/pill/pill.js.map +4 -4
package/dist/packages/radio/radio.test.js +1 -1
package/dist/packages/radio-group/radio-group.a11y.test.js +1 -1
package/dist/packages/radio-group/radio-group.js.map +1 -1
package/dist/packages/select/select.js.map +4 -4
package/dist/packages/slider/slider.js.map +1 -1
package/dist/packages/slider/slider.test.js +1 -1
package/dist/packages/slider-thumb/slider-thumb.js.map +1 -1
package/dist/packages/step/step.js +1 -1
package/dist/packages/step/step.js.map +4 -4
package/dist/packages/switch/switch.a11y.test.js +1 -1
package/dist/packages/tabs/tabs.a11y.test.js +1 -1
package/dist/packages/tabs/tabs.test.js +1 -1
package/dist/packages/textarea/textarea.js.map +1 -1
package/dist/packages/textarea/textarea.test.js +1 -1
package/dist/packages/textfield/textfield.test.js +1 -1
package/dist/packages/toast/toast.js +3 -3
package/dist/packages/toast/toast.js.map +4 -4
package/dist/packages/toast/toast.stories.d.ts +1 -5
package/dist/packages/toast/toast.stories.js +0 -17
package/dist/web-types.json +147 -75
package/package.json +2 -2

package/dist/index.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { WIcon } from "./packages/icon/icon.ts";
+import type { WarpIcon, WIcon } from "./packages/icon/icon.ts";
 import type { WarpTextField } from "./packages/textfield/textfield.ts";
 import type { WarpAffix } from "./packages/affix/affix.ts";
 import type { WarpAlert } from "./packages/alert/alert.ts";
@@ -114,22 +114,26 @@ type BaseProps<T extends HTMLElement> = {
 type BaseEvents = {};
-export type WIconProps = {
+export type WarpIconProps = {
   /** Icon filename (without .svg) */
-  name?: WIcon["name"];
-  /** Size: small, medium, large or pixel value (e.g. "32px") */
-  size?: WIcon["size"];
-  /** Locale used in CDN URL */
-  locale?: WIcon["locale"];
+  name?: WarpIcon["name"];
+  /** Size: small, medium, large or pixel value (e.g. "32px"). */
+  size?: WarpIcon["size"];
+  /** Locale used for `<title>` text.
+Reads the `lang` attribute from `<html>`, falls back to 'en'. */
+  locale?: WarpIcon["locale"];
 };
-export type WIconSolidJsProps = {
+export type WarpIconSolidJsProps = {
   /** Icon filename (without .svg) */
-  "prop:name"?: WIcon["name"];
-  /** Size: small, medium, large or pixel value (e.g. "32px") */
-  "prop:size"?: WIcon["size"];
-  /** Locale used in CDN URL */
-  "prop:locale"?: WIcon["locale"];
+  "prop:name"?: WarpIcon["name"];
+  /** Size: small, medium, large or pixel value (e.g. "32px"). */
+  "prop:size"?: WarpIcon["size"];
+  /** Locale used for `<title>` text.
+Reads the `lang` attribute from `<html>`, falls back to 'en'. */
+  "prop:locale"?: WarpIcon["locale"];
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -343,44 +347,52 @@ export type WarpAlertSolidJsProps = {
 };
 export type WarpLinkProps = {
-  /**  */
+  /** Focus the link after it is rendered */
   autofocus?: WarpLink["autofocus"];
-  /**  */
+  /** Visual style for the link/button. */
   variant?: WarpLink["variant"];
-  /**  */
+  /** Render a smaller version */
   small?: WarpLink["small"];
-  /**  */
+  /** The URL the link points to */
   href?: WarpLink["href"];
-  /**  */
+  /** Applies disabled styling, but you need to disable clicks on your own.
+The component renders an `<a>` element; `disabled` affects styling, but does not inherently prevent navigation. If you need to fully disable interaction, omit `href` and/or prevent default click behavior. */
   disabled?: WarpLink["disabled"];
-  /**  */
+  /** Where to display the linked URL (e.g. `_blank`) */
   target?: WarpLink["target"];
-  /**  */
+  /** Relationship of the linked URL.
+If `target="_blank"` and `rel` is not provided, the component uses `noopener`. */
   rel?: WarpLink["rel"];
-  /**  */
+  /** Makes the link take up the full width of its parent */
   "full-width"?: WarpLink["fullWidth"];
-  /**  */
+  /** Makes the link take up the full width of its parent */
   fullWidth?: WarpLink["fullWidth"];
 };
 export type WarpLinkSolidJsProps = {
-  /**  */
+  /** Focus the link after it is rendered */
   "prop:autofocus"?: WarpLink["autofocus"];
-  /**  */
+  /** Visual style for the link/button. */
   "prop:variant"?: WarpLink["variant"];
-  /**  */
+  /** Render a smaller version */
   "prop:small"?: WarpLink["small"];
-  /**  */
+  /** The URL the link points to */
   "prop:href"?: WarpLink["href"];
-  /**  */
+  /** Applies disabled styling, but you need to disable clicks on your own.
+The component renders an `<a>` element; `disabled` affects styling, but does not inherently prevent navigation. If you need to fully disable interaction, omit `href` and/or prevent default click behavior. */
   "prop:disabled"?: WarpLink["disabled"];
-  /**  */
+  /** Where to display the linked URL (e.g. `_blank`) */
   "prop:target"?: WarpLink["target"];
-  /**  */
+  /** Relationship of the linked URL.
+If `target="_blank"` and `rel` is not provided, the component uses `noopener`. */
   "prop:rel"?: WarpLink["rel"];
-  /**  */
+  /** Makes the link take up the full width of its parent */
   "bool:full-width"?: WarpLink["fullWidth"];
-  /**  */
+  /** Makes the link take up the full width of its parent */
   "prop:fullWidth"?: WarpLink["fullWidth"];
   /** Set the innerHTML of the element */
@@ -723,22 +735,34 @@ Defaults to the localized "You are here" label. Set `aria-label` when the defaul
 };
 export type WarpCardProps = {
-  /**  */
+  /** Whether the card is visually selected.
+Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes. */
   selected?: WarpCard["selected"];
-  /**  */
+  /** Whether the card uses the flat visual treatment.
+Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface. */
   flat?: WarpCard["flat"];
-  /**  */
+  /** Whether the whole card is interactive.
+When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice. */
   clickable?: WarpCard["clickable"];
   /**  */
   buttonText?: WarpCard["buttonText"];
 };
 export type WarpCardSolidJsProps = {
-  /**  */
+  /** Whether the card is visually selected.
+Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes. */
   "prop:selected"?: WarpCard["selected"];
-  /**  */
+  /** Whether the card uses the flat visual treatment.
+Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface. */
   "prop:flat"?: WarpCard["flat"];
-  /**  */
+  /** Whether the whole card is interactive.
+When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice. */
   "prop:clickable"?: WarpCard["clickable"];
   /**  */
   "prop:buttonText"?: WarpCard["buttonText"];
@@ -750,19 +774,33 @@ export type WarpCardSolidJsProps = {
 };
 export type WCheckboxProps = {
-  /** The name of the checkbox, submitted as a name/value pair with form data. */
+  /** The name of the checkbox.
+When the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name. */
   name?: WCheckbox["name"];
-  /** The value of the checkbox, submitted as a name/value pair with form data. */
+  /** The value submitted when the checkbox is checked.
+If no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value. */
   value?: WCheckbox["value"];
-  /** Draws the checkbox in an indeterminate state. */
+  /** Whether the checkbox is visually indeterminate.
+Use this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked. */
   indeterminate?: WCheckbox["indeterminate"];
-  /** Draws the checkbox in a checked state (reflected to attribute). */
+  /** Whether the checkbox is checked.
+Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute. */
   checked?: WCheckbox["checked"];
-  /** Disables the checkbox. */
+  /** Whether the checkbox is disabled.
+Disabled checkboxes cannot be focused, changed, or submitted with form data. */
   disabled?: WCheckbox["disabled"];
-  /** Makes the checkbox a required field. */
+  /** Whether the checkbox must be checked before form submission.
+A required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`. */
   required?: WCheckbox["required"];
-  /** Draws the checkbox in an invalid state. */
+  /** Whether the checkbox is visually invalid.
+Use this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form. */
   invalid?: WCheckbox["invalid"];
   /**  */
   input?: WCheckbox["input"];
@@ -772,19 +810,33 @@ export type WCheckboxProps = {
 };
 export type WCheckboxSolidJsProps = {
-  /** The name of the checkbox, submitted as a name/value pair with form data. */
+  /** The name of the checkbox.
+When the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name. */
   "prop:name"?: WCheckbox["name"];
-  /** The value of the checkbox, submitted as a name/value pair with form data. */
+  /** The value submitted when the checkbox is checked.
+If no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value. */
   "prop:value"?: WCheckbox["value"];
-  /** Draws the checkbox in an indeterminate state. */
+  /** Whether the checkbox is visually indeterminate.
+Use this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked. */
   "prop:indeterminate"?: WCheckbox["indeterminate"];
-  /** Draws the checkbox in a checked state (reflected to attribute). */
+  /** Whether the checkbox is checked.
+Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute. */
   "prop:checked"?: WCheckbox["checked"];
-  /** Disables the checkbox. */
+  /** Whether the checkbox is disabled.
+Disabled checkboxes cannot be focused, changed, or submitted with form data. */
   "prop:disabled"?: WCheckbox["disabled"];
-  /** Makes the checkbox a required field. */
+  /** Whether the checkbox must be checked before form submission.
+A required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`. */
   "prop:required"?: WCheckbox["required"];
-  /** Draws the checkbox in an invalid state. */
+  /** Whether the checkbox is visually invalid.
+Use this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form. */
   "prop:invalid"?: WCheckbox["invalid"];
   /**  */
   "prop:input"?: WCheckbox["input"];
@@ -798,36 +850,64 @@ export type WCheckboxSolidJsProps = {
 };
 export type WCheckboxGroupProps = {
-  /** The group label displayed above the checkboxes. */
+  /** The group label displayed above the checkboxes.
+Use this to describe the shared question or topic for the checkbox options. The label is connected to the internal group for assistive technologies. */
   label?: WCheckboxGroup["label"];
-  /** The name applied to child checkboxes when they do not provide one. */
+  /** The name applied to child checkboxes when they do not provide one.
+Use this when the grouped checkboxes should submit values under the same form field name. Individual checkboxes can still override the group name with their own `name`. */
   name?: WCheckboxGroup["name"];
-  /** Whether to show optional text next to the label. */
+  /** Whether to show optional text next to the label.
+Use this to indicate that selecting an option from the group is not required. */
   optional?: WCheckboxGroup["optional"];
-  /**  */
+  /** Help text displayed below the checkbox group.
+Use this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message. */
   "help-text"?: WCheckboxGroup["helpText"];
-  /**  */
+  /** Help text displayed below the checkbox group.
+Use this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message. */
   helpText?: WCheckboxGroup["helpText"];
-  /** Makes the checkbox group required. */
+  /** Whether at least one checkbox in the group must be selected.
+Required validation is managed by the group. The individual checkboxes provide the submitted form values. */
   required?: WCheckboxGroup["required"];
-  /** Marks the checkbox group as invalid. */
+  /** Whether the checkbox group is visually invalid.
+Use this to show an externally managed validation error for the group. The invalid state is also shared with child checkboxes for consistent styling and accessibility state. */
   invalid?: WCheckboxGroup["invalid"];
 };
 export type WCheckboxGroupSolidJsProps = {
-  /** The group label displayed above the checkboxes. */
+  /** The group label displayed above the checkboxes.
+Use this to describe the shared question or topic for the checkbox options. The label is connected to the internal group for assistive technologies. */
   "prop:label"?: WCheckboxGroup["label"];
-  /** The name applied to child checkboxes when they do not provide one. */
+  /** The name applied to child checkboxes when they do not provide one.
+Use this when the grouped checkboxes should submit values under the same form field name. Individual checkboxes can still override the group name with their own `name`. */
   "prop:name"?: WCheckboxGroup["name"];
-  /** Whether to show optional text next to the label. */
+  /** Whether to show optional text next to the label.
+Use this to indicate that selecting an option from the group is not required. */
   "prop:optional"?: WCheckboxGroup["optional"];
-  /**  */
+  /** Help text displayed below the checkbox group.
+Use this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message. */
   "attr:help-text"?: WCheckboxGroup["helpText"];
-  /**  */
+  /** Help text displayed below the checkbox group.
+Use this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message. */
   "prop:helpText"?: WCheckboxGroup["helpText"];
-  /** Makes the checkbox group required. */
+  /** Whether at least one checkbox in the group must be selected.
+Required validation is managed by the group. The individual checkboxes provide the submitted form values. */
   "prop:required"?: WCheckboxGroup["required"];
-  /** Marks the checkbox group as invalid. */
+  /** Whether the checkbox group is visually invalid.
+Use this to show an externally managed validation error for the group. The invalid state is also shared with child checkboxes for consistent styling and accessibility state. */
   "prop:invalid"?: WCheckboxGroup["invalid"];
   /** Set the innerHTML of the element */
@@ -837,88 +917,168 @@ export type WCheckboxGroupSolidJsProps = {
 };
 export type WarpComboboxProps = {
-  /** The available options to select from */
+  /** The available options to select from.
+Use this for framework usage, application state, or remote search results. When `options` contains entries, it is used instead of child `<option>` elements. */
   options?: WarpCombobox["options"];
-  /** Label above input */
+  /** The label displayed above the input.
+Use this to give the combobox a visible and accessible name. */
   label?: WarpCombobox["label"];
-  /** Input placeholder */
+  /** Placeholder text displayed when the input is empty.
+Use this as a short hint for the expected input. Do not use placeholder text as a replacement for a label. */
   placeholder?: WarpCombobox["placeholder"];
-  /** The input value */
+  /** The selected or typed value.
+When an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label. */
   value?: WarpCombobox["value"];
-  /** Whether the popover opens when focus is on the text field */
+  /** Whether the option list opens when the input receives focus.
+Use this when users should see available options before they start typing. */
   "open-on-focus"?: WarpCombobox["openOnFocus"];
-  /** Whether the popover opens when focus is on the text field */
+  /** Whether the option list opens when the input receives focus.
+Use this when users should see available options before they start typing. */
   openOnFocus?: WarpCombobox["openOnFocus"];
-  /** Select active option on blur */
+  /** Whether the active option is selected when the input loses focus.
+When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur. */
   "select-on-blur"?: WarpCombobox["selectOnBlur"];
-  /** Select active option on blur */
+  /** Whether the active option is selected when the input loses focus.
+When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur. */
   selectOnBlur?: WarpCombobox["selectOnBlur"];
-  /** Whether the matching text segments in the options should be highlighted */
+  /** Whether matching text segments in options are highlighted.
+Use this to visually emphasize the part of each option that matches the current input value. */
   "match-text-segments"?: WarpCombobox["matchTextSegments"];
-  /** Whether the matching text segments in the options should be highlighted */
+  /** Whether matching text segments in options are highlighted.
+Use this to visually emphasize the part of each option that matches the current input value. */
   matchTextSegments?: WarpCombobox["matchTextSegments"];
-  /** Disable client-side static filtering */
+  /** Whether built-in client-side filtering is disabled.
+Use this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided. */
   "disable-static-filtering"?: WarpCombobox["disableStaticFiltering"];
-  /** Disable client-side static filtering */
+  /** Whether built-in client-side filtering is disabled.
+Use this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided. */
   disableStaticFiltering?: WarpCombobox["disableStaticFiltering"];
-  /** Renders the input field in an invalid state */
+  /** Whether the combobox is visually invalid.
+Use this to show an externally managed validation error. Pair it with `help-text` to explain how to fix the error. */
   invalid?: WarpCombobox["invalid"];
-  /** The content to display as the help text */
+  /** Help text displayed below the input.
+Use this for supporting guidance or validation feedback. */
   "help-text"?: WarpCombobox["helpText"];
-  /** The content to display as the help text */
+  /** Help text displayed below the input.
+Use this for supporting guidance or validation feedback. */
   helpText?: WarpCombobox["helpText"];
-  /** Whether the element is disabled */
+  /** Whether the combobox is disabled.
+Disabled comboboxes cannot be focused, changed, or submitted with form data. */
   disabled?: WarpCombobox["disabled"];
-  /** Whether the element is required */
+  /** Whether the combobox is required before form submission.
+Use this when the user must provide a value before submitting the form. */
   required?: WarpCombobox["required"];
-  /** Whether to show optional text */
+  /** Whether to show optional text next to the label.
+Use this to indicate that the combobox is not required. */
   optional?: WarpCombobox["optional"];
-  /** Name attribute for form submission */
+  /** The name submitted with the combobox value.
+Use this when the combobox belongs to a form and its value should be included in form data. */
   name?: WarpCombobox["name"];
-  /** Autocomplete attribute for the input field */
+  /** The autocomplete attribute passed to the internal input.
+Defaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token. */
   autocomplete?: WarpCombobox["autocomplete"];
 };
 export type WarpComboboxSolidJsProps = {
-  /** The available options to select from */
+  /** The available options to select from.
+Use this for framework usage, application state, or remote search results. When `options` contains entries, it is used instead of child `<option>` elements. */
   "prop:options"?: WarpCombobox["options"];
-  /** Label above input */
+  /** The label displayed above the input.
+Use this to give the combobox a visible and accessible name. */
   "prop:label"?: WarpCombobox["label"];
-  /** Input placeholder */
+  /** Placeholder text displayed when the input is empty.
+Use this as a short hint for the expected input. Do not use placeholder text as a replacement for a label. */
   "prop:placeholder"?: WarpCombobox["placeholder"];
-  /** The input value */
+  /** The selected or typed value.
+When an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label. */
   "prop:value"?: WarpCombobox["value"];
-  /** Whether the popover opens when focus is on the text field */
+  /** Whether the option list opens when the input receives focus.
+Use this when users should see available options before they start typing. */
   "bool:open-on-focus"?: WarpCombobox["openOnFocus"];
-  /** Whether the popover opens when focus is on the text field */
+  /** Whether the option list opens when the input receives focus.
+Use this when users should see available options before they start typing. */
   "prop:openOnFocus"?: WarpCombobox["openOnFocus"];
-  /** Select active option on blur */
+  /** Whether the active option is selected when the input loses focus.
+When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur. */
   "bool:select-on-blur"?: WarpCombobox["selectOnBlur"];
-  /** Select active option on blur */
+  /** Whether the active option is selected when the input loses focus.
+When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur. */
   "prop:selectOnBlur"?: WarpCombobox["selectOnBlur"];
-  /** Whether the matching text segments in the options should be highlighted */
+  /** Whether matching text segments in options are highlighted.
+Use this to visually emphasize the part of each option that matches the current input value. */
   "bool:match-text-segments"?: WarpCombobox["matchTextSegments"];
-  /** Whether the matching text segments in the options should be highlighted */
+  /** Whether matching text segments in options are highlighted.
+Use this to visually emphasize the part of each option that matches the current input value. */
   "prop:matchTextSegments"?: WarpCombobox["matchTextSegments"];
-  /** Disable client-side static filtering */
+  /** Whether built-in client-side filtering is disabled.
+Use this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided. */
   "bool:disable-static-filtering"?: WarpCombobox["disableStaticFiltering"];
-  /** Disable client-side static filtering */
+  /** Whether built-in client-side filtering is disabled.
+Use this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided. */
   "prop:disableStaticFiltering"?: WarpCombobox["disableStaticFiltering"];
-  /** Renders the input field in an invalid state */
+  /** Whether the combobox is visually invalid.
+Use this to show an externally managed validation error. Pair it with `help-text` to explain how to fix the error. */
   "prop:invalid"?: WarpCombobox["invalid"];
-  /** The content to display as the help text */
+  /** Help text displayed below the input.
+Use this for supporting guidance or validation feedback. */
   "attr:help-text"?: WarpCombobox["helpText"];
-  /** The content to display as the help text */
+  /** Help text displayed below the input.
+Use this for supporting guidance or validation feedback. */
   "prop:helpText"?: WarpCombobox["helpText"];
-  /** Whether the element is disabled */
+  /** Whether the combobox is disabled.
+Disabled comboboxes cannot be focused, changed, or submitted with form data. */
   "prop:disabled"?: WarpCombobox["disabled"];
-  /** Whether the element is required */
+  /** Whether the combobox is required before form submission.
+Use this when the user must provide a value before submitting the form. */
   "prop:required"?: WarpCombobox["required"];
-  /** Whether to show optional text */
+  /** Whether to show optional text next to the label.
+Use this to indicate that the combobox is not required. */
   "prop:optional"?: WarpCombobox["optional"];
-  /** Name attribute for form submission */
+  /** The name submitted with the combobox value.
+Use this when the combobox belongs to a form and its value should be included in form data. */
   "prop:name"?: WarpCombobox["name"];
-  /** Autocomplete attribute for the input field */
+  /** The autocomplete attribute passed to the internal input.
+Defaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token. */
   "prop:autocomplete"?: WarpCombobox["autocomplete"];
   /** Set the innerHTML of the element */
@@ -1918,10 +2078,12 @@ export type CustomElements = {
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
    * - `name`: Icon filename (without .svg)
-   * - `size`: Size: small, medium, large or pixel value (e.g. "32px")
-   * - `locale`: Locale used in CDN URL
+   * - `size`: Size: small, medium, large or pixel value (e.g. "32px").
+   * - `locale`: Locale used for `<title>` text.
+   *
+   * Reads the `lang` attribute from `<html>`, falls back to 'en'.
    */
-  "w-icon": Partial<WIconProps & BaseProps<WIcon> & BaseEvents>;
+  "w-icon": Partial<WarpIconProps & BaseProps<WarpIcon> & BaseEvents>;
   /**
    * A single-line input component used for entering and editing textual or numeric data.
@@ -2032,14 +2194,18 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `autofocus`: undefined
-   * - `variant`: undefined
-   * - `small`: undefined
-   * - `href`: undefined
-   * - `disabled`: undefined
-   * - `target`: undefined
-   * - `rel`: undefined
-   * - `full-width`/`fullWidth`: undefined
+   * - `autofocus`: Focus the link after it is rendered
+   * - `variant`: Visual style for the link/button.
+   * - `small`: Render a smaller version
+   * - `href`: The URL the link points to
+   * - `disabled`: Applies disabled styling, but you need to disable clicks on your own.
+   *
+   * The component renders an `<a>` element; `disabled` affects styling, but does not inherently prevent navigation. If you need to fully disable interaction, omit `href` and/or prevent default click behavior.
+   * - `target`: Where to display the linked URL (e.g. `_blank`)
+   * - `rel`: Relationship of the linked URL.
+   *
+   * If `target="_blank"` and `rel` is not provided, the component uses `noopener`.
+   * - `full-width`/`fullWidth`: Makes the link take up the full width of its parent
    */
   "w-link": Partial<WarpLinkProps & BaseProps<WarpLink> & BaseEvents>;
@@ -2219,9 +2385,15 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `selected`: undefined
-   * - `flat`: undefined
-   * - `clickable`: undefined
+   * - `selected`: Whether the card is visually selected.
+   *
+   * Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.
+   * - `flat`: Whether the card uses the flat visual treatment.
+   *
+   * Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.
+   * - `clickable`: Whether the whole card is interactive.
+   *
+   * When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.
    * - `buttonText`: undefined (property only)
    *
    * ## Methods
@@ -2239,13 +2411,27 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `name`: The name of the checkbox, submitted as a name/value pair with form data.
-   * - `value`: The value of the checkbox, submitted as a name/value pair with form data.
-   * - `indeterminate`: Draws the checkbox in an indeterminate state.
-   * - `checked`: Draws the checkbox in a checked state (reflected to attribute).
-   * - `disabled`: Disables the checkbox.
-   * - `required`: Makes the checkbox a required field.
-   * - `invalid`: Draws the checkbox in an invalid state.
+   * - `name`: The name of the checkbox.
+   *
+   * When the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name.
+   * - `value`: The value submitted when the checkbox is checked.
+   *
+   * If no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value.
+   * - `indeterminate`: Whether the checkbox is visually indeterminate.
+   *
+   * Use this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked.
+   * - `checked`: Whether the checkbox is checked.
+   *
+   * Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute.
+   * - `disabled`: Whether the checkbox is disabled.
+   *
+   * Disabled checkboxes cannot be focused, changed, or submitted with form data.
+   * - `required`: Whether the checkbox must be checked before form submission.
+   *
+   * A required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`.
+   * - `invalid`: Whether the checkbox is visually invalid.
+   *
+   * Use this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form.
    * - `input`: undefined (property only)
    * - `_computedInvalid`: Computed invalid state: combines own invalid with group invalid (property only) (readonly)
    * - `validationMessage`: Returns the validation message if the checkbox is invalid, otherwise an empty string (property only) (readonly)
@@ -2278,11 +2464,23 @@ export type CustomElements = {
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
    * - `label`: The group label displayed above the checkboxes.
+   *
+   * Use this to describe the shared question or topic for the checkbox options. The label is connected to the internal group for assistive technologies.
    * - `name`: The name applied to child checkboxes when they do not provide one.
+   *
+   * Use this when the grouped checkboxes should submit values under the same form field name. Individual checkboxes can still override the group name with their own `name`.
    * - `optional`: Whether to show optional text next to the label.
-   * - `help-text`/`helpText`: undefined
-   * - `required`: Makes the checkbox group required.
-   * - `invalid`: Marks the checkbox group as invalid.
+   *
+   * Use this to indicate that selecting an option from the group is not required.
+   * - `help-text`/`helpText`: Help text displayed below the checkbox group.
+   *
+   * Use this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message.
+   * - `required`: Whether at least one checkbox in the group must be selected.
+   *
+   * Required validation is managed by the group. The individual checkboxes provide the submitted form values.
+   * - `invalid`: Whether the checkbox group is visually invalid.
+   *
+   * Use this to show an externally managed validation error for the group. The invalid state is also shared with child checkboxes for consistent styling and accessibility state.
    *
    * ## Methods
    *
@@ -2305,21 +2503,51 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `options`: The available options to select from
-   * - `label`: Label above input
-   * - `placeholder`: Input placeholder
-   * - `value`: The input value
-   * - `open-on-focus`/`openOnFocus`: Whether the popover opens when focus is on the text field
-   * - `select-on-blur`/`selectOnBlur`: Select active option on blur
-   * - `match-text-segments`/`matchTextSegments`: Whether the matching text segments in the options should be highlighted
-   * - `disable-static-filtering`/`disableStaticFiltering`: Disable client-side static filtering
-   * - `invalid`: Renders the input field in an invalid state
-   * - `help-text`/`helpText`: The content to display as the help text
-   * - `disabled`: Whether the element is disabled
-   * - `required`: Whether the element is required
-   * - `optional`: Whether to show optional text
-   * - `name`: Name attribute for form submission
-   * - `autocomplete`: Autocomplete attribute for the input field
+   * - `options`: The available options to select from.
+   *
+   * Use this for framework usage, application state, or remote search results. When `options` contains entries, it is used instead of child `<option>` elements.
+   * - `label`: The label displayed above the input.
+   *
+   * Use this to give the combobox a visible and accessible name.
+   * - `placeholder`: Placeholder text displayed when the input is empty.
+   *
+   * Use this as a short hint for the expected input. Do not use placeholder text as a replacement for a label.
+   * - `value`: The selected or typed value.
+   *
+   * When an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label.
+   * - `open-on-focus`/`openOnFocus`: Whether the option list opens when the input receives focus.
+   *
+   * Use this when users should see available options before they start typing.
+   * - `select-on-blur`/`selectOnBlur`: Whether the active option is selected when the input loses focus.
+   *
+   * When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur.
+   * - `match-text-segments`/`matchTextSegments`: Whether matching text segments in options are highlighted.
+   *
+   * Use this to visually emphasize the part of each option that matches the current input value.
+   * - `disable-static-filtering`/`disableStaticFiltering`: Whether built-in client-side filtering is disabled.
+   *
+   * Use this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided.
+   * - `invalid`: Whether the combobox is visually invalid.
+   *
+   * Use this to show an externally managed validation error. Pair it with `help-text` to explain how to fix the error.
+   * - `help-text`/`helpText`: Help text displayed below the input.
+   *
+   * Use this for supporting guidance or validation feedback.
+   * - `disabled`: Whether the combobox is disabled.
+   *
+   * Disabled comboboxes cannot be focused, changed, or submitted with form data.
+   * - `required`: Whether the combobox is required before form submission.
+   *
+   * Use this when the user must provide a value before submitting the form.
+   * - `optional`: Whether to show optional text next to the label.
+   *
+   * Use this to indicate that the combobox is not required.
+   * - `name`: The name submitted with the combobox value.
+   *
+   * Use this when the combobox belongs to a form and its value should be included in form data.
+   * - `autocomplete`: The autocomplete attribute passed to the internal input.
+   *
+   * Defaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token.
    *
    * ## Methods
    *
@@ -2870,11 +3098,13 @@ export type CustomElementsSolidJs = {
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
    * - `name`: Icon filename (without .svg)
-   * - `size`: Size: small, medium, large or pixel value (e.g. "32px")
-   * - `locale`: Locale used in CDN URL
+   * - `size`: Size: small, medium, large or pixel value (e.g. "32px").
+   * - `locale`: Locale used for `<title>` text.
+   *
+   * Reads the `lang` attribute from `<html>`, falls back to 'en'.
    */
   "w-icon": Partial<
-    WIconProps & WIconSolidJsProps & BaseProps<WIcon> & BaseEvents
+    WarpIconProps & WarpIconSolidJsProps & BaseProps<WarpIcon> & BaseEvents
   >;
   /**
@@ -2993,14 +3223,18 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `autofocus`: undefined
-   * - `variant`: undefined
-   * - `small`: undefined
-   * - `href`: undefined
-   * - `disabled`: undefined
-   * - `target`: undefined
-   * - `rel`: undefined
-   * - `full-width`/`fullWidth`: undefined
+   * - `autofocus`: Focus the link after it is rendered
+   * - `variant`: Visual style for the link/button.
+   * - `small`: Render a smaller version
+   * - `href`: The URL the link points to
+   * - `disabled`: Applies disabled styling, but you need to disable clicks on your own.
+   *
+   * The component renders an `<a>` element; `disabled` affects styling, but does not inherently prevent navigation. If you need to fully disable interaction, omit `href` and/or prevent default click behavior.
+   * - `target`: Where to display the linked URL (e.g. `_blank`)
+   * - `rel`: Relationship of the linked URL.
+   *
+   * If `target="_blank"` and `rel` is not provided, the component uses `noopener`.
+   * - `full-width`/`fullWidth`: Makes the link take up the full width of its parent
    */
   "w-link": Partial<
     WarpLinkProps & WarpLinkSolidJsProps & BaseProps<WarpLink> & BaseEvents
@@ -3197,9 +3431,15 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `selected`: undefined
-   * - `flat`: undefined
-   * - `clickable`: undefined
+   * - `selected`: Whether the card is visually selected.
+   *
+   * Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.
+   * - `flat`: Whether the card uses the flat visual treatment.
+   *
+   * Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.
+   * - `clickable`: Whether the whole card is interactive.
+   *
+   * When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.
    * - `buttonText`: undefined (property only)
    *
    * ## Methods
@@ -3219,13 +3459,27 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `name`: The name of the checkbox, submitted as a name/value pair with form data.
-   * - `value`: The value of the checkbox, submitted as a name/value pair with form data.
-   * - `indeterminate`: Draws the checkbox in an indeterminate state.
-   * - `checked`: Draws the checkbox in a checked state (reflected to attribute).
-   * - `disabled`: Disables the checkbox.
-   * - `required`: Makes the checkbox a required field.
-   * - `invalid`: Draws the checkbox in an invalid state.
+   * - `name`: The name of the checkbox.
+   *
+   * When the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name.
+   * - `value`: The value submitted when the checkbox is checked.
+   *
+   * If no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value.
+   * - `indeterminate`: Whether the checkbox is visually indeterminate.
+   *
+   * Use this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked.
+   * - `checked`: Whether the checkbox is checked.
+   *
+   * Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute.
+   * - `disabled`: Whether the checkbox is disabled.
+   *
+   * Disabled checkboxes cannot be focused, changed, or submitted with form data.
+   * - `required`: Whether the checkbox must be checked before form submission.
+   *
+   * A required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`.
+   * - `invalid`: Whether the checkbox is visually invalid.
+   *
+   * Use this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form.
    * - `input`: undefined (property only)
    * - `_computedInvalid`: Computed invalid state: combines own invalid with group invalid (property only) (readonly)
    * - `validationMessage`: Returns the validation message if the checkbox is invalid, otherwise an empty string (property only) (readonly)
@@ -3260,11 +3514,23 @@ export type CustomElementsSolidJs = {
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
    * - `label`: The group label displayed above the checkboxes.
+   *
+   * Use this to describe the shared question or topic for the checkbox options. The label is connected to the internal group for assistive technologies.
    * - `name`: The name applied to child checkboxes when they do not provide one.
+   *
+   * Use this when the grouped checkboxes should submit values under the same form field name. Individual checkboxes can still override the group name with their own `name`.
    * - `optional`: Whether to show optional text next to the label.
-   * - `help-text`/`helpText`: undefined
-   * - `required`: Makes the checkbox group required.
-   * - `invalid`: Marks the checkbox group as invalid.
+   *
+   * Use this to indicate that selecting an option from the group is not required.
+   * - `help-text`/`helpText`: Help text displayed below the checkbox group.
+   *
+   * Use this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message.
+   * - `required`: Whether at least one checkbox in the group must be selected.
+   *
+   * Required validation is managed by the group. The individual checkboxes provide the submitted form values.
+   * - `invalid`: Whether the checkbox group is visually invalid.
+   *
+   * Use this to show an externally managed validation error for the group. The invalid state is also shared with child checkboxes for consistent styling and accessibility state.
    *
    * ## Methods
    *
@@ -3290,21 +3556,51 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `options`: The available options to select from
-   * - `label`: Label above input
-   * - `placeholder`: Input placeholder
-   * - `value`: The input value
-   * - `open-on-focus`/`openOnFocus`: Whether the popover opens when focus is on the text field
-   * - `select-on-blur`/`selectOnBlur`: Select active option on blur
-   * - `match-text-segments`/`matchTextSegments`: Whether the matching text segments in the options should be highlighted
-   * - `disable-static-filtering`/`disableStaticFiltering`: Disable client-side static filtering
-   * - `invalid`: Renders the input field in an invalid state
-   * - `help-text`/`helpText`: The content to display as the help text
-   * - `disabled`: Whether the element is disabled
-   * - `required`: Whether the element is required
-   * - `optional`: Whether to show optional text
-   * - `name`: Name attribute for form submission
-   * - `autocomplete`: Autocomplete attribute for the input field
+   * - `options`: The available options to select from.
+   *
+   * Use this for framework usage, application state, or remote search results. When `options` contains entries, it is used instead of child `<option>` elements.
+   * - `label`: The label displayed above the input.
+   *
+   * Use this to give the combobox a visible and accessible name.
+   * - `placeholder`: Placeholder text displayed when the input is empty.
+   *
+   * Use this as a short hint for the expected input. Do not use placeholder text as a replacement for a label.
+   * - `value`: The selected or typed value.
+   *
+   * When an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label.
+   * - `open-on-focus`/`openOnFocus`: Whether the option list opens when the input receives focus.
+   *
+   * Use this when users should see available options before they start typing.
+   * - `select-on-blur`/`selectOnBlur`: Whether the active option is selected when the input loses focus.
+   *
+   * When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur.
+   * - `match-text-segments`/`matchTextSegments`: Whether matching text segments in options are highlighted.
+   *
+   * Use this to visually emphasize the part of each option that matches the current input value.
+   * - `disable-static-filtering`/`disableStaticFiltering`: Whether built-in client-side filtering is disabled.
+   *
+   * Use this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided.
+   * - `invalid`: Whether the combobox is visually invalid.
+   *
+   * Use this to show an externally managed validation error. Pair it with `help-text` to explain how to fix the error.
+   * - `help-text`/`helpText`: Help text displayed below the input.
+   *
+   * Use this for supporting guidance or validation feedback.
+   * - `disabled`: Whether the combobox is disabled.
+   *
+   * Disabled comboboxes cannot be focused, changed, or submitted with form data.
+   * - `required`: Whether the combobox is required before form submission.
+   *
+   * Use this when the user must provide a value before submitting the form.
+   * - `optional`: Whether to show optional text next to the label.
+   *
+   * Use this to indicate that the combobox is not required.
+   * - `name`: The name submitted with the combobox value.
+   *
+   * Use this when the combobox belongs to a form and its value should be included in form data.
+   * - `autocomplete`: The autocomplete attribute passed to the internal input.
+   *
+   * Defaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token.
    *
    * ## Methods
    *