@spindlecommerce/storefront-react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The SpindleCommerce authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @spindlecommerce/storefront-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React bindings for [SpindleCommerce](https://spindlecommerce.com) storefronts, on [`@spindlecommerce/storefront-client`](https://www.npmjs.com/package/@spindlecommerce/storefront-client).
+
+**Page builder content.** One component per code, with a context of your own. Components may be async Server Components.
+
+```tsx
+import { createRenderer, type NodeProps } from "@spindlecommerce/storefront-react";
+
+type Own = { tone: "light" | "dark" };
+
+const { RenderNode, contextFor } = createRenderer<Own>({
+  components: { hero: Hero, rich_text: RichText },
+  fallback: ({ node }) => null, // codes the storefront doesn't know yet
+});
+
+function Hero({ node, ctx }: NodeProps<HeroNode, Own>) {
+  return <section {...ctx.edit.node(node)}>{ctx.renderBlocks(node.fields.actions)}</section>;
+}
+
+const ctx = contextFor(page, draft, { tone: "light" });
+page.content.fields.sections.map((section) => <RenderNode key={section.id} node={section} ctx={ctx} />);
+```
+
+`spindle-storefront components types` ([`@spindlecommerce/storefront-cli`](https://www.npmjs.com/package/@spindlecommerce/storefront-cli)) generates the node types, such as `HeroNode`.
+
+**Variant pickers.** `useVariantSelection(variants)`, from `@spindlecommerce/storefront-react/client`, returns `selection`, `variant`, `choose(attribute, value)` and `available(attribute, value)`.

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import { type Selection } from "@spindlecommerce/storefront-client";
+type Variant = {
+    isAvailable: boolean;
+    selectedOptions: {
+        attribute: string;
+        value: string;
+    }[];
+};
+/**
+ * The shopper's options, starting from the first variant in stock. `choose` keeps the other
+ * choices when that combination exists, and returns the variant chosen.
+ */
+export declare const useVariantSelection: <V extends Variant>(variants: V[]) => {
+    selection: Selection;
+    variant: V | undefined;
+    choose: (attribute: string, value: string) => V | undefined;
+    available: (attribute: string, value: string) => boolean;
+};
+export {};

package/dist/client.js

@@ -0,0 +1,19 @@
+"use client";
+import { chooseValue, inStock, selectionOf, variantFor } from "@spindlecommerce/storefront-client";
+import { useState } from "react";
+/**
+ * The shopper's options, starting from the first variant in stock. `choose` keeps the other
+ * choices when that combination exists, and returns the variant chosen.
+ */
+export const useVariantSelection = (variants) => {
+    const [selection, setSelection] = useState(() => selectionOf(variants.find((v) => v.isAvailable) ?? variants[0]));
+    const variant = variants.length === 1 ? variants[0] : variantFor(variants, selection);
+    const choose = (attribute, value) => {
+        const next = chooseValue(variants, selection, attribute, value);
+        setSelection(next.selection);
+        return next.variant;
+    };
+    /** Whether choosing this value, keeping the other choices, gives a variant in stock. */
+    const available = (attribute, value) => inStock(variants, selection, attribute, value);
+    return { selection, variant, choose, available };
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { createRenderer, type NodeProps, type RenderContext, type Renderer } from "./renderer.tsx";

package/dist/index.js

@@ -0,0 +1 @@
+export { createRenderer } from "./renderer.js";

package/dist/renderer.d.ts

@@ -0,0 +1,37 @@
+import { type CategoryLink, type ContentNode, type Editable, type ProductSummary } from "@spindlecommerce/storefront-client";
+import type { ReactNode } from "react";
+/** What every component gets besides its node. `X` is the storefront's own context. */
+export type RenderContext<X extends object = object> = X & {
+    /** Visual editing attributes (empty outside draft mode). */
+    edit: Editable;
+    draft: boolean;
+    /** Objects the document refers to by global id. */
+    products: ReadonlyMap<string, ProductSummary>;
+    categories: ReadonlyMap<string, CategoryLink>;
+    /** Renders a blocks field's nodes, optionally with a changed context. */
+    renderBlocks: (nodes: readonly ContentNode[], overrides?: Partial<X>) => ReactNode;
+};
+export type NodeProps<N, X extends object = object> = {
+    node: N;
+    ctx: RenderContext<X>;
+};
+/** A component for one code. Server Components may be async. */
+export type Renderer<N, X extends object = object> = (props: NodeProps<N, X>) => ReactNode | Promise<ReactNode>;
+type Document = {
+    references: {
+        products: ProductSummary[];
+        categories: CategoryLink[];
+    };
+};
+/**
+ * Renders builder content with one component per code. `fallback` renders codes without one, such
+ * as a component added in the admin after the storefront was built.
+ */
+export declare const createRenderer: <X extends object>(renderers: {
+    components: Partial<Record<string, Renderer<never, X>>>;
+    fallback: Renderer<ContentNode, X>;
+}) => {
+    RenderNode: ({ node, ctx }: NodeProps<ContentNode, X>) => import("react").JSX.Element;
+    contextFor: (document: Document, draft: boolean, own: X) => RenderContext<X>;
+};
+export {};

package/dist/renderer.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { editable } from "@spindlecommerce/storefront-client";
+/**
+ * Renders builder content with one component per code. `fallback` renders codes without one, such
+ * as a component added in the admin after the storefront was built.
+ */
+export const createRenderer = (renderers) => {
+    function RenderNode({ node, ctx }) {
+        // The API delivers fields in the shape the component's generated type describes.
+        const Component = (renderers.components[node.component] ?? renderers.fallback);
+        return _jsx(Component, { node: node, ctx: ctx });
+    }
+    const withRenderer = (base) => {
+        const ctx = {
+            ...base,
+            renderBlocks: (nodes, overrides) => {
+                const child = overrides ? withRenderer({ ...base, ...overrides }) : ctx;
+                return nodes.map((node) => _jsx(RenderNode, { node: node, ctx: child }, node.id));
+            },
+        };
+        return ctx;
+    };
+    /** The context for one document: a page, a template, the header or the footer. */
+    const contextFor = (document, draft, own) => withRenderer({
+        ...own,
+        edit: editable(draft),
+        draft,
+        products: new Map(document.references.products.map((p) => [p.id, p])),
+        categories: new Map(document.references.categories.map((c) => [c.id, c])),
+    });
+    return { RenderNode, contextFor };
+};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@spindlecommerce/storefront-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "React bindings for SpindleCommerce storefronts: render page-builder content and pick variants.",
+  "keywords": [
+    "spindlecommerce",
+    "storefront"
+  ],
+  "homepage": "https://github.com/spindlecommerce/storefront-sdk/tree/main/packages/storefront-react#readme",
+  "bugs": "https://github.com/spindlecommerce/storefront-sdk/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spindlecommerce/storefront-sdk.git",
+    "directory": "packages/storefront-react"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@spindlecommerce/storefront-client": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "react": "19.3.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }