@astryxdesign/core 0.1.2 → 0.1.3

package/src/Carousel/Carousel.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
     anatomy: [
       {name: 'Scroll container', required: true, description: 'The horizontal overflow area that holds all items.'},
       {name: 'Items', required: true, description: 'The children rendered in a row. Each item is animated with a scroll-driven scale effect.'},
-      {name: 'Fade edges', required: true, description: 'Gradient fades on the left and right edges that indicate more content is available.'},
+      {name: 'Fade edges', required: false, description: 'Gradient fades on the left and right edges that indicate more content is available. Enabled by default, disable with hasEdgeFade={false}.'},
       {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear on hover. Enabled by default, disable with hasButtons={false}.'},
     ],
   },
@@ -29,7 +29,9 @@ export const docs = {
     {name: 'children', type: 'ReactNode', description: 'Carousel items rendered in a horizontal scroll container.', required: true},
     {name: 'gap', type: "0 | 0.5 | 1 | 1.5 | 2 | 3 | 4", description: 'Gap between items using the spacing token scale.', default: '1'},
     {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons on hover (desktop only).', default: 'true'},
+    {name: 'hasEdgeFade', type: 'boolean', description: 'Show a gradient edge-fade mask when content overflows, signalling that more items exist off-screen.', default: 'true'},
     {name: 'hasSnap', type: 'boolean', description: 'Enable scroll-snap so each child snaps to the start edge.', default: 'false'},
+    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inline padding inside the scroll container, with matching scroll-padding so snap points align to the content edge.'},
     {name: 'aria-label', type: 'string', description: 'Accessible label for the carousel region.', default: "\'Carousel\'"},
     {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
     {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.'},
@@ -71,7 +73,9 @@ export const docsZh = {
     children: '在水平滚动容器中渲染的轮播项目。',
     gap: '使用间距令牌比例的项目间距。',
     hasButtons: '悬停时显示上一个/下一个导航按钮（仅桌面端）。',
+    hasEdgeFade: '内容溢出时显示渐变边缘遮罩，提示屏幕外还有更多项目。',
     hasSnap: '启用滚动吸附，使每个子元素吸附到起始边缘。',
+    padding: '滚动容器内的内联内边距，并设置匹配的 scroll-padding，使吸附点与内容边缘对齐。',
     'aria-label': '轮播区域的无障碍标签。',
   },
 };
@@ -95,7 +99,9 @@ export const docsDense = {
     children: 'carousel items in horizontal scroll',
     gap: 'item spacing via spacing token scale',
     hasButtons: 'prev/next buttons on hover (desktop)',
+    hasEdgeFade: 'gradient edge-fade mask on overflow',
     hasSnap: 'scroll-snap; children snap to start edge',
+    padding: 'inline padding; scroll-padding keeps snap points on content edge',
     'aria-label': 'accessible label for carousel region',
     'data-testid': 'test selector for automated testing frameworks',
   },

package/src/Carousel/Carousel.test.tsx

@@ -78,4 +78,24 @@ describe('Carousel', () => {
     expect(screen.getByLabelText('Scroll left')).toBeInTheDocument();
     expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();
   });
+
+  it('disables edge scroll buttons instead of removing them from the tab order', () => {
+    // In jsdom there is no measurable overflow, so both edges are at rest and
+    // the scroll buttons are in their hidden/inert state. They must stay
+    // mounted but be disabled — a disabled <button> is skipped by the tab
+    // order and hidden from the a11y tree, so keyboard users don't focus an
+    // invisible control (WCAG 2.4.7).
+    render(
+      <Carousel aria-label="Edge state">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Carousel>,
+    );
+    const left = screen.getByLabelText('Scroll left');
+    const right = screen.getByLabelText('Scroll right');
+    expect(left).toBeInTheDocument();
+    expect(right).toBeInTheDocument();
+    expect(left).toBeDisabled();
+    expect(right).toBeDisabled();
+  });
 });

package/src/Carousel/Carousel.tsx

@@ -295,9 +295,16 @@ export function Carousel({
     const firstChild = el.firstElementChild as HTMLElement | null;
     const itemWidth = firstChild ? firstChild.offsetWidth : 0;
     const amount = el.clientWidth - itemWidth * 0.5;
+    // Respect the user's reduced-motion preference — mirrors the CSS
+    // scroll-behavior override so button-driven scrolling doesn't animate
+    // for users who opted out of motion.
+    const prefersReducedMotion =
+      typeof window !== 'undefined' &&
+      typeof window.matchMedia === 'function' &&
+      window.matchMedia('(prefers-reduced-motion: reduce)').matches;
     el.scrollBy({
       left: direction * Math.max(amount, itemWidth),
-      behavior: 'smooth',
+      behavior: prefersReducedMotion ? 'auto' : 'smooth',
     });
   }, []);
 
@@ -360,6 +367,11 @@ export function Carousel({
                 variant="ghost"
                 size="sm"
                 isIconOnly
+                // Disabled when there's nothing to scroll toward. Keeps the
+                // button mounted (stable layout/focus) but removes it from the
+                // tab order and a11y tree while it's visually hidden, so
+                // keyboard users don't land on an invisible control.
+                isDisabled={!overflowStart}
                 onClick={() => scrollBy(-1)}
                 xstyle={styles.buttonRadiusOverride}
               />
@@ -376,6 +388,9 @@ export function Carousel({
                 variant="ghost"
                 size="sm"
                 isIconOnly
+                // See "Scroll left" — disabled while visually hidden so the
+                // button stays mounted but out of the tab order / a11y tree.
+                isDisabled={!overflowEnd}
                 onClick={() => scrollBy(1)}
                 xstyle={styles.buttonRadiusOverride}
               />

package/src/Center/Center.doc.mjs

@@ -18,14 +18,24 @@ export const docs = {
     },
     {
       name: 'width',
-      type: 'number | string',
+      type: 'SizeValue',
       description: 'Container width (px or CSS value).',
     },
     {
       name: 'height',
-      type: 'number | string',
+      type: 'SizeValue',
       description: 'Container height (px or CSS value).',
     },
+    {
+      name: 'maxWidth',
+      type: 'SizeValue',
+      description: 'Maximum container width (px or CSS value).',
+    },
+    {
+      name: 'minHeight',
+      type: 'SizeValue',
+      description: 'Minimum container height (px or CSS value).',
+    },
     {
       name: 'isInline',
       type: 'boolean',

package/src/Center/Center.tsx

@@ -39,15 +39,21 @@ const styles = stylex.create({
 
 // Dynamic styles for sizing props
 const dynamicStyles = stylex.create({
-  sizing: (width: SizeValue | null, height: SizeValue | null) => ({
+  sizing: (
+    width: SizeValue | null,
+    height: SizeValue | null,
+    maxWidth: SizeValue | null,
+    minHeight: SizeValue | null,
+  ) => ({
     width,
     height,
+    maxWidth,
+    minHeight,
   }),
 });
 
 export type CenterAxis = 'both' | 'horizontal' | 'vertical';
 
-
 export interface CenterProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDivElement>;
@@ -72,6 +78,18 @@ export interface CenterProps extends BaseProps<HTMLDivElement> {
    */
   height?: SizeValue;
 
+  /**
+   * Maximum width of the container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  maxWidth?: SizeValue;
+
+  /**
+   * Minimum height of the container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  minHeight?: SizeValue;
+
   /**
    * Whether to make the container inline-flex (useful for text/icons).
    * @default false
@@ -101,6 +119,8 @@ export function Center({
   axis = 'both',
   width,
   height,
+  maxWidth,
+  minHeight,
   isInline = false,
   children,
   xstyle,
@@ -115,7 +135,12 @@ export function Center({
       isInline ? styles.inline : styles.base,
       (axis === 'both' || axis === 'vertical') && styles.alignItemsCenter,
       (axis === 'both' || axis === 'horizontal') && styles.justifyContentCenter,
-      dynamicStyles.sizing(width ?? null, height ?? null),
+      dynamicStyles.sizing(
+        width ?? null,
+        height ?? null,
+        maxWidth ?? null,
+        minHeight ?? null,
+      ),
       xstyle,
     ),
     className,

package/src/Chat/ChatComposerInput.test.tsx

@@ -409,18 +409,36 @@ describe('ChatComposerInput', () => {
   });
 
   describe('accessibility', () => {
-    it('has aria-haspopup on the textbox', () => {
+    it('exposes role=combobox when triggers are configured', () => {
       const triggers = [createMentionTrigger()];
       render(<ChatComposerInput triggers={triggers} />);
-      const textbox = screen.getByRole('textbox');
-      expect(textbox).toHaveAttribute('aria-haspopup', 'listbox');
+      // aria-expanded/haspopup/controls/activedescendant are only valid on
+      // role="combobox", so the editable element must be a combobox (not a
+      // plain textbox) whenever trigger-menu behavior is wired.
+      expect(screen.getByRole('combobox')).toBeInTheDocument();
+      expect(screen.queryByRole('textbox')).not.toBeInTheDocument();
+    });
+
+    it('has aria-haspopup on the combobox', () => {
+      const triggers = [createMentionTrigger()];
+      render(<ChatComposerInput triggers={triggers} />);
+      const combobox = screen.getByRole('combobox');
+      expect(combobox).toHaveAttribute('aria-haspopup', 'listbox');
     });
 
     it('has aria-expanded=false when menu is closed', () => {
       const triggers = [createMentionTrigger()];
       render(<ChatComposerInput triggers={triggers} />);
-      const textbox = screen.getByRole('textbox');
-      expect(textbox).toHaveAttribute('aria-expanded', 'false');
+      const combobox = screen.getByRole('combobox');
+      expect(combobox).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('stays role=textbox with no combobox attributes when no triggers are configured', () => {
+      render(<ChatComposerInput label="Message" />);
+      const textbox = screen.getByRole('textbox', {name: 'Message'});
+      // A plain textbox must not carry combobox-only ARIA (axe: aria-allowed-attr).
+      expect(textbox).not.toHaveAttribute('aria-expanded');
+      expect(textbox).not.toHaveAttribute('aria-haspopup');
     });
   });
 
@@ -590,7 +608,8 @@ describe('ChatComposerInput', () => {
       const result = render(
         <ChatComposerInput triggers={triggers} onChange={onChange} />,
       );
-      const textbox = screen.getByRole('textbox');
+      // With triggers configured the editable is a combobox, not a textbox.
+      const textbox = screen.getByRole('combobox');
       textbox.focus();
       return {...result, textbox, onChange};
     }
@@ -684,7 +703,7 @@ describe('ChatComposerInput', () => {
           onChange={onChange}
         />,
       );
-      const textbox = screen.getByRole('textbox');
+      const textbox = screen.getByRole('combobox');
       textbox.focus();
 
       setCursorAfterText(textbox, 'hello @');

package/src/Chat/ChatComposerInput.tsx

@@ -632,7 +632,6 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
       )}
       <div
         ref={editableRef}
-        role="textbox"
         aria-multiline="true"
         aria-label={label}
         contentEditable={!isDisabled}

package/src/Chat/ChatDictationButton.doc.mjs

@@ -34,7 +34,7 @@ export const docs = {
       name: 'dictation',
       type: 'UseSpeechRecognitionReturn',
       description:
-        'The return value from useChatDictation or useSpeechRecognition. Controls all button state \u2014 listening, volume, bands, and toggle.',
+        'The return value from useChatDictation or useSpeechRecognition. Controls all button state: listening, volume, bands, and toggle.',
       required: true,
     },
     {

package/src/Chat/ChatMessageList.doc.mjs

@@ -45,6 +45,12 @@ export const docs = {
       type: 'SpacingStep',
       description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.',
     },
+    {
+      name: 'isStreaming',
+      type: 'boolean',
+      description: 'Whether an assistant message is actively streaming. Marks the log aria-busy so screen readers wait and announce the completed message once instead of re-announcing partial text on every token.',
+      default: 'false',
+    },
   ],
 };
 
@@ -59,6 +65,7 @@ export const docsZh = {
     scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
     density: '视觉密度，通过上下文传递给子消息。',
     gap: '顶层消息行之间的间距。默认跟随密度；当 LLM 事件流等独立行需要不同间距时可覆盖。',
+    isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy，让屏幕阅读器等待并在完成后一次性播报，而不是每个 token 都重复播报。',
   },
 };
 
@@ -73,5 +80,6 @@ export const docsDense = {
     scrollToTopAction: 'async action at scroll top; load older msgs',
     density: 'visual density; flows to children via context',
     gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
+    isStreaming: 'assistant streaming? marks log aria-busy so SR announces the completed msg once',
   },
 };

package/src/Chat/ChatMessageList.test.tsx

@@ -28,6 +28,24 @@ describe('ChatMessageList', () => {
     expect(el.getAttribute('role')).toBe('log');
   });
 
+  it('is not aria-busy by default', () => {
+    render(
+      <ChatMessageList data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(screen.getByTestId('list')).not.toHaveAttribute('aria-busy');
+  });
+
+  it('marks the log aria-busy while streaming', () => {
+    render(
+      <ChatMessageList data-testid="list" isStreaming>
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(screen.getByTestId('list')).toHaveAttribute('aria-busy', 'true');
+  });
+
   it('renders empty state when no children', () => {
     render(
       <ChatMessageList emptyState={<div>No messages yet</div>}>

package/src/Chat/ChatMessageList.tsx

@@ -72,6 +72,20 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {
    * be grouped) and row spacing should be tuned separately from density.
    */
   gap?: SpacingStep;
+
+  /**
+   * Whether an assistant message is actively streaming into the list.
+   *
+   * The list is a `role="log"` / `aria-live="polite"` region, so while a
+   * message streams in token-by-token, screen readers would otherwise
+   * re-announce the accumulating partial text on every mutation. Set
+   * `isStreaming` to `true` for the duration of a stream: it marks the log
+   * `aria-busy="true"` so assistive tech waits and announces the completed
+   * message once, when `isStreaming` returns to `false`.
+   *
+   * @default false
+   */
+  isStreaming?: boolean;
 }
 
 // =============================================================================
@@ -190,6 +204,7 @@ export function ChatMessageList({
   scrollToTopAction,
   density = 'balanced',
   gap,
+  isStreaming = false,
   xstyle,
   className,
   style,
@@ -252,6 +267,7 @@ export function ChatMessageList({
         ref={ref}
         role="log"
         aria-live="polite"
+        aria-busy={isStreaming || undefined}
         tabIndex={0}
         data-testid={testId}
         {...mergeProps(

package/src/Chat/useTriggerMenu.tsx

@@ -81,8 +81,15 @@ export interface UseTriggerMenuReturn {
   renderMenu: () => ReactNode;
   /** Reset/close the trigger menu */
   reset: () => void;
-  /** ARIA props to spread onto the textbox element */
+  /**
+   * ARIA props to spread onto the editable element. When triggers are
+   * configured the element becomes a `combobox` (which is the only role that
+   * permits `aria-expanded`/`aria-haspopup`/`aria-controls`/
+   * `aria-activedescendant`); otherwise it stays a plain `textbox` and no
+   * combobox attributes are emitted.
+   */
   ariaProps: {
+    role: 'combobox' | 'textbox';
     'aria-expanded'?: boolean;
     'aria-controls'?: string;
     'aria-activedescendant'?: string;
@@ -296,6 +303,9 @@ export function useTriggerMenu(
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
+    // The popup's own role="listbox" is the exposed semantics; focus stays in
+    // the contenteditable composer, so a modal dialog wrapper is incorrect.
+    role: 'none',
   });
 
   // Cleanup on unmount
@@ -598,10 +608,17 @@ export function useTriggerMenu(
     el?.scrollIntoView({block: 'nearest'});
   }, [state.highlightedIndex, popover.isOpen, getItemId]);
 
-  // ARIA props for the textbox element
-  const ariaProps =
-    state.isActive && popover.isOpen
+  // ARIA props for the editable element. Combobox attributes
+  // (aria-expanded/haspopup/controls/activedescendant) are only valid on
+  // role="combobox", so we only switch to that role — and only emit those
+  // attributes — when triggers are actually configured. With no triggers the
+  // element stays a plain role="textbox".
+  const hasTriggers = (triggers?.length ?? 0) > 0;
+  const ariaProps: UseTriggerMenuReturn['ariaProps'] = !hasTriggers
+    ? {role: 'textbox'}
+    : state.isActive && popover.isOpen
       ? {
+          role: 'combobox',
           'aria-expanded': true as const,
           'aria-controls': listboxId,
           'aria-activedescendant':
@@ -611,6 +628,7 @@ export function useTriggerMenu(
           'aria-haspopup': 'listbox' as const,
         }
       : {
+          role: 'combobox',
           'aria-expanded': false as const,
           'aria-haspopup': 'listbox' as const,
         };

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -63,6 +63,12 @@ export const docs = {
       description: 'Whether the checkbox is disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isReadOnly',
       type: 'boolean',
@@ -124,6 +130,7 @@ export const docs = {
       { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
       { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
       { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+      { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
     anatomy: [
       { name: 'Checkbox', required: true, description: 'The check box itself: unchecked, checked, or indeterminate.' },
@@ -146,6 +153,7 @@ export const docsZh = {
       { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
       { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
       { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+      { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
   props: [
@@ -163,6 +171,7 @@ export const docsZh = {
     },
     {name: 'isLoading', type: 'boolean', description: '复选框是否处于加载状态。显示旋转器并阻止交互。', default: 'false'},
     {name: 'isDisabled', type: 'boolean', description: '复选框是否禁用。', default: 'false'},
+    {name: 'disabledMessage', type: 'string', description: 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.'},
     {name: 'isReadOnly', type: 'boolean', description: '复选框是否为只读。以完整不透明度显示当前状态但阻止交互。与 isDisabled 不同，只读复选框不会变暗。', default: 'false'},
     {name: 'isOptional', type: 'boolean', description: '字段是否可选。与 isRequired 互斥。', default: 'false'},
     {name: 'isRequired', type: 'boolean', description: '复选框是否必填。与 isOptional 互斥。', default: 'false'},
@@ -200,6 +209,7 @@ export const docsDense = {
       { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
       { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
       { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+      { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
   propDescriptions: {