@object-ui/app-shell 6.2.3 → 7.1.0

package/dist/layout/ContextSelectors.js

@@ -0,0 +1,242 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * AppContextSelectors — renders the app-level "scope" dropdowns declared
+ * in `App.contextSelectors` (e.g. the Studio package filter) and exposes
+ * their current values so the sidebar can feed them into
+ * `NavigationRenderer`'s `templateContext.contextValues`.
+ *
+ * Each selector's value is published under its `id` and referenced by
+ * nav items as `{<id>}` (e.g. `{active_package}`), exactly like the
+ * built-in `{current_user_id}` / `{current_org_id}` template vars.
+ * Selecting an option therefore transparently scopes every child nav
+ * item — no per-item wiring required.
+ *
+ * @module
+ */
+import * as React from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from '@object-ui/components';
+import { getIcon } from '../utils/getIcon';
+import { resolveI18nLabel } from '../utils';
+// Local/Custom scope sentinel — kept inline (not imported from metadata-admin)
+// so this layout module never forms an import cycle with the metadata-admin
+// views. Mirrors `LOCAL_PACKAGE_ID` in views/metadata-admin/package-scope.ts.
+const LOCAL_SCOPE_ID = 'sys_metadata';
+function localScopeLabel() {
+    const lang = (typeof document !== 'undefined' && document.documentElement?.lang) ||
+        (typeof navigator !== 'undefined' && navigator.language) ||
+        '';
+    return /^zh/i.test(lang) ? '本地 / 自定义（本环境）' : 'Local / Custom (this env)';
+}
+const ALL_SENTINEL = '__all__';
+/** Read a (possibly dotted) property path off a row, e.g. `manifest.id`. */
+function getByPath(row, key) {
+    if (!key)
+        return undefined;
+    return key.split('.').reduce((o, k) => (o == null ? o : o[k]), row);
+}
+/** Tolerate the common REST envelope shapes used across the platform. */
+function extractRows(json) {
+    if (Array.isArray(json))
+        return json;
+    const d = json?.data ?? json;
+    if (Array.isArray(d))
+        return d;
+    if (Array.isArray(d?.packages))
+        return d.packages;
+    if (Array.isArray(d?.items))
+        return d.items;
+    if (Array.isArray(json?.items))
+        return json.items;
+    return [];
+}
+/** Apply a selector's `filter` predicates (AND) to a fetched row. */
+function rowPasses(row, filters) {
+    if (!filters || filters.length === 0)
+        return true;
+    for (const f of filters) {
+        const actual = getByPath(row, f.key);
+        const op = f.op ?? 'eq';
+        const list = Array.isArray(f.value) ? f.value : [f.value];
+        switch (op) {
+            case 'eq':
+                if (actual !== f.value)
+                    return false;
+                break;
+            case 'ne':
+                if (actual === f.value)
+                    return false;
+                break;
+            // `in`/`nin` treat a missing value as "not in the set", which keeps
+            // untagged rows visible under `nin` (e.g. a package whose manifest
+            // omits `scope` defaults to project and should remain selectable).
+            case 'in':
+                if (!list.includes(actual))
+                    return false;
+                break;
+            case 'nin':
+                if (list.includes(actual))
+                    return false;
+                break;
+        }
+    }
+    return true;
+}
+function useSelectorOptions(def) {
+    const [options, setOptions] = React.useState([]);
+    const endpoint = def.optionsSource.endpoint;
+    const valueKey = def.optionsSource.valueKey || 'id';
+    const labelKey = def.optionsSource.labelKey || 'name';
+    const filters = def.optionsSource.filter;
+    const filterKey = JSON.stringify(filters ?? []);
+    // Stable, re-runnable fetch. Without an explicit refetch the option list is
+    // read once on mount, so a package created elsewhere (PackagesPage) stays
+    // invisible in this dropdown until a full page reload. We refetch on
+    // dropdown-open and on a global `objectui:packages-changed` signal.
+    const load = React.useCallback(async () => {
+        try {
+            const res = await fetch(endpoint, {
+                credentials: 'include',
+                headers: { Accept: 'application/json' },
+            });
+            if (!res.ok)
+                return;
+            const json = await res.json();
+            const rows = extractRows(json);
+            const opts = [];
+            const seen = new Set();
+            for (const row of rows) {
+                if (!rowPasses(row, filters))
+                    continue;
+                const value = getByPath(row, valueKey);
+                if (value == null || typeof value !== 'string' || seen.has(value))
+                    continue;
+                seen.add(value);
+                const labelRaw = getByPath(row, labelKey);
+                opts.push({ value, label: typeof labelRaw === 'string' && labelRaw ? labelRaw : value });
+            }
+            opts.sort((a, b) => a.label.localeCompare(b.label));
+            // The package-scope selector gets a stable "Local / Custom (this env)"
+            // entry for this environment's runtime, DB-authored metadata — it is
+            // never a real package row (`package_id = null` / `sys_metadata`
+            // provenance) yet must always be selectable so org-authored items are
+            // discoverable and editable. The metadata list/get API already treats
+            // `?package=sys_metadata` as exactly this local scope.
+            if (/package/i.test(endpoint) && !opts.some((o) => o.value === LOCAL_SCOPE_ID)) {
+                opts.push({ value: LOCAL_SCOPE_ID, label: localScopeLabel() });
+            }
+            setOptions(opts);
+        }
+        catch {
+            /* offline / unauthorized — render with no options */
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [endpoint, valueKey, labelKey, filterKey]);
+    React.useEffect(() => {
+        void load();
+        const onChanged = () => { void load(); };
+        window.addEventListener('objectui:packages-changed', onChanged);
+        return () => window.removeEventListener('objectui:packages-changed', onChanged);
+    }, [load]);
+    return { options, refetch: load };
+}
+/**
+ * Hook: resolves the active values for an app's context selectors and
+ * returns a ready-to-render UI element plus the `contextValues` map for
+ * `NavigationRenderer`.
+ */
+export function useAppContextSelectors(appName, selectors, t) {
+    const list = Array.isArray(selectors) ? selectors : [];
+    const navigate = useNavigate();
+    const location = useLocation();
+    // The URL query string is the single source of truth for the active
+    // scope. Deriving the selected value from it (rather than a parallel
+    // useState) keeps the sidebar control in lock-step with the page — no
+    // more "sidebar says A while the list shows B" drift.
+    const params = new URLSearchParams(location.search);
+    // Re-apply a remembered scope whenever navigation drops the query param.
+    // The selector is mandatory for Studio: package-scoped pages should never
+    // sit at a blank package value just because a nav link omitted `?package=`.
+    React.useEffect(() => {
+        const p = new URLSearchParams(location.search);
+        let changed = false;
+        for (const sel of list) {
+            if (sel.persist === 'none')
+                continue;
+            if (p.get('package'))
+                continue;
+            try {
+                const saved = sessionStorage.getItem(`objectui-ctx-${appName}-${sel.id}`);
+                if (saved) {
+                    p.set('package', saved);
+                    changed = true;
+                }
+            }
+            catch { /* storage disabled */ }
+        }
+        if (changed) {
+            navigate({ pathname: location.pathname, search: p.toString() }, { replace: true });
+        }
+    }, [appName, list, location.pathname, location.search, navigate]);
+    const setValue = React.useCallback((sel, raw) => {
+        const value = raw === ALL_SENTINEL ? (sel.allValue ?? '') : raw;
+        try {
+            const key = `objectui-ctx-${appName}-${sel.id}`;
+            if (value)
+                sessionStorage.setItem(key, value);
+            else
+                sessionStorage.removeItem(key);
+        }
+        catch { /* storage disabled */ }
+        // Reflect the scope onto the current page immediately. Metadata
+        // surfaces read the `package` query param as the conventional filter
+        // key; nav links pick it up via the `{active_package}` template var.
+        const next = new URLSearchParams(location.search);
+        if (value)
+            next.set('package', value);
+        else
+            next.delete('package');
+        navigate({ pathname: location.pathname, search: next.toString() }, { replace: true });
+    }, [appName, location.pathname, location.search, navigate]);
+    const contextValues = {};
+    for (const sel of list) {
+        let saved = '';
+        try {
+            saved = sessionStorage.getItem(`objectui-ctx-${appName}-${sel.id}`) ?? '';
+        }
+        catch { /* storage disabled */ }
+        contextValues[sel.id] = (params.get('package') ?? saved) || (sel.allValue ?? '');
+    }
+    const element = list.length === 0 ? null : (_jsx("div", { className: "flex flex-col gap-1.5", children: list.map((sel) => (_jsx(SelectorControl, { def: sel, value: contextValues[sel.id], onChange: (raw) => setValue(sel, raw), t: t }, sel.id))) }));
+    return { contextValues, element };
+}
+function SelectorControl({ def, value, onChange, t, }) {
+    const { options, refetch } = useSelectorOptions(def);
+    const Icon = getIcon(def.icon);
+    const rawLabel = resolveI18nLabel(def.label, t) || def.id;
+    const label = rawLabel === 'Package'
+        ? (t?.('common.package', { defaultValue: rawLabel }) ?? rawLabel)
+        : rawLabel;
+    const placeholder = t?.('actionDialog.selectPlaceholder', {
+        label,
+        defaultValue: `Select ${label}…`,
+    }) ?? `Select ${label}…`;
+    // Context selectors are *mandatory scope* selectors: a concrete option must
+    // always be active. Allowing an "All" choice would unscope the surface and,
+    // for Studio's package filter, leak system metadata. We therefore ignore
+    // `includeAll`, never render an "All" row, and auto-select the first option
+    // as soon as the list resolves when nothing concrete is selected yet.
+    const hasConcrete = !!value && value !== (def.allValue ?? '');
+    React.useEffect(() => {
+        if (hasConcrete) {
+            return;
+        }
+        if (options.length > 0) {
+            onChange(options[0].value);
+        }
+    }, [hasConcrete, onChange, options]);
+    const current = hasConcrete ? value : '';
+    return (_jsxs(Select, { value: current, onValueChange: onChange, onOpenChange: (open) => { if (open)
+            refetch(); }, children: [_jsx(SelectTrigger, { "aria-label": label, "data-testid": "package-switcher", className: "h-9 w-full gap-2 rounded-md border-sidebar-border/70 bg-sidebar/80 px-2 text-xs font-medium text-sidebar-foreground shadow-none transition-colors hover:bg-sidebar-accent focus:ring-1 focus:ring-sidebar-ring data-[state=open]:bg-sidebar-accent [&>svg]:h-3.5 [&>svg]:w-3.5 [&>svg]:shrink-0", children: _jsxs("div", { className: "flex min-w-0 flex-1 items-center gap-2 overflow-hidden", children: [_jsx("span", { className: "flex h-5 w-5 shrink-0 items-center justify-center rounded border border-sidebar-border/70 bg-sidebar-accent text-sidebar-foreground/70", children: _jsx(Icon, { className: "h-3 w-3" }) }), _jsx(SelectValue, { placeholder: placeholder, className: "truncate" })] }) }), _jsx(SelectContent, { className: "w-[var(--radix-select-trigger-width)]", children: options.map((opt) => (_jsx(SelectItem, { value: opt.value, children: opt.label }, opt.value))) })] }));
+}

package/dist/layout/InboxPopover.d.ts

@@ -16,9 +16,14 @@
 import type { ActivityItem } from './ActivityFeed';
 export interface InboxNotification {
     id: string;
+    /** FK → sys_notification (L2 event) — keys the read-state receipt (ADR-0030). */
+    notification_id?: string | null;
+    receipt_id?: string | null;
     type: string;
     title: string;
     body?: string | null;
+    /** Deep-link target carried by the inbox materialization. */
+    action_url?: string | null;
     source_object?: string | null;
     source_id?: string | null;
     actor_name?: string | null;
@@ -33,4 +38,4 @@ export interface InboxPopoverProps {
     onMarkAllRead: () => void;
     onMarkRead: (id: string) => void;
 }
-export declare function InboxPopover({ notifications, unreadCount, pendingApprovalsCount, activities, onMarkAllRead, onMarkRead, }: InboxPopoverProps): import("react/jsx-runtime").JSX.Element;
+export declare function InboxPopover({ notifications, unreadCount, pendingApprovalsCount, activities, onMarkAllRead, onMarkRead, }: InboxPopoverProps): import("react").JSX.Element;

package/dist/layout/InboxPopover.js

@@ -77,11 +77,11 @@ export function InboxPopover({ notifications, unreadCount, pendingApprovalsCount
     };
     const goToAllNotifications = () => {
         setOpen(false);
-        // Always route through the setup app's sys_notification list view —
-        // it's the canonical full-page inbox and lives outside per-app sidebars.
-        // The `?view=mine` query selects the "Mine" tab so the user sees their
-        // own notifications by default (matching the popover scope).
-        navigate('/apps/setup/sys_notification?view=mine');
+        // Route through the setup app's sys_inbox_message list view — the
+        // canonical full-page inbox (ADR-0030 L5), outside per-app sidebars. The
+        // `?view=mine` query selects the user-scoped "Notifications" view, matching
+        // the popover scope.
+        navigate('/apps/setup/sys_inbox_message?view=mine');
     };
     const goToAllActivity = () => {
         setOpen(false);
@@ -92,9 +92,28 @@ export function InboxPopover({ notifications, unreadCount, pendingApprovalsCount
     };
     const handleNotificationClick = (n) => {
         onMarkRead(n.id);
+        const app = currentAppName ?? params.appName;
+        // Prefer the materialization's action_url (ADR-0030). The messaging
+        // pipeline synthesizes an app-relative `/{object}/{id}` link from the
+        // event's source when a producer didn't set an explicit url.
+        if (n.action_url) {
+            setOpen(false);
+            const url = n.action_url;
+            if (/^https?:\/\//i.test(url)) {
+                window.open(url, '_blank', 'noopener,noreferrer');
+                return;
+            }
+            if (url.startsWith('/apps/')) {
+                navigate(url);
+                return;
+            }
+            const rel = url.startsWith('/') ? url : `/${url}`;
+            navigate(app ? `/apps/${app}${rel}` : rel);
+            return;
+        }
+        // Back-compat fallback: explicit source object/record pointer.
         if (n.source_object && n.source_id) {
             setOpen(false);
-            const app = currentAppName ?? params.appName;
             const target = app
                 ? `/apps/${app}/${n.source_object}/${n.source_id}`
                 : `/objects/${n.source_object}/${n.source_id}`;

package/dist/layout/LocaleSwitcher.d.ts

@@ -4,4 +4,4 @@
  * Dropdown menu for switching the application language.
  * Uses the i18n context to change language at runtime.
  */
-export declare function LocaleSwitcher(): import("react/jsx-runtime").JSX.Element;
+export declare function LocaleSwitcher(): import("react").JSX.Element;

package/dist/layout/LocalizedSidebarTrigger.d.ts

@@ -0,0 +1,2 @@
+import * as React from 'react';
+export declare const LocalizedSidebarTrigger: React.ForwardRefExoticComponent<Omit<import("@object-ui/components").ButtonProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/layout/LocalizedSidebarTrigger.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { PanelLeft } from 'lucide-react';
+import { Button, cn, useSidebar } from '@object-ui/components';
+import { useObjectTranslation } from '@object-ui/i18n';
+export const LocalizedSidebarTrigger = React.forwardRef(({ className, onClick, 'aria-label': ariaLabel, title, ...props }, ref) => {
+    const { toggleSidebar } = useSidebar();
+    const { t } = useObjectTranslation();
+    const label = String(ariaLabel || title || t('common.toggleSidebar', { defaultValue: 'Toggle sidebar' }));
+    return (_jsxs(Button, { ref: ref, "data-sidebar": "trigger", variant: "ghost", size: "icon", className: cn('h-7 w-7', className), "aria-label": label, title: label, onClick: (event) => {
+            onClick?.(event);
+            toggleSidebar();
+        }, ...props, children: [_jsx(PanelLeft, {}), _jsx("span", { className: "sr-only", children: label })] }));
+});
+LocalizedSidebarTrigger.displayName = 'LocalizedSidebarTrigger';

package/dist/layout/MobileViewSwitcherContext.d.ts

@@ -54,7 +54,7 @@ export interface MobileViewSwitcherValue {
 /** Provider — mount once near the top of the console tree (above AppHeader). */
 export declare function MobileViewSwitcherProvider({ children }: {
     children: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 /** Read the currently registered switcher value (or `null`). */
 export declare function useMobileViewSwitcher(): MobileViewSwitcherValue | null;
 /**

package/dist/layout/ModeToggle.d.ts

@@ -1 +1 @@
-export declare function ModeToggle(): import("react/jsx-runtime").JSX.Element;
+export declare function ModeToggle(): import("react").JSX.Element;

package/dist/layout/PageHeader.d.ts

@@ -65,5 +65,5 @@ export interface PageHeaderProps {
  * (`--page-header-accent`) so consumers can override it without rebuilding
  * Tailwind classes.
  */
-export declare function PageHeader({ title, description, icon, actions, accentColor, sticky, className, 'data-testid': testId, }: PageHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function PageHeader({ title, description, icon, actions, accentColor, sticky, className, 'data-testid': testId, }: PageHeaderProps): React.JSX.Element;
 export default PageHeader;

package/dist/layout/UnifiedSidebar.d.ts

@@ -12,6 +12,7 @@
  *
  * @module
  */
+import * as React from 'react';
 /**
  * Lazy-resolved Lucide icon — see ../utils/getIcon for impl.
  * The local symbol is kept for backwards compat with existing call sites
@@ -23,5 +24,5 @@ interface UnifiedSidebarProps {
     /** Callback when user switches apps */
     onAppChange?: (name: string) => void;
 }
-export declare function UnifiedSidebar({ activeAppName }: UnifiedSidebarProps): import("react/jsx-runtime").JSX.Element;
+export declare function UnifiedSidebar({ activeAppName }: UnifiedSidebarProps): React.JSX.Element;
 export {};

package/dist/layout/UnifiedSidebar.js

@@ -16,20 +16,24 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import * as React from 'react';
 import { Link, useLocation } from 'react-router-dom';
 import { getIcon } from '../utils/getIcon';
-import { Sidebar, SidebarContent, SidebarFooter, SidebarHeader, SidebarGroup, SidebarGroupLabel, SidebarGroupContent, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarMenuAction, SidebarTrigger, useSidebar, } from '@object-ui/components';
+import { Sidebar, SidebarContent, SidebarFooter, SidebarHeader, SidebarGroup, SidebarGroupLabel, SidebarGroupContent, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarMenuAction, useSidebar, } from '@object-ui/components';
 import { Clock, Star, StarOff, ChevronRight, Home, Layers, } from 'lucide-react';
 import { NavigationRenderer } from '@object-ui/layout';
 import { useMetadata } from '../providers/MetadataProvider';
 import { useExpressionContext, evaluateVisibility } from '../providers/ExpressionProvider';
 import { usePermissions } from '@object-ui/permissions';
+import { useAuth, useIsWorkspaceAdmin } from '@object-ui/auth';
 import { useRecentItems } from '../hooks/useRecentItems';
 import { useFavorites } from '../hooks/useFavorites';
 import { useNavPins } from '../hooks/useNavPins';
+import { matchAppBySegment, appRouteSegment } from '../utils';
 import { useObjectTranslation, useObjectLabel } from '@object-ui/i18n';
 // useObjectLabel provides appLabel/appDescription for convention-based
 // i18n lookup — `{ns}.apps.{name}.label` resolves to the translated label
 // loaded from /api/v1/i18n/translations/:locale.
 import { useNavigationContext } from '../context/NavigationContext';
+import { useAppContextSelectors } from './ContextSelectors';
+import { LocalizedSidebarTrigger } from './LocalizedSidebarTrigger';
 // ---------------------------------------------------------------------------
 // useNavOrder – localStorage-persisted drag-and-drop reorder for nav items
 // ---------------------------------------------------------------------------
@@ -84,12 +88,27 @@ function useNavOrder(appName) {
     }, [orderMap, persist]);
     return { applyOrder, handleReorder };
 }
+function isMetadataDirectoryItem(item) {
+    return item.componentRef === 'metadata:directory';
+}
+function isPackagesItem(item) {
+    return item.componentRef === 'developer:packages';
+}
+function isOverviewGroup(item) {
+    if (item.type !== 'group')
+        return false;
+    const id = String(item.id ?? '').toLowerCase();
+    const label = typeof item.label === 'string' ? item.label.toLowerCase() : '';
+    return id === 'overview' || label === 'overview';
+}
 export function UnifiedSidebar({ activeAppName }) {
     const { isMobile, setOpenMobile } = useSidebar();
     const location = useLocation();
     const { t } = useObjectTranslation();
     const { objectLabel: resolveNavObjectLabel, dashboardLabel: resolveNavDashboardLabel, navGroupLabel: resolveNavGroupLabel, viewLabel: resolveNavViewLabel } = useObjectLabel();
     const { context, currentAppName } = useNavigationContext();
+    const { user } = useAuth();
+    const isWorkspaceAdmin = useIsWorkspaceAdmin();
     // Swipe-from-left-edge gesture to open sidebar on mobile
     React.useEffect(() => {
         const EDGE_THRESHOLD = 30;
@@ -101,7 +120,8 @@ export function UnifiedSidebar({ activeAppName }) {
         const handleTouchEnd = (e) => {
             const deltaX = e.changedTouches[0].clientX - touchStartX;
             if (touchStartX < EDGE_THRESHOLD && deltaX > SWIPE_DISTANCE && isMobile) {
-                document.querySelector('[data-sidebar="trigger"]')?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+                // Idempotent direct open (ADR-0054 C1) — no synthetic click dispatch.
+                setOpenMobile(true);
             }
         };
         document.addEventListener('touchstart', handleTouchStart, { passive: true });
@@ -110,13 +130,16 @@ export function UnifiedSidebar({ activeAppName }) {
             document.removeEventListener('touchstart', handleTouchStart);
             document.removeEventListener('touchend', handleTouchEnd);
         };
-    }, [isMobile]);
+    }, [isMobile, setOpenMobile]);
     const { recentItems } = useRecentItems();
     const { favorites, removeFavorite } = useFavorites();
     const { apps: metadataApps, objects: metadataObjects } = useMetadata();
     const apps = metadataApps || [];
-    const activeApps = apps.filter((a) => a.active !== false);
-    const activeApp = activeApps.find((a) => a.name === (activeAppName || currentAppName)) || activeApps[0];
+    // Filter switcher to non-hidden apps; active-app lookup spans all so
+    // direct navigation to /apps/account still renders.
+    const activeApps = apps.filter((a) => a.active !== false && a.hidden !== true);
+    // ADR-0048 (A) — route segment may be a package id; match by it (name fallback).
+    const activeApp = matchAppBySegment(apps.filter((a) => a.active !== false), activeAppName || currentAppName) || activeApps[0];
     // Drag-reorder and pin persistence
     const { applyOrder, handleReorder } = useNavOrder(activeApp?.name || 'home');
     const { togglePin, applyPins } = useNavPins();
@@ -134,17 +157,93 @@ export function UnifiedSidebar({ activeAppName }) {
     // Resolve navigation items
     const activeArea = areas.find((a) => a.id === activeAreaId);
     const appNavigation = activeArea?.navigation || activeApp?.navigation || [];
-    // Home navigation items
-    const homeNavigation = React.useMemo(() => [
-        { id: 'home-dashboard', label: t('home.nav', { defaultValue: 'Home' }), type: 'url', url: '/home', icon: 'home' },
-    ], [t]);
+    // App-level context selectors (e.g. Studio's package scope). Their
+    // values are injected into nav items as `{<id>}` template vars so a
+    // single dropdown transparently scopes every secondary menu.
+    const { contextValues, element: contextSelectorsUI } = useAppContextSelectors(activeApp?.name || 'home', activeApp?.contextSelectors, t);
+    // Home navigation items. For workspace admins we surface the full system
+    // ("Administration") nav right here on /home — previously the home context
+    // showed ONLY a "Home" link, so a fresh env (no apps yet) rendered a bare
+    // centered page with the real menu nowhere in sight. Mirrors AppSidebar's
+    // `systemFallbackNavigation` (sans the deprecated manual "Create App").
+    // Non-admins get just Home — system administration is owner/admin-gated.
+    const homeNavigation = React.useMemo(() => {
+        const items = [
+            { id: 'home-dashboard', label: t('home.nav', { defaultValue: 'Home' }), type: 'url', url: '/home', icon: 'home' },
+            // Package documentation portal (ADR-0046) — visible to all users, not
+            // just workspace admins, so it lives in the base items rather than the
+            // admin cluster below.
+            { id: 'docs', label: t('layout.systemNav.documentation', { defaultValue: 'Documentation' }), type: 'url', url: '/docs', icon: 'book-open' },
+        ];
+        if (isWorkspaceAdmin) {
+            const adminItems = [
+                { id: 'sys-settings', label: t('layout.systemNav.systemSettings', { defaultValue: 'System Settings' }), type: 'url', url: '/apps/setup', icon: 'settings' },
+                { id: 'sys-apps', label: t('layout.systemNav.applications', { defaultValue: 'Applications' }), type: 'url', url: '/apps/setup/system/apps', icon: 'layout-grid' },
+                { id: 'sys-marketplace', label: t('layout.systemNav.appMarketplace', { defaultValue: 'App Marketplace' }), type: 'url', url: '/apps/setup/system/marketplace', icon: 'store' },
+                { id: 'sys-objects', label: t('layout.systemNav.objectManager', { defaultValue: 'Object Manager' }), type: 'url', url: '/apps/setup/system/metadata/object', icon: 'database' },
+                { id: 'sys-datasources', label: t('layout.systemNav.datasources', { defaultValue: 'Datasources' }), type: 'url', url: '/apps/setup/component/metadata/resource?type=datasource', icon: 'database' },
+                { id: 'sys-users', label: t('layout.systemNav.users', { defaultValue: 'Users' }), type: 'url', url: '/apps/setup/system/users', icon: 'users' },
+                { id: 'sys-orgs', label: t('layout.systemNav.organizations', { defaultValue: 'Organizations' }), type: 'url', url: '/apps/setup/system/organizations', icon: 'building-2' },
+                { id: 'sys-roles', label: t('layout.systemNav.roles', { defaultValue: 'Roles' }), type: 'url', url: '/apps/setup/system/roles', icon: 'shield' },
+                { id: 'sys-config', label: t('layout.systemNav.configuration', { defaultValue: 'Configuration' }), type: 'url', url: '/apps/setup/system/settings', icon: 'sliders-horizontal' },
+            ];
+            items.push({
+                id: 'sys-administration',
+                label: t('layout.systemNav.administration', { defaultValue: 'Administration' }),
+                type: 'group',
+                icon: 'shield',
+                children: adminItems,
+            });
+        }
+        return items;
+    }, [t, isWorkspaceAdmin]);
     // Determine which navigation to show based on context
     const navigationItems = context === 'home' ? homeNavigation : appNavigation;
+    const basePath = context === 'app' && activeApp ? `/apps/${appRouteSegment(activeApp)}` : '';
+    const isStudioApp = context === 'app' && activeApp?.name === 'studio';
+    const studioHomeSearch = React.useMemo(() => {
+        if (!isStudioApp)
+            return '';
+        const packageId = new URLSearchParams(location.search).get('package') || contextValues.active_package;
+        return packageId ? `?package=${encodeURIComponent(packageId)}` : '';
+    }, [contextValues.active_package, isStudioApp, location.search]);
+    const studioNavigationItems = React.useMemo(() => {
+        if (context !== 'app' || activeApp?.name !== 'studio')
+            return navigationItems;
+        const packageManagementLabel = t('sidebar.packageManagement', {
+            defaultValue: 'Package management',
+        });
+        const walk = (items) => items.flatMap((item) => {
+            if (isMetadataDirectoryItem(item))
+                return [];
+            const children = item.children?.length ? walk(item.children) : item.children;
+            if (item.type === 'group' && children?.length === 0)
+                return [];
+            if (isPackagesItem(item)) {
+                return [{
+                        ...item,
+                        type: 'url',
+                        label: packageManagementLabel,
+                        url: `${basePath}/component/developer/packages${studioHomeSearch}`,
+                        children,
+                    }];
+            }
+            if (children !== item.children) {
+                return [{ ...item, children }];
+            }
+            return [item];
+        });
+        return walk(navigationItems).flatMap((item) => {
+            if (!isOverviewGroup(item))
+                return [item];
+            return item.children ?? [];
+        });
+    }, [activeApp?.name, basePath, context, navigationItems, studioHomeSearch, t]);
     // Apply saved order and pin state
     const processedNavigation = React.useMemo(() => {
-        const ordered = applyOrder(navigationItems);
+        const ordered = applyOrder(studioNavigationItems);
         return applyPins(ordered);
-    }, [navigationItems, applyOrder, applyPins]);
+    }, [studioNavigationItems, applyOrder, applyPins]);
     // Recent section collapsed by default
     const [recentExpanded, setRecentExpanded] = React.useState(false);
     // Visibility evaluation
@@ -170,14 +269,16 @@ export function UnifiedSidebar({ activeAppName }) {
         }
         return true;
     }, [registeredObjectNames]);
-    const basePath = context === 'app' && activeApp ? `/apps/${activeApp.name}` : '';
-    return (_jsx(_Fragment, { children: _jsxs(Sidebar, { collapsible: "icon", className: "!top-14 !h-[calc(100svh-3.5rem)]", children: [isMobile && context === 'app' && (_jsx(SidebarHeader, { className: "border-b p-1.5", children: _jsx(SidebarMenu, { children: _jsx(SidebarMenuItem, { children: _jsx(SidebarMenuButton, { asChild: true, className: "h-9 text-sm font-medium", children: _jsxs(Link, { to: "/home", onClick: () => setOpenMobile(false), "data-testid": "mobile-sidebar-home", children: [_jsx(Home, { className: "h-4 w-4" }), _jsx("span", { children: t('home.nav', { defaultValue: 'Home' }) })] }) }) }) }) })), _jsx(SidebarContent, { className: "pt-2", children: _jsx("div", { className: "transition-opacity duration-200 ease-in-out", children: context === 'app' && activeApp ? (_jsxs(_Fragment, { children: [areas.length > 1 && (_jsxs(SidebarGroup, { children: [_jsxs(SidebarGroupLabel, { className: "flex items-center gap-1.5", children: [_jsx(Layers, { className: "h-3.5 w-3.5" }), t('sidebar.area', { defaultValue: 'Area' })] }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: areas.map((area) => {
+    const isStudioHomeActive = isStudioApp && location.pathname.replace(/\/+$/, '') === basePath;
+    return (_jsx(_Fragment, { children: _jsxs(Sidebar, { collapsible: "icon", className: "!top-14 !h-[calc(100svh-3.5rem)]", children: [isMobile && context === 'app' && (_jsx(SidebarHeader, { className: "border-b p-1.5", children: _jsx(SidebarMenu, { children: _jsx(SidebarMenuItem, { children: _jsx(SidebarMenuButton, { asChild: true, className: "min-h-[44px] text-[15px] font-medium rounded-xl", children: _jsxs(Link, { to: "/home", onClick: () => setOpenMobile(false), "data-testid": "mobile-sidebar-home", children: [_jsx(Home, { className: "h-5 w-5" }), _jsx("span", { children: t('home.nav', { defaultValue: 'Home' }) })] }) }) }) }) })), _jsx(SidebarContent, { className: "pt-2", children: _jsx("div", { className: "transition-opacity duration-200 ease-in-out", children: context === 'app' && activeApp ? (_jsxs(_Fragment, { children: [contextSelectorsUI && (_jsx(SidebarGroup, { className: "group-data-[state=collapsed]:hidden px-2 pb-1", children: _jsx("div", { className: "rounded-lg border border-sidebar-border/70 bg-sidebar-accent/25 p-1.5 shadow-xs", children: _jsx(SidebarGroupContent, { children: contextSelectorsUI }) }) })), isStudioApp && (_jsx(SidebarGroup, { children: _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: _jsx(SidebarMenuItem, { children: _jsx(SidebarMenuButton, { asChild: true, isActive: isStudioHomeActive, tooltip: t('home.nav', { defaultValue: 'Home' }), children: _jsxs(Link, { to: { pathname: basePath, search: studioHomeSearch }, children: [_jsx(Home, { className: "h-4 w-4" }), _jsx("span", { children: t('home.nav', { defaultValue: 'Home' }) })] }) }) }) }) }) })), areas.length > 1 && (_jsxs(SidebarGroup, { children: [_jsxs(SidebarGroupLabel, { className: "flex items-center gap-1.5", children: [_jsx(Layers, { className: "h-3.5 w-3.5" }), t('sidebar.area', { defaultValue: 'Area' })] }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: areas.map((area) => {
                                                     const AreaIcon = getIcon(area.icon);
                                                     const isActiveArea = area.id === activeAreaId;
                                                     return (_jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { isActive: isActiveArea, tooltip: area.label, onClick: () => setActiveAreaId(area.id), children: [_jsx(AreaIcon, { className: "h-4 w-4" }), _jsx("span", { children: area.label })] }) }, area.id));
-                                                }) }) })] })), _jsx(NavigationRenderer, { items: processedNavigation, basePath: basePath, evaluateVisibility: evalVis, checkPermission: checkPerm, checkCapability: checkCap, enablePinning: !isMobile, onPinToggle: togglePin, enableReorder: !isMobile, onReorder: handleReorder, resolveObjectLabel: (objectName, fallback) => resolveNavObjectLabel({ name: objectName, label: fallback }), resolveDashboardLabel: (dashboardName, fallback) => resolveNavDashboardLabel({ name: dashboardName, label: fallback }), resolveGroupLabel: activeApp ? (groupId, fallback) => resolveNavGroupLabel(activeApp.name, groupId, fallback) : undefined, resolveItemLabel: activeApp ? (itemId, fallback) => resolveNavGroupLabel(activeApp.name, itemId, fallback) : undefined, resolveViewLabel: (objectName, viewName, fallback) => resolveNavViewLabel(objectName, viewName, fallback), t: t }), recentItems.length > 0 && (_jsxs(SidebarGroup, { children: [_jsxs(SidebarGroupLabel, { className: "flex items-center gap-1.5 cursor-pointer select-none", onClick: () => setRecentExpanded(prev => !prev), children: [_jsx(ChevronRight, { className: `h-3 w-3 transition-transform duration-150 ${recentExpanded ? 'rotate-90' : ''}` }), _jsx(Clock, { className: "h-3.5 w-3.5" }), t('sidebar.recent', { defaultValue: 'Recent' })] }), recentExpanded && (_jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: recentItems.slice(0, 5).map(item => (_jsx(SidebarMenuItem, { children: _jsx(SidebarMenuButton, { asChild: true, tooltip: item.label, children: _jsxs(Link, { to: item.href, children: [_jsx("span", { className: "text-muted-foreground", children: item.type === 'dashboard' ? '📊' : item.type === 'report' ? '📈' : '📄' }), _jsx("span", { className: "truncate", children: item.label })] }) }) }, item.id))) }) }))] })), favorites.some(f => f.type !== 'nav') && (_jsxs(SidebarGroup, { children: [_jsxs(SidebarGroupLabel, { className: "flex items-center gap-1.5", children: [_jsx(Star, { className: "h-3.5 w-3.5" }), t('sidebar.favorites', { defaultValue: 'Favorites' })] }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: favorites.filter(f => f.type !== 'nav').slice(0, 8).map(item => (_jsxs(SidebarMenuItem, { children: [_jsx(SidebarMenuButton, { asChild: true, tooltip: item.label, children: _jsxs(Link, { to: item.href, children: [_jsx("span", { className: "text-muted-foreground", children: item.type === 'dashboard' ? '📊' : item.type === 'report' ? '📈' : item.type === 'page' ? '📄' : '📋' }), _jsx("span", { className: "truncate", children: item.label })] }) }), _jsx(SidebarMenuAction, { showOnHover: true, onClick: (e) => { e.stopPropagation(); removeFavorite(item.id); }, "aria-label": t('sidebar.removeFromFavorites', { defaultValue: 'Remove {{name}} from favorites', name: item.label }), children: _jsx(StarOff, { className: "h-3 w-3" }) })] }, item.id))) }) })] }))] })) : (_jsxs(_Fragment, { children: [_jsx(SidebarGroup, { children: _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: homeNavigation.map((item) => {
+                                                }) }) })] })), _jsx(NavigationRenderer, { items: processedNavigation, basePath: basePath, evaluateVisibility: evalVis, checkPermission: checkPerm, checkCapability: checkCap, enablePinning: !isMobile, onPinToggle: togglePin, enableReorder: !isMobile, onReorder: handleReorder, resolveObjectLabel: (objectName, fallback) => resolveNavObjectLabel({ name: objectName, label: fallback }), resolveDashboardLabel: (dashboardName, fallback) => resolveNavDashboardLabel({ name: dashboardName, label: fallback }), resolveGroupLabel: activeApp ? (groupId, fallback) => resolveNavGroupLabel(activeApp.name, groupId, fallback) : undefined, resolveItemLabel: activeApp ? (itemId, fallback) => (activeApp.name === 'studio' && fallback === t('sidebar.packageManagement', { defaultValue: 'Package management' })
+                                        ? fallback
+                                        : resolveNavGroupLabel(activeApp.name, itemId, fallback)) : undefined, resolveViewLabel: (objectName, viewName, fallback) => resolveNavViewLabel(objectName, viewName, fallback), t: t, templateContext: { currentUserId: user?.id ?? null, contextValues } }), recentItems.length > 0 && (_jsxs(SidebarGroup, { children: [_jsxs(SidebarGroupLabel, { className: "flex items-center gap-1.5 cursor-pointer select-none", onClick: () => setRecentExpanded(prev => !prev), children: [_jsx(ChevronRight, { className: `h-3 w-3 transition-transform duration-150 ${recentExpanded ? 'rotate-90' : ''}` }), _jsx(Clock, { className: "h-3.5 w-3.5" }), t('sidebar.recent', { defaultValue: 'Recent' })] }), recentExpanded && (_jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: recentItems.slice(0, 5).map(item => (_jsx(SidebarMenuItem, { children: _jsx(SidebarMenuButton, { asChild: true, tooltip: item.label, children: _jsxs(Link, { to: item.href, children: [_jsx("span", { className: "text-muted-foreground", children: item.type === 'dashboard' ? '📊' : item.type === 'report' ? '📈' : '📄' }), _jsx("span", { className: "truncate", children: item.label })] }) }) }, item.id))) }) }))] })), favorites.some(f => f.type !== 'nav') && (_jsxs(SidebarGroup, { children: [_jsxs(SidebarGroupLabel, { className: "flex items-center gap-1.5", children: [_jsx(Star, { className: "h-3.5 w-3.5" }), t('sidebar.favorites', { defaultValue: 'Favorites' })] }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: favorites.filter(f => f.type !== 'nav').slice(0, 8).map(item => (_jsxs(SidebarMenuItem, { children: [_jsx(SidebarMenuButton, { asChild: true, tooltip: item.label, children: _jsxs(Link, { to: item.href, children: [_jsx("span", { className: "text-muted-foreground", children: item.type === 'dashboard' ? '📊' : item.type === 'report' ? '📈' : item.type === 'page' ? '📄' : '📋' }), _jsx("span", { className: "truncate", children: item.label })] }) }), _jsx(SidebarMenuAction, { showOnHover: true, onClick: (e) => { e.stopPropagation(); removeFavorite(item.id); }, "aria-label": t('sidebar.removeFromFavorites', { defaultValue: 'Remove {{name}} from favorites', name: item.label }), children: _jsx(StarOff, { className: "h-3 w-3" }) })] }, item.id))) }) })] }))] })) : (_jsxs(_Fragment, { children: [_jsx(SidebarGroup, { children: _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: homeNavigation.map((item) => {
                                                 const NavIcon = getIcon(item.icon);
                                                 const isActive = location.pathname === item.url;
                                                 return (_jsx(SidebarMenuItem, { children: _jsx(SidebarMenuButton, { asChild: true, tooltip: item.label, isActive: isActive, children: _jsxs(Link, { to: item.url || '/home', children: [_jsx(NavIcon, { className: "h-4 w-4" }), _jsx("span", { children: item.label })] }) }) }, item.id));
-                                            }) }) }) }), favorites.filter(f => f.type === 'object' || f.type === 'dashboard' || f.type === 'page').length > 0 && (_jsxs(SidebarGroup, { children: [_jsxs(SidebarGroupLabel, { className: "flex items-center gap-1.5", children: [_jsx(Star, { className: "h-3.5 w-3.5" }), t('sidebar.starred', { defaultValue: 'Starred' })] }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: favorites.filter(f => f.type === 'object' || f.type === 'dashboard' || f.type === 'page').slice(0, 8).map(item => (_jsxs(SidebarMenuItem, { children: [_jsx(SidebarMenuButton, { asChild: true, tooltip: item.label, children: _jsxs(Link, { to: item.href, children: [_jsx("span", { className: "text-muted-foreground", children: item.type === 'dashboard' ? '📊' : item.type === 'page' ? '📄' : '📋' }), _jsx("span", { className: "truncate", children: item.label })] }) }), _jsx(SidebarMenuAction, { showOnHover: true, onClick: (e) => { e.stopPropagation(); removeFavorite(item.id); }, "aria-label": t('sidebar.removeFromFavorites', { defaultValue: 'Remove {{name}} from favorites', name: item.label }), children: _jsx(StarOff, { className: "h-3 w-3" }) })] }, item.id))) }) })] }))] })) }) }), _jsx(SidebarFooter, { className: "border-t p-1", children: _jsx(SidebarTrigger, { className: "w-full justify-start pl-2 group-data-[state=collapsed]:justify-center group-data-[state=collapsed]:pl-0" }) })] }) }));
+                                            }) }) }) }), favorites.filter(f => f.type === 'object' || f.type === 'dashboard' || f.type === 'page').length > 0 && (_jsxs(SidebarGroup, { children: [_jsxs(SidebarGroupLabel, { className: "flex items-center gap-1.5", children: [_jsx(Star, { className: "h-3.5 w-3.5" }), t('sidebar.starred', { defaultValue: 'Starred' })] }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: favorites.filter(f => f.type === 'object' || f.type === 'dashboard' || f.type === 'page').slice(0, 8).map(item => (_jsxs(SidebarMenuItem, { children: [_jsx(SidebarMenuButton, { asChild: true, tooltip: item.label, children: _jsxs(Link, { to: item.href, children: [_jsx("span", { className: "text-muted-foreground", children: item.type === 'dashboard' ? '📊' : item.type === 'page' ? '📄' : '📋' }), _jsx("span", { className: "truncate", children: item.label })] }) }), _jsx(SidebarMenuAction, { showOnHover: true, onClick: (e) => { e.stopPropagation(); removeFavorite(item.id); }, "aria-label": t('sidebar.removeFromFavorites', { defaultValue: 'Remove {{name}} from favorites', name: item.label }), children: _jsx(StarOff, { className: "h-3 w-3" }) })] }, item.id))) }) })] }))] })) }) }), _jsx(SidebarFooter, { className: "border-t p-1", children: _jsx(LocalizedSidebarTrigger, { className: "w-full justify-start pl-2 group-data-[state=collapsed]:justify-center group-data-[state=collapsed]:pl-0" }) })] }) }));
 }