@astryxdesign/core 0.2.0 → 0.3.0

package/src/Item/Item.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Item.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, useClickableContainer
  * @output Exports Item component, ItemProps type
  * @position Core layout primitive; consumed by index.ts, tested by Item.test.tsx
  *
@@ -13,10 +13,10 @@
  * - /packages/core/src/Item/Item.test.tsx
  * - /packages/core/src/Item/index.ts
  * - /apps/storybook/stories/Item.stories.tsx
- * - /packages/cli/templates/blocks/components/Item/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Item/ (showcase blocks)
  */
 
-import type {ReactNode} from 'react';
+import {useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -27,9 +27,11 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps, mergeRefs} from '../utils';
 import {computeTargetAndRel} from '../Link/computeTargetAndRel';
 import {useLinkComponent} from '../Link/useLinkComponent';
+import {useClickableContainer} from '../hooks/useClickableContainer';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -108,6 +110,20 @@ export interface ItemProps extends BaseProps<HTMLElement> {
    */
   onClick?: (event: 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). Clicks on the
+   * control itself, and on any other nested interactive element, are left to
+   * that element. Mutually exclusive with `onClick`/`href` — when
+   * `interactiveRef` is set those are ignored (the nested control is the sole
+   * action).
+   */
+  interactiveRef?: React.RefObject<HTMLElement | null>;
+
   /**
    * Link URL. Makes the item a link via an invisible anchor element.
    */
@@ -349,6 +365,7 @@ export function Item({
   labelLines,
   descriptionLines,
   onClick,
+  interactiveRef,
   href,
   target: targetFromProps,
   rel: relFromProps,
@@ -363,7 +380,29 @@ export function Item({
   ...restProps
 }: ItemProps) {
   const LinkComponent = useLinkComponent();
-  const isInteractive = onClick != null || href != null;
+
+  // Delegation mode: the row is an enlarged click/tap target for a nested
+  // control (e.g. a checkbox) that owns the keyboard access and action. The
+  // control is the row's only tab stop; the row proxies surface clicks to it.
+  const isDelegate = interactiveRef != null;
+  const containerRef = useRef<HTMLElement | null>(null);
+  // Only onClick is needed: onMouseUp handles middle-click href navigation,
+  // which delegation mode never has (href is ignored here).
+  const {onClick: delegatedOnClick} = useClickableContainer({
+    containerRef,
+    interactiveRef: interactiveRef ?? undefined,
+    disabled: isDisabled,
+  });
+
+  useDevWarning(
+    'Item',
+    '`interactiveRef` is mutually exclusive with `onClick`/`href`. In ' +
+      'delegation mode the row only forwards clicks to the referenced control, ' +
+      'so `onClick`/`href` are ignored. Drop one of them.',
+    isDelegate && (onClick != null || href != null),
+  );
+
+  const isInteractive = onClick != null || href != null || isDelegate;
   const {target, rel} = computeTargetAndRel(targetFromProps, relFromProps);
   // When a semantic role is provided (e.g. "menuitem"), a parent component
   // handles keyboard access. Skip the invisible button/anchor and put
@@ -441,7 +480,10 @@ export function Item({
         <span {...stylex.props(styles.startContent)}>{startContent}</span>
       )}
 
-      {hasParentRole ? (
+      {hasParentRole || isDelegate ? (
+        // Delegation mode (and parent-role mode) put the label in a plain span:
+        // keyboard access lives on the nested control, so no invisible
+        // button/anchor is rendered and the row adds no second tab stop.
         <span
           {...stylex.props(
             styles.content,
@@ -497,7 +539,9 @@ export function Item({
 
   return (
     <Component
-      ref={ref as React.Ref<never>}
+      ref={
+        (isDelegate ? mergeRefs(ref, containerRef) : ref) as React.Ref<never>
+      }
       {...restProps}
       aria-selected={(allowsAriaSelected && isSelected) || undefined}
       // aria-selected is invalid on roles that don't permit it (listitem, a
@@ -527,11 +571,13 @@ export function Item({
       )}
       role={role}
       onClick={
-        hasParentRole
-          ? onClick
-          : isInteractive
-            ? handleContainerClick
-            : undefined
+        isDelegate
+          ? delegatedOnClick
+          : hasParentRole
+            ? onClick
+            : isInteractive
+              ? handleContainerClick
+              : undefined
       }>
       {innerContent}
     </Component>

package/src/Kbd/Kbd.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: 'Kbd',
@@ -47,7 +47,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Kbd',
   displayName: 'Kbd',
@@ -91,7 +91,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Renders keyboard shortcut as styled key badges. Use in tooltips, menus + help text to show key combinations.',

package/src/Kbd/Kbd.tsx

@@ -10,7 +10,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Kbd/index.ts
- * - /packages/cli/templates/blocks/components/Kbd/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Kbd/ (showcase blocks)
  */
 
 import React, {useSyncExternalStore} from 'react';

package/src/Layer/Layer.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: 'Layer',
   displayName: 'Layer',
@@ -63,7 +63,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

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',
@@ -44,7 +44,7 @@ export const docs = {
     {
       name: 'hasZoom',
       type: 'boolean',
-      description: 'Enable zoom on double-click (images only). When zoomed, drag to pan.',
+      description: 'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',
       default: 'false',
     },
     {
@@ -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: {
@@ -168,7 +168,7 @@ export const docsDense = {
     media: 'Single media object or array for gallery mode.',
     index: 'Current index in gallery mode.',
     onIndexChange: 'Callback when gallery index changes.',
-    hasZoom: 'Enable double-click zoom and drag pan (images only).',
+    hasZoom: 'Enable zoom (double-click, Enter/Space, or +/-) and pan (drag or arrow keys) for images.',
     xstyle: 'StyleX styles for layout customization.',
   },
 };

package/src/Lightbox/Lightbox.test.tsx

@@ -421,6 +421,184 @@ describe('Lightbox', () => {
     });
   });
 
+  describe('keyboard zoom and pan', () => {
+    const media = [
+      {src: '/a.jpg', alt: 'Image A'},
+      {src: '/b.jpg', alt: 'Image B'},
+      {src: '/c.jpg', alt: 'Image C'},
+    ];
+
+    function zoomTarget(): HTMLElement {
+      return screen.getByRole('button', {name: 'Zoom'});
+    }
+
+    it('exposes the image as a focusable zoom toggle when hasZoom is on', () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={{src: '/photo.jpg', alt: 'Photo'}}
+          hasZoom
+        />,
+      );
+      const target = zoomTarget();
+      expect(target).toHaveAttribute('tabindex', '0');
+      expect(target).toHaveAttribute('aria-pressed', 'false');
+    });
+
+    it('toggles zoom with Enter on the image', () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={{src: '/photo.jpg', alt: 'Photo'}}
+          hasZoom
+        />,
+      );
+      const target = zoomTarget();
+      fireEvent.keyDown(target, {key: 'Enter'});
+      expect(target).toHaveAttribute('aria-pressed', 'true');
+      fireEvent.keyDown(target, {key: 'Enter'});
+      expect(target).toHaveAttribute('aria-pressed', 'false');
+    });
+
+    it('toggles zoom with Space on the image', () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={{src: '/photo.jpg', alt: 'Photo'}}
+          hasZoom
+        />,
+      );
+      const target = zoomTarget();
+      fireEvent.keyDown(target, {key: ' '});
+      expect(target).toHaveAttribute('aria-pressed', 'true');
+      fireEvent.keyDown(target, {key: ' '});
+      expect(target).toHaveAttribute('aria-pressed', 'false');
+    });
+
+    it('zooms in with + and out with - from anywhere in the dialog', () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={{src: '/photo.jpg', alt: 'Photo'}}
+          hasZoom
+        />,
+      );
+      const dialog = document.querySelector('dialog')!;
+      fireEvent.keyDown(dialog, {key: '+'});
+      expect(zoomTarget()).toHaveAttribute('aria-pressed', 'true');
+      fireEvent.keyDown(dialog, {key: '-'});
+      expect(zoomTarget()).toHaveAttribute('aria-pressed', 'false');
+      // `=` (unshifted `+` on most layouts) also zooms in.
+      fireEvent.keyDown(dialog, {key: '='});
+      expect(zoomTarget()).toHaveAttribute('aria-pressed', 'true');
+    });
+
+    it('pans with arrow keys while zoomed instead of navigating the gallery', () => {
+      const onIndexChange = vi.fn();
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={1}
+          onIndexChange={onIndexChange}
+          hasZoom
+        />,
+      );
+      const dialog = document.querySelector('dialog')!;
+      fireEvent.keyDown(zoomTarget(), {key: 'Enter'});
+      const img = screen.getByAltText('Image B');
+      expect(img.getAttribute('style') ?? '').toContain('translate(0px, 0px)');
+      // ArrowRight reveals content to the right (image shifts left) and must
+      // not fall through to gallery navigation.
+      fireEvent.keyDown(dialog, {key: 'ArrowRight'});
+      expect(onIndexChange).not.toHaveBeenCalled();
+      expect(img.getAttribute('style') ?? '').toContain(
+        'translate(-25px, 0px)',
+      );
+      fireEvent.keyDown(dialog, {key: 'ArrowDown'});
+      expect(img.getAttribute('style') ?? '').toContain(
+        'translate(-25px, -25px)',
+      );
+      fireEvent.keyDown(dialog, {key: 'ArrowLeft'});
+      fireEvent.keyDown(dialog, {key: 'ArrowUp'});
+      expect(img.getAttribute('style') ?? '').toContain('translate(0px, 0px)');
+      expect(onIndexChange).not.toHaveBeenCalled();
+    });
+
+    it('navigates the gallery with arrows when not zoomed, even with hasZoom', () => {
+      const onIndexChange = vi.fn();
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={1}
+          onIndexChange={onIndexChange}
+          hasZoom
+        />,
+      );
+      const dialog = document.querySelector('dialog')!;
+      fireEvent.keyDown(dialog, {key: 'ArrowRight'});
+      expect(onIndexChange).toHaveBeenCalledWith(2);
+    });
+
+    it('announces zoom state changes politely', async () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={{src: '/photo.jpg', alt: 'Photo'}}
+          hasZoom
+        />,
+      );
+      fireEvent.keyDown(zoomTarget(), {key: 'Enter'});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Zoomed in');
+      });
+      fireEvent.keyDown(zoomTarget(), {key: 'Enter'});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Zoomed out');
+      });
+    });
+
+    it('has no zoom target or key bindings when hasZoom is off', () => {
+      const onIndexChange = vi.fn();
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={1}
+          onIndexChange={onIndexChange}
+        />,
+      );
+      expect(screen.queryByRole('button', {name: 'Zoom'})).toBeNull();
+      const dialog = document.querySelector('dialog')!;
+      fireEvent.keyDown(dialog, {key: '+'});
+      expect(document.querySelector('[aria-pressed]')).toBeNull();
+      // Arrows still navigate the gallery.
+      fireEvent.keyDown(dialog, {key: 'ArrowRight'});
+      expect(onIndexChange).toHaveBeenCalledWith(2);
+    });
+
+    it('does not expose a zoom target for video items', () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={{src: '/clip.mp4', alt: 'A clip', type: 'video'}}
+          hasZoom
+        />,
+      );
+      expect(screen.queryByRole('button', {name: 'Zoom'})).toBeNull();
+    });
+  });
+
   describe('video support', () => {
     it('renders a video element when type is video', () => {
       const {container} = render(
@@ -443,4 +621,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();
+    });
+  });
 });