@playgenx/components 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -281,11 +281,18 @@ declare function usePlaygroundState(): PlaygroundState;
  *
  * Implementation note: this hook ALWAYS calls the same number of
  * React hooks regardless of whether `key` is set or a Provider is in
- * scope. The "no binding" / "no Provider" branch uses dummy local
- * state so the hook count stays aligned across renders. That means a
+ * scope. The "no binding" / "no Provider" branch returns a static
+ * tuple so the hook count stays aligned across renders. That means a
  * component can flip `stateKey` from defined to undefined (or move in
  * or out of a Provider) without crashing with a hooks-order error.
  *
+ * The hook uses React 19's `useSyncExternalStore` so SSR renders the
+ * Provider's current value synchronously — no "value=fallback on
+ * server, value=real after hydration" surprise. The hook count drops
+ * from 5 (useContext + useState + useState + useEffect + useCallback)
+ * to 3 (useContext + useSyncExternalStore + useCallback) as a side
+ * benefit.
+ *
  * Components that accept a `stateKey` prop should call this internally
  * and use the returned tuple as a drop-in for the underlying
  * value/onChange pair. The return type widens to `readonly [...] | undefined`
@@ -298,6 +305,98 @@ declare function usePlaygroundState(): PlaygroundState;
  */
 declare function useBoundValueOrUndefined<T>(key: string | undefined, fallback: T): readonly [T, (next: T) => void] | undefined;
 declare function useBoundValue<T>(key: string, fallback: T): readonly [T, (next: T) => void];
+/**
+ * Non-subscribing accessor for the store. Returns a stable tuple of
+ * imperative API methods (`get`, `set`, `subscribe`, `snapshot`,
+ * `replaceAll`) plus the raw `state` ref — none of which trigger a
+ * re-render when used.
+ *
+ * When to use this instead of `useBoundValue`:
+ *
+ *  - You need to read state inside an event handler (no render needed).
+ *  - You need to set state from many different handlers, not one bound prop.
+ *  - You're implementing a custom hook that wraps the store.
+ *  - You want to subscribe imperatively (for analytics, side-effects).
+ *
+ * When NOT to use this: if you need the component to RE-RENDER on
+ * state changes, use `useBoundValue` (which subscribes for you).
+ *
+ * @example
+ *   function LogoutButton() {
+ *     const { get, set } = useStoreSnapshot();
+ *     return (
+ *       <button onClick={() => {
+ *         if (get<boolean>('confirmLogout')) set('confirmLogout', false);
+ *         doLogout();
+ *       }}>Log out</button>
+ *     );
+ *   }
+ */
+declare function useStoreSnapshot(): {
+  readonly state: PlaygroundState;
+  readonly get: <T = unknown>(key: string) => T | undefined;
+  readonly set: <T = unknown>(key: string, value: T) => void;
+  readonly subscribe: (key: string, cb: (value: unknown) => void) => () => void;
+  readonly snapshot: () => Readonly<Record<string, unknown>>;
+  readonly replaceAll: (values: Record<string, unknown>) => void;
+};
+/**
+ * Bind a state key with a selector transform. Returns the SELECTED
+ * value, not the raw value. The component only re-renders when the
+ * selected slice changes — not when OTHER fields on the same key
+ * change.
+ *
+ * Useful for normalized state where one key holds an object and you
+ * only care about one property:
+ *
+ * @example
+ *   interface User { name: string; age: number; email: string; }
+ *   const userName = useBoundSelector<User, string>(
+ *     'currentUser',
+ *     (u) => u?.name ?? '(anonymous)',
+ *     'guest'
+ *   );
+ *   // Setting `currentUser.age` does NOT re-render this component.
+ *   // Setting `currentUser.name` DOES re-render this component.
+ *
+ * The setter writes the SELECTED value as-is to the store. For
+ * partial-merge semantics (e.g., "set only the name, keep other
+ * fields"), use `useStoreSnapshot()` directly and merge yourself.
+ *
+ * If the selector throws, the error propagates and the component
+ * unmounts via the nearest error boundary. Wrap your selector in
+ * a try/catch if you need resilience.
+ */
+declare function useBoundSelector<T, U>(key: string, selector: (raw: T | undefined) => U, fallback: U): readonly [U, (next: U) => void];
+/**
+ * Bind multiple keys at once. Returns a `Record<key, [value, setter]>`
+ * for the keys you specify. Each setter writes back to its own key.
+ *
+ * Useful for forms and dashboards where multiple bound inputs share
+ * a single Provider.
+ *
+ * @example
+ *   const form = useMultiBoundValue({
+ *     name: { fallback: '' },
+ *     age:  { fallback: 0 },
+ *     email: { fallback: '' },
+ *   });
+ *   // form.name[0] === current name string
+ *   // form.age[1](42)  writes 42 to state.age
+ *
+ * The hook subscribes ONCE per key (so 5 keys = 5 subscriptions,
+ * not a single batched subscription). If you bind a LOT of keys,
+ * consider using `useStoreSnapshot()` instead — it doesn't subscribe.
+ *
+ * @example
+ *   // 50-row table, each row needs its own value
+ *   const { get, set } = useStoreSnapshot();
+ *   rows.map(row => <input value={get(`cell-${row.id}`) ?? ''}
+ *                       onChange={e => set(`cell-${row.id}`, e.target.value)} />);
+ */
+declare function useMultiBoundValue<K extends string>(bindings: Record<K, {
+  fallback: unknown;
+}>): { readonly [P in K]: readonly [unknown, (next: unknown) => void]; };
 /**
  * State-binding action shape. Used by `<Button onClickAction={...}>`.
  *   { set: { count: 1 } }   -> sets state.count = 1
@@ -506,5 +605,5 @@ declare const componentMap: ComponentMap;
  */
 declare function createRegistry(overrides: Partial<ComponentMap>): ComponentMap;
 //#endregion
-export { ArtifactErrorBoundary, type ArtifactErrorBoundaryProps, Button, type ButtonProps, Card, type CardProps, Chart, type ChartKind, type ChartProps, Code, type CodeProps, type ComponentMap, Container, type ContainerProps, Heading, type HeadingProps, List, type ListProps, type PlaygroundState, PlaygroundStateProvider, type PlaygroundStateProviderProps, ShowSource, type ShowSourceProps, Slider, type SliderProps, type StateAction, type StateDiff, type StateEnvelope, type Step, Stepper, type StepperProps, Text, TextField, type TextFieldProps, type TextProps, batch, clearState, componentMap, createPlaygroundState, createRegistry, diffSnapshots, diffState, dumpState, useBoundValue, useBoundValueOrUndefined, usePlaygroundState, useStateAction, validateStateKey };
+export { ArtifactErrorBoundary, type ArtifactErrorBoundaryProps, Button, type ButtonProps, Card, type CardProps, Chart, type ChartKind, type ChartProps, Code, type CodeProps, type ComponentMap, Container, type ContainerProps, Heading, type HeadingProps, List, type ListProps, type PlaygroundState, PlaygroundStateProvider, type PlaygroundStateProviderProps, ShowSource, type ShowSourceProps, Slider, type SliderProps, type StateAction, type StateDiff, type StateEnvelope, type Step, Stepper, type StepperProps, Text, TextField, type TextFieldProps, type TextProps, batch, clearState, componentMap, createPlaygroundState, createRegistry, diffSnapshots, diffState, dumpState, useBoundSelector, useBoundValue, useBoundValueOrUndefined, useMultiBoundValue, usePlaygroundState, useStateAction, useStoreSnapshot, validateStateKey };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/Button.tsx","../src/TextField.tsx","../src/Slider.tsx","../src/Chart.tsx","../src/Container.tsx","../src/Code.tsx","../src/Heading.tsx","../src/Text.tsx","../src/Stepper.tsx","../src/Card.tsx","../src/List.tsx","../src/state.tsx","../src/stateHelpers.ts","../src/ArtifactErrorBoundary.tsx","../src/ShowSource.tsx","../src/createRegistry.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/Button.tsx","../src/TextField.tsx","../src/Slider.tsx","../src/Chart.tsx","../src/Container.tsx","../src/Code.tsx","../src/Heading.tsx","../src/Text.tsx","../src/Stepper.tsx","../src/Card.tsx","../src/List.tsx","../src/state.tsx","../src/stateHelpers.ts","../src/ArtifactErrorBoundary.tsx","../src/ShowSource.tsx","../src/createRegistry.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -308,11 +308,18 @@ function usePlaygroundState() {
 *
 * Implementation note: this hook ALWAYS calls the same number of
 * React hooks regardless of whether `key` is set or a Provider is in
-* scope. The "no binding" / "no Provider" branch uses dummy local
-* state so the hook count stays aligned across renders. That means a
+* scope. The "no binding" / "no Provider" branch returns a static
+* tuple so the hook count stays aligned across renders. That means a
 * component can flip `stateKey` from defined to undefined (or move in
 * or out of a Provider) without crashing with a hooks-order error.
 *
+* The hook uses React 19's `useSyncExternalStore` so SSR renders the
+* Provider's current value synchronously — no "value=fallback on
+* server, value=real after hydration" surprise. The hook count drops
+* from 5 (useContext + useState + useState + useEffect + useCallback)
+* to 3 (useContext + useSyncExternalStore + useCallback) as a side
+* benefit.
+*
 * Components that accept a `stateKey` prop should call this internally
 * and use the returned tuple as a drop-in for the underlying
 * value/onChange pair. The return type widens to `readonly [...] | undefined`
@@ -326,21 +333,30 @@ function usePlaygroundState() {
 function useBoundValueOrUndefined(key, fallback) {
 	const ctx = React.useContext(PlaygroundStateContext);
 	const bound = key !== void 0 && ctx !== null;
-	const [value, setValue] = React.useState(fallback);
-	const [, force] = React.useState(0);
-	React.useEffect(() => {
-		if (!bound || key === void 0 || ctx === null) return;
-		const initial = ctx.state.get(key) ?? fallback;
-		setValue(initial);
-		return ctx.state.subscribe(key, (next) => {
-			setValue(next);
-			force((n) => n + 1);
-		});
+	const value = React.useSyncExternalStore(React.useCallback((onStoreChange) => {
+		if (!bound || key === void 0 || ctx === null) return () => {};
+		return ctx.state.subscribe(key, onStoreChange);
 	}, [
 		bound,
 		ctx,
 		key
-	]);
+	]), React.useCallback(() => {
+		if (!bound || key === void 0 || ctx === null) return fallback;
+		return ctx.state.get(key) ?? fallback;
+	}, [
+		bound,
+		ctx,
+		key,
+		fallback
+	]), React.useCallback(() => {
+		if (!bound || key === void 0 || ctx === null) return fallback;
+		return ctx.state.get(key) ?? fallback;
+	}, [
+		bound,
+		ctx,
+		key,
+		fallback
+	]));
 	const set = React.useCallback((next) => {
 		if (!bound || key === void 0 || ctx === null) return;
 		ctx.state.set(key, next);
@@ -358,6 +374,124 @@ function useBoundValue(key, fallback) {
 	return bound;
 }
 /**
+* Non-subscribing accessor for the store. Returns a stable tuple of
+* imperative API methods (`get`, `set`, `subscribe`, `snapshot`,
+* `replaceAll`) plus the raw `state` ref — none of which trigger a
+* re-render when used.
+*
+* When to use this instead of `useBoundValue`:
+*
+*  - You need to read state inside an event handler (no render needed).
+*  - You need to set state from many different handlers, not one bound prop.
+*  - You're implementing a custom hook that wraps the store.
+*  - You want to subscribe imperatively (for analytics, side-effects).
+*
+* When NOT to use this: if you need the component to RE-RENDER on
+* state changes, use `useBoundValue` (which subscribes for you).
+*
+* @example
+*   function LogoutButton() {
+*     const { get, set } = useStoreSnapshot();
+*     return (
+*       <button onClick={() => {
+*         if (get<boolean>('confirmLogout')) set('confirmLogout', false);
+*         doLogout();
+*       }}>Log out</button>
+*     );
+*   }
+*/
+function useStoreSnapshot() {
+	const ctx = React.useContext(PlaygroundStateContext);
+	if (ctx === null) throw new Error("useStoreSnapshot() must be called inside a <PlaygroundStateProvider>.");
+	return {
+		state: ctx.state,
+		get: ctx.state.get,
+		set: ctx.state.set,
+		subscribe: ctx.state.subscribe,
+		snapshot: ctx.state.snapshot,
+		replaceAll: ctx.state.replaceAll
+	};
+}
+/**
+* Bind a state key with a selector transform. Returns the SELECTED
+* value, not the raw value. The component only re-renders when the
+* selected slice changes — not when OTHER fields on the same key
+* change.
+*
+* Useful for normalized state where one key holds an object and you
+* only care about one property:
+*
+* @example
+*   interface User { name: string; age: number; email: string; }
+*   const userName = useBoundSelector<User, string>(
+*     'currentUser',
+*     (u) => u?.name ?? '(anonymous)',
+*     'guest'
+*   );
+*   // Setting `currentUser.age` does NOT re-render this component.
+*   // Setting `currentUser.name` DOES re-render this component.
+*
+* The setter writes the SELECTED value as-is to the store. For
+* partial-merge semantics (e.g., "set only the name, keep other
+* fields"), use `useStoreSnapshot()` directly and merge yourself.
+*
+* If the selector throws, the error propagates and the component
+* unmounts via the nearest error boundary. Wrap your selector in
+* a try/catch if you need resilience.
+*/
+function useBoundSelector(key, selector, fallback) {
+	const bound = useBoundValueOrUndefined(key, fallback);
+	const raw = bound === void 0 ? void 0 : bound[0];
+	const value = React.useMemo(() => selector(raw), [
+		raw,
+		selector,
+		fallback
+	]);
+	const set = React.useCallback((next) => {
+		if (bound === void 0) return;
+		bound[1](next);
+	}, [bound]);
+	if (bound === void 0) throw new Error("useBoundSelector requires a non-undefined `key` and a <PlaygroundStateProvider> ancestor.");
+	return [value, set];
+}
+/**
+* Bind multiple keys at once. Returns a `Record<key, [value, setter]>`
+* for the keys you specify. Each setter writes back to its own key.
+*
+* Useful for forms and dashboards where multiple bound inputs share
+* a single Provider.
+*
+* @example
+*   const form = useMultiBoundValue({
+*     name: { fallback: '' },
+*     age:  { fallback: 0 },
+*     email: { fallback: '' },
+*   });
+*   // form.name[0] === current name string
+*   // form.age[1](42)  writes 42 to state.age
+*
+* The hook subscribes ONCE per key (so 5 keys = 5 subscriptions,
+* not a single batched subscription). If you bind a LOT of keys,
+* consider using `useStoreSnapshot()` instead — it doesn't subscribe.
+*
+* @example
+*   // 50-row table, each row needs its own value
+*   const { get, set } = useStoreSnapshot();
+*   rows.map(row => <input value={get(`cell-${row.id}`) ?? ''}
+*                       onChange={e => set(`cell-${row.id}`, e.target.value)} />);
+*/
+function useMultiBoundValue(bindings) {
+	if (React.useContext(PlaygroundStateContext) === null) throw new Error("useMultiBoundValue() must be called inside a <PlaygroundStateProvider>.");
+	const result = {};
+	const keys = Object.keys(bindings);
+	for (const k of keys) {
+		const b = useBoundValueOrUndefined(k, bindings[k].fallback);
+		if (b === void 0) result[k] = [bindings[k].fallback, () => {}];
+		else result[k] = b;
+	}
+	return result;
+}
+/**
 * Apply a StateAction to the nearest PlaygroundState. Returns an
 * onClick handler that fires the action. If action is undefined
 * the handler is a no-op.
@@ -1184,6 +1318,6 @@ function createRegistry(overrides) {
 	return Object.freeze(merged);
 }
 //#endregion
-export { ArtifactErrorBoundary, Button, Card, Chart, Code, Container, Heading, List, PlaygroundStateProvider, ShowSource, Slider, Stepper, Text, TextField, batch, clearState, componentMap, createPlaygroundState, createRegistry, diffSnapshots, diffState, dumpState, useBoundValue, useBoundValueOrUndefined, usePlaygroundState, useStateAction, validateStateKey };
+export { ArtifactErrorBoundary, Button, Card, Chart, Code, Container, Heading, List, PlaygroundStateProvider, ShowSource, Slider, Stepper, Text, TextField, batch, clearState, componentMap, createPlaygroundState, createRegistry, diffSnapshots, diffState, dumpState, useBoundSelector, useBoundValue, useBoundValueOrUndefined, useMultiBoundValue, usePlaygroundState, useStateAction, useStoreSnapshot, validateStateKey };
 
 //# sourceMappingURL=index.mjs.map