@s3pweb/shell-ui 0.1.0

package/dist/lib/popover-offsets.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Single source of truth for every popover/tooltip `sideOffset` in shell-ui.
+ *
+ * The goal: regardless of the trigger element's actual size, every popover
+ * lands the same visual distance past the row's edge (top-bar) or past the
+ * sidebar's right edge (sidebar). Without these constants, each call site
+ * tunes its own number and they drift apart as triggers get added or resized.
+ *
+ * If you find yourself hardcoding a `sideOffset` somewhere, add a new entry
+ * here instead. Document what the trigger's geometry is so the value is
+ * recomputable when the trigger changes.
+ */
+/** Visual gap between any popover and the trigger's containing row / column edge. */
+export declare const POPOVER_GAP = 8;
+/**
+ * Top-bar popovers (open downward).
+ *
+ * The header row is 38 px tall (h-10 ghost icon Button). Triggers that fill
+ * that height (38 px Button) need offset = `POPOVER_GAP`. Shorter triggers
+ * (30 px nav buttons with `my-1`, 30 px partners chip centered in the row)
+ * sit 4 px above the row's bottom, so they need offset = `POPOVER_GAP + 4`
+ * to land at the same Y.
+ */
+export declare const TOPBAR_OFFSET: {
+    /** Trigger fills the row vertically — 38 px ghost icon Button. */
+    readonly fullRow: 8;
+    /** Trigger is shorter than the row — 30 px nav button or partners chip. */
+    readonly shortRow: number;
+};
+/**
+ * Sidebar popovers (open to the right).
+ *
+ * Geometry math (collapsed sidebar = 64 px wide):
+ *   - Nav-group / nav-item button: `w-full` inside the nav's `p-2`
+ *     → right edge at `64 - 8 = 56` (no scrollbar) or `64 - 8 - scrollbarWidth`
+ *     (with scrollbar). The `navGroup` constant assumes no scrollbar; for
+ *     dynamic compensation use `useSidebarScrollbarWidth()` and add the
+ *     measured width.
+ *   - Footer ActionButton (collapsed): 32×32 centered inside the footer's
+ *     `p-2` → right edge at `8 + (48 - 32) / 2 + 32 = 48`.
+ *   - User-section avatar: has its own `p-1` padding inside `p-2`, so the
+ *     visible avatar circle is further left — needs a much higher offset.
+ *
+ * All values land the popover at `sidebar_right + POPOVER_GAP` = 72.
+ */
+export declare const SIDEBAR_OFFSET: {
+    /** Nav-group / nav-item button — collapsed sidebar fly-out. */
+    readonly navGroup: 16;
+    /** Footer ActionButton — expanded mode (full-width row, right at sidebar_right − 8). */
+    readonly actionExpanded: 16;
+    /** Footer ActionButton — collapsed mode (centered 32 px button). */
+    readonly actionCollapsed: 24;
+    /** User-section avatar — expanded mode (full-width row with inner p-1). */
+    readonly userExpanded: 48;
+    /** User-section avatar — collapsed mode. */
+    readonly userCollapsed: 20;
+};

package/dist/lib/sidebar-layout-context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SidebarLayoutContext — provides live layout measurements from the Sidebar
+ * to its descendants. Currently exposes the nav scroll container's vertical
+ * scrollbar width so collapsed-mode flyouts can compensate their `sideOffset`
+ * and stay anchored at the sidebar's right edge regardless of scrollbar
+ * presence.
+ */
+export interface SidebarLayout {
+    /** 0 when no scrollbar; ~6–17 px depending on OS / theme when present. */
+    scrollbarWidth: number;
+}
+export declare const SidebarLayoutProvider: import('react').Provider<SidebarLayout>;
+export declare function useSidebarLayout(): SidebarLayout;

package/dist/lib/use-media-query.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Subscribe to a CSS media query. Returns `true` when the query matches.
+ *
+ * Uses `useSyncExternalStore` to bridge `MediaQueryList` to React's
+ * concurrent-render-safe subscription model — no `setState` inside `useEffect`
+ * and no extra render on mount.
+ *
+ * SSR-safe: the server snapshot returns `false`.
+ */
+export declare function useMediaQuery(query: string): boolean;

package/dist/lib/utils.d.ts

@@ -0,0 +1,2 @@
+import { ClassValue } from 'clsx';
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/preset.css

@@ -0,0 +1,140 @@
+/**
+ * Neutral defaults for @s3pweb/shell-ui.
+ * Import this in your app's CSS if you don't already provide these tokens
+ * (shadcn/ui-style apps usually do — in which case this file is unnecessary).
+ *
+ *   @import '@s3pweb/shell-ui/preset.css';
+ *
+ * Every color token shell-ui's components reference is declared in @theme
+ * so Tailwind v4 generates utilities for them (bg-primary, hover:bg-primary/10,
+ * text-popover-foreground, etc.). Brand themes override the *values* via the
+ * regular cascade; that's enough — Tailwind only cares that the tokens exist
+ * at @theme-time.
+ */
+
+/* Animation utilities (animate-in, fade-in-0, zoom-in-95, slide-in-from-*).
+   The shadcn Tooltip / DropdownMenu / Popover defaults reference these — without
+   this import the tooltip would still open, just without the fade/zoom/slide
+   transition. */
+@import 'tw-animate-css';
+
+/* Bind the `dark:` variant to a `.dark` ancestor (shadcn convention) instead
+   of the default `prefers-color-scheme` media query. Without this, a user
+   whose OS is set to dark mode would see dark-mode hover/focus colors in the
+   storybook even though the app itself is in light mode. */
+@custom-variant dark (&:is(.dark *));
+
+@theme {
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.145 0 0);
+  --color-card: oklch(1 0 0);
+  --color-card-foreground: oklch(0.145 0 0);
+  --color-popover: oklch(1 0 0);
+  --color-popover-foreground: oklch(0.145 0 0);
+  --color-primary: oklch(0.205 0 0);
+  --color-primary-foreground: oklch(0.985 0 0);
+  --color-secondary: oklch(0.97 0 0);
+  --color-secondary-foreground: oklch(0.205 0 0);
+  --color-muted: oklch(0.97 0 0);
+  --color-muted-foreground: oklch(0.5 0 0);
+  --color-accent: oklch(0.97 0 0);
+  --color-accent-foreground: oklch(0.205 0 0);
+  --color-border: oklch(0.922 0 0);
+  --color-input: oklch(0.922 0 0);
+  --color-ring: oklch(0.708 0 0);
+  --color-cta: oklch(0.205 0 0);
+  --color-cta-foreground: oklch(0.985 0 0);
+  --color-sidebar: oklch(0.97 0 0);
+  --color-sidebar-foreground: oklch(0.145 0 0);
+
+  /* Status tokens — needed for `text-success` / `bg-warning` /
+     `text-destructive` utilities used by RealtimePulse and any consumer
+     that surfaces success / warning / error states. Neutral defaults;
+     brand themes (e.g. s3pweb.css) can override the values. */
+  --color-success: oklch(0.62 0.18 145);
+  --color-success-foreground: oklch(0.985 0 0);
+  --color-warning: oklch(0.7 0.18 65);
+  --color-warning-foreground: oklch(0.145 0 0);
+  --color-destructive: oklch(0.55 0.22 25);
+  --color-destructive-foreground: oklch(0.985 0 0);
+
+  /* Radius scale — match the s3pweb design system so `rounded-md` etc.
+     resolve to the same pixels as the live SaaS shell (Tailwind v4's defaults
+     are otherwise sm=2px, md=6px, lg=8px, xl=12px — md would be too round). */
+  --radius-sm: 2px;
+  --radius-md: 4px;
+  --radius-lg: 6px;
+  --radius-xl: 8px;
+
+  /* Inter is the s3pweb / aftral house font; safe to set as default — apps that
+     ship their own --font-sans will override since their @theme is loaded later. */
+  --font-sans: Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+}
+
+.dark {
+  --color-background: oklch(0.145 0 0);
+  --color-foreground: oklch(0.985 0 0);
+  --color-card: oklch(0.205 0 0);
+  --color-card-foreground: oklch(0.985 0 0);
+  --color-popover: oklch(0.205 0 0);
+  --color-popover-foreground: oklch(0.985 0 0);
+  --color-primary: oklch(0.985 0 0);
+  --color-primary-foreground: oklch(0.205 0 0);
+  --color-secondary: oklch(0.269 0 0);
+  --color-secondary-foreground: oklch(0.985 0 0);
+  --color-muted: oklch(0.269 0 0);
+  --color-muted-foreground: oklch(0.65 0 0);
+  --color-accent: oklch(0.269 0 0);
+  --color-accent-foreground: oklch(0.985 0 0);
+  --color-border: oklch(0.269 0 0);
+  --color-input: oklch(0.269 0 0);
+  --color-ring: oklch(0.439 0 0);
+  --color-cta: oklch(0.985 0 0);
+  --color-cta-foreground: oklch(0.205 0 0);
+  --color-sidebar: oklch(0.269 0 0);
+  --color-sidebar-foreground: oklch(0.985 0 0);
+
+  /* Brighter status tokens for dark mode. */
+  --color-success: oklch(0.78 0.18 145);
+  --color-success-foreground: oklch(0.145 0 0);
+  --color-warning: oklch(0.82 0.17 75);
+  --color-warning-foreground: oklch(0.145 0 0);
+  --color-destructive: oklch(0.68 0.22 25);
+  --color-destructive-foreground: oklch(0.145 0 0);
+}
+
+/* Match shared-ui/themes/base.css — make Tailwind border utilities default
+   to the theme border token instead of currentColor, paint the body with the
+   theme tokens, and reset the cursor on interactive elements so buttons get
+   the pointer cursor users expect (Tailwind v4 preflight resets it to default,
+   which is jarring on shadcn buttons). */
+@layer base {
+  * {
+    border-color: var(--color-border);
+    outline-color: color-mix(in oklab, var(--color-ring) 50%, transparent);
+  }
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+  }
+  button,
+  a,
+  select,
+  summary,
+  label,
+  [role='button'],
+  [role='link'],
+  [role='tab'],
+  [role='checkbox'],
+  [role='radio'],
+  [role='switch'],
+  [role='menuitem'],
+  [role='option'],
+  [type='button'],
+  [type='submit'],
+  [type='reset'],
+  [type='checkbox'],
+  [type='radio'] {
+    cursor: pointer;
+  }
+}

package/dist/shell.d.ts

@@ -0,0 +1,85 @@
+import { ReactNode } from 'react';
+import { ShellLocale } from './i18n';
+import { RenderCollapsedTooltip, SidebarUser } from './sidebar';
+import { NavEntry, NavGroup, NavItem, ShellAction } from './types';
+export interface ShellProps {
+    /** Navigation entries (groups + leaf items). */
+    items: NavEntry[];
+    /** 'sidebar' renders a vertical aside on the left; 'top' renders a horizontal bar. */
+    navMode?: 'sidebar' | 'top';
+    /** Pass to control the mode externally — omit and Shell manages it locally. */
+    onNavModeChange?: (mode: 'sidebar' | 'top') => void;
+    collapsed?: boolean;
+    onCollapseToggle?: () => void;
+    collapsedLogo?: ReactNode;
+    topSlot?: ReactNode;
+    scrollActiveIntoView?: boolean;
+    renderCollapsedTooltip?: RenderCollapsedTooltip;
+    footer?: ReactNode;
+    footerExtra?: ReactNode;
+    userSection?: ReactNode;
+    logo?: ReactNode;
+    user?: SidebarUser;
+    onLogout?: () => void;
+    theme?: 'light' | 'dark';
+    onThemeToggle?: () => void;
+    /** Locale for built-in button labels. Default: `fr`. */
+    locale?: ShellLocale;
+    onItemSelect?: (item: NavItem, group?: NavGroup) => void;
+    onGroupToggle?: (group: NavGroup) => void;
+    /** Show the theme toggle when `onThemeToggle` is wired. Default: true. */
+    enableThemeToggle?: boolean;
+    /** Show the nav-mode toggle when `onNavModeChange` is wired (or Shell manages it locally). Default: true. */
+    enableNavModeToggle?: boolean;
+    /** Show the logout button when `onLogout` is wired. Default: true. */
+    enableLogoutButton?: boolean;
+    /**
+     * Show the decorative chevron that signals an icon-only nav entry has
+     * sub-items — the collapsed-sidebar `ChevronRight` and the top-bar
+     * `ChevronDown` cue. The expanded-sidebar accordion caret is NOT
+     * gated by this flag; it always renders because it doubles as the
+     * open/close state indicator. Default: false — opt in per-brand when
+     * the visual hint is desired.
+     */
+    showSubmenuIndicator?: boolean;
+    /**
+     * Collapse overflowing top-bar nav items, compact-mode actions, and the
+     * compact-mode sidebar footer into a single "Plus" / "…" popover when
+     * space is tight. Default: true. Pass `false` for brands whose nav fits
+     * the viewport at all sizes and prefer a flat chrome with no overflow
+     * trigger.
+     */
+    enablePlusOverflow?: boolean;
+    /** Extra action buttons rendered alongside the built-in cluster (e.g. fullscreen, mobile-mode). */
+    actions?: ShellAction[];
+    /**
+     * Content rendered inside a click-Popover anchored to the user avatar /
+     * name section. When set, that section becomes a ghost-button trigger
+     * (cursor pointer, hover background). When omitted, the user section
+     * stays non-interactive — matches the previous behaviour.
+     *
+     * The menu node itself is free-form JSX — typically a list of menu
+     * items (profile, preferences, help, …). Wrap each row in
+     * `<PopoverClose asChild>` so clicking dismisses the menu before
+     * running the row's action.
+     */
+    userMenu?: ReactNode;
+    /** Main content rendered next to the sidebar / under the top bar. */
+    children?: ReactNode;
+    /** Extra Tailwind classes on the root layout container. */
+    className?: string;
+    /** Tailwind classes for the main content wrapper. Default: `flex-1 overflow-auto`. */
+    mainClassName?: string;
+    /** Background class applied to the chrome surface — the `<aside>` in sidebar mode, the `<header>` in top mode. Overrides the defaults (bg-background / bg-sidebar). */
+    bgClassName?: string;
+}
+/**
+ * Stateless white-label shell that renders either a vertical sidebar or a
+ * horizontal top-nav based on `navMode`. The active layout switch is internal,
+ * so consumers don't need to compose Sidebar + a custom top-bar themselves.
+ *
+ *   <Shell items={...} navMode='sidebar' user={...}>
+ *     <Outlet />
+ *   </Shell>
+ */
+export declare function Shell({ items, navMode: navModeProp, onNavModeChange, collapsed, onCollapseToggle, collapsedLogo, topSlot, scrollActiveIntoView, renderCollapsedTooltip, footer, footerExtra, userSection, logo, user, onLogout, theme, onThemeToggle, locale, onItemSelect, onGroupToggle, enableThemeToggle, enableNavModeToggle, enableLogoutButton, showSubmenuIndicator, enablePlusOverflow, actions, userMenu, children, className, mainClassName, bgClassName, }: ShellProps): import("react/jsx-runtime").JSX.Element;

package/dist/sidebar.d.ts

@@ -0,0 +1,114 @@
+import { ReactNode } from 'react';
+import { ShellLocale } from './i18n';
+import { NavEntry, NavGroup, NavItem, ShellAction } from './types';
+export interface SidebarUser {
+    /** Display name (e.g. "Addwyn Lelann"). */
+    name: string;
+    /** Secondary line shown under the name (e.g. an email or role). */
+    subtitle?: string;
+    /** Initials shown in the avatar; defaults to first letter of the first two words of `name`. */
+    initials?: string;
+}
+/**
+ * Render-prop for wrapping a leaf item or group button in a tooltip when the
+ * sidebar is collapsed. Omit to fall back to the native `title` attribute.
+ */
+export type RenderCollapsedTooltip = (props: {
+    trigger: ReactNode;
+    entry: NavEntry;
+    isGroup: boolean;
+    onItemSelect?: (item: NavItem, group?: NavGroup) => void;
+}) => ReactNode;
+export interface SidebarProps {
+    /** Navigation entries to render. */
+    items: NavEntry[];
+    /** Collapsed state — controlled. Consumer owns this. */
+    collapsed?: boolean;
+    /** Called when the user clicks the collapse toggle. Consumer flips its own state. */
+    onCollapseToggle?: () => void;
+    /** Called when the user clicks a leaf nav item. Consumer wires this to its router. */
+    onItemSelect?: (item: NavItem, group?: NavGroup) => void;
+    /** Called when the user clicks a group header. Consumer flips group.expanded in its own state. */
+    onGroupToggle?: (group: NavGroup) => void;
+    /** Logo at the top of the sidebar. */
+    logo?: ReactNode;
+    /** Optional alternate logo shown when collapsed (smaller variant). */
+    collapsedLogo?: ReactNode;
+    /** Slot under the logo — typically an entity / structure picker. */
+    topSlot?: ReactNode;
+    /** When set, renders the built-in user section (avatar + name + subtitle + logout). */
+    user?: SidebarUser;
+    /** Called when the user clicks the logout button in the built-in user section. */
+    onLogout?: () => void;
+    /** Current theme. When `onThemeToggle` is provided, renders a Sun/Moon toggle button. */
+    theme?: 'light' | 'dark';
+    /** Called when the user clicks the theme toggle. */
+    onThemeToggle?: () => void;
+    /** Current navigation mode. When `onNavModeChange` is provided, renders a PanelLeft/PanelTop toggle. */
+    navMode?: 'sidebar' | 'top';
+    /** Called with the new mode when the user clicks the nav-mode toggle. */
+    onNavModeChange?: (mode: 'sidebar' | 'top') => void;
+    /** Show the theme toggle when `onThemeToggle` is wired. Default: true. */
+    enableThemeToggle?: boolean;
+    /** Show the nav-mode toggle when `onNavModeChange` is wired. Default: true. */
+    enableNavModeToggle?: boolean;
+    /** Show the logout button when `onLogout` is wired. Default: true. */
+    enableLogoutButton?: boolean;
+    /**
+     * Show the decorative `data-shell-ui-nav-has-children` ChevronRight on
+     * collapsed nav groups. The expanded-sidebar accordion caret is NOT
+     * gated by this flag — it always renders because it doubles as the
+     * open/close indicator. Default: false.
+     */
+    showSubmenuIndicator?: boolean;
+    /**
+     * Collapse the footer into a single "Plus" / "…" popover row below
+     * `max-height: 820px`. Default: true. Pass `false` to keep every footer
+     * control inline regardless of viewport height.
+     */
+    enablePlusOverflow?: boolean;
+    /** Extra action buttons rendered in the footer cluster (after theme/nav-mode, before user section). */
+    actions?: ShellAction[];
+    /** Locale for the built-in button labels (collapse / logout / theme / nav-mode). Default: `fr`. */
+    locale?: ShellLocale;
+    /** Replace the entire built-in user section with custom content. */
+    userSection?: ReactNode;
+    /**
+     * When set, wraps the avatar+name region in a click-Popover trigger
+     * with this content. The region picks up cursor-pointer + ghost-button
+     * hover styling. Doesn't apply when `userSection` is set (custom override).
+     */
+    userMenu?: ReactNode;
+    /** Replace the entire built-in footer (theme + nav-mode + any custom extras) with custom content. */
+    footer?: ReactNode;
+    /** Extra elements rendered above the built-in theme/nav-mode toggles (e.g. brand-specific actions). */
+    footerExtra?: ReactNode;
+    /** Auto-scroll the active item into view on first render. Default: true. */
+    scrollActiveIntoView?: boolean;
+    /** Render-prop for tooltips on collapsed items / groups. */
+    renderCollapsedTooltip?: RenderCollapsedTooltip;
+    /** Extra classes applied to the root <aside>. */
+    className?: string;
+}
+/**
+ * Stateless sidebar with built-in feature buttons (user / theme / nav-mode).
+ * The consumer owns:
+ *   - the router (active state is passed in via `item.active` / `group.active`)
+ *   - the collapsed / expanded / theme / nav-mode state (controlled props + callbacks)
+ *   - i18n (labels come in as props)
+ *
+ * Style: assumes Tailwind v4. Import `@s3pweb/shell-ui/preset.css` for neutral
+ * defaults or `@s3pweb/shell-ui/themes/{s3pweb,aftral}.css` for a brand theme.
+ */
+export declare function Sidebar({ items, collapsed: collapsedProp, onCollapseToggle, onItemSelect, onGroupToggle, logo, collapsedLogo, topSlot, user, onLogout, theme, onThemeToggle, navMode, onNavModeChange, enableThemeToggle, enableNavModeToggle, enableLogoutButton, showSubmenuIndicator, enablePlusOverflow, actions, locale, userSection, userMenu, footer, footerExtra, scrollActiveIntoView, renderCollapsedTooltip, className, }: SidebarProps): import("react/jsx-runtime").JSX.Element;
+export interface SidebarItemsProps {
+    items: NavEntry[];
+    collapsed?: boolean;
+    onItemSelect?: (item: NavItem, group?: NavGroup) => void;
+    onGroupToggle?: (group: NavGroup) => void;
+    scrollActiveIntoView?: boolean;
+    renderCollapsedTooltip?: RenderCollapsedTooltip;
+    /** Show the decorative chevron on collapsed groups. The accordion caret (expanded mode) is always shown. Default: false. */
+    showSubmenuIndicator?: boolean;
+}
+export declare function SidebarItems({ items, collapsed, onItemSelect, onGroupToggle, scrollActiveIntoView, renderCollapsedTooltip, showSubmenuIndicator, }: SidebarItemsProps): import("react/jsx-runtime").JSX.Element;

package/dist/themes/aftral.css

@@ -0,0 +1,46 @@
+/**
+ * @s3pweb/shell-ui — AFTRAL brand theme.
+ *
+ * Activated by adding `data-shell-theme="aftral"` on any ancestor of the
+ * shell-ui components. Pairs with the `.dark` class for dark mode.
+ *
+ *   @import '@s3pweb/shell-ui/themes/aftral.css';
+ *   <html class='dark' data-shell-theme='aftral'>...</html>
+ *
+ * Source palette: apps/aftral/src/theme/aftral.css (AFTRAL blue + green accent).
+ */
+
+[data-shell-theme='aftral'] {
+  --color-background: #ffffff;
+  --color-foreground: #123c5d;
+  --color-card: #ffffff;
+  --color-card-foreground: #123c5d;
+  --color-accent: #e3e8ec;
+  --color-accent-foreground: #123c5d;
+  --color-border: #d4dce2;
+  --color-muted-foreground: #4d6d86;
+
+  --color-primary: #123c5d;
+  --color-primary-foreground: #ffffff;
+}
+
+[data-shell-theme='aftral'].dark,
+.dark [data-shell-theme='aftral'] {
+  --color-background: oklch(0.22 0.015 250);
+  --color-foreground: oklch(0.93 0.008 240);
+  --color-card: oklch(0.26 0.015 250);
+  --color-card-foreground: oklch(0.93 0.008 240);
+  --color-accent: oklch(0.3 0.03 240);
+  --color-accent-foreground: oklch(0.93 0.008 240);
+  --color-border: oklch(0.34 0.02 240);
+  --color-muted-foreground: oklch(0.65 0.015 240);
+
+  --color-primary: oklch(0.72 0.16 142);
+  --color-primary-foreground: oklch(0.16 0.03 240);
+}
+
+/* AFTRAL decoration: solid primary background on active nav items. */
+[data-shell-theme='aftral'] [data-shell-ui-sidebar] [data-shell-ui-nav-item][data-active] {
+  background: var(--color-primary);
+  color: var(--color-primary-foreground);
+}