@nisli/core 0.54.1 → 0.56.0

package/dist/template-audit.js

@@ -0,0 +1,246 @@
+/**
+ * template-audit.ts — First-parse static template audit (ADR 0030.2 T4).
+ *
+ * Attached to the parse-once cache in template.ts: runs ONCE per `html`
+ * callsite (keyed by TemplateStringsArray identity) at the first parse, and
+ * walks the parsed-but-never-mounted template element checking its STATIC
+ * parts. The silent-static-typo class — the no-build equivalent of a compile
+ * error — dies in the engine, amortized free.
+ *
+ * Checks (per ADR 0030.2 §2 T4 as amended by §8 "T4 (template)"):
+ * - N101 — a dash-tag with no customElements definition. Races
+ *   `customElements.whenDefined` against a microtask + macrotask grace so
+ *   ordinary lazy definition (module import order) never warns.
+ * - N102 — an `@event` name that is neither a known native event nor an
+ *   allowlisted component-dispatched event (`ui-*`, `nisli-*`).
+ * - N103 — an unknown `@event.modifier`.
+ * - N104 — an attribute on a component tag that declares attributes
+ *   (non-empty `static observedAttributes`) which is neither declared nor a
+ *   global HTML attribute. Components WITHOUT declared attributes get NO
+ *   attribute audit: pre-schema (T3) there is no truth source — auto-resolved
+ *   props are deliberately not attributes (§8).
+ *
+ * Suppression escape (designed for lazy islands, §8): a comment directive as
+ * the template's FIRST node (leading whitespace allowed):
+ *
+ *   html`<!-- nisli-audit off --><my-island>…</my-island>`
+ *     — disables the whole audit for this template.
+ *
+ *   html`<!-- nisli-audit allow-undefined: my-island other-tag --><…>`
+ *     — suppresses only N101 for the named tags (other checks stay live).
+ *
+ * The directive comment is static content: it survives into the mounted DOM
+ * (and SSG output) as an inert HTML comment. Documented, accepted for the
+ * prototype; the design gate may choose to strip it at parse.
+ *
+ * Dev gating: core has no build-time dev/prod define today — that mechanism
+ * is a named Wave-1 deliverable (§8). Until it exists this module is gated on
+ * the `devMode` flag below ONLY. SSG/happy-dom detection is deliberately NOT
+ * attempted (unreliable); an SSG build that wants silence must call
+ * `setTemplateAuditEnabled(false)` before rendering.
+ */
+// Reporting goes through the diagnostics leaf. The audit keeps its own
+// enable override (tests, SSG environments) and otherwise follows the
+// leaf's dev gate — under NODE_ENV=production builds it is silent.
+import { diag as emitDiag, isDev } from './diagnostics.js';
+let enabledOverride = null;
+/**
+ * Enable/disable the first-parse audit (and its callsite capture);
+ * `null` restores the dev-gate default.
+ */
+export function setTemplateAuditEnabled(enabled) {
+    enabledOverride = enabled;
+}
+/** Current audit gate state (exposed for template.ts and tests). */
+export function isTemplateAuditEnabled() {
+    return enabledOverride ?? isDev();
+}
+/** Emit a coded audit diagnostic through the diagnostics leaf (audit-gated). */
+export function diag(code, message, detail) {
+    if (!isTemplateAuditEnabled())
+        return;
+    emitDiag(code, message, detail === undefined ? undefined : { detail });
+}
+// ── Callsite capture ────────────────────────────────────────────────
+/** First-seen authoring callsite per template identity (dev only). */
+const callsites = new WeakMap();
+/**
+ * Remember the authoring callsite of an `html` template the first time its
+ * strings identity is seen. Must be called from `html()` itself — by the
+ * time the first parse happens (first mount), the authoring frame is gone
+ * from the stack. No-op when the audit is disabled or already captured.
+ */
+export function captureCallsite(strings) {
+    if (!isTemplateAuditEnabled() || callsites.has(strings))
+        return;
+    const stack = new Error().stack ?? '';
+    const frame = stack
+        .split('\n')
+        .slice(1)
+        .find(line => line.includes('at ') && !/template(-audit)?\.(ts|js|mjs|cjs)/.test(line));
+    callsites.set(strings, frame ? frame.trim() : '(unknown callsite)');
+}
+// ── Audit ───────────────────────────────────────────────────────────
+const audited = new WeakSet();
+/** Modifiers understood by bindEvent (template.ts). */
+const KNOWN_MODIFIERS = new Set(['stop', 'prevent', 'once', 'enter', 'escape', 'space', 'tab']);
+/** Component-dispatched event prefixes exempt from the native-event check (§8). */
+const COMPONENT_EVENT_PREFIXES = ['ui-', 'nisli-'];
+/** Real native events with no `on*` IDL attribute (the `in`-check misses them). */
+const NATIVE_EVENTS_WITHOUT_IDL = new Set(['focusin', 'focusout']);
+/**
+ * Global HTML attributes legal on ANY component tag. Mirrors (and must stay a
+ * superset of) template.ts's auto-resolution exclusion list — these reach the
+ * element as plain attributes, never `_setProp`.
+ */
+const GLOBAL_ATTRS = new Set([
+    'id', 'class', 'style', 'slot', 'title', 'role', 'tabindex', 'name',
+    'part', 'hidden', 'dir', 'lang', 'is',
+]);
+/** Parse the leading `<!-- nisli-audit … -->` directive comment, if any. */
+function parseDirectives(content) {
+    const directives = { off: false, allowUndefined: new Set() };
+    for (const node of content.childNodes) {
+        if (node.nodeType === Node.TEXT_NODE) {
+            if ((node.textContent ?? '').trim() === '')
+                continue; // leading whitespace
+            break;
+        }
+        if (node.nodeType === Node.COMMENT_NODE) {
+            const body = (node.textContent ?? '').trim();
+            if (!body.startsWith('nisli-audit'))
+                break;
+            const rest = body.slice('nisli-audit'.length).trim();
+            if (rest === 'off') {
+                directives.off = true;
+            }
+            else if (rest.startsWith('allow-undefined')) {
+                const tags = rest
+                    .slice('allow-undefined'.length)
+                    .replace(/^[:\s]+/, '')
+                    .split(/[\s,]+/)
+                    .filter(Boolean);
+                for (const tag of tags)
+                    directives.allowUndefined.add(tag.toLowerCase());
+            }
+        }
+        break; // only the FIRST non-whitespace node may carry the directive
+    }
+    return directives;
+}
+/**
+ * N101 — dash-tag with no definition. Rather than warning synchronously (the
+ * defining module may simply import later in the same task), race
+ * `customElements.whenDefined(tag)` against a microtask + macrotask grace;
+ * warn only if the tag is still undefined after the grace elapses.
+ */
+function checkDashTag(tag, site) {
+    let registry;
+    try {
+        registry = customElements;
+    }
+    catch {
+        return; // no registry in this environment — nothing to check
+    }
+    if (!registry || registry.get(tag))
+        return;
+    let defined = false;
+    try {
+        registry.whenDefined(tag).then(() => { defined = true; }, () => { });
+    }
+    catch {
+        diag('N101', `<${tag}> is not a valid custom element name — at ${site}`);
+        return;
+    }
+    // Grace: one microtask hop (whenDefined settlements for definitions made
+    // earlier in this task) + one macrotask hop (definitions made later in the
+    // same task, e.g. module evaluation order). Under fake timers the macrotask
+    // may never fire — the warning is simply skipped, never wrong.
+    queueMicrotask(() => {
+        if (defined)
+            return;
+        setTimeout(() => {
+            try {
+                if (!isTemplateAuditEnabled() || defined || registry.get(tag))
+                    return;
+                diag('N101', `<${tag}> is used in a template but never defined (customElements.get returned ` +
+                    `undefined after grace) — at ${site}. If this tag is a lazily-loaded island, ` +
+                    `suppress with a leading <!-- nisli-audit allow-undefined: ${tag} --> comment.`);
+            }
+            catch { /* environment torn down during grace — nothing to report */ }
+        }, 0);
+    });
+}
+/** N102/N103 — event-name and modifier checks for one `@event.mods` attribute. */
+function checkEvent(el, attrName, site) {
+    const parts = attrName.slice(1).split('.');
+    const eventName = parts[0] ?? '';
+    const modifiers = parts.slice(1);
+    const isNative = `on${eventName}` in el || NATIVE_EVENTS_WITHOUT_IDL.has(eventName);
+    const isComponentEvent = COMPONENT_EVENT_PREFIXES.some(p => eventName.startsWith(p));
+    if (eventName && !isNative && !isComponentEvent) {
+        diag('N102', `@${eventName} on <${el.tagName.toLowerCase()}> is not a known native event ` +
+            `(and not an allowlisted ${COMPONENT_EVENT_PREFIXES.join('/')} component event) — at ${site}`);
+    }
+    for (const mod of modifiers) {
+        if (!KNOWN_MODIFIERS.has(mod)) {
+            diag('N103', `unknown event modifier ".${mod}" in "${attrName}" — known: ` +
+                `${[...KNOWN_MODIFIERS].join(', ')} — at ${site}`);
+        }
+    }
+}
+/** N104 — undeclared attribute on a component that DECLARES attributes. */
+function checkComponentAttr(tag, name, observed, site) {
+    if (name.startsWith('data-') || name.startsWith('aria-'))
+        return;
+    if (GLOBAL_ATTRS.has(name) || observed.includes(name))
+        return;
+    diag('N104', `<${tag}> declares attributes [${observed.join(', ')}] but the template sets ` +
+        `unknown "${name}" — at ${site}. Undeclared names route through _setProp and are ` +
+        `silently dead as attributes.`);
+}
+/**
+ * Run the one-time static audit over a freshly parsed template. Called by
+ * template.ts's parse-once cache on cache miss; idempotent per template
+ * identity, no-op when the audit is disabled. Read-only over the cached
+ * template element — mounting state is never touched.
+ */
+export function auditTemplate(strings, template) {
+    if (!isTemplateAuditEnabled() || audited.has(strings))
+        return;
+    audited.add(strings);
+    const site = callsites.get(strings) ?? '(unknown callsite)';
+    const content = template.content;
+    const directives = parseDirectives(content);
+    if (directives.off)
+        return;
+    for (const el of content.querySelectorAll('*')) {
+        const tag = el.tagName.toLowerCase();
+        const isDashTag = tag.includes('-');
+        if (isDashTag && !directives.allowUndefined.has(tag)) {
+            checkDashTag(tag, site);
+        }
+        // Attribute audit ONLY for components with declared attrs (§8): a
+        // non-empty static observedAttributes is the single pre-T3 truth source.
+        let observed;
+        if (isDashTag) {
+            const ctor = customElements.get(tag);
+            const list = ctor?.observedAttributes;
+            if (Array.isArray(list) && list.length > 0)
+                observed = list;
+        }
+        for (const attr of [...el.attributes]) {
+            const name = attr.name;
+            if (name.startsWith('@')) {
+                checkEvent(el, name, site);
+                continue;
+            }
+            // Directive positions with their own semantics — never attributes.
+            if (name.startsWith('class:') || name === 'ref' || name === 'html:inner')
+                continue;
+            if (observed)
+                checkComponentAttr(tag, name, observed, site);
+        }
+    }
+}
+//# sourceMappingURL=template-audit.js.map

package/dist/template-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-audit.js","sourceRoot":"","sources":["../src/template-audit.ts"],"names":[],"mappings":"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"}

package/dist/template.d.ts

@@ -21,6 +21,59 @@ export interface TemplateResult {
 }
 /** A DOM event handler whose event type is inferred from its native event name. */
 export type TypedEventHandler<K extends keyof HTMLElementEventMap> = (event: HTMLElementEventMap[K]) => void;
+/**
+ * Branded trusted-HTML value accepted by `html:inner` (and by @nisli/ssg's
+ * static renderer, which re-exports this brand — core owns it, ADR 0030.2 §8).
+ * Structural, not nominal: cross-package/cross-realm values with the same
+ * shape stay valid.
+ */
+export interface RawHtml {
+    value: string;
+    __raw: true;
+}
+/**
+ * Mark a string as trusted raw HTML. `html:inner` accepts ONLY branded
+ * values — a bare string throws N106 (the accidental-XSS-sink class closes,
+ * ADR 0030.2 §3). NEVER wrap user-generated input.
+ */
+export declare function raw(value: string): RawHtml;
+/**
+ * Branded UNTRUSTED-HTML value accepted by `html:inner`. The mirror image of
+ * {@link RawHtml}: where `raw()` is the author asserting markup is already
+ * trustworthy, this brand asserts the opposite — the string is untrusted and
+ * MUST pass a sanitizer before it reaches the DOM (ADR 0019:124–128, executed
+ * by bet-09(c)). Structural, not nominal, on the same rule as RawHtml.
+ */
+export interface SanitizedHtml {
+    value: string;
+    __sanitize: true;
+}
+/**
+ * Mark a string as untrusted markup to be sanitized at the sink — the brand
+ * for user-generated HTML, which must NEVER go through `raw()`.
+ *
+ * `html:inner` writes it with the platform's `Element.setHTML()` (the spec's
+ * XSS-safe default sanitizer) when the engine has one, otherwise with the hook
+ * registered by {@link setSanitizerFallback}. With NEITHER available the
+ * binding throws N107: it never falls back to `innerHTML`. nisli bundles no
+ * sanitizer — the trust decision, and its bytes, stay in the app.
+ */
+export declare function sanitized(value: string): SanitizedHtml;
+/** A sanitizing writer: sanitize `html`, then put the result inside `el`. */
+export type SanitizerFallback = (el: Element, html: string) => void;
+/**
+ * Register the sanitizing writer used for `sanitized()` values on engines
+ * WITHOUT native `Element.setHTML()` (Safari today, older Chromium/Firefox),
+ * or `null` to unregister. Native `setHTML()` always wins where it exists, so
+ * modern engines never pay the hook. nisli ships no sanitizer; wire one:
+ *
+ *   setSanitizerFallback((el, html) => {
+ *     el.innerHTML = DOMPurify.sanitize(html);
+ *   });
+ */
+export declare function setSanitizerFallback(fn: SanitizerFallback | null): void;
+/** @internal Test-only: number of actual `<template>` parses performed. */
+export declare function __templateParseCount(): number;
 /**
  * Tagged template literal for creating reactive DOM templates.
  *
@@ -34,22 +87,26 @@ export type TypedEventHandler<K extends keyof HTMLElementEventMap> = (event: HTM
  * the specific text node or attribute updates — no diffing needed.
  */
 export declare function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
+export declare function each<T>(items: ReadonlySignal<T[]>, keyFn: (item: T, index: number) => string | number, templateFn: (item: ReadonlySignal<T>, index: ReadonlySignal<number>) => TemplateResult | {
+    __type: 'factory';
+}): TemplateResult;
 /**
- * Reactive list rendering with keyed reconciliation.
+ * Conditional rendering helper (ADR 0030.2 §3, boolean-gated with `else`).
  *
- * Renders a list of items from a signal, tracking each item by key.
- * When the array changes, only affected DOM nodes are added, removed,
- * or reordered — existing items update in-place via their signals.
+ * Shows `template` when the condition is truthy, `elseTemplate` (optional)
+ * when falsy. Both arms accept a TemplateResult or a lazy callback
+ * `() => TemplateResult`; callbacks are only evaluated for the active arm.
  *
- * ```ts
- * const tasks = signal([{ id: '1', title: 'A' }, { id: '2', title: 'B' }]);
- * html`<ul>${each(tasks, t => t.id, (task, index) =>
- *   html`<li>${computed(() => task.value.title)}</li>`
- * )}</ul>`
- * ```
+ * Semantics for signal conditions:
+ * - The gate is `!!condition.value` — a truthy→truthy (or falsy→falsy)
+ *   transition returns the memoized previous result, so the live branch is
+ *   NEVER rebuilt (no state/scroll/focus loss) and callbacks never re-run.
+ * - Branch callbacks evaluate UNTRACKED: a signal read during branch
+ *   construction does not subscribe the when() computed, so it cannot
+ *   trigger a rebuild. Reactive parts inside a branch must be interpolated
+ *   as signals/computeds (values), not read raw at construction time.
  */
-export declare function each<T>(items: ReadonlySignal<T[]>, keyFn: (item: T, index: number) => string | number, templateFn: (item: ReadonlySignal<T>, index: ReadonlySignal<number>) => TemplateResult): TemplateResult;
-export declare function when(condition: unknown, template: TemplateResult | (() => TemplateResult)): TemplateResult | ReadonlySignal<TemplateResult | null> | null;
+export declare function when(condition: unknown, template: TemplateResult | (() => TemplateResult), elseTemplate?: TemplateResult | (() => TemplateResult)): TemplateResult | ReadonlySignal<TemplateResult | null> | null;
 /** A value bindable to an `el()` attribute — static or reactive. */
 type ElAttrValue = string | number | boolean | null | undefined | ReadonlySignal<unknown>;
 export interface ElProps {