@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/Chat/ChatPastedTextToken.tsx

@@ -25,6 +25,7 @@ import {
 import {Badge} from '../Badge';
 import {Button} from '../Button';
 import {HoverCard} from '../HoverCard';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -88,6 +89,7 @@ export function ChatPastedTextToken({
   text,
   onExpand,
 }: ChatPastedTextTokenProps) {
+  const t = useTranslator();
   const label = formatLabel(text);
 
   const cardContent = (
@@ -97,7 +99,7 @@ export function ChatPastedTextToken({
         <span {...stylex.props(styles.meta)}>{label}</span>
         {onExpand && (
           <Button
-            label="Expand"
+            label={t('@astryx.chat.pastedText.expand')}
             variant="ghost"
             size="sm"
             onClick={onExpand}

package/src/Chat/ChatSendButton.tsx

@@ -25,6 +25,7 @@ import {useChatComposerContext} from './ChatContext';
 
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -75,6 +76,7 @@ const styles = stylex.create({
  * ```
  */
 export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
+  const t = useTranslator();
   const context = useChatComposerContext();
 
   const {
@@ -94,7 +96,7 @@ export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
   return (
     <Button
       ref={ref}
-      label={isStopShown ? 'Stop' : 'Send'}
+      label={isStopShown ? t('@astryx.chatSendButton.stop') : t('@astryx.chatSendButton.send')}
       variant={isStopShown ? 'secondary' : 'primary'}
       size={size}
       icon={

package/src/Chat/ChatToolCalls.doc.mjs

@@ -38,7 +38,7 @@ export const docs = {
       name: 'calls',
       type: 'ChatToolCallItem[]',
       description:
-        'Array of tool call data. Each item has name, status, target, duration, node, additions, deletions, stats, errorMessage, resultDetail, key, and data.',
+        "Array of tool call data. Each item has name, status, target, duration, node, additions, deletions, stats, errorMessage, resultDetail, key, and data. status is one of 'pending', 'running', 'complete', or 'error' (defaults to 'complete').",
       required: true,
     },
     {

package/src/Chat/index.ts

@@ -59,6 +59,7 @@ export type {
 
 export {useChatStreamScroll} from './useChatStreamScroll';
 export type {
+  ChatScrollToBottomOptions,
   UseChatStreamScrollOptions,
   UseChatStreamScrollReturn,
 } from './useChatStreamScroll';

package/src/Chat/useChatStreamScroll.test.tsx

@@ -0,0 +1,168 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {act, render} from '@testing-library/react';
+import {useRef} from 'react';
+import {
+  useChatStreamScroll,
+  type UseChatStreamScrollOptions,
+  type UseChatStreamScrollReturn,
+} from './useChatStreamScroll';
+
+// ---------------------------------------------------------------------------
+// Test infrastructure
+//
+// jsdom has no layout engine, so these tests cover only the SYNCHRONOUS
+// scroll paths (instant positioning, lock state, rAF scheduling decisions).
+// The spring physics itself (frame-by-frame integration, scrollend re-lock,
+// user-scroll detection) is layout/browser-dependent and is verified
+// manually via Storybook — mocking it here would only test the mock.
+// ---------------------------------------------------------------------------
+
+let rafQueue: FrameRequestCallback[] = [];
+
+function flushRaf() {
+  // One flush = one frame: callbacks scheduled during a flush run next flush.
+  const frame = rafQueue;
+  rafQueue = [];
+  act(() => {
+    for (const cb of frame) {
+      cb(performance.now());
+    }
+  });
+}
+
+beforeEach(() => {
+  rafQueue = [];
+  vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+    rafQueue.push(cb);
+    return rafQueue.length;
+  });
+  vi.stubGlobal('cancelAnimationFrame', () => {});
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function setGeometry(
+  el: HTMLElement,
+  {scrollHeight, clientHeight}: {scrollHeight: number; clientHeight: number},
+) {
+  Object.defineProperty(el, 'scrollHeight', {
+    value: scrollHeight,
+    configurable: true,
+  });
+  Object.defineProperty(el, 'clientHeight', {
+    value: clientHeight,
+    configurable: true,
+  });
+  Object.defineProperty(el, 'offsetHeight', {
+    value: clientHeight,
+    configurable: true,
+  });
+}
+
+function Harness({
+  options,
+  api,
+}: {
+  options?: Partial<UseChatStreamScrollOptions>;
+  api: {current: UseChatStreamScrollReturn | null};
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  api.current = useChatStreamScroll({scrollRef, ...options});
+  return <div ref={scrollRef} data-testid="scroller" />;
+}
+
+function renderHook(options?: Partial<UseChatStreamScrollOptions>) {
+  const api: {current: UseChatStreamScrollReturn | null} = {current: null};
+  const utils = render(<Harness options={options} api={api} />);
+  const el = utils.getByTestId('scroller');
+  return {api, el, ...utils};
+}
+
+describe('useChatStreamScroll — initial positioning', () => {
+  it('default: jumps to the bottom on mount when content is scrollable', () => {
+    const {el} = renderHook();
+    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
+    flushRaf();
+    expect(el.scrollTop).toBe(600);
+  });
+
+  it('positions the first async fill in one synchronous step', () => {
+    const {api, el} = renderHook();
+    // Mount while loading — nothing scrollable yet.
+    setGeometry(el, {scrollHeight: 400, clientHeight: 400});
+    flushRaf();
+    expect(el.scrollTop).toBe(0);
+
+    // Async content lands; the layout's ResizeObserver calls scrollIfLocked.
+    setGeometry(el, {scrollHeight: 1200, clientHeight: 400});
+    act(() => api.current!.scrollIfLocked());
+    // Positioned synchronously — no animation frames needed.
+    expect(el.scrollTop).toBe(800);
+
+    // Subsequent growth (streaming) goes back to the spring: nothing moves
+    // until animation frames run.
+    setGeometry(el, {scrollHeight: 1600, clientHeight: 400});
+    act(() => api.current!.scrollIfLocked());
+    expect(el.scrollTop).toBe(800);
+  });
+
+  it('consumes the pending first fill via the mount jump too', () => {
+    const {api, el} = renderHook();
+    // Content already present at mount.
+    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
+    flushRaf();
+    expect(el.scrollTop).toBe(600);
+
+    // Growth after the mount jump is streaming — spring path, not instant.
+    setGeometry(el, {scrollHeight: 1400, clientHeight: 400});
+    act(() => api.current!.scrollIfLocked());
+    expect(el.scrollTop).toBe(600);
+  });
+
+  it('default: starts locked', () => {
+    const {api} = renderHook();
+    expect(api.current!.isLocked).toBe(true);
+  });
+});
+
+describe("useChatStreamScroll — scrollToBottom({behavior: 'instant'})", () => {
+  it('jumps synchronously without scheduling animation frames', () => {
+    const {api, el} = renderHook();
+    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
+    flushRaf(); // consume the mount jump
+    el.scrollTop = 100; // user scrolled up
+
+    rafQueue = [];
+    act(() => api.current!.scrollToBottom({behavior: 'instant'}));
+    expect(el.scrollTop).toBe(600);
+    expect(rafQueue).toHaveLength(0);
+  });
+
+  it('re-locks after an instant jump', () => {
+    const {api, el} = renderHook();
+    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
+    flushRaf();
+    act(() => api.current!.unlock());
+    expect(api.current!.isLocked).toBe(false);
+
+    act(() => api.current!.scrollToBottom({behavior: 'instant'}));
+    expect(api.current!.isLocked).toBe(true);
+    expect(el.scrollTop).toBe(600);
+  });
+
+  it('default scrollToBottom animates instead of jumping', () => {
+    const {api, el} = renderHook();
+    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
+    flushRaf();
+    el.scrollTop = 100;
+
+    act(() => api.current!.scrollToBottom());
+    // Spring path: position is untouched until animation frames run.
+    expect(el.scrollTop).toBe(100);
+    expect(rafQueue.length).toBeGreaterThan(0);
+  });
+});

package/src/Chat/useChatStreamScroll.ts

@@ -12,6 +12,9 @@
  * - Locked (default): content growth auto-scrolls to bottom via rAF spring
  * - Scrolling up (any source): unlocks immediately
  * - Scrolling settles at bottom: re-locks on scrollend
+ * - The first fill positions instantly (whether content is present at
+ *   mount or arrives async); only subsequent growth springs
+ * - `scrollToBottom({behavior: 'instant'})` jumps in one frame, no animation
  *
  * Uses scroll direction (lastScrollTop comparison) to detect user
  * intent — works for wheel, touch, scrollbar drag, keyboard, everything.
@@ -28,6 +31,18 @@ import {useCallback, useEffect, useRef, useState} from 'react';
 // Types
 // =============================================================================
 
+export interface ChatScrollToBottomOptions {
+  /**
+   * `'instant'` jumps to the bottom in a single frame instead of running
+   * the spring animation. Use for programmatic positioning (opening a
+   * conversation, restoring a session) — keep the default `'spring'` for
+   * user-initiated scrolls like the scroll-to-bottom button. Mirrors the
+   * DOM's `scrollTo({behavior})`.
+   * @default 'spring'
+   */
+  behavior?: 'instant' | 'spring';
+}
+
 export interface UseChatStreamScrollOptions {
   /**
    * Ref to the scrollable container element.
@@ -81,7 +96,7 @@ export interface UseChatStreamScrollReturn {
   isLocked: boolean;
 
   /** Scroll to the bottom of the container and re-lock. */
-  scrollToBottom: () => void;
+  scrollToBottom: (options?: ChatScrollToBottomOptions) => void;
 
   /** Scroll so a specific element is at the top of the visible area. No lock change. */
   scrollToMessage: (el: HTMLElement) => void;
@@ -118,6 +133,9 @@ export function useChatStreamScroll({
   const [isLocked, setIsLocked] = useState(true);
 
   const lockedRef = useRef(true);
+  // True until the initial fill has been positioned — consumed by the first
+  // scrollIfLocked that sees scrollable content.
+  const initialFillPendingRef = useRef(true);
   const velocityRef = useRef(0);
   const animatingRef = useRef(false);
   const lastTickRef = useRef<number | undefined>(undefined);
@@ -179,14 +197,36 @@ export function useChatStreamScroll({
     }
   }, [animate]);
 
+  // Jump to the bottom in a single frame — cancels any in-flight spring so
+  // a later animation tick can't fight the assignment.
+  const jumpToBottom = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) {
+      return;
+    }
+    animatingRef.current = false;
+    velocityRef.current = 0;
+    lastTickRef.current = undefined;
+    el.scrollTop = el.scrollHeight - el.clientHeight;
+    lastScrollTopRef.current = el.scrollTop;
+  }, [scrollRef]);
+
   // --- Public API ---
 
-  const scrollToBottom = useCallback(() => {
-    lockedRef.current = true;
-    setIsLocked(true);
-    setIsScrolledUp(false);
-    startAnimation();
-  }, [startAnimation]);
+  const scrollToBottom = useCallback(
+    (options?: ChatScrollToBottomOptions) => {
+      lockedRef.current = true;
+      setIsLocked(true);
+      setIsScrolledUp(false);
+      initialFillPendingRef.current = false;
+      if (options?.behavior === 'instant') {
+        jumpToBottom();
+        return;
+      }
+      startAnimation();
+    },
+    [startAnimation, jumpToBottom],
+  );
 
   const scrollToMessage = useCallback(
     (el: HTMLElement) => {
@@ -232,10 +272,25 @@ export function useChatStreamScroll({
     if (!enabled) {
       return;
     }
-    if (lockedRef.current) {
-      startAnimation();
+    if (!lockedRef.current) {
+      return;
+    }
+    // Initial fill: content appearing for the first time (e.g. an
+    // async-loaded conversation) positions in one frame instead of
+    // spring-flying from the top. Stays pending through empty/loading
+    // resizes until the container is actually scrollable.
+    const el = scrollRef.current;
+    if (
+      initialFillPendingRef.current &&
+      el &&
+      el.scrollHeight > el.clientHeight
+    ) {
+      initialFillPendingRef.current = false;
+      jumpToBottom();
+      return;
     }
-  }, [enabled, startAnimation]);
+    startAnimation();
+  }, [enabled, startAnimation, jumpToBottom, scrollRef]);
 
   // --- Event listeners ---
 
@@ -314,11 +369,12 @@ export function useChatStreamScroll({
     el.addEventListener('wheel', onWheel, {passive: true});
     el.addEventListener('touchmove', onTouchMove, {passive: true});
 
-    // Initial scroll to bottom
+    // Initial scroll to bottom — content already present at mount.
     requestAnimationFrame(() => {
       if (el.scrollHeight > el.clientHeight) {
         el.scrollTop = el.scrollHeight - el.clientHeight;
         lastScrollTopRef.current = el.scrollTop;
+        initialFillPendingRef.current = false;
       }
     });
 

package/src/Chat/useSpeechRecognition.ts

@@ -14,6 +14,7 @@
  */
 
 import {useState, useCallback, useEffect, useMemo, useRef} from 'react';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -258,6 +259,7 @@ export function getDefaultAudioContext(): AudioContext {
 export function useSpeechRecognition(
   options: UseSpeechRecognitionOptions = {},
 ): UseSpeechRecognitionReturn {
+  const t = useTranslator();
   const {
     lang,
     continuous = true,
@@ -408,13 +410,20 @@ export function useSpeechRecognition(
     recognition.onnomatch = () => {
       callbacksRef.current.onError?.({
         error: 'no-speech',
-        message: 'No speech was detected.',
+        message: t('@astryx.chat.speechRecognition.noSpeechDetected'),
       });
     };
 
     recognitionRef.current = recognition;
     recognition.start();
-  }, [lang, continuous, interimResults, startVolumePolling, stopVolumePolling]);
+  }, [
+    lang,
+    continuous,
+    interimResults,
+    startVolumePolling,
+    stopVolumePolling,
+    t,
+  ]);
 
   const stop = useCallback(() => {
     recognitionRef.current?.stop();

package/src/Chat/useTriggerMenu.tsx

@@ -40,6 +40,7 @@ import {
 import {mergeProps, groupItems} from '../utils';
 import type {SearchableItem} from '../Typeahead/types';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 import type {ChatComposerTrigger, ChatComposerToken} from './ChatComposerInput';
 
 // =============================================================================
@@ -254,6 +255,7 @@ function deleteTriggerText(
 export function useTriggerMenu(
   options: UseTriggerMenuOptions,
 ): UseTriggerMenuReturn {
+  const t = useTranslator();
   const {
     triggers,
     editableRef,
@@ -697,7 +699,7 @@ export function useTriggerMenu(
       <div
         id={listboxId}
         role="listbox"
-        aria-label={trigger?.menuLabel ?? 'Suggestions'}
+        aria-label={trigger?.menuLabel ?? t('@astryx.chatTriggerMenu.suggestions')}
         {...mergeProps(
           themeProps('trigger-menu'),
           stylex.props(styles.dropdown),
@@ -710,7 +712,7 @@ export function useTriggerMenu(
         xstyle: [styles.popoverSurface, styles.popoverGap],
       },
     );
-  }, [popover, listboxId, state, selectItem, getItemId]);
+  }, [popover, listboxId, state, selectItem, getItemId, t]);
 
   return {
     state,

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -113,7 +113,7 @@ export const docs = {
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon to display before the label text. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'status',

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -248,6 +248,22 @@ describe('CheckboxInput', () => {
     expect(screen.getByLabelText('Select row')).toBeInTheDocument();
   });
 
+  it('keeps description linked via aria-describedby when isLabelHidden', () => {
+    render(
+      <CheckboxInput
+        label="Select row"
+        isLabelHidden
+        description="Selects this row for bulk actions"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+    const checkbox = screen.getByRole('checkbox');
+    const description = screen.getByText('Selects this row for bulk actions');
+    expect(description.id).not.toBe('');
+    expect(checkbox.getAttribute('aria-describedby')).toContain(description.id);
+  });
+
   it('shows label visually by default', () => {
     render(
       <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,

package/src/CheckboxInput/CheckboxInput.tsx

@@ -446,9 +446,11 @@ export function CheckboxInput({
   );
 
   // Build aria-describedby from description and status message
-  // Only include descriptionID when the element actually renders
+  // Only include descriptionID when the element actually renders.
+  // FieldLabel renders the description (with descriptionID) even when the
+  // label is visually hidden — it's sr-only, so keep it linked.
   const describedByParts: string[] = [];
-  if (description && !isLabelHidden) {
+  if (description) {
     describedByParts.push(descriptionID);
   }
   if (status?.message) {

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -85,7 +85,7 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: 'Status indicator ({ type, message }).',
     },
     {
@@ -108,6 +108,11 @@ export const docs = {
       { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
+  theming: {
+    targets: [
+      {className: 'astryx-checkbox-list'},
+    ],
+  },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */

package/src/CheckboxList/CheckboxList.tsx

@@ -163,6 +163,7 @@ export function CheckboxList({
   className,
   style,
   'data-testid': dataTestId,
+  ...rest
 }: CheckboxListProps) {
   const inputID = useId();
   const labelID = useId();
@@ -234,6 +235,7 @@ export function CheckboxList({
 
   return (
     <Field
+      {...rest}
       ref={ref}
       data-testid={dataTestId}
       label={label}

package/src/CheckboxList/CheckboxListItem.tsx

@@ -26,6 +26,7 @@ import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
 import {ListItem} from '../List/ListItem';
 import {ListContext} from '../List/ListContext';
 import {CheckboxListContext} from './CheckboxListContext';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Styles
@@ -132,6 +133,7 @@ export function CheckboxListItem({
   onClick: onClickProp,
   ...restProps
 }: CheckboxListItemProps) {
+  const t = useTranslator();
   const ctx = use(CheckboxListContext);
 
   if (ctx && ctx.value !== undefined && value === undefined) {
@@ -224,7 +226,11 @@ export function CheckboxListItem({
       style={style}
       startContent={
         <CheckboxInput
-          label={typeof label === 'string' ? label : 'Checkbox'}
+          label={
+            typeof label === 'string'
+              ? label
+              : t('@astryx.checkboxList.item.checkbox')
+          }
           isLabelHidden
           value={resolvedChecked}
           onChange={() => handleToggle()}

package/src/Citation/Citation.tsx

@@ -28,6 +28,7 @@ import {
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 export interface CitationSource {
   title?: string;
@@ -154,6 +155,7 @@ export function Citation({
   'data-testid': testId,
   ...rest
 }: CitationProps): React.ReactElement {
+  const t = useTranslator();
   const title = source.title ?? String(number);
   const href = source.url;
   const icon = source.icon;
@@ -181,7 +183,7 @@ export function Citation({
         {...rest}
         ref={elementRef}
         role={noteRole}
-        aria-label={`Citation ${number}: ${title}`}
+        aria-label={t('@astryx.citation.label', {number, title})}
         data-testid={testId}
         {...linkProps}
         {...mergeProps(
@@ -204,7 +206,7 @@ export function Citation({
       {...rest}
       ref={elementRef}
       role={noteRole}
-      aria-label={`Citation ${number}: ${title}`}
+      aria-label={t('@astryx.citation.label', {number, title})}
       data-testid={testId}
       {...linkProps}
       {...mergeProps(

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -26,7 +26,7 @@ export const docs = {
     {name: 'target', type: 'string', description: 'Link target.', default: "'_self'"},
     {name: 'isDisabled', type: 'boolean', description: 'Disables the card.', default: 'false'},
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
-    {name: 'padding', type: "SpacingStep", description: 'Inner padding.', default: '4'},
+    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inner padding.', default: '4'},
     {name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: 'Background color variant.', default: "'default'"},
     {name: 'width', type: 'SizeValue', description: 'Card width.'},
     {name: 'height', type: 'SizeValue', description: 'Card height.'},