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

package/src/MultiSelector/MultiSelector.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: 'MultiSelector',
@@ -234,7 +234,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   components: [
     {
@@ -316,7 +316,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'checkbox multi-select dropdown for finite sets like column toggles or filter facets',

package/src/MultiSelector/MultiSelector.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/MultiSelector/MultiSelector.test.tsx
  * - /packages/core/src/MultiSelector/index.ts
  * - /apps/storybook/stories/InputGroup.stories.tsx
- * - /packages/cli/templates/blocks/components/MultiSelector/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/MultiSelector/ (showcase blocks)
  */
 
 import React, {

package/src/NavIcon/NavIcon.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: 'NavIcon',
@@ -36,7 +36,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'NavIcon',
   displayName: 'Nav Icon',
@@ -65,7 +65,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Circular icon container w/ accent background for navigation headers.',

package/src/NavIcon/NavIcon.tsx

@@ -11,7 +11,7 @@
  * - /packages/core/src/NavIcon/NavIcon.test.tsx
  * - /packages/core/src/NavIcon/index.ts
  * - /apps/storybook/stories/TopNav.stories.tsx
- * - /packages/cli/templates/blocks/components/NavIcon/NavIconShowcase.tsx
+ * - /packages/cli/assets/templates/blocks/components/NavIcon/NavIconShowcase.tsx
  */
 
 import type {ReactNode} from 'react';

package/src/NavMenu/NavMenu.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: 'NavHeadingMenu',
@@ -40,7 +40,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Accessible menu container + items for nav heading popovers. NavHeadingMenu = role="menu" w/ keyboard nav; NavHeadingMenuItem renders selectable items.',
   usage: {

package/src/NumberInput/NumberInput.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: 'NumberInput',
@@ -197,7 +197,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'NumberInput',
   displayName: 'Number Input',
@@ -384,7 +384,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Number input component for collecting numeric user input w/ validation.',
   usage: {

package/src/NumberInput/NumberInput.tsx

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

package/src/Outline/Outline.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: 'Outline',
@@ -236,7 +236,7 @@ function FlashOnArrival() {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Outline',
   displayName: 'Outline',
@@ -334,7 +334,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Document outline/table-of-contents nav with sliding indicator track. Flat items array {id,label,level}; anchor links; density variant (default/compact); uncontrolled scroll-spy by scroll position (last heading past its resting line = offset + its own scroll-margin-top; first item at top, last at bottom); controlled with activeId; smooth-scroll on click that pins the active item until the next manual scroll. Single tab stop (roving tabindex): Arrow keys move, Home/End jump, Enter/Space activate. onNavigateStart/onNavigateEnd fire around the scroll. Scroll scoping via offset / scrollContainerRef / hasScrollOnClick.',

package/src/Outline/Outline.tsx

@@ -20,7 +20,7 @@
  * - /packages/core/src/Outline/Outline.doc.mjs
  * - /packages/core/src/Outline/index.ts
  * - /apps/storybook/stories/Outline.stories.tsx
- * - /packages/cli/templates/blocks/components/Outline/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Outline/ (showcase blocks)
  */
 
 import {useRef} from 'react';

package/src/OverflowList/OverflowList.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: 'OverflowList',
@@ -112,7 +112,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'OverflowList',
   displayName: 'Overflow List',
@@ -188,7 +188,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'horizontal list w/ overflow indicator: hides items beyond container width',
   usage: {

package/src/OverflowList/OverflowList.tsx

@@ -15,7 +15,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/OverflowList/index.ts (exports if types change)
- * - /packages/cli/templates/blocks/components/OverflowList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/OverflowList/ (showcase blocks)
  */
 
 import {type ReactNode, type ReactElement, Children} from 'react';

package/src/Overlay/Overlay.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: 'Overlay',
@@ -188,7 +188,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'layered content over media/card surfaces with scrim + hover/focus/controlled reveal',
   usage: {

package/src/Pagination/Pagination.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: 'Pagination',
@@ -131,7 +131,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Pagination',
   displayName: 'Pagination',
@@ -251,7 +251,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Standalone pagination controls for navigating content pages. Supports multiple display variants + works w/ known totals or cursor-based pagination.',

package/src/Pagination/Pagination.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Pagination/Pagination.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Pagination/index.ts (exports if types change)
  * - /apps/storybook/stories/Pagination.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Pagination/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Pagination/ (showcase blocks)
  *
  * Last synced props: page, onChange, changeAction, totalItems, totalPages, hasMore,
  *   pageSize, pageSizeOptions, onPageSizeChange, variant, siblingCount, size, isDisabled,
@@ -42,32 +42,12 @@ import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n/useTranslator';
 import {useDirection} from '../i18n/useDirection';
+import type {PaginationVariantMap} from './index';
 
 // =============================================================================
 // Types
 // =============================================================================
 
-/**
- * Extensible variant map for Pagination.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Pagination' {
- *   interface PaginationVariantMap {
- *     'progress': true;
- *   }
- * }
- * ```
- */
-export interface PaginationVariantMap {
-  pages: true;
-  count: true;
-  compact: true;
-  dots: true;
-  none: true;
-}
-
 /** Visual variant controlling what appears between prev/next buttons.
  * Extensible via module augmentation of PaginationVariantMap.
  */

package/src/Pagination/index.ts

@@ -9,10 +9,30 @@
  * @position Barrel export; consumed by packages/core/src/index.ts
  */
 
+/**
+ * Extensible variant map for Pagination.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Pagination' {
+ *   interface PaginationVariantMap {
+ *     'progress': true;
+ *   }
+ * }
+ * ```
+ */
+export interface PaginationVariantMap {
+  pages: true;
+  count: true;
+  compact: true;
+  dots: true;
+  none: true;
+}
+
 export {Pagination, generatePageRange} from './Pagination';
 export type {
   PaginationProps,
   PaginationVariant,
-  PaginationVariantMap,
   PaginationSize,
 } from './Pagination';

package/src/Popover/Popover.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: 'Popover',
@@ -72,6 +72,20 @@ export const docs = {
           type: 'string',
           description: 'Accessible label for the popover dialog.',
         },
+        {
+          name: 'role',
+          type: "'dialog' | 'none'",
+          description:
+            'ARIA role for the popover wrapper. Use dialog for dialog-style popovers; use none when content provides its own role, like menu or listbox.',
+          default: "'dialog'",
+        },
+        {
+          name: 'isModal',
+          type: 'boolean',
+          description:
+            'Whether a dialog-style popover sets aria-modal. Only applies when role is dialog.',
+          default: 'true',
+        },
         {
           name: 'hasCloseButton',
           type: 'boolean',
@@ -145,7 +159,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Popover',
   displayName: 'Popover',
@@ -213,6 +227,20 @@ export const docsZh = {
           type: 'string',
           description: '弹出框对话框的无障碍标签。',
         },
+        {
+          name: 'role',
+          type: "'dialog' | 'none'",
+          description:
+            '弹出框包装器的 ARIA 角色。对话框式弹出框使用 dialog；当内容提供自己的角色（如 menu 或 listbox）时使用 none。',
+          default: "'dialog'",
+        },
+        {
+          name: 'isModal',
+          type: 'boolean',
+          description:
+            '对话框式弹出框是否设置 aria-modal。仅在 role 为 dialog 时适用。',
+          default: 'true',
+        },
         {
           name: 'hasCloseButton',
           type: 'boolean',
@@ -275,7 +303,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Click-triggered popover displaying interactive content anchored to trigger element; implements button+dialog ARIA pattern.',

package/src/Popover/Popover.test.tsx

@@ -107,6 +107,47 @@ describe('Popover', () => {
     expect(dialog).toHaveAttribute('aria-label', 'Greeting');
   });
 
+  it('can render a neutral wrapper when content owns its role', () => {
+    render(
+      <Popover
+        role="none"
+        content={
+          <div role="menu" aria-label="Actions">
+            Menu content
+          </div>
+        }
+        label="Actions">
+        <button type="button">Open</button>
+      </Popover>,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Open'});
+    expect(trigger).toHaveAttribute('aria-haspopup', 'true');
+    expect(
+      screen.queryByRole('dialog', {hidden: true}),
+    ).not.toBeInTheDocument();
+    expect(screen.getByRole('menu', {hidden: true})).toHaveAttribute(
+      'aria-label',
+      'Actions',
+    );
+  });
+
+  it('can render a non-modal dialog wrapper', () => {
+    render(
+      <Popover
+        role="dialog"
+        isModal={false}
+        content={<span>Hello</span>}
+        label="Greeting">
+        <button type="button">Open</button>
+      </Popover>,
+    );
+
+    const dialog = screen.getByRole('dialog', {hidden: true});
+    expect(dialog).toBeInTheDocument();
+    expect(dialog).not.toHaveAttribute('aria-modal');
+  });
+
   it('calls onOpenChange when opened', () => {
     const onOpenChange = vi.fn();
     render(

package/src/Popover/Popover.tsx

@@ -14,7 +14,7 @@
  * - /packages/core/src/Popover/Popover.test.tsx
  * - /packages/core/src/Popover/index.ts
  * - /apps/storybook/stories/Popover.stories.tsx
- * - /packages/cli/templates/blocks/components/Popover/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Popover/ (showcase blocks)
  */
 
 import React, {
@@ -163,10 +163,29 @@ export interface PopoverProps extends Pick<
 
   /**
    * Accessible label for the popover dialog.
-   * Recommended for accessibility (used as aria-label on the dialog).
+   * Recommended for accessibility when `role` is `'dialog'`.
    */
   label?: string;
 
+  /**
+   * ARIA role stamped on the popover content wrapper.
+   *
+   * Use `'dialog'` for dialog-style popovers. Use `'none'` when the popup
+   * content owns its own role, such as a child `role="menu"` or
+   * `role="listbox"`.
+   *
+   * @default 'dialog'
+   */
+  role?: 'dialog' | 'none';
+
+  /**
+   * Whether a dialog-style popover is modal (`aria-modal`). Only applies when
+   * `role` is `'dialog'`.
+   *
+   * @default true
+   */
+  isModal?: boolean;
+
   /**
    * Whether to include a hidden close button for accessibility.
    * The button appears when keyboard users tab past the last element.
@@ -293,6 +312,8 @@ export function Popover({
   isEnabled = true,
   width,
   label,
+  role = 'dialog',
+  isModal,
   hasCloseButton,
   closeButtonLabel,
   hasAutoFocus,
@@ -320,6 +341,8 @@ export function Popover({
 
   const popover = usePopover({
     dialogLabel: label,
+    role,
+    isModal,
     hasLightDismiss,
     hasEscapeDismiss,
     hasCloseButton,

package/src/Popover/usePopover.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: 'usePopover',
   displayName: 'usePopover',
@@ -46,7 +46,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Use for custom interactive floating content needing keyboard nav.',
   paramDescriptions: {

package/src/Popover/usePopover.tsx

@@ -27,6 +27,7 @@ import {
   shadowVars,
 } from '../theme/tokens.stylex';
 import {Button} from '../Button';
+import {rtlStyles} from '../utils';
 import {useTranslator} from '../i18n';
 import {useDevWarning} from '../hooks/useDevWarning';
 
@@ -43,12 +44,13 @@ const styles = stylex.create({
   contentWrapper: {
     position: 'relative',
   },
-  // Hidden close button wrapper - sr-only until focused, then positioned below popover
+  // Hidden close button wrapper - sr-only until focused, then positioned below
+  // popover. Inline-axis centering (+ the translateY(100%) that drops it below
+  // the surface) comes from rtlStyles.centerInline('100%') at the call site —
+  // it centers correctly in both LTR and RTL.
   closeButtonWrapper: {
     position: 'absolute',
     bottom: 0,
-    left: '50%',
-    transform: 'translate(-50%, 100%)',
     zIndex: 1,
     // sr-only by default
     width: {
@@ -417,7 +419,11 @@ export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
           )}>
           {children}
           {hasCloseButton && (
-            <div {...stylex.props(styles.closeButtonWrapper)}>
+            <div
+              {...stylex.props(
+                styles.closeButtonWrapper,
+                rtlStyles.centerInline('100%'),
+              )}>
               <Button
                 variant="secondary"
                 label={closeButtonLabel}

package/src/PowerSearch/PowerSearch.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: 'PowerSearch',
@@ -172,7 +172,7 @@ export const docs = {
 // See .context/decisions/dense-compression-protocol.md
 // -------------------------------------------------------
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'PowerSearch',
   displayName: 'Power Search',
@@ -319,7 +319,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Structured filter bar where each token represents filter (field+operator+value). Users select fields from typeahead dropdown, configure operators+values in edit popover, manage filters as removable tokens.',

package/src/PowerSearch/PowerSearch.tsx

@@ -11,7 +11,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/PowerSearch/index.ts
- * - /packages/cli/templates/blocks/components/PowerSearch/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/PowerSearch/ (showcase blocks)
  */
 
 import React, {

package/src/ProgressBar/ProgressBar.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: 'ProgressBar',
@@ -90,7 +90,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'ProgressBar',
   displayName: 'Progress Bar',
@@ -177,7 +177,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Progress bar for displaying determinate or indeterminate progress.',

package/src/ProgressBar/ProgressBar.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/ProgressBar/ProgressBar.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/ProgressBar/index.ts (exports if types change)
  * - /apps/storybook/stories/ProgressBar.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/ProgressBar/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/ProgressBar/ (showcase blocks)
  */
 
 import {useId} from 'react';
@@ -32,27 +32,7 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {VisuallyHidden} from '../VisuallyHidden';
-
-/**
- * Extensible variant map for ProgressBar.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/ProgressBar' {
- *   interface ProgressBarVariantMap {
- *     'brand': true;
- *   }
- * }
- * ```
- */
-export interface ProgressBarVariantMap {
-  accent: true;
-  success: true;
-  warning: true;
-  neutral: true;
-  error: true;
-}
+import type {ProgressBarVariantMap} from './index';
 
 /**
  * Progress bar variant type — maps to semantic color tokens.