@notis_ai/cli 0.2.4 → 0.2.6

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

@@ -0,0 +1,121 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord, QueryFilter } from '../runtime';
+
+interface QueryDatabaseResult {
+  documents?: unknown[];
+  has_more?: boolean;
+  next_offset?: number | null;
+  message?: string;
+  error?: string;
+}
+
+export interface UseDocumentsOptions {
+  filter?: QueryFilter;
+  pageSize?: number;
+  offset?: number;
+  /** Fetch every page, starting at offset, instead of returning only one page. */
+  fetchAll?: boolean;
+  enabled?: boolean;
+}
+
+export interface UseDocumentsResult {
+  documents: DocumentRecord[];
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/**
+ * Query a Notis database and get normalized `DocumentRecord`s.
+ *
+ * ```tsx
+ * const { documents, loading, refetch } = useDocuments('notes', {
+ *   filter: { filters: [{ property: 'Folder', operator: 'contains', type: 'relation', value: folderId }] },
+ *   pageSize: 250,
+ * });
+ * ```
+ */
+export function useDocuments(
+  databaseSlug: string,
+  options: UseDocumentsOptions = {},
+): UseDocumentsResult {
+  const runtime = useNotisRuntime();
+  const [documents, setDocuments] = useState<DocumentRecord[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const enabled = options.enabled !== false;
+  const filterKey = JSON.stringify(options.filter ?? null);
+
+  const refetch = useCallback(() => {
+    setFetchKey((key) => key + 1);
+  }, []);
+
+  useEffect(() => {
+    if (!runtime || !enabled) {
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+
+    const filter = filterKey === 'null' ? null : (JSON.parse(filterKey) as QueryFilter);
+
+    const fetchDocuments = async (): Promise<unknown[]> => {
+      const allDocuments: unknown[] = [];
+      let offset = options.offset ?? 0;
+
+      while (true) {
+        const result = await runtime.callTool<QueryDatabaseResult>('LOCAL_NOTIS_DATABASE_QUERY', {
+          database_slug: databaseSlug,
+          query: {
+            ...(filter ?? {}),
+            ...(options.pageSize !== undefined ? { page_size: options.pageSize } : {}),
+          },
+          ...(offset > 0 ? { offset } : {}),
+        });
+        const message = result.error ?? result.message;
+        if (!result.documents && message) {
+          throw new Error(message);
+        }
+        allDocuments.push(...(result.documents ?? []));
+        if (!options.fetchAll || !result.has_more) return allDocuments;
+
+        const nextOffset = result.next_offset;
+        if (typeof nextOffset !== 'number' || nextOffset <= offset) {
+          throw new Error('Database query returned an invalid pagination offset');
+        }
+        offset = nextOffset;
+      }
+    };
+
+    fetchDocuments()
+      .then((result) => {
+        if (cancelled) return;
+        setDocuments(
+          result
+            .map(normalizeDocumentRecord)
+            .filter((document) => document.id),
+        );
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime, databaseSlug, enabled, fetchKey, filterKey, options.fetchAll, options.offset, options.pageSize]);
+
+  return { documents, loading, error, refetch };
+}

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

@@ -59,6 +59,19 @@ export interface MultiSelectController<T> {
 
   /** Spread on each selectable row so drag-select can find them. */
   getRowProps: (id: string) => { [ROW_ATTR]: string };
+  /**
+   * Spread on each selectable row/card — bundles `getRowProps` (the drag-select
+   * attribute) with the Cmd/Ctrl+click `onMouseDown` handler in one spread.
+   */
+  getItemProps: (id: string) => {
+    [ROW_ATTR]: string;
+    onMouseDown: (event: ReactMouseEvent) => void;
+  };
+  /** Spread onto `<MultiSelectCheckbox {...getCheckboxProps(id)} />`. */
+  getCheckboxProps: (id: string) => {
+    isSelected: boolean;
+    onClick: (event: ReactMouseEvent) => void;
+  };
   /** Spread on the list container — owns the drag-select mousedown/move/up + click-empty-to-clear. */
   getContainerProps: () => {
     ref: (node: HTMLElement | null) => void;
@@ -68,7 +81,12 @@ export interface MultiSelectController<T> {
   };
 }
 
-function isEditableTarget(target: EventTarget | null): boolean {
+function isEditableEvent(event: Event): boolean {
+  // Notis apps mount inside a Shadow DOM, so a document-level listener sees
+  // `event.target` retargeted to the shadow host rather than the real focused
+  // element. `composedPath()[0]` pierces the shadow boundary to the actual
+  // target, so typing in an app input doesn't trigger selection shortcuts.
+  const target = event.composedPath?.()[0] ?? event.target;
   if (!(target instanceof HTMLElement)) return false;
   if (target.isContentEditable) return true;
   const tag = target.tagName;
@@ -218,6 +236,22 @@ export function useMultiSelect<T>(opts: UseMultiSelectOptions<T>): MultiSelectCo
     [],
   );
 
+  const getItemProps = useCallback(
+    (id: string) => ({
+      [ROW_ATTR]: id,
+      onMouseDown: onRowMouseDown(id),
+    }),
+    [onRowMouseDown],
+  );
+
+  const getCheckboxProps = useCallback(
+    (id: string) => ({
+      isSelected: selectedIdsRef.current.has(id),
+      onClick: onCheckboxClick(id),
+    }),
+    [onCheckboxClick],
+  );
+
   // ---------------------------------------------------------------------------
   // Drag-select
   // ---------------------------------------------------------------------------
@@ -386,7 +420,7 @@ export function useMultiSelect<T>(opts: UseMultiSelectOptions<T>): MultiSelectCo
     if (!bindKeyboardShortcuts) return;
 
     const handleKeyDown = (event: KeyboardEvent) => {
-      if (isEditableTarget(event.target)) return;
+      if (isEditableEvent(event)) return;
 
       // Esc — clear selection
       if (event.key === 'Escape') {
@@ -498,6 +532,8 @@ export function useMultiSelect<T>(opts: UseMultiSelectOptions<T>): MultiSelectCo
     onCheckboxClick,
     onRowMouseDown,
     getRowProps,
+    getItemProps,
+    getCheckboxProps,
     getContainerProps,
   };
 }

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

@@ -2,39 +2,84 @@
 
 import { useCallback, useState } from 'react';
 import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
 import type { DocumentRecord } from '../runtime';
 
-interface UpsertArgs {
-  databaseSlug: string;
+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 UseUpsertDocumentResult {
-  upsert: (args: UpsertArgs) => Promise<DocumentRecord>;
+interface UpsertToolResult {
+  status?: string;
+  document?: unknown;
+  message?: string;
+  error?: string;
+}
+
+export interface UseUpsertDocumentResult {
+  upsert: (args: UpsertDocumentArgs) => Promise<DocumentRecord>;
   loading: boolean;
   error: Error | null;
 }
 
-export function useUpsertDocument(): UseUpsertDocumentResult {
+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: UpsertArgs): Promise<DocumentRecord> => {
+    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.upsertDocument(args);
-        return result.document;
+        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);
@@ -43,7 +88,7 @@ export function useUpsertDocument(): UseUpsertDocumentResult {
         setLoading(false);
       }
     },
-    [runtime],
+    [runtime, databaseSlug],
   );
 
   return { upsert, loading, error };

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

@@ -11,8 +11,14 @@ export { NotisProvider, useNotisRuntime } from './provider';
 
 // Hooks
 export { useNotis } from './hooks/useNotis';
-export { useDatabase } from './hooks/useDatabase';
+export { useDocuments } from './hooks/useDocuments';
+export type { UseDocumentsOptions, UseDocumentsResult } from './hooks/useDocuments';
+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';
@@ -21,6 +27,24 @@ export { useTopBarSearch } from './hooks/useTopBarSearch';
 export { useBackend } from './hooks/useBackend';
 export { useMultiSelect } from './hooks/useMultiSelect';
 
+// Documents & markdown
+export { Markdown } from './components/Markdown';
+export type { MarkdownProps } from './components/Markdown';
+export { DocumentEditor } from './components/DocumentEditor';
+export {
+  asRecord,
+  blockNoteToPlainText,
+  extractRichText,
+  getDocumentPreview,
+  getRelationIds,
+  isPresentString,
+  markdownToPlainText,
+  normalizeDatabaseProperty,
+  normalizeDocumentRecord,
+  normalizePropertyValue,
+  optionalString,
+} from './documents';
+
 // Multi-select components
 export { MultiSelectActionBar } from './components/MultiSelectActionBar';
 export { MultiSelectCheckbox } from './components/MultiSelectCheckbox';
@@ -44,9 +68,14 @@ export type {
   CollectionItemDetail,
   DatabaseDescriptor,
   DatabaseProperty,
+  DatabasePropertyOption,
+  DatabasePropertyType,
+  DocumentContentType,
   DocumentRecord,
+  NotisDocumentEditorProps,
   NotisRuntime,
   NotisRuntimeContext,
+  NotisRuntimeUI,
   QueryFilter,
   RouteDescriptor,
   ToolDescriptor,

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

@@ -7,15 +7,39 @@
  * (useTool, useNotis, etc.) which read from the NotisProvider context.
  */
 
+import type { ComponentType } from 'react';
+
 // ---------------------------------------------------------------------------
 // Database types
 // ---------------------------------------------------------------------------
 
+export type DatabasePropertyType =
+  | 'title'
+  | 'rich_text'
+  | 'text'
+  | 'number'
+  | 'checkbox'
+  | 'date'
+  | 'select'
+  | 'multi_select'
+  | 'status'
+  | 'relation'
+  | 'formula'
+  | 'files';
+
+export interface DatabasePropertyOption {
+  id?: string | null;
+  name: string;
+  color?: string | null;
+  order?: number;
+}
+
 export interface DatabaseProperty {
+  id?: string | null;
   name: string;
-  type: 'title' | 'rich_text' | 'number' | 'checkbox' | 'date' | 'select' | 'multi_select' | 'status' | 'relation' | 'formula' | 'files';
-  description?: string;
-  options?: Array<{ name: string; id?: string }>;
+  type: DatabasePropertyType;
+  description?: string | null;
+  options?: DatabasePropertyOption[];
 }
 
 export interface DatabaseDescriptor {
@@ -26,13 +50,25 @@ export interface DatabaseDescriptor {
   properties: DatabaseProperty[];
 }
 
+/**
+ * A document's content is typed. `markdown` documents carry rich text as
+ * BlockNote JSON (canonical) with a derived markdown projection; `file`
+ * documents carry an uploaded file whose format is in `fileType`
+ * (pdf, xlsx, pptx, ...). Future content types (canvas, ...) extend this
+ * union without changing the component contracts.
+ */
+export type DocumentContentType = 'markdown' | 'file';
+
 export interface DocumentRecord {
   id: string;
   title: string;
   properties: Record<string, unknown>;
+  url?: string | null;
   icon?: string | null;
   cover?: string | null;
   databaseSlug?: string;
+  contentType?: DocumentContentType | null;
+  fileType?: string | null;
   contentBlocknote?: Array<Record<string, unknown>> | null;
   contentMarkdown?: string | null;
   plainText?: string | null;
@@ -99,6 +135,7 @@ export interface QueryFilter {
   filters?: Array<{
     property: string;
     operator: string;
+    type?: string;
     value: unknown;
   }>;
   sorts?: Array<{
@@ -110,6 +147,41 @@ export interface QueryFilter {
 
 export interface NotisRuntimeContext {
   collectionItem?: CollectionItemDetail | null;
+  /**
+   * Set when the app is being rendered by the screenshot harness (`notis apps
+   * screenshot`) for the named listing scenario. Lets apps and SDK components
+   * hide dev-only chrome from listing images.
+   */
+  screenshotScenario?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Host-provided UI
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for the host-provided document editor. The host implementation
+ * dispatches on the document's content type (markdown -> rich text editor,
+ * file -> matching viewer/editor), so this contract stays stable as new
+ * content types ship.
+ */
+export interface NotisDocumentEditorProps {
+  documentId: string;
+  /** 'full' renders icon/title/cover above the content; 'body' renders content only. */
+  variant?: 'full' | 'body';
+  readOnly?: boolean;
+  className?: string;
+  onDirtyChange?: (dirty: boolean) => void;
+  onSavingChange?: (saving: boolean) => void;
+}
+
+/**
+ * Components the host (portal) injects through the runtime. Apps consume them
+ * via the SDK wrappers (e.g. `DocumentEditor`), which fall back gracefully
+ * when a host component is unavailable (standalone dev harness, snapshots).
+ */
+export interface NotisRuntimeUI {
+  DocumentEditor?: ComponentType<NotisDocumentEditorProps>;
 }
 
 // ---------------------------------------------------------------------------
@@ -121,6 +193,7 @@ export interface NotisRuntime {
   route: RouteDescriptor;
   databases: DatabaseDescriptor[];
   context: NotisRuntimeContext;
+  ui?: NotisRuntimeUI;
 
   navigate?: (payload: { kind: string; [key: string]: unknown }) => void;
 
@@ -139,20 +212,6 @@ export interface NotisRuntime {
   listTools(): Promise<ToolDescriptor[]>;
   callTool<TResult = unknown>(name: string, args?: Record<string, unknown>): Promise<TResult>;
 
-  queryDatabase(args: {
-    databaseSlug: string;
-    query?: QueryFilter;
-    offset?: number;
-  }): Promise<{ documents: DocumentRecord[] }>;
-
-  upsertDocument(args: {
-    databaseSlug: string;
-    documentId?: string;
-    title?: string;
-    properties?: Record<string, unknown>;
-    contentBlocknote?: Array<Record<string, unknown>> | null;
-  }): Promise<{ status: string; document: DocumentRecord }>;
-
   request(path: string, options?: {
     method?: string;
     headers?: Record<string, string>;

package/template/packages/sdk/src/styles.css

@@ -36,3 +36,151 @@
     @apply p-5 md:p-6;
   }
 }
+
+/*
+ * Markdown value-type rendering (see the `Markdown` component). Plain CSS on
+ * theme variables so it works inside the portal shadow root and the dev
+ * harness without depending on the app's Tailwind content scan.
+ */
+.notis-markdown {
+  font-size: 14px;
+  line-height: 1.65;
+  color: hsl(var(--foreground));
+  overflow-wrap: break-word;
+}
+
+.notis-markdown--sm {
+  font-size: 13px;
+  line-height: 1.55;
+}
+
+.notis-markdown > :first-child {
+  margin-top: 0;
+}
+
+.notis-markdown > :last-child {
+  margin-bottom: 0;
+}
+
+.notis-markdown p {
+  margin: 0.625em 0;
+}
+
+.notis-markdown h1,
+.notis-markdown h2,
+.notis-markdown h3,
+.notis-markdown h4,
+.notis-markdown h5,
+.notis-markdown h6 {
+  margin: 1.25em 0 0.5em;
+  font-weight: 650;
+  letter-spacing: -0.01em;
+  line-height: 1.3;
+  color: hsl(var(--foreground));
+}
+
+.notis-markdown h1 { font-size: 1.5em; }
+.notis-markdown h2 { font-size: 1.25em; }
+.notis-markdown h3 { font-size: 1.1em; }
+.notis-markdown h4,
+.notis-markdown h5,
+.notis-markdown h6 { font-size: 1em; }
+
+.notis-markdown ul,
+.notis-markdown ol {
+  margin: 0.625em 0;
+  padding-left: 1.5em;
+}
+
+.notis-markdown ul { list-style-type: disc; }
+.notis-markdown ol { list-style-type: decimal; }
+
+.notis-markdown li {
+  margin: 0.25em 0;
+}
+
+.notis-markdown li > ul,
+.notis-markdown li > ol {
+  margin: 0.25em 0;
+}
+
+.notis-markdown ul.contains-task-list {
+  list-style: none;
+  padding-left: 0.375em;
+}
+
+.notis-markdown li.task-list-item input[type='checkbox'] {
+  margin-right: 0.5em;
+  accent-color: hsl(var(--primary));
+}
+
+.notis-markdown blockquote {
+  margin: 0.75em 0;
+  padding: 0.125em 0 0.125em 0.875em;
+  border-left: 3px solid hsl(var(--border));
+  color: hsl(var(--muted-foreground));
+}
+
+.notis-markdown a {
+  color: hsl(var(--primary));
+  text-decoration: underline;
+  text-decoration-color: hsl(var(--primary) / 0.35);
+  text-underline-offset: 2px;
+}
+
+.notis-markdown a:hover {
+  text-decoration-color: hsl(var(--primary));
+}
+
+.notis-markdown code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.875em;
+  padding: 0.125em 0.375em;
+  border-radius: 0.25rem;
+  background: hsl(var(--muted));
+  color: hsl(var(--foreground));
+}
+
+.notis-markdown pre {
+  margin: 0.75em 0;
+  padding: 0.75em 1em;
+  border-radius: 0.5rem;
+  background: hsl(var(--muted));
+  overflow-x: auto;
+}
+
+.notis-markdown pre code {
+  padding: 0;
+  background: transparent;
+  font-size: 0.875em;
+}
+
+.notis-markdown hr {
+  margin: 1.25em 0;
+  border: 0;
+  border-top: 1px solid hsl(var(--border));
+}
+
+.notis-markdown img {
+  max-width: 100%;
+  border-radius: 0.5rem;
+}
+
+.notis-markdown table {
+  margin: 0.75em 0;
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.95em;
+}
+
+.notis-markdown th,
+.notis-markdown td {
+  padding: 0.375em 0.75em;
+  border: 1px solid hsl(var(--border));
+  text-align: left;
+}
+
+.notis-markdown th {
+  background: hsl(var(--muted));
+  font-weight: 600;
+}