@jarenjs/forms 0.9.2

package/src/data.js

@@ -0,0 +1,223 @@
+//@ts-check
+
+/**
+ * Immutable data helpers for form values, addressed by JSON pointer.
+ *
+ * Form data follows JSON semantics: a field that was never filled in is
+ * ABSENT (undefined), not an empty string - so `required` and default
+ * handling behave exactly like they will on the wire.
+ *
+ * Pointer parsing and reading go through the @jarenjs/json compiled
+ * pointer engine (one pointer implementation in the whole repo); field
+ * pointers are stable for a model's lifetime, so compiled getters are
+ * cached by pointer string and reads are allocation-free.
+ */
+
+import {
+  parseJSONPointer,
+  compileJSONPointer,
+  JSONPOINTER_NOTHING,
+} from '@jarenjs/json/pointer';
+
+/**
+ * Split a JSON pointer into decoded segments per RFC 6901. '' -> [].
+ * @param {string} pointer
+ * @returns {string[]}
+ * @throws {import('@jarenjs/json/pointer').JSONPointerSyntaxError}
+ *   When the pointer violates the RFC 6901 grammar
+ */
+export function parsePointer(pointer) {
+  if (pointer == null) return [];
+  return parseJSONPointer(pointer);
+}
+
+const getterCache = new Map();
+const GETTER_CACHE_LIMIT = 512;
+
+/**
+ * Compiled getter for a pointer string, cached FIFO (the same pattern as
+ * the query engine's string cache): form field pointers are a small,
+ * stable set, so every keystroke after the first hits the cache.
+ * @param {string} pointer
+ * @returns {(root: any) => any}
+ */
+function getPointerGetter(pointer) {
+  let getter = getterCache.get(pointer);
+  if (getter === undefined) {
+    getter = compileJSONPointer(pointer);
+    if (getterCache.size >= GETTER_CACHE_LIMIT)
+      getterCache.delete(getterCache.keys().next().value);
+    getterCache.set(pointer, getter);
+  }
+  return getter;
+}
+
+/**
+ * Read the value at a JSON pointer.
+ * @param {any} data
+ * @param {string} pointer - e.g. '/user/address/0/street'
+ * @returns {any} The value, or undefined when the path does not exist
+ */
+export function getValueAtPointer(data, pointer) {
+  const value = getPointerGetter(pointer)(data);
+  return value === JSONPOINTER_NOTHING ? undefined : value;
+}
+
+//#region roadmap
+// Immutable write ops (set/append/remove by pointer) are a @jarenjs/json
+// roadmap item (compiled setters beside the compiled getters, feeding the
+// JSON Patch work). Until that lands they live here; parsing already goes
+// through the shared parseJSONPointer above.
+
+/**
+ * Return a copy of `data` with the value at `pointer` replaced.
+ * Setting `undefined` REMOVES the property (array items become undefined
+ * holes only when explicitly set; use removeItemAt to delete them).
+ * Missing intermediate containers are created (objects for name segments,
+ * arrays for numeric segments).
+ * @param {any} data
+ * @param {string} pointer
+ * @param {any} value
+ * @returns {any} The new root value
+ */
+export function setValueAtPointer(data, pointer, value) {
+  const keys = parsePointer(pointer);
+  if (keys.length === 0) return value;
+
+  const root = cloneContainer(data, keys[0]);
+  let current = root;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    current[key] = cloneContainer(current[key], keys[i + 1]);
+    current = current[key];
+  }
+
+  const last = keys[keys.length - 1];
+  if (value === undefined && !Array.isArray(current)) {
+    delete current[last];
+  }
+  else {
+    current[last] = value;
+  }
+  return root;
+}
+
+function cloneContainer(value, nextKey) {
+  if (Array.isArray(value)) return value.slice();
+  if (value != null && typeof value === 'object') return { ...value };
+  return /^\d+$/.test(String(nextKey)) ? [] : {};
+}
+
+/**
+ * Return a copy of `data` with the item at `index` removed from the array
+ * at `pointer`.
+ * @param {any} data
+ * @param {string} pointer - Pointer to the ARRAY
+ * @param {number} index
+ * @returns {any}
+ */
+export function removeItemAt(data, pointer, index) {
+  const arr = getValueAtPointer(data, pointer);
+  if (!Array.isArray(arr)) return data;
+  const next = arr.slice();
+  next.splice(index, 1);
+  return setValueAtPointer(data, pointer, next);
+}
+
+/**
+ * Return a copy of `data` with `value` appended to the array at `pointer`
+ * (the array is created when absent).
+ * @param {any} data
+ * @param {string} pointer - Pointer to the ARRAY
+ * @param {any} value
+ * @returns {any}
+ */
+export function appendItem(data, pointer, value) {
+  const arr = getValueAtPointer(data, pointer);
+  const next = Array.isArray(arr) ? [...arr, value] : [value];
+  return setValueAtPointer(data, pointer, next);
+}
+
+//#endregion
+
+/**
+ * Create initial data for a form model: schema defaults and const values
+ * are filled in, everything else stays absent.
+ * @param {import('./model.js').FormField} field - A field from buildFormModel
+ * @returns {any}
+ */
+export function createInitialData(field) {
+  if (field == null) return undefined;
+  if (field.defaultValue !== undefined) return field.defaultValue;
+  if (field.constValue !== undefined) return field.constValue;
+
+  if (field.kind === 'object') {
+    const obj = {};
+    if (field.children) {
+      for (const child of field.children) {
+        const value = createInitialData(child);
+        if (value !== undefined) obj[child.key] = value;
+      }
+    }
+    return obj;
+  }
+
+  if (field.kind === 'array') {
+    if (field.tuple) {
+      const items = field.tuple.map((item) => createInitialData(item));
+      while (items.length > 0 && items[items.length - 1] === undefined) items.pop();
+      return items;
+    }
+    return [];
+  }
+
+  return undefined;
+}
+
+/**
+ * Create a sensible starter value for one array item of the given field.
+ * @param {import('./model.js').FormField} itemField
+ * @returns {any}
+ */
+export function createItemValue(itemField) {
+  const initial = createInitialData(itemField);
+  if (initial !== undefined) return initial;
+  switch (itemField?.kind) {
+    case 'string': return '';
+    case 'number':
+    case 'integer': return 0;
+    case 'boolean': return false;
+    case 'enum': return itemField.enumValues?.[0];
+    default: return initial;
+  }
+}
+
+/**
+ * Coerce a raw input string (what an HTML input yields) into the typed
+ * value for a field. An empty string means "absent" (undefined) so that
+ * required/optional semantics stay correct.
+ * @param {import('./model.js').FormField} field
+ * @param {any} raw - Raw input value (string, or boolean for checkboxes)
+ * @returns {any}
+ */
+export function parseFieldInput(field, raw) {
+  if (field.kind === 'boolean') return !!raw;
+  if (raw === '' || raw == null) return undefined;
+
+  switch (field.kind) {
+    case 'number':
+    case 'integer': {
+      const num = Number(raw);
+      // Keep the raw string when it is not numeric, so validation can
+      // report a type error instead of silently swallowing the input.
+      return Number.isNaN(num) ? raw : num;
+    }
+    case 'enum': {
+      // Map the selected option string back to the typed enum value
+      const match = field.enumValues?.find((v) => String(v) === String(raw));
+      return match !== undefined ? match : raw;
+    }
+    default:
+      return raw;
+  }
+}

package/src/formats.js

@@ -0,0 +1,120 @@
+//@ts-check
+
+/**
+ * Format registry for form fields.
+ *
+ * The test predicates come from the CANONICAL format registry in
+ * `@jarenjs/formats` (`formatTesters`) - the same name -> tester bindings
+ * the schema validator's format compilers wrap - so the preemptive
+ * per-keystroke validation accepts exactly what the authoritative
+ * validation accepts. This module only adds what is genuinely
+ * form-specific: rendering hints (which HTML input control fits and a
+ * sensible placeholder) plus a few control-hint-only convenience formats.
+ */
+
+import {
+  formatTesters,
+  numberFormatTesters,
+} from '@jarenjs/formats';
+
+/**
+ * @typedef {object} FormatInfo
+ * @property {(value: string) => boolean} test - Synchronous validity test
+ * @property {string} control - Suggested HTML input control
+ * @property {string} [placeholder] - Suggested placeholder text
+ */
+
+/**
+ * Rendering hints per format name. Formats without an entry render as a
+ * plain text input (number-group formats as a number input).
+ * @type {Record<string, { control?: string, placeholder?: string }>}
+ */
+const FORM_HINTS = {
+  // -- date and time (RFC 3339 requires a timezone offset, which the HTML
+  //    time / datetime-local inputs cannot produce; those stay text inputs)
+  'date': { control: 'date', placeholder: '2024-01-15' },
+  'time': { placeholder: '13:45:30Z' },
+  'date-time': { placeholder: '2024-01-15T13:45:30Z' },
+  'iso-date-time': { placeholder: '2024-01-15T13:45:30' },
+  'iso-time': { placeholder: '13:45:30' },
+  'duration': { placeholder: 'P3DT4H' },
+
+  // -- email
+  'email': { control: 'email', placeholder: 'user@example.com' },
+  'email--full': { control: 'email', placeholder: 'user@example.com' },
+  'idn-email': { control: 'email', placeholder: 'user@example.com' },
+
+  // -- hosts and addresses
+  'hostname': { placeholder: 'example.com' },
+  'idn-hostname': { placeholder: 'example.com' },
+  'ipv4': { placeholder: '192.168.0.1' },
+  'ipv6': { placeholder: '::1' },
+  'mac': { placeholder: '00:1B:44:11:3A:B7' },
+
+  // -- uris
+  'uri': { control: 'url', placeholder: 'https://example.com/path' },
+  'uri--full': { control: 'url', placeholder: 'https://example.com/path' },
+  'uri-reference': { placeholder: '/relative/path' },
+  'uri-reference--full': { placeholder: '/relative/path' },
+  'uri-template': { placeholder: '/users/{id}' },
+  'url': { control: 'url', placeholder: 'https://example.com' },
+  'url--full': { control: 'url', placeholder: 'https://example.com' },
+  'iri': { control: 'url', placeholder: 'https://example.com/päth' },
+  'iri-reference': { placeholder: '/relative/päth' },
+
+  // -- identifiers
+  'uuid': { placeholder: '123e4567-e89b-12d3-a456-426614174000' },
+  'guid': { placeholder: '123e4567-e89b-12d3-a456-426614174000' },
+  'identifier': { placeholder: 'my_identifier' },
+  'html-identifier': { placeholder: 'my-element-id' },
+  'css-identifier': { placeholder: 'my-class-name' },
+
+  // -- json addressing
+  'json-pointer': { placeholder: '/path/to/value' },
+  'json-pointer-uri-fragment': { placeholder: '#/path/to/value' },
+  'relative-json-pointer': { placeholder: '1/sibling' },
+  'json-path': { placeholder: '$.store.book[0].title' },
+
+  // -- misc
+  'regex': { placeholder: '^[a-z]+$' },
+  'base64': { control: 'textarea', placeholder: 'SGVsbG8=' },
+  'byte': { control: 'textarea', placeholder: 'SGVsbG8=' },
+  'alpha': { placeholder: 'alpha' },
+  'numeric': { placeholder: '0123' },
+  'alphanumeric': { placeholder: 'abc123' },
+  'hexadecimal': { placeholder: 'deadbeef' },
+  'uppercase': { placeholder: 'ABC' },
+  'lowercase': { placeholder: 'abc' },
+  'color': { control: 'color', placeholder: '#ff8800' },
+  'isbn10': { placeholder: '0-306-40615-2' },
+  'isbn13': { placeholder: '978-3-16-148410-0' },
+  'iban': { placeholder: 'NL91ABNA0417164300' },
+  'country2': { placeholder: 'NL' },
+};
+
+function acceptAnything() {
+  return true;
+}
+
+/** @type {Record<string, FormatInfo>} */
+export const FORM_FORMATS = {};
+for (const [name, test] of Object.entries(formatTesters)) {
+  const control = name in numberFormatTesters ? 'number' : 'text';
+  FORM_FORMATS[name] = { test, control, ...FORM_HINTS[name] };
+}
+
+// -- convenience (non-standard, control hints only; unknown to the
+//    validator's registries, so they never assert anything)
+FORM_FORMATS['password'] = { test: acceptAnything, control: 'password' };
+FORM_FORMATS['textarea'] = { test: acceptAnything, control: 'textarea' };
+FORM_FORMATS['multiline'] = { test: acceptAnything, control: 'textarea' };
+
+/**
+ * Look up the format info for a JSON Schema format name.
+ * @param {string|undefined} format - The format name
+ * @returns {FormatInfo|null} The format info, or null when unknown
+ */
+export function getFormatInfo(format) {
+  if (typeof format !== 'string') return null;
+  return FORM_FORMATS[format] || null;
+}

package/src/index.js

@@ -0,0 +1,49 @@
+//@ts-check
+
+/**
+ * @jarenjs/forms - framework-agnostic form model generation for JSON Schema.
+ *
+ * buildFormModel(schema) turns a schema into a renderable field tree;
+ * validateField gives immediate per-field feedback powered by @jarenjs/core
+ * primitives, and the `x-form` rules (rules.js) add cross-field behavior -
+ * visibility, enablement, computed values, preemptive assertions - as
+ * compiled Jaren JSON Queries, before the complete compiled schema
+ * validation runs (app-wired; forms never imports the validator). The
+ * data helpers keep form values in plain JSON semantics, addressed by
+ * JSON pointer through the @jarenjs/json compiled pointer engine.
+ */
+
+export {
+  buildFormModel,
+  resolveSchema,
+  getFieldKind,
+  humanizeKey,
+  escapePointerKey,
+} from './model.js';
+
+export {
+  compileFormRules,
+  evaluateFormRules,
+  formRulesToQueryAssertions,
+} from './rules.js';
+
+export {
+  validateField,
+  validateAllFields,
+} from './validate.js';
+
+export {
+  createInitialData,
+  createItemValue,
+  parseFieldInput,
+  parsePointer,
+  getValueAtPointer,
+  setValueAtPointer,
+  appendItem,
+  removeItemAt,
+} from './data.js';
+
+export {
+  FORM_FORMATS,
+  getFormatInfo,
+} from './formats.js';