# 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 (`olivesbooks`) forked from Drupal core's Olivero theme, deployed to the "Book Lives @UPEI" site (booklives2.islandarchives.ca) — part of the Islandimagined / IslandArchives ecosystem. The `description` in `olivesbooks.info.yml` literally says "THIS IS A CLONE OF OLIVERO FOR ISLANDIMAGINED." Expect to see Olivero's structure and naming throughout.

Treat the theme as internal-and-forked: there is no upstream sync workflow. Modifications happen directly in this repo.

## Commands

Node toolchain is pinned to Node 12 via `.nvmrc` (legacy — `nvm use` before running scripts). Package manager is Yarn 4 (`packageManager` field in `package.json`).

- `node bs.js` — Browsersync dev server that proxies the live site (`https://booklives2.islandarchives.ca`) and live-reloads on CSS changes. It rewrites `/themes/custom/olivesbooks` URLs so local CSS edits show up immediately against the remote site. **This is the dev workflow.**

There is no build step. CSS is plain `.css`, JS is plain ES5 — edit files directly and Drupal serves them as-is. The legacy Olivero PostCSS/Babel pipeline (build/watch/lint scripts, `scripts/` dir, `.pcss.css` files) has been removed. The babel/postcss/stylelint/eslint entries in `devDependencies` are leftover from that pipeline and can be pruned when convenient.

## Deployment

`./deploy.sh "commit message"` — commits all local changes, pushes, then SSHes into `booklives2.islandarchives.ca`, `git pull`s the theme directory, and runs `drush cr` to clear caches. The server paths are hardcoded at the top of the script. This is a single-environment workflow — there is no staging.

## Architecture

### PHP side (Drupal hooks)

- `olivesbooks.theme` — the bulk of theme logic: `hook_preprocess_*` for html, page-title, maintenance-page, node, block, menu, form, menu-local-tasks, form-element, input, etc., plus `hook_theme_suggestions_*_alter` (notably for blocks and menus, which add region-aware suggestions like `block__sidebar` / `menu__sidebar`).
- `theme-settings.php` — adds the custom theme-settings form (mobile-menu toggle, site-branding bg color, color picker with named schemes). The primary color is stored as hex and converted to HSL at preprocess time so CSS can use the hue/sat/lightness components via custom properties.
- `olivesbooks.post_update.php` — Drupal post-update hooks (e.g., default primary color).
- `src/OlivesbooksPreRender.php` — `TrustedCallbackInterface` implementations used as `#pre_render` callbacks (text_format wrappers, message placeholder fallback).

### CSS

Authored CSS lives under `css/{base,components,layout,theme}/` and is **plain vanilla CSS**. Edit `.css` files directly — there is no preprocessor.

### Libraries

`olivesbooks.libraries.yml` defines ~30+ small libraries, each scoping a few CSS/JS files. The `global-styling` library is attached via `info.yml`; others are attached on demand from `hook_preprocess_*` in `olivesbooks.theme` (e.g., the search library is chosen based on which region the search block lives in — `primary_menu` → narrow, `secondary_menu` → wide).

`libraries-override` in `olivesbooks.info.yml` aggressively replaces Drupal core CSS (admin, dropbutton, vertical-tabs, layout_builder columns, oembed formatter). `libraries-extend` layers theme CSS/JS on top of core libraries (messages, collapse, dialog, progress, layout_discovery, node preview, content_moderation). When adding a new component, check these two sections before assuming core styles will load.

### Templates

`templates/` overrides Drupal core templates organized by category (block, content, dataset, field, filter, form, layout, navigation, user, views, etc.). The two top-level overrides worth noting: `maintenance-page.html.twig` (custom maintenance page) and `mirador.html.twig` (IIIF viewer).

### Config

- `config/install/olivesbooks.settings.yml` — default theme settings (loaded on install)
- `config/schema/olivesbooks.schema.yml` — schema for those settings
- `config/optional/` — Drupal block placement defaults, installed if dependencies are met
- `config/mirador_config/` — **not** Drupal config; this is the Mirador IIIF viewer's own JS config (`main.js`, `settings.js`) referenced by the mirador integration.

### JS

Plain ES5/jQuery-ish JS under `js/`. The `navigation-*`, `messages`, `search`, `tabs`, `comments`, `color-picker`, `checkbox`, `mirador-mods` files map 1:1 to entries in `olivesbooks.libraries.yml`. Nothing is bundled — files are loaded as-is by Drupal.

## Gotchas

- The CSS color system is driven by a single hex value (`base_primary_color`) converted to HSL at preprocess time and exposed as `--color--primary-hue/saturation/lightness` on `<html>`. All other color tokens derive from this. Adding a "new color" means deriving it from the hue, not hardcoding.
- `mobile_menu_all_widths` theme setting toggles the `is-always-mobile-nav` body class. CSS that targets mobile nav needs to respect this state.
- The theme is marked `@internal` in `olivesbooks.info.yml` (inherited from Olivero) and is not backwards-compatible across minor versions — but since this is a fork, that warning applies to the upstream Olivero, not to us.