portal-mojo 0.1.0

package/src/ui/menu-registry.ts

@@ -0,0 +1,213 @@
+// Sidebar menu engine — the registry + resolution logic, ported from
+// web-mojo Sidebar.js (menus Map, autoSwitchToMenuForRoute, menuContainsRoute,
+// getGroupMenu/_groupKindMatches, _applyFallbackMenu, _menuHasVisibleItems).
+//
+// Menus are DATA in a registry; the sidebar renders whichever one is active.
+// web-mojo kept mutable active-menu state driven by events; here the active
+// menu is a PURE FUNCTION of (route, active group, me):
+//   1. the first registered menu whose visible items contain the route —
+//      group menus are eligible only when a kind-matched group is active
+//      (web-mojo skipped them only when NO group was active; requiring the
+//      kind match too is a deliberate tightening)
+//   2. otherwise the fallback chain: defaultMenu → first non-group menu with
+//      at least one visible item → first non-group menu
+// Entering a group menu happens by NAVIGATION (e.g. the app routes into the
+// group's home on switcher selection) — no hidden menu state to desync.
+//
+// Admin sections contribute menus through this same registry (see
+// portal-mojo/admin adminSectionsMenu) — sections never own the sidebar.
+import { matchPath } from 'react-router-dom';
+import { hasPermission, type Me, type MemberLike } from '../client/me';
+import type { PermSpec } from '../client/model';
+import type { Group } from '../client/group-context';
+
+export interface MenuItem {
+    /** Stable identity for route-less parents (accordion state, aria ids). */
+    id?: string;
+    /** Section label row (the side-label idiom). Mutually exclusive with route. */
+    divider?: string;
+    label?: string;
+    /** Extra quick-navigation terms that are never rendered. */
+    keywords?: string[];
+    icon?: string;
+    /** Absolute route within the hash router, e.g. '/users'. */
+    route?: string;
+    children?: MenuItem[];
+    /** Permission name(s) required to see the item (ANY-of; member-aware). */
+    permissions?: string | string[];
+    /**
+     * Additional permission clauses: ANY within one clause, AND across clauses.
+     * `permissions`, when present, is evaluated as one more required clause.
+     */
+    permissionClauses?: PermSpec[];
+    /** Only visible when the active group's kind matches. */
+    requiresGroupKind?: string | string[];
+    badge?: { text: string; tone?: 'success' | 'warning' | 'danger' | 'info' | 'muted' | 'primary' };
+}
+
+export interface MenuConfig {
+    name: string;
+    /** Shell metadata. Omitted group menus infer `group`; others infer `global`. */
+    scope?: 'admin' | 'group' | 'account' | 'global';
+    /** Route-less parents stay static unless a consumer explicitly opts in. */
+    presentation?: 'static' | 'accordion';
+    /**
+     * null/undefined → a global menu. A kind string/array scopes the menu to
+     * active groups of that kind; 'any' matches every kind (used as the
+     * fallback group menu).
+     */
+    groupKind?: string | string[] | 'any' | null;
+    items: MenuItem[];
+}
+
+export interface MenuContext {
+    me: Me | null;
+    member: MemberLike | null;
+    group: Group | null;
+}
+
+// ── Registry (insertion-ordered; subscribable so late registration — lazy
+// admin sections, HMR — re-renders subscribers) ───────────────────────
+
+const menus = new Map<string, MenuConfig>();
+let defaultMenuName: string | null = null;
+let version = 0;
+const listeners = new Set<() => void>();
+
+function bump(): void {
+    version += 1;
+    for (const cb of listeners) cb();
+}
+
+/** Register (or replace) one menu. Registration order is resolution order. */
+export function registerMenu(config: MenuConfig): void {
+    menus.set(config.name, config);
+    bump();
+}
+
+export function registerMenus(configs: MenuConfig[]): void {
+    for (const c of configs) menus.set(c.name, c);
+    bump();
+}
+
+/** The menu the fallback chain prefers when no route matches. */
+export function setDefaultMenu(name: string): void {
+    defaultMenuName = name;
+    bump();
+}
+
+export function getMenus(): ReadonlyMap<string, MenuConfig> {
+    return menus;
+}
+
+export function subscribeMenus(cb: () => void): () => void {
+    listeners.add(cb);
+    return () => listeners.delete(cb);
+}
+
+export function menusVersion(): number {
+    return version;
+}
+
+// ── Matching + visibility (pure) ──────────────────────────────────────
+
+export function groupKindMatches(menuKind: MenuConfig['groupKind'], kind: string | null | undefined): boolean {
+    if (!menuKind || !kind) return false;
+    if (menuKind === 'any') return true;
+    if (Array.isArray(menuKind)) return menuKind.includes(kind);
+    return menuKind === kind;
+}
+
+/** Route match: exact for '/', prefix (param-aware) otherwise. */
+export function routesMatch(itemRoute: string, pathname: string): boolean {
+    return matchPath({ path: itemRoute, end: itemRoute === '/' }, pathname) != null;
+}
+
+/** Permission + group-kind visibility for one item (dividers always show). */
+export function itemVisible(item: MenuItem, ctx: MenuContext): boolean {
+    if (item.divider) return true;
+    if (item.permissions && !hasPermission(ctx.me, item.permissions, ctx.member)) return false;
+    if (item.permissionClauses?.some((clause) => !hasPermission(ctx.me, clause, ctx.member))) return false;
+    if (item.requiresGroupKind) {
+        if (!groupKindMatches(item.requiresGroupKind, ctx.group?.kind)) return false;
+    }
+    return true;
+}
+
+/** Visible immediate children, shared by route resolution and SidebarNav. */
+export function visibleMenuChildren(item: MenuItem, ctx: MenuContext): MenuItem[] {
+    return (item.children ?? []).filter((child) => itemVisible(child, ctx));
+}
+
+/** Does this item's visible subtree own the current route? */
+export function itemContainsRoute(item: MenuItem, pathname: string, ctx: MenuContext): boolean {
+    if (!itemVisible(item, ctx)) return false;
+    if (item.route && routesMatch(item.route, pathname)) return true;
+    return visibleMenuChildren(item, ctx).some((child) => itemContainsRoute(child, pathname, ctx));
+}
+
+/** Effective scope with backward-compatible groupKind inference. */
+export function menuScope(menu: MenuConfig): NonNullable<MenuConfig['scope']> {
+    return menu.scope ?? (menu.groupKind ? 'group' : 'global');
+}
+
+function menuHasVisibleItems(menu: MenuConfig, ctx: MenuContext): boolean {
+    return menu.items.some((item) => !item.divider && itemVisible(item, ctx));
+}
+
+/** Does this menu own the route (visible items + children considered)? */
+export function menuContainsRoute(menu: MenuConfig, pathname: string, ctx: MenuContext): boolean {
+    return menu.items.some((item) => itemContainsRoute(item, pathname, ctx));
+}
+
+/** Is a group menu eligible at all under the current context? */
+function groupMenuEligible(menu: MenuConfig, ctx: MenuContext): boolean {
+    if (!menu.groupKind) return true;
+    return ctx.group != null && groupKindMatches(menu.groupKind, ctx.group.kind);
+}
+
+/**
+ * The active menu for (route, context) — autoSwitchToMenuForRoute + the
+ * _applyFallbackMenu chain, as one pure resolution.
+ */
+export function resolveActiveMenu(pathname: string, ctx: MenuContext): MenuConfig | null {
+    // 1. Route containment, registration order.
+    for (const menu of menus.values()) {
+        if (!groupMenuEligible(menu, ctx)) continue;
+        if (menuContainsRoute(menu, pathname, ctx)) return menu;
+    }
+    // 2. defaultMenu.
+    if (defaultMenuName) {
+        const dm = menus.get(defaultMenuName);
+        if (dm) return dm;
+    }
+    // 3. First non-group menu with visible items; else first non-group.
+    let firstNonGroup: MenuConfig | null = null;
+    for (const menu of menus.values()) {
+        if (menu.groupKind) continue;
+        firstNonGroup ??= menu;
+        if (menuHasVisibleItems(menu, ctx)) return menu;
+    }
+    return firstNonGroup;
+}
+
+/** The kind-matched group menu (exact/array match beats 'any') — getGroupMenu. */
+export function resolveGroupMenu(group: Group): MenuConfig | null {
+    let anyMenu: MenuConfig | null = null;
+    for (const menu of menus.values()) {
+        if (!menu.groupKind) continue;
+        if (menu.groupKind === 'any') {
+            anyMenu ??= menu;
+        } else if (groupKindMatches(menu.groupKind, group.kind)) {
+            return menu;
+        }
+    }
+    return anyMenu;
+}
+
+/** TEST/DEV ONLY: wipe the registry (module state survives HMR reloads). */
+export function resetMenus(): void {
+    menus.clear();
+    defaultMenuName = null;
+    bump();
+}

package/src/ui/modal.tsx

@@ -0,0 +1,297 @@
+// ModalManager — ports web-mojo's imperative, awaitable Modal API onto
+// native <dialog> + a portal-free host. `await modal.confirm(...)` from any
+// event handler; no JSX modal state to hoist. The z-index/backdrop stack
+// manager web-mojo needed does not exist here: <dialog> stacks natively.
+import { useEffect, useRef, useSyncExternalStore, type CSSProperties, type ReactNode } from 'react';
+
+export type ModalSize = 'sm' | 'md' | 'lg';
+
+/** Drawer width: the 'wide' preset, or an explicit pixel number. */
+export type DrawerWidth = number | 'wide';
+
+/** One entry of the drawer's "context · title · meta" subtitle row. */
+export type DrawerMeta = string | { icon?: string; text: ReactNode };
+
+export interface DrawerOptions<T> {
+    /** Big header line. */
+    title?: ReactNode;
+    /** Small uppercase tag above the title. */
+    eyebrow?: ReactNode;
+    /** Subtitle row under the title: bare strings or `{icon, text}`. */
+    meta?: DrawerMeta[];
+    /** Static body. Ignored when `render` is given. */
+    content?: ReactNode;
+    /** Body that owns the result: call `close(value)` to resolve the await. */
+    render?: (close: (value: T | null) => void) => ReactNode;
+    /** Default 480px; 'wide' → 720px; or an explicit pixel number. */
+    width?: DrawerWidth;
+    /** Escape / backdrop / header-X dismissal (resolves null). Default true. */
+    dismissable?: boolean;
+}
+
+interface BaseItem {
+    id: number;
+    render: (close: (value: unknown) => void) => ReactNode;
+    resolve: (value: unknown) => void;
+}
+
+interface ModalItem extends BaseItem {
+    variant: 'modal';
+    size: ModalSize;
+    flush: boolean; // no body padding (DetailView-style)
+    /** Dynamic dismissal gate. Explicit close(value) always bypasses it. */
+    canDismiss?: () => boolean;
+}
+
+interface DrawerItem extends BaseItem {
+    variant: 'drawer';
+    title?: ReactNode;
+    eyebrow?: ReactNode;
+    meta?: DrawerMeta[];
+    width: number;
+    dismissable: boolean;
+    closing: boolean; // exit animation in flight — see drawer()'s two-phase close
+}
+
+type StackItem = ModalItem | DrawerItem;
+
+let nextId = 1;
+let stack: StackItem[] = [];
+const listeners = new Set<() => void>();
+
+function emit() {
+    listeners.forEach((fn) => fn());
+}
+
+export interface ModalOptions {
+    size?: ModalSize;
+    flush?: boolean;
+    /** Guards Escape/backdrop dismissal. Programmatic close still succeeds. */
+    canDismiss?: () => boolean;
+}
+
+function open<T>(render: (close: (value: T) => void) => ReactNode, opts: ModalOptions = {}): Promise<T | null> {
+    return new Promise<T | null>((resolve) => {
+        const id = nextId++;
+        let settled = false;
+        const close = (value: unknown) => {
+            if (settled) return;
+            settled = true;
+            stack = stack.filter((m) => m.id !== id);
+            emit();
+            resolve(value as T | null);
+        };
+        stack = [...stack, {
+            id,
+            variant: 'modal',
+            size: opts.size ?? 'md',
+            flush: opts.flush ?? false,
+            canDismiss: opts.canDismiss,
+            render: render as (close: (value: unknown) => void) => ReactNode,
+            resolve: close,
+        }];
+        emit();
+    });
+}
+
+// ── Drawer ────────────────────────────────────────────────────────────
+// Right slide-over. Same <dialog> substrate as every other modal (backdrop,
+// Escape and stacking come free), so a drawer opened from a modal simply
+// takes the top layer. web-mojo's Modal.drawer() header shape — eyebrow /
+// title / meta row — is carried over verbatim; the right-anchored panel and
+// the awaitable close are the parts it never had.
+
+const DRAWER_W_DEFAULT = 480;
+const DRAWER_W_WIDE = 720;
+const DRAWER_W_MIN = 280;
+/** Must match the .mojo-drawer-closing animation in the app's drawer.css. */
+const DRAWER_EXIT_MS = 200;
+
+function reducedMotion(): boolean {
+    return typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true;
+}
+
+function drawerWidthPx(width: DrawerWidth | undefined): number {
+    if (width === undefined) return DRAWER_W_DEFAULT;
+    if (width === 'wide') return DRAWER_W_WIDE;
+    if (typeof width === 'number' && Number.isFinite(width) && width > 0) return Math.max(DRAWER_W_MIN, width);
+    console.warn(`modal.drawer: unknown width ${JSON.stringify(width)} — falling back to ${DRAWER_W_DEFAULT}px`);
+    return DRAWER_W_DEFAULT;
+}
+
+function drawer<T = unknown>(opts: DrawerOptions<T>): Promise<T | null> {
+    const body = opts.render ?? (() => opts.content ?? null);
+    let dismissable = opts.dismissable ?? true;
+    if (!dismissable && !opts.render) {
+        // Nothing else can close it: no X, no Escape, no backdrop, and a static
+        // `content` has no close() to call. Fall back rather than trap the user.
+        console.warn('modal.drawer: dismissable:false needs a render() that can close the drawer — falling back to dismissable');
+        dismissable = true;
+    }
+
+    return new Promise<T | null>((resolve) => {
+        const id = nextId++;
+        let settled = false;
+
+        // Two-phase close so the slide-out actually plays: flip `closing` (CSS
+        // transforms the panel off-screen), wait out the animation, THEN drop
+        // the item — unmounting calls dialog.close() — and settle the promise.
+        const close = (value: unknown) => {
+            if (settled) return; // Escape + backdrop + a body button can race
+            settled = true;
+            stack = stack.map((m) => (m.id === id && m.variant === 'drawer' ? { ...m, closing: true } : m));
+            emit();
+            const drop = () => {
+                stack = stack.filter((m) => m.id !== id);
+                emit();
+                resolve(value as T | null);
+            };
+            if (reducedMotion()) drop();
+            else window.setTimeout(drop, DRAWER_EXIT_MS);
+        };
+
+        stack = [...stack, {
+            id,
+            variant: 'drawer',
+            title: opts.title,
+            eyebrow: opts.eyebrow,
+            meta: opts.meta,
+            width: drawerWidthPx(opts.width),
+            dismissable,
+            closing: false,
+            render: body as (close: (value: unknown) => void) => ReactNode,
+            resolve: close,
+        }];
+        emit();
+    });
+}
+
+export const modal = {
+    open,
+
+    /** Detail modal: large, flush body — the Modal.detail() envelope. */
+    detail(render: (close: (value: unknown) => void) => ReactNode): Promise<unknown> {
+        return open(render, { size: 'lg', flush: true });
+    },
+
+    /**
+     * Right slide-over drawer. Awaitable like every other static: resolves
+     * whatever `render`'s `close(value)` passes, or `null` on dismiss.
+     * TRANSIENT and modal — not the persistent shell right-panel slot.
+     */
+    drawer,
+
+    confirm(opts: { title?: string; message: ReactNode; confirmText?: string; cancelText?: string; danger?: boolean }): Promise<boolean> {
+        return open<boolean>((close) => (
+            <div className="modal-pad">
+                {opts.title && <h2 className="modal-title">{opts.title}</h2>}
+                <div className="modal-message">{opts.message}</div>
+                <div className="modal-actions">
+                    <button className="btn" onClick={() => close(false)}>{opts.cancelText ?? 'Cancel'}</button>
+                    <button className={opts.danger ? 'btn btn-danger' : 'btn btn-primary'} onClick={() => close(true)}>
+                        {opts.confirmText ?? 'Confirm'}
+                    </button>
+                </div>
+            </div>
+        ), { size: 'sm' }).then((v) => v === true);
+    },
+};
+
+function ModalDialog({ item }: { item: ModalItem }) {
+    const ref = useRef<HTMLDialogElement>(null);
+
+    useEffect(() => {
+        ref.current?.showModal();
+    }, []);
+
+    const dismiss = () => {
+        if (item.canDismiss?.() === false) return;
+        item.resolve(null);
+    };
+
+    return (
+        <dialog
+            ref={ref}
+            className={`mojo-modal mojo-modal-${item.size}${item.flush ? ' mojo-modal-flush' : ''}`}
+            onCancel={(e) => { e.preventDefault(); dismiss(); }}
+            onMouseDown={(e) => { if (e.target === ref.current) dismiss(); }}
+        >
+            {item.render(item.resolve)}
+        </dialog>
+    );
+}
+
+function DrawerDialog({ item }: { item: DrawerItem }) {
+    const ref = useRef<HTMLDialogElement>(null);
+
+    useEffect(() => {
+        const el = ref.current;
+        el?.showModal();
+        // Unmount is the END of the exit animation (the manager holds the item
+        // until then), so this is the "closing class, animate, then close()"
+        // order — and it fires the native close event / restores focus.
+        return () => { if (el?.open) el.close(); };
+    }, []);
+
+    const dismiss = () => { if (item.dismissable) item.resolve(null); };
+    const hasHead = item.dismissable || item.eyebrow != null || item.title != null || (item.meta?.length ?? 0) > 0;
+
+    return (
+        <dialog
+            ref={ref}
+            className={`mojo-drawer${item.closing ? ' mojo-drawer-closing' : ''}`}
+            // React's CSSProperties has no index signature for custom props.
+            style={{ '--drawer-w': `${item.width}px` } as CSSProperties}
+            onCancel={(e) => { e.preventDefault(); dismiss(); }}
+            onMouseDown={(e) => { if (e.target === ref.current) dismiss(); }}
+        >
+            {/* The panel fills the dialog, so the dialog element is only ever
+                the event target for ::backdrop clicks — that is the dismiss. */}
+            <div className="drawer-panel">
+                {hasHead && (
+                    <header className="drawer-head">
+                        <div className="drawer-head-text">
+                            {item.eyebrow != null && <span className="drawer-eyebrow">{item.eyebrow}</span>}
+                            {item.title != null && <h2 className="drawer-title">{item.title}</h2>}
+                            {!!item.meta?.length && (
+                                <div className="drawer-meta">
+                                    {item.meta.map((m, i) => {
+                                        const entry = typeof m === 'string' ? { icon: undefined, text: m } : m;
+                                        return (
+                                            <span key={i}>
+                                                {entry.icon && <i className={`bi ${entry.icon}`} />}
+                                                {entry.text}
+                                            </span>
+                                        );
+                                    })}
+                                </div>
+                            )}
+                        </div>
+                        {item.dismissable && (
+                            <button className="btn-icon" onClick={dismiss} title="Close" aria-label="Close">
+                                <i className="bi bi-x-lg" />
+                            </button>
+                        )}
+                    </header>
+                )}
+                <div className="drawer-body">{item.render(item.resolve)}</div>
+            </div>
+        </dialog>
+    );
+}
+
+export function ModalHost() {
+    const items = useSyncExternalStore(
+        (cb) => { listeners.add(cb); return () => listeners.delete(cb); },
+        () => stack,
+    );
+    return (
+        <>
+            {items.map((item) => (
+                item.variant === 'drawer'
+                    ? <DrawerDialog key={item.id} item={item} />
+                    : <ModalDialog key={item.id} item={item} />
+            ))}
+        </>
+    );
+}