@helixui/library 0.3.2 → 0.3.4

package/custom-elements.json

@@ -1852,221 +1852,298 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/hx-button/hx-button.ts",
+      "path": "src/components/hx-breadcrumb/hx-breadcrumb-item.ts",
       "declarations": [
         {
           "kind": "class",
-          "description": "A production-grade button component for user interaction. Supports multiple\nvisual variants, sizes, loading state, prefix/suffix slots, anchor rendering,\nand full ElementInternals form association.",
-          "name": "HelixButton",
+          "description": "A single breadcrumb navigation item.",
+          "name": "HelixBreadcrumbItem",
           "cssProperties": [
             {
-              "description": "Button background color.",
-              "name": "--hx-button-bg",
-              "default": "var(--hx-color-primary-500)"
+              "description": "Link text color.",
+              "name": "--hx-breadcrumb-link-color",
+              "default": "var(--hx-color-primary-600)"
             },
             {
-              "description": "Button text color.",
-              "name": "--hx-button-color",
-              "default": "var(--hx-color-neutral-0)"
+              "description": "Link hover text color.",
+              "name": "--hx-breadcrumb-link-hover-color",
+              "default": "var(--hx-color-primary-700)"
             },
             {
-              "description": "Button border color.",
-              "name": "--hx-button-border-color",
-              "default": "transparent"
+              "description": "Current page text color.",
+              "name": "--hx-breadcrumb-text-color",
+              "default": "var(--hx-color-neutral-700)"
             },
             {
-              "description": "Button border radius.",
-              "name": "--hx-button-border-radius",
-              "default": "var(--hx-border-radius-md)"
+              "description": "Separator character displayed after non-last items.",
+              "name": "--hx-breadcrumb-separator-content",
+              "default": "'/'"
             },
             {
-              "description": "Button font family.",
-              "name": "--hx-button-font-family",
-              "default": "var(--hx-font-family-sans)"
+              "description": "Separator color.",
+              "name": "--hx-breadcrumb-separator-color",
+              "default": "var(--hx-color-neutral-400)"
             },
             {
-              "description": "Button font weight.",
-              "name": "--hx-button-font-weight",
-              "default": "var(--hx-font-weight-semibold)"
+              "description": "Horizontal margin around separator.",
+              "name": "--hx-breadcrumb-separator-gap",
+              "default": "var(--hx-space-1)"
             },
             {
-              "description": "Focus ring color.",
-              "name": "--hx-button-focus-ring-color",
-              "default": "var(--hx-focus-ring-color)"
+              "description": "Optional max-width for text truncation.",
+              "name": "--hx-breadcrumb-item-max-width"
             }
           ],
           "cssParts": [
             {
-              "description": "The native button or anchor element.",
-              "name": "button"
-            },
-            {
-              "description": "The label text wrapper span.",
-              "name": "label"
+              "description": "Wrapper around the link or text content.",
+              "name": "item"
             },
             {
-              "description": "The prefix slot container span.",
-              "name": "prefix"
+              "description": "The anchor element when href is provided (non-current items only).",
+              "name": "link"
             },
             {
-              "description": "The suffix slot container span.",
-              "name": "suffix"
+              "description": "The span element for the current page or items without href.",
+              "name": "text"
             },
             {
-              "description": "The loading spinner SVG element.",
-              "name": "spinner"
+              "description": "The separator element rendered after non-last items.",
+              "name": "separator"
             }
           ],
           "slots": [
             {
-              "description": "Default slot for button label text or content.",
+              "description": "The link or page text content. Accepts text, HTML, or icon elements.",
               "name": ""
-            },
-            {
-              "description": "Icon or content rendered before the label.",
-              "name": "prefix"
-            },
-            {
-              "description": "Icon or content rendered after the label.",
-              "name": "suffix"
             }
           ],
           "members": [
             {
               "kind": "field",
-              "name": "formAssociated",
+              "name": "href",
               "type": {
-                "text": "boolean"
+                "text": "string | undefined"
               },
-              "static": true,
-              "default": "true"
+              "default": "undefined",
+              "description": "The URL for this breadcrumb link. Omit for the current page item.\nWhen `current` is true, this attribute is ignored and the item always\nrenders as static text per WAI-ARIA APG breadcrumb guidance.",
+              "attribute": "href",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "_internals",
+              "name": "current",
               "type": {
-                "text": "ElementInternals"
+                "text": "boolean"
               },
-              "privacy": "private"
-            },
+              "default": "false",
+              "description": "Marks this item as the current page. When set, the item always renders as\nstatic text (never a navigable link) and `aria-current=\"page\"` is placed on\nthe inner text element per WAI-ARIA APG breadcrumb guidance, yielding the\ncanonical AT announcement (\"current page, Patient Records\").\n\nCan be set explicitly by consumers (e.g. Drupal Twig templates) to override\nthe default positional last-item detection in `hx-breadcrumb`. When any item\nin the breadcrumb has an explicit `current` attribute, the parent will not\noverride it.",
+              "attribute": "current",
+              "reflects": true
+            }
+          ],
+          "attributes": [
             {
-              "kind": "field",
-              "name": "variant",
+              "name": "href",
               "type": {
-                "text": "'primary' | 'secondary' | 'tertiary' | 'danger' | 'ghost' | 'outline'"
+                "text": "string | undefined"
               },
-              "default": "'primary'",
-              "description": "Visual style variant of the button.",
-              "attribute": "variant",
-              "reflects": true
+              "default": "undefined",
+              "description": "The URL for this breadcrumb link. Omit for the current page item.\nWhen `current` is true, this attribute is ignored and the item always\nrenders as static text per WAI-ARIA APG breadcrumb guidance.",
+              "fieldName": "href",
+              "attribute": "href"
             },
             {
-              "kind": "field",
-              "name": "size",
+              "name": "current",
               "type": {
-                "text": "'sm' | 'md' | 'lg'"
+                "text": "boolean"
               },
-              "default": "'md'",
-              "description": "Size of the button.",
-              "attribute": "hx-size",
-              "reflects": true
-            },
+              "default": "false",
+              "description": "Marks this item as the current page. When set, the item always renders as\nstatic text (never a navigable link) and `aria-current=\"page\"` is placed on\nthe inner text element per WAI-ARIA APG breadcrumb guidance, yielding the\ncanonical AT announcement (\"current page, Patient Records\").\n\nCan be set explicitly by consumers (e.g. Drupal Twig templates) to override\nthe default positional last-item detection in `hx-breadcrumb`. When any item\nin the breadcrumb has an explicit `current` attribute, the parent will not\noverride it.",
+              "fieldName": "current",
+              "attribute": "current"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "hx-breadcrumb-item",
+          "customElement": true,
+          "summary": "A navigation item within an hx-breadcrumb component. Renders as a link when `href` is\nprovided, or as static text for the current page item. The current page item is determined by\nthe `current` attribute (set explicitly or automatically by the parent `hx-breadcrumb`)."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "HelixBreadcrumbItem",
+          "declaration": {
+            "name": "HelixBreadcrumbItem",
+            "module": "src/components/hx-breadcrumb/hx-breadcrumb-item.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "hx-breadcrumb-item",
+          "declaration": {
+            "name": "HelixBreadcrumbItem",
+            "module": "src/components/hx-breadcrumb/hx-breadcrumb-item.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/hx-breadcrumb/hx-breadcrumb.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "HelixBreadcrumb",
+          "members": [
             {
               "kind": "field",
-              "name": "disabled",
+              "name": "_instanceCounter",
               "type": {
-                "text": "boolean"
+                "text": "number"
               },
-              "default": "false",
-              "description": "Whether the button is disabled. Prevents all interaction and form actions.",
-              "attribute": "disabled",
-              "reflects": true
+              "privacy": "private",
+              "static": true,
+              "default": "0",
+              "description": "Per-instance counter used to generate stable, deterministic IDs for the\ninjected JSON-LD script tags. Deterministic IDs (vs Math.random()) allow\nSSR frameworks to match server-rendered script tags during hydration."
             },
             {
               "kind": "field",
-              "name": "loading",
+              "name": "separator",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "default": "false",
-              "description": "Whether the button is in a loading state. Shows spinner, prevents interaction,\nand sets aria-busy. Does not set the disabled attribute.",
-              "attribute": "loading",
-              "reflects": true
+              "default": "'/'",
+              "description": "The separator character displayed between breadcrumb items.",
+              "attribute": "separator"
             },
             {
               "kind": "field",
-              "name": "type",
+              "name": "label",
               "type": {
-                "text": "'button' | 'submit' | 'reset'"
+                "text": "string"
               },
-              "default": "'button'",
-              "description": "The type attribute for the underlying button element. Ignored when href is set.",
-              "attribute": "type"
+              "default": "'Breadcrumb'",
+              "description": "The accessible label for the nav landmark.",
+              "attribute": "label"
             },
             {
               "kind": "field",
-              "name": "href",
+              "name": "maxItems",
               "type": {
-                "text": "string | undefined"
+                "text": "number"
               },
-              "default": "undefined",
-              "description": "When set, renders an anchor element instead of a button.",
-              "attribute": "href"
+              "default": "0",
+              "description": "Maximum number of items to show before collapsing middle items with an ellipsis.\nSet to 0 (default) to show all items. The ellipsis is a keyboard-accessible\nbutton; activating it expands the full breadcrumb by setting maxItems to 0.",
+              "attribute": "max-items"
             },
             {
               "kind": "field",
-              "name": "target",
+              "name": "jsonLd",
               "type": {
-                "text": "string | undefined"
+                "text": "boolean"
               },
-              "default": "undefined",
-              "description": "Anchor target attribute. Only used when href is set.",
-              "attribute": "target"
+              "default": "false",
+              "description": "When true, injects a JSON-LD BreadcrumbList structured data script into the document head.\n\nNOTE: Drupal manages `<head>` content via its own render pipeline. Injecting a\n`<script>` directly via `document.head.appendChild()` in a Drupal context:\n1. Bypasses Drupal's deduplication and `hook_html_head_alter()` hook.\n2. Is not cacheable by Drupal's page cache.\n3. Will be wiped on BigPipe partial page replacements.\n\nFor Drupal integrations, leave `json-ld` false and use the structured data\nTwig template instead (see `hx-breadcrumb.twig` in the component directory).",
+              "attribute": "json-ld"
             },
             {
               "kind": "field",
-              "name": "name",
+              "name": "_ellipsisItem",
               "type": {
-                "text": "string | undefined"
+                "text": "Element | null"
               },
-              "default": "undefined",
-              "description": "Form field name submitted via ElementInternals.setFormValue on submit.",
-              "attribute": "name"
+              "privacy": "private",
+              "default": "null"
             },
             {
               "kind": "field",
-              "name": "value",
+              "name": "_jsonLdScript",
               "type": {
-                "text": "string | undefined"
+                "text": "HTMLScriptElement | null"
               },
-              "default": "undefined",
-              "description": "Form field value submitted via ElementInternals.setFormValue on submit.",
-              "attribute": "value"
+              "privacy": "private",
+              "default": "null"
             },
             {
               "kind": "field",
-              "name": "ariaLabel",
+              "name": "_boundEllipsisClick",
               "type": {
-                "text": "string | null"
+                "text": "(e: Event) => void"
               },
-              "default": "null",
-              "description": "Accessible label forwarded to the inner button/anchor. Required for icon-only usage.",
-              "attribute": "aria-label",
-              "reflects": true
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "form",
+              "name": "_boundEllipsisKeydown",
               "type": {
-                "text": "HTMLFormElement | null"
+                "text": "(e: KeyboardEvent) => void"
               },
-              "description": "Returns the associated form element, if any.",
-              "readonly": true
+              "privacy": "private"
             },
             {
-              "kind": "method",
-              "name": "_handleClick",
-              "privacy": "private",
+              "kind": "field",
+              "name": "_managedCurrentItems",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new WeakSet<Element>()",
+              "description": "Tracks which items had their `current` attribute set by this component\n(as opposed to set by a consumer/Drupal template). This lets us re-evaluate\npositional current-page detection on each slotchange without incorrectly\ntreating a previously component-set `current` attribute as a consumer-set\nexplicit override."
+            },
+            {
+              "kind": "field",
+              "name": "_jsonLdId",
+              "privacy": "private",
+              "readonly": true,
+              "default": "`hx-breadcrumb-ld-${++HelixBreadcrumb._instanceCounter}`",
+              "description": "Stable per-instance ID used to tag the injected script element so that\nmultiple hx-breadcrumb instances on the same page don't produce conflicting\nor duplicate structured-data blocks. Each instance owns exactly one script\ntag identified by this ID; any stale tag from a previous render cycle is\nremoved before a new one is inserted.\n\nUses a static counter (not Math.random()) so IDs are deterministic across\nserver and client renders, enabling SSR hydration matching."
+            },
+            {
+              "kind": "method",
+              "name": "_getBreadcrumbItems",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Element[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "slot",
+                  "type": {
+                    "text": "HTMLSlotElement"
+                  }
+                }
+              ],
+              "description": "Returns only real breadcrumb items, excluding the managed ellipsis element."
+            },
+            {
+              "kind": "method",
+              "name": "_applyItemAttributes",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "items",
+                  "type": {
+                    "text": "Element[]"
+                  }
+                }
+              ],
+              "description": "Applies aria/state attributes to the item list.\n\nCurrent-page detection: if any item has an explicit `current` attribute\n(e.g. set by a Drupal Twig template), that item is treated as the current\npage. Otherwise the last item is the current page (default behaviour).\n\nThis separation allows Drupal to control current-page marking without\nrelying on item order."
+            },
+            {
+              "kind": "method",
+              "name": "_handleSlotChange",
+              "privacy": "private",
               "return": {
                 "type": {
                   "text": "void"
@@ -2076,515 +2153,478 @@
                 {
                   "name": "e",
                   "type": {
-                    "text": "MouseEvent"
+                    "text": "Event"
                   }
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "_renderSpinner",
+              "name": "_handleSeparatorSlotChange",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "TemplateResult"
+                  "text": "void"
                 }
-              }
+              },
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
             },
             {
               "kind": "method",
-              "name": "_renderInner",
+              "name": "_applyCollapse",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "TemplateResult"
+                  "text": "void"
                 }
-              }
-            }
-          ],
-          "events": [
-            {
-              "name": "hx-click",
-              "type": {
-                "text": "CustomEvent<{originalEvent: MouseEvent}>"
               },
-              "description": "Dispatched when the button is clicked and is neither disabled nor loading."
-            }
-          ],
-          "attributes": [
+              "parameters": [
+                {
+                  "name": "items",
+                  "type": {
+                    "text": "Element[]"
+                  }
+                }
+              ]
+            },
             {
-              "name": "variant",
-              "type": {
-                "text": "'primary' | 'secondary' | 'tertiary' | 'danger' | 'ghost' | 'outline'"
+              "kind": "method",
+              "name": "_removeCollapse",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
               },
-              "default": "'primary'",
-              "description": "Visual style variant of the button.",
-              "fieldName": "variant",
-              "attribute": "variant"
+              "parameters": [
+                {
+                  "name": "items",
+                  "type": {
+                    "text": "Element[]"
+                  }
+                }
+              ]
             },
             {
-              "name": "hx-size",
-              "type": {
-                "text": "'sm' | 'md' | 'lg'"
+              "kind": "method",
+              "name": "_handleEllipsisClick",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
               },
-              "default": "'md'",
-              "description": "Size of the button.",
-              "fieldName": "size",
-              "attribute": "hx-size"
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
             },
             {
-              "name": "disabled",
-              "type": {
-                "text": "boolean"
+              "kind": "method",
+              "name": "_handleEllipsisKeydown",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
               },
-              "default": "false",
-              "description": "Whether the button is disabled. Prevents all interaction and form actions.",
-              "fieldName": "disabled",
-              "attribute": "disabled"
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ]
             },
             {
-              "name": "loading",
-              "type": {
-                "text": "boolean"
+              "kind": "method",
+              "name": "_expandBreadcrumb",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
               },
-              "default": "false",
-              "description": "Whether the button is in a loading state. Shows spinner, prevents interaction,\nand sets aria-busy. Does not set the disabled attribute.",
-              "fieldName": "loading",
-              "attribute": "loading"
+              "description": "Expands a collapsed breadcrumb by resetting maxItems to 0.\nCalled by the ellipsis expand button (click or Enter/Space)."
             },
             {
-              "name": "type",
-              "type": {
-                "text": "'button' | 'submit' | 'reset'"
+              "kind": "method",
+              "name": "_buildListItem",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "JsonLdListItem"
+                }
               },
-              "default": "'button'",
-              "description": "The type attribute for the underlying button element. Ignored when href is set.",
-              "fieldName": "type",
-              "attribute": "type"
+              "parameters": [
+                {
+                  "name": "item",
+                  "type": {
+                    "text": "Element"
+                  }
+                },
+                {
+                  "name": "position",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "JSON-LD ListItem entry with typed fields to avoid Record<string, unknown>."
             },
             {
-              "name": "href",
-              "type": {
-                "text": "string | undefined"
+              "kind": "method",
+              "name": "_updateJsonLd",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
               },
-              "default": "undefined",
-              "description": "When set, renders an anchor element instead of a button.",
-              "fieldName": "href",
-              "attribute": "href"
+              "parameters": [
+                {
+                  "name": "items",
+                  "type": {
+                    "text": "Element[]"
+                  }
+                }
+              ]
             },
             {
-              "name": "target",
+              "kind": "method",
+              "name": "_removeJsonLd",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "name": "separator",
               "type": {
-                "text": "string | undefined"
+                "text": "string"
               },
-              "default": "undefined",
-              "description": "Anchor target attribute. Only used when href is set.",
-              "fieldName": "target",
-              "attribute": "target"
+              "default": "'/'",
+              "description": "The separator character displayed between breadcrumb items.",
+              "fieldName": "separator",
+              "attribute": "separator"
             },
             {
-              "name": "name",
+              "name": "label",
               "type": {
-                "text": "string | undefined"
+                "text": "string"
               },
-              "default": "undefined",
-              "description": "Form field name submitted via ElementInternals.setFormValue on submit.",
-              "fieldName": "name",
-              "attribute": "name"
+              "default": "'Breadcrumb'",
+              "description": "The accessible label for the nav landmark.",
+              "fieldName": "label",
+              "attribute": "label"
             },
             {
-              "name": "value",
+              "name": "max-items",
               "type": {
-                "text": "string | undefined"
+                "text": "number"
               },
-              "default": "undefined",
-              "description": "Form field value submitted via ElementInternals.setFormValue on submit.",
-              "fieldName": "value",
-              "attribute": "value"
+              "default": "0",
+              "description": "Maximum number of items to show before collapsing middle items with an ellipsis.\nSet to 0 (default) to show all items. The ellipsis is a keyboard-accessible\nbutton; activating it expands the full breadcrumb by setting maxItems to 0.",
+              "fieldName": "maxItems",
+              "attribute": "max-items"
             },
             {
-              "name": "aria-label",
+              "name": "json-ld",
               "type": {
-                "text": "string | null"
+                "text": "boolean"
               },
-              "default": "null",
-              "description": "Accessible label forwarded to the inner button/anchor. Required for icon-only usage.",
-              "fieldName": "ariaLabel",
-              "attribute": "aria-label"
+              "default": "false",
+              "description": "When true, injects a JSON-LD BreadcrumbList structured data script into the document head.\n\nNOTE: Drupal manages `<head>` content via its own render pipeline. Injecting a\n`<script>` directly via `document.head.appendChild()` in a Drupal context:\n1. Bypasses Drupal's deduplication and `hook_html_head_alter()` hook.\n2. Is not cacheable by Drupal's page cache.\n3. Will be wiped on BigPipe partial page replacements.\n\nFor Drupal integrations, leave `json-ld` false and use the structured data\nTwig template instead (see `hx-breadcrumb.twig` in the component directory).",
+              "fieldName": "jsonLd",
+              "attribute": "json-ld"
             }
           ],
           "superclass": {
             "name": "LitElement",
             "package": "lit"
           },
-          "tagName": "hx-button",
-          "customElement": true,
-          "summary": "Primary interactive element for triggering actions and form submission."
+          "tagName": "hx-breadcrumb",
+          "customElement": true
+        },
+        {
+          "kind": "variable",
+          "name": "name"
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "HelixButton",
+          "name": "HelixBreadcrumb",
           "declaration": {
-            "name": "HelixButton",
-            "module": "src/components/hx-button/hx-button.ts"
+            "name": "HelixBreadcrumb",
+            "module": "src/components/hx-breadcrumb/hx-breadcrumb.ts"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "hx-button",
+          "name": "hx-breadcrumb",
           "declaration": {
-            "name": "HelixButton",
-            "module": "src/components/hx-button/hx-button.ts"
+            "name": "HelixBreadcrumb",
+            "module": "src/components/hx-breadcrumb/hx-breadcrumb.ts"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/hx-button/index.ts",
+      "path": "src/components/hx-breadcrumb/index.ts",
       "declarations": [],
       "exports": [
         {
           "kind": "js",
-          "name": "HelixButton",
-          "declaration": {
-            "name": "HelixButton",
-            "module": "./hx-button.js"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/components/hx-breadcrumb/hx-breadcrumb-item.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "A single breadcrumb navigation item.",
-          "name": "HelixBreadcrumbItem",
-          "cssProperties": [
-            {
-              "description": "Link text color.",
-              "name": "--hx-breadcrumb-link-color",
-              "default": "var(--hx-color-primary-600)"
-            },
-            {
-              "description": "Link hover text color.",
-              "name": "--hx-breadcrumb-link-hover-color",
-              "default": "var(--hx-color-primary-700)"
-            },
-            {
-              "description": "Current page text color.",
-              "name": "--hx-breadcrumb-text-color",
-              "default": "var(--hx-color-neutral-700)"
-            },
-            {
-              "description": "Separator character displayed after non-last items.",
-              "name": "--hx-breadcrumb-separator-content",
-              "default": "'/'"
-            },
-            {
-              "description": "Separator color.",
-              "name": "--hx-breadcrumb-separator-color",
-              "default": "var(--hx-color-neutral-400)"
-            },
-            {
-              "description": "Horizontal margin around separator.",
-              "name": "--hx-breadcrumb-separator-gap",
-              "default": "var(--hx-space-1)"
-            },
-            {
-              "description": "Optional max-width for text truncation.",
-              "name": "--hx-breadcrumb-item-max-width"
-            }
-          ],
-          "cssParts": [
-            {
-              "description": "Wrapper around the link or text content.",
-              "name": "item"
-            },
-            {
-              "description": "The anchor element when href is provided (non-current items only).",
-              "name": "link"
-            },
-            {
-              "description": "The span element for the current page or items without href.",
-              "name": "text"
-            },
-            {
-              "description": "The separator element rendered after non-last items.",
-              "name": "separator"
-            }
-          ],
-          "slots": [
-            {
-              "description": "The link or page text content. Accepts text, HTML, or icon elements.",
-              "name": ""
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "href",
-              "type": {
-                "text": "string | undefined"
-              },
-              "default": "undefined",
-              "description": "The URL for this breadcrumb link. Omit for the current page item.\nWhen `current` is true, this attribute is ignored and the item always\nrenders as static text per WAI-ARIA APG breadcrumb guidance.",
-              "attribute": "href",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "current",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Marks this item as the current page. When set, the item always renders as\nstatic text (never a navigable link) and `aria-current=\"page\"` is placed on\nthe inner text element per WAI-ARIA APG breadcrumb guidance, yielding the\ncanonical AT announcement (\"current page, Patient Records\").\n\nCan be set explicitly by consumers (e.g. Drupal Twig templates) to override\nthe default positional last-item detection in `hx-breadcrumb`. When any item\nin the breadcrumb has an explicit `current` attribute, the parent will not\noverride it.",
-              "attribute": "current",
-              "reflects": true
-            }
-          ],
-          "attributes": [
-            {
-              "name": "href",
-              "type": {
-                "text": "string | undefined"
-              },
-              "default": "undefined",
-              "description": "The URL for this breadcrumb link. Omit for the current page item.\nWhen `current` is true, this attribute is ignored and the item always\nrenders as static text per WAI-ARIA APG breadcrumb guidance.",
-              "fieldName": "href",
-              "attribute": "href"
-            },
-            {
-              "name": "current",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Marks this item as the current page. When set, the item always renders as\nstatic text (never a navigable link) and `aria-current=\"page\"` is placed on\nthe inner text element per WAI-ARIA APG breadcrumb guidance, yielding the\ncanonical AT announcement (\"current page, Patient Records\").\n\nCan be set explicitly by consumers (e.g. Drupal Twig templates) to override\nthe default positional last-item detection in `hx-breadcrumb`. When any item\nin the breadcrumb has an explicit `current` attribute, the parent will not\noverride it.",
-              "fieldName": "current",
-              "attribute": "current"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "hx-breadcrumb-item",
-          "customElement": true,
-          "summary": "A navigation item within an hx-breadcrumb component. Renders as a link when `href` is\nprovided, or as static text for the current page item. The current page item is determined by\nthe `current` attribute (set explicitly or automatically by the parent `hx-breadcrumb`)."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "HelixBreadcrumbItem",
+          "name": "HelixBreadcrumb",
           "declaration": {
-            "name": "HelixBreadcrumbItem",
-            "module": "src/components/hx-breadcrumb/hx-breadcrumb-item.ts"
+            "name": "HelixBreadcrumb",
+            "module": "./hx-breadcrumb.js"
           }
         },
         {
-          "kind": "custom-element-definition",
-          "name": "hx-breadcrumb-item",
+          "kind": "js",
+          "name": "HelixBreadcrumbItem",
           "declaration": {
             "name": "HelixBreadcrumbItem",
-            "module": "src/components/hx-breadcrumb/hx-breadcrumb-item.ts"
+            "module": "./hx-breadcrumb-item.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/hx-breadcrumb/hx-breadcrumb.ts",
+      "path": "src/components/hx-button/hx-button.ts",
       "declarations": [
         {
           "kind": "class",
-          "description": "",
-          "name": "HelixBreadcrumb",
+          "description": "A production-grade button component for user interaction. Supports multiple\nvisual variants, sizes, loading state, prefix/suffix slots, anchor rendering,\nand full ElementInternals form association.",
+          "name": "HelixButton",
+          "cssProperties": [
+            {
+              "description": "Button background color.",
+              "name": "--hx-button-bg",
+              "default": "var(--hx-color-primary-500)"
+            },
+            {
+              "description": "Button text color.",
+              "name": "--hx-button-color",
+              "default": "var(--hx-color-neutral-0)"
+            },
+            {
+              "description": "Button border color.",
+              "name": "--hx-button-border-color",
+              "default": "transparent"
+            },
+            {
+              "description": "Button border radius.",
+              "name": "--hx-button-border-radius",
+              "default": "var(--hx-border-radius-md)"
+            },
+            {
+              "description": "Button font family.",
+              "name": "--hx-button-font-family",
+              "default": "var(--hx-font-family-sans)"
+            },
+            {
+              "description": "Button font weight.",
+              "name": "--hx-button-font-weight",
+              "default": "var(--hx-font-weight-semibold)"
+            },
+            {
+              "description": "Focus ring color.",
+              "name": "--hx-button-focus-ring-color",
+              "default": "var(--hx-focus-ring-color)"
+            }
+          ],
+          "cssParts": [
+            {
+              "description": "The native button or anchor element.",
+              "name": "button"
+            },
+            {
+              "description": "The label text wrapper span.",
+              "name": "label"
+            },
+            {
+              "description": "The prefix slot container span.",
+              "name": "prefix"
+            },
+            {
+              "description": "The suffix slot container span.",
+              "name": "suffix"
+            },
+            {
+              "description": "The loading spinner SVG element.",
+              "name": "spinner"
+            }
+          ],
+          "slots": [
+            {
+              "description": "Default slot for button label text or content.",
+              "name": ""
+            },
+            {
+              "description": "Icon or content rendered before the label.",
+              "name": "prefix"
+            },
+            {
+              "description": "Icon or content rendered after the label.",
+              "name": "suffix"
+            }
+          ],
           "members": [
             {
               "kind": "field",
-              "name": "_instanceCounter",
+              "name": "formAssociated",
               "type": {
-                "text": "number"
+                "text": "boolean"
               },
-              "privacy": "private",
               "static": true,
-              "default": "0",
-              "description": "Per-instance counter used to generate stable, deterministic IDs for the\ninjected JSON-LD script tags. Deterministic IDs (vs Math.random()) allow\nSSR frameworks to match server-rendered script tags during hydration."
+              "default": "true"
             },
             {
               "kind": "field",
-              "name": "separator",
+              "name": "_internals",
               "type": {
-                "text": "string"
+                "text": "ElementInternals"
               },
-              "default": "'/'",
-              "description": "The separator character displayed between breadcrumb items.",
-              "attribute": "separator"
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "label",
+              "name": "variant",
               "type": {
-                "text": "string"
+                "text": "'primary' | 'secondary' | 'tertiary' | 'danger' | 'ghost' | 'outline'"
               },
-              "default": "'Breadcrumb'",
-              "description": "The accessible label for the nav landmark.",
-              "attribute": "label"
+              "default": "'primary'",
+              "description": "Visual style variant of the button.",
+              "attribute": "variant",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "maxItems",
+              "name": "size",
               "type": {
-                "text": "number"
+                "text": "'sm' | 'md' | 'lg'"
               },
-              "default": "0",
-              "description": "Maximum number of items to show before collapsing middle items with an ellipsis.\nSet to 0 (default) to show all items. The ellipsis is a keyboard-accessible\nbutton; activating it expands the full breadcrumb by setting maxItems to 0.",
-              "attribute": "max-items"
+              "default": "'md'",
+              "description": "Size of the button.",
+              "attribute": "hx-size",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "jsonLd",
+              "name": "disabled",
               "type": {
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When true, injects a JSON-LD BreadcrumbList structured data script into the document head.\n\nNOTE: Drupal manages `<head>` content via its own render pipeline. Injecting a\n`<script>` directly via `document.head.appendChild()` in a Drupal context:\n1. Bypasses Drupal's deduplication and `hook_html_head_alter()` hook.\n2. Is not cacheable by Drupal's page cache.\n3. Will be wiped on BigPipe partial page replacements.\n\nFor Drupal integrations, leave `json-ld` false and use the structured data\nTwig template instead (see `hx-breadcrumb.twig` in the component directory).",
-              "attribute": "json-ld"
+              "description": "Whether the button is disabled. Prevents all interaction and form actions.",
+              "attribute": "disabled",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "_ellipsisItem",
+              "name": "loading",
               "type": {
-                "text": "Element | null"
+                "text": "boolean"
               },
-              "privacy": "private",
-              "default": "null"
+              "default": "false",
+              "description": "Whether the button is in a loading state. Shows spinner, prevents interaction,\nand sets aria-busy. Does not set the disabled attribute.",
+              "attribute": "loading",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "_jsonLdScript",
+              "name": "type",
               "type": {
-                "text": "HTMLScriptElement | null"
+                "text": "'button' | 'submit' | 'reset'"
               },
-              "privacy": "private",
-              "default": "null"
+              "default": "'button'",
+              "description": "The type attribute for the underlying button element. Ignored when href is set.",
+              "attribute": "type"
             },
             {
               "kind": "field",
-              "name": "_boundEllipsisClick",
+              "name": "href",
               "type": {
-                "text": "(e: Event) => void"
+                "text": "string | undefined"
               },
-              "privacy": "private"
+              "default": "undefined",
+              "description": "When set, renders an anchor element instead of a button.",
+              "attribute": "href"
             },
             {
               "kind": "field",
-              "name": "_boundEllipsisKeydown",
+              "name": "target",
               "type": {
-                "text": "(e: KeyboardEvent) => void"
+                "text": "string | undefined"
               },
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "_managedCurrentItems",
-              "privacy": "private",
-              "readonly": true,
-              "default": "new WeakSet<Element>()",
-              "description": "Tracks which items had their `current` attribute set by this component\n(as opposed to set by a consumer/Drupal template). This lets us re-evaluate\npositional current-page detection on each slotchange without incorrectly\ntreating a previously component-set `current` attribute as a consumer-set\nexplicit override."
+              "default": "undefined",
+              "description": "Anchor target attribute. Only used when href is set.",
+              "attribute": "target"
             },
             {
               "kind": "field",
-              "name": "_jsonLdId",
-              "privacy": "private",
-              "readonly": true,
-              "default": "`hx-breadcrumb-ld-${++HelixBreadcrumb._instanceCounter}`",
-              "description": "Stable per-instance ID used to tag the injected script element so that\nmultiple hx-breadcrumb instances on the same page don't produce conflicting\nor duplicate structured-data blocks. Each instance owns exactly one script\ntag identified by this ID; any stale tag from a previous render cycle is\nremoved before a new one is inserted.\n\nUses a static counter (not Math.random()) so IDs are deterministic across\nserver and client renders, enabling SSR hydration matching."
-            },
-            {
-              "kind": "method",
-              "name": "_getBreadcrumbItems",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "Element[]"
-                }
+              "name": "name",
+              "type": {
+                "text": "string | undefined"
               },
-              "parameters": [
-                {
-                  "name": "slot",
-                  "type": {
-                    "text": "HTMLSlotElement"
-                  }
-                }
-              ],
-              "description": "Returns only real breadcrumb items, excluding the managed ellipsis element."
+              "default": "undefined",
+              "description": "Form field name submitted via ElementInternals.setFormValue on submit.",
+              "attribute": "name"
             },
             {
-              "kind": "method",
-              "name": "_applyItemAttributes",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+              "kind": "field",
+              "name": "value",
+              "type": {
+                "text": "string | undefined"
               },
-              "parameters": [
-                {
-                  "name": "items",
-                  "type": {
-                    "text": "Element[]"
-                  }
-                }
-              ],
-              "description": "Applies aria/state attributes to the item list.\n\nCurrent-page detection: if any item has an explicit `current` attribute\n(e.g. set by a Drupal Twig template), that item is treated as the current\npage. Otherwise the last item is the current page (default behaviour).\n\nThis separation allows Drupal to control current-page marking without\nrelying on item order."
+              "default": "undefined",
+              "description": "Form field value submitted via ElementInternals.setFormValue on submit.",
+              "attribute": "value"
             },
             {
-              "kind": "method",
-              "name": "_handleSlotChange",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+              "kind": "field",
+              "name": "ariaLabel",
+              "type": {
+                "text": "string | null"
               },
-              "parameters": [
-                {
-                  "name": "e",
-                  "type": {
-                    "text": "Event"
-                  }
-                }
-              ]
+              "default": "null",
+              "description": "Accessible label forwarded to the inner button/anchor. Required for icon-only usage.",
+              "attribute": "aria-label",
+              "reflects": true
             },
             {
-              "kind": "method",
-              "name": "_handleSeparatorSlotChange",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+              "kind": "field",
+              "name": "form",
+              "type": {
+                "text": "HTMLFormElement | null"
               },
-              "parameters": [
-                {
-                  "name": "e",
-                  "type": {
-                    "text": "Event"
-                  }
-                }
-              ]
+              "description": "Returns the associated form element, if any.",
+              "readonly": true
             },
             {
               "kind": "method",
-              "name": "_applyCollapse",
+              "name": "_handleClick",
               "privacy": "private",
               "return": {
                 "type": {
@@ -2593,224 +2633,184 @@
               },
               "parameters": [
                 {
-                  "name": "items",
+                  "name": "e",
                   "type": {
-                    "text": "Element[]"
+                    "text": "MouseEvent"
                   }
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "_removeCollapse",
+              "name": "_renderSpinner",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "items",
-                  "type": {
-                    "text": "Element[]"
-                  }
+                  "text": "TemplateResult"
                 }
-              ]
+              }
             },
             {
               "kind": "method",
-              "name": "_handleEllipsisClick",
+              "name": "_renderInner",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "TemplateResult"
                 }
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "hx-click",
+              "type": {
+                "text": "CustomEvent<{originalEvent: MouseEvent}>"
               },
-              "parameters": [
-                {
-                  "name": "e",
-                  "type": {
-                    "text": "Event"
-                  }
-                }
-              ]
+              "description": "Dispatched when the button is clicked and is neither disabled nor loading."
+            }
+          ],
+          "attributes": [
+            {
+              "name": "variant",
+              "type": {
+                "text": "'primary' | 'secondary' | 'tertiary' | 'danger' | 'ghost' | 'outline'"
+              },
+              "default": "'primary'",
+              "description": "Visual style variant of the button.",
+              "fieldName": "variant",
+              "attribute": "variant"
             },
             {
-              "kind": "method",
-              "name": "_handleEllipsisKeydown",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+              "name": "hx-size",
+              "type": {
+                "text": "'sm' | 'md' | 'lg'"
               },
-              "parameters": [
-                {
-                  "name": "e",
-                  "type": {
-                    "text": "KeyboardEvent"
-                  }
-                }
-              ]
+              "default": "'md'",
+              "description": "Size of the button.",
+              "fieldName": "size",
+              "attribute": "hx-size"
             },
             {
-              "kind": "method",
-              "name": "_expandBreadcrumb",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
               },
-              "description": "Expands a collapsed breadcrumb by resetting maxItems to 0.\nCalled by the ellipsis expand button (click or Enter/Space)."
+              "default": "false",
+              "description": "Whether the button is disabled. Prevents all interaction and form actions.",
+              "fieldName": "disabled",
+              "attribute": "disabled"
             },
             {
-              "kind": "method",
-              "name": "_buildListItem",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "JsonLdListItem"
-                }
+              "name": "loading",
+              "type": {
+                "text": "boolean"
               },
-              "parameters": [
-                {
-                  "name": "item",
-                  "type": {
-                    "text": "Element"
-                  }
-                },
-                {
-                  "name": "position",
-                  "type": {
-                    "text": "number"
-                  }
-                }
-              ],
-              "description": "JSON-LD ListItem entry with typed fields to avoid Record<string, unknown>."
+              "default": "false",
+              "description": "Whether the button is in a loading state. Shows spinner, prevents interaction,\nand sets aria-busy. Does not set the disabled attribute.",
+              "fieldName": "loading",
+              "attribute": "loading"
             },
             {
-              "kind": "method",
-              "name": "_updateJsonLd",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+              "name": "type",
+              "type": {
+                "text": "'button' | 'submit' | 'reset'"
               },
-              "parameters": [
-                {
-                  "name": "items",
-                  "type": {
-                    "text": "Element[]"
-                  }
-                }
-              ]
+              "default": "'button'",
+              "description": "The type attribute for the underlying button element. Ignored when href is set.",
+              "fieldName": "type",
+              "attribute": "type"
             },
             {
-              "kind": "method",
-              "name": "_removeJsonLd",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            }
-          ],
-          "attributes": [
+              "name": "href",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "When set, renders an anchor element instead of a button.",
+              "fieldName": "href",
+              "attribute": "href"
+            },
             {
-              "name": "separator",
+              "name": "target",
               "type": {
-                "text": "string"
+                "text": "string | undefined"
               },
-              "default": "'/'",
-              "description": "The separator character displayed between breadcrumb items.",
-              "fieldName": "separator",
-              "attribute": "separator"
+              "default": "undefined",
+              "description": "Anchor target attribute. Only used when href is set.",
+              "fieldName": "target",
+              "attribute": "target"
             },
             {
-              "name": "label",
+              "name": "name",
               "type": {
-                "text": "string"
+                "text": "string | undefined"
               },
-              "default": "'Breadcrumb'",
-              "description": "The accessible label for the nav landmark.",
-              "fieldName": "label",
-              "attribute": "label"
+              "default": "undefined",
+              "description": "Form field name submitted via ElementInternals.setFormValue on submit.",
+              "fieldName": "name",
+              "attribute": "name"
             },
             {
-              "name": "max-items",
+              "name": "value",
               "type": {
-                "text": "number"
+                "text": "string | undefined"
               },
-              "default": "0",
-              "description": "Maximum number of items to show before collapsing middle items with an ellipsis.\nSet to 0 (default) to show all items. The ellipsis is a keyboard-accessible\nbutton; activating it expands the full breadcrumb by setting maxItems to 0.",
-              "fieldName": "maxItems",
-              "attribute": "max-items"
+              "default": "undefined",
+              "description": "Form field value submitted via ElementInternals.setFormValue on submit.",
+              "fieldName": "value",
+              "attribute": "value"
             },
             {
-              "name": "json-ld",
+              "name": "aria-label",
               "type": {
-                "text": "boolean"
+                "text": "string | null"
               },
-              "default": "false",
-              "description": "When true, injects a JSON-LD BreadcrumbList structured data script into the document head.\n\nNOTE: Drupal manages `<head>` content via its own render pipeline. Injecting a\n`<script>` directly via `document.head.appendChild()` in a Drupal context:\n1. Bypasses Drupal's deduplication and `hook_html_head_alter()` hook.\n2. Is not cacheable by Drupal's page cache.\n3. Will be wiped on BigPipe partial page replacements.\n\nFor Drupal integrations, leave `json-ld` false and use the structured data\nTwig template instead (see `hx-breadcrumb.twig` in the component directory).",
-              "fieldName": "jsonLd",
-              "attribute": "json-ld"
+              "default": "null",
+              "description": "Accessible label forwarded to the inner button/anchor. Required for icon-only usage.",
+              "fieldName": "ariaLabel",
+              "attribute": "aria-label"
             }
           ],
           "superclass": {
             "name": "LitElement",
             "package": "lit"
           },
-          "tagName": "hx-breadcrumb",
-          "customElement": true
-        },
-        {
-          "kind": "variable",
-          "name": "name"
+          "tagName": "hx-button",
+          "customElement": true,
+          "summary": "Primary interactive element for triggering actions and form submission."
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "HelixBreadcrumb",
+          "name": "HelixButton",
           "declaration": {
-            "name": "HelixBreadcrumb",
-            "module": "src/components/hx-breadcrumb/hx-breadcrumb.ts"
+            "name": "HelixButton",
+            "module": "src/components/hx-button/hx-button.ts"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "hx-breadcrumb",
+          "name": "hx-button",
           "declaration": {
-            "name": "HelixBreadcrumb",
-            "module": "src/components/hx-breadcrumb/hx-breadcrumb.ts"
+            "name": "HelixButton",
+            "module": "src/components/hx-button/hx-button.ts"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/hx-breadcrumb/index.ts",
+      "path": "src/components/hx-button/index.ts",
       "declarations": [],
       "exports": [
         {
           "kind": "js",
-          "name": "HelixBreadcrumb",
-          "declaration": {
-            "name": "HelixBreadcrumb",
-            "module": "./hx-breadcrumb.js"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "HelixBreadcrumbItem",
+          "name": "HelixButton",
           "declaration": {
-            "name": "HelixBreadcrumbItem",
-            "module": "./hx-breadcrumb-item.js"
+            "name": "HelixButton",
+            "module": "./hx-button.js"
           }
         }
       ]