@kerne/react 0.1.0 → 0.1.2

package/dist/ui/index.d.cts

@@ -0,0 +1,391 @@
+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-Qketn1RF.cjs';
+
+/**
+ * Per-instance overrides of the same custom properties the stylesheet reads,
+ * applied as inline style so they win over the class defaults without
+ * specificity tricks.
+ */
+interface KerneAppearance {
+    /**
+     * `light` (default), `dark`, or `system` to follow the visitor's OS. Not
+     * defaulted to `system`: a light-only host would silently render a dark form
+     * for half its users.
+     */
+    theme?: 'light' | 'dark' | 'system';
+    /**
+     * The brand colour. Drives the primary button, and - unless overridden below -
+     * its label, its hover, and the accent used for focus rings and links.
+     */
+    primaryColor?: string;
+    /** Label on the primary button. Derived from `primaryColor` when omitted. */
+    primaryTextColor?: string;
+    /** Focus rings and links. Falls back to `primaryColor`. */
+    accentColor?: string;
+    textColor?: string;
+    borderColor?: string;
+    /** Background of error/info panels. */
+    panelColor?: string;
+    /**
+     * The ground the component sits on. Leave unset when embedding (the host's
+     * page shows through); set it when the component owns the viewport, so its
+     * text can never resolve against a background it doesn't know about.
+     */
+    background?: string;
+    /** Opaque ground for the card variant, the account dropdown, a pressed segment. */
+    surfaceColor?: string;
+    /** `card` wraps the screen in a bordered, raised container. Defaults to `none`. */
+    surface?: 'none' | 'card';
+    fontFamily?: string;
+    /** Corner radius on inputs and buttons, e.g. `"0px"` for square. */
+    radius?: string;
+    /** Height of inputs and buttons. Defaults to `"44px"`. */
+    controlHeight?: string;
+}
+
+interface KerneUIProps {
+    appearance?: KerneAppearance;
+    /** Rendered above the heading - a wordmark or logo. */
+    logo?: React.ReactNode;
+    className?: string;
+}
+
+type AuthFlowStep = 'sign-in' | 'sign-up' | 'forgot-password' | 'reset-password' | 'magic-link' | 'verify-email' | 'activate';
+interface AuthFlowProps extends KerneUIProps {
+    /** Where to start when nothing in the URL says otherwise. */
+    initialStep?: AuthFlowStep;
+    /** Controlled mode - pair with `onStepChange` to drive the flow from your router. */
+    step?: AuthFlowStep;
+    onStepChange?: (step: AuthFlowStep) => void;
+    /** Called once the user holds a session. */
+    onSuccess?: () => void;
+    /** Hand the session to another origin (the hosted portal's job). */
+    redirectUrl?: string;
+    /** Where emailed links should land. Defaults to the tenant's configured callbacks. */
+    magicLinkCallbackUrl?: string;
+    resetPasswordCallbackUrl?: string;
+    verificationCallbackUrl?: string;
+    /** Skip sign-up entirely, even on an OPEN tenant (e.g. an internal tool). */
+    allowSignUp?: boolean;
+    legal?: React.ReactNode;
+}
+declare function AuthFlow({ initialStep, step: controlledStep, onStepChange, onSuccess, redirectUrl, magicLinkCallbackUrl, resetPasswordCallbackUrl, verificationCallbackUrl, allowSignUp, legal, appearance, logo, className, }: AuthFlowProps): react_jsx_runtime.JSX.Element;
+
+interface LoginFormProps extends KerneUIProps {
+    /** Called after a successful password sign-in. */
+    onSuccess?: () => void;
+    /**
+     * Hand the session to another origin after sign-in (the hosted portal's
+     * job - see `redirectWithSession`). Takes precedence over `onSuccess`.
+     */
+    redirectUrl?: string;
+    /** Where the emailed sign-in link should land. Defaults to the tenant's configured callback. */
+    magicLinkCallbackUrl?: string;
+    signUpUrl?: string;
+    onSignUpClick?: () => void;
+    forgotPasswordUrl?: string;
+    onForgotPasswordClick?: () => void;
+    onOAuthSelect?: (provider: string) => void;
+    title?: string;
+    /** Replaces the "First time here? Sign up" line under the title. */
+    subtitle?: React.ReactNode;
+    /** Small print under the form, e.g. terms and privacy links. */
+    legal?: React.ReactNode;
+}
+declare function LoginForm({ onSuccess, redirectUrl, magicLinkCallbackUrl, signUpUrl, onSignUpClick, forgotPasswordUrl, onForgotPasswordClick, onOAuthSelect, title, subtitle, legal, appearance, logo, className, }: LoginFormProps): react_jsx_runtime.JSX.Element;
+
+interface RegisterFormProps extends KerneUIProps {
+    onSuccess?: () => void;
+    /** Hand the session to another origin after sign-up (hosted portal). */
+    redirectUrl?: string;
+    /** Where the emailed sign-up link should land. Defaults to the tenant's configured callback. */
+    magicLinkCallbackUrl?: string;
+    /**
+     * Invitation token. Read from `?token=` in the URL when omitted, so an
+     * emailed invitation link works with no wiring on the host's side.
+     */
+    invitationToken?: string;
+    signInUrl?: string;
+    onSignInClick?: () => void;
+    onOAuthSelect?: (provider: string) => void;
+    title?: string;
+    subtitle?: React.ReactNode;
+    legal?: React.ReactNode;
+    /** Collect a display name alongside the credentials. */
+    collectName?: boolean;
+}
+declare function RegisterForm({ onSuccess, redirectUrl, magicLinkCallbackUrl, invitationToken: invitationTokenProp, signInUrl, onSignInClick, onOAuthSelect, title, subtitle, legal, collectName, appearance, logo, className, }: RegisterFormProps): react_jsx_runtime.JSX.Element;
+
+interface MagicLinkCallbackProps extends KerneUIProps {
+    /** Overrides the `?token=` query param - for hosts that parse routes themselves. */
+    token?: string;
+    onSuccess?: () => void;
+    /** Hand the session to another origin after sign-in (hosted portal). */
+    redirectUrl?: string;
+    signInUrl?: string;
+    onSignInClick?: () => void;
+}
+declare function MagicLinkCallback({ token: tokenProp, onSuccess, redirectUrl, signInUrl, onSignInClick, appearance, logo, className, }: MagicLinkCallbackProps): react_jsx_runtime.JSX.Element;
+
+interface ForgotPasswordFormProps extends KerneUIProps {
+    /** Where the emailed reset link should land. Defaults to the tenant's configured callback. */
+    callbackUrl?: string;
+    signInUrl?: string;
+    onSignInClick?: () => void;
+    onSent?: (email: string) => void;
+    title?: string;
+    subtitle?: React.ReactNode;
+}
+declare function ForgotPasswordForm({ callbackUrl, signInUrl, onSignInClick, onSent, title, subtitle, appearance, logo, className, }: ForgotPasswordFormProps): react_jsx_runtime.JSX.Element;
+
+interface ResetPasswordFormProps extends KerneUIProps {
+    /** Overrides the `?token=` query param. */
+    token?: string;
+    signInUrl?: string;
+    onSignInClick?: () => void;
+    onSuccess?: () => void;
+    title?: string;
+    subtitle?: React.ReactNode;
+}
+declare function ResetPasswordForm({ token: tokenProp, signInUrl, onSignInClick, onSuccess, title, subtitle, appearance, logo, className, }: ResetPasswordFormProps): react_jsx_runtime.JSX.Element;
+
+interface VerifyEmailFormProps extends KerneUIProps {
+    /** Overrides the `?token=` query param. */
+    token?: string;
+    /** Where a resent verification link should land. */
+    callbackUrl?: string;
+    onVerified?: () => void;
+    title?: string;
+    subtitle?: React.ReactNode;
+}
+declare function VerifyEmailForm({ token: tokenProp, callbackUrl, onVerified, title, subtitle, appearance, logo, className, }: VerifyEmailFormProps): react_jsx_runtime.JSX.Element;
+
+interface ActivateAccountFormProps extends KerneUIProps {
+    /** Overrides the `?token=` query param. */
+    token?: string;
+    onSuccess?: () => void;
+    /** Hand the session to another origin after activation (hosted portal). */
+    redirectUrl?: string;
+    signInUrl?: string;
+    onSignInClick?: () => void;
+    title?: string;
+}
+declare function ActivateAccountForm({ token: tokenProp, onSuccess, redirectUrl, signInUrl, onSignInClick, title, appearance, logo, className, }: ActivateAccountFormProps): react_jsx_runtime.JSX.Element;
+
+interface ChangePasswordFormProps extends Omit<KerneUIProps, 'logo'> {
+    onSuccess?: () => void;
+    /** Heading above the fields. Omit for the localized default, `null` for none. */
+    title?: string | null;
+}
+declare function ChangePasswordForm({ onSuccess, title, appearance, className, }: ChangePasswordFormProps): react_jsx_runtime.JSX.Element;
+
+interface WaitlistFormProps extends KerneUIProps {
+    title?: string;
+    subtitle?: React.ReactNode;
+    /** Collect a name alongside the email. */
+    collectName?: boolean;
+    /** Attached to the entry - campaign, referrer, anything you want back later. */
+    metadata?: Record<string, unknown>;
+    submitLabel?: string;
+    /** Replaces the default confirmation copy. */
+    successMessage?: React.ReactNode;
+    onJoined?: (email: string) => void;
+    legal?: React.ReactNode;
+}
+declare function WaitlistForm({ title, subtitle, collectName, metadata, submitLabel, successMessage, onJoined, legal, appearance, logo, className, }: WaitlistFormProps): react_jsx_runtime.JSX.Element;
+
+interface SignOutButtonProps {
+    /** Omit for the localized "Sign out" label. */
+    children?: React.ReactNode;
+    onSignedOut?: () => void;
+    /** Where to send the browser after signing out. */
+    redirectUrl?: string;
+    className?: string;
+    appearance?: KerneAppearance;
+}
+declare function SignOutButton({ children, onSignedOut, redirectUrl, className, appearance, }: SignOutButtonProps): react_jsx_runtime.JSX.Element;
+interface UserButtonMenuItem {
+    label: string;
+    href?: string;
+    onClick?: () => void;
+}
+interface UserButtonProps {
+    /** Extra entries above "Sign out" - profile, settings, billing. */
+    items?: UserButtonMenuItem[];
+    onSignedOut?: () => void;
+    signOutRedirectUrl?: string;
+    /** Rendered instead of nothing when signed out - e.g. a sign-in link. */
+    signedOutFallback?: React.ReactNode;
+    appearance?: KerneAppearance;
+    className?: string;
+}
+declare function UserButton({ items, onSignedOut, signOutRedirectUrl, signedOutFallback, appearance, className, }: UserButtonProps): react_jsx_runtime.JSX.Element;
+
+type UserProfileTab = 'profile' | 'security' | 'billing';
+interface UserProfileExtraTab {
+    /** Must not collide with a built-in id. */
+    id: string;
+    label: string;
+    title?: string;
+    description?: string;
+    content: React.ReactNode;
+}
+interface UserProfileProps extends Omit<KerneUIProps, 'logo'> {
+    /** Which built-in tabs to show, in this order. */
+    tabs?: UserProfileTab[];
+    /** Appended after the built-in tabs. */
+    extraTabs?: UserProfileExtraTab[];
+    /** Tab shown on mount. Defaults to the first one. */
+    defaultTab?: string;
+    /** Controlled mode - pair with `onTabChange` to drive tabs from your router. */
+    activeTab?: string;
+    onTabChange?: (tab: string) => void;
+    showDeleteAccount?: boolean;
+    onSaved?: () => void;
+    onDeleted?: () => void;
+    productSlug?: string;
+    pricingProductIdOrSlug?: string;
+    portalReturnUrl?: string;
+    checkoutSuccessUrl?: string;
+    checkoutCancelUrl?: string;
+    showPlanSwitcher?: boolean;
+    showUsage?: boolean;
+    usageFeatureKeys?: string[];
+    usageLabels?: Record<string, string>;
+    verificationCallbackUrl?: string;
+}
+declare function UserProfile({ tabs, extraTabs, defaultTab, activeTab: controlledTab, onTabChange, showDeleteAccount, onSaved, onDeleted, productSlug, pricingProductIdOrSlug, portalReturnUrl, checkoutSuccessUrl, checkoutCancelUrl, showPlanSwitcher, showUsage, usageFeatureKeys, usageLabels, verificationCallbackUrl, appearance, className, }: UserProfileProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * "Profile" pane: who the user is, and the address they sign in with.
+ *
+ * The email is deliberately read-only. Changing the address a session is keyed
+ * on is a re-verification flow, not a text field, and no endpoint implements it
+ * today - rendering an editable input would promise something that silently
+ * fails on save.
+ */
+interface ProfileSectionProps {
+    /** Where a resent verification link should land. */
+    verificationCallbackUrl?: string;
+    onSaved?: () => void;
+}
+declare function ProfileSection({ verificationCallbackUrl, onSaved }: ProfileSectionProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * "Security" pane: password, and leaving.
+ *
+ * Clerk's equivalent also lists active sessions and 2FA. Neither is rendered
+ * here because neither exists in the API - there is no session-listing or TOTP
+ * endpoint (checked against the public OpenAPI spec). An empty "Active devices"
+ * card that never populates is worse than no card, so these appear only once
+ * there is something real behind them.
+ *
+ * The password block hides itself on a magic-link-only tenant: there is no
+ * password to change, and `POST /auth/password` would refuse anyway.
+ */
+interface SecuritySectionProps {
+    showDeleteAccount?: boolean;
+    onDeleted?: () => void;
+}
+declare function SecuritySection({ showDeleteAccount, onDeleted }: SecuritySectionProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * "Billing" pane: the active plan, what it has been used for, and how to move
+ * to another one.
+ *
+ * The plan switcher is a settings control, not the marketing pricing page: it
+ * lists what this scope can move to and starts a checkout, and deliberately
+ * does not sell. `<PricingTable>` is the surface that sells.
+ *
+ * Interval handling is the honest minimum until PriceLabel exists (see
+ * 34-ENTITLEMENT-ENGINE.md §9.2): prices are grouped by `interval`, and the
+ * segmented control only renders when a plan genuinely has more than one. A
+ * plan carrying a third price (early-bird, non-profit) still has no way to be
+ * described here - which is exactly the gap PriceLabel closes.
+ */
+interface BillingSectionProps {
+    productSlug?: string;
+    /** Product the plan list is read from. Defaults to the tenant's default product. */
+    pricingProductIdOrSlug?: string;
+    portalReturnUrl?: string;
+    checkoutSuccessUrl?: string;
+    checkoutCancelUrl?: string;
+    /** Hide the plan switcher, e.g. when plan changes go through sales. */
+    showPlanSwitcher?: boolean;
+    showUsage?: boolean;
+    usageFeatureKeys?: string[];
+    usageLabels?: Record<string, string>;
+}
+declare function BillingSection({ productSlug, pricingProductIdOrSlug, portalReturnUrl, checkoutSuccessUrl, checkoutCancelUrl, showPlanSwitcher, showUsage, usageFeatureKeys, usageLabels, }: BillingSectionProps): react_jsx_runtime.JSX.Element;
+
+interface SubscriptionCardProps extends Omit<KerneUIProps, 'logo'> {
+    /** Restrict to one product, when the tenant sells several. */
+    productSlug?: string;
+    /** Heading above the details. Omit for the localized default, `null` for none. */
+    title?: string | null;
+    /** Where the provider portal should return to. */
+    portalReturnUrl?: string;
+    /** Shown when there is no active subscription - your pricing page. */
+    upgradeUrl?: string;
+    onUpgradeClick?: () => void;
+    /** Hide the "Manage billing" button (e.g. when the page has its own). */
+    hidePortalButton?: boolean;
+}
+declare function SubscriptionCard({ productSlug, title, portalReturnUrl, upgradeUrl, onUpgradeClick, hidePortalButton, 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. */
+    title?: string | null;
+    /** Restrict to these feature keys, in this order - skips the automatic ordering. */
+    featureKeys?: string[];
+    /** Show entitlements with no ceiling. Off by default: there is no progress to show. */
+    showUnlimited?: boolean;
+    /** Cap how many meters render, after ordering. */
+    limit?: number;
+    /** Override the label for a feature key, when the API name is not end-user wording. */
+    labels?: Record<string, string>;
+    /** Rendered when the scope has no metered quota at all. */
+    emptyState?: React.ReactNode;
+}
+declare function UsageMeters({ title, featureKeys, showUnlimited, limit: maxRows, labels, emptyState, appearance, className, }: UsageMetersProps): react_jsx_runtime.JSX.Element;
+
+interface CheckoutResultProps extends KerneUIProps {
+    /** `cancel` renders the abandoned-checkout copy and skips polling entirely. */
+    outcome?: 'success' | 'cancel';
+    productSlug?: string;
+    /** Where "Continue" sends the user once the subscription is confirmed. */
+    continueUrl?: string;
+    onContinue?: () => void;
+    /** Where to go back to after a cancelled checkout - your pricing page. */
+    pricingUrl?: string;
+    onRetry?: () => void;
+    onConfirmed?: (subscription: SubscriptionWithPlan) => void;
+    /** How long to wait for the webhook before showing the "still finishing" state. */
+    confirmTimeoutMs?: number;
+}
+declare function CheckoutResult({ outcome, productSlug, continueUrl, onContinue, pricingUrl, onRetry, onConfirmed, confirmTimeoutMs, appearance, logo, className, }: CheckoutResultProps): react_jsx_runtime.JSX.Element;
+
+interface UpgradePromptProps extends Omit<KerneUIProps, 'logo'> {
+    /** The entitlement that gates the feature. */
+    featureKey: string;
+    /** How much the action needs, for a quota check. */
+    requested?: number;
+    /** Human name for the gated capability - beats the raw key in the copy. */
+    featureName?: string;
+    /** Rendered instead of the prompt when the check allows it. */
+    children?: React.ReactNode;
+    /** Your pricing page. */
+    upgradeUrl?: string;
+    onUpgradeClick?: () => void;
+    upgradeLabel?: string;
+    title?: string;
+    /** Replaces the generated explanation entirely. */
+    description?: React.ReactNode;
+    /** Render nothing at all while the check is in flight. Off by default. */
+    hideWhileLoading?: boolean;
+}
+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 };