create-skybridge 0.0.0-dev.3581704 → 0.0.0-dev.35a7b38

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,64 @@
+import { useState } from "react";
+import { initialSelection, type Selection } from "../lib/variants.js";
+import type { Product } from "../tools/render-carousel.js";
+import { VariantPicker } from "./variant-picker";
+
+// A sparse catalog: {black,40}, {black,42}, {white,40} exist — but not
+// {white,42}. Picking "White" therefore disables "42".
+function variant(
+  id: string,
+  color: string,
+  size: string,
+): Product["variants"][number] {
+  return {
+    id,
+    selection: { color, size },
+    title: `Sneaker ${color} ${size}`,
+    price: { amount: 120, currency: "EUR" },
+    media: [],
+    attributes: [],
+  };
+}
+
+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"),
+    variant("s-w-40", "white", "40"),
+  ],
+  card: { title: "Sneaker", media: [], attributes: [] },
+};
+
+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,82 @@
+import { text } from "../design/tokens";
+import { cx } from "../lib/cx";
+import { type Selection, selectableValues } from "../lib/variants.js";
+import type { Product } from "../tools/render-carousel.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 and resolves the client's choices against
+ * the product's SPARSE variant list. Values with no surviving variant (given
+ * the other choices) are disabled, not hidden. Selecting a value that strands an
+ * earlier choice drops that choice so the selection stays reachable.
+ *
+ * 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) {
+  function choose(axisId: string, valueId: string) {
+    const next: Selection = { ...selection, [axisId]: valueId };
+    // Repair: drop any other-axis choice the new pick just made unreachable.
+    for (const option of product.options) {
+      if (option.id === axisId) {
+        continue;
+      }
+      const chosen = next[option.id];
+      if (
+        chosen != null &&
+        !selectableValues(product, option.id, next).has(chosen)
+      ) {
+        delete next[option.id];
+      }
+    }
+    onChange(next);
+  }
+
+  return (
+    <div className={styles.picker}>
+      {product.options.map((option) => {
+        // A single-value axis is not a choice; skip it.
+        if (option.values.length <= 1) {
+          return null;
+        }
+        const reachable = selectableValues(product, option.id, selection);
+        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}
+                  disabled={!reachable.has(value.id)}
+                  onSelect={() => choose(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",
+});

package/templates/ecom/src/components/view-frame.tsx

@@ -0,0 +1,27 @@
+import type { HTMLAttributes } from "react";
+import { useLayout } from "skybridge/web";
+import { darkTheme, lightTheme } from "../design/tokens";
+import { cx } from "../lib/cx";
+import { viewFrame } from "./view-frame.css";
+
+/**
+ * ViewFrame: the top-level wrapper every view mounts inside. It activates the
+ * design system by applying the active theme class (which sets the CSS
+ * variables the color contract declares) and paints the base surface + font +
+ * content color so descendants inherit from the DS instead of the host page.
+ *
+ * It follows the host theme via useLayout(). To lock the widget to one palette
+ * (e.g. always light), drop useLayout and hardcode the theme class.
+ *
+ * Keep view entry files thin: render <ViewFrame> at the root and let this carry
+ * the theme + base-style boilerplate.
+ */
+type ViewFrameProps = HTMLAttributes<HTMLDivElement>;
+
+export function ViewFrame({ className, ...rest }: ViewFrameProps) {
+  const { theme } = useLayout();
+  const themeClass = theme === "dark" ? darkTheme : lightTheme;
+
+  return <div {...rest} className={cx(themeClass, viewFrame, className)} />;
+}
+ViewFrame.displayName = "ViewFrame";

package/templates/ecom/src/config.ts

@@ -0,0 +1,12 @@
+// App-wide tuning knobs, shared by the server prompt and the tools.
+
+// @todo: minimum number of searches the model runs before rendering. Feeds the
+// prompts to enforce multi-call exploration; raise for deeper results.
+export const MIN_SEARCH_ITERATIONS = 2;
+
+// @todo: the maximum number of products the carousel shows.
+export const CAROUSEL_MAX_SIZE = 6;
+
+// A "min-max" string (e.g. "3-6") derived from CAROUSEL_MAX_SIZE, interpolated
+// into the prompts to tell the model how many products to curate toward.
+export const CAROUSEL_RANGE = `${Math.ceil(CAROUSEL_MAX_SIZE / 2)}-${CAROUSEL_MAX_SIZE}`;

package/templates/ecom/src/design/contract.css.ts

@@ -0,0 +1,39 @@
+import { createThemeContract } from "@vanilla-extract/css";
+
+/**
+ * Semantic color contract. Every field must be satisfied by both
+ * themes/light.css.ts and themes/dark.css.ts: TypeScript errors on drift.
+ *
+ * Adding a field here forces both themes to set a value. The compiler is the
+ * enforcement mechanism that keeps light and dark coherent.
+ *
+ * @todo: add or remove semantic slots to fit your UI. Keep names intent-based
+ * (surface.subtle, content.intense), not literal (grey100): the point is that
+ * components reference meaning, and the theme decides the hex.
+ */
+export const colors = createThemeContract({
+  surface: {
+    extraLight: null,
+    light: null,
+    subtle: null,
+    intense: null,
+  },
+  content: {
+    intense: null,
+    subtle: null,
+    invertIntense: null,
+    invertSubtle: null,
+  },
+  border: {
+    thin: null,
+    subtle: null,
+    intense: null,
+  },
+  common: {
+    accent: null,
+    invertAccent: null,
+    highlight: null,
+    error: null,
+    success: null,
+  },
+});