json-schema-to-blocks 0.1.0
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/LICENSE +21 -0
- package/README.md +118 -0
- package/constraints.d.ts +10 -0
- package/constraints.js +31 -0
- package/convert.d.ts +18 -0
- package/convert.js +267 -0
- package/esm/constraints.js +28 -0
- package/esm/convert.js +263 -0
- package/esm/index.js +5 -0
- package/esm/rules.js +109 -0
- package/esm/schema.js +89 -0
- package/esm/types.js +8 -0
- package/index.d.ts +5 -0
- package/index.js +21 -0
- package/package.json +50 -0
- package/rules.d.ts +8 -0
- package/rules.js +113 -0
- package/schema.d.ts +20 -0
- package/schema.js +96 -0
- package/types.d.ts +110 -0
- package/types.js +9 -0
package/schema.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** Schema-shape helpers shared by the rules and the converter. */
|
|
2
|
+
import type { JSONSchema, JSONSchemaType, UIAnnotation } from './types';
|
|
3
|
+
/**
|
|
4
|
+
* A union with `null` is how nullability is spelled in JSON Schema; the primary
|
|
5
|
+
* type is the non-null member so `['string', 'null']` still lowers to an Input.
|
|
6
|
+
*/
|
|
7
|
+
export declare function primaryType(schema: JSONSchema): JSONSchemaType | undefined;
|
|
8
|
+
export declare function isNullable(schema: JSONSchema): boolean;
|
|
9
|
+
export declare function annotation(schema: JSONSchema): UIAnnotation;
|
|
10
|
+
/**
|
|
11
|
+
* Resolve local `$ref`s (`#/$defs/x`, `#/definitions/x`) against the root.
|
|
12
|
+
* Remote refs are left alone: a resolver would need IO, and an unresolved ref
|
|
13
|
+
* lowers to a JsonEditor rather than failing the whole document.
|
|
14
|
+
*/
|
|
15
|
+
export declare function createResolver(root: JSONSchema): (schema: JSONSchema) => JSONSchema;
|
|
16
|
+
/**
|
|
17
|
+
* Flatten `allOf` into its parent. Composition-by-intersection has no UI
|
|
18
|
+
* meaning: the fields of every member belong to the same group.
|
|
19
|
+
*/
|
|
20
|
+
export declare function mergeAllOf(schema: JSONSchema, resolve: (schema: JSONSchema) => JSONSchema): JSONSchema;
|
package/schema.js
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/** Schema-shape helpers shared by the rules and the converter. */
|
|
3
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
|
+
exports.primaryType = primaryType;
|
|
5
|
+
exports.isNullable = isNullable;
|
|
6
|
+
exports.annotation = annotation;
|
|
7
|
+
exports.createResolver = createResolver;
|
|
8
|
+
exports.mergeAllOf = mergeAllOf;
|
|
9
|
+
/**
|
|
10
|
+
* A union with `null` is how nullability is spelled in JSON Schema; the primary
|
|
11
|
+
* type is the non-null member so `['string', 'null']` still lowers to an Input.
|
|
12
|
+
*/
|
|
13
|
+
function primaryType(schema) {
|
|
14
|
+
const { type } = schema;
|
|
15
|
+
if (Array.isArray(type))
|
|
16
|
+
return type.find((entry) => entry !== 'null');
|
|
17
|
+
if (type)
|
|
18
|
+
return type;
|
|
19
|
+
// A schema may describe its type only through structural keywords.
|
|
20
|
+
if (schema.properties)
|
|
21
|
+
return 'object';
|
|
22
|
+
if (schema.items)
|
|
23
|
+
return 'array';
|
|
24
|
+
if (schema.enum || schema.const !== undefined)
|
|
25
|
+
return 'string';
|
|
26
|
+
return undefined;
|
|
27
|
+
}
|
|
28
|
+
function isNullable(schema) {
|
|
29
|
+
return Array.isArray(schema.type) ? schema.type.includes('null') : false;
|
|
30
|
+
}
|
|
31
|
+
function annotation(schema) {
|
|
32
|
+
return schema['x-ui'] ?? {};
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Resolve local `$ref`s (`#/$defs/x`, `#/definitions/x`) against the root.
|
|
36
|
+
* Remote refs are left alone: a resolver would need IO, and an unresolved ref
|
|
37
|
+
* lowers to a JsonEditor rather than failing the whole document.
|
|
38
|
+
*/
|
|
39
|
+
function createResolver(root) {
|
|
40
|
+
const seen = new Set();
|
|
41
|
+
function resolve(schema) {
|
|
42
|
+
const ref = schema.$ref;
|
|
43
|
+
if (!ref || !ref.startsWith('#/'))
|
|
44
|
+
return schema;
|
|
45
|
+
if (seen.has(ref))
|
|
46
|
+
return schema;
|
|
47
|
+
const target = pointer(root, ref);
|
|
48
|
+
if (!target)
|
|
49
|
+
return schema;
|
|
50
|
+
seen.add(ref);
|
|
51
|
+
try {
|
|
52
|
+
// Sibling keywords win over the referenced schema, per JSON Schema 2019-09.
|
|
53
|
+
const { $ref: _ref, ...rest } = schema;
|
|
54
|
+
return resolve({ ...target, ...rest });
|
|
55
|
+
}
|
|
56
|
+
finally {
|
|
57
|
+
seen.delete(ref);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
return resolve;
|
|
61
|
+
}
|
|
62
|
+
function pointer(root, ref) {
|
|
63
|
+
let current = root;
|
|
64
|
+
for (const rawSegment of ref.slice(2).split('/')) {
|
|
65
|
+
const segment = rawSegment.replace(/~1/g, '/').replace(/~0/g, '~');
|
|
66
|
+
if (!current || typeof current !== 'object')
|
|
67
|
+
return undefined;
|
|
68
|
+
current = current[segment];
|
|
69
|
+
}
|
|
70
|
+
return current && typeof current === 'object' ? current : undefined;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Flatten `allOf` into its parent. Composition-by-intersection has no UI
|
|
74
|
+
* meaning: the fields of every member belong to the same group.
|
|
75
|
+
*/
|
|
76
|
+
function mergeAllOf(schema, resolve) {
|
|
77
|
+
if (!schema.allOf?.length)
|
|
78
|
+
return schema;
|
|
79
|
+
const { allOf, ...base } = schema;
|
|
80
|
+
let merged = base;
|
|
81
|
+
for (const member of allOf) {
|
|
82
|
+
const resolved = mergeAllOf(resolve(member), resolve);
|
|
83
|
+
merged = {
|
|
84
|
+
...resolved,
|
|
85
|
+
...merged,
|
|
86
|
+
properties: { ...resolved.properties, ...merged.properties },
|
|
87
|
+
required: [...(resolved.required ?? []), ...(merged.required ?? [])],
|
|
88
|
+
'x-ui': { ...annotation(resolved), ...annotation(merged) },
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
if (!merged.required?.length)
|
|
92
|
+
delete merged.required;
|
|
93
|
+
if (!merged.properties || Object.keys(merged.properties).length === 0)
|
|
94
|
+
delete merged.properties;
|
|
95
|
+
return merged;
|
|
96
|
+
}
|
package/types.d.ts
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for lowering JSON Schema into `blocks-schema` UI documents.
|
|
3
|
+
*
|
|
4
|
+
* Only the keywords this package lowers are modelled; anything else is carried
|
|
5
|
+
* along untouched so a schema is never rejected for being richer than the
|
|
6
|
+
* lowering rules.
|
|
7
|
+
*/
|
|
8
|
+
import type { UINode, UINodeConstraints, UINodeType } from 'blocks-schema';
|
|
9
|
+
export type JSONSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
|
|
10
|
+
/** UI hints authored inline on a schema, under the `x-ui` extension keyword. */
|
|
11
|
+
export interface UIAnnotation {
|
|
12
|
+
/** Force a node type, bypassing widget rules. */
|
|
13
|
+
widget?: UINodeType;
|
|
14
|
+
label?: string;
|
|
15
|
+
description?: string;
|
|
16
|
+
placeholder?: string;
|
|
17
|
+
hidden?: boolean;
|
|
18
|
+
disabled?: boolean;
|
|
19
|
+
className?: string;
|
|
20
|
+
/** Sort weight within its group; lower comes first, unset keeps schema order. */
|
|
21
|
+
order?: number;
|
|
22
|
+
/** Extra props merged onto the produced node. */
|
|
23
|
+
props?: Record<string, unknown>;
|
|
24
|
+
}
|
|
25
|
+
export interface JSONSchema {
|
|
26
|
+
$id?: string;
|
|
27
|
+
$ref?: string;
|
|
28
|
+
$defs?: Record<string, JSONSchema>;
|
|
29
|
+
definitions?: Record<string, JSONSchema>;
|
|
30
|
+
type?: JSONSchemaType | JSONSchemaType[];
|
|
31
|
+
title?: string;
|
|
32
|
+
description?: string;
|
|
33
|
+
format?: string;
|
|
34
|
+
enum?: unknown[];
|
|
35
|
+
const?: unknown;
|
|
36
|
+
default?: unknown;
|
|
37
|
+
examples?: unknown[];
|
|
38
|
+
properties?: Record<string, JSONSchema>;
|
|
39
|
+
required?: string[];
|
|
40
|
+
items?: JSONSchema;
|
|
41
|
+
oneOf?: JSONSchema[];
|
|
42
|
+
anyOf?: JSONSchema[];
|
|
43
|
+
allOf?: JSONSchema[];
|
|
44
|
+
readOnly?: boolean;
|
|
45
|
+
writeOnly?: boolean;
|
|
46
|
+
minLength?: number;
|
|
47
|
+
maxLength?: number;
|
|
48
|
+
pattern?: string;
|
|
49
|
+
minimum?: number;
|
|
50
|
+
maximum?: number;
|
|
51
|
+
exclusiveMinimum?: number;
|
|
52
|
+
exclusiveMaximum?: number;
|
|
53
|
+
multipleOf?: number;
|
|
54
|
+
minItems?: number;
|
|
55
|
+
maxItems?: number;
|
|
56
|
+
'x-ui'?: UIAnnotation;
|
|
57
|
+
[keyword: string]: unknown;
|
|
58
|
+
}
|
|
59
|
+
/** Everything a rule needs to decide on one schema position. */
|
|
60
|
+
export interface FieldContext {
|
|
61
|
+
/** The schema at this position, with `$ref`s already resolved. */
|
|
62
|
+
schema: JSONSchema;
|
|
63
|
+
/** Property name, or `''` for the root schema. */
|
|
64
|
+
name: string;
|
|
65
|
+
/** Dot path from the root, e.g. `billing.address.city`. */
|
|
66
|
+
path: string;
|
|
67
|
+
/** Declared as required by the parent's `required` list. */
|
|
68
|
+
required: boolean;
|
|
69
|
+
/** Normalized primary `type`, or `undefined` when the schema omits it. */
|
|
70
|
+
type?: JSONSchemaType;
|
|
71
|
+
/** Merged `x-ui` annotation for this position. */
|
|
72
|
+
ui: UIAnnotation;
|
|
73
|
+
/** Resolve a `$ref` against the root schema's definitions. */
|
|
74
|
+
resolve: (schema: JSONSchema) => JSONSchema;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* A widget rule maps one schema position to a node type. Rules are tried in
|
|
78
|
+
* order and the first match wins, so app-specific rules are prepended rather
|
|
79
|
+
* than replacing the defaults.
|
|
80
|
+
*/
|
|
81
|
+
export interface WidgetRule {
|
|
82
|
+
/** Identifies the rule so a consumer can replace exactly one default. */
|
|
83
|
+
name: string;
|
|
84
|
+
match: (ctx: FieldContext) => boolean;
|
|
85
|
+
/** Node type to render, or a partial node merged over the derived one. */
|
|
86
|
+
node: UINodeType | ((ctx: FieldContext) => UINodeType | PartialNode);
|
|
87
|
+
}
|
|
88
|
+
/** A rule's contribution to the node built for a schema position. */
|
|
89
|
+
export interface PartialNode {
|
|
90
|
+
type?: UINodeType;
|
|
91
|
+
props?: Record<string, unknown>;
|
|
92
|
+
constraints?: UINodeConstraints;
|
|
93
|
+
children?: UINode[];
|
|
94
|
+
}
|
|
95
|
+
export interface ConvertOptions {
|
|
96
|
+
/** Document id; defaults to the schema `$id` or `'document'`. */
|
|
97
|
+
id?: string;
|
|
98
|
+
/** Widget rules tried before the defaults. */
|
|
99
|
+
rules?: WidgetRule[];
|
|
100
|
+
/** Replace the default rule set entirely instead of prepending to it. */
|
|
101
|
+
replaceDefaultRules?: boolean;
|
|
102
|
+
/** Wrap the fields in a `Form` node (default `true`). */
|
|
103
|
+
form?: boolean;
|
|
104
|
+
/** Value for the form's `submit` label prop. */
|
|
105
|
+
submitLabel?: string;
|
|
106
|
+
/** Root node key (default `'page'`). */
|
|
107
|
+
rootKey?: string;
|
|
108
|
+
/** Include `readOnly` schema properties as disabled fields (default `true`). */
|
|
109
|
+
includeReadOnly?: boolean;
|
|
110
|
+
}
|
package/types.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Types for lowering JSON Schema into `blocks-schema` UI documents.
|
|
4
|
+
*
|
|
5
|
+
* Only the keywords this package lowers are modelled; anything else is carried
|
|
6
|
+
* along untouched so a schema is never rejected for being richer than the
|
|
7
|
+
* lowering rules.
|
|
8
|
+
*/
|
|
9
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|