@brightweblabs/ui 0.3.1 → 1.0.0

package/src/components/skeleton.tsx

@@ -0,0 +1,45 @@
+import type { CSSProperties } from "react";
+
+export function Skeleton({ className = "", rounded = "var(--radius)", style }: {
+  className?: string;
+  rounded?: string;
+  style?: CSSProperties;
+}) {
+  return <span aria-hidden className={`skeleton-ghost block ${className}`} style={{ borderRadius: rounded, ...style }} />;
+}
+
+export function SkeletonLine({ w = "100%", className = "" }: { w?: string; className?: string }) {
+  return <Skeleton rounded="999px" className={`h-[0.6rem] ${className}`} style={{ width: w }} />;
+}
+
+export function SkeletonText({ lines = 3, className = "" }: { lines?: number; className?: string }) {
+  const widths = ["100%", "92%", "84%", "96%", "70%"];
+  return (
+    <div className={`flex flex-col gap-2 ${className}`}>
+      {Array.from({ length: lines }, (_, index) => (
+        <SkeletonLine key={index} w={index === lines - 1 ? "55%" : widths[index % widths.length]} />
+      ))}
+    </div>
+  );
+}
+
+export function SkeletonCard({ lines = 3, meta = true, className = "", bodyClassName = "" }: {
+  lines?: number;
+  meta?: boolean;
+  className?: string;
+  bodyClassName?: string;
+}) {
+  return (
+    <div className={`flex flex-col gap-4 rounded-[var(--radius-card)] border border-border bg-card p-5 shadow-[0_1px_2px_var(--hairline)] ${className}`}>
+      <div className="flex flex-col gap-2">
+        <SkeletonLine w="45%" className="h-[0.7rem]" />
+        {meta ? <SkeletonLine w="28%" /> : null}
+      </div>
+      <SkeletonText lines={lines} className={bodyClassName} />
+    </div>
+  );
+}
+
+export function SkeletonCircle({ size = "2.25rem", className = "" }: { size?: string; className?: string }) {
+  return <Skeleton rounded="50%" className={`shrink-0 ${className}`} style={{ width: size, height: size }} />;
+}

package/src/components/sonner.tsx

@@ -1,9 +1,10 @@
 "use client";
 
 import { CircleCheckIcon, InfoIcon, Loader2Icon, OctagonXIcon, TriangleAlertIcon } from "lucide-react";
-import { useTheme } from "next-themes";
 import { Toaster as Sonner, type ToasterProps } from "sonner";
 
+import { useTheme } from "./theme-provider";
+
 const Toaster = ({ ...props }: ToasterProps) => {
   const { theme = "system" } = useTheme();
 

package/src/components/stat-tile.tsx

@@ -0,0 +1,30 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { cn } from "../lib/utils";
+
+export type StatTileProps = HTMLAttributes<HTMLDivElement> & {
+  label: ReactNode;
+};
+
+export function StatTile({ label, children, className, ...props }: StatTileProps) {
+  return (
+    <div className={cn("stat-cell", className)} {...props}>
+      <p className="text-ui-label">{label}</p>
+      <div className="mt-3">{children}</div>
+    </div>
+  );
+}
+
+export type StatValueProps = HTMLAttributes<HTMLParagraphElement> & {
+  size?: "normal" | "large" | "display";
+};
+
+const statValueSizeClasses: Record<NonNullable<StatValueProps["size"]>, string> = {
+  normal: "text-ui-metric",
+  large: "text-ui-metric-xl",
+  display: "text-ui-metric-display",
+};
+
+export function StatValue({ size = "normal", className, ...props }: StatValueProps) {
+  return <p className={cn(statValueSizeClasses[size], className)} {...props} />;
+}

package/src/components/status-pill.tsx

@@ -0,0 +1,37 @@
+import { Slot } from "@radix-ui/react-slot";
+import { tintPill } from "@brightweblabs/theme/tint";
+import type { ComponentProps, CSSProperties, ReactNode } from "react";
+
+import { cn } from "../lib/utils";
+
+export type StatusPillSize = "small" | "normal";
+
+export const STATUS_PILL_BASE_CLASS =
+  "inline-flex shrink-0 items-center justify-center gap-1.5 whitespace-nowrap rounded-full border font-semibold leading-none";
+
+export const STATUS_PILL_SIZE_CLASSES: Record<StatusPillSize, string> = {
+  small: "h-5 px-2 text-ui-micro",
+  normal: "h-7 px-3 text-ui-meta",
+};
+
+export type StatusPillProps = Omit<ComponentProps<"span">, "children"> & {
+  children: ReactNode;
+  token: string;
+  size?: StatusPillSize;
+  asChild?: boolean;
+};
+
+export function StatusPill({ children, token, size = "small", asChild = false, className, style, ...props }: StatusPillProps) {
+  const Comp = asChild ? Slot : "span";
+  const tint = tintPill(token);
+
+  return (
+    <Comp
+      className={cn(STATUS_PILL_BASE_CLASS, STATUS_PILL_SIZE_CLASSES[size], tint.className, className)}
+      style={{ ...tint.style, ...style } as CSSProperties}
+      {...props}
+    >
+      {children}
+    </Comp>
+  );
+}

package/src/components/surface-card.tsx

@@ -0,0 +1,11 @@
+import type { HTMLAttributes } from "react";
+
+import { cn } from "../lib/utils";
+
+export type SurfaceCardProps = HTMLAttributes<HTMLElement> & {
+  isLight?: boolean;
+};
+
+export function SurfaceCard({ isLight = false, className, ...props }: SurfaceCardProps) {
+  return <article className={cn("surface-card", isLight && "is-light", className)} {...props} />;
+}

package/src/components/table-pagination.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+import { getPaginationWindow } from "../lib/patterns";
+import { cn } from "../lib/utils";
+import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink } from "./pagination";
+
+export type TablePaginationProps = {
+  page: number;
+  totalPages: number;
+  onPageChange: (page: number) => void;
+  summary?: string;
+  className?: string;
+  previousLabel?: string;
+  nextLabel?: string;
+  pageLabel?: (page: number, totalPages: number) => string;
+};
+
+export function TablePagination({
+  page,
+  totalPages,
+  onPageChange,
+  summary,
+  className,
+  previousLabel = "Go to the previous page",
+  nextLabel = "Go to the next page",
+  pageLabel = (currentPage, pageCount) => `Page ${currentPage} of ${pageCount}`,
+}: TablePaginationProps) {
+  const safeTotalPages = Math.max(1, Math.trunc(totalPages));
+  const safePage = Math.min(Math.max(Math.trunc(page), 1), safeTotalPages);
+  const items = getPaginationWindow(safePage, safeTotalPages);
+
+  const changePage = (nextPage: number) => {
+    const clampedPage = Math.min(Math.max(nextPage, 1), safeTotalPages);
+    if (clampedPage !== safePage) onPageChange(clampedPage);
+  };
+
+  return (
+    <div className={cn("flex min-w-0 flex-col gap-2 border-t border-hairline px-4 py-2 md:flex-row md:items-center md:justify-between", className)}>
+      {summary ? (
+        <p className="min-w-0 truncate text-ui-meta">
+          <span className="font-semibold text-foreground">{pageLabel(safePage, safeTotalPages)}</span>
+          <span className="px-1.5 text-border">·</span>
+          {summary}
+        </p>
+      ) : null}
+      <Pagination className="mx-0 w-auto min-w-0 shrink-0 justify-start md:ml-auto md:justify-end">
+        <PaginationContent className="gap-1.5">
+          <PaginationItem>
+            <PaginationLink
+              size="sm"
+              href="#"
+              aria-label={previousLabel}
+              aria-disabled={safePage === 1}
+              onClick={(event) => {
+                event.preventDefault();
+                changePage(safePage - 1);
+              }}
+              className={cn("size-8 rounded-full border border-transparent text-muted-foreground hover:border-hairline-strong hover:bg-surface-hover hover:text-foreground", safePage === 1 && "pointer-events-none opacity-45")}
+            >
+              <ChevronLeft className="size-4" />
+            </PaginationLink>
+          </PaginationItem>
+          {items.map((item) => typeof item === "number" ? (
+            <PaginationItem key={item}>
+              <PaginationLink
+                size="sm"
+                href="#"
+                isActive={item === safePage}
+                onClick={(event) => {
+                  event.preventDefault();
+                  changePage(item);
+                }}
+                className={cn(
+                  "size-8 rounded-full text-ui-label normal-case tracking-normal",
+                  item === safePage ? "border-hairline-strong bg-elevate-2 text-foreground" : "text-muted-foreground hover:bg-surface-hover hover:text-foreground",
+                )}
+              >
+                {item}
+              </PaginationLink>
+            </PaginationItem>
+          ) : (
+            <PaginationItem key={item}>
+              <PaginationEllipsis />
+            </PaginationItem>
+          ))}
+          <PaginationItem>
+            <PaginationLink
+              size="sm"
+              href="#"
+              aria-label={nextLabel}
+              aria-disabled={safePage === safeTotalPages}
+              onClick={(event) => {
+                event.preventDefault();
+                changePage(safePage + 1);
+              }}
+              className={cn("size-8 rounded-full border border-transparent text-muted-foreground hover:border-hairline-strong hover:bg-surface-hover hover:text-foreground", safePage === safeTotalPages && "pointer-events-none opacity-45")}
+            >
+              <ChevronRight className="size-4" />
+            </PaginationLink>
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    </div>
+  );
+}

package/src/components/table.tsx

@@ -2,9 +2,12 @@ import * as React from "react";
 
 import { cn } from "../lib/utils";
 
-const Table = React.forwardRef<HTMLTableElement, React.HTMLAttributes<HTMLTableElement>>(
-  ({ className, ...props }, ref) => (
-    <div className="w-full overflow-auto">
+const Table = React.forwardRef<
+  HTMLTableElement,
+  React.HTMLAttributes<HTMLTableElement> & { containerClassName?: string }
+>(
+  ({ className, containerClassName, ...props }, ref) => (
+    <div className={cn("w-full flex-1 overflow-auto", containerClassName)}>
       <table ref={ref} className={cn("w-full caption-bottom text-sm", className)} {...props} />
     </div>
   ),
@@ -25,7 +28,7 @@ TableBody.displayName = "TableBody";
 
 const TableFooter = React.forwardRef<HTMLTableSectionElement, React.HTMLAttributes<HTMLTableSectionElement>>(
   ({ className, ...props }, ref) => (
-    <tfoot ref={ref} className={cn("border-t bg-muted/50 font-medium [&>tr]:last:border-b-0", className)} {...props} />
+    <tfoot ref={ref} className={cn("border-t bg-muted/50 font-semibold [&>tr]:last:border-b-0", className)} {...props} />
   ),
 );
 TableFooter.displayName = "TableFooter";

package/src/components/theme-provider.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+
+type Theme = "light" | "dark" | "system";
+
+type ThemeProviderProps = {
+  children: ReactNode;
+  defaultTheme?: Theme;
+  enableSystem?: boolean;
+  disableTransitionOnChange?: boolean;
+};
+
+type ThemeContextValue = {
+  theme: Theme;
+  setTheme: (theme: string) => void;
+  resolvedTheme: "light" | "dark";
+  systemTheme: "light" | "dark";
+  themes: Theme[];
+};
+
+const STORAGE_KEY = "theme";
+const THEME_VALUES: Theme[] = ["light", "dark", "system"];
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+function getSystemTheme(): "light" | "dark" {
+  if (typeof window === "undefined") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+function readStoredTheme(defaultTheme: Theme): Theme {
+  if (typeof window === "undefined") return defaultTheme;
+  try {
+    const stored = window.localStorage.getItem(STORAGE_KEY);
+    return stored === "light" || stored === "dark" || stored === "system" ? stored : defaultTheme;
+  } catch {
+    return defaultTheme;
+  }
+}
+
+function applyResolvedTheme(resolvedTheme: "light" | "dark", disableTransitionOnChange: boolean) {
+  const root = document.documentElement;
+  let cleanup: (() => void) | null = null;
+
+  if (disableTransitionOnChange) {
+    const style = document.createElement("style");
+    style.appendChild(document.createTextNode("*,*::before,*::after{transition:none!important;animation-duration:0s!important}"));
+    document.head.appendChild(style);
+    cleanup = () => {
+      window.getComputedStyle(document.body);
+      window.setTimeout(() => style.remove(), 1);
+    };
+  }
+
+  root.classList.remove("light", "dark");
+  root.classList.add(resolvedTheme);
+  root.dataset.theme = resolvedTheme;
+  root.style.colorScheme = resolvedTheme;
+  cleanup?.();
+}
+
+export function ThemeProvider({
+  children,
+  defaultTheme = "light",
+  enableSystem = true,
+  disableTransitionOnChange = false,
+}: ThemeProviderProps) {
+  const [theme, setThemeState] = useState<Theme>(defaultTheme);
+  const [systemTheme, setSystemTheme] = useState<"light" | "dark">("light");
+  const resolvedTheme = theme === "system" && enableSystem ? systemTheme : theme === "dark" ? "dark" : "light";
+
+  useLayoutEffect(() => {
+    applyResolvedTheme(resolvedTheme, disableTransitionOnChange);
+  }, [disableTransitionOnChange, resolvedTheme]);
+
+  useEffect(() => {
+    setThemeState(readStoredTheme(defaultTheme));
+    setSystemTheme(getSystemTheme());
+  }, [defaultTheme]);
+
+  useEffect(() => {
+    if (!enableSystem) return;
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    const handleChange = () => setSystemTheme(media.matches ? "dark" : "light");
+    handleChange();
+    media.addEventListener("change", handleChange);
+    return () => media.removeEventListener("change", handleChange);
+  }, [enableSystem]);
+
+  useEffect(() => {
+    const handleStorage = (event: StorageEvent) => {
+      if (event.key === STORAGE_KEY) setThemeState(readStoredTheme(defaultTheme));
+    };
+    window.addEventListener("storage", handleStorage);
+    return () => window.removeEventListener("storage", handleStorage);
+  }, [defaultTheme]);
+
+  const setTheme = useCallback((nextTheme: string) => {
+    const normalizedTheme: Theme = nextTheme === "dark" || nextTheme === "light" || nextTheme === "system" ? nextTheme : defaultTheme;
+    setThemeState(normalizedTheme);
+    try {
+      window.localStorage.setItem(STORAGE_KEY, normalizedTheme);
+    } catch {
+      // In-memory theme state remains usable when storage is unavailable.
+    }
+  }, [defaultTheme]);
+
+  const value = useMemo<ThemeContextValue>(() => ({
+    theme,
+    setTheme,
+    resolvedTheme,
+    systemTheme,
+    themes: enableSystem ? THEME_VALUES : ["light", "dark"],
+  }), [enableSystem, resolvedTheme, setTheme, systemTheme, theme]);
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): ThemeContextValue {
+  return useContext(ThemeContext) ?? {
+    theme: "light",
+    setTheme: () => undefined,
+    resolvedTheme: "light",
+    systemTheme: "light",
+    themes: THEME_VALUES,
+  };
+}
+
+export type { Theme, ThemeContextValue, ThemeProviderProps };

package/src/components/tooltip.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import * as React from "react"
-import { Tooltip as TooltipPrimitive } from "radix-ui"
+import * as TooltipPrimitive from "@radix-ui/react-tooltip"
 
 import { cn } from "../lib/utils"
 
@@ -41,7 +41,7 @@ function TooltipContent({
         data-slot="tooltip-content"
         sideOffset={sideOffset}
         className={cn(
-          "z-[1300] overflow-hidden rounded-xl border border-black/12 bg-white/95 px-2.5 py-1.5 text-xs font-medium text-foreground/90 shadow-[0_14px_34px_rgba(8,24,16,0.12)] backdrop-blur-xl data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0 dark:border-white/12 dark:bg-black/70 dark:text-foreground",
+          "z-[1300] overflow-hidden rounded-[var(--radius-card)] border border-[color:var(--hairline-strong)] bg-[color:color-mix(in_srgb,var(--popover)_95%,transparent)] px-2.5 py-1.5 text-ui-meta !font-semibold text-popover-foreground shadow-[0_14px_34px_var(--elevate-3)] backdrop-blur-xl data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0",
           className
         )}
         {...props}

package/src/index.ts

@@ -1,5 +1,7 @@
 export { Button, buttonVariants } from "./components/button";
-export { Badge } from "./components/badge";
+export type { ButtonProps, ButtonVariantProps } from "./components/button";
+export { Badge, badgeVariants } from "./components/badge";
+export * from "./components/avatar";
 export * from "./components/dropdown-menu";
 export {
   Field,
@@ -13,7 +15,14 @@ export {
 } from "./components/field";
 export { Input } from "./components/input";
 export { PasswordInput } from "./components/password-input";
+export type { PasswordInputProps } from "./components/password-input";
 export { PasswordStrength } from "./components/password-strength";
+export { PhoneInput } from "./components/phone-input";
+export type { PhoneInputProps } from "./components/phone-input";
+export { SearchField } from "./components/search-field";
+export type { SearchFieldProps } from "./components/search-field";
+export * from "./components/skeleton";
+export { TableRowsSkeleton } from "./components/skeleton-table";
 export { Separator } from "./components/separator";
 export * from "./components/alert-dialog";
 export * from "./components/card";
@@ -26,4 +35,25 @@ export * from "./components/popover";
 export * from "./components/sheet";
 export * from "./components/table";
 export { Toaster } from "./components/sonner";
+export { ThemeProvider, useTheme } from "./components/theme-provider";
+export type { Theme, ThemeContextValue, ThemeProviderProps } from "./components/theme-provider";
 export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./components/tooltip";
+export { ActivityMessage } from "./components/activity-message";
+export * from "./components/action";
+export * from "./components/empty-state";
+export * from "./components/initials-avatar";
+export * from "./components/kpi-breakdown-bar";
+export * from "./components/role-badge";
+export * from "./components/section-heading";
+export * from "./components/stat-tile";
+export * from "./components/status-pill";
+export * from "./components/surface-card";
+export * from "./components/table-pagination";
+export {
+  formatActivityValue,
+  toActivityChanges,
+  type ActivityChange,
+  type ActivityChangesOptions,
+  type ActivityValueOptions,
+  type MsgSeg,
+} from "./lib/activity-format";

package/src/lib/activity-format.ts

@@ -0,0 +1,96 @@
+/**
+ * Framework-free formatting primitives shared by every activity / timeline
+ * surface (notifications bell, project "recent activity" rail, CRM timeline).
+ *
+ * These are language-neutral: all human-readable strings (field labels, the
+ * system fallback, boolean words, the date locale) are injected by the caller
+ * so each app/module supplies its own dictionary. Imports nothing from React —
+ * safe to use in server and client code alike.
+ */
+
+/** A rendered message is plain text + emphasised names ({ b }) + emphasised values ({ v }). */
+export type MsgSeg = string | { b: string } | { v: string };
+
+/** One field-level change, ready to render as "Label: from → to". */
+export type ActivityChange = { key: string; label: string; from: string | null; to: string | null };
+
+export type ActivityValueOptions = {
+  /** Intl locale used to format ISO dates. Defaults to "en". */
+  locale?: string;
+  /** Label for a boolean `true` value. Defaults to "Yes". */
+  trueLabel?: string;
+  /** Label for a boolean `false` value. Defaults to "No". */
+  falseLabel?: string;
+};
+
+export type ActivityChangesOptions = ActivityValueOptions & {
+  /** Map of payload field name → human label. Unmapped fields fall back to the raw key. */
+  fieldLabels?: Record<string, string>;
+  /** Field names whose values are people — an empty one reads as the system, not a blank. */
+  personFields?: Iterable<string>;
+  /** Label used when a person field is explicitly empty. Defaults to "System". */
+  systemLabel?: string;
+};
+
+function looksLikeId(value: string) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(value);
+}
+
+function isEmpty(value: unknown) {
+  return value === null || value === undefined || value === "";
+}
+
+/** Render a stored change value into something readable, or null when it can't be shown plainly. */
+export function formatActivityValue(value: unknown, options: ActivityValueOptions = {}): string | null {
+  const { locale = "en", trueLabel = "Yes", falseLabel = "No" } = options;
+  if (isEmpty(value)) return null;
+  if (typeof value === "boolean") return value ? trueLabel : falseLabel;
+  if (typeof value === "number") return String(value);
+  if (typeof value !== "string") return null;
+
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  // Profile / entity references come through as raw UUIDs — not worth showing.
+  if (looksLikeId(trimmed)) return null;
+
+  // ISO date / datetime → short localised form.
+  if (/^\d{4}-\d{2}-\d{2}/.test(trimmed)) {
+    const date = new Date(trimmed);
+    if (!Number.isNaN(date.getTime())) {
+      return new Intl.DateTimeFormat(locale, { day: "2-digit", month: "2-digit", year: "numeric" }).format(date);
+    }
+  }
+
+  return trimmed.length > 32 ? `${trimmed.slice(0, 31)}…` : trimmed;
+}
+
+/** Pull the `payload.changes` map ({ field: { from, to } }) into a flat, display-ready list. */
+export function toActivityChanges(
+  payload: Record<string, unknown> | undefined,
+  options: ActivityChangesOptions = {},
+): ActivityChange[] {
+  const { fieldLabels = {}, systemLabel = "System" } = options;
+  const personFields = new Set(options.personFields ?? []);
+  const changesRaw = payload?.changes;
+  if (!changesRaw || typeof changesRaw !== "object" || Array.isArray(changesRaw)) return [];
+
+  return Object.entries(changesRaw as Record<string, unknown>).flatMap(([field, raw]) => {
+    if (!raw || typeof raw !== "object") return [];
+    const { from, to } = raw as { from?: unknown; to?: unknown };
+    const isPerson = personFields.has(field);
+    // People always read as someone: an explicitly empty assignee/owner is the
+    // system. An unresolved id (formats to null) is left blank rather than
+    // wrongly attributed to the system.
+    const resolve = (value: unknown) => {
+      const formatted = formatActivityValue(value, options);
+      if (formatted) return formatted;
+      return isPerson && isEmpty(value) ? systemLabel : null;
+    };
+    return [{
+      key: field,
+      label: fieldLabels[field] ?? field,
+      from: resolve(from),
+      to: resolve(to),
+    }];
+  });
+}

package/src/lib/patterns.ts

@@ -0,0 +1,52 @@
+export type PaginationWindowItem = number | "start-ellipsis" | "end-ellipsis";
+
+export function getPaginationWindow(page: number, totalPages: number): PaginationWindowItem[] {
+  const safeTotal = Math.max(1, Math.trunc(totalPages));
+  const safePage = Math.min(Math.max(Math.trunc(page), 1), safeTotal);
+
+  if (safeTotal <= 5) {
+    return Array.from({ length: safeTotal }, (_, index) => index + 1);
+  }
+
+  const pages = new Set([1, safeTotal, safePage - 1, safePage, safePage + 1]);
+  const visible = Array.from(pages).filter((value) => value >= 1 && value <= safeTotal).sort((a, b) => a - b);
+  const result: PaginationWindowItem[] = [];
+
+  visible.forEach((value, index) => {
+    const previous = visible[index - 1];
+    if (previous && value - previous > 1) {
+      result.push(previous === 1 ? "start-ellipsis" : "end-ellipsis");
+    }
+    result.push(value);
+  });
+
+  return result;
+}
+
+export function getInitials(label?: string | null, fallback?: string | null): string {
+  const source = (label || fallback || "?").trim();
+  if (!source) return "?";
+
+  return source
+    .split(/\s+/)
+    .map((token) => token.charAt(0))
+    .filter(Boolean)
+    .slice(0, 2)
+    .join("")
+    .toUpperCase();
+}
+
+export function getRoleLabel(role: string): string {
+  return role
+    .trim()
+    .replace(/[_-]+/g, " ")
+    .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+
+export function resolveRoleToken(
+  role: string,
+  tokenMap: Readonly<Record<string, string>>,
+  fallbackToken = "--semantic-neutral",
+): string {
+  return tokenMap[role] ?? fallbackToken;
+}