json-renderer 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -50,6 +50,7 @@ import { resolveBinding } from 'json-renderer/bindings';
50
50
  | **Compose** | Fragment expansion, slot filling, overrides, merge | `compose.ts` |
51
51
  | **Bindings** | `{{ scope.path }}` resolution and scope layering | `bindings.ts` |
52
52
  | **Registry** | Layered node type → handler resolution | `registry.ts` |
53
+ | **Rules** | `FieldDescriptor` and the ordered field → node rule pipeline | `rules.ts` |
53
54
  | **Adapter** | The interface a renderer implements | `adapter.ts` |
54
55
 
55
56
  ## Document
@@ -95,6 +96,30 @@ composition:
95
96
  composeEnvelope(document, { fragments, vocabulary: { fragmentNodeType: 'include' } });
96
97
  ```
97
98
 
99
+ ## Field rules
100
+
101
+ A document source (a JSON Schema, a database table, a task's input contract)
102
+ describes each field as a `FieldDescriptor` and lets rules decide the widget.
103
+ Rules are data — an ordered list, first match wins, defaults last — so a host
104
+ prepends its own instead of forking the converter, and a rule written once
105
+ applies to every source.
106
+
107
+ ```ts
108
+ import { applyWidgetRules, composeWidgetRules, fieldNodeProps } from 'json-renderer';
109
+
110
+ const rules = composeWidgetRules(defaults, [
111
+ { name: 'file', match: (field) => field.format === 'uri', node: 'FileUpload' },
112
+ { name: 'big-enum', match: (field) => (field.enumValues?.length ?? 0) > 20, node: 'Combobox' },
113
+ ]);
114
+
115
+ const partial = applyWidgetRules(descriptor, rules, 'Input');
116
+ const props = { ...fieldNodeProps(descriptor), ...partial.props };
117
+ ```
118
+
119
+ A source extends the descriptor with its own facts for rules that need them —
120
+ `json-schema-to-blocks`' `FieldContext` adds the raw schema — while every
121
+ source-neutral decision reads the shared fields.
122
+
98
123
  ## Adapter contract
99
124
 
100
125
  A renderer is generic over the handler it resolves a node type to (`THandler`)
package/esm/index.js CHANGED
@@ -7,4 +7,5 @@ export * from './fields';
7
7
  export * from './json-schema';
8
8
  export * from './node';
9
9
  export * from './registry';
10
+ export * from './rules';
10
11
  export * from './zod';
package/esm/rules.js ADDED
@@ -0,0 +1,63 @@
1
+ /**
2
+ * The field lowering layer: a source-neutral description of one field, and the
3
+ * ordered rule pipeline that turns it into a node.
4
+ *
5
+ * Every document source (JSON Schema, database metadata, a flow) knows how to
6
+ * describe a field but should not own the widget decisions — "`format: uri`
7
+ * renders as a file picker", "enums over twenty values render as a combobox".
8
+ * Those decisions are data: an ordered list of rules, first match wins, defaults
9
+ * last. Rules written against `FieldDescriptor` are shared across sources, and a
10
+ * source may extend the descriptor with its own facts (the raw schema, the
11
+ * column) for rules that need them.
12
+ */
13
+ /**
14
+ * Order a rule set: caller rules first (so they win), defaults last, unless the
15
+ * caller replaces the defaults outright.
16
+ */
17
+ export function composeWidgetRules(defaults, rules, replaceDefaults) {
18
+ if (replaceDefaults)
19
+ return [...(rules ?? [])];
20
+ return rules?.length ? [...rules, ...defaults] : [...defaults];
21
+ }
22
+ /** Run the pipeline: the first matching rule's contribution, else the fallback type. */
23
+ export function applyWidgetRules(context, rules, fallbackType) {
24
+ for (const rule of rules) {
25
+ if (!rule.match(context))
26
+ continue;
27
+ const result = typeof rule.node === 'function' ? rule.node(context) : rule.node;
28
+ return typeof result === 'string' ? { type: result } : result;
29
+ }
30
+ return { type: fallbackType };
31
+ }
32
+ /**
33
+ * The props every lowered field node carries, before a rule's own props are
34
+ * merged on top. Sources share this so a generated field looks the same whether
35
+ * it came from a schema or a column.
36
+ */
37
+ export function fieldNodeProps(descriptor) {
38
+ const { hints } = descriptor;
39
+ const label = hints.label ?? descriptor.label;
40
+ const description = hints.description ?? descriptor.description;
41
+ return {
42
+ name: descriptor.path,
43
+ ...(label !== undefined ? { label } : {}),
44
+ ...(description !== undefined ? { description } : {}),
45
+ ...(hints.placeholder ? { placeholder: hints.placeholder } : {}),
46
+ ...(descriptor.required ? { required: true } : {}),
47
+ ...(hints.hidden ? { hidden: true } : {}),
48
+ ...(hints.disabled || descriptor.readOnly ? { disabled: true } : {}),
49
+ ...(hints.className ? { className: hints.className } : {}),
50
+ ...(descriptor.nullable ? { nullable: true } : {}),
51
+ ...(descriptor.defaultValue !== undefined ? { defaultValue: descriptor.defaultValue } : {}),
52
+ };
53
+ }
54
+ /** Sort key honouring `hints.order`; fields without one keep source order. */
55
+ export function compareFieldOrder(left, right) {
56
+ if (left.order == null && right.order == null)
57
+ return left.index - right.index;
58
+ if (left.order == null)
59
+ return 1;
60
+ if (right.order == null)
61
+ return -1;
62
+ return left.order - right.order;
63
+ }
package/index.d.ts CHANGED
@@ -7,4 +7,5 @@ export * from './fields';
7
7
  export * from './json-schema';
8
8
  export * from './node';
9
9
  export * from './registry';
10
+ export * from './rules';
10
11
  export * from './zod';
package/index.js CHANGED
@@ -23,4 +23,5 @@ __exportStar(require("./fields"), exports);
23
23
  __exportStar(require("./json-schema"), exports);
24
24
  __exportStar(require("./node"), exports);
25
25
  __exportStar(require("./registry"), exports);
26
+ __exportStar(require("./rules"), exports);
26
27
  __exportStar(require("./zod"), exports);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "json-renderer",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "description": "Framework-agnostic JSON UI document core: envelope and node tree, validation, composition, binding resolution, and the renderer adapter contract",
5
5
  "private": false,
6
6
  "license": "MIT",
@@ -41,5 +41,5 @@
41
41
  "engines": {
42
42
  "node": ">=24.0.0"
43
43
  },
44
- "gitHead": "8321f44d0cc91bb6885f3c843ef8467ebdccec40"
44
+ "gitHead": "47f7c369334a26bf7b944443892b5083acdffb2b"
45
45
  }
package/rules.d.ts ADDED
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The field lowering layer: a source-neutral description of one field, and the
3
+ * ordered rule pipeline that turns it into a node.
4
+ *
5
+ * Every document source (JSON Schema, database metadata, a flow) knows how to
6
+ * describe a field but should not own the widget decisions — "`format: uri`
7
+ * renders as a file picker", "enums over twenty values render as a combobox".
8
+ * Those decisions are data: an ordered list of rules, first match wins, defaults
9
+ * last. Rules written against `FieldDescriptor` are shared across sources, and a
10
+ * source may extend the descriptor with its own facts (the raw schema, the
11
+ * column) for rules that need them.
12
+ */
13
+ import type { NodeConstraints } from './constraints';
14
+ import type { DocumentNode, NodeProps } from './node';
15
+ /** Author-supplied hints that override what a rule would otherwise decide. */
16
+ export interface FieldHints<TType extends string = string> {
17
+ /** Force a node type, bypassing the rules. */
18
+ widget?: TType;
19
+ label?: string;
20
+ description?: string;
21
+ placeholder?: string;
22
+ hidden?: boolean;
23
+ disabled?: boolean;
24
+ className?: string;
25
+ /** Sort weight within its group; lower comes first, unset keeps source order. */
26
+ order?: number;
27
+ /** Extra props merged onto the produced node. */
28
+ props?: NodeProps;
29
+ }
30
+ /**
31
+ * One field, described independently of where it came from. `dataType` and
32
+ * `format` are deliberately open strings: a JSON Schema contributes
33
+ * `'string'`/`'uri'`, a database column `'text'`/`'json'`, and a rule matches on
34
+ * whichever it cares about.
35
+ */
36
+ export interface FieldDescriptor<TType extends string = string> {
37
+ /** Field name within its parent, e.g. `city`. */
38
+ name: string;
39
+ /** Path from the document root, e.g. `billing.address.city`. */
40
+ path: string;
41
+ required: boolean;
42
+ dataType?: string;
43
+ format?: string;
44
+ label?: string;
45
+ description?: string;
46
+ enumValues?: readonly unknown[];
47
+ nullable?: boolean;
48
+ readOnly?: boolean;
49
+ defaultValue?: unknown;
50
+ constraints?: NodeConstraints;
51
+ hints: FieldHints<TType>;
52
+ }
53
+ /** A rule's contribution to the node built for a field. */
54
+ export interface PartialNode<TType extends string = string, TNode extends DocumentNode<TType> = DocumentNode<TType>> {
55
+ type?: TType;
56
+ props?: NodeProps;
57
+ constraints?: NodeConstraints;
58
+ children?: TNode[];
59
+ }
60
+ /**
61
+ * A widget rule maps one field to a node type. Rules are tried in order and the
62
+ * first match wins, so app-specific rules are prepended rather than replacing
63
+ * the defaults.
64
+ */
65
+ export interface WidgetRule<TContext extends FieldDescriptor = FieldDescriptor, TType extends string = string, TNode extends DocumentNode<TType> = DocumentNode<TType>> {
66
+ /** Identifies the rule so a consumer can replace exactly one default. */
67
+ name: string;
68
+ match: (context: TContext) => boolean;
69
+ /** Node type to render, or a partial node merged over the derived one. */
70
+ node: TType | ((context: TContext) => TType | PartialNode<TType, TNode>);
71
+ }
72
+ /**
73
+ * Order a rule set: caller rules first (so they win), defaults last, unless the
74
+ * caller replaces the defaults outright.
75
+ */
76
+ export declare function composeWidgetRules<TRule extends {
77
+ name: string;
78
+ }>(defaults: readonly TRule[], rules?: readonly TRule[], replaceDefaults?: boolean): TRule[];
79
+ /** Run the pipeline: the first matching rule's contribution, else the fallback type. */
80
+ export declare function applyWidgetRules<TContext extends FieldDescriptor, TType extends string, TNode extends DocumentNode<TType>>(context: TContext, rules: readonly WidgetRule<TContext, TType, TNode>[], fallbackType: TType): PartialNode<TType, TNode>;
81
+ /**
82
+ * The props every lowered field node carries, before a rule's own props are
83
+ * merged on top. Sources share this so a generated field looks the same whether
84
+ * it came from a schema or a column.
85
+ */
86
+ export declare function fieldNodeProps(descriptor: FieldDescriptor): NodeProps;
87
+ /** Sort key honouring `hints.order`; fields without one keep source order. */
88
+ export declare function compareFieldOrder(left: {
89
+ order?: number;
90
+ index: number;
91
+ }, right: {
92
+ order?: number;
93
+ index: number;
94
+ }): number;
package/rules.js ADDED
@@ -0,0 +1,69 @@
1
+ "use strict";
2
+ /**
3
+ * The field lowering layer: a source-neutral description of one field, and the
4
+ * ordered rule pipeline that turns it into a node.
5
+ *
6
+ * Every document source (JSON Schema, database metadata, a flow) knows how to
7
+ * describe a field but should not own the widget decisions — "`format: uri`
8
+ * renders as a file picker", "enums over twenty values render as a combobox".
9
+ * Those decisions are data: an ordered list of rules, first match wins, defaults
10
+ * last. Rules written against `FieldDescriptor` are shared across sources, and a
11
+ * source may extend the descriptor with its own facts (the raw schema, the
12
+ * column) for rules that need them.
13
+ */
14
+ Object.defineProperty(exports, "__esModule", { value: true });
15
+ exports.composeWidgetRules = composeWidgetRules;
16
+ exports.applyWidgetRules = applyWidgetRules;
17
+ exports.fieldNodeProps = fieldNodeProps;
18
+ exports.compareFieldOrder = compareFieldOrder;
19
+ /**
20
+ * Order a rule set: caller rules first (so they win), defaults last, unless the
21
+ * caller replaces the defaults outright.
22
+ */
23
+ function composeWidgetRules(defaults, rules, replaceDefaults) {
24
+ if (replaceDefaults)
25
+ return [...(rules ?? [])];
26
+ return rules?.length ? [...rules, ...defaults] : [...defaults];
27
+ }
28
+ /** Run the pipeline: the first matching rule's contribution, else the fallback type. */
29
+ function applyWidgetRules(context, rules, fallbackType) {
30
+ for (const rule of rules) {
31
+ if (!rule.match(context))
32
+ continue;
33
+ const result = typeof rule.node === 'function' ? rule.node(context) : rule.node;
34
+ return typeof result === 'string' ? { type: result } : result;
35
+ }
36
+ return { type: fallbackType };
37
+ }
38
+ /**
39
+ * The props every lowered field node carries, before a rule's own props are
40
+ * merged on top. Sources share this so a generated field looks the same whether
41
+ * it came from a schema or a column.
42
+ */
43
+ function fieldNodeProps(descriptor) {
44
+ const { hints } = descriptor;
45
+ const label = hints.label ?? descriptor.label;
46
+ const description = hints.description ?? descriptor.description;
47
+ return {
48
+ name: descriptor.path,
49
+ ...(label !== undefined ? { label } : {}),
50
+ ...(description !== undefined ? { description } : {}),
51
+ ...(hints.placeholder ? { placeholder: hints.placeholder } : {}),
52
+ ...(descriptor.required ? { required: true } : {}),
53
+ ...(hints.hidden ? { hidden: true } : {}),
54
+ ...(hints.disabled || descriptor.readOnly ? { disabled: true } : {}),
55
+ ...(hints.className ? { className: hints.className } : {}),
56
+ ...(descriptor.nullable ? { nullable: true } : {}),
57
+ ...(descriptor.defaultValue !== undefined ? { defaultValue: descriptor.defaultValue } : {}),
58
+ };
59
+ }
60
+ /** Sort key honouring `hints.order`; fields without one keep source order. */
61
+ function compareFieldOrder(left, right) {
62
+ if (left.order == null && right.order == null)
63
+ return left.index - right.index;
64
+ if (left.order == null)
65
+ return 1;
66
+ if (right.order == null)
67
+ return -1;
68
+ return left.order - right.order;
69
+ }