@helixui/library 2.1.2-next.52 → 2.1.2-next.54

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/base/styles.ts","../src/controllers/helix-audit-controller.ts"],"sourcesContent":["import { type CSSResultOrNative } from 'lit';\n\n/**\n * Merges token CSS custom properties into component styles.\n *\n * Accepts either a single style or an array for each argument and returns\n * a flat merged array suitable for use as `static override styles`.\n *\n * @deprecated Use document-level adopted stylesheets instead. Import\n * `'@helixui/library'` (which auto-adopts tokens) or call\n * `ensureDocumentTokens()` directly. Per-component token merging is no\n * longer necessary because tokens are now adopted at the document level\n * and cascade into Shadow DOM via CSS inheritance.\n *\n * @param componentStyles - The component's own styles\n * @param tokenStyles - Additional token CSS to merge in\n * @returns Merged styles array\n * @public\n *\n * @example\n * ```ts\n * // Preferred: tokens are auto-adopted at the document level\n * import '@helixui/library';\n *\n * // Legacy usage (deprecated):\n * static override styles = mergeTokenStyles(myStyles, extraStyles);\n * ```\n */\nexport function mergeTokenStyles(\n  componentStyles: CSSResultOrNative | CSSResultOrNative[],\n  tokenStyles: CSSResultOrNative | CSSResultOrNative[],\n): CSSResultOrNative[] {\n  const base = Array.isArray(componentStyles) ? componentStyles : [componentStyles];\n  const tokens = Array.isArray(tokenStyles) ? tokenStyles : [tokenStyles];\n  return [...base, ...tokens];\n}\n","/**\n * @module HelixAuditController\n *\n * A Lit ReactiveController that captures `hx-*` CustomEvents on the host\n * element and re-dispatches them as enriched `hx-audit` events that bubble to\n * the document level. Designed for HIPAA audit-trail infrastructure in\n * enterprise healthcare deployments.\n *\n * @example\n * ```ts\n * import { HelixAuditController } from '../controllers/helix-audit-controller.js';\n *\n * class MyElement extends LitElement {\n *   private _audit = new HelixAuditController(this, {\n *     userId: 'user-123',\n *     patientContextId: 'patient-456',\n *     encounterId: 'encounter-789',\n *   });\n * }\n * ```\n *\n * At the application boundary, wire a single document-level listener to forward\n * events to your HIPAA audit log infrastructure:\n *\n * ```ts\n * document.addEventListener('hx-audit', (e) => {\n *   const detail = (e as CustomEvent<AuditEventDetail>).detail;\n *   auditLogService.record(detail);\n * });\n * ```\n */\nimport type { ReactiveController, ReactiveControllerHost } from 'lit';\n\n/**\n * The structured payload carried in every `hx-audit` CustomEvent.\n */\nexport interface AuditEventDetail {\n  /** Stable correlation ID generated once per controller instance. */\n  sessionId: string;\n  /** ISO-8601 timestamp at the moment of capture. */\n  timestamp: string;\n  /** Lowercase tag name of the host element (e.g. `\"hx-button\"`). */\n  tagName: string;\n  /** The original `hx-*` event type that triggered this audit record. */\n  sourceEventType: string;\n  /** The original event's `detail` payload, preserved verbatim. */\n  sourceEventDetail: unknown;\n  /** Optional user identifier for the authenticated session. */\n  userId?: string;\n  /** Optional patient context identifier for clinical audit trails. */\n  patientContextId?: string;\n  /** Optional encounter/visit identifier for clinical audit trails. */\n  encounterId?: string;\n  /** Additional caller-supplied key/value metadata. */\n  [key: string]: unknown;\n}\n\n/**\n * Options accepted by `HelixAuditController` at construction time and via\n * `updateMetadata()`.\n */\nexport interface AuditControllerOptions {\n  /** Authenticated user identifier. */\n  userId?: string;\n  /** Patient context identifier. */\n  patientContextId?: string;\n  /** Clinical encounter / visit identifier. */\n  encounterId?: string;\n  /** Arbitrary additional metadata to merge into every audit record. */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * All `hx-*` event types defined in the HELiX component library that should\n * be captured for audit. When a new event is added to the library, adding it\n * here ensures automatic audit coverage with zero other changes required.\n *\n * The DOM event model does not support wildcard subscriptions, so we maintain\n * this explicit list and attach/detach one listener per type — a single bound\n * handler object is reused across all registrations for memory efficiency.\n */\nconst HX_EVENT_TYPES = [\n  'hx-click',\n  'hx-input',\n  'hx-change',\n  'hx-open',\n  'hx-close',\n  'hx-select',\n  'hx-submit',\n  'hx-reset',\n  'hx-sort',\n  'hx-filter',\n  'hx-page-change',\n  'hx-tab-change',\n  'hx-expand',\n  'hx-collapse',\n  'hx-copy',\n  'hx-upload',\n  'hx-remove',\n  'hx-rate',\n  'hx-toggle',\n  'hx-dismiss',\n  'hx-phi-access',\n] as const;\n\n/**\n * Generates a unique session correlation ID. Uses `crypto.randomUUID()` when\n * available and falls back to a timestamp-seeded pseudo-random string for\n * environments that do not expose the Web Crypto API (e.g. SSR, jsdom without\n * the crypto polyfill).\n */\nfunction generateSessionId(): string {\n  if (typeof crypto !== 'undefined' && typeof (crypto as Crypto).randomUUID === 'function') {\n    return (crypto as Crypto).randomUUID();\n  }\n  // Fallback: formatted as a UUID v4 lookalike so downstream parsers that\n  // expect that shape don't break.\n  const t = Date.now().toString(16).padStart(12, '0');\n  const r1 = Math.random().toString(16).slice(2, 10).padStart(8, '0');\n  const r2 = Math.random().toString(16).slice(2, 14).padStart(12, '0');\n  return `${t.slice(0, 8)}-${t.slice(8)}-4${r1.slice(0, 3)}-${r2.slice(0, 4)}-${r2.slice(4)}`;\n}\n\n/**\n * Attaches to a Lit `ReactiveControllerHost` (any `LitElement`) and silently\n * captures all `hx-*` events, enriching them with session, timestamp, and\n * optional clinical metadata before re-dispatching as `hx-audit` events.\n *\n * Because all HELiX component events are dispatched with\n * `bubbles: true, composed: true`, they propagate from inside the shadow DOM\n * up to the host element — where this controller's listeners are registered —\n * and then continue bubbling to `document`, making the `hx-audit` event\n * observable anywhere in the page without requiring a global listener.\n */\nexport class HelixAuditController implements ReactiveController {\n  private readonly _host: ReactiveControllerHost & EventTarget;\n  private readonly _sessionId: string;\n  private _options: AuditControllerOptions;\n\n  /**\n   * A single `EventListenerObject` reused across all event-type registrations.\n   * Using the object form (rather than a bound function) avoids creating a new\n   * closure per event type while still keeping `this` bound correctly.\n   */\n  private readonly _listener: EventListenerObject;\n\n  constructor(host: ReactiveControllerHost & EventTarget, options: AuditControllerOptions = {}) {\n    this._host = host;\n    this._sessionId = generateSessionId();\n    this._options = options;\n    this._listener = { handleEvent: this._onHxEvent.bind(this) };\n    this._host.addController(this);\n  }\n\n  /**\n   * Updates the metadata attached to future audit records. Useful when the\n   * authenticated user, patient context, or encounter changes after the\n   * component is connected (e.g. patient context switch within a session).\n   */\n  updateMetadata(options: AuditControllerOptions): void {\n    this._options = { ...this._options, ...options };\n  }\n\n  hostConnected(): void {\n    for (const type of HX_EVENT_TYPES) {\n      this._host.addEventListener(type, this._listener);\n    }\n  }\n\n  hostDisconnected(): void {\n    for (const type of HX_EVENT_TYPES) {\n      this._host.removeEventListener(type, this._listener);\n    }\n  }\n\n  private _onHxEvent(event: Event): void {\n    // Guard: only process events whose type starts with 'hx-'.\n    if (!event.type.startsWith('hx-')) return;\n    // Guard: prevent recursion — never audit the audit event itself.\n    if (event.type === 'hx-audit') return;\n\n    const sourceDetail = event instanceof CustomEvent ? event.detail : undefined;\n\n    const tagName = this._host instanceof Element ? this._host.tagName.toLowerCase() : 'unknown';\n\n    const { userId, patientContextId, encounterId, metadata } = this._options;\n\n    const detail: AuditEventDetail = {\n      sessionId: this._sessionId,\n      timestamp: new Date().toISOString(),\n      tagName,\n      sourceEventType: event.type,\n      sourceEventDetail: sourceDetail,\n      ...(userId !== undefined ? { userId } : {}),\n      ...(patientContextId !== undefined ? { patientContextId } : {}),\n      ...(encounterId !== undefined ? { encounterId } : {}),\n      ...metadata,\n    };\n\n    this._host.dispatchEvent(\n      new CustomEvent<AuditEventDetail>('hx-audit', {\n        bubbles: true,\n        composed: true,\n        detail,\n      }),\n    );\n  }\n}\n"],"names":["mergeTokenStyles","componentStyles","tokenStyles","base","tokens","HX_EVENT_TYPES","generateSessionId","r1","r2","HelixAuditController","host","options","type","event","sourceDetail","tagName","userId","patientContextId","encounterId","metadata","detail"],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../src/utilities/document-token-adoption.ts","../src/controllers/helix-audit-controller.ts"],"sourcesContent":["/**\n * @module document-token-adoption\n *\n * Adopts HELiX design tokens into `document.adoptedStyleSheets` exactly once,\n * so that every Shadow DOM component can reference `var(--hx-*)` tokens via\n * CSS inheritance rather than declaring them on each component's `:host`.\n *\n * This is the correct architecture for theme provider compatibility:\n * - Tokens declared at the document level provide fallback values\n * - `hx-theme` overrides tokens on its `:host`, which flow down via inheritance\n * - Components simply consume `var(--hx-*)` in their styles without redeclaring\n *\n * Inspired by @phase2/outline-adopted-stylesheets-controller.\n *\n * Limitation: tokens are adopted into the current `document` only. Components\n * rendered inside iframes or cross-document contexts will need their own\n * `ensureDocumentTokens()` call against the appropriate document.\n *\n * @example\n * ```ts\n * // Auto-registers on first import — no API call needed\n * import '../utilities/document-token-adoption.js';\n * ```\n */\nimport { lightTokenCss } from '@helixui/tokens';\n\n/** Cross-bundle marker — Symbol.for ensures all copies share the same key */\nconst MARKER = Symbol.for('hx-tokens-adopted');\n\n/**\n * Adopts the full set of HELiX design tokens into `document.adoptedStyleSheets`.\n * Safe to call multiple times — only the first invocation has any effect.\n * Uses a document-level Symbol marker to survive multiple bundled copies of the library.\n *\n * The tokens are declared on `:root` so they participate in CSS inheritance\n * and can be overridden by `hx-theme` (which declares on its `:host`).\n */\nexport function ensureDocumentTokens(): void {\n  if (\n    typeof document === 'undefined' ||\n    typeof CSSStyleSheet === 'undefined' ||\n    typeof CSSStyleSheet.prototype.replaceSync !== 'function'\n  ) {\n    return;\n  }\n\n  const doc = document as unknown as Record<symbol, unknown>;\n  if (doc[MARKER]) return;\n\n  try {\n    const cssText = `:root {\\n${lightTokenCss}\\n}`;\n\n    const sheet = new CSSStyleSheet();\n    sheet.replaceSync(cssText);\n\n    document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];\n    doc[MARKER] = MARKER;\n  } catch (e: unknown) {\n    console.warn('[HELiX] Could not adopt document-level token styles:', e);\n  }\n}\n\n// Auto-execute on import so bare `import './document-token-adoption.js'` works\n// in browser components. The SSR guard inside ensureDocumentTokens() makes this\n// safe in Node/Deno/SSR environments where `document` is not defined.\n//\n// PERF: This top-level side effect intentionally runs on every per-component import.\n// Without it, components would render without design tokens until a consumer manually\n// calls ensureDocumentTokens(). This trade-off is acceptable because:\n// 1. The function is idempotent (Symbol.for marker prevents duplicate adoption)\n// 2. The CSSStyleSheet is shared across all components (~2KB overhead, not per-component)\n// 3. Tree-shakers correctly identify this file via the package.json sideEffects array\n// 4. SSR environments are guarded by the typeof document check\n//\n// To use components without auto-adoption (e.g., in a custom shadow root without\n// document-level tokens), import the component directly from its module path and\n// call ensureDocumentTokens() manually when ready.\nif (typeof document !== 'undefined') {\n  ensureDocumentTokens();\n}\n","/**\n * @module HelixAuditController\n *\n * A Lit ReactiveController that captures `hx-*` CustomEvents on the host\n * element and re-dispatches them as enriched `hx-audit` events that bubble to\n * the document level. Designed for HIPAA audit-trail infrastructure in\n * enterprise healthcare deployments.\n *\n * @example\n * ```ts\n * import { HelixAuditController } from '../controllers/helix-audit-controller.js';\n *\n * class MyElement extends LitElement {\n *   private _audit = new HelixAuditController(this, {\n *     userId: 'user-123',\n *     patientContextId: 'patient-456',\n *     encounterId: 'encounter-789',\n *   });\n * }\n * ```\n *\n * At the application boundary, wire a single document-level listener to forward\n * events to your HIPAA audit log infrastructure:\n *\n * ```ts\n * document.addEventListener('hx-audit', (e) => {\n *   const detail = (e as CustomEvent<AuditEventDetail>).detail;\n *   auditLogService.record(detail);\n * });\n * ```\n */\nimport type { ReactiveController, ReactiveControllerHost } from 'lit';\n\n/**\n * The structured payload carried in every `hx-audit` CustomEvent.\n */\nexport interface AuditEventDetail {\n  /** Stable correlation ID generated once per controller instance. */\n  sessionId: string;\n  /** ISO-8601 timestamp at the moment of capture. */\n  timestamp: string;\n  /** Lowercase tag name of the host element (e.g. `\"hx-button\"`). */\n  tagName: string;\n  /** The original `hx-*` event type that triggered this audit record. */\n  sourceEventType: string;\n  /** The original event's `detail` payload, preserved verbatim. */\n  sourceEventDetail: unknown;\n  /** Optional user identifier for the authenticated session. */\n  userId?: string;\n  /** Optional patient context identifier for clinical audit trails. */\n  patientContextId?: string;\n  /** Optional encounter/visit identifier for clinical audit trails. */\n  encounterId?: string;\n  /** Additional caller-supplied key/value metadata. */\n  [key: string]: unknown;\n}\n\n/**\n * Options accepted by `HelixAuditController` at construction time and via\n * `updateMetadata()`.\n */\nexport interface AuditControllerOptions {\n  /** Authenticated user identifier. */\n  userId?: string;\n  /** Patient context identifier. */\n  patientContextId?: string;\n  /** Clinical encounter / visit identifier. */\n  encounterId?: string;\n  /** Arbitrary additional metadata to merge into every audit record. */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * All `hx-*` event types defined in the HELiX component library that should\n * be captured for audit. When a new event is added to the library, adding it\n * here ensures automatic audit coverage with zero other changes required.\n *\n * The DOM event model does not support wildcard subscriptions, so we maintain\n * this explicit list and attach/detach one listener per type — a single bound\n * handler object is reused across all registrations for memory efficiency.\n */\nconst HX_EVENT_TYPES = [\n  'hx-click',\n  'hx-input',\n  'hx-change',\n  'hx-open',\n  'hx-close',\n  'hx-select',\n  'hx-submit',\n  'hx-reset',\n  'hx-sort',\n  'hx-filter',\n  'hx-page-change',\n  'hx-tab-change',\n  'hx-expand',\n  'hx-collapse',\n  'hx-copy',\n  'hx-upload',\n  'hx-remove',\n  'hx-rate',\n  'hx-toggle',\n  'hx-dismiss',\n  'hx-phi-access',\n] as const;\n\n/**\n * Generates a unique session correlation ID. Uses `crypto.randomUUID()` when\n * available and falls back to a timestamp-seeded pseudo-random string for\n * environments that do not expose the Web Crypto API (e.g. SSR, jsdom without\n * the crypto polyfill).\n */\nfunction generateSessionId(): string {\n  if (typeof crypto !== 'undefined' && typeof (crypto as Crypto).randomUUID === 'function') {\n    return (crypto as Crypto).randomUUID();\n  }\n  // Fallback: formatted as a UUID v4 lookalike so downstream parsers that\n  // expect that shape don't break.\n  const t = Date.now().toString(16).padStart(12, '0');\n  const r1 = Math.random().toString(16).slice(2, 10).padStart(8, '0');\n  const r2 = Math.random().toString(16).slice(2, 14).padStart(12, '0');\n  return `${t.slice(0, 8)}-${t.slice(8)}-4${r1.slice(0, 3)}-${r2.slice(0, 4)}-${r2.slice(4)}`;\n}\n\n/**\n * Attaches to a Lit `ReactiveControllerHost` (any `LitElement`) and silently\n * captures all `hx-*` events, enriching them with session, timestamp, and\n * optional clinical metadata before re-dispatching as `hx-audit` events.\n *\n * Because all HELiX component events are dispatched with\n * `bubbles: true, composed: true`, they propagate from inside the shadow DOM\n * up to the host element — where this controller's listeners are registered —\n * and then continue bubbling to `document`, making the `hx-audit` event\n * observable anywhere in the page without requiring a global listener.\n */\nexport class HelixAuditController implements ReactiveController {\n  private readonly _host: ReactiveControllerHost & EventTarget;\n  private readonly _sessionId: string;\n  private _options: AuditControllerOptions;\n\n  /**\n   * A single `EventListenerObject` reused across all event-type registrations.\n   * Using the object form (rather than a bound function) avoids creating a new\n   * closure per event type while still keeping `this` bound correctly.\n   */\n  private readonly _listener: EventListenerObject;\n\n  constructor(host: ReactiveControllerHost & EventTarget, options: AuditControllerOptions = {}) {\n    this._host = host;\n    this._sessionId = generateSessionId();\n    this._options = options;\n    this._listener = { handleEvent: this._onHxEvent.bind(this) };\n    this._host.addController(this);\n  }\n\n  /**\n   * Updates the metadata attached to future audit records. Useful when the\n   * authenticated user, patient context, or encounter changes after the\n   * component is connected (e.g. patient context switch within a session).\n   */\n  updateMetadata(options: AuditControllerOptions): void {\n    this._options = { ...this._options, ...options };\n  }\n\n  hostConnected(): void {\n    for (const type of HX_EVENT_TYPES) {\n      this._host.addEventListener(type, this._listener);\n    }\n  }\n\n  hostDisconnected(): void {\n    for (const type of HX_EVENT_TYPES) {\n      this._host.removeEventListener(type, this._listener);\n    }\n  }\n\n  private _onHxEvent(event: Event): void {\n    // Guard: only process events whose type starts with 'hx-'.\n    if (!event.type.startsWith('hx-')) return;\n    // Guard: prevent recursion — never audit the audit event itself.\n    if (event.type === 'hx-audit') return;\n\n    const sourceDetail = event instanceof CustomEvent ? event.detail : undefined;\n\n    const tagName = this._host instanceof Element ? this._host.tagName.toLowerCase() : 'unknown';\n\n    const { userId, patientContextId, encounterId, metadata } = this._options;\n\n    const detail: AuditEventDetail = {\n      sessionId: this._sessionId,\n      timestamp: new Date().toISOString(),\n      tagName,\n      sourceEventType: event.type,\n      sourceEventDetail: sourceDetail,\n      ...(userId !== undefined ? { userId } : {}),\n      ...(patientContextId !== undefined ? { patientContextId } : {}),\n      ...(encounterId !== undefined ? { encounterId } : {}),\n      ...metadata,\n    };\n\n    this._host.dispatchEvent(\n      new CustomEvent<AuditEventDetail>('hx-audit', {\n        bubbles: true,\n        composed: true,\n        detail,\n      }),\n    );\n  }\n}\n"],"names":["MARKER","ensureDocumentTokens","doc","cssText","lightTokenCss","sheet","HX_EVENT_TYPES","generateSessionId","r1","r2","HelixAuditController","host","options","type","event","sourceDetail","tagName","userId","patientContextId","encounterId","metadata","detail"],"mappings":"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"}

package/dist/mixins/FormMixin.d.ts

@@ -6,6 +6,7 @@ import { HelixElement } from '../base/helix-element.js';
 type Constructor<T = object> = new (...args: any[]) => T;
 /**
  * The public interface that FormMixin adds to any host element.
+ * Contains only the API that external consumers may access.
  *
  * @public
  */
@@ -20,21 +21,39 @@ export interface FormMixinInterface {
     checkValidity(): boolean;
     /** Delegates to ElementInternals.reportValidity(). */
     reportValidity(): boolean;
+}
+/**
+ * Protected subclassing hooks provided by FormMixin.
+ *
+ * These are part of the stable subclassing contract (breaking changes gated
+ * to major releases) but are NOT exposed as public consumer API.
+ * They are accessible only from within FormMixin subclasses.
+ *
+ * @protected
+ */
+export interface FormMixinProtectedHooks {
     /**
      * Advance `dirty` state. Call from the native input's `input` event handler.
-     * @internal
+     * @protected
      */
     _handleInteractionInput(): void;
     /**
      * Advance `touched` state. Call from the native input's `blur` event handler.
-     * @internal
+     * @protected
      */
     _handleInteractionBlur(): void;
     /**
      * Reset interaction flags. Call from `_onFormReset()` in the host component.
-     * @internal
+     * @protected
      */
     _resetInteractionState(): void;
+    /**
+     * Override in the host component to run constraint validation logic.
+     * Called automatically by `updated()`. Use `this._internals.setValidity()`
+     * inside this method.
+     * @protected
+     */
+    _updateValidity(...args: unknown[]): void;
 }
 /**
  * FormMixin adds shared form infrastructure to any HelixElement subclass:
@@ -49,7 +68,7 @@ export interface FormMixinInterface {
  * @example
  * ```ts
  * class HxTextInput extends FormMixin(HelixElement) {
- *   protected override _updateValidity(): void {
+ *   override _updateValidity(): void {
  *     if (this.required && !this.value) {
  *       this._internals.setValidity({ valueMissing: true }, 'Required', this._inputEl);
  *     } else {
@@ -64,6 +83,6 @@ export interface FormMixinInterface {
  *
  * @public
  */
-export declare function FormMixin<TBase extends Constructor<HelixElement>>(superClass: TBase): TBase & Constructor<FormMixinInterface>;
+export declare function FormMixin<TBase extends Constructor<HelixElement>>(superClass: TBase): TBase & Constructor<FormMixinInterface & FormMixinProtectedHooks>;
 export {};
 //# sourceMappingURL=FormMixin.d.ts.map

package/dist/mixins/FormMixin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FormMixin.d.ts","sourceRoot":"","sources":["../../src/mixins/FormMixin.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD;;;GAGG;AAEH,KAAK,WAAW,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,qDAAqD;IACrD,aAAa,IAAI,OAAO,CAAC;IACzB,sDAAsD;IACtD,cAAc,IAAI,OAAO,CAAC;IAE1B;;;OAGG;IACH,uBAAuB,IAAI,IAAI,CAAC;IAEhC;;;OAGG;IACH,sBAAsB,IAAI,IAAI,CAAC;IAE/B;;;OAGG;IACH,sBAAsB,IAAI,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,KAAK,SAAS,WAAW,CAAC,YAAY,CAAC,EAC/D,UAAU,EAAE,KAAK,GAChB,KAAK,GAAG,WAAW,CAAC,kBAAkB,CAAC,CAmHzC"}
+{"version":3,"file":"FormMixin.d.ts","sourceRoot":"","sources":["../../src/mixins/FormMixin.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD;;;GAGG;AAEH,KAAK,WAAW,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,qDAAqD;IACrD,aAAa,IAAI,OAAO,CAAC;IACzB,sDAAsD;IACtD,cAAc,IAAI,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,uBAAuB,IAAI,IAAI,CAAC;IAEhC;;;OAGG;IACH,sBAAsB,IAAI,IAAI,CAAC;IAE/B;;;OAGG;IACH,sBAAsB,IAAI,IAAI,CAAC;IAE/B;;;;;OAKG;IACH,eAAe,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,KAAK,SAAS,WAAW,CAAC,YAAY,CAAC,EAC/D,UAAU,EAAE,KAAK,GAChB,KAAK,GAAG,WAAW,CAAC,kBAAkB,GAAG,uBAAuB,CAAC,CAiInE"}

package/dist/mixins/aria-delegation.d.ts

@@ -12,7 +12,7 @@ type LitElementConstructor = new (...args: any[]) => LitElement;
  * JS property accessors for all intercepted ARIA attributes, reading from
  * `data-aria-*` storage rather than `aria-*` attributes on the host.
  */
-export interface AriadDelegationMixinInterface {
+export interface AriaDelegationMixinInterface {
     ariaActiveDescendant: string | null;
     ariaAtomic: string | null;
     ariaAutoComplete: string | null;

package/dist/mixins/aria-delegation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aria-delegation.d.ts","sourceRoot":"","sources":["../../src/mixins/aria-delegation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"aria-delegation.d.ts","sourceRoot":"","sources":["../../src/mixins/aria-delegation.ts"],"names":[],"mappings":"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"}

package/dist/mixins/index.d.ts

@@ -1,5 +1,7 @@
 export { mixinDelegatesAria } from './aria-delegation.js';
-export type { AriadDelegationMixinInterface, AriaAttribute } from './aria-delegation.js';
+export type { AriaDelegationMixinInterface, AriaAttribute } from './aria-delegation.js';
 export { FocusMixin } from './FocusMixin.js';
 export type { FocusMixinInterface } from './FocusMixin.js';
+export { FormMixin } from './FormMixin.js';
+export type { FormMixinInterface } from './FormMixin.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/mixins/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mixins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,6BAA6B,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mixins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,4BAA4B,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/shared/{FormMixin-Bjvw20G5.js → FormMixin-B8PXk5RQ.js}

@@ -1,5 +1,5 @@
-function s(t) {
-  class e extends t {
+function d(e) {
+  class i extends e {
     constructor() {
       super(...arguments), this._dirty = !1, this._touched = !1;
     }
@@ -44,45 +44,62 @@ function s(t) {
      * Calls `_updateValidity()` after every Lit update cycle.
      * @internal
      */
-    updated(i) {
-      super.updated(i), this._updateValidity();
+    updated(t) {
+      super.updated(t), this._updateValidity();
     }
     // ─── Hook Methods ────────────────────────────────────────────────────────
     /**
      * Override in the host component to run constraint validation logic.
      * Called automatically by `updated()`. Use `this._internals.setValidity()`
      * inside this method.
-     * @internal
+     *
+     * Part of the FormMixin subclassing contract — compiler-enforced protected;
+     * do not call from outside a subclass.
      */
     _updateValidity() {
     }
     // ─── Interaction State Helpers ───────────────────────────────────────────
     /**
      * Advance `dirty` state. Call from the native input's `input` event.
-     * @internal
+     *
+     * Part of the FormMixin subclassing contract — compiler-enforced protected;
+     * do not call from outside a subclass.
      */
     _handleInteractionInput() {
-      this._dirty || (this._dirty = !0, this.requestUpdate());
+      if (!this._dirty) {
+        const t = this._dirty;
+        this._dirty = !0, this.requestUpdate("_dirty", t);
+      }
     }
     /**
      * Advance `touched` state. Call from the native input's `blur` event.
-     * @internal
+     *
+     * Part of the FormMixin subclassing contract — compiler-enforced protected;
+     * do not call from outside a subclass.
      */
     _handleInteractionBlur() {
-      this._touched || (this._touched = !0, this.requestUpdate());
+      if (!this._touched) {
+        const t = this._touched;
+        this._touched = !0, this.requestUpdate("_touched", t);
+      }
     }
     /**
      * Reset interaction state to initial values.
      * Call from `_onFormReset()` in the host component.
-     * @internal
+     *
+     * Part of the FormMixin subclassing contract — compiler-enforced protected;
+     * do not call from outside a subclass.
      */
     _resetInteractionState() {
-      (this._dirty || this._touched) && (this._dirty = !1, this._touched = !1, this.requestUpdate());
+      if (this._dirty || this._touched) {
+        const t = this._dirty, r = this._touched;
+        this._dirty = !1, this._touched = !1, this.requestUpdate("_dirty", t), this.requestUpdate("_touched", r);
+      }
     }
   }
-  return e;
+  return i;
 }
 export {
-  s as F
+  d as F
 };
-//# sourceMappingURL=FormMixin-Bjvw20G5.js.map
+//# sourceMappingURL=FormMixin-B8PXk5RQ.js.map

package/dist/shared/FormMixin-B8PXk5RQ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormMixin-B8PXk5RQ.js","sources":["../../src/mixins/FormMixin.ts"],"sourcesContent":["import type { PropertyValues } from 'lit';\nimport { HelixElement } from '../base/helix-element.js';\n\n/**\n * Constructor type for the mixin pattern.\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype Constructor<T = object> = new (...args: any[]) => T;\n\n/**\n * The public interface that FormMixin adds to any host element.\n * Contains only the API that external consumers may access.\n *\n * @public\n */\nexport interface FormMixinInterface {\n  /** True after the user has modified the field value at least once. */\n  readonly dirty: boolean;\n  /** True after the field has received and lost focus at least once. */\n  readonly touched: boolean;\n  /** True while the field has never been modified (opposite of dirty). */\n  readonly pristine: boolean;\n\n  /** Delegates to ElementInternals.checkValidity(). */\n  checkValidity(): boolean;\n  /** Delegates to ElementInternals.reportValidity(). */\n  reportValidity(): boolean;\n}\n\n/**\n * Protected subclassing hooks provided by FormMixin.\n *\n * These are part of the stable subclassing contract (breaking changes gated\n * to major releases) but are NOT exposed as public consumer API.\n * They are accessible only from within FormMixin subclasses.\n *\n * @protected\n */\nexport interface FormMixinProtectedHooks {\n  /**\n   * Advance `dirty` state. Call from the native input's `input` event handler.\n   * @protected\n   */\n  _handleInteractionInput(): void;\n\n  /**\n   * Advance `touched` state. Call from the native input's `blur` event handler.\n   * @protected\n   */\n  _handleInteractionBlur(): void;\n\n  /**\n   * Reset interaction flags. Call from `_onFormReset()` in the host component.\n   * @protected\n   */\n  _resetInteractionState(): void;\n\n  /**\n   * Override in the host component to run constraint validation logic.\n   * Called automatically by `updated()`. Use `this._internals.setValidity()`\n   * inside this method.\n   * @protected\n   */\n  _updateValidity(...args: unknown[]): void;\n}\n\n/**\n * FormMixin adds shared form infrastructure to any HelixElement subclass:\n *\n * - Interaction state tracking: `dirty`, `touched`, `pristine`\n * - `checkValidity()` / `reportValidity()` delegation to `ElementInternals`\n * - A `_updateValidity()` lifecycle hook called automatically after every\n *   `updated()` cycle — subclasses override this to run constraint checks\n * - `_handleInteractionBlur()` and `_handleInteractionInput()` helpers that\n *   components wire to their native inputs to advance interaction state\n *\n * @example\n * ```ts\n * class HxTextInput extends FormMixin(HelixElement) {\n *   override _updateValidity(): void {\n *     if (this.required && !this.value) {\n *       this._internals.setValidity({ valueMissing: true }, 'Required', this._inputEl);\n *     } else {\n *       this._internals.setValidity({});\n *     }\n *   }\n * }\n * ```\n *\n * @param superClass - A HelixElement-derived constructor to mix into\n * @returns The mixed class constructor with form interaction state tracking\n *\n * @public\n */\nexport function FormMixin<TBase extends Constructor<HelixElement>>(\n  superClass: TBase,\n): TBase & Constructor<FormMixinInterface & FormMixinProtectedHooks> {\n  class FormMixinClass extends (superClass as Constructor<HelixElement>) {\n    // ─── Interaction State ───────────────────────────────────────────────────\n\n    /** @internal */\n    private _dirty = false;\n\n    /** @internal */\n    private _touched = false;\n\n    // ─── Public Getters ──────────────────────────────────────────────────────\n\n    /**\n     * True after the user has modified the field value at least once.\n     * Resets to false on form reset.\n     */\n    get dirty(): boolean {\n      return this._dirty;\n    }\n\n    /**\n     * True after the field has received and lost focus at least once.\n     * Resets to false on form reset.\n     */\n    get touched(): boolean {\n      return this._touched;\n    }\n\n    /**\n     * True while the field has never been modified. Opposite of `dirty`.\n     */\n    get pristine(): boolean {\n      return !this._dirty;\n    }\n\n    // ─── Validity Delegation ─────────────────────────────────────────────────\n\n    /**\n     * Delegates to `ElementInternals.checkValidity()`.\n     * The host element must have `static formAssociated = true`.\n     */\n    checkValidity(): boolean {\n      return this._internals.checkValidity();\n    }\n\n    /**\n     * Delegates to `ElementInternals.reportValidity()`.\n     * The host element must have `static formAssociated = true`.\n     */\n    reportValidity(): boolean {\n      return this._internals.reportValidity();\n    }\n\n    // ─── Lifecycle ───────────────────────────────────────────────────────────\n\n    /**\n     * Calls `_updateValidity()` after every Lit update cycle.\n     * @internal\n     */\n    override updated(changedProperties: PropertyValues): void {\n      super.updated(changedProperties);\n      this._updateValidity();\n    }\n\n    // ─── Hook Methods ────────────────────────────────────────────────────────\n\n    /**\n     * Override in the host component to run constraint validation logic.\n     * Called automatically by `updated()`. Use `this._internals.setValidity()`\n     * inside this method.\n     *\n     * Part of the FormMixin subclassing contract — compiler-enforced protected;\n     * do not call from outside a subclass.\n     */\n    protected _updateValidity(): void {\n      // Default: valid. Subclasses override to apply constraints.\n    }\n\n    // ─── Interaction State Helpers ───────────────────────────────────────────\n\n    /**\n     * Advance `dirty` state. Call from the native input's `input` event.\n     *\n     * Part of the FormMixin subclassing contract — compiler-enforced protected;\n     * do not call from outside a subclass.\n     */\n    protected _handleInteractionInput(): void {\n      if (!this._dirty) {\n        const prev = this._dirty;\n        this._dirty = true;\n        this.requestUpdate('_dirty', prev);\n      }\n    }\n\n    /**\n     * Advance `touched` state. Call from the native input's `blur` event.\n     *\n     * Part of the FormMixin subclassing contract — compiler-enforced protected;\n     * do not call from outside a subclass.\n     */\n    protected _handleInteractionBlur(): void {\n      if (!this._touched) {\n        const prev = this._touched;\n        this._touched = true;\n        this.requestUpdate('_touched', prev);\n      }\n    }\n\n    /**\n     * Reset interaction state to initial values.\n     * Call from `_onFormReset()` in the host component.\n     *\n     * Part of the FormMixin subclassing contract — compiler-enforced protected;\n     * do not call from outside a subclass.\n     */\n    protected _resetInteractionState(): void {\n      if (this._dirty || this._touched) {\n        const prevDirty = this._dirty;\n        const prevTouched = this._touched;\n        this._dirty = false;\n        this._touched = false;\n        this.requestUpdate('_dirty', prevDirty);\n        this.requestUpdate('_touched', prevTouched);\n      }\n    }\n  }\n\n  return FormMixinClass as unknown as TBase &\n    Constructor<FormMixinInterface & FormMixinProtectedHooks>;\n}\n"],"names":["FormMixin","superClass","FormMixinClass","changedProperties","prev","prevDirty","prevTouched"],"mappings":"AA+FO,SAASA,EACdC,GACmE;AAAA,EACnE,MAAMC,UAAwBD,EAAyC;AAAA,IAAvE,cAAA;AAAA,YAAA,GAAA,SAAA,GAIE,KAAQ,SAAS,IAGjB,KAAQ,WAAW;AAAA,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQnB,IAAI,QAAiB;AACnB,aAAO,KAAK;AAAA,IACd;AAAA;AAAA;AAAA;AAAA;AAAA,IAMA,IAAI,UAAmB;AACrB,aAAO,KAAK;AAAA,IACd;AAAA;AAAA;AAAA;AAAA,IAKA,IAAI,WAAoB;AACtB,aAAO,CAAC,KAAK;AAAA,IACf;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQA,gBAAyB;AACvB,aAAO,KAAK,WAAW,cAAA;AAAA,IACzB;AAAA;AAAA;AAAA;AAAA;AAAA,IAMA,iBAA0B;AACxB,aAAO,KAAK,WAAW,eAAA;AAAA,IACzB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQS,QAAQE,GAAyC;AACxD,YAAM,QAAQA,CAAiB,GAC/B,KAAK,gBAAA;AAAA,IACP;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAYU,kBAAwB;AAAA,IAElC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAUU,0BAAgC;AACxC,UAAI,CAAC,KAAK,QAAQ;AAChB,cAAMC,IAAO,KAAK;AAClB,aAAK,SAAS,IACd,KAAK,cAAc,UAAUA,CAAI;AAAA,MACnC;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQU,yBAA+B;AACvC,UAAI,CAAC,KAAK,UAAU;AAClB,cAAMA,IAAO,KAAK;AAClB,aAAK,WAAW,IAChB,KAAK,cAAc,YAAYA,CAAI;AAAA,MACrC;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IASU,yBAA+B;AACvC,UAAI,KAAK,UAAU,KAAK,UAAU;AAChC,cAAMC,IAAY,KAAK,QACjBC,IAAc,KAAK;AACzB,aAAK,SAAS,IACd,KAAK,WAAW,IAChB,KAAK,cAAc,UAAUD,CAAS,GACtC,KAAK,cAAc,YAAYC,CAAW;AAAA,MAC5C;AAAA,IACF;AAAA,EAAA;AAGF,SAAOJ;AAET;"}

package/dist/shared/{aria-delegation-CBP9eQ0M.js → aria-delegation-Doq6RRUy.js}

@@ -1,8 +1,8 @@
-var d = (e) => {
+var u = (e) => {
   throw TypeError(e);
 };
-var h = (e, a, r) => a.has(e) || d("Cannot " + r);
-var c = (e, a, r) => (h(e, a, "read from private field"), r ? r.call(e) : a.get(e)), b = (e, a, r) => a.has(e) ? d("Cannot add the same private member more than once") : a instanceof WeakSet ? a.add(e) : a.set(e, r);
+var h = (e, a, r) => a.has(e) || u("Cannot " + r);
+var c = (e, a, r) => (h(e, a, "read from private field"), r ? r.call(e) : a.get(e)), b = (e, a, r) => a.has(e) ? u("Cannot add the same private member more than once") : a instanceof WeakSet ? a.add(e) : a.set(e, r);
 const n = [
   "aria-activedescendant",
   "aria-atomic",
@@ -83,8 +83,8 @@ function v(e) {
   r = new WeakMap();
   let a = o;
   for (const s of n) {
-    const u = s === "role" ? "role" : A(s), t = `data-${s}`;
-    Object.defineProperty(a.prototype, u, {
+    const d = s === "role" ? "role" : A(s), t = `data-${s}`;
+    Object.defineProperty(a.prototype, d, {
       get() {
         return this.getAttribute(t);
       },
@@ -104,4 +104,4 @@ function A(e) {
 export {
   v as m
 };
-//# sourceMappingURL=aria-delegation-CBP9eQ0M.js.map
+//# sourceMappingURL=aria-delegation-Doq6RRUy.js.map

package/dist/shared/aria-delegation-Doq6RRUy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aria-delegation-Doq6RRUy.js","sources":["../../src/mixins/aria-delegation.ts"],"sourcesContent":["import type { LitElement } from 'lit';\n\n/**\n * All standard ARIA attributes intercepted by this mixin.\n * Extend as needed, but keep the list minimal.\n */\nconst ARIA_ATTRIBUTES = [\n  'aria-activedescendant',\n  'aria-atomic',\n  'aria-autocomplete',\n  'aria-braillelabel',\n  'aria-brailleroledescription',\n  'aria-busy',\n  'aria-checked',\n  'aria-colcount',\n  'aria-colindex',\n  'aria-colindextext',\n  'aria-colspan',\n  'aria-controls',\n  'aria-current',\n  'aria-describedby',\n  'aria-description',\n  'aria-details',\n  'aria-disabled',\n  'aria-errormessage',\n  'aria-expanded',\n  'aria-flowto',\n  'aria-haspopup',\n  'aria-hidden',\n  'aria-invalid',\n  'aria-keyshortcuts',\n  'aria-label',\n  'aria-labelledby',\n  'aria-level',\n  'aria-live',\n  'aria-modal',\n  'aria-multiline',\n  'aria-multiselectable',\n  'aria-orientation',\n  'aria-owns',\n  'aria-placeholder',\n  'aria-posinset',\n  'aria-pressed',\n  'aria-readonly',\n  'aria-relevant',\n  'aria-required',\n  'aria-roledescription',\n  'aria-rowcount',\n  'aria-rowindex',\n  'aria-rowindextext',\n  'aria-rowspan',\n  'aria-selected',\n  'aria-setsize',\n  'aria-sort',\n  'aria-valuemax',\n  'aria-valuemin',\n  'aria-valuenow',\n  'aria-valuetext',\n  'role',\n] as const;\n\n/** Union type of all intercepted ARIA attribute names. */\nexport type AriaAttribute = (typeof ARIA_ATTRIBUTES)[number];\n\n// TypeScript mixin constraint: constructors must accept `any[]`.\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype LitElementConstructor = new (...args: any[]) => LitElement;\n\n/**\n * The public interface added to any class by `mixinDelegatesAria`.\n * JS property accessors for all intercepted ARIA attributes, reading from\n * `data-aria-*` storage rather than `aria-*` attributes on the host.\n */\n\nexport interface AriaDelegationMixinInterface {\n  ariaActiveDescendant: string | null;\n  ariaAtomic: string | null;\n  ariaAutoComplete: string | null;\n  ariaBrailleLabel: string | null;\n  ariaBrailleRoleDescription: string | null;\n  ariaBusy: string | null;\n  ariaChecked: string | null;\n  ariaColCount: string | null;\n  ariaColIndex: string | null;\n  ariaColIndexText: string | null;\n  ariaColSpan: string | null;\n  ariaControls: string | null;\n  ariaCurrent: string | null;\n  ariaDescribedBy: string | null;\n  ariaDescription: string | null;\n  ariaDetails: string | null;\n  ariaDisabled: string | null;\n  ariaErrorMessage: string | null;\n  ariaExpanded: string | null;\n  ariaFlowTo: string | null;\n  ariaHasPopup: string | null;\n  ariaHidden: string | null;\n  ariaInvalid: string | null;\n  ariaKeyShortcuts: string | null;\n  ariaLabel: string | null;\n  ariaLabelledBy: string | null;\n  ariaLevel: string | null;\n  ariaLive: string | null;\n  ariaModal: string | null;\n  ariaMultiLine: string | null;\n  ariaMultiSelectable: string | null;\n  ariaOrientation: string | null;\n  ariaOwns: string | null;\n  ariaPlaceholder: string | null;\n  ariaPosInSet: string | null;\n  ariaPressed: string | null;\n  ariaReadOnly: string | null;\n  ariaRelevant: string | null;\n  ariaRequired: string | null;\n  ariaRoleDescription: string | null;\n  ariaRowCount: string | null;\n  ariaRowIndex: string | null;\n  ariaRowIndexText: string | null;\n  ariaRowSpan: string | null;\n  ariaSelected: string | null;\n  ariaSetSize: string | null;\n  ariaSort: string | null;\n  ariaValueMax: string | null;\n  ariaValueMin: string | null;\n  ariaValueNow: string | null;\n  ariaValueText: string | null;\n  role: string | null;\n}\n\n/**\n * Mixin that delegates ARIA attributes from the host element to data-aria-* storage,\n * preventing Shadow DOM double-announcement by screen readers.\n *\n * When a custom element uses `delegatesFocus: true`, the focus delegate (inner element)\n * and the host are both in the a11y tree. Setting `aria-label` on the host causes the\n * label to be announced twice — once for the host, once for the focused inner element.\n *\n * This mixin intercepts `attributeChangedCallback` for all ARIA attributes:\n * - Shifts the value from `aria-*` to `data-aria-*` on the host\n * - Provides JS property accessors that read from `data-aria-*`\n * - The host element no longer has `aria-*` attributes visible in the a11y tree\n * - Components read ARIA values via property accessors and apply them to inner elements\n *\n * @example\n * ```ts\n * class HxButton extends mixinDelegatesAria(LitElement) {\n *   render() {\n *     return html`<button aria-label=${this.ariaLabel ?? nothing}></button>`;\n *   }\n * }\n * ```\n *\n * @param Base - A LitElement subclass constructor\n * @returns A new constructor extending Base with ARIA delegation behaviour\n */\nexport function mixinDelegatesAria<T extends LitElementConstructor>(Base: T): T {\n  class AriaDelegationMixin extends Base {\n    // Per-instance guard: tracks which aria attributes are mid-processing so\n    // that the recursive attributeChangedCallback triggered by our own\n    // removeAttribute(name) call does not erroneously clear data-aria-*.\n    #processingAria = new Set<string>();\n\n    static get observedAttributes(): string[] {\n      // Reflect.get with `this` as the receiver passes the concrete subclass\n      // (e.g. HelixButton) through to Lit's ReactiveElement getter, so it\n      // returns @property attribute names for that specific class.\n      // TypeScript cannot infer static members on `T`, so we use Reflect.get\n      // rather than `super.observedAttributes` to avoid TS2339.\n      const parent: object = Object.getPrototypeOf(AriaDelegationMixin);\n      const superAttrs: string[] =\n        (Reflect.get(parent, 'observedAttributes', this) as string[] | undefined) ?? [];\n      // Append any ARIA attributes not already in the list.\n      const ariaAttrs = ARIA_ATTRIBUTES.filter((a) => !superAttrs.includes(a));\n      return [...superAttrs, ...ariaAttrs];\n    }\n\n    attributeChangedCallback(name: string, old: string | null, next: string | null): void {\n      if ((ARIA_ATTRIBUTES as readonly string[]).includes(name)) {\n        // Guard: if we're already processing this attribute, we're in the\n        // recursive callback triggered by our own removeAttribute(name) below.\n        // Do not process it again — that would clear data-aria-* incorrectly.\n        if (this.#processingAria.has(name)) return;\n\n        // Intercept: store as data-aria-*, do not propagate aria-* to the host.\n        if (next !== null) {\n          // data-aria-* is not in observedAttributes — no recursive loop here.\n          this.setAttribute(`data-${name}`, next);\n        } else {\n          this.removeAttribute(`data-${name}`);\n        }\n\n        // Remove the aria-* attribute from the host so it is absent from the\n        // a11y tree and cannot cause double announcements. Guard while doing so.\n        this.#processingAria.add(name);\n        if (this.hasAttribute(name)) {\n          this.removeAttribute(name); // synchronously re-enters attributeChangedCallback; guard catches it\n        }\n        this.#processingAria.delete(name);\n\n        // Trigger Lit update so render() re-reads the delegated value.\n        this.requestUpdate();\n        return;\n      }\n      super.attributeChangedCallback(name, old, next);\n    }\n  }\n\n  // Add JS property accessors for each ARIA attribute, reading from data-aria-*\n  for (const attr of ARIA_ATTRIBUTES) {\n    // Convert 'aria-label' → 'ariaLabel', 'role' → 'role'\n    const propName: string = attr === 'role' ? 'role' : ariaAttrToProp(attr);\n    const dataAttr = `data-${attr}`;\n\n    Object.defineProperty(AriaDelegationMixin.prototype, propName, {\n      get(this: Element): string | null {\n        return this.getAttribute(dataAttr);\n      },\n      set(this: LitElement, value: string | null) {\n        if (value === null || value === undefined) {\n          this.removeAttribute(dataAttr);\n          this.removeAttribute(attr);\n        } else {\n          this.setAttribute(dataAttr, value);\n          // Ensure aria-* is NOT present on the host.\n          if (this.hasAttribute(attr)) {\n            this.removeAttribute(attr);\n          }\n        }\n        // Trigger Lit reactive update.\n        this.requestUpdate();\n      },\n      configurable: true,\n      enumerable: false,\n    });\n  }\n\n  // Cast to T to satisfy the declared return type. The AriaDelegationMixinInterface\n  // instance members are added at runtime via Object.defineProperty above; callers\n  // that need the typed accessors should cast the instance or use the interface directly.\n  return AriaDelegationMixin as unknown as T;\n}\n\n/**\n * Converts 'aria-label' → 'ariaLabel', 'aria-busy' → 'ariaBusy', etc.\n * Removes the 'aria-' prefix, capitalizes the first letter of the remainder,\n * then camelCases any additional hyphen-separated segments.\n */\nfunction ariaAttrToProp(attr: string): string {\n  const rest = attr.replace(/^aria-/, '');\n  return (\n    'aria' +\n    rest.charAt(0).toUpperCase() +\n    rest.slice(1).replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())\n  );\n}\n"],"names":["ARIA_ATTRIBUTES","mixinDelegatesAria","Base","_processingAria","_AriaDelegationMixin","__privateAdd","parent","superAttrs","ariaAttrs","a","name","old","next","__privateGet","AriaDelegationMixin","attr","propName","ariaAttrToProp","dataAttr","value","rest","_","c"],"mappings":";;;;;AAMA,MAAMA,IAAkB;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAgGO,SAASC,EAAoDC,GAAY;AArJhF,MAAAC;AAsJE,QAAMC,IAAN,MAAMA,UAA4BF,EAAK;AAAA,IAAvC;AAAA;AAIE;AAAA;AAAA;AAAA,MAAAG,EAAA,MAAAF,uBAAsB,IAAA;AAAA;AAAA,IAEtB,WAAW,qBAA+B;AAMxC,YAAMG,IAAiB,OAAO,eAAeF,CAAmB,GAC1DG,IACH,QAAQ,IAAID,GAAQ,sBAAsB,IAAI,KAA8B,CAAA,GAEzEE,IAAYR,EAAgB,OAAO,CAACS,MAAM,CAACF,EAAW,SAASE,CAAC,CAAC;AACvE,aAAO,CAAC,GAAGF,GAAY,GAAGC,CAAS;AAAA,IACrC;AAAA,IAEA,yBAAyBE,GAAcC,GAAoBC,GAA2B;AACpF,UAAKZ,EAAsC,SAASU,CAAI,GAAG;AAIzD,YAAIG,EAAA,MAAKV,GAAgB,IAAIO,CAAI,EAAG;AAGpC,QAAIE,MAAS,OAEX,KAAK,aAAa,QAAQF,CAAI,IAAIE,CAAI,IAEtC,KAAK,gBAAgB,QAAQF,CAAI,EAAE,GAKrCG,EAAA,MAAKV,GAAgB,IAAIO,CAAI,GACzB,KAAK,aAAaA,CAAI,KACxB,KAAK,gBAAgBA,CAAI,GAE3BG,EAAA,MAAKV,GAAgB,OAAOO,CAAI,GAGhC,KAAK,cAAA;AACL;AAAA,MACF;AACA,YAAM,yBAAyBA,GAAMC,GAAKC,CAAI;AAAA,IAChD;AAAA,EAAA;AA5CA,EAAAT,IAAA;AAJF,MAAMW,IAANV;AAoDA,aAAWW,KAAQf,GAAiB;AAElC,UAAMgB,IAAmBD,MAAS,SAAS,SAASE,EAAeF,CAAI,GACjEG,IAAW,QAAQH,CAAI;AAE7B,WAAO,eAAeD,EAAoB,WAAWE,GAAU;AAAA,MAC7D,MAAkC;AAChC,eAAO,KAAK,aAAaE,CAAQ;AAAA,MACnC;AAAA,MACA,IAAsBC,GAAsB;AAC1C,QAAIA,KAAU,QACZ,KAAK,gBAAgBD,CAAQ,GAC7B,KAAK,gBAAgBH,CAAI,MAEzB,KAAK,aAAaG,GAAUC,CAAK,GAE7B,KAAK,aAAaJ,CAAI,KACxB,KAAK,gBAAgBA,CAAI,IAI7B,KAAK,cAAA;AAAA,MACP;AAAA,MACA,cAAc;AAAA,MACd,YAAY;AAAA,IAAA,CACb;AAAA,EACH;AAKA,SAAOD;AACT;AAOA,SAASG,EAAeF,GAAsB;AAC5C,QAAMK,IAAOL,EAAK,QAAQ,UAAU,EAAE;AACtC,SACE,SACAK,EAAK,OAAO,CAAC,EAAE,YAAA,IACfA,EAAK,MAAM,CAAC,EAAE,QAAQ,aAAa,CAACC,GAAGC,MAAcA,EAAE,aAAa;AAExE;"}

package/dist/shared/{helix-element-CZvaIEQP.js → helix-element-BNEYeiys.js}

@@ -1,35 +1,31 @@
 var a = (s) => {
   throw TypeError(s);
 };
-var c = (s, o, t) => o.has(s) || a("Cannot " + t);
-var i = (s, o, t) => (c(s, o, "read from private field"), t ? t.call(s) : o.get(s)), l = (s, o, t) => o.has(s) ? a("Cannot add the same private member more than once") : o instanceof WeakSet ? o.add(s) : o.set(s, t), d = (s, o, t, e) => (c(s, o, "write to private field"), e ? e.call(s, t) : o.set(s, t), t);
-import { LitElement as h } from "lit";
-var r;
-const n = class n extends h {
+var n = (s, r, t) => r.has(s) || a("Cannot " + t);
+var l = (s, r, t) => (n(s, r, "read from private field"), t ? t.call(s) : r.get(s)), c = (s, r, t) => r.has(s) ? a("Cannot add the same private member more than once") : r instanceof WeakSet ? r.add(s) : r.set(s, t), d = (s, r, t, e) => (n(s, r, "write to private field"), e ? e.call(s, t) : r.set(s, t), t);
+import { LitElement as f } from "lit";
+var o;
+const i = class i extends f {
   constructor() {
     super(...arguments);
-    l(this, r);
+    c(this, o);
   }
   /**
    * Lazy accessor for `ElementInternals`. Calls `attachInternals()` on first
    * access and caches the result.
    *
-   * Only valid when `static formAssociated = true` is declared on the subclass.
-   * Accessing this on a non-form-associated component throws a descriptive error.
+   * Available to ALL components — not just form-associated ones.
+   * `ElementInternals` is also the standard mechanism for setting ARIA roles,
+   * states, and properties from within Shadow DOM (e.g., `this._internals.role`).
    *
-   * @throws {Error} If accessed on a component where `formAssociated` is `false`
    * @internal
    */
   get _internals() {
-    if (!this.constructor.formAssociated)
-      throw new Error(
-        `[HelixElement] _internals accessed on <${this.tagName.toLowerCase()}> but static formAssociated is not set to true on ${this.constructor.name}.`
-      );
-    const t = i(this, r);
+    const t = l(this, o);
     if (t !== void 0)
       return t;
     const e = this.attachInternals();
-    return d(this, r, e), e;
+    return d(this, o, e), e;
   }
   // ─── Browser Form Callbacks (delegate to hook methods) ───
   /**
@@ -65,23 +61,33 @@ const n = class n extends h {
    * Override in subclass to react to the element being disabled or enabled
    * via a parent `<fieldset>`.
    *
+   * Part of the HelixElement subclassing contract (stable across minor/patch
+   * releases; breaking changes gated to major releases).
+   *
    * @param _disabled - `true` when the element is being disabled
-   * @internal
+   * @protected
    */
   _onFormDisabled(t) {
   }
   /**
    * Override in subclass to reset component state when the owning form resets.
-   * @internal
+   *
+   * Part of the HelixElement subclassing contract (stable across minor/patch
+   * releases; breaking changes gated to major releases).
+   *
+   * @protected
    */
   _onFormReset() {
   }
   /**
    * Override in subclass to restore component state from saved form state.
    *
+   * Part of the HelixElement subclassing contract (stable across minor/patch
+   * releases; breaking changes gated to major releases).
+   *
    * @param _state - The saved state value, or `null` if none
    * @param _mode - `'restore'` for bfcache navigation, `'autocomplete'` for autofill
-   * @internal
+   * @protected
    */
   _onFormStateRestore(t, e) {
   }
@@ -96,8 +102,7 @@ const n = class n extends h {
    * @internal
    */
   get form() {
-    const t = i(this, r);
-    return !this.constructor.formAssociated || t === void 0 ? null : t.form;
+    return this.constructor.formAssociated ? this._internals.form : null;
   }
   /**
    * The current `ValidityState` for this element, or `null` if not
@@ -109,8 +114,7 @@ const n = class n extends h {
    * @internal
    */
   get validity() {
-    const t = i(this, r);
-    return !this.constructor.formAssociated || t === void 0 ? null : t.validity;
+    return this.constructor.formAssociated ? this._internals.validity : null;
   }
   /**
    * The current validation message, or an empty string if not form-associated
@@ -119,13 +123,12 @@ const n = class n extends h {
    * @internal
    */
   get validationMessage() {
-    const t = i(this, r);
-    return !this.constructor.formAssociated || t === void 0 ? "" : t.validationMessage;
+    return this.constructor.formAssociated ? this._internals.validationMessage : "";
   }
 };
-r = new WeakMap(), n.formAssociated = !1;
-let m = n;
+o = new WeakMap(), i.formAssociated = !1;
+let m = i;
 export {
   m as H
 };
-//# sourceMappingURL=helix-element-CZvaIEQP.js.map
+//# sourceMappingURL=helix-element-BNEYeiys.js.map

package/dist/shared/helix-element-BNEYeiys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helix-element-BNEYeiys.js","sources":["../../src/base/helix-element.ts"],"sourcesContent":["import { LitElement } from 'lit';\n\n/**\n * `HelixElement` extends `LitElement` with shared infrastructure for all HELiX\n * components: lazy `ElementInternals` access, form lifecycle hook delegation,\n * and convenience validity getters.\n *\n * All subclasses get a lazy `_internals` accessor that calls\n * `attachInternals()` on first access — useful for both form participation\n * and ARIA role/state management via `ElementInternals`.\n *\n * Form association is opt-in via `static formAssociated = true` on the subclass.\n *\n * Form components should also override the `_onForm*` hook methods rather than\n * re-declaring the raw browser callbacks (`formResetCallback`, etc.).\n *\n * @example Non-form component — no configuration required:\n * ```ts\n * class HxCard extends HelixElement {\n *   // no formAssociated needed\n * }\n * ```\n *\n * @example Form-associated component:\n * ```ts\n * class HxTextInput extends HelixElement {\n *   static override formAssociated = true;\n *\n *   override _onFormReset(): void {\n *     this.value = '';\n *     this._internals.setFormValue('');\n *   }\n *\n *   override _onFormDisabled(disabled: boolean): void {\n *     this.disabled = disabled;\n *   }\n * }\n * ```\n *\n * @public\n */\nexport class HelixElement extends LitElement {\n  /**\n   * Set to `true` on the subclass to enable ElementInternals form association.\n   *\n   * IMPORTANT: This MUST be redeclared as `static override formAssociated = true`\n   * on each form-associated subclass. The browser's form association mechanism\n   * inspects `formAssociated` on the *registered* custom element class, not\n   * on ancestor classes.\n   *\n   * @internal\n   */\n  static formAssociated = false;\n\n  #internals: ElementInternals | undefined;\n\n  /**\n   * Lazy accessor for `ElementInternals`. Calls `attachInternals()` on first\n   * access and caches the result.\n   *\n   * Available to ALL components — not just form-associated ones.\n   * `ElementInternals` is also the standard mechanism for setting ARIA roles,\n   * states, and properties from within Shadow DOM (e.g., `this._internals.role`).\n   *\n   * @internal\n   */\n  get _internals(): ElementInternals {\n    const cached = this.#internals;\n    if (cached !== undefined) {\n      return cached;\n    }\n    const internals = this.attachInternals();\n    this.#internals = internals;\n    return internals;\n  }\n\n  // ─── Browser Form Callbacks (delegate to hook methods) ───\n\n  /**\n   * Called by the browser when the element's form-associated disabled state\n   * changes (e.g., a parent `<fieldset disabled>` is toggled).\n   *\n   * Delegates to `_onFormDisabled`. Override that method in subclasses.\n   * @internal\n   */\n  formDisabledCallback(disabled: boolean): void {\n    this._onFormDisabled(disabled);\n  }\n\n  /**\n   * Called by the browser when the owning form is reset.\n   *\n   * Delegates to `_onFormReset`. Override that method in subclasses.\n   * @internal\n   */\n  formResetCallback(): void {\n    this._onFormReset();\n  }\n\n  /**\n   * Called by the browser to restore form state (e.g., back/forward cache).\n   *\n   * Delegates to `_onFormStateRestore`. Override that method in subclasses.\n   * @internal\n   */\n  formStateRestoreCallback(\n    state: File | string | FormData | null,\n    mode: 'restore' | 'autocomplete',\n  ): void {\n    this._onFormStateRestore(state, mode);\n  }\n\n  // ─── Hook Methods (override in subclasses) ───\n\n  /**\n   * Override in subclass to react to the element being disabled or enabled\n   * via a parent `<fieldset>`.\n   *\n   * Part of the HelixElement subclassing contract (stable across minor/patch\n   * releases; breaking changes gated to major releases).\n   *\n   * @param _disabled - `true` when the element is being disabled\n   * @protected\n   */\n  protected _onFormDisabled(_disabled: boolean): void {}\n\n  /**\n   * Override in subclass to reset component state when the owning form resets.\n   *\n   * Part of the HelixElement subclassing contract (stable across minor/patch\n   * releases; breaking changes gated to major releases).\n   *\n   * @protected\n   */\n  protected _onFormReset(): void {}\n\n  /**\n   * Override in subclass to restore component state from saved form state.\n   *\n   * Part of the HelixElement subclassing contract (stable across minor/patch\n   * releases; breaking changes gated to major releases).\n   *\n   * @param _state - The saved state value, or `null` if none\n   * @param _mode - `'restore'` for bfcache navigation, `'autocomplete'` for autofill\n   * @protected\n   */\n  protected _onFormStateRestore(\n    _state: File | string | FormData | null,\n    _mode: 'restore' | 'autocomplete',\n  ): void {}\n\n  // ─── Convenience Getters ───\n\n  /**\n   * The associated form element, or `null` if not form-associated or not yet\n   * connected to a form.\n   *\n   * Form-associated subclasses that need a guaranteed non-null return type\n   * should redeclare this getter and delegate to `this._internals.form`.\n   *\n   * @internal\n   */\n  get form(): HTMLFormElement | null {\n    if (!(this.constructor as typeof HelixElement).formAssociated) {\n      return null;\n    }\n    return this._internals.form;\n  }\n\n  /**\n   * The current `ValidityState` for this element, or `null` if not\n   * form-associated.\n   *\n   * Form-associated subclasses that need a guaranteed `ValidityState` return\n   * should redeclare this getter and delegate to `this._internals.validity`.\n   *\n   * @internal\n   */\n  get validity(): ValidityState | null {\n    if (!(this.constructor as typeof HelixElement).formAssociated) {\n      return null;\n    }\n    return this._internals.validity;\n  }\n\n  /**\n   * The current validation message, or an empty string if not form-associated\n   * or if the element is valid.\n   *\n   * @internal\n   */\n  get validationMessage(): string {\n    if (!(this.constructor as typeof HelixElement).formAssociated) {\n      return '';\n    }\n    return this._internals.validationMessage;\n  }\n}\n"],"names":["_HelixElement","LitElement","__privateAdd","_internals","cached","__privateGet","internals","__privateSet","disabled","state","mode","_disabled","_state","_mode","HelixElement"],"mappings":";;;;;;;AAyCO,MAAMA,IAAN,MAAMA,UAAqBC,EAAW;AAAA,EAAtC;AAAA;AAaL,IAAAC,EAAA,MAAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,IAAI,aAA+B;AACjC,UAAMC,IAASC,EAAA,MAAKF;AACpB,QAAIC,MAAW;AACb,aAAOA;AAET,UAAME,IAAY,KAAK,gBAAA;AACvB,WAAAC,EAAA,MAAKJ,GAAaG,IACXA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,qBAAqBE,GAAyB;AAC5C,SAAK,gBAAgBA,CAAQ;AAAA,EAC/B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,oBAA0B;AACxB,SAAK,aAAA;AAAA,EACP;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,yBACEC,GACAC,GACM;AACN,SAAK,oBAAoBD,GAAOC,CAAI;AAAA,EACtC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcU,gBAAgBC,GAA0B;AAAA,EAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAU3C,eAAqB;AAAA,EAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYtB,oBACRC,GACAC,GACM;AAAA,EAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaT,IAAI,OAA+B;AACjC,WAAM,KAAK,YAAoC,iBAGxC,KAAK,WAAW,OAFd;AAAA,EAGX;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,IAAI,WAAiC;AACnC,WAAM,KAAK,YAAoC,iBAGxC,KAAK,WAAW,WAFd;AAAA,EAGX;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,oBAA4B;AAC9B,WAAM,KAAK,YAAoC,iBAGxC,KAAK,WAAW,oBAFd;AAAA,EAGX;AACF;AA/IEV,IAAA,eAFAH,EAAO,iBAAiB;AAXnB,IAAMc,IAANd;"}