@bsuite/ui 1.1.0 → 1.2.0

package/README.md

@@ -169,6 +169,60 @@ import { BrandingCard, OklchColorPicker } from '@bsuite/ui'
 - `favicon_url` - Favicon URL (16x16 or 32x32)
 - `company_name` - Company name for alt text
 
+## `EntitySelector` (v1.2.0+)
+
+Generic, schema-agnostic searchable combobox for picking a row out of any
+Supabase table. Extracted from crm7 (AD-5, 2026-08-17) — crm7 had 65 files of
+adoption and two other apps had each started hand-porting their own copy at
+the identical path. This is now the sole implementation.
+
+Data access is dependency-injected — the package does not own a Supabase
+client, since every app's client is shaped differently (Vite-SPA singleton,
+per-request `createClient()` factory, distinct `storageKey`, …):
+
+```tsx
+import { EntitySelector } from '@bsuite/ui'
+import { supabase } from '@/lib/supabase' // your app's own client
+
+<EntitySelector<Employer>
+  supabaseClient={supabase}
+  table="employers"
+  value={form.employer_id}
+  onSelect={(emp) => setValue('employer_id', emp?.id ?? null)}
+  displayField={(r) => r.business_name}
+  secondaryField={(r) => r.abn ?? r.industry}
+  searchColumns={['business_name', 'trading_name', 'abn']}
+/>
+```
+
+**Recommended per-app pattern:** wrap the import once in a thin local file
+that binds your app's client, so the rest of the app's ~dozens of call sites
+never repeat `supabaseClient={supabase}`:
+
+```tsx
+// src/components/entity/EntitySelector.tsx
+import { EntitySelector as BaseEntitySelector, type EntitySelectorProps as BaseProps } from '@bsuite/ui'
+import { supabase } from '@/lib/supabase'
+
+export type EntitySelectorProps<T extends Record<string, unknown>> = Omit<BaseProps<T>, 'supabaseClient'>
+
+export function EntitySelector<T extends Record<string, unknown>>(props: EntitySelectorProps<T>) {
+  return <BaseEntitySelector<T> supabaseClient={supabase} {...props} />
+}
+```
+
+**Features:** debounced typeahead (`ilike` across configured columns),
+optional cross-schema reads (`schema` prop), a `filterFn` escape hatch for
+arbitrary PostgREST filter chains, "one-shot" suggested options (rows already
+linked on an earlier screen, shown before any typing), an async-safe
+`onSelect` (no optimistic UI when the caller's select routes through an
+import/RPC step), and a distinct error state (not the same "no results" copy
+a genuine empty search shows).
+
+Also exported for building custom pickers on the same visual language:
+`Command`, `CommandInput`, `CommandList`, `CommandGroup`, `CommandItem`,
+`CommandEmpty`, `Popover`, `PopoverTrigger`, `PopoverContent`.
+
 ## Utils
 
 ### `cn(...classes)`
@@ -198,6 +252,9 @@ import { BrandingCard, ColorEditorSheet, OklchColorPicker } from '@bsuite/ui/bra
 import { Button } from '@bsuite/ui/button'
 import { DialogContent } from '@bsuite/ui/dialog'
 import { EmptyState } from '@bsuite/ui/empty-state'
+import { EntitySelector } from '@bsuite/ui/entity-selector'
+import { Command, CommandInput } from '@bsuite/ui/command'
+import { Popover, PopoverContent } from '@bsuite/ui/popover'
 
 // SVG asset
 import logoSvg from '@bsuite/ui/assets/d2c-default-logo.svg'

package/dist/command.d.ts

@@ -0,0 +1,85 @@
+import { type DialogProps } from '@radix-ui/react-dialog';
+import * as React from 'react';
+declare const Command: React.ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "key" | keyof React.HTMLAttributes<HTMLDivElement> | "asChild"> & {
+    label?: string;
+    shouldFilter?: boolean;
+    filter?: (value: string, search: string, keywords?: string[]) => number;
+    defaultValue?: string;
+    value?: string;
+    onValueChange?: (value: string) => void;
+    loop?: boolean;
+    disablePointerSelection?: boolean;
+    vimBindings?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+interface CommandDialogProps extends DialogProps {
+    title?: string;
+    description?: string;
+}
+declare const CommandDialog: ({ children, title, description, ...props }: CommandDialogProps) => React.JSX.Element;
+declare const CommandInput: React.ForwardRefExoticComponent<Omit<Omit<Pick<Pick<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "key" | keyof React.InputHTMLAttributes<HTMLInputElement>> & {
+    ref?: React.Ref<HTMLInputElement>;
+} & {
+    asChild?: boolean;
+}, "key" | "asChild" | keyof React.InputHTMLAttributes<HTMLInputElement>>, "type" | "onChange" | "value"> & {
+    value?: string;
+    onValueChange?: (search: string) => void;
+} & React.RefAttributes<HTMLInputElement>, "ref"> & React.RefAttributes<HTMLInputElement>>;
+declare const CommandList: React.ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "key" | keyof React.HTMLAttributes<HTMLDivElement> | "asChild"> & {
+    label?: string;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandEmpty: React.ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "key" | keyof React.HTMLAttributes<HTMLDivElement> | "asChild"> & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandGroup: React.ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Omit<Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "key" | keyof React.HTMLAttributes<HTMLDivElement> | "asChild">, "heading" | "value"> & {
+    heading?: React.ReactNode;
+    value?: string;
+    forceMount?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandSeparator: React.ForwardRefExoticComponent<Omit<Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "key" | keyof React.HTMLAttributes<HTMLDivElement> | "asChild"> & {
+    alwaysRender?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandItem: React.ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Omit<Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "key" | keyof React.HTMLAttributes<HTMLDivElement> | "asChild">, "onSelect" | "disabled" | "value"> & {
+    disabled?: boolean;
+    onSelect?: (value: string) => void;
+    value?: string;
+    keywords?: string[];
+    forceMount?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandShortcut: {
+    ({ className, ...props }: React.HTMLAttributes<HTMLSpanElement>): React.JSX.Element;
+    displayName: string;
+};
+export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, };
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAGzD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;sFAYX,CAAA;AAGF,UAAU,kBAAmB,SAAQ,WAAW;IAG9C,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,QAAA,MAAM,aAAa,GAAI,4CAKpB,kBAAkB,sBAYpB,CAAA;AAED,QAAA,MAAM,YAAY;;;;;;;0FAehB,CAAA;AAIF,QAAA,MAAM,WAAW;;;;;;;;sFASf,CAAA;AAIF,QAAA,MAAM,YAAY;;;;;;uJAKhB,CAAA;AAIF,QAAA,MAAM,YAAY;;;;;;;;;;sFAYhB,CAAA;AAIF,QAAA,MAAM,gBAAgB;;;;;;sFASpB,CAAA;AAGF,QAAA,MAAM,WAAW;;;;;;;;;;;;sFAYf,CAAA;AAIF,QAAA,MAAM,eAAe;8BAA6B,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC;;CAOtF,CAAA;AAGD,OAAO,EACL,OAAO,EACP,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,eAAe,GAChB,CAAA"}

package/dist/command.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Command as CommandPrimitive } from 'cmdk';
+import { Search } from 'lucide-react';
+import * as React from 'react';
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from './dialog.js';
+import { cn } from './utils.js';
+const Command = React.forwardRef(({ className, ...props }, ref) => (_jsx(CommandPrimitive, { ref: ref, className: cn('flex h-full w-full flex-col overflow-hidden rounded-md bg-popover text-popover-foreground', className), ...props })));
+Command.displayName = CommandPrimitive.displayName;
+const CommandDialog = ({ children, title = 'Command palette', description = 'Search for commands, navigation, and actions', ...props }) => {
+    return (_jsx(Dialog, { ...props, children: _jsxs(DialogContent, { className: "overflow-hidden p-0 shadow-lg", children: [_jsx(DialogTitle, { className: "sr-only", children: title }), _jsx(DialogDescription, { className: "sr-only", children: description }), _jsx(Command, { className: "[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5", children: children })] }) }));
+};
+const CommandInput = React.forwardRef(({ className, ...props }, ref) => (_jsxs("div", { className: "flex items-center border-b px-3", "cmdk-input-wrapper": "", children: [_jsx(Search, { className: "mr-2 h-4 w-4 shrink-0 opacity-50", "aria-hidden": "true" }), _jsx(CommandPrimitive.Input, { ref: ref, className: cn('flex h-11 w-full rounded-md bg-transparent py-3 text-sm text-foreground outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50', className), ...props })] })));
+CommandInput.displayName = CommandPrimitive.Input.displayName;
+const CommandList = React.forwardRef(({ className, ...props }, ref) => (_jsx(CommandPrimitive.List, { ref: ref, className: cn('max-h-[300px] overflow-y-auto overflow-x-hidden', className), ...props })));
+CommandList.displayName = CommandPrimitive.List.displayName;
+const CommandEmpty = React.forwardRef((props, ref) => (_jsx(CommandPrimitive.Empty, { ref: ref, className: "py-6 text-center text-sm", ...props })));
+CommandEmpty.displayName = CommandPrimitive.Empty.displayName;
+const CommandGroup = React.forwardRef(({ className, ...props }, ref) => (_jsx(CommandPrimitive.Group, { ref: ref, className: cn('overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground', className), ...props })));
+CommandGroup.displayName = CommandPrimitive.Group.displayName;
+const CommandSeparator = React.forwardRef(({ className, ...props }, ref) => (_jsx(CommandPrimitive.Separator, { ref: ref, className: cn('-mx-1 h-px bg-border', className), ...props })));
+CommandSeparator.displayName = CommandPrimitive.Separator.displayName;
+const CommandItem = React.forwardRef(({ className, ...props }, ref) => (_jsx(CommandPrimitive.Item, { ref: ref, className: cn("relative flex cursor-default gap-2 select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none data-[disabled=true]:pointer-events-none data-[selected='true']:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0", className), ...props })));
+CommandItem.displayName = CommandPrimitive.Item.displayName;
+const CommandShortcut = ({ className, ...props }) => {
+    return (_jsx("span", { className: cn('ml-auto text-xs tracking-widest text-muted-foreground', className), ...props }));
+};
+CommandShortcut.displayName = 'CommandShortcut';
+export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, };

package/dist/entity-selector.d.ts

@@ -0,0 +1,252 @@
+/**
+ * EntitySelector<T>
+ *
+ * Generic searchable combobox for selecting entities from any Supabase table.
+ * Built on cmdk (Command) + Popover primitives shipped alongside this file in
+ * `@bsuite/ui`.
+ *
+ * Extracted from crm7 into `@bsuite/ui` (AD-5, 2026-08-17). crm7 had 65 files
+ * of adoption; throughput and conduit had each started hand-porting their own
+ * copy at the identical path. A shared package with the old copies still
+ * present is worse than no package at all — three divergent implementations
+ * instead of one — so this is the SOLE implementation going forward. Apps
+ * consume it directly (or via a thin per-app adapter that only binds their
+ * own Supabase client instance — see crm7's `src/components/entity/
+ * EntitySelector.tsx` for that pattern) rather than re-implementing it.
+ *
+ * Generalised out of crm7 in two ways, both required so this package does not
+ * drag a consumer's local shadcn instance or app-singleton Supabase client
+ * with it:
+ *
+ *   1. UI primitives (`Button`, `Command*`, `Popover*`, `StatusBadge`) are
+ *      this package's OWN copies (`./button.js`, `./command.js`,
+ *      `./popover.js`, `./status-badge.js`), not `@/components/ui/*` imports
+ *      reaching back into crm7. They render from the same semantic Tailwind
+ *      token classes (`bg-popover`, `text-muted-foreground`, …) every BSuite
+ *      app already shares via `@bsuite/theme`, so the rendered result is
+ *      pixel-identical to crm7's former local copy.
+ *   2. Data access (`supabaseClient`) and diagnostics (`logger`) are
+ *      dependency-injected props rather than a hardcoded `@/lib/supabase` /
+ *      `@/utils/logger` import — every app owns a differently-shaped
+ *      Supabase client (crm7: a Vite-SPA singleton; conduit: a per-request
+ *      `createClient()` factory via `@supabase/ssr`), and this package
+ *      cannot assume either.
+ *
+ * Features:
+ *   - Debounced typeahead search against Supabase (ilike across configured columns)
+ *   - Shows primary + secondary display fields per result
+ *   - Returns the full row object on select (enables auto-populate in parent forms)
+ *   - Optional "quick-add" button for inline entity creation
+ *   - For small datasets (<50 rows) loads all on open; for larger sets requires typing
+ *   - Supports external value control via `value` prop
+ *
+ * Usage:
+ *   <EntitySelector<Employer>
+ *     supabaseClient={supabase}
+ *     table="employers"
+ *     value={form.employer_id}
+ *     onSelect={(emp) => { setValue('employer_id', emp.id); autoFill(emp); }}
+ *     displayField={(r) => r.business_name}
+ *     secondaryField={(r) => r.abn ?? r.industry}
+ *     searchColumns={['business_name', 'trading_name', 'abn']}
+ *   />
+ */
+import type { PostgrestFilterBuilder } from '@supabase/postgrest-js';
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+/**
+ * Schema-agnostic Supabase filter-builder alias used by `filterFn`.
+ *
+ * `PostgrestFilterBuilder` is parameterised over the concrete DB schema,
+ * row, result, and relationship types — which the EntitySelector factory
+ * deliberately does not know at this layer (each selector wraps its own
+ * `T`). Using `any` for the four generic positions is the canonical escape
+ * hatch in `@supabase/postgrest-js` for schema-agnostic filter-builder
+ * wrappers. Centralising it here (rather than `(query: any) => any` inline)
+ * gives call sites stable input/output types so they get method completion
+ * on `.eq()` / `.in()` / `.gte()` chains and no longer need `as typeof
+ * query` casts.
+ */
+export type EntitySelectorQuery = PostgrestFilterBuilder<any, any, any, any>;
+/**
+ * Minimal diagnostics sink. Defaults to `console` so a consumer that omits
+ * `logger` still sees failures during development rather than a silent
+ * swallow; production apps typically inject their own structured logger.
+ */
+export interface EntitySelectorLogger {
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Structural shape this component needs from a Supabase client — NOT the
+ * nominal `SupabaseClient` class type from `@supabase/supabase-js`.
+ *
+ * Deliberate: this package's own `@supabase/supabase-js` (a devDependency,
+ * used only for the type) and a consumer's own `@supabase/supabase-js` (a
+ * peer dependency, resolved from THEIR lockfile) can end up as two
+ * different installed instances in a pnpm monorepo where every app pins
+ * its own floating range independently — crm7's own copy has drifted to
+ * 2.110.8 against this package's 2.108.1, for instance. TypeScript treats
+ * two structurally-identical classes sourced from different physical
+ * packages as nominally incompatible ("not assignable" even though every
+ * member matches), which would make a real consumer's real client fail to
+ * satisfy a nominal `SupabaseClient` prop type for no functional reason.
+ * A structural interface sidesteps the whole class of failure: any client
+ * with these two methods satisfies it, regardless of which supabase-js
+ * instance produced it. The query builder itself is intentionally
+ * `any`-erased past this point — see {@link EntitySelectorQuery}, the
+ * same escape hatch this component already uses for `filterFn`.
+ */
+export interface EntitySelectorSupabaseClient {
+    from: (table: string) => any;
+    schema: (schemaName: string) => {
+        from: (table: string) => any;
+    };
+}
+export interface EntitySelectorProps<T extends Record<string, unknown>> {
+    /**
+     * The consumer's own Supabase client instance. `@bsuite/ui` does not own a
+     * client — each app's client is shaped differently (singleton vs
+     * per-request factory, different `storageKey`, etc.) — so this is
+     * required rather than imported internally.
+     */
+    supabaseClient: EntitySelectorSupabaseClient;
+    /** Diagnostics sink for non-fatal query failures. Defaults to `console`. */
+    logger?: EntitySelectorLogger;
+    /** Supabase table name */
+    table: string;
+    /**
+     * Optional non-`public` Postgres schema (e.g. `'catalog'`). When set, the
+     * query is built via `supabaseClient.schema(schema).from(table)` instead
+     * of `supabaseClient.from(table)`. PostgREST embeds do not cross schema
+     * boundaries, and cross-schema reads additionally require the querying
+     * role (`authenticated`/`anon`) to hold `USAGE` on that schema, which is a
+     * DB grant this component cannot verify or fix at runtime. A failed read
+     * surfaces through the existing `error` state below (role="alert"), the
+     * same path used for a bad embed hint — never a silent "no results".
+     */
+    schema?: string;
+    /** Currently selected entity ID (controlled) */
+    value?: string;
+    /**
+     * Called with the full row when user selects; null when cleared.
+     *
+     * May return a Promise (import-on-select: a catalogue selector resolves
+     * the pick through an RPC before committing it). When it does,
+     * `handleItemSelect` below does NOT optimistically show the clicked row —
+     * see that function's comment for why an optimistic update is actively
+     * wrong for an async `onSelect`.
+     */
+    onSelect: (entity: T | null) => void | Promise<void>;
+    /** How to render the primary display text from a row */
+    displayField: (row: T) => string;
+    /** Optional secondary line (e.g. ABN, email) */
+    secondaryField?: (row: T) => string;
+    /** Columns to search via ilike */
+    searchColumns: readonly string[];
+    /** Supabase select string — supports JOINs e.g. "*, contacts(first_name)" */
+    selectColumns?: string;
+    /**
+     * Additional Supabase query filters (e.g. status eq active). Receives
+     * and returns a schema-agnostic {@link EntitySelectorQuery} so consumers
+     * get stable input/output typing and `.eq()` / `.in()` / `.gte()` method
+     * completion without needing `as typeof query` casts at each call site.
+     */
+    filterFn?: (query: EntitySelectorQuery) => EntitySelectorQuery;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Show a "+" quick-add button; callback fired on click */
+    onQuickAdd?: () => void;
+    /** Quick-add button label */
+    quickAddLabel?: string;
+    /** Min characters before searching (0 = load on open) */
+    minChars?: number;
+    /** Debounce in ms */
+    debounceMs?: number;
+    /** Max results to fetch */
+    limit?: number;
+    /** Allow clearing the selection */
+    clearable?: boolean;
+    /** Additional className for the trigger button */
+    className?: string;
+    /** Label shown in the trigger when an entity is selected */
+    selectedLabel?: string;
+    /**
+     * Notifies the parent when the selector's query state changes so the
+     * parent form can gate submission ("Resolving company…") while the
+     * typeahead is in-flight. Fires on every loading-state transition plus
+     * when the query text changes.
+     */
+    onQueryStateChange?: (state: {
+        isLoading: boolean;
+        query: string;
+    }) => void;
+    /**
+     * Optional custom row renderer. When provided, replaces the default
+     * display/secondary field layout for each result row, letting selectors
+     * visually distinguish inactive/discontinued rows.
+     *
+     * The renderer receives the row plus a selection indicator so custom
+     * implementations can still draw a check/highlight for the currently
+     * selected entity. The wrapping `<CommandItem>` (with its own click /
+     * keyboard handler) is supplied by EntitySelector — `renderRow` only
+     * renders the row's inner content.
+     */
+    renderRow?: (row: T, meta: {
+        isSelected: boolean;
+    }) => ReactNode;
+    /** Form control id for aria-labelledby */
+    id?: ComponentPropsWithoutRef<'button'>['id'];
+    /** Form control name attribute */
+    name?: ComponentPropsWithoutRef<'button'>['name'];
+    /** Form control aria-describedby */
+    'aria-describedby'?: ComponentPropsWithoutRef<'button'>['aria-describedby'];
+    /** Form control aria-invalid */
+    'aria-invalid'?: ComponentPropsWithoutRef<'button'>['aria-invalid'];
+    /** Form control aria-labelledby */
+    'aria-labelledby'?: ComponentPropsWithoutRef<'button'>['aria-labelledby'];
+    /**
+     * Import-on-select: when a selector SEARCHES one table/schema but `value`
+     * is a foreign key into a DIFFERENT table (e.g. a catalogue selector
+     * searches `catalog.qualifications` but the owning column — and
+     * therefore `value` — points at `public.qualifications`, the tenant's
+     * own copy created on select), these three let the "resolve an
+     * already-selected value" lookup target that different table instead of
+     * `table`/`schema`/`selectColumns`. Default (all three omitted) is
+     * today's behaviour: resolve from the same place search runs against —
+     * every existing caller is unaffected.
+     */
+    resolveValueTable?: string;
+    resolveValueSchema?: string;
+    resolveValueSelectColumns?: string;
+    /**
+     * ONE-SHOT: ids already linked to this record through an earlier screen.
+     *
+     * DRY is about one row in one table. This is about the USER never typing
+     * the same thing twice: the second screen in a workflow surfaces what the
+     * first screen already established, so the answer is one click rather
+     * than a search.
+     *
+     * These are fetched BY ID and shown in their own group at the top, before
+     * any typing. That matters — `minChars` means an ordinary picker shows
+     * nothing at all until the user types, which is exactly the moment they
+     * are being asked to re-derive something the system already knows.
+     * Suggested rows bypass that.
+     *
+     * This narrows nothing. The full catalogue stays searchable underneath,
+     * so a genuinely new choice is never blocked — the same
+     * advise-don't-block posture the rest of this domain runs on.
+     */
+    suggestedIds?: readonly string[];
+    /**
+     * Heading for the suggested group. Say WHERE the options came from — "From
+     * Teagan Taylor's record", "Preferred by Built Management Services" —
+     * because a bare "Suggested" gives the user no way to judge whether to
+     * trust it.
+     */
+    suggestedLabel?: string;
+}
+export declare function EntitySelector<T extends Record<string, unknown>>({ supabaseClient, logger, table, schema, value, onSelect, displayField, secondaryField, searchColumns, selectColumns, filterFn, placeholder, disabled, onQuickAdd, quickAddLabel, minChars, debounceMs, limit, clearable, className, selectedLabel, onQueryStateChange, renderRow, id, name, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-labelledby': ariaLabelledBy, resolveValueTable, resolveValueSchema, resolveValueSelectColumns, suggestedIds, suggestedLabel, }: EntitySelectorProps<T>): import("react").JSX.Element;
+export default EntitySelector;
+//# sourceMappingURL=entity-selector.d.ts.map

package/dist/entity-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-selector.d.ts","sourceRoot":"","sources":["../src/entity-selector.tsx"],"names":[],"mappings":"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"}

package/dist/entity-selector.js

@@ -0,0 +1,297 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Check, ChevronsUpDown, Loader2, Plus, X } from 'lucide-react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Button } from './button.js';
+import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, } from './command.js';
+import { Popover, PopoverContent, PopoverTrigger } from './popover.js';
+import { StatusBadge } from './status-badge.js';
+import { cn } from './utils.js';
+// ============================================================================
+// COMPONENT
+// ============================================================================
+export function EntitySelector({ supabaseClient, logger = console, table, schema, value, onSelect, displayField, secondaryField, searchColumns, selectColumns = '*', filterFn, placeholder = 'Search...', disabled = false, onQuickAdd, quickAddLabel = 'Create new', minChars = 0, debounceMs = 250, limit = 50, clearable = true, className, selectedLabel, onQueryStateChange, renderRow, id, name, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-labelledby': ariaLabelledBy, resolveValueTable, resolveValueSchema, resolveValueSelectColumns, suggestedIds, suggestedLabel = 'Already linked', }) {
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState('');
+    const [items, setItems] = useState([]);
+    const [suggestedItems, setSuggestedItems] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [selectedItem, setSelectedItem] = useState(null);
+    /**
+     * A failed search (bad `selectColumns` embed, RLS denial, network error,
+     * etc.) must not fall through to `setItems([])` with only a logger
+     * side-channel — the rendered dropdown would show the exact same
+     * `CommandEmpty` "No items found" copy as a genuine zero-result search,
+     * which is indistinguishable from the user's perspective. Tracking the
+     * error message separately lets the render below show a distinct,
+     * `role="alert"` state instead.
+     */
+    const [error, setError] = useState(null);
+    const debounceRef = useRef(null);
+    const hasLoadedInitial = useRef(false);
+    /**
+     * Returns a schema-scoped `.from(table)` builder. Defaults to the public
+     * schema (identical to the pre-existing `supabaseClient.from(table)`
+     * behaviour) unless `schema` is supplied, in which case it queries via
+     * `supabaseClient.schema(schema).from(table)` — see the `schema` prop doc.
+     *
+     * {@link EntitySelectorSupabaseClient} is structurally typed for the same
+     * reason {@link EntitySelectorQuery} is `any`-erased: this package has no
+     * generated `Database` type to parameterise against, and each consumer's
+     * own generated types differ. `.schema()` is likewise unparameterised
+     * here — a schema-agnostic escape hatch, not a typing gap introduced by
+     * this component.
+     */
+    const fromTable = useCallback(() => {
+        if (schema) {
+            return supabaseClient.schema(schema).from(table);
+        }
+        return supabaseClient.from(table);
+    }, [schema, table, supabaseClient]);
+    /**
+     * Table/schema/columns for resolving an already-selected `value` into a
+     * display row. Defaults to the search table when `resolveValueTable` is
+     * omitted — see the prop doc for why these can differ.
+     */
+    const resolveTableName = resolveValueTable ?? table;
+    const resolveSchemaName = resolveValueSchema ?? schema;
+    const resolveSelectColumns = resolveValueSelectColumns ?? selectColumns;
+    const fromResolveTable = useCallback(() => {
+        if (resolveSchemaName) {
+            return supabaseClient.schema(resolveSchemaName).from(resolveTableName);
+        }
+        return supabaseClient.from(resolveTableName);
+    }, [resolveSchemaName, resolveTableName, supabaseClient]);
+    // ── Resolve selected item from value prop ──────────────────────────────
+    useEffect(() => {
+        if (!value) {
+            setSelectedItem(null);
+            return;
+        }
+        // If we already have this item loaded, use it — but only when the
+        // search results and the resolve target are the SAME table (the
+        // `resolveValueTable` override case means `items` come from a
+        // different table than `value` points at, so a matching `id` there
+        // would be coincidental, not correct).
+        if (!resolveValueTable) {
+            const existing = items.find((i) => String(i.id) === String(value));
+            if (existing) {
+                setSelectedItem(existing);
+                return;
+            }
+        }
+        // Otherwise fetch the single entity by ID
+        let cancelled = false;
+        (async () => {
+            const { data } = await fromResolveTable()
+                .select(resolveSelectColumns)
+                .eq('id', value)
+                .single();
+            if (!cancelled && data) {
+                setSelectedItem(data);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [value, resolveValueTable, resolveTableName, resolveSelectColumns, fromResolveTable]); // eslint-disable-line react-hooks/exhaustive-deps
+    // ── Search / load items ────────────────────────────────────────────────
+    const fetchItems = useCallback(async (searchTerm) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            // Supabase `.select()` returns a narrow `PostgrestTransformBuilder`
+            // subtype that carries the concrete row schema. We widen it to the
+            // schema-agnostic {@link EntitySelectorQuery} alias so the public
+            // `filterFn` prop type (which is unparameterised by design) can
+            // consume and return it without callers needing `as` casts. The
+            // single widen-cast here replaces the casts every inner selector
+            // would otherwise need.
+            let q = fromTable().select(selectColumns);
+            // Apply custom filters
+            if (filterFn) {
+                q = filterFn(q);
+            }
+            // Apply search if term is long enough
+            if (searchTerm.length >= Math.max(minChars, 1)) {
+                const escaped = searchTerm
+                    .replace(/\\/g, '\\\\')
+                    .replace(/"/g, '\\"')
+                    .replace(/,/g, '\\,')
+                    .replace(/\(/g, '\\(')
+                    .replace(/\)/g, '\\)');
+                const term = `%${escaped}%`;
+                const orConditions = searchColumns.map((col) => `${col}.ilike.${term}`).join(',');
+                q = q.or(orConditions);
+            }
+            q = q.limit(limit);
+            const { data, error: queryError } = await q;
+            if (queryError) {
+                logger.warn(`EntitySelector(${table}): search error`, queryError.message);
+                setError(queryError.message || 'Failed to load results.');
+                setItems([]);
+                return;
+            }
+            setItems(data ?? []);
+        }
+        catch (err) {
+            logger.error(`EntitySelector(${table}): unexpected error`, err);
+            setError(err instanceof Error ? err.message : 'Failed to load results.');
+            setItems([]);
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [table, selectColumns, searchColumns, filterFn, minChars, limit, fromTable, logger]);
+    /**
+     * ONE-SHOT: fetch the already-linked rows BY ID.
+     *
+     * Deliberately a separate query from the search, for two reasons. It must not
+     * be subject to `minChars` — the whole point is that the user sees the answer
+     * without typing — and it must not be subject to `limit`, or a suggestion
+     * could fall off the end of a busy catalogue and silently stop being offered.
+     *
+     * `filterFn` is NOT applied. A suggestion is already an established link made
+     * by this user on an earlier screen; re-filtering it here could hide a row the
+     * system itself put there, which reads as the feature being broken.
+     */
+    const suggestedKey = suggestedIds?.length ? [...suggestedIds].sort().join(',') : '';
+    useEffect(() => {
+        if (!open || !suggestedKey) {
+            if (!suggestedKey)
+                setSuggestedItems([]);
+            return;
+        }
+        let cancelled = false;
+        void (async () => {
+            try {
+                const { data, error: sErr } = await fromTable()
+                    .select(selectColumns)
+                    .in('id', suggestedKey.split(','));
+                if (cancelled)
+                    return;
+                if (sErr) {
+                    // Never surface this as a page error — the catalogue below still
+                    // works, so a failed suggestion degrades to an ordinary search
+                    // rather than blocking the user.
+                    logger.warn(`EntitySelector(${table}): suggested fetch failed`, sErr.message);
+                    setSuggestedItems([]);
+                    return;
+                }
+                setSuggestedItems(data ?? []);
+            }
+            catch (err) {
+                if (!cancelled) {
+                    logger.warn(`EntitySelector(${table}): suggested fetch threw`, err);
+                    setSuggestedItems([]);
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [open, suggestedKey, fromTable, selectColumns, table, logger]);
+    /**
+     * One row, shared by the suggested group and the catalogue group.
+     *
+     * Extracted rather than duplicated: the two groups must stay visually and
+     * behaviourally identical, and a copy is how one of them quietly loses the
+     * selected-check or the `renderRow` override later.
+     */
+    const renderItem = (item) => {
+        const itemId = String(item.id);
+        const isSelected = String(value) === itemId;
+        return (_jsx(CommandItem, { value: itemId, onSelect: () => handleItemSelect(item), className: "flex items-center justify-between", children: renderRow ? (renderRow(item, { isSelected })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex flex-col min-w-0", children: [_jsx("span", { className: "font-medium truncate", children: displayField(item) }), secondaryField && (_jsx("span", { className: "text-xs text-muted-foreground truncate", children: secondaryField(item) }))] }), isSelected && _jsx(Check, { className: "h-4 w-4 shrink-0 text-primary" })] })) }, itemId));
+    };
+    // ── Load items when popover opens (for small datasets / minChars=0) ───
+    useEffect(() => {
+        if (open && !hasLoadedInitial.current) {
+            hasLoadedInitial.current = true;
+            fetchItems('');
+        }
+    }, [open, fetchItems]);
+    // ── Debounced search on query change ───────────────────────────────────
+    const handleQueryChange = useCallback((val) => {
+        setQuery(val);
+        if (debounceRef.current)
+            clearTimeout(debounceRef.current);
+        debounceRef.current = setTimeout(() => fetchItems(val), debounceMs);
+    }, [fetchItems, debounceMs]);
+    // ── Surface loading+query state upward so the parent form can gate submit ─
+    useEffect(() => {
+        if (onQueryStateChange) {
+            onQueryStateChange({ isLoading, query });
+        }
+    }, [isLoading, query, onQueryStateChange]);
+    // Cleanup debounce on unmount
+    useEffect(() => {
+        return () => {
+            if (debounceRef.current)
+                clearTimeout(debounceRef.current);
+        };
+    }, []);
+    // ── Selection handlers ─────────────────────────────────────────────────
+    /**
+     * A PRIOR version of this fix had an import-on-select consumer call the
+     * parent's `onSelect(null)` on every import-RPC failure, meant to clear a
+     * stale optimistic display. That made things worse: in EDIT mode `value`
+     * starts as the SAVED entity id, and `onSelect(null)` overwrote the
+     * parent form's state with `undefined` — wiping a link the database
+     * actually has, the exact inverse of the bug being fixed, on every failed
+     * re-pick.
+     *
+     * The real defect is here, not in the caller: this function set
+     * `selectedItem` SYNCHRONOUSLY AND OPTIMISTICALLY on every click, before
+     * `onSelect` (which may be async — see the prop doc) had any chance to
+     * fail. For a synchronous `onSelect` (the overwhelming majority of
+     * consumers) that is correct — there is no failure mode to protect
+     * against. For an async `onSelect` (routing the pick through an
+     * import-from-catalogue RPC, say), setting `selectedItem` before the
+     * round-trip resolves means: on failure, the trigger shows a row the
+     * database was never given, and it stays wrong because `value` never
+     * changed, so the "resolve selected item from value" effect (above) has
+     * nothing to react to and never corrects it.
+     *
+     * Fix: detect a thenable return and skip the optimistic update entirely.
+     * The eventual state is then driven ONLY by `value`:
+     *   - success: the async `onSelect` calls the caller's real setter with
+     *     the new (imported) id, `value` changes, the resolve-effect fetches
+     *     and displays it — one extra network round trip, correct result.
+     *   - failure: the async `onSelect` does NOT call the caller's setter,
+     *     `value` is untouched, `selectedItem` was never touched either — a
+     *     fresh form keeps showing the placeholder, an edit form keeps
+     *     showing the saved entity. Neither a false assertion nor a false
+     *     wipe.
+     */
+    const handleItemSelect = (item) => {
+        const result = onSelect(item);
+        if (!result || typeof result.then !== 'function') {
+            setSelectedItem(item);
+        }
+        setOpen(false);
+        setQuery('');
+    };
+    const handleClear = (e) => {
+        e.stopPropagation();
+        setSelectedItem(null);
+        onSelect(null);
+    };
+    // ── Render ─────────────────────────────────────────────────────────────
+    const triggerLabel = selectedItem ? (selectedLabel ?? displayField(selectedItem)) : placeholder;
+    return (_jsxs("div", { className: "flex gap-1.5", children: [_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { variant: "outline", role: "combobox", "aria-expanded": open, id: id, name: name, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-labelledby": ariaLabelledBy, disabled: disabled, className: cn('w-full justify-between font-normal', !selectedItem && 'text-muted-foreground', className), children: [_jsx("span", { className: "truncate min-w-0", children: triggerLabel }), _jsxs("div", { className: "flex items-center gap-1 ml-2 shrink-0", children: [clearable && selectedItem && (_jsx(X, { className: "h-3.5 w-3.5 opacity-50 hover:opacity-100", onClick: handleClear })), _jsx(ChevronsUpDown, { className: "h-3.5 w-3.5 opacity-50" })] })] }) }), _jsx(PopoverContent, { className: "w-[--radix-popover-trigger-width] p-0", align: "start", children: _jsxs(Command, { shouldFilter: false, children: [_jsx(CommandInput, { placeholder: placeholder, value: query, onValueChange: handleQueryChange }), _jsxs(CommandList, { children: [isLoading ? (_jsxs("div", { className: "flex items-center justify-center py-6", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin text-muted-foreground" }), _jsx("span", { className: "ml-2 text-sm text-muted-foreground", children: "Searching..." })] })) : error ? (_jsxs("div", { className: "text-center py-6 px-4 text-sm text-error-text", role: "alert", children: ["Couldn't load results: ", error] })) : items.length === 0 && suggestedItems.length === 0 ? (_jsx(CommandEmpty, { children: query.length > 0 ? `No results for "${query}"` : 'No items found' })) : (_jsxs(_Fragment, { children: [suggestedItems.length > 0 && query.length === 0 && (_jsx(CommandGroup, { heading: suggestedLabel, children: suggestedItems.map((item) => renderItem(item)) })), (() => {
+                                                    // De-dupe so a suggested row is not offered twice; showing
+                                                    // the same entity in both groups reads as two different
+                                                    // records.
+                                                    const shown = suggestedItems.length > 0 && query.length === 0
+                                                        ? items.filter((i) => !suggestedItems.some((s) => String(s.id) === String(i.id)))
+                                                        : items;
+                                                    if (shown.length === 0)
+                                                        return null;
+                                                    return (_jsx(CommandGroup, { heading: suggestedItems.length > 0 && query.length === 0
+                                                            ? 'All options'
+                                                            : undefined, children: shown.map((item) => renderItem(item)) }));
+                                                })()] })), onQuickAdd && (_jsx("div", { className: "border-t p-1", children: _jsxs(Button, { variant: "ghost", size: "sm", className: "w-full justify-start text-muted-foreground", onClick: () => {
+                                                    setOpen(false);
+                                                    onQuickAdd();
+                                                }, children: [_jsx(Plus, { className: "h-4 w-4 mr-2" }), quickAddLabel] }) })), items.length > 0 && (_jsx("div", { className: "border-t px-2 py-1.5 text-center", children: _jsxs(StatusBadge, { tone: "neutral", className: "text-[10px]", children: [items.length, items.length >= limit ? '+' : '', " result", items.length !== 1 ? 's' : ''] }) }))] })] }) })] }), onQuickAdd && (_jsxs(Button, { type: "button", variant: "outline", size: quickAddLabel && quickAddLabel.length > 12 ? 'sm' : 'icon', className: quickAddLabel && quickAddLabel.length > 12 ? 'shrink-0 whitespace-nowrap' : 'shrink-0', disabled: disabled, onClick: onQuickAdd, title: quickAddLabel, "aria-label": quickAddLabel, "data-testid": "entity-selector-quick-add", children: [_jsx(Plus, { className: "h-4 w-4" }), quickAddLabel && quickAddLabel.length > 12 ? (_jsx("span", { className: "ml-1.5 max-w-[10rem] truncate sm:max-w-none", children: quickAddLabel })) : null] }))] }));
+}
+export default EntitySelector;

package/dist/index.d.ts

@@ -11,6 +11,9 @@ export { DataUnavailable, resolveDataState, describeError, type DataUnavailableP
 export { ErrorBoundary, type ErrorBoundaryProps } from './error-boundary.js';
 export { LoadingSpinner, type LoadingSpinnerProps } from './loading-spinner.js';
 export { StatusBadge, type StatusBadgeProps, type StatusBadgeTone } from './status-badge.js';
+export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, } from './command.js';
+export { Popover, PopoverTrigger, PopoverContent } from './popover.js';
+export { EntitySelector, type EntitySelectorProps, type EntitySelectorQuery, type EntitySelectorLogger, type EntitySelectorSupabaseClient, } from './entity-selector.js';
 export { BrandingCard, ColorEditorSheet, OklchColorPicker, type BrandingCardProps, type ColorEditorSheetProps, type OklchColorPickerProps, } from './branding/index.js';
 export { sanitizeCustomCss } from './branding/sanitizeCustomCss.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACnE,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAA;AAC/B,OAAO,EACL,IAAI,EACJ,cAAc,EACd,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,OAAO,GACb,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAC5E,OAAO,EACL,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,MAAM,EACN,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACnE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC5E,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAG5F,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACnE,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAA;AAC/B,OAAO,EACL,IAAI,EACJ,cAAc,EACd,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,OAAO,GACb,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAC5E,OAAO,EACL,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,MAAM,EACN,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACnE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC5E,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAC5F,OAAO,EACL,OAAO,EACP,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,eAAe,GAChB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AACtE,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,GAClC,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA"}

package/dist/index.js

@@ -11,6 +11,9 @@ export { DataUnavailable, resolveDataState, describeError, } from './data-unavai
 export { ErrorBoundary } from './error-boundary.js';
 export { LoadingSpinner } from './loading-spinner.js';
 export { StatusBadge } from './status-badge.js';
+export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, } from './command.js';
+export { Popover, PopoverTrigger, PopoverContent } from './popover.js';
+export { EntitySelector, } from './entity-selector.js';
 // Branding components (v0.3.0+)
 export { BrandingCard, ColorEditorSheet, OklchColorPicker, } from './branding/index.js';
 export { sanitizeCustomCss } from './branding/sanitizeCustomCss.js';

package/dist/popover.d.ts

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+declare const Popover: React.FC<PopoverPrimitive.PopoverProps>;
+declare const PopoverTrigger: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const PopoverContent: React.ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export { Popover, PopoverTrigger, PopoverContent };
+//# sourceMappingURL=popover.d.ts.map

package/dist/popover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popover.d.ts","sourceRoot":"","sources":["../src/popover.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,gBAAgB,MAAM,yBAAyB,CAAA;AAI3D,QAAA,MAAM,OAAO,yCAAwB,CAAA;AAErC,QAAA,MAAM,cAAc,gHAA2B,CAAA;AAE/C,QAAA,MAAM,cAAc,gKAgBlB,CAAA;AAGF,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAA"}

package/dist/popover.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+import { cn } from './utils.js';
+const Popover = PopoverPrimitive.Root;
+const PopoverTrigger = PopoverPrimitive.Trigger;
+const PopoverContent = React.forwardRef(({ className, align = 'center', sideOffset = 4, ...props }, ref) => (_jsx(PopoverPrimitive.Portal, { children: _jsx(PopoverPrimitive.Content, { ref: ref, align: align, sideOffset: sideOffset, className: cn('z-50 w-72 rounded-md bg-popover p-4 text-popover-foreground shadow-lg outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2', className), ...props }) })));
+PopoverContent.displayName = PopoverPrimitive.Content.displayName;
+export { Popover, PopoverTrigger, PopoverContent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/ui",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -67,6 +67,18 @@
       "import": "./dist/status-badge.js",
       "types": "./dist/status-badge.d.ts"
     },
+    "./command": {
+      "import": "./dist/command.js",
+      "types": "./dist/command.d.ts"
+    },
+    "./popover": {
+      "import": "./dist/popover.js",
+      "types": "./dist/popover.d.ts"
+    },
+    "./entity-selector": {
+      "import": "./dist/entity-selector.js",
+      "types": "./dist/entity-selector.d.ts"
+    },
     "./assets/d2c-default-logo.svg": "./src/assets/d2c-default-logo.svg"
   },
   "scripts": {
@@ -78,23 +90,31 @@
   },
   "dependencies": {
     "@radix-ui/react-dialog": "^1.1.16",
+    "@radix-ui/react-popover": "^1.1.16",
     "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "lucide-react": "^1.17.0",
     "react-error-boundary": "^6.1.2",
     "tailwind-merge": "^3.6.0"
   },
   "peerDependencies": {
     "@bsuite/theme": ">=0.7.0",
+    "@supabase/postgrest-js": "^2",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
     "@bsuite/theme": {
       "optional": true
+    },
+    "@supabase/postgrest-js": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@bsuite/theme": "^0.11.0",
     "@storybook/react-vite": "^10.5.8",
+    "@supabase/postgrest-js": "^2.108.1",
     "@tailwindcss/vite": "^4.3.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",