@funnelsgrove/cli 0.1.14 → 0.1.18

package/template_scaffold/src/steps/paywall-checkout-options.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildPaywallCheckoutBillingDetails,
+  buildPaywallCheckoutExpressOptions,
+  buildPaywallCheckoutPaymentElementOptions,
+} from './paywall-checkout-options';
+
+describe('paywall checkout options', () => {
+  it('prioritizes Link and stacked express checkout buttons for the checkout dialog', () => {
+    const options = buildPaywallCheckoutExpressOptions({
+      amountCents: 3599,
+      summaryLabel: 'ClaimBee Pro · 3 Months',
+    });
+
+    expect(options.paymentMethodOrder).toEqual(['link', 'apple_pay', 'google_pay']);
+    expect(options.buttonHeight).toBe(55);
+    expect(options.layout).toEqual({
+      maxColumns: 1,
+      maxRows: 0,
+      overflow: 'never',
+    });
+    expect(options.paymentMethods).toMatchObject({
+      applePay: 'always',
+      googlePay: 'always',
+      amazonPay: 'never',
+      klarna: 'never',
+      paypal: 'never',
+    });
+    expect(options.lineItems).toEqual([
+      {
+        name: 'ClaimBee Pro · 3 Months',
+        amount: 3599,
+      },
+    ]);
+  });
+
+  it('keeps the card form focused on manual card entry while prefilling the known email', () => {
+    const options = buildPaywallCheckoutPaymentElementOptions({
+      email: 'jane@example.com',
+    });
+
+    expect(options.paymentMethodOrder).toEqual(['card']);
+    expect(options.wallets).toEqual({
+      applePay: 'never',
+      googlePay: 'never',
+      link: 'never',
+    });
+    expect(options.fields).toEqual({
+      billingDetails: {
+        address: 'if_required',
+        email: 'never',
+        name: 'never',
+        phone: 'auto',
+      },
+    });
+    expect(options.defaultValues).toEqual({
+      billingDetails: {
+        email: 'jane@example.com',
+      },
+    });
+    expect(options.layout).toEqual({
+      type: 'tabs',
+    });
+  });
+
+  it('shows the email field when the funnel has not collected one yet', () => {
+    const options = buildPaywallCheckoutPaymentElementOptions({});
+
+    expect(options.fields).toEqual({
+      billingDetails: {
+        address: 'if_required',
+        email: 'auto',
+        name: 'never',
+        phone: 'auto',
+      },
+    });
+    expect(options.defaultValues).toBeUndefined();
+  });
+
+  it('supplies hidden billing details when the checkout form omits the name field', () => {
+    expect(
+      buildPaywallCheckoutBillingDetails({
+        email: 'jane.doe@example.com',
+        name: 'Jane Doe',
+      }),
+    ).toEqual({
+      email: 'jane.doe@example.com',
+      name: 'Jane Doe',
+    });
+
+    expect(
+      buildPaywallCheckoutBillingDetails({
+        email: 'jane.doe@example.com',
+      }),
+    ).toEqual({
+      email: 'jane.doe@example.com',
+      name: 'jane doe',
+    });
+
+    expect(buildPaywallCheckoutBillingDetails({})).toEqual({
+      name: 'Customer',
+    });
+  });
+});

package/template_scaffold/src/steps/paywall-checkout-options.ts

@@ -0,0 +1,130 @@
+import type {
+  StripeExpressCheckoutElementOptions,
+  StripePaymentElementOptions,
+} from '@stripe/stripe-js';
+
+type PaywallCheckoutExpressOptionsInput = {
+  amountCents: number;
+  summaryLabel: string;
+};
+
+type PaywallCheckoutPaymentElementOptionsInput = {
+  email?: string | null;
+};
+
+type PaywallCheckoutBillingDetailsInput = {
+  email?: string | null;
+  name?: string | null;
+};
+
+const normalizePaywallCheckoutBillingName = ({
+  email,
+  name,
+}: PaywallCheckoutBillingDetailsInput): string => {
+  const normalizedName = name?.trim();
+  if (normalizedName) {
+    return normalizedName;
+  }
+
+  const normalizedEmail = email?.trim();
+  if (normalizedEmail) {
+    const localPart = normalizedEmail
+      .split('@')[0]
+      ?.replace(/[._-]+/g, ' ')
+      .trim();
+    if (localPart) {
+      return localPart;
+    }
+  }
+
+  return 'Customer';
+};
+
+export function buildPaywallCheckoutExpressOptions({
+  amountCents,
+  summaryLabel,
+}: PaywallCheckoutExpressOptionsInput): StripeExpressCheckoutElementOptions {
+  return {
+    buttonHeight: 55,
+    buttonTheme: {
+      applePay: 'black',
+      googlePay: 'black',
+    },
+    buttonType: {
+      applePay: 'check-out',
+      googlePay: 'checkout',
+    },
+    emailRequired: true,
+    layout: {
+      maxColumns: 1,
+      maxRows: 0,
+      overflow: 'never',
+    },
+    lineItems: [
+      {
+        name: summaryLabel.trim() || 'Selected plan',
+        amount: amountCents,
+      },
+    ],
+    paymentMethodOrder: ['link', 'apple_pay', 'google_pay'],
+    paymentMethods: {
+      amazonPay: 'never',
+      applePay: 'always',
+      googlePay: 'always',
+      klarna: 'never',
+      paypal: 'never',
+    },
+  };
+}
+
+export function buildPaywallCheckoutPaymentElementOptions({
+  email,
+}: PaywallCheckoutPaymentElementOptionsInput): StripePaymentElementOptions {
+  const normalizedEmail = email?.trim() || '';
+  const emailFieldMode = normalizedEmail ? 'never' : 'auto';
+
+  return {
+    defaultValues: normalizedEmail
+      ? {
+          billingDetails: {
+            email: normalizedEmail,
+          },
+        }
+      : undefined,
+    fields: {
+      billingDetails: {
+        address: 'if_required',
+        email: emailFieldMode,
+        name: 'never',
+        phone: 'auto',
+      },
+    },
+    layout: {
+      type: 'tabs',
+    },
+    paymentMethodOrder: ['card'],
+    wallets: {
+      applePay: 'never',
+      googlePay: 'never',
+      link: 'never',
+    },
+  };
+}
+
+export function buildPaywallCheckoutBillingDetails({
+  email,
+  name,
+}: PaywallCheckoutBillingDetailsInput): {
+  email?: string;
+  name: string;
+} {
+  const normalizedEmail = email?.trim() || undefined;
+
+  return {
+    email: normalizedEmail,
+    name: normalizePaywallCheckoutBillingName({
+      email: normalizedEmail,
+      name,
+    }),
+  };
+}

package/template_scaffold/src/steps/pricing/paywall-b.pricing.ts

@@ -0,0 +1,12 @@
+import type { CountryPricingProfile } from '@funnelsgrove/runtime';
+import {
+  defaultPaywallPlanKey,
+  defaultPaywallPlanOrder,
+  paywallCountryOverrides,
+} from './shared-plan-order';
+
+export const paywallBPricing = {
+  defaultOfferOrder: defaultPaywallPlanOrder,
+  defaultOfferKey: defaultPaywallPlanKey,
+  countryOverrides: paywallCountryOverrides,
+} as const satisfies CountryPricingProfile<string>;

package/template_scaffold/src/steps/pricing/paywall.pricing.ts

@@ -0,0 +1,12 @@
+import type { CountryPricingProfile } from '@funnelsgrove/runtime';
+import {
+  defaultPaywallPlanKey,
+  defaultPaywallPlanOrder,
+  paywallCountryOverrides,
+} from './shared-plan-order';
+
+export const paywallPricing = {
+  defaultOfferOrder: defaultPaywallPlanOrder,
+  defaultOfferKey: defaultPaywallPlanKey,
+  countryOverrides: paywallCountryOverrides,
+} as const satisfies CountryPricingProfile<string>;

package/template_scaffold/src/steps/pricing/shared-plan-order.ts

@@ -0,0 +1,17 @@
+const basePlanOrder = ['primary', 'secondary'] as const;
+const secondaryFirstPlanOrder = ['secondary', 'primary'] as const;
+const secondaryFirstCountries = ['PT', 'DE'] as const;
+
+export const defaultPaywallPlanOrder = [...basePlanOrder];
+export const defaultPaywallPlanKey = basePlanOrder[0];
+export const secondaryFirstPaywallPlanOrder = [...secondaryFirstPlanOrder];
+export const secondaryFirstPaywallPlanKey = secondaryFirstPlanOrder[0];
+export const paywallCountryOverrides = Object.fromEntries(
+  secondaryFirstCountries.map((countryCode) => [
+    countryCode,
+    {
+      defaultOfferKey: secondaryFirstPaywallPlanKey,
+      offerOrder: secondaryFirstPaywallPlanOrder,
+    },
+  ]),
+);

package/template_scaffold/src/steps/pricing/upsell-form.pricing.ts

@@ -0,0 +1,16 @@
+import type { CountryPricingProfile } from '@funnelsgrove/runtime';
+import {
+  secondaryFirstPaywallPlanKey,
+  secondaryFirstPaywallPlanOrder,
+} from './shared-plan-order';
+
+export const upsellFormPricing = {
+  defaultOfferOrder: secondaryFirstPaywallPlanOrder,
+  defaultOfferKey: secondaryFirstPaywallPlanKey,
+  countryOverrides: {
+    US: {
+      defaultOfferKey: secondaryFirstPaywallPlanKey,
+      offerOrder: secondaryFirstPaywallPlanOrder,
+    },
+  },
+} as const satisfies CountryPricingProfile<string>;

package/template_scaffold/src/steps/shared-header-contract.test.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const readStepSource = (fileName: string): string =>
+  readFileSync(path.resolve(__dirname, fileName), 'utf8');
+
+describe('template shared header contract', () => {
+  it('renders template step headers through the shared FunnelStepHeader component', () => {
+    const sharedHeaderSource = readStepSource('../components/step/FunnelStepHeader.tsx');
+
+    expect(sharedHeaderSource).toContain('export type FunnelStepHeaderProps');
+    expect(sharedHeaderSource).toContain('export function FunnelStepHeader');
+
+    const headerStepFiles = [
+      'step-01.tsx',
+      'step-02.tsx',
+      'step-04.tsx',
+    ];
+
+    headerStepFiles.forEach((fileName) => {
+      const stepSource = readStepSource(fileName);
+      expect(stepSource).toContain("from '@/components/step/FunnelStepHeader'");
+      expect(stepSource).toContain('<FunnelStepHeader');
+    });
+  });
+});

package/template_scaffold/src/steps/step-01.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { stepOneContent } from '@/steps/content/step-01.content';
+import {
+  resolveStepOneArtworkSrc,
+  resolveStepOneImportedAssetSrc,
+} from '@/steps/step-01';
+
+describe('StepOne helpers', () => {
+  it('falls back to the bundled sprite when configured artwork failed to load', () => {
+    expect(
+      resolveStepOneArtworkSrc(
+        {
+          src: 'https://example.com/missing-step-one.png',
+          alt: 'Broken step one artwork',
+        },
+        '/claimbee/steps-sprite-default.png',
+        true,
+      ),
+    ).toBe('/claimbee/steps-sprite-default.png');
+  });
+
+  it('normalizes imported sprite assets from both preview and Next runtimes', () => {
+    expect(resolveStepOneImportedAssetSrc('/claimbee/steps-sprite-default.png')).toBe(
+      '/claimbee/steps-sprite-default.png',
+    );
+    expect(resolveStepOneImportedAssetSrc({ src: '/claimbee/steps-sprite-default.png' })).toBe(
+      '/claimbee/steps-sprite-default.png',
+    );
+  });
+
+  it('ships ClaimBee-style default headline copy', () => {
+    expect(stepOneContent.locales.en.headline).toEqual([
+      'People getting',
+      'free money',
+      'know one secret',
+    ]);
+  });
+});

package/template_scaffold/src/steps/step-01.tsx

@@ -0,0 +1,108 @@
+import { useState } from 'react';
+import { FunnelStepImage } from '@/components/FunnelStepImage';
+import { FunnelStepHeader } from '@/components/step/FunnelStepHeader';
+import {
+  usePreviewStepLocalizedContent,
+  useFunnel,
+  type StepImage,
+  type FunnelStepMeta,
+} from '@funnelsgrove/runtime';
+import stepsSpriteDefault from '@/assets/claimbee/steps-sprite-default.png';
+import { getStepContentLocale } from '@/runtime/step-content-context';
+import { stepOneContent } from '@/steps/content/step-01.content';
+
+export const stepOneId = 'step-1';
+
+type ImportedStepAsset = string | { src: string };
+
+export const resolveStepOneImportedAssetSrc = (asset: ImportedStepAsset): string => {
+  return typeof asset === 'string' ? asset : asset.src;
+};
+
+export const resolveStepOneArtworkSrc = (
+  artwork: StepImage | null | undefined,
+  fallbackSrc: string,
+  hasLoadError = false,
+): string => {
+  const configuredSrc = artwork?.src?.trim() || '';
+  if (!hasLoadError && configuredSrc) {
+    return configuredSrc;
+  }
+
+  return fallbackSrc;
+};
+
+const stepOneFallbackArtworkSrc = resolveStepOneImportedAssetSrc(stepsSpriteDefault);
+
+export const stepOne: FunnelStepMeta = {
+  id: stepOneId,
+  name: 'step-1',
+  type: 'intro_hero',
+  figmaNodeId: 'template-01-intro',
+  title: 'People getting free money know one secret',
+  description: 'ClaimBee-style opening hero with resilient sprite fallback.',
+};
+
+export function StepOne() {
+  const { attributes } = useFunnel();
+  const content = usePreviewStepLocalizedContent(
+    stepOneId,
+    stepOneContent,
+    getStepContentLocale(attributes),
+  );
+  const configuredArtworkSrc = content.artwork.src?.trim() || '';
+  const [failedArtworkSrc, setFailedArtworkSrc] = useState<string | null>(null);
+  const artworkSrc = resolveStepOneArtworkSrc(
+    content.artwork,
+    stepOneFallbackArtworkSrc,
+    Boolean(configuredArtworkSrc) && failedArtworkSrc === configuredArtworkSrc,
+  );
+
+  return (
+    <>
+      <section className="figma-step-screen step-one-screen" data-node-id="template:01-intro">
+        <FunnelStepHeader
+          className="figma-headline"
+          titleAs="div"
+          title={
+            <>
+              <p className="figma-headline-line">{content.headline[0]}</p>
+              <p className="figma-headline-line is-accent">{content.headline[1]}</p>
+              <p className="figma-headline-line">{content.headline[2]}</p>
+            </>
+          }
+        />
+
+        <div className="figma-artwork" aria-hidden>
+          <FunnelStepImage
+            src={artworkSrc}
+            alt={content.artwork.alt || ''}
+            width={stepsSpriteDefault.width}
+            height={stepsSpriteDefault.height}
+            className="figma-artwork-sprite"
+            draggable={false}
+            priority
+            onError={() => {
+              if (configuredArtworkSrc) {
+                setFailedArtworkSrc(configuredArtworkSrc);
+              }
+            }}
+          />
+        </div>
+      </section>
+
+      {stepOneStyles ? <style>{stepOneStyles}</style> : null}
+    </>
+  );
+}
+
+const stepOneStyles = `
+.step-one-screen {
+  --sprite-offset-x: 0px;
+  background: var(--color-bg-warning);
+}
+
+.step-one-screen .figma-headline-line.is-accent {
+  color: var(--color-primary);
+}
+`;

package/template_scaffold/src/steps/step-02.test.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { stepTwoContent, stepTwoOptions } from './content/step-02.content';
+import { stepTwo } from './step-02';
+
+const stepSource = readFileSync(path.resolve(__dirname, './step-02.tsx'), 'utf8');
+
+describe('StepTwo', () => {
+  it('declares its typed multi-select answer contract and immutable option IDs', () => {
+    expect(stepTwo.choice).toEqual({
+      answerKey: 'selectedDevices',
+      allowEmpty: true,
+    });
+    expect(stepTwoOptions.map((option) => option.id)).toEqual([
+      'iphone',
+      'laptop',
+      'watch',
+      'none',
+    ]);
+    expect(Object.isFrozen(stepTwoOptions)).toBe(true);
+    expect(stepTwoOptions.every((option) => Object.isFrozen(option))).toBe(true);
+  });
+
+  it('owns explicit typed completion instead of writing choices continuously', () => {
+    expect(stepTwo.actionBar).toEqual({ hidden: true });
+    expect(stepTwoContent.locales.en.continueLabel).toBe('Continue');
+    expect(stepSource).toContain('useStepChoices(stepTwo, stepTwoOptions)');
+    expect(stepSource).toContain('<PrimaryButton');
+    expect(stepSource).toContain('{content.continueLabel}');
+    expect(stepSource).toContain('completeMulti(selectedIds)');
+    expect(stepSource).not.toContain('useEffect');
+    expect(stepSource).not.toContain('setAnswer');
+  });
+
+  it('exposes each native choice button and its selected state to assistive technology', () => {
+    expect(stepSource).toContain('role="group"');
+    expect(stepSource).not.toContain('role="list"');
+    expect(stepSource).not.toContain('role="listitem"');
+    expect(stepSource).toContain('aria-pressed={isSelected}');
+    expect(stepSource).toContain('aria-hidden="true"');
+  });
+});

package/template_scaffold/src/steps/step-02.tsx

@@ -0,0 +1,140 @@
+import { useMemo, useState } from 'react';
+import { FunnelStepImage } from '@/components/FunnelStepImage';
+import { FunnelStepHeader } from '@/components/step/FunnelStepHeader';
+import { getStepContentLocale } from '@/runtime/step-content-context';
+import {
+  stepTwoContent,
+  stepTwoOptions,
+  type StepTwoOptionId,
+} from '@/steps/content/step-02.content';
+import {
+  PrimaryButton,
+  usePreviewStepLocalizedContent,
+  useFunnel,
+  useStepChoices,
+  type FunnelStepMeta,
+} from '@funnelsgrove/runtime';
+
+export const stepTwoId = 'step-2';
+
+export const stepTwo: FunnelStepMeta = {
+  id: stepTwoId,
+  name: 'step-2',
+  type: 'multi_select_choice',
+  choice: {
+    answerKey: 'selectedDevices',
+    allowEmpty: true,
+  },
+  figmaNodeId: 'template-02-devices',
+  title: 'Step 2',
+  description: 'Device selection step with visual options.',
+  actionBar: {
+    hidden: true,
+  },
+};
+
+export function StepTwo() {
+  const { attributes } = useFunnel();
+  const { completeMulti } = useStepChoices(stepTwo, stepTwoOptions);
+  const [selectedIds, setSelectedIds] = useState<StepTwoOptionId[]>([]);
+  const content = usePreviewStepLocalizedContent(
+    stepTwoId,
+    stepTwoContent,
+    getStepContentLocale(attributes),
+  );
+
+  const selectedLookup = useMemo(() => new Set(selectedIds), [selectedIds]);
+
+  const toggleOption = (optionId: StepTwoOptionId) => {
+    setSelectedIds((prev) => {
+      const exists = prev.includes(optionId);
+      return exists ? prev.filter((id) => id !== optionId) : [...prev, optionId];
+    });
+  };
+
+  return (
+    <>
+      <section className="devices-step" data-node-id="template:02-devices">
+        <FunnelStepHeader
+          className="devices-header"
+          titleClassName="devices-title"
+          title={
+            <>
+              {content.title[0]}
+              <br />
+              <span className="is-accent">{content.title[1]}</span>
+            </>
+          }
+          subtitle={content.description}
+          subtitleClassName="devices-description"
+        />
+
+        <div className="devices-options" role="group" aria-label={content.optionsLabel}>
+          {content.options.map((option) => {
+            const isSelected = selectedLookup.has(option.id);
+
+            return (
+              <button
+                key={option.id}
+                type="button"
+                aria-pressed={isSelected}
+                className={
+                  isSelected
+                    ? 'device-option is-interactive is-selected'
+                    : 'device-option is-interactive'
+                }
+                onClick={() => toggleOption(option.id)}
+              >
+                <span className="device-option-main">
+                  <FunnelStepImage
+                    src={option.image.src}
+                    alt={option.image.alt || ''}
+                    width={42}
+                    height={42}
+                    className="device-option-image"
+                    draggable={false}
+                  />
+                  <span className="device-option-label">{option.label}</span>
+                </span>
+
+                <span
+                  className={isSelected ? 'device-option-checkbox is-selected' : 'device-option-checkbox'}
+                  aria-hidden="true"
+                >
+                  {isSelected ? <span className="device-option-checkbox-icon">✓</span> : null}
+                </span>
+              </button>
+            );
+          })}
+        </div>
+      </section>
+
+      <footer className="action-bar">
+        <PrimaryButton onClick={() => completeMulti(selectedIds)}>
+          {content.continueLabel}
+        </PrimaryButton>
+      </footer>
+
+      {stepTwoStyles ? <style>{stepTwoStyles}</style> : null}
+    </>
+  );
+}
+
+const stepTwoStyles = `
+.device-option {
+  cursor: pointer;
+}
+
+.device-option-image {
+  width: 42px;
+  height: 42px;
+  object-fit: contain;
+  border-radius: 8px;
+}
+
+.device-option-checkbox-icon {
+  font-size: 12px;
+  line-height: 1;
+  font-weight: 800;
+}
+`;

package/template_scaffold/src/steps/step-03.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { resolveStepThreeAutoAdvanceMs, stepThree } from './step-03';
+
+describe('StepThree', () => {
+  it('keeps the shell action bar hidden because the step owns its own auto-advance behavior', () => {
+    expect(stepThree.actionBar).toEqual({
+      hidden: true,
+    });
+  });
+
+  it('disables auto-advance when the funnel is rendered inside builder preview', () => {
+    expect(resolveStepThreeAutoAdvanceMs(true)).toBeNull();
+    expect(resolveStepThreeAutoAdvanceMs(false)).toBe(2200);
+  });
+});