@playgenx/components 0.1.0 → 0.2.1

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/theme.ts
 /**
 * Shared theme tokens for @playgenx/components.
@@ -125,15 +125,285 @@ function TextField({ label, value, placeholder, disabled = false, onChange }) {
 	});
 }
 //#endregion
+//#region src/state.tsx
+/**
+* Per-render interactive state store. Used by PlaygroundStateProvider to
+* back interactive components (Slider, TextField, Button, Chart) without
+* requiring them to be fully controlled.
+*
+* Design notes:
+* - The store is a singleton instance per Provider, NOT React context.
+*   Components consume it via usePlaygroundState() inside React renders,
+*   and via .subscribe() / .get() / .set() from non-React callers.
+* - `set` is synchronous; subscribers fire in registration order on the
+*   next microtask (so multiple sets in a single tick produce a single
+*   re-render per subscriber).
+* - `set` with `===` equal value is a no-op (no subscriber fires).
+* - Throws if used outside a PlaygroundStateProvider (when required by
+*   the caller's contract).
+*
+* @packageDocumentation
+*/
+/**
+* Create a fresh state store. Public so PlaygroundStateProvider can
+* construct one, but consumers should use Provider/usePlaygroundState
+* to access stores (not direct construction).
+*
+* The optional type parameter is the "shape" of values you intend to
+* store. It's purely a documentation convenience — the store does
+* not enforce it (so you can store heterogeneous values for
+* playgrounds that mix kinds), but `get<T>()` and `set<T>()` will
+* infer correctly when you pass it here.
+*/
+function createPlaygroundState(initial = {}) {
+	const values = new Map(Object.entries(initial));
+	const subs = /* @__PURE__ */ new Map();
+	let pending = [];
+	let scheduled = false;
+	let batchDepth = 0;
+	let batchedPending = [];
+	const flush = () => {
+		if (pending.length === 0) return;
+		const batch = pending;
+		pending = [];
+		scheduled = false;
+		for (const { key, value } of batch) {
+			const list = subs.get(key);
+			if (list) for (const cb of [...list]) try {
+				cb(value);
+			} catch (err) {
+				if (process.env.NODE_ENV !== "production") console.error("[playgenx] subscriber for key %s threw:", key, err);
+			}
+		}
+	};
+	const schedule = () => {
+		if (scheduled) return;
+		scheduled = true;
+		if (typeof queueMicrotask === "function") queueMicrotask(flush);
+		else Promise.resolve().then(flush);
+	};
+	const state = {
+		get(key) {
+			return values.get(key);
+		},
+		set(key, value) {
+			if (Object.is(values.get(key), value)) return;
+			values.set(key, value);
+			if (batchDepth > 0) batchedPending.push({
+				key,
+				value
+			});
+			else pending.push({
+				key,
+				value
+			});
+			schedule();
+		},
+		subscribe(key, cb) {
+			let list = subs.get(key);
+			if (!list) {
+				list = /* @__PURE__ */ new Set();
+				subs.set(key, list);
+			}
+			list.add(cb);
+			return () => {
+				const l = subs.get(key);
+				if (l) {
+					l.delete(cb);
+					if (l.size === 0) subs.delete(key);
+				}
+			};
+		},
+		snapshot() {
+			return Object.fromEntries(values);
+		},
+		replaceAll(values) {
+			for (const [k, v] of Object.entries(values)) state.set(k, v);
+		},
+		_flush() {
+			flush();
+		},
+		_batch(fn) {
+			batchDepth++;
+			try {
+				return fn();
+			} finally {
+				batchDepth--;
+				if (batchDepth === 0 && batchedPending.length > 0) {
+					const lastPerKey = /* @__PURE__ */ new Map();
+					for (let i = batchedPending.length - 1; i >= 0; i--) {
+						const { key, value } = batchedPending[i];
+						if (!lastPerKey.has(key)) {
+							lastPerKey.set(key, value);
+							pending.push({
+								key,
+								value
+							});
+						}
+					}
+					batchedPending = [];
+				}
+			}
+		},
+		_clearAllSubscribers() {
+			subs.clear();
+			pending = [];
+			batchedPending = [];
+			scheduled = false;
+		}
+	};
+	return state;
+}
+/**
+* React context. Exposed as a type only — consumers should use
+* PlaygroundStateProvider and usePlaygroundState rather than reading
+* the context directly.
+*/
+const PlaygroundStateContext = React.createContext(null);
+/**
+* Provide a PlaygroundState scope to descendant components.
+*
+* Each Provider instance has its own store; nested Providers create
+* independent scopes. Components rendered outside any Provider will
+* throw a clear error if they call usePlaygroundState.
+*/
+function PlaygroundStateProvider(props) {
+	const [state] = React.useState(() => {
+		return createPlaygroundState({
+			...props.seed,
+			...props.initial
+		});
+	});
+	React.useEffect(() => {
+		return () => {
+			state._clearAllSubscribers?.();
+		};
+	}, [state]);
+	const value = React.useMemo(() => ({ state }), [state]);
+	return React.createElement(PlaygroundStateContext.Provider, { value }, props.children);
+}
+/**
+* Hook to access the nearest PlaygroundState store. Throws a clear
+* error if called outside a Provider so consumers get a usable
+* diagnostic instead of a `Cannot read properties of undefined`.
+*
+* Note for @playgenx/renderer users: the renderer's `renderBody`
+* does NOT yet auto-wrap with a PlaygroundStateProvider. You'll
+* need to wrap your own tree with `<PlaygroundStateProvider>` (or
+* use the lower-level `renderNodes` API) before state-bound
+* components can resolve. The `withState` option on `renderBody`
+* is planned for a future renderer release (tracked in v0.6.0).
+*/
+function usePlaygroundState() {
+	const ctx = React.useContext(PlaygroundStateContext);
+	if (ctx === null) throw new Error("usePlaygroundState() must be called inside a <PlaygroundStateProvider>. Wrap your component tree with the Provider. (A future renderer release will auto-wrap; for now, do it explicitly.)");
+	return ctx.state;
+}
+/**
+* Optional helper for binding a component prop to a state key. Returns
+* the live value (re-renders subscribers on change) and a setter. Pass
+* `undefined` for `key` to disable the binding — the component behaves
+* as if it had no stateKey, and `set` becomes a no-op. Safe to call
+* outside a Provider.
+*
+* 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
+* component can flip `stateKey` from defined to undefined (or move in
+* or out of a Provider) without crashing with a hooks-order error.
+*
+* 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`
+* so the caller can still branch on `if (bound)` — but they don't have
+* to (the tuple is always safe to index).
+*
+* @example
+*   const bound = useBoundValueOrUndefined<number>(stateKey, 50);
+*   // ... onChange={(e) => bound?.[1](Number(e.currentTarget.value))}
+*/
+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);
+		});
+	}, [
+		bound,
+		ctx,
+		key
+	]);
+	const set = React.useCallback((next) => {
+		if (!bound || key === void 0 || ctx === null) return;
+		ctx.state.set(key, next);
+	}, [
+		bound,
+		ctx,
+		key
+	]);
+	if (!bound) return void 0;
+	return [value, set];
+}
+function useBoundValue(key, fallback) {
+	const bound = useBoundValueOrUndefined(key, fallback);
+	if (bound === void 0) throw new Error("useBoundValue(key, ...) requires both a non-undefined `key` and a <PlaygroundStateProvider> ancestor. Use useBoundValueOrUndefined if you want optional binding.");
+	return bound;
+}
+/**
+* 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.
+*/
+function useStateAction(action) {
+	const state = usePlaygroundState();
+	return React.useCallback((event) => {
+		if (action === void 0) return;
+		if (action.set) for (const [k, v] of Object.entries(action.set)) state.set(k, v);
+		if (action.toggle !== void 0) {
+			const key = action.toggle;
+			const current = state.get(key);
+			state.set(key, !current);
+		}
+	}, [action, state]);
+}
+//#endregion
 //#region src/Slider.tsx
 /**
-* Range input. State: internal `value` mirrors props.value if present
-* (otherwise uncontrolled); clamps to [min, max].
+* Range input. Three operating modes:
+*
+*  1. **Uncontrolled** (no `value`, no `stateKey`): the slider owns
+*     its value as local React state. The onChange mutates that state.
+*     Use this when nothing else needs to observe the value.
+*
+*  2. **Controlled by `value` prop**: the slider is read-only —
+*     user input is ignored because there is no `onChange` callback
+*     wired by the deterministic renderer. Use this for "static"
+*     sliders in artifacts. (If you want fully interactive control,
+*     use mode 3.)
+*
+*  3. **Bound to PlaygroundState via `stateKey`**: the slider reads
+*     its value from the nearest Provider's store (initial: either
+*     the store's current value OR `value` prop, whichever is
+*     present; the live store wins when bound). On change, the
+*     slider writes to the store. Other components can subscribe
+*     to the same key.
+*
+* In all modes the displayed value is clamped to `[min, max]`. NaN
+* inputs clamp to `min`. When `min === max` the input is disabled.
 */
-function Slider({ min, max, value, step = 1, label }) {
+function Slider({ min, max, value, step = 1, label, stateKey }) {
 	const [internal, setInternal] = React.useState(() => clamp(value ?? min, min, max));
+	const bound = useBoundValueOrUndefined(stateKey, internal);
 	const controlled = value !== void 0;
-	const current = controlled ? clamp(value, min, max) : internal;
+	const current = stateKey !== void 0 && bound ? clamp(bound[0], min, max) : controlled ? clamp(value, min, max) : internal;
 	const trackStyle = {
 		display: "flex",
 		flexDirection: "column",
@@ -179,7 +449,8 @@ function Slider({ min, max, value, step = 1, label }) {
 				"aria-label": label,
 				onChange: (e) => {
 					const next = Number(e.currentTarget.value);
-					if (!controlled) setInternal(next);
+					if (stateKey !== void 0 && bound) bound[1](next);
+					else if (!controlled) setInternal(next);
 				},
 				style: inputStyle
 			}), /* @__PURE__ */ jsx("span", {
@@ -604,35 +875,315 @@ function List({ items, ordered, children }) {
 	}));
 }
 //#endregion
-//#region src/registry.ts
+//#region src/stateHelpers.ts
+function diffSnapshots(prev, next) {
+	const added = [];
+	const changed = [];
+	const removed = [];
+	const prevKeys = Object.keys(prev);
+	const nextKeys = Object.keys(next);
+	const prevSet = new Set(prevKeys);
+	const nextSet = new Set(nextKeys);
+	for (const k of nextKeys) {
+		if (!prevSet.has(k)) {
+			added.push(k);
+			continue;
+		}
+		if (!Object.is(prev[k], next[k])) changed.push(k);
+	}
+	for (const k of prevKeys) if (!nextSet.has(k)) removed.push(k);
+	added.sort();
+	changed.sort();
+	removed.sort();
+	if (added.length === 0 && changed.length === 0 && removed.length === 0) return null;
+	return {
+		added,
+		changed,
+		removed
+	};
+}
+/**
+* Convenience: take snapshots of both stores and diff them. Returns
+* `null` when equal. Useful in tests and debug endpoints.
+*/
+function diffState(_a, _b, prev, next) {
+	return diffSnapshots(prev ?? _a.snapshot(), next ?? _b.snapshot());
+}
+/**
+* Validate a state-key string. Returns `null` on success, or a
+* human-readable error message on failure. The rules:
+*
+*  - 1..64 characters
+*  - No whitespace
+*  - Only alphanumerics, dots, dashes, underscores
+*  - Must start with an alphabetic character (so a parser can
+*    safely infer `<Slider stateKey="...">` from a body without
+*    swallowing accidental numeric keys).
+*
+* Note: keys like `with/slash` or `with spaces` are rejected because
+* the schema-driven body parser uses them as attribute names —
+* a key with weird characters would break the round-trip.
+*/
+function validateStateKey(key) {
+	if (key.length === 0) return "stateKey must be a non-empty string";
+	if (key.length > 64) return "stateKey must be at most 64 characters";
+	if (/\s/.test(key)) return "stateKey must not contain whitespace";
+	if (!/^[A-Za-z][A-Za-z0-9._-]*$/.test(key)) return "stateKey contains forbidden characters (allowed: A-Z, a-z, 0-9, dot, dash, underscore; must start with a letter)";
+	return null;
+}
+/**
+* Remove every key from the store, firing subscribers with `undefined`.
+* After this call, `state.snapshot()` is `{}`.
+*/
+function clearState(state) {
+	for (const k of Object.keys(state.snapshot())) state.set(k, void 0);
+}
+function dumpState(state) {
+	const snap = state.snapshot();
+	const envelope = {
+		version: 1,
+		keys: Object.keys(snap).sort(),
+		values: { ...snap }
+	};
+	return JSON.stringify(envelope, null, 2);
+}
+/**
+* Apply multiple `set` calls as a single atomic batch. Each
+* subscriber sees only the LAST value written to its key in this
+* batch. The store still batches subscriber fires via the microtask
+* scheduler — `batch` does not flush synchronously, it only ensures
+* that within the batch, repeated `set` calls to the same key don't
+* queue redundant fires.
+*
+* Useful for: undo/redo, multi-field form commits, hydrated state
+* restore where you want each subscriber to fire exactly once with
+* the final value.
+*
+* @example
+*   batch(state, (s) => {
+*     s.set('x', 1);
+*     s.set('y', 2);
+*     s.set('x', 3); // overwrites; subscriber sees only 3
+*   });
+*/
+function batch(state, fn) {
+	return state._batch(() => fn(state));
+}
+//#endregion
+//#region src/ShowSource.tsx
 /**
-* Map of PascalCase component name to React component. Use this when
-* you have a renderer that walks an AST and needs to pick an
-* implementation at runtime:
+* Render-prop component that shows a toggle-able raw-source panel.
+* Consumer controls the trigger UI via a children render prop.
 *
-*   const C = componentMap[tagName];
-*   if (C) el = <C {...props}>{children}</C>;
+* Design notes:
+* - Render-prop pattern (not props.children-as-trigger) because the
+*   trigger UI varies wildly across consumers (button, link, icon,
+*   inline text). The consumer gets `(toggle, showing)` and decides
+*   what to render.
+* - The source panel is a `<pre>` with `<code>` inside. Plain-text;
+*   no syntax highlighting (avoiding a 50KB highlight.js dep).
+*   Consumers who need highlighting can compose with their own
+*   syntax-highlighter.
+* - The panel is rendered INLINE (not in a portal/tooltip) so the
+*   toggle's visual feedback is immediate.
+*
+* @packageDocumentation
+*/
+/**
+* Toggle button + expandable source panel. The trigger UI is the
+* consumer's choice; the panel is plain `<pre><code>`.
+*/
+function ShowSource(props) {
+	const { body, language, children } = props;
+	const [showing, setShowing] = React.useState(false);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [children(React.useCallback(() => {
+		setShowing((s) => !s);
+	}, []), showing), showing ? /* @__PURE__ */ jsx("pre", {
+		"data-pgx": "ShowSource",
+		"data-language": language ?? "text",
+		style: {
+			background: "#0f172a",
+			color: "#e2e8f0",
+			padding: "12px",
+			borderRadius: "6px",
+			overflowX: "auto",
+			fontFamily: "ui-monospace, Menlo, monospace",
+			fontSize: "12px",
+			lineHeight: 1.5,
+			margin: "8px 0 0",
+			maxHeight: "320px",
+			whiteSpace: "pre"
+		},
+		children: /* @__PURE__ */ jsx("code", { children: body })
+	}) : null] });
+}
+//#endregion
+//#region src/ArtifactErrorBoundary.tsx
+/**
+* Error boundary for rendered artifacts. Catches render-time errors
+* (malformed body, throw from a component, etc.) and shows a recoverable
+* fallback. Without this, a single bad artifact blanks the student's
+* whole page.
 *
-* Keys mirror `DEFAULT_REGISTRY.list()`.
+* Design notes:
+* - Uses React's class-component error boundary API (the only
+*   first-class option in React 18/19).
+* - Default fallback shows the error message + an optional "Show source"
+*   toggle that reveals the raw body. Consumer can override with
+*   `fallback` for custom UX.
+* - `onError` fires before the fallback renders so consumers can log
+*   to Sentry / Datadog / etc.
 *
-* Type note: components vary in their props shape, so the map is
-* typed permissively (`Record<string, ComponentType<any>>`). Each
-* individual export above is still strictly typed.
+* @packageDocumentation
+*/
+/**
+* Default fallback panel. Renders the error message and, if `body` is
+* provided, a ShowSource toggle. Designed to be a calm, recoverable
+* surface — not a stack-trace dump that panics users.
 */
-const componentMap = {
+function DefaultFallback({ error, body, language, kind }) {
+	return /* @__PURE__ */ jsxs("div", {
+		role: "alert",
+		"data-pgx": "ArtifactErrorBoundary",
+		"data-pgx-kind": kind,
+		style: {
+			border: "1px solid #fca5a5",
+			background: "#fef2f2",
+			color: "#7f1d1d",
+			borderRadius: "8px",
+			padding: "12px 16px",
+			fontFamily: "ui-sans-serif, system-ui, sans-serif",
+			fontSize: "14px",
+			maxWidth: "720px",
+			margin: "12px 0"
+		},
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				style: {
+					fontWeight: 600,
+					marginBottom: "6px"
+				},
+				children: kind ? `${kind} artifact failed to render` : "Artifact failed to render"
+			}),
+			/* @__PURE__ */ jsx("code", {
+				"data-pgx": "error-message",
+				style: {
+					display: "block",
+					fontFamily: "ui-monospace, Menlo, monospace",
+					fontSize: "12px",
+					background: "rgba(0,0,0,0.04)",
+					padding: "6px 8px",
+					borderRadius: "4px",
+					whiteSpace: "pre-wrap",
+					wordBreak: "break-word"
+				},
+				children: error.message
+			}),
+			body !== void 0 ? /* @__PURE__ */ jsx("div", {
+				style: { marginTop: "8px" },
+				children: /* @__PURE__ */ jsx(ShowSource, {
+					body,
+					language,
+					children: (toggle, showing) => /* @__PURE__ */ jsx("button", {
+						type: "button",
+						onClick: toggle,
+						"data-pgx": "show-source-toggle",
+						style: {
+							background: "transparent",
+							border: "1px solid #fca5a5",
+							color: "#7f1d1d",
+							padding: "4px 10px",
+							fontSize: "12px",
+							borderRadius: "4px",
+							cursor: "pointer"
+						},
+						children: showing ? "Hide source" : "Show source"
+					})
+				})
+			}) : null
+		]
+	});
+}
+/**
+* Error boundary. Catches render-time errors in `children` and shows
+* the fallback. The error state is reset on prop change of `children`
+* (or explicit `resetKey` bump) so the consumer can recover by
+* re-rendering.
+*/
+var ArtifactErrorBoundary = class extends React.Component {
+	state = { error: null };
+	static getDerivedStateFromError(error) {
+		return { error };
+	}
+	componentDidCatch(error, info) {
+		if (this.props.onError) try {
+			this.props.onError(error, { componentStack: info.componentStack ?? "" });
+		} catch {}
+	}
+	render() {
+		const { error } = this.state;
+		if (error === null) return this.props.children;
+		const { fallback, body, language, kind } = this.props;
+		if (typeof fallback === "function") return fallback(error);
+		if (fallback !== void 0) return fallback;
+		return /* @__PURE__ */ jsx(DefaultFallback, {
+			error,
+			body,
+			language,
+			kind
+		});
+	}
+};
+//#endregion
+//#region src/createRegistry.ts
+const DEFAULT_REGISTRY = Object.freeze({
 	Button,
-	TextField,
-	Slider,
+	Card,
 	Chart,
-	Container,
 	Code,
+	Container,
 	Heading,
-	Text,
+	List,
+	Slider,
 	Stepper,
-	Card,
-	List
-};
+	Text,
+	TextField
+});
+/**
+* The full default registry (Button, Card, Chart, Code, Container,
+* Heading, List, Slider, Stepper, Text, TextField). Frozen. Use
+* `createRegistry(overrides)` to extend.
+*/
+const componentMap = DEFAULT_REGISTRY;
+/**
+* Build a new registry by merging the defaults with caller-supplied
+* overrides. The returned map is frozen (Object.freeze) to prevent
+* post-hoc mutation that would surprise concurrent renders.
+*
+* **Lowercase HTML tags are NOT in this map.** The renderer handles
+* `div`, `span`, etc. as React intrinsic elements separately. Calling
+* `createRegistry({ div: StubDiv })` will NOT override the renderer
+* for `<div>` (the renderer uses the lowercase lookup path first).
+*
+* @example
+* ```ts
+* const map = createRegistry({
+*   MathExpression: MathExpressionComponent,
+*   LatexBlock: LatexBlockComponent,
+* });
+* ```
+*/
+function createRegistry(overrides) {
+	const merged = { ...DEFAULT_REGISTRY };
+	for (const key of Object.keys(overrides)) {
+		const value = overrides[key];
+		if (value === void 0) continue;
+		if (key[0] !== key[0].toUpperCase()) continue;
+		merged[key] = value;
+	}
+	return Object.freeze(merged);
+}
 //#endregion
-export { Button, Card, Chart, Code, Container, Heading, List, Slider, Stepper, Text, TextField, componentMap };
+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 };
 
 //# sourceMappingURL=index.mjs.map