` to host the chrome. CDK Overlay portals (Select, DatePicker) remain non-shadow-aware as noted below.\n\n## Theming (Angular)\n\nThe Angular adapter uses Angular Material 19 (Material Design 3) and is **not** shadow-DOM aware in this release. Theming is driven by the standard Material `--mat-sys-*` system tokens:\n\n```scss\n:root {\n /* Tenant brand */\n --mat-sys-primary: #FF6B35;\n --mat-sys-on-primary: #ffffff;\n --mat-sys-primary-container: #ffd5c0;\n\n /* Surface */\n --mat-sys-surface: #fafafa;\n --mat-sys-on-surface: rgba(0, 0, 0, 0.87);\n --mat-sys-surface-container-lowest: #ffffff;\n --mat-sys-outline-variant: #e5e7eb;\n\n /* Status */\n --mat-sys-error: #d32f2f;\n --mat-sys-on-error: #ffffff;\n}\n```\n\nFor dark mode, switch the Material prebuilt theme CSS (e.g. `@angular/material/prebuilt-themes/azure-blue.css` → `azure-blue-dark.css`) at app bootstrap or compose your own theme with `mat.theme()` SCSS mixin.\n\n### Component styles\n\nThe adapter ships a small stylesheet (`pseudo-ui-angular.css`) that defines the structural helper classes used by the renderer: icon sizes, card interaction states, tab panel layout, and the validation-error snackbar panel class. Include it in your Angular application's global styles:\n\n```json\n// angular.json — styles array\n\"styles\": [\n \"node_modules/@burgan-tech/pseudo-ui/angular/style.css\",\n \"src/styles.scss\"\n]\n```\n\nor via SCSS import:\n\n```scss\n// styles.scss\n@import '@burgan-tech/pseudo-ui/angular/style.css';\n```\n\nThe stylesheet intentionally omits Angular Material theming CSS — that remains the consumer's responsibility (prebuilt theme or `mat.theme()` SCSS mixin).\n\n### Shadow DOM\n\n`adoptStylesIntoRoot` is exported from `@burgan-tech/pseudo-ui/angular` for consumers who host Angular inside a Shadow DOM (e.g. via `@angular/elements` with `ViewEncapsulation.ShadowDom`). Full CDK Overlay containment is tracked for a future release.\n\n> CDK Overlay portals (Select, DatePicker, Dialog) are not shadow-aware in this release; they portal to `document.body` and may appear outside the shadow tree if the host element is inside one.\n\n## Package Exports\n\n| Import path | Content |\n|---|---|\n| `@burgan-tech/pseudo-ui` | Core engine: types, expression resolver, schema resolver, conditional engine, builder utilities (`componentMeta`, `enumerateBindPaths`) |\n| `@burgan-tech/pseudo-ui/vue` | Vue 3 adapter (PrimeVue 4): `PseudoView`, `DynamicRenderer`, `provideDelegate`, `adoptStylesIntoRoot`, `pseudoUiVueCss`, `useOverlayTarget` |\n| `@burgan-tech/pseudo-ui/angular` | Angular 19 adapter (standalone, Angular Material): `PseudoViewComponent`, `DynamicRendererComponent`, `FORM_CONTEXT`, `PSEUDO_DELEGATE`, `adoptStylesIntoRoot` |\n| `@burgan-tech/pseudo-ui/react` | React 18+ adapter (PrimeReact 10): `PseudoView`, `DynamicRenderer`, `createFormContext`, `FormCtx`, `DelegateCtx`, `adoptStylesIntoRoot`, `pseudoUiReactCss` |\n| `@burgan-tech/pseudo-ui/vue/style.css` | Vue adapter component styles (Material Design 3 tokens) |\n| `@burgan-tech/pseudo-ui/vue/style.js` | Vue adapter component CSS as a JS string (for `adoptedStyleSheets`) |\n| `@burgan-tech/pseudo-ui/react/style.css` | React adapter component styles |\n| `@burgan-tech/pseudo-ui/react/style.js` | React adapter component CSS as a JS string (for `adoptedStyleSheets`) |\n| `@burgan-tech/pseudo-ui/angular/style.css` | Angular adapter component helper classes (icon sizes, card states, snackbar) |\n| `@burgan-tech/pseudo-ui/vocabularies/view-vocabulary.json` | View meta-schema (UI component tree definition) |\n| `@burgan-tech/pseudo-ui/vocabularies/view-model-vocabulary.json` | ViewModel meta-schema (JSON Schema x- extensions) |\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│ Your Application │\n│ │\n│ ┌──────────────┐ implements ┌────────────────┐ │\n│ │ App.vue │ ──────────────▶│ Delegate │ │\n│ │ │ │ - requestData │ │\n│ │
│ └────────────────┘ │\n│ └──────┬───────┘ ▲ │\n│ │ provides │ │\n├─────────┼────────────────────────────────┼──────────┤\n│ SDK │ │ │\n│ ▼ │ │\n│ ┌─────────────────┐ ┌──────────────┐ │ │\n│ │ DynamicRenderer │ │ Expression │ │ │\n│ │ (recursive) │ │ Resolver │ │ │\n│ │ │ ├──────────────┤ │ │\n│ │ 30+ MD3 widgets │ │ Conditional │ │ │\n│ │ via PrimeVue 4 │ │ Engine │ │ │\n│ │ │ ├──────────────┤ │ │\n│ │ ErrorBoundary │ │ Schema │ │ │\n│ │ for Component & │ │ Resolver │◀──┘ │\n│ │ ForEach │ │ (validation) │ │\n│ └─────────────────┘ └──────────────┘ │\n└─────────────────────────────────────────────────────┘\n```\n\n## Data Model (MVVM)\n\n| Layer | File | Purpose |\n|---|---|---|\n| **ViewModel** | `schema.json` | Data contract — field types, validation, LOV sources, conditionals, multi-lang labels |\n| **View** | `view.json` | UI component tree — layout, binding, actions, transient UI state |\n| **Model** | Backend | Persisted data, served via delegate's `requestData` |\n\n## Delegate Interface\n\n```typescript\ninterface PseudoViewDelegate {\n /** Fetch data from backend (LOV items, lookup enrichment). ref = source (required); params = resolved filter from x-lookup (optional when no filter). */\n requestData(ref: string, params?: Record): Promise\n\n /** Load a nested component's schema + view by reference */\n loadComponent(ref: string): Promise<{ schema: DataSchema; view: ViewDefinition }>\n\n /** Handle user actions (submit, cancel, back, custom commands) */\n onAction(action: string, formData: Record, command?: string): Promise\n\n /** Optional: custom async validation after built-in checks pass */\n onValidationRequest?(field: string, value: unknown, formData: Record): Promise\n\n /** Optional: capture SDK logs (debug, info, warn, error) */\n onLog?(level: LogLevel, message: string, error?: unknown, context?: Record): void\n\n /**\n * Optional: read this record's CHILD instances so a parent view can display\n * their data via `$subFlow.*` / `$subProcess.*` without copying it into the\n * parent. Only the roots the view actually references are requested.\n * Required only if views use those roots — see\n * docs/child-instance-read-through.md\n */\n loadSubInstances?(input: {\n domain: string; workflow: string; instanceId: string\n states: string[]; flows: string[]\n }): Promise\n\n /**\n * Optional: turn a `FilePicker`'s handle into bytes — the platform half, and\n * NOT an upload. Return `{name, mimeType, size, content}` with `content` as\n * base64 and no `data:` prefix, or `null` when the file could not be read\n * (the node then leaves the field empty rather than storing half a document).\n * The gate — accepted media type, non-empty, within `maxSizeBytes` — has\n * already run in `engine/filePicker.ts`. See below.\n */\n readFile?(input: FileReadRequest): Promise\n}\n```\n\n### `readFile` — the file picker's platform half\n\n`FilePicker` needs one thing pure code cannot do: read a platform file handle\ninto bytes. That is all `readFile` is. **It sends nothing anywhere** — the base64\nit returns is written into form data at the picker's `bind` and the ordinary\nsubmit carries it to the backend inside the transition body, exactly like a text\nfield's string. There is no second request, no endpoint, no attachment id, and\nnone may be added: a client that could name a storage location would be a client\nthat knows where the file is stored, which is the one thing this contract must\nnever encode.\n\nOn web, use `FileReader.readAsDataURL` and cut at the comma — **not**\n`arrayBuffer()` plus a byte loop. `String.fromCharCode(...bytes)` blows the\nargument limit and throws `RangeError: Maximum call stack size exceeded` at\naround a hundred kilobytes, which is well inside the range this picker allows.\n\n```typescript\nasync function readFile(input: FileReadRequest): Promise {\n const file = input.file\n if (!(file instanceof Blob)) return null // an adapter bug, not a user error\n const content = await new Promise(resolve => {\n const reader = new FileReader()\n reader.onerror = () => resolve(null)\n reader.onload = () => {\n const r = reader.result\n if (typeof r !== 'string') return resolve(null)\n const comma = r.indexOf(',')\n resolve(comma >= 0 ? r.slice(comma + 1) : null) // drop the `data:` prefix\n }\n try { reader.readAsDataURL(file) } catch { resolve(null) }\n })\n if (content === null) return null\n return { name: input.name, mimeType: input.mimeType, size: input.size, content }\n}\n```\n\n**Wire it once, in the host's base delegate, not per surface.** A seam nobody\nwires is a feature that does not exist: when it is missing the node reports at\n`error` naming the consequence and tells the person on screen, rather than\nleaving a control that swallows every pick.\n\n**Never log the content.** Names, types and sizes only — a base64 blob in a\nconsole line is both a leak of a customer's papers and a console nobody can\nscroll afterwards. The SDK exports `withoutFileContent` / `withoutFileContents`\nfor host log lines that carry a field value or a whole record.\n\n### Child instance read-through (`$subFlow` / `$subProcess`)\n\nA parent workflow's view can display its sub-flow / sub-process data without that\ndata ever being copied into the parent. Two things must be supplied, and **if\neither is missing nothing is fetched** — the view renders empty and logs one\nwarning:\n\n1. `loadSubInstances` on the delegate (above)\n2. `instanceRef` on `PseudoView` — `{ domain, workflow, instanceId }`, or `null`\n on a start surface where no instance exists yet\n\n```tsx\n\n```\n\nThe load is **reference-driven**: a view with no `$sub*` binding calls nothing at\nall, and a parent with seven open children serving a view that names one fan-out\nissues three reads. Absent children suppress silently (`undefined` / `[]`), so a\nbinding can be written eagerly.\n\nThree authoring rules that bite, all covered in\n[docs/child-instance-read-through.md](../../docs/child-instance-read-through.md):\nthis engine has no `{{ }}` interpolation (compose counters from sibling `Text`\nnodes), index with `.0` not `[0]`, and `x-conditional` cannot see child data so a\nblock cannot be hidden when a fan-out is empty.\n\n## Supported Components\n\n### Page frame\n`Scaffold` (view root only — owns the top app bar and the body)\n\n### Layout\n`Column` · `Row` · `Stack` · `Grid` · `Expanded` · `SizedBox` · `Divider` · `Spacer`\n\n### Input\n`TextField` · `TextArea` · `NumberField` · `Dropdown` · `Checkbox` · `RadioGroup` · `DatePicker` · `TimePicker` · `Switch` · `Slider` · `SegmentedButton` · `SearchField` · `AutoComplete` · `ImagePicker` · `FilePicker`\n\n`FilePicker` opens the machine's own file dialog and puts the chosen document into the form. **There\nis no upload**: the file becomes base64 in the form data and travels to the backend in the ordinary\ntransition body, exactly like a text field's string — no side channel, no endpoint, no attachment id.\nThe node calls `delegate.readFile` only to turn the platform's file handle into bytes, and that seam\ntalks to no server. Label, requiredness, visibility and validation all come from the bound schema\nproperty, so a required-but-empty picker blocks submit through the same gate a required `TextField`\ndoes. The stored value is `{name, mimeType, size, content}` (base64, no `data:` prefix); the optional\n`fields` mapping renames those four keys for a backend schema that already spells them differently,\nand `multiple` asks for a set — where the bind then always holds an array. Per-file, total and count\nceilings default to 1 MiB / 4 MiB / 5 files and cannot be switched off: the base64 sits in the\ninstance data and is carried on every read of that record.\n\n### Display\n`Text` · `Image` · `Chip` · `ListTile` · `Avatar` · `RichText` · `LoadingIndicator`\n\n### Surface & Overlay\n`Card` · `Dialog` · `BottomSheet` · `SideSheet` · `Snackbar` · `Tooltip`\n\n### Navigation\n`TabView` · `AppBar` · `NavigationBar` · `NavigationDrawer`\n\n### Container\n`ExpansionPanel` · `Stepper`\n\n### Action\n`Button` · `IconButton` · `FAB` · `Menu` · `Toolbar` · `Carousel`\n\n### Control\n`ForEach` · `Component` (nested)\n\n## Expression Namespaces\n\n| Namespace | Source | Example |\n|---|---|---|\n| `$form.field` | User input data | `$form.firstName` |\n| `$instance.field` | Backend persisted data | `$instance.status` |\n| `$param.field` | Parent-bound data (nested components) | `$param.cityCode` |\n| `$ui.key` | Transient UI state (not submitted) | `$ui.showDialog` |\n| `$schema.field.label` | Schema label for current language | `$schema.city.label` |\n| `$lov.field` | LOV items array | `$lov.city` |\n| `$lov.field.display` | Localized display name for current value | `$lov.city.display` |\n| `$lookup.prop.field` | Enrichment data | `$lookup.branch.address` |\n| `$subFlow.state.…` | A child sub-flow's own data, read through without copying it into the parent | `$subFlow.precheck.data.notes` |\n| `$subProcess.flow` | A fanned-out sub-process group (array); `.length` and `.$done` read its size and how many reported back | `$subProcess.ns-notify.$done` |\n| `$item.field` | ForEach iteration item | `$item.name` |\n| `$context.lang` | Runtime context | `$context.lang` |\n\n## Conditional Operators\n\n`equals` · `notEquals` · `in` · `notIn` · `greaterThan` · `lessThan` · `greaterThanOrEquals` · `lessThanOrEquals` · `contains` · `startsWith` · `endsWith` · `isEmpty` · `isNotEmpty` · `matches` (regex)\n\nCompound rules: `allOf` (AND), `anyOf` (OR), `not` (negate) — recursive nesting supported.\n\n## Validation Formats\n\nBuilt-in `format` validators: `email` · `uri` / `url` · `date` · `date-time` · `time` · `phone` / `tel` · `iban`\n\n## Designer Mode\n\nWhen wiring this SDK into a view.json editor or preview pane, set the\n`designer` prop on `PseudoView` so structural placeholders show up even\nwhen no real data is bound:\n\n```vue\n\n```\n\n```tsx\n\n```\n\n```html\n\n```\n\nWhat changes when `designer === true`:\n\n- **`ForEach`** with an empty `source` renders its `template` once with\n an empty `$item` — designers see the iteration shape instead of a\n blank region.\n- **`x-conditional` visibility** (`showIf` / `hideIf`) is bypassed —\n hidden fields render so editors can see and select them. Enabled\n state is **preserved**, so `disableIf` / `enableIf` still produce\n disabled styling.\n- **Validation rules are unaffected.** A submit that triggers\n `validateAllFields` still uses the original visibility rules —\n errors do not surface for fields that the live runtime would hide.\n\nThe flag bridges to the engine via `FormContext.designerMode`. Direct\ncontext consumers can also flip it with `createFormContext(schema, lang,\n{ designerMode: true })`.\n\n## Builder & Tooling APIs\n\nTwo engine-level utilities make it easy to build view.json editors, autocomplete UIs,\nor static analyzers without re-implementing the SDK's structural knowledge:\n\n### `componentMeta`\n\nProgrammatic catalog of every node type. Use it instead of hard-coding a parallel\nlist in your tooling — the catalog is sync-tested against `view-vocabulary.json`,\nso adding a new component anywhere in the SDK surfaces here automatically.\n\n```typescript\nimport { componentMeta, getComponentMeta, listComponentTypes } from '@burgan-tech/pseudo-ui'\n\nlistComponentTypes()\n// → ['Column', 'Row', ..., 'Button', 'TextField', ..., 'ForEach', 'Component']\n\ngetComponentMeta('TabView')\n// → {\n// type: 'TabView',\n// category: 'container',\n// acceptsChildren: true,\n// childContainerKey: 'tabs',\n// childContainerShape: 'wrapped', // 'flat' = ComponentNode[], 'wrapped' = TabDefinition[] etc.\n// defaultProps: { tabs: [{ title: 'Tab 1', content: [] }] },\n// description: 'Tabbed container...',\n// }\n```\n\nFields: `type`, `category`, `acceptsChildren`, `childContainerKey`,\n`childContainerShape`, `defaultProps`, `bindable`, `description`.\n\n### `enumerateBindPaths`\n\nWalks a `dataSchema` and returns every reachable bind path with its metadata —\nuseful for autocomplete UIs, bind validators, and documentation generators.\n\n```typescript\nimport { enumerateBindPaths } from '@burgan-tech/pseudo-ui'\n\nenumerateBindPaths(schema, { prefix: '$form', includeObjects: false, maxDepth: 5 })\n// → [\n// { path: '$form.firstName', type: 'string', label: { tr: 'Ad', en: 'First name' }, required: true, depth: 0 },\n// { path: '$form.city', type: 'string', hasLov: true, depth: 0 },\n// { path: '$form.branchDetail.address', type: 'string', depth: 1 },\n// ]\n```\n\nEach entry carries `type`, `format`, `label` (multi-lang), `hasLov`, `hasLookup`,\n`required` (top-level only — `allOf` conditional required is intentionally not\nresolved here; it needs runtime context), and `depth`.\n\n## Vocabularies\n\nThe package includes JSON Schema vocabulary definitions for IDE auto-complete and tooling:\n\n```typescript\n// Import as JSON modules\nimport viewVocab from '@burgan-tech/pseudo-ui/vocabularies/view-vocabulary.json'\nimport viewModelVocab from '@burgan-tech/pseudo-ui/vocabularies/view-model-vocabulary.json'\n```\n\n- **View Vocabulary** — defines all valid component types, properties, and their constraints\n- **ViewModel Vocabulary** — defines all `x-*` extensions (`x-labels`, `x-lov`, `x-conditional`, etc.)\n\n## Cross-Platform\n\nThis package provides the **TypeScript/Vue** implementation. A **Dart/Flutter** package is planned and will render the same JSON schemas and views using Material 3 widgets. Both will share the same vocabulary definitions, ensuring consistent behavior across platforms.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}