@5mts/canopy 0.0.0-stage → 0.3.0

package/examples/disclosure.md

@@ -0,0 +1,90 @@
+# Dropdowns and accordions
+
+`disclosure()` adds a button that opens and closes content. Use it with
+the SCSS below; JavaScript alone won't hide anything. Set colors, spacing,
+and borders in your theme.
+
+## Dropdown menu
+
+This makes `#sub-nav-menu` a dropdown below 768px. The menu must contain a
+`ul`. Put the JavaScript in your theme:
+
+```js
+import { onGroveRender } from '@5mts/canopy/ready.js';
+import { disclosure } from '@5mts/canopy/disclosure.js';
+
+onGroveRender(() => {
+  const nav = document.querySelector('#sub-nav-menu');
+  if (nav) disclosure(nav, { label: 'Menu', toggleClass: 'my-toggle', panel: 'ul' });
+});
+```
+
+Add this to your SCSS:
+
+```scss
+@use 'pkg:@5mts/canopy/patterns' as *;
+
+.my-toggle { display: none; }
+
+#sub-nav-menu {
+  @media (max-width: 767px) {
+    @include disclosure-dropdown('my-toggle') {
+      .my-toggle { @include disclosure-glyph; }
+      ul {
+        flex-direction: column;
+        background: white;
+      }
+    }
+  }
+}
+```
+
+Change `767px` to choose when the dropdown appears. Remove the media query
+to use a dropdown at every width. Keep `toggleClass` and the mixin's first
+argument identical. Repeated calls update the label without adding another button.
+
+To close the menu on an outside click or Escape, pass
+`closeOnOutsideClick: true` and `closeOnEscape: true` to `disclosure()`.
+
+## Collapsible transcript
+
+This example finds a container whose first child is an `h2` containing only
+"Transcript". In the CMS, start each transcript with that heading.
+
+```js
+import { onGroveElement } from '@5mts/canopy/ready.js';
+import { disclosure } from '@5mts/canopy/disclosure.js';
+
+onGroveElement('h2:first-child', (heading) => {
+  if (heading.textContent.trim().toLowerCase() !== 'transcript') return;
+
+  const wrapper = heading.parentElement;
+  disclosure(wrapper, { label: 'Transcript', toggleClass: 'transcript-toggle' });
+  wrapper.classList.add('collapsible-transcript');
+});
+```
+
+```scss
+@use 'pkg:@5mts/canopy/patterns' as *;
+
+.collapsible-transcript {
+  @include disclosure-accordion('transcript-toggle', $preserve: 'h2');
+  .transcript-toggle { @include disclosure-glyph; }
+}
+```
+
+The heading stays visible when closed. Omit `$preserve: 'h2'` to hide it
+with the transcript. The container should hold only the transcript: its
+other direct children will also collapse.
+
+## SCSS options
+
+- `disclosure-dropdown($toggle-class, $panel: 'ul', $panel-display: flex)`
+  opens the panel as a full-width overlay. If you change `$panel`, change
+  the JavaScript `panel` option too.
+- `disclosure-accordion($toggle-class, $preserve: ())` hides direct children
+  when closed, except the button and any selectors in `$preserve`.
+- `disclosure-glyph($closed: '▼', $open: '▲')` adds an open/closed indicator
+  to the button.
+
+Browsers without CSS `:has()` support leave the content expanded.

package/examples/inline-snippets.md

@@ -0,0 +1,112 @@
+# Run JavaScript pasted into the CMS
+
+Grove can change pages without reloading the browser. Canopy runs your code
+when the elements it needs appear, including after those page changes.
+
+Your site must load `global.js` once. If it doesn't yet, follow
+[site setup](#site-setup).
+
+## Code for one page
+
+Paste this into a page's HTML field. It adds a working "Back to top" button:
+
+```html
+<button type="button" class="back-to-top">Back to top</button>
+<script type="text/canopy">
+  canopy.on('groveElement', '.back-to-top', button => {
+    button.addEventListener('click', () => window.scrollTo({ top: 0 }));
+  });
+</script>
+```
+
+Keep `type="text/canopy"`. Canopy runs the script when it appears and stops
+its registered callbacks when it leaves the page. Returning to the page
+runs a newly inserted script again.
+
+`groveElement` runs once per matching element. Use it for adding buttons,
+changing text, or attaching click handlers.
+
+## Code for every page
+
+Use a normal `<script>` in a site-wide header or footer slot:
+
+```html
+<script>
+  canopy.on('groveElement', '.back-to-top', button => {
+    button.addEventListener('click', () => window.scrollTo({ top: 0 }));
+  });
+</script>
+```
+
+This handles each `.back-to-top` button as it appears across page changes.
+Include the button HTML wherever you want it. The setup below must come
+before site-wide snippets.
+
+## Site setup
+
+Add this once in the site-wide header, before other canopy scripts. Replace
+`VERSION` with the published version you want to use.
+
+```html
+<script>
+window.canopy = window.canopy || {
+  on: (...args) => (window.canopyActions = window.canopyActions || []).push(args),
+};
+</script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@5mts/canopy@VERSION/global.js"></script>
+```
+
+The first script holds calls until canopy loads. Use a fixed version so
+updates don't change your site unexpectedly.
+
+If your theme already includes `import '@5mts/canopy/global.js'`, keep the
+first script and omit the CDN script. Load `global.js` only once.
+
+Sites whose Content Security Policy blocks `eval` cannot run `text/canopy`
+scripts. Use a permitted normal script with `{ scope: 'page' }` instead.
+Without `global.js`, `text/canopy` scripts do nothing.
+
+## Choose when code runs
+
+| Action | Runs |
+|---|---|
+| `groveElement` | Once per element matching your selector |
+| `groveRender` | When ready, then after content or navigation changes |
+| `groveNavigate` | On load and whenever the path or query changes |
+
+`groveNavigate` ignores hash changes; returning to an earlier URL runs it
+again. The new page's elements may not exist yet, so use `groveElement`
+when working with them.
+
+With `groveRender`, check before changing text or adding/removing elements.
+Those changes trigger another run; repeating them can freeze the page:
+
+```js
+canopy.on('groveRender', () => {
+  const heading = document.querySelector('#section-title');
+  if (heading && heading.textContent !== 'Local news') {
+    heading.textContent = 'Local news';
+  }
+});
+```
+
+## Limit a normal script to its current page
+
+Pass `{ scope: 'page' }` last:
+
+```js
+canopy.on('groveElement', '.back-to-top', button => {
+  button.addEventListener('click', () => window.scrollTo({ top: 0 }));
+}, { scope: 'page' });
+```
+
+This checks the path and query where the call was made. The callback stays
+registered and can run again when you return. In a normal script, calls
+apply site-wide unless you add this option. Calls from tag managers, the
+console, or other callbacks follow the same rule.
+
+Once canopy has loaded, `canopy.on()` returns a function you can call to
+stop that registration. Calls made before it loads can't return this function.
+
+For debugging, look for `[canopy]` errors in the browser console. Check
+action names first: unknown names throw an error.

package/examples/relocate.md

@@ -0,0 +1,52 @@
+# Move content
+
+`relocate()` moves matching elements when the page loads and after Grove
+updates it. Register each move once in your theme's JavaScript.
+
+## Move the podcast subscribe links
+
+This places the links inside the first `.my-sidebar-slot` element:
+
+```js
+import { grove } from '@5mts/canopy/selectors.js';
+import { relocate } from '@5mts/canopy/relocate.js';
+
+relocate({ source: grove('podcast-subscribe'), dest: '.my-sidebar-slot' });
+```
+
+Use any CSS selector for `source` and `dest`. All matching sources move;
+if the destination is missing, they stay where they are.
+
+`position` controls placement:
+
+| Value | Placement |
+|---|---|
+| `beforeend` (default) | Inside, after existing content |
+| `afterbegin` | Inside, before existing content |
+| `beforebegin` | Before the destination |
+| `afterend` | After the destination |
+
+## Prevent a flash before the move
+
+Optional SCSS hides the source until it moves:
+
+```scss
+@use 'pkg:@5mts/canopy' as *;
+@use 'pkg:@5mts/canopy/patterns' as *;
+
+@include grove-selector('podcast-subscribe') {
+  @include relocate-flash-guard($dest: '.my-sidebar-slot');
+}
+```
+
+Use the same destination selector in both examples. The source stays visible
+on pages without a destination. If JavaScript fails, it reappears after
+five seconds.
+
+Options: `$fallback-delay: 5s`, `$duration: 0.4s`, and `$shift: -0.5rem`.
+These control the fallback reveal's delay, duration, and vertical movement.
+Reduced-motion settings remove the animation, but keep the delayed reveal.
+
+Moved elements get `data-canopy-relocated`; destinations get the `canopy-relocated`
+class. The SCSS uses the attribute to reveal each element after it moves,
+including new content loaded during navigation.

package/examples/sidebar-left.md

@@ -0,0 +1,57 @@
+# Put the sidebar on the left
+
+`sidebar-left` moves Grove's sidebar to the left on wide screens and fixes
+its margins. You choose which pages it affects and how much space separates
+the columns.
+
+## Pages with a sidebar menu
+
+This puts the sidebar on the left from 768px up, and above the content on
+smaller screens:
+
+```scss
+@use 'pkg:@5mts/canopy/patterns' as *;
+
+html:has(#sub-nav-menu) {
+  @include sidebar-left($gap: 2rem, $stacked: sidebar-first);
+}
+```
+
+Replace `html:has(#sub-nav-menu)` to select different pages. Set column
+widths in your theme.
+
+## Show and episode pages
+
+These layouts use different widths for side-by-side columns:
+
+```scss
+@use 'pkg:@5mts/canopy/patterns' as *;
+
+@include sidebar-left($container: 'show-landing-container', $gap: 2rem);
+@include sidebar-left($container: 'episode-container', $gap: 2rem);
+```
+
+| `$container` | Sidebar moves left at |
+|---|---|
+| `'page-container'` (default) | 768px |
+| `'show-landing-container'` | 768px |
+| `'episode-container'` | 1024px |
+
+For article, blog post, and live blog layouts, pass `$breakpoint: 1024px`
+with `'page-container'` to match Grove. `'show-container'` combines layouts
+with different widths, so it requires an explicit `$breakpoint`.
+
+## Options
+
+- `$gap` sets the sidebar's right margin at every width. Omit it to leave
+  that margin unchanged.
+- `$breakpoint` overrides the width in the table.
+- `$stacked: sidebar-first` puts the sidebar above the content below that
+  width. `$stacked: sidebar-last` puts it below. Omit `$stacked` to keep
+  Grove's normal stacking.
+
+If your `$breakpoint` is wider than Grove's, set `$stacked` too. This keeps
+the columns stacked until your chosen width.
+
+For a sidebar menu with current-page styling and a mobile dropdown, see
+[section navigation](subnav.md).

package/examples/subnav.md

@@ -0,0 +1,71 @@
+# Section navigation
+
+`subnav()` labels a menu for screen readers and marks the current page's
+link. Use it with `disclosure()` for a dropdown on small screens.
+
+## JavaScript
+
+This expects a menu container with `id="sub-nav-menu"` and a `ul` of links.
+Add it to your theme's JavaScript:
+
+```js
+import { onGroveRender } from '@5mts/canopy/ready.js';
+import { subnav } from '@5mts/canopy/subnav.js';
+import { disclosure } from '@5mts/canopy/disclosure.js';
+
+onGroveRender(() => {
+  const nav = document.querySelector('#sub-nav-menu');
+  if (!nav) return;
+
+  const current = subnav(nav, { label: 'Section', currentClass: 'current-link' });
+
+  disclosure(nav, {
+    label: current?.textContent.trim() || 'Section',
+    panel: 'ul',
+    toggleClass: 'section-toggle',
+    closeOnOutsideClick: true,
+    closeOnEscape: true,
+  });
+});
+```
+
+The button shows the current page's link text, or "Section" if no link
+matches. Remove the `disclosure()` call and import for an expanded menu.
+
+## SCSS
+
+This bolds the current link and turns the menu into a dropdown below 768px:
+
+```scss
+@use 'pkg:@5mts/canopy/patterns' as *;
+
+.section-toggle { display: none; }
+
+#sub-nav-menu {
+  a.current-link { font-weight: bold; }
+
+  @media (max-width: 767px) {
+    @include disclosure-dropdown('section-toggle') {
+      .section-toggle { @include disclosure-glyph; }
+      ul {
+        flex-direction: column;
+        background: white;
+      }
+    }
+  }
+}
+```
+
+Change the width, colors, and spacing for your site. More options:
+[dropdowns and accordions](disclosure.md).
+
+## Current-page and accessibility details
+
+- Matching links get `aria-current="page"` and `currentClass` (default:
+  `canopy-current`). Links must be on the same site. Matching ignores query
+  strings, hashes, and trailing slashes.
+- `subnav()` returns the first matching link, or `null`.
+- It adds a navigation role and label where needed, and preserves an
+  existing `aria-label`. Pass a container around the list, such as a `nav`
+  or `div`; a bare `ul` or `ol` won't get a navigation role or label.
+- Lists get `role="list"` so Safari recognizes them when bullets are hidden.

package/global.js

@@ -0,0 +1,106 @@
+// Enable <script type="text/canopy"> snippets and window.canopy.on().
+//
+// Load once in your theme:
+//   import '@5mts/canopy/global.js'
+// Or use a module script:
+//   <script type="module" src=".../@5mts/canopy/global.js"></script>
+//
+// Page snippets run when their script element appears. Inside a snippet,
+// canopy.on() callbacks stop when Grove removes the script from the page.
+// Each snippet has its own variables and can appear before this module loads.
+//
+// window.canopy.on('groveRender', callback) runs on every page. Its action
+// names match ready.js functions without the initial "on": groveRender,
+// groveElement, groveNavigate. Add {scope: "page"} as the last argument to
+// limit callbacks to the current path and query, including return visits.
+// Calls made before this module loads need the setup in examples/inline-snippets.md.
+
+import { onGroveRender, onGroveElement, onGroveNavigate } from "./ready.js";
+
+const api = { onGroveRender, onGroveElement, onGroveNavigate };
+
+function resolve(action) {
+  const method = api["on" + action[0].toUpperCase() + action.slice(1)];
+  if (!method) throw new Error(`[canopy] unknown action: '${action}'`);
+  return method;
+}
+
+// Read and remove the optional final {scope} argument.
+function takeScope(args, fallback) {
+  let scope = fallback;
+  if (args.length && typeof args[args.length - 1] === "object") {
+    scope = args.pop().scope ?? fallback;
+  }
+  if (scope !== "page" && scope !== "site") {
+    throw new Error(`[canopy] unknown scope: '${scope}' (use "page" or "site")`);
+  }
+  return scope;
+}
+
+// Return the function that stops this callback. Invalid actions throw an error.
+function on(action, ...args) {
+  if (takeScope(args, "site") === "page") {
+    const here = location.pathname + location.search;
+    args = args.map(a => typeof a !== "function" ? a : (...xs) => {
+      if (location.pathname + location.search === here) return a(...xs);
+    });
+  }
+  return resolve(action)(...args);
+}
+
+// Log errors and continue with the remaining queued calls.
+function run(entry) {
+  try { on(...entry); }
+  catch (err) { console.error("[canopy] dropped queued action:", err); }
+}
+
+// Page snippets
+
+const seen = new WeakSet();
+const records = [];
+
+function execute(el) {
+  const record = { el, offs: [], dead: false };
+  records.push(record);
+  const facade = {
+    on: (action, ...args) => {
+      if (record.dead) return () => {}; // don't add callbacks after leaving the page
+      if (takeScope(args, "page") === "site") return on(action, ...args, { scope: "site" });
+      const off = resolve(action)(...args);
+      record.offs.push(off);
+      return off;
+    },
+  };
+  try {
+    // Give each snippet its own variables and page-scoped canopy.on().
+    // If the site's Content Security Policy blocks eval, use a plain script
+    // with {scope: "page"} instead of text/canopy.
+    new Function("canopy", el.textContent)(facade);
+  } catch (err) {
+    console.error("[canopy] page snippet failed:", err);
+  }
+}
+
+// Run first so removed snippets stop before their callbacks can run again.
+onGroveRender(() => {
+  for (const el of document.querySelectorAll('script[type="text/canopy"]')) {
+    if (seen.has(el)) continue;
+    seen.add(el);
+    execute(el);
+  }
+  for (let i = records.length - 1; i >= 0; i--) {
+    if (!records[i].el.isConnected) {
+      records[i].dead = true;
+      records[i].offs.forEach(off => off());
+      records.splice(i, 1);
+    }
+  }
+});
+
+// Keep existing references to window.canopy working.
+window.canopy = Object.assign(window.canopy ?? {}, { on });
+
+// Run queued calls now and new calls as they arrive.
+const queued = Array.isArray(window.canopyActions) ? window.canopyActions : [];
+window.canopyActions = { push: (...entries) => entries.forEach(run) };
+queued.forEach(run);

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@5mts/canopy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "A lightweight toolkit for customizing the styling and presentation of Grove sites",
+  "author": "Five Mountains",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/5mts/canopy.git"
+  },
+  "homepage": "https://github.com/5mts/canopy#readme",
+  "bugs": "https://github.com/5mts/canopy/issues",
+  "type": "module",
+  "sass": "_index.scss",
+  "main": "_index.scss",
+  "exports": {
+    ".": {
+      "sass": "./_index.scss"
+    },
+    "./patterns": {
+      "sass": "./patterns/_index.scss"
+    },
+    "./patterns.scss": {
+      "sass": "./patterns/_index.scss"
+    },
+    "./selectors.js": "./selectors.js",
+    "./ready.js": "./ready.js",
+    "./global.js": "./global.js",
+    "./relocate.js": "./relocate.js",
+    "./disclosure.js": "./disclosure.js",
+    "./subnav.js": "./subnav.js",
+    "./_selectors.scss": "./_selectors.scss",
+    "./_layout.scss": "./_layout.scss"
+  },
+  "files": [
+    "_index.scss",
+    "_selectors.scss",
+    "_layout.scss",
+    "patterns/",
+    "examples/",
+    "selectors.js",
+    "ready.js",
+    "global.js",
+    "relocate.js",
+    "disclosure.js",
+    "subnav.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:selectors": "node scripts/generate-selectors-js.mjs",
+    "prepublishOnly": "npm run build:selectors"
+  },
+  "license": "MIT",
+  "keywords": [
+    "grove",
+    "sass",
+    "scss",
+    "adapter",
+    "theme"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/patterns/_audio-player-bottom.scss

@@ -0,0 +1,24 @@
+// Fix Grove's audio player at the bottom of the screen. Set $offset for its
+// bottom position and $reserve-footer for space below the footer content.
+// Footer padding applies at $reserve-at and wider (768px by default).
+
+@use '../selectors' as *;
+@use '../layout' as *;
+
+@mixin audio-player-bottom($offset: null, $reserve-footer: null, $reserve-at: grove-bp('md')) {
+  @include grove-selector('audio-player') {
+    position: fixed;
+    top: auto;
+    @if $offset != null {
+      bottom: $offset;
+    }
+  }
+
+  @if $reserve-footer != null {
+    @media (min-width: $reserve-at) {
+      .Page-footer {
+        padding-bottom: $reserve-footer;
+      }
+    }
+  }
+}

package/patterns/_column-list.scss

@@ -0,0 +1,77 @@
+// Arrange a promo list in two or three columns. Use two-column-list() or
+// three-column-list(). Both use two columns from $two-col-at (768px);
+// three-column-list() adds a third from $three-col-at (1240px).
+// Hides bylines, puts audio labels first, and removes image margins.
+
+@use '../selectors' as *;
+@use '../layout' as *;
+
+@mixin column-list(
+  $columns: 3,
+  $gap: 1.5rem,
+  $tile-padding: 20px 10px,
+  $row-margin: 0 -10px,
+  $two-col-at: grove-bp('md'),
+  $three-col-at: grove-bp('lg')
+) {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  margin: $row-margin;
+
+  @include grove-selector('promo') {
+    display: flex;
+    flex-direction: column;
+    margin: 0;
+  }
+
+  // Tile spacing.
+  & > * {
+    padding: $tile-padding;
+    margin: 0;
+    border-bottom: none;
+  }
+
+  @include grove-selector('promo-content') {
+    display: flex;
+    flex-direction: column;
+    gap: $gap;
+
+    @include grove-selector('byline') {
+      display: none;
+    }
+
+    @include grove-selector('promo-audio-label') {
+      order: 1;
+    }
+    @include grove-selector(('promo-title', 'promo-content', 'description')) {
+      order: 2;
+    }
+  }
+
+  // Two columns.
+  @media (min-width: $two-col-at) {
+    & > * {
+      flex-basis: 50%;
+      max-width: 50%;
+    }
+  }
+
+  // Three columns, if requested.
+  @if $columns >= 3 {
+    @media (min-width: $three-col-at) {
+      & > * {
+        flex-basis: 33%;
+        max-width: 33%;
+      }
+    }
+  }
+
+  @include grove-selector('promo-media') {
+    margin: 0;
+  }
+}
+
+// Both shortcuts accept column-list's named options, such as $gap.
+@mixin two-column-list($args...)   { @include column-list(2, $args...); }
+@mixin three-column-list($args...) { @include column-list(3, $args...); }