@getvitops/core 8.3.0-alpha.4 → 8.3.0-alpha.5

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @getvitops/core
 
+## 8.3.0-alpha.5
+
+### Minor Changes
+
+- 4d94c8b: **Added: `site.chrome` — a configurable masthead and nav behaviour.** Non-breaking.
+
+  - `site.chrome.masthead` (new `@getvitops/config` schema): `position` (`static|sticky|fixed`), `behavior` (`always|hide-on-scroll`), `surface` (`solid|glass|transparent|transparent-until-scrolled`), `tone` (a `colors.roles` key), `layout` (`full|inset|floating`), `width`, `elevation` (`shadow`, `border`, `onScroll`), `height` and `inset`. `height` and `inset` take fluid lengths (`calc()`, `clamp()`, `min()`, `max()`, with `cqi`/`vw`/… units), checked against a closed grammar because they are written into CSS. `validateConfig` rejects a `tone` or `shadow` the design system does not define (only when the default theme states them directly, not via `extends`).
+  - `site.chrome.nav`: `compact` (`drawer|dropdown`), `drawerSide`, `breakpoint`/`mobileBreakpoint`/`megaBreakpoint`, `depth`, `megaDepth`.
+  - `<Masthead config={site}>` (`@getvitops/astro`, slots `brand`/default/`actions`) and `resolveMasthead()` / `resolveNavOptions()`. A prop overrides one field per layout. The key is `chrome`/`masthead` on purpose: `<header>` is valid in any section and `banner` already means the announcement bar and the landmark role.
+  - `<SiteNav>` gains `compact="dropdown"` (a columnar panel anchored under the toggle), `drawerSide` (previously hardcoded to the end edge in Astro), `megaDepth` and `megaPanel`. `.sitenav--mega` now styles second-level items as column headings and has an optional featured column.
+  - `@getvitops/emdash`: `VitopsMegaPanel` fills that column from the widget area `mega-<item url slug>` (or a `mega-area:<name>` class on the menu item). No area means no column.
+  - `@getvitops/create` (emdash template): the layout renders through `<Masthead>`; `site.json` ships a sticky glass masthead with a shadow once scrolled. The hand-written `.navbar { block-size: 64px }` is gone (use `masthead.height`).
+  - CSS (`patterns/masthead.css`, `patterns/sitenav.css`): **all formats**, including tailwind, where the patterns are inlined into `@layer components`. Hide-on-scroll and the `*-on-scroll` states are `scroll-state()` container queries that only subtract from a settled (solid, elevated, visible) bar, so a browser without them (Firefox today) shows that bar rather than a transparent one. A sticky or fixed masthead sets `--header-offset` / `--top-offset` so anchors land below it.
+  - `@getvitops/generator`: new `TIERS.masthead`; `TIERS.sitenav` documents the new props.
+
 ## 8.3.0-alpha.4
 
 ### Minor Changes

package/css/index.css

@@ -40,6 +40,7 @@
 /* navbar before sitenav: sitenav's wide state composes it. */
 @import './patterns/navbar.css';
 @import './patterns/sitenav.css';
+@import './patterns/masthead.css';
 /* After sitenav (the nav family stays contiguous) and after drawer.css, whose
    panel surface navshell's desktop block has to undo. */
 @import './patterns/navshell.css';

package/css/patterns/masthead.css

@@ -0,0 +1,201 @@
+/**
+ * Masthead — the site's top bar: brand, navigation, actions. Pure CSS (tier 1); `<Masthead>`
+ * (`@getvitops/astro`) only emits the classes below from `site.chrome.masthead`.
+ *
+ *   <header class="masthead masthead--sticky masthead--glass masthead--shadow-on-scroll">
+ *     <div class="masthead__row navbar centered">brand · nav · actions</div>
+ *   </header>
+ *
+ * Named "masthead", not "header"/"banner": `<header>` is valid in any section, and `.banner` is
+ * the announcement bar. The element is a plain `<header>` with no explicit `role`.
+ *
+ * ── SAFE BASE, SUBTRACTIVE ENHANCEMENTS ──
+ * The un-modified rule is the settled state: visible, solid (or glass), elevated, in flow.
+ * Scroll behaviour is layered on with `scroll-state()` container queries that only ever
+ * SUBTRACT from it — `*-on-scroll` clears the surface/shadow/border while the page is at the
+ * top; `hide-on-scroll` slides the bar away. Where the query is unsupported (Firefox today)
+ * nothing subtracts, so the bar stays visible, solid and elevated: a query can change how the
+ * bar looks, never leave it unreadable or take the nav away. (Writing these the other way
+ * round — base clear, query reveals — leaves an unsupporting browser with a transparent bar
+ * over body text forever.)
+ *
+ * Hooks (all optional custom properties): `--masthead-height`, `--masthead-bg`, `--masthead-fg`,
+ * `--masthead-blur`, `--masthead-glass-opacity`, `--masthead-inset`, `--masthead-shadow`,
+ * `--masthead-border`. `site.chrome.masthead` sets `--masthead-height` and `--masthead-inset`
+ * on `:root` (see `mastheadRootCss()`), so a clamp()/cqi length there reaches `--header-offset`.
+ */
+
+/* Zero-specificity colour defaults, so a `.tone` (or any class) on the element wins. */
+:where(.masthead) {
+  --_masthead-base: var(--tone-bg, var(--color-bg-surface));
+
+  background-color: var(--masthead-bg, var(--_masthead-base));
+  color: var(--masthead-fg, var(--tone-fg, var(--color-text-surface)));
+}
+
+.masthead {
+  --_masthead-h: var(--masthead-height, 4rem);
+  --_masthead-inset: 0px;
+
+  position: relative;
+  z-index: var(--z-tier-sticky);
+  display: block;
+  box-sizing: border-box;
+  transition:
+    translate 0.25s ease,
+    background-color 0.25s ease,
+    box-shadow 0.25s ease,
+    backdrop-filter 0.25s ease;
+}
+
+.masthead__row {
+  display: block;
+}
+
+/* The row's flex child carries the height; `.centered` (when used) is the grid around it. */
+.masthead__row > .navbar {
+  min-block-size: var(--_masthead-h);
+}
+
+/* `width: full` has no track to supply a gutter. */
+.masthead__row:not(.centered) > .navbar {
+  padding-inline: var(--masthead-gutter, 1rem);
+}
+
+/* ── Position ──────────────────────────────────────────────────────────────── */
+.masthead--sticky {
+  position: sticky;
+  inset-block-start: var(--_masthead-inset);
+}
+
+/* Out of flow: overlays the first section. Pair with `--transparent*`. */
+.masthead--fixed {
+  position: fixed;
+  inset-block-start: var(--_masthead-inset);
+  inset-inline: 0;
+}
+
+/* Anchors and `scroll-padding` land below a pinned masthead. Sticky keeps its space in
+   flow, fixed does not, but both cover the top of the viewport. */
+:root:has(.masthead--sticky, .masthead--fixed) {
+  --header-offset: calc(var(--masthead-height, 4rem) + var(--masthead-inset, 0px));
+  --top-offset: var(--header-offset);
+}
+
+/* ── Surface ───────────────────────────────────────────────────────────────── */
+.masthead--glass {
+  background-color: color-mix(
+    in oklch,
+    var(--masthead-bg, var(--_masthead-base)) var(--masthead-glass-opacity, 72%),
+    transparent
+  );
+  backdrop-filter: blur(var(--masthead-blur, 12px));
+  -webkit-backdrop-filter: blur(var(--masthead-blur, 12px));
+}
+
+/* A browser without backdrop-filter would show page content through a tint. Go solid. */
+@supports not (backdrop-filter: blur(1px)) {
+  .masthead--glass {
+    background-color: var(--masthead-bg, var(--_masthead-base));
+  }
+}
+
+.masthead--transparent {
+  background-color: transparent;
+}
+
+/* ── Layout ────────────────────────────────────────────────────────────────── */
+.masthead--inset,
+.masthead--floating {
+  --_masthead-inset: var(--masthead-inset, 0.75rem);
+
+  margin-inline: var(--_masthead-inset);
+  margin-block-start: var(--_masthead-inset);
+}
+
+/* `fixed` has no flow to margin against: pin the box in by its insets instead. */
+.masthead--fixed.masthead--inset,
+.masthead--fixed.masthead--floating {
+  margin: 0;
+  inset-inline: var(--_masthead-inset);
+}
+
+.masthead--inset {
+  border-radius: var(--br-control, 0.375rem);
+}
+
+.masthead--floating {
+  border-radius: var(--br-panel, 1rem);
+  overflow: clip;
+}
+
+/* ── Elevation ─────────────────────────────────────────────────────────────── */
+.masthead--shadow {
+  box-shadow: var(--masthead-shadow, var(--shadow-sm));
+}
+
+.masthead--border {
+  border-block-end: var(
+    --masthead-border,
+    1px solid var(--tone-border, var(--color-border-surface))
+  );
+}
+
+/* A full outline once the masthead is detached from the viewport edge. */
+.masthead--border:is(.masthead--inset, .masthead--floating) {
+  border: var(--masthead-border, 1px solid var(--tone-border, var(--color-border-surface)));
+}
+
+/* ── Scroll behaviour ───────────────────────────────────────────────────────
+   The page is the scroll-state container. Only when a masthead asks for one, so a
+   site that uses none pays nothing. */
+:root:has(
+  .masthead--hide-on-scroll,
+  .masthead--transparent-until-scrolled,
+  .masthead--shadow-on-scroll,
+  .masthead--border-on-scroll
+) {
+  container: masthead-page / scroll-state;
+}
+
+/* At the top of the page, the *-on-scroll modifiers subtract their settled look. `not
+   scroll-state(scrollable: top)` is "nothing above the viewport", i.e. scrollY = 0. */
+@container masthead-page not scroll-state(scrollable: top) {
+  .masthead--transparent-until-scrolled {
+    background-color: transparent;
+    /* A glass bar would otherwise blur the hero behind an otherwise clear bar. */
+    backdrop-filter: none;
+    -webkit-backdrop-filter: none;
+  }
+  .masthead--shadow-on-scroll {
+    box-shadow: none;
+  }
+  .masthead--border-on-scroll {
+    border-color: transparent;
+  }
+}
+
+/* Slide away while the last scroll was downward; back when it reverses. Never while the
+   visitor is inside it: focus, an open popover or an open disclosure keeps it on screen. */
+@container masthead-page scroll-state(scrolled: block-end) {
+  .masthead--hide-on-scroll:not(:focus-within, :has(:popover-open, details[open])) {
+    translate: 0 calc(-100% - var(--_masthead-inset) - 1px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .masthead {
+    transition: none;
+  }
+}
+
+/* Shadows and tints disappear in forced-colors; keep a real edge. */
+@media (forced-colors: active) {
+  .masthead {
+    border-block-end: 1px solid CanvasText;
+  }
+  .masthead--inset,
+  .masthead--floating {
+    border: 1px solid CanvasText;
+  }
+}

package/css/patterns/sitenav.css

@@ -179,6 +179,77 @@
   }
 }
 
+/* ── Compact dropdown — NARROW ONLY ─────────────────────────────────────────
+   `compact: 'dropdown'` swaps the edge drawer for a panel anchored under the toggle,
+   laid out as columns (each top-level item a column, its sub-links beneath). Same
+   markup; `navClass` emits `sitenav--panel-dropdown` INSTEAD of a `drawer-*` class,
+   so nothing here competes with the drawer's equal-specificity edge rules. Scoped to
+   the narrow state for the reason the whole file is (see "TWO BRANCHES"). */
+.sitenav--panel-dropdown {
+  anchor-scope: --sitenav-toggle;
+}
+.sitenav--panel-dropdown > .sitenav__toggle {
+  anchor-name: --sitenav-toggle;
+}
+
+@container style(--_sitenav-wide: 0) {
+  .sitenav--panel-dropdown .sitenav__panel {
+    position-anchor: --sitenav-toggle;
+    position-area: block-end span-inline-start;
+    inset: auto;
+    margin: var(--sitenav-dropdown-gap, 0.5rem) 0;
+    inline-size: min(calc(100dvw - 1.5rem), var(--sitenav-dropdown-size, 36rem));
+    max-block-size: calc(100dvh - 6rem);
+    padding: 1.25rem;
+    border: var(--b-panel);
+    border-radius: var(--br-panel);
+    box-shadow: var(--ds-panel);
+    translate: 0 -0.5rem;
+  }
+  .sitenav--panel-dropdown .sitenav__panel:popover-open {
+    translate: 0 0;
+  }
+  @starting-style {
+    .sitenav--panel-dropdown .sitenav__panel:popover-open {
+      opacity: 0;
+      translate: 0 -0.5rem;
+    }
+  }
+  /* The dropdown is anchored, not modal: no close button, no dimmed page. */
+  .sitenav--panel-dropdown .sitenav__close {
+    display: none;
+  }
+  .sitenav--panel-dropdown .sitenav__panel {
+    padding-block-start: 1.25rem;
+  }
+  .sitenav--panel-dropdown .sitenav__panel::backdrop {
+    background: transparent;
+  }
+  .sitenav--panel-dropdown .sitenav__panel:popover-open::backdrop {
+    background: transparent;
+  }
+  .sitenav--panel-dropdown .sitenav__list {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
+    gap: 1rem 1.5rem;
+    align-items: start;
+  }
+  /* Columns, not accordions: every sub-list is open, so the caret has nothing to do. */
+  .sitenav--panel-dropdown .sitenav__item--branch {
+    display: block;
+  }
+  .sitenav--panel-dropdown .sitenav__item--branch > .sitenav__submenu {
+    overflow: visible;
+    padding-inline-start: 0;
+  }
+  .sitenav--panel-dropdown .sitenav__disclosure {
+    display: none;
+  }
+  .sitenav--panel-dropdown .sitenav__list > .sitenav__item--branch > .sitenav__link {
+    font-weight: 600;
+  }
+}
+
 /* ── Lists + links ─────────────────────────────────────────────────────────── */
 .sitenav__list,
 .sitenav__submenu {
@@ -534,6 +605,38 @@
   .sitenav--mega .sitenav__submenu .sitenav__disclosure {
     display: none;
   }
+  /* Second level reads as a column heading; its description (`titleAttr`) stays. */
+  .sitenav--mega
+    .sitenav__list
+    > .sitenav__item--branch
+    > .sitenav__submenu
+    > .sitenav__item--branch
+    > .sitenav__link {
+    font-weight: 600;
+    padding-inline: 0;
+  }
+  .sitenav--mega .sitenav__submenu .sitenav__item--branch > .sitenav__submenu {
+    padding-inline: 0;
+  }
+  /* Optional featured column (EmDash widget area via `megaPanel`). */
+  .sitenav--mega .sitenav__mega-extra {
+    flex: 1 1 14rem;
+    margin-inline-start: auto;
+    max-inline-size: 22rem;
+    padding-inline-start: 1.5rem;
+    border-inline-start: 1px solid var(--color-border-surface, currentColor);
+  }
+  .sitenav--mega .sitenav__mega-extra:empty {
+    display: none;
+  }
+}
+
+/* Extra column is a wide-mega feature: in a drawer (a mega menu that is the only tier) it
+   would be an unlabelled block between accordions. Empty (no widget area) shows nothing. */
+@container style(--_sitenav-wide: 0) {
+  .sitenav__mega-extra {
+    display: none;
+  }
 }
 
 /* ── In-page menu (`vitops_nav` block) ─────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/core",
-  "version": "8.3.0-alpha.4",
+  "version": "8.3.0-alpha.5",
   "description": "The Vitops design-system framework — CSS partials, Lit web components, and browser polyfills.",
   "homepage": "https://docs.vitops.ca",
   "bugs": "https://github.com/getvitops/design-system/issues",
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@getvitops/utils": "8.3.0-alpha.4",
+    "@getvitops/utils": "8.3.0-alpha.5",
     "@lit-labs/signals": "^0.3.0",
     "@oddbird/css-anchor-positioning": "^0.9.0",
     "@oddbird/popover-polyfill": "^0.7.0",