@iloveagents/foundry-web-ui 0.3.1 → 0.5.0

package/dist/lib/client-tools.js

@@ -0,0 +1,274 @@
+/**
+ * Global Client Tools — registered into the dynamic tool registry at app init.
+ *
+ * Naming convention:
+ *   ui_*    — tools that affect the UI (navigate, theme, panel, content)
+ *
+ * Page-specific tools use their own prefix (e.g., page_search_documents).
+ * The adapter reads from the registry (not this file) on every request.
+ */
+import { useThemeStore } from "./theme-store.js";
+import { useToolPanelStore } from "./tool-panel-store.js";
+import { useAppStore } from "./app-store.js";
+import { clientToolRegistry } from "@iloveagents/foundry-agent";
+// ---------------------------------------------------------------------------
+// Navigate function injection (needs React Router context)
+// ---------------------------------------------------------------------------
+let _navigateFn = null;
+export function setNavigateFunction(fn) {
+    _navigateFn = fn;
+}
+// ---------------------------------------------------------------------------
+// Global tool definitions with executors
+// ---------------------------------------------------------------------------
+const GLOBAL_TOOLS = [
+    {
+        name: "ui_navigate",
+        description: "Navigate the user to a different page in the application. " +
+            "Only use when the user explicitly asks to go to a page.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "The path to navigate to (e.g. '/workspace')",
+                },
+            },
+            required: ["path"],
+        },
+        execute: async (argsJson) => {
+            const { path } = JSON.parse(argsJson || "{}");
+            if (_navigateFn)
+                _navigateFn(path);
+            return JSON.stringify({ status: "success", path });
+        },
+    },
+    {
+        name: "ui_set_theme",
+        description: "Change the application theme. Modes: 'light', 'dark', or 'system'.",
+        parameters: {
+            type: "object",
+            properties: {
+                mode: {
+                    type: "string",
+                    enum: ["light", "dark", "system"],
+                    description: "The theme mode to apply",
+                },
+            },
+            required: ["mode"],
+        },
+        execute: async (argsJson) => {
+            const { mode } = JSON.parse(argsJson || "{}");
+            useThemeStore.getState().setMode(mode);
+            return JSON.stringify({ status: "success", mode });
+        },
+    },
+    {
+        name: "ui_open_panel",
+        description: "Show content in the side panel. Prefer this over ui_navigate to keep " +
+            "chat visible. Use path for a page component (e.g. '/workspace'), " +
+            "or content for generated markdown/text.",
+        parameters: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Panel title" },
+                path: {
+                    type: "string",
+                    description: "Page path to render in the panel (e.g. '/workspace')",
+                },
+                content: {
+                    type: "string",
+                    description: "Markdown or text content (used when path is not provided)",
+                },
+                type: {
+                    type: "string",
+                    enum: ["markdown", "text"],
+                    description: "Content format (default: markdown)",
+                },
+            },
+            required: ["title"],
+        },
+        execute: async (argsJson) => {
+            const args = JSON.parse(argsJson || "{}");
+            if (args.path) {
+                useToolPanelStore.getState().openPanel({
+                    title: args.title,
+                    content: args.path,
+                    type: "page",
+                });
+            }
+            else {
+                useToolPanelStore.getState().openPanel({
+                    title: args.title,
+                    content: args.content || "",
+                    type: args.type || "markdown",
+                });
+            }
+            return JSON.stringify({
+                status: "success",
+                title: args.title,
+                mode: args.path ? "page" : "content",
+            });
+        },
+    },
+    {
+        name: "ui_select_item",
+        description: "Select an item in the current page by its ID. Highlights it in the UI.",
+        parameters: {
+            type: "object",
+            properties: {
+                itemId: {
+                    type: "string",
+                    description: "The ID of the item to select (or null to deselect)",
+                },
+            },
+            required: ["itemId"],
+        },
+        execute: async (argsJson) => {
+            const { itemId } = JSON.parse(argsJson || "{}");
+            useAppStore.getState().setSelectedItemId(itemId ?? null);
+            return JSON.stringify({ status: "success", itemId });
+        },
+    },
+    {
+        name: "ui_update_content",
+        description: "Update fields in the shared draft/form. Pass all fields as key-value " +
+            "pairs in a single call. Works for one or many fields.",
+        parameters: {
+            type: "object",
+            properties: {
+                fields: {
+                    type: "object",
+                    description: "Key-value pairs of field names and their values",
+                    additionalProperties: true,
+                },
+            },
+            required: ["fields"],
+        },
+        execute: async (argsJson) => {
+            const { fields } = JSON.parse(argsJson || "{}");
+            const store = useAppStore.getState();
+            for (const [key, value] of Object.entries(fields)) {
+                store.updateContentField(key, value);
+            }
+            return JSON.stringify({ status: "success", fields });
+        },
+    },
+    {
+        name: "ui_highlight",
+        description: "Highlight an entity in the UI to draw the user's attention.",
+        parameters: {
+            type: "object",
+            properties: {
+                entityId: {
+                    type: "string",
+                    description: "The ID of the entity to highlight",
+                },
+            },
+            required: ["entityId"],
+        },
+        execute: async (argsJson) => {
+            const { entityId } = JSON.parse(argsJson || "{}");
+            useAppStore.getState().addHighlight(entityId);
+            return JSON.stringify({ status: "success", entityId });
+        },
+    },
+    {
+        name: "ui_confirm",
+        description: "Ask the user to confirm or reject an action before proceeding. " +
+            "Use for destructive or important actions.",
+        parameters: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    description: "Short description of the action requiring confirmation",
+                },
+                details: {
+                    type: "string",
+                    description: "Optional details about what will happen",
+                },
+            },
+            required: ["action"],
+        },
+        execute: async (argsJson) => {
+            const { action, details } = JSON.parse(argsJson || "{}");
+            return JSON.stringify({
+                status: "pending",
+                action,
+                details: details || "",
+                message: "Awaiting user confirmation via chat.",
+            });
+        },
+    },
+    {
+        name: "ui_get_context",
+        description: "Get the full application context: navigation breadcrumb from root " +
+            "to current page (with accumulated metadata), selected items, draft " +
+            "values, highlights, and user-pinned context items.",
+        parameters: { type: "object", properties: {}, required: [] },
+        execute: async () => {
+            const state = useAppStore.getState().getAgentState();
+            const { useNavStore } = await import("./nav-store.js");
+            const navConfig = useNavStore.getState().config;
+            // Build breadcrumb: root group → parent item → current leaf
+            const breadcrumb = [];
+            for (const group of navConfig) {
+                for (const item of group.items) {
+                    if (item.to === state.navigation.page) {
+                        breadcrumb.push({ level: "group", label: group.label, meta: group.meta });
+                        breadcrumb.push({
+                            level: "page",
+                            label: item.label,
+                            description: item.description,
+                            meta: item.meta,
+                        });
+                        break;
+                    }
+                    if (item.children) {
+                        for (const child of item.children) {
+                            if (child.to === state.navigation.page) {
+                                breadcrumb.push({ level: "group", label: group.label, meta: group.meta });
+                                breadcrumb.push({
+                                    level: "parent",
+                                    label: item.label,
+                                    description: item.description,
+                                    meta: item.meta,
+                                });
+                                breadcrumb.push({
+                                    level: "page",
+                                    label: child.label,
+                                    description: child.description,
+                                    meta: child.meta,
+                                });
+                                break;
+                            }
+                        }
+                    }
+                }
+                if (breadcrumb.length > 0)
+                    break;
+            }
+            return JSON.stringify({
+                status: "success",
+                breadcrumb,
+                currentPage: state.navigation,
+                selectedItemId: state.selectedItemId,
+                content: state.content,
+                highlights: state.highlights,
+                contextItems: state.contextItems,
+            });
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Registration — called once at module load
+// ---------------------------------------------------------------------------
+export function registerGlobalTools() {
+    const registry = clientToolRegistry.getState();
+    for (const tool of GLOBAL_TOOLS) {
+        registry.registerGlobal(tool);
+    }
+}
+// Auto-register on import
+registerGlobalTools();

package/dist/lib/composer-submit-store.d.ts

@@ -0,0 +1,12 @@
+interface PendingComposerSubmit {
+    id: number;
+    text: string;
+}
+interface ComposerSubmitState {
+    pending: PendingComposerSubmit | null;
+    submit: (text: string) => void;
+    consume: (id: number) => void;
+}
+export declare const useComposerSubmitStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ComposerSubmitState>>;
+export declare function submitComposerText(text: string): void;
+export {};

package/dist/lib/composer-submit-store.js

@@ -0,0 +1,17 @@
+import { create } from "zustand";
+let nextSubmitId = 1;
+export const useComposerSubmitStore = create((set) => ({
+    pending: null,
+    submit: (text) => {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        set({ pending: { id: nextSubmitId++, text: trimmed } });
+    },
+    consume: (id) => set((state) => ({
+        pending: state.pending?.id === id ? null : state.pending,
+    })),
+}));
+export function submitComposerText(text) {
+    useComposerSubmitStore.getState().submit(text);
+}

package/dist/lib/dev-store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Dev Store — captures debug telemetry for the Dev Panel.
+ *
+ * Only populated in dev mode. Stores the last AG-UI request payload
+ * and tool call events so developers can inspect the full agent turn.
+ */
+export interface DevToolCall {
+    id: string;
+    name: string;
+    args: string;
+    result?: unknown;
+    isClientSide: boolean;
+    timestamp: number;
+}
+interface DevState {
+    /** Last AG-UI request payload (runInput) */
+    lastRequest: Record<string, unknown> | null;
+    /** Timestamp of last request */
+    lastRequestAt: number | null;
+    /** Tool calls from the current/last turn */
+    toolCalls: DevToolCall[];
+    /** SSE events log (last N) */
+    events: Array<{
+        type: string;
+        timestamp: number;
+        data?: string;
+    }>;
+    /** Capture a request payload (resets tool calls for new turn) */
+    captureRequest: (payload: Record<string, unknown>) => void;
+    /** Record a tool call */
+    addToolCall: (call: DevToolCall) => void;
+    /** Update a tool call with args and/or result */
+    updateToolCall: (id: string, update: Partial<Pick<DevToolCall, "args" | "result">>) => void;
+    /** Log an SSE event */
+    logEvent: (type: string, data?: string) => void;
+}
+export declare const useDevStore: import("zustand").UseBoundStore<import("zustand").StoreApi<DevState>>;
+export {};

package/dist/lib/dev-store.js

@@ -0,0 +1,32 @@
+/**
+ * Dev Store — captures debug telemetry for the Dev Panel.
+ *
+ * Only populated in dev mode. Stores the last AG-UI request payload
+ * and tool call events so developers can inspect the full agent turn.
+ */
+import { create } from "zustand";
+const MAX_EVENTS = 50;
+export const useDevStore = create((set, get) => ({
+    lastRequest: null,
+    lastRequestAt: null,
+    toolCalls: [],
+    events: [],
+    captureRequest: (payload) => {
+        const isFollowUp = get().toolCalls.length > 0;
+        set({
+            lastRequest: payload,
+            lastRequestAt: Date.now(),
+            // Keep tool calls for follow-up requests (multi-turn), reset on fresh turn
+            ...(isFollowUp ? {} : { toolCalls: [], events: [] }),
+        });
+    },
+    addToolCall: (call) => set({ toolCalls: [...get().toolCalls, call] }),
+    updateToolCall: (id, update) => set({
+        toolCalls: get().toolCalls.map((tc) => (tc.id === id ? { ...tc, ...update } : tc)),
+    }),
+    logEvent: (type, data) => {
+        const events = get().events;
+        const next = [...events, { type, timestamp: Date.now(), data }];
+        set({ events: next.length > MAX_EVENTS ? next.slice(-MAX_EVENTS) : next });
+    },
+}));

package/dist/lib/nav-config.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Navigation Configuration — types, default config, and lookup utility.
+ *
+ * This is the single source of truth for the sidebar and agent context projection.
+ * The sidebar and app-layout read from the nav store (nav-store.ts), which is
+ * initialized with DEFAULT_NAV_CONFIG. Dynamic items (e.g., from a database)
+ * can be merged at runtime via useNavStore.getState().addGroup().
+ */
+import type { LucideIcon } from "lucide-react";
+export interface NavItemAction {
+    icon: LucideIcon;
+    label: string;
+    handler: () => void | Promise<void>;
+    /** Render a separator line before this action. */
+    separator?: boolean;
+    /** Style as destructive (red text). */
+    destructive?: boolean;
+}
+/** Drag-and-drop behavior for a nav item. Provided by feature modules (e.g., SPACES). */
+export interface NavItemDnd {
+    /** MIME type for dataTransfer */
+    type: string;
+    /** Data to set on drag start (e.g., entity ID) */
+    getData: () => string | null;
+    /** Whether this item can be dragged */
+    canDrag: () => boolean;
+    /** Whether this item accepts drops */
+    canDrop: () => boolean;
+    /** Whether this item accepts external file drops (e.g. from Finder) */
+    canDropFiles?: () => boolean;
+    /** Handle a drop event — receives dragged data string and returns a promise */
+    onDrop: (draggedData: string) => Promise<void>;
+    /** Handle external file drop — receives File objects from the browser */
+    onFileDrop?: (files: File[]) => Promise<void>;
+}
+export interface NavItem {
+    to: string;
+    label: string;
+    icon: LucideIcon;
+    /** When true, the item is visible but not clickable (ghost state for label scope). */
+    disabled?: boolean;
+    /** Render with reduced opacity (e.g., hidden files). */
+    dimmed?: boolean;
+    /** Small text badge after the label (e.g., "managed", "locked"). */
+    badge?: string;
+    /** Small status dot after the label for quiet state hints such as pending review impact. */
+    statusDot?: {
+        tone?: "neutral" | "info" | "low-impact" | "medium-impact" | "high-impact" | "pending";
+        label?: string;
+    };
+    /**
+     * Optional warning / status icon shown after the label. Use for
+     * "something needs attention" annotations (e.g. failed indexing,
+     * permission drift) where a coloured dot isn't legible enough.
+     * Pass any LucideIcon; the tone drives the colour.
+     */
+    statusIcon?: {
+        icon: LucideIcon;
+        tone?: "neutral" | "info" | "warning" | "danger";
+        label?: string;
+    };
+    /** Page description sent to the agent for context */
+    description?: string;
+    /** Arbitrary metadata sent to the agent (e.g., workspace IDs, entity types) */
+    meta?: Record<string, unknown>;
+    /** Page-specific instructions automatically sent to the agent when this page is active */
+    contextInstructions?: string;
+    /** Sub-navigation items (rendered indented under parent) */
+    children?: NavItem[];
+    /** Inline action buttons rendered next to the nav item (e.g., + document, + folder) */
+    actions?: NavItemAction[];
+    /** Optional drag-and-drop behavior (provided by feature modules) */
+    dnd?: NavItemDnd;
+}
+/** Action shown in the "+" dropdown on a nav group header. */
+export interface NavGroupCreateAction {
+    id: string;
+    label: string;
+    handler: () => void;
+}
+/** Item rendered on the collapsed sidebar rail. Returned by `NavGroup.collapsedRail`. */
+export interface CollapsedRailItem {
+    to: string;
+    label: string;
+    icon: LucideIcon;
+    isActive: boolean;
+}
+/**
+ * Context passed to `NavGroup.collapsedRail` so the renderer can decide which
+ * shortcuts to surface. Modules read their own keys out of `navContextMeta`
+ * (e.g., Spaces uses `spacesRootId`).
+ */
+export interface CollapsedRailContext {
+    currentPage: string;
+    navContextMeta: Record<string, unknown>;
+}
+export interface NavGroup {
+    label: string;
+    items: NavItem[];
+    /**
+     * Render order weight. Higher = higher in the sidebar. Default 0.
+     * Ties keep insertion order (stable sort), so existing call sites
+     * that don't set a priority preserve the legacy "addGroup appends"
+     * behaviour. Use this to pin a group to a specific slot regardless
+     * of which feature hook finishes first.
+     */
+    priority?: number;
+    /**
+     * When true, the group header gets a click-to-toggle chevron and
+     * the children hide when collapsed. State persists per group label
+     * in localStorage so the user's preference survives reloads. Mutually
+     * exclusive with ``hideLabel`` — a hidden label can't host a chevron.
+     *
+     * If any child carries a :attr:`NavItem.statusDot`, it bubbles up to
+     * the collapsed header so the user can still see "the active chat is
+     * inside this collapsed group" without auto-expanding.
+     */
+    collapsible?: boolean;
+    /** Initial collapse state when no user preference is stored. */
+    defaultCollapsed?: boolean;
+    /** Optional link for the group header label */
+    to?: string;
+    /** Hide the group header while preserving group semantics. */
+    hideLabel?: boolean;
+    /** Group description sent to the agent */
+    description?: string;
+    /** Group-level metadata (e.g., org settings, workspace config, custom instructions) */
+    meta?: Record<string, unknown>;
+    /** Group-level instructions automatically sent to the agent for all pages in this group */
+    contextInstructions?: string;
+    /** Create actions shown as a "+" dropdown in the group header */
+    createActions?: NavGroupCreateAction[];
+    /**
+     * Optional override for the collapsed sidebar rail. When present, the
+     * shell calls this instead of mapping `items` to icons one-to-one.
+     *
+     * Useful for groups whose collapsed view is "header link plus the active
+     * item's root", not a flat icon list. Returning `[]` hides the group.
+     */
+    collapsedRail?: (ctx: CollapsedRailContext) => CollapsedRailItem[];
+}
+/** Static default config — the template ships with these pages. */
+export declare const DEFAULT_NAV_CONFIG: NavGroup[];
+/**
+ * Find the active nav item by path match.
+ * Tries exact match first, then longest-prefix match for dynamic routes.
+ * Searches top-level items and their children.
+ *
+ * For dynamic routes loaded from a database, add them to the nav store
+ * at runtime — they'll be found here automatically.
+ */
+export interface NavMatch {
+    group: string;
+    groupMeta?: Record<string, unknown>;
+    groupDescription?: string;
+    groupInstructions?: string;
+    item: NavItem;
+}
+export declare function findNavItem(config: NavGroup[], path: string): NavMatch | null;