@s3pweb/shell-ui 0.1.0

package/README.md

@@ -0,0 +1,337 @@
+# @s3pweb/shell-ui
+
+Stateless, white-label-ready application shell for React. A single `<Shell>`
+component renders either a **vertical sidebar** or a **horizontal top-nav**
+based on a `navMode` prop. The consumer owns router, i18n, auth, and state —
+Shell owns the chrome.
+
+```
+┌──────────────┬────────────────────────┐         ┌────────────────────────┐
+│ ▢  Logo      │                        │         │ Logo  ▢ ▢ ▢ ▢   👤 🌙  │
+│              │                        │         ├────────────────────────┤
+│ ▢ Home       │   <Outlet />           │   or    │                        │
+│ ▢ Inbox  ⓿   │                        │         │      <Outlet />        │
+│ ▼ Reports    │                        │         │                        │
+│ ▢ Settings   │                        │         │                        │
+└──────────────┴────────────────────────┘         └────────────────────────┘
+        navMode='sidebar'                                navMode='top'
+```
+
+## Design
+
+- **No router, no i18n provider, no state library.** Pass `items` with
+  `active: boolean` flags and an `onItemSelect` callback. Wire to your router.
+- **Hybrid controlled / uncontrolled.** `collapsed`, `navMode`, and per-group
+  `expanded` work zero-config; pass props + callbacks to persist them.
+- **Theming via Tailwind v4 tokens.** All colors live in CSS variables
+  (`--color-primary`, `--color-sidebar`, …). Override them per brand without
+  forking the component.
+- **No `@s3pweb/*` imports.** Externally consumable as-is.
+
+Runtime deps: `react`, `radix-ui`, `lucide-react`, `class-variance-authority`,
+`clsx`, `tailwind-merge`, `tw-animate-css`.
+
+## Install
+
+```bash
+pnpm add @s3pweb/shell-ui
+```
+
+Requires **React 19** and **Tailwind CSS v4** in the consumer app.
+
+## Public API
+
+```ts
+import {
+  Shell,            // <Shell> — sidebar OR top-nav, switched by navMode prop
+  Sidebar,          // <Sidebar> — vertical-only, exported for advanced layouts
+  SidebarItems,     // The nav-items list alone (used for mobile Sheet drawers)
+  isNavGroup,       // Type guard: NavEntry → NavGroup
+  type NavItem,
+  type NavGroup,
+  type NavEntry,    // NavItem | NavGroup
+  type SidebarUser, // { name, subtitle?, initials? }
+  type ShellLocale, // 'fr' | 'en'
+  type ShellProps,
+} from '@s3pweb/shell-ui';
+```
+
+## Minimal example (outside the monorepo)
+
+**`src/index.css`** — Tailwind v4, scan shell-ui sources, import the preset:
+
+```css
+@import 'tailwindcss';
+
+/* So Tailwind generates the utility classes shell-ui references. */
+@source "../node_modules/@s3pweb/shell-ui/src/**/*.{ts,tsx}";
+
+/* Neutral tokens + dark-variant binding + tw-animate-css.
+   Skip if your app already declares --color-primary, --color-sidebar, etc. */
+@import '@s3pweb/shell-ui/preset.css';
+
+/* Optional brand theme. */
+@import '@s3pweb/shell-ui/themes/s3pweb.css';
+```
+
+**`src/App.tsx`** — render the shell:
+
+```tsx
+import { useState } from 'react';
+import { BarChart3, FileText, Home, Inbox, Settings } from 'lucide-react';
+import { Shell, type NavEntry } from '@s3pweb/shell-ui';
+
+export function App() {
+  const [activeId, setActiveId] = useState('inbox');
+
+  const items: NavEntry[] = [
+    { id: 'home',  label: 'Home',  icon: <Home />,  active: activeId === 'home' },
+    {
+      id: 'inbox', label: 'Inbox', icon: <Inbox />, active: activeId === 'inbox',
+      badge: <span className="rounded-full bg-primary px-1.5 text-xs text-primary-foreground">12</span>,
+    },
+    {
+      id: 'reports', label: 'Reports', icon: <BarChart3 />,
+      active: activeId.startsWith('reports-'),
+      items: [
+        { id: 'reports-monthly',   label: 'Monthly',   icon: <FileText />, active: activeId === 'reports-monthly' },
+        { id: 'reports-quarterly', label: 'Quarterly', icon: <FileText />, active: activeId === 'reports-quarterly' },
+      ],
+    },
+    { id: 'settings', label: 'Settings', icon: <Settings />, active: activeId === 'settings' },
+  ];
+
+  return (
+    <Shell
+      items={items}
+      locale="en"
+      logo={<span className="text-lg font-semibold">ACME</span>}
+      user={{ name: 'Alex Dev', subtitle: 'alex@acme.com' }}
+      onItemSelect={(item) => setActiveId(item.id)}
+      onLogout={() => signOut()}
+      onThemeToggle={() => document.documentElement.classList.toggle('dark')}
+    >
+      <main className="p-8">
+        <h1 className="text-2xl font-semibold">Active: {activeId}</h1>
+      </main>
+    </Shell>
+  );
+}
+```
+
+No provider stack, no router required. Pass `navMode='top'` (or wire
+`onNavModeChange`) to swap chrome layout without touching the rest of the code.
+
+## Wiring inside the s3pweb monorepo
+
+Apps don't render `<Shell>` directly — they go through `MainLayout` in
+`@s3pweb/shared-layouts`, which bridges Zustand (`useUIStore`) → Shell props:
+
+```tsx
+// apps/s3pweb/src/app/main-layout.tsx
+<SharedMainLayout
+  logo={<S3pwebLogo />}
+  navigationItems={navigationItems}
+  bgClassName="bg-white"
+  variant="corporate"
+  enableNavModeToggle
+  user={user ? { name: user.fullName, subtitle: user.email } : undefined}
+  onLogout={logout}
+/>
+```
+
+```css
+/* apps/s3pweb/src/index.css */
+@import 'tailwindcss';
+@import 'tw-animate-css';
+
+@source "../../../packages/shell-ui/src/**/*.{ts,tsx}";
+/* ...other @source dirs... */
+
+@import '@s3pweb/shared-ui/themes/base.css';
+@import './theme/s3pweb.css';
+@import '@s3pweb/shell-ui/themes/s3pweb.css';
+```
+
+`MainLayout` reads `collapsed`, `navMode`, `theme`, `expandedNavGroups` from
+`useUIStore`, maps the app's `NavEntry` (with React Router metadata) into
+shell-ui's `NavEntry`, and renders `<Shell>` with a router-aware
+`onItemSelect={(item) => navigate(item.href)}`.
+
+## Brand themes
+
+Two pre-built brand themes ship with the package. They redefine the neutral
+tokens and add per-module decoration (icon chips, active-item accent line/dot).
+
+```css
+@import '@s3pweb/shell-ui/themes/s3pweb.css';
+/* or */
+@import '@s3pweb/shell-ui/themes/aftral.css';
+```
+
+Themes are scoped under `[data-shell-theme="s3pweb"]` (or `"aftral"`), so
+multiple brands can coexist in the same document. Activate one by setting the
+attribute on `<html>` or any ancestor:
+
+```html
+<html data-shell-theme="s3pweb">
+  ...
+</html>
+```
+
+Combine with the standard `.dark` class for dark mode:
+
+```html
+<html class="dark" data-shell-theme="s3pweb">
+```
+
+To roll your own theme, override the tokens in `:root` (or a scoped selector):
+
+```css
+:root {
+  --color-primary: oklch(0.3 0.1 240);
+  --color-primary-foreground: oklch(0.98 0 0);
+  --color-cta: oklch(0.85 0.15 90);
+  --color-sidebar: oklch(0.97 0 0);
+}
+```
+
+## Per-module decoration (`slug`)
+
+Every `NavEntry` is rendered with `data-shell-ui-nav-slug="..."` on three
+surfaces — the sidebar group, the sidebar flat leaf, and the top-bar button —
+so brand CSS can paint a module-specific chip in all three layouts with a
+single rule.
+
+**`slug` defaults to `id`** — only set it explicitly when you need a
+CSS-friendly theme key that's different from your id (e.g. your `id` is a
+route path like `/incidents` or a UUID like `inc-1234`):
+
+```tsx
+{ id: '/incidents', slug: 'incidents', label: 'Incidents', icon: <Bell />, items: [...] }
+```
+
+### Canonical palette rule
+
+To paint one slug, list all three selectors in a single rule (they share
+declarations). The `:not([data-shell-ui-nav-children] *)` clause excludes
+sub-items inside an expanded group so only top-level items get the chip.
+
+```css
+[data-shell-theme='s3pweb'] [data-shell-ui-nav-slug='foo'] [data-shell-ui-nav-group-button] [data-shell-ui-nav-icon],
+[data-shell-theme='s3pweb'] [data-shell-ui-nav-item][data-shell-ui-nav-slug='foo']:not([data-shell-ui-nav-children] *) [data-shell-ui-nav-icon],
+[data-shell-theme='s3pweb'] [data-shell-ui-top-bar-button][data-shell-ui-nav-slug='foo'] {
+  background: var(--color-emerald-100);
+  color:      var(--color-emerald-700);
+}
+.dark [data-shell-theme='s3pweb'] [data-shell-ui-nav-slug='foo'] [data-shell-ui-nav-group-button] [data-shell-ui-nav-icon],
+.dark [data-shell-theme='s3pweb'] [data-shell-ui-nav-item][data-shell-ui-nav-slug='foo']:not([data-shell-ui-nav-children] *) [data-shell-ui-nav-icon],
+.dark [data-shell-theme='s3pweb'] [data-shell-ui-top-bar-button][data-shell-ui-nav-slug='foo'] {
+  background: color-mix(in oklab, var(--color-emerald-700) 28%, transparent);
+  color:      var(--color-emerald-300);
+}
+```
+
+### Shade tiers
+
+Tailwind 4.2.1 ships every family as `--color-{family}-{shade}`. Pick the tier
+that matches the family's chroma:
+
+- **Saturated** (red, orange, amber, yellow, lime, green, emerald, teal, cyan,
+  sky, blue, indigo, violet, purple, fuchsia, pink, rose) —
+  light: `bg=*-100 / fg=*-700`; dark: `bg=color-mix(*-700 28%, transparent) / fg=*-300`.
+- **Desaturated** (slate, gray, zinc, neutral, stone, olive) —
+  light: `bg=*-200 / fg=*-500`; dark: `bg=color-mix(*-500 30%, transparent) / fg=*-300`.
+  Their `*-700` reads almost black against a `*-100` bg, so the tier shifts.
+- **One-step darker** (when two slugs share a family and you want them distinct) —
+  light: `bg=*-300 / fg=*-800`; dark: `bg=color-mix(*-800 36%, transparent) / fg=*-300`.
+
+The shipped `themes/s3pweb.css` keeps the per-slug palette block empty by
+default (every chip neutral) — see the long comment in that file for a
+copy-paste-ready template; uncomment and add rules per module as needed.
+
+## Slots & extras
+
+| Prop                     | Where                       | Use case                              |
+|--------------------------|-----------------------------|---------------------------------------|
+| `logo` / `collapsedLogo` | Sidebar top / top-bar left  | Brand mark                            |
+| `topSlot`                | Sidebar, above the nav list | Entity selector, search box           |
+| `userSection`            | Sidebar footer              | Custom user widget (replaces default) |
+| `footer` / `footerExtra` | Sidebar footer              | Status pill, secondary CTA            |
+| `bgClassName`            | Sidebar `<aside>` / `<header>` | `bg-white`, `bg-sidebar`, etc.     |
+| `mainClassName`          | The `<Outlet />` wrapper    | Padding, scroll behavior              |
+| `renderCollapsedTooltip` | Collapsed sidebar tooltip   | Override default tooltip content      |
+
+## Locale
+
+Built-in button labels (Collapse / Expand / Logout / Dark mode / etc.) are
+embedded in the package. Pass `locale="fr"` (default) or `locale="en"` — no
+i18n provider needed. The strings are exposed via `getShellStrings(locale)`
+for advanced use.
+
+## Storybook
+
+```bash
+pnpm --filter @s3pweb/shell-ui storybook         # dev server on :6006
+pnpm --filter @s3pweb/shell-ui build-storybook   # static build to ./storybook-static
+```
+
+Three stories ship out of the box:
+
+- **Shells / S3pweb** — replicates the s3pweb SaaS nav (Carte, Messagerie,
+  Éco-conduite, Maintenance, Social, Incidents, Prise de poste, Km/Carburant,
+  Nibelis).
+- **Shells / Aftral** — replicates the AFTRAL nav (Eco-driving + Coaching, plus
+  the Administration group for non-AFTRAL users).
+- **Playground / Configurable** — generic shell with Storybook Controls for
+  theme, locale, badges, groups, user/logo/toggles visibility. Events stream
+  to the Actions panel.
+
+Switch between light/dark mode via the Storybook toolbar.
+
+## Data types
+
+```ts
+interface NavItem {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+  active?: boolean;
+  badge?: ReactNode;
+  href?: string;       // Renders as <a href> for native browser semantics
+  meta?: unknown;      // Free-form payload, passed back via onItemSelect
+}
+
+interface NavGroup {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+  items: NavItem[];
+  active?: boolean;
+  expanded?: boolean;
+  slug?: string;       // data-shell-ui-nav-slug for per-module theming
+}
+
+type NavEntry = NavItem | NavGroup;
+```
+
+## Publishing externally
+
+This package is `"private": true` today. To publish to a registry:
+
+1. Build to `dist/` (e.g. `tsup --dts --format esm`)
+2. Set `"private": false` + bump `"version"`
+3. Update `"exports"` to point at `./dist/*` instead of `./src/*`
+4. Configure `publishConfig` for your registry
+5. `pnpm publish`
+
+The current `"exports"` entries:
+
+```jsonc
+{
+  ".":                    "./src/index.ts",
+  "./preset.css":         "./src/preset.css",
+  "./themes/s3pweb.css":  "./src/themes/s3pweb.css",
+  "./themes/aftral.css":  "./src/themes/aftral.css"
+}
+```

package/dist/components/actions-menu.d.ts

@@ -0,0 +1,45 @@
+import { ReactNode } from 'react';
+import { ShellAction } from '../types';
+export interface UseActionsMenuOptions {
+    /** The full set of actions the user can pin / unpin. */
+    actions: ShellAction[];
+    /** localStorage key for the pinned id set. Default `'shell-ui:pinnedActions'`. */
+    storageKey?: string;
+    /**
+     * Action IDs pinned by default — used the first time the hook mounts
+     * (no localStorage entry yet). Default: every action ID (all pinned).
+     */
+    defaultPinned?: string[];
+    /** Menu trigger label / panel heading. Default `'Actions'`. */
+    menuLabel?: string;
+    /** Menu trigger placement in the chrome cluster. Default `'trailing'`. */
+    menuPlacement?: 'leading' | 'trailing';
+    /** Draw a divider after the menu trigger. Default false. */
+    menuDividerAfter?: boolean;
+    /** Override the menu trigger icon. Default lucide `Puzzle`. */
+    menuIcon?: ReactNode;
+    /** Override the menu trigger's action id. Default `'__actions-menu__'`. */
+    menuId?: string;
+    /** Labels for the pin toggle button (i18n). */
+    pinLabel?: string;
+    unpinLabel?: string;
+}
+export interface UseActionsMenuReturn {
+    /** Pass straight to `<Shell actions={...}>`: pinned subset + the menu trigger appended. */
+    visibleActions: ShellAction[];
+    /** Set of currently-pinned action IDs. */
+    pinnedIds: Set<string>;
+    /** Pin / unpin imperatively (alongside the panel's pin buttons). */
+    togglePin: (id: string) => void;
+}
+export declare function useActionsMenu({ actions, storageKey, defaultPinned, menuLabel, menuPlacement, menuDividerAfter, menuIcon, menuId, pinLabel, unpinLabel, }: UseActionsMenuOptions): UseActionsMenuReturn;
+export interface ActionsMenuPanelProps {
+    actions: ShellAction[];
+    pinnedIds: Set<string>;
+    onTogglePin: (id: string) => void;
+    title?: string;
+    pinLabel?: string;
+    unpinLabel?: string;
+    className?: string;
+}
+export declare function ActionsMenuPanel({ actions, pinnedIds, onTogglePin, title, pinLabel, unpinLabel, className }: ActionsMenuPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/button.d.ts

@@ -0,0 +1,16 @@
+import { VariantProps } from 'class-variance-authority';
+import * as React from 'react';
+/**
+ * Button — shadcn/ui Button installed via `npx shadcn@latest add button`,
+ * customized with the s3pweb design-system values (rounded-sm, font-semibold,
+ * 38px icon size, brand-tuned ghost hover) so the shell's top-bar / footer
+ * buttons render identically to the live SaaS shell.
+ */
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
+    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<'button'> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export { Button, buttonVariants };

package/dist/components/ecosystem-mega-panel.d.ts

@@ -0,0 +1,37 @@
+import { Partner } from './partner-cluster';
+/**
+ * EcosystemMegaPanel — the "L'écosystème …" popover panel from the partners
+ * maquette, ported to React. Designed to live inside a Radix Popover (passed
+ * via `PartnerCluster.popoverContent` or `ShellAction.clickContent`), with
+ * panel-internal links wrapped in `<PopoverClose asChild>` so a click both
+ * dismisses the popover and opens the partner site in a new tab.
+ *
+ * Built-in fr/en strings, override any of them via the explicit props. Any
+ * Partner with an `href` opens that URL in a new tab; partners without `href`
+ * still render but their link is non-functional (href='#').
+ */
+export interface EcosystemMegaPanelProps {
+    /** Partners to render. */
+    partners: Partner[];
+    /** Heading line. Default: 'L'écosystème' / 'The ecosystem'. */
+    title?: string;
+    /** Sub-heading paragraph. Default: localised generic. */
+    subtitle?: string;
+    /** Footer-left label. Default: '{N} services connectés à votre compte'. */
+    connectedLabel?: string;
+    /** Footer-right action label. Default: 'Tout découvrir →' / 'Discover all →'. */
+    seeAllLabel?: string;
+    /** When set, the "see all" footer item renders as an `<a target='_blank' href>`. */
+    seeAllHref?: string;
+    /** Click callback for the "see all" footer (fires alongside href navigation if both are set). */
+    onSeeAllClick?: () => void;
+    /** Click callback when a partner row is clicked. Fires alongside href navigation. */
+    onPartnerClick?: (partner: Partner) => void;
+    /** Show the 'Nous' / 'Part.' kind tag next to each name. Default true. */
+    showKindTag?: boolean;
+    /** Locale for built-in strings. Default 'fr'. */
+    locale?: 'fr' | 'en';
+    /** Extra Tailwind classes on the panel root (override width / padding). */
+    className?: string;
+}
+export declare function EcosystemMegaPanel({ partners, title, subtitle, connectedLabel, seeAllLabel, seeAllHref, onSeeAllClick, onPartnerClick, showKindTag, locale, className, }: EcosystemMegaPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/hover-card.d.ts

@@ -0,0 +1,16 @@
+import { HoverCard as HoverCardPrimitive } from 'radix-ui';
+import * as React from 'react';
+/**
+ * HoverCard — shadcn-style wrapper around Radix HoverCard, mirroring the
+ * brand-themed Tooltip in `./tooltip.tsx`. Use it for any rich-content popup
+ * that should open on hover (e.g. a partners list, user-profile preview,
+ * avatar tooltip with metadata). When you need keyboard-equivalent click
+ * semantics or a focus-trapped menu, reach for DropdownMenu instead.
+ *
+ * Defaults: openDelay 200ms / closeDelay 100ms — felt right against the
+ * existing Tooltip's instant open. Override per-instance when needed.
+ */
+declare function HoverCard({ openDelay, closeDelay, ...props }: React.ComponentProps<typeof HoverCardPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+declare function HoverCardTrigger({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
+declare function HoverCardContent({ className, align, sideOffset, children, ...props }: React.ComponentProps<typeof HoverCardPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+export { HoverCard, HoverCardTrigger, HoverCardContent };

package/dist/components/layout-switcher.d.ts

@@ -0,0 +1,52 @@
+/**
+ * LayoutSwitcher — ports the `s3p-app-header--layoutButton` from the s3pweb
+ * Stencil app into shell-ui as a **stateless, click-emitting** button. The
+ * consumer owns the layout state (typically a `useState` persisted to
+ * `localStorage`), and is responsible for opening whatever picker modal /
+ * drawer wires up to the click.
+ *
+ * If the consumer wants the keyboard-shortcut behaviour from the original
+ * (pressing 1-9 / AZERTY `& é " ' ( - è _ ç` to jump to a layout), they wire
+ * a `window.addEventListener('keydown')` themselves — the component does NOT
+ * attach any global listener.
+ *
+ * Use the `variant` prop to render:
+ *   - **compact** (default, top-bar): 38×38 ghost-button with the
+ *     `LayoutGrid` icon + a small primary-coloured badge in the
+ *     bottom-right corner showing the current value.
+ *   - **row** (expanded sidebar): full-width footer row matching the other
+ *     sidebar toggles — icon + label + badge on the right.
+ *
+ * For collapsed-sidebar mode (where shell-ui falls back to the standard
+ * icon button), use `<LayoutNumberIcon>` as the action's `icon` so the
+ * number badge is still visible at 16px.
+ */
+export interface LayoutSwitcherProps {
+    /** Current layout value (typically 1-9). Rendered as the badge. */
+    value: number;
+    /** Fires when the trigger is clicked. Consumer opens its picker / modal here. */
+    onClick?: () => void;
+    /**
+     * Visual variant:
+     *   - 'compact' (default): 38×38 ghost-button, icon + corner badge.
+     *   - 'row': h-8 full-width row, icon + label + trailing badge.
+     */
+    variant?: 'compact' | 'row';
+    /** Title (native tooltip + aria-label prefix). Default 'Gérer les dispositions'. */
+    title?: string;
+    /** Label shown in the `row` variant. Default = `title`. */
+    label?: string;
+    /** Extra Tailwind classes on the root button. */
+    className?: string;
+}
+export declare function LayoutSwitcher({ value, onClick, variant, title, label, className }: LayoutSwitcherProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Icon-slot variant of LayoutSwitcher: a 16×16 `LayoutGrid` with a small
+ * primary-coloured number badge overflowing the bottom-right corner. Use
+ * as `ShellAction.icon` when the action's `customTrigger` is skipped (e.g.
+ * in the collapsed-sidebar fallback) but you still want the badge visible.
+ */
+export declare function LayoutNumberIcon({ value, className }: {
+    value: number;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/partner-cluster.d.ts

@@ -0,0 +1,111 @@
+import * as React from 'react';
+/**
+ * Partner-cluster widget — replicates the "Nos solutions" header pattern from
+ * the s3pweb partners maquette (claude-maquette-partners). Use it as the
+ * trigger of a `ShellAction` with `clickContent` / `hoverContent` set, e.g.:
+ *
+ *   { id: 'solutions', label: 'Nos solutions',
+ *     icon: <Layers />,                       // sidebar fallback
+ *     customTrigger: <PartnerCluster partners={ECOSYSTEM} chipBorderColor='white' />,
+ *     clickContent: <YourMegaPanel /> }
+ *
+ * The cluster paints a small label, the first N partner tiles overlapped
+ * (-7px stride, ringed with `chipBorderColor` to mask the overlap against the
+ * chrome bg), and a "+M" overflow chip when there are more partners than
+ * `maxVisible`. Each tile uses a 16% tint of the partner's brand colour for
+ * its bg and the full brand colour for the mark stroke.
+ */
+export interface Partner {
+    id: string;
+    name: string;
+    /** Brand hex colour (e.g. '#2E6BE6'). */
+    color: string;
+    /**
+     * Brand mark — rendered inside the tile as-is. Pass any ReactNode:
+     *   - SVG paths wrapped via `svgMark(...)` (or your own `<svg>` element)
+     *   - `<img src='/favicons/x.png' alt='X' />` for raster brand icons
+     *   - any custom component
+     *
+     * The tile constrains the mark to ~60% of its width/height; any inner
+     * `<svg>` or `<img>` automatically fills that slot.
+     */
+    mark: React.ReactNode;
+    /** Optional one-line tagline shown in detail / popover layouts. */
+    tagline?: string;
+    /** Optional category — free-form (e.g. 'Financement', 'Optimisation'). */
+    category?: string;
+    /** Optional taxonomy tag — 'solution' = ours, 'partner' = external. */
+    kind?: 'solution' | 'partner';
+    /** Optional URL — handy for popover content that links to the partner site. */
+    href?: string;
+}
+/**
+ * Mix a hex colour toward white by `ratio` (0 = white, 1 = full colour).
+ * Mirrors `ECO.tint()` in the maquette's ecosystem.js. Returns an rgb() string.
+ */
+export declare function tintColor(hex: string, ratio?: number): string;
+/**
+ * Convenience helper for the most common Partner.mark case: raw SVG path
+ * content lifted from a design source. Wraps the paths in a 24×24 viewBox
+ * with `stroke=currentColor` so the brand colour cascades from the tile.
+ *
+ *   mark: svgMark(<><circle cx='12' cy='12' r='8'/><path d='...'/></>)
+ */
+export declare function svgMark(paths: React.ReactNode, opts?: {
+    strokeWidth?: number;
+}): React.ReactNode;
+export interface PartnerTileProps extends React.HTMLAttributes<HTMLSpanElement> {
+    partner: Partner;
+    /** Outer square edge in px. Default 30. */
+    size?: number;
+    /** Solid mode: bg=brand colour, glyph=white. Default tinted bg + brand glyph. */
+    solid?: boolean;
+    /** Border-radius in px. Defaults to ~28% of `size`. */
+    radius?: number;
+    /** Optional 2px ring colour painted around the tile (used inside PartnerCluster). */
+    ringColor?: string;
+}
+export declare function PartnerTile({ partner, size, solid, radius, ringColor, className, style, title, ...props }: PartnerTileProps): import("react/jsx-runtime").JSX.Element;
+export interface PartnerClusterProps extends React.HTMLAttributes<HTMLDivElement> {
+    partners: Partner[];
+    /** Tiles shown before the +N overflow chip. Default 4. */
+    maxVisible?: number;
+    /**
+     * Small label shown to the left of the tiles. Default: no label.
+     * Pass a string (e.g. 'Nos solutions') to display one.
+     */
+    label?: string | null;
+    /** Tile edge in px. Default 30. */
+    tileSize?: number;
+    /**
+     * Colour painted on the 2px ring around each tile / the +N chip to mask the
+     * -7px overlap against the chrome's background. Should match the
+     * surrounding bg — defaults to `var(--color-sidebar)`. Pass `'white'` (or
+     * a Tailwind colour variable) when the chrome uses a different bg.
+     */
+    chipBorderColor?: string;
+    /**
+     * Content rendered inside the click-Popover anchored to the +N overflow
+     * chip. When the cluster has no overflow (maxVisible >= partners.length)
+     * the popover won't have a trigger — keep `maxVisible` below
+     * `partners.length` if you rely on this.
+     */
+    popoverContent?: React.ReactNode;
+    /** Popover side. Default 'bottom' (top-bar context). Use 'right' when the cluster sits in a sidebar. */
+    popoverSide?: 'top' | 'right' | 'bottom' | 'left';
+    /** Popover align. Default 'end'. */
+    popoverAlign?: 'start' | 'center' | 'end';
+    /** Popover offset from the trigger in px. Default 8. */
+    popoverSideOffset?: number;
+    /** Locale for built-in labels (the overflow chip title). Default 'fr'. */
+    locale?: 'fr' | 'en';
+}
+/**
+ * The cluster is NOT a single button. Each visible tile is an independent
+ * `<a target='_blank'>` when its partner has an `href` (otherwise a
+ * non-interactive `<span>`), and the `+N` chip is a separate `<button>` that
+ * opens `popoverContent` in a Popover. Effect: clicking a tile goes straight
+ * to that partner's site, clicking `+N` opens the full panel — matching the
+ * maquette's UX.
+ */
+export declare function PartnerCluster({ partners, maxVisible, label, tileSize, chipBorderColor, popoverContent, popoverSide, popoverAlign, popoverSideOffset, locale, className, ...props }: PartnerClusterProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/popover.d.ts

@@ -0,0 +1,24 @@
+import { Popover as PopoverPrimitive } from 'radix-ui';
+import * as React from 'react';
+/**
+ * Popover — shadcn-style wrapper around Radix Popover, mirroring the
+ * brand-themed Tooltip + HoverCard primitives. Use it for click-triggered
+ * rich-content popups (vs. HoverCard's hover semantics).
+ */
+declare function Popover({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+declare function PopoverTrigger({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Use to decouple the popover's positioning anchor from its click trigger.
+ * Typical case: a row of items where ONE small button opens the popover, but
+ * the popover should anchor to the whole row so it doesn't move when the
+ * trigger's `transform` changes on hover.
+ */
+declare function PopoverAnchor({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Anchor>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Wraps a child element so clicking it closes the popover (Radix forwards the
+ * click + close to the underlying element via `asChild`). Use to make
+ * panel-internal links / buttons dismiss the popover before navigating.
+ */
+declare function PopoverClose({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Close>): import("react/jsx-runtime").JSX.Element;
+declare function PopoverContent({ className, align, sideOffset, children, ...props }: React.ComponentProps<typeof PopoverPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+export { Popover, PopoverTrigger, PopoverAnchor, PopoverClose, PopoverContent };