feat(web): catalog shared primitives — ViewModeToggle, CatalogHeader, useViewMode

Three drift-prone catalog surfaces (main /catalog, /catalog/$brandName, and
the legacy CategoryViewToggle) each carried their own inline view-mode
toggle with subtly different aria labels, sizing, icon paths and even a
"Sutun" typo. New surfaces will inherit a single primitive.

- ViewModeToggle: grid/tree/columns radio-group with i18n labels driven by
  `catalog.view.*` keys; fan-out by passing `groupLabelKey`.
- useViewMode(key): centralises read/write of `brandViewMode`/`modelViewMode`
  in user-settings — page just owns its current value.
- CatalogHeader: title + subtitle + optional breadcrumb trail + back button +
  trailing actions slot, so every catalog drill page renders the same shell.

i18n: adds catalog.subtitle, catalog.view.{groupLabel,grid,list,columns},
catalog.{brandSearch,modelSearch}{Placeholder,NoMatch}, catalog.{hideLocked,
showLocked,lockedSection,lockedSectionHint,inPlanSection,goToModels,
selectBrandHint,columnsBrowseHint,sortLabel}, catalog.sort.{newest,oldest,
alphabetical}.

These primitives stand alone in this commit — the main /catalog and
brand-detail pages migrate to them in 10B and 10C.

apps/web/src/components/catalog/catalog-header.tsx

@@ -0,0 +1,72 @@
+import { Button } from "@sase/ui";
+import { Link } from "@tanstack/react-router";
+import { ArrowLeft } from "lucide-react";
+import type React from "react";
+
+interface Crumb {
+  label: string;
+  to?: string;
+  search?: Record<string, unknown>;
+}
+
+/**
+ * Shared header for catalog surfaces. Renders a breadcrumb trail (last item
+ * non-link), a title (the last crumb by default) and a slot for a trailing
+ * action (typically a view-mode toggle). Keeps drill pages visually
+ * consistent — main catalog, brand detail, sub-catalog selectors.
+ */
+export function CatalogHeader({
+  crumbs,
+  title,
+  subtitle,
+  onBack,
+  actions,
+}: {
+  crumbs?: Crumb[];
+  title: string;
+  subtitle?: string;
+  onBack?: () => void;
+  actions?: React.ReactNode;
+}) {
+  return (
+    <div className="flex flex-col gap-3 sm:flex-row sm:items-end sm:justify-between">
+      <div className="flex items-start gap-3">
+        {onBack && (
+          <Button variant="ghost" size="icon" onClick={onBack} className="mt-0.5 shrink-0">
+            <ArrowLeft className="size-4" />
+          </Button>
+        )}
+        <div className="min-w-0">
+          {crumbs && crumbs.length > 0 && (
+            <nav aria-label="breadcrumb" className="mb-1 text-xs text-muted-foreground">
+              {crumbs.map((c, i) => {
+                const isLast = i === crumbs.length - 1;
+                return (
+                  <span key={`${c.label}-${i}`}>
+                    {c.to && !isLast ? (
+                      <Link
+                        to={c.to}
+                        search={c.search as Record<string, string | undefined> | undefined}
+                        className="hover:underline"
+                      >
+                        {c.label}
+                      </Link>
+                    ) : (
+                      <span className={isLast ? "font-medium text-foreground" : undefined}>
+                        {c.label}
+                      </span>
+                    )}
+                    {!isLast && <span className="mx-1.5">/</span>}
+                  </span>
+                );
+              })}
+            </nav>
+          )}
+          <h1 className="text-2xl font-bold leading-tight">{title}</h1>
+          {subtitle && <p className="mt-1 text-sm text-muted-foreground">{subtitle}</p>}
+        </div>
+      </div>
+      {actions && <div className="shrink-0">{actions}</div>}
+    </div>
+  );
+}

apps/web/src/components/catalog/view-mode-toggle.tsx

@@ -0,0 +1,77 @@
+import {
+  CardsViewIcon,
+  ListViewIcon,
+  TreeViewIcon,
+  type ViewIconProps,
+} from "@/components/categories/view-toggle-icons";
+import { useTranslation } from "@/lib/i18n";
+import { cn } from "@sase/ui";
+
+export type ViewMode = "grid" | "tree" | "columns";
+
+const OPTIONS: Array<{
+  value: ViewMode;
+  labelKey: string;
+  Icon: React.ComponentType<ViewIconProps>;
+}> = [
+  { value: "grid", labelKey: "catalog.view.grid", Icon: CardsViewIcon },
+  { value: "tree", labelKey: "catalog.view.list", Icon: TreeViewIcon },
+  { value: "columns", labelKey: "catalog.view.columns", Icon: ListViewIcon },
+];
+
+/**
+ * Shared 3-mode view toggle (grid / tree / columns) used across catalog
+ * surfaces. Replaces three separate inline implementations that drifted
+ * apart on labels, sizing, and a11y. `groupLabelKey` lets the caller scope
+ * the aria-label to its context (e.g. "brand view", "model view").
+ */
+export function ViewModeToggle({
+  value,
+  onChange,
+  groupLabelKey = "catalog.view.groupLabel",
+  className,
+}: {
+  value: ViewMode;
+  onChange: (mode: ViewMode) => void;
+  groupLabelKey?: string;
+  className?: string;
+}) {
+  const { t } = useTranslation();
+  return (
+    <div
+      // biome-ignore lint/a11y/useSemanticElements: a button group, not a form fieldset; role="group" is the correct ARIA here.
+      role="group"
+      aria-label={t(groupLabelKey)}
+      className={cn(
+        "inline-flex items-center gap-0.5 rounded-lg border border-border bg-muted/40 p-0.5",
+        className,
+      )}
+    >
+      {OPTIONS.map(({ value: v, labelKey, Icon }) => {
+        const active = value === v;
+        const label = t(labelKey);
+        return (
+          <button
+            key={v}
+            type="button"
+            aria-pressed={active}
+            aria-label={label}
+            title={label}
+            onClick={() => onChange(v)}
+            data-faro-user-action-name={`view-mode-${v}`}
+            className={cn(
+              "inline-flex h-8 w-8 items-center justify-center rounded-md",
+              "transition-colors duration-150",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+              active
+                ? "bg-background text-foreground shadow-sm"
+                : "text-muted-foreground hover:bg-background/60 hover:text-foreground",
+            )}
+          >
+            <Icon isActive={active} className="size-4" />
+          </button>
+        );
+      })}
+    </div>
+  );
+}

apps/web/src/lib/use-view-mode.ts

@@ -0,0 +1,26 @@
+import { getUserSettings, setUserSetting } from "@/lib/user-settings";
+import { useCallback, useState } from "react";
+
+type Setting = "brandViewMode" | "modelViewMode";
+export type ViewMode = "grid" | "tree" | "columns";
+
+/**
+ * View-mode state that mirrors localStorage via user-settings — same pattern
+ * the catalog pages were inlining. Returns the active mode and an updater
+ * that also persists. Decoupled from the toggle so any surface can read its
+ * persisted preference.
+ */
+export function useViewMode(
+  key: Setting,
+  fallback: ViewMode = "grid",
+): [ViewMode, (next: ViewMode) => void] {
+  const [mode, setMode] = useState<ViewMode>(() => getUserSettings()[key] ?? fallback);
+  const set = useCallback(
+    (next: ViewMode) => {
+      setMode(next);
+      setUserSetting(key, next);
+    },
+    [key],
+  );
+  return [mode, set];
+}

apps/web/src/messages/en.json

@@ -124,6 +124,7 @@
   },
   "catalog": {
     "title": "Parts Catalog",
+    "subtitle": "Browse brand catalogs — find parts without a VIN.",
     "brands": "Brands",
     "models": "Models",
     "allBrands": "All Brands",
@@ -133,6 +134,31 @@
     "locked": "This brand is not in your plan",
     "upgradeCta": "Upgrade Plan",
     "loadingModels": "Loading models...",
+    "view": {
+      "groupLabel": "View mode",
+      "grid": "Grid",
+      "list": "List",
+      "columns": "Columns"
+    },
+    "brandSearchPlaceholder": "Search brand",
+    "brandSearchNoMatch": "No brand matches \"{query}\"",
+    "modelSearchPlaceholder": "Search model, engine or year",
+    "modelSearchNoMatch": "No matching models",
+    "hideLocked": "Hide brands not in plan",
+    "showLocked": "Show brands not in plan",
+    "lockedSection": "Brands not in your plan",
+    "lockedSectionHint": "Upgrade to access these brands.",
+    "inPlanSection": "Brands in your plan",
+    "goToModels": "Browse models",
+    "selectBrandHint": "Select a brand from the left",
+    "columnsBrowseHint": "Pick a brand on the left and its models appear here.",
+    "modelCount2": "{count} model(s)",
+    "sortLabel": "Sort",
+    "sort": {
+      "newest": "Year (newest first)",
+      "oldest": "Year (oldest first)",
+      "alphabetical": "Model (A→Z)"
+    },
     "tabSasetr": "SASE",
     "tabPl24": "Pl24",
     "tabPcat": "Pcat",

apps/web/src/messages/tr.json

@@ -124,6 +124,7 @@
   },
   "catalog": {
     "title": "Parça Kataloğu",
+    "subtitle": "Marka kataloglarına göz at — şase bilmeden parça bul.",
     "brands": "Markalar",
     "models": "Modeller",
     "allBrands": "Tüm Markalar",
@@ -133,6 +134,31 @@
     "locked": "Bu marka planınızda yok",
     "upgradeCta": "Planını Yükselt",
     "loadingModels": "Modeller yükleniyor...",
+    "view": {
+      "groupLabel": "Görünüm modu",
+      "grid": "Izgara",
+      "list": "Liste",
+      "columns": "Sütun"
+    },
+    "brandSearchPlaceholder": "Marka ara",
+    "brandSearchNoMatch": "\"{query}\" ile eşleşen marka yok",
+    "modelSearchPlaceholder": "Model, motor veya yıl ara",
+    "modelSearchNoMatch": "Eşleşen model yok",
+    "hideLocked": "Plan dışı markaları gizle",
+    "showLocked": "Plan dışı markaları göster",
+    "lockedSection": "Plan dışı markalar",
+    "lockedSectionHint": "Erişmek istediğin markalar için planını yükselt.",
+    "inPlanSection": "Planındaki markalar",
+    "goToModels": "Modellere Git",
+    "selectBrandHint": "Soldan bir marka seç",
+    "columnsBrowseHint": "Soldaki listeden bir marka seçince modeller burada görünür.",
+    "modelCount2": "{count} model",
+    "sortLabel": "Sırala",
+    "sort": {
+      "newest": "Yıla göre (yeniden eskiye)",
+      "oldest": "Yıla göre (eskiden yeniye)",
+      "alphabetical": "Modele göre (A→Z)"
+    },
     "tabSasetr": "SASE",
     "tabPl24": "Pl24",
     "tabPcat": "Pcat",