@wildo-ai/saas-frontend-lib 1.0.1

package/dist/esm/core/loading/LoadingContext.js

@@ -0,0 +1,267 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Loading Context — Event-Driven State Aggregator
+ *
+ * Central loading state management. Subscribes to loading events on the EventBus
+ * and maintains aggregate state for UI consumption.
+ *
+ * Architecture: EventBus → LoadingProvider (useReducer) → Context → Hooks
+ *
+ * Tier 1 (APPLICATION): Gates entire app — init, language change, org switch.
+ * Tier 2 (COMPONENT): Per-scope — resource lists, detail views, etc.
+ *
+ * @see .cursor/plans/loading-system-architecture.md
+ *
+ * ARCHITECTURE NOTE:
+ * This file exports the Provider component and context. Hooks are in separate files
+ * (useAppLoading.ts, useComponentLoading.ts, useLoading.ts) for React Fast Refresh
+ * compatibility — mixing components and hooks causes HMR invalidation loops.
+ */
+import { createContext, useReducer, useEffect, useRef, useCallback, useMemo } from 'react';
+import { frontendEventBus } from '../../core/events/event-bus.frontend.service.js';
+import { FrontendEvents } from '../../core/events/events.frontend.schemas.js';
+import { ResourcePrimaryScope } from '@wildo-ai/saas-models';
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+import { LoadingTier, LoadingPhase, } from './loading-types.frontend.schemas.js';
+import { buildLoadingScopeKey } from './loading-scope.frontend.utils.js';
+const logger = LoggerFrontendService.getLogger();
+const logDebug = logger.debugByType('LoadingContext');
+logger.setDebugTypeLogging('LoadingContext', false);
+// ─── Internal State ─────────────────────────────────────────────────────────
+var LoadingActionType;
+(function (LoadingActionType) {
+    LoadingActionType["APP_LOADING_START"] = "APP_LOADING_START";
+    LoadingActionType["APP_LOADING_END"] = "APP_LOADING_END";
+    LoadingActionType["COMPONENT_LOADING_START"] = "COMPONENT_LOADING_START";
+    LoadingActionType["COMPONENT_LOADING_END"] = "COMPONENT_LOADING_END";
+})(LoadingActionType || (LoadingActionType = {}));
+const initialState = {
+    appLoadingSources: new Map(),
+    componentLoadingMap: new Map(),
+};
+/**
+ * IMPORTANT: Returns new Map instances on every mutation.
+ * React detects state changes by reference equality — mutating a Map in place
+ * returns the same reference and triggers no re-render.
+ */
+function loadingReducer(state, action) {
+    switch (action.type) {
+        case LoadingActionType.APP_LOADING_START: {
+            const next = new Map(state.appLoadingSources);
+            next.set(action.identifier, action.source);
+            return { ...state, appLoadingSources: next };
+        }
+        case LoadingActionType.APP_LOADING_END: {
+            const next = new Map(state.appLoadingSources);
+            next.delete(action.identifier);
+            return { ...state, appLoadingSources: next };
+        }
+        case LoadingActionType.COMPONENT_LOADING_START: {
+            const next = new Map(state.componentLoadingMap);
+            const existing = next.get(action.scopeKey);
+            const activeCount = (existing?.activeCount ?? 0) + 1;
+            next.set(action.scopeKey, {
+                hasLoadedOnce: existing?.hasLoadedOnce ?? false,
+                isLoading: true,
+                phase: action.phase,
+                activeCount,
+            });
+            return { ...state, componentLoadingMap: next };
+        }
+        case LoadingActionType.COMPONENT_LOADING_END: {
+            const next = new Map(state.componentLoadingMap);
+            const existing = next.get(action.scopeKey);
+            if (!existing)
+                return state;
+            const activeCount = Math.max(0, existing.activeCount - 1);
+            next.set(action.scopeKey, {
+                hasLoadedOnce: true,
+                isLoading: activeCount > 0,
+                phase: existing.phase,
+                activeCount,
+            });
+            return { ...state, componentLoadingMap: next };
+        }
+        default:
+            return state;
+    }
+}
+// ─── LoadedOnce LRU Cache ───────────────────────────────────────────────────
+/**
+ * Tracks data contexts that have been successfully loaded and rendered.
+ * Used to distinguish initial loads from refreshes on re-visit.
+ *
+ * LRU eviction: oldest entries are evicted when cache exceeds maxEntries.
+ * Map insertion order is exploited — delete+re-set moves entry to end.
+ */
+class LoadedOnceCache {
+    cache = new Map();
+    maxEntries = 200;
+    has(scopeKey, refreshThresholdMs = 5 * 60 * 1000) {
+        const entry = this.cache.get(scopeKey);
+        if (!entry)
+            return false;
+        return (Date.now() - entry.lastRenderedAt) < refreshThresholdMs;
+    }
+    set(scopeKey) {
+        this.cache.delete(scopeKey);
+        this.cache.set(scopeKey, { lastRenderedAt: Date.now() });
+        if (this.cache.size > this.maxEntries) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+/**
+ * @internal Use useLoading(), useAppLoading(), or useComponentLoading() hooks
+ */
+export const LoadingContext = createContext(undefined);
+// ─── Provider ───────────────────────────────────────────────────────────────
+export const LoadingProvider = ({ children }) => {
+    const [state, dispatch] = useReducer(loadingReducer, initialState);
+    const loadedOnceCacheRef = useRef(new LoadedOnceCache());
+    useEffect(() => {
+        const identifiers = Array.from(state.appLoadingSources.keys());
+        logDebug(`App loading state: ${state.appLoadingSources.size > 0 ? 'loading' : 'ready'} [${identifiers.join(', ') || 'none'}]`);
+    }, [state.appLoadingSources]);
+    // ── Subscribe to loading events ──────────────────────────────────────────
+    useEffect(() => {
+        const unsubscribes = [];
+        unsubscribes.push(frontendEventBus.on(FrontendEvents.LOADING_RESOURCE_START, (payload) => {
+            const scopeKey = buildLoadingScopeKey({
+                resourceType: payload.resourceType,
+                operation: payload.operationIdentifier,
+                discriminator: payload.optionalDiscriminator,
+            });
+            const tier = payload.tier ?? LoadingTier.COMPONENT;
+            const phase = payload.phase ?? LoadingPhase.INITIAL;
+            if (tier === LoadingTier.APPLICATION) {
+                logDebug(`APP_LOADING_START resource:${scopeKey}`);
+                dispatch({ type: LoadingActionType.APP_LOADING_START, identifier: scopeKey, source: { identifier: scopeKey, tier, startedAt: Date.now() } });
+            }
+            else {
+                dispatch({ type: LoadingActionType.COMPONENT_LOADING_START, scopeKey, phase });
+            }
+        }));
+        unsubscribes.push(frontendEventBus.on(FrontendEvents.LOADING_RESOURCE_END, (payload) => {
+            const scopeKey = buildLoadingScopeKey({
+                resourceType: payload.resourceType,
+                operation: payload.operationIdentifier,
+                discriminator: payload.optionalDiscriminator,
+            });
+            const tier = payload.tier ?? LoadingTier.COMPONENT;
+            if (tier === LoadingTier.APPLICATION) {
+                logDebug(`APP_LOADING_END resource:${scopeKey}`);
+                dispatch({ type: LoadingActionType.APP_LOADING_END, identifier: scopeKey });
+            }
+            else {
+                dispatch({ type: LoadingActionType.COMPONENT_LOADING_END, scopeKey });
+            }
+        }));
+        unsubscribes.push(frontendEventBus.on(FrontendEvents.LOADING_CUSTOM_START, (payload) => {
+            const tier = payload.tier ?? LoadingTier.COMPONENT;
+            const phase = payload.phase ?? LoadingPhase.INITIAL;
+            if (tier === LoadingTier.APPLICATION) {
+                logDebug(`APP_LOADING_START custom:${payload.identifier}`);
+                dispatch({ type: LoadingActionType.APP_LOADING_START, identifier: payload.identifier, source: { identifier: payload.identifier, tier, startedAt: Date.now() } });
+            }
+            else {
+                dispatch({ type: LoadingActionType.COMPONENT_LOADING_START, scopeKey: `custom:${payload.identifier}`, phase });
+            }
+        }));
+        unsubscribes.push(frontendEventBus.on(FrontendEvents.LOADING_CUSTOM_END, (payload) => {
+            const tier = payload.tier ?? LoadingTier.COMPONENT;
+            if (tier === LoadingTier.APPLICATION) {
+                logDebug(`APP_LOADING_END custom:${payload.identifier}`);
+                dispatch({ type: LoadingActionType.APP_LOADING_END, identifier: payload.identifier });
+            }
+            else {
+                dispatch({ type: LoadingActionType.COMPONENT_LOADING_END, scopeKey: `custom:${payload.identifier}` });
+            }
+        }));
+        return () => unsubscribes.forEach(unsub => unsub());
+    }, []);
+    // ── Global clear events — invalidate hasLoadedOnce cache ─────────────────
+    useEffect(() => {
+        const unsubscribes = [];
+        unsubscribes.push(frontendEventBus.on(FrontendEvents.PRIMARY_SCOPE_CHANGED, (payload) => {
+            if (payload.scopeLevel === ResourcePrimaryScope.ORGANIZATIONS) {
+                loadedOnceCacheRef.current.clear();
+            }
+        }));
+        unsubscribes.push(frontendEventBus.on(FrontendEvents.AUTH_LOGOUT_REQUIRED, () => {
+            loadedOnceCacheRef.current.clear();
+        }));
+        unsubscribes.push(frontendEventBus.on(FrontendEvents.WHOLE_APP_REFRESH, () => {
+            loadedOnceCacheRef.current.clear();
+        }));
+        return () => unsubscribes.forEach(unsub => unsub());
+    }, []);
+    // ── New API methods ──────────────────────────────────────────────────────
+    const getComponentLoadingState = useCallback((scopeKey) => state.componentLoadingMap.get(scopeKey), [state.componentLoadingMap]);
+    const hasLoadedOnce = useCallback((scopeKey, refreshThresholdMs) => loadedOnceCacheRef.current.has(scopeKey, refreshThresholdMs), []);
+    const markRendered = useCallback((scopeKey) => loadedOnceCacheRef.current.set(scopeKey), []);
+    const fireLoading = useCallback((scope, options) => {
+        const isCustom = !!scope.customIdentifier;
+        if (isCustom) {
+            frontendEventBus.emit(FrontendEvents.LOADING_CUSTOM_START, {
+                identifier: scope.customIdentifier,
+                data: undefined,
+                tier: options?.tier,
+                phase: options?.phase,
+            });
+        }
+        else {
+            frontendEventBus.emit(FrontendEvents.LOADING_RESOURCE_START, {
+                resourceType: scope.resourceType ?? '',
+                operationIdentifier: scope.operation ?? '',
+                optionalDiscriminator: scope.discriminator,
+                contextResourceIdentifiers: {},
+                tier: options?.tier,
+                phase: options?.phase,
+            });
+        }
+    }, []);
+    const endLoading = useCallback((scope, options) => {
+        const isCustom = !!scope.customIdentifier;
+        if (isCustom) {
+            frontendEventBus.emit(FrontendEvents.LOADING_CUSTOM_END, {
+                identifier: scope.customIdentifier,
+                data: undefined,
+                tier: options?.tier,
+            });
+        }
+        else {
+            frontendEventBus.emit(FrontendEvents.LOADING_RESOURCE_END, {
+                resourceType: scope.resourceType ?? '',
+                operationIdentifier: scope.operation ?? '',
+                optionalDiscriminator: scope.discriminator,
+                contextResourceIdentifiers: {},
+                tier: options?.tier,
+            });
+        }
+    }, []);
+    // ── Build context value ──────────────────────────────────────────────────
+    const value = useMemo(() => ({
+        isAppLoading: state.appLoadingSources.size > 0,
+        appLoadingSources: Array.from(state.appLoadingSources.values()),
+        getComponentLoadingState,
+        hasLoadedOnce,
+        markRendered,
+        fireLoading,
+        endLoading,
+    }), [
+        state.appLoadingSources,
+        getComponentLoadingState,
+        hasLoadedOnce,
+        markRendered,
+        fireLoading,
+        endLoading,
+    ]);
+    return _jsx(LoadingContext.Provider, { value: value, children: children });
+};
+//# sourceMappingURL=LoadingContext.js.map

package/dist/esm/core/loading/LoadingContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadingContext.js","sourceRoot":"","sources":["../../../../src/core/loading/LoadingContext.tsx"],"names":[],"mappings":"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"}

package/dist/esm/core/loading/LoadingGate.d.ts

@@ -0,0 +1,38 @@
+import React from 'react';
+import type { ReactNode } from 'react';
+import type { LoadingScope, LoadingPolicy, LoadingRenderContext, LoadingErrorContext } from './loading-types.frontend.schemas.js';
+export interface LoadingGateProps {
+    /** Loading scopes to wait for — each scope is tracked independently */
+    loadingScopes?: LoadingScope[];
+    /** i18n dot-path keys that must be loaded before rendering children */
+    i18nKeys?: string[];
+    /** Custom readiness signals — all must be `true` for the gate to open */
+    readiness?: Array<{
+        id: string;
+        isReady: boolean;
+    }>;
+    /** Loading policy determining visual treatment per phase */
+    policy?: LoadingPolicy;
+    /** Custom loading renderer — called for CUSTOM and SKELETON treatments */
+    renderLoading?: (context: LoadingRenderContext) => ReactNode;
+    /** Error renderer — called on timeout or loading error */
+    renderError?: (context: LoadingErrorContext) => ReactNode;
+    /** Timeout in ms after which the gate shows an error state. Default: no timeout. */
+    timeoutMs?: number;
+    children: ReactNode;
+}
+/**
+ * LoadingGate — Universal gating component for loading dependencies.
+ *
+ * Waits for all specified dependencies (loading scopes, i18n keys, custom
+ * readiness signals) before rendering children. While waiting, renders the
+ * appropriate visual treatment based on the loading policy.
+ *
+ * The gate is a utility tool, not a policy enforcer — presets own their
+ * loading behavior. `resolveLoadingPolicy()` resolves category defaults;
+ * explicit policy props override them.
+ *
+ * @see loading-system-architecture.md §2.5
+ */
+export declare function LoadingGate({ loadingScopes, i18nKeys, readiness, policy, renderLoading, renderError, timeoutMs, children, }: LoadingGateProps): React.JSX.Element;
+//# sourceMappingURL=LoadingGate.d.ts.map

package/dist/esm/core/loading/LoadingGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadingGate.d.ts","sourceRoot":"","sources":["../../../../src/core/loading/LoadingGate.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA2D,MAAM,OAAO,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,mBAAmB,EAAyB,MAAM,kCAAkC,CAAC;AAStJ,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,yEAAyE;IACzE,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpD,4DAA4D;IAC5D,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,SAAS,CAAC;IAC7D,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,SAAS,CAAC;IAC1D,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,EAC1B,aAAa,EACb,QAAQ,EACR,SAAS,EACT,MAAM,EACN,aAAa,EACb,WAAW,EACX,SAAS,EACT,QAAQ,GACT,EAAE,gBAAgB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAmLtC"}

package/dist/esm/core/loading/LoadingGate.js

@@ -0,0 +1,145 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { LoadingTreatment, LoadingPhase } from './loading-types.frontend.schemas.js';
+import { LoadingContext } from './LoadingContext.js';
+import { buildLoadingScopeKey } from './loading-scope.frontend.utils.js';
+import { LoadingSpinner } from '../../components/feedback/loading-spinner.js';
+import { LoadingOverlay } from '../../components/feedback/loading-overlay.js';
+import { Skeleton } from '../../components/feedback/skeleton.js';
+import { useI18n } from '../../core/i18n/useI18n.js';
+/**
+ * LoadingGate — Universal gating component for loading dependencies.
+ *
+ * Waits for all specified dependencies (loading scopes, i18n keys, custom
+ * readiness signals) before rendering children. While waiting, renders the
+ * appropriate visual treatment based on the loading policy.
+ *
+ * The gate is a utility tool, not a policy enforcer — presets own their
+ * loading behavior. `resolveLoadingPolicy()` resolves category defaults;
+ * explicit policy props override them.
+ *
+ * @see loading-system-architecture.md §2.5
+ */
+export function LoadingGate({ loadingScopes, i18nKeys, readiness, policy, renderLoading, renderError, timeoutMs, children, }) {
+    if (process.env.NODE_ENV !== 'production' && timeoutMs && !renderError) {
+        console.warn('[LoadingGate] timeoutMs is set without renderError — timeout will have no visible effect. Provide renderError to surface timeout failures.');
+    }
+    const context = useContext(LoadingContext);
+    if (!context)
+        throw new Error('LoadingGate must be used within a LoadingProvider');
+    const i18nDeps = useMemo(() => ({ keys: i18nKeys ?? [] }), [i18nKeys]);
+    const { requestKeys, isKeyLoaded, isReady } = useI18n(i18nDeps);
+    // ── Loading scope states ─────────────────────────────────────────────────
+    const scopeStates = useMemo(() => {
+        if (!loadingScopes?.length)
+            return [];
+        return loadingScopes.map(scope => {
+            const key = buildLoadingScopeKey(scope);
+            const state = context.getComponentLoadingState(key);
+            const isLoading = state?.isLoading ?? false;
+            const hasLoadedOnce = context.hasLoadedOnce(key);
+            return { scope, key, isLoading, hasLoadedOnce };
+        });
+    }, [loadingScopes, context]);
+    const loadingScopesReady = scopeStates.length === 0 || scopeStates.every(s => !s.isLoading);
+    // ── i18n key readiness ──────────────────────────────────────────────────
+    useEffect(() => {
+        if (i18nKeys?.length) {
+            requestKeys(i18nKeys);
+        }
+    }, [i18nKeys, requestKeys]);
+    const i18nReady = !i18nKeys?.length || i18nKeys.every(k => isKeyLoaded(k));
+    // ── Custom readiness signals ────────────────────────────────────────────
+    const customReady = !readiness?.length || readiness.every(r => r.isReady);
+    // ── Combined readiness ──────────────────────────────────────────────────
+    const allReady = loadingScopesReady && i18nReady && customReady;
+    // ── Determine loading phase ─────────────────────────────────────────────
+    const phase = useMemo(() => {
+        if (scopeStates.some(s => s.isLoading && !s.hasLoadedOnce))
+            return LoadingPhase.INITIAL;
+        if (scopeStates.some(s => s.isLoading && s.hasLoadedOnce))
+            return LoadingPhase.REFRESH;
+        return LoadingPhase.INITIAL;
+    }, [scopeStates]);
+    // ── Timeout handling ────────────────────────────────────────────────────
+    const [timedOut, setTimedOut] = useState(false);
+    const loadingStartRef = useRef(null);
+    useEffect(() => {
+        if (allReady) {
+            loadingStartRef.current = null;
+            setTimedOut(false);
+            return;
+        }
+        if (!loadingStartRef.current) {
+            loadingStartRef.current = Date.now();
+        }
+        if (!timeoutMs)
+            return;
+        const elapsed = Date.now() - loadingStartRef.current;
+        const remaining = timeoutMs - elapsed;
+        if (remaining <= 0) {
+            setTimedOut(true);
+            return;
+        }
+        const timer = setTimeout(() => setTimedOut(true), remaining);
+        return () => clearTimeout(timer);
+    }, [allReady, timeoutMs]);
+    // ── Mark rendered on first ready ────────────────────────────────────────
+    const hasMarkedRef = useRef(false);
+    useEffect(() => {
+        if (allReady && !hasMarkedRef.current && loadingScopes?.length) {
+            hasMarkedRef.current = true;
+            for (const scope of loadingScopes) {
+                context.markRendered(buildLoadingScopeKey(scope));
+            }
+        }
+        if (!allReady) {
+            hasMarkedRef.current = false;
+        }
+    }, [allReady, loadingScopes, context]);
+    // ── Timeout error state ─────────────────────────────────────────────────
+    if (timedOut && renderError) {
+        const failedScopes = scopeStates.filter(s => s.isLoading).map(s => s.scope);
+        return (_jsx(_Fragment, { children: renderError({
+                failedScopes,
+                reason: 'timeout',
+                retry: () => {
+                    setTimedOut(false);
+                    loadingStartRef.current = Date.now();
+                },
+            }) }));
+    }
+    // ── Ready — render children ─────────────────────────────────────────────
+    if (allReady) {
+        return _jsx(_Fragment, { children: children });
+    }
+    // ── Not ready — render loading treatment ────────────────────────────────
+    const treatment = phase === LoadingPhase.REFRESH
+        ? (policy?.refresh ?? LoadingTreatment.OPACITY_OVERLAY)
+        : (policy?.initialLoad ?? LoadingTreatment.SKELETON);
+    const renderContext = {
+        phase,
+        scope: scopeStates[0]?.scope ?? { customIdentifier: 'loading-gate' },
+    };
+    switch (treatment) {
+        case LoadingTreatment.CUSTOM:
+            return _jsx(_Fragment, { children: renderLoading?.(renderContext) ?? children });
+        case LoadingTreatment.SKELETON:
+            if (renderLoading)
+                return _jsx(_Fragment, { children: renderLoading(renderContext) });
+            return (_jsxs("div", { role: "status", "aria-live": "polite", className: "space-y-field", children: [_jsx("span", { className: "sr-only", children: "Loading" }), _jsx(Skeleton, { className: "h-6 w-1/3", "aria-hidden": "true" }), _jsx(Skeleton, { className: "h-4 w-full", "aria-hidden": "true" }), _jsx(Skeleton, { className: "h-4 w-2/3", "aria-hidden": "true" })] }));
+        case LoadingTreatment.SPINNER:
+            return (_jsx("div", { className: "flex items-center justify-center py-8", children: _jsx(LoadingSpinner, { size: 32 }) }));
+        case LoadingTreatment.OPACITY_OVERLAY:
+            return (_jsxs("div", { className: "relative", children: [children, _jsx(LoadingOverlay, {})] }));
+        case LoadingTreatment.HIDDEN:
+            return _jsx("div", { style: { display: 'none' }, children: children });
+        case LoadingTreatment.INVISIBLE:
+            return _jsx("div", { style: { visibility: 'hidden' }, children: children });
+        case LoadingTreatment.FULL_SCREEN:
+            return (_jsx("div", { className: "fixed inset-0 z-50 flex items-center justify-center bg-background/80", children: _jsx(LoadingSpinner, { size: 48 }) }));
+        default:
+            return _jsx(_Fragment, { children: children });
+    }
+}
+//# sourceMappingURL=LoadingGate.js.map

package/dist/esm/core/loading/LoadingGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadingGate.js","sourceRoot":"","sources":["../../../../src/core/loading/LoadingGate.tsx"],"names":[],"mappings":"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"}

package/dist/esm/core/loading/loading-policy.frontend.schemas.d.ts

@@ -0,0 +1,15 @@
+import { FrontendComponentCategory } from '@wildo-ai/presets-components-models';
+import type { LoadingPolicy } from './loading-types.frontend.schemas.js';
+/**
+ * Day-1 category defaults for loading policy resolution.
+ *
+ * Categories NOT listed (`APP_LAYOUTS`, `LOW_LEVEL_COMPONENTS`, `GUIDANCE`,
+ * `PROGRESSION`, `LIFECYCLE`) have **no default** — their presets either
+ * don't load data (primitives) or have specialized loading flows.
+ * Presets in those categories must provide explicit overrides when using
+ * `resolveLoadingPolicy`; omitting the category is intentional.
+ *
+ * @see loading-system-architecture.md §2.5
+ */
+export declare const CATEGORY_LOADING_DEFAULTS: Partial<Record<FrontendComponentCategory, Partial<LoadingPolicy>>>;
+//# sourceMappingURL=loading-policy.frontend.schemas.d.ts.map

package/dist/esm/core/loading/loading-policy.frontend.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-policy.frontend.schemas.d.ts","sourceRoot":"","sources":["../../../../src/core/loading/loading-policy.frontend.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAGtE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,CAAC,MAAM,CAAC,yBAAyB,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAMxG,CAAC"}

package/dist/esm/core/loading/loading-policy.frontend.schemas.js

@@ -0,0 +1,21 @@
+import { FrontendComponentCategory } from '@wildo-ai/presets-components-models';
+import { LoadingTreatment } from './loading-types.frontend.schemas.js';
+/**
+ * Day-1 category defaults for loading policy resolution.
+ *
+ * Categories NOT listed (`APP_LAYOUTS`, `LOW_LEVEL_COMPONENTS`, `GUIDANCE`,
+ * `PROGRESSION`, `LIFECYCLE`) have **no default** — their presets either
+ * don't load data (primitives) or have specialized loading flows.
+ * Presets in those categories must provide explicit overrides when using
+ * `resolveLoadingPolicy`; omitting the category is intentional.
+ *
+ * @see loading-system-architecture.md §2.5
+ */
+export const CATEGORY_LOADING_DEFAULTS = {
+    [FrontendComponentCategory.RESOURCES_LAYOUTS]: { initialLoad: LoadingTreatment.SKELETON, refresh: LoadingTreatment.OPACITY_OVERLAY },
+    [FrontendComponentCategory.RESOURCES_FIELDS]: { initialLoad: LoadingTreatment.SKELETON, refresh: LoadingTreatment.OPACITY_OVERLAY },
+    [FrontendComponentCategory.HIGH_LEVEL_VIEWS]: { initialLoad: LoadingTreatment.SKELETON, refresh: LoadingTreatment.OPACITY_OVERLAY },
+    [FrontendComponentCategory.APPLICATION_LEVEL_COMPONENTS]: { initialLoad: LoadingTreatment.SKELETON, refresh: LoadingTreatment.HIDDEN },
+    [FrontendComponentCategory.PUBLIC_LAYOUTS]: { initialLoad: LoadingTreatment.SPINNER, refresh: LoadingTreatment.SPINNER },
+};
+//# sourceMappingURL=loading-policy.frontend.schemas.js.map

package/dist/esm/core/loading/loading-policy.frontend.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-policy.frontend.schemas.js","sourceRoot":"","sources":["../../../../src/core/loading/loading-policy.frontend.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAEhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAuE;IAC3G,CAAC,yBAAyB,CAAC,iBAAiB,CAAC,EAAa,EAAE,WAAW,EAAE,gBAAgB,CAAC,QAAQ,EAAG,OAAO,EAAE,gBAAgB,CAAC,eAAe,EAAE;IAChJ,CAAC,yBAAyB,CAAC,gBAAgB,CAAC,EAAc,EAAE,WAAW,EAAE,gBAAgB,CAAC,QAAQ,EAAG,OAAO,EAAE,gBAAgB,CAAC,eAAe,EAAE;IAChJ,CAAC,yBAAyB,CAAC,gBAAgB,CAAC,EAAc,EAAE,WAAW,EAAE,gBAAgB,CAAC,QAAQ,EAAG,OAAO,EAAE,gBAAgB,CAAC,eAAe,EAAE;IAChJ,CAAC,yBAAyB,CAAC,4BAA4B,CAAC,EAAE,EAAE,WAAW,EAAE,gBAAgB,CAAC,QAAQ,EAAG,OAAO,EAAE,gBAAgB,CAAC,MAAM,EAAE;IACvI,CAAC,yBAAyB,CAAC,cAAc,CAAC,EAAiB,EAAE,WAAW,EAAE,gBAAgB,CAAC,OAAO,EAAI,OAAO,EAAE,gBAAgB,CAAC,OAAO,EAAE;CAC1I,CAAC"}

package/dist/esm/core/loading/loading-scope.frontend.utils.d.ts

@@ -0,0 +1,13 @@
+import type { LoadingScope } from './loading-types.frontend.schemas.js';
+/**
+ * Builds a deterministic string key from a LoadingScope.
+ * Used as Map keys in the loading state aggregator.
+ *
+ * Key format:
+ * - Custom: `custom:{identifier}`
+ * - Resource: `{resourceType}:{operation}` or `{resourceType}:{operation}:{discriminator}`
+ *
+ * Consumers must use the same scope shape to match — no fuzzy matching.
+ */
+export declare function buildLoadingScopeKey(scope: LoadingScope): string;
+//# sourceMappingURL=loading-scope.frontend.utils.d.ts.map

package/dist/esm/core/loading/loading-scope.frontend.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-scope.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../src/core/loading/loading-scope.frontend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAErE;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAIhE"}

package/dist/esm/core/loading/loading-scope.frontend.utils.js

@@ -0,0 +1,17 @@
+/**
+ * Builds a deterministic string key from a LoadingScope.
+ * Used as Map keys in the loading state aggregator.
+ *
+ * Key format:
+ * - Custom: `custom:{identifier}`
+ * - Resource: `{resourceType}:{operation}` or `{resourceType}:{operation}:{discriminator}`
+ *
+ * Consumers must use the same scope shape to match — no fuzzy matching.
+ */
+export function buildLoadingScopeKey(scope) {
+    if (scope.customIdentifier)
+        return `custom:${scope.customIdentifier}`;
+    const parts = [scope.resourceType, scope.operation, scope.discriminator].filter(Boolean);
+    return parts.join(':');
+}
+//# sourceMappingURL=loading-scope.frontend.utils.js.map

package/dist/esm/core/loading/loading-scope.frontend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-scope.frontend.utils.js","sourceRoot":"","sources":["../../../../src/core/loading/loading-scope.frontend.utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAmB;IACtD,IAAI,KAAK,CAAC,gBAAgB;QAAE,OAAO,UAAU,KAAK,CAAC,gBAAgB,EAAE,CAAC;IACtE,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACzF,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}