@jarenjs/app 0.49.2 → 0.66.1

package/README.md

@@ -40,6 +40,47 @@ const app = createApp({
 }, { node: document.getElementById('app') });
 ```
 
+### The same app, by code
+
+`@jarenjs/linq/app` writes that document from typed builders — the
+initial state derived from the state schema's defaults, the view the
+JSLT pen's stylesheet, the actions captured over `$`/`$event`/`$payload`
+and their patch pointers derived from the state shape — and answers the
+state's JSON Schema beside it for `validateState`:
+
+```javascript
+import { action, bind, defineApp, replace, transition } from '@jarenjs/linq/app';
+import { rule } from '@jarenjs/linq/jslt';
+import * as s from '@jarenjs/linq/schema';
+
+const counter = defineApp({
+  state: s.object({ count: s.integer().default(0) }),
+  view: [rule('$', (v) => ['main', {},
+    ['h1', {}, 'Count: ', v.get('count')],
+    ['button', { on: { click: 'inc' } }, '+'],
+    ['button', { on: { click: bind('add', { payload: 10 }) } }, '+10'],
+  ])],
+  actions: {
+    inc: action((st) => transition({
+      patch: [replace((c) => c.get('count'), st.get('count').add(1))],
+    })),
+    add: action((st, x) => transition({
+      patch: [replace((c) => c.get('count'), st.get('count').add(x.payload))],
+    }), { payload: s.integer() }),
+  },
+});
+
+createApp(counter.document, { node: document.getElementById('app') });
+```
+
+It is the same application — the test suite boots both and compares
+them frame for frame. The mapping table, every refusal and the
+member-name escape this example's `get('count')` spells are
+[APP-PEN.md](../linq/docs/APP-PEN.md); this package depends on none of
+it.
+
+## The view
+
 The view is a JSLT stylesheet: rules match state by location (JSONPath) and shape (JSON Schema, via `compileTypeTest`), bodies are query documents producing vnodes, and `$path`/`$root` are in scope — a rule rendering `/todos/3` can embed its own pointer in an event binding, which is why there are no payload-creator functions anywhere.
 
 ## Actions and transitions
@@ -129,6 +170,10 @@ Two IDE-shaped primitives ship ready to bind, so a two-pane surface (the studio,
 - **`createSplitterWidget({ action, grid, rail, cssVar, min, max, step })`** — a drag handle over a pane boundary. It drives a CSS ratio variable *live* during a drag (no per-move dispatch — that would flood the transaction log and undo) and commits the ratio through `action` on pointer-up only, plus keyboard resize as an ARIA separator. Register it like any widget; parameterize the grid/rail selectors, the CSS variable and the commit action so each surface binds its own.
 - **`createDocStore({ storage, key })`** — a keyed `save`/`load`/`remove`/`names`/`all` CRUD over an injected `storage` (`localStorage` in the browser, an in-memory object in tests), so the package never touches `localStorage` itself. Paired with **`encodeShare(snapshot)`** / **`decodeShare(token)`**, a Unicode-safe base64url share-link codec (a corrupt token decodes to `null`, never a throw), it is the new/save/load/delete/share pattern behind the studio and play surfaces.
 
+Collection keys and document names such as `__proto__` are ordinary own
+members of the document store and survive persistence. Loading a name
+that has not been saved returns `undefined`, including prototype-member names.
+
 ## Invariants the model can't cheat
 
 ```javascript
@@ -173,7 +218,12 @@ const app = createApp({
 });
 ```
 
-Schema in, live form out: text/email/number/date/color inputs, textareas, checkboxes, selects with precomputed options, nested object fieldsets, arrays with add/remove buttons, inline errors, and `x-form` visibility/enablement/computed reacting per keystroke. The `viewModel` option is the general **derivation boundary**: it maps state to the view stylesheet's input before every render, so JS-computed derivations enter the render path without ever entering the state. A DOM control's value is a string, and two controls carry something else: a select over a non-string enum, and the `json` editor over a structured value. Both round-trip through JSON text and decode it in `formEventFields()`, the format's one sanctioned place for host JavaScript at the DOM boundary (APP-FORMAT §5.4) — **register it or those two controls write nothing**. Remaining 0.1 limits (documented in `src/forms.js`): a cleared number input writes `null`, and arrays need to exist in the data (give them `default: []` in the schema).
+Schema in, live form out: text/email/number/date/color inputs, textareas, checkboxes, selects with precomputed options, nested object fieldsets, arrays with add/remove buttons, inline errors, and `x-form` visibility/enablement/computed reacting per keystroke. The `viewModel` option is the general **derivation boundary**: it maps state to the view stylesheet's input before every render, so JS-computed derivations enter the render path without ever entering the state. A DOM control's value is a string, and two controls carry something else: a select over a non-string enum, and the `json` editor over a structured value. Both round-trip through JSON text and decode it in `formEventFields()`, the format's one sanctioned place for host JavaScript at the DOM boundary (APP-FORMAT §5.4) — **register it or those two controls write nothing**. Remaining limits (documented in `src/forms.js`): a cleared number input writes `null`, and intermediate object/array containers need to exist in the data. `createInitialData(model)` supplies them for a new form; loaded documents must supply them too.
+
+Nested object and array fields honor `x-form.enabled` through their native
+`fieldset` disablement, including child controls and array buttons. A `readOnly`
+field uses native `readonly` for text inputs and textareas, and `disabled` for
+checkboxes, selects, collection fieldsets, and add/remove buttons.
 
 ## Headless and server-side
 
@@ -192,6 +242,20 @@ Also exported: `compileActions`, `compileSubs`, `createFormView`, `createFormAct
 
 Options: `node`, `document`, `effects`, `subs`, `eventFields` (named `$event` field extractors), `widgets` (registered widget definitions, forwarded to the renderer), `compileTypeTest`, `validateState`, `viewModel`, `onError` (default rethrows), `schedule` (render batching; default microtask — pass `(f) => f()` for synchronous tests). Compile failures throw `AppCompileError` (`JA0xxx`, with a `docPath` into the app document); runtime failures route `AppRuntimeError` (`JA2xxx`) through `onError`. The full code table is in [APP-FORMAT.md](docs/APP-FORMAT.md) §10.
 
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.app-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/app` | JavaScript | declared |
+| `@jarenjs/app/schemas/jaren-app.draft-07.schema.json` | schema | — |
+| `@jarenjs/app/schemas/jaren-app.schema.json` | schema | — |
+| `@jarenjs/app/package.json` | metadata | — |
+<!--/fact-->
+
 ## Development
 
 Unit tests live in `test/app/` at the repository root (`npm run test:app`). See [ROADMAP](../../docs/ROADMAP.md) for what's next: dirty-path-pruned re-rendering and time-travel tooling over the action log.

package/dist/types/forms.d.ts

@@ -22,9 +22,11 @@
  * JavaScript at the DOM boundary (APP-FORMAT §5.4). A host that renders
  * these controls MUST register them.
  *
- * Remaining limitation, documented rather than hidden: a cleared number
- * input writes `null` (which surfaces as a validation error, not a
- * dispatch error).
+ * Remaining limitations: a cleared number input writes `null` (which
+ * surfaces as a validation error, not a dispatch error), and standard
+ * actions require intermediate object/array containers to exist in the
+ * data. `createInitialData` supplies those containers for a new form;
+ * loaded documents must supply them too.
  */
 /**
  * The event-field extractors the standard form controls need, for

package/docs/APP-FORMAT.md

@@ -38,6 +38,19 @@ valid per §2–§5. A **runtime** (the reference implementation is
 specified there, and MUST serialize dispatches per the transaction
 model of §8.
 
+One producer ships in this repository: `@jarenjs/linq/app` writes these
+documents from typed JavaScript builders — the state's initial value
+derived from its schema's defaults, the view the JSLT pen's stylesheet,
+actions captured over §3.1's three names, and patch pointers derived
+from the state shape — with `defineApp()` refusing at build time what
+§4 and §6 would otherwise report per dispatch. Its mapping table is
+[APP-PEN.md](../../linq/docs/APP-PEN.md); §2's document below
+and the `contract/catalog.load/start` action of
+[CONTRACT-FORMAT §11.1](../../contract/docs/CONTRACT-FORMAT.md) are
+rebuilt through it byte for byte by that package's test suite. Nothing
+in this package depends on it: the format is the contract, and a
+document written by hand is the same document.
+
 ## 2. The app document
 
 ```json

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/app",
   "private": false,
-  "version": "0.49.2",
+  "version": "0.66.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -50,8 +50,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.49.2",
-    "@jarenjs/json": "^0.49.2",
-    "@jarenjs/view": "^0.49.2"
+    "@jarenjs/core": "^0.66.1",
+    "@jarenjs/json": "^0.66.1",
+    "@jarenjs/view": "^0.66.1"
   }
 }

package/src/docstore.js

@@ -12,6 +12,8 @@
  * forgivingly: a corrupt token decodes to `null`, never a throw.
  */
 
+import { setObjectMember } from '@jarenjs/core/object';
+
 /**
  * @param {Object} opts
  * @param {{ read: () => any, write: (store: any) => void }} opts.storage
@@ -29,10 +31,10 @@
 export function createDocStore({ storage, key = 'experiments' }) {
   // read once; keep the SAME object reference for every write-back
   const store = storage.read() ?? {};
-  if (store[key] === undefined || store[key] === null) store[key] = {};
+  if (!Object.hasOwn(store, key) || store[key] == null) setObjectMember(store, key, {});
   return {
-    save(name, value) { store[key][name] = value; storage.write(store); },
-    load(name) { return store[key][name]; },
+    save(name, value) { setObjectMember(store[key], name, value); storage.write(store); },
+    load(name) { return Object.hasOwn(store[key], name) ? store[key][name] : undefined; },
     remove(name) { delete store[key][name]; storage.write(store); },
     names() { return Object.keys(store[key]).sort(); },
     all() { return store[key]; },

package/src/forms.js

@@ -23,9 +23,11 @@
  * JavaScript at the DOM boundary (APP-FORMAT §5.4). A host that renders
  * these controls MUST register them.
  *
- * Remaining limitation, documented rather than hidden: a cleared number
- * input writes `null` (which surfaces as a validation error, not a
- * dispatch error).
+ * Remaining limitations: a cleared number input writes `null` (which
+ * surfaces as a validation error, not a dispatch error), and standard
+ * actions require intermediate object/array containers to exist in the
+ * data. `createInitialData` supplies those containers for a new form;
+ * loaded documents must supply them too.
  */
 
 /** The default action names shared by both factories. */
@@ -111,6 +113,21 @@ export function createFormView(options = {}) {
   const ctl = (control) => `${root}..[?@.control == '${control}']`;
 
   const disabled = { $not: '$.enabled' };
+  // Selects, checkboxes and collection controls have no readonly mode.
+  // Disabling their fieldset also prevents edits through child controls.
+  const writeDisabled = { $or: [disabled, '$.readOnly'] };
+
+  /** One removal control for scalar and collection array elements. */
+  const remove = { $if: ['$.removable',
+    ['button', {
+      type: 'button',
+      class: `${cls}-remove`,
+      // the glyph is decoration; the accessible name is the label
+      'aria-label': labels.removeItem,
+      title: labels.removeItem,
+      disabled: writeDisabled,
+      on: { click: { action: act.remove, with: { pointer: '$.pointer' } } },
+    }, options.removeLabel ?? '×']] };
 
   /** The shared field chrome around one control vnode. */
   const field = (control) => ['div', { class: `${cls}-field`, 'data-pointer': '$.pointer' },
@@ -121,15 +138,7 @@ export function createFormView(options = {}) {
     ],
     { $if: ['$.description', ['p', { class: `${cls}-description` }, '$.description']] },
     [{ $apply: '$.errors[*]' }],
-    { $if: ['$.removable',
-      ['button', {
-        type: 'button',
-        class: `${cls}-remove`,
-        // the glyph is decoration; the accessible name is the label
-        'aria-label': labels.removeItem,
-        title: labels.removeItem,
-        on: { click: { action: act.remove, with: { pointer: '$.pointer' } } },
-      }, options.removeLabel ?? '×']] },
+    remove,
   ];
 
   // every write binding carries the element flag: the standard actions
@@ -179,16 +188,17 @@ export function createFormView(options = {}) {
     // nested objects: a fieldset group
     {
       match: ctl('object'),
-      body: ['fieldset', { class: `${cls}-group`, 'data-pointer': '$.pointer' },
+      body: ['fieldset', { class: `${cls}-group`, 'data-pointer': '$.pointer', disabled: writeDisabled },
         { $if: ['$.label', ['legend', {}, '$.label']] },
         [{ $apply: '$.children[*]' }],
         [{ $apply: '$.errors[*]' }],
+        remove,
       ],
     },
     // arrays: expanded items plus the add-item button
     {
       match: ctl('array'),
-      body: ['fieldset', { class: `${cls}-array`, 'data-pointer': '$.pointer' },
+      body: ['fieldset', { class: `${cls}-array`, 'data-pointer': '$.pointer', disabled: writeDisabled },
         { $if: ['$.label', ['legend', {}, '$.label']] },
         [{ $apply: '$.items[*]' }],
         { $if: [{ $exists: '$.addValue' },
@@ -197,9 +207,11 @@ export function createFormView(options = {}) {
             class: `${cls}-add`,
             'aria-label': labels.addItem,
             title: labels.addItem,
+            disabled: writeDisabled,
             on: { click: { action: act.add, with: { pointer: '$.pointer', value: '$.addValue' } } },
           }, options.addLabel ?? '+']] },
         [{ $apply: '$.errors[*]' }],
+        remove,
       ],
     },
     // one error line per message
@@ -216,7 +228,7 @@ export function createFormView(options = {}) {
     {
       match: ctl('select'),
       body: field(['select', {
-        disabled,
+        disabled: writeDisabled,
         on: {
           change: { action: act.json, with: writeWith, event: [JSON_FIELD] },
         },
@@ -228,7 +240,7 @@ export function createFormView(options = {}) {
       body: field(['input', {
         type: 'checkbox',
         checked: '$.value',
-        disabled,
+        disabled: writeDisabled,
         on: { change: { action: act.check, with: writeWith } },
       }]),
     },