Docs Update

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

Multi-Path Features

When a feature has multiple configuration paths (e.g., CSS vs JS, declarative vs programmatic), every documentation surface that covers the feature must:

1. State that both paths exist — even if it only covers one in detail
2. Explain when to use which — include a comparison table with trade-offs
3. Cross-reference — link to the other doc surface that covers the other path in detail
4. Identify the recommended default — guide developers toward the simpler path unless they have specific needs

Apply this to: icons (CSS vars vs gridConfig.icons), column config (declarative <tbw-grid-column> vs JS columns), features (declarative features vs manual plugins), styling (CSS custom properties vs registerStyles() vs cellClass/rowClass), etc.

Plugin MDX (.mdx)

Plugin MDX pages live in apps/docs/src/content/docs/grid/plugins/. Structure:

---
title: Plugin Name
description: One-line description.
---

import PluginDefaultDemo from '@components/demos/plugin-name/PluginNameDefaultDemo.astro';
import ShowSource from '@components/ShowSource.astro';

## Installation

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

## Basic Usage

<ShowSource component="plugin-name/PluginNameDefaultDemo">
  <PluginDefaultDemo />
</ShowSource>

## Configuration

Auto-generated from the plugin's config interface by \`genPluginConfigTable()\`.

## Events

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

## API

Public methods and properties.

Plugin JSDoc conventions for auto-generated API docs:

• ## Configuration Options tables are auto-generated from the constructor's config interface — do not hand-write them in JSDoc
• ## Programmatic API tables are redundant with auto-generated Methods — do not hand-write them in JSDoc
• Use {@link TypeName} in hand-written sections (Column Configuration, CSS Custom Properties, Events) to cross-link types
• Run bun nx typedoc grid after changing JSDoc to regenerate MDX

Plugin README (README.md)

Keep concise — links to docs site 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 [docs site](https://toolboxjs.com/grid/plugins/my-plugin/) 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)

api-reference.mdx (apps/docs/src/content/docs/grid/api-reference.mdx) Events section — Update when:

• Event cancelability changes (the cancelable events table is curated)
• Framework-specific listening patterns change

:::note Individual event descriptions, payload types, and code examples are auto-generated from JSDoc in DataGridEventMap — update the JSDoc, not the curated docs. Run bun nx typedoc grid to regenerate. :::

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 (apps/docs/src/content/docs/grid/)

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:

/**
 * 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
• @category — Routes exports to different TypeDoc sidebar sections (grid core only, see below)
• @group — Organizes class members into subsection headings within a page (see below)
• @fires — Documents events emitted by a method; collected into Events tables

@category and @group — Controlling API Doc Output

The typedoc-to-mdx.ts scripts convert TypeDoc JSON into MDX pages. Two JSDoc tags control where and how exports appear.

@category and @group are only processed by the grid core script (libs/grid/scripts/typedoc-to-mdx.ts). Adapter scripts use hard-coded name lists instead (see below).

@category — API Doc Routing (Grid Core)

Add @category to top-level exports in types.ts, constants.ts, or grid.ts to control which API docs section they land in. The routing logic lives in processCoreModule():

• @category Plugin Development → Grid/API/Plugin Development/{Kind}/{Name}
• @category Framework Adapters → Grid/API/Framework Adapters/{Kind}/{Name}
• Any other value or no @category → Grid/API/Core/{Kind}/{Name}

Only Plugin Development and Framework Adapters cause routing changes. Other values (e.g., Data Management, Events) are informational — they still route to Core. Check processCoreModule() in libs/grid/scripts/typedoc-to-mdx.ts for the current routing logic.

DataGridElement split: The DataGridElement class is special-cased by genDataGridSplit() — it produces 3 separate MDX documents by filtering members:

• Public API (DataGridElement.mdx) — members without _ prefix, without @internal, without @category Framework Adapters
• Plugin API (DataGridElement-PluginAPI.mdx) — _-prefixed members (not __) or @internal Plugin API
• Framework Adapters (DataGridElement-Adapters.mdx) — members tagged @category Framework Adapters

When adding a new member to DataGridElement, choose the right tag/prefix to place it in the correct document.

@group — Section Headings Within a Page

Add @group GroupName to class members (accessors, methods) to organize them under headings within a generated MDX page. Currently used on DataGridElement members. The genMembersSectionByGroup() function renders groups in a defined order — check the groupOrder array in that function for the current list. Members without @group fall into a generic section at the end.

When adding a new member, use an existing @group value if it fits. If no group fits, create a new one — it will be appended after the ordered groups. If the new group should appear in a specific position, add it to the groupOrder array in genMembersSectionByGroup().

@internal Modifier — Visibility Control

• @internal alone → excluded from all generated docs
• @internal Plugin API → included only in the Plugin API document
• _ prefix (without @internal) → same as @internal Plugin API by convention
• __ prefix → excluded from all docs (deeply internal)

Adapter Scripts — Hard-Coded Categorization

Adapter scripts (libs/grid-{angular,react,vue}/scripts/typedoc-to-mdx.ts) do NOT use @category. They categorize by checking export names against hard-coded lists (e.g., isDirective() checks a directiveNames array in Angular). Each adapter sorts into folders like Directives/, Components/, Hooks/, Types/, Utilities/, etc.

When adding a new export to an adapter: check the script's categorization functions. If your export doesn't match an existing check (e.g., a new Angular directive), add its name to the corresponding list so it lands in the right folder instead of the catch-all Utilities/.

Verification

After updating docs:

# Verify docs site builds cleanly
bun nx build docs

# Check for broken links or missing pages
bun nx serve docs
# Navigate to updated pages in browser (http://localhost:4401)

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.