# BW Pretty Post Link - Claude Development Guide

**Version:** 1.0.0 | **Last Updated:** 2026-04-20

## What this plugin does

Gutenberg block for displaying nicely-rendered post links. Supports internal posts (any public post type) and external URLs with two layout modes: Simple (text list) and Thumbnail (16:9 image + title).

## Quick Reference

| Item | Value |
|------|-------|
| Slug | `bw-pretty-post-link` |
| Text Domain | `bw-pretty-post-link` |
| Constant Prefix | `BW_PPL_` |
| Function Prefix | `bw_ppl_` |
| Block Namespace | `bw/pretty-post-link-*` |

## File Structure

```
bw-pretty-post-link/
├── bw-pretty-post-link.php   # Main plugin file
├── assets/
│   ├── editor.js             # Block registration (no build step)
│   ├── editor.css            # Editor-only styles
│   └── frontend.css          # Frontend styles
├── README.md
├── CHANGELOG.md
├── CLAUDE.md                 # This file
├── LICENSE
└── uninstall.php
```

## Blocks

### `bw/pretty-post-link-list` (Parent)

Container block that holds items and controls layout.

**Attributes:**
- `layout` (string): `simple` or `thumbnail`
- `imgWidthPercent` (number): Thumbnail width as percentage (10-60)

### `bw/pretty-post-link-item` (Child)

Individual link item, either internal or external.

**Attributes:**
- `linkType` (string): `internal` or `external`
- `postType` (string): Post type slug for internal links
- `postId` (number): Selected post ID
- `customTitle` (string): Override title for internal posts
- `customThumbnailId` (number): Override thumbnail attachment ID
- `externalTitle` (string): Title for external links
- `externalUrl` (string): URL for external links
- `externalThumbnailId` (number): Thumbnail for external links

## REST Endpoint

`GET /bw-ppl/v1/post-types`

Returns public post types (excluding attachments, blocks, templates). Requires `edit_posts` capability.

## Security Notes

- All output escaped with `esc_html()`, `esc_url()`
- External URLs sanitized with `esc_url_raw()` on input
- REST endpoint gated by `current_user_can('edit_posts')`
- No SQL - uses WordPress APIs only
- No user data stored - block attributes only

## Styling

CSS custom property `--bw-ppl-img-width` controls thumbnail width in thumbnail layout. Set via inline style on the wrapper.

## Development Notes

- No build step required - editor.js uses `wp.element.createElement`
- Blocks are dynamic (server-rendered via `render_callback`)
- Frontend styles loaded on-demand when block is present