pixelize-design-library 2.4.1-beta.1 → 2.4.1-beta.11

package/dist/Theme/tokens/builders/statusTone.d.ts

@@ -0,0 +1,35 @@
+import type { ColorScale, ResolvedColorMode } from "../types";
+export type StatusTone = {
+    /** Chip fill. */
+    bg: string;
+    /** Label ink, guaranteed >= 4.5:1 on `bg`. */
+    fg: string;
+    /** Chip outline, guaranteed >= 3:1 on `bg`. */
+    border: string;
+};
+/**
+ * Status chips (open / in-progress / resolved …) were authored as `X.500` text on an `X.100`
+ * tint, which measures 3.3-4.4:1 — under the 4.5:1 body-text bar in BOTH modes. The ink is
+ * resolved from the scale's own hue instead of pinned, so every brand and both modes land on the
+ * lightest ink that still passes rather than a hand-copied hex that goes stale.
+ *
+ * `reverseScale` flips the utility ramps in dark, so `X.100` is already a dark tint there and the
+ * ink walks lighter instead of darker — hence the mode argument.
+ */
+export declare function resolveStatusTone(scale: ColorScale, mode: ResolvedColorMode): StatusTone;
+/**
+ * Avatar initials are drawn white on a generated fill. The seed hues in use measured 1.92:1
+ * (`#eab308`), 2.54:1 (`#10b981`) and 3.76:1 (`#ef4444`) — failing in light mode too, not just
+ * dark. Darkening the fill keeps the intended hue and the white-initials look while clearing AA.
+ */
+export declare function resolveAvatarFill(hex: string, target?: number): string;
+/**
+ * Hue set for generated avatars. Values are seeds, not final fills — always pass them through
+ * `resolveAvatarFill` so the white initials stay legible.
+ */
+export declare const AVATAR_SEEDS: readonly ["#ef4444", "#f97316", "#eab308", "#22c55e", "#10b981", "#06b6d4", "#3b82f6", "#8b5cf6", "#ec4899"];
+/** Stable per-name avatar fill: same name always yields the same accessible colour. */
+export declare function avatarFillFor(seedText: string): string;
+/** True when `fg` clears the body-text bar on `bg` — exported for consumer assertions. */
+export declare const meetsBodyText: (fg: string, bg: string) => boolean;
+//# sourceMappingURL=statusTone.d.ts.map

package/dist/Theme/tokens/builders/statusTone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statusTone.d.ts","sourceRoot":"","sources":["../../../../src/Theme/tokens/builders/statusTone.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE9D,MAAM,MAAM,UAAU,GAAG;IACvB,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAUxF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAuB,GAAG,MAAM,CAGtF;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,8GAUf,CAAC;AAEX,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED,0FAA0F;AAC1F,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,EAAE,IAAI,MAAM,KAAG,OACd,CAAC"}

package/dist/Theme/tokens/builders/statusTone.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.meetsBodyText = exports.AVATAR_SEEDS = void 0;
+exports.resolveStatusTone = resolveStatusTone;
+exports.resolveAvatarFill = resolveAvatarFill;
+exports.avatarFillFor = avatarFillFor;
+const color_1 = require("./color");
+const accentText_1 = require("./accentText");
+const outlineRung_1 = require("./outlineRung");
+/**
+ * Status chips (open / in-progress / resolved …) were authored as `X.500` text on an `X.100`
+ * tint, which measures 3.3-4.4:1 — under the 4.5:1 body-text bar in BOTH modes. The ink is
+ * resolved from the scale's own hue instead of pinned, so every brand and both modes land on the
+ * lightest ink that still passes rather than a hand-copied hex that goes stale.
+ *
+ * `reverseScale` flips the utility ramps in dark, so `X.100` is already a dark tint there and the
+ * ink walks lighter instead of darker — hence the mode argument.
+ */
+function resolveStatusTone(scale, mode) {
+    const bg = scale[100];
+    const inkSeed = mode === "dark" ? scale[300] : scale[700];
+    const edgeSeed = mode === "dark" ? scale[400] : scale[300];
+    return {
+        bg,
+        fg: (0, outlineRung_1.liftToContrast)(inkSeed, bg, mode, accentText_1.AA_NORMAL_TEXT),
+        border: (0, outlineRung_1.liftToContrast)(edgeSeed, bg, mode, outlineRung_1.AA_NON_TEXT),
+    };
+}
+/**
+ * Avatar initials are drawn white on a generated fill. The seed hues in use measured 1.92:1
+ * (`#eab308`), 2.54:1 (`#10b981`) and 3.76:1 (`#ef4444`) — failing in light mode too, not just
+ * dark. Darkening the fill keeps the intended hue and the white-initials look while clearing AA.
+ */
+function resolveAvatarFill(hex, target = accentText_1.AA_NORMAL_TEXT) {
+    // "light" walks downward in lightness — i.e. darken until white ink clears the bar.
+    return (0, outlineRung_1.liftToContrast)(hex, "#ffffff", "light", target);
+}
+/**
+ * Hue set for generated avatars. Values are seeds, not final fills — always pass them through
+ * `resolveAvatarFill` so the white initials stay legible.
+ */
+exports.AVATAR_SEEDS = [
+    "#ef4444",
+    "#f97316",
+    "#eab308",
+    "#22c55e",
+    "#10b981",
+    "#06b6d4",
+    "#3b82f6",
+    "#8b5cf6",
+    "#ec4899",
+];
+/** Stable per-name avatar fill: same name always yields the same accessible colour. */
+function avatarFillFor(seedText) {
+    let hash = 0;
+    for (let i = 0; i < seedText.length; i++) {
+        hash = (hash * 31 + seedText.charCodeAt(i)) >>> 0;
+    }
+    return resolveAvatarFill(exports.AVATAR_SEEDS[hash % exports.AVATAR_SEEDS.length]);
+}
+/** True when `fg` clears the body-text bar on `bg` — exported for consumer assertions. */
+const meetsBodyText = (fg, bg) => (0, color_1.contrastRatio)(fg, bg) >= accentText_1.AA_NORMAL_TEXT;
+exports.meetsBodyText = meetsBodyText;

package/dist/Utils/accountHandoff.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cross-app "Account handoff": deep-link from a product app (CRM, Tickets, HRMS)
+ * into the Account app carrying the token, so the user lands signed in. Consuming
+ * apps once copy-pasted this per repo; it lives here so they share one contract.
+ *
+ * Query-param contract (must stay in sync across every caller):
+ * `sourceApp`, `returnUrl`, `orgId`, `api_key` (+ `userId` on the users page).
+ *
+ * The library is pre-bundled, so it must not read `import.meta.env` — that would
+ * bake in the library's own build env. Env-derived values are injected as config.
+ */
+export declare function isAllowedReturnUrl(url: string): boolean;
+export type ResolveReturnUrlOptions = {
+    /** App-specific fallback (e.g. its own origin) used when the param is missing/disallowed. */
+    defaultReturnUrl?: string;
+};
+/**
+ * Receiver side (Account). Returns the `returnUrl` param only when it passes the
+ * allowlist, else the caller's `defaultReturnUrl` when that is allowed, else null.
+ * `fallbackOrgId` is accepted for caller symmetry; the app owns any org-derived
+ * fallback via `opts.defaultReturnUrl`.
+ */
+export declare function resolveReturnUrl(searchParams: URLSearchParams, fallbackOrgId?: number | string | null, opts?: ResolveReturnUrlOptions): string | null;
+export type AccountHandoffConfig = {
+    sourceApp: string;
+    /** The app's `VITE_ACCOUNT_UI` (may be empty). */
+    accountUiBase?: string;
+    /** This app's dev port, e.g. "3002". */
+    appLocalPort: string;
+    /** Account's dev port. Defaults to "3000". */
+    accountLocalPort?: string;
+    /** The app's `VITE_FORCE_REMOTE_ACCOUNT_UI === "true"`. */
+    forceRemote?: boolean;
+    /** Where Account returns the user to. Defaults to this app's own origin. */
+    buildReturnUrl?: (orgId?: number | string | null) => string;
+};
+export type AccountHandoffLinkOptions = {
+    sourceApp?: string;
+    returnUrl?: string;
+    orgId?: number | string | null;
+    token?: string | null;
+};
+export type AccountHandoffUsersOptions = AccountHandoffLinkOptions & {
+    userId?: number | string | null;
+};
+export type AccountHandoff = {
+    resolveAccountUiBase: () => string;
+    buildUsersPageUrl: (options?: AccountHandoffUsersOptions) => string;
+    navigateToUsersPage: (options?: AccountHandoffUsersOptions) => void;
+    buildOrganizationPageUrl: (options?: AccountHandoffLinkOptions) => string;
+    navigateToOrganizationPage: (options?: AccountHandoffLinkOptions) => void;
+};
+export declare function createAccountHandoff(config: AccountHandoffConfig): AccountHandoff;
+//# sourceMappingURL=accountHandoff.d.ts.map

package/dist/Utils/accountHandoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountHandoff.d.ts","sourceRoot":"","sources":["../../src/Utils/accountHandoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAYvD;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,eAAe,EAC7B,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EACtC,IAAI,CAAC,EAAE,uBAAuB,GAC7B,MAAM,GAAG,IAAI,CAcf;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,MAAM,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,yBAAyB,GAAG;IACnE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,oBAAoB,EAAE,MAAM,MAAM,CAAC;IACnC,iBAAiB,EAAE,CAAC,OAAO,CAAC,EAAE,0BAA0B,KAAK,MAAM,CAAC;IACpE,mBAAmB,EAAE,CAAC,OAAO,CAAC,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACpE,wBAAwB,EAAE,CAAC,OAAO,CAAC,EAAE,yBAAyB,KAAK,MAAM,CAAC;IAC1E,0BAA0B,EAAE,CAAC,OAAO,CAAC,EAAE,yBAAyB,KAAK,IAAI,CAAC;CAC3E,CAAC;AAaF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAyGjF"}

package/dist/Utils/accountHandoff.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Cross-app "Account handoff": deep-link from a product app (CRM, Tickets, HRMS)
+ * into the Account app carrying the token, so the user lands signed in. Consuming
+ * apps once copy-pasted this per repo; it lives here so they share one contract.
+ *
+ * Query-param contract (must stay in sync across every caller):
+ * `sourceApp`, `returnUrl`, `orgId`, `api_key` (+ `userId` on the users page).
+ *
+ * The library is pre-bundled, so it must not read `import.meta.env` — that would
+ * bake in the library's own build env. Env-derived values are injected as config.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAllowedReturnUrl = isAllowedReturnUrl;
+exports.resolveReturnUrl = resolveReturnUrl;
+exports.createAccountHandoff = createAccountHandoff;
+const ALLOWED_RETURN_HOST_PATTERNS = [
+    /^localhost$/,
+    /^127\.0\.0\.1$/,
+    /\.pixelizetech\.com$/i,
+];
+const DEFAULT_ACCOUNT_PORT = "3000";
+function isAllowedReturnUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+            return false;
+        }
+        return ALLOWED_RETURN_HOST_PATTERNS.some((pattern) => pattern.test(parsed.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Receiver side (Account). Returns the `returnUrl` param only when it passes the
+ * allowlist, else the caller's `defaultReturnUrl` when that is allowed, else null.
+ * `fallbackOrgId` is accepted for caller symmetry; the app owns any org-derived
+ * fallback via `opts.defaultReturnUrl`.
+ */
+function resolveReturnUrl(searchParams, fallbackOrgId, opts) {
+    void fallbackOrgId;
+    const returnUrl = searchParams.get("returnUrl");
+    if (returnUrl && isAllowedReturnUrl(returnUrl)) {
+        return returnUrl;
+    }
+    const fallback = opts === null || opts === void 0 ? void 0 : opts.defaultReturnUrl;
+    if (fallback && isAllowedReturnUrl(fallback)) {
+        return fallback;
+    }
+    return null;
+}
+function isLocalDevHost(hostname) {
+    return /^(localhost|127\.0\.0\.1)$/i.test(hostname);
+}
+function currentPagePort() {
+    return (window.location.port ||
+        (window.location.protocol === "https:" ? "443" : "80"));
+}
+function createAccountHandoff(config) {
+    var _a;
+    /** Account origin for local dev. Never this app's own port — a same-origin URL would keep the user here. */
+    function localAccountBase(hostname) {
+        const pagePort = currentPagePort();
+        let port = String(config.accountLocalPort || DEFAULT_ACCOUNT_PORT).trim() ||
+            DEFAULT_ACCOUNT_PORT;
+        if (port === pagePort || port === config.appLocalPort) {
+            port = DEFAULT_ACCOUNT_PORT;
+        }
+        if (port === pagePort) {
+            port = pagePort === "3000" ? "3001" : DEFAULT_ACCOUNT_PORT;
+        }
+        return `http://${hostname}:${port}`;
+    }
+    function resolveAccountUiBase() {
+        const hostname = window.location.hostname;
+        const configured = String(config.accountUiBase || "")
+            .trim()
+            .replace(/\/$/, "");
+        if (!config.forceRemote && isLocalDevHost(hostname)) {
+            return localAccountBase(hostname);
+        }
+        if (!configured) {
+            return localAccountBase(hostname);
+        }
+        try {
+            if (new URL(configured).origin === window.location.origin) {
+                return localAccountBase(hostname);
+            }
+        }
+        catch {
+            return localAccountBase(hostname);
+        }
+        return configured;
+    }
+    const buildReturnUrl = (_a = config.buildReturnUrl) !== null && _a !== void 0 ? _a : (() => window.location.origin.replace(/\/$/, ""));
+    function buildParams(options) {
+        var _a, _b;
+        const params = new URLSearchParams();
+        params.set("sourceApp", (_a = options.sourceApp) !== null && _a !== void 0 ? _a : config.sourceApp);
+        const returnUrl = (_b = options.returnUrl) !== null && _b !== void 0 ? _b : buildReturnUrl(options.orgId);
+        if (returnUrl && isAllowedReturnUrl(returnUrl)) {
+            params.set("returnUrl", returnUrl);
+        }
+        if (options.orgId) {
+            params.set("orgId", String(options.orgId));
+        }
+        if (options.token) {
+            params.set("api_key", options.token);
+        }
+        return params;
+    }
+    function buildUsersPageUrl(options = {}) {
+        const params = buildParams(options);
+        if (options.userId != null && options.userId !== "") {
+            params.set("userId", String(options.userId));
+        }
+        return `${resolveAccountUiBase()}/users?${params.toString()}`;
+    }
+    function navigateToUsersPage(options = {}) {
+        const url = buildUsersPageUrl(options);
+        if (!/^https?:\/\//i.test(url)) {
+            return;
+        }
+        window.location.assign(url);
+    }
+    function buildOrganizationPageUrl(options = {}) {
+        return `${resolveAccountUiBase()}/organization?${buildParams(options).toString()}`;
+    }
+    function navigateToOrganizationPage(options = {}) {
+        const url = buildOrganizationPageUrl(options);
+        if (!/^https?:\/\//i.test(url)) {
+            return;
+        }
+        window.location.assign(url);
+    }
+    return {
+        resolveAccountUiBase,
+        buildUsersPageUrl,
+        navigateToUsersPage,
+        buildOrganizationPageUrl,
+        navigateToOrganizationPage,
+    };
+}

package/dist/Utils/planBadge.d.ts

@@ -0,0 +1,39 @@
+import { PlanPillTone } from "../Components/PlanPill/PlanPillProps";
+import { PlanExpiryInput } from "./planExpiry";
+export type PlanBadgeInput = {
+    /**
+     * Whether the org is on any plan at all. Defaults to true, so a caller that
+     * only knows the plan's name/code can omit it.
+     */
+    hasPlan?: boolean;
+    planName?: string | null;
+    /** Plan code, e.g. `"free"`. Used to detect the free plan when `isFreePlan` is omitted. */
+    planCode?: string | null;
+    /** Legacy numeric plan id, where `1` is the free plan. */
+    planId?: number | null;
+    /** Explicit free-plan flag. Overrides detection from `planCode`/`planId`/`planName`. */
+    isFreePlan?: boolean;
+    isTrial?: boolean;
+    isExpired?: boolean;
+    expiryDate?: PlanExpiryInput;
+    /** The badge is hidden entirely for anyone who cannot act on it. */
+    canManageBilling?: boolean;
+    /** Injectable clock, for tests. */
+    now?: Date;
+};
+export type PlanBadgeResult = {
+    visible: boolean;
+    label: string;
+    mobileLabel: string;
+    subtitle: string;
+    tone: PlanPillTone;
+};
+/**
+ * Turns an org's plan state into the label, urgency tone and inset-chip text for
+ * a `PlanPill` — the "Upgrade your plan" badge in an app's top bar.
+ *
+ * Copy and thresholds are centralized here so every app shows the same badge for
+ * the same org.
+ */
+export declare function resolvePlanBadge(input: PlanBadgeInput): PlanBadgeResult;
+//# sourceMappingURL=planBadge.d.ts.map

package/dist/Utils/planBadge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planBadge.d.ts","sourceRoot":"","sources":["../../src/Utils/planBadge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EACL,eAAe,EAGhB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wFAAwF;IACxF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mCAAmC;IACnC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;CACpB,CAAC;AA0DF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAuDvE"}

package/dist/Utils/planBadge.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePlanBadge = resolvePlanBadge;
+const planExpiry_1 = require("./planExpiry");
+const UPGRADE_LABEL = "Upgrade your plan";
+const UPGRADE_MOBILE_LABEL = "Upgrade";
+const EXPIRED_MOBILE_LABEL = "Expired";
+const TRIAL_LABEL = "Trial";
+const GENERIC_PLAN_NAME = "Plan";
+const LEGACY_FREE_PLAN_ID = 1;
+const TRIAL_DANGER_DAYS = 3;
+const ACTIVE_WARNING_DAYS = 15;
+const HIDDEN = {
+    visible: false,
+    label: "",
+    mobileLabel: "",
+    subtitle: "",
+    tone: "normal",
+};
+const upgrade = (subtitle, tone = "normal") => ({
+    visible: true,
+    label: UPGRADE_LABEL,
+    mobileLabel: UPGRADE_MOBILE_LABEL,
+    subtitle,
+    tone,
+});
+const normalize = (value) => String(value !== null && value !== void 0 ? value : "")
+    .trim()
+    .toLowerCase();
+function isFreePlan(input, planName) {
+    if (input.isFreePlan !== undefined)
+        return input.isFreePlan;
+    if (normalize(input.planCode) === "free")
+        return true;
+    if (input.planId !== null && input.planId !== undefined) {
+        return Number(input.planId) === LEGACY_FREE_PLAN_ID;
+    }
+    return normalize(planName) === "free";
+}
+/** Whole days from today to the expiry day; null when there is no usable date. */
+function daysUntil(expiryDate, now) {
+    if (expiryDate === null || expiryDate === undefined || expiryDate === "") {
+        return null;
+    }
+    const expiry = expiryDate instanceof Date ? expiryDate : new Date(expiryDate);
+    if (isNaN(expiry.getTime()))
+        return null;
+    const startOfDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate());
+    return Math.round((startOfDay(expiry).getTime() - startOfDay(now).getTime()) / 86400000);
+}
+/**
+ * Turns an org's plan state into the label, urgency tone and inset-chip text for
+ * a `PlanPill` — the "Upgrade your plan" badge in an app's top bar.
+ *
+ * Copy and thresholds are centralized here so every app shows the same badge for
+ * the same org.
+ */
+function resolvePlanBadge(input) {
+    var _a, _b;
+    if (!input.canManageBilling)
+        return HIDDEN;
+    const now = (_a = input.now) !== null && _a !== void 0 ? _a : new Date();
+    const planName = ((_b = input.planName) === null || _b === void 0 ? void 0 : _b.trim()) || "";
+    const daysLeft = daysUntil(input.expiryDate, now);
+    const remaining = (0, planExpiry_1.formatPlanRemaining)(input.expiryDate, now);
+    const elapsed = (0, planExpiry_1.formatPlanElapsed)(input.expiryDate, now);
+    // Checked before the expiry branch: a lapsed org is downgraded to free, and
+    // "Free expired" is not a state worth shouting about.
+    if (isFreePlan(input, planName))
+        return upgrade("");
+    if (input.isExpired || elapsed !== "") {
+        // "<plan> expired" as the label with the elapsed time in the inset chip —
+        // folding both behind "Upgrade your plan" made the pill wide enough to
+        // crowd the header.
+        return {
+            visible: true,
+            label: `${planName || GENERIC_PLAN_NAME} expired`,
+            mobileLabel: EXPIRED_MOBILE_LABEL,
+            subtitle: elapsed,
+            tone: "danger",
+        };
+    }
+    if (input.hasPlan === false)
+        return upgrade("");
+    if (input.isTrial) {
+        return {
+            visible: true,
+            label: TRIAL_LABEL,
+            mobileLabel: TRIAL_LABEL,
+            subtitle: remaining,
+            tone: daysLeft !== null && daysLeft <= TRIAL_DANGER_DAYS
+                ? "danger"
+                : "warning",
+        };
+    }
+    const tone = daysLeft !== null && daysLeft < ACTIVE_WARNING_DAYS ? "warning" : "normal";
+    // An active paid plan names itself — falling through to "Upgrade your plan"
+    // told users with years remaining that they were on nothing.
+    if (!planName)
+        return upgrade(remaining, tone);
+    return {
+        visible: true,
+        label: planName,
+        mobileLabel: planName,
+        subtitle: remaining,
+        tone,
+    };
+}

package/dist/Utils/planExpiry.d.ts

@@ -0,0 +1,35 @@
+export type PlanExpiryInput = string | number | Date | null | undefined;
+/**
+ * Calendar months + leftover days between two dates.
+ * Anchoring on a real month boundary keeps "1 month" honest across 28/30/31-day
+ * months, so Jan 31 → Feb 28 reads as 28 days rather than a whole month.
+ */
+export declare function splitMonthsAndDays(from: Date, to: Date): {
+    months: number;
+    days: number;
+};
+/**
+ * Time left on a plan, compactly: `"3mo left"` once a whole month remains,
+ * `"18d left"` below that. Intended for `UpgradeButton`'s `subtitle`, so it
+ * stays one short line. Returns `""` when there is no usable date or the plan
+ * has already lapsed — an expired plan is a different message, which the
+ * consuming app owns.
+ */
+export declare function formatPlanExpiry(expiryDate: PlanExpiryInput, now?: Date): string;
+/**
+ * Time left on a plan, to the minute in the final day: `"3mo left"`, `"18d left"`,
+ * then `"23h 45m left"` down to `"1m left"`. `""` once lapsed.
+ *
+ * Differs from `formatPlanExpiry` only in that last day: a calendar-day count
+ * reads as "Expires today" for the whole day, which goes stale next to a live
+ * countdown. Prefer this for a badge that sits on screen; `formatPlanExpiry`
+ * stays the cheaper day-granular option.
+ */
+export declare function formatPlanRemaining(expiryDate: PlanExpiryInput, now?: Date): string;
+/**
+ * How long ago a plan lapsed: `"1h 10m ago"` under a day, `"2d ago"` / `"1mo ago"`
+ * beyond it. `""` while the plan is still live — so a badge can say how stale a
+ * lapse is rather than a bare "expired".
+ */
+export declare function formatPlanElapsed(expiryDate: PlanExpiryInput, now?: Date): string;
+//# sourceMappingURL=planExpiry.d.ts.map

package/dist/Utils/planExpiry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planExpiry.d.ts","sourceRoot":"","sources":["../../src/Utils/planExpiry.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;AAoCxE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,IAAI,GACP;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAOlC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,eAAe,EAC3B,GAAG,CAAC,EAAE,IAAI,GACT,MAAM,CAaR;AAYD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,eAAe,EAC3B,GAAG,CAAC,EAAE,IAAI,GACT,MAAM,CAgBR;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,eAAe,EAC3B,GAAG,CAAC,EAAE,IAAI,GACT,MAAM,CAgBR"}

package/dist/Utils/planExpiry.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitMonthsAndDays = splitMonthsAndDays;
+exports.formatPlanExpiry = formatPlanExpiry;
+exports.formatPlanRemaining = formatPlanRemaining;
+exports.formatPlanElapsed = formatPlanElapsed;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function toDate(value) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+    return isNaN(date.getTime()) ? null : date;
+}
+function startOfDay(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+function addCalendarMonths(date, months) {
+    const lastDayOfTarget = new Date(date.getFullYear(), date.getMonth() + months + 1, 0).getDate();
+    return new Date(date.getFullYear(), date.getMonth() + months, Math.min(date.getDate(), lastDayOfTarget));
+}
+function daysBetween(from, to) {
+    return Math.round((to.getTime() - from.getTime()) / MS_PER_DAY);
+}
+/** Compact units (`2mo`, `5d`) — this reads inside a badge subtitle, where
+ * "2 months 5 days left" wraps. */
+function unit(count, suffix) {
+    return `${count}${suffix}`;
+}
+/**
+ * Calendar months + leftover days between two dates.
+ * Anchoring on a real month boundary keeps "1 month" honest across 28/30/31-day
+ * months, so Jan 31 → Feb 28 reads as 28 days rather than a whole month.
+ */
+function splitMonthsAndDays(from, to) {
+    let months = (to.getFullYear() - from.getFullYear()) * 12 +
+        (to.getMonth() - from.getMonth());
+    if (to.getDate() < from.getDate())
+        months -= 1;
+    if (months < 0)
+        months = 0;
+    return { months, days: daysBetween(addCalendarMonths(from, months), to) };
+}
+/**
+ * Time left on a plan, compactly: `"3mo left"` once a whole month remains,
+ * `"18d left"` below that. Intended for `UpgradeButton`'s `subtitle`, so it
+ * stays one short line. Returns `""` when there is no usable date or the plan
+ * has already lapsed — an expired plan is a different message, which the
+ * consuming app owns.
+ */
+function formatPlanExpiry(expiryDate, now) {
+    const expiry = toDate(expiryDate);
+    if (!expiry)
+        return "";
+    const expiryDay = startOfDay(expiry);
+    const today = startOfDay(now !== null && now !== void 0 ? now : new Date());
+    const daysLeft = daysBetween(today, expiryDay);
+    if (daysLeft < 0)
+        return "";
+    if (daysLeft === 0)
+        return "Expires today";
+    const { months, days } = splitMonthsAndDays(today, expiryDay);
+    return months > 0 ? `${unit(months, "mo")} left` : `${unit(days, "d")} left`;
+}
+/** Never reports `0m`; the final stretch reads `1m`. */
+function formatHoursMinutes(ms, suffix) {
+    const totalMinutes = Math.floor(ms / 60000);
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    return hours > 0
+        ? `${unit(hours, "h")} ${unit(minutes, "m")} ${suffix}`
+        : `${unit(Math.max(minutes, 1), "m")} ${suffix}`;
+}
+/**
+ * Time left on a plan, to the minute in the final day: `"3mo left"`, `"18d left"`,
+ * then `"23h 45m left"` down to `"1m left"`. `""` once lapsed.
+ *
+ * Differs from `formatPlanExpiry` only in that last day: a calendar-day count
+ * reads as "Expires today" for the whole day, which goes stale next to a live
+ * countdown. Prefer this for a badge that sits on screen; `formatPlanExpiry`
+ * stays the cheaper day-granular option.
+ */
+function formatPlanRemaining(expiryDate, now) {
+    const expiry = toDate(expiryDate);
+    if (!expiry)
+        return "";
+    const referenceNow = now !== null && now !== void 0 ? now : new Date();
+    const msLeft = expiry.getTime() - referenceNow.getTime();
+    if (msLeft < 0)
+        return "";
+    if (msLeft < MS_PER_DAY) {
+        return msLeft === 0 ? "Expires today" : formatHoursMinutes(msLeft, "left");
+    }
+    const { months, days } = splitMonthsAndDays(startOfDay(referenceNow), startOfDay(expiry));
+    return months > 0 ? `${unit(months, "mo")} left` : `${unit(days, "d")} left`;
+}
+/**
+ * How long ago a plan lapsed: `"1h 10m ago"` under a day, `"2d ago"` / `"1mo ago"`
+ * beyond it. `""` while the plan is still live — so a badge can say how stale a
+ * lapse is rather than a bare "expired".
+ */
+function formatPlanElapsed(expiryDate, now) {
+    const expiry = toDate(expiryDate);
+    if (!expiry)
+        return "";
+    const referenceNow = now !== null && now !== void 0 ? now : new Date();
+    const msAgo = referenceNow.getTime() - expiry.getTime();
+    if (msAgo <= 0)
+        return "";
+    if (msAgo < MS_PER_DAY)
+        return formatHoursMinutes(msAgo, "ago");
+    const { months, days } = splitMonthsAndDays(startOfDay(expiry), startOfDay(referenceNow));
+    return months > 0
+        ? `${unit(months, "mo")} ago`
+        : `${unit(Math.max(days, 1), "d")} ago`;
+}