An open source design system that's fully customizable and agent ready
TypeScript
feat(core): add XDSFormLayout — spatial layout for form fields (#438)
Cindy Zhange79f0b401ee4
diff --git a/apps/storybook/stories/FormLayout.stories.tsx b/apps/storybook/stories/FormLayout.stories.tsxnew file mode 100644index 0000000000..582ca71751--- /dev/null+++ b/apps/storybook/stories/FormLayout.stories.tsx@@ -0,0 +1,265 @@+import {useState} from 'react';+import type {Meta, StoryObj} from '@storybook/react';+import {XDSFormLayout} from '@xds/core/FormLayout';+import {XDSTextInput} from '@xds/core/TextInput';+import {XDSSelector} from '@xds/core/Selector';+import {XDSField} from '@xds/core/Field';+import {XDSText} from '@xds/core/Text';+import * as stylex from '@stylexjs/stylex';++const meta: Meta<typeof XDSFormLayout> = {+ title: 'Form/XDSFormLayout',+ component: XDSFormLayout,+ tags: ['autodocs'],+ args: {+ direction: 'vertical',+ },+ argTypes: {+ direction: {+ control: 'select',+ options: ['vertical', 'horizontal', 'horizontal-labels'],+ description: 'Direction of field arrangement',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSFormLayout>;++// Helper component that uses args so Storybook controls work+function FormLayoutDemo({+ direction,+}: {+ direction?: 'vertical' | 'horizontal' | 'horizontal-labels';+}) {+ const [name, setName] = useState('');+ const [email, setEmail] = useState('');+ const [bio, setBio] = useState('');+ return (+ <XDSFormLayout direction={direction}>+ <XDSTextInput label="Name" value={name} onChange={setName} />+ <XDSTextInput label="Email" value={email} onChange={setEmail} />+ <XDSTextInput label="Bio" value={bio} onChange={setBio} />+ </XDSFormLayout>+ );+}++// ─── Vertical (default) ───────────────────────────────────────────────────++export const Vertical: Story = {+ name: 'Vertical (Default)',+ render: args => <FormLayoutDemo direction={args.direction} />,+};++// ─── Horizontal ───────────────────────────────────────────────────────────++export const Horizontal: Story = {+ name: 'Horizontal',+ args: {+ direction: 'horizontal',+ },+ render: args => {+ const [first, setFirst] = useState('');+ const [last, setLast] = useState('');+ return (+ <XDSFormLayout direction={args.direction}>+ <XDSTextInput label="First Name" value={first} onChange={setFirst} />+ <XDSTextInput label="Last Name" value={last} onChange={setLast} />+ </XDSFormLayout>+ );+ },+};++// ─── Horizontal Labels ────────────────────────────────────────────────────++export const HorizontalLabels: Story = {+ name: 'Horizontal Labels (Settings)',+ args: {+ direction: 'horizontal-labels',+ },+ render: args => {+ const [displayName, setDisplayName] = useState('Jane Doe');+ const [email, setEmail] = useState('[email protected]');+ const [timezone, setTimezone] = useState('America/Los_Angeles');+ return (+ <XDSFormLayout direction={args.direction}>+ <XDSTextInput+ label="Display Name"+ value={displayName}+ onChange={setDisplayName}+ />+ <XDSTextInput label="Email" value={email} onChange={setEmail} />+ <XDSSelector+ label="Timezone"+ value={timezone}+ onChange={v => setTimezone(v as string)}+ items={[+ {label: 'Pacific Time', value: 'America/Los_Angeles'},+ {label: 'Eastern Time', value: 'America/New_York'},+ {label: 'UTC', value: 'UTC'},+ ]}+ />+ </XDSFormLayout>+ );+ },+};++// ─── Mixed: XDS inputs + XDSField-wrapped custom controls ─────────────────++const checkboxStyles = stylex.create({+ group: {+ display: 'flex',+ flexDirection: 'column',+ gap: 4,+ },+ label: {+ display: 'flex',+ alignItems: 'center',+ gap: 8,+ },+});++export const MixedControls: Story = {+ name: 'Mixed Controls',+ render: () => {+ const [name, setName] = useState('');+ const [role, setRole] = useState('viewer');+ return (+ <XDSFormLayout>+ <XDSTextInput label="Name" value={name} onChange={setName} />+ <XDSSelector+ label="Role"+ value={role}+ onChange={v => setRole(v as string)}+ items={[+ {label: 'Viewer', value: 'viewer'},+ {label: 'Editor', value: 'editor'},+ {label: 'Admin', value: 'admin'},+ ]}+ />+ <XDSField label="Notifications" inputID="notif-group">+ <div {...stylex.props(checkboxStyles.group)} id="notif-group">+ <label {...stylex.props(checkboxStyles.label)}>+ <input type="checkbox" defaultChecked /> Email+ </label>+ <label {...stylex.props(checkboxStyles.label)}>+ <input type="checkbox" /> SMS+ </label>+ <label {...stylex.props(checkboxStyles.label)}>+ <input type="checkbox" defaultChecked /> Push+ </label>+ </div>+ </XDSField>+ </XDSFormLayout>+ );+ },+};++// ─── Nested Layouts ───────────────────────────────────────────────────────++export const Nested: Story = {+ name: 'Nested Layouts',+ render: () => {+ const [first, setFirst] = useState('');+ const [last, setLast] = useState('');+ const [email, setEmail] = useState('');+ const [city, setCity] = useState('');+ const [state, setState] = useState('');+ const [zip, setZip] = useState('');+ return (+ <XDSFormLayout>+ <XDSFormLayout direction="horizontal">+ <XDSTextInput label="First Name" value={first} onChange={setFirst} />+ <XDSTextInput label="Last Name" value={last} onChange={setLast} />+ </XDSFormLayout>+ <XDSTextInput label="Email" value={email} onChange={setEmail} />+ <XDSFormLayout direction="horizontal">+ <XDSTextInput label="City" value={city} onChange={setCity} />+ <XDSTextInput label="State" value={state} onChange={setState} />+ <XDSTextInput label="ZIP" value={zip} onChange={setZip} />+ </XDSFormLayout>+ </XDSFormLayout>+ );+ },+};++// ─── In a Dialog (form attribute pattern) ─────────────────────────────────++const dialogStyles = stylex.create({+ container: {+ border: '1px solid #ddd',+ borderRadius: 8,+ maxWidth: 480,+ overflow: 'hidden',+ },+ header: {+ padding: 16,+ borderBottom: '1px solid #eee',+ },+ body: {+ padding: 16,+ },+ footer: {+ display: 'flex',+ justifyContent: 'flex-end',+ gap: 8,+ padding: 16,+ borderTop: '1px solid #eee',+ },+ button: {+ padding: '8px 16px',+ borderRadius: 6,+ border: 'none',+ cursor: 'pointer',+ fontSize: 14,+ },+ primary: {+ backgroundColor: '#0064E0',+ color: '#fff',+ },+ secondary: {+ backgroundColor: '#F1F4F7',+ color: '#0A1317',+ },+});++export const InDialog: Story = {+ name: 'In a Dialog',+ render: () => {+ const [name, setName] = useState('Jane Doe');+ const [email, setEmail] = useState('[email protected]');+ return (+ <div {...stylex.props(dialogStyles.container)}>+ <div {...stylex.props(dialogStyles.header)}>+ <XDSText variant="subtitle">Edit Profile</XDSText>+ </div>+ <div {...stylex.props(dialogStyles.body)}>+ <form+ id="edit-profile"+ onSubmit={e => {+ e.preventDefault();+ alert(`Saved: ${name}, ${email}`);+ }}>+ <XDSFormLayout>+ <XDSTextInput label="Name" value={name} onChange={setName} />+ <XDSTextInput label="Email" value={email} onChange={setEmail} />+ </XDSFormLayout>+ </form>+ </div>+ <div {...stylex.props(dialogStyles.footer)}>+ <button+ {...stylex.props(dialogStyles.button, dialogStyles.secondary)}+ type="button">+ Cancel+ </button>+ <button+ {...stylex.props(dialogStyles.button, dialogStyles.primary)}+ type="submit"+ form="edit-profile">+ Save+ </button>+ </div>+ </div>+ );+ },+};diff --git a/packages/core/src/FormLayout/README.md b/packages/core/src/FormLayout/README.mdnew file mode 100644index 0000000000..a25fbc17c5--- /dev/null+++ b/packages/core/src/FormLayout/README.md@@ -0,0 +1,129 @@+# FormLayout++A spatial layout container for arranging form fields with consistent spacing and direction.++<!-- SYNC: When files in this directory change, update this document. -->++## Features++- **Three Layout Modes**: Vertical (default), horizontal, and horizontal-labels+- **Direction Context**: Provides layout direction to children via React context+- **Responsive**: Horizontal-labels collapses to vertical on narrow viewports (≤480px)+- **Nestable**: FormLayout inside FormLayout works naturally — inner overrides context+- **Purely Spatial**: Does not manage form state or render `<form>` — form submission is separate+- **Styled with StyleX**: Uses XDS design tokens for consistent spacing++## Components++### XDSFormLayout++Arranges form fields with consistent spacing and direction.++```tsx+<XDSFormLayout direction="vertical">+ <XDSTextInput label="Name" value={name} onChange={setName} />+ <XDSTextInput label="Email" value={email} onChange={setEmail} />+</XDSFormLayout>+```++| Prop | Type | Default | Description |+| ------------- | --------------------------------------------------- | ------------ | -------------------------------------- |+| `direction` | `'vertical' \| 'horizontal' \| 'horizontal-labels'` | `'vertical'` | Direction of field arrangement |+| `children` | `ReactNode` | — | Form fields to arrange |+| `xstyle` | `StyleXStyles` | — | StyleX styles for the layout container |+| `data-testid` | `string` | — | Test ID for the root element |+| `ref` | `Ref<HTMLDivElement>` | — | Ref to the root div element |++Also accepts standard HTML `div` attributes (`id`, `role`, `aria-*`, etc.).++## Layout Modes++### Vertical (default)++Fields stack top-to-bottom with consistent gap. Most common pattern for simple forms and dialogs.++```tsx+<XDSFormLayout>+ <XDSTextInput label="Name" ... />+ <XDSTextInput label="Email" ... />+</XDSFormLayout>+```++### Horizontal++Fields arrange left-to-right, each getting equal flex-grow. Wraps when the container is too narrow. Used for related fields (first/last name, city/state/zip).++```tsx+<XDSFormLayout direction="horizontal">+ <XDSTextInput label="First Name" ... />+ <XDSTextInput label="Last Name" ... />+</XDSFormLayout>+```++### Horizontal Labels++CSS Grid layout with labels to the left of inputs. Collapses to vertical on narrow viewports (≤480px). Used for settings panels and admin forms.++```tsx+<XDSFormLayout direction="horizontal-labels">+ <XDSTextInput label="Display Name" ... />+ <XDSSelector label="Timezone" ... />+</XDSFormLayout>+```++## Composition Patterns++### Nesting++```tsx+<XDSFormLayout direction="vertical">+ <XDSFormLayout direction="horizontal">+ <XDSTextInput label="First Name" ... />+ <XDSTextInput label="Last Name" ... />+ </XDSFormLayout>+ <XDSTextInput label="Email" ... />+</XDSFormLayout>+```++### With Custom Controls++Use `XDSField` to wrap custom controls that need labels:++```tsx+<XDSFormLayout>+ <XDSTextInput label="Name" ... />+ <XDSField label="Permissions" inputID="perms">+ <CheckboxGroup id="perms" ... />+ </XDSField>+</XDSFormLayout>+```++### Dialog Composition++FormLayout does not include buttons. In dialogs, connect buttons via the HTML `form` attribute:++```tsx+<XDSDialog>+ <form id="edit-form" onSubmit={handleSubmit}>+ <XDSFormLayout>+ <XDSTextInput label="Name" ... />+ </XDSFormLayout>+ </form>+ <XDSDialogFooter>+ <XDSButton label="Save" type="submit" form="edit-form" />+ </XDSDialogFooter>+</XDSDialog>+```++## Context++`XDSFormLayoutContext` provides `{ direction: XDSFormLayoutDirection }` to children. Import from `@xds/core/FormLayout` to read the current layout direction in custom components.++## Files++| File | Role | Purpose |+| ------------------------- | ------- | --------------------------- |+| `index.ts` | Entry | Exports component and types |+| `XDSFormLayout.tsx` | Core | Component implementation |+| `XDSFormLayoutContext.ts` | Context | Direction context |+| `XDSFormLayout.test.tsx` | Test | Unit tests |diff --git a/packages/core/src/FormLayout/XDSFormLayout.test.tsx b/packages/core/src/FormLayout/XDSFormLayout.test.tsxnew file mode 100644index 0000000000..39799da0f8--- /dev/null+++ b/packages/core/src/FormLayout/XDSFormLayout.test.tsx@@ -0,0 +1,185 @@+/**+ * @file XDSFormLayout.test.tsx+ * @input Uses vitest, @testing-library/react, XDSFormLayout component+ * @output Unit tests for XDSFormLayout component behavior+ * @position Testing; validates XDSFormLayout.tsx implementation+ *+ * SYNC: When XDSFormLayout.tsx changes, update tests to match new behavior+ */++import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {useContext} from 'react';+import {XDSFormLayout} from './XDSFormLayout';+import {XDSFormLayoutContext} from './XDSFormLayoutContext';+import type {XDSFormLayoutDirection} from './XDSFormLayoutContext';++// Helper component to read context+function DirectionReader() {+ const {direction} = useContext(XDSFormLayoutContext);+ return <span data-testid="direction">{direction}</span>;+}++describe('XDSFormLayout', () => {+ // ─── Basic rendering ────────────────────────────────────────────────────++ it('renders children', () => {+ render(+ <XDSFormLayout>+ <input data-testid="child" />+ </XDSFormLayout>,+ );+ expect(screen.getByTestId('child')).toBeInTheDocument();+ });++ it('renders a div element', () => {+ render(<XDSFormLayout data-testid="layout">content</XDSFormLayout>);+ const el = screen.getByTestId('layout');+ expect(el.tagName).toBe('DIV');+ });++ it('forwards ref', () => {+ const ref = {current: null as HTMLDivElement | null};+ render(<XDSFormLayout ref={ref}>content</XDSFormLayout>);+ expect(ref.current).toBeInstanceOf(HTMLDivElement);+ });++ it('passes data-testid', () => {+ render(<XDSFormLayout data-testid="my-form">content</XDSFormLayout>);+ expect(screen.getByTestId('my-form')).toBeInTheDocument();+ });++ it('passes through HTML attributes', () => {+ render(+ <XDSFormLayout data-testid="layout" id="form-1" role="group">+ content+ </XDSFormLayout>,+ );+ const el = screen.getByTestId('layout');+ expect(el).toHaveAttribute('id', 'form-1');+ expect(el).toHaveAttribute('role', 'group');+ });++ // ─── Direction modes ────────────────────────────────────────────────────++ it('defaults to vertical direction', () => {+ render(+ <XDSFormLayout data-testid="layout">+ <DirectionReader />+ </XDSFormLayout>,+ );+ expect(screen.getByTestId('direction')).toHaveTextContent('vertical');+ });++ it('supports horizontal direction', () => {+ render(+ <XDSFormLayout direction="horizontal" data-testid="layout">+ <DirectionReader />+ </XDSFormLayout>,+ );+ expect(screen.getByTestId('direction')).toHaveTextContent('horizontal');+ });++ it('supports horizontal-labels direction', () => {+ render(+ <XDSFormLayout direction="horizontal-labels" data-testid="layout">+ <DirectionReader />+ </XDSFormLayout>,+ );+ expect(screen.getByTestId('direction')).toHaveTextContent(+ 'horizontal-labels',+ );+ });++ // ─── Context propagation ────────────────────────────────────────────────++ it('provides direction context to children', () => {+ const directions: XDSFormLayoutDirection[] = [+ 'vertical',+ 'horizontal',+ 'horizontal-labels',+ ];++ for (const dir of directions) {+ const {unmount} = render(+ <XDSFormLayout direction={dir}>+ <DirectionReader />+ </XDSFormLayout>,+ );+ expect(screen.getByTestId('direction')).toHaveTextContent(dir);+ unmount();+ }+ });++ it('provides default context when no direction is specified', () => {+ render(+ <XDSFormLayout>+ <DirectionReader />+ </XDSFormLayout>,+ );+ expect(screen.getByTestId('direction')).toHaveTextContent('vertical');+ });++ // ─── Nesting ────────────────────────────────────────────────────────────++ it('supports nesting — inner layout overrides context', () => {+ render(+ <XDSFormLayout direction="vertical" data-testid="outer">+ <XDSFormLayout direction="horizontal" data-testid="inner">+ <DirectionReader />+ </XDSFormLayout>+ </XDSFormLayout>,+ );+ // Inner context should be 'horizontal', not 'vertical'+ expect(screen.getByTestId('direction')).toHaveTextContent('horizontal');+ });++ it('renders nested layouts with different elements', () => {+ render(+ <XDSFormLayout data-testid="outer">+ <input data-testid="outer-child" />+ <XDSFormLayout direction="horizontal" data-testid="inner">+ <input data-testid="inner-child-1" />+ <input data-testid="inner-child-2" />+ </XDSFormLayout>+ </XDSFormLayout>,+ );+ expect(screen.getByTestId('outer')).toBeInTheDocument();+ expect(screen.getByTestId('inner')).toBeInTheDocument();+ expect(screen.getByTestId('outer-child')).toBeInTheDocument();+ expect(screen.getByTestId('inner-child-1')).toBeInTheDocument();+ expect(screen.getByTestId('inner-child-2')).toBeInTheDocument();+ });++ // ─── Snapshot tests ─────────────────────────────────────────────────────++ it('matches snapshot for vertical direction', () => {+ const {container} = render(+ <XDSFormLayout data-testid="layout">+ <input placeholder="Name" />+ <input placeholder="Email" />+ </XDSFormLayout>,+ );+ expect(container.firstChild).toMatchSnapshot();+ });++ it('matches snapshot for horizontal direction', () => {+ const {container} = render(+ <XDSFormLayout direction="horizontal" data-testid="layout">+ <input placeholder="First" />+ <input placeholder="Last" />+ </XDSFormLayout>,+ );+ expect(container.firstChild).toMatchSnapshot();+ });++ it('matches snapshot for horizontal-labels direction', () => {+ const {container} = render(+ <XDSFormLayout direction="horizontal-labels" data-testid="layout">+ <label>Name</label>+ <input placeholder="Name" />+ </XDSFormLayout>,+ );+ expect(container.firstChild).toMatchSnapshot();+ });+});diff --git a/packages/core/src/FormLayout/XDSFormLayout.tsx b/packages/core/src/FormLayout/XDSFormLayout.tsxnew file mode 100644index 0000000000..95b7ac452e--- /dev/null+++ b/packages/core/src/FormLayout/XDSFormLayout.tsx@@ -0,0 +1,162 @@+/**+ * @file XDSFormLayout.tsx+ * @input Uses React forwardRef, XDSFormLayoutContext, StyleX+ * @output Exports XDSFormLayout component and XDSFormLayoutProps+ * @position Core implementation; consumed by index.ts, tested by XDSFormLayout.test.tsx+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/FormLayout/README.md (props table, features, implementation notes)+ * - /packages/core/src/FormLayout/XDSFormLayout.test.tsx (tests for new/changed behavior)+ * - /packages/core/src/FormLayout/index.ts (exports if types change)+ * - /apps/storybook/stories/FormLayout.stories.tsx (storybook stories)+ */++import {forwardRef, useMemo, type HTMLAttributes, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {spacingVars} from '../theme/tokens.stylex';+import {+ XDSFormLayoutContext,+ type XDSFormLayoutDirection,+} from './XDSFormLayoutContext';++// =============================================================================+// Responsive breakpoint for horizontal-labels collapse+// =============================================================================++const HORIZONTAL_LABELS_COLLAPSE = '@media (max-width: 480px)';++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ base: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-4'],+ },+ horizontal: {+ flexDirection: 'row',+ flexWrap: 'wrap',+ },+ horizontalLabels: {+ display: 'grid',+ gridTemplateColumns: 'auto 1fr',+ gap: `${spacingVars['--spacing-3']} ${spacingVars['--spacing-4']}`,+ alignItems: 'start',+ [HORIZONTAL_LABELS_COLLAPSE]: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-4'],+ },+ },+});++// =============================================================================+// Props+// =============================================================================++export interface XDSFormLayoutProps extends Omit<+ HTMLAttributes<HTMLDivElement>,+ 'style' | 'className'+> {+ /**+ * Form fields to arrange. Accepts XDS inputs (XDSTextInput, XDSSelector, etc.)+ * and XDSField-wrapped custom controls.+ */+ children?: ReactNode;++ /**+ * Direction of field arrangement.+ *+ * - `'vertical'` — Fields stack top-to-bottom (default). Most common.+ * - `'horizontal'` — Fields arrange left-to-right, wrapping when needed.+ * Each child gets equal flex-grow.+ * - `'horizontal-labels'` — CSS Grid with labels to the left of inputs.+ * Collapses to vertical on narrow viewports (≤480px).+ *+ * @default 'vertical'+ */+ direction?: XDSFormLayoutDirection;++ /**+ * StyleX styles to apply to the layout container.+ */+ xstyle?: StyleXStyles;++ /**+ * Test ID for the root element.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Component+// =============================================================================++/**+ * Spatial layout container for form fields.+ *+ * Arranges form fields with consistent spacing and direction. Renders a `<div>`+ * (not a `<form>` — form submission is a separate concern). For label wrapping+ * of custom controls, use `XDSField` directly.+ *+ * Provides direction context to children via `XDSFormLayoutContext`.+ * Supports nesting — a horizontal layout inside a vertical layout works naturally.+ *+ * @example+ * ```tsx+ * // Vertical (default) — simple form+ * <XDSFormLayout>+ * <XDSTextInput label="Name" value={name} onChange={setName} />+ * <XDSTextInput label="Email" value={email} onChange={setEmail} />+ * </XDSFormLayout>+ *+ * // Horizontal — related fields side by side+ * <XDSFormLayout direction="horizontal">+ * <XDSTextInput label="First Name" value={first} onChange={setFirst} />+ * <XDSTextInput label="Last Name" value={last} onChange={setLast} />+ * </XDSFormLayout>+ *+ * // Horizontal labels — settings panel pattern+ * <XDSFormLayout direction="horizontal-labels">+ * <XDSTextInput label="Display Name" value={name} onChange={setName} />+ * <XDSSelector label="Timezone" value={tz} onChange={setTz} options={tzs} />+ * </XDSFormLayout>+ *+ * // Dialog composition via HTML form attribute+ * <form id="edit-form" onSubmit={handleSubmit}>+ * <XDSFormLayout>+ * <XDSTextInput label="Name" value={name} onChange={setName} />+ * </XDSFormLayout>+ * </form>+ * <XDSButton label="Save" type="submit" form="edit-form" />+ * ```+ */+export const XDSFormLayout = forwardRef<HTMLDivElement, XDSFormLayoutProps>(+ function XDSFormLayout(+ {children, direction = 'vertical', xstyle, ...props},+ ref,+ ) {+ const contextValue = useMemo(() => ({direction}), [direction]);++ return (+ <XDSFormLayoutContext.Provider value={contextValue}>+ <div+ ref={ref}+ {...stylex.props(+ styles.base,+ direction === 'horizontal' && styles.horizontal,+ direction === 'horizontal-labels' && styles.horizontalLabels,+ xstyle,+ )}+ {...props}>+ {children}+ </div>+ </XDSFormLayoutContext.Provider>+ );+ },+);++XDSFormLayout.displayName = 'XDSFormLayout';diff --git a/packages/core/src/FormLayout/XDSFormLayoutContext.ts b/packages/core/src/FormLayout/XDSFormLayoutContext.tsnew file mode 100644index 0000000000..77f44c5d47--- /dev/null+++ b/packages/core/src/FormLayout/XDSFormLayoutContext.ts@@ -0,0 +1,32 @@+/**+ * @file XDSFormLayoutContext.ts+ * @input Uses React createContext+ * @output Exports XDSFormLayoutContext and XDSFormLayoutDirection type+ * @position Context for form layout direction detection+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/FormLayout/README.md+ */++import {createContext} from 'react';++/**+ * Direction of form field arrangement.+ *+ * - `'vertical'` — Fields stack top-to-bottom (default). Most common.+ * - `'horizontal'` — Fields arrange left-to-right, wrapping when needed.+ * - `'horizontal-labels'` — Fields stack vertically but labels sit to the left+ * of their inputs (settings/admin panel pattern).+ */+export type XDSFormLayoutDirection =+ | 'vertical'+ | 'horizontal'+ | 'horizontal-labels';++/**+ * Context for detecting which form layout direction a component is rendered in.+ * Children can use this to adapt their rendering based on the parent layout.+ */+export const XDSFormLayoutContext = createContext<{+ direction: XDSFormLayoutDirection;+}>({direction: 'vertical'});diff --git a/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snap b/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snapnew file mode 100644index 0000000000..99f6e100bd--- /dev/null+++ b/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snap@@ -0,0 +1,46 @@+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html++exports[`XDSFormLayout > matches snapshot for horizontal direction 1`] = `+<div+ class="XDSFormLayout__styles.base x78zum5 x18g69wz XDSFormLayout__styles.horizontal x1q0g3np x1a02dak"+ data-style-src="@xds/core:src/FormLayout/XDSFormLayout.tsx:34; @xds/core:src/FormLayout/XDSFormLayout.tsx:39"+ data-testid="layout"+>+ <input+ placeholder="First"+ />+ <input+ placeholder="Last"+ />+</div>+`;++exports[`XDSFormLayout > matches snapshot for horizontal-labels direction 1`] = `+<div+ class="XDSFormLayout__styles.base xdt5ytf XDSFormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"+ data-style-src="@xds/core:src/FormLayout/XDSFormLayout.tsx:34; @xds/core:src/FormLayout/XDSFormLayout.tsx:43"+ data-testid="layout"+>+ <label>+ Name+ </label>+ <input+ placeholder="Name"+ />+</div>+`;++exports[`XDSFormLayout > matches snapshot for vertical direction 1`] = `+<div+ class="XDSFormLayout__styles.base x78zum5 xdt5ytf x18g69wz"+ data-style-src="@xds/core:src/FormLayout/XDSFormLayout.tsx:34"+ data-testid="layout"+>+ <input+ placeholder="Name"+ />+ <input+ placeholder="Email"+ />+</div>+`;diff --git a/packages/core/src/FormLayout/index.ts b/packages/core/src/FormLayout/index.tsnew file mode 100644index 0000000000..a391796edb--- /dev/null+++ b/packages/core/src/FormLayout/index.ts@@ -0,0 +1,14 @@+/**+ * @file index.ts+ * @input Uses XDSFormLayout, XDSFormLayoutContext+ * @output Re-exports public API for FormLayout+ * @position Entry point for FormLayout module+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/FormLayout/README.md+ */++export {XDSFormLayout} from './XDSFormLayout';+export type {XDSFormLayoutProps} from './XDSFormLayout';+export type {XDSFormLayoutDirection} from './XDSFormLayoutContext';+export {XDSFormLayoutContext} from './XDSFormLayoutContext';diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex b171d9d86f..5512c98f83 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -30,6 +30,7 @@ export * from './Stack';export * from './Switch';export * from './DateInput';export * from './Field';+export * from './FormLayout';export * from './Grid';export * from './Section';export * from './Selector';