# CLAUDE.md

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

## What this is

A Drupal 9/10/11 custom theme for the Roblib ILL (interlibrary loan) site. Based on the `stable9` base theme. It's a fork/customization of "The X" base theme (see `README.txt`, `changelog.txt`, `credit.txt`).

Key naming gotcha: the directory is `roblib_ill_theme` but the theme's machine name is **`ill`**. All the config files (`ill.info.yml`, `ill.libraries.yml`, `ill.theme`, `ill.breakpoints.yml`) and the Twig namespace (`@ill/...`) use `ill`. Don't rename one without the other.

## Common commands

### Local dev with browser-sync
The intended local workflow proxies a DDEV site and live-reloads on CSS/JS changes:
```
node bs.js
```
`bs.js` is hardcoded to proxy `https://drupal-theme-dev.ddev.site` and watch `css/**/*.css` and `js/**/*.js`. Edit `bs.js` if your local Drupal URL differs.

### Deploy
`./deploy.sh "commit message"` does the full deploy: `git add --all`, commit, push, then SSH to the production server (`137.149.52.34`), `git pull` in the theme dir, and run `drush cr`. Edit the `SERVER`/`THEME_DIR`/`SITE_ROOT`/`DRUSH_PATH` constants at the top for new environments. Requires SSH key auth set up in advance.

### Drupal cache
After Twig template, library, or `.theme` changes on a running site, the cache must be cleared (`drush cr`). The deploy script does this automatically; locally you'll need to run it yourself.

### Build/lint scripts (currently non-functional)
`package.json` declares yarn scripts for PostCSS / Babel builds, stylelint, and prettier (e.g. `yarn build`, `yarn watch:css`, `yarn lint:css`). **These scripts reference `./scripts/css/...` and `./scripts/js/...` which do not exist in this repo.** Don't run them expecting them to work; CSS and JS in `css/` and `js/` are edited and shipped directly. If a build step gets restored later, the package.json declarations show what was intended.

## Architecture

### Theme entry points
- `ill.info.yml` — declares regions (header_top_left/right, header, primary_menu, search_box, page_header, highlighted, content, content_top/bottom, content_home_top/bottom, sidebar_first/second, footer_top, footer_one..four, footer_bottom_left/right/last, hidden) and pulls in the `ill/global-styling` library.
- `ill.libraries.yml` — defines the libraries. `global-styling` lists every CSS file in `css/` individually (base, layout, then ~15 component files); `js/ill.js` is the only JS, and it depends on `core/jquery`. Additional libraries are defined for `book`, `fontawesome4`, `fontawesome5`, `bootstrap-icons`, and `maintenance`.
- `ill.theme` — only three preprocess hooks: `ill_preprocess_page` (exposes `site_name`, `site_slogan`, `base_path`, `scrolltotop_on`), `ill_preprocess_breadcrumb` (appends current page title to the breadcrumb trail and sets `breadcrumb_icon_style = '/'`), and `ill_preprocess_html` (exposes `is_front`).
- `ill.breakpoints.yml` — three breakpoints: `mobile`, `narrow` (560–850px), `wide` (≥851px).

### Template structure
`templates/layout/page.html.twig` is the assembly point: it conditionally `{% include %}`s partials from `templates/template-parts/{header,footer,sidebar,content-parts,components}/` using the `@ill` namespace. When adding regions or restructuring page chrome, edit `page.html.twig` and add the matching partial under `template-parts/`.

Other template subdirectories (`block/`, `content/`, `content-edit/`, `dataset/`, `field/`, `form/`, `misc/`, `navigation/`) hold standard Drupal template overrides (e.g. `breadcrumb.html.twig`, `menu.html.twig`, `book-navigation.html.twig`).

### CSS organization
Many small files in `css/`, each loaded explicitly by `ill.libraries.yml` (so adding a new CSS file requires registering it there or it won't load). Roughly organized by page region (`header.css`, `footer.css`, `sidebar.css`, `node.css`) and concern (`base.css`, `layout.css`, `responsive.css`, `components.css`, `shortcodes.css`). Several large vendor files are vendored in (`bootstrap-icons.css`, `font-awesome.css`, `font-awesome5.css`, `fontawesome5.css`).

### JS
`js/ill.js` is jQuery-based (`jQuery(document).ready(...)`) and handles: mobile menu toggle, header search box open/close (with click-outside and Esc handling), and scroll-to-top button visibility. No build pipeline — edit and ship.

### Block placement config
`config/optional/block.block.ill_*.yml` defines default block placements (branding, breadcrumbs, content, footer, help, local actions/tasks, main menu, messages, page title, powered, search, tools, account menu) so that a fresh install of the theme has a sane out-of-the-box layout.