@fanfare-io/fanfare-sdk-react 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanfare-io/fanfare-sdk-react",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "React adapter for Fanfare SDK",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -17,7 +17,6 @@
   "type": "module",
   "files": [
     "dist/",
-    "docs/",
     "README.md"
   ],
   "module": "./dist/index.js",
@@ -44,8 +43,8 @@
     "nanostores": "^1.1.0",
     "tailwind-merge": "^2.6.0",
     "valibot": "^1.1.0",
-    "@fanfare-io/fanfare-sdk-core": "0.1.0",
-    "@fanfare-io/fanfare-sdk-i18n": "0.1.0"
+    "@fanfare-io/fanfare-sdk-core": "0.3.0",
+    "@fanfare-io/fanfare-sdk-i18n": "0.3.0"
   },
   "devDependencies": {
     "@iconify-json/heroicons": "^1.2.3",
@@ -89,8 +88,8 @@
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4",
-    "@fanfare-io/fanfare-sdk-core": "0.1.0",
-    "@fanfare-io/fanfare-sdk-solid": "0.1.0"
+    "@fanfare-io/fanfare-sdk-core": "0.3.0",
+    "@fanfare-io/fanfare-sdk-solid": "0.3.0"
   },
   "sideEffects": [
     "**/*.css"
@@ -125,7 +124,7 @@
   "scripts": {
     "prebuild": "rimraf dist && pnpm -F @fanfare-io/fanfare-sdk-i18n build:deps && pnpm -F @fanfare-io/fanfare-sdk-core build:deps",
     "pretest": "pnpm -F @fanfare-io/fanfare-sdk-i18n build:deps && pnpm -F @fanfare-io/fanfare-sdk-core build:deps && pnpm -F @fanfare-io/fanfare-sdk-solid build:incremental",
-    "build": "vite build && tailwindcss -i src/styles/base.css -o dist/styles/base.css && pnpm size",
+    "build": "vite build && tailwindcss -i src/styles/base.css -o dist/styles/base.css --minify && pnpm size",
     "build:incremental": "vite build --emptyOutDir false",
     "build:strict": "pnpm typecheck && pnpm build",
     "build-storybook": "storybook build",

package/dist/components/widgets/auction/auction-actions.d.ts

@@ -1,38 +0,0 @@
-/**
- * AuctionActions Component
- *
- * Bid form and action buttons for auction operations.
- */
-export type AuctionStatus = "open" | "bidding" | "winning" | "outbid" | "won" | "lost" | "ended";
-export interface AuctionActionsProps {
-    /** Current auction status */
-    status: AuctionStatus;
-    /** Current highest bid */
-    currentBid: number;
-    /** Minimum next bid */
-    minNextBid: number;
-    /** Bid increment */
-    bidIncrement: number;
-    /** Place bid handler */
-    onBid?: (amount: number) => void;
-    /** Proceed to checkout handler (for won status) */
-    onProceed?: () => void;
-    /** Whether bid is in progress */
-    isBidding?: boolean;
-    /** Bid button label */
-    bidLabel?: string;
-    /** Proceed button label */
-    proceedLabel?: string;
-    /** Currency code (ISO 4217). */
-    currencyCode?: string;
-    /** Locale used for formatting */
-    locale?: string;
-    /** Show quick bid buttons */
-    showQuickBids?: boolean;
-    /** Additional class name */
-    className?: string;
-}
-export declare function AuctionActions({ status, currentBid, minNextBid, bidIncrement, onBid, onProceed, isBidding, bidLabel, proceedLabel, currencyCode, locale, showQuickBids, className, }: AuctionActionsProps): import("react/jsx-runtime").JSX.Element;
-export declare namespace AuctionActions {
-    var displayName: string;
-}

package/dist/components/widgets/auction/auction-bid-display.d.ts

@@ -1,35 +0,0 @@
-/**
- * AuctionBidDisplay Component
- *
- * Displays the current bid amount and auction status.
- */
-export interface AuctionBidDisplayProps {
-    /** Current highest bid */
-    currentBid: number;
-    /** User's bid (if any) */
-    myBid?: number | null;
-    /** Minimum next bid */
-    minNextBid: number;
-    /** Bid increment */
-    bidIncrement: number;
-    /** Reserve price */
-    reservePrice?: number;
-    /** Whether reserve is met */
-    reserveMet?: boolean;
-    /** Total number of bids */
-    bidCount?: number;
-    /** Whether the user is winning */
-    isWinning?: boolean;
-    /** Currency code (ISO 4217). */
-    currencyCode?: string;
-    /** Locale used for formatting */
-    locale?: string;
-    /** Visual size */
-    size?: "sm" | "md" | "lg";
-    /** Additional class name */
-    className?: string;
-}
-export declare function AuctionBidDisplay({ currentBid, myBid, minNextBid, bidIncrement, reservePrice, reserveMet, bidCount, isWinning, currencyCode, locale, size, className, }: AuctionBidDisplayProps): import("react/jsx-runtime").JSX.Element;
-export declare namespace AuctionBidDisplay {
-    var displayName: string;
-}

package/dist/components/widgets/auction/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * Auction Widget Internal Components
- *
- * Building blocks for the AuctionWidget.
- */
-export { AuctionActions, type AuctionActionsProps, type AuctionStatus } from './auction-actions';
-export { AuctionBidDisplay, type AuctionBidDisplayProps } from './auction-bid-display';

package/dist/components/widgets/waitlist/waitlist-actions.d.ts

@@ -1,40 +0,0 @@
-/**
- * WaitlistActions Component
- *
- * Action buttons for waitlist operations (enter, leave, share).
- */
-export type WaitlistStatus = "available" | "entered" | "opening" | "opened";
-export interface WaitlistActionsProps {
-    /** Current waitlist status */
-    status: WaitlistStatus;
-    /** Enter waitlist handler */
-    onEnter?: () => void;
-    /** Leave waitlist handler */
-    onLeave?: () => void;
-    /** Share position handler */
-    onShare?: () => void;
-    /** Proceed handler (when opened) */
-    onProceed?: () => void;
-    /** Whether enter is in progress */
-    isEntering?: boolean;
-    /** Whether leave is in progress */
-    isLeaving?: boolean;
-    /** Enter button label */
-    enterLabel?: string;
-    /** Leave button label */
-    leaveLabel?: string;
-    /** Share button label */
-    shareLabel?: string;
-    /** Proceed button label */
-    proceedLabel?: string;
-    /** Show share button */
-    showShare?: boolean;
-    /** Layout direction */
-    layout?: "horizontal" | "vertical";
-    /** Additional class name */
-    className?: string;
-}
-export declare function WaitlistActions({ status, onEnter, onLeave, onShare, onProceed, isEntering, isLeaving, enterLabel, leaveLabel, shareLabel, proceedLabel, showShare, layout, className, }: WaitlistActionsProps): import("react/jsx-runtime").JSX.Element;
-export declare namespace WaitlistActions {
-    var displayName: string;
-}

package/docs/SLOTS.md

@@ -1,89 +0,0 @@
-# ExperienceWidget Slots
-
-`ExperienceWidget` slots are render props for targeted UI overrides. Each slot is called only when the matching journey or sequence state is active; all other states keep the default Fanfare UI.
-
-The slot surface is derived from the same model as `JourneyView`: `journeyStage` -> `sequence.phase` -> `sequence.mechanism`. Actions are not serialized as a separate source of truth, and the server stays authoritative over what is permitted.
-
-Use `children` or `useExperienceJourney` when you need to replace the full widget. Use `slots` when the default flow is correct and a specific state needs custom UI.
-
-## Shared Props
-
-Every slot receives:
-
-- `snapshot`: the current `JourneySnapshot | null`.
-- `view`: the current `JourneyView | null`.
-- `error`: the current widget error string, or `null`.
-
-## Journey Slots
-
-| Slot         | Meaningful state                                              | Extra props                                               |
-| ------------ | ------------------------------------------------------------- | --------------------------------------------------------- |
-| `start`      | `journeyStage: "ready"`                                       | `onStart`, `isStarting`                                   |
-| `loading`    | `journeyStage: "routing"`, gated loading, or fallback loading | `message?`                                                |
-| `auth`       | `journeyStage: "gated"` with an auth gate                     | `onSubmit`, `onVerify`, `onSkip?`                         |
-| `accessCode` | `journeyStage: "gated"` with an access-code gate              | `onSubmit`, `onSkip?`                                     |
-| `challenge`  | `journeyStage: "gated"` with a bot-check gate                 | `challenge`, `botMitigation?`, `onVerifyToken`, `onRetry` |
-| `error`      | Widget action or loading error                                | `error`, `onRetry`                                        |
-
-## Routed Sequence Slots
-
-| Slot            | Meaningful state                                | Mechanisms                                                 | Extra props                                      |
-| --------------- | ----------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------ |
-| `upcoming`      | `phase: "scheduled"`                            | `queue`, `draw`, `auction`, `timed_release`, `appointment` | `startsAt?`, `canEnter`, `onEnter`, `isEntering` |
-| `upcoming`      | `phase: "enterable"`                            | `waitlist`                                                 | `startsAt?`, `canEnter`, `onEnter`, `isEntering` |
-| `waitlist`      | `phase: "participating"`                        | `waitlist`                                                 | `startsAt?`, `onLeave`, `isLeaving`              |
-| `enterable`     | `phase: "enterable"`                            | `queue`, `draw`, `auction`, `timed_release`, `appointment` | `sequence`, `participationType`                  |
-| `participating` | `phase: "participating"`                        | `queue`, `draw`, `auction`, `timed_release`, `appointment` | `sequence`, `participationType`, `position?`     |
-| `granted`       | `phase: "granted"`                              | `queue`, `draw`, `auction`, `timed_release`                | `sequence`, `grant?`, `expiresAt?`               |
-| `expired`       | `phase: "ended"` with `outcome.type: "expired"` | any ended mechanism                                        | `reason`, `endedAt?`                             |
-| `ended`         | `phase: "unavailable"` or `phase: "ended"`      | any ended mechanism                                        | `reason`, `endedAt?`                             |
-
-There is no slot for `phase: "settling"`; `draw` and `auction` render their default settling modules. There is no `granted` state for `appointment` or `waitlist`. The `ended` slot also renders `phase: "unavailable"` for convenience; `unavailable` is not a terminal phase.
-
-## `slots.enterable`
-
-`slots.enterable` receives the typed `sequence` view. Call the method exposed for that exact `phase` and `mechanism`.
-
-```tsx
-<ExperienceWidget
-  experienceId="exp_123"
-  slots={{
-    enterable: ({ sequence, participationType }) => {
-      if (sequence.mechanism === "auction") {
-        return <button onClick={() => void sequence.bid("125.00")}>Bid</button>;
-      }
-      if (sequence.mechanism === "appointment") {
-        return <button onClick={() => void sequence.book("slot_123")}>Book</button>;
-      }
-      return <button onClick={() => void sequence.enter()}>Enter {participationType}</button>;
-    },
-  }}
-/>
-```
-
-`participationType` is the slot prop carrying `sequence.mechanism` for the five non-waitlist mechanisms: `queue`, `draw`, `auction`, `timed_release`, or `appointment`. See the Mechanisms section of the core SDK `JOURNEY_MODEL.md`.
-
-## `slots.participating`
-
-`slots.participating` receives the typed `sequence` view for `queue`, `draw`, `auction`, `timed_release`, and `appointment`.
-
-- `queue`, `draw`: `state$`, `leave()`.
-- `auction`: `state$`, `bid(amount)`, `leave()`.
-- `timed_release`: `state$`, `leave()`, `complete()`.
-- `appointment`: `state$`, `cancel(reason?)`, `reschedule(newSlotId, newLocationId?)`.
-
-`position` is populated when queue display state includes a queue position.
-
-## Default Rendering
-
-Without a slot:
-
-- `ready` uses `StartView`.
-- `routing` and loading fallbacks use `LoadingView`.
-- `gated` uses `JourneyGate` or `ChallengeGate`.
-- `scheduled` and enterable `waitlist` use `UpcomingModule`.
-- participating `waitlist` uses `WaitlistView`.
-- `queue`, `draw`, `auction`, `timed_release`, and `appointment` use their default modules for supported phases.
-- `granted` uses the distribution module's granted panel.
-- `ended` uses the distribution module's outcome UI for `queue`, `draw`, `auction`, `timed_release`, and `appointment`; `unavailable` uses `EndedModule`.
-- ended `waitlist` can be handled with `slots.ended` or full custom rendering.

package/docs/STYLING.md

@@ -1,61 +0,0 @@
-# Styling Reference
-
-`@fanfare-io/fanfare-sdk-react` ships dressed components — `ExperienceWidget`, the
-sequence modules, and slot helpers — that read from a single theme context.
-Most customers should rely on the defaults, then override at four levels of
-increasing specificity:
-
-1. `theme` for brand colors, typography, and imagery
-2. `variant` for packaged presentation styles
-3. `slots` for swapping specific journey or sequence states
-4. `children` or `useExperienceJourney` for full custom rendering
-
-The rendered surface follows the SDK model: `journeyStage`, then
-`sequence.phase`, then `sequence.mechanism`. Styling changes presentation only;
-the server stays authoritative over which actions are permitted.
-
-## Theme
-
-Pass a `BrandTheme` to `ThemeProvider` or directly to `ExperienceWidget`.
-
-```tsx
-<ThemeProvider theme={{ primary: "#0f766e", fontHeading: "Instrument Serif, serif" }}>
-  <ExperienceWidget experienceId="exp_123" />
-</ThemeProvider>
-```
-
-Per-widget overrides are shallow-merged over the current theme.
-
-## Variant
-
-`ExperienceWidget` supports packaged variants:
-
-- `default`
-- `retro`
-- `rounded`
-- `clean`
-
-Use variants for presentation differences, not for business logic.
-
-## Slots
-
-Replace specific sections with slots — the slot's render prop is called when
-that state is active. All other states keep their default rendering.
-
-```tsx
-<ExperienceWidget
-  experienceId="exp_123"
-  slots={{
-    upcoming: ({ startsAt, onEnter }) => <YourUpcomingCard startsAt={startsAt} onCta={onEnter} />,
-  }}
-/>
-```
-
-See [`docs/SLOTS.md`](./SLOTS.md) for the full slot inventory.
-
-## Custom rendering
-
-For full control, pass `children` to `ExperienceWidget` (a render prop
-receiving `{ journey, view, snapshot, error, start, isStarting }`) or assemble
-your own UI from `useExperienceJourney`. This is the lowest-level integration
-and bypasses slots entirely.