@burgantech/pseudo-ui 0.1.0 → 0.1.1

package/README.md

@@ -35,97 +35,294 @@ npm install vue@^3.5 primevue@^4.5 @primeuix/themes@^2 primeicons@^7
 
 ## Quick Start
 
-### 1. Set up the delegate
+Two steps: first a minimal form, then we enrich it with a nested component and a dropdown. Each step is self-contained.
 
-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'
+### Step 1: Minimal form
 
-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()
-  },
+Name, surname, birth date, and a Submit button. No dropdowns, no nested components — just schema, view, and a minimal delegate.
 
-  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 }
-  },
+**Schema:**
+```json
+{
+  "$schema": "https://amorphie.io/meta/view-model-vocabulary",
+  "$id": "urn:amorphie:res:schema:demo:quick-start",
+  "type": "object",
+  "required": ["name", "surname"],
+  "properties": {
+    "name": { "type": "string", "minLength": 1, "x-labels": { "en": "First Name", "tr": "Ad" } },
+    "surname": { "type": "string", "minLength": 1, "x-labels": { "en": "Surname", "tr": "Soyad" } },
+    "birthDate": { "type": "string", "format": "date", "x-labels": { "en": "Date of Birth", "tr": "Doğum Tarihi" } }
+  }
+}
+```
 
-  async onAction(action, formData, command) {
-    if (action === 'submit') {
-      await fetch('/api/submit', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(formData),
-      })
-    }
+**View:**
+```json
+{
+  "$schema": "https://amorphie.io/meta/view-vocabulary/1.0",
+  "dataSchema": "urn:amorphie:res:schema:demo:quick-start",
+  "view": {
+    "type": "Column",
+    "gap": "md",
+    "children": [
+      { "type": "TextField", "bind": "name" },
+      { "type": "TextField", "bind": "surname" },
+      { "type": "DatePicker", "bind": "birthDate" },
+      { "type": "Button", "label": { "en": "Submit", "tr": "Gönder" }, "variant": "filled", "action": "submit" }
+    ]
+  }
+}
+```
+
+**Delegate + render:** `requestData` and `loadComponent` are never called here, so we stub them to throw. Only `onAction` matters.
+
+```vue
+<script setup lang="ts">
+import { provideDelegate } from '@burgantech/pseudo-ui/vue'
+import { PseudoView } from '@burgantech/pseudo-ui/vue'
+import '@burgantech/pseudo-ui/vue/style.css'
+
+import type { PseudoViewDelegate, DataSchema, ViewDefinition } from '@burgantech/pseudo-ui'
+
+const schema: DataSchema = {
+  $schema: 'https://amorphie.io/meta/view-model-vocabulary',
+  $id: 'urn:amorphie:res:schema:demo:quick-start',
+  type: 'object',
+  required: ['name', 'surname'],
+  properties: {
+    name: { type: 'string', minLength: 1, 'x-labels': { en: 'First Name', tr: 'Ad' } },
+    surname: { type: 'string', minLength: 1, 'x-labels': { en: 'Surname', tr: 'Soyad' } },
+    birthDate: { type: 'string', format: 'date', 'x-labels': { en: 'Date of Birth', tr: 'Doğum Tarihi' } },
   },
+}
 
-  // 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
+const view: ViewDefinition = {
+  $schema: 'https://amorphie.io/meta/view-vocabulary/1.0',
+  dataSchema: 'urn:amorphie:res:schema:demo:quick-start',
+  view: {
+    type: 'Column',
+    gap: 'md',
+    children: [
+      { type: 'TextField', bind: 'name' },
+      { type: 'TextField', bind: 'surname' },
+      { type: 'DatePicker', bind: 'birthDate' },
+      { type: 'Button', label: { en: 'Submit', tr: 'Gönder' }, variant: 'filled', action: 'submit' },
+    ],
   },
+}
 
-  // Optional: capture SDK internal logs
-  onLog(level, message, error, context) {
-    console[level](`[pseudo-ui] ${message}`, context ?? '')
+const delegate: PseudoViewDelegate = {
+  async requestData() { throw new Error('No LOV in this example — add a dropdown to trigger this') },
+  async loadComponent() { throw new Error('No nested components — add type: "Component" to trigger this') },
+  async onAction(action, formData) {
+    if (action === 'submit') console.log('Form submitted:', formData)
   },
 }
+</script>
+
+<template>
+  <PseudoView :schema="schema" :view="view" lang="en" :delegate="delegate" />
+</template>
 ```
 
-### 2. Provide the delegate and render
+---
+
+### Step 2: Add a continent dropdown (nested component + LOV)
+
+We extend the form with a **continent** field. The dropdown lives in a nested sub-component and gets its options via `requestData` — so you see both `loadComponent` (nested UI) and `requestData` (LOV data) in action. All data is inline.
+
+**Add to main schema:**
+```json
+"continent": { "type": "string", "x-labels": { "en": "Continent you live in", "tr": "Yaşadığınız kıta" } }
+```
+
+**Add to main view** (between DatePicker and Button):
+```json
+{
+  "type": "Component",
+  "ref": "continent-selector",
+  "bind": { "continent": "$form.continent" }
+}
+```
+
+**Sub-component schema** (continent-selector — has `x-lov`, so the SDK calls `requestData("get-continents")`):
+```json
+{
+  "$schema": "https://amorphie.io/meta/view-model-vocabulary",
+  "$id": "urn:amorphie:res:schema:demo:continent-selector",
+  "type": "object",
+  "required": ["continent"],
+  "properties": {
+    "continent": {
+      "type": "string",
+      "x-labels": { "en": "Continent you live in", "tr": "Yaşadığınız kıta" },
+      "x-lov": {
+        "source": "get-continents",
+        "valueField": "$.response.data.code",
+        "displayField": "$.response.data.name"
+      }
+    }
+  }
+}
+```
+
+**Sub-component view:**
+```json
+{
+  "$schema": "https://amorphie.io/meta/view-vocabulary/1.0",
+  "dataSchema": "urn:amorphie:res:schema:demo:continent-selector",
+  "view": { "type": "Dropdown", "bind": "continent" }
+}
+```
+
+**Full delegate** (replace the stubs with real implementations):
 
 ```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'
+import type { PseudoViewDelegate, DataSchema, ViewDefinition } from '@burgantech/pseudo-ui'
+
+const CONTINENTS = [
+  { code: 'eu', name: 'Europe' },
+  { code: 'as', name: 'Asia' },
+  { code: 'na', name: 'North America' },
+  { code: 'sa', name: 'South America' },
+  { code: 'af', name: 'Africa' },
+  { code: 'oc', name: 'Oceania' },
+  { code: 'an', name: 'Antarctica' },
+]
+
+const mainSchema: DataSchema = {
+  $schema: 'https://amorphie.io/meta/view-model-vocabulary',
+  $id: 'urn:amorphie:res:schema:demo:quick-start',
+  type: 'object',
+  required: ['name', 'surname'],
+  properties: {
+    name: { type: 'string', minLength: 1, 'x-labels': { en: 'First Name', tr: 'Ad' } },
+    surname: { type: 'string', minLength: 1, 'x-labels': { en: 'Surname', tr: 'Soyad' } },
+    birthDate: { type: 'string', format: 'date', 'x-labels': { en: 'Date of Birth', tr: 'Doğum Tarihi' } },
+    continent: { type: 'string', 'x-labels': { en: 'Continent you live in', tr: 'Yaşadığınız kıta' } },
+  },
+}
 
-provideDelegate(delegate)
+const continentSchema: DataSchema = {
+  $schema: 'https://amorphie.io/meta/view-model-vocabulary',
+  $id: 'urn:amorphie:res:schema:demo:continent-selector',
+  type: 'object',
+  required: ['continent'],
+  properties: {
+    continent: {
+      type: 'string',
+      'x-labels': { en: 'Continent you live in', tr: 'Yaşadığınız kıta' },
+      'x-lov': { source: 'get-continents', valueField: '$.response.data.code', displayField: '$.response.data.name' },
+    },
+  },
+}
 
-const schema = ref<DataSchema>()
-const view = ref<ViewDefinition>()
+const mainView: ViewDefinition = {
+  $schema: 'https://amorphie.io/meta/view-vocabulary/1.0',
+  dataSchema: 'urn:amorphie:res:schema:demo:quick-start',
+  view: {
+    type: 'Column',
+    gap: 'md',
+    children: [
+      { type: 'TextField', bind: 'name' },
+      { type: 'TextField', bind: 'surname' },
+      { type: 'DatePicker', bind: 'birthDate' },
+      { type: 'Component', ref: 'continent-selector', bind: { continent: '$form.continent' } },
+      { type: 'Button', label: { en: 'Submit', tr: 'Gönder' }, variant: 'filled', action: 'submit' },
+    ],
+  },
+}
 
-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
-})
+const delegate: PseudoViewDelegate = {
+  async requestData(ref, params) {
+    if (ref === 'get-continents') return { response: { data: CONTINENTS } }
+    throw new Error(`Unknown data source: ${ref}`)
+  },
+  async loadComponent(ref) {
+    if (ref === 'continent-selector') {
+      return {
+        schema: continentSchema,
+        view: { $schema: 'https://amorphie.io/meta/view-vocabulary/1.0', dataSchema: 'urn:amorphie:res:schema:demo:continent-selector', view: { type: 'Dropdown', bind: 'continent' } },
+      }
+    }
+    throw new Error(`Unknown component: ${ref}`)
+  },
+  async onAction(action, formData) {
+    if (action === 'submit') console.log('Form submitted:', formData)
+  },
+}
 </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)"
-  />
+  <PseudoView :schema="mainSchema" :view="mainView" lang="en" :delegate="delegate" />
 </template>
 ```
 
+Step 1 gives you the basics. Step 2 shows how to add a nested component and LOV — `requestData` serves dropdown options, `loadComponent` serves the sub-component.
+
+---
+
+### Initial data (optional)
+
+You can pass initial values when the view first renders:
+
+| Prop | Purpose |
+|---|---|
+| `formData` | Pre-fill editable fields (e.g. user draft, edit mode). Fields are bound to `$form` and can be changed by the user. |
+| `instanceData` | Backend/persisted data (e.g. read-only display, lookup filters). Used by `$instance` expressions and summary views. |
+
+```vue
+<PseudoView
+  :schema="schema"
+  :view="view"
+  :form-data="{ name: 'Jane', surname: 'Doe', birthDate: '1990-05-15' }"
+  :instance-data="{ status: 'active', createdAt: '2024-01-01' }"
+  lang="en"
+  :delegate="delegate"
+/>
+```
+
+`formData` is for user-editable data. `instanceData` is for backend state that drives display and lookups — both are optional and merged when the view mounts.
+
+---
+
+### Lookups (enrichment)
+
+When a schema property has `x-lookup`, the SDK fetches enrichment data via `requestData`. You must **activate** the lookup by listing it in the view's `lookups` array — otherwise it won't run.
+
+**Schema** (defines the lookup):
+```json
+{
+  "branchDetail": {
+    "type": "object",
+    "x-lookup": {
+      "source": "get-branch-details",
+      "resultField": "$.response.data",
+      "filter": [{ "param": "branchCode", "value": "$param.selectedBranchCode", "required": true }]
+    }
+  }
+}
+```
+
+**View** (activates it):
+```json
+{
+  "$schema": "https://amorphie.io/meta/view-vocabulary/1.0",
+  "dataSchema": "urn:amorphie:res:schema:shared:branch-info",
+  "lookups": ["branchDetail"],
+  "view": { ... }
+}
+```
+
+Then use `$lookup.branchDetail.address`, `$lookup.branchDetail.phone`, etc. in Text or other components. The SDK calls `requestData(source, filterParams)` when the view mounts; the delegate returns the enrichment payload.
+
 ## Package Exports
 
 | Import path | Content |
@@ -176,77 +373,11 @@ onMounted(async () => {
 | **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) */
+  /** Fetch data from backend (LOV items, lookup enrichment). ref = source (required); params = resolved filter from x-lookup (optional when no filter). */
   requestData(ref: string, params?: Record<string, string>): Promise<unknown>
 
   /** Load a nested component's schema + view by reference */
@@ -329,7 +460,7 @@ import viewModelVocab from '@burgantech/pseudo-ui/vocabularies/view-model-vocabu
 
 ## 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.
+This 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.
 
 ## License
 

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

@@ -1,7 +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"]]);
+const a = /* @__PURE__ */ r(o, [["__scopeId", "data-v-3324b6bc"]]);
 export {
   a as default
 };