portal-mojo 0.1.0

package/src/ui/RightPanel.tsx

@@ -0,0 +1,107 @@
+import {
+    createContext, useCallback, useContext, useEffect, useId, useLayoutEffect,
+    useRef, useState, type ReactNode,
+} from 'react';
+
+export interface RightPanelRenderContext {
+    close(): void;
+}
+
+export interface RightPanelDescriptor {
+    /** Stable session identity. Opening the same key is idempotent. */
+    key: string;
+    /** Visible accessible heading for the complementary region. */
+    title: ReactNode;
+    render(context: RightPanelRenderContext): ReactNode;
+}
+
+export interface RightPanelContextValue {
+    descriptor: RightPanelDescriptor | null;
+    isOpen: boolean;
+    open(descriptor: RightPanelDescriptor, launcher?: HTMLElement | null): void;
+    close(): void;
+}
+
+const RightPanelContext = createContext<RightPanelContextValue | null>(null);
+
+export function RightPanelProvider({ children }: { children: ReactNode }) {
+    const [descriptor, setDescriptor] = useState<RightPanelDescriptor | null>(null);
+    const launcherRef = useRef<HTMLElement | null>(null);
+    const descriptorRef = useRef<RightPanelDescriptor | null>(null);
+    descriptorRef.current = descriptor;
+
+    const open = useCallback((next: RightPanelDescriptor, launcher?: HTMLElement | null) => {
+        if (descriptorRef.current?.key === next.key) return;
+        const active = typeof document !== 'undefined' && document.activeElement instanceof HTMLElement
+            ? document.activeElement
+            : null;
+        launcherRef.current = launcher ?? active;
+        descriptorRef.current = next;
+        setDescriptor(next);
+    }, []);
+
+    const close = useCallback(() => {
+        if (descriptorRef.current == null) return;
+        descriptorRef.current = null;
+        setDescriptor(null);
+        const launcher = launcherRef.current;
+        launcherRef.current = null;
+        requestAnimationFrame(() => {
+            if (launcher?.isConnected) launcher.focus();
+        });
+    }, []);
+
+    useEffect(() => {
+        if (!descriptor) return;
+        const onKeyDown = (event: KeyboardEvent) => {
+            if (event.key !== 'Escape' || event.defaultPrevented) return;
+            // Native dialogs own Escape while they are in the top layer.
+            if (document.querySelector('dialog[open]')) return;
+            event.preventDefault();
+            close();
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [descriptor, close]);
+
+    return (
+        <RightPanelContext.Provider value={{ descriptor, isOpen: descriptor != null, open, close }}>
+            {children}
+        </RightPanelContext.Provider>
+    );
+}
+
+export function useRightPanel(): RightPanelContextValue {
+    const context = useContext(RightPanelContext);
+    if (!context) throw new Error('useRightPanel must be used inside <RightPanelProvider>');
+    return context;
+}
+
+export function RightPanelSlot({ className }: { className?: string }) {
+    const { descriptor, close } = useRightPanel();
+    const uid = useId();
+    const headingId = `right-panel-heading-${uid}`;
+    const closeRef = useRef<HTMLButtonElement>(null);
+
+    useLayoutEffect(() => {
+        if (!descriptor) return;
+        closeRef.current?.focus();
+    }, [descriptor?.key]);
+
+    if (!descriptor) return null;
+    return (
+        <aside
+            className={`right-panel${className ? ` ${className}` : ''}`}
+            role="complementary"
+            aria-labelledby={headingId}
+        >
+            <header className="right-panel-head">
+                <h2 id={headingId} tabIndex={-1}>{descriptor.title}</h2>
+                <button ref={closeRef} type="button" className="btn-icon" onClick={close} aria-label="Close panel" title="Close panel">
+                    <i className="bi bi-x-lg" aria-hidden="true" />
+                </button>
+            </header>
+            <div className="right-panel-body">{descriptor.render({ close })}</div>
+        </aside>
+    );
+}

package/src/ui/SidebarNav.tsx

@@ -0,0 +1,330 @@
+// SidebarNav — renders the ACTIVE menu from the registry (menu-registry.ts).
+// Static menus keep A4's original always-visible children. Menus that opt into
+// `presentation: 'accordion'` get one-open domain groups, navigation search,
+// active-branch expansion, and an app-owned icon-rail presentation.
+import {
+    useContext, useEffect, useId, useMemo, useState, useSyncExternalStore,
+    type Dispatch, type SetStateAction,
+} from 'react';
+import { NavLink, useLocation } from 'react-router-dom';
+import { useMe } from '../client/me';
+import { GroupContext } from '../client/group-context';
+import {
+    itemContainsRoute, itemVisible, menusVersion, resolveActiveMenu,
+    routesMatch, subscribeMenus, visibleMenuChildren,
+    type MenuConfig, type MenuContext, type MenuItem,
+} from './menu-registry';
+
+/** The active menu + context, derived — no menu state to desync. */
+export function useSidebarMenu(): { menu: MenuConfig | null; ctx: MenuContext } {
+    useSyncExternalStore(subscribeMenus, menusVersion, menusVersion);
+    const { pathname } = useLocation();
+    const { data: me } = useMe();
+    const groupCtx = useContext(GroupContext);
+    const ctx: MenuContext = {
+        me: me ?? null,
+        member: groupCtx?.member ?? null,
+        group: groupCtx?.group ?? null,
+    };
+    return { menu: resolveActiveMenu(pathname, ctx), ctx };
+}
+
+function itemKey(item: MenuItem, index: number, parent = 'root'): string {
+    return item.id ?? item.route ?? `${parent}:${item.label ?? item.divider ?? index}`;
+}
+
+function domToken(value: string): string {
+    return value.replace(/[^a-zA-Z0-9_-]+/g, '-');
+}
+
+/** Remove denied/empty branches while retaining the public MenuItem shape. */
+function visibleTree(item: MenuItem, ctx: MenuContext): MenuItem | null {
+    if (!itemVisible(item, ctx)) return null;
+    if (item.divider) return item;
+    const hadChildren = item.children != null;
+    const children = visibleMenuChildren(item, ctx)
+        .map((child) => visibleTree(child, ctx))
+        .filter((child): child is MenuItem => child != null);
+    if (!item.route && hadChildren && children.length === 0) return null;
+    return hadChildren ? { ...item, children } : item;
+}
+
+/** Drop section dividers whose complete visible section is empty. */
+function visibleRootItems(items: MenuItem[], ctx: MenuContext): MenuItem[] {
+    const out: MenuItem[] = [];
+    let pendingDivider: MenuItem | null = null;
+    for (const item of items) {
+        if (item.divider) {
+            pendingDivider = item;
+            continue;
+        }
+        const visible = visibleTree(item, ctx);
+        if (!visible) continue;
+        if (pendingDivider) {
+            out.push(pendingDivider);
+            pendingDivider = null;
+        }
+        out.push(visible);
+    }
+    return out;
+}
+
+function filterTree(item: MenuItem, query: string): MenuItem | null {
+    if (item.divider) return null;
+    const children = (item.children ?? [])
+        .map((child) => filterTree(child, query))
+        .filter((child): child is MenuItem => child != null);
+    const selfMatch = [item.label ?? '', ...(item.keywords ?? [])]
+        .some((value) => value.toLocaleLowerCase().includes(query));
+    if (!selfMatch && children.length === 0) return null;
+    return item.children ? { ...item, children: selfMatch ? item.children : children } : item;
+}
+
+function countDestinations(items: MenuItem[]): number {
+    return items.reduce((total, item) => total
+        + (item.route ? 1 : 0)
+        + countDestinations(item.children ?? []), 0);
+}
+
+function treeOwnsRoute(item: MenuItem, pathname: string): boolean {
+    if (item.route && routesMatch(item.route, pathname)) return true;
+    return (item.children ?? []).some((child) => treeOwnsRoute(child, pathname));
+}
+
+function NavRow({
+    item, pathname, depth, collapsed = false,
+}: {
+    item: MenuItem;
+    pathname: string;
+    depth: number;
+    collapsed?: boolean;
+}) {
+    if (!item.route) return null;
+    const active = routesMatch(item.route, pathname);
+    const label = item.label ?? item.route;
+    return (
+        <NavLink
+            to={item.route}
+            end={item.route === '/'}
+            aria-label={collapsed ? label : undefined}
+            data-tooltip={collapsed ? label : undefined}
+            className={`nav-item${depth > 0 ? ' nav-child' : ''}${active ? ' nav-active' : ''}`}
+        >
+            {item.icon && <i className={`bi ${item.icon}`} />}
+            <span className="nav-text">{label}</span>
+            {item.badge && <span className={`chip chip-${item.badge.tone ?? 'muted'} nav-badge`}>{item.badge.text}</span>}
+        </NavLink>
+    );
+}
+
+function StaticItem({
+    item, pathname, depth, parentKey, index,
+}: {
+    item: MenuItem;
+    pathname: string;
+    depth: number;
+    parentKey: string;
+    index: number;
+}) {
+    if (item.divider) return <div className="side-label">{item.divider}</div>;
+    const children = item.children ?? [];
+    if (!item.route) {
+        return (
+            <div className="nav-static-group">
+                {item.label && <div className="side-label">{item.label}</div>}
+                {children.map((child, childIndex) => (
+                    <StaticItem
+                        key={itemKey(child, childIndex, itemKey(item, index, parentKey))}
+                        item={child}
+                        pathname={pathname}
+                        depth={depth + 1}
+                        parentKey={itemKey(item, index, parentKey)}
+                        index={childIndex}
+                    />
+                ))}
+            </div>
+        );
+    }
+    return (
+        <>
+            <NavRow item={item} pathname={pathname} depth={depth} />
+            {children.map((child, childIndex) => (
+                <StaticItem
+                    key={itemKey(child, childIndex, itemKey(item, index, parentKey))}
+                    item={child}
+                    pathname={pathname}
+                    depth={depth + 1}
+                    parentKey={itemKey(item, index, parentKey)}
+                    index={childIndex}
+                />
+            ))}
+        </>
+    );
+}
+
+function AccordionItem({
+    item, index, pathname, openKey, setOpenKey, searching, collapsed,
+    onRequestExpand, idPrefix,
+}: {
+    item: MenuItem;
+    index: number;
+    pathname: string;
+    openKey: string | null;
+    setOpenKey: Dispatch<SetStateAction<string | null>>;
+    searching: boolean;
+    collapsed: boolean;
+    onRequestExpand?: () => void;
+    idPrefix: string;
+}) {
+    if (item.divider) return collapsed ? null : <div className="side-label">{item.divider}</div>;
+    const children = item.children ?? [];
+    if (item.route || children.length === 0) {
+        return <NavRow item={item} pathname={pathname} depth={0} collapsed={collapsed} />;
+    }
+
+    const key = itemKey(item, index);
+    const active = treeOwnsRoute(item, pathname);
+    const open = searching || openKey === key;
+    const disclosureId = `${idPrefix}-${domToken(key)}`;
+    const label = item.label ?? key;
+    const activate = () => {
+        if (collapsed) {
+            setOpenKey(key);
+            onRequestExpand?.();
+        } else {
+            setOpenKey((current) => current === key ? null : key);
+        }
+    };
+
+    return (
+        <div className={`nav-accordion${open ? ' nav-accordion-open' : ''}`}>
+            <button
+                type="button"
+                className={`nav-item nav-parent${active ? ' nav-active' : ''}`}
+                aria-expanded={collapsed ? undefined : open}
+                aria-controls={collapsed ? undefined : disclosureId}
+                aria-label={collapsed ? label : undefined}
+                data-tooltip={collapsed ? label : undefined}
+                onClick={activate}
+                onKeyDown={(event) => {
+                    if (collapsed && (event.key === 'Enter' || event.key === ' ')) {
+                        event.preventDefault();
+                        activate();
+                    }
+                }}
+            >
+                {item.icon && <i className={`bi ${item.icon}`} />}
+                <span className="nav-text">{label}</span>
+                {item.badge && <span className={`chip chip-${item.badge.tone ?? 'muted'} nav-badge`}>{item.badge.text}</span>}
+                {!collapsed && <i className="bi bi-chevron-down nav-arrow" aria-hidden="true" />}
+            </button>
+            {!collapsed && (
+                <div id={disclosureId} className="nav-submenu" hidden={!open}>
+                    {children.map((child, childIndex) => (
+                        child.route
+                            ? <NavRow key={itemKey(child, childIndex, key)} item={child} pathname={pathname} depth={1} />
+                            : <StaticItem
+                                key={itemKey(child, childIndex, key)}
+                                item={child}
+                                pathname={pathname}
+                                depth={1}
+                                parentKey={key}
+                                index={childIndex}
+                            />
+                    ))}
+                </div>
+            )}
+        </div>
+    );
+}
+
+export interface SidebarNavProps {
+    /** App-owned icon-rail state. Layout width remains the app's concern. */
+    collapsed?: boolean;
+    /** Called when a rail category is activated so the shell can expand. */
+    onRequestExpand?: () => void;
+}
+
+export function SidebarNav({ collapsed = false, onRequestExpand }: SidebarNavProps = {}) {
+    const { menu, ctx } = useSidebarMenu();
+    const { pathname } = useLocation();
+    const disclosurePrefix = domToken(useId());
+    const [openKey, setOpenKey] = useState<string | null>(null);
+    const [query, setQuery] = useState('');
+
+    const items = useMemo(
+        () => menu ? visibleRootItems(menu.items, ctx) : [],
+        [menu, ctx.me, ctx.member, ctx.group],
+    );
+    const activeKey = useMemo(() => {
+        const index = items.findIndex((item) => !item.divider && itemContainsRoute(item, pathname, ctx));
+        return index < 0 ? null : itemKey(items[index]!, index);
+    }, [items, pathname, ctx]);
+
+    useEffect(() => {
+        setOpenKey(activeKey);
+    }, [activeKey, menu?.name]);
+
+    const normalizedQuery = query.trim().toLocaleLowerCase();
+    const filteredItems = useMemo(() => normalizedQuery
+        ? items.map((item) => filterTree(item, normalizedQuery)).filter((item): item is MenuItem => item != null)
+        : items, [items, normalizedQuery]);
+    const resultCount = countDestinations(filteredItems);
+
+    if (!menu) return null;
+    if (menu.presentation !== 'accordion') {
+        return (
+            <nav className="side-nav" data-menu={menu.name}>
+                {items.map((item, index) => (
+                    <StaticItem
+                        key={itemKey(item, index)} item={item} pathname={pathname}
+                        depth={0} parentKey="root" index={index}
+                    />
+                ))}
+            </nav>
+        );
+    }
+
+    return (
+        <nav className={`side-nav side-nav-accordion${collapsed ? ' side-nav-collapsed' : ''}`} data-menu={menu.name} aria-label="Admin navigation">
+            {!collapsed && (
+                <div className="nav-search">
+                    <i className="bi bi-search" aria-hidden="true" />
+                    <input
+                        type="search"
+                        value={query}
+                        aria-label="Search Admin navigation"
+                        placeholder="Find admin page…"
+                        onChange={(event) => setQuery(event.target.value)}
+                        onKeyDown={(event) => {
+                            if (event.key === 'Escape' && query) {
+                                event.preventDefault();
+                                setQuery('');
+                            }
+                        }}
+                    />
+                    {query && <button type="button" aria-label="Clear navigation search" onClick={() => setQuery('')}><i className="bi bi-x-lg" /></button>}
+                </div>
+            )}
+            {!collapsed && normalizedQuery && (
+                <div className="nav-search-status" role="status" aria-live="polite">
+                    {resultCount === 0 ? 'No admin pages found' : `${resultCount} admin page${resultCount === 1 ? '' : 's'} found`}
+                </div>
+            )}
+            {filteredItems.map((item, index) => (
+                <AccordionItem
+                    key={itemKey(item, index)}
+                    item={item}
+                    index={index}
+                    pathname={pathname}
+                    openKey={openKey}
+                    setOpenKey={setOpenKey}
+                    searching={Boolean(normalizedQuery)}
+                    collapsed={collapsed}
+                    onRequestExpand={onRequestExpand}
+                    idPrefix={disclosurePrefix}
+                />
+            ))}
+        </nav>
+    );
+}

package/src/ui/Tabs.tsx

@@ -0,0 +1,161 @@
+import { useEffect, useId, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
+
+export type TabVariant = 'minimal' | 'traditional' | 'underline' | 'underline-all' | 'pills' | 'pills-solid' | 'segmented' | 'btn-group';
+
+export interface TabItem {
+    key: string;
+    label: ReactNode;
+    panel: ReactNode;
+    disabled?: boolean;
+    ariaLabel?: string;
+}
+
+export interface TabsProps {
+    items: TabItem[];
+    activeKey?: string | null;
+    defaultActiveKey?: string | null;
+    onActiveKeyChange?: (key: string) => void;
+    variant?: TabVariant | 'buttongroup' | 'btngroup' | (string & {});
+    ariaLabel?: string;
+    className?: string;
+}
+
+const VARIANTS = new Set<TabVariant>(['minimal', 'traditional', 'underline', 'underline-all', 'pills', 'pills-solid', 'segmented', 'btn-group']);
+const warned = new Set<string>();
+
+function warnOnce(key: string, message: string): void {
+    if (warned.has(key)) return;
+    warned.add(key);
+    console.warn(message);
+}
+
+export function normalizeTabVariant(value: string | undefined): TabVariant {
+    if (value === 'buttongroup' || value === 'btngroup') return 'btn-group';
+    if (!value) return 'underline-all';
+    if (VARIANTS.has(value as TabVariant)) return value as TabVariant;
+    warnOnce(`variant:${value}`, `Tabs: unknown variant "${value}" — falling back to "underline-all"`);
+    return 'underline-all';
+}
+
+export function normalizeTabItems(items: TabItem[]): TabItem[] {
+    const seen = new Set<string>();
+    return items.filter((item) => {
+        if (!item.key || seen.has(item.key)) {
+            warnOnce(`key:${item.key || '<empty>'}`, `Tabs: ${item.key ? `duplicate key "${item.key}"` : 'empty key'} ignored`);
+            return false;
+        }
+        seen.add(item.key);
+        return true;
+    });
+}
+
+export function effectiveTabKey(requested: string | null | undefined, items: TabItem[]): string | null {
+    const enabled = items.filter((item) => !item.disabled);
+    if (requested && enabled.some((item) => item.key === requested)) return requested;
+    return enabled[0]?.key ?? null;
+}
+
+export function nextTabKey(items: TabItem[], current: string | null, key: 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End'): string | null {
+    const enabled = items.filter((item) => !item.disabled);
+    if (!enabled.length) return null;
+    if (key === 'Home') return enabled[0]!.key;
+    if (key === 'End') return enabled[enabled.length - 1]!.key;
+    const at = Math.max(0, enabled.findIndex((item) => item.key === current));
+    const delta = key === 'ArrowRight' ? 1 : -1;
+    return enabled[(at + delta + enabled.length) % enabled.length]!.key;
+}
+
+export function controlledTabHealTransition(
+    previousNotice: string,
+    requested: string | null | undefined,
+    effective: string | null,
+    items: TabItem[],
+): { nextNotice: string; notify: string | null } {
+    // A valid request closes the prior invalid episode. If that same invalid
+    // request returns later, it is a new transition and must notify again.
+    if (requested === effective || effective == null) return { nextNotice: '', notify: null };
+    const notice = `${String(requested)}|${items.filter((item) => !item.disabled).map((item) => item.key).join('|')}|${effective}`;
+    if (notice === previousNotice) return { nextNotice: previousNotice, notify: null };
+    return { nextNotice: notice, notify: effective };
+}
+
+export function Tabs({ items, activeKey, defaultActiveKey, onActiveKeyChange, variant, ariaLabel = 'Tabs', className }: TabsProps) {
+    const normalized = useMemo(() => normalizeTabItems(items), [items]);
+    const controlled = activeKey !== undefined;
+    const [internalKey, setInternalKey] = useState<string | null>(() => effectiveTabKey(defaultActiveKey, normalized));
+    const requested = controlled ? activeKey : internalKey;
+    const effective = effectiveTabKey(requested, normalized);
+    const uid = useId().replace(/:/g, '');
+    const refs = useRef(new Map<string, HTMLButtonElement>());
+    const lastNotice = useRef('');
+
+    useEffect(() => {
+        if (!controlled && internalKey !== effective) setInternalKey(effective);
+    }, [controlled, internalKey, effective]);
+
+    useEffect(() => {
+        if (!controlled) {
+            lastNotice.current = '';
+            return;
+        }
+        const transition = controlledTabHealTransition(lastNotice.current, requested, effective, normalized);
+        lastNotice.current = transition.nextNotice;
+        if (transition.notify) onActiveKeyChange?.(transition.notify);
+    }, [controlled, requested, effective, normalized, onActiveKeyChange]);
+
+    const select = (key: string, focus = false) => {
+        if (!controlled) setInternalKey(key);
+        onActiveKeyChange?.(key);
+        if (focus) window.setTimeout(() => refs.current.get(key)?.focus(), 0);
+    };
+
+    const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+        if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return;
+        event.preventDefault();
+        const next = nextTabKey(normalized, effective, event.key as 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End');
+        if (next) select(next, true);
+    };
+
+    const variantName = normalizeTabVariant(variant);
+    return (
+        <div className={className ? `mojo-tabs ${className}` : 'mojo-tabs'} data-tab-variant={variantName}>
+            <div className="mojo-tab-list" role="tablist" aria-label={ariaLabel}>
+                {normalized.map((item, index) => {
+                    const selected = item.key === effective;
+                    const tabId = `tab-${uid}-${index}`;
+                    const panelId = `panel-${uid}-${index}`;
+                    return (
+                        <button
+                            ref={(node) => { if (node) refs.current.set(item.key, node); else refs.current.delete(item.key); }}
+                            key={item.key}
+                            id={tabId}
+                            type="button"
+                            role="tab"
+                            aria-label={item.ariaLabel}
+                            aria-selected={selected}
+                            aria-disabled={item.disabled || undefined}
+                            aria-controls={panelId}
+                            tabIndex={selected ? 0 : -1}
+                            disabled={item.disabled}
+                            className="mojo-tab"
+                            onClick={() => select(item.key)}
+                            onKeyDown={onKeyDown}
+                        >
+                            {item.label}
+                        </button>
+                    );
+                })}
+            </div>
+            <div className="mojo-tab-panels">
+                {normalized.map((item, index) => {
+                    const selected = item.key === effective;
+                    return (
+                        <div key={item.key} id={`panel-${uid}-${index}`} role="tabpanel" aria-labelledby={`tab-${uid}-${index}`} hidden={!selected} className="mojo-tab-panel">
+                            {selected ? item.panel : null}
+                        </div>
+                    );
+                })}
+            </div>
+        </div>
+    );
+}