Documentation Update Guide

After any code change, use this checklist to identify which documentation needs updating and how.

Quick Decision Matrix

Documentation Inventory

Hand-Written (update manually)

Auto-Generated (regenerate, don't hand-edit)

How to Write Each Doc Type

Plugin MDX (.mdx)

Plugin MDX appears in the Storybook sidebar. Structure:

import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
import * as Stories from './<plugin-name>.stories';

<Meta of={Stories} />

# Plugin Name

One-line description.

## Installation

\`\`\`typescript
import { MyPlugin } from '@toolbox-web/grid/plugins/my-plugin';
\`\`\`

## Basic Usage

<Canvas of={Stories.Basic} />

## Configuration

<Controls of={Stories.Basic} />

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |

## Events

| Event | Detail | Description |
| ----- | ------ | ----------- |

## API

Public methods and properties.

Plugin README (README.md)

Keep concise — links to Storybook for live examples:

# @toolbox-web/grid — Plugin Name

Brief description.

## Usage

\`\`\`typescript
import { MyPlugin } from '@toolbox-web/grid/plugins/my-plugin';
\`\`\`

## Options

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |

## Documentation

See the [Storybook docs](https://your-docs-url) for live examples.

LLM Files (llms.txt / llms-full.txt)

These are AI-consumable documentation. llms.txt is a concise index (~120 lines); llms-full.txt is the full guide (~1600 lines).

llms.txt — Update when:

• •New plugin added (add to plugin list)
• •New public export (add to API summary)
• •New event (add to events list)
• •New CSS variable (add to theming section)

llms-full.txt — Update when:

• •Any user-facing change (contains full code examples for all frameworks)
• •New plugin config options
• •Changed event payloads
• •New CSS custom properties
• •New adapter features

Core MDX Docs (libs/grid/docs/)

Regenerating API Docs

When public API changes (new exports, changed signatures, updated JSDoc):

# Generate TypeDoc JSON and convert to MDX
bun nx typedoc grid
bun nx typedoc grid-angular
bun nx typedoc grid-react
bun nx typedoc grid-vue

Output goes to libs/*/docs/api/ (MDX pages) and libs/*/docs/api-generated/api.json.

Do NOT hand-edit files in docs/api/ or docs/api-generated/ — they are regenerated.

Writing Good JSDoc

JSDoc comments feed into TypeDoc API docs AND Storybook autodocs:

/**
 * Configuration for the grid component.
 *
 * @example
 * ```typescript
 * const config: GridConfig = {
 *   columns: [{ field: 'name', header: 'Name' }],
 * };
 * ```
 *
 * @remarks
 * The config is merged with defaults via `mergeEffectiveConfig()`.
 *
 * @see {@link ColumnConfig} for column-level options
 */
export interface GridConfig { ... }

Key tags:

• •@example — Code examples (rendered in docs)
• •@remarks — Extended description
• •@see — Cross-references
• •@deprecated — Mark deprecated APIs with migration info
• •@internal — Exclude from public API docs
• •@since — Version when feature was added

Verification

After updating docs:

# Verify Storybook builds cleanly
bun nx build docs

# Check for broken links or missing stories
bun nx serve docs
# Navigate to updated pages in browser

Pre-Commit Documentation Review

Before each commit, quickly scan:

1. •Did I change any public API? → Update API.mdx, llms.txt, llms-full.txt
2. •Did I change any plugin? → Update plugin .mdx and README
3. •Did I add/remove CSS variables? → Update Theming.mdx, llms-full.txt
4. •Did I change events? → Update API.mdx, plugin .mdx, llms-full.txt
5. •Did I change conventions? → Update copilot-instructions.md

LLM Files Cross-Check

When updating llms-full.txt, verify these sections stay in sync with the codebase:

1. •Plugin list — Cross-check the plugin table in "Correct Plugin Class Names" against the actual plugins in libs/grid/src/lib/plugins/. Any new plugin must be added with its class name and import path.
2. •Feature props table — Verify every plugin with a feature prop entry in libs/grid-*/src/lib/features/ is listed.
3. •Events table — Check DGEvents enum in libs/grid/src/lib/core/types.ts for new/removed events.
4. •CSS variables — Scan libs/grid/src/lib/core/grid.css for new --tbw-* variables.
5. •Framework recipes — Ensure code examples compile against the current API (import paths, prop names, type names).

Quick validation command:

# List all plugin directories (compare against llms-full.txt plugin table)
ls libs/grid/src/lib/plugins/

# List all feature prop modules (compare against feature props table)
ls libs/grid-react/src/lib/features/ 2>/dev/null
ls libs/grid-angular/src/lib/features/ 2>/dev/null
ls libs/grid-vue/src/lib/features/ 2>/dev/null