@mohasinac/appkit 4.55.0 → 4.57.0

package/dist/ui/components/ImageMosaic.d.ts

@@ -13,6 +13,22 @@ export interface ImageMosaicProps {
     alt: string;
     /** Height preset. Defaults to `"band"`, the original behaviour. */
     size?: ImageMosaicSize;
+    /**
+     * Replaces the large cell's image with arbitrary content — the homepage
+     * hero's brand panel is the only caller.
+     *
+     * 🛑 It changes what `images` MEANS, which is the whole reason it is a
+     * separate prop rather than a `images[0]`-shaped special case: without a
+     * slot the first image takes the large cell, with one EVERY image goes to
+     * the small column. A caller that passes both a slot and three images gets
+     * three small tiles, not two.
+     *
+     * `MOSAIC_MIN` is also not applied in this mode. The minimum exists because
+     * fewer than three images is not an arrangement — but a slot is content in
+     * its own right, so one image beside it is still a composition, and zero
+     * images collapses to the slot alone at full width.
+     */
+    leadSlot?: React.ReactNode;
     className?: string;
 }
 /**
@@ -47,4 +63,4 @@ export interface ImageMosaicProps {
  * breaks SSR/hydration agreement and makes the page feel unstable — and it is
  * the shape Root Cause #25 is about on the seed side.
  */
-export declare function ImageMosaic({ images, alt, size, className }: ImageMosaicProps): React.JSX.Element | null;
+export declare function ImageMosaic({ images, alt, size, leadSlot, className }: ImageMosaicProps): React.JSX.Element | null;

package/dist/ui/components/ImageMosaic.js

@@ -37,11 +37,34 @@ export const MOSAIC_MIN = 3;
  * breaks SSR/hydration agreement and makes the page feel unstable — and it is
  * the shape Root Cause #25 is about on the seed side.
  */
-export function ImageMosaic({ images, alt, size = "band", className }) {
-    const tiles = images.filter(Boolean).slice(0, MOSAIC_MAX);
-    if (tiles.length < MOSAIC_MIN)
+export function ImageMosaic({ images, alt, size = "band", leadSlot, className }) {
+    // With a slot the large cell is already spoken for, so the whole budget
+    // belongs to the small column — one fewer tile than the image-led shape.
+    const tiles = images.filter(Boolean).slice(0, leadSlot ? MOSAIC_MAX - 1 : MOSAIC_MAX);
+    if (!leadSlot && tiles.length < MOSAIC_MIN)
         return null;
-    const [lead, ...rest] = tiles;
+    const [lead, ...rest] = leadSlot ? [undefined, ...tiles] : tiles;
     const sizeClass = size === "hero" ? "appkit-image-mosaic--hero" : "";
-    return (_jsxs(Div, { className: `appkit-image-mosaic ${sizeClass} ${className ?? ""}`, role: "img", "aria-label": alt, children: [_jsx(Div, { className: "appkit-image-mosaic__lead", children: _jsx(MediaImage, { src: lead, alt: "", size: "card" }) }), _jsx(Div, { className: "appkit-image-mosaic__rest", children: rest.map((src, i) => (_jsx(Div, { className: "appkit-image-mosaic__tile", children: _jsx(MediaImage, { src: src, alt: "", size: "thumbnail" }) }, `${src}-${i}`))) })] }));
+    // Nothing to put in the small column — the 1fr track would otherwise render
+    // as an empty gutter beside the slot, which reads as a failed image load
+    // rather than as a deliberate panel.
+    const soloClass = leadSlot && rest.length === 0 ? "appkit-image-mosaic--solo" : "";
+    /*
+     * 🛑 WHERE `role="img"` GOES DEPENDS ON THE SLOT, and getting this wrong is
+     * silent.
+     *
+     * `role="img"` collapses its entire subtree into ONE node named by
+     * `aria-label` — that is exactly right for a group of decorative thumbnails
+     * (point 1 in the header: one alt describing the subject, not five
+     * filenames). Leave it on the grid in `leadSlot` mode and it also swallows
+     * the slot, so the hero's logo and its "Let It Rip India" caption would
+     * reach a screen reader as "…collection highlights" and nothing else — real
+     * content erased by a label meant for the pictures beside it.
+     *
+     * So in slot mode the role moves down to the image group, where it belongs,
+     * and the slot stays ordinary DOM. The no-slot path is byte-identical to
+     * what it always was.
+     */
+    const imageGroupA11y = { role: "img", "aria-label": alt };
+    return (_jsxs(Div, { className: `appkit-image-mosaic ${sizeClass} ${soloClass} ${className ?? ""}`, ...(leadSlot ? {} : imageGroupA11y), children: [_jsx(Div, { className: "appkit-image-mosaic__lead", children: leadSlot ?? _jsx(MediaImage, { src: lead, alt: "", size: "card" }) }), rest.length > 0 && (_jsx(Div, { className: "appkit-image-mosaic__rest", ...(leadSlot ? imageGroupA11y : {}), children: rest.map((src, i) => (_jsx(Div, { className: "appkit-image-mosaic__tile", children: _jsx(MediaImage, { src: src, alt: "", size: "thumbnail" }) }, `${src}-${i}`))) }))] }));
 }

package/dist/ui/components/ImageMosaic.style.css

@@ -7,10 +7,19 @@
  * around as a visitor moves through the tree. A fixed height per breakpoint is
  * the one shape that keeps the hero stable.
  *
- * 🛑 `overflow: hidden` on the grid and `object-fit: cover` on the images, so a
- * portrait product photo cannot stretch the band. Every image here is a
- * thumbnail of unknown aspect ratio; cropping is the only option that does not
- * distort the subject.
+ * 🛑 `overflow: hidden` on the grid, and the images are CONTAINED rather than
+ * cropped. This block used to say the opposite — "cropping is the only option
+ * that does not distort the subject" — and `object-fit: cover` was declared
+ * here. Both are gone: `MediaImage` now defaults to `contain` app-wide, which
+ * it applies as a Tailwind utility, and both Tailwind configs set
+ * `important: true` — so a plain `object-fit: cover` declaration here could
+ * never have won anyway. It would have been a rule that reads as the
+ * governing decision while changing nothing (Root Cause #106).
+ *
+ * The trade is real and is the one that was asked for: a 4:3 publisher shot in
+ * a square tile now letterboxes against `--appkit-color-surface` instead of
+ * having its edges cut off. Most of this catalogue's imagery is product-on-
+ * white, where a crop removes the product and `contain` does not.
  */
 .appkit-image-mosaic {
   display: grid;
@@ -49,6 +58,16 @@
   }
 }
 
+/*
+ * `--solo` — a `leadSlot` with no images beside it.
+ *
+ * One column, not `2fr 1fr`. The small track has nothing to hold, and an empty
+ * 1fr gutter beside a brand panel reads as four images that failed to load.
+ */
+.appkit-image-mosaic--solo {
+  grid-template-columns: 1fr;
+}
+
 .appkit-image-mosaic__lead,
 .appkit-image-mosaic__tile {
   position: relative;
@@ -61,7 +80,20 @@
 .appkit-image-mosaic__tile img {
   width: 100%;
   height: 100%;
-  object-fit: cover;
+}
+
+/*
+ * Breathing room INSIDE the tile, so a contained image stops short of the
+ * rounded corners instead of touching them. On `cover` this was unnecessary —
+ * the crop ran to the edge by definition — which is why it arrives with the
+ * fit change rather than before it.
+ */
+.appkit-image-mosaic__lead img {
+  padding: var(--appkit-space-3);
+}
+
+.appkit-image-mosaic__tile img {
+  padding: var(--appkit-space-2);
 }
 
 .appkit-image-mosaic__rest {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.55.0",
+  "version": "4.57.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"