@script-it/json-views-react 0.1.0-beta.1 → 2026.10.25

package/README.md

@@ -155,6 +155,8 @@ Custom descriptor properties are preserved and passed to both validation and edi
 
 Editors receive `value`, `stringValue`, `descriptor`, `disabled`, `error`, and `onChange`/`onCommit`/`onCancel`. `onChange` updates the local draft; `onCommit(value)` submits a candidate, while `onCommit()` submits the current draft. Respect `disabled` while a save is pending. An optional display receives the canonical JSON value, `compact`, `onOpen`, and the host Markdown renderer. Object and array values use the same widget contract, including at the current/root location, with an Expand action for structural inspection.
 
+A registration's `enterKey` sets what a plain Enter does in the editor's multiline controls: `'submit'` (default) saves and leaves Shift+Enter for a line break, while `'newline'` keeps Enter for line breaks and saves on Ctrl/Cmd+Enter, as the built-in `markdown`, `body`, and `html` editors do. Replacing only a type's editor keeps its `enterKey`. A widget that handles Enter itself, such as a code editor, calls `event.preventDefault()` on that keydown to keep it.
+
 Core `filterOperators`, `matchesFilter`, and `compare` supply custom filtering and ordering. Comparators must define a consistent order. Register implementations before compiling annotations; use registry methods to replace or unregister them. Registries notify mounted viewers of changes. Create a provider-scoped registry or clone when behavior must differ across instances. See the [complete extension contract](annotation-spec.md#extension-lifecycle) and the [working custom-object consumer](../examples/consumer/src/main.tsx).
 
 Registrations are additive. Replacing only a type's editor preserves its existing display widget:
@@ -167,6 +169,23 @@ const widgets = createDefaultWidgetRegistry().register('date', {
 
 For optional dates, `JSONContent` sets Clear to `null` by default. Pass `clearBehavior="remove"` when the host should remove the property instead.
 
+### Tall table cells
+
+Table cells clip values taller than `9rem` (about six lines), so long text and wrapped choices keep rows scannable. Selecting a clipped cell floats its whole value over the rows below without changing any row height; editing a cell opens its editor in that same surface. A record's title cell keeps opening the record, which shows the whole value. Configure this with the optional `tableCells` prop on `JSONContent`, `CSVContent`, or `JsonViewer`:
+
+```tsx
+<JSONContent
+  content={content}
+  tableCells={{
+    overflow: 'clamp', // default; 'grow' lets rows fit their tallest value
+    maxHeight: 160,    // pixels or any CSS length; default '9rem'
+    reveal: 'select',  // default; 'none' keeps clipped cells clipped
+  }}
+/>
+```
+
+Hosts can also set the limit in CSS, per container or breakpoint, with `--json-views-table-cell-max-height`; a `maxHeight` prop takes precedence for its viewer.
+
 Built-in `select` and `multi-select` widgets are creatable. Descriptor `options` provide the initial suggestions, while new string values remain valid and are inferred back into the effective option list wherever the same schema declaration applies.
 
 Use descriptor `optionColors` to assign a palette color per option. With writable annotations, the menu shows a palette button beside each option and persists the selected color through the annotation host callback.
@@ -181,7 +200,7 @@ JSON Views descriptors are not JSON Schema. The packaged `@script-it/json-views-
 
 `JSONContent` includes `JsonViewsSurface` and scopes its styles and presentation state to that instance. State is in-memory unless the host supplies the presentation-state callbacks above. Navigation and hidden columns are never stored in a module-global cache. Each `JsonViewsProvider` also owns independent default registries. No host Tailwind installation is required. Use `theme="light"` or `theme="dark"` for explicit sibling themes; `inherit` reads the nearest host `data-json-views-theme`, `.light`, or `.dark`, falling back to light. It does not independently choose an OS theme.
 
-Override semantic tokens on a containing element with `--json-views-background`, `--json-views-foreground`, `--json-views-card`, `--json-views-border`, `--json-views-muted`, `--json-views-accent`, `--json-views-primary`, `--json-views-ring`, their foreground companions, and `--json-views-font-family`. Popups receive the same theme and tokens in a per-instance portal root. Use `portalContainer` for a host modal/overlay boundary; the supplied element should belong to the same document. `JsonViewsSurface` is exported for compositions using lower-level components.
+Override semantic tokens on a containing element with `--json-views-background`, `--json-views-foreground`, `--json-views-card`, `--json-views-border`, `--json-views-muted`, `--json-views-accent`, `--json-views-primary`, `--json-views-ring`, their foreground companions, `--json-views-font-family`, and `--json-views-table-cell-max-height`. Popups receive the same theme and tokens in a per-instance portal root. Use `portalContainer` for a host modal/overlay boundary; the supplied element should belong to the same document. `JsonViewsSurface` is exported for compositions using lower-level components.
 
 ```css
 .product-json-viewer {
@@ -229,7 +248,9 @@ Accepted values are `null`, `YYYY-MM-DD`, and ISO 8601 date-times with seconds.
 
 ### Editor behavior
 
-Clicking a date opens its calendar immediately. Day, time, and timezone changes remain in a draft until Save; Cancel and Escape discard the draft. Enabling time requires a valid hour and minute and saves seconds. Floating date-times remain timezone-less unless the user chooses a timezone. Changing between timezone offsets preserves the instant; adding or removing a timezone preserves the displayed wall-clock time. Disabling time warns before saving the calendar date alone.
+Enter saves a field and Escape cancels it; leaving a field also saves. In multiline text, Shift+Enter inserts a line break. Long-form Markdown, body, and HTML fields keep Enter for line breaks and save on Ctrl/Cmd+Enter. On mobile, where soft keyboards have no Shift+Enter, Return always inserts a line break in multiline fields, and leaving the field or Ctrl/Cmd+Enter saves.
+
+Clicking a date opens its calendar immediately. Day, time, and timezone changes remain in a draft until Save, or Enter in the time field; Cancel and Escape discard the draft. Enabling time requires a valid hour and minute and saves seconds. Floating date-times remain timezone-less unless the user chooses a timezone. Changing between timezone offsets preserves the instant; adding or removing a timezone preserves the displayed wall-clock time. Disabling time warns before saving the calendar date alone.
 
 Clear is disabled for required fields. Optional dates default to `null`; a host can remove the property instead:
 
@@ -279,7 +300,7 @@ A view with `display: "html"` contains its HTML and CSS in the same `$jsonviews.
 
 - `jv-value` element: display a scalar value without editing.
 - `jv-field` element: display a scalar value and open the existing schema/registry field editor when clicked. Shared editors appear in the product layer, outside the authored CSS.
-- `jv-bind` on input or textarea: edit the source value. Supported inputs are text, number, range, and checkbox. Range commits at pointer/keyboard completion; text and number commit on blur or Enter; textarea uses blur or Ctrl/Cmd+Enter. Escape cancels. A failed native edit can be retried by completing the interaction again.
+- `jv-bind` on input or textarea: edit the source value. Supported inputs are text, number, range, and checkbox. Range commits at pointer/keyboard completion; text, number, and textarea commit on blur or Enter, and Shift+Enter inserts a line break in a textarea (on mobile, Return inserts it and Ctrl/Cmd+Enter commits). Escape cancels. A failed native edit can be retried by completing the interaction again.
 - `jv-value` attribute on progress/meter: bind the numeric value property.
 - `jv-attr-<attribute>`: read a scalar into an allowed attribute: title, aria-label, aria-valuenow, aria-valuetext, x/y/cx/cy/x1/x2/y1/y2/width/height/r/rx/ry/fill/stroke/opacity. URLs are not permitted in attributes.
 - `jv-repeat source="$.tasks" as="task" key="id"`: repeat over an array. Aliases use ordinary path suffixes (`task.title`, `task['odd.key']`); nested repeats can reference outer aliases. Keys must be unique strings or finite numbers. Unkeyed arrays can display/edit against an unchanged acknowledged document, but have no stable row identity across reorder.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { CSVContent, JSONContent, StructuredDataContent, type CSVContentProps, type JSONContentProps, type JsonViewClearBehavior, type MetadataPersistence, type MetadataPersistenceRequest, type ObjectRootConversionRequest, type StructuredDataContentProps, } from './json/json-content.js';
 export { JsonViewer, type JsonViewJsonEditing } from './json/json-view.js';
+export type { JsonViewsTableCellOptions } from './structured-data/table-cell-options.js';
 export { JsonViewsProvider, JsonViewWidgetRegistry, createDefaultWidgetRegistry, useJsonViewsRegistries, type JsonViewEditWidget, type JsonViewEditWidgetProps, type JsonViewDisplayWidget, type JsonViewDisplayWidgetProps, type JsonViewWidgetDefinition, type JsonViewWidgetRegistration, type JsonViewsRegistryValue, } from './widget-registry.js';
 export { DateValueDisplay, DateValueEditor } from './widgets/date-picker-widget.js';
 export { InlineFeedbackAction } from './primitives/inline-feedback-action.js';

package/dist/json/html-view/format-value.d.ts

@@ -0,0 +1,5 @@
+/** Explicit, text-only presentation. Never evaluates template expressions. */
+export declare function formatHtmlValue(value: unknown, attrs: Record<string, string>, resolve: (binding: string) => unknown): string | undefined;
+/** The editor shows human units; the source retains its API encoding. */
+export declare function htmlValueForEditing(value: unknown, attrs: Record<string, string>, resolve?: (binding: string) => unknown): unknown;
+export declare function htmlValueFromEditing(value: unknown, attrs: Record<string, string>, resolve?: (binding: string) => unknown): unknown;

package/dist/json/html-view/format-value.js

@@ -0,0 +1,84 @@
+/** Explicit, text-only presentation. Never evaluates template expressions. */
+export function formatHtmlValue(value, attrs, resolve) {
+    if (attrs.labels) {
+        const labels = JSON.parse(attrs.labels);
+        if (!labels || typeof labels !== 'object' || Array.isArray(labels) || Object.values(labels).some(label => typeof label !== 'string'))
+            throw new Error('labels must be a JSON object of string labels');
+        if (Object.hasOwn(labels, String(value)))
+            return labels[String(value)];
+    }
+    if (!attrs.format)
+        return undefined;
+    if (value == null)
+        return '—';
+    if (attrs.format === 'currency-minor') {
+        if (typeof value !== 'number' || !Number.isSafeInteger(value))
+            throw new Error('currency-minor requires a safe integer');
+        const formatter = currencyFormatter(attrs, resolve);
+        return formatter.format(value / 10 ** (formatter.resolvedOptions().maximumFractionDigits ?? 2));
+    }
+    if (['date', 'time', 'datetime'].includes(attrs.format)) {
+        const unit = attrs['date-unit'] ?? 'iso';
+        let date;
+        if (unit === 'seconds' || unit === 'milliseconds') {
+            if (!(typeof value === 'number' || typeof value === 'string' && /^-?\d+(\.\d+)?$/.test(value)))
+                throw new Error('Timestamp must be numeric');
+            date = new Date(Number(value) * (unit === 'seconds' ? 1000 : 1));
+        }
+        else if (unit === 'iso' && typeof value === 'string' && /^\d{4}-\d{2}-\d{2}(T.*)?$/.test(value))
+            date = new Date(value);
+        else
+            throw new Error('Dates require an ISO value or an explicit timestamp unit');
+        if (!Number.isFinite(date.getTime()))
+            throw new Error('Invalid date');
+        return new Intl.DateTimeFormat('en-US', {
+            timeZone: attrs['time-zone'] ?? 'UTC',
+            ...(attrs.format !== 'time' ? { month: 'short', day: 'numeric', ...(attrs.format === 'date' ? { year: 'numeric' } : {}) } : {}),
+            ...(attrs.format !== 'date' ? { hour: 'numeric', minute: '2-digit' } : {}),
+        }).format(date);
+    }
+    if (attrs.format === 'base64url') {
+        if (typeof value !== 'string' || !/^[\w-]*={0,2}$/.test(value) || value.replace(/=+$/, '').length % 4 === 1)
+            throw new Error('Invalid base64url text');
+        const bytes = Uint8Array.from(atob(value.replace(/-/g, '+').replace(/_/g, '/')), character => character.charCodeAt(0));
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    throw new Error(`Unsupported value format: ${attrs.format}`);
+}
+function currencyFormatter(attrs, resolve) {
+    const currency = attrs['currency-bind'] ? resolve(attrs['currency-bind']) : attrs.currency;
+    if (typeof currency !== 'string' || !/^[a-z]{3}$/i.test(currency))
+        throw new Error('currency-minor requires a currency code');
+    return new Intl.NumberFormat('en-US', { style: 'currency', currency });
+}
+function minorUnitFactor(attrs, resolve) {
+    return 10 ** (currencyFormatter(attrs, resolve).resolvedOptions().maximumFractionDigits ?? 2);
+}
+/** The editor shows human units; the source retains its API encoding. */
+export function htmlValueForEditing(value, attrs, resolve = () => undefined) {
+    if (attrs.format === 'base64url')
+        return formatHtmlValue(value, attrs, resolve);
+    if (attrs.format === 'currency-minor' && typeof value === 'number')
+        return value / minorUnitFactor(attrs, resolve);
+    return value;
+}
+export function htmlValueFromEditing(value, attrs, resolve = () => undefined) {
+    if (attrs.format === 'base64url') {
+        if (typeof value !== 'string')
+            throw new Error('Enter text');
+        const bytes = new TextEncoder().encode(value);
+        let binary = '';
+        for (const byte of bytes)
+            binary += String.fromCharCode(byte);
+        return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    }
+    if (attrs.format === 'currency-minor') {
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            throw new Error('Enter a finite amount');
+        const scaled = value * minorUnitFactor(attrs, resolve), rounded = Math.round(scaled);
+        if (!Number.isSafeInteger(rounded) || Math.abs(scaled - rounded) > 1e-7)
+            throw new Error('Amount has unsupported precision');
+        return rounded;
+    }
+    return value;
+}

package/dist/json/html-view/native-control.d.ts

@@ -1,4 +1,5 @@
 import type { ValuePath } from '@script-it/json-views-core';
+import { type EnterKeyEvent } from '../../lib/enter-key.js';
 import type { JsonViewJsonEditing } from '../view-types.js';
 export declare function NativeHtmlControl({ tag, props, path, value, editing, report }: {
     tag: string;
@@ -16,10 +17,7 @@ export declare function NativeHtmlControl({ tag, props, path, value, editing, re
     onBlur: () => void;
     onPointerUp: () => void;
     onKeyUp: () => void;
-    onKeyDown: (event: {
-        key: string;
-        ctrlKey: boolean;
-        metaKey: boolean;
+    onKeyDown: (event: EnterKeyEvent & {
         preventDefault: () => void;
     }) => void;
     checked: boolean;
@@ -33,10 +31,7 @@ export declare function NativeHtmlControl({ tag, props, path, value, editing, re
     onBlur: () => void;
     onPointerUp: () => void;
     onKeyUp: () => void;
-    onKeyDown: (event: {
-        key: string;
-        ctrlKey: boolean;
-        metaKey: boolean;
+    onKeyDown: (event: EnterKeyEvent & {
         preventDefault: () => void;
     }) => void;
     value: string;

package/dist/json/html-view/native-control.js

@@ -1,5 +1,6 @@
 import { createElement, useContext, useEffect, useRef, useState } from 'react';
 import { EditBaseContext } from '../../structured-data/edit-base.js';
+import { submitsOnEnter, useEnterKeyBehavior } from '../../lib/enter-key.js';
 export function NativeHtmlControl({ tag, props, path, value, editing, report }) {
     const base = useContext(EditBaseContext);
     const [draft, setDraft] = useState(value == null ? '' : String(value));
@@ -8,6 +9,7 @@ export function NativeHtmlControl({ tag, props, path, value, editing, report })
     const original = useRef({ base, path });
     const pending = useRef(false), changed = useRef(false), draftRef = useRef(draft);
     const type = props.type ?? 'text';
+    const enterKey = useEnterKeyBehavior();
     useEffect(() => { if (!active) {
         const next = value == null ? '' : String(value);
         setDraft(next);
@@ -87,7 +89,7 @@ export function NativeHtmlControl({ tag, props, path, value, editing, report })
                 cancel();
                 report('');
             }
-            if (event.key === 'Enter' && (tag !== 'textarea' || event.ctrlKey || event.metaKey)) {
+            if (submitsOnEnter(event, { multiline: tag === 'textarea', enterKey })) {
                 event.preventDefault();
                 void commit();
             }

package/dist/json/html-view/template.js

@@ -2,6 +2,7 @@ const tags = new Set('main article section header footer nav aside div span h1 h
 const dangerous = new Set('script iframe object embed base meta link form foreignobject animate animatemotion animatetransform set style'.split(' '));
 export const boundAttributes = new Set('title aria-label aria-valuenow aria-valuetext x y cx cy x1 x2 y1 y2 width height r rx ry fill stroke opacity'.split(' '));
 const attributes = new Set('id class title role type min max step placeholder rows cols maxlength disabled readonly tabindex for value checked max low high optimum width height viewBox preserveAspectRatio d x y cx cy x1 x2 y1 y2 r rx ry points fill stroke stroke-width opacity text-anchor font-size font-family alt bind source as key'.toLowerCase().split(' '));
+const valueAttributes = new Set('format labels currency currency-bind date-unit time-zone sync-bind byte-length-bind'.split(' '));
 export function parseHtmlTemplate(doc, html) {
     const template = doc.createElement('template');
     // Template contents are inert; parsed only in the CSP-restricted frame document.
@@ -29,6 +30,10 @@ export function parseHtmlTemplate(doc, html) {
         const attrs = {};
         for (const attr of Array.from(element.attributes)) {
             const name = attr.name.toLowerCase(), value = attr.value;
+            if ((tag === 'jv-value' || tag === 'jv-field') && valueAttributes.has(name) || tag === 'jv-repeat' && name === 'order') {
+                attrs[name] = value;
+                continue;
+            }
             if (name === 'src' && tag === 'img' && /^data:image\/(png|jpeg|gif|webp);base64,[A-Za-z0-9+/=]+$/.test(value) && value.length <= 256 * 1024) {
                 attrs.src = value;
                 continue;

package/dist/json/html-view.js

@@ -10,6 +10,7 @@ import { SchemaEditor } from './schema-value.js';
 import { useJsonSourceLiterals } from './source-literals.js';
 import { parseHtmlTemplate } from './html-view/template.js';
 import { NativeHtmlControl } from './html-view/native-control.js';
+import { formatHtmlValue, htmlValueForEditing, htmlValueFromEditing } from './html-view/format-value.js';
 const skeleton = `<!doctype html><html><head><meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src 'none'; connect-src 'none'; object-src 'none'; frame-src 'none'; base-uri 'none'; form-action 'none'"><style>body{margin:0;font:14px system-ui;background:var(--jv-background);color:var(--jv-foreground)}*{box-sizing:border-box}jv-field,jv-value{display:inline}button.jv-field{font:inherit;color:inherit;background:transparent;border:0;padding:0;text-align:inherit;cursor:pointer}button.jv-field:hover{outline:1px dashed currentColor}button.jv-field:focus-visible{outline:2px solid currentColor}</style></head><body><div id="mount"></div></body></html>`;
 export function HtmlView({ compiled, view, editing, fillHeight, onCurrentPathChange }) {
     const frame = useRef(null), editorRef = useRef(null);
@@ -101,7 +102,12 @@ export function HtmlView({ compiled, view, editing, fillHeight, onCurrentPathCha
                 if (!Array.isArray(resolved.value))
                     throw new Error('jv-repeat source must be an array');
                 const keys = htmlRepeatKeys(resolved.value, node.attrs.key);
-                return resolved.value.map((_, index) => _jsx(Fragment, { children: render(node.children, { ...aliases, [alias]: [...resolved.sourcePath, index] }) }, `${node.id}:${keys[index]}`));
+                if (node.attrs.order && !['forward', 'reverse'].includes(node.attrs.order))
+                    throw new Error('Repeat order must be forward or reverse');
+                const indices = resolved.value.map((_, index) => index);
+                if (node.attrs.order === 'reverse')
+                    indices.reverse();
+                return indices.map(index => _jsx(Fragment, { children: render(node.children, { ...aliases, [alias]: [...resolved.sourcePath, index] }) }, `${node.id}:${keys[index]}`));
             }
             const props = { key: node.id };
             const mapping = { class: 'className', for: 'htmlFor', tabindex: 'tabIndex', readonly: 'readOnly', maxlength: 'maxLength', viewbox: 'viewBox', preserveaspectratio: 'preserveAspectRatio', 'stroke-width': 'strokeWidth', 'text-anchor': 'textAnchor', 'font-size': 'fontSize', 'font-family': 'fontFamily' };
@@ -119,9 +125,16 @@ export function HtmlView({ compiled, view, editing, fillHeight, onCurrentPathCha
                 const resolved = resolve(node.attrs.bind ?? '', aliases), value = resolved.value;
                 if (value !== null && typeof value === 'object')
                     throw new Error('Use jv-repeat for arrays and objects');
-                const text = literals(resolved.sourcePath) ?? (value == null ? '—' : String(value));
-                const canEdit = node.tag === 'jv-field' && editing && editing.canReplace?.(resolved.sourcePath) !== false;
-                return _jsx("span", { children: canEdit ? _jsx("button", { className: "jv-field", "aria-label": `Edit ${node.attrs.bind}`, onClick: event => setSelected({ path: resolved.sourcePath, anchor: event.currentTarget, base }), children: text }) : text }, node.id);
+                const resolveValue = (binding) => resolve(binding, aliases).value;
+                const text = formatHtmlValue(value, node.attrs, resolveValue) ?? literals(resolved.sourcePath) ?? (value == null ? '—' : String(value));
+                const sync = node.attrs['sync-bind'] ? resolve(node.attrs['sync-bind'], aliases) : undefined;
+                const byteLength = node.attrs['byte-length-bind'] ? resolve(node.attrs['byte-length-bind'], aliases) : undefined;
+                if (sync && sync.value !== null && typeof sync.value === 'object')
+                    throw new Error('sync-bind must address a scalar');
+                if (byteLength && (node.attrs.format !== 'base64url' || typeof byteLength.value !== 'number'))
+                    throw new Error('byte-length-bind requires base64url and a numeric size field');
+                const canEdit = node.tag === 'jv-field' && editing && [resolved, sync, byteLength].every(target => !target || editing.canReplace?.(target.sourcePath) !== false);
+                return _jsx("span", { children: canEdit ? _jsx("button", { className: "jv-field", "aria-label": node.attrs['aria-label'] ?? `Edit ${node.attrs.bind}`, onClick: event => setSelected({ path: resolved.sourcePath, anchor: event.currentTarget, base, attrs: node.attrs, resolve: resolveValue, syncPath: sync?.sourcePath, byteLengthPath: byteLength?.sourcePath }), children: text }) : text }, node.id);
             }
             if (node.attrs['jv-bind']) {
                 if (node.tag !== 'input' && node.tag !== 'textarea')
@@ -156,8 +169,37 @@ export function HtmlView({ compiled, view, editing, fillHeight, onCurrentPathCha
     const descriptor = selected ? schemaForJsonViewPath(compiled.schema, selected.path)?.descriptor ?? { type: typeof selectedValue === 'number' ? 'number' : typeof selectedValue === 'boolean' ? 'checkbox' : 'text' } : undefined;
     // Text too long for one line gets the resizable multi-line control, matching
     // how tables and records present the same value.
-    const editorDescriptor = descriptor?.type === 'text' && isLongText(selectedValue, descriptor) ? { ...descriptor, multiline: true } : descriptor;
-    return _jsxs("div", { className: "flex min-h-0 flex-1 flex-col", "data-id": "jsonView-html-view", children: [(error || warnings.length > 0) && _jsxs("div", { role: "alert", className: "border-b p-2 text-xs", children: [error || warnings.slice(0, 10).join(' · '), error && _jsx("button", { onClick: () => setError(''), className: "ml-2 underline", children: "Dismiss" })] }), _jsx("iframe", { ref: frame, title: view.name, sandbox: "allow-same-origin", srcDoc: skeleton, className: "w-full flex-1 border-0", style: { minHeight: fillHeight ? 200 : height, height: fillHeight ? '100%' : height }, onLoad: event => { setDoc(event.currentTarget.contentDocument ?? undefined); setSelected(undefined); } }), doc?.getElementById('mount') && createPortal(content, doc.getElementById('mount')), selected && editorDescriptor && editing && portal && createPortal(_jsx("div", { ref: editorRef, "data-anchored-popup": true, className: "z-[120] w-80 rounded-md border bg-card p-3 text-card-foreground shadow-lg", style: position, children: _jsx(EditBaseContext.Provider, { value: base, children: _jsx(SchemaEditor, { descriptor: editorDescriptor, disabled: editing.saving, label: String(selected.path.at(-1) ?? 'value'), variant: "default", value: selectedValue, onCancel: () => { const anchor = selected.anchor; setSelected(undefined); if (anchor.isConnected)
-                            anchor.focus(); }, onCommit: async (value) => { if (selected.base !== base)
-                            throw new Error('This document changed outside this editor. Cancel and reopen it before saving.'); await editing.replace(selected.path, value); } }, `${view.id}:${JSON.stringify(selected.path)}`) }) }), portal)] });
+    let editorValue = selectedValue;
+    let formattedDescriptor = selected?.attrs.format === 'base64url' ? { type: 'text', multiline: true } : descriptor;
+    try {
+        if (selected)
+            editorValue = htmlValueForEditing(selectedValue, selected.attrs, selected.resolve);
+        if (selected?.attrs.format === 'currency-minor' && descriptor) {
+            formattedDescriptor = { ...descriptor };
+            for (const key of ['minimum', 'maximum', 'step']) {
+                if (typeof descriptor[key] === 'number')
+                    formattedDescriptor[key] = htmlValueForEditing(descriptor[key], selected.attrs, selected.resolve);
+            }
+        }
+    }
+    catch {
+        // A source change can invalidate an open field. Its stale-save guard still
+        // rejects the draft; rendering that state must not crash the whole view.
+    }
+    const editorDescriptor = formattedDescriptor?.type === 'text' && isLongText(editorValue, formattedDescriptor) ? { ...formattedDescriptor, multiline: true } : formattedDescriptor;
+    return _jsxs("div", { className: "flex min-h-0 flex-1 flex-col", "data-id": "jsonView-html-view", children: [(error || warnings.length > 0) && _jsxs("div", { role: "alert", className: "border-b p-2 text-xs", children: [error || warnings.slice(0, 10).join(' · '), error && _jsx("button", { onClick: () => setError(''), className: "ml-2 underline", children: "Dismiss" })] }), _jsx("iframe", { ref: frame, title: view.name, sandbox: "allow-same-origin", srcDoc: skeleton, className: "w-full flex-1 border-0", style: { minHeight: fillHeight ? 200 : height, height: fillHeight ? '100%' : height }, onLoad: event => { setDoc(event.currentTarget.contentDocument ?? undefined); setSelected(undefined); } }), doc?.getElementById('mount') && createPortal(content, doc.getElementById('mount')), selected && editorDescriptor && editing && portal && createPortal(_jsx("div", { ref: editorRef, "data-anchored-popup": true, className: "z-[120] w-80 rounded-md border bg-card p-3 text-card-foreground shadow-lg", style: position, children: _jsx(EditBaseContext.Provider, { value: base, children: _jsx(SchemaEditor, { descriptor: editorDescriptor, disabled: editing.saving, label: selected.attrs['aria-label'] ?? String(selected.path.at(-1) ?? 'value'), variant: "default", value: editorValue, onCancel: () => { const anchor = selected.anchor; setSelected(undefined); if (anchor.isConnected)
+                            anchor.focus(); }, onCommit: async (value) => {
+                            if (selected.base !== base)
+                                throw new Error('This document changed outside this editor. Cancel and reopen it before saving.');
+                            const encoded = htmlValueFromEditing(value, selected.attrs, selected.resolve);
+                            const replacements = [{ path: selected.path, value: encoded }];
+                            if (selected.syncPath)
+                                replacements.push({ path: selected.syncPath, value: encoded });
+                            if (selected.byteLengthPath)
+                                replacements.push({ path: selected.byteLengthPath, value: new TextEncoder().encode(String(value)).length });
+                            if (replacements.length > 1)
+                                await editing.replaceMany(replacements);
+                            else
+                                await editing.replace(selected.path, encoded);
+                        } }, `${view.id}:${JSON.stringify(selected.path)}`) }) }), portal)] });
 }

package/dist/json/json-content.d.ts

@@ -4,6 +4,7 @@ import { type JsonDocumentSave, type StructuredDocumentAdapter, type ValuePath }
 import type { UiSize } from '../lib/ui-size.js';
 import type { FileContentEditState } from '../file-content-edit-state.js';
 import { type MetadataPersistence } from '../structured-data/use-metadata-persistence.js';
+import type { JsonViewsTableCellOptions } from '../structured-data/table-cell-options.js';
 import type { JsonViewSchemaExternalWidgetRenderer } from './schema-value.js';
 import type { JsonViewsPresentationState } from '../viewer-state.js';
 export type JsonViewClearBehavior = 'null' | 'remove';
@@ -46,6 +47,8 @@ export interface StructuredDataContentProps {
     sourceVisible?: boolean;
     onSourceVisibleChange?: (visible: boolean) => void;
     clearBehavior?: JsonViewClearBehavior;
+    /** Clamps tall table cells and reveals one on selection (default), or lets rows grow to fit. */
+    tableCells?: JsonViewsTableCellOptions;
     onDraftRowsChange?: (paths: readonly ValuePath[]) => void;
     renderMarkdown?: (content: string) => ReactNode;
     renderExternalWidget?: JsonViewSchemaExternalWidgetRenderer;

package/dist/json/json-content.js

@@ -46,25 +46,31 @@ export function StructuredDataContent(props) {
     return _jsx(JsonViewsSurface, { theme: props.theme, portalContainer: props.portalContainer, presentationState: props.presentationState, onPresentationStateChange: props.onPresentationStateChange, children: _jsx(StructuredDataContentSession, { ...props }, `${props.documentId ?? props.path ?? 'document'}:${props.adapter.format}`) }, props.documentId ?? props.path ?? 'document');
 }
 export function JSONContent(props) {
-    let adapter = jsonObjectFormat;
     // The editable draft is the current document while the source editor is open.
     // Hosts may keep `content` at the last persisted revision until a save finishes,
     // so choosing the adapter from it would incorrectly reject a valid root-shape
     // change (for example, an object replaced with an array).
-    try {
-        adapter = jsonFormatForSource(props.edit?.isEditing ? props.edit.editContent : props.content);
-    }
-    catch { /* Recovery handles invalid JSON. */ }
+    const source = props.edit?.isEditing ? props.edit.editContent : props.content;
+    // Choosing the adapter parses the whole document; hosts re-render far more often than the text changes.
+    const adapter = useMemo(() => {
+        try {
+            return jsonFormatForSource(source);
+        }
+        catch { /* Recovery handles invalid JSON. */ }
+        return jsonObjectFormat;
+    }, [source]);
     return _jsx(StructuredDataContent, { ...props, adapter: adapter });
 }
 export function CSVContent(props) {
     return _jsx(StructuredDataContent, { ...props, adapter: csvFormat });
 }
-function StructuredDataContentSession({ content, adapter, documentId, revision, metadata, metadataPersistence, presentationState, onMetadataChange, onRequestMetadataPersistence, metadataConversionConfirmation = 'viewer', allowRootArrayWrapping = true, path, uiSize, fillHeight = false, edit, onSave, isSaving, isDirty, saveError, sourceVisible, onSourceVisibleChange, clearBehavior = 'null', onDraftRowsChange, renderExternalWidget, renderMarkdown, }) {
+function StructuredDataContentSession({ content, adapter, documentId, revision, metadata, metadataPersistence, presentationState, onMetadataChange, onRequestMetadataPersistence, metadataConversionConfirmation = 'viewer', allowRootArrayWrapping = true, path, uiSize, fillHeight = false, edit, onSave, isSaving, isDirty, saveError, sourceVisible, onSourceVisibleChange, clearBehavior = 'null', tableCells, onDraftRowsChange, renderExternalWidget, renderMarkdown, }) {
     const { types } = useJsonViewsRegistries();
     const [editorGeneration, setEditorGeneration] = useState(0);
     const [draftRows, setDraftRows] = useState([]);
-    const [localSourceVisible, setLocalSourceVisible] = useState(() => presentationState?.activeView ? presentationState.activeView === 'source' : adapter.format !== 'csv' && prefersSource(content, metadata));
+    // A host that controls `sourceVisible` never reads the local flag, so the default-view heuristic can be skipped.
+    const [localSourceVisible, setLocalSourceVisible] = useState(() => sourceVisible === undefined
+        && (presentationState?.activeView ? presentationState.activeView === 'source' : adapter.format !== 'csv' && prefersSource(content, metadata)));
     const [currentViewPaths, setCurrentViewPaths] = useState([[]]);
     const rememberSourcePaths = useCallback((path, paths) => {
         setCurrentViewPaths(paths ?? [path]);
@@ -251,7 +257,7 @@ function StructuredDataContentSession({ content, adapter, documentId, revision,
             const rawView = views[viewDeclarationIndex];
             if (!isRecord(rawView))
                 throw new Error('This table view cannot be updated');
-            const existingView = compileJsonViewMetadata(root).views.find((view) => view.declarationIndex === viewDeclarationIndex);
+            const existingView = compileJsonViewMetadata(root, undefined, { validateValues: false }).views.find((view) => view.declarationIndex === viewDeclarationIndex);
             const columns = Array.isArray(rawView.columns) && rawView.columns.length > 0 ? [...rawView.columns]
                 : existingView ? projectJsonViewCollection(root, { ...existingView, filter: undefined, sort: [] }).columns.map((column) => ({ label: column.label, path: column.path.source })) : [];
             views[viewDeclarationIndex] = { ...rawView, columns: [...columns, { label: typeof descriptor.title === 'string' ? descriptor.title : property, path: schemaPath }] };
@@ -315,7 +321,7 @@ function StructuredDataContentSession({ content, adapter, documentId, revision,
         if (!metadataWritable || !compiled)
             throw new Error('These annotations cannot be edited');
         const next = withOptionColor(currentMetadata(), schemaPath, optionValue, color);
-        const candidate = compileJsonViewMetadata(parsed.root, types, { metadata: next });
+        const candidate = compileJsonViewMetadata(parsed.root, types, { metadata: next, validateValues: false });
         if (!candidate.schema.some((entry) => entry.declaration === schemaPath)) {
             throw new Error(candidate.diagnostics.find((item) => item.scope === 'schema')?.message ?? 'Invalid option color');
         }
@@ -344,7 +350,7 @@ function StructuredDataContentSession({ content, adapter, documentId, revision,
             ...(base.schema === undefined && compiled.inference && Object.keys(compiled.inference.schema).length > 0 ? { schema: compiled.inference.schema } : {}),
             views,
         };
-        const candidate = compileJsonViewMetadata(parsed.root, types, { metadata: next });
+        const candidate = compileJsonViewMetadata(parsed.root, types, { metadata: next, validateValues: false });
         if (candidate.views.length !== views.length)
             throw new Error(candidate.diagnostics.find((item) => item.scope === 'view')?.message ?? 'Invalid view');
         if (persistence === 'session') {
@@ -380,8 +386,9 @@ function StructuredDataContentSession({ content, adapter, documentId, revision,
     };
     const saveStatus = _jsx(ViewSaveStatus, { embedded: embedded, objectRoot: adapter.format === 'json-object' && isRecord(parsed.root), conversionConfirmation: metadataConversionConfirmation, saving: document.saving, dirty: isDirty || document.dirty, invalidSourceError: parsed.error ?? undefined, invalidFormat: parsed.error ? adapter.format === 'csv' ? 'CSV' : 'JSON' : undefined, error: document.error || saveError || (!metadataWritable ? 'View settings need repair before saving.' : undefined), onSave: document.canCommit && metadataWritable && (isRecord(parsed.root) && adapter.format === 'json-object' || onRequestMetadataPersistence) ? saveViewsToSource : undefined });
     const sourceFormat = adapter.format === 'csv' ? 'CSV' : 'JSON';
+    // Formatting and target ranges are only consumed by the source panel, so they wait until it is shown.
     const formattedSource = useMemo(() => {
-        if (adapter.format === 'csv')
+        if (adapter.format === 'csv' || !showingSource)
             return undefined;
         try {
             return formatJsonSource(document.content);
@@ -389,12 +396,12 @@ function StructuredDataContentSession({ content, adapter, documentId, revision,
         catch {
             return undefined;
         }
-    }, [adapter.format, document.content]);
+    }, [adapter.format, document.content, showingSource]);
     const formatSource = !document.canCommit || formattedSource === undefined || formattedSource === document.content.trim()
         ? undefined : () => editSource(formattedSource);
     const sourceControl = _jsxs(_Fragment, { children: [showingSource && formatSource && _jsx(SourceFormatButton, { format: sourceFormat, disabled: document.saving, onFormat: formatSource }), saveStatus] });
     const sourceTargetRanges = useMemo(() => {
-        if (adapter.format === 'csv' || currentViewPaths.length === 0 || coversAllDocumentData(parsed.root, currentViewPaths))
+        if (adapter.format === 'csv' || !showingSource || currentViewPaths.length === 0 || coversAllDocumentData(parsed.root, currentViewPaths))
             return [];
         try {
             return jsonSourceRangesAtPaths(document.content, currentViewPaths);
@@ -402,7 +409,7 @@ function StructuredDataContentSession({ content, adapter, documentId, revision,
         catch {
             return [];
         }
-    }, [adapter.format, currentViewPaths, document.content, parsed.root]);
+    }, [adapter.format, currentViewPaths, document.content, parsed.root, showingSource]);
     const sourceEditor = (_jsx(TooltipProvider, { children: _jsx(SourceEditor, { embedded: !parsed.error, saveStatus: saveStatus, content: document.content, dirty: isDirty ?? document.dirty, fillHeight: fillHeight, format: sourceFormat, invalidSourceError: parsed.error, onChange: editSource, onClose: () => setShowingSource(false), onFormat: formatSource, readOnly: !document.canCommit, saveError: document.error ?? saveError, saving: document.saving, targetRanges: sourceTargetRanges }) }));
     if (parsed.error)
         return sourceEditor;
@@ -429,5 +436,5 @@ function StructuredDataContentSession({ content, adapter, documentId, revision,
         replace: replaceValue, replaceMany: replaceValues, ...(metadataWritable ? { setOptionColor } : {}), replaceViews,
         removeMany: removeValues, saving: document.saving,
     } : undefined;
-    return (_jsxs(TooltipProvider, { children: [document.error && _jsxs("div", { className: "grid gap-2 px-4 py-2 text-sm", children: [_jsx("p", { role: "alert", className: "text-destructive", children: document.error }), document.dirty && _jsxs("div", { className: "flex flex-wrap gap-2", children: [_jsx("button", { type: "button", disabled: document.saving, className: "rounded-md border border-border px-2 py-1 disabled:opacity-50", onClick: () => { void document.commit((source) => source).catch(() => { }); }, children: "Retry save" }), _jsx("button", { type: "button", disabled: document.saving, className: "rounded-md border border-border px-2 py-1 disabled:opacity-50", onClick: () => { document.reset(); setEditorGeneration((generation) => generation + 1); }, children: "Discard unsaved changes" }), _jsxs("details", { className: "basis-full", children: [_jsx("summary", { children: "Unsaved source" }), _jsx("pre", { className: "max-h-64 overflow-auto whitespace-pre-wrap font-mono text-xs", children: document.content })] })] })] }), formatDiagnostics.length > 0 && _jsxs("details", { className: "px-4 py-2 text-sm", children: [_jsx("summary", { children: formatDiagnostics.some((item) => item.severity === 'error') ? 'This document needs repair before structured editing.' : 'Some values require source editing to preserve their exact representation.' }), _jsx(JsonSourceRecovery, { source: document.content, error: formatDiagnostics.map((item) => item.message).join(' '), onCommit: recoveryCommit })] }), _jsx(JsonRendererBoundary, { source: document.content, onCommit: recoveryCommit, children: _jsx(JsonSourceLiteralsProvider, { diagnostics: sourceDiagnostics, children: _jsx(EditBaseContext.Provider, { value: document.acknowledgedContent, children: _jsx(JsonViewer, { compiled: compiled, defaultKey: path?.split('/').pop() || 'root', filePath: documentId ?? path, sourceContent: sourceEditor, sourceVisible: showingSource, onSourceVisibleChange: setShowingSource, tabularRoot: adapter.format === 'csv', editing: editing, onCurrentPathChange: rememberSourcePaths, renderExternalWidget: renderExternalWidget, renderMarkdown: renderMarkdown, sourceControl: sourceControl, uiSize: uiSize, fillHeight: fillHeight }) }) }) }, editorGeneration)] }));
+    return (_jsxs(TooltipProvider, { children: [document.error && _jsxs("div", { className: "grid gap-2 px-4 py-2 text-sm", children: [_jsx("p", { role: "alert", className: "text-destructive", children: document.error }), document.dirty && _jsxs("div", { className: "flex flex-wrap gap-2", children: [_jsx("button", { type: "button", disabled: document.saving, className: "rounded-md border border-border px-2 py-1 disabled:opacity-50", onClick: () => { void document.commit((source) => source).catch(() => { }); }, children: "Retry save" }), _jsx("button", { type: "button", disabled: document.saving, className: "rounded-md border border-border px-2 py-1 disabled:opacity-50", onClick: () => { document.reset(); setEditorGeneration((generation) => generation + 1); }, children: "Discard unsaved changes" }), _jsxs("details", { className: "basis-full", children: [_jsx("summary", { children: "Unsaved source" }), _jsx("pre", { className: "max-h-64 overflow-auto whitespace-pre-wrap font-mono text-xs", children: document.content })] })] })] }), formatDiagnostics.length > 0 && _jsxs("details", { className: "px-4 py-2 text-sm", children: [_jsx("summary", { children: formatDiagnostics.some((item) => item.severity === 'error') ? 'This document needs repair before structured editing.' : 'Some values require source editing to preserve their exact representation.' }), _jsx(JsonSourceRecovery, { source: document.content, error: formatDiagnostics.map((item) => item.message).join(' '), onCommit: recoveryCommit })] }), _jsx(JsonRendererBoundary, { source: document.content, onCommit: recoveryCommit, children: _jsx(JsonSourceLiteralsProvider, { diagnostics: sourceDiagnostics, children: _jsx(EditBaseContext.Provider, { value: document.acknowledgedContent, children: _jsx(JsonViewer, { compiled: compiled, defaultKey: path?.split('/').pop() || 'root', filePath: documentId ?? path, sourceContent: sourceEditor, sourceVisible: showingSource, onSourceVisibleChange: setShowingSource, tabularRoot: adapter.format === 'csv', editing: editing, onCurrentPathChange: rememberSourcePaths, renderExternalWidget: renderExternalWidget, renderMarkdown: renderMarkdown, sourceControl: sourceControl, tableCells: tableCells, uiSize: uiSize, fillHeight: fillHeight }) }) }) }, editorGeneration)] }));
 }

package/dist/json/json-view.d.ts

@@ -1,3 +1,3 @@
 import { type JsonViewerProps } from './view-types.js';
-export declare function JsonViewer({ compiled, defaultKey, editing, filePath, fillHeight, onCurrentPathChange, renderExternalWidget, renderMarkdown, sourceControl, sourceContent, sourceVisible, onSourceVisibleChange, uiSize, viewsEnabled, tabularRoot, }: JsonViewerProps): import("react").JSX.Element;
+export declare function JsonViewer({ compiled, defaultKey, editing, filePath, fillHeight, onCurrentPathChange, renderExternalWidget, renderMarkdown, sourceControl, sourceContent, sourceVisible, onSourceVisibleChange, tableCells, uiSize, viewsEnabled, tabularRoot, }: JsonViewerProps): import("react").JSX.Element;
 export type { JsonViewJsonEditing } from './view-types.js';