/**
 * `<CategoryTileGrid>` — the phone landing's category tiles: two rows that
 * scroll sideways, with the third column peeking in so the row reads as
 * scrollable without a scrollbar to say so.
 *
 * ── Why a second surface instead of a prop on the strip ────────────────────
 *
 * `<CategoryCarouselStrip>` is a WRAPPING row of labelled cards — the desktop
 * shape, and it stays exactly what it is. This is a different geometry with a
 * different reading order (a fixed two-row grid, a horizontal scroll port, a
 * tile whose label and art sit in opposite corners), and folding both into one
 * component would mean a `layout` prop nobody could photograph either arm of.
 * They share the one thing worth sharing: the headless `<CategoryCarousel>`
 * bag, so both rows are the same categories in the same order.
 *
 * ── The image seam is the strip's seam, unchanged ──────────────────────────
 *
 * `carousel_icon` / `catalog_icon` are OPAQUE STRINGS the backend deliberately
 * does not resolve, so this skin never BUILDS one: it hands the reference to
 * the host through `renderIcon` — the SAME contract
 * `<CategoryCarouselStrip>` takes, so a storefront wires its CDN resolver once
 * and both surfaces draw art. Where the reference already IS an address (a
 * seeded catalogue writes the uploaded asset's URL into `catalog_icon`) the
 * tile draws it, and where it is neither the tile draws the category's own
 * initial as {@link TileMonogram} — a tile with nothing in its art corner
 * reads as a broken tile. Never a guessed URL, and therefore never a broken
 * image; the order and the reasoning are on {@link tileArt}.
 *
 * ── Two sources of rows, one geometry ──────────────────────────────────────
 *
 * By default the rows come from the carousel bag, which answers exactly one
 * question: which categories the operator put on the front page. A CATEGORY
 * landing asks a different one — what is inside THIS category — and its answer
 * is already in the host's hand (`useCategoryTree()`), not on the carousel
 * endpoint. {@link CategoryTileGridProps.entries} is that second source, and
 * when it is given `<CategoryCarousel>` is not mounted at all, so the override
 * costs no request it would then discard.
 *
 * ── Where tiles STOP ───────────────────────────────────────────────────────
 *
 * Tiles are the top level and a top-level category's children, and nothing
 * deeper: below that a category is a CHARACTERISTIC, chosen through cascading
 * child selectors when filtering or posting, not a tile a person navigates
 * into. {@link CategoryTileGridProps.categoryDepth} is how a landing says
 * which depth it is at, and past the cap this component renders NOTHING at
 * all — not an empty state, because there is no absence to report: the
 * sub-categories exist, they are simply offered somewhere else, in a different
 * shape. The number itself lives in `catalog/tiles.ts` so the search and
 * composer surfaces read the same one.
 *
 * ── Geometry ───────────────────────────────────────────────────────────────
 *
 * Every length is relative to the CONTAINER, not to the viewport: the column
 * is `100% / 2.5` of the scroll port minus one gap, and the tile's height
 * comes from its aspect ratio. A tile sized in viewport pixels is a tile that
 * is the wrong size inside every panel, sheet and column that is not the whole
 * screen — and this row is mounted inside all three.
 *
 * `layout="wrap"` keeps that rule and drops the scroll port: the columns come
 * from `minmax(min(minTileWidth, 100%), 1fr)`, so the tiles wrap onto as many
 * lines as the container needs and none of them is off screen.
 */
import { useMemo, useState } from "react";
import type { CSSProperties, ReactElement, ReactNode } from "react";
import { Flex, Input, List, Skeleton } from "antd";
import { cssVar, fontSize, fontWeight, radii, spacing } from "@stapel/tokens-antd";
import { STAPEL_UI_KEYS, useI18n, useT } from "@stapel/core";
import type { LinkComponent } from "@stapel/core";
import type { Category } from "../api/types.js";
import { renderCategoryLabel } from "../catalog/labels.js";
import { categoryIconSrc, categoryOffersTileGrid } from "../catalog/tiles.js";
import { CategoryCarousel } from "../headless/CategoryCarousel.js";
import type {
  CarouselEntry,
  CategoryTileEntry,
  VirtualTileEntry,
} from "../headless/CategoryCarousel.js";
import { CATEGORIES_I18N_KEYS } from "../i18n/keys.js";
import { CategoryLink } from "./CategoryLink.js";
import type { LinkComponentProp } from "./CategoryLink.js";
import {
  EmptyState,
  ErrorAlert,
  LoadList,
  PHONE_CONTROL_HEIGHT,
  SkinDialog,
  SkinTheme,
} from "@stapel/tokens-antd/skin";
import type { ThemeModeProp } from "./types.js";

/** Rows in the scroller. Two, per the reference — one row wastes the height a
 * phone has, three makes the tile too small to carry a two-line label. */
const TILE_ROWS = 2;

/**
 * How many columns fit the scroll port. The half is the whole point: a row
 * that ends flush on a column edge looks like the end of the list, and the
 * peeking third tile is what says "there is more to the right" without a
 * scrollbar, an arrow or a hint line.
 */
const VISIBLE_COLUMNS = 2.5;

/**
 * The COMPACT geometry, in two numbers (the owner's ruling on tile size,
 * 2026-09-02: the cozy tiles were "huge" at 390px and a fraction-of-container
 * column turned a 1440px catalogue page into a wall of ~550px tiles).
 *
 * More visible columns makes the phone row dense — a 390px port shows four
 * tiles and the peek of a fifth. The PIXEL CAP is the desktop half of the
 * same fix: the column is `min(fraction, cap)`, so a wide container gets a
 * modest strip of 128px tiles instead of inflating the fraction into
 * billboards. Both numbers stay relative to the CONTAINER first — the cap
 * only stops the growth, it never stretches a narrow port.
 */
const COMPACT_VISIBLE_COLUMNS = 4.4;
const COMPACT_MAX_COLUMN_PX = 128;

/**
 * THE NARROWEST A COMPACT COLUMN MAY BE, and it is an arithmetic rather than
 * a taste.
 *
 * The fraction alone gave a 390px phone a 63px caption column, and the
 * catalogue's longest root name — a twelve-letter single word — measures
 * ~83px at the caption's 12px (the stand's own reading: nine letters, 62px).
 * 83 into 63 does not go, so the caption broke inside the word.
 *
 * So the column has a FLOOR: the longest name's measure plus the tile's
 * inline padding, rounded up a step for the next long name. Below it the
 * grid gives up a column rather than a word — three tiles and a peek on a
 * 390px phone instead of four and a peek. The fraction and the 128px cap are
 * untouched above it, so every wider container is exactly what it was.
 */
const COMPACT_MIN_COLUMN_PX = 96;

/** The two tile geometries a host can ask for. `cozy` is the reference
 * two-row scroller; `compact` is the dense strip — see the constants above. */
export type TileDensity = "cozy" | "compact";

/**
 * The tile's own ANATOMY, orthogonal to {@link TileDensity} (which packs the
 * SCROLLER's columns) and to {@link TileLayout} (scroll vs wrap).
 *
 * `"regular"` (default) is the reference root tile — label top-left, art
 * bottom-right, unchanged. `"compact"` is the reference's SECOND-level tile
 * (owner's verdict, 2026-09-04): a person landing inside a category sees a
 * denser row about HALF the root tile's height for the same width. A root page
 * (the home) stays `"regular"`; every tile page below it is where `"compact"`
 * belongs.
 *
 * WHAT IS IN THAT ROW depends on the SURFACE, and only since the flat tile
 * (architect's verdict, superseding 2026-09-04 for the flat surface only) —
 * see {@link tileSizeCompact} and {@link tileSizeCompactFlat}. The height and
 * the density are the 2026-09-04 ruling either way.
 */
export type TileSize = "regular" | "compact";

/**
 * `"compact"` size's own geometry — a THIRD anatomy, not a smaller `cozy` or
 * a re-skinned `density: "compact"` (that one centres the art over the label
 * for the phone SCROLLER; this one is a horizontal row, because the two solve
 * different problems at different depths of the catalogue).
 *
 * The aspect ratio is derived, not guessed: {@link TILE_ASPECT_RATIO} is
 * `4 / 3` (height = 0.75 × width), so HALF that height at the same width is
 * `1.5 / 4` → `8 / 3` the other way up.
 */
const COMPACT_SIZE_ASPECT_RATIO = "8 / 3";
/** Denser grid than the regular 240px default — the owner's number. */
const COMPACT_SIZE_MIN_TILE_WIDTH = 220;
/** Smaller type at this density — the label is one clamped line shorter too
 * (2, not 3), because a horizontal row has no third line to spend. */
const COMPACT_SIZE_LABEL_FONT_SIZE = 13;
/** A small picture, never a corner ornament at this size — a fixed fraction
 * of the row, capped so a wide row does not inflate it into a second tile. */
const COMPACT_SIZE_ART_WIDTH = "32%";
const COMPACT_SIZE_ART_MAX_PX = 56;

/**
 * WHERE THE COMPACT ROW'S PICTURE BECOMES A CORNER GLYPH, measured on the
 * TILE and not on the window.
 *
 * The row is `[caption][art]`, and the art took a flat 32% of it. On a narrow
 * scroller that is the caption's width being spent on decoration: a storefront
 * running this size at 2.5 columns on a 390px phone left ~90px of caption, and
 * its two longest single-word root names — twelve and eleven letters — ended
 * in an ellipsis INSIDE the word. The name is the only part of a tile that
 * says where the tap goes, so it is the part that may not be sacrificed.
 *
 * Below this width the picture drops to {@link COMPACT_SIZE_ART_GLYPH_PX} and
 * the caption takes everything it gives up. The threshold is a CONTAINER
 * query on the tile, so a host that mounts the same size in a wide sidebar and
 * a narrow phone strip gets the right answer in both without telling the pair
 * which is which.
 */
const COMPACT_SIZE_ART_TIGHT_PX = 200;
const COMPACT_SIZE_ART_GLYPH_PX = 24;
/** The container this tile establishes, so the query above cannot be
 * answered by somebody else's box. */
const COMPACT_SIZE_CONTAINER = "stapel-category-tile";
/** The class the compact row's art carries, so the sheet can reach it. */
export const CATEGORY_TILE_ART_CLASS = "stapel-category-tile-art";
/** Tighter gap between tiles at this density, and between the label and the
 * picture inside one row. */
const COMPACT_SIZE_GAP = spacing[1];
const DEFAULT_GAP = spacing[2];

/** Tile proportions — wider than tall, so a two-line label and the art corner
 * both fit without the row eating the fold. */
const TILE_ASPECT_RATIO = "4 / 3";

/**
 * The art corner's own aspect ratio — the same ratio {@link TileImage} draws
 * its `<img>` at. Giving the WRAPPER this ratio too (not just the image) is
 * what reserves the corner's height on the first frame: a definite width (a
 * percentage of the tile, itself sized by {@link TILE_ASPECT_RATIO} from a
 * definite grid column) times a definite ratio is a definite height, with no
 * dependency on an asset that has not decoded yet. The box is the SAME shape
 * whether it ends up holding a picture or {@link TileMonogram} — the tile's
 * own height must not depend on which one a row happens to have.
 */
const ART_ASPECT_RATIO = "3 / 2";

/**
 * Lines a tile's label may take before it is clipped.
 *
 * Three, not the original two, and with hyphenation below — measured on a
 * live 390px classified catalogue: the tile's inner column is ~105px there,
 * one root name is a single 12-letter word wider than that (the clamp
 * ellipsized it on its FIRST line), and the longest root name is three lines
 * of text however it breaks. Real root names in a hyphenating language need
 * the third line more than the art corner needs the headroom.
 */
const LABEL_LINES = 3;

/**
 * HOW MANY ROWS `count` TILES TAKE IN `columns` COLUMNS.
 *
 * One line of arithmetic, exported, because three places need the same answer
 * and a fourth (a host holding the stage's box from outside the pair) had no
 * way to ask for it and was guessing a height instead — which is the defect
 * this file's budget note keeps recording under other names.
 *
 * Six tiles in five columns is TWO rows; five in five is ONE. A stage that
 * reserves a fixed number of rows leaves the difference as an empty band
 * under the last tile, before whatever block comes next.
 *
 * Zero tiles is zero rows and not one: there is no content, so there is no
 * box, and a row reserved for nothing is the hole an empty state exists to
 * replace.
 */
export function tileStageRows(count: number, columns: number): number {
  if (count <= 0) return 0;
  return Math.ceil(count / Math.max(1, columns));
}

/**
 * How many tiles the loading arm reserves room for when the caller does not
 * say — the number this arm has always drawn.
 *
 * A caller that KNOWS how many are coming says so
 * ({@link CategoryTileGridProps.reserveCount}) and the reservation is then the
 * box the tiles land in rather than a fixed four: the skeletons sit in the
 * SAME grid, so the browser lays out `tileStageRows(count, columns)` rows for
 * the reserve exactly as it will for the answer, with no second copy of the
 * geometry to drift from the first.
 */
const RESERVED_TILES_DEFAULT = 4;

/**
 * THE BOX THE TILES ARRIVE INTO — the row's own geometry, filled with
 * skeletons, and the one place it is written.
 *
 * Shared between the carousel arm's `loading` slot and
 * {@link CategoryTileGridProps.reserve}, because a reserved box that is not
 * the box the tiles land in is a smaller shift rather than no shift: the
 * skeletons carry {@link TILE_ASPECT_RATIO} inside the same
 * {@link listStyle} grid, so the reservation is the same height whichever
 * side of the seam asked for it.
 */
function ReservedTiles(props: {
  readonly layout: TileLayout;
  readonly density: TileDensity;
  readonly minTileWidth: number;
  readonly size: TileSize;
  /** How many tiles are coming. One skeleton each, in the grid they will land
   * in, so the reserved height is the rows they will take and no more. */
  readonly count: number;
  /** The scroller's column count, so the box held before the answer is the
   * box the answer lands in. */
  readonly visibleColumns?: number;
}): ReactElement {
  const slots = Array.from({ length: Math.max(0, props.count) }, (_, i) => i);
  return (
    <div
      style={listStyle(
        props.layout,
        props.density,
        props.minTileWidth,
        props.size,
        props.count,
        props.visibleColumns
      )}
      data-testid="categories-tile-grid-reserved-list"
      data-reserved-tiles={String(slots.length)}
    >
      {slots.map((slot) => (
        <Skeleton.Button
          key={slot}
          active
          block
          // The shape of the tile that is coming — see `tileAspectRatio`.
          style={{
            aspectRatio: tileAspectRatio(props.density, props.size),
            height: "auto",
          }}
        />
      ))}
    </div>
  );
}

/** The scroller's own geometry, `gap` threaded through so `size: "compact"`
 * (see {@link COMPACT_SIZE_GAP}) can tighten it without a second copy of the
 * grid rules. */
function scrollerStyle(
  density: TileDensity,
  gap: number,
  count: number,
  visibleColumns: number = VISIBLE_COLUMNS
): CSSProperties {
  const columns =
    density === "compact"
      ? // A floor, the fraction, a cap — see `COMPACT_MIN_COLUMN_PX`. `clamp`
        // rather than a nested `min`/`max` pair so the three numbers read in
        // the order they act in.
        `clamp(${COMPACT_MIN_COLUMN_PX}px, calc(100% / ${COMPACT_VISIBLE_COLUMNS} - ${gap}px), ${COMPACT_MAX_COLUMN_PX}px)`
      : // `100%` is the SCROLL PORT's content box, so the tile is a fraction
        // of the box it was mounted in — see this file's header.
        `calc(100% / ${String(visibleColumns)} - ${gap}px)`;
  // Two rows is the shape, not a floor. `grid-auto-flow: column` fills a
  // declared row whether or not a tile lands in it, so a stage with one tile
  // used to declare a second, empty row and pay its gap — an empty band under
  // the only thing on screen. The rows are what the tiles need, capped at the
  // reference's two.
  const rows = Math.min(TILE_ROWS, Math.max(1, count));
  return {
    display: "grid",
    gridAutoFlow: "column",
    gridTemplateRows: `repeat(${String(rows)}, auto)`,
    gridAutoColumns: columns,
    gap,
    overflowX: "auto",
    overscrollBehaviorX: "contain",
    scrollSnapType: "x proximity",
    // The scroll port is the affordance; a scrollbar over a 2-row tile grid
    // on a phone is chrome that covers the art.
    scrollbarWidth: "none",
  };
}

/**
 * The two ways the tiles fill their container.
 *
 * `"scroll"` (default) is the reference phone row: two rows deep, sideways,
 * with the peeking column that says there is more. `"wrap"` is the same tiles
 * with no scroll port at all — as many per line as the width allows, wrapping
 * onto as many lines as it takes, so EVERY category is on screen at once.
 *
 * A landing that wants the whole catalogue visible (a desktop home page, a
 * category page's subcategories) cannot get there from the scroller: a wrapped
 * grid is a different geometry, not a wider one, and a host that needed it had
 * to draw its own tiles — which is the same tile anatomy re-implemented, and
 * the copy that drifts.
 */
export type TileLayout = "scroll" | "wrap";

/**
 * The narrowest a wrapped tile may be before the grid drops a column
 * (`repeat(auto-fill, minmax(...))`). 240px is the reference desktop tile.
 */
const DEFAULT_MIN_TILE_WIDTH = 240;

/**
 * The wrapping arm.
 *
 * `min(<width>, 100%)` rather than the bare width: `minmax` with a fixed
 * minimum is the classic auto-fill overflow — inside a container narrower
 * than one tile the track keeps its minimum and the page scrolls sideways,
 * which is precisely the thing this layout exists not to do.
 */
function wrapStyle(minTileWidth: number, gap: number): CSSProperties {
  return {
    display: "grid",
    gridTemplateColumns: `repeat(auto-fill, minmax(min(${String(minTileWidth)}px, 100%), 1fr))`,
    gap,
  };
}

/** The container the tiles sit in — one of the two geometries. */
function listStyle(
  layout: TileLayout,
  density: TileDensity,
  minTileWidth: number,
  size: TileSize,
  count: number,
  visibleColumns?: number
): CSSProperties {
  const gap = size === "compact" ? COMPACT_SIZE_GAP : DEFAULT_GAP;
  // `wrap` needs no row count of its own: the tiles are the grid's items, so
  // the browser lays out `tileStageRows(count, columns)` rows and not one
  // more — which is the whole reason the reserve draws one skeleton per tile
  // rather than a fixed four.
  return layout === "wrap"
    ? wrapStyle(minTileWidth, gap)
    : scrollerStyle(density, gap, count, visibleColumns);
}

const tileBase: CSSProperties = {
  display: "flex",
  flexDirection: "column",
  justifyContent: "space-between",
  aspectRatio: TILE_ASPECT_RATIO,
  padding: spacing[3],
  borderRadius: radii.lg,
  /* THE CARD TILE IS TINTED (owner, 2026-09-13).
   *
   * It drew `surface-sunken` — the neutral step BELOW the page — and on the
   * walked storefront a grid of them read as a packed list with dividers
   * rather than as the reference's illustrated cards: at #f4f5f7 against a
   * #ffffff page the box is a hairline, so what a reader sees is the gaps
   * between the tiles and not the tiles themselves.
   *
   * `brand-subtle` is this vocabulary's own TINT role (brand.100 light /
   * brand.900 dark). A colour rather than a shade of grey is the whole
   * difference between "a row in a list" and "a card with a picture on it",
   * and it is a declared ROLE rather than a value chosen here — a deployment
   * that regenerates its palette moves this tile with it, which a hex would
   * not. The text role above it is unchanged and stays legible on both sides:
   * `text` is gray.900 on brand.100 and gray.100 on brand.900.
   *
   * The FLAT tile's hover fill stays `surface-sunken` deliberately — see
   * `categoryTileCss`. */
  background: cssVar("brand-subtle"),
  // A tile is a link, and a link that inherits the anchor colour reads as a
  // sentence rather than as a surface.
  color: cssVar("text"),
  scrollSnapAlign: "start",
  overflow: "hidden",
};

/**
 * The compact tile is a different ANATOMY, not just a smaller cozy tile: at
 * ~70px the reference label-top-left/art-bottom-right corners collide, and a
 * hyphenating root name clipped to its first syllable ("Nedvi-") reads as a
 * broken screen. The dense-grid convention every classified app uses at this
 * size is the icon centred on top with the label centred under it — the
 * label gets the tile's full width, which is what lets a long root name
 * hyphenate into two honest lines instead of clipping into one.
 */
const tileCompact: CSSProperties = {
  ...tileBase,
  aspectRatio: "1 / 1",
  // The INLINE padding is the caption's column, one step tighter than the
  // block padding: on a ~96px tile those 8px are a letter and a half of the
  // longest root name, and the art is centred so it loses nothing by them.
  paddingBlock: spacing[2],
  paddingInline: spacing[1],
  justifyContent: "center",
  alignItems: "center",
  gap: spacing[1],
};

/**
 * `size: "compact"`'s CARD tile — a HORIZONTAL row (name left, small picture
 * right), not the `density: "compact"` icon-over-label square above. `size`
 * takes precedence: the two never both apply to one tile.
 *
 * The owner's 2026-09-04 anatomy, unchanged and still the answer whenever
 * there is a fill to hold it — see {@link tileSizeCompactFlat} for what the
 * same row does without one.
 */
const tileSizeCompact: CSSProperties = {
  display: "flex",
  flexDirection: "row",
  alignItems: "center",
  justifyContent: "space-between",
  gap: spacing[2],
  // The box the art's own query is measured against — see
  // `COMPACT_SIZE_ART_TIGHT_PX`.
  containerType: "inline-size",
  containerName: COMPACT_SIZE_CONTAINER,
  aspectRatio: COMPACT_SIZE_ASPECT_RATIO,
  padding: spacing[2],
  borderRadius: radii.lg,
  // The same tint the regular card tile takes, and for the same reason: the
  // filled box is what makes two marks at opposite ends of a row read as one
  // thing, and a box nobody can see does not.
  background: cssVar("brand-subtle"),
  color: cssVar("text"),
  scrollSnapAlign: "start",
  overflow: "hidden",
};

/**
 * `size: "compact"` WITHOUT a fill — a LIST ROW (architect's verdict, which
 * supersedes the 2026-09-04 ruling for the flat surface only).
 *
 * `justify-content: space-between` puts the name against one end of the row
 * and the picture against the other, and that is a CARD's anatomy: the filled
 * box is what makes two marks at opposite ends read as one thing. Take the
 * fill away — the owner's ruling for every tile — and the same row is two
 * pieces of scattered text with a gap in the middle, which is what the stand
 * measured.
 *
 * So the flat compact tile is what a list row has always been: the art first,
 * the caption second, adjacent, both against the leading edge, with the
 * design system's own gap between them. It is the same fix the regular flat
 * tile got ({@link tileFlat}) applied to a row instead of a stack — proximity
 * replacing the box in the axis the anatomy actually runs along.
 *
 * Everything else is the 2026-09-04 ruling: the same half-tile height, the
 * same density, the same padding. Only the arrangement inside the row moves.
 */
const tileSizeCompactFlat: CSSProperties = {
  ...tileSizeCompact,
  justifyContent: "flex-start",
};

/* ── THE TILE'S SURFACE ────────────────────────────────────────────────────
 *
 * A tile is an icon and a name. The filled box behind it was never carrying
 * information: on the walked storefront the home grid read as a wall of dark
 * rectangles, each one competing with the picture inside it, and the fills
 * added up to more visual weight than the whole catalogue they stand for.
 *
 * `"flat"` takes the fill and the border away and leaves the tile's contents —
 * and gives the SURFACE back on hover and on `:focus-visible`, where a fill
 * means something: this is the one you are about to open. The radius is the
 * same one the filled tile always had, so the hovered shape is the tile the
 * grid was already laid out for, and nothing about the focus ring is touched:
 * a keyboard walk still shows the browser's own outline over the fill.
 *
 * `"card"` is the filled tile, unchanged, for a surface that was designed
 * around it.
 */

/** Whether a tile draws a surface of its own — see
 * {@link CategoryTileGridProps.tileSurface}. */
export type TileSurface = "flat" | "card";

/** The class every tile carries, whichever surface it draws. */
export const CATEGORY_TILE_CLASS = "stapel-category-tile";

/** The modifier a `"flat"` tile carries — the hover/focus rules hang on it. */
export const CATEGORY_TILE_FLAT_CLASS = "stapel-category-tile-flat";

/** The `href` the hoisted tile sheet is deduplicated by. */
export const CATEGORY_TILE_STYLE_HREF = "stapel-category-tile";

/**
 * The flat tile's rule set.
 *
 * `background-color`, never the `background` shorthand: the shorthand would
 * also reset an image a host put behind a tile of its own, and a rule that
 * quietly erases somebody else's declaration is not a surface choice.
 *
 * A sheet rather than inline styles because `:hover` and `:focus-visible`
 * cannot be said in a style attribute, and the colours are `--stapel-*`
 * custom properties so both themes resolve at paint time.
 *
 * `surface-sunken` — this design system's neutral tertiary fill — is the hover
 * colour, and it deliberately did NOT follow the card tile to `brand-subtle`
 * when that tile was tinted (2026-09-13). A hover is a POINTER's answer: "this
 * is the one you are about to open", drawn under the reader's own cursor and
 * gone the moment it leaves. A brand tint there would put the page's accent
 * colour on whichever tile a mouse happens to be resting over, which is a
 * stronger statement than the state deserves — and on a grid of twelve it
 * would read as a selection rather than as a hover. The card tile's fill is
 * about the TILE; this one is about the pointer.
 */
export function categoryTileCss(): string {
  const flat = `.${CATEGORY_TILE_FLAT_CLASS}`;
  const art = `.${CATEGORY_TILE_ART_CLASS}`;
  return [
    // A `<button>` brings a platform fill of its own; a link does not.
    `${flat}{background-color:transparent;border:none}`,
    `${flat}:hover,${flat}:focus-visible{` +
      `background-color:${cssVar("surface-sunken")}}`,
    // THE NARROW COMPACT ROW GIVES ITS PICTURE UP TO ITS NAME.
    //
    // A container query and not a media query: the tile states its own width
    // (`container-type: inline-size` in `tileSizeCompact`), so the same size
    // mounted in a wide sidebar and in a narrow phone scroller each get the
    // right answer without the host declaring which it is. A media query here
    // would read the WINDOW, which is the one measurement that says nothing
    // about how wide this particular tile ended up.
    //
    // It has to be a sheet rule rather than an inline style for the same
    // reason any query does: an inline `style` cannot carry a condition.
    `@container ${COMPACT_SIZE_CONTAINER} ` +
      `(max-width:${String(COMPACT_SIZE_ART_TIGHT_PX - 1)}px){` +
      `${art}{width:${String(COMPACT_SIZE_ART_GLYPH_PX)}px;` +
      `max-width:${String(COMPACT_SIZE_ART_GLYPH_PX)}px}}`,
  ].join("\n");
}

/**
 * THE FLAT TILE'S ANATOMY — centred, art over caption.
 *
 * Taking the fill away was right and it was only half the change. The card
 * anatomy puts the caption in the top-left corner and the art in the
 * bottom-right, and a filled box is what held those two marks together: with
 * no fill they are two unrelated things with a void between them, and six of
 * them across a desktop row read as a loose list rather than as a grid of
 * tiles (owner's walk of 0.27.0, both themes).
 *
 * The phone landing's dense grid already reads correctly with no fill, and it
 * is the same arrangement every catalogue app uses at that size: the icon
 * centred with the caption centred under it. Proximity is what groups them,
 * so the group survives the loss of the box.
 *
 * The RATIO stays 4/3 and the padding stays the card's. Only the arrangement
 * moves — a flat tile occupies exactly the box the card tile did, so every
 * reservation, every track height and every measured stage is unchanged.
 *
 * `size: "compact"` has the SAME problem and the same answer along its own
 * axis: it is a horizontal row half a tile high, and putting the name against
 * one end and the picture against the other is a card's arrangement too. Flat,
 * it becomes a list row — art first, caption second, adjacent — see
 * {@link tileSizeCompactFlat}. Its height and density are untouched.
 */
const tileFlat: CSSProperties = {
  ...tileBase,
  justifyContent: "center",
  alignItems: "center",
  gap: spacing[1],
};

/**
 * The flat tile's STACK — a regular-size tile with no fill: art over caption,
 * both centred. See {@link tileFlat}.
 */
function isFlatStack(size: TileSize, surface: TileSurface): boolean {
  return size !== "compact" && surface === "flat";
}

/**
 * The flat tile's ROW — a compact-size tile with no fill: art first, caption
 * second, adjacent and against the leading edge. See
 * {@link tileSizeCompactFlat}.
 *
 * Two predicates rather than one "is this flat", because the anatomy differs
 * by AXIS and each one names the arrangement it selects: a stack and a row are
 * not two spellings of the same rule, and a single flag would have to be read
 * together with `size` at every call site to mean anything.
 */
function isFlatRow(size: TileSize, surface: TileSurface): boolean {
  return size === "compact" && surface === "flat";
}

/** The classes one tile carries, for the surface it draws. */
function tileClassName(surface: TileSurface): string {
  return surface === "flat"
    ? `${CATEGORY_TILE_CLASS} ${CATEGORY_TILE_FLAT_CLASS}`
    : CATEGORY_TILE_CLASS;
}

function tileStyle(
  density: TileDensity,
  size: TileSize,
  surface: TileSurface = "card"
): CSSProperties {
  const base =
    size === "compact"
      ? surface === "flat"
        ? tileSizeCompactFlat
        : tileSizeCompact
      : density === "compact"
        ? tileCompact
        : surface === "flat"
          ? tileFlat
          : tileBase;
  if (surface === "card") return base;
  // The fill leaves the inline style entirely rather than being overwritten
  // with `transparent`: an inline declaration would beat the sheet's own
  // hover rule, which is where the fill now lives.
  const { background: _fill, ...flat } = base;
  return flat;
}

/**
 * THE SHAPE A TILE WILL BE, for anything that has to reserve room for one
 * before it exists.
 *
 * Read off {@link tileStyle} rather than restated, because a second copy of
 * "which anatomy is this" is a copy that drifts: the loading arm drew every
 * skeleton at {@link TILE_ASPECT_RATIO} (4/3) while a `density="compact"`
 * tile is a square and a `size="compact"` tile is 8/3 — so the row was one
 * height while it waited and a different height when it arrived. Measured on
 * the storefront's home: 0.024 of layout shift, paid on every cold load.
 */
function tileAspectRatio(density: TileDensity, size: TileSize): string {
  const shape = tileStyle(density, size).aspectRatio;
  return typeof shape === "string" ? shape : TILE_ASPECT_RATIO;
}

/**
 * Compact label: the same clamp one step down the TYPE SCALE — `xs`, the
 * smallest step the design system has, because a ~96px tile cannot spend
 * body-size lines and still show its art.
 *
 * Read from the scale rather than written as a number: the step below it does
 * not exist, which is exactly why {@link COMPACT_MIN_COLUMN_PX} and not a
 * smaller type is what makes the longest root name fit.
 */
const COMPACT_LABEL_FONT_SIZE = fontSize.xs.fontSize;

const labelStyle: CSSProperties = {
  fontWeight: fontWeight.semibold,
  // The clamp, then an ellipsis: a category name that pushes the art out of
  // the tile is worse than a truncated one.
  display: "-webkit-box",
  WebkitBoxOrient: "vertical",
  WebkitLineClamp: LABEL_LINES,
  overflow: "hidden",
  // A touch tighter than the skin's body line: three clamped lines are a
  // label, not a paragraph, and the saved height is what keeps the art corner
  // inside the tile at the measured 129×97 phone geometry.
  lineHeight: 1.3,
  // NOT `hyphens: auto`. The argument for it was that a word wider than the
  // tile should break like a book word rather than clip — and on a 70px
  // phone tile the browser took that permission everywhere: the deployed
  // home screen hyphenated its four longest root captions mid-word, set a
  // nine-letter one in three lines and a four-word one in six (walker D90,
  // four passes). A hyphen inside a NAVIGATION LABEL is not
  // typesetting, it is a word the reader has to reassemble before they can
  // decide whether to tap it, and the clamp below already answers the case
  // hyphenation was defending against.
  //
  // `manual` still honours a soft hyphen a catalogue author writes into the
  // name on purpose; it just stops the browser inventing its own.
  hyphens: "manual",
  // A CAPTION BREAKS BETWEEN WORDS, NEVER INSIDE ONE.
  //
  // `anywhere` was the defence against a column too narrow for the longest
  // root name, and it paid for it on the phone landing: the catalogue's two
  // longest root names were set over two lines with the break INSIDE the word
  // and nothing marking it, which a reader has to reassemble before deciding
  // whether to tap it. The column is what was wrong, and the column is fixed:
  // {@link COMPACT_MIN_COLUMN_PX} is derived from the longest name the tile
  // has to carry, so `normal` now has room to be right.
  //
  // The clamp plus `text-overflow` is the floor under the case no column can
  // answer (a 20-letter name, a host's narrower tile): the caption ends in an
  // ellipsis on its last line rather than splitting a word.
  overflowWrap: "normal",
  textOverflow: "ellipsis",
};

const labelCompact: CSSProperties = {
  ...labelStyle,
  fontSize: COMPACT_LABEL_FONT_SIZE,
  lineHeight: 1.2,
  textAlign: "center",
  // Two centred lines under the icon; the third line belongs to the cozy
  // anatomy, where the label owns the top of the tile.
  WebkitLineClamp: 2,
};

/** Compact art: centred over the label, never a corner ornament. A fixed
 * width plus {@link ART_ASPECT_RATIO} — see that constant — instead of a
 * shrink-to-fit cap, so the box has its final size before anything is drawn
 * inside it. */
/** The flat tile's caption: the card's own type, centred under the art —
 * NOT `labelCompact`'s 12px, which belongs to an ~80px phone tile. The clamp
 * is the regular one, and `labelLines` still overrides it. */
const labelFlat: CSSProperties = {
  ...labelStyle,
  textAlign: "center",
};

const artCompact: CSSProperties = {
  display: "flex",
  alignItems: "center",
  justifyContent: "center",
  width: "50%",
  aspectRatio: ART_ASPECT_RATIO,
};

const artStyle: CSSProperties = {
  display: "flex",
  alignItems: "flex-end",
  justifyContent: "flex-end",
  alignSelf: "flex-end",
  width: "60%",
  aspectRatio: ART_ASPECT_RATIO,
};

/** `size: "compact"`'s label: smaller type, one clamped line fewer than the
 * regular tile — a horizontal row has no third line to spend. */
const labelSizeCompact: CSSProperties = {
  ...labelStyle,
  fontSize: COMPACT_SIZE_LABEL_FONT_SIZE,
  lineHeight: 1.25,
  textAlign: "start",
  WebkitLineClamp: 2,
  // THE CAPTION TAKES THE ROW, the art takes what is left — not the other way
  // round. Without this the label is `flex: 0 1 auto` with `min-width: auto`,
  // so the art's fixed 32% is subtracted first and the name lives in the
  // remainder; on a narrow scroller that remainder is too small for a long
  // single word and the clamp ends it in an ellipsis mid-word. `min-width: 0`
  // is what lets a flex item be narrower than its longest word at all.
  flex: "1 1 auto",
  minWidth: 0,
};

/** `size: "compact"`'s small picture — a fixed fraction of the row, capped so
 * a wide row does not inflate it into a second tile. */
const artSizeCompact: CSSProperties = {
  display: "flex",
  alignItems: "center",
  justifyContent: "center",
  flex: "0 0 auto",
  width: COMPACT_SIZE_ART_WIDTH,
  maxWidth: COMPACT_SIZE_ART_MAX_PX,
  aspectRatio: ART_ASPECT_RATIO,
};

/**
 * What a tile draws in its art corner when there is no art.
 *
 * ── Why a monogram and not a disc ──────────────────────────────────────────
 *
 * The first version of this drew a muted circle, on the reasoning that a tile
 * with an empty corner reads as a tile that failed to load. It does — and so
 * does the circle. A live catalogue put nine of them on one landing (every
 * category on that deployment carries `carousel_icon: ""`, which is the state
 * every catalogue is in until somebody uploads art), and a grid of identical
 * grey discs reads as nine images still loading, not as a design.
 *
 * A letter cannot be mistaken for a pending image. It is also not a guess: the
 * category's own initial is information the tile already has and already
 * shows, set large and faint so it sits behind the label as texture rather
 * than competing with it as a second reading. Every tile then differs from
 * every other tile, which is the property the discs lacked.
 *
 * Still never an `<img>` with an invented `src` — the reason the art seam is a
 * host callback in the first place (see this file's header).
 *
 * `aria-hidden`, because it is the label's first letter: a screen reader that
 * announced it would read the category's name and then its initial.
 */
function TileMonogram(props: { readonly label: string }): ReactElement {
  return (
    <span
      aria-hidden="true"
      data-stapel-tile-art="monogram"
      style={{
        // `Intl.Segmenter` would be the pedantic way to take one grapheme, and
        // it is not worth a polyfill here: the fallback is decorative, and a
        // label whose first code point is half a surrogate pair renders the
        // replacement glyph in a corner nobody reads letters from.
        fontSize: "2.25em",
        lineHeight: 1,
        fontWeight: fontWeight.bold,
        color: cssVar("text"),
        // Faint enough to stay behind the label at any tile size, dark enough
        // to survive the sunken surface in both themes.
        opacity: 0.14,
        userSelect: "none",
      }}
    >
      {firstLetter(props.label)}
    </span>
  );
}

/**
 * The seeded catalogue's art: `catalog_icon` when it already holds an address.
 *
 * Three arms, in this order, and the order is the contract: the host's
 * `renderIcon` first (a storefront that hardcodes its own root glyphs keeps
 * them), then an address — the host's `resolveIconSrc`, else the row's own
 * field — and then the monogram. So the picture appears on a deployment whose
 * catalogue has been seeded and nowhere else, and no arm was taken away from
 * anybody: each one may DECLINE and hand the row to the next.
 *
 * 3:2 and `contain`: the generated art is 3:2 on a soft ground, and `contain`
 * is what keeps a differently-proportioned upload whole instead of cropping
 * its subject. The alt text is the category's own name — the tile's label is
 * beside it, so the two agree by construction.
 *
 * `eager` decides `loading` and `fetchPriority` — see
 * {@link CategoryTileGridProps.eagerCount}. Lazy is still the default for
 * every row past that count, because a mega-menu or a long landing draws
 * dozens of these below the fold.
 */
function TileImage(props: {
  readonly src: string;
  readonly label: string;
  readonly eager: boolean;
}): ReactElement {
  return (
    <img
      src={props.src}
      alt={props.label}
      loading={props.eager ? "eager" : "lazy"}
      {...(props.eager ? { fetchPriority: "high" as const } : {})}
      decoding="async"
      data-stapel-tile-art="image"
      style={{
        width: "100%",
        aspectRatio: ART_ASPECT_RATIO,
        objectFit: "contain",
      }}
    />
  );
}

/**
 * Turn a category's opaque icon reference into an ADDRESS — the seam for a
 * host whose CDN needs a lookup rather than a prefix.
 *
 * `renderIcon` already lets a host draw whatever it likes, but it costs the
 * host the tile's own `<img>` (its lazy loading, its aspect ratio, its alt
 * text) for the one thing it usually wants: the URL. A resolver hands back a
 * string and keeps the library's picture.
 *
 * It takes the CATEGORY, not the reference, because a store of opaque refs
 * (`product/<sha256>`) is keyed by the row, and the alternative — projecting
 * every row into a new `entries` array just to rewrite one field — is a copy
 * of the catalogue per render.
 *
 * `undefined` is DECLINING this row, not an error: the next arm answers.
 * Whatever comes back still goes through {@link categoryIconSrc}, so a
 * resolver that returns an opaque string or a `data:` URI draws the monogram
 * rather than a broken image.
 */
export type CategoryIconResolver = (category: Category) => string | undefined;

/**
 * Is this tile a VALUE of an expanded branch rather than a row?
 *
 * The two differ in exactly three places — the React key, whether the link
 * carries a category identity, and whether there is art to resolve — and
 * nowhere else, which is why they share one {@link Tile} rather than getting
 * a second component.
 */
function isVirtualTile(entry: CategoryTileEntry): entry is VirtualTileEntry {
  return "virtual" in entry;
}

/**
 * The art of one tile: the host's `renderIcon`, then an address, then the
 * monogram — and EVERY arm may decline.
 *
 * Declining is the whole correction here. `renderIcon` used to be returned
 * unconditionally whenever the row carried a reference, so a host that draws
 * its own glyph for five roots and `null` for the rest turned the other two
 * arms off for the entire catalogue: the seeded `catalog_icon` never drew, and
 * neither did the monogram — every unglyphed tile had an empty art corner,
 * which reads as a tile that failed to load. `null` (and `undefined`) from a
 * host renderer means "not this row", and the next arm answers.
 */
function tileArt(
  reference: string | null,
  label: string,
  entry: CarouselEntry,
  eager: boolean,
  renderIcon?: (reference: string, entry: CarouselEntry) => ReactNode,
  resolveIconSrc?: CategoryIconResolver
): ReactNode {
  if (reference !== null && renderIcon !== undefined) {
    const drawn = renderIcon(reference, entry);
    if (drawn !== null && drawn !== undefined) return drawn;
  }
  // The resolver first, then the row's own field: a host that can address the
  // opaque reference knows more about its CDN than the row does, and a
  // resolver that declines leaves the seeded URL exactly where it was.
  const src = categoryIconSrc(resolveIconSrc?.(entry.category) ?? reference);
  if (src !== null) return <TileImage src={src} label={label} eager={eager} />;
  return <TileMonogram label={label} />;
}

/** The one character a monogram shows: the label's first letter, uppercased
 * in the label's OWN locale rules — `toLocaleUpperCase` and not
 * `toUpperCase`, so a Turkish `i` becomes `İ` rather than `I`. */
function firstLetter(label: string): string {
  const [first] = [...label.trim()];
  return first === undefined ? "" : first.toLocaleUpperCase();
}

/**
 * WHETHER THE BROWSER MAY HYPHENATE A CAPTION IT CANNOT FIT.
 *
 * `"manual"` is the default and the skin's own long-standing answer (D90): a
 * caption breaks between words and no character appears that the catalogue
 * author did not write. A name too wide even for the column
 * {@link COMPACT_MIN_COLUMN_PX} guarantees ends in an ellipsis rather than
 * being split.
 *
 * `"auto"` is the OTHER reading of the same break, and a deployment whose
 * catalogue disagrees with D90 needs it: a walk of a 390px phone measured
 * "Nedvizhimost" and "Elektronika" set over two lines with the break INSIDE
 * the word and nothing marking it — "Nedvizhim / ost" — which a reader has to
 * notice is one word before they can decide whether to tap it. The arithmetic
 * is not a rendering accident and no line count can escape it: at the
 * compact tile's measured 63px caption column, a 12-letter root name is
 * ~83px wide, so SOME break is forced and the only question is whether it is
 * marked.
 *
 * A PROP and not a flip, because the two readings are both measured and they
 * disagree: D90 walked a catalogue whose long captions read worse hyphenated,
 * this one walks a catalogue whose long captions read worse unhyphenated, and
 * neither is the other's bug. The default is unchanged, so no existing host
 * moves; the deployment that measured the second reading asks for it by name.
 *
 * `hyphens: auto` needs a LANGUAGE to hyphenate by — without one the browser
 * has no pattern set and the declaration is inert. So the caption is stamped
 * with the i18n engine's own locale when this is `"auto"`, rather than the
 * pair trusting a host to have put `lang` on its `<html>`.
 */
export type TileLabelHyphens = "manual" | "auto";

/**
 * The label style of ONE tile — the anatomy's own, with the host's
 * {@link CategoryTileGridProps.labelLines} standing in for its clamp when one
 * is given.
 *
 * Read off the same three constants the anatomies are written in rather than
 * restated, so the ONLY thing a host can move is the line count: a catalogue
 * whose longest root name needs a third line on the compact tile keeps that
 * tile's size, weight, alignment and break rules, which are the skin's and
 * not the deployment's.
 */
function labelStyleFor(
  density: TileDensity,
  size: TileSize,
  surface: TileSurface,
  labelLines: number | undefined,
  hyphens: TileLabelHyphens
): CSSProperties {
  const base =
    size === "compact"
      ? labelSizeCompact
      : density === "compact"
        ? labelCompact
        : isFlatStack(size, surface)
          ? labelFlat
          : labelStyle;
  const clamped =
    labelLines === undefined ? base : { ...base, WebkitLineClamp: labelLines };
  return hyphens === "manual" ? clamped : { ...clamped, hyphens };
}

/**
 * THE TILE CAPTION'S NAME — the one element a reading of the label may aim
 * at, in every anatomy.
 *
 * A tile's caption used to be an unnamed `<span>` inside the tile link, and
 * WHICH span it is depends on the anatomy: the label comes FIRST on the
 * regular and `size="compact"` tiles and SECOND on `density="compact"`, whose
 * art leads. So anything reaching for it by position — a stylesheet's
 * `span:first-child`, a probe's `querySelector` — aims at the label on one
 * surface and at the art on the next, and reports a number either way. That
 * is not hypothetical twice over: it is the `!important` clamp override
 * {@link CategoryTileGridProps.labelLines} replaced, and then a stand probe
 * that read `-webkit-line-clamp` off the tile LINK (where it is `none`, on a
 * page where the clamp is working perfectly) and counted the art box and the
 * monogram as two of the caption's "lines".
 *
 * Every ordinary tile's caption carries this. The two special tiles keep
 * their own, older names on the same span — `categories-tile-grid-all` on the
 * "All" tile — because a test that reads the clamp off THAT tile already
 * points at the right element and must keep pointing at it.
 */
export const CATEGORY_TILE_LABEL_TESTID = "categories-tile-label";

/**
 * The label + art pairing for ONE tile, in whichever of the three anatomies
 * applies — shared between {@link Tile} and {@link MoreTile}, which differ
 * only in what wraps this (a link vs a button).
 *
 * `size: "compact"` takes precedence over `density`: the two never both
 * apply to one tile — see {@link tileStyle}.
 */
function tileBody(props: {
  readonly label: string;
  readonly art: ReactNode;
  readonly size: TileSize;
  readonly density: TileDensity;
  readonly surface: TileSurface;
  readonly labelLines: number | undefined;
  readonly labelHyphens: TileLabelHyphens;
  /** The i18n engine's locale, for `hyphens: auto` to hyphenate BY — see
   * {@link TileLabelHyphens}. Absent under `"manual"`, where the declaration
   * is not made and a `lang` would say nothing the host has not already
   * said. */
  readonly labelLang: string | undefined;
  readonly testId?: string;
}): ReactElement {
  const label = (
    <span
      style={labelStyleFor(
        props.density,
        props.size,
        props.surface,
        props.labelLines,
        props.labelHyphens
      )}
      {...(props.labelHyphens === "auto" && props.labelLang !== undefined
        ? { lang: props.labelLang }
        : {})}
      data-testid={props.testId ?? CATEGORY_TILE_LABEL_TESTID}
    >
      {props.label}
    </span>
  );
  // The CARD's compact row: name against one end, picture against the other.
  // The flat one falls through to the art-first arrangement below — see
  // `tileSizeCompactFlat` for why the corners stop working without a fill.
  if (props.size === "compact" && !isFlatRow(props.size, props.surface)) {
    return (
      <>
        {label}
        <span className={CATEGORY_TILE_ART_CLASS} style={artSizeCompact}>
          {props.art}
        </span>
      </>
    );
  }
  // A LIST ROW: the art leads, the caption follows, adjacent. Same picture box
  // as the card row — only the order and the alignment change.
  if (isFlatRow(props.size, props.surface)) {
    return (
      <>
        <span className={CATEGORY_TILE_ART_CLASS} style={artSizeCompact}>
          {props.art}
        </span>
        {label}
      </>
    );
  }
  // Art over caption, both centred — the dense phone grid's arrangement, and
  // the FLAT tile's too: with no fill to hold them, proximity is what makes
  // the icon and the name one thing. See `tileFlat`.
  if (props.density === "compact" || isFlatStack(props.size, props.surface)) {
    return (
      <>
        <span style={artCompact}>{props.art}</span>
        {label}
      </>
    );
  }
  return (
    <>
      {label}
      <span style={artStyle}>{props.art}</span>
    </>
  );
}

function Tile(props: {
  readonly href: string;
  readonly label: string;
  readonly art: ReactNode;
  readonly slug?: string;
  readonly categoryId?: number;
  readonly linkComponent?: LinkComponent;
  readonly testId?: string;
  readonly density: TileDensity;
  readonly size: TileSize;
  readonly surface: TileSurface;
  readonly labelLines: number | undefined;
  readonly labelHyphens: TileLabelHyphens;
  readonly labelLang: string | undefined;
}): ReactElement {
  return (
    <CategoryLink
      {...(props.linkComponent !== undefined
        ? { linkComponent: props.linkComponent }
        : {})}
      {...(props.slug !== undefined ? { slug: props.slug } : {})}
      {...(props.categoryId !== undefined
        ? { categoryId: props.categoryId }
        : {})}
      href={props.href}
      className={tileClassName(props.surface)}
      style={tileStyle(props.density, props.size, props.surface)}
    >
      {tileBody(props)}
    </CategoryLink>
  );
}

/**
 * The overflow tile/button ("All categories") — drawn in place of the rows
 * past {@link CategoryTileGridProps.maxVisible} when
 * {@link CategoryTileGridProps.overflow} is `"modal"`. Same anatomy as an
 * ordinary tile (art corner, label) so it sits in the grid without a visual
 * seam; a `<button>`, not a link, because it opens the dialog rather than
 * navigating.
 */
function MoreTile(props: {
  readonly label: string;
  readonly extraCount: number;
  readonly density: TileDensity;
  readonly size: TileSize;
  readonly surface: TileSurface;
  readonly labelLines: number | undefined;
  readonly labelHyphens: TileLabelHyphens;
  readonly labelLang: string | undefined;
  readonly testId: string;
  readonly onClick: () => void;
  /** `stapel/clickable-needs-event` opt-out, checked on THIS element — see
   * the call site in `TileRow`, which carries the same two attributes. */
  readonly "data-analytics"?: "none";
  readonly "data-analytics-reason"?: string;
}): ReactElement {
  return (
    <button
      type="button"
      className={tileClassName(props.surface)}
      style={{
        ...tileStyle(props.density, props.size, props.surface),
        border: "none",
        cursor: "pointer",
        font: "inherit",
        textAlign: "start",
      }}
      data-testid={props.testId}
      data-analytics="none"
      data-analytics-reason="opens the local overflow dialog; nothing leaves the browser"
      onClick={props.onClick}
    >
      {tileBody({
        label: props.label,
        art: <MoreGlyph count={props.extraCount} />,
        size: props.size,
        density: props.density,
        surface: props.surface,
        labelLines: props.labelLines,
        labelHyphens: props.labelHyphens,
        labelLang: props.labelLang,
      })}
    </button>
  );
}

/**
 * THE "ALL" TILE'S OWN ART — a pictogram, never the monogram.
 *
 * The "All" tile stands FIRST in the grid, beside ten siblings that every
 * seeded catalogue draws with a picture. Handed {@link TileMonogram} it drew
 * its label's initial instead — a lone faint capital where ten pictures are,
 * which a walk of the phone home screen read as an image that failed to load
 * (measured: `categories-tile-grid-all` carried zero `<img>`/`<svg>` while
 * the grid carried ten).
 *
 * The monogram's own argument is why it cannot be the answer here. It is a
 * fallback for a row whose art the CATALOGUE has not supplied, and its value
 * is that "every tile then differs from every other tile". This tile is not a
 * catalogue row: it is the grid's own control, it has no `catalog_icon` to
 * wait for, and its meaning — "all of them" — is the one meaning a pictogram
 * can carry exactly. So it gets a drawn glyph and not a letter.
 *
 * Inline, and not an icon dependency: this package ships no icon set and one
 * four-square glyph is not the reason to take one. `aria-hidden`, like every
 * other tile's art — the accessible name is the tile's own label.
 */
function AllCategoriesGlyph(): ReactElement {
  return (
    <svg
      aria-hidden="true"
      focusable="false"
      data-stapel-tile-art="all"
      viewBox="0 0 24 24"
      style={{
        width: "100%",
        height: "100%",
        // `contain` is what the picture arm uses, and the two sit side by
        // side in one grid: a glyph that filled its box while its neighbours
        // fitted theirs would be the odd tile in the row.
        objectFit: "contain",
        fill: "currentColor",
        color: cssVar("text-muted"),
      }}
    >
      {/* Four rounded cells — the catalogue-grid idiom, and the same shape
          the tiles it opens are laid out in. */}
      <rect x="3" y="3" width="8" height="8" rx="2" />
      <rect x="13" y="3" width="8" height="8" rx="2" />
      <rect x="3" y="13" width="8" height="8" rx="2" />
      <rect x="13" y="13" width="8" height="8" rx="2" />
    </svg>
  );
}

/** The overflow tile's own art: `+N`, faint like {@link TileMonogram} — the
 * accessible name comes from the button's own label, this is decorative. */
function MoreGlyph(props: { readonly count: number }): ReactElement {
  return (
    <span
      aria-hidden="true"
      style={{
        fontSize: "1.5em",
        lineHeight: 1,
        fontWeight: fontWeight.bold,
        color: cssVar("text"),
        opacity: 0.5,
      }}
    >
      +{props.count}
    </span>
  );
}

export interface CategoryTileGridProps extends ThemeModeProp, LinkComponentProp {
  /** Path prefix for a tile's link, and the "All" tile's own href. Default
   * `/c` — the same convention `<CategoryCarousel>` and the spec's `/c/:slug`
   * already use. */
  readonly basePath?: string;
  /**
   * Turn an opaque icon reference into something renderable — the same
   * contract `<CategoryCarouselStrip>` takes.
   *
   * Returning `null` DECLINES the row and the remaining arms answer it: the
   * row's own address if it carries one, otherwise {@link TileMonogram}. So a
   * host that only has glyphs for its five roots hands back `null` for
   * everything else and the rest of the catalogue keeps its art.
   */
  readonly renderIcon?: (reference: string, entry: CarouselEntry) => ReactNode;
  /**
   * Address a row's opaque icon reference without projecting the rows — see
   * {@link CategoryIconResolver}. Consulted after `renderIcon` and before the
   * row's own `catalog_icon`; `undefined` declines.
   */
  readonly resolveIconSrc?: CategoryIconResolver;
  /**
   * Lead with a tile linking `basePath` itself (default `true`). Off for a row
   * that is already inside a category, where "All" would point at the
   * catalogue root the visitor just came from.
   */
  readonly allTile?: boolean;
  /**
   * Tiles the HOST supplies, instead of the carousel bag.
   *
   * The bag answers ONE question — "which categories has the operator put on
   * the storefront's front page" (`carousel_enabled`, `GET /categories
   * /carousel/`) — and that is the only question a landing page asks. A
   * CATEGORY page asks a different one: "what is inside this category", whose
   * answer is `useCategoryTree()`'s children, already in the host's hand and
   * not on the carousel endpoint at all. Without this prop the second surface
   * either re-implements the tile geometry or renders the wrong rows, and the
   * tiles on `/c/transport` would be the same five the home page shows.
   *
   * Given, the component asks the server NOTHING: `<CategoryCarousel>` is not
   * mounted, so an override costs no `GET /categories/carousel/` (the request
   * a "swap the bag's data" implementation would still fire and discard). An
   * empty array is a real answer — a category with no children — and draws the
   * same empty state a featureless carousel draws.
   *
   * There is no loading or failed arm for an override, and that is deliberate:
   * the host owns the fetch it drew these rows from, so it owns the two
   * sentences that go with it. Handing this component a `LoadState` would give
   * one load two owners — {@link CategoryTileGridProps.reserve} is how the
   * host lends this one back the ONE thing it cannot own, which is the row's
   * height before the rows exist.
   *
   * Since stapel-categories 0.22.0 an entry is not always a row: a POINTER
   * arrives as an ordinary {@link CarouselEntry} (its every key is the
   * target's, so it draws and navigates like any other tile), and a VALUE of
   * an expanded branch arrives as a {@link VirtualTileEntry} — no id, no
   * slug, and the `href` its own host built out of the `filter` pair. Build
   * both with `categoryChildTileEntries`.
   */
  readonly entries?: readonly CategoryTileEntry[];
  /**
   * HOLD THE ROW'S BOX WHILE THE HOST'S OWN FETCH IS IN FLIGHT.
   *
   * The `entries` override skips this component's loading arm on purpose (the
   * host owns that read), and the consequence was a hole in the layout: a
   * category page that has not resolved its children yet renders no tile row
   * at all, and the row then APPEARS a beat later and pushes everything under
   * it down the page. The pair already draws exactly the right box — the same
   * grid, the same aspect ratio, the same skeletons — in its own loading arm;
   * without this prop the only way to get it was for the host to re-implement
   * it, and the measured storefront instead reserved a hand-guessed height in
   * its own stylesheet.
   *
   *  - `false` (default) — unchanged: no rows, no box.
   *  - `true` — reserve while `entries` is `undefined`, i.e. for exactly as
   *    long as the host has handed nothing over. An empty array is a real
   *    answer ("this category has no children") and ends the reservation.
   *  - `"pending"` — the host STATES that its read is in flight, and the box
   *    is held whatever `entries` currently says. For a host that keeps the
   *    previous rows in hand across a refetch and would rather hold the box
   *    than show a stale row.
   *
   * The reservation never asks the server anything: like the override arm,
   * `<CategoryCarousel>` stays unmounted, so a host-driven row costs no
   * `GET /categories/carousel/` in either state. Past the depth cap it is
   * nothing at all — there are no tiles to reserve room for.
   */
  readonly reserve?: boolean | "pending";
  /**
   * HOW MANY TILES the reservation holds room for. Default 4 — the number
   * this arm has always drawn.
   *
   * The reserved box is not a height: it is one skeleton per tile in the grid
   * the tiles themselves land in, so the browser lays out
   * `tileStageRows(count, columns)` rows for the reservation exactly as it
   * will for the answer. A caller that already knows the count — a host whose
   * own read returns the children, a page that has the tree in hand — states
   * it here, and the band under the last row goes away in both directions: no
   * hole where the answer is shorter, no shift where it is taller.
   *
   * See {@link tileStageRows} for the rule itself, which is exported so a
   * host holding the stage's box from OUTSIDE this pair computes it from the
   * same arithmetic instead of guessing a pixel height.
   */
  readonly reserveCount?: number;
  /**
   * The 0-indexed depth of the category whose children these tiles are — a
   * top-level category is `0`, its child is `1`. Omitted means the catalogue
   * ROOT (the home screen), which is above every category and always offers
   * tiles.
   *
   * Past {@link MAX_TILE_DEPTH} this component renders nothing: the deeper
   * levels of the tree are characteristics chosen through cascading selectors,
   * not tiles (see this file's header). The rows are NOT lost — the host still
   * has them, and a list, a breadcrumb or a selector may render them.
   */
  readonly categoryDepth?: number;
  /**
   * Tile geometry (default `"cozy"`, the reference two-row scroller).
   * `"compact"` is the dense strip: 4+ visible columns and an absolute cap on
   * the column width, so the same mount is small on a phone and a modest
   * strip — never a wall — inside a wide desktop column.
   */
  readonly density?: TileDensity;
  /**
   * How the tiles fill the container — see {@link TileLayout}. Default
   * `"scroll"`, the reference two-row scroller, so no existing host changes
   * shape.
   */
  readonly layout?: TileLayout;
  /**
   * The narrowest a tile may be in `layout="wrap"` before the grid drops a
   * column. Default 240px. Ignored by `"scroll"`, whose column width comes
   * from {@link TileDensity} and the container.
   */
  readonly minTileWidth?: number;
  /**
   * HOW MANY COLUMNS OF THE SCROLLER ARE IN VIEW — the fraction, so the half
   * column that peeks is what says "there is more to the right".
   *
   * Default 2.5, the reference phone row, and `layout="wrap"` ignores it (its
   * columns come from {@link CategoryTileGridProps.minTileWidth}). It is also
   * ignored by `density="compact"`, whose column is a floor/fraction/cap of
   * its own.
   *
   * A PROP because the right number depends on the longest NAME in the
   * catalogue, which is a fact about the deployment and not about the pair. A
   * storefront running `size="compact"` at the default 2.5 on a 390px phone
   * left ~90px of caption, and its two longest single-word roots ended in an
   * ellipsis inside the word; at 2 they print whole. A catalogue of short
   * names has no reason to give up the column.
   */
  readonly visibleColumns?: number;
  /**
   * How many of the leading tiles (by `entries` order, the "All" tile not
   * counted — it never carries an image) load their picture EAGERLY, with
   * `fetchPriority="high"`, instead of `loading="lazy"`. Default 8.
   *
   * A grid whose whole first row sits above the fold and still marks every
   * image `lazy` gives the browser no reason to fetch them before first
   * paint, so the row's real height (and whatever sits below it) arrives a
   * beat late — a walker measured a home page shoving its feed 224px down
   * this way. Past `eagerCount` a tile stays `lazy`: a mega-menu or a long
   * `layout="wrap"` landing still must not fetch dozens of images nobody has
   * scrolled to.
   */
  readonly eagerCount?: number;
  /**
   * The tile's own anatomy — see {@link TileSize}. Default `"regular"`, the
   * reference root tile, so no existing host changes shape. A landing below
   * the home page is where `"compact"` belongs.
   */
  readonly size?: TileSize;
  /**
   * Whether a tile draws a SURFACE of its own. Default `"flat"`.
   *
   *  - `"flat"` — no fill and no border at rest: the icon and the caption are
   *    the tile. The surface arrives on hover and on `:focus-visible`, in the
   *    same radius and the same token fill the card tile wears, so pointing at
   *    a tile is what colours it in. The focus ring is untouched;
   *  - `"card"` — the filled tile this grid has always drawn.
   *
   * The default is the NEW behaviour, deliberately: `surface-sunken` behind
   * every tile was inherited from the first carousel strip, and a grid of a
   * dozen of them is a wall of boxes with the catalogue inside — the fills
   * carry no information and outweigh the art they contain. A surface that
   * was designed around the filled tile says `tileSurface="card"` and keeps
   * it exactly.
   */
  readonly tileSurface?: TileSurface;
  /**
   * HOW MANY LINES A TILE'S LABEL MAY TAKE before it is clipped — the one
   * number of the label a deployment owns.
   *
   * Each anatomy has its own default and they are the skin's measured
   * answers: {@link LABEL_LINES} (3) on the regular tile, 2 on both compact
   * ones, where a ~80px square and a half-height horizontal row have no third
   * line to spend. Those defaults are right for the catalogue they were
   * measured on and wrong for a catalogue whose longest root NAME is longer:
   * the clamp is the only part of the label that depends on the words rather
   * than on the tile.
   *
   * Without this prop a host could only reach the clamp with an `!important`
   * rule against the pair's inline style — a rule that cannot be read back,
   * that silently aims at the wrong `<span>` when the anatomy reorders label
   * and art (the compact density draws its art FIRST), and that a version
   * bump moving the default cannot tell it has become a no-op. This prop is
   * that number, and nothing else about the label moves with it.
   *
   * Default: the anatomy's own, so no existing host changes shape.
   */
  readonly labelLines?: number;
  /**
   * WHETHER A CAPTION TOO WIDE FOR ITS COLUMN MAY BE HYPHENATED. Default
   * `"manual"` — the skin's own answer, unchanged for every host that does
   * not ask. See {@link TileLabelHyphens} for both readings and why this is a
   * deployment's choice rather than the skin's.
   */
  readonly labelHyphens?: TileLabelHyphens;
  /**
   * Cap the grid at this many rows before offering the rest through
   * {@link CategoryTileGridProps.overflow}. Ignored unless `overflow` is
   * `"modal"` — see there. The "All" tile is not counted against the cap.
   */
  readonly maxVisible?: number;
  /**
   * What happens past {@link CategoryTileGridProps.maxVisible}. Default
   * `"none"` — no cap is enforced and every row draws, so `maxVisible` alone
   * changes nothing.
   *
   * `"modal"` draws exactly `maxVisible` rows plus one "All categories" tile
   * that opens a dialog (`SkinDialog`) listing EVERY child — compact rows
   * with pictures, a search box once there are more than
   * {@link ALL_CATEGORIES_SEARCH_THRESHOLD}. The reference's own second-level
   * page (owner's verdict, 2026-09-04): a compact grid capped at 10, plus the
   * button.
   */
  readonly overflow?: TileOverflow;
}

/** {@link CategoryTileGridProps.eagerCount}'s default — the reference
 * desktop grid's first row. */
const DEFAULT_EAGER_COUNT = 8;

/** {@link CategoryTileGridProps.overflow}'s two answers. */
export type TileOverflow = "none" | "modal";

/** Past this many children, the overflow dialog grows a search box — a list
 * short enough to scan needs no filter, and a search box over three rows is
 * chrome nobody asked for. */
const ALL_CATEGORIES_SEARCH_THRESHOLD = 20;

/**
 * "All categories" — every child of this rung, searchable once there are
 * enough of them, in a `SkinDialog` (a bottom sheet on a phone, a centred
 * modal on tablet/desktop — the primitive's own responsive rule, so this
 * component makes no surface choice of its own). Compact rows, each a real
 * link: a keyboard tabs through them and Enter/click navigates like any other
 * tile, and Esc / the mask / the dialog's own dismiss control close it — all
 * `SkinDialog`'s doing.
 */
function AllCategoriesDialog(props: {
  readonly open: boolean;
  readonly onClose: () => void;
  readonly entries: readonly CategoryTileEntry[];
  readonly linkComponent?: LinkComponent;
  readonly renderIcon?: (reference: string, entry: CarouselEntry) => ReactNode;
  readonly resolveIconSrc?: CategoryIconResolver;
}): ReactElement {
  const t = useT();
  const [query, setQuery] = useState("");
  const linkProps =
    props.linkComponent !== undefined
      ? { linkComponent: props.linkComponent }
      : {};
  const rows = useMemo(
    () =>
      props.entries.map((entry) => ({
        entry,
        label: renderCategoryLabel(entry.label, t),
      })),
    [props.entries, t]
  );
  const searchable = props.entries.length > ALL_CATEGORIES_SEARCH_THRESHOLD;
  const filtered =
    query === ""
      ? rows
      : rows.filter(({ label }) =>
          label.toLocaleLowerCase().includes(query.toLocaleLowerCase())
        );

  return (
    <SkinDialog
      open={props.open}
      onClose={props.onClose}
      title={t(CATEGORIES_I18N_KEYS.tilesShowAll)}
      dismissLabel={t(STAPEL_UI_KEYS.dismiss)}
      data-testid="categories-tile-grid-dialog"
    >
      <Flex vertical gap={spacing[2]}>
        {searchable ? (
          <Input
            allowClear
            value={query}
            placeholder={t(CATEGORIES_I18N_KEYS.tilesAllSearch)}
            aria-label={t(CATEGORIES_I18N_KEYS.tilesAllSearch)}
            data-testid="categories-tile-grid-dialog-search"
            onChange={(event) => {
              setQuery(event.target.value);
            }}
          />
        ) : null}
        {filtered.length === 0 ? (
          <EmptyState
            testId="categories-tile-grid-dialog-empty"
            compact
            title={t(CATEGORIES_I18N_KEYS.tilesAllNoMatches)}
          />
        ) : (
          <List
            data-testid="categories-tile-grid-dialog-list"
            size="small"
            dataSource={filtered}
            renderItem={({ entry, label }) => {
              const value = isVirtualTile(entry);
              const key = value
                ? `value-${entry.virtual.value}`
                : String(entry.category.id);
              return (
              <List.Item
                key={key}
                data-testid={`categories-tile-grid-dialog-option-${key}`}
              >
                <CategoryLink
                  {...linkProps}
                  {...(value
                    ? {}
                    : {
                        slug: entry.category.slug,
                        categoryId: entry.category.id,
                      })}
                  href={entry.href}
                  style={{
                    display: "flex",
                    alignItems: "center",
                    justifyContent: "space-between",
                    gap: spacing[2],
                    width: "100%",
                    minHeight: PHONE_CONTROL_HEIGHT,
                    color: cssVar("text"),
                  }}
                >
                  <span>{label}</span>
                  <span
                    style={{
                      width: spacing[7],
                      height: spacing[7],
                      flex: "0 0 auto",
                    }}
                  >
                    {value ? (
                      <TileMonogram label={label} />
                    ) : (
                      tileArt(
                        entry.icon,
                        label,
                        entry,
                        false,
                        props.renderIcon,
                        props.resolveIconSrc
                      )
                    )}
                  </span>
                </CategoryLink>
              </List.Item>
              );
            }}
          />
        )}
      </Flex>
    </SkinDialog>
  );
}

/** The scroll port itself: the "All" tile, then one tile per row, then —
 * past `maxVisible` under `overflow: "modal"` — the "All categories" tile and
 * its dialog. */
function TileRow(props: {
  readonly entries: readonly CategoryTileEntry[];
  readonly basePath: string;
  readonly allTile?: boolean;
  readonly linkComponent?: LinkComponent;
  readonly renderIcon?: (reference: string, entry: CarouselEntry) => ReactNode;
  readonly resolveIconSrc?: CategoryIconResolver;
  readonly density: TileDensity;
  readonly size: TileSize;
  readonly surface: TileSurface;
  readonly labelLines: number | undefined;
  readonly labelHyphens: TileLabelHyphens;
  readonly layout: TileLayout;
  readonly minTileWidth: number;
  readonly eagerCount: number;
  readonly maxVisible?: number;
  readonly overflow: TileOverflow;
  /** See {@link CategoryTileGridProps.visibleColumns}. */
  readonly visibleColumns?: number;
}): ReactElement {
  const t = useT();
  /* The locale the captions are hyphenated BY — see `TileLabelHyphens`. Read
     from the engine rather than taken as a prop: the pair already resolves
     every one of these labels through that same engine, so a second answer
     to "what language is this" could only ever disagree with the first. */
  const { locale } = useI18n();
  const labelLang = props.labelHyphens === "auto" ? locale : undefined;
  const [dialogOpen, setDialogOpen] = useState(false);
  const linkProps =
    props.linkComponent !== undefined
      ? { linkComponent: props.linkComponent }
      : {};
  const capped =
    props.overflow === "modal" &&
    props.maxVisible !== undefined &&
    props.entries.length > props.maxVisible;
  const visible = capped ? props.entries.slice(0, props.maxVisible) : props.entries;
  const hiddenCount = capped ? props.entries.length - visible.length : 0;

  return (
    <>
      <div
        style={listStyle(
          props.layout,
          props.density,
          props.minTileWidth,
          props.size,
          visible.length + (props.allTile !== false ? 1 : 0) + (capped ? 1 : 0),
          props.visibleColumns
        )}
        data-stapel-tile-layout={props.layout}
        data-testid="categories-tile-grid-list"
      >
        {props.allTile !== false && (() => {
          const allLabel = t(CATEGORIES_I18N_KEYS.tilesAll);
          return (
            <Tile
              {...linkProps}
              density={props.density}
              size={props.size}
              surface={props.surface}
              labelLines={props.labelLines}
              labelHyphens={props.labelHyphens}
              labelLang={labelLang}
              href={props.basePath}
              label={allLabel}
              art={<AllCategoriesGlyph />}
              testId="categories-tile-grid-all"
            />
          );
        })()}
        {visible.map((entry, index) => {
          const label = renderCategoryLabel(entry.label, t);
          const value = isVirtualTile(entry);
          return (
            <Tile
              // A value has no id to key by, and its option code is unique
              // among its siblings by construction — they are the values of
              // one feature.
              key={value ? `value:${entry.virtual.value}` : entry.category.id}
              {...linkProps}
              density={props.density}
              size={props.size}
              surface={props.surface}
              labelLines={props.labelLines}
              labelHyphens={props.labelHyphens}
              labelLang={labelLang}
              href={entry.href}
              {...(value
                ? {}
                : { slug: entry.category.slug, categoryId: entry.category.id })}
              label={label}
              art={
                value ? (
                  // No row, so no `catalog_icon` and nothing for a host
                  // resolver to key on: the caption's own monogram, which is
                  // what an unglyphed category tile draws too.
                  <TileMonogram label={label} />
                ) : (
                  tileArt(
                    entry.icon,
                    label,
                    entry,
                    index < props.eagerCount,
                    props.renderIcon,
                    props.resolveIconSrc
                  )
                )
              }
            />
          );
        })}
        {capped ? (
          <MoreTile
            label={t(CATEGORIES_I18N_KEYS.tilesShowAll)}
            extraCount={hiddenCount}
            density={props.density}
            size={props.size}
            surface={props.surface}
            labelLines={props.labelLines}
            labelHyphens={props.labelHyphens}
            labelLang={labelLang}
            testId="categories-tile-grid-more"
            data-analytics="none"
            data-analytics-reason="opens the local overflow dialog; nothing leaves the browser"
            onClick={() => {
              setDialogOpen(true);
            }}
          />
        ) : null}
      </div>
      {capped ? (
        <AllCategoriesDialog
          open={dialogOpen}
          onClose={() => {
            setDialogOpen(false);
          }}
          entries={props.entries}
          {...linkProps}
          {...(props.renderIcon !== undefined ? { renderIcon: props.renderIcon } : {})}
          {...(props.resolveIconSrc !== undefined
            ? { resolveIconSrc: props.resolveIconSrc }
            : {})}
        />
      ) : null}
    </>
  );
}

export function CategoryTileGrid(
  props: CategoryTileGridProps
): ReactElement | null {
  const t = useT();
  const basePath = props.basePath ?? "/c";
  // Before any load: past the cap there are no tiles to ask for, so the
  // carousel bag is never mounted and the request it would make is never
  // fired. A component that fetched and then hid the answer would pay for
  // rows nobody may see.
  const offersTiles = categoryOffersTileGrid(props.categoryDepth);
  const density: TileDensity = props.density ?? "cozy";
  const size: TileSize = props.size ?? "regular";
  const surface: TileSurface = props.tileSurface ?? "flat";
  // How many tiles the reservation holds room for. A caller that knows the
  // number says it and the box is the rows those tiles will take — see
  // `tileStageRows`; one that does not gets the arm's own long-standing four.
  const reserveCount = props.reserveCount ?? RESERVED_TILES_DEFAULT;
  const overflow: TileOverflow = props.overflow ?? "none";
  const layout: TileLayout = props.layout ?? "scroll";
  const minTileWidth =
    props.minTileWidth ??
    (size === "compact" ? COMPACT_SIZE_MIN_TILE_WIDTH : DEFAULT_MIN_TILE_WIDTH);
  const eagerCount = props.eagerCount ?? DEFAULT_EAGER_COUNT;
  const rowProps = {
    basePath,
    density,
    size,
    surface,
    labelLines: props.labelLines,
    labelHyphens: props.labelHyphens ?? "manual",
    layout,
    minTileWidth,
    eagerCount,
    overflow,
    ...(props.visibleColumns !== undefined
      ? { visibleColumns: props.visibleColumns }
      : {}),
    ...(props.maxVisible !== undefined ? { maxVisible: props.maxVisible } : {}),
    ...(props.allTile !== undefined ? { allTile: props.allTile } : {}),
    ...(props.linkComponent !== undefined
      ? { linkComponent: props.linkComponent }
      : {}),
    ...(props.renderIcon !== undefined ? { renderIcon: props.renderIcon } : {}),
    ...(props.resolveIconSrc !== undefined
      ? { resolveIconSrc: props.resolveIconSrc }
      : {}),
  };
  const override = props.entries;
  // The host's read is in flight — see `reserve`. `"pending"` is the host
  // saying so; `true` infers it from the one fact this component has, which
  // is that no rows have been handed over yet.
  const reserving =
    props.reserve === "pending" ||
    (props.reserve === true && override === undefined);

  if (!offersTiles) return null;

  return (
    /* THE CONTAINER TAKES THE TILES' OWN SURFACE.
     *
     * `SkinTheme` defaults to `surface="raised"`, which paints
     * `colorBgContainer` over the whole component — and that is a PANEL behind
     * the tile row: a lighter strip the width of the grid on the desktop
     * catalogue page, a full panel on the phone and behind the landing's
     * compact strip (owner's read of 0.29.0, dark). It is the same block fill
     * the tiles themselves just lost, one box further out, and it survived the
     * flat tile because it is painted by the wrapper rather than by anything
     * this file styles: the list geometry, the reserve box and the scroller
     * all sit INSIDE it and paint nothing of their own, so one gate here is
     * every one of the three.
     *
     * Flat tiles sit on the PAGE. `surface="bare"` paints nothing at all —
     * which also drops the text colour `raised` would have written, so the
     * flat arm states it from the token instead: `--stapel-text` resolves per
     * theme at paint time, where `SkinTheme` would have frozen the value of
     * whichever side was mounted first. The tiles' own hover fill
     * (`surface-sunken`) is then the only fill in the box, which is what makes
     * it read as a hover at all — over a `colorBgContainer` panel the two are
     * a step apart and the highlight is nearly invisible in the dark theme.
     *
     * `"card"` keeps the panel: a grid of filled tiles was designed on it.
     */
    <SkinTheme
      surface={surface === "flat" ? "bare" : "raised"}
      {...(surface === "flat" ? { style: { color: cssVar("text") } } : {})}
      {...(props.mode !== undefined ? { mode: props.mode } : {})}
    >
      <nav
        aria-label={t(CATEGORIES_I18N_KEYS.carouselTitle)}
        data-tile-surface={surface}
        data-testid="categories-tile-grid"
      >
        {/* The flat tile's hover and focus states — see `categoryTileCss`.
            Hoisted, deduped by `href`, and not mounted for a grid of cards,
            whose fill is an inline declaration and needs no rule. */}
        {surface === "flat" && (
          <style href={CATEGORY_TILE_STYLE_HREF} precedence="default">
            {categoryTileCss()}
          </style>
        )}
        {reserving ? (
          // The substrate's own loading arm, by hand: this load belongs to the
          // host, so `LoadList` has no state to route — but the box, the busy
          // role and the `data-stapel-load-state` stamp are the fleet's, and a
          // reservation that announced itself differently from every other
          // pending region would be a second dialect of "wait".
          <div
            role="status"
            aria-busy="true"
            aria-label={t(STAPEL_UI_KEYS.loading)}
            data-stapel-load-state="loading"
            data-testid="categories-tile-grid-reserved"
          >
            <ReservedTiles
              layout={layout}
              density={density}
              minTileWidth={minTileWidth}
              {...(props.visibleColumns !== undefined
                ? { visibleColumns: props.visibleColumns }
                : {})}
              size={size}
              count={reserveCount}
            />
          </div>
        ) : override !== undefined ? (
          // The override arm asks the server nothing — see `entries`.
          override.length === 0 ? (
            <EmptyState
              testId="categories-tile-grid-empty"
              compact
              title={t(CATEGORIES_I18N_KEYS.carouselEmpty)}
            />
          ) : (
            <TileRow {...rowProps} entries={override} />
          )
        ) : (
          <CategoryCarousel basePath={basePath}>
            {(bag) => (
              <LoadList
                state={bag.state}
                testId="categories-tile-grid"
                onRetry={bag.refetch}
                loading={
                  <ReservedTiles
                    layout={layout}
                    density={density}
                    minTileWidth={minTileWidth}
                    {...(props.visibleColumns !== undefined
                      ? { visibleColumns: props.visibleColumns }
                      : {})}
                    size={size}
                    count={reserveCount}
                  />
                }
                failed={(error) => (
                  <ErrorAlert
                    testId="categories-tile-grid-failed"
                    thrown={error}
                    message={t(CATEGORIES_I18N_KEYS.carouselLoadFailed)}
                    onRetry={bag.refetch}
                  />
                )}
                empty={
                  <EmptyState
                    testId="categories-tile-grid-empty"
                    compact
                    title={t(CATEGORIES_I18N_KEYS.carouselEmpty)}
                  />
                }
              >
                {(entries) => <TileRow {...rowProps} entries={entries} />}
              </LoadList>
            )}
          </CategoryCarousel>
        )}
      </nav>
    </SkinTheme>
  );
}