@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/Layer/layerAnimations.stylex.ts

@@ -61,6 +61,27 @@ const enterStart = stylex.keyframes({
   to: {opacity: 1, transform: 'translateX(0) scale(1)'},
 });
 
+// RTL: the horizontal entrance nudge is a physical translateX, so it must
+// mirror under RTL — a layer on the inline-end/start side must slide in from
+// the correct physical side following the reading flow. Only the horizontal
+// (translateX) keyframes need mirroring; the vertical enterAbove/enterBelow
+// (translateY) entrances are direction-neutral and are left as-is.
+const enterEndRtl = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateX(${spacingVars['--spacing-2']}) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateX(0) scale(1)'},
+});
+
+const enterStartRtl = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateX(calc(-1 * ${spacingVars['--spacing-2']})) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateX(0) scale(1)'},
+});
+
 const animationBase = {
   animationDuration: durationVars['--duration-fast-max'],
   animationTimingFunction: easeVars['--ease-standard'],
@@ -95,6 +116,7 @@ export const layerAnimations = stylex.create({
   end: {
     animationName: {
       default: enterEnd,
+      ':is([dir="rtl"] *)': enterEndRtl,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
     ...animationBase,
@@ -102,6 +124,7 @@ export const layerAnimations = stylex.create({
   start: {
     animationName: {
       default: enterStart,
+      ':is([dir="rtl"] *)': enterStartRtl,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
     ...animationBase,

package/src/Layer/useLayer.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useLayer',
   displayName: 'useLayer',
@@ -114,7 +114,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Core positioning hook for overlay content via CSS Anchor Positioning + Popover API. Foundation for custom popovers, hover cards, tooltips, fixed-position layers.',

package/src/Layout/Layout.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: 'Layout',
@@ -114,7 +114,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -128,7 +128,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Composable utilities + components for structured layouts w/ container/content separation pattern.',

package/src/Layout/Layout.tsx

@@ -14,7 +14,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 
 import {type ReactNode, useMemo} from 'react';

package/src/Layout/LayoutContent.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: 'LayoutContent',

package/src/Layout/LayoutContent.tsx

@@ -12,7 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 
 import type {AriaRole, ReactNode} from 'react';

package/src/Layout/LayoutFooter.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: 'LayoutFooter',

package/src/Layout/LayoutFooter.tsx

@@ -12,7 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 
 import type {AriaRole, ReactNode} from 'react';

package/src/Layout/LayoutHeader.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: 'LayoutHeader',

package/src/Layout/LayoutHeader.tsx

@@ -12,7 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 
 import type {AriaRole, ReactNode} from 'react';

package/src/Layout/LayoutPanel.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: 'LayoutPanel',

package/src/Layout/LayoutPanel.tsx

@@ -12,7 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Layout/Layout.doc.mjs
  * - /apps/storybook/stories/Layout.stories.tsx
- * - /packages/cli/templates/blocks/components/Layout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
  */
 
 import type {AriaRole, ReactNode} from 'react';

package/src/Lightbox/Lightbox.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: 'Lightbox',
@@ -85,7 +85,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Lightbox',
   displayName: 'Lightbox',
@@ -148,7 +148,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Fullscreen overlay for viewing images and videos at full resolution with gallery navigation and zoom.',
   usage: {

package/src/Lightbox/Lightbox.test.tsx

@@ -443,4 +443,37 @@ describe('Lightbox', () => {
     );
     expect(container.querySelector('dialog')).not.toBeInTheDocument();
   });
+
+  describe('backdrop dismiss', () => {
+    it('calls onOpenChange(false) when the dark area around the media is clicked', () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          media={{src: '/photo.jpg', alt: 'Photo'}}
+        />,
+      );
+      // The container fills the whole dialog, so a click on the visual
+      // backdrop (the dark area around the media) lands on it — not on the
+      // dialog element itself.
+      const dialog = document.querySelector('dialog')!;
+      const container = dialog.firstElementChild!;
+      fireEvent.click(container);
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+
+    it('does not close when the media itself is clicked', () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          media={{src: '/photo.jpg', alt: 'Photo'}}
+        />,
+      );
+      fireEvent.click(screen.getByRole('img', {hidden: true}));
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+  });
 });

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 {
@@ -32,7 +32,7 @@ import {IconButton} from '../IconButton';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useScrollLock} from '../hooks/useScrollLock';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -199,7 +199,7 @@ const styles = stylex.create({
   closeButton: {
     position: 'absolute',
     top: spacingVars['--spacing-3'],
-    right: spacingVars['--spacing-3'],
+    insetInlineEnd: spacingVars['--spacing-3'],
     zIndex: 1,
   },
   navButton: {
@@ -209,15 +209,15 @@ const styles = stylex.create({
     zIndex: 1,
   },
   navPrev: {
-    left: spacingVars['--spacing-3'],
+    insetInlineStart: spacingVars['--spacing-3'],
   },
   navNext: {
-    right: spacingVars['--spacing-3'],
+    insetInlineEnd: spacingVars['--spacing-3'],
   },
   counter: {
     position: 'absolute',
     top: spacingVars['--spacing-3'],
-    left: spacingVars['--spacing-3'],
+    insetInlineStart: spacingVars['--spacing-3'],
     color: colorVars['--color-on-dark'],
     fontSize: typeScaleVars['--text-body-size'],
     lineHeight: typeScaleVars['--text-body-leading'],
@@ -285,6 +285,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 +391,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();
       }
     },
@@ -448,6 +458,7 @@ export function Lightbox({
         return;
       }
       setIsDragging(true);
+      didDragRef.current = false;
       dragStartRef.current = {
         x: e.clientX,
         y: e.clientY,
@@ -464,6 +475,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({
@@ -514,7 +526,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
@@ -532,7 +544,11 @@ export function Lightbox({
         {isGallery && (
           <div {...stylex.props(styles.navButton, styles.navPrev)}>
             <IconButton
-              icon={<Icon icon="chevronLeft" size="sm" color="inherit" />}
+              icon={
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <Icon icon="chevronLeft" size="sm" color="inherit" />
+                </span>
+              }
               label={t('@astryx.lightbox.previous')}
               variant="ghost"
               isDisabled={!canPrev}
@@ -587,7 +603,11 @@ export function Lightbox({
         {isGallery && (
           <div {...stylex.props(styles.navButton, styles.navNext)}>
             <IconButton
-              icon={<Icon icon="chevronRight" size="sm" color="inherit" />}
+              icon={
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <Icon icon="chevronRight" size="sm" color="inherit" />
+                </span>
+              }
               label={t('@astryx.lightbox.next')}
               variant="ghost"
               isDisabled={!canNext}

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.test.tsx

@@ -136,35 +136,23 @@ describe('List', () => {
     expect(container.querySelector('ul')).toBeInTheDocument();
   });
 
-  it('adds role="list" when listStyle is none (Safari fix)', () => {
-    const {container} = render(
-      <List>
-        <ListItem label="Item" />
-      </List>,
-    );
-    const ul = container.querySelector('ul');
-    expect(ul).toHaveAttribute('role', 'list');
-  });
-
-  it('does not add role="list" when listStyle is disc', () => {
-    const {container} = render(
-      <List listStyle="disc">
-        <ListItem label="Item" />
-      </List>,
-    );
-    const ul = container.querySelector('ul');
-    expect(ul).not.toHaveAttribute('role');
-  });
-
-  it('does not add role="list" when listStyle is decimal', () => {
-    const {container} = render(
-      <List listStyle="decimal">
-        <ListItem label="Item" />
-      </List>,
-    );
-    const ol = container.querySelector('ol');
-    expect(ol).not.toHaveAttribute('role');
-  });
+  it.each(['none', 'disc', 'circle', 'decimal'] as const)(
+    'adds an explicit role="list" when listStyle is %s (Safari fix)',
+    listStyle => {
+      // The base list style always sets list-style-type: none (markers are
+      // custom-rendered by ListItem), so Safari/VoiceOver drops the implicit
+      // list role for EVERY variant — the explicit role must always be there.
+      render(
+        <List listStyle={listStyle}>
+          <ListItem label="Item 1" />
+          <ListItem label="Item 2" />
+        </List>,
+      );
+      const list = screen.getByRole('list');
+      expect(list).toHaveAttribute('role', 'list');
+      expect(screen.getAllByRole('listitem')).toHaveLength(2);
+    },
+  );
 
   it('renders items as <li> elements', () => {
     const {container} = render(

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';
@@ -168,7 +168,12 @@ export function List({
       data-testid={testId}
       aria-labelledby={header != null ? headerId : undefined}
       {...(isOrdered && start != null && start !== 1 ? {start} : {})}
-      {...(listStyle === 'none' && !isOrdered ? {role: 'list'} : {})}
+      // The base list style always sets list-style-type: none (markers are
+      // custom-rendered by ListItem), and Safari/VoiceOver drops implicit
+      // list semantics for lists styled with list-style: none. The explicit
+      // role restores "list, N items" announcements for every listStyle
+      // variant.
+      role="list"
       {...mergeProps(
         themeProps('list', {density, listStyle}),
         stylex.props(

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',

package/src/Markdown/Markdown.test.tsx

@@ -236,6 +236,27 @@ describe('Markdown', () => {
     expect(img!.getAttribute('src')).toBe('image.png');
   });
 
+  it('uses the components.image override for a standalone (block) image', () => {
+    // A standalone image line parses as a block image; its render path must
+    // honor components.image just like the inline image path does.
+    render(
+      <Markdown
+        components={{
+          image: ({src, alt}) => (
+            <span data-testid="custom-image" data-src={src}>
+              {alt}
+            </span>
+          ),
+        }}>
+        {'![alt text](image.png)'}
+      </Markdown>,
+    );
+    expect(document.querySelector('img')).not.toBeInTheDocument();
+    const custom = screen.getByTestId('custom-image');
+    expect(custom).toHaveTextContent('alt text');
+    expect(custom.getAttribute('data-src')).toBe('image.png');
+  });
+
   it('shifts heading levels with headingLevelStart', () => {
     render(<Markdown headingLevelStart={3}>{'# Heading 1'}</Markdown>);
     expect(screen.getByText('Heading 1').tagName).toBe('H3');