@jasonshimmy/custom-elements-runtime 2.8.2 → 3.1.0

package/dist/runtime/component/factory.d.ts

@@ -1,4 +1,4 @@
-import type { VNode } from '../types';
+import type { HydrateStrategy, VNode } from '../types';
 /**
  * Streamlined functional component API with automatic reactive props and lifecycle hooks.
  *
@@ -36,4 +36,18 @@ import type { VNode } from '../types';
  * });
  * ```
  */
-export declare function component(tag: string, renderFn: () => VNode | VNode[] | Promise<VNode | VNode[]>): void;
+/** Options for `component()`. */
+export interface ComponentOptions {
+    /**
+     * Partial-hydration strategy when this component is server-rendered with
+     * Declarative Shadow DOM (`dsd: true`). Emitted as `data-cer-hydrate` on the
+     * host element so the client runtime can schedule hydration appropriately.
+     *
+     * - `'load'`    — hydrate immediately on connection (default)
+     * - `'idle'`    — defer to `requestIdleCallback`
+     * - `'visible'` — defer until the element enters the viewport
+     * - `'none'`    — never hydrate (purely static, no JS runtime for this element)
+     */
+    hydrate?: HydrateStrategy;
+}
+export declare function component(tag: string, renderFn: () => VNode | VNode[] | Promise<VNode | VNode[]>, options?: ComponentOptions): void;

package/dist/runtime/css-utils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure CSS utility functions — no JIT dependencies, no module-level side effects.
+ *
+ * Extracted so that render.ts and hooks.ts can import lightweight CSS helpers
+ * without pulling the entire JIT CSS engine into every consumer's bundle.
+ */
+/**
+ * CSS template literal tag
+ */
+export declare function css(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * CSS minification utility (basic)
+ */
+export declare function minifyCSS(input: string): string;
+/**
+ * Sanitize CSS to prevent injection attacks (XSS, javascript: URLs, expression(), etc.)
+ */
+export declare function sanitizeCSS(input: string): string;
+/**
+ * Polyfill for CSS.escape() for SSR environments.
+ * Based on https://drafts.csswg.org/cssom/#serialize-an-identifier
+ */
+export declare function cssEscape(value: string): string;
+/** Escape a class name and prefix it with a dot for use in CSS selectors. */
+export declare function escapeClassName(name: string): string;
+/** Escape a string for use in a RegExp. */
+export declare function escapeRegExp(str: string): string;
+export declare const baseReset: string;
+/** Default spacing unit used by the JIT spacing scale. */
+export declare const spacing = "0.25rem";
+export declare function getBaseResetSheet(): CSSStyleSheet;
+/** Reset the base reset sheet singleton (for HMR). @internal */
+export declare function _resetBaseResetSheet(): void;

package/dist/runtime/discovery-state.d.ts

@@ -19,6 +19,9 @@ export declare function isDiscoveryRender(): boolean;
  * Mark the start of a discovery render pass.
  * Call this immediately before invoking the render function for the first time
  * (before `useProps` prop-name collection).
+ *
+ * Emits a dev warning when called while a discovery render is already active
+ * so that nested or mismatched begin/end pairs are surfaced during development.
  * @internal
  */
 export declare function beginDiscoveryRender(): void;

package/dist/runtime/hooks.d.ts

@@ -2,6 +2,8 @@
  * Context-based hooks for functional components
  * Provides React-like hooks with perfect TypeScript inference
  */
+import type { JITCSSOptions } from './style';
+export type { JITCSSOptions };
 export { beginDiscoveryRender, endDiscoveryRender } from './discovery-state';
 /**
  * Returns true while a discovery render is in progress.
@@ -150,6 +152,82 @@ export declare function useProps<T extends Record<string, unknown>>(defaults: T)
  * ```
  */
 export declare function useStyle(callback: () => string): void;
+/**
+ * Inject CSS into `document.adoptedStyleSheets`, escaping the Shadow DOM
+ * boundary. Suitable for `@font-face` declarations, `:root` variable overrides,
+ * and global scroll/scroll-bar styling. Deduplicated by CSS content so calling
+ * this in multiple component instances is safe.
+ *
+ * **Use sparingly** — this intentionally breaks Shadow DOM encapsulation.
+ * A dev-mode warning is emitted to make the escape hatch visible.
+ *
+ * @example
+ * ```ts
+ * component('app-root', () => {
+ *   useGlobalStyle(() => css`
+ *     @font-face {
+ *       font-family: 'Inter';
+ *       src: url('/fonts/inter.woff2') format('woff2');
+ *     }
+ *     :root {
+ *       --app-font: 'Inter', sans-serif;
+ *     }
+ *   `);
+ *   return html`<slot></slot>`;
+ * });
+ * ```
+ */
+export declare function useGlobalStyle(styleFactory: () => string): void;
+/**
+ * Design token definitions accepted by `useDesignTokens()`.
+ * Map high-level token names to CSS custom property overrides.
+ */
+export interface DesignTokens {
+    /** Override the primary color scale root (sets --cer-color-primary-500) */
+    primary?: string;
+    /** Override the secondary color scale root */
+    secondary?: string;
+    /** Override the neutral color scale root */
+    neutral?: string;
+    /** Override the success color root */
+    success?: string;
+    /** Override the info color root */
+    info?: string;
+    /** Override the warning color root */
+    warning?: string;
+    /** Override the error color root */
+    error?: string;
+    /** Override the sans-serif font family */
+    fontSans?: string;
+    /** Override the serif font family */
+    fontSerif?: string;
+    /** Override the monospace font family */
+    fontMono?: string;
+    /** Additional arbitrary CSS custom property overrides */
+    [key: string]: string | undefined;
+}
+/**
+ * Apply design tokens to `:host` as CSS custom property overrides.
+ * Must be called during component render. This is a typed, validated
+ * alternative to writing `useStyle(() => css\`:host { ... }\`)` by hand.
+ *
+ * Semantic color tokens (e.g. `primary: '#6366f1'`) set the `*-500` shade
+ * for that scale. Use arbitrary `'--cer-color-primary-500'` keys to override
+ * individual shades.
+ *
+ * @example
+ * ```ts
+ * component('app-root', () => {
+ *   useDesignTokens({
+ *     primary: '#6366f1',
+ *     fontSans: '"Inter", sans-serif',
+ *     '--cer-color-neutral-900': '#0a0a0a',
+ *   });
+ *   return html`<slot></slot>`;
+ * });
+ * ```
+ */
+export declare function useDesignTokens(tokens: DesignTokens): void;
 /**
  * Store a value under a key so that descendant components can retrieve it
  * with `inject()`. Must be called during component render.

package/dist/runtime/hydration.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Client-side hydration helpers.
+ *
+ * When the server renders with `dsd: true`, each custom element's shadow DOM
+ * is already present in the HTML via a Declarative Shadow DOM template. The
+ * browser parses that template and attaches the shadow root before any
+ * JavaScript runs. When the JS bundle loads, the custom element constructors
+ * detect the existing shadow root and skip the `attachShadow()` call, then
+ * hydrate (attach reactivity to) the existing DOM on `connectedCallback`.
+ *
+ * `hydrateApp` is a signal/entry point for this process. In most cases custom
+ * elements self-hydrate automatically on connection — this function is useful
+ * when you need to explicitly trigger or defer the hydration of a subtree.
+ */
+/**
+ * Trigger hydration for all registered custom elements within `root`.
+ *
+ * In practice, custom elements self-hydrate as soon as their class definition
+ * is registered and the element is connected to the DOM. Call `hydrateApp`
+ * after importing and calling `component()` for all your components to signal
+ * that the page is ready for reactive activation.
+ *
+ * @param root - The root element to hydrate. Defaults to `document`.
+ *
+ * @example
+ * ```ts
+ * import { component, hydrateApp } from '@jasonshimmy/custom-elements-runtime';
+ * import './components'; // registers all components via component()
+ *
+ * hydrateApp(); // activate all DSD-rendered components on the page
+ * ```
+ */
+export declare function hydrateApp(root?: Element | Document): void;

package/dist/runtime/jit-hooks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * JIT CSS hooks — lives in a separate module so that hooks.ts does not
+ * statically import style.ts. Consumers who never call `useJITCSS` will
+ * have the entire JIT engine tree-shaken out of their bundle.
+ */
+import { type JITCSSOptions } from './style';
+/**
+ * Configure the JIT CSS engine for the current session.
+ * This is a convenience wrapper around `enableJITCSS()` that can be called
+ * inside a component render function or at module initialisation time.
+ *
+ * @example
+ * ```ts
+ * component('my-component', () => {
+ *   // Enable extended Tailwind colors so bg-blue-500, text-violet-700, etc. generate CSS
+ *   useJITCSS({ extendedColors: true });
+ *   return html`<div class="bg-blue-500 text-white">Hello</div>`;
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // At app entry – enable once for all components
+ * useJITCSS({ extendedColors: true, customColors: { brand: { '500': '#e63946' } } });
+ * ```
+ */
+export declare function useJITCSS(options?: JITCSSOptions): void;
+export type { JITCSSOptions };

package/dist/runtime/render-bridge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Lazy render bridge — populated by style.ts when the JIT engine is imported.
+ *
+ * render.ts always imports this module (so it is always bundled), but
+ * style.ts (the full JIT engine, ~24 KB gzip) is only bundled when the
+ * consumer explicitly imports JIT CSS symbols such as `enableJITCSS` or
+ * `useJITCSS`. When style.ts IS imported it registers itself here so that
+ * render.ts can call back into the JIT engine without a static dependency.
+ *
+ * Result: consumers that never use JIT CSS get zero JIT code in their bundle.
+ */
+type JITChecker = (root: ShadowRoot) => boolean;
+type JITProcessor = (html: string) => string;
+type ProseSheetGetter = () => CSSStyleSheet | null;
+/**
+ * Register the JIT CSS engine with the render pipeline.
+ * Called by style.ts at module load time so renders automatically get
+ * JIT processing without render.ts needing to import style.ts directly.
+ * @internal
+ */
+export declare function _registerRenderBridge(checker: JITChecker, processor: JITProcessor, proseGetter: ProseSheetGetter): void;
+/**
+ * Returns true when JIT CSS should run for the given shadow root.
+ * Returns false if the JIT engine is not loaded.
+ */
+export declare function isJITCSSActiveFor(root: ShadowRoot): boolean;
+/**
+ * Run JIT CSS processing over the aggregated HTML string.
+ * Returns empty string if the JIT engine is not loaded.
+ */
+export declare function processJITCSS(html: string): string;
+/**
+ * Get the prose stylesheet singleton.
+ * Returns null if the JIT engine is not loaded or no prose classes detected.
+ */
+export declare function getProseStyleSheet(): CSSStyleSheet | null;
+export {};

package/dist/runtime/scheduler.d.ts

@@ -28,7 +28,6 @@ declare class UpdateScheduler {
      */
     private scheduleFlush;
     /**
-     * Execute all pending updates with priority ordering
      * Execute all pending updates with priority ordering
      */
     private flush;
@@ -61,7 +60,8 @@ declare class UpdateScheduler {
      */
     private performPeriodicCleanup;
     /**
-     * Emergency cleanup when pending updates exceed safe limits
+     * Emergency cleanup when pending updates exceed safe limits.
+     * @param queue - The specific map to trim; defaults to the normal queue.
      */
     private performEmergencyCleanup;
     /**
@@ -94,8 +94,7 @@ declare class UpdateScheduler {
 }
 export declare const updateScheduler: UpdateScheduler;
 /**
- * Schedule a DOM update to be batched with optional component identity and priority
- * Schedule a DOM update to be batched with optional component identity and priority
+ * Schedule a DOM update to be batched with optional component identity and priority.
  */
 export declare function scheduleDOMUpdate(update: () => void, componentId?: string): void;
 /**

package/dist/runtime/secure-expression-evaluator.d.ts

@@ -7,7 +7,6 @@
  */
 declare class SecureExpressionEvaluator {
     private static cache;
-    private static maxCacheSize;
     private static dangerousPatterns;
     static evaluate(expression: string, context: Record<string, unknown>): unknown;
     private static createEvaluator;

package/dist/runtime/ssr-context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SSR execution context for running component render functions server-side.
+ *
+ * When generating Declarative Shadow DOM (DSD) output, the SSR renderer must
+ * call each custom element's render function to obtain its shadow DOM VNode
+ * tree and capture any useStyle() / useGlobalStyle() output. This module
+ * provides the minimal execution environment that makes that safe.
+ *
+ * Guarantees:
+ *  - useStyle() callbacks are executed and their output is captured.
+ *  - useGlobalStyle() callbacks are captured (not injected into document).
+ *  - Lifecycle hooks (useOnConnected, watch, …) register harmlessly to arrays
+ *    that are never invoked.
+ *  - The reactive system is never permanently mutated — component registration
+ *    is cleaned up by the render wrapper in factory.ts after each call.
+ */
+import type { ComponentConfig, VNode } from './types';
+/** Start collecting useGlobalStyle() output from the current render pass. */
+export declare function beginSSRGlobalStyleCollection(): void;
+/** Stop collecting and return everything gathered so far. */
+export declare function endSSRGlobalStyleCollection(): string[];
+/**
+ * Called by useGlobalStyle() when an SSR collection pass is active.
+ * Returns true if the CSS was captured (caller should skip DOM injection).
+ */
+export declare function captureGlobalStyleForSSR(css: string): boolean;
+export interface SSRRenderResult {
+    /** VNode tree from the component's render function (shadow DOM content). */
+    shadowVNode: VNode | VNode[] | null;
+    /** CSS string captured from useStyle() calls during this render. */
+    useStyleCSS: string;
+}
+/**
+ * Run a component's render function in a minimal SSR context to capture its
+ * shadow DOM VNode tree and any useStyle() output.
+ *
+ * The component's render wrapper in factory.ts handles:
+ *   - setCurrentComponentContext / clearCurrentComponentContext
+ *   - _hookCallbacks reset
+ *   - _computedStyle reset
+ *   - reactiveSystem registration / cleanup
+ *
+ * We only need to build a context object that satisfies the hooks' expectations.
+ */
+export declare function runComponentSSRRender(config: ComponentConfig<object, object, object>, attrs: Record<string, string | number | boolean | null | undefined>, tag?: string): SSRRenderResult;

package/dist/runtime/style.d.ts

@@ -1,24 +1,92 @@
-/**
- * Optimized JIT CSS implementation with reduced bloat and enhanced utilities
- */
-/**
- * CSS template literal
- */
-export declare function css(strings: TemplateStringsArray, ...values: unknown[]): string;
-/**
- * CSS minification utility (basic)
- */
-export declare function minifyCSS(css: string): string;
-export declare function getBaseResetSheet(): CSSStyleSheet;
 export declare function getProseSheet(): CSSStyleSheet | null;
 export declare function registerProseSize(size: string): void;
-export declare function sanitizeCSS(css: string): string;
-export declare const baseReset: string;
 export type CSSMap = Record<string, string>;
+/**
+ * Options for configuring the JIT CSS engine.
+ *
+ * @example
+ * ```ts
+ * import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime';
+ * enableJITCSS({ extendedColors: true });
+ * ```
+ */
+export interface JITCSSOptions {
+    /**
+     * Include the extended Tailwind color palette (slate, gray, red, orange, blue, violet, rose, etc.).
+     * Pass `true` to include all 21 color families, or an array of specific family names to include only
+     * those (e.g. `['slate', 'blue', 'red']`). A targeted list reduces `_activeColors` size and improves
+     * JIT match performance when only a few extended families are needed.
+     */
+    extendedColors?: boolean | string[];
+    /** Custom color palette entries to add to the JIT engine */
+    customColors?: Record<string, Record<string, string>>;
+    /** Disable specific variant groups for smaller output */
+    disableVariants?: Array<'responsive' | 'dark' | 'motion' | 'print' | 'container'>;
+}
 type SelectorVariantMap = Record<string, (selector: string, body: string) => string>;
 type MediaVariantMap = Record<string, string>;
 export declare const colors: Record<string, Record<string, string>>;
-export declare const spacing = "0.25rem";
+/**
+ * Returns `true` when the JIT CSS engine is globally active.
+ * The render engine uses this to skip the JIT pass for projects that do not
+ * use utility classes.
+ */
+export declare function isJITCSSEnabled(): boolean;
+/**
+ * Returns `true` when JIT CSS should run for the given shadow root.
+ * JIT CSS is active if the global flag is set (`enableJITCSS()`) OR if the
+ * specific shadow root was registered via `registerJITCSSComponent()`
+ * (i.e. the component called `useJITCSS()` in its render function).
+ * @internal — used by render.ts
+ */
+export declare function isJITCSSEnabledFor(root: ShadowRoot): boolean;
+/**
+ * Register a shadow root for per-component JIT CSS opt-in.
+ * Called by `useJITCSS()` when invoked inside a component render function.
+ * Optionally processes colour / variant options for this render pass.
+ * @internal
+ */
+export declare function registerJITCSSComponent(root: ShadowRoot, options?: JITCSSOptions): void;
+/**
+ * Configure the JIT CSS engine globally.
+ * Call once at app startup to set options that apply to all components.
+ *
+ * Calling this function also activates the JIT CSS engine if it has been
+ * disabled (e.g. by `disableJITCSS()`).
+ *
+ * @example
+ * ```ts
+ * import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime';
+ *
+ * // Enable extended Tailwind color palette (bg-blue-500, text-violet-700, etc.)
+ * enableJITCSS({ extendedColors: true });
+ *
+ * // Add custom colors
+ * enableJITCSS({ customColors: { brand: { '500': '#e63946', '600': '#c1121f' } } });
+ * ```
+ */
+export declare function enableJITCSS(options?: JITCSSOptions): void;
+/**
+ * Disable the JIT CSS engine globally. Útil for projects that use only
+ * `useStyle()` and want to avoid any JIT parsing overhead.
+ *
+ * @example
+ * ```ts
+ * import { disableJITCSS } from '@jasonshimmy/custom-elements-runtime';
+ * disableJITCSS(); // JIT CSS will not run for any component
+ * ```
+ */
+export declare function disableJITCSS(): void;
+/**
+ * Get the current global JIT CSS options.
+ * @internal
+ */
+export declare function getJITCSSOptions(): JITCSSOptions;
+/**
+ * Reset JIT CSS to default state (semantic colors only). Intended for tests.
+ * @internal
+ */
+export declare function _resetJITCSS(): void;
 export declare const spacingProps: Record<string, string[]>;
 export declare const utilityMap: CSSMap;
 /**
@@ -52,18 +120,8 @@ export declare function parseGradientColorStop(className: string): string | null
 export declare function parseOpacity(className: string): string | null;
 export declare function parseArbitrary(className: string): string | null;
 export declare function parseArbitraryVariant(token: string): string | null;
-/**
- * Polyfill for CSS.escape() for SSR environments
- * Based on https://drafts.csswg.org/cssom/#serialize-an-identifier
- */
-export declare function cssEscape(value: string): string;
-export declare function escapeClassName(name: string): string;
-export declare function escapeRegExp(str: string): string;
 export declare function extractClassesFromHTML(html: string): string[];
-export declare const jitCssCache: Map<string, {
-    css: string;
-    timestamp: number;
-}>;
+export declare const jitCssCache: Map<string, string>;
 export declare const JIT_CSS_THROTTLE_MS = 16;
 export declare function jitCSS(html: string): string;
 export {};

package/dist/runtime/template-compiler/lru-cache.d.ts

@@ -2,12 +2,9 @@ import type { VNode } from '../types';
 export declare class LRUCache<K, V> {
     private map;
     private maxSize;
-    private accessOrder;
-    private accessCounter;
     constructor(maxSize: number);
     get(key: K): V | undefined;
     set(key: K, value: V): void;
-    private evictLRU;
     has(key: K): boolean;
     clear(): void;
     get size(): number;

package/dist/runtime/types.d.ts

@@ -86,11 +86,29 @@ export type ComponentContext<S extends object, C extends object, P extends objec
 } & {
     [key: string]: unknown;
 };
+/**
+ * Controls when (and whether) a server-rendered custom element is hydrated
+ * on the client after the JavaScript bundle loads.
+ *
+ * | Value     | Behaviour |
+ * |-----------|-----------|
+ * | `'load'`  | Hydrate immediately when the element connects (default). |
+ * | `'idle'`  | Defer until `requestIdleCallback` fires. |
+ * | `'visible'` | Defer until the element enters the viewport (`IntersectionObserver`). |
+ * | `'none'`  | Never hydrate — element stays as static server-rendered HTML. |
+ */
+export type HydrateStrategy = 'load' | 'idle' | 'visible' | 'none';
 export type ComponentConfig<S extends object, C extends object = object, P extends object = object, T extends object = object> = {
     props?: Record<string, {
         type: StringConstructor | NumberConstructor | BooleanConstructor | FunctionConstructor;
         default?: string | number | boolean;
     }>;
+    /**
+     * Partial-hydration strategy for this component when SSR DSD output is used.
+     * Emitted as `data-cer-hydrate` on the host element in DSD HTML.
+     * @default 'load'
+     */
+    hydrate?: HydrateStrategy;
     render: (context: ComponentContext<S, C, P, T>) => VNode | VNode[] | Promise<VNode | VNode[]>;
     onConnected?: (context: ComponentContext<S, C, P, T>) => void;
     onDisconnected?: (context: ComponentContext<S, C, P, T>) => void;

package/dist/runtime/vdom-helpers.d.ts

@@ -61,7 +61,6 @@ export interface VDomGlobal {
         };
     };
     __vitest__?: unknown;
-    __VDOM_DISABLED_PROMOTIONS?: unknown[];
 }
 /**
  * Returns `true` when `val` is an object that exposes a `.value` property.

package/dist/runtime/vdom-ssr-dsd.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Declarative Shadow DOM (DSD) SSR renderer.
+ *
+ * When `dsd: true` is passed to the render options, registered custom elements
+ * are serialised as:
+ *
+ * ```html
+ * <my-element attr="val">
+ *   <template shadowrootmode="open">
+ *     <style>
+ *       /* baseReset + useStyle() output + JIT utility CSS *\/
+ *     </style>
+ *     <!-- shadow DOM from component render function -->
+ *   </template>
+ *   <!-- light DOM / slotted children from vnode.children -->
+ * </my-element>
+ * ```
+ *
+ * The browser parses the `<template shadowrootmode="open">` block and attaches
+ * a real shadow root before any JavaScript executes. All CSS layers are present
+ * at first paint — eliminating both FOUC and layout shift.
+ *
+ * Non-custom-element VNodes are rendered identically to renderToString() but
+ * with DSD recursion active for any custom elements nested inside them.
+ */
+import type { VNode } from './types';
+import { type RenderOptions } from './vdom-ssr';
+export type DSDRenderOptions = RenderOptions & {
+    /**
+     * Emit Declarative Shadow DOM output for registered custom elements.
+     * Shadow content is serialised inside `<template shadowrootmode="open">`,
+     * with a complete CSS layer stack (`baseReset` + `useStyle` + JIT CSS)
+     * injected as a `<style>` block so styles are available at first paint.
+     * @default false
+     */
+    dsd?: boolean;
+    /**
+     * Append the DSD polyfill `<script>` for browsers without native support
+     * (Firefox < 123). Only meaningful when `dsd` is true.
+     * @default true
+     */
+    dsdPolyfill?: boolean;
+};
+/**
+ * Minified DSD polyfill for browsers without native Declarative Shadow DOM.
+ * Processes all `<template shadowrootmode>` elements synchronously.
+ */
+export declare const DSD_POLYFILL_SCRIPT: string;
+/**
+ * Render a VNode tree to an HTML string with Declarative Shadow DOM output
+ * for all registered custom elements encountered in the tree.
+ */
+export declare function renderToDSD(vnode: VNode, opts: DSDRenderOptions): string;
+/**
+ * Render a VNode tree to a DSD HTML string and optionally append the
+ * DSD polyfill script for older browsers.
+ */
+export declare function renderToStringDSD(vnode: VNode, opts?: DSDRenderOptions): string;