@astryxdesign/core 0.2.0 → 0.3.0-canary.060cc9d

package/dist/Icon/globalIconRegistry.d.ts

@@ -2,23 +2,35 @@
  * @file globalIconRegistry.tsx
  * @input None (pure module-level state)
  * @output Exports registerIcons, getIconRegistry, getIcon, resetIcons, IconName, IconRegistry
- * @position Global icon registry; works in both server and client environments
+ * @position Global and theme-scoped icon registry; works in server and client environments
  *
  * This module has NO 'use client' directive — it's importable from RSC.
- * All components use getIcon() to resolve icons from this global registry.
+ * Components resolve semantic icons through getIcon() or the client useIcon() hook.
  */
 import type { ReactNode } from 'react';
+import type { DefinedTheme } from '../theme/defineTheme';
 /**
  * Semantic icon names used internally by Astryx components.
  *
  * These represent the functional purpose of each icon, not a specific
  * visual representation. Themes provide the actual icon components.
  */
-export type IconName = 'close' | 'chevronDown' | 'chevronLeft' | 'chevronRight' | 'check' | 'success' | 'error' | 'warning' | 'info' | 'calendar' | 'clock' | 'externalLink' | 'menu' | 'moreHorizontal' | 'search' | 'arrowUp' | 'arrowDown' | 'arrowsUpDown' | 'funnel' | 'eyeSlash' | 'viewColumns' | 'copy' | 'checkDouble' | 'wrench' | 'stop' | 'microphone';
+export type IconName = 'close' | 'chevronDown' | 'chevronLeft' | 'chevronRight' | 'chevronsLeft' | 'chevronsRight' | 'check' | 'success' | 'error' | 'warning' | 'info' | 'calendar' | 'clock' | 'externalLink' | 'menu' | 'moreHorizontal' | 'search' | 'arrowUp' | 'arrowDown' | 'arrowsUpDown' | 'funnel' | 'eyeSlash' | 'viewColumns' | 'copy' | 'checkDouble' | 'wrench' | 'stop' | 'microphone';
+/**
+ * A semantic icon name — either one of the built-in {@link IconName}s or an
+ * arbitrary string key contributed by a library/app.
+ *
+ * The `(string & {})` intersection keeps the built-in names available for
+ * autocomplete while still allowing any string, so downstream libraries can
+ * register and resolve their own keys (e.g. `'richtext:bold'`) without having
+ * to widen the core `IconName` union.
+ */
+export type ExtendedIconName = IconName | (string & {});
 /**
  * Icon registry mapping semantic names to React nodes.
  */
 export type IconRegistry = Record<IconName, ReactNode>;
+export type IconRegistrySource = DefinedTheme | string | null | undefined;
 /**
  * Register icons at the module level. Works in both server and client
  * environments. Call once at app initialization (e.g. root layout).
@@ -32,8 +44,17 @@ export type IconRegistry = Record<IconName, ReactNode>;
  * import { brandIcons } from './brand-icons';
  * registerIcons(brandIcons);
  * ```
+ *
+ * Libraries may also register their own extension keys (any string), so a
+ * theme can override them the same way it overrides built-in icons:
+ * @example
+ * ```
+ * // In a library that ships its own icons:
+ * registerIcons({ 'richtext:bold': <MyBoldIcon /> });
+ * // resolve with getIcon('richtext:bold')
+ * ```
  */
-export declare function registerIcons(icons: Partial<IconRegistry>): void;
+export declare function registerIcons(icons: Partial<Record<ExtendedIconName, ReactNode>>): void;
 /**
  * Get a snapshot of the full icon registry, with registered icons overriding
  * built-in defaults.
@@ -42,14 +63,35 @@ export declare function registerIcons(icons: Partial<IconRegistry>): void;
  * to derive valid semantic icon-name options from the same registry Icon
  * resolves against.
  */
-export declare function getIconRegistry(): Readonly<IconRegistry>;
+export declare function getIconRegistry(source?: IconRegistrySource): Readonly<IconRegistry>;
 /**
  * Get an icon by name from the global registry, falling back to defaults.
  *
  * Works in both server and client environments.
  * Falls back to built-in default icons when no override is registered.
+ *
+ * Accepts extension keys (any string) in addition to the built-in
+ * {@link IconName}s — useful for library-contributed icons. For a
+ * caller-supplied fallback when a key isn't registered, use
+ * {@link getExtendedIcon}.
+ */
+export declare function getIcon(name: ExtendedIconName, source?: IconRegistrySource): ReactNode;
+/**
+ * Resolve an extension icon by an arbitrary string key, falling back to a
+ * caller-supplied default when nothing is registered.
+ *
+ * This is the seam libraries use to make their own icons themeable: ship the
+ * inline SVG as `fallback`, resolve through this function, and a theme can
+ * override the key via {@link registerIcons} without the library having to
+ * widen the core {@link IconName} union.
+ *
+ * @example
+ * ```
+ * // Library default, overridable by a theme registering 'richtext:bold':
+ * getExtendedIcon('richtext:bold', <BoldGlyph />)
+ * ```
  */
-export declare function getIcon(name: IconName): ReactNode;
+export declare function getExtendedIcon(name: ExtendedIconName, fallback?: ReactNode, source?: IconRegistrySource): ReactNode;
 /**
  * Reset the global registry. For testing only.
  * @internal

package/dist/Icon/globalIconRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"globalIconRegistry.d.ts","sourceRoot":"","sources":["../../src/Icon/globalIconRegistry.tsx"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAOrC;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,aAAa,GACb,aAAa,GACb,cAAc,GACd,OAAO,GACP,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,cAAc,GACd,MAAM,GACN,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,cAAc,GACd,QAAQ,GACR,UAAU,GACV,aAAa,GACb,MAAM,GACN,aAAa,GACb,QAAQ,GACR,MAAM,GACN,YAAY,CAAC;AAEjB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAQvD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,QAAQ,CAAC,YAAY,CAAC,CAQxD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAEjD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}
+{"version":3,"file":"globalIconRegistry.d.ts","sourceRoot":"","sources":["../../src/Icon/globalIconRegistry.tsx"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAQvD;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,aAAa,GACb,aAAa,GACb,cAAc,GACd,cAAc,GACd,eAAe,GACf,OAAO,GACP,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,cAAc,GACd,MAAM,GACN,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,cAAc,GACd,QAAQ,GACR,UAAU,GACV,aAAa,GACb,MAAM,GACN,aAAa,GACb,QAAQ,GACR,MAAM,GACN,YAAY,CAAC;AAEjB;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAsB1E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC,GAClD,IAAI,CAON;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,QAAQ,CAAC,YAAY,CAAC,CAkBxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAOX;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,QAAQ,CAAC,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAQX;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}

package/dist/Icon/globalIconRegistry.js

@@ -4,13 +4,15 @@
  * @file globalIconRegistry.tsx
  * @input None (pure module-level state)
  * @output Exports registerIcons, getIconRegistry, getIcon, resetIcons, IconName, IconRegistry
- * @position Global icon registry; works in both server and client environments
+ * @position Global and theme-scoped icon registry; works in server and client environments
  *
  * This module has NO 'use client' directive — it's importable from RSC.
- * All components use getIcon() to resolve icons from this global registry.
+ * Components resolve semantic icons through getIcon() or the client useIcon() hook.
  */
 
 import { defaultIcons } from "./defaultIcons.js";
+import { getRegisteredTheme } from "../theme/themeRegistry.js";
+import { warnOnce } from "../utils/devWarning.js";
 
 // =============================================================================
 // Types
@@ -22,7 +24,17 @@ import { defaultIcons } from "./defaultIcons.js";
  * These represent the functional purpose of each icon, not a specific
  * visual representation. Themes provide the actual icon components.
  */
-// SYNC: packages/cli/docs/icons.doc.mjs — update USAGE_HINTS when adding names
+// SYNC: packages/cli/assets/docs/icons.doc.mjs — update USAGE_HINTS when adding names
+
+/**
+ * A semantic icon name — either one of the built-in {@link IconName}s or an
+ * arbitrary string key contributed by a library/app.
+ *
+ * The `(string & {})` intersection keeps the built-in names available for
+ * autocomplete while still allowing any string, so downstream libraries can
+ * register and resolve their own keys (e.g. `'richtext:bold'`) without having
+ * to widen the core `IconName` union.
+ */
 
 /**
  * Icon registry mapping semantic names to React nodes.
@@ -33,6 +45,15 @@ import { defaultIcons } from "./defaultIcons.js";
 // =============================================================================
 
 let globalRegistry = {};
+function getThemeIconOverrides(source) {
+  if (source == null) {
+    return null;
+  }
+  if (typeof source === 'string') {
+    return getRegisteredTheme(source)?.icons ?? null;
+  }
+  return source.icons ?? null;
+}
 
 /**
  * Register icons at the module level. Works in both server and client
@@ -47,8 +68,18 @@ let globalRegistry = {};
  * import { brandIcons } from './brand-icons';
  * registerIcons(brandIcons);
  * ```
+ *
+ * Libraries may also register their own extension keys (any string), so a
+ * theme can override them the same way it overrides built-in icons:
+ * @example
+ * ```
+ * // In a library that ships its own icons:
+ * registerIcons({ 'richtext:bold': <MyBoldIcon /> });
+ * // resolve with getIcon('richtext:bold')
+ * ```
  */
 export function registerIcons(icons) {
+  warnOnce('icon-registry:global-register-icons', 'Icon', '`registerIcons()` applies icon overrides globally. Prefer `defineTheme({ icons })` for theme-scoped icon overrides.');
   globalRegistry = {
     ...globalRegistry,
     ...icons
@@ -63,13 +94,23 @@ export function registerIcons(icons) {
  * to derive valid semantic icon-name options from the same registry Icon
  * resolves against.
  */
-export function getIconRegistry() {
+export function getIconRegistry(source) {
   const registry = {
     ...defaultIcons
   };
-  for (const name of Object.keys(globalRegistry)) {
+
+  // Only surface built-in IconName keys here — extension keys registered by
+  // libraries are resolved via getIcon/getExtendedIcon and intentionally kept
+  // out of the typed IconRegistry snapshot.
+  for (const name of Object.keys(defaultIcons)) {
     registry[name] = globalRegistry[name] ?? defaultIcons[name];
   }
+  const themeIcons = getThemeIconOverrides(source);
+  if (themeIcons != null) {
+    for (const name of Object.keys(themeIcons)) {
+      registry[name] = themeIcons[name] ?? registry[name];
+    }
+  }
   return registry;
 }
 
@@ -78,9 +119,35 @@ export function getIconRegistry() {
  *
  * Works in both server and client environments.
  * Falls back to built-in default icons when no override is registered.
+ *
+ * Accepts extension keys (any string) in addition to the built-in
+ * {@link IconName}s — useful for library-contributed icons. For a
+ * caller-supplied fallback when a key isn't registered, use
+ * {@link getExtendedIcon}.
+ */
+export function getIcon(name, source) {
+  const themeIcons = getThemeIconOverrides(source);
+  return themeIcons?.[name] ?? globalRegistry[name] ?? defaultIcons[name];
+}
+
+/**
+ * Resolve an extension icon by an arbitrary string key, falling back to a
+ * caller-supplied default when nothing is registered.
+ *
+ * This is the seam libraries use to make their own icons themeable: ship the
+ * inline SVG as `fallback`, resolve through this function, and a theme can
+ * override the key via {@link registerIcons} without the library having to
+ * widen the core {@link IconName} union.
+ *
+ * @example
+ * ```
+ * // Library default, overridable by a theme registering 'richtext:bold':
+ * getExtendedIcon('richtext:bold', <BoldGlyph />)
+ * ```
  */
-export function getIcon(name) {
-  return globalRegistry[name] ?? defaultIcons[name];
+export function getExtendedIcon(name, fallback, source) {
+  const themeIcons = getThemeIconOverrides(source);
+  return themeIcons?.[name] ?? globalRegistry[name] ?? defaultIcons[name] ?? fallback;
 }
 
 /**

package/dist/Icon/index.d.ts

@@ -7,7 +7,8 @@
  * SYNC: When modified, update this header and /packages/core/src/Icon/Icon.doc.mjs
  */
 export { Icon, renderIconSlot } from './Icon';
-export type { IconProps, IconColor, IconSize, IconType, } from './Icon';
-export { registerIcons, getIconRegistry, getIcon, resetIcons, } from './globalIconRegistry';
-export type { IconName, IconRegistry } from './globalIconRegistry';
+export { useIcon } from './useIcon';
+export type { IconProps, IconColor, IconSize, IconType } from './Icon';
+export { registerIcons, getIconRegistry, getIcon, getExtendedIcon, resetIcons, } from './globalIconRegistry';
+export type { IconName, ExtendedIconName, IconRegistry, IconRegistrySource, } from './globalIconRegistry';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Icon/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,IAAI,EAAE,cAAc,EAAC,MAAM,QAAQ,CAAC;AAC5C,YAAY,EACV,SAAS,EACT,SAAS,EACT,QAAQ,EACR,QAAQ,GACT,MAAM,QAAQ,CAAC;AAGhB,OAAO,EACL,aAAa,EACb,eAAe,EACf,OAAO,EACP,UAAU,GACX,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAC,QAAQ,EAAE,YAAY,EAAC,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Icon/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,IAAI,EAAE,cAAc,EAAC,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAClC,YAAY,EAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAC,MAAM,QAAQ,CAAC;AAGrE,OAAO,EACL,aAAa,EACb,eAAe,EACf,OAAO,EACP,eAAe,EACf,UAAU,GACX,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,GACnB,MAAM,sBAAsB,CAAC"}

package/dist/Icon/index.js

@@ -11,5 +11,6 @@
  * SYNC: When modified, update this header and /packages/core/src/Icon/Icon.doc.mjs
  */
 export { Icon, renderIconSlot } from "./Icon.js";
+export { useIcon } from "./useIcon.js";
 // Global registry (RSC-compatible, no 'use client')
-export { registerIcons, getIconRegistry, getIcon, resetIcons } from "./globalIconRegistry.js";
+export { registerIcons, getIconRegistry, getIcon, getExtendedIcon, resetIcons } from "./globalIconRegistry.js";

package/dist/Icon/useIcon.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file useIcon.ts
+ * @input Semantic icon name
+ * @output Exports useIcon hook for theme-aware icon lookup
+ * @position Client hook for components that render registry icons directly
+ */
+import type { ReactNode } from 'react';
+import { type IconName } from './globalIconRegistry';
+/**
+ * Resolve a semantic icon name from the nearest Theme, falling back through
+ * root theme registration, global icon overrides, and built-in defaults.
+ */
+export declare function useIcon(name: IconName): ReactNode;
+//# sourceMappingURL=useIcon.d.ts.map

package/dist/Icon/useIcon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIcon.d.ts","sourceRoot":"","sources":["../../src/Icon/useIcon.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAAU,KAAK,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAGjD"}

package/dist/Icon/useIcon.js

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIcon.ts
+ * @input Semantic icon name
+ * @output Exports useIcon hook for theme-aware icon lookup
+ * @position Client hook for components that render registry icons directly
+ */
+import { useThemeName } from "../theme/useTheme.js";
+import { getIcon } from "./globalIconRegistry.js";
+
+/**
+ * Resolve a semantic icon name from the nearest Theme, falling back through
+ * root theme registration, global icon overrides, and built-in defaults.
+ */
+export function useIcon(name) {
+  const themeName = useThemeName();
+  return getIcon(name, themeName);
+}

package/dist/IconButton/IconButton.d.ts

@@ -9,7 +9,7 @@
  * - /packages/core/src/IconButton/IconButton.test.tsx (tests)
  * - /packages/core/src/IconButton/index.ts (exports if types change)
  * - /apps/storybook/stories/IconButton.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/IconButton/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/IconButton/ (showcase blocks)
  */
 import type { ReactNode } from 'react';
 import type { ButtonProps } from '../Button/Button';

package/dist/IconButton/IconButton.js

@@ -13,7 +13,7 @@
  * - /packages/core/src/IconButton/IconButton.test.tsx (tests)
  * - /packages/core/src/IconButton/index.ts (exports if types change)
  * - /apps/storybook/stories/IconButton.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/IconButton/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/IconButton/ (showcase blocks)
  */
 import { Button } from "../Button/Button.js";
 

package/dist/InputGroup/InputGroup.d.ts

@@ -14,7 +14,7 @@
  * - /packages/core/src/InputGroup/InputGroup.test.tsx
  * - /packages/core/src/InputGroup/index.ts
  * - /apps/storybook/stories/InputGroup.stories.tsx
- * - /packages/cli/templates/blocks/components/InputGroup/
+ * - /packages/cli/assets/templates/blocks/components/InputGroup/
  */
 import { type ReactNode } from 'react';
 import { type InputStatus } from '../Field';

package/dist/InputGroup/InputGroup.js

@@ -18,7 +18,7 @@
  * - /packages/core/src/InputGroup/InputGroup.test.tsx
  * - /packages/core/src/InputGroup/index.ts
  * - /apps/storybook/stories/InputGroup.stories.tsx
- * - /packages/cli/templates/blocks/components/InputGroup/
+ * - /packages/cli/assets/templates/blocks/components/InputGroup/
  */
 import { useId, useMemo } from 'react';
 import * as stylex from '@stylexjs/stylex';

package/dist/InputGroup/InputGroupText.d.ts

@@ -7,7 +7,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/InputGroup/InputGroup.doc.mjs
  * - /packages/core/src/InputGroup/index.ts
- * - /packages/cli/templates/blocks/components/InputGroup/
+ * - /packages/cli/assets/templates/blocks/components/InputGroup/
  */
 import React, { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';

package/dist/InputGroup/InputGroupText.js

@@ -11,7 +11,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/InputGroup/InputGroup.doc.mjs
  * - /packages/core/src/InputGroup/index.ts
- * - /packages/cli/templates/blocks/components/InputGroup/
+ * - /packages/cli/assets/templates/blocks/components/InputGroup/
  */
 import React from 'react';
 import * as stylex from '@stylexjs/stylex';

package/dist/Item/Item.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file Item.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, useClickableContainer
  * @output Exports Item component, ItemProps type
  * @position Core layout primitive; consumed by index.ts, tested by Item.test.tsx
  *
@@ -9,9 +9,9 @@
  * - /packages/core/src/Item/Item.test.tsx
  * - /packages/core/src/Item/index.ts
  * - /apps/storybook/stories/Item.stories.tsx
- * - /packages/cli/templates/blocks/components/Item/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Item/ (showcase blocks)
  */
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
 export type ItemAlign = 'center' | 'start';
 export type ItemDensity = 'compact' | 'balanced' | 'spacious';
@@ -72,6 +72,19 @@ export interface ItemProps extends BaseProps<HTMLElement> {
      * Click handler. Makes the item clickable with button semantics.
      */
     onClick?: (event: React.MouseEvent) => void;
+    /**
+     * Ref to a nested control inside the item (e.g. a checkbox in
+     * `startContent`) that already provides the item's keyboard access and
+     * action. When set, the item becomes an enlarged click/tap target that
+     * delegates surface clicks to that control via the `useClickableContainer`
+     * pattern: it renders no invisible button/anchor, so the row adds no second
+     * tab stop (WCAG 4.1.2 — one focusable control per option). Clicks on the
+     * control itself, and on any other nested interactive element, are left to
+     * that element. Mutually exclusive with `onClick`/`href` — when
+     * `interactiveRef` is set those are ignored (the nested control is the sole
+     * action).
+     */
+    interactiveRef?: React.RefObject<HTMLElement | null>;
     /**
      * Link URL. Makes the item a link via an invisible anchor element.
      */
@@ -126,7 +139,7 @@ export interface ItemProps extends BaseProps<HTMLElement> {
  * />
  * ```
  */
-export declare function Item({ as: Component, marker, startContent, label, description, endContent, align, density, labelLines, descriptionLines, onClick, href, target: targetFromProps, rel: relFromProps, isHighlighted, isSelected, isDisabled, xstyle, className, style, ref, role, ...restProps }: ItemProps): import("react").JSX.Element;
+export declare function Item({ as: Component, marker, startContent, label, description, endContent, align, density, labelLines, descriptionLines, onClick, interactiveRef, href, target: targetFromProps, rel: relFromProps, isHighlighted, isSelected, isDisabled, xstyle, className, style, ref, role, ...restProps }: ItemProps): import("react").JSX.Element;
 export declare namespace Item {
     var displayName: string;
 }

package/dist/Item/Item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Item.d.ts","sourceRoot":"","sources":["../../src/Item/Item.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAUrC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAU5C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,WAAW,CAAC;IACvD,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;OAGG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE5C;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA0KD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,EACnB,EAAE,EAAE,SAAiB,EACrB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,WAAW,EACX,UAAU,EACV,KAAgB,EAChB,OAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,IAAI,EACJ,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,YAAY,EACjB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,IAAI,EACJ,GAAG,SAAS,EACb,EAAE,SAAS,+BA+KX;yBAvMe,IAAI"}
+{"version":3,"file":"Item.d.ts","sourceRoot":"","sources":["../../src/Item/Item.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAY5C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,WAAW,CAAC;IACvD,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;OAGG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAErD;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA0KD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,EACnB,EAAE,EAAE,SAAiB,EACrB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,WAAW,EACX,UAAU,EACV,KAAgB,EAChB,OAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,cAAc,EACd,IAAI,EACJ,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,YAAY,EACjB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,IAAI,EACJ,GAAG,SAAS,EACb,EAAE,SAAS,+BA4MX;yBArOe,IAAI"}

package/dist/Item/Item.js

@@ -4,7 +4,7 @@
 
 /**
  * @file Item.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, useClickableContainer
  * @output Exports Item component, ItemProps type
  * @position Core layout primitive; consumed by index.ts, tested by Item.test.tsx
  *
@@ -13,14 +13,17 @@
  * - /packages/core/src/Item/Item.test.tsx
  * - /packages/core/src/Item/index.ts
  * - /apps/storybook/stories/Item.stories.tsx
- * - /packages/cli/templates/blocks/components/Item/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Item/ (showcase blocks)
  */
+import { useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, radiusVars, spacingVars, durationVars, easeVars, typeScaleVars } from "../theme/tokens.stylex.js";
-import { mergeProps } from "../utils/index.js";
+import { mergeProps, mergeRefs } from "../utils/index.js";
 import { computeTargetAndRel } from "../Link/computeTargetAndRel.js";
 import { useLinkComponent } from "../Link/useLinkComponent.js";
+import { useClickableContainer } from "../hooks/useClickableContainer.js";
+import { useDevWarning } from "../hooks/useDevWarning.js";
 import { themeProps } from "../utils/themeProps.js";
 
 // =============================================================================
@@ -176,6 +179,7 @@ export function Item({
   labelLines,
   descriptionLines,
   onClick,
+  interactiveRef,
   href,
   target: targetFromProps,
   rel: relFromProps,
@@ -190,7 +194,23 @@ export function Item({
   ...restProps
 }) {
   const LinkComponent = useLinkComponent();
-  const isInteractive = onClick != null || href != null;
+
+  // Delegation mode: the row is an enlarged click/tap target for a nested
+  // control (e.g. a checkbox) that owns the keyboard access and action. The
+  // control is the row's only tab stop; the row proxies surface clicks to it.
+  const isDelegate = interactiveRef != null;
+  const containerRef = useRef(null);
+  // Only onClick is needed: onMouseUp handles middle-click href navigation,
+  // which delegation mode never has (href is ignored here).
+  const {
+    onClick: delegatedOnClick
+  } = useClickableContainer({
+    containerRef,
+    interactiveRef: interactiveRef ?? undefined,
+    disabled: isDisabled
+  });
+  useDevWarning('Item', '`interactiveRef` is mutually exclusive with `onClick`/`href`. In ' + 'delegation mode the row only forwards clicks to the referenced control, ' + 'so `onClick`/`href` are ignored. Drop one of them.', isDelegate && (onClick != null || href != null));
+  const isInteractive = onClick != null || href != null || isDelegate;
   const {
     target,
     rel
@@ -233,7 +253,12 @@ export function Item({
         className: "x3psx0u x78zum5"
       },
       children: startContent
-    }), hasParentRole ? /*#__PURE__*/_jsx("span", {
+    }), hasParentRole || isDelegate ?
+    /*#__PURE__*/
+    // Delegation mode (and parent-role mode) put the label in a plain span:
+    // keyboard access lives on the nested control, so no invisible
+    // button/anchor is rendered and the row adds no second tab stop.
+    _jsx("span", {
       ...{
         0: {
           className: "x78zum5 xdt5ytf x98rzlu xeuugli x1yc453h"
@@ -294,7 +319,7 @@ export function Item({
     })]
   });
   return /*#__PURE__*/_jsx(Component, {
-    ref: ref,
+    ref: isDelegate ? mergeRefs(ref, containerRef) : ref,
     ...restProps,
     "aria-selected": allowsAriaSelected && isSelected || undefined
     // aria-selected is invalid on roles that don't permit it (listitem, a
@@ -309,7 +334,7 @@ export function Item({
       align
     }), stylex.props(styles.root, densityStyles[density], align === 'start' && styles.alignStart, isInteractive && styles.interactive, isInteractive && styles.focusVisibleOutline, isHighlighted && styles.highlighted, isSelected && styles.selected, isDisabled && !hasParentRole && styles.disabled, xstyle), className, style),
     role: role,
-    onClick: hasParentRole ? onClick : isInteractive ? handleContainerClick : undefined,
+    onClick: isDelegate ? delegatedOnClick : hasParentRole ? onClick : isInteractive ? handleContainerClick : undefined,
     children: innerContent
   });
 }

package/dist/Kbd/Kbd.d.ts

@@ -6,7 +6,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Kbd/index.ts
- * - /packages/cli/templates/blocks/components/Kbd/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Kbd/ (showcase blocks)
  */
 import React from 'react';
 import type { BaseProps } from '../BaseProps';

package/dist/Kbd/Kbd.js

@@ -10,7 +10,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Kbd/index.ts
- * - /packages/cli/templates/blocks/components/Kbd/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Kbd/ (showcase blocks)
  */
 import React, { useSyncExternalStore } from 'react';
 import * as stylex from '@stylexjs/stylex';

package/dist/Layout/Layout.d.ts

@@ -10,7 +10,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 import { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';

package/dist/Layout/Layout.js

@@ -14,7 +14,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 import { useMemo } from 'react';
 import * as stylex from '@stylexjs/stylex';

package/dist/Layout/LayoutContent.d.ts

@@ -8,7 +8,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 import type { AriaRole, ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';

package/dist/Layout/LayoutContent.js

@@ -12,7 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 import { use } from 'react';
 import * as stylex from '@stylexjs/stylex';

package/dist/Layout/LayoutFooter.d.ts

@@ -8,7 +8,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 import type { AriaRole, ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';

package/dist/Layout/LayoutFooter.js

@@ -12,7 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 import { use } from 'react';
 import * as stylex from '@stylexjs/stylex';

package/dist/Layout/LayoutHeader.d.ts

@@ -8,7 +8,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 import type { AriaRole, ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';

package/dist/Layout/LayoutHeader.js

@@ -12,7 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 import { use } from 'react';
 import * as stylex from '@stylexjs/stylex';

package/dist/Layout/LayoutPanel.d.ts

@@ -8,7 +8,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 import type { AriaRole, ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';