@ttoss/react-billing 0.5.11 → 0.5.13

package/dist/index.d.cts

@@ -0,0 +1,459 @@
+
+import { IconType } from "@ttoss/react-icons";
+import { ButtonProps, CardProps } from "@ttoss/ui";
+import * as React from "react";
+
+//#region src/components/planCard/PlanCardVariants.d.ts
+type PlanCardVariantType = 'primary' | 'secondary'
+/**
+ * @deprecated Use `primary`.
+ */
+| 'default'
+/**
+ * @deprecated Use `secondary`.
+ */
+| 'enterprise';
+type PlanCardVariant = PlanCardVariantType;
+//#endregion
+//#region src/components/planCard/PlanCardMetadataSlot.d.ts
+type PlanCardMetadataSlotParameter = {
+  name: string;
+  value: React.ReactNode;
+};
+type PlanCardMetadataSlotService = {
+  label: string;
+  icon?: IconType;
+  parameters: PlanCardMetadataSlotParameter[];
+  id?: string;
+  key?: string;
+};
+type PlanCardMetadataSlotVariant = PlanCardVariantType;
+interface PlanCardMetadataSlotProps {
+  metadata: PlanCardMetadataSlotService[];
+  variant?: PlanCardMetadataSlotVariant;
+}
+//#endregion
+//#region src/components/planCard/PlanCard.d.ts
+type PlanCardMetadata = PlanCardMetadataSlotService[];
+type PlanCardPrice = {
+  value: string | number;
+  interval: string;
+  description?: string;
+};
+type PlanCardButtonProps = Omit<ButtonProps, 'children'> & {
+  label?: string;
+  leftIcon?: IconType;
+};
+interface PlanCardProps extends Omit<CardProps, 'children'> {
+  variant?: PlanCardVariant;
+  topTag?: React.ReactNode;
+  title: string;
+  subtitle?: string;
+  metadata?: PlanCardMetadata;
+  metadataVariant?: PlanCardMetadataSlotVariant;
+  price: PlanCardPrice;
+  features?: unknown[];
+  buttonProps?: PlanCardButtonProps;
+}
+declare const PlanCard: (props: PlanCardProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/components/plansPanel/PlansPanel.types.d.ts
+/**
+ * A single option inside a PlansPanel filter.
+ */
+interface PlansPanelFilterOption {
+  /** Display label shown in the SegmentedControl. */
+  label: string;
+  /** Value used for filtering plans. */
+  value: string;
+}
+/**
+ * Defines one filter dimension rendered as a SegmentedControl above the plans grid.
+ */
+interface PlansPanelFilter {
+  /** Unique identifier for this filter dimension. */
+  id: string;
+  /** Optional label rendered above the SegmentedControl. */
+  label?: string;
+  /** List of selectable options. */
+  options: PlansPanelFilterOption[];
+  /** Initial value used in uncontrolled mode. */
+  defaultValue?: string;
+}
+/**
+ * A plan displayed inside the PlansPanel.
+ */
+interface PlansPanelPlan {
+  /** Unique plan identifier. */
+  id: string;
+  /**
+   * Maps each filter id to the value this plan belongs to.
+   * Plans are only shown when all active filter values match.
+   */
+  filterValues?: Record<string, string>;
+  /** Plan title (e.g. "Basic", "Pro"). */
+  title: string;
+  /** Optional subtitle displayed below the title. */
+  subtitle?: string;
+  /** Pricing information. */
+  price: PlanCardPrice;
+  /** Feature list items. */
+  features?: unknown[];
+  /** Optional metadata sections. */
+  metadata?: PlanCardMetadata;
+  /** Props forwarded to the CTA button. onClick is merged with onSelectPlan. */
+  buttonProps?: PlanCardButtonProps;
+  /** Visual variant for the PlanCard. Active plans override this with "secondary". */
+  variant?: PlanCardVariant;
+  /** Optional content rendered at the top of the PlanCard. */
+  topTag?: React.ReactNode;
+}
+/**
+ * Props for the PlansPanel component.
+ */
+interface PlansPanelProps {
+  /**
+   * Filter dimensions rendered as SegmentedControl rows above the plan grid.
+   * Each dimension independently narrows the visible set of plans.
+   */
+  filters?: PlansPanelFilter[];
+  /** All available plans. Only plans matching every active filter value are shown. */
+  plans: PlansPanelPlan[];
+  /** ID of the currently active/subscribed plan. That card is highlighted. */
+  activePlanId?: string;
+  /**
+   * Called when the user clicks the CTA button of a plan.
+   * @param planId - The id of the selected plan.
+   */
+  onSelectPlan?: (planId: string) => void;
+  /**
+   * Controlled filter values (record of filterId → selected value).
+   * When provided the component operates in controlled mode and internal
+   * state is not used.
+   */
+  filterValues?: Record<string, string>;
+  /**
+   * Called when a filter value changes in controlled mode.
+   * @param id - The filter id that changed.
+   * @param value - The new selected value.
+   */
+  onFilterChange?: (id: string, value: string) => void;
+}
+//#endregion
+//#region src/components/plansPanel/PlansPanel.d.ts
+/**
+ * PlansPanel renders a grid of PlanCard components with optional multi-dimensional
+ * SegmentedControl filters above them.
+ *
+ * Each filter dimension independently narrows the visible set of plan cards.
+ * The component supports both uncontrolled mode (internal state from `defaultValue`)
+ * and controlled mode (via `filterValues` + `onFilterChange`).
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled — component manages filter state internally
+ * <PlansPanel
+ *   filters={[
+ *     {
+ *       id: 'interval',
+ *       label: 'Billing Frequency',
+ *       options: [
+ *         { label: 'Monthly', value: 'monthly' },
+ *         { label: 'Yearly',  value: 'yearly' },
+ *       ],
+ *       defaultValue: 'monthly',
+ *     },
+ *   ]}
+ *   plans={plans}
+ *   activePlanId="plan_basic_monthly"
+ *   onSelectPlan={(planId) => console.log(planId)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled — consumer owns filter state
+ * <PlansPanel
+ *   filters={filters}
+ *   filterValues={{ interval: 'yearly' }}
+ *   onFilterChange={(id, value) =>
+ *     setFilterValues((prev) => ({ ...prev, [id]: value }))
+ *   }
+ *   plans={plans}
+ *   onSelectPlan={(planId) => checkout(planId)}
+ * />
+ * ```
+ */
+declare const PlansPanel: ({
+  filters,
+  plans,
+  activePlanId,
+  onSelectPlan,
+  filterValues: controlledFilterValues,
+  onFilterChange
+}: PlansPanelProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/components/subscriptionPanel/SubscriptionPanel.styles.d.ts
+type SubscriptionPanelVariant = 'spotlight-accent' | 'spotlight-primary' | 'primary' | 'secondary' | 'accent';
+//#endregion
+//#region src/components/subscriptionPanel/SubscriptionPanel.types.d.ts
+/**
+ * Subscription status indicating the current state of the subscription.
+ */
+type SubscriptionStatus = 'active' | 'inactive' | 'cancelled';
+/**
+ * Base metric properties shared by all metric types.
+ */
+interface BaseMetric {
+  /**
+   * Label displayed above the metric value.
+   */
+  label: string;
+  /**
+   * Optional tooltip text or action handler for additional context.
+   * When a string is provided, it displays a simple tooltip.
+   * When a function is provided, it's called when the tooltip icon is clicked (e.g., to open help articles).
+   */
+  tooltip?: string | (() => void);
+  /**
+   * Icon to display alongside the metric.
+   */
+  icon?: IconType;
+  /**
+   * Optional click handler to make the metric card interactive.
+   */
+  onClick?: () => void;
+  /**
+   * Optional help article action handler.
+   */
+  helpArticleAction?: () => void;
+}
+/**
+ * Date-based metric for displaying dates like expiration or renewal.
+ */
+interface DateMetric extends BaseMetric {
+  type: 'date';
+  /**
+   * The date value to display.
+   */
+  date: string;
+  /**
+   * Optional message showing remaining days.
+   */
+  remainingDaysMessage?: string;
+  /**
+   * Whether to show a warning indicator.
+   */
+  isWarning?: boolean;
+}
+/**
+ * Percentage-based metric with progress bar.
+ */
+interface PercentageMetric extends BaseMetric {
+  type: 'percentage';
+  /**
+   * Current value.
+   */
+  current: number;
+  /**
+   * Maximum value. Use null for unlimited.
+   */
+  max: number | null;
+  /**
+   * Custom formatter for displaying values.
+   */
+  formatValue?: (value: number) => string;
+  /**
+   * Percentage threshold at which to show an alert.
+   */
+  showAlertThreshold?: number;
+}
+/**
+ * Number-based metric for displaying counts.
+ */
+interface NumberMetric extends BaseMetric {
+  type: 'number';
+  /**
+   * Current value.
+   */
+  current: number;
+  /**
+   * Maximum value. Use null for unlimited.
+   */
+  max: number | null;
+  /**
+   * Custom formatter for displaying values.
+   */
+  formatValue?: (value: number) => string;
+  /**
+   * Optional footer text below the metric.
+   */
+  footerText?: string;
+}
+/**
+ * Union type for all metric types.
+ */
+type MetricType = DateMetric | PercentageMetric | NumberMetric;
+/**
+ * Status badge configuration.
+ */
+interface SubscriptionPanelStatusBadgeProps {
+  /**
+   * The subscription status.
+   */
+  status: SubscriptionStatus;
+  /**
+   * Billing interval (e.g., "Mensal", "Anual").
+   */
+  interval?: string;
+  /**
+   * Whether the subscription has a pending cancellation.
+   */
+  hasCancellation?: boolean;
+  /**
+   * Whether the subscription has a scheduled update.
+   */
+  hasScheduledUpdate?: boolean;
+}
+/**
+ * Feature tag displayed in the card header.
+ */
+interface SubscriptionPanelFeatureTag {
+  /**
+   * Label text for the feature.
+   */
+  label: string;
+  /**
+   * Optional icon for the feature.
+   */
+  icon?: IconType;
+}
+/**
+ * Action button configuration.
+ */
+interface SubscriptionPanelAction extends Omit<ButtonProps, 'children'> {
+  /**
+   * Button label text.
+   */
+  label: string;
+  /**
+   * Click handler for the action.
+   */
+  onClick: () => void;
+  /**
+   * Optional icon for the button.
+   */
+  leftIcon?: IconType;
+  /**
+   * Whether the action is currently loading.
+   */
+  isLoading?: boolean;
+}
+/**
+ * Price configuration.
+ */
+interface SubscriptionPanelPrice {
+  /**
+   * Price value (e.g., "R$ 5,00").
+   */
+  value: string;
+  /**
+   * Price interval (e.g., "mês", "ano").
+   */
+  interval?: string;
+}
+/**
+ * Main SubscriptionPanel props.
+ */
+interface SubscriptionPanelProps {
+  /**
+   * Visual variant for the accent bar and header icon.
+   * @default 'spotlight'
+   */
+  variant?: SubscriptionPanelVariant;
+  /**
+   * Plan icon to display. Can be a ReactNode or an IconType string.
+   */
+  icon?: string;
+  /**
+   * Name of the subscription plan.
+   */
+  planName: string;
+  /**
+   * Price configuration.
+   */
+  price: SubscriptionPanelPrice;
+  /**
+   * Status badge configuration.
+   */
+  status: SubscriptionPanelStatusBadgeProps;
+  /**
+   * Feature tags to display.
+   */
+  features?: SubscriptionPanelFeatureTag[];
+  /**
+   * Action buttons.
+   */
+  actions?: SubscriptionPanelAction[];
+  /**
+   * Metrics to display in the card.
+   */
+  metrics?: MetricType[];
+  /**
+   * Whether the card is in a loading state.
+   */
+  isLoading?: boolean;
+}
+//#endregion
+//#region src/components/subscriptionPanel/SubscriptionPanel.d.ts
+/**
+ * SubscriptionPanel displays comprehensive subscription information including
+ * plan details, status, actions, and various metrics.
+ *
+ * It supports three types of metrics:
+ * - **Date**: For displaying dates like expiration or renewal
+ * - **Percentage**: For usage-based metrics with progress bars
+ * - **Number**: For count-based metrics
+ *
+ * @example
+ * ```tsx
+ * <SubscriptionPanel
+ *   planName="Premium Plan"
+ *   price={{ value: "R$ 99,00", interval: "mês" }}
+ *   status={{ status: "active", interval: "Mensal" }}
+ *   features={[{ label: "Feature 1" }, { label: "Feature 2" }]}
+ *   actions={[
+ *     { label: "Upgrade", onClick: () => {}, variant: "accent" },
+ *     { label: "Cancel", onClick: () => {}, variant: "danger" },
+ *   ]}
+ *   metrics={[
+ *     { type: "date", label: "Expira em", date: "15/01/2025", icon: "fluent:calendar-24-regular" },
+ *     { type: "percentage", label: "Uso", current: 75, max: 100, icon: "fluent:data-usage-24-regular" },
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Compact mode for smaller spaces
+ * <SubscriptionPanel
+ *   planName="Basic Plan"
+ *   price={{ value: "R$ 29,00", interval: "mês" }}
+ *   status={{ status: "active" }}
+ *   compact
+ * />
+ * ```
+ */
+declare const SubscriptionPanel: ({
+  variant,
+  icon,
+  planName,
+  price,
+  status,
+  features,
+  actions,
+  metrics,
+  isLoading
+}: SubscriptionPanelProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+export { PlanCard, type PlanCardButtonProps, type PlanCardMetadata, type PlanCardMetadataSlotParameter, type PlanCardMetadataSlotProps, type PlanCardMetadataSlotService, type PlanCardMetadataSlotVariant, type PlanCardPrice, type PlanCardProps, type PlanCardVariant, PlansPanel, type PlansPanelFilter, type PlansPanelFilterOption, type PlansPanelPlan, type PlansPanelProps, SubscriptionPanel };