@getvitops/astro 5.0.0 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @getvitops/astro
 
+## 6.0.0
+
+### Major Changes
+
+- Carousel rework: a scroll strip that is operable and discoverable with no JS in every engine, and
+  real controls where the scroll-marker pseudo-elements are missing.
+
+  `::scroll-button()`, `::scroll-marker` and `::scroll-marker-group` are still Chromium-only, and
+  there is no usable polyfill (the one prototype targets the superseded syntax and only re-parses
+  inline `<style>` elements). So the carousel no longer assumes them: `<wc-carousel>` builds real
+  prev/next `<button>`s and a real dot nav where they are absent, styled from the same declarations
+  as the native ones. Which branch is live is decided **by the stylesheet** — one `@supports` sets
+  `--carousel-native-nav: 1` and the element reads it back — so the condition is written once and
+  the two cannot disagree.
+
+  **Breaking — `.carousel` is now a shell and `.carousel__track` is the scroller** (all formats). The
+  hint and the controls need a home outside the scrollport, and absolute positioning against the
+  shell replaces `position: fixed` + `anchor-name`/`position-area`, which pinned controls to a
+  viewport corner in any engine without anchor positioning. The 5.x single-element form is still
+  styled via `:not(:has(> .carousel__track))` and is promoted by the element at runtime, but it is
+  deprecated: wrap your slides in `<ul class="carousel__track">`.
+
+  **Breaking — looping is opt-in.** `<wc-carousel loop>` clones the slides; the default no longer
+  does. Cloning triples the markup, duplicates every image element and makes the scrollbar report 3×
+  the real content. `autoplay` implies `loop`. Migration: add `loop`.
+
+  **Breaking — `[part='autoplay']` is now `.carousel__autoplay`** (aliased for one release; `part`
+  only crosses a shadow boundary and this element is light DOM, so it was never a part). The button
+  is also a child of the shell rather than the track, where it used to occupy a slide-width column.
+
+  **Breaking — the host role is `group`, not `region`.** `region` is a landmark, so every carousel
+  grew an entry in the landmark list. Pass `landmark` to `<Carousel />` where it really is one.
+
+  **Changed (visual)** — the scrollbar is visible by default (`scrollbar-width: thin`, was `none`)
+  and a "Scroll for more" hint renders above the strip; both dim once the visitor scrolls, via a
+  scroll-progress timeline where available and a `data-scrolled` attribute otherwise. Opt out with
+  `.carousel--no-scrollbar` and `hint={false}`. `@getvitops/core`'s `global.css` also gains a narrow
+  media reset (`max-inline-size: 100%` on replaced elements, `block-size: auto` on `img`/`video`) —
+  deliberately without `display: block`, which would change inline images in prose.
+
+  **Added** — `@getvitops/astro/components/Carousel.astro`, a tier-3 wrapper emitting semantic
+  `<ul>`/`<li>`/`<figure>` markup with the right per-slide image priorities: the first slide eager
+  and high (the LCP candidate), the rest `lazy`/`low`/`async`. `loading="lazy"` is honoured for
+  images clipped by a horizontal scroll container, so off-screen slides defer with no JavaScript at
+  all. Also new: `carousel--markers-below` and `carousel--no-scrollbar`, and
+  `--carousel-slide-aspect`, which keeps slide heights equal whatever each image's aspect ratio is.
+
+  **Fixed** — `::scroll-button()` glyphs sat off-centre in their circles (`global.css`'s `*` reset
+  does not reach a pseudo-element, so the button was `content-box` with the UA's `padding: 1px 6px`
+  and `inline-size` + `aspect-ratio` sized an ellipse); the hover state was a no-op (it set the same
+  token as the base rule); slide heights varied with each image's aspect ratio; navigation used
+  physical `left`/`right` and so put "previous" on the wrong side in RTL; cloned slides duplicated
+  their `id`s; and `scrollBy(clientWidth)` overshot whenever `--carousel-slide-size` was not `100%`.
+
+### Patch Changes
+
+- Updated dependencies
+  - @getvitops/core@6.0.0
+  - @getvitops/generator@6.0.0
+  - @getvitops/vite@6.0.0
+  - @getvitops/utils@6.0.0
+
 ## 5.0.0
 
 ### Major Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/astro",
-  "version": "5.0.0",
+  "version": "6.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": [
@@ -16,6 +16,7 @@
     "src/ads.ts",
     "src/components/Subgrid.astro",
     "src/components/Cards.astro",
+    "src/components/Carousel.astro",
     "src/components/NodeRenderer.astro",
     "src/components/WebComponentLoader.astro",
     "src/components/Icon.astro",
@@ -58,6 +59,7 @@
     "./Tracking.astro": "./src/components/Tracking.astro",
     "./components/Subgrid.astro": "./src/components/Subgrid.astro",
     "./components/Cards.astro": "./src/components/Cards.astro",
+    "./components/Carousel.astro": "./src/components/Carousel.astro",
     "./components/NodeRenderer.astro": "./src/components/NodeRenderer.astro",
     "./components/WebComponentLoader.astro": "./src/components/WebComponentLoader.astro",
     "./components/Icon.astro": "./src/components/Icon.astro",
@@ -75,10 +77,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/core": "5.0.0",
-    "@getvitops/generator": "5.0.0",
-    "@getvitops/utils": "5.0.0",
-    "@getvitops/vite": "5.0.0"
+    "@getvitops/core": "6.0.0",
+    "@getvitops/generator": "6.0.0",
+    "@getvitops/utils": "6.0.0",
+    "@getvitops/vite": "6.0.0"
   },
   "devDependencies": {
     "@astrojs/sitemap": "^3.7.3",

package/src/components/Carousel.astro

@@ -0,0 +1,230 @@
+---
+/**
+ * A scroll-snap carousel that works with no JavaScript, in every engine.
+ *
+ * Tier-3 in the framework's terms — an authoring convenience that emits the right
+ * `.carousel` markup and requires **no runtime JS**. What it renders stands on its
+ * own:
+ *
+ *   - the slides are a real `<ul>`/`<li>`, so assistive tech announces list
+ *     position and count;
+ *   - the scroller carries `tabindex="0"`, so arrow keys scroll it — the keyboard
+ *     route the platform gives any focusable scroll container, and the reason
+ *     inclusive-components.design/a-content-slider/ focuses the scroller rather
+ *     than building a widget;
+ *   - `scroll-snap` and (in Chromium today) `::scroll-button()` / `::scroll-marker`
+ *     give buttons and dots with no script at all;
+ *   - a visible scrollbar and a "Scroll for more" hint say the strip scrolls, which
+ *     was the missing signal wherever those pseudo-elements are absent;
+ *   - off-screen images are lazy **without JS**: `loading="lazy"` is honoured for
+ *     images clipped by a horizontal scroll container, so there is no `data-src` +
+ *     IntersectionObserver dance to fail.
+ *
+ * **This component emits its own `<wc-carousel>`** — do NOT wrap it in one. That is
+ * the tier-3 rule ("the wrapper emits its `<wc-*>` tag with the accessible fallback
+ * inside"), and `Cards.astro`, `Tree.astro` and `CookieConsent.astro` all do the
+ * same. The element defers to an enclosing one, so a nested pair degrades to a
+ * no-op rather than cloning the same slides twice, but the single call is the
+ * intended shape.
+ *
+ * `<wc-carousel>` adds the opt-in cloned loop, autoplay, and — only where the
+ * browser lacks the scroll-marker pseudo-elements — real prev/next buttons and a
+ * real dot nav. If it never loads, that enhancement is all that is missing, which
+ * is why `enhance={false}` is a supported way to get the bare fragment.
+ *
+ * Three deliberate a11y choices:
+ *
+ *   - **The group role is on the shell, the list role stays on the `<ul>`.** The
+ *     inclusive-components article puts `role="region"` on the scroller because
+ *     there the scroller *is* the container; a shell lets us have real list
+ *     semantics *and* a named group. `group` rather than `region` because `region`
+ *     is a landmark and four carousels would grow four landmark entries — pass
+ *     `landmark` when the carousel really is a page-level landmark.
+ *   - **The visible hint is `aria-hidden`, and a separate `.sr-only` element is the
+ *     description.** The hint fades once the visitor scrolls, so as a description
+ *     it would go stale; and its text is about a pointer affordance, whereas what a
+ *     keyboard user needs described is the arrow keys. One string cannot honestly
+ *     be both.
+ *   - **`aria-describedby` sits on the `<ul>`**, which is the focusable thing, since
+ *     a description is announced on focus.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+export interface CarouselSlide {
+  src: string;
+  alt: string;
+  /**
+   * Intrinsic size. Emitted as `width`/`height` so the UA derives an aspect ratio
+   * and the slide reserves space before the image lands. When unknown,
+   * `--carousel-slide-aspect` still reserves the box, so CLS is covered either way.
+   */
+  width?: number;
+  height?: number;
+  srcset?: string;
+  sizes?: string;
+  caption?: string;
+}
+
+export interface Props extends Omit<HTMLAttributes<'div'>, 'slot'> {
+  /** Accessible name. Required — an unnamed group is unfindable. */
+  label: string;
+  /** Image slides. Omit and use the default slot for richer slides. */
+  slides?: CarouselSlide[];
+  /** Milliseconds between slides. Implies `loop`. */
+  autoplay?: number;
+  /**
+   * Clone the slides for a seamless infinite strip. **Off by default:** it triples
+   * the DOM and duplicates every image element, makes the scrollbar report 3× the
+   * real content, and most carousels do not want it.
+   */
+  loop?: boolean;
+  /** Prev/next controls. */
+  buttons?: boolean;
+  /** Dot navigation. */
+  markers?: boolean;
+  /** Dots below the strip rather than overlaid on it. */
+  markersBelow?: boolean;
+  /** CSS multicol paging. Chromium-only; degrades to a plain strip elsewhere. */
+  columns?: number;
+  /** Dim and inert the off-screen slides. */
+  inert?: boolean;
+  /** `scroll-snap-stop: always` — never skip a slide in one fling. */
+  forceStop?: boolean;
+  /** Hide the scrollbar. Costs the no-JS "this scrolls" signal; be deliberate. */
+  noScrollbar?: boolean;
+  /** `--carousel-slide-aspect`, the ratio every slide's media box takes. */
+  aspect?: string;
+  /** Visible affordance text. `false` removes it. */
+  hint?: string | false;
+  /** Expose as a landmark (`role="region"`) rather than `role="group"`. */
+  landmark?: boolean;
+  /**
+   * Emit the `<wc-carousel>` wrapper (default `true`).
+   *
+   * Set false where the element cannot run — an email, a PDF, a page that does not
+   * load `elements.js`. The carousel is unchanged; only the enhancement layer goes,
+   * so nothing is lost but the loop, autoplay and the non-Chromium control set.
+   */
+  enhance?: boolean;
+  /**
+   * Id prefix for the slide ids and the description. Defaults to a slug of
+   * `label`. Astro has no `useId`, and a random one would change on every build —
+   * so this is derived, deterministic and overridable when two carousels on a page
+   * share a label.
+   */
+  id?: string;
+}
+
+const {
+  label,
+  slides = [],
+  autoplay,
+  loop = false,
+  buttons = true,
+  markers = true,
+  markersBelow = false,
+  columns,
+  inert = false,
+  forceStop = false,
+  noScrollbar = false,
+  aspect = '16 / 9',
+  hint = 'Scroll for more',
+  landmark = false,
+  enhance = true,
+  id,
+  class: className,
+  role,
+  style,
+  ...rest
+} = Astro.props;
+
+const uid =
+  id ??
+  `carousel-${
+    label
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '') || 'x'
+  }`;
+
+const classes = [
+  'carousel',
+  buttons && 'carousel--scroll-buttons',
+  markers && 'carousel--scroll-markers',
+  markersBelow && 'carousel--markers-below',
+  columns && 'carousel--auto-pages',
+  inert && 'carousel--inert',
+  forceStop && 'carousel--force-stop',
+  noScrollbar && 'carousel--no-scrollbar',
+  className,
+];
+
+const vars = [
+  `--carousel-slide-aspect:${aspect}`,
+  columns ? `--carousel-columns:${columns}` : '',
+  style ?? '',
+]
+  .filter(Boolean)
+  .join(';');
+
+const Shell = enhance ? 'wc-carousel' : 'div';
+---
+
+<Shell
+  class:list={classes}
+  role={role ?? (landmark ? 'region' : 'group')}
+  aria-roledescription="carousel"
+  aria-label={label}
+  loop={enhance && (loop || (autoplay ?? 0) > 0) ? '' : undefined}
+  autoplay={enhance && autoplay ? autoplay : undefined}
+  style={vars}
+  {...rest}
+>
+  <ul
+    class="carousel__track"
+    role="list"
+    tabindex="0"
+    aria-label={label}
+    aria-describedby={`${uid}-desc`}
+  >
+    {
+      slides.map((slide, i) => (
+        <li class="carousel__slide" id={`${uid}-slide-${i + 1}`}>
+          <figure class="carousel__media">
+            {/* The first slide is the LCP candidate, so it is eager and high
+                priority; every later one is lazy, low and async. A horizontal
+                scroll container clips them, and `loading="lazy"` is honoured for
+                that, so this is genuinely JS-free deferral. `decoding` is left
+                unset on the first: `sync` can block the main thread, and the UA's
+                own choice for an eager LCP image is better than ours. */}
+            <img
+              src={slide.src}
+              alt={slide.alt}
+              srcset={slide.srcset}
+              sizes={slide.sizes}
+              width={slide.width}
+              height={slide.height}
+              loading={i === 0 ? 'eager' : 'lazy'}
+              fetchpriority={i === 0 ? 'high' : 'low'}
+              decoding={i === 0 ? undefined : 'async'}
+            />
+            {slide.caption && (
+              <figcaption class="carousel__caption font-caption">{slide.caption}</figcaption>
+            )}
+          </figure>
+        </li>
+      ))
+    }
+    <slot />
+  </ul>
+  {
+    hint !== false && (
+      <p class="carousel__hint font-footnote" aria-hidden="true">
+        {hint}
+      </p>
+    )
+  }
+  <p id={`${uid}-desc`} class="sr-only">
+    Use the left and right arrow keys, or scroll sideways, to move between slides.
+  </p>
+</Shell>