@burgantech/pseudo-ui 0.1.0

package/README.md

@@ -0,0 +1,336 @@
+# @burgantech/pseudo-ui
+
+A **Server-Driven UI (SDUI)** rendering engine for TypeScript. Define your UI once with JSON — render it natively on any platform.
+
+The SDK pairs a **JSON Schema** data contract with a **View JSON** component tree to produce fully interactive forms, summaries, and multi-step workflows without shipping new client code.
+
+## Features
+
+- **30+ Material Design 3 components** — TextField, Dropdown, DatePicker, TabView, Dialog, Stepper, Carousel, and more
+- **Delegate-driven architecture** — the SDK never makes HTTP calls; your app provides data via a simple interface
+- **Expression engine** — `$form`, `$instance`, `$param`, `$ui`, `$lov`, `$lookup`, `$schema`, `$item`, `$context` namespaces for dynamic value resolution
+- **Conditional engine** — `showIf` / `hideIf` / `enableIf` / `disableIf` with `allOf`, `anyOf`, `not` compound rules and 13 operators
+- **Validation engine** — JSON Schema validation (`pattern`, `format`, `minLength`, `min/max`) plus async custom validation via delegate
+- **LOV & Lookup** — List-of-Values dropdowns with cascade filtering and real-time data enrichment
+- **Nested components** — reusable sub-components with isolated contexts, input contracts (`x-binding`), and two-way data flow
+- **`$ui` state** — transient UI state (dialog visibility, active tab) that never pollutes form data
+- **Accessibility** — `aria-required`, `aria-invalid`, `aria-label` on all inputs; `role="alert"` on errors
+- **Error boundaries** — `Component` and `ForEach` nodes are wrapped to prevent child crashes from taking down the app
+- **Multi-language** — all labels, errors, and enum values support `{ "en": "...", "tr": "...", "ar": "..." }`
+- **View & ViewModel vocabularies** — included JSON Schema definitions for tooling and IDE auto-complete
+
+## Installation
+
+```bash
+npm install @burgantech/pseudo-ui
+```
+
+### Peer dependencies
+
+The Vue adapter requires these in your project:
+
+```bash
+npm install vue@^3.5 primevue@^4.5 @primeuix/themes@^2 primeicons@^7
+```
+
+## Quick Start
+
+### 1. Set up the delegate
+
+The SDK uses **inversion of control** — you implement `PseudoViewDelegate` to supply data, load nested components, and handle actions:
+
+```typescript
+import type { PseudoViewDelegate } from '@burgantech/pseudo-ui'
+
+const delegate: PseudoViewDelegate = {
+  async requestData(ref, params) {
+    const res = await fetch(`/api/functions/${ref}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ params }),
+    })
+    return res.json()
+  },
+
+  async loadComponent(ref) {
+    const [schema, view] = await Promise.all([
+      fetch(`/api/components/${ref}/schema.json`).then(r => r.json()),
+      fetch(`/api/components/${ref}/view.json`).then(r => r.json()),
+    ])
+    return { schema, view }
+  },
+
+  async onAction(action, formData, command) {
+    if (action === 'submit') {
+      await fetch('/api/submit', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(formData),
+      })
+    }
+  },
+
+  // Optional: custom server-side validation
+  async onValidationRequest(field, value, formData) {
+    const res = await fetch(`/api/validate/${field}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value, formData }),
+    })
+    const { error } = await res.json()
+    return error ?? null
+  },
+
+  // Optional: capture SDK internal logs
+  onLog(level, message, error, context) {
+    console[level](`[pseudo-ui] ${message}`, context ?? '')
+  },
+}
+```
+
+### 2. Provide the delegate and render
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import { provideDelegate } from '@burgantech/pseudo-ui/vue'
+import { PseudoView } from '@burgantech/pseudo-ui/vue'
+import '@burgantech/pseudo-ui/vue/style.css'
+
+import type { DataSchema, ViewDefinition } from '@burgantech/pseudo-ui'
+
+provideDelegate(delegate)
+
+const schema = ref<DataSchema>()
+const view = ref<ViewDefinition>()
+
+onMounted(async () => {
+  const [s, v] = await Promise.all([
+    fetch('/api/components/my-form/schema.json').then(r => r.json()),
+    fetch('/api/components/my-form/view.json').then(r => r.json()),
+  ])
+  schema.value = s
+  view.value = v
+})
+</script>
+
+<template>
+  <PseudoView
+    v-if="schema && view"
+    :schema="schema"
+    :view="view"
+    lang="en"
+    @form-change="console.log('form data:', $event)"
+    @validation-change="console.log('is valid:', $event)"
+  />
+</template>
+```
+
+## Package Exports
+
+| Import path | Content |
+|---|---|
+| `@burgantech/pseudo-ui` | Core engine: types, expression resolver, schema resolver, conditional engine |
+| `@burgantech/pseudo-ui/vue` | Vue 3 adapter: `PseudoView`, `DynamicRenderer`, `provideDelegate` |
+| `@burgantech/pseudo-ui/vue/style.css` | Component styles (Material Design 3 tokens) |
+| `@burgantech/pseudo-ui/vocabularies/view-vocabulary.json` | View meta-schema (UI component tree definition) |
+| `@burgantech/pseudo-ui/vocabularies/view-model-vocabulary.json` | ViewModel meta-schema (JSON Schema x- extensions) |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Your Application                   │
+│                                                      │
+│  ┌──────────────┐   implements   ┌────────────────┐ │
+│  │   App.vue    │ ──────────────▶│  Delegate      │ │
+│  │              │                │  - requestData │ │
+│  │  <PseudoView │                │  - loadComponent│ │
+│  │   :schema    │                │  - onAction    │ │
+│  │   :view      │                │  - onLog       │ │
+│  │   lang="en"/>│                └────────────────┘ │
+│  └──────┬───────┘                        ▲          │
+│         │ provides                       │          │
+├─────────┼────────────────────────────────┼──────────┤
+│  SDK    │                                │          │
+│         ▼                                │          │
+│  ┌─────────────────┐  ┌──────────────┐   │          │
+│  │ DynamicRenderer  │  │ Expression   │   │          │
+│  │ (recursive)      │  │ Resolver     │   │          │
+│  │                  │  ├──────────────┤   │          │
+│  │ 30+ MD3 widgets  │  │ Conditional  │   │          │
+│  │ via PrimeVue 4   │  │ Engine       │   │          │
+│  │                  │  ├──────────────┤   │          │
+│  │ ErrorBoundary    │  │ Schema       │   │          │
+│  │ for Component &  │  │ Resolver     │◀──┘          │
+│  │ ForEach          │  │ (validation) │              │
+│  └─────────────────┘  └──────────────┘              │
+└─────────────────────────────────────────────────────┘
+```
+
+## Data Model (MVVM)
+
+| Layer | File | Purpose |
+|---|---|---|
+| **ViewModel** | `schema.json` | Data contract — field types, validation, LOV sources, conditionals, multi-lang labels |
+| **View** | `view.json` | UI component tree — layout, binding, actions, transient UI state |
+| **Model** | Backend | Persisted data, served via delegate's `requestData` |
+
+### Schema example (ViewModel)
+
+```json
+{
+  "$id": "urn:amorphie:res:schema:shared:customer-form",
+  "type": "object",
+  "required": ["fullName", "city"],
+  "properties": {
+    "fullName": {
+      "type": "string",
+      "minLength": 2,
+      "x-labels": { "en": "Full Name", "tr": "Ad Soyad" },
+      "x-errorMessages": {
+        "required": { "en": "Required", "tr": "Zorunlu" }
+      }
+    },
+    "city": {
+      "type": "string",
+      "x-labels": { "en": "City", "tr": "Şehir" },
+      "x-lov": {
+        "source": "urn:amorphie:func:domain:shared:get-cities",
+        "valueField": "$.response.data.code",
+        "displayField": "$.response.data.name"
+      }
+    },
+    "companyName": {
+      "type": "string",
+      "x-labels": { "en": "Company", "tr": "Şirket" },
+      "x-conditional": {
+        "showIf": {
+          "allOf": [
+            { "field": "accountType", "operator": "equals", "value": "corporate" },
+            { "field": "age", "operator": "greaterThan", "value": 17 }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+### View example
+
+```json
+{
+  "$schema": "https://amorphie.io/meta/view-vocabulary/1.0",
+  "dataSchema": "urn:amorphie:res:schema:shared:customer-form",
+  "uiState": { "showDialog": false },
+  "view": {
+    "type": "Column",
+    "gap": "md",
+    "children": [
+      { "type": "TextField", "bind": "fullName" },
+      { "type": "Dropdown", "bind": "city" },
+      { "type": "TextField", "bind": "companyName" },
+      {
+        "type": "Button",
+        "label": { "en": "Submit", "tr": "Gönder" },
+        "variant": "filled",
+        "action": "submit"
+      }
+    ]
+  }
+}
+```
+
+## Delegate Interface
+
+```typescript
+interface PseudoViewDelegate {
+  /** Fetch data from backend (LOV items, lookup enrichment) */
+  requestData(ref: string, params?: Record<string, string>): Promise<unknown>
+
+  /** Load a nested component's schema + view by reference */
+  loadComponent(ref: string): Promise<{ schema: DataSchema; view: ViewDefinition }>
+
+  /** Handle user actions (submit, cancel, back, custom commands) */
+  onAction(action: string, formData: Record<string, unknown>, command?: string): Promise<void>
+
+  /** Optional: custom async validation after built-in checks pass */
+  onValidationRequest?(field: string, value: unknown, formData: Record<string, unknown>): Promise<string | null>
+
+  /** Optional: capture SDK logs (debug, info, warn, error) */
+  onLog?(level: LogLevel, message: string, error?: unknown, context?: Record<string, unknown>): void
+}
+```
+
+## Supported Components
+
+### Layout
+`Column` · `Row` · `Stack` · `Grid` · `Expanded` · `SizedBox` · `Divider` · `Spacer`
+
+### Input
+`TextField` · `TextArea` · `NumberField` · `Dropdown` · `Checkbox` · `RadioGroup` · `DatePicker` · `TimePicker` · `Switch` · `Slider` · `SegmentedButton` · `SearchField` · `AutoComplete`
+
+### Display
+`Text` · `Image` · `Chip` · `ListTile` · `Avatar` · `RichText` · `LoadingIndicator`
+
+### Surface & Overlay
+`Card` · `Dialog` · `BottomSheet` · `SideSheet` · `Snackbar` · `Tooltip`
+
+### Navigation
+`TabView` · `AppBar` · `NavigationBar` · `NavigationDrawer`
+
+### Container
+`ExpansionPanel` · `Stepper`
+
+### Action
+`Button` · `IconButton` · `FAB` · `Menu` · `Toolbar` · `Carousel`
+
+### Control
+`ForEach` · `Component` (nested)
+
+## Expression Namespaces
+
+| Namespace | Source | Example |
+|---|---|---|
+| `$form.field` | User input data | `$form.firstName` |
+| `$instance.field` | Backend persisted data | `$instance.status` |
+| `$param.field` | Parent-bound data (nested components) | `$param.cityCode` |
+| `$ui.key` | Transient UI state (not submitted) | `$ui.showDialog` |
+| `$schema.field.label` | Schema label for current language | `$schema.city.label` |
+| `$lov.field` | LOV items array | `$lov.city` |
+| `$lov.field.display` | Localized display name for current value | `$lov.city.display` |
+| `$lookup.prop.field` | Enrichment data | `$lookup.branch.address` |
+| `$item.field` | ForEach iteration item | `$item.name` |
+| `$context.lang` | Runtime context | `$context.lang` |
+
+## Conditional Operators
+
+`equals` · `notEquals` · `in` · `notIn` · `greaterThan` · `lessThan` · `greaterThanOrEquals` · `lessThanOrEquals` · `contains` · `startsWith` · `endsWith` · `isEmpty` · `isNotEmpty`
+
+Compound rules: `allOf` (AND), `anyOf` (OR), `not` (negate) — recursive nesting supported.
+
+## Validation Formats
+
+Built-in `format` validators: `email` · `uri` / `url` · `date` · `date-time` · `time` · `phone` / `tel` · `iban`
+
+## Vocabularies
+
+The package includes JSON Schema vocabulary definitions for IDE auto-complete and tooling:
+
+```typescript
+// Import as JSON modules
+import viewVocab from '@burgantech/pseudo-ui/vocabularies/view-vocabulary.json'
+import viewModelVocab from '@burgantech/pseudo-ui/vocabularies/view-model-vocabulary.json'
+```
+
+- **View Vocabulary** — defines all valid component types, properties, and their constraints
+- **ViewModel Vocabulary** — defines all `x-*` extensions (`x-labels`, `x-lov`, `x-conditional`, etc.)
+
+## Cross-Platform
+
+This package provides the **TypeScript/Vue** implementation. A **Dart/Flutter** package (`pseudo_ui`) renders the same JSON schemas and views using Material 3 widgets. Both packages share the same vocabulary definitions, ensuring consistent behavior across platforms.
+
+## License
+
+MIT

package/dist/_virtual/_plugin-vue_export-helper.js

@@ -0,0 +1,9 @@
+const s = (t, e) => {
+  const o = t.__vccOpts || t;
+  for (const [r, c] of e)
+    o[r] = c;
+  return o;
+};
+export {
+  s as default
+};

package/dist/adapters/vue/DynamicRenderer.vue.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentNode } from '../../engine/types';
+type __VLS_Props = {
+    node: ComponentNode;
+    item?: Record<string, unknown>;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/adapters/vue/DynamicRenderer.vue.js

@@ -0,0 +1,7 @@
+import o from "./DynamicRenderer.vue2.js";
+/* empty css                     */
+import r from "../../_virtual/_plugin-vue_export-helper.js";
+const a = /* @__PURE__ */ r(o, [["__scopeId", "data-v-c6e3365d"]]);
+export {
+  a as default
+};