desen-core 1.0.0-draft

package/src/schemas/composition.ts

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import { modifiersSpec, bindingSpec } from "./binding";
+import { telemetrySpec } from "./telemetry";
+
+// ─── Forward-declare recursive types ─────────────────────────────
+// TypeScript needs explicit type annotations for circular schemas.
+// z.lazy() defers evaluation to runtime, solving circular references.
+
+export type NodeSpec = {
+    type: string;
+    [key: string]: any;
+};
+
+// ─── Positioning ─────────────────────────────────────────────────
+// SPEC.md §3.5: relative, sticky, absolute
+export const positioningSpec = z.object({
+    type: z.enum(["relative", "sticky", "absolute"]),
+});
+
+// ─── layoutSpec ──────────────────────────────────────────────────
+// SPEC.md §2.3: kind REQUIRED, rest optional
+export const layoutSpec = z.object({
+    kind: z.enum(["stack", "grid"]),
+    direction: z.enum(["vertical", "horizontal"]).optional(),
+    gap: z.number().min(0).optional(),
+    columns: z.number().int().min(1).optional(),
+    align: z.enum(["start", "center", "end", "stretch"]).optional(),
+    positioning: positioningSpec.optional(),
+});
+
+// ─── Composition types ───────────────────────────────────────────
+const compositionTypeEnum = z.enum(["Card", "Stack", "Grid", "Header", "Footer"]);
+const compositionTypes = new Set(["Card", "Stack", "Grid", "Header", "Footer"]);
+
+// ─── Constraints (shared) ────────────────────────────────────────
+const constraintsSpec = z.object({
+    a11y: z.object({
+        aria_label: z.string().optional(),
+        aria_role: z.string().optional(),
+        min_contrast_ratio: z.number().min(1).optional(),
+        focusable: z.boolean().optional(),
+    }).optional(),
+}).passthrough().optional();
+
+// ─── nodeSpec (discriminated by type field) ───────────────────────
+// SPEC.md §1.3: Node = Element | Composition | Repeater
+//
+// PERFORMANCE FIX: Instead of z.union() which tries all branches,
+// we use a custom z.lazy() that checks the `type` field to
+// dispatch to the correct schema — avoiding exponential backtracking.
+export const nodeSpec: z.ZodType<NodeSpec> = z.lazy(() =>
+    z.any().superRefine((val, ctx) => {
+        if (typeof val !== "object" || val === null || typeof val.type !== "string") {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Node must be an object with a 'type' string property.",
+            });
+            return;
+        }
+
+        let result;
+        if (val.type === "Repeater") {
+            result = repeaterSpec.safeParse(val);
+        } else if (compositionTypes.has(val.type)) {
+            result = compositionSpec.safeParse(val);
+        } else {
+            // Any other type is treated as an ElementSpec
+            result = elementSpecInternal.safeParse(val);
+        }
+
+        if (!result.success) {
+            for (const issue of result.error.issues) {
+                ctx.addIssue(issue);
+            }
+        }
+    })
+);
+
+// ─── Internal ElementSpec (no refine to avoid double-checking in nodeSpec) ──
+const elementSpecInternal = z.object({
+    type: z.string().min(1),
+    id: z.string().min(1),
+    props: z.record(z.any()),
+    constraints: constraintsSpec,
+    modifiers: modifiersSpec.optional(),
+    telemetry: telemetrySpec.optional(),
+}).passthrough()
+    .refine(
+        (data) => !("children" in data),
+        { message: "ElementSpec MUST NOT contain 'children'. Use CompositionSpec for containers." }
+    )
+    .refine(
+        (data) => !("layout" in data),
+        { message: "ElementSpec MUST NOT contain 'layout'. Use CompositionSpec for layout." }
+    );
+
+// ─── CompositionSpec ─────────────────────────────────────────────
+// SPEC.md §2.3: type (enum), id, layout, children, telemetry REQUIRED.
+export const compositionSpec: z.ZodType<any> = z.lazy(() =>
+    z.object({
+        type: compositionTypeEnum,
+        id: z.string().min(1).regex(/^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/),
+        layout: layoutSpec,
+        children: z.array(nodeSpec).min(0),
+        constraints: constraintsSpec,
+        modifiers: modifiersSpec.optional(),
+        telemetry: telemetrySpec,
+    }).passthrough()
+);
+
+// ─── RepeaterSpec ────────────────────────────────────────────────
+// SPEC.md §2.5: type MUST be "Repeater", data.bind REQUIRED,
+// template MUST be a valid nodeSpec, telemetry REQUIRED.
+export const repeaterSpec: z.ZodType<any> = z.lazy(() =>
+    z.object({
+        type: z.literal("Repeater"),
+        id: z.string().min(1),
+        data: z.object({
+            bind: bindingSpec,
+        }),
+        template: nodeSpec,
+        modifiers: modifiersSpec.optional(),
+        telemetry: telemetrySpec,
+    }).passthrough()
+);
+
+// ─── Types ───────────────────────────────────────────────────────
+export type PositioningSpec = z.infer<typeof positioningSpec>;
+export type LayoutSpec = z.infer<typeof layoutSpec>;
+export type CompositionSpec = z.infer<typeof compositionSpec>;
+export type RepeaterSpec = z.infer<typeof repeaterSpec>;

package/src/schemas/element.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { modifiersSpec } from "./binding";
+import { telemetrySpec } from "./telemetry";
+
+// ─── ElementSpec ─────────────────────────────────────────────────
+// SPEC.md §2.2: type, id, props REQUIRED.
+//
+// CRITICAL RULE: ElementSpec MUST NOT contain `children` or `layout`.
+// These belong exclusively to CompositionSpec (§2.3).
+// Enforced via .refine() to reject any payload with these fields.
+export const elementSpec = z.object({
+    type: z.string().min(1),
+    id: z.string().min(1),
+    props: z.record(z.any()),
+    constraints: z.object({
+        a11y: z.object({
+            aria_label: z.string().optional(),
+            aria_role: z.string().optional(),
+            min_contrast_ratio: z.number().min(1).optional(),
+            focusable: z.boolean().optional(),
+        }).optional(),
+    }).passthrough().optional(),
+    modifiers: modifiersSpec.optional(),
+    telemetry: telemetrySpec.optional(),
+}).passthrough()
+    .refine(
+        (data) => !("children" in data),
+        { message: "ElementSpec MUST NOT contain 'children'. Use CompositionSpec for containers." }
+    )
+    .refine(
+        (data) => !("layout" in data),
+        { message: "ElementSpec MUST NOT contain 'layout'. Use CompositionSpec for layout." }
+    );
+
+// ─── Types ───────────────────────────────────────────────────────
+export type ElementSpec = z.infer<typeof elementSpec>;

package/src/schemas/style.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+
+// ─── Token-Aware Style Schema ────────────────────────────────────
+// SPEC.md §2.6: Properties support both literal and token-based config.
+// Convention: literal `bg_color` + parallel `bg_color_token` (DTCG path).
+//
+// When both are present, runtimes MUST attempt token resolution first.
+// If token resolution fails and literal is type-compatible, runtimes
+// MAY use literal as graceful degradation.
+
+// DTCG token path: e.g. "color.bg.primary"
+const dtcgTokenPath = z.string().min(1);
+
+export const styleSpec = z.object({
+    // ── Color Properties ──
+    bg_color: z.string().optional(),
+    bg_color_token: dtcgTokenPath.optional(),
+    text_color: z.string().optional(),
+    text_color_token: dtcgTokenPath.optional(),
+    border_color: z.string().optional(),
+    border_color_token: dtcgTokenPath.optional(),
+
+    // ── Typography Properties ──
+    font_family: z.string().optional(),
+    font_family_token: dtcgTokenPath.optional(),
+    font_size: z.number().optional(),
+    font_size_token: dtcgTokenPath.optional(),
+    font_weight: z.number().optional(),
+    font_weight_token: dtcgTokenPath.optional(),
+    line_height: z.number().optional(),
+    line_height_token: dtcgTokenPath.optional(),
+
+    // ── Spacing Properties ──
+    padding: z.union([
+        z.number(),
+        z.object({
+            top: z.number().optional(),
+            right: z.number().optional(),
+            bottom: z.number().optional(),
+            left: z.number().optional(),
+        }),
+    ]).optional(),
+    padding_token: dtcgTokenPath.optional(),
+    margin: z.union([
+        z.number(),
+        z.object({
+            top: z.number().optional(),
+            right: z.number().optional(),
+            bottom: z.number().optional(),
+            left: z.number().optional(),
+        }),
+    ]).optional(),
+    margin_token: dtcgTokenPath.optional(),
+
+    // ── Border Properties ──
+    border_radius: z.number().optional(),
+    border_radius_token: dtcgTokenPath.optional(),
+    border_width: z.number().optional(),
+    border_width_token: dtcgTokenPath.optional(),
+
+    // ── Dimension Properties ──
+    min_height: z.number().optional(),
+    min_height_token: dtcgTokenPath.optional(),
+    min_width: z.number().optional(),
+    min_width_token: dtcgTokenPath.optional(),
+    width: z.union([z.number(), z.string()]).optional(),
+    width_token: dtcgTokenPath.optional(),
+    height: z.union([z.number(), z.string()]).optional(),
+    height_token: dtcgTokenPath.optional(),
+
+    // ── Opacity ──
+    opacity: z.number().min(0).max(1).optional(),
+    opacity_token: dtcgTokenPath.optional(),
+}).passthrough(); // Allow vendor extensions (§2.9)
+
+// ─── Types ───────────────────────────────────────────────────────
+export type StyleSpec = z.infer<typeof styleSpec>;

package/src/schemas/surface.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { compositionSpec } from "./composition";
+import { telemetrySpec } from "./telemetry";
+
+// ─── SurfaceSpec ─────────────────────────────────────────────────
+// SPEC.md §2.8: id, root, telemetry REQUIRED.
+//
+// CRITICAL RULE: root MUST be a CompositionSpec.
+// It MUST NOT be an ElementSpec. An Element cannot exist at the
+// root level; it must be contained within a Composition.
+export const surfaceSpec = z.object({
+    id: z.string().min(1).regex(/^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/),
+    root: compositionSpec,
+    telemetry: telemetrySpec,
+    metadata: z.record(z.any()).optional(),
+    environment: z.record(z.any()).optional(),
+}).passthrough();
+
+// ─── Types ───────────────────────────────────────────────────────
+export type SurfaceSpec = z.infer<typeof surfaceSpec>;

package/src/schemas/telemetry.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+// ─── telemetrySpec ───────────────────────────────────────────────
+// SPEC.md §2.3/$defs/telemetrySpec: object with emit string array
+export const telemetrySpec = z.object({
+    emit: z.array(z.string()),
+});
+
+// ─── TelemetryEnvelope ───────────────────────────────────────────
+// SPEC.md §4.5: All telemetry events MUST share this common envelope.
+// All fields are REQUIRED per the normative schema.
+export const telemetryEnvelopeSpec = z.object({
+    session_id: z.string().min(1),
+    element_id: z.string().min(1),
+    timestamp: z.string(), // ISO 8601 UTC
+    revision_id: z.string().min(1),
+    event_type: z.string().min(1),
+    payload: z.record(z.any()),
+}).passthrough(); // additionalProperties: true per §4.5
+
+// ─── Types ───────────────────────────────────────────────────────
+export type TelemetrySpec = z.infer<typeof telemetrySpec>;
+export type TelemetryEnvelope = z.infer<typeof telemetryEnvelopeSpec>;

package/src/schemas/token.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+// ─── DTCG Token Format Schema ────────────────────────────────────
+// SPEC.md §2.6: DESEN MUST reuse the Design Tokens Community Group
+// (DTCG) Design Tokens Format Module.
+//
+// A token leaf node has { $type, $value } (required) and
+// optional $description. Non-leaf nodes are groups that contain
+// other token nodes or groups (recursive).
+//
+// Example:
+// {
+//   "color": {
+//     "bg": {
+//       "primary": { "$type": "color", "$value": "#0B5FFF" }
+//     }
+//   }
+// }
+
+// Leaf token node — the actual design token
+export const dtcgTokenLeaf = z.object({
+    $type: z.string().min(1),
+    $value: z.any(),
+    $description: z.string().optional(),
+}).passthrough();
+
+// Recursive token group — can contain leaves or nested groups
+export type DTCGTokenGroup = {
+    [key: string]: DTCGTokenGroup | { $type: string; $value: any; $description?: string };
+};
+
+// The full token theme is a recursive structure.
+// We use z.record + z.lazy for recursive validation.
+const dtcgTokenNode: z.ZodType<any> = z.lazy(() =>
+    z.union([
+        dtcgTokenLeaf,
+        z.record(dtcgTokenNode),
+    ])
+);
+
+// ─── TokenThemeSchema ────────────────────────────────────────────
+// Top-level theme file: a record of token groups
+// e.g. { "color": { "bg": { "primary": { "$type": "color", "$value": "#0B5FFF" } } } }
+export const tokenThemeSchema = z.record(dtcgTokenNode);
+
+// ─── Types ───────────────────────────────────────────────────────
+export type DTCGTokenLeaf = z.infer<typeof dtcgTokenLeaf>;
+export type TokenTheme = z.infer<typeof tokenThemeSchema>;

package/test-schemas.js

@@ -0,0 +1,62 @@
+const { surfaceSpec, elementSpec, tokenThemeSchema } = require('./dist/index');
+
+// TEST 1: Valid SurfaceSpec 
+const validSurface = {
+    id: 'promo.surface',
+    root: {
+        type: 'Stack',
+        id: 'promo.root',
+        layout: { kind: 'stack', direction: 'vertical' },
+        children: [
+            { type: 'Text', id: 'promo.title', props: { text: 'Hello DESEN' } }
+        ],
+        telemetry: { emit: ['VIEW_ELEMENT'] }
+    },
+    telemetry: { emit: ['VIEW_ELEMENT'] }
+};
+const r1 = surfaceSpec.safeParse(validSurface);
+console.log('TEST 1 (Valid Surface):', r1.success ? 'PASS ✅' : 'FAIL ❌', r1.error?.issues?.map(i => i.message).join('; ') || '');
+
+// TEST 2: Element with children → MUST FAIL
+const badElement = { type: 'Button', id: 'bad', props: {}, children: [] };
+const r2 = elementSpec.safeParse(badElement);
+console.log('TEST 2 (Element+children rejected):', !r2.success ? 'PASS ✅' : 'FAIL ❌', r2.error?.issues?.map(i => i.message).join('; ') || '');
+
+// TEST 3: Element with layout → MUST FAIL
+const badElement2 = { type: 'Button', id: 'bad2', props: {}, layout: { kind: 'stack' } };
+const r3 = elementSpec.safeParse(badElement2);
+console.log('TEST 3 (Element+layout rejected):', !r3.success ? 'PASS ✅' : 'FAIL ❌', r3.error?.issues?.map(i => i.message).join('; ') || '');
+
+// TEST 4: DTCG Token validation
+const validTheme = { color: { bg: { primary: { $type: 'color', $value: '#0B5FFF' } } } };
+const r4 = tokenThemeSchema.safeParse(validTheme);
+console.log('TEST 4 (DTCG Theme valid):', r4.success ? 'PASS ✅' : 'FAIL ❌', r4.error?.issues?.map(i => i.message).join('; ') || '');
+
+// TEST 5: Surface with Element root → MUST FAIL
+const badSurface = {
+    id: 'bad.surface',
+    root: { type: 'Button', id: 'btn', props: {} },
+    telemetry: { emit: ['VIEW_ELEMENT'] }
+};
+const r5 = surfaceSpec.safeParse(badSurface);
+console.log('TEST 5 (Element root rejected):', !r5.success ? 'PASS ✅' : 'FAIL ❌');
+
+// TEST 6: Valid Element with modifiers binding
+const validElement = {
+    type: 'Button',
+    id: 'admin.delete',
+    props: { text: 'Delete' },
+    modifiers: {
+        visible: { bind: { source: 'session', path: 'user.is_admin', fallback: false } }
+    }
+};
+const r6 = elementSpec.safeParse(validElement);
+console.log('TEST 6 (Element+modifiers valid):', r6.success ? 'PASS ✅' : 'FAIL ❌', r6.error?.issues?.map(i => i.message).join('; ') || '');
+
+// TEST 7: Binding with invalid source → MUST FAIL  
+const { bindingSpec } = require('./dist/index');
+const badBinding = { source: 'unknown_source', path: 'user.name' };
+const r7 = bindingSpec.safeParse(badBinding);
+console.log('TEST 7 (Invalid binding source rejected):', !r7.success ? 'PASS ✅' : 'FAIL ❌');
+
+console.log('\n--- All tests complete ---');

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "CommonJS",
+        "declaration": true,
+        "outDir": "./dist",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": [
+        "src/**/*"
+    ]
+}