import { ReactNode } from 'react';
export interface PersonaSurfaceDefinition {
    /** Stable surface id, e.g. "farmer". Must not be "everything" (reserved). */
    id: string;
    /** Display label, e.g. "Farmer". */
    label: string;
    /** One-line description shown in pickers. */
    description?: string;
    /**
     * Managed role template keys this surface represents
     * (e.g. "product.healthybowl.farmer"). Used to match simulated roles,
     * whose templateKey is known; also serves as documentation of identity.
     */
    templateKeys?: string[];
    /**
     * Role display names this surface matches against the caller's
     * `myPermissions.roles` (the RBAC API exposes role NAMES to members, not
     * template keys). List every managed role name that should get this
     * surface, e.g. ["HealthyBowl Farmer"].
     */
    roleNames: string[];
    /** Landing path for this persona (used by shells for post-login redirect). */
    homePath?: string;
    /**
     * Nav item ids shown BY DEFAULT for this surface. Listing a parent/group id
     * shows the parent and all of its children; a child id can be listed alone
     * to show it under a soft-hidden parent. Every permitted item NOT covered
     * here is soft-hidden (collapsed behind "N more…", user-toggleable) —
     * never removed.
     */
    visibleItems: string[];
    /** Optional per-item label overrides (persona vocabulary), keyed by item id. */
    labelOverrides?: Record<string, string>;
}
/** Reserved surface id meaning "no curation — show everything permitted". */
export declare const EVERYTHING_SURFACE_ID = "everything";
export type NavItemOverrideState = 'shown' | 'hidden';
/**
 * A USER-CREATED view: same visibility semantics as a product-defined
 * surface, but owned by one user, named by them, and (in remote-persistence
 * mode) stored server-side so it follows them across devices. Custom views
 * have no role mapping — they are picked explicitly.
 */
export interface PersonaCustomView {
    id: string;
    name: string;
    visibleItems: string[];
    homePath: string | null;
}
export interface SimulatableRole {
    id: string;
    name: string;
    templateKey: string | null;
    priority: number;
    defaultPermissions: Array<{
        resourceType: string;
        level: 'ADMIN' | 'EDITOR' | 'VIEWER' | 'NONE';
    }>;
}
export interface SimulationState {
    roleId: string;
    roleName: string;
    templateKey: string | null;
    /**
     * Permission strings synthesized from the role's default permission levels
     * using the fleet default action matrix. A UI approximation for nav
     * preview — per-resource action overrides are not reflected.
     */
    permissionStrings: string[];
}
export interface PersonaSurfaceContextValue {
    /** All surfaces the product defines (excluding the built-in Everything). */
    surfaces: PersonaSurfaceDefinition[];
    /** The surface currently applied ("everything" when uncurated). */
    activeSurfaceId: string;
    /** Definition of the applied surface; null when Everything. */
    activeSurface: PersonaSurfaceDefinition | null;
    /** What the user's roles resolve to before any manual override. */
    resolvedSurfaceId: string;
    /** Surface ids the current user qualifies for (own roles), for the picker. */
    availableSurfaceIds: string[];
    /** Pick a surface manually; null clears the override (back to resolved). */
    setSurfaceId: (id: string | null) => void;
    /** Per-item user visibility overrides (sparse; wins over surface defaults). */
    overrides: Record<string, NavItemOverrideState>;
    setItemOverride: (itemId: string, state: NavItemOverrideState | null) => void;
    resetOverrides: () => void;
    /** Customize-menu dialog open state (rendered by ProductSideNav). */
    customizeOpen: boolean;
    setCustomizeOpen: (open: boolean) => void;
    /** Role simulation (admins / super admins only). */
    canSimulate: boolean;
    simulation: SimulationState | null;
    startSimulation: (role: SimulatableRole) => void;
    stopSimulation: () => void;
    simulatableRoles: SimulatableRole[];
    simulatableRolesLoading: boolean;
    /** Lazily fetch the workspace role catalog for the simulation picker. */
    loadSimulatableRoles: () => void;
    /** User-created custom views (server-persisted in remote mode). */
    customViews: PersonaCustomView[];
    /**
     * True when custom-view management is available: remote persistence is
     * enabled and the server preferences have loaded.
     */
    canManageViews: boolean;
    /** Create a view from an explicit visible-item set; activates it. */
    createCustomView: (name: string, visibleItems: string[], homePath?: string | null) => Promise<PersonaCustomView | null>;
    renameCustomView: (id: string, name: string) => Promise<boolean>;
    deleteCustomView: (id: string) => Promise<boolean>;
}
export declare function synthesizeSimulatedPermissionStrings(role: SimulatableRole): string[];
/**
 * Resolve which surface the user's role names map to. Surfaces are checked in
 * array order — list the most privileged surface first so a user holding
 * several product roles lands on the broader one.
 */
export declare function resolveSurfaceForRoles(surfaces: PersonaSurfaceDefinition[], roleNames: string[]): string;
export interface PersonaSurfaceProviderProps {
    children: ReactNode;
    /** The product's surface definitions, most privileged first. */
    surfaces: PersonaSurfaceDefinition[];
    /**
     * Stable product key used to namespace persisted preferences
     * (e.g. "healthybowl").
     */
    productKey: string;
    /**
     * Gateway used to fetch simulatable roles.
     * @default 'workspace'
     */
    gateway?: 'workspace' | 'global';
    /**
     * Where user choices (active view, per-view item overrides, custom views)
     * live. 'remote' stores them in the backend (wspace-workspace-svc
     * `nav-view` module) keyed by actor+workspace+product, so they follow the
     * user across devices; localStorage stays as a warm cache so the sidebar
     * renders the last-known state instantly while the server responds.
     * 'local' (default, for shells whose backend hasn't onboarded yet) keeps
     * everything device-local.
     */
    persistence?: 'local' | 'remote';
}
export declare function PersonaSurfaceProvider({ children, surfaces, productKey, gateway, persistence, }: PersonaSurfaceProviderProps): import("react/jsx-runtime").JSX.Element;
/** Access the persona surface context; throws outside the provider. */
export declare function usePersonaSurface(): PersonaSurfaceContextValue;
/**
 * Like `usePersonaSurface` but returns `null` outside the provider, so chrome
 * components degrade gracefully in shells that haven't adopted surfaces yet.
 */
export declare function useSafePersonaSurface(): PersonaSurfaceContextValue | null;
//# sourceMappingURL=PersonaSurfaceProvider.d.ts.map