@vendure-io/ui 2.0.0-beta.3 → 2.0.0-beta.5

package/README.md

@@ -4,8 +4,8 @@ React component library for Vendure, built on [shadcn/ui](https://ui.shadcn.com/
 
 ## Install
 
-```bash
-npm install @vendure-io/ui
+```sh
+bun add @vendure-io/ui
 ```
 
 ### Peer dependencies
@@ -13,7 +13,7 @@ npm install @vendure-io/ui
 - `react` >= 19
 - `react-dom` >= 19
 
-Optional peers: `next`, `next-themes`, `react-hook-form`
+Optional peers: `next`, `next-themes`
 
 ## Usage
 
@@ -32,6 +32,9 @@ import { cn } from "@vendure-io/ui/lib/utils";
 | `@vendure-io/ui/lib/base-ui` | `@base-ui/react` primitive namespaces (see below) |
 | `@vendure-io/ui/hooks/*` | Shared React hooks |
 
+See the repository's [component guide](../../docs/ui-components.md) for the full
+atom and molecule inventory.
+
 ## Customizing wrapper components
 
 The components under `components/atoms/*` are thin wrappers around [`@base-ui/react`](https://base-ui.com/) primitives. To override a single subcomponent (e.g. swap `DialogTitle` for one with a different font) while re-using the rest, import the underlying primitive namespace from `@vendure-io/ui/lib/base-ui` rather than from `@base-ui/react` directly:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vendure-io/ui",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.5",
   "description": "React component library for Vendure, built on shadcn/ui and Tailwind v4",
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://github.com/vendurehq/design/tree/main/packages/ui",
@@ -33,8 +33,7 @@
     "react": ">=19",
     "react-dom": ">=19",
     "next": ">=14",
-    "next-themes": "^0.4.6",
-    "react-hook-form": ">=7"
+    "next-themes": "^0.4.6"
   },
   "peerDependenciesMeta": {
     "next": {
@@ -42,15 +41,12 @@
     },
     "next-themes": {
       "optional": true
-    },
-    "react-hook-form": {
-      "optional": true
     }
   },
   "dependencies": {
     "@base-ui/react": "^1.2.0",
     "@tanstack/react-table": "^8.21.3",
-    "@vendure-io/design-tokens": "^2.0.0-beta.1",
+    "@vendure-io/design-tokens": "^2.0.0-beta.5",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",

package/src/components/atoms/button.tsx

@@ -11,6 +11,10 @@ const buttonVariants = cva(
     variants: {
       variant: {
         default: "bg-primary text-primary-foreground hover:bg-primary/80",
+        // Identity/marketing CTA only ("Start free trial", "Upgrade to Cloud"):
+        // a deliberate brand moment, not a louder `default` primary. Brand is a
+        // signature, not a wallpaper; see Button guidance before reaching for it.
+        brand: "bg-brand text-brand-foreground hover:bg-brand/80",
         outline:
           "border-border bg-background hover:bg-muted hover:text-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 aria-expanded:bg-muted aria-expanded:text-foreground",
         secondary:

package/src/components/atoms/scroll-area.tsx

@@ -39,7 +39,10 @@ function ScrollBar({
       data-orientation={orientation}
       orientation={orientation}
       className={cn(
-        "flex touch-none p-px transition-colors select-none data-horizontal:h-2.5 data-horizontal:flex-col data-horizontal:border-t data-horizontal:border-t-transparent data-vertical:h-full data-vertical:w-2.5 data-vertical:border-l data-vertical:border-l-transparent",
+        // Overlay scrollbars: invisible at rest, fade in while the pointer is over
+        // the scroll area (data-hovering) or during active scrolling (data-scrolling).
+        // Base UI omits data-scrolling on programmatic scrolls, so route changes don't flash.
+        "flex touch-none p-px select-none opacity-0 transition-opacity data-hovering:opacity-100 data-scrolling:opacity-100 data-horizontal:h-2.5 data-horizontal:flex-col data-horizontal:border-t data-horizontal:border-t-transparent data-vertical:h-full data-vertical:w-2.5 data-vertical:border-l data-vertical:border-l-transparent",
         className
       )}
       {...props}

package/src/components/molecules/app-shell.tsx

@@ -15,13 +15,16 @@ import type * as React from 'react';
 // the step instead. That asymmetry is intentional, not a gap.
 //
 // The sidebar slot is deliberately unopinionated: drop the full `Sidebar` atom in
-// for a real app, or use `AppShellSidebar` for a lightweight rail.
+// for a real app, or use `AppShellSidebar` for a lightweight rail. Content owns a
+// header + main anatomy so every consumer gets the same scroll boundary and skip
+// link target without coupling the design system to a router or auth provider. The
+// shell is viewport-bound so the canvas inset remains visible while main scrolls.
 
 function AppShell({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
       data-slot="app-shell"
-      className={cn('bg-background text-foreground flex min-h-svh w-full', className)}
+      className={cn('bg-background text-foreground flex h-svh w-full overflow-hidden', className)}
       {...props}
     />
   );
@@ -40,16 +43,29 @@ function AppShellSidebar({ className, ...props }: React.ComponentProps<'aside'>)
   );
 }
 
-function AppShellContent({ className, ...props }: React.ComponentProps<'main'>) {
+function AppShellContent({ className, ...props }: React.ComponentProps<'div'>) {
   return (
-    <main
+    <div
       data-slot="app-shell-content"
       className={cn(
         // The missing tier: step up to --surface and inset from the canvas so the
         // shell frames the pane on all sides, including a gutter between the
         // sidebar and the pane. Flat by design: the border carries the tier in
         // light mode (see AGENTS.md "flat look"), so no drop shadow.
-        'bg-surface m-3 flex flex-1 flex-col overflow-hidden rounded-xl border border-border/60',
+        'bg-surface m-3 flex min-w-0 flex-1 flex-col overflow-hidden rounded-xl border border-border/60',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function AppShellHeader({ className, ...props }: React.ComponentProps<'header'>) {
+  return (
+    <header
+      data-slot="app-shell-header"
+      className={cn(
+        'flex h-12 shrink-0 items-center gap-2 border-b border-border/60 px-4',
         className,
       )}
       {...props}
@@ -57,4 +73,16 @@ function AppShellContent({ className, ...props }: React.ComponentProps<'main'>)
   );
 }
 
-export { AppShell, AppShellSidebar, AppShellContent };
+function AppShellMain({ className, id = 'main-content', ...props }: React.ComponentProps<'main'>) {
+  return (
+    <main
+      id={id}
+      tabIndex={-1}
+      data-slot="app-shell-main"
+      className={cn('min-h-0 min-w-0 flex-1 overflow-auto outline-none', className)}
+      {...props}
+    />
+  );
+}
+
+export { AppShell, AppShellSidebar, AppShellContent, AppShellHeader, AppShellMain };

package/src/components/molecules/date-picker.tsx

@@ -0,0 +1,117 @@
+'use client';
+
+import { Button } from '@vendure-io/ui/components/atoms/button';
+import { Calendar } from '@vendure-io/ui/components/atoms/calendar';
+import { Popover, PopoverContent, PopoverTrigger } from '@vendure-io/ui/components/atoms/popover';
+import { useFormatSettings } from '@vendure-io/ui/components/molecules/format-provider';
+import {
+  formatCalendarDate,
+  formatDateLabel,
+  parseCalendarDate,
+} from '@vendure-io/ui/lib/date-value';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { CalendarIcon, XIcon } from 'lucide-react';
+import * as React from 'react';
+
+type CalendarProps = Omit<
+  React.ComponentProps<typeof Calendar>,
+  'mode' | 'selected' | 'onSelect' | 'disabled' | 'defaultMonth'
+>;
+
+interface DatePickerProps extends Omit<React.ComponentProps<'div'>, 'defaultValue' | 'onChange'> {
+  /** Local calendar date (`YYYY-MM-DD`), never an instant. */
+  value?: string;
+  onValueChange?: (value: string | undefined) => void;
+  min?: string;
+  max?: string;
+  placeholder?: React.ReactNode;
+  clearable?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  name?: string;
+  id?: string;
+  calendarProps?: CalendarProps;
+}
+
+/** Date-only picker whose value cannot shift when serialized across time zones. */
+function DatePicker({
+  value,
+  onValueChange,
+  min,
+  max,
+  placeholder = 'Pick a date',
+  clearable = true,
+  disabled,
+  invalid,
+  name,
+  id,
+  calendarProps,
+  className,
+  ...props
+}: DatePickerProps) {
+  const [open, setOpen] = React.useState(false);
+  const { locale } = useFormatSettings();
+  const selected = parseCalendarDate(value);
+  const minDate = parseCalendarDate(min);
+  const maxDate = parseCalendarDate(max);
+  const disabledMatchers = [
+    ...(minDate ? [{ before: minDate }] : []),
+    ...(maxDate ? [{ after: maxDate }] : []),
+  ];
+
+  return (
+    <div
+      data-slot="date-picker"
+      className={cn('flex min-w-0 items-center gap-1', className)}
+      {...props}
+    >
+      {name ? <input type="hidden" name={name} value={value ?? ''} /> : null}
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger
+          render={
+            <Button
+              id={id}
+              type="button"
+              variant="outline"
+              disabled={disabled}
+              aria-invalid={invalid || undefined}
+              className="min-w-0 flex-1 justify-start font-normal"
+            />
+          }
+        >
+          <CalendarIcon />
+          <span className={cn('truncate', !selected && 'text-muted-foreground')}>
+            {selected ? formatDateLabel(selected, locale) : placeholder}
+          </span>
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0" align="start">
+          <Calendar
+            {...calendarProps}
+            mode="single"
+            selected={selected}
+            defaultMonth={selected ?? minDate}
+            disabled={disabledMatchers}
+            onSelect={(date) => {
+              onValueChange?.(date ? formatCalendarDate(date) : undefined);
+              if (date) setOpen(false);
+            }}
+          />
+        </PopoverContent>
+      </Popover>
+      {clearable && selected ? (
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-sm"
+          disabled={disabled}
+          aria-label="Clear date"
+          onClick={() => onValueChange?.(undefined)}
+        >
+          <XIcon />
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+export { DatePicker, type DatePickerProps };

package/src/components/molecules/date-range-picker.tsx

@@ -0,0 +1,151 @@
+'use client';
+
+import { Button } from '@vendure-io/ui/components/atoms/button';
+import { Calendar } from '@vendure-io/ui/components/atoms/calendar';
+import { Popover, PopoverContent, PopoverTrigger } from '@vendure-io/ui/components/atoms/popover';
+import { useFormatSettings } from '@vendure-io/ui/components/molecules/format-provider';
+import {
+  formatCalendarDate,
+  formatDateRangeLabel,
+  parseCalendarDate,
+} from '@vendure-io/ui/lib/date-value';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { CalendarRangeIcon, XIcon } from 'lucide-react';
+import * as React from 'react';
+import type { DateRange } from 'react-day-picker';
+
+type CalendarProps = Omit<
+  React.ComponentProps<typeof Calendar>,
+  'mode' | 'selected' | 'onSelect' | 'defaultMonth'
+>;
+
+interface DateRangeValue {
+  from?: string;
+  to?: string;
+}
+
+interface DateRangePreset {
+  id: string;
+  label: React.ReactNode;
+  value: DateRangeValue | (() => DateRangeValue);
+}
+
+interface DateRangePickerProps
+  extends Omit<React.ComponentProps<'div'>, 'defaultValue' | 'onChange'> {
+  /** Local calendar-date boundaries (`YYYY-MM-DD`), inclusive. */
+  value?: DateRangeValue;
+  onValueChange?: (value: DateRangeValue | undefined) => void;
+  placeholder?: React.ReactNode;
+  clearable?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  presets?: readonly DateRangePreset[];
+  calendarProps?: CalendarProps;
+}
+
+function resolvePreset(value: DateRangePreset['value']): DateRangeValue {
+  return typeof value === 'function' ? value() : value;
+}
+
+function DateRangePicker({
+  value,
+  onValueChange,
+  placeholder = 'Pick a date range',
+  clearable = true,
+  disabled,
+  invalid,
+  presets = [],
+  calendarProps,
+  className,
+  ...props
+}: DateRangePickerProps) {
+  const [open, setOpen] = React.useState(false);
+  const { locale } = useFormatSettings();
+  const selected: DateRange = {
+    from: parseCalendarDate(value?.from),
+    to: parseCalendarDate(value?.to),
+  };
+  const hasValue = Boolean(selected.from);
+
+  function commitRange(range: DateRange | undefined) {
+    if (!range?.from) {
+      onValueChange?.(undefined);
+      return;
+    }
+    onValueChange?.({
+      from: formatCalendarDate(range.from),
+      to: range.to ? formatCalendarDate(range.to) : undefined,
+    });
+  }
+
+  return (
+    <div
+      data-slot="date-range-picker"
+      className={cn('flex min-w-0 items-center gap-1', className)}
+      {...props}
+    >
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger
+          render={
+            <Button
+              type="button"
+              variant="outline"
+              disabled={disabled}
+              aria-invalid={invalid || undefined}
+              className="min-w-0 flex-1 justify-start font-normal"
+            />
+          }
+        >
+          <CalendarRangeIcon />
+          <span className={cn('truncate', !hasValue && 'text-muted-foreground')}>
+            {selected.from ? formatDateRangeLabel(selected.from, selected.to, locale) : placeholder}
+          </span>
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0" align="start">
+          <div className={cn('flex', presets.length > 0 && 'divide-x')}>
+            {presets.length > 0 ? (
+              <div className="flex w-40 flex-col gap-1 p-2">
+                {presets.map((preset) => (
+                  <Button
+                    key={preset.id}
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    className="justify-start font-normal"
+                    onClick={() => {
+                      onValueChange?.(resolvePreset(preset.value));
+                      setOpen(false);
+                    }}
+                  >
+                    {preset.label}
+                  </Button>
+                ))}
+              </div>
+            ) : null}
+            <Calendar
+              {...calendarProps}
+              mode="range"
+              selected={selected}
+              defaultMonth={selected.from}
+              onSelect={commitRange}
+            />
+          </div>
+        </PopoverContent>
+      </Popover>
+      {clearable && hasValue ? (
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-sm"
+          disabled={disabled}
+          aria-label="Clear date range"
+          onClick={() => onValueChange?.(undefined)}
+        >
+          <XIcon />
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+export { DateRangePicker, type DateRangePickerProps, type DateRangePreset, type DateRangeValue };

package/src/components/molecules/date-time-picker.tsx

@@ -0,0 +1,131 @@
+'use client';
+
+import { Button } from '@vendure-io/ui/components/atoms/button';
+import { Calendar } from '@vendure-io/ui/components/atoms/calendar';
+import { Input } from '@vendure-io/ui/components/atoms/input';
+import { Popover, PopoverContent, PopoverTrigger } from '@vendure-io/ui/components/atoms/popover';
+import { useFormatSettings } from '@vendure-io/ui/components/molecules/format-provider';
+import { formatDateLabel, parseInstant } from '@vendure-io/ui/lib/date-value';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { CalendarClockIcon, XIcon } from 'lucide-react';
+import * as React from 'react';
+
+type CalendarProps = Omit<
+  React.ComponentProps<typeof Calendar>,
+  'mode' | 'selected' | 'onSelect' | 'defaultMonth'
+>;
+
+interface DateTimePickerProps
+  extends Omit<React.ComponentProps<'div'>, 'defaultValue' | 'onChange'> {
+  /** ISO 8601 instant. Calendar and time controls edit it in the user's local zone. */
+  value?: string;
+  onValueChange?: (value: string | undefined) => void;
+  placeholder?: React.ReactNode;
+  clearable?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  name?: string;
+  id?: string;
+  calendarProps?: CalendarProps;
+}
+
+function DateTimePicker({
+  value,
+  onValueChange,
+  placeholder = 'Pick a date and time',
+  clearable = true,
+  disabled,
+  invalid,
+  name,
+  id,
+  calendarProps,
+  className,
+  ...props
+}: DateTimePickerProps) {
+  const [open, setOpen] = React.useState(false);
+  const { locale } = useFormatSettings();
+  const selected = parseInstant(value);
+  const timeValue = selected
+    ? `${String(selected.getHours()).padStart(2, '0')}:${String(selected.getMinutes()).padStart(2, '0')}`
+    : '';
+
+  function commitDate(date: Date | undefined) {
+    if (!date) return;
+    const next = new Date(date);
+    next.setHours(selected?.getHours() ?? 0, selected?.getMinutes() ?? 0, 0, 0);
+    onValueChange?.(next.toISOString());
+    setOpen(false);
+  }
+
+  function commitTime(time: string) {
+    if (!time) return;
+    const [hoursText, minutesText] = time.split(':');
+    const hours = Number(hoursText);
+    const minutes = Number(minutesText);
+    if (!Number.isFinite(hours) || !Number.isFinite(minutes)) return;
+    const next = selected ? new Date(selected) : new Date();
+    next.setHours(hours, minutes, 0, 0);
+    onValueChange?.(next.toISOString());
+  }
+
+  return (
+    <div
+      data-slot="date-time-picker"
+      className={cn('flex min-w-0 items-center gap-2', className)}
+      {...props}
+    >
+      {name ? <input type="hidden" name={name} value={value ?? ''} /> : null}
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger
+          render={
+            <Button
+              id={id}
+              type="button"
+              variant="outline"
+              disabled={disabled}
+              aria-invalid={invalid || undefined}
+              className="min-w-0 flex-1 justify-start font-normal"
+            />
+          }
+        >
+          <CalendarClockIcon />
+          <span className={cn('truncate', !selected && 'text-muted-foreground')}>
+            {selected ? formatDateLabel(selected, locale) : placeholder}
+          </span>
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0" align="start">
+          <Calendar
+            {...calendarProps}
+            mode="single"
+            selected={selected}
+            defaultMonth={selected}
+            onSelect={commitDate}
+          />
+        </PopoverContent>
+      </Popover>
+      <Input
+        type="time"
+        aria-label="Time"
+        aria-invalid={invalid || undefined}
+        value={timeValue}
+        disabled={disabled || !selected}
+        className="w-28"
+        onChange={(event) => commitTime(event.currentTarget.value)}
+      />
+      {clearable && selected ? (
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-sm"
+          disabled={disabled}
+          aria-label="Clear date and time"
+          onClick={() => onValueChange?.(undefined)}
+        >
+          <XIcon />
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+export { DateTimePicker, type DateTimePickerProps };

package/src/components/molecules/file-dropzone.tsx

@@ -0,0 +1,261 @@
+'use client';
+
+import { Button } from '@vendure-io/ui/components/atoms/button';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { FileIcon, UploadCloudIcon, XIcon } from 'lucide-react';
+import * as React from 'react';
+
+type FileValidationResult = string | readonly string[] | null | undefined;
+type FileValidator = (file: File) => FileValidationResult | Promise<FileValidationResult>;
+
+interface FileRejection {
+  file: File;
+  messages: string[];
+}
+
+interface FileDropzoneProps extends Omit<React.ComponentProps<'div'>, 'onChange'> {
+  value?: readonly File[];
+  onValueChange?: (files: File[]) => void;
+  onRejected?: (rejections: FileRejection[]) => void;
+  accept?: string;
+  multiple?: boolean;
+  maxFiles?: number;
+  maxSize?: number;
+  validateFile?: FileValidator;
+  disabled?: boolean;
+  required?: boolean;
+  name?: string;
+  id?: string;
+  label?: React.ReactNode;
+  description?: React.ReactNode;
+  emptyLabel?: React.ReactNode;
+  dragLabel?: React.ReactNode;
+  renderFile?: (file: File, remove: () => void) => React.ReactNode;
+}
+
+function fileMatchesAccept(file: File, accept: string | undefined): boolean {
+  if (!accept?.trim()) return true;
+  const fileName = file.name.toLowerCase();
+  const mime = file.type.toLowerCase();
+  return accept.split(',').some((rawRule) => {
+    const rule = rawRule.trim().toLowerCase();
+    if (!rule) return false;
+    if (rule.startsWith('.')) return fileName.endsWith(rule);
+    if (rule.endsWith('/*')) return mime.startsWith(rule.slice(0, -1));
+    return mime === rule;
+  });
+}
+
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 ** 2) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+}
+
+function normalizeValidationResult(result: FileValidationResult): string[] {
+  if (!result) return [];
+  return typeof result === 'string' ? [result] : [...result];
+}
+
+/**
+ * Controlled, transport-agnostic file input. It owns accessible picking,
+ * drag-and-drop, limits, validation, errors, and removal; consumers own upload
+ * persistence and can replace the selected-file rendering with `renderFile`.
+ */
+function FileDropzone({
+  value = [],
+  onValueChange,
+  onRejected,
+  accept,
+  multiple = false,
+  maxFiles = multiple ? Number.POSITIVE_INFINITY : 1,
+  maxSize,
+  validateFile,
+  disabled,
+  required,
+  name,
+  id: providedId,
+  label = 'Upload files',
+  description,
+  emptyLabel = 'Drag and drop files here, or choose files',
+  dragLabel = 'Drop files to add them',
+  renderFile,
+  className,
+  ...props
+}: FileDropzoneProps) {
+  const generatedId = React.useId();
+  const id = providedId ?? generatedId;
+  const descriptionId = `${id}-description`;
+  const errorId = `${id}-error`;
+  const [dragging, setDragging] = React.useState(false);
+  const [validating, setValidating] = React.useState(false);
+  const [rejections, setRejections] = React.useState<FileRejection[]>([]);
+  const dragDepth = React.useRef(0);
+
+  async function addFiles(incoming: readonly File[]) {
+    if (disabled || incoming.length === 0) return;
+    setValidating(true);
+    const accepted: File[] = [];
+    const rejected: FileRejection[] = [];
+    const remaining = Math.max(0, maxFiles - (multiple ? value.length : 0));
+
+    for (const file of incoming.slice(0, remaining)) {
+      const messages: string[] = [];
+      if (!fileMatchesAccept(file, accept)) messages.push('This file type is not accepted.');
+      if (maxSize !== undefined && file.size > maxSize) {
+        messages.push(`File size must be ${formatFileSize(maxSize)} or smaller.`);
+      }
+      if (validateFile) {
+        try {
+          messages.push(...normalizeValidationResult(await validateFile(file)));
+        } catch {
+          messages.push('This file could not be validated.');
+        }
+      }
+      if (messages.length > 0) rejected.push({ file, messages });
+      else accepted.push(file);
+    }
+
+    if (incoming.length > remaining) {
+      for (const file of incoming.slice(remaining)) {
+        rejected.push({ file, messages: [`You can select up to ${maxFiles} files.`] });
+      }
+    }
+
+    setRejections(rejected);
+    setValidating(false);
+    if (rejected.length > 0) onRejected?.(rejected);
+    if (accepted.length > 0) {
+      onValueChange?.(multiple ? [...value, ...accepted] : accepted.slice(0, 1));
+    }
+  }
+
+  function removeFile(index: number) {
+    onValueChange?.(value.filter((_, fileIndex) => fileIndex !== index));
+    setRejections([]);
+  }
+
+  return (
+    <div data-slot="file-dropzone" className={cn('flex flex-col gap-3', className)} {...props}>
+      <div>
+        <label htmlFor={id} className="text-sm font-medium">
+          {label}
+          {required ? <span className="text-destructive"> *</span> : null}
+        </label>
+        {description ? (
+          <p id={descriptionId} className="text-muted-foreground mt-1 text-sm">
+            {description}
+          </p>
+        ) : null}
+      </div>
+
+      <input
+        id={id}
+        name={name}
+        type="file"
+        accept={accept}
+        multiple={multiple}
+        required={required && value.length === 0}
+        disabled={disabled || validating}
+        aria-describedby={
+          cn(description && descriptionId, rejections.length > 0 && errorId) || undefined
+        }
+        className="peer sr-only"
+        onChange={(event) => {
+          const files = Array.from(event.currentTarget.files ?? []);
+          event.currentTarget.value = '';
+          void addFiles(files);
+        }}
+      />
+
+      <label
+        htmlFor={id}
+        data-slot="file-dropzone-target"
+        data-dragging={dragging || undefined}
+        data-disabled={disabled || validating || undefined}
+        onDragEnter={(event) => {
+          event.preventDefault();
+          if (disabled) return;
+          dragDepth.current += 1;
+          setDragging(true);
+        }}
+        onDragOver={(event) => {
+          event.preventDefault();
+          if (event.dataTransfer) event.dataTransfer.dropEffect = 'copy';
+        }}
+        onDragLeave={(event) => {
+          event.preventDefault();
+          dragDepth.current = Math.max(0, dragDepth.current - 1);
+          if (dragDepth.current === 0) setDragging(false);
+        }}
+        onDrop={(event) => {
+          event.preventDefault();
+          dragDepth.current = 0;
+          setDragging(false);
+          void addFiles(Array.from(event.dataTransfer.files));
+        }}
+        className={cn(
+          'border-border text-muted-foreground hover:border-foreground/40 flex min-h-32 cursor-pointer flex-col items-center justify-center gap-2 rounded-xl border-2 border-dashed px-6 py-8 text-center transition-[border-color,background-color,color] duration-(--transition-duration-fast) ease-(--ease-out)',
+          'peer-focus-visible:border-ring peer-focus-visible:ring-3 peer-focus-visible:ring-ring/50',
+          'data-dragging:border-foreground data-dragging:bg-accent data-dragging:text-accent-foreground',
+          'data-disabled:pointer-events-none data-disabled:cursor-not-allowed data-disabled:opacity-50',
+        )}
+      >
+        <UploadCloudIcon className="size-7" />
+        <span className="text-foreground text-sm font-medium">
+          {validating ? 'Checking files…' : dragging ? dragLabel : emptyLabel}
+        </span>
+        {accept ? <span className="text-xs">Accepted: {accept}</span> : null}
+      </label>
+
+      {value.length > 0 ? (
+        <ul data-slot="file-dropzone-files" className="flex flex-col gap-2">
+          {value.map((file, index) => (
+            <li key={`${file.name}-${file.size}-${file.lastModified}`}>
+              {renderFile ? (
+                renderFile(file, () => removeFile(index))
+              ) : (
+                <div className="bg-muted/60 flex min-w-0 items-center gap-3 rounded-lg border px-3 py-2">
+                  <FileIcon className="text-muted-foreground size-4 shrink-0" />
+                  <div className="min-w-0 flex-1">
+                    <p className="truncate text-sm font-medium">{file.name}</p>
+                    <p className="text-muted-foreground text-xs">{formatFileSize(file.size)}</p>
+                  </div>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-xs"
+                    disabled={disabled}
+                    aria-label={`Remove ${file.name}`}
+                    onClick={() => removeFile(index)}
+                  >
+                    <XIcon />
+                  </Button>
+                </div>
+              )}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+
+      {rejections.length > 0 ? (
+        <div id={errorId} role="alert" className="text-destructive text-sm">
+          {rejections.map(({ file, messages }) => (
+            <p key={`${file.name}-${file.size}`}>
+              <span className="font-medium">{file.name}:</span> {messages.join(' ')}
+            </p>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export {
+  FileDropzone,
+  fileMatchesAccept,
+  formatFileSize,
+  type FileDropzoneProps,
+  type FileRejection,
+  type FileValidator,
+};

package/src/components/molecules/skip-link.tsx

@@ -0,0 +1,36 @@
+import { cn } from '@vendure-io/ui/lib/utils';
+import type * as React from 'react';
+
+interface SkipLinkProps extends React.ComponentProps<'a'> {
+  /** The main-content element to focus. Include the leading `#`. */
+  href?: `#${string}`;
+}
+
+/**
+ * Keyboard-only escape hatch for repeated application chrome. Place it as the
+ * first focusable element in the document and point it at `AppShellMain` (whose
+ * default id is `main-content`). Native anchor behavior keeps this server-safe
+ * and works before React hydrates.
+ */
+function SkipLink({
+  className,
+  href = '#main-content',
+  children = 'Skip to main content',
+  ...props
+}: SkipLinkProps) {
+  return (
+    <a
+      data-slot="skip-link"
+      href={href}
+      className={cn(
+        'bg-primary text-primary-foreground fixed top-3 left-3 z-[100] -translate-y-20 rounded-md px-3 py-2 text-sm font-medium opacity-0 outline-none transition-[transform,opacity] duration-(--transition-duration-fast) ease-(--ease-out) focus-visible:translate-y-0 focus-visible:opacity-100 focus-visible:ring-3 focus-visible:ring-ring/50 motion-reduce:transition-none',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </a>
+  );
+}
+
+export { SkipLink, type SkipLinkProps };

package/src/lib/date-value.ts

@@ -0,0 +1,48 @@
+const CALENDAR_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/** Parse `YYYY-MM-DD` into a local calendar date without a UTC shift. */
+function parseCalendarDate(value: string | null | undefined): Date | undefined {
+  if (!value) return undefined;
+  const match = CALENDAR_DATE_PATTERN.exec(value);
+  if (!match) return undefined;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const date = new Date(year, month - 1, day);
+  if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) {
+    return undefined;
+  }
+  return date;
+}
+
+/** Serialize a local calendar date as `YYYY-MM-DD`. */
+function formatCalendarDate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function parseInstant(value: string | null | undefined): Date | undefined {
+  if (!value) return undefined;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+function formatDateLabel(date: Date, locale?: string): string {
+  return new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(date);
+}
+
+function formatDateRangeLabel(from: Date, to: Date | undefined, locale?: string): string {
+  if (!to || from.getTime() === to.getTime()) return formatDateLabel(from, locale);
+  const formatter = new Intl.DateTimeFormat(locale, { dateStyle: 'medium' });
+  return formatter.formatRange(from, to);
+}
+
+export {
+  formatCalendarDate,
+  formatDateLabel,
+  formatDateRangeLabel,
+  parseCalendarDate,
+  parseInstant,
+};