@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/src/Chat/ChatComposerInput.test.tsx

@@ -155,6 +155,93 @@ describe('ChatComposerInput', () => {
     });
   });
 
+  describe('Enter submit behavior', () => {
+    it('does not submit on Enter while IME composition is in progress', () => {
+      const onSubmit = vi.fn();
+      render(<ChatComposerInput onSubmit={onSubmit} />);
+      const textbox = screen.getByRole('textbox');
+      textbox.textContent = 'こんにちは';
+      fireEvent.input(textbox);
+      // isComposing is surfaced on the native event during IME composition.
+      fireEvent.keyDown(textbox, {key: 'Enter', isComposing: true});
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+
+    it('does not submit on Enter for the legacy keyCode 229 composing signal', () => {
+      const onSubmit = vi.fn();
+      render(<ChatComposerInput onSubmit={onSubmit} />);
+      const textbox = screen.getByRole('textbox');
+      textbox.textContent = 'ㅎ';
+      fireEvent.input(textbox);
+      fireEvent.keyDown(textbox, {key: 'Enter', keyCode: 229});
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+
+    it('lets onKeyDown suppress the default submit via preventDefault (touch-newline recipe)', () => {
+      // The documented "insert a newline instead of sending" pattern: a
+      // consumer preventDefaults Enter (e.g. on a coarse pointer).
+      const onSubmit = vi.fn();
+      const onKeyDown = vi.fn(e => {
+        if (e.key === 'Enter' && !e.shiftKey) {
+          e.preventDefault();
+        }
+      });
+      render(<ChatComposerInput onSubmit={onSubmit} onKeyDown={onKeyDown} />);
+      const textbox = screen.getByRole('textbox');
+      textbox.textContent = 'hello';
+      fireEvent.input(textbox);
+      fireEvent.keyDown(textbox, {key: 'Enter'});
+      expect(onKeyDown).toHaveBeenCalled();
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+
+    it('lets onKeyDown add behavior (Cmd/Ctrl+Enter submit) without preventDefault', () => {
+      // Adding a submit shortcut is just handling the event yourself; the
+      // built-in Enter handling still runs for the plain-Enter case.
+      const onSubmit = vi.fn();
+      const handle = vi.fn();
+      const onKeyDown = vi.fn(e => {
+        if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+          handle();
+        }
+      });
+      render(<ChatComposerInput onSubmit={onSubmit} onKeyDown={onKeyDown} />);
+      const textbox = screen.getByRole('textbox');
+      textbox.textContent = 'hello';
+      fireEvent.input(textbox);
+      fireEvent.keyDown(textbox, {key: 'Enter', metaKey: true});
+      expect(handle).toHaveBeenCalled();
+      // Consumer did not preventDefault, so the built-in submit also fires.
+      expect(onSubmit).toHaveBeenCalledWith('hello');
+    });
+
+    it('calls onKeyDown before submit and lets preventDefault take over', () => {
+      const onSubmit = vi.fn();
+      const onKeyDown = vi.fn(e => {
+        e.preventDefault();
+      });
+      render(<ChatComposerInput onSubmit={onSubmit} onKeyDown={onKeyDown} />);
+      const textbox = screen.getByRole('textbox');
+      textbox.textContent = 'hello';
+      fireEvent.input(textbox);
+      fireEvent.keyDown(textbox, {key: 'Enter'});
+      expect(onKeyDown).toHaveBeenCalled();
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+
+    it('calls onKeyDown but still submits when the consumer does not preventDefault', () => {
+      const onSubmit = vi.fn();
+      const onKeyDown = vi.fn();
+      render(<ChatComposerInput onSubmit={onSubmit} onKeyDown={onKeyDown} />);
+      const textbox = screen.getByRole('textbox');
+      textbox.textContent = 'hello';
+      fireEvent.input(textbox);
+      fireEvent.keyDown(textbox, {key: 'Enter'});
+      expect(onKeyDown).toHaveBeenCalled();
+      expect(onSubmit).toHaveBeenCalledWith('hello');
+    });
+  });
+
   // Controlled-value sync used to overwrite `textContent` on every
   // distinct render, which (a) collapsed the caret to offset 0
   // (visible after a slash-command pick like

package/src/Chat/ChatComposerInput.tsx

@@ -11,8 +11,10 @@
  *
  * ContentEditable-based rich input for the chat composer.
  * Supports trigger menus (@ mentions, / commands) via SearchSource,
- * inline token rendering, serialization, Enter/Shift+Enter, message
- * history, paste/drop file handling, and mobile-safe touch typography.
+ * inline token rendering, serialization, Enter-to-submit with
+ * IME-composition guarding and an onKeyDown seam for platform-specific
+ * key handling, message history, paste/drop file handling, and
+ * mobile-safe touch typography.
  *
  *
  * SYNC: When modified, update:
@@ -188,6 +190,21 @@ export interface ChatComposerInputProps extends Omit<
   onFiles?: (files: File[]) => void;
   /** Submit handler (Enter without Shift) */
   onSubmit?: (value: string) => void;
+  /**
+   * Key-down handler invoked before the built-in Enter/history behavior
+   * (but after an open trigger menu consumes the event).
+   *
+   * This is the seam for platform- or app-specific key handling:
+   * - Call `event.preventDefault()` to suppress the default submit (e.g.
+   *   let Enter insert a newline on a touch keyboard).
+   * - Add behavior by acting on the event yourself (e.g. submit on
+   *   Cmd/Ctrl+Enter) without calling `preventDefault()`, so the default
+   *   handling still runs for other keys.
+   *
+   * IME composition is always respected regardless of this handler: Enter
+   * never submits while a composition is in progress.
+   */
+  onKeyDown?: (event: KeyboardEvent<HTMLDivElement>) => void;
 }
 
 // =============================================================================
@@ -299,6 +316,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
     pasteAsToken: pasteAsTokenProp,
     onFiles,
     onSubmit = composerCtx?.onSubmit,
+    onKeyDown: onKeyDownProp,
     xstyle,
     className,
     style,
@@ -477,6 +495,13 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
         return;
       }
 
+      // Consumer passthrough — runs before built-in Enter/history handling.
+      // A consumer can preventDefault() to fully own the keystroke.
+      onKeyDownProp?.(e);
+      if (e.defaultPrevented) {
+        return;
+      }
+
       // Handle Backspace near tokens — prevent browser from creating
       // stray <br> elements or moving the cursor unexpectedly.
       if (e.key === 'Backspace') {
@@ -519,6 +544,13 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
       }
 
       if (e.key === 'Enter' && !e.shiftKey) {
+        // Never submit mid-composition — an IME uses Enter to commit a
+        // candidate (e.g. Japanese/Chinese/Korean input), and browsers may
+        // also surface the legacy keyCode 229 for composing keystrokes.
+        if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) {
+          return;
+        }
+
         e.preventDefault();
         if (!editableRef.current) {
           return;
@@ -583,7 +615,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
         }
       }
     },
-    [hasHistory, onSubmit, onChange, emitChange, triggerMenu],
+    [hasHistory, onSubmit, onChange, emitChange, triggerMenu, onKeyDownProp],
   );
 
   const handlePaste = useCallback(

package/src/Chat/ChatLayout.tsx

@@ -276,7 +276,9 @@ export function ChatLayout({
   const defaultScrollButton = (
     <ChatLayoutScrollButton
       isVisible={scroll.isScrolledUp || newMsgs.hasNewMessages}
-      label={newMsgs.hasNewMessages ? t('@astryx.chatLayout.newMessages') : undefined}
+      label={
+        newMsgs.hasNewMessages ? t('@astryx.chatLayout.newMessages') : undefined
+      }
       onClick={() => {
         newMsgs.dismiss();
         scroll.scrollToBottom();

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -135,7 +135,9 @@ export function ChatLayoutScrollButton({
         )}>
         <Button
           label={label ?? t('@astryx.chatLayoutScrollButton.scrollToBottom')}
-          aria-label={label ?? t('@astryx.chatLayoutScrollButton.scrollToBottom')}
+          aria-label={
+            label ?? t('@astryx.chatLayoutScrollButton.scrollToBottom')
+          }
           icon={<Icon icon="chevronDown" size="md" />}
           variant="ghost"
           size="md"

package/src/Chat/ChatMessage.tsx

@@ -150,7 +150,7 @@ const styles = stylex.create({
  *
  * @example
  * ```
- * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="small" />}>
+ * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="md" />}>
  *   <ChatMessageBubble>Hello!</ChatMessageBubble>
  *   <ChatMessageMetadata timestamp="2:30 PM" />
  * </ChatMessage>
@@ -222,7 +222,9 @@ export function ChatMessage({
         {...rest}
         ref={ref}
         data-testid={testId}
-        aria-label={!hasName ? t('@astryx.chatMessage.messageFrom', {sender}) : undefined}
+        aria-label={
+          !hasName ? t('@astryx.chatMessage.messageFrom', {sender}) : undefined
+        }
         aria-labelledby={hasName ? nameId : undefined}
         {...mergeProps(
           themeProps('chat-message', {sender, density}),

package/src/Chat/ChatMessageMetadata.tsx

@@ -122,8 +122,7 @@ export function ChatMessageMetadata({
   const sender = msgContext?.sender ?? 'assistant';
 
   const statusConfig = status != null ? STATUS_CONFIG[status] : null;
-  const statusLabel =
-    statusConfig != null ? t(statusConfig.i18nKey) : '';
+  const statusLabel = statusConfig != null ? t(statusConfig.i18nKey) : '';
 
   const hasContent =
     timestamp != null || footer != null || statusConfig != null;

package/src/Chat/ChatSendButton.tsx

@@ -96,7 +96,11 @@ export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
   return (
     <Button
       ref={ref}
-      label={isStopShown ? t('@astryx.chatSendButton.stop') : t('@astryx.chatSendButton.send')}
+      label={
+        isStopShown
+          ? t('@astryx.chatSendButton.stop')
+          : t('@astryx.chatSendButton.send')
+      }
       variant={isStopShown ? 'secondary' : 'primary'}
       size={size}
       icon={

package/src/Chat/ChatToolCalls.test.tsx

@@ -133,6 +133,70 @@ describe('ChatToolCalls', () => {
     expect(panel).toHaveTextContent('file contents here');
   });
 
+  it('exposes the error message as text without requiring hover', () => {
+    render(
+      <ChatToolCalls
+        calls={[
+          {
+            name: 'bash',
+            status: 'error',
+            errorMessage: 'Command exited with code 1',
+          },
+        ]}
+      />,
+    );
+    // The message must exist as real (screen-reader-visible) text content,
+    // not only inside a hover-only title attribute.
+    expect(screen.getByText(/Command exited with code 1/)).toBeInTheDocument();
+  });
+
+  it('includes the error message in the accessible name of an expandable error row', () => {
+    render(
+      <ChatToolCalls
+        calls={[
+          {
+            name: 'bash',
+            status: 'error',
+            errorMessage: 'Command exited with code 1',
+            resultDetail: <div>stderr output</div>,
+          },
+        ]}
+      />,
+    );
+    expect(
+      screen.getByRole('button', {name: /Command exited with code 1/}),
+    ).toBeInTheDocument();
+  });
+
+  it('keeps the hover tooltip on the error status icon', () => {
+    const {container} = render(
+      <ChatToolCalls
+        calls={[
+          {
+            name: 'bash',
+            status: 'error',
+            errorMessage: 'Command exited with code 1',
+          },
+        ]}
+      />,
+    );
+    expect(
+      container.querySelector('[title="Command exited with code 1"]'),
+    ).not.toBeNull();
+  });
+
+  it('renders no error text for non-error calls', () => {
+    render(
+      <ChatToolCalls
+        calls={[
+          {name: 'bash', status: 'complete', errorMessage: 'stale message'},
+        ]}
+      />,
+    );
+    expect(screen.queryByText(/stale message/)).not.toBeInTheDocument();
+    expect(screen.queryByText(/Error:/)).not.toBeInTheDocument();
+  });
+
   it('points the group header aria-controls at the content region', () => {
     render(
       <ChatToolCalls

package/src/Chat/ChatToolCalls.tsx

@@ -35,6 +35,7 @@ import {getKey, mergeProps} from '../utils';
 import {Badge} from '../Badge';
 import {Icon, type IconName} from '../Icon';
 import {Spinner} from '../Spinner';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -60,7 +61,11 @@ export interface ChatToolCallItem {
   deletions?: number;
   /** Additional info rendered after the label. Free-form ReactNode. */
   stats?: ReactNode;
-  /** Error message when status is 'error'. Shown in a tooltip on the status icon. */
+  /**
+   * Error message when status is 'error'. Rendered as visually hidden text in
+   * the row (so screen readers and keyboard users perceive it) and echoed in a
+   * hover tooltip on the status icon.
+   */
   errorMessage?: string;
   /** Unique key for React list rendering. Derived from stable metadata if omitted. */
   key?: string;
@@ -395,6 +400,13 @@ function CallRow({call}: {call: ChatToolCallItem}) {
             </span>
           </>
         )}
+        {status === 'error' && call.errorMessage != null && (
+          // The title attribute above is hover-only; expose the error detail
+          // as real text so it reaches screen readers, keyboard, and touch
+          // users. Rendering it inside the row also folds it into the
+          // accessible name of expandable (role="button") rows.
+          <VisuallyHidden>{`Error: ${call.errorMessage}`}</VisuallyHidden>
+        )}
       </span>
       <span {...stylex.props(styles.callName)}>{call.name}</span>
       {call.node != null && (

package/src/Chat/useTriggerMenu.tsx

@@ -699,7 +699,9 @@ export function useTriggerMenu(
       <div
         id={listboxId}
         role="listbox"
-        aria-label={trigger?.menuLabel ?? t('@astryx.chatTriggerMenu.suggestions')}
+        aria-label={
+          trigger?.menuLabel ?? t('@astryx.chatTriggerMenu.suggestions')
+        }
         {...mergeProps(
           themeProps('trigger-menu'),
           stylex.props(styles.dropdown),

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

@@ -9,10 +9,15 @@
  * SYNC: When CheckboxInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {CheckboxInput} from './CheckboxInput';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
 
 // Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
 // reflects its open state via a `popover-open` attribute the tests can assert.
@@ -333,6 +338,32 @@ describe('CheckboxInput', () => {
     );
   });
 
+  // Regression: the status is conditionally mounted, so it must be announced
+  // through the persistent useAnnounce live region — a live region born
+  // together with its content is not reliably announced.
+  it('announces a status message that appears after mount', async () => {
+    const {rerender} = render(
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
+    );
+    expect(
+      document.querySelector('[data-astryx-live-region="assertive"]'),
+    ).toBeNull();
+
+    rerender(
+      <CheckboxInput
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required field'}}
+      />,
+    );
+    await waitFor(() => {
+      expect(
+        document.querySelector('[data-astryx-live-region="assertive"]'),
+      ).toHaveTextContent('Required field');
+    });
+  });
+
   describe('disabledMessage', () => {
     const h = {hidden: true} as const;
 

package/src/CheckboxList/CheckboxList.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When CheckboxList.tsx or CheckboxListItem.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {
   render,
   screen,
@@ -20,8 +20,16 @@ import {
 import userEvent from '@testing-library/user-event';
 import {CheckboxList} from './CheckboxList';
 import {CheckboxListItem} from './CheckboxListItem';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {List} from '../List/List';
 
+// FieldStatus announces status messages through the persistent useAnnounce
+// singletons; remove them between tests so role/aria-live queries in this
+// file never match a leftover region.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 // Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
 // reflects its open state via a `popover-open` attribute the tests can assert.
 beforeEach(() => {

package/src/Citation/Citation.test.tsx

@@ -20,6 +20,7 @@ const probe = stylex.create({
   secondaryText: {color: colorVars['--color-text-secondary']},
   accentText: {color: colorVars['--color-text-accent']},
   badgeBackground: {backgroundColor: colorVars['--color-accent-muted']},
+  pointerCursor: {cursor: 'pointer'},
 });
 
 function atomicClasses(style: (typeof probe)[keyof typeof probe]): string[] {
@@ -118,4 +119,54 @@ describe('Citation', () => {
       expect(el.classList.contains(cls)).toBe(true);
     }
   });
+
+  // The interactive (pointer) treatment is keyed on `source.url`: a citation
+  // with no url is non-interactive and must keep the default cursor.
+  const noUrlSource = {title: 'No link'};
+
+  it('does not use the pointer cursor without a url in the label variant', () => {
+    render(<Citation source={noUrlSource} number={1} data-testid="citation" />);
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.pointerCursor)) {
+      expect(el.classList.contains(cls)).toBe(false);
+    }
+  });
+
+  it('uses the pointer cursor with a url in the label variant', () => {
+    render(<Citation source={source} number={1} data-testid="citation" />);
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.pointerCursor)) {
+      expect(el.classList.contains(cls)).toBe(true);
+    }
+  });
+
+  it('does not use the pointer cursor without a url in the number variant', () => {
+    render(
+      <Citation
+        source={noUrlSource}
+        number={1}
+        variant="number"
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.pointerCursor)) {
+      expect(el.classList.contains(cls)).toBe(false);
+    }
+  });
+
+  it('uses the pointer cursor with a url in the number variant', () => {
+    render(
+      <Citation
+        source={source}
+        number={1}
+        variant="number"
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.pointerCursor)) {
+      expect(el.classList.contains(cls)).toBe(true);
+    }
+  });
 });

package/src/Citation/Citation.tsx

@@ -61,7 +61,6 @@ const styles = stylex.create({
     paddingInline: spacingVars['--spacing-2'],
     marginInlineStart: spacingVars['--spacing-0-5'],
     textDecoration: 'none',
-    cursor: 'pointer',
     transitionProperty: 'background-color, border-color, color',
     transitionDuration: durationVars['--duration-fast-max'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -77,6 +76,9 @@ const styles = stylex.create({
     whiteSpace: 'nowrap',
     minWidth: 0,
   },
+  labelInteractive: {
+    cursor: 'pointer',
+  },
   labelHover: {
     backgroundColor: {
       ':hover': {
@@ -108,11 +110,13 @@ const styles = stylex.create({
     height: spacingVars['--spacing-5'],
     paddingInline: spacingVars['--spacing-1'],
     textDecoration: 'none',
-    cursor: 'pointer',
     transitionProperty: 'background-color',
     transitionDuration: durationVars['--duration-fast-max'],
     transitionTimingFunction: easeVars['--ease-standard'],
   },
+  numberInteractive: {
+    cursor: 'pointer',
+  },
   numberHover: {
     backgroundColor: {
       // Explicit default for the same reason as labelHover's color: a
@@ -191,6 +195,7 @@ export function Citation({
           stylex.props(
             styles.number,
             href != null && styles.numberHover,
+            href != null && styles.numberInteractive,
             xstyle,
           ),
           className,
@@ -215,6 +220,7 @@ export function Citation({
           styles.label,
           icon != null && styles.labelWithIcon,
           href != null && styles.labelHover,
+          href != null && styles.labelInteractive,
           xstyle,
         ),
         className,

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -28,6 +28,7 @@ export const docs = {
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
     {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: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: 'Resting shadow depth. Often raised to signal the whole card is clickable.', default: "'none'"},
     {name: 'width', type: 'SizeValue', description: 'Card width.'},
     {name: 'height', type: 'SizeValue', description: 'Card height.'},
     {name: 'maxWidth', type: 'SizeValue', description: 'Maximum card width.'},
@@ -73,6 +74,7 @@ export const docsDense = {
     isDisabled: 'disables card',
     padding: 'inner padding',
     variant: 'background color variant',
+    elevation: 'resting shadow depth: none|low|med|high; often raised to signal clickability',
     width: 'card width',
     height: 'card height',
     maxWidth: 'max card width',

package/src/ClickableCard/ClickableCard.test.tsx

@@ -106,4 +106,38 @@ describe('ClickableCard', () => {
     const link = screen.getByRole('link', {name: 'Disabled link'});
     expect(link).toHaveAttribute('aria-disabled', 'true');
   });
+
+  describe('elevation', () => {
+    it('forwards a distinct elevation class to the card for each level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <ClickableCard label="Card" elevation={elevation}>
+            Content
+          </ClickableCard>,
+        );
+        return container.firstElementChild!.className;
+      };
+      const classes = new Set([
+        classFor('none'),
+        classFor('low'),
+        classFor('med'),
+        classFor('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('defaults to flat (elevation none)', () => {
+      const {container: def} = render(
+        <ClickableCard label="Card">Content</ClickableCard>,
+      );
+      const {container: none} = render(
+        <ClickableCard label="Card" elevation="none">
+          Content
+        </ClickableCard>,
+      );
+      expect(def.firstElementChild!.className).toBe(
+        none.firstElementChild!.className,
+      );
+    });
+  });
 });

package/src/ClickableCard/ClickableCard.tsx

@@ -14,6 +14,7 @@
  * - /apps/storybook/stories/ClickableCard.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Card/ClickableCardShowcase.tsx (showcase block)
  * - /packages/cli/templates/blocks/components/Card/ClickableCardWithNestedButton.tsx (block)
+ * - /packages/cli/templates/blocks/components/Card/ClickableCardElevated.tsx (block)
  *
  * Composes Card for all visual styling (radius, padding, variants,
  * container tokens, theming). Adds an interactive wrapper with
@@ -37,7 +38,7 @@ import {
   durationVars,
   easeVars,
 } from '../theme/tokens.stylex';
-import type {SizeValue, SpacingStep} from '../utils/types';
+import type {SizeValue, SpacingStep, Elevation} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
@@ -197,6 +198,13 @@ export interface ClickableCardProps extends BaseProps {
    */
   variant?: CardVariant;
 
+  /**
+   * Resting elevation — the shadow depth the card sits at. Often raised to
+   * signal that the whole card is clickable.
+   * @default 'none'
+   */
+  elevation?: Elevation;
+
   /** Width of the card. */
   width?: SizeValue;
 
@@ -253,6 +261,7 @@ export function ClickableCard({
   children,
   padding,
   variant = 'default',
+  elevation = 'none',
   width,
   height,
   maxWidth,
@@ -297,6 +306,7 @@ export function ClickableCard({
       maxWidth={maxWidth}
       padding={padding}
       variant={variant}
+      elevation={elevation}
       {...mergeProps(themeProps('clickable-card', {variant}), {
         className: classNameProp,
         style,