npm package: @10up/block-renderer-preferences
Description: User preferences and style guide configuration for WordPress block generation
Latest version: 0.1.7

# @10up/block-renderer-preferences

Load and manage user preferences for AI block generation. Preferences guide AI assistants on preferred blocks, styles, and patterns.

## Installation

```bash
npm install @10up/block-renderer-preferences
# or
pnpm add @10up/block-renderer-preferences
```

## Overview

This package:

1. **Loads preferences** - From `block-preferences.json` or `.blockrc.json`
2. **Validates with Zod** - Ensures preference files are correctly formatted
3. **Formats for AI prompts** - Converts preferences to AI-friendly text
4. **Provides defaults** - Sensible defaults when no file exists

## Usage

### Load Preferences

Automatically find and load preferences from a directory:

```typescript
import { loadPreferences } from '@10up/block-renderer-preferences';

const prefs = loadPreferences('/path/to/project');
// Searches for:
// - /path/to/project/block-preferences.json
// - /path/to/project/.blockrc.json
// - /path/to/project/.block-renderer/preferences.json

if (prefs) {
  console.log(prefs.preferredBlocks);
  console.log(prefs.avoidBlocks);
  console.log(prefs.styleGuide);
}
```

### Load from Specific File

```typescript
import { loadPreferencesFromFile } from '@10up/block-renderer-preferences';

const prefs = loadPreferencesFromFile('/path/to/custom-prefs.json');
```

### Find Preferences File

```typescript
import { findPreferencesFile } from '@10up/block-renderer-preferences';

const filePath = findPreferencesFile('/path/to/project');
// Returns path to preferences file or null if not found
```

### Create Default Preferences

```typescript
import { createDefaultPreferences } from '@10up/block-renderer-preferences';

const defaults = createDefaultPreferences();
// Returns sensible default configuration
```

### Merge Preferences

Combine multiple preference sources:

```typescript
import { mergePreferences, createDefaultPreferences } from '@10up/block-renderer-preferences';

const defaults = createDefaultPreferences();
const userPrefs = loadPreferencesFromFile('/path/to/prefs.json');
const merged = mergePreferences(defaults, userPrefs);
```

### Format for AI Prompts

```typescript
import { formatPreferencesForPrompt } from '@10up/block-renderer-preferences';

const promptSection = formatPreferencesForPrompt(prefs);
// Returns formatted markdown for AI system prompt
```

## Preferences Schema

### BlockPreferencesConfig

The main configuration object:

```typescript
interface BlockPreferencesConfig {
  // Block preferences
  blocks?: BlocksPreferences;

  // Layout preferences
  layout?: LayoutPreferences;

  // Typography preferences
  typography?: TypographyPreferences;

  // Color preferences
  colors?: ColorPreferences;

  // Spacing preferences
  spacing?: SpacingPreferences;

  // Image preferences
  images?: ImagePreferences;

  // Style guide
  styleGuide?: StyleGuide;

  // Brand guidelines
  brand?: BrandGuideline;
}
```

### BlocksPreferences

```typescript
interface BlocksPreferences {
  /** Blocks to prefer when multiple options exist */
  preferred?: string[];
  /** Blocks to avoid using */
  avoid?: string[];
  /** Default block for text content */
  defaultText?: string;
  /** Default container block */
  defaultContainer?: string;
}
```

### LayoutPreferences

```typescript
interface LayoutPreferences {
  /** Default layout type for groups */
  defaultType?: 'constrained' | 'flex' | 'flow' | 'grid';
  /** Maximum content width */
  maxWidth?: string;
  /** Default alignment */
  defaultAlign?: 'left' | 'center' | 'right' | 'wide' | 'full';
}
```

### TypographyPreferences

```typescript
interface TypographyPreferences {
  /** Use semantic heading levels */
  useSemanticHeadings?: boolean;
  /** Maximum heading level to use */
  maxHeadingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
  /** Default font size */
  defaultFontSize?: string;
}
```

### ColorPreferences

```typescript
interface ColorPreferences {
  /** Preferred color tokens to use */
  preferred?: string[];
  /** Colors to avoid */
  avoid?: string[];
  /** Default background color */
  defaultBackground?: string;
  /** Default text color */
  defaultText?: string;
}
```

### SpacingPreferences

```typescript
interface SpacingPreferences {
  /** Default spacing token */
  default?: string;
  /** Preferred spacing scale */
  scale?: string[];
}
```

### ImagePreferences

```typescript
interface ImagePreferences {
  /** Preferred image sizes */
  preferredSizes?: string[];
  /** Default aspect ratio */
  defaultAspectRatio?: string;
  /** Always include alt text */
  requireAlt?: boolean;
}
```

### StyleGuide

```typescript
interface StyleGuide {
  /** Custom style rules */
  rules?: string[];
  /** Preferred patterns by category */
  patternsByCategory?: Record<string, string[]>;
  /** Patterns to avoid */
  avoidPatterns?: string[];
}
```

### BrandGuideline

```typescript
interface BrandGuideline {
  /** Brand name */
  name?: string;
  /** Brand description */
  description?: string;
  /** Voice and tone guidelines */
  voiceTone?: string[];
}
```

## Example Configuration

```json
{
  "blocks": {
    "preferred": ["core/group", "core/columns"],
    "avoid": ["core/freeform", "core/html"],
    "defaultText": "core/paragraph",
    "defaultContainer": "core/group"
  },
  "layout": {
    "defaultType": "constrained",
    "defaultAlign": "wide"
  },
  "typography": {
    "useSemanticHeadings": true,
    "maxHeadingLevel": 4
  },
  "colors": {
    "preferred": ["primary", "secondary", "base", "contrast"],
    "avoid": ["error", "warning"]
  },
  "spacing": {
    "default": "50",
    "scale": ["30", "40", "50", "60", "70"]
  },
  "images": {
    "preferredSizes": ["large", "full"],
    "requireAlt": true
  },
  "styleGuide": {
    "rules": [
      "Always use constrained layout for content groups",
      "Prefer flex layout for button containers",
      "Use consistent spacing throughout sections"
    ],
    "patternsByCategory": {
      "hero": ["theme/hero-centered", "theme/hero-split"]
    },
    "avoidPatterns": ["theme/deprecated-banner"]
  },
  "brand": {
    "name": "Acme Corp",
    "voiceTone": [
      "Professional but approachable",
      "Clear and concise",
      "Helpful and supportive"
    ]
  }
}
```

## Complete Exports

### Functions

| Function | Description |
|----------|-------------|
| `loadPreferences(directory)` | Auto-detect and load preferences |
| `loadPreferencesFromFile(filePath)` | Load from specific file |
| `findPreferencesFile(directory)` | Find preferences file path |
| `createDefaultPreferences()` | Create default configuration |
| `mergePreferences(base, override)` | Merge preference objects |
| `formatPreferencesForPrompt(prefs)` | Format for AI prompt |

### Types

| Type | Description |
|------|-------------|
| `BlockPreferencesConfig` | Main configuration type |
| `BlocksPreferences` | Block selection preferences |
| `LayoutPreferences` | Layout preferences |
| `TypographyPreferences` | Typography preferences |
| `ColorPreferences` | Color preferences |
| `SpacingPreferences` | Spacing preferences |
| `ImagePreferences` | Image preferences |
| `StyleGuide` | Style guide rules |
| `BrandGuideline` | Brand guidelines |
| `Preferences` | Alias for BlockPreferencesConfig |

### Zod Schemas

| Schema | Description |
|--------|-------------|
| `blockPreferencesConfigSchema` | Main config schema |
| `blockPreferencesSchema` | Block preferences schema |
| `layoutPreferencesSchema` | Layout preferences schema |
| `typographyPreferencesSchema` | Typography preferences schema |
| `colorPreferencesSchema` | Color preferences schema |
| `spacingPreferencesSchema` | Spacing preferences schema |
| `imagePreferencesSchema` | Image preferences schema |
| `styleGuideSchema` | Style guide schema |
| `brandGuidelineSchema` | Brand guideline schema |
| `preferencesSchema` | Alias for main schema |

## License

MIT