@coffer-org/sdk 2.2.1 → 3.1.0

package/dist/condition.d.ts

@@ -17,6 +17,13 @@ export interface Condition {
     $or?: Condition[];
 }
 export type Values = Record<string, unknown>;
+export declare const COMPILABLE_SCALAR_OPS: Set<string>;
+export declare const COMPILABLE_ARRAY_OPS: Set<string>;
 export declare function evalCondition(cond: Condition | undefined, values: Values): boolean;
 export declare function resolveFlag(v: boolean | Condition | undefined, values: Values): boolean;
+export declare function conditionKeys(cond: Condition | undefined): string[];
+export declare function visibleOptions<T extends {
+    value?: string;
+    when?: Condition;
+}>(options: T[], values: Values, keep?: string | string[]): T[];
 export declare function describeCondition(cond: Condition | undefined, labelOf: (field: string) => string, valueLabelOf?: (field: string, value: Scalar) => string): string[];

package/dist/condition.js

@@ -1,4 +1,6 @@
 import sift from 'sift';
+export const COMPILABLE_SCALAR_OPS = new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte']);
+export const COMPILABLE_ARRAY_OPS = new Set(['$in', '$nin']);
 const createEqualsOperation = sift
     .createEqualsOperation;
 const isScalar = (v) => typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
@@ -62,6 +64,26 @@ function describePredicate(label, pred, vl) {
     }
     return out;
 }
+export function conditionKeys(cond) {
+    if (!cond)
+        return [];
+    const out = [];
+    for (const [key, spec] of Object.entries(cond)) {
+        if (spec === undefined)
+            continue;
+        if (key === '$and' || key === '$or') {
+            for (const c of spec)
+                out.push(...conditionKeys(c));
+            continue;
+        }
+        out.push(key);
+    }
+    return [...new Set(out)];
+}
+export function visibleOptions(options, values, keep) {
+    const kept = keep === undefined ? undefined : new Set(Array.isArray(keep) ? keep : [keep]);
+    return options.filter((o) => (kept !== undefined && o.value !== undefined && kept.has(o.value)) || (o.when ? evalCondition(o.when, values) : true));
+}
 export function describeCondition(cond, labelOf, valueLabelOf) {
     if (!cond)
         return [];

package/dist/derive.d.ts

@@ -0,0 +1,12 @@
+import { type LayoutEl } from './fields.ts';
+export interface DeriveCtx {
+    record: Record<string, unknown>;
+}
+export type DeriveFn = (ctx: DeriveCtx) => unknown;
+export interface DeriveSpec {
+    deps: string[];
+    fn: DeriveFn;
+}
+export declare function derivedEntries(fields: LayoutEl[]): [string, DeriveSpec][];
+export declare function applyDerived(fields: LayoutEl[], record: Record<string, unknown>): Record<string, unknown>;
+export declare function derivableKeys(fields: LayoutEl[]): Set<string>;

package/dist/derive.js

@@ -0,0 +1,42 @@
+import { isField, isGroup } from "./fields.js";
+export function derivedEntries(fields) {
+    const out = [];
+    for (const it of fields) {
+        if (isField(it)) {
+            const spec = it.type.derive;
+            if (spec)
+                out.push([it.key, spec]);
+        }
+        else if (isGroup(it) && !it.key) {
+            out.push(...derivedEntries(it.fields));
+        }
+    }
+    return out;
+}
+export function applyDerived(fields, record) {
+    const out = {};
+    for (const [key, spec] of derivedEntries(fields)) {
+        try {
+            out[key] = spec.fn({ record });
+        }
+        catch (e) {
+            console.warn(`[derive] '${key}' threw`, e);
+        }
+    }
+    return out;
+}
+export function derivableKeys(fields) {
+    const keys = new Set();
+    for (const it of fields) {
+        if (isField(it))
+            keys.add(it.key);
+        else if (isGroup(it)) {
+            if (it.key)
+                keys.add(it.key);
+            if (!it.key)
+                for (const k of derivableKeys(it.fields))
+                    keys.add(k);
+        }
+    }
+    return keys;
+}

package/dist/field-presets.js

@@ -375,7 +375,7 @@ export function source(raw) {
         required,
         prim: 'text',
         column: 'text',
-        hints: { ext, maxBytes, noEditControl: true },
+        hints: { ext, maxBytes, noEditControl: true, ...(o.key ? { fileName: o.key } : {}) },
         zod: optionalize(s, required),
     };
     return wrapKey(o, meta);

package/dist/fields.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type UnitsSpec } from './units.ts';
 export { vmsg, reqErr, typeErr, reqTypeErr, jsonRefined, optionalize, jsonValue, decodeVmsg, validateField, } from './fields/validation.ts';
 import type { Condition } from './condition.ts';
 export type { Rules, View, FieldConfig } from './fields/normalize.ts';
@@ -23,6 +24,7 @@ export interface OptionItem {
     title: string;
     icon?: OptionIcon;
     subtitle?: string;
+    when?: Condition;
 }
 declare const __fieldItemBrand: unique symbol;
 export interface FieldItem {
@@ -95,10 +97,12 @@ export interface FieldClient {
     relation?: {
         library: string;
         shelf: string;
+        filter?: Condition;
     };
     virtual?: boolean;
     default?: string | number | boolean | null;
     json?: true;
+    derived?: true;
     columns?: Record<string, ColumnType>;
     hidden?: boolean | Condition;
 }
@@ -180,6 +184,7 @@ export interface FieldCoreOpts {
     emphasis?: 'hero' | 'muted';
     noLabel?: boolean;
     role?: 'cover' | 'avatar';
+    derive?: import('./derive.ts').DeriveSpec;
 }
 export declare function wrapKey(opts: {
     key?: string;
@@ -190,10 +195,12 @@ export declare function wrapKey(opts: {
     emphasis?: 'hero' | 'muted';
     noLabel?: boolean;
     role?: 'cover' | 'avatar';
+    derive?: import('./derive.ts').DeriveSpec;
 }, meta: FieldMeta): FieldItem | StaticEl | FieldMeta;
 export interface FieldMeta extends FieldClient {
     column: ColumnType;
     zod: z.ZodTypeAny;
+    derive?: import('./derive.ts').DeriveSpec;
 }
 export declare function isJsonStored(field: FieldMeta | FieldClient): boolean;
 export { LANGUAGES, SEX_OPTIONS, WEEKDAY_OPTIONS } from './fields/constants.ts';
@@ -372,6 +379,7 @@ export interface RelationOpts extends FieldCoreOpts {
     options: {
         library: string;
         shelf: string;
+        filter?: Condition;
     };
 }
 export declare function relation(o: RelationOpts & {
@@ -427,6 +435,27 @@ export declare function measured(o: MeasuredOpts & {
     key?: undefined;
     value?: undefined;
 }): FieldMeta;
+export type UnitScope = string;
+export interface UnitOpts extends FieldCoreOpts {
+    options: UnitsSpec;
+}
+export declare function unit(o: UnitOpts & {
+    key: string;
+}): FieldItem;
+export declare function unit(o: UnitOpts & {
+    key?: undefined;
+    value?: undefined;
+}): FieldMeta;
+export interface AmountOpts extends FieldCoreOpts {
+    unitFrom: UnitScope;
+}
+export declare function amount(o: AmountOpts & {
+    key: string;
+}): FieldItem;
+export declare function amount(o: AmountOpts & {
+    key?: undefined;
+    value?: undefined;
+}): FieldMeta;
 export type MoneyOpts = FieldCoreOpts;
 export declare function money(o: MoneyOpts & {
     key: string;
@@ -667,6 +696,8 @@ declare const PRIMITIVES: {
     json: typeof json;
     check: typeof check;
     measured: typeof measured;
+    unit: typeof unit;
+    amount: typeof amount;
     money: typeof money;
     code: typeof code;
     geo: typeof geo;

package/dist/fields.js

@@ -127,6 +127,8 @@ export function wrapKey(opts, meta) {
         m = { ...m, default: opts.default };
     if (opts.hidden !== undefined)
         m = { ...m, hidden: opts.hidden };
+    if (opts.derive)
+        m = { ...m, derive: opts.derive, derived: true, hints: { ...m.hints, noEditControl: true } };
     if (opts.key)
         return { key: opts.key, type: m };
     if ('value' in opts && opts.value !== undefined)
@@ -451,10 +453,20 @@ export function select(raw) {
     const meta = applyMultiple(base, o.multiple ?? false);
     return wrapKey(o, meta);
 }
+function assertFlatEqualityFilter(filter) {
+    for (const [key, value] of Object.entries(filter)) {
+        if (key.startsWith('$'))
+            throw new Error(`[relation] filter key '${key}' is an operator — only flat equality is allowed here`);
+        if (value === undefined || (value !== null && typeof value === 'object'))
+            throw new Error(`[relation] filter key '${key}' has a non-scalar value — only flat equality is allowed here`);
+    }
+}
 export function relation(raw) {
     const o = normalizeOpts(raw);
     const required = o.required ?? false;
     const multi = o.multiple ?? false;
+    if (raw.options.filter)
+        assertFlatEqualityFilter(raw.options.filter);
     let s;
     if (multi) {
         s = z.unknown().superRefine((raw, ctx) => {
@@ -476,7 +488,11 @@ export function relation(raw) {
         prim: 'relation',
         column: multi ? 'text' : 'integer',
         hints: { multi, displayKey: o.displayKey ?? 'name' },
-        relation: { library: raw.options.library, shelf: raw.options.shelf },
+        relation: {
+            library: raw.options.library,
+            shelf: raw.options.shelf,
+            ...(raw.options.filter && { filter: raw.options.filter }),
+        },
         ...(multi && { json: true }),
         zod: optionalize(s, required),
     };
@@ -635,6 +651,45 @@ export function measured(raw) {
     };
     return wrapKey(o, meta);
 }
+export function unit(raw) {
+    const o = normalizeOpts(raw);
+    const required = o.required ?? false;
+    const units = resolveUnits(o.options);
+    const s = z
+        .string(reqErr())
+        .refine((v) => units.some((u) => u.value === v), { message: vmsg('measured_unit') });
+    const meta = {
+        kind: 'unit',
+        label: o.label ?? '',
+        required,
+        prim: 'select',
+        column: 'text',
+        hints: { source: typeof o.options === 'string' ? o.options : null },
+        options: units.map((u) => ({ value: u.value, title: u.label })),
+        zod: optionalize(s, required),
+    };
+    return wrapKey(o, meta);
+}
+export function amount(raw) {
+    const o = normalizeOpts(raw);
+    const required = o.required ?? false;
+    const cfg = (o.config ?? {});
+    let s = z.coerce.number(typeErr());
+    if (cfg.min != null)
+        s = s.min(cfg.min, { message: vmsg('min', { min: cfg.min }) });
+    if (cfg.max != null)
+        s = s.max(cfg.max, { message: vmsg('max', { max: cfg.max }) });
+    const meta = {
+        kind: 'amount',
+        label: o.label ?? '',
+        required,
+        prim: 'number',
+        column: 'real',
+        hints: { unitFrom: o.unitFrom, min: cfg.min, max: cfg.max, step: cfg.step ?? 'any' },
+        zod: optionalize(s, required),
+    };
+    return wrapKey(o, meta);
+}
 export function money(raw) {
     const o = normalizeOpts(raw);
     const required = o.required ?? false;
@@ -1022,6 +1077,8 @@ const PRIMITIVES = {
     json,
     check,
     measured,
+    unit,
+    amount,
     money,
     code,
     geo,
@@ -1065,6 +1122,6 @@ export const field = new Proxy({}, {
     has: (_t, k) => k in composedField(),
 });
 export function toClient(field) {
-    const { kind, label, required, prim, hints, options, relation, virtual, json, hidden } = field;
-    return { kind, label, required, prim, hints, options, relation, virtual, json, hidden };
+    const { kind, label, required, prim, hints, options, relation, virtual, json, hidden, derived } = field;
+    return { kind, label, required, prim, hints, options, relation, virtual, json, hidden, derived };
 }

package/dist/plugin.d.ts

@@ -3,6 +3,7 @@ import type { ShelfDef } from './shelf.ts';
 import type { ExtendDef } from './extend.ts';
 import type { OptionItem } from './fields.ts';
 import type { SettingsDef } from './settings.ts';
+import type { ShowcaseDef } from './showcase.ts';
 export interface FieldContrib {
     library: string;
     shelf: string;
@@ -24,6 +25,7 @@ export interface PluginManifest {
     fieldContribs?: FieldContrib[];
     optionLists?: NamedOptionList[];
     settings?: SettingsDef;
+    showcases?: ShowcaseDef[];
 }
 export declare const BASE_PLUGIN = "core";
 export declare function definePlugin(p: PluginManifest): PluginManifest;

package/dist/shelf.d.ts

@@ -1,14 +1,11 @@
 import { z } from 'zod';
 import type { FieldMeta, LayoutEl, ColumnType } from './fields.ts';
 import type { FieldClient, GroupEl, PseudoEl } from './fields.ts';
-export interface ShelfListView {
-    kind?: string;
-    fields: string[];
-}
 export interface ShelfViews {
     title?: string;
     inline?: string[];
-    list?: ShelfListView;
+    list?: string[];
+    listKind?: string;
     groupBy?: string[];
     defaultGroupBy?: string;
     select?: {

package/dist/shelf.js

@@ -2,6 +2,8 @@ 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";
+import { vmsg } from "./fields/validation.js";
+import { derivedEntries, derivableKeys } from "./derive.js";
 export function fieldEntries(items) {
     const out = [];
     for (const it of items) {
@@ -70,24 +72,45 @@ export function defineShelf(m) {
         throw new Error(`[shelf] ${m.library}/${m.shelf}: duplicate key '${dup}'`);
     if (m.single && !m.claude)
         throw new Error(`[shelf] ${m.library}/${m.shelf}: single shelf requires \`claude\` — the agent cannot find it otherwise`);
-    if (m.standalone !== false && !m.single && !m.views?.list?.fields?.length)
+    if (m.views?.list !== undefined && !Array.isArray(m.views.list))
+        throw new Error(`[shelf] ${m.library}/${m.shelf}: views.list is a flat array of field keys — ` +
+            `the { kind, fields } form is gone; use views.list: [...] plus views.listKind`);
+    if (m.standalone !== false && !m.single && !m.views?.list?.length)
         console.warn(`[shelf] ${m.library}/${m.shelf}: standalone shelf without an explicit views.list`);
+    if (m.views?.title && !ownFieldEntries(m.fields).some(([k]) => k === m.views.title))
+        throw new Error(`[shelf] ${m.library}/${m.shelf}: views.title '${m.views.title}' is not a field`);
+    if (m.views?.list?.includes(titleKey(m)))
+        console.warn(`[shelf] ${m.library}/${m.shelf}: views.list repeats the title '${titleKey(m)}' — the title is declared separately`);
+    const titles = ownFieldEntries(m.fields).filter(([, f]) => f.kind === 'title');
+    if (titles.length > 1)
+        console.warn(`[shelf] ${m.library}/${m.shelf}: ${titles.length} title fields (${titles.map(([k]) => k).join(', ')}) — '${titles[0][0]}' wins`);
+    if (m.standalone !== false && !m.single && titleKey(m) === 'id')
+        console.warn(`[shelf] ${m.library}/${m.shelf}: no title declared (field.title() or views.title) — the record renders no heading`);
+    const known = derivableKeys(m.fields);
+    for (const [key, spec] of derivedEntries(m.fields)) {
+        for (const dep of spec.deps) {
+            if (!known.has(dep))
+                throw new Error(`[defineShelf] ${m.library}/${m.shelf}: derive on '${key}' depends on unknown key '${dep}'`);
+        }
+    }
     return m;
 }
 export const SYSTEM_FIELDS = ['id', 'createdAt', 'updatedAt'];
+function ownFieldEntries(items) {
+    const out = [];
+    for (const it of items) {
+        if (isField(it))
+            out.push([it.key, it.type]);
+        else if (isGroup(it) && !isCollectionGroup(it) && !isEmbeddedGroup(it))
+            out.push(...ownFieldEntries(it.fields));
+    }
+    return out;
+}
 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';
+    const declared = ownFieldEntries(m.fields).find(([, f]) => f.kind === 'title');
+    return declared ? declared[0] : 'id';
 }
 export function recordTitle(m, record) {
     return String(record[titleKey(m)] ?? record['id'] ?? '');
@@ -128,13 +151,11 @@ export function inlineText(m, row) {
 }
 export function viewKeys(m) {
     const tk = titleKey(m);
-    const rest = m.views?.list?.fields?.length
-        ? realKeys(m, m.views.list.fields.filter((k) => k !== tk))
-        : [];
+    const rest = m.views?.list?.length ? realKeys(m, m.views.list.filter((k) => k !== tk)) : [];
     return [tk, ...rest];
 }
 export function listKind(m) {
-    return m.views?.list?.kind ?? 'table';
+    return m.views?.listKind ?? 'table';
 }
 const GROUPABLE_PRIMS = new Set(['select', 'checkbox', 'relation']);
 export function groupableFields(m) {
@@ -198,6 +219,10 @@ export function buildShape(fields, partial) {
         if (isField(it)) {
             if (it.type.virtual)
                 continue;
+            if (it.type.derive) {
+                shape[it.key] = z.never({ error: () => vmsg('derived') }).optional();
+                continue;
+            }
             shape[it.key] = partial ? it.type.zod.optional() : it.type.zod;
         }
         else if (isGroup(it)) {

package/dist/showcase.d.ts

@@ -0,0 +1,15 @@
+import type { Condition } from './condition.ts';
+export interface ShowcaseDef {
+    id: string;
+    library: string;
+    label: string;
+    icon: string;
+    source: {
+        library: string;
+        shelf: string;
+    };
+    filter: Condition;
+    columns: string[];
+    createDefaults?: Record<string, unknown>;
+}
+export declare function defineShowcase(s: ShowcaseDef): ShowcaseDef;

package/dist/showcase.js

@@ -0,0 +1,35 @@
+import { COMPILABLE_SCALAR_OPS, COMPILABLE_ARRAY_OPS } from "./condition.js";
+const COMPILABLE_OPS = new Set([...COMPILABLE_SCALAR_OPS, ...COMPILABLE_ARRAY_OPS]);
+function assertCompilableOps(cond, id) {
+    for (const [key, spec] of Object.entries(cond)) {
+        if (spec === undefined)
+            continue;
+        if (key === '$and' || key === '$or') {
+            for (const c of spec)
+                assertCompilableOps(c, id);
+            continue;
+        }
+        if (typeof spec === 'object' && spec !== null) {
+            for (const op of Object.keys(spec)) {
+                if (!COMPILABLE_OPS.has(op)) {
+                    throw new Error(`[showcase] ${id}: operator '${op}' on '${key}' does not compile to SQL`);
+                }
+            }
+        }
+    }
+}
+export function defineShowcase(s) {
+    if (!s.id)
+        throw new Error('[showcase] missing id');
+    if (!s.library)
+        throw new Error(`[showcase] ${s.id}: missing library`);
+    if (!s.source?.library || !s.source?.shelf)
+        throw new Error(`[showcase] ${s.id}: missing source library/shelf`);
+    if (!s.columns?.length)
+        throw new Error(`[showcase] ${s.id}: columns must not be empty`);
+    if (!s.filter || Object.keys(s.filter).length === 0) {
+        throw new Error(`[showcase] ${s.id}: filter must not be empty — an unfiltered showcase is the shelf itself`);
+    }
+    assertCompilableOps(s.filter, s.id);
+    return s;
+}

package/dist/users-shelf.js

@@ -5,7 +5,7 @@ export const USERS_SHELF = defineShelf({
     library: '',
     label: 'auth.usersTitle',
     icon: 'lucide:users',
-    views: { list: { fields: ['login', 'displayName', 'role', 'disabled'] } },
+    views: { title: 'login', list: ['displayName', 'role', 'disabled'] },
     fields: [
         field.string({ key: 'login', label: 'auth.fieldLogin' }),
         field.string({ key: 'displayName', label: 'auth.fieldDisplayName' }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/sdk",
-  "version": "2.2.1",
+  "version": "3.1.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -13,6 +13,14 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./derive": {
+      "types": "./dist/derive.d.ts",
+      "default": "./dist/derive.js"
+    },
+    "./showcase": {
+      "types": "./dist/showcase.d.ts",
+      "default": "./dist/showcase.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"