@iloveagents/foundry-web-ui 0.1.0

package/src/lib/nav-config.ts

@@ -0,0 +1,292 @@
+/**
+ * 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";
+import {
+  MessageSquare,
+  // FileEdit,
+  // FolderOpen,
+  // BarChart3,
+  // ClipboardList,
+  // FileText,
+} 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;
+  /** 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[];
+  /** 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 const DEFAULT_NAV_CONFIG: NavGroup[] = [
+  {
+    label: "Pages",
+    hideLabel: true,
+    items: [
+      {
+        to: "/",
+        label: "Chat",
+        icon: MessageSquare,
+        description: "Chat with the AI assistant",
+      },
+      // {
+      //   to: "/dashboard",
+      //   label: "Dashboard",
+      //   icon: BarChart3,
+      //   description: "Overview and analytics",
+      // },
+    ],
+  },
+  // {
+  //   label: "Demos",
+  //   description: "Demo pages for the Acme Corp engagement",
+  //   meta: {
+  //     workspaceId: "ws-acme-2026",
+  //     client: "Acme Corp",
+  //     region: "eu-west",
+  //     permissions: ["read", "write", "comment"],
+  //   },
+  //   contextInstructions:
+  //     "This is the Acme Corp demo workspace. Always address the user professionally. " +
+  //     "When referencing documents or drafts, mention they belong to the Acme Corp project.",
+  //   items: [
+  //     {
+  //       to: "/workspace",
+  //       label: "Form",
+  //       icon: ClipboardList,
+  //       description:
+  //         "Draft form with fields: title, description, category " +
+  //         "(Bug/Feature/Task/Improvement), priority (Low/Medium/High/Critical), " +
+  //         "assignee. Use ui_update_content to fill fields.",
+  //       meta: { type: "form", formId: "default" },
+  //       contextInstructions:
+  //         "Always use ui_update_content to fill all fields in a single call. " +
+  //         "Ask for confirmation before clearing the form. " +
+  //         "Suggest appropriate category and priority based on the description.",
+  //     },
+  //     {
+  //       to: "/documents",
+  //       label: "Documents",
+  //       icon: FolderOpen,
+  //       description: "Browse and manage documents",
+  //       children: [
+  //         {
+  //           to: "/documents",
+  //           label: "All Documents",
+  //           icon: FolderOpen,
+  //           description: "Browse all documents",
+  //         },
+  //         {
+  //           to: "/documents",
+  //           label: "Engineering",
+  //           icon: FileText,
+  //           description: "Engineering documents",
+  //           meta: { category: "Engineering" },
+  //         },
+  //         {
+  //           to: "/documents",
+  //           label: "Planning",
+  //           icon: FileEdit,
+  //           description: "Planning documents",
+  //           meta: { category: "Planning" },
+  //         },
+  //       ],
+  //     },
+  //   ],
+  // },
+];
+
+/**
+ * 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;
+}
+
+function findExactNavItem(items: NavItem[], path: string): NavItem | null {
+  for (const item of items) {
+    if (item.to === path) {
+      return item;
+    }
+    if (item.children) {
+      const nested = findExactNavItem(item.children, path);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+function findBestPrefixNavItem(
+  items: NavItem[],
+  path: string,
+  currentBest: { item: NavItem; length: number } | null = null,
+): { item: NavItem; length: number } | null {
+  let best = currentBest;
+  for (const item of items) {
+    if (path.startsWith(item.to + "/") && item.to.length > (best?.length ?? 0)) {
+      best = { item, length: item.to.length };
+    }
+    if (item.children) {
+      best = findBestPrefixNavItem(item.children, path, best);
+    }
+  }
+  return best;
+}
+
+export function findNavItem(config: NavGroup[], path: string): NavMatch | null {
+  // Pass 1: exact match on items
+  for (const group of config) {
+    const base = {
+      group: group.label,
+      groupMeta: group.meta,
+      groupDescription: group.description,
+      groupInstructions: group.contextInstructions,
+    };
+    const match = findExactNavItem(group.items, path);
+    if (match) {
+      return { ...base, item: match };
+    }
+  }
+
+  // Pass 2: group-level `to` match (e.g. /spaces matches Workspaces group)
+  for (const group of config) {
+    if (group.to && group.to === path) {
+      return {
+        group: group.label,
+        groupMeta: group.meta,
+        groupDescription: group.description,
+        groupInstructions: group.contextInstructions,
+        item: { to: group.to, label: group.label, icon: MessageSquare },
+      };
+    }
+  }
+
+  // Pass 3: longest-prefix match (for dynamic/parameterized routes)
+  let best: NavMatch | null = null;
+  let bestLen = 0;
+  for (const group of config) {
+    const base = {
+      group: group.label,
+      groupMeta: group.meta,
+      groupDescription: group.description,
+      groupInstructions: group.contextInstructions,
+    };
+    const match = findBestPrefixNavItem(group.items, path);
+    if (match && match.length > bestLen) {
+      best = { ...base, item: match.item };
+      bestLen = match.length;
+    }
+  }
+  return best;
+}

package/src/lib/nav-dnd.ts

@@ -0,0 +1,14 @@
+export function hasExternalFilesData(dataTransfer: {
+  types: ArrayLike<string>;
+  files?: { length: number } | null;
+}): boolean {
+  return Array.from(dataTransfer.types).includes("Files") || (dataTransfer.files?.length ?? 0) > 0;
+}
+
+export function hasAnyDropTarget(isDropTarget: boolean, isFileDropTarget: boolean): boolean {
+  return isDropTarget || isFileDropTarget;
+}
+
+export function getContainerDropZoneLabel(hasExternalFiles: boolean): string {
+  return hasExternalFiles ? "Upload to root" : "Move to root";
+}

package/src/lib/nav-store.ts

@@ -0,0 +1,76 @@
+/**
+ * Navigation Store — Zustand store for the live navigation config.
+ *
+ * Initialized with DEFAULT_NAV_CONFIG (static pages).
+ * Dynamic groups/items (e.g., contract workspaces from a database)
+ * can be merged at runtime via addGroup() or setConfig().
+ *
+ * The sidebar and app-layout both subscribe to this store,
+ * so changes propagate automatically.
+ */
+
+import { create } from "zustand";
+import { type NavGroup, DEFAULT_NAV_CONFIG } from "./nav-config.ts";
+
+/** A toggle or action rendered at the bottom of the sidebar. */
+export interface NavFooterAction {
+  id: string;
+  label: string;
+  activeLabel?: string;
+  active: boolean;
+  onToggle: () => void;
+}
+
+interface NavStoreState {
+  config: NavGroup[];
+  footerActions: NavFooterAction[];
+  /** Replace the entire config */
+  setConfig: (config: NavGroup[]) => void;
+  /** Add a group (replaces existing group with the same label) */
+  addGroup: (group: NavGroup) => void;
+  /** Remove a group by label */
+  removeGroup: (label: string) => void;
+  /** Register a footer toggle (replaces existing by id) */
+  setFooterAction: (action: NavFooterAction) => void;
+  /** Remove a footer action by id */
+  removeFooterAction: (id: string) => void;
+}
+
+export const useNavStore = create<NavStoreState>((set, get) => ({
+  config: DEFAULT_NAV_CONFIG,
+  footerActions: [],
+
+  setConfig: (config) => set({ config }),
+
+  addGroup: (group) => {
+    const config = get().config;
+    const idx = config.findIndex((g) => g.label === group.label);
+    if (idx >= 0) {
+      const next = [...config];
+      next[idx] = group;
+      set({ config: next });
+    } else {
+      set({ config: [...config, group] });
+    }
+  },
+
+  removeGroup: (label) => {
+    set({ config: get().config.filter((g) => g.label !== label) });
+  },
+
+  setFooterAction: (action) => {
+    const actions = get().footerActions;
+    const idx = actions.findIndex((a) => a.id === action.id);
+    if (idx >= 0) {
+      const next = [...actions];
+      next[idx] = action;
+      set({ footerActions: next });
+    } else {
+      set({ footerActions: [...actions, action] });
+    }
+  },
+
+  removeFooterAction: (id) => {
+    set({ footerActions: get().footerActions.filter((a) => a.id !== id) });
+  },
+}));

package/src/lib/sidebar-store.ts

@@ -0,0 +1,113 @@
+/**
+ * Sidebar State Management
+ *
+ * Zustand store for the collapsible left sidebar.
+ * Persists expanded/collapsed state to localStorage.
+ */
+
+import { create } from "zustand";
+
+export const SIDEBAR_WIDTH = 272;
+export const RAIL_WIDTH = 52;
+export const SIDEBAR_MIN_WIDTH = 248;
+export const SIDEBAR_MAX_WIDTH = 440;
+const MOBILE_BREAKPOINT = 768;
+const STORAGE_KEY = "sidebar";
+const WIDTH_STORAGE_KEY = "sidebar-width";
+const WIDTH_VERSION_STORAGE_KEY = "sidebar-width-version";
+const WIDTH_PERSIST_DELAY_MS = 120;
+const SIDEBAR_WIDTH_VERSION = "2026-03-27-narrow";
+let persistWidthTimer: ReturnType<typeof setTimeout> | null = null;
+
+function clampWidth(width: number): number {
+  return Math.min(SIDEBAR_MAX_WIDTH, Math.max(SIDEBAR_MIN_WIDTH, width));
+}
+
+function getStoredOpen(): boolean {
+  if (typeof window === "undefined") return true;
+  const stored = localStorage.getItem(STORAGE_KEY);
+  if (stored === "true" || stored === "false") return stored === "true";
+  // Default: collapsed rail — users expand when they want it
+  return false;
+}
+
+function getStoredWidth(): number {
+  if (typeof window === "undefined") return SIDEBAR_WIDTH;
+  const version = localStorage.getItem(WIDTH_VERSION_STORAGE_KEY);
+  if (version !== SIDEBAR_WIDTH_VERSION) return SIDEBAR_WIDTH;
+  const raw = localStorage.getItem(WIDTH_STORAGE_KEY);
+  if (raw === null || raw.trim() === "") return SIDEBAR_WIDTH;
+  const stored = Number(raw);
+  if (!Number.isFinite(stored)) return SIDEBAR_WIDTH;
+  return clampWidth(stored);
+}
+
+function persistWidth(width: number): void {
+  if (typeof window === "undefined") return;
+  if (persistWidthTimer) window.clearTimeout(persistWidthTimer);
+  persistWidthTimer = window.setTimeout(() => {
+    localStorage.setItem(WIDTH_STORAGE_KEY, String(width));
+    localStorage.setItem(WIDTH_VERSION_STORAGE_KEY, SIDEBAR_WIDTH_VERSION);
+    persistWidthTimer = null;
+  }, WIDTH_PERSIST_DELAY_MS);
+}
+
+interface SidebarState {
+  isOpen: boolean;
+  isMobileOpen: boolean;
+  width: number;
+
+  toggle: () => void;
+  open: () => void;
+  close: () => void;
+  toggleMobile: () => void;
+  closeMobile: () => void;
+  setWidth: (width: number) => void;
+}
+
+export const useSidebarStore = create<SidebarState>((set, get) => ({
+  isOpen: getStoredOpen(),
+  isMobileOpen: false,
+  width: getStoredWidth(),
+
+  toggle: () => {
+    const next = !get().isOpen;
+    localStorage.setItem(STORAGE_KEY, String(next));
+    set({ isOpen: next });
+  },
+  open: () => {
+    localStorage.setItem(STORAGE_KEY, "true");
+    set({ isOpen: true });
+  },
+  close: () => {
+    localStorage.setItem(STORAGE_KEY, "false");
+    set({ isOpen: false });
+  },
+  toggleMobile: () => set({ isMobileOpen: !get().isMobileOpen }),
+  closeMobile: () => set({ isMobileOpen: false }),
+  setWidth: (width) => {
+    const next = clampWidth(width);
+    persistWidth(next);
+    set({ width: next });
+  },
+}));
+
+// Auto-close mobile drawer when resizing above breakpoint
+if (typeof window !== "undefined") {
+  const version = localStorage.getItem(WIDTH_VERSION_STORAGE_KEY);
+  if (version !== SIDEBAR_WIDTH_VERSION) {
+    localStorage.setItem(WIDTH_STORAGE_KEY, String(SIDEBAR_WIDTH));
+    localStorage.setItem(WIDTH_VERSION_STORAGE_KEY, SIDEBAR_WIDTH_VERSION);
+    useSidebarStore.setState({ width: SIDEBAR_WIDTH });
+  }
+
+  let timeout: ReturnType<typeof setTimeout>;
+  window.addEventListener("resize", () => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      if (window.innerWidth >= MOBILE_BREAKPOINT) {
+        useSidebarStore.getState().closeMobile();
+      }
+    }, 100);
+  });
+}