@coffer-org/sdk 3.1.0 → 3.3.0

package/dist/condition.d.ts

@@ -19,9 +19,11 @@ export interface 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 const COMPILABLE_MEMBER_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 conditionOps(cond: Condition | undefined, field: string): string[];
 export declare function visibleOptions<T extends {
     value?: string;
     when?: Condition;

package/dist/condition.js

@@ -1,6 +1,7 @@
 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']);
+export const COMPILABLE_MEMBER_OPS = new Set(['$contains']);
 const createEqualsOperation = sift
     .createEqualsOperation;
 const isScalar = (v) => typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
@@ -80,6 +81,27 @@ export function conditionKeys(cond) {
     }
     return [...new Set(out)];
 }
+export function conditionOps(cond, field) {
+    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(...conditionOps(c, field));
+            continue;
+        }
+        if (key !== field)
+            continue;
+        if (typeof spec === 'object' && spec !== null && !Array.isArray(spec))
+            out.push(...Object.keys(spec));
+        else
+            out.push('$eq');
+    }
+    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));

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/fields.d.ts

@@ -2,6 +2,8 @@ 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';
@@ -45,6 +47,7 @@ export interface ComputeCtx {
         library: string;
         shelf: string;
     };
+    self?: Record<string, unknown>;
 }
 export type ComputeFn = (ctx: ComputeCtx) => unknown;
 export interface DividerEl {
@@ -104,6 +107,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: {
@@ -201,6 +210,8 @@ 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 +434,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 +468,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 +482,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 +496,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;
@@ -520,7 +538,9 @@ export declare function lookup(o: LookupOpts & {
     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 +662,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;

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,15 @@ 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 } };
+    if (opts.key && 'value' in opts && opts.value !== undefined) {
+        m = { ...m, compute: opts.value, derived: true, hints: { ...m.hints, noEditControl: 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 +604,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 +621,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));
+    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 +646,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 +662,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);
@@ -690,6 +707,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 +720,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));
+    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 +749,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));
+    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 +785,49 @@ 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));
+    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 +836,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);
@@ -817,8 +869,20 @@ export function lookup(raw) {
     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 +903,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 +925,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 +944,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 +1049,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));
+    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 +1101,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);
@@ -1122,6 +1205,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,28 @@
+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[]): Record<string, z.ZodTypeAny>;
+export declare function stripServerOwnedParts(value: Record<string, unknown>, parts: ResolvedPart[]): Record<string, unknown>;

package/dist/parts.js

@@ -0,0 +1,106 @@
+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) {
+    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
+            out[p.key] = p.overridden ? p.meta.zod : (shape[p.role] ?? z.unknown().optional());
+    }
+    return out;
+}
+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.js

@@ -3,7 +3,7 @@ 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";
 export function fieldEntries(items) {
     const out = [];
     for (const it of items) {
@@ -65,6 +65,14 @@ export function fieldMap(items) {
     }
     return m;
 }
+function assertNoKeylessCompute(items, m) {
+    for (const it of items) {
+        if (isStatic(it) && typeof it.value === 'function')
+            throw new Error(`${m.library}/${m.shelf}: computed element needs a key — the server computes it and needs a name to return it under`);
+        if (isGroup(it))
+            assertNoKeylessCompute(it.fields, m);
+    }
+}
 export function defineShelf(m) {
     const keys = fieldEntries(m.fields).map(([k]) => k);
     const dup = keys.find((k, i) => keys.indexOf(k) !== i);
@@ -86,9 +94,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`);
+    assertNoKeylessCompute(m.fields, m);
     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/dist/showcase.js

@@ -1,5 +1,9 @@
-import { COMPILABLE_SCALAR_OPS, COMPILABLE_ARRAY_OPS } from "./condition.js";
-const COMPILABLE_OPS = new Set([...COMPILABLE_SCALAR_OPS, ...COMPILABLE_ARRAY_OPS]);
+import { COMPILABLE_SCALAR_OPS, COMPILABLE_ARRAY_OPS, COMPILABLE_MEMBER_OPS } from "./condition.js";
+const COMPILABLE_OPS = new Set([
+    ...COMPILABLE_SCALAR_OPS,
+    ...COMPILABLE_ARRAY_OPS,
+    ...COMPILABLE_MEMBER_OPS,
+]);
 function assertCompilableOps(cond, id) {
     for (const [key, spec] of Object.entries(cond)) {
         if (spec === undefined)

package/package.json

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