npm - @colletdev/core - Versions diffs - 0.1.3 - Mend

@colletdev/core 0.1.3

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

Files changed (119) hide show

package/README.md +77 -0
package/custom-elements.json +6037 -0
package/generated/.gitattributes +2 -0
package/generated/index.d.ts +120 -0
package/generated/index.js +521 -0
package/generated/styles.js +2845 -0
package/package.json +56 -0
package/src/elements/accordion.d.ts +20 -0
package/src/elements/accordion.js +92 -0
package/src/elements/activity_group.d.ts +19 -0
package/src/elements/activity_group.js +27 -0
package/src/elements/alert.d.ts +24 -0
package/src/elements/alert.js +40 -0
package/src/elements/autocomplete.d.ts +30 -0
package/src/elements/autocomplete.js +671 -0
package/src/elements/avatar.d.ts +18 -0
package/src/elements/avatar.js +28 -0
package/src/elements/backdrop.d.ts +14 -0
package/src/elements/backdrop.js +28 -0
package/src/elements/badge.d.ts +21 -0
package/src/elements/badge.js +42 -0
package/src/elements/breadcrumb.d.ts +17 -0
package/src/elements/breadcrumb.js +41 -0
package/src/elements/button.d.ts +24 -0
package/src/elements/button.js +36 -0
package/src/elements/card.d.ts +21 -0
package/src/elements/card.js +67 -0
package/src/elements/carousel.d.ts +23 -0
package/src/elements/carousel.js +895 -0
package/src/elements/chat_input.d.ts +22 -0
package/src/elements/chat_input.js +78 -0
package/src/elements/checkbox.d.ts +21 -0
package/src/elements/checkbox.js +114 -0
package/src/elements/code_block.d.ts +21 -0
package/src/elements/code_block.js +27 -0
package/src/elements/collapsible.d.ts +20 -0
package/src/elements/collapsible.js +93 -0
package/src/elements/date_picker.d.ts +30 -0
package/src/elements/date_picker.js +528 -0
package/src/elements/dialog.d.ts +20 -0
package/src/elements/dialog.js +314 -0
package/src/elements/drawer.d.ts +20 -0
package/src/elements/drawer.js +318 -0
package/src/elements/fab.d.ts +22 -0
package/src/elements/fab.js +36 -0
package/src/elements/file_upload.d.ts +26 -0
package/src/elements/file_upload.js +59 -0
package/src/elements/listbox.d.ts +19 -0
package/src/elements/listbox.js +250 -0
package/src/elements/menu.d.ts +20 -0
package/src/elements/menu.js +224 -0
package/src/elements/message_bubble.d.ts +23 -0
package/src/elements/message_bubble.js +29 -0
package/src/elements/message_group.d.ts +18 -0
package/src/elements/message_group.js +28 -0
package/src/elements/message_part.d.ts +35 -0
package/src/elements/message_part.js +153 -0
package/src/elements/pagination.d.ts +22 -0
package/src/elements/pagination.js +36 -0
package/src/elements/popover.d.ts +26 -0
package/src/elements/popover.js +191 -0
package/src/elements/profile_menu.d.ts +20 -0
package/src/elements/profile_menu.js +213 -0
package/src/elements/progress.d.ts +18 -0
package/src/elements/progress.js +31 -0
package/src/elements/radio_group.d.ts +22 -0
package/src/elements/radio_group.js +70 -0
package/src/elements/scrollbar.d.ts +19 -0
package/src/elements/scrollbar.js +299 -0
package/src/elements/search_bar.d.ts +27 -0
package/src/elements/search_bar.js +98 -0
package/src/elements/select.d.ts +26 -0
package/src/elements/select.js +485 -0
package/src/elements/sidebar.d.ts +21 -0
package/src/elements/sidebar.js +322 -0
package/src/elements/skeleton.d.ts +17 -0
package/src/elements/skeleton.js +31 -0
package/src/elements/slider.d.ts +28 -0
package/src/elements/slider.js +93 -0
package/src/elements/speed_dial.d.ts +23 -0
package/src/elements/speed_dial.js +370 -0
package/src/elements/spinner.d.ts +15 -0
package/src/elements/spinner.js +28 -0
package/src/elements/split_button.d.ts +23 -0
package/src/elements/split_button.js +281 -0
package/src/elements/stepper.d.ts +20 -0
package/src/elements/stepper.js +31 -0
package/src/elements/switch.d.ts +22 -0
package/src/elements/switch.js +129 -0
package/src/elements/table.d.ts +29 -0
package/src/elements/table.js +371 -0
package/src/elements/tabs.d.ts +19 -0
package/src/elements/tabs.js +139 -0
package/src/elements/text.d.ts +26 -0
package/src/elements/text.js +32 -0
package/src/elements/text_input.d.ts +36 -0
package/src/elements/text_input.js +121 -0
package/src/elements/thinking.d.ts +17 -0
package/src/elements/thinking.js +28 -0
package/src/elements/toast.d.ts +23 -0
package/src/elements/toast.js +209 -0
package/src/elements/toggle_group.d.ts +22 -0
package/src/elements/toggle_group.js +176 -0
package/src/elements/tooltip.d.ts +18 -0
package/src/elements/tooltip.js +64 -0
package/src/markdown.d.ts +24 -0
package/src/markdown.js +66 -0
package/src/runtime.d.ts +35 -0
package/src/runtime.js +790 -0
package/src/server.d.ts +69 -0
package/src/server.js +176 -0
package/src/streaming-markdown.js +43 -0
package/src/vite-plugin.d.ts +46 -0
package/src/vite-plugin.js +221 -0
package/wasm/package.json +16 -0
package/wasm/wasm_api.d.ts +72 -0
package/wasm/wasm_api.js +593 -0
package/wasm/wasm_api_bg.wasm +0 -0
package/wasm/wasm_api_bg.wasm.d.ts +10 -0

package/src/runtime.js ADDED Viewed

@@ -0,0 +1,790 @@
+// Collet Core Runtime — WASM init, shared styles, base Custom Element class.
+//
+// This is the platform layer. Every Collet Custom Element extends CxElement.
+// Key design decisions:
+//   1. adoptedStyleSheets shares ONE parsed CSS across ALL Shadow Roots
+//   2. queueMicrotask batches multiple attribute changes into one WASM render
+//   3. Attribute names are kebab-case (HTML standard), converted to snake_case
+//      for Rust serde deserialization automatically
+//   4. Form-associated elements use ElementInternals for native <form> participation
+//   5. Custom Events with composed:true bubble out of Shadow DOM for framework binding
+// ─── WASM Singleton ───
+// One promise, resolved once. All elements share the same WASM instance.
+let wasmReady;
+let wasmExports;
+// Elements that connect before WASM is ready queue here.
+// When WASM loads, they re-render automatically.
+const _pendingElements = new Set();
+export function initWasm(initFn) {
+  if (!wasmReady) {
+    wasmReady = initFn().then(exports => {
+      wasmExports = exports;
+      // Flush elements that tried to render before WASM was ready
+      for (const el of _pendingElements) {
+        if (el.isConnected) el._scheduleRender();
+      }
+      _pendingElements.clear();
+      return exports;
+    }).catch(err => {
+      // Reset so fallback can retry with a different URL
+      wasmReady = null;
+      throw err;
+    });
+  }
+  return wasmReady;
+}
+export function getWasmExports() {
+  return wasmExports;
+}
+export function isWasmReady() {
+  return !!wasmExports;
+}
+// ─── WASM JIT Pre-Warming ───
+// After init, call each WASM function once with minimal config during idle time.
+// This forces V8's JIT to compile the hot deserialization + rendering paths
+// BEFORE the user's first interaction, eliminating the 20-50ms cold-call penalty.
+//
+// Uses requestIdleCallback (Chrome 47+, Firefox 55+) with setTimeout fallback.
+// Each warm-up call is wrapped in try/catch — the results are discarded.
+export function preWarmWasm(wasmFunctions) {
+  const run = () => {
+    for (const fn of wasmFunctions) {
+      try { fn({}); } catch { /* expected — missing required fields */ }
+    }
+  };
+  if (typeof requestIdleCallback === 'function') {
+    requestIdleCallback(run, { timeout: 200 });
+  } else {
+    setTimeout(run, 50);
+  }
+}
+// ─── Shared Stylesheets ───
+// Created once, adopted by every Shadow Root. Zero duplication.
+// tokens.css custom properties pierce Shadow DOM — loaded in <head> by consumer.
+// cx-utilities.css (extracted Tailwind) shared via adoptedStyleSheets.
+const sharedSheets = [];
+const HAS_CONSTRUCTABLE_STYLESHEETS = typeof CSSStyleSheet !== 'undefined';
+const HTMLElementBase = typeof HTMLElement === 'undefined' ? class {} : HTMLElement;
+const _hostDisplaySheets = new Map();
+function createSyncSheet(cssText) {
+  if (!HAS_CONSTRUCTABLE_STYLESHEETS) return null;
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(cssText);
+  return sheet;
+}
+async function createAsyncSheet(cssText) {
+  if (!HAS_CONSTRUCTABLE_STYLESHEETS) return null;
+  const sheet = new CSSStyleSheet();
+  await sheet.replace(cssText);
+  return sheet;
+}
+function getExtraHostSheet(ctor) {
+  if (ctor._hostSheet) return ctor._hostSheet;
+  const display = ctor._hostDisplay || 'block';
+  let sheet = _hostDisplaySheets.get(display);
+  if (!sheet) {
+    sheet = createSyncSheet(`:host { display: ${display}; }`);
+    if (sheet) _hostDisplaySheets.set(display, sheet);
+  }
+  return sheet;
+}
+function getAdoptedSheets(ctor) {
+  const extra = getExtraHostSheet(ctor);
+  return extra ? [...sharedSheets, extra] : sharedSheets;
+}
+function adoptSheets(shadow, ctor) {
+  if (!shadow || !('adoptedStyleSheets' in shadow)) return;
+  const baseSheets = getAdoptedSheets(ctor);
+  const extraSheets = shadow.adoptedStyleSheets.filter(
+    sheet => !baseSheets.includes(sheet)
+  );
+  shadow.adoptedStyleSheets = [...baseSheets, ...extraSheets];
+}
+// Suppress default browser focus outline on host elements.
+// When delegatesFocus is true, Chromium applies :focus-visible on BOTH
+// the host AND the inner focusable element, causing a double focus ring.
+// The inner element already has Tailwind focus-visible:ring-* classes
+// from the Rust design system — only that ring should be visible.
+// See: https://github.com/w3c/csswg-drafts/issues/5893
+const hostSheet = createSyncSheet([
+  // Host display is now per-component (`static _hostDisplay`) so inline
+  // controls no longer inherit a shared `display: block`.
+  // overflow: visible ensures fixed-positioned floating content (tooltips,
+  // menus, popovers) is not clipped by the host element boundary.
+  ':host { overflow: visible; }',
+  // Inner buttons/links must fill the host width when the component chooses a
+  // block layout. Without this, a host with width:100% leaves dead space around
+  // the inner control that swallows click events without shadow DOM delegation.
+  //
+  // CRITICAL: This MUST be inside @layer base so that explicit Tailwind sizing
+  // utilities (size-10, size-14 etc. in @layer utilities) can override it.
+  // Without @layer, this rule beats ALL layered rules (CSS cascade: unlayered
+  // wins over layered regardless of specificity), causing icon-only buttons
+  // and FABs to collapse to content width instead of their intended square size.
+  '@layer base {',
+  '  :host > button, :host > a { width: 100%; min-width: max-content; box-sizing: border-box; }',
+  '}',
+  // Suppress Chromium's double focus ring (inner element has its own Tailwind ring).
+  ':host(:focus) { outline: none; }',
+  ':host(:focus-visible) { outline: none; }',
+  // Interaction lockout during animations — set data-cx-busy on the host
+  // to prevent clicks while an open/close/toggle animation is in progress.
+  ':host([data-cx-busy]) { pointer-events: none !important; }',
+  // Tailwind v4 uses @property (inherits:false) to initialize internal CSS vars.
+  // @property registrations don't propagate into Shadow DOM — the variables stay
+  // undefined, breaking box-shadow/ring/transform computations.
+  //
+  // CRITICAL: This MUST be in @layer properties (Tailwind's lowest-priority layer).
+  // Unlayered styles beat ALL layered styles in the CSS cascade — if this were
+  // unlayered, Tailwind's @layer utilities rules (focus-visible:ring-2 etc.)
+  // could never override these defaults, and focus rings would stay invisible.
+  '@layer properties {',
+  '  *, ::before, ::after {',
+  '    --tw-shadow: 0 0 #0000;',
+  '    --tw-shadow-color: initial;',
+  '    --tw-shadow-alpha: 100%;',
+  '    --tw-inset-shadow: 0 0 #0000;',
+  '    --tw-inset-shadow-color: initial;',
+  '    --tw-inset-shadow-alpha: 100%;',
+  '    --tw-ring-color: initial;',
+  '    --tw-ring-shadow: 0 0 #0000;',
+  '    --tw-inset-ring-color: initial;',
+  '    --tw-inset-ring-shadow: 0 0 #0000;',
+  '    --tw-ring-inset: initial;',
+  '    --tw-ring-offset-width: 0px;',
+  '    --tw-ring-offset-color: #fff;',
+  '    --tw-ring-offset-shadow: 0 0 #0000;',
+  '    --tw-translate-x: 0;',
+  '    --tw-translate-y: 0;',
+  '    --tw-border-style: solid;',
+  '    --tw-outline-style: solid;',
+  '  }',
+  '}',
+].join('\n'));
+if (hostSheet) sharedSheets.push(hostSheet);
+// Essential loading animations override.
+// tokens.css kills ALL keyframe animations under prefers-reduced-motion:
+//   *, *::before, *::after { animation-duration: 0.01ms !important; }
+// This is correct for decorative motion, but spinners/skeletons/progress bars
+// are essential loading feedback — WCAG 2.2 allows essential animations even
+// when users prefer reduced motion. These overrides restore them.
+// Uses class selectors (specificity 0,1,0) to beat * (specificity 0,0,0).
+const loadingSheet = createSyncSheet([
+  '@media (prefers-reduced-motion: reduce) {',
+  '  .animate-spin { animation: spin 1s linear infinite !important; }',
+  '  .animate-spin-square { animation: spin-square 1.8s ease-in-out infinite !important; }',
+  '  .animate-pulse { animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite !important; }',
+  '  .animate-skeleton-wave::after { animation: skeleton-wave 2s linear infinite !important; }',
+  '  .animate-progress-indeterminate { animation: progress-indeterminate 1.5s ease-in-out infinite !important; }',
+  '}',
+].join('\n'));
+if (loadingSheet) sharedSheets.push(loadingSheet);
+// Tailwind v4 compatibility + interactive transition overrides.
+//
+// 1. Tailwind v4 uses CSS `translate` / `rotate` / `scale` properties
+//    (NOT `transform`). tokens.css transitions target `transform`, which
+//    won't animate Tailwind v4's individual transform properties.
+//    This sheet fixes the mismatch for affected components.
+//
+// 2. Under prefers-reduced-motion, tokens.css sets --duration-* vars to
+//    0.01ms on :root (inherited into Shadow DOM), killing all CSS
+//    transitions. Interactive transitions (switch slide, accordion
+//    chevron, collapsible chevron) provide state-change feedback and
+//    should retain brief, simple motion. We restore them with reduced
+//    durations and linear easing (no overshoot).
+const compatSheet = createSyncSheet([
+  // Switch thumb: transition `translate` (Tailwind v4 property).
+  // !important overrides tokens.css `transition: transform` which loads later.
+  'button[role="switch"] > span[aria-hidden="true"] {',
+  '  transition: translate var(--duration-smooth, 300ms) var(--ease-spring, cubic-bezier(0.175, 0.885, 0.32, 1.275)) !important;',
+  '}',
+  '',
+  // Checkbox: preserve checked indicator color on hover.
+  // MicroInteraction::color_shift() adds hover:text-[var(--color-primary)]
+  // which overrides peer-checked:text-[var(--color-text-inverse)] in Tailwind
+  // cascade order. Result: blue checkmark on blue background = invisible.
+  // This rule has higher specificity (0,3,1) than the Tailwind hover utility
+  // (0,2,0), so it correctly preserves the white checkmark on hover.
+  'input.peer:checked + [aria-hidden="true"]:hover { color: var(--color-text-inverse); }',
+  '',
+  // Tailwind v4 cascade order: .inline-flex overrides .hidden when both classes
+  // are on the same element (inline-flex appears later in the CSS). This breaks
+  // listbox check indicators which use "inline-flex ... hidden" to toggle visibility.
+  // Scoped to [data-check] so it doesn't break "hidden data-[open]:block" on dropdowns.
+  '[data-check].hidden { display: none !important; }',
+  '',
+  // Ensure border-box in shadow DOM (Tailwind preflight may not load first)
+  '*, *::before, *::after { box-sizing: border-box; }',
+  '',
+  // Reduced-motion: restore brief interactive transitions
+  '@media (prefers-reduced-motion: reduce) {',
+  '  :host {',
+  '    --duration-fast: 100ms;',
+  '    --duration-normal: 150ms;',
+  '    --duration-smooth: 200ms;',
+  '    --ease-spring: ease-out;',
+  '  }',
+  '}',
+].join('\n'));
+if (compatSheet) sharedSheets.push(compatSheet);
+export async function loadSharedStyles(urls) {
+  const results = await Promise.all(
+    urls.map(url => fetch(url).then(r => r.text()))
+  );
+  for (const cssText of results) {
+    const sheet = await createAsyncSheet(cssText);
+    if (sheet) sharedSheets.push(sheet);
+  }
+  return sharedSheets;
+}
+// Load utility CSS from an inline string (no fetch). Used by zero-config init.
+export async function loadInlineSharedStyles(cssText) {
+  const sheet = await createAsyncSheet(cssText);
+  if (sheet) sharedSheets.push(sheet);
+}
+// ─── Shadow DOM Token Loading ───
+// The build produces two separate CSS outputs:
+//   tokens.css        — full design tokens (vars, fonts, themes) for document <head>
+//   tokens-shadow.css — Shadow DOM subset (animations, motion, component rules)
+//
+// CSS custom properties (colors, spacing, easing) defined in <head> inherit into
+// Shadow DOM automatically. The shadow subset contains only rules that Shadow DOM
+// elements need but can't inherit: @keyframes, component motion, slider/scrollbar
+// pseudo-elements, etc.
+//
+// This build-time split eliminates the previous runtime CSS parser
+// (stripTokensForShadowDom) which broke across three patch versions due to
+// comment handling, nested @media blocks, and regex over-matching.
+// Load shadow token CSS from a URL (fetch). Used when explicit CSS URLs are provided.
+export async function loadMotionStyles(url) {
+  // When given the full tokens URL, fetch and strip at runtime (legacy path).
+  // Prefer passing the tokens-shadow.css URL directly via tokensUrl.
+  const raw = await fetch(url).then(r => r.text());
+  const sheet = await createAsyncSheet(raw);
+  if (sheet) sharedSheets.push(sheet);
+}
+// Load shadow token CSS from an inline string (no fetch). Used by zero-config init.
+export async function loadInlineMotionStyles(raw) {
+  const sheet = await createAsyncSheet(raw);
+  if (sheet) sharedSheets.push(sheet);
+}
+// Inject tokens.css into document <head> as a <style> element (no <link> needed).
+// PREPENDED (not appended) so consumer CSS that loads later naturally wins
+// the cascade — same :root selector, same specificity, later source wins.
+// This means `--color-primary: red` in the consumer's index.css overrides
+// the library default with zero !important hacks.
+export function injectTokensToHead(cssText) {
+  if (document.getElementById('cx-tokens')) return;
+  const style = document.createElement('style');
+  style.id = 'cx-tokens';
+  style.textContent = cssText;
+  document.head.prepend(style);
+}
+// ─── FOUC Prevention ───
+// Hide cx-* elements until their Custom Element class is defined.
+// Uses :not(:defined) — a native CSS pseudo-class that matches elements
+// whose constructor hasn't been registered via customElements.define().
+// Once defined, the element becomes :defined and immediately appears.
+// Generated from the component registry — always in sync, zero maintenance.
+export function injectFoucPrevention(componentNames) {
+  if (document.getElementById('cx-fouc')) return;
+  const selectors = componentNames.map(n => `cx-${n}:not(:defined)`);
+  const style = document.createElement('style');
+  style.id = 'cx-fouc';
+  // display:none prevents the inline-display footgun (Custom Elements default
+  // to display:inline before their shadow DOM styles load). Once the element
+  // class is registered via customElements.define(), :not(:defined) stops
+  // matching and the component's _hostDisplay takes over.
+  style.textContent = selectors.join(',') + '{display:none}';
+  document.head.prepend(style);
+}
+export function getSharedSheets() {
+  return sharedSheets;
+}
+// ─── Base Custom Element ───
+// Every Collet element follows this pattern:
+//   1. Attach Shadow DOM (open mode) in constructor
+//   2. Adopt shared stylesheets
+//   3. Collect attribute changes into a props object
+//   4. Batch renders via queueMicrotask (coalesces multiple changes)
+//   5. Call WASM render function with props → inject HTML into shadow root
+// ─── Scroll Lock ───
+// Prevents background scrolling when modals/drawers are open.
+// Compensates for scrollbar removal with padding-right to prevent layout shift.
+// Reference-counted: multiple concurrent modals share one lock.
+let _scrollLockCount = 0;
+export class CxElement extends HTMLElementBase {
+  #shadow;
+  #props = {};
+  #pendingRender = false;
+  #prevAria = {};
+  #initialized = false;
+  constructor() {
+    super();
+    // Declarative Shadow DOM: if a <template shadowrootmode="open"> was in the
+    // HTML, the browser already created this.shadowRoot before any JS ran.
+    // Reuse it — calling attachShadow() on an element that already has a shadow
+    // root throws a DOMException. This is the "resumability" mechanism: the
+    // server/build pre-renders HTML, the browser paints it instantly, and when
+    // this constructor runs the element upgrades without re-creating the DOM.
+    if (this.shadowRoot) {
+      this.#shadow = this.shadowRoot;
+    } else if (typeof this.attachShadow === 'function') {
+      this.#shadow = this.attachShadow({ mode: 'open' });
+    }
+    // Subclasses can define `static _hostDisplay = 'inline-flex'` or provide
+    // a custom `static _hostSheet` for specialized host styles.
+    if (this.#shadow) adoptSheets(this.#shadow, this.constructor);
+  }
+  // Subclasses access these for rendering
+  get _shadow() { return this.#shadow; }
+  get _props() { return this.#props; }
+  // Guard against duplicate listener attachment on DOM reparenting.
+  // connectedCallback fires every time the element is moved in the DOM —
+  // shadow event listeners must only be added once.
+  get _isInitialized() { return this.#initialized; }
+  _markInitialized() { this.#initialized = true; }
+  // ─── Lifecycle ───
+  connectedCallback() {
+    if (!this.#shadow) return;
+    // Auto-generate a unique ID if the consumer didn't provide one.
+    // Many Rust component builders require an ID for ARIA associations
+    // (aria-labelledby, aria-controls, etc.). Without this, serde
+    // deserialization would fail or produce empty HTML.
+    if (!this.#props.id) {
+      const tag = this.tagName.toLowerCase().replace('cx-', '');
+      this.#props.id = `cx-${tag}-${Math.random().toString(36).slice(2, 8)}`;
+    }
+    // Re-adopt styles — sharedSheets grows as init() loads tokens.css and
+    // utilities CSS. The constructor may run before those are ready, leaving
+    // the shadow root with only the base host display sheet. Re-adoption is
+    // cheap (no re-parse) and ensures every render has all styles available.
+    adoptSheets(this.#shadow, this.constructor);
+    this._scheduleRender();
+  }
+  disconnectedCallback() {
+    // Remove from pending queue to prevent memory leaks.
+    // Elements removed from DOM before WASM loads would otherwise
+    // stay in the Set forever, holding strong references.
+    _pendingElements.delete(this);
+  }
+  attributeChangedCallback(name, _old, value) {
+    // Guard: stripping host title attribute to suppress native browser tooltip.
+    // Only fires for components with 'title' in observedAttributes (dialog,
+    // drawer, popover, alert, toast) — they use title as content, not tooltip.
+    if (name === 'title' && this.__strippingTitle) return;
+    // Convert kebab-case attribute names to snake_case for Rust serde.
+    // HTML: icon-leading → Rust: icon_leading
+    const key = name.replace(/-/g, '_');
+    const isBooleanAttr = this.constructor._booleanAttrs?.has(name);
+    const isNumericAttr = this.constructor._numericAttrs?.has(name);
+    let newValue;
+    if (value === null) {
+      // Attribute removed → delete key so serde's #[serde(default)] supplies
+      // the correct default. Works for both default-false (disabled) and
+      // default-true (show_icon) booleans.
+      newValue = undefined;
+    } else if (isBooleanAttr && value === 'false') {
+      // Explicit "false" string → boolean false (overrides default-true fields)
+      newValue = false;
+    } else if (isBooleanAttr && (value === '' || value === 'true')) {
+      // Boolean attribute present with no value → true.
+      // ONLY for fields declared as boolean in the Rust config struct.
+      // Without this guard, string fields like `value=""` or `label=""`
+      // would be coerced to boolean true, causing serde deserialization
+      // errors ("invalid type: boolean, expected a string").
+      newValue = true;
+    } else if (isNumericAttr && value !== '') {
+      // Numeric attributes (value, min, max, step, page, etc.) must be
+      // passed as JS numbers for serde_wasm_bindgen to deserialize into
+      // Rust f64/usize. HTML attributes are always strings — without this
+      // coercion, serde fails with "invalid type: string, expected f64".
+      const num = Number(value);
+      newValue = isNaN(num) ? value : num;
+    } else if (value === '') {
+      // Empty string for non-boolean fields — pass as empty string.
+      newValue = value;
+    } else if (value.length > 1 && (value[0] === '[' || value[0] === '{')) {
+      // JSON array/object string → parsed JS value for serde_wasm_bindgen.
+      // WASM expects actual arrays/objects (Vec<T>, HashMap), not strings.
+      try {
+        newValue = JSON.parse(value);
+      } catch {
+        newValue = value; // not valid JSON — keep as string
+      }
+    } else {
+      // HTML attributes are strings. Keep primitive values as strings so
+      // Rust serde receives `value: "2021"` instead of `value: 2021`.
+      newValue = value;
+    }
+    // Skip re-render when the resolved value matches what's already in props.
+    // This prevents interactive elements (checkbox, switch) from having their
+    // CSS transitions killed when React echoes back the same state that the
+    // internal change/click handler already set.
+    if (newValue === undefined) {
+      if (!(key in this.#props)) return;
+      delete this.#props[key];
+    } else {
+      if (this.#props[key] === newValue) return;
+      this.#props[key] = newValue;
+    }
+    if (this.isConnected) this._scheduleRender();
+    // Strip 'title' from host element to suppress native browser tooltip.
+    // The value is already stored in _props for WASM rendering.
+    if (name === 'title' && value !== null) {
+      this.__strippingTitle = true;
+      this.removeAttribute('title');
+      this.__strippingTitle = false;
+    }
+  }
+  // ─── Batched Rendering ───
+  _scheduleRender() {
+    if (!this.#shadow) return;
+    if (this.#pendingRender) return;
+    this.#pendingRender = true;
+    queueMicrotask(() => {
+      this.#pendingRender = false;
+      // Guard: element may have been disconnected between scheduling and execution.
+      if (!this.isConnected) return;
+      // Ensure latest shared styles are adopted before rendering.
+      // Preserve any component-specific sheets already attached by subclasses.
+      adoptSheets(this.#shadow, this.constructor);
+      // If WASM isn't loaded yet (lazy init), queue for re-render when ready.
+      // initWasm() flushes _pendingElements on load.
+      if (!wasmExports) {
+        _pendingElements.add(this);
+        // Pre-render fallback: inject <slot> so light DOM children are visible
+        // while WASM loads. This enables progressive enhancement — consumers can
+        // put fallback content inside Custom Elements. For slot-based components
+        // (scrollbar, collapsible, card), their content is visible immediately.
+        if (!this.#shadow.firstChild) {
+          this.#shadow.innerHTML = '<slot></slot>';
+        }
+        return;
+      }
+      this._doRender();
+    });
+  }
+  // Override in subclass to call the WASM render function
+  _doRender() {}
+  // Inject WASM render result into Shadow Root and apply a11y to host.
+  //
+  // The a11y metadata originates from Rust's compile-time Accessible trait:
+  //   Rust Behavior::aria_attrs() → A11yMetadata → host element attributes
+  //
+  // This propagates the three-layer accessibility guarantee through
+  // the Shadow DOM boundary — the host element reflects the inner
+  // component's ARIA state for external CSS selectors and AT.
+  _injectHtml(result) {
+    // Preserve focus across innerHTML replacement. Without this, typing
+    // in an <input> inside shadow DOM loses focus on every re-render
+    // because innerHTML destroys and recreates all DOM nodes.
+    const active = this.#shadow.activeElement;
+    let focusInfo = null;
+    if (active && (active.tagName === 'INPUT' || active.tagName === 'TEXTAREA')) {
+      focusInfo = {
+        tag: active.tagName,
+        type: active.type || '',
+        value: active.value,
+        selStart: active.selectionStart,
+        selEnd: active.selectionEnd,
+      };
+    }
+    this.#shadow.innerHTML = result.sprites + result.html;
+    // Restore focus to equivalent element after DOM replacement
+    if (focusInfo) {
+      const selector = focusInfo.type
+        ? `${focusInfo.tag}[type="${focusInfo.type}"]`
+        : focusInfo.tag;
+      const target = this.#shadow.querySelector(selector) || this.#shadow.querySelector(focusInfo.tag);
+      if (target) {
+        target.value = focusInfo.value;
+        target.focus();
+        try { target.setSelectionRange(focusInfo.selStart, focusInfo.selEnd); } catch { /* not all inputs support selection */ }
+      }
+    }
+    if (result.a11y) {
+      // Apply role to host (only when inner HTML doesn't imply it)
+      if (result.a11y.role) {
+        this.setAttribute('role', result.a11y.role);
+      }
+      // Reflect ARIA attributes on host element.
+      // Remove stale attrs from previous render, add/update current ones.
+      const newAria = result.a11y.aria || {};
+      // Remove attrs that were set last render but aren't in this render
+      for (const key of Object.keys(this.#prevAria)) {
+        if (!(key in newAria)) {
+          this.removeAttribute(key);
+        }
+      }
+      // Set current ARIA attrs
+      for (const [key, value] of Object.entries(newAria)) {
+        this.setAttribute(key, value);
+      }
+      this.#prevAria = newAria;
+    }
+  }
+  // ─── Interaction Guards ───
+  // Named action lock — prevents re-entry during an in-progress action.
+  // The lock holds until:
+  //   - Web Animation: after .finished resolves
+  //   - Promise: after resolution
+  //   - Sync: after next animation frame
+  // Use for open/close, toggle, and any stateful animation flow.
+  _guard(key, fn) {
+    const guards = this.__guards ??= new Set();
+    if (guards.has(key)) return undefined;
+    guards.add(key);
+    const release = () => guards.delete(key);
+    try {
+      const result = fn();
+      if (result?.finished) {
+        // Web Animation — release after it completes
+        result.finished.then(release, release);
+      } else if (result?.then) {
+        // Promise — release on settle
+        result.then(release, release);
+      } else {
+        // Sync — release next frame (prevents same-frame re-entry)
+        requestAnimationFrame(release);
+      }
+      return result;
+    } catch (e) {
+      release();
+      throw e;
+    }
+  }
+  // Check if a named guard is currently active.
+  _isGuarded(key) {
+    return this.__guards?.has(key) ?? false;
+  }
+  // ─── Event Helpers ───
+  // Action events that get automatic interaction cooldown.
+  // Prevents the same component from emitting the same action event
+  // twice within 150ms — catches accidental double-clicks, rapid toggles,
+  // and animation-overlap scenarios. Input/focus/keyboard events are NOT
+  // included — they fire freely for responsive typing and navigation.
+  static _actionEvents = new Set([
+    'cx-click', 'cx-close', 'cx-sort', 'cx-select',
+    'cx-action', 'cx-change', 'cx-dismiss', 'cx-navigate',
+  ]);
+  // Dispatch a Custom Event that bubbles out of Shadow DOM.
+  // Frameworks can listen via element.addEventListener or JSX handlers.
+  // Action events include automatic 150ms cooldown per event type.
+  _emit(name, detail) {
+    if (CxElement._actionEvents.has(name)) {
+      const cdKey = `__cxCd_${name}`;
+      if (this[cdKey]) return;
+      this[cdKey] = true;
+      setTimeout(() => { this[cdKey] = false; }, 150);
+    }
+    this.dispatchEvent(new CustomEvent(name, {
+      detail,
+      bubbles: true,
+      composed: true, // crosses Shadow DOM boundary
+    }));
+  }
+  // ─── Property Setters ───
+  // For non-string values that can't be set via HTML attributes.
+  _setProp(key, value) {
+    this.#props[key] = value;
+    if (this.isConnected) this._scheduleRender();
+  }
+  // ─── Scroll Lock ───
+  // Used by dialog/drawer to prevent background scrolling.
+  // Adds padding-right to <html> equal to scrollbar width so removing
+  // the scrollbar doesn't shift page content (the Radix UI approach).
+  // Reference-counted for nested modals.
+  _lockScroll() {
+    if (_scrollLockCount === 0) {
+      const scrollbarW = window.innerWidth - document.documentElement.clientWidth;
+      document.documentElement.style.overflow = 'hidden';
+      if (scrollbarW > 0) {
+        document.documentElement.style.paddingRight = `${scrollbarW}px`;
+      }
+    }
+    _scrollLockCount++;
+  }
+  _unlockScroll() {
+    _scrollLockCount = Math.max(0, _scrollLockCount - 1);
+    if (_scrollLockCount === 0) {
+      document.documentElement.style.overflow = '';
+      document.documentElement.style.paddingRight = '';
+    }
+  }
+  // ─── Fixed-Position Floating ───
+  // Positions a floating panel with `position: fixed` using viewport coordinates.
+  // This escapes `overflow: auto/scroll/hidden` on ancestor elements (e.g. when
+  // a Popover/Select/Menu is inside <cx-scrollbar>). Absolute positioning clips;
+  // fixed positioning is relative to the viewport.
+  //
+  // opts.matchWidth — set panel width to trigger width (for Select/Autocomplete)
+  // opts.gap        — pixel gap between trigger and panel (default: 4)
+  // Returns 'top' or 'bottom' (the chosen placement).
+  _positionFloatingFixed(trigger, panel, opts) {
+    const rect = trigger.getBoundingClientRect();
+    const gap = opts?.gap ?? 4;
+    const vh = window.innerHeight;
+    const below = vh - rect.bottom - gap;
+    const above = rect.top - gap;
+    const openAbove = below < 120 && above > below;
+    panel.style.position = 'fixed';
+    panel.style.zIndex = '50';
+    panel.style.left = rect.left + 'px';
+    if (opts?.matchWidth) panel.style.width = rect.width + 'px';
+    else panel.style.minWidth = rect.width + 'px';
+    if (openAbove) {
+      panel.style.top = '';
+      panel.style.bottom = (vh - rect.top + gap) + 'px';
+    } else {
+      panel.style.top = (rect.bottom + gap) + 'px';
+      panel.style.bottom = '';
+    }
+    panel.setAttribute('data-placement', openAbove ? 'top' : 'bottom');
+    return openAbove ? 'top' : 'bottom';
+  }
+  _resetFloatingFixed(panel) {
+    if (!panel) return;
+    panel.style.position = '';
+    panel.style.zIndex = '';
+    panel.style.left = '';
+    panel.style.right = '';
+    panel.style.top = '';
+    panel.style.bottom = '';
+    panel.style.width = '';
+    panel.style.minWidth = '';
+    panel.removeAttribute('data-placement');
+  }
+}
+// ─── Form-Associated Base ───
+// Elements that participate in <form> submissions extend this.
+// Uses ElementInternals API (Chrome 77+, Firefox 98+, Safari 16.4+).
+export class CxFormElement extends CxElement {
+  static formAssociated = true;
+  #internals;
+  constructor() {
+    super();
+    this.#internals = typeof this.attachInternals === 'function'
+      ? this.attachInternals()
+      : null;
+  }
+  get _internals() { return this.#internals; }
+  // Set the form submission value. Called after each render.
+  _setFormValue(value) {
+    this.#internals?.setFormValue(value);
+  }
+  // Set validation state.
+  _setValidity(flags, message, anchor) {
+    if (flags) {
+      this.#internals?.setValidity(flags, message, anchor);
+    } else {
+      this.#internals?.setValidity({});
+    }
+  }
+  // Native form lifecycle callbacks
+  formResetCallback() {
+    this._setProp('value', '');
+    this._setFormValue('');
+  }
+  formDisabledCallback(disabled) {
+    this._setProp('disabled', disabled);
+  }
+  // Expose internals for label association.
+  // Getters AND setters for properties that React sets directly on the DOM
+  // element (element.name = 'foo', element.value = 'bar'). Without setters,
+  // React crashes: "Cannot set property X of #<CxFormElement> which has only
+  // a getter". The setter delegates to setAttribute so the normal
+  // attributeChangedCallback → props → render pipeline runs.
+  get form() { return this.#internals?.form ?? null; }
+  get name() { return this.getAttribute?.('name') ?? null; }
+  set name(v) { if (v == null) this.removeAttribute('name'); else this.setAttribute('name', String(v)); }
+  get type() { return this.getAttribute?.('type') ?? this.localName; }
+  set type(v) { if (v != null) this.setAttribute('type', String(v)); }
+  get value() { return this.getAttribute?.('value') ?? ''; }
+  set value(v) { if (v == null) this.removeAttribute('value'); else this.setAttribute('value', String(v)); }
+  get disabled() { return this.hasAttribute('disabled'); }
+  set disabled(v) { if (v) this.setAttribute('disabled', ''); else this.removeAttribute('disabled'); }
+  get required() { return this.hasAttribute('required'); }
+  set required(v) { if (v) this.setAttribute('required', ''); else this.removeAttribute('required'); }
+  get validity() { return this.#internals?.validity ?? null; }
+  get validationMessage() { return this.#internals?.validationMessage ?? ''; }
+  get willValidate() { return this.#internals?.willValidate ?? false; }
+  checkValidity() { return this.#internals?.checkValidity?.() ?? true; }
+  reportValidity() { return this.#internals?.reportValidity?.() ?? true; }
+}