@eifi1/ui-kit 0.32.2 → 0.33.1

package/src/i18n/locales/hu.ts

@@ -1488,14 +1488,53 @@ export function uiKitLabelsHu(numberLocale = "hu-HU"): UiKitLabels {
       // Both figures arrive formatted and stay bare, as `characterCount.count` (convention 3).
       usage: (used, limit) => `${used} / ${limit}`,
       contactSubject: (dimension) => `Csomagkorlát: ${dimension}`,
+      // The toast's figure line (§14.11) and the plan change's over-limit lines (§14.12);
+      // the figures bare, as `usage` (convention 3).
+      limitUsageLine: (dimension, used, limit) => `${dimension}: ${used} / ${limit}`,
       manage: "Fizetés és számlák",
       cancel: "Előfizetés lemondása",
+      // §14.5: no customer at the provider yet, so no portal to open.
+      notAtProvider:
+        "Egyelőre nincs mit kezelni. A fizetések és a számlák itt jelennek meg, amint fizetős csomagja lesz.",
+      // §14.4: the pay page's lines, built into its bundle — in Hungarian, though Paddle's
+      // checkout beside them is English (it has no Hungarian).
+      payOpening: "A biztonságos fizetés megnyitása…",
+      payNothing: "Itt nincs mit kifizetni. Csomag választásához térjen vissza az alkalmazásba.",
+      payFailed: "A fizetést nem sikerült megnyitni. Kérjük, lépjen vissza, és próbálja újra egy kis idő múlva.",
+      payBack: "A fizetés bezárult. Visszaléphet, vagy a megnyitásához töltse újra ezt az oldalt.",
       // No plural after a numeral (convention 2).
       waitingChanges: (count) => `${n(count)} módosítás csomagra vár`,
       // "Elvetés", as `wizard.cancelConfirmLabel`.
       discardWaiting: "Várakozó módosítások elvetése",
       notConfigured: "A fizetés még nincs beállítva. Kérjük, próbálja újra később.",
       disabled: "Az előfizetés itt nem érhető el.",
+      // §14.2: server-kit 0.7's refusals. "Fizetés és számlák", as `manage`.
+      providerUnavailable: "A fizetési szolgáltató jelenleg nem érhető el. Kérjük, próbálja újra egy kis idő múlva.",
+      alreadySubscribed: "Már van előfizetése. A csomag módosításához nyissa meg a „Fizetés és számlák” részt.",
+      planNotSold:
+        "Ez a csomag ehhez a számlázási időszakhoz vagy pénznemhez nem érhető el. Kérjük, válasszon másikat.",
+    },
+    // 0.33.0 — docs/billing-harmonization.md §14.12: the operator's plan parts, "csomag"
+    // as in `billing`. A plan's name takes no case ending: it follows a colon or an arrow.
+    planChange: {
+      column: "Csomag",
+      title: "Csomag módosítása",
+      confirm: "Csomag módosítása",
+      plan: "Csomag",
+      current: (plan) => `Jelenlegi csomag: ${plan}`,
+      keepsItems: "A kisebb csomag csak újak létrehozását tiltja; semmi sem törlődik.",
+      until: "Ingyenes eddig",
+      untilHint: "Hagyja üresen, ha nincs vége. A futó béta megtartja a saját lejáratát.",
+      needsChange: "Válasszon másik csomagot vagy egy záró dátumot.",
+      changed: (from, to) => `Csomag módosítva: ${from} → ${to}.`,
+      set: (to) => `Beállított csomag: ${to}.`,
+      keptBeta: "A béta megtartja a lejáratát; csak a csomag változott.",
+      untilDone: (date) => `Ingyenes eddig: ${date}.`,
+      overLimit: "Az új csomag korlátja felett: semmi sem törlődik, de újak nem hozhatók létre.",
+      // The figures bare, as `billing.usage` (convention 3), and the app's word after
+      // them, as `dataTable.filterResults` ("1 / 5 költségvetés"): since 0.33.1 it is the
+      // word as it reads after a number, which stays singular here (convention 2).
+      usageOf: (used, limit, dimension) => `${used} / ${limit} ${dimension}`,
     },
     // 0.32.0 — docs/text-size-harmonization.md §6: the text-size and contrast settings in
     // the "Megjelenés" group.

package/src/i18n/locales/it.ts

@@ -1500,14 +1500,50 @@ export function uiKitLabelsIt(numberLocale = "it-IT"): UiKitLabels {
       // Both figures arrive formatted; "di", as `characterCount.count`.
       usage: (used, limit) => `${used} di ${limit}`,
       contactSubject: (dimension) => `Limite del piano: ${dimension}`,
+      // The toast's figure line (§14.11) and the plan change's over-limit lines (§14.12).
+      limitUsageLine: (dimension, used, limit) => `${dimension}: ${used} di ${limit}`,
       manage: "Pagamento e fatture",
       cancel: "Disdici l’abbonamento",
+      // §14.5: no customer at the provider yet, so no portal to open.
+      notAtProvider:
+        "Ancora niente da gestire. Pagamenti e fatture compariranno qui quando avrà un piano a pagamento.",
+      // §14.4: the pay page's lines, built into its bundle. "Lei".
+      payOpening: "Apertura del pagamento sicuro…",
+      payNothing: "Qui non c’è nulla da pagare. Per scegliere un piano, torni all’app.",
+      payFailed: "Non è stato possibile aprire il pagamento. Torni indietro e riprovi tra un momento.",
+      payBack: "Il pagamento è stato chiuso. Può tornare indietro, oppure ricaricare questa pagina per riaprirlo.",
       waitingChanges: (count) =>
         `${n(count)} ${plural(count, "modifica in attesa", "modifiche in attesa")} di un piano`,
       // "Scarta", as `wizard.cancelConfirmLabel`.
       discardWaiting: "Scarta le modifiche in attesa",
       notConfigured: "I pagamenti non sono ancora configurati. Riprovi più tardi.",
       disabled: "Gli abbonamenti non sono disponibili qui.",
+      // §14.2: server-kit 0.7's refusals. "Pagamento e fatture", as `manage`. "Lei".
+      providerUnavailable: "Il fornitore dei pagamenti non è raggiungibile al momento. Riprovi tra un momento.",
+      alreadySubscribed: "Ha già un abbonamento. Per cambiare piano, vada su «Pagamento e fatture».",
+      planNotSold:
+        "Questo piano non è disponibile per questo periodo di fatturazione o questa valuta. Ne scelga un altro.",
+    },
+    // 0.33.0 — docs/billing-harmonization.md §14.12: the operator's plan parts, "piano" as
+    // in `billing`. "Lei" in sentences, the imperative on the title and the button.
+    planChange: {
+      column: "Piano",
+      title: "Cambia piano",
+      confirm: "Cambia piano",
+      plan: "Piano",
+      current: (plan) => `Piano attuale: ${plan}`,
+      keepsItems: "Un piano più piccolo blocca solo la creazione di nuovi elementi; non viene eliminato nulla.",
+      until: "Gratuito fino al",
+      untilHint: "Lasci vuoto per nessuna scadenza. Una beta in corso mantiene la propria scadenza.",
+      needsChange: "Scelga un altro piano o una data di fine.",
+      changed: (from, to) => `Piano cambiato da ${from} a ${to}.`,
+      set: (to) => `Piano impostato su ${to}.`,
+      keptBeta: "La beta mantiene la sua scadenza; è cambiato solo il piano.",
+      untilDone: (date) => `Gratuito fino al ${date}.`,
+      overLimit: "Oltre il limite del nuovo piano: non viene rimosso nulla, i nuovi elementi sono bloccati.",
+      // Figures formatted; "di", as `billing.usage`. The app's word follows the limit,
+      // in its form (0.33.1): "1 di 1 budget", "1 di 5 budget".
+      usageOf: (used, limit, dimension) => `${used} di ${limit} ${dimension}`,
     },
     // 0.32.0 — docs/text-size-harmonization.md §6: the text-size and contrast settings in
     // the "Aspetto" group.

package/src/i18n/locales/zh.ts

@@ -1425,13 +1425,47 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       // Both figures arrive formatted; written as `characterCount.count` writes them.
       usage: (used, limit) => `${used}/${limit}`,
       contactSubject: (dimension) => `套餐上限：${dimension}`,
+      // The toast's figure line (§14.11) and the plan change's over-limit lines (§14.12);
+      // written as `usage` writes the figures.
+      limitUsageLine: (dimension, used, limit) => `${dimension}：${used}/${limit}`,
       manage: "付款与发票",
       cancel: "取消订阅",
+      // §14.5: no customer at the provider yet, so no portal to open.
+      notAtProvider: "暂无可管理的内容。开通付费套餐后，付款和发票会显示在这里。",
+      // §14.4: the pay page's lines, built into its bundle.
+      payOpening: "正在打开安全支付页面…",
+      payNothing: "这里没有需要支付的款项。如需选择套餐，请返回应用。",
+      payFailed: "无法打开支付页面。请返回后稍候再试。",
+      payBack: "支付页面已关闭。您可以返回，或重新加载此页面以再次打开。",
       waitingChanges: (count) => `${n(count)} 项修改正在等待套餐`,
       // "放弃", as `wizard.cancelConfirmLabel`.
       discardWaiting: "放弃等待中的修改",
       notConfigured: "付款尚未设置，请稍后再试。",
       disabled: "此处不提供订阅。",
+      // §14.2: server-kit 0.7's refusals. "付款与发票", as `manage`.
+      providerUnavailable: "暂时无法连接支付服务商，请稍后再试。",
+      alreadySubscribed: "您已有订阅。如需更改套餐，请前往“付款与发票”。",
+      planNotSold: "该套餐不支持此计费周期或货币，请选择其他套餐。",
+    },
+    // 0.33.0 — docs/billing-harmonization.md §14.12: the operator's plan parts, "套餐" as
+    // in `billing`. "测试版", as `landing.beta`.
+    planChange: {
+      column: "套餐",
+      title: "更改套餐",
+      confirm: "更改套餐",
+      plan: "套餐",
+      current: (plan) => `当前套餐：${plan}`,
+      keepsItems: "较小的套餐只会阻止新建更多内容，不会删除任何内容。",
+      until: "免费至",
+      untilHint: "留空表示没有结束日期。正在进行的测试版保留其自身的结束日期。",
+      needsChange: "请选择其他套餐或结束日期。",
+      changed: (from, to) => `套餐已从 ${from} 更改为 ${to}。`,
+      set: (to) => `套餐已设为 ${to}。`,
+      keptBeta: "测试版保留其结束日期；只更改了套餐。",
+      untilDone: (date) => `免费至 ${date}。`,
+      overLimit: "超出新套餐的上限：不会删除任何内容，但无法新建。",
+      // No plural: the app's word reads the same after any number (0.33.1).
+      usageOf: (used, limit, dimension) => `${used}/${limit} ${dimension}`,
     },
     // 0.32.0 — docs/text-size-harmonization.md §6: the text-size and contrast settings in
     // the "外观" group.

package/src/i18n/plurals.ts

@@ -52,3 +52,32 @@ function pluralCategories(locale: string, type: Intl.PluralRuleType): readonly s
     return [];
   }
 }
+
+/**
+ * A word in the plural forms a count can ask for, `other` required: an app's
+ * `key_one` / `key_other` pair, or any of CLDR's categories (`zero`, `one`, `two`, `few`,
+ * `many`). A category left out reads `other`, the stand-in {@link withAllPlurals} fills
+ * a catalogue with — so English's two forms serve every language, as in the apps'
+ * catalogues.
+ *
+ *     { one: t("planUsage.budget_one"), other: t("planUsage.budget_other") }
+ */
+export type PluralForms = { other: string } & Partial<Record<Intl.LDMLPluralRule, string>>;
+
+/**
+ * The form of `forms` that `count` takes in `locale` — CLDR's cardinal category for it,
+ * through `Intl.PluralRules`, else `other`. A locale `Intl` cannot read reads as the
+ * runtime's, as everywhere the kit formats (and `undefined` is the runtime's). For the
+ * kit's own parts that put an app's word after a count: `planColumn`'s usage.
+ */
+export function pluralForm(count: number, forms: PluralForms, locale?: string): string {
+  return forms[pluralCategory(count, locale)] ?? forms.other;
+}
+
+function pluralCategory(count: number, locale: string | undefined): Intl.LDMLPluralRule {
+  try {
+    return new Intl.PluralRules(locale).select(count);
+  } catch {
+    return new Intl.PluralRules().select(count);
+  }
+}

package/src/i18n/review.ts

@@ -366,4 +366,11 @@ export const KIT_LABEL_SAMPLES: Readonly<Record<string, readonly (readonly unkno
   "billing.usage": [["{{used}}", "{{limit}}"]],
   "billing.contactSubject": [["{{dimension}}"]],
   "billing.waitingChanges": one,
+  // 0.33.0: the limit's figure line (§14.11) and the operator's plan parts (§14.12).
+  "billing.limitUsageLine": [["{{dimension}}", "{{used}}", "{{limit}}"]],
+  "planChange.current": [["{{plan}}"]],
+  "planChange.changed": [["{{from}}", "{{to}}"]],
+  "planChange.set": [["{{to}}"]],
+  "planChange.untilDone": [["{{date}}"]],
+  "planChange.usageOf": [["{{used}}", "{{limit}}", "{{dimension}}"]],
 };

package/src/index.ts

@@ -88,7 +88,7 @@ export * from "./components/search-field";
 export * from "./components/dropdown";
 export * from "./components/popover";
 export { SwipeableRow } from "./components/swipeable-row";
-export type { SwipeAction, SwipeableRowProps } from "./components/swipeable-row";
+export type { SwipeAction, SwipePaint, SwipeTone, SwipeableRowProps } from "./components/swipeable-row";
 export * from "./components/calculator";
 export * from "./components/numpad-sheet";
 export * from "./components/number-input";
@@ -214,8 +214,11 @@ export * from "./components/description-list";
 export * from "./components/form-actions";
 // 0.18: lock every opted-in commit under one provider, the reason in its tooltip
 // (Kurvenschmiede 2). `useCommitReason` stays internal.
-export { WriteLockProvider, useWriteLock, DEFAULT_WRITE_LOCK_LABELS } from "./components/write-lock";
-export type { WriteLock, WriteLockLabels, WriteLockProviderProps } from "./components/write-lock";
+// 0.33: a lock says its source, and a control can be exempt from one
+// (docs/billing-harmonization.md §12.36): the kinds, the holds, `CommitScope`,
+// `COMMIT_EXCEPT_BILLING` and the pure `writeLockFor`.
+export { WriteLockProvider, useWriteLock, writeLockFor, COMMIT_EXCEPT_BILLING, DEFAULT_WRITE_LOCK_LABELS } from "./components/write-lock";
+export type { WriteLock, WriteLockLabels, WriteLockProviderProps, WriteLockKind, WriteLockHold, CommitScope } from "./components/write-lock";
 // 0.18: the parts both apps' admin rosters repeat (Kurvenschmiede 6).
 export { RoleChip, AccountStateChip, DateMark, dateColumn, DEFAULT_ACCOUNT_STATE_LABELS, ACCOUNT_STATE_TONES } from "./components/account-chips";
 export type { RoleChipProps, RoleDefinition, RoleVocabulary, AccountState, AccountStateLabels, AccountStateChipProps, DateMarkProps, DateColumnOptions } from "./components/account-chips";
@@ -399,8 +402,10 @@ export { kitLabelStrings } from "./i18n/review";
 export type { KitLabelStringsOptions } from "./i18n/review";
 // The seven languages, how an app resolves one, and the kit catalogue loader for it.
 export * from "./i18n/languages";
-// CLDR plural categories for an app's i18next catalogue, filled from `_other`.
+// CLDR plural categories for an app's i18next catalogue, filled from `_other`; and the
+// forms of an app's word a kit part picks from by count (0.33.1, `PlanColumnUsage.label`).
 export { withAllPlurals } from "./i18n/plurals";
+export type { PluralForms } from "./i18n/plurals";
 // Translation review (0.19): one contract for kastlan's and keksdose's review pages —
 // the pure rows/status/placeholder logic and the presentational page parts.
 export {
@@ -784,6 +789,7 @@ export type {
   RowActionsCollapse,
   RowActionsSize,
   RowActionsColumnOptions,
+  RowActionTone,
 } from "./components/row-actions";
 export { useLargeText, useCoarsePointer, useInlineFacts } from "./hooks/use-large-text";
 export type { AppearanceLabels } from "./components/appearance-labels";
@@ -803,12 +809,52 @@ export { PlanLimitNotice, planLimitMailto } from "./billing/plan-limit-notice";
 export type { PlanLimitNoticeProps } from "./billing/plan-limit-notice";
 export { isPlanLimit } from "./billing/plan-limit";
 export type { PlanLimitRefusal } from "./billing/plan-limit";
-export { combineWriteLocks, useBillingLockReason } from "./billing/billing-lock";
+// 0.33.0: sources name their kind, the combined lock holds them all, and billing's is one
+// hook (docs/billing-harmonization.md §12.36).
+export { combineWriteLocks, useBillingLockReason, useBillingWriteLock } from "./billing/billing-lock";
 export type { WriteLockSource, CombinedWriteLock, BillingLockReasonOptions } from "./billing/billing-lock";
 export { billingLockAt, isBillingReadOnly, billingDaysLeft } from "./billing/billing-standing";
 export type { BillingStanding } from "./billing/billing-standing";
 export { SubscriptionActions } from "./billing/subscription-actions";
 export type { SubscriptionActionsProps } from "./billing/subscription-actions";
+// ── 0.33.0: billing's round 0.33 (docs/billing-harmonization.md §14) ──
+// The way back from a checkout and its "processing", router-agnostic (§14.4).
+export {
+  CHECKOUT_RETURN_PARAM,
+  CHECKOUT_RETURN_VALUE,
+  isCheckoutReturn,
+  withoutCheckoutReturn,
+  checkoutReturnUrl,
+} from "./billing/checkout-return";
+export { checkoutFingerprint, checkoutLanded, noteCheckoutStarted, useCheckoutProcessing } from "./billing/checkout-processing";
+export type { CheckoutOverview, CheckoutProcessingOptions } from "./billing/checkout-processing";
+// The link to the pay page and Paddle's locale (§14.4); the page itself ships as dist/pay/.
+export { PAY_PAGE_LANG_PARAM, paddleLocale, payPageUrl } from "./billing/pay-page";
+export type { PaddleEnvironment } from "./billing/pay-page";
+// The API's shapes the parts read, server-kit 0.7's (§4, §14.5), and the plan limit as
+// a toast (§14.11).
+export type { BillingOverview, SubscriptionSource, PortalTarget, PortalRequest } from "./billing/billing-overview";
+export { usePlanLimitToast } from "./billing/plan-limit-toast";
+export type { PlanLimitToastOptions } from "./billing/plan-limit-toast";
+// The operator's plan parts (§14.12).
+export {
+  planColumn,
+  usePlanColumn,
+  PlanChangeConfirm,
+  usePlanChangeResult,
+  DEFAULT_PLAN_CHANGE_LABELS,
+} from "./admin/plan-change";
+export type {
+  PlanChangeLabels,
+  PlanColumnOptions,
+  PlanColumnUsage,
+  PlanChange,
+  PlanChangeConfirmProps,
+  PlanChangeOutcome,
+  PlanChangeTone,
+  PlanChangeLine,
+  PlanChangeResultOptions,
+} from "./admin/plan-change";
 
 // ── 0.22.0: the inputs round (kastlan's, keksdose's and Kurvenschmiede's audits) ──
 export * from "./components/checkbox-group";

package/src/testing/css-variables.generated.ts

@@ -0,0 +1,112 @@
+// GENERATED by scripts/gen-kit-css-variables.mjs — do not edit by hand. Re-run it after
+// changing tokens.css or upgrading Tailwind; src/__tests__/token-vars-declared.test.ts
+// fails while this is stale.
+
+/** Every custom property tokens.css declares, `@theme inline` names and `--app-nav-h`
+ *  left out (100 names). */
+export const KIT_NAMES =
+  "--bg-active --bg-hover --bg-inverse --bg-page --bg-surface --bg-surface-2 --border " +
+  "--border-strong --brand --brand-bg --brand-bg-hover --brand-contrast --brand-hover --brand-muted " +
+  "--breakpoint-3xl --chart-1 --chart-2 --chart-3 --chart-4 --chart-5 --chart-6 --chart-7 --chart-8 " +
+  "--chart-9 --danger --danger-bg --danger-border --danger-border-strong --danger-contrast " +
+  "--danger-hover --flyout-from --focus-ring-width --hue-blue --hue-blue-bg --hue-blue-border " +
+  "--hue-blue-contrast --hue-indigo --hue-indigo-bg --hue-indigo-border --hue-indigo-contrast " +
+  "--hue-orange --hue-orange-bg --hue-orange-border --hue-orange-contrast --hue-purple " +
+  "--hue-purple-bg --hue-purple-border --hue-purple-contrast --hue-teal --hue-teal-bg " +
+  "--hue-teal-border --hue-teal-contrast --info --info-bg --info-border --info-contrast --media-ink " +
+  "--media-scrim --media-scrim-hover --money-expense --money-expense-contrast --money-income " +
+  "--money-income-contrast --money-net --money-net-contrast --money-neutral " +
+  "--money-neutral-contrast --neutral --neutral-contrast --status-edited --status-error " +
+  "--status-pending --status-synced --success --success-bg --success-border --success-contrast " +
+  "--text-caption --text-inverse --text-micro --text-muted --text-placeholder --text-primary " +
+  "--text-secondary --toast-action-bg --toast-action-fg --toast-danger-bg --toast-danger-border " +
+  "--toast-info-bg --toast-info-border --toast-success-bg --toast-success-border --toast-warning-bg " +
+  "--toast-warning-border --warning --warning-bg --warning-border --warning-border-strong " +
+  "--warning-contrast --z-toast";
+
+/** The theme variables of Tailwind 4.3.3's `theme.css` (413 names). */
+export const TAILWIND_THEME_NAMES =
+  "--animate-bounce --animate-ping --animate-pulse --animate-spin --aspect-video --blur-2xl " +
+  "--blur-3xl --blur-lg --blur-md --blur-sm --blur-xl --blur-xs --breakpoint-2xl --breakpoint-lg " +
+  "--breakpoint-md --breakpoint-sm --breakpoint-xl --color-amber-100 --color-amber-200 " +
+  "--color-amber-300 --color-amber-400 --color-amber-50 --color-amber-500 --color-amber-600 " +
+  "--color-amber-700 --color-amber-800 --color-amber-900 --color-amber-950 --color-black " +
+  "--color-blue-100 --color-blue-200 --color-blue-300 --color-blue-400 --color-blue-50 " +
+  "--color-blue-500 --color-blue-600 --color-blue-700 --color-blue-800 --color-blue-900 " +
+  "--color-blue-950 --color-cyan-100 --color-cyan-200 --color-cyan-300 --color-cyan-400 " +
+  "--color-cyan-50 --color-cyan-500 --color-cyan-600 --color-cyan-700 --color-cyan-800 " +
+  "--color-cyan-900 --color-cyan-950 --color-emerald-100 --color-emerald-200 --color-emerald-300 " +
+  "--color-emerald-400 --color-emerald-50 --color-emerald-500 --color-emerald-600 " +
+  "--color-emerald-700 --color-emerald-800 --color-emerald-900 --color-emerald-950 " +
+  "--color-fuchsia-100 --color-fuchsia-200 --color-fuchsia-300 --color-fuchsia-400 " +
+  "--color-fuchsia-50 --color-fuchsia-500 --color-fuchsia-600 --color-fuchsia-700 " +
+  "--color-fuchsia-800 --color-fuchsia-900 --color-fuchsia-950 --color-gray-100 --color-gray-200 " +
+  "--color-gray-300 --color-gray-400 --color-gray-50 --color-gray-500 --color-gray-600 " +
+  "--color-gray-700 --color-gray-800 --color-gray-900 --color-gray-950 --color-green-100 " +
+  "--color-green-200 --color-green-300 --color-green-400 --color-green-50 --color-green-500 " +
+  "--color-green-600 --color-green-700 --color-green-800 --color-green-900 --color-green-950 " +
+  "--color-indigo-100 --color-indigo-200 --color-indigo-300 --color-indigo-400 --color-indigo-50 " +
+  "--color-indigo-500 --color-indigo-600 --color-indigo-700 --color-indigo-800 --color-indigo-900 " +
+  "--color-indigo-950 --color-lime-100 --color-lime-200 --color-lime-300 --color-lime-400 " +
+  "--color-lime-50 --color-lime-500 --color-lime-600 --color-lime-700 --color-lime-800 " +
+  "--color-lime-900 --color-lime-950 --color-mauve-100 --color-mauve-200 --color-mauve-300 " +
+  "--color-mauve-400 --color-mauve-50 --color-mauve-500 --color-mauve-600 --color-mauve-700 " +
+  "--color-mauve-800 --color-mauve-900 --color-mauve-950 --color-mist-100 --color-mist-200 " +
+  "--color-mist-300 --color-mist-400 --color-mist-50 --color-mist-500 --color-mist-600 " +
+  "--color-mist-700 --color-mist-800 --color-mist-900 --color-mist-950 --color-neutral-100 " +
+  "--color-neutral-200 --color-neutral-300 --color-neutral-400 --color-neutral-50 " +
+  "--color-neutral-500 --color-neutral-600 --color-neutral-700 --color-neutral-800 " +
+  "--color-neutral-900 --color-neutral-950 --color-olive-100 --color-olive-200 --color-olive-300 " +
+  "--color-olive-400 --color-olive-50 --color-olive-500 --color-olive-600 --color-olive-700 " +
+  "--color-olive-800 --color-olive-900 --color-olive-950 --color-orange-100 --color-orange-200 " +
+  "--color-orange-300 --color-orange-400 --color-orange-50 --color-orange-500 --color-orange-600 " +
+  "--color-orange-700 --color-orange-800 --color-orange-900 --color-orange-950 --color-pink-100 " +
+  "--color-pink-200 --color-pink-300 --color-pink-400 --color-pink-50 --color-pink-500 " +
+  "--color-pink-600 --color-pink-700 --color-pink-800 --color-pink-900 --color-pink-950 " +
+  "--color-purple-100 --color-purple-200 --color-purple-300 --color-purple-400 --color-purple-50 " +
+  "--color-purple-500 --color-purple-600 --color-purple-700 --color-purple-800 --color-purple-900 " +
+  "--color-purple-950 --color-red-100 --color-red-200 --color-red-300 --color-red-400 " +
+  "--color-red-50 --color-red-500 --color-red-600 --color-red-700 --color-red-800 --color-red-900 " +
+  "--color-red-950 --color-rose-100 --color-rose-200 --color-rose-300 --color-rose-400 " +
+  "--color-rose-50 --color-rose-500 --color-rose-600 --color-rose-700 --color-rose-800 " +
+  "--color-rose-900 --color-rose-950 --color-sky-100 --color-sky-200 --color-sky-300 " +
+  "--color-sky-400 --color-sky-50 --color-sky-500 --color-sky-600 --color-sky-700 --color-sky-800 " +
+  "--color-sky-900 --color-sky-950 --color-slate-100 --color-slate-200 --color-slate-300 " +
+  "--color-slate-400 --color-slate-50 --color-slate-500 --color-slate-600 --color-slate-700 " +
+  "--color-slate-800 --color-slate-900 --color-slate-950 --color-stone-100 --color-stone-200 " +
+  "--color-stone-300 --color-stone-400 --color-stone-50 --color-stone-500 --color-stone-600 " +
+  "--color-stone-700 --color-stone-800 --color-stone-900 --color-stone-950 --color-taupe-100 " +
+  "--color-taupe-200 --color-taupe-300 --color-taupe-400 --color-taupe-50 --color-taupe-500 " +
+  "--color-taupe-600 --color-taupe-700 --color-taupe-800 --color-taupe-900 --color-taupe-950 " +
+  "--color-teal-100 --color-teal-200 --color-teal-300 --color-teal-400 --color-teal-50 " +
+  "--color-teal-500 --color-teal-600 --color-teal-700 --color-teal-800 --color-teal-900 " +
+  "--color-teal-950 --color-violet-100 --color-violet-200 --color-violet-300 --color-violet-400 " +
+  "--color-violet-50 --color-violet-500 --color-violet-600 --color-violet-700 --color-violet-800 " +
+  "--color-violet-900 --color-violet-950 --color-white --color-yellow-100 --color-yellow-200 " +
+  "--color-yellow-300 --color-yellow-400 --color-yellow-50 --color-yellow-500 --color-yellow-600 " +
+  "--color-yellow-700 --color-yellow-800 --color-yellow-900 --color-yellow-950 --color-zinc-100 " +
+  "--color-zinc-200 --color-zinc-300 --color-zinc-400 --color-zinc-50 --color-zinc-500 " +
+  "--color-zinc-600 --color-zinc-700 --color-zinc-800 --color-zinc-900 --color-zinc-950 " +
+  "--container-2xl --container-2xs --container-3xl --container-3xs --container-4xl --container-5xl " +
+  "--container-6xl --container-7xl --container-lg --container-md --container-sm --container-xl " +
+  "--container-xs --default-font-family --default-font-feature-settings " +
+  "--default-font-variation-settings --default-mono-font-family " +
+  "--default-mono-font-feature-settings --default-mono-font-variation-settings " +
+  "--default-transition-duration --default-transition-timing-function --drop-shadow-2xl " +
+  "--drop-shadow-lg --drop-shadow-md --drop-shadow-sm --drop-shadow-xl --drop-shadow-xs --ease-in " +
+  "--ease-in-out --ease-out --font-mono --font-sans --font-serif --font-weight-black " +
+  "--font-weight-bold --font-weight-extrabold --font-weight-extralight --font-weight-light " +
+  "--font-weight-medium --font-weight-normal --font-weight-semibold --font-weight-thin " +
+  "--inset-shadow-2xs --inset-shadow-sm --inset-shadow-xs --leading-loose --leading-normal " +
+  "--leading-relaxed --leading-snug --leading-tight --perspective-distant --perspective-dramatic " +
+  "--perspective-midrange --perspective-near --perspective-normal --radius-2xl --radius-3xl " +
+  "--radius-4xl --radius-lg --radius-md --radius-sm --radius-xl --radius-xs --shadow-2xl " +
+  "--shadow-2xs --shadow-lg --shadow-md --shadow-sm --shadow-xl --shadow-xs --spacing --text-2xl " +
+  "--text-2xl--line-height --text-3xl --text-3xl--line-height --text-4xl --text-4xl--line-height " +
+  "--text-5xl --text-5xl--line-height --text-6xl --text-6xl--line-height --text-7xl " +
+  "--text-7xl--line-height --text-8xl --text-8xl--line-height --text-9xl --text-9xl--line-height " +
+  "--text-base --text-base--line-height --text-lg --text-lg--line-height --text-shadow-2xs " +
+  "--text-shadow-lg --text-shadow-md --text-shadow-sm --text-shadow-xs --text-sm " +
+  "--text-sm--line-height --text-xl --text-xl--line-height --text-xs --text-xs--line-height " +
+  "--tracking-normal --tracking-tight --tracking-tighter --tracking-wide --tracking-wider " +
+  "--tracking-widest";

package/src/testing/css-variables.ts

@@ -0,0 +1,191 @@
+import { KIT_NAMES, TAILWIND_THEME_NAMES } from "./css-variables.generated";
+
+/**
+ * The guard against an undeclared CSS custom property (0.33,
+ * docs/colour-roles-harmonization.md §8, §12.5).
+ *
+ * A `var(--name)` with no fallback, where nothing declares `--name`, makes the whole
+ * declaration invalid at computed-value time: `fill` inherits, `color` inherits, a
+ * background goes transparent. Kurvenschmiede's control diagram painted
+ * `fill-[var(--surface)]` — a token that never existed (the kit's is `--bg-surface`) —
+ * and drew black boxes on a public page. The class compiled, the build passed, the type
+ * checker had no opinion, and nothing in any suite noticed. This is the check that
+ * notices, run from an app's own test over the source texts the app collects.
+ *
+ * Browser-safe on purpose, like the rest of the kit: it takes TEXTS, not paths, so an app
+ * reads its files however its setup allows (`import.meta.glob` with `?raw`, or `node:fs`)
+ * and the kit carries no `node:fs`.
+ */
+
+/** Every custom property the installed kit declares or publishes to apps.
+ *
+ *  Generated from `tokens.css` when the kit is built (scripts/gen-kit-css-variables.mjs),
+ *  so it is always the installed version's, and an app never searches `node_modules`.
+ *  It leaves out two kinds of name on purpose:
+ *  - a name declared only in an `@theme inline` block (`--text-color-muted`,
+ *    `--background-color-surface`): Tailwind emits no variable for it, so
+ *    `var(--text-color-muted)` would pass a guard that counted it and paint nothing;
+ *  - AppShell's measured `--app-nav-h`, which exists only while an AppShell is mounted —
+ *    on a landing, legal, sign-in or pay page it is undefined. Read it with a fallback,
+ *    `var(--app-nav-h,0px)`, as every kit read does.
+ *  Everything `applyTokenSet` and More contrast write on `<html>` is in, through the
+ *  stylesheet's `:root` / `.dark` mirror. Component internals (`--slider-fill`, `--fp-*`,
+ *  `--icon-button-tone`, `--label-strip-edge`) are not: an app that reads one depends on
+ *  the kit's internals, and the guard says so. */
+export const KIT_CSS_VARIABLES: ReadonlySet<string> = new Set(KIT_NAMES.split(" "));
+
+/** Tailwind's own theme variables (`--color-rose-500`, `--spacing`, `--text-sm` …), from
+ *  the `tailwindcss/theme.css` the kit builds with. Tailwind emits one when a scanned file
+ *  names it, so a `var()` of it resolves. */
+const TAILWIND_THEME: ReadonlySet<string> = new Set(TAILWIND_THEME_NAMES.split(" "));
+
+/** A Tailwind PALETTE colour: a hue with a shade, black or white. `refusePalette` reports
+ *  these although they resolve — an app that has no palette lint asks this test to be
+ *  its refusal. */
+const PALETTE_VARIABLE = /^--color-(?:[a-z]+-\d{2,3}|black|white)$/;
+
+/** Read only where it is set: the guard accepts it in a fallback use, never bare. */
+const APP_NAV_H = "--app-nav-h";
+
+export interface UndeclaredCssVariablesOptions {
+  /** Variables a library writes at runtime, as names or patterns:
+   *  `["--radix-collapsible-content-height"]`. An app's own writes are found in its
+   *  source and need no listing. */
+  runtime?: readonly (string | RegExp)[];
+  /** Also check `var(--x, …)`. Off by default: a fallback says what happens when the
+   *  name is missing. `--app-nav-h` counts as declared only here. */
+  checkFallbacks?: boolean;
+  /** Report Tailwind palette variables (`--color-red-500`, `--color-white`) although
+   *  they resolve. Default false. */
+  refusePalette?: boolean;
+}
+
+/** Comments are not CSS. `/* *\/` in both; `//` in TS only (not after a `:`, so a URL in a
+ *  string survives). Replaced by spaces of the same shape, so line numbers hold. */
+function stripComments(text: string, isCss: boolean): string {
+  const blank = (m: string) => m.replace(/[^\n]/g, " ");
+  const noBlocks = text.replace(/\/\*[\s\S]*?\*\//g, blank);
+  return isCss ? noBlocks : noBlocks.replace(/(^|[^:])(\/\/[^\n]*)/g, (_, pre: string, c: string) => pre + blank(c));
+}
+
+/** The text with every `@theme … inline … { … }` block blanked out, braces and all. */
+function withoutInlineTheme(css: string): string {
+  let out = css;
+  for (const m of css.matchAll(/@theme\b[^{;]*\binline\b[^{;]*\{/g)) {
+    let depth = 0;
+    let end = m.index + m[0].length - 1;
+    for (; end < css.length; end++) {
+      if (css[end] === "{") depth++;
+      else if (css[end] === "}" && --depth === 0) break;
+    }
+    out = out.slice(0, m.index) + css.slice(m.index, end + 1).replace(/[^\n]/g, " ") + out.slice(end + 1);
+  }
+  return out;
+}
+
+/**
+ * Every custom property a stylesheet declares (`--name:`), in any block — except a name
+ * declared only inside `@theme inline`, which Tailwind never emits as a variable. Comments
+ * are skipped. The same rule builds {@link KIT_CSS_VARIABLES} from `tokens.css`.
+ */
+export function declaredCustomProperties(css: string): Set<string> {
+  const code = withoutInlineTheme(stripComments(css, true));
+  return new Set([...code.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g)].map((m) => m[1]));
+}
+
+/** What an app's source writes at runtime: `setProperty("--name"`, a React style key
+ *  `"--name":`, a Tailwind arbitrary property `[--name:…]`. */
+function runtimeWrites(code: string): string[] {
+  return [
+    ...code.matchAll(/setProperty\(\s*["'`](--[a-zA-Z0-9_-]+)["'`]/g),
+    ...code.matchAll(/["'](--[a-zA-Z0-9_-]+)["']\s*:/g),
+    ...code.matchAll(/\[(--[a-zA-Z0-9_-]+):/g),
+  ].map((m) => m[1]);
+}
+
+/** A chart series' colour (`var(--color-total)`) is declared in a file with a `total: {`
+ *  config entry: the kit's ChartContainer writes `--color-<key>` for each key. */
+function chartKeys(code: string): Set<string> {
+  return new Set([...code.matchAll(/(?:^|[\s{,])["']?([A-Za-z_][\w-]*)["']?\s*:\s*\{/g)].map((m) => m[1]));
+}
+
+const isCssPath = (path: string) => /\.css(?:\?|$)/.test(path);
+
+/**
+ * Every `var(--name)` without a fallback that nothing declares, as `"path:line --name"`.
+ *
+ * `sources` maps a path to its text: the app's `.ts`, `.tsx` and `.css` source, tests
+ * left out. A name counts as declared when it is:
+ * 1. the kit's ({@link KIT_CSS_VARIABLES});
+ * 2. declared in any `.css` entry of `sources` (outside `@theme inline`);
+ * 3. written by the source at runtime (`setProperty`, a style key, `[--name:…]`);
+ * 4. one of Tailwind's theme variables — unless `refusePalette` and it is a palette colour;
+ * 5. a chart series' `--color-<key>`, in a file with a `<key>: {` entry;
+ * 6. listed in `options.runtime`.
+ *
+ * Not counted: comments; a use with a fallback, unless `checkFallbacks`; a name built at
+ * runtime (`` `var(--chart-${n})` `` — a name must be followed by `)` or `,`).
+ *
+ * It REFUSES A VACUOUS RUN: it throws when `sources` holds fewer than ten files, or when
+ * a `.css` entry is empty. Vitest stubs every stylesheet with an empty string by default,
+ * `?raw` included, so an app that reads its CSS that way without opting it out of the stub
+ * (`test.css.include`) would otherwise lose every declaration and every use in it, and
+ * this would pass or fail for the wrong reason.
+ */
+export function undeclaredCssVariables(
+  sources: Record<string, string>,
+  options: UndeclaredCssVariablesOptions = {},
+): string[] {
+  const { runtime = [], checkFallbacks = false, refusePalette = false } = options;
+  const entries = Object.entries(sources);
+  if (entries.length < 10) {
+    throw new Error(
+      `undeclaredCssVariables: only ${entries.length} source file(s) — the glob or the file list found ` +
+        `(almost) nothing, and a check over nothing passes. Pass the app's .ts/.tsx/.css source.`,
+    );
+  }
+  const emptyCss = entries.filter(([path, text]) => isCssPath(path) && text.trim() === "").map(([path]) => path);
+  if (emptyCss.length) {
+    throw new Error(
+      `undeclaredCssVariables: ${emptyCss.join(", ")} read as empty. Vitest stubs stylesheets with "" ` +
+        `(\`?raw\` too) unless the file is listed in \`test.css.include\`.`,
+    );
+  }
+
+  const code = entries.map(([path, text]) => [path, stripComments(text, isCssPath(path))] as const);
+  const declared = new Set<string>();
+  for (const [path, text] of code) {
+    if (isCssPath(path)) for (const name of declaredCustomProperties(text)) declared.add(name);
+    for (const name of runtimeWrites(text)) declared.add(name);
+  }
+  const listed = (name: string) =>
+    runtime.some((r) => (typeof r === "string" ? r === name : r.test(name)));
+
+  const out: string[] = [];
+  for (const [path, text] of code) {
+    let keys: Set<string> | null = null;
+    for (const m of text.matchAll(/var\(\s*(--[a-zA-Z0-9_-]+)\s*([,)])/g)) {
+      const [, name, next] = m;
+      const fallback = next === ",";
+      if (fallback && !checkFallbacks) continue;
+      if (KIT_CSS_VARIABLES.has(name) || declared.has(name) || listed(name)) continue;
+      if (fallback && name === APP_NAV_H) continue;
+      if (TAILWIND_THEME.has(name)) {
+        if (refusePalette && PALETTE_VARIABLE.test(name)) {
+          out.push(`${path}:${lineOf(text, m.index)} ${name} (a Tailwind palette colour; refusePalette is on)`);
+        }
+        continue;
+      }
+      const chart = /^--color-([A-Za-z_][\w-]*)$/.exec(name);
+      if (chart && (keys ??= chartKeys(text)).has(chart[1])) continue;
+      out.push(`${path}:${lineOf(text, m.index)} ${name}`);
+    }
+  }
+  return out;
+}
+
+function lineOf(text: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (text.charCodeAt(i) === 10) line++;
+  return line;
+}

package/src/testing/index.ts

@@ -0,0 +1,13 @@
+// `@eifi1/ui-kit/testing` — helpers an app runs from its OWN test suite (0.33).
+//
+// Not part of the main barrel: nothing here renders, and an app's production bundle has
+// no business carrying it. Browser-safe like the rest of the kit (no `node:fs`): each
+// helper takes texts, so an app collects them with `import.meta.glob` or `node:fs`, as
+// its setup allows. The first content is the guard against undeclared CSS custom
+// properties (docs/colour-roles-harmonization.md §8).
+export {
+  KIT_CSS_VARIABLES,
+  declaredCustomProperties,
+  undeclaredCssVariables,
+  type UndeclaredCssVariablesOptions,
+} from "./css-variables";