@astryxdesign/core 0.5.2-canary.2da7a39 → 0.5.2-canary.2e51213

package/src/RadioList/RadioList.test.tsx

@@ -666,13 +666,147 @@ describe('RadioList', () => {
             value="a"
             data-testid="item-a"
             id="item-a-id"
-            aria-label="First option"
+            aria-describedby="help-text"
           />
         </RadioList>,
       );
       const item = screen.getByTestId('item-a');
       expect(item).toHaveAttribute('id', 'item-a-id');
-      expect(item).toHaveAttribute('aria-label', 'First option');
+      expect(item).toHaveAttribute('aria-describedby', 'help-text');
+    });
+
+    it('routes aria-label to the radio control, not the row', () => {
+      render(
+        <RadioList label="Preference" value="" onChange={() => {}}>
+          <RadioListItem
+            label="Option A"
+            value="a"
+            data-testid="item-a"
+            aria-label="First option"
+          />
+        </RadioList>,
+      );
+      expect(screen.getByTestId('item-a')).not.toHaveAttribute('aria-label');
+      expect(
+        screen.getByRole('radio', {name: 'First option'}),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('RadioListItem rich content', () => {
+    it('names the radio from the text of a ReactNode label', () => {
+      render(
+        <RadioList label="Plans" value="" onChange={() => {}}>
+          <RadioListItem
+            label={
+              <span>
+                Pro plan <em>(recommended)</em>
+              </span>
+            }
+            value="pro"
+          />
+        </RadioList>,
+      );
+      // The radio points at its visible label, so the name is computed from
+      // the rich node's own text — unlike CheckboxListItem, whose control has
+      // a separate hidden label and needs aria-label to say anything useful.
+      expect(
+        screen.getByRole('radio', {name: 'Pro plan (recommended)'}),
+      ).toBeInTheDocument();
+    });
+
+    it('lets aria-label override the name a ReactNode label would compute', () => {
+      render(
+        <RadioList label="Plans" value="" onChange={() => {}}>
+          <RadioListItem
+            label={
+              <span>
+                Pro plan <em>(recommended)</em>
+              </span>
+            }
+            aria-label="Pro plan"
+            value="pro"
+          />
+        </RadioList>,
+      );
+      expect(screen.getByRole('radio', {name: 'Pro plan'})).toBeInTheDocument();
+    });
+
+    it('selects the option when a ReactNode label is clicked', async () => {
+      const onChange = vi.fn();
+      const user = userEvent.setup();
+      render(
+        <RadioList label="Plans" value="" onChange={onChange}>
+          <RadioListItem label={<span>Pro plan</span>} value="pro" />
+        </RadioList>,
+      );
+      await user.click(screen.getByText('Pro plan'));
+      expect(onChange).toHaveBeenCalledWith('pro');
+    });
+
+    it('keeps a link in a ReactNode label independent from selection', async () => {
+      const onChange = vi.fn();
+      const user = userEvent.setup();
+      render(
+        <RadioList label="Plans" value="" onChange={onChange}>
+          <RadioListItem
+            label={
+              <>
+                Pro plan <a href="#pricing">pricing details</a>
+              </>
+            }
+            aria-label="Pro plan"
+            value="pro"
+          />
+        </RadioList>,
+      );
+      const radio = screen.getByRole('radio', {name: 'Pro plan'});
+      const link = screen.getByRole('link', {name: 'pricing details'});
+      await user.tab();
+      expect(radio).toHaveFocus();
+      await user.tab();
+      expect(link).toHaveFocus();
+      await user.click(link);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('renders a ReactNode description and keeps it linked to the radio', async () => {
+      const onChange = vi.fn();
+      const user = userEvent.setup();
+      render(
+        <RadioList label="Plans" value="" onChange={onChange}>
+          <RadioListItem
+            label="Pro plan"
+            description={
+              <span>
+                See the <a href="#pricing">pricing page</a>
+              </span>
+            }
+            value="pro"
+          />
+        </RadioList>,
+      );
+      const radio = screen.getByRole('radio', {name: 'Pro plan'});
+      expect(radio).toHaveAccessibleDescription('See the pricing page');
+      // The row delegates surface clicks to the radio, but a nested link is
+      // its own click target — following it must not also select the option.
+      await user.click(screen.getByRole('link', {name: 'pricing page'}));
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('leaves aria-describedby off when a conditional description renders nothing', () => {
+      const showDetails = false;
+      render(
+        <RadioList label="Plans" value="" onChange={() => {}}>
+          <RadioListItem
+            label="Pro plan"
+            // The common conditional-slot idiom yields `false`, not undefined.
+            description={showDetails && <span>Billing details</span>}
+            value="pro"
+          />
+        </RadioList>,
+      );
+      expect(screen.getByRole('radio')).not.toHaveAttribute('aria-describedby');
     });
   });
 

package/src/RadioList/RadioListItem.doc.mjs

@@ -7,7 +7,8 @@ export const docs = {
   subComponentOf: 'RadioList',
   displayName: 'Radio List Item',
   isHiddenFromOverview: true,
-  description: 'Individual radio item with label, description, and content slots.',
+  description:
+    'Individual radio item with label, description, and content slots.',
   // RadioListItem requires RadioList context; wrap it so the preview doesn't throw.
   playground: {
     defaults: {value: 'option-1', label: 'Option'},
@@ -19,10 +20,17 @@ export const docs = {
   props: [
     {
       name: 'label',
-      type: 'string',
-      description: 'Label text for the radio item.',
+      type: 'ReactNode',
+      description:
+        'Primary label for the radio item. Rich labels may contain links or buttons, which keep their own behavior without selecting the item. The label text names the radio; pair it with aria-label when that text does not read well on its own.',
       required: true,
     },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description:
+        'Plain-text accessible name for the radio, applied to the control rather than the row. It overrides whatever the label element computes — a plain string label included — so reach for it when a rich label\u2019s own text is absent or reads badly.',
+    },
     {
       name: 'value',
       type: 'string',
@@ -31,8 +39,9 @@ export const docs = {
     },
     {
       name: 'description',
-      type: 'string',
-      description: 'Description text displayed below the label.',
+      type: 'ReactNode',
+      description:
+        'Secondary content displayed below the label. Links and buttons keep their own click behaviour — the row only delegates clicks from its non-interactive surface to the radio.',
     },
     {
       name: 'isDisabled',
@@ -85,10 +94,17 @@ export const docsZh = {
   props: [
     {
       name: 'label',
-      type: 'string',
-      description: '单选选项的标签文本。',
+      type: 'ReactNode',
+      description:
+        '单选选项的主标签。富内容标签可包含链接或按钮，它们保留自身行为且不会选中该选项。标签文本用于命名单选框；若朗读效果不佳，请同时传入 aria-label。',
       required: true,
     },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description:
+        '单选框的纯文本无障碍名称，应用于控件本身而非整行。它会覆盖标签元素计算出的名称（包括纯字符串标签），因此仅在富文本标签自身缺少文本或朗读效果不佳时使用。',
+    },
     {
       name: 'value',
       type: 'string',
@@ -97,8 +113,9 @@ export const docsZh = {
     },
     {
       name: 'description',
-      type: 'string',
-      description: '显示在标签下方的描述文本。',
+      type: 'ReactNode',
+      description:
+        '显示在标签下方的次要内容。链接和按钮保留自身的点击行为——整行仅将非交互区域的点击委派给单选框。',
     },
     {
       name: 'isDisabled',
@@ -125,9 +142,11 @@ export const docsDense = {
   displayName: 'Radio List Item',
   description: 'Individual radio item w/ label, description, content slots.',
   propDescriptions: {
-    label: 'Label text for radio item.',
+    label:
+      'Primary label. String or ReactNode; nested controls keep their behavior.',
+    'aria-label': 'Plain-text radio name; overrides any label.',
     value: 'Value of this radio item.',
-    description: 'Description text below label.',
+    description: 'Secondary content below label. String or ReactNode.',
     isDisabled: 'Whether this individual radio item disabled.',
     startContent: 'Content rendered before radio circle.',
     endContent: 'Content rendered after label.',

package/src/RadioList/RadioListItem.tsx

@@ -113,17 +113,42 @@ const rowStyles = stylex.create({
 export interface RadioListItemProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   /**
-   * Label text for the radio item.
+   * Primary label for the radio item.
+   *
+   * Accepts a plain string or a ReactNode for rich content. Links and buttons
+   * in the label keep their own behavior; only non-interactive row clicks
+   * delegate to the radio. The radio points at the rendered label for its
+   * accessible name, so a rich label still names it from its own text — pass
+   * `aria-label` when that text is absent or too noisy to announce.
    */
-  label: string;
+  label: ReactNode;
+  /**
+   * Plain-text accessible name for the radio, applied to the control rather
+   * than the row. It replaces the name the label would otherwise supply — a
+   * plain string label included — so reach for it when a rich label's own
+   * text is absent or reads badly, not as a routine addition.
+   *
+   * @example
+   * ```
+   * <RadioListItem
+   *   label={<span>Pro plan <Badge label="Recommended" /></span>}
+   *   aria-label="Pro plan"
+   *   value="pro"
+   * />
+   * ```
+   */
+  'aria-label'?: string;
   /**
    * Value of this radio item.
    */
   value: string;
   /**
-   * Description text displayed below the label.
+   * Secondary content displayed below the label. Accepts a plain string or a
+   * ReactNode. Links and buttons anywhere in the row keep their own click
+   * behaviour — the row only delegates clicks from its non-interactive
+   * surface to the radio.
    */
-  description?: string;
+  description?: ReactNode;
   /**
    * Whether this individual radio item is disabled.
    * @default false
@@ -155,6 +180,7 @@ export interface RadioListItemProps extends BaseProps<HTMLDivElement> {
 export function RadioListItem({
   ref,
   label,
+  'aria-label': ariaLabel,
   value,
   description,
   isDisabled: isItemDisabled = false,
@@ -172,6 +198,7 @@ export function RadioListItem({
   }
 
   const id = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const isDisabled = context.isDisabled || isItemDisabled;
   // When the whole group is disabled with a disabledMessage, radios stay
@@ -181,6 +208,10 @@ export function RadioListItem({
   const keepsFocusableForMessage =
     context.hasDisabledMessage && !isItemDisabled;
   const isChecked = context.value === value;
+  // One predicate for both the rendered element and the aria-describedby that
+  // points at it. A ReactNode description can be `false` or `''`, which render
+  // nothing — a `!= null` check would leave the link dangling.
+  const hasDescription = isRenderable(description);
   const size = context.size;
   // The radio visual is an indicator: a theme can restyle it through the
   // `radio` / `radio-dot` targets or replace the component outright.
@@ -211,7 +242,6 @@ export function RadioListItem({
         name={context.name}
         value={value}
         checked={isChecked}
-        aria-label={label}
         disabled={isDisabled && !keepsFocusableForMessage}
         aria-disabled={keepsFocusableForMessage ? 'true' : undefined}
         // A focusable-disabled radio is not natively disabled, so detach it
@@ -229,7 +259,13 @@ export function RadioListItem({
         // both direct control clicks and row-surface clicks the row delegates
         // to the input — the same routing CheckboxListItem uses.
         onClick={onClick}
-        aria-describedby={description ? descriptionID : undefined}
+        // The radio names itself from the visible label element, which works
+        // for a rich label as well as a plain string. `aria-label` replaces
+        // that name rather than adding to it, so the two are mutually
+        // exclusive — aria-labelledby would otherwise win over it.
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabel == null ? labelID : undefined}
+        aria-describedby={hasDescription ? descriptionID : undefined}
         {...stylex.props(
           styles.input,
           wrapperSizeStyles[size],
@@ -264,9 +300,9 @@ export function RadioListItem({
       // focusable control, so the row adds no second tab stop.
       interactiveRef={radioRef}
       isDisabled={isDisabled}
-      label={<span>{label}</span>}
+      label={<span id={labelID}>{label}</span>}
       description={
-        isRenderable(description) ? (
+        hasDescription ? (
           <span id={descriptionID}>{description}</span>
         ) : undefined
       }

package/src/Resizable/Resizable.doc.mjs

@@ -1,5 +1,27 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Handle',
+    required: true,
+    description:
+      'Focusable separator that owns pointer and keyboard resize interaction.',
+  },
+  {
+    name: 'Grip pill',
+    required: false,
+    description:
+      'Default visible grip indicator; custom handle content can replace it.',
+  },
+  {
+    name: 'Grab zone',
+    required: true,
+    description:
+      'Invisible enlarged pointer region aligned with the grip or divider.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docs = {
   name: 'Resizable',
@@ -19,11 +41,17 @@ export const docs = {
     'grip',
   ],
   usage: {
+    anatomy,
     description:
       'Hook-based resizable panel system. useResizable() manages size state ' +
       'and ResizeHandle provides the interactive pill-grip separator. ' +
       'Pass resize props to existing layout components via their resizable prop.',
     bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use percent(value, {min: pixel(value)}) or percent(value, {max: pixel(value)}) when a percentage needs exactly one pixel floor or ceiling. Reuse Table’s pixel() helper; numbers, exact Npx, and pixel(value) remain pixels. State, persistence, callbacks, paint, and ARIA remain resolved pixels.',
+      },
       {
         guidance: true,
         description:
@@ -57,24 +85,79 @@ export const docs = {
       description:
         'Hook that manages resize state for one or more panel regions. ' +
         'Returns size, isCollapsed, collapse/expand/resize methods, and props to pass to handles.',
+      examples: [
+        {
+          label: 'Structured fixed pixels',
+          code: `const region = useResizable({
+  defaultSize: pixel(333),
+  containerRef,
+});`,
+        },
+        {
+          label: 'One-time structured default',
+          code: `import {useRef} from 'react';
+import {ResizeHandle, useResizable} from '@astryxdesign/core/Resizable';
+import {percent, pixel} from '@astryxdesign/core/Resizable/utils';
+
+const containerRef = useRef<HTMLDivElement>(null);
+
+const region = useResizable({
+  defaultSize: percent(40, {min: pixel(333)}),
+  containerRef,
+});
+
+<ResizeHandle direction="horizontal" resizable={region.props} />;`,
+        },
+        {
+          label: 'Live percentage floor',
+          code: `const region = useResizable({
+  defaultSize: 0,
+  minSize: percent(40, {min: pixel(333)}),
+  containerRef,
+});`,
+        },
+        {
+          label: 'Live percentage ceiling',
+          code: `const region = useResizable({
+  defaultSize: 500,
+  maxSize: percent(10, {max: pixel(400)}),
+  containerRef,
+});`,
+        },
+      ],
       props: [
         {
           name: 'defaultSize',
-          type: 'number | string',
+          type: 'SizeValue | ResizableSize',
           description:
-            'Initial size in pixels or percentage string (e.g. "20%").',
+            'Initial size. Numbers, exact Npx, and pixel(value) are pixels; exact N% has no additional pixel bound; percent(value, {min: pixel(value)}) or percent(value, {max: pixel(value)}) adds exactly one and resolves once.',
           default: '250',
         },
+        {
+          name: 'minSize',
+          type: 'ResizableSize',
+          description:
+            'Live minimum. Numbers, exact Npx, and pixel(value) remain pixels; exact N% has no additional pixel bound; percent(value, {min: pixel(value)}) or percent(value, {max: pixel(value)}) adds exactly one.',
+          default: '50',
+        },
+        {
+          name: 'maxSize',
+          type: 'ResizableSize',
+          description:
+            'Live maximum. Numbers, exact Npx, and pixel(value) remain pixels; exact N% has no additional pixel bound; percent(value, {min: pixel(value)}) or percent(value, {max: pixel(value)}) adds exactly one.',
+          default: 'Infinity',
+        },
         {
           name: 'minSizePx',
           type: 'number',
-          description: 'Minimum size in pixels.',
+          description: 'Deprecated pixel-only alias for minSize.',
           default: '50',
         },
         {
           name: 'maxSizePx',
           type: 'number',
-          description: 'Maximum size in pixels.',
+          description:
+            'Deprecated pixel-only alias for maxSize. Explicit Infinity remains valid.',
           default: 'Infinity',
         },
         {
@@ -86,8 +169,7 @@ export const docs = {
         {
           name: 'collapsedSize',
           type: 'number',
-          description:
-            'Pixel threshold that triggers collapse during drag.',
+          description: 'Pixel threshold that triggers collapse during drag.',
           default: '40',
         },
         {
@@ -98,13 +180,13 @@ export const docs = {
         {
           name: 'shrinkOrder',
           type: 'number',
-          description:
-            'Cascade priority: lower number shrinks first.',
+          description: 'Cascade priority: lower number shrinks first.',
         },
         {
           name: 'autoSaveId',
           type: 'string',
-          description: 'Key for persisting sizes and collapse state to localStorage.',
+          description:
+            'Key for persisting sizes and collapse state to localStorage.',
         },
       ],
     },
@@ -168,7 +250,7 @@ export const docs = {
           name: 'resizable',
           type: 'ResizableProps',
           description:
-            'Resize props from useResizable: connects handle to panel.',
+            "Resize props from useResizable: connects handle to panel. Carries the region's axis ('horizontal' | 'vertical'), which must match this handle's direction.",
           required: true,
         },
         {
@@ -190,24 +272,42 @@ export const docs = {
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator.',
+  description:
+    'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator.',
   usage: {
+    anatomy,
     description:
       'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator. Pass resize props to existing layout components via their resizable prop.',
     bestPractices: [
-      {guidance: true, description: 'Use useResizable() w/ existing Astryx layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.'},
-      {guidance: true, description: 'Provide accessible label on each ResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").'},
-      {guidance: false, description: 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.'},
+      {
+        guidance: true,
+        description:
+          'Use useResizable() w/ existing Astryx layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide accessible label on each ResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.',
+      },
     ],
   },
   components: [
     {
       name: 'useResizable',
-      description: 'Hook managing resize state for one or more panel regions. Returns size, isCollapsed, collapse/expand/resize methods, + props to pass to handles.',
+      description:
+        'Hook managing resize state for one or more panel regions. Returns size, isCollapsed, collapse/expand/resize methods, + props to pass to handles.',
       propDescriptions: {
-        defaultSize: 'initial size in px or % string (e.g. "20%")',
-        minSizePx: 'minimum size in px',
-        maxSizePx: 'maximum size in px',
+        defaultSize:
+          'initial pixels, exact N%, or percent(value, {min: pixel(value)}) / percent(value, {max: pixel(value)}); resolves once',
+        minSize:
+          'live minimum: pixels, exact N%, or percent(value, {min: pixel(value)}) / percent(value, {max: pixel(value)})',
+        maxSize:
+          'live maximum: pixels, exact N%, or percent(value, {min: pixel(value)}) / percent(value, {max: pixel(value)})',
         collapsible: 'region can collapse to size 0?',
         collapsedSize: 'px threshold triggering collapse during drag',
         snaps: 'px values to snap to during resize',
@@ -217,14 +317,20 @@ export const docsDense = {
     },
     {
       name: 'ResizeHandle',
-      description: 'Draggable separator between panels. Pill-grip: invisible at rest, visible on hover (0.6 opacity), fully opaque during drag (1.0). Keyboard-accessible.',
+      description:
+        'Draggable separator between panels. Pill-grip: invisible at rest, visible on hover (0.6 opacity), fully opaque during drag (1.0). Keyboard-accessible.',
       propDescriptions: {
-        direction: 'layout direction: determines cursor + indicator orientation',
-        isReversed: 'reverse drag direction. Use when handle controls panel on end/right/bottom side',
+        direction:
+          'layout direction: determines cursor + indicator orientation',
+        isReversed:
+          'reverse drag direction. Use when handle controls panel on end/right/bottom side',
         isDisabled: 'handle interactive?',
-        hasDivider: 'show full-length 1px divider line through handle. Use when adjacent panels share same background',
-        isAlwaysVisible: 'show pill grip at rest instead of only on hover. Use when discoverability important',
-        pillPlacement: 'which side of divider pill sits on. auto = content side (derived from isReversed), flips when collapsed; start = left/top, end = right/bottom, center = centered on divider',
+        hasDivider:
+          'show full-length 1px divider line through handle. Use when adjacent panels share same background',
+        isAlwaysVisible:
+          'show pill grip at rest instead of only on hover. Use when discoverability important',
+        pillPlacement:
+          'which side of divider pill sits on. auto = content side (derived from isReversed), flips when collapsed; start = left/top, end = right/bottom, center = centered on divider',
         label: 'accessible label for separator',
         resizable: 'resize props from useResizable: connects handle to panel',
       },