lemma-sdk 0.2.31 → 0.2.32

package/README.md

@@ -74,9 +74,9 @@ import {
 | Area | Hooks | Stability | Use when |
 | --- | --- | --- | --- |
 | Auth | `AuthGuard`, `useAuth`, `useCurrentUser`, `usePodAccess` | Stable | Gate an app, read signed-in user state, or request pod access. |
-| Tables | `useTables`, `useTable`, `useRecords`, `useRecord`, `useJoinedRecords`, `useRelatedRecords`, `useReverseRelatedRecords` | Stable | Build custom table browsers, details views, related-record views, and relational reads. |
-| Record mutations | `useCreateRecord`, `useUpdateRecord`, `useDeleteRecord`, `useBulkRecords` | Stable | Create, update, delete, or bulk-delete rows from headless UI. |
-| Record forms | `useRecordSchema`, `useRecordForm`, `useForeignKeyOptions`, `useSchemaForm` | Stable | Render schema-driven forms, enum fields, and foreign-key selectors. |
+| Tables | `useTables`, `useTable`, `useRecords`, `useRecord`, `useJoinedRecords`, `useRelatedRecords`, `useReverseRelatedRecords`, `useReferencingRecords` | Stable | Build custom table browsers, details views, related-record views, and relational reads. |
+| Record mutations | `useCreateRecord`, `useUpdateRecord`, `useDeleteRecord`, `useBulkRecords` | Stable | Create, update, delete, or bulk-delete rows from headless UI. Function-backed mutations via `createVia`/`updateVia` options. |
+| Record forms | `useRecordSchema`, `useRecordForm`, `useForeignKeyOptions`, `useSchemaForm` | Stable | Render schema-driven forms, enum fields, and foreign-key selectors. `useRecordForm` supports `submitVia: "function"`, `visibleFields`, `hiddenFields`. |
 | Assistant | `useConversations`, `useConversation`, `useConversationMessages`, `useAssistantRun`, `useAssistantSession`, `useAssistantRuntime`, `useAssistantController` | Stable except controller/runtime | Build custom chat, conversation lists, streaming output, and final-output views. |
 | Agents | `useAgentRun`, `useAgentRuns`, `useAgentInputSchema`, `useTaskSession` | Stable except raw session | Start agent tasks, submit follow-up input, read task history, and inspect input/output schemas. |
 | Workflows | `useWorkflowStart`, `useWorkflowRun`, `useWorkflowRuns`, `useWorkflowResume` | Stable | Start, poll, resume, cancel, retry, and inspect workflow runs. |
@@ -86,6 +86,8 @@ import {
 
 ### Common Hook Shapes
 
+For business-facing examples and a decision guide mapping "I want to..." to the right hook, see [docs/hooks-guide.md](docs/hooks-guide.md).
+
 List hooks generally expose:
 
 - `items` named for the resource, such as `records`, `runs`, or `members`

package/dist/react/index.d.ts

@@ -45,11 +45,13 @@ export type { UseDeleteRecordOptions, UseDeleteRecordResult } from "./useDeleteR
 export { useBulkRecords } from "./useBulkRecords.js";
 export type { UseBulkRecordsOptions, UseBulkRecordsResult } from "./useBulkRecords.js";
 export { useJoinedRecords } from "./useJoinedRecords.js";
-export type { UseJoinedRecordsOptions, UseJoinedRecordsResult } from "./useJoinedRecords.js";
+export type { JoinedRecordsShorthandJoin, UseJoinedRecordsOptions, UseJoinedRecordsResult, } from "./useJoinedRecords.js";
 export { useRelatedRecords } from "./useRelatedRecords.js";
 export type { RelatedRecordsColumn, RelatedRecordsInclude, RelatedRecordsResolvedInclude, UseRelatedRecordsOptions, UseRelatedRecordsResult, } from "./useRelatedRecords.js";
 export { useReverseRelatedRecords } from "./useReverseRelatedRecords.js";
 export type { ReverseRelatedRecordsColumn, ReverseRelatedRelation, ReverseRelationSelector, UseReverseRelatedRecordsOptions, UseReverseRelatedRecordsResult, } from "./useReverseRelatedRecords.js";
+export { useReferencingRecords } from "./useReferencingRecords.js";
+export type { ReferencingRecordsColumn, UseReferencingRecordsOptions, UseReferencingRecordsResult, } from "./useReferencingRecords.js";
 export { useForeignKeyOptions } from "./useForeignKeyOptions.js";
 export type { ForeignKeyOption, UseForeignKeyOptionsOptions, UseForeignKeyOptionsResult, } from "./useForeignKeyOptions.js";
 export { useRecordSchema } from "./useRecordSchema.js";

package/dist/react/index.js

@@ -24,6 +24,7 @@ export { useBulkRecords } from "./useBulkRecords.js";
 export { useJoinedRecords } from "./useJoinedRecords.js";
 export { useRelatedRecords } from "./useRelatedRecords.js";
 export { useReverseRelatedRecords } from "./useReverseRelatedRecords.js";
+export { useReferencingRecords } from "./useReferencingRecords.js";
 export { useForeignKeyOptions } from "./useForeignKeyOptions.js";
 export { useRecordSchema } from "./useRecordSchema.js";
 export { useRecordForm } from "./useRecordForm.js";

package/dist/react/useCreateRecord.d.ts

@@ -1,11 +1,41 @@
 import type { LemmaClient } from "../client.js";
-import type { RecordResponse } from "../types.js";
+import type { FunctionRun, RecordResponse } from "../types.js";
+/**
+ * React hook for creating a single record. Manages loading/error state and
+ * exposes a `create` function you can call from event handlers.
+ *
+ * Supports two modes:
+ * - `"direct"` (default): calls `records.create` directly.
+ * - `"function"`: calls `functions.runs.create`, routing the create through
+ *   a pod function that may enforce business logic.
+ *
+ * @example Direct create
+ * ```tsx
+ * const { create, isSubmitting } = useCreateRecord({ client, tableName: "comments" });
+ * await create({ body: "Hello", issue_id: "123" });
+ * ```
+ *
+ * @example Function-backed create
+ * ```tsx
+ * const { create, isSubmitting } = useCreateRecord({
+ *   client,
+ *   tableName: "issues",
+ *   createVia: "function",
+ *   createFunctionName: "create-issue",
+ * });
+ * await create({ title: "Bug", team_id: "team_1" });
+ * ```
+ */
 export interface UseCreateRecordOptions {
     client: LemmaClient;
     podId?: string;
     tableName: string;
     enabled?: boolean;
-    onSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    /** How the record is created. `"direct"` calls `records.create`. `"function"` calls `functions.runs.create`. */
+    createVia?: "direct" | "function";
+    /** Function name to run when `createVia` is `"function"`. Falls back to `tableName` if omitted. */
+    createFunctionName?: string;
+    onSuccess?: (record: Record<string, unknown>, response: RecordResponse | FunctionRun) => void;
     onError?: (error: unknown) => void;
 }
 export interface UseCreateRecordResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
@@ -15,4 +45,4 @@ export interface UseCreateRecordResult<TRecord extends Record<string, unknown> =
     create: (data: Record<string, unknown>) => Promise<TRecord | null>;
     reset: () => void;
 }
-export declare function useCreateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, enabled, onSuccess, onError, }: UseCreateRecordOptions): UseCreateRecordResult<TRecord>;
+export declare function useCreateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, enabled, createVia, createFunctionName, onSuccess, onError, }: UseCreateRecordOptions): UseCreateRecordResult<TRecord>;

package/dist/react/useCreateRecord.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { normalizeError, resolvePodClient } from "./utils.js";
-export function useCreateRecord({ client, podId, tableName, enabled = true, onSuccess, onError, }) {
+export function useCreateRecord({ client, podId, tableName, enabled = true, createVia = "direct", createFunctionName, onSuccess, onError, }) {
     const [createdRecord, setCreatedRecord] = useState(null);
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [error, setError] = useState(null);
@@ -18,6 +18,16 @@ export function useCreateRecord({ client, podId, tableName, enabled = true, onSu
         setError(null);
         try {
             const scopedClient = resolvePodClient(client, podId);
+            if (createVia === "function") {
+                const functionName = createFunctionName ?? trimmedTableName;
+                const run = await scopedClient.functions.runs.create(functionName, { input: data });
+                const nextRecord = (run.output_data ?? { id: run.id, ...data });
+                setCreatedRecord(nextRecord);
+                if (nextRecord) {
+                    onSuccessRef.current?.(nextRecord, run);
+                }
+                return nextRecord;
+            }
             const response = await scopedClient.records.create(trimmedTableName, data);
             const nextRecord = (response.data ?? null);
             setCreatedRecord(nextRecord);
@@ -35,7 +45,7 @@ export function useCreateRecord({ client, podId, tableName, enabled = true, onSu
         finally {
             setIsSubmitting(false);
         }
-    }, [client, isEnabled, podId, trimmedTableName]);
+    }, [client, createFunctionName, createVia, isEnabled, podId, trimmedTableName]);
     const reset = useCallback(() => {
         setCreatedRecord(null);
         setError(null);

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;

package/dist/react/useRecordForm.js

@@ -3,7 +3,7 @@ import { buildRecordFormValues, buildRecordPayload, } from "../record-form.js";
 import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
 import { useRecordSchema, } from "./useRecordSchema.js";
 const EMPTY_VALUES = {};
-export function useRecordForm({ client, podId, tableName, recordId = null, initialValues = EMPTY_VALUES, mode = "auto", enabled = true, autoLoad = true, onSubmitSuccess, onError, }) {
+export function useRecordForm({ client, podId, tableName, recordId = null, initialValues = EMPTY_VALUES, mode = "auto", enabled = true, autoLoad = true, visibleFields, hiddenFields, submitVia = "direct", submitFunctionName, submitFunctionInput, onSubmitSuccess, onError, }) {
     const schema = useRecordSchema({
         client,
         podId,
@@ -11,6 +11,30 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         enabled,
         autoLoad,
     });
+    const visibleSet = useMemo(() => visibleFields ? new Set(visibleFields) : null, [visibleFields]);
+    const hiddenSet = useMemo(() => hiddenFields ? new Set(hiddenFields) : null, [hiddenFields]);
+    const filteredFields = useMemo(() => {
+        if (!visibleSet && !hiddenSet)
+            return schema.fields;
+        return schema.fields.filter((field) => {
+            if (visibleSet)
+                return visibleSet.has(field.name);
+            if (hiddenSet)
+                return !hiddenSet.has(field.name);
+            return true;
+        });
+    }, [hiddenSet, schema.fields, visibleSet]);
+    const filteredEditableFields = useMemo(() => {
+        if (!visibleSet && !hiddenSet)
+            return schema.editableFields;
+        return schema.editableFields.filter((field) => {
+            if (visibleSet)
+                return visibleSet.has(field.name);
+            if (hiddenSet)
+                return !hiddenSet.has(field.name);
+            return true;
+        });
+    }, [hiddenSet, schema.editableFields, visibleSet]);
     const [record, setRecord] = useState(null);
     const [values, setValuesState] = useState({});
     const [baselineValues, setBaselineValues] = useState({});
@@ -147,6 +171,19 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         setRecordError(null);
         try {
             const scopedClient = resolvePodClient(client, podId);
+            if (submitVia === "function") {
+                const functionName = submitFunctionName ?? tableName;
+                const functionInput = submitFunctionInput ? submitFunctionInput(payload.data) : payload.data;
+                const run = await scopedClient.functions.runs.create(functionName, { input: functionInput });
+                const nextRecord = run.output_data ?? { id: run.id, ...functionInput };
+                setRecord(nextRecord);
+                hydrateValues({
+                    ...(nextRecord ?? {}),
+                    ...stableInitialValues,
+                });
+                onSubmitSuccess?.(nextRecord ?? {}, run);
+                return nextRecord;
+            }
             const response = resolvedMode === "update" && recordId
                 ? await scopedClient.records.update(tableName, recordId, payload.data)
                 : await scopedClient.records.create(tableName, payload.data);
@@ -168,14 +205,14 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         finally {
             setIsSubmitting(false);
         }
-    }, [client, hydrateValues, mode, onError, onSubmitSuccess, podId, recordId, schemaTable, stableInitialValues, tableName, values]);
+    }, [client, hydrateValues, mode, onError, onSubmitSuccess, podId, recordId, schemaTable, stableInitialValues, submitFunctionInput, submitFunctionName, submitVia, tableName, values]);
     const isDirty = useMemo(() => {
         return stringifyComparable(values) !== stringifyComparable(baselineValues);
     }, [baselineValues, values]);
     return useMemo(() => ({
         table: schema.table,
-        fields: schema.fields,
-        editableFields: schema.editableFields,
+        fields: filteredFields,
+        editableFields: filteredEditableFields,
         defaults: schema.defaults,
         values,
         baselineValues,
@@ -197,6 +234,8 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
     }), [
         baselineValues,
         fieldErrors,
+        filteredEditableFields,
+        filteredFields,
         isDirty,
         isLoadingRecord,
         isSubmitting,
@@ -206,9 +245,7 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         refreshRecord,
         reset,
         schema.defaults,
-        schema.editableFields,
         schema.error,
-        schema.fields,
         schema.isLoading,
         schema.refresh,
         schema.table,

package/dist/react/useReferencingRecords.d.ts

@@ -0,0 +1,66 @@
+import type { LemmaClient } from "../client.js";
+import type { Table } from "../types.js";
+/**
+ * React hook for fetching records from a referencing table that point back
+ * to a specific record via a foreign key.
+ *
+ * Unlike `useReverseRelatedRecords` which starts from a parent table and
+ * discovers what references it, this hook starts from the child table and
+ * says "give me all rows in this table where this FK column equals this ID."
+ *
+ * @example Fetch all comments for an issue
+ * ```tsx
+ * const { records, isLoading } = useReferencingRecords({
+ *   client,
+ *   table: "comments",
+ *   foreignKey: "issue_id",
+ *   recordId: "issue_123",
+ * });
+ * ```
+ *
+ * @example Fetch history entries
+ * ```tsx
+ * const { records, columns, isLoading } = useReferencingRecords({
+ *   client,
+ *   table: "issue_history",
+ *   foreignKey: "issue_id",
+ *   recordId: selectedIssueId,
+ *   sortBy: "created_at",
+ *   order: "desc",
+ * });
+ * ```
+ */
+export interface ReferencingRecordsColumn {
+    key: string;
+    field: string;
+    label: string;
+}
+export interface UseReferencingRecordsOptions {
+    client: LemmaClient;
+    podId?: string;
+    /** The referencing (child) table, e.g. "comments". */
+    table: string;
+    /** The foreign-key column in the referencing table, e.g. "issue_id". */
+    foreignKey: string;
+    /** The record ID value to match against the foreign-key column. */
+    recordId?: string | null;
+    /** Fields to select. Auto-resolved from the table schema if omitted. */
+    fields?: string[];
+    limit?: number;
+    offset?: number;
+    sortBy?: string;
+    order?: "asc" | "desc" | string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseReferencingRecordsResult<TRow extends Record<string, unknown> = Record<string, unknown>> {
+    referencedTable: Table | null;
+    columns: ReferencingRecordsColumn[];
+    records: TRow[];
+    total: number;
+    nextPageToken: string | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<TRow[]>;
+}
+export declare function useReferencingRecords<TRow extends Record<string, unknown> = Record<string, unknown>>({ client, podId, table, foreignKey, recordId, fields, limit, offset, sortBy, order, enabled, autoLoad, }: UseReferencingRecordsOptions): UseReferencingRecordsResult<TRow>;

package/dist/react/useReferencingRecords.js

@@ -0,0 +1,159 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
+function sentenceCase(value) {
+    return value
+        .replace(/[_\.]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+function pickDefaultFields(table, foreignKey) {
+    const names = table.columns
+        .map((column) => column.name)
+        .filter((name) => name !== "created_at" && name !== "updated_at");
+    const prioritized = ["id", "name", "title", "label", "status", foreignKey];
+    const next = [];
+    prioritized.forEach((name) => {
+        if (names.includes(name) && !next.includes(name)) {
+            next.push(name);
+        }
+    });
+    names.forEach((name) => {
+        if (!next.includes(name)) {
+            next.push(name);
+        }
+    });
+    return next.slice(0, 6);
+}
+export function useReferencingRecords({ client, podId, table, foreignKey, recordId = null, fields, limit = 20, offset, sortBy, order, enabled = true, autoLoad = true, }) {
+    const [referencedTable, setReferencedTable] = useState(null);
+    const [columns, setColumns] = useState([]);
+    const [records, setRecords] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [nextPageToken, setNextPageToken] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedTable = table.trim();
+    const trimmedRecordId = typeof recordId === "string" ? recordId.trim() : "";
+    const fieldsKey = stringifyComparable(fields);
+    const stableFields = useMemo(() => fields, [fieldsKey]);
+    const isEnabled = enabled && trimmedTable.length > 0 && trimmedRecordId.length > 0;
+    const refresh = useCallback(async (signal) => {
+        if (!isEnabled) {
+            setReferencedTable(null);
+            setColumns([]);
+            setRecords([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const tableResponse = await scopedClient.tables.get(trimmedTable);
+            if (signal?.aborted)
+                return [];
+            setReferencedTable(tableResponse);
+            const resolvedFields = (stableFields?.length ? stableFields : pickDefaultFields(tableResponse, foreignKey))
+                .filter((field, index, allFields) => field.trim().length > 0 && allFields.indexOf(field) === index);
+            const response = await scopedClient.records.list(trimmedTable, {
+                filters: [{
+                        field: foreignKey,
+                        op: "eq",
+                        value: trimmedRecordId,
+                    }],
+                limit,
+                offset,
+                sortBy,
+                order,
+            });
+            if (signal?.aborted)
+                return [];
+            const nextRecords = (response.items ?? []);
+            setColumns(resolvedFields.map((field) => ({
+                key: field,
+                field,
+                label: sentenceCase(field),
+            })));
+            setRecords(nextRecords);
+            setTotal(response.total ?? nextRecords.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return nextRecords;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(refreshError, "Failed to load referencing records.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [
+        client,
+        foreignKey,
+        isEnabled,
+        limit,
+        offset,
+        order,
+        podId,
+        sortBy,
+        stableFields,
+        trimmedRecordId,
+        trimmedTable,
+    ]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setReferencedTable(null);
+            setColumns([]);
+            setRecords([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh(controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load referencing records."), "Failed to load referencing records."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        referencedTable,
+        columns,
+        records,
+        total,
+        nextPageToken,
+        isLoading,
+        error,
+        refresh,
+    }), [
+        columns,
+        error,
+        isLoading,
+        nextPageToken,
+        records,
+        refresh,
+        referencedTable,
+        total,
+    ]);
+}

package/dist/react/useRelatedRecords.d.ts

@@ -1,5 +1,22 @@
 import type { LemmaClient } from "../client.js";
 import type { Table } from "../types.js";
+/**
+ * React hook for fetching base-table rows with their FK-related data
+ * joined in a single query. You specify which FK columns to include and
+ * the hook auto-resolves the referenced table and join columns.
+ *
+ * The result has nested objects: `{ id, name, team: { id, name } }`.
+ *
+ * @example Issues with their team
+ * ```tsx
+ * const { records, isLoading } = useRelatedRecords({
+ *   client,
+ *   tableName: "issues",
+ *   include: [{ foreignKey: "team_id" }],
+ * });
+ * // records[0] = { id: "1", title: "Bug", team: { id: "t1", name: "Eng" } }
+ * ```
+ */
 export interface RelatedRecordsInclude {
     foreignKey: string;
     as?: string;

package/dist/react/useReverseRelatedRecords.d.ts

@@ -1,5 +1,26 @@
 import type { LemmaClient } from "../client.js";
 import type { Table } from "../types.js";
+/**
+ * React hook for finding records in *other* tables that reference a given
+ * record. Starts from the parent table, discovers all tables with FK
+ * columns pointing back to it, and fetches the referencing rows.
+ *
+ * For the simpler case where you already know the referencing table and
+ * FK column, prefer `useReferencingRecords` — it has a more intuitive API.
+ *
+ * @example All comments and history entries for an issue
+ * ```tsx
+ * const { relations, records, isLoading } = useReverseRelatedRecords({
+ *   client,
+ *   tableName: "issues",
+ *   recordId: "issue_123",
+ *   relation: { tableName: "comments", foreignKey: "issue_id" },
+ * });
+ * ```
+ *
+ * @see useReferencingRecords — flipped-perspective alias for the common
+ *   "show me all rows in table X where FK = Y" pattern.
+ */
 export interface ReverseRelationSelector {
     tableName: string;
     foreignKey: string;

package/dist/react/useUpdateRecord.d.ts

@@ -1,12 +1,43 @@
 import type { LemmaClient } from "../client.js";
-import type { RecordResponse } from "../types.js";
+import type { FunctionRun, RecordResponse } from "../types.js";
+/**
+ * React hook for updating a single record. Manages loading/error state and
+ * exposes an `update` function you can call from event handlers.
+ *
+ * Supports two modes:
+ * - `"direct"` (default): calls `records.update` directly.
+ * - `"function"`: calls `functions.runs.create`, routing the update through
+ *   a pod function (e.g. for status transitions that log history).
+ *
+ * @example Direct update
+ * ```tsx
+ * const { update, isSubmitting } = useUpdateRecord({ client, tableName: "issues", recordId: "123" });
+ * await update({ status: "closed" });
+ * ```
+ *
+ * @example Function-backed update
+ * ```tsx
+ * const { update, isSubmitting } = useUpdateRecord({
+ *   client,
+ *   tableName: "issues",
+ *   recordId: "123",
+ *   updateVia: "function",
+ *   updateFunctionName: "update-issue-status",
+ * });
+ * await update({ status: "in_progress" });
+ * ```
+ */
 export interface UseUpdateRecordOptions {
     client: LemmaClient;
     podId?: string;
     tableName: string;
     recordId?: string | null;
     enabled?: boolean;
-    onSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    /** How the record is updated. `"direct"` calls `records.update`. `"function"` calls `functions.runs.create`. */
+    updateVia?: "direct" | "function";
+    /** Function name to run when `updateVia` is `"function"`. Falls back to `tableName` if omitted. */
+    updateFunctionName?: string;
+    onSuccess?: (record: Record<string, unknown>, response: RecordResponse | FunctionRun) => void;
     onError?: (error: unknown) => void;
 }
 export interface UseUpdateRecordResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
@@ -18,4 +49,4 @@ export interface UseUpdateRecordResult<TRecord extends Record<string, unknown> =
     }) => Promise<TRecord | null>;
     reset: () => void;
 }
-export declare function useUpdateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, recordId, enabled, onSuccess, onError, }: UseUpdateRecordOptions): UseUpdateRecordResult<TRecord>;
+export declare function useUpdateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, recordId, enabled, updateVia, updateFunctionName, onSuccess, onError, }: UseUpdateRecordOptions): UseUpdateRecordResult<TRecord>;

package/dist/react/useUpdateRecord.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { normalizeError, resolvePodClient } from "./utils.js";
-export function useUpdateRecord({ client, podId, tableName, recordId = null, enabled = true, onSuccess, onError, }) {
+export function useUpdateRecord({ client, podId, tableName, recordId = null, enabled = true, updateVia = "direct", updateFunctionName, onSuccess, onError, }) {
     const [updatedRecord, setUpdatedRecord] = useState(null);
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [error, setError] = useState(null);
@@ -22,6 +22,17 @@ export function useUpdateRecord({ client, podId, tableName, recordId = null, ena
         setError(null);
         try {
             const scopedClient = resolvePodClient(client, podId);
+            if (updateVia === "function") {
+                const functionName = updateFunctionName ?? trimmedTableName;
+                const input = { ...data, id: nextRecordId, record_id: nextRecordId };
+                const run = await scopedClient.functions.runs.create(functionName, { input });
+                const nextRecord = (run.output_data ?? { id: nextRecordId, ...data });
+                setUpdatedRecord(nextRecord);
+                if (nextRecord) {
+                    onSuccessRef.current?.(nextRecord, run);
+                }
+                return nextRecord;
+            }
             const response = await scopedClient.records.update(trimmedTableName, nextRecordId, data);
             const nextRecord = (response.data ?? null);
             setUpdatedRecord(nextRecord);
@@ -39,7 +50,7 @@ export function useUpdateRecord({ client, podId, tableName, recordId = null, ena
         finally {
             setIsSubmitting(false);
         }
-    }, [client, isEnabled, podId, trimmedRecordId, trimmedTableName]);
+    }, [client, isEnabled, podId, trimmedRecordId, trimmedTableName, updateFunctionName, updateVia]);
     const reset = useCallback(() => {
         setUpdatedRecord(null);
         setError(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemma-sdk",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "description": "Official TypeScript SDK for Lemma pod-scoped APIs",
   "type": "module",
   "main": "dist/index.js",