@object-ui/app-shell 3.3.0 → 3.3.1

package/dist/console/organizations/manage/SettingsPage.js

@@ -0,0 +1,141 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * SettingsPage
+ *
+ * Organization settings: general info form + danger zone.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { Button, Input, Label, Separator, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, } from '@object-ui/components';
+import { useAuth } from '@object-ui/auth';
+import { useObjectTranslation } from '@object-ui/i18n';
+import { Loader2 } from 'lucide-react';
+import { toast } from 'sonner';
+import { useNavigate } from 'react-router-dom';
+import { useOrgContext } from './orgContext';
+export function SettingsPage() {
+    const { t } = useObjectTranslation();
+    const { org } = useOrgContext();
+    const { user, getMembers, updateOrganization, deleteOrganization, leaveOrganization, } = useAuth();
+    const navigate = useNavigate();
+    // Form state
+    const [name, setName] = useState(org.name);
+    const [slug, setSlug] = useState(org.slug ?? '');
+    const [logo, setLogo] = useState(org.logo ?? '');
+    const [isSaving, setIsSaving] = useState(false);
+    // Owner check
+    const [isOwner, setIsOwner] = useState(null);
+    const [membersLoading, setMembersLoading] = useState(true);
+    // Danger zone dialogs
+    const [isLeaveOpen, setIsLeaveOpen] = useState(false);
+    const [isDeleteOpen, setIsDeleteOpen] = useState(false);
+    const [deleteConfirmSlug, setDeleteConfirmSlug] = useState('');
+    const [isDangerLoading, setIsDangerLoading] = useState(false);
+    // Sync form when org changes (e.g., after save)
+    useEffect(() => {
+        setName(org.name);
+        setSlug(org.slug ?? '');
+        setLogo(org.logo ?? '');
+    }, [org]);
+    // Load members to determine if current user is owner
+    useEffect(() => {
+        let cancelled = false;
+        setMembersLoading(true);
+        getMembers(org.id)
+            .then((members) => {
+            if (cancelled)
+                return;
+            const me = members.find((m) => m.userId === user?.id);
+            setIsOwner(me?.role === 'owner');
+        })
+            .catch(() => {
+            if (!cancelled)
+                setIsOwner(false);
+        })
+            .finally(() => {
+            if (!cancelled)
+                setMembersLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [org.id, user?.id, getMembers]);
+    const handleSave = useCallback(async (e) => {
+        e.preventDefault();
+        setIsSaving(true);
+        try {
+            await updateOrganization(org.id, {
+                name: name.trim(),
+                slug: slug.trim() || undefined,
+                logo: logo.trim() || undefined,
+            });
+            toast.success(t('organization.settings.saved', { defaultValue: 'Settings saved' }));
+        }
+        catch (err) {
+            toast.error(err instanceof Error
+                ? err.message
+                : t('organization.settings.saveFailed', { defaultValue: 'Failed to save settings' }));
+        }
+        finally {
+            setIsSaving(false);
+        }
+    }, [org.id, name, slug, logo, updateOrganization, t]);
+    const handleLeave = async () => {
+        setIsDangerLoading(true);
+        try {
+            await leaveOrganization(org.id);
+            toast.success(t('organization.settings.leftOrg', { defaultValue: 'You have left the organization' }));
+            navigate('/organizations');
+        }
+        catch (err) {
+            toast.error(err instanceof Error
+                ? err.message
+                : t('organization.settings.leaveFailed', { defaultValue: 'Failed to leave organization' }));
+        }
+        finally {
+            setIsDangerLoading(false);
+        }
+    };
+    const handleDelete = async () => {
+        setIsDangerLoading(true);
+        try {
+            await deleteOrganization(org.id);
+            toast.success(t('organization.settings.deleted', { defaultValue: 'Organization deleted' }));
+            navigate('/organizations');
+        }
+        catch (err) {
+            toast.error(err instanceof Error
+                ? err.message
+                : t('organization.settings.deleteFailed', { defaultValue: 'Failed to delete organization' }));
+        }
+        finally {
+            setIsDangerLoading(false);
+        }
+    };
+    if (membersLoading) {
+        return (_jsx("div", { className: "flex items-center justify-center py-20", children: _jsx(Loader2, { className: "h-5 w-5 animate-spin text-muted-foreground" }) }));
+    }
+    return (_jsxs("div", { className: "space-y-8", "data-testid": "settings-page", children: [_jsxs("section", { children: [_jsx("h2", { className: "text-lg font-semibold", children: t('organization.settings.generalTitle', { defaultValue: 'General' }) }), _jsx("p", { className: "text-sm text-muted-foreground mt-1", children: t('organization.settings.generalDescription', {
+                            defaultValue: 'Update your organization information.',
+                        }) }), _jsx(Separator, { className: "my-4" }), !isOwner ? (_jsx("div", { className: "rounded-lg border bg-muted/50 p-4 text-sm text-muted-foreground", children: t('organization.settings.readOnlyNote', {
+                            defaultValue: 'Only owners can change settings.',
+                        }) })) : (_jsxs("form", { onSubmit: handleSave, className: "space-y-4 max-w-md", children: [_jsxs("div", { className: "grid gap-2", children: [_jsx(Label, { htmlFor: "org-name", children: t('organization.settings.nameLabel', { defaultValue: 'Organization name' }) }), _jsx(Input, { id: "org-name", value: name, onChange: (e) => setName(e.target.value), required: true, "data-testid": "settings-name-input" })] }), _jsxs("div", { className: "grid gap-2", children: [_jsx(Label, { htmlFor: "org-slug", children: t('organization.settings.slugLabel', { defaultValue: 'Slug' }) }), _jsx(Input, { id: "org-slug", value: slug, onChange: (e) => setSlug(e.target.value), "data-testid": "settings-slug-input" })] }), _jsxs("div", { className: "grid gap-2", children: [_jsx(Label, { htmlFor: "org-logo", children: t('organization.settings.logoLabel', { defaultValue: 'Logo URL (optional)' }) }), _jsx(Input, { id: "org-logo", type: "url", value: logo, onChange: (e) => setLogo(e.target.value), placeholder: "https://example.com/logo.png", "data-testid": "settings-logo-input" })] }), _jsxs(Button, { type: "submit", disabled: isSaving, "data-testid": "settings-save-btn", children: [isSaving && _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }), t('organization.settings.save', { defaultValue: 'Save changes' })] })] }))] }), _jsxs("section", { children: [_jsx("h2", { className: "text-lg font-semibold text-destructive", children: t('organization.settings.dangerZone', { defaultValue: 'Danger zone' }) }), _jsx(Separator, { className: "my-4" }), _jsxs("div", { className: "space-y-4 rounded-lg border border-destructive/50 bg-destructive/5 p-4", children: [_jsxs("div", { className: "flex items-center justify-between gap-4", children: [_jsxs("div", { children: [_jsx("p", { className: "font-medium text-sm", children: t('organization.settings.leaveTitle', { defaultValue: 'Leave organization' }) }), _jsx("p", { className: "text-xs text-muted-foreground", children: t('organization.settings.leaveDescription', {
+                                                    defaultValue: 'You will lose access to this organization.',
+                                                }) })] }), _jsx(Button, { variant: "destructive", size: "sm", onClick: () => setIsLeaveOpen(true), children: t('organization.settings.leaveAction', { defaultValue: 'Leave' }) })] }), _jsx(Separator, {}), _jsxs("div", { className: "flex items-center justify-between gap-4", children: [_jsxs("div", { children: [_jsx("p", { className: "font-medium text-sm", children: t('organization.settings.deleteTitle', { defaultValue: 'Delete organization' }) }), _jsx("p", { className: "text-xs text-muted-foreground", children: t('organization.settings.deleteDescription', {
+                                                    defaultValue: 'Permanently delete this organization and all its data.',
+                                                }) })] }), _jsx(Button, { variant: "destructive", size: "sm", onClick: () => {
+                                            setDeleteConfirmSlug('');
+                                            setIsDeleteOpen(true);
+                                        }, disabled: !isOwner, children: t('organization.settings.deleteAction', { defaultValue: 'Delete' }) })] })] })] }), _jsx(AlertDialog, { open: isLeaveOpen, onOpenChange: setIsLeaveOpen, children: _jsxs(AlertDialogContent, { children: [_jsxs(AlertDialogHeader, { children: [_jsx(AlertDialogTitle, { children: t('organization.settings.leaveConfirmTitle', { defaultValue: 'Leave organization?' }) }), _jsx(AlertDialogDescription, { children: t('organization.settings.leaveConfirmDescription', {
+                                        defaultValue: 'Are you sure you want to leave {{name}}? You will lose access immediately.',
+                                        name: org.name,
+                                    }) })] }), _jsxs(AlertDialogFooter, { children: [_jsx(AlertDialogCancel, { disabled: isDangerLoading, children: t('common.cancel', { defaultValue: 'Cancel' }) }), _jsxs(AlertDialogAction, { className: "bg-destructive text-destructive-foreground hover:bg-destructive/90", onClick: handleLeave, disabled: isDangerLoading, children: [isDangerLoading && _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }), t('organization.settings.leaveConfirmAction', { defaultValue: 'Leave' })] })] })] }) }), _jsx(AlertDialog, { open: isDeleteOpen, onOpenChange: (open) => {
+                    setIsDeleteOpen(open);
+                    if (!open)
+                        setDeleteConfirmSlug('');
+                }, children: _jsxs(AlertDialogContent, { children: [_jsxs(AlertDialogHeader, { children: [_jsx(AlertDialogTitle, { children: t('organization.settings.deleteConfirmTitle', { defaultValue: 'Delete organization?' }) }), _jsx(AlertDialogDescription, { children: t('organization.settings.deleteConfirmDescription', {
+                                        defaultValue: 'This action is irreversible. All data will be permanently deleted. Type the organization slug to confirm.',
+                                    }) })] }), _jsxs("div", { className: "px-6 pb-2", children: [_jsx(Label, { htmlFor: "delete-confirm-slug", className: "text-sm font-medium", children: t('organization.settings.deleteConfirmSlugLabel', {
+                                        defaultValue: 'Type "{{slug}}" to confirm',
+                                        slug: org.slug,
+                                    }) }), _jsx(Input, { id: "delete-confirm-slug", className: "mt-2", value: deleteConfirmSlug, onChange: (e) => setDeleteConfirmSlug(e.target.value), placeholder: org.slug, "data-testid": "delete-confirm-slug-input" })] }), _jsxs(AlertDialogFooter, { children: [_jsx(AlertDialogCancel, { disabled: isDangerLoading, children: t('common.cancel', { defaultValue: 'Cancel' }) }), _jsxs(AlertDialogAction, { className: "bg-destructive text-destructive-foreground hover:bg-destructive/90", onClick: handleDelete, disabled: isDangerLoading || deleteConfirmSlug !== org.slug, children: [isDangerLoading && _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }), t('organization.settings.deleteConfirmAction', { defaultValue: 'Delete organization' })] })] })] }) })] }));
+}

package/dist/console/organizations/manage/orgContext.d.ts

@@ -0,0 +1,5 @@
+import type { AuthOrganization } from '@object-ui/auth';
+export interface OrgOutletContext {
+    org: AuthOrganization;
+}
+export declare function useOrgContext(): OrgOutletContext;

package/dist/console/organizations/manage/orgContext.js

@@ -0,0 +1,4 @@
+import { useOutletContext } from 'react-router-dom';
+export function useOrgContext() {
+    return useOutletContext();
+}

package/dist/context/FavoritesProvider.d.ts

@@ -0,0 +1,50 @@
+/**
+ * FavoritesProvider
+ *
+ * React Context + Provider for shared favorites state across all consumers
+ * (HomePage, AppCard, AppSidebar, UnifiedSidebar, StarredApps).
+ *
+ * Replaces the standalone `useFavorites` hook pattern — all callers now share
+ * a single state instance so that toggling a star in AppCard immediately
+ * reflects in HomePage's Starred section and sidebar.
+ *
+ * Persistence: localStorage (key: "objectui-favorites", max 20 items).
+ *
+ * TODO: Migrate persistence to server-side storage via the adapter/API layer
+ * (e.g. PUT /api/user/preferences) so favorites sync across devices and browsers.
+ * The provider should accept an optional `persistenceAdapter` prop that implements
+ * `load(): Promise<FavoriteItem[]>` and `save(items: FavoriteItem[]): Promise<void>`.
+ * When the adapter is provided, localStorage should be used only as a fallback
+ * during the initial load while the server response is in-flight.
+ *
+ * @module
+ */
+import { type ReactNode } from 'react';
+export interface FavoriteItem {
+    /** Unique key, e.g. "object:contact" or "dashboard:sales_overview" */
+    id: string;
+    label: string;
+    href: string;
+    type: 'object' | 'dashboard' | 'page' | 'report';
+    /** ISO timestamp of when the item was favorited */
+    favoritedAt: string;
+}
+interface FavoritesContextValue {
+    favorites: FavoriteItem[];
+    addFavorite: (item: Omit<FavoriteItem, 'favoritedAt'>) => void;
+    removeFavorite: (id: string) => void;
+    toggleFavorite: (item: Omit<FavoriteItem, 'favoritedAt'>) => void;
+    isFavorite: (id: string) => boolean;
+    clearFavorites: () => void;
+}
+interface FavoritesProviderProps {
+    children: ReactNode;
+}
+export declare function FavoritesProvider({ children }: FavoritesProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Access shared favorites state.
+ *
+ * Must be used inside `<FavoritesProvider>`.
+ */
+export declare function useFavorites(): FavoritesContextValue;
+export {};

package/dist/context/FavoritesProvider.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * FavoritesProvider
+ *
+ * React Context + Provider for shared favorites state across all consumers
+ * (HomePage, AppCard, AppSidebar, UnifiedSidebar, StarredApps).
+ *
+ * Replaces the standalone `useFavorites` hook pattern — all callers now share
+ * a single state instance so that toggling a star in AppCard immediately
+ * reflects in HomePage's Starred section and sidebar.
+ *
+ * Persistence: localStorage (key: "objectui-favorites", max 20 items).
+ *
+ * TODO: Migrate persistence to server-side storage via the adapter/API layer
+ * (e.g. PUT /api/user/preferences) so favorites sync across devices and browsers.
+ * The provider should accept an optional `persistenceAdapter` prop that implements
+ * `load(): Promise<FavoriteItem[]>` and `save(items: FavoriteItem[]): Promise<void>`.
+ * When the adapter is provided, localStorage should be used only as a fallback
+ * during the initial load while the server response is in-flight.
+ *
+ * @module
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
+// ---------------------------------------------------------------------------
+// Storage helpers
+// ---------------------------------------------------------------------------
+const STORAGE_KEY = 'objectui-favorites';
+const MAX_FAVORITES = 20;
+function loadFavorites() {
+    try {
+        const raw = localStorage.getItem(STORAGE_KEY);
+        return raw ? JSON.parse(raw) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function saveFavorites(items) {
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(items));
+    }
+    catch {
+        // Storage full — silently ignore
+    }
+}
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+const FavoritesContext = createContext(null);
+export function FavoritesProvider({ children }) {
+    const [favorites, setFavorites] = useState(loadFavorites);
+    // Re-sync from storage on mount (handles cases where storage was written
+    // before this provider was mounted, e.g. on initial page load).
+    useEffect(() => {
+        setFavorites(loadFavorites());
+    }, []);
+    const addFavorite = useCallback((item) => {
+        setFavorites(prev => {
+            if (prev.some(f => f.id === item.id))
+                return prev;
+            const updated = [
+                { ...item, favoritedAt: new Date().toISOString() },
+                ...prev,
+            ].slice(0, MAX_FAVORITES);
+            saveFavorites(updated);
+            return updated;
+        });
+    }, []);
+    const removeFavorite = useCallback((id) => {
+        setFavorites(prev => {
+            const updated = prev.filter(f => f.id !== id);
+            saveFavorites(updated);
+            return updated;
+        });
+    }, []);
+    const toggleFavorite = useCallback((item) => {
+        setFavorites(prev => {
+            const exists = prev.some(f => f.id === item.id);
+            const updated = exists
+                ? prev.filter(f => f.id !== item.id)
+                : [{ ...item, favoritedAt: new Date().toISOString() }, ...prev].slice(0, MAX_FAVORITES);
+            saveFavorites(updated);
+            return updated;
+        });
+    }, []);
+    const clearFavorites = useCallback(() => {
+        setFavorites([]);
+        saveFavorites([]);
+    }, []);
+    const value = useMemo(() => ({
+        favorites,
+        addFavorite,
+        removeFavorite,
+        toggleFavorite,
+        // Inlined here so useMemo sees the freshest `favorites` without needing
+        // a separate useCallback([favorites]) entry in the deps array.
+        isFavorite: (id) => favorites.some(f => f.id === id),
+        clearFavorites,
+    }), 
+    // addFavorite / removeFavorite / toggleFavorite / clearFavorites are all
+    // stable (useCallback with [] deps) and never cause extra re-renders.
+    [favorites, addFavorite, removeFavorite, toggleFavorite, clearFavorites]);
+    return (_jsx(FavoritesContext.Provider, { value: value, children: children }));
+}
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+/**
+ * Access shared favorites state.
+ *
+ * Must be used inside `<FavoritesProvider>`.
+ */
+export function useFavorites() {
+    const ctx = useContext(FavoritesContext);
+    if (!ctx) {
+        // Graceful fallback: when a consumer (e.g. AppSidebar) is rendered outside
+        // a FavoritesProvider — common in unit tests that only need to assert on
+        // navigation rendering — return a no-op implementation rather than crash.
+        return {
+            favorites: [],
+            addFavorite: () => { },
+            removeFavorite: () => { },
+            toggleFavorite: () => { },
+            isFavorite: () => false,
+            clearFavorites: () => { },
+        };
+    }
+    return ctx;
+}

package/dist/context/NavigationContext.d.ts

@@ -0,0 +1,46 @@
+/**
+ * NavigationContext
+ *
+ * Provides global navigation state for the unified sidebar and breadcrumb.
+ * Tracks whether the user is in "Home" context (workspace view) or "App"
+ * context (specific app), plus an optional record-detail title that record
+ * pages publish so the top-bar breadcrumb can show the human-readable title
+ * (e.g. "Acme Platform Upgrade") instead of the raw record ID.
+ *
+ * @module
+ */
+import { type ReactNode } from 'react';
+export type NavigationContextType = 'home' | 'app';
+interface NavigationContextValue {
+    /** Current navigation context (home or app) */
+    context: NavigationContextType;
+    /** Set the navigation context */
+    setContext: (context: NavigationContextType) => void;
+    /** Current app name when in app context */
+    currentAppName?: string;
+    /** Set the current app name */
+    setCurrentAppName: (appName?: string) => void;
+    /**
+     * Human-readable title of the currently displayed record (when on a record
+     * detail page). Published by RecordDetailView once data loads; consumed by
+     * AppHeader to replace the raw `#shortId` segment in the breadcrumb.
+     */
+    recordTitle?: string;
+    /** Update the current record title (or clear it when leaving a record page). */
+    setRecordTitle: (title?: string) => void;
+}
+interface NavigationProviderProps {
+    children: ReactNode;
+}
+export declare function NavigationProvider({ children }: NavigationProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access navigation context
+ */
+export declare function useNavigationContext(): NavigationContextValue;
+/**
+ * Helper hook for record pages: sets the record title on mount and clears it
+ * on unmount, so the breadcrumb only shows a record title while a record page
+ * is actually visible.
+ */
+export declare function useRecordBreadcrumbTitle(title: string | undefined): void;
+export {};

package/dist/context/NavigationContext.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * NavigationContext
+ *
+ * Provides global navigation state for the unified sidebar and breadcrumb.
+ * Tracks whether the user is in "Home" context (workspace view) or "App"
+ * context (specific app), plus an optional record-detail title that record
+ * pages publish so the top-bar breadcrumb can show the human-readable title
+ * (e.g. "Acme Platform Upgrade") instead of the raw record ID.
+ *
+ * @module
+ */
+import { createContext, useContext, useState, useMemo, useEffect } from 'react';
+const NavigationContext = createContext(undefined);
+export function NavigationProvider({ children }) {
+    const [context, setContext] = useState('home');
+    const [currentAppName, setCurrentAppName] = useState();
+    const [recordTitle, setRecordTitle] = useState();
+    const value = useMemo(() => ({
+        context,
+        setContext,
+        currentAppName,
+        setCurrentAppName,
+        recordTitle,
+        setRecordTitle,
+    }), [context, currentAppName, recordTitle]);
+    return (_jsx(NavigationContext.Provider, { value: value, children: children }));
+}
+/**
+ * Hook to access navigation context
+ */
+export function useNavigationContext() {
+    const context = useContext(NavigationContext);
+    if (!context) {
+        // Graceful fallback for consumers rendered outside <NavigationProvider>
+        // (common in lightweight unit tests). Production paths always wrap.
+        return {
+            context: 'app',
+            setContext: () => { },
+            currentAppName: undefined,
+            setCurrentAppName: () => { },
+            recordTitle: undefined,
+            setRecordTitle: () => { },
+        };
+    }
+    return context;
+}
+/**
+ * Helper hook for record pages: sets the record title on mount and clears it
+ * on unmount, so the breadcrumb only shows a record title while a record page
+ * is actually visible.
+ */
+export function useRecordBreadcrumbTitle(title) {
+    const { setRecordTitle } = useNavigationContext();
+    useEffect(() => {
+        setRecordTitle(title);
+        return () => setRecordTitle(undefined);
+    }, [title, setRecordTitle]);
+}

package/dist/context/index.d.ts

@@ -0,0 +1,3 @@
+export { NavigationProvider, useNavigationContext } from './NavigationContext';
+export { FavoritesProvider, useFavorites } from './FavoritesProvider';
+export type { FavoriteItem } from './FavoritesProvider';

package/dist/context/index.js

@@ -0,0 +1,2 @@
+export { NavigationProvider, useNavigationContext } from './NavigationContext';
+export { FavoritesProvider, useFavorites } from './FavoritesProvider';

package/dist/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { useFavorites, type FavoriteItem } from './useFavorites';
+export { useMetadataService } from './useMetadataService';
+export { useNavPins } from './useNavPins';
+export { useNavigationSync, NavigationSyncEffect, generateNavId, addNavigationItem, removeNavigationItems, renameNavigationItems, navigationEqual, type UseNavigationSyncReturn, } from './useNavigationSync';
+export { useObjectActions } from './useObjectActions';
+export { useRecentItems, type RecentItem } from './useRecentItems';
+export { useResponsiveSidebar } from './useResponsiveSidebar';

package/dist/hooks/index.js

@@ -0,0 +1,7 @@
+export { useFavorites } from './useFavorites';
+export { useMetadataService } from './useMetadataService';
+export { useNavPins } from './useNavPins';
+export { useNavigationSync, NavigationSyncEffect, generateNavId, addNavigationItem, removeNavigationItems, renameNavigationItems, navigationEqual, } from './useNavigationSync';
+export { useObjectActions } from './useObjectActions';
+export { useRecentItems } from './useRecentItems';
+export { useResponsiveSidebar } from './useResponsiveSidebar';

package/dist/hooks/useFavorites.d.ts

@@ -0,0 +1,13 @@
+/**
+ * useFavorites — re-export shim
+ *
+ * The favorites state has been migrated to a React Context so all consumers
+ * share a single state instance (fixes star toggle not updating HomePage).
+ *
+ * All existing imports of `useFavorites` and `FavoriteItem` from this path
+ * continue to work without any changes at the call sites.
+ *
+ * @see apps/console/src/context/FavoritesProvider.tsx
+ * @module
+ */
+export { useFavorites, type FavoriteItem } from '../context/FavoritesProvider';

package/dist/hooks/useFavorites.js

@@ -0,0 +1,13 @@
+/**
+ * useFavorites — re-export shim
+ *
+ * The favorites state has been migrated to a React Context so all consumers
+ * share a single state instance (fixes star toggle not updating HomePage).
+ *
+ * All existing imports of `useFavorites` and `FavoriteItem` from this path
+ * continue to work without any changes at the call sites.
+ *
+ * @see apps/console/src/context/FavoritesProvider.tsx
+ * @module
+ */
+export { useFavorites } from '../context/FavoritesProvider';

package/dist/hooks/useMetadataService.d.ts

@@ -0,0 +1,13 @@
+/**
+ * useMetadataService
+ *
+ * React hook that creates a memoised `MetadataService` instance from the
+ * current `ObjectStackAdapter` (via `useAdapter`).
+ *
+ * Returns `null` when the adapter is not yet available (e.g. while
+ * the connection is being established).
+ *
+ * @module hooks/useMetadataService
+ */
+import { MetadataService } from '../services/MetadataService';
+export declare function useMetadataService(): MetadataService | null;

package/dist/hooks/useMetadataService.js

@@ -0,0 +1,18 @@
+/**
+ * useMetadataService
+ *
+ * React hook that creates a memoised `MetadataService` instance from the
+ * current `ObjectStackAdapter` (via `useAdapter`).
+ *
+ * Returns `null` when the adapter is not yet available (e.g. while
+ * the connection is being established).
+ *
+ * @module hooks/useMetadataService
+ */
+import { useMemo } from 'react';
+import { useAdapter } from '../providers/AdapterProvider';
+import { MetadataService } from '../services/MetadataService';
+export function useMetadataService() {
+    const adapter = useAdapter();
+    return useMemo(() => (adapter ? new MetadataService(adapter) : null), [adapter]);
+}

package/dist/hooks/useNavPins.d.ts

@@ -0,0 +1,16 @@
+/**
+ * useNavPins
+ *
+ * Tracks user-pinned navigation items with localStorage persistence.
+ * Pinned items are shown at the top of the sidebar as a "Pinned" section.
+ * Works alongside the existing `useFavorites` hook (record-level favorites).
+ * @module
+ */
+import type { NavigationItem } from '@object-ui/types';
+export declare function useNavPins(): {
+    pinnedIds: string[];
+    togglePin: (itemId: string, pinned: boolean) => void;
+    isPinned: (itemId: string) => boolean;
+    applyPins: (items: NavigationItem[]) => NavigationItem[];
+    clearPins: () => void;
+};

package/dist/hooks/useNavPins.js

@@ -0,0 +1,72 @@
+/**
+ * useNavPins
+ *
+ * Tracks user-pinned navigation items with localStorage persistence.
+ * Pinned items are shown at the top of the sidebar as a "Pinned" section.
+ * Works alongside the existing `useFavorites` hook (record-level favorites).
+ * @module
+ */
+import { useState, useCallback, useEffect } from 'react';
+const STORAGE_KEY = 'objectui-nav-pins';
+const MAX_PINS = 20;
+function loadPins() {
+    try {
+        const raw = localStorage.getItem(STORAGE_KEY);
+        if (!raw)
+            return [];
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((id) => typeof id === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+function savePins(ids) {
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(ids));
+    }
+    catch {
+        // Storage full — silently ignore
+    }
+}
+export function useNavPins() {
+    const [pinnedIds, setPinnedIds] = useState(loadPins);
+    // Sync from storage on mount
+    useEffect(() => {
+        setPinnedIds(loadPins());
+    }, []);
+    const togglePin = useCallback((itemId, pinned) => {
+        setPinnedIds(prev => {
+            const filtered = prev.filter(id => id !== itemId);
+            const updated = pinned
+                ? [...filtered, itemId].slice(0, MAX_PINS)
+                : filtered;
+            savePins(updated);
+            return updated;
+        });
+    }, []);
+    const isPinned = useCallback((itemId) => pinnedIds.includes(itemId), [pinnedIds]);
+    /**
+     * Apply pinned state to a navigation item tree.
+     * Returns new items with `pinned` property set based on stored pin state.
+     */
+    const applyPins = useCallback((items) => {
+        return items.map(item => {
+            const pinned = pinnedIds.includes(item.id);
+            const children = item.children?.length
+                ? applyPins(item.children)
+                : item.children;
+            if (pinned !== (item.pinned ?? false) || children !== item.children) {
+                return { ...item, pinned, children };
+            }
+            return item;
+        });
+    }, [pinnedIds]);
+    const clearPins = useCallback(() => {
+        setPinnedIds([]);
+        savePins([]);
+    }, []);
+    return { pinnedIds, togglePin, isPinned, applyPins, clearPins };
+}