@exxatdesignux/ui 0.2.16 → 0.2.18

package/template/lib/exxat-palette.ts

@@ -0,0 +1,136 @@
+/**
+ * Exxat web color palette — single source of truth for the curated brand
+ * color picker (and any future surface that needs a typed enumeration of the
+ * Exxat color tokens with both hex and OKLCH forms).
+ *
+ * Data lives in `exxat-palette.json` (16 shades × 9 families). This module
+ * adds:
+ *
+ *  - Static TypeScript types for the JSON shape so consumers get autocomplete
+ *    on family ids and shade keys.
+ *  - Stable display labels for each family (`exxatPink` → `"Pink"`, etc.) so
+ *    the picker UI does not have to know the JSON key naming convention.
+ *  - A flattened `EXXAT_PALETTE_SWATCHES` array of { family, shade, hex,
+ *    oklch, label } records for grid rendering, plus `findExxatPaletteSwatch`
+ *    so we can highlight the "selected" swatch when the brand color matches a
+ *    palette token.
+ *
+ * The picker may also store a free-form CSS color (the underlying state stays
+ * `string`); helpers here only describe the curated subset so the UI can
+ * expose recognised tokens with a friendlier label / hover tooltip.
+ */
+import paletteRaw from "./exxat-palette.json"
+
+export interface ExxatPaletteSwatchData {
+  hex: string
+  oklch: string
+  oklchValues: { l: number; c: number; h: number }
+}
+
+export type ExxatPaletteJson = Record<string, Record<string, ExxatPaletteSwatchData>>
+
+const PALETTE: ExxatPaletteJson = paletteRaw as ExxatPaletteJson
+
+export type ExxatPaletteFamilyId =
+  | "exxatPink"
+  | "exxatBlue"
+  | "exxatIndigo"
+  | "sapphireGrayBlack"
+  | "orange"
+  | "teal"
+  | "red"
+  | "neutral"
+  | "purple"
+  | "green"
+
+/**
+ * Display labels — keep ordering consistent with how the palette is composed
+ * (Exxat brand families first, then auxiliary hues, neutrals last).
+ */
+export const EXXAT_PALETTE_FAMILIES: ReadonlyArray<{ id: ExxatPaletteFamilyId; label: string }> = [
+  { id: "exxatPink", label: "Pink" },
+  { id: "exxatBlue", label: "Blue" },
+  { id: "exxatIndigo", label: "Indigo" },
+  { id: "purple", label: "Purple" },
+  { id: "teal", label: "Teal" },
+  { id: "green", label: "Green" },
+  { id: "orange", label: "Orange" },
+  { id: "red", label: "Red" },
+  { id: "neutral", label: "Neutral" },
+  { id: "sapphireGrayBlack", label: "Sapphire" },
+]
+
+/** Shade keys preserved in palette order (50, 100, 150, …, 900). Some "round" stops
+ * are intentionally absent (no 350 / 800) — keep this in sync with the JSON. */
+export const EXXAT_PALETTE_SHADES: ReadonlyArray<string> = [
+  "50",
+  "100",
+  "150",
+  "200",
+  "250",
+  "300",
+  "400",
+  "450",
+  "500",
+  "550",
+  "600",
+  "650",
+  "700",
+  "750",
+  "850",
+  "900",
+]
+
+export interface ExxatPaletteSwatch extends ExxatPaletteSwatchData {
+  family: ExxatPaletteFamilyId
+  familyLabel: string
+  shade: string
+  /** Human-readable label, e.g. `"Pink 500"`. */
+  label: string
+}
+
+function buildSwatch(family: ExxatPaletteFamilyId, familyLabel: string, shade: string): ExxatPaletteSwatch | null {
+  const data = PALETTE[family]?.[shade]
+  if (!data) return null
+  return {
+    family,
+    familyLabel,
+    shade,
+    label: `${familyLabel} ${shade}`,
+    hex: data.hex,
+    oklch: data.oklch,
+    oklchValues: data.oklchValues,
+  }
+}
+
+/** Family → ordered list of swatches (only shades that actually exist in the JSON). */
+export const EXXAT_PALETTE_BY_FAMILY: ReadonlyArray<{
+  id: ExxatPaletteFamilyId
+  label: string
+  swatches: ReadonlyArray<ExxatPaletteSwatch>
+}> = EXXAT_PALETTE_FAMILIES.map(({ id, label }) => ({
+  id,
+  label,
+  swatches: EXXAT_PALETTE_SHADES.map(shade => buildSwatch(id, label, shade)).filter(
+    (swatch): swatch is ExxatPaletteSwatch => swatch !== null,
+  ),
+}))
+
+/** Flat list — convenient for "find by value" lookups. */
+export const EXXAT_PALETTE_SWATCHES: ReadonlyArray<ExxatPaletteSwatch> = EXXAT_PALETTE_BY_FAMILY.flatMap(
+  family => family.swatches,
+)
+
+/**
+ * Try to resolve a stored brand color (any CSS string) to a known palette
+ * swatch — matches both the canonical OKLCH form and the hex form so values
+ * authored either way still light up in the picker.
+ */
+export function findExxatPaletteSwatch(value: string | null | undefined): ExxatPaletteSwatch | undefined {
+  if (!value) return undefined
+  const normalized = value.trim().toLowerCase()
+  if (!normalized) return undefined
+  return EXXAT_PALETTE_SWATCHES.find(
+    swatch => swatch.oklch.toLowerCase() === normalized || swatch.hex.toLowerCase() === normalized,
+  )
+}

package/template/lib/list-page-table-properties.ts

@@ -1,6 +1,6 @@
 /**
  * Connects ListPageTemplate “View → Edit” to a surface that hosts TablePropertiesDrawer
- * (DataListTable, TeamTable, ComplianceTable, …). Import from `@/components/table-properties`
+ * (PlacementsTable, TeamTable, ComplianceTable, …). Import from `@/components/table-properties`
  * or use here — see `createListPageEditViewHandler`.
  *
  * View **labels** for tabs and Properties are centralized in `@/lib/data-list-view`

package/template/lib/list-status-badges.ts

@@ -6,7 +6,7 @@
  * Labels use **sentence / title case** (e.g. "Due soon", "Under Review"). Do **not** add **`uppercase`**.
  *
  * **Rendering:** Use **`ListHubStatusBadge`** from `@/components/list-hub-status-badge`, or
- * **`StatusBadge`** from **`components/data-list-table-cells.tsx`** for placement rows (wrapper
+ * **`StatusBadge`** from **`components/placements-table-cells.tsx`** for placement rows (wrapper
  * around **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`** below). Task priority → **`TaskPriorityBadge`**.
  *
  * **Semantic tints:** Map domain statuses onto **`LIST_HUB_STATUS_TINT_*`** before inventing new colors.

package/template/lib/mailto.ts

@@ -0,0 +1,29 @@
+/**
+ * Build a safe `mailto:` URL from a possibly-untrusted email string.
+ *
+ * Per RFC 6068, a `mailto:` href is parsed as `mailto:<addr>[?<headers>]`,
+ * where `<headers>` is a sequence of `key=value` pairs separated by `&`.
+ * Without encoding, an email-shaped string that contains `?`, `&`, `\r`,
+ * `\n`, or other URI-reserved characters could append arbitrary mail headers
+ * (`?cc=`, `?bcc=`, `?subject=`, `%0A` for newlines) or break out of the URL
+ * entirely.
+ *
+ * We split on the first `@` so the address still reads naturally in tooltips
+ * and address-bar previews (`user@example.com` instead of `user%40example.com`),
+ * and percent-encode each side independently with `encodeURIComponent`. We
+ * also strip CR/LF defensively before encoding to short-circuit header
+ * injection even if a future bug allows them through validation upstream.
+ */
+export function mailtoHref(email: string): string {
+  const cleaned = email.replace(/[\r\n]+/g, "").trim()
+  if (!cleaned) return "mailto:"
+
+  const at = cleaned.indexOf("@")
+  if (at <= 0 || at === cleaned.length - 1) {
+    return `mailto:${encodeURIComponent(cleaned)}`
+  }
+
+  const local = encodeURIComponent(cleaned.slice(0, at))
+  const domain = encodeURIComponent(cleaned.slice(at + 1))
+  return `mailto:${local}@${domain}`
+}

package/template/lib/placement-board-card-layout.ts

@@ -7,7 +7,7 @@
 import type { ColumnDef } from "@/components/data-table/types"
 import type { Placement } from "@/lib/mock/placements"
 
-/** Mirrors PlacementLifecycleTabId without importing data-list-table (avoids circular imports). */
+/** Mirrors PlacementLifecycleTabId without importing placements-table (avoids circular imports). */
 export type BoardCardLifecycleTabId = "all" | "upcoming" | "ongoing" | "completed"
 
 /** Default card fields per tab — intersected with visible table columns (except header-only rules below). */

package/template/lib/product-brand.ts

@@ -0,0 +1,268 @@
+/**
+ * Product brand registry — single source of truth for wordmark + mark colors.
+ *
+ * Use {@link defineProductBrand} (or just author a `ProductBrandConfig` literal)
+ * to add a new product without touching the rendering code. The registry feeds
+ * {@link import("../components/product-wordmark").ProductWordmark} and
+ * {@link import("../components/product-wordmark").ProductMark}, which in turn
+ * power `ExxatProductLogo` / `ExxatProductMark` and the product switcher.
+ *
+ * Adding a new product:
+ *
+ * ```ts
+ * // 1. Author the brand
+ * const exxatPulse = defineProductBrand({
+ *   id: "exxat-pulse",
+ *   prefix: "Exxat",
+ *   suffix: "Pulse",
+ *   brandColor: "#00A8E8",                    // any CSS color
+ *   markGradient: ["#0083C7", "#3FC6FF"],     // optional 2-stop linear gradient
+ * })
+ *
+ * // 2. Register it (or just import the config where you render the logo)
+ * registerProductBrand(exxatPulse)
+ *
+ * // 3. Render anywhere
+ * <ProductWordmark config={exxatPulse} className="h-7" />
+ * ```
+ *
+ * The renderer uses Ivy Presto (Adobe Fonts kit `wuk5wqn`, loaded in
+ * `app/layout.tsx`) for the suffix so it reads as a real italic serif logo
+ * rather than fake "logo-styled" text. The prefix uses Inter extra-bold.
+ */
+
+import {
+  DEFAULT_CUSTOM_PRODUCT_BRAND,
+  type CustomProductBrand,
+  type Product,
+} from "@/stores/app-store"
+
+export interface ProductBrandConfig {
+  /** Stable identifier — matches `Product` for the two built-in brands. */
+  id: string
+  /** Word before the suffix in the wordmark. Defaults to "Exxat". */
+  prefix?: string
+  /**
+   * Product suffix — rendered in Ivy Presto italic with `brandColor`.
+   * Should read as a single word; the wordmark renders it inline after
+   * `prefix` with a small em-based gap.
+   */
+  suffix: string
+  /**
+   * Primary brand color (any CSS color). Drives the suffix text fill and the
+   * mark's flat fill. When `markGradient` is provided, the gradient overrides
+   * the mark fill but the suffix text still uses `brandColor`.
+   */
+  brandColor: string
+  /** Optional logo suffix fill when product theme color differs from the logo art. */
+  wordmarkColor?: string
+  /** Use the circular Exxat mark + suffix only when the full wordmark would crowd the shell. */
+  compactLogo?: boolean
+  /**
+   * Optional 2-stop linear gradient for the circular mark. Two CSS color
+   * strings — first is the upper-left stop, second is the lower-right stop.
+   * Defaults to `[brandColor, brandColor]` (flat fill).
+   */
+  markGradient?: [string, string]
+  /**
+   * Darker tone for the inner cut-out behind the "E" glyph on the mark.
+   * Defaults to `brandColor` darkened by ~12 % (or you can pass an explicit
+   * color for finer control over contrast).
+   */
+  markShadow?: string
+  /**
+   * Optional accessible name override. Defaults to `"${prefix} ${suffix}"`.
+   * The wordmark itself stays `aria-hidden`; this name is used by parent
+   * affordances (logo links, switcher triggers) via {@link productBrandLabel}.
+   */
+  label?: string
+}
+
+/**
+ * Author-friendly factory — same signature as the type, plus runtime
+ * normalisation (trims strings, defaults `prefix` to "Exxat"). Use it when you
+ * want a quick literal in JSX; for module-level registry entries the literal
+ * `ProductBrandConfig` form is equally fine.
+ */
+export function defineProductBrand(input: ProductBrandConfig): ProductBrandConfig {
+  return {
+    ...input,
+    prefix: (input.prefix ?? "Exxat").trim(),
+    suffix: input.suffix.trim(),
+  }
+}
+
+/** Human-readable label for a brand — used in aria-labels and dropdown copy. */
+export function productBrandLabel(config: ProductBrandConfig): string {
+  if (config.label) return config.label
+  const prefix = config.prefix ?? "Exxat"
+  return `${prefix} ${config.suffix}`.replace(/\s+/g, " ").trim()
+}
+
+/* ── Built-in Exxat brands ─────────────────────────────────────────────────── */
+
+/**
+ * Exxat brand pink — Pink 500 from `lib/exxat-palette.json`. Used to pin the
+ * **logo art** (mark gradient, shadow plate, suffix wordmark) across every
+ * product so the corporate identity stays consistent even when a product's
+ * accent / theme colour is recoloured by the user.
+ *
+ * Exact-hex match with `Pink 500` so the brand color picker highlights "Pink
+ * 500" instead of falling back to "Custom" when the user opens the popover
+ * for Exxat One.
+ */
+const EXXAT_LOGO_PINK = "#E31C79" // palette: exxatPink-500
+const EXXAT_LOGO_PINK_GRADIENT_END = "#EF609D" // ~ exxatPink-400 lifted
+const EXXAT_LOGO_PINK_SHADOW = "#BE1E6D" // ~ exxatPink-600 deepened
+
+/**
+ * Per-product **theme accent** defaults — these match palette swatches exactly
+ * so the BrandColorPicker labels each product's current colour ("Indigo 600",
+ * "Pink 550", "Green 550") instead of falling back to a generic "Custom" chip.
+ *
+ * They are also the closest palette mappings of the hardcoded `theme-one /
+ * theme-prism / theme-assessment` CSS hues in `app/globals.css`:
+ *  - One → Lavender / Indigo (hue 286 ≈ Indigo 600, hue 278.83)
+ *  - Prism → Rose (hue 342 ≈ Pink 550, hue 358.57)
+ *  - Assessment → Green (hue 159.88 ≈ Green 550, hue 145.88)
+ *
+ * Picking another swatch flips the html theme class to `theme-custom` and
+ * writes the new colour into `--custom-product-brand-color` so chrome retints
+ * — see `ProductProvider`.
+ */
+// Anchor each built-in to its palette family's **500** shade so the
+// BrandColorPicker labels the current value by family name ("Indigo", "Pink",
+// "Green") and the simplified one-anchor-per-family picker can highlight the
+// default selection cleanly.
+const EXXAT_ONE_ACCENT = "oklch(57.84% 0.1560 279.93)" // palette: exxatIndigo-500
+const EXXAT_PRISM_ACCENT = "oklch(60.07% 0.2312 0.68)" // palette: exxatPink-500
+const EXXAT_ASSESSMENT_ACCENT = "oklch(76.40% 0.0773 145.90)" // palette: green-500
+
+export const EXXAT_ONE_BRAND: ProductBrandConfig = defineProductBrand({
+  id: "exxat-one",
+  prefix: "Exxat",
+  suffix: "One",
+  brandColor: EXXAT_ONE_ACCENT,
+  // Logo art pinned to pink — see EXXAT_LOGO_PINK doc. The picker only
+  // overrides `brandColor` (theme accent), never the logo colours.
+  wordmarkColor: EXXAT_LOGO_PINK,
+  markGradient: [EXXAT_LOGO_PINK, EXXAT_LOGO_PINK_GRADIENT_END],
+  markShadow: EXXAT_LOGO_PINK_SHADOW,
+})
+
+export const EXXAT_PRISM_BRAND: ProductBrandConfig = defineProductBrand({
+  id: "exxat-prism",
+  prefix: "Exxat",
+  suffix: "Prism",
+  brandColor: EXXAT_PRISM_ACCENT,
+  wordmarkColor: EXXAT_LOGO_PINK,
+  markGradient: [EXXAT_LOGO_PINK, EXXAT_LOGO_PINK_GRADIENT_END],
+  markShadow: EXXAT_LOGO_PINK_SHADOW,
+})
+
+export const EXXAT_ASSESSMENT_BRAND: ProductBrandConfig = defineProductBrand({
+  id: "exxat-assessment",
+  prefix: "Exxat",
+  suffix: "Assessment",
+  brandColor: EXXAT_ASSESSMENT_ACCENT,
+  // Logo art pinned to pink — Exxat brand identity is shared across every
+  // product. The colour picker only controls the **theme accent / chrome**
+  // (via `applyBrandColorOverride` → `brandColor`), never the mark / suffix.
+  wordmarkColor: EXXAT_LOGO_PINK,
+  markGradient: [EXXAT_LOGO_PINK, EXXAT_LOGO_PINK_GRADIENT_END],
+  markShadow: EXXAT_LOGO_PINK_SHADOW,
+  compactLogo: true,
+})
+
+export function customProductBrandConfig(
+  customBrand: CustomProductBrand | null | undefined = DEFAULT_CUSTOM_PRODUCT_BRAND,
+): ProductBrandConfig {
+  const suffix = customBrand?.suffix.trim() || DEFAULT_CUSTOM_PRODUCT_BRAND.suffix
+  const brandColor =
+    customBrand?.brandColor.trim() || DEFAULT_CUSTOM_PRODUCT_BRAND.brandColor
+  // Logo pinned to pink across every product (Exxat brand identity).
+  // `brandColor` is the **theme / accent** colour only (drives `theme-custom`
+  // chrome via `--custom-product-brand-color`), never the wordmark tint.
+  return defineProductBrand({
+    id: "exxat-custom",
+    prefix: "Exxat",
+    suffix,
+    brandColor,
+    wordmarkColor: EXXAT_LOGO_PINK,
+    markGradient: [EXXAT_LOGO_PINK, EXXAT_LOGO_PINK_GRADIENT_END],
+    markShadow: EXXAT_LOGO_PINK_SHADOW,
+    compactLogo: suffix.length > 8,
+  })
+}
+
+/**
+ * Apply a per-product brand color override to a base config — used when the
+ * user picks a colour for a built-in product (One / Prism / Assessment) in
+ * Settings → Appearance.
+ *
+ * **Only `brandColor` is overridden** — the wordmark / mark stay pinned to
+ * the Exxat brand pink defined on the base config. `brandColor` is the
+ * product **accent / theme** colour (it drives `theme-custom` chrome via
+ * `--custom-product-brand-color`), so recolouring a product changes the
+ * surrounding UI without ever rebranding the corporate logo.
+ *
+ * Keeping `compactLogo`, `prefix`, `suffix`, `wordmarkColor`, `markGradient`,
+ * and `markShadow` from the base config means the picker can never
+ * accidentally change the product's logo identity.
+ */
+export function applyBrandColorOverride(
+  config: ProductBrandConfig,
+  color: string | undefined | null,
+): ProductBrandConfig {
+  const next = color?.trim()
+  if (!next) return config
+  return { ...config, brandColor: next }
+}
+
+/* ── Registry ──────────────────────────────────────────────────────────────── */
+
+const REGISTRY = new Map<string, ProductBrandConfig>()
+
+/** Register a brand. Idempotent — re-registering overrides the existing entry. */
+export function registerProductBrand(config: ProductBrandConfig): void {
+  REGISTRY.set(config.id, config)
+}
+
+/** Look up a brand by id. Returns `undefined` if not registered. */
+export function getProductBrand(id: string): ProductBrandConfig | undefined {
+  return REGISTRY.get(id)
+}
+
+/** All registered brands in insertion order. */
+export function listProductBrands(): ProductBrandConfig[] {
+  return Array.from(REGISTRY.values())
+}
+
+// Eagerly register the two built-ins so call-sites can `getProductBrand("exxat-one")`
+// without an explicit setup step. Safe to call multiple times (Map dedupes on key).
+registerProductBrand(EXXAT_ONE_BRAND)
+registerProductBrand(EXXAT_PRISM_BRAND)
+registerProductBrand(EXXAT_ASSESSMENT_BRAND)
+registerProductBrand(customProductBrandConfig())
+
+/**
+ * Convenience helper for the existing `Product` union — resolves to the
+ * Exxat-branded config, falling back to {@link EXXAT_ONE_BRAND}. Callers that
+ * already have a `Product` value (e.g. `useProduct().product`) can use this
+ * instead of touching the registry directly.
+ *
+ * `productBrandColors` is the per-product override map from the app store
+ * (`useProduct().productBrandColors`). When set, the matching entry retints
+ * the resolved config end-to-end (mark + suffix). Pass `undefined` or `{}` to
+ * use the registry defaults.
+ */
+export function brandForProduct(
+  product: Product,
+  customBrand?: CustomProductBrand | null,
+  productBrandColors?: Partial<Record<Product, string>>,
+): ProductBrandConfig {
+  const base = product === "exxat-custom"
+    ? customProductBrandConfig(customBrand)
+    : getProductBrand(product) ?? EXXAT_ONE_BRAND
+  return applyBrandColorOverride(base, productBrandColors?.[product])
+}