@creezio/shell-ui 0.22.0

package/ui/layout/desktop-update-banner.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import { getShellDesktopApi, getShellUiBrand } from "@creezio/shell-ui";
+
+/**
+ * Bannière quand une mise à jour desktop est disponible.
+ * Pas de toast : la barre suffit (évite le doublon coin haut-droit).
+ * Invisible hors app Electron.
+ */
+
+import { useEffect, useState } from "react";
+import { toast } from "sonner";
+import { ArrowUpCircle, Loader2, X } from "lucide-react";
+import { Button } from "../primitives/button";
+import type { DesktopUpdateStatus } from "../desktop-types";
+
+export function DesktopUpdateBanner() {
+  const [status, setStatus] = useState<DesktopUpdateStatus | null>(null);
+  const [dismissed, setDismissed] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    const api = getShellDesktopApi();
+    if (!api?.getUpdateStatus) return;
+    void api.getUpdateStatus().then(setStatus);
+    const unsub = api.onUpdateChanged?.(setStatus);
+    return () => unsub?.();
+  }, []);
+
+  if (!status) return null;
+  if (status.state === "disabled" || status.state === "not-available") return null;
+  if (!status.updateAvailable && status.state !== "downloading" && status.state !== "ready") {
+    return null;
+  }
+  if (
+    dismissed &&
+    status.availableVersion &&
+    dismissed === status.availableVersion &&
+    status.state === "available"
+  ) {
+    return null;
+  }
+
+  async function onInstall() {
+    const api = getShellDesktopApi();
+    if (!api?.downloadAndInstallUpdate) return;
+    setBusy(true);
+    try {
+      const s = await api.downloadAndInstallUpdate();
+      setStatus(s);
+      if (s.state === "error") toast.error(s.error || "Échec de la mise à jour");
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "Échec de la mise à jour");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const downloading = status.state === "downloading";
+  const version = status.availableVersion ?? "?";
+
+  return (
+    <div
+      role="status"
+      className="relative z-[55] flex flex-wrap items-center justify-center gap-2 bg-sky-600 px-3 py-2 text-center text-[13px] text-white"
+    >
+      <ArrowUpCircle className="h-4 w-4 shrink-0" />
+      <span className="font-medium">
+        {downloading
+          ? `Téléchargement de la mise à jour ${version}… ${Math.floor(status.percent ?? 0)} %`
+          : status.state === "ready"
+            ? `Mise à jour ${version} prête — redémarrage…`
+            : `Mise à jour ${version} disponible`}
+      </span>
+      {!downloading && status.state !== "ready" ? (
+        <Button
+          type="button"
+          size="sm"
+          variant="secondary"
+          className="h-7 bg-white text-sky-800 hover:bg-sky-50"
+          disabled={busy}
+          onClick={() => void onInstall()}
+        >
+          {busy ? <Loader2 className="mr-1 h-3.5 w-3.5 animate-spin" /> : null}
+          Mettre à jour
+        </Button>
+      ) : null}
+      {status.state === "available" ? (
+        <button
+          type="button"
+          className="absolute right-2 top-1/2 -translate-y-1/2 rounded p-1 text-white/80 hover:bg-white/10 hover:text-white"
+          aria-label="Masquer"
+          onClick={() => setDismissed(status.availableVersion ?? "x")}
+        >
+          <X className="h-4 w-4" />
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/ui/layout/entity-header.tsx

@@ -0,0 +1,44 @@
+import type { ReactNode } from "react";
+import { cn } from "@creezio/shell-ui";
+
+/**
+ * En-tête standard des fiches entité (contenu, sous le chrome sticky).
+ * Titre obligatoire — pas de H1 hors de ce composant.
+ */
+export function EntityHeader({
+  title,
+  description,
+  badges,
+  actions,
+  className,
+}: {
+  title: string;
+  description?: ReactNode;
+  badges?: ReactNode;
+  actions?: ReactNode;
+  className?: string;
+}) {
+  return (
+    <header
+      className={cn(
+        "flex flex-wrap items-start justify-between gap-3",
+        className,
+      )}
+    >
+      <div className="min-w-0 flex-1 space-y-2">
+        {badges ? (
+          <div className="flex flex-wrap items-center gap-2">{badges}</div>
+        ) : null}
+        <h1 className="text-xl font-semibold leading-snug tracking-tight text-slate-900 sm:text-2xl">
+          {title}
+        </h1>
+        {description ? (
+          <div className="text-sm text-slate-500">{description}</div>
+        ) : null}
+      </div>
+      {actions ? (
+        <div className="flex shrink-0 flex-wrap items-center gap-2">{actions}</div>
+      ) : null}
+    </header>
+  );
+}

package/ui/layout/native-os-nav.ts

@@ -0,0 +1,104 @@
+"use client";
+
+/**
+ * Nav OS native Creezio — adaptateur sidebar du catalogue unique.
+ *
+ * SoT = `registerOsNavEntry` / `defaultOsCatalogEntries()`
+ * (`@creezio/shell-ui`, `src/nav-catalog.ts`). Cette fonction ne fait
+ * que projeter le registre vers `SidebarNavItem[]` (icônes résolues).
+ *
+ * La marque DOIT monter `<NavCatalogLoader />` (Phase C) — **interdit**
+ * de recopier un `OS_NAV` inline. Fallback hors mount :
+ * `defaultOsPrimaryNavItems()`. Cible : `docs/plans/PLAN-NAV-CATALOG.md`.
+ * Hermes / n8n restent injectés par la sidebar kit (Admin → Outils).
+ *
+ * Feature-off plugins : passer `{ includePlugins: false }` à
+ * `defaultOsAdminNavItems` — ne pas lister `/admin/plugins`.
+ */
+import {
+  Activity,
+  Braces,
+  Cable,
+  Database,
+  KeyRound,
+  List,
+  Package,
+  ScrollText,
+  Settings,
+  ShieldCheck,
+} from "lucide-react";
+import {
+  defaultOsCatalogEntries,
+  type NavCatalogEntry,
+} from "../../dist/nav-catalog.js";
+import { resolveNavIcon } from "./nav-icons";
+import type { SidebarAdminItem, SidebarNavItem } from "./sidebar-host";
+
+function toSidebarNavItem(entry: NavCatalogEntry): SidebarNavItem {
+  return {
+    href: entry.href,
+    label: entry.label,
+    icon: resolveNavIcon(entry.icon),
+    fromShell: true,
+    permission: entry.permission,
+  };
+}
+
+/** Pages OS utilisateur (hors métier marque) — dérivé du registre. */
+export function defaultOsPrimaryNavItems(): SidebarNavItem[] {
+  return defaultOsCatalogEntries()
+    .filter(
+      (e) =>
+        e.available &&
+        e.defaultVisible &&
+        e.group !== "admin" &&
+        e.group !== "plugin",
+    )
+    .map(toSidebarNavItem);
+}
+
+export type OsAdminNavOptions = {
+  /**
+   * Inclure `/admin/plugins`. Défaut `true`.
+   * Mettre `false` si `manifest.features.plugins === false`.
+   */
+  includePlugins?: boolean;
+};
+
+/** Liens Admin OS (Hermes/n8n ajoutés à part par la sidebar kit). */
+export function defaultOsAdminNavItems(
+  opts?: OsAdminNavOptions,
+): SidebarAdminItem[] {
+  const includePlugins = opts?.includePlugins !== false;
+  const items: SidebarAdminItem[] = [
+    { href: "/configuration", label: "Configuration", icon: Settings },
+    { href: "/admin/analytics", label: "Analytics", icon: Activity },
+  ];
+  if (includePlugins) {
+    items.push({ href: "/admin/plugins", label: "Plugins", icon: Package });
+  }
+  items.push(
+    {
+      href: "/admin/access",
+      label: "Rôles & accès",
+      icon: ShieldCheck,
+      permission: "platform.access.manage",
+    },
+    {
+      href: "/admin/nav",
+      label: "Navigation",
+      icon: List,
+      permission: "platform.access.manage",
+    },
+    { href: "/admin/database", label: "Database", icon: Database },
+    { href: "/admin/integrations", label: "Intégrations", icon: KeyRound },
+    { href: "/admin/api", label: "API", icon: Braces },
+    { href: "/admin/mcp", label: "MCP", icon: Cable },
+    {
+      href: "/admin/request-logs",
+      label: "Logs API / MCP",
+      icon: ScrollText,
+    },
+  );
+  return items;
+}

package/ui/layout/nav-catalog-loader.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+/**
+ * Loader unique du catalogue sidebar — fetch `GET /api/v1/modules/nav`,
+ * bump `configureSidebar`, alimente `getNavItems`.
+ *
+ * Vit dans `@creezio/shell-ui/ui` pour que le chrome factory n'importe
+ * pas `@creezio/nav` au runtime UI. La factory **installe** quand même
+ * `@creezio/nav` (même vague publish) pour `/admin/nav` et le mount
+ * auto-register. `@creezio/nav/ui` re-exporte le même composant.
+ *
+ * Contrat items : `{ id, href, label, order, group?, permission?, icon }`.
+ */
+import { useEffect } from "react";
+import {
+  parseNavCatalogSessionItems,
+  type NavCatalogSessionItem,
+} from "../../dist/nav-catalog.js";
+import { defaultOsAdminNavItems } from "./native-os-nav";
+import { resolveNavIcon } from "./nav-icons";
+import {
+  configureSidebar,
+  getSidebarHostOptional,
+  type SidebarHost,
+  type SidebarNavItem,
+} from "./sidebar-host";
+
+export const NAV_CATALOG_ENDPOINT = "/api/v1/modules/nav";
+
+export function mapNavCatalogSessionToSidebar(
+  items: readonly NavCatalogSessionItem[],
+): SidebarNavItem[] {
+  return items
+    .filter((item) => item.group !== "admin" && item.group !== "plugin")
+    .slice()
+    .sort((a, b) => a.order - b.order || a.id.localeCompare(b.id))
+    .map((item) => ({
+      href: item.href,
+      label: item.label,
+      icon: resolveNavIcon(item.icon),
+      fromShell: item.group === "core" || item.group === undefined,
+      permission: item.permission,
+    }));
+}
+
+export function applyNavCatalogItemsToSidebar(
+  items: readonly NavCatalogSessionItem[],
+  opts?: { includePlugins?: boolean },
+): void {
+  const prev = getSidebarHostOptional();
+  const next: SidebarHost = {
+    ...(prev ?? { getNavItems: () => [] }),
+    getNavItems: () => mapNavCatalogSessionToSidebar(items),
+    getAdminItems:
+      prev?.getAdminItems ??
+      (() => defaultOsAdminNavItems({ includePlugins: opts?.includePlugins })),
+  };
+  configureSidebar(next);
+}
+
+export type NavCatalogLoaderProps = {
+  endpoint?: string;
+  includePlugins?: boolean;
+};
+
+/**
+ * Monte dans le chrome (sous `RequireSession`). Premier paint = fallback
+ * `defaultOsPrimaryNavItems()` déjà posé par `configureSidebar` ; après
+ * GET / le host est remplacé et la sidebar se re-rend (version bump).
+ */
+export function NavCatalogLoader(props: NavCatalogLoaderProps = {}): null {
+  const endpoint = props.endpoint ?? NAV_CATALOG_ENDPOINT;
+  const includePlugins = props.includePlugins;
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const res = await fetch(endpoint, {
+          credentials: "include",
+          headers: { Accept: "application/json" },
+        });
+        if (!res.ok || cancelled) return;
+        const body: unknown = await res.json();
+        const items = parseNavCatalogSessionItems(body);
+        if (cancelled || items.length === 0) return;
+        applyNavCatalogItemsToSidebar(items, { includePlugins });
+      } catch {
+        /* fallback : configureSidebar initial (catalogue OS local) */
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [endpoint, includePlugins]);
+
+  return null;
+}

package/ui/layout/nav-icons.ts

@@ -0,0 +1,67 @@
+"use client";
+
+/**
+ * Résolution nom lucide → composant. Allowlist kit (ceux déjà utilisés
+ * par la sidebar OS + Bot / NotebookPen). Inconnu → `Circle` + warning,
+ * jamais de throw UI.
+ */
+import {
+  Activity,
+  Bot,
+  Braces,
+  Cable,
+  Circle,
+  Database,
+  FileText,
+  KeyRound,
+  LayoutDashboard,
+  List,
+  ListTodo,
+  Mail,
+  NotebookPen,
+  Package,
+  ScrollText,
+  Settings,
+  Shield,
+  ShieldCheck,
+  SlidersHorizontal,
+  SquarePen,
+  Workflow,
+  type LucideIcon,
+} from "lucide-react";
+import { isKnownNavIcon } from "../../dist/nav-catalog.js";
+
+const NAV_ICONS: Record<string, LucideIcon> = {
+  Activity,
+  Bot,
+  Braces,
+  Cable,
+  Circle,
+  Database,
+  FileText,
+  KeyRound,
+  LayoutDashboard,
+  List,
+  ListTodo,
+  Mail,
+  NotebookPen,
+  Package,
+  ScrollText,
+  Settings,
+  Shield,
+  ShieldCheck,
+  SlidersHorizontal,
+  SquarePen,
+  Workflow,
+};
+
+export function resolveNavIcon(name: string): LucideIcon {
+  const icon = NAV_ICONS[name];
+  if (icon && isKnownNavIcon(name)) return icon;
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(
+      `[shell-ui] resolveNavIcon: icône inconnue "${name}", fallback Circle`,
+    );
+  }
+  return Circle;
+}

package/ui/layout/page-chrome.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { Fragment } from "react";
+import Link from "next/link";
+import { GlobalSearchTrigger } from "../global-search";
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "../primitives/breadcrumb";
+import { cn } from "@creezio/shell-ui";
+import { normalizeHref } from "../workspace/types";
+import type { PageKind, TrailCrumb } from "../workspace/types";
+import { usePageToolbarActions } from "./page-toolbar-context";
+
+/**
+ * Bandeau unique sous les onglets workspace.
+ * - section : recherche + actions (titre = label d'onglet uniquement)
+ * - entity  : recherche + fil d'Ariane + actions
+ */
+export function PageChrome({
+  kind,
+  href,
+  trail,
+}: {
+  kind: PageKind;
+  href: string;
+  trail?: TrailCrumb[];
+}) {
+  const actions = usePageToolbarActions(normalizeHref(href));
+  const crumbs: TrailCrumb[] =
+    kind === "entity" && trail && trail.length > 0 ? trail : [];
+
+  return (
+    <div className="-mx-2 border-b border-slate-200/80 bg-white px-3 py-2 sm:-mx-3 sm:px-4 md:-mx-4 md:px-5">
+      <div className="flex min-h-9 items-center gap-2 sm:gap-3">
+        <div
+          className={cn(
+            "min-w-0 shrink-0",
+            kind === "entity" ? "w-full max-w-[14rem] sm:max-w-xs" : "max-w-md flex-1",
+          )}
+        >
+          <GlobalSearchTrigger variant="toolbar" />
+        </div>
+
+        {kind === "entity" && crumbs.length > 0 ? (
+          <div className="min-w-0 flex-1 overflow-hidden">
+            <Breadcrumb>
+              <BreadcrumbList className="flex-nowrap">
+                {crumbs.map((c, i) => {
+                  const last = i === crumbs.length - 1;
+                  // Le séparateur (un <li>) doit être FRÈRE de BreadcrumbItem
+                  // (aussi un <li>) — un <li> imbriqué dans un <li> est du HTML
+                  // invalide qui casse l'hydratation React (mismatch #418).
+                  return (
+                    <Fragment key={`${c.label}-${i}`}>
+                      {i > 0 ? <BreadcrumbSeparator /> : null}
+                      <BreadcrumbItem className="min-w-0">
+                        {last || !c.href ? (
+                          <BreadcrumbPage
+                            className={cn(!last && "font-normal text-slate-500")}
+                          >
+                            {c.label}
+                          </BreadcrumbPage>
+                        ) : (
+                          <BreadcrumbLink asChild>
+                            <Link href={c.href}>{c.label}</Link>
+                          </BreadcrumbLink>
+                        )}
+                      </BreadcrumbItem>
+                    </Fragment>
+                  );
+                })}
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+        ) : null}
+
+        {actions ? (
+          <div className="ml-auto flex shrink-0 flex-wrap items-center justify-end gap-2">
+            {actions}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/ui/layout/page-toolbar-context.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { normalizeHref } from "../workspace/types";
+
+/** Clé stable pour la toolbar : pathname seul (les vues `?view=` partagent les actions). */
+export function toolbarKey(href: string): string {
+  return normalizeHref(href).split("?")[0] || "/";
+}
+
+type RegisterFn = (href: string, actions: ReactNode | null) => void;
+
+const RegisterContext = createContext<RegisterFn | null>(null);
+const ToolbarVersionContext = createContext(0);
+
+/** Ref module — lecture synchrone dans usePageToolbarActions sans recréer le contexte. */
+const entriesRef = { current: new Map<string, ReactNode | null>() };
+
+export function PageToolbarProvider({ children }: { children: ReactNode }) {
+  const [version, bump] = useState(0);
+
+  const register = useCallback<RegisterFn>((href, actions) => {
+    const key = toolbarKey(href);
+    const prev = entriesRef.current.get(key);
+    if (actions == null) {
+      if (!entriesRef.current.has(key)) return;
+      entriesRef.current.delete(key);
+    } else if (prev === actions) {
+      return;
+    } else {
+      entriesRef.current.set(key, actions);
+    }
+    bump((n) => n + 1);
+  }, []);
+
+  return (
+    <RegisterContext.Provider value={register}>
+      <ToolbarVersionContext.Provider value={version}>
+        {children}
+      </ToolbarVersionContext.Provider>
+    </RegisterContext.Provider>
+  );
+}
+
+function useToolbarRegister(): RegisterFn | null {
+  return useContext(RegisterContext);
+}
+
+/** Publie les actions de page vers le bandeau sticky (clé = pathname de la pane). */
+export function useRegisterPageToolbar(
+  href: string | null,
+  actions?: ReactNode,
+) {
+  const register = useToolbarRegister();
+  const actionsRef = useRef(actions);
+  actionsRef.current = actions;
+
+  useLayoutEffect(() => {
+    if (!register || !href) return;
+    register(href, actionsRef.current ?? null);
+  });
+
+  useEffect(() => {
+    if (!register || !href) return;
+    return () => register(href, null);
+  }, [register, href]);
+}
+
+export function usePageToolbarActions(href: string): ReactNode | null {
+  const version = useContext(ToolbarVersionContext);
+  void version;
+  return entriesRef.current.get(toolbarKey(href)) ?? null;
+}

package/ui/layout/sandbox-banner.tsx

@@ -0,0 +1,38 @@
+/**
+ * Bandeau permanent en environnement sandbox (clone restaurant).
+ * Activé via APP_ENV=sandbox — jamais en prod / client.
+ *
+ * Lecture dynamique de process.env pour éviter l'inlining Next au build.
+ */
+function runtimeEnv(name: string): string {
+  return String((process.env as Record<string, string | undefined>)[name] ?? "").trim();
+}
+
+export function SandboxBanner() {
+  const env = runtimeEnv("APP_ENV").toLowerCase();
+  if (env !== "sandbox") return null;
+
+  const tenant = runtimeEnv("SANDBOX_TENANT") || "sandbox";
+  const url = runtimeEnv("SANDBOX_PUBLIC_URL");
+
+  return (
+    <div
+      role="status"
+      className="relative z-[60] flex items-center justify-center gap-3 bg-amber-500 px-3 py-1.5 text-center text-[12px] font-semibold tracking-wide text-amber-950"
+    >
+      <span className="rounded bg-amber-950/15 px-1.5 py-0.5 font-mono text-[10px] uppercase">
+        Sandbox
+      </span>
+      <span>
+        Environnement de test « {tenant} » — les changements ici ne touchent pas
+        l&apos;instance client
+        {url ? (
+          <>
+            {" "}
+            · <span className="font-mono font-normal">{url.replace(/^https?:\/\//, "")}</span>
+          </>
+        ) : null}
+      </span>
+    </div>
+  );
+}

package/ui/layout/section-view-shell.tsx

@@ -0,0 +1,73 @@
+import { Suspense, type ReactNode } from "react";
+import { AppShell } from "./app-shell";
+import {
+  ViewToggle,
+  ViewToggleSkeleton,
+  type ViewOption,
+} from "../list-toolbar";
+
+/** À ré-exporter depuis page.tsx des sections catalogue avec vues. */
+export const SECTION_VIEW_DYNAMIC = "force-dynamic" as const;
+
+export type SectionViewShellProps = {
+  title: string;
+  subtitle: string;
+  view: string;
+  viewOptions: readonly ViewOption[];
+  suspenseKey: string;
+  fallback: ReactNode;
+  children: ReactNode;
+};
+
+/**
+ * Shell section immédiat : AppShell + ViewToggle optimiste + Suspense catalogue.
+ * Le fetch lourd vit dans *-catalog.tsx (async server component).
+ */
+export function SectionViewShell({
+  title,
+  subtitle,
+  view,
+  viewOptions,
+  suspenseKey,
+  fallback,
+  children,
+}: SectionViewShellProps) {
+  return (
+    <AppShell
+      kind="section"
+      title={title}
+      subtitle={subtitle}
+      actions={<ViewToggle view={view} options={[...viewOptions]} />}
+    >
+      <Suspense key={suspenseKey} fallback={fallback}>
+        {children}
+      </Suspense>
+    </AppShell>
+  );
+}
+
+export type SectionViewLoadingProps = {
+  title: string;
+  subtitle?: string;
+  viewOptions: readonly ViewOption[];
+  contentFallback: ReactNode;
+};
+
+/** loading.tsx — même chrome que SectionViewShell (toggle skeleton + contenu). */
+export function SectionViewLoading({
+  title,
+  subtitle = "Chargement…",
+  viewOptions,
+  contentFallback,
+}: SectionViewLoadingProps) {
+  return (
+    <AppShell
+      kind="section"
+      title={title}
+      subtitle={subtitle}
+      actions={<ViewToggleSkeleton options={viewOptions} />}
+    >
+      {contentFallback}
+    </AppShell>
+  );
+}