@opensaas/stack-ui 0.22.0 → 0.23.0

package/dist/components/SingletonView.js

@@ -0,0 +1,82 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Link from 'next/link.js';
+import { ItemFormClient } from './ItemFormClient.js';
+import { formatListName } from '../lib/utils.js';
+import { getDbKey, getUrlKey } from '@opensaas/stack-core';
+import { prepareItemForm } from '../lib/prepareItemForm.js';
+import { isOperationPotentiallyAllowed } from '../lib/operationAccess.js';
+/**
+ * Singleton editor — renders a single-record edit form for a list configured
+ * with `isSingleton: true`.
+ *
+ * Resolves the record via the singleton `get()` operation (which auto-creates
+ * the row with field defaults when absent, unless `autoCreate: false`), then
+ * reuses the same `ItemFormClient` + serialization path as `ItemForm` so the
+ * existing field rendering, validation, and `serverAction` save flow apply.
+ *
+ * A `null` from `get()` is ambiguous at the boundary — it means EITHER an
+ * `autoCreate: false` singleton with no row yet, OR that `query` access is
+ * denied (access-controlled reads return null/[] silently). We disambiguate
+ * using the list's operation-level access:
+ *
+ * - `query` denied  → friendly "no access" message (never an editable form).
+ * - `query` allowed + `create` allowed → a create-on-first-save form
+ *   (`ItemFormClient` in `mode="create"`); core assigns the singleton `id` and
+ *   enforces the single-record constraint on create.
+ * - `query` allowed + `create` denied → friendly "no record yet" message.
+ *
+ * An update-denied singleton still renders the edit form (the happy path), but
+ * the save fails gracefully: the server action's `update` access check returns
+ * a denied envelope, which `ItemFormClient` surfaces as an error.
+ *
+ * Server Component that fetches data and sets up actions.
+ */
+export async function SingletonView({ context, config, listKey, basePath = '/admin', serverAction, }) {
+    const listConfig = config.lists[listKey];
+    const urlKey = getUrlKey(listKey);
+    if (!listConfig) {
+        return (_jsx("div", { className: "p-8", children: _jsxs("div", { className: "bg-destructive/10 border border-destructive text-destructive rounded-lg p-6", children: [_jsx("h2", { className: "text-lg font-semibold mb-2", children: "List not found" }), _jsxs("p", { children: ["The list \"", listKey, "\" does not exist in your configuration."] })] }) }));
+    }
+    // Resolve the singleton record. `get()` auto-creates with field defaults when
+    // absent (the default), so a record is the common case. It returns null when
+    // either `autoCreate: false` with no row yet, OR `query` access is denied —
+    // these are indistinguishable here, so we disambiguate via access below.
+    let record = null;
+    try {
+        const delegate = context.db[getDbKey(listKey)];
+        if (delegate?.get) {
+            record = await delegate.get();
+        }
+    }
+    catch (error) {
+        console.error(`Failed to resolve singleton ${listKey}:`, error);
+    }
+    if (!record) {
+        // A null `get()` is ambiguous (autoCreate:false-empty vs query-denied).
+        // Evaluate operation access to choose the safe affordance.
+        const accessArgs = { session: context.session, context };
+        const canQuery = await isOperationPotentiallyAllowed(listConfig.access?.operation, 'query', accessArgs);
+        // Query denied → the session cannot read this singleton at all. Show a
+        // friendly message; never an editable/create form.
+        if (!canQuery) {
+            return (_jsxs("div", { className: "p-8 max-w-4xl", children: [_jsx("div", { className: "mb-8", children: _jsx("h1", { className: "text-3xl font-bold", children: formatListName(listKey) }) }), _jsx("div", { className: "bg-muted/50 border border-border rounded-lg p-6", children: _jsxs("p", { className: "text-muted-foreground", children: ["You don't have access to ", formatListName(listKey), "."] }) })] }));
+        }
+        // Query allowed but no row → an `autoCreate: false` singleton. Offer a
+        // create-on-first-save form only when `create` is actually permitted.
+        const canCreate = await isOperationPotentiallyAllowed(listConfig.access?.operation, 'create', accessArgs);
+        if (!canCreate) {
+            return (_jsxs("div", { className: "p-8 max-w-4xl", children: [_jsx("div", { className: "mb-8", children: _jsx("h1", { className: "text-3xl font-bold", children: formatListName(listKey) }) }), _jsx("div", { className: "bg-muted/50 border border-border rounded-lg p-6", children: _jsxs("p", { className: "text-muted-foreground", children: ["There is no ", formatListName(listKey), " record yet."] }) })] }));
+        }
+        // Create-on-first-save: render the form in create mode with an empty record.
+        // The save goes through the existing `serverAction` create path; core
+        // assigns the singleton `id` (always `1`) and enforces the single-record
+        // constraint, so the form sends only the user-entered field data.
+        const { serializableFields: createFields, initialData: createInitialData, relationshipData: createRelationshipData, } = await prepareItemForm(context, config, listConfig, {});
+        return (_jsxs("div", { className: "p-8 max-w-4xl", children: [_jsxs("div", { className: "mb-8", children: [_jsxs(Link, { href: basePath, className: "inline-flex items-center text-sm text-muted-foreground hover:text-foreground mb-4", children: [_jsx("svg", { className: "w-4 h-4 mr-1", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M15 19l-7-7 7-7" }) }), "Back to dashboard"] }), _jsxs("h1", { className: "text-3xl font-bold", children: ["Create ", formatListName(listKey)] })] }), _jsx("div", { className: "bg-card border border-border rounded-lg p-6", children: _jsx(ItemFormClient, { listKey: listKey, urlKey: urlKey, mode: "create", fields: createFields, initialData: createInitialData, basePath: basePath, serverAction: serverAction, relationshipData: createRelationshipData, canDelete: false }) })] }));
+    }
+    // Reuse the shared field-serialization + relationship-data logic so the
+    // singleton editor stays in lockstep with the regular item form.
+    const { serializableFields, initialData, relationshipData } = await prepareItemForm(context, config, listConfig, record);
+    const itemId = record.id;
+    return (_jsxs("div", { className: "p-8 max-w-4xl", children: [_jsxs("div", { className: "mb-8", children: [_jsxs(Link, { href: basePath, className: "inline-flex items-center text-sm text-muted-foreground hover:text-foreground mb-4", children: [_jsx("svg", { className: "w-4 h-4 mr-1", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M15 19l-7-7 7-7" }) }), "Back to dashboard"] }), _jsxs("h1", { className: "text-3xl font-bold", children: ["Edit ", formatListName(listKey)] })] }), _jsx("div", { className: "bg-card border border-border rounded-lg p-6", children: _jsx(ItemFormClient, { listKey: listKey, urlKey: urlKey, mode: "edit", fields: serializableFields, initialData: initialData, itemId: itemId, basePath: basePath, serverAction: serverAction, relationshipData: relationshipData, canDelete: false }) })] }));
+}

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { ListView } from './components/ListView.js';
 export { ListViewClient } from './components/ListViewClient.js';
 export { ItemForm } from './components/ItemForm.js';
 export { ItemFormClient } from './components/ItemFormClient.js';
+export { SingletonView } from './components/SingletonView.js';
 export { ConfirmDialog } from './components/ConfirmDialog.js';
 export { LoadingSpinner } from './components/LoadingSpinner.js';
 export { SkeletonLoader, TableSkeleton, FormSkeleton } from './components/SkeletonLoader.js';
@@ -18,6 +19,7 @@ export type { ListViewProps } from './components/ListView.js';
 export type { ListViewClientProps } from './components/ListViewClient.js';
 export type { ItemFormProps } from './components/ItemForm.js';
 export type { ItemFormClientProps } from './components/ItemFormClient.js';
+export type { SingletonViewProps } from './components/SingletonView.js';
 export type { ConfirmDialogProps } from './components/ConfirmDialog.js';
 export type { LoadingSpinnerProps } from './components/LoadingSpinner.js';
 export type { SkeletonLoaderProps } from './components/SkeletonLoader.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAC/D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAG5F,OAAO,EACL,SAAS,EACT,YAAY,EACZ,aAAa,EACb,WAAW,EACX,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,8BAA8B,CAAA;AAGrC,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC/D,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AACjE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACzE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACzE,YAAY,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AACvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACzE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAEzE,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,GACpB,MAAM,8BAA8B,CAAA;AAGrC,OAAO,EACL,cAAc,EACd,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,kCAAkC,CAAA;AAEzC,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,kCAAkC,CAAA;AAGzC,OAAO,EAAE,EAAE,EAAE,cAAc,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAG1F,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAC/D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAG5F,OAAO,EACL,SAAS,EACT,YAAY,EACZ,aAAa,EACb,WAAW,EACX,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,8BAA8B,CAAA;AAGrC,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC/D,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AACjE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACzE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACzE,YAAY,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AACvE,YAAY,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AACvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACzE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAEzE,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,GACpB,MAAM,8BAA8B,CAAA;AAGrC,OAAO,EACL,cAAc,EACd,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,kCAAkC,CAAA;AAEzC,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,kCAAkC,CAAA;AAGzC,OAAO,EAAE,EAAE,EAAE,cAAc,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAG1F,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -7,6 +7,7 @@ export { ListView } from './components/ListView.js';
 export { ListViewClient } from './components/ListViewClient.js';
 export { ItemForm } from './components/ItemForm.js';
 export { ItemFormClient } from './components/ItemFormClient.js';
+export { SingletonView } from './components/SingletonView.js';
 export { ConfirmDialog } from './components/ConfirmDialog.js';
 export { LoadingSpinner } from './components/LoadingSpinner.js';
 export { SkeletonLoader, TableSkeleton, FormSkeleton } from './components/SkeletonLoader.js';

package/dist/lib/operationAccess.d.ts

@@ -0,0 +1,34 @@
+import type { AccessContext, OperationAccess, Session } from '@opensaas/stack-core';
+/**
+ * The names of the operation-level access checks we evaluate in the UI.
+ */
+export type OperationAccessName = 'query' | 'create' | 'update' | 'delete';
+/**
+ * Evaluate a list's operation-level access control for the current session,
+ * coercing the result to a single "is this operation potentially permitted?"
+ * boolean.
+ *
+ * This mirrors how the core access engine treats a result:
+ * - `false`            → denied
+ * - `true`             → permitted
+ * - a filter object    → permitted, but scoped to matching rows
+ *
+ * Because the UI cannot know whether a returned filter would match the
+ * (possibly not-yet-created) singleton row, a filter is treated as "potentially
+ * permitted" — the actual operation still runs through the access engine, which
+ * re-applies the filter. This helper only decides which affordance to render.
+ *
+ * Access functions are user-defined and may throw (e.g. they assume a session
+ * shape that anonymous requests don't have). A throw is treated as **denied** —
+ * the safest outcome, so a misbehaving access function never exposes an
+ * editable/create form to a session that might not be allowed.
+ *
+ * No access function configured for the operation is also treated as denied,
+ * matching the core engine's deny-by-default (`checkAccess` returns `false`
+ * when `accessControl` is undefined).
+ */
+export declare function isOperationPotentiallyAllowed(access: OperationAccess | undefined, operation: OperationAccessName, args: {
+    session: Session | null;
+    context: AccessContext<unknown>;
+}): Promise<boolean>;
+//# sourceMappingURL=operationAccess.d.ts.map

package/dist/lib/operationAccess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operationAccess.d.ts","sourceRoot":"","sources":["../../src/lib/operationAccess.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAEnF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE1E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,eAAe,GAAG,SAAS,EACnC,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAAE,GACjE,OAAO,CAAC,OAAO,CAAC,CAiBlB"}

package/dist/lib/operationAccess.js

@@ -0,0 +1,43 @@
+/**
+ * Evaluate a list's operation-level access control for the current session,
+ * coercing the result to a single "is this operation potentially permitted?"
+ * boolean.
+ *
+ * This mirrors how the core access engine treats a result:
+ * - `false`            → denied
+ * - `true`             → permitted
+ * - a filter object    → permitted, but scoped to matching rows
+ *
+ * Because the UI cannot know whether a returned filter would match the
+ * (possibly not-yet-created) singleton row, a filter is treated as "potentially
+ * permitted" — the actual operation still runs through the access engine, which
+ * re-applies the filter. This helper only decides which affordance to render.
+ *
+ * Access functions are user-defined and may throw (e.g. they assume a session
+ * shape that anonymous requests don't have). A throw is treated as **denied** —
+ * the safest outcome, so a misbehaving access function never exposes an
+ * editable/create form to a session that might not be allowed.
+ *
+ * No access function configured for the operation is also treated as denied,
+ * matching the core engine's deny-by-default (`checkAccess` returns `false`
+ * when `accessControl` is undefined).
+ */
+export async function isOperationPotentiallyAllowed(access, operation, args) {
+    const accessControl = access?.[operation];
+    // Deny by default — no rule means no access (matches the core engine).
+    if (!accessControl)
+        return false;
+    try {
+        const result = await accessControl({
+            session: args.session,
+            // The access engine passes the same context through to the function.
+            context: args.context,
+        });
+        // `false` denies; `true` or a filter object both mean "potentially allowed".
+        return result !== false;
+    }
+    catch {
+        // A throwing access function is treated as denied — never widen access on error.
+        return false;
+    }
+}

package/dist/lib/prepareItemForm.d.ts

@@ -0,0 +1,35 @@
+import { type AccessContext, OpenSaasConfig } from '@opensaas/stack-core';
+import type { ListConfig } from '@opensaas/stack-core';
+import { type SerializableFieldConfig } from './serializeFieldConfig.js';
+/**
+ * Data prepared on the server for the client item form.
+ *
+ * Everything here is JSON-serializable and contains only what `ItemFormClient`
+ * needs to render — see the repo rule on minimal, serializable client props.
+ */
+export interface PreparedItemForm {
+    /** Field configs stripped of functions/non-serializable props. */
+    serializableFields: Record<string, SerializableFieldConfig>;
+    /** Initial form values (relationships reduced to ids, client transforms applied). */
+    initialData: Record<string, unknown>;
+    /** Relationship options keyed by field name. */
+    relationshipData: Record<string, Array<{
+        id: string;
+        label: string;
+    }>>;
+}
+/**
+ * Build the `include` object needed to hydrate relationship fields when
+ * fetching an item for editing.
+ */
+export declare function buildRelationshipInclude(listConfig: ListConfig<any>): Record<string, boolean>;
+/**
+ * Prepare the serializable props for `ItemFormClient` from an already-fetched
+ * record (or an empty object for create).
+ *
+ * This is shared by `ItemForm` (which fetches via `findUnique`) and
+ * `SingletonView` (which resolves via the singleton `get()`), so the
+ * relationship/serialization logic lives in exactly one place.
+ */
+export declare function prepareItemForm(context: AccessContext<unknown>, config: OpenSaasConfig, listConfig: ListConfig<any>, itemData: Record<string, unknown>): Promise<PreparedItemForm>;
+//# sourceMappingURL=prepareItemForm.d.ts.map

package/dist/lib/prepareItemForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareItemForm.d.ts","sourceRoot":"","sources":["../../src/lib/prepareItemForm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAY,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAyB,KAAK,uBAAuB,EAAE,MAAM,2BAA2B,CAAA;AAE/F;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAA;IAC3D,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;CACvE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAEtC,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,GAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,EAC/B,MAAM,EAAE,cAAc,EAEtB,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,EAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAsE3B"}

package/dist/lib/prepareItemForm.js

@@ -0,0 +1,85 @@
+import { getDbKey } from '@opensaas/stack-core';
+import { serializeFieldConfigs } from './serializeFieldConfig.js';
+/**
+ * Build the `include` object needed to hydrate relationship fields when
+ * fetching an item for editing.
+ */
+export function buildRelationshipInclude(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig is generic over TypeInfo
+listConfig) {
+    const includeRelationships = {};
+    for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
+        if (fieldConfig.type === 'relationship') {
+            includeRelationships[fieldName] = true;
+        }
+    }
+    return includeRelationships;
+}
+/**
+ * Prepare the serializable props for `ItemFormClient` from an already-fetched
+ * record (or an empty object for create).
+ *
+ * This is shared by `ItemForm` (which fetches via `findUnique`) and
+ * `SingletonView` (which resolves via the singleton `get()`), so the
+ * relationship/serialization logic lives in exactly one place.
+ */
+export async function prepareItemForm(context, config, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig is generic over TypeInfo
+listConfig, itemData) {
+    // Fetch relationship options for all relationship fields
+    const relationshipData = {};
+    for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
+        const fieldConfigAny = fieldConfig;
+        if (fieldConfigAny.type === 'relationship') {
+            const ref = fieldConfigAny.ref;
+            if (ref) {
+                // Parse ref format: "ListName.fieldName"
+                const relatedListName = ref.split('.')[0];
+                const relatedListConfig = config.lists[relatedListName];
+                if (relatedListConfig) {
+                    try {
+                        const delegate = context.db[getDbKey(relatedListName)];
+                        const relatedItems = delegate?.findMany ? await delegate.findMany({}) : [];
+                        // Use 'name' field as label if it exists, otherwise use 'id'
+                        relationshipData[fieldName] = relatedItems.map((item) => ({
+                            id: item.id,
+                            label: (item.name || item.title || item.id) || '',
+                        }));
+                    }
+                    catch (error) {
+                        console.error(`Failed to fetch relationship items for ${fieldName}:`, error);
+                        relationshipData[fieldName] = [];
+                    }
+                }
+            }
+        }
+    }
+    // Serialize field configs to remove non-serializable properties
+    const serializableFields = serializeFieldConfigs(listConfig.fields);
+    // Transform relationship data in itemData from objects to IDs for form
+    // Also apply valueForClientSerialization transformation
+    const formData = { ...itemData };
+    for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
+        const fieldConfigAny = fieldConfig;
+        if (fieldConfigAny.type === 'relationship' && formData[fieldName]) {
+            const value = formData[fieldName];
+            if (fieldConfigAny.many && Array.isArray(value)) {
+                // Many relationship: extract IDs from array of objects
+                formData[fieldName] = value.map((item) => item.id);
+            }
+            else if (value && typeof value === 'object' && 'id' in value) {
+                // Single relationship: extract ID from object
+                formData[fieldName] = value.id;
+            }
+        }
+        // Apply valueForClientSerialization if defined
+        if (fieldConfigAny.ui?.valueForClientSerialization &&
+            typeof fieldConfigAny.ui.valueForClientSerialization === 'function') {
+            const transformer = fieldConfigAny.ui.valueForClientSerialization;
+            formData[fieldName] = transformer({ value: formData[fieldName] });
+        }
+    }
+    // JSON round-trip ensures only serializable data crosses the client boundary
+    const initialData = JSON.parse(JSON.stringify(formData));
+    return { serializableFields, initialData, relationshipData };
+}

package/dist/styles/globals.css

@@ -384,6 +384,9 @@
   .grid {
     display: grid;
   }
+  .hidden {
+    display: none;
+  }
   .inline-block {
     display: inline-block;
   }
@@ -402,6 +405,9 @@
   .h-4 {
     height: calc(var(--spacing) * 4);
   }
+  .h-5 {
+    height: calc(var(--spacing) * 5);
+  }
   .h-7 {
     height: calc(var(--spacing) * 7);
   }
@@ -459,6 +465,12 @@
   .w-4 {
     width: calc(var(--spacing) * 4);
   }
+  .w-5 {
+    width: calc(var(--spacing) * 5);
+  }
+  .w-7 {
+    width: calc(var(--spacing) * 7);
+  }
   .w-8 {
     width: calc(var(--spacing) * 8);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-ui",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Composable React UI components for OpenSaas Stack",
   "type": "module",
   "main": "./dist/index.js",
@@ -94,7 +94,7 @@
     "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",
-    "@opensaas/stack-core": "0.22.0"
+    "@opensaas/stack-core": "0.23.0"
   },
   "scripts": {
     "build": "tsc && npm run build:css",

package/src/components/AdminUI.tsx

@@ -1,10 +1,17 @@
 import * as React from 'react'
+import { redirect } from 'next/navigation.js'
 import { Navigation } from './Navigation.js'
 import { Dashboard } from './Dashboard.js'
 import { ListView } from './ListView.js'
 import { ItemForm } from './ItemForm.js'
+import { SingletonView } from './SingletonView.js'
 import type { ServerActionInput } from '../server/types.js'
-import { type AccessContext, getListKeyFromUrl, OpenSaasConfig } from '@opensaas/stack-core'
+import {
+  type AccessContext,
+  getListKeyFromUrl,
+  getUrlKey,
+  OpenSaasConfig,
+} from '@opensaas/stack-core'
 import { generateThemeCSS } from '../lib/theme.js'
 
 export interface AdminUIProps {
@@ -24,7 +31,7 @@ export interface AdminUIProps {
  *
  * Handles routing based on params array:
  * - [] → Dashboard
- * - [list] → ListView
+ * - [list] → ListView (or SingletonView when the list is `isSingleton`)
  * - [list, 'create'] → ItemForm (create)
  * - [list, id] → ItemForm (edit)
  */
@@ -52,6 +59,13 @@ export function AdminUI({
   if (!listKey) {
     // Dashboard
     content = <Dashboard context={context} config={config} basePath={basePath} />
+  } else if (config.lists[listKey]?.isSingleton && action) {
+    // A singleton has a single record edited at its bare [list] route, so the
+    // create/id sub-routes (`[list, 'create']` / `[list, id]`) don't apply.
+    // Redirect them to the bare editor so old links keep working. This runs
+    // before the create/edit ItemForm branches; non-singleton routing below is
+    // unchanged.
+    redirect(`${basePath}/${getUrlKey(listKey)}`)
   } else if (action === 'create') {
     // Create form
     content = (
@@ -77,6 +91,18 @@ export function AdminUI({
         serverAction={serverAction}
       />
     )
+  } else if (config.lists[listKey]?.isSingleton) {
+    // Singleton editor: a singleton has a single record, so its bare [list]
+    // route renders a single-record editor instead of a list table.
+    content = (
+      <SingletonView
+        context={context}
+        config={config}
+        listKey={listKey}
+        basePath={basePath}
+        serverAction={serverAction}
+      />
+    )
   } else {
     // List view
     const search = typeof searchParams.search === 'string' ? searchParams.search : undefined

package/src/components/Dashboard.tsx

@@ -16,9 +16,16 @@ export interface DashboardProps {
 export async function Dashboard({ context, config, basePath = '/admin' }: DashboardProps) {
   const lists = Object.keys(config.lists || {})
 
-  // Get counts for each list
+  // Split lists into standard lists (shown in the counted grid) and singletons
+  // (shown in their own "Settings" section). A singleton's count is always 0/1,
+  // so the "N items" label is misleading — show a "Configure" affordance instead.
+  const standardLists = lists.filter((listKey) => !config.lists[listKey]?.isSingleton)
+  const singletonLists = lists.filter((listKey) => config.lists[listKey]?.isSingleton)
+
+  // Get counts for the standard lists only. Singletons don't show a count, so
+  // there's no need to call count() for them here.
   const listCounts = await Promise.all(
-    lists.map(async (listKey) => {
+    standardLists.map(async (listKey) => {
       try {
         const delegate = context.db[getDbKey(listKey)]
         const count = delegate?.count ? await delegate.count() : 0
@@ -51,7 +58,7 @@ export async function Dashboard({ context, config, basePath = '/admin' }: Dashbo
             Add lists to your opensaas.config.ts to get started.
           </p>
         </Card>
-      ) : (
+      ) : standardLists.length > 0 ? (
         <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
           {listCounts.map(({ listKey, count }) => {
             const urlKey = getUrlKey(listKey)
@@ -97,9 +104,103 @@ export async function Dashboard({ context, config, basePath = '/admin' }: Dashbo
             )
           })}
         </div>
+      ) : null}
+
+      {/* Settings section — singletons present a "Configure" affordance instead
+          of a misleading "N items" count. */}
+      {singletonLists.length > 0 && (
+        <div className={standardLists.length > 0 ? 'mt-12' : ''}>
+          <div className="mb-4 flex items-center gap-2">
+            <svg
+              className="w-5 h-5 text-muted-foreground"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+              aria-hidden="true"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z"
+              />
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"
+              />
+            </svg>
+            <h2 className="text-xl font-semibold text-foreground">Settings</h2>
+          </div>
+          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+            {singletonLists.map((listKey) => {
+              const urlKey = getUrlKey(listKey)
+              return (
+                <Link key={listKey} href={`${basePath}/${urlKey}`}>
+                  <Card className="group hover:border-primary hover:shadow-lg hover:shadow-primary/20 transition-all duration-200 cursor-pointer h-full relative overflow-hidden">
+                    <div className="absolute inset-0 bg-gradient-to-br from-primary/5 to-accent/5 opacity-0 group-hover:opacity-100 transition-opacity" />
+                    <CardHeader className="relative">
+                      <div className="flex items-start justify-between">
+                        <div>
+                          <CardTitle className="text-xl group-hover:text-primary transition-colors">
+                            {formatListName(listKey)}
+                          </CardTitle>
+                        </div>
+                        <div className="text-muted-foreground opacity-60 group-hover:opacity-100 transition-opacity">
+                          <svg
+                            className="w-7 h-7"
+                            fill="none"
+                            stroke="currentColor"
+                            viewBox="0 0 24 24"
+                            aria-hidden="true"
+                          >
+                            <path
+                              strokeLinecap="round"
+                              strokeLinejoin="round"
+                              strokeWidth={2}
+                              d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z"
+                            />
+                            <path
+                              strokeLinecap="round"
+                              strokeLinejoin="round"
+                              strokeWidth={2}
+                              d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"
+                            />
+                          </svg>
+                        </div>
+                      </div>
+                    </CardHeader>
+                    <CardContent className="relative">
+                      <div className="flex items-center text-sm font-medium text-primary">
+                        <span>Configure</span>
+                        <svg
+                          className="ml-1 w-4 h-4 group-hover:translate-x-1 transition-transform"
+                          fill="none"
+                          stroke="currentColor"
+                          viewBox="0 0 24 24"
+                        >
+                          <path
+                            strokeLinecap="round"
+                            strokeLinejoin="round"
+                            strokeWidth={2}
+                            d="M9 5l7 7-7 7"
+                          />
+                        </svg>
+                      </div>
+                    </CardContent>
+                  </Card>
+                </Link>
+              )
+            })}
+          </div>
+        </div>
       )}
 
-      {lists.length > 0 && (
+      {/* Quick Actions only contains "Create {list}" links for standard lists,
+          so hide the whole card when there are no standard lists (e.g. a
+          singleton-only admin). */}
+      {standardLists.length > 0 && (
         <Card className="mt-12 bg-gradient-to-br from-accent/10 to-primary/10 border-accent/20">
           <CardHeader>
             <CardTitle className="text-lg flex items-center gap-2">
@@ -109,7 +210,9 @@ export async function Dashboard({ context, config, basePath = '/admin' }: Dashbo
           </CardHeader>
           <CardContent>
             <div className="flex flex-wrap gap-3">
-              {lists.map((listKey) => {
+              {/* Singletons have a single record (no create), so they're
+                  excluded here — only standard lists get a "Create" quick-action. */}
+              {standardLists.map((listKey) => {
                 const urlKey = getUrlKey(listKey)
                 return (
                   <Link