@fanfare-io/fanfare-sdk-solid 0.1.0

package/dist/styles/index.d.ts

@@ -0,0 +1,2 @@
+export { default as baseStyles } from './base.css?inline';
+export { default as themeStyles } from './theme.css?inline';

package/dist/styles/theme.css

@@ -0,0 +1,82 @@
+@theme {
+  /* Core colors - overridden by ThemeProvider inline styles */
+  --color-primary: #1d1f27;
+  --color-primary-foreground: #ffffff;
+  --color-secondary: #f4f4f5;
+  --color-background: #ffffff;
+  --color-surface: #ffffff;
+  --color-surface-foreground: #1d1f27;
+  --color-foreground: #1d1f27;
+  --color-muted: #4b4e56cc;
+  --color-muted-foreground: #4b4e5699;
+  --color-border: #4b4e5666;
+
+  /* Status colors */
+  --color-success: oklch(0.77 0.18 130);
+  --color-success-foreground: #111111;
+  --color-warning: oklch(0.72 0.18 65);
+  --color-warning-foreground: #111111;
+  --color-danger: oklch(0.63 0.24 25);
+  --color-danger-foreground: #ffffff;
+
+  /* Typography */
+  --font-sans: "Inter", system-ui, sans-serif;
+  --font-heading: "Inter", system-ui, sans-serif;
+
+  /* Extension below Tailwind's default `text-xs` (12px) for badge / pill / micro-label copy. */
+  --text-xxs: 0.625rem;
+  --text-xxs--line-height: 0.875rem;
+}
+
+@layer base {
+  /**
+   * Default theme values for .fanfare-themed elements.
+   * ThemeProvider overrides these via inline styles.
+   */
+  .fanfare-themed {
+    font-family: var(--ff-font-sans);
+    color: var(--ff-color-foreground);
+    background-color: var(--ff-color-background);
+  }
+
+  /**
+   * Ensure all descendants inherit border and outline colors
+   */
+  .fanfare-themed *,
+  .fanfare-themed ::after,
+  .fanfare-themed ::before,
+  .fanfare-themed ::backdrop,
+  .fanfare-themed ::file-selector-button {
+    border-color: var(--ff-color-border);
+    outline-color: var(--ff-color-border);
+  }
+
+  /**
+   * Interactive elements
+   */
+  .fanfare-themed button:not(:disabled),
+  .fanfare-themed [role="button"]:not(:disabled) {
+    cursor: pointer;
+  }
+
+  /**
+   * Focus styles
+   */
+  .fanfare-themed :focus-visible {
+    outline: 2px solid var(--ff-color-primary);
+    outline-offset: 2px;
+  }
+
+  /**
+   * Respect reduced motion preferences
+   */
+  @media (prefers-reduced-motion: reduce) {
+    .fanfare-themed *,
+    .fanfare-themed ::before,
+    .fanfare-themed ::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+}

package/dist/theme/index.d.ts

@@ -0,0 +1,8 @@
+export { ThemeContext, createMergedTheme, useThemeContext } from './theme-context';
+export type { ThemeContextValue } from './theme-context';
+export { ThemeProvider } from './theme-provider';
+export type { ThemeProviderProps } from './theme-provider';
+export { buildThemeCssVars } from './theme-utils';
+export { THEME_CSS_VARS } from './theme.types';
+export type { BrandTheme, ResolvedTheme, ThemeCssVar, WidgetThemeConfig, WidgetVariant } from './theme.types';
+export { useTheme, useThemeAndVariant, useVariant } from './use-theme';

package/dist/theme/theme-context.d.ts

@@ -0,0 +1,10 @@
+import { BrandTheme, WidgetVariant } from '@fanfare-io/fanfare-sdk-core/theme';
+import { Accessor } from 'solid-js';
+export interface ThemeContextValue {
+    theme: Accessor<BrandTheme>;
+    variant: Accessor<WidgetVariant>;
+    isRoot: boolean;
+}
+export declare const ThemeContext: import('solid-js').Context<ThemeContextValue>;
+export declare function useThemeContext(): ThemeContextValue;
+export declare function createMergedTheme(parent: ThemeContextValue, theme: Accessor<BrandTheme | null | undefined>, variant: Accessor<WidgetVariant | undefined>): ThemeContextValue;

package/dist/theme/theme-provider.d.ts

@@ -0,0 +1,15 @@
+import { BrandTheme, WidgetVariant } from '@fanfare-io/fanfare-sdk-core/theme';
+import { JSX } from 'solid-js';
+export interface ThemeProviderProps {
+    /** Theme overrides to merge with parent theme */
+    theme?: BrandTheme | null;
+    /** Widget variant (layout/density) */
+    variant?: WidgetVariant;
+    /** HTML element to render as wrapper */
+    as?: keyof JSX.IntrinsicElements;
+    /** Additional CSS classes */
+    className?: string;
+    /** Child components */
+    children: JSX.Element;
+}
+export declare function ThemeProvider(props: ThemeProviderProps): JSX.Element;

package/dist/theme/theme-utils.d.ts

@@ -0,0 +1,6 @@
+import { BrandTheme } from '@fanfare-io/fanfare-sdk-core/theme';
+/**
+ * Builds CSS custom property values from a theme.
+ * Used by ThemeProvider to apply theme as inline styles.
+ */
+export declare function buildThemeCssVars(theme: BrandTheme): Record<string, string>;

package/dist/theme/theme.types.d.ts

@@ -0,0 +1,47 @@
+import { BrandTheme, WidgetVariant } from '@fanfare-io/fanfare-sdk-core/theme';
+export type { BrandTheme, WidgetVariant } from '@fanfare-io/fanfare-sdk-core/theme';
+/**
+ * Extended theme configuration for widgets.
+ * Builds on BrandTheme from fanfare-sdk-core.
+ */
+export interface WidgetThemeConfig {
+    /** Base theme from experience configuration */
+    theme?: BrandTheme;
+    /** Layout/density variant (not related to colors) */
+    variant?: WidgetVariant;
+}
+/**
+ * Resolved theme with all defaults applied.
+ * This is what components receive from the theme context.
+ */
+export interface ResolvedTheme {
+    /** The fully-merged BrandTheme with defaults */
+    theme: BrandTheme;
+    /** The active variant */
+    variant: WidgetVariant;
+}
+/**
+ * CSS custom property names used by the theme system.
+ * Maps to Tailwind V4 variables with ff- prefix (--ff-color-*, --ff-font-*).
+ */
+export declare const THEME_CSS_VARS: {
+    readonly primary: "--ff-color-primary";
+    readonly primaryForeground: "--ff-color-primary-foreground";
+    readonly secondary: "--ff-color-secondary";
+    readonly background: "--ff-color-background";
+    readonly surface: "--ff-color-surface";
+    readonly surfaceForeground: "--ff-color-surface-foreground";
+    readonly foreground: "--ff-color-foreground";
+    readonly muted: "--ff-color-muted";
+    readonly mutedForeground: "--ff-color-muted-foreground";
+    readonly border: "--ff-color-border";
+    readonly success: "--ff-color-success";
+    readonly successForeground: "--ff-color-success-foreground";
+    readonly warning: "--ff-color-warning";
+    readonly warningForeground: "--ff-color-warning-foreground";
+    readonly danger: "--ff-color-danger";
+    readonly dangerForeground: "--ff-color-danger-foreground";
+    readonly fontFamily: "--ff-font-sans";
+    readonly fontHeading: "--ff-font-heading";
+};
+export type ThemeCssVar = (typeof THEME_CSS_VARS)[keyof typeof THEME_CSS_VARS];

package/dist/theme/use-theme.d.ts

@@ -0,0 +1,8 @@
+import { BrandTheme, WidgetVariant } from '@fanfare-io/fanfare-sdk-core/theme';
+import { Accessor } from 'solid-js';
+export declare function useTheme(): Accessor<BrandTheme>;
+export declare function useVariant(): Accessor<WidgetVariant>;
+export declare function useThemeAndVariant(): {
+    theme: Accessor<BrandTheme>;
+    variant: Accessor<WidgetVariant>;
+};

package/dist/utils/solid.d.ts

@@ -0,0 +1 @@
+export { cn, extractAriaProps, extractDataProps, fanfareClass } from '../lib/utils';

package/dist/utils/to-accessor.d.ts

@@ -0,0 +1,3 @@
+import { Accessor } from 'solid-js';
+export type MaybeAccessor<T> = T | Accessor<T>;
+export declare function toAccessor<T>(value: MaybeAccessor<T>): Accessor<T>;

package/docs/SLOTS.md

@@ -0,0 +1,91 @@
+# 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.
+
+The slot inventory and props match the React adapter; Solid slots are render props returning `JSX.Element` and read SDK state through Solid reactivity.
+
+## 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/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@fanfare-io/fanfare-sdk-solid",
+  "version": "0.1.0",
+  "description": "SolidJS web components for Fanfare experiences",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fanfare-io/fanfare-sdk.git"
+  },
+  "homepage": "https://docs.fanfare.io/sdk/components/web-components",
+  "bugs": {
+    "url": "https://github.com/fanfare-io/fanfare-sdk/issues"
+  },
+  "type": "module",
+  "files": [
+    "dist/",
+    "docs/",
+    "README.md"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles": {
+      "import": "./dist/styles/base.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.6"
+  },
+  "dependencies": {
+    "canvas-confetti": "^1.9.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "nanostores": "^1.1.0",
+    "solid-element": "^1.8.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"
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.1.8",
+    "@solidjs/testing-library": "^0.8.0",
+    "@storybook/addon-a11y": "^10.4.0",
+    "@storybook/addon-docs": "^10.4.0",
+    "@storybook/addon-themes": "^10.4.0",
+    "@storybook/addon-vitest": "~10.2.16",
+    "@tailwindcss/cli": "^4.1.16",
+    "@tailwindcss/vite": "^4.1.3",
+    "@testing-library/jest-dom": "^6.6.4",
+    "@types/testing-library__jest-dom": "^6.0.0",
+    "@vitest/browser": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "jsdom": "^26.1.0",
+    "playwright": "^1.51.1",
+    "prettier": "^3.5.3",
+    "prettier-plugin-organize-imports": "^4.1.0",
+    "rimraf": "^6.0.1",
+    "size-limit": "^11.1.8",
+    "solid-js": "^1.9.6",
+    "storybook": "^10.4.0",
+    "storybook-solidjs-vite": "^10.0.12",
+    "tailwindcss": "^4.1.3",
+    "tailwindcss-animate": "^1.0.7",
+    "typescript": "^5.9.2",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-solid": "^2.11.6",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4",
+    "@fanfare-io/fanfare-sdk-core": "0.1.0",
+    "@fanfare-io/fanfare-sdk-react": "0.1.0"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "keywords": [
+    "fanfare",
+    "solidjs",
+    "web-components",
+    "queue",
+    "ecommerce"
+  ],
+  "license": "Apache-2.0",
+  "size-limit": [
+    {
+      "name": "Solid adapter",
+      "path": "dist/index.js",
+      "limit": "50 KB",
+      "ignore": [
+        "solid-js",
+        "solid-js/web",
+        "@fanfare-io/fanfare-sdk-core",
+        "@fanfare-io/fanfare-sdk-core/internals",
+        "@fanfare-io/fanfare-sdk-core/test-utils",
+        "@fanfare-io/fanfare-sdk-i18n"
+      ]
+    }
+  ],
+  "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-react build:incremental",
+    "build": "vite build && tailwindcss -i src/styles/base.css -o dist/styles/base.css && pnpm size",
+    "build:incremental": "vite build --emptyOutDir false",
+    "build:strict": "pnpm typecheck && pnpm build",
+    "build-storybook": "storybook build",
+    "dev": "vite build --watch",
+    "fmt": "prettier src --write",
+    "lint": "oxlint src",
+    "lint:fix": "oxlint --fix src",
+    "size": "size-limit",
+    "storybook": "storybook dev -p 6008 --no-open",
+    "test": "vitest run",
+    "test:browser": "vitest run --project storybook",
+    "test:watch": "vitest",
+    "test:unit": "vitest run .unit.test.ts --passWithNoTests",
+    "test:component": "vitest run .test.tsx --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}