elements-kit 0.27.2 → 0.27.3

package/dist/integrations/astro-client.mjs

@@ -1,8 +1,8 @@
 import { t as createElement } from "../element-DgQvp-49.mjs";
 import { render } from "../render.mjs";
 import { t as hydrate } from "../hydrate-ICXw1FIY.mjs";
-import { withSlotProps } from "./astro-slots.mjs";
 import { HMR_SLOT } from "./hmr-slot.mjs";
+import { withSlotProps } from "./astro-slots.mjs";
 //#region src/integrations/astro-client.ts
 /**
 * Astro client entrypoint: hydrate an elements-kit island.

package/dist/integrations/astro-server.mjs

@@ -1,7 +1,7 @@
 import { y as setInertEffects } from "../lib-DYypKhxk.mjs";
 import { i as setRenderer, t as createElement } from "../element-DgQvp-49.mjs";
+import { i as serverJsx, n as renderToString, r as SNode } from "../server-CoEm-C0I.mjs";
 import { withSlotProps } from "./astro-slots.mjs";
-import { i as serverJsx, n as renderToString, r as SNode } from "../server-Qm9JTZ-J.mjs";
 //#region src/integrations/astro-server.ts
 /**
 * Decide whether `Component` is an elements-kit component. Invoked by Astro

package/dist/integrations/hmr-runtime.mjs

@@ -1,7 +1,7 @@
 import { t as createElement } from "../element-DgQvp-49.mjs";
 import { render } from "../render.mjs";
 import { HMR_SLOT } from "./hmr-slot.mjs";
-import { n as updateCells } from "../hot-Zl0s17uq.mjs";
+import { n as updateCells } from "../hot-eP6QROpU.mjs";
 //#region src/integrations/hmr-runtime.ts
 const slot = globalThis;
 const records = /* @__PURE__ */ new Set();

package/dist/integrations/react.d.mts

@@ -8,8 +8,17 @@ import { t as Computed } from "../index-B1FHAd5T.mjs";
  * `Computed<T>`. Using `() => T` instead of `Computed<T>` prevents TypeScript from
  * picking the write overload of `Signal<T>` during type inference.
  *
+ * **Server rendering:** pass `getServerSnapshot` for any component React renders
+ * on the server — React requires it there and throws without one. It runs on
+ * the server *and* again for the hydration render on the client, so it must
+ * return the same value both times: whatever the server put in the HTML. A
+ * signal reading browser state (`matchMedia`, `localStorage`, `location`) does
+ * not qualify, since it answers differently in the browser.
+ *
  * @template T - The type of the signal value.
  * @param value - A writable `Signal<T>` or a derived `Computed<T>`.
+ * @param getServerSnapshot - Returns the value the server rendered. Required
+ *   for server-rendered components; omit only for client-only ones.
  * @returns The current value, updated on every signal change.
  *
  * @example
@@ -23,8 +32,15 @@ import { t as Computed } from "../index-B1FHAd5T.mjs";
  *   return <div>{countValue} × 2 = {doubleValue}</div>;
  * }
  * ```
+ *
+ * @example
+ * Server-rendered component reading a browser-only signal:
+ * ```tsx
+ * // `theme` resolves to "light" on the server — say so, or hydration mismatches.
+ * const mode = useSignal(theme, () => "light");
+ * ```
  */
-declare function useSignal<T>(value: () => T): T;
+declare function useSignal<T>(value: () => T, getServerSnapshot?: () => T): T;
 /**
  * Create a signal effect scope tied to a React component's lifetime.
  *

package/dist/integrations/react.mjs

@@ -10,8 +10,17 @@ import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 * `Computed<T>`. Using `() => T` instead of `Computed<T>` prevents TypeScript from
 * picking the write overload of `Signal<T>` during type inference.
 *
+* **Server rendering:** pass `getServerSnapshot` for any component React renders
+* on the server — React requires it there and throws without one. It runs on
+* the server *and* again for the hydration render on the client, so it must
+* return the same value both times: whatever the server put in the HTML. A
+* signal reading browser state (`matchMedia`, `localStorage`, `location`) does
+* not qualify, since it answers differently in the browser.
+*
 * @template T - The type of the signal value.
 * @param value - A writable `Signal<T>` or a derived `Computed<T>`.
+* @param getServerSnapshot - Returns the value the server rendered. Required
+*   for server-rendered components; omit only for client-only ones.
 * @returns The current value, updated on every signal change.
 *
 * @example
@@ -25,12 +34,19 @@ import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 *   return <div>{countValue} × 2 = {doubleValue}</div>;
 * }
 * ```
+*
+* @example
+* Server-rendered component reading a browser-only signal:
+* ```tsx
+* // `theme` resolves to "light" on the server — say so, or hydration mismatches.
+* const mode = useSignal(theme, () => "light");
+* ```
 */
-function useSignal(value) {
+function useSignal(value, getServerSnapshot) {
 	return useSyncExternalStore((callback) => effect(() => {
 		value();
 		callback();
-	}), () => value(), () => value());
+	}), value, getServerSnapshot);
 }
 /**
 * Create a signal effect scope tied to a React component's lifetime.

package/dist/jsx-runtime/dev.mjs

@@ -1,4 +1,4 @@
 import { t as Fragment } from "../fragment-BJfcQdsL.mjs";
-import { t as createHotElement } from "../hot-Zl0s17uq.mjs";
 import "./index.mjs";
+import { t as createHotElement } from "../hot-eP6QROpU.mjs";
 export { Fragment, createHotElement as h, createHotElement as jsx, createHotElement as jsxDEV, createHotElement as jsxs };

package/dist/server/index.mjs

@@ -1,2 +1,2 @@
-import { n as renderToString, t as renderToStream } from "../server-Qm9JTZ-J.mjs";
+import { n as renderToString, t as renderToStream } from "../server-CoEm-C0I.mjs";
 export { renderToStream, renderToString };

package/dist/ui/marketing/marketing.css

@@ -522,7 +522,6 @@
     flex-flow: wrap;
     justify-content: center;
     align-items: center;
-    gap: 1rem 1.5rem;
     width: auto;
   }
 }

package/dist/utilities/dom-lifecycle.d.mts

@@ -1,3 +1,5 @@
+import { t as HTMLElementBase } from "../environment-c2ftMYT0.mjs";
+
 //#region src/utilities/dom-lifecycle.d.ts
 type LifecycleCallback = (self: DomLifecycleElement) => void;
 type AdoptedCallback = (oldDocument: Document, newDocument: Document) => void;
@@ -59,7 +61,7 @@ type AdoptedCallback = (oldDocument: Document, newDocument: Document) => void;
  * </div>
  * ```
  */
-declare class DomLifecycleElement extends HTMLElement {
+declare class DomLifecycleElement extends HTMLElementBase {
   #private;
   set onConnect(fn: LifecycleCallback | null);
   get onConnect(): LifecycleCallback | null;

package/dist/utilities/dom-lifecycle.mjs

@@ -1,6 +1,6 @@
 import { d as effectScope } from "../lib-DYypKhxk.mjs";
 import "../signals/index.mjs";
-import { isBrowser } from "./environment.mjs";
+import { HTMLElementBase, isBrowser } from "./environment.mjs";
 //#region src/utilities/dom-lifecycle.ts
 /**
 * Custom element backing the `<dom-lifecycle>` JSX tag. Place inside any
@@ -60,7 +60,7 @@ import { isBrowser } from "./environment.mjs";
 * </div>
 * ```
 */
-var DomLifecycleElement = class extends HTMLElement {
+var DomLifecycleElement = class extends HTMLElementBase {
 	#onConnect = null;
 	#onDisconnect = null;
 	#onMove = null;

package/dist/utilities/storage.d.mts

@@ -11,6 +11,9 @@ type StorageOptions<T> = {
  * Changes made in other tabs/windows are synchronised automatically via
  * the `StorageEvent`.
  *
+ * Outside a browser — or when `localStorage` is unavailable — the signal is
+ * plain in-memory state seeded with `initialValue`; nothing is persisted.
+ *
  * @example
  * ```ts
  * import { createLocalStorage } from "elements-kit/utilities/storage";
@@ -26,6 +29,9 @@ declare function createLocalStorage<T>(key: string, initialValue: T, options?: S
  *
  * Session storage is scoped to the current tab — no cross-tab sync.
  *
+ * Outside a browser — or when `sessionStorage` is unavailable — the signal is
+ * plain in-memory state seeded with `initialValue`; nothing is persisted.
+ *
  * @example
  * ```ts
  * import { createSessionStorage } from "elements-kit/utilities/storage";

package/dist/utilities/storage.mjs

@@ -1,5 +1,20 @@
+import { x as signal } from "../lib-DYypKhxk.mjs";
+import "../signals/index.mjs";
 import { sync } from "./event-driven.mjs";
+import { isBrowser } from "./environment.mjs";
 //#region src/utilities/storage.ts
+/**
+* The requested `Storage`, or `null` outside a browser and when access throws
+* (sandboxed iframes, blocked site data).
+*/
+function getStorage(area) {
+	if (!isBrowser) return null;
+	try {
+		return area === "local" ? localStorage : sessionStorage;
+	} catch {
+		return null;
+	}
+}
 function readOrDefault(storage, key, initialValue, deserialise) {
 	try {
 		const item = storage.getItem(key);
@@ -7,28 +22,17 @@ function readOrDefault(storage, key, initialValue, deserialise) {
 	} catch {}
 	return initialValue;
 }
-/**
-* Returns a `Signal` persisted to `localStorage`.
-*
-* Changes made in other tabs/windows are synchronised automatically via
-* the `StorageEvent`.
-*
-* @example
-* ```ts
-* import { createLocalStorage } from "elements-kit/utilities/storage";
-*
-* const theme = createLocalStorage<"light" | "dark">("theme", "light");
-* theme();         // read current
-* theme("dark");   // write — persists and notifies
-* ```
-*/
-function createLocalStorage(key, initialValue, options) {
+function createStorageSignal(area, key, initialValue, options, crossTab) {
+	const storage = getStorage(area);
+	if (!storage) return signal(initialValue);
 	const serialise = options?.serialise ?? ((v) => JSON.stringify(v));
 	const deserialise = options?.deserialise ?? ((raw) => JSON.parse(raw));
-	const storage = localStorage;
 	let notify;
 	const subscribe = (cb) => {
 		notify = cb;
+		if (!crossTab) return () => {
+			notify = void 0;
+		};
 		const handler = (e) => {
 			if (e.key === key && e.storageArea === storage) cb();
 		};
@@ -47,10 +51,34 @@ function createLocalStorage(key, initialValue, options) {
 	return s;
 }
 /**
+* Returns a `Signal` persisted to `localStorage`.
+*
+* Changes made in other tabs/windows are synchronised automatically via
+* the `StorageEvent`.
+*
+* Outside a browser — or when `localStorage` is unavailable — the signal is
+* plain in-memory state seeded with `initialValue`; nothing is persisted.
+*
+* @example
+* ```ts
+* import { createLocalStorage } from "elements-kit/utilities/storage";
+*
+* const theme = createLocalStorage<"light" | "dark">("theme", "light");
+* theme();         // read current
+* theme("dark");   // write — persists and notifies
+* ```
+*/
+function createLocalStorage(key, initialValue, options) {
+	return createStorageSignal("local", key, initialValue, options, true);
+}
+/**
 * Returns a `Signal` persisted to `sessionStorage`.
 *
 * Session storage is scoped to the current tab — no cross-tab sync.
 *
+* Outside a browser — or when `sessionStorage` is unavailable — the signal is
+* plain in-memory state seeded with `initialValue`; nothing is persisted.
+*
 * @example
 * ```ts
 * import { createSessionStorage } from "elements-kit/utilities/storage";
@@ -60,23 +88,7 @@ function createLocalStorage(key, initialValue, options) {
 * ```
 */
 function createSessionStorage(key, initialValue, options) {
-	const serialise = options?.serialise ?? ((v) => JSON.stringify(v));
-	const deserialise = options?.deserialise ?? ((raw) => JSON.parse(raw));
-	const storage = sessionStorage;
-	let notify;
-	const subscribe = (cb) => {
-		notify = cb;
-		return () => {
-			notify = void 0;
-		};
-	};
-	const [s] = sync(subscribe, () => readOrDefault(storage, key, initialValue, deserialise), (v) => {
-		try {
-			storage.setItem(key, serialise(v));
-		} catch {}
-		notify?.();
-	});
-	return s;
+	return createStorageSignal("session", key, initialValue, options, false);
 }
 //#endregion
 export { createLocalStorage, createSessionStorage };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elements-kit",
   "type": "module",
-  "version": "0.27.2",
+  "version": "0.27.3",
   "description": "A lightweight reactive UI library that transforms native HTMLElements into reactive components with signals. Ideal for framework-agnostic applications and web components.",
   "keywords": [
     "webcomponents",
@@ -124,7 +124,8 @@
     "storybook": "pnpm --filter elements-kit-storybook dev",
     "watch": "tsdown -w",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:engines": "node scripts/engine-matrix.mjs"
   },
   "packageManager": "pnpm@10.33.0",
   "devDependencies": {
@@ -138,7 +139,8 @@
     "react-dom": "^19.2.5",
     "tsdown": "0.22.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.2",
+    "puppeteer-core": "^24.0.0"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.6",