@wildo-ai/presets-components 1.1.5 → 1.1.7

package/dist/esm/config/resources/billing.resource-presets.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { RelatedResourceSections, resourceUIBehavior, resourceUIBehaviorFrom, polymorphicResourceUIBehavior, StandardIconReference, SummaryFlow, SummaryMeta, SummaryTitle, } from '@wildo-ai/saas-frontend-lib';
-import { useFormTemplateContext, useDisplayTemplateContext, DisplayField, DisplayLayout, FormField, FormLayout, ObjectScope, Section, SummaryLayout, } from '@wildo-ai/saas-frontend-lib';
+import { RelatedResourceSections, ResourceHeaderTitle, resourceUIBehavior, resourceUIBehaviorFrom, polymorphicResourceUIBehavior, StandardIconReference, SummaryFlow, SummaryMeta, SummaryTitle, unresolvedLabel, } from '@wildo-ai/saas-frontend-lib';
+import { useDisplayTemplateContext, DisplayField, DisplayLayout, FormField, FormLayout, ObjectScope, Section, SummaryLayout, } from '@wildo-ai/saas-frontend-lib';
 import { BadgeSemanticVariant, BooleanDisplayMode, BooleanEditMode, BooleanLabellingValue, SectionMode, DisplayChromeMode, EditChromeMode, EnumDisplayMode, FormFieldComponent, NumberDisplayMode, StringDisplayMode, } from '@wildo-ai/zod-decorators';
-import { Package, Layers, Puzzle, Gauge, CircleDot, Coins, ShoppingBag, Hash, Layers2, TrendingUp, Package as PackageIcon, Calendar, CalendarDays, Ticket, KeyRound, Gift, Handshake, Percent, Banknote, Clock, UserCheck, CheckCircle2, TimerOff, CircleX, Building2, User, Ban, AlertTriangle, Wallet, Loader, OctagonX, PauseCircle, Sparkles, Square, Repeat, Infinity, FileText, BarChart3, BadgeCheck, PowerOff, ShoppingCart, ExternalLink, Info, CirclePlay, ArrowRightLeft, PackagePlus, PackageMinus, CirclePlus, } from 'lucide-react';
-import { CoreResourceType as R, CoreResourceOperation as Op, Promotion_Operations, BillingAccount_Operations, BillingSubscription_Operations, CreditPool_Operations, productsResourceConfiguration_InitializationFactory as productsFactory, pricesResourceConfiguration_InitializationFactory as pricesFactory, referralsResourceConfiguration_InitializationFactory as referralsFactory, promotionsResourceConfiguration_InitializationFactory as promotionsFactory, billingAccountsPolymorphicFactories, billingSubscriptionsPolymorphicFactories, creditPoolsPolymorphicFactories, invoiceRefsPolymorphicFactories, usageRecordsPolymorphicFactories, ProductSchema, PriceSchema, ReferralSchema, PromotionSchema, BillingAccountBaseSchema, BillingSubscriptionBaseSchema, CreditPoolSchema, InvoiceRefSchema, UsageRecordSchema, ReferralStatus, SubscriptionStatus, InvoiceStatus, BillingScopeType, PromotionDuration, ProductType, PricingModel, BillingInterval, PromotionType, DiscountType, } from '@wildo-ai/saas-models';
+import { Package, Layers, Puzzle, Gauge, CircleDot, Coins, ShoppingBag, Hash, Layers2, TrendingUp, Package as PackageIcon, Calendar, CalendarDays, Ticket, KeyRound, Gift, Handshake, Percent, Banknote, Clock, UserCheck, CheckCircle2, TimerOff, CircleX, Building2, User, Ban, AlertTriangle, Wallet, Loader, OctagonX, PauseCircle, Sparkles, Square, Repeat, Infinity, FileText, BarChart3, BadgeCheck, PowerOff, ShoppingCart, ExternalLink, Info, CirclePlay, CalendarX2, ArrowRightLeft, PackagePlus, PackageMinus, CirclePlus, } from 'lucide-react';
+import { CoreResourceType as R, CoreResourceOperation as Op, Promotion_Operations, BillingAccount_Operations, Referral_Operations, BillingSubscription_Operations, CreditPool_Operations, productsResourceConfiguration_InitializationFactory as productsFactory, pricesResourceConfiguration_InitializationFactory as pricesFactory, referralsResourceConfiguration_InitializationFactory as referralsFactory, promotionsResourceConfiguration_InitializationFactory as promotionsFactory, billingAccountsPolymorphicFactories, billingSubscriptionsPolymorphicFactories, creditPoolsPolymorphicFactories, invoiceRefsPolymorphicFactories, usageRecordsPolymorphicFactories, ProductSchema, PriceSchema, ReferralSchema, PromotionSchema, BillingAccountBaseSchema, BillingSubscriptionBaseSchema, CreditPoolSchema, InvoiceRefSchema, UsageRecordSchema, ReferralStatus, SubscriptionStatus, InvoiceStatus, BillingScopeType, PromotionDuration, ProductType, ProductAvailability, PricingModel, BillingInterval, PromotionType, DiscountType, } from '@wildo-ai/saas-models';
+import { LabellingTypes } from '@wildo-ai/presets-components-models';
 import { notAddressable, apiOnly } from './resource.config.utils.js';
 export function buildBillingMainPresets() {
     /**
@@ -25,38 +26,61 @@ export function buildBillingMainPresets() {
     return {
         [R.PRODUCTS]: resourceUIBehavior(productsFactory, ProductSchema, ({ schema, schemaShape, opsVariantResolver }) => ({
             icon: Package,
-            emptyState: { primaryAction: Op.CREATE },
             layout: {
+                // No `tax` section any more: it was a heading over one field. The tax display mode is a commercial
+                // term of the product, so it sits in `overview` with the other terms.
                 refs: {
-                    sections: ['overview', 'tax', 'purchase', 'behavior', 'visibility'],
+                    sections: ['overview', 'purchase', 'behavior', 'visibility'],
                 },
+                // A catalogue entry is configuration: settings rows on read and edit, bare values on a card.
                 defaultChromeMode: {
-                    display: DisplayChromeMode.STACKED,
-                    summary: DisplayChromeMode.INLINE,
+                    display: DisplayChromeMode.SETTINGS_ROW,
+                    summary: DisplayChromeMode.HIDDEN,
                     edit: EditChromeMode.SETTINGS_ROW,
                 },
-                edit: () => {
-                    const { isExisting, operationType } = useFormTemplateContext();
-                    return (_jsxs(FormLayout, { children: [_jsxs(Section, { name: "overview", appearance: SectionMode.CARD, children: [_jsx(FormField, { name: "key" }), _jsx(FormField, { name: "type" }), _jsx(FormField, { name: "planTier" }), _jsx(FormField, { name: "planTierOrder" }), _jsx(FormField, { name: "requiredPlanTiers" }), _jsx(FormField, { name: "targetScopes" }), _jsx(FormField, { name: "grantedFeatures" }), _jsx(FormField, { name: "grantedLimits" }), _jsx(FormField, { name: "sortOrder" })] }), _jsx(Section, { name: "tax", children: _jsx(FormField, { name: "taxDisplayMode" }) }), _jsx(Section, { name: "purchase", appearance: SectionMode.CARD, children: _jsxs(ObjectScope, { name: "purchaseConfig", children: [_jsx(FormField, { name: "maxQuantityPerPurchase" }), _jsx(FormField, { name: "creditsPerUnit" }), _jsx(FormField, { name: "creditPoolKey" })] }) }), _jsx(Section, { name: "behavior", children: _jsx(FormField, { name: "behaviorPolicy" }) }), _jsxs(Section, { name: "visibility", children: [_jsx(FormField, { name: "isPublic" }), _jsx(FormField, { name: "isActive" }), _jsx(FormField, { name: "metadata" })] })] }));
-                },
+                // The identity line: the product's name (the record's label, its word — #1851), what KIND of product it is, and whether new
+                // checkouts can buy it. None of the three is repeated below.
+                header: () => (_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-field", children: [_jsx(ResourceHeaderTitle, {}), _jsx(DisplayField, { name: "type", hideLabel: true, hideDescription: true, className: "w-auto" }), _jsx(DisplayField, { name: "isActive", hideLabel: true, hideDescription: true, className: "w-auto" })] })),
+                /*
+                 * The form carries what can be CHANGED. `key`, `type`, `grantedFeatures` and `grantedLimits` are
+                 * `isNotEditable` — they are set when the product is materialized from its definition — so on a form
+                 * they were four read-only rows restating the read page. The first editable term takes the focus.
+                 */
+                edit: () => (_jsxs(FormLayout, { children: [_jsxs(Section, { name: "overview", appearance: SectionMode.CARD, children: [_jsx(FormField, { name: "planTier", autoFocus: true }), _jsx(FormField, { name: "planTierOrder" }), _jsx(FormField, { name: "requiredPlanTiers" }), _jsx(FormField, { name: "targetScopes" }), _jsx(FormField, { name: "taxDisplayMode" })] }), _jsx(Section, { name: "purchase", appearance: SectionMode.CARD, children: _jsxs(ObjectScope, { name: "purchaseConfig", children: [_jsx(FormField, { name: "maxQuantityPerPurchase" }), _jsx(FormField, { name: "creditsPerUnit" }), _jsx(FormField, { name: "creditPoolKey" })] }) }), _jsx(Section, { name: "behavior", children: _jsx(FormField, { name: "behaviorPolicy" }) }), _jsxs(Section, { name: "visibility", children: [_jsx(FormField, { name: "isPublic" }), _jsx(FormField, { name: "isActive" }), _jsx(FormField, { name: "sortOrder" }), _jsx(FormField, { name: "metadata" })] })] })),
+                /*
+                 * Read: the header names the product, its type and its availability, so the body starts at the terms.
+                 * No read section carries a description — "Does not set legal tax rates", "Backend enforcement lives in
+                 * services" were notes to an engineer, on a page an operator reads. The purchase and behaviour blocks only
+                 * exist for some product types, so they render only when the product carries them; an add-on used to show
+                 * a "Purchase settings" card of three dashes.
+                 */
                 display: () => {
-                    const { data, isLoading } = useDisplayTemplateContext();
-                    return (_jsxs(DisplayLayout, { children: [_jsxs(Section, { name: "overview", appearance: SectionMode.CARD, children: [_jsx(DisplayField, { name: "key" }), _jsx(DisplayField, { name: "type" }), _jsx(DisplayField, { name: "planTier" }), _jsx(DisplayField, { name: "planTierOrder" }), _jsx(DisplayField, { name: "sortOrder" }), _jsx(DisplayField, { name: "targetScopes" }), _jsx(DisplayField, { name: "grantedFeatures" }), _jsx(DisplayField, { name: "grantedLimits" })] }), _jsx(Section, { name: "tax", children: _jsx(DisplayField, { name: "taxDisplayMode" }) }), _jsx(Section, { name: "purchase", appearance: SectionMode.CARD, children: _jsxs(ObjectScope, { name: "purchaseConfig", children: [_jsx(DisplayField, { name: "maxQuantityPerPurchase" }), _jsx(DisplayField, { name: "creditsPerUnit" }), _jsx(DisplayField, { name: "creditPoolKey" })] }) }), _jsx(Section, { name: "behavior", children: _jsx(DisplayField, { name: "behaviorPolicy" }) }), _jsxs(Section, { name: "visibility", children: [_jsx(DisplayField, { name: "isPublic" }), _jsx(DisplayField, { name: "isActive" }), _jsx(DisplayField, { name: "metadata" })] }), _jsx(RelatedResourceSections, { config: { mode: SectionMode.TABS }, targets: [R.PRICES] })] }));
+                    const { data } = useDisplayTemplateContext();
+                    const purchase = data?.purchaseConfig;
+                    const purchaseHas = (key) => purchase?.[key] !== undefined && purchase?.[key] !== null;
+                    const hasPurchase = purchaseHas('maxQuantityPerPurchase') || purchaseHas('creditsPerUnit') || purchaseHas('creditPoolKey');
+                    const behavior = data?.behaviorPolicy;
+                    const hasBehavior = !!behavior && Object.keys(behavior).length > 0;
+                    return (_jsxs(DisplayLayout, { children: [_jsxs(Section, { name: "overview", appearance: SectionMode.CARD, hideDescription: true, children: [_jsx(DisplayField, { name: "key" }), _jsx(DisplayField, { name: "planTier" }), _jsx(DisplayField, { name: "planTierOrder" }), _jsx(DisplayField, { name: "requiredPlanTiers" }), _jsx(DisplayField, { name: "targetScopes" }), _jsx(DisplayField, { name: "grantedFeatures" }), _jsx(DisplayField, { name: "grantedLimits" }), _jsx(DisplayField, { name: "taxDisplayMode" })] }), hasPurchase && (_jsx(Section, { name: "purchase", appearance: SectionMode.CARD, hideDescription: true, children: _jsxs(ObjectScope, { name: "purchaseConfig", children: [purchaseHas('maxQuantityPerPurchase') && _jsx(DisplayField, { name: "maxQuantityPerPurchase" }), purchaseHas('creditsPerUnit') && _jsx(DisplayField, { name: "creditsPerUnit" }), purchaseHas('creditPoolKey') && _jsx(DisplayField, { name: "creditPoolKey" })] }) })), hasBehavior && (_jsx(Section, { name: "behavior", chromeMode: DisplayChromeMode.HIDDEN, hideDescription: true, children: _jsx(DisplayField, { name: "behaviorPolicy" }) })), _jsxs(Section, { name: "visibility", hideDescription: true, children: [_jsx(DisplayField, { name: "isPublic" }), _jsx(DisplayField, { name: "sortOrder" }), _jsx(DisplayField, { name: "isRecommended" }), _jsx(DisplayField, { name: "priceDisclosure" }), _jsx(DisplayField, { name: "availability" }), _jsx(DisplayField, { name: "metadata" })] }), _jsx(RelatedResourceSections, { config: { mode: SectionMode.TABS }, targets: [R.PRICES] })] }));
                 },
+                /*
+                 * A catalogue card: the product's name, its key, the type badge, the tier. The title is the host-resolved name
+                 * (the application's word for the product, #1851) — `name="key"` rendered the raw key where the word
+                 * belonged. The key stays on the card as a meta value because an operator also identifies a product by it.
+                 * Availability shows only when it is the EXCEPTION — nearly every product is active and public, and a
+                 * checkmark on every card was a column of noise that hid the one product that is not. The record id is gone.
+                 */
                 summary: () => {
-                    const { data, isLoading } = useDisplayTemplateContext();
-                    return (_jsxs(SummaryLayout, { children: [_jsx(SummaryTitle, { name: "key" }), _jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "type" }), _jsx(DisplayField, { name: "planTier" }), _jsx(DisplayField, { name: "isPublic" }), _jsx(DisplayField, { name: "isActive" })] }), _jsx(DisplayField, { name: "_id", hideLabel: true, className: "text-muted-foreground text-xs font-mono truncate max-w-full" })] }));
+                    const { data } = useDisplayTemplateContext();
+                    const product = data;
+                    return (_jsxs(SummaryLayout, { children: [_jsx(SummaryTitle, {}), _jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "key" }), _jsx(DisplayField, { name: "type" }), _jsx(DisplayField, { name: "planTier" }), product?.isActive === false && _jsx(DisplayField, { name: "isActive" }), product?.isPublic === false && _jsx(DisplayField, { name: "isPublic" }), product?.availability === ProductAvailability.UPCOMING && _jsx(DisplayField, { name: "availability" }), product?.isRecommended === true && _jsx(DisplayField, { name: "isRecommended" })] })] }));
                 },
             },
             fields: {
                 _id: schemaShape._id.isHidden(),
-                key: schemaShape.key.stringUI({
-                    display: { displayMode: StringDisplayMode.COPY, showDescription: true },
-                    edit: { showDescription: true },
-                }),
+                key: schemaShape.key.stringUI({ display: { displayMode: StringDisplayMode.COPY } }),
                 type: schemaShape.type.enumUI({
-                    display: { displayMode: EnumDisplayMode.BADGE, showDescription: true },
-                    edit: { showDescription: true },
+                    display: { displayMode: EnumDisplayMode.BADGE },
                     values: {
                         [ProductType.PLAN]: { color: BadgeSemanticVariant.INFO, icon: Layers },
                         [ProductType.ADDON]: { color: BadgeSemanticVariant.SECONDARY, icon: Puzzle },
@@ -66,57 +90,94 @@ export function buildBillingMainPresets() {
                         [ProductType.ITEM]: { color: BadgeSemanticVariant.DEFAULT, icon: ShoppingBag },
                     },
                 }),
+                // Keeps its description on the FORM only: what a tier is for (plan comparison) is not obvious from the
+                // word. On a card the bare tier ("premium") beside the type badge read as a second product name, so the
+                // card keeps its label.
                 planTier: schemaShape.planTier.stringUI({
-                    display: { displayMode: StringDisplayMode.TRUNCATE, truncateLength: 48, showDescription: true },
-                    edit: { showDescription: true },
-                }),
-                sortOrder: schemaShape.sortOrder.numberUI({
-                    display: { displayMode: NumberDisplayMode.FORMATTED, showDescription: true },
+                    display: { displayMode: StringDisplayMode.TRUNCATE, truncateLength: 48, hideWhenEmpty: true },
+                    summaryOverride: { chromeMode: DisplayChromeMode.INLINE },
                     edit: { showDescription: true },
                 }),
+                planTierOrder: schemaShape.planTierOrder.numberUI({ display: { hideWhenEmpty: true } }),
+                requiredPlanTiers: schemaShape.requiredPlanTiers.arrayUI({ display: { hideWhenEmpty: true } }),
+                grantedFeatures: schemaShape.grantedFeatures.arrayUI({ display: { hideWhenEmpty: true } }),
+                grantedLimits: schemaShape.grantedLimits.objectUI({ display: { hideWhenEmpty: true } }),
+                sortOrder: schemaShape.sortOrder.numberUI({ display: { displayMode: NumberDisplayMode.FORMATTED } }),
+                // Read as a word ("Active" / "Inactive") because it stands alone in the header and, when inactive, on a
+                // card: a bare checkmark there says nothing about what is checked. The form keeps its description — what
+                // "active" governs (new checkouts only) is not obvious.
                 isActive: schemaShape.isActive.booleanUI({
                     labellingValue: BooleanLabellingValue.ACTIVE_INACTIVE,
-                    display: { displayMode: BooleanDisplayMode.CHECKMARK, showDescription: true },
+                    display: { displayMode: BooleanDisplayMode.RAW },
                     edit: { editMode: BooleanEditMode.SWITCH, showDescription: true },
                 }),
+                // A bare "No" on a card would not say what is not; the card keeps the label. The form keeps the description
+                // (public = listed in self-serve catalogues).
                 isPublic: schemaShape.isPublic.booleanUI({
                     labellingValue: BooleanLabellingValue.YES_NO,
-                    display: { displayMode: BooleanDisplayMode.CHECKMARK, showDescription: true },
+                    display: { displayMode: BooleanDisplayMode.CHECKMARK },
+                    summaryOverride: { chromeMode: DisplayChromeMode.INLINE },
                     edit: { editMode: BooleanEditMode.SWITCH, showDescription: true },
                 }),
-                taxDisplayMode: schemaShape.taxDisplayMode.enumUI({ display: { tooltip: true }, edit: { tooltip: true } }),
+                // On a card only when true (see the summary above), and for the same reason as `isPublic` the card keeps the
+                // label: a bare checkmark beside the tier would not say WHAT is checked. Set by the catalogue sync, so there is
+                // no edit configuration.
+                isRecommended: schemaShape.isRecommended.booleanUI({
+                    labellingValue: BooleanLabellingValue.YES_NO,
+                    display: { displayMode: BooleanDisplayMode.CHECKMARK },
+                    summaryOverride: { chromeMode: DisplayChromeMode.INLINE },
+                }),
+                taxDisplayMode: schemaShape.taxDisplayMode.enumUI({ display: { hideWhenEmpty: true }, edit: { tooltip: true } }),
+                metadata: schemaShape.metadata.objectUI({ display: { hideWhenEmpty: true } }),
+            },
+            /*
+             * A product is named by the application's word for it (`billing_products.<key>.name`), never by its key (#1851).
+             * The key stays on the page as a copyable row. A product with no authored word answers its key, which LOOKS
+             * missing and gets authored. The section is declared so the registry loads it for every surface that names a
+             * product — a list row, the header, a subscription line's product reference, the breadcrumb of a price.
+             */
+            getFrontendResourceLabel: ({ currentObject, t }) => {
+                const nameKey = `${LabellingTypes.BILLING_PRODUCTS}.${currentObject.key}.name`;
+                const name = t(nameKey);
+                return name === nameKey ? unresolvedLabel(currentObject.key) : name;
             },
-            getFrontendResourceLabel: ({ currentObject }) => currentObject.key,
+            instanceLabelSections: [LabellingTypes.BILLING_PRODUCTS],
             views: [],
         })),
         [R.PRICES]: resourceUIBehavior(pricesFactory, PriceSchema, ({ schema, schemaShape, opsVariantResolver }) => ({
             icon: StandardIconReference.RECEIPT,
-            emptyState: { primaryAction: Op.CREATE },
             layout: {
                 refs: { sections: ['pricing', 'tiers', 'tax', 'availability'] },
                 defaultChromeMode: {
-                    display: DisplayChromeMode.STACKED,
-                    summary: DisplayChromeMode.INLINE,
+                    display: DisplayChromeMode.SETTINGS_ROW,
+                    summary: DisplayChromeMode.HIDDEN,
                     edit: EditChromeMode.SETTINGS_ROW,
                 },
-                edit: () => {
-                    const { isExisting, operationType } = useFormTemplateContext();
-                    return (_jsxs(FormLayout, { children: [_jsxs(Section, { name: "pricing", appearance: SectionMode.CARD, children: [_jsx(FormField, { name: "productId" }), _jsx(FormField, { name: "model" }), _jsx(FormField, { name: "unitPrice" }), _jsx(FormField, { name: "interval" }), _jsx(FormField, { name: "intervalCount" })] }), _jsxs(Section, { name: "tiers", children: [_jsx(FormField, { name: "tiers" }), _jsx(FormField, { name: "packageSize" }), _jsx(FormField, { name: "usageAggregation" })] }), _jsx(Section, { name: "tax", children: _jsx(FormField, { name: "taxBehavior" }) }), _jsxs(Section, { name: "availability", chromeMode: EditChromeMode.INLINE, children: [_jsx(FormField, { name: "isDefault" }), _jsx(FormField, { name: "isActive" })] })] }));
-                },
+                // The name of a price is its model and cadence (see `getFrontendResourceLabel`); the header adds whether it
+                // is the product's default and whether it is still sold, so neither is a body row.
+                header: () => (_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-field", children: [_jsx(ResourceHeaderTitle, {}), _jsx(DisplayField, { name: "isActive", hideLabel: true, hideDescription: true, className: "w-auto" })] })),
+                edit: () => (_jsxs(FormLayout, { children: [_jsxs(Section, { name: "pricing", appearance: SectionMode.CARD, children: [_jsx(FormField, { name: "productId" }), _jsx(FormField, { name: "model", autoFocus: true }), _jsx(FormField, { name: "unitPrice" }), _jsx(FormField, { name: "interval" }), _jsx(FormField, { name: "intervalCount" })] }), _jsxs(Section, { name: "tiers", children: [_jsx(FormField, { name: "tiers" }), _jsx(FormField, { name: "packageSize" }), _jsx(FormField, { name: "usageAggregation" })] }), _jsx(Section, { name: "tax", children: _jsx(FormField, { name: "taxBehavior" }) }), _jsxs(Section, { name: "availability", chromeMode: EditChromeMode.INLINE, children: [_jsx(FormField, { name: "isDefault" }), _jsx(FormField, { name: "isActive" })] })] })),
+                /*
+                 * Read: the amount first, then cadence. The product is not repeated — a price is read inside its product's
+                 * page — and the model is the header. Tiers and tax only exist for some prices, so those rows hide when
+                 * empty and their sections render only when they hold something; a flat monthly price used to show two
+                 * headed blocks of dashes. No read section carries a description.
+                 */
                 display: () => {
-                    const { data, isLoading } = useDisplayTemplateContext();
-                    return (_jsxs(DisplayLayout, { children: [_jsxs(Section, { name: "pricing", appearance: SectionMode.CARD, children: [_jsx(DisplayField, { name: "productId" }), _jsx(DisplayField, { name: "model" }), _jsx(DisplayField, { name: "unitPrice" }), _jsx(DisplayField, { name: "interval" }), _jsx(DisplayField, { name: "intervalCount" })] }), _jsxs(Section, { name: "tiers", children: [_jsx(DisplayField, { name: "tiers" }), _jsx(DisplayField, { name: "packageSize" }), _jsx(DisplayField, { name: "usageAggregation" })] }), _jsx(Section, { name: "tax", children: _jsx(DisplayField, { name: "taxBehavior" }) }), _jsxs(Section, { name: "availability", children: [_jsx(DisplayField, { name: "isDefault" }), _jsx(DisplayField, { name: "isActive" })] })] }));
-                },
-                summary: () => {
-                    const { data, isLoading } = useDisplayTemplateContext();
-                    return (_jsxs(SummaryLayout, { children: [_jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "model" }), _jsx(DisplayField, { name: "unitPrice" }), _jsx(DisplayField, { name: "interval" })] }), _jsx(DisplayField, { name: "_id", hideLabel: true, className: "text-muted-foreground text-xs font-mono truncate max-w-full" })] }));
+                    const { data } = useDisplayTemplateContext();
+                    const price = data;
+                    const hasTiers = (price?.tiers?.length ?? 0) > 0 || price?.packageSize != null || price?.usageAggregation != null;
+                    return (_jsxs(DisplayLayout, { children: [_jsxs(Section, { name: "pricing", appearance: SectionMode.CARD, hideTitle: true, hideDescription: true, children: [_jsx(DisplayField, { name: "unitPrice" }), _jsx(DisplayField, { name: "interval" }), _jsx(DisplayField, { name: "intervalCount" }), _jsx(DisplayField, { name: "isDefault" })] }), hasTiers && (_jsxs(Section, { name: "tiers", hideDescription: true, children: [_jsx(DisplayField, { name: "tiers" }), _jsx(DisplayField, { name: "packageSize" }), _jsx(DisplayField, { name: "usageAggregation" })] })), price?.taxBehavior != null && (_jsx(Section, { name: "tax", hideDescription: true, children: _jsx(DisplayField, { name: "taxBehavior" }) }))] }));
                 },
+                // A card inside the product's Prices tab: the amount, the cadence, the model — bare, each speaks for itself.
+                // The record id is gone.
+                summary: () => (_jsx(SummaryLayout, { children: _jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "unitPrice" }), _jsx(DisplayField, { name: "interval" }), _jsx(DisplayField, { name: "model" })] }) })),
             },
             fields: {
                 _id: schemaShape._id.isHidden(),
                 model: schemaShape.model.enumUI({
                     defaultColor: BadgeSemanticVariant.SECONDARY,
-                    display: { displayMode: EnumDisplayMode.BADGE, showDescription: true },
+                    display: { displayMode: EnumDisplayMode.BADGE },
                     edit: { showDescription: true },
                     values: {
                         [PricingModel.FLAT]: { color: BadgeSemanticVariant.SECONDARY, icon: Square },
@@ -126,48 +187,77 @@ export function buildBillingMainPresets() {
                         [PricingModel.PACKAGE]: { color: BadgeSemanticVariant.OUTLINE, icon: PackageIcon },
                     },
                 }),
+                // Absent on a one-time price, which is exactly what its absence means; the header and the card say it by
+                // not showing a cadence.
                 interval: schemaShape.interval.enumUI({
-                    display: { displayMode: EnumDisplayMode.BADGE, showDescription: true },
-                    edit: { showDescription: true },
+                    display: { displayMode: EnumDisplayMode.BADGE, hideWhenEmpty: true },
                     values: {
                         [BillingInterval.MONTH]: { color: BadgeSemanticVariant.SECONDARY, icon: Calendar },
                         [BillingInterval.YEAR]: { color: BadgeSemanticVariant.INFO, icon: CalendarDays },
                     },
                 }),
                 intervalCount: schemaShape.intervalCount.numberUI({
-                    display: { displayMode: NumberDisplayMode.FORMATTED, showDescription: true },
+                    display: { displayMode: NumberDisplayMode.FORMATTED, hideWhenEmpty: true },
                     edit: { showDescription: true },
                 }),
-                packageSize: schemaShape.packageSize.numberUI({ display: { tooltip: true }, edit: { tooltip: true } }),
-                usageAggregation: schemaShape.usageAggregation.enumUI({ display: { tooltip: true }, edit: { tooltip: true } }),
-                taxBehavior: schemaShape.taxBehavior.enumUI({ display: { tooltip: true }, edit: { tooltip: true } }),
+                tiers: schemaShape.tiers.arrayUI({ display: { hideWhenEmpty: true } }),
+                packageSize: schemaShape.packageSize.numberUI({ display: { hideWhenEmpty: true }, edit: { tooltip: true } }),
+                usageAggregation: schemaShape.usageAggregation.enumUI({ display: { hideWhenEmpty: true }, edit: { tooltip: true } }),
+                taxBehavior: schemaShape.taxBehavior.enumUI({ display: { hideWhenEmpty: true }, edit: { tooltip: true } }),
+                // A default price is the exception worth reading; "not the default" is not information.
                 isDefault: schemaShape.isDefault.booleanUI({
                     labellingValue: BooleanLabellingValue.YES_NO,
-                    display: { displayMode: BooleanDisplayMode.CHECKMARK, showDescription: true },
+                    display: { displayMode: BooleanDisplayMode.CHECKMARK },
                     edit: { editMode: BooleanEditMode.SWITCH, showDescription: true },
                 }),
+                // A word in the header, for the same reason as a product's.
                 isActive: schemaShape.isActive.booleanUI({
                     labellingValue: BooleanLabellingValue.ACTIVE_INACTIVE,
-                    display: { displayMode: BooleanDisplayMode.CHECKMARK, showDescription: true },
+                    display: { displayMode: BooleanDisplayMode.RAW },
                     edit: { editMode: BooleanEditMode.SWITCH, showDescription: true },
                 }),
             },
-            getFrontendResourceLabel: ({ currentObject }) => `${currentObject.model} — ${currentObject.interval ?? 'one-time'}`,
+            /*
+             * A price's name is its model and, when it recurs, its cadence — both in the application's own words. It used
+             * to join the raw wire values with an English "one-time", which no translator could reach
+             * (`display-text-comes-from-i18n.md`). A missing word answers the raw value, which LOOKS missing and gets
+             * authored. A one-time price is named by its model alone.
+             */
+            getFrontendResourceLabel: ({ currentObject, t }) => {
+                const word = (key, raw) => {
+                    const resolved = t(key);
+                    return resolved === key ? raw : resolved;
+                };
+                const model = word(`${LabellingTypes.SYSTEM_ENUMS}.PricingModel.${currentObject.model}`, String(currentObject.model));
+                if (!currentObject.interval)
+                    return model;
+                const interval = word(`${LabellingTypes.RESOURCES}.${R.PRICES}.fields.interval.enum.${currentObject.interval}`, String(currentObject.interval));
+                return `${model} · ${interval}`;
+            },
             views: [],
         })),
         [R.REFERRALS]: resourceUIBehavior(referralsFactory, ReferralSchema, ({ schema, schemaShape, opsVariantResolver }) => ({
             icon: StandardIconReference.SHARE,
-            emptyState: { primaryAction: Op.CREATE },
             layout: {
+                // No sections: a referral is one code, its state, the two sides and what each earned. It is an immutable
+                // ledger row (no edit form), read in a list.
                 defaultChromeMode: {
-                    display: DisplayChromeMode.STACKED,
-                    summary: DisplayChromeMode.INLINE,
+                    display: DisplayChromeMode.SETTINGS_ROW,
+                    summary: DisplayChromeMode.HIDDEN,
                     edit: EditChromeMode.SETTINGS_ROW,
                 },
-                summary: () => {
-                    const { data, isLoading } = useDisplayTemplateContext();
-                    return (_jsxs(SummaryLayout, { children: [_jsx(SummaryTitle, { name: "referralCode" }), _jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "status" }), _jsx(DisplayField, { name: "referrerScopeType" }), _jsx(DisplayField, { name: "referredScopeType" })] }), _jsxs(SummaryMeta, { className: "text-muted-foreground text-xs", children: [_jsx(DisplayField, { name: "expiresAt" }), _jsx(DisplayField, { name: "convertedAt" })] }), _jsx(DisplayField, { name: "referrerBillingAccountId", hideLabel: true, className: "text-xs font-mono truncate max-w-full" })] }));
-                },
+                // The code is the record's name and the status its state; neither is repeated in the body.
+                header: () => (_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-field", children: [_jsx(ResourceHeaderTitle, {}), _jsx(DisplayField, { name: "status", hideLabel: true, hideDescription: true, className: "w-auto" })] })),
+                // The two sides, when each moved, and what each earned. Every optional row hides when empty — a referral
+                // that has not been accepted yet has no referred side, and a column of dashes said nothing.
+                display: () => (_jsxs(DisplayLayout, { children: [_jsx(DisplayField, { name: "referrerScopeType" }), _jsx(DisplayField, { name: "referredScopeType" }), _jsx(DisplayField, { name: "expiresAt" }), _jsx(DisplayField, { name: "acceptedAt" }), _jsx(DisplayField, { name: "convertedAt" }), _jsx(DisplayField, { name: "referrerReward" }), _jsx(DisplayField, { name: "referrerRewardApplied" }), _jsx(DisplayField, { name: "referredReward" }), _jsx(DisplayField, { name: "referredRewardApplied" })] })),
+                /*
+                 * A card: the code and its status badge. The two scope badges and the two dates keep their labels — a bare
+                 * "Organization" beside a bare "User" does not say which side referred, and a bare date does not say what
+                 * happened on it. The referrer's billing-account id is gone: in an organization's own referrals it is that
+                 * organization, and an opaque id told the reader nothing.
+                 */
+                summary: () => (_jsxs(SummaryLayout, { children: [_jsx(SummaryTitle, { name: "referralCode" }), _jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "status" }), _jsx(DisplayField, { name: "referrerScopeType" }), _jsx(DisplayField, { name: "referredScopeType" })] }), _jsxs(SummaryMeta, { className: "text-muted-foreground text-xs", children: [_jsx(DisplayField, { name: "expiresAt" }), _jsx(DisplayField, { name: "convertedAt" })] })] })),
             },
             fields: {
                 _id: schemaShape._id.isHidden(),
@@ -184,18 +274,25 @@ export function buildBillingMainPresets() {
                 referralCode: schemaShape.referralCode.stringUI({ display: { displayMode: StringDisplayMode.COPY } }),
                 referrerScopeType: schemaShape.referrerScopeType.enumUI({
                     display: { displayMode: EnumDisplayMode.BADGE },
+                    summaryOverride: { chromeMode: DisplayChromeMode.INLINE },
                     values: {
                         [BillingScopeType.ORGANIZATIONS]: { color: BadgeSemanticVariant.SECONDARY, icon: Building2 },
                         [BillingScopeType.USER_SELF]: { color: BadgeSemanticVariant.OUTLINE, icon: User },
                     },
                 }),
                 referredScopeType: schemaShape.referredScopeType.enumUI({
-                    display: { displayMode: EnumDisplayMode.BADGE },
+                    display: { displayMode: EnumDisplayMode.BADGE, hideWhenEmpty: true },
+                    summaryOverride: { chromeMode: DisplayChromeMode.INLINE },
                     values: {
                         [BillingScopeType.ORGANIZATIONS]: { color: BadgeSemanticVariant.SECONDARY, icon: Building2 },
                         [BillingScopeType.USER_SELF]: { color: BadgeSemanticVariant.OUTLINE, icon: User },
                     },
                 }),
+                expiresAt: schemaShape.expiresAt.dateUI({ display: { hideWhenEmpty: true }, summaryOverride: { chromeMode: DisplayChromeMode.INLINE } }),
+                acceptedAt: schemaShape.acceptedAt.dateUI({ display: { hideWhenEmpty: true } }),
+                convertedAt: schemaShape.convertedAt.dateUI({ display: { hideWhenEmpty: true }, summaryOverride: { chromeMode: DisplayChromeMode.INLINE } }),
+                referrerReward: schemaShape.referrerReward.objectUI({ display: { hideWhenEmpty: true } }),
+                referredReward: schemaShape.referredReward.objectUI({ display: { hideWhenEmpty: true } }),
                 referrerRewardApplied: schemaShape.referrerRewardApplied.booleanUI({
                     labellingValue: BooleanLabellingValue.YES_NO,
                     display: { displayMode: BooleanDisplayMode.CHECKMARK },
@@ -206,45 +303,58 @@ export function buildBillingMainPresets() {
                 }),
             },
             getFrontendResourceLabel: ({ currentObject }) => currentObject.referralCode,
-            views: [],
+            // #1802: the organization owner issues a code from the list, and withdraws one that has not converted.
+            views: [
+                [Referral_Operations.ISSUE, notAddressable({ iconOverride: CirclePlus })],
+                [Referral_Operations.CANCEL, notAddressable({ iconOverride: CircleX })],
+            ],
         })),
         [R.PROMOTIONS]: resourceUIBehavior(promotionsFactory, PromotionSchema, ({ schema, schemaShape, opsVariantResolver }) => ({
             icon: StandardIconReference.PROMOTION,
-            emptyState: { primaryAction: Op.CREATE },
             layout: {
                 refs: { sections: ['overview', 'discount', 'duration', 'applicability', 'validity'] },
+                // An operator AUTHORS a promotion (a name, a description), so the form stacks; the read page is rows.
                 defaultChromeMode: {
-                    display: DisplayChromeMode.STACKED,
-                    summary: DisplayChromeMode.INLINE,
-                    edit: EditChromeMode.SETTINGS_ROW,
-                },
-                edit: () => (_jsxs(FormLayout, { children: [_jsxs(Section, { name: "overview", appearance: SectionMode.CARD, children: [_jsx(FormField, { name: "name" }), _jsx(FormField, { name: "description" }), _jsx(FormField, { name: "type" }), _jsx(FormField, { name: "code" })] }), _jsxs(Section, { name: "discount", children: [_jsx(FormField, { name: "discountType" }), _jsx(FormField, { name: "discountPercentage" }), _jsx(FormField, { name: "discountFixedAmount" })] }), _jsxs(Section, { name: "duration", children: [_jsx(FormField, { name: "duration" }), _jsx(FormField, { name: "durationInMonths" })] }), _jsxs(Section, { name: "applicability", children: [_jsx(FormField, { name: "applicableProducts" }), _jsx(FormField, { name: "maxRedemptions" }), _jsx(FormField, { name: "timesRedeemed" })] }), _jsxs(Section, { name: "validity", children: [_jsx(FormField, { name: "validFrom" }), _jsx(FormField, { name: "validUntil" }), _jsx(FormField, { name: "isActive" }), _jsx(FormField, { name: "metadata" })] })] })),
-                display: () => {
-                    const { data, isLoading } = useDisplayTemplateContext();
-                    return (_jsxs(DisplayLayout, { children: [_jsxs(Section, { name: "overview", appearance: SectionMode.CARD, children: [_jsx(DisplayField, { name: "name" }), _jsx(DisplayField, { name: "description" }), _jsx(DisplayField, { name: "type" }), _jsx(DisplayField, { name: "code" })] }), _jsxs(Section, { name: "discount", children: [_jsx(DisplayField, { name: "discountType" }), _jsx(DisplayField, { name: "discountPercentage" }), _jsx(DisplayField, { name: "discountFixedAmount" })] }), _jsxs(Section, { name: "duration", children: [_jsx(DisplayField, { name: "duration" }), _jsx(DisplayField, { name: "durationInMonths" })] }), _jsxs(Section, { name: "applicability", children: [_jsx(DisplayField, { name: "applicableProducts" }), _jsx(DisplayField, { name: "maxRedemptions" }), _jsx(DisplayField, { name: "timesRedeemed" })] }), _jsxs(Section, { name: "validity", children: [_jsx(DisplayField, { name: "validFrom" }), _jsx(DisplayField, { name: "validUntil" }), _jsx(DisplayField, { name: "isActive" }), _jsx(DisplayField, { name: "metadata" })] })] }));
-                },
-                summary: () => {
-                    const { data, isLoading } = useDisplayTemplateContext();
-                    return (_jsxs(SummaryLayout, { children: [_jsx(SummaryTitle, { name: "name" }), _jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "type" }), _jsx(DisplayField, { name: "discountType" })] }), _jsx(DisplayField, { name: "_id", hideLabel: true, className: "text-muted-foreground text-xs font-mono truncate max-w-full" })] }));
+                    display: DisplayChromeMode.SETTINGS_ROW,
+                    summary: DisplayChromeMode.HIDDEN,
+                    edit: EditChromeMode.STACKED,
                 },
+                // The name, the kind of promotion and whether it still accepts redemptions — the three things the body no
+                // longer repeats.
+                header: () => (_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-field", children: [_jsx(ResourceHeaderTitle, {}), _jsx(DisplayField, { name: "type", hideLabel: true, hideDescription: true, className: "w-auto" }), _jsx(DisplayField, { name: "isActive", hideLabel: true, hideDescription: true, className: "w-auto" })] })),
+                /*
+                 * The name first, focused; the description is prose, so a textarea. `timesRedeemed` is a counter the
+                 * system advances (`isNotEditable`), so it is read on the record, not shown as a disabled input here. The
+                 * discount and duration blocks keep their descriptions: which of the two amounts applies, and what
+                 * "repeating" needs, are not obvious from the fields.
+                 */
+                edit: () => (_jsxs(FormLayout, { children: [_jsxs(Section, { name: "overview", appearance: SectionMode.CARD, children: [_jsx(FormField, { name: "name", autoFocus: true }), _jsx(FormField, { name: "description" }), _jsx(FormField, { name: "type" }), _jsx(FormField, { name: "code" })] }), _jsxs(Section, { name: "discount", children: [_jsx(FormField, { name: "discountType" }), _jsx(FormField, { name: "discountPercentage" }), _jsx(FormField, { name: "discountFixedAmount" })] }), _jsxs(Section, { name: "duration", children: [_jsx(FormField, { name: "duration" }), _jsx(FormField, { name: "durationInMonths" })] }), _jsxs(Section, { name: "applicability", children: [_jsx(FormField, { name: "applicableProducts" }), _jsx(FormField, { name: "maxRedemptions" })] }), _jsxs(Section, { name: "validity", children: [_jsx(FormField, { name: "validFrom" }), _jsx(FormField, { name: "validUntil" }), _jsx(FormField, { name: "isActive" }), _jsx(FormField, { name: "metadata" })] })] })),
+                /*
+                 * Read: the header is the name, type and state. The first card is the promotion's own words and its code,
+                 * with no heading — "Overview" over a description said nothing the description does not. No read section
+                 * carries a description; those were notes about provider sync and API behaviour.
+                 */
+                display: () => (_jsxs(DisplayLayout, { children: [_jsxs(Section, { name: "overview", appearance: SectionMode.CARD, hideTitle: true, hideDescription: true, children: [_jsx(DisplayField, { name: "description" }), _jsx(DisplayField, { name: "code" })] }), _jsxs(Section, { name: "discount", hideDescription: true, children: [_jsx(DisplayField, { name: "discountType" }), _jsx(DisplayField, { name: "discountPercentage" }), _jsx(DisplayField, { name: "discountFixedAmount" })] }), _jsxs(Section, { name: "duration", hideDescription: true, children: [_jsx(DisplayField, { name: "duration" }), _jsx(DisplayField, { name: "durationInMonths" })] }), _jsxs(Section, { name: "applicability", hideDescription: true, children: [_jsx(DisplayField, { name: "applicableProducts" }), _jsx(DisplayField, { name: "maxRedemptions" }), _jsx(DisplayField, { name: "timesRedeemed" })] }), _jsxs(Section, { name: "validity", hideDescription: true, children: [_jsx(DisplayField, { name: "validFrom" }), _jsx(DisplayField, { name: "validUntil" }), _jsx(DisplayField, { name: "metadata" })] })] })),
+                // A card: the name, then the promotion type and the discount type as badges. The record id is gone.
+                summary: () => (_jsxs(SummaryLayout, { children: [_jsx(SummaryTitle, { name: "name" }), _jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "type" }), _jsx(DisplayField, { name: "discountType" })] })] })),
             },
             fields: {
                 _id: schemaShape._id.isHidden(),
                 name: schemaShape.name.stringUI({
-                    display: { displayMode: StringDisplayMode.TRUNCATE, truncateLength: 64, showDescription: true },
-                    edit: { showDescription: true },
+                    display: { displayMode: StringDisplayMode.TRUNCATE, truncateLength: 64 },
                 }),
                 description: schemaShape.description.stringUI({
-                    display: { displayMode: StringDisplayMode.MULTILINE, showDescription: true },
-                    edit: { component: FormFieldComponent.TEXTAREA, showDescription: true },
+                    display: { displayMode: StringDisplayMode.MULTILINE, hideWhenEmpty: true },
+                    edit: { component: FormFieldComponent.TEXTAREA },
                 }),
+                // Hidden when empty: a deal with no customer-facing code is a real kind of promotion, not a gap. The form
+                // keeps the description — what the code is for (typed at checkout) is not obvious.
                 code: schemaShape.code.stringUI({
-                    display: { displayMode: StringDisplayMode.COPY, showDescription: true },
+                    display: { displayMode: StringDisplayMode.COPY, hideWhenEmpty: true },
                     edit: { showDescription: true },
                 }),
                 type: schemaShape.type.enumUI({
-                    display: { displayMode: EnumDisplayMode.BADGE, showDescription: true },
-                    edit: { showDescription: true },
+                    display: { displayMode: EnumDisplayMode.BADGE },
                     values: {
                         [PromotionType.COUPON]: { color: BadgeSemanticVariant.SUCCESS, icon: Ticket },
                         [PromotionType.PROMOTION_CODE]: { color: BadgeSemanticVariant.INFO, icon: KeyRound },
@@ -253,44 +363,43 @@ export function buildBillingMainPresets() {
                     },
                 }),
                 discountType: schemaShape.discountType.enumUI({
-                    display: { displayMode: EnumDisplayMode.BADGE, showDescription: true },
-                    edit: { showDescription: true },
+                    display: { displayMode: EnumDisplayMode.BADGE },
                     values: {
                         [DiscountType.PERCENTAGE]: { color: BadgeSemanticVariant.INFO, icon: Percent },
                         [DiscountType.FIXED_AMOUNT]: { color: BadgeSemanticVariant.SECONDARY, icon: Banknote },
                     },
                 }),
+                // Only one of the two amounts applies (per `discountType`); the other is empty and hides.
                 discountPercentage: schemaShape.discountPercentage.numberUI({
                     suffix: '%',
-                    display: { displayMode: NumberDisplayMode.FORMATTED, showDescription: true },
-                    edit: { showDescription: true },
+                    display: { displayMode: NumberDisplayMode.FORMATTED, hideWhenEmpty: true },
                 }),
+                discountFixedAmount: schemaShape.discountFixedAmount.moneyUI({ display: { hideWhenEmpty: true } }),
                 duration: schemaShape.duration.enumUI({
-                    display: { displayMode: EnumDisplayMode.BADGE, showDescription: true },
-                    edit: { showDescription: true },
+                    display: { displayMode: EnumDisplayMode.BADGE },
                     values: {
                         [PromotionDuration.ONCE]: { color: BadgeSemanticVariant.SECONDARY, icon: CircleDot },
                         [PromotionDuration.REPEATING]: { color: BadgeSemanticVariant.INFO, icon: Repeat },
                         [PromotionDuration.FOREVER]: { color: BadgeSemanticVariant.SUCCESS, icon: Infinity },
                     },
                 }),
+                // Only a REPEATING promotion has a month count.
                 durationInMonths: schemaShape.durationInMonths.numberUI({
-                    display: { displayMode: NumberDisplayMode.FORMATTED, showDescription: true },
-                    edit: { showDescription: true },
-                }),
-                maxRedemptions: schemaShape.maxRedemptions.numberUI({
-                    display: { displayMode: NumberDisplayMode.FORMATTED, showDescription: true },
-                    edit: { showDescription: true },
-                }),
-                timesRedeemed: schemaShape.timesRedeemed.numberUI({
-                    display: { displayMode: NumberDisplayMode.FORMATTED, showDescription: true },
-                    edit: { showDescription: true },
-                }),
+                    display: { displayMode: NumberDisplayMode.FORMATTED, hideWhenEmpty: true },
+                }),
+                // NOT hidden when empty, and neither are the redemption cap and the validity bounds: for these four an
+                // empty value MEANS something ("every product", "unlimited", "no start", "no end"). The dash is kept until
+                // those words are authored, rather than hiding a real answer.
+                maxRedemptions: schemaShape.maxRedemptions.numberUI({ display: { displayMode: NumberDisplayMode.FORMATTED } }),
+                timesRedeemed: schemaShape.timesRedeemed.numberUI({ display: { displayMode: NumberDisplayMode.FORMATTED } }),
+                // A word in the header ("Active" / "Inactive"); a bare checkmark beside the name said nothing about what
+                // was checked. The form keeps the description: deactivating stops NEW redemptions only.
                 isActive: schemaShape.isActive.booleanUI({
                     labellingValue: BooleanLabellingValue.ACTIVE_INACTIVE,
-                    display: { displayMode: BooleanDisplayMode.CHECKMARK, showDescription: true },
+                    display: { displayMode: BooleanDisplayMode.RAW },
                     edit: { editMode: BooleanEditMode.SWITCH, showDescription: true },
                 }),
+                metadata: schemaShape.metadata.objectUI({ display: { hideWhenEmpty: true } }),
             },
             getFrontendResourceLabel: ({ currentObject }) => currentObject.name,
             views: [
@@ -319,14 +428,16 @@ export function buildBillingMainPresets() {
                     display: { displayMode: BooleanDisplayMode.CHECKMARK },
                 }),
             },
-            // A billing account has no user-authored name — it is the singleton
-            // provider link for its scope. Label it by its role + state instead of
-            // leaking the raw `_id` as a title (same raw-composition convention as
-            // the invoice label below).
-            getFrontendResourceLabel: ({ currentObject }) => currentObject.isActive === false ? 'Billing account (inactive)' : 'Billing account',
+            // A billing account has no user-authored name — it is the singleton provider link for its scope — so it is
+            // named by its resource's own words (the READ title, "Billing account"), never by its raw `_id`. Whether it
+            // is active is its STATE, a badge, not part of the name; the name used to be English written in code
+            // ("Billing account (inactive)"), which no translator could reach. A missing word shows its key.
+            getFrontendResourceLabel: ({ t, resourceType }) => t(`${LabellingTypes.RESOURCES}.${resourceType}.operations.read.title`),
             views: [
                 [BillingAccount_Operations.OPEN_CHECKOUT, notAddressable({ iconOverride: ShoppingCart })],
                 [BillingAccount_Operations.OPEN_PORTAL, notAddressable({ iconOverride: ExternalLink })],
+                // #1802: a new customer redeems a referral code on its own account.
+                [BillingAccount_Operations.REDEEM_REFERRAL, notAddressable({ iconOverride: Handshake })],
                 [BillingAccount_Operations.GET_STATE, notAddressable({ iconOverride: Info })],
                 // Billing accounts are Stripe-managed (portal/checkout) — generic UPDATE/DELETE
                 // are headless (no inline edit/delete UI).
@@ -416,7 +527,9 @@ export function buildBillingMainPresets() {
                     edit: { component: FormFieldComponent.TEXTAREA },
                 }),
             },
-            getFrontendResourceLabel: ({ currentObject }) => String(currentObject.status),
+            // A subscription is named by the billing period it is in, in the viewer's date format. Its status is its state
+            // (the badge), and the raw status value was all the name used to say.
+            getFrontendResourceLabel: ({ currentObject, formatDate }) => `${formatDate(currentObject.currentPeriodStart)} – ${formatDate(currentObject.currentPeriodEnd)}`,
             views: [
                 [BillingSubscription_Operations.CANCEL, notAddressable({ iconOverride: Ban })],
                 [BillingSubscription_Operations.RESUME, notAddressable({ iconOverride: CirclePlay })],
@@ -424,6 +537,8 @@ export function buildBillingMainPresets() {
                 [BillingSubscription_Operations.PREVIEW_PLAN_CHANGE, apiOnly()],
                 [BillingSubscription_Operations.ADD_ADDON, notAddressable({ iconOverride: PackagePlus })],
                 [BillingSubscription_Operations.REMOVE_ADDON, notAddressable({ iconOverride: PackageMinus })],
+                // Withdraws a plan change pending at the end of the period (#1868).
+                [BillingSubscription_Operations.CANCEL_PLAN_CHANGE, notAddressable({ iconOverride: CalendarX2 })],
                 // Subscriptions are managed via the custom ops above + Stripe — generic UPDATE
                 // is headless (no inline edit UI).
                 [Op.UPDATE, apiOnly()],
@@ -450,16 +565,24 @@ export function buildBillingMainPresets() {
                 },
                 summary: () => {
                     const { data, isLoading } = useDisplayTemplateContext();
-                    return (_jsxs(SummaryLayout, { children: [_jsx(SummaryTitle, { name: "poolKey" }), _jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "available" }), _jsx(DisplayField, { name: "totalPurchased" }), _jsx(DisplayField, { name: "totalConsumed" })] }), _jsx(DisplayField, { name: "billingAccountId", hideLabel: true, className: "text-muted-foreground text-xs font-mono truncate max-w-full" })] }));
+                    return (_jsxs(SummaryLayout, { children: [_jsx(SummaryTitle, {}), _jsxs(SummaryMeta, { children: [_jsx(DisplayField, { name: "poolKey" }), _jsx(DisplayField, { name: "available" }), _jsx(DisplayField, { name: "totalPurchased" }), _jsx(DisplayField, { name: "totalGranted" }), _jsx(DisplayField, { name: "totalConsumed" })] }), _jsx(DisplayField, { name: "billingAccountId", hideLabel: true, className: "text-muted-foreground text-xs font-mono truncate max-w-full" })] }));
                 },
             },
             fields: {
                 _id: schema.shape._id.isHidden(),
                 available: schema.shape.available.numberUI({ display: { displayMode: NumberDisplayMode.FORMATTED } }),
                 totalPurchased: schema.shape.totalPurchased.numberUI({ display: { displayMode: NumberDisplayMode.FORMATTED } }),
+                totalGranted: schema.shape.totalGranted.numberUI({ display: { displayMode: NumberDisplayMode.FORMATTED, hideWhenEmpty: true } }),
                 totalConsumed: schema.shape.totalConsumed.numberUI({ display: { displayMode: NumberDisplayMode.FORMATTED } }),
             },
-            getFrontendResourceLabel: ({ currentObject }) => currentObject.poolKey,
+            // Named by the application's word for the pool (`billing_credit_pools.<poolKey>.name`), for the same reason as a
+            // product (#1851). An unworded pool answers its key.
+            getFrontendResourceLabel: ({ currentObject, t }) => {
+                const nameKey = `${LabellingTypes.BILLING_CREDIT_POOLS}.${currentObject.poolKey}.name`;
+                const name = t(nameKey);
+                return name === nameKey ? unresolvedLabel(currentObject.poolKey) : name;
+            },
+            instanceLabelSections: [LabellingTypes.BILLING_CREDIT_POOLS],
             views: [
                 [CreditPool_Operations.TOP_UP, notAddressable({ iconOverride: CirclePlus })],
             ],
@@ -490,7 +613,9 @@ export function buildBillingMainPresets() {
                     display: { displayMode: NumberDisplayMode.FORMATTED, showDescription: true },
                 }),
             },
-            getFrontendResourceLabel: ({ currentObject }) => `Invoice ${currentObject.status}`,
+            // An invoice is named by its date, in the viewer's format. Its status is the badge beside it; the name used to be
+            // English written in code around the raw status ("Invoice paid").
+            getFrontendResourceLabel: ({ currentObject, formatDate }) => formatDate(currentObject.createdAt),
             views: [
                 [Op.LIST, notAddressable()],
                 [Op.READ, notAddressable()],
@@ -514,7 +639,9 @@ export function buildBillingMainPresets() {
                     display: { displayMode: NumberDisplayMode.FORMATTED, showDescription: true },
                 }),
             },
-            getFrontendResourceLabel: ({ currentObject }) => `${currentObject.productKey} · ${currentObject.quantity}`,
+            // A usage record is named by the instant it was recorded. The product key is an identifier and the quantity a
+            // value; both are rows, and the name used to be the two raw values joined.
+            getFrontendResourceLabel: ({ currentObject, formatDateTime }) => formatDateTime(currentObject.timestamp),
             views: [
                 [Op.LIST, notAddressable()],
                 [Op.READ, notAddressable()],
@@ -549,6 +676,8 @@ export function buildBillingAdminPresets(main) {
                 [Op.READ, notAddressable()],
                 // Referrals are an immutable ledger record — UPDATE is headless (no edit UI).
                 [Op.UPDATE, apiOnly()],
+                [Referral_Operations.ISSUE, notAddressable({ iconOverride: CirclePlus })],
+                [Referral_Operations.CANCEL, notAddressable({ iconOverride: CircleX })],
             ],
         })),
         [R.PROMOTIONS]: resourceUIBehaviorFrom(promotionsFactory, main[R.PROMOTIONS], ({ base }) => ({