# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Install all dependencies (Node + Composer)
npm run setup

# Development with watch mode
npm run start

# Production build
npm run build

# PHP linting (WordPress Coding Standards)
npm run lint:php

# PHP auto-fix
npm run fix:php

# JS linting
npm run lint:js

# CSS linting
npm run lint:css

# JS/CSS auto-format
npm run format
```

## Architecture

This is a **WordPress Gutenberg block plugin** (`weboptics/advance-post-grid`) that also supports a `[advance_post_grid]` shortcode.

### Data flow

All block attributes are defined in [src/block.json](src/block.json). They flow through two separate render paths that must stay in sync:

1. **Editor (React)** — [src/edit.jsx](src/edit.jsx) fetches posts via the `@wordpress/data` store (`core` entity records) and renders a live preview inside the block editor. Post types are fetched from the REST API (`/wp-json/wp/v2/types`), filtered to `post`, `page`, `product`.

2. **Frontend (PHP)** — [src/render.php](src/render.php) runs a `WP_Query` using the saved attribute values and outputs HTML directly. Grid column counts are passed as CSS custom properties (`--adv-grid-value`, `--adv-grid-mobile-value`, `--adv-grid-tablet-value`) on the wrapper element.

### Class: `WO_APG_Init` ([advance-post-grid.php](advance-post-grid.php))

The single PHP class that bootstraps the plugin. It:
- Registers the block from the `build/` directory on `init`
- Provides static helpers used in `render.php`: `calculate_read_time()`, `pagination()`, `get_current_page_url()`, `get_page_number_from_url()`
- Handles shortcode rendering via `shortcode_render()`, which maps lowercase shortcode attributes back to camelCase before delegating to `build/render.php`

### Build output

`npm run build` (via `@wordpress/scripts`) compiles `src/` → `build/` and copies `render.php`. The `build/` directory is what WordPress loads — never edit files there directly.

### PHP coding standards

`phpcs.xml.dist` enforces the `WordPress` ruleset. Required global prefixes are `WO_APG`, `Woagp`, `woagp_`. The `vendor/` and `node_modules/` directories are excluded from sniffing.

### Responsive grid

When `enablePostGridRes` is `false`, mobile and tablet columns default to the desktop `postGrid` value. When `true`, `postGridTablet` and `postGridMobile` are used independently. This logic exists in both `render.php` (lines 19–26) and implicitly in `edit.jsx`.