@dashforge/tw 0.2.1-beta → 0.4.0-beta

package/src/components/Dialog/dialog.types.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from 'react';
+import type { DialogVariants } from './dialog.variants.js';
+
+/**
+ * Per-slot className overrides for `<Dialog>`. Mirrors the
+ * canonical TW slotProps shape: `{ slot?: { className?: string } }`.
+ */
+export interface DialogSlotProps {
+  overlay?: { className?: string };
+  content?: { className?: string };
+  title?: { className?: string };
+  description?: { className?: string };
+  closeButton?: { className?: string };
+  body?: { className?: string };
+  actions?: { className?: string };
+}
+
+/**
+ * Props for the declarative `<Dialog>` component.
+ *
+ * Built on `@radix-ui/react-dialog`. Use this when:
+ *  - You want full control over the dialog's open state (controlled
+ *    from a parent component).
+ *  - You want to mount a custom-styled dialog body / trigger that
+ *    composes with the rest of your component tree.
+ *  - You don't need an imperative `confirm()`-style return value
+ *    (use `useDialog()` or `useConfirm()` for those).
+ *
+ * Three size variants (`sm` / `md` / `lg`) with sensible defaults.
+ * Backdrop + content animations respect `prefers-reduced-motion`.
+ */
+export interface DialogProps extends Pick<DialogVariants, 'size'> {
+  /** Controlled open state. */
+  open: boolean;
+  /** Called when the dialog requests to change open state. */
+  onOpenChange: (open: boolean) => void;
+  /** Dialog body — usually a `<DialogContent>` subtree. */
+  children: ReactNode;
+  /** Dialog title (screen-reader announced via `aria-labelledby`). */
+  title?: ReactNode;
+  /** Dialog description (announced via `aria-describedby`). */
+  description?: ReactNode;
+  /**
+   * Show the `×` close button in the top-right corner.
+   * @default true
+   */
+  showCloseButton?: boolean;
+  /**
+   * Disable closing on backdrop click.
+   * @default false
+   */
+  disableBackdropClose?: boolean;
+  /**
+   * Disable closing on Escape key.
+   * @default false
+   */
+  disableEscapeClose?: boolean;
+  /** Root className shortcut on the content element. */
+  sx?: string;
+  /** Per-slot overrides. */
+  slotProps?: DialogSlotProps;
+}

package/src/components/Dialog/dialog.variants.ts

@@ -0,0 +1,62 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `<Dialog>` variant recipe.
+ *
+ * Slots:
+ *  - `overlay`  — backdrop (Radix's `DialogOverlay`)
+ *  - `content`  — the dialog box itself
+ *  - `title`    — heading at the top
+ *  - `description` — secondary text under the title
+ *  - `closeButton` — top-right `×` button
+ *  - `body`     — main scrollable area
+ *  - `actions`  — footer action bar
+ *
+ * Three sizes (`sm` / `md` / `lg`) drive the content max-width.
+ * Motion is gated by `prefers-reduced-motion` so the slide-in
+ * animation collapses to an instant appear on users that opt out.
+ */
+export const dialogVariants = tv({
+  slots: {
+    overlay: [
+      'fixed inset-0 z-50 bg-neutral-950/60 backdrop-blur-sm',
+      'data-[state=open]:animate-in data-[state=open]:fade-in-0',
+      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0',
+      'motion-reduce:transition-none motion-reduce:duration-0',
+    ],
+    content: [
+      'fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2',
+      'w-full bg-white dark:bg-neutral-900 rounded-lg shadow-xl',
+      'border border-neutral-200 dark:border-neutral-800',
+      'p-6 flex flex-col gap-4 max-h-[90vh]',
+      'focus:outline-none',
+      'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+      'motion-reduce:transition-none motion-reduce:duration-0',
+    ],
+    title: 'text-lg font-semibold leading-tight text-neutral-900 dark:text-neutral-50',
+    description: 'text-sm text-neutral-600 dark:text-neutral-400',
+    closeButton: [
+      'absolute top-4 right-4 inline-flex items-center justify-center',
+      'h-8 w-8 rounded-md text-neutral-500 hover:text-neutral-900',
+      'dark:text-neutral-400 dark:hover:text-neutral-50',
+      'hover:bg-neutral-100 dark:hover:bg-neutral-800',
+      'focus:outline-none focus:ring-2 focus:ring-primary-500',
+      'transition-colors',
+    ],
+    body: 'flex-1 overflow-y-auto',
+    actions: 'flex justify-end gap-2 pt-2',
+  },
+  variants: {
+    size: {
+      sm: { content: 'max-w-sm' },
+      md: { content: 'max-w-md' },
+      lg: { content: 'max-w-2xl' },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+});
+
+export type DialogVariants = VariantProps<typeof dialogVariants>;

package/src/components/LeftNav/leftNav.variants.ts

@@ -24,7 +24,10 @@ export const leftNavVariants = tv({
     root: [
       'flex flex-col h-full',
       'bg-neutral-50 border-r border-neutral-200',
-      'transition-[width] duration-200',
+      // Width transition (rail-mode toggle) — gated on
+      // prefers-reduced-motion (WCAG 2.3.3). The new width still
+      // applies, just without the animated tween.
+      'transition-[width] duration-200 motion-reduce:transition-none motion-reduce:duration-0',
     ],
     brand: [
       'flex items-center gap-2 px-3 h-14 shrink-0',
@@ -39,6 +42,14 @@ export const leftNavVariants = tv({
       'transition-colors w-full',
       'aria-disabled:opacity-50 aria-disabled:cursor-not-allowed',
       'aria-disabled:hover:bg-transparent',
+      // Defensive `no-underline` — Tailwind's preflight removes the
+      // default browser anchor underline globally, but environments
+      // that DISABLE preflight (e.g. our docs-lab, where the tw
+      // section coexists with MUI's chrome) get raw browser defaults
+      // back. Without this, `<a>` items in the nav render underlined
+      // in those contexts. Explicit `no-underline` + `hover:no-underline`
+      // keeps the appearance consistent regardless of preflight state.
+      'no-underline hover:no-underline',
     ],
     itemActive: 'bg-primary-100 text-primary-900 font-medium',
     itemIcon: 'shrink-0 w-5 h-5 flex items-center justify-center',

package/src/components/Popover/Popover.test.tsx

@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, afterEach, beforeAll } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+import { Popover } from './Popover.js';
+
+void React;
+afterEach(() => cleanup());
+
+// jsdom doesn't implement ResizeObserver — Radix Floating UI requires it.
+beforeAll(() => {
+  if (typeof globalThis.ResizeObserver === 'undefined') {
+    (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    };
+  }
+});
+
+describe('Popover — rendering', () => {
+  it('renders the trigger always', () => {
+    render(
+      <Popover content={<p>Panel</p>}>
+        <button>Open panel</button>
+      </Popover>
+    );
+    expect(screen.queryByRole('button', { name: 'Open panel' })).not.toBeNull();
+  });
+
+  it('renders content when controlled open=true', () => {
+    render(
+      <Popover content={<p>Panel content</p>} open onOpenChange={() => {}}>
+        <button>Open panel</button>
+      </Popover>
+    );
+    expect(screen.queryByText('Panel content')).not.toBeNull();
+  });
+
+  it('does not render content when open=false', () => {
+    render(
+      <Popover content={<p>Panel content</p>} open={false} onOpenChange={() => {}}>
+        <button>Open panel</button>
+      </Popover>
+    );
+    expect(screen.queryByText('Panel content')).toBeNull();
+  });
+});
+
+describe('Popover — placement', () => {
+  it.each(['top', 'right', 'bottom', 'left'] as const)(
+    'renders side=%s without crashing',
+    (side) => {
+      render(
+        <Popover content={<p>Panel</p>} open side={side} onOpenChange={() => {}}>
+          <button>T</button>
+        </Popover>
+      );
+      expect(screen.queryByText('Panel')).not.toBeNull();
+    }
+  );
+
+  it('applies width style', () => {
+    render(
+      <Popover content={<p>Panel</p>} open width="300px" onOpenChange={() => {}}>
+        <button>T</button>
+      </Popover>
+    );
+    const content = screen.getByText('Panel').closest('[role="dialog"]') as HTMLElement | null;
+    expect(content?.style.width).toBe('300px');
+  });
+});

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,55 @@
+import * as RadixPopover from '@radix-ui/react-popover';
+import { cn } from '../../utils/cn.js';
+import { popoverVariants } from './popover.variants.js';
+import type { PopoverProps } from './popover.types.js';
+
+/**
+ * Dashforge TW `<Popover>` — clickable floating content panel.
+ *
+ * Built on `@radix-ui/react-popover`:
+ *  - Focus trap inside the popover (Tab cycles within).
+ *  - Outside-click + Escape dismiss.
+ *  - APG dialog-like semantics (`role="dialog"` on content).
+ *  - Portal-rendered.
+ *
+ * Use `<Popover>` for menus / pickers / settings panels with
+ * interactive children. Use `<Tooltip>` for read-only hints.
+ */
+export function Popover(props: PopoverProps) {
+  const {
+    children,
+    content,
+    side = 'bottom',
+    align = 'center',
+    showArrow = false,
+    open,
+    onOpenChange,
+    sideOffset = 8,
+    width,
+    slotProps,
+  } = props;
+
+  const v = popoverVariants();
+
+  return (
+    <RadixPopover.Root open={open} onOpenChange={onOpenChange}>
+      <RadixPopover.Trigger asChild>{children}</RadixPopover.Trigger>
+      <RadixPopover.Portal>
+        <RadixPopover.Content
+          side={side}
+          align={align}
+          sideOffset={sideOffset}
+          style={width != null ? { width } : undefined}
+          className={cn(v.content(), slotProps?.content?.className)}
+        >
+          {content}
+          {showArrow && (
+            <RadixPopover.Arrow
+              className={cn(v.arrow(), slotProps?.arrow?.className)}
+            />
+          )}
+        </RadixPopover.Content>
+      </RadixPopover.Portal>
+    </RadixPopover.Root>
+  );
+}

package/src/components/Popover/popover.types.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+
+export interface PopoverSlotProps {
+  content?: { className?: string };
+  arrow?: { className?: string };
+}
+
+/**
+ * Props for `<Popover>`.
+ *
+ * Built on `@radix-ui/react-popover`. Use for richer floating UI
+ * than a tooltip — e.g. action menus, color pickers, settings
+ * panels.
+ *
+ * Differences vs `<Tooltip>`:
+ *  - Popover is **clickable** and captures focus inside (focus trap).
+ *  - Popover supports arbitrary interactive content (forms, buttons).
+ *  - Popover dismisses on outside-click / Escape (Radix-managed).
+ *  - No `role="tooltip"` — popovers are conceptually mini-dialogs.
+ */
+export interface PopoverProps {
+  /** The trigger element (wrapped in Radix's `asChild` slot). */
+  children: ReactNode;
+  /** Popover body content. */
+  content: ReactNode;
+  /** Side of the trigger to render on. @default 'bottom' */
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  /** Alignment along the perpendicular axis. @default 'center' */
+  align?: 'start' | 'center' | 'end';
+  /** Show an arrow indicator. @default false */
+  showArrow?: boolean;
+  /** Controlled open state. */
+  open?: boolean;
+  /** Called when open state changes. */
+  onOpenChange?: (open: boolean) => void;
+  /** Side offset in pixels. @default 8 */
+  sideOffset?: number;
+  /** Width of the popover content. CSS value. */
+  width?: string;
+  /** Per-slot overrides. */
+  slotProps?: PopoverSlotProps;
+}

package/src/components/Popover/popover.variants.ts

@@ -0,0 +1,18 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+export const popoverVariants = tv({
+  slots: {
+    content: [
+      'z-50 rounded-md border border-neutral-200 dark:border-neutral-800',
+      'bg-white dark:bg-neutral-900 p-4 shadow-lg',
+      'text-sm text-neutral-900 dark:text-neutral-50',
+      'focus:outline-none',
+      'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+      'motion-reduce:transition-none motion-reduce:duration-0',
+    ],
+    arrow: 'fill-white dark:fill-neutral-900',
+  },
+});
+
+export type PopoverVariants = VariantProps<typeof popoverVariants>;

package/src/components/Snackbar/snackbar.variants.ts

@@ -23,8 +23,10 @@ export const snackbarVariants = tv({
       'rounded-lg border shadow-lg',
       'text-sm bg-neutral-50 text-neutral-900',
       // Subtle enter transition — opacity + translate, kept short so a
-      // burst of snackbars feels snappy.
-      'transition-all duration-200',
+      // burst of snackbars feels snappy. Gated on motion-reduce
+      // (WCAG 2.3.3) — users who request reduced motion see snackbars
+      // pop in instantly without the slide animation.
+      'transition-all duration-200 motion-reduce:transition-none motion-reduce:duration-0',
       'data-[state=entered]:opacity-100 data-[state=exited]:opacity-0',
     ],
     icon: 'shrink-0 mt-0.5 w-5 h-5 inline-flex items-center justify-center',

package/src/components/Switch/switch.variants.ts

@@ -25,7 +25,12 @@ export const switchVariants = tv({
     ],
     thumb: [
       'pointer-events-none inline-block rounded-full bg-white shadow ring-0',
-      'transition-transform',
+      // Slide animation gated on `prefers-reduced-motion: no-preference`
+      // (WCAG 2.3.3). The thumb still moves between positions instantly
+      // for users who request reduced motion — the data-state change
+      // applies the translate-x rule unconditionally, only the smooth
+      // transition between the two is suppressed.
+      'transition-transform motion-reduce:transition-none',
       'data-[state=unchecked]:translate-x-0',
     ],
     label: 'select-none cursor-pointer text-neutral-900',

package/src/components/Tabs/Tabs.test.tsx

@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import { Tabs } from './Tabs.js';
+
+void React;
+afterEach(() => cleanup());
+
+const items = [
+  { value: 'overview', label: 'Overview', content: <p>Overview body</p> },
+  { value: 'details', label: 'Details', content: <p>Details body</p> },
+  { value: 'history', label: 'History', content: <p>History body</p> },
+];
+
+describe('Tabs — rendering', () => {
+  it('renders all triggers and the default-active content', () => {
+    render(<Tabs items={items} />);
+    expect(screen.queryByRole('tab', { name: 'Overview' })).not.toBeNull();
+    expect(screen.queryByRole('tab', { name: 'Details' })).not.toBeNull();
+    expect(screen.queryByRole('tab', { name: 'History' })).not.toBeNull();
+    // Only the active panel renders content (others get data-state="inactive").
+    expect(screen.queryByText('Overview body')).not.toBeNull();
+  });
+
+  it('honors `defaultValue`', () => {
+    render(<Tabs items={items} defaultValue="history" />);
+    expect(screen.queryByText('History body')).not.toBeNull();
+  });
+
+  it('switches active panel via controlled `value` rerender', () => {
+    const { rerender } = render(
+      <Tabs items={items} value="overview" onValueChange={() => {}} />
+    );
+    expect(screen.queryByText('Overview body')).not.toBeNull();
+    rerender(<Tabs items={items} value="details" onValueChange={() => {}} />);
+    expect(screen.queryByText('Details body')).not.toBeNull();
+  });
+
+  it('marks the active tab via aria-selected', () => {
+    render(<Tabs items={items} defaultValue="details" />);
+    const detailsTab = screen.getByRole('tab', { name: 'Details' });
+    expect(detailsTab.getAttribute('aria-selected')).toBe('true');
+    const overviewTab = screen.getByRole('tab', { name: 'Overview' });
+    expect(overviewTab.getAttribute('aria-selected')).toBe('false');
+  });
+});
+
+void fireEvent; // imported for parity but not needed after the controlled-mode simplification
+
+describe('Tabs — variants', () => {
+  it.each(['underline', 'pill'] as const)('renders variant=%s', (variant) => {
+    render(<Tabs items={items} variant={variant} />);
+    expect(screen.queryByRole('tablist')).not.toBeNull();
+  });
+
+  it.each(['horizontal', 'vertical'] as const)('renders orientation=%s', (o) => {
+    render(<Tabs items={items} orientation={o} />);
+    const list = screen.getByRole('tablist');
+    expect(list.getAttribute('aria-orientation')).toBe(o);
+  });
+});
+
+describe('Tabs — disabled items', () => {
+  it('marks disabled triggers as disabled', () => {
+    const disabledItems = [
+      ...items.slice(0, 2),
+      { ...items[2]!, disabled: true },
+    ];
+    render(<Tabs items={disabledItems} />);
+    const trigger = screen.getByRole('tab', { name: 'History' }) as HTMLButtonElement;
+    expect(trigger.disabled).toBe(true);
+  });
+});

package/src/components/Tabs/Tabs.tsx

@@ -0,0 +1,66 @@
+import * as RadixTabs from '@radix-ui/react-tabs';
+import { cn } from '../../utils/cn.js';
+import { tabsVariants } from './tabs.variants.js';
+import type { TabsProps } from './tabs.types.js';
+
+/**
+ * Dashforge TW `<Tabs>` — declarative tab navigation.
+ *
+ * Built on `@radix-ui/react-tabs`:
+ *  - APG tabs pattern (arrow-key navigation, automatic activation,
+ *    `role="tablist"` + `role="tab"` + `role="tabpanel"`).
+ *  - Controlled / uncontrolled (`value` / `defaultValue`).
+ *
+ * Two variant axes:
+ *  - `variant` — `underline` (default) | `pill`
+ *  - `orientation` — `horizontal` (default) | `vertical`
+ */
+export function Tabs(props: TabsProps) {
+  const {
+    items,
+    value,
+    defaultValue,
+    onValueChange,
+    variant = 'underline',
+    orientation = 'horizontal',
+    sx,
+    slotProps,
+  } = props;
+
+  const v = tabsVariants({ variant, orientation });
+  const resolvedDefault = defaultValue ?? items[0]?.value;
+
+  return (
+    <RadixTabs.Root
+      value={value}
+      defaultValue={resolvedDefault}
+      onValueChange={onValueChange}
+      orientation={orientation}
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+    >
+      <RadixTabs.List
+        className={cn(v.list(), slotProps?.list?.className)}
+      >
+        {items.map((item) => (
+          <RadixTabs.Trigger
+            key={item.value}
+            value={item.value}
+            disabled={item.disabled}
+            className={cn(v.trigger(), slotProps?.trigger?.className)}
+          >
+            {item.label}
+          </RadixTabs.Trigger>
+        ))}
+      </RadixTabs.List>
+      {items.map((item) => (
+        <RadixTabs.Content
+          key={item.value}
+          value={item.value}
+          className={cn(v.content(), slotProps?.content?.className)}
+        >
+          {item.content}
+        </RadixTabs.Content>
+      ))}
+    </RadixTabs.Root>
+  );
+}

package/src/components/Tabs/tabs.types.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+import type { TabsVariants } from './tabs.variants.js';
+
+export interface TabsSlotProps {
+  root?: { className?: string };
+  list?: { className?: string };
+  trigger?: { className?: string };
+  content?: { className?: string };
+}
+
+/**
+ * Single tab item — paired `{ value, label, content }`. The `value`
+ * is the canonical id (selected via the `value` / `defaultValue`
+ * props on the root); the `label` is the trigger button text, and
+ * `content` is what renders in the panel when this tab is active.
+ */
+export interface TabItem {
+  value: string;
+  label: ReactNode;
+  /** Tab panel content. */
+  content: ReactNode;
+  /** Per-tab disabled flag. */
+  disabled?: boolean;
+}
+
+/**
+ * Props for `<Tabs>`.
+ *
+ * Built on `@radix-ui/react-tabs`. Two variant axes:
+ *  - `variant` — `underline` (default) | `pill`
+ *  - `orientation` — `horizontal` (default) | `vertical`
+ *
+ * Supports controlled (`value` + `onValueChange`) and uncontrolled
+ * (`defaultValue`) modes — the `value` prop wins when both are set.
+ */
+export interface TabsProps extends TabsVariants {
+  /** Tab items array (declarative — alternative to passing children). */
+  items: TabItem[];
+  /** Controlled active value. */
+  value?: string;
+  /** Default active value (uncontrolled). Defaults to first item's value. */
+  defaultValue?: string;
+  /** Fires when the active tab changes. */
+  onValueChange?: (value: string) => void;
+  /** Root className shortcut. */
+  sx?: string;
+  /** Per-slot overrides. */
+  slotProps?: TabsSlotProps;
+}

package/src/components/Tabs/tabs.variants.ts

@@ -0,0 +1,58 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+export const tabsVariants = tv({
+  slots: {
+    root: 'flex',
+    list: 'inline-flex items-center gap-1',
+    trigger: [
+      'inline-flex items-center justify-center whitespace-nowrap',
+      'text-sm font-medium transition-colors',
+      'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+      'disabled:opacity-50 disabled:pointer-events-none',
+      'motion-reduce:transition-none',
+    ],
+    content: [
+      'mt-3 focus:outline-none',
+      'data-[state=inactive]:hidden',
+    ],
+  },
+  variants: {
+    variant: {
+      underline: {
+        list: 'border-b border-neutral-200 dark:border-neutral-800',
+        trigger: [
+          'px-3 py-2 border-b-2 border-transparent text-neutral-600 dark:text-neutral-400',
+          'hover:text-neutral-900 dark:hover:text-neutral-50',
+          'data-[state=active]:border-primary-500 data-[state=active]:text-primary-700',
+          'dark:data-[state=active]:text-primary-400',
+        ],
+      },
+      pill: {
+        list: 'rounded-lg bg-neutral-100 dark:bg-neutral-800 p-1',
+        trigger: [
+          'px-3 py-1.5 rounded-md text-neutral-600 dark:text-neutral-400',
+          'hover:text-neutral-900 dark:hover:text-neutral-50',
+          'data-[state=active]:bg-white dark:data-[state=active]:bg-neutral-900',
+          'data-[state=active]:text-neutral-900 dark:data-[state=active]:text-neutral-50',
+          'data-[state=active]:shadow-sm',
+        ],
+      },
+    },
+    orientation: {
+      horizontal: {
+        root: 'flex-col',
+        list: 'flex-row',
+      },
+      vertical: {
+        root: 'flex-row gap-4',
+        list: 'flex-col items-stretch',
+      },
+    },
+  },
+  defaultVariants: {
+    variant: 'underline',
+    orientation: 'horizontal',
+  },
+});
+
+export type TabsVariants = VariantProps<typeof tabsVariants>;

package/src/components/TextField/TextField.tsx

@@ -178,6 +178,22 @@ export function TextField(props: TextFieldProps) {
       )}
 
       <div className={cn(v.inputWrapper(), slotProps?.inputWrapper?.className)}>
+        {/*
+         * Prefix slot (Sprint 2 P4.1) — inline adornment rendered
+         * BEFORE the input. Mounts only when `slotProps.prefix.children`
+         * is provided so empty configs don't add layout cost. Common
+         * use: currency symbols (`$`, `€`), units (`@`, `#`), status
+         * icons. The slot wrapper carries `pointer-events-none` to
+         * avoid stealing focus from the input on click.
+         */}
+        {slotProps?.prefix?.children !== undefined && (
+          <span
+            aria-hidden="true"
+            className={cn(v.prefix(), slotProps.prefix.className)}
+          >
+            {slotProps.prefix.children}
+          </span>
+        )}
         <input
           {...rest}
           id={inputId}
@@ -196,6 +212,19 @@ export function TextField(props: TextFieldProps) {
           ref={inputRef}
           className={cn(v.input(), slotProps?.input?.className)}
         />
+        {/*
+         * Suffix slot (Sprint 2 P4.1) — same pattern as prefix,
+         * rendered AFTER the input. Typical use: unit labels (`USD`,
+         * `kg`, `%`), trailing icons, length counters.
+         */}
+        {slotProps?.suffix?.children !== undefined && (
+          <span
+            aria-hidden="true"
+            className={cn(v.suffix(), slotProps.suffix.className)}
+          >
+            {slotProps.suffix.children}
+          </span>
+        )}
       </div>
 
       {resolvedHelperText && (