create-skybridge 0.0.0-dev.ea04428 → 0.0.0-dev.ea09368

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

@@ -0,0 +1,58 @@
+import { ProductCard, ProductCardSkeleton } from "./product-card";
+
+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";
+
+const frame = { maxWidth: 220 };
+
+export const Default = () => (
+  <div style={frame}>
+    <ProductCard
+      title="Merino wool sweater"
+      price={{ amount: 129.9, currency: "EUR" }}
+      media={[IMAGE]}
+    />
+  </div>
+);
+
+export const LongTitle = () => (
+  <div style={frame}>
+    <ProductCard
+      title="Extra long product title that wraps onto two lines and then clamps"
+      price={{ amount: 1290, currency: "USD" }}
+      media={[IMAGE]}
+    />
+  </div>
+);
+
+export const NoImage = () => (
+  <div style={frame}>
+    <ProductCard
+      title="Product without an image"
+      price={{ amount: 49, currency: "EUR" }}
+    />
+  </div>
+);
+
+export const NoPrice = () => (
+  <div style={frame}>
+    <ProductCard title="Price on request" media={[IMAGE]} />
+  </div>
+);
+
+export const OutOfStock = () => (
+  <div style={frame}>
+    <ProductCard
+      title="Sold out product"
+      price={{ amount: 89, currency: "EUR" }}
+      media={[IMAGE]}
+      outOfStock
+    />
+  </div>
+);
+
+export const Skeleton = () => (
+  <div style={frame}>
+    <ProductCardSkeleton />
+  </div>
+);

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

@@ -0,0 +1,101 @@
+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 cross-fade to media[1] on hover.
+  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: extra fields. Render catalog-specific data here, e.g. from the
+            product's `attributes`: ratings, discounts, tags, badges. */}
+      </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,195 @@
+import {
+  Children,
+  type ReactNode,
+  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;
+};
+
+/**
+ * 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,
+}: ProductCarouselProps) {
+  const labels = useLabels();
+  const trackRef = useRef<HTMLElement>(null);
+  const [canScrollLeft, setCanScrollLeft] = useState(false);
+  const [canScrollRight, setCanScrollRight] = useState(false);
+
+  // Keep the latest callback in a ref so the observer effect does not
+  // re-subscribe when the parent passes a new function each render.
+  const onVisibleChangeRef = useRef(onVisibleChange);
+  onVisibleChangeRef.current = onVisibleChange;
+
+  const updateEdges = useCallback(() => {
+    const el = trackRef.current;
+    if (!el) {
+      return;
+    }
+    setCanScrollLeft(el.scrollLeft > 0);
+    setCanScrollRight(el.scrollLeft + el.clientWidth < el.scrollWidth - 1);
+  }, []);
+
+  useEffect(() => {
+    const el = trackRef.current;
+    if (!el) {
+      return;
+    }
+    updateEdges();
+    el.addEventListener("scroll", updateEdges, { passive: true });
+    const observer = new ResizeObserver(updateEdges);
+    observer.observe(el);
+    return () => {
+      el.removeEventListener("scroll", updateEdges);
+      observer.disconnect();
+    };
+  }, [updateEdges]);
+
+  // Track which cells are in view and report them (only when a consumer asks).
+  const childCount = Children.count(children);
+  // Re-subscribe when a consumer starts (or stops) passing onVisibleChange, even
+  // if the child count is unchanged; the callback itself is read via the ref.
+  const observeVisibility = onVisibleChange != null;
+  // biome-ignore lint/correctness/useExhaustiveDependencies: childCount and observeVisibility drive re-subscription; neither is read inside the effect.
+  useEffect(() => {
+    const el = trackRef.current;
+    if (!el || !observeVisibility) {
+      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);
+      onVisibleChangeRef.current?.(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, observeVisibility]);
+
+  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={trackRef}
+        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/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");
+   }
+*/