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

package/src/components/molecules/combobox-free-text.tsx

@@ -0,0 +1,160 @@
+'use client';
+
+import { Autocomplete } from '@base-ui/react/autocomplete';
+import {
+  ComboboxContent,
+  ComboboxItem,
+  ComboboxList,
+} from '@vendure-io/ui/components/atoms/combobox';
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupInput,
+} from '@vendure-io/ui/components/atoms/input-group';
+import { Spinner } from '@vendure-io/ui/components/atoms/spinner';
+import { cn } from '@vendure-io/ui/lib/utils';
+import * as React from 'react';
+
+export interface ComboboxFreeTextItem {
+  /**
+   * The string committed to `value` when this row is chosen. Must be unique
+   * across `items`: it is used as the React key and to resolve a picked row back
+   * to its record for `onSelectItem`.
+   */
+  value: string;
+  /** Primary line of the suggestion row. */
+  label: string;
+  /** Optional secondary line. */
+  description?: string;
+}
+
+export interface ComboboxFreeTextProps<T extends ComboboxFreeTextItem = ComboboxFreeTextItem> {
+  /** The input text — the source of truth. Free-form: it need not match any item. */
+  value: string;
+  /**
+   * Fires on every keystroke and when a suggestion is chosen (with the chosen
+   * item's `value`). Always a string — never the item object, because most
+   * fires (keystrokes, free text) have no item behind them.
+   */
+  onValueChange: (value: string) => void;
+  /**
+   * Fires only when a suggestion is chosen (by click or keyboard) — never on a
+   * keystroke or free-text entry, since those have no underlying record. Hands
+   * back the full item, so attach extra fields (e.g. an `id`) to your `items`
+   * and read them here.
+   */
+  onSelectItem?: (item: T) => void;
+  /**
+   * Suggestions for the current input. The caller fetches these — typically
+   * debounced against `value` — and they are assumed to be already filtered
+   * (the component does no client-side filtering). Items may carry extra fields
+   * beyond `value`/`label`/`description`; those flow through to `onSelectItem`.
+   */
+  items: readonly T[];
+  /** Async state of the suggestion source. Shows a trailing spinner while true. */
+  loading?: boolean;
+  /** Render a suggestion row. Defaults to `label` over `description`. */
+  renderItem?: (item: T) => React.ReactNode;
+  /** id forwarded to the input. */
+  id?: string;
+  placeholder?: string;
+  /** Render the error state (sets `aria-invalid` on the input). */
+  invalid?: boolean;
+  disabled?: boolean;
+  /** Class applied to the input container. */
+  className?: string;
+}
+
+function defaultRenderItem(item: ComboboxFreeTextItem): React.ReactNode {
+  return (
+    <div className="flex min-w-0 flex-col">
+      <span className="truncate">{item.label}</span>
+      {item.description ? (
+        <span className="text-muted-foreground truncate text-xs">{item.description}</span>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * A text input with debounced, server-driven suggestions where free text wins:
+ * pick a suggestion to commit its value, or keep typing and your text is the
+ * value. A choice is never forced — Enter, blur and no-match all keep the text.
+ *
+ * Built on Base UI's `Autocomplete` (the free-text primitive — `selectionMode`
+ * is fixed to `none` and the input value is the source of truth), not the
+ * pick-only `Combobox`. `mode="none"` keeps suggestions static (no client-side
+ * filtering, since the caller pre-filters server-side) and disables
+ * inline-autocompletion. Fetching, debounce and validation live with the caller.
+ */
+function ComboboxFreeText<T extends ComboboxFreeTextItem = ComboboxFreeTextItem>({
+  value,
+  onValueChange,
+  onSelectItem,
+  items,
+  loading = false,
+  renderItem = defaultRenderItem,
+  id,
+  placeholder,
+  invalid,
+  disabled,
+  className,
+}: ComboboxFreeTextProps<T>) {
+  // Base UI opens the popup on every keystroke; we only want it open when there
+  // is something pickable, so a no-match closes it silently instead of flashing
+  // an empty box. `open` tracks the user's intent (typing, Escape, blur,
+  // select) and we AND it with "items present" to derive the rendered state.
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Autocomplete.Root
+      mode="none"
+      autoHighlight={false}
+      value={value}
+      onValueChange={(next, details) => {
+        // Call onValueChange before onSelectItem so a record captured in the
+        // latter survives any reset the value handler performs.
+        onValueChange(next);
+        // `item-press` is the only reason a row selection (mouse or keyboard)
+        // drives a value change; keystrokes and free text use other reasons.
+        // The literal is checked against Base UI's public `reason` union, so a
+        // future rename surfaces as a type error rather than silent breakage.
+        if (onSelectItem && details.reason === 'item-press') {
+          const picked = items.find((i) => i.value === next);
+          if (picked) {
+            onSelectItem(picked);
+          }
+        }
+      }}
+      open={open && items.length > 0}
+      onOpenChange={setOpen}
+      disabled={disabled}
+    >
+      <InputGroup className={cn('w-full', className)}>
+        <Autocomplete.Input
+          render={<InputGroupInput />}
+          id={id}
+          placeholder={placeholder}
+          disabled={disabled}
+          aria-invalid={invalid || undefined}
+        />
+        {loading ? (
+          <InputGroupAddon align="inline-end">
+            <Spinner />
+          </InputGroupAddon>
+        ) : null}
+      </InputGroup>
+      <ComboboxContent>
+        <ComboboxList>
+          {items.map((item) => (
+            <ComboboxItem key={item.value} value={item.value}>
+              {renderItem(item)}
+            </ComboboxItem>
+          ))}
+        </ComboboxList>
+      </ComboboxContent>
+    </Autocomplete.Root>
+  );
+}
+
+export { ComboboxFreeText };

package/src/components/molecules/confirm-dialog.tsx

@@ -0,0 +1,108 @@
+'use client';
+
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@vendure-io/ui/components/atoms/alert-dialog';
+import { Spinner } from '@vendure-io/ui/components/atoms/spinner';
+import { type ReactElement, type ReactNode, useRef, useState } from 'react';
+
+interface ConfirmDialogProps {
+  title: ReactNode;
+  description?: ReactNode;
+  /**
+   * May return a promise: the dialog then keeps itself open, disables both
+   * buttons, shows a pending spinner on the action, and closes only on resolve.
+   * A rejection leaves the dialog open so the user can retry.
+   */
+  onConfirm: () => void | Promise<void>;
+  confirmLabel?: ReactNode;
+  cancelLabel?: ReactNode;
+  variant?: 'default' | 'destructive';
+  /** Uncontrolled mode — the element that opens the dialog. */
+  children?: ReactElement;
+  /** Controlled mode — supply with `onOpenChange`. */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+function ConfirmDialog({
+  title,
+  description,
+  onConfirm,
+  confirmLabel = 'Confirm',
+  cancelLabel = 'Cancel',
+  variant = 'default',
+  children,
+  open,
+  onOpenChange,
+}: ConfirmDialogProps) {
+  const isControlled = open !== undefined;
+  const [internalOpen, setInternalOpen] = useState(false);
+  const [pending, setPending] = useState(false);
+  // State alone can't stop a fast double-click: both clicks land before the
+  // re-render disables the button, so the in-flight flag lives in a ref too.
+  const pendingRef = useRef(false);
+  const actualOpen = isControlled ? open : internalOpen;
+
+  const setOpen = (next: boolean) => {
+    if (!isControlled) setInternalOpen(next);
+    onOpenChange?.(next);
+  };
+
+  const handleConfirm = async () => {
+    if (pendingRef.current) return;
+    pendingRef.current = true;
+    try {
+      setPending(true);
+      await onConfirm();
+      setOpen(false);
+    } catch {
+      // Stay open on rejection so the user can retry or cancel.
+    } finally {
+      pendingRef.current = false;
+      setPending(false);
+    }
+  };
+
+  return (
+    <AlertDialog
+      open={actualOpen}
+      onOpenChange={(next) => {
+        // Block dismissal (escape/backdrop) while the action is in flight.
+        if (!pending) setOpen(next);
+      }}
+    >
+      {children ? <AlertDialogTrigger render={children} /> : null}
+      <AlertDialogContent data-slot="confirm-dialog">
+        <AlertDialogHeader>
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          {description ? <AlertDialogDescription>{description}</AlertDialogDescription> : null}
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel disabled={pending}>{cancelLabel}</AlertDialogCancel>
+          {/* AlertDialogAction is a plain Button (not a Close), so closing stays
+              under our control — the promise decides when the dialog leaves. */}
+          <AlertDialogAction
+            variant={variant}
+            disabled={pending}
+            aria-busy={pending || undefined}
+            onClick={handleConfirm}
+          >
+            {pending ? <Spinner /> : null}
+            {confirmLabel}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
+
+export { ConfirmDialog, type ConfirmDialogProps };

package/src/components/molecules/copyable-text.tsx

@@ -0,0 +1,102 @@
+'use client';
+
+import { Button } from '@vendure-io/ui/components/atoms/button';
+import { useCopy } from '@vendure-io/ui/hooks/use-copy';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { CheckIcon, CopyIcon } from 'lucide-react';
+import type * as React from 'react';
+
+interface CopyButtonProps extends Omit<React.ComponentProps<typeof Button>, 'value' | 'children'> {
+  /** The text written to the clipboard. */
+  value: string;
+  /** How long the check-mark feedback stays visible, in ms. @default 2000 */
+  timeout?: number;
+  /** Called after a successful copy. Wire your toast here — the DS never toasts. */
+  onCopied?: () => void;
+  /** Called when the clipboard write fails (e.g. permissions, insecure context). */
+  onCopyError?: (error: Error) => void;
+  /** Accessible label before copying. @default "Copy" */
+  copyLabel?: string;
+  /** Accessible label shown while the copied state is active. @default "Copied" */
+  copiedLabel?: string;
+}
+
+/**
+ * Ghost icon button that copies `value` and swaps its icon to a check-mark for a
+ * short window. Colours the confirmation with the semantic `text-success` token
+ * (never a raw green), per ADR 0003.
+ */
+function CopyButton({
+  value,
+  timeout,
+  onCopied,
+  onCopyError,
+  copyLabel = 'Copy',
+  copiedLabel = 'Copied',
+  variant = 'ghost',
+  size = 'icon-xs',
+  className,
+  onClick,
+  ...props
+}: CopyButtonProps) {
+  const { copied, copy } = useCopy({ timeout });
+
+  return (
+    <Button
+      type="button"
+      data-slot="copy-button"
+      variant={variant}
+      size={size}
+      aria-label={copied ? copiedLabel : copyLabel}
+      className={cn('text-muted-foreground hover:text-foreground', className)}
+      onClick={async (event) => {
+        onClick?.(event);
+        if (event.defaultPrevented) return;
+        const ok = await copy(value);
+        if (ok) onCopied?.();
+        else onCopyError?.(new Error('Failed to copy to the clipboard'));
+      }}
+      {...props}
+    >
+      {copied ? <CheckIcon className="text-success" /> : <CopyIcon />}
+    </Button>
+  );
+}
+
+interface CopyableTextProps {
+  /** The text written to the clipboard. */
+  value: string;
+  /** Content to render beside the copy button. Falls back to `value` as plain text. Styling is the consumer's. */
+  children?: React.ReactNode;
+  className?: string;
+  /** How long the check-mark feedback stays visible, in ms. @default 2000 */
+  timeout?: number;
+  /** Called after a successful copy. Wire your toast here — the DS never toasts. */
+  onCopied?: () => void;
+  /** Called when the clipboard write fails. */
+  onCopyError?: (error: Error) => void;
+}
+
+/**
+ * Renders arbitrary content alongside a {@link CopyButton}. Applies no styling
+ * to `children` — presentation is entirely the consumer's; only the layout
+ * (inline flex + gap) belongs to the molecule.
+ */
+function CopyableText({
+  value,
+  children,
+  className,
+  timeout,
+  onCopied,
+  onCopyError,
+}: CopyableTextProps) {
+  return (
+    <span data-slot="copyable-text" className={cn('inline-flex items-center gap-1.5', className)}>
+      {children ?? value}
+      <CopyButton value={value} timeout={timeout} onCopied={onCopied} onCopyError={onCopyError} />
+    </span>
+  );
+}
+
+export { CopyButton, CopyableText };
+export type { CopyButtonProps, CopyableTextProps };

package/src/components/molecules/data-table/data-table-bulk-actions.tsx

@@ -0,0 +1,69 @@
+'use client';
+
+import type { Table } from '@tanstack/react-table';
+import {
+  getSelectedOriginals,
+  getSelectedRowIds,
+} from '@vendure-io/ui/components/molecules/data-table/data-table-helpers';
+import type { DataTableBulkActionContext } from '@vendure-io/ui/components/molecules/data-table/data-table-types';
+import { cn } from '@vendure-io/ui/lib/utils';
+import * as React from 'react';
+
+// The selection overlay that replaces the controls row while rows are selected.
+// The cross-page selection cache lives here (donor parity): `rows` only ever
+// holds the current page, so we accumulate `row.original` by id as pages are
+// seen, letting `bulkActions` receive every selected original — not just the
+// ones still on screen.
+
+/**
+ * Accumulate `row.original` keyed by row id across page changes. Populated during
+ * render (idempotent map writes) so the current render's `bulkActions` can
+ * resolve the full selection synchronously.
+ */
+function useSelectionCache<TData>(table: Table<TData>): Map<string, TData> {
+  const cacheRef = React.useRef<Map<string, TData>>(new Map());
+  for (const row of table.getRowModel().rows) {
+    cacheRef.current.set(row.id, row.original);
+  }
+  return cacheRef.current;
+}
+
+interface DataTableBulkActionsProps<TData> extends React.ComponentProps<'div'> {
+  table: Table<TData>;
+  cache: Map<string, TData>;
+  render: (ctx: DataTableBulkActionContext<TData>) => React.ReactNode;
+}
+
+function DataTableBulkActions<TData>({
+  table,
+  cache,
+  render,
+  className,
+  ...props
+}: DataTableBulkActionsProps<TData>) {
+  const selection = table.getState().rowSelection;
+  const selectedRowIds = getSelectedRowIds(selection);
+  if (selectedRowIds.length === 0) return null;
+
+  const ctx: DataTableBulkActionContext<TData> = {
+    selection: getSelectedOriginals(selection, cache),
+    selectedRowIds,
+    table,
+    clearSelection: () => table.resetRowSelection(),
+  };
+
+  return (
+    <div
+      data-slot="data-table-bulk-actions"
+      className={cn(
+        'bg-muted/50 flex flex-wrap items-center gap-2 rounded-md border px-3 py-2',
+        className,
+      )}
+      {...props}
+    >
+      {render(ctx)}
+    </div>
+  );
+}
+
+export { DataTableBulkActions, useSelectionCache };

package/src/components/molecules/data-table/data-table-column-header.tsx

@@ -0,0 +1,61 @@
+'use client';
+
+import type { Column } from '@tanstack/react-table';
+import { Button } from '@vendure-io/ui/components/atoms/button';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { ArrowDownIcon, ArrowUpIcon, ChevronsUpDownIcon } from 'lucide-react';
+import type * as React from 'react';
+
+// The sortable header control rendered inside a `<TableHead>`. When the column
+// can't sort it degrades to plain text — the header stays a passive label, no
+// button, no affordance it can't honour. The `aria-sort` state lives on the
+// enclosing `<TableHead>` (set by `data-table.tsx`), not here.
+
+interface DataTableColumnHeaderProps<TData, TValue>
+  extends Omit<React.ComponentProps<'button'>, 'title'> {
+  column: Column<TData, TValue>;
+  /** Accessible name for the sort toggle, e.g. `Sort by Name`. */
+  sortLabel?: string;
+}
+
+function DataTableColumnHeader<TData, TValue>({
+  column,
+  sortLabel,
+  className,
+  children,
+  ...props
+}: DataTableColumnHeaderProps<TData, TValue>) {
+  if (!column.getCanSort()) {
+    return <span className={cn('font-medium', className)}>{children}</span>;
+  }
+
+  const sorted = column.getIsSorted();
+
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="sm"
+      data-slot="data-table-column-header"
+      aria-label={sortLabel}
+      // Tri-state cycle asc → desc → none is TanStack's default toggle (removal
+      // enabled). We only wire the click; the engine owns the state machine.
+      onClick={column.getToggleSortingHandler()}
+      className={cn('-ml-2.5 h-8 gap-1.5 data-[slot=data-table-column-header]:px-2.5', className)}
+      {...props}
+    >
+      {children}
+      {/* Active sort reads at full intensity; the idle affordance stays faint so
+          it hints without competing with the header label. */}
+      {sorted === 'asc' ? (
+        <ArrowUpIcon />
+      ) : sorted === 'desc' ? (
+        <ArrowDownIcon />
+      ) : (
+        <ChevronsUpDownIcon className="text-muted-foreground/40" />
+      )}
+    </Button>
+  );
+}
+
+export { DataTableColumnHeader };

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

@@ -0,0 +1,198 @@
+'use client';
+
+import type { Table } from '@tanstack/react-table';
+import { Button } from '@vendure-io/ui/components/atoms/button';
+import { Input } from '@vendure-io/ui/components/atoms/input';
+import { Popover, PopoverContent, PopoverTrigger } from '@vendure-io/ui/components/atoms/popover';
+import { Chip } from '@vendure-io/ui/components/molecules/chip';
+import type {
+  DataTableFilterColumn,
+  DataTableFilterValue,
+} from '@vendure-io/ui/components/molecules/data-table/data-table-types';
+import { cn } from '@vendure-io/ui/lib/utils';
+import { ChevronLeftIcon, ListFilterIcon } from 'lucide-react';
+import * as React from 'react';
+
+// The two filter surfaces. `DataTableAddFilter` is the core-owned column picker
+// + value editor (rendered only when `filters.columns` is declared).
+// `DataTableAppliedFilters` is the chip row — an applied filter is a `Chip` with
+// `onRemove`, by decision there is no `FilterChip`. Both write through the live
+// TanStack column API (`setFilterValue`), so the controlled `columnFilters`
+// state stays the single source of truth.
+
+/** The default text editor: emits `{ [firstOperator ?? 'contains']: value }`. */
+function DefaultFilterInput<TData>({
+  column,
+  value,
+  onChange,
+}: {
+  column: DataTableFilterColumn<TData>;
+  value: DataTableFilterValue | undefined;
+  onChange: (next: DataTableFilterValue | undefined) => void;
+}) {
+  const operator = column.operators?.[0] ?? 'contains';
+  const current = value?.[operator];
+
+  return (
+    <Input
+      autoFocus
+      value={typeof current === 'string' ? current : ''}
+      placeholder="Value"
+      onChange={(event) => {
+        const next = event.target.value;
+        onChange(next ? { [operator]: next } : undefined);
+      }}
+    />
+  );
+}
+
+interface DataTableAddFilterProps<TData> {
+  table: Table<TData>;
+  columns: DataTableFilterColumn<TData>[];
+  label?: string;
+}
+
+function DataTableAddFilter<TData>({
+  table,
+  columns,
+  label = 'Add filter',
+}: DataTableAddFilterProps<TData>) {
+  const [open, setOpen] = React.useState(false);
+  const [activeId, setActiveId] = React.useState<string | null>(null);
+  const active = columns.find((column) => column.id === activeId) ?? null;
+  const tableColumn = active ? table.getColumn(active.id) : undefined;
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) setActiveId(null);
+      }}
+    >
+      <PopoverTrigger
+        data-slot="data-table-add-filter"
+        render={
+          <Button variant="outline" size="sm">
+            <ListFilterIcon />
+            {label}
+          </Button>
+        }
+      />
+      <PopoverContent align="start" className="w-64 gap-2 p-2">
+        {active ? (
+          <div className="flex flex-col gap-2">
+            <button
+              type="button"
+              className="text-muted-foreground hover:text-foreground -ml-1 flex items-center gap-1 text-xs"
+              onClick={() => setActiveId(null)}
+            >
+              <ChevronLeftIcon className="size-3" />
+              {active.label}
+            </button>
+            {active.renderInput ? (
+              active.renderInput({
+                value: tableColumn?.getFilterValue() as DataTableFilterValue | undefined,
+                onChange: (next) => tableColumn?.setFilterValue(next),
+                column: active,
+              })
+            ) : (
+              <DefaultFilterInput
+                column={active}
+                value={tableColumn?.getFilterValue() as DataTableFilterValue | undefined}
+                onChange={(next) => tableColumn?.setFilterValue(next)}
+              />
+            )}
+          </div>
+        ) : (
+          <div className="flex flex-col">
+            {columns.map((column) => (
+              <Button
+                key={column.id}
+                variant="ghost"
+                size="sm"
+                className="justify-start font-normal"
+                onClick={() => setActiveId(column.id)}
+              >
+                {column.label}
+              </Button>
+            ))}
+          </div>
+        )}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+/** String form of a column label, for accessible names that need a string. */
+function labelText(label: React.ReactNode, fallback: string): string {
+  return typeof label === 'string' ? label : fallback;
+}
+
+interface DataTableAppliedFiltersProps<TData> {
+  table: Table<TData>;
+  columns?: DataTableFilterColumn<TData>[];
+  inlineChipLimit?: number;
+  removeLabel?: (columnLabel: string) => string;
+  collapsedLabel?: (count: number) => string;
+}
+
+function DataTableAppliedFilters<TData>({
+  table,
+  columns,
+  inlineChipLimit = Number.POSITIVE_INFINITY,
+  removeLabel = (columnLabel) => `Remove ${columnLabel} filter`,
+  collapsedLabel = (count) => `${count} filters`,
+}: DataTableAppliedFiltersProps<TData>) {
+  const applied = table.getState().columnFilters;
+  if (applied.length === 0) return null;
+
+  const columnMap = new Map((columns ?? []).map((column) => [column.id, column]));
+
+  const chipFor = (filter: (typeof applied)[number]) => {
+    const column = columnMap.get(filter.id);
+    const text = labelText(column?.label, filter.id);
+    const content = column?.formatChip ? (
+      column.formatChip(filter.value as DataTableFilterValue)
+    ) : (
+      <>
+        {column?.label ?? filter.id}: {JSON.stringify(filter.value)}
+      </>
+    );
+
+    return (
+      <Chip
+        key={filter.id}
+        onRemove={() => table.getColumn(filter.id)?.setFilterValue(undefined)}
+        removeLabel={removeLabel(text)}
+      >
+        {content}
+      </Chip>
+    );
+  };
+
+  const inline = applied.slice(0, inlineChipLimit);
+  const overflow = applied.slice(inlineChipLimit);
+
+  return (
+    <>
+      {inline.map(chipFor)}
+      {overflow.length > 0 && (
+        <Popover>
+          <PopoverTrigger
+            render={
+              <Button variant="outline" size="sm">
+                {collapsedLabel(overflow.length)}
+              </Button>
+            }
+          />
+          <PopoverContent align="start" className={cn('w-auto max-w-72 flex-row flex-wrap gap-2')}>
+            {overflow.map(chipFor)}
+          </PopoverContent>
+        </Popover>
+      )}
+    </>
+  );
+}
+
+export { DataTableAddFilter, DataTableAppliedFilters };