create-skybridge 0.0.0-dev.08be486 → 0.0.0-dev.09043e8

package/templates/ecom/src/components/product-card.tsx

@@ -0,0 +1,102 @@
+import type { ReactNode } from "react";
+import { useUser } from "skybridge/web";
+import { text } from "../design/tokens";
+import { useLabels } from "../i18n";
+import { cx } from "../lib/cx";
+import { formatPrice } from "../lib/format";
+import type { Price } from "../types.js";
+import * as styles from "./product-card.css";
+
+type ProductCardProps = {
+  title: string;
+  price?: Price;
+  media?: string[]; // all images; the card decides which to show
+  outOfStock?: boolean;
+};
+
+// @todo: for boxed cards (border + background), set this to true and leave the
+// carousel unframed. Pick one, not both.
+const FRAMED = false;
+
+/**
+ * A single product card: image, title, price, and an out-of-stock treatment.
+ * Maps a product's display fields to markup; the view passes them in.
+ */
+export function ProductCard({
+  title,
+  price,
+  media,
+  outOfStock,
+}: ProductCardProps) {
+  const { locale } = useUser();
+  const labels = useLabels();
+  // Show the first image. @todo: the rest of `media` is available here, e.g. to
+  // swap in media[1] on hover (do not cross-fade, breaks with transparency)
+  const cover = media?.[0];
+  return (
+    <article className={styles.card({ framed: FRAMED })}>
+      <div className={styles.imageBox}>
+        {cover ? (
+          <img
+            className={cx(styles.image, outOfStock && styles.imageDimmed)}
+            src={cover}
+            alt={title}
+            loading="lazy"
+            draggable={false}
+          />
+        ) : (
+          <div className={styles.placeholder} />
+        )}
+        {outOfStock ? (
+          <span className={styles.oosBadge}>{labels.outOfStock}</span>
+        ) : null}
+      </div>
+
+      <div className={styles.body}>
+        <p
+          className={cx(
+            text({ style: "bodyS", weight: "medium" }),
+            styles.title,
+          )}
+        >
+          {title}
+        </p>
+        {price ? (
+          <p className={cx(text({ style: "bodyS" }), styles.price)}>
+            {formatPrice(price, locale)}
+          </p>
+        ) : null}
+        {/* @todo: to show a custom Meta field (rating → stars, discountPct →
+            badge, badges → chips), add it to ProductCardProps, pass
+            card.<field> from the carousel view, and render it here. */}
+      </div>
+    </article>
+  );
+}
+
+/** Placeholder card shown while the tool resolves. Same footprint as the card
+ *  so the layout does not jump when data arrives. */
+export function ProductCardSkeleton() {
+  const titleLines: ReactNode[] = [];
+  for (let i = 0; i < styles.TITLE_LINES; i++) {
+    const isLast = i === styles.TITLE_LINES - 1;
+    titleLines.push(
+      <div
+        key={i}
+        className={cx(
+          styles.skeletonBox,
+          isLast ? styles.skeletonLineShort : styles.skeletonLine,
+        )}
+      />,
+    );
+  }
+  return (
+    <div className={styles.card({ framed: FRAMED })} aria-hidden="true">
+      <div className={cx(styles.skeletonBox, styles.skeletonImage)} />
+      <div className={styles.skeletonBody}>
+        {titleLines}
+        <div className={cx(styles.skeletonBox, styles.skeletonPrice)} />
+      </div>
+    </div>
+  );
+}

package/templates/ecom/src/components/product-carousel.css.ts

@@ -0,0 +1,134 @@
+import { globalStyle, style } from "@vanilla-extract/css";
+import { recipe } from "@vanilla-extract/recipes";
+import { colors, primitives } from "../design/tokens";
+
+// Carousel tuning knobs. @todo: tune to your card design.
+const gap = primitives.space["2xs"]; // gap between cards
+// Cards visible at each width; the fractional part is the peek that signals the
+// row scrolls. If you change a count, adjust the gap multiplier in its
+// `--card-width` calc (full gaps visible = the whole-number part).
+const CARDS_VISIBLE = 2.5;
+const CARDS_VISIBLE_COMPACT = 1.5;
+// Below this container width, switch to the compact count.
+const COMPACT_MAX_WIDTH = "560px";
+
+// Structural wrapper (kept as a plain class so the nav-reveal globalStyle below
+// can target it). The recipe composes it as its base.
+const carouselBase = style({
+  position: "relative",
+  // Size cards against the carousel width, not the iframe viewport.
+  containerType: "inline-size",
+});
+
+// `framed: true` frames the whole carousel; the default is flush (pair it with
+// framed cards instead). Pick one of the two.
+export const carousel = recipe({
+  base: carouselBase,
+  variants: {
+    framed: {
+      // @todo: tune the outer frame to your brand. Soften the shadow in dark
+      // mode if the strip reads as a hard box against the host.
+      true: {
+        // Pad top/bottom only; the leading/trailing inset lives on the track's
+        // own `framed` variant so it scrolls away. Cards bleed to the left/right
+        // border, and `overflow: hidden` masks them to the rounded corners, so
+        // a scrolled card disappears exactly at the frame edge.
+        paddingBlock: primitives.space.xs,
+        borderRadius: primitives.radius.l,
+        border: `${primitives.stroke.thin} solid ${colors.border.thin}`,
+        backgroundColor: colors.surface.extraLight,
+        boxShadow: "0 10px 20px -20px rgba(0, 0, 0, 0.18)",
+        overflow: "hidden",
+      },
+      false: {},
+    },
+  },
+  defaultVariants: { framed: false },
+});
+
+// Kept as a plain class so the scrollbar-hiding globalStyle below can target it.
+// The recipe composes it as its base.
+const trackBase = style({
+  display: "flex",
+  gap,
+  overflowX: "auto",
+  scrollSnapType: "x mandatory",
+  scrollBehavior: "smooth",
+  scrollbarWidth: "none",
+  vars: { "--card-width": `calc((100% - 2 * ${gap}) / ${CARDS_VISIBLE})` },
+  "@container": {
+    [`(max-width: ${COMPACT_MAX_WIDTH})`]: {
+      vars: {
+        "--card-width": `calc((100% - ${gap}) / ${CARDS_VISIBLE_COMPACT})`,
+      },
+    },
+  },
+  "@media": {
+    "(prefers-reduced-motion: reduce)": { scrollBehavior: "auto" },
+  },
+});
+
+globalStyle(`${trackBase}::-webkit-scrollbar`, { display: "none" });
+
+// `framed: true` adds an inset on both ends. Padding on the scroll track (not on
+// the frame) so it shows before the first card and after the last at rest, but
+// scrolls away in between: a card scrolled past clips at the border, not at a
+// fixed gutter. scroll-padding keeps mandatory snap from collapsing the inset.
+export const track = recipe({
+  base: trackBase,
+  variants: {
+    framed: {
+      true: {
+        paddingInline: primitives.space.xs,
+        scrollPaddingInline: primitives.space.xs,
+      },
+      false: {},
+    },
+    // Skeleton state: lock the scroll, there is nothing to scroll to yet.
+    loading: {
+      true: { overflowX: "hidden" },
+      false: {},
+    },
+  },
+  defaultVariants: { framed: false, loading: false },
+});
+
+export const cell = style({
+  flex: "0 0 var(--card-width)",
+  scrollSnapAlign: "start",
+});
+
+// Prev/next buttons: desktop only. Hidden on touch, revealed on hover/focus,
+// disabled at the scroll ends.
+export const nav = style({
+  position: "absolute",
+  top: "50%",
+  transform: "translateY(-50%)",
+  display: "grid",
+  placeItems: "center",
+  width: "36px",
+  height: "36px",
+  padding: 0,
+  borderRadius: primitives.radius.full,
+  border: `${primitives.stroke.thin} solid ${colors.border.subtle}`,
+  backgroundColor: colors.surface.extraLight,
+  color: colors.content.intense,
+  cursor: "pointer",
+  opacity: 0,
+  transition: "opacity 150ms ease",
+  selectors: {
+    "&:disabled": { opacity: 0, pointerEvents: "none" },
+  },
+  "@media": {
+    "(hover: none)": { display: "none" },
+  },
+});
+
+export const navPrev = style({ left: primitives.space["3xs"] });
+export const navNext = style({ right: primitives.space["3xs"] });
+
+// Reveal the (enabled) buttons on hover or keyboard focus within the carousel.
+globalStyle(
+  `${carouselBase}:hover ${nav}:not(:disabled), ${carouselBase}:focus-within ${nav}:not(:disabled)`,
+  { opacity: 1 },
+);

package/templates/ecom/src/components/product-carousel.stories.tsx

@@ -0,0 +1,64 @@
+import type { ReactNode } from "react";
+import type { Price } from "../types.js";
+import { ProductCard, ProductCardSkeleton } from "./product-card";
+import { ProductCarousel } from "./product-carousel";
+
+const IMAGE =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='240' height='240'%3E%3Crect width='240' height='240' fill='%23e5e5e5'/%3E%3Ccircle cx='120' cy='120' r='70' fill='%23bcbcbc'/%3E%3C/svg%3E";
+
+type Sample = { title: string; price: Price; outOfStock?: boolean };
+
+const SAMPLE: Sample[] = [
+  { title: "Merino wool sweater", price: { amount: 129.9, currency: "EUR" } },
+  { title: "Oxford cotton shirt", price: { amount: 79, currency: "EUR" } },
+  { title: "Slim chino trousers", price: { amount: 89.5, currency: "EUR" } },
+  {
+    title: "Leather derby shoes",
+    price: { amount: 210, currency: "EUR" },
+    outOfStock: true,
+  },
+  { title: "Cashmere scarf", price: { amount: 145, currency: "EUR" } },
+  { title: "Quilted field jacket", price: { amount: 320, currency: "EUR" } },
+];
+
+function sampleCards(): ReactNode[] {
+  const cards: ReactNode[] = [];
+  for (let i = 0; i < SAMPLE.length; i++) {
+    const item = SAMPLE[i];
+    cards.push(
+      <ProductCard
+        key={i}
+        title={item.title}
+        price={item.price}
+        media={[IMAGE]}
+        outOfStock={item.outOfStock}
+      />,
+    );
+  }
+  return cards;
+}
+
+export const Default = () => <ProductCarousel>{sampleCards()}</ProductCarousel>;
+
+export const Loading = () => {
+  const skeletons: ReactNode[] = [];
+  for (let i = 0; i < 4; i++) {
+    skeletons.push(<ProductCardSkeleton key={i} />);
+  }
+  return <ProductCarousel loading>{skeletons}</ProductCarousel>;
+};
+
+export const FewItems = () => (
+  <ProductCarousel>
+    <ProductCard
+      title="Merino wool sweater"
+      price={{ amount: 129.9, currency: "EUR" }}
+      media={[IMAGE]}
+    />
+    <ProductCard
+      title="Oxford cotton shirt"
+      price={{ amount: 79, currency: "EUR" }}
+      media={[IMAGE]}
+    />
+  </ProductCarousel>
+);

package/templates/ecom/src/components/product-carousel.tsx

@@ -0,0 +1,202 @@
+import {
+  Children,
+  type ReactNode,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { useLabels } from "../i18n";
+import { cx } from "../lib/cx";
+import * as styles from "./product-carousel.css";
+
+// How long to wait after the last intersection change before reporting, so a
+// fast scroll does not spam updates.
+const VISIBILITY_DEBOUNCE_MS = 200;
+
+// @todo: for boxed cards (border + background), set this to true and leave the
+// carousel unframed. Pick one, not both.
+const FRAMED = false;
+
+function Chevron({ direction }: { direction: "left" | "right" }) {
+  const d = direction === "left" ? "M15 18l-6-6 6-6" : "M9 18l6-6-6-6";
+  return (
+    <svg
+      width="20"
+      height="20"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d={d} />
+    </svg>
+  );
+}
+
+type ProductCarouselProps = {
+  children: ReactNode;
+  // Reports which child indices are at least half in view, in ascending order,
+  // debounced. Use it to narrate only what the user actually sees.
+  onVisibleChange?: (indices: number[]) => void;
+  // Skeleton state: locks the scroll and hides the nav buttons.
+  loading?: boolean;
+  // Optional external ref to the scroll track. The orchestrator uses it to save
+  // and restore scroll position across the carousel ⇄ detail transition (the
+  // carousel is hidden, not unmounted, but display:none resets scrollLeft).
+  trackRef?: RefObject<HTMLElement | null>;
+};
+
+/**
+ * Horizontal, scroll-snapping track of cards. Generic: it renders whatever
+ * children it is given, one per snap cell. Native scroll handles touch; the
+ * prev/next buttons are desktop-only affordances (see product-carousel.css.ts).
+ */
+export function ProductCarousel({
+  children,
+  onVisibleChange,
+  loading = false,
+  trackRef: externalTrackRef,
+}: ProductCarouselProps) {
+  const labels = useLabels();
+  const trackRef = useRef<HTMLElement>(null);
+  // Merge the internal ref with the optional external one via a callback ref, so
+  // the orchestrator can read/restore scroll while `trackRef` stays a plain
+  // useRef (its `.current` reads need no effect dependency).
+  const setTrackRef = useCallback(
+    (el: HTMLElement | null) => {
+      trackRef.current = el;
+      if (externalTrackRef) {
+        externalTrackRef.current = el;
+      }
+    },
+    [externalTrackRef],
+  );
+  const [canScrollLeft, setCanScrollLeft] = useState(false);
+  const [canScrollRight, setCanScrollRight] = useState(false);
+
+  useEffect(() => {
+    const el = trackRef.current;
+    if (!el) {
+      return;
+    }
+    const updateEdges = () => {
+      setCanScrollLeft(el.scrollLeft > 0);
+      setCanScrollRight(el.scrollLeft + el.clientWidth < el.scrollWidth - 1);
+    };
+    updateEdges();
+    el.addEventListener("scroll", updateEdges, { passive: true });
+    const observer = new ResizeObserver(updateEdges);
+    observer.observe(el);
+    return () => {
+      el.removeEventListener("scroll", updateEdges);
+      observer.disconnect();
+    };
+  }, []);
+
+  // Track which cells are in view and report them (only when a consumer asks).
+  // Pass a stable `onVisibleChange` (e.g. a useState setter): a new identity
+  // each render re-subscribes the observer.
+  const childCount = Children.count(children);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: childCount re-subscribes when the number of cells changes; it is not read in the body.
+  useEffect(() => {
+    const el = trackRef.current;
+    if (!el || !onVisibleChange) {
+      return;
+    }
+    const cells = Array.from(el.children);
+    const visible = new Set<number>();
+    let timer: number | undefined;
+    const emit = () => {
+      const indices = [...visible].sort((a, b) => a - b);
+      onVisibleChange?.(indices);
+    };
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          const index = cells.indexOf(entry.target);
+          if (index === -1) {
+            continue;
+          }
+          if (entry.isIntersecting) {
+            visible.add(index);
+          } else {
+            visible.delete(index);
+          }
+        }
+        window.clearTimeout(timer);
+        timer = window.setTimeout(emit, VISIBILITY_DEBOUNCE_MS);
+      },
+      { root: el, threshold: 0.5 },
+    );
+    for (const cell of cells) {
+      observer.observe(cell);
+    }
+    return () => {
+      window.clearTimeout(timer);
+      observer.disconnect();
+    };
+  }, [childCount, onVisibleChange]);
+
+  const step = (direction: 1 | -1) => {
+    const el = trackRef.current;
+    if (!el) {
+      return;
+    }
+    const cell = el.firstElementChild as HTMLElement | null;
+    const gap = Number.parseFloat(getComputedStyle(el).columnGap) || 0;
+    const distance = cell ? cell.offsetWidth + gap : el.clientWidth;
+    // No `behavior`: inherits the track's CSS scroll-behavior (respects
+    // prefers-reduced-motion).
+    el.scrollBy({ left: direction * distance });
+  };
+
+  const cells: ReactNode[] = [];
+  const items = Children.toArray(children);
+  for (let i = 0; i < items.length; i++) {
+    cells.push(
+      <div key={i} className={styles.cell}>
+        {items[i]}
+      </div>,
+    );
+  }
+
+  return (
+    <div className={styles.carousel({ framed: FRAMED })}>
+      <section
+        ref={setTrackRef}
+        className={styles.track({ framed: FRAMED, loading })}
+        aria-roledescription={labels.carousel}
+        aria-label={labels.products}
+      >
+        {cells}
+      </section>
+      {loading ? null : (
+        <>
+          <button
+            type="button"
+            aria-label={labels.previous}
+            className={cx(styles.nav, styles.navPrev)}
+            disabled={!canScrollLeft}
+            onClick={() => step(-1)}
+          >
+            <Chevron direction="left" />
+          </button>
+          <button
+            type="button"
+            aria-label={labels.next}
+            className={cx(styles.nav, styles.navNext)}
+            disabled={!canScrollRight}
+            onClick={() => step(1)}
+          >
+            <Chevron direction="right" />
+          </button>
+        </>
+      )}
+    </div>
+  );
+}

package/templates/ecom/src/components/variant-picker.css.ts

@@ -0,0 +1,27 @@
+import { style } from "@vanilla-extract/css";
+import { colors, primitives } from "../design/tokens";
+
+export const picker = style({
+  display: "flex",
+  flexDirection: "column",
+  gap: primitives.space.xs,
+});
+
+export const section = style({
+  display: "flex",
+  flexDirection: "column",
+  gap: primitives.space["3xs"],
+});
+
+export const label = style({
+  color: colors.content.subtle,
+});
+
+// Chip row: wraps to the next line when it overflows. @todo: swap for a
+// horizontal scroll row with an edge fade (as the carousel track) if you expect
+// many values on one axis.
+export const values = style({
+  display: "flex",
+  flexWrap: "wrap",
+  gap: primitives.space["3xs"],
+});

package/templates/ecom/src/components/variant-picker.stories.tsx

@@ -0,0 +1,67 @@
+import { useState } from "react";
+import { initialSelection, type Selection } from "../lib/variants.js";
+import type { Product } from "../types.js";
+import { VariantPicker } from "./variant-picker";
+
+// A sparse catalog: {white,42} does not exist, so "42" is hard-disabled under
+// "White"; {black,42} is sold out, so it renders struck (yet clickable) under
+// "Black".
+function variant(
+  id: string,
+  color: string,
+  size: string,
+  outOfStock = false,
+): Product["variants"][number] {
+  return {
+    id,
+    selection: { color, size },
+    title: `Sneaker ${color} ${size}`,
+    price: { amount: 120, currency: "EUR" },
+    media: [],
+    specs: [],
+    outOfStock,
+  };
+}
+
+const PRODUCT: Product = {
+  id: "sneaker",
+  options: [
+    {
+      id: "color",
+      label: "Color",
+      values: [
+        { id: "black", label: "Black" },
+        { id: "white", label: "White" },
+      ],
+    },
+    {
+      id: "size",
+      label: "Size",
+      values: [
+        { id: "40", label: "40" },
+        { id: "42", label: "42" },
+      ],
+    },
+  ],
+  variants: [
+    variant("s-b-40", "black", "40"),
+    variant("s-b-42", "black", "42", true),
+    variant("s-w-40", "white", "40"),
+  ],
+  card: { title: "Sneaker", media: [], specs: [] },
+};
+
+export const Contingency = () => {
+  const [selection, setSelection] = useState<Selection>(() =>
+    initialSelection(PRODUCT),
+  );
+  return (
+    <div style={{ maxWidth: 320 }}>
+      <VariantPicker
+        product={PRODUCT}
+        selection={selection}
+        onChange={setSelection}
+      />
+    </div>
+  );
+};

package/templates/ecom/src/components/variant-picker.tsx

@@ -0,0 +1,70 @@
+import { text } from "../design/tokens";
+import { cx } from "../lib/cx";
+import { applyChoice, axisStates, type Selection } from "../lib/variants.js";
+import type { Product } from "../types.js";
+import { Chip } from "./chip";
+import * as styles from "./variant-picker.css";
+
+type VariantPickerProps = {
+  product: Product;
+  selection: Selection;
+  onChange: (selection: Selection) => void;
+};
+
+/**
+ * Renders one section per option axis. Chip states come from axisStates
+ * (lib/variants.ts, top-down): nonexistent values are hard-disabled, sold-out
+ * ones struck but clickable (the CTA names the cause), and an axis that does
+ * not apply hides its row. A pick goes through applyChoice, which keeps
+ * still-existing later choices and snaps the rest onto a real variant.
+ *
+ * This is the in-place model: every axis is local state, no remount. @todo: if
+ * a catalog models an axis (e.g. color) as separate products, promote it to a
+ * cross-product switch that changes the opened product id instead.
+ */
+export function VariantPicker({
+  product,
+  selection,
+  onChange,
+}: VariantPickerProps) {
+  return (
+    <div className={styles.picker}>
+      {product.options.map((option) => {
+        // Empty map: the axis does not apply to the current configuration.
+        const states = axisStates(product, option.id, selection);
+        if (states.size === 0) {
+          return null;
+        }
+        return (
+          <div
+            key={option.id}
+            className={styles.section}
+            role="radiogroup"
+            aria-label={option.label}
+          >
+            <span className={cx(text({ style: "labelS" }), styles.label)}>
+              {option.label}
+            </span>
+            <div className={styles.values}>
+              {option.values.map((value) => (
+                <Chip
+                  key={value.id}
+                  label={value.label}
+                  media={value.media}
+                  selected={selection[option.id] === value.id}
+                  nonExistent={!states.has(value.id)}
+                  outOfStock={states.get(value.id) === "soldOut"}
+                  onSelect={() =>
+                    onChange(
+                      applyChoice(product, selection, option.id, value.id),
+                    )
+                  }
+                />
+              ))}
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/templates/ecom/src/components/view-frame.css.ts

@@ -0,0 +1,22 @@
+import { globalStyle, style } from "@vanilla-extract/css";
+import { colors, primitives } from "../design/tokens";
+
+/**
+ * Base frame for every view. Transparent so the widget blends into the host
+ * surface; it pins the design system's font + content color so descendants
+ * inherit from the DS, not from the host page (whose text color could be white
+ * on a dark host and make card text vanish).
+ */
+export const viewFrame = style({
+  color: colors.content.intense,
+  fontFamily: primitives.font.family.primary,
+  fontSize: primitives.font.size.m,
+  lineHeight: primitives.font.lineHeight.normal,
+  WebkitFontSmoothing: "antialiased",
+  MozOsxFontSmoothing: "grayscale",
+});
+
+// Box-sizing reset scoped to the frame subtree.
+globalStyle(`${viewFrame} *, ${viewFrame} *::before, ${viewFrame} *::after`, {
+  boxSizing: "border-box",
+});