@softheon/armature 21.2.1 → 21.2.2

package/b2b/README.md

@@ -0,0 +1,255 @@
+# @softheon/armature/b2b
+
+Secondary entry point for B2B components in the `@softheon/armature` library. Optional B2B components with zero added bundle cost.
+
+## Architecture
+
+```
+@softheon/armature/b2b
+  ├─ SofB2BModule                        (NgModule wrapper — optional)
+  ├─ SofB2BJsonEditorComponent           (standalone, root editor)
+  │    └─ SofB2BJsonNodeComponent        (standalone, recursive renderer)
+  └─ Utilities
+       ├─ json-path.utils.ts             (flatten / unflatten / path parsing)
+       ├─ json-tree.utils.ts             (tree build / reconstruct / array clone & reindex)
+       ├─ json-filter.utils.ts           (search filtering)
+       └─ json-schema.utils.ts           (JSON Schema parsing — internal)
+```
+
+## Quick Start
+
+### 1. Install the type dependency (optional)
+
+The `[schema]` input uses `JsonSchema`, an alias for `JSONSchema7` from `@types/json-schema`. Add it as a devDependency if you plan to use schema-driven field configuration:
+
+```bash
+npm install --save-dev @types/json-schema
+```
+
+### 2. Import the component
+
+`SofB2BJsonEditorComponent` is standalone — import it directly or use `SofB2BModule`:
+
+```typescript
+import { SofB2BJsonEditorComponent } from '@softheon/armature/b2b';
+
+// Option A — standalone component
+@Component({
+  standalone: true,
+  imports: [SofB2BJsonEditorComponent],
+})
+export class MyComponent {}
+
+// Option B — NgModule
+import { SofB2BModule } from '@softheon/armature/b2b';
+
+@NgModule({
+  imports: [SofB2BModule],
+})
+export class MyModule {}
+```
+
+### 3. Use in template
+
+Pass a `JsonObject` (any nested JSON object) directly — no pre-processing required:
+
+```html
+<sof-b2b-json-editor
+  [data]="rawData"
+  [schema]="jsonSchema"
+  [readOnly]="false"
+  [debounceMs]="1500"
+  [searchTerm]="searchTerm"
+  (dataChanged)="onDataChanged($event)"
+  (parseError)="onParseError($event)"
+  [emptyMessage]="'editor.data.empty' | translate"
+  [noResultsMessage]="'editor.data.no-results' | translate">
+</sof-b2b-json-editor>
+```
+
+### 4. Handle changes
+
+The `(dataChanged)` output emits the full reconstructed `JsonObject` after the debounce period:
+
+```typescript
+import { JsonObject } from '@softheon/armature/b2b';
+
+onDataChanged(data: JsonObject): void {
+  // data is the full reconstructed JSON object
+  this.myService.save(data);
+}
+
+onParseError(error: string): void {
+  // Display the error in your own snackbar/toast/etc.
+  this.snackbar.open(error, 'Dismiss');
+}
+```
+
+## API Reference
+
+### SofB2BJsonEditorComponent inputs
+
+| Input              | Type         | Default                 | Description                                                                 |
+| ------------------ | ------------ | ----------------------- | --------------------------------------------------------------------------- |
+| `data`             | `JsonObject` | `{}`                    | Raw nested JSON object. Pass a **new object reference** to trigger updates. |
+| `schema`           | `JsonSchema` | `undefined`             | Optional JSON Schema (Draft 7+). Parsed internally into field configs.      |
+| `readOnly`         | `boolean`    | `false`                 | Disables editing; fields render as plaintext.                               |
+| `debounceMs`       | `number`     | `1500`                  | Debounce delay before `dataChanged` emits.                                  |
+| `searchTerm`       | `string`     | `''`                    | Filters tree nodes (min 2 chars to activate).                               |
+| `emptyMessage`     | `string`     | `'No data to display.'` | Message shown when `data` is empty.                                         |
+| `noResultsMessage` | `string`     | `'No results found.'`   | Message shown when search returns no matches.                               |
+
+### SofB2BJsonEditorComponent outputs
+
+| Output        | Type         | Description                                                                             |
+| ------------- | ------------ | --------------------------------------------------------------------------------------- |
+| `dataChanged` | `JsonObject` | Emits the reconstructed JSON object after debounce. Suppressed when `readOnly` is true. |
+| `parseError`  | `string`     | Emits error message strings for parsing/validation failures.                            |
+
+### SofB2BJsonEditorComponent public methods
+
+| Method       | Description                                   |
+| ------------ | --------------------------------------------- |
+| `openAll()`  | Programmatically opens all top-level panels.  |
+| `closeAll()` | Programmatically closes all top-level panels. |
+
+## Models
+
+### JsonObject (input & output)
+
+```typescript
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
+```
+
+### JsonSchema (schema input)
+
+The `[schema]` input accepts a `JsonSchema` type — an alias for `JSONSchema7` from `@types/json-schema` (Draft 7):
+
+```typescript
+import { JsonSchema } from '@softheon/armature/b2b';
+
+const schema: JsonSchema = {
+  type: 'object',
+  properties: {
+    Theme: { type: 'string', enum: ['dark', 'light'] },
+    MaxRetries: { type: 'integer', title: 'Max Retries' },
+    Enabled: { type: 'boolean' },
+  },
+};
+```
+
+## Utility Functions
+
+All utilities are importable from the entry point:
+
+```typescript
+import {
+  type JsonSchema,
+  unflattenJson,
+  normalizeToEntries,
+  parsePath,
+  buildNodesFromEntries,
+  flattenNamespaces,
+  filterNamespaces,
+  validateDuplicateKeys,
+  parseJsonSchema,
+} from '@softheon/armature/b2b';
+```
+
+| Function                   | Description                                                        |
+| -------------------------- | ------------------------------------------------------------------ |
+| `unflattenJson(entries)`   | Reconstructs nested JSON from `JsonEntry[]`.                       |
+| `normalizeToEntries()`     | Flattens a `JsonObject` into `JsonEntry[]` with dot/bracket paths. |
+| `parsePath(key)`           | Splits a dot/bracket path into segments.                           |
+| `filterNamespaces()`       | Filters a namespace tree by search term.                           |
+| `validateDuplicateKeys()`  | Detects duplicate keys in `JsonEntry[]` and returns error strings. |
+| `parseJsonSchema()`        | Parses a JSON Schema into a flat `Record<string, FieldConfig>`.    |
+
+## Key Path Notation
+
+Internally, the editor uses path notation for keys:
+
+| Pattern        | Example                       | Meaning                   |
+| -------------- | ----------------------------- | ------------------------- |
+| Dot notation   | `BillingInformation.PlanName` | Object property access    |
+| Bracket index  | `Invoice.Payments[0].Amount`  | Array element access      |
+| Quoted bracket | `["Discount Amount"]`         | Special characters in key |
+
+## Read-Only Mode
+
+When `readOnly` is `true`:
+
+- All scalar fields render as plaintext (no inputs)
+- Toggle switches are disabled
+- The debounce subscription is never created (no wasted cycles)
+- `dataChanged` never emits
+
+```html
+<sof-b2b-json-editor [data]="myData" [readOnly]="true"></sof-b2b-json-editor>
+```
+
+## Search Filtering
+
+Pass a `searchTerm` to filter the tree. Filtering activates at 2+ characters and recursively prunes namespaces/nodes that don't match:
+
+```html
+<sof-b2b-json-editor [data]="myData" [searchTerm]="userSearchInput"></sof-b2b-json-editor>
+```
+
+## Array Add / Remove
+
+When a schema is provided and an array field has at least one item, the editor renders interactive add/remove controls:
+
+- **Add button** — appears at the bottom of expanded arrays. Labeled "Add [Singular]" (e.g. "Add Payment"). Clones the first item's structure and values.
+- **Remove button** — a trash icon on each array item header, visible on hover. Cannot remove the last remaining item (minimum 1).
+- **Read-only mode** — add/remove buttons are hidden entirely (not disabled).
+- **Empty arrays** — arrays with zero items and no schema display a grayed-out "(no schema)" label and are non-interactive.
+
+All add/remove changes flow through the existing debounced `dataChanged` pipeline.
+
+## Dirty Field Detection
+
+Scalar fields that have been edited display a blue label to indicate unsaved changes:
+
+- The editor tracks each field's **original value** (the value when the tree was first built).
+- When a field's current value differs from its original, the label turns blue (`--primary-color`).
+- Resetting a field back to its original value removes the dirty indicator.
+- Newly added array items are **not** marked dirty — their original value is set to the cloned value.
+
+## JSON Schema Support
+
+The editor accepts a standard JSON Schema (Draft 7+) directly via its `[schema]` input and uses it to configure field types, labels, and dropdown options automatically.
+
+### Schema keyword mapping
+
+| JSON Schema keyword | Editor behaviour        | Notes                                           |
+| ------------------- | ----------------------- | ----------------------------------------------- |
+| `type: "string"`    | `<input type="text">`   |                                                 |
+| `type: "number"`    | `<input type="number">` |                                                 |
+| `type: "integer"`   | `<input type="number">` |                                                 |
+| `type: "boolean"`   | `<mat-slide-toggle>`    |                                                 |
+| `enum`              | `<mat-select>`          | Values are converted to strings for option list |
+| `$id`               | Label override          | Last URI segment or fragment extracted          |
+| `title`             | Label override          | Used when `$id` is absent                       |
+| `description`       | Placeholder text        |                                                 |
+| `properties`        | _(recurse)_             | Builds dot-notation path prefix                 |
+| `items`             | _(recurse)_             | Applies element schema to array paths           |
+
+Nullable types like `["string", "null"]` are supported — the first non-null type is used.
+
+### Depth limit
+
+Schema recursion stops at 20 levels (matching the tree builder's `MAX_DEPTH`) and logs a console warning.
+
+## Testing
+
+```bash
+# Run B2B tests
+npm run testB2B
+
+# Or directly via ng
+ng test b2b
+```