v10/.claude/skills/docs/patterns/code-examples.md

Code Examples Pattern

How to write effective code examples for documentation.

Core Principles

1. Self-contained — include all imports
2. Copy-paste ready — works immediately
3. TypeScript-first — show types, leverage inference
4. Minimal — only what's needed to demonstrate the concept
5. Real — use realistic values, not foo/bar

Self-Contained Examples

// ❌ Missing imports — won't work when copied
function App() {
  const player = usePlayer();
  return <Player src="video.mp4" />;
}

// ✅ Complete — copy, paste, run
import { Player, usePlayer } from '@videojs/react';

function App() {
  const player = usePlayer();
  return <Player src="video.mp4" />;
}

TypeScript Best Practices

Show Type Inference

// ✅ Let inference work — cleaner
const player = createPlayer({
  src: 'video.mp4',
  autoplay: true,
});
// player is inferred as Player

// ❌ Redundant annotation
const player: Player = createPlayer({
  src: 'video.mp4',
  autoplay: true,
});

Annotate When Helpful

// ✅ Annotation clarifies complex return
function usePlayerState(): {
  state: PlayerState;
  request: RequestAPI;
} {
  // ...
}

// ✅ Annotation shows expected shape
const options: PlayerOptions = {
  src: 'video.mp4',
  tracks: [
    { kind: 'subtitles', src: 'en.vtt', label: 'English' },
  ],
};

Show Type Imports

// ✅ Show type imports for complex types
import type { PlayerOptions, TextTrack } from '@videojs/core';

const tracks: TextTrack[] = [
  { kind: 'subtitles', src: 'en.vtt', label: 'English' },
];

Framework Tabs

Use tabs for multi-framework examples:

<Tabs>
<Tab label="React">
```tsx
import { Player } from '@videojs/react';

function App() {
  return <Player src="video.mp4" />;
}
```
</Tab>
<Tab label="Vue">
```vue
<script setup>
import { Player } from '@videojs/vue';
</script>

<template>
  <Player src="video.mp4" />
</template>
```
</Tab>
<Tab label="Svelte">
```svelte
<script>
  import { Player } from '@videojs/svelte';
</script>

<Player src="video.mp4" />
```
</Tab>
<Tab label="Vanilla">
```ts
import { createPlayer } from '@videojs/core';

const player = createPlayer({
  target: document.getElementById('player'),
  src: 'video.mp4',
});
```
</Tab>
</Tabs>

Progressive Examples

Start simple, add complexity:

## Basic Usage

const player = createPlayer({ src: 'video.mp4' });

## With Options

const player = createPlayer({
  src: 'video.mp4',
  autoplay: true,
  muted: true,
});

## With Event Handling

const player = createPlayer({
  src: 'video.mp4',
  onPlay: () => console.log('Playing'),
  onError: (e) => console.error(e),
});

## Full Configuration

const player = createPlayer({
  src: 'video.mp4',
  autoplay: true,
  muted: true,
  loop: false,
  preload: 'metadata',
  tracks: [
    { kind: 'subtitles', src: 'en.vtt', label: 'English', default: true },
  ],
  onPlay: () => analytics.track('video_play'),
  onError: (e) => errorReporter.capture(e),
});

Highlight Key Lines

Use comments to draw attention:

const player = createPlayer({
  src: 'video.mp4',
  // highlight-next-line
  autoplay: true, // ← Starts playing automatically
});

Or diff-style:

const player = createPlayer({
  src: 'video.mp4',
- autoplay: false,
+ autoplay: true,
});

Show Output

Include expected output as comments:

console.log(player.state.currentTime);
// => 0

await player.request.seek(30);
console.log(player.state.currentTime);
// => 30

Error Examples

Show what errors look like:

// This will throw:
player.play();
// => Error: Player not attached to media element

// Do this instead:
await player.attach(videoElement);
player.play();

Interactive Examples

Link to StackBlitz/CodeSandbox:

```tsx
import { Player } from '@videojs/react';

function App() {
  return <Player src="video.mp4" />;
}

Open in StackBlitz →

## Copy Buttons

All code blocks should have copy functionality. In MDX:

```mdx
<CodeBlock copy>
const player = createPlayer({ src: 'video.mp4' });
</CodeBlock>

Filename Headers

Show which file the code belongs to:

```tsx title="App.tsx"
import { Player } from '@videojs/react';

export function App() {
  return <Player src="video.mp4" />;
}
```

```css title="player.css"
.player {
  --player-accent-color: #3b82f6;
}
```

Do/Don't Examples

Show contrast:

### Event Handling

// ❌ Don't — inline handlers get recreated
<Player
  onTimeUpdate={(t) => setTime(t)}
/>

// ✅ Do — stable callback reference
const handleTimeUpdate = useCallback((t) => setTime(t), []);
<Player onTimeUpdate={handleTimeUpdate} />

Realistic Values

// ❌ Meaningless
const foo = createBar({ baz: 'qux' });

// ✅ Realistic
const player = createPlayer({
  src: 'https://example.com/video.mp4',
  poster: 'https://example.com/poster.jpg',
});

Console Examples

For CLI documentation:

# Install the package
npm install @videojs/core

# Or with other package managers
pnpm add @videojs/core
yarn add @videojs/core

API Response Examples

For async operations:

const result = await player.request.play();
// => { success: true, state: 'playing' }

const error = await player.request.play();
// => { success: false, error: { code: 'NOT_ALLOWED', message: '...' } }

Configuration Comparison

Show equivalent configs:

### JavaScript

const player = createPlayer({
  src: 'video.mp4',
  autoplay: true,
});

### HTML Data Attributes

<video
  data-player
  data-src="video.mp4"
  data-autoplay
></video>

### React Props

<Player src="video.mp4" autoplay />