@structured-field/widget-editor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bnznamco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# @structured-field/widget-editor
+
+A Vue-powered JSON Schema form builder with first-class support for relation fields (ForeignKey, QuerySet) and autocomplete search. Ships as both Vue components and a Web Component custom element.
+
+Built for the [django-structured-json-field](https://github.com/bnznamco/django-structured-field) admin widget, but usable standalone with any JSON Schema + REST search endpoint.
+
+## Features
+
+- **JSON Schema driven** — renders forms from standard JSON Schema (`$ref`, `$defs`, `anyOf`, `oneOf`, `discriminator`)
+- **Relation fields** — ForeignKey (single) and QuerySet (multi) with AJAX autocomplete from a search endpoint
+- **Discriminated unions** — type selector that swaps sub-forms based on a discriminator property
+- **Nullable fields** — togglable Add/Remove for optional nested objects
+- **Array fields** — ordered list with add, remove, and reorder controls
+- **Built with Vue 3** — internally uses Vue SFC components, exported as a Web Component custom element
+- **Theme integration** — styles via CSS custom properties (ships with Django admin compatibility)
+
+## Installation
+
+```bash
+npm install @structured-field/widget-editor
+# or
+pnpm add @structured-field/widget-editor
+```
+
+## Usage
+
+### Web Component (custom element)
+
+Register the `<schema-form>` custom element, then use it in any HTML page or framework:
+
+```js
+import { registerCustomElement } from '@structured-field/widget-editor';
+import '@structured-field/widget-editor/css';
+
+registerCustomElement(); // registers <schema-form>
+```
+
+#### Programmatic initialization (recommended)
+
+```js
+const el = document.createElement('schema-form');
+
+el.schema = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    age: { type: 'integer' },
+  },
+};
+
+el.initialData = { name: 'Ada', age: 36 };
+
+el.addEventListener('change', (e) => {
+  console.log('Form value:', e.detail);
+});
+
+document.getElementById('my-form').appendChild(el);
+
+// Get current value at any time
+const value = el.getValue();
+```
+
+#### Declarative HTML
+
+```html
+<schema-form
+  schema='{"type":"object","properties":{"name":{"type":"string"}}}'
+  initial-data='{"name":"Ada"}'
+></schema-form>
+
+<script>
+  document.querySelector('schema-form').addEventListener('change', (e) => {
+    console.log(e.detail);
+  });
+</script>
+```
+
+### As a Vue component
+
+Import `SchemaForm` directly for use inside Vue applications:
+
+```vue
+<template>
+  <SchemaForm :schema="schema" :initial-data="data" @change="onFormChange" />
+</template>
+
+<script setup>
+import { SchemaForm } from '@structured-field/widget-editor';
+import '@structured-field/widget-editor/css';
+
+const schema = { /* JSON Schema */ };
+const data = { /* initial form data */ };
+
+function onFormChange(value) {
+  console.log('Form value:', value);
+}
+</script>
+```
+
+### As an IIFE (script tag)
+
+#### All-in-one bundle (recommended)
+
+A single `<script>` tag that includes both JS and CSS — no separate stylesheet needed:
+
+```html
+<!-- Latest version -->
+<script src="https://bnznamco.github.io/structured-widget-editor/latest/structured-widget-editor.iife.js"></script>
+
+<!-- Pinned version -->
+<script src="https://bnznamco.github.io/structured-widget-editor/v1.0.0/structured-widget-editor.iife.js"></script>
+```
+
+#### Separate JS + CSS
+
+```html
+<!-- Latest version -->
+<link rel="stylesheet" href="https://bnznamco.github.io/structured-widget-editor/latest/structured-widget-editor.css">
+<script src="https://bnznamco.github.io/structured-widget-editor/latest/structured-widget-editor.js"></script>
+
+<!-- Pinned version -->
+<link rel="stylesheet" href="https://bnznamco.github.io/structured-widget-editor/v1.0.0/structured-widget-editor.css">
+<script src="https://bnznamco.github.io/structured-widget-editor/v1.0.0/structured-widget-editor.js"></script>
+```
+
+#### Via jsDelivr (from npm)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@structured-field/widget-editor@latest/dist/structured-widget-editor.iife.js"></script>
+<!-- or pinned -->
+<script src="https://cdn.jsdelivr.net/npm/@structured-field/widget-editor@1.0.0/dist/structured-widget-editor.iife.js"></script>
+```
+
+#### Usage
+
+```html
+<script src="https://bnznamco.github.io/structured-widget-editor/latest/structured-widget-editor.iife.js"></script>
+<script>
+  StructuredWidgetEditor.registerCustomElement();
+
+  const el = document.createElement('schema-form');
+  el.schema = { /* JSON Schema */ };
+  el.initialData = { /* data */ };
+  el.addEventListener('change', (e) => console.log(e.detail));
+  document.getElementById('my-form').appendChild(el);
+</script>
+```
+
+## Relation Fields
+
+The editor supports a custom `type: "relation"` schema extension for ForeignKey and QuerySet fields:
+
+```json
+{
+  "type": "relation",
+  "format": "select2",
+  "model": "app.ModelName",
+  "multiple": false,
+  "options": {
+    "select2": {
+      "placeholder": "Search...",
+      "allowClear": true,
+      "ajax": {
+        "url": "/api/search/app.ModelName/"
+      }
+    }
+  }
+}
+```
+
+The search endpoint should return:
+
+```json
+{
+  "items": [
+    { "id": 1, "name": "Item 1", "model": "app.modelname" },
+    { "id": 2, "name": "Item 2", "model": "app.modelname" }
+  ],
+  "more": false
+}
+```
+
+Query parameters sent: `_q` (search term), `page` (pagination).
+
+## Editors
+
+| Schema type | Editor | Description |
+|---|---|---|
+| `string` | StringEditor | Text input or textarea |
+| `integer` / `number` | NumberEditor | Number input with step |
+| `boolean` | BooleanEditor | Checkbox |
+| `enum` | SelectEditor | Dropdown select |
+| `const` | HiddenEditor | Hidden (not rendered) |
+| `object` | ObjectEditor | Nested fieldset |
+| `array` | ArrayEditor | List with add/remove/reorder |
+| `anyOf [T, null]` | NullableEditor | Togglable wrapper |
+| `oneOf + discriminator` | UnionEditor | Type selector |
+| `relation` | RelationEditor | Autocomplete with search |
+
+## Theming
+
+All styles use CSS custom properties with sensible defaults. Override them to match your design system:
+
+```css
+:root {
+  --body-bg: #fff;
+  --body-fg: #333;
+  --border-color: #ccc;
+  --primary: #79aec8;
+  --error-fg: #ba2121;
+  --darkened-bg: #f0f0f0;
+  --object-tools-bg: #888;
+  --object-tools-fg: #fff;
+  /* ... */
+}
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm run dev    # watch mode
+pnpm run build  # production build
+```
+
+## License
+
+MIT

package/dist/structured-widget-editor.css

@@ -0,0 +1 @@
+.structured-field-editor{width:100%;border-radius:4px;font-size:.8125rem}.structured-field-editor *,.structured-field-editor *::before,.structured-field-editor *::after{box-sizing:border-box}.structured-field-editor .sf-label{display:block;font-weight:600;margin-bottom:4px;text-transform:capitalize;color:var(--body-quiet-color, #666);font-size:.8125rem}.structured-field-editor .sf-label.required::after{content:" *";color:var(--error-fg, #ba2121)}.structured-field-editor .sf-input{display:block;width:100%;padding:6px 8px;border:1px solid var(--border-color, #ccc);border-radius:4px;background:var(--body-bg, #fff);color:var(--body-fg, #333);font-size:.8125rem;font-family:inherit;transition:border-color .15s}.structured-field-editor .sf-input:focus{outline:none;border-color:var(--primary, #79aec8);box-shadow:0 0 0 2px rgba(121,174,200,.2)}.structured-field-editor .sf-textarea{resize:vertical;min-height:60px}.structured-field-editor .sf-select{appearance:auto;cursor:pointer}.structured-field-editor .sf-checkbox{margin-right:6px;accent-color:var(--primary, #79aec8)}.structured-field-editor .sf-checkbox-label{display:flex;align-items:center;font-weight:normal;cursor:pointer;padding:6px 0}.structured-field-editor .sf-btn{display:inline-flex;align-items:center;gap:4px;padding:4px 12px;background:var(--object-tools-bg, #888);color:var(--object-tools-fg, #fff);font-weight:400;font-size:.6875rem;text-transform:uppercase;letter-spacing:.5px;border-radius:15px;border:none;cursor:pointer;transition:background-color .15s}.structured-field-editor .sf-btn:hover{background-color:var(--object-tools-hover-bg, #666)}.structured-field-editor .sf-btn i{font-size:.6rem}.structured-field-editor .sf-btn-sm{padding:2px 8px;font-size:.625rem}.structured-field-editor .sf-btn-add{background:var(--object-tools-bg, #888);color:var(--object-tools-fg, #fff)}.structured-field-editor .sf-btn-danger{background:var(--delete-button-bg, #ba2121);color:var(--delete-button-fg, #fff)}.structured-field-editor .sf-btn-danger:hover{background:#a41515}.structured-field-editor .sf-error{color:var(--error-fg, #ba2121);font-size:.75rem;margin-top:2px}.structured-field-editor .errors .sf-input{border-color:var(--error-fg, #ba2121)}.structured-field-editor .errorlist{margin:4px 0 0 0;padding:0;list-style:none;color:var(--error-fg, #ba2121);font-size:.75rem}.structured-field-editor .errorlist li{padding:2px 0}.form-row{overflow:visible !important}.structured-field-editor .sf-field{margin-bottom:12px}.structured-field-editor .sf-field-boolean{margin-bottom:8px}.structured-field-editor .sf-object:not(.sf-object-root){border:1px solid var(--border-color, #ccc);border-radius:4px;padding:12px;margin-bottom:12px;background:var(--body-bg, #fff)}.structured-field-editor .sf-object-title{font-weight:600;font-size:.8125rem;color:var(--body-fg, #333);text-transform:capitalize;padding:0 4px}.structured-field-editor .sf-object-fields{display:flex;flex-direction:column}.structured-field-editor .sf-array{margin-bottom:12px}.structured-field-editor .sf-array-header{display:flex;align-items:center;gap:8px;margin-bottom:8px}.structured-field-editor .sf-array-header .sf-label{margin-bottom:0}.structured-field-editor .sf-array-count{display:inline-flex;align-items:center;justify-content:center;min-width:20px;height:20px;padding:0 6px;background:var(--darkened-bg, #f0f0f0);border-radius:10px;font-size:.6875rem;font-weight:600;color:var(--body-quiet-color, #666)}.structured-field-editor .sf-array-items{display:flex;flex-direction:column;gap:8px}.structured-field-editor .sf-array-item{border:1px solid var(--border-color, #ccc);border-radius:4px;background:var(--darkened-bg, #f8f8f8);overflow:hidden}.structured-field-editor .sf-array-item-header{display:flex;align-items:center;justify-content:space-between;padding:4px 8px;background:var(--darkened-bg, #f0f0f0);border-bottom:1px solid var(--border-color, #ccc)}.structured-field-editor .sf-array-item-index{font-size:.6875rem;font-weight:600;color:var(--body-quiet-color, #666)}.structured-field-editor .sf-array-item-actions{display:flex;gap:4px}.structured-field-editor .sf-array-item-body{padding:10px}.structured-field-editor .sf-array-item-body>.sf-object.sf-object-root,.structured-field-editor .sf-array-item-body>.sf-object:not(.sf-object-root){border:none;padding:0;margin:0;background:rgba(0,0,0,0)}.structured-field-editor .sf-nullable{margin-bottom:12px}.structured-field-editor .sf-nullable-header{display:flex;align-items:center;gap:8px;margin-bottom:4px}.structured-field-editor .sf-nullable-header .sf-label{margin-bottom:0}.structured-field-editor .sf-nullable-body{padding-left:0}.structured-field-editor .sf-nullable-body:not(:empty){border:1px solid var(--border-color, #ccc);border-radius:4px;padding:12px;margin-top:4px;background:var(--body-bg, #fff)}.structured-field-editor .sf-union{margin-bottom:12px}.structured-field-editor .sf-union-body{border:1px solid var(--border-color, #ccc);border-radius:4px;padding:12px;margin-top:8px;background:var(--body-bg, #fff)}.structured-field-editor .sf-union-body>.sf-object{border:none;padding:0;margin:0;background:rgba(0,0,0,0)}.structured-field-editor .sf-relation{position:relative}.structured-field-editor .sf-relation-wrapper{display:flex;flex-direction:column;gap:6px}.structured-field-editor .sf-relation-selected{display:flex;flex-wrap:wrap;gap:6px}.structured-field-editor .sf-relation-selected:empty{display:none}.structured-field-editor .sf-relation-tag{display:inline-flex;align-items:center;gap:6px;padding:4px 10px;background:var(--darkened-bg, #f0f0f0);border:1px solid var(--border-color, #ccc);border-radius:4px;font-size:.8125rem;color:var(--body-fg, #333);max-width:100%}.structured-field-editor .sf-relation-tag-text{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.structured-field-editor .sf-relation-tag-remove{display:inline-flex;align-items:center;justify-content:center;width:18px;height:18px;padding:0;border:none;border-radius:50%;background:rgba(0,0,0,0);color:var(--body-quiet-color, #666);cursor:pointer;font-size:.6875rem;flex-shrink:0;transition:color .15s,background .15s}.structured-field-editor .sf-relation-tag-remove:hover{color:var(--error-fg, #ba2121);background:rgba(186,33,33,.1)}.structured-field-editor .sf-relation-search{position:relative}.structured-field-editor .sf-relation-input{padding-left:28px;background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='14' viewBox='0 0 24 24' fill='none' stroke='%23999' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E");background-repeat:no-repeat;background-position:8px center;background-size:14px}.structured-field-editor .sf-relation-dropdown{position:absolute;top:100%;left:0;right:0;z-index:1000;max-height:240px;overflow-y:auto;background:var(--body-bg, #fff);border:1px solid var(--border-color, #ccc);border-top:none;border-radius:0 0 4px 4px;box-shadow:0 4px 12px rgba(0,0,0,.1)}.structured-field-editor .sf-relation-dropdown-item{padding:8px 12px;cursor:pointer;font-size:.8125rem;color:var(--body-fg, #333);transition:background .1s;border-bottom:1px solid var(--hairline-color, #eee)}.structured-field-editor .sf-relation-dropdown-item:last-child{border-bottom:none}.structured-field-editor .sf-relation-dropdown-item:hover,.structured-field-editor .sf-relation-dropdown-item.highlighted{background:var(--selected-bg, #e4e4e4)}.structured-field-editor .sf-relation-dropdown-empty{padding:12px;text-align:center;color:var(--body-quiet-color, #999);font-size:.8125rem;font-style:italic}.structured-field-editor .sf-relation-dropdown-more{padding:8px 12px;text-align:center;cursor:pointer;font-size:.75rem;color:var(--link-fg, #417690);font-weight:600;border-top:1px solid var(--hairline-color, #eee);transition:background .1s}.structured-field-editor .sf-relation-dropdown-more:hover{background:var(--darkened-bg, #f0f0f0)}