@astryxdesign/core 0.1.7 → 0.1.8-canary.c5fa19b

package/dist/DropdownMenu/DropdownMenuRadioGroup.js

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DropdownMenuRadioGroup.tsx
+ * @output DropdownMenuRadioGroup — a single-select group of menu items.
+ * @position Sub-component; wraps DropdownMenuRadioItem inside a DropdownMenu.
+ *
+ * Owns single-selection state (value/onChange) for its child
+ * DropdownMenuRadioItems and exposes it via context. Renders role="group" with
+ * an accessible name so the radios are announced as a set. Keyboard navigation
+ * comes from the parent DropdownMenu's useListFocus, which matches
+ * menuitemradio rows.
+ */
+import { useMemo } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { spacingVars } from "../theme/tokens.stylex.js";
+import { mergeProps } from "../utils/index.js";
+import { DropdownMenuRadioGroupContext } from "./DropdownMenuContext.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A single-select group of radio menu items (role="group" of menuitemradio).
+ *
+ * @example
+ * ```
+ *  * import {
+ *   DropdownMenuRadioGroup,
+ *   DropdownMenuRadioItem,
+ * } from '@astryxdesign/core/DropdownMenu';
+ *
+ * <DropdownMenu button={{label: 'Sort'}}>
+ *   <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
+ *     <DropdownMenuRadioItem value="newest" label="Newest" />
+ *     <DropdownMenuRadioItem value="oldest" label="Oldest" />
+ *   </DropdownMenuRadioGroup>
+ * </DropdownMenu>
+ * ```
+ */
+export function DropdownMenuRadioGroup({
+  value,
+  onChange,
+  hasCloseOnSelect = true,
+  children,
+  className,
+  style,
+  ...rest
+}) {
+  const contextValue = useMemo(() => ({
+    value,
+    onChange,
+    hasCloseOnSelect
+  }), [value, onChange, hasCloseOnSelect]);
+  return /*#__PURE__*/_jsx("div", {
+    ...rest,
+    role: "group",
+    ...mergeProps({
+      className: "x78zum5 xdt5ytf x1lsbc85"
+    }, {
+      className,
+      style
+    }),
+    children: /*#__PURE__*/_jsx(DropdownMenuRadioGroupContext, {
+      value: contextValue,
+      children: children
+    })
+  });
+}
+DropdownMenuRadioGroup.displayName = 'DropdownMenuRadioGroup';

package/dist/DropdownMenu/DropdownMenuRadioItem.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @file DropdownMenuRadioItem.tsx
+ * @input React, stylex, Item + Icon + DropdownMenu context + tokens from core
+ * @output DropdownMenuRadioItem — a single option in a radio group.
+ * @position Sub-component; must be used inside a DropdownMenuRadioGroup.
+ *
+ * A menu item representing one option in a single-select group
+ * (role="menuitemradio"). The row owns the role and aria-checked; there is no
+ * nested native <input> (per the WAI-ARIA menuitemradio pattern). Selection
+ * state + onChange come from DropdownMenuRadioGroupContext. Keyboard nav +
+ * Enter/Space activation come from the parent DropdownMenu.
+ *
+ * The round radio visual (circle + center dot) is decorative (aria-hidden) —
+ * the row owns the checked state. Its size is derived from the menu's item size
+ * and it swaps to the inline-end of the row on coarse-pointer (touch) devices
+ * via CSS `order`. The dot is a shaped element, not an icon (a filled circle
+ * has no registry glyph).
+ */
+import { type ReactNode } from 'react';
+import { type IconType } from '../Icon';
+import type { BaseProps } from '../BaseProps';
+export interface DropdownMenuRadioItemProps extends Omit<BaseProps, 'role' | 'aria-checked' | 'tabIndex'> {
+    /**
+     * The value this item represents within its group. The group's `value`
+     * matches against this to determine the checked state.
+     */
+    value: string;
+    /**
+     * Primary label text identifying the option.
+     */
+    label: ReactNode;
+    /**
+     * Secondary description text displayed below the label.
+     */
+    description?: ReactNode;
+    /**
+     * Icon to display before the label. Accepts a semantic icon name (see
+     * `npx astryx docs icons`) or a rendered node.
+     */
+    icon?: ReactNode | IconType;
+    /**
+     * Whether this individual radio item is disabled. Disabled items stay
+     * focusable (via `aria-disabled`) so they remain discoverable by keyboard
+     * and assistive technology, but selection is blocked.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * Content to render after the label and description, such as a badge or
+     * metadata.
+     */
+    endContent?: ReactNode;
+}
+/**
+ * A single option in a DropdownMenuRadioGroup (role="menuitemradio").
+ *
+ * @example
+ * ```
+ * <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
+ *   <DropdownMenuRadioItem value="newest" label="Newest" />
+ *   <DropdownMenuRadioItem value="oldest" label="Oldest" icon="clock" />
+ * </DropdownMenuRadioGroup>
+ * ```
+ */
+export declare function DropdownMenuRadioItem({ value, label, description, icon, isDisabled, endContent, xstyle, className, style, ...rest }: DropdownMenuRadioItemProps): import("react").JSX.Element;
+export declare namespace DropdownMenuRadioItem {
+    var displayName: string;
+}
+//# sourceMappingURL=DropdownMenuRadioItem.d.ts.map

package/dist/DropdownMenu/DropdownMenuRadioItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DropdownMenuRadioItem.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenuRadioItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAc,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAElD,OAAO,EAAiB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAWtD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAsE5C,MAAM,WAAW,0BAA2B,SAAQ,IAAI,CACtD,SAAS,EACT,MAAM,GAAG,cAAc,GAAG,UAAU,CACrC;IACC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,KAAK,EACL,WAAW,EACX,IAAI,EACJ,UAAkB,EAClB,UAAU,EACV,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,0BAA0B,+BAiE5B;yBA5Ee,qBAAqB"}

package/dist/DropdownMenu/DropdownMenuRadioItem.js

@@ -0,0 +1,178 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DropdownMenuRadioItem.tsx
+ * @input React, stylex, Item + Icon + DropdownMenu context + tokens from core
+ * @output DropdownMenuRadioItem — a single option in a radio group.
+ * @position Sub-component; must be used inside a DropdownMenuRadioGroup.
+ *
+ * A menu item representing one option in a single-select group
+ * (role="menuitemradio"). The row owns the role and aria-checked; there is no
+ * nested native <input> (per the WAI-ARIA menuitemradio pattern). Selection
+ * state + onChange come from DropdownMenuRadioGroupContext. Keyboard nav +
+ * Enter/Space activation come from the parent DropdownMenu.
+ *
+ * The round radio visual (circle + center dot) is decorative (aria-hidden) —
+ * the row owns the checked state. Its size is derived from the menu's item size
+ * and it swaps to the inline-end of the row on coarse-pointer (touch) devices
+ * via CSS `order`. The dot is a shaped element, not an icon (a filled circle
+ * has no registry glyph).
+ */
+import { useCallback } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { renderIconSlot } from "../Icon/index.js";
+import { Item } from "../Item/index.js";
+import { useDropdownMenuContext } from "./DropdownMenuContext.js";
+import "../theme/tokens.stylex.js";
+import { colorVars, spacingVars, durationVars, easeVars, borderVars } from "../theme/tokens.stylex.js";
+import { mergeProps, themeProps } from "../utils/index.js";
+import { useDropdownMenuRadioGroupContext } from "./DropdownMenuContext.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const styles = {
+  root: {
+    kzqmXN: "xh8yej3",
+    kaIpWk: "x1ws5lxm",
+    kMwMTN: "x1tgivj0",
+    kWkggS: "xjbqb8w x1c52tdz x1uwx2nv",
+    kkrTdU: "x1ypdohk",
+    kI3sdo: "x1a2a7pz",
+    $$css: true
+  },
+  disabled: {
+    kSiTet: "xbyyjgo",
+    kkrTdU: "x1h6gzvc",
+    $$css: true
+  },
+  circle: {
+    k1xSpc: "x78zum5",
+    kGNEyG: "x6s0dn4",
+    kjj79g: "xl56j7k",
+    kmuXW: "x2lah0s",
+    kB7OPa: "x9f619",
+    kMzoRj: "x1litavf",
+    ksu8eU: "x1y0btm7",
+    kaIpWk: "x16rqkct",
+    k1ekBW: "xts7igz",
+    kIyJzY: "xuedmi6 x12w9bfk",
+    kAMwcw: "xlr8y92",
+    kayTVb: "x1g77sc7 xozvky",
+    keTefX: "x1lziwak x1jymrmb",
+    $$css: true
+  },
+  unchecked: {
+    kVAM5u: "xvy26l8",
+    kWkggS: "x10xzikg",
+    $$css: true
+  },
+  checked: {
+    kVAM5u: "xad5do",
+    kWkggS: "x1ewilqj",
+    $$css: true
+  },
+  dot: {
+    kaIpWk: "x16rqkct",
+    kWkggS: "x1azo05",
+    $$css: true
+  }
+};
+const circleSizeStyles = {
+  sm: {
+    kzqmXN: "x1xp8n7a",
+    kZKoxP: "xmix8c7",
+    $$css: true
+  },
+  md: {
+    kzqmXN: "x17z2i9w",
+    kZKoxP: "x17rw0jw",
+    $$css: true
+  }
+};
+const dotSizeStyles = {
+  sm: {
+    kzqmXN: "x1v4s8kt",
+    kZKoxP: "xols6we",
+    $$css: true
+  },
+  md: {
+    kzqmXN: "x1xc55vz",
+    kZKoxP: "xdk7pt",
+    $$css: true
+  }
+};
+/**
+ * A single option in a DropdownMenuRadioGroup (role="menuitemradio").
+ *
+ * @example
+ * ```
+ * <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
+ *   <DropdownMenuRadioItem value="newest" label="Newest" />
+ *   <DropdownMenuRadioItem value="oldest" label="Oldest" icon="clock" />
+ * </DropdownMenuRadioGroup>
+ * ```
+ */
+export function DropdownMenuRadioItem({
+  value,
+  label,
+  description,
+  icon,
+  isDisabled = false,
+  endContent,
+  xstyle,
+  className,
+  style,
+  ...rest
+}) {
+  const menuCtx = useDropdownMenuContext();
+  const groupCtx = useDropdownMenuRadioGroupContext();
+  if (!groupCtx) {
+    throw new Error('DropdownMenuRadioItem must be used within a DropdownMenuRadioGroup');
+  }
+  const menuSize = menuCtx?.menuSize ?? 'md';
+  const controlSize = menuSize === 'sm' ? 'sm' : 'md';
+  const isChecked = groupCtx.value === value;
+  const handleClick = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
+    groupCtx.onChange(value);
+    if (groupCtx.hasCloseOnSelect) {
+      menuCtx?.closeMenu();
+    }
+  }, [isDisabled, groupCtx, value, menuCtx]);
+  return /*#__PURE__*/_jsx(Item, {
+    ...rest,
+    role: "menuitemradio",
+    "aria-checked": isChecked,
+    tabIndex: isDisabled ? undefined : -1,
+    marker: /*#__PURE__*/_jsx("span", {
+      "aria-hidden": "true",
+      ...mergeProps(themeProps('dropdown-menu-radio', {
+        size: controlSize,
+        checked: isChecked ? 'checked' : null,
+        disabled: isDisabled ? 'disabled' : null
+      }), stylex.props(styles.circle, circleSizeStyles[controlSize], isChecked ? styles.checked : styles.unchecked)),
+      children: isChecked && /*#__PURE__*/_jsx("span", {
+        ...stylex.props(styles.dot, dotSizeStyles[controlSize])
+      })
+    }),
+    startContent: icon ? renderIconSlot(icon, {
+      size: 'sm',
+      color: 'secondary'
+    }) : undefined,
+    label: label,
+    description: description,
+    endContent: endContent,
+    onClick: handleClick,
+    isDisabled: isDisabled,
+    xstyle: [styles.root, isDisabled && styles.disabled, xstyle],
+    ...mergeProps(themeProps('dropdown-menu-item', {
+      size: menuSize
+    }), {
+      className,
+      style
+    })
+  });
+}
+DropdownMenuRadioItem.displayName = 'DropdownMenuRadioItem';

package/dist/DropdownMenu/index.d.ts

@@ -4,5 +4,9 @@
  * @position Public API entry point
  */
 export { DropdownMenu, type DropdownMenuProps, type DropdownMenuButtonProps, type DropdownMenuItemData, type DropdownMenuDivider, type DropdownMenuSection, type DropdownMenuOption, } from './DropdownMenu';
-export { DropdownMenuItem, type DropdownMenuItemProps, } from './DropdownMenuItem';
+export { DropdownMenuItem, type DropdownMenuItemProps } from './DropdownMenuItem';
+export { DropdownMenuCheckboxItem, type DropdownMenuCheckboxItemProps, } from './DropdownMenuCheckboxItem';
+export { DropdownMenuRadioGroup, type DropdownMenuRadioGroupProps, } from './DropdownMenuRadioGroup';
+export { DropdownMenuRadioItem, type DropdownMenuRadioItemProps, } from './DropdownMenuRadioItem';
+export { DropdownMenuContext, useDropdownMenuContext, type DropdownMenuContextValue, type DropdownMenuSize, } from './DropdownMenuContext';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/index.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,GAC3B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/index.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAC,gBAAgB,EAAE,KAAK,qBAAqB,EAAC,MAAM,oBAAoB,CAAC;AAGhF,OAAO,EACL,wBAAwB,EACxB,KAAK,6BAA6B,GACnC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,sBAAsB,EACtB,KAAK,2BAA2B,GACjC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC"}

package/dist/DropdownMenu/index.js

@@ -8,4 +8,13 @@
  * @position Public API entry point
  */
 export { DropdownMenu } from "./DropdownMenu.js";
-export { DropdownMenuItem } from "./DropdownMenuItem.js";
+export { DropdownMenuItem } from "./DropdownMenuItem.js";
+
+// Selectable items — checkbox (independent) and radio (single-select group).
+export { DropdownMenuCheckboxItem } from "./DropdownMenuCheckboxItem.js";
+export { DropdownMenuRadioGroup } from "./DropdownMenuRadioGroup.js";
+export { DropdownMenuRadioItem } from "./DropdownMenuRadioItem.js";
+
+// Menu-coordination context — public so consumers can build custom menu items
+// that read the menu size / close the menu.
+export { DropdownMenuContext, useDropdownMenuContext } from "./DropdownMenuContext.js";

package/dist/DropdownMenu/menuItemRoles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file menuItemRoles.ts
+ * @output Shared menu-item role set + focus selector.
+ * @position Internal; used by DropdownMenu and ContextMenu so their
+ *   roving-focus, typeahead, and Enter/Space activation stay in sync.
+ *
+ * Includes the selectable items (menuitemradio/menuitemcheckbox) alongside
+ * plain menuitem so checkbox/radio rows are reachable by arrow keys, typeahead,
+ * and Enter/Space — not just role="menuitem".
+ */
+export declare const MENU_ITEM_ROLES: ReadonlySet<string>;
+export declare const MENU_ITEM_SELECTOR: string;
+//# sourceMappingURL=menuItemRoles.d.ts.map

package/dist/DropdownMenu/menuItemRoles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menuItemRoles.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/menuItemRoles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAI9C,CAAC;AAEH,eAAO,MAAM,kBAAkB,EAAE,MAErB,CAAC"}

package/dist/DropdownMenu/menuItemRoles.js

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file menuItemRoles.ts
+ * @output Shared menu-item role set + focus selector.
+ * @position Internal; used by DropdownMenu and ContextMenu so their
+ *   roving-focus, typeahead, and Enter/Space activation stay in sync.
+ *
+ * Includes the selectable items (menuitemradio/menuitemcheckbox) alongside
+ * plain menuitem so checkbox/radio rows are reachable by arrow keys, typeahead,
+ * and Enter/Space — not just role="menuitem".
+ */
+
+export const MENU_ITEM_ROLES = new Set(['menuitem', 'menuitemradio', 'menuitemcheckbox']);
+export const MENU_ITEM_SELECTOR = [...MENU_ITEM_ROLES].map(role => `[role="${role}"]:not([aria-disabled="true"])`).join(',');

package/dist/Icon/Icon.d.ts

@@ -82,23 +82,28 @@ declare const colorStyles: Readonly<{
 /**
  * Size styles for direct SVG icon components.
  * Uses width/height only — SVG components handle their own viewBox scaling.
+ *
+ * Sizes are expressed in `rem` (relative to the root font-size) so icons scale
+ * in step with text when the document font-size changes, matching the rest of
+ * the design system's rem-based type scale. Values are the px-equivalents at a
+ * 16px root: 12px → 0.75rem, 16px → 1rem, 20px → 1.25rem, 24px → 1.5rem.
  */
 declare const sizeStyles: Readonly<{
     readonly xsm: Readonly<{
-        readonly width: stylex.StyleXClassNameFor<"width", 12>;
-        readonly height: stylex.StyleXClassNameFor<"height", 12>;
+        readonly width: stylex.StyleXClassNameFor<"width", "0.75rem">;
+        readonly height: stylex.StyleXClassNameFor<"height", "0.75rem">;
     }>;
     readonly sm: Readonly<{
-        readonly width: stylex.StyleXClassNameFor<"width", 16>;
-        readonly height: stylex.StyleXClassNameFor<"height", 16>;
+        readonly width: stylex.StyleXClassNameFor<"width", "1rem">;
+        readonly height: stylex.StyleXClassNameFor<"height", "1rem">;
     }>;
     readonly md: Readonly<{
-        readonly width: stylex.StyleXClassNameFor<"width", 20>;
-        readonly height: stylex.StyleXClassNameFor<"height", 20>;
+        readonly width: stylex.StyleXClassNameFor<"width", "1.25rem">;
+        readonly height: stylex.StyleXClassNameFor<"height", "1.25rem">;
     }>;
     readonly lg: Readonly<{
-        readonly width: stylex.StyleXClassNameFor<"width", 24>;
-        readonly height: stylex.StyleXClassNameFor<"height", 24>;
+        readonly width: stylex.StyleXClassNameFor<"width", "1.5rem">;
+        readonly height: stylex.StyleXClassNameFor<"height", "1.5rem">;
     }>;
 }>;
 export type IconColor = keyof typeof colorStyles;
@@ -128,13 +133,38 @@ export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'
     color?: IconColor;
     /**
      * The size of the icon.
-     * - 'xsm': 12px
-     * - 'sm': 16px
-     * - 'md': 20px
-     * - 'lg': 24px
+     * - 'xsm': 0.75rem (12px at a 16px root)
+     * - 'sm': 1rem (16px at a 16px root)
+     * - 'md': 1.25rem (20px at a 16px root)
+     * - 'lg': 1.5rem (24px at a 16px root)
      * @default 'md'
      */
     size?: IconSize;
+    /**
+     * Accessible name for the icon. Set this only when the icon is MEANINGFUL on
+     * its own — a standalone status glyph or an icon-only indicator with no
+     * adjacent text conveying the same information. Providing it exposes the icon
+     * to assistive tech as `role="img"` with this string as the accessible name
+     * (via `aria-label`) and drops the default `aria-hidden="true"`.
+     *
+     * Omit it (the default) for decorative icons — the common case, e.g. an icon
+     * beside a text label — and the icon stays hidden from assistive tech
+     * (`aria-hidden="true"`). An empty string (`''`) is treated the same as
+     * omitting it (decorative), since an empty accessible name is meaningless.
+     *
+     * Don't set `label` when an interactive parent (Button, IconButton, link)
+     * already names the control — that produces a duplicate announcement.
+     *
+     * @example
+     * ```
+     * // Meaningful, standalone icon
+     * <Icon icon="success" label="Completed" />
+     *
+     * // Decorative icon (default) — omit label
+     * <Icon icon="search" />
+     * ```
+     */
+    label?: string;
 }
 /**
  * Renders an icon from the icon registry or a custom SVG component.
@@ -144,7 +174,7 @@ export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'
  * <Icon icon="close" size="md" color="primary" />
  * ```
  */
-export declare function Icon({ icon, color, size, ref, ...props }: IconProps): React.JSX.Element;
+export declare function Icon({ icon, color, size, label, ref, ...props }: IconProps): React.JSX.Element;
 export declare namespace Icon {
     var displayName: string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAqBnD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2Df,CAAC;AAEH;;;GAGG;AACH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;EAiBd,CAAC;AAiCH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;OAIG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAMD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAW,EACX,GAAG,EACH,GAAG,KAAK,EACT,EAAE,SAAS,qBA0BX;yBAhCe,IAAI;;;AAiFpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}
+{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAqBnD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2Df,CAAC;AAEH;;;;;;;;GAQG;AACH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;EAiBd,CAAC;AAyCH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;OAIG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyBD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAW,EACX,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,SAAS,qBAkCX;yBAzCe,IAAI;;;AA4FpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}

package/dist/Icon/Icon.js

@@ -128,26 +128,31 @@ const colorStyles = {
 /**
  * Size styles for direct SVG icon components.
  * Uses width/height only — SVG components handle their own viewBox scaling.
+ *
+ * Sizes are expressed in `rem` (relative to the root font-size) so icons scale
+ * in step with text when the document font-size changes, matching the rest of
+ * the design system's rem-based type scale. Values are the px-equivalents at a
+ * 16px root: 12px → 0.75rem, 16px → 1rem, 20px → 1.25rem, 24px → 1.5rem.
  */
 const sizeStyles = {
   xsm: {
-    kzqmXN: "xsmyaan",
-    kZKoxP: "x1kpxq89",
+    kzqmXN: "x1jw3ynk",
+    kZKoxP: "xvle69y",
     $$css: true
   },
   sm: {
-    kzqmXN: "x1kky2od",
-    kZKoxP: "xlup9mm",
+    kzqmXN: "xcdlrvm",
+    kZKoxP: "x1l36t39",
     $$css: true
   },
   md: {
-    kzqmXN: "xw4jnvo",
-    kZKoxP: "x1qx5ct2",
+    kzqmXN: "xwqq7k2",
+    kZKoxP: "xmll18r",
     $$css: true
   },
   lg: {
-    kzqmXN: "xvy4d1p",
-    kZKoxP: "xxk0z11",
+    kzqmXN: "xp8d6y2",
+    kZKoxP: "xam5rvr",
     $$css: true
   }
 };
@@ -155,30 +160,33 @@ const sizeStyles = {
 /**
  * Size styles for string-based (registry) icons.
  * Includes fontSize so that 1em-based icons from the registry scale correctly.
+ *
+ * Expressed in `rem` for the same reason as {@link sizeStyles} — icons track the
+ * root font-size instead of being locked to absolute pixels.
  */
 const spanSizeStyles = {
   xsm: {
-    kzqmXN: "xsmyaan",
-    kZKoxP: "x1kpxq89",
-    kGuDYH: "xfifm61",
+    kzqmXN: "x1jw3ynk",
+    kZKoxP: "xvle69y",
+    kGuDYH: "xboafo0",
     $$css: true
   },
   sm: {
-    kzqmXN: "x1kky2od",
-    kZKoxP: "xlup9mm",
-    kGuDYH: "x1j61zf2",
+    kzqmXN: "xcdlrvm",
+    kZKoxP: "x1l36t39",
+    kGuDYH: "x1jchvi3",
     $$css: true
   },
   md: {
-    kzqmXN: "xw4jnvo",
-    kZKoxP: "x1qx5ct2",
-    kGuDYH: "xwsyq91",
+    kzqmXN: "xwqq7k2",
+    kZKoxP: "xmll18r",
+    kGuDYH: "x1603h9y",
     $$css: true
   },
   lg: {
-    kzqmXN: "xvy4d1p",
-    kZKoxP: "xxk0z11",
-    kGuDYH: "x1pvqxga",
+    kzqmXN: "xp8d6y2",
+    kZKoxP: "xam5rvr",
+    kGuDYH: "xngnso2",
     $$css: true
   }
 };
@@ -197,6 +205,26 @@ const spanSizeStyles = {
  * Extends SVGProps to allow passing additional SVG attributes (used when icon is a component).
  */
 
+/**
+ * Derives the ARIA attributes for an icon from its `label` prop.
+ *
+ * - Non-empty `label` → meaningful image: `role="img"` + `aria-label`, and no
+ *   `aria-hidden` (an `aria-hidden` element is removed from the accessibility
+ *   tree, so its accessible name would be ignored).
+ * - Omitted or empty `label` → decorative default: `aria-hidden="true"`.
+ *
+ * The result is spread BEFORE `{...props}` in both render modes so an explicit
+ * `aria-hidden` / `role` / `aria-label` from the consumer always wins.
+ */
+function getIconA11yProps(label) {
+  return label != null && label !== '' ? {
+    role: 'img',
+    'aria-label': label
+  } : {
+    'aria-hidden': 'true'
+  };
+}
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -213,15 +241,21 @@ export function Icon({
   icon,
   color = 'inherit',
   size = 'md',
+  label,
   ref,
   ...props
 }) {
+  // Derive ARIA from `label`: decorative (aria-hidden) by default, or a
+  // meaningful image (role="img" + aria-label) when `label` is non-empty.
+  const a11yProps = getIconA11yProps(label);
+
   // String mode: resolve from icon registry, wrap in styled span
   if (typeof icon === 'string') {
     return /*#__PURE__*/_jsx(IconFromRegistry, {
       name: icon,
       color: color,
       size: size,
+      a11yProps: a11yProps,
       spanProps: props
     });
   }
@@ -229,8 +263,12 @@ export function Icon({
   // Component mode: render SVG component directly with ref forwarding
   const IconComponent = icon;
   return /*#__PURE__*/_jsx(IconComponent, {
-    ref: ref,
-    "aria-hidden": "true",
+    ref: ref
+    // Derived a11y (decorative default or meaningful `label`) is spread
+    // BEFORE {...props} so an explicit aria-hidden/role/aria-label from the
+    // consumer still wins as an escape hatch.
+    ,
+    ...a11yProps,
     ...mergeProps(themeProps('icon', {
       size,
       color
@@ -255,6 +293,7 @@ function IconFromRegistry({
   name,
   color,
   size,
+  a11yProps,
   spanProps
 }) {
   const resolvedIcon = getIcon(name);
@@ -262,11 +301,7 @@ function IconFromRegistry({
     return null;
   }
   return /*#__PURE__*/_jsx("span", {
-    // Decorative by default, but placed BEFORE the prop spread so consumers
-    // can override it (e.g. `aria-hidden={false}` + `role="img"` +
-    // `aria-label`) to expose a meaningful standalone icon. This matches
-    // component-mode Icon, which already sets aria-hidden before its spread.
-    "aria-hidden": "true",
+    ...a11yProps,
     ...spanProps,
     ...mergeProps(themeProps('icon', {
       size,