@vendure-io/ui 1.3.0 → 2.0.0-beta.1

package/src/components/molecules/password-input.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from '@vendure-io/ui/components/atoms/input-group';
+import { Eye, EyeOff } from 'lucide-react';
+import * as React from 'react';
+
+export interface PasswordInputProps extends Omit<React.ComponentProps<'input'>, 'type'> {
+  /** Accessible label for the reveal toggle while the password is hidden. */
+  showPasswordLabel?: string;
+  /** Accessible label for the reveal toggle while the password is shown. */
+  hidePasswordLabel?: string;
+}
+
+/**
+ * A password field with a show/hide toggle, composed from the InputGroup atoms.
+ * Toggle labels are props so consumers can localize them — the design system
+ * carries no i18n runtime of its own.
+ */
+function PasswordInput({
+  showPasswordLabel = 'Show password',
+  hidePasswordLabel = 'Hide password',
+  ...props
+}: PasswordInputProps) {
+  const [showPassword, setShowPassword] = React.useState(false);
+
+  return (
+    <InputGroup>
+      <InputGroupInput type={showPassword ? 'text' : 'password'} {...props} />
+      <InputGroupAddon align="inline-end">
+        <InputGroupButton
+          size="icon-xs"
+          onClick={() => setShowPassword((prev) => !prev)}
+          aria-label={showPassword ? hidePasswordLabel : showPasswordLabel}
+        >
+          {showPassword ? <EyeOff /> : <Eye />}
+        </InputGroupButton>
+      </InputGroupAddon>
+    </InputGroup>
+  );
+}
+
+export { PasswordInput };

package/src/components/molecules/relative-time.tsx

@@ -0,0 +1,81 @@
+'use client';
+
+import { useFormatSettings } from '@vendure-io/ui/components/molecules/format-provider';
+import { type FormatRelativeOptions, formatRelative } from '@vendure-io/ui/lib/format-relative';
+import { type ComponentProps, type ReactNode, useEffect, useState } from 'react';
+
+function toDate(value: string | number | Date | null | undefined): Date | null {
+  if (value === null || value === undefined) return null;
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+interface RelativeTimeProps extends Omit<ComponentProps<'time'>, 'dateTime'> {
+  value: string | number | Date | null | undefined;
+  locale?: string;
+  numeric?: 'auto' | 'always';
+  unitStyle?: Intl.RelativeTimeFormatOptions['style'];
+  /**
+   * Self-refresh cadence in ms so a long-open view ages "just now" → "2 minutes
+   * ago". Default `60_000`. Pass `false` to disable the timer when the caller
+   * already re-renders (e.g. a polling query drives it).
+   */
+  updateInterval?: number | false;
+  /** Rendered for nullish/invalid input. Default `'—'`. */
+  fallback?: ReactNode;
+}
+
+/**
+ * SSR note: output is time- and locale-dependent, so the server render and the
+ * first client render can disagree. The `<time>` carries
+ * `suppressHydrationWarning` and re-formats once right after mount; SSR
+ * consumers should still pin `locale`/`timeZone` via `FormatProvider` (or
+ * props) so the absolute `title` matches too.
+ */
+function RelativeTime({
+  value,
+  locale,
+  numeric,
+  unitStyle,
+  updateInterval = 60_000,
+  fallback = '—',
+  ...props
+}: RelativeTimeProps) {
+  const settings = useFormatSettings();
+  // A bare counter to force a re-format on each tick; the value itself is unused.
+  const [, tick] = useState(0);
+
+  const date = toDate(value);
+  const hasDate = date !== null;
+
+  useEffect(() => {
+    if (!hasDate) return;
+    // SSR'd text can already be stale by the time hydration runs, so re-format
+    // once immediately — this also covers `updateInterval={false}`, which
+    // otherwise never refreshes on its own.
+    tick((n) => n + 1);
+    if (updateInterval === false) return;
+    const id = setInterval(() => tick((n) => n + 1), updateInterval);
+    return () => clearInterval(id);
+  }, [updateInterval, hasDate]);
+
+  if (!date) return <>{fallback}</>;
+
+  const resolvedLocale = locale ?? settings.locale;
+
+  return (
+    <time
+      data-slot="relative-time"
+      dateTime={date.toISOString()}
+      title={date.toLocaleString(resolvedLocale, { timeZone: settings.timeZone })}
+      suppressHydrationWarning
+      {...props}
+    >
+      {formatRelative(date, { locale: resolvedLocale, numeric, unitStyle })}
+    </time>
+  );
+}
+
+// Re-exported so the spike's import surface (molecules/relative-time) keeps
+// working; the implementation lives in lib/ per the JSX-or-lib rule.
+export { RelativeTime, formatRelative, type RelativeTimeProps, type FormatRelativeOptions };

package/src/components/molecules/stat-card.tsx

@@ -0,0 +1,134 @@
+import { Card, CardAction, CardContent, CardHeader } from '@vendure-io/ui/components/atoms/card';
+import { Skeleton } from '@vendure-io/ui/components/atoms/skeleton';
+import { cva } from 'class-variance-authority';
+import { ArrowDown, ArrowUp } from 'lucide-react';
+import type { ComponentProps, ReactNode } from 'react';
+
+// Delta tone follows consequence, not direction: `goodWhen` says which way is
+// good for this metric (revenue up vs. refund-rate down), and the token is
+// derived from that — never a hardcoded green/red. Per ADR 0003: good →
+// success, bad → destructive, flat → muted.
+const statCardDeltaVariants = cva('inline-flex items-center gap-0.5 text-xs font-medium', {
+  variants: {
+    tone: {
+      good: 'text-success',
+      bad: 'text-destructive',
+      flat: 'text-muted-foreground',
+    },
+  },
+  defaultVariants: {
+    tone: 'flat',
+  },
+});
+
+interface StatCardDelta {
+  /** Raw percentage change, e.g. `-3.2`. Sign drives the arrow and tone. */
+  value: number;
+  /** Suffix after the number. Default `'%'`. */
+  label?: string;
+  /** Which direction is a good outcome for this metric. Default `'up'`. */
+  goodWhen?: 'up' | 'down';
+}
+
+interface StatCardProps extends ComponentProps<typeof Card> {
+  label: ReactNode;
+  /** Pre-formatted display value — pass `<Money>`, `<AnimatedNumber>`, a string. */
+  value: ReactNode;
+  /** Secondary line, e.g. "vs. previous period". */
+  description?: ReactNode;
+  icon?: ReactNode;
+  delta?: StatCardDelta;
+  /** Optional sparkline/chart slot. */
+  chart?: ReactNode;
+  isLoading?: boolean;
+  /** Header-right slot, e.g. a menu or timeframe select. */
+  action?: ReactNode;
+}
+
+function StatCardDeltaBadge({ value, label = '%', goodWhen = 'up' }: StatCardDelta) {
+  const direction = value > 0 ? 'up' : value < 0 ? 'down' : 'flat';
+  const tone = direction === 'flat' ? 'flat' : direction === goodWhen ? 'good' : 'bad';
+
+  return (
+    <span data-slot="stat-card-delta" className={statCardDeltaVariants({ tone })}>
+      {direction === 'up' ? (
+        <ArrowUp aria-hidden="true" className="size-3" />
+      ) : direction === 'down' ? (
+        <ArrowDown aria-hidden="true" className="size-3" />
+      ) : null}
+      {/* Math.abs strips the sign and the arrow is visual-only, so screen
+          readers need the direction spelled out. */}
+      {direction !== 'flat' ? (
+        <span className="sr-only">{direction === 'up' ? 'up' : 'down'} </span>
+      ) : null}
+      {Math.abs(value).toFixed(1)}
+      {label}
+    </span>
+  );
+}
+
+function StatCard({
+  label,
+  value,
+  description,
+  icon,
+  delta,
+  chart,
+  isLoading = false,
+  action,
+  className,
+  ...props
+}: StatCardProps) {
+  if (isLoading) {
+    return (
+      <Card data-slot="stat-card" className={className} {...props}>
+        <CardHeader>
+          <Skeleton className="h-4 w-24" />
+        </CardHeader>
+        <CardContent className="flex flex-col gap-2">
+          <Skeleton className="h-8 w-32" />
+          <Skeleton className="h-4 w-40" />
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <Card data-slot="stat-card" className={className} {...props}>
+      <CardHeader>
+        <div
+          data-slot="stat-card-label"
+          className="text-muted-foreground flex items-center gap-1.5 text-sm font-medium [&_svg:not([class*='size-'])]:size-4"
+        >
+          {icon ? (
+            <span data-slot="stat-card-icon" className="inline-flex">
+              {icon}
+            </span>
+          ) : null}
+          {label}
+        </div>
+        {action ? <CardAction>{action}</CardAction> : null}
+      </CardHeader>
+      <CardContent className="flex flex-col gap-1">
+        <div className="flex items-baseline gap-2">
+          <span data-slot="stat-card-value" className="text-2xl font-semibold tabular-nums">
+            {value}
+          </span>
+          {delta ? <StatCardDeltaBadge {...delta} /> : null}
+        </div>
+        {description ? (
+          <p data-slot="stat-card-description" className="text-muted-foreground text-sm">
+            {description}
+          </p>
+        ) : null}
+        {chart ? (
+          <div data-slot="stat-card-chart" className="mt-2">
+            {chart}
+          </div>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}
+
+export { StatCard, statCardDeltaVariants, type StatCardProps, type StatCardDelta };

package/src/components/molecules/state-views/empty-state.tsx

@@ -0,0 +1,75 @@
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@vendure-io/ui/components/atoms/empty';
+import { EmptyCollectionIllustration } from '@vendure-io/ui/components/molecules/illustrations/empty-collection';
+import { cn } from '@vendure-io/ui/lib/utils';
+
+// `title` is redefined as `ReactNode`, so drop the native string `title` attr.
+export interface EmptyStateProps extends Omit<React.ComponentProps<typeof Empty>, 'title'> {
+  /** Leading icon element, rendered in the muted icon chip. Ignored once `illustration` renders (see below). */
+  icon?: React.ReactNode;
+  /**
+   * Illustration rendered above the title, in place of `icon`. Defaults to
+   * `EmptyCollectionIllustration`. Pass a different illustration to match the
+   * scenario, or `illustration={null}` to fall back to `icon` (or nothing).
+   */
+  illustration?: React.ReactNode | null;
+  /** The headline. */
+  title: React.ReactNode;
+  /** Optional supporting copy. */
+  description?: React.ReactNode;
+  /** Actions/CTA — rendered in the content slot below the header. */
+  children?: React.ReactNode;
+}
+
+/**
+ * The canonical "there's nothing here yet" panel. A thin wrapper over the
+ * `Empty` atom's header/media/title/description/content stack that three
+ * codebases (custom-ui, ops-admin, dashboard-common) kept re-assembling inline.
+ *
+ * The `Empty` atom ships `border-dashed` but no `border` width so it stays
+ * shadcn-aligned; the molecule adds `border` to draw the dashed box every donor
+ * implementation had (spike decision).
+ */
+function EmptyState({
+  icon,
+  illustration,
+  title,
+  description,
+  children,
+  className,
+  ...props
+}: EmptyStateProps) {
+  // Precedence: an explicit `illustration` (including `null`, to opt out)
+  // always wins; otherwise an explicit `icon` keeps rendering exactly as
+  // before. Only when neither is touched does the default illustration fill
+  // the media slot, so existing icon-only consumers see no change.
+  const resolvedIllustration =
+    illustration !== undefined ? (
+      illustration
+    ) : icon === undefined ? (
+      <EmptyCollectionIllustration />
+    ) : null;
+
+  return (
+    <Empty data-slot="empty-state" className={cn('border', className)} {...props}>
+      <EmptyHeader>
+        {resolvedIllustration ? (
+          <EmptyMedia>{resolvedIllustration}</EmptyMedia>
+        ) : icon ? (
+          <EmptyMedia variant="icon">{icon}</EmptyMedia>
+        ) : null}
+        <EmptyTitle>{title}</EmptyTitle>
+        {description ? <EmptyDescription>{description}</EmptyDescription> : null}
+      </EmptyHeader>
+      {children ? <EmptyContent>{children}</EmptyContent> : null}
+    </Empty>
+  );
+}
+
+export { EmptyState };

package/src/components/molecules/state-views/error-state.tsx

@@ -0,0 +1,91 @@
+import { Button } from '@vendure-io/ui/components/atoms/button';
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@vendure-io/ui/components/atoms/empty';
+import { ErrorIllustration } from '@vendure-io/ui/components/molecules/illustrations/error';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { TriangleAlertIcon } from 'lucide-react';
+
+// `title` is redefined as `ReactNode`, so drop the native string `title` attr.
+export interface ErrorStateProps extends Omit<React.ComponentProps<typeof Empty>, 'title'> {
+  /**
+   * Leading icon, tinted `text-destructive`. Defaults to an alert triangle.
+   * Ignored once `illustration` renders (see below).
+   */
+  icon?: React.ReactNode;
+  /**
+   * Illustration rendered above the title, in place of `icon`. Defaults to
+   * `ErrorIllustration`. Pass a different illustration (e.g. `NotFoundIllustration`
+   * for a 404), or `illustration={null}` to fall back to `icon`.
+   */
+  illustration?: React.ReactNode | null;
+  /** The headline. Defaults to "Something went wrong". */
+  title?: React.ReactNode;
+  /** Optional supporting copy. */
+  description?: React.ReactNode;
+  /** When provided, renders a "Try again" button that calls this handler. */
+  onRetry?: () => void;
+  /** Label for the retry button. Defaults to "Try again". */
+  retryLabel?: React.ReactNode;
+  /** Extra actions (e.g. a not-found "Go back" link) rendered beside retry. */
+  children?: React.ReactNode;
+}
+
+/**
+ * The one canonical error presentation: a centered box that carries semantics
+ * no atom has — `role="alert"`, a destructive-tinted icon (or illustration),
+ * and an optional retry CTA. Same anatomy as `EmptyState` so failed and empty
+ * states line up.
+ */
+function ErrorState({
+  icon,
+  illustration,
+  title = 'Something went wrong',
+  description,
+  onRetry,
+  retryLabel = 'Try again',
+  children,
+  className,
+  ...props
+}: ErrorStateProps) {
+  // Precedence: an explicit `illustration` (including `null`, to opt out)
+  // always wins; otherwise an explicit `icon` (including `null`) keeps
+  // rendering exactly as before. Only when neither is touched does the
+  // default illustration replace the default triangle icon.
+  const resolvedIllustration =
+    illustration !== undefined ? illustration : icon === undefined ? <ErrorIllustration /> : null;
+  const resolvedIcon = icon === undefined ? <TriangleAlertIcon /> : icon;
+
+  return (
+    <Empty role="alert" data-slot="error-state" className={cn('border', className)} {...props}>
+      <EmptyHeader>
+        {resolvedIllustration ? (
+          <EmptyMedia>{resolvedIllustration}</EmptyMedia>
+        ) : resolvedIcon ? (
+          <EmptyMedia variant="icon" className="text-destructive">
+            {resolvedIcon}
+          </EmptyMedia>
+        ) : null}
+        <EmptyTitle>{title}</EmptyTitle>
+        {description ? <EmptyDescription>{description}</EmptyDescription> : null}
+      </EmptyHeader>
+      {onRetry || children ? (
+        <EmptyContent>
+          {onRetry ? (
+            <Button variant="outline" size="sm" onClick={onRetry}>
+              {retryLabel}
+            </Button>
+          ) : null}
+          {children}
+        </EmptyContent>
+      ) : null}
+    </Empty>
+  );
+}
+
+export { ErrorState };

package/src/components/molecules/state-views/loading-state.tsx

@@ -0,0 +1,80 @@
+import { Skeleton } from '@vendure-io/ui/components/atoms/skeleton';
+import { Spinner } from '@vendure-io/ui/components/atoms/spinner';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+const loadingStateVariants = cva('flex w-full min-w-0 flex-col gap-3', {
+  variants: {
+    variant: {
+      skeleton: '',
+      spinner: 'text-muted-foreground items-center justify-center gap-2 py-8',
+    },
+  },
+  defaultVariants: {
+    variant: 'skeleton',
+  },
+});
+
+// `React.ComponentProps<'output'>` (not `'div'` as the spike sketch wrote) so
+// the spread props type-check against the `<output>` we render.
+export interface LoadingStateProps
+  extends React.ComponentProps<'output'>,
+    VariantProps<typeof loadingStateVariants> {
+  /** Number of skeleton rows. `skeleton` variant only; defaults to 5. */
+  rows?: number;
+  /** Classes applied to each skeleton row (e.g. `h-10` for tighter lists). */
+  rowClassName?: string;
+  /** Visible label. An sr-only "Loading…" is always rendered for assistive tech. */
+  label?: React.ReactNode;
+}
+
+/**
+ * Placeholder shell for in-flight list/detail queries. Renders as an
+ * `aria-live` `<output>` with an always-present sr-only "Loading…" label.
+ * `skeleton` (default) draws N shimmer rows; `spinner` centers the `Spinner`
+ * atom for compact or unknown-height regions.
+ */
+function LoadingState({
+  variant = 'skeleton',
+  rows = 5,
+  rowClassName,
+  label,
+  className,
+  ...props
+}: LoadingStateProps) {
+  return (
+    <output
+      data-slot="loading-state"
+      aria-live="polite"
+      className={cn(loadingStateVariants({ variant }), className)}
+      {...props}
+    >
+      <span className="sr-only">Loading…</span>
+      {variant === 'spinner' ? (
+        <>
+          {/* aria-hidden overrides the atom's role="status": the <output> is
+              already the live region, so the spinner must not double-announce. */}
+          <Spinner aria-hidden="true" />
+          {label ? (
+            <span data-slot="loading-state-label" className="text-muted-foreground text-sm">
+              {label}
+            </span>
+          ) : null}
+        </>
+      ) : (
+        <>
+          {label ? (
+            <span data-slot="loading-state-label" className="text-muted-foreground text-sm">
+              {label}
+            </span>
+          ) : null}
+          {Array.from({ length: rows }).map((_, i) => (
+            <Skeleton key={i} className={cn('h-14 w-full rounded-md', rowClassName)} />
+          ))}
+        </>
+      )}
+    </output>
+  );
+}
+
+export { LoadingState, loadingStateVariants };

package/src/components/molecules/status-badge.tsx

@@ -0,0 +1,100 @@
+import { mergeProps } from '@base-ui/react/merge-props';
+import { useRender } from '@base-ui/react/use-render';
+import type { Tone } from '@vendure-io/ui/lib/state-dictionary';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { cva } from 'class-variance-authority';
+
+// Subtle-only, always. Tinted background + readable foreground + matching
+// border, per tone — the treatment every hand-rolled status chip was reaching
+// for. There is no solid mode: solid/brand chips stay on the base `Badge`
+// (accent rationing applied at the API level).
+//
+// Slot = tone, with two aliases: `critical` renders via the `destructive`
+// slots (the token keeps its shadcn-compatible name) and `progress` renders
+// via the `neutral` slots with an info-colored pulsing dot — a chip that is
+// otherwise identical to `info` is not scannable; the neutral body says "no
+// outcome yet" while the dot says "in motion". Class strings are static per
+// tone so Tailwind's scanner picks them up.
+//
+// Metrics mirror `Badge` (h-5, pill radius, text-xs) so a StatusBadge and a
+// Badge sit side by side on the same row of a table.
+const statusBadgeVariants = cva(
+  'inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1.5 overflow-hidden whitespace-nowrap rounded-4xl border px-2 py-0.5 text-xs font-medium',
+  {
+    variants: {
+      tone: {
+        neutral: 'bg-neutral-subtle text-neutral-subtle-foreground border-neutral-border',
+        info: 'bg-info-subtle text-info-subtle-foreground border-info-border',
+        success: 'bg-success-subtle text-success-subtle-foreground border-success-border',
+        warning: 'bg-warning-subtle text-warning-subtle-foreground border-warning-border',
+        critical:
+          'bg-destructive-subtle text-destructive-subtle-foreground border-destructive-border',
+        progress: 'bg-neutral-subtle text-neutral-subtle-foreground border-neutral-border',
+      } satisfies Record<Tone, string>,
+    },
+    defaultVariants: {
+      tone: 'neutral',
+    },
+  },
+);
+
+interface StatusBadgeProps extends useRender.ComponentProps<'span'> {
+  /** Semantic tone. Defaults to `neutral`. */
+  tone?: Tone;
+  /**
+   * Show a leading dot. Off by default (calm on detail pages); opt in for dense
+   * tables. `progress` always shows a dot regardless of this prop, and that dot
+   * pulses (pausing under `prefers-reduced-motion`) — it replaces ad-hoc
+   * spinners.
+   */
+  dot?: boolean;
+}
+
+function StatusBadge({
+  className,
+  tone = 'neutral',
+  dot = false,
+  render,
+  children,
+  ...props
+}: StatusBadgeProps) {
+  const showDot = dot || tone === 'progress';
+
+  return useRender({
+    defaultTagName: 'span',
+    props: mergeProps<'span'>(
+      {
+        className: cn(statusBadgeVariants({ tone }), className),
+      },
+      props,
+      {
+        // The component never transforms or translates the label — children win.
+        // A consumer passes their translated string; `defaultLabel` from the
+        // dictionary is a fallback the caller resolves, not something rendered here.
+        children: (
+          <>
+            {showDot ? (
+              <span
+                aria-hidden
+                className={cn(
+                  'size-1.5 shrink-0 rounded-full',
+                  tone === 'progress'
+                    ? 'bg-info-subtle-foreground motion-safe:animate-pulse'
+                    : 'bg-current',
+                )}
+              />
+            ) : null}
+            {children}
+          </>
+        ),
+      },
+    ),
+    render,
+    state: {
+      slot: 'status-badge',
+      tone,
+    },
+  });
+}
+
+export { StatusBadge, statusBadgeVariants };

package/src/hooks/use-copy.ts

@@ -0,0 +1,51 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface UseCopyOptions {
+  /** How long `copied` stays true after a successful copy, in ms. */
+  timeout?: number;
+}
+
+interface UseCopyReturn {
+  /** True for `timeout` ms after the last successful copy. */
+  copied: boolean;
+  /** Writes `text` to the clipboard. Resolves `true` on success, `false` on failure — never throws. */
+  copy: (text: string) => Promise<boolean>;
+}
+
+/**
+ * Clipboard-copy hook with transient "copied" feedback. Inlines the
+ * `navigator.clipboard` call so the design system takes no third-party
+ * clipboard dependency, and never couples to a toast — surface success/failure
+ * through the returned `copied` flag (or the `CopyButton` callbacks).
+ */
+export function useCopy({ timeout = 2000 }: UseCopyOptions = {}): UseCopyReturn {
+  const [copied, setCopied] = useState(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    },
+    [],
+  );
+
+  const copy = useCallback(
+    async (text: string): Promise<boolean> => {
+      try {
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        if (timeoutRef.current) clearTimeout(timeoutRef.current);
+        timeoutRef.current = setTimeout(() => setCopied(false), timeout);
+        return true;
+      } catch {
+        setCopied(false);
+        return false;
+      }
+    },
+    [timeout],
+  );
+
+  return { copied, copy };
+}

package/src/lib/base-ui.ts

@@ -1,7 +1,7 @@
 /**
  * Re-exports of `@base-ui/react` primitive namespaces.
  *
- * Why this exists: the wrapper components in `@vendure-io/ui/components/ui/*`
+ * Why this exists: the wrapper components in `@vendure-io/ui/components/atoms/*`
  * are intentionally thin layers over `@base-ui/react` primitives. Consumers
  * (notably `@vendure/dashboard`) often need to override a single subcomponent
  * — e.g. swap `DialogTitle` for one that uses a different font — while