@stapel/search-react 0.12.0 → 0.13.0

package/src/default/cardPhotos.ts

@@ -0,0 +1,195 @@
+/**
+ * WHAT A SEARCH CARD ACTUALLY STORES FOR A PHOTO, and how it becomes something
+ * `@stapel/image` can draw.
+ *
+ * ── The defect this file exists to end ────────────────────────────────────
+ *
+ * The default card used to read `card.image` expecting an object with a `url`
+ * key, and fall back to `card.image_url`. Neither is what this fleet emits:
+ *
+ *  - `image_url` is a convention NOTHING in the fleet writes. It was declared
+ *    in `GENERIC_CARD_FIELDS`, drawn in the demos from a data URI, and never
+ *    once served by a backend.
+ *  - `card.image` IS emitted — by `stapel-classified`'s search projection —
+ *    and it is a plain `<type>/<hash>` STRING, not an object.
+ *  - where a card DOES carry an object (chat's subject card, which serves the
+ *    same CDN render descriptor its attachments carry), that object has `ref`
+ *    and `variants[]` and NO top-level `url` — so the `"url" in rich` guard
+ *    rejected the one rich shape the fleet has.
+ *
+ * The net effect was a card with no photo on every consumer that did not pass
+ * its own `renderCard`. Read the two real shapes instead, and read `images[]`
+ * first: since stapel-classified 0.7.0 the projection carries the whole
+ * gallery in seller order, deduplicated and capped by `CARD_IMAGES_LIMIT`,
+ * with the singular `image` kept as `images[0]`.
+ *
+ * ── Three shapes, one output ──────────────────────────────────────────────
+ *
+ * 1. A CDN reference (`"image/9f2c…"`) — resolved through the runtime's
+ *    {@link SearchImageResolver}, the same seam `@stapel/listings-react`
+ *    states, for the same reason: no contract in this fleet resolves a
+ *    stranger's reference, so the deployment hands its own knowledge in once.
+ * 2. A URL a doc type stored directly (`"https://…"`, `"/media/…"`,
+ *    `"data:image/…"`) — no ladder to shop, so it degrades to `source:
+ *    "link"`. A CDN reference is `<type>/<hash>`: no scheme and no leading
+ *    slash, so the two are told apart by shape and never by a guess.
+ * 3. A render descriptor object — `variants[]` with a `tier` each, an inline
+ *    `preview_b64`, geometry. Read defensively (the field is `unknown` by
+ *    contract) exactly as `@stapel/chat-react` reads the same descriptor.
+ */
+import type { StapelImage } from "@stapel/image";
+import type { SearchImageResolver } from "../model/runtime.js";
+
+/** A card's photo fields, and how many of them the card carried at all. */
+export interface CardPhotos {
+  /**
+   * How many photo entries the card STORES — before resolving. `0` means the
+   * doc type has no photo for this row (or no photo field at all), which is a
+   * different thing from "a photo nothing could resolve", and the card draws
+   * the two differently.
+   */
+  readonly stored: number;
+  /** The ones that became something drawable, in the stored order. */
+  readonly images: readonly StapelImage[];
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * A stored string that is already a URL rather than a CDN reference.
+ *
+ * stapel-cdn's unit is `<type>/<hash>` — a relative pair with no scheme and no
+ * leading slash — so anything carrying a scheme, a protocol-relative prefix or
+ * a leading `/` is a URL the doc type stored itself.
+ */
+function isUrl(value: string): boolean {
+  return (
+    value.startsWith("/") ||
+    value.startsWith("data:") ||
+    /^[a-z][a-z0-9+.-]*:/i.test(value)
+  );
+}
+
+/** A bare URL as the descriptor `<Image>` consumes: one rung, no ladder. */
+function linkImage(url: string): StapelImage {
+  return {
+    source: "link",
+    url,
+    mime: null,
+    width: null,
+    height: null,
+    aspect: null,
+    square: false,
+    preview_b64: null,
+    variants: [],
+  };
+}
+
+/**
+ * One rung of a render descriptor's ladder, in `@stapel/image`'s spelling.
+ *
+ * `tier` arrives in two spellings inside the SAME array — an int for the
+ * ladder rungs and the string sentinel `"original"` for the entry the snapshot
+ * builder appends. `String()` is right for both, which is why there is no
+ * branch here (`@stapel/cdn-react`'s `model/refs.ts` argues it at length).
+ */
+function rung(value: unknown): StapelImage["variants"][number] | undefined {
+  if (!isRecord(value)) return undefined;
+  const url = str(value["url"]);
+  if (url === undefined) return undefined;
+  const tier = value["tier"];
+  const branch = value["branch"];
+  return {
+    tier: typeof tier === "number" || typeof tier === "string" ? String(tier) : "",
+    branch: branch === "w" || branch === "h" ? branch : null,
+    url,
+    width: num(value["width"]),
+    height: num(value["height"]),
+  };
+}
+
+/**
+ * A CDN render descriptor → the descriptor `<Image>` consumes.
+ *
+ * The display URL is the descriptor's own `url` when it has one, else the
+ * `original` rung, else the largest rung — a snapshot carries no
+ * `original_url`, so the top of the ladder IS the original. With no rung at
+ * all the inline `preview_b64` is used: a real, honestly blurry image beats
+ * nothing. A descriptor with neither is not drawable and says so.
+ */
+function metaImage(meta: Readonly<Record<string, unknown>>): StapelImage | undefined {
+  const raw = meta["variants"];
+  const variants = (Array.isArray(raw) ? raw : [])
+    .map(rung)
+    .filter((v): v is StapelImage["variants"][number] => v !== undefined);
+  const original = variants.find((v) => v.tier === "original");
+  const largest = variants.reduce<StapelImage["variants"][number] | undefined>(
+    (best, v) => {
+      const size = Number(v.tier);
+      if (!Number.isFinite(size)) return best;
+      return best === undefined || size > Number(best.tier) ? v : best;
+    },
+    undefined
+  );
+  const preview = str(meta["preview_b64"]);
+  const url = str(meta["url"]) ?? original?.url ?? largest?.url ?? preview;
+  if (url === undefined) return undefined;
+  return {
+    source: "cdn",
+    url,
+    mime: str(meta["mime"]) ?? null,
+    width: num(meta["width"]),
+    height: num(meta["height"]),
+    aspect: num(meta["aspect"]),
+    square: meta["square"] === true,
+    preview_b64: preview ?? null,
+    variants,
+  };
+}
+
+/** One stored entry, in whichever of the three shapes it arrived. */
+export function cardImage(
+  value: unknown,
+  resolve: SearchImageResolver | undefined
+): StapelImage | undefined {
+  const ref = str(value);
+  if (ref !== undefined) {
+    return isUrl(ref) ? linkImage(ref) : resolve?.(ref);
+  }
+  if (isRecord(value)) return metaImage(value);
+  return undefined;
+}
+
+/**
+ * The card's gallery: `images[]` when the doc type carries one, the singular
+ * `image` otherwise.
+ *
+ * Never both — `stapel-classified` stores `image` as `images[0]`, so reading
+ * the singular after the list would draw the first photo twice. The singular
+ * stays the fallback for a doc type that never grew a list.
+ */
+export function readCardPhotos(
+  card: Readonly<Record<string, unknown>>,
+  resolve: SearchImageResolver | undefined
+): CardPhotos {
+  const list = card["images"];
+  const stored: readonly unknown[] = Array.isArray(list)
+    ? list
+    : card["image"] === undefined || card["image"] === null
+      ? []
+      : [card["image"]];
+  const images = stored
+    .map((entry) => cardImage(entry, resolve))
+    .filter((image): image is StapelImage => image !== undefined);
+  return { stored: stored.length, images };
+}

package/src/i18n/es.ts

@@ -40,6 +40,9 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.results.untitled": "Sin título",
   "search.results.open": "Abrir",
   "search.results.image_alt": "Foto de {title}",
+  "search.results.photo_alt": "Foto {index} de {total}: {title}",
+  "search.results.photos": "Fotos",
+  "search.results.photo_unavailable": "Foto no disponible",
 
   "search.box.label": "Buscar",
   "search.box.placeholder": "¿Qué estás buscando?",

package/src/i18n/keys.ts

@@ -56,6 +56,16 @@ export const SEARCH_I18N_KEYS = {
   resultsOpen: "search.results.open",
   /** Alt text for the card photo — the card's own title, in a sentence. */
   resultsImageAlt: "search.results.image_alt",
+  /** Alt text for one photo of a GALLERY: its place in the strip, and the
+   * card's title. A row of ten photos all called "Photo of X" is ten
+   * identical announcements. */
+  resultsPhotoAlt: "search.results.photo_alt",
+  /** The photo strip's accessible name. `SkinCarousel` takes its label from
+   * the caller for exactly this reason: the token bridge owns no i18n. */
+  resultsPhotos: "search.results.photos",
+  /** The card stores a reference and nothing resolved it — a sentence gets
+   * the wiring fixed; an empty grey box teaches nobody anything. */
+  resultsPhotoUnavailable: "search.results.photo_unavailable",
 
   // ── the query box ────────────────────────────────────────────────────────
   boxLabel: "search.box.label",
@@ -318,6 +328,9 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.results.untitled": "Untitled",
   "search.results.open": "Open",
   "search.results.image_alt": "Photo of {title}",
+  "search.results.photo_alt": "Photo {index} of {total}: {title}",
+  "search.results.photos": "Photos",
+  "search.results.photo_unavailable": "Photo unavailable",
 
   "search.box.label": "Search",
   "search.box.placeholder": "What are you looking for?",

package/src/i18n/ru.ts

@@ -63,6 +63,9 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.results.untitled": "Без названия",
   "search.results.open": "Открыть",
   "search.results.image_alt": "Фото: {title}",
+  "search.results.photo_alt": "Фото {index} из {total}: {title}",
+  "search.results.photos": "Фотографии",
+  "search.results.photo_unavailable": "Фото недоступно",
 
   "search.box.label": "Поиск",
   "search.box.placeholder": "Что ищете?",

package/src/index.ts

@@ -145,6 +145,7 @@ export {
 export { createSearchRuntime } from "./model/runtime.js";
 export type {
   SearchRuntime,
+  SearchImageResolver,
   CreateSearchRuntimeOptions,
 } from "./model/runtime.js";
 export {

package/src/model/runtime.ts

@@ -1,8 +1,36 @@
 import { createModuleRuntime } from "@stapel/core";
 import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+import type { StapelImage } from "@stapel/image";
 import { createSearchApi } from "../api/searchApi.js";
 import type { SearchApi } from "../api/searchApi.js";
 
+/**
+ * Turn a stored CDN reference into something renderable.
+ *
+ * ── Why this is a seam and not a URL builder ───────────────────────────────
+ *
+ * A search card's photo fields (`image`, `images`) hold what the indexed doc
+ * type stores, and in this fleet that is an OPAQUE `<type>/<hash>` reference —
+ * the same unit `Listing.images` holds. No contract here resolves a stranger's
+ * reference: stapel-cdn's `file/exists/` is owner-scoped, so
+ * `@stapel/cdn-react`'s `useCdnRef` answers for a person's OWN draft and can
+ * never render somebody else's gallery. A pair that guessed `${base}/${ref}`
+ * would be writing a contract nobody agreed to, and it would break the first
+ * deployment that signs its media paths.
+ *
+ * So the deployment hands its own knowledge in once, exactly as
+ * `@stapel/listings-react`'s `ListingImageResolver` does — one seam, one
+ * spelling, and a container that already has a resolver passes the SAME
+ * function to both runtimes.
+ *
+ * A `StapelImage` rather than a string is what buys the variant ladder: with
+ * `variants` populated, `@stapel/image`'s `<Image>` measures the slot and
+ * picks a tier. A resolver with nothing for a reference returns `undefined`,
+ * and the skin then says "photo unavailable" instead of drawing a broken
+ * `<img>`.
+ */
+export type SearchImageResolver = (ref: string) => StapelImage | undefined;
+
 /**
  * The wired search runtime — core's `ModuleRuntime` bound to this pair's API
  * (slim wave §21/S2). The returned `client` is what the host injects into
@@ -13,7 +41,10 @@ import type { SearchApi } from "../api/searchApi.js";
  * storefront's catalogue, category and search pages need nothing but:
  *
  * ```tsx
- * const runtime = createSearchRuntime({ baseUrl: "/search/api/v1/" });
+ * const runtime = createSearchRuntime({
+ *   baseUrl: "/search/api/v1/",
+ *   resolveImage: (ref) => myCdn.describe(ref),
+ * });
  * <SearchProvider runtime={runtime}>…</SearchProvider>
  * ```
  *
@@ -22,12 +53,20 @@ import type { SearchApi } from "../api/searchApi.js";
  * calls carry it — this pair neither requires nor waits for one, which is why
  * its read hooks are deliberately not gated on `useActiveSessionReady`.
  */
-export type SearchRuntime = ModuleRuntime<SearchApi>;
+export interface SearchRuntime extends ModuleRuntime<SearchApi> {
+  /** See {@link SearchImageResolver}. Absent = a card that stores references
+   * draws the placeholder and names the reason. */
+  readonly resolveImage: SearchImageResolver | undefined;
+}
 
-export type CreateSearchRuntimeOptions = CreateModuleRuntimeOptions;
+export interface CreateSearchRuntimeOptions extends CreateModuleRuntimeOptions {
+  /** See {@link SearchImageResolver}. */
+  readonly resolveImage?: SearchImageResolver;
+}
 
 export function createSearchRuntime(
   options: CreateSearchRuntimeOptions
 ): SearchRuntime {
-  return createModuleRuntime((client) => createSearchApi(client), options);
+  const base = createModuleRuntime((client) => createSearchApi(client), options);
+  return { ...base, resolveImage: options.resolveImage };
 }