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

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");
+   }
+*/

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

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

@@ -0,0 +1,128 @@
+import { createSprinkles, defineProperties } from "@vanilla-extract/sprinkles";
+import { colors } from "./contract.css";
+import { primitives } from "./primitives.css";
+
+/**
+ * Atomic style props built on the primitives + color contract. Use sprinkles
+ * for one-off layout/spacing/color on an element, e.g.
+ *   sprinkles({ display: "flex", gap: "s", color: "intense" })
+ *
+ * Structural component styling belongs in a co-located `.css.ts` `style()`
+ * block; sprinkles is the thin glue layer on top.
+ */
+
+const spaceProperties = defineProperties({
+  properties: {
+    padding: primitives.space,
+    paddingTop: primitives.space,
+    paddingRight: primitives.space,
+    paddingBottom: primitives.space,
+    paddingLeft: primitives.space,
+    margin: primitives.space,
+    marginTop: primitives.space,
+    marginRight: primitives.space,
+    marginBottom: primitives.space,
+    marginLeft: primitives.space,
+    gap: primitives.space,
+    rowGap: primitives.space,
+    columnGap: primitives.space,
+  },
+  shorthands: {
+    p: ["padding"],
+    pt: ["paddingTop"],
+    pr: ["paddingRight"],
+    pb: ["paddingBottom"],
+    pl: ["paddingLeft"],
+    px: ["paddingLeft", "paddingRight"],
+    py: ["paddingTop", "paddingBottom"],
+    m: ["margin"],
+    mt: ["marginTop"],
+    mr: ["marginRight"],
+    mb: ["marginBottom"],
+    ml: ["marginLeft"],
+    mx: ["marginLeft", "marginRight"],
+    my: ["marginTop", "marginBottom"],
+  },
+});
+
+const colorProperties = defineProperties({
+  properties: {
+    backgroundColor: {
+      ...colors.surface,
+      accent: colors.common.accent,
+      invertAccent: colors.common.invertAccent,
+      highlight: colors.common.highlight,
+      transparent: "transparent",
+    },
+    color: {
+      ...colors.content,
+      accent: colors.common.accent,
+      invertAccent: colors.common.invertAccent,
+      highlight: colors.common.highlight,
+      error: colors.common.error,
+      success: colors.common.success,
+    },
+    borderColor: {
+      ...colors.border,
+      accent: colors.common.accent,
+      invertAccent: colors.common.invertAccent,
+      highlight: colors.common.highlight,
+      transparent: "transparent",
+    },
+  },
+});
+
+const radiusProperties = defineProperties({
+  properties: {
+    borderRadius: primitives.radius,
+    borderTopLeftRadius: primitives.radius,
+    borderTopRightRadius: primitives.radius,
+    borderBottomLeftRadius: primitives.radius,
+    borderBottomRightRadius: primitives.radius,
+  },
+});
+
+const typographyProperties = defineProperties({
+  properties: {
+    fontFamily: primitives.font.family,
+    fontWeight: primitives.font.weight,
+    fontSize: primitives.font.size,
+    lineHeight: primitives.font.lineHeight,
+    letterSpacing: primitives.font.letterSpacing,
+  },
+});
+
+const strokeProperties = defineProperties({
+  properties: {
+    borderWidth: primitives.stroke,
+  },
+});
+
+const layoutProperties = defineProperties({
+  properties: {
+    display: ["none", "flex", "inline-flex", "block", "inline-block", "grid"],
+    flexDirection: ["row", "column", "row-reverse", "column-reverse"],
+    alignItems: ["flex-start", "center", "flex-end", "stretch", "baseline"],
+    justifyContent: [
+      "flex-start",
+      "center",
+      "flex-end",
+      "space-between",
+      "space-around",
+      "space-evenly",
+    ],
+    flexWrap: ["wrap", "nowrap", "wrap-reverse"],
+    textAlign: ["left", "center", "right"],
+  },
+});
+
+export const sprinkles = createSprinkles(
+  spaceProperties,
+  colorProperties,
+  radiusProperties,
+  typographyProperties,
+  strokeProperties,
+  layoutProperties,
+);
+
+export type Sprinkles = Parameters<typeof sprinkles>[0];