@astryxdesign/core 0.2.0 → 0.3.0

package/src/Lightbox/Lightbox.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Lightbox/Lightbox.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Lightbox/index.ts (exports if types change)
  * - /apps/storybook/stories/Lightbox.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Lightbox/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Lightbox/ (showcase blocks)
  */
 
 import {
@@ -91,8 +91,8 @@ export interface LightboxProps extends BaseProps<HTMLDialogElement> {
    */
   onIndexChange?: (index: number) => void;
   /**
-   * Enable zoom on double-click (images only).
-   * When zoomed, drag to pan.
+   * Enable zoom on double-click, or Enter/Space/`+`/`-` via keyboard
+   * (images only). When zoomed, drag or use arrow keys to pan.
    * @default false
    */
   hasZoom?: boolean;
@@ -158,6 +158,16 @@ const styles = stylex.create({
       '@media (hover: hover)': 'zoom-in',
     },
   },
+  zoomTarget: {
+    outline: {
+      default: 'none',
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
+  },
   imageWrapperZoomed: {
     cursor: 'grab',
   },
@@ -234,12 +244,28 @@ const dynamicStyles = stylex.create({
   }),
 });
 
+/**
+ * Pan distance (px) per arrow-key press while zoomed. Offsets move the
+ * viewport in the arrow's direction — pressing ArrowRight reveals content to
+ * the right, so the image itself shifts left (negative x), matching how
+ * scrolling and pointer-drag panning feel.
+ */
+const KEYBOARD_PAN_STEP = 50;
+const KEYBOARD_PAN_OFFSETS: Record<string, [number, number]> = {
+  ArrowLeft: [KEYBOARD_PAN_STEP, 0],
+  ArrowRight: [-KEYBOARD_PAN_STEP, 0],
+  ArrowUp: [0, KEYBOARD_PAN_STEP],
+  ArrowDown: [0, -KEYBOARD_PAN_STEP],
+};
+
 /**
  * A fullscreen overlay for viewing images at full resolution.
  *
  * Supports single image and gallery modes. In gallery mode, provides
  * prev/next navigation via buttons and arrow keys. Optionally supports
- * zoom (double-click to toggle 2x) and pan (drag when zoomed).
+ * zoom (double-click, Enter/Space on the image, or `+`/`-` to toggle 2x)
+ * and pan (drag or arrow keys when zoomed; arrows navigate the gallery
+ * when not zoomed).
  *
  * Uses the native `<dialog>` element with `showModal()` for focus
  * trapping and top-layer placement. Dismiss via Escape, close button,
@@ -285,6 +311,7 @@ export function Lightbox({
 }: LightboxProps) {
   const t = useTranslator();
   const dialogRef = useRef<HTMLDialogElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
   const imageWrapperRef = useRef<HTMLDivElement>(null);
   const triggerElementRef = useRef<Element | null>(null);
 
@@ -390,10 +417,19 @@ export function Lightbox({
     [handleClose],
   );
 
-  // Backdrop click
+  // Backdrop click. The layout container fills the whole transparent dialog,
+  // so clicks on the visual backdrop (the dark area around the media) land on
+  // the container, never on the dialog element itself — treat both as the
+  // backdrop. A pan drag that ends over the backdrop still fires a click on
+  // the common ancestor; ignore it so releasing a drag doesn't dismiss.
+  const didDragRef = useRef(false);
   const handleBackdropClick = useCallback(
     (e: ReactMouseEvent<HTMLDialogElement>) => {
-      if (e.target === e.currentTarget) {
+      if (didDragRef.current) {
+        didDragRef.current = false;
+        return;
+      }
+      if (e.target === e.currentTarget || e.target === containerRef.current) {
         handleClose();
       }
     },
@@ -413,9 +449,52 @@ export function Lightbox({
     }
   }, [canNext, index, setIndex]);
 
-  // Keyboard navigation
+  // Zoom: double-click, Enter/Space on the image, or +/- keys toggle 1x ↔ 2x.
+  // Zoom changes are silent to assistive tech (only the transform changes), so
+  // mirror them in the polite live region, including a hint that arrow keys
+  // pan while zoomed.
+  const applyZoom = useCallback(
+    (next: number) => {
+      if (!hasZoom || isVideo || next === zoom) {
+        return;
+      }
+      setZoom(next);
+      setPan({x: 0, y: 0});
+      announce(
+        next > 1
+          ? t('@astryx.lightbox.zoomedIn')
+          : t('@astryx.lightbox.zoomedOut'),
+      );
+    },
+    [hasZoom, isVideo, zoom, announce, t],
+  );
+
+  const handleDoubleClick = useCallback(() => {
+    applyZoom(zoom === 1 ? 2 : 1);
+  }, [applyZoom, zoom]);
+
+  // Keyboard navigation. While zoomed, arrows pan the image (matching common
+  // lightbox conventions); when not zoomed they navigate the gallery.
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      if (hasZoom && !isVideo) {
+        if (e.key === '+' || e.key === '=') {
+          e.preventDefault();
+          applyZoom(2);
+          return;
+        }
+        if (e.key === '-') {
+          e.preventDefault();
+          applyZoom(1);
+          return;
+        }
+        if (zoom > 1 && KEYBOARD_PAN_OFFSETS[e.key] !== undefined) {
+          e.preventDefault();
+          const [dx, dy] = KEYBOARD_PAN_OFFSETS[e.key];
+          setPan(prev => ({x: prev.x + dx, y: prev.y + dy}));
+          return;
+        }
+      }
       if (e.key === 'ArrowLeft') {
         e.preventDefault();
         goToPrev();
@@ -424,22 +503,19 @@ export function Lightbox({
         goToNext();
       }
     },
-    [goToPrev, goToNext],
+    [hasZoom, isVideo, zoom, applyZoom, goToPrev, goToNext],
   );
 
-  // Zoom: double-click toggles 1x ↔ 2x
-  const handleDoubleClick = useCallback(() => {
-    if (!hasZoom) {
-      return;
-    }
-    if (zoom === 1) {
-      setZoom(2);
-      setPan({x: 0, y: 0});
-    } else {
-      setZoom(1);
-      setPan({x: 0, y: 0});
-    }
-  }, [hasZoom, zoom]);
+  // Enter/Space on the focused image wrapper (role="button") toggles zoom.
+  const handleImageKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        handleDoubleClick();
+      }
+    },
+    [handleDoubleClick],
+  );
 
   // Pan: mouse drag when zoomed
   const handlePointerDown = useCallback(
@@ -448,6 +524,7 @@ export function Lightbox({
         return;
       }
       setIsDragging(true);
+      didDragRef.current = false;
       dragStartRef.current = {
         x: e.clientX,
         y: e.clientY,
@@ -464,6 +541,7 @@ export function Lightbox({
     }
 
     const handlePointerMove = (e: PointerEvent) => {
+      didDragRef.current = true;
       const dx = e.clientX - dragStartRef.current.x;
       const dy = e.clientY - dragStartRef.current.y;
       setPan({
@@ -485,6 +563,7 @@ export function Lightbox({
   }, [isDragging]);
 
   const isZoomed = zoom > 1;
+  const isZoomTarget = hasZoom && !isVideo;
   const imageTransform =
     zoom === 1
       ? null
@@ -514,7 +593,7 @@ export function Lightbox({
         style,
       )}
       {...props}>
-      <div {...stylex.props(styles.container)}>
+      <div ref={containerRef} {...stylex.props(styles.container)}>
         {/* Close button */}
         <div {...stylex.props(styles.closeButton)}>
           <IconButton
@@ -550,13 +629,21 @@ export function Lightbox({
         <div {...stylex.props(styles.mediaGroup)}>
           <div
             ref={imageWrapperRef}
+            // The wrapper is a keyboard-operable zoom toggle when zoom is
+            // enabled: Enter/Space toggles, aria-pressed reflects state.
+            role={isZoomTarget ? 'button' : undefined}
+            tabIndex={isZoomTarget ? 0 : undefined}
+            aria-pressed={isZoomTarget ? isZoomed : undefined}
+            aria-label={isZoomTarget ? t('@astryx.lightbox.zoom') : undefined}
             {...stylex.props(
               styles.imageWrapper,
+              isZoomTarget && styles.zoomTarget,
               !isVideo && hasZoom && !isZoomed && styles.imageWrapperZoomable,
               !isVideo && isZoomed && styles.imageWrapperZoomed,
               !isVideo && isDragging && styles.imageWrapperDragging,
             )}
             onDoubleClick={isVideo ? undefined : handleDoubleClick}
+            onKeyDown={isZoomTarget ? handleImageKeyDown : undefined}
             onPointerDown={isVideo ? undefined : handlePointerDown}>
             {isVideo ? (
               <video

package/src/Link/Link.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Link',
@@ -143,7 +143,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Link',
   displayName: 'Link',
@@ -275,7 +275,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Styled anchor links w/ multiple variants + polymorphic link infra for custom link components (Next.js Link, React Router Link, etc.).',

package/src/Link/Link.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Link/Link.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Link/index.ts (exports if types change)
  * - /apps/storybook/stories/Link.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Link/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Link/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/Link/LinkProvider.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'LinkProvider',
@@ -18,7 +18,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
   usage: {

package/src/Link/LinkProvider.tsx

@@ -22,8 +22,8 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Link/index.ts
  * - /packages/core/src/Link/Link.doc.mjs
- * - /packages/cli/templates/blocks/components/Link/ (showcase blocks)
- * - /packages/cli/templates/blocks/components/LinkProvider/ (example blocks)
+ * - /packages/cli/assets/templates/blocks/components/Link/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/LinkProvider/ (example blocks)
  */
 
 import {useMemo, type ReactNode} from 'react';

package/src/List/List.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'List',
@@ -95,7 +95,7 @@ export const docs = {
     ],
   },
 };
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -116,7 +116,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Vertical list for rendering item collections w/ consistent spacing, dividers, marker styles. Composition model: List wraps ListItem sub-components.',

package/src/List/List.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/List/List.test.tsx
  * - /packages/core/src/List/index.ts
  * - /apps/storybook/stories/List.stories.tsx
- * - /packages/cli/templates/blocks/components/List/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/List/ (showcase blocks)
  */
 
 import {useId, useMemo, type ReactNode} from 'react';

package/src/List/ListItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ListItem',
@@ -59,6 +59,11 @@ export const docs = {
       type: '(e: MouseEvent) => void',
       description: 'Click handler; enables the invisible button pattern.',
     },
+    {
+      name: 'interactiveRef',
+      type: 'RefObject<HTMLElement | null>',
+      description: 'Ref to a nested control (e.g. a checkbox in startContent) that owns the item\'s keyboard access and action. The row becomes an enlarged click/tap target that delegates surface clicks to it (useClickableContainer) and renders no invisible button/anchor, so the row adds no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href; those are ignored when set.',
+    },
     {
       name: 'href',
       type: 'string',
@@ -121,6 +126,11 @@ export const docsZh = {
       type: '(e: MouseEvent) => void',
       description: '点击处理函数；启用隐形按钮模式。',
     },
+    {
+      name: 'interactiveRef',
+      type: 'RefObject<HTMLElement | null>',
+      description: '指向嵌套控件（如 startContent 中的复选框）的 ref，该控件承载项目的键盘访问和操作。行成为更大的点击/触摸目标，将表面点击委托给该控件（useClickableContainer），且不渲染不可见按钮/锚点，因此行不会增加第二个 Tab 停留点（WCAG 4.1.2）。与 onClick/href 互斥——设置后二者将被忽略。',
+    },
     {
       name: 'href',
       type: 'string',
@@ -162,6 +172,8 @@ export const docsDense = {
     startContent: 'Content before label area (e.g. icon, avatar).',
     endContent: 'Content after label area (e.g. badge, chevron).',
     onClick: 'Click handler; enables invisible button pattern.',
+    interactiveRef:
+      'Ref to a nested control that owns the item\'s keyboard access/action; row delegates surface clicks to it (useClickableContainer), no invisible button/anchor, no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href.',
     href: 'Link URL; enables invisible anchor pattern.',
     target: 'Link target attribute, only when href provided. target="_blank" auto-adds noopener noreferrer.',
     rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',

package/src/List/ListItem.tsx

@@ -16,7 +16,7 @@
  * - /packages/core/src/List/List.test.tsx
  * - /packages/core/src/List/index.ts
  * - /apps/storybook/stories/List.stories.tsx
- * - /packages/cli/templates/blocks/components/List/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/List/ (showcase blocks)
  */
 
 import {use, type ReactNode} from 'react';
@@ -75,6 +75,17 @@ export interface ListItemProps extends BaseProps<HTMLLIElement> {
    */
   onClick?: (e: React.MouseEvent) => void;
 
+  /**
+   * Ref to a nested control inside the item (e.g. a checkbox in
+   * `startContent`) that already provides the item's keyboard access and
+   * action. When set, the item becomes an enlarged click/tap target that
+   * delegates surface clicks to that control via the `useClickableContainer`
+   * pattern: it renders no invisible button/anchor, so the row adds no second
+   * tab stop (WCAG 4.1.2 — one focusable control per option). Mutually
+   * exclusive with `onClick`/`href` — when set those are ignored.
+   */
+  interactiveRef?: React.RefObject<HTMLElement | null>;
+
   /**
    * URL for link items. Renders an invisible anchor element.
    * Automatically enables hover/press styles when provided.
@@ -199,6 +210,7 @@ export function ListItem({
   startContent,
   endContent,
   onClick,
+  interactiveRef,
   href,
   target,
   rel,
@@ -239,6 +251,7 @@ export function ListItem({
       description={description}
       endContent={endContent}
       onClick={onClick}
+      interactiveRef={interactiveRef}
       href={href}
       target={target as '_blank' | '_self'}
       rel={rel}

package/src/Markdown/Markdown.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Markdown',
@@ -128,6 +128,38 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-markdown', visualProps: ['density']},
+      {
+        className: 'astryx-markdown-heading',
+        visualProps: ['density', 'level'],
+      },
+      {
+        className: 'astryx-markdown-paragraph',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-list',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-codeblock',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-blockquote',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-table',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-hr',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-image',
+        visualProps: ['density'],
+      },
     ],
   },
   usage: {
@@ -292,6 +324,54 @@ export const docsZh = {
   theming: {
     targets: [
       {className: 'astryx-markdown', visualProps: ['density']},
+      {
+        className: 'astryx-markdown-heading',
+        visualProps: ['density', 'level'],
+        description:
+          '每个渲染的标题块（h1–h6）。覆盖 marginBlockStart/marginBlockEnd 可调整标题周围的间距；反映 data-density 和 data-level，因此主题可按密度和标题层级设置间距。仅适用于默认标题渲染——自定义的 components.heading 拥有自己的样式。',
+      },
+      {
+        className: 'astryx-markdown-paragraph',
+        visualProps: ['density'],
+        description:
+          '每个渲染的段落块。覆盖 marginBlockStart/marginBlockEnd 可调整段落之间的间距。反映 data-density，因此主题可以为不同密度设置不同的间距。',
+      },
+      {
+        className: 'astryx-markdown-list',
+        visualProps: ['density'],
+        description:
+          '每个渲染的列表块（有序、无序和任务列表）。覆盖 marginBlockStart/marginBlockEnd 可调整列表周围的间距；反映 data-density。',
+      },
+      {
+        className: 'astryx-markdown-codeblock',
+        visualProps: ['density'],
+        description:
+          '每个渲染的代码块外层容器。覆盖 marginBlockStart/marginBlockEnd 可调整代码块周围的间距；反映 data-density。仅适用于默认渲染——自定义的 components.code 拥有自己的样式。',
+      },
+      {
+        className: 'astryx-markdown-blockquote',
+        visualProps: ['density'],
+        description:
+          '每个渲染的引用块（与 astryx-blockquote 目标共用同一元素）。覆盖 marginBlockStart/marginBlockEnd 可调整引用块周围的间距；反映 data-density。仅适用于默认渲染——自定义的 components.blockquote 拥有自己的样式。',
+      },
+      {
+        className: 'astryx-markdown-table',
+        visualProps: ['density'],
+        description:
+          '每个渲染的表格外层容器。覆盖 marginBlockStart/marginBlockEnd 可调整表格周围的间距；反映 data-density。',
+      },
+      {
+        className: 'astryx-markdown-hr',
+        visualProps: ['density'],
+        description:
+          '每个渲染的水平分隔线。覆盖 marginBlockStart/marginBlockEnd 可调整分隔线周围的间距；反映 data-density。仅适用于默认渲染——自定义的 components.hr 拥有自己的样式。',
+      },
+      {
+        className: 'astryx-markdown-image',
+        visualProps: ['density'],
+        description:
+          '每个渲染的块级图片外层容器（以及损坏图片的占位符）。覆盖 marginBlockStart/marginBlockEnd 可调整图片周围的间距；反映 data-density。仅适用于默认渲染——自定义的 components.image 拥有自己的样式。',
+      },
     ],
   },
   usage: {

package/src/Markdown/Markdown.test.tsx

@@ -2,6 +2,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import type {ReactNode} from 'react';
 import {Markdown} from './Markdown';
 import type {MarkdownInlinePlugin} from './Markdown';
 
@@ -34,6 +35,97 @@ describe('Markdown', () => {
     expect(para).toHaveAttribute('role', 'paragraph');
   });
 
+  it('renders the astryx-markdown-paragraph theme target on each paragraph', () => {
+    render(<Markdown>{'First para\n\nSecond para'}</Markdown>);
+    const first = screen.getByText('First para');
+    const second = screen.getByText('Second para');
+    // Stable theme-target class lets a theme adjust the inter-paragraph gap
+    // (marginBlockStart/marginBlockEnd) via defineTheme without reaching for
+    // fragile descendant selectors or global spacing tokens.
+    expect(first.className).toContain('astryx-markdown-paragraph');
+    expect(second.className).toContain('astryx-markdown-paragraph');
+  });
+
+  describe('block spacing theme targets', () => {
+    // Every block type renders a stable astryx-markdown-<block> class so a
+    // theme can tune the gap around it (marginBlockStart/marginBlockEnd) via
+    // defineTheme — the whole prose rhythm is themeable, not just paragraphs.
+    it('renders a stable theme-target class on every block type', () => {
+      const {container} = render(
+        <Markdown>
+          {[
+            '# Heading',
+            'Paragraph text',
+            '- item one',
+            '```\ncode\n```',
+            '> quoted',
+            '| a | b |\n| - | - |\n| 1 | 2 |',
+            '---',
+            '![alt](https://example.com/x.png)',
+          ].join('\n\n')}
+        </Markdown>,
+      );
+      for (const cls of [
+        'astryx-markdown-heading',
+        'astryx-markdown-paragraph',
+        'astryx-markdown-list',
+        'astryx-markdown-codeblock',
+        'astryx-markdown-blockquote',
+        'astryx-markdown-table',
+        'astryx-markdown-hr',
+        'astryx-markdown-image',
+      ]) {
+        expect(
+          container.querySelector(`.${cls}`),
+          `expected a .${cls} element`,
+        ).not.toBeNull();
+      }
+    });
+
+    it('renders the theme target on task lists too', () => {
+      const {container} = render(<Markdown>{'- [ ] todo'}</Markdown>);
+      expect(container.querySelector('.astryx-markdown-list')).not.toBeNull();
+    });
+
+    it('reflects density on block targets as data-density', () => {
+      const {rerender} = render(<Markdown>{'Hello world'}</Markdown>);
+      // Default density is reflected so themes can tune spacing per density.
+      expect(screen.getByText('Hello world')).toHaveAttribute(
+        'data-density',
+        'default',
+      );
+      rerender(<Markdown density="compact">{'Hello world'}</Markdown>);
+      expect(screen.getByText('Hello world')).toHaveAttribute(
+        'data-density',
+        'compact',
+      );
+    });
+
+    it('reflects the heading level on the heading target as data-level', () => {
+      render(<Markdown>{'## Section'}</Markdown>);
+      const heading = screen.getByText('Section');
+      expect(heading.className).toContain('astryx-markdown-heading');
+      expect(heading).toHaveAttribute('data-level', '2');
+    });
+
+    it('does not apply the theme target when a custom block component is provided', () => {
+      const {container} = render(
+        <Markdown
+          components={{
+            heading: ({children}: {children: ReactNode}) => (
+              <h2 data-custom>{children}</h2>
+            ),
+          }}>
+          {'# Custom heading'}
+        </Markdown>,
+      );
+      // Custom components own their own styling — the default target is not
+      // imposed on them.
+      expect(container.querySelector('.astryx-markdown-heading')).toBeNull();
+      expect(container.querySelector('[data-custom]')).not.toBeNull();
+    });
+  });
+
   it('renders inline display without block wrappers', () => {
     const {container} = render(
       <Markdown display="inline">{'Use `code` and **bold**'}</Markdown>,