@jarenjs/forms 0.46.5 → 0.56.0

package/README.md

@@ -21,13 +21,13 @@ import {
 
 const schema = {
   type: 'object',
-  title: 'Sign up',
   properties: {
     username: { type: 'string', minLength: 3, pattern: '^[a-z0-9_]+$' },
     email: { type: 'string', format: 'email' },
     age: { type: 'integer', minimum: 13 },
   },
   required: ['username', 'email'],
+  title: 'Sign up',
 };
 
 // 1. Build the field tree once
@@ -90,6 +90,27 @@ stylesheet is the second kind of host, and the website's data studio the first.
 
 Which date formats get a **native** control is decided by the offset, not by convenience. HTML's `datetime-local` and `time` inputs cannot produce one, and RFC 3339 requires one — binding them to `date-time`/`time` would make the control emit values its own schema rejects, so those stay text inputs. The `iso-date-time`/`iso-time` formats leave the offset optional and are exactly what those inputs spell, so they map losslessly. `formatMinimum`/`formatMaximum` reach the field as constraints and become the control's `min`/`max`, so the picker itself refuses an out-of-range date; HTML has no exclusive date bounds, so `formatExclusive*` stays a submit-time check.
 
+### The same model, by code
+
+The schema above is what `@jarenjs/linq/forms` emits, byte for byte:
+
+```javascript
+import * as f from '@jarenjs/linq/forms';
+
+export const signup = f.object({
+  username: f.string().min(3).pattern('^[a-z0-9_]+$'),
+  email: f.string().format('email'),
+  age: f.integer().min(13).optional(),
+}).open().title('Sign up');
+
+const model = buildFormModel(signup.schema);
+```
+
+Every rule of the next section is a `.form({ … })` on the member it
+belongs to; the pen's document is
+[FORMS-PEN.md](../linq/docs/FORMS-PEN.md), and nothing in this package
+depends on it — the schema is the contract.
+
 ## Layer 1 — preemptive per-field validation
 
 `validateField(field, value)` returns `[{ keyword, message }]` using `@jarenjs/core` directly:
@@ -119,6 +140,16 @@ One namespaced annotation keyword — safe under every metaschema, invisible to
   } }
 ```
 
+These annotations can be **written by code**: `@jarenjs/linq/forms` is
+the schema pen plus `form({ visible, enabled, assert, computed,
+message })` on every builder, with the rules captured as callbacks over
+the same context (`c.root`, `c.value`, `c.pointer`) rather than typed
+as path strings, and `assertOnSubmit()` answering the layer-3 twin
+below in one call. The document above is what it emits, byte for byte
+— see [the by-code twin](#the-same-model-by-code) and
+[FORMS-PEN.md](../linq/docs/FORMS-PEN.md). This package depends on
+none of it; the annotation is the contract.
+
 Recognized members — unknown members are ignored for forward compatibility:
 
 | Member | Kind | Meaning |
@@ -259,6 +290,29 @@ const errors = validateAllFields(model, data, catalog);
 // errors['/name'][0].message === 'Dit veld is verplicht'
 ```
 
+### A format's name, in the reader's language
+
+A format's name is its wire name — `date-time`, `iso-time` — which is
+English by construction and reads as gibberish inside a translated
+sentence (*"Moet een geldige date-time zijn"*). A catalog that carries
+`format/name/<format>` says how that format is called in its own
+language, and `renderFormsMessage` swaps it in before `form/format`
+renders. The error's own `params.format` stays the raw wire name, so the
+same error re-rendered through a second catalog answers in *that*
+language rather than repeating the first one's noun:
+
+```javascript
+const error = validateField(whenField, 'nope', catalog)[0];
+error.message;       // 'Moet een geldige datum en tijd zijn'
+error.params.format; // 'date-time'
+formatDisplayName(catalog, 'email');  // 'email' — already a word
+```
+
+`@jarenjs/locales` carries the six date and time names in every pack; a
+format the catalog cannot name keeps its own, which is the readable
+answer for the names that are already words and the only possible one for
+a format nobody has heard of.
+
 ### MessageSpec in `x-form.message`
 
 A rule's `message` may be a plain string (backward compatible — an inline

package/dist/types/index.d.ts

@@ -15,7 +15,7 @@
 export { buildFormModel, resolveSchema, getFieldKind, humanizeKey, escapePointerKey, } from './model.js';
 export { compileFormRules, evaluateFormRules, formRulesToQueryAssertions, pruneHiddenValues, createRuleMemo, } from './rules.js';
 export { validateField, validateAllFields, } from './validate.js';
-export { formsMessagesEn, formChromeLabels, compileMessageTemplate, compileMessageCatalog, } from './messages.js';
+export { formsMessagesEn, formChromeLabels, formatDisplayName, compileMessageTemplate, compileMessageCatalog, } from './messages.js';
 export { createInitialData, createItemValue, parseFieldInput, parsePointer, getValueAtPointer, setValueAtPointer, appendItem, removeItemAt, } from './data.js';
 export { FORM_FORMATS, getFormatInfo, } from './formats.js';
 export { buildFormViewModel, } from './viewmodel.js';

package/dist/types/messages.d.ts

@@ -8,9 +8,37 @@ export { compileMessageTemplate, compileMessageCatalog, } from '@jarenjs/core/me
 export declare const formsMessagesEn: Record<string, string | ((params: object, error?: object) => string)>;
 /** The compiled built-in English catalog (module-level singleton). */
 export declare const formsMessages: Readonly<Record<string, (params: object, error?: object) => string>>;
+/**
+ * The display name of a format, as the catalog in hand spells it.
+ *
+ * A format's name is its wire name - `date-time`, `iso-time` - which is
+ * English by construction and reads as gibberish inside a translated
+ * sentence ("Moet een geldige date-time zijn"). A catalog that carries
+ * `format/name/<format>` says how that format is called in its own
+ * language; the date catalog of `@jarenjs/locales` carries the six date
+ * and time ones. A format the catalog has no name for keeps its own,
+ * which is the readable answer for the format names that are already
+ * words ("email", "hostname") and the only possible one for a format
+ * this repository has never heard of.
+ *
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>|undefined} catalog - A compiled catalog, or undefined for English
+ * @param {string} format - The format name
+ * @returns {string} The display name, or the format name itself
+ * @example
+ * formatDisplayName(dutch, 'date-time'); // 'datum en tijd'
+ * formatDisplayName(dutch, 'email');     // 'email'
+ */
+export declare function formatDisplayName(catalog: Readonly<Record<string, (params: object, error?: object) => string>> | undefined, format: string): string;
 /**
  * Resolve a message key through a caller catalog with built-in English
  * fallback and render it.
+ *
+ * A format failure is the one message whose params are prepared here
+ * rather than at the call site: the error's own `params.format` stays
+ * the raw wire name, so re-rendering the same error through a second
+ * catalog answers in that catalog's language instead of repeating the
+ * first one's noun.
+ *
  * @param {Readonly<Record<string, (params: object, error?: object) => string>>|undefined} catalog - A compiled catalog, or undefined for English
  * @param {string} msgid - The message key
  * @param {object} params - The structured params

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/forms",
   "private": false,
-  "version": "0.46.5",
+  "version": "0.56.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -47,9 +47,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.46.5",
-    "@jarenjs/formats": "^0.46.5",
-    "@jarenjs/json": "^0.46.5",
-    "@jarenjs/validate": "^0.46.5"
+    "@jarenjs/core": "^0.56.0",
+    "@jarenjs/formats": "^0.56.0",
+    "@jarenjs/json": "^0.56.0",
+    "@jarenjs/validate": "^0.56.0"
   }
 }

package/src/index.js

@@ -39,6 +39,7 @@ export {
 export {
   formsMessagesEn,
   formChromeLabels,
+  formatDisplayName,
   compileMessageTemplate,
   compileMessageCatalog,
 } from './messages.js';

package/src/messages.js

@@ -68,9 +68,47 @@ export const formsMessagesEn = {
 /** The compiled built-in English catalog (module-level singleton). */
 export const formsMessages = compileMessageCatalog(formsMessagesEn);
 
+/** Shared empty params for the entries that interpolate nothing. */
+const NO_PARAMS = Object.freeze({});
+
+/**
+ * The display name of a format, as the catalog in hand spells it.
+ *
+ * A format's name is its wire name - `date-time`, `iso-time` - which is
+ * English by construction and reads as gibberish inside a translated
+ * sentence ("Moet een geldige date-time zijn"). A catalog that carries
+ * `format/name/<format>` says how that format is called in its own
+ * language; the date catalog of `@jarenjs/locales` carries the six date
+ * and time ones. A format the catalog has no name for keeps its own,
+ * which is the readable answer for the format names that are already
+ * words ("email", "hostname") and the only possible one for a format
+ * this repository has never heard of.
+ *
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>|undefined} catalog - A compiled catalog, or undefined for English
+ * @param {string} format - The format name
+ * @returns {string} The display name, or the format name itself
+ * @example
+ * formatDisplayName(dutch, 'date-time'); // 'datum en tijd'
+ * formatDisplayName(dutch, 'email');     // 'email'
+ */
+export function formatDisplayName(catalog, format) {
+  if (typeof format !== 'string' || catalog === undefined) return format;
+  const render = catalog[`format/name/${format}`];
+  if (render === undefined) return format;
+  const name = render(NO_PARAMS);
+  return typeof name === 'string' && name !== '' ? name : format;
+}
+
 /**
  * Resolve a message key through a caller catalog with built-in English
  * fallback and render it.
+ *
+ * A format failure is the one message whose params are prepared here
+ * rather than at the call site: the error's own `params.format` stays
+ * the raw wire name, so re-rendering the same error through a second
+ * catalog answers in that catalog's language instead of repeating the
+ * first one's noun.
+ *
  * @param {Readonly<Record<string, (params: object, error?: object) => string>>|undefined} catalog - A compiled catalog, or undefined for English
  * @param {string} msgid - The message key
  * @param {object} params - The structured params
@@ -80,6 +118,10 @@ export function renderFormsMessage(catalog, msgid, params) {
   let render = catalog !== undefined ? catalog[msgid] : undefined;
   if (render === undefined) render = formsMessages[msgid];
   if (render === undefined) return msgid;
+  if (msgid === 'form/format') {
+    const format = formatDisplayName(catalog, /** @type {any} */ (params).format);
+    return render({ ...params, format });
+  }
   return render(params);
 }