@kerne/react 0.1.3 → 1.1.0

package/dist/ui/index.d.cts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { SubscriptionWithPlan } from '@kerne/types';
-export { K as KerneLocalization, d as defaultLocalization, u as useLocalization } from '../i18n-BWTT1DWD.cjs';
+import { PublicPlan, PublicPriceLabel, PublicPlanPrice, SubscriptionWithPlan } from '@kerne/types';
+import { K as KerneLocalization } from '../i18n-QilNgwqe.cjs';
+export { d as defaultLocalization, u as useLocalization } from '../i18n-QilNgwqe.cjs';
 
 /**
  * Per-instance overrides of the same custom properties the stylesheet reads,
@@ -332,8 +333,10 @@ interface SubscriptionCardProps extends Omit<KerneUIProps, 'logo'> {
     onUpgradeClick?: () => void;
     /** Hide the "Manage billing" button (e.g. when the page has its own). */
     hidePortalButton?: boolean;
+    /** Hide the "Cancel subscription" button, e.g. when cancellation goes through sales/support. */
+    hideCancelButton?: boolean;
 }
-declare function SubscriptionCard({ productSlug, title, portalReturnUrl, upgradeUrl, onUpgradeClick, hidePortalButton, appearance, className, }: SubscriptionCardProps): react_jsx_runtime.JSX.Element;
+declare function SubscriptionCard({ productSlug, title, portalReturnUrl, upgradeUrl, onUpgradeClick, hidePortalButton, hideCancelButton, appearance, className, }: SubscriptionCardProps): react_jsx_runtime.JSX.Element;
 
 interface UsageMetersProps extends Omit<KerneUIProps, 'logo'> {
     /** Heading above the meters. Omit for the localized default, `null` for none. */
@@ -351,6 +354,138 @@ interface UsageMetersProps extends Omit<KerneUIProps, 'logo'> {
 }
 declare function UsageMeters({ title, featureKeys, showUnlimited, limit: maxRows, labels, emptyState, appearance, className, }: UsageMetersProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Display helpers shared by the billing and usage components.
+ */
+
+/**
+ * Last-resort label for a feature.
+ *
+ * `GET /v1/billing/entitlements` returns `feature_key` but no `feature_name`
+ * (see EntitlementSummary), while the subscription payload does carry names -
+ * so components cross-reference the subscription first and only fall back
+ * here for a scope on a default pack, which has no subscription to read names
+ * from. Turning `api_calls` into "Api calls" is not as good as the real name;
+ * it is only better than showing a raw key to an end user.
+ */
+declare function humanizeFeatureKey(key: string): string;
+/** Amounts are stored in minor units (cents), as the provider APIs return them. */
+declare function formatMoney(amountMinorUnits: number, currency: string): string;
+declare function formatNumber(value: number): string;
+declare function formatDate(iso: string | null): string | null;
+/**
+ * Normalises the provider's interval wording, then localizes it.
+ *
+ * `PlanPrice.interval` is Kerne's own "N+cycle" encoding ("1M", "3M", "1Y",
+ * "30D" - see apps/api's interval.ts), checked first since it's what every
+ * subscription/plan payload actually carries. The word-based fallback below
+ * stays for any raw provider string passed directly (Stripe says `month`,
+ * Polar says `monthly` - same thing to a reader). An interval matching
+ * neither falls through unchanged rather than being dropped: better a raw
+ * value than a price with no period attached.
+ */
+declare function formatInterval(interval: string, labels: IntervalLabels): string;
+type IntervalLabels = Pick<KerneLocalization['billing'], 'intervalMonth' | 'intervalYear' | 'intervalWeek' | 'intervalDay'>;
+interface PriceDisplay {
+    /** What's actually charged - show this alongside displayAmount, never hide it. */
+    billedAmount: number;
+    billedInterval: string;
+    /** The headline number a PriceLabel.display_interval asks to show instead. */
+    displayAmount: number;
+    displayInterval: string;
+}
+/**
+ * Resolves what to show for a price under a label's `display_interval` -
+ * e.g. an annual price shown as its monthly equivalent while still billing
+ * annually. `null`/`undefined`/equal-to-billed pass through unchanged. Divides
+ * once via approxMonths()'s ratio, never divide-then-multiply back to
+ * "verify" - a price rarely divides evenly (100 EUR/year -> 8.33 EUR/month,
+ * and 8.33 * 12 = 99.96, not 100).
+ */
+declare function resolvePriceDisplay(price: {
+    amount: number;
+    interval: string;
+}, displayInterval: string | null | undefined): PriceDisplay;
+/**
+ * One entry per distinct PriceLabel across a plan catalog, in owner order
+ * (PriceLabel.sort_order, never alphabetical) - shared by every surface that
+ * renders a label switch ("Monthly"/"Annual" and similar).
+ */
+declare function collectPriceLabels(plans: PublicPlan[]): PublicPriceLabel[];
+interface LabelSavings {
+    labelSlug: string;
+    percent: number;
+}
+/**
+ * Per-month discount of the longest-billed label vs the shortest-billed one -
+ * the "Save X%" hint on a label switch. Compares what's actually charged
+ * (interval/amount), never the display_interval cosmetic - a label showing
+ * "10 EUR/mo" for an annual price still bills the year, and that's what the
+ * saving has to stay true about. Only returned once an actual plan prices
+ * both ends of the range: nothing is inferred from a single price, and a
+ * catalog that only sells the longest label can't claim a discount that
+ * doesn't apply to it.
+ */
+declare function resolveLabelSavings(plans: PublicPlan[], labels: PublicPriceLabel[]): LabelSavings | null;
+
+interface PricingTableContextValue {
+    plans: PublicPlan[];
+    labels: PublicPriceLabel[];
+    selectedLabelSlug: string | null;
+    setSelectedLabelSlug: (slug: string) => void;
+    savings: LabelSavings | null;
+    currentPlanId: string | null;
+    busyPriceId: string | null;
+    onSelectPlan: (plan: PublicPlan) => void;
+}
+/**
+ * Headless access to the same state `<PricingTable.LabelSwitch>`/`<PricingTable.Plan>`
+ * read - for a host building a fully custom layout around the data instead of
+ * the provided subcomponents. Must be called under `<PricingTable>`.
+ */
+declare function usePricingTable(): PricingTableContextValue;
+interface PricingTableProps extends Omit<KerneUIProps, 'logo'> {
+    /** Product the plans are read from. Omit for the tenant's default product. */
+    product?: string;
+    /** Label slug selected on first render. Defaults to the first label by PriceLabel.sort_order once the catalog loads. */
+    defaultLabel?: string;
+    /** Where the provider checkout should return to. */
+    checkoutSuccessUrl?: string;
+    checkoutCancelUrl?: string;
+    /** Overrides the built-in checkout - e.g. a marketing site that wants its own confirmation step first. */
+    onSelectPlan?: (plan: PublicPlan, price: PublicPlanPrice) => void;
+    children: React.ReactNode;
+}
+/**
+ * Provider + layout root. Renders a skeleton while the catalog loads and an
+ * error panel if it fails, so `<PricingTable.Plan>` children only ever mount
+ * once real data exists - they never have to handle a "plan not loaded yet"
+ * state of their own.
+ */
+declare function PricingTable({ product, defaultLabel, checkoutSuccessUrl, checkoutCancelUrl, onSelectPlan, appearance, className, children, }: PricingTableProps): react_jsx_runtime.JSX.Element;
+declare namespace PricingTable {
+    var LabelSwitch: () => react_jsx_runtime.JSX.Element | null;
+    var Plan: ({ slug, featured, badge, maxFeatures }: PricingTablePlanProps) => react_jsx_runtime.JSX.Element | null;
+    var Plans: ({ featuredSlug, featuredBadge, maxFeatures }: PricingTablePlansProps) => react_jsx_runtime.JSX.Element;
+}
+interface PricingTablePlanProps {
+    /** The plan to render - matched against `Plan.slug`. */
+    slug: string;
+    /** Visually distinguished (stronger border, soft elevation) - a host decision, never inferred from `is_default` (the free-tier fallback, not a "recommended" signal). */
+    featured?: boolean;
+    /** Eyebrow shown above the plan name, e.g. "Most popular". Only rendered when passed - no badge is invented from data. */
+    badge?: string;
+    /** Cap how many entitlements render before "+N more". Omit to show all. */
+    maxFeatures?: number;
+}
+interface PricingTablePlansProps {
+    /** Slug of the plan to visually feature - a host decision, see PricingTablePlanProps.featured. */
+    featuredSlug?: string;
+    /** Eyebrow on the featured plan, e.g. "Most popular". */
+    featuredBadge?: string;
+    maxFeatures?: number;
+}
+
 interface CheckoutResultProps extends KerneUIProps {
     /** `cancel` renders the abandoned-checkout copy and skips polling entirely. */
     outcome?: 'success' | 'cancel';
@@ -388,4 +523,4 @@ interface UpgradePromptProps extends Omit<KerneUIProps, 'logo'> {
 }
 declare function UpgradePrompt({ featureKey, requested, featureName, children, upgradeUrl, onUpgradeClick, upgradeLabel, title, description, hideWhileLoading, appearance, className, }: UpgradePromptProps): react_jsx_runtime.JSX.Element | null;
 
-export { ActivateAccountForm, type ActivateAccountFormProps, AuthFlow, type AuthFlowProps, type AuthFlowStep, BillingSection, type BillingSectionProps, ChangePasswordForm, type ChangePasswordFormProps, CheckoutResult, type CheckoutResultProps, ForgotPasswordForm, type ForgotPasswordFormProps, type KerneAppearance, LoginForm, type LoginFormProps, MagicLinkCallback, type MagicLinkCallbackProps, ProfileSection, type ProfileSectionProps, RegisterForm, type RegisterFormProps, ResetPasswordForm, type ResetPasswordFormProps, SecuritySection, type SecuritySectionProps, SignOutButton, type SignOutButtonProps, SubscriptionCard, type SubscriptionCardProps, UpgradePrompt, type UpgradePromptProps, UsageMeters, type UsageMetersProps, UserButton, type UserButtonMenuItem, type UserButtonProps, UserProfile, type UserProfileExtraTab, type UserProfileProps, type UserProfileTab, VerifyEmailForm, type VerifyEmailFormProps, WaitlistForm, type WaitlistFormProps };
+export { ActivateAccountForm, type ActivateAccountFormProps, AuthFlow, type AuthFlowProps, type AuthFlowStep, BillingSection, type BillingSectionProps, ChangePasswordForm, type ChangePasswordFormProps, CheckoutResult, type CheckoutResultProps, ForgotPasswordForm, type ForgotPasswordFormProps, type KerneAppearance, KerneLocalization, type LabelSavings, LoginForm, type LoginFormProps, MagicLinkCallback, type MagicLinkCallbackProps, type PriceDisplay, PricingTable, type PricingTablePlanProps, type PricingTablePlansProps, type PricingTableProps, ProfileSection, type ProfileSectionProps, RegisterForm, type RegisterFormProps, ResetPasswordForm, type ResetPasswordFormProps, SecuritySection, type SecuritySectionProps, SignOutButton, type SignOutButtonProps, SubscriptionCard, type SubscriptionCardProps, UpgradePrompt, type UpgradePromptProps, UsageMeters, type UsageMetersProps, UserButton, type UserButtonMenuItem, type UserButtonProps, UserProfile, type UserProfileExtraTab, type UserProfileProps, type UserProfileTab, VerifyEmailForm, type VerifyEmailFormProps, WaitlistForm, type WaitlistFormProps, collectPriceLabels, formatDate, formatInterval, formatMoney, formatNumber, humanizeFeatureKey, resolveLabelSavings, resolvePriceDisplay, usePricingTable };

package/dist/ui/index.d.ts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { SubscriptionWithPlan } from '@kerne/types';
-export { K as KerneLocalization, d as defaultLocalization, u as useLocalization } from '../i18n-BWTT1DWD.js';
+import { PublicPlan, PublicPriceLabel, PublicPlanPrice, SubscriptionWithPlan } from '@kerne/types';
+import { K as KerneLocalization } from '../i18n-QilNgwqe.js';
+export { d as defaultLocalization, u as useLocalization } from '../i18n-QilNgwqe.js';
 
 /**
  * Per-instance overrides of the same custom properties the stylesheet reads,
@@ -332,8 +333,10 @@ interface SubscriptionCardProps extends Omit<KerneUIProps, 'logo'> {
     onUpgradeClick?: () => void;
     /** Hide the "Manage billing" button (e.g. when the page has its own). */
     hidePortalButton?: boolean;
+    /** Hide the "Cancel subscription" button, e.g. when cancellation goes through sales/support. */
+    hideCancelButton?: boolean;
 }
-declare function SubscriptionCard({ productSlug, title, portalReturnUrl, upgradeUrl, onUpgradeClick, hidePortalButton, appearance, className, }: SubscriptionCardProps): react_jsx_runtime.JSX.Element;
+declare function SubscriptionCard({ productSlug, title, portalReturnUrl, upgradeUrl, onUpgradeClick, hidePortalButton, hideCancelButton, appearance, className, }: SubscriptionCardProps): react_jsx_runtime.JSX.Element;
 
 interface UsageMetersProps extends Omit<KerneUIProps, 'logo'> {
     /** Heading above the meters. Omit for the localized default, `null` for none. */
@@ -351,6 +354,138 @@ interface UsageMetersProps extends Omit<KerneUIProps, 'logo'> {
 }
 declare function UsageMeters({ title, featureKeys, showUnlimited, limit: maxRows, labels, emptyState, appearance, className, }: UsageMetersProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Display helpers shared by the billing and usage components.
+ */
+
+/**
+ * Last-resort label for a feature.
+ *
+ * `GET /v1/billing/entitlements` returns `feature_key` but no `feature_name`
+ * (see EntitlementSummary), while the subscription payload does carry names -
+ * so components cross-reference the subscription first and only fall back
+ * here for a scope on a default pack, which has no subscription to read names
+ * from. Turning `api_calls` into "Api calls" is not as good as the real name;
+ * it is only better than showing a raw key to an end user.
+ */
+declare function humanizeFeatureKey(key: string): string;
+/** Amounts are stored in minor units (cents), as the provider APIs return them. */
+declare function formatMoney(amountMinorUnits: number, currency: string): string;
+declare function formatNumber(value: number): string;
+declare function formatDate(iso: string | null): string | null;
+/**
+ * Normalises the provider's interval wording, then localizes it.
+ *
+ * `PlanPrice.interval` is Kerne's own "N+cycle" encoding ("1M", "3M", "1Y",
+ * "30D" - see apps/api's interval.ts), checked first since it's what every
+ * subscription/plan payload actually carries. The word-based fallback below
+ * stays for any raw provider string passed directly (Stripe says `month`,
+ * Polar says `monthly` - same thing to a reader). An interval matching
+ * neither falls through unchanged rather than being dropped: better a raw
+ * value than a price with no period attached.
+ */
+declare function formatInterval(interval: string, labels: IntervalLabels): string;
+type IntervalLabels = Pick<KerneLocalization['billing'], 'intervalMonth' | 'intervalYear' | 'intervalWeek' | 'intervalDay'>;
+interface PriceDisplay {
+    /** What's actually charged - show this alongside displayAmount, never hide it. */
+    billedAmount: number;
+    billedInterval: string;
+    /** The headline number a PriceLabel.display_interval asks to show instead. */
+    displayAmount: number;
+    displayInterval: string;
+}
+/**
+ * Resolves what to show for a price under a label's `display_interval` -
+ * e.g. an annual price shown as its monthly equivalent while still billing
+ * annually. `null`/`undefined`/equal-to-billed pass through unchanged. Divides
+ * once via approxMonths()'s ratio, never divide-then-multiply back to
+ * "verify" - a price rarely divides evenly (100 EUR/year -> 8.33 EUR/month,
+ * and 8.33 * 12 = 99.96, not 100).
+ */
+declare function resolvePriceDisplay(price: {
+    amount: number;
+    interval: string;
+}, displayInterval: string | null | undefined): PriceDisplay;
+/**
+ * One entry per distinct PriceLabel across a plan catalog, in owner order
+ * (PriceLabel.sort_order, never alphabetical) - shared by every surface that
+ * renders a label switch ("Monthly"/"Annual" and similar).
+ */
+declare function collectPriceLabels(plans: PublicPlan[]): PublicPriceLabel[];
+interface LabelSavings {
+    labelSlug: string;
+    percent: number;
+}
+/**
+ * Per-month discount of the longest-billed label vs the shortest-billed one -
+ * the "Save X%" hint on a label switch. Compares what's actually charged
+ * (interval/amount), never the display_interval cosmetic - a label showing
+ * "10 EUR/mo" for an annual price still bills the year, and that's what the
+ * saving has to stay true about. Only returned once an actual plan prices
+ * both ends of the range: nothing is inferred from a single price, and a
+ * catalog that only sells the longest label can't claim a discount that
+ * doesn't apply to it.
+ */
+declare function resolveLabelSavings(plans: PublicPlan[], labels: PublicPriceLabel[]): LabelSavings | null;
+
+interface PricingTableContextValue {
+    plans: PublicPlan[];
+    labels: PublicPriceLabel[];
+    selectedLabelSlug: string | null;
+    setSelectedLabelSlug: (slug: string) => void;
+    savings: LabelSavings | null;
+    currentPlanId: string | null;
+    busyPriceId: string | null;
+    onSelectPlan: (plan: PublicPlan) => void;
+}
+/**
+ * Headless access to the same state `<PricingTable.LabelSwitch>`/`<PricingTable.Plan>`
+ * read - for a host building a fully custom layout around the data instead of
+ * the provided subcomponents. Must be called under `<PricingTable>`.
+ */
+declare function usePricingTable(): PricingTableContextValue;
+interface PricingTableProps extends Omit<KerneUIProps, 'logo'> {
+    /** Product the plans are read from. Omit for the tenant's default product. */
+    product?: string;
+    /** Label slug selected on first render. Defaults to the first label by PriceLabel.sort_order once the catalog loads. */
+    defaultLabel?: string;
+    /** Where the provider checkout should return to. */
+    checkoutSuccessUrl?: string;
+    checkoutCancelUrl?: string;
+    /** Overrides the built-in checkout - e.g. a marketing site that wants its own confirmation step first. */
+    onSelectPlan?: (plan: PublicPlan, price: PublicPlanPrice) => void;
+    children: React.ReactNode;
+}
+/**
+ * Provider + layout root. Renders a skeleton while the catalog loads and an
+ * error panel if it fails, so `<PricingTable.Plan>` children only ever mount
+ * once real data exists - they never have to handle a "plan not loaded yet"
+ * state of their own.
+ */
+declare function PricingTable({ product, defaultLabel, checkoutSuccessUrl, checkoutCancelUrl, onSelectPlan, appearance, className, children, }: PricingTableProps): react_jsx_runtime.JSX.Element;
+declare namespace PricingTable {
+    var LabelSwitch: () => react_jsx_runtime.JSX.Element | null;
+    var Plan: ({ slug, featured, badge, maxFeatures }: PricingTablePlanProps) => react_jsx_runtime.JSX.Element | null;
+    var Plans: ({ featuredSlug, featuredBadge, maxFeatures }: PricingTablePlansProps) => react_jsx_runtime.JSX.Element;
+}
+interface PricingTablePlanProps {
+    /** The plan to render - matched against `Plan.slug`. */
+    slug: string;
+    /** Visually distinguished (stronger border, soft elevation) - a host decision, never inferred from `is_default` (the free-tier fallback, not a "recommended" signal). */
+    featured?: boolean;
+    /** Eyebrow shown above the plan name, e.g. "Most popular". Only rendered when passed - no badge is invented from data. */
+    badge?: string;
+    /** Cap how many entitlements render before "+N more". Omit to show all. */
+    maxFeatures?: number;
+}
+interface PricingTablePlansProps {
+    /** Slug of the plan to visually feature - a host decision, see PricingTablePlanProps.featured. */
+    featuredSlug?: string;
+    /** Eyebrow on the featured plan, e.g. "Most popular". */
+    featuredBadge?: string;
+    maxFeatures?: number;
+}
+
 interface CheckoutResultProps extends KerneUIProps {
     /** `cancel` renders the abandoned-checkout copy and skips polling entirely. */
     outcome?: 'success' | 'cancel';
@@ -388,4 +523,4 @@ interface UpgradePromptProps extends Omit<KerneUIProps, 'logo'> {
 }
 declare function UpgradePrompt({ featureKey, requested, featureName, children, upgradeUrl, onUpgradeClick, upgradeLabel, title, description, hideWhileLoading, appearance, className, }: UpgradePromptProps): react_jsx_runtime.JSX.Element | null;
 
-export { ActivateAccountForm, type ActivateAccountFormProps, AuthFlow, type AuthFlowProps, type AuthFlowStep, BillingSection, type BillingSectionProps, ChangePasswordForm, type ChangePasswordFormProps, CheckoutResult, type CheckoutResultProps, ForgotPasswordForm, type ForgotPasswordFormProps, type KerneAppearance, LoginForm, type LoginFormProps, MagicLinkCallback, type MagicLinkCallbackProps, ProfileSection, type ProfileSectionProps, RegisterForm, type RegisterFormProps, ResetPasswordForm, type ResetPasswordFormProps, SecuritySection, type SecuritySectionProps, SignOutButton, type SignOutButtonProps, SubscriptionCard, type SubscriptionCardProps, UpgradePrompt, type UpgradePromptProps, UsageMeters, type UsageMetersProps, UserButton, type UserButtonMenuItem, type UserButtonProps, UserProfile, type UserProfileExtraTab, type UserProfileProps, type UserProfileTab, VerifyEmailForm, type VerifyEmailFormProps, WaitlistForm, type WaitlistFormProps };
+export { ActivateAccountForm, type ActivateAccountFormProps, AuthFlow, type AuthFlowProps, type AuthFlowStep, BillingSection, type BillingSectionProps, ChangePasswordForm, type ChangePasswordFormProps, CheckoutResult, type CheckoutResultProps, ForgotPasswordForm, type ForgotPasswordFormProps, type KerneAppearance, KerneLocalization, type LabelSavings, LoginForm, type LoginFormProps, MagicLinkCallback, type MagicLinkCallbackProps, type PriceDisplay, PricingTable, type PricingTablePlanProps, type PricingTablePlansProps, type PricingTableProps, ProfileSection, type ProfileSectionProps, RegisterForm, type RegisterFormProps, ResetPasswordForm, type ResetPasswordFormProps, SecuritySection, type SecuritySectionProps, SignOutButton, type SignOutButtonProps, SubscriptionCard, type SubscriptionCardProps, UpgradePrompt, type UpgradePromptProps, UsageMeters, type UsageMetersProps, UserButton, type UserButtonMenuItem, type UserButtonProps, UserProfile, type UserProfileExtraTab, type UserProfileProps, type UserProfileTab, VerifyEmailForm, type VerifyEmailFormProps, WaitlistForm, type WaitlistFormProps, collectPriceLabels, formatDate, formatInterval, formatMoney, formatNumber, humanizeFeatureKey, resolveLabelSavings, resolvePriceDisplay, usePricingTable };