@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/billing/PlanCard/PlanCard.baseline.test.tsx

@@ -0,0 +1,26 @@
+import { render } from '@testing-library/react';
+import { PlanCard, type BillingPlan } from './PlanCard';
+
+const full: BillingPlan = {
+  name: 'Fixture Plan',
+  status: 'active',
+  priceMonthly: 10,
+  priceAnnual: 100,
+  currency: 'EUR',
+  renewsOn: '2027-01-01',
+  summary: '2 seats',
+  features: ['Feature A', 'Feature B'],
+};
+
+// Keep text-node spaces inline while retaining the exact rendered HTML baseline.
+describe('PlanCard billing DOM baseline', () => {
+  it('preserves the no-props billing header', () => {
+    const { container } = render(<PlanCard />);
+    expect(container.outerHTML).toMatchSnapshot();
+  });
+
+  it('preserves the FULL billing header', () => {
+    const { container } = render(<PlanCard plan={full} upgradeLabel="Upgrade" manageLabel="Manage" />);
+    expect(container.outerHTML).toMatchSnapshot();
+  });
+});

package/src/billing/PlanCard/PlanCard.summary.test.tsx

@@ -0,0 +1,227 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Button } from '@gntik-ai/ui';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { PlanCard, type PlanSummaryProps } from './PlanCard';
+
+const minimal = { name: 'Fixture Plan', statusLabel: 'Activo' };
+const full = {
+  ...minimal,
+  priceMonthly: 10,
+  priceAnnual: 100,
+  currency: 'EUR',
+  cycle: 'monthly' as const,
+  renewsOn: '2027-01-01',
+  features: ['Feature A', 'Feature B'],
+};
+const fixtures: Array<[string, Omit<PlanSummaryProps, 'variant'>]> = [
+  [
+    'FULL',
+    {
+      plan: full,
+      actions: (
+        <>
+          <Button>Upgrade</Button>
+          <Button>Manage</Button>
+        </>
+      ),
+    },
+  ],
+  ['MINIMAL', { plan: minimal }],
+  ['UNASSIGNED', { emptyLabel: 'Sin plan asignado' }],
+  ['UNASSIGNED-NO-LABEL', {}],
+  ['PRICE-ONLY', { plan: { ...minimal, priceMonthly: 10, currency: 'EUR' } }],
+  ['ZERO-PRICE', { plan: { ...minimal, priceMonthly: 0, currency: 'EUR' } }],
+  ['RENEWAL-ONLY', { plan: { ...minimal, renewsOn: '2027-01-01' } }],
+  ['FEATURES-ONLY', { plan: { ...minimal, features: ['Feature A'] } }],
+  ['ACTIONS-ONLY', { plan: minimal, actions: <Button>Manage</Button> }],
+];
+
+describe('PlanCard summary', () => {
+  it('renders all FULL values and focusable consumer actions', async () => {
+    const user = userEvent.setup();
+    render(<PlanCard variant="summary" {...fixtures[0]![1]} />);
+    expect(screen.getByRole('heading', { name: 'Fixture Plan' })).toBeInTheDocument();
+    expect(screen.getByText('Activo')).toBeInTheDocument();
+    expect(screen.getByText('€10')).toBeInTheDocument();
+    expect(screen.getByText('Billed monthly')).toBeInTheDocument();
+    expect(screen.getByText('Renews January 1, 2027')).toBeInTheDocument();
+    expect(screen.getAllByRole('listitem').map((item) => item.textContent)).toEqual(['Feature A', 'Feature B']);
+    await user.click(screen.getByRole('button', { name: 'Annual' }));
+    expect(screen.getByText('€100')).toBeInTheDocument();
+    expect(screen.getByText('Billed annually')).toBeInTheDocument();
+    for (const name of ['Upgrade', 'Manage']) {
+      const button = screen.getByRole('button', { name });
+      expect(button.tagName).toBe('BUTTON');
+      button.focus();
+      expect(button).toHaveFocus();
+    }
+  });
+
+  it.each(['dark', 'light', 'high_contrast'])('has no axe violations for every fixture in %s', async (theme) => {
+    document.documentElement.className = theme;
+    for (const [, props] of fixtures) {
+      const { container, unmount } = render(<PlanCard variant="summary" {...props} />);
+      await expectNoAxeViolations(container);
+      unmount();
+    }
+  });
+  it('renders ACTIONS-ONLY as a focusable native button with Enter and Space activation', async () => {
+    const user = userEvent.setup();
+    const onManage = vi.fn();
+    render(<PlanCard variant="summary" plan={minimal} actions={<Button onClick={onManage}>Manage</Button>} />);
+    const manage = screen.getByRole('button', { name: 'Manage' });
+    expect(manage.tagName).toBe('BUTTON');
+    expect(screen.queryByText(/€|\$|Billed|Renews/)).toBeNull();
+    expect(screen.queryByRole('list')).toBeNull();
+    await user.tab();
+    expect(manage).toHaveFocus();
+    await user.keyboard('{Enter}');
+    expect(onManage).toHaveBeenCalledTimes(1);
+    await user.keyboard(' ');
+    expect(onManage).toHaveBeenCalledTimes(2);
+  });
+  it('renders FEATURES-ONLY as an accessible list without billing or actions', () => {
+    render(<PlanCard variant="summary" plan={{ ...minimal, features: ['Feature A'] }} />);
+    expect(screen.getByRole('list', { name: 'Plan features' })).toBeInTheDocument();
+    expect(screen.getByRole('listitem')).toHaveTextContent('Feature A');
+    expect(screen.queryByText(/€|\$|Billed|Renews/)).toBeNull();
+    expect(screen.queryByRole('button')).toBeNull();
+  });
+  it('renders RENEWAL-ONLY without any other optional region', () => {
+    render(<PlanCard variant="summary" plan={{ ...minimal, renewsOn: '2027-01-01' }} />);
+    expect(screen.getByText('Renews January 1, 2027')).toBeInTheDocument();
+    expect(screen.queryByText(/€|\$|Billed/)).toBeNull();
+    expect(screen.queryByRole('button')).toBeNull();
+    expect(screen.queryByRole('list')).toBeNull();
+  });
+  it.each([
+    ['PRICE-ONLY', 10, '€10'],
+    ['ZERO-PRICE', 0, '€0'],
+  ] as const)('renders %s without cycle text or a focusable toggle', async (_fixture, priceMonthly, amount) => {
+    const user = userEvent.setup();
+    const { container } = render(<PlanCard variant="summary" plan={{ ...minimal, priceMonthly, currency: 'EUR' }} />);
+    expect(screen.getByText(amount)).toBeInTheDocument();
+    expect(screen.queryByRole('group')).toBeNull();
+    expect(screen.queryByRole('button')).toBeNull();
+    expect(screen.queryByText(/Billed|Renews|month|annual/i)).toBeNull();
+    expect(screen.queryByRole('list')).toBeNull();
+    await user.tab();
+    expect(document.body).toHaveFocus();
+    await expectNoAxeViolations(container);
+  });
+
+  it('shows supplied monthly and annual totals verbatim with an accessible toggle', async () => {
+    const user = userEvent.setup();
+    const onCycleChange = vi.fn();
+    render(
+      <PlanCard
+        variant="summary"
+        plan={{
+          ...minimal,
+          priceMonthly: 10,
+          priceAnnual: 100,
+          currency: 'EUR',
+        }}
+        onCycleChange={onCycleChange}
+      />,
+    );
+    expect(screen.getByText('€10')).toBeInTheDocument();
+    const monthly = screen.getByRole('button', {
+      name: 'Monthly',
+    });
+    const annual = screen.getByRole('button', { name: 'Annual' });
+    expect(monthly).toHaveAttribute('aria-pressed', 'true');
+    await user.tab();
+    expect(monthly).toHaveFocus();
+    await user.click(annual);
+    expect(screen.getByText('€100')).toBeInTheDocument();
+    expect(screen.queryByText('€1,200')).toBeNull();
+    expect(annual).toHaveAttribute('aria-pressed', 'true');
+    expect(onCycleChange).toHaveBeenCalledWith('annual');
+    await user.click(monthly);
+    expect(screen.getByText('€10')).toBeInTheDocument();
+  });
+
+  it('renders an annual-only price without a toggle', () => {
+    render(<PlanCard variant="summary" plan={{ ...minimal, priceAnnual: 100, currency: 'EUR' }} />);
+    expect(screen.getByText('€100')).toBeInTheDocument();
+    expect(screen.queryByRole('button')).toBeNull();
+    expect(screen.queryByText(/Billed/)).toBeNull();
+  });
+
+  it('renders supplied cycle text independently of price', () => {
+    render(<PlanCard variant="summary" plan={{ ...minimal, cycle: 'annual' }} />);
+    expect(screen.getByText('Billed annually')).toBeInTheDocument();
+    expect(screen.queryByText(/€|\$/)).toBeNull();
+    expect(screen.queryByRole('button')).toBeNull();
+  });
+
+  it('renders a name without inventing a status or any optional content', () => {
+    const { container } = render(<PlanCard variant="summary" plan={{ name: 'Fixture Plan' }} />);
+    expect(screen.getByRole('heading', { name: 'Fixture Plan' })).toBeInTheDocument();
+    expect(container.textContent).toBe('Fixture Plan');
+    expect(screen.queryByText('Active')).toBeNull();
+    expect(screen.queryByRole('button')).toBeNull();
+    expect(screen.queryByRole('group')).toBeNull();
+    expect(screen.queryByRole('list')).toBeNull();
+  });
+
+  it('keeps zero annual pricing selectable with the keyboard', async () => {
+    const user = userEvent.setup();
+    render(<PlanCard variant="summary" plan={{ ...minimal, priceMonthly: 10, priceAnnual: 0, currency: 'EUR' }} />);
+    const monthly = screen.getByRole('button', { name: 'Monthly' });
+    const annual = screen.getByRole('button', { name: 'Annual' });
+    expect(screen.getByText('€10')).toBeInTheDocument();
+    await user.tab();
+    expect(monthly).toHaveFocus();
+    await user.keyboard('{ArrowRight}');
+    expect(annual).toHaveFocus();
+    await user.keyboard(' ');
+    expect(screen.getByText('€0')).toBeInTheDocument();
+    expect(annual).toHaveAttribute('aria-pressed', 'true');
+    expect(monthly).toHaveAttribute('aria-pressed', 'false');
+    await user.keyboard('{ArrowLeft}{Enter}');
+    expect(screen.getByText('€10')).toBeInTheDocument();
+    expect(monthly).toHaveAttribute('aria-pressed', 'true');
+    expect(annual).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  it('renders only the consumer name and status for MINIMAL', () => {
+    const { container } = render(<PlanCard variant="summary" plan={minimal} />);
+    expect(screen.getByRole('heading', { name: 'Fixture Plan' })).toBeInTheDocument();
+    expect(screen.getByText('Activo')).toBeInTheDocument();
+    expect(screen.queryByRole('button')).toBeNull();
+    expect(screen.queryByRole('group')).toBeNull();
+    expect(screen.queryByRole('list')).toBeNull();
+    expect(container.textContent).toBe('Fixture PlanActivo');
+    expect(screen.queryByText(/Scale|\$|Billed|Renews|Active/)).toBeNull();
+  });
+
+  it('renders UNASSIGNED using only the consumer empty label', () => {
+    const { container } = render(<PlanCard variant="summary" emptyLabel="Sin plan asignado" />);
+    expect(screen.getByRole('heading', { name: 'Sin plan asignado' })).toBeInTheDocument();
+    expect(screen.queryByRole('status')).toBeNull();
+    expect(screen.queryByRole('button')).toBeNull();
+    expect(container.textContent).toBe('Sin plan asignado');
+  });
+
+  it('renders no heading for UNASSIGNED-NO-LABEL and warns only in development', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      vi.stubEnv('NODE_ENV', 'development');
+      const { container, unmount } = render(<PlanCard variant="summary" />);
+      expect(screen.queryByRole('heading')).toBeNull();
+      expect(container.textContent).toBe('');
+      expect(warn).toHaveBeenCalledWith('PlanCard summary: supply a plan name or emptyLabel.');
+      unmount();
+      warn.mockClear();
+      vi.stubEnv('NODE_ENV', 'production');
+      render(<PlanCard variant="summary" />);
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllEnvs();
+      warn.mockRestore();
+    }
+  });
+});

package/src/billing/PlanCard/PlanCard.test.tsx

@@ -0,0 +1,27 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { PlanCard } from './PlanCard';
+
+describe('PlanCard', () => {
+  it('renders the sample plan', async () => {
+    const { container } = render(<PlanCard />);
+    expect(screen.getByRole('heading', { name: 'Scale plan' })).toBeInTheDocument();
+    expect(screen.getByText('$1,200')).toBeInTheDocument();
+    expect(screen.getByText(/Renews June 1, 2026/)).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('switches the cycle and fires the actions', async () => {
+    const user = userEvent.setup();
+    const onUpgrade = vi.fn();
+    const onCycleChange = vi.fn();
+    render(<PlanCard onUpgrade={onUpgrade} onCycleChange={onCycleChange} />);
+    await user.click(screen.getByRole('button', { name: /Annual/ }));
+    expect(onCycleChange).toHaveBeenCalledWith('annual');
+    expect(screen.getByText('$1,000')).toBeInTheDocument();
+    expect(screen.getByText(/Billed annually/)).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Upgrade plan' }));
+    expect(onUpgrade).toHaveBeenCalledOnce();
+  });
+});

package/src/billing/PlanCard/PlanCard.tsx

@@ -0,0 +1,140 @@
+import { useState } from 'react';
+import { Badge, Button, Card, Toggle, ToggleGroup, cn, type BadgeTone } from '@gntik-ai/ui';
+import { Check, Sparkles } from '@gntik-ai/icons';
+import { formatDate, formatMoney, type DateInput } from '../format';
+import { samplePlan } from './fixtures';
+import { PlanSummary, type PlanSummaryProps } from './PlanSummary';
+export type { SummaryPlan, PlanSummaryProps } from './PlanSummary';
+
+export type PlanStatus = 'active' | 'trialing' | 'past_due' | 'canceled';
+export type BillingCycle = 'monthly' | 'annual';
+
+export interface BillingPlan {
+  name: string;
+  status?: PlanStatus;
+  /** Price per month on the monthly cycle. */
+  priceMonthly: number;
+  /** Price per month when billed annually. Enables the monthly/annual toggle. */
+  priceAnnual?: number;
+  /** ISO 4217 code. Default USD. */
+  currency?: string;
+  /** Next renewal date. */
+  renewsOn: DateInput;
+  /** Short line after the renewal date, e.g. "50 seats · 2 regions". */
+  summary?: string;
+  features?: string[];
+}
+
+export interface BillingPlanCardProps {
+  variant?: 'billing';
+  plan?: BillingPlan;
+  /** Initial cycle shown (uncontrolled). */
+  defaultCycle?: BillingCycle;
+  onCycleChange?: (cycle: BillingCycle) => void;
+  onUpgrade?: () => void;
+  onManage?: () => void;
+  upgradeLabel?: string;
+  manageLabel?: string;
+  /** Heading level of the title, to fit the page outline (default h3). */
+  titleAs?: 'h2' | 'h3' | 'h4';
+  className?: string;
+}
+
+export type PlanCardProps = BillingPlanCardProps | PlanSummaryProps;
+
+/** Default billing header, or an opt-in summary without sample data. */
+export function PlanCard(props: PlanCardProps) {
+  return props.variant === 'summary' ? <PlanSummary {...props} /> : <BillingPlanCard {...props} />;
+}
+
+const STATUS: Record<PlanStatus, { label: string; tone: BadgeTone }> = {
+  active: { label: 'Active', tone: 'success' },
+  trialing: { label: 'Trial', tone: 'info' },
+  past_due: { label: 'Past due', tone: 'warning' },
+  canceled: { label: 'Canceled', tone: 'neutral' },
+};
+
+/** Billing page header: the current plan, its price per cycle, renewal date, features and actions. */
+function BillingPlanCard({
+  plan = samplePlan,
+  defaultCycle = 'monthly',
+  onCycleChange,
+  onUpgrade,
+  onManage,
+  upgradeLabel = 'Upgrade plan',
+  manageLabel = 'Manage',
+  titleAs: TitleTag = 'h3',
+  className,
+}: BillingPlanCardProps) {
+  const [cycle, setCycle] = useState<BillingCycle>(defaultCycle);
+  const hasAnnual = plan.priceAnnual != null;
+  const annual = hasAnnual && cycle === 'annual';
+  const perMonth = annual ? (plan.priceAnnual ?? plan.priceMonthly) : plan.priceMonthly;
+  const currency = plan.currency ?? 'USD';
+  const savings = hasAnnual ? Math.round((1 - (plan.priceAnnual ?? 0) / plan.priceMonthly) * 100) : 0;
+  const status = STATUS[plan.status ?? 'active'];
+
+  const changeCycle = (value: string[]) => {
+    const next = value[0];
+    if (next !== 'monthly' && next !== 'annual') return;
+    setCycle(next);
+    onCycleChange?.(next);
+  };
+
+  return (
+    <Card className={cn('p-6', className)}>
+      <div className="flex flex-col gap-5 sm:flex-row sm:items-start sm:justify-between">
+        <div className="min-w-0">
+          <div className="flex flex-wrap items-center gap-2">
+            <TitleTag className="text-[17px] font-semibold tracking-tight text-foreground">{plan.name} plan</TitleTag>
+            <Badge tone={status.tone} dot>
+              {status.label}
+            </Badge>
+          </div>
+          <p className="mt-1 text-[13px] text-muted-foreground">
+            Renews {formatDate(plan.renewsOn)}
+            {plan.summary && <> · {plan.summary}</>}
+          </p>
+          <p className="mt-4 flex items-baseline gap-1.5">
+            <span className="text-[30px] font-semibold tracking-tight text-foreground tabular-nums">
+              {formatMoney(perMonth, currency, true)}
+            </span>
+            <span className="text-[13px] text-muted-foreground">/ month</span>
+          </p>
+          <p className="mt-1 text-[12px] text-muted-foreground">
+            {annual ? `Billed annually (${formatMoney(perMonth * 12, currency, true)})` : 'Billed monthly'}
+          </p>
+        </div>
+        <div className="flex flex-col items-start gap-3 sm:items-end">
+          {hasAnnual && (
+            <ToggleGroup size="sm" aria-label="Billing cycle" value={[cycle]} onValueChange={changeCycle}>
+              <Toggle value="monthly">Monthly</Toggle>
+              <Toggle value="annual">Annual{savings > 0 && ` −${savings}%`}</Toggle>
+            </ToggleGroup>
+          )}
+          <div className="flex flex-wrap items-center gap-2">
+            <Button variant="secondary" onClick={onManage}>
+              {manageLabel}
+            </Button>
+            <Button icon={Sparkles} onClick={onUpgrade}>
+              {upgradeLabel}
+            </Button>
+          </div>
+        </div>
+      </div>
+      {plan.features && plan.features.length > 0 && (
+        <ul
+          aria-label={`${plan.name} plan features`}
+          className="mt-5 grid gap-x-6 gap-y-2 border-t border-border pt-5 sm:grid-cols-2"
+        >
+          {plan.features.map((f) => (
+            <li key={f} className="flex items-start gap-2 text-[13px] text-foreground">
+              <Check size={15} aria-hidden className="mt-0.5 shrink-0 text-primary-text" />
+              {f}
+            </li>
+          ))}
+        </ul>
+      )}
+    </Card>
+  );
+}

package/src/billing/PlanCard/PlanSummary.tsx

@@ -0,0 +1,101 @@
+import { Badge, Card, Toggle, ToggleGroup, cn, type BadgeTone } from '@gntik-ai/ui';
+import { useEffect, useState, type ReactNode } from 'react';
+import { formatDate, formatMoney, type DateInput } from '../format';
+import type { BillingCycle } from './PlanCard';
+
+/** Consumer data only: each summary region is optional. Prices are cycle totals. */
+export interface SummaryPlan {
+  name?: string;
+  statusLabel?: string;
+  statusTone?: BadgeTone;
+  priceMonthly?: number;
+  priceAnnual?: number;
+  currency?: string;
+  cycle?: BillingCycle;
+  renewsOn?: DateInput;
+  features?: string[];
+}
+
+export interface PlanSummaryProps {
+  variant: 'summary';
+  plan?: SummaryPlan;
+  emptyLabel?: string;
+  /** Consumer-supplied kit Buttons or native links. No built-in actions. */
+  actions?: ReactNode;
+  defaultCycle?: BillingCycle;
+  onCycleChange?: (cycle: BillingCycle) => void;
+  titleAs?: 'h2' | 'h3' | 'h4';
+  className?: string;
+}
+
+export function PlanSummary({
+  plan,
+  emptyLabel,
+  actions,
+  defaultCycle = 'monthly',
+  onCycleChange,
+  titleAs: TitleTag = 'h3',
+  className,
+}: PlanSummaryProps) {
+  const title = plan?.name || emptyLabel;
+  const [cycle, setCycle] = useState<BillingCycle>(defaultCycle);
+  const hasBothPrices = plan?.priceMonthly != null && plan?.priceAnnual != null;
+  const price = hasBothPrices
+    ? cycle === 'annual'
+      ? plan.priceAnnual
+      : plan.priceMonthly
+    : (plan?.priceMonthly ?? plan?.priceAnnual);
+  const changeCycle = (values: string[]) => {
+    const next = values[0];
+    if (next !== 'monthly' && next !== 'annual') return;
+    setCycle(next);
+    onCycleChange?.(next);
+  };
+  useEffect(() => {
+    if (!title && process.env.NODE_ENV === 'development') {
+      console.warn('PlanCard summary: supply a plan name or emptyLabel.');
+    }
+  }, [title]);
+  return (
+    <Card className={cn('p-6', className)}>
+      <div className="flex flex-wrap items-center gap-2">
+        {title && <TitleTag className="text-lg font-semibold text-foreground">{title}</TitleTag>}
+        {plan?.statusLabel && (
+          <Badge tone={plan.statusTone ?? 'neutral'} dot>
+            {plan.statusLabel}
+          </Badge>
+        )}
+      </div>
+      {plan?.renewsOn != null && (
+        <p className="mt-1 text-sm text-muted-foreground">Renews {formatDate(plan.renewsOn)}</p>
+      )}
+      {price != null && (
+        <p className="mt-4 text-3xl font-semibold text-foreground tabular-nums">
+          {formatMoney(price, plan?.currency, true)}
+        </p>
+      )}
+      {plan?.cycle && (
+        <p className="mt-1 text-sm text-muted-foreground">
+          {(hasBothPrices ? cycle : plan.cycle) === 'annual' ? 'Billed annually' : 'Billed monthly'}
+        </p>
+      )}
+      {hasBothPrices && (
+        <ToggleGroup className="mt-4" size="sm" aria-label="Billing cycle" value={[cycle]} onValueChange={changeCycle}>
+          <Toggle value="monthly">Monthly</Toggle>
+          <Toggle value="annual">Annual</Toggle>
+        </ToggleGroup>
+      )}
+      {plan?.features && plan.features.length > 0 && (
+        <ul
+          aria-label="Plan features"
+          className="mt-5 grid gap-2 border-t border-border pt-5 text-sm text-foreground sm:grid-cols-2"
+        >
+          {plan.features.map((feature) => (
+            <li key={feature}>{feature}</li>
+          ))}
+        </ul>
+      )}
+      {actions && <div className="mt-4 flex flex-wrap items-center gap-2">{actions}</div>}
+    </Card>
+  );
+}

package/src/billing/PlanCard/README.md

@@ -0,0 +1,23 @@
+# Plan card
+
+`PlanCard` defaults to the existing billing header. Opt into `variant="summary"` for consumer-only data with independently optional regions. Import the component and types from `@gntik-ai/blocks`.
+
+| Props                           | Billing (default)                                                                                                     | Summary                                                                                                         |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `plan`                          | `BillingPlan`; omitted uses `samplePlan`                                                                              | `SummaryPlan`; omitted renders no sample values                                                                 |
+| Plan name                       | Required; adds “plan” to the heading                                                                                  | Optional, shown verbatim; missing name uses `emptyLabel`                                                        |
+| Status                          | Optional enum; falls back to Active                                                                                   | Optional `statusLabel` and `statusTone`; no default label                                                       |
+| Prices                          | Required `priceMonthly`; optional `priceAnnual` is a discounted monthly amount                                        | Optional `priceMonthly` and `priceAnnual` are complete cycle totals; zero is valid                              |
+| `currency`                      | Defaults to USD                                                                                                       | Formatting defaults to USD only when a price is supplied                                                        |
+| Cycle                           | Always renders billing copy; annual total is monthly amount × 12                                                      | Optional `plan.cycle` renders cycle copy; toggle only when both prices are supplied, with no savings arithmetic |
+| `renewsOn`                      | Required; always shows formatted renewal                                                                              | Optional; absent means no renewal line                                                                          |
+| `features`                      | Optional nonempty array renders a list                                                                                | Optional nonempty array renders a list                                                                          |
+| Actions                         | Always renders Manage and Upgrade plan buttons; `onManage`, `onUpgrade`, `manageLabel`, `upgradeLabel` customize them | Optional `actions: ReactNode` slot of kit Buttons or native links; no default actions                           |
+| `defaultCycle`, `onCycleChange` | Initial cycle (monthly by default), selection callback                                                                | Same; applies to the optional toggle                                                                            |
+| `titleAs`, `className`          | h2/h3/h4 (default h3), token-backed classes                                                                           | Same                                                                                                            |
+
+Billing also supports optional `plan.summary` after renewal. Summary never imports sample data. With neither a name nor an `emptyLabel`, summary renders no heading and warns only in development.
+
+ARIA and keyboard: a heading at the consumer's requested level, a visibly labelled status badge, a named features list, and native consumer actions. The cycle group is named “Billing cycle”; toggles expose `aria-pressed`. Tab/Shift+Tab visit controls; arrow keys/Home/End navigate the toggle; Enter/Space activate buttons and toggles; Enter activates links. With fewer than two prices the toggle is absent from both DOM and tab order. Axe tests cover dark, light and high_contrast; browser tests also check contrast.
+
+Preview IDs: `plan-card--summary-full`, `--summary-minimal`, `--summary-unassigned`, `--summary-unassigned-no-label`, `--summary-price-only`, `--summary-zero-price`, `--summary-renewal-only`, `--summary-features-only`, `--summary-actions-only`. Examples use English copy; translated values belong to consumers.

package/src/billing/PlanCard/__snapshots__/PlanCard.baseline.test.tsx.snap

@@ -0,0 +1,5 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`PlanCard billing DOM baseline > preserves the FULL billing header 1`] = `"<div><div class="overflow-hidden rounded-xl border border-border text-card-foreground bg-card shadow-sm p-6"><div class="flex flex-col gap-5 sm:flex-row sm:items-start sm:justify-between"><div class="min-w-0"><div class="flex flex-wrap items-center gap-2"><h3 class="text-[17px] font-semibold tracking-tight text-foreground">Fixture Plan plan</h3><span class="inline-flex max-w-full shrink-0 items-center gap-1.5 font-semibold whitespace-nowrap select-none h-chip px-2.5 font-mono text-[10.5px] rounded-md bg-success/15 text-success-chip-text"><span aria-hidden="true" class="size-1.5 shrink-0 rounded-full bg-success"></span>Active</span></div><p class="mt-1 text-[13px] text-muted-foreground">Renews January 1, 2027 · 2 seats</p><p class="mt-4 flex items-baseline gap-1.5"><span class="text-[30px] font-semibold tracking-tight text-foreground tabular-nums">€10</span><span class="text-[13px] text-muted-foreground">/ month</span></p><p class="mt-1 text-[12px] text-muted-foreground">Billed monthly</p></div><div class="flex flex-col items-start gap-3 sm:items-end"><div data-orientation="horizontal" role="group" aria-label="Billing cycle" class="inline-flex data-[orientation=vertical]:flex-col data-disabled:opacity-50 items-center gap-0.5 rounded-lg border border-border bg-card p-0.5 shadow-sm"><button type="button" data-pressed="" aria-disabled="false" tabindex="0" aria-pressed="true" class="inline-flex shrink-0 items-center justify-center gap-2 font-medium whitespace-nowrap text-muted-foreground transition-colors select-none hover:text-foreground data-pressed:bg-secondary data-pressed:text-foreground focus-visible:relative focus-visible:z-10 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring data-disabled:cursor-not-allowed data-disabled:opacity-50 data-disabled:hover:text-muted-foreground rounded-md data-pressed:shadow-sm h-7 px-2.5 text-[12px]">Monthly</button><button type="button" aria-disabled="false" tabindex="-1" aria-pressed="false" class="inline-flex shrink-0 items-center justify-center gap-2 font-medium whitespace-nowrap text-muted-foreground transition-colors select-none hover:text-foreground data-pressed:bg-secondary data-pressed:text-foreground focus-visible:relative focus-visible:z-10 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring data-disabled:cursor-not-allowed data-disabled:opacity-50 data-disabled:hover:text-muted-foreground rounded-md data-pressed:shadow-sm h-7 px-2.5 text-[12px]">Annual</button></div><div class="flex flex-wrap items-center gap-2"><button type="button" tabindex="0" class="inline-flex shrink-0 items-center justify-center font-semibold whitespace-nowrap transition-colors select-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring data-[disabled]:pointer-events-none data-[disabled]:opacity-50 border border-border bg-card text-foreground shadow-sm hover:bg-secondary/70 h-control gap-1.5 px-control text-[13px] rounded-lg">Manage</button><button type="button" tabindex="0" class="inline-flex shrink-0 items-center justify-center font-semibold whitespace-nowrap transition-colors select-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring data-[disabled]:pointer-events-none data-[disabled]:opacity-50 bg-primary text-primary-foreground shadow-sm hover:bg-primary/90 h-control gap-1.5 px-control text-[13px] rounded-lg"><svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-sparkles lucide-stars" aria-hidden="true"><path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z"></path><path d="M20 2v4"></path><path d="M22 4h-4"></path><circle cx="4" cy="20" r="2"></circle></svg>Upgrade</button></div></div></div><ul aria-label="Fixture Plan plan features" class="mt-5 grid gap-x-6 gap-y-2 border-t border-border pt-5 sm:grid-cols-2"><li class="flex items-start gap-2 text-[13px] text-foreground"><svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check mt-0.5 shrink-0 text-primary-text" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>Feature A</li><li class="flex items-start gap-2 text-[13px] text-foreground"><svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check mt-0.5 shrink-0 text-primary-text" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>Feature B</li></ul></div></div>"`;
+
+exports[`PlanCard billing DOM baseline > preserves the no-props billing header 1`] = `"<div><div class="overflow-hidden rounded-xl border border-border text-card-foreground bg-card shadow-sm p-6"><div class="flex flex-col gap-5 sm:flex-row sm:items-start sm:justify-between"><div class="min-w-0"><div class="flex flex-wrap items-center gap-2"><h3 class="text-[17px] font-semibold tracking-tight text-foreground">Scale plan</h3><span class="inline-flex max-w-full shrink-0 items-center gap-1.5 font-semibold whitespace-nowrap select-none h-chip px-2.5 font-mono text-[10.5px] rounded-md bg-success/15 text-success-chip-text"><span aria-hidden="true" class="size-1.5 shrink-0 rounded-full bg-success"></span>Active</span></div><p class="mt-1 text-[13px] text-muted-foreground">Renews June 1, 2026 · 50 seats · 2 regions</p><p class="mt-4 flex items-baseline gap-1.5"><span class="text-[30px] font-semibold tracking-tight text-foreground tabular-nums">$1,200</span><span class="text-[13px] text-muted-foreground">/ month</span></p><p class="mt-1 text-[12px] text-muted-foreground">Billed monthly</p></div><div class="flex flex-col items-start gap-3 sm:items-end"><div data-orientation="horizontal" role="group" aria-label="Billing cycle" class="inline-flex data-[orientation=vertical]:flex-col data-disabled:opacity-50 items-center gap-0.5 rounded-lg border border-border bg-card p-0.5 shadow-sm"><button type="button" data-pressed="" aria-disabled="false" tabindex="0" aria-pressed="true" class="inline-flex shrink-0 items-center justify-center gap-2 font-medium whitespace-nowrap text-muted-foreground transition-colors select-none hover:text-foreground data-pressed:bg-secondary data-pressed:text-foreground focus-visible:relative focus-visible:z-10 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring data-disabled:cursor-not-allowed data-disabled:opacity-50 data-disabled:hover:text-muted-foreground rounded-md data-pressed:shadow-sm h-7 px-2.5 text-[12px]">Monthly</button><button type="button" aria-disabled="false" tabindex="-1" aria-pressed="false" class="inline-flex shrink-0 items-center justify-center gap-2 font-medium whitespace-nowrap text-muted-foreground transition-colors select-none hover:text-foreground data-pressed:bg-secondary data-pressed:text-foreground focus-visible:relative focus-visible:z-10 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring data-disabled:cursor-not-allowed data-disabled:opacity-50 data-disabled:hover:text-muted-foreground rounded-md data-pressed:shadow-sm h-7 px-2.5 text-[12px]">Annual −17%</button></div><div class="flex flex-wrap items-center gap-2"><button type="button" tabindex="0" class="inline-flex shrink-0 items-center justify-center font-semibold whitespace-nowrap transition-colors select-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring data-[disabled]:pointer-events-none data-[disabled]:opacity-50 border border-border bg-card text-foreground shadow-sm hover:bg-secondary/70 h-control gap-1.5 px-control text-[13px] rounded-lg">Manage</button><button type="button" tabindex="0" class="inline-flex shrink-0 items-center justify-center font-semibold whitespace-nowrap transition-colors select-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring data-[disabled]:pointer-events-none data-[disabled]:opacity-50 bg-primary text-primary-foreground shadow-sm hover:bg-primary/90 h-control gap-1.5 px-control text-[13px] rounded-lg"><svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-sparkles lucide-stars" aria-hidden="true"><path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z"></path><path d="M20 2v4"></path><path d="M22 4h-4"></path><circle cx="4" cy="20" r="2"></circle></svg>Upgrade plan</button></div></div></div><ul aria-label="Scale plan features" class="mt-5 grid gap-x-6 gap-y-2 border-t border-border pt-5 sm:grid-cols-2"><li class="flex items-start gap-2 text-[13px] text-foreground"><svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check mt-0.5 shrink-0 text-primary-text" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>500,000 requests / month</li><li class="flex items-start gap-2 text-[13px] text-foreground"><svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check mt-0.5 shrink-0 text-primary-text" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>120M tokens / month</li><li class="flex items-start gap-2 text-[13px] text-foreground"><svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check mt-0.5 shrink-0 text-primary-text" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>20 GB storage</li><li class="flex items-start gap-2 text-[13px] text-foreground"><svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check mt-0.5 shrink-0 text-primary-text" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>Audit log and SSO</li><li class="flex items-start gap-2 text-[13px] text-foreground"><svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check mt-0.5 shrink-0 text-primary-text" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>Email support · 1 business day</li></ul></div></div>"`;

package/src/billing/PlanCard/block.meta.ts

@@ -0,0 +1,60 @@
+import type { BlockMeta } from '../../meta';
+
+/** Catalogue contract read by get_block and llms-full.txt. */
+export const documentation = {
+  pattern:
+    'Heading (titleAs h2/h3/h4), text-labelled Badge, optional features list and native consumer actions. Summary omits absent regions; no heading plus a development warning when name and emptyLabel are absent. ToggleGroup has an accessible Billing cycle label and aria-pressed buttons, rendered only with both prices. Axe coverage in dark, light and high_contrast.',
+  keyboard: [
+    ['Tab / Shift+Tab', 'Move through the cycle toggle (only with both prices) and supplied buttons or links.'],
+    ['Arrow keys / Home / End', 'Move focus within the monthly/annual toggle group.'],
+    ['Enter / Space', 'Activate focused buttons and toggles; Enter activates links.'],
+  ],
+  tokens: ['card', 'foreground', 'muted-foreground', 'border', 'focus-ring'],
+  props: [
+    ['variant', 'billing (default) | summary'],
+    [
+      'billing plan',
+      'BillingPlan: name, priceMonthly and renewsOn required; status, priceAnnual, currency, summary and features optional. Omitted plan uses samplePlan.',
+    ],
+    [
+      'summary plan',
+      'SummaryPlan: all optional: name, statusLabel, statusTone, priceMonthly, priceAnnual, currency, cycle, renewsOn, features. Prices are supplied cycle totals, never multiplied or discounted.',
+    ],
+    ['emptyLabel', 'Summary only: consumer label used when the name is absent.'],
+    ['actions', 'Summary only: ReactNode slot of kit Buttons or native links, absent by default.'],
+    ['defaultCycle / onCycleChange', 'Initial monthly (default) or annual selection and cycle callback.'],
+    ['titleAs / className', 'h2 | h3 (default) | h4; additional token-backed classes.'],
+    [
+      'onUpgrade / onManage / upgradeLabel / manageLabel',
+      'Billing only: existing action handlers and labels; both buttons always render.',
+    ],
+  ],
+  examples: [
+    'summary-full',
+    'summary-minimal',
+    'summary-unassigned',
+    'summary-unassigned-no-label',
+    'summary-price-only',
+    'summary-zero-price',
+    'summary-renewal-only',
+    'summary-features-only',
+    'summary-actions-only',
+  ],
+};
+
+export const meta: BlockMeta = {
+  name: 'Plan card',
+  family: 'billing',
+  status: 'beta',
+  description: [
+    'Default billing header retains sample plan, Active status fallback, required monthly price and renewal, monthly/annual per-month pricing and built-in Manage/Upgrade actions. Opt-in variant="summary" uses only consumer data: optional name or emptyLabel, statusLabel, price totals (including zero), cycle, renewal, features and action slots; no sample fallback. See README.md for props, ARIA, keyboard and examples.',
+    '',
+    '| Prop | Contract |',
+    '| --- | --- |',
+    ...documentation.props.map(([prop, contract]) => `| ${prop} | ${contract?.replaceAll('|', '\\|')} |`),
+    '',
+    'Examples:',
+    ...documentation.examples.map((example) => `- [${example}](/preview.html?kind=block&id=plan-card--${example})`),
+  ].join('\n'),
+  uses: ['Card', 'Badge', 'Button', 'ToggleGroup', 'Toggle'],
+};