@tskapo/descr-ui

@tskapo/descr-ui

Deterministic, schema-driven UI engine, W3C Custom Elements, and Nuxt 3 module for dynamic forms and Visual Studio.

descr-ui turns database schemas and declarative AST rules into fully interactive, reactive user interfaces with 100% deterministic logic parity between server and client.

---

Table of Contents

• Key Features
• Installation
• Quickstart for Nuxt 3
• Visual Studio & Admin Mode
• Framework-Agnostic Usage (React, Angular, HTML)
• Extending with Custom Design-System Widgets
• Database & PostgreSQL Integration
• Component & Props Reference
• License

---

Key Features

• Pure AST Logic Engine: Dynamic field visibility, conditional editability, required checks, and mathematical calculations without hardcoded template logic.
• Autonomous Schema Provisioning: Renders form interfaces directly from schema tables (DESCR_UI_FIELDS & DESCR_UI_PAGES).
• 3 Presentation Layouts: Multi-step Wizard (with confirmation review screen), Tabs, and Accordion.
• Interactive Visual Studio: Low-code form designer with column span sliders (1–12), nested AND/OR condition builders, and live preview.
• Database Drift Detection: Real-time screaming alert banners when unmapped database columns are detected.
• Auto-Injected Server Endpoints: Built-in Nitro API handlers for schema CRUD, table introspection, deployment migrations, and telemetry.
• W3C Custom Elements: Drop into React, Angular, Vue, WordPress, or plain HTML.

---

Installation

# Using pnpm
pnpm add @tskapo/descr-ui

# Using npm
npm install @tskapo/descr-ui

# Using yarn
yarn add @tskapo/descr-ui

---

Quickstart for Nuxt 3

1. Register the Module in nuxt.config.ts

export default defineNuxtConfig({
	modules: ["@tskapo/descr-ui"],
	descrUi: {
		// API base route for schema endpoints (default: "/api/pages")
		apiBase: "/api/pages",
		// Standalone Visual Studio route (default: "/admin/descr-studio")
		studio: {
			enabled: true,
			route: "/admin/descr-studio",
		},
		// Optional database connection for live introspection
		db: {
			url: process.env.DATABASE_URL,
		},
	},
});

2. Render a Dynamic Form (<descr-renderer>)

<!-- app.vue or pages/form.vue -->
<template>
	<div class="container">
		<descr-renderer
			page-id="employee-profile"
			:model-value="form_data"
			:context="{ roles: ['user', 'admin'], locale: 'en' }"
			layout="wizard"
			@update:model-value="(val) => form_data = val"
			@submit="handleFormSubmit"
		/>
	</div>
</template>

<script setup lang="ts">
import { ref } from "vue";

const form_data = ref({
	first_name: "John",
	last_name: "Doe",
	email: "john.doe@example.com",
	age: 28,
});

function handleFormSubmit(values: Record<string, any>, state: any) {
	console.log("Submitted payload:", values);
	console.log("Evaluation validation state:", state);
}
</script>

---

Visual Studio & Admin Mode

Mode A: Standalone Route (Zero Setup)

When studio.enabled: true, navigating to http://localhost:3000/admin/descr-studio opens the full 3-column Visual Studio:

• Left Column: Database table explorer, country filters, and form field reordering (▲ / ▼).
• Center Column: Real-time live interactive preview with instant AST parity.
• Right Column: Field property inspector, 12-column grid slider, and visual AST condition tree builder.
• Top Navigation: Switch seamlessly between Visual Studio (Editor) and User Manual.

Mode B: Embedded Component Mode

You can embed the Visual Editor directly inside any custom host admin page, drawer, or modal:

<template>
	<div class="admin-page">
		<h2>Form Customizer: {{ current_page_id }}</h2>
		
		<!-- Drop-in Visual Studio Component -->
		<descr-studio
			:page-id="current_page_id"
			:embedded="true"
			:show-top-bar="true"
			@save="onStudioSave"
			@deploy="onStudioDeploy"
		/>
	</div>
</template>

<script setup lang="ts">
import { ref } from "vue";

const current_page_id = ref("employee-profile");

function onStudioSave(schema: any) {
	console.log("Saved schema:", schema);
}

function onStudioDeploy(payload: any) {
	console.log("Deploying form schema:", payload);
}
</script>

---

Framework-Agnostic Usage (React, Angular, HTML)

descr-ui components are standard W3C Custom Elements:

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8" />
	<title>descr-ui Embedded Form</title>
	<!-- Load @tskapo/descr-ui Custom Element -->
	<script type="module" src="https://unpkg.com/@tskapo/descr-ui"></script>
</head>
<body>
	<!-- Framework-Agnostic Form Web Component -->
	<descr-form
		page="employee-profile"
		layout="wizard"
		locale="en"
		endpoint="https://api.your-domain.com"
	></descr-form>
</body>
</html>

---

Extending with Custom Design-System Widgets

Pass custom input widgets from your own design system (e.g. Sargo, Nibelis, PrimeVue, Vuetify) into <descr-renderer> or <descr-studio>:

<template>
	<descr-renderer
		page-id="partner-onboarding"
		:model-value="values"
		:custom-widgets="custom_widgets"
	/>
</template>

<script setup lang="ts">
import MyIbanInput from "~/components/widgets/my-iban-input.vue";
import MyCurrencyInput from "~/components/widgets/my-currency-input.vue";

const custom_widgets = {
	"sargo-iban-input": MyIbanInput,
	"sargo-currency-input": MyCurrencyInput,
};
</script>

---

Database & PostgreSQL Integration

descr-ui introspects your database automatically.

Environment Variables

Configure your database connection in .env:

DATABASE_URL="postgresql://postgres:password@localhost:5432/my_database"

The built-in introspection queries PostgreSQL catalogs with comments (col_description, obj_description), providing instant metadata reflection in the Visual Studio without manual schema configuration.

---

Component & Props Reference

<descr-renderer> Props

Prop	Type	Default	Description
pageId	string	undefined	Autonomous schema fetching by ID from API
schema	FormSchema	undefined	Directly passed JSON schema object
modelValue	Record<string, any>	{}	Form values v-model binding
layout	"wizard" | "tabs" | "accordion"	"tabs"	Presentation layout mode
context	EvaluationContext	{ roles: ['user'], locale: 'en' }	RBAC roles and locale evaluation context
customWidgets	Record<string, Component>	{}	Custom input widget mapping
messages	Record<string, string>	{}	Optional i18n translation dictionary

<descr-studio> Props

Prop	Type	Default	Description
pageId	string	"employee-profile"	Target form schema ID to edit
embedded	boolean	false	Adapts container styling for embedding in custom host pages
standalone	boolean	false	Full-screen standalone mode
showTopBar	boolean	true	Shows header with template switcher and actions
showModeSwitcher	boolean	true	Enables toggling between Visual Studio and User Manual
customWidgets	Record<string, Component>	{}	Passes host custom widgets to the studio canvas
apiBase	string	"/api"	API base endpoint

---

License

MIT tskapo