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

package/src/components/molecules/data-table/table-pagination.tsx

@@ -0,0 +1,263 @@
+'use client';
+
+import { Button } from '@vendure-io/ui/components/atoms/button';
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@vendure-io/ui/components/atoms/select';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import type * as React from 'react';
+
+// The list-page pagination footer: range text on one side, optional page-size
+// selector and prev/next controls on the other. TanStack-free and
+// fetch-agnostic — driven by value props, not a table instance.
+//
+// Capability-props contract: a feature renders only if its prop is wired. The
+// page-size selector appears only with `onPageSizeChange`; prev/next appear only
+// with `onPageChange` or `getPageHref`. There are no feature flags and no
+// disabled placeholder UI for capabilities the consumer didn't opt into.
+
+/** max(1, …) so an empty result still reports a single page, never zero pages. */
+function getPageCount(totalItems: number, pageSize: number): number {
+  return Math.max(1, Math.ceil(totalItems / pageSize));
+}
+
+/** Clamp a possibly out-of-range page into `[1, pageCount]`. */
+function clampPage(page: number, pageCount: number): number {
+  return Math.min(Math.max(page, 1), pageCount);
+}
+
+/**
+ * The 1-based item range shown on the current page. Empty results collapse to
+ * `{ 0, 0 }` so the caller can render "0 of 0" rather than a nonsensical "1–0".
+ * The last partial page clamps its end to `totalItems` (e.g. "126–132 of 132").
+ */
+function getRange(
+  page: number,
+  pageSize: number,
+  totalItems: number,
+): { start: number; end: number } {
+  if (totalItems <= 0) return { start: 0, end: 0 };
+  const clamped = clampPage(page, getPageCount(totalItems, pageSize));
+  const start = (clamped - 1) * pageSize + 1;
+  const end = Math.min(clamped * pageSize, totalItems);
+  return { start, end };
+}
+
+/** Default range string: "0 of 0" when empty, else "start–end of total" (en dash). */
+function defaultFormatRange({
+  start,
+  end,
+  total,
+}: {
+  start: number;
+  end: number;
+  total: number;
+}): string {
+  return total <= 0 ? '0 of 0' : `${start}–${end} of ${total}`;
+}
+
+interface TablePaginationProps extends React.ComponentProps<'div'> {
+  /**
+   * 1-based current page. The footer clamps this into range for what it
+   * *displays* only — it does not own page state. If `page` can end up past the
+   * last page (e.g. after the page size grows), reset it in your own handler;
+   * see `onPageSizeChange`.
+   */
+  page: number;
+  /** Items per page — also scales the range math. */
+  pageSize: number;
+  /** Total items across all pages, used for the range text and last-page detection. */
+  totalItems: number;
+  /**
+   * Wires button-mode prev/next: renders `<button>`s that call this with the
+   * target page. Ignored for navigation rendering when `getPageHref` is set.
+   */
+  onPageChange?: (page: number) => void;
+  /**
+   * Its presence is the only thing that renders the page-size selector. Called
+   * with the chosen size. You own page state: growing the size can leave `page`
+   * pointing past the new last page, so reset it here (typically `setPage(1)`).
+   * The footer clamps only its own display, never your state.
+   */
+  onPageSizeChange?: (size: number) => void;
+  /** Options offered by the page-size selector. */
+  pageSizeOptions?: number[];
+  /**
+   * Anchor mode: prev/next render as real `<a href>` elements for full-page
+   * navigation (RSC-friendly). When set, it wins over `onPageChange`. A disabled
+   * edge renders a non-link with `aria-disabled` rather than an `<a>`.
+   */
+  getPageHref?: (page: number) => string;
+  /**
+   * Override the range text. Receives the clamped 1-based range and total, and
+   * defaults to "start–end of total" ("0 of 0" when empty). A function, not a
+   * word-swap prop, so it survives non-English word order.
+   */
+  formatRange?: (range: { start: number; end: number; total: number }) => string;
+  /** Accessible name for the prev/next navigation landmark. */
+  navLabel?: string;
+  /** Accessible name for the previous-page control. */
+  previousLabel?: string;
+  /** Accessible name for the next-page control. */
+  nextLabel?: string;
+  /** Visible + accessible name for the page-size selector. */
+  pageSizeLabel?: string;
+}
+
+function TablePagination({
+  page,
+  pageSize,
+  totalItems,
+  onPageChange,
+  onPageSizeChange,
+  pageSizeOptions = [10, 25, 50, 100],
+  getPageHref,
+  formatRange = defaultFormatRange,
+  navLabel = 'Pagination',
+  previousLabel = 'Go to previous page',
+  nextLabel = 'Go to next page',
+  pageSizeLabel = 'Items per page',
+  className,
+  ...props
+}: TablePaginationProps) {
+  const pageCount = getPageCount(totalItems, pageSize);
+  const current = clampPage(page, pageCount);
+  const { start, end } = getRange(page, pageSize, totalItems);
+
+  const rangeText = formatRange({ start, end, total: totalItems });
+
+  const anchorMode = Boolean(getPageHref);
+  const showNav = anchorMode || Boolean(onPageChange);
+  const isFirst = current <= 1;
+  const isLast = current >= pageCount;
+
+  return (
+    <div
+      data-slot="table-pagination"
+      className={cn('flex items-center justify-between gap-4', className)}
+      {...props}
+    >
+      <span className="text-muted-foreground text-sm tabular-nums">{rangeText}</span>
+
+      {(onPageSizeChange || showNav) && (
+        <div className="flex items-center gap-4">
+          {onPageSizeChange && (
+            <div className="flex items-center gap-2">
+              <span className="text-muted-foreground text-sm">{pageSizeLabel}</span>
+              <Select value={pageSize} onValueChange={(value) => onPageSizeChange(Number(value))}>
+                <SelectTrigger size="sm" aria-label={pageSizeLabel} className="w-fit">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectGroup>
+                    {pageSizeOptions.map((size) => (
+                      <SelectItem key={size} value={size}>
+                        {size}
+                      </SelectItem>
+                    ))}
+                  </SelectGroup>
+                </SelectContent>
+              </Select>
+            </div>
+          )}
+
+          {showNav && (
+            // Only the prev/next group is a navigation landmark — not the range
+            // text or size selector. Mirrors the shadcn pagination atom's
+            // role="navigation" + aria-label.
+            <nav aria-label={navLabel} className="flex items-center gap-1">
+              <NavButton
+                slot="table-pagination-previous"
+                anchor={anchorMode}
+                disabled={isFirst}
+                label={previousLabel}
+                href={anchorMode && !isFirst ? getPageHref?.(current - 1) : undefined}
+                onClick={onPageChange ? () => onPageChange(current - 1) : undefined}
+              >
+                <ChevronLeftIcon />
+              </NavButton>
+              <NavButton
+                slot="table-pagination-next"
+                anchor={anchorMode}
+                disabled={isLast}
+                label={nextLabel}
+                href={anchorMode && !isLast ? getPageHref?.(current + 1) : undefined}
+                onClick={onPageChange ? () => onPageChange(current + 1) : undefined}
+              >
+                <ChevronRightIcon />
+              </NavButton>
+            </nav>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function NavButton({
+  slot,
+  anchor,
+  href,
+  onClick,
+  disabled,
+  label,
+  children,
+}: {
+  slot: string;
+  anchor: boolean;
+  href?: string;
+  onClick?: () => void;
+  disabled: boolean;
+  label: string;
+  children: React.ReactNode;
+}) {
+  const shared = {
+    variant: 'outline' as const,
+    size: 'icon-sm' as const,
+    'data-slot': slot,
+  };
+
+  if (anchor) {
+    // A disabled edge is a non-link (span) so it isn't focusable or followable.
+    // The icon lives inside the render element (rather than as a Button child) so
+    // the anchor's content is statically visible to the a11y linter. No aria-label
+    // on the span — naming a role-less, non-interactive element is prohibited.
+    if (disabled) {
+      return (
+        <Button
+          {...shared}
+          aria-disabled
+          nativeButton={false}
+          className="pointer-events-none opacity-50"
+          render={<span>{children}</span>}
+        />
+      );
+    }
+    return (
+      <Button
+        {...shared}
+        aria-label={label}
+        nativeButton={false}
+        render={
+          <a href={href} aria-label={label}>
+            {children}
+          </a>
+        }
+      />
+    );
+  }
+
+  return (
+    <Button {...shared} aria-label={label} disabled={disabled} onClick={onClick}>
+      {children}
+    </Button>
+  );
+}
+
+export { TablePagination, type TablePaginationProps };

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

@@ -0,0 +1,73 @@
+'use client';
+
+import { useFormatSettings } from '@vendure-io/ui/components/molecules/format-provider';
+import type { ComponentProps, ReactNode } 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 DateTimeProps extends Omit<ComponentProps<'time'>, 'dateTime'> {
+  value: string | number | Date | null | undefined;
+  locale?: string;
+  /** `Intl` date preset. Default `'medium'`. */
+  dateStyle?: Intl.DateTimeFormatOptions['dateStyle'];
+  /** `Intl` time preset. Omit for a date-only rendering. */
+  timeStyle?: Intl.DateTimeFormatOptions['timeStyle'];
+  timeZone?: string;
+  /** Escape hatch — full control, ignores `dateStyle`/`timeStyle`. */
+  formatOptions?: Intl.DateTimeFormatOptions;
+  /** Rendered for nullish/invalid input. Default `'—'`. */
+  fallback?: ReactNode;
+}
+
+/**
+ * A single semantic `<time>` — the one presentation everyone shares. Callers
+ * that want the old two-line date-over-muted-time stack compose it themselves.
+ *
+ * SSR note: output depends on locale/timeZone, so server and client renders can
+ * disagree when either falls back to the runtime default. SSR consumers should
+ * pin both via `FormatProvider` (or props) to avoid hydration mismatches.
+ */
+function DateTime({
+  value,
+  locale,
+  dateStyle,
+  timeStyle,
+  timeZone,
+  formatOptions,
+  fallback = '—',
+  ...props
+}: DateTimeProps) {
+  const settings = useFormatSettings();
+  const date = toDate(value);
+  if (!date) return <>{fallback}</>;
+
+  // Explicit wins over context: an escape-hatch `formatOptions.timeZone` must
+  // not be clobbered by the provider's zone.
+  const resolvedTimeZone = timeZone ?? formatOptions?.timeZone ?? settings.timeZone;
+  const options: Intl.DateTimeFormatOptions = {
+    ...(formatOptions ?? {
+      dateStyle: dateStyle ?? 'medium',
+      ...(timeStyle ? { timeStyle } : {}),
+    }),
+    ...(resolvedTimeZone ? { timeZone: resolvedTimeZone } : {}),
+  };
+
+  let formatted: string;
+  try {
+    formatted = new Intl.DateTimeFormat(locale ?? settings.locale, options).format(date);
+  } catch {
+    return <>{fallback}</>;
+  }
+
+  return (
+    <time data-slot="date-time" dateTime={date.toISOString()} {...props}>
+      {formatted}
+    </time>
+  );
+}
+
+export { DateTime, type DateTimeProps };

package/src/components/molecules/description-list.tsx

@@ -0,0 +1,120 @@
+'use client';
+
+import { cn } from '@vendure-io/ui/lib/utils';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { type ComponentProps, createContext, type ReactNode, useContext } from 'react';
+
+// A read-only label/value list with valid `dl`/`dt`/`dd` semantics — the
+// display counterpart to the form-oriented `field.tsx` atom. In horizontal and
+// (at container width) responsive mode, each item collapses to `display:
+// contents` so its `dt`/`dd` land directly in the list's two-column grid.
+type Orientation = 'vertical' | 'horizontal' | 'responsive';
+
+const descriptionListVariants = cva('text-sm', {
+  variants: {
+    orientation: {
+      vertical: 'flex flex-col gap-4',
+      horizontal: 'grid grid-cols-[auto_1fr] gap-x-6 gap-y-3',
+      responsive: 'flex flex-col gap-4 @md:grid @md:grid-cols-[auto_1fr] @md:gap-x-6 @md:gap-y-3',
+    },
+  },
+  defaultVariants: {
+    orientation: 'vertical',
+  },
+});
+
+const DescriptionListContext = createContext<Orientation>('vertical');
+
+function DescriptionList({
+  className,
+  orientation = 'vertical',
+  ...props
+}: ComponentProps<'dl'> & VariantProps<typeof descriptionListVariants>) {
+  const list = (
+    <dl
+      data-slot="description-list"
+      data-orientation={orientation}
+      className={cn(descriptionListVariants({ orientation }), className)}
+      {...props}
+    />
+  );
+  return (
+    <DescriptionListContext.Provider value={orientation ?? 'vertical'}>
+      {orientation === 'responsive' ? (
+        // An element cannot respond to its own container query: if the dl
+        // carried `@container`, its `@md:grid` would resolve against the nearest
+        // ANCESTOR container while the items' `@md:contents` resolve against the
+        // dl — and the two can disagree (narrow side panel inside a wide page).
+        // A wrapper div is the container, so the dl and every item query the
+        // same box.
+        <div data-slot="description-list-container" className="@container">
+          {list}
+        </div>
+      ) : (
+        list
+      )}
+    </DescriptionListContext.Provider>
+  );
+}
+
+function DescriptionItem({ className, ...props }: ComponentProps<'div'>) {
+  const orientation = useContext(DescriptionListContext);
+  return (
+    <div
+      data-slot="description-item"
+      className={cn(
+        orientation === 'horizontal' && 'contents',
+        orientation === 'responsive' && 'flex flex-col gap-0.5 @md:contents',
+        orientation === 'vertical' && 'flex flex-col gap-0.5',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function DescriptionTerm({ className, ...props }: ComponentProps<'dt'>) {
+  return (
+    <dt
+      data-slot="description-term"
+      className={cn('text-muted-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+function DescriptionDetail({ className, ...props }: ComponentProps<'dd'>) {
+  return (
+    <dd
+      data-slot="description-detail"
+      className={cn('font-medium break-words', className)}
+      {...props}
+    />
+  );
+}
+
+interface DescriptionListItemProps extends ComponentProps<'div'> {
+  label: ReactNode;
+  /** The value, deliberately children rather than a `value` prop. */
+  children: ReactNode;
+}
+
+// Sugar covering ~95% of found call sites: a term/detail pair in one line.
+function DescriptionListItem({ label, children, ...props }: DescriptionListItemProps) {
+  return (
+    <DescriptionItem {...props}>
+      <DescriptionTerm>{label}</DescriptionTerm>
+      <DescriptionDetail>{children}</DescriptionDetail>
+    </DescriptionItem>
+  );
+}
+
+export {
+  DescriptionList,
+  DescriptionItem,
+  DescriptionTerm,
+  DescriptionDetail,
+  DescriptionListItem,
+  descriptionListVariants,
+  type DescriptionListItemProps,
+};

package/src/components/molecules/format-provider.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import { createContext, type ReactNode, useContext, useMemo } from 'react';
+
+// The design system cannot depend on any app's i18n. Formatters resolve their
+// locale/currency in a fixed order — explicit prop → this context → `undefined`
+// (a valid Intl argument that falls back to the runtime default locale) — so a
+// bare `<Money>` or `<DateTime>` works with zero setup, and an app that mounts
+// `FormatProvider` (e.g. from its own locale + server config) gets consistent
+// output everywhere without threading props.
+interface FormatContextValue {
+  /** BCP 47 locale tag, e.g. `en-GB`. */
+  locale?: string;
+  /** IANA time zone, e.g. `Europe/Berlin`. */
+  timeZone?: string;
+  /** Default ISO 4217 currency code used by `<Money>` when none is passed. */
+  currency?: string;
+  /**
+   * Number of minor-unit digits money integers are stored with (Vendure's
+   * `moneyStrategyPrecision`). `undefined` → each currency's own Intl fraction
+   * digits (2 for USD, 0 for JPY, 3 for BHD).
+   */
+  currencyPrecision?: number;
+}
+
+const FormatContext = createContext<FormatContextValue>({});
+
+function FormatProvider({
+  children,
+  locale,
+  timeZone,
+  currency,
+  currencyPrecision,
+}: FormatContextValue & { children: ReactNode }) {
+  const value = useMemo(
+    () => ({ locale, timeZone, currency, currencyPrecision }),
+    [locale, timeZone, currency, currencyPrecision],
+  );
+  return <FormatContext.Provider value={value}>{children}</FormatContext.Provider>;
+}
+
+function useFormatSettings(): FormatContextValue {
+  return useContext(FormatContext);
+}
+
+export { FormatProvider, useFormatSettings, type FormatContextValue };

package/src/components/molecules/id-chip.tsx

@@ -0,0 +1,79 @@
+'use client';
+
+import { CopyButton } from '@vendure-io/ui/components/molecules/copyable-text';
+import { cn } from '@vendure-io/ui/lib/utils';
+
+type TruncateMode = 'middle' | 'start' | 'none';
+
+/**
+ * Shared chrome for the identifier-chip family (`IdChip`, `AnonymizedToken`): a
+ * bordered, `bg-muted`, monospace `text-xs` pill sized to its content. Kept in
+ * one place so the two chips can't drift apart — only their *contents* differ
+ * (a plain value vs a blurred, reveal-on-hover secret).
+ */
+function chipChromeClass(copyable: boolean, className?: string): string {
+  return cn(
+    'inline-flex w-fit items-center gap-1 rounded-md border bg-muted py-0.5 pl-1.5 font-mono text-xs',
+    copyable ? 'pr-0.5' : 'pr-1.5',
+    className,
+  );
+}
+
+// Middle truncation renders 13 chars (8 + ellipsis + 4), so anything at or
+// below that length would lose information without saving space — skip it.
+const TRUNCATE_THRESHOLD = 13;
+
+function truncateId(value: string, mode: TruncateMode): string {
+  if (mode === 'none' || value.length <= TRUNCATE_THRESHOLD) return value;
+  // Middle keeps a recognizable head + tail (proven `AnonymizedToken` pattern);
+  // start drops the (often constant) prefix and keeps the distinguishing tail.
+  return mode === 'middle' ? `${value.slice(0, 8)}…${value.slice(-4)}` : `…${value.slice(-8)}`;
+}
+
+interface IdChipProps {
+  /** The full value — always copied in full and revealed on hover via `title`. */
+  value: string;
+  /** Override the rendered text (e.g. a longer prefix). Bypasses `truncate`. */
+  display?: string;
+  /** How to shorten the rendered value. @default 'middle' */
+  truncate?: TruncateMode;
+  /** Render the copy affordance. @default true */
+  copyable?: boolean;
+  className?: string;
+  /** Called after a successful copy. Wire your toast here — the DS never toasts. */
+  onCopied?: () => void;
+}
+
+/**
+ * A bordered, monospace chip for IDs/tokens with a built-in copy affordance.
+ * The rendered text is truncated for density while the full value is copied and
+ * available on hover (`title`).
+ */
+function IdChip({
+  value,
+  display,
+  truncate = 'middle',
+  copyable = true,
+  className,
+  onCopied,
+}: IdChipProps) {
+  const text = display ?? truncateId(value, truncate);
+
+  return (
+    <span data-slot="id-chip" title={value} className={chipChromeClass(copyable, className)}>
+      <span className="truncate">{text}</span>
+      {/* 16px visual button to match the chip's density, but the ::after inset
+          extends the hit target to 24px for the WCAG 2.2 AA minimum. */}
+      {copyable ? (
+        <CopyButton
+          value={value}
+          onCopied={onCopied}
+          className="relative size-4 after:absolute after:-inset-1"
+        />
+      ) : null}
+    </span>
+  );
+}
+
+export { chipChromeClass, IdChip };
+export type { IdChipProps };

package/src/components/molecules/illustrations/access-denied.tsx

@@ -0,0 +1,55 @@
+import type { IllustrationProps } from '@vendure-io/ui/components/molecules/illustrations/illustration-types';
+import { cn } from '@vendure-io/ui/lib/utils';
+
+/**
+ * A closed padlock centered on a shield, roped off by a dashed barrier strung
+ * between two posts. For permission/authorization failures — pass as
+ * `illustration` to `ErrorState` alongside a "Go back" or "Request access"
+ * action, not a retry. Not for generic load failures (use `ErrorIllustration`)
+ * or missing resources (use `NotFoundIllustration`).
+ */
+function AccessDeniedIllustration({ className, size = 160 }: IllustrationProps) {
+  return (
+    <svg
+      viewBox="0 0 160 120"
+      width={size}
+      height={(size * 120) / 160}
+      fill="none"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+      className={cn('shrink-0', className)}
+    >
+      <ellipse cx="80" cy="104" rx="28" ry="5" className="fill-muted" />
+
+      {/* barrier posts + dashed rope, blocking the way forward */}
+      <line x1="44" y1="80" x2="44" y2="98" className="stroke-muted-foreground" />
+      <line x1="116" y1="80" x2="116" y2="98" className="stroke-muted-foreground" />
+      <path d="M44,82 Q80,96 116,82" className="stroke-border" strokeDasharray="3 4" />
+
+      {/* shield */}
+      <path
+        d="M80,24 L102,32 L102,56 C102,74 92,86 80,92 C68,86 58,74 58,56 L58,32 Z"
+        className="fill-surface stroke-muted-foreground"
+      />
+
+      {/* padlock: solid shackle + body */}
+      <path d="M74,56 v-7 a6,6 0 0,1 12,0 v7" className="stroke-muted-foreground" />
+      <rect
+        x="70"
+        y="56"
+        width="20"
+        height="17"
+        rx="3"
+        className="fill-surface stroke-muted-foreground"
+      />
+
+      {/* keyhole — the one brand accent */}
+      <circle cx="80" cy="63" r="2" className="fill-brand" />
+    </svg>
+  );
+}
+
+export { AccessDeniedIllustration };