@vendure-io/ui 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vendure-io/ui",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "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",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.2.0",
-    "@vendure-io/design-tokens": "^1.1.2",
+    "@vendure-io/design-tokens": "^1.2.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",

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

@@ -0,0 +1,156 @@
+'use client';
+
+import { Autocomplete } from '@base-ui/react/autocomplete';
+import { ComboboxContent, ComboboxItem, ComboboxList } from '@vendure-io/ui/components/ui/combobox';
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupInput,
+} from '@vendure-io/ui/components/ui/input-group';
+import { Spinner } from '@vendure-io/ui/components/ui/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/custom/multi-select.tsx

@@ -0,0 +1,176 @@
+'use client';
+
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@vendure-io/ui/components/ui/select';
+import { cn } from '@vendure-io/ui/lib/utils';
+import * as React from 'react';
+
+type ItemValue = string | number;
+
+/**
+ * Describes how to read a piece of data off an item. Pass a property key — only
+ * keys whose value is assignable to `R` are allowed — or a function for full control.
+ */
+type AccessorKey<T, R> = { [K in keyof T]-?: T[K] extends R ? K : never }[keyof T];
+type Accessor<T, R> = AccessorKey<T, R> | ((item: T) => R);
+
+function resolveAccessor<T, R>(item: T, accessor: Accessor<T, R>): R {
+  return typeof accessor === 'function' ? accessor(item) : (item[accessor] as R);
+}
+
+export interface MultiSelectProps<T> {
+  /** The list of options to choose from. */
+  items: readonly T[];
+  /**
+   * How to render each option's label. Pass a property key for the common case
+   * (`itemToLabel="name"`), or a function for full control
+   * (`itemToLabel={(item) => <Flag code={item.code} />}`).
+   * @default String(item)
+   */
+  itemToLabel?: Accessor<T, React.ReactNode>;
+  /**
+   * How to derive the stable value stored in state for each option. Pass a
+   * property key (`itemToValue="id"`) or a function. Required when items are
+   * objects; for string/number items it defaults to the item itself.
+   */
+  itemToValue?: Accessor<T, ItemValue>;
+  /** Selected values. Use for controlled usage. */
+  value?: readonly ItemValue[];
+  /** Initially selected values for uncontrolled usage. */
+  defaultValue?: readonly ItemValue[];
+  /** Called with the next array of selected values whenever the selection changes. */
+  onValueChange?: (value: ItemValue[]) => void;
+  /** Text shown in the trigger when nothing is selected. */
+  placeholder?: React.ReactNode;
+  /**
+   * Override how the selected options are summarised in the trigger. Defaults
+   * to the selected labels joined with commas. Provide this when `itemToLabel`
+   * renders multi-line content, so the trigger stays a single, non-growing line.
+   */
+  renderValue?: (selectedItems: T[]) => React.ReactNode;
+  /** Disable the entire control. */
+  disabled?: boolean;
+  /** Render the error state (sets `aria-invalid` on the trigger). */
+  invalid?: boolean;
+  /** Trigger height. */
+  size?: 'sm' | 'default';
+  /** Class applied to the trigger. Defaults to a full-width, non-growing trigger; pass e.g. `w-[260px]` to fix the width. */
+  className?: string;
+  /** Class applied to the dropdown content. */
+  contentClassName?: string;
+  /** Form field name for the hidden inputs base-ui renders for each value. */
+  name?: string;
+  /** Whether a selection is required for form submission. */
+  required?: boolean;
+  /** id forwarded to the trigger. */
+  id?: string;
+}
+
+function MultiSelect<T>({
+  items,
+  itemToLabel = String as unknown as Accessor<T, React.ReactNode>,
+  itemToValue,
+  value,
+  defaultValue,
+  onValueChange,
+  placeholder = 'Select…',
+  renderValue,
+  disabled,
+  invalid,
+  size = 'default',
+  className,
+  contentClassName,
+  name,
+  required,
+  id,
+}: MultiSelectProps<T>) {
+  const getValue = React.useCallback(
+    (item: T): ItemValue =>
+      itemToValue == null ? (item as unknown as ItemValue) : resolveAccessor(item, itemToValue),
+    [itemToValue],
+  );
+  const getLabel = React.useCallback(
+    (item: T): React.ReactNode => resolveAccessor(item, itemToLabel),
+    [itemToLabel],
+  );
+
+  const itemByValue = React.useMemo(() => {
+    const map = new Map<ItemValue, T>();
+    for (const item of items) {
+      const itemValue = getValue(item);
+      if (process.env.NODE_ENV !== 'production') {
+        if (typeof itemValue !== 'string' && typeof itemValue !== 'number') {
+          console.warn(
+            'MultiSelect: `itemToValue` must resolve to a string or number. When `items` are ' +
+              'objects, pass `itemToValue` (e.g. itemToValue="id") so the selection survives the ' +
+              'items array being recreated.',
+          );
+        } else if (map.has(itemValue)) {
+          console.warn(
+            `MultiSelect: duplicate item value ${JSON.stringify(itemValue)} — each item must ` +
+              'resolve to a unique `itemToValue`; later items override earlier ones.',
+          );
+        }
+      }
+      map.set(itemValue, item);
+    }
+    return map;
+  }, [items, getValue]);
+
+  return (
+    <Select
+      multiple
+      value={value as ItemValue[] | undefined}
+      defaultValue={defaultValue as ItemValue[] | undefined}
+      onValueChange={onValueChange}
+      disabled={disabled}
+      name={name}
+      required={required}
+    >
+      {/* [vendure] default to a stable, container-width trigger so it doesn't grow with the
+          selection — the underlying SelectTrigger is `w-fit`, which we override here. */}
+      <SelectTrigger
+        id={id}
+        size={size}
+        className={cn('w-full', className)}
+        aria-invalid={invalid || undefined}
+      >
+        <SelectValue placeholder={placeholder}>
+          {(selected: ItemValue[]) => {
+            const selectedItems = selected
+              .map((v) => itemByValue.get(v))
+              .filter((item): item is T => item !== undefined);
+            if (selectedItems.length === 0) return placeholder;
+            if (renderValue) return renderValue(selectedItems);
+            return selectedItems.map((item, index) => (
+              <React.Fragment key={getValue(item)}>
+                {index > 0 ? ', ' : null}
+                {getLabel(item)}
+              </React.Fragment>
+            ));
+          }}
+        </SelectValue>
+      </SelectTrigger>
+      <SelectContent className={contentClassName}>
+        <SelectGroup>
+          {items.map((item) => {
+            const itemValue = getValue(item);
+            return (
+              <SelectItem key={itemValue} value={itemValue}>
+                {getLabel(item)}
+              </SelectItem>
+            );
+          })}
+        </SelectGroup>
+      </SelectContent>
+    </Select>
+  );
+}
+
+export { MultiSelect };

package/src/components/ui/popover.tsx

@@ -9,6 +9,10 @@ function Popover({ ...props }: PopoverPrimitive.Root.Props) {
   return <PopoverPrimitive.Root data-slot="popover" {...props} />
 }
 
+function PopoverPortal({ ...props }: PopoverPrimitive.Portal.Props) {
+  return <PopoverPrimitive.Portal data-slot="popover-portal" {...props} />
+}
+
 function PopoverTrigger({ ...props }: PopoverPrimitive.Trigger.Props) {
   return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
 }
@@ -82,6 +86,7 @@ function PopoverDescription({
 
 export {
   Popover,
+  PopoverPortal,
   PopoverContent,
   PopoverDescription,
   PopoverHeader,

package/src/lib/base-ui.ts

@@ -24,6 +24,7 @@
 
 export { Accordion as AccordionPrimitive } from '@base-ui/react/accordion';
 export { AlertDialog as AlertDialogPrimitive } from '@base-ui/react/alert-dialog';
+export { Autocomplete as AutocompletePrimitive } from '@base-ui/react/autocomplete';
 export { Avatar as AvatarPrimitive } from '@base-ui/react/avatar';
 export { Button as ButtonPrimitive } from '@base-ui/react/button';
 export { Checkbox as CheckboxPrimitive } from '@base-ui/react/checkbox';