@jarenjs/forms 0.43.3 → 0.46.5

package/README.md

@@ -66,11 +66,28 @@ const result = validate(data); // { valid, errors: [{ instancePath, keyword, mes
 | `constraints` | `minLength`/`maxLength`/`pattern`/`format`/`minimum`/`maximum`/`multipleOf`/`minItems`/... |
 | `rules` | The raw `x-form` rules annotation, if any (see below) |
 | `enumValues` / `constValue` / `defaultValue` / `placeholder` | Values for the UI |
+| `preview` | A preview hint, or `null`: what a host MAY draw beside the control, as data (`{ kind: 'map' }` for `geojson`) — see below |
 | `children` | Child fields (object kinds) |
 | `item` / `tuple` | Item template and tuple prefix fields (array kinds) |
 
 Field kinds are inferred from structural keywords when `type` is absent, and `format` maps to input controls and placeholders through the same registry the preemptive validation uses (`getFormatInfo`).
 
+### The preview hint — a renderer described as data
+
+A `geojson` field is a `textarea` whose text is validated by parsing it and judging the
+object (`isValidGeoJson`), and that is where a text control stops: the value can be valid
+GeoJSON long before it is the shape the user meant, and no textarea can show the
+difference. The format registry therefore carries a **preview hint** —
+`getFormatInfo('geojson').preview` is `{ kind: 'map' }` — and the field and the view node
+carry it through as `preview`. It is a description, not a renderer: `@jarenjs/forms`
+imports no chart, and the dependency arrow forbids it (`@jarenjs/charts` sits above this
+package). A **host that understands** `preview.kind === 'map'` parses the field's text and
+hands it to a map renderer — `@jarenjs/charts` draws a `FeatureCollection`, a `Feature` or a
+geometry through `compileChart({ type: 'map' }, { features })` — beside the control. A host
+that does **not** ignores the member, and the field is exactly the textarea it always was:
+same control, same placeholder, same test. Both paths are tests; the `@jarenjs/app` form
+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.
 
 ## Layer 1 — preemptive per-field validation

package/dist/types/formats.d.ts

@@ -11,6 +11,18 @@ export type FormatInfo = {
      * - Suggested placeholder text
      */
     placeholder?: string;
+    /**
+     * - What a host MAY render beside the
+     * control, as data (see {@link FormatPreview}); absent for formats a
+     * text control already shows in full
+     */
+    preview?: FormatPreview;
+};
+export type FormatPreview = {
+    /**
+     * - The renderer family the host is asked for ('map')
+     */
+    kind: string;
 };
 /** @type {Record<string, FormatInfo>} */
 export declare const FORM_FORMATS: Record<string, FormatInfo>;

package/dist/types/model.d.ts

@@ -47,6 +47,10 @@ export type FormField = {
     constValue: any;
     defaultValue: any;
     placeholder: string | undefined;
+    /**
+     * - The format's preview hint (formats.js), for a host with a renderer for it; null otherwise
+     */
+    preview: import('./formats.js').FormatPreview | null;
     /**
      * - minLength/maxLength/pattern/minimum/... extracted for the UI
      */

package/dist/types/viewmodel.d.ts

@@ -44,6 +44,12 @@ export type FormViewNode = {
      */
     enabled: boolean;
     placeholder: string | null;
+    /**
+     * - The
+     * format's preview hint, carried through for a host that renders it;
+     * a host without a renderer for `preview.kind` ignores it.
+     */
+    preview: import('./formats.js').FormatPreview | null;
     /**
      * - The current value (`x-form.computed` wins);
      * `null` when the field is absent from the data.
@@ -246,6 +252,9 @@ export type FormViewModelOptions = {
  * @property {boolean} readOnly
  * @property {boolean} enabled - `x-form.enabled`, defaulting true.
  * @property {string|null} placeholder
+ * @property {import('./formats.js').FormatPreview|null} preview - The
+ *   format's preview hint, carried through for a host that renders it;
+ *   a host without a renderer for `preview.kind` ignores it.
  * @property {any} value - The current value (`x-form.computed` wins);
  *   `null` when the field is absent from the data.
  * @property {Array<{value: any, key: string, label: string, selected: boolean}>|null} options

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/forms",
   "private": false,
-  "version": "0.43.3",
+  "version": "0.46.5",
   "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.43.3",
-    "@jarenjs/formats": "^0.43.3",
-    "@jarenjs/json": "^0.43.3",
-    "@jarenjs/validate": "^0.43.3"
+    "@jarenjs/core": "^0.46.5",
+    "@jarenjs/formats": "^0.46.5",
+    "@jarenjs/json": "^0.46.5",
+    "@jarenjs/validate": "^0.46.5"
   }
 }

package/src/formats.js

@@ -26,6 +26,21 @@ import {
  * @property {(value: string) => boolean} test - Synchronous validity test
  * @property {string} control - Suggested HTML input control
  * @property {string} [placeholder] - Suggested placeholder text
+ * @property {FormatPreview} [preview] - What a host MAY render beside the
+ *   control, as data (see {@link FormatPreview}); absent for formats a
+ *   text control already shows in full
+ */
+
+/**
+ * A preview hint: a description of what to draw from the field's value,
+ * for a host that has a renderer for it. It is DATA, not a renderer —
+ * `@jarenjs/forms` imports no chart, and a host that does not recognise
+ * `kind` ignores the hint and the field behaves exactly as without it.
+ * The one kind shipped is `map`: the host feeds the field's parsed
+ * GeoJSON to a map renderer (`@jarenjs/charts`' `map` type takes a
+ * `FeatureCollection`, a `Feature` or a geometry as `features`).
+ * @typedef {object} FormatPreview
+ * @property {string} kind - The renderer family the host is asked for ('map')
  */
 
 /**
@@ -34,7 +49,7 @@ import {
  * also override the canonical `test` when what a form field holds is not
  * what the validator's format judges (a field holds `geojson` as text,
  * the format applies to the parsed object).
- * @type {Record<string, { control?: string, placeholder?: string, test?: (value: string) => boolean }>}
+ * @type {Record<string, { control?: string, placeholder?: string, test?: (value: string) => boolean, preview?: FormatPreview }>}
  */
 const FORM_HINTS = {
   // -- date and time. Which formats get a native control is decided by
@@ -101,11 +116,17 @@ const FORM_HINTS = {
 
   // -- geospatial. The geojson tester judges the OBJECT, but a form
   //    field holds its text, so the field-level test parses first.
+  //    The text a user types is valid GeoJSON long before it is the
+  //    shape they meant, which no textarea can show: `preview` tells a
+  //    host that has a map renderer to draw the parsed value. It is a
+  //    hint in the same sense `control` is — a host without one
+  //    ignores it and the field is exactly this textarea.
   'geohash': { placeholder: 'u173z' },
   'wkt': { placeholder: 'POINT (4.9041 52.3676)' },
   'geojson': {
     control: 'textarea',
     placeholder: '{"type":"Point","coordinates":[4.9,52.4]}',
+    preview: { kind: 'map' },
     test: (text) => {
       try {
         return isValidGeoJson(JSON.parse(text));

package/src/model.js

@@ -46,6 +46,7 @@ const DEFAULT_MAX_DEPTH = 24;
  * @property {any} constValue - Fixed value when the schema is a const
  * @property {any} defaultValue
  * @property {string|undefined} placeholder
+ * @property {import('./formats.js').FormatPreview|null} preview - The format's preview hint (formats.js), for a host with a renderer for it; null otherwise
  * @property {object} constraints - minLength/maxLength/pattern/minimum/... extracted for the UI
  * @property {object|null} rules - The raw `x-form` rules annotation, if any (see rules.js)
  * @property {Array<FormField>|null} children - Child fields for object kinds
@@ -327,6 +328,7 @@ function buildField(rawSchema, rootSchema, pointer, key, required, depth, t) {
     constValue: kind === 'const' ? effective.const : undefined,
     defaultValue: effective.default,
     placeholder: t(`${base}#placeholder`, placeholder),
+    preview: formatInfo?.preview ?? null,
     constraints: getConstraints(effective),
     // The raw `x-form` annotation only - compiling its query documents is
     // rules.js territory, so model building stays query-engine-free.

package/src/viewmodel.js

@@ -43,6 +43,9 @@ const EMPTY_STATE = Object.freeze({});
  * @property {boolean} readOnly
  * @property {boolean} enabled - `x-form.enabled`, defaulting true.
  * @property {string|null} placeholder
+ * @property {import('./formats.js').FormatPreview|null} preview - The
+ *   format's preview hint, carried through for a host that renders it;
+ *   a host without a renderer for `preview.kind` ignores it.
  * @property {any} value - The current value (`x-form.computed` wins);
  *   `null` when the field is absent from the data.
  * @property {Array<{value: any, key: string, label: string, selected: boolean}>|null} options
@@ -321,6 +324,7 @@ function buildNode(field, pointer, data, ruleState, fieldErrors, element, remova
     readOnly: field.readOnly === true,
     enabled: rs === undefined || rs.enabled !== false,
     placeholder: field.placeholder ?? null,
+    preview: field.preview ?? null,
     value: value === undefined ? null : value,
     options: null,
     errors,