@coffer-org/sdk 2.2.1 → 3.0.0

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/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';
@@ -99,6 +100,7 @@ export interface FieldClient {
     virtual?: boolean;
     default?: string | number | boolean | null;
     json?: true;
+    derived?: true;
     columns?: Record<string, ColumnType>;
     hidden?: boolean | Condition;
 }
@@ -180,6 +182,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 +193,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';
@@ -427,6 +432,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 +693,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)
@@ -635,6 +637,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 +1063,8 @@ const PRIMITIVES = {
     json,
     check,
     measured,
+    unit,
+    amount,
     money,
     code,
     geo,
@@ -1065,6 +1108,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/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/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.0.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -13,6 +13,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./derive": {
+      "types": "./dist/derive.d.ts",
+      "default": "./dist/derive.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"