@notis_ai/cli 0.2.0 → 0.2.1

package/template/packages/notis-sdk/src/hooks/useMultiSelect.ts

@@ -0,0 +1,502 @@
+'use client';
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type MouseEvent as ReactMouseEvent,
+} from 'react';
+
+const ROW_ATTR = 'data-notis-row-id';
+const INTERACTIVE_SELECTOR = 'button, a, input, textarea, select, [role="button"]';
+
+export interface DragRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export interface UseMultiSelectOptions<T> {
+  items: T[];
+  getId: (item: T) => string;
+  /** When false, suppresses the global Esc / Cmd+A / X / Shift+Arrow listeners. Default true. */
+  bindKeyboardShortcuts?: boolean;
+  /** When false, disables the rubber-band drag-select rectangle. Default true. */
+  enableDragSelect?: boolean;
+  /** Distance (px) the cursor must move past mousedown before a drag begins. Default 5. */
+  dragThreshold?: number;
+  /** Initial head id (the row that Shift+Arrow extends from). */
+  initialHeadId?: string | null;
+  /** Fires when the head moves via Shift+Arrow so the consumer can scroll the row into view. */
+  onHeadChange?: (id: string | null) => void;
+}
+
+export interface MultiSelectController<T> {
+  selectedIds: ReadonlySet<string>;
+  selectedCount: number;
+  lastClickedId: string | null;
+  headId: string | null;
+  /** Viewport-fixed drag rectangle, or null when no drag is active. */
+  dragRect: DragRect | null;
+
+  isSelected: (id: string) => boolean;
+  getSelectedItems: () => T[];
+
+  toggle: (id: string) => void;
+  select: (ids: string[]) => void;
+  clear: () => void;
+  selectAll: () => void;
+  selectRange: (anchorId: string, targetId: string) => void;
+  setHead: (id: string | null) => void;
+
+  /** Click handler for a row's hover checkbox. Toggles, with shift-click range from lastClickedId. */
+  onCheckboxClick: (id: string) => (event: ReactMouseEvent) => void;
+  /** mousedown on a row body — handles Cmd/Ctrl+click toggle without opening detail. */
+  onRowMouseDown: (id: string) => (event: ReactMouseEvent) => void;
+
+  /** Spread on each selectable row so drag-select can find them. */
+  getRowProps: (id: string) => { [ROW_ATTR]: string };
+  /** Spread on the list container — owns the drag-select mousedown/move/up + click-empty-to-clear. */
+  getContainerProps: () => {
+    ref: (node: HTMLElement | null) => void;
+    onMouseDown: (event: ReactMouseEvent) => void;
+    onClickCapture: (event: ReactMouseEvent) => void;
+    style: { userSelect: 'none' };
+  };
+}
+
+function isEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+}
+
+function rectsIntersect(
+  a: { left: number; top: number; right: number; bottom: number },
+  b: { left: number; top: number; right: number; bottom: number },
+): boolean {
+  return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
+}
+
+export function useMultiSelect<T>(opts: UseMultiSelectOptions<T>): MultiSelectController<T> {
+  const {
+    items,
+    getId,
+    bindKeyboardShortcuts = true,
+    enableDragSelect = true,
+    dragThreshold = 5,
+    initialHeadId = null,
+    onHeadChange,
+  } = opts;
+
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(() => new Set());
+  const [lastClickedId, setLastClickedId] = useState<string | null>(null);
+  const [headId, setHeadIdState] = useState<string | null>(initialHeadId);
+  const [dragRect, setDragRect] = useState<DragRect | null>(null);
+
+  // Latest-state refs so document listeners and stable callbacks read fresh
+  // values without retriggering the effect.
+  const itemsRef = useRef(items);
+  const getIdRef = useRef(getId);
+  const selectedIdsRef = useRef(selectedIds);
+  const lastClickedIdRef = useRef(lastClickedId);
+  const headIdRef = useRef(headId);
+  const onHeadChangeRef = useRef(onHeadChange);
+  const containerRef = useRef<HTMLElement | null>(null);
+
+  itemsRef.current = items;
+  getIdRef.current = getId;
+  selectedIdsRef.current = selectedIds;
+  lastClickedIdRef.current = lastClickedId;
+  headIdRef.current = headId;
+  onHeadChangeRef.current = onHeadChange;
+
+  const orderedIds = useMemo(() => items.map((item) => getId(item)), [items, getId]);
+  const orderedIdsRef = useRef(orderedIds);
+  orderedIdsRef.current = orderedIds;
+
+  const isSelected = useCallback((id: string) => selectedIds.has(id), [selectedIds]);
+
+  const getSelectedItems = useCallback(() => {
+    const set = selectedIdsRef.current;
+    return itemsRef.current.filter((item) => set.has(getIdRef.current(item)));
+  }, []);
+
+  const setHead = useCallback((id: string | null) => {
+    setHeadIdState((prev) => {
+      if (prev === id) return prev;
+      onHeadChangeRef.current?.(id);
+      return id;
+    });
+  }, []);
+
+  const toggle = useCallback((id: string) => {
+    setSelectedIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+    setLastClickedId(id);
+  }, []);
+
+  const select = useCallback((ids: string[]) => {
+    setSelectedIds(new Set(ids));
+    setLastClickedId(ids.length > 0 ? ids[ids.length - 1] : null);
+  }, []);
+
+  const clear = useCallback(() => {
+    setSelectedIds((prev) => (prev.size === 0 ? prev : new Set()));
+  }, []);
+
+  const selectAll = useCallback(() => {
+    const all = orderedIdsRef.current;
+    setSelectedIds(new Set(all));
+    setLastClickedId(all.length > 0 ? all[all.length - 1] : null);
+  }, []);
+
+  const selectRange = useCallback((anchorId: string, targetId: string) => {
+    const all = orderedIdsRef.current;
+    const anchorIdx = all.indexOf(anchorId);
+    const targetIdx = all.indexOf(targetId);
+    if (anchorIdx === -1 || targetIdx === -1) {
+      setSelectedIds(new Set([targetId]));
+      setLastClickedId(targetId);
+      return;
+    }
+    const start = Math.min(anchorIdx, targetIdx);
+    const end = Math.max(anchorIdx, targetIdx);
+    const range = all.slice(start, end + 1);
+    setSelectedIds((prev) => {
+      const next = new Set(prev);
+      for (const id of range) next.add(id);
+      return next;
+    });
+    setLastClickedId(targetId);
+  }, []);
+
+  const onCheckboxClick = useCallback(
+    (id: string) =>
+      (event: ReactMouseEvent) => {
+        event.stopPropagation();
+        if (event.shiftKey && lastClickedIdRef.current && lastClickedIdRef.current !== id) {
+          selectRange(lastClickedIdRef.current, id);
+          return;
+        }
+        toggle(id);
+      },
+    [selectRange, toggle],
+  );
+
+  const onRowMouseDown = useCallback(
+    (id: string) =>
+      (event: ReactMouseEvent) => {
+        if (event.button !== 0) return;
+        if (!(event.metaKey || event.ctrlKey)) return;
+        const target = event.target as HTMLElement | null;
+        if (target && target.closest(INTERACTIVE_SELECTOR)) return;
+        event.preventDefault();
+        event.stopPropagation();
+        toggle(id);
+        // The trailing click on the row should NOT open it.
+        armSuppressNextClick();
+      },
+    [toggle],
+  );
+
+  const getRowProps = useCallback(
+    (id: string) => ({
+      [ROW_ATTR]: id,
+    }),
+    [],
+  );
+
+  // ---------------------------------------------------------------------------
+  // Drag-select
+  // ---------------------------------------------------------------------------
+
+  const dragPendingRef = useRef(false);
+  const dragActiveRef = useRef(false);
+  const dragStartRef = useRef<{ x: number; y: number }>({ x: 0, y: 0 });
+  const dragCurrentRef = useRef<{ x: number; y: number }>({ x: 0, y: 0 });
+  // Tracks whether the most recent mousedown originated outside any row, which
+  // means a bare click should clear the selection.
+  const clickShouldClearRef = useRef(false);
+  // Set true after a gesture that should NOT trigger the row's onClick: an
+  // active drag-select, or a cmd/ctrl-click toggle. The container's
+  // onClickCapture consumes the next click before it reaches the row.
+  const suppressNextClickRef = useRef(false);
+
+  const armSuppressNextClick = () => {
+    suppressNextClickRef.current = true;
+    setTimeout(() => {
+      suppressNextClickRef.current = false;
+    }, 0);
+  };
+
+  const computeDragRect = useCallback((): DragRect => {
+    const start = dragStartRef.current;
+    const current = dragCurrentRef.current;
+    return {
+      left: Math.min(start.x, current.x),
+      top: Math.min(start.y, current.y),
+      width: Math.abs(current.x - start.x),
+      height: Math.abs(current.y - start.y),
+    };
+  }, []);
+
+  const computeIntersectingIds = useCallback(
+    (rect: { left: number; top: number; right: number; bottom: number }): string[] => {
+      const container = containerRef.current;
+      if (!container) return [];
+      const nodes = container.querySelectorAll<HTMLElement>(`[${ROW_ATTR}]`);
+      const ids: string[] = [];
+      nodes.forEach((node) => {
+        const rowRect = node.getBoundingClientRect();
+        if (rectsIntersect(rect, rowRect)) {
+          const id = node.getAttribute(ROW_ATTR);
+          if (id) ids.push(id);
+        }
+      });
+      return ids;
+    },
+    [],
+  );
+
+  const setContainerRef = useCallback(
+    (node: HTMLElement | null) => {
+      containerRef.current = node;
+    },
+    [],
+  );
+
+  const handleContainerMouseDown = useCallback(
+    (event: ReactMouseEvent) => {
+      if (event.button !== 0) return;
+      const target = event.target as HTMLElement | null;
+      if (!target) return;
+      // Cmd/Ctrl-click on a row is handled by `onRowMouseDown` (which calls
+      // stopPropagation), so we never reach here for that case. Skip if the
+      // mousedown lands on an interactive element so its native focus/text
+      // behavior is preserved.
+      if (target.closest(INTERACTIVE_SELECTOR)) {
+        clickShouldClearRef.current = false;
+        return;
+      }
+      const isOnRow = Boolean(target.closest(`[${ROW_ATTR}]`));
+      // A click on empty space (not on a row) should clear the selection.
+      clickShouldClearRef.current = !isOnRow;
+      if (!enableDragSelect) return;
+      // Arm a possible drag from anywhere in the container — including row
+      // bodies. If the user moves past the threshold we activate a rubber-band
+      // selection AND suppress the trailing click on the row.
+      dragPendingRef.current = true;
+      dragStartRef.current = { x: event.clientX, y: event.clientY };
+      dragCurrentRef.current = { x: event.clientX, y: event.clientY };
+    },
+    [enableDragSelect],
+  );
+
+  // Capture-phase click handler intercepts the trailing click after a drag so
+  // the row's bubble-phase onClick (which would open the row) never fires.
+  const handleContainerClickCapture = useCallback(
+    (event: ReactMouseEvent) => {
+      if (suppressNextClickRef.current) {
+        suppressNextClickRef.current = false;
+        event.stopPropagation();
+        event.preventDefault();
+      }
+    },
+    [],
+  );
+
+  // Attach document mousemove/mouseup while a drag is pending or active.
+  useEffect(() => {
+    if (!enableDragSelect) return;
+
+    const handleMouseMove = (event: MouseEvent) => {
+      if (dragPendingRef.current) {
+        const dx = event.clientX - dragStartRef.current.x;
+        const dy = event.clientY - dragStartRef.current.y;
+        if (Math.abs(dx) > dragThreshold || Math.abs(dy) > dragThreshold) {
+          dragPendingRef.current = false;
+          dragActiveRef.current = true;
+          window.getSelection()?.removeAllRanges();
+          dragCurrentRef.current = { x: event.clientX, y: event.clientY };
+          setDragRect(computeDragRect());
+        }
+        return;
+      }
+      if (!dragActiveRef.current) return;
+      event.preventDefault();
+      dragCurrentRef.current = { x: event.clientX, y: event.clientY };
+      const rect = computeDragRect();
+      setDragRect(rect);
+      const ids = computeIntersectingIds({
+        left: rect.left,
+        top: rect.top,
+        right: rect.left + rect.width,
+        bottom: rect.top + rect.height,
+      });
+      setSelectedIds(new Set(ids));
+      setLastClickedId(ids.length > 0 ? ids[ids.length - 1] : null);
+    };
+
+    const handleMouseUp = () => {
+      const wasPending = dragPendingRef.current;
+      const wasActive = dragActiveRef.current;
+      dragPendingRef.current = false;
+      dragActiveRef.current = false;
+      if (wasActive) {
+        setDragRect(null);
+        clickShouldClearRef.current = false;
+        // The trailing click on the row should not open it.
+        armSuppressNextClick();
+        return;
+      }
+      if (wasPending && clickShouldClearRef.current) {
+        // Bare click on empty space — clear the selection.
+        clickShouldClearRef.current = false;
+        if (selectedIdsRef.current.size > 0) {
+          setSelectedIds(new Set());
+        }
+      }
+    };
+
+    document.addEventListener('mousemove', handleMouseMove);
+    document.addEventListener('mouseup', handleMouseUp);
+    return () => {
+      document.removeEventListener('mousemove', handleMouseMove);
+      document.removeEventListener('mouseup', handleMouseUp);
+    };
+  }, [computeDragRect, computeIntersectingIds, dragThreshold, enableDragSelect]);
+
+  // ---------------------------------------------------------------------------
+  // Keyboard shortcuts
+  // ---------------------------------------------------------------------------
+
+  useEffect(() => {
+    if (!bindKeyboardShortcuts) return;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (isEditableTarget(event.target)) return;
+
+      // Esc — clear selection
+      if (event.key === 'Escape') {
+        if (selectedIdsRef.current.size > 0) {
+          event.preventDefault();
+          setSelectedIds(new Set());
+        }
+        return;
+      }
+
+      // Cmd/Ctrl + A — select all
+      if ((event.metaKey || event.ctrlKey) && !event.shiftKey && !event.altKey) {
+        const key = event.key.toLowerCase();
+        if (key === 'a') {
+          if (orderedIdsRef.current.length === 0) return;
+          event.preventDefault();
+          const all = orderedIdsRef.current;
+          setSelectedIds(new Set(all));
+          setLastClickedId(all[all.length - 1] ?? null);
+          return;
+        }
+      }
+
+      // X — toggle the focused/head row
+      if (
+        event.key === 'x' &&
+        !event.shiftKey &&
+        !event.metaKey &&
+        !event.ctrlKey &&
+        !event.altKey
+      ) {
+        const targetId = headIdRef.current ?? lastClickedIdRef.current;
+        if (!targetId) return;
+        event.preventDefault();
+        toggle(targetId);
+        return;
+      }
+
+      // Shift + ArrowUp / ArrowDown — extend range from anchor
+      if (
+        (event.key === 'ArrowDown' || event.key === 'ArrowUp') &&
+        event.shiftKey &&
+        !event.metaKey &&
+        !event.ctrlKey &&
+        !event.altKey
+      ) {
+        const all = orderedIdsRef.current;
+        if (all.length === 0) return;
+        event.preventDefault();
+        const direction = event.key === 'ArrowDown' ? 1 : -1;
+        const currentHead = headIdRef.current;
+        const currentIdx = currentHead ? all.indexOf(currentHead) : -1;
+        const newIdx =
+          currentIdx === -1
+            ? direction === 1
+              ? 0
+              : all.length - 1
+            : Math.min(all.length - 1, Math.max(0, currentIdx + direction));
+        if (newIdx === currentIdx) return;
+        const newHead = all[newIdx];
+        const anchorId = lastClickedIdRef.current ?? currentHead ?? newHead;
+        const anchorIdx = all.indexOf(anchorId);
+        if (anchorIdx === -1) {
+          setSelectedIds(new Set([newHead]));
+        } else {
+          const start = Math.min(anchorIdx, newIdx);
+          const end = Math.max(anchorIdx, newIdx);
+          setSelectedIds(new Set(all.slice(start, end + 1)));
+        }
+        if (lastClickedIdRef.current === null) {
+          setLastClickedId(anchorId);
+        }
+        setHead(newHead);
+        return;
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [bindKeyboardShortcuts, setHead, toggle]);
+
+  const getContainerProps = useCallback(
+    () => ({
+      ref: setContainerRef,
+      onMouseDown: handleContainerMouseDown,
+      onClickCapture: handleContainerClickCapture,
+      style: { userSelect: 'none' as const },
+    }),
+    [handleContainerClickCapture, handleContainerMouseDown, setContainerRef],
+  );
+
+  return {
+    selectedIds,
+    selectedCount: selectedIds.size,
+    lastClickedId,
+    headId,
+    dragRect,
+    isSelected,
+    getSelectedItems,
+    toggle,
+    select,
+    clear,
+    selectAll,
+    selectRange,
+    setHead,
+    onCheckboxClick,
+    onRowMouseDown,
+    getRowProps,
+    getContainerProps,
+  };
+}

package/template/packages/notis-sdk/src/hooks/useNotis.ts

@@ -0,0 +1,33 @@
+'use client';
+
+import { useNotisRuntime } from '../provider';
+import type { AppDescriptor, RouteDescriptor, DatabaseDescriptor, CollectionItemDetail } from '../runtime';
+
+interface NotisContext {
+  /** App metadata (id, name, icon, description). Null before runtime loads. */
+  app: AppDescriptor | null;
+  /** Current route descriptor. Null before runtime loads. */
+  route: RouteDescriptor | null;
+  /** Databases declared by this app. Empty before runtime loads. */
+  databases: DatabaseDescriptor[];
+  /** Selected collection item for the current route, when applicable. */
+  collectionItem: CollectionItemDetail | null;
+  /** Whether the runtime is loaded and available. */
+  ready: boolean;
+}
+
+/**
+ * Access app-level metadata: the app descriptor, current route, and declared
+ * databases. Returns safe defaults when the portal runtime is not available.
+ */
+export function useNotis(): NotisContext {
+  const runtime = useNotisRuntime();
+
+  return {
+    app: runtime?.app ?? null,
+    route: runtime?.route ?? null,
+    databases: runtime?.databases ?? [],
+    collectionItem: runtime?.context?.collectionItem ?? null,
+    ready: runtime !== null,
+  };
+}

package/template/packages/notis-sdk/src/hooks/useNotisNavigation.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import { useCallback } from 'react';
+import { useNotisRuntime } from '../provider';
+
+interface NavigationActions {
+  /** Navigate to a route within the app by its path. */
+  toRoute: (path: string) => void;
+  /** Navigate to a document detail view. */
+  toDocument: (documentId: string) => void;
+  /** Navigate to the app's default route. */
+  toApp: () => void;
+}
+
+/**
+ * Navigation helpers for moving between routes and documents within the app.
+ * When rendered inside the portal, uses the runtime.navigate() bridge.
+ * Without a portal runtime, falls back to window.location for route navigation.
+ *
+ * ```tsx
+ * const nav = useNotisNavigation();
+ * nav.toRoute('/settings');
+ * ```
+ */
+export function useNotisNavigation(): NavigationActions {
+  const runtime = useNotisRuntime();
+
+  const toRoute = useCallback((path: string) => {
+    if (runtime?.navigate) {
+      runtime.navigate({ kind: 'route', path });
+    } else if (typeof window !== 'undefined') {
+      window.location.href = path;
+    }
+  }, [runtime]);
+
+  const toDocument = useCallback((documentId: string) => {
+    if (runtime?.navigate) {
+      runtime.navigate({ kind: 'document', documentId });
+    }
+  }, [runtime]);
+
+  const toApp = useCallback(() => {
+    if (runtime?.navigate) {
+      runtime.navigate({ kind: 'app' });
+    }
+  }, [runtime]);
+
+  return { toRoute, toDocument, toApp };
+}

package/template/packages/notis-sdk/src/hooks/useTool.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+
+interface UseToolResult {
+  call: (args?: Record<string, unknown>) => Promise<unknown>;
+  loading: boolean;
+  error: Error | null;
+}
+
+/**
+ * Call a specific Notis tool by name.
+ *
+ * ```tsx
+ * const { call, loading } = useTool('notis_web_search');
+ * const result = await call({ query: 'latest news' });
+ * ```
+ */
+export function useTool(toolName: string): UseToolResult {
+  const runtime = useNotisRuntime();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const call = useCallback(
+    async (args?: Record<string, unknown>): Promise<unknown> => {
+      if (!runtime) {
+        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
+      }
+
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await runtime.callTool(toolName, args);
+        return result;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [runtime, toolName],
+  );
+
+  return { call, loading, error };
+}

package/template/packages/notis-sdk/src/hooks/useTools.ts

@@ -0,0 +1,56 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { ToolDescriptor } from '../runtime';
+
+interface UseToolsResult {
+  tools: ToolDescriptor[];
+  loading: boolean;
+  error: Error | null;
+}
+
+/**
+ * List all tools available to this app.
+ *
+ * ```tsx
+ * const { tools, loading } = useTools();
+ * ```
+ */
+export function useTools(): UseToolsResult {
+  const runtime = useNotisRuntime();
+  const [tools, setTools] = useState<ToolDescriptor[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!runtime) {
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+
+    runtime
+      .listTools()
+      .then((result) => {
+        if (!cancelled) {
+          setTools(result);
+          setLoading(false);
+        }
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+          setLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime]);
+
+  return { tools, loading, error };
+}