@astryxdesign/core 0.2.0-canary.fc53ff7 → 0.2.0-canary.fce8b64

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/useListFocus.ts

@@ -82,14 +82,15 @@ export interface UseListFocusOptions {
   hasHomeEnd?: boolean;
 
   /**
-   * Whether the list is in a right-to-left context. When true, ArrowLeft and
-   * ArrowRight are swapped so horizontal navigation follows visual direction.
-   * Only affects horizontal (`'horizontal'`/`'both'`) navigation.
+   * @deprecated Direction is auto-detected from the container's computed
+   * `direction` — omit this. The explicit override is redundant (there's no
+   * valid reason to force RTL arrows in an LTR context) and will be removed in
+   * an upcoming major.
    *
-   * When omitted, the direction is auto-detected from the container's computed
-   * `direction` (read lazily on keydown, only for horizontal arrow keys), so
-   * lists inside `dir="rtl"` subtrees flip automatically. Pass an explicit
-   * boolean to override detection.
+   * When set, forces whether the list is right-to-left: ArrowLeft/ArrowRight
+   * are swapped so horizontal navigation follows visual direction. When
+   * omitted (preferred), the direction is auto-detected from the container's
+   * computed `direction` (read lazily on keydown, horizontal arrows only).
    * @default undefined (auto-detect from the container)
    */
   isRtl?: boolean;

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/hooks/useTreeFocus.test.tsx

@@ -35,10 +35,12 @@ function Tree({
   collapsed = NO_NODES,
   expanded = NO_NODES,
   onActivate,
+  dir,
 }: {
   collapsed?: Node[];
   expanded?: Node[];
   onActivate?: (id: string | undefined) => boolean | undefined;
+  dir?: 'ltr' | 'rtl';
 }) {
   const [isOpen, setIsOpen] = useState(false);
   const nodes = isOpen && expanded.length > 0 ? expanded : collapsed;
@@ -47,7 +49,7 @@ function Tree({
     onActivate: onActivate ? (_item, id) => onActivate(id) : undefined,
   });
   return (
-    <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown}>
+    <ul ref={treeRef} role="tree" dir={dir} onKeyDown={handleKeyDown}>
       {nodes.map(n => (
         <li
           key={n.id}
@@ -172,6 +174,56 @@ describe('useTreeFocus tree semantics (Arrow Left/Right)', () => {
   });
 });
 
+describe('useTreeFocus RTL tree semantics (WAI-ARIA Tree View)', () => {
+  const COLLAPSED: Node[] = [
+    {id: 'p', label: 'Parent', level: 1, expanded: false},
+  ];
+  const EXPANDED: Node[] = [
+    {id: 'p', label: 'Parent', level: 1, expanded: true},
+    {id: 'c1', label: 'Child 1', level: 2},
+    {id: 'c2', label: 'Child 2', level: 2},
+  ];
+
+  it('auto-detects dir="rtl": ArrowLeft expands a collapsed parent, then enters the first child', () => {
+    render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} dir="rtl" />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('p').focus();
+
+    expect(screen.queryByTestId('c1')).not.toBeInTheDocument();
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // RTL: descend → expand
+    expect(screen.getByTestId('c1')).toBeInTheDocument();
+    expect(screen.getByTestId('p')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // RTL: descend → into first child
+    expect(screen.getByTestId('c1')).toHaveFocus();
+  });
+
+  it('auto-detects dir="rtl": ArrowRight moves to parent, then collapses', () => {
+    render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} dir="rtl" />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('p').focus();
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // expand
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // into child 1
+    expect(screen.getByTestId('c1')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowRight'}); // RTL: ascend → child leaf → parent
+    expect(screen.getByTestId('p')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowRight'}); // RTL: ascend → expanded parent → collapse
+    expect(screen.queryByTestId('c1')).not.toBeInTheDocument();
+  });
+
+  it('vertical keys (ArrowDown/ArrowUp) are unaffected by RTL', () => {
+    render(<Tree collapsed={FLAT} dir="rtl" />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('a').focus();
+    fireEvent.keyDown(tree, {key: 'ArrowDown'});
+    expect(screen.getByTestId('b')).toHaveFocus();
+    fireEvent.keyDown(tree, {key: 'ArrowUp'});
+    expect(screen.getByTestId('a')).toHaveFocus();
+  });
+});
+
 describe('useTreeFocus activation + typeahead', () => {
   it('Enter/Space call onActivate for the focused item', () => {
     const onActivate = vi.fn(() => true);

package/src/hooks/useTreeFocus.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useTreeFocus.ts
- * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect, isRtlElement
  * @output Exports useTreeFocus hook for WAI-ARIA tree keyboard navigation
  * @position Core hook; used by TreeList for roving tabindex + APG tree keyboard model
  *
@@ -16,6 +16,7 @@
 
 import {useCallback, useRef} from 'react';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+import {isRtlElement} from './isRtlElement';
 
 /** Keys handled by the tree keyboard model (used to gate typeahead). */
 const NAVIGATION_KEYS = new Set([
@@ -429,7 +430,17 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(
         return;
       }
 
-      switch (e.key) {
+      // Under RTL, swap the horizontal arrows to a logical key so the
+      // expand/collapse case bodies (written LTR-first) stay unchanged.
+      let key = e.key;
+      if (key === 'ArrowLeft' || key === 'ArrowRight') {
+        const rtl = isRtlElement(treeRef.current);
+        if (rtl) {
+          key = key === 'ArrowLeft' ? 'ArrowRight' : 'ArrowLeft';
+        }
+      }
+
+      switch (key) {
         case 'ArrowDown': {
           e.preventDefault();
           focusEnabledFrom(items, currentIndex < 0 ? 0 : currentIndex + 1, 1);

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

package/src/index.ts

@@ -168,25 +168,29 @@ export * from './hooks';
 export * from './utils';
 
 // Theme
+export type {TextColorMap} from './Text';
 export * from './theme';
 
 // Internationalization
 export * from './i18n';
 
-// Doc types — for external library authors writing .doc.mjs files
+// Doc types — for external library authors writing .doc.mjs files.
+// @deprecated Import these from `@astryxdesign/cli/authoring` instead. These
+// re-exports are kept for one release cycle and will be removed; `astryx upgrade`
+// repoints them automatically.
 export type {
   ComponentDoc,
   SingleComponentDoc,
   MultiComponentDoc,
-  PropDoc,
+  ComponentPropDoc,
   ComponentEntry,
-  ThemingTarget,
-  ComponentVar,
-  DerivedVar,
-  TranslationDoc,
-  GroupDoc,
+  ComponentThemingTarget,
+  ComponentThemingVar,
+  ComponentThemingDerivedVar,
+  ComponentTranslationDoc,
+  ComponentGroupDoc,
   ReferenceDoc,
   ReferenceSection,
-  ContentBlock,
-  TokenPreviewType,
-} from './docs-types';
+  ReferenceContentBlock,
+  ReferenceTokenPreviewType,
+} from '@astryxdesign/cli/authoring';

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

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

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