@db-vincent/components 0.0.0-stage → 0.1.0

package/src/astro/Navbar.astro

@@ -0,0 +1,756 @@
+---
+import Icon from "./Icon.astro";
+import "../styles/navbar.css";
+
+/**
+ * Navigation bar for the top of an app view, built on the navigation-menu
+ * model: a row of triggers and links, one shared viewport that resizes and
+ * slides between panels, and rich rows that pair a title with a one-line
+ * description.
+ *
+ * - An item with `children` or `groups` is a trigger that opens a panel.
+ *   `layout` picks the panel shape: "list" (one column), "grid" (two
+ *   columns) or "featured" (a highlight card next to a list).
+ * - An item without them is a plain link.
+ * - The bar responds to its own width (a container query), not the window,
+ *   so it collapses correctly inside any layout, including a demo frame.
+ *   When the full row no longer fits, it becomes a menu button that opens
+ *   a modal sheet (without script: below 720px of bar width):
+ *   focus is trapped, the page is inert and cannot scroll, Escape and the
+ *   backdrop close it, and focus returns to the button.
+ * - Slots: `start` (context such as breadcrumbs), `actions` (utilities
+ *   such as a theme toggle) and `sheet-footer` (extra content at the end of
+ *   the mobile sheet).
+ */
+
+interface NavLink {
+  label: string;
+  href: string;
+  /** One-line summary under the label. */
+  description?: string;
+  /** Icon name from the functional icon set. */
+  icon?: string;
+  active?: boolean;
+}
+
+interface NavGroup {
+  /** Overline for the cluster; omit for an unlabelled cluster. */
+  label?: string;
+  items: NavLink[];
+}
+
+interface NavFeature {
+  title: string;
+  href: string;
+  description?: string;
+  /** Small overline above the title. */
+  eyebrow?: string;
+  icon?: string;
+}
+
+interface NavItem {
+  label: string;
+  /** Destination for a plain link. Menu items also expose it as an
+   * "Overview" row so the section itself stays reachable. */
+  href?: string;
+  icon?: string;
+  active?: boolean;
+  /** Flat list of destinations. */
+  children?: NavLink[];
+  /** Labelled clusters of destinations, one column each. */
+  groups?: NavGroup[];
+  layout?: "list" | "grid" | "featured";
+  /** Highlight card for the "featured" layout. */
+  feature?: NavFeature;
+}
+
+interface FooterLink {
+  label: string;
+  href: string;
+}
+
+interface Props {
+  /** Accessible label for the nav landmark. */
+  label?: string;
+  items?: NavItem[];
+  brand?: string;
+  brandHref?: string;
+  /** Pin the bar to the top; a blurred tint appears once content scrolls under it. */
+  sticky?: boolean;
+  /** Secondary links (about, support, legal) shown in two columns at the
+   * foot of the mobile menu. */
+  footerLinks?: FooterLink[];
+  navId?: string;
+  class?: string;
+}
+
+const {
+  label = "Main",
+  items = [],
+  brand,
+  brandHref = "/",
+  sticky = false,
+  footerLinks = [],
+  navId = `navbar-${Math.random().toString(36).slice(2, 9)}`,
+  class: className,
+} = Astro.props;
+
+const sheetId = `${navId}-sheet`;
+const panelId = (index: number) => `${navId}-panel-${index}`;
+const hasMenu = (item: NavItem) =>
+  Boolean(item.children?.length || item.groups?.length || item.feature);
+const linksOf = (item: NavItem): NavLink[] =>
+  item.groups?.length
+    ? item.groups.flatMap((group) => group.items)
+    : (item.children ?? []);
+const isCurrent = (item: NavItem) =>
+  Boolean(item.active || linksOf(item).some((child) => child.active));
+const layoutOf = (item: NavItem) =>
+  item.groups?.length
+    ? "groups"
+    : item.feature
+      ? "featured"
+      : (item.layout ?? "list");
+const hasSheetFooter = Astro.slots.has("sheet-footer");
+---
+
+<header
+  class:list={["ds-navbar", sticky && "ds-navbar--sticky", className]}
+  data-navbar
+>
+  <div class="ds-navbar__inner">
+    {brand && (
+      <a class="ds-navbar__brand" href={brandHref}>
+        <span class="ds-navbar__mark" aria-hidden="true">
+          <Icon name="terminal" size={16} />
+        </span>
+        <span>{brand}</span>
+      </a>
+    )}
+    <div class="ds-navbar__start">
+      <slot name="start" />
+    </div>
+
+    {items.length > 0 && (
+      <nav id={navId} class="ds-navbar__nav" aria-label={label}>
+        <ul class="ds-navbar__list">
+          {items.map((item, index) => (
+            <li class="ds-navbar__item">
+              {hasMenu(item) ? (
+                <button
+                  class:list={[
+                    "ds-navbar__trigger",
+                    isCurrent(item) && "is-current",
+                  ]}
+                  type="button"
+                  aria-expanded="false"
+                  aria-controls={panelId(index)}
+                  data-navbar-trigger={panelId(index)}
+                >
+                  {item.icon && <Icon name={item.icon} size={16} />}
+                  <span>{item.label}</span>
+                  <Icon
+                    name="chevron-down"
+                    size={14}
+                    class="ds-navbar__chevron"
+                  />
+                </button>
+              ) : (
+                <a
+                  class="ds-navbar__trigger"
+                  href={item.href ?? "#"}
+                  aria-current={item.active ? "page" : undefined}
+                  data-navbar-link
+                >
+                  {item.icon && <Icon name={item.icon} size={16} />}
+                  <span>{item.label}</span>
+                </a>
+              )}
+            </li>
+          ))}
+        </ul>
+
+        <div class="ds-navbar__viewport" data-navbar-viewport hidden>
+          {items.map(
+            (item, index) =>
+              hasMenu(item) && (
+                <div
+                  class:list={[
+                    "ds-navbar__panel",
+                    `ds-navbar__panel--${layoutOf(item)}`,
+                  ]}
+                  id={panelId(index)}
+                  data-navbar-panel
+                  hidden
+                >
+                  {item.feature && (
+                    <a
+                      class="ds-navbar__feature"
+                      href={item.feature.href}
+                      data-navbar-row
+                    >
+                      {item.feature.icon && (
+                        <span
+                          class="ds-navbar__feature-icon"
+                          aria-hidden="true"
+                        >
+                          <Icon name={item.feature.icon} size={20} />
+                        </span>
+                      )}
+                      {item.feature.eyebrow && (
+                        <span class="ds-navbar__eyebrow">
+                          {item.feature.eyebrow}
+                        </span>
+                      )}
+                      <span class="ds-navbar__feature-title">
+                        {item.feature.title}
+                      </span>
+                      {item.feature.description && (
+                        <span class="ds-navbar__row-desc">
+                          {item.feature.description}
+                        </span>
+                      )}
+                    </a>
+                  )}
+                  {(item.groups?.length
+                    ? item.groups
+                    : [{ items: item.children ?? [] }]
+                  ).map((group: NavGroup) => (
+                    <div class="ds-navbar__group">
+                      {group.label && (
+                        <p class="ds-navbar__eyebrow">{group.label}</p>
+                      )}
+                      <ul class="ds-navbar__rows">
+                        {group.items.map((child) => (
+                          <li>
+                            <a
+                              class="ds-navbar__row"
+                              href={child.href}
+                              aria-current={child.active ? "page" : undefined}
+                              data-navbar-row
+                            >
+                              {child.icon && (
+                                <span
+                                  class="ds-navbar__row-icon"
+                                  aria-hidden="true"
+                                >
+                                  <Icon name={child.icon} size={16} />
+                                </span>
+                              )}
+                              <span class="ds-navbar__row-body">
+                                <span class="ds-navbar__row-title">
+                                  {child.label}
+                                </span>
+                                {child.description && (
+                                  <span class="ds-navbar__row-desc">
+                                    {child.description}
+                                  </span>
+                                )}
+                              </span>
+                            </a>
+                          </li>
+                        ))}
+                      </ul>
+                    </div>
+                  ))}
+                </div>
+              ),
+          )}
+        </div>
+      </nav>
+    )}
+
+    <div class="ds-navbar__actions">
+      <slot name="actions" />
+    </div>
+
+    {items.length > 0 && (
+      <button
+        class="ds-navbar__toggle"
+        type="button"
+        aria-haspopup="dialog"
+        aria-expanded="false"
+        aria-controls={sheetId}
+        aria-label="Open navigation menu"
+        data-navbar-toggle
+      >
+        <Icon name="menu" size={20} />
+      </button>
+    )}
+  </div>
+
+  {items.length > 0 && (
+    <dialog
+      class="ds-navbar__sheet"
+      id={sheetId}
+      aria-label={`${label} navigation`}
+      data-navbar-sheet
+    >
+      <div class="ds-navbar__sheet-head">
+        {brand ? (
+          <a class="ds-navbar__brand" href={brandHref}>
+            <span class="ds-navbar__mark" aria-hidden="true">
+              <Icon name="terminal" size={16} />
+            </span>
+            <span>{brand}</span>
+          </a>
+        ) : (
+          <span class="ds-navbar__sheet-title">{label}</span>
+        )}
+        <form method="dialog">
+          <button
+            class="ds-navbar__toggle ds-navbar__sheet-close"
+            type="submit"
+            aria-label="Close navigation menu"
+          >
+            <Icon name="x" size={20} />
+          </button>
+        </form>
+      </div>
+
+      <nav class="ds-navbar__sheet-nav" aria-label={label}>
+        <ul class="ds-navbar__sheet-list">
+          {items.map((item) =>
+            hasMenu(item) ? (
+              <li>
+                <details
+                  class="ds-navbar__disclosure"
+                  open={isCurrent(item) ? true : undefined}
+                >
+                  <summary
+                    class:list={[
+                      "ds-navbar__sheet-link",
+                      isCurrent(item) && "is-current",
+                    ]}
+                  >
+                    {item.icon && <Icon name={item.icon} size={20} />}
+                    <span>{item.label}</span>
+                    <Icon
+                      name="chevron-down"
+                      size={16}
+                      class="ds-navbar__chevron"
+                    />
+                  </summary>
+                  <div class="ds-navbar__sheet-panel">
+                    {item.feature && (
+                      <a
+                        class="ds-navbar__sheet-sublink"
+                        href={item.feature.href}
+                      >
+                        <span class="ds-navbar__row-title">
+                          {item.feature.title}
+                        </span>
+                        {item.feature.description && (
+                          <span class="ds-navbar__row-desc">
+                            {item.feature.description}
+                          </span>
+                        )}
+                      </a>
+                    )}
+                    {(item.groups?.length
+                      ? item.groups
+                      : [{ items: item.children ?? [] }]
+                    ).map((group: NavGroup) => (
+                      <div class="ds-navbar__sheet-group">
+                        {group.label && (
+                          <p class="ds-navbar__eyebrow">{group.label}</p>
+                        )}
+                        <ul>
+                          {group.items.map((child) => (
+                            <li>
+                              <a
+                                class="ds-navbar__sheet-sublink"
+                                href={child.href}
+                                aria-current={child.active ? "page" : undefined}
+                              >
+                                <span class="ds-navbar__row-title">
+                                  {child.label}
+                                </span>
+                                {child.description && (
+                                  <span class="ds-navbar__row-desc">
+                                    {child.description}
+                                  </span>
+                                )}
+                              </a>
+                            </li>
+                          ))}
+                        </ul>
+                      </div>
+                    ))}
+                  </div>
+                </details>
+              </li>
+            ) : (
+              <li>
+                <a
+                  class="ds-navbar__sheet-link"
+                  href={item.href ?? "#"}
+                  aria-current={item.active ? "page" : undefined}
+                >
+                  {item.icon && <Icon name={item.icon} size={20} />}
+                  <span>{item.label}</span>
+                </a>
+              </li>
+            ),
+          )}
+        </ul>
+      </nav>
+
+      {(footerLinks.length > 0 || hasSheetFooter) && (
+        <div class="ds-navbar__sheet-footer">
+          {footerLinks.length > 0 && (
+            <ul class="ds-navbar__sheet-meta">
+              {footerLinks.map((link) => (
+                <li>
+                  <a href={link.href}>{link.label}</a>
+                </li>
+              ))}
+            </ul>
+          )}
+          {hasSheetFooter && (
+            <div class="ds-navbar__sheet-actions">
+              <slot name="sheet-footer" />
+            </div>
+          )}
+        </div>
+      )}
+    </dialog>
+  )}
+</header>
+
+<script>
+  const OPEN_DELAY = 120;
+  const CLOSE_DELAY = 260;
+  const canHover = () =>
+    window.matchMedia("(hover: hover) and (pointer: fine)").matches;
+
+  const bindNavbar = (navbar: HTMLElement) => {
+    if (navbar.dataset.navbarBound) return;
+    navbar.dataset.navbarBound = "true";
+
+    const nav = navbar.querySelector<HTMLElement>(".ds-navbar__nav");
+    const viewport = navbar.querySelector<HTMLElement>(
+      "[data-navbar-viewport]",
+    );
+    const triggers = Array.from(
+      navbar.querySelectorAll<HTMLButtonElement>("[data-navbar-trigger]"),
+    );
+    const topLevel = Array.from(
+      navbar.querySelectorAll<HTMLElement>(".ds-navbar__list > li > *"),
+    );
+    const toggle = navbar.querySelector<HTMLButtonElement>(
+      "[data-navbar-toggle]",
+    );
+    const sheet = navbar.querySelector<HTMLDialogElement>(
+      "[data-navbar-sheet]",
+    );
+
+    let current: HTMLButtonElement | null = null;
+    let openTimer = 0;
+    let closeTimer = 0;
+
+    const panelFor = (trigger: HTMLButtonElement) =>
+      document.getElementById(trigger.dataset.navbarTrigger ?? "");
+    const rowsOf = (panel: HTMLElement | null) =>
+      panel
+        ? Array.from(panel.querySelectorAll<HTMLElement>("[data-navbar-row]"))
+        : [];
+
+    // The viewport is one surface. It is placed under the open trigger,
+    // clamped inside the bar, and sized to the panel it shows, so moving
+    // between triggers slides and resizes it instead of swapping boxes.
+    const place = (trigger: HTMLButtonElement, panel: HTMLElement) => {
+      if (!viewport || !nav) return;
+      const navBox = nav.getBoundingClientRect();
+      const barBox = navbar.getBoundingClientRect();
+      const triggerBox = trigger.getBoundingClientRect();
+      const width = panel.offsetWidth;
+      const height = panel.offsetHeight;
+      const gutter = 8;
+      const minLeft = barBox.left - navBox.left + gutter;
+      const maxLeft = barBox.right - navBox.left - width - gutter;
+      const left = Math.max(
+        minLeft,
+        Math.min(triggerBox.left - navBox.left, maxLeft),
+      );
+      viewport.style.setProperty("--ds-navbar-viewport-x", `${left}px`);
+      viewport.style.setProperty("--ds-navbar-viewport-w", `${width}px`);
+      viewport.style.setProperty("--ds-navbar-viewport-h", `${height}px`);
+    };
+
+    const open = (
+      trigger: HTMLButtonElement,
+      focusRow: "first" | "last" | null = null,
+    ) => {
+      window.clearTimeout(closeTimer);
+      const panel = panelFor(trigger);
+      if (!viewport || !panel) return;
+      const wasOpen = current !== null;
+      triggers.forEach((other) => {
+        const active = other === trigger;
+        other.setAttribute("aria-expanded", String(active));
+        const otherPanel = panelFor(other);
+        if (otherPanel) otherPanel.hidden = !active;
+      });
+      viewport.hidden = false;
+      viewport.dataset.instant = wasOpen ? "false" : "true";
+      current = trigger;
+      place(trigger, panel);
+      if (focusRow) {
+        const rows = rowsOf(panel);
+        (focusRow === "first" ? rows[0] : rows[rows.length - 1])?.focus();
+      }
+    };
+
+    const close = (returnFocus = false) => {
+      window.clearTimeout(openTimer);
+      window.clearTimeout(closeTimer);
+      if (!current || !viewport) return;
+      const trigger = current;
+      current = null;
+      triggers.forEach((other) => other.setAttribute("aria-expanded", "false"));
+      viewport.hidden = true;
+      viewport
+        .querySelectorAll<HTMLElement>("[data-navbar-panel]")
+        .forEach((panel) => (panel.hidden = true));
+      if (returnFocus) trigger.focus();
+    };
+
+    const focusTopLevel = (from: HTMLElement, step: 1 | -1) => {
+      const index = topLevel.indexOf(from);
+      if (index < 0) return;
+      const next = topLevel[(index + step + topLevel.length) % topLevel.length];
+      next.focus();
+      if (
+        current &&
+        next instanceof HTMLButtonElement &&
+        next.dataset.navbarTrigger
+      ) {
+        open(next);
+      } else if (current) {
+        close();
+      }
+    };
+
+    triggers.forEach((trigger) => {
+      trigger.addEventListener("click", () => {
+        if (current === trigger) close();
+        else open(trigger);
+      });
+
+      trigger.addEventListener("keydown", (event) => {
+        if (event.key === "ArrowDown") {
+          event.preventDefault();
+          open(trigger, "first");
+        } else if (event.key === "ArrowUp") {
+          event.preventDefault();
+          open(trigger, "last");
+        }
+      });
+
+      trigger.addEventListener("pointerenter", (event) => {
+        if (event.pointerType !== "mouse" || !canHover()) return;
+        window.clearTimeout(closeTimer);
+        window.clearTimeout(openTimer);
+        if (current) open(trigger);
+        else openTimer = window.setTimeout(() => open(trigger), OPEN_DELAY);
+      });
+    });
+
+    topLevel.forEach((item) => {
+      item.addEventListener("keydown", (event) => {
+        if (event.key === "ArrowRight") {
+          event.preventDefault();
+          focusTopLevel(item, 1);
+        } else if (event.key === "ArrowLeft") {
+          event.preventDefault();
+          focusTopLevel(item, -1);
+        }
+      });
+      // Hovering a plain link while a panel is open closes the panel, as in
+      // a menubar: the pointer has moved on.
+      if (!(item instanceof HTMLButtonElement)) {
+        item.addEventListener("pointerenter", (event) => {
+          if (event.pointerType === "mouse" && current) {
+            closeTimer = window.setTimeout(() => close(), CLOSE_DELAY / 2);
+          }
+        });
+      }
+    });
+
+    if (nav && viewport) {
+      nav.addEventListener("pointerleave", (event) => {
+        if (event.pointerType !== "mouse" || !canHover()) return;
+        window.clearTimeout(openTimer);
+        closeTimer = window.setTimeout(() => close(), CLOSE_DELAY);
+      });
+      viewport.addEventListener("pointerenter", () =>
+        window.clearTimeout(closeTimer),
+      );
+
+      viewport.addEventListener("keydown", (event) => {
+        if (!current) return;
+        const rows = rowsOf(panelFor(current));
+        const index = rows.indexOf(document.activeElement as HTMLElement);
+        if (event.key === "ArrowDown") {
+          event.preventDefault();
+          rows[Math.min(rows.length - 1, index + 1)]?.focus();
+        } else if (event.key === "ArrowUp") {
+          event.preventDefault();
+          if (index <= 0) close(true);
+          else rows[index - 1]?.focus();
+        } else if (event.key === "Home") {
+          event.preventDefault();
+          rows[0]?.focus();
+        } else if (event.key === "End") {
+          event.preventDefault();
+          rows[rows.length - 1]?.focus();
+        } else if (event.key === "Tab") {
+          // The viewport sits after the row in the DOM; Tab continues to the
+          // next top-level item instead of skipping it.
+          const trigger = current;
+          if (!event.shiftKey && index === rows.length - 1) {
+            event.preventDefault();
+            close();
+            const next = topLevel[topLevel.indexOf(trigger) + 1];
+            if (next) next.focus();
+            else trigger.focus();
+          } else if (event.shiftKey && index === 0) {
+            event.preventDefault();
+            close(true);
+          }
+        }
+      });
+
+      viewport.addEventListener("click", (event) => {
+        if ((event.target as Element).closest("a[href]")) close();
+      });
+    }
+
+    navbar.addEventListener("keydown", (event) => {
+      if (event.key === "Escape" && current) {
+        event.preventDefault();
+        close(true);
+      }
+    });
+
+    navbar.addEventListener("focusout", (event) => {
+      const next = event.relatedTarget as Node | null;
+      if (current && next && !nav?.contains(next)) close();
+    });
+
+    document.addEventListener("pointerdown", (event) => {
+      if (current && !nav?.contains(event.target as Node)) close();
+    });
+
+    window.addEventListener("resize", () => {
+      if (current) {
+        const panel = panelFor(current);
+        if (panel) place(current, panel);
+      }
+    });
+
+    // Mobile sheet: a modal dialog, so the browser supplies the focus trap,
+    // the inert page and Escape. Scroll lock is CSS (:has(dialog[open])).
+    if (toggle && sheet) {
+      toggle.addEventListener("click", () => {
+        close();
+        sheet.showModal();
+        toggle.setAttribute("aria-expanded", "true");
+        sheet
+          .querySelector<HTMLElement>(
+            ".ds-navbar__sheet-nav [aria-current='page'], .ds-navbar__sheet-nav a, .ds-navbar__sheet-nav summary",
+          )
+          ?.focus();
+      });
+      sheet.addEventListener("close", () => {
+        toggle.setAttribute("aria-expanded", "false");
+        toggle.focus();
+      });
+      sheet.addEventListener("click", (event) => {
+        if (event.target === sheet) {
+          sheet.close();
+          return;
+        }
+        if ((event.target as Element).closest("a[href]")) sheet.close();
+      });
+    }
+
+    // Fit-based collapse: measure the full row once (expanded), then collapse
+    // whenever the bar is narrower than that. Re-measure when fonts load.
+    const inner = navbar.querySelector<HTMLElement>(".ds-navbar__inner");
+    let needed = 0;
+    const measure = () => {
+      if (!inner || !nav) return;
+      navbar.dataset.collapsed = "false";
+      const style = getComputedStyle(inner);
+      const gap = Number.parseFloat(style.columnGap) || 0;
+      const children = Array.from(inner.children).filter(
+        (child) =>
+          child !== toggle && getComputedStyle(child).display !== "none",
+      ) as HTMLElement[];
+      needed =
+        children.reduce((sum, child) => sum + child.scrollWidth, 0) +
+        gap * Math.max(0, children.length - 1) +
+        (Number.parseFloat(style.paddingInlineStart) || 0) +
+        (Number.parseFloat(style.paddingInlineEnd) || 0);
+    };
+    const fit = () => {
+      if (!inner || !nav) return;
+      const collapsed = navbar.clientWidth < needed;
+      navbar.dataset.collapsed = String(collapsed);
+      if (collapsed) close();
+      else if (sheet?.open) sheet.close();
+    };
+    if (nav) {
+      measure();
+      fit();
+      new ResizeObserver(fit).observe(navbar);
+      document.fonts?.ready.then(() => {
+        measure();
+        fit();
+      });
+    }
+
+    // Scrolled state: only a sticky bar has content passing under it. It
+    // listens to its own scroll container (the window, or the nearest
+    // scrolling ancestor), so it also works inside a scrolling panel.
+    if (navbar.classList.contains("ds-navbar--sticky")) {
+      const scrollParent = (() => {
+        for (let el = navbar.parentElement; el; el = el.parentElement) {
+          const { overflowY } = getComputedStyle(el);
+          if (
+            /(auto|scroll|overlay)/.test(overflowY) &&
+            el.scrollHeight > el.clientHeight
+          ) {
+            return el;
+          }
+        }
+        return null;
+      })();
+      const offset = () =>
+        scrollParent ? scrollParent.scrollTop : window.scrollY;
+      let ticking = false;
+      const syncScrolled = () => {
+        navbar.dataset.scrolled = offset() > 4 ? "true" : "false";
+        ticking = false;
+      };
+      (scrollParent ?? window).addEventListener(
+        "scroll",
+        () => {
+          if (!ticking) {
+            ticking = true;
+            requestAnimationFrame(syncScrolled);
+          }
+        },
+        { passive: true },
+      );
+      syncScrolled();
+    }
+  };
+
+  const bindAll = () =>
+    document.querySelectorAll<HTMLElement>("[data-navbar]").forEach(bindNavbar);
+  bindAll();
+  document.addEventListener("astro:page-load", bindAll);
+</script>