Derivations and Formatting

A derivation is a pure function from a hook’s data to a display model: (serverData, options) => ViewModel. The drop-ins render from these, and they are exported from @schematichq/schematic-components/elements so your own JSX renders from the same answers. Numbers, names, and dates arrive formatted for locale, the raw values sit beside them, and none of them assemble sentences. Where a line needs wording, it carries a kind with its formatted parts, so the words and their translation stay in your code.

The derivations

Most rows keep the server’s row on source, so a component that needs a field the model leaves out reads it there instead of abandoning the derivation.

Plan Manager

derivePlanManager lays the company out the way the Plan Manager component does. notice is at most one of four kinds, checked in order: trial with endsIn counted down in days, hours, or minutes; canceled with the plan name and date; customPlanBilling for a custom plan’s pending invoice; and scheduledDowngrade with both plan names. plan.price is { kind: "amount", amount, period }, { kind: "usageBased" } for a free plan with usage-based features, or { kind: "free" } when showZeroPriceAsFree is set. usageBased holds each feature with a price behavior, planCredits sums the plan’s grants of each credit, and topUps, bundles, and promotional group the company’s auto top-up, purchased, and free grants. canChangePlan is false while a custom plan waits for payment to activate.

Included and metered features

deriveIncludedFeatures describes what each entitlement gives. entitlement is one of units, perUnit, perPackage, tierUpTo, tierUnlimited, perUse, or unlimited, each with its amounts and unit names formatted, or null for a feature with no entitlement line, such as a boolean feature. usage is a list of segments (unitPricePerPeriod, used, cost, resets) that the Included Features component joins with a bullet, and usageSummary stands in when that list is empty.

deriveMeteredFeatures keeps the event and trait features and gives each the parts of a usage card. meter has value, total, percent from 0 to 100, valueText, totalText, and a tone of ok, warning, critical, tier, or overage. A pay-as-you-go or credit-burndown feature has no meter. hasUsageByUser marks the event-based rows that useFeatureUserUsage can break down by user.

Credits

deriveCreditUsage gives each credit its remaining amount and unit name, and a ledger of its live grants, newest first. Each ledger row has a kind of plan, bundle, autoTopup, or promotional for any other grant, the granted amount with the credit’s name for it in item, its createdAt date, a date that says when the grant resets or expires, and the server’s grant on source. composition spells out a per-license grant, such as 12 seats at 10 credits each.

Pricing table

Selection state such as the period toggle stays in your component; derivePricingTable takes the selection and returns what the catalog offers. periods lists the periods the catalog prices, months before quarters before years, and currencies the currencies, lowercase. period and currency are the ones you asked for when the catalog offers them, else the subscription’s period and the catalog’s default currency, else the first; period is null when nothing recurs. Pass company from useCompany when signed in, so the current plan is current only in the period it bills in and the table opens on that period.

plans and addOns hold a card each, priced in that period and currency. A card with prices but none in the currency is left out, and a recurring one with none in the period; a one-time add-on is priced once. price is { kind: "amount", amount, period }, { kind: "usageBased" } for a plan priced at zero with a priced feature, or { kind: "free" } with showZeroPriceAsFree. priceId is the price the card shows, for a checkout. credits lists the included credits the catalog shows, one line per credit; a credit granted per license and to the company outright reads as the per-license line with the company’s share in plus. savings holds what the company’s current plan saves by period against paying monthly, as a formatted percentage, and is empty in the public catalog. entitlements gives each feature a text with a kind of name, unlimited, units, perUnit, perUse, or upTo, a detail of overage, tiered, or null, its tiers, and its hardLimit.

action is null in the public catalog. In the company’s view it is one of current; choose with upgrade for a plan above the current one; remove or change for a held add-on; overLimit with the violations; downgradeBlocked with the account’s text and url; or unavailable when the company cannot check out. active marks the company’s plan in the period shown, and trialDaysLeft counts down its trial. customPlan is the catalog’s custom-plan call to action, with priceText, ctaText, and ctaUrl, or null.

Checkout

deriveCheckout turns the catalog, the cart and the checkout the server last priced into what the Checkout dialog shows: the plan and add-on rows with their standing, the quantity, bundle and auto top-up rows, and the summary’s lines and totals from checkout.priceSnapshot. The cart is its own small model: initialCart({ catalog, company, config }) builds it from what the company holds and a CheckoutConfig, cartReducer applies each choice, and checkoutSelections(cart, catalog, company) turns it into the CheckoutSelections that useCheckout().setSelections writes, picking the price ids for the period and currency. planSteps derives the steps the cart has, and stepOfProblem(problem, { cart, catalog }) names the step that can fix a problem, which is how a refused finalize lands the customer in the right place. lines are the cart’s rows at the catalog’s prices, the plan, each quantity bought ahead at its unit price, the add-ons and the bundles, and totals the snapshot’s figures formatted, so a summary can show what makes up the total the server priced. The autoTopups rows name the credit and price one top-up on costText, which the catalog’s own autoTopups do not. Checkout API describes the resource these write to.

Upcoming bill

deriveUpcomingInvoice formats the parts without doing the arithmetic, because the server sends how much balance the invoice consumes and how much survives. balanceApplied comes back negative, as a deduction, and null when none of the balance applies. Each entry in discounts has couponName, code, a kind of percent or amount, valueText such as “20%” or “$5.00”, and months for a discount that repeats, with the raw percentOff, amountOffMinor, and duration beside them.

Invoices

deriveInvoiceList formats each row the way the Invoices component does: the due date, or the created date when there is none, in the locale’s long form such as “March 1, 2026”; the amount as absolute text with isCredit carrying the sign; currency upper-cased; and url reduced to null unless it is an http or https link. date is null rather than an Invalid Date when the timestamp is unusable, and dateText is then empty.

Payment methods

derivePaymentMethods lays the list out the way the Payment Methods component does. current is the default, or null when there is none, and others is every other row, or all of them when there is no default.

expiryWarning is soon when the default card has fewer than four months left, expired once its month has arrived, and none otherwise. Months count by calendar month and ignore the day, so a card expiring in August is two months away anywhere in June. now fixes the moment they are counted from, for a test or a server render.

Each row has id, externalId, kind, label, icon, brand, type, last4, expiresShort, monthsToExpiration, expiry, isDefault, and canRemove. kind is card, bank, wallet, or other. icon names the Schematic icon font glyph: visa, mastercard, amex, or credit for other cards, bank for a US bank account, the wallet’s own mark, and generic-payment otherwise. expiresShort is the card’s “8/27”.

label is either { key }, copy to translate such as paymentMethodsCardEndingIn for “Card ending in”, or { text }, a value the provider supplied such as a bank’s name or the email behind a Link account. That keeps the translatable words in your strings:

const { current, others } = derivePaymentMethods(data, { locale: "en-US" });
const name = (row: PaymentMethodRow) =>
  row.label.key !== undefined ? t(row.label.key) : row.label.text;

Cancellation

deriveUnsubscribe answers what a cancel dialog needs. canUnsubscribe is true while there is a subscription with no cancellation date. accessEndsOn is the cancellation date, else the next bill date, else today. plan, addOns, and total are what cancelling stops charging for, with total the recurring cost per period.

Overriding one field

deriveInvoiceList and deriveUpcomingInvoice take format, which replaces one formatter at a time and receives the raw value. The amount formatter receives the signed amount, unlike deriveInvoiceList’s default text, which is absolute:

deriveInvoiceList(page, {
  locale: "en-US",
  format: {
    date: (date, locale) => date.toLocaleDateString(locale),
    amount: (amountMinor, currency, locale) => myMoney(amountMinor, currency),
  },
});

Formatting helpers

usageLimit and currentTier read a single FeatureUsage row directly, and pricePeriod, tierRanges, isTieredPrice, and unitPrice read its price, for a component that works from the rows rather than a derivation. <Icon name={row.icon} /> draws a feature’s or credit’s icon the way the drop-ins do: the glyph for a schematic-icons name, and anything else, such as an emoji, as text.

Tests travel with them

The drop-ins render from the same derivations, and their test suites check the derivations directly, so a rendering rule that changes is caught before it reaches a page. Pin @schematichq/schematic-components to a minor to take those changes deliberately.