threeu-sdk 0.1.0

package/dist/session-BFDRm-KJ.d.ts

@@ -0,0 +1,94 @@
+import { B as BaseRecord, T as ThreeuHttpClient, I as Id, R as RequestOptions, L as ListParams, f as Page } from './types-DfyYnoLn.js';
+
+/**
+ * Generic CRUD resource bound to a base path and a brand scope. Each high-level
+ * resource (products, orders, ...) is a thin subclass that adds domain-specific
+ * actions. Paths are centralized so they're trivial to adjust as backend routes
+ * are confirmed.
+ */
+
+interface ResourceContext {
+    http: ThreeuHttpClient;
+    /** Brand scope applied as `platform-id` on every call (undefined = client default). */
+    brand?: Id;
+}
+declare class CrudResource<T extends BaseRecord = BaseRecord, TInput = Partial<T>> {
+    protected readonly ctx: ResourceContext;
+    protected readonly path: string;
+    constructor(ctx: ResourceContext, path: string);
+    protected opts(extra?: RequestOptions): RequestOptions;
+    list(params?: ListParams): Promise<Page<T>>;
+    iterate(params?: ListParams): AsyncGenerator<T, void, void>;
+    get(id: Id): Promise<T>;
+    create(input: TInput, options?: {
+        idempotencyKey?: string;
+    }): Promise<T>;
+    update(id: Id, input: Partial<TInput>): Promise<T>;
+    delete(id: Id): Promise<void>;
+    /** POST a custom sub-action, e.g. `action(id, "fulfill", {...})`. */
+    protected action<R = unknown>(id: Id, verb: string, body?: unknown): Promise<R>;
+}
+
+/**
+ * POS session + cart. A session captures the location/cashier context; carts are
+ * created within it and drive the add-item → discount → checkout flow.
+ * Shared by `brand.pos.session(...)` and the standalone `ThreeuPOS` client.
+ */
+
+interface PosSessionConfig {
+    locationId?: Id;
+    cashierId?: Id;
+}
+interface CartItemInput {
+    productId: Id;
+    quantity: number;
+    variantId?: Id;
+    price?: number;
+}
+interface CartDiscountInput {
+    type: "percentage" | "fixed";
+    value: number;
+    code?: string;
+}
+interface CheckoutInput {
+    method: "card" | "cash" | "wallet" | string;
+    amountTendered?: number;
+    customerId?: Id;
+}
+interface CartData {
+    id: Id;
+    [key: string]: unknown;
+}
+declare class PosCart {
+    private readonly ctx;
+    readonly id: Id;
+    private data;
+    constructor(ctx: ResourceContext, id: Id, data: CartData);
+    private opts;
+    get snapshot(): CartData;
+    addItem(item: CartItemInput): Promise<CartData>;
+    removeItem(itemId: Id): Promise<CartData>;
+    applyDiscount(discount: CartDiscountInput): Promise<CartData>;
+    checkout(input: CheckoutInput): Promise<Record<string, unknown>>;
+}
+declare class PosCartNamespace {
+    private readonly ctx;
+    private readonly config;
+    constructor(ctx: ResourceContext, config: PosSessionConfig);
+    create(): Promise<PosCart>;
+    get(id: Id): Promise<PosCart>;
+}
+declare class PosSession {
+    private readonly ctx;
+    readonly config: PosSessionConfig;
+    readonly cart: PosCartNamespace;
+    constructor(ctx: ResourceContext, config: PosSessionConfig);
+}
+/** Factory used by both the brand POS namespace and ThreeuPOS. */
+declare class PosNamespace {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    session(config?: PosSessionConfig): PosSession;
+}
+
+export { type CartData as C, type PosSessionConfig as P, type ResourceContext as R, PosSession as a, type CartDiscountInput as b, type CartItemInput as c, type CheckoutInput as d, PosCart as e, PosCartNamespace as f, PosNamespace as g, CrudResource as h };

package/dist/storefront/index.d.ts

@@ -0,0 +1,76 @@
+import { T as ThreeuHttpClient, I as Id, f as Page, d as Product, C as Collection, g as ThreeuLogger, h as ThreeuTelemetryOptions } from '../types-DfyYnoLn.js';
+
+/**
+ * @threeu/threeu/storefront — public-token storefront client.
+ *
+ *   const storefront = new ThreeuStorefront({
+ *     publicToken: import.meta.env.VITE_THREEU_PUBLIC_KEY,
+ *     brand: "my-store",
+ *   });
+ *   const products = await storefront.products.list({ collection: "featured", limit: 8 });
+ *   const cart = await storefront.cart.create();
+ *
+ * Public surface lives under `/api/marketplace/storefront/*` and resolves the
+ * brand purely from the `platform-id` header (docs/ARCHITECTURE_MAP.md §14).
+ * Safe to use in the browser — it never carries a secret token.
+ */
+
+interface ThreeuStorefrontOptions {
+    brand: Id;
+    publicToken?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    logger?: ThreeuLogger;
+    telemetry?: ThreeuTelemetryOptions;
+    timeoutMs?: number;
+}
+interface StorefrontProductParams {
+    collection?: string;
+    limit?: number;
+    page?: number;
+    search?: string;
+    [key: string]: unknown;
+}
+declare class StorefrontProducts {
+    private readonly http;
+    private readonly brand;
+    constructor(http: ThreeuHttpClient, brand: Id);
+    list(params?: StorefrontProductParams): Promise<Page<Product>>;
+    get(id: Id): Promise<Product>;
+}
+declare class StorefrontCollections {
+    private readonly http;
+    private readonly brand;
+    constructor(http: ThreeuHttpClient, brand: Id);
+    list(params?: {
+        limit?: number;
+        page?: number;
+    }): Promise<Page<Collection>>;
+}
+declare class StorefrontCart {
+    private readonly http;
+    private readonly brand;
+    constructor(http: ThreeuHttpClient, brand: Id);
+    create(): Promise<Record<string, unknown>>;
+    get(id: Id): Promise<Record<string, unknown>>;
+    addItem(id: Id, item: {
+        productId: Id;
+        quantity: number;
+    }): Promise<Record<string, unknown>>;
+}
+declare class ThreeuStorefront {
+    readonly http: ThreeuHttpClient;
+    readonly products: StorefrontProducts;
+    readonly collections: StorefrontCollections;
+    readonly cart: StorefrontCart;
+    private readonly brand;
+    constructor(options: ThreeuStorefrontOptions);
+    /** Fetch the unified storefront config (delivery, payments, theme tokens). */
+    getConfig(params?: {
+        website?: boolean;
+        pos?: boolean;
+    }): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+}
+
+export { type StorefrontProductParams, ThreeuStorefront, type ThreeuStorefrontOptions };

package/dist/storefront/index.js

@@ -0,0 +1,6 @@
+export { ThreeuStorefront } from '../chunk-6S7OFN23.js';
+import '../chunk-HYSJ6YPN.js';
+import '../chunk-H3XILKGI.js';
+import '../chunk-LFF5LPWT.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/storefront/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/testing/index.d.ts

@@ -0,0 +1,82 @@
+import { PluginServer } from '../plugin/server/index.js';
+import { P as PluginManifest } from '../types-BoGD3IXz.js';
+import '../define-B6ZJMWDI.js';
+
+interface MockRoute {
+    method?: string;
+    /** Match against the request path (substring) or a RegExp on the full URL. */
+    path: string | RegExp;
+    status?: number;
+    body?: unknown;
+    /** Dynamic responder; takes precedence over `body`. */
+    respond?: (req: {
+        method: string;
+        url: string;
+        body: unknown;
+    }) => {
+        status?: number;
+        body?: unknown;
+    };
+}
+interface RecordedRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+interface MockFetch {
+    (input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /** Every request the mock received, in order. */
+    readonly requests: RecordedRequest[];
+}
+/** Build a `fetch` implementation that answers from a route table and records calls. */
+declare function createMockFetch(routes?: MockRoute[]): MockFetch;
+interface TestActionOptions {
+    brandId?: string | number;
+    verb?: string;
+    secret?: string;
+}
+/** Invoke a plugin-server action locally, signing the request when a secret is given. */
+declare function testPluginAction(server: PluginServer, action: string, payload: Record<string, unknown>, options?: TestActionOptions): Promise<{
+    status: number;
+    body: unknown;
+}>;
+/** Invoke a plugin-server health check locally. */
+declare function testPluginHealth(server: PluginServer, healthPath?: string): Promise<{
+    status: number;
+    body: unknown;
+}>;
+declare const fixtures: {
+    product: {
+        id: string;
+        name: string;
+        price: string;
+        currency: string;
+        stock: number;
+    };
+    order: {
+        id: string;
+        status: string;
+        total: string;
+        currency: string;
+        customer_id: string;
+    };
+    customer: {
+        id: string;
+        name: string;
+        email: string;
+    };
+    paginated<T>(items: T[], page?: number, perPage?: number, total?: number): {
+        success: boolean;
+        data: {
+            data: T[];
+            current_page: number;
+            per_page: number;
+            total: number;
+            last_page: number;
+        };
+    };
+    pluginManifest(overrides?: Partial<PluginManifest>): PluginManifest;
+};
+
+export { type MockFetch, type MockRoute, type RecordedRequest, type TestActionOptions, createMockFetch, fixtures, testPluginAction, testPluginHealth };

package/dist/testing/index.js

@@ -0,0 +1,106 @@
+import { signLegacyWebhook } from '../chunk-ZWLFJIAM.js';
+import '../chunk-LFF5LPWT.js';
+
+// src/testing/index.ts
+function createMockFetch(routes = []) {
+  const requests = [];
+  const impl = async (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    const method = (init?.method ?? "GET").toUpperCase();
+    const headers = normalizeHeaders(init?.headers);
+    const parsedBody = parseRequestBody(init?.body);
+    requests.push({ method, url, headers, body: parsedBody });
+    const route = routes.find(
+      (r) => (!r.method || r.method.toUpperCase() === method) && (r.path instanceof RegExp ? r.path.test(url) : url.includes(r.path))
+    );
+    if (!route) {
+      return jsonResponse(404, { success: false, message: `No mock route for ${method} ${url}` });
+    }
+    const dynamic = route.respond?.({ method, url, body: parsedBody });
+    const status = dynamic?.status ?? route.status ?? 200;
+    const body = dynamic?.body ?? route.body ?? { success: true, data: null };
+    return jsonResponse(status, body);
+  };
+  return Object.assign(impl, { requests });
+}
+function normalizeHeaders(headers) {
+  const out = {};
+  if (!headers) return out;
+  if (headers instanceof Headers) {
+    headers.forEach((v, k) => out[k] = v);
+  } else if (Array.isArray(headers)) {
+    for (const [k, v] of headers) out[k] = v;
+  } else {
+    Object.assign(out, headers);
+  }
+  return out;
+}
+function parseRequestBody(body) {
+  if (typeof body !== "string") return body ?? null;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return body;
+  }
+}
+function jsonResponse(status, body) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" }
+  });
+}
+async function testPluginAction(server, action, payload, options = {}) {
+  const bodyObj = { brand_id: options.brandId, verb: options.verb ?? "POST", action, payload };
+  const rawBody = JSON.stringify(bodyObj);
+  const headers = { "content-type": "application/json" };
+  if (options.secret) headers["x-threeu-signature"] = await signLegacyWebhook(options.secret, bodyObj);
+  const res = await server.handle({ method: "POST", path: `/actions/${action}`, headers, rawBody });
+  return { status: res.status, body: safeJson(res.body) };
+}
+async function testPluginHealth(server, healthPath = "/health") {
+  const res = await server.handle({ method: "GET", path: healthPath, headers: {}, rawBody: "" });
+  return { status: res.status, body: safeJson(res.body) };
+}
+function safeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+var fixtures = {
+  product: { id: "prod_123", name: "Black Abaya", price: "350.00", currency: "QAR", stock: 20 },
+  order: { id: "order_123", status: "pending", total: "350.00", currency: "QAR", customer_id: "cust_1" },
+  customer: { id: "cust_1", name: "Aisha", email: "aisha@example.com" },
+  paginated(items, page = 1, perPage = 20, total = items.length) {
+    return {
+      success: true,
+      data: { data: items, current_page: page, per_page: perPage, total, last_page: Math.max(1, Math.ceil(total / perPage)) }
+    };
+  },
+  pluginManifest(overrides = {}) {
+    return {
+      type: "plugin",
+      runtime: "remote_http",
+      name: "FastShip",
+      slug: "fastship",
+      version: "1.0.0",
+      category: "shipping",
+      surface_type: "plugin",
+      trigger_mode: "manual",
+      ownership: "community",
+      permissions: ["orders:read", "shipping:write"],
+      provider: {
+        type: "remote_http",
+        base_url: "https://api.fastship.com/threeu",
+        health_path: "/health",
+        auth: { type: "hmac_sha256", signature_header: "X-ThreeU-Signature", timestamp_header: "X-ThreeU-Timestamp" }
+      },
+      ...overrides
+    };
+  }
+};
+
+export { createMockFetch, fixtures, testPluginAction, testPluginHealth };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/testing/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @threeu/threeu/testing — mocks & fixtures for testing SDK integrations.\n *\n *   const fetchMock = createMockFetch([\n *     { method: \"POST\", path: \"/products\", body: { success: true, data: fixtures.product } },\n *   ]);\n *   const threeu = new Threeu(\"test\", { fetch: fetchMock, baseUrl: \"https://api.test\" });\n */\nimport { signLegacyWebhook } from \"../webhooks\";\nimport type { PluginServer } from \"../plugin/server\";\nimport type { PluginManifest } from \"../manifests/types\";\n\nexport interface MockRoute {\n  method?: string;\n  /** Match against the request path (substring) or a RegExp on the full URL. */\n  path: string | RegExp;\n  status?: number;\n  body?: unknown;\n  /** Dynamic responder; takes precedence over `body`. */\n  respond?: (req: { method: string; url: string; body: unknown }) => { status?: number; body?: unknown };\n}\n\nexport interface RecordedRequest {\n  method: string;\n  url: string;\n  headers: Record<string, string>;\n  body: unknown;\n}\n\nexport interface MockFetch {\n  (input: RequestInfo | URL, init?: RequestInit): Promise<Response>;\n  /** Every request the mock received, in order. */\n  readonly requests: RecordedRequest[];\n}\n\n/** Build a `fetch` implementation that answers from a route table and records calls. */\nexport function createMockFetch(routes: MockRoute[] = []): MockFetch {\n  const requests: RecordedRequest[] = [];\n\n  const impl = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {\n    const url = typeof input === \"string\" ? input : input instanceof URL ? input.toString() : input.url;\n    const method = (init?.method ?? \"GET\").toUpperCase();\n    const headers = normalizeHeaders(init?.headers);\n    const parsedBody = parseRequestBody(init?.body);\n    requests.push({ method, url, headers, body: parsedBody });\n\n    const route = routes.find(\n      (r) =>\n        (!r.method || r.method.toUpperCase() === method) &&\n        (r.path instanceof RegExp ? r.path.test(url) : url.includes(r.path)),\n    );\n\n    if (!route) {\n      return jsonResponse(404, { success: false, message: `No mock route for ${method} ${url}` });\n    }\n    const dynamic = route.respond?.({ method, url, body: parsedBody });\n    const status = dynamic?.status ?? route.status ?? 200;\n    const body = dynamic?.body ?? route.body ?? { success: true, data: null };\n    return jsonResponse(status, body);\n  };\n\n  return Object.assign(impl, { requests }) as MockFetch;\n}\n\nfunction normalizeHeaders(headers: RequestInit[\"headers\"]): Record<string, string> {\n  const out: Record<string, string> = {};\n  if (!headers) return out;\n  if (headers instanceof Headers) {\n    headers.forEach((v, k) => (out[k] = v));\n  } else if (Array.isArray(headers)) {\n    for (const [k, v] of headers) out[k] = v;\n  } else {\n    Object.assign(out, headers);\n  }\n  return out;\n}\n\nfunction parseRequestBody(body: RequestInit[\"body\"]): unknown {\n  if (typeof body !== \"string\") return body ?? null;\n  try {\n    return JSON.parse(body);\n  } catch {\n    return body;\n  }\n}\n\nfunction jsonResponse(status: number, body: unknown): Response {\n  return new Response(JSON.stringify(body), {\n    status,\n    headers: { \"content-type\": \"application/json\" },\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Plugin server local testing\n// ---------------------------------------------------------------------------\n\nexport interface TestActionOptions {\n  brandId?: string | number;\n  verb?: string;\n  secret?: string;\n}\n\n/** Invoke a plugin-server action locally, signing the request when a secret is given. */\nexport async function testPluginAction(\n  server: PluginServer,\n  action: string,\n  payload: Record<string, unknown>,\n  options: TestActionOptions = {},\n): Promise<{ status: number; body: unknown }> {\n  const bodyObj = { brand_id: options.brandId, verb: options.verb ?? \"POST\", action, payload };\n  const rawBody = JSON.stringify(bodyObj);\n  const headers: Record<string, string> = { \"content-type\": \"application/json\" };\n  if (options.secret) headers[\"x-threeu-signature\"] = await signLegacyWebhook(options.secret, bodyObj);\n\n  const res = await server.handle({ method: \"POST\", path: `/actions/${action}`, headers, rawBody });\n  return { status: res.status, body: safeJson(res.body) };\n}\n\n/** Invoke a plugin-server health check locally. */\nexport async function testPluginHealth(\n  server: PluginServer,\n  healthPath = \"/health\",\n): Promise<{ status: number; body: unknown }> {\n  const res = await server.handle({ method: \"GET\", path: healthPath, headers: {}, rawBody: \"\" });\n  return { status: res.status, body: safeJson(res.body) };\n}\n\nfunction safeJson(text: string): unknown {\n  try {\n    return JSON.parse(text);\n  } catch {\n    return text;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Fixtures\n// ---------------------------------------------------------------------------\n\nexport const fixtures = {\n  product: { id: \"prod_123\", name: \"Black Abaya\", price: \"350.00\", currency: \"QAR\", stock: 20 },\n  order: { id: \"order_123\", status: \"pending\", total: \"350.00\", currency: \"QAR\", customer_id: \"cust_1\" },\n  customer: { id: \"cust_1\", name: \"Aisha\", email: \"aisha@example.com\" },\n  paginated<T>(items: T[], page = 1, perPage = 20, total = items.length) {\n    return {\n      success: true,\n      data: { data: items, current_page: page, per_page: perPage, total, last_page: Math.max(1, Math.ceil(total / perPage)) },\n    };\n  },\n  pluginManifest(overrides: Partial<PluginManifest> = {}): PluginManifest {\n    return {\n      type: \"plugin\",\n      runtime: \"remote_http\",\n      name: \"FastShip\",\n      slug: \"fastship\",\n      version: \"1.0.0\",\n      category: \"shipping\",\n      surface_type: \"plugin\",\n      trigger_mode: \"manual\",\n      ownership: \"community\",\n      permissions: [\"orders:read\", \"shipping:write\"],\n      provider: {\n        type: \"remote_http\",\n        base_url: \"https://api.fastship.com/threeu\",\n        health_path: \"/health\",\n        auth: { type: \"hmac_sha256\", signature_header: \"X-ThreeU-Signature\", timestamp_header: \"X-ThreeU-Timestamp\" },\n      },\n      ...overrides,\n    };\n  },\n};\n"]}

package/dist/theme/index.d.ts

@@ -0,0 +1,109 @@
+import { ComponentType, CSSProperties, ReactNode } from 'react';
+import { u as ThemeVisibility, v as ThemeEditableField, d as ThemeManifest } from '../types-BoGD3IXz.js';
+export { A as AsyncState, F as FieldKind, T as ThemeBrandInfo, a as ThemeContextValue, b as ThemeProvider, c as ThemeProviderProps, d as ThreeuThemeProvider, e as ThreeuThemeProviderProps, f as extractFields, r as registerField, g as resetRegistry, h as resolveValue, s as setActiveCustomization, u as useBrand, i as useCart, j as useCheckout, k as useCollections, l as useCurrency, m as useCustomer, n as useLocale, o as useProducts, p as useTheme, q as useThemeContext, t as useThemeField } from '../index-ksmDFDZc.js';
+import { C as Collection, d as Product } from '../types-DfyYnoLn.js';
+import '../storefront/index.js';
+
+/**
+ * createTheme / defineTheme — register pages and produce a theme manifest.
+ *
+ * Editable fields are discovered at render time via the runtime registry, so
+ * `manifest()` merges any explicitly declared fields with those collected from
+ * the most recent render/extraction pass. A CLI build step can render each page
+ * once and then call `manifest()` to capture the full field set.
+ */
+
+interface CreateThemeOptions {
+    name: string;
+    slug: string;
+    version?: string;
+    visibility?: ThemeVisibility;
+    pages: Record<string, ComponentType<Record<string, unknown>>>;
+    /** Explicitly declared editable fields (merged with render-extracted ones). */
+    fields?: ThemeEditableField[];
+}
+interface DefinedTheme {
+    readonly name: string;
+    readonly slug: string;
+    readonly visibility: ThemeVisibility;
+    readonly pages: Record<string, ComponentType<Record<string, unknown>>>;
+    getPage(name: string): ComponentType<Record<string, unknown>> | undefined;
+    /** Build the theme manifest, merging declared + render-extracted fields. */
+    manifest(): ThemeManifest;
+    toJSON(): ThemeManifest;
+}
+declare function createTheme(options: CreateThemeOptions): DefinedTheme;
+/** Alias — some authors prefer `defineTheme`. */
+declare const defineTheme: typeof createTheme;
+
+/**
+ * Type-safe, customizable theme components. Each `T*` component registers the
+ * editable field it exposes (so the theme editor / build step can enumerate
+ * them) and resolves its current value from the active customization.
+ *
+ * Editable elements carry a `data-threeu-field` attribute the in-app editor uses
+ * to target them.
+ */
+
+/** Resolve (and register) a color field. Usable inline: `TColor("hero.bg", "#000")`. */
+declare function TColor(name: string, fallback?: string): string;
+interface FieldProps {
+    name: string;
+    className?: string;
+    style?: CSSProperties;
+}
+declare function TSection(props: FieldProps & {
+    children?: ReactNode;
+}): JSX.Element;
+declare function THeading(props: FieldProps & {
+    children?: ReactNode;
+    as?: "h1" | "h2" | "h3";
+}): JSX.Element;
+declare function TParagraph(props: FieldProps & {
+    children?: ReactNode;
+}): JSX.Element;
+declare function TText(props: FieldProps & {
+    children?: ReactNode;
+}): JSX.Element;
+declare function TSpan(props: FieldProps & {
+    children?: ReactNode;
+}): JSX.Element;
+declare function TImage(props: FieldProps & {
+    src: string;
+    alt: string;
+    width?: number | string;
+    height?: number | string;
+}): JSX.Element;
+declare function TButton(props: FieldProps & {
+    children?: ReactNode;
+    onClick?: () => void;
+    type?: "button" | "submit";
+}): JSX.Element;
+declare function TLink(props: FieldProps & {
+    href: string;
+    children?: ReactNode;
+}): JSX.Element;
+declare function TProductCard(props: {
+    product: Product;
+    className?: string;
+}): JSX.Element;
+declare function TProductGrid(props: {
+    products: Product[];
+    columns?: number;
+    className?: string;
+}): JSX.Element;
+declare function TCollectionGrid(props: {
+    collections: Collection[];
+    className?: string;
+}): JSX.Element;
+declare function TCartSummary(props: {
+    cart?: Record<string, unknown>;
+    className?: string;
+}): JSX.Element;
+declare function TCheckoutForm(props: {
+    onSubmit?: (data: Record<string, FormDataEntryValue>) => void;
+    className?: string;
+    children?: ReactNode;
+}): JSX.Element;
+
+export { type CreateThemeOptions, type DefinedTheme, TButton, TCartSummary, TCheckoutForm, TCollectionGrid, TColor, THeading, TImage, TLink, TParagraph, TProductCard, TProductGrid, TSection, TSpan, TText, ThemeEditableField, ThemeManifest, ThemeVisibility, createTheme, defineTheme };

package/dist/theme/index.js

@@ -0,0 +1,152 @@
+import { registerField, resolveValue, useThemeField, extractFields } from '../chunk-6ZCBDWWQ.js';
+export { ThemeProvider, ThreeuThemeProvider, extractFields, registerField, resetRegistry, resolveValue, setActiveCustomization, useBrand, useCart, useCheckout, useCollections, useCurrency, useCustomer, useLocale, useProducts, useTheme, useThemeContext, useThemeField } from '../chunk-6ZCBDWWQ.js';
+import '../chunk-6S7OFN23.js';
+import { buildThemeManifest } from '../chunk-USFJIM5K.js';
+import '../chunk-HYSJ6YPN.js';
+import '../chunk-H3XILKGI.js';
+import '../chunk-LFF5LPWT.js';
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+// src/theme/define.ts
+function createTheme(options) {
+  const pageNames = Object.keys(options.pages);
+  const manifest = () => {
+    const declared = options.fields ?? [];
+    const extracted = extractFields();
+    const byName = /* @__PURE__ */ new Map();
+    for (const f of [...extracted, ...declared]) byName.set(f.name, f);
+    return buildThemeManifest({
+      name: options.name,
+      slug: options.slug,
+      version: options.version,
+      visibility: options.visibility,
+      pages: pageNames,
+      fields: Array.from(byName.values())
+    });
+  };
+  return {
+    name: options.name,
+    slug: options.slug,
+    visibility: options.visibility ?? "public",
+    pages: options.pages,
+    getPage: (name) => options.pages[name],
+    manifest,
+    toJSON: manifest
+  };
+}
+var defineTheme = createTheme;
+function TColor(name, fallback = "#000000") {
+  registerField(name, "color", fallback);
+  return resolveValue(name, fallback);
+}
+function TSection(props) {
+  return /* @__PURE__ */ jsx("section", { "data-threeu-field": props.name, "data-threeu-kind": "section", className: props.className, style: props.style, children: props.children });
+}
+function THeading(props) {
+  const text = useThemeField(props.name, "heading", asText(props.children));
+  const Tag = props.as ?? "h1";
+  return /* @__PURE__ */ jsx(Tag, { "data-threeu-field": props.name, "data-threeu-kind": "heading", className: props.className, style: props.style, children: text });
+}
+function TParagraph(props) {
+  const text = useThemeField(props.name, "paragraph", asText(props.children));
+  return /* @__PURE__ */ jsx("p", { "data-threeu-field": props.name, "data-threeu-kind": "paragraph", className: props.className, style: props.style, children: text });
+}
+function TText(props) {
+  const text = useThemeField(props.name, "text", asText(props.children));
+  return /* @__PURE__ */ jsx("span", { "data-threeu-field": props.name, "data-threeu-kind": "text", className: props.className, style: props.style, children: text });
+}
+function TSpan(props) {
+  const text = useThemeField(props.name, "span", asText(props.children));
+  return /* @__PURE__ */ jsx("span", { "data-threeu-field": props.name, "data-threeu-kind": "span", className: props.className, style: props.style, children: text });
+}
+function TImage(props) {
+  const src = useThemeField(props.name, "image", props.src);
+  return /* @__PURE__ */ jsx(
+    "img",
+    {
+      "data-threeu-field": props.name,
+      "data-threeu-kind": "image",
+      src,
+      alt: props.alt,
+      width: props.width,
+      height: props.height,
+      className: props.className,
+      style: props.style
+    }
+  );
+}
+function TButton(props) {
+  const label = useThemeField(props.name, "text", asText(props.children));
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      "data-threeu-field": props.name,
+      "data-threeu-kind": "text",
+      type: props.type ?? "button",
+      onClick: props.onClick,
+      className: props.className,
+      style: props.style,
+      children: label
+    }
+  );
+}
+function TLink(props) {
+  const href = useThemeField(props.name, "link", props.href);
+  return /* @__PURE__ */ jsx("a", { "data-threeu-field": props.name, "data-threeu-kind": "link", href, className: props.className, style: props.style, children: props.children });
+}
+function TProductCard(props) {
+  const { product } = props;
+  return /* @__PURE__ */ jsxs("div", { "data-threeu-product": String(product.id), className: props.className, children: [
+    /* @__PURE__ */ jsx("div", { className: "threeu-product-name", children: String(product.name ?? "") }),
+    /* @__PURE__ */ jsx("div", { className: "threeu-product-price", children: formatPrice(product.price, product.currency) })
+  ] });
+}
+function TProductGrid(props) {
+  const columns = props.columns ?? 3;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: props.className,
+      style: { display: "grid", gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`, gap: "1rem" },
+      children: props.products.map((p) => /* @__PURE__ */ jsx(TProductCard, { product: p }, String(p.id)))
+    }
+  );
+}
+function TCollectionGrid(props) {
+  return /* @__PURE__ */ jsx("div", { className: props.className, style: { display: "grid", gap: "1rem" }, children: props.collections.map((c) => /* @__PURE__ */ jsx("div", { "data-threeu-collection": String(c.id), children: String(c.title ?? c.handle ?? c.id) }, String(c.id))) });
+}
+function TCartSummary(props) {
+  const items = Array.isArray(props.cart?.items) ? props.cart?.items : [];
+  return /* @__PURE__ */ jsx("div", { className: props.className, "data-threeu-cart-summary": true, children: /* @__PURE__ */ jsxs("div", { children: [
+    items.length,
+    " item(s)"
+  ] }) });
+}
+function TCheckoutForm(props) {
+  return /* @__PURE__ */ jsx(
+    "form",
+    {
+      className: props.className,
+      "data-threeu-checkout-form": true,
+      onSubmit: (e) => {
+        e.preventDefault();
+        const data = Object.fromEntries(new FormData(e.currentTarget).entries());
+        props.onSubmit?.(data);
+      },
+      children: props.children
+    }
+  );
+}
+function asText(children) {
+  return typeof children === "string" ? children : "";
+}
+function formatPrice(price, currency) {
+  if (price === void 0) return "";
+  const n = typeof price === "string" ? Number(price) : price;
+  if (!Number.isFinite(n)) return String(price);
+  return `${n.toFixed(2)} ${currency ?? ""}`.trim();
+}
+
+export { TButton, TCartSummary, TCheckoutForm, TCollectionGrid, TColor, THeading, TImage, TLink, TParagraph, TProductCard, TProductGrid, TSection, TSpan, TText, createTheme, defineTheme };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map