@osimart/create-storefront 0.0.0-stage → 1.0.0

package/app/composables/useContentTree.js

@@ -0,0 +1,770 @@
+import { markRaw } from "vue";
+/**
+ * The block tree of a block-built section (MEDIA_WITH_TEXT, VIDEO, …).
+ *
+ * Blocks nest: block.parent_key names the GROUP a block sits in ('' = the
+ * section). Order is the section's flat block order. This turns the flat list
+ * into resolved, pruned nodes; ContentNode.vue draws them. The root node is a
+ * flex container laid out by the section's own DIRECTION / VERTICAL_ON_MOBILE /
+ * ALIGNMENT / POSITION / GAP settings.
+ *
+ * Pruned (never rendered): disabled blocks and their subtrees, blocks whose
+ * group isn't in the payload, empty text, a button without label or link, an
+ * image without media, a group left with no children and no background media.
+ * In the builder editor, images and groups are kept with placeholders so there
+ * is something to click.
+ *
+ * @param section  getter / ref of the section
+ * @param options  rootDefaults   settings the root falls back to (e.g. its
+ *                                DIRECTION when the section never set one)
+ *                 fillRootImages getter: images directly in the section fill
+ *                                its height instead of setting it
+ *                 index          getter: the section's index (first image on
+ *                                the first section loads eagerly)
+ *                 imageHeight    px an Image block falls back to when it sets
+ *                                no IMAGE_HEIGHT of its own
+ *
+ * Returns { tree, backgroundOf, editing, u } — `u` holds the small value
+ * helpers so sections using this don't redefine them.
+ */
+/**
+ * options.custom      { BLOCK_TYPE: Component } — block types a section draws
+ *                     with components of its own (see the default case below).
+ * options.customText  { BLOCK_TYPE: default preset } — which of those take the
+ *                     Text block's look (preset, size, colour…).
+ * options.raw         [BLOCK_TYPE] — kept as plain nodes (with their children)
+ *                     for the section to draw itself.
+ */
+export function useContentTree(section, options = {}) {
+  const t = useT();
+  const s = computed(() => toValue(section)?.settings ?? {});
+  const { mediaUrl } = useMediaUrl();
+  const { isVideo } = useMediaTypes();
+  const { isMobile } = useLayoutShell();
+  const placeholders = usePlaceholders();
+  const editing = computed(() => !!placeholders.allowed?.value);
+
+  const has = (v) => v !== undefined && v !== null && v !== "";
+  const num = (v, d) => (has(v) && Number.isFinite(Number(v)) ? Number(v) : d);
+  const px = (v) => (has(v) && Number.isFinite(Number(v)) ? `${Number(v)}px` : undefined);
+  const compact = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => has(v)));
+  const upper = (v, d) => String(v || d).toUpperCase();
+  const pathOf = (m) => m?.path ?? (typeof m === "string" ? m : "");
+
+  /* ------------------------------------------------------------ shared bits */
+
+  const ROW_JUSTIFY = { LEFT: "flex-start", CENTER: "center", RIGHT: "flex-end", SPACE_BETWEEN: "space-between" };
+  const COL_ALIGN = { LEFT: "flex-start", CENTER: "center", RIGHT: "flex-end", SPACE_BETWEEN: "flex-start" };
+  const CROSS = { TOP: "flex-start", CENTER: "center", BOTTOM: "flex-end" };
+  const TEXT_ALIGN = { LEFT: "start", CENTER: "center", RIGHT: "end", SPACE_BETWEEN: "start" };
+
+  /** Container classes + vars from DIRECTION / ALIGNMENT / POSITION / GAP. */
+  function flexOf(v) {
+    const row = upper(v.DIRECTION, "VERTICAL") === "HORIZONTAL";
+    // SPACE_BETWEEN is a row-only choice (the panel only offers it then); a
+    // column that still has it stored lines up left, as the panel shows.
+    const chosen = upper(v.ALIGNMENT, "LEFT");
+    const align = !row && chosen === "SPACE_BETWEEN" ? "LEFT" : chosen;
+    const position = upper(v.POSITION, "CENTER");
+    // CAROUSEL (horizontal only): MOBILE swipes on phones and is a normal row
+    // above; ALWAYS swipes everywhere. Either one replaces stacking on phones.
+    const mode = row ? upper(v.CAROUSEL, "NONE") : "NONE";
+    const carousel = mode === "MOBILE" || mode === "ALWAYS";
+    return {
+      flexClasses: [
+        row ? "is-row" : "is-col",
+        {
+          // WRAP: a row that continues on the next line instead of stacking.
+          "is-wrap": row && !carousel && !!v.WRAP,
+          "stack-mobile": row && !carousel && !v.WRAP && v.VERTICAL_ON_MOBILE !== false,
+          "car-mobile": mode === "MOBILE",
+          "car-always": mode === "ALWAYS",
+        },
+      ],
+      carousel: carousel
+        ? {
+            arrows: v.CAROUSEL_ARROWS !== false,
+            dots: v.CAROUSEL_DOTS !== false,
+            autoplay: !!v.CAROUSEL_AUTOPLAY,
+            interval: num(v.CAROUSEL_INTERVAL, 5) * 1000,
+            loop: v.CAROUSEL_LOOP !== false,
+            // Where the controls sit, and how they look.
+            arrowsAt: upper(v.CAROUSEL_ARROWS_POSITION, "BELOW") === "SIDES" ? "SIDES" : "BELOW",
+            dotsAt: upper(v.CAROUSEL_DOTS_POSITION, "BELOW") === "INSIDE" ? "INSIDE" : "BELOW",
+            dotStyle: ["BAR", "LINE"].includes(upper(v.CAROUSEL_DOT_STYLE, "DOT"))
+              ? upper(v.CAROUSEL_DOT_STYLE, "DOT")
+              : "DOT",
+            arrowBorder: v.CAROUSEL_ARROW_BORDER !== false,
+            controlVars: compact({
+              "--bc-arrow": px(v.CAROUSEL_ARROW_SIZE),
+              "--bc-arrow-color": v.CAROUSEL_ARROW_COLOR,
+              "--bc-arrow-bg": v.CAROUSEL_ARROW_BG,
+              "--bc-arrow-border": v.CAROUSEL_ARROW_BORDER_COLOR,
+              "--bc-arrow-radius": px(v.CAROUSEL_ARROW_RADIUS),
+              "--bc-arrow-offset": px(v.CAROUSEL_ARROW_OFFSET),
+              "--bc-dot": px(v.CAROUSEL_DOT_SIZE),
+              "--bc-dot-color": v.CAROUSEL_DOT_COLOR,
+              "--bc-dot-active": v.CAROUSEL_DOT_ACTIVE_COLOR,
+              "--bc-controls-gap": px(v.CAROUSEL_CONTROLS_SPACING),
+            }),
+          }
+        : null,
+      flexVars: compact({
+        "--cb-per": carousel ? String(num(v.PER_VIEW, 3)) : undefined,
+        "--cb-per-m": carousel ? String(num(v.PER_VIEW_MOBILE, 1.2)) : undefined,
+        // Both always set — a nested group must not inherit its parent's gap.
+        "--cb-gap": `${num(v.GAP, 16)}px`,
+        "--cb-gap-m": `${num(v.GAP_MOBILE, num(v.GAP, 16))}px`,
+        "--cb-row-justify": ROW_JUSTIFY[align],
+        "--cb-row-align": CROSS[position],
+        "--cb-col-align": COL_ALIGN[align],
+        "--cb-col-justify": CROSS[position],
+        "--cb-text-align": TEXT_ALIGN[align],
+      }),
+    };
+  }
+
+  /**
+   * Width classes. Desktop from `id` (FIT / FILL / CUSTOM + `${id}_CUSTOM` %);
+   * phones from `mobileId` when the block has one, else the desktop mode
+   * (a custom width becomes fill once a row stacks).
+   */
+  // Width shares are shortcuts for a custom %.
+  const SHARES = { QUARTER: 25, THIRD: 100 / 3, HALF: 50, TWO_THIRDS: 200 / 3, THREE_QUARTERS: 75 };
+
+  /** FIT / FILL as is; a share or CUSTOM → { mode: "CUSTOM", pct }. */
+  function widthOf(v, id, fallback) {
+    const mode = upper(v[id], fallback);
+    if (SHARES[mode]) return { mode: "CUSTOM", pct: SHARES[mode] };
+    if (mode === "CUSTOM") return { mode, pct: num(v[`${id}_CUSTOM`], 50) };
+    return { mode: mode === "FIT" ? "FIT" : "FILL" };
+  }
+
+  function sizeOf(v, id, mobileId, fallback = "FILL") {
+    const desk = widthOf(v, id, fallback);
+    // No mobile setting: a custom / share width becomes fill once a row stacks.
+    const mob = mobileId ? widthOf(v, mobileId, fallback) : { mode: desk.mode === "CUSTOM" ? "FILL" : desk.mode };
+    return {
+      sizeClasses: [`w-${desk.mode.toLowerCase()}`, `mw-${mob.mode.toLowerCase()}`],
+      sizeVars: compact({
+        "--cb-w": desk.pct != null ? `${desk.pct}%` : undefined,
+        "--cb-mw": mob.pct != null ? `${mob.pct}%` : undefined,
+      }),
+    };
+  }
+
+  /**
+   * Padding as variables, desktop and phone, like the section's own
+   * (PADDING_* and PADDING_*_MOBILE; an empty phone value = the desktop one).
+   * ContentNode's CSS picks the pair per breakpoint. All eight are always set:
+   * custom properties inherit, so a block that left one out would pick up its
+   * group's padding.
+   */
+  const SIDES = { TOP: "t", RIGHT: "r", BOTTOM: "b", LEFT: "l" };
+  function paddingOf(v) {
+    const out = {};
+    for (const [side, k] of Object.entries(SIDES)) {
+      const desktop = num(v[`PADDING_${side}`], 0);
+      out[`--cb-p${k}`] = `${desktop}px`;
+      out[`--cb-p${k}-m`] = `${num(v[`PADDING_${side}_MOBILE`], desktop)}px`;
+    }
+    return out;
+  }
+
+  /** Background, border, corner radius, padding. */
+  function boxOf(v, { background = true } = {}) {
+    return {
+      ...compact({
+        background: background ? v.BG_COLOR : undefined,
+        border: upper(v.BORDER_STYLE, "NONE") === "SOLID"
+          ? `${num(v.BORDER_WIDTH, 1)}px solid ${v.BORDER_COLOR || "currentColor"}`
+          : undefined,
+        borderRadius: num(v.RADIUS, 0) ? `${num(v.RADIUS, 0)}px` : undefined,
+      }),
+      ...paddingOf(v),
+    };
+  }
+
+  function backgroundOf(v) {
+    const kind = upper(v.BACKGROUND_TYPE, "NONE");
+    const image = (isMobile.value && v.BACKGROUND_MOBILE_IMAGE) || v.BACKGROUND_IMAGE;
+    const src = kind === "IMAGE" ? mediaUrl(image ?? null) : kind === "VIDEO" ? mediaUrl(v.BACKGROUND_VIDEO_MEDIA ?? null) : "";
+    const opacity = num(v.OVERLAY_OPACITY, 0);
+    return {
+      bg: src ? { kind: kind === "VIDEO" ? "video" : "image", src } : null,
+      overlay: opacity > 0 ? { background: v.OVERLAY_COLOR || "#000", opacity: opacity / 100 } : null,
+    };
+  }
+
+  const RATIOS = { PORTRAIT: "4 / 5", SQUARE: "1 / 1", LANDSCAPE: "4 / 3", WIDE: "16 / 9" };
+  const MAX_WIDTHS = { NARROW: "28rem", NORMAL: "42rem", NONE: "none" };
+  const WEIGHTS = { LIGHT: 300, REGULAR: 400, MEDIUM: 500, SEMIBOLD: 600, BOLD: 700 };
+  const CASES = { NONE: "none", UPPERCASE: "uppercase", LOWERCASE: "lowercase", CAPITALIZE: "capitalize" };
+  const CARD_RATIOS = { SQUARE: "1 / 1", PORTRAIT_4_5: "4 / 5", PORTRAIT_3_4: "3 / 4", LANDSCAPE: "4 / 3", WIDE: "16 / 9" };
+
+  /**
+   * A Text block's look — element, preset classes, custom typography — for
+   * Text itself and for text-like card parts (title, count, description).
+   */
+  function textLook(v, defaultPreset = "DEFAULT") {
+    const preset = upper(v.PRESET, defaultPreset);
+    const heading = HEADINGS.includes(preset);
+    // The element: a heading preset is its own tag; CUSTOM uses TAG.
+    const customTag = preset === "CUSTOM" ? upper(v.TAG, "P") : "";
+    const tag = heading ? preset : HEADINGS.includes(customTag) ? customTag : "";
+    return {
+      tag: tag ? tag.toLowerCase() : "div",
+      presetClass: heading ? ["p-heading", `p-${preset.toLowerCase()}`] : [`p-${preset.toLowerCase()}`],
+      typeVars: compact({
+        "--cb-max": MAX_WIDTHS[upper(v.MAX_WIDTH, "NORMAL")],
+        "--cb-align": TEXT_ALIGN[upper(v.ALIGNMENT, "")],
+        "--cb-color": v.COLOR,
+        ...(preset === "CUSTOM"
+          ? {
+              "--cb-ff": v.FONT === "HEADING" ? "var(--osi-font-heading)" : undefined,
+              "--cb-fs": px(v.SIZE),
+              "--cb-fs-m": px(v.SIZE_MOBILE),
+              "--cb-fw": Number(v.WEIGHT) || WEIGHTS[upper(v.WEIGHT, "")],
+              "--cb-lh": has(v.LINE_HEIGHT) ? String(num(v.LINE_HEIGHT, 150) / 100) : undefined,
+              "--cb-ls": has(v.LETTER_SPACING) ? `${num(v.LETTER_SPACING, 0) / 100}em` : undefined,
+              "--cb-tt": CASES[v.CASE],
+            }
+          : {}),
+      }),
+    };
+  }
+
+  const SPACES = { SMALL: 12, MEDIUM: 24, LARGE: 48 };
+  const HEADINGS = ["H1", "H2", "H3", "H4", "H5", "H6"];
+
+  const plain = (html) => String(html || "").replace(/<(img|video|iframe)\b/gi, "x").replace(/<[^>]*>/g, "").replace(/&nbsp;/g, " ").trim();
+  // A heading preset renders as <hN>: its richtext paragraphs become lines.
+  const inline = (html) =>
+    String(html).replace(/<\/p>\s*<p[^>]*>/gi, "<br>").replace(/^\s*<p[^>]*>/i, "").replace(/<\/p>\s*$/i, "");
+
+  /* ------------------------------------------------------------ the tree */
+
+  let firstImage = true;
+
+  /** Block types that hold other blocks (their children point at them). */
+  // PRODUCT_GRID: the classification page's grid, holding its Card template.
+  const CONTAINERS = new Set(["GROUP", "ACCORDION", "SLIDE", "CARD", "PRODUCT_GRID"]);
+
+  /** Root-level images fill the container's height (a sized section). */
+  const sized = computed(() => !!toValue(options.fillRootImages));
+
+  function resolve(block, children, atRoot = false) {
+    const v = block.settings ?? {};
+    const base = { key: block.id ?? block.key, type: block.type, s: v, children };
+
+    switch (block.type) {
+      // A Slide is a Group with a background — drawn as one (type GROUP), marked
+      // `slide` so the slideshow can find it.
+      case "SLIDE":
+      case "GROUP": {
+        // An empty group is dropped; an empty slide still shows its background.
+        if (!children.length && !editing.value && block.type !== "SLIDE" && upper(v.BACKGROUND_TYPE, "NONE") === "NONE") return null;
+        const heightMode = upper(v.HEIGHT, "FIT");
+        const size = sizeOf(v, "WIDTH");
+        const nestedLink = children.some(function linked(c) {
+          return c.link || c.type === "BUTTON" || /<a\b/i.test(c.html || "") || c.children?.some(linked);
+        });
+        const background = backgroundOf(v);
+        return {
+          ...base,
+          type: "GROUP",
+          slide: block.type === "SLIDE",
+          ...flexOf(v),
+          ...background,
+          clip: !!(num(v.RADIUS, 0) || background.bg),
+          sizeClasses: [...size.sizeClasses, `h-${heightMode.toLowerCase()}`, { "is-sticky": !!v.STICKY }],
+          sizeVars: {
+            ...size.sizeVars,
+            ...(heightMode === "CUSTOM" ? { "--cb-h": `${num(v.HEIGHT_CUSTOM, 300)}px` } : {}),
+            // Phones: HEIGHT_MOBILE, else the custom height. Always set, so a
+            // nested group never inherits its parent's.
+            "--cb-h-m": `${num(v.HEIGHT_MOBILE, heightMode === "CUSTOM" ? num(v.HEIGHT_CUSTOM, 300) : 0)}px`,
+          },
+          // COLOR: text colour for everything inside (inherited).
+          box: { ...boxOf(v), ...compact({ color: v.COLOR }) },
+          link: v.LINK_URL && !nestedLink ? v.LINK_URL : null,
+        };
+      }
+
+      case "MEDIA": {
+        // In a section with a set height, an image sitting directly in the
+        // section fills that height (cropped) instead of forcing its own —
+        // otherwise its aspect ratio decides the height and the setting does
+        // nothing.
+        const media = isMobile.value ? v.MOBILE_MEDIA || v.MEDIA || block.media : v.MEDIA ?? block.media ?? block.relations?.media;
+        const src = mediaUrl(media ?? null);
+        if (!src && !editing.value) return null;
+        const ratio = upper(v.RATIO, "SQUARE");
+        // A section can give images a height to fall back on (the marquee: an
+        // item has no row to take a width from, so it's sized by height).
+        const imageHeight = has(v.IMAGE_HEIGHT) ? v.IMAGE_HEIGHT : toValue(options.imageHeight);
+        const eager = !!src && firstImage && toValue(options.index) === 0;
+        if (src) firstImage = false;
+        return {
+          ...base,
+          ...sizeOf(v, "DESKTOP_WIDTH", "MOBILE_WIDTH"),
+          box: boxOf(v, { background: false }),
+          frame: compact({
+            "--cb-ratio": RATIOS[ratio],
+            "--cb-fit": upper(v.FIT, "COVER").toLowerCase(),
+            "--cb-max-h": px(v.MAX_HEIGHT),
+            "--cb-max-h-m": px(v.MAX_HEIGHT_MOBILE),
+            "--cb-img-h": px(imageHeight),
+            "--cb-img-h-m": px(v.IMAGE_HEIGHT_MOBILE),
+            borderRadius: px(v.RADIUS),
+          }),
+          fillHeight: atRoot && sized.value && !has(imageHeight),
+          fixedHeight: has(imageHeight),
+          grayscale: !!v.GRAYSCALE,
+          ratio: ratio === "AUTO" ? "auto" : ratio,
+          src,
+          isVideo: !!src && isVideo(pathOf(media)),
+          autoplay: v.VIDEO_AUTOPLAY !== false,
+          controls: !!v.VIDEO_CONTROLS,
+          alt: t(v.ALT) || "",
+          link: v.LINK_URL || null,
+          eager,
+        };
+      }
+
+      case "TEXT": {
+        const html = t(v.TEXT);
+        if (!plain(html)) return null;
+        const look = textLook(v);
+        return {
+          ...base,
+          ...sizeOf(v, "WIDTH", null, "FIT"),
+          box: boxOf(v),
+          ...look,
+          // In an <hN>, richtext paragraphs become lines (no <p> in a heading).
+          html: look.tag !== "div" ? inline(html) : html,
+        };
+      }
+
+      /* ---- CLASSIFICATION_LIST's / PRODUCT_LIST's card template: drawn once per item, filled
+         in from it by ContentNode (its `item` prop). Never pruned. ---- */
+
+      case "CARD": {
+        const placement = upper(v.TEXT_PLACEMENT, "BELOW") === "ON_IMAGE" ? "on-image" : "below";
+        let kids = children;
+        let box = { ...boxOf(v), ...compact({ color: v.COLOR }) };
+        // Buy buttons set to "On the image" draw inside the image (its
+        // `overlays`), not in the card's flow. No image: they stay in flow.
+        // Desktop and phones can differ: a button on the image on one and in
+        // the card on the other is drawn in both spots, each shown only on
+        // its device (`showOn`).
+        const cardImage = kids.find((c) => c.type === "CARD_IMAGE");
+        if (placement === "below" && cardImage) {
+          const overlays = [];
+          const flow = [];
+          for (const c of kids) {
+            const desk = !!c.onImage;
+            const phone = c.onImageMobile ?? desk;
+            if (!desk && !phone) flow.push(c);
+            else if (desk && phone) overlays.push(c);
+            else {
+              overlays.push({ ...c, showOn: desk ? "desktop" : "mobile" });
+              flow.push({ ...c, showOn: desk ? "mobile" : "desktop" });
+            }
+          }
+          if (overlays.length) {
+            kids = flow.map((c) => (c === cardImage ? { ...c, overlays } : c));
+          }
+        }
+        if (placement === "on-image") {
+          // Image underneath, everything else in one layer over it, placed by
+          // TEXT_POSITION; the card's padding moves onto that layer.
+          const image = children.find((c) => c.type === "CARD_IMAGE");
+          const rest = children.filter((c) => c !== image);
+          const layer = {
+            key: `${base.key}~on-image`,
+            type: "GROUP",
+            virtual: true,
+            s: {},
+            children: rest,
+            ...flexOf({ DIRECTION: "VERTICAL", ALIGNMENT: v.ALIGNMENT, POSITION: v.TEXT_POSITION || "BOTTOM", GAP: v.GAP }),
+            sizeClasses: ["w-fill", "osi-cb-card-layer"],
+            sizeVars: {},
+            box: paddingOf(v),
+            bg: null,
+            overlay: null,
+            link: null,
+            clip: false,
+          };
+          kids = image ? [image, layer] : [layer];
+          box = { ...box, ...paddingOf({}) };
+        }
+        // Image to the card's edges (IMAGE_EDGE, off by default): the image
+        // cancels the card's padding with negative margins, so the padding
+        // goes around the text only. Needs the padding under names the image
+        // doesn't reset (--card-*), since its own --cb-p* are zero.
+        const bleed = placement === "below" && !!cardImage && v.IMAGE_EDGE === true;
+        // ALIGN_BUTTONS (on by default): the card fills its cell — every card
+        // in a row as tall as the tallest — and the first part holding a
+        // button is pushed to the bottom, taking what follows with it. So a
+        // one-line title and a two-line one still put their buttons on one
+        // line. Off for a lone card (Product highlight).
+        const alignButtons =
+          placement === "below" &&
+          v.ALIGN_BUTTONS !== false &&
+          toValue(section)?.type !== "PRODUCT_HIGHLIGHT";
+        if (alignButtons) {
+          const isButton = (c) => c.type === "CARD_BUTTON" || c.type === "BUTTON";
+          const holdsButton = (c) => isButton(c) || (c.children ?? []).some(holdsButton);
+          const at = kids.findIndex((c) => c.type !== "CARD_IMAGE" && holdsButton(c));
+          if (at >= 0) kids = kids.map((c, i) => (i === at ? { ...c, pushDown: true } : c));
+        }
+        if (bleed) {
+          for (const [k, val] of Object.entries(paddingOf(v))) box[k.replace("--cb-p", "--card-p")] = val;
+        }
+        return {
+          ...base,
+          ...flexOf(v),
+          children: kids,
+          sizeClasses: ["w-fill"],
+          sizeVars: {},
+          box,
+          cardClasses: [
+            ...(bleed ? ["image-bleed"] : []),
+            ...(alignButtons ? ["align-buttons"] : []),
+            `card-${placement}`,
+            `hover-${upper(v.HOVER, "ZOOM").toLowerCase()}`,
+            `shadow-${upper(v.SHADOW, "NONE").toLowerCase()}`,
+          ],
+        };
+      }
+
+      case "CARD_IMAGE": {
+        const ratio = upper(v.RATIO, "SQUARE");
+        const fixed = ratio === "FIXED";
+        const size = sizeOf(v, "WIDTH");
+        return {
+          ...base,
+          ...size,
+          // Its own (zero) padding: without it the image inherited the card's
+          // --cb-p* and padded itself inside its frame.
+          sizeVars: { ...size.sizeVars, ...paddingOf({}) },
+          natural: ratio === "NATURAL",
+          // Product cards only (PRODUCT_LIST's schema has these fields).
+          hoverImage: v.HOVER_IMAGE !== false,
+          badges: v.BADGES !== false,
+          badgePosition: upper(v.BADGE_POSITION, "TOP_LEFT").toLowerCase().replace("_", "-"),
+          saleLabel: t(v.SALE_LABEL) || "Sale",
+          soldOutLabel: t(v.SOLD_OUT_LABEL) || "Sold out",
+          wishlist: !!v.WISHLIST,
+          badgeBrand: !!v.BADGE_BRAND,
+          badgeCategories: !!v.BADGE_CATEGORIES,
+          // The brand / category badges' own corner; null: with the others.
+          badgeInfoPosition: upper(v.BADGE_INFO_POSITION, "SAME") === "SAME"
+            ? null
+            : upper(v.BADGE_INFO_POSITION, "SAME").toLowerCase().replace("_", "-"),
+          // The wishlist button's look (WISHLIST_*).
+          wish: {
+            icon: upper(v.WISHLIST_ICON, "HEART"),
+            svg: upper(v.WISHLIST_ICON, "HEART") === "CUSTOM" ? String(v.WISHLIST_ICON_SVG || "").trim() : "",
+            position: upper(v.WISHLIST_POSITION, "TOP_RIGHT").toLowerCase().replace("_", "-"),
+            plain: upper(v.WISHLIST_STYLE, "CIRCLE") === "PLAIN",
+            hover: upper(v.WISHLIST_REVEAL, "ALWAYS") === "HOVER",
+            vars: compact({
+              "--cb-wish-size": px(v.WISHLIST_SIZE),
+              "--cb-wish-icon": px(v.WISHLIST_ICON_SIZE),
+              "--cb-wish-offset": px(v.WISHLIST_OFFSET),
+              "--cb-wish-bg": v.WISHLIST_BG,
+              "--cb-wish-border": v.WISHLIST_BORDER_COLOR,
+              "--cb-wish-color": v.WISHLIST_COLOR,
+              "--cb-wish-active": v.WISHLIST_ACTIVE_COLOR,
+            }),
+          },
+          // The badge's own look (BADGE_* / SALE_BADGE_*); empty = the scheme's.
+          badgeVars: compact({
+            "--cb-badge-bg": v.BADGE_BG,
+            "--cb-badge-color": v.BADGE_TEXT_COLOR,
+            "--cb-badge-border": v.BADGE_BORDER_COLOR,
+            "--cb-badge-bw": px(v.BADGE_BORDER_WIDTH),
+            "--cb-badge-r": px(v.BADGE_RADIUS),
+            "--cb-badge-fs": px(v.BADGE_FONT_SIZE),
+            "--cb-badge-tt": has(v.BADGE_CASE) ? (upper(v.BADGE_CASE, "UPPERCASE") === "NONE" ? "none" : "uppercase") : undefined,
+            "--cb-badge-sale-bg": v.SALE_BADGE_BG,
+            "--cb-badge-sale-color": v.SALE_BADGE_TEXT_COLOR,
+            "--cb-badge-sale-border": v.SALE_BADGE_BORDER_COLOR,
+            "--cb-badge-out-bg": v.SOLD_OUT_BADGE_BG,
+            "--cb-badge-out-color": v.SOLD_OUT_BADGE_TEXT_COLOR,
+            "--cb-badge-out-border": v.SOLD_OUT_BADGE_BORDER_COLOR,
+          }),
+          frame: compact({
+            "--cb-ratio": fixed || ratio === "NATURAL" ? "auto" : CARD_RATIOS[ratio] ?? "1 / 1",
+            "--cb-h": fixed ? px(num(v.IMAGE_HEIGHT, 320)) : undefined,
+            "--cb-h-m": fixed ? px(num(v.IMAGE_HEIGHT_MOBILE, num(v.IMAGE_HEIGHT, 320))) : undefined,
+            "--cb-fit": upper(v.FIT, "COVER") === "CONTAIN" ? "contain" : "cover",
+            borderRadius: px(v.RADIUS),
+          }),
+          overlay:
+            num(v.OVERLAY_OPACITY, 0) > 0
+              ? { background: v.OVERLAY_COLOR || "#000", opacity: num(v.OVERLAY_OPACITY, 0) / 100 }
+              : null,
+        };
+      }
+
+      case "CARD_TITLE":
+      case "CARD_COUNT":
+      case "CARD_DESCRIPTION":
+        return {
+          ...base,
+          ...sizeOf(v, "WIDTH", null, "FIT"),
+          box: boxOf(v),
+          ...textLook(v, { CARD_TITLE: "H4", CARD_COUNT: "CUSTOM", CARD_DESCRIPTION: "PARAGRAPH" }[block.type]),
+          part: { CARD_TITLE: "title", CARD_COUNT: "count", CARD_DESCRIPTION: "description" }[block.type],
+          prefix: t(v.PREFIX),
+          singular: t(v.SINGULAR) || "product",
+          plural: t(v.PLURAL) || "products",
+          lines: num(v.LINES, 2),
+          // Product titles clamp only when the block sets LINES.
+          clamp: block.type === "CARD_DESCRIPTION" || has(v.LINES),
+        };
+
+      case "CARD_PRICE":
+        return {
+          ...base,
+          ...sizeOf(v, "WIDTH", null, "FIT"),
+          box: boxOf(v),
+          ...textLook(v, "CUSTOM"),
+          part: "price",
+          showCompare: v.SHOW_COMPARE !== false,
+          priceVars: compact({ "--cb-sale": v.SALE_COLOR, "--cb-was": v.COMPARE_COLOR }),
+        };
+
+      case "CARD_SWATCHES":
+        return {
+          ...base,
+          box: boxOf(v, { background: false }),
+          max: num(v.MAX, 5),
+          square: upper(v.SHAPE, "CIRCLE") === "SQUARE",
+          // COLOR: the colour option only; ALL: every option (sizes as text).
+          show: upper(v.SHOW, "ALL"),
+          swatchVars: { "--cb-sw": `${num(v.SIZE, 16)}px`, "--cb-sw-gap": `${num(v.GAP, 6)}px` },
+        };
+
+      case "CARD_BUTTON":
+        return {
+          ...base,
+          ...sizeOf(v, "WIDTH", null, "FIT"),
+          box: boxOf(v, { background: false }),
+          label: t(v.LABEL) || (has(v.ACTION) ? "Add to cart" : "Shop now"),
+          // Product cards: QUICK_BUY | ADD_TO_CART | LINK. Classification cards have no
+          // ACTION — their button is only a look.
+          action: upper(v.ACTION, "LINK"),
+          optionsLabel: t(v.OPTIONS_LABEL) || "Choose options",
+          soldOutLabel: t(v.SOLD_OUT_LABEL) || "Sold out",
+          quickBuyStyle: upper(v.QUICK_BUY_STYLE, "SHEET"),
+          look: upper(v.LOOK, "TEXT"),
+          onImage: upper(v.PLACEMENT, "IN_CARD") === "ON_IMAGE",
+          // null: same as desktop.
+          onImageMobile: { IN_CARD: false, ON_IMAGE: true }[upper(v.PLACEMENT_MOBILE, "SAME")] ?? null,
+          imagePosition: upper(v.IMAGE_POSITION, "BOTTOM").toLowerCase().replace("_", "-"),
+          imageOffset: px(v.IMAGE_OFFSET),
+          revealOnHover: upper(v.REVEAL, "HOVER") === "HOVER",
+          // The icon (ICON looks): a preset or the merchant's SVG, and its sizes.
+          icon: upper(v.ICON, "BAG"),
+          iconSvg: upper(v.ICON, "BAG") === "CUSTOM" ? String(v.ICON_SVG || "").trim() : "",
+          btnVars: compact({ "--cb-btn-icon": px(v.ICON_SIZE), "--cb-btn-size": px(v.CIRCLE_SIZE) }),
+        };
+
+      case "BUTTON": {
+        const label = t(v.LABEL);
+        if (!label || !v.URL) return null;
+        return {
+          ...base,
+          ...sizeOf(v, "WIDTH", null, "FIT"),
+          box: boxOf(v, { background: false }),
+          label,
+          url: v.URL,
+          newTab: !!v.OPEN_IN_NEW_TAB,
+        };
+      }
+
+      case "ICON":
+        return {
+          ...base,
+          box: boxOf(v),
+          iconVars: compact({ "--cb-icon": px(v.SIZE), color: v.COLOR }),
+          icon: v.ICON_PRESET,
+          svg: String(v.ICON_SVG || "").trim(),
+          link: v.LINK_URL || null,
+        };
+
+      case "SPACER": {
+        const size = upper(v.SIZE, "MEDIUM");
+        return {
+          ...base,
+          box: paddingOf({}),
+          spacerVars: compact({
+            "--cb-sp": `${size === "CUSTOM" ? num(v.SIZE_CUSTOM, 40) : SPACES[size] ?? SPACES.MEDIUM}px`,
+            "--cb-sp-m": px(v.SIZE_MOBILE),
+          }),
+        };
+      }
+
+      case "RATING": {
+        const value = Math.max(0, Math.min(5, Number(v.RATING ?? 5) || 0));
+        return {
+          ...base,
+          box: boxOf(v),
+          value,
+          // Each star's filled share, 0..1 — 4.5 → five stars, the last half full.
+          stars: [0, 1, 2, 3, 4].map((i) => Math.max(0, Math.min(1, value - i))),
+          // A set empty colour is used as is; unset, empty stars are a faint
+          // version of the text colour.
+          customOff: has(v.EMPTY_COLOR),
+          ratingVars: compact({
+            "--cb-star": px(num(v.SIZE, 18)),
+            "--cb-star-gap": px(num(v.GAP, 2)),
+            "--cb-star-on": v.COLOR || "#f5a623",
+            "--cb-star-off": v.EMPTY_COLOR,
+          }),
+        };
+      }
+
+      case "ACCORDION": {
+        if (!children.length && !editing.value) return null;
+        const grid = upper(v.LAYOUT, "ACCORDION") === "GRID";
+        const tag = { H2: "h2", H3: "h3", H4: "h4", P: "p" }[upper(v.QUESTION_TAG, "H3")] ?? "h3";
+        const context = {
+          grid,
+          tag,
+          // Same name = the browser keeps one open at a time, natively.
+          name: v.ONE_AT_A_TIME !== false ? `faq-${base.key}` : undefined,
+          icon: upper(v.ICON_STYLE, "PLUS_MINUS"),
+          iconStart: upper(v.ICON_POSITION, "END") === "START",
+        };
+        let first = true;
+        for (const child of children) {
+          if (child.type !== "FAQ_ITEM") continue;
+          child.acc = context;
+          if (first && v.OPEN_FIRST !== false && !grid) child.open = true;
+          first = false;
+        }
+        const divider = upper(v.DIVIDER, "DIVIDER");
+        const typeVars = (prefix, key) =>
+          compact({
+            [`--faq-${key}-fs`]: px(v[`${prefix}_SIZE`]),
+            [`--faq-${key}-fs-m`]: px(v[`${prefix}_SIZE_MOBILE`]),
+            [`--faq-${key}-fw`]: Number(v[`${prefix}_WEIGHT`]) || undefined,
+            [`--faq-${key}-ff`]: v[`${prefix}_FONT`] === "HEADING" ? "var(--osi-font-heading)" : undefined,
+            [`--faq-${key}-lh`]: has(v[`${prefix}_LINE_HEIGHT`]) ? String(num(v[`${prefix}_LINE_HEIGHT`], 150) / 100) : undefined,
+            [`--faq-${key}-color`]: v[`${prefix}_COLOR`],
+          });
+        return {
+          ...base,
+          ...sizeOf(v, "WIDTH"),
+          box: boxOf(v),
+          accClasses: [grid ? "is-grid" : "is-list", `rows-${divider.toLowerCase()}`],
+          accVars: {
+            "--faq-gap": `${num(v.ITEM_SPACING, 0)}px`,
+            "--faq-cols": String(num(v.COLUMNS, 2)),
+            "--faq-cols-m": String(num(v.COLUMNS_MOBILE, 1)),
+            "--faq-radius": `${num(v.ROW_RADIUS, 8)}px`,
+            "--faq-py": `${num(v.ROW_PADDING_Y, 16)}px`,
+            "--faq-px": `${num(v.ROW_PADDING_X, 0)}px`,
+            "--faq-icon": `${num(v.ICON_SIZE, 12)}px`,
+            ...compact({
+              "--faq-line": v.DIVIDER_COLOR,
+              "--faq-row-bg": v.ROW_BG,
+              "--faq-icon-color": v.ICON_COLOR,
+            }),
+            ...typeVars("QUESTION", "q"),
+            ...typeVars("ANSWER", "a"),
+          },
+        };
+      }
+
+      case "FAQ_ITEM": {
+        const question = t(v.QUESTION);
+        if (!question && !editing.value) return null;
+        return {
+          ...base,
+          box: paddingOf({}),
+          question: question || "Question",
+          answer: t(v.ANSWER),
+          open: v.OPEN === true,
+          // Replaced by the accordion it sits in; a lone question uses these.
+          acc: { grid: false, tag: "h3", name: undefined, icon: "PLUS_MINUS", iconStart: false },
+        };
+      }
+
+      default: {
+        // A section's own block types (the footer's Menu, Logo…): the
+        // section passes options.custom = { TYPE: Component }. Drawn by that
+        // component with the node's box / width and its raw settings.
+        // options.raw: types the section draws itself from the tree (the
+        // classification page's Toolbar / Product grid) — kept as plain nodes.
+        if (options.raw?.includes(block.type)) return base;
+        const component = options.custom?.[block.type];
+        if (!component) return null;
+        // options.customText: { TYPE: default preset } — blocks with the Text
+        // block's look (a banner's title…) get it resolved like Text does.
+        const textDefault = options.customText?.[block.type];
+        return {
+          ...base,
+          ...sizeOf(v, "WIDTH", "WIDTH_MOBILE", "FILL"),
+          box: boxOf(v, { background: false }),
+          ...(textDefault ? textLook(v, textDefault) : {}),
+          component: markRaw(component),
+        };
+      }
+    }
+  }
+
+  /**
+   * VISIBILITY (every content block): shown everywhere, or only on phones /
+   * only on larger screens. A class the parent puts on the node's element
+   * (ContentNode's `vis-*`), so it's CSS — no flash, works with SSR.
+   */
+  const VIS = { DESKTOP: "vis-desktop", MOBILE: "vis-mobile" };
+  function withVisibility(block, node) {
+    if (!node) return node;
+    const vis = VIS[upper(block.settings?.VISIBILITY, "ALL")];
+    return vis ? { ...node, visClass: vis } : node;
+  }
+
+  const tree = computed(() => {
+    const blocks = toValue(section)?.blocks ?? [];
+    const keys = new Set(blocks.map((b) => b.key));
+    const byParent = new Map();
+    for (const b of blocks) {
+      const parent = b.parent_key || "";
+      // A parent that isn't here (a hidden group the API left out) takes its
+      // children with it — lifting them to the top would scramble the layout.
+      if (parent && !keys.has(parent)) continue;
+      if (!byParent.has(parent)) byParent.set(parent, []);
+      byParent.get(parent).push(b);
+    }
+    firstImage = true;
+    const build = (parent, depth) =>
+      depth > 8
+        ? []
+        : (byParent.get(parent) ?? [])
+            .filter((b) => !b.disabled)
+            .map((b) => withVisibility(b, resolve(b, CONTAINERS.has(b.type) ? build(b.key, depth + 1) : [], parent === "")))
+            .filter(Boolean);
+    const children = build("", 0);
+    return {
+      key: "root",
+      type: "GROUP",
+      children,
+      ...flexOf({ ...(options.rootDefaults ?? {}), ...s.value }),
+      sizeClasses: [],
+      sizeVars: {},
+      box: paddingOf({}),
+      bg: null,
+      overlay: null,
+      link: null,
+    };
+  });
+
+  return { tree, backgroundOf, editing, u: { has, num, px, compact, upper } };
+}