@crediball/react 0.7.0 → 0.8.0

package/dist/CrediballProvider.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from "react";
 import { type PackageOption, type SubscriptionPlanOption } from "./PaywallModal";
-import { type UsagePeriod } from "@crediball/core";
+import { type UsagePeriod, type PackagesPayload, type CrediballUiContent } from "@crediball/core";
 export interface CrediballProviderProps {
     children: ReactNode;
     /**
@@ -84,6 +84,15 @@ export interface CrediballProviderProps {
     description?: string;
     /** Override the accent color (defaults to Action Blue). */
     accentColor?: string;
+    /**
+     * Apply the theme (colors, radii, font) the developer published on the
+     * Crediball dashboard's UI-patterns page — served alongside packages — as
+     * `--crediball-*` CSS variables, so preview edits reflect here with no code
+     * change. On by default; the published theme takes precedence over any
+     * `--crediball-*` vars you set in your own CSS. Set false to opt out and
+     * theme entirely from your own stylesheet.
+     */
+    applyRemoteTheme?: boolean;
 }
 interface CrediballContextValue {
     /**
@@ -116,6 +125,12 @@ interface CrediballContextValue {
     topUp: (amount: number) => Promise<void>;
     /** Refetch balance, usage, costs, and packages immediately. No-op without publishableKey/userId. */
     refresh: () => Promise<void>;
+    /** The live packages payload (top-up options, plans, custom-topup, currency, ui). null until loaded. */
+    packages: PackagesPayload | null;
+    /** Currency symbol derived from the dashboard's configured currency (e.g. "€", "$"). */
+    currencySymbol: string;
+    /** Developer-published default copy from the dashboard, used as a label fallback. null when unconfigured. */
+    content: CrediballUiContent | null;
 }
 /**
  * Pattern B, automated. Wrap your app once:
@@ -137,7 +152,7 @@ interface CrediballContextValue {
  * SSE/streaming routes (text/event-stream, ndjson) are also handled automatically —
  * the watcher scans each chunk for credit errors, so no manual wiring is needed.
  */
-export declare function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts, onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, watchFetch, allowCustom, customMin, customMax, currencySymbol: currencySymbolProp, title, description, accentColor, }: CrediballProviderProps): import("react").JSX.Element;
+export declare function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts, onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, watchFetch, allowCustom, customMin, customMax, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme, }: CrediballProviderProps): import("react").JSX.Element;
 /**
  * Access the paywall + live data from anywhere inside <CrediballProvider>.
  *

package/dist/CrediballProvider.js

@@ -1,10 +1,10 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
 import { PaywallModal } from "./PaywallModal";
 import { subscribeFetchWatcher } from "./fetchWatcher";
 import { subscribeInsufficientCredits } from "./creditEvent";
-import { getCrediballClient, notifyBalanceChanged } from "@crediball/core";
+import { getCrediballClient, notifyBalanceChanged, } from "@crediball/core";
 const CrediballContext = createContext(null);
 const EMPTY_SNAPSHOT = {
     balance: null,
@@ -34,6 +34,50 @@ function symbolForCurrency(iso) {
         return iso;
     }
 }
+/**
+ * Turn a published theme into the `--crediball-*` inline style the provider
+ * spreads onto a wrapping element. Only set fields are emitted, so an empty or
+ * partial theme leaves the built-in defaults (and any host CSS vars) in place.
+ */
+function themeToCssVars(theme) {
+    if (!theme)
+        return {};
+    const vars = {};
+    if (theme.accent)
+        vars["--crediball-accent"] = theme.accent;
+    if (theme.onAccent)
+        vars["--crediball-on-accent"] = theme.onAccent;
+    if (theme.ink)
+        vars["--crediball-ink"] = theme.ink;
+    if (theme.canvas)
+        vars["--crediball-canvas"] = theme.canvas;
+    if (theme.hairline)
+        vars["--crediball-hairline"] = theme.hairline;
+    if (theme.radius != null)
+        vars["--crediball-radius"] = `${theme.radius}px`;
+    if (theme.radiusCard != null)
+        vars["--crediball-radius-card"] = `${theme.radiusCard}px`;
+    if (theme.fontStack)
+        vars["--crediball-font"] = theme.fontStack;
+    return vars;
+}
+/** Inject a webfont stylesheet <link> once (idempotent by href), for a published theme's fontUrl. */
+function loadRemoteFont(url) {
+    if (typeof document === "undefined")
+        return;
+    const existing = document.querySelector(`link[data-crediball-font]`);
+    if (existing?.href === url)
+        return;
+    if (existing)
+        existing.href = url;
+    else {
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = url;
+        link.setAttribute("data-crediball-font", "");
+        document.head.appendChild(link);
+    }
+}
 /**
  * Pattern B, automated. Wrap your app once:
  *
@@ -54,7 +98,7 @@ function symbolForCurrency(iso) {
  * SSE/streaming routes (text/event-stream, ndjson) are also handled automatically —
  * the watcher scans each chunk for credit errors, so no manual wiring is needed.
  */
-export function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts = [5, 10, 20], onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, watchFetch = true, allowCustom, customMin, customMax, currencySymbol: currencySymbolProp, title, description, accentColor, }) {
+export function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts = [5, 10, 20], onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, watchFetch = true, allowCustom, customMin, customMax, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme = true, }) {
     const [open, setOpen] = useState(false);
     const showPaywall = useCallback(() => setOpen(true), []);
     const hidePaywall = useCallback(() => setOpen(false), []);
@@ -84,6 +128,20 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         return () => client.stop();
     }, [client]);
     const snapshot = useSyncExternalStore(client ? client.subscribe : noopSubscribe, client ? client.getSnapshot : getEmptySnapshot, client ? client.getSnapshot : getEmptySnapshot);
+    const pkgs = snapshot.packages;
+    const uiTheme = pkgs?.ui?.theme ?? null;
+    const uiContent = pkgs?.ui?.content ?? null;
+    // Follow the dashboard's configured currency once packages load, unless the
+    // host pins an explicit symbol. Falls back to "€" only until the first fetch
+    // resolves, so switching currencies on the Packages page never requires a
+    // matching code change/redeploy here.
+    const currencySymbol = currencySymbolProp ?? (pkgs?.currency ? symbolForCurrency(pkgs.currency) : "€");
+    // Load the published theme's webfont, if any, so --crediball-font renders.
+    useEffect(() => {
+        if (!applyRemoteTheme || !uiTheme?.fontUrl)
+            return;
+        loadRemoteFont(uiTheme.fontUrl);
+    }, [applyRemoteTheme, uiTheme?.fontUrl]);
     const costOf = useCallback((event) => client?.costOf(event), [client]);
     const refresh = useCallback(async () => {
         await client?.refresh();
@@ -107,7 +165,10 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         costOf,
         topUp,
         refresh,
-    }), [showPaywall, hidePaywall, open, snapshot, costOf, topUp, refresh]);
+        packages: pkgs,
+        currencySymbol,
+        content: uiContent,
+    }), [showPaywall, hidePaywall, open, snapshot, costOf, topUp, refresh, pkgs, currencySymbol, uiContent]);
     // The page to return to after Stripe checkout — the one the user is on now.
     function currentReturnPath() {
         if (typeof window === "undefined")
@@ -208,12 +269,6 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         await onCancelSubscription?.(subscriptionId);
         await client?.refresh();
     }
-    const pkgs = snapshot.packages;
-    // Follow the dashboard's configured currency once packages load, unless the
-    // host pins an explicit symbol. Falls back to "€" only until the first fetch
-    // resolves, so switching currencies on the Packages page never requires a
-    // matching code change/redeploy here.
-    const currencySymbol = currencySymbolProp ?? (pkgs?.currency ? symbolForCurrency(pkgs.currency) : "€");
     // Auto-derive the custom-amount field from the dashboard's custom-topup config,
     // so a developer who enabled it doesn't also have to pass allowCustom/min/max.
     // Explicit props still win (allowCustom={false} force-hides it).
@@ -221,7 +276,13 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
     const effectiveAllowCustom = allowCustom ?? customCfg?.enabled ?? false;
     const effectiveCustomMin = customMin ?? customCfg?.minEur;
     const effectiveCustomMax = customMax ?? customCfg?.maxEur ?? undefined;
-    return (_jsxs(CrediballContext.Provider, { value: ctx, children: [children, _jsx(PaywallModal, { open: open, packages: pkgs?.packages, onSelectPackage: handleSelectPackage, subscriptionPlans: pkgs?.subscriptionPlans, onSelectPlan: handleSelectPlan, activeSubscription: pkgs?.activeSubscription, onCancelSubscription: handleCancelSubscription, amounts: amounts, amountPrefix: `Add ${currencySymbol}`, onAdd: handleAdd, onClose: hidePaywall, allowCustom: effectiveAllowCustom, customMin: effectiveCustomMin, customMax: effectiveCustomMax, currencySymbol: currencySymbol, balance: snapshot.balance ?? undefined, balanceRate: pkgs?.customTopup.enabled ? pkgs.customTopup.rate : undefined, currency: pkgs?.currency, usage: snapshot.usage?.usedCredits ?? undefined, title: title, description: description, accentColor: accentColor })] }));
+    // Published theme → --crediball-* CSS vars, applied on a display:contents
+    // wrapper so it themes every descendant (and the paywall) without adding a
+    // layout box. Host props/CSS are overridden by design (dashboard wins).
+    const themeVars = applyRemoteTheme ? themeToCssVars(uiTheme) : {};
+    const hasThemeVars = Object.keys(themeVars).length > 0;
+    const inner = (_jsxs(_Fragment, { children: [children, _jsx(PaywallModal, { open: open, packages: pkgs?.packages, onSelectPackage: handleSelectPackage, subscriptionPlans: pkgs?.subscriptionPlans, onSelectPlan: handleSelectPlan, activeSubscription: pkgs?.activeSubscription, onCancelSubscription: onCancelSubscription ? handleCancelSubscription : undefined, amounts: amounts, amountPrefix: `Add ${currencySymbol}`, onAdd: handleAdd, onClose: hidePaywall, allowCustom: effectiveAllowCustom, customMin: effectiveCustomMin, customMax: effectiveCustomMax, currencySymbol: currencySymbol, balance: snapshot.balance ?? undefined, balanceRate: pkgs?.customTopup.enabled ? pkgs.customTopup.rate : undefined, currency: pkgs?.currency, usage: snapshot.usage?.usedCredits ?? undefined, title: title ?? uiContent?.paywallTitle, description: description ?? uiContent?.paywallDescription, addButtonText: uiContent?.paywallButtonText, accentColor: accentColor })] }));
+    return (_jsx(CrediballContext.Provider, { value: ctx, children: hasThemeVars ? _jsx("div", { style: { display: "contents", ...themeVars }, children: inner }) : inner }));
 }
 /**
  * Access the paywall + live data from anywhere inside <CrediballProvider>.

package/dist/CreditIndicator.js

@@ -7,9 +7,11 @@ import { useCrediballOptional } from "./CrediballProvider";
  * Pattern C — Subtle indicator. A quiet balance chip for a host app's top bar;
  * clickable to open a top-up flow. Minimal and non-intrusive.
  */
-export function CreditIndicator({ balanceLabel, label = "Credits:", onClick, accentColor, style, }) {
+export function CreditIndicator({ balanceLabel, label, onClick, accentColor, style, }) {
     const ctx = useCrediballOptional();
     const resolvedLabel = balanceLabel ?? (ctx?.balance != null ? formatCredits(ctx.balance) : "—");
+    // Prefer the host prop, then the dashboard-published default, then the built-in.
+    const resolvedText = label ?? ctx?.content?.indicatorLabel ?? "Credits:";
     const resolvedOnClick = onClick ?? ctx?.openPaywall;
     return (_jsxs("button", { onClick: resolvedOnClick, style: {
             display: "inline-flex",
@@ -26,5 +28,5 @@ export function CreditIndicator({ balanceLabel, label = "Credits:", onClick, acc
             padding: "4px 12px",
             ...accentStyle(accentColor),
             ...style,
-        }, children: [_jsx("span", { style: { color: theme.inkMuted }, children: label }), _jsx("span", { style: { fontWeight: 600 }, children: resolvedLabel })] }));
+        }, children: [_jsx("span", { style: { color: theme.inkMuted }, children: resolvedText }), _jsx("span", { style: { fontWeight: 600 }, children: resolvedLabel })] }));
 }

package/dist/CreditsBadge.js

@@ -9,9 +9,12 @@ import { useCrediballOptional } from "./CrediballProvider";
  * as the primary figure and an approximate money value beneath it. No Crediball
  * branding.
  */
-export function CreditsBadge({ credits, rate, currency = "EUR", label = "Credit balance", onAddCredits, addLabel = "Add credits", accentColor, style, }) {
+export function CreditsBadge({ credits, rate, currency = "EUR", label, onAddCredits, addLabel, accentColor, style, }) {
     const ctx = useCrediballOptional();
     const resolvedCredits = credits ?? ctx?.balance ?? 0;
+    // Prefer the host prop, then the dashboard-published default, then the built-in.
+    const resolvedLabel = label ?? ctx?.content?.badgeLabel ?? "Credit balance";
+    const resolvedAddLabel = addLabel ?? ctx?.content?.badgeAddLabel ?? "Add credits";
     const showMoney = typeof rate === "number" && rate > 0;
     return (_jsxs("div", { style: {
             display: "flex",
@@ -25,7 +28,7 @@ export function CreditsBadge({ credits, rate, currency = "EUR", label = "Credit
             fontFamily: theme.font,
             ...accentStyle(accentColor),
             ...style,
-        }, children: [_jsxs("div", { children: [_jsx("div", { style: { fontSize: 14, color: theme.inkMuted }, children: label }), _jsxs("div", { style: { fontSize: 28, fontWeight: 600, color: theme.ink, letterSpacing: "-0.01em" }, children: [formatCredits(resolvedCredits), _jsx("span", { style: { fontSize: 16, fontWeight: 400, color: theme.inkMuted, marginLeft: 6 }, children: "credits" })] }), showMoney ? (_jsxs("div", { style: { fontSize: 13, color: theme.inkMuted, marginTop: 2 }, children: ["\u2248 ", formatMoney(resolvedCredits / rate, currency)] })) : null] }), _jsx("button", { onClick: onAddCredits ?? ctx?.openPaywall, style: {
+        }, children: [_jsxs("div", { children: [_jsx("div", { style: { fontSize: 14, color: theme.inkMuted }, children: resolvedLabel }), _jsxs("div", { style: { fontSize: 28, fontWeight: 600, color: theme.ink, letterSpacing: "-0.01em" }, children: [formatCredits(resolvedCredits), _jsx("span", { style: { fontSize: 16, fontWeight: 400, color: theme.inkMuted, marginLeft: 6 }, children: "credits" })] }), showMoney ? (_jsxs("div", { style: { fontSize: 13, color: theme.inkMuted, marginTop: 2 }, children: ["\u2248 ", formatMoney(resolvedCredits / rate, currency)] })) : null] }), _jsx("button", { onClick: onAddCredits ?? ctx?.openPaywall, style: {
                     appearance: "none",
                     border: "none",
                     cursor: "pointer",
@@ -35,5 +38,5 @@ export function CreditsBadge({ credits, rate, currency = "EUR", label = "Credit
                     fontSize: 14,
                     padding: "8px 16px",
                     borderRadius: theme.radiusPill,
-                }, children: addLabel })] }));
+                }, children: resolvedAddLabel })] }));
 }

package/dist/variables/CrediballLowCreditWarning.js

@@ -8,13 +8,16 @@ import { useCrediball } from "../CrediballProvider";
  *
  *   <CrediballLowCreditWarning threshold={20} message="Not enough for one more image." />
  */
-export function CrediballLowCreditWarning({ className, style, threshold, message = "Low credit balance — top up to keep going.", children, }) {
-    const { balance, isLow: contextIsLow } = useCrediball();
-    const isLow = threshold != null && balance != null ? balance < threshold : contextIsLow;
+export function CrediballLowCreditWarning({ className, style, threshold, message, children, }) {
+    const { balance, isLow: contextIsLow, content } = useCrediball();
+    // Prefer the host prop, then the dashboard-published default, then the provider's.
+    const effectiveThreshold = threshold ?? content?.lowCreditThreshold;
+    const isLow = effectiveThreshold != null && balance != null ? balance < effectiveThreshold : contextIsLow;
     if (!isLow)
         return null;
     if (typeof children === "function") {
         return _jsx(_Fragment, { children: children({ balance, isLow }) });
     }
-    return (_jsx("span", { className: className, style: { font: "inherit", color: "currentColor", ...style }, children: children ?? message }));
+    const resolvedMessage = message ?? content?.lowCreditMessage ?? "Low credit balance — top up to keep going.";
+    return (_jsx("span", { className: className, style: { font: "inherit", color: "currentColor", ...style }, children: children ?? resolvedMessage }));
 }

package/dist/variables/CrediballTopUpButton.js

@@ -11,7 +11,7 @@ import { theme, accentStyle } from "../theme";
  *   <CrediballTopUpButton>Get more credits</CrediballTopUpButton>
  */
 export function CrediballTopUpButton({ className, style, children, onClick, accentColor }) {
-    const { openPaywall } = useCrediball();
+    const { openPaywall, content } = useCrediball();
     return (_jsx("button", { type: "button", className: className, onClick: onClick ?? openPaywall, style: {
             font: "inherit",
             appearance: "none",
@@ -23,5 +23,5 @@ export function CrediballTopUpButton({ className, style, children, onClick, acce
             padding: "0.5em 1.1em",
             ...accentStyle(accentColor),
             ...style,
-        }, children: children ?? "Add credits" }));
+        }, children: children ?? content?.topUpButtonText ?? "Add credits" }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/react",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Drop-in React components for showing Crediball credits inside your AI app.",
   "license": "MIT",
   "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",
@@ -51,7 +51,7 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@crediball/core": "^0.2.0"
+    "@crediball/core": "^0.3.0"
   },
   "devDependencies": {
     "@types/react": "^18.3.11",