@getvitops/astro 6.0.0 → 8.0.0

package/src/components/Gallery.astro

@@ -0,0 +1,218 @@
+---
+/**
+ * A `.gallery` thumbnail grid whose triggers open a single `.lightbox-dialog`
+ * wrapping a `<Carousel />` of every image — a fully working modal lightbox with
+ * zero JavaScript.
+ *
+ * Tier-3 in the framework's terms — an authoring convenience that emits the right
+ * `.gallery` / `.lightbox-dialog` markup and needs no runtime JS to be usable:
+ *
+ *   - each thumbnail is a real `<a href="#slide-id">` into the carousel's own
+ *     `<li id="slide-id">`, so following it is ordinary fragment navigation —
+ *     no Invoker Commands, no polyfill, in every engine;
+ *   - `:has(:target)` in `patterns/lightbox.css` is what reveals the dialog once
+ *     that navigation lands, and the browser's own fragment scroll puts the
+ *     carousel on the right slide;
+ *   - prev/next, dots, arrow keys and swipe are the carousel's — reused, not
+ *     re-implemented, and already dual-path (native `::scroll-button()` /
+ *     `::scroll-marker` where the engine has them, real fallback buttons where
+ *     it doesn't).
+ *
+ * **This component emits its own `<wc-gallery>`, wrapping its own `<Carousel />`
+ * (which emits its own `<wc-carousel>`)** — do NOT wrap either in one yourself.
+ * That is the tier-3 rule ("the wrapper emits its `<wc-*>` tag with the
+ * accessible fallback inside"). `<wc-gallery>` only intercepts a trigger click to
+ * `showModal()` the dialog and run the thumbnail → full-image view-transition
+ * morph; it does not step between slides — the nested `<wc-carousel>` does that,
+ * and if it never loads, the dialog is still a plain scroll-snap strip.
+ *
+ * `enhance={false}` on `<Gallery />` still emits a real, working carousel inside
+ * the dialog (`enhance` is passed through) — the fallback here is not a stripped
+ * lightbox, it is a genuine one, because a scroll-snap carousel needs no
+ * `<wc-gallery>` at all to already have prev/next.
+ *
+ * Images take `string | ImageMetadata` via `<ResponsiveImage />`: a plain string
+ * renders a raw `<img>` (unchanged from before `ImageMetadata` support existed);
+ * an `astro:assets` import renders through `<Picture />` for AVIF/WebP
+ * derivatives. `formats` is passed straight through, including a value
+ * astro:assets doesn't recognise yet — see `ResponsiveImage.astro`'s docblock for
+ * why (no hard-coded closed format union).
+ */
+import type { HTMLAttributes } from 'astro/types';
+import Carousel from './Carousel.astro';
+import ResponsiveImage from './ResponsiveImage.astro';
+import type { ImageFormat } from './ResponsiveImage.astro';
+
+export interface GalleryImage {
+  /** Full-size image, shown in the dialog. */
+  src: string | ImageMetadata;
+  /** Thumbnail. Defaults to `src` — for an `ImageMetadata` source, rendered at `thumbWidth`. */
+  thumb?: string | ImageMetadata;
+  /** Pixel width to request for the thumbnail derivative when `src`/`thumb` is `ImageMetadata`. */
+  thumbWidth?: number;
+  alt: string;
+  caption?: string;
+  width?: number;
+  height?: number;
+  /** Only meaningful when `src` is a plain string — see `ResponsiveImage.astro`. */
+  srcset?: string;
+  sizes?: string;
+}
+
+export interface Props extends Omit<HTMLAttributes<'div'>, 'slot'> {
+  /** Accessible name for the grid, and for the dialog it opens. Required. */
+  label: string;
+  images?: GalleryImage[];
+  /** Passed to every `<Picture formats>`. Default `['avif', 'webp']`. */
+  formats?: ImageFormat[];
+  /** `--gallery-thumb-size` — minimum thumbnail track width. Default `150px`. */
+  thumbSize?: string;
+  /** `--gallery-gap`. Default `0.5rem`. */
+  gap?: string;
+  /** `--gallery-aspect` — every thumbnail's box ratio. Default `1`. */
+  aspect?: string;
+  /** Wrap prev/next past the ends instead of stopping there. Passed to `<Carousel loop>`. */
+  loop?: boolean;
+  /**
+   * Emit the `<wc-gallery>` wrapper (default `true`). Also controls `<Carousel
+   * enhance>` — set false where no runtime JS will ever load at all (an email, a
+   * PDF); the dialog still opens via `:target` and the carousel is still a real,
+   * scroll-snapping strip, just without the morph, autoplay-adjacent polish, or
+   * (outside Chromium today) prev/next buttons.
+   */
+  enhance?: boolean;
+  /**
+   * Id prefix for the dialog and slide ids. 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 galleries on a page share a
+   * label.
+   */
+  id?: string;
+}
+
+const {
+  label,
+  images = [],
+  formats = ['avif', 'webp'],
+  thumbSize,
+  gap,
+  aspect,
+  loop = false,
+  enhance = true,
+  id,
+  class: className,
+  role,
+  style,
+  ...rest
+} = Astro.props;
+
+const uid =
+  id ??
+  `gallery-${
+    label
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '') || 'x'
+  }`;
+
+const vars = [
+  thumbSize ? `--gallery-thumb-size:${thumbSize}` : '',
+  gap ? `--gallery-gap:${gap}` : '',
+  aspect ? `--gallery-aspect:${aspect}` : '',
+  style ?? '',
+]
+  .filter(Boolean)
+  .join(';');
+
+const Shell = enhance ? 'wc-gallery' : 'div';
+---
+
+<Shell
+  class:list={['gallery-shell', className]}
+  role={role ?? 'group'}
+  aria-label={label}
+  style={vars}
+  {...rest}
+>
+  <ul class="gallery" role="list">
+    {
+      images.map((img, i) => {
+        const thumb = img.thumb ?? img.src;
+        return (
+          <li class="gallery__item">
+            <a class="gallery__trigger" href={`#${uid}-img-${i}`}>
+              <ResponsiveImage
+                src={thumb}
+                alt={img.alt}
+                formats={formats}
+                class="gallery__thumb"
+                width={typeof thumb === 'string' ? undefined : (img.thumbWidth ?? 400)}
+                loading={i === 0 ? 'eager' : 'lazy'}
+                fetchpriority={i === 0 ? 'high' : 'low'}
+                decoding={i === 0 ? undefined : 'async'}
+              />
+              <span class="visually-hidden">View full size</span>
+            </a>
+          </li>
+        );
+      })
+    }
+    <slot />
+  </ul>
+  <dialog id={uid} class="lightbox-dialog" closedby="any" aria-label={label}>
+    <Carousel
+      id={`${uid}-track`}
+      label={label}
+      class="lightbox-dialog__track"
+      enhance={enhance}
+      loop={loop}
+      hint={false}
+    >
+      {
+        images.map((img, i) => {
+          const thumb = img.thumb ?? img.src;
+          // A per-slide placeholder: whatever's already on screen (the
+          // thumbnail) stays painted in `.carousel__media`'s background until
+          // the full image finishes loading, so the view-transition morph
+          // never has an empty box as its target — see lightbox.css.
+          const placeholder = typeof thumb === 'string' ? `--lightbox-placeholder:url(${JSON.stringify(thumb)})` : '';
+          return (
+            <li class="carousel__slide" id={`${uid}-img-${i}`}>
+              <figure class="carousel__media" style={placeholder}>
+                <ResponsiveImage
+                  src={img.src}
+                  alt={img.alt}
+                  formats={formats}
+                  width={img.width}
+                  height={img.height}
+                  srcset={img.srcset}
+                  sizes={img.sizes}
+                  loading="lazy"
+                />
+                {img.caption && <figcaption class="carousel__caption font-caption">{img.caption}</figcaption>}
+              </figure>
+            </li>
+          );
+        })
+      }
+    </Carousel>
+    <a class="lightbox-dialog__close" href="#" aria-label="Close">&times;</a>
+  </dialog>
+</Shell>
+
+<style>
+  /* Icon-only trigger keeps its label for screen readers. Component-scoped
+     rather than the framework's `sr-only`: that one is in the generator's
+     TW_CLASH list, so the tailwind format ships no rule for it. */
+  .visually-hidden {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+</style>

package/src/components/Marquee.astro

@@ -0,0 +1,63 @@
+---
+/**
+ * A `.marquee` — content scrolling seamlessly along a track (a strip of
+ * testimonials, logos, a ticker).
+ *
+ * Tier-3 like `Counter.astro`: the pattern is pure CSS
+ * (`@getvitops/core/css/patterns/marquee.css`'s `@keyframes marquee-scroll`), and
+ * `<wc-marquee>` only fixes the seam gap by cloning `.marquee__content` enough
+ * times to cover the track — "how many copies cover this container" is a
+ * measurement CSS cannot make. With no JS (or `enhance={false}`), this still
+ * scrolls exactly as authored; it just isn't seamless with a short content run.
+ *
+ * **This component emits its own `<wc-marquee>`** — do NOT wrap it in one, same
+ * rule as `Counter.astro`/`Carousel.astro`.
+ *
+ * Put the items in the default slot — a list of `<ReviewCard>`s, logos,
+ * whatever scrolls. They become the one `.marquee__content` copy the element
+ * clones from.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+export interface Props extends Omit<HTMLAttributes<'div'>, 'slot'> {
+  /** Pause the scroll on hover (default false). */
+  pauseOnHover?: boolean;
+  /** Scroll in the opposite direction (default false). */
+  reverse?: boolean;
+  /** Scroll along the block axis instead of inline (default false). */
+  vertical?: boolean;
+  /**
+   * Emit the `<wc-marquee>` wrapper (default `true`).
+   *
+   * Set false where the element cannot run. The scroll animation still works —
+   * only the seamless-loop fixup goes.
+   */
+  enhance?: boolean;
+}
+
+const {
+  pauseOnHover = false,
+  reverse = false,
+  vertical = false,
+  enhance = true,
+  class: className,
+  ...rest
+} = Astro.props;
+
+const Shell = enhance ? 'wc-marquee' : 'div';
+---
+
+<Shell
+  class:list={[
+    'marquee',
+    pauseOnHover && 'marquee--pause-hover',
+    reverse && 'marquee--reverse',
+    vertical && 'marquee--vertical',
+    className,
+  ]}
+  {...rest}
+>
+  <div class="marquee__content">
+    <slot />
+  </div>
+</Shell>

package/src/components/ResponsiveImage.astro

@@ -0,0 +1,52 @@
+---
+/**
+ * Internal helper — turns `string | ImageMetadata` into markup, so `Gallery` and
+ * `Carousel` render images identically and cannot drift from each other.
+ *
+ * Not exported from `package.json`: it is packaging detail, not a pattern a
+ * consumer places on a page (same treatment as `TreeNode.astro`), so it carries
+ * no `TIERS` entry either — `tiers.test.ts` only scans `exports`.
+ *
+ * A plain `string` renders the raw `<img>` path every Astro component in this
+ * package already used before `ImageMetadata` support existed — unchanged, so
+ * every existing string-`src` call site keeps rendering byte-identical markup.
+ * An `ImageMetadata` (an `astro:assets` image import) renders through
+ * `<Picture />`, which is what gets a consumer AVIF/WebP derivatives instead of
+ * shipping whatever format the source file happens to be in.
+ *
+ * `formats` defaults to `['avif', 'webp']` and is passed straight through to
+ * `<Picture formats>` — including a value astro:assets doesn't recognise yet.
+ * That is deliberate: Astro's `VALID_OUTPUT_FORMATS` today is
+ * `avif/png/webp/jpeg/jpg/svg` (no JPEG-XL — the sharp service can't emit it), so
+ * hard-coding a closed format union here would need editing the day a service
+ * adds one. `ImageFormat` mirrors Astro's own `ImageOutputFormat`
+ * (`… | (string & {})`) for exactly that reason, defined locally rather than
+ * imported — `astro:assets`'s ambient module declaration doesn't export it, and
+ * reaching into `astro/dist/**` for a type is not a stable import.
+ */
+import { Picture } from 'astro:assets';
+import type { HTMLAttributes } from 'astro/types';
+
+export type ImageFormat = 'avif' | 'webp' | 'png' | 'jpeg' | 'jpg' | 'gif' | 'svg' | (string & {});
+
+export interface Props extends Omit<HTMLAttributes<'img'>, 'src' | 'alt'> {
+  src: string | ImageMetadata;
+  alt: string;
+  formats?: ImageFormat[];
+  /**
+   * Only meaningful when `src` is a plain `string` — Astro computes its own
+   * `srcset` for an `ImageMetadata` source and this is not merged with it.
+   */
+  srcset?: string;
+}
+
+const { src, alt, formats = ['avif', 'webp'], srcset, class: className, ...rest } = Astro.props;
+---
+
+{
+  typeof src === 'string' ? (
+    <img src={src} alt={alt} srcset={srcset} class={className} {...rest} />
+  ) : (
+    <Picture src={src} alt={alt} formats={formats} class={className} {...rest} />
+  )
+}

package/src/components/ReviewCard.astro

@@ -0,0 +1,60 @@
+---
+/**
+ * One `.review` card, from a `vitops reviews` cache entry
+ * (`@getvitops/utils/reviews`'s `Review`).
+ *
+ * Pure tier-3: `.review` is a config-generated pattern
+ * (`patterns.items.review`), so this needs no runtime JS, no `<wc-*>` tag, and
+ * therefore no `enhance` prop. Put several inside `<Carousel>` slides or
+ * `<Marquee>` items — there is no group component.
+ *
+ * **Named `ReviewCard`, not `Review`.** `../schemas/Review.astro` already owns
+ * that name for the JSON-LD builder this component composes when `schema` is
+ * true; two same-named components differing only by directory is a needless
+ * import trap.
+ *
+ * **`schema` defaults to false.** Google's structured-data policy treats a
+ * business marking up reviews of itself as ineligible for review rich results,
+ * and risks a manual action — see AGENTS.md's Reviews section. Pass
+ * `itemReviewed` (the business the review is of) only when you have deliberately
+ * decided to emit it anyway; without it, `schema` is a no-op.
+ *
+ * **`avatar` defaults to false.** A reviewer's photo is a Google-hosted URL —
+ * rendering it by default would put a third-party request on every page and
+ * depend on a link that isn't guaranteed to stay live. With it off,
+ * `.review__initials` carries the author's initials instead.
+ */
+import type { ComponentProps, HTMLAttributes } from 'astro/types';
+import type { Review } from '@getvitops/utils/reviews';
+import ReviewCardBody from './ReviewCardBody.astro';
+import SchemaReview from '../schemas/Review.astro';
+
+export interface Props extends Omit<HTMLAttributes<'article'>, 'slot'> {
+  review: Review;
+  /** Emit `Review` JSON-LD via `../schemas/Review.astro` (default false). */
+  schema?: boolean;
+  /** Required for `schema` to take effect — the business this review is of. */
+  itemReviewed?: ComponentProps<typeof SchemaReview>['itemReviewed'];
+  /** Render the reviewer's Google-hosted avatar photo (default false). */
+  avatar?: boolean;
+}
+
+const { review, schema = false, itemReviewed, avatar = false, ...rest } = Astro.props;
+---
+
+{
+  schema && itemReviewed ? (
+    <SchemaReview
+      itemReviewed={itemReviewed}
+      reviewRating={{ ratingValue: review.rating }}
+      author={{ name: review.author }}
+      datePublished={review.publishedAt}
+      reviewBody={review.text}
+      publisher={{ name: 'Google', type: 'Organization' }}
+    >
+      <ReviewCardBody review={review} avatar={avatar} {...rest} />
+    </SchemaReview>
+  ) : (
+    <ReviewCardBody review={review} avatar={avatar} {...rest} />
+  )
+}

package/src/components/ReviewCardBody.astro

@@ -0,0 +1,67 @@
+---
+/**
+ * The `.review` markup itself — split out of `ReviewCard.astro` purely so it can
+ * be rendered twice (once bare, once wrapped in `../schemas/Review.astro`'s
+ * JSON-LD `<script>`) without duplicating the template. Not a public export;
+ * `ReviewCard.astro` is the tier-3 entry point.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import type { Review } from '@getvitops/utils/reviews';
+import Icon from './Icon.astro';
+
+export interface Props extends Omit<HTMLAttributes<'article'>, 'slot'> {
+  review: Review;
+  avatar: boolean;
+}
+
+const { review, avatar, class: className, ...rest } = Astro.props;
+
+const initials = review.author
+  .split(/\s+/)
+  .filter(Boolean)
+  .slice(0, 2)
+  .map((w) => w[0]?.toUpperCase())
+  .join('');
+
+const full = Math.floor(review.rating);
+const hasHalf = review.rating - full >= 0.5;
+---
+
+<article class:list={['review', className]} {...rest}>
+  <header class="review__header">
+    {
+      avatar && review.authorPhoto ? (
+        <img class="review__avatar" src={review.authorPhoto} alt="" loading="lazy" />
+      ) : (
+        <span class="review__initials" aria-hidden="true">{initials}</span>
+      )
+    }
+    <div class="review__identity">
+      <cite class="review__author">{review.author}</cite>
+      <time class="review__date" datetime={review.publishedAt}>
+        {new Date(review.publishedAt).toLocaleDateString()}
+      </time>
+    </div>
+    <span class="review__stars" role="img" aria-label={`${review.rating} out of 5 stars`}>
+      {Array.from({ length: 5 }, (_, i) => {
+        const half = i === full && hasHalf;
+        const empty = i >= full && !half;
+        return (
+          <Icon
+            name={half ? 'star-half' : 'star'}
+            class:list={['review__star', empty && 'review__star--empty']}
+          />
+        );
+      })}
+    </span>
+  </header>
+  {review.text && <blockquote class="review__body">{review.text}</blockquote>}
+  {
+    review.reply && (
+      <footer class="review__reply">
+        <p class="review__reply-author">Response from the owner</p>
+        <p>{review.reply.text}</p>
+      </footer>
+    )
+  }
+</article>

package/src/components/Tree.astro

@@ -10,9 +10,12 @@
  *     position and depth. A `<div>` soup looks identical and tells a screen-reader
  *     user nothing about where they are;
  *   - every branch is a native `<details>`/`<summary>`, so expanded state and
- *     keyboard operation come from the platform. No `role="tree"`, no
- *     `aria-expanded` bookkeeping — a hand-rolled ARIA tree that loses its JS is
- *     worse than no ARIA at all;
+ *     keyboard operation come from the platform with no JS at all. This
+ *     fallback carries no `role="tree"` and no `aria-expanded` bookkeeping —
+ *     those aren't hand-rolled into markup that would be silently wrong the
+ *     instant JS failed to load; `<wc-tree>` applies them on upgrade, over a
+ *     DOM it unwraps for the purpose (branches lose their `<details>`/
+ *     `<summary>` entirely — see that element's own docblock for why and how);
  *   - nodes carry ids, so any node is linkable without JS.
  *
  * **This component emits its own `<wc-tree>`** — do NOT wrap it in one. That is the
@@ -22,9 +25,11 @@
  * element now defers to an enclosing one, so it degrades to a no-op rather than two
  * duelling toolbars, but the single call is the intended shape.
  *
- * `<wc-tree>` upgrades it with filter, expand/collapse-all and deep-linking. If
- * that never loads, only those three conveniences are missing — which is why
- * `enhance={false}` is a supported way to get the bare fragment.
+ * `<wc-tree>` upgrades it with WAI-ARIA tree semantics, roving-tabindex keyboard
+ * navigation, filter, expand/collapse-all and hash deep-linking. If that never
+ * loads, the fallback above — native nested `<details>`, Tab-and-Enter — is all
+ * that remains, which is why `enhance={false}` is a supported way to get the
+ * bare fragment on its own.
  */
 import type { TreeItem } from './tree.ts';
 import TreeNode from './TreeNode.astro';

package/src/components/TreeNode.astro

@@ -6,13 +6,23 @@
  *
  *   - a **branch** wraps its label in `<details>`/`<summary>` — a native
  *     disclosure button, so expanded state is announced and keyboard operation
- *     is free. The child `<ul>` lives inside the `<details>`, which is what makes
- *     it collapse with no JS.
+ *     is free with no JS. The child `<ul>` lives inside the `<details>`, which
+ *     is what makes it collapse with no JS.
  *   - a **leaf** is a plain `.tree__content` row. A `<details>` with nothing to
  *     disclose would still render a control and announce as collapsible.
  *
+ * That description is the NO-JS contract only. `<wc-tree>` unwraps every
+ * branch's `<details>`/`<summary>` on upgrade — see its own docblock — so once
+ * it loads, "keyboard operation is free" stops meaning native Tab-and-Enter and
+ * starts meaning that element's roving-tabindex arrow-key navigation instead,
+ * and `role="treeitem"`/`role="group"` replace the `<li>`'s and `<ul>`'s
+ * implicit `listitem`/`list` roles. The markup below never changes to reflect
+ * that — it's the fallback `<wc-tree>` reads and transforms, not two things to
+ * keep in sync.
+ *
  * The item class sits on the `<li>` in both cases, so `<wc-tree>`'s filter treats
- * leaves and branches as one kind of thing and hiding one hides its whole row.
+ * leaves and branches as one kind of thing and hiding one hides its whole row —
+ * true before and after upgrade, since the transform preserves the class.
  */
 import type { TreeItem } from './tree.ts';
 

package/src/schemas/Article.astro

@@ -1,6 +1,6 @@
 ---
-import { articleGraph } from '@getvitops/utils';
-import type { ArticleGraphOptions } from '@getvitops/utils';
+import { articleGraph } from '@getvitops/utils/schema';
+import type { ArticleGraphOptions } from '@getvitops/utils/schema';
 
 export type Props = ArticleGraphOptions;
 

package/src/schemas/Breadcrumb.astro

@@ -1,6 +1,6 @@
 ---
-import { breadcrumbGraph } from '@getvitops/utils';
-import type { BreadcrumbGraphOptions, BreadcrumbItem } from '@getvitops/utils';
+import { breadcrumbGraph } from '@getvitops/utils/schema';
+import type { BreadcrumbGraphOptions, BreadcrumbItem } from '@getvitops/utils/schema';
 
 export type { BreadcrumbItem };
 export type Props = BreadcrumbGraphOptions;

package/src/schemas/Carousel.astro

@@ -1,33 +1,12 @@
 ---
-export interface CarouselItem {
-  type: 'Article' | 'Recipe' | 'Movie' | 'Course' | 'Restaurant' | 'Product';
-  name: string;
-  url: string;
-  image?: string;
-  description?: string;
-}
+import { itemListGraph } from '@getvitops/utils/schema';
+import type { ItemListEntry, ItemListGraphOptions } from '@getvitops/utils/schema';
 
-export interface Props {
-  items: CarouselItem[];
-}
+export type { ItemListEntry };
+export type CarouselItem = ItemListEntry;
+export type Props = ItemListGraphOptions;
 
-const { items } = Astro.props;
-
-const jsonLd = {
-  '@context': 'https://schema.org',
-  '@type': 'ItemList',
-  itemListElement: items.map((item, index) => ({
-    '@type': 'ListItem',
-    position: index + 1,
-    item: {
-      '@type': item.type,
-      name: item.name,
-      url: item.url,
-      ...(item.image && { image: item.image }),
-      ...(item.description && { description: item.description }),
-    },
-  })),
-};
+const jsonLd = itemListGraph(Astro.props);
 ---
 
 <script is:inline type="application/ld+json" set:html={JSON.stringify(jsonLd)} />

package/src/schemas/FAQ.astro

@@ -5,8 +5,8 @@
  * NOTE: Google recommends FAQ markup only for authoritative government
  * and health sites. For other sites, consider using QAPage schema instead.
  */
-import { faqGraph } from '@getvitops/utils';
-import type { FAQGraphOptions, FAQItem } from '@getvitops/utils';
+import { faqGraph } from '@getvitops/utils/schema';
+import type { FAQGraphOptions, FAQItem } from '@getvitops/utils/schema';
 
 export type { FAQItem };
 export type Props = FAQGraphOptions;