ftvuzw-configuration-builder 0.1.0

package/LICENSE

@@ -0,0 +1,31 @@
+Copyright (c) 2026 sendeanschmidt@gmail.com. All rights reserved.
+
+PROPRIETARY AND CONFIDENTIAL
+
+This software and all associated source code, files, and documentation
+(the "Software") are the exclusive property of the copyright holder.
+
+No license, right, or permission of any kind is granted to any other person
+or entity. You may NOT, without the prior written permission of the copyright
+holder:
+
+  1. use, run, or execute the Software;
+  2. copy, reproduce, or store the Software;
+  3. modify, adapt, translate, or create derivative works of the Software;
+  4. distribute, publish, sublicense, sell, rent, lease, or otherwise make
+     the Software available to any third party; or
+  5. reverse engineer, decompile, or disassemble the Software.
+
+The Software is provided to the copyright holder only. Any access, use, or
+possession of the Software by anyone other than the copyright holder is
+unauthorized and strictly prohibited.
+
+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
+COPYRIGHT HOLDER 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.
+</content>
+</invoke>

package/README.md

@@ -0,0 +1,211 @@
+# dialog-builder-element
+
+A configurable `<dialog-builder>` **web component** for visually authoring
+form/dialog configurations. Each field can carry visibility (`hidden`),
+read-only, dropdown options, a computed value (`calculation`) and validation —
+all authored through a no-code **rule builder** that compiles to plain
+`x => …` JavaScript function strings plus a plain-language summary.
+
+The headline design goal is **configurability by field type**: every element
+type declares *which features it supports*, so a `file` upload (no options, no
+calculation) and a rich `dropdown` share the same engine without special-casing.
+
+```
+<dialog-builder>
+ ├─ top bar: config name + roles
+ ├─ rows of field "cards" (Label, Type, Width, Default)
+ │    └─ per-card feature tabs — rendered ONLY for features the type supports
+ │         Readonly · Hide · Dropdown · Calculation · Validation
+ └─ live JSON output (active field / complete dialog)
+```
+
+## Install
+
+```bash
+npm install dialog-builder-element
+```
+
+The package ships as native ES modules (no build step required).
+
+## Usage
+
+```html
+<dialog-builder id="builder"></dialog-builder>
+
+<script type="module">
+  import 'dialog-builder-element'; // registers <dialog-builder>
+
+  const builder = document.getElementById('builder');
+
+  // Load an existing config (also settable before the element upgrades).
+  builder.config = {
+    name: 'Risk Dialog',
+    roles: ['Admin', 'Manager'],
+    rows: [
+      [
+        { key: 'origin', label: 'Origin Project', type: 'text', width: 2 },
+        { key: 'risk', label: 'Project Risk', type: 'dropdown', width: 2,
+          options: ['This Project', 'Outside Project'] },
+        { key: 'attachment', label: 'Attachment', type: 'file', width: 2 },
+      ],
+    ],
+  };
+
+  // React to every edit.
+  builder.addEventListener('change', (e) => {
+    console.log(e.detail); // -> { name, roles, rows: [[field, ...]] }
+  });
+
+  // Read the current config any time.
+  const cfg = builder.getConfig();
+</script>
+```
+
+### Properties
+
+| Property      | Type                          | Description |
+|---------------|-------------------------------|-------------|
+| `config`      | `{ name, roles, rows }`       | Get/set the whole dialog config. `rows` is an array of rows; each row is an array of field objects. |
+| `roles`       | `string[]`                    | Get/set the global role list used by role-based readonly/hidden rules. |
+| `fieldTypes`  | `FieldType[]` (set only)      | Replace the field-type registry. See below. |
+
+### Methods & events
+
+- `getConfig()` → deep copy of the current config.
+- `"change"` event → `CustomEvent` whose `detail` is the current config; fires on any edit.
+
+### Theming
+
+All colors are CSS custom properties set on `:host`. Override them on the element:
+
+```css
+dialog-builder { --db-primary: #0b7285; --db-radius: 6px; }
+```
+
+## Configurable field types — the important part
+
+A field type is just data. Every type declares a `features` array; the UI reads
+it to decide which controls to render. **Adding a new type requires no code
+changes outside the registry.**
+
+```js
+import { DEFAULT_FIELD_TYPES, FEATURES } from 'dialog-builder-element/field-types';
+
+builder.fieldTypes = [
+  ...DEFAULT_FIELD_TYPES,
+  {
+    value: 'rating',          // stored on field.type
+    label: 'Star Rating',     // shown in the type dropdown
+    icon: 'star',             // Material Symbols icon name
+    defaultWidth: 2,          // grid columns a new field spans
+    valueBucket: 'number',    // how the rule engine compares it: text|number|bool|array
+    features: [
+      FEATURES.READONLY,
+      FEATURES.HIDDEN,
+      FEATURES.VALIDATION,
+      FEATURES.CALCULATION,
+      FEATURES.DEFAULT,
+    ],
+  },
+];
+```
+
+### Available features
+
+| Feature                | Effect on the card |
+|------------------------|--------------------|
+| `FEATURES.READONLY`    | "Readonly" rule tab (`x => boolean`, `true` = read-only). |
+| `FEATURES.HIDDEN`      | "Hide" rule tab (`x => boolean`, `true` = hidden). |
+| `FEATURES.OPTIONS`     | "Dropdown" editor: value list, table (`{value,label,…}`), or async API fetcher. |
+| `FEATURES.MULTIPLE`    | Adds the multi-select toggle inside the options editor (needs `OPTIONS`). |
+| `FEATURES.CALCULATION` | "Calculation" rule tab (computed value: number/text/bool/date/formula/field/JSON). |
+| `FEATURES.VALIDATION`  | "Validation" rule tab (returns an error message or `""`). |
+| `FEATURES.DEFAULT`     | Shows the inline "Default value" input. |
+
+### Built-in types
+
+| Type       | Features |
+|------------|----------|
+| `text`     | readonly, hidden, validation, calculation, default |
+| `number`   | readonly, hidden, validation, calculation, default |
+| `dropdown` | readonly, hidden, **options**, **multiple**, validation, calculation, default |
+| `textarea` | readonly, hidden, validation, default |
+| `checkbox` | readonly, hidden, validation, calculation, default |
+| `date`     | readonly, hidden, validation, calculation, default |
+| `file`     | readonly, hidden, validation — *example of a structurally lighter type* |
+
+> The `file` type ships as a worked example: it has no Dropdown or Calculation
+> buttons because those features simply aren't listed. Remove the type, or add
+> your own, by passing a custom registry.
+
+## Output shape
+
+`getConfig()` / the `change` event produce a compact JSON/JS-style config —
+each rule is a plain JS function (as a source string), and anything unset is
+omitted:
+
+```jsonc
+{
+  "name": "Risk Dialog",
+  "roles": ["Admin", "Manager"],
+  "rows": [
+    [
+      {
+        "key": "origin",
+        "label": "Origin Project",
+        "type": "text",
+        "width": 2,
+        "options": ["A", "B"],            // or [{value,label}], for dropdowns
+        "default": "",
+        "readonly": "x => x.currentUserRole === \"User\"",   // true → read-only
+        "hidden":   "x => !x.origin",                        // true → hidden
+        "validate": "x => !x.origin ? \"Required\" : \"\"",  // "" → valid
+        "color":    "x => x.risk > 5 ? \"#f44336\" : \"\"",  // hex → tint
+        "onInit":   "x => \"default value\"",                // computed default
+        // or "onUpdate": recomputed on every change (field becomes read-only)
+        "email":    "(prevX, x) => [...recipients]",
+        "_rules": { /* visual-editor rule models — see below */ }
+      }
+    ]
+  ]
+}
+```
+
+The rule keys are executable function strings your runtime can `new Function`
+to drive a live form; `x` is the current form values plus `currentUserRole` /
+`currentUser`. `_rules` holds the editable models behind the visual rule
+builder — the builder regenerates the functions from them on load, so a saved
+config re-opens with its rules intact. Strip `_rules` if a consumer only needs
+the runtime behavior.
+
+Importing also accepts the old verbose shape (`readonlyCode`, `hiddenCode`,
+`validationCode`, `colorCode`, `calculation` + `calculationTrigger`, top-level
+`*Rules`) and production-style booleans (`disabled: true` / `hidden: true`
+become constant functions).
+
+## Reusing the engine directly
+
+The pure codegen functions are exported if you want to compile rule models
+yourself (no DOM):
+
+```js
+import { codegen } from 'dialog-builder-element';
+// or: import * as codegen from 'dialog-builder-element/codegen';
+
+const fields = [{ key: 'amount', label: 'Amount', type: 'number' }];
+const js = codegen.genValidationJs(fields, {
+  rules: [{ when: { combinator: 'AND', conditions: [
+    { field: 'amount', operator: 'isEmpty' },
+  ] }, message: 'Required' }],
+});
+// -> x => (x.amount === null || x.amount === undefined || x.amount === "") ? "Required" : ""
+```
+
+## Scope (v0.1)
+
+Included: cards, rows, the field-type registry, the rule builder (readonly /
+hidden / calculation / validation), options (value/table/API), roles, live JSON
+output, `change` events.
+
+Deferred to a later version: drag-and-drop reordering of cards/rows, and the
+JSON import/validation panel from the original prototype.