@xnetjs/react 0.0.2 → 0.0.3

package/dist/database.d.ts

@@ -0,0 +1,383 @@
+import { ColumnDefinition, ViewConfig, DatabaseDocumentModel, FilterGroup, SortConfig, NodeQueryMaterializedViewOptions, CellValue, Schema, DatabaseSchemaMetadata } from '@xnetjs/data';
+export { ColumnConfig, ColumnDefinition, ColumnType, ViewConfig, ViewType } from '@xnetjs/data';
+import * as Y from 'yjs';
+
+/**
+ * useDatabaseDoc - Hook for database column and view operations
+ *
+ * Provides reactive access to the database's Y.Doc structure:
+ * - Column definitions (CRDT-ordered)
+ * - View configurations
+ * - Column and view CRUD operations
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   columns,
+ *   views,
+ *   createColumn,
+ *   updateColumn,
+ *   deleteColumn,
+ *   reorderColumn,
+ *   createView,
+ *   updateView,
+ *   deleteView
+ * } = useDatabaseDoc(databaseId)
+ * ```
+ */
+
+interface UseDatabaseDocResult {
+    /** All column definitions (CRDT-ordered) */
+    columns: ColumnDefinition[];
+    /** All view configurations */
+    views: ViewConfig[];
+    /** Y.Doc for direct access (if needed) */
+    doc: Y.Doc | null;
+    /** Which document storage model currently backs this database */
+    storageMode: DatabaseDocumentModel;
+    /** Whether this doc can still be explicitly materialized into the canonical model */
+    /** Whether the doc is loading */
+    loading: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Create a new column */
+    createColumn: (definition: Omit<ColumnDefinition, 'id'>) => string | null;
+    /** Update a column's properties */
+    updateColumn: (columnId: string, updates: Partial<Omit<ColumnDefinition, 'id'>>) => void;
+    /** Delete a column */
+    deleteColumn: (columnId: string) => void;
+    /** Reorder a column to a new position */
+    reorderColumn: (columnId: string, newIndex: number) => void;
+    /** Duplicate a column */
+    duplicateColumn: (columnId: string, newName?: string) => string | null;
+    /** Get a single column by ID */
+    getColumn: (columnId: string) => ColumnDefinition | null;
+    /** Create a new view */
+    createView: (config: Omit<ViewConfig, 'id'>) => string | null;
+    /** Update a view's properties */
+    updateView: (viewId: string, updates: Partial<Omit<ViewConfig, 'id'>>) => void;
+    /** Delete a view */
+    deleteView: (viewId: string) => void;
+    /** Duplicate a view */
+    duplicateView: (viewId: string, newName?: string) => string | null;
+    /** Get a single view by ID */
+    getView: (viewId: string) => ViewConfig | null;
+}
+/**
+ * Hook for database column and view operations.
+ *
+ * Provides reactive access to the database's Y.Doc structure with
+ * CRDT-based column ordering and real-time schema sync.
+ */
+declare function useDatabaseDoc(databaseId: string): UseDatabaseDocResult;
+
+/**
+ * useDatabase - Hook for database row operations with pagination
+ *
+ * Provides:
+ * - Paginated row queries
+ * - Row CRUD operations
+ * - Integration with useDatabaseDoc for columns/views
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   rows,
+ *   columns,
+ *   views,
+ *   loading,
+ *   hasMore,
+ *   loadMore,
+ *   createRow,
+ *   updateRow,
+ *   deleteRow
+ * } = useDatabase(databaseId)
+ * ```
+ */
+
+interface UseDatabaseOptions {
+    /** Active view ID (uses first view if not specified) */
+    view?: string;
+    /** Override view filters */
+    filters?: FilterGroup;
+    /** Override view sorts */
+    sorts?: SortConfig[];
+    /** Search query (full-text search) - not yet implemented */
+    search?: string;
+    /** Page size (default: 50) */
+    pageSize?: number;
+    /**
+     * Opt into SQLite materialized row lists for stable persisted views.
+     * Pass true to derive a database/view cache key, or pass explicit options.
+     */
+    materializedView?: boolean | string | NodeQueryMaterializedViewOptions;
+}
+interface DatabaseRow {
+    /** Row ID */
+    id: string;
+    /** Sort key for ordering */
+    sortKey: string;
+    /** Cell values keyed by column ID */
+    cells: Record<string, CellValue>;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Creator DID */
+    createdBy: string;
+}
+interface UseDatabaseResult {
+    /** Column definitions */
+    columns: ColumnDefinition[];
+    /** View configurations */
+    views: ViewConfig[];
+    /** Loaded rows */
+    rows: DatabaseRow[];
+    /** Total row count */
+    total: number;
+    /** Whether more rows are available */
+    hasMore: boolean;
+    /** Load more rows */
+    loadMore: () => Promise<void>;
+    /** Active view configuration */
+    activeView: ViewConfig | null;
+    /** Set the active view */
+    setActiveView: (viewId: string) => void;
+    /** Create a new row */
+    createRow: (values?: Record<string, CellValue>) => Promise<string>;
+    /** Update a row's cell values */
+    updateRow: (rowId: string, values: Record<string, CellValue>) => Promise<void>;
+    /** Delete a row */
+    deleteRow: (rowId: string) => Promise<void>;
+    /** Reorder a row */
+    reorderRow: (rowId: string, before?: string, after?: string) => Promise<void>;
+    /** Delete multiple rows */
+    deleteRows: (rowIds: string[]) => Promise<void>;
+    /** Whether initially loading */
+    loading: boolean;
+    /** Whether loading more rows */
+    loadingMore: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Refetch all rows */
+    refetch: () => Promise<void>;
+}
+/**
+ * Hook for database row operations with pagination.
+ */
+declare function useDatabase(databaseId: string, options?: UseDatabaseOptions): UseDatabaseResult;
+
+/**
+ * useDatabaseRow - Hook for single row operations with optimistic updates
+ *
+ * Provides:
+ * - Row data with cell values
+ * - Y.Doc for rich text cells
+ * - Optimistic updates
+ * - Delete operation
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   row,
+ *   doc,
+ *   update,
+ *   delete: deleteRow,
+ *   loading
+ * } = useDatabaseRow(rowId)
+ * ```
+ */
+
+interface DatabaseRowData {
+    /** Row ID */
+    id: string;
+    /** Database ID this row belongs to */
+    databaseId: string;
+    /** Sort key for ordering */
+    sortKey: string;
+    /** Cell values keyed by column ID */
+    cells: Record<string, CellValue>;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Creator DID */
+    createdBy: string;
+}
+interface UseDatabaseRowResult {
+    /** Row data */
+    row: DatabaseRowData | null;
+    /** Y.Doc for rich text cells (if any) */
+    doc: Y.Doc | null;
+    /** Update cell values (with optimistic UI) */
+    update: (values: Record<string, CellValue>) => Promise<void>;
+    /** Delete this row */
+    delete: () => Promise<void>;
+    /** Loading state */
+    loading: boolean;
+    /** Error state */
+    error: Error | null;
+}
+/**
+ * Hook for single row operations with optimistic updates.
+ */
+declare function useDatabaseRow(rowId: string): UseDatabaseRowResult;
+
+/**
+ * useCell - Hook for individual cell editing with debounced saves
+ *
+ * Provides:
+ * - Cell value with optimistic updates
+ * - Debounced persistence
+ * - Clear operation
+ *
+ * @example
+ * ```tsx
+ * const { value, setValue, saving } = useCell<string>(rowId, 'title')
+ *
+ * return (
+ *   <Input
+ *     value={value ?? ''}
+ *     onChange={(e) => setValue(e.target.value)}
+ *     className={saving ? 'opacity-50' : ''}
+ *   />
+ * )
+ * ```
+ */
+
+interface UseCellResult<T extends CellValue = CellValue> {
+    /** Cell value */
+    value: T | null;
+    /** Update cell value (debounced save) */
+    setValue: (value: T | null) => void;
+    /** Clear cell value */
+    clear: () => void;
+    /** Whether cell is being saved */
+    saving: boolean;
+    /** Error from last save */
+    error: Error | null;
+}
+interface UseCellOptions {
+    /** Debounce delay in ms (default: 300) */
+    debounce?: number;
+}
+/**
+ * Hook for individual cell editing with debounced saves.
+ */
+declare function useCell<T extends CellValue = CellValue>(rowId: string, columnId: string, options?: UseCellOptions): UseCellResult<T>;
+
+/**
+ * useRelatedRows - Hook for loading related row data for relation columns
+ *
+ * Fetches the row data for a list of row IDs, typically from a relation column.
+ *
+ * @example
+ * ```tsx
+ * const { rows, loading, error } = useRelatedRows(['row1', 'row2'])
+ * // rows contains the full row data for display
+ * ```
+ */
+
+interface UseRelatedRowsResult {
+    /** Loaded row data */
+    rows: DatabaseRow[];
+    /** Whether rows are loading */
+    loading: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+}
+/**
+ * Hook for loading related row data.
+ *
+ * @param rowIds - Array of row IDs to load
+ * @returns Object containing rows, loading state, and error
+ */
+declare function useRelatedRows(rowIds: string[]): UseRelatedRowsResult;
+
+/**
+ * useReverseRelations - Hook for finding rows that link TO a given row
+ *
+ * Finds all rows in other databases that have relation columns pointing
+ * to the specified row. Useful for showing "backlinks" or "linked from" sections.
+ *
+ * @example
+ * ```tsx
+ * const { relations, loading, error } = useReverseRelations(taskId, tasksDatabaseId)
+ * // relations contains all rows that link to this task
+ * ```
+ */
+
+interface ReverseRelation {
+    /** The row that links to the target row */
+    row: DatabaseRow;
+    /** The relation column through which it links */
+    column: ColumnDefinition;
+    /** ID of the source database */
+    sourceDatabaseId: string;
+    /** Title of the source database */
+    sourceDatabaseTitle: string;
+}
+interface UseReverseRelationsResult {
+    /** Found reverse relations */
+    relations: ReverseRelation[];
+    /** Whether relations are loading */
+    loading: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Refetch the relations */
+    refetch: () => void;
+}
+/**
+ * Hook for finding reverse relations (backlinks) to a row.
+ *
+ * @param rowId - The row ID to find links to
+ * @param databaseId - The database containing the row
+ * @returns Object containing relations, loading state, and error
+ */
+declare function useReverseRelations(rowId: string, databaseId: string): UseReverseRelationsResult;
+
+/**
+ * useDatabaseSchema - Hook for database-defined schema access
+ *
+ * Provides reactive access to a database's schema metadata and properties.
+ * Works with the schema registry to resolve database-defined schemas.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   schema,
+ *   metadata,
+ *   loading,
+ *   error
+ * } = useDatabaseSchema(databaseId)
+ *
+ * // Access schema version
+ * console.log(metadata?.version) // "1.2.0"
+ *
+ * // Access schema properties
+ * schema?.properties.forEach(prop => console.log(prop.name))
+ * ```
+ */
+
+interface UseDatabaseSchemaResult {
+    /** The resolved Schema object, or null if not loaded */
+    schema: Schema | null;
+    /** The schema metadata from the database's Y.Doc */
+    metadata: DatabaseSchemaMetadata | null;
+    /** The schema IRI for this database */
+    schemaIRI: string | null;
+    /** Whether the schema is loading */
+    loading: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Force refresh the schema */
+    refresh: () => void;
+}
+/**
+ * Hook for accessing a database's schema.
+ *
+ * Loads the database's Y.Doc, extracts schema metadata and columns,
+ * builds the Schema object, and registers it with the schema registry.
+ *
+ * @param databaseId - The database node ID
+ * @returns The schema, metadata, and loading state
+ */
+declare function useDatabaseSchema(databaseId: string | undefined): UseDatabaseSchemaResult;
+
+export { type DatabaseRow, type DatabaseRowData, type ReverseRelation, type UseCellOptions, type UseCellResult, type UseDatabaseDocResult, type UseDatabaseOptions, type UseDatabaseResult, type UseDatabaseRowResult, type UseDatabaseSchemaResult, type UseRelatedRowsResult, type UseReverseRelationsResult, useCell, useDatabase, useDatabaseDoc, useDatabaseRow, useDatabaseSchema, useRelatedRows, useReverseRelations };

package/dist/database.js

@@ -0,0 +1,19 @@
+import {
+  useCell,
+  useDatabase,
+  useDatabaseDoc,
+  useDatabaseRow,
+  useDatabaseSchema,
+  useRelatedRows,
+  useReverseRelations
+} from "./chunk-KSHTDZ2V.js";
+import "./chunk-IHTMVTTE.js";
+export {
+  useCell,
+  useDatabase,
+  useDatabaseDoc,
+  useDatabaseRow,
+  useDatabaseSchema,
+  useRelatedRows,
+  useReverseRelations
+};