@astryxdesign/core 0.2.0-canary.8d64648 → 0.2.0-canary.8dfd7cf

package/src/hooks/useContainerReveal.doc.mjs

@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useContainerReveal',
+  displayName: 'useContainerReveal',
+  keywords: ['reveal', 'hover', 'focus', 'container', 'row', 'actions', 'overlay', 'conceal', 'hidden', 'show'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseContainerRevealOptions',
+      description: 'Configuration object for the reveal container. Optional.',
+      required: false,
+    },
+    {
+      name: 'options.isEnabled',
+      type: 'boolean',
+      description: 'When false the hook is inert: no marker is applied and content getters return no styles, so content is always shown. Lets a component gate reveal on its own prop (e.g. revealOn === "hover").',
+      default: 'true',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'getContainerProps',
+      type: '() => {className?: string; style?: CSSProperties}',
+      description: 'Spread onto the container whose hover/focus-within drives the reveal.',
+    },
+    {
+      name: 'getContentRevealProps',
+      type: '(options?: ContentRevealOptions) => {className?: string; style?: CSSProperties}',
+      description: 'Spread onto each revealed (or concealed) child. Accepts isRevealInverted to conceal-on-hover instead of reveal-on-hover, and isLayoutPreserved to reserve the layout box while hidden (opacity-only) and avoid layout shift.',
+    },
+  ],
+  usage: {
+    description:
+      'A headless hover/focus reveal primitive. Gives a container a scoped trigger that reveals (or conceals) content inside it when the container is hovered or receives keyboard focus: the classic "row actions appear on hover" pattern. The reveal is CSS-only: no hover state lives in React and hovering never triggers a re-render. The caller authors no StyleX for the reveal itself; the hook hands out a scoped marker and matching styles, so nested containers never leak hover/focus into one another. Accessible by construction: revealed content is visually hidden at rest with position and opacity (never display:none), so it stays mounted, keeps its place in the tab order, and is announced to assistive technology; it reveals on :focus-within so keyboard users see it when tabbing in, stays visible on touch (never gated behind hover on coarse pointers), and honors prefers-reduced-motion.',
+    bestPractices: [
+      { guidance: true, description: 'Destructure getContainerProps and getContentRevealProps; spread getContainerProps() on the container (via mergeProps with your own stylex.props) and getContentRevealProps() on the content to reveal.' },
+      { guidance: true, description: 'Use for secondary affordances: reveal-on-hover row actions (edit/copy/remove on list or table rows) and overlay controls on a card or media tile (e.g. Thumbnail\'s remove button).' },
+      { guidance: true, description: 'Gate the reveal with isEnabled when a consumer prop decides whether content is revealed on hover or always shown.' },
+      { guidance: true, description: 'Pass isLayoutPreserved for absolutely-positioned or overlay content to reserve its box and avoid layout shift when it appears.' },
+      { guidance: false, description: 'Use it to hide content that must always be discoverable; keep essential actions visible instead of gating them behind hover.' },
+    ],
+  },
+  relatedComponents: ['Thumbnail'],
+  relatedHooks: ['useClickableContainer'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Headless hover/focus reveal primitive. Gives a container a scoped trigger that reveals (or conceals) content inside it on hover / keyboard focus: the "row actions appear on hover" pattern. CSS-only: no hover state in React, no re-render on hover. Caller authors no StyleX; hook hands out a scoped marker + matching styles, so nested containers never leak hover/focus. Accessible: revealed content visually hidden at rest via position + opacity (never display:none), stays mounted + in tab order + announced; reveals on :focus-within, stays visible on touch, honors prefers-reduced-motion.',
+  paramDescriptions: {
+    options: 'config for reveal container. optional.',
+    'options.isEnabled': 'when false hook is inert: no marker, content getters return no styles, content always shown. Lets component gate reveal on its own prop.',
+  },
+  returnDescriptions: {
+    getContainerProps: 'spread onto container whose hover/focus-within drives reveal.',
+    getContentRevealProps: 'spread onto each revealed / concealed child. Accepts isRevealInverted (conceal-on-hover) + isLayoutPreserved (reserve layout box while hidden).',
+  },
+  usage: {
+    description:
+      'Headless hover/focus reveal primitive. Gives a container a scoped trigger that reveals (or conceals) content inside it on hover / keyboard focus: the "row actions appear on hover" pattern. CSS-only: no hover state in React, no re-render on hover. Caller authors no StyleX; hook hands out a scoped marker + matching styles, so nested containers never leak hover/focus. Accessible: revealed content visually hidden at rest via position + opacity (never display:none), stays mounted + in tab order + announced; reveals on :focus-within, stays visible on touch, honors prefers-reduced-motion.',
+    bestPractices: [
+      { guidance: true, description: 'Destructure getContainerProps + getContentRevealProps; spread getContainerProps() on container (via mergeProps w/ your stylex.props) + getContentRevealProps() on content to reveal.' },
+      { guidance: true, description: 'Use for secondary affordances: reveal-on-hover row actions (edit/copy/remove on list / table rows) + overlay controls on card / media tile (e.g. Thumbnail remove button).' },
+      { guidance: true, description: 'Gate reveal w/ isEnabled when a consumer prop decides revealed-on-hover vs always shown.' },
+      { guidance: true, description: 'Pass isLayoutPreserved for absolutely-positioned / overlay content to reserve its box + avoid layout shift.' },
+      { guidance: false, description: 'Use to hide content that must always be discoverable; keep essential actions visible instead of gating behind hover.' },
+    ],
+  },
+};

package/src/hooks/useContainerReveal.ts

@@ -16,7 +16,7 @@
  * marker + matching reveal styles from a pre-compiled pool.
  *
  * ACCESSIBILITY (WCAG 2.2 by construction):
- * - Revealed content is visually hidden at rest via the clip recipe, so it
+ * - Revealed content is visually hidden at rest via position + opacity, so it
  *   stays in the accessibility tree and tab order — never display:none.
  * - Keyboard: revealed on :focus-within, so tabbing in shows it.
  * - Touch: always visible on coarse pointers; never gated behind hover.
@@ -102,9 +102,10 @@ export interface UseContainerRevealReturn {
   /** Spread onto the container whose hover/focus-within drives the reveal. */
   getContainerProps: () => {className?: string; style?: CSSProperties};
   /** Spread onto each revealed / concealed child. */
-  getContentRevealProps: (
-    options?: ContentRevealOptions,
-  ) => {className?: string; style?: CSSProperties};
+  getContentRevealProps: (options?: ContentRevealOptions) => {
+    className?: string;
+    style?: CSSProperties;
+  };
 }
 
 const EMPTY = Object.freeze({});

package/src/hooks/useEntryAnimation.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: 'useEntryAnimation',
   displayName: 'useEntryAnimation',
@@ -36,7 +36,7 @@ export const docs = {
   category: 'animation',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',

package/src/hooks/useFocusTrap.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: 'useFocusTrap',
   displayName: 'useFocusTrap',
@@ -53,7 +53,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted; use light-dismiss handler for that.',

package/src/hooks/useGridFocus.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: 'useGridFocus',
   displayName: 'useGridFocus',
@@ -124,7 +124,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Manages keyboard navigation within 2D grid following WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, Page Up/Down for custom callbacks (e.g. month navigation in calendars). Boundary navigation callbacks allow cross-grid navigation.',

package/src/hooks/useHotkeys.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: 'useHotkeys',
   displayName: 'useHotkeys',
@@ -31,7 +31,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref; re-renders never re-subscribe. Skips typing targets (input/textarea/select/contenteditable) unless allowInInputs, skips defaultPrevented, preventDefault() on match. "mod" = ⌘ on macOS, Ctrl elsewhere. SSR-safe.',

package/src/hooks/useImageMode.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: 'useImageMode',
   displayName: 'useImageMode',
@@ -61,7 +61,7 @@ export const docs = {
   category: 'media',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',

package/src/hooks/useInputContainer.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: 'useInputContainer',
   displayName: 'useInputContainer',
@@ -59,7 +59,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Makes input container wrapper clickable, delegating focus to inner input/textarea when user clicks non-interactive areas (icons, padding, status indicators). Built on useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) handled safely; clicking them does NOT steal focus from input. Automatically detects input type: text-like inputs receive .focus(), other types (checkbox, radio, file) receive .click().',

package/src/hooks/useInputContainer.test.tsx

@@ -0,0 +1,180 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useInputContainer.test.tsx
+ * @input Uses React Testing Library, useInputContainer
+ * @output Unit tests for focus-vs-click forwarding on container click
+ */
+
+import {fireEvent, render} from '@testing-library/react';
+import {useRef} from 'react';
+import {describe, expect, it, vi} from 'vitest';
+import {useInputContainer} from './useInputContainer';
+
+/**
+ * Renders a container wired with useInputContainer around a single control.
+ * The control is described by `control`, which receives the ref to attach.
+ */
+function TestContainer({
+  renderControl,
+}: {
+  renderControl: (ref: React.RefObject<HTMLElement | null>) => React.ReactNode;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLElement | null>(null);
+  const {onClick, onMouseUp} = useInputContainer({
+    containerRef,
+    inputRef,
+  });
+  return (
+    <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
+      <span data-testid="chrome">chrome</span>
+      {renderControl(inputRef)}
+    </div>
+  );
+}
+
+describe('useInputContainer', () => {
+  it('clicks (not focuses) a role="combobox" aria-haspopup="dialog" text input', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="text"
+            role="combobox"
+            aria-haspopup="dialog"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    // Click the non-interactive chrome so the container handler fires.
+    fireEvent.click(getByTestId('chrome'));
+
+    // A popup trigger must be activated via click, not merely focused —
+    // otherwise DateInput's calendar would never open.
+    expect(onControlClick).toHaveBeenCalledTimes(1);
+    expect(onFocus).not.toHaveBeenCalled();
+  });
+
+  it('clicks a control that only advertises aria-haspopup (no combobox role)', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="text"
+            aria-haspopup="menu"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onControlClick).toHaveBeenCalledTimes(1);
+    expect(onFocus).not.toHaveBeenCalled();
+  });
+
+  it('focuses (not clicks) a plain type="text" input', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="text"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onFocus).toHaveBeenCalledTimes(1);
+    expect(onControlClick).not.toHaveBeenCalled();
+  });
+
+  it('focuses (not clicks) a plain type="number" input', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="number"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onFocus).toHaveBeenCalledTimes(1);
+    expect(onControlClick).not.toHaveBeenCalled();
+  });
+
+  it('focuses (not clicks) a textarea', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <textarea
+            ref={ref as React.RefObject<HTMLTextAreaElement>}
+            data-testid="control"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onFocus).toHaveBeenCalledTimes(1);
+    expect(onControlClick).not.toHaveBeenCalled();
+  });
+
+  it('clicks (not focuses) a checkbox — unchanged behavior', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="checkbox"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onControlClick).toHaveBeenCalledTimes(1);
+    expect(onFocus).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useInputContainer.ts

@@ -35,6 +35,36 @@ const FOCUS_INPUT_TYPES = new Set([
   'week',
 ]);
 
+/**
+ * `aria-haspopup` values that advertise a control opens a popup on activation.
+ * https://www.w3.org/TR/wai-aria-1.2/#aria-haspopup
+ */
+const HASPOPUP_VALUES = new Set([
+  'true',
+  'menu',
+  'listbox',
+  'tree',
+  'grid',
+  'dialog',
+]);
+
+/**
+ * Whether an element is a popup trigger — a combobox or any control that
+ * advertises `aria-haspopup`. Such controls activate their popup on *click*
+ * (e.g. DateInput's `<input type="text" role="combobox" aria-haspopup="dialog">`
+ * opens its calendar via `onClick`, with no `onFocus` opener). Forwarding a
+ * container click to `.focus()` would focus the control but leave the popup
+ * closed — so we `.click()` these instead. Plain text inputs (no popup) are
+ * unaffected and keep `.focus()`.
+ */
+function isPopupTrigger(el: HTMLElement): boolean {
+  if (el.getAttribute('role') === 'combobox') {
+    return true;
+  }
+  const haspopup = el.getAttribute('aria-haspopup');
+  return haspopup != null && HASPOPUP_VALUES.has(haspopup);
+}
+
 export interface UseInputContainerOptions {
   /** Ref to the outer container/wrapper element */
   containerRef: RefObject<HTMLElement | null>;
@@ -83,7 +113,12 @@ export function useInputContainer({
     if (input == null) {
       return;
     }
-    if (
+    // Popup triggers (combobox / aria-haspopup) activate their popup on
+    // *click*, not focus — so check this BEFORE the type check, otherwise a
+    // `type="text"` combobox (DateInput) would `.focus()` and never open.
+    if (input instanceof HTMLElement && isPopupTrigger(input)) {
+      input.click();
+    } else if (
       input instanceof HTMLInputElement &&
       FOCUS_INPUT_TYPES.has(input.type)
     ) {

package/src/hooks/useKeyboardHint.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: 'useKeyboardHint',
   displayName: 'useKeyboardHint',
@@ -72,7 +72,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Ephemeral "← → to navigate" hint anchored to the focused item on first keyboard focus of a roving-tabindex composite (Toolbar/TabList/SegmentedControl). Teaches sighted keyboard users that arrows move within the group. Kbd-rendered arrows in a top-layer popover="manual", CSS-anchor-positioned (never clipped by overflow), aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; never re-shows for that instance.',

package/src/hooks/useKeyboardHint.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/hooks/index.ts
  * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
  * - /apps/storybook/stories/useKeyboardHint.stories.tsx
- * - /packages/cli/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
+ * - /packages/cli/assets/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
  */
 
 import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';

package/src/hooks/useListFocus.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: 'useListFocus',
   displayName: 'useListFocus',
@@ -135,7 +135,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Manages keyboard navigation within linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical / horizontal), Home/End for boundaries, optional wrap-around, Escape to close. Suitable for dropdown menus, toolbars, any 1D focusable list.',

package/src/hooks/useMediaQuery.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: 'useMediaQuery',
   displayName: 'useMediaQuery',
@@ -34,7 +34,7 @@ export const docs = {
   category: 'media',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'SSR-safe media query hook subscribing to window.matchMedia changes. Returns whether given media query matches. Always returns false on first render for SSR compatibility.',
   paramDescriptions: {

package/src/hooks/useOverflow.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: 'useOverflow',
   displayName: 'useOverflow',
@@ -84,7 +84,7 @@ export const docs = {
   category: 'layout',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Measures children rendered in hidden container to determine how many fit in available width w/o flickering. Uses ResizeObserver to react to container size changes. Measurement container should hold all items plus optional overflow indicator element (identified by data-overflow-indicator attribute).',

package/src/hooks/useScrollLock.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: 'useScrollLock',
   displayName: 'useScrollLock',
@@ -29,7 +29,7 @@ export const docs = {
   category: 'layout',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked.',

package/src/hooks/useScrollOverflow.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: 'useScrollOverflow',
   displayName: 'useScrollOverflow',
@@ -43,7 +43,7 @@ export const docs = {
   category: 'layout',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Tracks scroll overflow state for horizontally scrollable container. Returns ref callback + state booleans that update as user scrolls / container resizes. Uses scroll event listeners + ResizeObserver for reactive updates. Tolerance of 1px applied to avoid sub-pixel false positives.',

package/src/hooks/useStreamingText.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: 'useStreamingText',
   displayName: 'useStreamingText',
@@ -55,7 +55,7 @@ export const docs = {
   category: 'streaming',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',

package/src/hooks/useTreeFocus.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: 'useTreeFocus',
   displayName: 'useTreeFocus',
@@ -106,7 +106,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Manages roving-tabindex focus + WAI-ARIA tree keyboard model. ArrowUp/Down/Home/End roam linearly over visible treeitems (skip disabled); ArrowRight/Left carry tree semantics (expand/collapse, move to first-child/parent). Enter/Space activate; printable chars trigger typeahead.',

package/src/i18n/InternationalizationProvider.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: 'InternationalizationProvider',
@@ -128,7 +128,7 @@ export function AppI18n({children}: {children: ReactNode}) {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Astryx components resolve strings against this context; missing keys fall back to shipped English.',

package/src/i18n/useTranslator.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: 'useTranslator',
   displayName: 'useTranslator',
@@ -31,7 +31,7 @@ export const docs = {
   importPath: '@astryxdesign/core',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Hook returning a translator function bound to the current InternationalizationProvider context. Call with an ICU MessageFormat key and values to get the formatted string for the active locale.',