@eifi1/ui-kit 0.54.0 → 0.56.0

package/src/billing/provider-page.ts

@@ -1,84 +0,0 @@
-/**
- * The provider's hosted portal in a NEW TAB (0.43, docs/billing-harmonization.md §17):
- * "Payment and invoices", the portal's "Cancel subscription" and the payment-failed
- * banner's "Update payment method" open at the provider while the app stays open where
- * it was. kastlan's `usePortal` (feat/kit-0.42, `72c3177`) is the reference.
- *
- * The checkout is NOT one of them (§17.4): it stays in the same tab, since the page waits
- * for the payer's return (`useCheckoutProcessing`).
- */
-
-/** How the page went: in a tab of its own, or — the browser refused one — in this one. */
-export type ProviderPageWay = "new-tab" | "same-tab";
-
-export interface OpenProviderPageOptions {
-  /** The window to open from and to fall back to. Default the global `window` (a test's
-   *  or an iframe's own). */
-  window?: Window;
-}
-
-/**
- * Opens the provider's page in a new tab, from INSIDE the click: call it in the click
- * handler itself, before any `await` — a `window.open` after one is blocked as a pop-up.
- *
- * 1. opens `about:blank` synchronously and sets its `opener` to `null`, so the provider's
- *    page cannot reach back into the app;
- * 2. awaits `fetchUrl` — the app's `POST /billing/portal` with its target, answering the
- *    `url` (the kit sends no request);
- * 3. points the tab at the URL;
- * 4. on a refusal closes the tab again and rethrows, so the app shows its error;
- * 5. where the browser refused the tab (a pop-up blocker), or it was closed while the
- *    URL was on its way, the app's own page goes there instead.
- *
- *     <SubscriptionActions
- *       onPortal={(target) => {
- *         openProviderPage(() => api.billingPortal({ target }).then((r) => r.url)).catch(showError);
- *       }}
- *       providerName="Paddle"
- *       appName="Kastlan"
- *     />
- *
- * Resolves with the way it went.
- *
- * **The test seam is `options.window`** (docs/tours-harmonization.md §9.5, kk 7): an app's
- * test passes a stub with `open` (returning a fake tab, or `null` for a blocked pop-up)
- * and `location.assign`, instead of patching the global `window`:
- *
- *     const tab = { opener: {}, closed: false, location: { href: "" }, close: vi.fn() };
- *     const win = { open: vi.fn(() => tab), location: { assign: vi.fn() } } as unknown as Window;
- *     await openProviderPage(async () => "https://pay.example/portal", { window: win });
- *     expect(tab.location.href).toBe("https://pay.example/portal");
- */
-export async function openProviderPage(
-  fetchUrl: () => Promise<string>,
-  options: OpenProviderPageOptions = {},
-): Promise<ProviderPageWay> {
-  const win = options.window ?? window;
-  let tab: Window | null;
-  try {
-    tab = win.open("about:blank", "_blank");
-  } catch {
-    tab = null;
-  }
-  if (tab) {
-    try {
-      // The provider's page must not reach back into the app.
-      tab.opener = null;
-    } catch {
-      /* a browser that guards `opener`: the tab is still ours to point */
-    }
-  }
-  let url: string;
-  try {
-    url = await fetchUrl();
-  } catch (error) {
-    tab?.close();
-    throw error;
-  }
-  if (tab && !tab.closed) {
-    tab.location.href = url;
-    return "new-tab";
-  }
-  win.location.assign(url);
-  return "same-tab";
-}

package/src/billing/subscription-actions.tsx

@@ -1,247 +0,0 @@
-import type { ComponentPropsWithRef, ReactNode } from "react";
-import { ExternalLink } from "lucide-react";
-
-import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
-import type { LabelOverride } from "../i18n/kit-labels";
-import { cn } from "../lib/cn";
-import { Button } from "../components/button";
-import { useBillingLabels } from "./billing-labels";
-import type { BillingLabels } from "./billing-labels";
-import type { BillingPortalAccess, PortalTarget } from "./billing-overview";
-import type { CancelRequested } from "./cancel-request";
-
-/** The portal action's mark (§17.3): the external-link glyph after the words, and "(opens
- *  in a new tab)" for a reader — on a link, `Button`'s `external` says the latter. */
-export function ExternalMark({ reader }: { reader?: string }) {
-  return (
-    <>
-      <ExternalLink aria-hidden data-external="" className="size-4 shrink-0 rtl:-scale-x-100" />
-      {reader !== undefined && (
-        <>
-          {" "}
-          <span className="sr-only">({reader})</span>
-        </>
-      )}
-    </>
-  );
-}
-
-export interface SubscriptionActionsProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
-  /** "Payment and invoices", as a link — or {@link onManage}. Without either, none. */
-  manageHref?: string;
-  /** "Payment and invoices", as the app's call: `POST /billing/portal` with
-   *  `{target: "overview"}`, then off to its `url` (§4, §14.5). The kit sends no
-   *  request. */
-  onManage?: () => void;
-  /** "Cancel subscription", as a link — or {@link onCancel}. Without either, none. */
-  cancelHref?: string;
-  /** "Cancel subscription", as the app's call: the portal again, with `{target:
-   *  "cancel"}` — its cancel link, where the provider's cancel and withdrawal functions
-   *  are (§12.26, §14.5). Not the overview. */
-  onCancel?: () => void;
-  /**
-   * Both, as one call that says where to ({@link PortalTarget}, the body of
-   * `POST /billing/portal`): `"overview"` for "Payment and invoices",
-   * `"cancel"` for "Cancel subscription" — so the target can't be mixed up (kastlan's
-   * cancel opened the overview). {@link onManage} and {@link onCancel} win over it.
-   */
-  onPortal?: (target: PortalTarget) => void;
-  /**
-   * The overview's `at_provider` (§14.5): whether the payer has reached the provider.
-   * `false`: no customer there yet, so nothing to open — a caption (`notAtProvider`)
-   * stands in place of both actions. `true`: both show, WHATEVER the status or source —
-   * a payer who bought under a grant keeps the way to the invoices and to "Cancel"
-   * (§12.26). Default true (0.32's behaviour).
-   */
-  atProvider?: boolean;
-  /**
-   * 0.42 (§16.2, server-kit 0.14): the overview's `portal`. `"buyer_only"` — the row has
-   * a buyer and the viewer isn't them, so the portal would answer `403
-   * billing_portal_buyer_only`: "Payment and invoices" becomes a caption naming the buyer
-   * (`buyerHolds`, no button), and "Cancel subscription" calls {@link onCancelInApp}
-   * (no portal at all — `cancelHref`, `onCancel` and `onPortal` are not used). `"open"`
-   * (default): as before.
-   */
-  portal?: BillingPortalAccess;
-  /** 0.42: the overview's `buyer_name`, for the caption under `"buyer_only"`. Empty: "…with
-   *  the admin who bought the subscription". */
-  buyerName?: string | null;
-  /**
-   * 0.42 (§16.2 decision 2): "Cancel subscription" in the app — open
-   * `CancelSubscriptionConfirm`, whose Confirm is `POST /billing/cancel`. The cancel under
-   * `"buyer_only"`. Under `"open"` it is the last resort, used only when no portal cancel
-   * (`cancelHref`, `onCancel`, `onPortal`) is given — a person-payer app that mounts the
-   * route and not the portal's cancel.
-   */
-  onCancelInApp?: () => void;
-  /** 0.42 (§16.7 C): the overview's `cancel_at_period_end` — a cancel is scheduled. With
-   *  {@link onResume}, "Keep subscription" takes the cancel's place. */
-  cancelAtPeriodEnd?: boolean;
-  /** 0.42 (§16.7 C): "Keep subscription", the app's `POST /billing/resume` — shown in
-   *  the cancel's place while {@link cancelAtPeriodEnd} is true. Without it, the cancel
-   *  stays as before. */
-  onResume?: () => void;
-  /**
-   * 0.43 (kastlan `18bf4c0`): what was asked in the app and the overview does not show
-   * yet — `useCancelRequest().view(row).requested`. `"cancel"`: shown as scheduled ("Keep
-   * subscription" with {@link onResume}; without it, no second "Cancel subscription").
-   * `"resume"`: shown as not scheduled. `null` (default): {@link cancelAtPeriodEnd} says.
-   */
-  cancelRequested?: CancelRequested;
-  /**
-   * 0.43 (§17): the portal opens in a NEW TAB — the app's handler calls
-   * `openProviderPage` — so its actions carry the external-link mark, a link opens with
-   * `target="_blank"`, and the `portalOpensNewTab` note shows under them. Default true;
-   * `false` for an app whose portal still opens in the same tab.
-   */
-  portalNewTab?: boolean;
-  /** 0.43: the provider's name in the note. Default `"Paddle"` (§2 decision 16). */
-  providerName?: string;
-  /** 0.43: the app's name in the note ("Kastlan stays open here"). Without it, "this page
-   *  stays open". */
-  appName?: string;
-  /** Which one is under way: its spinner, no second press. `"resume"` since 0.42. */
-  pending?: "manage" | "cancel" | "resume" | null;
-  /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
-  labels?: LabelOverride<BillingLabels>;
-}
-
-/**
- * The two ways to the provider's hosted portal on the subscription page
- * (docs/billing-harmonization.md §2.8, §7, §12.26): "Payment and invoices" — the payment
- * method and the invoices live there, never in the app — and a VISIBLE "Cancel
- * subscription". Consumer law wants the second in plain sight: Germany's cancellation
- * button (§312k BGB) and the EU withdrawal function (Directive (EU) 2023/2673, from
- * 19 June 2026) are in the portal, and the app's page must not hide the way there behind
- * "manage".
- *
- * Neither takes the write lock: a read-only payer must be able to pay, leave or cancel
- * (§3.3).
- *
- * Before the payer has reached the provider (`atProvider={false}`, a trial without a
- * card, a beta) there is no portal to open: the part says so in a caption instead of
- * offering two buttons that could only end in `409 billing_not_at_provider`.
- *
- * 0.42 (§16): where the company's buyer is another admin (`portal="buyer_only"`), the
- * portal stays the buyer's — "Payment and invoices" is a caption that names them, and
- * "Cancel subscription" is the in-app cancel (`onCancelInApp`). While a cancel is
- * scheduled (`cancelAtPeriodEnd`) and `onResume` is given, "Keep subscription" stands in
- * the cancel's place, whoever the viewer is.
- *
- * 0.43 (§17): the portal opens in a new tab (`openProviderPage` in the app's handler):
- * its actions carry the external-link mark, and a muted note says so — "Payment and
- * invoices open at {provider} in a new tab; {app} stays open here." The in-app cancel and
- * "Keep subscription" stay unmarked. After an in-app cancel or resume, `cancelRequested`
- * (`useCancelRequest`) shows what was asked until the provider's webhook lands.
- */
-export function SubscriptionActions({
-  manageHref,
-  onManage,
-  cancelHref,
-  onCancel,
-  onPortal,
-  atProvider = true,
-  portal = "open",
-  buyerName,
-  onCancelInApp,
-  cancelAtPeriodEnd = false,
-  onResume,
-  cancelRequested = null,
-  portalNewTab = true,
-  providerName = "Paddle",
-  appName,
-  pending,
-  labels: labelsProp,
-  className,
-  ...rest
-}: SubscriptionActionsProps) {
-  const labels = useBillingLabels(labelsProp);
-  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
-  if (!atProvider) {
-    return (
-      <div {...rest} data-at-provider="false" className={cn("text-sm text-muted", className)}>
-        <p>{labels.notAtProvider}</p>
-      </div>
-    );
-  }
-  const buyerOnly = portal === "buyer_only";
-  const manageCall = onManage ?? (onPortal ? () => onPortal("overview") : undefined);
-  const portalCancel = onCancel ?? (onPortal ? () => onPortal("cancel") : undefined);
-  // Under "buyer_only" the in-app cancel only; under "open" the portal's first, the
-  // in-app cancel only where no way to the portal's is given.
-  const cancelCall = buyerOnly
-    ? onCancelInApp
-    : (portalCancel ?? (cancelHref === undefined ? onCancelInApp : undefined));
-  // 0.43: what was asked in the app wins over the row until the row moves.
-  const scheduled = cancelRequested === "cancel" ? true : cancelRequested === "resume" ? false : cancelAtPeriodEnd;
-  // 0.43 (§17): the portal's actions are marked, a link opens a tab of its own.
-  const newTab = portalNewTab && !buyerOnly;
-  const words = (text: string, external: boolean, link: boolean): ReactNode =>
-    external ? (
-      <>
-        {text}
-        <ExternalMark reader={link ? undefined : common.opensInNewTab} />
-      </>
-    ) : (
-      text
-    );
-  const portalCancelShown = !buyerOnly && (cancelHref !== undefined || portalCancel !== undefined);
-  const manage = buyerOnly ? (
-    <p className="basis-full text-sm text-muted" data-buyer-holds="">
-      {labels.buyerHolds(buyerName || undefined)}
-    </p>
-  ) : manageHref !== undefined ? (
-    <Button href={manageHref} variant="secondary" external={newTab || undefined} data-portal-action="manage">
-      {words(labels.manage, newTab, true)}
-    </Button>
-  ) : manageCall !== undefined ? (
-    <Button
-      type="button"
-      variant="secondary"
-      onClick={manageCall}
-      pending={pending === "manage"}
-      className={newTab ? "relative" : undefined}
-      data-portal-action="manage"
-    >
-      {words(labels.manage, newTab, false)}
-    </Button>
-  ) : null;
-  const cancel =
-    scheduled && onResume !== undefined ? (
-      <Button type="button" variant="link" onClick={onResume} pending={pending === "resume"} data-keep-subscription="">
-        {labels.keepSubscription}
-      </Button>
-    ) : cancelRequested === "cancel" ? null : cancelHref !== undefined && !buyerOnly ? (
-      <Button href={cancelHref} variant="link" tone="danger" external={newTab || undefined} data-portal-action="cancel">
-        {words(labels.cancel, newTab, true)}
-      </Button>
-    ) : cancelCall !== undefined ? (
-      <Button
-        type="button"
-        variant="link"
-        tone="danger"
-        onClick={cancelCall}
-        pending={pending === "cancel"}
-        className={newTab && portalCancelShown ? "relative" : undefined}
-        data-portal-action={portalCancelShown ? "cancel" : undefined}
-      >
-        {words(labels.cancel, newTab && portalCancelShown, false)}
-      </Button>
-    ) : null;
-  if (!manage && !cancel) return null;
-  // The note while a way to the portal shows: "Payment and invoices open at Paddle in a
-  // new tab; Kastlan stays open here."
-  const portalShown =
-    !buyerOnly && (manage !== null || (cancel !== null && portalCancelShown && !(scheduled && onResume)));
-  return (
-    <div {...rest} className={cn("flex flex-wrap items-center gap-x-4 gap-y-2", className)}>
-      {manage}
-      {cancel}
-      {newTab && portalShown && (
-        <p className="basis-full text-sm text-muted" data-portal-note="">
-          {labels.portalOpensNewTab(providerName, appName || undefined)}
-        </p>
-      )}
-    </div>
-  );
-}

package/src/billing/subscription-status-chip.tsx

@@ -1,95 +0,0 @@
-import type { ReactNode } from "react";
-
-import type { LabelOverride } from "../i18n/kit-labels";
-import { Chip } from "../components/chip";
-import type { ChipShape, ChipSize, ChipTone, ChipVariant } from "../components/chip";
-import { useBillingLabels } from "./billing-labels";
-import type { BillingLabels, SubscriptionStatus } from "./billing-labels";
-
-/**
- * The tone of each status (docs/billing-harmonization.md §3.2, §3.3). The tone follows
- * the STANDING, so a roster reads at a glance who can write:
- *
- * - `active` green: paid, in good standing;
- * - `trialing` blue (info): in good standing until `trial_ends_at`, nothing wrong;
- * - `past_due` amber: a payment failed, still in good standing while the provider retries;
- * - `expired` red: out of good standing — read-only until a plan is chosen;
- * - `canceled` grey: the payer's own choice, nothing to warn about;
- * - `comped` purple, a hue rather than a tone: free by grant — neither paid nor in trouble,
- *   only different from both.
- */
-export const SUBSCRIPTION_STATUS_TONES: Readonly<Record<SubscriptionStatus, ChipTone>> = Object.freeze({
-  trialing: "info",
-  active: "success",
-  past_due: "warning",
-  canceled: "neutral",
-  expired: "danger",
-  comped: "purple",
-});
-
-export interface SubscriptionStatusChipProps {
-  /**
-   * The row's `status` as the API sends it (§3.2). A value the kit does not know yet is
-   * shown as itself, in `neutral` — an unknown status is still a fact an operator should
-   * see. `null` / `undefined` renders nothing.
-   */
-  status: SubscriptionStatus | (string & {}) | null | undefined;
-  /** Over {@link SUBSCRIPTION_STATUS_TONES}. */
-  tone?: ChipTone;
-  /** Over the status's word, for an app whose word is its own. */
-  children?: ReactNode;
-  /** Default `sm` (a roster's `extra` column, §6). */
-  size?: ChipSize;
-  /** Default `soft`. */
-  variant?: ChipVariant;
-  /** Default `square`, the status tag of `AccountStateChip`. */
-  shape?: ChipShape;
-  /** Default true, as `AccountStateChip`. */
-  caps?: boolean;
-  className?: string;
-  /** Prop > `<UiKitProvider labels={{ billing: { status } }}>` > English. */
-  labels?: LabelOverride<BillingLabels>;
-  [key: `data-${string}`]: string | number | boolean | undefined;
-}
-
-// Own keys only: `"toString" in {}` is true.
-const isKnown = (value: string): value is SubscriptionStatus =>
-  Object.prototype.hasOwnProperty.call(SUBSCRIPTION_STATUS_TONES, value);
-
-/**
- * A subscription's status as a chip, in the kit's words and tones (§6: the operator's
- * roster shows the plan and the standing; §7: the subscription page). ALWAYS A WORD, never
- * colour alone: "Trial", "Active", "Payment overdue", "Cancelled", "Expired",
- * "Complimentary" — the tone repeats what the word says. Carries `data-status` with the
- * key, for a test or a style hook.
- */
-export function SubscriptionStatusChip({
-  status,
-  tone,
-  children,
-  size = "sm",
-  variant,
-  shape = "square",
-  caps = true,
-  className,
-  labels: labelsProp,
-  ...rest
-}: SubscriptionStatusChipProps) {
-  const labels = useBillingLabels(labelsProp);
-  if (status === null || status === undefined || status === "") return null;
-  const known = isKnown(status);
-  return (
-    <Chip
-      {...rest}
-      data-status={status}
-      tone={tone ?? (known ? SUBSCRIPTION_STATUS_TONES[status] : "neutral")}
-      size={size}
-      variant={variant}
-      shape={shape}
-      caps={caps}
-      className={className}
-    >
-      {children ?? (known ? labels.status[status] : status)}
-    </Chip>
-  );
-}

package/src/chart.ts

@@ -1,103 +0,0 @@
-// `@eifi1/ui-kit/chart` — the chart shell and its colour system.
-//
-// A re-slicing of what the main barrel already exports, not a new API. It exists so a
-// consumer can reach the chart kit WITHOUT the barrel: `import("@eifi1/ui-kit/chart")`
-// is a chunk of its own (50.4 KB min, 19.9 KB gzip at 0.51.6, refactor audit 2026-10-30
-// MOD-7; it was 31KB when this was written), where the same lazy import through the barrel
-// pulls the barrel, because a dynamic import of it cannot be tree-shaken down to one member.
-//
-// It is about chunk size, not about the peer: `recharts` is a REQUIRED peer (since 0.5.0),
-// because the main barrel re-exports everything here too, so `import { Button } from
-// "@eifi1/ui-kit"` reaches recharts as well (packaging-contract.test.ts asserts it).
-export * from "./components/chart";
-// Named, not `*`, for chart-palette, series-chart and toggle-legend: 0.53 took the slice's
-// share of the 55 names no app reads off the surface (deprecated in 0.52, refactor audit
-// 2026-10-30, API-4) — `EDGE_MIN_CONTRAST`, `resolveTooltipPlacement`, `STROKE_PATTERNS`,
-// which their modules keep for the kit's own use.
-export {
-  PALETTE_SIZE,
-  CVD_ORDER,
-  paletteFor,
-  CHART_COLORS,
-  CHART_ROLES,
-  CHART_MUTED_HEX,
-  chartEdge,
-  PALETTE_HEX,
-  HEATMAP_HEX,
-  lerpHex,
-  textOn,
-  type PaletteForOptions,
-  type HeatStops,
-} from "./theme/chart-palette";
-
-// The tile chart (treemap) the apps share — moved here from keksdose so every consumer
-// derives it from the package rather than from a copy. 0.52: its `treemap` label namespace.
-export * from "./components/treemap";
-export * from "./components/treemap-labels";
-
-// lenkbank's zoomable series chart, its synced x-zoom, the toggle legend and the
-// mirrored-pair axis geometry — moved here so the apps derive them from the package.
-export {
-  AXIS_TICK_WIDTH,
-  AXIS_TITLE_STRIP,
-  anchoredBand,
-  axisBandWidth,
-  mergeSeries,
-  oneAxis,
-  padBand,
-  paddedDomain,
-  seriesKey,
-  soleSeriesColor,
-  visibleSeries,
-  seriesLegendEntries,
-  StaticSeriesChart,
-  SeriesChart,
-  type TimeTickUnit,
-  type SeriesChartAxisBudget,
-  type SeriesSource,
-  type SeriesChartSeries,
-  type SeriesChartType,
-  type SeriesChartPoint,
-  type SeriesChartRow,
-  type SeriesChartXValue,
-  type SeriesChartTickValues,
-  type SeriesChartAxis,
-  type SeriesChartXTick,
-  type SeriesChartX,
-  type SeriesChartTooltipPlacement,
-  type SeriesChartTooltip,
-  type SeriesChartSpan,
-  type SeriesChartTone,
-  type SeriesChartReference,
-  type SeriesChartMarker,
-  type SeriesChartHit,
-  type SeriesChartProps,
-  type SeriesLegendAxes,
-} from "./components/series-chart";
-// 0.32.1 (keksdose's 0.32 report): the height every chart takes, for an app's wrappers.
-export type { ChartHeight } from "./components/chart-height";
-// SharedXZoom and the zoom's types: the public face of ./chart-zoom-core, whose arithmetic
-// stays the kit's (refactor audit 2026-10, API-6b; off the surface in 0.35).
-export * from "./components/chart-zoom";
-// The same binding, named from the module that holds it and the drag layer (recharts): the
-// packaging contract reads this entry's own imports to know which modules may import
-// recharts, so chart-zoom-core has to be one of them (MOD-6).
-export { SharedXZoom } from "./components/chart-zoom-core";
-export {
-  strokeDash,
-  STEP_DASH,
-  toggleHidden,
-  ToggleLegend,
-  StaticLegend,
-  LegendColumn,
-  LegendGroup,
-  type LegendEntry,
-  type ToggleLegendProps,
-  type StaticLegendProps,
-} from "./components/toggle-legend";
-export * from "./components/facing-pair";
-export * from "./components/series-chart-labels";
-
-// The part-to-whole chart (donut / pie) — moved here from kastlan's dashboard and reports.
-export * from "./components/pie-chart";
-export * from "./components/pie-chart-labels";

package/src/components/account-chips-labels.ts

@@ -1,16 +0,0 @@
-// The English words of ./account-chips, in a module with no component code: the English
-// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
-// chunk like the other languages (0.34, KS U8). ./account-chips re-exports them.
-
-import type { AccountStateLabels } from "./account-chips";
-
-export const DEFAULT_ACCOUNT_STATE_LABELS = {
-  active: "Active",
-  inactive: "Inactive",
-  invited: "Invited",
-  registered: "Registered",
-  unverified: "Unverified",
-  passwordChange: "Must change password",
-  deletion: "Deletion requested",
-  deletionOn: (date: string) => `Deletion on ${date}`,
-} satisfies Required<AccountStateLabels>;