@uipath/apollo-wind 2.55.0 → 2.56.0

package/dist/components/ui/model-picker/ModelPicker.d.ts

@@ -0,0 +1,304 @@
+import React from 'react';
+import type { ModelBadgeKind } from './badges';
+import { type ModelPickerLabels } from './labels';
+import { type FolderSwitcherFolder } from './primitives/FolderSwitcher';
+import { type PickerPopupProps } from './primitives/PickerPopup';
+import type { DiscoveryModel, ModelTag } from './types';
+import type { GroupStrategy } from './utils';
+export type ModelPickerVariant = 'searchable' | 'virtualized';
+/**
+ * Selection callback. The picker calls `onChange(model)` with the full
+ * Discovery DTO — read `model.modelId` for the id.
+ */
+export type ModelPickerChangeHandler = (model: DiscoveryModel) => void;
+/**
+ * Context handed to footer-type slots (`listFooter`, `popupFooter`).
+ * `close()` dismisses the popup — call it before navigating away so
+ * the picker doesn't linger over the next screen.
+ */
+export interface ModelPickerSlotContext {
+    selected: DiscoveryModel | null;
+    close: () => void;
+}
+export interface ModelPickerSlots {
+    /**
+     * Extra content rendered to the right of the model name in the trigger,
+     * before the caret. Example: a small "effort" badge.
+     */
+    triggerExtra?: (model: DiscoveryModel | null) => React.ReactNode;
+    /**
+     * Rendered above the search input in the popup. Use for a sticky CTA
+     * or a banner that spans the full width. Default: nothing.
+     *
+     * NOTE: for compact inline controls like a folder picker, prefer
+     * `searchLeading` — it puts the control on the same row as the search
+     * field, sharing chrome instead of stacking a separate banner.
+     */
+    popupHeader?: () => React.ReactNode;
+    /**
+     * Rendered to the left of the search field, inline with it. Use for a
+     * folder scope picker, a "filter by tag" pill, or any control that
+     * scopes the visible options.
+     */
+    searchLeading?: () => React.ReactNode;
+    /**
+     * Rendered directly under the option list, flush against the last row
+     * but inside the popup's main scroll/content region — *above* any
+     * `popupFooter`. Use for inline calls-to-action that should read as
+     * part of the list rather than a separate footer band (e.g.,
+     * `+ Add custom model` styled like a list row).
+     */
+    listFooter?: (ctx: ModelPickerSlotContext) => React.ReactNode;
+    /**
+     * Rendered below the option list in the popup, in its own banded
+     * footer with a top border + secondary background. Use for an effort
+     * picker, "Show all models" toggle, etc.
+     *
+     * When `canManageByo` is true and this slot is unset, the picker
+     * renders the default "Use custom model" CTA wired to
+     * `onUseCustomModel`. Pass a function here to replace the default
+     * footer, or `null` to suppress it entirely.
+     */
+    popupFooter?: null | ((ctx: ModelPickerSlotContext) => React.ReactNode);
+    /**
+     * Per-row meta column (renders after the model name + chips, before
+     * row actions). Use for cost bars, context window indicators, etc.
+     */
+    optionMeta?: (model: DiscoveryModel) => React.ReactNode;
+    /**
+     * Per-row right-aligned actions. The default renders edit/delete on BYO
+     * rows when `canManageByo` is true and the matching handler is wired.
+     * Pass null to suppress.
+     */
+    optionActions?: (model: DiscoveryModel) => React.ReactNode;
+}
+export interface ModelPickerProps {
+    /**
+     * The catalog to render, typically the rows the LLM Gateway Discovery API
+     * returns. The picker fetches nothing; how the host loads them is its own
+     * business.
+     */
+    models: DiscoveryModel[];
+    /** Selected `modelId`, or `null`/`undefined` for no selection. */
+    value?: string | null;
+    /**
+     * Connection id of the selected BYO model. Two BYO configurations can
+     * serve the same model name under different connections; `value` alone
+     * matches the first, so the wrong row highlights. When provided,
+     * selection also requires `byomDetails.integrationServiceConnectionId`
+     * to match. Omit for non-BYO selections.
+     */
+    valueConnectionId?: string | null;
+    /**
+     * Selection callback — receives the picked `DiscoveryModel`. See
+     * `ModelPickerChangeHandler` above for the migration note from the
+     * legacy `(modelId, model)` shape.
+     */
+    onChange?: ModelPickerChangeHandler;
+    /**
+     * Field label above the trigger. Defaults to a localized "Model".
+     *
+     * Pass `null` when the host already labels the field — a parameter row, a
+     * table cell — and a second label would be duplicate chrome. The visible
+     * label is then dropped and the trigger keeps an accessible name from
+     * `ariaLabel` (falling back to the default "Model"), so suppressing the
+     * label never costs the field its name.
+     */
+    label?: string | null;
+    /**
+     * Accessible name for the trigger when `label` is `null`. Ignored when a
+     * visible label renders — that label names the field.
+     */
+    ariaLabel?: string;
+    /**
+     * Marks the field required: a visual asterisk on the label, plus
+     * `aria-required` on the trigger, which is a `combobox` and so announces
+     * it. The search field inside the popup carries no `aria-required`.
+     */
+    required?: boolean;
+    /**
+     * Trigger text when nothing is selected. Defaults to a localized
+     * "Select a model".
+     */
+    placeholder?: string;
+    /** Disables the trigger. */
+    disabled?: boolean;
+    /** Paints the trigger border error-red and sets `aria-invalid`. */
+    invalid?: boolean;
+    /**
+     * Error message under the trigger (`role="alert"`, associated to the
+     * trigger via `aria-describedby`).
+     */
+    errorText?: string;
+    /**
+     * Which option-list renderer to use. Default: `searchable`, which
+     * renders every row but automatically switches to the virtualized
+     * renderer when more than 120 options are visible. Pass
+     * `virtualized` to force virtualization regardless of count.
+     */
+    variant?: ModelPickerVariant;
+    /**
+     * Grouping strategy. The picker holds this as internal state so the
+     * in-popup view toggle (see `allowGroupingChange`) can update it without
+     * lifting state to the host; passing a different value later resets the
+     * view to it. Default: `subscription`.
+     */
+    groupBy?: GroupStrategy;
+    /**
+     * Show the in-popup grouping pill (Category ⇆ Provider) on the
+     * toolbar. Default: `true`.
+     */
+    allowGroupingChange?: boolean;
+    /**
+     * User's home region — used to flag out-of-region models. Accepts a
+     * Discovery geography code (`'EU'`) or the raw OMS organization region
+     * exactly as PortalShell serves it (`'UnitedStates'`, `'Japan'`, …);
+     * the picker owns the OMS→geography mapping so hosts don't each
+     * maintain one. Unknown values disable out-of-region chips.
+     */
+    homeRegion?: string;
+    /**
+     * Test/storybook override for the Recommended signal. In production
+     * the signal arrives ON the Discovery DTO (`model.isRecommended`) —
+     * the backend merges `Model_hub/<product>.yaml` from
+     * `gitops-centralized-cluster` into the response, so products do NOT
+     * fetch Model_hub or pass this prop. When set (even as an empty
+     * array), only listed ids count as Recommended.
+     */
+    recommendedModelIds?: readonly string[];
+    /**
+     * Test/storybook override for the Preview signal. Production sources
+     * it from the DTO's `isPreview`.
+     */
+    previewModelIds?: readonly string[];
+    /**
+     * Per-product filter applied to the catalog *before* grouping and
+     * search. The most common per-product control: an FPS team scopes
+     * the picker to (e.g.) only models that match a given operation
+     * code, or only the ones the current user has access to. Pass a
+     * stable reference if `models` is large.
+     */
+    filter?: (model: DiscoveryModel) => boolean;
+    /**
+     * Stamp badges from the Apollo badge pool per model (e.g.
+     * `['cost-premium']`). The pool (`MODEL_BADGES` in badges.ts) owns
+     * labels, tooltips, variants, and localization so the same badge
+     * reads identically in every product; new badges are added to the
+     * pool by design-system PR, not invented per product. Pool badges
+     * render after the built-in derived tags (Recommended, Preview,
+     * Custom, Deprecating, Out-of-region, Substituted).
+     */
+    badgesFor?: (model: DiscoveryModel) => readonly ModelBadgeKind[];
+    /**
+     * Escape hatch: free-form chips appended after pool badges. Prefer
+     * `badgesFor` — use this only for experiments or one-offs pending a
+     * badge-pool addition.
+     */
+    customTagsFor?: (model: DiscoveryModel) => readonly ModelTag[];
+    /**
+     * Chip variant lookup for *new* tag kinds the host
+     * introduces via `customTagsFor`. Built-in kinds keep their existing
+     * variant. Pass to color custom tags without forking ModelTagChip,
+     * e.g. `customTagVariants={{ multimodal: 'info-mini' }}`.
+     */
+    customTagVariants?: Record<string, string>;
+    /**
+     * Whether to show the BYO management affordances (row actions +
+     * "Use custom model" footer CTA).
+     *
+     * Your authorization model decides — the platform's own rule is
+     * organization administrator, the same signal the portal uses to gate the
+     * AI Trust Layer admin pages, but the picker does not check it. Defaults to
+     * false, so the affordances stay hidden until a host opts in.
+     *
+     * A product that wants different actions can still override via
+     * `slots.optionActions`; a different footer can replace the default
+     * via `slots.popupFooter` (or `null` to suppress it).
+     */
+    canManageByo?: boolean;
+    /**
+     * Activation for the "Use custom model" footer CTA. There is no default
+     * destination; the AI Trust Layer add form is the usual one. Without this
+     * the CTA still renders, as a disabled hint, so the affordance stays
+     * discoverable. The picker closes itself before calling.
+     */
+    onUseCustomModel?: () => void;
+    /**
+     * Folders for the toolbar scope switcher, which renders when this is
+     * non-empty — typically the user's Orchestrator folders, fetched by the
+     * host. Ids are opaque to the picker: it reports the chosen one through
+     * `onFolderChange` and the host refetches.
+     */
+    folders?: readonly FolderSwitcherFolder[];
+    /**
+     * Selected folder id. `null` means the "All folders" sentinel. Leave
+     * undefined to let the picker own the selection (uncontrolled), which
+     * is useful when the folder only drives a client-side `filter`.
+     */
+    folder?: string | null;
+    /**
+     * Folder change callback. Optional when uncontrolled; required to refetch
+     * a folder-scoped catalog, since the picker fetches nothing itself.
+     */
+    onFolderChange?: (next: string | null) => void;
+    /** Label for the "All folders" sentinel. Default: `'All folders'`. */
+    allFoldersLabel?: string;
+    /** Shows a spinner in the popup while the catalog loads. */
+    loading?: boolean;
+    /**
+     * Catalog fetch error. Renders the message in the popup
+     * (`role="alert"`) and paints the trigger invalid.
+     */
+    error?: Error | null;
+    /**
+     * Show section header rows (`CUSTOM MODELS (BYO)` / `RECOMMENDED` /
+     * `PREVIEW` / `DEPRECATING SOON`) between groups. Default: `true`.
+     *
+     * Regardless of this setting, models stay ordered by group — BYO
+     * first, then Recommended, Preview, More, Deprecating.
+     */
+    showGroupHeaders?: boolean;
+    /**
+     * Portal target for the dropdown popup. Hosts that mount the picker inside a
+     * shadow root or a webview should pass their root element so the popup
+     * resolves the CSS variables scoped to it. Defaults to the nearest
+     * `PortalContainerProvider`, then `document.body`.
+     *
+     * There is deliberately no `disablePortal`: mounting a
+     * `PortalContainerProvider` around the host tree solves the same problem
+     * for every overlay at once, and is the apollo-wind convention.
+     */
+    popupContainer?: PickerPopupProps['container'];
+    /**
+     * Delete request for a BYO row. Rendered only when `canManageByo` is true;
+     * omit it and no delete action appears.
+     *
+     * The picker issues no request of its own. It shows a confirmation dialog
+     * naming the configuration, then calls this and awaits it — a rejection
+     * surfaces in the picker's own error region rather than going unhandled.
+     * **Refreshing `models` afterwards is the host's job**; the deleted row
+     * stays on screen until a new list arrives.
+     */
+    onDeleteModel?: (model: DiscoveryModel) => void | Promise<void>;
+    /**
+     * Edit activation for a BYO row. Rendered only when `canManageByo` is true.
+     * The host decides where it leads; the AI Trust Layer edit page is the
+     * usual destination.
+     */
+    onEditModel?: (model: DiscoveryModel) => void;
+    /**
+     * Overrides for the strings the picker renders. Anything omitted falls back
+     * to `DEFAULT_MODEL_PICKER_LABELS`, so an unlocalized host still shows real
+     * English rather than raw keys.
+     */
+    labels?: Partial<ModelPickerLabels>;
+    /** Extensibility slots. See `ModelPickerSlots`. */
+    slots?: ModelPickerSlots;
+    /** Rendered as `data-testid` on the picker's root element. */
+    testId?: string;
+}
+/**
+ * The forwarded ref points at the trigger button, so hosts can focus
+ * the picker programmatically (e.g. after a validation failure).
+ */
+export declare const ModelPicker: React.ForwardRefExoticComponent<ModelPickerProps & React.RefAttributes<HTMLButtonElement>>;