@the-portland-company/shell 0.92.0 → 0.93.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.93.0
+
+Tab icons come from the Brand tab icon map (Reference/UI-Platform → Tabs, "Tab icon map (Brand `tabIcons`)", Ben 2026-10-24).
+
+- **`NavTabStrip` `iconStrip` prop** (optional, e.g. `iconStrip="forms"`). Each tab reads `--tab-icon-<iconStrip>-<tab.key>` from `:root` (emitted by `/api/tokens?format=css`) and renders the named Lucide icon at the tab icon size (15px / 13px small, 1.75 stroke, `text-current`). Missing, empty or unknown names render the tab's own `icon`. One `<head>` MutationObserver per strip re-reads when the Brand stylesheet loads; no `window` access during render. Without `iconStrip` nothing changes.
+- **New `resolveTabGlyph(name)` and `KNOWN_TAB_GLYPHS`** (main entry and `./native`): the 124-name tab icon vocabulary, kebab-case Lucide names mapped to `react-icons/lu` components. `resolveTabGlyph` trims, strips quotes and lowercases; it returns `null` for an unknown name. Also exports the `TabGlyphComponent` type.
+- `react-icons/lu` is external in the build (like `react-icons/fi`); `./native` still has no Chakra, emotion or react-router dependency.
+- Tests: `__tests__/tabIconMap.test.tsx`.
+
 ## 0.92.0
 
 Politogy ID gets its own registry row (Reference/UI-Platform: each app that renders the chrome has its own `POLITOGY_APPS` row).

package/README.md

@@ -142,7 +142,7 @@ All `<ShellChrome>` props are optional — only supply what your app has. The ch
 | `<Card>` | Page-level layout primitive. |
 | `<PageHeader>` | The page header (Reference/UI-Platform → "Page header"): no filled surface, 22px below the top bar, 24px gutter (16px below `md`), spans its container. Eyebrow in the mode color, 30px bold Graphite `h1` title, 15px G4 subtitle, `actions` right, `tabBar` beneath. `breadcrumbs` and `maxW` are **deprecated** (accepted, ignored, warn once in dev); width comes from `FormColumn` (960px) or the fluid frame. Warns in dev if `title` / `subtitle` is a string holding an email address. |
 | `<FormColumn>` | The one constrained layout inside the frame's fluid `<main>`: a left-aligned column, `max-width: 960px`, for form and settings pages. Also exported from `./native`. |
-| `<NavTabStrip>` (from `./native`) | The canonical page tab strip: underlined text tabs with a 2px underline in the mode color. Render it in the page body, below the page header. |
+| `<NavTabStrip>` (from `./native`) | The canonical page tab strip: underlined text tabs with a 2px underline in the mode color. Render it in the page body, below the page header. Pass `iconStrip` to take tab icons from the Brand tab icon map (see below). |
 | `<PageContainer>`, `<BreadcrumbBar>`, `<HeaderTabBar>` | **Deprecated for apps** (each warns in dev). The frame owns a fluid `<main>` (24px gutter, 16px below `md`, no max-width); there are no breadcrumbs; the tab strip is `NavTabStrip`. |
 | `<GlobalUiIdProvider>` | Assigns stable UI IDs (for testing/analytics). |
 
@@ -176,6 +176,29 @@ All `<ShellChrome>` props are optional — only supply what your app has. The ch
 
 `PageHeader`, `Card`, `FormColumn`, and the deprecated `BreadcrumbBar` and `HeaderTabBar` are also exported from `@the-portland-company/shell/native`, which needs no Chakra or react-router peer.
 
+## Tab icons from the Brand map (`iconStrip`)
+
+Every tab icon comes from the Brand tab icon map (`tabIcons`, edited in the Brand editor's "Tab Icons" section; Reference/UI-Platform → Tabs). Pass your app's strip key and keep your current icons as the fallback:
+
+```tsx
+import { NavTabStrip } from '@the-portland-company/shell/native'
+
+<NavTabStrip
+  iconStrip="forms"
+  aria-label="Forms"
+  tabs={[
+    { key: 'forms', label: 'Forms', icon: LuFileText, href: '/forms', selected: true },
+    { key: 'canvas', label: 'Canvas', icon: LuLayoutTemplate, href: '/canvas' },
+  ]}
+/>
+```
+
+- For each tab the strip reads `--tab-icon-<iconStrip>-<tab.key>` (emitted on `:root` by `/api/tokens?format=css`, e.g. `--tab-icon-forms-canvas: "layout-template"`) and renders that Lucide icon at the tab icon size (15px, 13px on `size="sm"`, 1.75 stroke, `currentColor`).
+- One `<head>` observer per strip re-reads the variables when the Brand stylesheet loads, so icons upgrade from the fallback without a reload. Nothing reads `window` during render (SSR-safe).
+- When the variable is missing, empty, or names an icon the shell does not know, the tab renders its own `icon` prop. Without `iconStrip` the strip behaves as before.
+- The tab slug is the tab's `key`. The strip key is lowercase kebab-case, one per strip (`contacts`, `contacts-tribes`, `forms`, `surveys`, `settings`, …).
+- The vocabulary is `KNOWN_TAB_GLYPHS` (124 Lucide kebab-case names); `resolveTabGlyph(name)` maps a name (trimmed, quotes stripped, lowercased) to its `react-icons/lu` component or `null`. Both are exported from the main entry and `./native`. Adding a name is a shell minor release; the Brand editor offers only these names.
+
 ## shell-version-check
 
 `shell-version-check` (a package `bin`, so `npx shell-version-check` works after install) exits 1 when the app's declared shell range cannot install the latest published version (`npm view`, 10s timeout; exit 2 if that lookup fails). `--offline` compares against the installed shell version instead; `--cwd=<dir>` checks another package.