@powerduck/schema-designer 0.1.0 → 0.1.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 +134 -142
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,213 +5,205 @@
|
|
|
5
5
|
<a href="https://www.powerduck.com/"><img src="https://img.shields.io/badge/website-powerduck.com-f28c28" alt="website"></a>
|
|
6
6
|
</p>
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Build JSON Schema and OpenAPI parameter editing UIs in minutes. Drop-in React components for designing request bodies, response schemas, query/path parameters, and variable-aware text fields — all sharing a single immutable schema engine.
|
|
9
9
|
|
|
10
10
|
**Website**: [https://www.powerduck.com/](https://www.powerduck.com/)
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
---
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Quick Start
|
|
15
|
+
|
|
16
|
+
Install:
|
|
15
17
|
|
|
16
18
|
```sh
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
19
|
+
npm install @powerduck/schema-designer
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Import the CSS once:
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
import "@powerduck/schema-designer/styles.css";
|
|
22
26
|
```
|
|
23
27
|
|
|
24
|
-
|
|
28
|
+
Wrap your app in a `ChakraProvider` (Chakra UI v3 required).
|
|
29
|
+
|
|
30
|
+
### Edit a JSON Schema tree
|
|
25
31
|
|
|
26
32
|
```tsx
|
|
27
33
|
import { useState } from "react";
|
|
28
|
-
import {
|
|
29
|
-
SchemaTreeEditor,
|
|
30
|
-
InlineSchemaEditor,
|
|
31
|
-
ParametersTable,
|
|
32
|
-
} from "@powerduck/schema-designer";
|
|
34
|
+
import { SchemaTreeEditor } from "@powerduck/schema-designer";
|
|
33
35
|
import type { SchemaValue } from "@powerduck/schema-designer";
|
|
34
|
-
import "@powerduck/schema-designer/styles.css";
|
|
35
36
|
|
|
36
|
-
function
|
|
37
|
+
function DesignSchema() {
|
|
37
38
|
const [schema, setSchema] = useState<SchemaValue>({
|
|
38
39
|
type: "object",
|
|
39
|
-
properties: {
|
|
40
|
+
properties: {
|
|
41
|
+
email: { type: "string", format: "email" },
|
|
42
|
+
age: { type: "integer", minimum: 0 },
|
|
43
|
+
},
|
|
44
|
+
required: ["email"],
|
|
40
45
|
});
|
|
46
|
+
|
|
41
47
|
return <SchemaTreeEditor value={schema} onChange={setSchema} />;
|
|
42
48
|
}
|
|
43
49
|
```
|
|
44
50
|
|
|
45
|
-
|
|
51
|
+
### Edit OpenAPI parameters
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
import { ParametersTable } from "@powerduck/schema-designer/react/parameters";
|
|
46
55
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
| `@powerduck/schema-designer/react/inline` | Standalone field constraints, arrays, objects, composition, examples, defaults, and preview |
|
|
52
|
-
| `@powerduck/schema-designer/react/parameters` | Parameter definitions and request value tables |
|
|
53
|
-
| `@powerduck/schema-designer/react/variable-editor` | The retained CodeMirror variable-aware input |
|
|
54
|
-
| `@powerduck/schema-designer/adapters/generator` | Optional Faker, JSON Schema Faker, and Ajv generation adapter |
|
|
55
|
-
| `@powerduck/schema-designer/styles.css` | Combined, scoped component styles; import once |
|
|
56
|
-
| `@powerduck/schema-designer/compat/*` | Migration exports for existing Powerduck code |
|
|
56
|
+
const [parameters, setParameters] = useState([
|
|
57
|
+
{ name: "page", in: "query", schema: { type: "integer", default: 1 } },
|
|
58
|
+
{ name: "limit", in: "query", schema: { type: "integer", default: 20, maximum: 100 } },
|
|
59
|
+
]);
|
|
57
60
|
|
|
58
|
-
|
|
61
|
+
<ParametersTable parameters={parameters} onChange={setParameters} />
|
|
62
|
+
```
|
|
59
63
|
|
|
60
|
-
|
|
64
|
+
### Variable-aware text input
|
|
61
65
|
|
|
62
|
-
|
|
66
|
+
```tsx
|
|
67
|
+
import { VariableTextEditor } from "@powerduck/schema-designer/react/variable-editor";
|
|
63
68
|
|
|
64
|
-
|
|
69
|
+
<VariableTextEditor
|
|
70
|
+
value={url}
|
|
71
|
+
onChange={setUrl}
|
|
72
|
+
variables={[{ name: "baseUrl", value: "https://api.example.com" }]}
|
|
73
|
+
/>
|
|
74
|
+
```
|
|
65
75
|
|
|
66
|
-
|
|
76
|
+
---
|
|
67
77
|
|
|
68
|
-
|
|
78
|
+
## What You Get
|
|
69
79
|
|
|
70
|
-
|
|
80
|
+
| Component | Use case |
|
|
81
|
+
|-----------|----------|
|
|
82
|
+
| **SchemaTreeEditor** | Visual tree for designing JSON Schema — add properties, set types, edit constraints, drag to reorder |
|
|
83
|
+
| **InlineSchemaEditor** | Single-field editor for editing one schema node inline (type, format, enum, examples, composition) |
|
|
84
|
+
| **ParametersTable** | OpenAPI parameter table — design query/path/header/cookie params, or switch to "request" mode to fill values |
|
|
85
|
+
| **VariableTextEditor** | CodeMirror input with `{{variable}}` token support for URLs, headers, and scripts |
|
|
71
86
|
|
|
72
|
-
|
|
87
|
+
---
|
|
73
88
|
|
|
74
|
-
##
|
|
89
|
+
## Common Scenarios
|
|
75
90
|
|
|
76
|
-
|
|
91
|
+
### Design mode vs Request mode
|
|
77
92
|
|
|
78
93
|
```tsx
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
import type { ParameterValues } from "@powerduck/schema-designer";
|
|
82
|
-
|
|
83
|
-
const [values, setValues] = useState<ParameterValues>(() =>
|
|
84
|
-
initializeParameterValues(parameters),
|
|
85
|
-
);
|
|
94
|
+
// Design: edit parameter definitions
|
|
95
|
+
<ParametersTable parameters={params} onChange={setParams} />
|
|
86
96
|
|
|
97
|
+
// Request: fill in values to send (definitions locked)
|
|
87
98
|
<ParametersTable
|
|
88
|
-
parameters={
|
|
99
|
+
parameters={params}
|
|
89
100
|
mode="request"
|
|
90
|
-
values={
|
|
91
|
-
onValuesChange={
|
|
92
|
-
|
|
93
|
-
/>;
|
|
101
|
+
values={requestValues}
|
|
102
|
+
onValuesChange={setRequestValues}
|
|
103
|
+
/>
|
|
94
104
|
```
|
|
95
105
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
`onChange` emits parameter definitions, while `onValuesChange` emits request values and enablement. Both controlled and local request values are supported. `onSelectionChange` retains the original internal row IDs and remains independent of enablement. Use `readOnly` to prevent edits and generation.
|
|
99
|
-
|
|
100
|
-
Generation skips supplied examples and values. A generation that makes no changes does not emit `onValuesChange`. A custom `generateValue(context)` may be asynchronous and receives an abort signal and optional document. Pending results merge only into unchanged rows and unchanged controlled values. Unmounting, entering read-only mode, changing mode or the reference document, or starting another generation cancels the previous operation. Errors are delivered through `onError`. Strict default generation rejects invalid candidates rather than returning an invalid fallback. Unsupported constraints may therefore require an explicit example or custom generator.
|
|
101
|
-
|
|
102
|
-
OpenAPI parameter content and extension fields are preserved. The table is not a complete OpenAPI document validator: hosts remain responsible for cross-parameter constraints such as duplicate names, path-template membership, and the incompatibility of `query` with `querystring` parameters.
|
|
103
|
-
|
|
104
|
-
## Theme and accessibility
|
|
105
|
-
|
|
106
|
-
All editors consume the existing Powerduck CSS tokens, including surface, text, border, radius, focus, and accent variables. Component CSS supplies light-theme fallbacks without overriding the host's tokens. Define the tokens on the page root for both themes so portaled menus and popovers inherit the same theme. Keep the Chakra color mode aligned with the page theme. `examples/tokens.css` is a reference copy of the application's tokens, not an automatically injected global stylesheet.
|
|
107
|
-
|
|
108
|
-
Controls retain accessible names, keyboard focus indicators, Escape handling, disabled states, and keyboard reordering. Popovers are mounted lazily and constrained to the viewport. Invalid value drafts remain visible for correction.
|
|
109
|
-
|
|
110
|
-
### Compact presentation
|
|
111
|
-
|
|
112
|
-
Both lists prioritize frequent edits. Tree shows field names and types by default; ParametersTable shows names and values. Optional columns are controlled independently with `showType`, `showRequired`, and `showDescription`. Hidden attributes remain available from the settings icon. Request mode opens settings read-only.
|
|
106
|
+
### Show optional columns
|
|
113
107
|
|
|
114
108
|
```tsx
|
|
115
109
|
<SchemaTreeEditor value={schema} onChange={setSchema} showRequired showDescription />
|
|
116
|
-
<ParametersTable parameters={
|
|
110
|
+
<ParametersTable parameters={params} onChange={setParams} showType showRequired showDescription />
|
|
117
111
|
```
|
|
118
112
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
## Performance and boundaries
|
|
113
|
+
### Resolve $ref references
|
|
122
114
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
115
|
+
```tsx
|
|
116
|
+
<SchemaTreeEditor
|
|
117
|
+
value={schema}
|
|
118
|
+
onChange={setSchema}
|
|
119
|
+
document={openApiDocument} // resolves local $ref pointers
|
|
120
|
+
/>
|
|
121
|
+
```
|
|
126
122
|
|
|
127
|
-
|
|
123
|
+
### Generate sample values
|
|
128
124
|
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
125
|
+
```tsx
|
|
126
|
+
<ParametersTable
|
|
127
|
+
parameters={params}
|
|
128
|
+
mode="request"
|
|
129
|
+
values={values}
|
|
130
|
+
onValuesChange={setValues}
|
|
131
|
+
onError={reportError}
|
|
132
|
+
/>
|
|
137
133
|
```
|
|
138
134
|
|
|
139
|
-
The
|
|
135
|
+
The built-in generator creates realistic sample values from your schema using Faker + JSON Schema Faker, with Ajv validation.
|
|
140
136
|
|
|
141
|
-
|
|
137
|
+
---
|
|
142
138
|
|
|
143
|
-
|
|
139
|
+
## Entry Points
|
|
144
140
|
|
|
145
|
-
|
|
141
|
+
| Import | Contents |
|
|
142
|
+
|--------|----------|
|
|
143
|
+
| `@powerduck/schema-designer` | All React components (tree, inline, parameters, variable editor) |
|
|
144
|
+
| `@powerduck/schema-designer/core` | Pure schema operations — patch, pointers, traversal, reference resolution (no React) |
|
|
145
|
+
| `@powerduck/schema-designer/react/tree` | SchemaTreeEditor only |
|
|
146
|
+
| `@powerduck/schema-designer/react/inline` | InlineSchemaEditor only |
|
|
147
|
+
| `@powerduck/schema-designer/react/parameters` | ParametersTable only |
|
|
148
|
+
| `@powerduck/schema-designer/react/variable-editor` | VariableTextEditor only |
|
|
149
|
+
| `@powerduck/schema-designer/styles.css` | Combined component styles |
|
|
146
150
|
|
|
147
|
-
|
|
151
|
+
ESM + CommonJS builds with full TypeScript declarations. Tree-shaking friendly — importing `react/tree` doesn't load CodeMirror or Faker.
|
|
148
152
|
|
|
149
|
-
|
|
150
|
-
import { VariableTextEditor } from "@powerduck/schema-designer/react/variable-editor";
|
|
153
|
+
---
|
|
151
154
|
|
|
152
|
-
|
|
153
|
-
```
|
|
155
|
+
## Requirements
|
|
154
156
|
|
|
155
|
-
|
|
157
|
+
- React 18.2+ or 19
|
|
158
|
+
- Chakra UI v3 (wrap app in `ChakraProvider`)
|
|
159
|
+
- Node 22.12+ (for the optional generator adapter)
|
|
156
160
|
|
|
157
|
-
|
|
161
|
+
---
|
|
158
162
|
|
|
159
|
-
|
|
163
|
+
## API Reference
|
|
160
164
|
|
|
161
|
-
|
|
162
|
-
| --------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
|
|
163
|
-
| `value`, `onChange` | Required controlled pair | Accepts object or boolean schemas; emits immutable replacements. |
|
|
164
|
-
| `document` | Edited schema | Root document for local `$ref` pointers. |
|
|
165
|
-
| `showType` | `true` | Shows the inline type selector. |
|
|
166
|
-
| `showRequired`, `showDescription` | `false` | Reveals optional columns without dropping their data. |
|
|
167
|
-
| `defaultExpanded` | `[]` | Initial occurrence paths, such as `properties/customer`; escape `~` and `/` as `~0` and `~1`. |
|
|
168
|
-
| `maxRows` | `5000` | Stops expanded traversal and displays an overflow notice. |
|
|
169
|
-
| `readOnly` | `false` | Prevents commits, including custom advanced-editor updates. |
|
|
170
|
-
| `renderAdvanced` | Shared Inline editor | Custom content receives a full-node replacement callback. |
|
|
171
|
-
| `onError` | Unset | Receives recovered errors with scope and path. Throwing observers cannot break recovery. |
|
|
165
|
+
### SchemaTreeEditor
|
|
172
166
|
|
|
173
|
-
|
|
167
|
+
| Prop | Default | Description |
|
|
168
|
+
|------|---------|-------------|
|
|
169
|
+
| `value` | required | The JSON Schema to edit (object or boolean) |
|
|
170
|
+
| `onChange` | required | Callback receiving the new schema |
|
|
171
|
+
| `document` | edited schema | Root document for resolving local `$ref` |
|
|
172
|
+
| `showType` | `true` | Show inline type selector |
|
|
173
|
+
| `showRequired` | `false` | Show required column |
|
|
174
|
+
| `showDescription` | `false` | Show description column |
|
|
175
|
+
| `defaultExpanded` | `[]` | Initially expanded paths |
|
|
176
|
+
| `maxRows` | `5000` | Max expanded rows before overflow notice |
|
|
177
|
+
| `readOnly` | `false` | Disable all edits |
|
|
178
|
+
| `onError` | — | Recovered errors with scope and path |
|
|
174
179
|
|
|
175
180
|
### ParametersTable
|
|
176
181
|
|
|
177
|
-
|
|
|
178
|
-
|
|
179
|
-
| `parameters`
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
182
|
-
| `values
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `readOnly`
|
|
187
|
-
| `generateValue` | Optional built-in adapter | Receives parameter, row index, document, and abort signal. |
|
|
188
|
-
|
|
189
|
-
Focused column separators accept Left/Right for 8px adjustments, or Shift+Left/Right for 32px. The adjacent pair retains its total width. The final column has no inactive resize handle. Content-based parameter schemas are preserved and are not accidentally combined with a new top-level `schema` by the type column. Boolean parameter schemas remain booleans in settings and reference resolution.
|
|
182
|
+
| Prop | Default | Description |
|
|
183
|
+
|------|---------|-------------|
|
|
184
|
+
| `parameters` | required | OpenAPI parameter array |
|
|
185
|
+
| `onChange` | — | Callback receiving updated parameter definitions |
|
|
186
|
+
| `mode` | `"design"` | `"design"` edits definitions; `"request"` fills values |
|
|
187
|
+
| `values` | local state | Controlled request values keyed by `parameterKey` |
|
|
188
|
+
| `onValuesChange` | — | Callback for request value changes |
|
|
189
|
+
| `document` | — | Root document for `$ref` resolution |
|
|
190
|
+
| `showType` / `showRequired` / `showDescription` | `false` | Toggle optional columns |
|
|
191
|
+
| `readOnly` | `false` | Disable all edits |
|
|
190
192
|
|
|
191
193
|
### VariableTextEditor
|
|
192
194
|
|
|
193
|
-
|
|
|
194
|
-
|
|
195
|
-
| `value
|
|
196
|
-
| `
|
|
197
|
-
| `
|
|
198
|
-
| `allowLineBreaks`
|
|
199
|
-
| `submitOnEnter`
|
|
200
|
-
| `minHeight
|
|
201
|
-
| `
|
|
202
|
-
| `maxLength` | `16384` | UTF-16 code-unit limit, configurable up to 1,000,000. |
|
|
203
|
-
| `disabled`, `readOnly` | `false` | Prevents edits, including paste/drop paths. |
|
|
204
|
-
|
|
205
|
-
Treat variable arrays and their entries as immutable. Inline token decorations update with the same document transaction, so deletion cannot leave stale token ranges. Updating presentation props preserves focus, selection, and history. Hosts should echo changes; delayed acknowledgments are tolerated, but this is not a collaborative-edit conflict-resolution protocol.
|
|
206
|
-
|
|
207
|
-
## Generator safety and release boundaries
|
|
208
|
-
|
|
209
|
-
The optional default generator validates candidates against the original schema in strict mode. `false` schemas reject generation. `maxArrayItems` defaults to 3 and is an allocation budget (1–1,000); increase it explicitly when an array's minimum requires more items. `maxDepth` accepts 1–32, and `validationRetryCount` accepts 0–20. Generated strings are bounded to 16,384 code units; larger required minimums produce an error. Local dereferencing is bounded to 20,000 visited nodes and a maximum depth of 128. Reference resolution never fetches remote documents.
|
|
210
|
-
|
|
211
|
-
These limits do not sandbox user-supplied regexes or third-party synchronous generation. For untrusted schemas or hard time limits, provide a worker-backed `generateValue` adapter and enforce a timeout there. An abort signal prevents stale results from being committed; it cannot interrupt synchronous JavaScript already executing.
|
|
195
|
+
| Prop | Default | Description |
|
|
196
|
+
|------|---------|-------------|
|
|
197
|
+
| `value` | required | Raw text string |
|
|
198
|
+
| `onChange` | — | Callback receiving new text |
|
|
199
|
+
| `variables` | `[]` | Array of `{ name, value, description, type? }` |
|
|
200
|
+
| `allowLineBreaks` | `false` | Enable multi-line input |
|
|
201
|
+
| `submitOnEnter` | `false` | Call submit on Enter |
|
|
202
|
+
| `minHeight` / `maxFocusedHeight` | `32` / `320` | Pixel height bounds |
|
|
203
|
+
| `readOnly` / `disabled` | `false` | Lock input |
|
|
212
204
|
|
|
213
|
-
|
|
205
|
+
---
|
|
214
206
|
|
|
215
|
-
|
|
207
|
+
## License
|
|
216
208
|
|
|
217
|
-
|
|
209
|
+
UNLICENSED — owned by Powerduck.
|