blume 0.0.0 → 0.1.0

package/src/components/layout/Header.astro

@@ -0,0 +1,188 @@
+---
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
+import { GITHUB_MARK } from "../github-mark.ts";
+import Icon from "../Icon.astro";
+import LanguageSwitcher from "./LanguageSwitcher.astro";
+import Search from "./Search.astro";
+
+interface Props {
+  site: { title: string };
+  logo?: {
+    svg?: string;
+    light?: string;
+    dark?: string;
+    alt: string;
+    href: string;
+  } | null;
+  navigation: Navigation;
+  route: string;
+  searchEnabled: boolean;
+  askEnabled?: boolean;
+  // The mobile menu button toggles the docs sidebar drawer; custom pages
+  // without a sidebar (e.g. a landing page) pass `false` to hide it.
+  hasSidebar?: boolean;
+  searchStrings?: UIStrings["search"];
+  switcherStrings?: UIStrings["languageSwitcher"];
+  localeSwitch?: LocaleSwitchOption[];
+  /** Active locale for per-language search filtering. */
+  searchLocale?: string;
+}
+
+const {
+  site,
+  logo,
+  navigation,
+  route,
+  searchEnabled,
+  askEnabled = false,
+  hasSidebar = true,
+  searchStrings,
+  switcherStrings,
+  localeSwitch,
+  searchLocale,
+} = Astro.props;
+
+// The logo is resolved upstream: an inline `svg` (so a currentColor mark
+// follows the theme) or image URL(s) for an <img>.
+const logoSvg = logo?.svg;
+const logoLight = logo?.light;
+const logoDark = logo?.dark ?? logo?.light;
+const logoAlt = logo?.alt ?? "";
+const brandHref = logo?.href ?? "/";
+
+const iconButton =
+  "inline-flex size-9 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground";
+
+// Delegated handlers for the theme toggle, mobile nav drawer, and banner
+// dismiss. Living with the header means every page that renders it — docs pages
+// and custom pages alike — gets identical behavior from one source.
+//
+// Toggling the theme flips colors; without suppressing transitions the animated
+// styles fade while the non-animated ones snap, so we disable all transitions
+// for the swap (next-themes' disableTransitionOnChange trick), force a
+// synchronous style flush, then restore them on the next tick.
+const clickScript = `document.addEventListener("click",(e)=>{const t=e.target.closest("[data-blume-theme-toggle]");if(t){const d=document.documentElement;const next=d.dataset.theme==="dark"?"light":"dark";const s=document.createElement("style");s.appendChild(document.createTextNode("*,*::before,*::after{transition:none!important}"));document.head.appendChild(s);d.dataset.theme=next;localStorage.setItem("blume-theme",next);window.getComputedStyle(d).opacity;setTimeout(()=>document.head.removeChild(s),1);}const n=e.target.closest("[data-blume-nav-toggle]");if(n){document.documentElement.toggleAttribute("data-blume-nav-open");}const b=e.target.closest("[data-blume-banner-dismiss]");if(b){const bar=b.closest("[data-blume-banner]");const k=bar&&bar.getAttribute("data-banner-key");if(k){localStorage.setItem("blume-banner:"+k,"1");}document.documentElement.setAttribute("data-blume-banner-hidden","");}});`;
+---
+
+<header
+  class="sticky top-0 z-40 flex h-16 items-center gap-3 bg-background/90 px-4 backdrop-blur md:px-6"
+>
+  {
+    hasSidebar && (
+      <button
+        aria-label="Toggle navigation"
+        class={`${iconButton} lg:hidden`}
+        data-blume-nav-toggle
+        type="button"
+      >
+        <Icon name="menu" size={20} />
+      </button>
+    )
+  }
+  <a
+    class="inline-flex items-center gap-2 font-semibold text-base text-foreground"
+    href={brandHref}
+  >
+    {
+      logoSvg && (
+        <span
+          aria-hidden="true"
+          class="inline-flex h-5 items-center [&>svg]:h-5 [&>svg]:w-auto"
+          set:html={logoSvg}
+        />
+      )
+    }
+    {
+      !logoSvg &&
+        logoLight &&
+        (logoLight === logoDark ? (
+          <img alt={logoAlt} class="h-5 w-auto" src={logoLight} />
+        ) : (
+          <>
+            <img alt={logoAlt} class="h-5 w-auto dark:hidden" src={logoLight} />
+            <img
+              alt={logoAlt}
+              class="hidden h-5 w-auto dark:block"
+              src={logoDark}
+            />
+          </>
+        ))
+    }
+    {site.title}
+  </a>
+  {
+    navigation.tabs.length > 0 && (
+      <nav aria-label="Sections" class="hidden gap-1 md:flex">
+        {navigation.tabs.map((tab) => (
+          <a
+            aria-current={
+              route === tab.path ||
+              (tab.path !== "/" && route.startsWith(tab.path))
+                ? "page"
+                : undefined
+            }
+            class="rounded-full px-3 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:text-foreground"
+            href={tab.path}
+          >
+            {tab.label}
+          </a>
+        ))}
+      </nav>
+    )
+  }
+  <div class="flex-1"></div>
+  <slot name="ask" />
+  {
+    localeSwitch && localeSwitch.length > 1 && (
+      <LanguageSwitcher
+        label={switcherStrings?.label ?? "Language"}
+        options={localeSwitch}
+        untranslatedLabel={switcherStrings?.untranslated ?? "Not translated"}
+      />
+    )
+  }
+  {
+    searchEnabled && (
+      <Search
+        askEnabled={askEnabled}
+        locale={searchLocale}
+        navigation={navigation}
+        strings={searchStrings}
+      />
+    )
+  }
+  <div class="flex items-center gap-2">
+    {
+      navigation.repoUrl && (
+        <a
+          aria-label="GitHub repository"
+          class={iconButton}
+          href={navigation.repoUrl}
+          rel="noreferrer"
+          target="_blank"
+        >
+          <svg
+            aria-hidden="true"
+            fill="currentColor"
+            height="18"
+            set:html={GITHUB_MARK}
+            viewBox="0 0 16 16"
+            width="18"
+            xmlns="http://www.w3.org/2000/svg"
+          />
+        </a>
+      )
+    }
+    <button
+      aria-label="Toggle color theme"
+      class={iconButton}
+      data-blume-theme-toggle
+      type="button"
+    >
+      <span class="inline-flex dark:hidden"><Icon name="sun" size={18} /></span>
+      <span class="hidden dark:inline-flex"><Icon name="moon" size={18} /></span>
+    </button>
+  </div>
+</header>
+<script is:inline set:html={clickScript} />

package/src/components/layout/LanguageSwitcher.astro

@@ -0,0 +1,56 @@
+---
+import type { LocaleSwitchOption } from "../../core/types.ts";
+import Icon from "../Icon.astro";
+
+interface Props {
+  options: LocaleSwitchOption[];
+  label: string;
+  untranslatedLabel: string;
+}
+
+const { options, label, untranslatedLabel } = Astro.props;
+const current = options.find((option) => option.current);
+
+const iconButton =
+  "inline-flex h-9 cursor-pointer items-center gap-1.5 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground";
+const menuRowClass =
+  "flex w-full items-center gap-2.5 rounded-md px-2 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=true]:text-foreground";
+---
+
+{
+  options.length > 1 && (
+    <details class="group relative">
+      <summary
+        aria-label={label}
+        class={`${iconButton} list-none [&::-webkit-details-marker]:hidden`}
+      >
+        <Icon name="globe" size={16} />
+        <span class="max-sm:hidden">{current?.label ?? label}</span>
+        <Icon
+          class="transition-transform group-open:rotate-180"
+          name="chevron-down"
+          size={14}
+        />
+      </summary>
+      <div class="absolute end-0 z-50 mt-2 min-w-44 rounded-blume border border-border bg-background p-1 shadow-xl">
+        {options.map((option) => (
+          <a
+            aria-current={option.current ? "true" : undefined}
+            class={menuRowClass}
+            href={option.href}
+            hreflang={option.code}
+            lang={option.code}
+          >
+            <span class="flex-1">{option.label}</span>
+            {option.untranslated && (
+              <span class="text-muted-foreground text-xs italic">
+                {untranslatedLabel}
+              </span>
+            )}
+            {option.current && <Icon name="check" size={14} />}
+          </a>
+        ))}
+      </div>
+    </details>
+  )
+}

package/src/components/layout/NavTree.astro

@@ -0,0 +1,462 @@
+---
+import type { NavNode } from "../../core/types.ts";
+import Icon from "../Icon.astro";
+import Self from "./NavTree.astro";
+
+interface PagePanel {
+  id: string;
+  parentId: string;
+  label: string;
+  route?: string;
+  icon?: string;
+  children: NavNode[];
+  active: boolean;
+}
+
+interface Props {
+  items: NavNode[];
+  currentRoute: string;
+  depth?: number;
+  /** Id prefix used to address `page`-mode panels (`${prefix}.${index}`). */
+  idPrefix?: string;
+  /** True only for the top-level call; renders the `<blume-nav>` panel stack. */
+  root?: boolean;
+}
+
+const {
+  items,
+  currentRoute,
+  depth = 0,
+  idPrefix = "n",
+  root = depth === 0,
+} = Astro.props;
+
+const badgeClass =
+  "shrink-0 rounded-full bg-muted px-1.5 py-0.5 font-medium text-[0.65rem] text-muted-foreground leading-none";
+const deprecatedClass =
+  "shrink-0 rounded-full bg-amber-500/10 px-1.5 py-0.5 font-medium text-[0.65rem] text-amber-700 leading-none dark:text-amber-300";
+
+const hasActivePage = (item: NavNode): boolean =>
+  item.kind === "page"
+    ? item.route === currentRoute
+    : item.route === currentRoute || item.children.some(hasActivePage);
+
+// Collect every `page`-mode group in the tree as a panel that is hoisted to the
+// top of the `<blume-nav>` stack. Panel ids match the `${prefix}.${index}`
+// scheme the row renderer uses for `data-nav-to`, so a drill-in trigger and its
+// panel always agree. `flat`/`group` ancestors keep their children in the same
+// visual panel (parentId unchanged); a `page` group opens a new panel.
+const collectPanels = (
+  nodes: NavNode[],
+  prefix: string,
+  parentId: string
+): PagePanel[] => {
+  const out: PagePanel[] = [];
+  nodes.forEach((node, index) => {
+    if (node.kind !== "group") {
+      return;
+    }
+    const id = `${prefix}.${index}`;
+    if ((node.display ?? "flat") === "page") {
+      out.push({
+        active: hasActivePage(node),
+        children: node.children,
+        icon: node.icon,
+        id,
+        label: node.label,
+        parentId,
+        route: node.route,
+      });
+      out.push(...collectPanels(node.children, id, id));
+    } else {
+      out.push(...collectPanels(node.children, id, parentId));
+    }
+  });
+  return out;
+};
+
+const panels = root ? collectPanels(items, idPrefix, "root") : [];
+// Open the deepest panel that contains the current page, so a real page load
+// lands on the right sub-panel (and degrades gracefully without JS).
+const activePanels = panels.filter((panel) => panel.active);
+const initialId =
+  activePanels.length > 0
+    ? activePanels.reduce((a, b) =>
+        b.id.split(".").length > a.id.split(".").length ? b : a
+      ).id
+    : "root";
+---
+
+{
+  root && panels.length > 0 ? (
+    <blume-nav class="block" data-initial={initialId}>
+      <div data-nav-panel="root" hidden={initialId !== "root"}>
+        <Self
+          currentRoute={currentRoute}
+          depth={0}
+          idPrefix={idPrefix}
+          items={items}
+          root={false}
+        />
+      </div>
+      {panels.map((panel) => (
+        <div data-nav-panel={panel.id} hidden={panel.id !== initialId}>
+          <div class="mb-3 flex items-center gap-1.5">
+            <button
+              aria-label="Back"
+              class="-ml-1 flex shrink-0 items-center justify-center rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+              data-nav-back={panel.parentId}
+              type="button"
+            >
+              <Icon name="arrow-left" size={16} />
+            </button>
+            {panel.route ? (
+              <a
+                aria-current={panel.route === currentRoute ? "page" : undefined}
+                class="min-w-0 flex-1 truncate font-semibold text-foreground text-sm hover:underline"
+                href={panel.route}
+              >
+                {panel.label}
+              </a>
+            ) : (
+              <span class="min-w-0 flex-1 truncate font-semibold text-foreground text-sm">
+                {panel.label}
+              </span>
+            )}
+          </div>
+          <Self
+            currentRoute={currentRoute}
+            depth={1}
+            idPrefix={panel.id}
+            items={panel.children}
+            root={false}
+          />
+        </div>
+      ))}
+    </blume-nav>
+  ) : (
+    <ul class="m-0 list-none p-0">
+      {items.map((item, index) => {
+        if (item.kind === "page") {
+          return (
+            <li>
+              <a
+                aria-current={item.route === currentRoute ? "page" : undefined}
+                class="block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:font-medium aria-[current=page]:text-foreground"
+                href={item.route}
+              >
+                <span class="flex min-w-0 items-center gap-2">
+                  {item.icon && (
+                    <Icon
+                      class="shrink-0 text-muted-foreground"
+                      name={item.icon}
+                      size={14}
+                    />
+                  )}
+                  <span class="min-w-0 flex-1 truncate">{item.label}</span>
+                  {item.badge && <span class={badgeClass}>{item.badge}</span>}
+                  {item.deprecated && (
+                    <span class={deprecatedClass}>deprecated</span>
+                  )}
+                </span>
+              </a>
+            </li>
+          );
+        }
+
+        const display = item.display ?? "flat";
+        const id = `${idPrefix}.${index}`;
+        // Flat groups are section headers and want breathing room; collapsible
+        // `group`/`page` rows are single rows and should stack tightly.
+        const spacing =
+          index === 0 ? "mt-0" : display === "flat" ? "mt-6" : "mt-0.5";
+
+        // `page`: a single row that drills into this group's panel.
+        if (display === "page") {
+          return (
+            <li class={spacing}>
+              <button
+                class="flex w-full min-w-0 items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-left font-medium text-foreground text-sm transition-colors hover:bg-muted"
+                data-nav-to={id}
+                type="button"
+              >
+                {item.icon && (
+                  <Icon
+                    class="shrink-0 text-muted-foreground"
+                    name={item.icon}
+                    size={14}
+                  />
+                )}
+                <span class="min-w-0 flex-1 truncate">{item.label}</span>
+                {item.badge && <span class={badgeClass}>{item.badge}</span>}
+                <Icon
+                  class="shrink-0 text-muted-foreground"
+                  name="chevron-right"
+                  size={14}
+                />
+              </button>
+            </li>
+          );
+        }
+
+        // `group`: a collapsible `<details>` disclosure.
+        if (display === "group") {
+          const active = hasActivePage(item);
+          const open = depth === 0 || active || item.collapsed === false;
+          return (
+            <li class={spacing}>
+              <details class="group" open={open}>
+                <summary class="mb-1 flex cursor-pointer list-none items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 font-medium text-foreground text-sm transition-colors hover:bg-muted [&::-webkit-details-marker]:hidden">
+                  {item.route ? (
+                    <a
+                      aria-current={
+                        item.route === currentRoute ? "page" : undefined
+                      }
+                      class="-my-1 flex min-w-0 flex-1 items-center gap-1.5 rounded py-1 text-foreground transition-colors aria-[current=page]:font-semibold"
+                      href={item.route}
+                    >
+                      {item.icon && (
+                        <Icon
+                          class="shrink-0 text-muted-foreground"
+                          name={item.icon}
+                          size={14}
+                        />
+                      )}
+                      <span class="min-w-0 flex-1 truncate">{item.label}</span>
+                      {item.badge && (
+                        <span class={badgeClass}>{item.badge}</span>
+                      )}
+                    </a>
+                  ) : (
+                    <>
+                      {item.icon && (
+                        <Icon
+                          class="shrink-0 text-muted-foreground"
+                          name={item.icon}
+                          size={14}
+                        />
+                      )}
+                      <span class="min-w-0 flex-1 truncate">{item.label}</span>
+                      {item.badge && (
+                        <span class={badgeClass}>{item.badge}</span>
+                      )}
+                    </>
+                  )}
+                  <span class="shrink-0 text-muted-foreground transition-transform group-open:rotate-90">
+                    <Icon name="chevron-right" size={13} />
+                  </span>
+                </summary>
+                <div class="space-y-0.5 border-border border-l pl-3">
+                  <Self
+                    currentRoute={currentRoute}
+                    depth={depth + 1}
+                    idPrefix={id}
+                    items={item.children}
+                    root={false}
+                  />
+                </div>
+              </details>
+            </li>
+          );
+        }
+
+        // `flat` (default): a non-collapsible header with its items beneath.
+        return (
+          <li class={spacing}>
+            <p class="mb-2 flex min-w-0 items-center gap-1.5 px-2.5 font-medium text-foreground text-sm">
+              {item.route ? (
+                <a
+                  aria-current={item.route === currentRoute ? "page" : undefined}
+                  class="-ml-1 flex min-w-0 flex-1 items-center gap-1.5 rounded px-1 py-0.5 text-foreground transition-colors hover:bg-muted aria-[current=page]:bg-muted"
+                  href={item.route}
+                >
+                  {item.icon && (
+                    <Icon
+                      class="shrink-0 text-muted-foreground"
+                      name={item.icon}
+                      size={14}
+                    />
+                  )}
+                  <span class="min-w-0 truncate">{item.label}</span>
+                  {item.badge && (
+                    <span class={`ml-auto ${badgeClass}`}>{item.badge}</span>
+                  )}
+                </a>
+              ) : (
+                <>
+                  {item.icon && (
+                    <Icon
+                      class="shrink-0 text-muted-foreground"
+                      name={item.icon}
+                      size={14}
+                    />
+                  )}
+                  <span class="min-w-0 truncate">{item.label}</span>
+                  {item.badge && (
+                    <span class={`ml-auto ${badgeClass}`}>{item.badge}</span>
+                  )}
+                </>
+              )}
+            </p>
+            <div class="space-y-0.5">
+              <Self
+                currentRoute={currentRoute}
+                depth={depth + 1}
+                idPrefix={id}
+                items={item.children}
+                root={false}
+              />
+            </div>
+          </li>
+        );
+      })}
+    </ul>
+  )
+}
+
+<script>
+  const DURATION = 260;
+  const EASING = "cubic-bezier(0.33, 1, 0.68, 1)";
+
+  class BlumeNav extends HTMLElement {
+    connectedCallback() {
+      if (this.dataset.ready) {
+        return;
+      }
+      this.dataset.ready = "1";
+      this.addEventListener("click", (event) => {
+        const target = event.target;
+        if (!(target instanceof Element)) {
+          return;
+        }
+        const drill = target.closest("[data-nav-to]");
+        if (drill && this.contains(drill)) {
+          const id = drill.getAttribute("data-nav-to");
+          if (id && this.panel(id)) {
+            event.preventDefault();
+            this.show(id, true);
+          }
+          return;
+        }
+        const back = target.closest("[data-nav-back]");
+        if (back && this.contains(back)) {
+          event.preventDefault();
+          this.show(back.getAttribute("data-nav-back") || "root", true);
+        }
+      });
+      // Initial panel is route-driven, so it snaps into place without a slide.
+      this.show(this.dataset.initial || "root", false);
+    }
+
+    panel(id) {
+      return this.querySelector(`[data-nav-panel="${id}"]`);
+    }
+
+    depth(id) {
+      return id === "root" ? 0 : id.split(".").length;
+    }
+
+    reduced() {
+      return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    }
+
+    show(id, animate) {
+      const next = this.panel(id) || this.panel("root");
+      if (!next) {
+        return;
+      }
+      const resolved = next.getAttribute("data-nav-panel");
+      const prev = this.active;
+      if (prev === next) {
+        return;
+      }
+      // Settle any in-flight slide before starting the next one.
+      if (this.finishSlide) {
+        this.finishSlide();
+      }
+      this.active = next;
+      this.dataset.active = resolved;
+
+      if (!(animate && prev) || this.reduced()) {
+        for (const panel of this.querySelectorAll("[data-nav-panel]")) {
+          panel.hidden = panel !== next;
+        }
+        return;
+      }
+
+      const forward =
+        this.depth(resolved) > this.depth(prev.getAttribute("data-nav-panel"));
+      this.slide(prev, next, forward);
+    }
+
+    slide(out, into, forward) {
+      const rtl = getComputedStyle(this).direction === "rtl" ? -1 : 1;
+      const sign = (forward ? -1 : 1) * rtl;
+
+      const fromHeight = out.offsetHeight;
+      this.style.position = "relative";
+      this.style.overflow = "hidden";
+      this.style.height = `${fromHeight}px`;
+      into.hidden = false;
+      for (const panel of [out, into]) {
+        panel.style.position = "absolute";
+        panel.style.top = "0";
+        panel.style.insetInlineStart = "0";
+        panel.style.width = "100%";
+      }
+      const toHeight = into.offsetHeight;
+      this.style.height = `${toHeight}px`;
+
+      const options = { duration: DURATION, easing: EASING };
+      const animations = [
+        out.animate(
+          [
+            { transform: "translateX(0)" },
+            { transform: `translateX(${sign * 100}%)` },
+          ],
+          options
+        ),
+        into.animate(
+          [
+            { transform: `translateX(${-sign * 100}%)` },
+            { transform: "translateX(0)" },
+          ],
+          options
+        ),
+        this.animate(
+          [{ height: `${fromHeight}px` }, { height: `${toHeight}px` }],
+          options
+        ),
+      ];
+
+      let done = false;
+      const finish = () => {
+        if (done) {
+          return;
+        }
+        done = true;
+        for (const animation of animations) {
+          animation.cancel();
+        }
+        out.hidden = true;
+        for (const panel of [out, into]) {
+          panel.style.position = "";
+          panel.style.top = "";
+          panel.style.insetInlineStart = "";
+          panel.style.width = "";
+          panel.style.transform = "";
+        }
+        this.style.position = "";
+        this.style.overflow = "";
+        this.style.height = "";
+        this.finishSlide = null;
+      };
+      this.finishSlide = finish;
+      animations[0].finished.then(finish, finish);
+    }
+  }
+
+  if (!customElements.get("blume-nav")) {
+    customElements.define("blume-nav", BlumeNav);
+  }
+</script>