@coffer-org/plugin-transit 7.0.1 → 7.1.0

package/dist/bus_route/index.js

@@ -15,9 +15,9 @@ export default defineShelf({
         from: field.string({ label: 'transit.bus_route.fields.from', rules: { max: 100 }, ui: { span: 3 } }),
         to: field.string({ label: 'transit.bus_route.fields.to', rules: { max: 100 }, ui: { span: 3 } }),
         stop: field.string({ label: 'transit.bus_route.fields.stop', rules: { max: 200 }, ui: { span: 3 } }),
-        weekday_times: field.time({ label: 'transit.bus_route.fields.weekday_times', multiple: true, ui: { span: 12 } }),
-        saturday_times: field.time({ label: 'transit.bus_route.fields.saturday_times', multiple: true, ui: { span: 6 } }),
-        sunday_times: field.time({ label: 'transit.bus_route.fields.sunday_times', multiple: true, ui: { span: 6 } }),
+        weekday_times: field.timetable({ label: 'transit.bus_route.fields.weekday_times', ui: { span: 12 } }),
+        saturday_times: field.timetable({ label: 'transit.bus_route.fields.saturday_times', ui: { span: 6 } }),
+        sunday_times: field.timetable({ label: 'transit.bus_route.fields.sunday_times', ui: { span: 6 } }),
         tags: field.tags({ label: 'transit.bus_route.fields.tags' }),
         notes: field.text({ label: 'transit.bus_route.fields.notes', rules: { max: 500 } }),
     },

package/dist/schema.js

@@ -4701,6 +4701,13 @@ function wrapKey(key, opts, meta) {
 			span: opts.span
 		}
 	};
+	if (opts.faces !== void 0) m = {
+		...m,
+		hints: {
+			...m.hints,
+			faces: opts.faces
+		}
+	};
 	if (opts.default !== void 0) m = {
 		...m,
 		default: opts.default
@@ -4800,6 +4807,7 @@ function normalizeOpts(rawIn) {
 		...v.valueLabel !== void 0 ? { valueLabel: v.valueLabel } : {},
 		compareWith: v.compareWith,
 		span: v.span,
+		faces: v.faces,
 		emphasis: v.emphasis,
 		noLabel: v.noLabel,
 		role: v.role,
@@ -5708,6 +5716,63 @@ registerPreset("slug", "string", {}, {
 		};
 	}
 });
+/**
+* Identifier — a code printed for a machine and read back by one: a serial number, an order
+* number, a policy number, an IMEI. What a person actually DOES with one is copy it, which is
+* why this is a type of its own and not `f.string({ ui: { voice: 'data' } })`: the machine face
+* is one word on any string now, but the click that copies belongs to the kind.
+*
+* Deliberately unvalidated beyond a length: an identifier's format belongs to whoever issued
+* it, and a pattern here would reject the next manufacturer's.
+*
+* @layer   preset
+* @base    string
+* @prim    text
+* @widget  identifier
+* @example f.identifier({ label: 'mod.fields.serialNumber' })
+*/
+function identifier(o) {
+	return declare("identifier", o);
+}
+registerPreset("identifier", "string", {}, {
+	kind: "identifier",
+	widget: "identifier",
+	build() {
+		return {
+			column: "text",
+			zod: string$1(),
+			hints: {}
+		};
+	}
+});
+/**
+* The machine-readable zone of a travel document — the identifier taken to its limit: printed
+* for a scanner, not for a person. Fixed pitch, chevrons kept as the filler they are, and the
+* line breaks preserved, because an MRZ's line structure is part of what it encodes.
+*
+* Unvalidated on purpose, like `identifier`: the ICAO line formats differ by document type, and
+* a strip transcribed from a real document is worth storing even when it does not check out.
+*
+* @layer   preset
+* @base    string
+* @prim    text
+* @widget  mrz
+* @example f.mrz({ label: 'documents.personal_document.fields.mrz' })
+*/
+function mrz(o) {
+	return declare("mrz", o);
+}
+registerPreset("mrz", "string", {}, {
+	kind: "mrz",
+	widget: "mrz",
+	build() {
+		return {
+			column: "text",
+			zod: string$1(),
+			hints: {}
+		};
+	}
+});
 var COLOR_RE = /^#[0-9a-fA-F]{6}$/;
 /**
 * Hex color — kind 'color', `#rrggbb` + swatch widget.
@@ -5992,6 +6057,38 @@ registerPreset("tag", "string", {}, {
 	}
 });
 /**
+* A location written the way it is said aloud: workshop › shelf 2 › box. A `string` fixed to
+* `multiple`, exactly as `f.tags` is, because a place inside a place inside a place IS a
+* sequence — the plurality is the type, not a modifier someone remembered to add.
+*
+* Distinct from `f.tags`, which stores the same shape: tags are an unordered SET, and a path is
+* an ordered CHAIN where each step is inside the one before it. Drawn as chips, that
+* containment — the only thing the value actually carries — is lost.
+*
+* @layer   preset
+* @base    string
+* @prim    text
+* @widget  path
+* @example f.path({ label: 'things.storage_location.fields.path' })
+*/
+function path(o) {
+	return declare("path", {
+		...o,
+		multiple: true
+	});
+}
+registerPreset("path", "string", {}, {
+	kind: "path",
+	widget: "path",
+	build() {
+		return {
+			column: "text",
+			zod: string$1(),
+			hints: {}
+		};
+	}
+});
+/**
 * Tags — `tag({ multiple: true })`.
 *
 * @layer   preset
@@ -6184,6 +6281,34 @@ registerPreset("reminder", "date", { lead: 30 }, {
 		};
 	}
 });
+/** Timetable — a set of times of day, read as a schedule rather than as a bag of values.
+* kind 'timetable', prim 'time', always `multiple`.
+*
+* Same shape as `f.reminder`/`f.age` over `date`: a semantic type whose renderer knows what
+* the values MEAN. Everything it shows beyond the times themselves — when the service starts
+* and ends, how many runs there are, which one is next — is derived from the values at render
+* time, never stored: a "next departure" is wrong the moment it is written down, exactly the
+* argument `f.age` already makes for an age.
+*
+* Storage is a plain multiple `time`, so a field can be switched to this from
+* `f.time({ multiple: true })` and back with no migration.
+*
+* @layer   preset
+* @base    time
+* @prim    time
+* @widget  timetable
+* @example f.timetable({ label: 'mod.fields.weekdays' })
+*/
+function timetable(o) {
+	return declare("timetable", {
+		...o,
+		multiple: true
+	});
+}
+registerPreset("timetable", "time", {}, {
+	kind: "timetable",
+	widget: "timetable"
+});
 /** Age — date whose whole-year age (as of today) renders alongside it, e.g. a birth date.
 * kind 'age', prim 'date'. The age itself is computed at RENDER time, never stored: unlike a
 * `mutate`-driven computed field, it must be right on every day that passes, not only the day
@@ -6398,6 +6523,9 @@ var presets = {
 	email,
 	tel,
 	slug,
+	path,
+	identifier,
+	mrz,
 	color,
 	colorname,
 	title,
@@ -6412,6 +6540,7 @@ var presets = {
 	duration,
 	reminder,
 	age,
+	timetable,
 	percent,
 	year,
 	weight,
@@ -7069,26 +7198,38 @@ function identity(opts) {
 		}
 	};
 }
-/** A scored value out of an optional max, with an optional verdict.
+/** One measure out of an optional max, from ONE OR MORE named sources, with an optional verdict.
+*
+* `source` takes several entries for the same reason `f.identity`'s `channels` does — it is a
+* role that holds a LIST, so `view.source` is an ordered list of names rather than one name.
+* Two ratings of the same film out of ten are one measure read twice, and drawing them apart is
+* what makes them incomparable: the eye has to carry the scale between two figures instead of
+* reading them against a shared one. `media/title` had exactly that, two `f.score` blocks of
+* `max: 10` held apart inside an `f.compare`, until this took the restriction off.
+*
+* NOT `multiple`. A multiple field is an anonymous array; these are NAMED sources, and the name
+* is what says which reading came from where. The two are different shapes and the block wants
+* this one.
 *
 * @layer   block
 * @base    group
 * @prim    —
 * @widget  score
-* @example f.score({ source: { value: f.real({ label: '…' }) }, max: 100, verdict: { verdict: f.string({ label: '…' }) } })
+* @example f.score({ source: { imdb: f.real({ label: '…' }), tmdb: f.real({ label: '…' }) }, max: 10 })
 */
 function score(opts) {
-	const source = slot("score", "source", opts.source);
+	const names = Object.keys(opts.source ?? {});
+	if (names.length === 0) throw new Error(`[field.score] slot 'source' expects at least one entry, got 0`);
 	const verdict = opts.verdict !== void 0 ? slot("score", "verdict", opts.verdict) : void 0;
 	return {
 		...group({
 			label: opts.label,
-			fields: merge("score", source, verdict),
+			fields: merge("score", opts.source, verdict),
 			ui: { kind: "score" }
 		}),
 		view: {
 			kind: "score",
-			source: Object.keys(source)[0],
+			source: names,
 			max: opts.max,
 			verdict: verdict && Object.keys(verdict)[0]
 		}
@@ -7210,6 +7351,11 @@ function balance(opts) {
 * @base    group
 * @prim    —
 * @widget  route
+* A `stub` is the part of the ticket that is TORN OFF and kept — a seat, a gate, a booking
+* reference. Declaring one makes the block a ticket rather than a line: the two halves are
+* separated by a perforation, and the fields in the stub sit below it. Without one the block
+* is exactly what it was, a route from here to there, so no existing call changes.
+*
 * @example f.route({ from: { from: f.string({ label: '…' }) }, to: { to: f.string({ label: '…' }) } })
 */
 function route(opts) {
@@ -7218,9 +7364,10 @@ function route(opts) {
 	const depart = opts.depart !== void 0 ? slot("route", "depart", opts.depart) : void 0;
 	const arrive = opts.arrive !== void 0 ? slot("route", "arrive", opts.arrive) : void 0;
 	const duration = opts.duration !== void 0 ? slot("route", "duration", opts.duration) : void 0;
+	const stub = opts.stub ?? {};
 	return {
 		...group({
-			fields: merge("route", from, to, depart, arrive, duration),
+			fields: merge("route", from, to, depart, arrive, duration, stub),
 			ui: { kind: "route" }
 		}),
 		view: {
@@ -7229,7 +7376,8 @@ function route(opts) {
 			to: Object.keys(to)[0],
 			depart: depart && Object.keys(depart)[0],
 			arrive: arrive && Object.keys(arrive)[0],
-			duration: duration && Object.keys(duration)[0]
+			duration: duration && Object.keys(duration)[0],
+			stub: Object.keys(stub)
 		}
 	};
 }
@@ -7407,6 +7555,81 @@ function specimen(opts) {
 	};
 }
 /**
+* Measurements against the range they were supposed to fall in, rendered from a single
+* collection source — see `stampCollection`. `analyte`, `value`, `unit`, `low` and `high` are
+* part KEYS inside each collection row, NOT `LayoutEl` positions — the same reasoning as
+* `manifest`'s `quantity`/`item`.
+*
+* The point is the COMPARISON. A `f.table` over the same rows prints the bounds as two more
+* columns and leaves the reader to do it; here each value sits on its own band with the
+* reference span marked on it, so "outside the range" is seen rather than worked out. That is
+* also the only thing on the row worth a colour — it is what the reader has to act on.
+*
+* `unit`, `low` and `high` are optional: a measurement with no published range (a culture, a
+* description) still belongs in the same list and simply gets no band.
+*
+* @layer   block
+* @base    group
+* @prim    —
+* @widget  assay
+* @example f.assay({ source: { results: f.group({ scope: 'nest', multiple: true, fields: { analyte: f.string({ label: '…' }), value: f.real({ label: '…' }) } }) }, analyte: 'analyte', value: 'value' })
+*/
+function assay(opts) {
+	return stampCollection("assay", opts.source, opts.label, {
+		kind: "assay",
+		analyte: opts.analyte,
+		value: opts.value,
+		...opts.unit ? { unit: opts.unit } : {},
+		...opts.low ? { low: opts.low } : {},
+		...opts.high ? { high: opts.high } : {}
+	});
+}
+/**
+* Value moving from one place to another, where the MOVEMENT is the subject — not one more
+* labelled row among the record's fields. The sum is set large in the machine voice, and the two
+* ends read as a path beneath it.
+*
+*   amount — what moved. The one required role, and the reason the block exists
+*   from   — where it left. Absent on money that only arrived
+*   to     — where it arrived. Absent on money that only left
+*   meta   — the record's own remaining fields, under a rule: date, category, reference
+*
+* An absent end is not drawn, and that is the whole reading: money that left an account and
+* arrived nowhere IS an expense. It is read off which ends the record actually has, never
+* guessed from the shape of a value. What the movement MEANS beyond that — whether this
+* particular kind of transfer is good news — is carried by the classifier's own option `tone`,
+* the same declaration every other coloured value in the product uses.
+*
+* Distinct from `f.route`, which also has two ends: there the journey is the subject and the
+* ends are places, so it carries times and a duration; here the ends are accounts and the
+* subject is the quantity.
+*
+* @layer   block
+* @base    group
+* @prim    —
+* @widget  flow
+* @example f.flow({ amount: { amount: f.money({ label: '…' }) }, from: { source: f.relation({ label: '…' }) } })
+*/
+function flow(opts) {
+	const amount = slot("flow", "amount", opts.amount);
+	const from = opts.from !== void 0 ? slot("flow", "from", opts.from) : void 0;
+	const to = opts.to !== void 0 ? slot("flow", "to", opts.to) : void 0;
+	return {
+		...group({
+			label: opts.label,
+			fields: merge("flow", amount, from, to, opts.meta),
+			ui: { kind: "flow" }
+		}),
+		view: {
+			kind: "flow",
+			amount: Object.keys(amount)[0],
+			from: from && Object.keys(from)[0],
+			to: to && Object.keys(to)[0],
+			meta: Object.keys(opts.meta ?? {})
+		}
+	};
+}
+/**
 * A packing/cargo manifest rendered from a single collection source — see `stampCollection`.
 * `quantity` and `item` are part KEYS inside each collection row, NOT `LayoutEl` positions —
 * the same reasoning as `journal`'s `date`/`text`.
@@ -7453,13 +7676,25 @@ function table(opts) {
 		} : {},
 		...opts.groupBy ? { groupBy: opts.groupBy } : {},
 		...opts.totals ? { totals: opts.totals } : {},
+		...opts.summary ? { summary: opts.summary } : {},
 		...opts.numbered ? { numbered: true } : {}
 	});
 }
 /**
-* An ID-card header: an optional overline, a prominent number, and trailing meta fields.
-* `view` names each role (Task 5) — see `masthead`'s own doc comment for what `meta` means
-* as an ordered name list.
+* An identity document, drawn as the card it is: a caption and its number across the top, a
+* portrait beside the holder's own fields, the issuing details under a rule, and the
+* machine-readable strip at the foot. `view` names each role (Task 5) — see `masthead`'s own
+* doc comment for what an ordered name list means.
+*
+*   overline — the caption at the top left ("PASSPORT", "DRIVING LICENCE")
+*   number   — the document's number, set apart at the top right
+*   photo    — the portrait. One field, rendered in a portrait frame beside the body
+*   meta     — the card's OWN fields, labelled, at each field's declared span
+*   footer   — the fields below the rule: issued, authority, record number
+*   mrz      — the machine-readable strip, set in monospace at the foot
+*
+* Every role is optional but `number`: a bank card has no `mrz`, a library card no `photo`,
+* and the card simply omits the part it was given nothing for.
 *
 * @layer   block
 * @base    group
@@ -7470,16 +7705,21 @@ function table(opts) {
 function idcard(opts) {
 	const overline = opts.overline !== void 0 ? slot("idcard", "overline", opts.overline) : void 0;
 	const number = slot("idcard", "number", opts.number);
+	const photo = opts.photo !== void 0 ? slot("idcard", "photo", opts.photo) : void 0;
+	const mrz = opts.mrz !== void 0 ? slot("idcard", "mrz", opts.mrz) : void 0;
 	return {
 		...group({
-			fields: merge("idcard", overline, number, opts.meta),
+			fields: merge("idcard", overline, number, photo, opts.meta, opts.footer, mrz),
 			ui: { kind: "idcard" }
 		}),
 		view: {
 			kind: "idcard",
 			overline: overline && Object.keys(overline)[0],
 			number: Object.keys(number)[0],
-			meta: Object.keys(opts.meta ?? {})
+			photo: photo && Object.keys(photo)[0],
+			meta: Object.keys(opts.meta ?? {}),
+			footer: Object.keys(opts.footer ?? {}),
+			mrz: mrz && Object.keys(mrz)[0]
 		}
 	};
 }
@@ -7564,6 +7804,8 @@ var blocks = {
 	nutrition,
 	specimen,
 	manifest,
+	assay,
+	flow,
 	table,
 	idcard,
 	properties,
@@ -8426,6 +8668,11 @@ function group(o) {
 		for (const f of fields) if (!("key" in f && f.key !== void 0) && !hasChildren(f)) throw new Error(`[field.group] a 'nest' group's children must be fields or groups, not layout elements`);
 		for (const k of r.unique ?? []) if (!fields.some((f) => "key" in f && f.key === k)) throw new Error(`[field.group] unique key '${k}' is not a subfield`);
 	} else if (o.value !== void 0) throw new Error(`[field.group] value requires scope 'nest' — a hoist group owns no children to write`);
+	const title = v.title ?? [];
+	if (title.length > 0) {
+		if (!o.multiple) throw new Error(`[field.group] ui.title heads a collection's ROWS — it needs multiple: true`);
+		for (const name of title) if (!fields.some((f) => "key" in f && f.key === name)) throw new Error(`[field.group] ui.title '${name}' is not one of its fields`);
+	}
 	return {
 		el: "group",
 		scope,
@@ -8438,6 +8685,7 @@ function group(o) {
 		display: v.display ?? "wrap",
 		kind: v.kind,
 		fixed: r.fixed,
+		view: title.length > 0 ? { title } : void 0,
 		fields
 	};
 }
@@ -8607,6 +8855,31 @@ function info(textKey) {
 	};
 }
 /**
+* What else points AT this record — the inverse of a relation, which is often the more useful
+* direction on a record page: a box is more usefully "what is in it" than "what it is in".
+*
+* Stores NOTHING and has no column: it declares where to look, and the server answers by asking
+* the pointing shelf. That is why it is a pseudo-element beside `divider` and `info` rather than
+* a field — there is no value here to validate or save.
+*
+* `from` names the pointing side explicitly (which shelf, and WHICH of its fields), never
+* "everything that happens to point here": a shelf may point at the same target through two
+* fields — a transaction has a source account and a destination account — and a panel that
+* merged them would answer a question nobody asked.
+*
+* @layer   primitive
+* @prim    —
+* @widget  backrefs
+* @example f.backrefs({ label: 'mod.fields.storedHere', from: { library: 'things', shelf: 'item', field: 'location' } })
+*/
+function backrefs(o) {
+	return {
+		el: "backrefs",
+		label: o.label,
+		from: o.from
+	};
+}
+/**
 * Action button: invokes the handler registered in actionRegistry under the key `value`.
 *
 * @layer   primitive
@@ -8931,20 +9204,22 @@ registerType("time", {
 	prim: "time",
 	widget: "time",
 	build(o) {
-		const granularity = o.config?.granularity ?? "second";
+		const granularity = o.config?.granularity ?? "minute";
+		const s = string$1(reqErr()).regex({
+			hour: /^([01]\d|2[0-3])$/,
+			minute: /^([01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/,
+			second: /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/
+		}[granularity], { message: vmsg("time_format") });
 		return {
 			column: "time",
-			zod: string$1(reqErr()).regex({
-				hour: /^([01]\d|2[0-3])$/,
-				minute: /^([01]\d|2[0-3]):[0-5]\d$/,
-				second: /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/
-			}[granularity], { message: vmsg("time_format") }),
+			zod: granularity === "minute" ? s.transform((v) => v.slice(0, 5)) : s,
 			hints: { granularity }
 		};
 	}
 });
 /**
-* Time-of-day value with configurable granularity ('hour' | 'minute' | 'second', default 'second').
+* Time-of-day value with configurable granularity ('hour' | 'minute' | 'second', default
+* 'minute' — the same default `f.datetime` has always had).
 *
 * @layer   primitive
 * @prim    time
@@ -10189,7 +10464,8 @@ var PRIMITIVES = {
 	url,
 	divider,
 	info,
-	button
+	button,
+	backrefs
 };
 /** Assembles `f`, guaranteeing no preset/block shadows a primitive. */
 function composeF(presets, blocks) {
@@ -11091,19 +11367,16 @@ var bus_route_default = defineShelf({
 			rules: { max: 200 },
 			ui: { span: 3 }
 		}),
-		weekday_times: field.time({
+		weekday_times: field.timetable({
 			label: "transit.bus_route.fields.weekday_times",
-			multiple: true,
 			ui: { span: 12 }
 		}),
-		saturday_times: field.time({
+		saturday_times: field.timetable({
 			label: "transit.bus_route.fields.saturday_times",
-			multiple: true,
 			ui: { span: 6 }
 		}),
-		sunday_times: field.time({
+		sunday_times: field.timetable({
 			label: "transit.bus_route.fields.sunday_times",
-			multiple: true,
 			ui: { span: 6 }
 		}),
 		tags: field.tags({ label: "transit.bus_route.fields.tags" }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/plugin-transit",
-  "version": "7.0.1",
+  "version": "7.1.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -26,9 +26,9 @@
     "test": "node --import tsx/esm --test 'src/runtime/*.test.ts'"
   },
   "dependencies": {
-    "@coffer-org/sdk": "^7.2.0",
-    "@coffer-org/server": "^7.2.0",
-    "@coffer-org/helper-dav": "^7.0.0"
+    "@coffer-org/sdk": "^7.3.0",
+    "@coffer-org/server": "^7.3.0",
+    "@coffer-org/helper-dav": "^7.1.0"
   },
   "coffer": {
     "runtime": "node",