@json-render/core 0.0.1

package/README.md

@@ -0,0 +1,184 @@
+# @json-render/core
+
+Enterprise-grade JSON-driven UI library with conditional visibility, rich actions, and enhanced validation.
+
+## Features
+
+- **Conditional Visibility**: Show/hide components based on data paths, auth state, or complex logic expressions
+- **Rich Actions**: Actions with typed parameters, confirmation dialogs, and success/error callbacks
+- **Enhanced Validation**: Built-in validation functions with custom catalog functions support
+- **Type-Safe Catalog**: Define component schemas using Zod for full type safety
+- **Framework Agnostic**: Core logic is independent of UI frameworks
+
+## Installation
+
+```bash
+npm install @json-render/core
+# or
+pnpm add @json-render/core
+```
+
+## Quick Start
+
+### Create a Catalog
+
+```typescript
+import { createCatalog } from '@json-render/core';
+import { z } from 'zod';
+
+const catalog = createCatalog({
+  name: 'My Dashboard',
+  components: {
+    Card: {
+      props: z.object({
+        title: z.string(),
+        description: z.string().nullable(),
+      }),
+      hasChildren: true,
+      description: 'A card container',
+    },
+    Button: {
+      props: z.object({
+        label: z.string(),
+        action: ActionSchema,
+      }),
+      description: 'A clickable button',
+    },
+  },
+  actions: {
+    submit: { description: 'Submit the form' },
+    export: { 
+      params: z.object({ format: z.enum(['csv', 'pdf']) }),
+      description: 'Export data',
+    },
+  },
+  functions: {
+    customValidation: (value) => typeof value === 'string' && value.length > 0,
+  },
+});
+```
+
+### Visibility Conditions
+
+```typescript
+import { visibility, evaluateVisibility } from '@json-render/core';
+
+// Simple path-based visibility
+const element1 = {
+  key: 'error-banner',
+  type: 'Alert',
+  props: { message: 'Error!' },
+  visible: { path: '/form/hasError' },
+};
+
+// Auth-based visibility
+const element2 = {
+  key: 'admin-panel',
+  type: 'Card',
+  props: { title: 'Admin' },
+  visible: { auth: 'signedIn' },
+};
+
+// Complex logic
+const element3 = {
+  key: 'notification',
+  type: 'Alert',
+  props: { message: 'Warning' },
+  visible: {
+    and: [
+      { path: '/settings/notifications' },
+      { not: { path: '/user/dismissed' } },
+      { gt: [{ path: '/items/count' }, 10] },
+    ],
+  },
+};
+
+// Evaluate visibility
+const isVisible = evaluateVisibility(element1.visible, {
+  dataModel: { form: { hasError: true } },
+});
+```
+
+### Rich Actions
+
+```typescript
+import { resolveAction, executeAction } from '@json-render/core';
+
+const buttonAction = {
+  name: 'refund',
+  params: {
+    paymentId: { path: '/selected/id' },
+    amount: 100,
+  },
+  confirm: {
+    title: 'Confirm Refund',
+    message: 'Refund $100 to customer?',
+    variant: 'danger',
+  },
+  onSuccess: { navigate: '/payments' },
+  onError: { set: { '/ui/error': '$error.message' } },
+};
+
+// Resolve dynamic values
+const resolved = resolveAction(buttonAction, dataModel);
+```
+
+### Validation
+
+```typescript
+import { runValidation, check } from '@json-render/core';
+
+const config = {
+  checks: [
+    check.required('Email is required'),
+    check.email('Invalid email'),
+    check.maxLength(100, 'Too long'),
+  ],
+  validateOn: 'blur',
+};
+
+const result = runValidation(config, {
+  value: 'user@example.com',
+  dataModel: {},
+});
+
+// result.valid = true
+// result.errors = []
+```
+
+## API Reference
+
+### Visibility
+
+- `evaluateVisibility(condition, context)` - Evaluate a visibility condition
+- `evaluateLogicExpression(expr, context)` - Evaluate a logic expression
+- `visibility.*` - Helper functions for creating visibility conditions
+
+### Actions
+
+- `resolveAction(action, dataModel)` - Resolve dynamic values in an action
+- `executeAction(context)` - Execute an action with callbacks
+- `interpolateString(template, dataModel)` - Interpolate `${path}` in strings
+
+### Validation
+
+- `runValidation(config, context)` - Run validation checks
+- `runValidationCheck(check, context)` - Run a single validation check
+- `builtInValidationFunctions` - Built-in validators (required, email, min, max, etc.)
+- `check.*` - Helper functions for creating validation checks
+
+### Catalog
+
+- `createCatalog(config)` - Create a catalog with components, actions, and functions
+- `generateCatalogPrompt(catalog)` - Generate an AI prompt describing the catalog
+
+## Types
+
+See `src/types.ts` for full type definitions:
+
+- `UIElement` - Base element structure
+- `UITree` - Flat tree structure
+- `VisibilityCondition` - Visibility condition types
+- `LogicExpression` - Logic expression types
+- `Action` - Rich action definition
+- `ValidationConfig` - Validation configuration