@voltro/ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,407 @@
+import { AgentChatMessage } from '@voltro/client';
+import { AgentChatPart } from '@voltro/client';
+import { AgentChatState } from '@voltro/client';
+import { CopilotAnswer } from '@voltro/client';
+import { DataCopilotState } from '@voltro/client';
+import { FieldDescriptor } from '@voltro/client';
+import { FieldOption } from '@voltro/client';
+import { FormBinding } from '@voltro/client';
+import { QueryFiltersState } from '@voltro/client';
+import { ReactNode } from 'react';
+import { Schema } from 'effect';
+import { UseDataTableOptions } from '@voltro/client';
+import { WidgetKind } from '@voltro/client';
+import { WorkflowRunStatus } from '@voltro/client';
+
+/** Kit-styled default chat surface. Streaming bubbles, the live typewriter
+ *  row, an input box wired to `<agent>.send`. */
+export declare function AgentChat(props: AgentChatProps): ReactNode;
+
+export declare interface AgentChatProps {
+    readonly api: string;
+    readonly agent: string;
+    readonly threadId: string;
+    readonly placeholder?: string;
+    readonly sendLabel?: string;
+    readonly emptyText?: string;
+}
+
+/** Render a message's content from its persisted parts, falling back to the
+ *  flat `content` string when no parts are present (e.g. a user turn). */
+export declare function AgentMessageView({ message }: {
+    readonly message: AgentChatMessage;
+}): ReactNode;
+
+/** Render one persisted message part by its `type`. Unknown types fall back to
+ *  a labelled JSON dump so nothing is silently dropped. */
+export declare function AgentPartView({ part }: {
+    readonly part: AgentChatPart;
+}): ReactNode;
+
+/** Headless render-prop over useAgentChat for fully custom layouts. */
+export declare function AgentStream(props: AgentStreamProps): ReactNode;
+
+export declare interface AgentStreamProps {
+    readonly api: string;
+    readonly agent: string;
+    readonly threadId: string;
+    readonly children: (chat: AgentChatState) => ReactNode;
+}
+
+export declare function AppAgent(props: AppAgentProps): ReactNode;
+
+export declare interface AppAgentProps extends AgentChatProps {
+    /** The tools this agent can use — rendered as a capability disclosure. */
+    readonly tools?: ReadonlyArray<AppAgentTool>;
+    /** Show the tools disclosure (default true when `tools` is non-empty). */
+    readonly showTools?: boolean;
+}
+
+/** A tool the agent can call (the manifest's `exposeAsTool` view /
+ *  synthesizeToolSpecs output). Structural — no @voltro/ai dep in the kit. */
+export declare interface AppAgentTool {
+    readonly name: string;
+    readonly description?: string;
+    /** mutation/action → true. */
+    readonly write?: boolean;
+    /** Requires human confirmation before it runs. */
+    readonly confirm?: boolean;
+}
+
+/** Approve/Reject buttons bound to a parked `awaitSignal` / `awaitUpdate`.
+ *  Controlled + gated: renders nothing unless the run is actually waiting. */
+export declare function ApprovalControls(props: ApprovalControlsProps): ReactNode;
+
+export declare interface ApprovalControlsProps {
+    /** Render ONLY when true — gate on `run.waitingFor?.name === 'approval'`. */
+    readonly when: boolean;
+    readonly onApprove: () => void;
+    readonly onReject: () => void;
+    readonly approveLabel?: string;
+    readonly rejectLabel?: string;
+    readonly pending?: boolean;
+}
+
+export declare const AsyncSelect: (props: AsyncSelectProps) => ReactNode;
+
+export declare interface AsyncSelectProps extends WidgetProps {
+    /** The api the source query lives on. */
+    readonly api: string;
+    /** The source query tag that supplies the options (`'users.search'`). */
+    readonly source: string;
+    readonly labelField?: string;
+    readonly valueField?: string;
+    /** Map the typed term → the source query input. Default `{ q: term }`. */
+    readonly input?: (term: string) => Record<string, unknown>;
+    readonly debounceMs?: number;
+}
+
+export declare function AutoForm<Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(props: AutoFormProps<Input, Output>): ReactNode;
+
+export declare interface AutoFormProps<Input extends Record<string, unknown>, Output> {
+    readonly api: string;
+    /** The mutation tag to bind to (`'todos.create'`). create vs. update are
+     *  different tags → different forms; no CRUD-mode abstraction. */
+    readonly mutation: string;
+    /** The mutation's input `Schema`. Optional — resolved from the mounted
+     *  descriptor's capability-map entry (`descriptors[tag].input`) when omitted. */
+    readonly schema?: Schema.Schema.Any;
+    readonly defaults?: Partial<Input>;
+    readonly onSuccess?: (output: Output) => void;
+    readonly submitLabel?: string;
+    /** Rung 3 — own the layout; arrange `<Field>`s yourself. The binding is
+     *  passed for derived UI (pending, isValid, values). */
+    readonly children?: (binding: FormBinding<Input, Output>) => ReactNode;
+}
+
+/** Kit-styled default copilot surface: a question box wired to the action +
+ *  a results region that swaps between refusal, empty, and a generic table. */
+export declare function DataCopilot(props: DataCopilotProps): ReactNode;
+
+/** Render a copilot answer: a refusal message, an empty note, or a table. */
+export declare function DataCopilotAnswer(props: {
+    readonly answer: CopilotAnswer | undefined;
+    readonly emptyText?: string;
+}): ReactNode;
+
+export declare interface DataCopilotProps {
+    readonly api: string;
+    /** The copilot action tag (input `{ question }`, output `CopilotAnswer`). */
+    readonly action: string;
+    readonly placeholder?: string;
+    readonly askLabel?: string;
+    readonly emptyText?: string;
+}
+
+/** Headless render-prop over `useDataCopilot` for a fully custom layout. */
+export declare function DataCopilotStream(props: DataCopilotStreamProps): ReactNode;
+
+export declare interface DataCopilotStreamProps {
+    readonly api: string;
+    readonly action: string;
+    readonly children: (copilot: DataCopilotState) => ReactNode;
+}
+
+export declare function DataTable<Row extends Record<string, unknown> = Record<string, unknown>>(props: DataTableProps<Row>): ReactNode;
+
+export declare interface DataTableProps<Row> extends UseDataTableOptions {
+    readonly api: string;
+    /** The reactive query tag whose rows + output schema drive the table. */
+    readonly query: string;
+    readonly emptyText?: string;
+    readonly loadingText?: string;
+    /** Label for the "Load more" button (shown when `pageSize` is set + more rows exist). */
+    readonly loadMoreText?: string;
+    /** Custom cell renderer; defaults to a string/boolean format. */
+    readonly renderCell?: (row: Row, column: FieldDescriptor) => ReactNode;
+    /** Per-row action cell (e.g. edit/delete buttons wired to mutations). */
+    readonly rowActions?: (row: Row) => ReactNode;
+    /** Stable row key; defaults to `row.id` then index. */
+    readonly rowKey?: (row: Row) => string;
+}
+
+/** The English defaults. A consumer overrides any subtree via
+ *  {@link UiStringsProvider}; unspecified keys fall through to these. */
+export declare const defaultUiStrings: UiStrings;
+
+/** The built-in defaults. Plain accessible HTML; overridable per app via the
+ *  registry, per field via a `<Field>` render-prop. `async-select` renders a
+ *  plain text input by design — a registry widget can't carry the `api`/`source`
+ *  binding a query-bound picker needs, so use the shipped `<AsyncSelect>`
+ *  component (or a rung-2 override) for the live picker. */
+export declare const defaultWidgets: Record<WidgetKind, Widget>;
+
+/** "X is editing" — surfaces that other users are active on the same
+ *  row/field. Soft (warn, not a hard lock). Renders nothing when alone. */
+export declare function EditingIndicator(props: EditingIndicatorProps): ReactNode;
+
+export declare interface EditingIndicatorProps {
+    readonly members: ReadonlyArray<PresenceMemberLike>;
+    /** Exclude the current user from the roster. */
+    readonly selfKey?: string;
+    /** Soft field-level scope — only members whose `meta.field` matches. */
+    readonly field?: string;
+    readonly verb?: string;
+    readonly nameOf?: (m: PresenceMemberLike) => string;
+}
+
+/** Render one field of the enclosing `<AutoForm>` — via its render-prop child
+ *  (rung 1) or the resolved widget (the seam). Returns null for an unknown
+ *  field name. */
+export declare const Field: ({ name, children }: FieldProps) => ReactNode;
+
+export declare interface FieldProps {
+    readonly name: string;
+    /** Rung 1 — render this field with a custom widget; the binding still owns
+     *  value / validation / submit. Omit to use the seam's widget for the kind. */
+    readonly children?: (props: WidgetProps) => ReactNode;
+}
+
+/** A form-shaped skeleton: one label+control placeholder per field of the
+ *  mutation's input Schema. */
+export declare function FormSkeleton(props: FormSkeletonProps): ReactNode;
+
+export declare interface FormSkeletonProps {
+    readonly api: string;
+    readonly mutation: string;
+    /** Fallback field count when the descriptor isn't resolvable yet. Default 3. */
+    readonly fallbackFields?: number;
+}
+
+/** Up-to-two-letter initials from a display name. */
+export declare const initials: (name: string) => string;
+
+/** A caller may override any subtree, not the whole object — deep-partial. The
+ *  `workflow.status` map is itself partial so you can relabel a single status. */
+export declare type PartialUiStrings = {
+    readonly [K in keyof UiStrings]?: K extends 'workflow' ? Partial<Omit<UiStrings['workflow'], 'status'>> & {
+        readonly status?: Partial<UiStrings['workflow']['status']>;
+    } : Partial<UiStrings[K]>;
+};
+
+/** Live roster of who's viewing this record/page. Feed it `usePresence(...)`. */
+export declare function PresenceAvatars(props: PresenceAvatarsProps): ReactNode;
+
+export declare interface PresenceAvatarsProps {
+    readonly members: ReadonlyArray<PresenceMemberLike>;
+    /** Cap the visible avatars; the rest collapse into a "+N" chip. Default 5. */
+    readonly max?: number;
+    readonly nameOf?: (m: PresenceMemberLike) => string;
+    /** Override one avatar's rendering (rung-1 escape hatch). */
+    readonly renderAvatar?: (m: PresenceMemberLike, name: string) => ReactNode;
+}
+
+/** Structural shape of a presence member — matches `PresenceMember` from
+ *  @voltro/plugin-presence/web without coupling the kit to that package. */
+export declare interface PresenceMemberLike {
+    readonly key: string;
+    readonly meta: Record<string, unknown> | null;
+    readonly lastSeen: number;
+}
+
+export declare function QueryFilters<Row = Record<string, unknown>>(props: QueryFiltersProps<Row>): ReactNode;
+
+export declare interface QueryFiltersProps<Row> {
+    readonly api: string;
+    readonly query: string;
+    readonly initial?: Readonly<Record<string, unknown>>;
+    readonly showCount?: boolean;
+    /** Render the live results beneath the panel. */
+    readonly children?: (state: QueryFiltersState<Row>) => ReactNode;
+}
+
+export declare function RecordView<R extends Record<string, unknown> = Record<string, unknown>>(props: RecordViewProps<R>): ReactNode;
+
+export declare interface RecordViewProps<R extends Record<string, unknown>> {
+    readonly api: string;
+    readonly query: string;
+    readonly input?: Readonly<Record<string, unknown>>;
+    /** Restrict/order the scalar fields shown (defaults to all non-relation keys). */
+    readonly fields?: ReadonlyArray<string>;
+    /** Override one scalar field's rendering (rung-1 escape hatch). */
+    readonly renderField?: (name: string, value: unknown, record: R) => ReactNode;
+    /** Override a relation's rendering (default: a nested table of the items). */
+    readonly renderRelation?: (name: string, items: ReadonlyArray<Record<string, unknown>>, record: R) => ReactNode;
+    readonly loadingText?: string;
+    readonly emptyText?: string;
+}
+
+/** Build the "X is editing" / "X and Y are editing" / "X and N others are
+ *  editing" sentence from the editor names. Pure — exported for tests. The
+ *  sentence templates come from the kit strings (localizable); defaults to the
+ *  English {@link defaultUiStrings} presence subtree when none is passed. */
+export declare const summarizeEditors: (names: ReadonlyArray<string>, verb: string, strings?: UiStrings["presence"]) => string;
+
+/** A table-shaped skeleton: the query's real columns as header placeholders +
+ *  N placeholder rows. */
+export declare function TableSkeleton(props: TableSkeletonProps): ReactNode;
+
+export declare interface TableSkeletonProps {
+    readonly api: string;
+    readonly query: string;
+    /** Skeleton row count. Default 5. */
+    readonly rows?: number;
+    /** Fallback column count when the descriptor isn't resolvable. Default 4. */
+    readonly fallbackColumns?: number;
+}
+
+/** Every user-facing string the kit renders. Scalars are literals; anything
+ *  that interpolates a value (count, name, label) is a function so a locale can
+ *  reorder/pluralize. English defaults live in {@link defaultUiStrings}. */
+export declare interface UiStrings {
+    /** <QueryFilters> — the reset button, the "Any <label>" option, the result
+     *  count, and the group's aria-label. */
+    readonly filters: {
+        readonly clear: string;
+        readonly filtersLabel: string;
+        readonly anyOption: (label: string) => string;
+        readonly resultCount: (count: number | string) => string;
+    };
+    /** <AsyncSelect> — the search box + loading/empty option text. */
+    readonly asyncSelect: {
+        readonly searchPlaceholder: string;
+        readonly searchLabel: (label: string) => string;
+        readonly loading: string;
+        /** The empty/no-selection option glyph (default `—`). */
+        readonly empty: string;
+    };
+    /** <DataTable> — the row-actions column header. */
+    readonly dataTable: {
+        readonly actions: string;
+    };
+    /** <WorkflowProgress> — per-status labels, the attempt suffix, loading/empty. */
+    readonly workflow: {
+        readonly status: Record<WorkflowRunStatus, string>;
+        readonly attempt: (n: number) => string;
+        readonly loading: string;
+        readonly empty: string;
+    };
+    /** <AgentChat> — the reasoning disclosure, message box + send button. */
+    readonly agentChat: {
+        readonly reasoning: string;
+        readonly messagePlaceholder: string;
+        readonly messageLabel: string;
+        readonly send: string;
+    };
+    /** <AppAgent> — the tool disclosure summary + the confirm/write hints. */
+    readonly appAgent: {
+        readonly toolsSummary: (count: number) => string;
+        readonly needsConfirm: string;
+    };
+    /** <PresenceAvatars> / <EditingIndicator> — the "N more" overflow, the online
+     *  count, and the "X is editing" sentence template. `verb` is the activity
+     *  (e.g. "editing"), threaded from the component. */
+    readonly presence: {
+        readonly moreOverflow: (n: number) => string;
+        readonly onlineCount: (n: number) => string;
+        readonly editingOne: (name: string, verb: string) => string;
+        readonly editingTwo: (a: string, b: string, verb: string) => string;
+        readonly editingMany: (name: string, othersCount: number, verb: string) => string;
+    };
+    /** <RecordView> — the empty-relation line. `relation` is already humanized. */
+    readonly recordView: {
+        readonly emptyRelation: (relation: string) => string;
+    };
+}
+
+/** Provide localized (or otherwise overridden) UI strings to every @voltro/ui
+ *  component below. Overrides are deep-merged onto the English defaults — supply
+ *  only the sections/keys you change. Nesting providers merges onto the parent. */
+export declare function UiStringsProvider(props: {
+    readonly strings: PartialUiStrings;
+    readonly children: ReactNode;
+}): ReactNode;
+
+/** Read the active UI strings. Returns the English defaults when no provider is
+ *  mounted, so every component works with zero setup. */
+export declare const useUiStrings: () => UiStrings;
+
+/** Resolve the component for a widget kind: registry override → built-in
+ *  default → the `custom` fallback (never throws). */
+export declare const useWidget: (kind: WidgetKind) => Widget;
+
+export declare type Widget = (props: WidgetProps) => ReactNode;
+
+/** The contract every widget receives. The form binding owns state +
+ *  validation; a widget only renders the control + reports changes. */
+export declare interface WidgetProps {
+    readonly name: string;
+    readonly label: string;
+    readonly value: unknown;
+    readonly onChange: (value: unknown) => void;
+    readonly error?: string;
+    readonly required: boolean;
+    readonly disabled?: boolean;
+    readonly options?: ReadonlyArray<FieldOption>;
+}
+
+export declare type WidgetRegistry = Partial<Record<WidgetKind, Widget>>;
+
+/** Override widgets app-wide (rung 2). Nests: an inner provider merges over
+ *  the outer one, so a subtree can refine the registry further. */
+export declare const WidgetRegistryProvider: (props: {
+    readonly widgets: WidgetRegistry;
+    readonly children: ReactNode;
+}) => ReactNode;
+
+/** Live step timeline from `_voltro_workflow_run_steps`, pushed reactively as
+ *  the run advances — no polling. Shows attempts + durations. */
+export declare function WorkflowProgress(props: WorkflowProgressProps): ReactNode;
+
+export declare interface WorkflowProgressProps {
+    readonly api: string;
+    readonly runId: string | undefined;
+    readonly loadingText?: string;
+    readonly emptyText?: string;
+}
+
+/** running / waiting / succeeded / failed, with the failing step + a
+ *  `voltro logs --trace <id>` hint on error. */
+export declare function WorkflowStatusBadge(props: WorkflowStatusBadgeProps): ReactNode;
+
+export declare interface WorkflowStatusBadgeProps {
+    readonly api: string;
+    readonly runId: string | undefined;
+}
+
+export { }