create-skybridge 0.0.0-dev.356dbec → 0.0.0-dev.35a7b38

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,
+  },
+});

package/templates/ecom/src/design/fonts.css

@@ -0,0 +1,15 @@
+/* @todo: add your brand's @font-face rules here, then point
+   primitives.font.family.primary at the family name. Drop the font files in
+   public/fonts/ so they are served under /assets/fonts/.
+
+   The template ships with the system font stack, which needs no @font-face,
+   so this file is empty by default. Example:
+
+   @font-face {
+     font-family: "My Brand";
+     font-style: normal;
+     font-weight: 400;
+     font-display: block;
+     src: url("/assets/fonts/MyBrand-Regular.woff2") format("woff2");
+   }
+*/

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

@@ -0,0 +1,101 @@
+import { createGlobalTheme } from "@vanilla-extract/css";
+
+/**
+ * Non-mode-aware design primitives: the raw scales every theme and recipe
+ * draws from. Values here are brand-neutral placeholders.
+ *
+ * @todo: replace these with your brand's real tokens (ideally extracted from
+ * a Figma design file). Change values, not the shape: the space/radius/font
+ * keys are referenced by sprinkles.css.ts and the recipes. Nothing outside
+ * this file should hard-code a hex, size, or spacing value.
+ */
+export const primitives = createGlobalTheme(":root", {
+  // Spacing scale (4px based). Used for padding, margin, and gap via sprinkles.
+  space: {
+    none: "0",
+    "5xs": "2px",
+    "4xs": "4px",
+    "3xs": "8px",
+    "2xs": "12px",
+    xs: "16px",
+    s: "24px",
+    m: "32px",
+    l: "40px",
+    xl: "48px",
+    "2xl": "56px",
+    "3xl": "64px",
+  },
+  radius: {
+    none: "0",
+    xs: "2px",
+    s: "4px",
+    m: "8px",
+    l: "16px",
+    xl: "32px",
+    full: "999px",
+  },
+  font: {
+    family: {
+      // @todo: swap in your brand font (add its @font-face to fonts.css). The
+      // system stack is the zero-asset default.
+      primary:
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+    },
+    weight: {
+      regular: "400",
+      medium: "500",
+      semibold: "600",
+      bold: "700",
+    },
+    size: {
+      xs: "12px",
+      s: "14px",
+      m: "16px",
+      l: "20px",
+      xl: "24px",
+      "2xl": "32px",
+      "3xl": "40px",
+    },
+    lineHeight: {
+      tight: "1.25",
+      normal: "1.5",
+    },
+    letterSpacing: {
+      default: "0",
+      wide: "0.5px",
+    },
+  },
+  stroke: {
+    thin: "1px",
+    medium: "1.5px",
+    thick: "2px",
+  },
+  // Raw greyscale ramp. Themes pick from these for surface/content/border.
+  grey: {
+    white: "#ffffff",
+    "50": "#f8f8f8",
+    "100": "#f2f2f2",
+    "200": "#e1e1e1",
+    "300": "#b4b4b4",
+    "400": "#929292",
+    "500": "#727272",
+    "600": "#636363",
+    "700": "#4c4c4c",
+    "800": "#333333",
+    "900": "#1a1a1a",
+    black: "#000000",
+  },
+  // @todo: your brand accent ramp (call-to-action, links, highlights). Steps
+  // named by lightness, like the grey ramp; each theme picks the shade that
+  // reads well on its surface (light mode the darker step, dark mode the
+  // lighter one). Add more steps as needed.
+  accent: {
+    "400": "#7ba0f5",
+    "600": "#3b6cf0",
+  },
+  // Status colors, shared across themes.
+  status: {
+    error: "#c53929",
+    success: "#5c7d0b",
+  },
+});

package/templates/ecom/src/design/recipes/typography.css.ts

@@ -0,0 +1,75 @@
+import { recipe } from "@vanilla-extract/recipes";
+import { primitives } from "../primitives.css";
+
+/**
+ * The one text style, driven by variants. Call it as:
+ *   text({ style: "headingM", weight: "medium" })
+ *
+ * `style` picks the size/line-height pair; `weight` picks the font weight.
+ * This is the workhorse recipe: use it for all typography rather than setting
+ * fontSize/fontWeight by hand.
+ *
+ * @todo: adjust the styles to your type scale. Add a component recipe (button,
+ * tag, card) only when a component has real variants; otherwise style with
+ * sprinkles or a `style()` block.
+ */
+export const text = recipe({
+  base: {
+    fontFamily: primitives.font.family.primary,
+    letterSpacing: primitives.font.letterSpacing.default,
+    fontWeight: primitives.font.weight.regular,
+    margin: 0,
+  },
+  variants: {
+    style: {
+      display: {
+        fontSize: primitives.font.size["3xl"],
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      headingL: {
+        fontSize: primitives.font.size["2xl"],
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      headingM: {
+        fontSize: primitives.font.size.xl,
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      headingS: {
+        fontSize: primitives.font.size.l,
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      bodyM: {
+        fontSize: primitives.font.size.m,
+        lineHeight: primitives.font.lineHeight.normal,
+      },
+      bodyS: {
+        fontSize: primitives.font.size.s,
+        lineHeight: primitives.font.lineHeight.normal,
+      },
+      labelM: {
+        fontSize: primitives.font.size.m,
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      labelS: {
+        fontSize: primitives.font.size.s,
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      overline: {
+        fontSize: primitives.font.size.xs,
+        lineHeight: primitives.font.lineHeight.normal,
+        letterSpacing: primitives.font.letterSpacing.wide,
+        textTransform: "uppercase",
+      },
+    },
+    weight: {
+      regular: { fontWeight: primitives.font.weight.regular },
+      medium: { fontWeight: primitives.font.weight.medium },
+      semibold: { fontWeight: primitives.font.weight.semibold },
+      bold: { fontWeight: primitives.font.weight.bold },
+    },
+  },
+  defaultVariants: {
+    style: "bodyM",
+    weight: "regular",
+  },
+});