@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

package/src/Card/Card.test.tsx

@@ -1,5 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import {createRef} from 'react';
 import {describe, it, expect} from 'vitest';
 import {render} from '@testing-library/react';
 import {Card} from './Card';
@@ -10,17 +11,52 @@ describe('Card', () => {
     expect(getByText('Hello')).toBeInTheDocument();
   });
 
-  it('renders astryx-* class names for theme targeting', () => {
-    const {container} = render(<Card>Content</Card>);
-    const root = container.firstElementChild!;
+  it('forwards ref to the rendered element', () => {
+    const ref = createRef<HTMLDivElement>();
+    const {container} = render(<Card ref={ref}>C</Card>);
+    expect(ref.current).toBe(container.firstElementChild);
+  });
+
+  it('spreads unknown props onto the same element that carries the theme target', () => {
+    const {getByTestId} = render(
+      <Card data-testid="card" id="promo" aria-label="Promotion">
+        C
+      </Card>,
+    );
+    const root = getByTestId('card');
+    expect(root).toHaveAttribute('id', 'promo');
+    expect(root).toHaveAttribute('aria-label', 'Promotion');
     expect(root.className).toContain('astryx-card');
   });
 
-  it('renders transparent variant with variant class', () => {
-    const {container} = render(<Card variant="transparent">Content</Card>);
+  it('merges a consumer className instead of replacing the theme target', () => {
+    const {container} = render(<Card className="promo">C</Card>);
     const root = container.firstElementChild!;
     expect(root.className).toContain('astryx-card');
-    expect(root.className).toContain('transparent');
+    expect(root.className).toContain('promo');
+  });
+
+  it('reflects variant as a theme data attribute', () => {
+    const {container} = render(<Card variant="muted">C</Card>);
+    expect(container.firstElementChild).toHaveAttribute(
+      'data-variant',
+      'muted',
+    );
+  });
+
+  it('reflects elevation as a theme data attribute', () => {
+    const {container} = render(<Card elevation="high">C</Card>);
+    expect(container.firstElementChild).toHaveAttribute(
+      'data-elevation',
+      'high',
+    );
+  });
+
+  it('defaults to the default variant at rest elevation', () => {
+    const {container} = render(<Card>C</Card>);
+    const root = container.firstElementChild!;
+    expect(root).toHaveAttribute('data-variant', 'default');
+    expect(root).toHaveAttribute('data-elevation', 'none');
   });
 
   it('applies a distinct class for each elevation level', () => {
@@ -28,18 +64,7 @@ describe('Card', () => {
       const {container} = render(<Card elevation={elevation}>C</Card>);
       return container.firstElementChild!.className;
     };
-    const none = classFor('none');
-    const low = classFor('low');
-    const med = classFor('med');
-    const high = classFor('high');
-    expect(new Set([none, low, med, high]).size).toBe(4);
-  });
-
-  it('defaults to flat (elevation none) — same class as explicit none', () => {
-    const {container: defaultContainer} = render(<Card>C</Card>);
-    const {container: noneContainer} = render(<Card elevation="none">C</Card>);
-    expect(defaultContainer.firstElementChild!.className).toBe(
-      noneContainer.firstElementChild!.className,
-    );
+    const classes = (['none', 'low', 'med', 'high'] as const).map(classFor);
+    expect(new Set(classes).size).toBe(4);
   });
 });

package/src/Card/Card.tsx

@@ -23,13 +23,7 @@ import {
 } from '../theme/tokens.stylex';
 import {container} from '../Layout/container.stylex';
 import type {SpacingToken} from '../Layout/container.stylex';
-import {
-  paddingStyles,
-  containerPaddingInlineVarStyles,
-  containerPaddingBlockStartVarStyles,
-  containerPaddingBlockEndVarStyles,
-  spacingStepToToken,
-} from '../Layout/padding.stylex';
+import {spacingStepToToken} from '../Layout/padding.stylex';
 import type {Elevation, SizeValue, SpacingStep} from '../utils/types';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -176,14 +170,6 @@ export type {SizeValue} from '../utils/types';
 
 export interface CardProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
-  /**
-   * CSS class name(s) appended to the root element.
-   */
-  className?: string;
-  /**
-   * Inline styles to apply to the root element.
-   */
-  style?: React.CSSProperties;
   /**
    * Width of the card.
    * Numbers are treated as pixels, strings are used as-is.
@@ -217,7 +203,12 @@ export interface CardProps extends BaseProps<HTMLDivElement> {
   /**
    * Internal padding of the card using the spacing scale.
    * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
-   * @default 4 (16px)
+   *
+   * Omit it and the card takes the theme's card padding rather than a step, so
+   * passing a step is a decision to override the theme, not a way to restate
+   * the default.
+   *
+   * @default the theme's card padding (spacing step 4 with no theme)
    */
   padding?: SpacingStep;
 
@@ -293,14 +284,15 @@ export function Card({
 
   // When no explicit padding prop, use theme default (set via container tokens)
   const useThemeDefault = padding == null;
-  const effectivePadding = padding ?? 4;
-  const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
+  const paddingToken = useThemeDefault
+    ? undefined
+    : (spacingStepToToken[padding] as SpacingToken);
 
   return (
     <div
       ref={ref}
       {...mergeProps(
-        themeProps('card', {variant}),
+        themeProps('card', {variant, elevation}),
         stylex.props(
           styles.card,
           variantStyles[variant],
@@ -313,7 +305,7 @@ export function Card({
             minHeight ?? null,
           ),
           ...container(
-            useThemeDefault
+            paddingToken == null
               ? {useThemeDefault: 'card'}
               : {
                   paddingInnerX: paddingToken,
@@ -322,18 +314,6 @@ export function Card({
                   paddingOuterY: paddingToken,
                 },
           ),
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            paddingStyles[effectivePadding],
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            containerPaddingInlineVarStyles[effectivePadding],
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            containerPaddingBlockStartVarStyles[effectivePadding],
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            containerPaddingBlockEndVarStyles[effectivePadding],
           // Applied after the container padding so the border-inset calc wins;
           // it reads the --container-padding-* vars set above.
           variant === 'default' && styles.withBorder,

package/src/Carousel/Carousel.tsx

@@ -46,11 +46,12 @@ import {useLayer} from '../Layer';
 import {useScrollOverflow} from '../hooks/useScrollOverflow';
 import {isRtlElement} from '../hooks/isRtlElement';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs, rtlStyles} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import type {SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 /**
  * Imperative control surface for the Carousel, accessed via the `handleRef`
  * prop. Methods drive the same native-scroll machinery as the built-in
@@ -506,7 +507,7 @@ export function Carousel({
 
   return (
     <div
-      ref={mergeRefs(ref, layer.ref as React.Ref<HTMLDivElement>)}
+      ref={useMergedRefs(ref, layer.ref as React.Ref<HTMLDivElement>)}
       data-testid={testId}
       {...htmlProps}
       {...mergeProps(

package/src/Chat/ChatComposerInput.tsx

@@ -255,6 +255,10 @@ const styles = stylex.create({
     opacity: 0.5,
     pointerEvents: 'none' as const,
   },
+  tokenSpan: {
+    display: 'inline-flex',
+    verticalAlign: 'middle',
+  },
 });
 
 // =============================================================================
@@ -749,7 +753,7 @@ export function ChatComposerTokenElement({token}: {token: ChatComposerToken}) {
       data-astryx-token=""
       data-astryx-token-value={token.value}
       contentEditable={false}
-      style={{display: 'inline-flex', verticalAlign: 'baseline'}}>
+      {...stylex.props(styles.tokenSpan)}>
       {isCustomToken(token) ? (
         token.render()
       ) : (

package/src/Chat/ChatLayout.tsx

@@ -33,7 +33,7 @@ import {type ReactNode, useMemo, useRef} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {useChatStreamScroll} from './useChatStreamScroll';
 import {useChatNewMessages} from './useChatNewMessages';
 import {ChatLayoutScrollButton} from './ChatLayoutScrollButton';
@@ -41,6 +41,7 @@ import {ChatLayoutContext} from './ChatContext';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Types
 // =============================================================================
@@ -343,7 +344,7 @@ export function ChatLayout({
     <ChatLayoutContext value={layoutContext}>
       <div
         {...rest}
-        ref={mergeRefs(ref, rootRef)}
+        ref={useMergedRefs(ref, rootRef)}
         data-testid={testId}
         {...mergeProps(
           themeProps('chat-layout', {density}),

package/src/Chat/ChatMessageList.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Chat',
   displayName: 'Chat Message List',
   isHiddenFromOverview: true,
-  description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full.`,
+  description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full; set align="top" to start messages at the top instead.`,
   props: [
     {
       name: 'children',
@@ -45,6 +45,12 @@ export const docs = {
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       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: 'align',
+      type: "'top' | 'bottom'",
+      description: "Vertical alignment when the list is shorter than its container. 'bottom' fills free space with a spacer so short conversations sit above the composer; 'top' omits the spacer so messages start at the top. Only affects a non-full list; overflowing lists scroll identically, preserving auto-scroll-to-bottom.",
+      default: "'bottom'",
+    },
     {
       name: 'isStreaming',
       type: 'boolean',
@@ -65,6 +71,7 @@ export const docsZh = {
     scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
     density: '视觉密度，通过上下文传递给子消息。',
     gap: '顶层消息行之间的间距。默认跟随密度；当 LLM 事件流等独立行需要不同间距时可覆盖。',
+    align: "列表内容不足一屏时的垂直对齐方式。'bottom' 用占位块填满剩余空间，让简短对话贴近输入框；'top' 省略占位块，让消息从顶部开始。仅影响未填满的列表，溢出后两种模式滚动一致，保持自动滚动到底部。",
     isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy，让屏幕阅读器等待并在完成后一次性播报，而不是每个 token 都重复播报。',
   },
 };
@@ -80,6 +87,7 @@ 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',
+    align: "'top'|'bottom' (def bottom); bottom spacer pushes short lists down, top starts at top; overflow scrolls same either way",
     isStreaming: 'assistant streaming? marks log aria-busy so SR announces the completed msg once',
   },
 };

package/src/Chat/ChatMessageList.test.tsx

@@ -83,4 +83,50 @@ describe('ChatMessageList', () => {
     );
     expect(screen.getByTestId('chat-list')).toBeTruthy();
   });
+
+  // With no scrollToTopAction the spacer is the only aria-hidden element in
+  // the list, so its presence maps 1:1 to the aria-hidden count.
+  it('renders the bottom spacer by default', () => {
+    render(
+      <ChatMessageList data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(
+      screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+    ).toHaveLength(1);
+  });
+
+  it('renders the bottom spacer when align="bottom"', () => {
+    render(
+      <ChatMessageList align="bottom" data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(
+      screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+    ).toHaveLength(1);
+  });
+
+  it('omits the spacer when align="top"', () => {
+    render(
+      <ChatMessageList align="top" data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(
+      screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+    ).toHaveLength(0);
+  });
+
+  it('still renders children when align="top"', () => {
+    render(
+      <ChatMessageList align="top">
+        <ChatMessage sender="assistant">
+          <ChatMessageBubble>Hello</ChatMessageBubble>
+        </ChatMessage>
+      </ChatMessageList>,
+    );
+    expect(screen.getByText('Hello')).toBeTruthy();
+  });
 });

package/src/Chat/ChatMessageList.tsx

@@ -10,7 +10,8 @@
  *
  * Renders a container with role="log" for chat message histories.
  * Handles density context, configurable gap, empty state,
- * a spacer that pushes messages to the bottom, and an infinite scroll sentinel.
+ * a configurable spacer (align) that pushes messages to the bottom,
+ * and an infinite scroll sentinel.
  *
  * Auto-scroll and the scroll-to-bottom button are owned by
  * ChatLayout. When used standalone (without a layout), the list
@@ -73,6 +74,24 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {
    */
   gap?: SpacingStep;
 
+  /**
+   * Vertical alignment of messages when the list is shorter than its
+   * container.
+   *
+   * - `'bottom'` (default): a spacer fills the free space and pushes
+   *   messages to the bottom, so a short conversation sits just above the
+   *   composer — the familiar messaging-app layout.
+   * - `'top'`: the spacer is omitted, so messages start at the top and grow
+   *   downward — better for document-style or log-style lists.
+   *
+   * This only changes the resting position of a non-full list. Once messages
+   * overflow the container the spacer collapses to zero in both modes, so
+   * ChatLayout auto-scroll-to-bottom behavior is identical either way.
+   *
+   * @default 'bottom'
+   */
+  align?: 'top' | 'bottom';
+
   /**
    * Whether an assistant message is actively streaming into the list.
    *
@@ -183,7 +202,8 @@ const gapStyles = stylex.create({
  *
  * Renders messages in a flex column with density-based spacing.
  * Override gap to tune row spacing separately from density.
- * A spacer pushes content to the bottom when the list isn't full.
+ * By default a spacer pushes content to the bottom when the list isn't full;
+ * set `align='top'` to start messages at the top instead.
  * Supports loading older messages via `scrollToTopAction`.
  *
  * Auto-scroll and the scroll-to-bottom button are owned by
@@ -204,6 +224,7 @@ export function ChatMessageList({
   scrollToTopAction,
   density = 'balanced',
   gap,
+  align = 'bottom',
   isStreaming = false,
   xstyle,
   className,
@@ -291,8 +312,11 @@ export function ChatMessageList({
             </div>
           )}
 
-          {/* Spacer pushes messages to bottom when list isn't full */}
-          <div {...stylex.props(styles.spacer)} aria-hidden />
+          {/* Spacer pushes messages to bottom when the list isn't full.
+              Omitted for top alignment so messages start at the top. */}
+          {align === 'bottom' && (
+            <div {...stylex.props(styles.spacer)} aria-hidden />
+          )}
 
           {/* Messages or empty state */}
           {hasChildren ? (

package/src/Chat/ChatTokenizedText.tsx

@@ -14,6 +14,8 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Chat/index.ts
+ * - /packages/core/src/Chat/ChatComposerInput.tsx (token alignment must match,
+ *   or a token moves when the message is sent)
  * - /packages/cli/assets/templates/blocks/components/ChatTokenizedText/ (block examples)
  */
 
@@ -33,6 +35,10 @@ const styles = stylex.create({
   root: {
     display: 'inline',
   },
+  token: {
+    display: 'inline-flex',
+    verticalAlign: 'middle',
+  },
 });
 
 // =============================================================================
@@ -156,16 +162,17 @@ function renderTokens(text: string, tokens: ChatComposerToken[]): ReactNode[] {
     const token = tokenMap.get(matched);
     if (token) {
       parts.push(
-        isCustomToken(token) ? (
-          <span key={`${matched}-${match.index}`}>{token.render()}</span>
-        ) : (
-          <Badge
-            key={`${matched}-${match.index}`}
-            label={token.label}
-            variant={token.variant}
-            icon={token.icon}
-          />
-        ),
+        <span key={`${matched}-${match.index}`} {...stylex.props(styles.token)}>
+          {isCustomToken(token) ? (
+            token.render()
+          ) : (
+            <Badge
+              label={token.label}
+              variant={token.variant}
+              icon={token.icon}
+            />
+          )}
+        </span>,
       );
     }
 

package/src/Chat/useChatComposerTokens.ts

@@ -120,7 +120,7 @@ export function useChatComposerTokens({
       span.setAttribute('data-astryx-token-id', id);
       span.contentEditable = 'false';
       span.style.display = 'inline-flex';
-      span.style.verticalAlign = 'baseline';
+      span.style.verticalAlign = 'middle';
 
       range.deleteContents();
       range.insertNode(span);

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -133,6 +133,7 @@ export const docs = {
       {className: 'astryx-checkbox-input', visualProps: ['size']},
       {className: 'astryx-checkbox-indicator', visualProps: ['size'], states: ['checked', 'disabled']},
       {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled'], deprecatedFor: 'checkbox-indicator'},
+      {className: 'astryx-checkbox-label'},
     ],
   },
   usage: {
@@ -209,6 +210,7 @@ export const docsZh = {
       },
       {className: 'astryx-checkbox-indicator', visualProps: ['size'], states: ['checked', 'disabled']},
       {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled'], deprecatedFor: 'checkbox-indicator'},
+      {className: 'astryx-checkbox-label'},
     ],
   },
 };

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -719,3 +719,18 @@ describe('focus ring ownership (WCAG 2.4.7)', () => {
     expect(indicatorOf(container).style.outlineStyle).toBe('');
   });
 });
+
+describe('label theme target', () => {
+  it('names its own label so a theme can style it apart from a field label', () => {
+    // The control knows this label shares a row with it; the label does not.
+    // Both classes land on the one element, so a theme reaches every label
+    // through `astryx-field-label` and only this kind through
+    // `astryx-checkbox-label`.
+    render(
+      <CheckboxInput label="Notify me" value={false} onChange={() => {}} />,
+    );
+    const label = screen.getByText('Notify me').closest('label');
+    expect(label).toHaveClass('astryx-field-label');
+    expect(label).toHaveClass('astryx-checkbox-label');
+  });
+});

package/src/CheckboxInput/CheckboxInput.tsx

@@ -44,7 +44,7 @@ import type {IconType} from '../Icon';
 import type {InputStatus} from '../Field/types';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {indicatorScope} from '../Indicator/indicator.markers.stylex';
 import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
@@ -52,6 +52,7 @@ import {useIndicator} from '../Indicator';
 import {themeProps} from '../utils/themeProps';
 import {CheckboxListContext} from '../CheckboxList/CheckboxListContext';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const styles = stylex.create({
   container: {
     display: 'flex',
@@ -409,7 +410,7 @@ export function CheckboxInput({
           {...focusProps}>
           <input
             {...rest}
-            ref={mergeRefs(
+            ref={useMergedRefs(
               ref,
               indeterminateRef,
               disabledMessageTooltip.positionRef,
@@ -477,6 +478,11 @@ export function CheckboxInput({
         </div>
         <div {...stylex.props(styles.labelWrapper)}>
           <FieldLabel
+            // A checkbox's label shares a row with its control, unlike a form
+            // field's label above its input. Naming the label rather than the
+            // arrangement means a theme asks for the thing it wants, and the
+            // component that actually knows what this is says so.
+            {...themeProps('checkbox-label')}
             label={label}
             inputID={id}
             isLabelHidden={isLabelHidden}

package/src/ClickableCard/ClickableCard.tsx

@@ -39,7 +39,7 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import type {SizeValue, SpacingStep, Elevation} from '../utils/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
 import {useClickableContainer} from '../hooks/useClickableContainer';
@@ -48,6 +48,7 @@ import {useLinkComponent} from '../Link/useLinkComponent';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Styles — only the interactive layer, Card handles everything else
 // =============================================================================
@@ -297,7 +298,7 @@ export function ClickableCard({
 
   return (
     <Card
-      ref={mergeRefs(ref, containerRef)}
+      ref={useMergedRefs(ref, containerRef)}
       width={width}
       height={height}
       maxWidth={maxWidth}

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -95,6 +95,12 @@ export const docs = {
       type: 'SyntaxThemeDefinition',
       description: 'Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors.',
     },
+    {
+      name: 'highlightMode',
+      type: "'auto' | 'ranges' | 'spans'",
+      description: 'Syntax highlighting rendering mode.',
+      default: "'auto'",
+    },
     {
       name: 'isCollapsible',
       type: 'boolean',
@@ -141,10 +147,16 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-code', visualProps: ['color']},
-      {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container']},
-      {className: 'astryx-codeblock-header', visualProps: ['size', 'language', 'container']},
-      {className: 'astryx-codeblock-title', visualProps: ['size', 'language']},
-      {className: 'astryx-codeblock-copy-button'},
+      {className: 'astryx-code-block', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-code-block-header', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-code-block-title', visualProps: ['size', 'language']},
+      {className: 'astryx-code-block-copy-button'},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container'], deprecatedFor: 'code-block'},
+      {className: 'astryx-codeblock-header', visualProps: ['size', 'language', 'container'], deprecatedFor: 'code-block-header'},
+      {className: 'astryx-codeblock-title', visualProps: ['size', 'language'], deprecatedFor: 'code-block-title'},
+      {className: 'astryx-codeblock-copy-button', deprecatedFor: 'code-block-copy-button'},
     ],
     vars: [
       {name: '--_codeblock-gutter-width', description: 'Width of the line-number gutter, computed from the digit count of the last line so the code column starts at a stable offset.', default: '2ch', private: true},

package/src/CodeBlock/CodeBlock.test.tsx

@@ -396,3 +396,40 @@ describe('CodeBlock', () => {
     });
   });
 });
+
+describe('CodeBlock theme target names', () => {
+  it('renders the deprecated classes beside the current ones', () => {
+    const {container} = render(
+      <CodeBlock
+        code="const x = 1;"
+        language="javascript"
+        title="example.js"
+      />,
+    );
+    expect(container.querySelector('.astryx-code-block')).toHaveClass(
+      'astryx-codeblock',
+    );
+    expect(container.querySelector('.astryx-code-block-header')).toHaveClass(
+      'astryx-codeblock-header',
+    );
+    expect(container.querySelector('.astryx-code-block-title')).toHaveClass(
+      'astryx-codeblock-title',
+    );
+    expect(screen.getByRole('button', {name: 'Copy code'})).toHaveClass(
+      'astryx-code-block-copy-button',
+    );
+  });
+
+  it('reaches the header and title through the current defineTheme keys', () => {
+    const theme = defineTheme({
+      name: 'code-block-header-target-test',
+      components: {
+        'code-block-header': {base: {paddingBlock: 'var(--spacing-1)'}},
+        'code-block-title': {base: {fontSize: 'var(--text-body-size)'}},
+      },
+    });
+    const css = generateThemeTestCSS(theme);
+    expect(css).toContain('.astryx-code-block-header');
+    expect(css).toContain('.astryx-code-block-title');
+  });
+});