lemma-sdk 0.2.31 → 0.2.33

package/dist/react/useFilePreview.js

@@ -0,0 +1,76 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useFilePreview({ client, podId, path = null, enabled = true, autoLoad = true, mode = "rendered", artifact = "document.md", }) {
+    const [content, setContent] = useState(null);
+    const [blob, setBlob] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedPath = typeof path === "string" ? path.trim() : "";
+    const isEnabled = enabled && trimmedPath.length > 0;
+    const refresh = useCallback(async (overrides = {}, signal) => {
+        const nextPath = typeof overrides.path === "string" ? overrides.path.trim() : trimmedPath;
+        const nextMode = overrides.mode ?? mode;
+        const nextArtifact = overrides.artifact ?? artifact;
+        if (!enabled || nextPath.length === 0) {
+            setContent(null);
+            setBlob(null);
+            setError(null);
+            setIsLoading(false);
+            return null;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            if (nextMode === "artifact") {
+                const nextBlob = await scopedClient.files.converted.download(nextPath, nextArtifact);
+                const text = await nextBlob.text();
+                if (signal?.aborted)
+                    return null;
+                setBlob(nextBlob);
+                setContent(text);
+                return text;
+            }
+            const rendered = await scopedClient.files.converted.render(nextPath);
+            const text = typeof rendered === "string" ? rendered : String(rendered ?? "");
+            if (signal?.aborted)
+                return null;
+            setBlob(null);
+            setContent(text);
+            return text;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return null;
+            setError(normalizeError(refreshError, "Failed to load file preview."));
+            setContent(null);
+            setBlob(null);
+            return null;
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [artifact, client, enabled, mode, podId, trimmedPath]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setContent(null);
+            setBlob(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        void refresh({}, controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        content,
+        blob,
+        isLoading,
+        error,
+        refresh,
+    }), [blob, content, error, isLoading, refresh]);
+}

package/dist/react/useFileSearch.d.ts

@@ -0,0 +1,26 @@
+import type { LemmaClient } from "../client.js";
+import type { FileSearchResponse, FileSearchResultSchema, SearchMethod } from "../types.js";
+export interface UseFileSearchOptions {
+    client: LemmaClient;
+    podId?: string;
+    query?: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    minQueryLength?: number;
+    limit?: number;
+    searchMethod?: SearchMethod;
+}
+export interface UseFileSearchResult {
+    response: FileSearchResponse | null;
+    results: FileSearchResultSchema[];
+    totalResults: number;
+    isLoading: boolean;
+    error: Error | null;
+    search: (overrides?: {
+        query?: string;
+        limit?: number;
+        searchMethod?: SearchMethod;
+    }) => Promise<FileSearchResponse | null>;
+    reset: () => void;
+}
+export declare function useFileSearch({ client, podId, query, enabled, autoLoad, minQueryLength, limit, searchMethod, }: UseFileSearchOptions): UseFileSearchResult;

package/dist/react/useFileSearch.js

@@ -0,0 +1,64 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useFileSearch({ client, podId, query = "", enabled = true, autoLoad = true, minQueryLength = 1, limit = 10, searchMethod, }) {
+    const [response, setResponse] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedQuery = query.trim();
+    const reset = useCallback(() => {
+        setResponse(null);
+        setError(null);
+        setIsLoading(false);
+    }, []);
+    const search = useCallback(async (overrides = {}, signal) => {
+        const nextQuery = (overrides.query ?? trimmedQuery).trim();
+        if (!enabled || nextQuery.length < minQueryLength) {
+            reset();
+            return null;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextResponse = await scopedClient.files.search(nextQuery, {
+                limit: overrides.limit ?? limit,
+                searchMethod: overrides.searchMethod ?? searchMethod,
+            });
+            if (signal?.aborted)
+                return null;
+            setResponse(nextResponse);
+            return nextResponse;
+        }
+        catch (searchError) {
+            if (signal?.aborted)
+                return null;
+            setError(normalizeError(searchError, "Failed to search files."));
+            setResponse(null);
+            return null;
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, enabled, limit, minQueryLength, podId, reset, searchMethod, trimmedQuery]);
+    useEffect(() => {
+        if (!enabled || !autoLoad)
+            return;
+        if (trimmedQuery.length < minQueryLength) {
+            reset();
+            return;
+        }
+        const controller = new AbortController();
+        void search({}, controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, enabled, minQueryLength, reset, search, trimmedQuery]);
+    return useMemo(() => ({
+        response,
+        results: response?.results ?? [],
+        totalResults: response?.total_results ?? 0,
+        isLoading,
+        error,
+        search,
+        reset,
+    }), [error, isLoading, reset, response, search]);
+}

package/dist/react/useFileTree.d.ts

@@ -0,0 +1,21 @@
+import type { LemmaClient } from "../client.js";
+import type { DirectoryTreeNode, DirectoryTreeResponse } from "../types.js";
+export interface UseFileTreeOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    rootPath?: string;
+    filesPerDirectory?: number;
+}
+export interface UseFileTreeResult {
+    tree: DirectoryTreeNode | null;
+    response: DirectoryTreeResponse | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        rootPath?: string;
+        filesPerDirectory?: number;
+    }) => Promise<DirectoryTreeResponse | null>;
+}
+export declare function useFileTree({ client, podId, enabled, autoLoad, rootPath, filesPerDirectory, }: UseFileTreeOptions): UseFileTreeResult;

package/dist/react/useFileTree.js

@@ -0,0 +1,59 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useFileTree({ client, podId, enabled = true, autoLoad = true, rootPath = "/", filesPerDirectory = 3, }) {
+    const [response, setResponse] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async (overrides = {}, signal) => {
+        if (!enabled) {
+            setResponse(null);
+            setError(null);
+            setIsLoading(false);
+            return null;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextResponse = await scopedClient.files.tree({
+                rootPath: overrides.rootPath ?? rootPath,
+                filesPerDirectory: overrides.filesPerDirectory ?? filesPerDirectory,
+            });
+            if (signal?.aborted)
+                return null;
+            setResponse(nextResponse);
+            return nextResponse;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return null;
+            setError(normalizeError(refreshError, "Failed to load file tree."));
+            setResponse(null);
+            return null;
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, enabled, filesPerDirectory, podId, rootPath]);
+    useEffect(() => {
+        if (!enabled) {
+            setResponse(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        void refresh({}, controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, enabled, refresh]);
+    return useMemo(() => ({
+        tree: response?.tree ?? null,
+        response,
+        isLoading,
+        error,
+        refresh,
+    }), [error, isLoading, refresh, response]);
+}

package/dist/react/useFiles.d.ts

@@ -0,0 +1,29 @@
+import type { LemmaClient } from "../client.js";
+import type { FileResponse } from "../types.js";
+export interface UseFilesOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    limit?: number;
+    pageToken?: string;
+    directoryPath?: string;
+    parentId?: string;
+}
+export interface UseFilesResult {
+    files: FileResponse[];
+    nextPageToken: string | null;
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        limit?: number;
+        pageToken?: string;
+        directoryPath?: string;
+        parentId?: string;
+    }) => Promise<FileResponse[]>;
+    loadMore: (overrides?: {
+        limit?: number;
+    }) => Promise<FileResponse[]>;
+}
+export declare function useFiles({ client, podId, enabled, autoLoad, limit, pageToken, directoryPath, parentId, }: UseFilesOptions): UseFilesResult;

package/dist/react/useFiles.js

@@ -0,0 +1,90 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useFiles({ client, podId, enabled = true, autoLoad = true, limit = 100, pageToken, directoryPath = "/", parentId, }) {
+    const [files, setFiles] = useState([]);
+    const [nextPageToken, setNextPageToken] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [isLoadingMore, setIsLoadingMore] = useState(false);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async (overrides = {}, signal) => {
+        if (!enabled)
+            return [];
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.files.list({
+                limit: overrides.limit ?? limit,
+                pageToken: overrides.pageToken ?? pageToken,
+                directoryPath: overrides.directoryPath ?? directoryPath,
+                parentId: overrides.parentId ?? parentId,
+            });
+            if (signal?.aborted)
+                return [];
+            const nextFiles = response.items ?? [];
+            setFiles(nextFiles);
+            setNextPageToken(response.next_page_token ?? null);
+            return nextFiles;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return [];
+            setError(normalizeError(refreshError, "Failed to load files."));
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, directoryPath, enabled, limit, pageToken, parentId, podId]);
+    const loadMore = useCallback(async (overrides = {}) => {
+        if (!enabled || !nextPageToken || isLoading || isLoadingMore)
+            return [];
+        setIsLoadingMore(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.files.list({
+                limit: overrides.limit ?? limit,
+                pageToken: nextPageToken,
+                directoryPath,
+                parentId,
+            });
+            const moreFiles = response.items ?? [];
+            setFiles((previous) => [...previous, ...moreFiles]);
+            setNextPageToken(response.next_page_token ?? null);
+            return moreFiles;
+        }
+        catch (loadError) {
+            setError(normalizeError(loadError, "Failed to load more files."));
+            return [];
+        }
+        finally {
+            setIsLoadingMore(false);
+        }
+    }, [client, directoryPath, enabled, isLoading, isLoadingMore, limit, nextPageToken, parentId, podId]);
+    useEffect(() => {
+        if (!enabled) {
+            setFiles([]);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            setIsLoadingMore(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        void refresh({}, controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, enabled, refresh]);
+    return useMemo(() => ({
+        files,
+        nextPageToken,
+        isLoading,
+        isLoadingMore,
+        error,
+        refresh,
+        loadMore,
+    }), [error, files, isLoading, isLoadingMore, loadMore, nextPageToken, refresh]);
+}

package/dist/react/useForeignKeyOptions.d.ts

@@ -1,6 +1,24 @@
 import type { LemmaClient } from "../client.js";
 import { type ForeignKeyReference } from "../datastore-query.js";
 import type { ColumnSchema, Table } from "../types.js";
+/**
+ * React hook that resolves a foreign-key column into dropdown options.
+ * Reads the FK metadata from the table schema, fetches records from the
+ * referenced table, and returns `{ value, label, record }` options ready
+ * for `<Select>` components.
+ *
+ * Auto-detects the best label field (name > title > label > email > slug).
+ *
+ * @example
+ * ```tsx
+ * const { options, isLoading } = useForeignKeyOptions({
+ *   client,
+ *   tableName: "issues",
+ *   columnName: "team_id",
+ * });
+ * // options = [{ value: "team_1", label: "Engineering", record: {...} }, ...]
+ * ```
+ */
 export interface ForeignKeyOption {
     value: unknown;
     label: string;

package/dist/react/useFunctionRun.d.ts

@@ -1,5 +1,22 @@
 import type { FunctionRun } from "../types.js";
 import { type UseFunctionSessionOptions, type UseFunctionSessionResult } from "./useFunctionSession.js";
+/**
+ * React hook for running a pod function and tracking its output.
+ * Wraps `useFunctionSession` with a simpler API — call `start(input)`
+ * from an event handler, read `output` / `finalOutput`.
+ *
+ * @example Run a function on button click
+ * ```tsx
+ * const { start, output, isFinished, isPolling } = useFunctionRun({
+ *   client,
+ *   functionName: "update-issue-status",
+ * });
+ *
+ * <button onClick={() => start({ issue_id: "123", status: "closed" })}>
+ *   Close issue
+ * </button>
+ * ```
+ */
 export interface UseFunctionRunOptions extends UseFunctionSessionOptions {
 }
 export interface UseFunctionRunResult extends Omit<UseFunctionSessionResult, "start" | "listHistory"> {

package/dist/react/useJoinedRecords.d.ts

@@ -1,9 +1,64 @@
 import type { LemmaClient } from "../client.js";
 import { type JoinedRecordsQueryDefinition } from "../datastore-query.js";
+/**
+ * A simplified join descriptor. The hook auto-resolves the join condition
+ * from the foreign-key metadata on the base table's column named by `on`.
+ */
+export interface JoinedRecordsShorthandJoin {
+    /** The table to join into (e.g. "teams"). */
+    table: string;
+    /**
+     * The FK column on the base table that references the join table
+     * (e.g. "team_id"). The hook reads the FK metadata on this column
+     * to determine the join condition automatically.
+     */
+    on: string;
+    /** Optional alias for the joined table. Defaults to the table name. */
+    alias?: string;
+    /** Join type. Defaults to "left". */
+    type?: "inner" | "left" | "left outer" | "right" | "right outer" | "full" | "full outer";
+}
+/**
+ * React hook for cross-table join queries. Supports two API styles:
+ *
+ * 1. **Full query** via the `query` option — for complex joins with custom
+ *    select lists, filters, and expressions.
+ *
+ * 2. **Shorthand** via `baseTable` + `joins` — the hook auto-resolves the
+ *    join conditions from the schema's foreign-key metadata, so you don't
+ *    need to spell out the `on` condition manually.
+ *
+ * @example Full query (existing API)
+ * ```tsx
+ * const { records, isLoading } = useJoinedRecords({
+ *   client,
+ *   query: {
+ *     from: "issues",
+ *     joins: [{ table: "teams", on: { left: "issues.team_id", right: "teams.id" } }],
+ *   },
+ * });
+ * ```
+ *
+ * @example Shorthand with FK auto-resolution
+ * ```tsx
+ * const { records, isLoading } = useJoinedRecords({
+ *   client,
+ *   baseTable: "issues",
+ *   joins: [{ table: "teams", on: "team_id" }],
+ * });
+ * // The hook reads the FK metadata on issues.team_id to find that
+ * // it references teams.id, and builds the join automatically.
+ * ```
+ */
 export interface UseJoinedRecordsOptions {
     client: LemmaClient;
     podId?: string;
-    query: JoinedRecordsQueryDefinition;
+    /** Full join query definition. Mutually exclusive with `baseTable` + `joins`. */
+    query?: JoinedRecordsQueryDefinition;
+    /** Base table for shorthand mode. Mutually exclusive with `query`. */
+    baseTable?: string;
+    /** Shorthand join descriptors. Auto-resolves join conditions from FK metadata. */
+    joins?: JoinedRecordsShorthandJoin[];
     enabled?: boolean;
     autoLoad?: boolean;
 }
@@ -15,4 +70,4 @@ export interface UseJoinedRecordsResult<TRecord extends Record<string, unknown>
     error: Error | null;
     refresh: () => Promise<TRecord[]>;
 }
-export declare function useJoinedRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, query, enabled, autoLoad, }: UseJoinedRecordsOptions): UseJoinedRecordsResult<TRecord>;
+export declare function useJoinedRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, query, baseTable, joins: shorthandJoins, enabled, autoLoad, }: UseJoinedRecordsOptions): UseJoinedRecordsResult<TRecord>;

package/dist/react/useJoinedRecords.js

@@ -1,18 +1,51 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
-import { buildJoinedRecordsQuery } from "../datastore-query.js";
+import { buildJoinedRecordsQuery, parseForeignKeyReference, } from "../datastore-query.js";
 import { normalizeError, resolvePodId, stringifyComparable } from "./utils.js";
-export function useJoinedRecords({ client, podId, query, enabled = true, autoLoad = true, }) {
+async function buildShorthandQuery(client, podId, baseTableName, shorthandJoins) {
+    const resolvedPodId = resolvePodId(client, podId);
+    const scopedClient = resolvedPodId === client.podId ? client : client.withPod(resolvedPodId);
+    const baseTable = await scopedClient.tables.get(baseTableName.trim());
+    const joins = await Promise.all(shorthandJoins.map(async (entry) => {
+        const baseColumn = baseTable.columns.find((col) => col.name === entry.on) ?? null;
+        const reference = baseColumn?.foreign_key?.references
+            ? parseForeignKeyReference(baseColumn.foreign_key.references)
+            : null;
+        if (!baseColumn) {
+            throw new Error(`Column "${entry.on}" was not found on table "${baseTableName}".`);
+        }
+        if (!reference) {
+            throw new Error(`Column "${entry.on}" on "${baseTableName}" is not a foreign key. Use the full query API for non-FK joins.`);
+        }
+        return {
+            type: entry.type ?? "left",
+            table: entry.table,
+            alias: entry.alias,
+            on: {
+                left: { table: baseTableName, column: entry.on },
+                right: { table: entry.alias ?? entry.table, column: reference.column },
+            },
+        };
+    }));
+    return {
+        from: { table: baseTableName, alias: baseTableName },
+        joins,
+    };
+}
+export function useJoinedRecords({ client, podId, query, baseTable, joins: shorthandJoins, enabled = true, autoLoad = true, }) {
     const [records, setRecords] = useState([]);
     const [total, setTotal] = useState(0);
+    const [sql, setSql] = useState("");
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
+    const hasShorthand = !query && !!baseTable && !!shorthandJoins?.length;
     const queryKey = stringifyComparable(query);
+    const shorthandKey = stringifyComparable({ baseTable, shorthandJoins });
     const stableQuery = useMemo(() => query, [queryKey]);
-    const sql = useMemo(() => buildJoinedRecordsQuery(stableQuery), [stableQuery]);
     const refresh = useCallback(async (signal) => {
         if (!enabled) {
             setRecords([]);
             setTotal(0);
+            setSql("");
             setError(null);
             setIsLoading(false);
             return [];
@@ -22,7 +55,22 @@ export function useJoinedRecords({ client, podId, query, enabled = true, autoLoa
         try {
             const resolvedPodId = resolvePodId(client, podId);
             const scopedClient = resolvedPodId === client.podId ? client : client.withPod(resolvedPodId);
-            const response = await scopedClient.datastore.query(sql);
+            let resolvedQuery = stableQuery;
+            if (hasShorthand && baseTable && shorthandJoins) {
+                resolvedQuery = await buildShorthandQuery(client, podId, baseTable, shorthandJoins);
+            }
+            if (!resolvedQuery) {
+                setRecords([]);
+                setTotal(0);
+                setSql("");
+                setIsLoading(false);
+                return [];
+            }
+            if (signal?.aborted)
+                return [];
+            const nextSql = buildJoinedRecordsQuery(resolvedQuery);
+            setSql(nextSql);
+            const response = await scopedClient.datastore.query(nextSql);
             if (signal?.aborted)
                 return [];
             const nextRecords = (response.items ?? []);
@@ -41,11 +89,12 @@ export function useJoinedRecords({ client, podId, query, enabled = true, autoLoa
             if (!signal?.aborted)
                 setIsLoading(false);
         }
-    }, [client, enabled, podId, sql]);
+    }, [client, enabled, hasShorthand, baseTable, podId, shorthandJoins, stableQuery]);
     useEffect(() => {
         if (!enabled) {
             setRecords([]);
             setTotal(0);
+            setSql("");
             setError(null);
             setIsLoading(false);
             return;

package/dist/react/useRecord.d.ts

@@ -1,4 +1,20 @@
 import type { LemmaClient } from "../client.js";
+/**
+ * React hook for fetching a single record by ID. Unwraps `.data`
+ * automatically so `record` is the plain object, not the API envelope.
+ *
+ * Perfect for detail panels — pair with `useRecords` for the list.
+ *
+ * @example
+ * ```tsx
+ * const { record, isLoading } = useRecord({
+ *   client,
+ *   tableName: "issues",
+ *   recordId: selectedId,
+ * });
+ * // record is the issue object directly (or null)
+ * ```
+ */
 export interface UseRecordOptions {
     client: LemmaClient;
     podId?: string;

package/dist/react/useRecordForm.d.ts

@@ -1,7 +1,36 @@
 import type { LemmaClient } from "../client.js";
 import { type RecordSchemaField } from "../record-form.js";
-import type { RecordResponse } from "../types.js";
+import type { FunctionRun, RecordResponse } from "../types.js";
 import { type UseRecordSchemaResult } from "./useRecordSchema.js";
+/**
+ * React hook for schema-driven record forms with validation, dirty tracking,
+ * and create/update auto-detection.
+ *
+ * Supports two submit modes:
+ * - `"direct"` (default): persists via `records.create` / `records.update`.
+ * - `"function"`: persists via `functions.runs.create`, routing the form
+ *   payload through a pod function that may enforce business logic
+ *   (e.g. auto-generating identifiers, logging history).
+ *
+ * @example Direct create/update form
+ * ```tsx
+ * const form = useRecordForm({ client, tableName: "issues" });
+ * // form.fields → all schema fields, form.editableFields → user-fillable fields
+ * await form.submit(); // calls records.create or records.update
+ * ```
+ *
+ * @example Function-backed form
+ * ```tsx
+ * const form = useRecordForm({
+ *   client,
+ *   tableName: "issues",
+ *   submitVia: "function",
+ *   submitFunctionName: "create-issue",
+ *   hiddenFields: ["identifier", "created_at"],
+ * });
+ * await form.submit(); // calls functions.runs.create("create-issue", { input: payload })
+ * ```
+ */
 export interface UseRecordFormOptions {
     client: LemmaClient;
     podId?: string;
@@ -11,7 +40,17 @@ export interface UseRecordFormOptions {
     mode?: "auto" | "create" | "update";
     enabled?: boolean;
     autoLoad?: boolean;
-    onSubmitSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    /** Field names to include in `fields` and `editableFields`. Takes precedence over `hiddenFields`. */
+    visibleFields?: string[];
+    /** Field names to exclude from `fields` and `editableFields`. Ignored for any field also listed in `visibleFields`. */
+    hiddenFields?: string[];
+    /** How the form persists data. `"direct"` calls `records.create`/`records.update`. `"function"` calls `functions.runs.create`. */
+    submitVia?: "direct" | "function";
+    /** Function name to run when `submitVia` is `"function"`. Required when `submitVia` is `"function"`. */
+    submitFunctionName?: string;
+    /** Transforms the form payload before passing it as function input. Receives the validated payload, returns the function input object. */
+    submitFunctionInput?: (payload: Record<string, unknown>) => Record<string, unknown>;
+    onSubmitSuccess?: (record: Record<string, unknown>, response: RecordResponse | FunctionRun) => void;
     onError?: (error: unknown) => void;
 }
 export interface UseRecordFormResult {
@@ -39,4 +78,4 @@ export interface UseRecordFormResult {
         mode?: "create" | "update";
     }) => Promise<Record<string, unknown> | null>;
 }
-export declare function useRecordForm({ client, podId, tableName, recordId, initialValues, mode, enabled, autoLoad, onSubmitSuccess, onError, }: UseRecordFormOptions): UseRecordFormResult;
+export declare function useRecordForm({ client, podId, tableName, recordId, initialValues, mode, enabled, autoLoad, visibleFields, hiddenFields, submitVia, submitFunctionName, submitFunctionInput, onSubmitSuccess, onError, }: UseRecordFormOptions): UseRecordFormResult;