@orbytes/astrolab 0.3.0 → 0.4.0-next.1

package/src/chrome/ComponentCard.astro

@@ -0,0 +1,69 @@
+---
+// One card per COMPONENT (a stories module), not per story — the tree stops at the component and
+// so does the grid. The thumbnail is its first story's bare render (/lab/stories/<id>) in a lazy
+// <iframe> sized to a virtual viewport and scaled to the card by ../chrome/shell-client.ts: page
+// width for section-like tiers, a component stage otherwise. The whole card opens the component;
+// the icon links under it sit above that link.
+import Icon from "./Icon.astro";
+import { componentState, type LabComponent } from "./trees";
+import { isSectionLike, livePillText, liveTitle } from "../shell/lab-index";
+
+interface Props {
+  mod: LabComponent;
+}
+
+const { mod } = Astro.props;
+const first = mod.stories[0]!;
+const liveStory = mod.stories.find((s) => s.live);
+const section = isSectionLike(first);
+const state = componentState(mod);
+---
+
+<article class="lab-card" data-lab-search={state.search} data-lab-facets={state.facets}>
+  <a class="lab-card__main" href={first.dashboardUrl}>
+    <span class="lab-card__thumb" data-frame-w={section ? 1440 : 960} data-frame-h={section ? 900 : 540}>
+      <iframe src={first.storyUrl} title={`${mod.moduleName} — ${first.storyName}`} loading="lazy" tabindex="-1"></iframe>
+    </span>
+    <span class="lab-card__body">
+      <span class="lab-card__name">
+        <span>{mod.moduleName}</span>
+        {mod.version && <span class="lab-card__version">{mod.version}</span>}
+      </span>
+      <span class="lab-card__sub">
+        {mod.stories.length} stor{mod.stories.length === 1 ? "y" : "ies"}{mod.summary ? ` · ${mod.summary}` : ""}
+      </span>
+      <span class="lab-card__pills">
+        {liveStory && <span class="lab-pill lab-pill--live" title={liveTitle(liveStory)}>{livePillText(liveStory)}</span>}
+        {!mod.live && mod.usedBy.length > 0 && (
+          <span class="lab-pill lab-pill--used" title={mod.usedBy.join("\n")}>used by {mod.usedBy.length}</span>
+        )}
+        {mod.responsive && (
+          <span
+            class:list={["lab-pill", mod.responsive.done ? "lab-pill--responsive" : "lab-pill--unresponsive"]}
+            title={mod.responsive.approved ? "approved for responsive work" : "not approved for responsive work yet"}
+          >
+            {mod.responsive.done ? "responsive" : "not responsive"}
+          </span>
+        )}
+      </span>
+    </span>
+  </a>
+  {
+    (first.editorUrl || first.stagingUrl) && (
+      <span class="lab-card__links">
+        {first.editorUrl && (
+          <a class="lab-icon-btn lab-card__link" href={first.editorUrl} title="Open in VS Code">
+            <Icon name="code" />
+            <span class="lab-visually-hidden">Open in VS Code</span>
+          </a>
+        )}
+        {first.stagingUrl && (
+          <a class="lab-icon-btn lab-card__link" href={first.stagingUrl} target="_blank" rel="noopener" title="View on staging">
+            <Icon name="external" />
+            <span class="lab-visually-hidden">View on staging</span>
+          </a>
+        )}
+      </span>
+    )
+  }
+</article>

package/src/chrome/Icon.astro

@@ -0,0 +1,21 @@
+---
+// One icon from the sprite (./Sprite.astro). Decorative by default; pass `label` when the icon is
+// the only thing naming a control.
+import type { IconName } from "./icons";
+
+interface Props {
+  name: IconName;
+  size?: "sm" | "md";
+  class?: string;
+  label?: string;
+}
+
+const { name, size = "md", class: extra, label } = Astro.props;
+---
+
+<svg
+  class:list={["lab-icon", size === "sm" && "lab-icon--sm", extra]}
+  aria-hidden={label ? undefined : "true"}
+  role={label ? "img" : undefined}
+  aria-label={label}
+><use href={`#lab-i-${name}`}></use></svg>

package/src/chrome/LICENSE-icons

@@ -0,0 +1,43 @@
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/chrome/Nav.astro

@@ -0,0 +1,105 @@
+---
+// Level 1 — the main nav (Figma `Sidebar navigation`, the white card). Home, the Site group (Pages,
+// one entry per tier, Assets), the Tasks group when the pin board is running, and Support and
+// Settings at the foot. Collapses to a 56px icon strip (⌘⇧B); in the strip a group's items open
+// as a flyout on hover or focus, drawn by CSS alone (../ui/lab.css › level 1 as a rail).
+//
+// The logo and the Support / Settings pages are placeholders until they are designed.
+import Icon from "./Icon.astro";
+import { labConfig, navModel, type NavKey } from "./model";
+
+interface Props {
+  active: NavKey;
+}
+
+const { active } = Astro.props;
+const model = navModel();
+const isOpen = (group: { items: { key: NavKey }[] }) => group.items.some((item) => item.key === active);
+---
+
+<nav class="lab-l1" aria-label="Lab">
+  <div class="lab-l1__card">
+    <div class="lab-l1__top">
+      <div class="lab-l1__header">
+        <a class="lab-brand" href={model.home.href} title={labConfig.title}>
+          <span class="lab-brand__mark" aria-hidden="true"></span>
+          <span class="lab-brand__name">Astrolab</span>
+        </a>
+        <button class="lab-icon-btn lab-theme-btn" type="button" data-lab-theme-toggle title="Light or dark lab">
+          <Icon name="sun" class="lab-icon--sun" />
+          <Icon name="moon" class="lab-icon--moon" />
+          <span class="lab-visually-hidden">Toggle the lab's light or dark theme</span>
+        </button>
+        <button class="lab-icon-btn" type="button" data-lab-toggle="l1" title="Collapse the menu (⌘⇧B)" data-lab-l1-btn>
+          <Icon name="chevrons-left" class="lab-l1-btn__collapse" />
+          <Icon name="chevrons-right" class="lab-l1-btn__expand" />
+          <span class="lab-visually-hidden">Collapse or expand the menu</span>
+        </button>
+      </div>
+
+      <div class="lab-l1__nav">
+        <a
+          class="lab-nav-item"
+          href={model.home.href}
+          aria-current={active === "home" ? "page" : undefined}
+          data-tip={model.home.label}
+          data-lab-nav-key="home"
+        >
+          <Icon name={model.home.icon} />
+          <span class="lab-nav-item__label">{model.home.label}</span>
+        </a>
+        {
+          model.groups.map((group) => (
+            <>
+              <hr class="lab-divider" />
+              <div class="lab-nav-group" data-lab-group={group.id} data-lab-holds-current={isOpen(group) ? "" : undefined}>
+                <button
+                  class="lab-nav-item"
+                  type="button"
+                  aria-expanded="true"
+                  aria-current={isOpen(group) ? "true" : undefined}
+                  data-tip={group.label}
+                  data-lab-group-toggle
+                >
+                  <Icon name={group.icon} />
+                  <span class="lab-nav-item__label">{group.label}</span>
+                  <Icon name="chevron-down" size="sm" class="lab-nav-group__chevron" />
+                </button>
+                <div class="lab-nav-group__items">
+                  {group.items.map((item) => (
+                    <a
+                      class="lab-nav-item"
+                      href={item.href}
+                      aria-current={item.key === active ? "page" : undefined}
+                      data-lab-nav-key={item.key}
+                    >
+                      <Icon name={item.icon} />
+                      <span class="lab-nav-item__label">{item.label}</span>
+                    </a>
+                  ))}
+                </div>
+              </div>
+            </>
+          ))
+        }
+      </div>
+    </div>
+
+    <div class="lab-l1__footer">
+      {
+        model.footer.map((item) => (
+          <a
+            class="lab-nav-item"
+            href={item.href}
+            aria-current={item.key === active ? "page" : undefined}
+            data-tip={item.label}
+            data-lab-nav-key={item.key}
+          >
+            <Icon name={item.icon} />
+            <span class="lab-nav-item__label">{item.label}</span>
+          </a>
+        ))
+      }
+    </div>
+  </div>
+</nav>

package/src/chrome/Panel.astro

@@ -0,0 +1,104 @@
+---
+// Level 2 — the panel (Figma `Sidebar navigation`, the grey column): breadcrumb, search with its
+// filter menu, the tree in the default slot, and the coffee footer. Closes with ⌘B or its own
+// button; while closed it peeks out over the stage when the pointer reaches the stage's left edge.
+//
+// The coffee link is a placeholder until it has a destination.
+import Icon from "./Icon.astro";
+import { labBase, type Crumb, type FilterOption } from "./model";
+
+interface Props {
+  crumbs: Crumb[];
+  /** Label for the panel landmark, e.g. "Pages". */
+  label: string;
+  search?: boolean;
+  searchPlaceholder?: string;
+  filters?: FilterOption[];
+  filterLabel?: string;
+}
+
+const { crumbs, label, search = true, searchPlaceholder = "Search", filters, filterLabel = "Show" } = Astro.props;
+---
+
+<aside class="lab-l2" id="lab-l2" aria-label={label}>
+  <div class="lab-l2__header">
+    <div class="lab-l2__crumbs-row">
+      <nav aria-label="Breadcrumb">
+        <ol class="lab-crumbs">
+          <li class="lab-crumbs__item">
+            <a href={labBase || "/"} title="Lab home"><Icon name="home" /><span class="lab-visually-hidden">Lab home</span></a>
+          </li>
+          {
+            crumbs.map((crumb, i) => (
+              <li class="lab-crumbs__item" aria-current={i === crumbs.length - 1 ? "page" : undefined}>
+                {crumb.href && i < crumbs.length - 1 ? <a href={crumb.href}>{crumb.label}</a> : crumb.label}
+              </li>
+            ))
+          }
+        </ol>
+      </nav>
+      <button class="lab-icon-btn lab-l2__close" type="button" data-lab-toggle="l2" title="Close the panel (⌘B)">
+        <Icon name="panel-close" />
+        <span class="lab-visually-hidden">Close the panel</span>
+      </button>
+    </div>
+
+    {
+      search && (
+        <div class="lab-input">
+          <Icon name="search" size="sm" />
+          <input
+            class="lab-input__field"
+            type="search"
+            placeholder={searchPlaceholder}
+            aria-label={searchPlaceholder}
+            autocomplete="off"
+            spellcheck="false"
+            data-lab-tree-search
+          />
+          <kbd class="lab-input__kbd">⌘K</kbd>
+          {filters && filters.length > 0 && (
+            <button
+              class="lab-icon-btn"
+              type="button"
+              popovertarget="lab-tree-filter"
+              title="Filter"
+              data-lab-filter-btn
+            >
+              <Icon name="filter" size="sm" />
+              <span class="lab-visually-hidden">Filter</span>
+            </button>
+          )}
+        </div>
+      )
+    }
+    {
+      filters && filters.length > 0 && (
+        <div class="lab-menu" id="lab-tree-filter" popover role="menu" data-lab-align="end">
+          <p class="lab-menu__label">{filterLabel}</p>
+          <button class="lab-menu__item" type="button" role="menuitemradio" aria-checked="true" data-lab-filter="">
+            All
+            <Icon name="check" size="sm" class="lab-menu__tick" />
+          </button>
+          {filters.map((option) => (
+            <button class="lab-menu__item" type="button" role="menuitemradio" aria-checked="false" data-lab-filter={option.value}>
+              {option.label}
+              <Icon name="check" size="sm" class="lab-menu__tick" />
+            </button>
+          ))}
+        </div>
+      )
+    }
+  </div>
+
+  <div class="lab-l2__body" data-lab-l2-body>
+    <slot />
+  </div>
+
+  <div class="lab-l2__footer">
+    <span class="lab-nav-item lab-coffee" aria-disabled="true" title="The link is still to come">
+      <Icon name="coffee" />
+      <span class="lab-nav-item__label">Buy Me A Coffee</span>
+    </span>
+  </div>
+</aside>

package/src/chrome/Shell.astro

@@ -0,0 +1,106 @@
+---
+// The chrome document — every lab page renders through this, and nothing of the consumer's does.
+// Level 1 (./Nav.astro), level 2 (./Panel.astro, when the page has a list to show), and main: the
+// navbar (slot "navbar") above the content (default slot). Figma `Astrolab` › Design › Desktop.
+//
+// PURE CHROME, NO CONSUMER CSS. Previews are <iframe>s of their own documents (the bare story
+// route, or the site's own page), so this document never imports `virtual:astrobook/user-css.mjs`
+// or the consumer's head. That split is what testbeds/orbytes-v2/scripts/check-isolation.mjs
+// asserts, both ways, on every built page.
+//
+// NO CLIENT ROUTER. A click is a real page load; `@view-transition { navigation: auto }` in the
+// stylesheet keeps the old page painted until the new one is ready, and everything worth keeping
+// across a load — which levels are collapsed, which tree groups are closed, the tree's scroll — is
+// in storage and re-applied before paint. That keeps every script here a plain module that runs
+// once per page, with none of the re-run guards a swapped document needs.
+import LabHead from "../LabHead.astro";
+import Nav from "./Nav.astro";
+import Panel from "./Panel.astro";
+import Sprite from "./Sprite.astro";
+import Icon from "./Icon.astro";
+import { labConfig, type Crumb, type FilterOption, type NavKey } from "./model";
+
+interface Props {
+  /** The document title's first half; the lab's own title follows it. */
+  title: string;
+  active: NavKey;
+  /** Level 2. Omit `panel` for a page with no list to show (Home, Settings): level 2 is not drawn. */
+  panel?: {
+    label: string;
+    crumbs: Crumb[];
+    search?: boolean;
+    searchPlaceholder?: string;
+    filters?: FilterOption[];
+    filterLabel?: string;
+  };
+  /** Extra class on main's content box, e.g. to make it a positioning context for the stage. */
+  contentClass?: string;
+}
+
+const { title, active, panel, contentClass } = Astro.props;
+---
+
+<html lang="en" class="lab-shell" data-lab-page={active}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <meta name="generator" content={Astro.generator} />
+    <title>{`${title} · ${labConfig.title}`}</title>
+    <LabHead />
+    {/* The collapse state, before paint — so a closed panel never flashes open. Level 1 starts as
+        the rail on a narrow window unless it was explicitly expanded there. */}
+    <script is:inline>
+      (() => {
+        try {
+          const root = document.documentElement;
+          const l1 = localStorage.getItem("lab-l1");
+          const l2 = localStorage.getItem("lab-l2");
+          if (l1 === "rail" || (!l1 && window.innerWidth < 1024)) root.dataset.labL1 = "rail";
+          if (l2 === "closed") root.dataset.labL2 = "closed";
+        } catch {
+          /* storage blocked — the defaults are fine */
+        }
+      })();
+    </script>
+  </head>
+  <body class="lab-shell">
+    <Sprite />
+    <div class="lab-app">
+      <Nav active={active} />
+      {
+        panel && (
+          <Panel
+            label={panel.label}
+            crumbs={panel.crumbs}
+            search={panel.search}
+            searchPlaceholder={panel.searchPlaceholder}
+            filters={panel.filters}
+            filterLabel={panel.filterLabel}
+          >
+            <slot name="panel" />
+          </Panel>
+        )
+      }
+      <main class="lab-main" id="lab-main">
+        {panel && <div class="lab-peek-zone" data-lab-peek-zone aria-hidden="true" />}
+        <header class="lab-navbar">
+          {
+            panel && (
+              <button class="lab-icon-btn lab-navbar__panel-btn" type="button" data-lab-toggle="l2" title="Open the panel (⌘B)">
+                <Icon name="panel-open" />
+                <span class="lab-visually-hidden">Open the panel</span>
+              </button>
+            )
+          }
+          <slot name="navbar" />
+        </header>
+        <div class:list={["lab-content", contentClass]} id="lab-content">
+          <slot />
+        </div>
+      </main>
+    </div>
+    <script>
+      import "./shell-client";
+    </script>
+  </body>
+</html>

package/src/chrome/Sprite.astro

@@ -0,0 +1,23 @@
+---
+// The icon sprite — every icon the chrome uses, once per page, as <symbol>s that ./Icon.astro
+// points at with <use>. A tree of fifty rows costs fifty `<use href>` tags rather than fifty copies
+// of the same path data. Shapes and licence: ./icons.ts.
+import { ICONS } from "./icons";
+---
+
+<svg aria-hidden="true" focusable="false" style="position:absolute;width:0;height:0;overflow:hidden">
+  {
+    Object.entries(ICONS).map(([name, inner]) => (
+      <symbol
+        id={`lab-i-${name}`}
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        set:html={inner}
+      />
+    ))
+  }
+</svg>