npm - @orbytes/astrolab - Versions diffs - 0.3.0 - Mend

@orbytes/astrolab 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (94) hide show

package/LICENSE +37 -0
package/README.md +410 -0
package/bin/lab-cull.mjs +401 -0
package/bin/pin-gallery.mjs +121 -0
package/defaults.mjs +120 -0
package/dist/core/astro-integration.js +130 -0
package/dist/core/index.js +6 -0
package/dist/core/lib-paths.js +29 -0
package/dist/core/options.js +173 -0
package/dist/core/utils/get-exports.js +52 -0
package/dist/core/utils/invariant.js +12 -0
package/dist/core/utils/kebab-case.js +15 -0
package/dist/core/utils/path-builder.js +22 -0
package/dist/core/utils/path.js +53 -0
package/dist/core/virtual-module/get-story-modules.js +60 -0
package/dist/core/virtual-module/story-modules.js +8 -0
package/dist/core/virtual-module/virtual-module-ids.js +22 -0
package/dist/core/virtual-module/virtual-routes.js +83 -0
package/dist/core/virtual-module/vite-plugin.js +98 -0
package/docs/PIN-CONTRACT.md +263 -0
package/docs/PIN.md +429 -0
package/index.d.ts +279 -0
package/index.mjs +347 -0
package/package.json +93 -0
package/src/Empty.astro +4 -0
package/src/Home.astro +298 -0
package/src/LabHead.astro +1102 -0
package/src/core/LICENSE-astrobook +166 -0
package/src/core/astro-integration.ts +166 -0
package/src/core/client.ts +89 -0
package/src/core/index.ts +7 -0
package/src/core/lib/components/empty.astro +1 -0
package/src/core/lib/components/head.astro +1 -0
package/src/core/lib/components/home.astro +8 -0
package/src/core/lib/components/with-decorators.astro +22 -0
package/src/core/lib/pages/app.astro +19 -0
package/src/core/lib/pages/preview.astro +17 -0
package/src/core/lib/pages/story.astro +16 -0
package/src/core/lib-paths.ts +72 -0
package/src/core/options.ts +262 -0
package/src/core/utils/get-exports.ts +59 -0
package/src/core/utils/invariant.ts +13 -0
package/src/core/utils/kebab-case.ts +30 -0
package/src/core/utils/path-builder.ts +45 -0
package/src/core/utils/path.ts +80 -0
package/src/core/virtual-module/get-story-modules.ts +110 -0
package/src/core/virtual-module/story-modules.ts +9 -0
package/src/core/virtual-module/virtual-module-ids.ts +17 -0
package/src/core/virtual-module/virtual-routes.ts +130 -0
package/src/core/virtual-module/vite-plugin.ts +125 -0
package/src/pin/board.mjs +1521 -0
package/src/pin/index.mjs +666 -0
package/src/pin/shot.mjs +427 -0
package/src/pin/source-stamp.mjs +159 -0
package/src/pin/tickets.mjs +697 -0
package/src/pin/toolbar.js +3181 -0
package/src/shell/Browse.astro +371 -0
package/src/shell/CardGrid.astro +297 -0
package/src/shell/Viewport.astro +1330 -0
package/src/shell/index.json.ts +12 -0
package/src/shell/lab-index.ts +344 -0
package/src/shell/lab-params.ts +245 -0
package/src/shell/live-files.mjs +164 -0
package/src/shell/marks.mjs +136 -0
package/src/types/index.ts +6 -0
package/src/types/types.ts +239 -0
package/src/types/virtual.d.ts +29 -0
package/src/ui/components/app.astro +13 -0
package/src/ui/components/build-path.ts +13 -0
package/src/ui/components/build-tree.ts +108 -0
package/src/ui/components/collapse-duration.ts +28 -0
package/src/ui/components/compress-terms.ts +10 -0
package/src/ui/components/dashboard-layout.astro +39 -0
package/src/ui/components/home.astro +65 -0
package/src/ui/components/layout.astro +110 -0
package/src/ui/components/preview-layout.astro +109 -0
package/src/ui/components/sidebar-button-fullscreen.astro +38 -0
package/src/ui/components/sidebar-button-search.astro +23 -0
package/src/ui/components/sidebar-button-theme.astro +9 -0
package/src/ui/components/sidebar-button.astro +24 -0
package/src/ui/components/sidebar-resize-handle.astro +74 -0
package/src/ui/components/sidebar-search-panel.astro +41 -0
package/src/ui/components/sidebar-search-script.ts +103 -0
package/src/ui/components/sidebar-title.astro +17 -0
package/src/ui/components/sidebar-tree-node.astro +143 -0
package/src/ui/components/sidebar-tree.astro +84 -0
package/src/ui/components/sidebar.astro +29 -0
package/src/ui/components/theme-message.ts +26 -0
package/src/ui/components/theme-script.astro +71 -0
package/src/ui/components/theme-toggle.astro +63 -0
package/src/ui/components/theme.ts +32 -0
package/src/ui/index.ts +4 -0
package/src/ui/lab.css +549 -0
package/virtual.d.ts +42 -0

package/src/ui/lab.css ADDED Viewed

@@ -0,0 +1,549 @@
+/* =============================================================================================
+   lab.css — THE lab's chrome stylesheet. The only one.
+   THE RULING THIS FILE EXISTS FOR (2026-09-22):
+     The lab is not styled in the styles of the website being built. It has one standard style
+     across every site. A user who wants it styled differently edits this open source code —
+     but that is never the default.
+   So the line runs between CHROME and PREVIEW, and it runs exactly there:
+     CHROME   the lab's own furniture — layout, sidebar, search, toolbar, the home page, the
+              folder pages, the viewport configurator. Styled HERE and nowhere else. It never
+              receives the consumer's `css` list and never receives the consumer's `head`.
+     PREVIEW  the story itself (/lab/stories/<id>) and the story rendered inside the dashboard.
+              It receives the consumer's `css` list and `head` — that is how the site's tokens
+              and fonts arrive, and seeing a component as the real site renders it is the whole
+              point of the lab.
+   ISOLATION RUNS BOTH WAYS, and that is why this file looks the way it does:
+     1. EVERY TOKEN IS `--lab-*`. The consumer owns `--color-background`, `--font-body`,
+        `--radius-pill` and the rest; a lab that read those names would wear the client's brand,
+        which is the exact thing the ruling forbids. Nothing here reads a name the consumer could
+        also define, so the two palettes cannot collide even where both stylesheets are in one
+        document (the dashboard, which must carry both).
+     2. NOTHING HERE IS A BARE ELEMENT SELECTOR that could reach a story. Every rule is anchored
+        on a chrome class, a chrome id, or a chrome custom element. `html`/`body` carry the
+        `.lab-shell` class rather than being styled as elements, and the chrome's font, colour
+        and font-size are set on the chrome's own boxes — never inherited down from `body`, which
+        on a dashboard page is shared with the preview.
+     3. NO CASCADE LAYER. The previous build put the lab's token fallbacks in
+        `@layer orbytes-lab-fallback` so the consumer would win; that was the leak, expressed as
+        a policy. The lab wins now.
+   WHAT THIS FILE IS NOT. This is the FUNCTION pass, not the design pass: plain, legible,
+   working, dark mode intact. Semantic class names (`.lab-sidebar`, `.lab-tree-row`) rather than
+   a hand-rolled utility set, precisely so the next pass is a restyle and not a rewrite. It
+   replaces the UnoCSS atomic classes the upstream `@astrobook/ui` was built from — this package
+   ships source and has no build step, so Uno was never an option here.
+   Typography ships with the package: a system font stack, no webfont, no build step, no
+   consumer dependency.
+   ============================================================================================= */
+/* ---------------------------------------------------------------------------------------------
+   Tokens. Light is the default; `.dark` on <html> is set by the theme script before paint
+   (src/ui/components/theme-script.astro) and is the hook LabHead's own styles key off too.
+   --------------------------------------------------------------------------------------------- */
+:root {
+  --lab-font-body:
+    system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif,
+    "Apple Color Emoji", "Segoe UI Emoji";
+  --lab-font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+  /* The chrome has one face today. The name exists so phase 2 can split display from body
+     without touching every rule that asks for it. */
+  --lab-font-heading: var(--lab-font-body);
+  --lab-color-bg: #ffffff;
+  --lab-color-bg-sunken: #f9fafb;
+  --lab-color-surface: #f4f4f5;
+  --lab-color-surface-raised: #ffffff;
+  --lab-color-border: #e4e4e7;
+  --lab-color-border-strong: #d4d4d8;
+  --lab-color-text: #3f3f46;
+  --lab-color-text-strong: #18181b;
+  --lab-color-text-muted: #71717a;
+  --lab-color-text-faint: #a1a1aa;
+  --lab-color-accent: #2563eb;
+  --lab-color-accent-text: #ffffff;
+  /* The accent that reads on the INVERTED active tree row, where the ground flips to the other
+     theme's. LabHead.astro's live pill is the only thing that needs it. */
+  --lab-color-accent-inverse: #60a5fa;
+  --lab-color-focus: #18181b;
+  /* The inverted active row in the tree. */
+  --lab-color-active-bg: #27272a;
+  --lab-color-active-text: #ffffff;
+  --lab-radius: 4px;
+  --lab-radius-pill: 100px;
+  --lab-radius-square: 0;
+  --lab-transition: 150ms ease;
+  --lab-sidebar-width: attr(data-sidebar-width px, 300px);
+}
+:root.dark {
+  --lab-color-bg: #18181b;
+  --lab-color-bg-sunken: #111113;
+  --lab-color-surface: #1f1f23;
+  --lab-color-surface-raised: #27272a;
+  --lab-color-border: #3f3f46;
+  --lab-color-border-strong: #52525b;
+  --lab-color-text: #d4d4d8;
+  --lab-color-text-strong: #fafafa;
+  --lab-color-text-muted: #a1a1aa;
+  --lab-color-text-faint: #71717a;
+  --lab-color-accent: #60a5fa;
+  --lab-color-accent-text: #09090b;
+  --lab-color-accent-inverse: #2563eb;
+  --lab-color-focus: #fafafa;
+  --lab-color-active-bg: #e4e4e7;
+  --lab-color-active-text: #18181b;
+}
+/* ---------------------------------------------------------------------------------------------
+   The document frame. Structure only — no font, no colour, nothing that would inherit into a
+   story rendered in <main> on a dashboard page.
+   --------------------------------------------------------------------------------------------- */
+html.lab-shell {
+  height: 100%;
+  max-height: 100vh;
+  overflow: hidden;
+  -webkit-text-size-adjust: 100%;
+}
+body.lab-shell {
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: row;
+  align-items: stretch;
+  justify-content: flex-start;
+  min-height: 100%;
+  max-height: 100%;
+}
+.lab-main {
+  flex: 1;
+  min-width: 0;
+  overflow: auto;
+  box-sizing: border-box;
+}
+/* Box-sizing is scoped to the chrome for the same reason: on a dashboard page a `*` selector
+   would cross into the story. */
+.lab-chrome,
+.lab-chrome *,
+.lab-chrome *::before,
+.lab-chrome *::after {
+  box-sizing: border-box;
+}
+/* The chrome's own typographic ground. Declared on the chrome boxes, not on `body`, because the
+   consumer's `body { font-family; font-size }` is in the same document on a dashboard page — a
+   class here beats an element selector there, and nothing inherits into the preview from us. */
+.lab-chrome {
+  font-family: var(--lab-font-body);
+  font-size: 14px;
+  line-height: 1.45;
+  color: var(--lab-color-text);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+.lab-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+.lab-focus-ring:focus-visible {
+  outline: 2px solid var(--lab-color-focus);
+  outline-offset: -1px;
+  z-index: 20;
+}
+/* ---------------------------------------------------------------------------------------------
+   Sidebar. `#astrobook-sidebar` is a DOM contract, not a style choice: LabHead.astro's collapse
+   script and pill decorator both query it by that id. Same for the resize-handle element.
+   --------------------------------------------------------------------------------------------- */
+#astrobook-sidebar {
+  display: flex;
+  flex-direction: column;
+  flex-shrink: 0;
+  width: var(--lab-sidebar-width, 300px);
+  min-width: 100px;
+  max-width: calc(100vw - 100px);
+  border-right: 1px solid var(--lab-color-border);
+  background-color: var(--lab-color-bg-sunken);
+}
+:root[data-sidebar-resizing] {
+  cursor: ew-resize;
+  user-select: none;
+}
+astrobook-sidebar-resize-handle {
+  position: relative;
+  left: -2px;
+  display: block;
+  width: 4px;
+  flex: none;
+  cursor: ew-resize;
+  transition: background-color var(--lab-transition);
+}
+astrobook-sidebar-resize-handle:hover {
+  background-color: var(--lab-color-border-strong);
+}
+.lab-sidebar__nav {
+  display: flex;
+  flex-direction: column;
+  min-height: 100%;
+  max-height: 100%;
+  overflow-y: hidden;
+  padding: 0;
+  margin: 0;
+}
+.lab-sidebar__header {
+  display: flex;
+  align-items: center;
+  gap: 0.125rem;
+  padding: 0.75rem 0.5rem;
+  border-bottom: 1px solid var(--lab-color-border);
+}
+.lab-sidebar__title {
+  min-width: 0;
+  flex: 0 1 auto;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  padding: 0.35rem 0.5rem;
+  border-radius: var(--lab-radius);
+  font-weight: 600;
+  color: var(--lab-color-text-muted);
+  text-decoration: none;
+  transition: color var(--lab-transition);
+}
+.lab-sidebar__title:hover {
+  color: var(--lab-color-text-strong);
+}
+.lab-sidebar__spacer {
+  flex: 1 1 auto;
+}
+/* The button class name is a DOM contract too: LabHead.astro creates the collapse, cull,
+   viewport, staging and code buttons and sets `className = "astrobook-sidebar-button"` on each,
+   so every injected control inherits this shape without knowing anything about the stylesheet. */
+.astrobook-sidebar-button {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 2rem;
+  height: 2rem;
+  padding: 0.375rem;
+  border: 0;
+  border-radius: var(--lab-radius);
+  background: transparent;
+  color: var(--lab-color-text-muted);
+  font: inherit;
+  font-size: 1rem;
+  text-decoration: none;
+  cursor: pointer;
+  transition:
+    color var(--lab-transition),
+    background-color var(--lab-transition);
+}
+.astrobook-sidebar-button:hover {
+  color: var(--lab-color-text-strong);
+  background-color: var(--lab-color-surface);
+}
+.astrobook-sidebar-button[data-active] {
+  color: var(--lab-color-text-strong);
+  background-color: var(--lab-color-surface);
+}
+.astrobook-sidebar-button svg {
+  display: block;
+  width: 1rem;
+  height: 1rem;
+}
+/* ---------------------------------------------------------------------------------------------
+   Search. The ids are the contract (LabHead widens matches by appending terms to
+   `data-search-text`, and opens the panel on ⌘K by clicking the toggle).
+   --------------------------------------------------------------------------------------------- */
+#astrobook-search-panel {
+  interpolate-size: allow-keywords;
+  height: 0;
+  overflow: clip;
+  border-bottom: 1px solid transparent;
+  transition: height var(--lab-transition);
+}
+#astrobook-search-panel[data-open] {
+  height: max-content;
+  border-bottom-color: var(--lab-color-border);
+}
+.lab-search__row {
+  display: flex;
+  align-items: center;
+  padding: 0.5rem;
+}
+.lab-search__field {
+  position: relative;
+  display: flex;
+  flex: 1;
+  align-items: center;
+}
+.lab-search__icon {
+  position: absolute;
+  left: 0.5rem;
+  display: block;
+  width: 0.875rem;
+  height: 0.875rem;
+  pointer-events: none;
+  color: var(--lab-color-text-faint);
+}
+#astrobook-search-input {
+  width: 100%;
+  padding: 0.3rem 0.5rem 0.3rem 1.75rem;
+  border: 1px solid var(--lab-color-border);
+  border-radius: var(--lab-radius);
+  background-color: var(--lab-color-surface-raised);
+  font-family: var(--lab-font-body);
+  font-size: 0.875rem;
+  color: var(--lab-color-text-strong);
+  outline: none;
+}
+#astrobook-search-input::placeholder {
+  color: var(--lab-color-text-faint);
+}
+#astrobook-search-input:focus {
+  border-color: var(--lab-color-border-strong);
+}
+/* ---------------------------------------------------------------------------------------------
+   The tree. Every selector below is one LabHead.astro also queries — see its DOM contract block.
+   --------------------------------------------------------------------------------------------- */
+astrobook-sidebar-tree {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  overflow-y: auto;
+  padding: 0.75rem 0.5rem 2rem;
+}
+astrobook-sidebar-node {
+  display: contents;
+}
+.astrobook-sidebar-link {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  list-style: none;
+  padding: 0.25rem 0.5rem;
+  border-radius: var(--lab-radius);
+  font-size: 0.875rem;
+  text-decoration: none;
+  cursor: pointer;
+  user-select: none;
+  transition:
+    color var(--lab-transition),
+    background-color var(--lab-transition);
+}
+.astrobook-sidebar-link::-webkit-details-marker {
+  display: none;
+}
+/* Folder and module rows. */
+.lab-tree-row--group {
+  color: var(--lab-color-text-muted);
+}
+.lab-tree-row--group:hover {
+  color: var(--lab-color-text-strong);
+  background-color: var(--lab-color-surface);
+}
+/* Story rows. The two state classes are toggled by the inline script in sidebar-tree.astro and
+   are styled by LabHead.astro as well — do not rename either. */
+.astrobook-sidebar-story-link-inactive {
+  color: var(--lab-color-text);
+}
+.astrobook-sidebar-story-link-inactive:hover {
+  color: var(--lab-color-text-strong);
+  background-color: var(--lab-color-surface);
+}
+.astrobook-sidebar-story-link-active,
+.astrobook-sidebar-story-link-active:hover {
+  color: var(--lab-color-active-text);
+  background-color: var(--lab-color-active-bg);
+}
+.lab-tree-icon {
+  display: block;
+  flex: none;
+  width: 0.875rem;
+  height: 0.875rem;
+  color: var(--lab-color-text-faint);
+}
+.astrobook-sidebar-story-link-active .lab-tree-icon {
+  color: inherit;
+}
+.lab-tree-children {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding-left: 0.75rem;
+}
+/* The collapse animation, lifted verbatim in behaviour from upstream's scoped block so the
+   chevron and the details height still move together. */
+details[data-astrobook-collapsible] {
+  --lab-collapse-ease: cubic-bezier(0, 0, 0.2, 1);
+  interpolate-size: allow-keywords;
+}
+details[data-astrobook-collapsible]::details-content {
+  height: 0;
+  overflow: clip;
+  transition:
+    height var(--collapse-duration, 150ms) var(--lab-collapse-ease),
+    content-visibility var(--collapse-duration, 150ms) var(--lab-collapse-ease) allow-discrete;
+}
+details[data-astrobook-collapsible][open]::details-content {
+  height: auto;
+}
+[data-astrobook-chevron] {
+  transform: rotate(-90deg);
+  transition: transform var(--collapse-duration, 150ms) var(--lab-collapse-ease);
+}
+details[data-astrobook-collapsible][open] > summary > [data-astrobook-chevron] {
+  transform: rotate(0deg);
+}
+/* ---------------------------------------------------------------------------------------------
+   Theme toggle (vendored — see components/theme-script.astro for why the dependency went).
+   --------------------------------------------------------------------------------------------- */
+.lab-theme-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.lab-theme-toggle .lab-theme-icon--dark {
+  display: none;
+}
+:root.dark .lab-theme-toggle .lab-theme-icon--light {
+  display: none;
+}
+:root.dark .lab-theme-toggle .lab-theme-icon--dark {
+  display: block;
+}
+/* ---------------------------------------------------------------------------------------------
+   The built-in splash. Reachable only when a consumer leaves `home` at its default; this package
+   always passes its own (src/Home.astro), so this is the fallback path, kept working.
+   --------------------------------------------------------------------------------------------- */
+.lab-splash {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  width: 100%;
+  padding: 1.5rem;
+  background-color: var(--lab-color-bg);
+}
+.lab-splash__title {
+  margin: 0;
+  font-size: 2rem;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  text-align: center;
+  color: var(--lab-color-text-strong);
+}
+.lab-splash__subtitle {
+  margin: 0.75rem 0 0;
+  font-size: 1rem;
+  text-align: center;
+  color: var(--lab-color-text-muted);
+}
+.lab-splash__badges {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  margin-top: 1.5rem;
+}
+.lab-splash__badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.25rem 0.75rem;
+  border: 1px solid var(--lab-color-border);
+  border-radius: var(--lab-radius-pill);
+  font-family: var(--lab-font-mono);
+  font-size: 0.8125rem;
+  color: var(--lab-color-text-muted);
+  text-decoration: none;
+  transition:
+    color var(--lab-transition),
+    border-color var(--lab-transition);
+}
+.lab-splash__badge:hover {
+  color: var(--lab-color-text-strong);
+  border-color: var(--lab-color-border-strong);
+}
+.lab-splash__badge svg {
+  display: block;
+  width: 0.875rem;
+  height: 0.875rem;
+}

package/virtual.d.ts ADDED Viewed

@@ -0,0 +1,42 @@
+// The virtual modules the lab's own pages read. Defined by the integration (../index.mjs) so the
+// resolved options, the consumer's head component and the consumer's CSS reach the package's
+// .astro pages without any of them importing a path out of the consumer's tree.
+declare module "virtual:orbytes-lab/config.mjs" {
+  export interface LabTier {
+    id: string;
+    label: string;
+    responsive: boolean;
+    cullable: boolean;
+  }
+  export interface LabConfig {
+    directory: string;
+    subpath: string;
+    title: string;
+    css: string[];
+    stagingUrl: string | null;
+    previewUrlTemplate: string | null;
+    feedbucketKey: string | null;
+    tiers: LabTier[];
+    sectionsTier: string | null;
+    cullTier: string | null;
+    responsiveDir: string | null;
+    cullDir: string | null;
+    responsiveFile: string;
+    cullFile: string;
+  }
+  const config: LabConfig;
+  export default config;
+}
+declare module "virtual:orbytes-lab/user-head.mjs" {
+  /**
+   * The consumer's own head component, or the package's Empty.astro when it passes none. Typed
+   * `any` because the module is generated: nothing here knows which .astro file it re-exports,
+   * and the Astro language server types real .astro imports on its own.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const Component: any;
+  export default Component;
+}
+declare module "virtual:orbytes-lab/user-css.mjs" {}