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

package/dist/index.d.ts

@@ -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";
@@ -9,8 +9,11 @@ import type { WarpBadge } from "./packages/badge/badge.ts";
 import type { WarpBox } from "./packages/box/box.ts";
 import type { WarpBreadcrumbs } from "./packages/breadcrumbs/breadcrumbs.ts";
 import type { WarpCard } from "./packages/card/card.ts";
-import type { WCheckbox } from "./packages/checkbox/checkbox.ts";
-import type { WCheckboxGroup } from "./packages/checkbox-group/checkbox-group.ts";
+import type { WarpCheckbox, WCheckbox } from "./packages/checkbox/checkbox.ts";
+import type {
+  WarpCheckboxGroup,
+  WCheckboxGroup,
+} from "./packages/checkbox-group/checkbox-group.ts";
 import type { WarpCombobox } from "./packages/combobox/combobox.ts";
 import type { WarpDatepicker } from "./packages/datepicker/datepicker.ts";
 import type { WarpExpandable } from "./packages/expandable/expandable.ts";
@@ -67,6 +70,15 @@ export type ScopedElements<
   [Key in keyof CustomElements as `${Prefix}${Key}${Suffix}`]: CustomElements[Key];
 };
 
+/**
+ * A generic type for strongly typing custom events with their targets
+ * @template T - The type of the event target (extends EventTarget)
+ * @template D - The type of the detail payload for the custom event
+ */
+type TypedEvent<T extends EventTarget, E = Event> = E & {
+  target: T;
+};
+
 type BaseProps<T extends HTMLElement> = {
   /** Content added between the opening and closing tags of the element */
   children?: any;
@@ -90,6 +102,8 @@ type BaseProps<T extends HTMLElement> = {
   key?: string | number;
   /** Specifies the language of the element. */
   lang?: string;
+  /** Defines the element's semantic role for accessibility APIs. */
+  role?: string;
   /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
   part?: string;
   /** Use the ref attribute with a variable to assign a DOM element to the variable once the element is rendered. */
@@ -112,24 +126,134 @@ type BaseProps<T extends HTMLElement> = {
   popovertargetaction?: "show" | "hide" | "toggle";
 };
 
-type BaseEvents = {};
+type BaseEvents = {
+  // Mouse Events
+
+  /** Triggered when the element is clicked by the user by mouse or keyboard. */
+  onClick?: (event: MouseEvent) => void;
+  /** Fired when the context menu is triggered, often by right-clicking. */
+  onContextMenu?: (event: MouseEvent) => void;
+  /** Fired when the element is double-clicked. */
+  onDoubleClick?: (event: MouseEvent) => void;
+  /** Fired repeatedly as the draggable element is being dragged. */
+  onDrag?: (event: DragEvent) => void;
+  /** Fired when the dragging of a draggable element is finished. */
+  onDragEnd?: (event: DragEvent) => void;
+  /** Fired when a dragged element or text selection enters a valid drop target. */
+  onDragEnter?: (event: DragEvent) => void;
+  /** Fired when a dragged element or text selection leaves a valid drop target. */
+  onDragExit?: (event: DragEvent) => void;
+  /** Fired when a dragged element or text selection leaves a valid drop target. */
+  onDragLeave?: (event: DragEvent) => void;
+  /** Fired when an element or text selection is being dragged over a valid drop target (every few hundred milliseconds). */
+  onDragOver?: (event: DragEvent) => void;
+  /** Fired when a draggable element starts being dragged. */
+  onDragStart?: (event: DragEvent) => void;
+  /** Fired when a dragged element is dropped onto a drop target. */
+  onDrop?: (event: DragEvent) => void;
+  /** Fired when a mouse button is pressed down on the element. */
+  onMouseDown?: (event: MouseEvent) => void;
+  /** Fired when the mouse cursor enters the element. */
+  onMouseEnter?: (event: MouseEvent) => void;
+  /** Triggered when the mouse cursor leaves the element. */
+  onMouseLeave?: (event: MouseEvent) => void;
+  /** Fired at an element when a pointing device (usually a mouse) is moved while the cursor's hotspot is inside it. */
+  onMouseMove?: (event: MouseEvent) => void;
+  /** Fired at an Element when a pointing device (usually a mouse) is used to move the cursor so that it is no longer contained within the element or one of its children. */
+  onMouseOut?: (event: MouseEvent) => void;
+  /** Fired at an Element when a pointing device (such as a mouse or trackpad) is used to move the cursor onto the element or one of its child elements. */
+  onMouseOver?: (event: MouseEvent) => void;
+  /** Fired when a mouse button is released on the element. */
+  onMouseUp?: (event: MouseEvent) => void;
+
+  // Keyboard Events
+
+  /** Fired when a key is pressed down. */
+  onKeyDown?: (event: KeyboardEvent) => void;
+  /** Fired when a key is released.. */
+  onKeyUp?: (event: KeyboardEvent) => void;
+  /** Fired when a key is pressed down. */
+  onKeyPressed?: (event: KeyboardEvent) => void;
+
+  // Focus Events
+
+  /** Fired when the element receives focus, often triggered by tab navigation. */
+  onFocus?: (event: FocusEvent) => void;
+  /** Fired when the element loses focus. */
+  onBlur?: (event: FocusEvent) => void;
+
+  // Form Events
+
+  /** Fired when the value of an input element changes, such as with text inputs or select elements. */
+  onChange?: (event: Event) => void;
+  /** Fires when the value of an <input>, <select>, or <textarea> element has been changed. */
+  onInput?: (event: Event) => void;
+  /** Fired when a form is submitted, usually on pressing Enter in a text input. */
+  onSubmit?: (event: Event) => void;
+  /** Fired when a form is reset. */
+  onReset?: (event: Event) => void;
+
+  // UI Events
+
+  /** Fired when the content of an element is scrolled. */
+  onScroll?: (event: UIEvent) => void;
+
+  // Wheel Events
+
+  /** Fired when the mouse wheel is scrolled while the element is focused. */
+  onWheel?: (event: WheelEvent) => void;
+
+  // Animation Events
+
+  /** Fired when a CSS animation starts. */
+  onAnimationStart?: (event: AnimationEvent) => void;
+  /** Fired when a CSS animation completes. */
+  onAnimationEnd?: (event: AnimationEvent) => void;
+  /** Fired when a CSS animation completes one iteration. */
+  onAnimationIteration?: (event: AnimationEvent) => void;
+
+  // Transition Events
+
+  /** Fired when a CSS transition has completed. */
+  onTransitionEnd?: (event: TransitionEvent) => void;
+
+  // Media Events
+
+  /** Fired when an element (usually an image) finishes loading */
+  onLoad?: (event: Event) => void;
+  /** Fired when an error occurs during the loading of an element, like an image not being found. */
+  onError?: (event: Event) => void;
+
+  // Clipboard Events
+
+  /** Fires when the user initiates a copy action through the browser's user interface. */
+  onCopy?: (event: ClipboardEvent) => void;
+  /** Fired when the user has initiated a "cut" action through the browser's user interface. */
+  onCut?: (event: ClipboardEvent) => void;
+  /** Fired when the user has initiated a "paste" action through the browser's user interface. */
+  onPaste?: (event: ClipboardEvent) => void;
+};
 
-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 +467,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 +855,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"];
@@ -749,47 +893,78 @@ export type WarpCardSolidJsProps = {
   textContent?: string | number;
 };
 
-export type WCheckboxProps = {
-  /** The name of the checkbox, submitted as a name/value pair with form data. */
-  name?: WCheckbox["name"];
-  /** The value of the checkbox, submitted as a name/value pair with form data. */
-  value?: WCheckbox["value"];
-  /** Draws the checkbox in an indeterminate state. */
-  indeterminate?: WCheckbox["indeterminate"];
-  /** Draws the checkbox in a checked state (reflected to attribute). */
-  checked?: WCheckbox["checked"];
-  /** Disables the checkbox. */
-  disabled?: WCheckbox["disabled"];
-  /** Makes the checkbox a required field. */
-  required?: WCheckbox["required"];
-  /** Draws the checkbox in an invalid state. */
-  invalid?: WCheckbox["invalid"];
+/** `WarpCheckbox` component event */
+export type WarpCheckboxElementEvent<E = Event> = TypedEvent<WarpCheckbox, E>;
+
+export type WarpCheckboxProps = {
+  /** 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?: WarpCheckbox["name"];
+  /** 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?: WarpCheckbox["value"];
+  /** 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?: WarpCheckbox["indeterminate"];
+  /** Whether the checkbox is checked.
+
+Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute. */
+  checked?: WarpCheckbox["checked"];
+  /** Whether the checkbox is disabled.
+
+Disabled checkboxes cannot be focused, changed, or submitted with form data. */
+  disabled?: WarpCheckbox["disabled"];
+  /** 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?: WarpCheckbox["required"];
+  /** 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?: WarpCheckbox["invalid"];
   /**  */
-  input?: WCheckbox["input"];
+  input?: WarpCheckbox["input"];
 
   /**  */
-  onchange?: (e: Event) => void;
-};
-
-export type WCheckboxSolidJsProps = {
-  /** The name of the checkbox, submitted as a name/value pair with form data. */
-  "prop:name"?: WCheckbox["name"];
-  /** The value of the checkbox, submitted as a name/value pair with form data. */
-  "prop:value"?: WCheckbox["value"];
-  /** Draws the checkbox in an indeterminate state. */
-  "prop:indeterminate"?: WCheckbox["indeterminate"];
-  /** Draws the checkbox in a checked state (reflected to attribute). */
-  "prop:checked"?: WCheckbox["checked"];
-  /** Disables the checkbox. */
-  "prop:disabled"?: WCheckbox["disabled"];
-  /** Makes the checkbox a required field. */
-  "prop:required"?: WCheckbox["required"];
-  /** Draws the checkbox in an invalid state. */
-  "prop:invalid"?: WCheckbox["invalid"];
+  onchange?: (e: WarpCheckboxElementEvent) => void;
+};
+
+export type WarpCheckboxSolidJsProps = {
+  /** 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"?: WarpCheckbox["name"];
+  /** 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"?: WarpCheckbox["value"];
+  /** 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"?: WarpCheckbox["indeterminate"];
+  /** Whether the checkbox is checked.
+
+Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute. */
+  "prop:checked"?: WarpCheckbox["checked"];
+  /** Whether the checkbox is disabled.
+
+Disabled checkboxes cannot be focused, changed, or submitted with form data. */
+  "prop:disabled"?: WarpCheckbox["disabled"];
+  /** 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"?: WarpCheckbox["required"];
+  /** 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"?: WarpCheckbox["invalid"];
   /**  */
-  "prop:input"?: WCheckbox["input"];
+  "prop:input"?: WarpCheckbox["input"];
   /**  */
-  "on:change"?: (e: Event) => void;
+  "on:change"?: (e: WarpCheckboxElementEvent) => void;
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -797,38 +972,66 @@ export type WCheckboxSolidJsProps = {
   textContent?: string | number;
 };
 
-export type WCheckboxGroupProps = {
-  /** The group label displayed above the checkboxes. */
-  label?: WCheckboxGroup["label"];
-  /** The name applied to child checkboxes when they do not provide one. */
-  name?: WCheckboxGroup["name"];
-  /** Whether to show optional text next to the label. */
-  optional?: WCheckboxGroup["optional"];
-  /**  */
-  "help-text"?: WCheckboxGroup["helpText"];
-  /**  */
-  helpText?: WCheckboxGroup["helpText"];
-  /** Makes the checkbox group required. */
-  required?: WCheckboxGroup["required"];
-  /** Marks the checkbox group as invalid. */
-  invalid?: WCheckboxGroup["invalid"];
-};
-
-export type WCheckboxGroupSolidJsProps = {
-  /** The group label displayed above the checkboxes. */
-  "prop:label"?: WCheckboxGroup["label"];
-  /** The name applied to child checkboxes when they do not provide one. */
-  "prop:name"?: WCheckboxGroup["name"];
-  /** Whether to show optional text next to the label. */
-  "prop:optional"?: WCheckboxGroup["optional"];
-  /**  */
-  "attr:help-text"?: WCheckboxGroup["helpText"];
-  /**  */
-  "prop:helpText"?: WCheckboxGroup["helpText"];
-  /** Makes the checkbox group required. */
-  "prop:required"?: WCheckboxGroup["required"];
-  /** Marks the checkbox group as invalid. */
-  "prop:invalid"?: WCheckboxGroup["invalid"];
+export type WarpCheckboxGroupProps = {
+  /** 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?: WarpCheckboxGroup["label"];
+  /** 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?: WarpCheckboxGroup["name"];
+  /** Whether to show optional text next to the label.
+
+Use this to indicate that selecting an option from the group is not required. */
+  optional?: WarpCheckboxGroup["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"?: WarpCheckboxGroup["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?: WarpCheckboxGroup["helpText"];
+  /** 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?: WarpCheckboxGroup["required"];
+  /** 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?: WarpCheckboxGroup["invalid"];
+};
+
+export type WarpCheckboxGroupSolidJsProps = {
+  /** 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"?: WarpCheckboxGroup["label"];
+  /** 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"?: WarpCheckboxGroup["name"];
+  /** 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"?: WarpCheckboxGroup["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"?: WarpCheckboxGroup["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"?: WarpCheckboxGroup["helpText"];
+  /** 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"?: WarpCheckboxGroup["required"];
+  /** 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"?: WarpCheckboxGroup["invalid"];
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -837,88 +1040,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 */
@@ -928,41 +1211,49 @@ export type WarpComboboxSolidJsProps = {
 };
 
 export type WarpDatepickerProps = {
-  /**  */
+  /** The label displayed above the date input.
+
+Use this to give the datepicker a visible and accessible name. */
   label?: WarpDatepicker["label"];
-  /** Takes precedence over the `<html>` lang attribute. */
+  /** The locale used for calendar labels and date formatting.
+
+This takes precedence over the `<html>` `lang` attribute. Supported built-in locales are `en`, `nb`, `sv`, `da`, and `fi`. */
   lang?: WarpDatepicker["lang"];
-  /**  */
+  /** The name submitted with the date value.
+
+Use this when the datepicker belongs to a form and its value should be included in form data. */
   name?: WarpDatepicker["name"];
-  /**  */
+  /** The selected date value.
+
+Use an ISO date string in `YYYY-MM-DD` format. The value is submitted with the form and is reset to its initial value when the form resets. */
   value?: WarpDatepicker["value"];
-  /** Decides the format of the date as shown in the calendar header.
+  /** The date format used in the calendar header.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   "header-format"?: WarpDatepicker["headerFormat"];
-  /** Decides the format of the date as shown in the calendar header.
+  /** The date format used in the calendar header.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   headerFormat?: WarpDatepicker["headerFormat"];
-  /** Decides the format of the weekday as shown above the grid of dates in the calendar.
+  /** The weekday format shown above the calendar grid.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   "weekday-format"?: WarpDatepicker["weekdayFormat"];
-  /** Decides the format of the weekday as shown above the grid of dates in the calendar.
+  /** The weekday format shown above the calendar grid.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   weekdayFormat?: WarpDatepicker["weekdayFormat"];
-  /** Decides the format of the day in the calendar as read to screen readers.
+  /** The date format used for calendar day accessible names.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   "day-format"?: WarpDatepicker["dayFormat"];
-  /** Decides the format of the day in the calendar as read to screen readers.
+  /** The date format used for calendar day accessible names.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   dayFormat?: WarpDatepicker["dayFormat"];
-  /** Lets you control if a date in the calendar should be disabled.
+  /** Function used to disable dates in the calendar.
 
-This needs to be set on the element instance in JavaScript, not as an HTML attribute. */
+Set this on the element instance in JavaScript, not as an HTML attribute. Disabled dates cannot be selected from the calendar. */
   isDayDisabled?: WarpDatepicker["isDayDisabled"];
   /**  */
   isCalendarOpen?: WarpDatepicker["isCalendarOpen"];
@@ -989,41 +1280,49 @@ the query will point to an element that doesn't exist anymore. */
 };
 
 export type WarpDatepickerSolidJsProps = {
-  /**  */
+  /** The label displayed above the date input.
+
+Use this to give the datepicker a visible and accessible name. */
   "prop:label"?: WarpDatepicker["label"];
-  /** Takes precedence over the `<html>` lang attribute. */
+  /** The locale used for calendar labels and date formatting.
+
+This takes precedence over the `<html>` `lang` attribute. Supported built-in locales are `en`, `nb`, `sv`, `da`, and `fi`. */
   "prop:lang"?: WarpDatepicker["lang"];
-  /**  */
+  /** The name submitted with the date value.
+
+Use this when the datepicker belongs to a form and its value should be included in form data. */
   "prop:name"?: WarpDatepicker["name"];
-  /**  */
+  /** The selected date value.
+
+Use an ISO date string in `YYYY-MM-DD` format. The value is submitted with the form and is reset to its initial value when the form resets. */
   "prop:value"?: WarpDatepicker["value"];
-  /** Decides the format of the date as shown in the calendar header.
+  /** The date format used in the calendar header.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   "attr:header-format"?: WarpDatepicker["headerFormat"];
-  /** Decides the format of the date as shown in the calendar header.
+  /** The date format used in the calendar header.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   "prop:headerFormat"?: WarpDatepicker["headerFormat"];
-  /** Decides the format of the weekday as shown above the grid of dates in the calendar.
+  /** The weekday format shown above the calendar grid.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   "attr:weekday-format"?: WarpDatepicker["weekdayFormat"];
-  /** Decides the format of the weekday as shown above the grid of dates in the calendar.
+  /** The weekday format shown above the calendar grid.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   "prop:weekdayFormat"?: WarpDatepicker["weekdayFormat"];
-  /** Decides the format of the day in the calendar as read to screen readers.
+  /** The date format used for calendar day accessible names.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   "attr:day-format"?: WarpDatepicker["dayFormat"];
-  /** Decides the format of the day in the calendar as read to screen readers.
+  /** The date format used for calendar day accessible names.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format). */
   "prop:dayFormat"?: WarpDatepicker["dayFormat"];
-  /** Lets you control if a date in the calendar should be disabled.
+  /** Function used to disable dates in the calendar.
 
-This needs to be set on the element instance in JavaScript, not as an HTML attribute. */
+Set this on the element instance in JavaScript, not as an HTML attribute. Disabled dates cannot be selected from the calendar. */
   "prop:isDayDisabled"?: WarpDatepicker["isDayDisabled"];
   /**  */
   "prop:isCalendarOpen"?: WarpDatepicker["isCalendarOpen"];
@@ -1055,31 +1354,31 @@ the query will point to an element that doesn't exist anymore. */
 };
 
 export type WarpExpandableProps = {
-  /**  */
+  /** Controls component's expanded state */
   expanded?: WarpExpandable["expanded"];
-  /**  */
+  /** Component title. Used to display the title value which is always present regardless of whether the component is open or closed. */
   title?: WarpExpandable["title"];
-  /**  */
+  /** Will make the expandable a Box */
   box?: WarpExpandable["box"];
-  /**  */
+  /** Will make the expandable full-width on the sm breakpoint size */
   bleed?: WarpExpandable["bleed"];
-  /**  */
+  /** @deprecated Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.  */
   "button-class"?: WarpExpandable["buttonClass"];
-  /**  */
+  /** @deprecated Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.  */
   buttonClass?: WarpExpandable["buttonClass"];
-  /**  */
+  /** @deprecated Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.  */
   "content-class"?: WarpExpandable["contentClass"];
-  /**  */
+  /** @deprecated Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.  */
   contentClass?: WarpExpandable["contentClass"];
-  /**  */
+  /** Controls chevron visibility */
   "no-chevron"?: WarpExpandable["noChevron"];
-  /**  */
+  /** Controls chevron visibility */
   noChevron?: WarpExpandable["noChevron"];
-  /**  */
+  /** Will animate the expansion/collapse */
   animated?: WarpExpandable["animated"];
-  /**  */
+  /** Wrap the toggle button in a heading element with the specified level. If headingLevel is not specified, the button will not be wrapped by a heading element. */
   "heading-level"?: WarpExpandable["headingLevel"];
-  /**  */
+  /** Wrap the toggle button in a heading element with the specified level. If headingLevel is not specified, the button will not be wrapped by a heading element. */
   headingLevel?: WarpExpandable["headingLevel"];
   /**  */
   _hasTitle?: WarpExpandable["_hasTitle"];
@@ -1088,31 +1387,31 @@ export type WarpExpandableProps = {
 };
 
 export type WarpExpandableSolidJsProps = {
-  /**  */
+  /** Controls component's expanded state */
   "prop:expanded"?: WarpExpandable["expanded"];
-  /**  */
+  /** Component title. Used to display the title value which is always present regardless of whether the component is open or closed. */
   "prop:title"?: WarpExpandable["title"];
-  /**  */
+  /** Will make the expandable a Box */
   "prop:box"?: WarpExpandable["box"];
-  /**  */
+  /** Will make the expandable full-width on the sm breakpoint size */
   "prop:bleed"?: WarpExpandable["bleed"];
-  /**  */
+  /** @deprecated Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.  */
   "attr:button-class"?: WarpExpandable["buttonClass"];
-  /**  */
+  /** @deprecated Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.  */
   "prop:buttonClass"?: WarpExpandable["buttonClass"];
-  /**  */
+  /** @deprecated Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.  */
   "attr:content-class"?: WarpExpandable["contentClass"];
-  /**  */
+  /** @deprecated Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.  */
   "prop:contentClass"?: WarpExpandable["contentClass"];
-  /**  */
+  /** Controls chevron visibility */
   "bool:no-chevron"?: WarpExpandable["noChevron"];
-  /**  */
+  /** Controls chevron visibility */
   "prop:noChevron"?: WarpExpandable["noChevron"];
-  /**  */
+  /** Will animate the expansion/collapse */
   "prop:animated"?: WarpExpandable["animated"];
-  /**  */
+  /** Wrap the toggle button in a heading element with the specified level. If headingLevel is not specified, the button will not be wrapped by a heading element. */
   "attr:heading-level"?: WarpExpandable["headingLevel"];
-  /**  */
+  /** Wrap the toggle button in a heading element with the specified level. If headingLevel is not specified, the button will not be wrapped by a heading element. */
   "prop:headingLevel"?: WarpExpandable["headingLevel"];
   /**  */
   "prop:_hasTitle"?: WarpExpandable["_hasTitle"];
@@ -1125,6 +1424,9 @@ export type WarpExpandableSolidJsProps = {
   textContent?: string | number;
 };
 
+/** `WarpModal` component event */
+export type WarpModalElementEvent<E = Event> = TypedEvent<WarpModal, E>;
+
 export type WarpModalProps = {
   /** Controls if the modal should show or hide.
 
@@ -1140,9 +1442,9 @@ You can also call the `open()` and `close()` methods. */
   ignoreBackdropClicks?: WarpModal["ignoreBackdropClicks"];
 
   /**  */
-  onshown?: (e: CustomEvent) => void;
+  onshown?: (e: WarpModalElementEvent) => void;
   /**  */
-  onhidden?: (e: CustomEvent) => void;
+  onhidden?: (e: WarpModalElementEvent) => void;
 };
 
 export type WarpModalSolidJsProps = {
@@ -1159,9 +1461,9 @@ You can also call the `open()` and `close()` methods. */
   /** Ignores clicks to the backdrop when set */
   "prop:ignoreBackdropClicks"?: WarpModal["ignoreBackdropClicks"];
   /**  */
-  "on:shown"?: (e: CustomEvent) => void;
+  "on:shown"?: (e: WarpModalElementEvent) => void;
   /**  */
-  "on:hidden"?: (e: CustomEvent) => void;
+  "on:hidden"?: (e: WarpModalElementEvent) => void;
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -1178,6 +1480,12 @@ export type WarpModalFooterSolidJsProps = {
   textContent?: string | number;
 };
 
+/** `WarpModalHeader` component event */
+export type WarpModalHeaderElementEvent<E = Event> = TypedEvent<
+  WarpModalHeader,
+  E
+>;
+
 export type WarpModalHeaderProps = {
   /** A short but descriptive title for the modal */
   title?: WarpModalHeader["title"];
@@ -1189,7 +1497,7 @@ export type WarpModalHeaderProps = {
   noClose?: WarpModalHeader["noClose"];
 
   /**  */
-  onbackClicked?: (e: CustomEvent) => void;
+  onbackClicked?: (e: WarpModalHeaderElementEvent) => void;
 };
 
 export type WarpModalHeaderSolidJsProps = {
@@ -1202,7 +1510,7 @@ export type WarpModalHeaderSolidJsProps = {
   /** Lets you hide the close button in the header */
   "prop:noClose"?: WarpModalHeader["noClose"];
   /**  */
-  "on:backClicked"?: (e: CustomEvent) => void;
+  "on:backClicked"?: (e: WarpModalHeaderElementEvent) => void;
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -1237,6 +1545,12 @@ export type WarpPageIndicatorSolidJsProps = {
   textContent?: string | number;
 };
 
+/** `WarpPagination` component event */
+export type WarpPaginationElementEvent<E = Event> = TypedEvent<
+  WarpPagination,
+  E
+>;
+
 export type WarpPaginationProps = {
   /** The base URL used to construct page links, for example `/search?page=`.
 
@@ -1258,7 +1572,7 @@ The page number is appended to this URL. */
   visiblePages?: WarpPagination["visiblePages"];
 
   /** Triggered when a link in the pagination is clicked. Contains the page number in `string` form. */
-  "onpage-click"?: (e: CustomEvent) => void;
+  "onpage-click"?: (e: WarpPaginationElementEvent) => void;
 };
 
 export type WarpPaginationSolidJsProps = {
@@ -1281,7 +1595,7 @@ The page number is appended to this URL. */
   /** The maximum number of page numbers visible. */
   "prop:visiblePages"?: WarpPagination["visiblePages"];
   /** Triggered when a link in the pagination is clicked. Contains the page number in `string` form. */
-  "on:page-click"?: (e: CustomEvent) => void;
+  "on:page-click"?: (e: WarpPaginationElementEvent) => void;
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -1289,6 +1603,9 @@ The page number is appended to this URL. */
   textContent?: string | number;
 };
 
+/** `WarpPill` component event */
+export type WarpPillElementEvent<E = Event> = TypedEvent<WarpPill, E>;
+
 export type WarpPillProps = {
   /** Whether the pill should be removable via a close button. */
   "can-close"?: WarpPill["canClose"];
@@ -1314,9 +1631,9 @@ export type WarpPillProps = {
   closeAriaLabel?: WarpPill["closeAriaLabel"];
 
   /** Fires when the pill itself is clicked. */
-  "onw-pill-click"?: (e: CustomEvent) => void;
+  "onw-pill-click"?: (e: WarpPillElementEvent) => void;
   /** Fires when the pill's close button is clicked. */
-  "onw-pill-close"?: (e: CustomEvent) => void;
+  "onw-pill-close"?: (e: WarpPillElementEvent) => void;
 };
 
 export type WarpPillSolidJsProps = {
@@ -1343,9 +1660,9 @@ export type WarpPillSolidJsProps = {
   /** Label read by screen readers when targeting the close button. */
   "prop:closeAriaLabel"?: WarpPill["closeAriaLabel"];
   /** Fires when the pill itself is clicked. */
-  "on:w-pill-click"?: (e: CustomEvent) => void;
+  "on:w-pill-click"?: (e: WarpPillElementEvent) => void;
   /** Fires when the pill's close button is clicked. */
-  "on:w-pill-close"?: (e: CustomEvent) => void;
+  "on:w-pill-close"?: (e: WarpPillElementEvent) => void;
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -1439,6 +1756,9 @@ If you set `required` and `invalid` the group gets a default error message, but
   textContent?: string | number;
 };
 
+/** `WarpSelect` component event */
+export type WarpSelectElementEvent<E = Event> = TypedEvent<WarpSelect, E>;
+
 export type WarpSelectProps = {
   /** @deprecated Use the native `autofocus` attribute instead. - Whether the element should receive focus on render. */
   "auto-focus"?: WarpSelect["autoFocus"];
@@ -1480,7 +1800,7 @@ Paired with `help-text` to provide feedback about the error. */
   value?: WarpSelect["value"];
 
   /**  */
-  onchange?: (e: CustomEvent) => void;
+  onchange?: (e: WarpSelectElementEvent) => void;
 };
 
 export type WarpSelectSolidJsProps = {
@@ -1523,7 +1843,7 @@ Paired with `help-text` to provide feedback about the error. */
   /** Lets you set the current value. */
   "prop:value"?: WarpSelect["value"];
   /**  */
-  "on:change"?: (e: CustomEvent) => void;
+  "on:change"?: (e: WarpSelectElementEvent) => void;
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -1531,6 +1851,12 @@ Paired with `help-text` to provide feedback about the error. */
   textContent?: string | number;
 };
 
+/** `WarpSliderThumb` component event */
+export type WarpSliderThumbElementEvent<E = Event> = TypedEvent<
+  WarpSliderThumb,
+  E
+>;
+
 export type WarpSliderThumbProps = {
   /** Label for the range input. */
   "aria-label"?: WarpSliderThumb["ariaLabel"];
@@ -1548,9 +1874,9 @@ export type WarpSliderThumbProps = {
   placeholder?: WarpSliderThumb["placeholder"];
 
   /** Internal event used by (and stopped by) `w-slider`. */
-  onthumbreset?: (e: CustomEvent) => void;
+  onthumbreset?: (e: WarpSliderThumbElementEvent) => void;
   /** Internal event used by (and stopped by) `w-slider`. */
-  onslidervalidity?: (e: CustomEvent) => void;
+  onslidervalidity?: (e: WarpSliderThumbElementEvent) => void;
 };
 
 export type WarpSliderThumbSolidJsProps = {
@@ -1569,9 +1895,9 @@ export type WarpSliderThumbSolidJsProps = {
   /** Placeholder in empty text fields */
   "prop:placeholder"?: WarpSliderThumb["placeholder"];
   /** Internal event used by (and stopped by) `w-slider`. */
-  "on:thumbreset"?: (e: CustomEvent) => void;
+  "on:thumbreset"?: (e: WarpSliderThumbElementEvent) => void;
   /** Internal event used by (and stopped by) `w-slider`. */
-  "on:slidervalidity"?: (e: CustomEvent) => void;
+  "on:slidervalidity"?: (e: WarpSliderThumbElementEvent) => void;
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -1720,6 +2046,12 @@ export type WarpStepIndicatorSolidJsProps = {
   textContent?: string | number;
 };
 
+/** `WarpSwitch` component event */
+export type WarpSwitchElementEvent<E = Event> = TypedEvent<WarpSwitch, E>;
+/** `change` event type */
+export type WarpSwitchChangeElementEvent =
+  WarpSwitchElementEvent<WarpSwitchChangeEvent>;
+
 export type WarpSwitchProps = {
   /** Name used when submitting an HTML form. */
   name?: WarpSwitch["name"];
@@ -1733,7 +2065,7 @@ The component reports `null` as the value in the `change` event when `value` is
   disabled?: WarpSwitch["disabled"];
 
   /** Dispatched when the switch toggles. Includes boolean `checked` and string/null `value` on `details`. */
-  onchange?: (e: WarpSwitchChangeEvent) => void;
+  onchange?: (e: WarpSwitchChangeElementEvent) => void;
 };
 
 export type WarpSwitchSolidJsProps = {
@@ -1748,7 +2080,7 @@ The component reports `null` as the value in the `change` event when `value` is
   /** Whether the switch is disabled. */
   "prop:disabled"?: WarpSwitch["disabled"];
   /** Dispatched when the switch toggles. Includes boolean `checked` and string/null `value` on `details`. */
-  "on:change"?: (e: WarpSwitchChangeEvent) => void;
+  "on:change"?: (e: WarpSwitchChangeElementEvent) => void;
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -1790,19 +2122,25 @@ export type WarpTabPanelSolidJsProps = {
   textContent?: string | number;
 };
 
+/** `WarpTabs` component event */
+export type WarpTabsElementEvent<E = Event> = TypedEvent<WarpTabs, E>;
+/** `change` event type */
+export type WarpTabsChangeElementEvent =
+  WarpTabsElementEvent<WarpTabsChangeEvent>;
+
 export type WarpTabsProps = {
   /** The `id` of the panel that should be active. */
   active?: WarpTabs["active"];
 
   /** Includes `details.panelId` with the now active tab's ID */
-  onchange?: (e: WarpTabsChangeEvent) => void;
+  onchange?: (e: WarpTabsChangeElementEvent) => void;
 };
 
 export type WarpTabsSolidJsProps = {
   /** The `id` of the panel that should be active. */
   "prop:active"?: WarpTabs["active"];
   /** Includes `details.panelId` with the now active tab's ID */
-  "on:change"?: (e: WarpTabsChangeEvent) => void;
+  "on:change"?: (e: WarpTabsChangeElementEvent) => void;
 
   /** Set the innerHTML of the element */
   innerHTML?: string;
@@ -1918,10 +2256,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 +2372,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 +2563,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 +2589,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)
@@ -2268,7 +2632,9 @@ export type CustomElements = {
    * - `checkValidity() => boolean`: Checks whether the checkbox passes constraint validation
    * - `reportValidity() => boolean`: Checks validity and shows the browser's validation message if invalid
    */
-  "w-checkbox": Partial<WCheckboxProps & BaseProps<WCheckbox> & BaseEvents>;
+  "w-checkbox": Partial<
+    WarpCheckboxProps & BaseProps<WarpCheckbox> & BaseEvents
+  >;
 
   /**
    *
@@ -2278,11 +2644,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
    *
@@ -2293,7 +2671,7 @@ export type CustomElements = {
    * - `focus(options?: FocusOptions) => void`: Sets focus on the checkbox group.
    */
   "w-checkbox-group": Partial<
-    WCheckboxGroupProps & BaseProps<WCheckboxGroup> & BaseEvents
+    WarpCheckboxGroupProps & BaseProps<WarpCheckboxGroup> & BaseEvents
   >;
 
   /**
@@ -2305,21 +2683,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
    *
@@ -2342,22 +2750,30 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `label`: undefined
-   * - `lang`: Takes precedence over the `<html>` lang attribute.
-   * - `name`: undefined
-   * - `value`: undefined
-   * - `header-format`/`headerFormat`: Decides the format of the date as shown in the calendar header.
+   * - `label`: The label displayed above the date input.
+   *
+   * Use this to give the datepicker a visible and accessible name.
+   * - `lang`: The locale used for calendar labels and date formatting.
+   *
+   * This takes precedence over the `<html>` `lang` attribute. Supported built-in locales are `en`, `nb`, `sv`, `da`, and `fi`.
+   * - `name`: The name submitted with the date value.
+   *
+   * Use this when the datepicker belongs to a form and its value should be included in form data.
+   * - `value`: The selected date value.
+   *
+   * Use an ISO date string in `YYYY-MM-DD` format. The value is submitted with the form and is reset to its initial value when the form resets.
+   * - `header-format`/`headerFormat`: The date format used in the calendar header.
    *
    * The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
-   * - `weekday-format`/`weekdayFormat`: Decides the format of the weekday as shown above the grid of dates in the calendar.
+   * - `weekday-format`/`weekdayFormat`: The weekday format shown above the calendar grid.
    *
    * The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
-   * - `day-format`/`dayFormat`: Decides the format of the day in the calendar as read to screen readers.
+   * - `day-format`/`dayFormat`: The date format used for calendar day accessible names.
    *
    * The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
-   * - `isDayDisabled`: Lets you control if a date in the calendar should be disabled.
+   * - `isDayDisabled`: Function used to disable dates in the calendar.
    *
-   * This needs to be set on the element instance in JavaScript, not as an HTML attribute. (property only)
+   * Set this on the element instance in JavaScript, not as an HTML attribute. Disabled dates cannot be selected from the calendar. (property only)
    * - `isCalendarOpen`: undefined (property only)
    * - `navigationDate`: undefined (property only)
    * - `selectedDate`: undefined (property only) (readonly)
@@ -2388,21 +2804,19 @@ export type CustomElements = {
   /**
    * Expandable is a layout component used for creating expandable content areas on a page.
    *
-   * [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/layout-expandable--docs)
-   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `expanded`: undefined
-   * - `title`: undefined
-   * - `box`: undefined
-   * - `bleed`: undefined
+   * - `expanded`: Controls component's expanded state
+   * - `title`: Component title. Used to display the title value which is always present regardless of whether the component is open or closed.
+   * - `box`: Will make the expandable a Box
+   * - `bleed`: Will make the expandable full-width on the sm breakpoint size
    * - `button-class`/`buttonClass`: undefined
    * - `content-class`/`contentClass`: undefined
-   * - `no-chevron`/`noChevron`: undefined
-   * - `animated`: undefined
-   * - `heading-level`/`headingLevel`: undefined
+   * - `no-chevron`/`noChevron`: Controls chevron visibility
+   * - `animated`: Will animate the expansion/collapse
+   * - `heading-level`/`headingLevel`: Wrap the toggle button in a heading element with the specified level. If headingLevel is not specified, the button will not be wrapped by a heading element.
    * - `_hasTitle`: undefined
    * - `_showChevronUp`: undefined
    *
@@ -2861,6 +3275,106 @@ export type CustomElements = {
   >;
 };
 
+type ReactElementProps<T extends HTMLElement> = import("react").DOMAttributes<T> &
+  import("react").AriaAttributes &
+  import("react").RefAttributes<T> &
+  Pick<
+    import("react").HTMLAttributes<T>,
+    | "className"
+    | "style"
+    | "suppressContentEditableWarning"
+    | "suppressHydrationWarning"
+  >;
+
+// Merge order matters: component props must win over React/global/base props
+// when names collide, e.g. w-attention's boolean popover prop.
+type ReactCustomElementProps<T extends HTMLElement, Props> = Omit<
+  BaseProps<T> & BaseEvents,
+  keyof ReactElementProps<T> | keyof Props
+> &
+  Omit<ReactElementProps<T>, keyof Props> &
+  Props;
+
+type CustomElementInstances = {
+  "w-icon": WarpIcon;
+  "w-textfield": WarpTextField;
+  "w-affix": WarpAffix;
+  "w-alert": WarpAlert;
+  "w-link": WarpLink;
+  "w-button": WarpButton;
+  "w-attention": WarpAttention;
+  "w-badge": WarpBadge;
+  "w-box": WarpBox;
+  "w-breadcrumbs": WarpBreadcrumbs;
+  "w-card": WarpCard;
+  "w-checkbox": WarpCheckbox;
+  "w-checkbox-group": WarpCheckboxGroup;
+  "w-combobox": WarpCombobox;
+  "w-datepicker": WarpDatepicker;
+  "w-expandable": WarpExpandable;
+  "w-modal": WarpModal;
+  "w-modal-footer": WarpModalFooter;
+  "w-modal-header": WarpModalHeader;
+  "w-page-indicator": WarpPageIndicator;
+  "w-pagination": WarpPagination;
+  "w-pill": WarpPill;
+  "w-radio": WarpRadio;
+  "w-radio-group": WarpRadioGroup;
+  "w-select": WarpSelect;
+  "w-slider-thumb": WarpSliderThumb;
+  "w-slider": WarpSlider;
+  "w-step": WarpStep;
+  "w-step-indicator": WarpStepIndicator;
+  "w-switch": WarpSwitch;
+  "w-tab": WarpTab;
+  "w-tab-panel": WarpTabPanel;
+  "w-tabs": WarpTabs;
+  "w-textarea": WarpTextarea;
+};
+
+type CustomElementComponentProps = {
+  "w-icon": WarpIconProps;
+  "w-textfield": WarpTextFieldProps;
+  "w-affix": WarpAffixProps;
+  "w-alert": WarpAlertProps;
+  "w-link": WarpLinkProps;
+  "w-button": WarpButtonProps;
+  "w-attention": WarpAttentionProps;
+  "w-badge": WarpBadgeProps;
+  "w-box": WarpBoxProps;
+  "w-breadcrumbs": WarpBreadcrumbsProps;
+  "w-card": WarpCardProps;
+  "w-checkbox": WarpCheckboxProps;
+  "w-checkbox-group": WarpCheckboxGroupProps;
+  "w-combobox": WarpComboboxProps;
+  "w-datepicker": WarpDatepickerProps;
+  "w-expandable": WarpExpandableProps;
+  "w-modal": WarpModalProps;
+  "w-modal-footer": WarpModalFooterProps;
+  "w-modal-header": WarpModalHeaderProps;
+  "w-page-indicator": WarpPageIndicatorProps;
+  "w-pagination": WarpPaginationProps;
+  "w-pill": WarpPillProps;
+  "w-radio": WarpRadioProps;
+  "w-radio-group": WarpRadioGroupProps;
+  "w-select": WarpSelectProps;
+  "w-slider-thumb": WarpSliderThumbProps;
+  "w-slider": WarpSliderProps;
+  "w-step": WarpStepProps;
+  "w-step-indicator": WarpStepIndicatorProps;
+  "w-switch": WarpSwitchProps;
+  "w-tab": WarpTabProps;
+  "w-tab-panel": WarpTabPanelProps;
+  "w-tabs": WarpTabsProps;
+  "w-textarea": WarpTextareaProps;
+};
+
+export type ReactCustomElements = {
+  [Tag in keyof CustomElementComponentProps]: Tag extends keyof CustomElementInstances
+    ? Partial<ReactCustomElementProps<CustomElementInstances[Tag], CustomElementComponentProps[Tag]>>
+    : never;
+};
+
 export type CustomElementsSolidJs = {
   /**
    *
@@ -2870,11 +3384,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 +3509,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 +3717,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 +3745,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)
@@ -3249,7 +3789,10 @@ export type CustomElementsSolidJs = {
    * - `reportValidity() => boolean`: Checks validity and shows the browser's validation message if invalid
    */
   "w-checkbox": Partial<
-    WCheckboxProps & WCheckboxSolidJsProps & BaseProps<WCheckbox> & BaseEvents
+    WarpCheckboxProps &
+      WarpCheckboxSolidJsProps &
+      BaseProps<WarpCheckbox> &
+      BaseEvents
   >;
 
   /**
@@ -3260,11 +3803,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
    *
@@ -3275,9 +3830,9 @@ export type CustomElementsSolidJs = {
    * - `focus(options?: FocusOptions) => void`: Sets focus on the checkbox group.
    */
   "w-checkbox-group": Partial<
-    WCheckboxGroupProps &
-      WCheckboxGroupSolidJsProps &
-      BaseProps<WCheckboxGroup> &
+    WarpCheckboxGroupProps &
+      WarpCheckboxGroupSolidJsProps &
+      BaseProps<WarpCheckboxGroup> &
       BaseEvents
   >;
 
@@ -3290,21 +3845,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
    *
@@ -3330,22 +3915,30 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `label`: undefined
-   * - `lang`: Takes precedence over the `<html>` lang attribute.
-   * - `name`: undefined
-   * - `value`: undefined
-   * - `header-format`/`headerFormat`: Decides the format of the date as shown in the calendar header.
+   * - `label`: The label displayed above the date input.
+   *
+   * Use this to give the datepicker a visible and accessible name.
+   * - `lang`: The locale used for calendar labels and date formatting.
+   *
+   * This takes precedence over the `<html>` `lang` attribute. Supported built-in locales are `en`, `nb`, `sv`, `da`, and `fi`.
+   * - `name`: The name submitted with the date value.
+   *
+   * Use this when the datepicker belongs to a form and its value should be included in form data.
+   * - `value`: The selected date value.
+   *
+   * Use an ISO date string in `YYYY-MM-DD` format. The value is submitted with the form and is reset to its initial value when the form resets.
+   * - `header-format`/`headerFormat`: The date format used in the calendar header.
    *
    * The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
-   * - `weekday-format`/`weekdayFormat`: Decides the format of the weekday as shown above the grid of dates in the calendar.
+   * - `weekday-format`/`weekdayFormat`: The weekday format shown above the calendar grid.
    *
    * The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
-   * - `day-format`/`dayFormat`: Decides the format of the day in the calendar as read to screen readers.
+   * - `day-format`/`dayFormat`: The date format used for calendar day accessible names.
    *
    * The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
-   * - `isDayDisabled`: Lets you control if a date in the calendar should be disabled.
+   * - `isDayDisabled`: Function used to disable dates in the calendar.
    *
-   * This needs to be set on the element instance in JavaScript, not as an HTML attribute. (property only)
+   * Set this on the element instance in JavaScript, not as an HTML attribute. Disabled dates cannot be selected from the calendar. (property only)
    * - `isCalendarOpen`: undefined (property only)
    * - `navigationDate`: undefined (property only)
    * - `selectedDate`: undefined (property only) (readonly)
@@ -3379,21 +3972,19 @@ export type CustomElementsSolidJs = {
   /**
    * Expandable is a layout component used for creating expandable content areas on a page.
    *
-   * [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/layout-expandable--docs)
-   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `expanded`: undefined
-   * - `title`: undefined
-   * - `box`: undefined
-   * - `bleed`: undefined
+   * - `expanded`: Controls component's expanded state
+   * - `title`: Component title. Used to display the title value which is always present regardless of whether the component is open or closed.
+   * - `box`: Will make the expandable a Box
+   * - `bleed`: Will make the expandable full-width on the sm breakpoint size
    * - `button-class`/`buttonClass`: undefined
    * - `content-class`/`contentClass`: undefined
-   * - `no-chevron`/`noChevron`: undefined
-   * - `animated`: undefined
-   * - `heading-level`/`headingLevel`: undefined
+   * - `no-chevron`/`noChevron`: Controls chevron visibility
+   * - `animated`: Will animate the expansion/collapse
+   * - `heading-level`/`headingLevel`: Wrap the toggle button in a heading element with the specified level. If headingLevel is not specified, the button will not be wrapped by a heading element.
    * - `_hasTitle`: undefined
    * - `_showChevronUp`: undefined
    *
@@ -3913,7 +4504,7 @@ export type CustomCssProperties = {};
 
 declare module "react" {
   namespace JSX {
-    interface IntrinsicElements extends CustomElements {}
+    interface IntrinsicElements extends ReactCustomElements {}
   }
   export interface CSSProperties extends CustomCssProperties {}
 }