@schematichq/schematic-components 2.30.0 → 2.31.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,13 +5,18 @@ import { BillingDataProviderProps } from '@schematichq/schematic-react';
5
5
  import { BillingDataStatus } from '@schematichq/schematic-react';
6
6
  import { BillingResourceName } from '@schematichq/schematic-react';
7
7
  import { Discount } from '@schematichq/schematic-react';
8
+ import { FEATURE_USER_USAGE_LIMIT } from '@schematichq/schematic-react';
9
+ import { FeatureUsage } from '@schematichq/schematic-react';
10
+ import { FeatureUserUsage } from '@schematichq/schematic-react';
8
11
  import { Invoice } from '@schematichq/schematic-react';
9
12
  import { InvoicePage } from '@schematichq/schematic-react';
10
13
  import { InvoiceQuery } from '@schematichq/schematic-react';
11
14
  import type { InvoiceStatus } from '@schematichq/schematic-react';
12
15
  import { JSX } from 'react';
16
+ import { MeteredPrice } from '@schematichq/schematic-react';
13
17
  import { PaymentMethod } from '@schematichq/schematic-react';
14
18
  import { PaymentMethodsHandle } from '@schematichq/schematic-react';
19
+ import { PerLicenseCreditGrant } from '@schematichq/schematic-react';
15
20
  import { default as React_2 } from 'react';
16
21
  import { ResourceHandle } from '@schematichq/schematic-react';
17
22
  import { ResourceState } from '@schematichq/schematic-react';
@@ -22,9 +27,12 @@ import { SetupIntent } from '@schematichq/schematic-react';
22
27
  import { SetupIntentHandle } from '@schematichq/schematic-react';
23
28
  import type { Translate } from '@schematichq/schematic-react';
24
29
  import { UpcomingInvoice } from '@schematichq/schematic-react';
30
+ import { useFeatureUsage } from '@schematichq/schematic-react';
31
+ import { useFeatureUserUsage } from '@schematichq/schematic-react';
25
32
  import { useInvalidateBillingData } from '@schematichq/schematic-react';
26
33
  import { useInvoices } from '@schematichq/schematic-react';
27
34
  import { usePaymentMethods } from '@schematichq/schematic-react';
35
+ import { UserUsage } from '@schematichq/schematic-react';
28
36
  import { useSchematicI18n } from '@schematichq/schematic-react';
29
37
  import { useSchematicLocale } from '@schematichq/schematic-react';
30
38
  import { useSchematicStrings } from '@schematichq/schematic-react';
@@ -58,6 +66,13 @@ export declare interface BillLine {
58
66
  amountText: string;
59
67
  }
60
68
 
69
+ /**
70
+ * The tier a row's usage sits in. For overage, the tier past the soft limit
71
+ * of a two-tier price, which is how an overage price is built; for tiered
72
+ * pricing, the tier holding the usage. `null` otherwise.
73
+ */
74
+ export declare function currentTier(row: FeatureUsage): TierRange | null;
75
+
61
76
  /**
62
77
  * The English copy, and the fallback for anything a host does not answer.
63
78
  * It is a plain resource bundle, so it can be registered as one:
@@ -86,6 +101,16 @@ export declare interface DerivedPaymentMethods {
86
101
  expiryWarning: PaymentMethodExpiryWarning;
87
102
  }
88
103
 
104
+ export declare function deriveIncludedFeatures(features: FeatureUsage[], options: DeriveIncludedFeaturesOptions): IncludedFeatureRow[];
105
+
106
+ export declare interface DeriveIncludedFeaturesOptions extends UsageLimitOptions {
107
+ locale: string;
108
+ /** Feature ids to show, in this order; every feature when absent. */
109
+ visibleFeatures?: string[];
110
+ /** The "credits per use" line on credit-burning features. Default true. */
111
+ showCredits?: boolean;
112
+ }
113
+
89
114
  export declare function deriveInvoiceList(page: InvoicePage, options: DeriveInvoiceListOptions): InvoiceList;
90
115
 
91
116
  export declare interface DeriveInvoiceListOptions {
@@ -224,8 +249,87 @@ export declare type ElementStrings = {
224
249
  paymentMethodsSaveError: string;
225
250
  paymentMethodsSetDefaultError: string;
226
251
  paymentMethodsRemoveError: string;
252
+ includedFeaturesLoading: string;
253
+ includedFeaturesHeader: string;
254
+ includedFeaturesError: string;
255
+ includedFeaturesUnavailable: string;
256
+ includedFeaturesSeeAll: string;
257
+ includedFeaturesHideAll: string;
258
+ includedFeaturesExpires: string;
259
+ includedFeaturesPerLicense: string;
260
+ usageUnits: string;
261
+ usagePerUnit: string;
262
+ usagePerPackage: string;
263
+ usageTierUpTo: string;
264
+ usageTierUnlimited: string;
265
+ usagePerUse: string;
266
+ usageUnlimited: string;
267
+ usageUnitPricePerPeriod: string;
268
+ usagePackagePricePerPeriod: string;
269
+ usageUsed: string;
270
+ usageResets: string;
271
+ usageLimited: string;
272
+ usageUnlimitedUsed: string;
273
+ usageHardLimitLabel: string;
274
+ usageHardLimit: string;
275
+ usageTieredPricingLabel: string;
276
+ usageTiersVolume: string;
277
+ usageTiersGraduated: string;
278
+ periodMonthShort: string;
279
+ periodQuarterShort: string;
280
+ periodYearShort: string;
227
281
  };
228
282
 
283
+ /**
284
+ * Display parts for each feature the company is entitled to. Numbers, names
285
+ * and dates arrive formatted; the element owns the wording, keyed by `kind`.
286
+ */
287
+ /** What the company gets: an allocation, a price, or a tier. */
288
+ export declare type EntitlementText =
289
+ /** "1,000 API calls" — an allocation, a soft limit, or a paid quantity. */
290
+ {
291
+ kind: "units";
292
+ amount: string;
293
+ units: string;
294
+ }
295
+ /** "$0.01 per API call". */
296
+ | {
297
+ kind: "perUnit";
298
+ cost: string;
299
+ unit: string;
300
+ }
301
+ /** "$1.00 per 100 API calls". */
302
+ | {
303
+ kind: "perPackage";
304
+ cost: string;
305
+ size: number;
306
+ units: string;
307
+ }
308
+ /** "Up to 1,000 API calls in this tier". */
309
+ | {
310
+ kind: "tierUpTo";
311
+ amount: string;
312
+ feature: string;
313
+ }
314
+ /** "Unlimited API calls in this tier". */
315
+ | {
316
+ kind: "tierUnlimited";
317
+ feature: string;
318
+ }
319
+ /** "2 credits per use". */
320
+ | {
321
+ kind: "perUse";
322
+ amount: string;
323
+ units: string;
324
+ }
325
+ /** "Unlimited API calls". */
326
+ | {
327
+ kind: "unlimited";
328
+ item: string;
329
+ };
330
+
331
+ export { FEATURE_USER_USAGE_LIMIT }
332
+
229
333
  /**
230
334
  * The singular or plural name of a feature or credit for a count.
231
335
  *
@@ -240,6 +344,10 @@ export declare function featureName(named: {
240
344
  pluralName?: string | null;
241
345
  }, count?: number, locale?: string): string;
242
346
 
347
+ export { FeatureUsage }
348
+
349
+ export { FeatureUserUsage }
350
+
243
351
  /** Credits per use, readable down to 1e-10 rather than "0" or "1e-10". */
244
352
  export declare function formatConsumptionRate(rate: number, locale: string): string;
245
353
 
@@ -309,6 +417,84 @@ export declare function httpStatus(error: Error | undefined): number | undefined
309
417
  */
310
418
  export declare const iconsCss: string;
311
419
 
420
+ export declare interface IncludedFeatureRow {
421
+ featureId: string;
422
+ name: string;
423
+ description: string | null;
424
+ /** A schematic-icons glyph name; `null` when the feature has none. */
425
+ icon: string | null;
426
+ /** "Includes 10 credits per seat", one per per-license plan grant. */
427
+ perLicenseCredits: PerLicenseCredits[];
428
+ /** When a company override ends; `null` for a plan entitlement. */
429
+ expiresAt: {
430
+ date: Date;
431
+ text: string;
432
+ } | null;
433
+ entitlement: EntitlementText | null;
434
+ usage: UsageSegment[];
435
+ /** Shown when `usage` is empty. */
436
+ usageSummary: UsageSummary | null;
437
+ /**
438
+ * The hard limit, for a numeric entitlement a price behavior bills past;
439
+ * the element shows it only when the host asks.
440
+ */
441
+ hardLimit: {
442
+ amount: number;
443
+ units: string;
444
+ } | null;
445
+ /** The price's tiers, for a tier-priced row or tiered pay-in-advance. */
446
+ tiers: {
447
+ ranges: TierRange[];
448
+ currency: string;
449
+ mode: "graduated" | "volume" | null;
450
+ /** A period key, for flat tier fees billed per period. */
451
+ period: string | null;
452
+ } | null;
453
+ /** The row as the API sent it, for a host that wants more. */
454
+ source: FeatureUsage;
455
+ }
456
+
457
+ /**
458
+ * Every feature the company is entitled to: what it gets, what it has used,
459
+ * and, for a priced feature, what that costs.
460
+ *
461
+ * A company entitled to nothing gets the heading over an empty list. A 404
462
+ * means the account is not enabled for company reads, and the card says so.
463
+ */
464
+ export declare function IncludedFeatures({ className, headingLevel, locale: localeProp, showCredits, showDescription, showEntitlement, showExpiration, showHardLimit, showHeader, showIcon, showUsage, showWarningThresholdAsLimit, strings, visibleFeatures, }: IncludedFeaturesProps): JSX.Element;
465
+
466
+ export declare namespace IncludedFeatures {
467
+ var resources: readonly ["featureUsage"];
468
+ }
469
+
470
+ export declare interface IncludedFeaturesProps extends ElementProps {
471
+ /** The "Included features" heading. Default true. */
472
+ showHeader?: boolean;
473
+ /** Heading level, so the card fits the host's outline. Default 2. */
474
+ headingLevel?: HeadingLevel;
475
+ /** Each feature's icon, where it has one. Default true. */
476
+ showIcon?: boolean;
477
+ /** Each feature's description. Default true. */
478
+ showDescription?: boolean;
479
+ /** When a company override ends. Default true. */
480
+ showExpiration?: boolean;
481
+ /** What the company gets: its allocation, price, or tier. Default true. */
482
+ showEntitlement?: boolean;
483
+ /** What the company has used, its cost, and when it resets. Default true. */
484
+ showUsage?: boolean;
485
+ /** Feature ids to show, in this order; every feature when absent. */
486
+ visibleFeatures?: string[];
487
+ /** The "credits per use" line on credit-burning features. Default true. */
488
+ showCredits?: boolean;
489
+ /** An info tip with the hard limit on features billed past it. Default false. */
490
+ showHardLimit?: boolean;
491
+ /**
492
+ * Show an entitlement's warning threshold in place of its limit, where one
493
+ * is configured. Default false.
494
+ */
495
+ showWarningThresholdAsLimit?: boolean;
496
+ }
497
+
312
498
  /**
313
499
  * Fills `{{name}}` placeholders, i18next style. A placeholder with no value
314
500
  * is left as written so the omission is visible.
@@ -386,6 +572,9 @@ export declare interface InvoicesProps extends ElementProps {
386
572
  query?: InvoiceQuery;
387
573
  }
388
574
 
575
+ /** Tiered when it has more than one tier, or a tiers mode says so. */
576
+ export declare function isTieredPrice(price: MeteredPrice | undefined): boolean;
577
+
389
578
  /**
390
579
  * `locale` is the language the catalogue is written in, since that decides
391
580
  * its plural forms: English for the defaults, the resolved locale for a
@@ -394,6 +583,8 @@ export declare interface InvoicesProps extends ElementProps {
394
583
  */
395
584
  export declare function lookup(catalog: StringCatalog | undefined, key: string, vars?: StringVars, locale?: string): string | undefined;
396
585
 
586
+ export { MeteredPrice }
587
+
397
588
  export { PaymentMethod }
398
589
 
399
590
  /**
@@ -527,6 +718,15 @@ export declare interface PaymentMethodsProps extends ElementProps {
527
718
  checkoutPrefill?: PaymentMethodsCheckoutPrefill;
528
719
  }
529
720
 
721
+ export { PerLicenseCreditGrant }
722
+
723
+ export declare interface PerLicenseCredits {
724
+ /** Credits per license unit, as the API sends it. */
725
+ amount: number;
726
+ creditName: string;
727
+ licenseName: string;
728
+ }
729
+
530
730
  /**
531
731
  * `other` is required because every language has it. Supply whichever other
532
732
  * categories the language uses: Polish needs `one`, `few`, and `many`;
@@ -539,6 +739,20 @@ export declare function plural(locale: string, count: number, forms: Partial<Rec
539
739
  /** The i18next plural suffixes a key can carry. */
540
740
  declare type PluralSuffix = "zero" | "one" | "two" | "few" | "many" | "other";
541
741
 
742
+ /**
743
+ * "month", "quarter" or "year": the period a price is billed per, from its
744
+ * interval and interval count (a quarter is three months). `null` without a
745
+ * price.
746
+ */
747
+ export declare function pricePeriod(price: MeteredPrice | undefined): string | null;
748
+
749
+ /**
750
+ * What IncludedFeatures and MeteredFeatures both read off a usage row: its
751
+ * limit, its current price tier, and its billing period. The server has
752
+ * already picked the price and its cost; this only reads them.
753
+ */
754
+ export declare type PriceTier = MeteredPrice["priceTiers"][number];
755
+
542
756
  /**
543
757
  * What an element reads from the billing store, declared on the element so
544
758
  * a page can prefetch exactly that. `fetchBillingData` has no default set:
@@ -612,10 +826,38 @@ export declare type StringOverrides = Partial<ElementStrings> & Partial<Record<`
612
826
  /** Interpolation values, and `count` for the plural form. */
613
827
  export declare type StringVars = Record<string, unknown>;
614
828
 
829
+ /** A tier as a range of units, with the price for a unit or the flat fee. */
830
+ export declare interface TierRange {
831
+ from: number;
832
+ /** `null` for the last tier, which has no upper bound. */
833
+ to: number | null;
834
+ flatPrice: number | null;
835
+ /** Minor units, fractional where the provider prices below a cent. */
836
+ perUnitPrice: number | null;
837
+ }
838
+
839
+ /** Every tier of the price, the first starting at one unit. */
840
+ export declare function tierRanges(price: MeteredPrice | undefined): TierRange[];
841
+
842
+ /**
843
+ * An info glyph that shows `children` while hovered or focused. The trigger
844
+ * is a button so a keyboard reaches it, and the content describes it so a
845
+ * screen reader reads it on focus.
846
+ */
847
+ export declare const Tooltip: React_2.FC<{
848
+ children: React_2.ReactNode;
849
+ className?: string;
850
+ /** The trigger's accessible name. */
851
+ label: string;
852
+ }>;
853
+
615
854
  export { Translate }
616
855
 
617
856
  export declare type Translator = (key: StringKey, vars?: StringVars) => string;
618
857
 
858
+ /** A unit's price in minor units, the provider's decimal where it has one. */
859
+ export declare function unitPrice(price: MeteredPrice): number;
860
+
619
861
  /**
620
862
  * The company's next bill: what it will be charged and when, and the
621
863
  * account balance and discounts that shaped the figure.
@@ -688,6 +930,66 @@ export declare interface UpcomingInvoiceFormatters {
688
930
  amount?: (amountMinor: number, currency: string, locale: string) => string;
689
931
  }
690
932
 
933
+ /**
934
+ * The number a row's usage is shown against: the allocation for a row with
935
+ * no price behavior or one paid in advance, the soft limit for overage, or
936
+ * the warning threshold when asked for and configured. `null` when none
937
+ * applies.
938
+ */
939
+ export declare function usageLimit(row: FeatureUsage, options?: UsageLimitOptions): number | null;
940
+
941
+ export declare interface UsageLimitOptions {
942
+ /**
943
+ * Show the entitlement's warning threshold in place of its limit where one
944
+ * is configured. In a fair-use setup the limit is the ceiling and the
945
+ * threshold is the advertised number. Default false.
946
+ */
947
+ showWarningThresholdAsLimit?: boolean;
948
+ }
949
+
950
+ /** One piece of the usage line; the element joins them with " • ". */
951
+ export declare type UsageSegment =
952
+ /** "$0.01/API call/mo" — pay in advance, untiered. */
953
+ {
954
+ kind: "unitPricePerPeriod";
955
+ cost: string;
956
+ size: number;
957
+ units: string;
958
+ /** A period key: "month", "quarter" or "year". */
959
+ period: string;
960
+ }
961
+ /** "1300 API calls used"; the amount is left as the API sends it. */
962
+ | {
963
+ kind: "used";
964
+ amount: string;
965
+ units: string;
966
+ }
967
+ /** "$15.00", with "/mo" for a trait feature billed per period. */
968
+ | {
969
+ kind: "cost";
970
+ cost: string;
971
+ period: string | null;
972
+ }
973
+ /** "Resets Oct 1". */
974
+ | {
975
+ kind: "resets";
976
+ date: string;
977
+ };
978
+
979
+ /** When the usage line has no segments: "1,300 of 5,000 used", or "1,300 used". */
980
+ export declare type UsageSummary = {
981
+ kind: "limited";
982
+ amount: string;
983
+ allocation: string;
984
+ } | {
985
+ kind: "unlimited";
986
+ amount: string;
987
+ };
988
+
989
+ export { useFeatureUsage }
990
+
991
+ export { useFeatureUserUsage }
992
+
691
993
  export { useInvalidateBillingData }
692
994
 
693
995
  export { useInvoices }
@@ -703,6 +1005,8 @@ export { usePaymentMethods }
703
1005
  */
704
1006
  export declare function useResolvedLocale(locale?: string): string;
705
1007
 
1008
+ export { UserUsage }
1009
+
706
1010
  export { useSchematicI18n }
707
1011
 
708
1012
  export { useSchematicLocale }