@hagicode/hagilight-starlight 0.15.1 → 0.15.2-dev.159.1.216d0b5

package/ArticlePromotion.astro

@@ -20,7 +20,7 @@ import ArticlePromotionPicker from './ArticlePromotionPicker.astro';
 
 interface Props {
   lang?: string;
-  /** Swap the illustration for one random pool entry per page view. Defaults to `true`. */
+  /** Deal the illustration as a fan of random cat heads, like the footer avatar. Defaults to `true`. */
   randomAvatar?: boolean;
 }
 
@@ -46,7 +46,7 @@ const galleryImages: Record<string, ImageMetadata> = {
   heroes,
   'cat-head': catHead,
 };
-// The illustration slot is the only gallery image that may change; its pool lives in the showcase manifest.
+// The illustration slot is the only gallery image that may change; its pool lives in the showcase manifest. It is dealt as the footer's fan of cat heads.
 const ILLUSTRATION_ID = 'cat-head';
 const avatarEntry = showcaseManifest.assets.find(({ id }) => id === ILLUSTRATION_ID);
 const avatarPool = randomAvatar && avatarEntry && 'pool' in avatarEntry ? randomPoolFromManifest(avatarEntry.pool) : undefined;
@@ -106,7 +106,7 @@ const gallery = copy.gallery.flatMap((item) => {
     <ul class="hagilight-article-promotion__gallery" aria-labelledby="hagilight-article-promotion-gallery-title">
       {gallery.map((item) => (
         <li>
-          <figure data-random-pool={item.id === ILLUSTRATION_ID && avatarPool ? randomPoolAttribute(avatarPool) : undefined}>
+          <figure>
             <Picture
               src={item.image}
               alt={item.alt}
@@ -119,6 +119,7 @@ const gallery = copy.gallery.flatMap((item) => {
               loading="lazy"
               decoding="async"
               fetchpriority="low"
+              pictureAttributes={item.id === ILLUSTRATION_ID && avatarPool ? { 'data-random-fan': randomPoolAttribute(avatarPool) } : undefined}
             />
             <figcaption>{item.caption}</figcaption>
           </figure>
@@ -442,6 +443,90 @@ const gallery = copy.gallery.flatMap((item) => {
     max-width: 12rem;
   }
 
+  /*
+   * The illustration's fan, the footer avatar's fan at the illustration's size: three cards pivot on a point
+   * below the stack, the vendored default is the first centre card and fades out as the random cards are dealt
+   * over it. Offsets are percentages of a card, so the fan scales with the 12 rem box.
+   */
+  .hagilight-article-promotion picture[data-random-fan] {
+    position: relative;
+    aspect-ratio: 112 / 76;
+  }
+
+  .hagilight-article-promotion picture[data-random-fan] img,
+  .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan__card) {
+    position: absolute;
+    top: 13.16%;
+    left: 25%;
+    width: 50%;
+    height: auto;
+    aspect-ratio: 1;
+    border: 0;
+    box-shadow: 0 0 0 2px var(--sl-color-bg), 0 3px 8px -2px color-mix(in srgb, var(--sl-color-black) 45%, transparent);
+    transform-origin: 50% 140%;
+    transition: opacity 320ms ease-out, transform 760ms cubic-bezier(0.16, 1, 0.3, 1);
+  }
+
+  .hagilight-article-promotion figure:hover picture[data-random-fan] img,
+  .hagilight-article-promotion figure:hover picture[data-random-fan] :global(.hagilight-fan__card) {
+    border: 0;
+  }
+
+  .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan) {
+    position: absolute;
+    inset: 0;
+    display: block;
+  }
+
+  .hagilight-article-promotion figure:hover picture[data-random-fan] img[data-fan-out],
+  .hagilight-article-promotion picture[data-random-fan] img[data-fan-out] {
+    opacity: 0;
+    transform: scale(0.9);
+  }
+
+  .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan__card) {
+    z-index: 0;
+    opacity: 0;
+    transform: scale(0.6);
+  }
+
+  .hagilight-article-promotion figure:hover picture[data-random-fan] :global(.hagilight-fan__card[data-slot="0"]),
+  .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan__card[data-slot="0"]) {
+    z-index: 1;
+    opacity: 1;
+    transform: translate(-11%, 2%) rotate(-17deg);
+  }
+
+  .hagilight-article-promotion figure:hover picture[data-random-fan] :global(.hagilight-fan__card[data-slot="1"]),
+  .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan__card[data-slot="1"]) {
+    z-index: 3;
+    opacity: 1;
+    transform: none;
+  }
+
+  .hagilight-article-promotion figure:hover picture[data-random-fan] :global(.hagilight-fan__card[data-slot="2"]),
+  .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan__card[data-slot="2"]) {
+    z-index: 2;
+    opacity: 1;
+    transform: translate(11%, 2%) rotate(17deg);
+  }
+
+  .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan__card[data-slot="3"]),
+  .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan__card[data-slot="4"]) {
+    transform: translate(18%, 0) rotate(34deg) scale(0.7);
+  }
+
+  .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan__card[data-slot="5"]) {
+    transform: translate(-18%, 0) rotate(-36deg) scale(0.7);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .hagilight-article-promotion picture[data-random-fan] img,
+    .hagilight-article-promotion picture[data-random-fan] :global(.hagilight-fan__card) {
+      transition: none;
+    }
+  }
+
   /* Closing: a full-bleed band, the heaviest surface, so "get it" is where the eye lands last. */
   .hagilight-article-promotion__closing {
     display: grid;

package/ArticlePromotionPicker.astro

@@ -1,9 +1,9 @@
 ---
-// Rendered only when the showcase's random option is on, so a site that turns it off ships no picker script.
+// Rendered only when the showcase's random option is on, so a site that turns it off ships no picker script. The illustration deals its cats as the footer's fan.
 ---
 
 <script>
-  import { mountRandomImages } from '@hagicode/hagilight-core/random-image';
+  import { mountRandomFans } from '@hagicode/hagilight-core/random-image';
 
-  void mountRandomImages(document);
+  void mountRandomFans(document);
 </script>

package/README.md

@@ -167,7 +167,7 @@ The copy and assets mirror `repos/web` and `repos/docs` in the HagiCode monorepo
 
 - **Copy:** edit `src/article-promotion-copy/<locale>.ts` (every locale must keep the same fields, feature ids, and gallery ids). Terminology is pinned in `GLOSSARY` in `src/article-promotion-copy/index.ts`, seeded from the product locale files in `repos/web/src/locales/<locale>/`. `HagiCode`, `OpenSpec`, `Hero Scenario`, `Microsoft Store`, and `Windows` are never translated.
 - **Images:** audit the candidate, crop and convert it to WebP (the AVIF and JPEG tiers are derived at build time, so an opaque image needs no extra file), add or update its `manifest.json` entry, register it in the `galleryImages` map in `ArticlePromotion.astro`, and add a caption and text alternative in every locale. The gallery mosaic places the first, second, and third catalog entries as the left top, left bottom, and right tall slot, so keep the three screenshots first. The illustration is the fourth entry: from 36rem it takes a full-width row with a 12 rem square and its caption, and it is the only gallery image that may change. To add a screenshot, revisit the placement in the component's `@container (min-width: 36rem)` block. `npm test` checks that the manifest, the files, the component registry, and the copy agree.
-- **Random illustration (R2 pool):** the `cat-head` entry in `assets/showcase/manifest.json` carries `source` (`repo: img-gen`, `album`, `objectKey`), its audit, and `pool` (`album`, `maxBytes` 200 KiB, `entries` with `key` and `bytes`). `ArticlePromotion.astro` builds the pool attribute at build time and renders `ArticlePromotionPicker.astro` only when the option is on. Refresh: take keys from the `cat-head-gallery` album `index.json`, keep 12 to 200 unique keys each within `maxBytes`, audit them text-free and current, update `pool.entries`, and keep the footer pool in `repos/hagilight/packages/core/assets/footer/manifest.json` in step. To rebuild the WebP, resize the source to 1200 px (lanczos3) and encode at quality 88. `npm test` (`test/showcase-assets.test.mjs`) checks the entry, the pool, the byte caps and the budgets.
+- **Random illustration (R2 pool):** the `cat-head` entry in `assets/showcase/manifest.json` carries `source` (`repo: img-gen`, `album`, `objectKey`), its audit, and `pool` (`album`, `maxBytes` 200 KiB, `entries` with `key` and `bytes`). `ArticlePromotion.astro` builds the pool attribute (`data-random-fan` on the illustration's `<picture>`) at build time and renders `ArticlePromotionPicker.astro` only when the option is on. The picker runs `mountRandomFans`, so the illustration is dealt as the same turning fan of three cat heads as the footer avatar, at the illustration's 12 rem width. Refresh: take keys from the `cat-head-gallery` album `index.json`, keep 12 to 200 unique keys each within `maxBytes`, audit them text-free and current, update `pool.entries`, and keep the footer pool in `repos/hagilight/packages/core/assets/footer/manifest.json` in step. To rebuild the WebP, resize the source to 1200 px (lanczos3) and encode at quality 88. `npm test` (`test/showcase-assets.test.mjs`) checks the entry, the pool, the byte caps and the budgets.
 - **Options:** `hagicodePromotion: { randomAvatar: false }` keeps the default illustration and loads no picker; `footer: { avatar: false }` removes the footer avatar, and `footer: { randomAvatar: false }` keeps its default. A site whose `img-src` policy blocks `https://img-gen.hagicode.com` keeps the defaults.
 - **Badge:** the product id is parsed from the Store URL and the badge language map lives in `src/windows-download.ts`. Re-check both against `repos/docs/src/components/MicrosoftStoreBadge.tsx` and the official site when the Store listing or the supported languages change.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.15.1",
+  "version": "0.15.2-dev.159.1.216d0b5",
   "type": "module",
   "description": "Starlight plugin and components for HagiCode documentation",
   "repository": {
@@ -53,7 +53,7 @@
     "assets/showcase/*"
   ],
   "dependencies": {
-    "@hagicode/hagilight-core": "0.15.1"
+    "@hagicode/hagilight-core": "0.15.2-dev.159.1.216d0b5"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",