@assistant-ui/mcp-docs-server 0.1.23 → 0.1.25

package/.docs/raw/docs/utilities/heat-graph.mdx

@@ -0,0 +1,236 @@
+---
+title: heat-graph
+description: Headless, composable activity heatmap components for React.
+---
+
+import { HeatGraphDemo } from "@/app/heat-graph/heat-graph-demo";
+
+`heat-graph` provides headless, Radix-style primitives for building GitHub-style activity heatmap graphs.
+
+- **Composable** — Radix-style compound components you fully control
+- **Headless** — Zero styling opinions, bring your own CSS/Tailwind
+- **Tooltip built-in** — Powered by Radix Popper for positioning
+- **Customizable bucketing** — Plug in your own classification function
+
+<HeatGraphDemo />
+
+## Installation
+
+<Tabs items={["shadcn", "npm", "pnpm", "yarn"]}>
+  <Tab value="shadcn">
+    ```sh
+    npx shadcn@latest add https://r.assistant-ui.com/heat-graph
+    ```
+    This installs a pre-styled `HeatGraph` component to `components/assistant-ui/heat-graph.tsx` along with the `heat-graph` package.
+  </Tab>
+  <Tab value="npm">
+    ```sh
+    npm install heat-graph
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```sh
+    pnpm add heat-graph
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```sh
+    yarn add heat-graph
+    ```
+  </Tab>
+</Tabs>
+
+## Quick Start
+
+```tsx title="components/activity-graph.tsx"
+"use client";
+
+import * as HeatGraph from "heat-graph";
+
+const COLORS = ["#ebedf0", "#c6d7f9", "#8fb0f3", "#5888e8", "#2563eb"];
+
+export function ActivityGraph({ data }: { data: HeatGraph.DataPoint[] }) {
+  return (
+    <HeatGraph.Root data={data} weekStart="monday" colorScale={COLORS}>
+      <HeatGraph.Grid className="gap-[3px]">
+        {() => (
+          <HeatGraph.Cell className="aspect-square rounded-sm" />
+        )}
+      </HeatGraph.Grid>
+      <HeatGraph.Tooltip>
+        {({ cell }) => (
+          <div>
+            {cell.count} contributions on {cell.date.toLocaleDateString()}
+          </div>
+        )}
+      </HeatGraph.Tooltip>
+    </HeatGraph.Root>
+  );
+}
+```
+
+<Callout type="info">
+  Components using Heat Graph must be Client Components (`"use client"`), since they rely on React Context and interactivity.
+</Callout>
+
+## Anatomy
+
+```tsx
+import * as HeatGraph from "heat-graph";
+
+<HeatGraph.Root data={data} colorScale={colors}>
+
+  {/* Month labels — iterates internally, renders each label */}
+  <HeatGraph.MonthLabels>
+    {({ label, totalWeeks }) => (
+      <span style={{ left: `${(label.column / totalWeeks) * 100}%` }}>
+        {HeatGraph.MONTH_SHORT[label.month]}
+      </span>
+    )}
+  </HeatGraph.MonthLabels>
+
+  {/* Day-of-week labels — iterates internally, renders each label */}
+  <HeatGraph.DayLabels>
+    {({ label }) => (
+      <span>{HeatGraph.DAY_SHORT[label.dayOfWeek]}</span>
+    )}
+  </HeatGraph.DayLabels>
+
+  {/* Grid + Cells — iterates internally, renders each cell */}
+  <HeatGraph.Grid>
+    {() => <HeatGraph.Cell />}
+  </HeatGraph.Grid>
+
+  {/* Legend — iterates internally, renders each level */}
+  <HeatGraph.Legend>
+    {() => <HeatGraph.LegendLevel />}
+  </HeatGraph.Legend>
+
+  {/* Tooltip */}
+  <HeatGraph.Tooltip>
+    {({ cell }) => <div>{cell.count} on {cell.date.toLocaleDateString()}</div>}
+  </HeatGraph.Tooltip>
+
+</HeatGraph.Root>
+```
+
+## API Reference
+
+### Root
+
+The top-level provider. Renders a `<div>` that computes the grid layout and provides state to all children. Accepts all standard div props.
+
+| Prop         | Type                   | Default             | Description                                        |
+| ------------ | ---------------------- | ------------------- | -------------------------------------------------- |
+| `data`       | `DataPoint[]`          | required            | Array of `{ date: string \| Date, count: number }` |
+| `start`      | `string \| Date`       | 1 year before `end` | Start of the date range                            |
+| `end`        | `string \| Date`       | today               | End of the date range                              |
+| `weekStart`  | `"sunday" \| "monday"` | `"sunday"`          | First day of the week                              |
+| `classify`   | `ClassifyFn`           | `autoLevels(5)`     | Bucketing function mapping counts to levels        |
+| `colorScale` | `string[]`             | —                   | Array of colors, one per level (index 0 = lowest)  |
+
+### Grid
+
+A `<div>` with CSS Grid layout. Renders `gridTemplateColumns` and `gridTemplateRows` based on the computed data. Accepts all standard div props.
+
+Iterates over cells internally, calling the children render function for each cell. Each cell is wrapped in a context that `Cell` reads from.
+
+```ts
+type CellData = {
+  date: Date;
+  count: number;
+  level: number;
+  column: number;
+  row: number;
+};
+```
+
+### Cell
+
+A `<div>` that reads from cell context. Automatically applies:
+- Grid positioning (`gridColumn`, `gridRow`)
+- Background color from `colorScale`
+- Tooltip hover handlers
+
+Accepts all standard div props. Pass `colorScale` to override the Root-level color scale.
+
+### MonthLabels
+
+Iterates over month labels, calling the children render function for each label.
+
+```tsx
+<HeatGraph.MonthLabels>
+  {({ label, totalWeeks }) => (
+    <span style={{ left: `${(label.column / totalWeeks) * 100}%` }}>
+      {HeatGraph.MONTH_SHORT[label.month]}
+    </span>
+  )}
+</HeatGraph.MonthLabels>
+```
+
+Each label has `{ month: number, column: number }`. Use `totalWeeks` to compute label positions. Use `MONTH_SHORT[label.month]` for English labels, or format with `Intl.DateTimeFormat` for localization.
+
+### DayLabels
+
+Iterates over day-of-week labels, calling the children render function for each label.
+
+```tsx
+<HeatGraph.DayLabels>
+  {({ label }) => (
+    <span>{HeatGraph.DAY_SHORT[label.dayOfWeek]}</span>
+  )}
+</HeatGraph.DayLabels>
+```
+
+Each label has `{ dayOfWeek: number, row: number }` where `dayOfWeek` is 0=Sun..6=Sat. Use `DAY_SHORT[label.dayOfWeek]` for English labels, or format with `Intl.DateTimeFormat` for localization.
+
+### Legend
+
+Iterates over legend levels, calling the children render function for each item. Each item has `{ level: number, color: string | undefined }`.
+
+### LegendLevel
+
+A `<div>` that reads from legend item context. Automatically applies `backgroundColor` from the color scale. Use inside `Legend`.
+
+### Tooltip
+
+Renders only when a cell is hovered. Positioned by Radix Popper relative to the hovered cell. Accepts Radix Popper `Content` props (`side`, `sideOffset`, `align`, etc.).
+
+```tsx
+<HeatGraph.Tooltip side="top" sideOffset={8} className="...">
+  {({ cell }) => <div>{cell.count} contributions</div>}
+</HeatGraph.Tooltip>
+```
+
+### autoLevels(n)
+
+Default classification function. Maps counts into `n` evenly-distributed levels (0 to n-1). Level 0 is always count 0.
+
+```ts
+type ClassifyFn = (counts: number[]) => (count: number) => number;
+```
+
+To provide a custom classifier:
+
+```tsx
+const myClassify: HeatGraph.ClassifyFn = (counts) => {
+  const p75 = percentile(counts, 75);
+  return (count) => {
+    if (count === 0) return 0;
+    if (count < p75 * 0.25) return 1;
+    if (count < p75 * 0.5) return 2;
+    if (count < p75) return 3;
+    return 4;
+  };
+};
+
+<HeatGraph.Root data={data} classify={myClassify}>
+```
+
+### MONTH_SHORT
+
+English month abbreviations array: `["Jan", "Feb", ..., "Dec"]`. Index by `MonthLabel.month`.
+
+### DAY_SHORT
+
+English day abbreviations array: `["Sun", "Mon", ..., "Sat"]`. Index by `DayLabel.dayOfWeek`.

package/.docs/raw/docs/utilities/tw-shimmer.mdx

@@ -0,0 +1,211 @@
+---
+title: tw-shimmer
+description: Tailwind CSS v4 plugin for shimmer effects.
+---
+
+`tw-shimmer` is a zero-dependency Tailwind CSS v4 plugin that provides polished shimmer animations for both text and skeleton loaders. It uses sine-eased gradients with 17 carefully calculated stops and OKLCH color mixing for smooth, banding-free effects.
+
+- **CSS-only** — No JavaScript runtime, pure Tailwind utilities
+- **Text + Background** — Shimmer text or skeleton placeholders
+- **Auto-sizing** — CSS container queries for automatic width detection
+- **Customizable** — Speed, spread, angle, color, and timing
+
+See the [interactive demo](/tw-shimmer) for live examples.
+
+## Installation
+
+<Tabs items={["npm", "pnpm", "yarn"]}>
+  <Tab value="npm">
+    ```sh
+    npm install tw-shimmer
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```sh
+    pnpm add tw-shimmer
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```sh
+    yarn add tw-shimmer
+    ```
+  </Tab>
+</Tabs>
+
+Add to your CSS:
+
+```css title="app/globals.css"
+@import "tailwindcss";
+@import "tw-shimmer";
+```
+
+## Quick Start
+
+### Text Shimmer
+
+```html
+<span class="shimmer text-foreground/60">Loading...</span>
+```
+
+<Callout type="info">
+  Set a semi-transparent text color (e.g., `text-foreground/40`) for the shimmer highlight to be visible.
+</Callout>
+
+### Skeleton Loader
+
+```html
+<div class="shimmer shimmer-bg bg-muted h-4 w-48 rounded" />
+```
+
+### Skeleton Card with Auto-Sizing
+
+```html
+<div class="shimmer-container flex gap-3">
+  <div class="shimmer-bg bg-muted size-12 rounded-full" />
+  <div class="flex-1 space-y-2">
+    <div class="shimmer-bg bg-muted h-4 w-1/4 rounded" />
+    <div class="shimmer-bg bg-muted h-4 w-full rounded" />
+    <div class="shimmer-bg bg-muted h-4 w-4/5 rounded" />
+  </div>
+</div>
+```
+
+## API Reference
+
+### Core Utilities
+
+#### `shimmer`
+
+Base utility for text shimmer. Applies a gradient animation over the text foreground color.
+
+#### `shimmer-bg`
+
+Background shimmer for skeleton loaders. Applies a gradient animation over the element's background. Requires a base `bg-*` class.
+
+```html
+<div class="shimmer shimmer-bg bg-muted h-4 w-64 rounded" />
+```
+
+#### `shimmer-container`
+
+CSS-only auto-sizing helper using container queries. Sets `container-type: inline-size` and automatically derives speed and spread from the container width.
+
+```html
+<div class="shimmer-container">
+  <div class="shimmer-bg bg-muted h-4 w-full rounded" />
+</div>
+```
+
+<Callout type="warn">
+  `shimmer-container` sets `container-type: inline-size`, which prevents shrink-to-fit sizing. Not recommended for text-only containers.
+</Callout>
+
+### Customization Utilities
+
+| Utility                     | Default (text) | Default (bg) | Description                        |
+| --------------------------- | -------------- | ------------ | ---------------------------------- |
+| `shimmer-speed-{n}`         | `150`          | `1000`       | Animation speed in px/s            |
+| `shimmer-width-{n}`         | `200`          | `800`        | Container width in px for timing   |
+| `shimmer-spread-{n}`        | `6ch`          | —            | Text shimmer highlight width       |
+| `shimmer-bg-spread-{n}`     | —              | `480px`      | Background shimmer highlight width |
+| `shimmer-color-{color}`     | auto           | auto         | Highlight color (Tailwind palette) |
+| `shimmer-angle-{deg}`       | `90`           | `90`         | Sweep direction in degrees         |
+| `shimmer-duration-{ms}`     | auto           | auto         | Fixed animation duration           |
+| `shimmer-repeat-delay-{ms}` | `1000`         | `1000`       | Pause between cycles               |
+| `shimmer-invert`            | —              | —            | Invert highlight direction         |
+
+All utilities are **inheritable** — set on a parent to affect all shimmer children.
+
+### Speed and Width
+
+Speed controls how fast the shimmer moves in pixels per second. Width tells the animation how wide the container is for timing calculations.
+
+```html
+<span class="shimmer shimmer-speed-200 shimmer-width-400 text-foreground/40">
+  Fast, wide shimmer
+</span>
+```
+
+### Color
+
+Use any Tailwind color with optional opacity:
+
+```html
+<span class="shimmer shimmer-color-blue-500 text-blue-500/40">
+  Blue shimmer
+</span>
+
+<div class="shimmer shimmer-bg shimmer-color-blue-300/30 bg-muted h-4 rounded" />
+```
+
+### Angle
+
+Control the sweep direction. Default is `90deg` (vertical sweep).
+
+```html
+<div class="shimmer-container shimmer-angle-15">
+  <div class="shimmer-bg bg-muted h-4 w-full rounded" />
+</div>
+```
+
+<Callout type="warn">
+  Avoid exactly `0deg` and `180deg` — they cause extreme animation delays. Safe range: 15-75° or 105-165°.
+</Callout>
+
+### Position Hints (Angled Shimmer)
+
+For angled shimmers, use `shimmer-x-{n}` and `shimmer-y-{n}` to sync elements:
+
+```html
+<div class="shimmer-container shimmer-angle-15 flex gap-3">
+  <div class="shimmer-bg shimmer-x-20 shimmer-y-20 bg-muted size-12 rounded-full" />
+  <div class="flex-1 space-y-2">
+    <div class="shimmer-bg shimmer-x-52 shimmer-y-0 bg-muted h-4 w-24 rounded" />
+    <div class="shimmer-bg shimmer-x-52 shimmer-y-24 bg-muted h-4 w-full rounded" />
+  </div>
+</div>
+```
+
+### Repeat Delay
+
+Control the pause between animation cycles:
+
+```html
+<!-- Continuous shimmer, no pause -->
+<span class="shimmer shimmer-repeat-delay-0 text-foreground/40">
+  Always moving
+</span>
+
+<!-- Long pause between cycles -->
+<span class="shimmer shimmer-repeat-delay-3000 text-foreground/40">
+  Slow pulse
+</span>
+```
+
+## CSS Variables
+
+All values can be set via CSS variables for dynamic control:
+
+| Variable                 | Description               |
+| ------------------------ | ------------------------- |
+| `--shimmer-speed`        | Speed in px/s             |
+| `--shimmer-width`        | Track width in px         |
+| `--shimmer-spread`       | Highlight width           |
+| `--shimmer-angle`        | Sweep angle               |
+| `--shimmer-color`        | Highlight color           |
+| `--shimmer-duration`     | Override duration (ms)    |
+| `--shimmer-repeat-delay` | Pause between cycles (ms) |
+
+```tsx
+<div style={{ "--shimmer-width": containerWidth } as React.CSSProperties}>
+  <div className="shimmer shimmer-bg bg-muted h-4 w-full rounded" />
+</div>
+```
+
+## Browser Support
+
+Uses modern CSS features: `oklch()`, `color-mix()`, independent `translate` transform, and CSS Container Queries.
+
+**Supported:** Chrome 111+, Firefox 113+, Safari 16.4+
+
+Older browsers degrade gracefully — shimmer effects simply won't appear.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -38,10 +38,10 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.5.0",
     "tsx": "^4.21.0",
-    "vitest": "^4.0.18",
-    "@assistant-ui/x-buildutils": "0.0.1"
+    "vitest": "^4.1.0",
+    "@assistant-ui/x-buildutils": "0.0.3"
   },
   "publishConfig": {
     "access": "public",

package/.docs/raw/docs/(reference)/legacy/styled/assistant-modal.mdx

@@ -1,77 +0,0 @@
----
-title: AssistantModal
-description: Chat bubble component for support or Q&A use cases.
----
-
-
-## Overview
-
-A chat bubble shown in the bottom right corner of the screen. Useful for support or Q&A use cases.
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Install `@assistant-ui/react-ui`
-
-<InstallCommand npm={["@assistant-ui/react-ui"]} />
-
-  </Step>
-  <Step>
-
-### Import CSS styles
-
-Add the following to your `tailwind.config.ts`:
-
-<Tabs items={["Tailwind", "Tailwind + shadcn-ui"]}>
-
-```ts title="/tailwind.config.ts" tab="Tailwind"
-{
-  plugins: [
-    require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
-    require("@assistant-ui/react-ui/tailwindcss")({
-      components: ["assistant-modal"],
-    })
-  ],
-}
-```
-
-```ts title="/tailwind.config.ts" tab="Tailwind + shadcn-ui"
-{
-  plugins: [
-    require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
-    require("@assistant-ui/react-ui/tailwindcss")({
-      components: ["assistant-modal"],
-      shadcn: true
-    })
-  ],
-}
-```
-
-</Tabs>
-
-  </Step>
-  <Step>
-
-### Use it in your app
-
-```tsx title="/app/page.tsx"
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
-import { AssistantModal } from "@assistant-ui/react-ui";
-
-const MyApp = () => {
-  const runtime = useChatRuntime({
-    api: "/api/chat",
-  });
-
-  return (
-    <div>
-      <AssistantModal runtime={runtime} />
-    </div>
-  );
-};
-```
-
-  </Step>
-</Steps>