@schematichq/schematic-components 2.25.2 → 2.27.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.
@@ -0,0 +1,500 @@
1
+ import { BillingData } from '@schematichq/schematic-react';
2
+ import { BillingDataProvider } from '@schematichq/schematic-react';
3
+ import { BillingDataProviderProps } from '@schematichq/schematic-react';
4
+ import { BillingDataStatus } from '@schematichq/schematic-react';
5
+ import { BillingResourceName } from '@schematichq/schematic-react';
6
+ import { Discount } from '@schematichq/schematic-react';
7
+ import { Invoice } from '@schematichq/schematic-react';
8
+ import { InvoicePage } from '@schematichq/schematic-react';
9
+ import { InvoiceQuery } from '@schematichq/schematic-react';
10
+ import type { InvoiceStatus } from '@schematichq/schematic-react';
11
+ import { JSX } from 'react';
12
+ import { default as React_2 } from 'react';
13
+ import { ResourceHandle } from '@schematichq/schematic-react';
14
+ import { ResourceState } from '@schematichq/schematic-react';
15
+ import { SchematicI18nConfig } from '@schematichq/schematic-react';
16
+ import { SchematicI18nProvider } from '@schematichq/schematic-react';
17
+ import { SchematicI18nProviderProps } from '@schematichq/schematic-react';
18
+ import type { Translate } from '@schematichq/schematic-react';
19
+ import { UpcomingInvoice } from '@schematichq/schematic-react';
20
+ import { useInvalidateBillingData } from '@schematichq/schematic-react';
21
+ import { useInvoices } from '@schematichq/schematic-react';
22
+ import { useSchematicI18n } from '@schematichq/schematic-react';
23
+ import { useSchematicLocale } from '@schematichq/schematic-react';
24
+ import { useSchematicStrings } from '@schematichq/schematic-react';
25
+ import { useSchematicTranslate } from '@schematichq/schematic-react';
26
+ import { useUpcomingInvoice } from '@schematichq/schematic-react';
27
+
28
+ export { BillingData }
29
+
30
+ export { BillingDataProvider }
31
+
32
+ export { BillingDataProviderProps }
33
+
34
+ export { BillingDataStatus }
35
+
36
+ /**
37
+ * The resource names to prefetch for the elements a page renders, each once:
38
+ *
39
+ * ```ts
40
+ * fetchBillingData(client, { names: billingResources(UpcomingBill, Invoices) });
41
+ * ```
42
+ */
43
+ export declare function billingResources(...elements: ReadsBillingResources[]): BillingResourceName[];
44
+
45
+ /** An amount on the bill, with the text for it. */
46
+ export declare interface BillLine {
47
+ /** Minor units, signed as it affects the bill. */
48
+ amountMinor: number;
49
+ amountText: string;
50
+ }
51
+
52
+ /**
53
+ * The English copy, and the fallback for anything a host does not answer.
54
+ * It is a plain resource bundle, so it can be registered as one:
55
+ *
56
+ * ```ts
57
+ * i18n.addResourceBundle("en", "schematic", DEFAULT_STRINGS);
58
+ * ```
59
+ *
60
+ * Registering it is optional: the elements render the English themselves on
61
+ * a miss.
62
+ *
63
+ * Also typed as a catalogue so plural variants can sit beside the bare key
64
+ * they inflect.
65
+ */
66
+ export declare const DEFAULT_STRINGS: ElementStrings & StringCatalog;
67
+
68
+ export declare function deriveInvoiceList(page: InvoicePage, options: DeriveInvoiceListOptions): InvoiceList;
69
+
70
+ export declare interface DeriveInvoiceListOptions {
71
+ locale: string;
72
+ format?: InvoiceFormatters;
73
+ }
74
+
75
+ export declare function deriveUpcomingInvoice(invoice: UpcomingInvoice, options: DeriveUpcomingInvoiceOptions): UpcomingBillSummary;
76
+
77
+ export declare interface DeriveUpcomingInvoiceOptions {
78
+ locale: string;
79
+ format?: UpcomingInvoiceFormatters;
80
+ }
81
+
82
+ export { Discount }
83
+
84
+ /**
85
+ * `deriveUpcomingInvoice`: the company's next bill as display parts — the
86
+ * estimated amount, the balance it consumes, and the discounts shaping it.
87
+ *
88
+ * The arithmetic is not here. The server sends what the balance applies and
89
+ * what survives, because those depend on provider conventions (a negative
90
+ * balance is held credit; a previewed invoice reports no ending balance)
91
+ * that no consumer should have to know.
92
+ */
93
+ /** One discount on the subscription, as the bill shows it. */
94
+ export declare interface DiscountLine {
95
+ /** The coupon's name, for a host that wants to show it. */
96
+ couponName: string;
97
+ /** The promo code, for the chip beside the amount; `null` when none. */
98
+ code: string | null;
99
+ /** Whether the discount takes a percentage off or a fixed amount. */
100
+ kind: "percent" | "amount";
101
+ /** "20%" or "$5.00" — what comes off. */
102
+ valueText: string;
103
+ /** The percentage as written (20 for 20% off); `null` for an amount. */
104
+ percentOff: number | null;
105
+ /** Minor units off; `null` for a percentage. */
106
+ amountOffMinor: number | null;
107
+ /** Months the discount repeats for; `null` when it does not repeat. */
108
+ months: number | null;
109
+ /** Provider vocabulary: `once`, `repeating`, or `forever`. */
110
+ duration: string;
111
+ }
112
+
113
+ /** Props every element accepts on its root. */
114
+ export declare interface ElementProps {
115
+ className?: string;
116
+ /** BCP 47 tag for number, currency, and date formatting. Overrides the
117
+ * provider's `locale`; without either, the viewer's language, else `en-US`. */
118
+ locale?: string;
119
+ /** Overrides the provider's `strings` and its `translate`. */
120
+ strings?: StringOverrides;
121
+ }
122
+
123
+ /**
124
+ * Only the copy the elements render. A host building its own markup owns its
125
+ * own labels and headers; those are not keys here.
126
+ *
127
+ * Plural forms follow i18next's `key_one` / `key_other` convention, looked
128
+ * up by the bare `key` with `{ count }`.
129
+ */
130
+ export declare type ElementStrings = {
131
+ retry: string;
132
+ invoicesLoading: string;
133
+ invoicesHeader: string;
134
+ invoicesError: string;
135
+ invoicesUnavailable: string;
136
+ invoicesEmpty: string;
137
+ invoicesSeeMore: string;
138
+ invoicesSeeLess: string;
139
+ invoicesLoadMore: string;
140
+ invoicesChargeTooltip: string;
141
+ invoicesCreditTooltip: string;
142
+ invoicesUndated: string;
143
+ upcomingBillLoading: string;
144
+ upcomingBillHeader: string;
145
+ upcomingBillError: string;
146
+ upcomingBillUnavailable: string;
147
+ upcomingBillEmpty: string;
148
+ upcomingBillEstimate: string;
149
+ upcomingBillBalanceApplied: string;
150
+ upcomingBillBalanceRemaining: string;
151
+ upcomingBillDiscount: string;
152
+ upcomingBillDiscountValue: string;
153
+ upcomingBillDiscountRepeating: string;
154
+ };
155
+
156
+ /**
157
+ * The singular or plural name of a feature or credit for a count.
158
+ *
159
+ * Configured forms win. Without a `pluralName`, English locales inflect the
160
+ * name with English suffix rules; other languages keep it as given rather
161
+ * than getting "Sitzplatzs". The category comes from `Intl.PluralRules`, so
162
+ * 0 is plural in English and "one" where a language says so.
163
+ */
164
+ export declare function featureName(named: {
165
+ name: string;
166
+ singularName?: string | null;
167
+ pluralName?: string | null;
168
+ }, count?: number, locale?: string): string;
169
+
170
+ /** Credits per use, readable down to 1e-10 rather than "0" or "1e-10". */
171
+ export declare function formatConsumptionRate(rate: number, locale: string): string;
172
+
173
+ /**
174
+ * Formats a minor-unit amount in its currency for the locale. Negative
175
+ * amounts format with the locale's sign; callers wanting accounting
176
+ * parentheses wrap the absolute value themselves.
177
+ */
178
+ export declare function formatCurrency(amountMinor: number, currency: string, locale: string, options?: FormatCurrencyOptions): string;
179
+
180
+ export declare interface FormatCurrencyOptions {
181
+ /**
182
+ * When the amount has sub-minor-unit precision (e.g. a $0.0015 per-unit
183
+ * price), render enough significant digits to show it instead of rounding
184
+ * to the currency's usual precision. Default true.
185
+ */
186
+ preserveSubUnitPrecision?: boolean;
187
+ }
188
+
189
+ /** "August 21, 2026", in the viewer's time zone. Empty for an Invalid Date. */
190
+ export declare function formatDate(date: Date, locale: string, options?: Intl.DateTimeFormatOptions): string;
191
+
192
+ export declare function formatNumber(value: number, locale: string, options?: Intl.NumberFormatOptions): string;
193
+
194
+ /**
195
+ * A malformed timestamp decodes to an Invalid Date, and `Intl` throws a
196
+ * RangeError on formatting one. Thrown inside a render, that takes down the
197
+ * host's tree.
198
+ */
199
+ /**
200
+ * "50%", or "12.5%" for a coupon written with a fraction. Two places is
201
+ * what a provider allows a percentage, and Intl drops trailing zeros, so
202
+ * a whole number stays whole.
203
+ */
204
+ export declare function formatPercent(fraction: number, locale: string): string;
205
+
206
+ /** "8/21". Empty for an Invalid Date. */
207
+ export declare function formatShortDate(date: Date, locale: string): string;
208
+
209
+ /** Heading level an element's own heading renders at. Default 2. */
210
+ export declare type HeadingLevel = 2 | 3 | 4 | 5 | 6;
211
+
212
+ /**
213
+ * The HTTP status behind a failed billing read, or `undefined` for anything
214
+ * that was not an HTTP response (network error, missing provider, malformed
215
+ * response).
216
+ *
217
+ * Checked by shape rather than `instanceof`: a page with two copies of
218
+ * schematic-js has two `SchematicApiError` classes, and the shape matches both.
219
+ */
220
+ export declare function httpStatus(error: Error | undefined): number | undefined;
221
+
222
+ /**
223
+ * Fills `{{name}}` placeholders, i18next style. A placeholder with no value
224
+ * is left as written so the omission is visible.
225
+ */
226
+ export declare function interpolate(template: string, vars?: StringVars): string;
227
+
228
+ export { Invoice }
229
+
230
+ /** `amount` receives the signed value, unlike the default text. */
231
+ export declare interface InvoiceFormatters {
232
+ date?: (date: Date, locale: string) => string;
233
+ amount?: (amountMinor: number, currency: string, locale: string) => string;
234
+ }
235
+
236
+ export declare interface InvoiceList {
237
+ rows: InvoiceRow[];
238
+ /** Total on the server; `rows.length` is only what has been loaded. */
239
+ count: number;
240
+ hasMore: boolean;
241
+ }
242
+
243
+ export { InvoicePage }
244
+
245
+ export { InvoiceQuery }
246
+
247
+ /**
248
+ * The `Text` fields are what the element renders. The raw fields beside them
249
+ * let a host format differently without re-deriving.
250
+ */
251
+ export declare interface InvoiceRow {
252
+ id: string;
253
+ /** Never an Invalid Date, which throws when formatted. */
254
+ date: Date | null;
255
+ dateText: string;
256
+ /** Signed, in the currency's minor units: negative is a credit note. */
257
+ amountMinor: number;
258
+ /** ISO 4217 code, upper-cased. */
259
+ currency: string;
260
+ /** Absolute by default; `isCredit` carries the sign. */
261
+ amountText: string;
262
+ /** Negative invoices are credit notes; render `amountText` in parentheses. */
263
+ isCredit: boolean;
264
+ status: InvoiceStatus | null;
265
+ url: string | null;
266
+ }
267
+
268
+ /**
269
+ * The company's invoice history. Each row links its date to the hosted
270
+ * invoice and shows the amount beside it; rows past `limit` sit behind
271
+ * "See more".
272
+ */
273
+ export declare function Invoices({ className, collapsible, headingLevel, limit, locale: localeProp, query, showAmount, showDate, showHeader, strings, }: InvoicesProps): JSX.Element;
274
+
275
+ export declare namespace Invoices {
276
+ var resources: readonly ["invoices"];
277
+ }
278
+
279
+ export declare interface InvoicesProps extends ElementProps {
280
+ /** Rows shown before "See more". Default 10. */
281
+ limit?: number;
282
+ /** The "Invoices" heading. Default true. */
283
+ showHeader?: boolean;
284
+ /** Heading level, so the card fits the host's outline. Default 2. */
285
+ headingLevel?: HeadingLevel;
286
+ /** The date on each row. Default true. */
287
+ showDate?: boolean;
288
+ /** The amount on each row. Default true. */
289
+ showAmount?: boolean;
290
+ /** Collapse to `limit` rows behind "See more". Default true. */
291
+ collapsible?: boolean;
292
+ /**
293
+ * Server-side filter, e.g. `{ includePending: true }` for invoices not yet
294
+ * due. The hook keys by value, so an inline object is fine.
295
+ */
296
+ query?: InvoiceQuery;
297
+ }
298
+
299
+ /**
300
+ * `locale` is the language the catalogue is written in, since that decides
301
+ * its plural forms: English for the defaults, the resolved locale for a
302
+ * host's overrides. Returns `undefined` on a miss so callers can fall
303
+ * through to the next source.
304
+ */
305
+ export declare function lookup(catalog: StringCatalog | undefined, key: string, vars?: StringVars, locale?: string): string | undefined;
306
+
307
+ /**
308
+ * `other` is required because every language has it. Supply whichever other
309
+ * categories the language uses: Polish needs `one`, `few`, and `many`;
310
+ * Japanese needs none.
311
+ */
312
+ export declare function plural(locale: string, count: number, forms: Partial<Record<Intl.LDMLPluralRule, string>> & {
313
+ other: string;
314
+ }): string;
315
+
316
+ /** The i18next plural suffixes a key can carry. */
317
+ declare type PluralSuffix = "zero" | "one" | "two" | "few" | "many" | "other";
318
+
319
+ /**
320
+ * What an element reads from the billing store, declared on the element so
321
+ * a page can prefetch exactly that. `fetchBillingData` has no default set:
322
+ * each resource is a request on the server, and the set grows with every
323
+ * element, so the page names what it renders.
324
+ */
325
+ export declare interface ReadsBillingResources {
326
+ readonly resources: readonly BillingResourceName[];
327
+ }
328
+
329
+ /**
330
+ * The given tag, or the default when it is absent or `Intl` rejects it.
331
+ * Deliberately ignores `navigator`; `viewerLocale` does that reading.
332
+ */
333
+ export declare function resolveLocale(locale?: string): string;
334
+
335
+ export { ResourceHandle }
336
+
337
+ export { ResourceState }
338
+
339
+ /**
340
+ * Every token the stylesheet can reference, with the value used when the
341
+ * host sets none. Adding a token here is what makes it usable in the CSS;
342
+ * `withTokenDefaults` throws on any other.
343
+ */
344
+ export declare const SCHEMATIC_TOKENS: Record<string, string>;
345
+
346
+ export { SchematicI18nConfig }
347
+
348
+ export { SchematicI18nProvider }
349
+
350
+ export { SchematicI18nProviderProps }
351
+
352
+ /**
353
+ * Injects the default stylesheet. Render once, anywhere in the tree; omit
354
+ * it to style the class names yourself.
355
+ */
356
+ export declare const SchematicStyles: React_2.FC;
357
+
358
+ /**
359
+ * The stylesheet `<SchematicStyles />` injects: the rules above with every
360
+ * token's default inlined as a `var()` fallback.
361
+ */
362
+ export declare const schematicStylesCss: string;
363
+
364
+ /**
365
+ * Opt-in and separate from `<SchematicStyles />`: as a rule it has the
366
+ * cascade problem the fallbacks avoid.
367
+ */
368
+ export declare const schematicTokensCss: string;
369
+
370
+ /** A flat catalogue, the shape of both a host's `strings` and the defaults. */
371
+ export declare type StringCatalog = Record<string, string | undefined>;
372
+
373
+ export declare type StringKey = keyof ElementStrings;
374
+
375
+ /**
376
+ * Copy overrides, on the provider or on an element. Plural spellings are
377
+ * accepted so an override can vary by count rather than answering `1` and
378
+ * `14` with the same words.
379
+ */
380
+ export declare type StringOverrides = Partial<ElementStrings> & Partial<Record<`${StringKey}_${PluralSuffix}`, string>>;
381
+
382
+ /** Interpolation values, and `count` for the plural form. */
383
+ export declare type StringVars = Record<string, unknown>;
384
+
385
+ export { Translate }
386
+
387
+ export declare type Translator = (key: StringKey, vars?: StringVars) => string;
388
+
389
+ /**
390
+ * The company's next bill: what it will be charged and when, and the
391
+ * account balance and discounts that shaped the figure.
392
+ *
393
+ * A company with nothing to bill — no subscription — gets the empty state
394
+ * rather than a fabricated zero. That is a loaded answer from the server (a
395
+ * 204), not a missing one, so it renders as content rather than as a
396
+ * permanent skeleton. A 404 is something else: the account is not enabled
397
+ * for company reads, and the card says so rather than showing a customer
398
+ * with a subscription "no upcoming invoice".
399
+ */
400
+ export declare function UpcomingBill({ className, headingLevel, locale: localeProp, showAmount, showBalance, showDiscounts, showHeader, strings, }: UpcomingBillProps): JSX.Element;
401
+
402
+ export declare namespace UpcomingBill {
403
+ var resources: readonly ["upcomingInvoice"];
404
+ }
405
+
406
+ export declare interface UpcomingBillProps extends ElementProps {
407
+ /** The "Next bill due …" heading. Default true. */
408
+ showHeader?: boolean;
409
+ /** Heading level, so the card fits the host's outline. Default 2. */
410
+ headingLevel?: HeadingLevel;
411
+ /** The estimated amount. Default true. */
412
+ showAmount?: boolean;
413
+ /** The applied and remaining account-balance rows. Default true. */
414
+ showBalance?: boolean;
415
+ /** The discount row. Default true. */
416
+ showDiscounts?: boolean;
417
+ }
418
+
419
+ export declare interface UpcomingBillSummary {
420
+ /** What the company will be charged, after discounts and balance. */
421
+ amountDueMinor: number;
422
+ amountDueText: string;
423
+ /** Before discounts and tax. */
424
+ subtotalMinor: number;
425
+ subtotalText: string;
426
+ /** ISO 4217 code, upper-cased. */
427
+ currency: string;
428
+ /** When it will be charged; `null` when the provider names no date. */
429
+ dueAt: {
430
+ date: Date;
431
+ text: string;
432
+ } | null;
433
+ /**
434
+ * The stored balance this invoice consumes, as a deduction — the amount is
435
+ * negative and its text carries the locale's sign. `null` when none of the
436
+ * balance is applied.
437
+ */
438
+ balanceApplied: BillLine | null;
439
+ /**
440
+ * What is left of the balance afterwards, as a positive amount. `null`
441
+ * when there was no balance to begin with — a company that has one, and
442
+ * spends all of it, still gets a zero here to say so.
443
+ */
444
+ balanceRemaining: BillLine | null;
445
+ /** Active discounts, already filtered server-side to the ones that bite. */
446
+ discounts: DiscountLine[];
447
+ }
448
+
449
+ export { UpcomingInvoice }
450
+
451
+ /**
452
+ * Per-field formatting, for a host that wants the derivation's parts but not
453
+ * its wording. Each receives the raw value and the resolved locale; amounts
454
+ * arrive signed.
455
+ */
456
+ export declare interface UpcomingInvoiceFormatters {
457
+ date?: (date: Date, locale: string) => string;
458
+ amount?: (amountMinor: number, currency: string, locale: string) => string;
459
+ }
460
+
461
+ export { useInvalidateBillingData }
462
+
463
+ export { useInvoices }
464
+
465
+ /**
466
+ * The element's `locale` prop, else the provider's, else the viewer's.
467
+ *
468
+ * The viewer's language is left out of a server render and its hydration,
469
+ * or every formatted date and amount would mismatch. Set `locale` on the
470
+ * provider for a server-rendered page to match on first paint.
471
+ */
472
+ export declare function useResolvedLocale(locale?: string): string;
473
+
474
+ export { useSchematicI18n }
475
+
476
+ export { useSchematicLocale }
477
+
478
+ export { useSchematicStrings }
479
+
480
+ export { useSchematicTranslate }
481
+
482
+ /**
483
+ * Resolves copy in order: the element's `strings`, the provider's `strings`,
484
+ * the provider's `translate`, then the English default.
485
+ *
486
+ * `translate` is called with a sentinel `defaultValue` so a miss is
487
+ * detectable even from an i18next stack that answers every key: `undefined`,
488
+ * the sentinel, or the bare key echoed back all count as misses.
489
+ *
490
+ * `onMissingString` fires during render, so keep it to logging.
491
+ */
492
+ export declare function useTranslator(overrides?: StringOverrides, locale?: string): Translator;
493
+
494
+ export { useUpcomingInvoice }
495
+
496
+ /** Not for a server render or its hydration; `useResolvedLocale` reads it
497
+ * through `useSyncExternalStore`, which keeps it out of both. */
498
+ export declare function viewerLocale(): string | undefined;
499
+
500
+ export { }