@coffer-org/sdk 3.2.0 → 3.4.0

package/dist/derive.d.ts

@@ -7,6 +7,7 @@ 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 derivedEntries(fields: LayoutEl[]): [string, DeriveFn][];
+export declare function legacyDeriveDeps(fields: LayoutEl[]): [string, string[]][];
+export declare function applyDerived(fields: LayoutEl[], record: Record<string, unknown>): Promise<Record<string, unknown>>;
 export declare function derivableKeys(fields: LayoutEl[]): Set<string>;

package/dist/derive.js

@@ -1,23 +1,35 @@
 import { isField, isGroup } from "./fields.js";
-export function derivedEntries(fields) {
+function topLevelFields(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));
-        }
+        if (isField(it))
+            out.push([it.key, it.type]);
+        else if (isGroup(it) && !it.key)
+            out.push(...topLevelFields(it.fields));
+    }
+    return out;
+}
+export function derivedEntries(fields) {
+    const out = [];
+    for (const [key, meta] of topLevelFields(fields)) {
+        const fn = meta.compute ?? meta.derive?.fn;
+        if (fn)
+            out.push([key, typeof fn === 'function' ? fn : () => fn]);
     }
     return out;
 }
-export function applyDerived(fields, record) {
+export function legacyDeriveDeps(fields) {
+    const out = [];
+    for (const [key, meta] of topLevelFields(fields))
+        if (meta.derive)
+            out.push([key, meta.derive.deps]);
+    return out;
+}
+export async function applyDerived(fields, record) {
     const out = {};
-    for (const [key, spec] of derivedEntries(fields)) {
+    for (const [key, fn] of derivedEntries(fields)) {
         try {
-            out[key] = spec.fn({ record });
+            out[key] = await fn({ record });
         }
         catch (e) {
             console.warn(`[derive] '${key}' threw`, e);

package/dist/extend.js

@@ -1,10 +1,11 @@
-import { layoutToClient, fieldEntries, buildShape } from "./shelf.js";
+import { layoutToClient, fieldEntries, buildShape, checkFieldDeclaration } from "./shelf.js";
 import { z } from 'zod';
 export function defineExtend(e) {
     const keys = fieldEntries(e.fields).map(([k]) => k);
     const dup = keys.find((k, i) => keys.indexOf(k) !== i);
     if (dup)
         throw new Error(`[extend] ${e.id}: duplicate key '${dup}'`);
+    checkFieldDeclaration(e.fields, `[extend] ${e.id}`);
     return e;
 }
 export function extendMatches(e, library, shelf) {

package/dist/fields/normalize.d.ts

@@ -50,6 +50,7 @@ export interface FieldConfig {
 export type NormalizedOpts = {
     key?: string;
     value?: unknown;
+    store?: boolean;
     label?: string;
     options?: string | unknown[];
     slots?: string[];

package/dist/fields.d.ts

@@ -2,11 +2,13 @@ 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';
+import { type PartsSpec, type ResolvedPart } from './parts.ts';
+export { partValueKey, partValueKeys, type PartSlot } from './parts.ts';
 export type { Rules, View, FieldConfig } from './fields/normalize.ts';
 export { normalizeOpts } from './fields/normalize.ts';
 import { type Rules, type View } from './fields/normalize.ts';
 import { presets } from './field-presets.ts';
-export type CorePrim = 'text' | 'number' | 'date' | 'time' | 'datetime' | 'checkbox' | 'select' | 'json' | 'check' | 'measured' | 'relation' | 'file' | 'per-weekday' | 'lookup';
+export type CorePrim = 'text' | 'number' | 'date' | 'time' | 'datetime' | 'checkbox' | 'select' | 'json' | 'check' | 'measured' | 'relation' | 'file' | 'per-weekday';
 export type Prim = CorePrim | (string & {});
 export type ColumnType = 'text' | 'integer' | 'real' | 'boolean' | 'date' | 'time' | 'datetime';
 export type OptionIcon = {
@@ -45,6 +47,9 @@ export interface ComputeCtx {
         library: string;
         shelf: string;
     };
+    self?: Record<string, unknown>;
+    parent?: Record<string, unknown>;
+    ref?: (key: string) => Promise<Record<string, unknown> | null>;
 }
 export type ComputeFn = (ctx: ComputeCtx) => unknown;
 export interface DividerEl {
@@ -104,6 +109,12 @@ export interface FieldClient {
     json?: true;
     derived?: true;
     columns?: Record<string, ColumnType>;
+    parts?: {
+        role: string;
+        key: string | null;
+        mode: string;
+        value?: unknown;
+    }[];
     hidden?: boolean | Condition;
 }
 export declare function group(o: {
@@ -175,6 +186,7 @@ export type FieldOptions = string | unknown[];
 export interface FieldCoreOpts {
     key?: string;
     value?: unknown;
+    store?: boolean;
     label?: string;
     rules?: Rules;
     view?: View;
@@ -195,12 +207,15 @@ export declare function wrapKey(opts: {
     emphasis?: 'hero' | 'muted';
     noLabel?: boolean;
     role?: 'cover' | 'avatar';
+    store?: boolean;
     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;
+    compute?: unknown;
+    parts?: ResolvedPart[];
 }
 export declare function isJsonStored(field: FieldMeta | FieldClient): boolean;
 export { LANGUAGES, SEX_OPTIONS, WEEKDAY_OPTIONS } from './fields/constants.ts';
@@ -423,6 +438,7 @@ export declare function check(o: CheckOpts & {
 }): FieldMeta;
 export interface MeasuredOpts extends FieldCoreOpts {
     options: FieldOptions;
+    parts?: PartsSpec;
 }
 export declare function measured(o: MeasuredOpts & {
     key: string;
@@ -456,7 +472,9 @@ export declare function amount(o: AmountOpts & {
     key?: undefined;
     value?: undefined;
 }): FieldMeta;
-export type MoneyOpts = FieldCoreOpts;
+export interface MoneyOpts extends FieldCoreOpts {
+    parts?: PartsSpec;
+}
 export declare function money(o: MoneyOpts & {
     key: string;
 }): FieldItem;
@@ -468,7 +486,9 @@ export declare function money(o: MoneyOpts & {
     key?: undefined;
     value?: undefined;
 }): FieldMeta;
-export type CodeFieldOpts = FieldCoreOpts;
+export interface CodeFieldOpts extends FieldCoreOpts {
+    parts?: PartsSpec;
+}
 export declare function code(o: CodeFieldOpts & {
     key: string;
 }): FieldItem;
@@ -480,7 +500,9 @@ export declare function code(o: CodeFieldOpts & {
     key?: undefined;
     value?: undefined;
 }): FieldMeta;
-export type GeoOpts = FieldCoreOpts;
+export interface GeoOpts extends FieldCoreOpts {
+    parts?: PartsSpec;
+}
 export declare function geo(o: GeoOpts & {
     key: string;
 }): FieldItem;
@@ -504,23 +526,10 @@ export declare function perWeekday(o: {
 export type RowSubField = FieldClient & {
     key: string;
 };
-export interface LookupOpts extends FieldCoreOpts {
-    from: string;
-    pick: string[];
-}
-export declare function lookup(o: LookupOpts & {
-    key: string;
-}): FieldItem;
-export declare function lookup(o: LookupOpts & {
-    value: unknown;
-    key?: undefined;
-}): StaticEl;
-export declare function lookup(o: LookupOpts & {
-    key?: undefined;
-    value?: undefined;
-}): FieldMeta;
 export declare function clientToMeta(fc: FieldClient): FieldMeta;
-type PeriodOpts = FieldCoreOpts;
+interface PeriodOpts extends FieldCoreOpts {
+    parts?: PartsSpec;
+}
 export declare function period(o: PeriodOpts & {
     key: string;
 }): FieldItem | GroupEl;
@@ -642,7 +651,9 @@ export interface KeyValueOpts extends FieldCoreOpts {
 export declare function keyValue(raw: KeyValueOpts & {
     key: string;
 }): GroupEl;
-export type RangeOpts = FieldCoreOpts;
+export interface RangeOpts extends FieldCoreOpts {
+    parts?: PartsSpec;
+}
 export declare function numberRange(o: RangeOpts & {
     key: string;
 }): FieldItem;
@@ -701,7 +712,6 @@ declare const PRIMITIVES: {
     money: typeof money;
     code: typeof code;
     geo: typeof geo;
-    lookup: typeof lookup;
     perWeekday: typeof perWeekday;
     period: typeof period;
     file: typeof file;

package/dist/fields.js

@@ -1,8 +1,10 @@
 import { z } from 'zod';
 import { resolveUnits } from "./units.js";
-import { isCurrencyCode } from "./currencies.js";
+import { isCurrencyCode, CURRENCY_CODES } from "./currencies.js";
 import { vmsg, reqErr, typeErr, reqTypeErr, jsonRefined, optionalize, jsonValue } from "./fields/validation.js";
 export { vmsg, reqErr, typeErr, reqTypeErr, jsonRefined, optionalize, jsonValue, decodeVmsg, validateField, } from "./fields/validation.js";
+import { resolveParts, partColumns, partsRowShape, partValueKey, partValueKeys, stripServerOwnedParts, } from "./parts.js";
+export { partValueKey, partValueKeys } from "./parts.js";
 export { normalizeOpts } from "./fields/normalize.js";
 import { normalizeOpts } from "./fields/normalize.js";
 import { presets } from "./field-presets.js";
@@ -127,8 +129,25 @@ export function wrapKey(opts, meta) {
         m = { ...m, default: opts.default };
     if (opts.hidden !== undefined)
         m = { ...m, hidden: opts.hidden };
+    if (opts.derive && opts.key && 'value' in opts && opts.value !== undefined)
+        throw new Error(`[wrapKey] '${opts.key}': both derive and value are set — they are two spellings of ` +
+            `"the server computes this field"; use value, the canonical spelling`);
     if (opts.derive)
         m = { ...m, derive: opts.derive, derived: true, hints: { ...m.hints, noEditControl: true } };
+    const computed = opts.key && 'value' in opts && opts.value !== undefined;
+    if (opts.derive && opts.store === false)
+        throw new Error(`[wrapKey] '${opts.key}': derive writes a column on every write, so store: false contradicts it; ` +
+            `spell the computation as \`value\` instead.`);
+    if (opts.store === false && !computed)
+        throw new Error(`[wrapKey] '${opts.key ?? '(keyless)'}': store: false needs key + value — it drops the COLUMN of a ` +
+            `computed field, so that the server recomputes it on every read. A field without \`value\` has ` +
+            `nothing to recompute; a field without \`key\` already stores nothing.`);
+    if (computed) {
+        m = { ...m, compute: opts.value, derived: true, hints: { ...m.hints, noEditControl: true } };
+        if (opts.store === false)
+            m = { ...m, virtual: true };
+        return { key: opts.key, type: m };
+    }
     if (opts.key)
         return { key: opts.key, type: m };
     if ('value' in opts && opts.value !== undefined)
@@ -595,6 +614,10 @@ export function check(raw) {
     };
     return wrapKey(o, meta);
 }
+const MEASURED_ROLES = (units) => [
+    { role: 'value', accepts: ['number'], fallback: () => real({}) },
+    { role: 'unit', accepts: ['select', 'relation'], fallback: () => select({ options: units }) },
+];
 export function measured(raw) {
     const o = normalizeOpts(raw);
     const required = o.required ?? false;
@@ -608,15 +631,16 @@ export function measured(raw) {
         numSchema = numSchema.min(cfg.min);
     if (cfg.max != null)
         numSchema = numSchema.max(cfg.max);
-    const rowSchema = z.object({
+    const parts = resolveParts(MEASURED_ROLES(o.options), o.parts);
+    const rowSchema = z.object(partsRowShape({
         value: numSchema,
         unit: z.string().refine((v) => units.some((u) => u.value === v), { message: vmsg('measured_unit') }),
-    });
-    const s = z.unknown().superRefine((raw, ctx) => {
+    }, parts, required !== true));
+    const s = z.unknown().transform((raw, ctx) => {
         const parsed = jsonValue(raw);
         if (typeof parsed === 'string') {
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('json') });
-            return;
+            return z.NEVER;
         }
         const r = rowSchema.safeParse(parsed);
         if (!r.success) {
@@ -632,7 +656,9 @@ export function measured(raw) {
                 code: z.ZodIssueCode.custom,
                 message: vmsgIssue ? vmsgIssue.message : vmsg('measured_structure'),
             });
+            return z.NEVER;
         }
+        return stripServerOwnedParts(r.data, parts);
     });
     const meta = {
         kind: 'measured',
@@ -646,7 +672,8 @@ export function measured(raw) {
             ...(cfg.max != null && { max: cfg.max }),
             ...(cfg.step != null && { step: cfg.step }),
         },
-        columns: { value: 'real', unit: 'text' },
+        columns: partColumns(parts),
+        parts,
         zod: optionalize(s, required),
     };
     return wrapKey(o, meta);
@@ -655,9 +682,7 @@ 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 s = z.string(reqErr()).refine((v) => units.some((u) => u.value === v), { message: vmsg('measured_unit') });
     const meta = {
         kind: 'unit',
         label: o.label ?? '',
@@ -690,6 +715,10 @@ export function amount(raw) {
     };
     return wrapKey(o, meta);
 }
+const MONEY_ROLES = [
+    { role: 'value', accepts: ['number'], fallback: () => real({}) },
+    { role: 'currency', accepts: ['select', 'relation'], fallback: () => select({ options: CURRENCY_CODES }) },
+];
 export function money(raw) {
     const o = normalizeOpts(raw);
     const required = o.required ?? false;
@@ -699,19 +728,23 @@ export function money(raw) {
         numSchema = numSchema.min(cfg.min);
     if (cfg.max != null)
         numSchema = numSchema.max(cfg.max);
-    const rowSchema = z.object({
+    const parts = resolveParts(MONEY_ROLES, o.parts);
+    const rowSchema = z.object(partsRowShape({
         value: numSchema,
         currency: z.string().refine(isCurrencyCode, { message: vmsg('money_currency') }),
-    });
-    const s = z.unknown().superRefine((raw, ctx) => {
+    }, parts, required !== true));
+    const s = z.unknown().transform((raw, ctx) => {
         const parsed = jsonValue(raw);
         if (typeof parsed === 'string') {
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('json') });
-            return;
+            return z.NEVER;
         }
         const r = rowSchema.safeParse(parsed);
-        if (!r.success)
+        if (!r.success) {
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('money_structure') });
+            return z.NEVER;
+        }
+        return stripServerOwnedParts(r.data, parts);
     });
     const meta = {
         kind: 'money',
@@ -724,24 +757,34 @@ export function money(raw) {
             ...(cfg.min != null && { min: cfg.min }),
             ...(cfg.max != null && { max: cfg.max }),
         },
-        columns: { value: 'real', currency: 'text' },
+        columns: partColumns(parts),
+        parts,
         zod: optionalize(s, required),
     };
     return wrapKey(o, meta);
 }
+const CODE_ROLES = [
+    { role: 'code', accepts: ['text'], fallback: () => string({}) },
+    { role: 'lang', accepts: ['text'], fallback: () => string({}) },
+];
 export function code(raw) {
     const o = normalizeOpts(raw);
     const required = o.required ?? false;
     const cfg = o.config ?? {};
-    const rowSchema = z.object({ code: z.string(), lang: z.string() });
-    const s = z.unknown().superRefine((raw, ctx) => {
+    const parts = resolveParts(CODE_ROLES, o.parts);
+    const rowSchema = z.object(partsRowShape({ code: z.string(), lang: z.string() }, parts, required !== true));
+    const s = z.unknown().transform((raw, ctx) => {
         const parsed = jsonValue(raw);
         if (typeof parsed === 'string') {
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('json') });
-            return;
+            return z.NEVER;
         }
-        if (!rowSchema.safeParse(parsed).success)
+        const r = rowSchema.safeParse(parsed);
+        if (!r.success) {
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('code_structure') });
+            return z.NEVER;
+        }
+        return stripServerOwnedParts(r.data, parts);
     });
     const base = {
         kind: 'code',
@@ -750,33 +793,48 @@ export function code(raw) {
         prim: 'code',
         column: 'text',
         hints: { ...(cfg.defaultLang && { defaultLang: cfg.defaultLang }) },
-        columns: { code: 'text', lang: 'text' },
+        columns: partColumns(parts),
+        parts,
         zod: optionalize(s, required),
     };
     return wrapKey(o, base);
 }
+const GEO_ROLES = [
+    { role: 'lat', accepts: ['number'], fallback: () => real({}) },
+    { role: 'lng', accepts: ['number'], fallback: () => real({}) },
+    { role: 'label', accepts: ['text'], fallback: () => string({}) },
+];
 export function geo(raw) {
     const o = normalizeOpts(raw);
     const required = o.required ?? false;
-    const rowSchema = z.object({
+    const parts = resolveParts(GEO_ROLES, o.parts);
+    const rowSchema = z.object(partsRowShape({
         lat: z.number().min(-90).max(90),
         lng: z.number().min(-180).max(180),
         label: z.string().nullish(),
-    });
-    const s = z.unknown().superRefine((raw, ctx) => {
+    }, parts, required !== true));
+    const clientCoordKeys = parts
+        .filter((p) => (p.role === 'lat' || p.role === 'lng') && p.mode === 'stored')
+        .map(partValueKey);
+    const s = z.unknown().transform((raw, ctx) => {
         const parsed = jsonValue(raw);
         const p = parsed;
-        if (p == null || (typeof p === 'object' && p.lat == null && p.lng == null)) {
+        const noCoords = p == null || (typeof p === 'object' && clientCoordKeys.length > 0 && clientCoordKeys.every((k) => p[k] == null));
+        if (noCoords) {
             if (required)
                 ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('required') });
-            return;
+            return raw;
         }
         if (typeof parsed === 'string') {
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('json') });
-            return;
+            return z.NEVER;
         }
-        if (!rowSchema.safeParse(parsed).success)
+        const r = rowSchema.safeParse(parsed);
+        if (!r.success) {
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('geo_structure') });
+            return z.NEVER;
+        }
+        return stripServerOwnedParts(r.data, parts);
     });
     const base = {
         kind: 'geo',
@@ -785,7 +843,8 @@ export function geo(raw) {
         prim: 'geo',
         column: 'text',
         hints: {},
-        columns: { lat: 'real', lng: 'real', label: 'text' },
+        columns: partColumns(parts),
+        parts,
         zod: optionalize(s, required),
     };
     return wrapKey(o, base);
@@ -802,23 +861,21 @@ export function perWeekday(o) {
         kind: 'per-weekday',
     };
 }
-export function lookup(raw) {
-    const o = normalizeOpts(raw);
-    const meta = {
-        kind: 'lookup',
-        label: o.label ?? '',
-        required: false,
-        prim: 'lookup',
-        column: 'text',
-        virtual: true,
-        hints: { from: o.from, pick: o.pick, compareWith: o.compareWith ?? null },
-        zod: z.any().optional(),
-    };
-    return wrapKey(o, meta);
-}
 export function clientToMeta(fc) {
-    return { ...fc, column: 'text', zod: z.any() };
-}
+    const { parts: _parts, ...rest } = fc;
+    return { ...rest, column: 'text', zod: z.any() };
+}
+function endpointReader(parts, keys) {
+    const pinned = new Map();
+    for (const p of parts)
+        if (p.mode === 'pinned')
+            pinned.set(p.role, p.value);
+    return (role, stored) => (pinned.has(role) ? pinned.get(role) : stored?.[keys[role]]);
+}
+const PERIOD_ROLES = (mkSub) => [
+    { role: 'from', accepts: ['date', 'datetime'], fallback: () => mkSub('from', 'core.period.from').type },
+    { role: 'until', accepts: ['date', 'datetime'], fallback: () => mkSub('until', 'core.period.until').type },
+];
 export function period(raw) {
     const o = normalizeOpts(raw);
     const granularity = (o.config?.granularity ?? 'day');
@@ -839,9 +896,13 @@ export function period(raw) {
     const fromField = mkSub('from', 'core.period.from');
     const untilField = mkSub('until', 'core.period.until');
     const subDefs = { from: fromField.type, until: untilField.type };
-    const rowShape = {};
+    const parts = resolveParts(PERIOD_ROLES(mkSub), o.parts);
+    const periodKeys = partValueKeys(parts);
+    const endpoint = endpointReader(parts, periodKeys);
+    const defaultShape = {};
     for (const [key, fm] of Object.entries(subDefs))
-        rowShape[key] = fm.zod.optional();
+        defaultShape[key] = fm.zod.optional();
+    const rowShape = partsRowShape(defaultShape, parts);
     let s = z.object(rowShape).passthrough();
     s = s.superRefine((val, ctx) => {
         if (val == null)
@@ -857,16 +918,18 @@ export function period(raw) {
         }
         const items = Array.isArray(parsed) ? parsed : [parsed];
         for (const item of items) {
-            const r = item;
-            if (r?.from && r?.until && String(r.from) > String(r.until))
+            const obj = item;
+            const r = obj != null && typeof obj === 'object' && !Array.isArray(obj) ? stripServerOwnedParts(obj, parts) : obj;
+            const f = endpoint('from', r);
+            const u = endpoint('until', r);
+            if (f && u && String(f) > String(u))
                 ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('period_order') });
         }
     });
-    const colType = granularity === 'datetime' ? 'datetime' : granularity === 'day' ? 'date' : 'text';
-    const subFields = [
-        { key: 'from', ...toClient(fromField.type) },
-        { key: 'until', ...toClient(untilField.type) },
-    ];
+    s = s.transform((val) => val != null && typeof val === 'object' && !Array.isArray(val)
+        ? stripServerOwnedParts(val, parts)
+        : val);
+    const subFields = parts.map((p) => ({ key: partValueKey(p), ...toClient(p.meta) }));
     const meta = {
         kind: 'period',
         label: o.label ?? '',
@@ -874,7 +937,8 @@ export function period(raw) {
         prim: 'period',
         column: 'text',
         hints: { fields: subFields, rowMultiple: false, unique: [], granularity },
-        columns: { from: colType, until: colType },
+        columns: partColumns(parts),
+        parts,
         zod: optionalize(s, required),
     };
     return wrapKey(o, meta);
@@ -978,35 +1042,46 @@ export function keyValue(raw) {
         required: o.required,
     });
 }
-function makeRange(kind, int, raw) {
+const RANGE_ROLES = (isInt) => [
+    { role: 'from', accepts: ['number'], fallback: () => (isInt ? int({}) : real({})) },
+    { role: 'to', accepts: ['number'], fallback: () => (isInt ? int({}) : real({})) },
+];
+function makeRange(kind, isInt, raw) {
     const o = normalizeOpts(raw);
     const required = o.required ?? false;
     const cfg = o.config ?? {};
     let n = z.number().finite();
-    if (int)
+    if (isInt)
         n = n.int({ message: vmsg('int') });
     if (cfg.min != null)
         n = n.min(cfg.min);
     if (cfg.max != null)
         n = n.max(cfg.max);
-    const rowSchema = z.object({ from: n, to: n });
-    const s = z.unknown().superRefine((raw, ctx) => {
+    const parts = resolveParts(RANGE_ROLES(isInt), o.parts);
+    const rangeKeys = partValueKeys(parts);
+    const rowSchema = z.object(partsRowShape({ from: n, to: n }, parts, required !== true));
+    const endpoint = endpointReader(parts, rangeKeys);
+    const s = z.unknown().transform((raw, ctx) => {
         if (typeof raw === 'string') {
             try {
                 JSON.parse(raw);
             }
             catch {
                 ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('json') });
-                return;
+                return z.NEVER;
             }
         }
         const r = rowSchema.safeParse(jsonValue(raw));
         if (!r.success) {
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('range_structure') });
-            return;
+            return z.NEVER;
         }
-        if (r.data.from > r.data.to)
+        const stored = stripServerOwnedParts(r.data, parts);
+        const fromV = endpoint('from', stored);
+        const toV = endpoint('to', stored);
+        if (fromV != null && toV != null && fromV > toV)
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('range_order') });
+        return stored;
     });
     const base = {
         kind,
@@ -1019,7 +1094,8 @@ function makeRange(kind, int, raw) {
             ...(cfg.max != null && { max: cfg.max }),
             ...(cfg.step != null && { step: cfg.step }),
         },
-        columns: int ? { from: 'integer', to: 'integer' } : { from: 'real', to: 'real' },
+        columns: partColumns(parts),
+        parts,
         zod: optionalize(s, required),
     };
     return wrapKey(o, base);
@@ -1082,7 +1158,6 @@ const PRIMITIVES = {
     money,
     code,
     geo,
-    lookup,
     perWeekday,
     period,
     file,
@@ -1122,6 +1197,24 @@ 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, derived } = field;
-    return { kind, label, required, prim, hints, options, relation, virtual, json, hidden, derived };
+    const { kind, label, required, prim, hints, options, relation, virtual, json, hidden, derived, parts } = field;
+    return {
+        kind,
+        label,
+        required,
+        prim,
+        hints,
+        options,
+        relation,
+        virtual,
+        json,
+        hidden,
+        derived,
+        parts: parts?.map((p) => ({
+            role: p.role,
+            key: p.key,
+            mode: p.mode,
+            ...(typeof p.value !== 'function' && p.value !== undefined && { value: p.value }),
+        })),
+    };
 }

package/dist/parts.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { type ColumnType, type FieldItem, type FieldMeta, type StaticEl } from './fields.ts';
+export interface RoleDef {
+    role: string;
+    accepts: string[];
+    fallback: () => FieldMeta;
+}
+export type PartInput = FieldItem | StaticEl | FieldMeta;
+export type PartsSpec = Record<string, PartInput>;
+export type PartMode = 'stored' | 'pinned' | 'computed' | 'computedStored';
+export interface ResolvedPart {
+    role: string;
+    key: string | null;
+    meta: FieldMeta;
+    mode: PartMode;
+    overridden: boolean;
+    value?: unknown;
+}
+export declare function partValueKey(p: PartSlot): string;
+export interface PartSlot {
+    role: string;
+    key: string | null;
+}
+export declare function partValueKeys(parts: PartSlot[]): Record<string, string>;
+export declare function resolveParts(roles: RoleDef[], spec: PartsSpec | undefined): ResolvedPart[];
+export declare function partColumns(parts: ResolvedPart[]): Record<string, ColumnType>;
+export declare function partsRowShape(shape: Record<string, z.ZodTypeAny>, parts: ResolvedPart[], tolerateNull?: boolean): Record<string, z.ZodTypeAny>;
+export declare function mixedOwnedStoredParts(parts: ResolvedPart[]): {
+    server: string[];
+    client: string[];
+} | null;
+export declare function mandatedClientParts(required: unknown, parts: ResolvedPart[]): string[];
+export declare function stripServerOwnedParts(value: Record<string, unknown>, parts: ResolvedPart[]): Record<string, unknown>;

package/dist/parts.js

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { isField, isStatic } from "./fields.js";
+export function partValueKey(p) {
+    return p.key ?? p.role;
+}
+export function partValueKeys(parts) {
+    const out = {};
+    for (const p of parts)
+        out[p.role] = partValueKey(p);
+    return out;
+}
+const NUMERIC_LIKE = /^\d+$/;
+function readInput(input) {
+    if (isField(input)) {
+        const it = input;
+        return { key: it.key, meta: it.type, value: it.type.compute };
+    }
+    if (isStatic(input)) {
+        const el = input;
+        return { key: null, meta: el.type, value: el.value };
+    }
+    return { key: null, meta: input, value: undefined };
+}
+function modeOf(key, value) {
+    if (key && value !== undefined)
+        return 'computedStored';
+    if (key)
+        return 'stored';
+    return typeof value === 'function' ? 'computed' : 'pinned';
+}
+export function resolveParts(roles, spec) {
+    const known = new Set(roles.map((r) => r.role));
+    for (const name of Object.keys(spec ?? {})) {
+        if (NUMERIC_LIKE.test(name))
+            throw new Error(`parts: numeric-like role name '${name}' (object iteration would reorder the parts)`);
+        if (!known.has(name))
+            throw new Error(`parts: unknown role '${name}' (roles: ${[...known].join(', ')})`);
+    }
+    const out = [];
+    const usedKeys = new Set();
+    for (const def of roles) {
+        const input = spec?.[def.role];
+        const { key, meta, value } = input ? readInput(input) : { key: def.role, meta: def.fallback(), value: undefined };
+        if (!def.accepts.includes(meta.prim))
+            throw new Error(`parts: role '${def.role}' does not accept prim '${meta.prim}' (accepts: ${def.accepts.join(', ')})`);
+        const storageKey = key ?? (value === undefined ? def.role : null);
+        const mode = modeOf(storageKey, value);
+        if (storageKey && storageKey !== def.role && known.has(storageKey))
+            throw new Error(`parts: role '${def.role}' filling declares key '${storageKey}', which is another role of this composite — ` +
+                `a stored part's key must not collide with a role name (an unstored role occupies its role name in the ` +
+                `value object).`);
+        if (storageKey) {
+            if (usedKeys.has(storageKey))
+                throw new Error(`parts: duplicate storage key '${storageKey}'`);
+            usedKeys.add(storageKey);
+        }
+        out.push({
+            role: def.role,
+            key: storageKey,
+            meta,
+            mode,
+            overridden: input !== undefined,
+            ...(value !== undefined && { value }),
+        });
+    }
+    return out;
+}
+export function partColumns(parts) {
+    const cols = {};
+    for (const p of parts)
+        if (p.key)
+            cols[p.key] = p.meta.column;
+    return cols;
+}
+export function partsRowShape(shape, parts, tolerateNull = false) {
+    const out = { ...shape };
+    for (const p of parts)
+        if (partValueKey(p) !== p.role)
+            delete out[p.role];
+    for (const p of parts) {
+        if (!p.key)
+            out[p.role] = z.unknown().optional();
+        else if (p.mode === 'computedStored')
+            out[p.key] = z.unknown().optional();
+        else {
+            const own = p.overridden ? p.meta.zod : (shape[p.role] ?? z.unknown().optional());
+            out[p.key] = tolerateNull && !(p.overridden && p.meta.required === true) ? own.nullable() : own;
+        }
+    }
+    return out;
+}
+export function mixedOwnedStoredParts(parts) {
+    const server = parts.filter((p) => p.mode === 'computedStored').map((p) => p.role);
+    const client = parts.filter((p) => p.mode === 'stored').map((p) => p.role);
+    return server.length > 0 && client.length > 0 ? { server, client } : null;
+}
+export function mandatedClientParts(required, parts) {
+    const speaks = (flag) => flag !== undefined && flag !== false;
+    const field = speaks(required);
+    return parts
+        .filter((p) => p.mode === 'stored' && (field || (p.overridden && speaks(p.meta.required))))
+        .map((p) => p.role);
+}
+function serverOwnedSlot(p) {
+    if (!p.key)
+        return p.role;
+    return p.mode === 'computedStored' ? p.key : null;
+}
+export function stripServerOwnedParts(value, parts) {
+    let out = value;
+    for (const p of parts) {
+        const slot = serverOwnedSlot(p);
+        if (slot != null && slot in out) {
+            if (out === value)
+                out = { ...value };
+            delete out[slot];
+        }
+    }
+    return out;
+}

package/dist/shelf.d.ts

@@ -28,12 +28,14 @@ export interface ShelfDef {
 export declare function fieldEntries(items: LayoutEl[]): [string, FieldMeta][];
 export declare function storageColumns(key: string, field: FieldMeta): [string, ColumnType][];
 export declare function cellValue(field: FieldMeta, key: string, row: Record<string, unknown>): unknown;
+export declare function magnitudeSub(field: FieldMeta): string | undefined;
 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 checkFieldDeclaration(fields: LayoutEl[], owner: string): void;
 export declare function defineShelf(m: ShelfDef): ShelfDef;
 export declare const SYSTEM_FIELDS: readonly ["id", "createdAt", "updatedAt"];
 export declare function titleKey(m: ShelfDef): string;

package/dist/shelf.js

@@ -3,7 +3,8 @@ import { toClient, isField, isGroup, isStatic, isCollectionGroup, isEmbeddedGrou
 import { resolveFlag } from "./condition.js";
 import { parseUrl } from "./fields/url.js";
 import { vmsg } from "./fields/validation.js";
-import { derivedEntries, derivableKeys } from "./derive.js";
+import { derivableKeys, legacyDeriveDeps } from "./derive.js";
+import { mixedOwnedStoredParts, mandatedClientParts } from "./parts.js";
 export function fieldEntries(items) {
     const out = [];
     for (const it of items) {
@@ -34,14 +35,21 @@ export function cellValue(field, key, row) {
     const out = {};
     let filled = false;
     for (const sub of Object.keys(field.columns)) {
-        const v = row[`${key}__${sub}`];
-        if (v == null || v === '')
+        const col = `${key}__${sub}`;
+        if (!(col in row))
             continue;
+        const v = row[col];
         out[sub] = v;
-        filled = true;
+        if (v != null && v !== '')
+            filled = true;
     }
     return filled ? out : undefined;
 }
+export function magnitudeSub(field) {
+    if (!field.columns)
+        return undefined;
+    return Object.keys(field.columns)[0];
+}
 export function collectionGroups(items) {
     const out = [];
     for (const it of items) {
@@ -65,6 +73,41 @@ export function fieldMap(items) {
     }
     return m;
 }
+function assertNoKeylessCompute(items, owner) {
+    for (const it of items) {
+        if (isStatic(it) && typeof it.value === 'function')
+            throw new Error(`${owner}: computed element needs a key — the server computes it and needs a name to return it under`);
+        if (isGroup(it))
+            assertNoKeylessCompute(it.fields, owner);
+    }
+}
+function warnMixedOwnedParts(items, owner, path = '') {
+    for (const it of items) {
+        if (isGroup(it)) {
+            warnMixedOwnedParts(it.fields, owner, it.key ? `${path}${it.key}.` : path);
+            continue;
+        }
+        if (!isField(it) || !it.type.parts)
+            continue;
+        const mixed = mixedOwnedStoredParts(it.type.parts);
+        if (!mixed)
+            continue;
+        const mandated = mandatedClientParts(it.type.required, it.type.parts);
+        if (!mandated.length)
+            continue;
+        console.warn(`${owner}: composite '${path}${it.key}' mandates a client-owned stored part (${mandated.join(', ')}) ` +
+            `and mixes it with a server-owned stored part (${mixed.server.join(', ')}) — ` +
+            `a mandated part is the client's to declare, so the write path does NOT materialize this composite ` +
+            `and the computed part stays absent until a client sends the field. Either drop \`required\` ` +
+            `(from the field or from the ${mandated.join('/')} filling), or give every stored part a \`value\` ` +
+            `(the composite becomes fully server-owned), or drop the \`key\` of ` +
+            `${mixed.client.join('/')} so it is unstored (pinned/computed and injected on read).`);
+    }
+}
+export function checkFieldDeclaration(fields, owner) {
+    assertNoKeylessCompute(fields, owner);
+    warnMixedOwnedParts(fields, owner);
+}
 export function defineShelf(m) {
     const keys = fieldEntries(m.fields).map(([k]) => k);
     const dup = keys.find((k, i) => keys.indexOf(k) !== i);
@@ -86,9 +129,10 @@ export function defineShelf(m) {
         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`);
+    checkFieldDeclaration(m.fields, `[shelf] ${m.library}/${m.shelf}`);
     const known = derivableKeys(m.fields);
-    for (const [key, spec] of derivedEntries(m.fields)) {
-        for (const dep of spec.deps) {
+    for (const [key, deps] of legacyDeriveDeps(m.fields)) {
+        for (const dep of deps) {
             if (!known.has(dep))
                 throw new Error(`[defineShelf] ${m.library}/${m.shelf}: derive on '${key}' depends on unknown key '${dep}'`);
         }

package/dist/showcase.d.ts

@@ -10,6 +10,7 @@ export interface ShowcaseDef {
     };
     filter: Condition;
     columns: string[];
+    defaultGroupBy?: string;
     createDefaults?: Record<string, unknown>;
 }
 export declare function defineShowcase(s: ShowcaseDef): ShowcaseDef;

package/package.json

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