@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/RadioList/RadioList.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file RadioList.tsx
- * @input Uses React useId, createContext, ReactNode, Field, InputStatus
+ * @input Uses React useId, useCallback, useRef, createContext, ReactNode, Field, InputStatus
  * @output Exports RadioList component, RadioListProps, RadioListContext
  * @position Core implementation; consumed by index.ts, tested by RadioList.test.tsx
  *
@@ -16,11 +16,19 @@
  * - /packages/cli/templates/blocks/components/RadioList/ (showcase blocks)
  */
 
-import React, {createContext, useId, useMemo, type ReactNode} from 'react';
+import React, {
+  createContext,
+  useCallback,
+  useId,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {Field} from '../Field/Field';
 import type {InputStatus} from '../Field/types';
+import {useTooltip} from '../Tooltip';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -36,13 +44,21 @@ export interface RadioListContextValue {
   value: string;
   onChange: (value: string) => void;
   isDisabled: boolean;
+  /**
+   * True when the whole group is disabled *and* a `disabledMessage` is set. In
+   * that mode radios stay focusable via `aria-disabled` (instead of the native
+   * `disabled` attribute) so the disabled-reason tooltip is keyboard- and
+   * AT-discoverable; selection is still blocked in the item's onChange guard.
+   */
+  hasDisabledMessage: boolean;
   isRequired: boolean;
   size: RadioListSize;
   status?: InputStatus;
 }
 
-export const RadioListContext =
-  createContext<RadioListContextValue | null>(null);
+export const RadioListContext = createContext<RadioListContextValue | null>(
+  null,
+);
 RadioListContext.displayName = 'RadioListContext';
 
 const styles = stylex.create({
@@ -95,6 +111,17 @@ export interface RadioListProps extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Explains why the radio group is disabled. Applies to the whole-group
+   * disabled state (`isDisabled`), not individual items. When set together with
+   * `isDisabled`, the group shows a tooltip with this text on hover and keyboard
+   * focus, and its radios stay focusable (via `aria-disabled`) so the reason is
+   * discoverable by keyboard and assistive technology. Selection stays blocked.
+   *
+   * Use this instead of wrapping a disabled group in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   */
+  disabledMessage?: string;
   /**
    * Whether the radio group is required.
    * @default false
@@ -161,6 +188,7 @@ export function RadioList({
   onChange,
   orientation = 'vertical',
   isDisabled = false,
+  disabledMessage,
   isRequired = false,
   isOptional = false,
   size = 'md',
@@ -175,12 +203,129 @@ export function RadioList({
 }: RadioListProps) {
   const name = useId();
   const inputID = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
 
+  const groupRef = useRef<HTMLDivElement>(null);
+
+  // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
+  // controls swallow pointer events, so the tooltip listeners attach to the
+  // radiogroup container and the radios stay perceivable via aria-disabled
+  // instead of the disabled attribute. Selection is blocked in the item's
+  // onChange guard.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The radiogroup container is not naturally focusable; focusin bubbles up
+    // from the radios, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   const contextValue = useMemo<RadioListContextValue>(
-    () => ({name, value, onChange, isDisabled, isRequired, size, status}),
-    [name, value, onChange, isDisabled, isRequired, size, status],
+    () => ({
+      name,
+      value,
+      onChange,
+      isDisabled,
+      hasDisabledMessage: showsDisabledMessage,
+      isRequired,
+      size,
+      status,
+    }),
+    [
+      name,
+      value,
+      onChange,
+      isDisabled,
+      showsDisabledMessage,
+      isRequired,
+      size,
+      status,
+    ],
+  );
+
+  /**
+   * Make the tab stop deterministic when a radio group has no selected value.
+   *
+   * Native `<input type="radio">` groups (same `name`) implement roving
+   * tabindex for free: when a value is selected, that radio is the single tab
+   * stop and receives focus, so no correction is needed there. But the ARIA
+   * radio-group pattern (APG) also requires a deterministic tab stop when the
+   * group has *no* selection — and browsers disagree here. Chrome, when
+   * Shift+Tab moves focus backward into an unselected group, lands on the
+   * *last* radio; forward Tab lands on the *first*. To keep the entry point
+   * predictable we redirect focus:
+   *   - forward entry  → first enabled radio (APG default)
+   *   - backward entry → last enabled radio (matches Chrome's backward tab)
+   *
+   * The redirect only runs when focus arrives from *outside* the group's own
+   * radios (guarded via `relatedTarget` containment). Moving between radios
+   * inside the group — arrow keys, clicks, programmatic focus of a sibling —
+   * is never hijacked.
+   */
+  const handleFocus = useCallback(
+    (e: React.FocusEvent<HTMLDivElement>) => {
+      // Only correct the no-selection case; a selected value already provides
+      // a deterministic native tab stop.
+      if (value !== '') {
+        return;
+      }
+
+      const group = groupRef.current;
+      if (!group) {
+        return;
+      }
+
+      // Ignore focus moving *within* the group. `relatedTarget` is the element
+      // losing focus; if it was inside the group, this is intra-group movement
+      // (arrow keys, clicking a sibling) and must not be hijacked. Some browsers
+      // report a null `relatedTarget`; fall back to checking whether the group
+      // already contained the active element before this focus landed.
+      const relatedTarget = e.relatedTarget as Node | null;
+      if (relatedTarget) {
+        if (group.contains(relatedTarget)) {
+          return;
+        }
+      } else if (
+        document.activeElement &&
+        document.activeElement !== e.target &&
+        group.contains(document.activeElement)
+      ) {
+        return;
+      }
+
+      const radios = Array.from(
+        group.querySelectorAll<HTMLInputElement>(
+          'input[type="radio"]:not([disabled])',
+        ),
+      );
+      if (radios.length === 0) {
+        return;
+      }
+
+      const target = e.target as HTMLElement;
+      const targetIndex = radios.findIndex(radio => radio === target);
+      // Only correct when the focus target is one of our enabled radios (not a
+      // nested control such as end-content).
+      if (targetIndex === -1) {
+        return;
+      }
+
+      // Infer tab direction from which end the browser chose. On a backward
+      // (Shift+Tab) entry into an unselected group, browsers focus the *last*
+      // radio; keep it as the deterministic backward tab stop. Any other entry
+      // (forward Tab, or a browser that lands mid-group) is normalized to the
+      // *first* enabled radio, the APG default.
+      const isBackwardEntry = targetIndex === radios.length - 1;
+      const intended = isBackwardEntry ? radios[radios.length - 1] : radios[0];
+
+      if (target !== intended) {
+        intended.focus();
+      }
+    },
+    [value],
   );
 
   return (
@@ -191,6 +336,8 @@ export function RadioList({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputID}
+      labelID={labelID}
+      isGroupLabel
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
       isRequired={isRequired}
@@ -211,12 +358,21 @@ export function RadioList({
       className={className}
       style={style}>
       <div
+        ref={el => {
+          groupRef.current = el;
+          // Anchor + hover/focus listeners for the disabled-message tooltip.
+          // Handlers are gated internally by isEnabled, so attaching
+          // unconditionally is safe.
+          disabledMessageTooltip.ref(el);
+        }}
         role="radiogroup"
-        aria-label={label}
+        aria-labelledby={labelID}
+        onFocus={handleFocus}
         aria-describedby={
           [
             description ? descriptionID : null,
             status?.message ? statusMessageID : null,
+            showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
           ]
             .filter(Boolean)
             .join(' ') || undefined
@@ -230,10 +386,10 @@ export function RadioList({
             orientation === 'vertical' ? styles.vertical : styles.horizontal,
           ),
         )}>
-        <RadioListContext value={contextValue}>
-          {children}
-        </RadioListContext>
+        <RadioListContext value={contextValue}>{children}</RadioListContext>
       </div>
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/RadioList/RadioListItem.tsx

@@ -230,6 +230,12 @@ export function RadioListItem({
   const id = useId();
   const descriptionID = useId();
   const isDisabled = context.isDisabled || isItemDisabled;
+  // When the whole group is disabled with a disabledMessage, radios stay
+  // focusable via aria-disabled (instead of native `disabled`) so the group's
+  // reason tooltip is keyboard-discoverable. Per-item disabling is unaffected
+  // and always uses the native disabled attribute.
+  const keepsFocusableForMessage =
+    context.hasDisabledMessage && !isItemDisabled;
   const isChecked = context.value === value;
   const size = context.size;
 
@@ -246,9 +252,15 @@ export function RadioListItem({
         name={context.name}
         value={value}
         checked={isChecked}
-        disabled={isDisabled}
+        disabled={isDisabled && !keepsFocusableForMessage}
+        aria-disabled={keepsFocusableForMessage ? 'true' : undefined}
         required={context.isRequired}
-        onChange={() => context.onChange(value)}
+        onChange={() => {
+          if (isDisabled) {
+            return;
+          }
+          context.onChange(value);
+        }}
         aria-describedby={description ? descriptionID : undefined}
         {...stylex.props(
           styles.input,

package/src/Resizable/Resizable.doc.mjs

@@ -147,7 +147,7 @@ export const docs = {
           type: 'boolean',
           description:
             'Show the pill grip at rest instead of only on hover. Use when discoverability is important.',
-          default: 'false',
+          default: 'true',
         },
         {
           name: 'pillPlacement',

package/src/Section/Section.doc.mjs

@@ -53,6 +53,11 @@ export const docs = {
       description: 'Internal padding using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Use padding={0} for edge-to-edge content.',
       default: '4',
     },
+    {
+      name: 'paddingBlock',
+      type: 'SpacingStep',
+      description: 'Block (vertical) padding override. Overrides only the block-axis padding while preserving inline padding from `padding` or the container theme default. Accepts the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10).',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -130,6 +135,11 @@ export const docsZh = {
       description: '使用间距比例的内部内边距（0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10）。使用 padding={0} 实现全宽内容。',
       default: '4',
     },
+    {
+      name: 'paddingBlock',
+      type: 'SpacingStep',
+      description: '块（垂直）方向内边距覆盖。仅覆盖块轴内边距，同时保留来自 padding 或容器主题默认值的行内内边距。使用间距比例（0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10）。',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -182,6 +192,7 @@ export const docsDense = {
     children: 'Content rendered inside section.',
     dividers: 'Which sides of section have divider borders.',
     padding: 'Internal padding via spacing scale; 0 for edge-to-edge content.',
+    paddingBlock: 'Block-axis padding override; preserves inline padding from padding/theme.',
     xstyle: 'StyleX styles for layout customization; must be stylex.create() value.',
   },
 };

package/src/SegmentedControl/SegmentedControl.doc.mjs

@@ -65,6 +65,12 @@ export const docs = {
       description: 'Whether the entire control is disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the control is disabled. Applies to the whole-group disabled state (isDisabled), not per segment. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the control focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled SegmentedControl in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -97,6 +103,7 @@ export const docs = {
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
       {guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
       {guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -111,6 +118,7 @@ export const docsZh = {
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
       {guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
       {guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -125,6 +133,7 @@ export const docsDense = {
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
       {guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
       {guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
   propDescriptions: {