zidane-ui 0.0.0-stage → 9.0.2

package/src/chat/composer/ModelChainList.tsx

@@ -0,0 +1,442 @@
+/**
+ * Model chain picker: the one model list of the desktop app's composer
+ * popover and `Model` modal. Data in (the catalog, the chain,
+ * the Legacy switch), edits out; nothing here loads or persists anything.
+ *
+ * Interaction (TUI parity):
+ *   - click / ↵          make the row the PRIMARY model (position 1)
+ *   - shift+click / ⇥    add or remove the row as a fallback
+ *   - ×  on a selected row  remove it from the chain
+ *   - ctrl+shift+↑ / ↓   move the highlighted selected row one slot
+ *   - ⌥L                 the Legacy switch; ⌘1…⌘9 jump to a tab (In use, then
+ *                        each provider)
+ *   - empty query        selected rows first, in priority order, so they
+ *                        can be reviewed / removed without searching
+ *   - unknown id         typed query that matches nothing becomes a
+ *                        "use as typed" row (`xai grok-9` targets xAI)
+ *
+ * The list owns the DRAFT chain and reports it through `onChainChange`;
+ * the owner decides when to persist (the modal commits on close, the
+ * popover on dismiss or on a quick single pick).
+ *
+ * Layout: the header (`ModelChainHeader`: the search field, the caller's
+ * `toolbar` with the Legacy switch, provider pills that jump through the
+ * list: In use, then each provider), then ONE list grouped by
+ * provider under sticky headers, the current chain pinned on top as "In
+ * use" (its models are not repeated under their provider). By default
+ * each provider shows its current models only (core `currentModelKeys`:
+ * the newest version of each family); the switch lists every model, legacy
+ * ones tagged. Search always covers every model of every provider, ranked,
+ * whatever the switch says. Membership in the chain: a checked row; once two
+ * or more are selected, the In use rows lead with their 1-based priority. A
+ * pick naming no account follows its provider's active account: where the
+ * catalog lists that provider per account, it shows as the active account's
+ * row (`resolveChain`), and edits keep it unpinned (`unresolveChain`).
+ * A row with `unavailable` shows greyed out and never joins the chain.
+ * Loading, a failed load, an empty catalog and a search that matched
+ * nothing each fill the list's body with one centred line.
+ *
+ * Hundreds of models stay at frame rate: `ModelChainRows` mounts only the
+ * rows in view and places them by arithmetic (`model-list-layout`); its
+ * handlers never change, so moving the cursor renders the two rows it moves
+ * between; the scroll position lives in the list body, so scrolling renders
+ * neither the search field nor the pills.
+ */
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { positionKeyed, reorderKeyed, toggleKeyed } from 'zidane/chat/pure';
+
+import { useChatLabels } from '../useChatLabels';
+import {
+  canJoinChain,
+  lineupKeyOf,
+  modelLineup,
+  offCatalogRows,
+  pickerGroups,
+  pickRefOf,
+  refKey,
+  resolveChain,
+  rowKey,
+  unresolveChain,
+  withPrimary,
+  type ModelCatalogRow,
+  type ModelPickRef,
+  type PickerGroup,
+} from './model-catalog';
+import { layoutModelList } from './model-list-layout';
+import { ModelChainFooter, ModelChainHeader } from './ModelChainParts';
+import { ModelChainRows, type Cursor } from './ModelChainRows';
+import { ModelProviderPills } from './ModelProviderPills';
+import { useModelListSpy } from './useModelListSpy';
+
+const NO_MODELS: readonly ModelCatalogRow[] = [];
+
+/** Props for {@link ModelChainList}. */
+export interface ModelChainListProps {
+  /** Seed chain: entry 0 = current primary, 1+ = fallbacks. Empty = nothing picked yet. */
+  initialChain: readonly ModelPickRef[];
+  /** The models offered; `null` while they load. */
+  catalog: readonly ModelCatalogRow[] | null;
+  /** Why the catalog failed to load. */
+  loadError?: string | null;
+  /** Asks for the catalog again; shown as a Retry next to `loadError`. */
+  onRetry?: () => void;
+  /** List every model, not only the newest of each family. */
+  showLegacy: boolean;
+  /** Called when the user toggles the list between the newest models of each family and every model. */
+  onShowLegacyChange: (showLegacy: boolean) => void;
+  /** Every draft change, including the initial seed. */
+  onChainChange: (chain: ModelPickRef[]) => void;
+  /**
+   * A plain click / ↵ on a row while the chain has at most one entry: a
+   * quick swap, not building a chain. A popover picks and closes here.
+   */
+  onQuickPick?: (chain: ModelPickRef[]) => void;
+  /** Compact one-line rows for the popover. */
+  dense?: boolean;
+  /** One model, no chain: every pick replaces the selection and fires `onQuickPick`; no fallbacks. */
+  single?: boolean;
+  /** Max list height class. */
+  className?: string;
+  /** Inline styles on the root element, merged after the component's own. */
+  style?: CSSProperties;
+  /** Controls on the row under the search field, before the Legacy switch. */
+  toolbar?: ReactNode;
+  /** A query that matches nothing offers itself as a model id (`offCatalogRows`). Default true. */
+  customIds?: boolean;
+  /** What the list says when the catalog is empty. Default: no provider is signed in. */
+  emptyText?: string;
+  /** The search text, when the caller keeps it (shared with another list). Absent: the list keeps its own. */
+  query?: string;
+  /** Called on each edit of a caller-kept `query`. */
+  onQueryChange?: (query: string) => void;
+}
+
+/**
+ * Renders a searchable list of models for building a fallback chain: the first entry is the primary, the rest are fallbacks. A plain pick on a chain of one swaps the primary.
+ *
+ * @param props - The {@link ModelChainListProps}.
+ */
+export function ModelChainList({
+  initialChain,
+  catalog,
+  loadError = null,
+  onRetry,
+  showLegacy,
+  onShowLegacyChange,
+  onChainChange,
+  onQuickPick,
+  dense = false,
+  single = false,
+  className = '',
+  style,
+  toolbar,
+  customIds = true,
+  emptyText,
+  query: keptQuery,
+  onQueryChange,
+}: ModelChainListProps) {
+  const labels = useChatLabels();
+  const [ownQuery, setOwnQuery] = useState('');
+  const query = keptQuery ?? ownQuery;
+  const setQuery = onQueryChange ?? setOwnQuery;
+  const [cursor, setCursor] = useState<Cursor>({ index: 0, by: 'key' });
+  const [chain, setChain] = useState<ModelPickRef[]>(() => [...initialChain]);
+  /** A pill's jump, for the list body to carry out; `seq` makes a second jump to the same section a new one. */
+  const [jump, setJump] = useState<{ key: string; seq: number } | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const currentProviderKey = chain[0]?.providerKey ?? null;
+  const spy = useModelListSpy();
+
+  useEffect(() => {
+    onChainChange(chain);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- report on change only
+  }, [chain]);
+
+  useEffect(() => {
+    inputRef.current?.focus({ preventScroll: true });
+  }, []);
+
+  // The lineup ignores the draft chain on purpose: picking a legacy model
+  // pins it under "In use", it does not make it current.
+  const current = useMemo(() => modelLineup(catalog ?? NO_MODELS), [catalog]);
+  /*
+   * The chain as the catalog lists it, what the list shows and edits. The
+   * draft keeps each entry's own form, so a chain nobody touched reports
+   * itself unchanged and nothing is committed.
+   */
+  const shown = useMemo(() => resolveChain(chain, catalog ?? NO_MODELS), [chain, catalog]);
+
+  const groups = useMemo(() => {
+    if (!catalog) return [];
+    const found = pickerGroups(catalog, query, shown, showLegacy, current);
+    if (!query.trim() || !customIds) return found;
+    // A typed id can go through any signed-in provider: one row per route,
+    // first when nothing in the catalog matched, after the matches otherwise.
+    const typed = offCatalogRows(catalog, query, currentProviderKey, found.length > 0);
+    if (typed.length === 0) return found;
+    const group: PickerGroup = {
+      key: 'typed',
+      label: 'Custom id',
+      detail: typed[0]!.modelId,
+      providerKey: null,
+      rows: typed,
+      total: typed.length,
+    };
+    return found.length > 0 ? [...found, group] : [group];
+  }, [catalog, query, shown, showLegacy, current, currentProviderKey, customIds]);
+
+  /** Every row in list order; the cursor indexes this. */
+  const rows = useMemo(() => groups.flatMap((g) => g.rows), [groups]);
+  const layout = useMemo(() => layoutModelList(groups, dense), [groups, dense]);
+  /** The sections the tabs jump to: In use, then each provider (not a typed id's routes). */
+  const tabs = useMemo(
+    () => groups.filter((g) => g.key === 'in-use' || (g.providerKey !== null && g.key !== 'typed')),
+    [groups],
+  );
+  const hiddenLegacy = useMemo(() => {
+    if (!catalog || showLegacy || query.trim()) return 0;
+    return catalog.filter((e) => !current.has(lineupKeyOf(e)) && positionKeyed(shown, rowKey(e), refKey) === null)
+      .length;
+  }, [catalog, showLegacy, query, current, shown]);
+
+  // Rows that join the list after the first paint (the Legacy switch, a
+  // search) sharpen in; the first list does not animate. A row asks as it
+  // mounts, and the list notes its rows only after that commit, so a row
+  // scrolled into view later is not new.
+  const seen = useRef<Set<string> | null>(null);
+  useEffect(() => {
+    seen.current ??= new Set();
+    for (const row of rows) seen.current.add(rowKey(row));
+  }, [rows]);
+  const isNew = useCallback((key: string) => seen.current !== null && !seen.current.has(key), []);
+
+  // A shorter list (a search) keeps the cursor on its last row.
+  const lastRow = Math.max(0, rows.length - 1);
+  if (cursor.index > lastRow) setCursor({ index: lastRow, by: cursor.by });
+
+  // What the handlers below need, as of the last render: read when they run,
+  // so their identity never changes and the memoized rows don't re-render.
+  const live = useRef({ rows, chain, catalog, single, onQuickPick, layout });
+  useLayoutEffect(() => {
+    live.current = { rows, chain, catalog, single, onQuickPick, layout };
+  });
+
+  const pick = useCallback((entry: ModelCatalogRow) => {
+    if (entry.unavailable) return;
+    const { chain, catalog, single, onQuickPick } = live.current;
+    const ref = pickRefOf(entry);
+    // On the row an entry shows as, a pick changes nothing about that entry.
+    const shown = resolveChain(chain, catalog ?? NO_MODELS);
+    const next = unresolveChain(single ? [ref] : withPrimary(shown, ref), chain, shown);
+    setChain(next);
+    if (single || chain.length <= 1) onQuickPick?.(next);
+  }, []);
+
+  const toggle = useCallback(
+    (entry: ModelCatalogRow) => {
+      if (live.current.single) {
+        pick(entry);
+        return;
+      }
+      if (entry.unavailable) return;
+      const ref = pickRefOf(entry);
+      setChain((prev) => {
+        const shown = resolveChain(prev, live.current.catalog ?? NO_MODELS);
+        const member = positionKeyed(shown, refKey(ref), refKey) !== null;
+        // One account per provider: a second account of a provider in the chain can't be a fallback.
+        if (!member && !canJoinChain(shown, ref)) return prev;
+        return unresolveChain(toggleKeyed(shown, ref, refKey), prev, shown);
+      });
+    },
+    [pick],
+  );
+
+  const onHover = useCallback(
+    (index: number) => setCursor((c) => (c.index === index && c.by === 'mouse' ? c : { index, by: 'mouse' })),
+    [],
+  );
+  const onPick = useCallback(
+    (index: number, shift: boolean) => {
+      const entry = live.current.rows[index];
+      if (entry) (shift ? toggle : pick)(entry);
+    },
+    [pick, toggle],
+  );
+  const onRemove = useCallback(
+    (index: number) => {
+      const entry = live.current.rows[index];
+      if (entry) toggle(entry);
+    },
+    [toggle],
+  );
+
+  const moveCursor = (update: (index: number) => number) => {
+    spy.unpin();
+    setCursor((c) => ({ index: update(c.index), by: 'key' }));
+  };
+
+  /** Bring a group's header to the top of the list and put the cursor on its first row. */
+  const { pin } = spy;
+  const jumpTo = useCallback(
+    (key: string) => {
+      const placed = live.current.layout.groups.find((g) => g.group.key === key);
+      setJump((prev) => ({ key, seq: (prev?.seq ?? 0) + 1 }));
+      // The jump places the list: the cursor goes there without scrolling it again.
+      if (placed) setCursor({ index: placed.first, by: 'mouse' });
+      pin(key);
+      inputRef.current?.focus({ preventScroll: true });
+    },
+    [pin],
+  );
+
+  // One listener for the life of the list; it runs the latest render's handler.
+  const onKey = useRef<(e: KeyboardEvent) => void>(() => {});
+  useLayoutEffect(() => {
+    onKey.current = (e) => {
+      if (e.altKey && !e.metaKey && !e.ctrlKey && e.code === 'KeyL') {
+        e.preventDefault();
+        onShowLegacyChange(!showLegacy);
+        return;
+      }
+      if ((e.metaKey || e.ctrlKey) && !e.shiftKey && !e.altKey && /^Digit[1-9]$/.test(e.code)) {
+        const target = tabs[Number(e.code.slice(5)) - 1];
+        if (target) {
+          e.preventDefault();
+          jumpTo(target.key);
+        }
+        return;
+      }
+      if (e.ctrlKey && e.shiftKey && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
+        e.preventDefault();
+        const row = rows[cursor.index];
+        if (!row) return;
+        const key = rowKey(row);
+        const delta = e.key === 'ArrowUp' ? (-1 as const) : (1 as const);
+        setChain((prev) => {
+          const shown = resolveChain(prev, catalog ?? NO_MODELS);
+          const reordered = reorderKeyed(shown, key, delta, refKey);
+          if (reordered === shown) return prev;
+          if (!query.trim()) {
+            const served = new Set((catalog ?? []).map(rowKey));
+            const next = reordered
+              .filter((entry) => served.has(refKey(entry)))
+              .findIndex((entry) => refKey(entry) === key);
+            if (next >= 0) moveCursor(() => next);
+          }
+          return unresolveChain(reordered, prev, shown);
+        });
+        return;
+      }
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        moveCursor((c) => Math.min(Math.max(0, rows.length - 1), c + 1));
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        moveCursor((c) => Math.max(0, c - 1));
+      } else if (e.key === 'Tab' || (e.key === 'Enter' && e.shiftKey)) {
+        e.preventDefault();
+        const entry = rows[cursor.index];
+        if (entry) toggle(entry);
+      } else if (e.key === 'Enter') {
+        e.preventDefault();
+        const entry = rows[cursor.index];
+        if (entry) pick(entry);
+      }
+    };
+  });
+  useEffect(() => {
+    const listener = (e: KeyboardEvent) => onKey.current(e);
+    document.addEventListener('keydown', listener);
+    return () => document.removeEventListener('keydown', listener);
+  }, []);
+
+  const pad = dense ? 'px-3' : 'px-4';
+  // What stands in for the rows: loading, a failed load, an empty catalog, a search that matched nothing.
+  const notice = loadError
+    ? null
+    : catalog === null
+      ? labels.modelsLoading
+      : catalog.length === 0
+        ? (emptyText ?? labels.modelsNoProviders)
+        : rows.length === 0
+          ? customIds
+            ? labels.modelsTypeAnId
+            : labels.modelsNoMatch(query.trim())
+          : null;
+
+  return (
+    <div className={`zg-model-picker flex flex-col min-h-0 ${className}`} style={style}>
+      <ModelChainHeader
+        pad={pad}
+        query={query}
+        onQuery={setQuery}
+        showLegacy={showLegacy}
+        onShowLegacyChange={onShowLegacyChange}
+        toolbar={toolbar}
+        pills={
+          tabs.length > 0 ? (
+            <ModelProviderPills groups={tabs} active={spy.active} dense={dense} onJump={jumpTo} />
+          ) : undefined
+        }
+        inputRef={inputRef}
+      />
+
+      <div className="shrink-0 h-px bg-[var(--zg-hairline)]" />
+
+      {loadError || notice ? (
+        <div
+          role="status"
+          className={`flex-1 min-h-0 flex flex-col items-center justify-center gap-2 px-6 py-8 text-center text-xs ${
+            loadError ? 'text-zg-danger' : 'text-[var(--zg-text-muted)]'
+          }`}
+        >
+          {loadError ? labels.modelsLoadFailed(loadError) : notice}
+          {loadError && onRetry && (
+            <button
+              type="button"
+              className="underline text-[var(--zg-text)] bg-transparent border-0 cursor-pointer"
+              onClick={onRetry}
+            >
+              {labels.retry}
+            </button>
+          )}
+        </div>
+      ) : (
+        <ModelChainRows
+          layout={layout}
+          cursor={cursor}
+          jump={jump}
+          chain={shown}
+          current={current}
+          isNew={isNew}
+          dense={dense}
+          single={single}
+          countHidden={!showLegacy && !query.trim()}
+          onHover={onHover}
+          onPick={onPick}
+          onRemove={onRemove}
+          onSpy={spy.report}
+          onUserMove={spy.unpin}
+        />
+      )}
+
+      <ModelChainFooter
+        pad={pad}
+        single={single}
+        multi={chain.length > 1}
+        selected={chain.length}
+        hiddenLegacy={hiddenLegacy}
+        onShowLegacy={() => onShowLegacyChange(true)}
+      />
+    </div>
+  );
+}

package/src/chat/composer/ModelChainParts.tsx

@@ -0,0 +1,247 @@
+/**
+ * The model pickers' furniture: the header (the search field, the caller's
+ * toolbar with the Legacy switch, the provider pills), the section header (a
+ * provider, the pinned chain, a typed id's routes) and the footer (the keys,
+ * the hidden legacy models, how many are selected).
+ */
+import { memo, type CSSProperties, type ReactNode, type RefObject } from 'react';
+
+import { KeyCombo } from '../../components/Keycap';
+import { MenuSwitch } from '../../components/Menu';
+import { providerColor } from '../provider-color';
+import { useChatLabels } from '../useChatLabels';
+import type { PickerGroup } from './model-catalog';
+import { MODEL_HEADER_H } from './model-list-layout';
+
+/** Props for {@link ModelGroupHeader}. */
+export interface ModelGroupHeaderProps {
+  /** The section the header names. */
+  group: PickerGroup;
+  /** Models of the section the lineup hides; 0: no count. */
+  hidden: number;
+  /** Extra classes on the root element. */
+  className?: string;
+  /** Inline styles on the root element, merged after the component's own. */
+  style?: CSSProperties;
+}
+
+/** A model list's sticky section header: a provider, the pinned chain, or a typed id's routes. */
+export const ModelGroupHeader = memo(function ModelGroupHeader({
+  group,
+  hidden,
+  className,
+  style,
+}: ModelGroupHeaderProps) {
+  const labels = useChatLabels();
+  const color = group.providerKey ? providerColor(group.providerKey) : 'var(--zg-accent)';
+  return (
+    <div
+      data-group-header={group.key}
+      // Opaque so rows scroll under it; both hosts (popover, modal) float on the overlay tone.
+      // A fixed height: the list places rows by arithmetic (`model-list-layout`).
+      className={[
+        'zg-section-label sticky top-0 z-[1] flex items-center gap-2 px-2 pt-2.5 pb-1 bg-[var(--zg-overlay)]',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      style={{ height: MODEL_HEADER_H, ...style }}
+    >
+      {group.key === 'in-use' ? (
+        <span aria-hidden className="i-ph-push-pin-fill text-zg-badge text-[var(--zg-accent)]" />
+      ) : group.key === 'typed' ? (
+        <span aria-hidden className="i-ph-arrow-bend-down-right text-zg-meta text-[var(--zg-accent)]" />
+      ) : (
+        <span aria-hidden className="w-1.5 h-1.5 rounded-full" style={{ background: color }} />
+      )}
+      <span>
+        {group.key === 'in-use' ? labels.modelsInUse : group.key === 'typed' ? labels.modelsCustomId : group.label}
+      </span>
+      {group.detail && (
+        <span className="min-w-0 truncate normal-case tracking-normal font-mono font-normal text-zg-meta text-[var(--zg-text)]">
+          {group.detail}
+        </span>
+      )}
+      {hidden > 0 && (
+        <span className="zg-meta normal-case tracking-normal font-normal">
+          {labels.modelsShownOf(group.rows.length, group.total)}
+        </span>
+      )}
+    </div>
+  );
+});
+
+/** A footer key hint, drawn like the app's `KeyHint` (one chord). */
+function FooterKey({ spec }: { spec: string }) {
+  return (
+    <span className="inline-flex items-center gap-0.5 " data-size="sm">
+      <span className="contents">
+        <KeyCombo spec={spec} size="sm" />
+      </span>
+    </span>
+  );
+}
+
+/** Props for {@link ModelChainFooter}. */
+export interface ModelChainFooterProps {
+  /** Horizontal padding class, the picker's. */
+  pad: string;
+  /** One model, no chain: no fallback hint and no selected count. */
+  single: boolean;
+  /** The chain has more than one model: the count explains the order. */
+  multi: boolean;
+  /** Models in the chain. */
+  selected: number;
+  /** Legacy models the lineup hides; 0: no hint. */
+  hiddenLegacy: number;
+  /** Called when the user clicks the hidden legacy models hint. */
+  onShowLegacy: () => void;
+  /** Extra classes on the root element. */
+  className?: string;
+  /** Inline styles on the root element, merged after the component's own. */
+  style?: CSSProperties;
+}
+
+/**
+ * The model pickers' footer: the keys, the hidden legacy models, how many are selected.
+ *
+ * @param props - The {@link ModelChainFooterProps}.
+ */
+export function ModelChainFooter({
+  pad,
+  single,
+  multi,
+  selected,
+  hiddenLegacy,
+  onShowLegacy,
+  className,
+  style,
+}: ModelChainFooterProps) {
+  const labels = useChatLabels();
+  return (
+    <div
+      className={[
+        `zg-meta ${pad} py-2 shrink-0 border-t border-[var(--zg-hairline)] flex items-center gap-3`,
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      style={style}
+    >
+      <span className="inline-flex items-center gap-1.5 whitespace-nowrap">
+        <FooterKey spec="enter" />
+        {single ? labels.pickModel : labels.modelPrimary}
+      </span>
+      {!single && (
+        <span className="inline-flex items-center gap-1.5 whitespace-nowrap" title={labels.modelFallbackHint}>
+          <FooterKey spec="tab" />
+          {labels.modelFallback}
+        </span>
+      )}
+      {hiddenLegacy > 0 && (
+        <button
+          type="button"
+          onClick={onShowLegacy}
+          className="zg-meta bg-transparent border-0 p-0 cursor-pointer hover:text-[var(--zg-text)] whitespace-nowrap"
+          data-testid="model-legacy-hint"
+        >
+          {labels.modelsLegacyHidden(hiddenLegacy)}
+        </button>
+      )}
+      <span
+        hidden={single}
+        className="ml-auto whitespace-nowrap text-[var(--zg-accent)]"
+        data-testid="model-chain-count"
+        title={multi ? labels.modelChainOrderHint : undefined}
+      >
+        {labels.modelsSelected(selected)}
+      </span>
+    </div>
+  );
+}
+
+/** Props for {@link ModelChainHeader}. */
+export interface ModelChainHeaderProps {
+  /** Horizontal padding class, the picker's. */
+  pad: string;
+  /** The search field's text. */
+  query: string;
+  /** Called with the search field's text on each edit. */
+  onQuery: (query: string) => void;
+  /** The Legacy switch is on: every model is listed. */
+  showLegacy: boolean;
+  /** Called when the user toggles the Legacy switch. */
+  onShowLegacyChange: (showLegacy: boolean) => void;
+  /** Controls at the start of the row under the field. */
+  toolbar?: ReactNode;
+  /** The provider pills (`ModelProviderPills`); absent while there are no sections. */
+  pills?: ReactNode;
+  /** The field, so the list can hand focus back to it after a jump. */
+  inputRef: RefObject<HTMLInputElement | null>;
+  /** Extra classes on the root element. */
+  className?: string;
+  /** Inline styles on the root element, merged after the component's own. */
+  style?: CSSProperties;
+}
+
+/**
+ * The pickers' header, the same for every list (chat models, image models):
+ * the search field across the full width, a row with the caller's `toolbar`
+ * (the popover's Chat / Image tabs) and the Legacy switch at its end, then
+ * the provider pills. One padding around it and one gap between rows, and
+ * each row keeps its height when it is empty, so switching lists or
+ * filtering to nothing never moves the list below.
+ *
+ * @param props - The {@link ModelChainHeaderProps}.
+ */
+export function ModelChainHeader({
+  pad,
+  query,
+  onQuery,
+  showLegacy,
+  onShowLegacyChange,
+  toolbar,
+  pills,
+  inputRef,
+  className,
+  style,
+}: ModelChainHeaderProps) {
+  const labels = useChatLabels();
+  return (
+    <div className={[`${pad} py-3 shrink-0 flex flex-col gap-2`, className].filter(Boolean).join(' ')} style={style}>
+      <label className="zg-well w-full min-w-0 flex items-center gap-2 h-8 px-2.5">
+        <span aria-hidden className="i-ph-magnifying-glass text-zg-ui text-[var(--zg-text-muted)] shrink-0" />
+        <input
+          ref={inputRef}
+          value={query}
+          onChange={(e) => onQuery(e.target.value)}
+          placeholder={labels.searchModelsPlaceholder}
+          aria-label={labels.searchModels}
+          className="flex-1 min-w-0 h-full bg-transparent border-0 outline-none text-sm text-[var(--zg-text)] placeholder:text-[var(--zg-text-subtle)]"
+          spellCheck={false}
+          autoCorrect="off"
+        />
+      </label>
+      <div className="h-7 flex items-center gap-2 min-w-0">
+        {toolbar}
+        <button
+          type="button"
+          role="switch"
+          aria-checked={showLegacy}
+          aria-label={labels.modelsShowLegacy}
+          title={labels.modelsShowLegacyHint}
+          onClick={() => {
+            onShowLegacyChange(!showLegacy);
+            inputRef.current?.focus({ preventScroll: true });
+          }}
+          className="zg-segment-item zg-press-subtle ml-auto shrink-0 inline-flex items-center gap-1.5 h-7 rounded-zg-md px-2 border-0 bg-transparent cursor-pointer text-zg-meta text-[var(--zg-text-muted)]"
+        >
+          <span aria-hidden className="i-ph-clock-counter-clockwise text-zg-ui" />
+          {labels.modelsLegacy}
+          <MenuSwitch on={showLegacy} />
+        </button>
+      </div>
+      <div className="h-7 flex min-w-0">{pills}</div>
+    </div>
+  );
+}