Update Examples and update docusaurus (#10)

* feat: add `useLocalStore` hook for component-scoped reactive stores with tests and documentation

* feat: add `useLocalStore` hook for component-scoped reactive stores with tests and documentation

* feat: add `withHistory`, `devtools`, and `subscribeKey` utilities for enhanced state management

- `withHistory`: Adds undo/redo functionality to stores with a snapshot stack.
- `devtools`: Integrates stores with Redux DevTools for debugging and time travel.
- `subscribeKey`: Enables subscribing to changes on specific properties in stores.

* docs: update architecture and documentation for `useLocalStore` and utilities

- Added `useLocalStore` details to architecture and docs.
- Expanded file structures to include `devtools`, `subscribeKey`, and `withHistory` utilities.
- Refined examples and tutorials for consistency and clarity.

* refactor(utils): improve state handling with try-finally and enhance safety checks

- Wrapped state application logic in `try-finally` blocks to ensure cleanup (`isTimeTraveling`, `paused`, `hydrating`) regardless of errors.
- Improved safety by skipping operations during invalid states (e.g., `hydration`/`disposed` in `persist`).
- Added `shallowEqual` utility export to utils index.

* test(utils): add extensive test coverage for edge cases in utilities

- Added additional tests for `devtools` to cover time travel, error handling, and message payloads.
- Extended test cases for `persist` to handle null states, invalid envelopes, and unsubscribe behavior.
- Introduced more cases for `subscribeKey` with various data types and subscriber behavior.
- Enhanced `shallowEqual` tests to include edge cases such as array vs object comparison and handling undefined values.

* refactor(examples): restructure and modernize examples for clarity and modularity

* feat(demos): integrate interactive examples and static demos into documentation site

- Added `demos:build` script to generate static demos for the documentation site.
- Updated `DemoContainer` component for improved tab structure and usability.
- Introduced a new `Examples` page in the docs with an iframe for demo previews.
- Enhanced fallback in `PostStore` with static data for cases when the API is unavailable.

Author: codeBelt

.gitignore

@@ -37,3 +37,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 website/build
 website/.docusaurus
 website/.cache-loader
+website/static/demos

bun.lock

@@ -11,6 +11,7 @@
   "dependencies": {
     "@codebelt/classy-store": "file:../..",
     "bun-plugin-tailwind": "0.1.2",
+    "prism-react-renderer": "^2.4.1",
     "proxy-compare": "3.0.1",
     "react": "19.2.4",
     "react-dom": "19.2.4",

examples/rendering/bun.lock

@@ -1,101 +1,41 @@
 // This component must be the top-most import in this file!
-import {ReactScan} from './ReactScan';
+import {ReactScan} from './components/ReactScan';
 import './index.css';
-import {useEffect, useState} from 'react';
-import {AsyncDemo} from './AsyncDemo';
-import {CollectionsDemo} from './CollectionsDemo';
-import {PersistPage} from './PersistPage';
-import {ReactiveFundamentalsDemo} from './ReactiveFundamentalsDemo';
-import {StructuralSharingDemo} from './StructuralSharingDemo';
-
-// ── Hash Router ─────────────────────────────────────────────────────────────
-
-function getRoute(): string {
-  const hash = globalThis.location?.hash ?? '';
-  return hash.replace(/^#/, '') || '/';
-}
-
-function useHashRoute() {
-  const [route, setRoute] = useState(getRoute);
-
-  useEffect(() => {
-    const handler = () => setRoute(getRoute());
-    globalThis.addEventListener('hashchange', handler);
-    return () => globalThis.removeEventListener('hashchange', handler);
-  }, []);
-
-  return route;
-}
-
-// ── Navigation ──────────────────────────────────────────────────────────────
-
-function NavBar({route}: {route: string}) {
-  const links = [
-    {href: '#/', label: 'Reactivity', active: route === '/'},
-    {href: '#/persist', label: 'Persist', active: route === '/persist'},
-  ];
-
-  return (
-    <nav className="flex items-center justify-center gap-1 mb-8">
-      {links.map((link) => (
-        <a
-          key={link.href}
-          href={link.href}
-          className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${
-            link.active
-              ? 'bg-zinc-800 text-zinc-100'
-              : 'text-zinc-500 hover:text-zinc-300 hover:bg-zinc-800/50'
-          }`}
-        >
-          {link.label}
-        </a>
-      ))}
-    </nav>
-  );
-}
-
-// ── Reactivity Demos Page ───────────────────────────────────────────────────
-
-function ReactivityPage() {
-  return (
-    <>
-      <header className="text-center mb-12">
-        <h1 className="text-4xl sm:text-5xl font-bold mb-3 bg-linear-to-r from-indigo-400 to-violet-400 bg-clip-text text-transparent">
-          @codebelt/classy-store
-        </h1>
-        <p className="text-zinc-400 max-w-xl mx-auto">
-          Class-based reactive state for React. Watch the render badges to see
-          exactly when each component re-renders.
-        </p>
-      </header>
-
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-6 mb-6">
-        <ReactiveFundamentalsDemo />
-        <AsyncDemo />
-      </div>
-
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-6 mb-6">
-        <CollectionsDemo />
-      </div>
-
-      <div className="grid grid-cols-1 gap-6">
-        <StructuralSharingDemo />
-      </div>
-    </>
-  );
-}
-
-// ── App ─────────────────────────────────────────────────────────────────────
+import {Layout} from './components/Layout';
+import {useHashRoute} from './hooks/useHashRoute';
+import {CollectionsPage} from './pages/CollectionsPage';
+import {DevtoolsPage} from './pages/DevtoolsPage';
+import {HistoryPage} from './pages/HistoryPage';
+import {OverviewPage} from './pages/OverviewPage';
+import {PersistPage} from './pages/PersistPage';
+import {ReactivityPage} from './pages/ReactivityPage';
+import {ShallowEqualPage} from './pages/ShallowEqualPage';
+import {SnapshotsPage} from './pages/SnapshotsPage';
+import {SubscribeKeyPage} from './pages/SubscribeKeyPage';
+import {UseLocalStorePage} from './pages/UseLocalStorePage';
+
+const routes: Record<string, React.ComponentType> = {
+  '/': OverviewPage,
+  '/reactivity': ReactivityPage,
+  '/collections': CollectionsPage,
+  '/snapshots': SnapshotsPage,
+  '/use-local-store': UseLocalStorePage,
+  '/persist': PersistPage,
+  '/history': HistoryPage,
+  '/devtools': DevtoolsPage,
+  '/subscribe-key': SubscribeKeyPage,
+  '/shallow-equal': ShallowEqualPage,
+};
 
 export function App() {
   const route = useHashRoute();
+  const Page = routes[route] ?? OverviewPage;
 
   return (
-    <div className="max-w-6xl mx-auto px-6 py-12">
+    <Layout route={route}>
       <ReactScan />
-      <NavBar route={route} />
-      {route === '/persist' ? <PersistPage /> : <ReactivityPage />}
-    </div>
+      <Page />
+    </Layout>
   );
 }
 

examples/rendering/package.json

@@ -0,0 +1,18 @@
+export function ApiSignature({
+  importPath,
+  signature,
+}: {
+  importPath: string;
+  signature: string;
+}) {
+  return (
+    <div className="rounded-lg bg-zinc-900 border border-zinc-800 px-4 py-3 mb-6 font-mono text-xs">
+      <div className="text-zinc-500">
+        import {'{'}{' '}
+        <span className="text-indigo-400">{signature.split('(')[0]}</span> {'}'}{' '}
+        from <span className="text-emerald-400">'{importPath}'</span>
+      </div>
+      <div className="text-zinc-300 mt-1">{signature}</div>
+    </div>
+  );
+}

examples/rendering/src/App.tsx

@@ -0,0 +1,40 @@
+import type {ButtonHTMLAttributes, ReactNode} from 'react';
+
+type Variant = 'primary' | 'secondary' | 'danger' | 'ghost';
+type Size = 'sm' | 'md';
+
+const variantStyles: Record<Variant, string> = {
+  primary: 'bg-indigo-500 text-white hover:bg-indigo-400',
+  secondary: 'bg-zinc-700 text-zinc-300 hover:bg-zinc-600',
+  danger: 'bg-rose-600 text-white hover:bg-rose-500',
+  ghost:
+    'bg-transparent text-zinc-400 hover:text-zinc-200 hover:bg-zinc-800/50',
+};
+
+const sizeStyles: Record<Size, string> = {
+  sm: 'px-2.5 py-1 text-xs',
+  md: 'px-3 py-1.5 text-sm',
+};
+
+export function Button({
+  variant = 'primary',
+  size = 'md',
+  children,
+  className = '',
+  ...props
+}: {
+  variant?: Variant;
+  size?: Size;
+  children: ReactNode;
+  className?: string;
+} & ButtonHTMLAttributes<HTMLButtonElement>) {
+  return (
+    <button
+      type="button"
+      className={`rounded-lg font-medium transition-colors cursor-pointer ${variantStyles[variant]} ${sizeStyles[size]} ${className}`}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}

examples/rendering/src/PersistPage.tsx

@@ -0,0 +1,41 @@
+import {Highlight, themes} from 'prism-react-renderer';
+
+export function CodeBlock({
+  code,
+  language = 'tsx',
+  title,
+  compact = false,
+}: {
+  code: string;
+  language?: string;
+  title?: string;
+  compact?: boolean;
+}) {
+  const trimmed = code.trim();
+
+  return (
+    <div className="rounded-lg overflow-hidden border border-zinc-800 bg-zinc-950">
+      {title && (
+        <div className="px-3 py-1.5 bg-zinc-900 border-b border-zinc-800 text-xs text-zinc-400 font-mono">
+          {title}
+        </div>
+      )}
+      <Highlight theme={themes.nightOwl} code={trimmed} language={language}>
+        {({tokens, getLineProps, getTokenProps}) => (
+          <pre
+            className={`overflow-x-auto font-mono text-xs leading-relaxed ${compact ? 'p-3' : 'p-4'}`}
+            style={{background: 'transparent'}}
+          >
+            {tokens.map((line, i) => (
+              <div key={i} {...getLineProps({line})}>
+                {line.map((token, key) => (
+                  <span key={key} {...getTokenProps({token})} />
+                ))}
+              </div>
+            ))}
+          </pre>
+        )}
+      </Highlight>
+    </div>
+  );
+}

examples/rendering/src/components/ApiSignature.tsx

@@ -0,0 +1,76 @@
+import {type ReactNode, useState} from 'react';
+import {CodeBlock} from './CodeBlock';
+
+interface CodeTab {
+  label: string;
+  code: string;
+  language?: string;
+}
+
+export function DemoContainer({
+  title,
+  description,
+  children,
+  codeTabs,
+}: {
+  title: string;
+  description?: string;
+  children: ReactNode;
+  codeTabs?: CodeTab[];
+}) {
+  const [activeTab, setActiveTab] = useState(0);
+
+  const allTabs = [
+    {label: 'Demo', type: 'demo' as const},
+    ...(codeTabs ?? []).map((t) => ({...t, type: 'code' as const})),
+  ];
+
+  return (
+    <div className="bg-zinc-900 border border-zinc-800 rounded-xl overflow-hidden">
+      {/* Header */}
+      <div className="px-6 pt-5 pb-0">
+        <h3 className="text-lg font-semibold text-zinc-100 mb-1">{title}</h3>
+        {description && (
+          <p className="text-sm text-zinc-400 mb-0">{description}</p>
+        )}
+      </div>
+
+      {/* Tabs */}
+      <div className="flex border-b border-zinc-800 px-6 mt-4">
+        {allTabs.map((tab, i) => (
+          <button
+            key={tab.label}
+            type="button"
+            onClick={() => setActiveTab(i)}
+            className={`px-3 py-2 text-xs font-medium transition-colors cursor-pointer -mb-px ${
+              activeTab === i
+                ? 'text-zinc-100 border-b-2 border-indigo-400'
+                : 'text-zinc-500 hover:text-zinc-300'
+            }`}
+          >
+            {tab.label}
+          </button>
+        ))}
+      </div>
+
+      {/* Content */}
+      {activeTab === 0 ? (
+        <div className="p-6">{children}</div>
+      ) : (
+        (() => {
+          const codeTab = codeTabs?.[activeTab - 1];
+          if (!codeTab) return null;
+          return (
+            <div className="max-h-[500px] overflow-y-auto bg-zinc-950">
+              <CodeBlock
+                code={codeTab.code}
+                language={codeTab.language ?? 'tsx'}
+                compact={true}
+              />
+            </div>
+          );
+        })()
+      )}
+    </div>
+  );
+}