@constela/server 3.0.1 → 4.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @constela/server
 
-Server-side rendering (SSR) for the Constela UI framework.
+Server-side rendering (SSR) for Constela JSON programs.
 
 ## Installation
 
@@ -11,78 +11,127 @@ npm install @constela/server
 **Peer Dependencies:**
 - `@constela/compiler` ^0.7.0
 
-## Overview
+## How It Works
+
+JSON program → HTML string
+
+```json
+{
+  "version": "1.0",
+  "state": { "name": { "type": "string", "initial": "World" } },
+  "view": {
+    "kind": "element",
+    "tag": "h1",
+    "children": [
+      { "kind": "text", "value": { "expr": "lit", "value": "Hello, " } },
+      { "kind": "text", "value": { "expr": "state", "name": "name" } }
+    ]
+  }
+}
+```
 
-This package provides SSR capabilities for Constela applications. Features:
+↓ SSR
 
-- **HTML Generation** - Render programs to HTML strings
-- **Route Context** - Pass route params and query strings
-- **Markdown & Code** - Server-side Markdown and syntax highlighting
-- **Dual Theme** - Light and dark theme code blocks
+```html
+<h1>Hello, World</h1>
+```
 
-## API Reference
+## Features
 
-### renderToString
+### Markdown Rendering
 
-Main SSR function that renders a compiled program to HTML.
+```json
+{
+  "kind": "markdown",
+  "content": { "expr": "data", "name": "article", "path": "content" }
+}
+```
 
-```typescript
-import { renderToString } from '@constela/server';
+Rendered with async parsing and Shiki syntax highlighting.
 
-const html = await renderToString(compiledProgram, {
-  route: {
-    params: { id: '123' },
-    query: { tab: 'overview' },
-    path: '/users/123',
-  },
-  imports: {
-    config: { siteName: 'My Site' },
-  },
-});
+### Code Highlighting
+
+```json
+{
+  "kind": "code",
+  "code": { "expr": "lit", "value": "const x = 1;" },
+  "language": { "expr": "lit", "value": "typescript" }
+}
 ```
 
-**Parameters:**
-- `program: CompiledProgram` - Compiled program from `@constela/compiler`
-- `options?: RenderOptions` - Optional render configuration
+Features:
+- Dual theme support (github-light, github-dark)
+- CSS custom properties for theme switching
+- Preloaded languages: javascript, typescript, json, html, css, python, rust, go, java, bash, markdown
+
+### Route Context
 
-**RenderOptions:**
-```typescript
-interface RenderOptions {
-  route?: {
-    params?: Record<string, string>;
-    query?: Record<string, string>;
-    path?: string;
-  };
-  imports?: Record<string, unknown>;
+Pass route parameters for dynamic pages:
+
+```json
+{
+  "route": { "path": "/users/:id" },
+  "view": {
+    "kind": "text",
+    "value": { "expr": "route", "name": "id", "source": "param" }
+  }
 }
 ```
 
-**Returns:** `Promise<string>` - Complete HTML string
+### Import Data
 
-## Internal Features
+Pass external data at render time:
 
-The package internally handles:
+```json
+{
+  "imports": { "config": "./data/config.json" },
+  "view": {
+    "kind": "text",
+    "value": { "expr": "import", "name": "config", "path": "siteName" }
+  }
+}
+```
 
-**Markdown Rendering:**
-- Async parsing with Shiki syntax highlighting
-- Sanitization via DOMPurify
+### Style Evaluation
+
+Style expressions are evaluated during SSR, producing CSS class strings:
+
+```json
+{
+  "styles": {
+    "button": {
+      "base": "px-4 py-2 rounded",
+      "variants": {
+        "variant": {
+          "primary": "bg-blue-500 text-white",
+          "secondary": "bg-gray-200 text-gray-800"
+        }
+      },
+      "defaultVariants": { "variant": "primary" }
+    }
+  },
+  "view": {
+    "kind": "element",
+    "tag": "button",
+    "props": {
+      "className": {
+        "expr": "style",
+        "name": "button",
+        "variants": { "variant": { "expr": "lit", "value": "primary" } }
+      }
+    }
+  }
+}
+```
 
-**Code Highlighting:**
-- Dual theme support (github-light, github-dark)
-- CSS custom properties for theme switching
-- Preloaded languages: javascript, typescript, json, html, css, python, rust, go, java, bash, markdown
+↓ SSR
 
-**CSS Variables:** Code blocks use CSS custom properties:
-```css
-/* Light mode */
-.shiki { background-color: var(--shiki-light-bg); }
-.shiki span { color: var(--shiki-light); }
-
-/* Dark mode */
-.dark .shiki { background-color: var(--shiki-dark-bg); }
-.dark .shiki span { color: var(--shiki-dark); }
+```html
+<button class="px-4 py-2 rounded bg-blue-500 text-white">...</button>
 ```
 
+Pass style presets via `RenderOptions.styles` for evaluation.
+
 ## Output Structure
 
 ### Code Block HTML
@@ -91,23 +140,23 @@ The package internally handles:
 <div class="constela-code" data-code-content="...">
   <div class="group relative">
     <div class="language-badge">typescript</div>
-    <button class="constela-copy-btn">
-      <!-- Copy icon SVG -->
-    </button>
+    <button class="constela-copy-btn"><!-- Copy icon --></button>
     <pre><code class="shiki">...</code></pre>
   </div>
 </div>
 ```
 
-The `data-code-content` attribute contains the raw code for copy functionality.
-
-## Expression Evaluation
+### CSS Variables
 
-SSR evaluates expressions server-side with some limitations:
+```css
+/* Light mode */
+.shiki { background-color: var(--shiki-light-bg); }
+.shiki span { color: var(--shiki-light); }
 
-- **No DOM refs** - `ref` expressions return `null`
-- **No safe globals** - Limited to basic operations
-- **Static only** - No reactive updates
+/* Dark mode */
+.dark .shiki { background-color: var(--shiki-dark-bg); }
+.dark .shiki span { color: var(--shiki-dark); }
+```
 
 ## Security
 
@@ -115,29 +164,56 @@ SSR evaluates expressions server-side with some limitations:
 - **DOMPurify** - Markdown content is sanitized
 - **Prototype Pollution Prevention** - Same as runtime
 
-## Example
+## Internal API
+
+> For framework developers only. End users should use the CLI.
+
+### renderToString
 
 ```typescript
-import { compile } from '@constela/compiler';
 import { renderToString } from '@constela/server';
 
-const program = compile({
-  version: '1.0',
-  state: { name: { type: 'string', initial: 'World' } },
-  actions: [],
-  view: {
-    kind: 'element',
-    tag: 'h1',
-    children: [
-      { kind: 'text', value: { expr: 'lit', value: 'Hello, ' } },
-      { kind: 'text', value: { expr: 'state', name: 'name' } },
-    ],
+const html = await renderToString(compiledProgram, {
+  route: {
+    params: { id: '123' },
+    query: { tab: 'overview' },
+    path: '/users/123',
+  },
+  imports: {
+    config: { siteName: 'My Site' },
+  },
+  styles: {
+    button: {
+      base: 'px-4 py-2 rounded',
+      variants: {
+        variant: {
+          primary: 'bg-blue-500 text-white',
+          secondary: 'bg-gray-200 text-gray-800',
+        },
+      },
+      defaultVariants: { variant: 'primary' },
+    },
   },
 });
+```
+
+**RenderOptions:**
+
+```typescript
+interface RenderOptions {
+  route?: {
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    path?: string;
+  };
+  imports?: Record<string, unknown>;
+  styles?: Record<string, StylePreset>;
+}
 
-if (program.ok) {
-  const html = await renderToString(program.program);
-  console.log(html); // '<h1>Hello, World</h1>'
+interface StylePreset {
+  base: string;
+  variants?: Record<string, Record<string, string>>;
+  defaultVariants?: Record<string, string>;
 }
 ```
 
@@ -145,14 +221,21 @@ if (program.ok) {
 
 Server-rendered HTML can be hydrated on the client:
 
-```typescript
-// Server
-import { renderToString } from '@constela/server';
-const html = await renderToString(program, { route, imports });
-
-// Client
-import { hydrateApp } from '@constela/runtime';
-hydrateApp({ program, mount, route, imports });
+```json
+{
+  "version": "1.0",
+  "lifecycle": { "onMount": "initializeClient" },
+  "state": { ... },
+  "actions": [
+    {
+      "name": "initializeClient",
+      "steps": [
+        { "do": "storage", "operation": "get", "key": { "expr": "lit", "value": "preferences" }, ... }
+      ]
+    }
+  ],
+  "view": { ... }
+}
 ```
 
 ## License

package/dist/index.d.ts

@@ -6,6 +6,17 @@ import { CompiledProgram } from '@constela/compiler';
  * Renders CompiledProgram to HTML string for Server-Side Rendering.
  */
 
+/**
+ * Style preset definition for SSR
+ */
+interface StylePreset {
+    base: string;
+    variants?: Record<string, Record<string, string>>;
+    defaultVariants?: Record<string, string>;
+    compoundVariants?: Array<Record<string, string> & {
+        class: string;
+    }>;
+}
 /**
  * Options for renderToString
  */
@@ -16,6 +27,7 @@ interface RenderOptions {
         path?: string;
     };
     imports?: Record<string, unknown>;
+    styles?: Record<string, StylePreset>;
 }
 /**
  * Renders a CompiledProgram to an HTML string.

package/dist/index.js

@@ -213,6 +213,12 @@ function evaluate(expr, ctx) {
       if (typeof key === "string" && forbiddenKeys.has(key)) return void 0;
       return base[key];
     }
+    case "param": {
+      return void 0;
+    }
+    case "style": {
+      return evaluateStyle(expr, ctx);
+    }
     default: {
       const _exhaustiveCheck = expr;
       throw new Error(`Unknown expression type: ${JSON.stringify(_exhaustiveCheck)}`);
@@ -304,6 +310,36 @@ function evaluateBinary(op, left, right, ctx) {
       throw new Error("Unknown binary operator: " + op);
   }
 }
+function evaluateStyle(expr, ctx) {
+  const preset = ctx.styles?.[expr.name];
+  if (!preset) return "";
+  let classes = preset.base;
+  if (preset.variants) {
+    for (const variantKey of Object.keys(preset.variants)) {
+      let variantValueStr = null;
+      if (expr.variants?.[variantKey]) {
+        let variantValue;
+        try {
+          variantValue = evaluate(expr.variants[variantKey], ctx);
+        } catch {
+          continue;
+        }
+        if (variantValue != null) {
+          variantValueStr = String(variantValue);
+        }
+      } else if (preset.defaultVariants?.[variantKey] !== void 0) {
+        variantValueStr = preset.defaultVariants[variantKey];
+      }
+      if (variantValueStr !== null) {
+        const variantClasses = preset.variants[variantKey]?.[variantValueStr];
+        if (variantClasses) {
+          classes += " " + variantClasses;
+        }
+      }
+    }
+  }
+  return classes.trim();
+}
 function formatValue(value) {
   if (value === null || value === void 0) {
     return "";
@@ -432,7 +468,8 @@ async function renderToString(program, options) {
       query: options.route.query ?? {},
       path: options.route.path ?? ""
     } : void 0,
-    imports: options?.imports ?? program.importData
+    imports: options?.imports ?? program.importData,
+    styles: options?.styles
   };
   return await renderNode(program.view, ctx);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/server",
-  "version": "3.0.1",
+  "version": "4.1.0",
   "description": "Server-side rendering for Constela UI framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "@constela/compiler": "^0.7.0"
+    "@constela/compiler": "^0.8.0"
   },
   "dependencies": {
     "isomorphic-dompurify": "^2.35.0",
@@ -28,7 +28,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^2.0.0",
-    "@constela/compiler": "0.7.0"
+    "@constela/compiler": "0.8.0"
   },
   "engines": {
     "node": ">=20.0.0"