@powerportalspro/react 5.0.0-beta.1

package/dist/index.d.cts

@@ -0,0 +1,2524 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { components, TableMetadata as TableMetadata$1, ViewMetadata, CurrentUserInfo, Transport, AuthClient, PowerPortalsProClient, LoginRequest, LoginResponse, SwitchIdentityResponse, PowerPortalsProError, TableRecord, RetrieveRecordsResponse, GridDataRequest, GridDataResponse, GridFilterBase, ChartAggregation, ColumnSort, ResolvedColumn, TableSecurityPermission, ChartData, OrganizationRequest } from '@powerportalspro/core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type EnvironmentFileSettings$2 = components['schemas']['EnvironmentFileSettings'];
+/**
+ * Client-side cache for table metadata. Mirrors Blazor's
+ * `ITableMetadataCache` interface (in `PowerPortalsPro.Common.Services`).
+ *
+ * The default implementation lives in-memory (Map) with in-flight-promise
+ * dedup so N parallel `getAsync` calls for the same table share one
+ * server round-trip. A localStorage layer can be stacked on top by
+ * supplying a custom implementation through
+ * {@link PowerPortalsProProviderProps.tableMetadataCache}.
+ *
+ * Why this exists: the inline-editable grid mounts one `<RecordContext>`
+ * per visible row when the user toggles edit mode on. Each RC would
+ * otherwise fire its own `retrieveTableMetadataAsync` round-trip —
+ * thundering-herd against the same endpoint that produces visibly
+ * staggered row rendering as each fetch's response lands. The cache
+ * collapses that to a single fetch shared across all consumers.
+ */
+interface TableMetadataCache {
+    /**
+     * Returns the cached metadata for `tableLogicalName`, fetching it from
+     * the server on a miss. Concurrent calls for the same table dedupe
+     * onto a single in-flight promise. Returns `null` only when the table
+     * itself doesn't exist on the server (404).
+     */
+    getAsync(tableLogicalName: string): Promise<TableMetadata$1 | null>;
+    /**
+     * Manually evicts an entry. Use when consumer code knows the server-
+     * side metadata has changed (rare — typical case is letting natural
+     * page refresh handle it).
+     */
+    invalidate(tableLogicalName: string): void;
+    /** Drops every cached entry. */
+    clear(): void;
+}
+/**
+ * Client-side cache for Dataverse view metadata. Same shape and
+ * rationale as {@link TableMetadataCache} — mirrors Blazor's
+ * `IViewMetadataCache` (in `PowerPortalsPro.Common.Services`).
+ *
+ * Keyed by view id (Dataverse GUID, hyphenated, no braces). The default
+ * implementation is in-memory with in-flight-promise dedup.
+ */
+interface ViewMetadataCache {
+    /**
+     * Returns the cached metadata for `viewId`, fetching it from the
+     * server on a miss. Concurrent calls dedupe onto one in-flight
+     * promise. Returns `null` only when the view doesn't exist (404).
+     */
+    getAsync(viewId: string): Promise<ViewMetadata | null>;
+    /** Manually evicts an entry. */
+    invalidate(viewId: string): void;
+    /** Drops every cached entry. */
+    clear(): void;
+}
+/**
+ * Client-side cache for the per-table list of available views (powers
+ * grid view-pickers and default-view resolution). Same in-memory +
+ * in-flight-promise-dedup shape as {@link TableMetadataCache}. Keyed by
+ * table logical name.
+ *
+ * Avoids the case where two grids on the same page targeting the same
+ * table each fetch the views list independently. Server-side caching
+ * already collapses these to one Dataverse call per server lifetime;
+ * the client cache collapses them to one HTTP call per browser session.
+ */
+interface ViewsForTableCache {
+    /**
+     * Returns the cached views list for `tableLogicalName`, fetching from
+     * the server on a miss. Returns an empty array (not `null`) when the
+     * table exists but has no views — distinguishes "no views" from "table
+     * doesn't exist" (the latter raises through the underlying client).
+     */
+    getAsync(tableLogicalName: string): Promise<readonly ViewMetadata[]>;
+    /** Manually evicts an entry. */
+    invalidate(tableLogicalName: string): void;
+    /** Drops every cached entry. */
+    clear(): void;
+}
+/**
+ * Singleton cache for the org-wide environment file settings (blocked
+ * extensions, max upload size). Unlike the keyed caches, there's only
+ * one `EnvironmentFileSettings` per environment — no key parameter.
+ *
+ * Avoids the case where multiple `<FileGrid>`s on the same page each
+ * fire their own `getEnvironmentFileSettingsAsync` request. The server
+ * already caches the response, but the client-side cache eliminates
+ * the duplicate HTTP round-trips entirely.
+ */
+interface EnvironmentFileSettingsCache {
+    /**
+     * Returns the cached settings, fetching from the server on a miss.
+     * Concurrent calls share a single in-flight promise. Returns `null`
+     * only when the server explicitly returns no settings (rare —
+     * typically the endpoint always returns a value).
+     */
+    getAsync(): Promise<EnvironmentFileSettings$2 | null>;
+    /**
+     * Drops the cached value. The next `getAsync` re-fetches from the
+     * server.
+     */
+    invalidate(): void;
+}
+
+/**
+ * Status values for the {@link AuthState} state machine.
+ *
+ * Hybrid shape — bare string-literal union as the type (clean narrowing) plus a
+ * const-object export for consumers who prefer refactor-safe constants. Both
+ * compare against the same runtime string, so `auth.status === 'loading'` and
+ * `auth.status === AuthStatus.Loading` are equivalent. Matches the
+ * auto-generated `LoginResult`-style pattern from `@powerportalspro/core`.
+ */
+declare const AuthStatus: {
+    readonly Loading: "loading";
+    readonly Anonymous: "anonymous";
+    readonly Authenticated: "authenticated";
+};
+type AuthStatus = (typeof AuthStatus)[keyof typeof AuthStatus];
+/**
+ * Discriminated state union exposed by {@link useAuth}. `loading` is the initial state
+ * during the first `/api/auth/me` call on mount; once that resolves, the state is
+ * either `anonymous` or `authenticated` for the rest of the app's lifetime (until
+ * `login()` / `logout()` actions transition it).
+ *
+ * The `authenticated` branch carries the {@link CurrentUserInfo} the server returned —
+ * the auto-generated DTO from `@powerportalspro/core`, no narrowing applied. Fields
+ * like `roles` arrive as `string[] | undefined` per the wire contract; consumers
+ * coalesce to `[]` at the read site if they want a non-null array.
+ */
+type AuthState = {
+    readonly status: 'loading';
+} | {
+    readonly status: 'anonymous';
+} | {
+    readonly status: 'authenticated';
+    readonly user: CurrentUserInfo;
+};
+interface PowerPortalsProContextValue {
+    /** The shared {@link Transport} both clients are constructed against. Exposed for advanced use. */
+    readonly transport: Transport;
+    /** {@link AuthClient} instance — same one returned by `usePowerPortalsPro().auth`. */
+    readonly auth: AuthClient;
+    /** {@link PowerPortalsProClient} instance — same one returned by `usePowerPortalsPro().ppp`. */
+    readonly ppp: PowerPortalsProClient;
+    /**
+     * Client-side cache for Dataverse table metadata. Reads dedupe
+     * concurrent fetches and persist resolved values for the lifetime of
+     * the `PowerPortalsProClient`. See {@link TableMetadataCache}.
+     */
+    readonly tableMetadataCache: TableMetadataCache;
+    /**
+     * Client-side cache for Dataverse view metadata. Same shape as
+     * {@link tableMetadataCache}, keyed by view id. See {@link ViewMetadataCache}.
+     */
+    readonly viewMetadataCache: ViewMetadataCache;
+    /**
+     * Client-side cache for the per-table views list (powers grid view-
+     * pickers). See {@link ViewsForTableCache}.
+     */
+    readonly viewsForTableCache: ViewsForTableCache;
+    /**
+     * Client-side cache for the singleton environment file settings
+     * (blocked extensions, max upload size). See
+     * {@link EnvironmentFileSettingsCache}.
+     */
+    readonly environmentFileSettingsCache: EnvironmentFileSettingsCache;
+    /** Current auth state. {@link useAuth} unpacks this directly. */
+    readonly authState: AuthState;
+    /** Refreshes the auth state by re-calling `/api/auth/me`. */
+    readonly refreshAuth: () => Promise<void>;
+    /** Submits credentials. On success the auth state transitions to `authenticated` automatically. */
+    readonly login: (request: LoginRequest) => Promise<LoginResponse>;
+    /** Clears the auth cookie and transitions the auth state to `anonymous`. */
+    readonly logout: () => Promise<void>;
+    /**
+     * Swaps the auth cookie for the user's alt-identity sibling (the
+     * contact↔systemuser pair stamped via `PortalClaimTypes.AltIdentity*`).
+     * On `SwitchIdentityResult.Switched` the in-memory auth state is refreshed
+     * from `/api/auth/me`; other outcomes leave it unchanged so the caller can
+     * surface a message to the user. The endpoint takes no parameters — the
+     * alt id is read from the cookie's claims server-side.
+     */
+    readonly switchIdentity: () => Promise<SwitchIdentityResponse>;
+}
+declare const PowerPortalsProContext: react.Context<PowerPortalsProContextValue | null>;
+
+interface PowerPortalsProProviderProps {
+    children: ReactNode;
+    /**
+     * Optional pre-constructed {@link Transport} for the AuthClient and PowerPortalsProClient
+     * to share. Pass one to set a non-default `baseUrl`, inject a custom `fetch`
+     * implementation for tests, etc. When omitted, a default transport is constructed —
+     * same-origin, browser fetch, cookie credentials included.
+     *
+     * The provider holds a stable reference to the transport for its lifetime — passing
+     * a new instance on every render is wasteful, so memoize it at the call site or
+     * construct it at module scope. Changes to this prop after first render are ignored.
+     */
+    transport?: Transport;
+    /**
+     * Single override JSON layered on top of the framework defaults. Use this
+     * when the consumer app has one additional strings file (e.g.
+     * `/localization/app.en.json`) with app-specific strings or English
+     * overrides. The framework defaults remain the base.
+     *
+     * Pass `localizationUrl={false}` to opt out of the auto-mounted localizer
+     * entirely (e.g. when adapting i18next via your own `<LocalizerProvider>`).
+     */
+    localizationUrl?: string | false;
+    /**
+     * Multiple override JSONs layered on top of the framework defaults, in
+     * order. Later URLs override earlier ones for matching keys. Use this when
+     * the consumer app has more than one strings file (e.g. one per page,
+     * one per feature module).
+     *
+     * Combined with `localizationUrl`, both are appended to the framework
+     * defaults — `localizationUrl` first, then `localizationUrls`.
+     */
+    localizationUrls?: readonly string[];
+    /**
+     * Baseline localization prefixes the auto-mounted
+     * `<DefaultLocalizerProvider>` should eagerly load alongside the
+     * default bundle. Forwards directly to that provider's `prefixes`
+     * prop — see its doc for the full semantics. Ignored when
+     * `localizationUrl={false}` (consumer is wiring their own
+     * localizer adapter).
+     *
+     * Typical use: declare baseline tables / views the entire app
+     * touches (header lookups, navigation chrome) so every
+     * `<LocalizationBoundary>` inherits them for free.
+     */
+    localizationPrefixes?: readonly string[];
+    /**
+     * Custom {@link TableMetadataCache} implementation. When omitted, the
+     * provider mounts an in-memory cache with in-flight-promise dedup.
+     * Override with a localStorage-backed implementation for cross-session
+     * persistence, or a mock for tests.
+     */
+    tableMetadataCache?: TableMetadataCache;
+    /**
+     * Custom {@link ViewMetadataCache} implementation. Same defaulting
+     * behavior as {@link tableMetadataCache}.
+     */
+    viewMetadataCache?: ViewMetadataCache;
+    /**
+     * Custom {@link ViewsForTableCache} implementation. Same defaulting
+     * behavior as {@link tableMetadataCache}.
+     */
+    viewsForTableCache?: ViewsForTableCache;
+    /**
+     * Custom {@link EnvironmentFileSettingsCache} implementation. Same
+     * defaulting behavior as {@link tableMetadataCache}.
+     */
+    environmentFileSettingsCache?: EnvironmentFileSettingsCache;
+}
+/**
+ * Top-level provider for `@powerportalspro/react`. Constructs an {@link AuthClient}
+ * and a {@link PowerPortalsProClient} (sharing one {@link Transport}) and manages the
+ * auth state machine — `loading` until the first `/api/auth/me` response, then
+ * `anonymous` or `authenticated` for the rest of the session.
+ *
+ * Wrap the app once near the root:
+ * ```tsx
+ * <PowerPortalsProProvider>
+ *   <App />
+ * </PowerPortalsProProvider>
+ * ```
+ *
+ * Hooks ({@link useAuth}, {@link usePowerPortalsPro}, {@link useRecord}, …) read from
+ * this provider's context.
+ */
+declare function PowerPortalsProProvider({ children, transport, localizationUrl, localizationUrls, localizationPrefixes, tableMetadataCache, viewMetadataCache, viewsForTableCache, environmentFileSettingsCache, }: PowerPortalsProProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Returns the {@link AuthClient}, {@link PowerPortalsProClient}, and underlying
+ * {@link Transport} from the nearest {@link PowerPortalsProProvider}. Use this when
+ * you need to call a method that doesn't have a dedicated hook (the higher-level
+ * `useAuth` / `useRecord` / `useFetchRecords` etc. cover the common cases).
+ *
+ * Throws if there's no provider above the calling component.
+ */
+declare function usePowerPortalsPro(): PowerPortalsProContextValue;
+
+/**
+ * Auth state + actions, surfaced as a discriminated union spread. Compare against
+ * the bare string literals or against {@link AuthStatus} constants — both are
+ * type-narrowed equivalently:
+ *
+ * ```tsx
+ * import { AuthStatus, useAuth } from '@powerportalspro/react';
+ *
+ * const auth = useAuth();
+ * if (auth.status === AuthStatus.Loading)       return <Spinner />;
+ * if (auth.status === AuthStatus.Anonymous)     return <SignInButton onClick={() => auth.login(...)} />;
+ * if (auth.status === AuthStatus.Authenticated) return <span>Hi, {auth.user.email}</span>;
+ * ```
+ *
+ * Behind the scenes the state lives on the {@link PowerPortalsProProvider} and
+ * propagates via context, so all `useAuth` calls in the tree see the same value
+ * and re-render on transitions.
+ *
+ * `login` mirrors {@link AuthClient.loginAsync} — same request/response shapes —
+ * but additionally re-fetches `/api/auth/me` on `Success` so the auth state
+ * transitions to `authenticated` without an extra round-trip from the consumer.
+ *
+ * `logout` mirrors {@link AuthClient.logoutAsync} and transitions the state to
+ * `anonymous` immediately on success.
+ */
+type UseAuthResult = AuthState & {
+    /** Re-runs `/api/auth/me` and updates the state. Call after side effects that may have changed the user (server-driven role updates, contact-record edits, etc.). */
+    refresh: () => Promise<void>;
+    /** Submits credentials. On `LoginResult.Success`, the state transitions to `authenticated`. */
+    login: (request: LoginRequest) => Promise<LoginResponse>;
+    /** Clears the auth cookie and transitions the state to `anonymous`. */
+    logout: () => Promise<void>;
+    /**
+     * Swaps the auth cookie for the user's alt-identity sibling. Returns the
+     * server's `SwitchIdentityResponse` so the caller can surface non-success
+     * outcomes (`NoAltIdentity`, `AltIdentityNotFound`, `NotAuthenticated`).
+     * On `Switched`, the in-memory auth state is refreshed automatically.
+     */
+    switchIdentity: () => Promise<SwitchIdentityResponse>;
+};
+declare function useAuth(): UseAuthResult;
+
+interface AuthorizedViewProps {
+    /**
+     * Children rendered when the principal is authenticated (and, if {@link roles}
+     * is supplied, holds at least one of the listed roles).
+     */
+    children: ReactNode;
+    /**
+     * Optional role gate. When supplied, the principal must hold AT LEAST ONE of
+     * the listed roles for the children to render — matching Blazor's
+     * `<AuthorizeView Roles="Admin,Manager">` (comma-separated = OR).
+     *
+     * Roles arrive on `auth.user.roles` from `/api/auth/me`. Per-role claims are
+     * only emitted for systemuser-backed principals — contacts don't have roles —
+     * so a role gate also implicitly limits the surface to staff users.
+     */
+    roles?: string | readonly string[];
+    /**
+     * Rendered when the principal is anonymous, the auth state is still loading,
+     * or the role check fails. Defaults to `null` (renders nothing).
+     */
+    fallback?: ReactNode;
+}
+/**
+ * Headless auth gate — React equivalent of Blazor's `<AuthorizeView>`. Renders
+ * {@link AuthorizedViewProps.children} only when the principal is authenticated;
+ * if {@link AuthorizedViewProps.roles} is supplied, the principal must hold at
+ * least one of the listed roles. Otherwise renders {@link AuthorizedViewProps.fallback}
+ * (default `null`).
+ *
+ * Loading is treated as "not yet authorized" — fallback renders during the
+ * initial `/api/auth/me` round-trip so consumers don't briefly flash the
+ * authorized UI before the cookie principal is hydrated.
+ *
+ * @example
+ * ```tsx
+ * <AuthorizedView>
+ *   <Link to="/Account/Manage">Manage account</Link>
+ * </AuthorizedView>
+ *
+ * <AuthorizedView roles="SystemAdmin">
+ *   <Link to="/SiteAdmin">Site admin</Link>
+ * </AuthorizedView>
+ *
+ * <AuthorizedView roles={["Admin", "Manager"]} fallback={<span>Restricted</span>}>
+ *   <SensitiveTools />
+ * </AuthorizedView>
+ * ```
+ */
+declare function AuthorizedView({ children, roles, fallback }: AuthorizedViewProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Status values for query hooks ({@link useRecord}, {@link useFetchRecords},
+ * {@link useTableMetadata}, …) and {@link RecordContext}.
+ *
+ * Hybrid shape — bare string-literal union as the type for clean narrowing in
+ * `if (q.status === 'success')`-style branching, plus a const-object export so
+ * consumers who prefer the refactor-safe form can write `q.status === QueryStatus.Success`.
+ * Both compare against the same runtime string. Matches the auto-generated
+ * `LoginResult`-style pattern from `@powerportalspro/core`.
+ */
+declare const QueryStatus: {
+    readonly Loading: "loading";
+    readonly Success: "success";
+    readonly Error: "error";
+};
+type QueryStatus = (typeof QueryStatus)[keyof typeof QueryStatus];
+/**
+ * Discriminated state surface returned by every query hook. `data` and `error` are
+ * always present as fields (so consumers can read them at any time) but only carry
+ * meaningful values when `status` matches. `refetch()` re-runs the query with the
+ * current dependency values, regardless of current state.
+ *
+ * Loosely mirrors react-query's API shape so consumers familiar with that library
+ * find the contract familiar — but with no caching, no dedup, no shared cache between
+ * components. Each hook call owns its own fetch lifecycle.
+ *
+ * **`status` vs. `isFetching`** — `status` describes the *outcome* (what's
+ * in `data`): `'loading'` = no data yet, `'success'` = data is populated,
+ * `'error'` = the most recent fetch threw. `isFetching` describes the
+ * *current request* — true whenever a network call is in flight,
+ * regardless of whether prior data is still being shown. With
+ * `keepPreviousData` enabled (see {@link useAsyncResource}), a deps-change
+ * triggered refetch keeps `status='success'` and the prior `data`
+ * populated while `isFetching` flips to true, so consumers can render a
+ * scrim overlay instead of wiping the UI.
+ */
+interface QueryResult<T> {
+    readonly status: QueryStatus;
+    readonly data: T | undefined;
+    readonly error: PowerPortalsProError | undefined;
+    /**
+     * True whenever a network request is currently in flight, including
+     * refetches triggered by deps changes or explicit `refetch()` calls.
+     * Independent of `status`: when `keepPreviousData` is enabled, the hook
+     * can be `status='success'` (prior data still on screen) AND
+     * `isFetching=true` (new request running) at the same time.
+     */
+    readonly isFetching: boolean;
+    /**
+     * Re-runs the query immediately, bypassing the deps comparison. Returns a
+     * promise that resolves when the next fetch settles successfully (or
+     * rejects if the fetch errors). Awaiting is optional — callers that just
+     * want to trigger a refresh can fire-and-forget.
+     *
+     * If the request is superseded by another deps change or another
+     * `refetch()` call before it settles, the returned promise resolves anyway
+     * (with the stale-but-final state of this `refetch` call's outcome) — that
+     * matches the "kick + observe" semantics callers want for a save-then-refresh
+     * flow, where the new data landing is what matters, not which trigger
+     * caused it.
+     */
+    readonly refetch: () => Promise<void>;
+}
+
+interface UseRecordOptions {
+    /** Column logical names to project. Omit for the table's full visible column set. */
+    columns?: readonly string[];
+    /** When false, the hook stays in the idle (success / data: undefined) state and skips fetching. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Fetches a single Dataverse record by table + id. Re-runs when `tableLogicalName`,
+ * `recordId`, or the joined column list changes; aborts in-flight requests on unmount.
+ *
+ * The `data` field is the raw `TableRecord` envelope (id, tableName, properties,
+ * permissions, formattedValues). Drill into `data.properties[columnName]` for typed
+ * column values; `data.formattedValues[columnName]` for the display string Dataverse
+ * supplied (already formatted in the user's locale).
+ *
+ * Permission enforcement happens server-side — an unauthorized read surfaces as a
+ * `UnauthorizedAccessError` in `error`, not a partial record.
+ */
+declare function useRecord(tableLogicalName: string, recordId: string, options?: UseRecordOptions): QueryResult<TableRecord>;
+
+interface UseFetchRecordsOptions {
+    /** When false, the hook stays in the idle (success / data: undefined) state and skips fetching. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Runs a FetchXML query. Re-runs when the `fetchXml` string changes; aborts
+ * in-flight requests on unmount. The query string is the FetchXML XML literal —
+ * the same format Dataverse natively accepts.
+ *
+ * `data.records` is the matched record list; `data.pagingCookie` and friends drive
+ * the standard FetchXML paging UX. Sorting, filtering, and link-entity joins are all
+ * encoded in the FetchXML — for grid scenarios a higher-level hook (in
+ * `@powerportalspro/react-fluent`'s eventual `MainGrid`) will manage the FetchXML
+ * lifecycle around view changes.
+ */
+declare function useFetchRecords(fetchXml: string, options?: UseFetchRecordsOptions): QueryResult<RetrieveRecordsResponse>;
+
+interface UseGridDataOptions {
+    /** When false, the hook stays in the idle (success / data: undefined) state and skips fetching. Defaults to true. */
+    enabled?: boolean;
+    /**
+     * When true, deps-change refetches (new page, new sort, new search text)
+     * hold the prior successful response on screen while the next request is
+     * in flight — `status` stays `'success'`, `data` stays populated, and
+     * `isFetching` flips to true so consumers can scrim the UI. Defaults to
+     * false, matching the strict state-machine behavior the other hooks use.
+     * Grids and other long-lived data surfaces will typically want this on.
+     */
+    keepPreviousData?: boolean;
+}
+/**
+ * Grid-data counterpart to {@link useFetchRecords}. Calls the server's
+ * `POST /api/grids/data` endpoint, which composes the final FetchXML via the
+ * shared `IFetchXmlQueryComposer` — applying search across the view's
+ * searchable columns, replacing sorts, AND-merging filters, etc. — so the
+ * search / sort / paging semantics match the Blazor grid exactly.
+ *
+ * Response includes both the row data (`tableRecords`, `pagingInfo`) and a
+ * server-resolved `columns` array — display names already localized, types
+ * for cell dispatch, sortability flags, widths. Grid consumers render
+ * straight from the response without a separate table-metadata round-trip.
+ *
+ * Re-runs whenever any field of the `request` changes (compared via JSON
+ * serialization — cheap, and the request is a small flat object). Aborts
+ * in-flight requests on unmount or when the request changes.
+ *
+ * Exactly one of `request.viewId` or `request.fetchXml` must be supplied;
+ * sending both or neither produces a 400 from the server.
+ */
+declare function useGridData(request: GridDataRequest, options?: UseGridDataOptions): QueryResult<GridDataResponse>;
+
+/**
+ * Soft cross-filter — a chart slice the user clicked but didn't drill
+ * through. Drives styling on consumers (chart: emphasize matching
+ * slice + dim others; grid: dim non-matching rows) WITHOUT changing
+ * the server-side query. Distinct from the hard filter
+ * ({@link ViewDataSourceProps.filter}) which IS sent to the server
+ * and re-fetches both row page and aggregations.
+ */
+interface ViewDataSourceHighlight {
+    /** Column the user clicked into — the slice's group-by column. */
+    readonly column: string;
+    /** Raw column value to match. Compared by strict equality. */
+    readonly value: unknown;
+}
+/**
+ * Options accepted by {@link useViewDataSource}. Split into two roles:
+ *
+ * - **Props** (forwarded straight into every request) — `viewId` /
+ *   `fetchXml` source, `staticFilters` (always-applied, never cleared
+ *   by mutators — the SubGrid relationship-filter case), `aggregations`
+ *   spec, behavior knobs (`enabled`, `keepPreviousData`, `debounceMs`).
+ * - **Initial state** (seeds once on mount, mutators take over) —
+ *   `initialFilter`, `initialSort`, `initialSearch`, `initialPage`,
+ *   `initialPageSize`, `initialHighlight`.
+ *
+ * The same datasource instance feeds a `<MainGrid>` and a
+ * `<DataverseChart>` (or two of either) — they all read the same row
+ * page + aggregations, so filter changes from any view land
+ * everywhere in one round-trip.
+ */
+interface UseViewDataSourceOptions {
+    /**
+     * Stored Dataverse view to query. Mutually exclusive with
+     * {@link fetchXml}. Reading the view's columns drives the
+     * search-column-type dispatch.
+     */
+    viewId?: string;
+    /**
+     * Caller-supplied FetchXML to query. Mutually exclusive with
+     * {@link viewId}. Useful for custom views.
+     */
+    fetchXml?: string;
+    /**
+     * Filters that the datasource never mutates — always sent verbatim
+     * with every request. The primary use case is `<SubGrid>` passing a
+     * `RelationshipFilter` to scope rows to a parent record; the
+     * datasource's user-driven {@link ViewDataSource.filter} state
+     * layers on top.
+     */
+    staticFilters?: readonly GridFilterBase[];
+    /**
+     * Optional aggregations to compute alongside the row page. Each
+     * entry becomes one entry in `GridDataRequest.Aggregations`; the
+     * server returns one `ChartData` per entry in
+     * {@link ViewDataSource.aggregationResults}, same order.
+     * <c>undefined</c> / empty → no chart pass; the response's
+     * `aggregations` slot is `null`. Treated as a prop (changes
+     * re-fetch) — if you need it to be mutable state inside the
+     * datasource, lift it to the consumer.
+     */
+    aggregations?: readonly ChartAggregation[];
+    /** Seed for {@link ViewDataSource.filter}. Defaults to empty. */
+    initialFilter?: readonly GridFilterBase[];
+    /** Seed for {@link ViewDataSource.sort}. Defaults to empty. */
+    initialSort?: readonly ColumnSort[];
+    /** Seed for {@link ViewDataSource.search}. Defaults to empty string. */
+    initialSearch?: string;
+    /** Seed for {@link ViewDataSource.page}. Defaults to 1. */
+    initialPage?: number;
+    /** Seed for {@link ViewDataSource.pageSize}. Defaults to 50. */
+    initialPageSize?: number;
+    /** Seed for {@link ViewDataSource.highlight}. Defaults to undefined. */
+    initialHighlight?: ViewDataSourceHighlight;
+    /**
+     * Debounce window in ms for the actual server request. State setter
+     * calls land synchronously (consumers reading `ds.search` see the
+     * latest typed value), but the network fetch fires once the
+     * debounce settles. Defaults to 300ms; pass 0 to disable.
+     */
+    debounceMs?: number;
+    /** When false, no fetch fires. Defaults to true. */
+    enabled?: boolean;
+    /**
+     * Keep the prior successful response on screen during deps-change
+     * refetches. Defaults to true — grids and charts typically want
+     * scrim-during-refetch over wiping the UI.
+     */
+    keepPreviousData?: boolean;
+}
+/**
+ * The reactive view of one query, shared by every consumer (grid,
+ * chart, side-panel, etc.) wired to the same {@link useViewDataSource}
+ * call. All consumers see the same row page + aggregations because
+ * the server returns them in a single response (atomically consistent
+ * — no race where the chart shows aggregations for an old filter
+ * while the grid shows rows for the new one).
+ *
+ * Reads (`filter` / `sort` / `search` / `rows` / `aggregationResults`)
+ * are snapshots at the time the hook ran. Mutators
+ * (`setFilter` / `setSearch` / `setHighlight` / etc.) trigger
+ * re-renders of the hook owner, which propagates to all consumers.
+ *
+ * Stable identity per snapshot — the returned object only changes
+ * reference when one of its fields actually changes. Safe to pass
+ * through `React.memo`'d component trees.
+ */
+interface ViewDataSource {
+    /**
+     * User-driven filter applied on top of {@link UseViewDataSourceOptions.staticFilters}.
+     * Always shipped as an AND-merge with the view's base filter.
+     */
+    readonly filter: readonly GridFilterBase[];
+    readonly sort: readonly ColumnSort[];
+    readonly search: string;
+    readonly page: number;
+    readonly pageSize: number;
+    /**
+     * Soft cross-filter for chart slice clicks — drives client-side
+     * styling on consumers (chart slice emphasis, grid row dimming)
+     * without changing the server query. Set to `undefined` to clear.
+     * Distinct from {@link filter}, which IS a hard filter.
+     */
+    readonly highlight: ViewDataSourceHighlight | undefined;
+    readonly aggregations: readonly ChartAggregation[];
+    readonly status: QueryStatus;
+    readonly rows: readonly TableRecord[];
+    readonly totalCount: number | string | null | undefined;
+    readonly columns: readonly ResolvedColumn[];
+    /**
+     * Current user's combined table-level `TableSecurityPermission` mask for
+     * the view's table — comes from the server response's
+     * `GridDataResponse.tablePermissions`. Mirrors the per-row
+     * permissions but at table scope, so toolbar buttons (`<MainGrid>`'s
+     * New / Delete and consumer-built equivalents) can gate off one
+     * authoritative value instead of sampling row[0] as a proxy.
+     * `undefined` until the first response lands.
+     */
+    readonly tablePermissions: TableSecurityPermission | undefined;
+    /**
+     * One {@link ChartData} per requested aggregation, in request order.
+     * Empty when no aggregations were requested OR when the response
+     * hasn't landed yet — consumers can render an empty / spinner state
+     * uniformly.
+     */
+    readonly aggregationResults: readonly ChartData[];
+    readonly error: PowerPortalsProError | undefined;
+    /** True whenever a fetch is in flight (including debounced refetches). */
+    readonly isFetching: boolean;
+    /**
+     * True only when the in-flight request actually carries the
+     * `aggregations` spec — i.e., when the chart's data is about to
+     * change. The skip-on-sort optimization above means that a column-
+     * header click on a sibling grid fires a row-page-only refetch the
+     * server processes without re-running aggregations, and this flag
+     * stays false through that. Chart consumers ({@link DataverseChart})
+     * gate their loading overlay on this so a sort-only refetch doesn't
+     * flash a spinner over an unchanged chart.
+     *
+     * Always false when {@link aggregations} is empty (no chart data
+     * being requested at all).
+     */
+    readonly isFetchingAggregations: boolean;
+    setFilter(filter: readonly GridFilterBase[]): void;
+    setSort(sort: readonly ColumnSort[]): void;
+    setSearch(search: string): void;
+    setPage(page: number): void;
+    setPageSize(pageSize: number): void;
+    setHighlight(highlight: ViewDataSourceHighlight | undefined): void;
+    /** Re-fires the current request immediately (skipping the debounce). */
+    refresh(): Promise<void>;
+}
+/**
+ * Shared {@link GridDataRequest} + chart-spec state for grid+chart
+ * scenarios. Hosts the filter / sort / search / page / aggregations
+ * once for any combination of `<MainGrid dataSource={ds}>` and
+ * `<DataverseChart dataSource={ds}>` consumers — one server request
+ * keeps the row page and the chart aggregations atomically consistent.
+ *
+ * Standalone usage (no chart) still works: omit the `aggregations`
+ * option and the datasource is just a hoisted-state grid hook.
+ *
+ * **Typical usage:**
+ *
+ * ```tsx
+ * function OpportunitiesPage() {
+ *   const ds = useViewDataSource({
+ *     viewId: openOpportunitiesViewId,
+ *     aggregations: [
+ *       { groupBy: { column: 'stepname' },
+ *         aggregateColumn: 'estimatedvalue',
+ *         aggregate: AggregateType.Sum },
+ *     ],
+ *   });
+ *   return (
+ *     <>
+ *       <DataverseChart dataSource={ds} type="bar" />
+ *       <MainGrid dataSource={ds} />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useViewDataSource(options: UseViewDataSourceOptions): ViewDataSource;
+
+interface UseTableMetadataOptions {
+    enabled?: boolean;
+}
+/**
+ * Fetches the column + relationship metadata for one Dataverse table.
+ * Routed through the {@link TableMetadataCache} on the provider — first
+ * call kicks off a server round-trip, concurrent calls dedupe onto the
+ * same in-flight promise, and resolved values are reused for the
+ * lifetime of the `PowerPortalsProClient`. Critical for the inline-
+ * editable grid, where N visible rows each mount their own
+ * `<RecordContext>` and would otherwise thunder N parallel
+ * `retrieveTableMetadataAsync` requests at toggle time.
+ *
+ * Coerces the cache's `null` "table not found" return to `undefined` in
+ * the query result so downstream consumers can treat metadata absence
+ * uniformly via `data == null`.
+ */
+declare function useTableMetadata(tableLogicalName: string, options?: UseTableMetadataOptions): QueryResult<TableMetadata$1>;
+
+interface UseTablePermissionsOptions {
+    enabled?: boolean;
+}
+/**
+ * Fetches the current user's combined table-level `TableSecurityPermission`
+ * mask for one Dataverse table. Mirrors the server-side
+ * `ITablePermissionCache.GetPermissionForUserAsync` lookup the Blazor
+ * grid buttons already use directly via DI — exposed here so React
+ * consumers can drive the same "Can the user create / delete on this
+ * table?" gates without firing a grid query.
+ *
+ * When a `<MainGrid>` / `<SubGrid>` is on the page the grid response
+ * already carries the same value as `GridDataResponse.tablePermissions`
+ * and toolbar buttons read it from there; reach for this hook when
+ * you're rendering UI outside a grid (a custom toolbar, conditional
+ * navigation, a "permission required" tooltip) and don't want to fire
+ * a grid query just to read the permission bits.
+ *
+ * Returns `data: TableSecurityPermission` once the fetch resolves. The
+ * caller compares via bit math, e.g.
+ * `(data & TableSecurityPermission.Create) === TableSecurityPermission.Create`.
+ *
+ * Empty `tableLogicalName` returns `data: TableSecurityPermission.None` (0)
+ * without firing a server round-trip — matches the server-side cache
+ * which returns `None` for null/empty table names.
+ */
+declare function useTablePermissions(tableLogicalName: string, options?: UseTablePermissionsOptions): QueryResult<TableSecurityPermission>;
+
+interface UseViewMetadataOptions {
+    enabled?: boolean;
+}
+/**
+ * Fetches metadata for one Dataverse view by its id (a GUID string).
+ * Routed through the {@link ViewMetadataCache} on the provider — first
+ * call hits the server, concurrent calls dedupe, resolved values are
+ * reused for the lifetime of the `PowerPortalsProClient`. Use
+ * {@link useViewsForTable} when you want every view for a table instead.
+ */
+declare function useViewMetadata(viewId: string, options?: UseViewMetadataOptions): QueryResult<ViewMetadata>;
+
+interface UseViewsForTableOptions {
+    enabled?: boolean;
+}
+/**
+ * Lists every view for a given table. Drives view-pickers and default-view
+ * resolution. Routed through {@link ViewsForTableCache} so two grids on
+ * the same page targeting the same table share one fetch.
+ */
+declare function useViewsForTable(tableLogicalName: string, options?: UseViewsForTableOptions): QueryResult<readonly ViewMetadata[]>;
+
+type EnvironmentFileSettings$1 = components['schemas']['EnvironmentFileSettings'];
+interface UseEnvironmentFileSettingsOptions {
+    enabled?: boolean;
+}
+/**
+ * Fetches the environment-wide file upload settings (blocked extension
+ * list, organization-level max upload size). Mirrors the Blazor
+ * <c>IPowerPortalsProService.GetEnvironmentFileSettingsAsync</c> call.
+ *
+ * Routed through {@link EnvironmentFileSettingsCache} on the provider —
+ * concurrent callers (e.g. multiple `<FileGrid>`s on the same page)
+ * share a single fetch, and the resolved value is reused across re-
+ * mounts for the lifetime of the `PowerPortalsProClient`. The cap
+ * reported here is the org-wide ceiling — the effective per-upload cap
+ * also has to account for per-column <c>maxSizeInKB</c> from
+ * {@link useTableMetadata}.
+ */
+declare function useEnvironmentFileSettings(options?: UseEnvironmentFileSettingsOptions): QueryResult<EnvironmentFileSettings$1>;
+
+interface UseSupportedLocalesOptions {
+    /**
+     * Gates the fetch. Defaults to `true` — the manifest is tiny (a
+     * handful of locale codes) and effectively free to fetch. Set
+     * `false` only when the consumer wants to suppress the call until
+     * some later condition (e.g. only fetch after auth resolves).
+     */
+    enabled?: boolean;
+}
+/**
+ * Returns the framework's configured supported UI locales. Reads from
+ * the {@link LocalizationManifestContext} populated by
+ * `DefaultLocalizerProvider`'s tier-1 manifest fetch — so call sites
+ * (typically `<LanguageDropdown>`) reuse the already-loaded data
+ * instead of issuing their own `/localizations/version` round-trip
+ * every time the hook mounts. The previous implementation re-fetched
+ * on each mount, which surfaced as one extra `/localizations/version`
+ * request on every page navigation in apps where the dropdown sits
+ * inside route-level chrome.
+ *
+ * Fallback path: when no `DefaultLocalizerProvider` is mounted (rare —
+ * consumers who wired their own i18next setup via
+ * `localizationUrl={false}`), the hook still issues its own fetch so
+ * the API works in isolation. The fallback uses the same
+ * `useAsyncResource` shape it always did, so the {@link QueryResult}
+ * surface is unchanged.
+ *
+ * The Blazor side gets this server-side via
+ * `IOptions<RequestLocalizationOptions>.SupportedUICultures`; in
+ * React the same configuration is exposed through the localization
+ * manifest endpoint at `/localizations/version`. Order matches the
+ * server's configured preference, default culture first.
+ */
+declare function useSupportedLocales(options?: UseSupportedLocalesOptions): QueryResult<readonly string[]>;
+
+/**
+ * Reads the value of a URL query-string parameter and re-renders when
+ * it changes (via browser back / forward, programmatic
+ * `history.pushState` / `replaceState`, or hash-only navigation).
+ * Router-agnostic — uses the platform `URLSearchParams` API directly
+ * so consumers don't have to pull in a specific router's hook.
+ *
+ * Returns `null` when the parameter is absent. SSR-safe — returns
+ * `null` when `window` is undefined.
+ *
+ * **Detecting in-app navigation:** `popstate` covers back / forward
+ * but the History API has no built-in event for `pushState` /
+ * `replaceState` calls. We patch both at module load to dispatch a
+ * synthetic `pushstate` / `replacestate` event, so consumers using
+ * any router (react-router, TanStack Router, Next.js, hand-rolled)
+ * get correct re-renders without taking a router dependency.
+ *
+ * Multiple components subscribing to the same parameter all re-read
+ * synchronously — each call sites runs its own `URLSearchParams`
+ * parse, which is cheap.
+ */
+declare function useQueryParam(name: string): string | null;
+
+type EnvironmentFileSettings = components['schemas']['EnvironmentFileSettings'];
+/**
+ * Default in-memory implementation of {@link TableMetadataCache}. Wraps
+ * a `PowerPortalsProClient.retrieveTableMetadataAsync` call with Map-based
+ * dedup. One instance per `PowerPortalsProClient` — the
+ * `PowerPortalsProProvider` constructs it.
+ */
+declare class InMemoryTableMetadataCache implements TableMetadataCache {
+    private readonly cache;
+    constructor(ppp: PowerPortalsProClient);
+    getAsync(tableLogicalName: string): Promise<TableMetadata$1 | null>;
+    invalidate(tableLogicalName: string): void;
+    clear(): void;
+}
+/**
+ * Default in-memory implementation of {@link ViewMetadataCache}. Same
+ * shape as {@link InMemoryTableMetadataCache}, keyed by view id.
+ */
+declare class InMemoryViewMetadataCache implements ViewMetadataCache {
+    private readonly cache;
+    constructor(ppp: PowerPortalsProClient);
+    getAsync(viewId: string): Promise<ViewMetadata | null>;
+    invalidate(viewId: string): void;
+    clear(): void;
+}
+/**
+ * Default in-memory implementation of {@link EnvironmentFileSettingsCache}.
+ * Singleton-shaped: no key, just one stored value + one in-flight promise.
+ *
+ * Implemented as a thin wrapper around the keyed {@link InMemoryCache}
+ * with a fixed sentinel key, so the dedup / fetch / error-eviction
+ * behaviors stay identical to the metadata caches without re-implementing
+ * any of that logic.
+ */
+declare class InMemoryEnvironmentFileSettingsCache implements EnvironmentFileSettingsCache {
+    private static readonly KEY;
+    private readonly cache;
+    constructor(ppp: PowerPortalsProClient);
+    getAsync(): Promise<EnvironmentFileSettings | null>;
+    invalidate(): void;
+}
+/**
+ * Default in-memory implementation of {@link ViewsForTableCache}. Wraps
+ * the per-table views-list endpoint with the same in-memory + in-flight
+ * dedup machinery the metadata caches use. Coerces a `null` fetch result
+ * (table not found / 404) to an empty list so consumers can treat the
+ * absence uniformly without branching on null.
+ */
+declare class InMemoryViewsForTableCache implements ViewsForTableCache {
+    private readonly cache;
+    constructor(ppp: PowerPortalsProClient);
+    getAsync(tableLogicalName: string): Promise<readonly ViewMetadata[]>;
+    invalidate(tableLogicalName: string): void;
+    clear(): void;
+}
+
+/**
+ * Per-descendant registration the {@link MainContext} keeps for save/refresh
+ * coordination + dirty aggregation. Each child component (typically a
+ * {@link RecordContext}, a `MainGrid`/`SubGrid`, or a many-to-many editor)
+ * calls {@link MainContextValue.registerDescendant} on mount and the returned
+ * unregister function on unmount.
+ *
+ * The parent uses the registry to orchestrate save / refresh / validate /
+ * aggregate `IsDirty`. Save is transactional: the parent collects
+ * {@link getRequests} across every descendant and ships them in a single
+ * `executeMultiple` round-trip.
+ *
+ * `isDirty` is a **getter** (`() => boolean`) — the parent calls it every
+ * time it recomputes the aggregate. Descendants should back it with a
+ * ref so it reads the latest value without re-registering. When the
+ * value flips, the descendant calls
+ * {@link MainContextValue.notifyDescendantDirtyChanged} to prompt the
+ * parent to re-read; this is materially cheaper than tearing down and
+ * re-creating the registration on every transition, which used to
+ * cascade re-renders through every {@link MainContext} consumer and
+ * dropped focus on the first keystroke in inline-edit cells.
+ */
+interface MainContextDescendant {
+    /**
+     * Returns all pending Dataverse operations for this descendant subtree.
+     * Returns an empty array when nothing is dirty. The parent collects these
+     * across every descendant and ships them in one transactional
+     * `executeMultiple` batch. Descendants that themselves contain nested
+     * descendants (e.g. a {@link RecordContext} hosting a `SubGrid`) should
+     * include the nested requests in the returned array so the entire subtree
+     * lands in a single batch.
+     */
+    readonly getRequests: () => OrganizationRequest[];
+    /**
+     * Returns `true` when the descendant subtree is in a state suitable for
+     * save. The parent calls this before collecting {@link getRequests};
+     * returning `false` aborts the save without firing any server-side
+     * operations.
+     *
+     * For descendants whose validation lives in a parallel system (e.g.
+     * {@link RecordContext} which routes per-column validation through
+     * `ValidationContext`), this can simply return `true` and let the
+     * dedicated validation surface drive the abort decision separately.
+     */
+    readonly validate: () => boolean | Promise<boolean>;
+    /** Reloads this descendant subtree from the server. */
+    readonly refresh: () => Promise<void>;
+    /**
+     * Discards every pending edit in this descendant subtree, reverting back
+     * to the loaded baseline WITHOUT re-fetching from the server. The "Cancel"
+     * / "Discard" primitive.
+     *
+     * Implementations should clear their own pending queue (`pendingChanges`
+     * for `RecordContext`, the queued row updates / creates / associates /
+     * disassociates for `MainGrid`, the pending adds / removes for
+     * `<ManyToManyLookupEdit>`, etc.) AND cascade to any nested descendants
+     * so the entire subtree is clean afterward.
+     */
+    readonly resetState: () => void;
+    /**
+     * Getter the parent calls when recomputing aggregate dirty state.
+     * Back it with a ref so the latest value is visible without
+     * re-registering; call
+     * {@link MainContextValue.notifyDescendantDirtyChanged} whenever the
+     * underlying value transitions so the parent knows to re-read.
+     */
+    readonly isDirty: () => boolean;
+}
+interface MainContextValue {
+    /**
+     * Transactionally saves the entire descendant subtree:
+     *
+     * 1. Calls {@link MainContextProps.onBeforeSave} (if wired). Throwing
+     *    aborts the save before any server call.
+     * 2. Runs {@link validate} across descendants; returns early without
+     *    saving when any descendant reports invalid.
+     * 3. Collects {@link MainContextDescendant.getRequests} from every
+     *    registered descendant.
+     * 4. If non-empty, ships the combined array in one
+     *    `executeMultipleAsync` round-trip so the operations land
+     *    transactionally on the server.
+     * 5. Calls {@link refreshAll} so the local state picks up server-applied
+     *    side-effects (computed columns, plugin defaults, the modifiedon
+     *    timestamp, etc.).
+     *
+     * Throws on the first server-side failure; later steps are skipped.
+     */
+    readonly saveAll: () => Promise<void>;
+    /** Refreshes every registered descendant. */
+    readonly refreshAll: () => Promise<void>;
+    /**
+     * Discards every pending edit in every registered descendant — the
+     * "Cancel" / "Discard" primitive that returns the entire subtree to its
+     * loaded baseline WITHOUT re-fetching from the server.
+     *
+     * Synchronous: descendants clear their local state in their own
+     * `setState` calls. Doesn't itself await anything.
+     */
+    readonly resetState: () => void;
+    /**
+     * Runs {@link MainContextDescendant.validate} across every registered
+     * descendant and returns `false` if any of them invalidates. Awaitable
+     * so descendants can perform async validation (e.g. async column
+     * validators routed through `ValidationContext.validateAll`).
+     */
+    readonly validate: () => Promise<boolean>;
+    /**
+     * Aggregates every pending Dataverse operation across the descendant
+     * subtree without firing them. Returns an empty array when nothing is
+     * dirty. Useful for previewing the payload {@link saveAll} would ship
+     * (audit log, dry-run UI, custom transactional flow that wants to
+     * append extra requests before calling
+     * `IPowerPortalsPro.executeMultipleAsync` directly).
+     *
+     * Mirrors Blazor's public `MainContext.GetRequests()` — same walk over
+     * registered grids / child contexts / M2M editors, same shape.
+     * Consumers that just want to save should call {@link saveAll}; this
+     * is the escape hatch for the rarer dry-run / merge-with-extras case.
+     */
+    readonly getRequests: () => OrganizationRequest[];
+    /**
+     * Adds `descendant` to the registry and returns an unregister function. Each
+     * descendant should call this once on mount and call the returned function
+     * on unmount, typically inside a single `useEffect` whose deps DON'T include
+     * the descendant's local `isDirty` — instead, signal dirty transitions via
+     * {@link notifyDescendantDirtyChanged}. The descendant's
+     * {@link MainContextDescendant.isDirty} getter is what the parent reads.
+     */
+    readonly registerDescendant: (descendant: MainContextDescendant) => () => void;
+    /**
+     * Called by a descendant when its
+     * {@link MainContextDescendant.isDirty} return value transitions.
+     * Prompts the parent to recompute its aggregate without forcing the
+     * descendant to unregister + re-register itself. The recommended
+     * idiom is a `useEffect` keyed on the local `isDirty` value.
+     */
+    readonly notifyDescendantDirtyChanged: () => void;
+    /**
+     * Aggregated dirty state — `true` if any registered descendant currently
+     * reports dirty. Flips reactively as descendants register/unregister/notify;
+     * consumers subscribed via {@link useMainContext} re-render on transitions.
+     */
+    readonly isDirty: boolean;
+    /**
+     * Resolved value of {@link MainContextProps.warnOnUnsavedChanges} for this
+     * context — `true` means the auto unsaved-changes warning is active; `false`
+     * means it's suppressed. Children read this to inherit the effective value
+     * when their own prop is omitted.
+     */
+    readonly warnOnUnsavedChanges: boolean;
+    /**
+     * Resolved value of {@link MainContextProps.forceSuccessfulValidationBeforeSave}.
+     * When `true` (the default), save flows in this subtree gate on
+     * validation passing — `SaveContextButton`, the dialog buttons inside
+     * `<OpenRecordGridButton>` / `<NewRecordGridButton>`, and
+     * {@link saveAll} all abort when any registered column validator reports
+     * an error. When `false`, those gates are bypassed and the save proceeds
+     * regardless. The server's own column validation (Dataverse required-on-
+     * update / type checks) still applies.
+     *
+     * Children read this to inherit the effective value when their own prop
+     * is omitted. Per-button overrides (e.g. on `<OpenRecordGridButton>`)
+     * take precedence over the cascaded value for the scope of that button.
+     */
+    readonly forceSuccessfulValidationBeforeSave: boolean;
+}
+interface MainContextProps {
+    children: ReactNode;
+    /**
+     * Optional pre-save hook. Throw (or return a rejected promise) to cancel
+     * the save — subsequent descendants are not saved.
+     */
+    onBeforeSave?: () => void | Promise<void>;
+    /**
+     * Auto-register a browser `beforeunload` warning when this context (or any
+     * descendant) is dirty.
+     *
+     * Resolution rules:
+     * - `true` / `false` — explicit override at this level.
+     * - `undefined` (default) — inherit from the parent
+     *   {@link MainContext} / {@link RecordContext}, falling back to `true` at
+     *   the root. Set `false` on the outer context of e.g. a demo site to
+     *   suppress the prompt across the whole subtree without touching every
+     *   nested context.
+     *
+     * Only the **top-most** MainContext / RecordContext on the page actually
+     * registers the listener — when contexts nest, the inner ones skip
+     * registration to avoid duplicate `beforeunload` handlers (the browser would
+     * still only prompt once, but the duplicates are wasteful). Soft navigation
+     * (e.g. `react-router` `<Link>` clicks) is NOT covered — that's
+     * router-specific; pair with the router's blocker hook plus
+     * {@link useWarnAboutUnsavedChanges}.
+     */
+    warnOnUnsavedChanges?: boolean;
+    /**
+     * When `true` (default), descendants' save flows abort if any registered
+     * column validator reports an error — covers `<SaveContextButton>`, the
+     * dialog buttons on `<OpenRecordGridButton>` / `<NewRecordGridButton>`,
+     * and {@link MainContextValue.saveAll}'s pre-flight. When `false`, those
+     * gates are bypassed and the save proceeds regardless. Useful for draft-
+     * style "save what you have" flows or when the consumer wants to defer
+     * validation to a downstream review step.
+     *
+     * Resolution rules (same as {@link warnOnUnsavedChanges}):
+     * - `true` / `false` — explicit override at this level.
+     * - `undefined` (default) — inherit from the parent
+     *   {@link MainContext} / {@link RecordContext}, falling back to `true`
+     *   at the root.
+     */
+    forceSuccessfulValidationBeforeSave?: boolean;
+}
+/**
+ * A context root that coordinates save and refresh across descendant components
+ * ({@link RecordContext}, future SubGrid / many-to-many editors). Headless:
+ * provides state and orchestration via React context, no rendering of its own
+ * beyond `children`.
+ *
+ * Nesting is supported — a child MainContext doesn't replace its parent's
+ * registry; it's just a separate root for its own subtree. Descendants always
+ * register with their nearest ancestor.
+ *
+ * Deferred surface (and how to layer it on later):
+ * - **Dirty tracking.** Blazor's MainContext aggregates `isDirty` across children
+ *   via `EditContext`. React doesn't have a built-in form layer; consumers bring
+ *   their own (react-hook-form, formik, vanilla state). When the dirty story
+ *   solidifies, an `isDirty: () => boolean` getter on `MainContextDescendant`
+ *   plus an aggregate getter on `MainContextValue` is the natural extension.
+ * - **Unsaved-changes warning** dialog on navigation. Driven by dirty tracking.
+ * - **Validation orchestration**. Same — needs the form layer.
+ * - **Persistent state across server↔WASM**. N/A in pure React.
+ */
+declare function MainContext({ children, onBeforeSave, warnOnUnsavedChanges, forceSuccessfulValidationBeforeSave, }: MainContextProps): react_jsx_runtime.JSX.Element;
+/**
+ * Returns the nearest ancestor {@link MainContext} value, or `null` if there is
+ * none. Components like {@link RecordContext} use this to optionally register
+ * themselves for save/refresh coordination — `null` is the standalone case where
+ * the component manages its own save without a coordinator.
+ */
+declare function useMainContext(): MainContextValue | null;
+/**
+ * Provides an existing {@link MainContextValue} to a subtree. Used by
+ * {@link RecordContext} to expose itself as a `MainContext` for nested
+ * descendants (mirroring Blazor's `RecordContext : MainContext` inheritance) —
+ * keeps the raw `MainContextContext` internal while still letting framework
+ * components compose multiple `MainContext` levels.
+ *
+ * Not generally needed by application code — use `<MainContext>` instead, which
+ * builds the value internally.
+ */
+declare function MainContextProvider({ value, children, }: {
+    value: MainContextValue;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+type ColumnValueBase = components['schemas']['ColumnValueBase'];
+type TableMetadata = components['schemas']['TableMetadata'];
+interface RecordContextValue {
+    /** Discriminator for the load lifecycle — same {@link QueryStatus} the query hooks use. */
+    readonly status: QueryStatus;
+    /** Most recent record from the server (or undefined while loading / on error). */
+    readonly record: TableRecord | undefined;
+    /** Last error thrown by the load. Undefined on success. */
+    readonly error: PowerPortalsProError | undefined;
+    /**
+     * Re-fetches this record from the server (replacing any local mutations) and
+     * cascades to every nested descendant's `refresh()`.
+     */
+    readonly reload: () => Promise<void>;
+    /**
+     * Persists this record AND any nested descendants (grids, M2M editors, child
+     * `<RecordContext>`s) — `RecordContext` IS-A `MainContext`, so `save()` here
+     * is the same as `MainContext.saveAll()` would be at this level.
+     *
+     * Order: this record's PATCH first, then each registered descendant's `save()`
+     * in registration order. Each descendant decides its own dirty-skip; saving a
+     * clean RecordContext is a no-op for the record itself but still cascades to
+     * nested descendants in case they have their own pending changes.
+     *
+     * Calls {@link RecordContextProps.onBeforeSave} (when provided) before issuing
+     * the PATCH; throwing from that callback cancels the entire save (no descendants
+     * run either). When inside an outer `<MainContext>`, this is also what gets
+     * wired into the outer `MainContext.saveAll()` for this subtree.
+     */
+    readonly save: () => Promise<void>;
+    /**
+     * Aggregates every pending Dataverse operation across this record AND
+     * every nested descendant — the own `UpdateRequest` / `CreateRequest`
+     * (when dirty) followed by each nested descendant's `getRequests()`, in
+     * registration order. Returns an empty array when nothing is dirty.
+     *
+     * Mirrors Blazor's public `RecordContext.GetRequests()` — same shape, same
+     * traversal. Use for previewing the payload {@link save} would ship,
+     * for dry-run UIs, or to merge the records into a custom
+     * `executeMultiple` batch alongside consumer-supplied requests.
+     * Consumers that just want to persist should call {@link save}.
+     */
+    readonly getRequests: () => OrganizationRequest[];
+    /**
+     * Discards every pending edit on this record AND in every nested
+     * descendant, reverting back to the loaded baseline WITHOUT re-fetching
+     * from the server. The "Cancel" / "Discard" primitive — same surface
+     * as `MainContextValue.resetState`, also drops the record's own
+     * baseline so it re-loads clean.
+     *
+     * Validation errors tracked against the dropped pending values are
+     * also cleared. Synchronous: descendants do their own `setState` calls.
+     */
+    readonly resetState: () => void;
+    /**
+     * Immutably updates one column on the in-memory record. Triggers a re-render of all
+     * descendants reading the record (typed-column hooks bind to this from
+     * `@powerportalspro/react-fluent`'s edit components and similar). Pass `null` or
+     * `undefined` to clear the column. Marks the column dirty in {@link dirtyColumns}
+     * and sets `record.isDirty = true`.
+     *
+     * No-op if no record has loaded yet — children should gate input on `status === 'success'`.
+     */
+    readonly setColumnValue: (columnName: string, value: ColumnValueBase | null | undefined) => void;
+    /**
+     * Patches the loaded baseline with a fresh value for one column WITHOUT
+     * marking the column dirty. Use for late-arriving server-side data — file
+     * binaries lazy-loaded by `<ImageEdit>`/`<FileEdit>`, async-resolved
+     * formatted values, secondary fetches that fill in fields the initial
+     * record query didn't populate. NOT for user edits — those go through
+     * {@link setColumnValue}.
+     *
+     * If the column already has a pending edit, the hydration is skipped to
+     * avoid silently clobbering the user's in-progress change. This
+     * distinguishes "load filled this in" from "user typed this" — the
+     * former sets the baseline, the latter sets a pending value compared
+     * against the baseline for dirty calculation.
+     *
+     * No-op if no record has loaded yet.
+     */
+    readonly hydrateColumnValue: (columnName: string, value: ColumnValueBase | null) => void;
+    /**
+     * Table metadata for the parent record's table — column types, required levels,
+     * isValidForCreate/Update flags, etc. Loaded in parallel with the record itself.
+     *
+     * Independent of `status`: this is `undefined` while metadata is loading, on
+     * metadata fetch failure, or for tables that have no metadata. The record's own
+     * `status` reflects only the record query — metadata is best-effort, edit
+     * components fall back to consumer-passed props when it's absent. This keeps
+     * forms rendering as soon as the record is ready instead of blocking on a
+     * second round-trip.
+     *
+     * Use {@link useColumnMetadata} from `@powerportalspro/react` to look up a
+     * single column's entry.
+     */
+    readonly tableMetadata: TableMetadata | undefined;
+    /**
+     * `true` when at least one column on this record has been modified, OR when
+     * any nested descendant (child `<RecordContext>`, grid, M2M editor) reports
+     * dirty.
+     *
+     * Use this for Save-button enablement, navigation-warning gates, or any UI
+     * that should react to the existence of unsaved changes anywhere in the
+     * record's subtree. For a more focused check (just this record's columns,
+     * ignoring nested descendants), inspect {@link dirtyColumns} directly.
+     */
+    readonly isDirty: boolean;
+    /**
+     * The set of column logical names that have been modified since the record
+     * loaded or was last saved. Cleared on successful {@link save} and when a
+     * fresh record lands from {@link reload}.
+     *
+     * Useful for per-field dirty indicators (a small marker next to a label),
+     * for save filtering (only ship changed columns), or for diff-style review
+     * UIs that show what's about to be persisted.
+     */
+    readonly dirtyColumns: ReadonlySet<string>;
+    /**
+     * Stable id this RecordContext uses when calling {@link OverlayService.show}
+     * during load. Pass to a scoped overlay container (e.g.
+     * `<FluentOverlayTarget targetId={ctx.overlayTargetId}>`) inside the
+     * RecordContext subtree to render the loading spinner localized to that
+     * region rather than full-screen.
+     *
+     * Generated once per RecordContext instance via React's `useId`. If no
+     * `<OverlayService>` is mounted, the show calls no-op silently.
+     */
+    readonly overlayTargetId: string;
+    /**
+     * Runs the context-level {@link RecordContextProps.onBeforeDelete}
+     * callback (when configured), surfacing any thrown error to the
+     * caller so the delete can be cancelled. No-op when no callback is
+     * wired. Delete-style buttons should `await` this BEFORE issuing
+     * their own pre-delete prompts or the actual `deleteRecordAsync`
+     * call. Parallels how `MainContext.saveAll` invokes
+     * {@link MainContextProps.onBeforeSave}.
+     */
+    readonly runBeforeDelete: () => Promise<void>;
+}
+/**
+ * `RecordContext` extends {@link MainContextProps} because every `RecordContext`
+ * conceptually IS-A `MainContext` — Blazor's `RecordContext.razor.cs` literally
+ * inherits from `MainContext.razor.cs` and `override`s `IsDirty` to add the
+ * record's own dirty state on top of the base aggregation. Inheriting the props
+ * means `onBeforeSave` (and any future cross-cutting `MainContextProps`) is
+ * available on a standalone `<RecordContext>` without a wrapping `<MainContext>`.
+ */
+interface RecordContextProps extends MainContextProps {
+    /** Logical name of the Dataverse table (e.g. `"account"`, `"contact"`). */
+    table: string;
+    /**
+     * Primary id of the record to edit. Omit (or pass empty / `Guid.Empty`)
+     * to enter **create mode**: no fetch fires, the in-memory record starts
+     * either empty or from {@link initialRecord}, and {@link save} emits a
+     * `CreateRequest` instead of an `UpdateRequest` on commit.
+     */
+    id?: string;
+    /**
+     * Optional pre-populated record to start from in **create mode** (when
+     * {@link id} is omitted). Use to seed default values — typical case is
+     * a SubGrid-hosted new-record dialog pre-filling the parent foreign-key
+     * column (`parentcustomerid`, `contact_customer_accounts` etc.). Ignored
+     * in edit mode — when `id` is set the server-loaded record is the
+     * baseline. The `tableName` on `initialRecord` should match {@link table};
+     * `id` will be ignored either way (a create starts without one).
+     */
+    initialRecord?: TableRecord;
+    /**
+     * Pre-loaded record to use as the baseline instead of fetching from the
+     * server. When provided in edit mode (with {@link id} set), the network
+     * fetch is skipped entirely and the supplied record becomes the
+     * `loadedRecord` baseline — `status` immediately reads `'success'`.
+     *
+     * The intended consumer is the inline-editable grid: each row already
+     * has its record in hand from the grid's `useGridData` fetch, so per-
+     * row RecordContexts would otherwise issue N redundant `retrieveRecord`
+     * round-trips just to re-fetch what's already on screen. Passing
+     * `loadedRecord={row}` short-circuits that.
+     *
+     * Identity change re-baselines: a fresh reference is treated like a
+     * fresh load, which seeds `loadedRecord` and resets `pendingChanges`
+     * (mirroring the success-effect's behavior on a real refetch). Pass a
+     * stable / memoized reference if you want pending edits to persist
+     * across re-renders.
+     *
+     * Ignored in create mode ({@link id} omitted) — {@link initialRecord}
+     * is the create-mode baseline.
+     */
+    loadedRecord?: TableRecord;
+    /**
+     * Pending column changes to apply on top of the server-loaded record.
+     * Used by the dialog-based Edit flow when reopening a row that already
+     * has queued updates from a prior session — the queued values become
+     * the dialog's initial pendingChanges, so reverting to the server value
+     * cleanly drops the column from `pendingChanges` (matches the loaded
+     * baseline → removed) and the eventual save can detect "no net change"
+     * by inspecting `dirtyColumns`.
+     *
+     * Applied once when the load lands; further user edits drive the
+     * pending map normally via `setColumnValue`. Identity change after the
+     * initial apply re-applies (rare — typically the prop is stable for
+     * the lifetime of a dialog instance).
+     */
+    initialPendingChanges?: ReadonlyMap<string, ColumnValueBase | null>;
+    /** Optional column allow-list. Omit for the table's full visible column set. */
+    columns?: readonly string[];
+    /** Fired once after a successful initial load (and again after any subsequent reload). */
+    onRecordLoaded?: (record: TableRecord) => void;
+    /**
+     * Name of the URL query-string parameter to read the record's id
+     * from. When set, the parameter's current value overrides
+     * {@link id} — useful for routes shaped like
+     * `/accounts/edit?accountId=...` where the consumer would
+     * otherwise wire `useSearchParams` + pass to `id` by hand.
+     *
+     * Router-agnostic — uses `useQueryParam` under the hood which
+     * reads from `window.location.search` and subscribes to back /
+     * forward + programmatic `pushState` / `replaceState` so any
+     * router's navigation triggers an id re-read.
+     *
+     * When the parameter is absent (or empty / Guid.Empty), the
+     * RecordContext enters create mode — same semantic as omitting
+     * the `id` prop entirely.
+     */
+    queryParameterName?: string;
+    /**
+     * Cancellable hook fired before this record is deleted. Throw from
+     * the callback to abort — the delete request never goes out and
+     * subsequent `onDeleted` hooks don't run either.
+     *
+     * Surfaces as `useRecordContext().onBeforeDelete` for delete-style
+     * buttons (the framework `<DeleteContextButton>`, or consumer-built
+     * delete actions) to consult before issuing `deleteRecordAsync`.
+     * Per-button `onBeforeDelete` props chain after this — context first
+     * (record-scoped policy), button second (action-specific).
+     *
+     * Use this for context-level deletion gates: "deleted records can't
+     * have active child records" / "only owners can delete" / etc.
+     * Throwing with a meaningful error message is fine — the framework
+     * delete button routes thrown errors through its `onError` path or
+     * the dialog service's error display.
+     */
+    onBeforeDelete?: () => void | Promise<void>;
+}
+/**
+ * Loads a single Dataverse record and provides it to descendants via React
+ * context (the analog of Blazor's cascading value). Children call
+ * {@link useRecordContext} to read the record + status.
+ *
+ * Also acts as a `MainContext` for its own subtree — nested grids, M2M editors,
+ * and child `<RecordContext>`s register with this `RecordContext` instead of
+ * skipping past it to a further-up `<MainContext>`. The aggregated
+ * `isDirty`/`saveAll` exposed to a wrapping outer `<MainContext>` includes both
+ * this record's own pending edits AND every nested descendant's state, so a
+ * single outer `<SaveButton>` covers everything beneath it.
+ *
+ * Auto-registers with a parent {@link MainContext} (when present) so
+ * {@link MainContext.saveAll} / {@link MainContext.refreshAll} include this record.
+ * Without a parent, `save()` and `reload()` are still callable directly from
+ * descendants via the context.
+ *
+ * What's deferred from Blazor's RecordContext (the full version is ~700 lines —
+ * this is the headless coordination skeleton):
+ * - **New-record creation** (id absent → empty TableRecord). Will need a
+ *   `mode: "edit" | "create"` discriminator and dispatching `createRecordAsync`
+ *   instead of `updateRecordAsync` from `save()`.
+ * - **Dirty tracking + EditContext-style validation**. Tied to the form layer.
+ * - **`OnBeforeSave` / `OnBeforeDelete`** cancellable callbacks at this level
+ *   (MainContext already has `onBeforeSave`).
+ * - **Delete handler** with confirmation flow.
+ * - **URL query-parameter reading** (Blazor's `QueryParameterName`). Consumers can
+ *   pull the id from `useSearchParams()` themselves and pass it as the `id` prop.
+ * - **PersistentComponentState** for server→WASM bridging. N/A in pure React.
+ */
+/**
+ * Wrapper that auto-mounts a {@link ValidationProvider} around the inner
+ * record-context logic. The split lets the inner component call
+ * `useValidationContext()` (e.g. to clear errors on reload) — that hook
+ * resolves the provider this wrapper just rendered.
+ *
+ * The two-component shape is invisible to consumers — `<RecordContext>` is
+ * the only public surface.
+ */
+declare function RecordContext(props: RecordContextProps): react_jsx_runtime.JSX.Element;
+/**
+ * Reads the nearest ancestor {@link RecordContext}'s value. Throws when called
+ * outside one — same diagnostic pattern as `useAuth`.
+ *
+ * @example
+ * ```tsx
+ * import { QueryStatus, useRecordContext } from '@powerportalspro/react';
+ *
+ * function ContactDetails() {
+ *   const { status, record } = useRecordContext();
+ *   if (status === QueryStatus.Loading) return <Spinner />;
+ *   if (status === QueryStatus.Error)   return <ErrorBanner />;
+ *   return <h1>{record!.formattedValues?.name}</h1>;
+ * }
+ * ```
+ */
+declare function useRecordContext(): RecordContextValue;
+/**
+ * Non-throwing variant of {@link useRecordContext} — returns the nearest
+ * `<RecordContext>`'s value when one is present, otherwise `null`. Useful
+ * for components that work either inside or outside a record context
+ * (e.g. `<SubGrid>` picks up the cascading record when one is available
+ * but accepts an explicit `record` prop as an alternative).
+ *
+ * Prefer {@link useRecordContext} when the component absolutely requires
+ * the context — the loud throw catches wiring bugs early; this hook is
+ * for the genuinely optional case.
+ */
+declare function useRecordContextOptional(): RecordContextValue | null;
+
+interface LookupRecordContextProps {
+    /**
+     * Logical name of the lookup column on the parent `<RecordContext>`'s
+     * record. The column must resolve to a `LookupValue` (typed
+     * `$type: 6`) — the component reads the lookup's `tableName` + `value`
+     * and spawns a nested `<RecordContext>` for the referenced record.
+     *
+     * Required. Mirrors Blazor's `<LookupRecordContext ColumnName="...">`
+     * `ColumnName` parameter.
+     */
+    columnName: string;
+    /**
+     * Optional pre-save cancellable hook forwarded to the nested
+     * `<RecordContext>`. Throwing (or returning a rejected promise) from
+     * this callback aborts the save before any server call — the same
+     * semantic as `<RecordContext onBeforeSave={…}>` directly. Mirrors
+     * Blazor's `LookupRecordContext.OnBeforeSave` cancellable hook.
+     */
+    onBeforeSave?: () => void | Promise<void>;
+    /**
+     * Children rendered inside the nested context. Typical contents:
+     * edit components (`<TextEdit>`, `<NumberEdit>`, etc.) bound to
+     * columns on the LOOKED-UP record's table — e.g. an
+     * `<TextEdit columnName="firstname" />` inside a
+     * `<LookupRecordContext columnName="primarycontactid">` on an account
+     * form edits the linked contact's first name.
+     */
+    children?: ReactNode;
+    /**
+     * When `false`, renders nothing. Defaults to `true`. Useful for
+     * conditionally hiding the section without unmounting the
+     * declaration. Mirrors `IsVisible` on the other framework
+     * components.
+     */
+    isVisible?: boolean;
+}
+/**
+ * Branches off into a nested `<RecordContext>` for the record referenced
+ * by a lookup column on the surrounding `<RecordContext>`. Mirrors
+ * Blazor's `<LookupRecordContext>` — a thin wrapper that resolves the
+ * lookup value, gates on its presence, and spawns the nested context.
+ *
+ * Edit components inside the lookup context bind to columns on the
+ * LOOKED-UP record's table, not the parent's. Changes flow through the
+ * surrounding save cascade automatically via the descendant-registry
+ * plumbing every `<RecordContext>` already wires up — the nested record
+ * registers with the outermost `<MainContext>` (or
+ * `<RecordContext>`-as-MainContext) and its pending edits join the
+ * single transactional `executeMultiple` batch on save.
+ *
+ * **Conditional render (matches Blazor's lazy pattern):** the nested
+ * `<RecordContext>` is only instantiated when the lookup actually has
+ * a value (non-null + non-empty-GUID + has `tableName`). Empty lookups
+ * render nothing — avoids spinning up nested contexts, EditContext
+ * validators, descendant registrations, etc. for every empty lookup
+ * column on a form. The Blazor source carries an explicit perf note on
+ * this: ~10 lookups × per-render lifecycle overhead added up to a
+ * measurable freeze before the conditional render was added.
+ *
+ * ```tsx
+ * <RecordContext table="account" id={accountId}>
+ *   <Section>
+ *     <SectionColumn header={<Text>Account</Text>}>
+ *       <TextEdit columnName="name" />
+ *       <TextEdit columnName="accountnumber" />
+ *     </SectionColumn>
+ *
+ *     <SectionColumn header={<Text>Primary contact</Text>}>
+ *       <LookupRecordContext columnName="primarycontactid">
+ *         {/* These edits bind to the linked CONTACT, not the account *\/}
+ *         <TextEdit columnName="firstname" />
+ *         <TextEdit columnName="lastname" />
+ *         <TextEdit columnName="emailaddress1" type="email" />
+ *       </LookupRecordContext>
+ *     </SectionColumn>
+ *   </Section>
+ * </RecordContext>
+ * ```
+ *
+ * Renders `null` when:
+ *  - the surrounding `<RecordContext>` hasn't loaded yet,
+ *  - the parent column doesn't carry a `LookupValue`,
+ *  - the lookup is the empty GUID (Dataverse's "no value" sentinel), or
+ *  - the lookup is missing its `tableName`.
+ *
+ * `<LookupRecordContext>` deliberately does NOT mirror Blazor's
+ * `BaseColumnEdit` inheritance — the parent's column read-write loop
+ * is owned by `useLookupColumn(columnName)` for consumers who want to
+ * change the lookup value programmatically; `<LookupRecordContext>` is
+ * pure read-then-branch.
+ */
+declare function LookupRecordContext({ columnName, onBeforeSave, children, isVisible, }: LookupRecordContextProps): react_jsx_runtime.JSX.Element | null;
+
+type ColumnMetadataBase = components['schemas']['ColumnMetadataBase'];
+/**
+ * Returns the column metadata for the given column name from the parent
+ * {@link RecordContext}'s table metadata. Returns `undefined` when:
+ * - the table metadata hasn't loaded yet (the request is still in flight),
+ * - the table metadata fetch failed,
+ * - the column doesn't exist on the table.
+ *
+ * Edit components use this to auto-resolve defaults (`maxLength`, `min`,
+ * `max`, `precision`, `required`, `readOnly`) when consumer-passed props are
+ * absent. Pass-through props always win — same convention as Blazor's
+ * `BaseColumnEdit.OnParametersSetAsync` (which only fills metadata-derived
+ * defaults when the consumer hasn't set them explicitly).
+ *
+ * Throws if not used inside a `<RecordContext>`, since column metadata only
+ * makes sense relative to a record's table.
+ */
+declare function useColumnMetadata(columnName: string): ColumnMetadataBase | undefined;
+
+/**
+ * Headless localizer contract. The framework calls `t(key)` to fetch a
+ * localized string; consumers can plug in any implementation that satisfies
+ * this interface — the bundled default ({@link createLocalizer}) reads from a
+ * flat key→string map, but an i18next-backed adapter, a hardcoded English
+ * map for tests, or a server-driven RPC localizer all work the same way.
+ *
+ * Args use positional indexing (`args[0]` → `{0}` in the template) to match
+ * the existing Blazor `IStringLocalizer` JSON format — `.NET String.Format`
+ * placeholders. Consumers using a named-args lib (e.g. i18next's `{{name}}`)
+ * adapt at the boundary.
+ */
+interface Localizer {
+    t(key: string, args?: readonly unknown[]): string;
+}
+/**
+ * Reads the nearest {@link Localizer}. Throws when called outside a provider —
+ * mirrors `useDialogService`'s strict behavior. The framework auto-mounts a
+ * default `<DefaultLocalizerProvider>` inside `<PowerPortalsProProvider>`, so
+ * this only fails when neither is present (typically a misconfigured test).
+ */
+declare function useLocalizer(): Localizer;
+/**
+ * Sugar over `useLocalizer().t` — returns the bound `t` function directly so
+ * components can write `const t = useT();` and then `t('app.buttons.save.label')`.
+ */
+declare function useT(): Localizer['t'];
+/**
+ * Returns a {@link Localizer.t} function with every key automatically
+ * prepended with `{prefix}.`. React analog of Blazor's
+ * `IPrefixedStringLocalizer` / `IStringLocalizer<T>` — use when a
+ * component consumes strings from a known namespace (typically another
+ * framework's class-scoped keys) and you don't want to repeat the
+ * prefix at every call site.
+ *
+ * Pure sugar over `useT()` — relies on the same auto-mounted
+ * `<DefaultLocalizerProvider>` and inherits all of its behavior
+ * (cache, locale tracking, missing-key warnings). The bundle still
+ * needs the full unprefixed key; this just saves the caller from
+ * writing it out each time.
+ *
+ * @example
+ * ```tsx
+ * const t = usePrefixedT(
+ *   'components.PowerPortalsPro.Web.Blazor.FluentUI.Components.Theme.ThemeColorSelector',
+ * );
+ * t('OfficeColor.0');
+ * // → looks up
+ * //   'components.PowerPortalsPro.Web.Blazor.FluentUI.Components.Theme.ThemeColorSelector.OfficeColor.0'
+ * ```
+ *
+ * The returned function is stable per `prefix` value (memoized via
+ * `useCallback`), so it's safe to reference from effect dependency
+ * arrays. Passing a fresh literal each render reuses the same identity
+ * as long as the string is identical.
+ */
+declare function usePrefixedT(prefix: string): Localizer['t'];
+/**
+ * Imperative contract for queueing per-resource localization bundles. The
+ * default localizer provider sets one of these on the
+ * {@link LocalizationPrefetcherContext}; custom adapters set via
+ * `<LocalizerProvider value={…}>` don't have to provide one — the public
+ * hooks degrade gracefully (treat everything as "loaded") when the
+ * prefetcher is absent.
+ */
+interface LocalizationPrefetcher {
+    /**
+     * Queue the supplied prefixes for fetch via the existing debounce / batch
+     * mechanism. Prefixes already fetched (or in flight) are silently skipped
+     * — repeated calls with the same prefixes don't generate redundant network
+     * traffic. Returns immediately; the actual fetch happens after the next
+     * flush tick.
+     */
+    prefetch(prefixes: readonly string[]): void;
+    /**
+     * Returns `true` once every supplied prefix has been *settled* — fetched
+     * successfully OR a failed attempt has resolved. Failures count as settled
+     * deliberately: a flaky bundle endpoint shouldn't strand consumers waiting
+     * forever. Per-fetch errors are logged via `console.warn` by the
+     * underlying flush so they remain debuggable.
+     *
+     * Prefixes not covered by a per-resource bundle (anything outside
+     * `tables.{name}` / `views.{viewId}` shape) are treated as already loaded
+     * — those keys live in the default bundle that loads on app boot.
+     */
+    isLoaded(prefixes: readonly string[]): boolean;
+    /**
+     * Subscribe to settled-set changes. The listener fires synchronously once
+     * per flush, after the settled set is updated. Used by
+     * {@link useLocalizationLoaded} to re-render subscribers; advanced
+     * consumers can hook in directly. Returns an unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Reads the active {@link LocalizationPrefetcher}. Returns `null` when no
+ * provider is mounted (custom-adapter setups). Most consumers should use
+ * the higher-level {@link useLocalization} / {@link useLocalizationLoaded}
+ * hooks; this is the raw escape hatch.
+ */
+declare function useLocalizationPrefetcher(): LocalizationPrefetcher | null;
+/**
+ * Declares localization prefixes the calling component (or its subtree)
+ * needs. The framework queues them via the existing debounced fetch
+ * pipeline — by the time the user wanders into a component that calls
+ * `t('tables.account.label')`, the fetch is either complete or in flight,
+ * collapsing the brief flash of raw keys.
+ *
+ * Fire-and-forget — does not block render or expose loading state. Pair
+ * with `<LocalizationBoundary>` (from `@powerportalspro/react-fluent`) or
+ * {@link useLocalizationLoaded} when you need to hold off rendering until
+ * the strings are ready.
+ *
+ * Accepts prefix or full-key shapes:
+ *  - `tables.{tablename}` (token) → loads `tables.<tablename>.*` strings
+ *  - `tables.account.label` (key) → coerced to `tables.account`
+ *  - `views.{viewId}` (token) → loads `views.<viewId>.*` strings
+ *  - `tables.account.views.{viewId}.foo` (key) → coerced to `views.<viewId>`
+ *  - Anything else (`app.*`, `components.*`) → silently dropped; covered
+ *    by the default bundle loaded on app boot.
+ *
+ * Re-fires only when `prefixes` changes by VALUE — passing a fresh array
+ * with the same content each render doesn't requeue. Already-fetched
+ * prefixes are deduped at the prefetcher layer regardless, so calling
+ * `useLocalization(['tables.account'])` from two components on the same
+ * page produces one network round-trip total.
+ *
+ * No-op when no `<DefaultLocalizerProvider>` ancestor is mounted (consumer
+ * is on a custom localizer adapter).
+ *
+ * @example
+ * ```tsx
+ * function MyAccountPage() {
+ *   useLocalization(['tables.account', 'tables.contact']);
+ *   return <Form>...</Form>;
+ * }
+ * ```
+ */
+declare function useLocalization(prefixes: readonly string[]): void;
+/**
+ * Reactive boolean — `true` once every prefix in the array has been settled
+ * (fetched or failed). Re-renders the calling component when the state
+ * flips. Treats a missing prefetcher (custom-adapter consumer) as "always
+ * loaded" so dependent components degrade gracefully.
+ *
+ * Powers `<LocalizationBoundary>` and is exported for consumers that want
+ * to drive their own gating UX — e.g. a loading row inside a grid rather
+ * than holding off the whole subtree.
+ *
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   const ready = useLocalizationLoaded(['tables.account']);
+ *   if (!ready) return <Spinner />;
+ *   return <Form>...</Form>;
+ * }
+ * ```
+ */
+declare function useLocalizationLoaded(prefixes: readonly string[]): boolean;
+/**
+ * Provides an explicit {@link Localizer} to the subtree. Used internally by
+ * {@link DefaultLocalizerProvider}; consumers wanting to swap in i18next or
+ * any other implementation wrap their tree with this and pass their adapter
+ * as `value`.
+ */
+declare function LocalizerProvider({ value, children, }: {
+    value: Localizer;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Flattens a nested object (Blazor's localization JSON shape) into a flat
+ * `key.path → value` map. Drops non-string leaves (no use for them in the
+ * localizer's lookup).
+ */
+declare function flattenStrings(obj: Record<string, unknown>, prefix?: string): Record<string, string>;
+/**
+ * Substitutes `{0}`, `{1}`, etc. with the corresponding positional arg.
+ * Strips `.NET`-style format specifiers (`{0:N0}`, `{1:yyyy-MM-dd}`) since
+ * those are .NET-only and don't translate to JS without a custom formatter
+ * pipeline. Consumers needing locale-aware number / date display should
+ * format their values via `Intl.NumberFormat` / `Intl.DateTimeFormat` before
+ * passing them to `t()`.
+ *
+ * Out-of-range placeholders are left as-is (visible in the rendered string)
+ * so the missing arg surfaces during dev.
+ */
+declare function interpolate(template: string, args?: readonly unknown[]): string;
+/**
+ * Optional behavior knobs for {@link createLocalizer}.
+ */
+interface CreateLocalizerOptions {
+    /**
+     * Called once per missing key the first time it's looked up. Use to wire
+     * dev-mode warnings, telemetry, or to fail loudly during tests. The hook
+     * is invoked AFTER the localizer falls back to returning the raw key.
+     *
+     * Each key is reported at most once per localizer instance — repeat
+     * lookups for the same missing key don't fire it again. This keeps a
+     * deeply-rendered missing key from spamming the console.
+     */
+    onMissingKey?: (key: string) => void;
+}
+/**
+ * Builds a {@link Localizer} backed by a flat string map. Missing keys
+ * return the key itself (visible fallback for missing strings — easier to
+ * spot than silently showing nothing). Pass `onMissingKey` to get a hook
+ * that fires once per missing key.
+ */
+declare function createLocalizer(strings: Record<string, string>, options?: CreateLocalizerOptions): Localizer;
+/**
+ * Substitutes the `{locale}` placeholder in a URL template. URLs without
+ * the placeholder pass through unchanged — useful for static-locale
+ * deployments where every locale uses the same URL.
+ */
+declare function resolveLocalizationUrl(template: string, locale: string): string;
+/**
+ * Cookie name ASP.NET Core's `CookieRequestCultureProvider` uses to persist
+ * the active culture. Same cookie the Blazor stack sets via the
+ * <c>/Culture/{culture}</c> endpoint, so reading/writing it here keeps the
+ * React and Blazor stacks in sync when both are hosted side-by-side.
+ */
+declare const ASP_NET_CULTURE_COOKIE = ".AspNetCore.Culture";
+/**
+ * Reads the ASP.NET Core culture cookie. The cookie value follows the
+ * `c={culture}|uic={uiCulture}` shape (URL-encoded) — we parse the `c`
+ * segment. Returns `null` when the cookie isn't set or can't be parsed.
+ *
+ * Safe to call in non-browser environments (returns `null`); both `document`
+ * and `document.cookie` are guarded.
+ */
+declare function getAspNetCultureCookie(): string | null;
+/**
+ * Writes the ASP.NET Core culture cookie with both `c` and `uic` segments
+ * set to the same value. Mirrors what the server-side
+ * <c>/Culture/{culture}</c> endpoint sets, so a React-side locale change
+ * immediately affects subsequent server-rendered Blazor pages on the same
+ * origin (and vice versa).
+ *
+ * Defaults to `path=/`, 1-year expiry, `SameSite=Lax`. Safe to call in
+ * non-browser environments (no-op).
+ */
+declare function setAspNetCultureCookie(culture: string, options?: {
+    path?: string;
+    maxAgeSeconds?: number;
+}): void;
+/**
+ * Default regex matching a locale code at the start of `window.location.pathname` —
+ * shapes like `/en`, `/en/`, `/en-US/page`, `/fr-CA/path/x`. Captures the
+ * locale code in group 1. Only 2-letter primary tags + optional 2–4-letter
+ * subtag (script / region) are recognized; arbitrary path segments don't
+ * trigger a false match.
+ */
+declare const DEFAULT_URL_LOCALE_PATTERN: RegExp;
+/**
+ * Reads the locale from the URL path's first segment using
+ * {@link DEFAULT_URL_LOCALE_PATTERN} (override via `pattern`). Returns the
+ * matched locale or `null` when the URL doesn't carry one.
+ *
+ * Safe to call in non-browser environments (returns `null`).
+ */
+declare function getLocaleFromUrlPath(pattern?: RegExp): string | null;
+/**
+ * Resolves the active locale from common sources, in order of precedence:
+ *
+ * 1. URL path segment (`/en/...`) — picked up via {@link getLocaleFromUrlPath}
+ *    when `matchUrl` is `true` (default).
+ * 2. ASP.NET culture cookie (`.AspNetCore.Culture`) — picked up via
+ *    {@link getAspNetCultureCookie}.
+ * 3. `navigator.language` — when `matchBrowser` is `true` (default), strips
+ *    the region (e.g. `en-US` → `en`) for compatibility with bundle locale
+ *    codes which are typically primary-tag only.
+ * 4. The supplied `fallback` (default `'en'`).
+ *
+ * Used by `<LocaleProvider>` for auto-detection; also exported for consumer
+ * code that wants the resolved locale without the provider context.
+ */
+declare function detectLocale(options?: {
+    matchUrl?: boolean;
+    urlPattern?: RegExp;
+    matchBrowser?: boolean;
+    fallback?: string;
+}): string;
+interface LocaleState {
+    /** Current locale code (e.g. `'en'`, `'es'`, `'fr-CA'`). */
+    readonly locale: string;
+    /** Replace the active locale. Triggers re-fetch of localization JSONs. */
+    readonly setLocale: (locale: string) => void;
+}
+/**
+ * Reads the active locale state, falling back to `{ locale: 'en' }` when no
+ * `<LocaleProvider>` is mounted. Apps that don't need locale switching can
+ * skip the provider — the framework treats the default locale as `'en'`.
+ */
+declare function useLocale(): LocaleState;
+interface LocaleProviderProps {
+    /**
+     * Initial locale on mount. Used as the FALLBACK when auto-detection is
+     * enabled (the default) and finds no URL / cookie / browser hint, OR as
+     * the literal initial value when `autoDetect={false}`. Defaults to `'en'`.
+     */
+    initialLocale?: string;
+    /**
+     * Auto-detect the active locale via {@link detectLocale} on mount. Default
+     * `true`. When enabled, the resolution order is:
+     * URL path → ASP.NET culture cookie → `navigator.language` → `initialLocale`.
+     * Pass `false` to start from `initialLocale` ignoring the environment.
+     */
+    autoDetect?: boolean;
+    /**
+     * Override the URL pattern used by `autoDetect`. Defaults to
+     * {@link DEFAULT_URL_LOCALE_PATTERN}. Set to a custom RegExp when your
+     * routes use a non-standard locale-segment shape, or pass `null` to
+     * disable URL-based detection (only cookie + browser will be checked).
+     */
+    urlPattern?: RegExp | null;
+    /**
+     * Persist locale changes to the ASP.NET culture cookie (the same cookie
+     * Blazor's locale switcher writes via `/Culture/{culture}`). Default
+     * `true` — keeps the React + Blazor stacks in sync when both render
+     * pages on the same origin. Pass `false` to manage persistence yourself
+     * (e.g. via the `onLocaleChange` callback).
+     */
+    persistToCookie?: boolean;
+    /**
+     * Optional controlled locale. When provided, the component is controlled
+     * and `setLocale` calls are forwarded via {@link onLocaleChange}. When
+     * omitted, the component is uncontrolled with internal state.
+     */
+    locale?: string;
+    /**
+     * Called when `setLocale` is invoked. Required when {@link locale} is
+     * provided (controlled mode); ignored otherwise.
+     */
+    onLocaleChange?: (locale: string) => void;
+    children: ReactNode;
+}
+/**
+ * Provides the active locale + a setter to the subtree. Descendants read via
+ * {@link useLocale}; the {@link DefaultLocalizerProvider} subscribes
+ * automatically and re-fetches its JSONs when the locale changes.
+ *
+ * Supports both controlled (`locale` + `onLocaleChange` props) and
+ * uncontrolled (`initialLocale` only, internal state) modes — same pattern
+ * as Fluent UI's controlled inputs.
+ *
+ * Example:
+ * ```tsx
+ * <LocaleProvider initialLocale="en">
+ *   <PowerPortalsProProvider>
+ *     <App />  {/* useLocale() inside returns { locale: 'en', setLocale: ... } *\/}
+ *   </PowerPortalsProProvider>
+ * </LocaleProvider>
+ * ```
+ */
+declare function LocaleProvider({ initialLocale, autoDetect, urlPattern, persistToCookie, locale: controlledLocale, onLocaleChange, children, }: LocaleProviderProps): react_jsx_runtime.JSX.Element;
+interface DefaultLocalizerProviderProps {
+    /**
+     * Optional additional URL templates to fetch + layer on top of the
+     * server bundle. Each may contain `{locale}` substituted with the active
+     * locale. Layered later-wins: bundle first, then each URL in order.
+     *
+     * Most apps leave this empty — the server bundle (framework defaults +
+     * app overrides + Dataverse-metadata-derived strings outside `tables.*`)
+     * already covers the common case. Use this for client-side overrides or
+     * page-specific files the consumer doesn't want round-tripping through
+     * the server.
+     */
+    urls?: readonly string[];
+    /**
+     * @deprecated Use {@link urls} instead. Kept for backwards compatibility —
+     * when set, treated as `urls: [url]`.
+     */
+    url?: string;
+    /**
+     * Called once per missing key the first time it's looked up via `t(key)`.
+     * Defaults to a `console.warn` so missing strings surface during dev.
+     * Pass `() => undefined` to silence; pass a custom function to route the
+     * warnings to telemetry.
+     *
+     * Fires whether or not the on-demand endpoint fetch succeeds — the hook is
+     * about "this key wasn't in the static cache when first seen", not "this
+     * key is unresolvable globally".
+     */
+    onMissingKey?: (key: string) => void;
+    /**
+     * Baseline localization prefixes the provider should eagerly load
+     * alongside the default bundle on mount. Same shape as the prop on
+     * {@link LocalizationBoundary} — `tables.{name}` / `views.{viewId}`
+     * tokens (or full keys, coerced). The framework queues them through
+     * the standard prefetch pipeline once the default bundle has
+     * resolved; descendant `<LocalizationBoundary>` components
+     * automatically wait for them as part of their readiness check, so
+     * baseline strings the whole app needs (e.g. tables that appear in
+     * the navigation chrome) flow into the cache before any boundary
+     * mounts its children.
+     *
+     * Prefixes the default bundle already covers (`app.*`,
+     * `components.*`) are silently dropped — they're loaded as part of
+     * Tier 1 regardless.
+     *
+     * Changing this prop after mount is supported: new prefixes are
+     * queued on the next render; removed prefixes stay cached (we don't
+     * actively evict strings — they just won't be re-fetched on locale
+     * change). Most apps set this once at the root and never change it.
+     */
+    prefixes?: readonly string[];
+    children: ReactNode;
+}
+/**
+ * Auto-loads localized strings and provides a {@link Localizer} to the
+ * subtree using a two-tier strategy:
+ *
+ * **Tier 1 — manifest + default bundle (eager, on mount + locale change).**
+ *
+ * Fetches the manifest from `/localizations/version`, then the default
+ * bundle from `/localizations/default/{locale}.{thumbprint}.json`. The
+ * thumbprint segment makes each release's URL unique so the browser can
+ * cache it `immutable`. The default bundle contains everything outside
+ * `tables.*` / `choices.*`. Optional client-side overlay URLs (the `urls`
+ * prop) are fetched in parallel and layered later-wins on top.
+ *
+ * **Tier 2 — per-resource bundle fetches (lazy, on cache miss).**
+ *
+ * When `t(key)` is called and the key isn't in the static cache, the key
+ * is coerced to its owning bundle token (`tables.{name}` or `views.{viewId}`)
+ * and queued for a debounced batched fetch (~75 ms). The flush fires one
+ * GET per distinct token in parallel, each landing under a per-resource
+ * thumbprinted URL (`/localizations/tables/{name}/{locale}.{thumb}.json`,
+ * `/localizations/views/{viewId}/{locale}.{thumb}.json`). Subsequent
+ * navigations to a page declaring the same token reuse the browser-cached
+ * response with zero network traffic. Source-generator-emitted tokens (via
+ * `LocalizationManifest`) flow through the same path — one fetch per
+ * declared token, on first hit, then cached.
+ *
+ * **Render strategy — non-blocking.** Children render immediately with a
+ * key-fallback localizer (every `t(key)` returns the key as plain text);
+ * the provider swaps in real strings once the manifest + bundle resolve.
+ * Cache misses appear as raw keys briefly until the per-resource fetch
+ * resolves and triggers a re-render.
+ *
+ * **Locale changes** clear the cache, cancel any in-flight fetch, re-fetch
+ * the manifest + bundle at the new locale, and start fresh.
+ *
+ * Auto-mounted by `<PowerPortalsProProvider>`. Wrap with a custom
+ * `<LocalizerProvider>` and pass `localizationUrl={false}` on the provider
+ * to opt out entirely (e.g. when adapting i18next).
+ */
+declare function DefaultLocalizerProvider({ urls, url, onMissingKey, prefixes, children, }: DefaultLocalizerProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Outcome of a dialog interaction. `cancelled` is `true` when the user
+ * dismissed the dialog (clicked the secondary button on a confirmation,
+ * pressed Escape, clicked the backdrop, or otherwise rejected the action).
+ *
+ * Mirrors Blazor's `DialogResult` shape — kept as an object rather than a
+ * naked boolean so we can extend with `data?` etc. when custom-content
+ * dialogs land without a wire-breaking change.
+ */
+interface DialogResult {
+    /** True when the user dismissed/cancelled, false when they confirmed. */
+    readonly cancelled: boolean;
+}
+/** Common shape for all single-button dialogs (success / warning / error / info). */
+interface DialogOptions {
+    /** Dialog title. When omitted, the implementation supplies a sensible default for the variant. */
+    title?: string;
+    /** Label for the primary (and only) action button. Defaults to `"OK"`. */
+    primaryText?: string;
+}
+/** Options for a confirmation dialog (two action buttons). */
+interface ConfirmationDialogOptions extends DialogOptions {
+    /** Label for the primary (affirmative) button. Defaults to `"Yes"`. */
+    primaryText?: string;
+    /** Label for the secondary (negative) button. Defaults to `"No"`. */
+    secondaryText?: string;
+}
+/**
+ * Headless dialog service contract — equivalent to Blazor's `IDialogService`.
+ * The framework calls these methods to surface success/warning/error/info
+ * messages and confirmation prompts; consumers provide the concrete
+ * implementation via {@link DialogServiceProvider} (typically the Fluent UI
+ * implementation that ships with `@powerportalspro/react-fluent`, but any
+ * dialog UI works as long as it satisfies this contract).
+ *
+ * **Message format.** The `message` argument is treated as HTML markup —
+ * matching Blazor's `Microsoft.FluentUI.AspNetCore.Components.IDialogService`,
+ * which renders messages via `MarkupString`. Tags like `<br/>`, `<strong>`,
+ * `<em>` work; framework localization strings (e.g.
+ * `app.messages.unsaved-changes`) rely on this. Don't pass unsanitized user
+ * input — same constraint as Blazor.
+ *
+ * Each method returns a {@link DialogResult} so the same shape covers both
+ * single-button (always `{ cancelled: false }` once dismissed) and
+ * confirmation dialogs.
+ */
+interface DialogService {
+    showSuccessAsync(message: string, options?: DialogOptions): Promise<DialogResult>;
+    showWarningAsync(message: string, options?: DialogOptions): Promise<DialogResult>;
+    showErrorAsync(message: string, options?: DialogOptions): Promise<DialogResult>;
+    showInfoAsync(message: string, options?: DialogOptions): Promise<DialogResult>;
+    showConfirmationAsync(message: string, options?: ConfirmationDialogOptions): Promise<DialogResult>;
+}
+/**
+ * Reads the nearest ancestor {@link DialogServiceProvider}. Throws when called
+ * outside one — the framework relies on the dialog service for unsaved-changes
+ * warnings, error reporting, etc.; throwing surfaces missing-provider bugs at
+ * mount time instead of producing silent no-op dialogs.
+ */
+declare function useDialogService(): DialogService;
+/**
+ * Provides a {@link DialogService} implementation to the subtree. UI libraries
+ * that ship a `DialogService` (e.g. `@powerportalspro/react-fluent`'s
+ * `<FluentDialogProvider>`) wrap their tree with this internally.
+ */
+declare function DialogServiceProvider({ value, children, }: {
+    value: DialogService;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Prompts the user about unsaved changes. Returns `true` if the user wants to
+ * continue (discarding their edits), `false` if they want to cancel and keep
+ * editing. Mirrors Blazor's `IPowerPortalsProDialogService.WarnAboutUnsavedChangesAsync`.
+ *
+ * Used by the framework before navigation, refresh, and any other operation
+ * that would discard pending edits. Application code can also call it directly
+ * for custom flows.
+ *
+ * Strings come from the supplied {@link Localizer} (default English from
+ * the framework's bundled JSON). Keys: `app.messages.unsaved-changes` (body),
+ * `app.messages.unsaved-changes-title` (title), `app.buttons.yes.label` /
+ * `app.buttons.no.label` (button labels).
+ */
+declare function warnAboutUnsavedChangesAsync(dialog: DialogService, localizer: Localizer): Promise<boolean>;
+/**
+ * Hook variant of {@link warnAboutUnsavedChangesAsync}. Returns a stable
+ * function bound to the current dialog service + localizer from context.
+ */
+declare function useWarnAboutUnsavedChanges(): () => Promise<boolean>;
+
+/** Options passed to {@link OverlayService.show}. */
+interface OverlayOptions {
+    /**
+     * Target id to scope the overlay. Undefined / empty = global (full-screen);
+     * any other value routes to a matching scoped `<OverlayTarget>` registered
+     * with the same id.
+     */
+    targetId?: string | undefined;
+    /** Text to display alongside the spinner (e.g. `"Loading..."`, `"Saving..."`). */
+    description?: string | undefined;
+    /** Whether to show a spinner. Defaults to `true`. */
+    showProgress?: boolean | undefined;
+}
+/**
+ * A live overlay handle returned by {@link OverlayService.show}. Pass it to
+ * {@link OverlayService.hide} to dismiss exactly that overlay (matters when
+ * concurrent show calls are stacked on the same target).
+ */
+interface OverlayInstance extends OverlayOptions {
+    /** Stable id assigned by the service at show time. */
+    readonly id: string;
+}
+/**
+ * Headless overlay service contract — equivalent to Blazor's
+ * `IOverlayService`. Maintains a per-target stack of overlay instances; the
+ * topmost instance for a target is what renders. Concrete implementations
+ * (e.g. `<FluentOverlayProvider>` from `@powerportalspro/react-fluent`)
+ * provide the actual UI.
+ *
+ * Reads happen via the {@link useOverlayForTarget} hook — that's how
+ * components subscribe to "what overlay should I currently render". The
+ * service interface itself is write-only (show / hide / hideAll).
+ */
+interface OverlayService {
+    /** Push an overlay onto its target's stack. Returns the handle to dismiss it. */
+    show(options?: OverlayOptions): OverlayInstance;
+    /** Remove a specific overlay from its target's stack. No-op if already removed. */
+    hide(overlay: OverlayInstance): void;
+    /** Clear every overlay on every target. */
+    hideAll(): void;
+}
+interface OverlayContextValue {
+    readonly service: OverlayService;
+    /**
+     * Per-target stacks. Keyed by `targetId ?? ''` (empty string = global).
+     * Last item in each stack is the topmost / currently-rendered overlay.
+     * Mutated only via the service; consumers read via {@link useOverlayForTarget}.
+     */
+    readonly overlaysByTarget: ReadonlyMap<string, readonly OverlayInstance[]>;
+}
+/** Returns the nearest {@link OverlayService}, or `null` when no provider is mounted. */
+declare function useOverlayService(): OverlayService | null;
+/**
+ * Returns the topmost overlay currently active for the given target id (or
+ * `null` if there is none). Subscribers re-render when their target's stack
+ * changes — this is how overlay-rendering components like
+ * `<FluentOverlayProvider>` and `<FluentOverlayTarget>` know what to draw.
+ */
+declare function useOverlayForTarget(targetId?: string): OverlayInstance | null;
+/**
+ * Provides an externally-built {@link OverlayService} + state to the subtree.
+ * Real implementations like `<FluentOverlayProvider>` use this internally;
+ * tests can use it to inject a mock service.
+ */
+declare function OverlayServiceProvider({ value, children, }: {
+    value: OverlayContextValue;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Hook that builds a state-backed {@link OverlayService} + the overlays-by-target
+ * map needed for the {@link OverlayServiceProvider} value. Used by overlay
+ * provider components — wraps children with `<OverlayServiceProvider value={...}>`
+ * and renders the actual overlay UI based on the returned `overlaysByTarget`.
+ */
+declare function useOverlayServiceState(): OverlayContextValue;
+/**
+ * Run an async operation while showing an overlay. Hides on success or
+ * failure (the overlay is dismissed in `finally`, so failures don't leave a
+ * stuck spinner). Mirrors the try/finally pattern Blazor's
+ * `MainContext.SaveAsync` uses around `_overlayService.ShowOverlayAsync` /
+ * `HideOverlayAsync`.
+ */
+declare function runWithOverlayAsync<T>(service: OverlayService | null, options: OverlayOptions, operation: () => Promise<T>): Promise<T>;
+/**
+ * Hook variant of {@link runWithOverlayAsync}. Returns a stable function bound
+ * to the current overlay service. No-op (just runs the op) when no service is
+ * present.
+ */
+declare function useRunWithOverlay(): <T>(options: OverlayOptions, operation: () => Promise<T>) => Promise<T>;
+
+/**
+ * Standalone hook that registers a `beforeunload` handler while the nearest
+ * `MainContext` / `RecordContext` reports `isDirty`.
+ *
+ * **You usually don't need this.** Both `<MainContext>` and `<RecordContext>`
+ * register the warning automatically when they're the top-most context on
+ * the page (controlled via the `warnOnUnsavedChanges` prop, default `true`).
+ * This hook is exported for cases where you want to wire the warning to a
+ * dirty signal that doesn't come from a MainContext (e.g. a `react-hook-form`
+ * `formState.isDirty`) or from a non-top-most context.
+ *
+ * **What this covers:** browser-level navigation — closing the tab, hitting
+ * the back button, refreshing the page, typing a new URL. The browser's
+ * native prompt fires; the message it shows is browser-controlled (you
+ * cannot customize it — security restriction since Chrome 60+).
+ *
+ * **What this does NOT cover:** in-app route changes via `react-router`'s
+ * `<Link>` or `navigate()`. Those don't trigger `beforeunload` because the
+ * page never actually unloads. For soft-nav blocking, use
+ * {@link useUnsavedChangesGuard} from any router's blocker callback (see
+ * its JSDoc for canonical patterns for react-router, TanStack Router,
+ * Wouter, etc.).
+ */
+declare function useUnsavedChangesWarning(): void;
+/**
+ * Headless controller for building a router blocker that prompts the user
+ * before discarding unsaved edits. Bundles the two primitives any soft-nav
+ * guard needs:
+ *
+ * - `isAnyDirty` — reactive boolean tracking whether any registered
+ *   top-most {@link MainContext} / {@link RecordContext} on the page is
+ *   dirty (read-through to {@link useIsAnyDirty}).
+ * - `warn` — async function that opens the framework confirmation dialog
+ *   and resolves `true` if the user confirmed discarding the edits,
+ *   `false` if they cancelled (read-through to
+ *   {@link useWarnAboutUnsavedChanges}).
+ *
+ * Router-agnostic — this package has zero router dependencies. Pair it
+ * with whichever router blocker your app uses:
+ *
+ * **react-router-dom (data router):** use the pre-built
+ * `<RouterUnsavedChangesGuard>` from `@powerportalspro/react-fluent` — it
+ * wraps this hook + react-router's `useBlocker`. Or roll your own:
+ *
+ * ```tsx
+ * import { useBlocker } from 'react-router-dom';
+ * function MyGuard() {
+ *   const guard = useUnsavedChangesGuard();
+ *   const blocker = useBlocker(
+ *     ({ currentLocation, nextLocation }) =>
+ *       guard.isAnyDirty &&
+ *       currentLocation.pathname !== nextLocation.pathname,
+ *   );
+ *   useEffect(() => {
+ *     if (blocker.state !== 'blocked') return;
+ *     let cancelled = false;
+ *     (async () => {
+ *       const proceed = await guard.warn();
+ *       if (cancelled) return;
+ *       if (proceed) blocker.proceed();
+ *       else blocker.reset();
+ *     })();
+ *     return () => { cancelled = true; };
+ *   }, [blocker, guard]);
+ *   return null;
+ * }
+ * ```
+ *
+ * **TanStack Router:** use `useBlocker({ blockerFn })`. The blocker fn
+ * returns `true` to allow the navigation, `false` to block. Pump the
+ * `warn` result through inverted:
+ *
+ * ```tsx
+ * import { useBlocker } from '@tanstack/react-router';
+ * function MyGuard() {
+ *   const guard = useUnsavedChangesGuard();
+ *   useBlocker({
+ *     blockerFn: async () => {
+ *       if (!guard.isAnyDirty) return true;       // allow
+ *       return await guard.warn();                // user choice
+ *     },
+ *   });
+ *   return null;
+ * }
+ * ```
+ *
+ * **Wouter:** doesn't ship a blocker API. Hand-roll by intercepting
+ * `<Link>` clicks at the app shell — call `event.preventDefault()` and
+ * route through `guard.warn()` before calling `navigate(to)`.
+ *
+ * **Next.js App Router:** `router.events` is gone in the App Router; the
+ * community pattern is to intercept `<Link>` clicks similar to Wouter.
+ * Same flow with `guard.warn()`.
+ *
+ * Same-pathname navigations (search-param tweaks, `replace: true` to the
+ * current URL) should not be blocked — the user isn't actually leaving
+ * the page. The react-router-dom guard above filters those out via the
+ * `currentLocation.pathname !== nextLocation.pathname` check; the TanStack
+ * blocker fn can do the equivalent using its passed-in location args.
+ */
+interface UnsavedChangesGuardController {
+    /**
+     * Reactive — `true` when at least one top-most
+     * {@link MainContext} / {@link RecordContext} registered with the page's
+     * {@link UnsavedChangesRegistry} reports dirty. Subscribes via
+     * {@link useSyncExternalStore} so it re-renders the calling component
+     * exactly when the aggregate flips.
+     */
+    readonly isAnyDirty: boolean;
+    /**
+     * Opens the framework's "discard your changes?" confirmation dialog
+     * and resolves `true` if the user confirmed proceeding (discarding
+     * pending edits), `false` if they cancelled (staying on the page).
+     * Stable identity across renders when the underlying dialog service
+     * / localizer haven't changed, so it's safe to put in effect deps.
+     */
+    readonly warn: () => Promise<boolean>;
+}
+declare function useUnsavedChangesGuard(): UnsavedChangesGuardController;
+
+/**
+ * Source of unsaved-changes state on the page. Each topmost
+ * {@link MainContext} / {@link RecordContext} registers one of these so a
+ * page-wide guard (browser beforeunload, router-blocker) can answer "is
+ * anything on this page dirty?" without having to walk every framework
+ * subtree itself.
+ *
+ * Nested contexts don't register — their dirty state already bubbles up
+ * to the topmost MainContext through the existing
+ * {@link MainContextValue.registerDescendant} plumbing, so registering
+ * nested contexts here would double-count.
+ */
+interface UnsavedChangesReporter {
+    /**
+     * Snapshot getter — invoked synchronously by the registry on every
+     * subscriber notification. Read-through to the reporter's live
+     * `isDirty` so subscribers see the latest aggregate without needing to
+     * re-register on every state flip.
+     */
+    readonly isDirty: () => boolean;
+}
+/**
+ * App-wide registry of {@link UnsavedChangesReporter}s. Owned by
+ * {@link PowerPortalsProProvider}; consumed by:
+ *
+ * - The auto-registration effect inside topmost
+ *   {@link MainContext} / {@link RecordContext}, which adds a reporter on
+ *   mount + removes it on unmount.
+ * - `<RouterUnsavedChangesGuard>` (in `@powerportalspro/react-fluent`),
+ *   which subscribes via {@link useIsAnyDirty} and gates `useBlocker` on
+ *   the aggregate.
+ *
+ * Router-agnostic by design — the registry knows nothing about
+ * react-router, history, or navigation events. That coupling lives in
+ * the optional UI package so consumers using a different router (or
+ * none at all) aren't forced into a dependency they don't need.
+ */
+interface UnsavedChangesRegistry {
+    /**
+     * Add a reporter to the registry. Returns the deregister function;
+     * call it in the same effect's cleanup so the reporter doesn't outlive
+     * the component that owns it.
+     */
+    readonly register: (reporter: UnsavedChangesReporter) => () => void;
+    /**
+     * Subscribe to "the set of dirty reporters might have changed" events.
+     * Fires when reporters are added or removed, AND when a registered
+     * reporter's wrapping {@link MainContext}'s `isDirty` flips (the
+     * reporter's `isDirty` getter closes over the live value).
+     *
+     * Shape compatible with {@link useSyncExternalStore} so the consuming
+     * hook ({@link useIsAnyDirty}) can use it directly.
+     */
+    readonly subscribe: (listener: () => void) => () => void;
+    /**
+     * Walks every registered reporter and returns `true` as soon as one
+     * reports dirty. Used as `getSnapshot` for {@link useSyncExternalStore}
+     * and called imperatively from the beforeunload handler.
+     */
+    readonly isAnyDirty: () => boolean;
+    /**
+     * Forces a notification fire — used by topmost MainContexts after
+     * their internal `isDirty` aggregate changes, so subscribers re-read
+     * the registry's `isAnyDirty()` and pick up the new value. Without
+     * this, the registry would only notify on register/deregister and
+     * stay silent through the user's actual edits.
+     */
+    readonly notifyDirtyChanged: () => void;
+}
+interface UnsavedChangesRegistryProviderProps {
+    children: ReactNode;
+}
+/**
+ * Mounts an {@link UnsavedChangesRegistry} for its subtree. Auto-mounted
+ * by {@link PowerPortalsProProvider}; consumers don't normally render it
+ * directly.
+ */
+declare function UnsavedChangesRegistryProvider({ children }: UnsavedChangesRegistryProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Returns the nearest ancestor {@link UnsavedChangesRegistry}, or `null`
+ * when none is mounted. Framework components ({@link MainContext}) use
+ * this to opt into reporting their dirty state; guard components
+ * ({@code RouterUnsavedChangesGuard}) use {@link useIsAnyDirty} which
+ * already null-checks internally.
+ */
+declare function useUnsavedChangesRegistry(): UnsavedChangesRegistry | null;
+/**
+ * Reactive read of "is anything on this page dirty?" — wraps
+ * {@link useSyncExternalStore} against the surrounding
+ * {@link UnsavedChangesRegistry}. Returns `false` when no registry is
+ * mounted (e.g. a tree that hasn't been wrapped in
+ * {@link PowerPortalsProProvider} yet) so guard components can default
+ * to "don't block" rather than throw.
+ *
+ * Use this from any component that wants to react to page-wide unsaved
+ * state — typically the router-blocker guard, but also custom dirty
+ * indicators in app chrome.
+ */
+declare function useIsAnyDirty(): boolean;
+
+/**
+ * A single column's validator. Returns the list of error messages produced by
+ * the current value (empty list = valid). Sync or async — async validators
+ * run sequentially during {@link ValidationContextValue.validateAll}.
+ *
+ * Implementations must read whatever state they need (current value, required
+ * flag, metadata) at call time — typically from refs — because the validator
+ * is invoked from outside the registering component's render cycle.
+ */
+type ColumnValidator = () => string[] | Promise<string[]>;
+/**
+ * Per-form-scope validation registry. One instance per logical form scope
+ * (auto-mounted by `<RecordContext>`); edit components below it register
+ * their validators and read back any errors.
+ *
+ * Reads happen via {@link useColumnValidationErrors} — that's how edit
+ * components subscribe to "do I have errors right now?" without re-rendering
+ * on every other column's transition.
+ */
+interface ValidationContextValue {
+    /**
+     * Register a column's validator. Returns the unregister function. The
+     * recommended idiom is a `useEffect` whose cleanup unregisters; on column
+     * rename or unmount the registration is replaced cleanly.
+     */
+    readonly register: (columnName: string, validator: ColumnValidator) => () => void;
+    /** Run a single column's validator and update its error state. */
+    readonly validateColumn: (columnName: string) => Promise<void>;
+    /**
+     * Run every registered validator and update all error states. Returns
+     * `true` when nothing failed. Used by save flows (e.g. `SaveContextButton`)
+     * to gate a save on overall validity.
+     */
+    readonly validateAll: () => Promise<boolean>;
+    /** Drop all errors. Useful when the underlying record reloads. */
+    readonly clearErrors: () => void;
+    /**
+     * Aggregated validity — `false` if any registered column currently has
+     * errors. Reactive; consumers subscribed via `useValidationContext` re-render
+     * on transitions.
+     */
+    readonly isValid: boolean;
+    /**
+     * Current errors keyed by column logical name. Re-rendered subscribers see
+     * the latest snapshot. Use {@link useColumnValidationErrors} for a
+     * column-scoped read that doesn't churn on unrelated transitions.
+     */
+    readonly errors: ReadonlyMap<string, readonly string[]>;
+}
+/**
+ * Returns the nearest {@link ValidationContextValue}, or `null` when no
+ * provider is mounted. Validation is optional — a form rendered outside a
+ * `<RecordContext>` (or anywhere without an explicit `<ValidationProvider>`)
+ * just doesn't run validators.
+ */
+declare function useValidationContext(): ValidationContextValue | null;
+/**
+ * Returns the current error messages for a single column (empty array if
+ * valid; `undefined` if no validation provider is mounted). Edit components
+ * call this to drive their inline error display.
+ */
+declare function useColumnValidationErrors(columnName: string): readonly string[] | undefined;
+/**
+ * Mounts a fresh validation scope for descendants. `<RecordContext>`
+ * auto-mounts one — manual use is for edge cases (e.g. a non-record form).
+ */
+declare function ValidationProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare const VERSION = "0.1.0";
+
+export { ASP_NET_CULTURE_COOKIE, type AuthState, AuthStatus, AuthorizedView, type AuthorizedViewProps, type ColumnValidator, type ConfirmationDialogOptions, type CreateLocalizerOptions, DEFAULT_URL_LOCALE_PATTERN, DefaultLocalizerProvider, type DefaultLocalizerProviderProps, type DialogOptions, type DialogResult, type DialogService, DialogServiceProvider, type EnvironmentFileSettingsCache, InMemoryEnvironmentFileSettingsCache, InMemoryTableMetadataCache, InMemoryViewMetadataCache, InMemoryViewsForTableCache, LocaleProvider, type LocaleProviderProps, type LocaleState, type LocalizationPrefetcher, type Localizer, LocalizerProvider, LookupRecordContext, type LookupRecordContextProps, MainContext, type MainContextDescendant, type MainContextProps, MainContextProvider, type MainContextValue, type OverlayInstance, type OverlayOptions, type OverlayService, OverlayServiceProvider, PowerPortalsProContext, type PowerPortalsProContextValue, PowerPortalsProProvider, type PowerPortalsProProviderProps, type QueryResult, QueryStatus, RecordContext, type RecordContextProps, type RecordContextValue, type TableMetadataCache, type UnsavedChangesGuardController, type UnsavedChangesRegistry, UnsavedChangesRegistryProvider, type UnsavedChangesRegistryProviderProps, type UnsavedChangesReporter, type UseAuthResult, type UseEnvironmentFileSettingsOptions, type UseFetchRecordsOptions, type UseGridDataOptions, type UseRecordOptions, type UseSupportedLocalesOptions, type UseTableMetadataOptions, type UseTablePermissionsOptions, type UseViewDataSourceOptions, type UseViewMetadataOptions, type UseViewsForTableOptions, VERSION, type ValidationContextValue, ValidationProvider, type ViewDataSource, type ViewDataSourceHighlight, type ViewMetadataCache, type ViewsForTableCache, createLocalizer, detectLocale, flattenStrings, getAspNetCultureCookie, getLocaleFromUrlPath, interpolate, resolveLocalizationUrl, runWithOverlayAsync, setAspNetCultureCookie, useAuth, useColumnMetadata, useColumnValidationErrors, useDialogService, useEnvironmentFileSettings, useFetchRecords, useGridData, useIsAnyDirty, useLocale, useLocalization, useLocalizationLoaded, useLocalizationPrefetcher, useLocalizer, useMainContext, useOverlayForTarget, useOverlayService, useOverlayServiceState, usePowerPortalsPro, usePrefixedT, useQueryParam, useRecord, useRecordContext, useRecordContextOptional, useRunWithOverlay, useSupportedLocales, useT, useTableMetadata, useTablePermissions, useUnsavedChangesGuard, useUnsavedChangesRegistry, useUnsavedChangesWarning, useValidationContext, useViewDataSource, useViewMetadata, useViewsForTable, useWarnAboutUnsavedChanges, warnAboutUnsavedChangesAsync };