@jasonshimmy/custom-elements-runtime 1.1.1 → 1.2.0

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { useEmit, useOnConnected, useOnDisconnected, useOnAttributeChanged, useO
 export { ref, computed, watch } from "./runtime/reactive";
 export { html } from "./runtime/template-compiler";
 export { css } from "./runtime/style";
+export { unsafeHTML, decodeEntities } from "./runtime/helpers";
 export { renderToString } from "./runtime/vdom";
 export type { VNode } from "./runtime/types";
 export * from "./directives";

package/dist/runtime/helpers.d.ts

@@ -23,6 +23,54 @@ export declare function getStringCacheStats(): {
     htmlEscapeCacheSize: number;
 };
 export declare function escapeHTML(str: string | number | boolean): string | number | boolean;
+/**
+ * Decode HTML entities (named and numeric) into their character equivalents.
+ * - In browser: uses a DOM-based technique to decode entities while preserving
+ *   existing raw tags.
+ * - In non-DOM (SSR) environments: handles numeric references and a conservative
+ *   named-entity map for common entities.
+ *
+ * @param str - string containing HTML entities
+ * @returns decoded string
+ */
+export declare function decodeEntities(str: string): string;
+/**
+ * Dynamically load the full named-entity map (used in SSR). Exported for testing and
+ * to allow bundlers to exclude the JSON from client bundles when dynamic import
+ * is used behind a DOM check.
+ */
+export declare function loadEntityMap(): Promise<Record<string, string>>;
+/**
+ * Register a full named-entity map for SSR. Intended for server startup code to
+ * provide the authoritative HTML5 entity mapping. This keeps the client bundle
+ * small because the map is only injected on the server side.
+ *
+ * registerEntityMap should be called once at server startup prior to rendering.
+ */
+export declare function registerEntityMap(map: Record<string, string>, options?: {
+    overwrite?: boolean;
+}): void;
+/**
+ * Clear any registered entity map. Useful for tests or restarting state.
+ */
+export declare function clearRegisteredEntityMap(): void;
+/**
+ * Wrap a string as raw HTML. This is intentionally unsafe — callers must
+ * sanitize untrusted input before using this. The returned object provides
+ * two property names to be compatible with different parts of the runtime.
+ */
+export declare function unsafeHTML(html: string): {
+    __unsafeHTML: string;
+    __rawHTML: string;
+};
+/** Type-guard for unsafeHTML wrapper */
+export declare function isUnsafeHTML(value: unknown): value is {
+    __unsafeHTML?: string;
+    __rawHTML?: string;
+};
+/**
+ * Get nested property value from object using dot notation
+ */
 export declare function getNestedValue(obj: any, path: string): any;
 /**
  * Set nested property value in object using dot notation

package/dist/runtime/node-metadata.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Retrieve the stored node key for a Node.
+ *
+ * The lookup prefers a WeakMap-stored value. For compatibility it will also
+ * attempt to read legacy fallbacks: a `.key` property or the
+ * `data-anchor-key` attribute on Elements.
+ *
+ * @internal
+ */
+export declare function getNodeKey(node: Node | null | undefined): string | undefined;
+/**
+ * Store a node key on a Node.
+ *
+ * This sets a WeakMap entry and also writes defensive DOM fallbacks for
+ * compatibility with older consumers/tests. Errors are swallowed to avoid
+ * disrupting host environments that forbid property writes.
+ *
+ * @internal
+ */
+export declare function setNodeKey(node: Node, key: string): void;
+/**
+ * Retrieve transition-group metadata attached to an element.
+ *
+ * Prefers the WeakMap but falls back to a legacy `._transitionGroup` property
+ * if present.
+ *
+ * @internal
+ */
+export declare function getElementTransition(el: HTMLElement | null | undefined): any;
+/**
+ * Store transition-group metadata for an element.
+ *
+ * Writes to the WeakMap and a defensive legacy property for compatibility.
+ * Errors are swallowed to avoid breaking host environments.
+ *
+ * @internal
+ */
+export declare function setElementTransition(el: HTMLElement, val: any): void;
+declare const _default: {
+    getNodeKey: typeof getNodeKey;
+    setNodeKey: typeof setNodeKey;
+    getElementTransition: typeof getElementTransition;
+    setElementTransition: typeof setElementTransition;
+};
+export default _default;

package/dist/runtime/style.d.ts

@@ -25,6 +25,7 @@ export declare const containerVariants: MediaVariantMap;
 export declare const responsiveOrder: string[];
 export declare const containerOrder: string[];
 export declare function parseSpacing(className: string): string | null;
+export declare function parseSpaceUtility(className: string): string | null;
 export declare function hexToRgb(hex: string): string;
 export declare function parseColorClass(className: string): string | null;
 export declare function parseOpacityModifier(className: string): {

package/dist/transitions.d.ts

@@ -75,6 +75,10 @@ export interface TransitionGroupOptions extends Omit<TransitionOptions, 'show'>
     moveClass?: string;
     /** Whether to show the group (defaults to true for TransitionGroup) */
     show?: boolean;
+    /** CSS classes to apply to the wrapper element (e.g., 'flex gap-4' or 'grid grid-cols-3') */
+    class?: string;
+    /** Inline styles to apply to the wrapper element */
+    style?: string | Record<string, string>;
 }
 /**
  * Pre-defined transition presets using JIT CSS classes
@@ -206,6 +210,7 @@ export declare function Transition(options: TransitionOptions, content: VNode |
  *
  * @example
  * ```ts
+ * // Basic usage
  * ${TransitionGroup({
  *   preset: 'slide-right',
  *   tag: 'ul',
@@ -213,6 +218,22 @@ export declare function Transition(options: TransitionOptions, content: VNode |
  * }, each(items.value, (item) => html`
  *   <li key="${item.id}">${item.text}</li>
  * `))}
+ *
+ * // With flex layout
+ * ${TransitionGroup({
+ *   preset: 'fade',
+ *   class: 'flex gap-4 flex-wrap'
+ * }, each(items.value, (item) => html`
+ *   <div key="${item.id}" class="flex-shrink-0">${item.text}</div>
+ * `))}
+ *
+ * // With grid layout
+ * ${TransitionGroup({
+ *   preset: 'scale',
+ *   class: 'grid grid-cols-3 gap-4'
+ * }, each(items.value, (item) => html`
+ *   <div key="${item.id}">${item.text}</div>
+ * `))}
  * ```
  */
 export declare function TransitionGroup(options: TransitionGroupOptions, children: VNode[]): VNode;

package/entities.json

@@ -0,0 +1,211 @@
+{
+  "lt": "<",
+  "gt": ">",
+  "amp": "&",
+  "quot": "\"",
+  "apos": "'",
+  "nbsp": "\u00A0",
+
+  "iexcl": "¡",
+  "cent": "¢",
+  "pound": "£",
+  "curren": "¤",
+  "yen": "¥",
+  "brvbar": "¦",
+  "sect": "§",
+  "uml": "¨",
+  "copy": "©",
+  "ordf": "ª",
+  "laquo": "«",
+  "not": "¬",
+  "shy": "\u00AD",
+  "reg": "®",
+  "macr": "¯",
+  "deg": "°",
+  "plusmn": "±",
+  "sup2": "²",
+  "sup3": "³",
+  "acute": "´",
+  "micro": "µ",
+  "para": "¶",
+  "middot": "·",
+  "cedil": "¸",
+  "sup1": "¹",
+  "ordm": "º",
+  "raquo": "»",
+  "frac14": "¼",
+  "frac12": "½",
+  "frac34": "¾",
+  "iquest": "¿",
+
+  "Agrave": "À",
+  "Aacute": "Á",
+  "Acirc": "Â",
+  "Atilde": "Ã",
+  "Auml": "Ä",
+  "Aring": "Å",
+  "AElig": "Æ",
+  "Ccedil": "Ç",
+  "Egrave": "È",
+  "Eacute": "É",
+  "Ecirc": "Ê",
+  "Euml": "Ë",
+  "Igrave": "Ì",
+  "Iacute": "Í",
+  "Icirc": "Î",
+  "Iuml": "Ï",
+  "ETH": "Ð",
+  "Ntilde": "Ñ",
+  "Ograve": "Ò",
+  "Oacute": "Ó",
+  "Ocirc": "Ô",
+  "Otilde": "Õ",
+  "Ouml": "Ö",
+  "times": "×",
+  "Oslash": "Ø",
+  "Ugrave": "Ù",
+  "Uacute": "Ú",
+  "Ucirc": "Û",
+  "Uuml": "Ü",
+  "Yacute": "Ý",
+  "THORN": "Þ",
+  "szlig": "ß",
+  "agrave": "à",
+  "aacute": "á",
+  "acirc": "â",
+  "atilde": "ã",
+  "auml": "ä",
+  "aring": "å",
+  "aelig": "æ",
+  "ccedil": "ç",
+  "egrave": "è",
+  "eacute": "é",
+  "ecirc": "ê",
+  "euml": "ë",
+  "igrave": "ì",
+  "iacute": "í",
+  "icirc": "î",
+  "iuml": "ï",
+  "eth": "ð",
+  "ntilde": "ñ",
+  "ograve": "ò",
+  "oacute": "ó",
+  "ocirc": "ô",
+  "otilde": "õ",
+  "ouml": "ö",
+  "divide": "÷",
+  "oslash": "ø",
+  "ugrave": "ù",
+  "uacute": "ú",
+  "ucirc": "û",
+  "uuml": "ü",
+  "yacute": "ý",
+  "thorn": "þ",
+  "yuml": "ÿ",
+
+  "euro": "€",
+  "trade": "™",
+  "mdash": "—",
+  "ndash": "–",
+  "hellip": "…",
+  "bull": "•",
+  "prime": "′",
+  "Prime": "″",
+  "permil": "‰",
+  "dagger": "†",
+  "Dagger": "‡",
+  "cedilla": "¸",
+  "oelig": "œ",
+  "scaron": "š",
+  "Yuml": "Ÿ",
+
+  "lsquo": "‘",
+  "rsquo": "’",
+  "ldquo": "“",
+  "rdquo": "”",
+
+  "sterling": "£",
+
+  "pi": "π",
+  "Pi": "Π",
+  "alpha": "α",
+  "beta": "β",
+  "gamma": "γ",
+  "Gamma": "Γ",
+  "delta": "δ",
+  "Delta": "Δ",
+  "epsilon": "ϵ",
+  "epsiv": "ε",
+  "zeta": "ζ",
+  "eta": "η",
+  "theta": "θ",
+  "Theta": "Θ",
+  "iota": "ι",
+  "kappa": "κ",
+  "lambda": "λ",
+  "Lambda": "Λ",
+  "mu": "μ",
+  "nu": "ν",
+  "xi": "ξ",
+  "Xi": "Ξ",
+  "omicron": "ο",
+  "rho": "ρ",
+  "sigma": "σ",
+  "Sigma": "Σ",
+  "tau": "τ",
+  "upsilon": "υ",
+  "phi": "φ",
+  "Phi": "Φ",
+  "chi": "χ",
+  "psi": "ψ",
+  "omega": "ω",
+  "Omega": "Ω",
+
+  "infty": "∞",
+  "sub": "⊂",
+  "sup": "⊃",
+  "nsub": "⊄",
+  "sube": "⊆",
+  "supe": "⊇",
+  "ne": "≠",
+  "le": "≤",
+  "ge": "≥",
+  "approx": "≈",
+  "cong": "≅",
+  "there4": "∴",
+  "forall": "∀",
+  "exist": "∃",
+  "empty": "∅",
+  "nabla": "∇",
+  "partial": "∂",
+  "sum": "∑",
+  "prod": "∏",
+  "int": "∫",
+  "lowast": "∗",
+  "radic": "√",
+  "real": "ℜ",
+  "image": "ℑ",
+  "ang": "∠",
+  "oplus": "⊕",
+  "otimes": "⊗",
+  "perp": "⊥",
+
+  "larr": "←",
+  "rarr": "→",
+  "uarr": "↑",
+  "darr": "↓",
+  "harr": "↔",
+  "lArr": "⇐",
+  "rArr": "⇒",
+  "uArr": "⇑",
+  "dArr": "⇓",
+  "hArr": "⇔",
+  "lceil": "⌈",
+  "rceil": "⌉",
+  "lfloor": "⌊",
+  "rfloor": "⌋",
+
+  "ampersand": "&",
+  "caret": "^",
+  "tilde": "~"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jasonshimmy/custom-elements-runtime",
   "description": "A powerful, modern, and lightweight runtime for creating reactive web components with TypeScript",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "type": "module",
   "keywords": [
     "web-components",
@@ -42,7 +42,8 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "dist/index.d.ts"
+    "dist/index.d.ts",
+    "entities.json"
   ],
   "exports": {
     ".": {
@@ -50,7 +51,8 @@
       "import": "./dist/custom-elements-runtime.es.js",
       "require": "./dist/custom-elements-runtime.cjs.js",
       "default": "./dist/custom-elements-runtime.umd.js"
-    }
+    },
+    "./entities.json": "./entities.json"
   },
   "publishConfig": {
     "access": "public"