v10/.claude/skills/docs/references/state-tooling.md

State Management & Tooling Documentation Patterns

Patterns from Zustand, Jotai, XState, Vite, Vitest, esbuild, Biome.

Contents

• State Management Documentation — Zustand, Jotai, XState patterns
• Configuration Documentation — Vite, esbuild patterns
• Testing Documentation — Test examples, mocking media

State Management Documentation

Zustand Pattern: Minimal Getting Started

3 code blocks to first success:

## Getting Started

Create a store:

const useStore = create((set) => ({
volume: 1,
setVolume: (v) => set({ volume: v }),
}));

Use in component:

function VolumeControl() {
const volume = useStore((state) => state.volume);
return <input value={volume} />;
}

That's it. No providers, no boilerplate.

Key: Show the simplest possible example first. Complexity comes later.

Jotai Pattern: Primitive Naming

atomWith* naming convention documents behavior:

Name	Behavior
atom	Basic read/write
atomWithStorage	Persists to localStorage
atomWithReset	Has reset capability
atomWithDefault	Async default value

Applicable to Video.js:

• createPlayerWith* naming for factory functions
• featureWith* for feature factories

XState Pattern: Visual State Machines

Bidirectional code-visualization sync:

## Player States

[Interactive state diagram here]

const playerMachine = createMachine({
initial: 'idle',
states: {
idle: { on: { LOAD: 'loading' } },
loading: { on: { READY: 'ready', ERROR: 'error' } },
ready: { on: { PLAY: 'playing' } },
playing: { on: { PAUSE: 'paused', END: 'ended' } },
paused: { on: { PLAY: 'playing' } },
ended: { on: { REPLAY: 'playing' } },
error: { on: { RETRY: 'loading' } },
},
});

Applicable to Video.js:

• Document player state machine with diagrams
• Show event-driven transitions
• Visualize request lifecycle

TanStack Query Pattern: AI-Friendly Exports

Every page includes:

> **AI/LLM:** This page is available in plain markdown at
> [/docs/queries.md](/docs/queries.md)

Also:

• Codemod-assisted migrations (npx @tanstack/query-codemod)
• Per-version documentation (/v4/, /v5/)

Configuration Documentation

Vite Pattern: Option Documentation

### root

- **Type:** `string`
- **Default:** `process.cwd()`
- **CLI:** `--root <path>`

Project root directory. Can be absolute or relative to cwd.

export default defineConfig({
root: './src',
});

Format rules:

• Type first (expandable for complex types)
• Default value explicit
• CLI equivalent if applicable
• Short description
• Example

esbuild Pattern: Multi-Interface Examples

Same config in multiple formats:

## minify

<Tabs>
<Tab label="CLI">
esbuild app.js --minify
</Tab>
<Tab label="JS">
import * as esbuild from 'esbuild';

await esbuild.build({
entryPoints: ['app.js'],
minify: true,
});
</Tab>
<Tab label="Go">
package main

import "github.com/evanw/esbuild/pkg/api"

api.Build(api.BuildOptions{
EntryPoints: []string{"app.js"},
MinifyWhitespace: true,
})
</Tab>
</Tabs>

Applicable to Video.js:

• JS config object
• Data attributes on <video>
• Framework-specific props

Biome Pattern: Migration Documentation

## Migrating from ESLint

Run the migration tool:

npx @biomejs/biome migrate eslint --write

This reads your `.eslintrc` and generates `biome.json`.

### Rule Mapping

| ESLint           | Biome                                |
| ---------------- | ------------------------------------ |
| `no-unused-vars` | `lint/correctness/noUnusedVariables` |
| `semi`           | `lint/style/useSemicolons`           |

### What's Not Migrated

- Plugin-specific rules
- Custom rule configurations

Applicable to Video.js:

• Migration from v8/v9 to v10
• Plugin compatibility tables
• Codemod commands

Testing Documentation (Vitest)

Test Examples Pattern

## Testing Components

import { render, screen } from '@testing-library/react';
import { Player } from '@videojs/react';

test('renders player', () => {
render(<Player src="test.mp4" />);
expect(screen.getByRole('application')).toBeInTheDocument();
});

### Mocking Media

import { mockMediaElement } from '@videojs/test-utils';

beforeEach(() => {
mockMediaElement();
});

Test Utilities Documentation

Document test helpers prominently:

## Test Utilities

@videojs/test-utils provides:

| Export               | Purpose                   |
| -------------------- | ------------------------- |
| `mockMediaElement()` | Mock HTMLMediaElement     |
| `createTestPlayer()` | Create player for testing |
| `simulatePlay()`     | Trigger play event        |
| `waitForState()`     | Wait for state change     |

CLI Documentation

Command Reference Pattern

## Commands

### videojs build

Build player bundle.

videojs build [options]

#### Options

| Option        | Description         | Default |
| ------------- | ------------------- | ------- |
| `--outdir`    | Output directory    | `dist`  |
| `--minify`    | Minify output       | `true`  |
| `--sourcemap` | Generate sourcemaps | `true`  |

#### Examples

# Basic build

videojs build

# Custom output

videojs build --outdir=public/player

Error Messages Documentation

Document common errors:

## Troubleshooting

### "Player not attached to media element"

**Cause:** Called method before `attach()`.

**Solution:**

// ❌ Wrong
const player = createPlayer();
player.play(); // Error!

// ✅ Correct
const player = createPlayer();
await player.attach(videoElement);
player.play();

Plugin Documentation Pattern

## Creating Plugins

### Basic Plugin

function myPlugin(player, options) {
// Plugin code
return {
destroy() {
// Cleanup
},
};
}

// Register
player.use(myPlugin, { option: 'value' });

### Plugin Options

Define options with defaults:

const defaultOptions = {
enabled: true,
threshold: 0.5,
};

function myPlugin(player, userOptions) {
const options = { ...defaultOptions, ...userOptions };
}

### Plugin Lifecycle

| Hook        | When                       |
| ----------- | -------------------------- |
| `onAttach`  | Player attached to element |
| `onReady`   | Media ready to play        |
| `onDestroy` | Player being destroyed     |

Event Documentation Pattern

## Events

### Listening to Events

player.on('play', () => {
console.log('Playing');
});

### Event Reference

| Event          | Payload                              | Description      |
| -------------- | ------------------------------------ | ---------------- |
| `play`         | `void`                               | Playback started |
| `pause`        | `void`                               | Playback paused  |
| `timeupdate`   | `{ currentTime: number }`            | Time changed     |
| `volumechange` | `{ volume: number, muted: boolean }` | Volume changed   |
| `error`        | `{ code: number, message: string }`  | Error occurred   |

### Custom Events

player.emit('custom:event', { data: 'value' });

---

See Also

• State Patterns — state management patterns