snice 4.29.0 → 4.30.1

package/dist/react/SniceProvider.d.ts

@@ -0,0 +1,71 @@
+import { type ReactNode } from 'react';
+/**
+ * Placard interface — matches src/types/placard.ts
+ * Re-declared here to avoid importing from the vanilla Snice source
+ * (React package should be independently importable)
+ */
+export interface Placard {
+    name: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    tooltip?: string;
+    searchTerms?: string[];
+    hotkeys?: string[];
+    helpUrl?: string;
+    breadcrumbs?: string[];
+    group?: string;
+    parent?: string;
+    order?: number;
+    show?: boolean;
+    visibleOn?: any;
+    attributes?: Record<string, any>;
+}
+/**
+ * Mirrors Snice's @context shape exactly.
+ */
+export interface SniceReactContext {
+    /** User-defined app state */
+    application: Record<string, any>;
+    /** Navigation state */
+    navigation: {
+        route: string;
+        params: Record<string, string>;
+        placards: Placard[];
+    };
+    /** Programmatic navigation */
+    navigate: (path: string) => void;
+    /** Optional context-aware fetcher */
+    fetch?: typeof globalThis.fetch;
+}
+export interface SniceProviderProps {
+    /** Application context object (user state, theme, config, etc.) */
+    context?: Record<string, any>;
+    /** Navigation function — provided by SniceRouter, or your own */
+    navigate?: (path: string) => void;
+    /** Current route pattern */
+    route?: string;
+    /** Current route params */
+    params?: Record<string, string>;
+    /** Registered placards */
+    placards?: Placard[];
+    /** Optional fetch function */
+    fetch?: typeof globalThis.fetch;
+    children: ReactNode;
+}
+/**
+ * Context provider for Snice React integration.
+ * Usable standalone without SniceRouter for simpler apps.
+ */
+export declare function SniceProvider({ context, navigate, route, params, placards, fetch: fetchFn, children, }: SniceProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Returns the full merged Snice context.
+ * Mirrors the shape returned by Snice's @context decorator.
+ */
+export declare function useSniceContext(): SniceReactContext;
+/** Convenience: returns just the navigate function */
+export declare function useNavigate(): (path: string) => void;
+/** Convenience: returns current route params */
+export declare function useParams(): Record<string, string>;
+/** Convenience: returns current matched route pattern */
+export declare function useRoute(): string;

package/dist/react/SniceProvider.js

@@ -0,0 +1,49 @@
+/*!
+ * snice v4.30.0
+ * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
+ * (c) 2024
+ * Released under the MIT License.
+ */
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useMemo, useContext } from 'react';
+
+const SniceCtx = createContext(null);
+/**
+ * Context provider for Snice React integration.
+ * Usable standalone without SniceRouter for simpler apps.
+ */
+function SniceProvider({ context = {}, navigate = () => { }, route = '', params = {}, placards = [], fetch: fetchFn, children, }) {
+    const value = useMemo(() => ({
+        application: context,
+        navigation: { route, params, placards },
+        navigate,
+        ...(fetchFn ? { fetch: fetchFn } : {}),
+    }), [context, navigate, route, params, placards, fetchFn]);
+    return jsx(SniceCtx.Provider, { value: value, children: children });
+}
+/**
+ * Returns the full merged Snice context.
+ * Mirrors the shape returned by Snice's @context decorator.
+ */
+function useSniceContext() {
+    const ctx = useContext(SniceCtx);
+    if (!ctx) {
+        throw new Error('useSniceContext must be used within a <SniceProvider> or <SniceRouter>');
+    }
+    return ctx;
+}
+/** Convenience: returns just the navigate function */
+function useNavigate() {
+    return useSniceContext().navigate;
+}
+/** Convenience: returns current route params */
+function useParams() {
+    return useSniceContext().navigation.params;
+}
+/** Convenience: returns current matched route pattern */
+function useRoute() {
+    return useSniceContext().navigation.route;
+}
+
+export { SniceProvider, useNavigate, useParams, useRoute, useSniceContext };
+//# sourceMappingURL=SniceProvider.js.map

package/dist/react/SniceProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SniceProvider.js","sources":["../../src/react/SniceProvider.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;;;;;;;AA2CA,MAAM,QAAQ,GAAG,aAAa,CAA2B,IAAI,CAAC;AAkB9D;;;AAGG;AACG,SAAU,aAAa,CAAC,EAC5B,OAAO,GAAG,EAAE,EACZ,QAAQ,GAAG,MAAK,EAAE,CAAC,EACnB,KAAK,GAAG,EAAE,EACV,MAAM,GAAG,EAAE,EACX,QAAQ,GAAG,EAAE,EACb,KAAK,EAAE,OAAO,EACd,QAAQ,GACW,EAAA;AACnB,IAAA,MAAM,KAAK,GAAG,OAAO,CACnB,OAAO;AACL,QAAA,WAAW,EAAE,OAAO;AACpB,QAAA,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE;QACvC,QAAQ;AACR,QAAA,IAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;AACvC,KAAA,CAAC,EACF,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CACtD;IAED,OAAOA,GAAA,CAAC,QAAQ,CAAC,QAAQ,EAAA,EAAC,KAAK,EAAE,KAAK,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAqB;AACxE;AAEA;;;AAGG;SACa,eAAe,GAAA;AAC7B,IAAA,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC;IAChC,IAAI,CAAC,GAAG,EAAE;AACR,QAAA,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC;IAC3F;AACA,IAAA,OAAO,GAAG;AACZ;AAEA;SACgB,WAAW,GAAA;AACzB,IAAA,OAAO,eAAe,EAAE,CAAC,QAAQ;AACnC;AAEA;SACgB,SAAS,GAAA;AACvB,IAAA,OAAO,eAAe,EAAE,CAAC,UAAU,CAAC,MAAM;AAC5C;AAEA;SACgB,QAAQ,GAAA;AACtB,IAAA,OAAO,eAAe,EAAE,CAAC,UAAU,CAAC,KAAK;AAC3C;;;;"}

package/dist/react/SniceRouter.d.ts

@@ -0,0 +1,44 @@
+import { type ReactNode, type ReactElement, type ComponentType } from 'react';
+import type { Placard } from './SniceProvider';
+export interface RouteProps {
+    path: string;
+    /** React component OR Snice element tag name (string) */
+    page: ComponentType<any> | string;
+    /** Single guard function */
+    guard?: (context: Record<string, any>, params: Record<string, string>) => boolean | Promise<boolean>;
+    /** Multiple guards (AND logic) */
+    guards?: Array<(context: Record<string, any>, params: Record<string, string>) => boolean | Promise<boolean>>;
+    /** Redirect path if guard rejects */
+    guardRedirect?: string;
+    /** Layout override. Component, string (Snice tag), or false (no layout) */
+    layout?: ComponentType<{
+        children: ReactNode;
+    }> | string | false;
+    /** Page metadata for layouts */
+    placard?: Placard;
+}
+/**
+ * Route definition component. Child of <SniceRouter>.
+ * Does not render anything — SniceRouter reads its props.
+ */
+export declare function Route(_props: RouteProps): ReactElement | null;
+export interface SniceRouterProps {
+    /** URL strategy */
+    mode: 'hash' | 'history';
+    /** Application context passed to guards, pages, layouts */
+    context?: Record<string, any>;
+    /** Default layout component or Snice tag name */
+    layout?: ComponentType<{
+        children: ReactNode;
+    }> | string;
+    /** Loading component shown during async guards. Component, string (Snice tag), or JSX. */
+    loading?: ComponentType | string | ReactNode;
+    /** Fallback when no route matches. Component, string (Snice tag), or JSX. */
+    fallback?: ComponentType | string | ReactNode;
+    children: ReactNode;
+}
+/**
+ * Root provider component. Manages URL state, route matching,
+ * guard execution, layout selection, and context propagation.
+ */
+export declare function SniceRouter({ mode, context, layout: defaultLayout, loading, fallback, children, }: SniceRouterProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/SniceRouter.js

@@ -0,0 +1,190 @@
+/*!
+ * snice v4.30.0
+ * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
+ * (c) 2024
+ * Released under the MIT License.
+ */
+import { jsx } from 'react/jsx-runtime';
+import { useState, useRef, useMemo, Children, isValidElement, useCallback, useEffect, createElement } from 'react';
+import { SniceProvider } from './SniceProvider.js';
+import { matchRoutes } from './matchRoute.js';
+import 'pica-route';
+
+/**
+ * Route definition component. Child of <SniceRouter>.
+ * Does not render anything — SniceRouter reads its props.
+ */
+function Route(_props) {
+    return null;
+}
+function getPath(mode) {
+    if (mode === 'hash') {
+        return window.location.hash.slice(1) || '/';
+    }
+    return window.location.pathname;
+}
+function DefaultLoading() {
+    return createElement('div', {
+        style: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            height: '100%',
+            minHeight: '200px',
+        },
+    }, createElement('style', null, '@keyframes snice-spin{to{transform:rotate(360deg)}}'), createElement('div', {
+        style: {
+            width: '32px',
+            height: '32px',
+            border: '3px solid rgba(128,128,128,0.3)',
+            borderTopColor: 'rgba(128,128,128,0.8)',
+            borderRadius: '50%',
+            animation: 'snice-spin 0.6s linear infinite',
+        },
+    }));
+}
+/** Render a page/layout/loading/fallback prop that can be component, string tag, or JSX */
+function renderFlexible(value, props) {
+    if (value === undefined || value === null)
+        return null;
+    // String = Snice web component tag name
+    if (typeof value === 'string') {
+        return createElement(value, props);
+    }
+    // Function = React component
+    if (typeof value === 'function') {
+        return createElement(value, props);
+    }
+    // Already JSX/ReactNode
+    return value;
+}
+/**
+ * Root provider component. Manages URL state, route matching,
+ * guard execution, layout selection, and context propagation.
+ */
+function SniceRouter({ mode, context = {}, layout: defaultLayout, loading, fallback, children, }) {
+    const [currentPath, setCurrentPath] = useState(() => getPath(mode));
+    const [guardState, setGuardState] = useState('idle');
+    const contextRef = useRef(context);
+    contextRef.current = context;
+    // Parse Route children into config
+    const parsedRoutes = useMemo(() => {
+        const result = [];
+        Children.forEach(children, (child) => {
+            if (!isValidElement(child) || child.type !== Route)
+                return;
+            const props = child.props;
+            const guards = [];
+            if (props.guard)
+                guards.push(props.guard);
+            if (props.guards)
+                guards.push(...props.guards);
+            result.push({
+                path: props.path,
+                page: props.page,
+                guards,
+                guardRedirect: props.guardRedirect,
+                layout: props.layout,
+                placard: props.placard,
+            });
+        });
+        return result;
+    }, [children]);
+    // Collect placards
+    const placards = useMemo(() => {
+        return parsedRoutes
+            .filter((r) => r.placard)
+            .map((r) => r.placard);
+    }, [parsedRoutes]);
+    // Build route configs for matching
+    const routeConfigs = useMemo(() => parsedRoutes.map((r, i) => ({ path: r.path, index: i })), [parsedRoutes]);
+    // Navigate function
+    const navigate = useCallback((path) => {
+        if (mode === 'hash') {
+            window.location.hash = path;
+        }
+        else {
+            window.history.pushState(null, '', path);
+            setCurrentPath(path);
+        }
+    }, [mode]);
+    // Listen for URL changes
+    useEffect(() => {
+        const handler = () => setCurrentPath(getPath(mode));
+        const event = mode === 'hash' ? 'hashchange' : 'popstate';
+        window.addEventListener(event, handler);
+        return () => window.removeEventListener(event, handler);
+    }, [mode]);
+    // Match current path
+    const match = useMemo(() => matchRoutes(routeConfigs, currentPath), [routeConfigs, currentPath]);
+    const matchedRoute = match ? parsedRoutes[match.index] : null;
+    const params = match?.params ?? {};
+    // Run guards
+    useEffect(() => {
+        if (!matchedRoute) {
+            setGuardState('idle');
+            return;
+        }
+        if (matchedRoute.guards.length === 0) {
+            setGuardState('passed');
+            return;
+        }
+        let cancelled = false;
+        setGuardState('checking');
+        (async () => {
+            try {
+                for (const guard of matchedRoute.guards) {
+                    const result = await guard(contextRef.current, params);
+                    if (cancelled)
+                        return;
+                    if (!result) {
+                        setGuardState('failed');
+                        if (matchedRoute.guardRedirect) {
+                            navigate(matchedRoute.guardRedirect);
+                        }
+                        return;
+                    }
+                }
+                if (!cancelled)
+                    setGuardState('passed');
+            }
+            catch {
+                if (!cancelled) {
+                    setGuardState('failed');
+                    if (matchedRoute.guardRedirect) {
+                        navigate(matchedRoute.guardRedirect);
+                    }
+                }
+            }
+        })();
+        return () => { cancelled = true; };
+    }, [matchedRoute, currentPath]); // eslint-disable-line react-hooks/exhaustive-deps
+    // Determine what to render
+    let content;
+    if (!matchedRoute) {
+        // No route match → fallback
+        content = renderFlexible(fallback) ?? createElement('div', null, '404 — Page not found');
+    }
+    else if (guardState === 'checking') {
+        // Async guards running → show loading
+        content = renderFlexible(loading) ?? createElement(DefaultLoading);
+    }
+    else if (guardState === 'failed') {
+        // Guard rejected (redirect may have fired) — render nothing
+        content = null;
+    }
+    else {
+        // Guard passed or no guards → render page
+        content = renderFlexible(matchedRoute.page, params);
+    }
+    // Apply layout
+    const layoutCandidate = matchedRoute?.layout !== undefined ? matchedRoute.layout : defaultLayout;
+    const layoutToUse = layoutCandidate === false ? undefined : layoutCandidate;
+    if (layoutToUse && content !== null) {
+        content = renderFlexible(layoutToUse, { children: content });
+    }
+    return (jsx(SniceProvider, { context: context, navigate: navigate, route: match?.path ?? '', params: params, placards: placards, children: content }));
+}
+
+export { Route, SniceRouter };
+//# sourceMappingURL=SniceRouter.js.map

package/dist/react/SniceRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SniceRouter.js","sources":["../../src/react/SniceRouter.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":"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"}

package/dist/react/index.d.ts

@@ -0,0 +1,3 @@
+export { SniceProvider, useSniceContext, useNavigate, useParams, useRoute, type SniceReactContext, type SniceProviderProps, type Placard, } from './SniceProvider';
+export { SniceRouter, Route, type SniceRouterProps, type RouteProps, } from './SniceRouter';
+export { useRequestHandler, type UseRequestRoute, type UseRequestRouteMap, type UseRequestHandlerOptions, } from './useRequestHandler';

package/dist/react/index.js

@@ -0,0 +1,14 @@
+/*!
+ * snice v4.30.0
+ * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
+ * (c) 2024
+ * Released under the MIT License.
+ */
+export { SniceProvider, useNavigate, useParams, useRoute, useSniceContext } from './SniceProvider.js';
+export { Route, SniceRouter } from './SniceRouter.js';
+export { useRequestHandler } from './useRequestHandler.js';
+import 'react/jsx-runtime';
+import 'react';
+import './matchRoute.js';
+import 'pica-route';
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}

package/dist/react/matchRoute.d.ts

@@ -0,0 +1,16 @@
+import { type RouteParams } from 'pica-route';
+export interface RouteConfig {
+    path: string;
+    index: number;
+}
+export interface MatchResult {
+    index: number;
+    params: RouteParams;
+    path: string;
+}
+/**
+ * Match a URL path against an array of route configs.
+ * Uses pica-route — same matching as vanilla Snice's Router.
+ * Routes are sorted by specificity (longest spec first).
+ */
+export declare function matchRoutes(routes: RouteConfig[], pathname: string): MatchResult | null;

package/dist/react/matchRoute.js

@@ -0,0 +1,32 @@
+/*!
+ * snice v4.30.0
+ * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
+ * (c) 2024
+ * Released under the MIT License.
+ */
+import { Route } from 'pica-route';
+
+/**
+ * Match a URL path against an array of route configs.
+ * Uses pica-route — same matching as vanilla Snice's Router.
+ * Routes are sorted by specificity (longest spec first).
+ */
+function matchRoutes(routes, pathname) {
+    // Sort by specificity (longest path first), same as vanilla Router
+    const sorted = [...routes].sort((a, b) => b.path.length - a.path.length);
+    for (const route of sorted) {
+        const matcher = new Route(route.path);
+        const params = matcher.match(pathname);
+        if (params !== false) {
+            return {
+                index: route.index,
+                params: params,
+                path: route.path,
+            };
+        }
+    }
+    return null;
+}
+
+export { matchRoutes };
+//# sourceMappingURL=matchRoute.js.map

package/dist/react/matchRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchRoute.js","sources":["../../src/react/matchRoute.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;AAaA;;;;AAIG;AACG,SAAU,WAAW,CAAC,MAAqB,EAAE,QAAgB,EAAA;;AAEjE,IAAA,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;AAExE,IAAA,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE;QAC1B,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;AACtC,QAAA,IAAI,MAAM,KAAK,KAAK,EAAE;YACpB,OAAO;gBACL,KAAK,EAAE,KAAK,CAAC,KAAK;AAClB,gBAAA,MAAM,EAAE,MAAqB;gBAC7B,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB;QACH;IACF;AAEA,IAAA,OAAO,IAAI;AACb;;;;"}

package/dist/react/useRequestHandler.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.28.0
+ * snice v4.30.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/react/useRequestHandler.js.map

@@ -1 +1 @@
-{"version":3,"file":"useRequestHandler.js","sources":["../../src/src/react/useRequestHandler.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCG;AAYH;;;;;;AAMG;SACa,iBAAiB,CAC/B,GAA2C,EAC3C,MAA0B,EAC1B,OAAkC,EAAA;AAElC,IAAA,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;AAChC,IAAA,SAAS,CAAC,OAAO,GAAG,MAAM;AAE1B,IAAA,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC;AAClC,IAAA,UAAU,CAAC,OAAO,GAAG,OAAO;AAE5B,IAAA,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;IAEzD,SAAS,CAAC,MAAK;AACb,QAAA,MAAM,MAAM,GAAgB,GAAG,EAAE,OAAO,IAAI,QAAQ;QACpD,MAAM,QAAQ,GAAmB,EAAE;QAEnC,KAAK,MAAM,WAAW,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE;AACjD,YAAA,IAAI,CAAC,WAAW;gBAAE;AAClB,YAAA,MAAM,SAAS,GAAG,CAAA,SAAA,EAAY,WAAW,EAAE;AAE3C,YAAA,MAAM,QAAQ,GAAG,CAAC,KAAY,KAAI;gBAChC,MAAM,EAAE,GAAG,KAAoB;gBAC/B,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM;AAE9C,gBAAA,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE;oBAChC,EAAE,CAAC,cAAc,EAAE;oBACnB,EAAE,CAAC,wBAAwB,EAAE;oBAC7B,EAAE,CAAC,eAAe,EAAE;gBACtB;gBAEA,SAAS,CAAC,OAAO,EAAE;gBAEnB,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC;gBAC9C,IAAI,CAAC,OAAO,EAAE;oBACZ,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,CAAA,mCAAA,EAAsC,WAAW,CAAA,CAAA,CAAG,CAAC,CAAC;oBAC5E;gBACF;gBAEA,OAAO,CAAC,OAAO;qBACZ,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC;AAC3B,qBAAA,IAAI,CAAC,CAAC,MAAW,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;AAC1C,qBAAA,KAAK,CAAC,CAAC,KAAU,KAAI;AACpB,oBAAA,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;oBAClB,OAAO,CAAC,KAAK,CAAC,CAAA,6BAAA,EAAgC,WAAW,CAAA,UAAA,CAAY,EAAE,KAAK,CAAC;AAC/E,gBAAA,CAAC,CAAC;AACN,YAAA,CAAC;AAED,YAAA,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC;AAC5C,YAAA,QAAQ,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACtE;AAEA,QAAA,OAAO,MAAK;YACV,KAAK,MAAM,EAAE,IAAI,QAAQ;AAAE,gBAAA,EAAE,EAAE;AACjC,QAAA,CAAC;;AAEH,IAAA,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AACxB;;;;"}
+{"version":3,"file":"useRequestHandler.js","sources":["../../src/react/useRequestHandler.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCG;AAYH;;;;;;AAMG;SACa,iBAAiB,CAC/B,GAA2C,EAC3C,MAA0B,EAC1B,OAAkC,EAAA;AAElC,IAAA,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;AAChC,IAAA,SAAS,CAAC,OAAO,GAAG,MAAM;AAE1B,IAAA,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC;AAClC,IAAA,UAAU,CAAC,OAAO,GAAG,OAAO;AAE5B,IAAA,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;IAEzD,SAAS,CAAC,MAAK;AACb,QAAA,MAAM,MAAM,GAAgB,GAAG,EAAE,OAAO,IAAI,QAAQ;QACpD,MAAM,QAAQ,GAAmB,EAAE;QAEnC,KAAK,MAAM,WAAW,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE;AACjD,YAAA,IAAI,CAAC,WAAW;gBAAE;AAClB,YAAA,MAAM,SAAS,GAAG,CAAA,SAAA,EAAY,WAAW,EAAE;AAE3C,YAAA,MAAM,QAAQ,GAAG,CAAC,KAAY,KAAI;gBAChC,MAAM,EAAE,GAAG,KAAoB;gBAC/B,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM;AAE9C,gBAAA,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE;oBAChC,EAAE,CAAC,cAAc,EAAE;oBACnB,EAAE,CAAC,wBAAwB,EAAE;oBAC7B,EAAE,CAAC,eAAe,EAAE;gBACtB;gBAEA,SAAS,CAAC,OAAO,EAAE;gBAEnB,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC;gBAC9C,IAAI,CAAC,OAAO,EAAE;oBACZ,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,CAAA,mCAAA,EAAsC,WAAW,CAAA,CAAA,CAAG,CAAC,CAAC;oBAC5E;gBACF;gBAEA,OAAO,CAAC,OAAO;qBACZ,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC;AAC3B,qBAAA,IAAI,CAAC,CAAC,MAAW,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;AAC1C,qBAAA,KAAK,CAAC,CAAC,KAAU,KAAI;AACpB,oBAAA,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;oBAClB,OAAO,CAAC,KAAK,CAAC,CAAA,6BAAA,EAAgC,WAAW,CAAA,UAAA,CAAY,EAAE,KAAK,CAAC;AAC/E,gBAAA,CAAC,CAAC;AACN,YAAA,CAAC;AAED,YAAA,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC;AAC5C,YAAA,QAAQ,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACtE;AAEA,QAAA,OAAO,MAAK;YACV,KAAK,MAAM,EAAE,IAAI,QAAQ;AAAE,gBAAA,EAAE,EAAE;AACjC,QAAA,CAAC;;AAEH,IAAA,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AACxB;;;;"}

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.28.0
+ * snice v4.30.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.28.0
+ * snice v4.30.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.28.0
+ * snice v4.30.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.28.0
+ * snice v4.30.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/types/guard.d.ts

@@ -1,19 +1,12 @@
 import { RouteParams } from './route-params';
 /**
  * Guard function type for route protection and visibility control.
- * Guards determine if navigation to a route should proceed or if a page should be visible.
+ * Guards determine if navigation to a route should proceed.
+ * Can return a boolean synchronously or a Promise<boolean> for async checks.
  *
  * @template T - The context type passed to the guard function
  * @param context - The application context object
  * @param params - Route parameters extracted from the URL
- * @returns boolean - true to allow access, false to deny
- *
- * @example
- * ```typescript
- * const isAuthenticated: Guard<AppContext> = (ctx, params) => ctx.getUser() !== null;
- * const canEditUser: Guard<AppContext> = (ctx, params) => {
- *   return ctx.hasPermission('users.edit', params.id);
- * };
- * ```
+ * @returns boolean or Promise<boolean> - true to allow, false to deny
  */
-export type Guard<T = any> = (context: T, params: RouteParams) => boolean;
+export type Guard<T = any> = (context: T, params: RouteParams) => boolean | Promise<boolean>;

package/docs/ai/README.md

@@ -12,6 +12,7 @@ Token-efficient reference docs for AI assistants. Same content as human docs, mi
 - `api.md` - Complete API reference
 - `decorators.md` - Quick decorator reference
 - `patterns.md` - Common usage patterns
+- `react-integration.md` - React router, hooks, guards, context
 - `architecture.md` - System design
 - `components/*.md` - Component reference (DO NOT read all upfront - read only as needed)
 
@@ -22,16 +23,14 @@ Read these instead of `/docs/*.md` for faster context loading.
 ## CLI
 
 ```bash
-# Create project from template
-npx snice create-app my-app --template=base
-npx snice create-app my-app --template=pwa
+# Create project
+npx snice create-app my-app
+npx snice create-app my-app --template=react
 
 # Run MCP server
 npx snice mcp
 ```
 
-**Note:** Use `--template=base` (equals), not `--template base` (space).
-
 ## MCP Server
 
 Snice includes an MCP server for AI-assisted development.
@@ -141,10 +140,11 @@ class MyCounter extends HTMLElement {
 - `@context()` receives Context on navigation
 
 **Guards:**
-- Signature: `(context: AppContext, params: RouteParams) => boolean`
+- Signature: `(context: AppContext, params: RouteParams) => boolean | Promise<boolean>`
 - TWO params: context (raw AppContext) and route params
 - Return `true` to allow, `false` renders 403 page
-- NO async guards, NO string redirects (boolean only)
+- Sync or async — async guards are awaited; React router shows `loading` component during async resolution
+- NO string redirects (boolean/Promise<boolean> only)
 - Multiple guards use AND logic, short-circuit on first false
 - Example: `(ctx, params) => ctx.user !== null`
 - Factory: `const hasRole = (role) => (ctx, params) => ctx.user?.role === role`