with buttons
- - Buttons present: 'Copy RIS', 'Copy BibTeX', 'Download .ris', 'Download .bib', 'Download CSL-JSON'
- - Each button has type="button"
-
- Hydration (unit-testable via JSDOM with mocked document):
- - hydrateBibliography(container) finds all li[data-csl] within the container and appends cite panels
- - After hydrateBibliography, the container has class 'bibliography-builder-js-ready'
- - li elements without data-csl are skipped (no panel appended)
- - li with invalid JSON in data-csl is skipped (no panel, no throw)
- - li with null or non-object JSON in data-csl is skipped
-
- Button behavior (unit tests use stubs for downloadTextExport and copyTextToClipboard):
- - 'Copy RIS' click calls copyTextToClipboard with buildSingleRisContent(cslItem) result
- - 'Download .ris' click calls downloadTextExport with RIS content and RIS MIME type
- - 'Download .bib' click awaits buildSingleBibtexContent then calls downloadTextExport
- - 'Download CSL-JSON' click calls downloadTextExport with CSL-JSON content and CSL-JSON MIME type
-
-
- TDD red-green-refactor.
-
- IMPORTANT: Export buildCitePanel and hydrateBibliography as named exports from view.js so they can be tested in isolation. The DOMContentLoaded listener at module scope is the only non-exported code.
-
- src/view.js structure:
- 1. Imports: copyTextToClipboard from ./lib/clipboard; downloadTextExport, RIS/BIBTEX/CSL_JSON_EXPORT_MIME_TYPE from ./lib/export; buildSingleRisContent, buildSingleBibtexContent, buildSingleCslJsonContent from ./lib/export-single
- 2. export function buildCitePanel(cslItem, { copyFn, downloadFn } = {}) — creates and returns the element. Accept copyFn and downloadFn as injectable dependencies for testing (default to copyTextToClipboard and downloadTextExport).
- 3. export function hydrateBibliography(container, { copyFn, downloadFn } = {}) — finds li[data-csl], parses JSON, appends panel, marks container js-ready.
- 4. DOMContentLoaded listener calls hydrateBibliography on each .wp-block-bibliography-builder-bibliography element.
-
- src/view.test.js: Use JSDOM (Jest's default jsdom environment). Mock imports:
- - jest.mock('./lib/export-single', ...) with sync stubs that return predictable strings
- - jest.mock('./lib/clipboard', ...) with a stub returning Promise.resolve(true)
- - jest.mock('./lib/export', ...) returning a stub downloadTextExport and the real MIME type constants
-
- i18n note: Button labels are hardcoded English in this phase. The open question about data-i18n attributes is deferred — hardcoded labels are acceptable for Phase 2. Track as follow-on.
-
-
-
-
-
-
- Task 1: TDD — view.js cite panel and hydration logic
- src/view.js, src/view.test.js
-
- Per the feature behavior block above — run RED commit then GREEN commit.
-
-
- Follow TDD cycle strictly:
-
- RED: Write src/view.test.js with:
- - Tests for buildCitePanel(cslItem) DOM structure (class, summary text, button count/labels, button types)
- - Tests for hydrateBibliography(container): panels added to li[data-csl] entries, js-ready class added, li without data-csl skipped, invalid JSON skipped
- - Tests for button click behavior using injected copyFn/downloadFn stubs (no real async imports needed)
-
- Mock strategy in test file:
- ```js
- jest.mock('./lib/export-single', () => ({
- buildSingleRisContent: jest.fn(() => 'RIS_CONTENT'),
- buildSingleBibtexContent: jest.fn(async () => 'BIBTEX_CONTENT'),
- buildSingleCslJsonContent: jest.fn(() => 'CSL_CONTENT'),
- }));
- jest.mock('./lib/clipboard', () => ({
- copyTextToClipboard: jest.fn(async () => true),
- }));
- jest.mock('./lib/export', () => ({
- downloadTextExport: jest.fn(),
- RIS_EXPORT_MIME_TYPE: 'application/x-research-info-systems;charset=utf-8',
- BIBTEX_EXPORT_MIME_TYPE: 'text/x-bibtex;charset=utf-8',
- CSL_JSON_EXPORT_MIME_TYPE: 'application/vnd.citationstyles.csl+json;charset=utf-8',
- }));
- ```
-
- Run `npm test -- --testPathPattern="src/view.test"` — tests must FAIL.
- Commit: test(02-03): add failing tests for view.js cite panel hydration
-
- GREEN: Create src/view.js with buildCitePanel and hydrateBibliography exported, plus DOMContentLoaded listener.
- Run tests — must PASS.
- Commit: feat(02-03): implement view.js cite panel hydration
-
- The DOMContentLoaded listener is not tested directly — it is glue code calling the tested hydrateBibliography function.
-
-
- npm test -- --testPathPattern="src/view.test" --passWithNoTests=false
-
-
- - src/view.js exports buildCitePanel and hydrateBibliography
- - src/view.test.js has tests covering DOM structure, hydration, skip-on-missing-data-csl, skip-on-invalid-JSON, button behavior
- - All view.test.js tests pass
- - RED commit then GREEN commit both present
-
-
-
-
- Task 2: Progressive enhancement CSS in style.scss
- src/style.scss
-
- Append to src/style.scss (do not replace existing content):
-
- ```scss
- // Cite / Export panel — progressive enhancement
- // Controls are hidden by default; view.js adds .bibliography-builder-js-ready
- // to reveal them only when JS has run successfully.
- .bibliography-builder-cite-controls {
- display: none;
- }
-
- .bibliography-builder-js-ready .bibliography-builder-cite-controls {
- display: block;
- }
-
- .bibliography-builder-cite-panel {
- display: flex;
- flex-wrap: wrap;
- gap: 0.5em;
- padding: 0.5em 0;
- }
-
- .bibliography-builder-cite-panel button {
- font-size: 0.875em;
- cursor: pointer;
- }
- ```
-
- This CSS ensures:
- - No cite controls are visible when JS is disabled (REQ-FE-04: no-JS bibliography fully readable)
- - Controls appear only after view.js adds bibliography-builder-js-ready (REQ-FE-05: deactivation-resilient)
- - When plugin is deactivated, bibliography-builder-js-ready is never added, controls remain hidden
- - Existing bibliography styles are unaffected (additive-only change)
-
-
- npm run build && echo "Build clean"
-
-
- - src/style.scss includes .bibliography-builder-cite-controls { display: none }
- - src/style.scss includes .bibliography-builder-js-ready .bibliography-builder-cite-controls rules
- - npm run build completes without errors
- - build/view.js is present in the build output
- - build/style-index.css includes the cite control rules
-
-
-
-
-
-
-After both tasks:
-- `npm test` — full suite passes (export-single + view + save tests all green)
-- `npm run build` — build/view.js present, no build errors
-- `grep -n "bibliography-builder-cite-controls" build/style-index.css` — CSS rule present in output
-- `ls build/view.js` — viewScript compiled artifact exists
-
-
-
-- src/view.js exists, exports buildCitePanel and hydrateBibliography, has DOMContentLoaded listener
-- src/view.test.js passes: DOM structure, hydration, skip logic, button wiring all covered
-- src/style.scss hides cite controls by default, reveals under js-ready parent
-- npm run build succeeds with build/view.js in output
-- Full Jest suite green
-- No PHP files modified
-
-
-
diff --git a/.planning/phases/02-frontend-cite-and-export-affordances/02-RESEARCH.md b/.planning/phases/02-frontend-cite-and-export-affordances/02-RESEARCH.md
deleted file mode 100644
index 03d10d2..0000000
--- a/.planning/phases/02-frontend-cite-and-export-affordances/02-RESEARCH.md
+++ /dev/null
@@ -1,560 +0,0 @@
-# Phase 2: Frontend Cite and Export Affordances - Research
-
-**Researched:** 2026-06-04
-**Domain:** WordPress static block, progressive-enhancement frontend interactivity, citation export (BibTeX/RIS/CSL-JSON), Clipboard API, Blob download
-**Confidence:** HIGH
-
----
-
-
-## Phase Requirements
-
-| ID | Description | Research Support |
-|----|-------------|-----------------|
-| REQ-FE-01 | Visible per-entry Cite/Export UI on the public bibliography frontend | viewScript + data-attribute hydration pattern; Google Scholar-style cite affordance |
-| REQ-FE-02 | BibTeX, RIS, and CSL-JSON download/copy per entry | `buildBibtexExportContent`, `buildRisExportContent`, `buildCslJsonExportContent` in `src/lib/export.js` are single-entry capable after trivial per-entry extraction; Blob+anchor download pattern |
-| REQ-FE-03 | No render_callback — all output stays in static save() | viewScript hydrates HTML already saved by save.js; no PHP render required for JS-layer behavior |
-| REQ-FE-04 | No-JS bibliography remains fully readable | Existing `` + `` structure is complete text; cite/export controls are additive DOM elements hidden until JS runs or styled as graceful degradation |
-| REQ-FE-05 | Preserves plugin-deactivation resilience | Citation data embedded in `data-csl` attributes is inert HTML; controls can be hidden by default (CSS: `display:none`) and shown by JS; deactivation removes JS but leaves readable bibliography markup intact |
-| REQ-FE-06 | Mendeley/Zotero manual-import acceptance | Visible per-entry RIS and BibTeX download buttons directly serve the gap confirmed in Mendeley testing (non-DOI entries missed by auto-detection) |
-
-
----
-
-## Summary
-
-This phase adds optional Scholar-like Cite/Export controls to the already-saved static bibliography frontend. The plugin uses a static `save()` function — no PHP `render_callback` — which constrains the approach: all interactive behavior must come from JavaScript that hydrates the saved HTML at runtime.
-
-The cleanest solution for this project is a `viewScript` frontend bundle registered in `block.json`. WordPress automatically enqueues `viewScript` only when the block is present on a page (since WP 6.1), making it zero-cost for posts without bibliography blocks. The script reads per-entry CSL-JSON data from attributes embedded during save and renders Cite/Export controls progressively. The WordPress Interactivity API is available but not required; it introduces a `data-wp-interactive` namespace coupling into saved block markup that becomes dead HTML if the plugin is deactivated — contrary to the deactivation-resilience requirement. Vanilla JS with `data-csl` attributes is the preferred approach.
-
-The existing `src/lib/export.js` already contains `buildBibtexExportContent`, `buildRisExportContent`, `buildCslJsonExportContent`, and `buildCslJsonExportContent`. These functions operate on arrays of citations and sort them by style; they need a thin wrapper to operate on a single CSL item. The existing `copyTextToClipboard` in `src/lib/clipboard.js` already handles the `navigator.clipboard` + `execCommand` fallback and is injectable for testing.
-
-**Primary recommendation:** Add a `viewScript` file (`src/view.js`) that reads per-entry CSL-JSON from `data-csl` attributes, builds a per-entry modal/details panel with Copy and Download buttons (BibTeX, RIS, CSL-JSON), and uses the existing export utilities. Embed per-entry CSL-JSON into the save markup using a `data-csl` attribute on each `
`. Keep controls hidden with CSS until JS initialises them.
-
----
-
-## Standard Stack
-
-### Core
-| Library | Version | Purpose | Why Standard |
-|---------|---------|---------|--------------|
-| `@citation-js/core` | 0.7.18 (already in deps) | BibTeX generation | Already bundled; `buildBibtexExportContent` uses it async |
-| `@citation-js/plugin-bibtex` | 0.7.18 (already in deps) | BibTeX/BibLaTeX format | Already bundled async chunk `citation-plugin-bibtex.js` |
-| WordPress `viewScript` | WP 6.1+ | Frontend-only JS enqueue | Auto-enqueued when block present; zero overhead otherwise |
-| Clipboard API (`navigator.clipboard`) | Baseline (2025) | Copy text to clipboard | `copyTextToClipboard` in `clipboard.js` already wraps it with fallback |
-
-### Supporting
-| Library | Version | Purpose | When to Use |
-|---------|---------|---------|-------------|
-| `Blob` + `URL.createObjectURL` | Baseline | File download in browser | Already used by `downloadTextExport` in `export.js` |
-| ``/`` HTML | HTML5 native | No-JS-accessible disclosure widget | Use as the cite panel toggle; degrades to always-open without CSS |
-
-### Alternatives Considered
-| Instead of | Could Use | Tradeoff |
-|------------|-----------|----------|
-| `viewScript` + vanilla JS | WordPress Interactivity API (`viewScriptModule`) | Interactivity API requires `data-wp-interactive` in saved markup, which becomes dead/inert HTML post-deactivation. Also requires WP 6.5+ minimum. Not worth the constraint for this use case. |
-| `data-csl` attribute per `` | Existing `