@assistant-ui/mcp-docs-server 0.2.3 → 0.3.0

package/.docs/organized/code-examples/with-store.md

@@ -1,679 +0,0 @@
-# Example: with-store
-
-## app/globals.css
-
-```css
-@import "tailwindcss";
-
-:root {
-  --background: #ffffff;
-  --foreground: #171717;
-}
-
-@theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --font-sans: var(--font-geist-sans);
-  --font-mono: var(--font-geist-mono);
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    --background: #0a0a0a;
-    --foreground: #ededed;
-  }
-}
-
-body {
-  background: var(--background);
-  color: var(--foreground);
-  font-family: Arial, Helvetica, sans-serif;
-}
-
-```
-
-## app/layout.tsx
-
-```tsx
-import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
-import "./globals.css";
-
-const geistSans = Geist({
-  variable: "--font-geist-sans",
-  subsets: ["latin"],
-});
-
-const geistMono = Geist_Mono({
-  variable: "--font-geist-mono",
-  subsets: ["latin"],
-});
-
-export const metadata: Metadata = {
-  title: "Create Next App",
-  description: "Generated by create next app",
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <html lang="en">
-      <body
-        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
-      >
-        {children}
-      </body>
-    </html>
-  );
-}
-
-```
-
-## app/page.tsx
-
-```tsx
-import { ExampleApp } from "@/lib/example-app";
-
-export default function Home() {
-  return (
-    <div className="min-h-screen bg-linear-to-br from-gray-50 to-gray-100 p-8 dark:from-gray-900 dark:to-gray-800">
-      <div className="mx-auto max-w-4xl">
-        <div className="mb-8">
-          <h1 className="mb-2 text-4xl font-bold text-gray-900 dark:text-white">
-            @assistant-ui/store Example
-          </h1>
-          <p className="text-lg text-gray-600 dark:text-gray-400">
-            Demonstrating tap-based state management with scopes, lists, and
-            providers
-          </p>
-        </div>
-
-        <ExampleApp />
-      </div>
-    </div>
-  );
-}
-
-```
-
-## lib/example-app.tsx
-
-```tsx
-"use client";
-
-import { useState } from "react";
-import {
-  useAui,
-  AuiProvider,
-  AuiConfig,
-  useAuiState,
-  useAuiEvent,
-} from "@assistant-ui/store";
-import { FooList, FooListResource } from "./store/foo-store";
-
-/**
- * Single Foo component - displays and allows editing a single foo
- */
-const Foo = () => {
-  const aui = useAui();
-  const fooId = useAuiState((s) => s.foo.id);
-  const fooBar = useAuiState((s) => s.foo.bar);
-
-  // Each foo logs its own events - only receives events from THIS foo instance
-  useAuiEvent("foo.updated", (payload) => {
-    console.log(`[${fooId}] Updated to: ${payload.newValue}`);
-  });
-
-  const handleUpdate = () => {
-    aui.foo().updateBar(`Updated at ${new Date().toLocaleTimeString()}`);
-  };
-
-  return (
-    <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-md transition-shadow hover:shadow-lg dark:border-gray-700 dark:bg-gray-800">
-      <div className="space-y-3">
-        <div className="flex items-center gap-2">
-          <span className="text-sm font-semibold text-gray-500 dark:text-gray-400">
-            ID:
-          </span>
-          <span className="font-mono text-sm text-gray-900 dark:text-white">
-            {fooId}
-          </span>
-        </div>
-        <div className="flex items-center gap-2">
-          <span className="text-sm font-semibold text-gray-500 dark:text-gray-400">
-            Value:
-          </span>
-          <span className="text-gray-900 dark:text-white">{fooBar}</span>
-        </div>
-        <div className="mt-2 flex gap-2">
-          <button
-            type="button"
-            onClick={handleUpdate}
-            className="flex-1 rounded-md bg-blue-600 px-4 py-2 font-medium text-white transition-colors hover:bg-blue-700 focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:outline-none dark:focus:ring-offset-gray-800"
-          >
-            Update
-          </button>
-          <button
-            type="button"
-            onClick={() => aui.foo().remove()}
-            className="rounded-md bg-red-600 px-4 py-2 font-medium text-white transition-colors hover:bg-red-700 focus:ring-2 focus:ring-red-500 focus:ring-offset-2 focus:outline-none dark:focus:ring-offset-gray-800"
-          >
-            Delete
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-const FooListLength = () => {
-  const fooListLength = useAuiState((s) => s.fooList.foos.length);
-  return (
-    <span className="text-gray-500 dark:text-gray-400">
-      ({fooListLength} items)
-    </span>
-  );
-};
-
-const AddFooButton = () => {
-  const aui = useAui();
-  return (
-    <button
-      type="button"
-      onClick={() => aui.fooList().addFoo()}
-      className="rounded-md bg-green-600 px-4 py-2 font-medium text-white transition-colors hover:bg-green-700 focus:ring-2 focus:ring-green-500 focus:ring-offset-2 focus:outline-none dark:focus:ring-offset-gray-800"
-    >
-      Add New
-    </button>
-  );
-};
-
-type EventLogEntry = {
-  id: number;
-  event: string;
-  payload: unknown;
-  timestamp: Date;
-};
-
-let idCounter = 0;
-/**
- * EventLog component - demonstrates event subscription
- */
-const EventLog = () => {
-  const [logs, setLogs] = useState<EventLogEntry[]>([]);
-
-  // Subscribe to all events using the wildcard selector
-  useAuiEvent("*", (data) => {
-    setLogs((prev) => [
-      {
-        id: ++idCounter,
-        event: data.event,
-        payload: data.payload,
-        timestamp: new Date(),
-      },
-      ...prev.slice(0, 9), // Keep last 10 entries
-    ]);
-  });
-
-  return (
-    <div className="rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-700 dark:bg-gray-800">
-      <h3 className="mb-3 font-semibold text-gray-900 dark:text-white">
-        Event Log
-      </h3>
-      <div className="max-h-48 space-y-2 overflow-y-auto">
-        {logs.length === 0 ? (
-          <p className="text-sm text-gray-500 dark:text-gray-400">
-            No events yet. Try updating or deleting a foo.
-          </p>
-        ) : (
-          logs.map((log) => (
-            <div
-              key={log.id}
-              className="rounded border border-gray-100 bg-gray-50 p-2 font-mono text-xs dark:border-gray-600 dark:bg-gray-700"
-            >
-              <span className="font-semibold text-blue-600 dark:text-blue-400">
-                {log.event}
-              </span>
-              <span className="ml-2 text-gray-600 dark:text-gray-300">
-                {JSON.stringify(log.payload)}
-              </span>
-              <span className="ml-2 text-gray-400 dark:text-gray-500">
-                {log.timestamp.toLocaleTimeString()}
-              </span>
-            </div>
-          ))
-        )}
-      </div>
-    </div>
-  );
-};
-
-/**
- * Example App - demonstrates the store with styled components
- *
- * Note: The fooList scope is also registered in foo-scope.ts as a default,
- * but we're explicitly passing it here for clarity in the example.
- */
-const config = AuiConfig({
-  fooList: FooListResource({ initialValues: true }),
-});
-
-export const ExampleApp = () => {
-  return (
-    <AuiProvider config={config}>
-      <div className="space-y-6">
-        <div className="rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-700 dark:bg-gray-800">
-          <div className="flex items-center justify-between">
-            <h2 className="text-xl font-semibold text-gray-900 dark:text-white">
-              Foo List <FooListLength />
-            </h2>
-            <AddFooButton />
-          </div>
-          <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">
-            Each item is rendered in its own FooProvider with scoped access
-          </p>
-        </div>
-        <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
-          <FooList>{() => <Foo />}</FooList>
-        </div>
-        <EventLog />
-      </div>
-    </AuiProvider>
-  );
-};
-
-```
-
-## lib/store/foo-scope.ts
-
-```typescript
-import "@assistant-ui/store";
-
-type FooState = { id: string; bar: string };
-type FooMethods = {
-  getState: () => FooState;
-  updateBar: (newBar: string) => void;
-  remove: () => void;
-};
-type FooMeta = {
-  source: "fooList";
-  query: { index: number } | { key: string };
-};
-type FooEvents = {
-  "foo.updated": { id: string; newValue: string };
-  "foo.removed": { id: string };
-};
-
-type FooListState = { foos: FooState[] };
-type FooListMethods = {
-  getState: () => FooListState;
-  foo: (lookup: FooMeta["query"]) => FooMethods;
-  addFoo: () => void;
-};
-type FooListEvents = {
-  "fooList.added": { id: string };
-};
-
-declare module "@assistant-ui/store" {
-  interface ScopeRegistry {
-    foo: {
-      methods: FooMethods;
-      meta: FooMeta;
-      events: FooEvents;
-    };
-    fooList: {
-      methods: FooListMethods;
-      events: FooListEvents;
-    };
-  }
-}
-
-```
-
-## lib/store/foo-store.tsx
-
-```tsx
-"use client";
-
-import "./foo-scope";
-
-import { type ReactNode, useMemo, useState } from "react";
-import { resource } from "@assistant-ui/tap";
-import {
-  useAui,
-  useAuiState,
-  AuiProvider,
-  AuiConfig,
-  useClientList,
-  Derived,
-  useAssistantEmit,
-  RenderChildrenWithAccessor,
-  type ClientOutput,
-} from "@assistant-ui/store";
-
-type FooData = { id: string; bar: string };
-
-const useFooItemResource = ({
-  getInitialData,
-  remove,
-}: useClientList.ResourceProps<FooData>): ClientOutput<"foo"> => {
-  const emit = useAssistantEmit();
-
-  const [state, setState] = useState<FooData>(getInitialData);
-
-  const updateBar = (newBar: string) => {
-    setState({ ...state, bar: newBar });
-    emit("foo.updated", { id: state.id, newValue: newBar });
-  };
-
-  const handleRemove = () => {
-    emit("foo.removed", { id: state.id });
-    remove();
-  };
-
-  return {
-    getState: () => state,
-    updateBar,
-    remove: handleRemove,
-  };
-};
-
-export const FooItemResource = resource(useFooItemResource);
-
-let counter = 3;
-const useFooListResource = ({
-  initialValues,
-}: {
-  initialValues: boolean;
-}): ClientOutput<"fooList"> => {
-  const emit = useAssistantEmit();
-
-  const foos = useClientList({
-    initialValues: initialValues
-      ? [
-          { id: "foo-1", bar: "First Foo" },
-          { id: "foo-2", bar: "Second Foo" },
-          { id: "foo-3", bar: "Third Foo" },
-        ]
-      : [],
-    getKey: (foo) => foo.id,
-    resource: FooItemResource,
-  });
-
-  const addFoo = () => {
-    const id = `foo-${++counter}`;
-    foos.add({ id: id, bar: `New Foo` });
-    emit("fooList.added", { id: id });
-  };
-
-  const state = useMemo(() => ({ foos: foos.state }), [foos.state]);
-
-  return {
-    getState: () => state,
-    foo: foos.get,
-    addFoo,
-  };
-};
-
-export const FooListResource = resource(useFooListResource);
-
-const FooProvider = ({
-  index,
-  children,
-}: {
-  index: number;
-  children: ReactNode;
-}) => {
-  const aui = useAui();
-  const config = AuiConfig({
-    foo: Derived({
-      source: "fooList",
-      query: { index },
-      get: (aui) => aui.fooList().foo({ index }),
-    }),
-  });
-
-  return (
-    <AuiProvider extends={aui} config={config}>
-      {children}
-    </AuiProvider>
-  );
-};
-
-export const FooList = ({
-  children,
-}: {
-  children: (item: { foo: FooData }) => ReactNode;
-}) => {
-  const length = useAuiState((s) => s.fooList.foos.length);
-
-  return useMemo(
-    () =>
-      Array.from({ length }, (_, index) => (
-        <FooProvider key={index} index={index}>
-          <RenderChildrenWithAccessor
-            getItemState={(aui) => aui.fooList().foo({ index }).getState()}
-          >
-            {(getItem) =>
-              children({
-                get foo() {
-                  return getItem();
-                },
-              })
-            }
-          </RenderChildrenWithAccessor>
-        </FooProvider>
-      )),
-    [length, children],
-  );
-};
-
-```
-
-## next.config.ts
-
-```typescript
-import { withAui } from "@assistant-ui/next";
-import type { NextConfig } from "next";
-
-const nextConfig: NextConfig = {/* config options here */};
-
-export default withAui(nextConfig);
-
-```
-
-## package.json
-
-```json
-{
-  "name": "with-store",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start"
-  },
-  "dependencies": {
-    "@assistant-ui/store": "workspace:*",
-    "@assistant-ui/tap": "workspace:*",
-    "next": "^16.3.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8"
-  },
-  "devDependencies": {
-    "@assistant-ui/next": "workspace:*",
-    "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4.3.3",
-    "@types/node": "^26.2.0",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.5",
-    "postcss": "^8.5.26",
-    "tailwindcss": "^4.3.3",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^7.0.2"
-  }
-}
-
-```
-
-## README.md
-
-```markdown
-# @assistant-ui/store Example App
-
-This is a Next.js application demonstrating the `@assistant-ui/store` package.
-
-## Features Demonstrated
-
-- **Client Registry**: Module augmentation for type-safe client definitions
-- **useClientList**: Managing lists with index and key lookup
-- **useAssistantEmit**: Emitting and subscribing to scoped events
-- **Derived**: Creating derived client scopes from parent resources
-- **Provider Pattern**: Scoped access to list items via FooProvider
-- **Component Composition**: Render props pattern with components prop
-
-## Getting Started
-
-```bash
-# Install dependencies (from monorepo root)
-pnpm install
-
-# Run the development server
-cd examples/store-example
-pnpm dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) to see the example.
-
-## Project Structure
-
-- `lib/store/foo-scope.ts` - Type definitions via module augmentation:
-  - Client registry definitions (foo, fooList)
-  - State, methods, meta, and events types
-- `lib/store/foo-store.tsx` - Store implementation with:
-  - Resource implementations (FooItemResource, FooListResource)
-  - Provider component (FooProvider)
-  - FooList mapping component
-- `lib/example-app.tsx` - Example app with styled components:
-  - Foo component with update/delete actions
-  - EventLog component demonstrating event subscriptions
-  - ExampleApp with layout and styling
-- `app/page.tsx` - Main page that renders the ExampleApp
-
-## Key Concepts
-
-### Client Registry
-
-```typescript
-declare module "@assistant-ui/store" {
-  interface ScopeRegistry {
-    foo: {
-      state: { id: string; bar: string };
-      methods: {
-        getState: () => FooState;
-        updateBar: (newBar: string) => void;
-        remove: () => void;
-      };
-      meta: {
-        source: "fooList";
-        query: { index: number } | { key: string };
-      };
-      events: {
-        "foo.updated": { id: string; newValue: string };
-        "foo.removed": { id: string };
-      };
-    };
-  }
-}
-```
-
-### Resource Implementation
-
-```typescript
-const FooListResource = resource(
-  function FooListResource({ initialValues }): ClientOutput<"fooList"> {
-    const emit = useAssistantEmit();
-
-    const foos = useClientList({
-      initialValues: initialValues ? [/* ... */] : [],
-      getKey: (foo) => foo.id,
-      resource: FooItemResource,
-    });
-
-    return {
-      state: { foos: foos.state },
-      methods: {
-        getState: () => state,
-        foo: foos.get,
-        addFoo: () => { /* ... */ },
-      },
-    };
-  },
-);
-```
-
-### Provider Pattern with Derived
-
-```typescript
-const FooProvider = ({ index, children }) => {
-  const aui = useAui();
-  const config = AuiConfig({
-    foo: Derived({
-      source: "fooList",
-      query: { index },
-      get: (aui) => aui.fooList().foo({ index }),
-    }),
-  });
-  return (
-    <AuiProvider extends={aui} config={config}>
-      {children}
-    </AuiProvider>
-  );
-};
-```
-
-### Event Subscriptions
-
-```typescript
-// Subscribe to specific events within a scope
-useAuiEvent("foo.updated", (payload) => {
-  console.log(`Updated to: ${payload.newValue}`);
-});
-
-// Subscribe to all events using wildcard
-useAuiEvent("*", (data) => {
-  console.log(data.event, data.payload);
-});
-```
-
-## Learn More
-
-- [@assistant-ui/store Documentation](https://github.com/assistant-ui/assistant-ui/tree/main/packages/store)
-- [Next.js Documentation](https://nextjs.org/docs)
-
-```
-
-## tsconfig.json
-
-```json
-{
-  "extends": "@assistant-ui/x-buildutils/ts/next",
-  "compilerOptions": {
-    "paths": {
-      "@/*": ["./*"]
-    },
-    "allowJs": true,
-    "incremental": true,
-    "jsx": "preserve"
-  },
-  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
-}
-
-```
-