Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(core): add logical start/end to Dialog position; deprecate physical left/right (#4568)

nynexman4464827f17387795
diff --git a/.changeset/dialog-position-logical-startend.md b/.changeset/dialog-position-logical-startend.md
new file mode 100644
index 0000000000..4ef93bc339
--- /dev/null
+++ b/.changeset/dialog-position-logical-startend.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Dialog: add logical `start`/`end` offsets to the `position` prop and deprecate the physical `left`/`right`. `start`/`end` map to `inset-inline-start`/`inset-inline-end`, so a positioned dialog mirrors correctly under RTL (start hugs the inline-start edge — left in LTR, right in RTL). The physical `left`/`right` still work unchanged and never mirror (non-breaking); they are now `@deprecated` and will be removed in a future major. When both a logical offset and its physical counterpart are set, the logical one wins. A codemod (`migrate-dialog-position-to-logical`, v0.2.1) rewrites `position={{left, right}}` to `{{start, end}}`.
+@nynexman4464
diff --git a/apps/storybook/stories/Dialog.stories.tsx b/apps/storybook/stories/Dialog.stories.tsx
index d6fcb1d382..65ef5ace8f 100644
--- a/apps/storybook/stories/Dialog.stories.tsx
+++ b/apps/storybook/stories/Dialog.stories.tsx
@@ -506,6 +506,67 @@ export const CustomPosition: Story = {
render: () => <PositionedModalExample />,
};
+/**
+ * Logical position example — start/end mirror under RTL.
+ *
+ * `start`/`end` map to inset-inline-start/end, so a dialog anchored to the
+ * inline-start edge stays on the start edge in both LTR and RTL. This is the
+ * preferred replacement for the deprecated physical `left`/`right` (which
+ * never mirror). Toggle the story's direction (RTL) to see it flip.
+ */
+function LogicalPositionedModalExample() {
+ const [isOpen, setIsOpen] = useState(false);
+
+ return (
+ <>
+ <Button
+ label="Open Logically-Positioned Modal"
+ variant="secondary"
+ onClick={() => setIsOpen(true)}
+ />
+ <Dialog
+ isOpen={isOpen}
+ onOpenChange={open => setIsOpen(open)}
+ position={{top: 100, start: 20}}
+ width={350}>
+ <Layout
+ header={
+ <DialogHeader
+ title="Logically-Positioned Modal"
+ onOpenChange={open => setIsOpen(open)}
+ />
+ }
+ content={
+ <LayoutContent>
+ <Text type="body">
+ Positioned with the logical `start: 20` offset (maps to
+ inset-inline-start). It hugs the inline-start edge — the left in
+ LTR, the right in RTL — instead of a fixed physical side. Prefer
+ `start`/`end` over the deprecated `left`/`right`.
+ </Text>
+ </LayoutContent>
+ }
+ footer={
+ <LayoutFooter>
+ <HStack hAlign="end">
+ <Button
+ label="Close"
+ variant="primary"
+ onClick={() => setIsOpen(false)}
+ />
+ </HStack>
+ </LayoutFooter>
+ }
+ />
+ </Dialog>
+ </>
+ );
+}
+
+export const LogicalPosition: Story = {
+ render: () => <LogicalPositionedModalExample />,
+};
+
/**
* Scrolling content example
*/
diff --git a/packages/cli/codemods/__tests__/registry.test.mjs b/packages/cli/codemods/__tests__/registry.test.mjs
index 1615494cf5..12cc692f03 100644
--- a/packages/cli/codemods/__tests__/registry.test.mjs
+++ b/packages/cli/codemods/__tests__/registry.test.mjs
@@ -23,6 +23,7 @@ describe('registry', () => {
'0.1.7',
'0.1.8',
'0.2.0',
+ '0.2.1',
]);
});
});
diff --git a/packages/cli/codemods/registry.mjs b/packages/cli/codemods/registry.mjs
index 988c165033..6e424b7b6a 100644
--- a/packages/cli/codemods/registry.mjs
+++ b/packages/cli/codemods/registry.mjs
@@ -24,6 +24,7 @@ const registry = new Map([
['0.1.7', () => import('./transforms/v0.1.7/index.mjs')],
['0.1.8', () => import('./transforms/v0.1.8/index.mjs')],
['0.2.0', () => import('./transforms/v0.2.0/index.mjs')],
+ ['0.2.1', () => import('./transforms/v0.2.1/index.mjs')],
]);
// Re-export from the shared utility so registry callers and other consumers
diff --git a/packages/cli/codemods/transforms/v0.2.1/__tests__/migrate-dialog-position-to-logical.test.mjs b/packages/cli/codemods/transforms/v0.2.1/__tests__/migrate-dialog-position-to-logical.test.mjs
new file mode 100644
index 0000000000..81e5b47bbf
--- /dev/null
+++ b/packages/cli/codemods/transforms/v0.2.1/__tests__/migrate-dialog-position-to-logical.test.mjs
@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+ const {default: transform} = await import(
+ '../migrate-dialog-position-to-logical.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const file = {source, path: 'test.tsx'};
+ const result = transform(file, api);
+ return result ?? source;
+}
+
+describe('migrate-dialog-position-to-logical', () => {
+ it('renames left->start and right->end in position object', async () => {
+ const input = `import {Dialog} from '@astryxdesign/core';
+const d = <Dialog isOpen position={{left: 20, right: 40, top: 10}}>x</Dialog>;`;
+ const output = await applyTransform(input);
+ expect(output).toContain('start: 20');
+ expect(output).toContain('end: 40');
+ expect(output).toContain('top: 10');
+ expect(output).not.toMatch(/\bleft:/);
+ expect(output).not.toMatch(/\bright:/);
+ });
+
+ it('renames only left when only left is present', async () => {
+ const input = `import {Dialog} from '@astryxdesign/core';
+const d = <Dialog position={{left: 5, top: 0}}>x</Dialog>;`;
+ const output = await applyTransform(input);
+ expect(output).toContain('start: 5');
+ expect(output).not.toMatch(/\bleft:/);
+ });
+
+ it('is alias-aware', async () => {
+ const input = `import {Dialog as Modal} from '@astryxdesign/core';
+const d = <Modal position={{right: 8}}>x</Modal>;`;
+ const output = await applyTransform(input);
+ expect(output).toContain('end: 8');
+ expect(output).not.toMatch(/\bright:/);
+ });
+
+ it('handles the subpath import source', async () => {
+ const input = `import {Dialog} from '@astryxdesign/core/Dialog';
+const d = <Dialog position={{left: 1, right: 2}}>x</Dialog>;`;
+ const output = await applyTransform(input);
+ expect(output).toContain('start: 1');
+ expect(output).toContain('end: 2');
+ });
+
+ it('handles the @xds/core import source', async () => {
+ const input = `import {Dialog} from '@xds/core';
+const d = <Dialog position={{left: 3}}>x</Dialog>;`;
+ const output = await applyTransform(input);
+ expect(output).toContain('start: 3');
+ });
+
+ it('preserves string offset values', async () => {
+ const input = `import {Dialog} from '@astryxdesign/core';
+const d = <Dialog position={{left: '5vw', right: '10%'}}>x</Dialog>;`;
+ const output = await applyTransform(input);
+ expect(output).toContain("start: '5vw'");
+ expect(output).toContain("end: '10%'");
+ });
+
+ it('leaves an already-logical position untouched (no-op)', async () => {
+ const input = `import {Dialog} from '@astryxdesign/core';
+const d = <Dialog position={{start: 20, end: 40}}>x</Dialog>;`;
+ const {default: transform} = await import(
+ '../migrate-dialog-position-to-logical.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const result = transform({source: input, path: 'test.tsx'}, api);
+ expect(result).toBeUndefined();
+ });
+
+ it('does not clobber left when start is already present (ambiguous)', async () => {
+ const input = `import {Dialog} from '@astryxdesign/core';
+const d = <Dialog position={{left: 20, start: 5}}>x</Dialog>;`;
+ const output = await applyTransform(input);
+ // start already present — leave both for a human to reconcile.
+ expect(output).toContain('left: 20');
+ expect(output).toContain('start: 5');
+ });
+
+ it('does not touch a position passed as a variable (unknown shape)', async () => {
+ const input = `import {Dialog} from '@astryxdesign/core';
+const pos = {left: 20};
+const d = <Dialog position={pos}>x</Dialog>;`;
+ const output = await applyTransform(input);
+ // The object is not inline on the JSX attribute — leave it alone.
+ expect(output).toContain('const pos = {left: 20}');
+ });
+
+ it('does not touch left/right on non-Dialog components', async () => {
+ const input = `import {Dialog} from '@astryxdesign/core';
+const d = <SomeOther position={{left: 20, right: 40}} />;`;
+ const output = await applyTransform(input);
+ expect(output).toContain('left: 20');
+ expect(output).toContain('right: 40');
+ });
+
+ it('returns undefined (no-op) when no Dialog import is found', async () => {
+ const input = `import {Button} from '@astryxdesign/core';
+const b = <Button label="x" />;`;
+ const {default: transform} = await import(
+ '../migrate-dialog-position-to-logical.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const result = transform({source: input, path: 'test.tsx'}, api);
+ expect(result).toBeUndefined();
+ });
+});
diff --git a/packages/cli/codemods/transforms/v0.2.1/index.mjs b/packages/cli/codemods/transforms/v0.2.1/index.mjs
new file mode 100644
index 0000000000..add46f051f
--- /dev/null
+++ b/packages/cli/codemods/transforms/v0.2.1/index.mjs
@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.2.1 transform manifest
+ *
+ * Lists all codemods for the v0.2.1 release in the order they should run.
+ */
+
+import migrateDialogPositionToLogical, {
+ meta as migrateDialogPositionToLogicalMeta,
+} from './migrate-dialog-position-to-logical.mjs';
+
+export default [
+ {
+ name: 'migrate-dialog-position-to-logical',
+ transform: migrateDialogPositionToLogical,
+ meta: migrateDialogPositionToLogicalMeta,
+ },
+];
diff --git a/packages/cli/codemods/transforms/v0.2.1/migrate-dialog-position-to-logical.mjs b/packages/cli/codemods/transforms/v0.2.1/migrate-dialog-position-to-logical.mjs
new file mode 100644
index 0000000000..1b59bbe3ac
--- /dev/null
+++ b/packages/cli/codemods/transforms/v0.2.1/migrate-dialog-position-to-logical.mjs
@@ -0,0 +1,139 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Migrate Dialog position left/right -> start/end
+ * @see https://github.com/facebook/astryx/pull/4568
+ *
+ * The Dialog `position` prop's physical `left`/`right` offsets are deprecated
+ * in favor of the logical `start`/`end` offsets. `start`/`end` map to
+ * `inset-inline-start` / `inset-inline-end`, so they MIRROR under RTL — a
+ * dialog anchored to the inline-start edge stays on the start edge in both
+ * LTR and RTL. The physical `left`/`right` still work (non-breaking) but never
+ * mirror and will be removed in a future major.
+ *
+ * This codemod rewrites the inline object-literal `position` prop on <Dialog>:
+ * <Dialog position={{left: 20, right: 40, top: 10}} />
+ * ->
+ * <Dialog position={{start: 20, end: 40, top: 10}} />
+ *
+ * It renames only the `left` -> `start` and `right` -> `end` keys inside an
+ * inline object literal passed to `position`. It is OPTIONAL: `left`/`right`
+ * remain valid, so consumers can adopt at their own pace. It intentionally
+ * does NOT touch:
+ * - a `position` whose value is a variable/identifier (can't see the shape),
+ * - a `left`/`right` key that already coexists with a `start`/`end` key
+ * (ambiguous intent — leave for a human),
+ * - `left`/`right` on any prop other than `position`, or on non-Dialog JSX.
+ */
+
+export const meta = {
+ title: 'Migrate Dialog position left/right to logical start/end',
+ description:
+ 'Rewrites <Dialog position={{left, right}}> to {{start, end}}. ' +
+ 'start/end map to inset-inline-start/end and mirror under RTL; the ' +
+ 'physical left/right are deprecated (still work, removed in a future ' +
+ 'major). Optional — adopt at your own pace.',
+ pr: '#4568',
+ isOptional: true,
+};
+
+/** Import sources that provide the Astryx Dialog component. */
+const IMPORT_SOURCES = new Set([
+ '@astryxdesign/core',
+ '@astryxdesign/core/Dialog',
+ '@xds/core',
+ '@xds/core/Dialog',
+]);
+
+/** Component names whose `position` prop carries DialogPosition. */
+const TARGET_IMPORTED_NAMES = new Set(['Dialog']);
+
+/** Physical -> logical key rename for the position object. */
+const KEY_RENAME = /** @type {Record<string, string>} */ ({
+ left: 'start',
+ right: 'end',
+});
+
+/**
+ * Read a static (non-computed) object-property key name.
+ * @param {any} key
+ * @returns {string | null}
+ */
+function keyName(key) {
+ if (!key) return null;
+ if (key.type === 'Identifier') return key.name;
+ if (key.type === 'Literal' || key.type === 'StringLiteral') return key.value;
+ return null;
+}
+
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ // Track alias-aware local names for Dialog.
+ const targetLocals = new Set();
+ root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+ if (!IMPORT_SOURCES.has(path.node.source.value)) return;
+ for (const spec of path.node.specifiers ?? []) {
+ if (
+ spec.type === 'ImportSpecifier' &&
+ TARGET_IMPORTED_NAMES.has(spec.imported.name)
+ ) {
+ targetLocals.add(spec.local.name);
+ }
+ }
+ });
+
+ if (targetLocals.size === 0) return undefined;
+
+ root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+ const name = path.node.name;
+ const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+ if (!componentName || !targetLocals.has(componentName)) return;
+
+ for (const attr of path.node.attributes ?? []) {
+ if (attr.type !== 'JSXAttribute') continue;
+ if (attr.name?.name !== 'position') continue;
+ // position={{ ... }} — a JSXExpressionContainer wrapping an object.
+ const value = attr.value;
+ if (!value || value.type !== 'JSXExpressionContainer') continue;
+ const obj = value.expression;
+ if (!obj || obj.type !== 'ObjectExpression') continue;
+
+ const props = obj.properties.filter(
+ (/** @type {any} */ p) =>
+ p.type === 'Property' || p.type === 'ObjectProperty',
+ );
+ const presentKeys = new Set(
+ props.map((/** @type {any} */ p) => keyName(p.key)).filter(Boolean),
+ );
+
+ for (const prop of props) {
+ if (prop.computed) continue;
+ const physical = keyName(prop.key);
+ if (!physical || !(physical in KEY_RENAME)) continue;
+ const logical = KEY_RENAME[physical];
+ // Skip if the logical key is already present — ambiguous, leave it.
+ if (presentKeys.has(logical)) continue;
+
+ if (prop.key.type === 'Identifier') {
+ prop.key.name = logical;
+ } else {
+ prop.key.value = logical;
+ }
+ presentKeys.delete(physical);
+ presentKeys.add(logical);
+ hasChanges = true;
+ }
+ }
+ });
+
+ if (!hasChanges) return undefined;
+ return root.toSource({quote: 'single'});
+}
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index a3d1f892d7..efb572768c 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -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',
diff --git a/packages/core/src/Dialog/Dialog.test.tsx b/packages/core/src/Dialog/Dialog.test.tsx
index fc5854309b..484c9fd9d9 100644
--- a/packages/core/src/Dialog/Dialog.test.tsx
+++ b/packages/core/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', () => {
diff --git a/packages/core/src/Dialog/Dialog.tsx b/packages/core/src/Dialog/Dialog.tsx
index 6352e7350f..dd63f2e61e 100644
--- a/packages/core/src/Dialog/Dialog.tsx
+++ b/packages/core/src/Dialog/Dialog.tsx
@@ -104,16 +104,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,36 +237,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',
- // consumer-facing DialogPosition API — physical by contract; logical
- // start/end migration tracked separately in the Dialog position deprecation PR
- // eslint-disable-next-line @astryx/no-physical-properties
- right: right !== undefined ? formatPosition(right) : 'auto',
- bottom: bottom !== undefined ? formatPosition(bottom) : 'auto',
- // consumer-facing DialogPosition API — physical by contract; logical
- // start/end migration tracked separately in the Dialog position deprecation PR
- // eslint-disable-next-line @astryx/no-physical-properties
- 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>;
@@ -638,12 +686,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,
),