npm - @t8n/ui - Versions diffs - 1.0.0 - Mend

@t8n/ui 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/README.md +276 -0
package/index.d.ts +65 -0
package/index.js +131 -0
package/jsconfig.json +13 -0
package/package.json +32 -0
package/test-app/.dockerignore +3 -0
package/test-app/Dockerfile +66 -0
package/test-app/app/actions/hello.js +7 -0
package/test-app/app/app.js +10 -0
package/test-app/app/static/app.html +9 -0
package/test-app/app/static/styles.css +9 -0
package/test-app/app/titan.d.ts +249 -0
package/test-app/eslint.config.js +8 -0
package/test-app/jsconfig.json +20 -0
package/test-app/package.json +25 -0
package/test-app/server/Cargo.toml +32 -0
package/test-app/server/src/action_management.rs +171 -0
package/test-app/server/src/errors.rs +10 -0
package/test-app/server/src/extensions/builtin.rs +828 -0
package/test-app/server/src/extensions/external.rs +309 -0
package/test-app/server/src/extensions/mod.rs +430 -0
package/test-app/server/src/extensions/titan_core.js +178 -0
package/test-app/server/src/main.rs +433 -0
package/test-app/server/src/runtime.rs +314 -0
package/test-app/server/src/utils.rs +33 -0
package/test-app/server/titan_storage.json +5 -0
package/test-app/titan/bundle.js +264 -0
package/test-app/titan/dev.js +350 -0
package/test-app/titan/error-box.js +268 -0
package/test-app/titan/titan.js +129 -0
package/titan.json +20 -0

package/README.md ADDED Viewed

@@ -0,0 +1,276 @@
+````md
+# @titanpl/ui
+A **minimal, explicit UI extension for TitanPL** that lets you render HTML and inject CSS **in a single render call** — with **no static routes**, **no magic**, and **full control**.
+This extension is designed for **action-based routing** and **runtime-first** TitanPL apps.
+---
+## ✨ Features
+- `t.ui.render()` → render HTML + CSS in one call
+- `t.ui.load()` → preload templates for reuse
+- `t.ui.css()` → load CSS manually if needed
+- Simple templating: `tpl{{ var }}`
+- Explicit CSS injection (no hidden parsing)
+- Memory + persistent (`ls`) caching
+- Zero static file server
+- Zero extra routes
+- One extension, one mental model
+---
+## 📦 Installation
+```bash
+npm install @titanpl/ui
+````
+TitanPL automatically loads the extension at runtime.
+---
+## 📁 Project Structure
+```
+app/
+├─ actions/
+│  └─ hello.js
+├─ static/
+│  ├─ app.html
+│  └─ styles.css
+```
+All paths are **relative to `app/`**.
+---
+## 🧠 Core Idea
+TitanPL does **nothing implicitly**.
+* HTML is rendered only when you call `t.ui.render()` or `t.ui.load()`
+* CSS is injected **only if you explicitly request it**
+* You decide where CSS goes in HTML
+---
+## 🧩 Template Syntax
+### Variables
+```html
+tpl{{ name }}
+```
+### CSS injection point
+```html
+tpl{{ css }}
+```
+---
+## 🚀 Usage
+### 1️⃣ HTML Template
+`app/static/app.html`
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  tpl{{ css }}
+</head>
+<body>
+  <h1>tpl{{ name }}</h1>
+</body>
+</html>
+```
+---
+### 2️⃣ CSS File
+`app/static/styles.css`
+```css
+body {
+  background-color: black;
+  height: 100vh;
+}
+h1 {
+  color: rgb(32, 215, 215);
+}
+```
+---
+### 3️⃣ One-Shot Render (Recommended)
+```js
+export const hello = () => {
+  return t.ui.render(
+    "static/app.html",
+    { name: "Titan" },
+    { css: "static/styles.css" }
+  );
+};
+```
+✔ HTML rendered
+✔ CSS injected
+✔ Single response
+✔ No static routes
+---
+### 4️⃣ Multiple CSS Files
+```js
+return t.ui.render(
+  "static/app.html",
+  { name: "Titan" },
+  { css: ["static/base.css", "static/theme.css"] }
+);
+```
+CSS files are injected **in order**.
+---
+## 🔁 Preloading Templates with `t.ui.load()`
+Use this for **high-traffic routes**.
+```js
+const page = t.ui.load("static/app.html");
+export const hello = () => {
+  return page(
+    { name: "Titan" },
+    { css: "static/styles.css" }
+  );
+};
+```
+### Why use `load()`?
+* Template read once
+* Faster per request
+* Cleaner route code
+---
+## 🎯 Manual CSS Loading (Optional)
+If you want full control:
+```js
+export const hello = () => {
+  return t.ui.render("static/app.html", {
+    name: "Titan",
+    css: t.ui.css("static/styles.css")
+  });
+};
+```
+---
+## 🧠 API Reference
+### `t.ui.render(htmlPath, data?, options?)`
+Render HTML once with optional CSS.
+```js
+t.ui.render(
+  "static/app.html",
+  { name: "Titan" },
+  { css: "static/styles.css" }
+);
+```
+---
+### `t.ui.load(htmlPath)`
+Preload template and return a reusable renderer.
+```js
+const page = t.ui.load("static/app.html");
+page(data, options);
+```
+---
+### `t.ui.css(cssPath)`
+Load CSS and return a `<style>` block.
+```js
+t.ui.css("static/styles.css");
+```
+---
+### `t.ui.clearCache()`
+Clear all cached HTML and CSS files.
+```js
+t.ui.clearCache();
+```
+---
+## 🧠 Mental Model (Important)
+```text
+t.ui.render() → returns an HTML response
+tpl{{ css }}  → where styles are injected
+tpl{{ var }}  → template variables
+YOU           → control composition
+```
+No implicit behavior.
+No auto static serving.
+No hidden parsing.
+---
+## ❌ What This Extension Does NOT Do
+* ❌ No static file server
+* ❌ No `<link>` interception
+* ❌ No auto CSS loading
+* ❌ No HTML AST parsing
+* ❌ No framework magic
+This is **intentional**.
+---
+## ✅ Why This Fits TitanPL
+* Runtime-first
+* Predictable
+* Explicit IO
+* Action-based routing friendly
+* Production-safe
+* Easy to debug
+---
+## 🛣️ Possible Extensions (Future)
+* `t.ui.js()` for inline JS
+* Layouts / partials
+* Scoped CSS
+* Dot-path vars (`tpl{{ user.name }}`)
+* HTML escaping / raw blocks

package/index.d.ts ADDED Viewed

@@ -0,0 +1,65 @@
+// Type definitions for @titanpl/ui
+// This file enables type inference when the UI extension
+// is installed in a TitanPL project.
+declare global {
+    namespace Titan {
+      interface Runtime {
+        /**
+         * @titanpl/ui Extension
+         *
+         * Unified UI rendering utilities for TitanPL
+         * (HTML + CSS, runtime-first, action-safe)
+         */
+        ui: {
+          /**
+           * Render an HTML template in one call.
+           *
+           * @param htmlPath Path relative to `app/`
+           * @param data Template variables (tpl{{ var }})
+           * @param options Optional render options
+           */
+          render(
+            htmlPath: string,
+            data?: Record<string, any>,
+            options?: {
+              /**
+               * CSS file or files to inline
+               * Paths are relative to `app/`
+               */
+              css?: string | string[];
+            }
+          ): unknown; // Titan Response
+          /**
+           * Preload an HTML template and return a reusable renderer.
+           *
+           * @param htmlPath Path relative to `app/`
+           */
+          load(
+            htmlPath: string
+          ): (
+            data?: Record<string, any>,
+            options?: {
+              css?: string | string[];
+            }
+          ) => unknown; // Titan Response
+          /**
+           * Load a CSS file and return a <style> string.
+           *
+           * @param cssPath Path relative to `app/`
+           */
+          css(cssPath: string): string;
+          /**
+           * Clear all cached UI templates and styles.
+           */
+          clearCache(): boolean;
+        };
+      }
+    }
+  }
+  export {};

package/index.js ADDED Viewed

@@ -0,0 +1,131 @@
+/**
+ * TitanPL UI Extension (HTML + CSS)
+ * Provides:
+ *   t.ui.load()
+ *   t.ui.render()
+ *   t.ui.css()
+ *   t.ui.clearCache()
+ */
+if (typeof Titan === "undefined") globalThis.Titan = t;
+const EXT_KEY = "ui";
+const { fs, ls } = t.core;
+// --------------------------------------------------
+// Internal cache (per isolate)
+// --------------------------------------------------
+const memoryCache = Object.create(null);
+// --------------------------------------------------
+// Resolve paths relative to app/
+// --------------------------------------------------
+function resolvePath(path) {
+    const root = "../app" || "."
+    return root + `/${path.replace(/^\/+/, "")}`;
+}
+// --------------------------------------------------
+// Load file with memory + persistent cache
+// --------------------------------------------------
+function loadFile(path, prefix) {
+    if (memoryCache[path]) return memoryCache[path];
+    const cached = ls.get(`${prefix}:${path}`);
+    if (cached) {
+        memoryCache[path] = cached;
+        return cached;
+    }
+    const content = fs.readFile(path);
+    memoryCache[path] = content;
+    ls.set(`${prefix}:${path}`, content);
+    return content;
+}
+// --------------------------------------------------
+// Render tpl{{ var }}
+// --------------------------------------------------
+function renderTemplate(template, data = {}) {
+    return template.replace(
+        /tpl\{\{\s*(\w+)\s*\}\}/g,
+        (m, k) => (k in data ? String(data[k]) : m)
+    );
+}
+// --------------------------------------------------
+// Inject CSS into render data
+// --------------------------------------------------
+function injectCSS(data, opts = {}) {
+    if (!opts.css) return data;
+    const cssFiles = Array.isArray(opts.css) ? opts.css : [opts.css];
+    const styles = cssFiles
+        .map(p => {
+            const css = loadFile(resolvePath(p), "css");
+            return `<style>\n${css}\n</style>`;
+        })
+        .join("\n");
+    return {
+        ...data,
+        css: styles
+    };
+}
+// --------------------------------------------------
+// EXTENSION CONTRACT (MANDATORY FOR TITANPL)
+// --------------------------------------------------
+t[EXT_KEY] = {
+    /**
+     * Load HTML template once and return a reusable responder
+     */
+    load(htmlPath) {
+        const fullPath = resolvePath(htmlPath);
+        const tpl = loadFile(fullPath, "html");
+        return (data = {}, opts = {}) => {
+            const finalData = injectCSS(data, opts);
+            const html = renderTemplate(tpl, finalData);
+            return t.response.html(html);
+        };
+    },
+    /**
+     * One-shot render with optional CSS
+     */
+    render(htmlPath, data = {}, opts = {}) {
+        const fullPath = resolvePath(htmlPath);
+        const tpl = loadFile(fullPath, "html");
+        const finalData = injectCSS(data, opts);
+        const html = renderTemplate(tpl, finalData);
+        return t.response.html(html);
+    },
+    /**
+     * Load CSS only (manual usage if needed)
+     */
+    css(cssPath) {
+        const css = loadFile(resolvePath(cssPath), "css");
+        return `<style>\n${css}\n</style>`;
+    },
+    /**
+     * Clear all cached UI files
+     */
+    clearCache() {
+        for (const k in memoryCache) delete memoryCache[k];
+        ls.keys().forEach(k => {
+            if (k.startsWith("html:") || k.startsWith("css:")) {
+                ls.remove(k);
+            }
+        });
+        return true;
+    }
+};

package/jsconfig.json ADDED Viewed

@@ -0,0 +1,13 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "target": "es2021",
+        "checkJs": false,
+        "allowJs": true,
+        "moduleResolution": "node"
+    },
+    "include": [
+        "index.js",
+        "node_modules/titan-sdk/index.d.ts"
+    ]
+}

package/package.json ADDED Viewed

@@ -0,0 +1,32 @@
+{
+    "name": "@t8n/ui",
+    "version": "1.0.0",
+    "description": "A lightweight HTML templating engine for TitanPL with file caching and variable interpolation.",
+    "main": "index.js",
+    "types": "index.d.ts",
+    "type": "module",
+    "scripts": {
+        "test": "titan run ext"
+    },
+    "keywords": [
+        "titanpl",
+        "t8n",
+        "titan",
+        "titan planet",
+        "templating",
+        "html",
+        "template",
+        "engine",
+        "gravity",
+        "@titanpl/core",
+        "@ezetgalxy/titan"
+    ],
+    "author": "Shoya",
+    "license": "ISC",
+    "dependencies": {
+        "@titanpl/core": "2.1.0",
+        "chokidar": "^5.0.0",
+        "esbuild": "^0.27.2",
+        "titanpl-sdk": "^1.0.6"
+    }
+}

package/test-app/.dockerignore ADDED Viewed

@@ -0,0 +1,3 @@
+node_modules
+npm-debug.log
+.git

package/test-app/Dockerfile ADDED Viewed

@@ -0,0 +1,66 @@
+# ================================================================
+# STAGE 1 — Build Titan (JS → Rust)
+# ================================================================
+FROM rust:1.91.1 AS builder
+# Install Node for Titan CLI + bundler
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs
+# Install Titan CLI (latest)
+RUN npm install -g @ezetgalaxy/titan@latest
+WORKDIR /app
+# Copy project files
+COPY . .
+# Install JS dependencies (needed for Titan DSL + bundler)
+RUN npm install
+SHELL ["/bin/bash", "-c"]
+# Extract Titan extensions into .ext
+RUN mkdir -p /app/.ext && \
+    find /app/node_modules -maxdepth 5 -type f -name "titan.json" -print0 | \
+    while IFS= read -r -d '' file; do \
+    pkg_dir="$(dirname "$file")"; \
+    pkg_name="$(basename "$pkg_dir")"; \
+    echo "Copying Titan extension: $pkg_name from $pkg_dir"; \
+    cp -r "$pkg_dir" "/app/.ext/$pkg_name"; \
+    done && \
+    echo "Extensions in .ext:" && \
+    ls -R /app/.ext
+# Build Titan metadata + bundle JS actions
+RUN titan build
+# Build Rust binary
+RUN cd server && cargo build --release
+# ================================================================
+# STAGE 2 — Runtime Image (Lightweight)
+# ================================================================
+FROM debian:stable-slim
+WORKDIR /app
+# Copy Rust binary from builder stage
+COPY --from=builder /app/server/target/release/titan-server ./titan-server
+# Copy Titan routing metadata
+COPY --from=builder /app/server/routes.json ./routes.json
+COPY --from=builder /app/server/action_map.json ./action_map.json
+# Copy Titan JS bundles
+RUN mkdir -p /app/actions
+COPY --from=builder /app/server/actions /app/actions
+# Copy only Titan extensions
+COPY --from=builder /app/.ext ./.ext
+EXPOSE 5100
+CMD ["./titan-server"]

package/test-app/app/actions/hello.js ADDED Viewed

@@ -0,0 +1,7 @@
+export const hello = () => {
+  return t.ui.render(
+    "static/app.html",
+    { name: "Titan" },
+    { css: "static/styles.css" }
+  );
+};

package/test-app/app/app.js ADDED Viewed

@@ -0,0 +1,10 @@
+import t from "../titan/titan.js";
+t.get("/hello").action("hello") // pass a json payload { "name": "titan" }
+t.get("/").reply("Ready to land on Titan Planet 🚀");
+t.start(5100, "Titan Running!", 10);

package/test-app/app/static/app.html ADDED Viewed

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+<head>
+  tpl{{ css }}
+</head>
+<body>
+  <h1>tpl{{ name }}</h1>
+</body>
+</html>

package/test-app/app/static/styles.css ADDED Viewed

@@ -0,0 +1,9 @@
+body{
+    background-color: black;
+    height: 100vh;
+    width: 100%;
+}
+h1{
+    color: rgb(32, 215, 215);
+}