create-skybridge 0.0.0-dev.7914624 → 0.0.0-dev.793efe5

package/templates/ecom/src/catalog/shopify.ts

@@ -0,0 +1,264 @@
+import type { SearchInput } from "../tools/search-products.js";
+import type {
+  Option,
+  Price,
+  Product,
+  SearchResult,
+  Spec,
+  Variant,
+} from "../types.js";
+
+// Shopify Storefront API provider. To use it:
+//   1. re-export this module from `./index.js` instead of `./mock.js`
+//   2. set SHOPIFY_STORE_DOMAIN and SHOPIFY_STOREFRONT_TOKEN in .env
+//   3. uncomment the `csp` block in `src/tools/render-carousel.ts` with
+//      `https://cdn.shopify.com` and your store domain
+//
+// Product ids are Shopify handles, not GIDs: stable, readable, and far cheaper
+// in model context than `gid://shopify/Product/8123456789`.
+
+const API_VERSION = "2026-07";
+const PAGE_SIZE = 20;
+
+// Only the fields this app renders. Options are derived from the variants'
+// `selectedOptions`, so the product-level `options` field is not queried.
+const PRODUCT_FIELDS = `
+fragment ProductFields on Product {
+  handle
+  title
+  description
+  vendor
+  productType
+  onlineStoreUrl
+  availableForSale
+  priceRange { minVariantPrice { amount currencyCode } }
+  images(first: 10) { nodes { url } }
+  variants(first: 100) {
+    nodes {
+      id
+      title
+      availableForSale
+      price { amount currencyCode }
+      image { url }
+      selectedOptions { name value }
+    }
+  }
+}`;
+
+type ShopifyMoney = { amount: string; currencyCode: string };
+
+type ShopifyProduct = {
+  handle: string;
+  title: string;
+  description: string;
+  vendor: string;
+  productType: string;
+  onlineStoreUrl: string | null;
+  availableForSale: boolean;
+  priceRange: { minVariantPrice: ShopifyMoney };
+  images: { nodes: { url: string }[] };
+  variants: {
+    nodes: {
+      id: string;
+      title: string;
+      availableForSale: boolean;
+      price: ShopifyMoney;
+      image: { url: string } | null;
+      selectedOptions: { name: string; value: string }[];
+    }[];
+  };
+};
+
+async function storefront(query: string, variables: Record<string, unknown>) {
+  const domain = process.env.SHOPIFY_STORE_DOMAIN;
+  const token = process.env.SHOPIFY_STOREFRONT_TOKEN;
+  if (!domain || !token) {
+    throw new Error(
+      "Missing SHOPIFY_STORE_DOMAIN or SHOPIFY_STOREFRONT_TOKEN in the environment.",
+    );
+  }
+
+  const response = await fetch(
+    `https://${domain}/api/${API_VERSION}/graphql.json`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Shopify-Storefront-Access-Token": token,
+      },
+      body: JSON.stringify({ query, variables }),
+    },
+  );
+  if (!response.ok) {
+    throw new Error(`Shopify ${response.status}: ${await response.text()}`);
+  }
+
+  const { data, errors } = await response.json();
+  if (errors) {
+    throw new Error(`Shopify: ${JSON.stringify(errors)}`);
+  }
+  return data;
+}
+
+function toPrice(money: ShopifyMoney): Price {
+  return { amount: Number(money.amount), currency: money.currencyCode };
+}
+
+// @todo: Shopify has no generic "specs" field. Vendor and product type are a
+// starting point; swap in your own metafields once you know their namespace.
+function toSpecs(node: ShopifyProduct): Spec[] {
+  const specs: Spec[] = [];
+  if (node.vendor) {
+    specs.push({ label: "Brand", value: node.vendor });
+  }
+  if (node.productType) {
+    specs.push({ label: "Type", value: node.productType });
+  }
+  return specs;
+}
+
+function toProduct(node: ShopifyProduct): Product {
+  const specs = toSpecs(node);
+  const images: string[] = [];
+  for (const image of node.images.nodes) {
+    images.push(image.url);
+  }
+
+  // Walk the variants once, building both the variants and the axes they vary
+  // on. Shopify option names are used as-is for ids, so a variant's
+  // `selectedOptions` maps straight onto `selection`.
+  const options: Option[] = [];
+  const variants: Variant[] = [];
+  for (const variant of node.variants.nodes) {
+    const selection: Record<string, string> = {};
+    for (const selected of variant.selectedOptions) {
+      selection[selected.name] = selected.value;
+
+      let option: Option | undefined;
+      for (const candidate of options) {
+        if (candidate.id === selected.name) {
+          option = candidate;
+          break;
+        }
+      }
+      if (!option) {
+        option = { id: selected.name, label: selected.name, values: [] };
+        options.push(option);
+      }
+
+      let known = false;
+      for (const value of option.values) {
+        if (value.id === selected.value) {
+          known = true;
+          break;
+        }
+      }
+      if (!known) {
+        option.values.push({
+          id: selected.value,
+          label: selected.value,
+          media: variant.image?.url,
+        });
+      }
+    }
+
+    variants.push({
+      id: variant.id,
+      selection,
+      title: variant.title === "Default Title" ? node.title : variant.title,
+      description: node.description,
+      price: toPrice(variant.price),
+      media: variant.image ? [variant.image.url] : images,
+      url: node.onlineStoreUrl ?? undefined,
+      outOfStock: !variant.availableForSale,
+      specs,
+    });
+  }
+
+  // A single-variant product has no axes to pick from.
+  if (variants.length < 2) {
+    options.length = 0;
+  }
+
+  return {
+    id: node.handle,
+    options,
+    variants,
+    card: {
+      title: node.title,
+      description: node.description,
+      price: toPrice(node.priceRange.minVariantPrice),
+      media: images,
+      url: node.onlineStoreUrl ?? undefined,
+      outOfStock: !node.availableForSale,
+      specs,
+    },
+  };
+}
+
+export async function search({
+  keyword,
+  sort,
+  priceRange,
+}: SearchInput): Promise<SearchResult> {
+  // Shopify's search DSL: a bare term matches title, vendor, type and tags;
+  // extra clauses narrow it. @todo: add your own (`tag:`, `product_type:`…).
+  let query = keyword;
+  if (priceRange) {
+    const [min, max] = priceRange.split("-");
+    query += ` variants.price:>=${min} variants.price:<=${max}`;
+  }
+
+  const data = await storefront(
+    `${PRODUCT_FIELDS}
+    query Search($query: String!, $sortKey: ProductSortKeys!, $reverse: Boolean!, $first: Int!) {
+      products(query: $query, sortKey: $sortKey, reverse: $reverse, first: $first) {
+        nodes { ...ProductFields }
+      }
+    }`,
+    {
+      query,
+      sortKey: sort ? "PRICE" : "RELEVANCE",
+      reverse: sort === "price-desc",
+      first: PAGE_SIZE,
+    },
+  );
+
+  const products: Product[] = [];
+  for (const node of data.products.nodes) {
+    products.push(toProduct(node));
+  }
+  // Storefront paginates by cursor and reports no total, so both counts are
+  // left out rather than faked.
+  return { products };
+}
+
+export async function getProducts(ids: string[]): Promise<Product[]> {
+  // One aliased lookup per handle, so the response comes back in the order the
+  // model asked for.
+  const declarations: string[] = [];
+  const fields: string[] = [];
+  const variables: Record<string, string> = {};
+  for (let index = 0; index < ids.length; index++) {
+    declarations.push(`$h${index}: String!`);
+    fields.push(`p${index}: product(handle: $h${index}) { ...ProductFields }`);
+    variables[`h${index}`] = ids[index];
+  }
+
+  const data = await storefront(
+    `${PRODUCT_FIELDS}
+    query Products(${declarations.join(", ")}) {
+      ${fields.join("\n      ")}
+    }`,
+    variables,
+  );
+
+  const products: Product[] = [];
+  for (let index = 0; index < ids.length; index++) {
+    const node = data[`p${index}`];
+    if (node) {
+      products.push(toProduct(node));
+    }
+  }
+  return products;
+}

package/templates/ecom/src/components/chip.css.ts

@@ -2,8 +2,9 @@ import { style } from "@vanilla-extract/css";
 import { recipe } from "@vanilla-extract/recipes";
 import { colors, primitives } from "../design/tokens";
 
-// A selectable pill used for option values (sizes, colors…). `selected` and
-// `disabled` are driven by the variant picker from the sparse variant list.
+// A selectable pill used for option values (sizes, colors…). `selected`,
+// `outOfStock` and `nonExistent` are driven by the variant picker from the
+// sparse variant list.
 // @todo: tune the chip to your brand (radius, borders, selected treatment).
 export const chip = recipe({
   base: {
@@ -32,18 +33,24 @@ export const chip = recipe({
       },
       false: {},
     },
-    disabled: {
-      // Unreachable value given the other choices: greyed and struck, but kept
-      // visible so the client sees the axis exists (never silently hidden).
+    outOfStock: {
+      // Struck but still clickable; the buy CTA carries the state.
       true: {
-        cursor: "not-allowed",
-        opacity: 0.4,
+        color: colors.content.subtle,
         textDecoration: "line-through",
       },
       false: {},
     },
+    nonExistent: {
+      // Faded and non-interactive, distinct from sold out above.
+      true: {
+        opacity: 0.35,
+        cursor: "default",
+      },
+      false: {},
+    },
   },
-  defaultVariants: { selected: false, disabled: false },
+  defaultVariants: { selected: false, outOfStock: false, nonExistent: false },
 });
 
 // Small color/material swatch shown before the label on image chips.

package/templates/ecom/src/components/chip.stories.tsx

@@ -14,7 +14,8 @@ export const States = () => (
   <div style={row}>
     <Chip label="M" />
     <Chip label="L" selected />
-    <Chip label="XL" disabled />
+    <Chip label="XL" outOfStock /> {/* exists, sold out: clickable */}
+    <Chip label="XXL" nonExistent /> {/* combination does not exist */}
   </div>
 );
 

package/templates/ecom/src/components/chip.tsx

@@ -3,7 +3,11 @@ import * as styles from "./chip.css";
 type ChipProps = {
   label: string;
   selected?: boolean;
-  disabled?: boolean;
+  // Exists but sold out: struck-through and greyed, still clickable
+  outOfStock?: boolean;
+  // The combination does not exist at all (hole in the variant matrix):
+  // faded and non-interactive
+  nonExistent?: boolean;
   onSelect?: () => void;
   // Optional swatch image (e.g. one per color); omit for a plain text chip.
   media?: string;
@@ -12,25 +16,29 @@ type ChipProps = {
 /**
  * One option value as a selectable pill. Rendered as a `radio` inside the
  * variant picker's `radiogroup`; the picker owns selection state and passes
- * `selected`/`disabled` computed from the sparse variant list.
+ * `selected`/`outOfStock`/`nonExistent` computed from the sparse variant list.
+ * An out-of-stock chip stays operable: aria-disabled announces the state to
+ * assistive tech without blocking activation. A nonexistent chip is natively
+ * disabled: the combination cannot be composed.
  */
 export function Chip({
   label,
   selected,
-  disabled,
+  outOfStock,
+  nonExistent,
   onSelect,
   media,
 }: ChipProps) {
   return (
-    // biome-ignore lint/a11y/useSemanticElements: custom radio; a styled button carries the swatch and disabled state a native radio cannot, inside the picker radiogroup.
+    // biome-ignore lint/a11y/useSemanticElements: custom radio; a styled button carries the swatch and availability states a native radio cannot, inside the picker radiogroup.
     <button
       type="button"
       role="radio"
       aria-checked={selected ?? false}
-      aria-disabled={disabled ?? false}
-      disabled={disabled}
-      className={styles.chip({ selected, disabled })}
-      onClick={disabled ? undefined : onSelect}
+      aria-disabled={outOfStock ?? false}
+      disabled={nonExistent ?? false}
+      className={styles.chip({ selected, outOfStock, nonExistent })}
+      onClick={onSelect}
     >
       {media ? (
         <img className={styles.swatch} src={media} alt="" draggable={false} />

package/templates/ecom/src/components/image-gallery.css.ts

@@ -50,8 +50,8 @@ globalStyle(`${track}::-webkit-scrollbar`, { display: "none" });
 export const slide = style({
   flex: "0 0 100%",
   scrollSnapAlign: "start",
-  // Reserve a square box so images load without shifting the page. @todo: match
-  // the carousel card's aspect ratio / fit if you changed them there.
+  // Reserve the box so images load without shifting the page. @todo: use the
+  // same aspect ratio / fit you chose for the card from the real image sample.
   aspectRatio: "1",
   backgroundColor: colors.surface.subtle,
 });

package/templates/ecom/src/components/image-gallery.tsx

@@ -7,7 +7,8 @@ import * as styles from "./image-gallery.css";
 // breakpoint); swipe-only when false. Off by default. When true, tune the rail
 // width / thumb size in image-gallery.css.ts. The rail is capped to the image
 // height and scrolls its excess; deferred polish (add if it earns it): an
-// edge-fade mask and auto-centering the active thumb.
+// edge-fade mask and auto-centering the active thumb. Progress bar is hidden
+// when thumbnail rail is active.
 const THUMBNAIL_RAIL: boolean = false;
 
 function Chevron({ direction }: { direction: "left" | "right" }) {
@@ -32,9 +33,9 @@ function Chevron({ direction }: { direction: "left" | "right" }) {
 /**
  * Product image gallery: a native scroll-snap track with prev/next chevrons and
  * a progress bar; the current index is read from scroll position (no library).
- * With the rail on, a desktop thumbnail rail is added as a second controller of
- * the SAME track (shared index, click = scroll). Mobile is always the swipe
- * track.
+ * With the rail on, a desktop thumbnail rail controls the SAME track (shared
+ * index, click = scroll), and the progress bar is hidden where the rail shows
+ * (desktop) so the two never appear together. Mobile is always the swipe track.
  */
 export function ImageGallery({ media, alt }: { media: string[]; alt: string }) {
   const labels = useLabels();

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

@@ -52,20 +52,24 @@ export const cardButton = style({
 
 export const imageBox = style({
   position: "relative",
+  // @todo: aspect ratio for product imagery. Do not assume: fetch a sample of
+  // the catalog's real images and pick from what they actually are (square,
+  // portrait for fashion, landscape…). Keep it consistent with the gallery.
   aspectRatio: "1",
   overflow: "hidden",
   borderRadius: primitives.radius.m,
-  // Stage behind the product image. @todo: pick the surface token that suits
-  // your imagery (a neutral grey for transparent cutouts, `extraLight`/white
-  // for full-bleed photos).
+  // Stage behind the product image. @todo: pick the surface from that same image
+  // sample (a neutral grey for transparent cutouts, `extraLight`/white for
+  // full-bleed photos).
   backgroundColor: colors.surface.subtle,
 });
 
 export const image = style({
   width: "100%",
   height: "100%",
-  // @todo: `contain` never crops; switch to `cover` for uniform, bleed-friendly
-  // cutout images.
+  // @todo: object-fit, from that same image sample: `contain` never crops (good
+  // for cutouts or mixed ratios); `cover` fills for a uniform grid (good for
+  // consistent, bleed-friendly photos).
   objectFit: "contain",
   display: "block",
   // Keep image drag from hijacking the swipe/scroll gesture.

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

@@ -30,8 +30,8 @@ export function ProductCard({
 }: 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.
+  // 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 })}>
@@ -66,8 +66,9 @@ export function ProductCard({
             {formatPrice(price, locale)}
           </p>
         ) : null}
-        {/* @todo: extra fields. Render catalog-specific data here, e.g. from the
-            product's `attributes`: ratings, discounts, tags, badges. */}
+        {/* @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>
   );

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

@@ -1,14 +1,16 @@
 import { useState } from "react";
 import { initialSelection, type Selection } from "../lib/variants.js";
-import type { Product } from "../tools/render-carousel.js";
+import type { Product } from "../types.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".
+// 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,
@@ -16,7 +18,8 @@ function variant(
     title: `Sneaker ${color} ${size}`,
     price: { amount: 120, currency: "EUR" },
     media: [],
-    attributes: [],
+    specs: [],
+    outOfStock,
   };
 }
 
@@ -42,10 +45,10 @@ const PRODUCT: Product = {
   ],
   variants: [
     variant("s-b-40", "black", "40"),
-    variant("s-b-42", "black", "42"),
+    variant("s-b-42", "black", "42", true),
     variant("s-w-40", "white", "40"),
   ],
-  card: { title: "Sneaker", media: [], attributes: [] },
+  card: { title: "Sneaker", media: [], specs: [] },
 };
 
 export const Contingency = () => {

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

@@ -1,7 +1,7 @@
 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 { 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";
 
@@ -12,10 +12,11 @@ type VariantPickerProps = {
 };
 
 /**
- * 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.
+ * 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
@@ -26,32 +27,14 @@ export function VariantPicker({
   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) {
+        // Empty map: the axis does not apply to the current configuration.
+        const states = axisStates(product, option.id, selection);
+        if (states.size === 0) {
           return null;
         }
-        const reachable = selectableValues(product, option.id, selection);
         return (
           <div
             key={option.id}
@@ -69,8 +52,13 @@ export function VariantPicker({
                   label={value.label}
                   media={value.media}
                   selected={selection[option.id] === value.id}
-                  disabled={!reachable.has(value.id)}
-                  onSelect={() => choose(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>

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

@@ -1,5 +1,5 @@
 import type { HTMLAttributes } from "react";
-import { useLayout } from "skybridge/web";
+import { useUser } from "skybridge/web";
 import { darkTheme, lightTheme } from "../design/tokens";
 import { cx } from "../lib/cx";
 import { viewFrame } from "./view-frame.css";
@@ -10,8 +10,8 @@ import { viewFrame } from "./view-frame.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.
+ * It follows the host theme via useUser(). To lock the widget to one palette
+ * (e.g. always light), drop useUser and hardcode the theme class.
  *
  * Keep view entry files thin: render <ViewFrame> at the root and let this carry
  * the theme + base-style boilerplate.
@@ -19,7 +19,7 @@ import { viewFrame } from "./view-frame.css";
 type ViewFrameProps = HTMLAttributes<HTMLDivElement>;
 
 export function ViewFrame({ className, ...rest }: ViewFrameProps) {
-  const { theme } = useLayout();
+  const { theme } = useUser();
   const themeClass = theme === "dark" ? darkTheme : lightTheme;
 
   return <div {...rest} className={cx(themeClass, viewFrame, className)} />;

package/templates/ecom/src/i18n.ts

@@ -8,14 +8,15 @@ import { useUser } from "skybridge/web";
 const LABELS = {
   en: {
     outOfStock: "Out of stock",
+    combinationUnavailable: "Combination unavailable",
     noProducts: "No products to show.",
     carousel: "carousel",
     products: "Products",
     previous: "Previous",
     next: "Next",
     // Detail view.
+    reference: "Ref.",
     viewOnSite: "View on site",
-    selectOptions: "Select options",
     priceOnRequest: "Price on request",
     specifications: "Specifications",
     readMore: "Read more",

package/templates/ecom/src/index.ts

@@ -0,0 +1,3 @@
+import { app } from "./server.js";
+
+export default await app.run();