@getvitops/astro 2.1.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/astro",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Astro integration for the Vitops design system — favicons/PWA, web-component scripts, and CSS, via a getvitops() integration + <Head /> component.",
   "license": "MIT",
   "files": [
@@ -19,6 +19,8 @@
     "src/components/Popover.astro",
     "src/components/Details.astro",
     "src/components/Drawer.astro",
+    "src/components/NavShell.astro",
+    "src/components/NavShellToggle.astro",
     "src/schemas",
     "virtual.d.ts",
     "CHANGELOG.md"
@@ -42,6 +44,8 @@
     "./components/Popover.astro": "./src/components/Popover.astro",
     "./components/Details.astro": "./src/components/Details.astro",
     "./components/Drawer.astro": "./src/components/Drawer.astro",
+    "./components/NavShell.astro": "./src/components/NavShell.astro",
+    "./components/NavShellToggle.astro": "./src/components/NavShellToggle.astro",
     "./schemas/*": "./src/schemas/*",
     "./package.json": "./package.json"
   },
@@ -49,10 +53,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/core": "2.1.0",
-    "@getvitops/generator": "2.1.0",
-    "@getvitops/utils": "2.1.0",
-    "@getvitops/vite": "2.1.0"
+    "@getvitops/core": "3.0.0",
+    "@getvitops/utils": "3.0.0",
+    "@getvitops/generator": "3.0.0",
+    "@getvitops/vite": "3.0.0"
   },
   "devDependencies": {
     "@astrojs/sitemap": "^3.7.3",

package/src/analytics.ts

@@ -136,7 +136,7 @@ export interface ResolvedAnalytics {
 }
 
 export interface ResolveAnalyticsContext {
-  /** Is the consent gate enabled on this site (`getvitops({ consent })`)? */
+  /** Is the consent gate enabled on this site (`vitops({ consent })`)? */
   consent?: boolean;
 }
 

package/src/components/Analytics.astro

@@ -1,7 +1,7 @@
 ---
 /**
  * <Analytics /> — the site's analytics tags, off the critical path and behind the
- * consent gate. Place in your layout's <head>; requires the getvitops()
+ * consent gate. Place in your layout's <head>; requires the vitops()
  * integration, which supplies `virtual:getvitops/head`.
  *
  * A dumb renderer over `resolveAnalytics()` (src/analytics.ts) — every decision
@@ -19,7 +19,7 @@
  * the critical-path cost the `idle` strategy exists to avoid.
  */
 import { type AnalyticsStrategy, resolveAnalytics } from '../analytics.ts';
-// @ts-ignore — virtual module provided by the getvitops() integration at build time
+// @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 
 interface Props {

package/src/components/CookieConsent.astro

@@ -1,7 +1,7 @@
 ---
 /**
  * <CookieConsent /> — the consent banner. Place near the end of <body>; requires
- * the getvitops() integration with `consent` enabled, which is what loads
+ * the vitops() integration with `consent` enabled, which is what loads
  * `@getvitops/core/consent` (the gate + `<wc-consent>`).
  *
  * This renders the *fallback*: a real, semantic form with real buttons. The
@@ -20,7 +20,7 @@
  * this banner offers therefore comes from the integration, not from
  * `<Analytics />`.
  */
-// @ts-ignore — virtual module provided by the getvitops() integration at build time
+// @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 import type { OptionalConsentCategory } from '../analytics.ts';
 

package/src/components/Details.astro

@@ -15,7 +15,7 @@ interface Props {
   /**
    * Map a semantic name onto a fully-qualified one before rendering.
    *
-   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * @deprecated The `icons` option on `vitops()` now does this centrally, so
    * the site's set is configured once instead of threaded through every call
    * site. Left in place because removing it would break consumers passing one;
    * when omitted, `<Icon />` resolves through the site config.

package/src/components/Drawer.astro

@@ -19,7 +19,7 @@ interface Props {
   /**
    * Map a semantic name onto a fully-qualified one before rendering.
    *
-   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * @deprecated The `icons` option on `vitops()` now does this centrally, so
    * the site's set is configured once instead of threaded through every call
    * site. Left in place because removing it would break consumers passing one;
    * when omitted, `<Icon />` resolves through the site config.

package/src/components/Head.astro

@@ -1,15 +1,15 @@
 ---
 /**
  * <Head /> — the Vitops design system's <head> contributions. Place inside your
- * layout's <head>. Requires the getvitops() integration (it provides the
+ * layout's <head>. Requires the vitops() integration (it provides the
  * `virtual:getvitops/head` config + copies the assets into public/).
  *
  * Renders: favicon + PWA manifest tags, the webfont <Font /> tags for families
- * declared via getvitops({ fonts }), and the web-component runtime scripts in
+ * declared via vitops({ fonts }), and the web-component runtime scripts in
  * canonical order/priority. It does NOT emit a stylesheet <link> — the CSS is
  * imported into Astro's graph by the integration and Astro emits that link.
  */
-// @ts-ignore — virtual module provided by the getvitops() integration at build time
+// @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 // @ts-ignore — `Font` is provided by Astro's Fonts API (astro >= 7)
 import { Font } from 'astro:assets';
@@ -61,7 +61,7 @@ const THEME_SCRIPT =
 {favicons && head.themeColor && <meta name="theme-color" content={head.themeColor} />}
 
 {/*
-  Webfonts declared via getvitops({ fonts }). Astro's `fonts:` config resolves and
+  Webfonts declared via vitops({ fonts }). Astro's `fonts:` config resolves and
   optimises the files; this component is what actually puts the @font-face on the page,
   so without it the config is inert and every --font-* token falls through to its
   fallback stack.
@@ -77,7 +77,7 @@ const THEME_SCRIPT =
   <Font cssVariable={f.cssVariable} preload={f.preload} />
 ))}
 
-{/* Set by getvitops({ sitemap }); null when no sitemap was registered. */}
+{/* Set by vitops({ sitemap }); null when no sitemap was registered. */}
 {head.sitemap && <link rel="sitemap" type="application/xml" href={head.sitemap} />}
 
 {webComponents && (
@@ -112,7 +112,7 @@ const THEME_SCRIPT =
 {head.consentRuntime && <script is:inline type="module" src={`${wc}/consent.js`}></script>}
 
 {/*
-  The live theme editor — a separate, opt-in bundle (getvitops({ editor: true })).
+  The live theme editor — a separate, opt-in bundle (vitops({ editor: true })).
   It is tooling, not part of the runtime, so it stays out of elements.js and off
   every page that doesn't ask for it. Loads independently of `webComponents`:
   <wc-theme-editor> registers itself and pulls in no framework element.

package/src/components/Icon.astro

@@ -67,13 +67,13 @@ if (icons.engine === 'inline' && qualified) {
   svg = await loadIconSvg(qualified, { resolveFrom: icons.root });
   if (!svg)
     console.warn(
-      `[getvitops] <Icon name="${name}"> — "${qualified}" not found. Is ` +
+      `[vitops] <Icon name="${name}"> — "${qualified}" not found. Is ` +
         `@iconify-json/${qualified.slice(0, qualified.indexOf(':'))} installed?`,
     );
 } else if (icons.engine === 'none') {
   console.warn(
-    `[getvitops] <Icon name="${name}"> rendered but icons are not configured. ` +
-      'Add `icons: true` to getvitops() in astro.config.',
+    `[vitops] <Icon name="${name}"> rendered but icons are not configured. ` +
+      'Add `icons: true` to vitops() in astro.config.',
   );
 }
 

package/src/components/NavShell.astro

@@ -0,0 +1,123 @@
+---
+/**
+ * NavShell — a navigation aside beside main content at width, collapsing to a
+ * toggle + drawer below it. Markup only: every declaration lives in the
+ * framework's `navshell` pattern (patterns/navshell.css), which is emitted in
+ * all three output formats.
+ *
+ * It nests. A docs page is typically two of these — a site nav wrapping an
+ * on-this-page nav — promoting at different breakpoints:
+ *
+ *   <NavShell id="site-nav" label="Documentation" breakpoint="md">
+ *     <Fragment slot="nav">…</Fragment>
+ *     <main>
+ *       <NavShell id="page-toc" label="On this page" breakpoint="lg" side="end">
+ *         <Fragment slot="nav">…</Fragment>
+ *         …prose…
+ *       </NavShell>
+ *     </main>
+ *   </NavShell>
+ *
+ * Nothing here may reach for a Tailwind utility: Tailwind doesn't scan
+ * node_modules, so a class only it can emit is silently never generated — and
+ * classes in the generator's TW_CLASH list are stripped from the framework's own
+ * tailwind bundle by design. `navshell*` and `drawer*` are in neither list.
+ *
+ * No runtime JS: the toggle is `<button popovertarget>` against a `[popover]`
+ * panel, so it works from the first paint and degrades to a visible panel if the
+ * Popover API is missing.
+ */
+interface Props {
+  /**
+   * The panel's id, and the `popovertarget` the toggle points at.
+   *
+   * Required, never generated. It IS the toggle↔panel contract, and a generated
+   * id would make the one real hazard of nesting — two instances colliding on
+   * the same id, so the outer toggle opens the inner panel — invisible rather
+   * than impossible. Making the author name each instance makes a collision a
+   * thing you can see in the markup.
+   */
+  id: string;
+  /** Accessible name for the `<nav>`, e.g. "Documentation" / "On this page". */
+  label: string;
+  /** Container width at which the aside appears. Default `md` (48rem). */
+  breakpoint?: 'sm' | 'md' | 'lg' | 'xl';
+  /** Which side the aside sits on at width. Default `start`. */
+  side?: 'start' | 'end';
+  /**
+   * Aside column width once promoted, e.g. `'14rem'`. Defaults to the design
+   * system's `--width-nav` token rather than a literal, so a site retunes every
+   * nav column in one place.
+   */
+  size?: string;
+  /** Accessible name for the toggle. Defaults to `Open ${label}`. */
+  toggleLabel?: string;
+  /**
+   * Where the toggle lives. `'inline'` renders a `.navshell__bar` row above the
+   * content; `'external'` renders none, for when a `<NavShellToggle>` elsewhere
+   * (typically the site header) opens this shell instead.
+   *
+   * Two NESTED shells should not both be `'inline'`: their bars are sticky at
+   * the same offset and land on top of each other. Hoist the outer one.
+   */
+  toggle?: 'inline' | 'external';
+  class?: string;
+}
+
+const {
+  id,
+  label,
+  breakpoint = 'md',
+  side = 'start',
+  // Not a literal: the default REFERENCES the design system's token, so an
+  // unsized instance still tracks `--width-nav`. A literal here would shadow it
+  // on every instance and quietly make the token unreachable through this
+  // component, which is the only way most consumers will use the pattern.
+  size = 'var(--width-nav, 16rem)',
+  toggleLabel,
+  toggle = 'inline',
+  class: className,
+} = Astro.props;
+
+// Always emitted, even when the author passes no `size`. `--navshell-size`
+// inherits (it can't be registered as non-inheriting — a registered property's
+// initial-value must be computationally independent, and this one is in rem), so
+// without this an inner instance would silently adopt an outer instance's column
+// width. Writing it on every root severs the inheritance at each boundary.
+const style = `--navshell-size: ${size}`;
+
+// The drawer slides in from the side its aside will occupy, so the motion points
+// at where the panel is going to live.
+const edge = side === 'end' ? 'drawer--right' : 'drawer--left';
+---
+
+<div
+  class:list={['navshell', `navshell--bp-${breakpoint}`, side === 'end' && 'navshell--end', className]}
+  style={style}
+>
+  {toggle === 'inline' && (
+    <div class="navshell__bar">
+      <slot name="toggle">
+        <button class="navshell__toggle" popovertarget={id} aria-label={toggleLabel ?? `Open ${label}`}>
+          <slot name="toggle-label">{label}</slot>
+        </button>
+      </slot>
+    </div>
+  )}
+
+  <div id={id} popover class:list={['navshell__panel', 'drawer', edge]}>
+    <button
+      class="navshell__close"
+      popovertarget={id}
+      popovertargetaction="hide"
+      aria-label={`Close ${label}`}>&times;</button
+    >
+    <nav class="navshell__nav" aria-label={label}>
+      <slot name="nav" />
+    </nav>
+  </div>
+
+  <div class="navshell__main">
+    <slot />
+  </div>
+</div>

package/src/components/NavShellToggle.astro

@@ -0,0 +1,45 @@
+---
+/**
+ * NavShellToggle — a `<NavShell>` toggle rendered outside its shell, so it can
+ * sit in a site header or navbar rather than in a row of its own.
+ *
+ * Two nested shells both rendering their own sticky toggle row put those rows at
+ * the same offset, on top of each other. Hoisting the outer one into the header
+ * — which is already sticky — leaves a single in-flow bar and no conflict. It is
+ * also simply where a site menu button belongs.
+ *
+ *   <header class="navbar">
+ *     <a href="/">Brand</a>
+ *     <NavShellToggle for="site-nav" label="Menu" breakpoint="md" />
+ *   </header>
+ *   …
+ *   <NavShell id="site-nav" label="Documentation" breakpoint="md" toggle="external">
+ *
+ * `breakpoint` MUST match the shell's: outside `.navshell` the toggle cannot read
+ * the shell's internal "am I wide?" flag (a style query resolves against an
+ * ancestor container, and the header is not one), so it carries its own copy.
+ * Mismatch them and you get a toggle visible next to an expanded sidebar, or no
+ * way to open the nav at all.
+ *
+ * No runtime JS: `popovertarget` is an id reference, which works from anywhere in
+ * the document.
+ */
+interface Props {
+  /** The `id` of the `<NavShell>` this opens. */
+  for: string;
+  /** Visible text (and accessible name, unless `aria-label` is given). */
+  label: string;
+  /** Must match the shell's `breakpoint`. Default `md`. */
+  breakpoint?: 'sm' | 'md' | 'lg' | 'xl';
+  class?: string;
+}
+
+const { for: target, label, breakpoint = 'md', class: className } = Astro.props;
+---
+
+<button
+  class:list={['navshell-toggle', `navshell-toggle--bp-${breakpoint}`, className]}
+  popovertarget={target}
+>
+  <slot>{label}</slot>
+</button>

package/src/components/Popover.astro

@@ -17,7 +17,7 @@ interface Props {
   /**
    * Map a semantic name onto a fully-qualified one before rendering.
    *
-   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * @deprecated The `icons` option on `vitops()` now does this centrally, so
    * the site's set is configured once instead of threaded through every call
    * site. Left in place because removing it would break consumers passing one;
    * when omitted, `<Icon />` resolves through the site config.

package/src/components/Seo.astro

@@ -4,7 +4,7 @@
  * alongside <Head /> (which owns favicons, theme-color and the web-component
  * runtime — the two don't overlap).
  *
- * Site-level defaults come from `getvitops({ seo: … })` via the
+ * Site-level defaults come from `vitops({ seo: … })` via the
  * `virtual:getvitops/head` module; the props here override them per page.
  *
  * It owns <title> and <meta name="description">, so **remove them from your
@@ -21,7 +21,7 @@
  * On an EmDash site use <EmDashHead> instead — it covers the same tags from the
  * CMS. Using both double-emits every og:/twitter: tag.
  */
-// @ts-ignore — virtual module provided by the getvitops() integration at build time
+// @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 import { resolveSeo, type SeoProps } from '../seo.ts';
 

package/src/seo.ts

@@ -17,11 +17,11 @@ export type SeoTwitterCard = 'summary' | 'summary_large_image' | 'app' | 'player
 export type SeoOgType = 'website' | 'article' | 'profile';
 
 /**
- * Site-level SEO defaults, passed to `getvitops({ seo })` and baked into the
+ * Site-level SEO defaults, passed to `vitops({ seo })` and baked into the
  * `virtual:getvitops/head` module. Per-page `<Seo />` props override these.
  *
  * The vocabulary mirrors the site-config schema's `seo` block
- * (`@getvitops/generator`, `src/site.ts`) so a `SiteConfig` → these adapter would
+ * (`@getvitops/generator`, `src/config.ts`) so a `Config` → these adapter would
  * be a flat field map — but it is not imported from there. This is the
  * integration's own option surface, and it must stay JSON-serialisable: it is
  * `JSON.stringify`d into the virtual module, so no functions, no `URL`s, no dates.