@cossackframework/renderer 0.6.0 → 0.7.1

package/dist/cossack-html.d.ts

@@ -1,5 +1,4 @@
 import { CossackElement } from './cossack-element';
-
 export declare class TemplateResult {
     readonly strings: TemplateStringsArray;
     readonly values: unknown[];
@@ -7,7 +6,7 @@ export declare class TemplateResult {
     constructor(strings: TemplateStringsArray, values: unknown[]);
 }
 export declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult;
-export declare const component: <T extends CossackElement>(clazz: new () => T, props?: Record<string, unknown>, children?: unknown) => TemplateResult;
+export declare const component: <T extends CossackElement>(clazz: new () => T, props?: T['props'] & Record<string, unknown>, children?: unknown) => TemplateResult;
 export declare const isTemplateResult: (value: unknown) => value is TemplateResult;
 export declare class UnsafeHTMLResult {
     readonly value: string;
@@ -16,5 +15,18 @@ export declare class UnsafeHTMLResult {
 export declare const unsafeHTML: (value: string) => UnsafeHTMLResult;
 export declare const isUnsafeHTML: (value: unknown) => value is UnsafeHTMLResult;
 export declare const escapeHtml: (unsafe: unknown) => string;
-export declare const renderToString: (result: TemplateResult) => string;
+export declare const renderToString: (result: TemplateResult, opts?: {
+    hydrate?: boolean;
+}) => string;
 export declare const render: (result: TemplateResult, container: Node) => void;
+/**
+ * Hydrate an existing container whose children were produced by SSR
+ * (`renderToString(result, { hydrate: true })`). Binds Part objects to the
+ * existing DOM nodes and adopts their SSR-rendered values instead of clearing
+ * and rebuilding — preserving the server-rendered DOM (no flash, no lost
+ * input/scroll, no duplicate component initialization).
+ *
+ * If the existing DOM cannot be confidently matched to the template, falls
+ * back to a full `render()` so behaviour is always correct.
+ */
+export declare const hydrate: (result: TemplateResult, container: Node) => void;

package/dist/directives.d.ts

@@ -13,6 +13,29 @@ export declare class KeyResult {
     readonly template: unknown;
     constructor(value: unknown, template: unknown);
 }
+export declare class BindResult {
+    readonly component: unknown;
+    readonly fieldName: string;
+    constructor(component: unknown, fieldName: string);
+}
+export declare class PreventDefaultResult {
+    readonly handler: EventListener;
+    readonly novalidate: boolean;
+    constructor(handler: EventListener, novalidate: boolean);
+}
+export declare class IfDefinedResult {
+    readonly value: unknown;
+    constructor(value: unknown);
+}
+export declare class GuardResult {
+    readonly deps: unknown;
+    readonly factory: () => unknown;
+    constructor(deps: unknown, factory: () => unknown);
+}
+export declare class CacheResult {
+    readonly value: unknown;
+    constructor(value: unknown);
+}
 /**
  * Checks against the DOM value instead of the previous rendered value.
  * Usage: <input .value=${live(x)}>
@@ -39,4 +62,203 @@ export declare const styleMap: (styleInfo: Record<string, string | undefined | n
  * Usage: html`${key(id, html`<child></child>`)}`
  */
 export declare const key: (value: unknown, template: unknown) => KeyResult;
+/**
+ * Two-way binding for a form element's value/checked against a component
+ * state field. Reads the field for rendering AND writes user edits back to
+ * it (which triggers a re-render via the `@State` setter).
+ *
+ * Usage (`.value`/`.checked` is inferred from the bound attribute):
+ *   <input .value="${bind(this, 'email')}" />
+ *   <input type="checkbox" .checked="${bind(this, 'active')}" />
+ *
+ * `bind` picks the DOM property to bind from the attribute it is attached to
+ * (`.value` -> `value`, `.checked` -> `checked`) and the appropriate writeback
+ * event for the element (`input` for text-like inputs/textarea; `change` for
+ * checkbox/radio/range inputs and `<select>`).
+ *
+ * @param component  The component instance owning the state field (usually `this`).
+ * @param fieldName  The state field name to read from / write back to. Supports
+ *                   dot-paths into nested state (e.g. `'address.street'`), so a
+ *                   `@Store` field can be bound at any depth.
+ */
+export declare const bind: (component: unknown, fieldName: string) => BindResult;
+/**
+ * Read a (possibly dotted) field path off a component, walking the object graph
+ * via property access (so `@Store` reactive proxies traverse correctly).
+ * Single-segment paths take the fast path; `null`/`undefined` short-circuits.
+ *
+ * @internal — used by the bind directive; lives here so the renderer stays
+ * dependency-free (it mirrors `resolveStatePath` in @cossackframework/core).
+ */
+export declare function resolveField(component: unknown, path: string): unknown;
+/**
+ * Write a value into a (possibly dotted) field path. Resolves to the parent via
+ * property access (so the `@Store` Proxy trap fires on the final segment) and
+ * creates intermediate objects when a segment is missing.
+ *
+ * @internal — counterpart to {@link resolveField} for the bind writeback.
+ */
+export declare function setField(component: unknown, path: string, value: unknown): void;
+/**
+ * Wraps an event handler so the event's default is prevented before it runs.
+ *
+ * Browser-native (HTML5 constraint) validation is ALSO disabled by default —
+ * the bound <form> gets `novalidate` — because Cossack encourages custom
+ * `@Validate` validation. Pass `{ novalidate: false }` to restore native
+ * validation.
+ *
+ * Usage:
+ *   <form @submit="${preventDefault(this.serverHandle)}"></form>
+ *   <!-- keep native validation -->
+ *   <form @submit="${preventDefault(this.serverHandle, { novalidate: false })}"></form>
+ *
+ * @param handler  The event handler to invoke after preventing default.
+ * @param options  Optional. `novalidate` (default `true`) toggles `novalidate`.
+ */
+export declare const preventDefault: (handler: EventListener, options?: {
+    novalidate?: boolean;
+}) => PreventDefaultResult;
+/**
+ * Only omit an attribute when the value is `undefined`; render every other
+ * value (including `null`, `false`, `0`, `''`) as a normal attribute. This is
+ * the Lit-faithful `ifDefined` directive.
+ *
+ * By default a plain Cossack attribute binding `href="${url}"` already omits the
+ * attribute for `null`/`undefined`/`false`, and renders everything else. The
+ * difference `ifDefined` makes is two-fold:
+ *
+ *  1. Only `undefined` drops the attribute — `null` is rendered as `"null"`,
+ *     `false` as `"false"` (useful for data attributes where you want the
+ *     literal string rather than an omission).
+ *  2. When the value transitions from defined back to `undefined` on a
+ *     re-render, the attribute is explicitly removed.
+ *
+ * Usage:
+ *   html`<a href="${ifDefined(url)}">link</a>`
+ *   html`<div data-flag="${ifDefined(maybeUndefined)}">...</div>`
+ *
+ * @param value  The value to render, or `undefined` to omit the attribute.
+ */
+export declare const ifDefined: (value: unknown) => IfDefinedResult;
+/**
+ * Defers re-evaluating a template until its dependencies change. `guard` caches
+ * the value produced by `factory()` and reuses it on subsequent renders as long
+ * as `deps` is shallow-equal to the previous render; `factory` only runs again
+ * when a dependency changes.
+ *
+ * This is an optimization for expensive rendering (large lists, heavy
+ * computations): wrap the costly part so it is not recomputed on every render,
+ * only when the inputs it actually depends on change.
+ *
+ * Usage (single dependency):
+ *   html`<ul>${guard(items, () => html`...expensive...`)}</ul>`
+ * Usage (multiple dependencies — pass an array):
+ *   html`${guard([query, page], () => renderResults(query, page))}`
+ *
+ * The dependency comparison is shallow: for a single value it uses `===`; for
+ * an array each element is compared with `===` and lengths must match.
+ *
+ * @param deps     A comparable value or an array of values.
+ * @param factory  Called (with no args) to produce the value when deps change.
+ */
+export declare const guard: (deps: unknown, factory: () => unknown) => GuardResult;
+/**
+ * Caches and reuses previously-rendered template subtrees instead of destroying
+ * them when the rendered value switches to a different template. When you
+ * toggle between two (or more) templates behind `cache`, switching back to one
+ * that was rendered before reattaches its existing DOM and part tree rather
+ * than rebuilding it — so component state, scroll positions, focus, and DOM
+ * identity are preserved across the swap.
+ *
+ * Without `cache`, a conditional like `cond ? html\`<A/>\` : html\`<B/>\``
+ * rebuilds the previously-shown branch every time you switch back, losing that
+ * branch's state. With `cache`, each branch is kept alive while it is not
+ * displayed.
+ *
+ * Usage:
+ *   html`${cache(showA ? html`<A-component></A-component>` : html`<B-component></B-component>`)}`
+ *
+ * The cache key is the template's `strings` (the literal parts of the tagged
+ * template), so distinct `html\`...\`` sites are cached separately. Non-template
+ * values are passed through unchanged (no caching benefit, no harm).
+ *
+ * @param value  A `TemplateResult` (or any node value) to cache by template.
+ */
+export declare const cache: (value: unknown) => CacheResult;
+/**
+ * Renders one of two templates based on a condition. `when` is a pure function
+ * that picks a branch and returns its result — it has no engine coupling, the
+ * chosen value flows through the renderer like any other node value.
+ *
+ * Usage:
+ *   html`${when(isOn, () => html`<p>On</p>`, () => html`<p>Off</p>`)}`
+ *
+ * The case functions receive the condition so they can use it without a second
+ * binding. If the false case is omitted, `undefined` is returned (renders nothing).
+ *
+ * @param condition  Truthy/falsy value selecting the branch.
+ * @param trueCase   Called with `condition` when it is truthy.
+ * @param falseCase  Optional. Called with `condition` when it is falsy.
+ */
+export declare const when: (condition: unknown, trueCase: (c: unknown) => unknown, falseCase?: (c: unknown) => unknown) => unknown;
+/**
+ * Selects a template by matching a value against an ordered list of cases,
+ * like a `switch`. The first case whose lookup `===` the value wins; otherwise
+ * the optional default case is used (or nothing is rendered).
+ *
+ * Usage:
+ *   html`${choose(status, [
+ *     ['idle', () => html`<i>Idle</i>`],
+ *     ['loading', () => html`<b>Loading…</b>`],
+ *   ], () => html`<span>Unknown</span>`)}`
+ *
+ * Each case function receives the matched value and its case index.
+ *
+ * @param value        The value to match.
+ * @param cases        Ordered `[lookup, fn]` pairs. First `lookup === value` wins.
+ * @param defaultCase  Optional fallback called when no case matches.
+ */
+export declare const choose: <T>(value: T, cases: Array<[T, (v: T, i: number) => unknown]>, defaultCase?: () => unknown) => unknown;
+/**
+ * Maps an iterable to renderable values (e.g. templates) and returns the array.
+ * It is a thin helper over `Array.from` so that plain objects/iterables can be
+ * rendered as a list without manually spreading into an array first. The
+ * renderer already handles arrays, so this needs no engine integration.
+ *
+ * Usage:
+ *   html`<ul>${map(items, (item) => html`<li>${item.name}</li>`)}</ul>`
+ *
+ * @param iterable   Anything `Array.from` accepts.
+ * @param identityFn Maps each item to a renderable value, receiving `(item, index)`.
+ */
+export declare const map: <T>(iterable: Iterable<T> | ArrayLike<T>, identityFn: (item: T, index: number) => unknown) => unknown[];
+/**
+ * Joins renderable values with a separator interleaved between each pair — the
+ * list equivalent of `Array.prototype.join`, but with values rather than
+ * strings so the separator can itself be a template (e.g. a `<li>` divider).
+ *
+ * Usage (string separator):
+ *   html`${join(names, (n) => n, ', ')}`  // "a, b, c"
+ * Usage (separator template):
+ *   html`<ul>${join(items, (i) => html`<li>${i}</li>`, () => html`<li class="sep">•</li>`)}</ul>`
+ *
+ * @param iterable Anything `Array.from` accepts.
+ * @param valueFn  Maps each item to a renderable value.
+ * @param joiner   Either a static renderable value or `(index) => value`. The
+ *                 index is the position of the item BEFORE the separator.
+ */
+export declare const join: <T>(iterable: Iterable<T> | ArrayLike<T>, valueFn: (item: T, index: number) => unknown, joiner: unknown | ((index: number) => unknown)) => unknown[];
+/**
+ * Generates an increasing (or decreasing) sequence of numbers as an array,
+ * suitable for rendering a fixed number of items. Overloads:
+ *   range(end)               -> [0, 1, …, end-1]     (half-open, step +1)
+ *   range(start, end)        -> [start, …, end-1]    (step +1)
+ *   range(start, end, step)  -> [start, start+step, …]  (stops before `end`)
+ *
+ * Usage:
+ *   html`<ul>${range(0, 5).map((n) => html`<li>${n}</li>`)}</ul>`
+ *
+ * A negative `step` walks downward (e.g. `range(5, 0, -1)` → `[5,4,3,2,1]`).
+ */
+export declare const range: (startOrEnd: number, end?: number, step?: number) => number[];
 export type RefCallback = (el: Element | undefined) => void;

package/dist/index.js

@@ -1,10 +1,10 @@
-import { C as e, S as t, _ as n, a as r, b as i, c as a, d as o, f as s, g as c, h as l, i as u, l as d, m as f, n as p, o as m, p as h, r as g, s as _, t as v, u as y, v as b, x, y as S } from "./cossack-html-QsGiJk7a.js";
+import { A as e, B as t, C as n, D as r, E as i, F as a, I as o, L as s, M as c, N as l, O as u, P as d, R as f, S as p, T as m, V as h, _ as g, a as _, b as v, c as y, d as b, f as x, g as S, h as C, i as w, j as T, k as E, l as D, m as O, n as k, o as A, p as j, r as M, s as N, t as P, u as F, v as I, w as L, x as R, y as z, z as B } from "./cossack-html-D6DeVgtW.js";
 //#region src/context.ts
-function C(e) {
+function V(e) {
 	return {
 		id: Math.random().toString(36).slice(2),
 		defaultValue: e
 	};
 }
 //#endregion
-export { S as CossackElement, o as KeyResult, s as LiveResult, h as RepeatResult, v as TemplateResult, p as UnsafeHTMLResult, f as classMap, g as component, C as createContext, u as escapeHtml, r as html, i as instanceStack, e as isComponentResult, m as isTemplateResult, _ as isUnsafeHTML, l as key, c as live, x as popCurrentInstance, t as pushCurrentInstance, a as render, d as renderToString, n as repeat, b as styleMap, y as unsafeHTML };
+export { x as BindResult, j as CacheResult, s as CossackElement, O as GuardResult, C as IfDefinedResult, S as KeyResult, g as LiveResult, I as PreventDefaultResult, z as RepeatResult, P as TemplateResult, k as UnsafeHTMLResult, v as bind, R as cache, p as choose, n as classMap, M as component, V as createContext, w as escapeHtml, L as guard, _ as html, A as hydrate, m as ifDefined, f as instanceStack, h as isComponentResult, N as isTemplateResult, y as isUnsafeHTML, i as join, r as key, u as live, E as map, B as popCurrentInstance, e as preventDefault, t as pushCurrentInstance, T as range, D as render, F as renderToString, c as repeat, l as resolveField, d as setField, a as styleMap, b as unsafeHTML, o as when };

package/dist/server.js

@@ -1,4 +1,4 @@
-import { i as e, l as t } from "./cossack-html-QsGiJk7a.js";
+import { i as e, u as t } from "./cossack-html-D6DeVgtW.js";
 //#region src/minify-html.ts
 var n = /<(script|style|pre|textarea)\b[^>]*>[\s\S]*?<\/\1>/gi, r = RegExp(`<(${[.../* @__PURE__ */ new Set([
 	"area",
@@ -30,7 +30,7 @@ function s(e, t) {
 	return e.replace(/\x00PRESERVE_(\d+)\x00/g, (e, n) => t[parseInt(n, 10)]);
 }
 function c(e) {
-	let { html: t, blocks: n } = o(e), c = t.replace(/<!--(?!\[if\s)[\s\S]*?-->/g, "");
+	let { html: t, blocks: n } = o(e), c = t.replace(/<!--(?!\[if\s|\/?CRP|CSA-[SE])[\s\S]*?-->/g, "");
 	return c = c.replace(i, ""), c = c.replace(/\s+/g, " "), c = c.replace(/>\s+</g, "><"), c = c.replace(a, (e, t, n) => `${t}=${n}`), c = c.replace(r, (e, t, n) => `<${t}${n ? n.trimEnd() : ""}>`), c = s(c, n), c = c.replace(/>\s+</g, "><"), c = c.trim(), c;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cossackframework/renderer",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "Light DOM rendering engine for the Cossack Framework",
   "license": "MIT",
@@ -10,6 +10,7 @@
     "directory": "packages/renderer"
   },
   "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist"
@@ -29,13 +30,12 @@
   },
   "devDependencies": {
     "oxlint": "^1.41.0",
-    "vite": "^8.1.0",
-    "vite-plugin-dts": "^3.9.1",
-    "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^4.1.9"
+    "typescript": "^7.0.2",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && tsc -p tsconfig.declarations.json",
     "test": "vitest",
     "lint": "oxlint"
   }

package/dist/children.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/component-dispose.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/context.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/controller.test.d.ts

@@ -1 +0,0 @@
-export {};