# CLAUDE.md

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

## What this is

A Drupal 10+ custom theme named "Olivesnews" — a fork of Drupal's Olivero theme, customized for the Island Newspapers project (newspapers2.islandarchives.ca). It includes extensive PHP hook implementations, Twig template overrides, and a Babel + PostCSS build pipeline.

## Commands

```bash
yarn build          # Build both CSS and JS
yarn watch          # Watch both CSS and JS (parallel)
yarn build:css      # PostCSS only
yarn build:js       # Babel transpile only
yarn watch:js-dev   # JS watch in development mode (NODE_ENV=development)
yarn lint:css       # Stylelint
yarn prettier       # Format ES6 and test files
```

BrowserSync for local dev is configured in `bs.js` (proxies a local Drupal instance).

Deployment is via `deploy.sh` — it pushes to Git remote, then SSHes into the server to pull and run `drush cr`.

## Architecture

### Drupal integration layer

- **`olivesnews.theme`** — all PHP hook implementations: `hook_preprocess_*`, `hook_theme_suggestions_*`, `hook_form_alter`, etc. This is the primary PHP entry point.
- **`theme-settings.php`** — admin UI form for theme settings (color schemes, header utilities).
- **`src/OlivesnewsPreRender.php`** — trusted prerender callbacks (must be a class method in Drupal to be trusted).
- **`olivesnews.libraries.yml`** — defines ~25 named asset libraries; controls which CSS/JS files load and their dependencies. Edit this when adding new assets.
- **`olivesnews.info.yml`** — theme metadata, region definitions, and library overrides (replaces core Drupal CSS/JS with theme versions).
- **`olivesnews.breakpoints.yml`** — responsive breakpoints used by Drupal's responsive image module.
- **`config/`** — exported Drupal configuration; `install/` runs on theme enable, `optional/` is applied conditionally.

### Frontend assets

- **`css/`** — PostCSS source, organized as `base/` (variables, fonts, reset), `components/` (buttons, nav, forms, etc.), `layout/`, and `theme/`.
- **`js/`** — ES6 source files, one per behavior. Key files: `navigation.js`, `second-level-navigation.js`, `nav-resize.js`, `search.js`. Transpiled by Babel to ES5.
- Compiled output goes alongside source (Drupal loads the compiled files referenced in `olivesnews.libraries.yml`).

### Templates

`templates/` mirrors Drupal's template suggestion hierarchy. Subdirectories map to entity/element types: `block/`, `content/`, `field/`, `layout/`, `navigation/`, `views/`, etc.

### Mirador integration

The theme includes custom config and JS (`js/mirador-mods.js`, `config/mirador_config/`) for the Islandora Mirador IIIF image viewer.

## Key conventions

- Node is pinned to 12.22.12 (see `.nvmrc`). Use `nvm use` before running yarn commands.
- Yarn 4.0.2 is used (`.yarnrc.yml`). Run `yarn` not `npm`.
- CSS uses px-to-rem conversion via PostCSS — write in `px`, output is `rem`.
- JS targets ES5 (legacy browser support). Babel config in `package.json` (`@babel/preset-env` with `targets: "defaults"`).
- After any PHP or template change in Drupal, a cache clear (`drush cr`) is required before changes are visible.