@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

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 {
@@ -27,7 +27,6 @@ import {
   type KeyboardEvent,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
 import {
   colorVars,
   sizeVars,
@@ -40,7 +39,6 @@ import {
 import {
   Field,
   type InputStatus,
-  type InputStatusType,
   inputWrapperStyles,
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
@@ -54,6 +52,7 @@ import {useCalendarConstraints} from '../Calendar/hooks';
 import {usePopover} from '../Popover';
 import {useTooltip} from '../Tooltip';
 import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {
   type ISOTimeString,
   parseDateInput,
@@ -470,25 +469,21 @@ export function DateTimeInput({
     isEnabled: showsDisabledMessage,
   });
 
-  const statusIconMap: Record<InputStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
-
-  const statusIconColorMap: Record<
-    InputStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  // DateTimeInput fixes its status presentation to the detached message box,
+  // so the shared helper suppresses the on-field icon (the message box carries
+  // its own leading glyph). Routed through the helper for consistency with the
+  // rest of the bordered input family.
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant: 'detached',
+    });
 
   const ariaDescribedBy =
     [
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
+      statusTooltipDescribedBy,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
@@ -890,14 +885,22 @@ export function DateTimeInput({
         {/* Date input */}
         <div
           ref={popover.triggerRef}
-          {...stylex.props(
-            inputWrapperStyles.base,
-            sizeStyles[size],
-            styles.dateWrapper,
-            isEffectivelyDisabled && inputWrapperStyles.disabled,
-            status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
-            status && inputStatusFocusWithinStyles[status.type],
+          {...mergeProps(
+            themeProps('date-time-input-date-segment', {
+              size,
+              status: status?.type ?? null,
+            }),
+            stylex.props(
+              inputWrapperStyles.base,
+              sizeStyles[size],
+              styles.dateWrapper,
+              isEffectivelyDisabled && inputWrapperStyles.disabled,
+              status && inputStatusBorderStyles[status.type],
+              status &&
+                !isEffectivelyDisabled &&
+                inputStatusHoverShadowStyles[status.type],
+              status && inputStatusFocusWithinStyles[status.type],
+            ),
           )}>
           <button
             type="button"
@@ -968,13 +971,7 @@ export function DateTimeInput({
             </button>
           )}
           {isBusy && <Spinner size="sm" />}
-          {status && (
-            <Icon
-              icon={statusIconMap[status.type]}
-              size="md"
-              color={statusIconColorMap[status.type]}
-            />
-          )}
+          {statusIcon}
         </div>
 
         {/* Time input */}
@@ -982,14 +979,22 @@ export function DateTimeInput({
           ref={timeContainerRef}
           onClick={handleTimeWrapperClick}
           onMouseUp={handleTimeWrapperMouseUp}
-          {...stylex.props(
-            inputWrapperStyles.base,
-            sizeStyles[size],
-            styles.timeWrapper,
-            isEffectivelyDisabled && inputWrapperStyles.disabled,
-            status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
-            status && inputStatusFocusWithinStyles[status.type],
+          {...mergeProps(
+            themeProps('date-time-input-time-segment', {
+              size,
+              status: status?.type ?? null,
+            }),
+            stylex.props(
+              inputWrapperStyles.base,
+              sizeStyles[size],
+              styles.timeWrapper,
+              isEffectivelyDisabled && inputWrapperStyles.disabled,
+              status && inputStatusBorderStyles[status.type],
+              status &&
+                !isEffectivelyDisabled &&
+                inputStatusHoverShadowStyles[status.type],
+              status && inputStatusFocusWithinStyles[status.type],
+            ),
           )}>
           <div {...stylex.props(styles.icon)}>
             <Icon icon="clock" size="sm" color="secondary" />

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', () => {

package/src/Dialog/Dialog.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Dialog/Dialog.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Dialog/index.ts (exports if types change)
  * - /apps/storybook/stories/Dialog.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Dialog/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Dialog/ (showcase blocks)
  */
 
 import {
@@ -49,6 +49,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {devWarn} from '../utils/devWarning';
 import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
+import type {DialogVariantMap} from './index';
 
 /**
  * Calculate a directional translate offset for dialog entry animation.
@@ -69,24 +70,6 @@ function getDialogDirection(
   };
 }
 
-/**
- * Extensible variant map for Dialog.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Dialog' {
- *   interface DialogVariantMap {
- *     'drawer': true;
- *   }
- * }
- * ```
- */
-export interface DialogVariantMap {
-  standard: true;
-  fullscreen: true;
-}
-
 /**
  * Dialog variant type
  * - standard: Normal dialog with configurable width/height
@@ -104,16 +87,38 @@ export type DialogVariant = keyof DialogVariantMap;
  */
 export type DialogPurpose = 'required' | 'form' | 'info';
 
-/**
- * Position configuration for static dialog positioning
- */
-export interface DialogPosition {
-  bottom?: number | string;
-  left?: number | string;
-  right?: number | string;
+/** Block-axis offsets — always allowed, independent of inline direction. */
+interface DialogBlockPosition {
   top?: number | string;
+  bottom?: number | string;
 }
 
+/**
+ * Static position for a dialog. The inline axis is logical XOR physical — the
+ * type forbids mixing the two, so a single dialog can't be positioned both ways:
+ * - Logical `start`/`end` map to `inset-inline-*` and mirror under RTL (preferred).
+ * - Physical `left`/`right` are deprecated, do not mirror, and are removed in a
+ *   future major.
+ * Block-axis `top`/`bottom` may be combined with either.
+ */
+export type DialogPosition =
+  | (DialogBlockPosition & {
+      /** Logical inline-start offset (`inset-inline-start`); mirrors under RTL. */
+      start?: number | string;
+      /** Logical inline-end offset (`inset-inline-end`); mirrors under RTL. */
+      end?: number | string;
+      left?: never;
+      right?: never;
+    })
+  | (DialogBlockPosition & {
+      /** @deprecated Use `start`. Physical (never mirrors); removed in a future major. */
+      left?: number | string;
+      /** @deprecated Use `end`. Physical (never mirrors); removed in a future major. */
+      right?: number | string;
+      start?: never;
+      end?: never;
+    });
+
 const enterDirectional = stylex.keyframes({
   from: {
     opacity: 0,
@@ -215,30 +220,62 @@ const dynamicStyles = stylex.create({
     maxHeight: typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight,
   }),
   position: (
-    top: number | string | undefined,
-    right: number | string | undefined,
-    bottom: number | string | undefined,
-    left: number | string | undefined,
+    top: string,
+    insetInlineStart: string,
+    insetInlineEnd: string,
+    right: string,
+    bottom: string,
+    left: string,
   ) => ({
-    // When position is set, disable auto margin and use fixed positioning
+    // Assigns pre-resolved offsets from resolveDialogPositionOffsets(). This
+    // literal has no logic — StyleX can't analyze a helper, so the values
+    // (logical start/end → inset-inline-*, physical left/right, `auto`
+    // fallbacks) are computed at the call site and passed in.
     margin: 0,
-    top: top !== undefined ? formatPosition(top) : 'auto',
-    right: right !== undefined ? formatPosition(right) : 'auto',
-    bottom: bottom !== undefined ? formatPosition(bottom) : 'auto',
-    left: left !== undefined ? formatPosition(left) : 'auto',
+    top,
+    insetInlineStart,
+    insetInlineEnd,
+    // eslint-disable-next-line @astryx/no-physical-properties -- deprecated consumer-facing DialogPosition.right; physical by contract, superseded by logical `end`
+    right,
+    bottom,
+    // eslint-disable-next-line @astryx/no-physical-properties -- deprecated consumer-facing DialogPosition.left; physical by contract, superseded by logical `start`
+    left,
   }),
 });
 
 /**
  * Format position value - numbers become pixels, strings pass through, undefined becomes null
  */
-function formatPosition(value: number | string | undefined): string | null {
-  if (value === undefined) {
-    return null;
-  }
+function formatPosition(value: number | string): string {
   return typeof value === 'number' ? `${value}px` : value;
 }
 
+/**
+ * Map a {@link DialogPosition} to resolved CSS offsets. Logical `start`/`end`
+ * become `inset-inline-*` (mirror under RTL); physical `left`/`right` stay
+ * physical. The union type guarantees at most one inline pair is set, so no
+ * precedence is needed — each unset offset falls back to `auto`.
+ *
+ * Not re-exported from the package; internal to Dialog. Directly unit-tested
+ * so the mapping is verified without StyleX class compilation.
+ *
+ * @see DialogPosition
+ */
+export function resolveDialogPositionOffsets(position: DialogPosition) {
+  const {top, bottom, start, end, left, right} = position;
+
+  return {
+    top: top !== undefined ? formatPosition(top) : 'auto',
+    bottom: bottom !== undefined ? formatPosition(bottom) : 'auto',
+    // Logical offsets mirror under RTL (preferred replacements).
+    insetInlineStart: start !== undefined ? formatPosition(start) : 'auto',
+    insetInlineEnd: end !== undefined ? formatPosition(end) : 'auto',
+    // Deprecated physical offsets never mirror.
+    left: left !== undefined ? formatPosition(left) : 'auto',
+    right: right !== undefined ? formatPosition(right) : 'auto',
+  };
+}
+
 export interface DialogProps extends BaseProps<HTMLDialogElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDialogElement>;
@@ -632,12 +669,17 @@ export function Dialog({
           styles.backdrop,
           !isFullscreen && dynamicStyles.sizing(width, maxHeight),
           hasPosition &&
-            dynamicStyles.position(
-              position?.top,
-              position?.right,
-              position?.bottom,
-              position?.left,
-            ),
+            (() => {
+              const o = resolveDialogPositionOffsets(position);
+              return dynamicStyles.position(
+                o.top,
+                o.insetInlineStart,
+                o.insetInlineEnd,
+                o.right,
+                o.bottom,
+                o.left,
+              );
+            })(),
           isFullscreen && styles.fullscreen,
           xstyle,
         ),

package/src/Dialog/DialogHeader.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: 'DialogHeader',

package/src/Dialog/DialogHeader.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Dialog/DialogHeader.test.tsx
  * - /packages/core/src/Dialog/index.ts
  * - /apps/storybook/stories/Dialog.stories.tsx
- * - /packages/cli/templates/blocks/components/Dialog/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Dialog/ (showcase blocks)
  */
 
 import {useEffect, useRef, type ReactNode} from 'react';

package/src/Dialog/index.ts

@@ -11,11 +11,28 @@
  * SYNC: When modified, update this header and /packages/core/src/Dialog/Dialog.doc.mjs
  */
 
+/**
+ * Extensible variant map for Dialog.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Dialog' {
+ *   interface DialogVariantMap {
+ *     'drawer': true;
+ *   }
+ * }
+ * ```
+ */
+export interface DialogVariantMap {
+  standard: true;
+  fullscreen: true;
+}
+
 export {Dialog} from './Dialog';
 export type {
   DialogProps,
   DialogVariant,
-  DialogVariantMap,
   DialogPurpose,
   DialogPosition,
 } from './Dialog';

package/src/Dialog/useImperativeDialog.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: 'useImperativeDialog',

package/src/Divider/Divider.doc.mjs

@@ -2,7 +2,7 @@
 
 
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Divider',
@@ -56,7 +56,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Divider',
   displayName: 'Divider',
@@ -106,7 +106,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'visual separator w/ optional label, using Astryx design tokens',
   usage: {

package/src/Divider/Divider.test.tsx

@@ -89,25 +89,49 @@ describe('Divider', () => {
 
   it('renders vertical divider with label', () => {
     render(
-      <Divider
-        orientation="vertical"
-        label="Vertical"
-        data-testid="divider"
-      />,
+      <Divider orientation="vertical" label="Vertical" data-testid="divider" />,
     );
     const divider = screen.getByTestId('divider');
     expect(divider).toHaveAttribute('aria-orientation', 'vertical');
     expect(screen.getByText('Vertical')).toBeInTheDocument();
   });
 
-  it('renders astryx-* class names for theme targeting', () => {
+  it('exposes the label as the accessible name of the separator', () => {
+    render(<Divider label="Section" data-testid="divider" />);
+    const divider = screen.getByTestId('divider');
+    expect(divider).toHaveAttribute('aria-labelledby');
+    expect(divider).toHaveAccessibleName('Section');
+  });
+
+  it('names the separator from a ReactNode label via aria-labelledby', () => {
+    render(<Divider label={<span>Custom</span>} data-testid="divider" />);
+    expect(screen.getByTestId('divider')).toHaveAccessibleName('Custom');
+  });
+
+  it('does not set aria-labelledby without a label', () => {
+    render(<Divider data-testid="divider" />);
+    expect(screen.getByTestId('divider')).not.toHaveAttribute(
+      'aria-labelledby',
+    );
+  });
+
+  it('prefers an explicit aria-label over the rendered label', () => {
     render(
       <Divider
-        variant="strong"
-        orientation="vertical"
+        label="Section"
+        aria-label="Custom name"
         data-testid="divider"
       />,
     );
+    const divider = screen.getByTestId('divider');
+    expect(divider).toHaveAccessibleName('Custom name');
+    expect(divider).not.toHaveAttribute('aria-labelledby');
+  });
+
+  it('renders astryx-* class names for theme targeting', () => {
+    render(
+      <Divider variant="strong" orientation="vertical" data-testid="divider" />,
+    );
     const root = screen.getByTestId('divider');
     expect(root.className).toContain('astryx-divider');
     expect(root.className).toContain('strong');