@sarimarcus/content-sites-ui 0.15.1 → 0.17.0

package/src/navigation/NavMenuLink.astro

@@ -0,0 +1,53 @@
+---
+/**
+ * One row of a desktop dropdown panel. With an icon: an icon box, the label and an optional description; without:
+ * a compact label clamped to two lines. `emphasis` paints the label in the tone (hub links such as "All guides");
+ * `iconStyle="tile"` sets the icon on a tinted square. The row marks itself aria-current when `active`.
+ */
+import { Icon } from '../primitives/index.ts';
+import { TONES } from './tones.ts';
+import type { NavLink, NavTone } from './types.ts';
+
+interface Props {
+  link: NavLink;
+  tone?: NavTone;
+  active?: boolean;
+  size?: 'md' | 'sm';
+  align?: 'start' | 'center';
+  emphasis?: boolean;
+  iconStyle?: 'plain' | 'tile';
+}
+
+const { link, tone = 'primary', active = false, size = 'md', align = 'start', emphasis = false, iconStyle = 'plain' } = Astro.props;
+const t = TONES[tone];
+const hasIcon = Boolean(link.icon);
+const ring = `focus-visible:ring-2 ${t.ring} focus-visible:ring-offset-2`;
+const rowClass = hasIcon
+  ? `flex ${align === 'center' ? 'items-center' : 'items-start'} gap-3 ${size === 'sm' ? 'p-2.5' : 'p-3'} rounded-lg hover:bg-muted transition-colors group ${ring}`
+  : `block p-2.5 rounded-lg hover:bg-muted transition-colors group ${ring}`;
+const boxClass = iconStyle === 'tile'
+  ? `w-8 h-8 rounded-lg ${t.tile} flex items-center justify-center shrink-0 transition-colors`
+  : `${size === 'sm' ? 'w-5 h-5' : 'w-6 h-6'} flex items-center justify-center shrink-0${size === 'sm' && align === 'start' ? ' mt-0.5' : ''}`;
+const iconClass = `${size === 'sm' && iconStyle === 'plain' ? 'w-3.5 h-3.5' : 'w-4 h-4'} ${t.icon}`;
+const labelClass = [
+  emphasis ? `font-semibold ${t.text} ${t.groupStrongHover}` : `font-medium text-foreground ${t.groupHoverText}`,
+  'transition-colors block text-sm',
+  hasIcon ? '' : 'leading-snug line-clamp-2',
+].join(' ').trim();
+---
+
+<a href={link.href} aria-current={active ? 'page' : undefined} class:list={[rowClass, active && `bg-muted font-semibold ${t.text}`]}>
+  {hasIcon && (
+    <div class={boxClass}>
+      <Icon name={link.icon!} class={iconClass} />
+    </div>
+  )}
+  {hasIcon ? (
+    <div>
+      <span class={labelClass}>{link.label}</span>
+      {link.description && <span class="text-xs text-muted-foreground">{link.description}</span>}
+    </div>
+  ) : (
+    <span class={labelClass}>{link.label}</span>
+  )}
+</a>

package/src/navigation/SiteFooter.astro

@@ -0,0 +1,105 @@
+---
+/**
+ * The site footer shell: a brand slot, one column per FooterSection, an optional `bottom` slot, then the copyright
+ * line and the labelled Legal `<nav>` closing with the cookie-preferences button. The button carries
+ * `data-cookie-preferences` instead of an inline handler; footer.ts calls `window.openCookiePreferences()`, which
+ * the site's consent loader defines. Defaults paint the `inverse` surface; the class props restyle each part.
+ */
+import { Icon } from '../primitives/index.ts';
+import type { FooterSection, NavLink, SiteIdentity } from './types.ts';
+
+interface Props {
+  identity: SiteIdentity;
+  sections?: FooterSection[];
+  legal?: NavLink[];
+  cookieLabel?: string;
+  /** Shown between legal items (aria-hidden), e.g. `|`. */
+  separator?: string;
+  year?: number;
+  class?: string;
+  gridClass?: string;
+  brandClass?: string;
+  headingClass?: string;
+  listClass?: string;
+  linkClass?: string;
+  /** Copyright and legal text. */
+  smallClass?: string;
+  dividerClass?: string;
+  legalClass?: string;
+  /** Focus ring shared by every footer control. */
+  ringClass?: string;
+}
+
+const {
+  identity,
+  sections = [],
+  legal = [],
+  cookieLabel = 'Cookie preferences',
+  separator,
+  year = new Date().getFullYear(),
+  class: className = 'bg-inverse text-inverse-muted',
+  gridClass = 'grid grid-cols-2 md:grid-cols-3 lg:grid-cols-3 gap-8 lg:gap-10',
+  brandClass = 'col-span-2 lg:col-span-2',
+  headingClass = 'flex items-center gap-2 text-sm font-medium text-inverse-foreground uppercase tracking-wider mb-4',
+  listClass,
+  linkClass = 'block py-3 text-sm text-inverse-muted/80 hover:text-inverse-foreground transition-colors',
+  smallClass = 'text-xs text-inverse-muted/60',
+  dividerClass = 'border-inverse-muted/10',
+  legalClass = 'gap-x-5 gap-y-2',
+  ringClass = 'rounded focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-inverse',
+} = Astro.props;
+
+const legalItemClass = `${smallClass} hover:text-inverse-foreground transition-colors ${ringClass}`;
+---
+
+<footer class={className}>
+  <div class="mx-auto max-w-shell px-4 sm:px-6 lg:px-8 py-12 lg:py-16">
+    <div class={gridClass}>
+      <div class={brandClass}>
+        <slot name="brand" />
+      </div>
+
+      {sections.map((section) => (
+        <div>
+          <h3 class={headingClass}>
+            {section.icon && <Icon name={section.icon} class="w-4 h-4" />}
+            {section.title}
+          </h3>
+          <ul class={listClass}>
+            {section.links.map((link) => (
+              <li>
+                <a href={link.href} class={`${linkClass} ${ringClass}`}>{link.label}</a>
+              </li>
+            ))}
+          </ul>
+        </div>
+      ))}
+    </div>
+
+    <div class:list={['mt-12 pt-8 border-t', dividerClass]}>
+      <slot name="bottom" />
+      <div class="flex flex-col sm:flex-row justify-between items-center gap-4">
+        <p class={smallClass}>
+          &copy; {year} {identity.name}. All rights reserved.
+        </p>
+        <nav class:list={['flex flex-wrap items-center justify-center sm:justify-end', legalClass]} aria-label="Legal">
+          {legal.map((link) => (
+            <>
+              <a href={link.href} class={legalItemClass}>{link.label}</a>
+              {separator && <span class={`${smallClass} opacity-40`} aria-hidden="true">{separator}</span>}
+            </>
+          ))}
+          <button type="button" class={`${legalItemClass} cursor-pointer bg-transparent border-0 p-0`} data-cookie-preferences>
+            {cookieLabel}
+          </button>
+        </nav>
+      </div>
+    </div>
+  </div>
+</footer>
+
+<script>
+  import { initCookiePreferences } from './footer.ts';
+
+  initCookiePreferences();
+</script>

package/src/navigation/SiteHeader.astro

@@ -0,0 +1,115 @@
+---
+/**
+ * The site header shell: a fixed `<header>` holding the labelled main `<nav>`, a logo slot, the desktop and mobile
+ * action slots and the mobile-menu toggle, then the mobile panel as a sibling of the header (the header's
+ * backdrop-blur would otherwise become the containing block of the fixed panel). The site composes every link,
+ * panel and logo; this component owns the landmarks, the toggle's ARIA and the controller.
+ *
+ * Slots: `logo`, `desktop` (inside the `lg:flex` bar), `actions` (after the desktop bar, every viewport),
+ * `mobile-actions` (before the toggle, below `lg`), `mobile` (the panel content).
+ * `searchPath` (site-relative, e.g. `/search`) turns on the Ctrl/Cmd+K shortcut to `<searchPath>?focus=1`.
+ * The ids default to the ones the sites reserve (`main-nav`, `mobile-menu`, `mobile-menu-btn`). The panel sits outside
+ * `<nav>`, so it carries its own `data-pagefind-ignore`.
+ */
+import { Icon } from '../primitives/index.ts';
+
+interface Props {
+  label?: string;
+  /** Background of the header bar and the mobile panel. */
+  surfaceClass?: string;
+  /** Replaces the header's whole class list (layout included); prefer surfaceClass. */
+  class?: string;
+  toggleClass?: string;
+  openLabel?: string;
+  closeLabel?: string;
+  searchPath?: string;
+  id?: string;
+  panelId?: string;
+  toggleId?: string;
+}
+
+const {
+  label = 'Main navigation',
+  surfaceClass = 'bg-background/95 backdrop-blur-md',
+  class: className = `fixed top-0 left-0 right-0 z-50 transition-[background-color,backdrop-filter,border-color,box-shadow] duration-300 border-b border-border ${surfaceClass}`,
+  toggleClass = 'p-2 min-h-[44px] min-w-[44px] flex items-center justify-center rounded-lg transition-colors text-foreground hover:bg-muted cursor-pointer focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
+  openLabel = 'Open menu',
+  closeLabel = 'Close menu',
+  searchPath,
+  id = 'main-nav',
+  panelId = 'mobile-menu',
+  toggleId = 'mobile-menu-btn',
+} = Astro.props;
+---
+
+<header
+  id={id}
+  class:list={['site-header', className]}
+  data-site-nav
+  data-search-path={searchPath}
+  data-search-base={searchPath ? import.meta.env.BASE_URL : undefined}
+>
+  <nav class="mx-auto max-w-shell px-4 sm:px-6 lg:px-8" aria-label={label}>
+    <div class="flex h-16 items-center justify-between">
+      <slot name="logo" />
+      <div class="hidden lg:flex items-center gap-1">
+        <slot name="desktop" />
+      </div>
+      <slot name="actions" />
+      <div class="lg:hidden flex items-center gap-1">
+        <slot name="mobile-actions" />
+        <button
+          type="button"
+          id={toggleId}
+          class:list={['site-header-toggle', toggleClass]}
+          aria-label={openLabel}
+          aria-expanded="false"
+          aria-controls={panelId}
+          data-mobile-menu-toggle
+          data-open-label={openLabel}
+          data-close-label={closeLabel}
+        >
+          <Icon name="menu" class="w-6 h-6 menu-open-icon" />
+          <Icon name="x" class="w-6 h-6 menu-close-icon" />
+        </button>
+      </div>
+    </div>
+  </nav>
+</header>
+
+<div id={panelId} class:list={['lg:hidden hidden fixed inset-x-0 top-16 bottom-0 z-50 overflow-y-auto overscroll-contain', surfaceClass]} data-pagefind-ignore>
+  <div class="flex flex-col pt-2 pb-12 border-t border-border relative">
+    <slot name="mobile" />
+  </div>
+</div>
+
+<style>
+  .site-header {
+    box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  }
+
+  .site-header:global(.mobile-menu-open) {
+    box-shadow: none;
+  }
+
+  :global(body.mobile-menu-open) {
+    overflow: hidden;
+  }
+
+  /* The icons are Icon components, which scoped selectors do not reach. */
+  .site-header-toggle :global(.menu-close-icon),
+  .site-header-toggle[aria-expanded='true'] :global(.menu-open-icon) {
+    display: none;
+  }
+
+  .site-header-toggle[aria-expanded='true'] :global(.menu-close-icon) {
+    display: block;
+  }
+</style>
+
+<script>
+  import { initNavigation } from './navigation.ts';
+
+  initNavigation();
+  document.addEventListener('astro:page-load', initNavigation);
+</script>

package/src/navigation/activePath.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether `href` is the current section: the page itself or a page below it, on a path-segment boundary
+ * (`/plan` matches `/plan` and `/plan/x`, not `/planning`). The home page matches only itself.
+ * Both sides are normalised page paths (core/url normalizePagePath, url()).
+ */
+export function isActivePath(currentPath: string, href: string): boolean {
+  const target = href.replace(/\/+$/, '');
+  const current = currentPath.replace(/\/+$/, '');
+  if (target === '') return current === '';
+  return current === target || current.startsWith(`${target}/`);
+}

package/src/navigation/footer.ts

@@ -0,0 +1,19 @@
+// The footer's cookie-preferences button. One delegated listener per page, so any number of buttons work and a
+// re-run binds nothing twice. The consent loader owns window.openCookiePreferences.
+
+declare global {
+  interface Window {
+    openCookiePreferences?: () => void;
+  }
+}
+
+let bound = false;
+
+export function initCookiePreferences(): void {
+  if (bound) return;
+  bound = true;
+  document.addEventListener('click', (event) => {
+    const target = event.target;
+    if (target instanceof Element && target.closest('[data-cookie-preferences]')) window.openCookiePreferences?.();
+  });
+}

package/src/navigation/index.ts

@@ -1,2 +1,10 @@
-// Public surface of @sarimarcus/content-sites-ui/navigation. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-ui/navigation: site chrome shells. Sites compose every link, panel and
+// logo; these own landmarks, ARIA state and the bundled controllers.
+export { default as SiteHeader } from './SiteHeader.astro';
+export { default as NavDropdown } from './NavDropdown.astro';
+export { default as MobileNavSection } from './MobileNavSection.astro';
+export { default as SiteFooter } from './SiteFooter.astro';
+export { default as NavMenuLink } from './NavMenuLink.astro';
+export { default as MobileNavLink } from './MobileNavLink.astro';
+export { isActivePath } from './activePath.ts';
+export type { SiteIdentity, NavLink, NavGroup, FooterSection, NavTone } from './types.ts';

package/src/navigation/navigation.ts

@@ -0,0 +1,155 @@
+// Site header controller: dropdowns (click, hover with a close delay, ArrowDown/ArrowUp/Escape, outside click,
+// focus leaving), the mobile menu (toggle, Escape from anywhere, focus into the panel on open), the single-open
+// mobile accordion and the Ctrl/Cmd+K search shortcut. Every root is bound once; document listeners are bound once
+// per page however many headers it holds, so re-running it on astro:page-load is safe.
+
+const CLOSE_DELAY = 150;
+let documentBound = false;
+
+const roots = () => Array.from(document.querySelectorAll<HTMLElement>('[data-site-nav]'));
+const dropdownButtons = (scope: ParentNode = document) =>
+  Array.from(scope.querySelectorAll<HTMLButtonElement>('[data-nav-dropdown-button]'));
+const controlled = (el: Element) => {
+  const id = el.getAttribute('aria-controls');
+  return id ? document.getElementById(id) : null;
+};
+
+function setDropdown(button: HTMLButtonElement, open: boolean): void {
+  if (open) dropdownButtons().forEach((other) => other !== button && other.setAttribute('aria-expanded', 'false'));
+  button.setAttribute('aria-expanded', String(open));
+}
+
+function setMobileMenu(root: HTMLElement, toggle: HTMLButtonElement, open: boolean, focus: boolean): void {
+  const panel = controlled(toggle);
+  if (!panel) return;
+  toggle.setAttribute('aria-expanded', String(open));
+  toggle.setAttribute('aria-label', (open ? toggle.dataset.closeLabel : toggle.dataset.openLabel) ?? '');
+  panel.classList.toggle('hidden', !open);
+  root.classList.toggle('mobile-menu-open', open);
+  document.body.classList.toggle('mobile-menu-open', open);
+  if (!focus) return;
+  if (open) panel.querySelector<HTMLElement>('button, a')?.focus();
+  else toggle.focus();
+}
+
+function bindDropdown(dropdown: HTMLElement): void {
+  const button = dropdown.querySelector<HTMLButtonElement>('[data-nav-dropdown-button]');
+  const menu = button && controlled(button);
+  if (!button || !menu) return;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  // A pointer that hovered the dropdown open then clicks the trigger means "open", not "toggle closed".
+  let openedByHover = false;
+
+  button.addEventListener('click', () => {
+    const open = openedByHover || button.getAttribute('aria-expanded') !== 'true';
+    openedByHover = false;
+    setDropdown(button, open);
+  });
+  button.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape') {
+      setDropdown(button, false);
+      button.focus();
+    } else if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      setDropdown(button, true);
+      menu.querySelector<HTMLElement>('a')?.focus();
+    }
+  });
+  menu.addEventListener('keydown', (event) => {
+    const links = Array.from(menu.querySelectorAll<HTMLElement>('a'));
+    const index = links.indexOf(document.activeElement as HTMLElement);
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      (links[index + 1] ?? links[0])?.focus();
+    } else if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      if (index <= 0) button.focus();
+      else links[index - 1]?.focus();
+    } else if (event.key === 'Escape') {
+      setDropdown(button, false);
+      button.focus();
+    }
+  });
+  dropdown.addEventListener('mouseenter', () => {
+    clearTimeout(timer);
+    openedByHover = button.getAttribute('aria-expanded') !== 'true';
+    setDropdown(button, true);
+  });
+  dropdown.addEventListener('mouseleave', () => {
+    openedByHover = false;
+    timer = setTimeout(() => setDropdown(button, false), CLOSE_DELAY);
+  });
+  dropdown.addEventListener('focusout', (event) => {
+    const next = event.relatedTarget;
+    if (next instanceof Node && dropdown.contains(next)) return;
+    button.setAttribute('aria-expanded', 'false');
+  });
+}
+
+function bindAccordion(panel: HTMLElement): void {
+  const buttons = Array.from(panel.querySelectorAll<HTMLButtonElement>('[data-mobile-section-button]'));
+  buttons.forEach((button) => {
+    button.addEventListener('click', () => {
+      const open = button.getAttribute('aria-expanded') !== 'true';
+      if (open) {
+        buttons.forEach((other) => {
+          if (other === button) return;
+          other.setAttribute('aria-expanded', 'false');
+          controlled(other)?.classList.add('hidden');
+        });
+      }
+      button.setAttribute('aria-expanded', String(open));
+      controlled(button)?.classList.toggle('hidden', !open);
+    });
+  });
+}
+
+function searchPathOf(root: HTMLElement): string | null {
+  const path = root.dataset.searchPath;
+  if (!path) return null;
+  const compiled = (root.dataset.searchBase ?? '/').replace(/\/$/, '');
+  return (window.location.pathname.indexOf(compiled) === 0 ? compiled : '') + path;
+}
+
+function bindDocument(): void {
+  if (documentBound) return;
+  documentBound = true;
+
+  document.addEventListener('click', (event) => {
+    const target = event.target;
+    if (!(target instanceof Element) || target.closest('[data-nav-dropdown]')) return;
+    dropdownButtons().forEach((button) => button.setAttribute('aria-expanded', 'false'));
+  });
+
+  document.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape') {
+      roots().forEach((root) => {
+        const toggle = root.querySelector<HTMLButtonElement>('[data-mobile-menu-toggle]');
+        if (toggle?.getAttribute('aria-expanded') === 'true') setMobileMenu(root, toggle, false, true);
+      });
+      return;
+    }
+    if (!(event.metaKey || event.ctrlKey) || event.key !== 'k') return;
+    const searchPath = roots().map(searchPathOf).find(Boolean);
+    if (!searchPath) return;
+    // On the search page itself the page input owns the shortcut.
+    const current = window.location.pathname;
+    if (current === searchPath || current === `${searchPath}/`) return;
+    event.preventDefault();
+    window.location.assign(`${searchPath}?focus=1`);
+  });
+}
+
+export function initNavigation(): void {
+  bindDocument();
+  roots().forEach((root) => {
+    if (root.hasAttribute('data-site-nav-ready')) return;
+    root.setAttribute('data-site-nav-ready', '');
+    root.querySelectorAll<HTMLElement>('[data-nav-dropdown]').forEach(bindDropdown);
+    const toggle = root.querySelector<HTMLButtonElement>('[data-mobile-menu-toggle]');
+    const panel = toggle && controlled(toggle);
+    if (!toggle || !panel) return;
+    toggle.addEventListener('click', () => setMobileMenu(root, toggle, toggle.getAttribute('aria-expanded') !== 'true', true));
+    bindAccordion(panel);
+  });
+}

package/src/navigation/tones.ts

@@ -0,0 +1,33 @@
+import type { NavTone } from './types.ts';
+
+// Literal class strings per tone, so Tailwind's scanner sees every utility the navigation components emit.
+export const TONES: Record<NavTone, {
+  text: string;
+  hoverText: string;
+  groupHoverText: string;
+  strongHover: string;
+  groupStrongHover: string;
+  ring: string;
+  icon: string;
+  iconDim: string;
+  tile: string;
+}> = {
+  primary: {
+    text: 'text-primary', hoverText: 'hover:text-primary', groupHoverText: 'group-hover:text-primary',
+    strongHover: 'hover:text-primary-strong', groupStrongHover: 'group-hover:text-primary-strong',
+    ring: 'focus-visible:ring-primary', icon: 'text-primary', iconDim: 'text-primary/60',
+    tile: 'bg-primary/10 group-hover:bg-primary/20',
+  },
+  secondary: {
+    text: 'text-secondary', hoverText: 'hover:text-secondary', groupHoverText: 'group-hover:text-secondary',
+    strongHover: 'hover:text-secondary-strong', groupStrongHover: 'group-hover:text-secondary-strong',
+    ring: 'focus-visible:ring-secondary', icon: 'text-secondary', iconDim: 'text-secondary/60',
+    tile: 'bg-secondary/10 group-hover:bg-secondary/20',
+  },
+  accent: {
+    text: 'text-accent', hoverText: 'hover:text-accent', groupHoverText: 'group-hover:text-accent',
+    strongHover: 'hover:text-accent-strong', groupStrongHover: 'group-hover:text-accent-strong',
+    ring: 'focus-visible:ring-accent', icon: 'text-accent', iconDim: 'text-accent/60',
+    tile: 'bg-accent/10 group-hover:bg-accent/20',
+  },
+};

package/src/navigation/types.ts

@@ -0,0 +1,33 @@
+// Public contracts for site chrome. Sites own every value: labels, hrefs, icons, logos and copy.
+
+/** Who the site is, as the header, footer and copyright line name it. */
+export interface SiteIdentity {
+  name: string;
+  tagline?: string;
+  homeHref?: string;
+}
+
+export interface NavLink {
+  label: string;
+  href: string;
+  description?: string;
+  /** Lucide icon name for the ui Icon primitive. */
+  icon?: string;
+}
+
+export interface NavGroup {
+  id: string;
+  label: string;
+  icon?: string;
+  links: NavLink[];
+}
+
+export interface FooterSection {
+  title: string;
+  /** Lucide icon name shown before the heading. */
+  icon?: string;
+  links: NavLink[];
+}
+
+/** The colour role a navigation item is tinted with. */
+export type NavTone = 'primary' | 'secondary' | 'accent';

package/src/search/SearchSuggestions.astro

@@ -0,0 +1,26 @@
+---
+/** The empty-state suggestion chips of a search page; each button carries the query it runs (data-search-suggest). */
+interface Props {
+  label: string;
+  suggestions: { label: string; query: string }[];
+}
+
+const { label, suggestions } = Astro.props;
+---
+
+<p class="search-suggestions__label">{label}</p>
+<ul class="search-suggestions">
+  {
+    suggestions.map((s) => (
+      <li>
+        <button
+          type="button"
+          class="search-chip search-chip--suggest"
+          data-search-suggest={s.query}
+        >
+          {s.label}
+        </button>
+      </li>
+    ))
+  }
+</ul>

package/src/search/index.ts

@@ -0,0 +1,5 @@
+// Public surface of @sarimarcus/content-sites-ui/search: search-page building blocks. The site keeps its page, its
+// type taxonomy, its copy and its Pagefind index.
+export { default as SearchSuggestions } from './SearchSuggestions.astro';
+export { appendResults } from './renderResult.ts';
+export type { PagefindResultFragment, SearchTaxonomy, SearchTypeMeta } from './renderResult.ts';