@tai42/studio-sdk 30.0.0 → 31.0.0

package/src/components/folder-filing.tsx

@@ -0,0 +1,109 @@
+/**
+ * Filing ONE tool into a folder of the tool-organization tree — for a screen whose
+ * rows have no edit dialog of their own to carry a folder field. The folder is part
+ * of the tool's overlay row, so the write is a single `upsertToolMeta` merge-patch of
+ * `folder_id`; the tool's display name, tags and visibility are left untouched.
+ *
+ * The picker offers the FULL tree with inline create. The write resolves only after
+ * the screen's `onFoldersChanged` refresh, and a failure is shown in the dialog — a
+ * not-configured refusal as the server's off note, reported so every screen withdraws
+ * its overlay writes.
+ */
+import { type ReactNode, useState } from 'react';
+
+import { useApi } from '../hooks/useApi';
+import { Dialog } from './dialog';
+import { Field } from './field';
+import { type FoldersChanged, useCreateFolder } from './folder-actions';
+import { type Folder, FolderPicker } from './folder-nav';
+import { Button, Spinner } from './primitives';
+import { ToolMetaWriteError, useReportToolMetaRefusal } from './tool-meta-access';
+
+/** Props of {@link MoveToFolderDialog}. */
+export interface MoveToFolderDialogProps {
+  /** The tool whose overlay row is filed (its registered tool name). */
+  readonly toolName: string;
+  /** What the dialog title calls the item (e.g. the agent's name). */
+  readonly label: string;
+  /** The tool's current folder (`null` = unfiled). */
+  readonly currentFolderId: string | null;
+  /** The FULL folder tree, offered as destinations. */
+  readonly folders: readonly Folder[];
+  /** The screen's refresh of its overlay read, awaited after the write. */
+  readonly onFoldersChanged: FoldersChanged;
+  /** Close the dialog (Cancel, dismiss, or after a successful move). */
+  readonly onClose: () => void;
+}
+
+/** A dialog that files one tool into a folder (or unfiles it). Mount while open. */
+export function MoveToFolderDialog({
+  toolName,
+  label,
+  currentFolderId,
+  folders,
+  onFoldersChanged,
+  onClose,
+}: MoveToFolderDialogProps): ReactNode {
+  const api = useApi();
+  const createFolder = useCreateFolder(onFoldersChanged);
+  const reportRefusal = useReportToolMetaRefusal();
+  const [folderId, setFolderId] = useState<string | null>(currentFolderId);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<unknown>(null);
+
+  const save = (): void => {
+    if (pending) return;
+    setPending(true);
+    setError(null);
+    api
+      .upsertToolMeta(toolName, { folder_id: folderId })
+      .then(() => onFoldersChanged())
+      .then(
+        () => {
+          setPending(false);
+          onClose();
+        },
+        (failure: unknown) => {
+          setError(failure);
+          setPending(false);
+          reportRefusal(failure);
+        },
+      );
+  };
+
+  return (
+    <Dialog
+      title={`Move ${label} to a folder`}
+      open
+      onOpenChange={(next) => {
+        if (!next) onClose();
+      }}
+    >
+      <Field label="Destination folder" description="Choose a folder, or no folder." group>
+        <FolderPicker
+          value={folderId}
+          onChange={setFolderId}
+          folders={folders}
+          onCreateFolder={createFolder}
+          unfiledLabel="No folder"
+          disabled={pending}
+        />
+      </Field>
+      <ToolMetaWriteError error={error} />
+      <div className="tai-dialog-actions">
+        <Button type="button" onClick={onClose}>
+          Cancel
+        </Button>
+        <Button
+          type="button"
+          variant="primary"
+          disabled={folderId === currentFolderId || pending}
+          onClick={save}
+        >
+          {pending ? <Spinner label="Moving" /> : null}
+          Move
+        </Button>
+      </div>
+    </Dialog>
+  );
+}

package/src/components/folder-nav.tsx

@@ -11,14 +11,17 @@
  *
  * `FolderPicker` carries inline new-folder creation, so a folder can be created from
  * EVERY consuming screen through this one component — never one screen's own
- * affordance.
+ * affordance. A failed creation is shown loudly under the draft by the picker
+ * itself, so every screen that files through it surfaces the failure the same way.
  */
+import type { FolderRecord } from '@tai42/api-client';
 import { type ReactNode, useState } from 'react';
 
 import { ChevronRightIcon, FolderIcon } from './icons';
 import { TextInput } from './inputs';
 import { Button } from './primitives';
 import { Select } from './select';
+import { ToolMetaWriteError } from './tool-meta-access';
 
 /** A folder in the tree, in the SDK's camelCase UI shape (`parentId`, `null` = root). */
 export interface Folder {
@@ -27,6 +30,15 @@ export interface Folder {
   readonly parentId: string | null;
 }
 
+/** Map the overlay's wire folder records into the UI {@link Folder} shape. */
+export function toFolders(records: readonly FolderRecord[]): Folder[] {
+  return records.map((record) => ({
+    id: record.id,
+    name: record.name,
+    parentId: record.parent_id,
+  }));
+}
+
 /** The subfolders directly under `parentId` (`null` = the root directory), name-sorted. */
 export function childFolders(folders: readonly Folder[], parentId: string | null): Folder[] {
   return folders
@@ -143,10 +155,11 @@ export interface FolderPickerProps {
   readonly folders: readonly Folder[];
   /**
    * Create a folder under `parentId` (the current selection) and resolve with its
-   * id; the picker selects it. Rejection is the caller's to surface — the picker
-   * leaves the draft in place so the operator can retry.
+   * id; the picker selects it. On a rejection the picker shows the error and keeps
+   * the draft in place so the operator can retry. Without it the picker offers no
+   * create — the caller may not create folders.
    */
-  readonly onCreateFolder: (name: string, parentId: string | null) => Promise<string>;
+  readonly onCreateFolder?: (name: string, parentId: string | null) => Promise<string>;
   readonly disabled?: boolean;
   /** The unfiled option's label (e.g. "No folder"). */
   readonly unfiledLabel: string;
@@ -164,22 +177,23 @@ export function FolderPicker({
   const [creating, setCreating] = useState(false);
   const [draft, setDraft] = useState('');
   const [busy, setBusy] = useState(false);
+  const [createError, setCreateError] = useState<unknown>(null);
 
   const options = [{ value: UNFILED_VALUE, label: unfiledLabel }, ...folderOptions(folders)];
 
   const create = async (): Promise<void> => {
     const name = draft.trim();
-    if (name === '' || busy) return;
+    if (name === '' || busy || onCreateFolder === undefined) return;
     setBusy(true);
+    setCreateError(null);
     try {
       const id = await onCreateFolder(name, value);
       onChange(id);
       setDraft('');
       setCreating(false);
-    } catch {
-      // The caller owns surfacing the failure (its `onCreateFolder` is the loud
-      // surface); the picker's part is to keep the draft OPEN with its text so the
-      // operator can retry — never to clear it or select nothing.
+    } catch (error: unknown) {
+      // Shown under the draft, which stays OPEN with its text for a retry.
+      setCreateError(error);
     } finally {
       setBusy(false);
     }
@@ -196,7 +210,7 @@ export function FolderPicker({
         }}
         disabled={disabled ?? busy}
       />
-      {creating ? (
+      {onCreateFolder === undefined ? null : creating ? (
         <div className="tai-row">
           <div style={{ flex: 1 }}>
             <TextInput
@@ -231,6 +245,7 @@ export function FolderPicker({
             onClick={() => {
               setCreating(false);
               setDraft('');
+              setCreateError(null);
             }}
             disabled={busy}
           >
@@ -250,6 +265,7 @@ export function FolderPicker({
           <span>New folder</span>
         </Button>
       )}
+      <ToolMetaWriteError error={createError} />
     </div>
   );
 }

package/src/components/folder-occupancy.ts

@@ -0,0 +1,83 @@
+/**
+ * Which folders of the ONE tool-organization tree a screen draws. Every tool has one
+ * folder; a screen lists only its own population (a subset of the tools), so it draws
+ * only the part of the tree that concerns that population:
+ *
+ *  - a folder whose subtree holds at least one of the screen's items is drawn;
+ *  - a folder whose subtree holds no tool at all is drawn (a fresh folder belongs to
+ *    every screen until something is filed in it);
+ *  - a folder whose subtree holds only other tools is not drawn;
+ *  - the ancestors of a drawn folder are drawn, so every drawn folder stays reachable
+ *    from the root.
+ *
+ * Occupancy counts EVERY overlay row with a `folder_id` — hidden tools and rows of
+ * tools no longer registered included — so a folder never reads as empty while it
+ * still holds something. A screen whose population is every tool draws the whole tree.
+ */
+import type { ToolMetaRecord } from '@tai42/api-client';
+
+import type { Folder } from './folder-nav';
+
+/** What a folder's subtree holds, and whether the folder is drawn. */
+interface SubtreeState {
+  readonly own: boolean;
+  readonly any: boolean;
+  readonly drawn: boolean;
+}
+
+const NOTHING: SubtreeState = { own: false, any: false, drawn: false };
+
+/**
+ * The folders a screen draws, in the input order.
+ *
+ * `rows` are the overlay rows (each tool's `folder_id`), `population` the tool names
+ * the screen lists. Linear in folders + rows; the subtree walk is cycle-guarded, so a
+ * malformed parent chain yields a bounded result rather than looping.
+ */
+export function foldersForView(
+  folders: readonly Folder[],
+  rows: readonly Pick<ToolMetaRecord, 'tool_name' | 'folder_id'>[],
+  population: ReadonlySet<string>,
+): Folder[] {
+  const direct = new Map<string, { own: boolean; any: boolean }>();
+  for (const row of rows) {
+    if (row.folder_id === null) continue;
+    const entry = direct.get(row.folder_id) ?? { own: false, any: false };
+    entry.any = true;
+    if (population.has(row.tool_name)) entry.own = true;
+    direct.set(row.folder_id, entry);
+  }
+
+  const childrenByParent = new Map<string, string[]>();
+  for (const folder of folders) {
+    if (folder.parentId === null) continue;
+    const siblings = childrenByParent.get(folder.parentId) ?? [];
+    siblings.push(folder.id);
+    childrenByParent.set(folder.parentId, siblings);
+  }
+
+  const settled = new Map<string, SubtreeState>();
+  const visiting = new Set<string>();
+  const stateOf = (id: string): SubtreeState => {
+    const cached = settled.get(id);
+    if (cached !== undefined) return cached;
+    if (visiting.has(id)) return NOTHING;
+    visiting.add(id);
+    const held = direct.get(id);
+    let own = held?.own ?? false;
+    let any = held?.any ?? false;
+    let childDrawn = false;
+    for (const childId of childrenByParent.get(id) ?? []) {
+      const child = stateOf(childId);
+      own = own || child.own;
+      any = any || child.any;
+      childDrawn = childDrawn || child.drawn;
+    }
+    visiting.delete(id);
+    const state = { own, any, drawn: own || !any || childDrawn };
+    settled.set(id, state);
+    return state;
+  };
+
+  return folders.filter((folder) => stateOf(folder.id).drawn);
+}

package/src/components/named-list-picker.tsx

@@ -1,10 +1,10 @@
 /**
- * The single-select both `AgentPicker` and `ChannelPicker` render: one list read of
- * names, drawn in its own `Field` with the read's states (pending, error with Retry,
+ * The searchable single-select both `AgentPicker` and `ChannelPicker` render: one list
+ * read of names, drawn in its own `Field` with the read's states (pending, error with Retry,
  * refused on a 403, loaded and empty) and a stored value the loaded list does not
  * hold flagged with the picker's unlisted label. Each picker hands in its own copy.
  * The host's `error` shows, and the `Field` claims its control id, exactly while a
- * `Select` renders.
+ * select renders.
  */
 import { type ReactNode, useId } from 'react';
 
@@ -12,7 +12,8 @@ import { errorMessage, isForbiddenError } from '../errors';
 import { Badge } from './badge';
 import { Field } from './field';
 import { ErrorState } from './primitives';
-import { Select, type SelectOption } from './select';
+import { SearchableSelect } from './searchable-select';
+import type { SelectOption } from './select';
 
 const MUTED_LINE = { margin: 0, color: 'var(--tai-color-text-muted)' } as const;
 
@@ -35,6 +36,8 @@ export interface NamedListCopy {
   readonly emptyNote: string;
   readonly emptyAction: ReactNode;
   readonly unlistedLabel: string;
+  /** Accessible name of the select's search box. */
+  readonly searchLabel: string;
 }
 
 export interface NamedListPickerProps {
@@ -107,7 +110,7 @@ function namedListView(
   return { refused, failed, pending, unlisted, empty, options, selectRenders };
 }
 
-/** The loaded, pending or refused body: the `Select` while one renders, then its notes. */
+/** The loaded, pending or refused body: the select while one renders, then its notes. */
 function NamedListBody({
   view,
   value,
@@ -123,13 +126,14 @@ function NamedListBody({
   return (
     <>
       {view.selectRenders ? (
-        <Select
+        <SearchableSelect
           options={view.options}
           value={value}
           placeholder={view.pending ? copy.loadingPlaceholder : copy.placeholder}
           disabled={view.pending}
           onValueChange={onValueChange}
           aria-describedby={view.unlisted ? unlistedId : undefined}
+          searchLabel={copy.searchLabel}
         />
       ) : null}
       {view.refused ? <MutedLine text={copy.forbiddenNote} /> : null}
@@ -163,7 +167,7 @@ export function NamedListPicker({
       label={copy.label}
       description={copy.description}
       error={view.selectRenders ? error : undefined}
-      // Only the Select claims the field's control id; with nothing to hold no
+      // Only the select claims the field's control id; with nothing to hold no
       // labelable element renders, so `for` would dangle.
       group={!view.selectRenders}
     >

package/src/components/primitives.tsx

@@ -68,7 +68,8 @@ function normalizeHref(href: string): string {
  * evil.com.
  *
  * Callers render the returned string rather than their input, so the URL that was
- * judged is always the URL that is navigated.
+ * judged is always the URL that is navigated. `isSafeHttpUrl` gives the yes/no
+ * answer for a caller that does not need the URL itself.
  */
 export function safeHttpUrl(href: string): string | undefined {
   const normalized = normalizeHref(href);

package/src/components/searchable-select-model.ts

@@ -0,0 +1,105 @@
+/**
+ * The option model behind `SearchableSelect`: the caller's options indexed once for
+ * search, the sections a query leaves, and the keyboard's movement over them. Pure,
+ * so the component re-derives nothing per row and the filter is testable alone.
+ */
+import { searchNeedle, textHasNeedle } from '../search-match';
+import type { SelectGroup, SelectOption } from './select';
+
+/** One option, with its position in the full list and its label in search form. */
+export interface SearchEntry {
+  readonly option: SelectOption;
+  /** The option's position across every section; stable while the reader filters. */
+  readonly position: number;
+  readonly loweredLabel: string;
+}
+
+/** A run of entries under one group label, or under none for a flat list. */
+export interface SearchSection {
+  readonly label: string | undefined;
+  readonly entries: readonly SearchEntry[];
+}
+
+/** What a query leaves: the non-empty sections and their entries in reading order. */
+export interface VisibleOptions {
+  readonly sections: readonly SearchSection[];
+  readonly entries: readonly SearchEntry[];
+}
+
+/** Index the caller's options (a flat run, or labelled groups) for search. */
+export function indexSections(
+  options: readonly SelectOption[] | undefined,
+  groups: readonly SelectGroup[] | undefined,
+): SearchSection[] {
+  const runs: { label: string | undefined; options: readonly SelectOption[] }[] =
+    groups !== undefined
+      ? groups.map((group) => ({ label: group.label, options: group.options }))
+      : [{ label: undefined, options: options ?? [] }];
+  let position = 0;
+  return runs.map((run) => ({
+    label: run.label,
+    entries: run.options.map((option) => ({
+      option,
+      position: position++,
+      loweredLabel: option.label.toLowerCase(),
+    })),
+  }));
+}
+
+/**
+ * The sections and entries whose label contains `query`. A blank query returns every
+ * section as indexed; either way each kept entry is the indexed object itself, so a
+ * row memoised on its entry does not re-render because the reader typed.
+ */
+export function visibleOptions(sections: readonly SearchSection[], query: string): VisibleOptions {
+  const needle = searchNeedle(query);
+  const kept =
+    needle === ''
+      ? sections
+      : sections.map((section) => ({
+          label: section.label,
+          entries: section.entries.filter((entry) => textHasNeedle(entry.loweredLabel, needle)),
+        }));
+  const nonEmpty = kept.filter((section) => section.entries.length > 0);
+  return { sections: nonEmpty, entries: nonEmpty.flatMap((section) => section.entries) };
+}
+
+function enabled(entry: SearchEntry): boolean {
+  return entry.option.disabled !== true;
+}
+
+/**
+ * The entry the keyboard highlight moves to from `current` by one step in
+ * `direction`, skipping disabled entries and stopping at either end. With no current
+ * highlight among `entries`, a step lands on the first (down) or last (up) one.
+ */
+export function stepEntry(
+  entries: readonly SearchEntry[],
+  current: SearchEntry | undefined,
+  direction: 1 | -1,
+): SearchEntry | undefined {
+  const at = current === undefined ? -1 : entries.indexOf(current);
+  if (at === -1) return direction === 1 ? entries.find(enabled) : entries.findLast(enabled);
+  for (let index = at + direction; index >= 0 && index < entries.length; index += direction) {
+    const entry = entries[index];
+    if (entry !== undefined && enabled(entry)) return entry;
+  }
+  return current;
+}
+
+/**
+ * The entry to draw highlighted: the choosable visible entry whose value is `wanted`,
+ * else the first choosable one. Keyed by value, so the highlight stays on its option
+ * when the list around it changes, and a query that filters it away moves it to the
+ * top of what is left instead of to nothing.
+ */
+export function shownEntry(
+  entries: readonly SearchEntry[],
+  wanted: string | undefined,
+): SearchEntry | undefined {
+  const kept =
+    wanted === undefined
+      ? undefined
+      : entries.find((entry) => entry.option.value === wanted && enabled(entry));
+  return kept ?? entries.find(enabled);
+}