@notis_ai/cli 0.2.0-beta.16.1 → 0.2.0-beta.161.1

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

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

package/template/packages/sdk/src/hooks/useToolQuery.ts

@@ -0,0 +1,12 @@
+'use client';
+
+import { useNotisRuntime } from '../provider';
+import { useQuery, type UseQueryOptions } from './useQuery';
+
+/** An explicitly identified read-only tool, cached by tool name and exact arguments. */
+export function useToolQuery<T = unknown>(name: string, args: Record<string, unknown> = {}, options: UseQueryOptions) {
+  const runtime = useNotisRuntime();
+  return useQuery<T>(['tool', name, args], () => runtime!.callTool<T>(name, args, {
+    readOnly: true, dedupe: true,
+  }), options);
+}

package/template/packages/sdk/src/hooks/useTopBarSearch.ts

@@ -0,0 +1,81 @@
+'use client';
+
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
+import { useNotisRuntime } from '../provider';
+
+interface TopBarSearchOptions {
+  /** Current value shown in the top bar search input. */
+  value: string;
+  /** Called when the user types in the top bar. */
+  onChange: (value: string) => void;
+  /** Placeholder text for the input. Defaults to 'Search…'. */
+  placeholder?: string;
+  /** Called when the user presses Enter. May return a Promise. */
+  onSubmit?: () => void | Promise<void>;
+}
+
+interface TopBarSearchActions {
+  /** Toggle the loader that replaces the search icon in the top bar. */
+  setLoading: (loading: boolean) => void;
+}
+
+/**
+ * Registers this view's search binding with the portal's top bar search input.
+ * While the component is mounted, typing in the top bar calls `onChange`,
+ * pressing Enter calls `onSubmit`, and the `value` prop drives the input.
+ *
+ * Use `setLoading(true)` only for an explicitly submitted search action, then
+ * restore the icon with `setLoading(false)`. Automatic reads use content
+ * skeletons initially and refresh populated content silently.
+ *
+ * Without a portal runtime, this hook is a safe no-op.
+ *
+ * ```tsx
+ * const [q, setQ] = useState('');
+ * const { setLoading } = useTopBarSearch({
+ *   value: q,
+ *   onChange: setQ,
+ *   placeholder: 'Search notes…',
+ *   onSubmit: async () => {
+ *     setLoading(true);
+ *     try { await runSearch(q); } finally { setLoading(false); }
+ *   },
+ * });
+ * ```
+ *
+ * Callback refs retain the latest committed handlers without re-registering
+ * search on every app render. Inline callbacks are safe.
+ */
+export function useTopBarSearch(opts: TopBarSearchOptions): TopBarSearchActions {
+  const runtime = useNotisRuntime();
+  const { value, onChange, placeholder, onSubmit } = opts;
+  const callbacks = useRef({ onChange, onSubmit });
+  useLayoutEffect(() => { callbacks.current = { onChange, onSubmit }; });
+  const hasSubmit = Boolean(onSubmit);
+
+  useEffect(() => {
+    const register = runtime?.registerTopBarSearch;
+    if (!register) return;
+    register({
+      onChange: (next) => callbacks.current.onChange(next),
+      placeholder,
+      onSubmit: hasSubmit ? () => callbacks.current.onSubmit?.() : undefined,
+    });
+    return () => {
+      register(null);
+    };
+  }, [runtime, placeholder, hasSubmit]);
+
+  useEffect(() => {
+    runtime?.setTopBarSearchValue?.(value);
+  }, [runtime, value]);
+
+  const setLoading = useCallback(
+    (loading: boolean) => {
+      runtime?.setTopBarSearchLoading?.(loading);
+    },
+    [runtime],
+  );
+
+  return { setLoading };
+}

package/template/packages/sdk/src/hooks/useUpsertDocument.ts

@@ -0,0 +1,95 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord } from '../runtime';
+
+export interface UpsertDocumentArgs {
+  documentId?: string;
+  title?: string;
+  /** Property values keyed by property name (already-plain values). */
+  properties?: Record<string, unknown>;
+  /** Markdown content; converted server-side to BlockNote. Exclusive with contentBlocknote. */
+  contentMarkdown?: string | null;
+  /** BlockNote block JSON. Exclusive with contentMarkdown. */
+  contentBlocknote?: Array<Record<string, unknown>> | null;
+  /** 'archive' soft-deletes the document (sets archived_at); 'restore' undoes it. */
+  operation?: 'create' | 'update' | 'archive' | 'restore';
+}
+
+interface UpsertToolResult {
+  status?: string;
+  document?: unknown;
+  message?: string;
+  error?: string;
+}
+
+export interface UseUpsertDocumentResult {
+  upsert: (args: UpsertDocumentArgs) => Promise<DocumentRecord>;
+  loading: boolean;
+  error: Error | null;
+}
+
+function upsertToolName(databaseSlug: string): string {
+  return `LOCAL_NOTIS_DATABASE_UPSERT_${databaseSlug.replace(/-/g, '_').toUpperCase()}`;
+}
+
+function buildToolArgs(args: UpsertDocumentArgs): Record<string, unknown> {
+  const payload: Record<string, unknown> = {};
+  if (args.documentId) payload.document_id = args.documentId;
+  if (typeof args.title === 'string') payload.title = args.title;
+  if (args.properties) Object.assign(payload, args.properties);
+  if ('contentMarkdown' in args) payload.content_markdown = args.contentMarkdown ?? '';
+  if ('contentBlocknote' in args) payload.content_blocknote = args.contentBlocknote ?? null;
+  if (args.operation) payload.operation = args.operation;
+  return payload;
+}
+
+/**
+ * Create/update/archive documents in a Notis database.
+ *
+ * ```tsx
+ * const { upsert } = useUpsertDocument('journal_entries');
+ * await upsert({ documentId, properties: { Mood: 'Great' }, contentMarkdown: reflection });
+ * ```
+ */
+export function useUpsertDocument(databaseSlug: string): UseUpsertDocumentResult {
+  const runtime = useNotisRuntime();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const upsert = useCallback(
+    async (args: UpsertDocumentArgs): Promise<DocumentRecord> => {
+      if (!runtime) {
+        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
+      }
+      if ('contentMarkdown' in args && 'contentBlocknote' in args) {
+        throw new Error('Provide contentMarkdown or contentBlocknote, not both.');
+      }
+
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await runtime.callTool<UpsertToolResult>(
+          upsertToolName(databaseSlug),
+          buildToolArgs(args),
+        );
+        if (!result.document) {
+          throw new Error(result.error ?? result.message ?? 'Failed to save document');
+        }
+        return normalizeDocumentRecord(result.document);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [runtime, databaseSlug],
+  );
+
+  return { upsert, loading, error };
+}

package/template/packages/sdk/src/index.ts

@@ -0,0 +1,161 @@
+/**
+ * @notis/sdk - The Notis App SDK
+ *
+ * Public API for building Notis apps. Import hooks and the provider from
+ * this entrypoint. For configuration, use `@notis/sdk/config`. For the
+ * Vite config builder, use `@notis/sdk/vite`.
+ */
+
+// Provider
+export { NotisProvider, useNotisRuntime } from './provider';
+
+// Hooks
+export { useQuery, useQueryClient } from './hooks/useQuery';
+export type { UseQueryOptions, UseQueryResult } from './hooks/useQuery';
+export { createQueryClient, createPrefetchQueue, queryKey } from './queryCache';
+export type { NotisQueryClient, QuerySnapshot, QueryFetchOptions } from './queryCache';
+export { useNotis } from './hooks/useNotis';
+export { useDocuments } from './hooks/useDocuments';
+export type { UseDocumentsOptions, UseDocumentsResult } from './hooks/useDocuments';
+export { useDatabaseSubscription } from './hooks/useDatabaseSubscription';
+export type {
+  UseDatabaseSubscriptionOptions,
+  UseDatabaseSubscriptionResult,
+} from './hooks/useDatabaseSubscription';
+export { useDocument } from './hooks/useDocument';
+export type { UseDocumentOptions, UseDocumentResult } from './hooks/useDocument';
+export { useUpsertDocument } from './hooks/useUpsertDocument';
+export type { UpsertDocumentArgs, UseUpsertDocumentResult } from './hooks/useUpsertDocument';
+export { useDatabaseSchema } from './hooks/useDatabaseSchema';
+export type { UseDatabaseSchemaResult } from './hooks/useDatabaseSchema';
+export { useTool } from './hooks/useTool';
+export type { ToolCallState, UseToolResult } from './hooks/useTool';
+export { useTools } from './hooks/useTools';
+export { useHandover } from './hooks/useHandover';
+export type { UseHandoverResult } from './hooks/useHandover';
+export { useCloudComputer } from './hooks/useCloudComputer';
+export type { UseCloudComputerResult } from './hooks/useCloudComputer';
+export { useNotisNavigation } from './hooks/useNotisNavigation';
+export { useTopBarSearch } from './hooks/useTopBarSearch';
+export { useBackend } from './hooks/useBackend';
+export { useMultiSelect } from './hooks/useMultiSelect';
+export { useCollectionInteractions, COLLECTION_ITEM_ATTRIBUTE } from './hooks/useCollectionInteractions';
+export { useActiveResource } from './hooks/useActiveResource';
+export {
+  ShortcutProvider,
+  SHORTCUT_SCOPE_PRIORITY,
+  isEditableShortcutEvent,
+  shortcutDisplay,
+  useShortcuts,
+} from './interactions/shortcuts';
+
+// Documents & markdown
+export { Markdown } from './components/Markdown';
+export type { MarkdownProps } from './components/Markdown';
+export { DocumentEditor } from './components/DocumentEditor';
+export { MarkdownEditor } from './components/MarkdownEditor';
+export { NotisSelectionBoundary, NOTIS_CONTEXT_CLIPBOARD_TYPE } from './components/NotisSelectionBoundary';
+export type { NotisSelectionBoundaryProps } from './components/NotisSelectionBoundary';
+export {
+  asRecord,
+  blockNoteToPlainText,
+  extractRichText,
+  getDocumentPreview,
+  getRelationIds,
+  getSecretValue,
+  isPresentString,
+  markdownToPlainText,
+  normalizeDatabaseProperty,
+  normalizeDocumentRecord,
+  normalizePropertyValue,
+  optionalString,
+} from './documents';
+
+// Multi-select components
+export { MultiSelectActionBar } from './components/MultiSelectActionBar';
+export { MultiSelectCheckbox, MultiSelectCheckbox as SelectionCheckbox } from './components/MultiSelectCheckbox';
+export { MultiSelectDragOverlay, MultiSelectDragOverlay as SelectionMarquee } from './components/MultiSelectDragOverlay';
+export { ShortcutHints } from './components/ShortcutHints';
+export type {
+  DragRect,
+  MultiSelectController,
+  UseMultiSelectOptions,
+} from './hooks/useMultiSelect';
+export type {
+  MultiSelectAction,
+  MultiSelectActionBarProps,
+} from './components/MultiSelectActionBar';
+export type { MultiSelectCheckboxProps } from './components/MultiSelectCheckbox';
+export type { MultiSelectDragOverlayProps } from './components/MultiSelectDragOverlay';
+export type { MultiSelectCheckboxProps as SelectionCheckboxProps } from './components/MultiSelectCheckbox';
+export type { MultiSelectDragOverlayProps as SelectionMarqueeProps } from './components/MultiSelectDragOverlay';
+export type { ShortcutHint, ShortcutHintsProps } from './components/ShortcutHints';
+export type {
+  CollectionInteractionController,
+  CollectionInteractionReason,
+  CollectionKeyboardShortcuts,
+  CollectionNavigationContext,
+  CollectionNavigationDirection,
+  CollectionSelectionChange,
+  SelectionMarqueeRect,
+  UseCollectionInteractionsOptions,
+} from './hooks/useCollectionInteractions';
+export type {
+  ShortcutDefinition,
+  ShortcutHelpEntry,
+  ShortcutScope,
+  UseShortcutsOptions,
+} from './interactions/shortcuts';
+export type {
+  CollectionAction,
+  CollectionActionContext,
+  CollectionActionIntent,
+  ResolvedCollectionAction,
+} from './interactions/actions';
+
+// Types (re-exported for convenience)
+export type {
+  AppDescriptor,
+  CloudComputerCliAuthFacts,
+  CloudComputerFacts,
+  CloudComputerSandboxFacts,
+  ContextAttributeValue,
+  ContextResource,
+  ContextSelection,
+  CollectionItem,
+  CollectionItemDetail,
+  DatabaseDescriptor,
+  DatabaseProperty,
+  DatabasePropertyOption,
+  DatabasePropertyType,
+  DocumentContentType,
+  DocumentRecord,
+  HandoverPayload,
+  HandoverResult,
+  NotisDocumentEditorProps,
+  NotisMarkdownEditorProps,
+  NotisMarkdownEditorSavePayload,
+  NotisMarkdownEditorSaveResult,
+  NotisRuntime,
+  NotisRuntimeContext,
+  NotisRuntimeUI,
+  QueryFilter,
+  RouteDescriptor,
+  SecretPropertyValue,
+  SubscribeDatabaseOptions,
+  ToolDescriptor,
+  ToolCallOptions,
+  ToolInputSchema,
+} from './runtime';
+
+export { useToolQuery } from './hooks/useToolQuery';
+
+export { Skeleton, ViewSkeleton } from './components/Skeleton';
+
+export { useLongPressSelection } from './hooks/useLongPressSelection';
+export { isInteractionElementVisible } from './interactions/visibility';
+
+export type { AgentContextContent, AgentContextItem, ContextAttachment } from './agentContext';
+export { useAgentContext } from './hooks/useAgentContext';
+export { NotisCommentBoundary, NotisCommentBox } from './components/NotisCommentBoundary';
+export type { NotisCommentBoundaryProps, NotisCommentBoxProps } from './components/NotisCommentBoundary';

package/template/packages/sdk/src/interactions/actions.ts

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+
+export type CollectionActionIntent =
+  | 'archive' | 'star' | 'delete'
+  | 'enable' | 'disable' | 'pause' | 'resume'
+  | 'move' | 'add-to-folder' | 'complete' | 'start-progress'
+  | 'custom';
+
+export interface CollectionActionContext<T> {
+  selectedIds: string[];
+  selectedItems: T[];
+  clearSelection: () => void;
+}
+
+export interface CollectionAction<T> {
+  id: string;
+  intent?: CollectionActionIntent;
+  label?: string;
+  icon?: ReactNode;
+  /** Omit to use the intent default, supply a key to override, or false to remove it. */
+  shortcut?: string | false;
+  destructive?: boolean;
+  disabled?: boolean | ((context: CollectionActionContext<T>) => boolean);
+  pending?: boolean;
+  onRun: (context: CollectionActionContext<T>) => void | Promise<void>;
+}
+
+export interface ResolvedCollectionAction {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+  shortcut?: string;
+  destructive?: boolean;
+  disabled?: boolean;
+  pending?: boolean;
+  onRun: () => void | Promise<void>;
+}
+
+const ACTION_DEFAULTS: Record<Exclude<CollectionActionIntent, 'custom'>, { label: string; shortcut: string }> = {
+  archive: { label: 'Archive', shortcut: 'E' },
+  star: { label: 'Star', shortcut: 'S' },
+  delete: { label: 'Delete', shortcut: '#' },
+  enable: { label: 'Enable', shortcut: 'E' },
+  disable: { label: 'Disable', shortcut: 'D' },
+  pause: { label: 'Pause', shortcut: 'P' },
+  resume: { label: 'Resume', shortcut: 'R' },
+  move: { label: 'Move', shortcut: 'M' },
+  'add-to-folder': { label: 'Add to folder', shortcut: 'F' },
+  complete: { label: 'Mark complete', shortcut: 'C' },
+  'start-progress': { label: 'Start progress', shortcut: 'P' },
+};
+
+export function collectionActionDefaults(intent: CollectionActionIntent | undefined): {
+  label?: string;
+  shortcut?: string;
+} {
+  if (!intent || intent === 'custom') return {};
+  return ACTION_DEFAULTS[intent];
+}