@exxatdesignux/ui 0.2.15 → 0.2.17

package/template/components/{data-list-table.tsx → placements-table.tsx}

@@ -1,7 +1,15 @@
 "use client"
 
 /**
- * DataListTable — list hub shell on top of the generic DataTable.
+ * PlacementsTable — placements hub composition on top of the generic
+ * `DataTable`. Owns: placement-specific column defs, board column grouping,
+ * KPI dashboards, the "open table properties" imperative handle, and the
+ * lifecycle persistence wiring (via `useTableStateLifecycle`).
+ *
+ * NOTE: this is hub composition, NOT a parallel table primitive. Every hub
+ * has its own `*-table.tsx` of the same shape (`team-table.tsx`,
+ * `compliance-table.tsx`, …); all of them render `<DataTable>` from
+ * `@/components/data-table`.
  *
  * View tabs drive `view` (table | list | board | …). `lifecycleTabId` selects which **demo row
  * segment** (columns + filtered rows) to use — keep in sync with each tab's `filterId`, or pass
@@ -11,6 +19,7 @@
 import * as React from "react"
 import dynamic from "next/dynamic"
 import { cn } from "@/lib/utils"
+import { mailtoHref } from "@/lib/mailto"
 import { useRouter } from "next/navigation"
 import { Button } from "@/components/ui/button"
 import { Tip } from "@/components/ui/tip"
@@ -48,15 +57,14 @@ import {
   DEFAULT_DATA_LIST_DISPLAY_OPTIONS,
   type DataListDisplayOptions,
 } from "@/lib/data-list-display-options"
-import {
-  applyLifecyclePersisted,
-  loadLifecycleFromStorage,
-  scheduleLifecycleSave,
-  serializeLifecycle,
-  type TableStatePersistSlice,
-} from "@/lib/data-list-persistence"
+import { useTableStateLifecycle } from "@/lib/table-state-lifecycle"
+import type { PlacementsLifecycleExtras } from "@/lib/data-list-persistence"
+
+/** Storage namespace for the placements hub. Keep `"data-list"` so existing
+ *  user payloads in localStorage remain readable. */
+const PLACEMENTS_LIFECYCLE_NAMESPACE = "data-list"
 import type { OpenTablePropertiesHandle } from "@/lib/list-page-table-properties"
-import { StatusBadge } from "@/components/data-list-table-cells"
+import { StatusBadge } from "@/components/placements-table-cells"
 import { columnsToFilterFields } from "@/components/placements-table-columns"
 import { DataTable, DataTableToolbar } from "@/components/data-table"
 import { CountSyncer, PaginationBar } from "@/components/data-table/pagination"
@@ -127,9 +135,14 @@ function DataListBoardShell({
   displayOptions: DataListDisplayOptions
   onDisplayOptionsChange: (patch: Partial<DataListDisplayOptions>) => void
 }) {
+  // Store the "open properties drawer" callback on a stable ref so the parent
+  // imperative handle can invoke it without re-rendering the whole table.
+  // `state` is freshly returned each render by useTableState; only the React
+  // setter is stable and needed here.
   React.useEffect(() => {
     openDrawerRef.current = () => state.setSheetOpen(true)
-  }, [state.setSheetOpen])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openDrawerRef, state.setSheetOpen])
 
   const boardColumnMenu: PlacementsBoardColumnMenu = React.useMemo(
     () => ({
@@ -248,9 +261,11 @@ function DataListListShell({
   listRows: Placement[]
   emptyTableCopy: string
 }) {
+  // Stable "open properties drawer" callback ref — see top of this file.
   React.useEffect(() => {
     openDrawerRef.current = () => state.setSheetOpen(true)
-  }, [state.setSheetOpen])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openDrawerRef, state.setSheetOpen])
 
   return (
     <>
@@ -336,9 +351,11 @@ function DataListDashboardShell({
   displayOptions: DataListDisplayOptions
   onDisplayOptionsChange: (patch: Partial<DataListDisplayOptions>) => void
 }) {
+  // Stable "open properties drawer" callback ref — see top of this file.
   React.useEffect(() => {
     openDrawerRef.current = () => state.setSheetOpen(true)
-  }, [state.setSheetOpen])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openDrawerRef, state.setSheetOpen])
 
   const dashboardKpi = React.useMemo(
     () => ({
@@ -627,9 +644,11 @@ function DataListFolderShell({
 }) {
   const router = useRouter()
 
+  // Stable "open properties drawer" callback ref — see top of this file.
   React.useEffect(() => {
     openDrawerRef.current = () => state.setSheetOpen(true)
-  }, [state.setSheetOpen])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openDrawerRef, state.setSheetOpen])
 
   const boardColumns = state.displayCols.filter(c => c.key !== "select" && c.key !== "actions")
 
@@ -735,9 +754,11 @@ function DataListTreeShell({
   const boardColumns = state.displayCols.filter(c => c.key !== "select" && c.key !== "actions")
   const [selectedId, setSelectedId] = React.useState<number | null>(() => listRows[0]?.id ?? null)
 
+  // Stable "open properties drawer" callback ref — see top of this file.
   React.useEffect(() => {
     openDrawerRef.current = () => state.setSheetOpen(true)
-  }, [state.setSheetOpen])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openDrawerRef, state.setSheetOpen])
 
   React.useEffect(() => {
     if (selectedId == null) {
@@ -941,7 +962,7 @@ function PlacementFinderDetail({
                 <i className="fa-light fa-envelope text-[10px]" aria-hidden="true" /> Email
               </dt>
               <dd className="text-[13px]">
-                <a href={`mailto:${row.email}`} className="text-interactive-foreground hover:underline">{row.email}</a>
+                <a href={mailtoHref(row.email)} className="text-interactive-foreground hover:underline">{row.email}</a>
               </dd>
             </div>
           )}
@@ -1099,9 +1120,11 @@ function DataListPanelShell({
   panelRenderListRow?: (row: Placement, isSelected: boolean) => React.ReactNode
   panelRenderDetail?: (row: Placement) => React.ReactNode
 }) {
+  // Stable "open properties drawer" callback ref — see top of this file.
   React.useEffect(() => {
     openDrawerRef.current = () => state.setSheetOpen(true)
-  }, [state.setSheetOpen])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openDrawerRef, state.setSheetOpen])
 
   const boardColumns = state.displayCols.filter(c => c.key !== "select" && c.key !== "actions")
   const groups = React.useMemo(
@@ -1187,7 +1210,7 @@ function DataListPanelShell({
 // Props
 // ─────────────────────────────────────────────────────────────────────────────
 
-export interface DataListTableProps {
+export interface PlacementsTableProps {
   view?: DataListViewType
   onViewChange?: (view: DataListViewType) => void
   /** Demo row segment: drives filtered rows + column set (`all` | `upcoming` | `ongoing` | `completed`). */
@@ -1210,13 +1233,13 @@ export interface DataListTableProps {
 }
 
 /** Imperative handle — open Table Properties (table view only). */
-export type DataListTableHandle = OpenTablePropertiesHandle
+export type PlacementsTableHandle = OpenTablePropertiesHandle
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Main component
 // ─────────────────────────────────────────────────────────────────────────────
 
-export const DataListTable = React.forwardRef<DataListTableHandle, DataListTableProps>(function DataListTable({
+export const PlacementsTable = React.forwardRef<PlacementsTableHandle, PlacementsTableProps>(function PlacementsTable({
   view = "table",
   onViewChange,
   lifecycleTabId = "all",
@@ -1320,50 +1343,36 @@ export const DataListTable = React.forwardRef<DataListTableHandle, DataListTable
 
   const columnKeys = React.useMemo(() => new Set(columns.map(c => c.key)), [columns])
 
-  React.useLayoutEffect(() => {
-    const raw = loadLifecycleFromStorage(lifecycleTabId)
-    if (!raw) return
-    applyLifecyclePersisted(tableState as unknown as TableStatePersistSlice, raw, columnKeys)
-    setConditionalRules(raw.conditionalRules)
-    setPagination(raw.pagination)
-    setPaginationPage(raw.paginationPage)
-    setPaginationPageSize(raw.paginationPageSize)
-  }, [lifecycleTabId, columnKeys])
-
+  // Stable "open properties drawer" callback ref — see top of this file.
   React.useEffect(() => {
     openDrawerRef.current = () => tableState.setSheetOpen(true)
-  }, [tableState.setSheetOpen])
-
-  React.useEffect(() => {
-    const payload = serializeLifecycle(tableState as unknown as TableStatePersistSlice, {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openDrawerRef, tableState.setSheetOpen])
+
+  // ── Lifecycle persistence ─────────────────────────────────────────────
+  // Centralised in `lib/table-state-lifecycle` — one hook wires both the
+  // load (layout effect) and the debounced save (effect) including all the
+  // table slices plus placements-specific extras. Hubs that don't want
+  // localStorage persistence simply don't call this hook.
+  useTableStateLifecycle<PlacementsLifecycleExtras>({
+    namespace: PLACEMENTS_LIFECYCLE_NAMESPACE,
+    tabId: lifecycleTabId,
+    tableState,
+    columnKeys,
+    extras: {
       conditionalRules,
       pagination,
       paginationPage: safePage,
       paginationPageSize,
-    })
-    scheduleLifecycleSave(lifecycleTabId, payload)
-  }, [
-    lifecycleTabId,
-    tableState.sortRules,
-    tableState.search,
-    tableState.activeFilters,
-    tableState.filterConnectors,
-    tableState.groupBy,
-    tableState.colOrder,
-    tableState.hiddenCols,
-    tableState.colWidths,
-    tableState.colPins,
-    tableState.colWrap,
-    tableState.colMenuSearch,
-    tableState.rowHeight,
-    tableState.showGridlines,
-    tableState.filterBarVisible,
-    tableState.searchOpen,
-    conditionalRules,
-    pagination,
-    safePage,
-    paginationPageSize,
-  ])
+    },
+    onLoadExtras: e => {
+      if (!e) return
+      if (Array.isArray(e.conditionalRules)) setConditionalRules(e.conditionalRules as ConditionalRule[])
+      if (typeof e.pagination === "boolean") setPagination(e.pagination)
+      if (typeof e.paginationPage === "number") setPaginationPage(e.paginationPage)
+      if (typeof e.paginationPageSize === "number") setPaginationPageSize(e.paginationPageSize)
+    },
+  })
 
   function buildToolbarSlot(
     s: ReturnType<typeof useTableState<Placement>>,
@@ -1658,7 +1667,7 @@ export const DataListTable = React.forwardRef<DataListTableHandle, DataListTable
   return <DataTable<Placement> key={lifecycleTabId} {...tableProps} />
 })
 
-DataListTable.displayName = "DataListTable"
+PlacementsTable.displayName = "PlacementsTable"
 
 
 export type { DataListViewType } from "@/lib/data-list-view"

package/template/components/product-switcher.tsx

@@ -18,17 +18,30 @@ import {
 } from "@/components/ui/sidebar"
 import { ExxatProductLogo, ExxatProductMark } from "@/components/exxat-product-logo"
 import { useProduct, type Product } from "@/contexts/product-context"
+import { customProductBrandConfig, productBrandLabel } from "@/lib/product-brand"
 
 const PRODUCTS: { id: Product; label: string }[] = [
-  { id: "exxat-one",   label: "Exxat One"   },
-  { id: "exxat-prism", label: "Exxat Prism" },
+  { id: "exxat-one",        label: "Exxat One"        },
+  { id: "exxat-prism",      label: "Exxat Prism"      },
+  { id: "exxat-assessment", label: "Exxat Assessment" },
+  { id: "exxat-custom",     label: "Custom product"   },
 ]
 
 export function ProductSwitcher() {
-  const { product, setProduct } = useProduct()
+  const { product, setProduct, customProductBrand, hiddenProductIds } = useProduct()
   const { state, isMobile } = useSidebar()
 
-  const current = PRODUCTS.find(p => p.id === product) ?? PRODUCTS[0]
+  const products = React.useMemo(
+    () => PRODUCTS.flatMap(p => {
+      if (hiddenProductIds.includes(p.id)) return []
+      if (p.id !== "exxat-custom") return [p]
+      return customProductBrand
+        ? [{ ...p, label: productBrandLabel(customProductBrandConfig(customProductBrand)) }]
+        : []
+    }),
+    [customProductBrand, hiddenProductIds],
+  )
+  const current = products.find(p => p.id === product) ?? products[0]
   const iconRail = state === "collapsed" && !isMobile
   const expandedOrMobile = state === "expanded" || isMobile
 
@@ -51,11 +64,10 @@ export function ProductSwitcher() {
               suppressHydrationWarning
             >
               {iconRail ? (
+                // Collapsed icon-rail product mark must read as a peer of the
+                // school selector, without a white cutout patch on the rail.
                 <span className="flex size-8 shrink-0 items-center justify-center">
-                  <ExxatProductMark
-                    product={current.id}
-                    className="size-7 max-h-none"
-                  />
+                  <ExxatProductMark product={current.id} className="size-8" cutoutColor="var(--sidebar)" />
                 </span>
               ) : (
                 <>
@@ -66,7 +78,7 @@ export function ProductSwitcher() {
                     <ExxatProductLogo
                       product={current.id}
                       variant="mutedSuffix"
-                      className="h-7 w-auto max-w-[min(100%,260px)] object-left object-contain"
+                      className="w-auto max-w-[min(100%,260px)]"
                     />
                   </span>
                   <i
@@ -87,7 +99,7 @@ export function ProductSwitcher() {
               Switch product
             </DropdownMenuLabel>
             <DropdownMenuSeparator />
-            {PRODUCTS.map(p => (
+            {products.map(p => (
               <DropdownMenuItem
                 key={p.id}
                 onClick={() => setProduct(p.id)}
@@ -97,7 +109,10 @@ export function ProductSwitcher() {
                 <ExxatProductLogo
                   product={p.id}
                   variant="mutedSuffix"
-                  className="h-7 w-auto shrink-0 max-w-[min(100%,200px)]"
+                  // h-9 matches the sidebar trigger so the mark renders at the
+                  // same 32 px footprint in both contexts. Dropdown rows
+                  // accommodate the bump via `py-2` on `DropdownMenuItem`.
+                  className="h-9 w-auto shrink-0 max-w-[min(100%,240px)]"
                 />
                 {p.id === product && (
                   <i

package/template/components/product-wordmark.tsx

@@ -0,0 +1,285 @@
+"use client"
+
+/**
+ * ProductWordmark + ProductMark — render any product brand as a logo.
+ *
+ * - `ProductWordmark` renders `${prefix} ${suffix}` as HTML text:
+ *   • `prefix` (e.g. "Exxat") in `font-sans` extra-bold (Inter 800), neutral.
+ *   • `suffix` (e.g. "One" / "Prism" / "Pulse") in **Ivy Presto Italic**
+ *     (`var(--font-heading)`, Adobe Fonts kit `wuk5wqn` preloaded in
+ *     `app/layout.tsx`) tinted with `brandColor`.
+ *
+ *   We render real font glyphs rather than baked-in SVG paths so a new product
+ *   only needs `{ prefix, suffix, brandColor }` — no path-tracing required.
+ *
+ * - `ProductMark` renders the same "E"-style circular mark used by Exxat,
+ *   recolored with the brand's gradient / fill. The SVG geometry stays
+ *   constant so existing layouts keep working.
+ *
+ * `variant="mutedSuffix"` (used by the product switcher / sidebar): in **dark**
+ * mode only, the suffix tints to `--muted-foreground` so the wordmark recedes
+ * into the rail. Light mode keeps the brand color for recognition.
+ */
+
+import * as React from "react"
+import { cn } from "@/lib/utils"
+import type { ProductBrandConfig } from "@/lib/product-brand"
+
+export type ProductWordmarkVariant = "default" | "mutedSuffix"
+
+export interface ProductWordmarkProps {
+  config: ProductBrandConfig
+  variant?: ProductWordmarkVariant
+  className?: string
+}
+
+/* ── Wordmark ──────────────────────────────────────────────────────────────── */
+
+/**
+ * Inline product wordmark. Sizing is height-driven — the parent sets the
+ * height (e.g. `className="h-7"`) and the text scales via `text-[...]`
+ * derived from `--wordmark-size` (set inline from the rendered font-size).
+ *
+ * Use `aria-hidden` because the wordmark is decorative — pair it with an
+ * `aria-label` on the trigger/link (see {@link productBrandLabel}).
+ */
+export function ProductWordmark({
+  config,
+  variant = "default",
+  className,
+}: ProductWordmarkProps) {
+  const prefix = config.prefix ?? "Exxat"
+  const { suffix, brandColor, wordmarkColor } = config
+  const mutedSuffix = variant === "mutedSuffix"
+  const suffixColor = wordmarkColor ?? brandColor
+
+  return (
+    <span
+      aria-hidden="true"
+      data-product-wordmark
+      data-product-id={config.id}
+      className={cn(
+        // Inline-flex so it sits on a text baseline; whitespace-nowrap so the
+        // suffix never wraps under the prefix at narrow widths.
+        "inline-flex items-baseline whitespace-nowrap leading-none select-none",
+        // Sized **relative to the inherited font-size** so the wordmark always
+        // dominates whatever surface hosts it. The parent (`ProductLogo` /
+        // `ExxatProductLogo`) pins `text-base` (16 px) → this resolves to
+        // ~28 px wordmark text (~20 px cap), matching the cap-to-render-height
+        // ratio in the standalone Exxat brand assets (~0.72; image dims 446×124
+        // with ~89 px caps). Slight (~1 px) overflow against a 28 px parent
+        // height is acceptable — sidebar / switcher slots use `overflow-visible`.
+        "text-[1.78em] tracking-tight",
+        // Vertically centre the **cap mid-line** on the parent's mid-line.
+        // Without this nudge the cap sits ~9 % of font-size above span centre
+        // because Inter / Ivy Presto baseline metrics put glyphs in the upper
+        // portion of the line box. 0.09 em moves the cap centre down by that
+        // exact offset so it shares an axis with the mark centre.
+        "translate-y-[0.09em]",
+        className,
+      )}
+    >
+      <span
+        className={cn(
+          "font-sans font-extrabold",
+          // Neutral wordmark prefix: deep slate on light, soft cool grey on dark.
+          "text-[#273441] dark:text-[#A8B2BA]",
+        )}
+      >
+        {prefix}
+      </span>
+      <span
+        data-product-wordmark-suffix
+        className={cn(
+          // Per the official Exxat brand spec (Figma):
+          //   font-family: IvyPresto Text
+          //   weight:      SemiBold (600)  — NOT Bold / ExtraBold
+          //   tracking:   -3%              — overrides parent `tracking-tight`
+          //   line-height: auto            — inherited (parent sets `leading-none`)
+          // IvyPresto's Bodoni-lineage SemiBold already has the thick verticals
+          // that read as a logo; pushing to 700/800 makes the letterforms
+          // visually heavier than the brand asset.
+          "ms-[0.18em] font-semibold tracking-[-0.03em]",
+          // mutedSuffix: dark mode recedes to muted; light mode keeps brand.
+          mutedSuffix && "dark:!text-[var(--muted-foreground)]",
+        )}
+        style={{
+          // Ivy Presto Text from Adobe Fonts. Upright (NOT italic) — matches
+          // the official Exxat wordmark. Fallback chain ends in `serif` so
+          // FOUT still renders a serif that reads as a logo rather than Inter.
+          fontFamily: "var(--font-heading), 'ivypresto-text', Georgia, serif",
+          color: suffixColor,
+        }}
+      >
+        {suffix}
+      </span>
+    </span>
+  )
+}
+
+/* ── Circular mark ─────────────────────────────────────────────────────────── */
+
+export interface ProductMarkProps {
+  config: ProductBrandConfig
+  className?: string
+  cutoutColor?: string
+}
+
+/**
+ * Generate a stable id suffix for SVG gradient defs so multiple marks on the
+ * same page never collide. Strip colons because IDs in HTML/SVG can't legally
+ * include them (Radix uses `:`-style IDs by default).
+ */
+function useMarkGradientId(brandId: string) {
+  const raw = React.useId().replace(/:/g, "")
+  return `pmk-${brandId.replace(/[^a-z0-9-]/gi, "")}-${raw}`
+}
+
+/**
+ * Defer SVG `<defs>` (gradient refs) until after mount so server HTML matches
+ * the first client paint. `useId()` returns different suffixes in SSR vs CSR
+ * trees that conditionally mount the sidebar.
+ */
+function useBrowserPaintReady() {
+  const [ready, setReady] = React.useState(false)
+  React.useLayoutEffect(() => {
+    setReady(true)
+  }, [])
+  return ready
+}
+
+/**
+ * Recoloured Exxat "E" mark. Same geometry as the canonical brand mark, so
+ * existing pixel-aligned layouts (sidebar header, dropdown rows) don't shift.
+ *
+ * Fills:
+ *  - Outer circle: `markGradient` if provided, else flat `brandColor`.
+ *  - Inner shadow plate: `markShadow` (defaults to `brandColor`).
+ *  - Cut-out "E" strokes: white by default; callers can override on tinted rails.
+ */
+export function ProductMark({ config, className, cutoutColor = "white" }: ProductMarkProps) {
+  const ready = useBrowserPaintReady()
+  const gradId = useMarkGradientId(config.id)
+  const [from, to] = config.markGradient ?? [config.brandColor, config.brandColor]
+  const shadow = config.markShadow ?? config.brandColor
+
+  // No size default. Callers MUST set explicit dimensions (`size-7`, `h-full
+  // w-auto`, etc.). A `size-*` default here loses to a downstream `h-full /
+  // w-auto` only when `tailwind-merge` correctly identifies `size-7` as a
+  // `w-7 + h-7` shorthand — fragile across versions and causes the mark to
+  // render at the default size instead of the parent's height (see
+  // `ExxatProductLogo` h-full mark → 32 px in h-8 parent). Aspect-square stays
+  // so the mark renders as a circle when only one of width/height is set.
+  const sharedClass = cn(
+    "box-border block aspect-square shrink-0 flex-none object-contain",
+    className,
+  )
+
+  if (!ready) {
+    return (
+      <svg
+        viewBox="0 8.25 147 147"
+        preserveAspectRatio="xMidYMid meet"
+        fill="none"
+        xmlns="http://www.w3.org/2000/svg"
+        data-product-mark
+        data-product-logo-mark
+        data-product-id={config.id}
+        className={sharedClass}
+        aria-hidden="true"
+        suppressHydrationWarning
+      />
+    )
+  }
+
+  return (
+    <svg
+      viewBox="0 8.25 147 147"
+      preserveAspectRatio="xMidYMid meet"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      data-product-mark
+      data-product-logo-mark
+      data-product-id={config.id}
+      className={sharedClass}
+      aria-hidden="true"
+      suppressHydrationWarning
+    >
+      <path
+        d="M73.4939 155.238C114.084 155.238 146.988 122.334 146.988 81.7439C146.988 41.1544 114.084 8.25 73.4939 8.25C32.9044 8.25 0 41.1544 0 81.7439C0 122.334 32.9044 155.238 73.4939 155.238Z"
+        fill={`url(#${gradId})`}
+      />
+      <path
+        d="M0.594727 90.9915C4.59951 122.921 29.0894 148.466 60.4966 154.085L102.462 116.355V102.302H86.8312L102.462 88.2489V74.1957H86.8312L102.462 60.1425V46.0894H50.5575L0.594727 90.9915Z"
+        fill={shadow}
+      />
+      <path d="M102.474 116.355H50.5576L58.6764 102.302H102.474V116.355Z" fill={cutoutColor} />
+      <path d="M102.474 60.1303H58.6764L50.5576 46.0771H102.474V60.1303Z" fill={cutoutColor} />
+      <path d="M102.474 88.2368H66.7949L70.8483 81.2102L66.7949 74.1836H102.474V88.2368Z" fill={cutoutColor} />
+      <path d="M39.2227 74.1835H66.795L58.6762 60.1304H39.2227V74.1835Z" fill={cutoutColor} />
+      <path d="M39.2227 102.302H58.6762L66.795 88.2368H39.2227V102.302Z" fill={cutoutColor} />
+      <defs>
+        <linearGradient
+          id={gradId}
+          x1="28.3733"
+          y1="134.255"
+          x2="117.195"
+          y2="30.9074"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopColor={from} />
+          <stop offset="1" stopColor={to} />
+        </linearGradient>
+      </defs>
+    </svg>
+  )
+}
+
+/* ── Mark + wordmark combo ─────────────────────────────────────────────────── */
+
+export interface ProductLogoProps {
+  config: ProductBrandConfig
+  variant?: ProductWordmarkVariant
+  /** Render only the mark (omit the wordmark). */
+  markOnly?: boolean
+  /** Render only the wordmark (omit the mark). */
+  wordmarkOnly?: boolean
+  className?: string
+  /** Class applied to the inner mark — useful for sizing it independently. */
+  markClassName?: string
+  /** Class applied to the inner wordmark. */
+  wordmarkClassName?: string
+}
+
+/**
+ * Mark + wordmark composed inline. Pass `markOnly` for collapsed sidebar /
+ * favicon-like contexts, or `wordmarkOnly` if you've already rendered the
+ * mark separately (e.g. switcher dropdown rows).
+ */
+export function ProductLogo({
+  config,
+  variant = "default",
+  markOnly = false,
+  wordmarkOnly = false,
+  className,
+  markClassName,
+  wordmarkClassName,
+}: ProductLogoProps) {
+  if (markOnly) {
+    return <ProductMark config={config} className={cn(className, markClassName)} />
+  }
+  if (wordmarkOnly) {
+    return <ProductWordmark config={config} variant={variant} className={cn(className, wordmarkClassName)} />
+  }
+  return (
+    <span
+      aria-hidden="true"
+      data-product-logo
+      data-product-id={config.id}
+      className={cn("inline-flex items-center gap-2", className)}
+    >
+      <ProductMark config={config} className={cn("size-7", markClassName)} />
+      <ProductWordmark config={config} variant={variant} className={wordmarkClassName} />
+    </span>
+  )
+}