@5mts/canopy 0.0.0-stage → 0.3.0

package/patterns/_disclosure.scss

@@ -0,0 +1,65 @@
+// Show/hide styles for disclosure.js. Add colors, borders, and spacing in
+// your theme. Wrap an include in a media query to limit it to certain widths,
+// and hide the toggle outside those widths: .my-toggle { display: none; }.
+// Keep the toggle hidden by default for disclosure-dropdown; it shows the
+// toggle only in browsers with :has(). Both mixins leave content visible
+// in browsers without :has().
+
+// Add an open/closed arrow to the button. Empty alt text keeps screen readers
+// from reading the arrow where supported; the first declaration is a fallback.
+@mixin disclosure-glyph($closed: '▼', $open: '▲') {
+  &::after {
+    content: $closed;
+    content: $closed / '';
+  }
+
+  &[aria-expanded='true']::after {
+    content: $open;
+    content: $open / '';
+  }
+}
+
+// Include on the container passed to disclosure(). Hides its children while
+// closed, except the toggle and $preserve matches. For example, $preserve: 'h2'
+// keeps headings available to screen readers. Style the toggle in your theme.
+@mixin disclosure-accordion($toggle-class, $preserve: ()) {
+  $spared: ':not(.#{$toggle-class})';
+  @each $selector in $preserve {
+    $spared: $spared + ':not(#{$selector})';
+  }
+
+  &:has(.#{$toggle-class}:not([aria-expanded='true'])) > #{$spared} {
+    display: none;
+  }
+}
+
+// Include on the container passed to disclosure(). Shows $panel as a
+// full-width overlay below the toggle when open. The panel can be nested.
+// Put dropdown colors, backgrounds, and shadows in the include's content block
+// so they apply only in browsers that support the dropdown.
+@mixin disclosure-dropdown($toggle-class, $panel: 'ul', $panel-display: flex) {
+  position: relative; // Position the panel relative to this container.
+
+  @supports selector(:has(*)) {
+    // Full-width toggle: label left, arrow right.
+    .#{$toggle-class} {
+      display: flex;
+      justify-content: space-between;
+      width: 100%;
+      text-align: left;
+      cursor: pointer;
+    }
+
+    #{$panel} {
+      display: none;
+      position: absolute;
+      width: 100%;
+    }
+
+    &:has(.#{$toggle-class}[aria-expanded='true']) #{$panel} {
+      display: $panel-display;
+    }
+
+    @content;
+  }
+}

package/patterns/_index.scss

@@ -0,0 +1,7 @@
+// Import these mixins separately. Each adds CSS only when you @include it.
+//   @use 'pkg:@5mts/canopy/patterns' as *;
+@forward 'column-list';
+@forward 'audio-player-bottom';
+@forward 'disclosure';
+@forward 'relocate-flash-guard';
+@forward 'sidebar';

package/patterns/_relocate-flash-guard.scss

@@ -0,0 +1,54 @@
+// Hide an element until relocate.js moves it and adds data-canopy-relocated.
+// Include inside the element's rule:
+//
+//   @include grove-selector('podcast-subscribe') {
+//     @include relocate-flash-guard($dest: '.my-sidebar-slot');
+//   }
+//
+// With $dest, hide only on pages containing that destination. New elements
+// loaded during navigation stay hidden until moved. If JS doesn't run,
+// reveal the content after $fallback-delay (5s). Reduced motion skips the
+// transition but still restores the content.
+
+$-flash-guard-keyframes-emitted: false;
+
+@mixin -flash-guard-hidden($duration, $delay, $shift) {
+  height: 0;
+  opacity: 0;
+  overflow: hidden;
+  transform: translateY($shift);
+  // Allow the height to animate from 0 to auto.
+  interpolate-size: allow-keywords;
+  animation: canopy-relocate-reveal $duration $delay forwards;
+
+  @media (prefers-reduced-motion: reduce) {
+    transform: none;
+    animation-duration: 0s;
+  }
+}
+
+@mixin relocate-flash-guard($dest: null, $fallback-delay: 5s, $duration: 0.4s, $shift: -0.5rem) {
+  // Add the shared animation once per compilation.
+  @if not $-flash-guard-keyframes-emitted {
+    $-flash-guard-keyframes-emitted: true !global;
+    @at-root {
+      @keyframes canopy-relocate-reveal {
+        to {
+          height: auto;
+          opacity: 1;
+          transform: translateY(0);
+        }
+      }
+    }
+  }
+
+  @if $dest {
+    body:has(#{$dest}) &:not([data-canopy-relocated]) {
+      @include -flash-guard-hidden($duration, $fallback-delay, $shift);
+    }
+  } @else {
+    &:not([data-canopy-relocated]) {
+      @include -flash-guard-hidden($duration, $fallback-delay, $shift);
+    }
+  }
+}

package/patterns/_sidebar.scss

@@ -0,0 +1,77 @@
+// Move the sidebar to the left and adjust its margins. By default, use
+// Grove's breakpoint for the chosen container. Nest the include to choose
+// which pages to change:
+//
+//   html:has(#sub-nav-menu) {
+//     @include sidebar-left($gap: 2rem, $stacked: sidebar-first);
+//   }
+
+@use 'sass:map';
+@use '../selectors' as *;
+@use '../layout' as *;
+
+// Widths where Grove puts the sidebar beside the main content.
+// For page-container, md fits OneOff/Author pages. Pass $breakpoint:
+// grove-bp('md-lg') for BlogPost/LiveBlog/ArtP pages.
+// show-container spans different widths, so it needs an explicit $breakpoint.
+$-sidebar-native-bp: (
+  'page-container': grove-bp('md'),
+  'show-landing-container': grove-bp('md'),
+  'episode-container': grove-bp('md-lg'),
+);
+
+// $container: selector key for the flex parent of main content and aside.
+//   Use page-container, show-landing-container, or episode-container.
+// $gap: space to the right of the sidebar, at all widths.
+// $breakpoint: put the sidebar on the left at this width and above.
+//   Defaults to the container's width listed above.
+// $stacked: below that width, sidebar-first puts the aside above the content;
+//   sidebar-last uses document order (normally aside below). Default null
+//   keeps Grove's layout. Set this if a higher breakpoint should keep content
+//   stacked past Grove's usual breakpoint.
+@mixin sidebar-left($container: 'page-container', $gap: null, $breakpoint: null, $stacked: null) {
+  @if $stacked != null and $stacked != sidebar-first and $stacked != sidebar-last {
+    @error "sidebar-left: $stacked must be sidebar-first or sidebar-last (or null to leave Grove's stacking alone).";
+  }
+
+  $flip-at: $breakpoint;
+  @if $flip-at == null {
+    $flip-at: map.get($-sidebar-native-bp, $container);
+    @if $flip-at == null {
+      @error "sidebar-left: no known Grove flip point for '#{$container}' — it may span families with different breakpoints (show-container does). Use a family key (show-landing-container, episode-container) or pass $breakpoint.";
+    }
+  }
+
+  @include grove-selector($container) {
+    @media (min-width: $flip-at) {
+      flex-direction: row-reverse;
+      justify-content: space-between;
+    }
+
+    @if $stacked != null {
+      @media (max-width: #{$flip-at - 1px}) {
+        display: flex;
+        @if $stacked == sidebar-first {
+          flex-direction: column-reverse;
+        } @else {
+          flex-direction: column;
+        }
+      }
+    }
+  }
+
+  // Remove right-sidebar margins and apply the requested gap.
+  @include grove-selector('sidebar') {
+    margin-left: 0;
+    
+    @if $gap != null {
+      margin-right: $gap;
+    }
+
+    margin-top: 0;
+  }
+
+  @include grove-selector('sidebar-content') {
+    margin-top: 0;
+  }
+}

package/ready.js

@@ -0,0 +1,94 @@
+// Run code when Grove content loads or changes, including after navigation.
+// DOMContentLoaded alone misses content Grove adds later.
+// Keep callbacks quick and safe to repeat: check before adding or changing things.
+
+const callbacks = new Set();
+let started = false;
+let scheduled = false;
+
+// Run callback when the page is ready, content changes, or the URL changes.
+// Returns a function that stops the callback.
+export function onGroveRender(callback) {
+  callbacks.add(callback);
+  start();
+  schedule();
+  return () => callbacks.delete(callback);
+}
+
+// Run callback(el) once per matching element, including elements added later.
+export function onGroveElement(selector, callback) {
+  const seen = new WeakSet();
+  return onGroveRender(() => {
+    for (const el of document.querySelectorAll(selector)) {
+      if (seen.has(el)) continue;
+      seen.add(el);
+      callback(el);
+    }
+  });
+}
+
+// Run callback(url) on load and when the path or query changes, including Back.
+// Ignores hash changes. Content may still be loading; use onGroveElement to
+// work with page elements. Returns a function that stops the callback.
+export function onGroveNavigate(callback) {
+  // Remember only the last URL so returning to a page runs the callback again.
+  let last;
+  return onGroveRender(() => {
+    const url = location.pathname + location.search;
+    if (url === last) return;
+    last = url;
+    callback(url);
+  });
+}
+
+// Start watching on first use, not on import.
+function start() {
+  if (started) return;
+  started = true;
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", () => {
+      observeBody();
+      schedule();
+    }, { once: true });
+  } else {
+    observeBody();
+  }
+  // Also handle Back/Forward and pages restored from the browser's cache.
+  window.addEventListener("pageshow", e => { if (e.persisted) schedule(); });
+  window.addEventListener("popstate", schedule);
+  // These methods fire no event. Watch them in case the URL changes after content.
+  for (const method of ["pushState", "replaceState"]) {
+    const orig = history[method];
+    history[method] = function (...args) {
+      const result = orig.apply(this, args);
+      schedule();
+      return result;
+    };
+  }
+}
+
+function observeBody() {
+  new MutationObserver(schedule).observe(document.body, { childList: true, subtree: true });
+}
+
+// Group changes so callbacks run once per batch.
+function schedule() {
+  if (scheduled) return;
+  scheduled = true;
+  queueMicrotask(() => {
+    scheduled = false;
+    runAll();
+  });
+}
+
+function runAll() {
+  if (document.readyState === "loading") return; // wait until the DOM is ready
+  for (const callback of [...callbacks]) {
+    if (!callbacks.has(callback)) continue; // stopped by an earlier callback
+    try {
+      callback();
+    } catch (err) {
+      console.error("[canopy] onGroveRender callback failed:", err);
+    }
+  }
+}

package/relocate.js

@@ -0,0 +1,38 @@
+// Move elements selected by `source` to `dest` (inside it by default).
+// Runs on load, content changes, and navigation, including Back/Forward.
+//
+// Both values are CSS selectors; use grove('key') for a mapped Grove selector.
+//
+// SCSS uses these names; keep them in sync:
+//   data-canopy-relocated marks moved elements so they move only once.
+//   canopy-relocated marks a destination that received elements.
+// CSS can hide elements until data-canopy-relocated is set to prevent a flash.
+
+import { onGroveRender } from "./ready.js";
+
+const rules = [];
+let registered = false;
+
+// rule = { source, dest, position = 'beforeend' }
+export function relocate(rule) {
+  rules.push(rule);
+  if (!registered) {
+    registered = true; // start watching only when a rule is added
+    onGroveRender(applyAll);
+  }
+}
+
+function applyAll() {
+  for (const { source, dest, position = "beforeend" } of rules) {
+    const destEl = document.querySelector(dest);
+    if (!destEl) continue;
+    let moved = false;
+    for (const node of document.querySelectorAll(source)) {
+      if (node.dataset.canopyRelocated) continue;
+      node.dataset.canopyRelocated = "true";
+      destEl.insertAdjacentElement(position, node);
+      moved = true;
+    }
+    if (moved) destEl.classList.add("canopy-relocated");
+  }
+}

package/selectors.js

@@ -0,0 +1,121 @@
+// GENERATED — do not edit. Source: _selectors.scss
+// Regenerate via: npm run build:selectors
+
+export const groveSelectors = Object.freeze({
+  "container-columns": ".FourColumnContainer, .OneColumnContainer, .ThreeColumnContainer, .TwoColumnContainer3070, .TwoColumnContainer5050, .TwoColumnContainer7030",
+  "page-is-show": ".PodcastPage, .RadioShowPage",
+  "page-is-episode": ".PCEP, .RSEP",
+  "page-is-archive": ".SectionPage, .TagPage",
+  "promo": "ps-promo:not(:where(ps-tabs,.EplB) ps-promo)",
+  "promo-media": "[class^=\"Promo\"][class$=\"-media\"]",
+  "promo-content": "[class^=\"Promo\"][class$=\"-content\"]",
+  "audio-player": ".PH-persistent-player",
+  "promo-audio-label": "[class^=\"Promo\"][class$=\"-audio-label\"]",
+  "button": "button, button.Button, button.Link",
+  "episode-list": ".EplB, .EplA",
+  "episode-list-wrapper": ".EplB-items, .EplA-items",
+  "episode-list-header": ".EplB-header, .EplA-header",
+  "episode-list-title": ".EplB-header-title, .EplA-header-title",
+  "episode-list-item": ".EplB-items-item, .EplA-items-item",
+  "promo-title": "[class^=\"Promo\"][class$=\"-title\"]",
+  "heading": "[class$=\"-header\"], [class$=\"-heading\"]",
+  "heading-title": "[class$=\"-header-title\"]",
+  "sidebar": "main > aside, [class$=\"-wrapper\"] > aside",
+  "sidebar-content": "aside > [class$=\"-aside-content\"]",
+  "main-content": "[class$=\"-mainContent\"]",
+  "main-headline": "h1[class$=\"-headline\"]",
+  "byline": "[class$=\"-byline\"]",
+  "content-meta": "[class$=\"-contentInfo\"]",
+  "page-lead": "main [class$=\"-lead\"]",
+  "breadcrumbs": "[class$=\"-breadcrumbs-wrapper\"]",
+  "people-byline": ".PromoPeople-content",
+  "article-body": "article [class$=\"-articleBody\"]",
+  "article-subhead": "article h2[class$=\"-subheadline\"]",
+  "post-article-tags": "[class$=\"-tags\"]",
+  "post-article-bio": "[class$=\"-bottomByline\"]",
+  "page-description": "[class$=\"-pageDescription-content\"]",
+  "series-banner": ".SeriesBanner",
+  "page-container": "[class$=\"Page-wrapper\"]",
+  "page-header": "[class$=\"Page-head\"]",
+  "page-head-text": "[class$=\"Page-head-text\"]",
+  "main-without-aside": "main:not(:has(~ aside, aside), aside ~ main)",
+  "main-with-aside": "main:has(~ aside, aside), aside ~ main",
+  "metadata-relocatable-links": "[class$=\"-contentInfo\"] a",
+  "content-image": "figure .Image, .PromoXS-media .Image",
+  "caption": ".Figure-caption, .CarouselSlide-infoDescription, .Figure-credit, .CarouselSlide-infoAttribution, [class$=\"-credit-container\"] [class$=\"-credit\"], [class$=\"-credit-container\"] [class$=\"-divider\"], [class$=\"-credit-container\"] [class$=\"-source\"]",
+  "title-text": "[class$=\"-title\"]",
+  "description": "[class$=\"-description\"]",
+  "news-story": ".ArtP:not(.aside)",
+  "podcast-container": ".PodcastPage-main, .PCEP-content .PCEP-wrapper",
+  "podcast-aside": ".PodcastPage-aside, .PCEP-aside",
+  "podcast-cover-and-title": ".PodcastPage-top",
+  "podcast-byline": ".PodcastPage-byline",
+  "podcast-description": ".PodcastPage-byline + *",
+  "podcast-subscribe": ".PodcastActionBar",
+  "podcast-subscribe-label": ".PodcastLink-provider",
+  "podcast-social-bar": ".PodcastPage-social",
+  "podcast-icon-headings": ".PodcastActionBar-heading, .PodcastPage-social .SocialBar-heading",
+  "podcast-hostname": ".PodcastPage-hostName",
+  "episode-series-header": "[class$=\"EP-parentInfo\"]",
+  "podcast-header": ".PodcastPage-info",
+  "radio-container": ".RadioShowPage-main, .RSEP-content .RSEP-wrapper",
+  "radio-aside": ".RadioShowPage-aside, .RSEP-aside",
+  "radio-cover-and-title": ".RadioShowPage-top",
+  "radio-byline": ".RadioShowPage-byline",
+  "radio-description": ".RadioShowPage-byline + *",
+  "radio-social-bar": ".RadioShowPage-social",
+  "radio-icon-headings": ".RadioShowPage-social .SocialBar-heading",
+  "radio-hostname": ".RadioShowPage-hostName",
+  "radio-header": ".RadioShowPage-info",
+  "show-landing-container": ".PodcastPage-main, .RadioShowPage-main",
+  "episode-container": ".PCEP-content .PCEP-wrapper, .RSEP-content .RSEP-wrapper",
+  "show-main": "[class$=\"Page-wrapper\"], [class$=\"EP-main\"]",
+  "sidebar-headings": "aside h2, aside h3, aside h4",
+  "episode-meta": ".PCEP-contentInfo, .RSEP-contentInfo",
+  "episode-player": ".PCEP-audioPlayer, .RSEP-audioPlayer",
+  "show-schedule-info": ".RadioShowPage-mediaSchedule, .PodcastPage-podcastSchedule",
+  "news-tile": "ps-promo[data-content-type=\"news-story\"]",
+  "eyebrow": "[class$=\"-category\"]:has(> a), [class$=\"-breadcrumbs\"]:has(a)",
+  "author-info": "[class$=\"-authorName\"], [class$=\"-contributors\"], [class$=\"-hostName\"]",
+  "author-position": "[class$=\"-authorTitle\"]",
+  "timestamp": "[class$=\"-timestamp\"], [class$=\"-timestamp\"] > *",
+  "tab": "ps-tabs .Tabs-tabs-tab",
+  "tab-active": "ps-tabs [role=\"tab\"][data-active=\"true\"], ps-tabs .Tabs-tabs-tab[data-active=\"true\"]",
+  "social-action": ".ActionLink[data-social-service]",
+  "nav-bar": ".PH-nav-bar",
+  "nav-item": ".NavI",
+  "nav-item-list": ".NavI-items",
+  "nav-item-text": ".NavI-text",
+  "dropdown-nav-items": ".DropdownNavigation-items, .NavI .NavLink",
+  "stream-pill-highlighted": ".StreamPill:hover, [playing] .StreamPill",
+});
+
+export const groveContentTypes  = Object.freeze(["ArtP","RSEP"]);
+export const groveNewsStoryType = "ArtP";
+export const groveHeadSuffixes  = Object.freeze(["-breadcrumbs-wrapper","-headline","-contentInfo","-audioPlayer","-parentInfo"]);
+
+export function grove(key) {
+  const value = groveSelectors[key];
+  if (value == null) {
+    throw new Error(
+      `No Grove selector found for key: '${key}'. ` +
+      `Check $grove-selectors-base — or write the raw selector if the class is plainly readable.`
+    );
+  }
+  return value;
+}
+
+export function groveAll(keys, root = document) {
+  const list = Array.isArray(keys) ? keys : [keys];
+  return Array.from(root.querySelectorAll(list.map(grove).join(', ')));
+}
+
+export function groveOne(key, root = document) {
+  return root.querySelector(grove(key));
+}
+
+export function groveVariants(prefix, suffix, letters) {
+  return letters.map(L => `.${prefix}${L}${suffix}`);
+}
+
+export const isNewsStory = el => el?.classList?.contains(groveNewsStoryType);

package/subnav.js

@@ -0,0 +1,51 @@
+// Label a menu for screen readers and mark the current page's link with
+// aria-current="page" and the canopy-current class (or your chosen currentClass).
+// Returns the matching link, or null. Use it to label a menu button:
+//
+//   const current = subnav(container, { label: 'Section' });
+//   disclosure(container, { label: current?.textContent.trim() || 'Section', panel: 'ul' });
+//
+// Call from onGroveRender to update the menu after navigation.
+// Links match by origin and path; query strings and hashes are ignored.
+
+// Ignore trailing slashes when comparing paths.
+function normalizePath(pathname) {
+  return pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+}
+
+export function subnav(container, options = {}) {
+  const {
+    label = "Menu",              // menu name for screen readers
+    currentClass = "canopy-current",
+  } = options;
+
+  const isList = container.matches("ul, ol"); // preserve the list's role
+
+  if (!isList) {
+    if (container.tagName !== "NAV") container.setAttribute("role", "navigation");
+    if (!container.hasAttribute("aria-label")) {
+      container.setAttribute("aria-label", label);
+    }
+  }
+
+  // list-style: none drops the list role in Safari; restore it.
+  const lists = isList ? [container] : container.querySelectorAll("ul, ol");
+  for (const list of lists) list.setAttribute("role", "list");
+
+  const currentPath = normalizePath(location.pathname);
+  let currentLink = null;
+
+  for (const link of container.querySelectorAll("a[href]")) {
+    // An external site's /about is not this site's /about.
+    const isCurrent = link.origin === location.origin
+      && normalizePath(link.pathname) === currentPath;
+    link.classList.toggle(currentClass, isCurrent);
+    if (isCurrent) {
+      link.setAttribute("aria-current", "page");
+      if (!currentLink) currentLink = link; // first match wins
+    } else {
+      link.removeAttribute("aria-current");
+    }
+  }
+  return currentLink;
+}