@jarenjs/rules 0.83.2

package/ARCHITECTURE.md

@@ -0,0 +1,17 @@
+# Rules component architecture
+
+`src/index.js` is the DOM-free draft/review controller. It imports core JSON
+snapshot helpers and receives preview/command functions structurally. It owns
+no query evaluator, database adapter, transaction, ledger or virtual range engine.
+
+`src/component/index.js` builds schema field guidance through forms and renders
+through view. Input updates the authoritative draft immediately; independent
+preview publication never replaces typed text or its caret. Review pages only
+present a bounded portion of the plan. Selection lives by immutable change IDs.
+The existing app widget lifecycle owns mounting and disposal. CSS binds host
+light/dark theme tokens.
+
+The host composes json/formula, json/rules, contract/command and linq/db receipts.
+It reads current state and revalidates the plan inside one existing transaction.
+The website supplies neutral application declarations and an independent virtual
+inventory grid, while all reusable UI remains in this workspace.

package/README.md

@@ -0,0 +1,49 @@
+# @jarenjs/rules
+
+The [combined adoption recipe](../../docs/ADOPTION-EVIDENCE.md) connects the editor to current-data validation and a durable receipt transaction. Preview grants no write authority, and unresolved original formulas remain preserved until application review.
+
+Reusable schema-guided JSON rule authoring and reviewed change selection. The
+engine imports core only; evaluator and authoritative command services are
+injected. The component layer uses view/forms and the existing app widget lifecycle.
+
+```js
+import { mountRuleEditor } from '@jarenjs/rules/component';
+import '@jarenjs/rules/styles/rules.css';
+const editor = mountRuleEditor(host, {
+  text: JSON.stringify(savedRule, null, 2),
+  schema: rowSchema,
+  preview: async (text) => previewSavedRule(JSON.parse(text)),
+  command: async (request) => validatedCommand.execute(request),
+});
+// editor.dispose() on unmount
+```
+
+The host supplies saved rule/dataset revisions and policy. Preview is read-only;
+`command` must revalidate current authorization, rows, rule identity and proposed
+values inside its transaction. Omitting it enables report-only authoring.
+[The formula/plan contract](../../packages/json/docs/FORMULA-FORMAT.md) specifies
+outcomes, conflicts, migration, refused shapes and qualification limits.
+
+`createRuleEditor` owns draft text/caret, stable selection IDs and generation
+fences. Call `edit`, `preview`, `select`, `commit`, `state` and `dispose`.
+`mountRuleEditor` presents schema fields, a controlled JSON textarea, bounded
+review pages and commit status. `createRuleEditorWidget` uses existing mount /
+update / unmount semantics. The default page holds 20 changes; hosts can select
+1–100. `maxChanges` defaults to 10000 and refuses larger preview documents.
+Selection survives unmounted pages, but a changed draft or plan clears it.
+Repeated commit admission shares one pending command; durable replay belongs to
+the host. Disposal fences preview publication; an accepted domain command stays
+host-owned. CSS uses the host theme tokens with standalone fallbacks.
+
+Automated desktop/mobile browser checks cover typing, caret preservation,
+selection, preview failure and durable commits. Physical-device and manual
+accessibility qualification remain pending.
+
+<!--fact:exports.rules-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/rules` | JavaScript | declared |
+| `@jarenjs/rules/component` | JavaScript | declared |
+| `@jarenjs/rules/package.json` | metadata | — |
+| `@jarenjs/rules/styles/rules.css` | asset | — |
+<!--/fact-->

package/dist/types/component/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Mount a reusable rule editor. Preview rows are a bounded presentation page;
+ * selection remains in the editor by stable ID. Schema fields guide JSON authors.
+ * @param {HTMLElement} host @param {any} options
+ */
+export declare function mountRuleEditor(host: HTMLElement, options: any): {
+    controller: {
+        state: () => {
+            text: string;
+            selectionStart: number;
+            selectionEnd: number;
+            plan: any;
+            selected: any[];
+            phase: string;
+            message: string;
+            reportOnly: boolean;
+        };
+        edit(value: any, selectionStart?: any, selectionEnd?: any): void;
+        preview(): Promise<{
+            text: string;
+            selectionStart: number;
+            selectionEnd: number;
+            plan: any;
+            selected: any[];
+            phase: string;
+            message: string;
+            reportOnly: boolean;
+        }>;
+        select(id: any, enabled?: boolean): boolean;
+        commit(): any;
+        dispose(): void;
+    };
+    refresh: (state?: {
+        text: string;
+        selectionStart: number;
+        selectionEnd: number;
+        plan: any;
+        selected: any[];
+        phase: string;
+        message: string;
+        reportOnly: boolean;
+    }) => void;
+    dispose(): void;
+};
+/** Existing app widget lifecycle, with all host services injected through options. */
+export declare function createRuleEditorWidget(options: any): {
+    mount: (host: any, props: any) => {
+        controller: {
+            state: () => {
+                text: string;
+                selectionStart: number;
+                selectionEnd: number;
+                plan: any;
+                selected: any[];
+                phase: string;
+                message: string;
+                reportOnly: boolean;
+            };
+            edit(value: any, selectionStart?: any, selectionEnd?: any): void;
+            preview(): Promise<{
+                text: string;
+                selectionStart: number;
+                selectionEnd: number;
+                plan: any;
+                selected: any[];
+                phase: string;
+                message: string;
+                reportOnly: boolean;
+            }>;
+            select(id: any, enabled?: boolean): boolean;
+            commit(): any;
+            dispose(): void;
+        };
+        refresh: (state?: {
+            text: string;
+            selectionStart: number;
+            selectionEnd: number;
+            plan: any;
+            selected: any[];
+            phase: string;
+            message: string;
+            reportOnly: boolean;
+        }) => void;
+        dispose(): void;
+    };
+    update: (handle: any) => any;
+    unmount: (handle: any) => any;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Preserve draft text/caret independently of asynchronous preview publications.
+ * @param {{text:string,preview:(text:string)=>any,command?:(request:any)=>any,onChange?:(state:any)=>void,maxChanges?:number}} options
+ */
+export declare function createRuleEditor(options: {
+    text: string;
+    preview: (text: string) => any;
+    command?: (request: any) => any;
+    onChange?: (state: any) => void;
+    maxChanges?: number;
+}): {
+    state: () => {
+        text: string;
+        selectionStart: number;
+        selectionEnd: number;
+        plan: any;
+        selected: any[];
+        phase: string;
+        message: string;
+        reportOnly: boolean;
+    };
+    /** Every input event updates the authoritative typing buffer before another render. */
+    edit(value: any, selectionStart?: any, selectionEnd?: any): void;
+    preview(): Promise<{
+        text: string;
+        selectionStart: number;
+        selectionEnd: number;
+        plan: any;
+        selected: any[];
+        phase: string;
+        message: string;
+        reportOnly: boolean;
+    }>;
+    /** Stable change IDs survive unmounted or evicted presentation rows. */
+    select(id: any, enabled?: boolean): boolean;
+    /** Double admission shares one command; the injected command owns transactional revalidation. */
+    commit(): any;
+    /** Fence late preview callbacks; a command already accepted remains host-owned. */
+    dispose(): void;
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@jarenjs/rules",
+  "private": false,
+  "version": "0.83.2",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./component": {
+      "types": "./dist/types/component/index.d.ts",
+      "default": "./src/component/index.js"
+    },
+    "./package.json": "./package.json",
+    "./styles/rules.css": "./styles/rules.css"
+  },
+  "files": [
+    "src/",
+    "dist/types/",
+    "styles/",
+    "docs/",
+    "ARCHITECTURE.md"
+  ],
+  "description": "Saved rule authoring and reviewed plans through injected formula and command services",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "components/rules"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "rules",
+    "formula"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.83.2",
+    "@jarenjs/view": "^0.83.2",
+    "@jarenjs/app": "^0.83.2",
+    "@jarenjs/forms": "^0.83.2"
+  }
+}

package/src/component/index.js

@@ -0,0 +1,84 @@
+//@ts-check
+/** Schema-guided authoring and bounded review pages over the injected editor. */
+import { createDomRenderer } from '@jarenjs/view';
+import { buildFormModel } from '@jarenjs/forms';
+import { createRuleEditor } from '../index.js';
+
+/**
+ * Mount a reusable rule editor. Preview rows are a bounded presentation page;
+ * selection remains in the editor by stable ID. Schema fields guide JSON authors.
+ * @param {HTMLElement} host @param {any} options
+ */
+export function mountRuleEditor(host, options) {
+  const document = host.ownerDocument;
+  const model = buildFormModel(options.schema ?? { type: 'object' });
+  const pageSize = options.pageSize ?? 20;
+  if (!Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) throw new TypeError('Invalid review page size');
+  let page = 0, disposed = false, targetIndex = 0;
+  const render = createDomRenderer(host, { document });
+  const controller = createRuleEditor({ ...options, onChange: (state) => { refresh(state); options.onChange?.(state); } });
+  function refresh(state = controller.state()) {
+    if (disposed) return;
+    const changes = state.plan?.changes ?? [];
+    page = Math.min(page, Math.max(0, Math.ceil(changes.length / pageSize) - 1));
+    const fields = (model.children ?? []).map((field) => `${field.pointer ?? field.path ?? field.key}: ${field.label ?? field.title ?? field.key}`);
+    let draft = null;
+    try { draft = JSON.parse(state.text); } catch { /* Keep incomplete draft text editable. */ }
+    const targets = Array.isArray(draft?.targets) ? draft.targets : [];
+    targetIndex = Math.min(targetIndex, Math.max(0, targets.length - 1));
+    const editableTarget = targets[targetIndex] && typeof targets[targetIndex] === 'object' && !Array.isArray(targets[targetIndex]);
+    const writable = (model.children ?? []).filter((field) => !field.readOnly && (!options.writableFields || options.writableFields.includes(field.pointer)));
+    render(['section', { class: 'jr-editor', 'aria-label': 'Rule editor' },
+      ['div', { class: 'jr-actions' }, ['label', {}, 'Target ', ['select', { 'aria-label': 'Rule target', 'data-rule-target': '', value: String(targetIndex), disabled: !targets.length },
+        ...targets.map((target, index) => ['option', { value: String(index) }, target?.id ?? String(index)])]],
+      ['label', {}, 'Writable field ', ['select', { 'aria-label': 'Writable field', 'data-rule-field': '', value: targets[targetIndex]?.field ?? '', disabled: !editableTarget },
+        ...writable.map((field) => ['option', { value: field.pointer }, field.label])]],
+      ['label', {}, ['input', { type: 'checkbox', 'aria-label': 'Target enabled', 'data-rule-enabled': '', checked: targets[targetIndex]?.enabled !== false, disabled: !editableTarget }], 'Enabled']],
+      ['label', { class: 'jr-draft-label' }, 'Rule document', ['textarea', { 'data-rule-draft': '', rows: 12, value: state.text, spellcheck: 'false', autocapitalize: 'off', autocomplete: 'off', 'aria-label': 'Rule document' }]],
+      ['details', {}, ['summary', {}, 'Available schema fields'], ['pre', {}, fields.join('\n') || JSON.stringify(options.schema ?? {}, null, 2)]],
+      ['div', { class: 'jr-actions' }, ['button', { type: 'button', 'data-rule-preview': '', disabled: state.phase === 'previewing' }, 'Preview rules'],
+        ['button', { type: 'button', 'data-rule-commit': '', disabled: state.reportOnly || state.phase !== 'review' || !state.selected.length }, `Commit selected (${state.selected.length})`]],
+      ['p', { role: 'status', 'data-rule-status': '' }, state.message || (state.phase === 'previewing' ? 'Evaluating preview…' : `${changes.length} proposed changes · ${state.selected.length} selected`)],
+      ['ul', { 'aria-label': 'Preview diagnostics' }, ...(state.plan?.errors ?? []).map((error) => ['li', {}, `${error.rowId ?? ''} ${error.targetId ?? ''}: ${error.code ?? ''} ${error.message ?? ''} ${error.docPath ?? ''}`]),
+        ...(state.plan?.omittedErrors ? [['li', {}, `${state.plan.omittedErrors} further diagnostics omitted by the configured limit.`]] : [])],
+      ['ul', { class: 'jr-changes', 'aria-label': 'Proposed changes' }, ...changes.slice(page * pageSize, (page + 1) * pageSize).map((change) =>
+        ['li', { key: change.id }, ['label', {}, ['input', { type: 'checkbox', 'data-rule-change': change.id, checked: state.selected.includes(change.id) }],
+          `${change.entityId} ${change.field}: ${change.before.present ? JSON.stringify(change.before.value) : '(absent)'} → ${JSON.stringify(change.proposed)}${change.explanation ? ` · ${change.explanation}` : ''}`]])],
+      ['nav', { class: 'jr-actions', 'aria-label': 'Preview pages' }, ['button', { type: 'button', 'data-rule-previous': '', disabled: page === 0 }, 'Previous'],
+        ['span', {}, `Page ${page + 1} of ${Math.max(1, Math.ceil(changes.length / pageSize))}`],
+        ['button', { type: 'button', 'data-rule-next': '', disabled: (page + 1) * pageSize >= changes.length }, 'Next']]]);
+  }
+  function input(event) {
+    const target = event.target;
+    if (target.hasAttribute('data-rule-draft')) controller.edit(target.value, target.selectionStart ?? 0, target.selectionEnd ?? 0);
+  }
+  function change(event) {
+    const target = event.target;
+    if (target.hasAttribute('data-rule-target')) { targetIndex = Number(target.value); refresh(); return; }
+    if (target.hasAttribute('data-rule-field') || target.hasAttribute('data-rule-enabled')) {
+      const draft = JSON.parse(controller.state().text);
+      if (target.hasAttribute('data-rule-field')) draft.targets[targetIndex].field = target.value;
+      else draft.targets[targetIndex].enabled = target.checked;
+      controller.edit(JSON.stringify(draft, null, 2)); return;
+    }
+    const id = target.getAttribute('data-rule-change');
+    if (id !== null) controller.select(id, event.target.checked);
+  }
+  function click(event) {
+    const target = event.target;
+    if (target.hasAttribute('data-rule-preview')) void controller.preview();
+    else if (target.hasAttribute('data-rule-commit')) void controller.commit();
+    else if (target.hasAttribute('data-rule-previous')) { page = Math.max(0, page - 1); refresh(); }
+    else if (target.hasAttribute('data-rule-next')) { page++; refresh(); }
+  }
+  host.addEventListener('input', input); host.addEventListener('change', change); host.addEventListener('click', click);
+  refresh();
+  return { controller, refresh,
+    dispose() { if (disposed) return; disposed = true; host.removeEventListener('input', input); host.removeEventListener('change', change); host.removeEventListener('click', click); controller.dispose(); render.destroy(); },
+  };
+}
+
+/** Existing app widget lifecycle, with all host services injected through options. */
+export function createRuleEditorWidget(options) {
+  return { mount: (host, props) => mountRuleEditor(host, { ...options, ...props }), update: (handle) => handle.refresh(), unmount: (handle) => handle.dispose() };
+}

package/src/index.js

@@ -0,0 +1,76 @@
+//@ts-check
+/** Draft and review state; all evaluation and domain command services are injected. */
+import { cloneJson, deepFreeze, isJsonValue } from '@jarenjs/core/object';
+
+/**
+ * Preserve draft text/caret independently of asynchronous preview publications.
+ * @param {{text:string,preview:(text:string)=>any,command?:(request:any)=>any,onChange?:(state:any)=>void,maxChanges?:number}} options
+ */
+export function createRuleEditor(options) {
+  if (typeof options?.text !== 'string' || typeof options.preview !== 'function') throw new TypeError('Rule editor needs a draft and preview service');
+  let text = options.text, start = 0, end = 0, plan = null, phase = 'draft', message = '', generation = 0, disposed = false, committing = null;
+  const selected = new Set();
+  const maxChanges = options.maxChanges ?? 10000;
+  if (!Number.isSafeInteger(maxChanges) || maxChanges < 1) throw new TypeError('Invalid preview change credit');
+  const state = () => deepFreeze(cloneJson({ text, selectionStart: start, selectionEnd: end, plan, selected: [...selected], phase, message, reportOnly: typeof options.command !== 'function' }));
+  const publish = () => { if (!disposed) options.onChange?.(state()); };
+  return {
+    state,
+    /** Every input event updates the authoritative typing buffer before another render. */
+    edit(value, selectionStart = value.length, selectionEnd = selectionStart) {
+      if (disposed) return;
+      if (typeof value !== 'string' || !Number.isSafeInteger(selectionStart) || !Number.isSafeInteger(selectionEnd)
+        || selectionStart < 0 || selectionEnd < selectionStart || selectionEnd > value.length) throw new TypeError('Invalid draft/caret');
+      if (value !== text) { generation++; plan = null; selected.clear(); phase = 'draft'; message = ''; }
+      text = value; start = selectionStart; end = selectionEnd; publish();
+    },
+    async preview() {
+      if (disposed) return state();
+      const mine = ++generation; phase = 'previewing'; message = ''; publish();
+      try {
+        const result = await options.preview(text);
+        if (disposed || mine !== generation) return state();
+        if (!isJsonValue(result) || !result || typeof result.id !== 'string' || !Array.isArray(result.changes)
+          || result.changes.length > maxChanges || result.changes.some((change) => !change || typeof change.id !== 'string' || !change.id
+            || typeof change.field !== 'string' || !change.before || typeof change.before.present !== 'boolean' || !Object.hasOwn(change, 'proposed'))
+          || result.errors !== undefined && !Array.isArray(result.errors)
+          || new Set(result.changes.map((change) => change.id)).size !== result.changes.length)
+          throw new TypeError('Invalid or oversized preview');
+        if (plan?.id !== result.id) selected.clear();
+        plan = deepFreeze(cloneJson(result)); phase = 'review';
+      }
+      catch (error) {
+        if (!disposed && mine === generation) {
+          let reason = 'Check the rule document.';
+          try { if (typeof error?.message === 'string') reason = error.message.slice(0, 512); }
+          catch { /* Host failures may contain inaccessible properties. */ }
+          phase = 'error'; message = `Preview failed: ${reason}`; plan = null; selected.clear();
+        }
+      }
+      publish(); return state();
+    },
+    /** Stable change IDs survive unmounted or evicted presentation rows. */
+    select(id, enabled = true) {
+      if (disposed || !plan?.changes.some((change) => change.id === id)) return false;
+      if (enabled) selected.add(id); else selected.delete(id);
+      publish(); return true;
+    },
+    /** Double admission shares one command; the injected command owns transactional revalidation. */
+    commit() {
+      if (committing) return committing;
+      if (disposed || !plan || phase !== 'review' || typeof options.command !== 'function' || !selected.size)
+        return Promise.resolve({ state: 'refused', reason: 'no-reviewed-selection' });
+      const selection = [...selected].sort(), request = deepFreeze(cloneJson({ plan, selection, key: JSON.stringify([plan.id, selection]) }));
+      const mine = generation; phase = 'committing'; message = ''; publish();
+      committing = Promise.resolve().then(() => options.command(request)).then((result) => {
+        if (!isJsonValue(result)) throw new TypeError('Command result must be JSON');
+        if (!disposed && mine === generation) { phase = 'review'; message = ['committed', 'replay'].includes(result?.state) ? 'Selected changes committed.' : 'Command refused. Preview current data again.'; }
+        return result;
+      }).catch(() => { if (!disposed && mine === generation) { phase = 'review'; message = 'Command failed. Preview current data again.'; } return { state: 'error', reason: 'command-failed' }; })
+        .finally(() => { committing = null; publish(); });
+      return committing;
+    },
+    /** Fence late preview callbacks; a command already accepted remains host-owned. */
+    dispose() { disposed = true; generation++; selected.clear(); plan = null; },
+  };
+}

package/styles/rules.css

@@ -0,0 +1,10 @@
+.jr-editor { color: var(--fg, #172033); background: var(--surface, #fff); min-width: 0; }
+.jr-draft-label { display: grid; gap: var(--space-2, .5rem); }
+.jr-editor textarea { box-sizing: border-box; width: 100%; color: inherit; background: var(--bg, #fff); border: 1px solid var(--border, #64748b); border-radius: var(--radius-sm, 8px); padding: var(--space-3, .75rem); font-family: var(--mono, monospace); }
+.jr-actions { display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-3, .75rem); margin-block: var(--space-4, 1rem); }
+.jr-editor select { max-width: 100%; min-height: 44px; color: inherit; background: var(--bg, #fff); border: 1px solid var(--border, #64748b); border-radius: var(--radius-sm, 8px); padding: var(--space-2, .5rem); }
+.jr-editor button { color: var(--accent-fg, #fff); background: var(--accent, #2563eb); border: 1px solid var(--border, #64748b); border-radius: var(--radius-sm, 8px); min-height: 44px; padding: var(--space-2, .5rem) var(--space-4, 1rem); cursor: pointer; }
+.jr-editor button:disabled { color: var(--muted, #475569); background: var(--surface, #fff); cursor: default; }
+.jr-changes { list-style: none; margin: 0; padding: 0; }
+.jr-changes label { display: flex; align-items: center; gap: var(--space-3, .75rem); min-height: 44px; overflow-wrap: anywhere; }
+.jr-editor :focus-visible { outline: 2px solid var(--accent, #2563eb); outline-offset: 2px; }