@arbidocs/blocks 0.3.184 → 0.4.0

package/README.md

@@ -0,0 +1,100 @@
+# @arbidocs/blocks
+
+Composable, domain-neutral React UI blocks for ARBI apps: grounded chat, citations, retrieval,
+documents, facts, agents, workspaces, collaboration, auth, settings and an app shell, on top of
+`@arbidocs/react`. Parts are presentational: view-models and slots in, callbacks out. No router,
+store, query client or SDK call is baked in.
+
+## Install
+
+```sh
+npm install @arbidocs/blocks @arbidocs/react react react-dom
+```
+
+`@arbidocs/react` is a **peer dependency**. It holds the React context the blocks read
+(`useArbi`), so the host and the blocks must resolve to one copy of it. Install it yourself at the
+same version as `@arbidocs/blocks`.
+
+Optional peers, only needed for the entry that uses them:
+
+| Peer | Needed by |
+| --- | --- |
+| `@tanstack/react-query` | `@arbidocs/blocks/connect`, `@arbidocs/blocks/studio` |
+| `react-router-dom` | `@arbidocs/blocks/studio` |
+| `@measured/puck` | `@arbidocs/blocks/studio` |
+| `@playwright/test` | types of `@arbidocs/blocks/record` (no runtime import) |
+
+React 18 and 19 are supported. Every UI entry carries a `"use client"` directive, so it can be
+imported from a Next.js App Router Server Component file.
+
+## Styles (read this: without it the blocks render unstyled)
+
+The blocks are styled with Tailwind v4 utilities. Tailwind skips `node_modules` when it scans for
+class names, so you must point it at the package. Order matters:
+
+```css
+/* app.css */
+@import '@arbidocs/blocks/tokens.css';   /* 1. token defaults, light + dark */
+@import '@arbidocs/blocks/blocks.css';   /* 2. blocks helpers (declares the layer order) */
+@import '@arbidocs/blocks/grid.css';     /*    only if you use /files or /facts */
+@import 'tailwindcss';                   /* 3. Tailwind */
+@import '@arbidocs/blocks/source.css';   /* 4. tells Tailwind to scan blocks' AND react's dist */
+```
+
+`source.css` contains `@source` lines for the blocks' `dist` **and** `@arbidocs/react`'s `dist`
+(`../../react/dist` from `node_modules/@arbidocs/blocks/src`, `../../arbi-react/dist` in this
+monorepo). The react half matters: Dialog, Popover and the other primitives are defined in
+`@arbidocs/react`, and utilities such as `left-[50%]` only exist in its compiled output, so
+without it dialogs render off-screen. If your bundler resolves those paths differently, write the
+lines yourself, relative to your stylesheet:
+
+```css
+@source '../node_modules/@arbidocs/blocks/dist';
+@source '../node_modules/@arbidocs/react/dist';
+```
+
+Tailwind 4.1 or later is required (the `pointer-coarse:` variant). Dark mode is the `.dark` class
+or `[data-theme='dark']` on a parent. Studio pages also import `@arbidocs/blocks/studio.css`.
+
+## Import from a subpath
+
+Every capability is its own entry, so a bundler only loads what you use:
+
+| Entry | What | Heavy dependency |
+| --- | --- | --- |
+| `@arbidocs/blocks` | Light root: theme, primitives, chat, shell, auth, retrieval, agents, citations, collaboration, site blocks | none (zustand, dompurify) |
+| `/chat`, `/shell`, `/auth`, `/retrieval`, `/citations`, `/collaboration`, `/agents`, `/timeline`, `/site` | one capability each | none |
+| `/files`, `/facts` | document grid, facts table | `ag-grid-*` |
+| `/home`, `/workspaces` | dashboard, workspace cards and forms | `@dnd-kit/*` |
+| `/settings` | settings, billing, modals | `cmdk` |
+| `/connect` | demo/live connection layer | `@tanstack/react-query` |
+| `/studio` | Puck page builder | `@measured/puck`, router, React Query |
+| `/record` | Playwright demo-recording helpers | none at runtime |
+
+The root barrel does not re-export the heavy areas on purpose. See `docs/design/blocks-package.md`
+in the repository for per-entry sizes.
+
+## Use
+
+```tsx
+import { BlocksProvider } from '@arbidocs/blocks'
+import { PassagePill } from '@arbidocs/blocks/citations'
+
+<BlocksProvider linkComponent={RouterLink} navigate={go} notify={toast}>
+  <PassagePill icon={<DocIcon />} documentTitle="Contract" pageNumber={3} passageIndex={4} href={url} />
+</BlocksProvider>
+```
+
+- `BlocksProvider` is optional; every field has a default. Without `notify`, success and failure
+  messages (for example "link copied") go nowhere, so wire it to a toast region
+  (`role="status"` for success, `role="alert"` for errors).
+- Fixed text is a typed `labels` prop with exported `DEFAULT_*_LABELS`; test ids are overridable
+  through `testId` / `testIds`.
+- Parts are not polymorphic: `asChild` exists only where a part documents it.
+
+## Workspace isolation
+
+Blocks hold no keys and do no crypto. Parts take the data of one workspace and never merge data
+across workspaces. The few places that persist something locally (Studio local storage, the last
+selected workspace in `/connect`) are scoped per user (and workspace) and fail loudly instead of
+falling back to unscoped plaintext storage.

package/dist/agents/approvals/AuthorizeAgentParts.d.ts

@@ -0,0 +1,79 @@
+import { type ReactNode } from 'react';
+/** Every fixed string of the agent modal. */
+export interface AuthorizeAgentLabels {
+    editIntro: (agentName: string) => string;
+    mainIntro: string;
+    noAssistant: string;
+    connectExternal: string;
+    optional: string;
+    createdIntro: string;
+    email: string;
+    signingKey: string;
+    configure: string;
+    hideConfiguration: string;
+    done: string;
+    backToMain: string;
+    connectIntro: string;
+    name: string;
+    namePlaceholder: string;
+    nameHint: string;
+    workspaces: string;
+    workspacesPlaceholder: string;
+    roleTitle: string;
+    collaborator: string;
+    guest: string;
+    cancel: string;
+    create: string;
+    creating: string;
+}
+export declare const DEFAULT_AUTHORIZE_AGENT_LABELS: AuthorizeAgentLabels;
+export interface AgentEditViewProps {
+    agentName: string;
+    /** The agent's config editor (host component: it owns the data). */
+    config: ReactNode;
+    labels?: Partial<AuthorizeAgentLabels>;
+}
+/** Edit variant: straight into the config editor of an existing agent. */
+export declare function AgentEditView({ agentName, config, labels }: AgentEditViewProps): import("react").JSX.Element;
+export interface AgentMainViewProps {
+    /** The main assistant's config editor; omit when no assistant exists yet. */
+    config?: ReactNode;
+    onConnectExternal: () => void;
+    labels?: Partial<AuthorizeAgentLabels>;
+}
+/** Primary view: configure the main assistant; connecting an external agent is secondary. */
+export declare function AgentMainView({ config, onConnectExternal, labels }: AgentMainViewProps): import("react").JSX.Element;
+export interface AgentCreatedViewProps {
+    email: string;
+    signingKey: string;
+    /** Connection instructions (host component). */
+    instructions: ReactNode;
+    /** The inline config editor, rendered while `isConfigOpen`. */
+    config: ReactNode;
+    isConfigOpen: boolean;
+    onToggleConfig: () => void;
+    onDone: () => void;
+    labels?: Partial<AuthorizeAgentLabels>;
+}
+/** After creating an external agent: the one-time signing key, instructions, optional config. */
+export declare function AgentCreatedView({ email, signingKey, instructions, config, isConfigOpen, onToggleConfig, onDone, labels, }: AgentCreatedViewProps): import("react").JSX.Element;
+export type AgentWorkspaceRole = 'collaborator' | 'guest';
+export interface AgentCreateViewProps {
+    name: string;
+    onNameChange: (name: string) => void;
+    workspaces: {
+        id: string;
+        name: string;
+    }[];
+    selectedWorkspaces: string[];
+    onSelectedWorkspacesChange: (ids: string[]) => void;
+    role: AgentWorkspaceRole;
+    onRoleChange: (role: AgentWorkspaceRole) => void;
+    isSubmitting: boolean;
+    onBack: () => void;
+    onCancel: () => void;
+    onCreate: () => void;
+    labels?: Partial<AuthorizeAgentLabels>;
+}
+/** Form to create an external agent: name, optional workspaces to share, role. */
+export declare function AgentCreateView({ name, onNameChange, workspaces, selectedWorkspaces, onSelectedWorkspacesChange, role, onRoleChange, isSubmitting, onBack, onCancel, onCreate, labels, }: AgentCreateViewProps): import("react").JSX.Element;

package/dist/agents/approvals/ConsentPage.d.ts

@@ -0,0 +1,76 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface ConsentActionsLabels {
+    deny: string;
+    allow: string;
+    loading: string;
+}
+export declare const DEFAULT_CONSENT_ACTIONS_LABELS: ConsentActionsLabels;
+export interface CopyableUrlLabels {
+    copy: string;
+    copied: string;
+}
+export declare const DEFAULT_COPYABLE_URL_LABELS: CopyableUrlLabels;
+/** Full-screen centered stage for a consent / authorization card. */
+export declare function ConsentPage({ children, className, testId, ...rest }: {
+    children: ReactNode;
+    className?: string;
+    testId?: string;
+} & Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'className'>): import("react").JSX.Element;
+declare const CARD_WIDTH: {
+    readonly sm: "max-w-sm";
+    readonly md: "max-w-md";
+};
+/** The grouping tile holding a consent flow's sections. */
+export declare function ConsentCard({ children, size, className, ...rest }: {
+    children: ReactNode;
+    size?: keyof typeof CARD_WIDTH;
+    className?: string;
+} & Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'className'>): import("react").JSX.Element;
+/** Icon + title + description block at the top of a card. */
+export declare function ConsentHeader({ icon, title, children, }: {
+    /** Icon (or logo) shown above (default) or beside the title. */
+    icon?: ReactNode;
+    title: ReactNode;
+    /** Description paragraph content. */
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** Titled section of a consent card (e.g. "This will allow"). */
+export declare function ConsentSection({ title, children }: {
+    title: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Checkmarked list of permissions. */
+export declare function ConsentPermissionList({ items }: {
+    items: ReactNode[];
+}): import("react").JSX.Element;
+declare const NOTICE_TONES: {
+    readonly error: "bg-destructive/10 text-destructive";
+    readonly success: "bg-green-bg text-green-text";
+    readonly warning: "bg-yellow-bg text-yellow-text";
+};
+/** Tinted inline notice (no box border): error, success or warning. */
+export declare function ConsentNotice({ tone, title, children, className, }: {
+    tone: keyof typeof NOTICE_TONES;
+    title?: string;
+    children?: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+/** Deny / Allow footer; Allow is the single primary action. */
+export declare function ConsentActions({ onDeny, onAllow, isLoading, denyLabel, allowLabel, loadingLabel, labels, }: {
+    onDeny: () => void;
+    onAllow: () => void;
+    isLoading?: boolean;
+    denyLabel?: string;
+    allowLabel?: string;
+    loadingLabel?: string;
+    /** Bundle form of the three label props; the single-string props win. */
+    labels?: Partial<ConsentActionsLabels>;
+}): import("react").JSX.Element;
+/** Read-only URL with a copy button (clipboard handled by the caller). */
+export declare function CopyableUrl({ url, copied, onCopy, labels, }: {
+    url: string;
+    copied: boolean;
+    onCopy: () => void;
+    labels?: Partial<CopyableUrlLabels>;
+}): import("react").JSX.Element;
+export {};

package/dist/agents/approvals/ConsentParts.d.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+declare const MESSAGE_TONES: {
+    readonly error: {
+        readonly card: "p-6";
+        readonly title: "mb-2 text-destructive";
+        readonly body: "text-muted-foreground";
+    };
+    readonly warning: {
+        readonly card: "bg-yellow-bg px-6 py-8";
+        readonly title: "text-yellow-text";
+        readonly body: "mt-2 text-yellow-text";
+    };
+};
+/** A card that only says something (an invalid request, "close this tab"): title and a message. */
+export declare function ConsentMessage({ tone, title, children, }: {
+    tone: keyof typeof MESSAGE_TONES;
+    title: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Bulleted list of what is being agreed to; each item can carry bold lead-in text. */
+export declare function ConsentBulletList({ items }: {
+    items: ReactNode[];
+}): import("react").JSX.Element;
+/** Paragraph of a consent card: `body` explains, `footnote` is small print under an action. */
+export declare function ConsentText({ variant, children, }: {
+    variant?: 'body' | 'footnote' | 'hint';
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Small print under the actions of a card, centred in the card's padding. */
+export declare function ConsentFootnote({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Emphasised lead-in inside running text ("**Read files** — lets…"). */
+export declare function ConsentStrong({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export {};

package/dist/agents/approvals/index.d.ts

@@ -0,0 +1,3 @@
+export { ConsentMessage, ConsentBulletList, ConsentText, ConsentFootnote, ConsentStrong, } from './ConsentParts';
+export { ConsentPage, ConsentCard, ConsentHeader, ConsentSection, ConsentPermissionList, ConsentNotice, ConsentActions, CopyableUrl, DEFAULT_CONSENT_ACTIONS_LABELS, DEFAULT_COPYABLE_URL_LABELS, type ConsentActionsLabels, type CopyableUrlLabels, } from './ConsentPage';
+export { AgentEditView, AgentMainView, AgentCreatedView, AgentCreateView, DEFAULT_AUTHORIZE_AGENT_LABELS, type AuthorizeAgentLabels, type AgentEditViewProps, type AgentMainViewProps, type AgentCreatedViewProps, type AgentCreateViewProps, type AgentWorkspaceRole, } from './AuthorizeAgentParts';

package/dist/agents/config/ConfigField.d.ts

@@ -0,0 +1,43 @@
+/** One config field, rendered from its schema type. Memoized independently. */
+import { type ReactNode } from 'react';
+import { type TupleArrayFieldLabels } from './TupleArrayField';
+import { type SchemaProperty } from './schema-utils';
+export interface ConfigFieldLabels extends TupleArrayFieldLabels {
+    editAsFields: string;
+    editAsJson: string;
+    jsonPlaceholder: string;
+    /** Select placeholder; receives the lower-cased field label. */
+    selectPlaceholder: (label: string) => string;
+    /** Text input placeholder; receives the lower-cased field label. */
+    enterPlaceholder: (label: string) => string;
+    /** Out-of-range hint; receives the range text (`1–5`, `≥ 1`, `≤ 5`). */
+    allowedRange: (range: string) => string;
+    /** Out-of-range notification; `range` may be empty. */
+    outOfRange: (label: string, range: string, value: unknown) => string;
+}
+export declare const DEFAULT_CONFIG_FIELD_LABELS: ConfigFieldLabels;
+export interface ConfigFieldTestIds {
+    /** Test id of a boolean/number control; default `config-field-{section}-{field with dots as dashes}`. */
+    field: (section: string, fieldName: string) => string;
+    /** Test id of the object "Edit as JSON" toggle; default `config-json-toggle-{fieldId}`. */
+    jsonToggle: (fieldId: string) => string;
+}
+export interface ConfigFieldSlots {
+    /** Custom control for the QueryLLM MODEL_NAME field (the app supplies its model picker). */
+    renderModelSelect?: (props: {
+        value: string;
+        onChange: (value: string) => void;
+    }) => ReactNode;
+}
+export interface ConfigFieldProps extends ConfigFieldSlots {
+    section: string;
+    fieldName: string;
+    fieldSchema: SchemaProperty;
+    value: any;
+    onChange: (section: string, field: string, value: any) => void;
+    labels?: Partial<ConfigFieldLabels>;
+    testIds?: Partial<ConfigFieldTestIds>;
+}
+declare function ConfigFieldComponent({ section, fieldName, fieldSchema, value, onChange, renderModelSelect, labels, testIds, }: ConfigFieldProps): import("react").JSX.Element | undefined;
+export declare const ConfigField: import("react").MemoExoticComponent<typeof ConfigFieldComponent>;
+export {};

package/dist/agents/config/ConfigForm.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ConfigForm: renders a backend JSON-schema config as collapsible sections of typed fields
+ * (switches, numbers, selects, prompts, tuples, nested objects).
+ */
+import { type ConfigFieldLabels, type ConfigFieldSlots, type ConfigFieldTestIds } from './ConfigField';
+export interface ConfigFormLabels extends ConfigFieldLabels {
+    collapseAll: string;
+    expandAll: string;
+    enabled: string;
+    disabled: string;
+}
+export declare const DEFAULT_CONFIG_FORM_LABELS: ConfigFormLabels;
+export interface ConfigFormTestIds extends ConfigFieldTestIds {
+    form: string;
+    toggleAll: string;
+    /** Default `config-section-{name}`. */
+    section: (name: string) => string;
+    /** Default `config-section-toggle-{name}`. */
+    sectionToggle: (name: string) => string;
+    /** Default `config-section-enabled-toggle-{name}`. */
+    sectionEnabled: (name: string) => string;
+}
+export interface ConfigFormProps extends ConfigFieldSlots {
+    /** Section name -> JSON schema ({ properties }). */
+    schema: Record<string, any>;
+    /** Current values: section -> field -> value. */
+    values: Record<string, any>;
+    onChange: (section: string, field: string, value: any) => void;
+    labels?: Partial<ConfigFormLabels>;
+    testIds?: Partial<ConfigFormTestIds>;
+    className?: string;
+}
+declare function ConfigFormComponent({ schema, values, onChange, renderModelSelect, labels, testIds, className, }: ConfigFormProps): import("react").JSX.Element;
+export declare const ConfigForm: import("react").MemoExoticComponent<typeof ConfigFormComponent>;
+export {};

package/dist/agents/config/TupleArrayField.d.ts

@@ -0,0 +1,32 @@
+/**
+ * TupleArrayField Component
+ *
+ * Specialized component for handling arrays of tuples, particularly for
+ * few-shot examples where each tuple contains multiple string elements.
+ * Displays in a clean table format for better organization.
+ */
+export interface TupleArrayFieldLabels {
+    addRow: string;
+    empty: string;
+    jsonArrayPlaceholder: string;
+    /** Placeholder of one cell; receives the lower-cased column label. */
+    cellPlaceholder: (column: string) => string;
+    /** aria-label of the remove button; receives the 1-based row number. */
+    removeRow: (row: number) => string;
+    /** Column labels of 2-tuple few-shot examples. */
+    pairColumns: string[];
+    /** Column labels of 3-tuple few-shot examples. */
+    tripleColumns: string[];
+    /** Generic column label; receives the 1-based column number. */
+    column: (n: number) => string;
+}
+export declare const DEFAULT_TUPLE_ARRAY_FIELD_LABELS: TupleArrayFieldLabels;
+export interface TupleArrayFieldProps {
+    fieldId: string;
+    label: string;
+    description?: string;
+    value: any;
+    onChange: (value: any) => void;
+    labels?: Partial<TupleArrayFieldLabels>;
+}
+export declare function TupleArrayField({ fieldId, label, description, value, onChange, labels, }: TupleArrayFieldProps): import("react").JSX.Element;

package/dist/agents/config/index.d.ts

@@ -0,0 +1,4 @@
+export { ConfigForm, DEFAULT_CONFIG_FORM_LABELS, type ConfigFormProps, type ConfigFormLabels, type ConfigFormTestIds, } from './ConfigForm';
+export { ConfigField, DEFAULT_CONFIG_FIELD_LABELS, type ConfigFieldProps, type ConfigFieldSlots, type ConfigFieldLabels, type ConfigFieldTestIds, } from './ConfigField';
+export { TupleArrayField, DEFAULT_TUPLE_ARRAY_FIELD_LABELS, type TupleArrayFieldProps, type TupleArrayFieldLabels, } from './TupleArrayField';
+export { humanizeSection, prettifyKey, inferType, isOutOfBounds, type SchemaProperty, } from './schema-utils';

package/dist/agents/config/schema-utils.d.ts

@@ -0,0 +1,28 @@
+/** Minimal JSON-schema property shape used by the config form. */
+export interface SchemaProperty {
+    type?: string;
+    title?: string;
+    description?: string;
+    default?: any;
+    minimum?: number;
+    maximum?: number;
+    enum?: string[];
+    format?: string;
+    properties?: Record<string, SchemaProperty>;
+}
+/**
+ * Humanize a PascalCase / acronym section key into a normal-case title:
+ * "QueryLLM" -> "Query LLM", "DocTagLLM" -> "Doc Tag LLM", "Agents" -> "Agents".
+ */
+export declare function humanizeSection(name: string): string;
+/** A readable label from an UPPER_SNAKE / snake_case key: SAVE_SOURCES -> "Save sources". */
+export declare function prettifyKey(key: string): string;
+/** True for a non-null, non-array object, i.e. something we can render as fields. */
+export declare function isPlainObject(val: unknown): val is Record<string, unknown>;
+/**
+ * Best-effort JSON-schema `type` inferred from a raw value, so a nested config object the schema
+ * did not declare sub-properties for still renders as structured fields instead of raw JSON.
+ */
+export declare function inferType(val: unknown): SchemaProperty['type'];
+/** True when `value` is a number and lies outside [minimum, maximum]. */
+export declare function isOutOfBounds(value: unknown, minimum?: number, maximum?: number): boolean;

package/dist/agents/definitions/AgentCard.d.ts

@@ -0,0 +1,63 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface AgentCardLabels {
+    running: string;
+    /** Pulse indicator aria-label. */
+    runningIndicator: string;
+    /** Chip text; receives the running count. */
+    runningCount: (count: number) => string;
+    /** Chip text; receives the task count (0 -> none yet). */
+    taskCount: (count: number) => string;
+    goalMet: (met: number, total: number) => string;
+    watch: string;
+    assignTask: string;
+    edit: string;
+    copyAddress: string;
+    deleteAgent: (name: string) => string;
+}
+export declare const DEFAULT_AGENT_CARD_LABELS: AgentCardLabels;
+export interface AgentCardTestIds {
+    root: string;
+    watch: string;
+    assignTask: string;
+    edit: string;
+    copyAddress: string;
+    delete: string;
+}
+export interface AgentCardProps {
+    /** Display name; also the key in the test ids (`agent-card-{name}`, `agent-edit-{name}`...). */
+    name: string;
+    /** The agent's avatar (the app supplies its entity avatar). */
+    avatar: ReactNode;
+    /** Tasks currently running for this agent; shows a pulse + chip when > 0. */
+    runningCount: number;
+    /** All tasks assigned to this agent. */
+    taskCount: number;
+    /** Extra content under the chips (the app shows what the agent can access). */
+    details?: ReactNode;
+    /** Criteria progress of the agent's most recent goal task. */
+    goalProgress?: {
+        met: number;
+        total: number;
+    } | null;
+    /** When set, a Watch action opens the live run. */
+    onWatch?: () => void;
+    /** Each action is optional: the button is omitted when its handler is absent. */
+    onAssignTask?: () => void;
+    onEdit?: () => void;
+    /** When set, a ghost "Copy address" action copies the agent's address (it is not shown raw). */
+    onCopyAddress?: () => void;
+    onDelete?: () => void;
+    /**
+     * Destination of the agent; the name becomes a real link. `onSelect` fires on a plain click
+     * (modified clicks go to the browser).
+     */
+    href?: string;
+    onSelect?: () => void;
+    labels?: Partial<AgentCardLabels>;
+    /** Overrides for the default `agent-card-{name}` / `agent-watch-run-{name}` ... ids. */
+    testIds?: Partial<AgentCardTestIds>;
+    testId?: string;
+    className?: string;
+}
+/** One agent in the gallery: avatar, live task chips, and Watch / Assign task / Edit / Delete. */
+export declare function AgentCard({ name, avatar, runningCount, taskCount, goalProgress, details, onWatch, onAssignTask, onEdit, onCopyAddress, onDelete, href, onSelect, labels, testIds, testId, className, ...rest }: AgentCardProps & Omit<HTMLAttributes<HTMLDivElement>, keyof AgentCardProps>): import("react").JSX.Element;

package/dist/agents/definitions/AgentCreator.d.ts

@@ -0,0 +1,118 @@
+import { type ReactNode } from 'react';
+import { type LucideIcon } from 'lucide-react';
+import type { AgentTypeOption } from './AgentEditorParts';
+/** One thing an agent can be allowed to do (a tool toggle). */
+export interface AgentCapability {
+    key: string;
+    label: string;
+    description: string;
+    icon: LucideIcon;
+}
+/** A starting point: a plain description plus the capabilities that go with it. */
+export interface AgentTemplate {
+    id: string;
+    title: string;
+    description: string;
+    /** Becomes the agent's persona text. */
+    persona: string;
+    /** Capability keys switched on. */
+    capabilities: string[];
+}
+export interface AgentCreatorValues {
+    name: string;
+    persona: string;
+    capabilities: Record<string, boolean>;
+    modelName: string;
+    type: string;
+    /** Workspaces the agent may read (ids). Empty = none: isolation is the default. */
+    workspaceIds: string[];
+}
+export interface AgentCreatorLabels {
+    titleNew: string;
+    titleEdit: (name: string) => string;
+    descriptionNew: string;
+    descriptionEdit: string;
+    describe: string;
+    describePlaceholder: string;
+    describeHint: string;
+    startFrom: string;
+    summaryHeading: string;
+    /** "Can search the web, run code." */
+    summaryCan: (list: string) => string;
+    /** "Cannot generate images." */
+    summaryCannot: (list: string) => string;
+    summaryNone: string;
+    summaryModel: (model: string) => string;
+    summaryModelAuto: string;
+    /** "Reads workspaces A and B." */
+    summaryWorkspaces: (list: string) => string;
+    summaryNoWorkspaces: string;
+    /** "Will be called research-assistant." */
+    summaryName: (name: string) => string;
+    workspaceAccess: string;
+    workspaceAccessHint: string;
+    workspaceAlready: string;
+    noWorkspacesToGrant: string;
+    name: string;
+    nameHint: string;
+    nameInvalid: string;
+    advanced: string;
+    capabilities: string;
+    /** One line under the Tools heading. */
+    toolsHint: string;
+    /** Button in the summary that opens Advanced. */
+    summaryChange: string;
+    model: string;
+    modelAuto: string;
+    cancel: string;
+    create: string;
+    save: string;
+    saving: string;
+}
+export declare const DEFAULT_AGENT_CREATOR_LABELS: AgentCreatorLabels;
+/** A valid agent name from the description: its first few meaningful words, dashed. */
+export declare function deriveAgentName(description: string): string;
+export declare const isValidAgentName: (name: string) => boolean;
+/** The plain-language "can / cannot" sentence for a capability selection. Pure; labels are data. */
+export declare function summarizeCapabilities(capabilities: AgentCapability[], enabled: Record<string, boolean>, modelName: string, labels?: Pick<AgentCreatorLabels, 'summaryCan' | 'summaryCannot' | 'summaryNone' | 'summaryModel' | 'summaryModelAuto'>): string[];
+/** The full plain-language summary: abilities, model, workspace access and the agent's name. */
+export declare function summarizeAgent(capabilities: AgentCapability[], values: Pick<AgentCreatorValues, 'capabilities' | 'modelName' | 'workspaceIds' | 'name'>, workspaces: Array<{
+    id: string;
+    name: string;
+}>, labels?: AgentCreatorLabels): string[];
+export interface AgentCreatorProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    isEdit?: boolean;
+    /** Name shown in the edit title. */
+    agentName?: string;
+    capabilities: AgentCapability[];
+    templates?: AgentTemplate[];
+    models?: string[];
+    /** The user's workspaces, for the explicit access list. */
+    workspaces?: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Workspaces the agent can already read: shown ticked and fixed (revoking is not available). */
+    grantedWorkspaceIds?: string[];
+    /** One-click avatar (or anything that sits beside the name). */
+    avatar?: ReactNode | ((values: AgentCreatorValues) => ReactNode);
+    types?: AgentTypeOption<string>[];
+    /** Controlled values; omit to let the dialog hold them (seeded by `initialValues`). */
+    values?: AgentCreatorValues;
+    initialValues?: Partial<AgentCreatorValues>;
+    onValuesChange?: (values: AgentCreatorValues) => void;
+    /** Avatar field, skills/tool pickers or anything else, folded under Advanced. */
+    advanced?: ReactNode | ((values: AgentCreatorValues) => ReactNode);
+    isSaving?: boolean;
+    onSubmit: (values: AgentCreatorValues) => void;
+    labels?: Partial<AgentCreatorLabels>;
+    testId?: string;
+}
+/**
+ * Create or edit an agent from a plain description. Templates pre-fill the description and the
+ * capabilities, a live sentence says what the agent can and cannot do, and the knobs (capability
+ * toggles, model, type, avatar, pickers) are folded under Advanced.
+ */
+export declare function AgentCreator({ open, onOpenChange, isEdit, agentName, capabilities, templates, models, workspaces, grantedWorkspaceIds, avatar, types, values: valuesProp, initialValues, onValuesChange, advanced, isSaving, onSubmit, labels, testId, }: AgentCreatorProps): import("react").JSX.Element;