@djangocfg/ui-core 2.1.347 → 2.1.349

package/README.md

@@ -31,7 +31,7 @@ Organized in `components/` by category — everything re-exported from the root
 | Category | Examples |
 |---|---|
 | **Forms** | `Button`, `ButtonLink`, `ButtonGroup`, `Input`, `Textarea`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `Label`, `Form`, `Field`, `InputOTP`, `PhoneInput`, `InputGroup`, `DownloadButton` |
-| **Select** | `Select`, `Combobox`, `MultiSelect`, `MultiSelectPro`, `MultiSelectProAsync`, `CountrySelect`, `LanguageSelect` (all support icons + badges; `Select` accepts empty-string values) |
+| **Select** | `Select`, `Combobox`, `ComboboxAsync`, `MultiSelect`, `MultiSelectPro`, `MultiSelectProAsync`, `CountrySelect`, `LanguageSelect` (all support icons + badges; `Select` accepts empty-string values; `ComboboxAsync` is the single-select counterpart to `MultiSelectProAsync` for server-side typeahead) |
 | **Overlay** | `Dialog`, `AlertDialog`, `Sheet`, `Drawer`, `Popover`, `Tooltip`, `HoverCard`, `ResponsiveSheet`, `SidePanel` |
 | **Navigation** | `Link`, `Breadcrumb`, `BreadcrumbNavigation`, `Pagination`, `StaticPagination`, `SSRPagination`, `Sidebar` (full shadcn primitives), `Tabs`, `Accordion`, `Collapsible`, `Command`, `DropdownMenu`, `ContextMenu`, `Menubar`, `NavigationMenu` |
 | **Layout** | `Card`, `Section`, `Sticky`, `ScrollArea`, `Resizable`, `Separator`, `Skeleton`, `AspectRatio` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.347",
+  "version": "2.1.349",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -91,7 +91,7 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.347",
+    "@djangocfg/i18n": "^2.1.349",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -150,6 +150,7 @@
     "i18n-iso-countries": "^7.14.0",
     "input-otp": "1.4.2",
     "libphonenumber-js": "^1.12.24",
+    "nextjs-toploader": "^3.9.17",
     "react-day-picker": "9.11.1",
     "react-hotkeys-hook": "^4.6.1",
     "react-resizable-panels": "3.0.6",
@@ -160,9 +161,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.347",
+    "@djangocfg/i18n": "^2.1.349",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.347",
+    "@djangocfg/typescript-config": "^2.1.349",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/select/combobox-async.story.tsx

@@ -0,0 +1,215 @@
+import { useEffect, useMemo, useState } from 'react';
+
+import { defineStory, useBoolean } from '@djangocfg/playground';
+
+import { ComboboxAsync, type ComboboxAsyncOption } from '.';
+import { Label } from '../forms/label';
+
+export default defineStory({
+  title: 'Core/ComboboxAsync',
+  component: ComboboxAsync,
+  description:
+    'Single-select combobox where the parent owns search + loading. Pairs with `MultiSelectProAsync` for the "pick one" case against a server-side typeahead endpoint.',
+});
+
+// ─── Fake "server" ──────────────────────────────────────────────────
+//
+// In real usage, ``options`` would come from an SWR / RQ hook keyed off
+// the debounced search value. For the playground we simulate latency
+// with a setTimeout so the loading affordance and seedOptions story
+// can be exercised without a real backend.
+
+interface Person {
+  id: string;
+  name: string;
+  email: string;
+  team: string;
+}
+
+const PEOPLE: Person[] = [
+  { id: 'p-1', name: 'Alice Lee', email: 'alice@x.co', team: 'Platform' },
+  { id: 'p-2', name: 'Bob Schmidt', email: 'bob@x.co', team: 'Platform' },
+  { id: 'p-3', name: 'Carla Romero', email: 'carla@x.co', team: 'Growth' },
+  { id: 'p-4', name: 'Dmitri Volkov', email: 'dmitri@x.co', team: 'Growth' },
+  { id: 'p-5', name: 'Evelyn Park', email: 'evelyn@x.co', team: 'Design' },
+  { id: 'p-6', name: 'Farah Patel', email: 'farah@x.co', team: 'Design' },
+  { id: 'p-7', name: 'Greta Hahn', email: 'greta@x.co', team: 'Engineering' },
+  { id: 'p-8', name: 'Hiro Tanaka', email: 'hiro@x.co', team: 'Engineering' },
+];
+
+function fakeSearch(query: string): Promise<Person[]> {
+  return new Promise((resolve) => {
+    const q = query.trim().toLowerCase();
+    const matches = q
+      ? PEOPLE.filter(
+          (p) =>
+            p.name.toLowerCase().includes(q) ||
+            p.email.toLowerCase().includes(q) ||
+            p.team.toLowerCase().includes(q),
+        )
+      : PEOPLE.slice(0, 6);
+    setTimeout(() => resolve(matches), 350);
+  });
+}
+
+function toOption(p: Person): ComboboxAsyncOption {
+  return {
+    value: p.id,
+    label: p.name,
+    description: `${p.email} · ${p.team}`,
+  };
+}
+
+// ─── Stories ────────────────────────────────────────────────────────
+
+export const Interactive = () => {
+  const [value, setValue] = useState<string | null>(null);
+  const [search, setSearch] = useState('');
+  const [options, setOptions] = useState<ComboboxAsyncOption[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [disabled] = useBoolean('disabled', {
+    defaultValue: false,
+    label: 'Disabled',
+    description: 'Disable picker',
+  });
+  const [clearable] = useBoolean('clearable', {
+    defaultValue: true,
+    label: 'Clearable',
+    description: 'Show inline × to reset selection',
+  });
+
+  useEffect(() => {
+    let cancelled = false;
+    setIsLoading(true);
+    void fakeSearch(search).then((rows) => {
+      if (cancelled) return;
+      setOptions(rows.map(toOption));
+      setIsLoading(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [search]);
+
+  return (
+    <div className="max-w-sm space-y-2">
+      <Label>Assignee</Label>
+      <ComboboxAsync
+        options={options}
+        value={value}
+        onValueChange={setValue}
+        searchValue={search}
+        onSearchChange={setSearch}
+        isLoading={isLoading}
+        placeholder="Pick a teammate…"
+        searchPlaceholder="Search by name, email, team…"
+        emptyText="No teammates found"
+        loadingText="Searching…"
+        disabled={disabled}
+        clearable={clearable}
+      />
+      <p className="text-xs text-muted-foreground">
+        Selected: {value ?? '∅'}
+      </p>
+    </div>
+  );
+};
+
+export const Default = Interactive;
+
+export const Loading = () => {
+  // Force ``isLoading`` true and an empty options list to show the
+  // initial spinner state — the same row that renders before the
+  // first server response lands.
+  const [value, setValue] = useState<string | null>(null);
+  const [search, setSearch] = useState('');
+
+  return (
+    <div className="max-w-sm space-y-2">
+      <Label>Assignee</Label>
+      <ComboboxAsync
+        options={[]}
+        value={value}
+        onValueChange={setValue}
+        searchValue={search}
+        onSearchChange={setSearch}
+        isLoading
+        placeholder="Pick a teammate…"
+      />
+    </div>
+  );
+};
+
+export const Empty = () => {
+  // Loaded but no matches — distinct visual from the loading row above.
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <div className="max-w-sm space-y-2">
+      <Label>Assignee</Label>
+      <ComboboxAsync
+        options={[]}
+        value={value}
+        onValueChange={setValue}
+        searchValue="zzznoresult"
+        onSearchChange={() => {}}
+        isLoading={false}
+        emptyText="No teammates found"
+      />
+    </div>
+  );
+};
+
+export const SeedOption = () => {
+  // The dialog opens with a pre-existing value whose row isn't part of
+  // the live results. ``seedOptions`` keeps the trigger from rendering
+  // a raw id while the user starts typing.
+  const [value, setValue] = useState<string | null>('p-stale');
+  const [search, setSearch] = useState('');
+  const [options, setOptions] = useState<ComboboxAsyncOption[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    setIsLoading(true);
+    void fakeSearch(search).then((rows) => {
+      if (cancelled) return;
+      setOptions(rows.map(toOption));
+      setIsLoading(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [search]);
+
+  const seedOptions = useMemo<ComboboxAsyncOption[]>(
+    () => [
+      {
+        value: 'p-stale',
+        label: 'Pre-selected (offline)',
+        description: 'Fetched once, kept around as a seed',
+      },
+    ],
+    [],
+  );
+
+  return (
+    <div className="max-w-sm space-y-2">
+      <Label>Assignee</Label>
+      <ComboboxAsync
+        options={options}
+        value={value}
+        onValueChange={setValue}
+        searchValue={search}
+        onSearchChange={setSearch}
+        isLoading={isLoading}
+        seedOptions={seedOptions}
+        placeholder="Pick a teammate…"
+      />
+      <p className="text-xs text-muted-foreground">
+        Selected id: <code>{value ?? '∅'}</code> — note the trigger shows the
+        seed label even though <code>p-stale</code> isn't in the search results.
+      </p>
+    </div>
+  );
+};

package/src/components/select/combobox-async.tsx

@@ -0,0 +1,287 @@
+"use client"
+
+import { Check, ChevronsUpDown, Loader2, X } from 'lucide-react';
+import * as React from 'react';
+
+import { useAppT } from '@djangocfg/i18n';
+import { cn } from '../../lib/utils';
+import { Badge } from '../data/badge';
+import { Button } from '../forms/button';
+import {
+  Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList
+} from '../navigation/command';
+import { Popover, PopoverContent, PopoverTrigger } from '../overlay/popover';
+
+export interface ComboboxAsyncOption {
+  value: string
+  label: string
+  description?: string
+  icon?: React.ComponentType<{ className?: string }>
+  badge?: string | React.ReactNode
+  disabled?: boolean
+}
+
+export interface ComboboxAsyncProps {
+  /**
+   * Options currently visible in the dropdown.
+   *
+   * The parent owns this list — typically a memoised projection of the
+   * latest server response keyed off ``searchValue``. The component does
+   * NOT filter ``options`` further; whatever you pass in is what shows.
+   */
+  options: ComboboxAsyncOption[]
+
+  /**
+   * Selected option id, or ``null`` when nothing is selected.
+   * Always controlled — there's no internal state, because the canonical
+   * value lives upstream (a form, a parent context, query string, …).
+   */
+  value: string | null
+
+  /** Fires with ``null`` when the user clears the selection. */
+  onValueChange: (value: string | null) => void
+
+  /**
+   * Controlled search input. Parent debounces and feeds it back into the
+   * data hook that produces ``options`` — same shape as
+   * ``MultiSelectProAsync``.
+   */
+  searchValue: string
+  onSearchChange: (value: string) => void
+
+  /** Show a spinner row + "Searching…" affordance while the parent fetch is in flight. */
+  isLoading?: boolean
+
+  /**
+   * Labels for ids that are selected but might not be present in
+   * ``options`` right now (e.g. dialog opened with a pre-filled value
+   * whose row isn't in the latest search response).
+   *
+   * Without this the trigger would show the raw id. Provide one entry per
+   * id you'd like resolved; the component falls back to the id only if
+   * neither ``options`` nor ``seedOptions`` contain it.
+   */
+  seedOptions?: ComboboxAsyncOption[]
+
+  placeholder?: string
+  searchPlaceholder?: string
+  emptyText?: string
+  loadingText?: string
+  className?: string
+  disabled?: boolean
+  /** Whether to render an inline ``×`` button on the trigger to clear. */
+  clearable?: boolean
+
+  renderOption?: (option: ComboboxAsyncOption) => React.ReactNode
+  renderValue?: (option: ComboboxAsyncOption | undefined) => React.ReactNode
+}
+
+/**
+ * Single-select combobox with parent-owned async search.
+ *
+ * Pairs with ``MultiSelectProAsync`` — same controlled-search /
+ * isLoading / seedOptions contract, just for "pick one" cases. Use
+ * this when the dataset is too large to ship to the browser up-front
+ * (typeaheads against a server-side search endpoint).
+ *
+ * For static / pre-loaded option lists use the plain ``Combobox`` —
+ * its built-in client-side filtering is the right tool there.
+ */
+export function ComboboxAsync({
+  options,
+  value,
+  onValueChange,
+  searchValue,
+  onSearchChange,
+  isLoading = false,
+  seedOptions,
+  placeholder,
+  searchPlaceholder,
+  emptyText,
+  loadingText,
+  className,
+  disabled = false,
+  clearable = true,
+  renderOption,
+  renderValue,
+}: ComboboxAsyncProps) {
+  const t = useAppT()
+  const [open, setOpen] = React.useState(false)
+  const scrollRef = React.useRef<HTMLDivElement>(null)
+
+  const resolvedPlaceholder = placeholder ?? t('ui.select.placeholder')
+  const resolvedSearchPlaceholder = searchPlaceholder ?? t('ui.select.search')
+  const resolvedEmptyText = emptyText ?? t('ui.select.noResults')
+  const resolvedLoadingText = loadingText ?? t('ui.select.loading')
+
+  // Resolve the selected option from options first (freshest label),
+  // fall back to seedOptions for the case where the value's row isn't
+  // in the current search response.
+  const selectedOption = React.useMemo<ComboboxAsyncOption | undefined>(() => {
+    if (!value) return undefined
+    return (
+      options.find((o) => o.value === value) ??
+      seedOptions?.find((o) => o.value === value)
+    )
+  }, [options, seedOptions, value])
+
+  React.useEffect(() => {
+    if (scrollRef.current && open) {
+      const el = scrollRef.current
+      el.style.cssText = `
+        max-height: 300px !important;
+        overflow-y: auto !important;
+        overflow-x: hidden !important;
+        -webkit-overflow-scrolling: touch !important;
+        overscroll-behavior: contain !important;
+      `
+    }
+  }, [open])
+
+  const handleSelect = React.useCallback(
+    (currentValue: string) => {
+      // Click again on the selected row → clear.
+      const next = currentValue === value ? null : currentValue
+      onValueChange(next)
+      setOpen(false)
+    },
+    [value, onValueChange],
+  )
+
+  const handleClear = React.useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      onValueChange(null)
+    },
+    [onValueChange],
+  )
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(isOpen) => {
+        setOpen(isOpen)
+        if (!isOpen) onSearchChange('')
+      }}
+    >
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          role="combobox"
+          aria-expanded={open}
+          className={cn(
+            "w-full justify-between",
+            !selectedOption && "text-muted-foreground",
+            className
+          )}
+          disabled={disabled}
+        >
+          {renderValue && selectedOption
+            ? renderValue(selectedOption)
+            : selectedOption
+            ? <SelectedTriggerLabel option={selectedOption} />
+            : <span className="truncate">{resolvedPlaceholder}</span>}
+          <div className="ml-2 flex shrink-0 items-center gap-1">
+            {clearable && selectedOption && !disabled ? (
+              <span
+                role="button"
+                tabIndex={-1}
+                aria-label="Clear selection"
+                onClick={handleClear}
+                onMouseDown={(e) => e.stopPropagation()}
+                className="rounded-sm p-0.5 opacity-50 transition-opacity hover:opacity-100"
+              >
+                <X className="h-4 w-4" />
+              </span>
+            ) : null}
+            <ChevronsUpDown className="h-4 w-4 opacity-50" />
+          </div>
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-[var(--radix-popover-trigger-width)] p-0" align="start">
+        <Command shouldFilter={false} className="flex flex-col">
+          <CommandInput
+            placeholder={resolvedSearchPlaceholder}
+            className="shrink-0"
+            value={searchValue}
+            onValueChange={onSearchChange}
+          />
+          <div
+            ref={scrollRef}
+            tabIndex={-1}
+            className="overflow-y-auto overflow-x-hidden"
+            style={{ maxHeight: '300px' }}
+            onWheel={(e) => e.stopPropagation()}
+          >
+            <CommandList className="!max-h-none !overflow-visible" style={{ pointerEvents: 'auto' }}>
+              {isLoading && options.length === 0 ? (
+                <div className="flex items-center gap-2 px-3 py-6 text-sm text-muted-foreground">
+                  <Loader2 className="h-4 w-4 animate-spin" />
+                  <span>{resolvedLoadingText}</span>
+                </div>
+              ) : options.length === 0 ? (
+                <CommandEmpty>{resolvedEmptyText}</CommandEmpty>
+              ) : (
+                <CommandGroup className="!overflow-visible" style={{ pointerEvents: 'auto' }}>
+                  {options.map((option) => (
+                    <CommandItem
+                      key={option.value}
+                      value={option.value}
+                      onSelect={(currentValue) => {
+                        if (!option.disabled) handleSelect(currentValue)
+                      }}
+                      disabled={option.disabled}
+                    >
+                      <Check
+                        className={cn(
+                          "mr-2 h-4 w-4 shrink-0",
+                          value === option.value ? "opacity-100" : "opacity-0"
+                        )}
+                      />
+                      {option.icon && <option.icon className="mr-2 h-4 w-4 shrink-0" />}
+                      {renderOption ? (
+                        renderOption(option)
+                      ) : (
+                        <div className="flex flex-col flex-1 min-w-0">
+                          <div className="flex items-center gap-2 truncate">
+                            <span className="truncate">{option.label}</span>
+                            {option.badge && (
+                              <Badge variant="outline" className="text-xs shrink-0">
+                                {option.badge}
+                              </Badge>
+                            )}
+                          </div>
+                          {option.description && (
+                            <span className="text-xs text-muted-foreground truncate">
+                              {option.description}
+                            </span>
+                          )}
+                        </div>
+                      )}
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              )}
+            </CommandList>
+          </div>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+function SelectedTriggerLabel({ option }: { option: ComboboxAsyncOption }) {
+  const Icon = option.icon
+  return (
+    <div className="flex min-w-0 items-center gap-2">
+      {Icon && <Icon className="h-4 w-4 shrink-0" />}
+      <span className="truncate">{option.label}</span>
+      {option.badge && (
+        <Badge variant="secondary" className="shrink-0 text-xs">
+          {option.badge}
+        </Badge>
+      )}
+    </div>
+  )
+}

package/src/components/select/index.ts

@@ -26,6 +26,10 @@ export {
 export { Combobox } from './combobox';
 export type { ComboboxOption, ComboboxProps } from './combobox';
 
+// Combobox Async (single-select with parent-owned async search)
+export { ComboboxAsync } from './combobox-async';
+export type { ComboboxAsyncOption, ComboboxAsyncProps } from './combobox-async';
+
 // MultiSelect
 export { MultiSelect } from './multi-select';
 export type { MultiSelectOption, MultiSelectProps } from './multi-select';

package/src/hooks/router/adapters/nextjs.tsx

@@ -40,7 +40,19 @@ import {
   type ReactNode,
   type Ref,
 } from 'react';
-import { useRouter as useNextRouter } from 'next/navigation';
+// Use the toploader-wrapped router so that EVERY programmatic
+// navigation through ui-core hooks (`useNavigate`, `useQueryState`,
+// `useRouter` from `@djangocfg/ui-core/hooks`) starts the
+// `nextjs-toploader` progress bar.
+//
+// Why not `next/navigation` directly: <NextTopLoader> only attaches a
+// document-level click listener for <a> tags and instruments
+// `history.pushState` to call `nprogress.done()` (NOT `.start()`). So
+// `router.push()` from `next/navigation` mutates history but never
+// starts the bar — only `<Link>` clicks do. The `nextjs-toploader/app`
+// entry exposes a thin wrapper around the same `useRouter` whose
+// `push`/`replace` call `nprogress.start()` first. Drop-in shape.
+import { useRouter as useNextRouter } from 'nextjs-toploader/app';
 import NextLink from 'next/link';
 
 import {