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

package/src/Collapsible/useCollapsible.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: 'useCollapsible',
   displayName: 'useCollapsible',
@@ -49,7 +49,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Encapsulates collapsible state machine. 3 modes: group-controlled (inside CollapsibleGroup), controlled (isOpen + onOpenChange), uncontrolled (self-managed w/ defaultIsOpen). Used internally by Card + Section.',
   paramDescriptions: {

package/src/CommandPalette/CommandPalette.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: 'CommandPalette',
   displayName: 'Command Palette',
@@ -22,7 +22,7 @@ export const docs = {
   description: 'Root component. Manages open state, search, keyboard navigation, and composition slots.',
   // Intentionally a contained isInline preview, not playground.overlay: the
   // component stays visible on load and knobs stay live, whereas a real
-  // showModal() overlay makes the page inert — see PlaygroundConfig.overlay
+  // showModal() overlay makes the page inert — see ComponentPlaygroundConfig.overlay
   // in docs-types.ts (#3657).
   playground: {
     defaults: {
@@ -162,7 +162,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
@@ -175,7 +175,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'searchSource-driven command palette dialog; filtering, keyboard nav, grouping, selection; same SearchSource interface as Typeahead',

package/src/CommandPalette/CommandPalette.tsx

@@ -9,7 +9,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /apps/storybook/stories/CommandPalette.stories.tsx
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 import {

package/src/CommandPalette/CommandPaletteEmpty.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: 'CommandPaletteEmpty',

package/src/CommandPalette/CommandPaletteEmpty.tsx

@@ -7,7 +7,7 @@
  * @position Sub-component; empty state shown when there are no items to display
  *
  * SYNC: When modified, update:
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 'use client';

package/src/CommandPalette/CommandPaletteFooter.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: 'CommandPaletteFooter',

package/src/CommandPalette/CommandPaletteFooter.tsx

@@ -7,7 +7,7 @@
  * @position Sub-component; footer with keyboard hints
  *
  * SYNC: When modified, update:
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 'use client';

package/src/CommandPalette/CommandPaletteGroup.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: 'CommandPaletteGroup',

package/src/CommandPalette/CommandPaletteGroup.tsx

@@ -7,7 +7,7 @@
  * @position Sub-component; visual grouping with heading
  *
  * SYNC: When modified, update:
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 'use client';

package/src/CommandPalette/CommandPaletteInput.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: 'CommandPaletteInput',

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -9,7 +9,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /apps/storybook/stories/CommandPalette.stories.tsx
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 import {useCallback, useEffect, useRef, type ReactNode} from 'react';
@@ -163,6 +163,8 @@ export function CommandPaletteInput({
   onKeyDown,
   ref,
   xstyle,
+  className,
+  style,
   ...props
 }: CommandPaletteInputProps) {
   const t = useTranslator();
@@ -207,6 +209,8 @@ export function CommandPaletteInput({
       {...mergeProps(
         themeProps('command-palette-input'),
         stylex.props(styles.wrapper, xstyle),
+        className,
+        style,
       )}>
       <span {...stylex.props(styles.icon)}>
         <Icon icon="search" size="sm" color="inherit" />

package/src/CommandPalette/CommandPaletteItem.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: 'CommandPaletteItem',

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -8,7 +8,7 @@
  * @position Sub-component; individual selectable item
  *
  * SYNC: When modified, update:
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 import {useCallback, useEffect, useMemo, useRef, type ReactNode} from 'react';

package/src/CommandPalette/CommandPaletteList.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: 'CommandPaletteList',

package/src/CommandPalette/CommandPaletteList.tsx

@@ -8,7 +8,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/CommandPalette/index.ts
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 'use client';

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -1,5 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ContextMenu',
@@ -95,7 +95,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: '右键点击时在光标位置出现的上下文菜单。用于为特定元素或区域提供上下文操作，而不使 UI 杂乱。',
@@ -109,7 +109,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'right-click context menu at cursor position',
   usage: {

package/src/ContextMenu/ContextMenu.tsx

@@ -27,7 +27,7 @@
  * - /packages/core/src/ContextMenu/ContextMenu.test.tsx
  * - /packages/core/src/ContextMenu/index.ts
  * - /apps/storybook/stories/ContextMenu.stories.tsx
- * - /packages/cli/templates/blocks/components/ContextMenu/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/ContextMenu/ (showcase blocks)
  */
 
 import React, {
@@ -220,12 +220,23 @@ export function ContextMenu({
   xstyle,
   triggerXstyle,
   'data-testid': testId,
-  ...props
+  ...rest
 }: ContextMenuProps) {
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.contextMenu.label');
-  const items = ('items' in props ? props.items : undefined) ?? [];
-  const menuContent = 'menuContent' in props ? props.menuContent : undefined;
+  // Separate content props (union discriminant) from DOM pass-through attrs.
+  // The union means exactly one of items/menuContent exists in rest; destructure
+  // both so triggerProps contains only DOM-safe attributes.
+  const {
+    items: itemsProp,
+    menuContent: menuContentProp,
+    ...triggerProps
+  } = rest as {items?: ContextMenuOption[]; menuContent?: ReactNode} & Omit<
+    typeof rest,
+    'items' | 'menuContent'
+  >;
+  const items = itemsProp ?? [];
+  const menuContent = menuContentProp;
 
   const menuId = useId();
   // Cursor point in the trigger's local coordinate space (offset from the
@@ -449,7 +460,7 @@ export function ContextMenu({
   );
 
   const resolvedMenuContent =
-    props.items !== undefined ? renderDropdownItems(items) : menuContent;
+    itemsProp !== undefined ? renderDropdownItems(items) : menuContent;
 
   return (
     <>
@@ -457,6 +468,7 @@ export function ContextMenu({
         ref={mergeRefs(ref, triggerRef)}
         onContextMenu={handleContextMenu}
         {...longPressHandlers}
+        {...triggerProps}
         data-testid={testId}
         {...stylex.props(
           styles.trigger,

package/src/ContextMenu/ContextMenuItem.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: 'ContextMenuItem',

package/src/DateInput/DateInput.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: 'DateInput',
@@ -258,7 +258,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'DateInput',
   displayName: 'Date Input',
@@ -443,7 +443,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'text input w/ calendar popover for picking a date',
   usage: {

package/src/DateInput/DateInput.tsx

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

package/src/DateRangeInput/DateRangeInput.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: 'DateRangeInput',
@@ -247,7 +247,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'date range picker with dual-month calendar popover and preset ranges',

package/src/DateRangeInput/DateRangeInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/DateRangeInput/DateRangeInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/DateRangeInput/index.ts (exports if types change)
  * - /apps/storybook/stories/DateRangeInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/DateRangeInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/DateRangeInput/ (showcase blocks)
  */
 
 import {useId, useCallback, useMemo, useOptimistic, useTransition} from 'react';

package/src/DateTimeInput/DateTimeInput.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: 'DateTimeInput',
@@ -288,7 +288,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'DateTimeInput',
   displayName: 'Date Time Input',
@@ -499,7 +499,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'combined date + time picker with calendar popover and time input',

package/src/DateTimeInput/DateTimeInput.tsx

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

package/src/Dialog/Dialog.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: 'Dialog',
@@ -10,7 +10,7 @@ export const docs = {
   keywords: ["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap","imperative"],
   // Intentionally a contained isInline preview, not playground.overlay: the
   // component stays visible on load and knobs stay live, whereas a real
-  // showModal() overlay makes the page inert — see PlaygroundConfig.overlay
+  // showModal() overlay makes the page inert — see ComponentPlaygroundConfig.overlay
   // in docs-types.ts (#3657).
   playground: {
     defaults: {
@@ -74,7 +74,11 @@ export const docs = {
     {
       name: 'position',
       type: 'DialogPosition',
-      description: 'Static position for the dialog; centered by default when omitted.',
+      description:
+        'Static position for the dialog; centered by default when omitted. ' +
+        'Prefer logical `start`/`end` (they map correctly under RTL) over the ' +
+        'deprecated physical `left`/`right`, which do not mirror. Logical ' +
+        'wins if both are set.',
     },
     {
       name: 'variant',
@@ -119,7 +123,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.',
@@ -141,7 +145,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'modal overlay that blocks page interaction until the user responds',
   usage: {

package/src/Dialog/Dialog.test.tsx

@@ -11,7 +11,7 @@
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen} from '@testing-library/react';
-import {Dialog} from './Dialog';
+import {Dialog, resolveDialogPositionOffsets} from './Dialog';
 import {DialogHeader} from './DialogHeader';
 
 // Mock showModal and close methods since they're not fully implemented in jsdom
@@ -208,6 +208,89 @@ describe('Dialog', () => {
       );
       expect(screen.getByRole('dialog')).toBeInTheDocument();
     });
+
+    it('accepts logical start/end position configuration', () => {
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={() => {}}
+          position={{top: 100, start: 20, end: 40}}>
+          Content
+        </Dialog>,
+      );
+      expect(screen.getByRole('dialog')).toBeInTheDocument();
+    });
+  });
+
+  // Physical-vs-logical mapping is verified against the pure resolver so we can
+  // assert the exact emitted CSS offsets without relying on StyleX class
+  // compilation or a browser. The public DialogPosition union forbids mixing
+  // logical and physical inline offsets (enforced at compile time, below), so
+  // the resolver has no precedence logic — it just maps what it's given.
+  describe('resolveDialogPositionOffsets (physical-vs-logical mapping)', () => {
+    it('maps logical start/end to inset-inline offsets (mirror under RTL)', () => {
+      // insetInlineStart/End are direction-relative: the browser resolves them
+      // to left/right per `dir`, so the same value mirrors under RTL.
+      const offsets = resolveDialogPositionOffsets({start: 20, end: 40});
+      expect(offsets.insetInlineStart).toBe('20px');
+      expect(offsets.insetInlineEnd).toBe('40px');
+      // No physical offsets requested → auto.
+      expect(offsets.left).toBe('auto');
+      expect(offsets.right).toBe('auto');
+    });
+
+    it('keeps physical left/right physical — they do NOT mirror', () => {
+      // Physical props are the visual-left / visual-right edge in BOTH LTR and
+      // RTL (unchanged from pre-deprecation).
+      const offsets = resolveDialogPositionOffsets({left: 20, right: 40});
+      expect(offsets.left).toBe('20px');
+      expect(offsets.right).toBe('40px');
+      // insetInlineStart/End default to auto (no logical positioning requested).
+      expect(offsets.insetInlineStart).toBe('auto');
+      expect(offsets.insetInlineEnd).toBe('auto');
+    });
+
+    it('combines block-axis top/bottom with an inline pair', () => {
+      const offsets = resolveDialogPositionOffsets({top: 100, start: 12});
+      expect(offsets.top).toBe('100px');
+      expect(offsets.insetInlineStart).toBe('12px');
+      // Everything unset falls back to auto — no mirroring for a logical-only
+      // consumer's physical slots.
+      expect(offsets.bottom).toBe('auto');
+      expect(offsets.left).toBe('auto');
+      expect(offsets.right).toBe('auto');
+      expect(offsets.insetInlineEnd).toBe('auto');
+    });
+
+    it('is non-breaking: physical-only offsets match pre-deprecation output', () => {
+      const offsets = resolveDialogPositionOffsets({top: 100, right: 20});
+      expect(offsets.top).toBe('100px');
+      expect(offsets.right).toBe('20px');
+      expect(offsets.left).toBe('auto');
+      expect(offsets.bottom).toBe('auto');
+      expect(offsets.insetInlineStart).toBe('auto');
+      expect(offsets.insetInlineEnd).toBe('auto');
+    });
+
+    it('passes through string offsets (vw/vh/etc.) for both APIs', () => {
+      const logical = resolveDialogPositionOffsets({start: '5vw', end: '10%'});
+      expect(logical.insetInlineStart).toBe('5vw');
+      expect(logical.insetInlineEnd).toBe('10%');
+
+      const physical = resolveDialogPositionOffsets({left: '5vw', top: '10vh'});
+      expect(physical.left).toBe('5vw');
+      expect(physical.top).toBe('10vh');
+    });
+
+    it('forbids mixing logical and physical inline offsets at compile time', () => {
+      // The union type makes a mixed inline pair a type error — a single dialog
+      // cannot be positioned both logically and physically. These would not
+      // compile (kept as documentation of the enforced contract):
+      // @ts-expect-error start (logical) cannot combine with left (physical)
+      resolveDialogPositionOffsets({start: 5, left: 99});
+      // @ts-expect-error end (logical) cannot combine with right (physical)
+      resolveDialogPositionOffsets({end: 7, right: 88});
+    });
   });
 
   it('forwards additional props to dialog element', () => {