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

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

@@ -0,0 +1,55 @@
+import { contrastRatio } from "./color.js";
+import { AA_NORMAL_TEXT } from "./accentText.js";
+import { AA_NON_TEXT, liftToContrast } from "./outlineRung.js";
+/**
+ * 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 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: liftToContrast(inkSeed, bg, AA_NORMAL_TEXT),
+        border: liftToContrast(edgeSeed, bg, 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.
+ */
+export function resolveAvatarFill(hex, target = AA_NORMAL_TEXT) {
+    return liftToContrast(hex, "#ffffff", target);
+}
+/**
+ * Hue set for generated avatars. Values are seeds, not final fills — always pass them through
+ * `resolveAvatarFill` so the white initials stay legible.
+ */
+export const AVATAR_SEEDS = [
+    "#ef4444",
+    "#f97316",
+    "#eab308",
+    "#22c55e",
+    "#10b981",
+    "#06b6d4",
+    "#3b82f6",
+    "#8b5cf6",
+    "#ec4899",
+];
+/** Stable per-name avatar fill: same name always yields the same accessible colour. */
+export function avatarFillFor(seedText) {
+    let hash = 0;
+    for (let i = 0; i < seedText.length; i++) {
+        hash = (hash * 31 + seedText.charCodeAt(i)) >>> 0;
+    }
+    return resolveAvatarFill(AVATAR_SEEDS[hash % AVATAR_SEEDS.length]);
+}
+/** True when `fg` clears the body-text bar on `bg` — exported for consumer assertions. */
+export const meetsBodyText = (fg, bg) => contrastRatio(fg, bg) >= AA_NORMAL_TEXT;

package/dist/esm/Theme/tokens/builders/surfaceRungs.js

@@ -0,0 +1,33 @@
+import { contrastRatio } from "./color.js";
+import { liftToContrast, AA_NON_TEXT } from "./outlineRung.js";
+import { AA_NORMAL_TEXT, pickAccentText } from "./accentText.js";
+import { SEMANTIC_TONES } from "./semanticText.js";
+export const namedSurfaces = (palette) => [
+    ...Object.values(palette.backgroundColor),
+    palette.background[50],
+    palette.table.hover[500],
+];
+/** The surface an ink is closest to — clearing it clears every other one. */
+export const hardestSurface = (ink, surfaces) => surfaces.reduce((worst, s) => contrastRatio(ink, s) < contrastRatio(ink, worst) ? s : worst);
+// Runs last: `table.hover` is one of the surfaces, and it settles in its own rung.
+export function withSurfaceRungs(palette) {
+    const surfaces = namedSurfaces(palette);
+    const lift = (ink, target) => liftToContrast(ink, hardestSurface(ink, surfaces), target);
+    const semanticText = SEMANTIC_TONES.reduce((acc, tone) => {
+        acc[tone] = lift(palette.semanticText[tone], AA_NORMAL_TEXT);
+        return acc;
+    }, {});
+    return {
+        ...palette,
+        textMuted: lift(palette.textMuted, AA_NORMAL_TEXT),
+        accentText: pickAccentText(palette.primary, hardestSurface(palette.accentText, surfaces)),
+        semanticText,
+        text: { ...palette.text, 500: lift(palette.text[500], AA_NORMAL_TEXT) },
+        header: { ...palette.header, 500: lift(palette.header[500], AA_NORMAL_TEXT) },
+        placeholder: {
+            ...palette.placeholder,
+            500: lift(palette.placeholder[500], AA_NORMAL_TEXT),
+        },
+        boxborder: { ...palette.boxborder, 500: lift(palette.boxborder[500], AA_NON_TEXT) },
+    };
+}

package/dist/esm/Theme/tokens/index.js

@@ -0,0 +1,14 @@
+/**
+ * Pixelize design tokens — the portable core of the design system.
+ *
+ * PURITY CONTRACT: nothing in this folder imports Chakra, React, or CSS. It is plain
+ * TypeScript data + pure functions, so the mobile design library can consume this
+ * folder as-is. Keep it that way — a single Chakra/CSS import here breaks the mobile port.
+ *
+ * Web-only concerns (Chakra `extendTheme`, `cssVarPrefix`, the Inter font-face CSS import)
+ * live in `Theme/chakra/` instead.
+ */
+export * from "./types.js";
+export * from "./primitives/index.js";
+export * from "./brands/index.js";
+export * from "./builders/index.js";

package/dist/esm/Theme/tokens/primitives/breakpoints.js

@@ -0,0 +1,8 @@
+const breakpoints = {
+    sm: "30em",
+    md: "48em",
+    lg: "62em",
+    xl: "80em",
+    "2xl": "96em",
+};
+export default breakpoints;

package/dist/esm/Theme/tokens/primitives/index.js

@@ -0,0 +1,9 @@
+export { default as space } from "./space.js";
+export { default as sizes } from "./sizes.js";
+export { default as radii } from "./radii.js";
+export { default as shadows } from "./shadows.js";
+export { default as zIndices } from "./zIndices.js";
+export { default as breakpoints } from "./breakpoints.js";
+export { default as lineHeights } from "./lineHeights.js";
+export { default as letterSpacings } from "./letterSpacings.js";
+export { default as typography, fonts, fontSizes, fontWeights } from "./typography.js";

package/dist/esm/Theme/tokens/primitives/letterSpacings.js

@@ -0,0 +1,9 @@
+const letterSpacings = {
+    tighter: "-0.05em",
+    tight: "-0.025em",
+    normal: "0",
+    wide: "0.025em",
+    wider: "0.05em",
+    widest: "0.1em",
+};
+export default letterSpacings;

package/dist/esm/Theme/tokens/primitives/lineHeights.js

@@ -0,0 +1,18 @@
+const lineHeights = {
+    normal: "normal",
+    none: 1,
+    shorter: 1.25,
+    short: 1.375,
+    base: 1.5,
+    tall: 1.625,
+    taller: "2",
+    "3": ".75rem",
+    "4": "1rem",
+    "5": "1.25rem",
+    "6": "1.5rem",
+    "7": "1.75rem",
+    "8": "2rem",
+    "9": "2.25rem",
+    "10": "2.5rem",
+};
+export default lineHeights;

package/dist/esm/Theme/tokens/primitives/radii.js

@@ -0,0 +1,12 @@
+const radii = {
+    none: "0",
+    sm: "0.125rem",
+    base: "0.25rem",
+    md: "0.375rem",
+    lg: "0.5rem",
+    xl: "0.75rem",
+    "2xl": "1rem",
+    "3xl": "1.5rem",
+    full: "9999px",
+};
+export default radii;

package/dist/esm/Theme/tokens/primitives/shadows.js

@@ -0,0 +1,15 @@
+/** Light-mode shadow ramp. Dark mode deepens these — see `builders/buildDarkShadows`. */
+const shadows = {
+    xs: "0 0 0 1px rgba(0, 0, 0, 0.05)",
+    sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
+    base: "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)",
+    md: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
+    lg: "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)",
+    xl: "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)",
+    "2xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)",
+    outline: "0 0 0 3px rgba(66, 153, 225, 0.6)",
+    inner: "inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)",
+    none: "none",
+    darkLg: "0 10px 15px -3px rgba(0, 0, 0, 0.5), 0 4px 6px -2px rgba(0, 0, 0, 0.5)",
+};
+export default shadows;

package/dist/esm/Theme/tokens/primitives/sizes.js

@@ -0,0 +1,34 @@
+import space from "./space.js";
+/**
+ * `screenW`/`screenH` use viewport units — a web concept. The mobile port should
+ * map these to `Dimensions.get("window")` rather than consuming them literally.
+ */
+const sizes = {
+    ...space,
+    full: "100%",
+    screenW: "100vw",
+    screenH: "100vh",
+    max: "max-content",
+    min: "min-content",
+    "3xs": "14rem",
+    "2xs": "16rem",
+    xs: "20rem",
+    sm: "24rem",
+    md: "28rem",
+    lg: "32rem",
+    xl: "36rem",
+    "2xl": "42rem",
+    "3xl": "48rem",
+    "4xl": "56rem",
+    "5xl": "64rem",
+    "6xl": "72rem",
+    "7xl": "80rem",
+    "8xl": "90rem",
+    container: {
+        sm: "640px",
+        md: "768px",
+        lg: "1024px",
+        xl: "1280px",
+    },
+};
+export default sizes;

package/dist/esm/Theme/tokens/primitives/space.js

@@ -0,0 +1,33 @@
+const space = {
+    px: "1px",
+    0: "0",
+    1: "0.25rem", // 4px
+    2: "0.5rem", // 8px
+    3: "0.75rem", // 12px
+    4: "1rem", // 16px
+    5: "1.25rem", // 20px
+    6: "1.5rem", // 24px
+    7: "1.75rem", // 28px
+    8: "2rem", // 32px
+    9: "2.25rem", // 36px
+    10: "2.5rem", // 40px
+    12: "3rem", // 48px
+    14: "3.5rem", // 56px
+    16: "4rem", // 64px
+    20: "5rem", // 80px
+    24: "6rem", // 96px
+    28: "7rem", // 112px
+    32: "8rem", // 128px
+    36: "9rem", // 144px
+    40: "10rem", // 160px
+    44: "11rem", // 176px
+    48: "12rem", // 192px
+    52: "13rem", // 208px
+    56: "14rem", // 224px
+    60: "15rem", // 240px
+    64: "16rem", // 256px
+    72: "18rem", // 288px
+    80: "20rem", // 320px
+    96: "24rem", // 384px
+};
+export default space;

package/dist/esm/Theme/tokens/primitives/typography.js

@@ -0,0 +1,40 @@
+/**
+ * Pure typography tokens. Platform-agnostic.
+ *
+ * NOTE: the web build must additionally load the Inter Variable font face
+ * (`Theme/chakra/fonts.web.ts` does the CSS side-effect import). That import is
+ * deliberately NOT here — a CSS import would break the mobile port of this folder.
+ */
+export const fonts = {
+    body: "Inter Variable, sans-serif",
+    heading: "Inter Variable, sans-serif",
+    mono: "Inter Variable, sans-serif",
+};
+export const fontSizes = {
+    xs: "0.75rem",
+    sm: "0.875rem",
+    md: "1rem",
+    lg: "1.125rem",
+    xl: "1.25rem",
+    "2xl": "1.5rem",
+    "3xl": "1.875rem",
+    "4xl": "2.25rem",
+    "5xl": "3rem",
+    "6xl": "3.75rem",
+    "7xl": "4.5rem",
+    "8xl": "6rem",
+    "9xl": "8rem",
+};
+export const fontWeights = {
+    hairline: 100,
+    thin: 200,
+    light: 300,
+    normal: 400,
+    medium: 500,
+    semibold: 600,
+    bold: 700,
+    extrabold: 800,
+    black: 900,
+};
+const typography = { fonts, fontSizes, fontWeights };
+export default typography;

package/dist/esm/Theme/tokens/primitives/zIndices.js

@@ -0,0 +1,16 @@
+const zIndices = {
+    hide: -1,
+    auto: "auto",
+    base: 0,
+    docked: 10,
+    dropdown: 1000,
+    sticky: 1100,
+    banner: 1200,
+    overlay: 1300,
+    modal: 1400,
+    popover: 1500,
+    skipLink: 1600,
+    toast: 1700,
+    tooltip: 1800,
+};
+export default zIndices;

package/dist/esm/Theme/tokens/types.js

@@ -0,0 +1,7 @@
+/**
+ * Pure token types — shared by web (Chakra) and mobile design libraries.
+ *
+ * PURITY RULE: nothing under `Theme/tokens/**` may import Chakra, React, or CSS.
+ * This folder is copy-paste portable to the mobile design library as-is.
+ */
+export {};

package/dist/esm/Theme/useCustomTheme.js

@@ -0,0 +1,7 @@
+import { useTheme as useChakraTheme } from "@chakra-ui/react";
+import { assertPixelizePalette } from "./assertPalette.js";
+export const useCustomTheme = () => {
+    const theme = useChakraTheme();
+    assertPixelizePalette(theme);
+    return theme;
+};

package/dist/esm/Utils/accountHandoff.js

@@ -0,0 +1,139 @@
+/**
+ * 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.
+ */
+const ALLOWED_RETURN_HOST_PATTERNS = [
+    /^localhost$/,
+    /^127\.0\.0\.1$/,
+    /\.pixelizetech\.com$/i,
+];
+const DEFAULT_ACCOUNT_PORT = "3000";
+export 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`.
+ */
+export 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"));
+}
+export 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/esm/Utils/functions.js

@@ -0,0 +1,7 @@
+export function toWords(str) {
+    return str
+        .toLowerCase()
+        .split('_')
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}

package/dist/esm/Utils/mergeRefs.js

@@ -0,0 +1,16 @@
+/** Assign a value to a callback ref or a ref object. */
+export function setRef(ref, value) {
+    if (typeof ref === "function")
+        ref(value);
+    else if (ref && typeof ref === "object")
+        ref.current = value;
+}
+/**
+ * Combine multiple refs into a single callback ref, so a value flows to all of
+ * them. Useful when cloning an element to attach an internal ref while
+ * preserving a ref the caller already set.
+ */
+export function mergeRefs(...refs) {
+    return (value) => refs.forEach((r) => setRef(r, value));
+}
+export default mergeRefs;

package/dist/esm/Utils/planBadge.js

@@ -0,0 +1,105 @@
+import { formatPlanElapsed, formatPlanRemaining, } from "./planExpiry.js";
+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.
+ */
+export 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 = formatPlanRemaining(input.expiryDate, now);
+    const elapsed = 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,
+    };
+}