@coffer-org/sdk 1.4.0 → 1.6.0

package/dist/extend.d.ts

@@ -2,8 +2,8 @@ import type { LayoutEl } from './fields.ts';
 import type { Condition } from './condition.ts';
 import { z } from 'zod';
 export interface AttachRule {
-    vault: string;
-    module?: string;
+    library: string;
+    shelf?: string;
 }
 export interface ExtendDef {
     id: string;
@@ -15,7 +15,7 @@ export interface ExtendDef {
     claude?: string;
 }
 export declare function defineExtend(e: ExtendDef): ExtendDef;
-export declare function extendMatches(e: ExtendDef, vault: string, module: string): boolean;
+export declare function extendMatches(e: ExtendDef, library: string, shelf: string): boolean;
 export declare function buildExtendZodPartial(e: ExtendDef): z.ZodObject<z.ZodRawShape>;
 export declare function extendToClient(e: ExtendDef): {
     id: string;
@@ -23,5 +23,5 @@ export declare function extendToClient(e: ExtendDef): {
     icon: string | undefined;
     attachTo: AttachRule[];
     showWhen: Condition | undefined;
-    fields: import("./module.ts").LayoutElClient[];
+    fields: import("./shelf.ts").LayoutElClient[];
 };

package/dist/extend.js

@@ -1,4 +1,4 @@
-import { layoutToClient, fieldEntries, buildShape } from "./module.js";
+import { layoutToClient, fieldEntries, buildShape } from "./shelf.js";
 import { z } from 'zod';
 export function defineExtend(e) {
     const keys = fieldEntries(e.fields).map(([k]) => k);
@@ -7,11 +7,11 @@ export function defineExtend(e) {
         throw new Error(`[extend] ${e.id}: duplicate key '${dup}'`);
     return e;
 }
-export function extendMatches(e, vault, module) {
+export function extendMatches(e, library, shelf) {
     return e.attachTo.some((rule) => {
-        if (rule.vault !== vault)
+        if (rule.library !== library)
             return false;
-        if (rule.module && rule.module !== module)
+        if (rule.shelf && rule.shelf !== shelf)
             return false;
         return true;
     });

package/dist/field-presets.d.ts

@@ -39,6 +39,10 @@ export declare function internalApiToken(o: {
     key: string;
     label?: string;
 }): GroupEl;
+export declare function internalOauthGrants(o: {
+    key: string;
+    label?: string;
+}): GroupEl;
 export declare function slug(o: TextPresetOpts & {
     key: string;
 }): FieldItem;
@@ -247,5 +251,6 @@ export declare const presets: {
     dimensions: typeof dimensions;
     country: typeof country;
     internalApiToken: typeof internalApiToken;
+    internalOauthGrants: typeof internalOauthGrants;
 };
 export {};

package/dist/field-presets.js

@@ -65,6 +65,19 @@ export function internalApiToken(o) {
         ],
     });
 }
+export function internalOauthGrants(o) {
+    return group({
+        key: o.key,
+        label: o.label ?? o.key,
+        multiple: true,
+        view: { kind: 'internalOauthGrants' },
+        fields: [
+            string({ key: 'clientName' }),
+            string({ key: 'createdAt' }),
+            string({ key: 'lastUsedAt' }),
+        ],
+    });
+}
 const SLUG_RE = /^[a-z0-9-]+$/;
 export function slug(raw) {
     const o = normalizeOpts(raw);
@@ -324,4 +337,5 @@ export const presets = {
     dimensions,
     country,
     internalApiToken,
+    internalOauthGrants,
 };

package/dist/fields/normalize.d.ts

@@ -55,8 +55,8 @@ export type NormalizedOpts = {
     pick?: string[];
     option?: unknown;
     relation?: {
-        vault: string;
-        module: string;
+        library: string;
+        shelf: string;
     };
     fields?: unknown;
     config?: FieldConfig;

package/dist/fields.d.ts

@@ -40,8 +40,8 @@ export interface ComputeCtx {
     settings: Record<string, unknown>;
     global: Record<string, unknown>;
     meta: {
-        vault: string;
-        module: string;
+        library: string;
+        shelf: string;
     };
 }
 export type ComputeFn = (ctx: ComputeCtx) => unknown;
@@ -93,7 +93,7 @@ export interface FieldClient {
     hints: Record<string, unknown>;
     options?: OptionItem[];
     relation?: {
-        vault: string;
+        library: string;
         type: string;
     };
     virtual?: boolean;
@@ -185,6 +185,10 @@ export interface FieldCoreOpts {
     default?: string | number | boolean | null;
     required?: boolean | Condition;
     multiple?: boolean;
+    emphasis?: 'hero' | 'muted';
+    noLabel?: boolean;
+    role?: 'cover' | 'avatar';
+    pinned?: boolean;
 }
 export declare function wrapKey(opts: {
     key?: string;
@@ -192,6 +196,10 @@ export declare function wrapKey(opts: {
     noEditControl?: boolean;
     default?: string | number | boolean | null;
     hidden?: boolean | Condition;
+    emphasis?: 'hero' | 'muted';
+    noLabel?: boolean;
+    role?: 'cover' | 'avatar';
+    pinned?: boolean;
 }, meta: FieldMeta): FieldItem | StaticEl | FieldMeta;
 export interface FieldMeta extends FieldClient {
     column: ColumnType;
@@ -371,8 +379,8 @@ export declare function select(o: SelectOpts & {
 }): FieldMeta;
 export interface RelationOpts extends FieldCoreOpts {
     options: {
-        vault: string;
-        module: string;
+        library: string;
+        shelf: string;
     };
 }
 export declare function relation(o: RelationOpts & {

package/dist/fields.js

@@ -116,6 +116,14 @@ export function wrapKey(opts, meta) {
     let m = meta;
     if (opts.noEditControl)
         m = { ...m, hints: { ...m.hints, noEditControl: true } };
+    if (opts.emphasis)
+        m = { ...m, hints: { ...m.hints, emphasis: opts.emphasis } };
+    if (opts.noLabel)
+        m = { ...m, hints: { ...m.hints, noLabel: true } };
+    if (opts.role)
+        m = { ...m, hints: { ...m.hints, role: opts.role } };
+    if (opts.pinned)
+        m = { ...m, hints: { ...m.hints, pinned: true } };
     if (opts.default !== undefined)
         m = { ...m, default: opts.default };
     if (opts.hidden !== undefined)
@@ -456,7 +464,7 @@ export function relation(raw) {
         prim: 'relation',
         column: multi ? 'text' : 'integer',
         hints: { multi, displayKey: o.displayKey ?? 'name' },
-        relation: { vault: raw.options.vault, type: raw.options.module },
+        relation: { library: raw.options.library, type: raw.options.shelf },
         ...(multi && { json: true }),
         zod: optionalize(s, required),
     };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export * from './field-helpers.ts';
 export * from './fields.ts';
 export * from './field-presets.ts';
-export * from './module.ts';
-export * from './vault.ts';
+export * from './shelf.ts';
+export * from './library.ts';
 export * from './extend.ts';
 export * from './package.ts';
 export * from './plugin.ts';

package/dist/index.js

@@ -1,8 +1,8 @@
 export * from "./field-helpers.js";
 export * from "./fields.js";
 export * from "./field-presets.js";
-export * from "./module.js";
-export * from "./vault.js";
+export * from "./shelf.js";
+export * from "./library.js";
 export * from "./extend.js";
 export * from "./package.js";
 export * from "./plugin.js";

package/dist/library.d.ts

@@ -0,0 +1,14 @@
+import type { ShelfDef } from './shelf.ts';
+export interface LibraryDef {
+    id: string;
+    label: string;
+    icon?: string;
+    agent?: string;
+}
+export declare function defineLibrary(v: LibraryDef): LibraryDef;
+export declare const DEFAULT_LIBRARY_ICON = "lucide:folder";
+export declare function fallbackLibrary(id: string): LibraryDef;
+export interface LibraryBundle {
+    meta: LibraryDef;
+    shelves: ShelfDef[];
+}

package/dist/library.js

@@ -0,0 +1,7 @@
+export function defineLibrary(v) {
+    return v;
+}
+export const DEFAULT_LIBRARY_ICON = 'lucide:folder';
+export function fallbackLibrary(id) {
+    return { id, label: id, icon: DEFAULT_LIBRARY_ICON };
+}

package/dist/package.d.ts

@@ -1,13 +1,13 @@
-import type { VaultBundle } from './vault.ts';
-import type { ModuleDef } from './module.ts';
+import type { LibraryBundle } from './library.ts';
+import type { ShelfDef } from './shelf.ts';
 import type { ExtendDef } from './extend.ts';
 export interface ModulePackage {
-    vaults?: VaultBundle[];
-    vaultModules?: ModuleDef[];
+    libraries?: LibraryBundle[];
+    libraryShelves?: ShelfDef[];
     extends_?: ExtendDef[];
 }
 export declare function assemblePackages(packages: ModulePackage[]): {
-    vaults: VaultBundle[];
-    modules: ModuleDef[];
+    libraries: LibraryBundle[];
+    shelves: ShelfDef[];
     extends_: ExtendDef[];
 };

package/dist/package.js

@@ -1,26 +1,26 @@
-import { fallbackVault } from "./vault.js";
+import { fallbackLibrary } from "./library.js";
 export function assemblePackages(packages) {
     const metaMap = new Map();
     for (const pkg of packages) {
-        for (const bundle of pkg.vaults ?? []) {
+        for (const bundle of pkg.libraries ?? []) {
             if (!metaMap.has(bundle.meta.id))
                 metaMap.set(bundle.meta.id, { ...bundle.meta });
         }
     }
-    const modules = [];
+    const shelves = [];
     for (const pkg of packages) {
-        for (const bundle of pkg.vaults ?? [])
-            modules.push(...bundle.modules);
-        modules.push(...(pkg.vaultModules ?? []));
+        for (const bundle of pkg.libraries ?? [])
+            shelves.push(...bundle.shelves);
+        shelves.push(...(pkg.libraryShelves ?? []));
     }
-    const ids = new Set([...metaMap.keys(), ...modules.map((m) => m.vault)]);
-    const vaults = [...ids].map((id) => ({
-        meta: metaMap.get(id) ?? fallbackVault(id),
-        modules: modules.filter((m) => m.vault === id),
+    const ids = new Set([...metaMap.keys(), ...shelves.map((m) => m.library)]);
+    const libraries = [...ids].map((id) => ({
+        meta: metaMap.get(id) ?? fallbackLibrary(id),
+        shelves: shelves.filter((m) => m.library === id),
     }));
     return {
-        vaults,
-        modules,
+        libraries,
+        shelves,
         extends_: packages.flatMap((pkg) => pkg.extends_ ?? []),
     };
 }

package/dist/plugin.d.ts

@@ -1,11 +1,11 @@
-import type { VaultBundle } from './vault.ts';
-import type { ModuleDef } from './module.ts';
+import type { LibraryBundle } from './library.ts';
+import type { ShelfDef } from './shelf.ts';
 import type { ExtendDef } from './extend.ts';
 import type { OptionItem } from './fields.ts';
 import type { SettingsDef } from './settings.ts';
 export interface FieldContrib {
-    vault: string;
-    module: string;
+    library: string;
+    shelf: string;
     field: string;
     options?: OptionItem[];
     suggestions?: string[];
@@ -18,8 +18,8 @@ export interface PluginManifest {
     id: string;
     version: string;
     dependsOn: string[];
-    vaults?: VaultBundle[];
-    vaultModules?: ModuleDef[];
+    libraries?: LibraryBundle[];
+    libraryShelves?: ShelfDef[];
     extends_?: ExtendDef[];
     fieldContribs?: FieldContrib[];
     optionLists?: NamedOptionList[];
@@ -30,8 +30,8 @@ export declare function definePlugin(p: PluginManifest): PluginManifest;
 export declare function topoSortPlugins(plugins: PluginManifest[]): PluginManifest[];
 export interface AssembledPlugins {
     order: PluginManifest[];
-    vaults: VaultBundle[];
-    modules: ModuleDef[];
+    libraries: LibraryBundle[];
+    shelves: ShelfDef[];
     extends_: ExtendDef[];
 }
 export declare function assemblePlugins(plugins: PluginManifest[]): AssembledPlugins;

package/dist/plugin.js

@@ -38,6 +38,6 @@ export function topoSortPlugins(plugins) {
 }
 export function assemblePlugins(plugins) {
     const order = topoSortPlugins(plugins);
-    const { vaults, modules, extends_ } = assemblePackages(order);
-    return { order, vaults, modules, extends_ };
+    const { libraries, shelves, extends_ } = assemblePackages(order);
+    return { order, libraries, shelves, extends_ };
 }

package/dist/shelf.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import type { FieldMeta, LayoutEl, ColumnType } from './fields.ts';
+import type { FieldClient, GroupEl, PseudoEl } from './fields.ts';
+export interface ShelfViews {
+    title?: string;
+    inline?: string[];
+    table?: string[];
+    groupBy?: string[];
+    defaultGroupBy?: string;
+    select?: {
+        icon?: string;
+        title: string | string[];
+        subtitle?: string;
+    };
+}
+export interface ShelfDef {
+    shelf: string;
+    library: string;
+    label: string;
+    icon?: string;
+    claude?: string;
+    standalone?: boolean;
+    views?: ShelfViews;
+    fields: LayoutEl[];
+}
+export declare function fieldEntries(items: LayoutEl[]): [string, FieldMeta][];
+export declare function storageColumns(key: string, field: FieldMeta): [string, ColumnType][];
+export interface CollectionEntry {
+    key: string;
+    group: GroupEl;
+}
+export declare function collectionGroups(items: LayoutEl[]): CollectionEntry[];
+export declare function fieldMap(items: LayoutEl[]): Record<string, FieldMeta>;
+export declare function defineShelf(m: ShelfDef): ShelfDef;
+export declare const SYSTEM_FIELDS: readonly ["id", "createdAt", "updatedAt"];
+export declare function titleKey(m: ShelfDef): string;
+export declare function recordTitle(m: ShelfDef, record: Record<string, unknown>): string;
+export declare const isImageKind: (kind: string) => boolean;
+export declare function textSearchKeys(m: ShelfDef): string[];
+export declare function inlineKeys(m: ShelfDef): string[];
+export declare function inlineImageKey(m: ShelfDef): string | undefined;
+export declare function inlineText(m: ShelfDef, row: Record<string, unknown>): string;
+export declare function tableKeys(m: ShelfDef): string[];
+export declare function groupableFields(m: ShelfDef): string[];
+export declare function defaultGroupField(m: ShelfDef): string | undefined;
+export declare function buildShape(fields: LayoutEl[], partial: boolean): z.ZodRawShape;
+export declare function buildZodObject(m: ShelfDef): z.ZodTypeAny;
+export declare function buildZodObjectPartial(m: ShelfDef): z.ZodTypeAny;
+export interface StaticElClient {
+    el: 'static';
+    type: FieldClient;
+    value: unknown;
+    computed?: boolean;
+}
+export type GroupElClient = Omit<GroupEl, 'fields'> & {
+    fields: ({
+        key: string;
+        type: FieldClient;
+    } | StaticElClient | GroupElClient | PseudoEl)[];
+};
+export type LayoutElClient = {
+    key: string;
+    type: FieldClient;
+} | GroupElClient | StaticElClient | PseudoEl;
+export declare function layoutToClient(items: LayoutEl[]): LayoutElClient[];
+export declare function shelfToClient(m: ShelfDef): {
+    shelf: string;
+    library: string;
+    label: string;
+    icon: string | undefined;
+    views: ShelfViews | undefined;
+    standalone: boolean | undefined;
+    fields: LayoutElClient[];
+};

package/dist/shelf.js

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+import { toClient, isField, isGroup, isStatic, isCollectionGroup, isEmbeddedGroup } from "./fields.js";
+import { resolveFlag } from "./condition.js";
+import { parseUrl } from "./fields/url.js";
+export function fieldEntries(items) {
+    const out = [];
+    for (const it of items) {
+        if (isField(it)) {
+            out.push([it.key, it.type]);
+        }
+        else if (isGroup(it)) {
+            if (isCollectionGroup(it))
+                continue;
+            const prefix = it.key ? `${it.key}__` : '';
+            for (const [sub, fm] of fieldEntries(it.fields)) {
+                out.push([prefix + sub, fm]);
+            }
+        }
+    }
+    return out;
+}
+export function storageColumns(key, field) {
+    if (field.columns)
+        return Object.entries(field.columns).map(([sub, col]) => [`${key}__${sub}`, col]);
+    return [[key, field.column]];
+}
+export function collectionGroups(items) {
+    const out = [];
+    for (const it of items) {
+        if (!isGroup(it))
+            continue;
+        if (isCollectionGroup(it)) {
+            out.push({ key: it.key, group: it });
+        }
+        else {
+            out.push(...collectionGroups(it.fields));
+        }
+    }
+    return out;
+}
+const mapCache = new WeakMap();
+export function fieldMap(items) {
+    let m = mapCache.get(items);
+    if (!m) {
+        m = Object.fromEntries(fieldEntries(items));
+        mapCache.set(items, m);
+    }
+    return m;
+}
+export function defineShelf(m) {
+    const keys = fieldEntries(m.fields).map(([k]) => k);
+    const dup = keys.find((k, i) => keys.indexOf(k) !== i);
+    if (dup)
+        throw new Error(`[shelf] ${m.library}/${m.shelf}: duplicate key '${dup}'`);
+    if (m.standalone !== false && !m.views?.table?.length)
+        console.warn(`[shelf] ${m.library}/${m.shelf}: standalone shelf without an explicit views.table`);
+    return m;
+}
+export const SYSTEM_FIELDS = ['id', 'createdAt', 'updatedAt'];
+export function titleKey(m) {
+    if (m.views?.title)
+        return m.views.title;
+    const fm = fieldMap(m.fields);
+    const inlineNonImage = m.views?.inline?.find((k) => fm[k] && !isImageKind(fm[k].kind));
+    if (inlineNonImage)
+        return inlineNonImage;
+    if (fm['name'])
+        return 'name';
+    const firstText = fieldEntries(m.fields).find(([, f]) => !f.virtual && isTextPrim(f.prim));
+    if (firstText)
+        return firstText[0];
+    return 'id';
+}
+export function recordTitle(m, record) {
+    return String(record[titleKey(m)] ?? record['id'] ?? '');
+}
+function realKeys(m, keys) {
+    const fm = fieldMap(m.fields);
+    return keys.filter((k) => fm[k] && !fm[k].virtual);
+}
+const IMAGE_KINDS = new Set(['image', 'media', 'avatar', 'cover']);
+export const isImageKind = (kind) => IMAGE_KINDS.has(kind);
+const isTextPrim = (p) => p === 'string' || p === 'text';
+export function textSearchKeys(m) {
+    return fieldEntries(m.fields)
+        .filter(([, f]) => !f.virtual && f.kind !== 'password' && isTextPrim(f.prim))
+        .map(([k]) => k);
+}
+export function inlineKeys(m) {
+    const ks = m.views?.inline?.length ? realKeys(m, m.views.inline) : [];
+    if (ks.length)
+        return ks;
+    return [titleKey(m)];
+}
+export function inlineImageKey(m) {
+    const fm = fieldMap(m.fields);
+    return inlineKeys(m).find((k) => fm[k] && isImageKind(fm[k].kind));
+}
+export function inlineText(m, row) {
+    const fm = fieldMap(m.fields);
+    const parts = inlineKeys(m).reduce((acc, k) => {
+        if (!fm[k] || !isImageKind(fm[k].kind)) {
+            const v = row[k];
+            if (v != null && v !== '')
+                acc.push(String(v));
+        }
+        return acc;
+    }, []);
+    return parts.join(' ').trim() || recordTitle(m, row);
+}
+export function tableKeys(m) {
+    const tk = titleKey(m);
+    const rest = m.views?.table?.length
+        ? realKeys(m, m.views.table.filter((k) => k !== tk))
+        : [];
+    return [tk, ...rest];
+}
+const GROUPABLE_PRIMS = new Set(['select', 'checkbox', 'relation']);
+export function groupableFields(m) {
+    if (m.views?.groupBy?.length)
+        return realKeys(m, m.views.groupBy);
+    return fieldEntries(m.fields)
+        .filter(([, f]) => !f.virtual && GROUPABLE_PRIMS.has(f.prim))
+        .map(([k]) => k);
+}
+export function defaultGroupField(m) {
+    const dg = m.views?.defaultGroupBy;
+    if (dg) {
+        const fm = fieldMap(m.fields);
+        if (fm[dg] && !fm[dg].virtual)
+            return dg;
+    }
+    return groupableFields(m)[0];
+}
+export function buildShape(fields, partial) {
+    const shape = {};
+    for (const it of fields) {
+        if (isField(it)) {
+            if (it.type.virtual)
+                continue;
+            shape[it.key] = partial ? it.type.zod.optional() : it.type.zod;
+        }
+        else if (isGroup(it)) {
+            if (isCollectionGroup(it)) {
+                const inner = z.object(buildShape(it.fields, partial)).passthrough();
+                const arr = z.array(inner);
+                shape[it.key] = partial ? arr.optional() : it.required ? arr : arr.optional();
+            }
+            else if (isEmbeddedGroup(it)) {
+                let inner = z.object(buildShape(it.fields, partial)).passthrough();
+                if (it.kind === 'url') {
+                    inner = z.preprocess((v) => (typeof v === 'string' ? (parseUrl(v) ?? {}) : v), inner);
+                }
+                shape[it.key] = partial ? inner.optional() : it.required ? inner : inner.optional();
+            }
+            else {
+                Object.assign(shape, buildShape(it.fields, partial));
+            }
+        }
+    }
+    return shape;
+}
+const isEmpty = (v) => v == null || v === '' || (Array.isArray(v) && v.length === 0);
+function withConditionalRequired(base, m, partial) {
+    return base.superRefine((data, ctx) => {
+        for (const [key, f] of fieldEntries(m.fields)) {
+            if (f.virtual)
+                continue;
+            if (key.includes('__'))
+                continue;
+            if (partial && !(key in data))
+                continue;
+            if (f.required === true)
+                continue;
+            if (!resolveFlag(f.required, data))
+                continue;
+            if (isEmpty(data[key]))
+                ctx.addIssue({ code: 'custom', path: [key], message: JSON.stringify({ code: 'required' }) });
+        }
+    });
+}
+export function buildZodObject(m) {
+    return withConditionalRequired(z.object(buildShape(m.fields, false)), m, false);
+}
+export function buildZodObjectPartial(m) {
+    return withConditionalRequired(z.object(buildShape(m.fields, true)), m, true);
+}
+function elToClient(it) {
+    if (isField(it))
+        return { key: it.key, type: toClient(it.type) };
+    if (isStatic(it)) {
+        const fn = typeof it.value === 'function';
+        return { el: 'static', type: toClient(it.type), value: fn ? null : it.value, computed: fn || undefined };
+    }
+    if (isGroup(it))
+        return { ...it, fields: it.fields.map(elToClient) };
+    return it;
+}
+export function layoutToClient(items) {
+    return items.map(elToClient);
+}
+export function shelfToClient(m) {
+    return {
+        shelf: m.shelf,
+        library: m.library,
+        label: m.label,
+        icon: m.icon,
+        views: m.views,
+        standalone: m.standalone,
+        fields: layoutToClient(m.fields),
+    };
+}

package/dist/users-shelf.d.ts

@@ -0,0 +1 @@
+export declare const USERS_SHELF: import("./shelf.ts").ShelfDef;

package/dist/users-shelf.js

@@ -0,0 +1,22 @@
+import { defineShelf } from "./shelf.js";
+import { field } from "./fields.js";
+export const USERS_SHELF = defineShelf({
+    shelf: 'users',
+    library: '',
+    label: 'auth.usersTitle',
+    icon: 'lucide:users',
+    views: { table: ['login', 'displayName', 'role', 'disabled'] },
+    fields: [
+        field.string({ key: 'login', label: 'auth.fieldLogin' }),
+        field.string({ key: 'displayName', label: 'auth.fieldDisplayName' }),
+        field.select({
+            key: 'role',
+            label: 'auth.fieldRole',
+            options: [
+                { value: 'admin', title: 'auth.roleAdmin' },
+                { value: 'member', title: 'auth.roleMember' },
+            ],
+        }),
+        field.boolean({ key: 'disabled', label: 'auth.fieldDisabled' }),
+    ],
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/sdk",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "type": "module",
   "engines": {
     "node": ">=24"