@jarenjs/forms 0.9.2 → 0.34.0

package/src/model.js

@@ -10,10 +10,18 @@
  * validation (see validate.js).
  */
 
+import { isJsonObject } from '@jarenjs/core/object';
+import { createWeakCache } from '@jarenjs/core/cache';
 import {
-  compileJSONPointer,
-  JSONPOINTER_NOTHING,
-} from '@jarenjs/json/pointer';
+  NUMERIC_CONSTRAINTS, STRING_CONSTRAINTS,
+  ARRAY_CONSTRAINTS, OBJECT_CONSTRAINTS,
+} from '@jarenjs/core/schema';
+
+import { encodeJSONPointerSegment } from '@jarenjs/json/pointer';
+import {
+  collectSameDocumentAnchors,
+  resolveSameDocumentRef,
+} from '@jarenjs/validate/normalize';
 
 import {
   getFormatInfo,
@@ -25,14 +33,16 @@ const DEFAULT_MAX_DEPTH = 24;
  * @typedef {object} FormField
  * @property {string} pointer - JSON pointer into the DATA (e.g. '/user/name')
  * @property {string} key - Property name (or '-' for an array item template)
- * @property {string} label - Human friendly label (schema title or humanized key)
+ * @property {string} msgid - The field's message-id base: `x-msgid` annotation or the pointer (the root field's base is the empty pointer '')
+ * @property {string} label - Human friendly label (schema title or humanized key), through the `t` hook
  * @property {string|undefined} description
  * @property {object} schema - The resolved subschema for this field
  * @property {string} kind - 'string'|'number'|'integer'|'boolean'|'enum'|'const'|'object'|'array'|'unknown'
- * @property {string} control - Suggested control: 'text'|'email'|'url'|'password'|'textarea'|'number'|'checkbox'|'select'|'date'|'color'|'json'
+ * @property {string} control - Suggested control: 'text'|'email'|'url'|'password'|'textarea'|'number'|'checkbox'|'select'|'date'|'datetime-local'|'time'|'color'|'json'
  * @property {boolean} required - Whether the parent object requires this property
  * @property {boolean} readOnly
  * @property {Array<any>|null} enumValues - Options for a select control
+ * @property {Array<string>|null} enumLabels - Display labels parallel to enumValues (oneOf const/title idiom, through the `t` hook)
  * @property {any} constValue - Fixed value when the schema is a const
  * @property {any} defaultValue
  * @property {string|undefined} placeholder
@@ -43,8 +53,22 @@ const DEFAULT_MAX_DEPTH = 24;
  * @property {Array<FormField>|null} tuple - Fixed prefix fields for tuple arrays
  */
 
+/**
+ * The static-text translation hook: receives a role-qualified message id
+ * (`<base>#label`, `<base>#description`, `<base>#placeholder`,
+ * `<base>#enum/<value>`) and the schema-derived fallback text; returns
+ * the text to display.
+ * @typedef {(msgid: string, fallback: string|undefined, params?: object) => string|undefined} TranslateHook
+ */
+
+/** @type {TranslateHook} The zero-cost identity hook. */
+const identityT = (msgid, fallback) => fallback;
+
 /**
  * Convert 'firstName' / 'first_name' / 'first-name' to 'First Name'.
+ * Latin-script-oriented (word splitting on case/underscore/hyphen and
+ * ASCII capitalization); the `t` hook of buildFormModel is the override
+ * point for anything it mangles.
  * @param {string} key
  * @returns {string}
  */
@@ -59,24 +83,38 @@ export function humanizeKey(key) {
 }
 
 /**
- * Resolve a local JSON pointer ('#/$defs/foo') inside the root document
- * through the shared @jarenjs/json pointer walk (RFC 6901: the URI
- * fragment percent-decodes to the pointer text).
+ * Anchor maps per root schema, computed once and held exactly as long
+ * as the root object itself (`collectSameDocumentAnchors` walks the
+ * whole document — per-field recomputation would be quadratic).
+ */
+const ANCHOR_MAPS = createWeakCache();
+
+/**
+ * Resolve a same-document `$ref` — `#` (the root), `#/pointer`, or
+ * `#anchor` — with the validator's own exported resolver, so a form
+ * derives its model from exactly the schema the validator would
+ * enforce. (The previous private re-implementation resolved only
+ * `#/pointer`, silently rendering `$ref: "#"` and `#anchor` fields as
+ * `unknown`.) External refs stay unresolvable by design.
  * @param {string} ref
  * @param {object} rootSchema
  * @returns {object|boolean|null} The referenced schema or null when unresolvable
  */
 function resolveLocalRef(ref, rootSchema) {
-  if (typeof ref !== 'string' || !ref.startsWith('#/')) return null;
-  let pointer = ref.slice(1);
+  if (typeof ref !== 'string' || !ref.startsWith('#')) return null;
+  let fragment = ref;
   try {
-    if (pointer.indexOf('%') >= 0) pointer = decodeURIComponent(pointer);
-    const target = compileJSONPointer(pointer)(rootSchema);
-    return target === JSONPOINTER_NOTHING ? null : target;
+    if (fragment.indexOf('%') >= 0) fragment = decodeURIComponent(fragment);
   }
-  catch (e) {
+  catch (_e) {
     return null; // malformed fragment: same 'unresolvable' answer as a missing target
   }
+  const anchors = (rootSchema !== null && typeof rootSchema === 'object')
+    ? ANCHOR_MAPS.getOrCreate(rootSchema, collectSameDocumentAnchors)
+    : undefined;
+  const target = resolveSameDocumentRef(fragment, rootSchema,
+    /** @type {Map<string, object>|undefined} */ (anchors));
+  return target === undefined ? null : target;
 }
 
 /**
@@ -98,7 +136,7 @@ export function resolveSchema(schema, rootSchema, depth = 0) {
     if (target != null && typeof target === 'object') {
       const deref = resolveSchema(target, rootSchema, depth + 1);
       // 2019-09+: siblings apply together with the referenced schema
-      const { $ref, ...siblings } = schema;
+      const { $ref: _$ref, ...siblings } = schema;
       resolved = (deref && typeof deref === 'object')
         ? { ...deref, ...siblings }
         : deref;
@@ -130,6 +168,21 @@ export function resolveSchema(schema, rootSchema, depth = 0) {
   return resolved;
 }
 
+/**
+ * The `oneOf: [{const, title}, ...]` idiom: every branch an object with a
+ * `const`. Returns the branches, or null when the idiom does not apply.
+ * @param {object} schema
+ * @returns {Array<{const: any, title?: string}>|null}
+ */
+function getOneOfConstBranches(schema) {
+  if (!Array.isArray(schema.oneOf) || schema.oneOf.length === 0) return null;
+  for (const branch of schema.oneOf) {
+    if (branch == null || typeof branch !== 'object' || Array.isArray(branch)
+      || branch.const === undefined) return null;
+  }
+  return schema.oneOf;
+}
+
 /**
  * Derive the field kind from a resolved schema.
  * @param {object|boolean} schema
@@ -139,6 +192,8 @@ export function getFieldKind(schema) {
   if (schema == null || typeof schema !== 'object') return 'unknown';
   if (schema.const !== undefined) return 'const';
   if (Array.isArray(schema.enum)) return 'enum';
+  // The oneOf const/title idiom is an enum with per-option labels
+  if (getOneOfConstBranches(schema) !== null) return 'enum';
 
   let type = schema.type;
   if (Array.isArray(type)) {
@@ -195,14 +250,21 @@ function getControl(kind, schema) {
  * @param {object} schema
  * @returns {object}
  */
+/** The form-relevant constraint keywords: the shared groups plus the
+ * date bounds — constraints like any other; without them a date control
+ * has no min/max to offer and the user only learns the range by
+ * submitting. */
+const FORM_CONSTRAINTS = [
+  ...STRING_CONSTRAINTS,
+  ...NUMERIC_CONSTRAINTS,
+  'formatMinimum', 'formatMaximum', 'formatExclusiveMinimum', 'formatExclusiveMaximum',
+  ...ARRAY_CONSTRAINTS,
+  ...OBJECT_CONSTRAINTS,
+];
+
 function getConstraints(schema) {
   const c = {};
-  for (const key of [
-    'minLength', 'maxLength', 'pattern', 'format',
-    'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf',
-    'minItems', 'maxItems', 'uniqueItems',
-    'minProperties', 'maxProperties',
-  ]) {
+  for (const key of FORM_CONSTRAINTS) {
     if (schema[key] !== undefined) c[key] = schema[key];
   }
   return c;
@@ -216,36 +278,59 @@ function getConstraints(schema) {
  * @param {string} key - Property name or '-' for an item template
  * @param {boolean} required
  * @param {number} depth
+ * @param {TranslateHook} t - The static-text translation hook
  * @returns {FormField}
  */
-function buildField(rawSchema, rootSchema, pointer, key, required, depth) {
+function buildField(rawSchema, rootSchema, pointer, key, required, depth, t) {
   const schema = resolveSchema(rawSchema, rootSchema, depth);
   const effective = (schema != null && typeof schema === 'object') ? schema : {};
   const kind = getFieldKind(schema);
   const control = getControl(kind, effective);
   const formatInfo = getFormatInfo(effective.format);
 
+  // The message-id base for static text: the x-msgid annotation, or the
+  // data pointer (the root field's base is the empty pointer '').
+  const base = typeof effective['x-msgid'] === 'string' ? effective['x-msgid'] : pointer;
+
+  const oneOfBranches = kind === 'enum' ? getOneOfConstBranches(effective) : null;
+  const enumValues = kind === 'enum'
+    ? (Array.isArray(effective.enum)
+      ? effective.enum
+      : oneOfBranches.map((branch) => branch.const))
+    : null;
+  const enumLabels = enumValues !== null
+    ? enumValues.map((value, i) => t(
+      `${base}#enum/${String(value)}`,
+      oneOfBranches !== null && typeof oneOfBranches[i].title === 'string'
+        ? oneOfBranches[i].title
+        : String(value)))
+    : null;
+
+  const placeholder = effective.examples?.[0] !== undefined
+    ? String(effective.examples[0])
+    : formatInfo?.placeholder;
+
   /** @type {FormField} */
   const field = {
     pointer,
     key,
-    label: effective.title || humanizeKey(key),
-    description: effective.description,
+    msgid: base,
+    label: t(`${base}#label`, effective.title || humanizeKey(key)),
+    description: t(`${base}#description`, effective.description),
     schema: effective,
     kind,
     control,
     required,
     readOnly: effective.readOnly === true,
-    enumValues: kind === 'enum' ? effective.enum : null,
+    enumValues,
+    enumLabels,
     constValue: kind === 'const' ? effective.const : undefined,
     defaultValue: effective.default,
-    placeholder: effective.examples?.[0] !== undefined
-      ? String(effective.examples[0])
-      : formatInfo?.placeholder,
+    placeholder: t(`${base}#placeholder`, placeholder),
     constraints: getConstraints(effective),
     // The raw `x-form` annotation only - compiling its query documents is
     // rules.js territory, so model building stays query-engine-free.
-    rules: isRulesObject(effective['x-form']) ? effective['x-form'] : null,
+    rules: isJsonObject(effective['x-form']) ? effective['x-form'] : null,
     children: null,
     item: null,
     tuple: null,
@@ -259,7 +344,7 @@ function buildField(rawSchema, rootSchema, pointer, key, required, depth) {
       buildField(
         propSchema, rootSchema,
         `${pointer}/${escapePointerKey(name)}`, name,
-        requiredSet.has(name), depth + 1));
+        requiredSet.has(name), depth + 1, t));
   }
 
   if (kind === 'array') {
@@ -268,41 +353,48 @@ function buildField(rawSchema, rootSchema, pointer, key, required, depth) {
       : (Array.isArray(effective.items) ? effective.items : null);
     if (prefix) {
       field.tuple = prefix.map((itemSchema, i) =>
-        buildField(itemSchema, rootSchema, `${pointer}/${i}`, String(i), false, depth + 1));
+        buildField(itemSchema, rootSchema, `${pointer}/${i}`, String(i), false, depth + 1, t));
       const rest = Array.isArray(effective.items) ? effective.additionalItems : effective.items;
       if (rest != null && typeof rest === 'object') {
-        field.item = buildField(rest, rootSchema, `${pointer}/-`, '-', false, depth + 1);
+        field.item = buildField(rest, rootSchema, `${pointer}/-`, '-', false, depth + 1, t);
       }
     }
     else if (effective.items != null && typeof effective.items === 'object') {
-      field.item = buildField(effective.items, rootSchema, `${pointer}/-`, '-', false, depth + 1);
+      field.item = buildField(effective.items, rootSchema, `${pointer}/-`, '-', false, depth + 1, t);
     }
     else {
-      field.item = buildField({}, rootSchema, `${pointer}/-`, '-', false, depth + 1);
+      field.item = buildField({}, rootSchema, `${pointer}/-`, '-', false, depth + 1, t);
     }
   }
 
   return field;
 }
 
-function isRulesObject(value) {
-  return value != null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /**
  * Encode a property name as an RFC 6901 reference token (`~` -> `~0`,
- * `/` -> `~1`), the write-side inverse of the shared parse.
+ * `/` -> `~1`), the write-side inverse of the shared parse. An alias of
+ * `encodeJSONPointerSegment` from `@jarenjs/json/pointer`, kept for
+ * compatibility.
  * @param {string} key
  * @returns {string}
  */
 export function escapePointerKey(key) {
-  return String(key).replace(/~/g, '~0').replace(/\//g, '~1');
+  return encodeJSONPointerSegment(key);
 }
 
 /**
  * Build the form model for a JSON schema.
  *
+ * Static text (labels, descriptions, placeholders, enum option labels) is
+ * resolved ONCE here, at model-build time - the right place for
+ * translation. The optional `t` hook receives role-qualified message ids
+ * built from each field's base (`x-msgid` annotation or data pointer):
+ * `<base>#label`, `<base>#description`, `<base>#placeholder`,
+ * `<base>#enum/<String(value)>` - and the schema-derived fallback text.
+ *
  * @param {object|boolean} schema - The root JSON schema
+ * @param {object} [options]
+ * @param {TranslateHook} [options.t] - Static-text translation hook, default the zero-cost identity `(id, fb) => fb`
  * @returns {FormField} The root field descriptor (kind 'object' for object schemas)
  * @example
  * const model = buildFormModel({
@@ -311,8 +403,14 @@ export function escapePointerKey(key) {
  *   required: ['email'],
  * });
  * model.children[0].control; // 'email'
+ * @example
+ * // static-text i18n
+ * const nlModel = buildFormModel(schema, {
+ *   t: (msgid, fallback) => staticTextNl[msgid] ?? fallback,
+ * });
  */
-export function buildFormModel(schema) {
+export function buildFormModel(schema, options = undefined) {
   const rootSchema = (schema != null && typeof schema === 'object') ? schema : {};
-  return buildField(schema, rootSchema, '', '', false, 0);
+  const t = options != null && typeof options.t === 'function' ? options.t : identityT;
+  return buildField(schema, rootSchema, '', '', false, 0, t);
 }