@cossackframework/renderer 0.1.0 → 0.3.9

package/README.md

@@ -0,0 +1,309 @@
+# Cossack Renderer Package
+
+Cossack Renderer is a Lit-compatible rendering engine designed for **Light DOM** and **SSR**. It provides a familiar API for building components but focuses on returning HTML strings directly for SSR and managing DOM updates without Shadow DOM isolation.
+
+## Installation
+
+This package is intended to use with the Cossack Framework via `create-cossack-app`, but can also be used standalone in any project that needs a lightweight rendering solution.
+
+```bash
+pnpm add @cossackframework/renderer
+```
+
+## Defining Components
+
+Components are classes that extend `CossackElement`. They manage their own state and render template results.
+
+```typescript
+import { CossackElement, html } from '@cossackframework/renderer';
+
+export class MyCounter extends CossackElement {
+  // Define reactive properties
+  static properties = {
+    count: { state: true },
+    label: { state: true }
+  };
+
+  // Declare fields for TypeScript
+  declare count: number;
+  declare label: string;
+
+  constructor() {
+    super();
+    this.count = 0;
+    this.label = 'Count';
+  }
+
+  increment() {
+    this.count++;
+  }
+
+  render() {
+    return html`
+      <div>
+        <span>${this.label}: ${this.count}</span>
+        <button @click="${() => this.increment()}">+</button>
+      </div>
+    `;
+  }
+}
+```
+
+## Rendering
+
+### Client-Side Rendering (Hydration/Mounting)
+
+To mount a component to the DOM:
+
+```typescript
+import { MyCounter } from './MyCounter';
+
+const container = document.getElementById('app');
+const app = new MyCounter();
+app.mount(container); // Mounts and renders to the container
+```
+
+### Server-Side Rendering (SSR)
+
+To render a component to an HTML string:
+
+```typescript
+import { renderToString } from '@cossackframework/renderer';
+import { MyCounter } from './MyCounter';
+
+const app = new MyCounter();
+// Optional: Wait for async data or updates
+const htmlString = renderToString(app.render());
+console.log(htmlString);
+```
+
+## Template Syntax
+
+Cossack uses tagged template literals via `html`.
+
+### Basic Expressions
+
+```typescript
+html`<h1>Hello ${name}</h1>`
+```
+
+### Attributes
+
+Boolean attributes are removed if `false/null/undefined`.
+
+```typescript
+html`<button ?disabled="${isDisabled}">Click</button>`
+```
+
+### Event Binding
+
+Bind event listeners using Lit's `@` syntax.
+
+```typescript
+html`<button @click="${(e) => this.handleClick(e)}">Click Me</button>`
+```
+
+### Property Binding
+
+For `<input>` elements, use `.` prefix to bind properties directly.
+
+```typescript
+html`<input type="text" .value="${this.inputValue}" @input="${this.handleInput}" />`
+```
+
+### Spread Attributes
+
+You can spread an object into attributes using the `...` syntax.
+
+```typescript
+const props = { id: 'btn', class: 'primary', 'data-type': 'action' };
+html`<button ...=${props}>Click</button>`
+```
+
+### Unsafe HTML
+
+To render raw HTML strings (careful!):
+
+```typescript
+import { unsafeHTML } from '@cossackframework/renderer';
+html`<div>${unsafeHTML('<script>...</script>')}</div>`
+```
+
+## Using Components in Templates
+
+Use the `component` helper function to include child components in your templates.
+
+```typescript
+import { component } from '@cossackframework/renderer';
+import { ChildComponent } from './ChildComponent';
+
+html`
+  <div class="parent">
+    ${component(ChildComponent, { someProp: 'value' })}
+  </div>
+`
+```
+
+You can also pass children to components:
+
+```typescript
+html`
+  <div class="parent">
+    ${component(ChildComponent, { someProp: 'value' }, html`
+      <span>Child content</span>
+    `)}
+  </div>
+`
+```
+
+## Directives
+
+Cossack includes standard Lit directives.
+
+### `repeat` (Keyed Lists)
+
+Efficiently renders lists by key.
+
+```typescript
+import { repeat } from '@cossackframework/renderer';
+
+html`
+  <ul>
+    ${repeat(items, (item) => item.id, (item) => html`
+      <li>${item.text}</li>
+    `)}
+  </ul>
+`
+```
+
+### `classMap` & `styleMap`
+
+Dynamic classes and styles.
+
+```typescript
+import { classMap, styleMap } from '@cossackframework/renderer';
+
+const classes = { active: isActive, error: hasError };
+const styles = { color: 'red', display: isVisible ? 'block' : 'none' };
+
+html`<div class="${classMap(classes)}" style="${styleMap(styles)}">...</div>`
+```
+
+### `ref`
+
+Get a reference to the DOM element.
+
+```typescript
+import { ref } from '@cossackframework/renderer';
+
+html`<input ref="${(el) => console.log(el)}" />`
+```
+
+### `live`
+
+Check against the live DOM value (useful for inputs).
+
+```typescript
+import { live } from '@cossackframework/renderer';
+
+html`<input .value="${live(inputValue)}" />`
+```
+
+## Context API
+
+Share state deep in the tree.
+
+### 1. Create Context
+
+```typescript
+import { createContext } from '@cossackframework/renderer';
+
+export const ThemeContext = createContext('light'); // Default value
+```
+
+### 2. Provide Context
+
+```typescript
+class App extends CossackElement {
+  render() {
+    this.provide(ThemeContext, 'dark');
+    return html`${component(Child)}`;
+  }
+}
+```
+
+### 3. Consume Context
+
+```typescript
+class Child extends CossackElement {
+  render() {
+    const theme = this.consume(ThemeContext);
+    return html`<span>Theme is ${theme}</span>`;
+  }
+}
+```
+
+## Reactive Controllers
+
+Reuse logic across components using controllers.
+
+```typescript
+import { ReactiveController, ReactiveControllerHost } from '@cossackframework/renderer';
+
+class ClockController implements ReactiveController {
+  host: ReactiveControllerHost;
+  value = new Date();
+  private timer?: number;
+
+  constructor(host: ReactiveControllerHost) {
+    this.host = host;
+    host.addController(this);
+  }
+
+  hostConnected() {
+    this.timer = setInterval(() => {
+      this.value = new Date();
+      this.host.requestUpdate();
+    }, 1000);
+  }
+
+  hostDisconnected() {
+    clearInterval(this.timer);
+  }
+}
+
+class ClockElement extends CossackElement {
+  private clock = new ClockController(this);
+
+  render() {
+    return html`<time>${this.clock.value.toLocaleTimeString()}</time>`;
+  }
+}
+```
+
+## Children Projection (Slots)
+
+Cossack supports passing children to components.
+
+**Parent:**
+```typescript
+html`
+  ${component(Card, {}, html`
+    <h1>Title</h1>
+    <p>Content</p>
+  `)}
+`
+```
+
+**Child (Card):**
+```typescript
+class Card extends CossackElement {
+  render() {
+    return html`
+      <div class="card">
+        ${this.children}
+      </div>
+    `;
+  }
+}
+```

package/dist/cossack-element.d.ts

@@ -28,6 +28,7 @@ export declare const popCurrentInstance: () => CossackElement | undefined;
 export declare class CossackElement implements ReactiveControllerHost {
     static properties: PropertyDeclarations;
     static readonly _isCossackElement = true;
+    static components: Record<string, typeof CossackElement>;
     children: unknown;
     props: Record<string, unknown>;
     __parent: CossackElement | null;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as n, L as r, R as l, T as p, U as o, k as u, c, e as i, h as m, d as R, g as T, i as f, a as C, l as M, f as d, p as L, b as g, r as h, j as H, m as k, s as v, u as x } from "./server-BEO1YttH.js";
+import { C as n, L as r, R as l, T as p, U as o, k as u, c, e as i, h as m, d as R, g as T, i as f, a as C, l as M, f as d, p as L, b as g, r as h, j as H, m as k, s as v, u as x } from "./server-BASPjT-s.js";
 function e(s) {
   return {
     id: Math.random().toString(36).slice(2),

package/dist/{server-BEO1YttH.js → server-BASPjT-s.js}

@@ -1,25 +1,25 @@
 var F = Object.defineProperty;
 var z = (n, e, s) => e in n ? F(n, e, { enumerable: !0, configurable: !0, writable: !0, value: s }) : n[e] = s;
-var h = (n, e, s) => z(n, typeof e != "symbol" ? e + "" : e, s);
-const L = (n) => typeof n == "object" && n !== null && n._type === "COMPONENT", g = [], k = (n) => g.push(n), x = () => g.pop();
-class T {
+var o = (n, e, s) => z(n, typeof e != "symbol" ? e + "" : e, s);
+const T = (n) => typeof n == "object" && n !== null && n._type === "COMPONENT", g = [], W = (n) => g.push(n), x = () => g.pop();
+class y {
   constructor() {
     // Holds content projected from the parent
-    h(this, "children", null);
-    h(this, "props", {});
+    o(this, "children", null);
+    o(this, "props", {});
     // Context Support
-    h(this, "__parent", null);
-    h(this, "_id", "");
-    h(this, "_childCounter", 0);
-    h(this, "__providedContexts", /* @__PURE__ */ new Map());
-    h(this, "__properties", /* @__PURE__ */ new Map());
-    h(this, "__updatePromise", null);
-    h(this, "__changedProperties", /* @__PURE__ */ new Map());
-    h(this, "__renderListeners", /* @__PURE__ */ new Set());
+    o(this, "__parent", null);
+    o(this, "_id", "");
+    o(this, "_childCounter", 0);
+    o(this, "__providedContexts", /* @__PURE__ */ new Map());
+    o(this, "__properties", /* @__PURE__ */ new Map());
+    o(this, "__updatePromise", null);
+    o(this, "__changedProperties", /* @__PURE__ */ new Map());
+    o(this, "__renderListeners", /* @__PURE__ */ new Set());
     // Controllers
-    h(this, "__controllers", /* @__PURE__ */ new Set());
-    h(this, "__hasConnected", !1);
-    h(this, "__eventListeners", /* @__PURE__ */ new Map());
+    o(this, "__controllers", /* @__PURE__ */ new Set());
+    o(this, "__hasConnected", !1);
+    o(this, "__eventListeners", /* @__PURE__ */ new Map());
     this.initialize();
   }
   // --- Static Stack Access for cossack-html ---
@@ -78,7 +78,7 @@ class T {
     let e = !1;
     try {
       if (e = this.shouldUpdate(this.__changedProperties), e) {
-        this.__controllers.forEach((t) => t.hostUpdate && t.hostUpdate()), this.willUpdate(this.__changedProperties), this.resetRenderState(), k(this);
+        this.__controllers.forEach((t) => t.hostUpdate && t.hostUpdate()), this.willUpdate(this.__changedProperties), this.resetRenderState(), W(this);
         const s = this.render();
         this.__notifyListeners(s), x(), this.updated(this.__changedProperties), this.__controllers.forEach((t) => t.hostUpdated && t.hostUpdated());
       }
@@ -98,7 +98,7 @@ class T {
   }
   mount(e) {
     this.addRenderListener((s) => {
-      s && (S(s) ? I(s, e) : I(E`${s}`, e));
+      s && (S(s) ? I(s, e) : I(L`${s}`, e));
     }), this.requestUpdate();
   }
   addEventListener(e, s, t) {
@@ -132,36 +132,36 @@ class T {
     this.__hasConnected = !1, this.__controllers.forEach((e) => e.hostDisconnected && e.hostDisconnected());
   }
 }
-h(T, "properties", {}), h(T, "_isCossackElement", !0);
+o(y, "properties", {}), o(y, "_isCossackElement", !0), o(y, "components", {});
 class R {
   constructor(e) {
     this.value = e;
   }
 }
-class y {
+class E {
   constructor(e, s, t) {
     this.items = e, this.keyFn = s, this.templateFn = t;
   }
 }
-const Z = (n) => new R(n), X = (n, e, s) => s === void 0 ? new y(n, (t, i) => i, e) : new y(n, e, s), G = (n) => Object.keys(n).filter((e) => n[e]).join(" "), J = (n) => Object.keys(n).filter((e) => n[e] != null).map((e) => `${e}:${n[e]}`).join(";");
+const Z = (n) => new R(n), X = (n, e, s) => s === void 0 ? new E(n, (t, i) => i, e) : new E(n, e, s), G = (n) => Object.keys(n).filter((e) => n[e]).join(" "), J = (n) => Object.keys(n).filter((e) => n[e] != null).map((e) => `${e}:${n[e]}`).join(";");
 class B {
   constructor(e, s) {
-    h(this, "_cossack_template_result", !0);
+    o(this, "_cossack_template_result", !0);
     this.strings = e, this.values = s;
   }
 }
-const E = (n, ...e) => new B(n, e), Q = E, Y = (n, e = {}, s) => E`${{
+const L = (n, ...e) => new B(n, e), Q = L, Y = (n, e = {}, s) => L`${{
   _type: "COMPONENT",
   clazz: n,
   props: e,
   children: s
 }}`, S = (n) => typeof n == "object" && n !== null && n._cossack_template_result === !0;
-class W {
+class k {
   constructor(e) {
     this.value = e;
   }
 }
-const ee = (n) => new W(n), U = (n) => n instanceof W, H = (n) => String(n).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;"), N = (n) => {
+const ee = (n) => new k(n), U = (n) => n instanceof k, H = (n) => String(n).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;"), N = (n) => {
   if (n == null || n === !1)
     return "";
   if (Array.isArray(n))
@@ -170,14 +170,14 @@ const ee = (n) => new W(n), U = (n) => n instanceof W, H = (n) => String(n).repl
     return A(n);
   if (n instanceof R)
     return N(n.value);
-  if (n instanceof y)
+  if (n instanceof E)
     return n.items.map((e, s) => N(n.templateFn(e, s))).join("");
-  if (L(n)) {
+  if (T(n)) {
     const e = new n.clazz();
-    Object.assign(e, n.props), "props" in e && (e.props = n.props), e.children = n.children, e.__parent = T.currentRenderingInstance, e.__parent && (e._id = `${e.__parent._id}:${e.__parent._childCounter++}`), e.connectedCallback(), k(e), e.willUpdate(/* @__PURE__ */ new Map());
+    Object.assign(e, n.props), "props" in e && (e.props = n.props), e.children = n.children, e.__parent = y.currentRenderingInstance, e.__parent && (e._id = `${e.__parent._id}:${e.__parent._childCounter++}`), e.connectedCallback(), W(e), e.willUpdate(/* @__PURE__ */ new Map());
     const s = e.render();
     let t = "";
-    return s && (S(s) ? t = A(s) : t = A(E`${s}`)), x(), t;
+    return s && (S(s) ? t = A(s) : t = A(L`${s}`)), x(), t;
   }
   return U(n) ? n.value : typeof n == "function" || typeof n == "object" && n !== null && "value" in n ? "" : H(n);
 }, V = (n) => {
@@ -196,9 +196,9 @@ const ee = (n) => new W(n), U = (n) => n instanceof W, H = (n) => String(n).repl
 };
 class D {
   constructor(e) {
-    h(this, "result", "");
-    h(this, "stringIdx", 0);
-    h(this, "charIdxForNext", 0);
+    o(this, "result", "");
+    o(this, "stringIdx", 0);
+    o(this, "charIdxForNext", 0);
     this.resultObj = e;
   }
   scan() {
@@ -227,23 +227,23 @@ class D {
 const A = (n) => new D(n).scan();
 class $ {
   constructor(e, s) {
-    h(this, "componentInstance", null);
-    h(this, "renderListener", null);
-    h(this, "_childParts", []);
-    h(this, "_partKeys", []);
+    o(this, "componentInstance", null);
+    o(this, "renderListener", null);
+    o(this, "_childParts", []);
+    o(this, "_partKeys", []);
     // Cache for nested template result updates
-    h(this, "_cachedTemplateStrings", null);
-    h(this, "_cachedParts", null);
+    o(this, "_cachedTemplateStrings", null);
+    o(this, "_cachedParts", null);
     this.startNode = e, this.endNode = s;
   }
   update(e) {
-    this.componentInstance && (!L(e) || e.clazz !== this.componentInstance.constructor) && this.disposeComponent(), !(e instanceof y) && !Array.isArray(e) && this._childParts.length > 0 && this.clearChildParts(), L(e) ? this.updateComponent(e) : e instanceof y ? this.updateRepeat(e) : Array.isArray(e) ? this.updateArray(e) : this.updateNode(e);
+    this.componentInstance && (!T(e) || e.clazz !== this.componentInstance.constructor) && this.disposeComponent(), !(e instanceof E) && !Array.isArray(e) && this._childParts.length > 0 && this.clearChildParts(), T(e) ? this.updateComponent(e) : e instanceof E ? this.updateRepeat(e) : Array.isArray(e) ? this.updateArray(e) : this.updateNode(e);
   }
   disposeComponent() {
     this.componentInstance && (this.renderListener && this.componentInstance.removeRenderListener(this.renderListener), this.componentInstance.disconnectedCallback(), this.componentInstance = null, this.renderListener = null, this._clearTemplateCache());
   }
   updateComponent(e) {
-    this.componentInstance || (this.componentInstance = new e.clazz(), this.componentInstance.__parent = T.currentRenderingInstance, this.componentInstance.__parent && (this.componentInstance._id = `${this.componentInstance.__parent._id}:${this.componentInstance.__parent._childCounter++}`), this.renderListener = (t) => {
+    this.componentInstance || (this.componentInstance = new e.clazz(), this.componentInstance.__parent = y.currentRenderingInstance, this.componentInstance.__parent && (this.componentInstance._id = `${this.componentInstance.__parent._id}:${this.componentInstance.__parent._childCounter++}`), this.renderListener = (t) => {
       this.updateNode(t);
     }, this.componentInstance.addRenderListener(this.renderListener), this.componentInstance.connectedCallback());
     const s = this.componentInstance;
@@ -314,10 +314,10 @@ class $ {
           const i = M.get(((s = t.firstChild) == null ? void 0 : s.childNodes[0]) || t);
           i && (this._cachedTemplateStrings = i.strings, this._cachedParts = i.parts);
         }
-      else if (L(e) || typeof e == "object" && e !== null && !(e instanceof Node) && !Array.isArray(e)) {
+      else if (T(e) || typeof e == "object" && e !== null && !(e instanceof Node) && !Array.isArray(e)) {
         this._clearTemplateCache(), this.clear();
         const t = document.createDocumentFragment();
-        I(E`${e}`, t), this.startNode.parentNode.insertBefore(t, this.endNode);
+        I(L`${e}`, t), this.startNode.parentNode.insertBefore(t, this.endNode);
       } else if (U(e)) {
         this._clearTemplateCache(), this.clear();
         const t = document.createElement("template");
@@ -350,7 +350,7 @@ class $ {
 }
 class q {
   constructor(e) {
-    h(this, "previousValues", {});
+    o(this, "previousValues", {});
     this.element = e;
   }
   update(e) {
@@ -400,22 +400,22 @@ class v {
 const M = /* @__PURE__ */ new WeakMap(), I = (n, e) => {
   const s = M.get(e);
   if (s && s.strings === n.strings) {
-    s.parts.forEach((o, l) => {
-      o.update(n.values[l]);
+    s.parts.forEach((h, l) => {
+      h.update(n.values[l]);
     });
     return;
   }
   const t = [], i = n.values;
   let r = "", a = !1;
-  const c = (o) => {
-    for (let l = 0; l < o.length; l++)
-      o[l] === "<" && o[l + 1] !== "!" && o[l + 1] !== "/" ? a = !0 : o[l] === ">" && (a = !1);
+  const c = (h) => {
+    for (let l = 0; l < h.length; l++)
+      h[l] === "<" && h[l + 1] !== "!" && h[l + 1] !== "/" ? a = !0 : h[l] === ">" && (a = !1);
   }, d = /(\.\.\.|[.@?]?[a-zA-Z0-9_-]+)=["']?$/;
-  for (let o = 0; o < n.strings.length - 1; o++) {
-    const l = n.strings[o];
+  for (let h = 0; h < n.strings.length - 1; h++) {
+    const l = n.strings[h];
     c(l), r += l;
     const u = l.match(d);
-    a && u ? r += `__CRP_${o}__` : r += `<!--CRP_${o}-->`;
+    a && u ? r += `__CRP_${h}__` : r += `<!--CRP_${h}-->`;
   }
   const p = n.strings[n.strings.length - 1];
   c(p), r += p;
@@ -426,18 +426,18 @@ const M = /* @__PURE__ */ new WeakMap(), I = (n, e) => {
   const j = [];
   for (; O = _.nextNode(); )
     j.push(O);
-  j.forEach((o) => {
+  j.forEach((h) => {
     var l;
-    if (o.nodeType === Node.COMMENT_NODE) {
-      const u = (l = o.nodeValue) == null ? void 0 : l.match(/CRP_(\d+)/);
+    if (h.nodeType === Node.COMMENT_NODE) {
+      const u = (l = h.nodeValue) == null ? void 0 : l.match(/CRP_(\d+)/);
       if (u) {
         const C = parseInt(u[1]), P = document.createComment("/CRP");
-        o.parentNode.insertBefore(P, o.nextSibling);
-        const b = new $(o, P);
+        h.parentNode.insertBefore(P, h.nextSibling);
+        const b = new $(h, P);
         t[C] = b;
       }
-    } else if (o.nodeType === Node.ELEMENT_NODE) {
-      const u = o;
+    } else if (h.nodeType === Node.ELEMENT_NODE) {
+      const u = h;
       Array.from(u.attributes).forEach((C) => {
         const P = C.value.match(/__CRP_(\d+)__/);
         if (P) {
@@ -454,8 +454,8 @@ const M = /* @__PURE__ */ new WeakMap(), I = (n, e) => {
       });
     }
   });
-  for (let o = 0; o < i.length; o++)
-    t[o] && t[o].update(i[o]);
+  for (let h = 0; h < i.length; h++)
+    t[h] && t[h].update(i[h]);
   if (e instanceof HTMLElement)
     e.innerHTML = "", e.appendChild(f);
   else if (e instanceof DocumentFragment) {
@@ -466,25 +466,25 @@ const M = /* @__PURE__ */ new WeakMap(), I = (n, e) => {
   M.set(e, { strings: n.strings, parts: t });
 };
 export {
-  T as C,
+  y as C,
   R as L,
-  y as R,
+  E as R,
   B as T,
-  W as U,
+  k as U,
   U as a,
   I as b,
   Y as c,
   g as d,
   H as e,
   x as f,
-  L as g,
-  E as h,
+  T as g,
+  L as h,
   S as i,
   X as j,
   G as k,
   Z as l,
   J as m,
-  k as p,
+  W as p,
   A as r,
   Q as s,
   ee as u

package/dist/server.js

@@ -1,4 +1,4 @@
-import { e as a, r as o } from "./server-BEO1YttH.js";
+import { e as a, r as o } from "./server-BASPjT-s.js";
 export {
   a as escapeHtml,
   o as renderToString

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cossackframework/renderer",
-  "version": "0.1.0",
+  "version": "0.3.9",
   "type": "module",
   "description": "Light DOM rendering engine for the Cossack Framework",
   "license": "MIT",
@@ -27,11 +27,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build",
-    "test": "vitest",
-    "lint": "oxlint"
-  },
   "devDependencies": {
     "htmlparser2": "^10.0.0",
     "magic-string": "^0.30.21",
@@ -40,5 +35,10 @@
     "vite-plugin-dts": "^3.9.1",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^1.2.2"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest",
+    "lint": "oxlint"
   }
-}
+}