@alneas/appkit-react 0.1.0 → 0.2.0

package/dist/tools/components/auth/AuthProvider.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"AuthProvider.cjs","names":["React","getInstanceCacheScope","getAdapterCacheScope","useQueryClient","useMemo","createAuthSession","useState","createSessionCache","useQuery","subscribeSessionCacheStorageEvent","useCallback","AuthContext","require_runtime","require_tools_components_auth_useAuth","require_tools_components_auth_auth_session","require_tools_components_auth_session_cache","react_jsx_runtime","react","_tanstack_react_query","_alneas_appkit_core_data","AuthProvider","providerId","scope","adapter","ScopedAuthProvider","queryClient","sessionId","session","epoch","isActionLoading","setIsActionLoading","actionError","setActionError","sessionCache","optimisticSession","mounted","placeholderData","hit","user","isQueryLoading","queryError","signal","isSessionVerified","isFetched","isPlaceholderData","isLoggedOutKnown","isLoading","error","unsubscribe","login","email","password","err","register","data","logout","resetPassword","updateEmail","updatePassword","reauthenticate","sendVerificationEmail","getToken","loginWithProvider","args"],"sources":["../../../../src/tools/components/auth/AuthProvider.tsx"],"sourcesContent":["import React, { useEffect, useState, useCallback, useMemo } from 'react';\nimport { useQuery, useQueryClient } from '@tanstack/react-query';\nimport { AuthAdapter } from './types';\nimport { AuthContext } from './useAuth';\nimport { getAdapterCacheScope, getInstanceCacheScope } from '../../lib/data-access/cache-scope';\nimport { createAuthSession } from './auth-session';\nimport {\n  createSessionCache,\n  subscribeSessionCacheStorageEvent,\n  type SessionCacheOptions,\n} from './session-cache';\n\n/** 楽観セッションキャッシュの設定。`true` はデフォルト TTL で有効化、`false`/省略は無効 */\nexport type OptimisticSessionOption = boolean | Omit<SessionCacheOptions, 'key'>;\n\ninterface AuthProviderProps {\n  children: React.ReactNode;\n  adapter: AuthAdapter;\n  /**\n   * 楽観セッションキャッシュ（stale-while-revalidate）を有効化します。\n   *\n   * 有効時は、前回のセッション検証結果を localStorage に保持し、リロード時に即座に\n   * 最後の状態で描画します。裏で whoami 等を再検証し、クッキーが無効なら即座に\n   * ログイン画面へフォールバックします。これにより「認証確認待ち」による画面ブロック\n   * （特に初期ロード時のログイン画面遅延）を排除できます。\n   *\n   * 保存するのは表示用プロフィールのみで、トークン等の機密は含みません。未指定時は無効。\n   *\n   * @example\n   * ```tsx\n   * <AuthProvider adapter={adapter} optimisticSession />\n   * // または TTL を指定\n   * <AuthProvider adapter={adapter} optimisticSession={{ ttl: 1000 * 60 * 60 * 24 }} />\n   * ```\n   */\n  optimisticSession?: OptimisticSessionOption;\n}\n\n/**\n * Authentication Provider Component\n *\n * Provides authentication context to child components with SSR support.\n *\n * Each provider/adapter has an isolated session key under `['session']`. On initial verification\n * and principal changes, application queries in the shared QueryClient are cancelled and removed,\n * and children remount to discard observer/component state. Same-user refreshes preserve them.\n * Use separate QueryClients for independent authentication domains. Data keys remain a cache\n * mechanism, not authorization; enforce access in the backend. Optimistic storage reuse across\n * reloads requires an explicit, non-secret `adapter.cacheScope`.\n *\n * **SSR Behavior:**\n * - During SSR and initial client render, auth state is `{ user: null, isLoading: true }`\n * - Auth listener is only activated after client-side mount\n * - This prevents hydration mismatches between server and client\n *\n * **Optimistic session:**\n * - `optimisticSession` が有効で、かつ直近のセッション状態が localStorage にあれば、\n *    `isLoading` は即 `false` となり `user` は最後の値（または null）で描画されます。\n *   その際 `isSessionVerified` は `false` となり、裏での再検証が完了するまで機微な\n *   画面をガードできます。\n *\n * @example\n * ```tsx\n * import { AuthProvider, BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';\n *\n * const adapter = new BetterAuthAdapter(authClient);\n *\n * <AuthProvider adapter={adapter} optimisticSession>\n *   <App />\n * </AuthProvider>\n * ```\n */\nexport function AuthProvider({ children, adapter, optimisticSession }: AuthProviderProps) {\n  const providerId = React.useId();\n  const scope = `${getInstanceCacheScope(adapter)}:${getAdapterCacheScope(adapter)}`;\n  return (\n    <ScopedAuthProvider\n      key={scope}\n      adapter={adapter}\n      optimisticSession={optimisticSession}\n      providerId={providerId}\n      scope={scope}\n    >\n      {children}\n    </ScopedAuthProvider>\n  );\n}\n\nfunction ScopedAuthProvider({\n  children,\n  adapter,\n  optimisticSession,\n  providerId,\n  scope,\n}: AuthProviderProps & { providerId: string; scope: string }) {\n  const queryClient = useQueryClient();\n  // A fresh mounted boundary must verify again even when returning to a previously used adapter.\n  const sessionId = React.useId();\n  const session = useMemo(\n    () =>\n      createAuthSession(queryClient, adapter, [\n        'session',\n        'react-tools.auth',\n        providerId,\n        scope,\n        sessionId,\n      ]),\n    [queryClient, adapter, providerId, scope, sessionId],\n  );\n  const epoch = React.useSyncExternalStore(\n    session.subscribe,\n    session.getSnapshot,\n    session.getServerSnapshot,\n  );\n  const [isActionLoading, setIsActionLoading] = useState(false);\n  const [actionError, setActionError] = useState<Error | null>(null);\n\n  const sessionCache = useMemo(() => {\n    if (!optimisticSession) return null;\n    const opts: SessionCacheOptions = optimisticSession === true ? {} : optimisticSession;\n    return createSessionCache({\n      ...opts,\n      key: `dataarthub.auth.last-session:${providerId}:${getAdapterCacheScope(adapter)}`,\n    });\n  }, [optimisticSession, providerId, adapter]);\n\n  // Mark component as mounted (client-side only)\n  // useSyncExternalStore ensures we have a consistent value during hydration\n  const mounted = React.useSyncExternalStore(\n    React.useCallback(() => () => {}, []),\n    () => true,\n    () => false,\n  );\n\n  // 楽観表示用の placeholder を読み込む（mounted 以降、かつ有効期限内のみ）\n  const placeholderData = React.useMemo(() => {\n    if (!sessionCache || !mounted) return undefined;\n    const hit = sessionCache.read();\n    // eslint-disable-next-line react-hooks/purity\n    if (!hit || hit.exp <= Date.now()) return undefined;\n    return hit.user; // User | null（null は「最後に未ログイン」\n  }, [sessionCache, mounted]);\n\n  // Session query using TanStack Query\n  const {\n    data: user = null,\n    isLoading: isQueryLoading,\n    error: queryError,\n    isPlaceholderData,\n    isFetched,\n  } = useQuery({\n    queryKey: session.queryKey,\n    queryFn: ({ signal }) => session.read(signal),\n    enabled: mounted,\n    placeholderData,\n    staleTime: sessionCache ? 1000 * 60 * 5 : 0,\n  });\n\n  // 楽観表示中かどうか（placeholder データで描画中＝裏で再検証中）\n  const isSessionVerified = isFetched && !isPlaceholderData;\n  // ログアウト確定など、明示的に未ログインが分かっている状態か\n  const isLoggedOutKnown = isSessionVerified && user === null;\n\n  const isLoading = !mounted || isQueryLoading || isActionLoading;\n  const error = actionError || (queryError as Error | null);\n\n  // 確定したセッション状態を localStorage に永続化（楽観キャッシュの更新）\n  useEffect(() => {\n    if (!sessionCache || !isFetched || isPlaceholderData) return;\n    sessionCache.write(user);\n  }, [sessionCache, isFetched, isPlaceholderData, user]);\n\n  // 他タブでのログイン/ログアウトを検知して再検証\n  useEffect(() => {\n    if (!sessionCache || !mounted) return;\n    return subscribeSessionCacheStorageEvent(sessionCache.key, () => {\n      void queryClient.invalidateQueries({ queryKey: session.queryKey, exact: true });\n    });\n  }, [sessionCache, mounted, queryClient, session]);\n\n  // Setup auth state listener only on client-side\n  useEffect(() => {\n    if (!mounted) return;\n\n    session.activate();\n    const unsubscribe = adapter.onAuthStateChanged(session.publish);\n    return () => {\n      unsubscribe();\n      session.deactivate();\n    };\n  }, [adapter, mounted, session]);\n\n  const login = useCallback(\n    async (email: string, password: string) => {\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.login(email, password));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  const register = useCallback(\n    async (email: string, password: string, data?: { name?: string }) => {\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.register(email, password, data));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  const logout = useCallback(async () => {\n    try {\n      setIsActionLoading(true);\n      setActionError(null);\n      await session.run(() => adapter.logout(), true);\n    } catch (err) {\n      setActionError(err as Error);\n      throw err;\n    } finally {\n      setIsActionLoading(false);\n    }\n  }, [adapter, session]);\n\n  const resetPassword = useCallback(\n    async (email: string) => {\n      return adapter.resetPassword(email);\n    },\n    [adapter],\n  );\n\n  const updateEmail = useCallback(\n    async (email: string) => {\n      return adapter.updateEmail(email);\n    },\n    [adapter],\n  );\n\n  const updatePassword = useCallback(\n    async (password: string) => {\n      return adapter.updatePassword(password);\n    },\n    [adapter],\n  );\n\n  const reauthenticate = useMemo(() => {\n    return adapter.reauthenticate\n      ? async (password: string) => adapter.reauthenticate!(password)\n      : undefined;\n  }, [adapter]);\n\n  const sendVerificationEmail = useMemo(() => {\n    return adapter.sendVerificationEmail ? async () => adapter.sendVerificationEmail!() : undefined;\n  }, [adapter]);\n\n  const getToken = useMemo(() => {\n    return adapter.getToken ? async () => adapter.getToken!() : undefined;\n  }, [adapter]);\n\n  const loginWithProvider = useCallback(\n    async (...args: Parameters<NonNullable<AuthAdapter['loginWithProvider']>>) => {\n      if (!adapter.loginWithProvider) {\n        throw new Error('OAuth login is not supported by this adapter.');\n      }\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.loginWithProvider!(...args));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  return (\n    <AuthContext.Provider\n      value={{\n        user,\n        isLoading,\n        error,\n        /** セッションが裏で再検証され、確定した状態か。楽観表示中は false */\n        isSessionVerified,\n        /** 再検証によって「未ログイン」が確定しているか */\n        isLoggedOutKnown,\n        /** 楽観キャッシュを利用中か */\n        optimisticSession: !!sessionCache,\n        login,\n        register,\n        logout,\n        resetPassword,\n        updateEmail,\n        updatePassword,\n        reauthenticate,\n        sendVerificationEmail,\n        getToken,\n        loginWithProvider: adapter.loginWithProvider ? loginWithProvider : undefined,\n      }}\n    >\n      <React.Fragment key={epoch}>{children}</React.Fragment>\n    </AuthContext.Provider>\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"AuthProvider.cjs","names":["React","getInstanceCacheScope","getAdapterCacheScope","useQueryClient","useMemo","createAuthSession","useState","createSessionCache","useQuery","subscribeSessionCacheStorageEvent","useCallback","AuthContext","require_runtime","require_tools_components_auth_useAuth","require_tools_components_auth_auth_session","require_tools_components_auth_session_cache","react_jsx_runtime","react","_tanstack_react_query","_alneas_appkit_core_data","AuthProvider","providerId","scope","adapter","ScopedAuthProvider","queryClient","sessionId","session","epoch","isActionLoading","setIsActionLoading","actionError","setActionError","sessionCache","optimisticSession","mounted","placeholderData","hit","user","isQueryLoading","queryError","signal","isSessionVerified","isFetched","isPlaceholderData","isLoggedOutKnown","isLoading","error","unsubscribe","login","email","password","err","register","data","logout","resetPassword","updateEmail","updatePassword","reauthenticate","sendVerificationEmail","getToken","loginWithProvider","args"],"sources":["../../../../src/tools/components/auth/AuthProvider.tsx"],"sourcesContent":["import React, { useEffect, useState, useCallback, useMemo } from 'react';\nimport { useQuery, useQueryClient } from '@tanstack/react-query';\nimport { AuthAdapter } from './types';\nimport { AuthContext } from './useAuth';\nimport { getAdapterCacheScope, getInstanceCacheScope } from '../../lib/data-access/cache-scope';\nimport { createAuthSession } from './auth-session';\nimport {\n  createSessionCache,\n  subscribeSessionCacheStorageEvent,\n  type SessionCacheOptions,\n} from './session-cache';\n\n/**\n * Optimistic display-cache setting: true uses seven days; false/omission disables it.\n * @see AuthProvider for the canonical usage example.\n */\nexport type OptimisticSessionOption = boolean | Omit<SessionCacheOptions, 'key'>;\n\n/**\n * Inputs to AuthProvider; see the component for provider setup.\n * @see AuthProvider for the canonical usage example.\n */\ninterface AuthProviderProps {\n  /** Descendants that consume authentication context. */\n  children: React.ReactNode;\n  /** Stable host-owned authentication backend adapter. */\n  adapter: AuthAdapter;\n  /** Enable browser display snapshots with an optional TTL in milliseconds; defaults to disabled. */\n  optimisticSession?: OptimisticSessionOption;\n}\n\n/**\n * Provides adapter-backed authentication state and actions to descendants.\n *\n * @param props - Children, stable host adapter and optional optimistic display caching.\n *\n * @returns Authentication context around children, remounted on principal transitions.\n *\n * @throws When rendered without an outer TanStack QueryClientProvider.\n *\n * @remarks Requires React and @tanstack/react-query; no CSS is required. Each mounted\n * provider scopes its session query. Initial verification and principal changes cancel\n * and remove application queries in the shared QueryClient and remount children;\n * same-user refreshes preserve them. Use separate QueryClients for independent auth domains.\n * SSR and hydration begin with user null and isLoading true. Subscriptions start after\n * mount and are disposed on cleanup. With optimisticSession, an unexpired localStorage\n * snapshot can appear while isSessionVerified remains false; gate sensitive UI on backend\n * verification. Storage contains the adapter's User display fields, so exclude secrets.\n * Cross-reload reuse requires an explicit non-secret adapter.cacheScope. Cache separation\n * is not authorization; the backend must enforce access. Login/register/logout/OAuth\n * failures reject and are exposed as context errors. Other adapter actions forward\n * their failures to the caller; session reads use TanStack Query error handling.\n *\n * @example\n * ```tsx\n * import type { ReactNode } from 'react';\n * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';\n * import { AuthProvider, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n * export function AuthRoot({ adapter, queryClient, children }: {\n *   adapter: AuthAdapter; queryClient: QueryClient; children: ReactNode;\n * }) {\n *   return (\n *     <QueryClientProvider client={queryClient}>\n *       <AuthProvider adapter={adapter} optimisticSession>{children}</AuthProvider>\n *     </QueryClientProvider>\n *   );\n * }\n * ```\n */\nexport function AuthProvider({ children, adapter, optimisticSession }: AuthProviderProps) {\n  const providerId = React.useId();\n  const scope = `${getInstanceCacheScope(adapter)}:${getAdapterCacheScope(adapter)}`;\n  return (\n    <ScopedAuthProvider\n      key={scope}\n      adapter={adapter}\n      optimisticSession={optimisticSession}\n      providerId={providerId}\n      scope={scope}\n    >\n      {children}\n    </ScopedAuthProvider>\n  );\n}\n\nfunction ScopedAuthProvider({\n  children,\n  adapter,\n  optimisticSession,\n  providerId,\n  scope,\n}: AuthProviderProps & { providerId: string; scope: string }) {\n  const queryClient = useQueryClient();\n  // A fresh mounted boundary must verify again even when returning to a previously used adapter.\n  const sessionId = React.useId();\n  const session = useMemo(\n    () =>\n      createAuthSession(queryClient, adapter, [\n        'session',\n        'react-tools.auth',\n        providerId,\n        scope,\n        sessionId,\n      ]),\n    [queryClient, adapter, providerId, scope, sessionId],\n  );\n  const epoch = React.useSyncExternalStore(\n    session.subscribe,\n    session.getSnapshot,\n    session.getServerSnapshot,\n  );\n  const [isActionLoading, setIsActionLoading] = useState(false);\n  const [actionError, setActionError] = useState<Error | null>(null);\n\n  const sessionCache = useMemo(() => {\n    if (!optimisticSession) return null;\n    const opts: SessionCacheOptions = optimisticSession === true ? {} : optimisticSession;\n    return createSessionCache({\n      ...opts,\n      key: `dataarthub.auth.last-session:${providerId}:${getAdapterCacheScope(adapter)}`,\n    });\n  }, [optimisticSession, providerId, adapter]);\n\n  // Mark component as mounted (client-side only)\n  // useSyncExternalStore ensures we have a consistent value during hydration\n  const mounted = React.useSyncExternalStore(\n    React.useCallback(() => () => {}, []),\n    () => true,\n    () => false,\n  );\n\n  // 楽観表示用の placeholder を読み込む（mounted 以降、かつ有効期限内のみ）\n  const placeholderData = React.useMemo(() => {\n    if (!sessionCache || !mounted) return undefined;\n    const hit = sessionCache.read();\n    // eslint-disable-next-line react-hooks/purity\n    if (!hit || hit.exp <= Date.now()) return undefined;\n    return hit.user; // User | null（null は「最後に未ログイン」\n  }, [sessionCache, mounted]);\n\n  // Session query using TanStack Query\n  const {\n    data: user = null,\n    isLoading: isQueryLoading,\n    error: queryError,\n    isPlaceholderData,\n    isFetched,\n  } = useQuery({\n    queryKey: session.queryKey,\n    queryFn: ({ signal }) => session.read(signal),\n    enabled: mounted,\n    placeholderData,\n    staleTime: sessionCache ? 1000 * 60 * 5 : 0,\n  });\n\n  // 楽観表示中かどうか（placeholder データで描画中＝裏で再検証中）\n  const isSessionVerified = isFetched && !isPlaceholderData;\n  // ログアウト確定など、明示的に未ログインが分かっている状態か\n  const isLoggedOutKnown = isSessionVerified && user === null;\n\n  const isLoading = !mounted || isQueryLoading || isActionLoading;\n  const error = actionError || (queryError as Error | null);\n\n  // 確定したセッション状態を localStorage に永続化（楽観キャッシュの更新）\n  useEffect(() => {\n    if (!sessionCache || !isFetched || isPlaceholderData) return;\n    sessionCache.write(user);\n  }, [sessionCache, isFetched, isPlaceholderData, user]);\n\n  // 他タブでのログイン/ログアウトを検知して再検証\n  useEffect(() => {\n    if (!sessionCache || !mounted) return;\n    return subscribeSessionCacheStorageEvent(sessionCache.key, () => {\n      void queryClient.invalidateQueries({ queryKey: session.queryKey, exact: true });\n    });\n  }, [sessionCache, mounted, queryClient, session]);\n\n  // Setup auth state listener only on client-side\n  useEffect(() => {\n    if (!mounted) return;\n\n    session.activate();\n    const unsubscribe = adapter.onAuthStateChanged(session.publish);\n    return () => {\n      unsubscribe();\n      session.deactivate();\n    };\n  }, [adapter, mounted, session]);\n\n  const login = useCallback(\n    async (email: string, password: string) => {\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.login(email, password));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  const register = useCallback(\n    async (email: string, password: string, data?: { name?: string }) => {\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.register(email, password, data));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  const logout = useCallback(async () => {\n    try {\n      setIsActionLoading(true);\n      setActionError(null);\n      await session.run(() => adapter.logout(), true);\n    } catch (err) {\n      setActionError(err as Error);\n      throw err;\n    } finally {\n      setIsActionLoading(false);\n    }\n  }, [adapter, session]);\n\n  const resetPassword = useCallback(\n    async (email: string) => {\n      return adapter.resetPassword(email);\n    },\n    [adapter],\n  );\n\n  const updateEmail = useCallback(\n    async (email: string) => {\n      return adapter.updateEmail(email);\n    },\n    [adapter],\n  );\n\n  const updatePassword = useCallback(\n    async (password: string) => {\n      return adapter.updatePassword(password);\n    },\n    [adapter],\n  );\n\n  const reauthenticate = useMemo(() => {\n    return adapter.reauthenticate\n      ? async (password: string) => adapter.reauthenticate!(password)\n      : undefined;\n  }, [adapter]);\n\n  const sendVerificationEmail = useMemo(() => {\n    return adapter.sendVerificationEmail ? async () => adapter.sendVerificationEmail!() : undefined;\n  }, [adapter]);\n\n  const getToken = useMemo(() => {\n    return adapter.getToken ? async () => adapter.getToken!() : undefined;\n  }, [adapter]);\n\n  const loginWithProvider = useCallback(\n    async (...args: Parameters<NonNullable<AuthAdapter['loginWithProvider']>>) => {\n      if (!adapter.loginWithProvider) {\n        throw new Error('OAuth login is not supported by this adapter.');\n      }\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.loginWithProvider!(...args));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  return (\n    <AuthContext.Provider\n      value={{\n        user,\n        isLoading,\n        error,\n        /** Whether backend verification completed; false during optimistic display. */\n        isSessionVerified,\n        /** Whether verification confirmed a logged-out state. */\n        isLoggedOutKnown,\n        /** Whether optimistic display caching is enabled. */\n        optimisticSession: !!sessionCache,\n        login,\n        register,\n        logout,\n        resetPassword,\n        updateEmail,\n        updatePassword,\n        reauthenticate,\n        sendVerificationEmail,\n        getToken,\n        loginWithProvider: adapter.loginWithProvider ? loginWithProvider : undefined,\n      }}\n    >\n      <React.Fragment key={epoch}>{children}</React.Fragment>\n    </AuthContext.Provider>\n  );\n}\n"],"mappings":"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"}

package/dist/tools/components/auth/AuthProvider.d.cts

@@ -1,62 +1,59 @@
 import { default as React } from 'react';
 import { AuthAdapter } from './types.cjs';
 import { SessionCacheOptions } from './session-cache.cjs';
-/** 楽観セッションキャッシュの設定。`true` はデフォルト TTL で有効化、`false`/省略は無効 */
+/**
+ * Optimistic display-cache setting: true uses seven days; false/omission disables it.
+ * @see AuthProvider for the canonical usage example.
+ */
 export type OptimisticSessionOption = boolean | Omit<SessionCacheOptions, 'key'>;
+/**
+ * Inputs to AuthProvider; see the component for provider setup.
+ * @see AuthProvider for the canonical usage example.
+ */
 interface AuthProviderProps {
+    /** Descendants that consume authentication context. */
     children: React.ReactNode;
+    /** Stable host-owned authentication backend adapter. */
     adapter: AuthAdapter;
-    /**
-     * 楽観セッションキャッシュ（stale-while-revalidate）を有効化します。
-     *
-     * 有効時は、前回のセッション検証結果を localStorage に保持し、リロード時に即座に
-     * 最後の状態で描画します。裏で whoami 等を再検証し、クッキーが無効なら即座に
-     * ログイン画面へフォールバックします。これにより「認証確認待ち」による画面ブロック
-     * （特に初期ロード時のログイン画面遅延）を排除できます。
-     *
-     * 保存するのは表示用プロフィールのみで、トークン等の機密は含みません。未指定時は無効。
-     *
-     * @example
-     * ```tsx
-     * <AuthProvider adapter={adapter} optimisticSession />
-     * // または TTL を指定
-     * <AuthProvider adapter={adapter} optimisticSession={{ ttl: 1000 * 60 * 60 * 24 }} />
-     * ```
-     */
+    /** Enable browser display snapshots with an optional TTL in milliseconds; defaults to disabled. */
     optimisticSession?: OptimisticSessionOption;
 }
 /**
- * Authentication Provider Component
+ * Provides adapter-backed authentication state and actions to descendants.
  *
- * Provides authentication context to child components with SSR support.
+ * @param props - Children, stable host adapter and optional optimistic display caching.
  *
- * Each provider/adapter has an isolated session key under `['session']`. On initial verification
- * and principal changes, application queries in the shared QueryClient are cancelled and removed,
- * and children remount to discard observer/component state. Same-user refreshes preserve them.
- * Use separate QueryClients for independent authentication domains. Data keys remain a cache
- * mechanism, not authorization; enforce access in the backend. Optimistic storage reuse across
- * reloads requires an explicit, non-secret `adapter.cacheScope`.
+ * @returns Authentication context around children, remounted on principal transitions.
  *
- * **SSR Behavior:**
- * - During SSR and initial client render, auth state is `{ user: null, isLoading: true }`
- * - Auth listener is only activated after client-side mount
- * - This prevents hydration mismatches between server and client
+ * @throws When rendered without an outer TanStack QueryClientProvider.
  *
- * **Optimistic session:**
- * - `optimisticSession` が有効で、かつ直近のセッション状態が localStorage にあれば、
- *    `isLoading` は即 `false` となり `user` は最後の値（または null）で描画されます。
- *   その際 `isSessionVerified` は `false` となり、裏での再検証が完了するまで機微な
- *   画面をガードできます。
+ * @remarks Requires React and @tanstack/react-query; no CSS is required. Each mounted
+ * provider scopes its session query. Initial verification and principal changes cancel
+ * and remove application queries in the shared QueryClient and remount children;
+ * same-user refreshes preserve them. Use separate QueryClients for independent auth domains.
+ * SSR and hydration begin with user null and isLoading true. Subscriptions start after
+ * mount and are disposed on cleanup. With optimisticSession, an unexpired localStorage
+ * snapshot can appear while isSessionVerified remains false; gate sensitive UI on backend
+ * verification. Storage contains the adapter's User display fields, so exclude secrets.
+ * Cross-reload reuse requires an explicit non-secret adapter.cacheScope. Cache separation
+ * is not authorization; the backend must enforce access. Login/register/logout/OAuth
+ * failures reject and are exposed as context errors. Other adapter actions forward
+ * their failures to the caller; session reads use TanStack Query error handling.
  *
  * @example
  * ```tsx
- * import { AuthProvider, BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
- *
- * const adapter = new BetterAuthAdapter(authClient);
- *
- * <AuthProvider adapter={adapter} optimisticSession>
- *   <App />
- * </AuthProvider>
+ * import type { ReactNode } from 'react';
+ * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+ * import { AuthProvider, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+ * export function AuthRoot({ adapter, queryClient, children }: {
+ *   adapter: AuthAdapter; queryClient: QueryClient; children: ReactNode;
+ * }) {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <AuthProvider adapter={adapter} optimisticSession>{children}</AuthProvider>
+ *     </QueryClientProvider>
+ *   );
+ * }
  * ```
  */
 export declare function AuthProvider({ children, adapter, optimisticSession }: AuthProviderProps): React.JSX.Element;

package/dist/tools/components/auth/AuthProvider.d.ts

@@ -1,62 +1,59 @@
 import { default as React } from 'react';
 import { AuthAdapter } from './types.js';
 import { SessionCacheOptions } from './session-cache.js';
-/** 楽観セッションキャッシュの設定。`true` はデフォルト TTL で有効化、`false`/省略は無効 */
+/**
+ * Optimistic display-cache setting: true uses seven days; false/omission disables it.
+ * @see AuthProvider for the canonical usage example.
+ */
 export type OptimisticSessionOption = boolean | Omit<SessionCacheOptions, 'key'>;
+/**
+ * Inputs to AuthProvider; see the component for provider setup.
+ * @see AuthProvider for the canonical usage example.
+ */
 interface AuthProviderProps {
+    /** Descendants that consume authentication context. */
     children: React.ReactNode;
+    /** Stable host-owned authentication backend adapter. */
     adapter: AuthAdapter;
-    /**
-     * 楽観セッションキャッシュ（stale-while-revalidate）を有効化します。
-     *
-     * 有効時は、前回のセッション検証結果を localStorage に保持し、リロード時に即座に
-     * 最後の状態で描画します。裏で whoami 等を再検証し、クッキーが無効なら即座に
-     * ログイン画面へフォールバックします。これにより「認証確認待ち」による画面ブロック
-     * （特に初期ロード時のログイン画面遅延）を排除できます。
-     *
-     * 保存するのは表示用プロフィールのみで、トークン等の機密は含みません。未指定時は無効。
-     *
-     * @example
-     * ```tsx
-     * <AuthProvider adapter={adapter} optimisticSession />
-     * // または TTL を指定
-     * <AuthProvider adapter={adapter} optimisticSession={{ ttl: 1000 * 60 * 60 * 24 }} />
-     * ```
-     */
+    /** Enable browser display snapshots with an optional TTL in milliseconds; defaults to disabled. */
     optimisticSession?: OptimisticSessionOption;
 }
 /**
- * Authentication Provider Component
+ * Provides adapter-backed authentication state and actions to descendants.
  *
- * Provides authentication context to child components with SSR support.
+ * @param props - Children, stable host adapter and optional optimistic display caching.
  *
- * Each provider/adapter has an isolated session key under `['session']`. On initial verification
- * and principal changes, application queries in the shared QueryClient are cancelled and removed,
- * and children remount to discard observer/component state. Same-user refreshes preserve them.
- * Use separate QueryClients for independent authentication domains. Data keys remain a cache
- * mechanism, not authorization; enforce access in the backend. Optimistic storage reuse across
- * reloads requires an explicit, non-secret `adapter.cacheScope`.
+ * @returns Authentication context around children, remounted on principal transitions.
  *
- * **SSR Behavior:**
- * - During SSR and initial client render, auth state is `{ user: null, isLoading: true }`
- * - Auth listener is only activated after client-side mount
- * - This prevents hydration mismatches between server and client
+ * @throws When rendered without an outer TanStack QueryClientProvider.
  *
- * **Optimistic session:**
- * - `optimisticSession` が有効で、かつ直近のセッション状態が localStorage にあれば、
- *    `isLoading` は即 `false` となり `user` は最後の値（または null）で描画されます。
- *   その際 `isSessionVerified` は `false` となり、裏での再検証が完了するまで機微な
- *   画面をガードできます。
+ * @remarks Requires React and @tanstack/react-query; no CSS is required. Each mounted
+ * provider scopes its session query. Initial verification and principal changes cancel
+ * and remove application queries in the shared QueryClient and remount children;
+ * same-user refreshes preserve them. Use separate QueryClients for independent auth domains.
+ * SSR and hydration begin with user null and isLoading true. Subscriptions start after
+ * mount and are disposed on cleanup. With optimisticSession, an unexpired localStorage
+ * snapshot can appear while isSessionVerified remains false; gate sensitive UI on backend
+ * verification. Storage contains the adapter's User display fields, so exclude secrets.
+ * Cross-reload reuse requires an explicit non-secret adapter.cacheScope. Cache separation
+ * is not authorization; the backend must enforce access. Login/register/logout/OAuth
+ * failures reject and are exposed as context errors. Other adapter actions forward
+ * their failures to the caller; session reads use TanStack Query error handling.
  *
  * @example
  * ```tsx
- * import { AuthProvider, BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
- *
- * const adapter = new BetterAuthAdapter(authClient);
- *
- * <AuthProvider adapter={adapter} optimisticSession>
- *   <App />
- * </AuthProvider>
+ * import type { ReactNode } from 'react';
+ * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+ * import { AuthProvider, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+ * export function AuthRoot({ adapter, queryClient, children }: {
+ *   adapter: AuthAdapter; queryClient: QueryClient; children: ReactNode;
+ * }) {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <AuthProvider adapter={adapter} optimisticSession>{children}</AuthProvider>
+ *     </QueryClientProvider>
+ *   );
+ * }
  * ```
  */
 export declare function AuthProvider({ children, adapter, optimisticSession }: AuthProviderProps): React.JSX.Element;

package/dist/tools/components/auth/AuthProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"AuthProvider.js","names":["React","AuthProvider","providerId","scope","getInstanceCacheScope","adapter","getAdapterCacheScope","ScopedAuthProvider","queryClient","useQueryClient","sessionId","session","useMemo","createAuthSession","epoch","isActionLoading","setIsActionLoading","useState","actionError","setActionError","sessionCache","optimisticSession","createSessionCache","mounted","placeholderData","hit","user","isQueryLoading","queryError","useQuery","signal","isSessionVerified","isFetched","isPlaceholderData","isLoggedOutKnown","isLoading","error","useEffect","subscribeSessionCacheStorageEvent","unsubscribe","login","useCallback","email","password","err","register","data","logout","resetPassword","updateEmail","updatePassword","reauthenticate","sendVerificationEmail","getToken","loginWithProvider","args","AuthContext"],"sources":["../../../../src/tools/components/auth/AuthProvider.tsx"],"sourcesContent":["import React, { useEffect, useState, useCallback, useMemo } from 'react';\nimport { useQuery, useQueryClient } from '@tanstack/react-query';\nimport { AuthAdapter } from './types';\nimport { AuthContext } from './useAuth';\nimport { getAdapterCacheScope, getInstanceCacheScope } from '../../lib/data-access/cache-scope';\nimport { createAuthSession } from './auth-session';\nimport {\n  createSessionCache,\n  subscribeSessionCacheStorageEvent,\n  type SessionCacheOptions,\n} from './session-cache';\n\n/** 楽観セッションキャッシュの設定。`true` はデフォルト TTL で有効化、`false`/省略は無効 */\nexport type OptimisticSessionOption = boolean | Omit<SessionCacheOptions, 'key'>;\n\ninterface AuthProviderProps {\n  children: React.ReactNode;\n  adapter: AuthAdapter;\n  /**\n   * 楽観セッションキャッシュ（stale-while-revalidate）を有効化します。\n   *\n   * 有効時は、前回のセッション検証結果を localStorage に保持し、リロード時に即座に\n   * 最後の状態で描画します。裏で whoami 等を再検証し、クッキーが無効なら即座に\n   * ログイン画面へフォールバックします。これにより「認証確認待ち」による画面ブロック\n   * （特に初期ロード時のログイン画面遅延）を排除できます。\n   *\n   * 保存するのは表示用プロフィールのみで、トークン等の機密は含みません。未指定時は無効。\n   *\n   * @example\n   * ```tsx\n   * <AuthProvider adapter={adapter} optimisticSession />\n   * // または TTL を指定\n   * <AuthProvider adapter={adapter} optimisticSession={{ ttl: 1000 * 60 * 60 * 24 }} />\n   * ```\n   */\n  optimisticSession?: OptimisticSessionOption;\n}\n\n/**\n * Authentication Provider Component\n *\n * Provides authentication context to child components with SSR support.\n *\n * Each provider/adapter has an isolated session key under `['session']`. On initial verification\n * and principal changes, application queries in the shared QueryClient are cancelled and removed,\n * and children remount to discard observer/component state. Same-user refreshes preserve them.\n * Use separate QueryClients for independent authentication domains. Data keys remain a cache\n * mechanism, not authorization; enforce access in the backend. Optimistic storage reuse across\n * reloads requires an explicit, non-secret `adapter.cacheScope`.\n *\n * **SSR Behavior:**\n * - During SSR and initial client render, auth state is `{ user: null, isLoading: true }`\n * - Auth listener is only activated after client-side mount\n * - This prevents hydration mismatches between server and client\n *\n * **Optimistic session:**\n * - `optimisticSession` が有効で、かつ直近のセッション状態が localStorage にあれば、\n *    `isLoading` は即 `false` となり `user` は最後の値（または null）で描画されます。\n *   その際 `isSessionVerified` は `false` となり、裏での再検証が完了するまで機微な\n *   画面をガードできます。\n *\n * @example\n * ```tsx\n * import { AuthProvider, BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';\n *\n * const adapter = new BetterAuthAdapter(authClient);\n *\n * <AuthProvider adapter={adapter} optimisticSession>\n *   <App />\n * </AuthProvider>\n * ```\n */\nexport function AuthProvider({ children, adapter, optimisticSession }: AuthProviderProps) {\n  const providerId = React.useId();\n  const scope = `${getInstanceCacheScope(adapter)}:${getAdapterCacheScope(adapter)}`;\n  return (\n    <ScopedAuthProvider\n      key={scope}\n      adapter={adapter}\n      optimisticSession={optimisticSession}\n      providerId={providerId}\n      scope={scope}\n    >\n      {children}\n    </ScopedAuthProvider>\n  );\n}\n\nfunction ScopedAuthProvider({\n  children,\n  adapter,\n  optimisticSession,\n  providerId,\n  scope,\n}: AuthProviderProps & { providerId: string; scope: string }) {\n  const queryClient = useQueryClient();\n  // A fresh mounted boundary must verify again even when returning to a previously used adapter.\n  const sessionId = React.useId();\n  const session = useMemo(\n    () =>\n      createAuthSession(queryClient, adapter, [\n        'session',\n        'react-tools.auth',\n        providerId,\n        scope,\n        sessionId,\n      ]),\n    [queryClient, adapter, providerId, scope, sessionId],\n  );\n  const epoch = React.useSyncExternalStore(\n    session.subscribe,\n    session.getSnapshot,\n    session.getServerSnapshot,\n  );\n  const [isActionLoading, setIsActionLoading] = useState(false);\n  const [actionError, setActionError] = useState<Error | null>(null);\n\n  const sessionCache = useMemo(() => {\n    if (!optimisticSession) return null;\n    const opts: SessionCacheOptions = optimisticSession === true ? {} : optimisticSession;\n    return createSessionCache({\n      ...opts,\n      key: `dataarthub.auth.last-session:${providerId}:${getAdapterCacheScope(adapter)}`,\n    });\n  }, [optimisticSession, providerId, adapter]);\n\n  // Mark component as mounted (client-side only)\n  // useSyncExternalStore ensures we have a consistent value during hydration\n  const mounted = React.useSyncExternalStore(\n    React.useCallback(() => () => {}, []),\n    () => true,\n    () => false,\n  );\n\n  // 楽観表示用の placeholder を読み込む（mounted 以降、かつ有効期限内のみ）\n  const placeholderData = React.useMemo(() => {\n    if (!sessionCache || !mounted) return undefined;\n    const hit = sessionCache.read();\n    // eslint-disable-next-line react-hooks/purity\n    if (!hit || hit.exp <= Date.now()) return undefined;\n    return hit.user; // User | null（null は「最後に未ログイン」\n  }, [sessionCache, mounted]);\n\n  // Session query using TanStack Query\n  const {\n    data: user = null,\n    isLoading: isQueryLoading,\n    error: queryError,\n    isPlaceholderData,\n    isFetched,\n  } = useQuery({\n    queryKey: session.queryKey,\n    queryFn: ({ signal }) => session.read(signal),\n    enabled: mounted,\n    placeholderData,\n    staleTime: sessionCache ? 1000 * 60 * 5 : 0,\n  });\n\n  // 楽観表示中かどうか（placeholder データで描画中＝裏で再検証中）\n  const isSessionVerified = isFetched && !isPlaceholderData;\n  // ログアウト確定など、明示的に未ログインが分かっている状態か\n  const isLoggedOutKnown = isSessionVerified && user === null;\n\n  const isLoading = !mounted || isQueryLoading || isActionLoading;\n  const error = actionError || (queryError as Error | null);\n\n  // 確定したセッション状態を localStorage に永続化（楽観キャッシュの更新）\n  useEffect(() => {\n    if (!sessionCache || !isFetched || isPlaceholderData) return;\n    sessionCache.write(user);\n  }, [sessionCache, isFetched, isPlaceholderData, user]);\n\n  // 他タブでのログイン/ログアウトを検知して再検証\n  useEffect(() => {\n    if (!sessionCache || !mounted) return;\n    return subscribeSessionCacheStorageEvent(sessionCache.key, () => {\n      void queryClient.invalidateQueries({ queryKey: session.queryKey, exact: true });\n    });\n  }, [sessionCache, mounted, queryClient, session]);\n\n  // Setup auth state listener only on client-side\n  useEffect(() => {\n    if (!mounted) return;\n\n    session.activate();\n    const unsubscribe = adapter.onAuthStateChanged(session.publish);\n    return () => {\n      unsubscribe();\n      session.deactivate();\n    };\n  }, [adapter, mounted, session]);\n\n  const login = useCallback(\n    async (email: string, password: string) => {\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.login(email, password));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  const register = useCallback(\n    async (email: string, password: string, data?: { name?: string }) => {\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.register(email, password, data));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  const logout = useCallback(async () => {\n    try {\n      setIsActionLoading(true);\n      setActionError(null);\n      await session.run(() => adapter.logout(), true);\n    } catch (err) {\n      setActionError(err as Error);\n      throw err;\n    } finally {\n      setIsActionLoading(false);\n    }\n  }, [adapter, session]);\n\n  const resetPassword = useCallback(\n    async (email: string) => {\n      return adapter.resetPassword(email);\n    },\n    [adapter],\n  );\n\n  const updateEmail = useCallback(\n    async (email: string) => {\n      return adapter.updateEmail(email);\n    },\n    [adapter],\n  );\n\n  const updatePassword = useCallback(\n    async (password: string) => {\n      return adapter.updatePassword(password);\n    },\n    [adapter],\n  );\n\n  const reauthenticate = useMemo(() => {\n    return adapter.reauthenticate\n      ? async (password: string) => adapter.reauthenticate!(password)\n      : undefined;\n  }, [adapter]);\n\n  const sendVerificationEmail = useMemo(() => {\n    return adapter.sendVerificationEmail ? async () => adapter.sendVerificationEmail!() : undefined;\n  }, [adapter]);\n\n  const getToken = useMemo(() => {\n    return adapter.getToken ? async () => adapter.getToken!() : undefined;\n  }, [adapter]);\n\n  const loginWithProvider = useCallback(\n    async (...args: Parameters<NonNullable<AuthAdapter['loginWithProvider']>>) => {\n      if (!adapter.loginWithProvider) {\n        throw new Error('OAuth login is not supported by this adapter.');\n      }\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.loginWithProvider!(...args));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  return (\n    <AuthContext.Provider\n      value={{\n        user,\n        isLoading,\n        error,\n        /** セッションが裏で再検証され、確定した状態か。楽観表示中は false */\n        isSessionVerified,\n        /** 再検証によって「未ログイン」が確定しているか */\n        isLoggedOutKnown,\n        /** 楽観キャッシュを利用中か */\n        optimisticSession: !!sessionCache,\n        login,\n        register,\n        logout,\n        resetPassword,\n        updateEmail,\n        updatePassword,\n        reauthenticate,\n        sendVerificationEmail,\n        getToken,\n        loginWithProvider: adapter.loginWithProvider ? loginWithProvider : undefined,\n      }}\n    >\n      <React.Fragment key={epoch}>{children}</React.Fragment>\n    </AuthContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;;AAwEA,SAAgBC,EAAa,EAAE,aAAU,YAAS,wBAAwC;CACxF,IAAMC,IAAaF,EAAM,MAAM,GACzBG,IAAQ,GAAGC,EAAsBC,CAAO,EAAE,GAAGC,EAAqBD,CAAO;CAC/E,OACE,kBAACE,GAAD;EAEW;EACU;EACP;EACL;EAEN;CACiB,GAPbJ,CAOa;AAExB;AAEA,SAASI,EAAmB,EAC1B,aACA,YACA,sBACA,eACA,YAC4D;CAC5D,IAAMC,IAAcC,EAAe,GAE7BC,IAAYV,EAAM,MAAM,GACxBW,IAAUC,QAEZC,EAAkBL,GAAaH,GAAS;EACtC;EACA;EACAH;EACAC;EACAO;CACF,CAAC,GACH;EAACF;EAAaH;EAASH;EAAYC;EAAOO;CAAS,CACrD,GACMI,IAAQd,EAAM,qBAClBW,EAAQ,WACRA,EAAQ,aACRA,EAAQ,iBACV,GACM,CAACI,GAAiBC,KAAsBC,EAAS,EAAK,GACtD,CAACC,GAAaC,KAAkBF,EAAuB,IAAI,GAE3DG,IAAeR,QACdS,IAEEC,EAAmB;EACxB,GAFgCD,MAAsB,KAAO,CAAC,IAAIA;EAGlE,KAAK,gCAAgCnB,EAAW,GAAGI,EAAqBD,CAAO;CACjF,CAAC,IAL8B,MAM9B;EAACgB;EAAmBnB;EAAYG;CAAO,CAAC,GAIrCkB,IAAUvB,EAAM,qBACpBA,EAAM,wBAAwB,CAAC,GAAG,CAAC,CAAC,SAC9B,UACA,EACR,GAGMwB,IAAkBxB,EAAM,cAAc;EAC1C,IAAI,CAACoB,KAAgB,CAACG,GAAS;EAC/B,IAAME,IAAML,EAAa,KAAK;EAE9B,IAAI,GAACK,KAAOA,EAAI,OAAO,KAAK,IAAI,IAChC,OAAOA,EAAI;CACb,GAAG,CAACL,GAAcG,CAAO,CAAC,GAGpB,EACJ,MAAMG,IAAO,MACb,WAAWC,GACX,OAAOC,GACP,sBACA,iBACEC,EAAS;EACX,UAAUlB,EAAQ;EAClB,UAAU,EAAE,gBAAaA,EAAQ,KAAKmB,CAAM;EAC5C,SAASP;EACT;EACA,WAAWH,IAAe,MAAgB;CAC5C,CAAC,GAGKW,IAAoBC,KAAa,CAACC,GAElCC,IAAmBH,KAAqBL,MAAS,MAEjDS,IAAY,CAACZ,KAAWI,KAAkBZ,GAC1CqB,IAAQlB,KAAgBU;CAiB9B,AAdAS,QAAgB;EACd,AAAKjB,KAAiBY,KAAa,MACnCZ,EAAa,MAAMM,CAAI;CACzB,GAAG;EAACN;EAAcY;EAAWC;EAAmBP;CAAI,CAAC,GAGrDW,QAAgB;EACd,IAAKjB,KAAiBG,GACtB,OAAOe,EAAkClB,EAAa,WAAW;GAC/D,EAAiB,kBAAkB;IAAE,UAAUT,EAAQ;IAAU,OAAO;GAAK,CAAC;EAChF,CAAC;CACH,GAAG;EAACS;EAAcG;EAASf;EAAaG;CAAO,CAAC,GAGhD0B,QAAgB;EACd,IAAI,CAACd,GAAS;EAEd,EAAQ,SAAS;EACjB,IAAMgB,IAAclC,EAAQ,mBAAmBM,EAAQ,OAAO;EAC9D,aAAa;GAEX,AADA4B,EAAY,GACZ5B,EAAQ,WAAW;EACrB;CACF,GAAG;EAACN;EAASkB;EAASZ;CAAO,CAAC;CAE9B,IAAM6B,IAAQC,EACZ,OAAO,GAAe,MAAqB;EACzC,IAAI;GAIF,OAHAzB,EAAmB,EAAI,GACvBG,EAAe,IAAI,GAEZ,MADkBR,EAAQ,UAAUN,EAAQ,MAAMqC,GAAOC,CAAQ,CAAC;EAE3E,SAASC,GAAK;GAEZ,MADAzB,EAAeyB,CAAY,GACrBA;EACR,UAAU;GACR,EAAmB,EAAK;EAC1B;CACF,GACA,CAACvC,GAASM,CAAO,CACnB,GAEMkC,IAAWJ,EACf,OAAO,GAAe,GAAkB,MAA6B;EACnE,IAAI;GAIF,OAHAzB,EAAmB,EAAI,GACvBG,EAAe,IAAI,GAEZ,MADkBR,EAAQ,UAAUN,EAAQ,SAASqC,GAAOC,GAAUG,CAAI,CAAC;EAEpF,SAASF,GAAK;GAEZ,MADAzB,EAAeyB,CAAY,GACrBA;EACR,UAAU;GACR,EAAmB,EAAK;EAC1B;CACF,GACA,CAACvC,GAASM,CAAO,CACnB,GAEMoC,IAASN,EAAY,YAAY;EACrC,IAAI;GAGF,AAFAzB,EAAmB,EAAI,GACvBG,EAAe,IAAI,GACnB,MAAMR,EAAQ,UAAUN,EAAQ,OAAO,GAAG,EAAI;EAChD,SAASuC,GAAK;GAEZ,MADAzB,EAAeyB,CAAY,GACrBA;EACR,UAAU;GACR,EAAmB,EAAK;EAC1B;CACF,GAAG,CAACvC,GAASM,CAAO,CAAC,GAEfqC,IAAgBP,EACpB,OAAO,MACEpC,EAAQ,cAAcqC,CAAK,GAEpC,CAACrC,CAAO,CACV,GAEM4C,IAAcR,EAClB,OAAO,MACEpC,EAAQ,YAAYqC,CAAK,GAElC,CAACrC,CAAO,CACV,GAEM6C,IAAiBT,EACrB,OAAO,MACEpC,EAAQ,eAAesC,CAAQ,GAExC,CAACtC,CAAO,CACV,GAEM8C,IAAiBvC,QACdP,EAAQ,iBACX,OAAO,MAAqBA,EAAQ,eAAgBsC,CAAQ,IAC5D,KAAA,GACH,CAACtC,CAAO,CAAC,GAEN+C,IAAwBxC,QACrBP,EAAQ,wBAAwB,YAAYA,EAAQ,sBAAuB,IAAI,KAAA,GACrF,CAACA,CAAO,CAAC,GAENgD,IAAWzC,QACRP,EAAQ,WAAW,YAAYA,EAAQ,SAAU,IAAI,KAAA,GAC3D,CAACA,CAAO,CAAC,GAENiD,IAAoBb,EACxB,OAAO,GAAGc,MAAoE;EAC5E,IAAI,CAAClD,EAAQ,mBACX,MAAU,MAAM,+CAA+C;EAEjE,IAAI;GAIF,OAHAW,EAAmB,EAAI,GACvBG,EAAe,IAAI,GAEZ,MADkBR,EAAQ,UAAUN,EAAQ,kBAAmB,GAAGkD,CAAI,CAAC;EAEhF,SAASX,GAAK;GAEZ,MADAzB,EAAeyB,CAAY,GACrBA;EACR,UAAU;GACR,EAAmB,EAAK;EAC1B;CACF,GACA,CAACvC,GAASM,CAAO,CACnB;CAEA,OACE,kBAAC6C,EAAY,UAAb;EACE,OAAO;GACL;GACA;GACA;GAEA;GAEA;GAEA,mBAAmB,CAAC,CAACpC;GACrB;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA,mBAAmBf,EAAQ,oBAAoBiD,IAAoB,KAAA;EACrE;EAEA,UAAA,kBAACtD,EAAM,UAAP,EAA6B,YAAyB,GAAjCc,CAAiC;CAClC,CAAA;AAE1B"}
+{"version":3,"file":"AuthProvider.js","names":["React","AuthProvider","providerId","scope","getInstanceCacheScope","adapter","getAdapterCacheScope","ScopedAuthProvider","queryClient","useQueryClient","sessionId","session","useMemo","createAuthSession","epoch","isActionLoading","setIsActionLoading","useState","actionError","setActionError","sessionCache","optimisticSession","createSessionCache","mounted","placeholderData","hit","user","isQueryLoading","queryError","useQuery","signal","isSessionVerified","isFetched","isPlaceholderData","isLoggedOutKnown","isLoading","error","useEffect","subscribeSessionCacheStorageEvent","unsubscribe","login","useCallback","email","password","err","register","data","logout","resetPassword","updateEmail","updatePassword","reauthenticate","sendVerificationEmail","getToken","loginWithProvider","args","AuthContext"],"sources":["../../../../src/tools/components/auth/AuthProvider.tsx"],"sourcesContent":["import React, { useEffect, useState, useCallback, useMemo } from 'react';\nimport { useQuery, useQueryClient } from '@tanstack/react-query';\nimport { AuthAdapter } from './types';\nimport { AuthContext } from './useAuth';\nimport { getAdapterCacheScope, getInstanceCacheScope } from '../../lib/data-access/cache-scope';\nimport { createAuthSession } from './auth-session';\nimport {\n  createSessionCache,\n  subscribeSessionCacheStorageEvent,\n  type SessionCacheOptions,\n} from './session-cache';\n\n/**\n * Optimistic display-cache setting: true uses seven days; false/omission disables it.\n * @see AuthProvider for the canonical usage example.\n */\nexport type OptimisticSessionOption = boolean | Omit<SessionCacheOptions, 'key'>;\n\n/**\n * Inputs to AuthProvider; see the component for provider setup.\n * @see AuthProvider for the canonical usage example.\n */\ninterface AuthProviderProps {\n  /** Descendants that consume authentication context. */\n  children: React.ReactNode;\n  /** Stable host-owned authentication backend adapter. */\n  adapter: AuthAdapter;\n  /** Enable browser display snapshots with an optional TTL in milliseconds; defaults to disabled. */\n  optimisticSession?: OptimisticSessionOption;\n}\n\n/**\n * Provides adapter-backed authentication state and actions to descendants.\n *\n * @param props - Children, stable host adapter and optional optimistic display caching.\n *\n * @returns Authentication context around children, remounted on principal transitions.\n *\n * @throws When rendered without an outer TanStack QueryClientProvider.\n *\n * @remarks Requires React and @tanstack/react-query; no CSS is required. Each mounted\n * provider scopes its session query. Initial verification and principal changes cancel\n * and remove application queries in the shared QueryClient and remount children;\n * same-user refreshes preserve them. Use separate QueryClients for independent auth domains.\n * SSR and hydration begin with user null and isLoading true. Subscriptions start after\n * mount and are disposed on cleanup. With optimisticSession, an unexpired localStorage\n * snapshot can appear while isSessionVerified remains false; gate sensitive UI on backend\n * verification. Storage contains the adapter's User display fields, so exclude secrets.\n * Cross-reload reuse requires an explicit non-secret adapter.cacheScope. Cache separation\n * is not authorization; the backend must enforce access. Login/register/logout/OAuth\n * failures reject and are exposed as context errors. Other adapter actions forward\n * their failures to the caller; session reads use TanStack Query error handling.\n *\n * @example\n * ```tsx\n * import type { ReactNode } from 'react';\n * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';\n * import { AuthProvider, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n * export function AuthRoot({ adapter, queryClient, children }: {\n *   adapter: AuthAdapter; queryClient: QueryClient; children: ReactNode;\n * }) {\n *   return (\n *     <QueryClientProvider client={queryClient}>\n *       <AuthProvider adapter={adapter} optimisticSession>{children}</AuthProvider>\n *     </QueryClientProvider>\n *   );\n * }\n * ```\n */\nexport function AuthProvider({ children, adapter, optimisticSession }: AuthProviderProps) {\n  const providerId = React.useId();\n  const scope = `${getInstanceCacheScope(adapter)}:${getAdapterCacheScope(adapter)}`;\n  return (\n    <ScopedAuthProvider\n      key={scope}\n      adapter={adapter}\n      optimisticSession={optimisticSession}\n      providerId={providerId}\n      scope={scope}\n    >\n      {children}\n    </ScopedAuthProvider>\n  );\n}\n\nfunction ScopedAuthProvider({\n  children,\n  adapter,\n  optimisticSession,\n  providerId,\n  scope,\n}: AuthProviderProps & { providerId: string; scope: string }) {\n  const queryClient = useQueryClient();\n  // A fresh mounted boundary must verify again even when returning to a previously used adapter.\n  const sessionId = React.useId();\n  const session = useMemo(\n    () =>\n      createAuthSession(queryClient, adapter, [\n        'session',\n        'react-tools.auth',\n        providerId,\n        scope,\n        sessionId,\n      ]),\n    [queryClient, adapter, providerId, scope, sessionId],\n  );\n  const epoch = React.useSyncExternalStore(\n    session.subscribe,\n    session.getSnapshot,\n    session.getServerSnapshot,\n  );\n  const [isActionLoading, setIsActionLoading] = useState(false);\n  const [actionError, setActionError] = useState<Error | null>(null);\n\n  const sessionCache = useMemo(() => {\n    if (!optimisticSession) return null;\n    const opts: SessionCacheOptions = optimisticSession === true ? {} : optimisticSession;\n    return createSessionCache({\n      ...opts,\n      key: `dataarthub.auth.last-session:${providerId}:${getAdapterCacheScope(adapter)}`,\n    });\n  }, [optimisticSession, providerId, adapter]);\n\n  // Mark component as mounted (client-side only)\n  // useSyncExternalStore ensures we have a consistent value during hydration\n  const mounted = React.useSyncExternalStore(\n    React.useCallback(() => () => {}, []),\n    () => true,\n    () => false,\n  );\n\n  // 楽観表示用の placeholder を読み込む（mounted 以降、かつ有効期限内のみ）\n  const placeholderData = React.useMemo(() => {\n    if (!sessionCache || !mounted) return undefined;\n    const hit = sessionCache.read();\n    // eslint-disable-next-line react-hooks/purity\n    if (!hit || hit.exp <= Date.now()) return undefined;\n    return hit.user; // User | null（null は「最後に未ログイン」\n  }, [sessionCache, mounted]);\n\n  // Session query using TanStack Query\n  const {\n    data: user = null,\n    isLoading: isQueryLoading,\n    error: queryError,\n    isPlaceholderData,\n    isFetched,\n  } = useQuery({\n    queryKey: session.queryKey,\n    queryFn: ({ signal }) => session.read(signal),\n    enabled: mounted,\n    placeholderData,\n    staleTime: sessionCache ? 1000 * 60 * 5 : 0,\n  });\n\n  // 楽観表示中かどうか（placeholder データで描画中＝裏で再検証中）\n  const isSessionVerified = isFetched && !isPlaceholderData;\n  // ログアウト確定など、明示的に未ログインが分かっている状態か\n  const isLoggedOutKnown = isSessionVerified && user === null;\n\n  const isLoading = !mounted || isQueryLoading || isActionLoading;\n  const error = actionError || (queryError as Error | null);\n\n  // 確定したセッション状態を localStorage に永続化（楽観キャッシュの更新）\n  useEffect(() => {\n    if (!sessionCache || !isFetched || isPlaceholderData) return;\n    sessionCache.write(user);\n  }, [sessionCache, isFetched, isPlaceholderData, user]);\n\n  // 他タブでのログイン/ログアウトを検知して再検証\n  useEffect(() => {\n    if (!sessionCache || !mounted) return;\n    return subscribeSessionCacheStorageEvent(sessionCache.key, () => {\n      void queryClient.invalidateQueries({ queryKey: session.queryKey, exact: true });\n    });\n  }, [sessionCache, mounted, queryClient, session]);\n\n  // Setup auth state listener only on client-side\n  useEffect(() => {\n    if (!mounted) return;\n\n    session.activate();\n    const unsubscribe = adapter.onAuthStateChanged(session.publish);\n    return () => {\n      unsubscribe();\n      session.deactivate();\n    };\n  }, [adapter, mounted, session]);\n\n  const login = useCallback(\n    async (email: string, password: string) => {\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.login(email, password));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  const register = useCallback(\n    async (email: string, password: string, data?: { name?: string }) => {\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.register(email, password, data));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  const logout = useCallback(async () => {\n    try {\n      setIsActionLoading(true);\n      setActionError(null);\n      await session.run(() => adapter.logout(), true);\n    } catch (err) {\n      setActionError(err as Error);\n      throw err;\n    } finally {\n      setIsActionLoading(false);\n    }\n  }, [adapter, session]);\n\n  const resetPassword = useCallback(\n    async (email: string) => {\n      return adapter.resetPassword(email);\n    },\n    [adapter],\n  );\n\n  const updateEmail = useCallback(\n    async (email: string) => {\n      return adapter.updateEmail(email);\n    },\n    [adapter],\n  );\n\n  const updatePassword = useCallback(\n    async (password: string) => {\n      return adapter.updatePassword(password);\n    },\n    [adapter],\n  );\n\n  const reauthenticate = useMemo(() => {\n    return adapter.reauthenticate\n      ? async (password: string) => adapter.reauthenticate!(password)\n      : undefined;\n  }, [adapter]);\n\n  const sendVerificationEmail = useMemo(() => {\n    return adapter.sendVerificationEmail ? async () => adapter.sendVerificationEmail!() : undefined;\n  }, [adapter]);\n\n  const getToken = useMemo(() => {\n    return adapter.getToken ? async () => adapter.getToken!() : undefined;\n  }, [adapter]);\n\n  const loginWithProvider = useCallback(\n    async (...args: Parameters<NonNullable<AuthAdapter['loginWithProvider']>>) => {\n      if (!adapter.loginWithProvider) {\n        throw new Error('OAuth login is not supported by this adapter.');\n      }\n      try {\n        setIsActionLoading(true);\n        setActionError(null);\n        const userResult = await session.run(() => adapter.loginWithProvider!(...args));\n        return userResult;\n      } catch (err) {\n        setActionError(err as Error);\n        throw err;\n      } finally {\n        setIsActionLoading(false);\n      }\n    },\n    [adapter, session],\n  );\n\n  return (\n    <AuthContext.Provider\n      value={{\n        user,\n        isLoading,\n        error,\n        /** Whether backend verification completed; false during optimistic display. */\n        isSessionVerified,\n        /** Whether verification confirmed a logged-out state. */\n        isLoggedOutKnown,\n        /** Whether optimistic display caching is enabled. */\n        optimisticSession: !!sessionCache,\n        login,\n        register,\n        logout,\n        resetPassword,\n        updateEmail,\n        updatePassword,\n        reauthenticate,\n        sendVerificationEmail,\n        getToken,\n        loginWithProvider: adapter.loginWithProvider ? loginWithProvider : undefined,\n      }}\n    >\n      <React.Fragment key={epoch}>{children}</React.Fragment>\n    </AuthContext.Provider>\n  );\n}\n"],"mappings":"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"}

package/dist/tools/components/auth/ProtectedRoute.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"ProtectedRoute.cjs","names":["useAuth","useUserProfile","_Fragment","useRoleCheck","require_runtime","require_tools_components_auth_useAuth","require_tools_components_auth_useUserProfile","require_tools_components_auth_useRoleCheck","react_jsx_runtime","react","ProtectedRoute","isAuthLoading","profile","isProfileLoading","profileContext","isLoading","isAuthenticated","user","isAuthorized","roles","userRole","roleField","role","condition","performRedirect","onRedirect","path","unauthorizedPath","loginPath","fallback","unauthorizedFallback","ShowFor","hasAnyRole"],"sources":["../../../../src/tools/components/auth/ProtectedRoute.tsx"],"sourcesContent":["import React, { useEffect } from 'react';\nimport { useAuth } from './useAuth';\nimport { useUserProfile } from './useUserProfile';\nimport { useRoleCheck } from './useRoleCheck';\nimport { BaseProfile } from './types';\n\nexport interface ProtectedRouteProps<T extends BaseProfile = BaseProfile> {\n  children: React.ReactNode;\n  /**\n   * ログインページへのパス\n   * @default '/login'\n   */\n  loginPath?: string;\n  /**\n   * 認可エラー時のリダイレクトパス (403)\n   * @default undefined (リダイレクトしない)\n   */\n  unauthorizedPath?: string;\n  /**\n   * 許可されるロールの配列\n   * @example ['admin', 'manager']\n   */\n  roles?: string[];\n  /**\n   * プロファイル内のロールフィールド名\n   * @default 'role'\n   */\n  roleField?: keyof T;\n  /**\n   * カスタムアクセス条件\n   * @example (profile) => profile?.subscription === 'premium'\n   */\n  condition?: (profile: T | null) => boolean;\n  /**\n   * ロード中に表示するコンポーネント\n   */\n  fallback?: React.ReactNode;\n  /**\n   * 認可エラー時に表示するコンポーネント (unauthorizedPath が未設定の場合)\n   */\n  unauthorizedFallback?: React.ReactNode;\n  /**\n   * リダイレクト処理をカスタマイズ\n   * @example (path) => navigate(path)\n   */\n  onRedirect?: (path: string) => void;\n}\n\n/**\n * ルート保護コンポーネント\n *\n * 認証状態とロール/条件に基づいてページアクセスを制御します。\n *\n * @example\n * ```tsx\n * // 認証ユーザーのみ\n * <ProtectedRoute>\n *   <DashboardPage />\n * </ProtectedRoute>\n *\n * // 特定ロールのみ\n * <ProtectedRoute roles={['admin']} unauthorizedPath=\"/403\">\n *   <AdminPage />\n * </ProtectedRoute>\n *\n * // カスタム条件\n * <ProtectedRoute\n *   condition={(profile) => profile?.plan === 'premium'}\n *   unauthorizedPath=\"/upgrade\"\n * >\n *   <PremiumPage />\n * </ProtectedRoute>\n * ```\n */\nexport function ProtectedRoute<T extends BaseProfile = BaseProfile>({\n  children,\n  loginPath = '/login',\n  unauthorizedPath,\n  roles,\n  roleField = 'role' as keyof T,\n  condition,\n  fallback = null,\n  unauthorizedFallback = null,\n  onRedirect,\n}: ProtectedRouteProps<T>) {\n  const { user, isLoading: isAuthLoading } = useAuth();\n\n  // UserProfileProvider はオプショナル\n  let profile: T | null = null;\n  let isProfileLoading = false;\n\n  try {\n    const profileContext = useUserProfile<T>();\n    profile = profileContext.profile;\n    isProfileLoading = profileContext.isLoading;\n  } catch {\n    // UserProfileProvider が存在しない場合は無視\n  }\n\n  const isLoading = isAuthLoading || isProfileLoading;\n\n  // 認証チェック\n  const isAuthenticated = !!user;\n\n  // ロールチェック\n  const hasRequiredRole = (): boolean => {\n    if (!roles || roles.length === 0) return true;\n    if (!profile) return false;\n\n    const userRole = profile[roleField];\n    if (Array.isArray(userRole)) {\n      // ユーザーが複数ロールを持つ場合\n      return roles.some((role) => userRole.includes(role));\n    }\n    return roles.includes(userRole as string);\n  };\n\n  // カスタム条件チェック\n  const meetsCondition = (): boolean => {\n    if (!condition) return true;\n    return condition(profile);\n  };\n\n  // 認可チェック (ロール + 条件)\n  const isAuthorized = hasRequiredRole() && meetsCondition();\n\n  // リダイレクト処理 (useEffect内でのみwindow操作)\n  useEffect(() => {\n    if (isLoading) return;\n\n    const performRedirect = (path: string) => {\n      if (onRedirect) {\n        onRedirect(path);\n      } else {\n        window.location.href = path;\n      }\n    };\n\n    if (!isAuthenticated) {\n      performRedirect(loginPath);\n      return;\n    }\n\n    if (!isAuthorized && unauthorizedPath) {\n      performRedirect(unauthorizedPath);\n    }\n  }, [isLoading, isAuthenticated, isAuthorized, loginPath, unauthorizedPath, onRedirect]);\n\n  // ローディング中\n  if (isLoading) {\n    return <>{fallback}</>;\n  }\n\n  // 未認証\n  if (!isAuthenticated) {\n    return null; // リダイレクト処理中\n  }\n\n  // 認可エラー\n  if (!isAuthorized) {\n    if (unauthorizedPath) {\n      return null; // リダイレクト処理中\n    }\n    return <>{unauthorizedFallback}</>;\n  }\n\n  // 認証・認可OK\n  return <>{children}</>;\n}\n\n/**\n * ロールベースの表示制御フック\n *\n * @example\n * ```tsx\n * function MyComponent() {\n *   const { hasRole, hasAnyRole } = useRoleCheck();\n *\n *   return (\n *     <div>\n *       {hasRole('admin') && <AdminPanel />}\n *       {hasAnyRole(['admin', 'manager']) && <ManageButton />}\n *     </div>\n *   );\n * }\n * ```\n */\n/**\n * 条件付き表示コンポーネント\n *\n * @example\n * ```tsx\n * <ShowFor roles={['admin']}>\n *   <AdminOnlyContent />\n * </ShowFor>\n *\n * <ShowFor condition={(profile) => profile?.plan === 'premium'}>\n *   <PremiumContent />\n * </ShowFor>\n * ```\n */\nexport interface ShowForProps<T extends BaseProfile = BaseProfile> {\n  children: React.ReactNode;\n  roles?: string[];\n  roleField?: keyof T;\n  condition?: (profile: T | null) => boolean;\n  fallback?: React.ReactNode;\n}\n\n/**\n * ユーザーのロールやカスタム条件に基づいて、子要素の表示・非表示を切り替える条件付き表示コンポーネント。\n */\nexport function ShowFor<T extends BaseProfile = BaseProfile>({\n  children,\n  roles,\n  roleField = 'role' as keyof T,\n  condition,\n  fallback = null,\n}: ShowForProps<T>) {\n  const { hasAnyRole, profile } = useRoleCheck<T>(roleField);\n\n  const shouldShow = (): boolean => {\n    if (roles && roles.length > 0) {\n      if (!hasAnyRole(roles)) return false;\n    }\n    if (condition) {\n      if (!condition(profile)) return false;\n    }\n    return true;\n  };\n\n  return shouldShow() ? <>{children}</> : <>{fallback}</>;\n}\n"],"mappings":"A,+SA0EA,SAAgBU,EAAoD,CAClE,WACA,YAAY,SACZ,mBACA,QACA,YAAY,OACZ,YACA,WAAW,KACX,uBAAuB,KACvB,cACyB,CACzB,GAAM,CAAE,OAAM,UAAWC,GAAkBX,EAAAA,QAAQ,EAG/CY,EAAoB,KACpBC,EAAmB,GAEvB,GAAI,CACF,IAAMC,EAAiBb,EAAAA,eAAkB,EACzC,EAAUa,EAAe,QACzB,EAAmBA,EAAe,SACpC,MAAQ,CAER,CAEA,IAAMC,EAAYJ,GAAiBE,EAG7BG,EAAkB,CAAC,CAACC,EAsBpBC,OAnBiC,CACrC,GAAI,CAACC,GAASA,EAAM,SAAW,EAAG,MAAO,GACzC,GAAI,CAACP,EAAS,MAAO,GAErB,IAAMQ,EAAWR,EAAQS,GAKzB,OAJI,MAAM,QAAQD,CAAQ,EAEjBD,EAAM,KAAM,GAASC,EAAS,SAASE,CAAI,CAAC,EAE9CH,EAAM,SAASC,CAAkB,CAC1C,EASqB,CAAgB,IALnC,CAAKG,GACEA,EAAUX,CAAO,GA+C1B,OAxCA,EAAAH,EAAA,UAAA,KAAgB,CACd,GAAIM,EAAW,OAEf,IAAMS,EAAmB,GAAiB,CACpCC,EACFA,EAAWC,CAAI,EAEf,OAAO,SAAS,KAAOA,CAE3B,EAEKV,EAKD,CAACE,GAAgBS,GACnBH,EAAgBG,CAAgB,EALhCH,EAAgBI,CAAS,CAO7B,EAAG,CAACb,EAAWC,EAAiBE,EAAcU,EAAWD,EAAkBF,CAAU,CAAC,EAGlFV,GACK,EAAAP,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAA,SAAG2B,CAAW,CAAA,EAIlBb,EAKAE,GAQE,EAAAV,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAG,UAAW,CAAA,EAPfyB,EACK,MAEF,EAAAnB,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAA,SAAG4B,CAAuB,CAAA,EAR1B,IAaX,CA4CA,SAAgBC,EAA6C,CAC3D,WACA,QACA,YAAY,OACZ,YACA,WAAW,MACO,CAClB,GAAM,CAAE,aAAY,WAAY5B,EAAAA,aAAgBkB,CAAS,EAYzD,OATMF,GAASA,EAAM,OAAS,GACtB,CAACa,EAAWb,CAAK,GAEnBI,GACE,CAACA,EAAUX,CAAO,GAKc,EAAAJ,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAA,SAAG2B,CAAW,CAAA,GAAhC,EAAArB,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAG,UAAW,CAAA,CACtC,C"}
+{"version":3,"file":"ProtectedRoute.cjs","names":["useAuth","useUserProfile","_Fragment","useRoleCheck","require_runtime","require_tools_components_auth_useAuth","require_tools_components_auth_useUserProfile","require_tools_components_auth_useRoleCheck","react_jsx_runtime","react","ProtectedRoute","isAuthLoading","profile","isProfileLoading","profileContext","isLoading","isAuthenticated","user","isAuthorized","roles","userRole","roleField","role","condition","performRedirect","onRedirect","path","unauthorizedPath","loginPath","fallback","unauthorizedFallback","ShowFor","hasAnyRole"],"sources":["../../../../src/tools/components/auth/ProtectedRoute.tsx"],"sourcesContent":["import React, { useEffect } from 'react';\nimport { useAuth } from './useAuth';\nimport { useUserProfile } from './useUserProfile';\nimport { useRoleCheck } from './useRoleCheck';\nimport { BaseProfile } from './types';\n\n/**\n * Route display restrictions and client redirects.\n *\n * @typeParam T - Profile shape extending BaseProfile; defaults to BaseProfile.\n *\n * @see ProtectedRoute for provider setup and semantics.\n */\nexport interface ProtectedRouteProps<T extends BaseProfile = BaseProfile> {\n  /**\n   * Content rendered only after loading and successful display checks.\n   */\n  children: React.ReactNode;\n    /**\n     * Unauthenticated redirect destination; defaults to /login.\n     */\n  loginPath?: string;\n    /**\n     * Optional denied-access destination; omission renders unauthorizedFallback.\n     */\n  unauthorizedPath?: string;\n    /**\n     * Any one listed role must match; omission or an empty array skips role restriction.\n     */\n  roles?: string[];\n    /**\n     * Profile scalar/array role property; defaults to role.\n     */\n  roleField?: keyof T;\n    /**\n     * Additional synchronous predicate receiving the profile or null; must pass after role checks. Thrown errors propagate from render.\n     */\n  condition?: (profile: T | null) => boolean;\n    /**\n     * Loading content; defaults to null.\n     */\n  fallback?: React.ReactNode;\n    /**\n     * Denied-access content when unauthorizedPath is omitted; defaults to null.\n     */\n  unauthorizedFallback?: React.ReactNode;\n    /**\n     * Optional synchronous navigation callback receiving the destination; omission assigns window.location.href.\n     */\n  onRedirect?: (path: string) => void;\n}\n\n/**\n * Renders or redirects according to current auth, optional roles and an optional predicate.\n *\n * @typeParam T - Profile shape used by roleField and condition; defaults to BaseProfile.\n *\n * @param props - Children, access predicates, loading/denial content and navigation settings.\n *\n * @returns Loading fallback, permitted children, denied fallback or null while redirecting.\n *\n * @throws Error without AuthProvider; condition errors propagate during rendering.\n *\n * @remarks Requires AuthProvider inside QueryClientProvider. UserProfileProvider is optional\n * but needed for profile-based roles. Redirects run in effects; missing profiles fail a\n * nonempty role restriction. This uses display user state without isSessionVerified;\n * backend authorization is still required. No CSS is required.\n *\n * @example\n * ```tsx\n * import type { ReactNode } from 'react';\n * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';\n * import { AuthProvider, ProtectedRoute, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n *\n * function Content() { return <ProtectedRoute><span>Account</span></ProtectedRoute>; }\n * export function Example({ adapter, queryClient }: { adapter: AuthAdapter; queryClient: QueryClient }) {\n *   return <QueryClientProvider client={queryClient}><AuthProvider adapter={adapter}><Content /></AuthProvider></QueryClientProvider>;\n * }\n * ```\n */\nexport function ProtectedRoute<T extends BaseProfile = BaseProfile>({\n  children,\n  loginPath = '/login',\n  unauthorizedPath,\n  roles,\n  roleField = 'role' as keyof T,\n  condition,\n  fallback = null,\n  unauthorizedFallback = null,\n  onRedirect,\n}: ProtectedRouteProps<T>) {\n  const { user, isLoading: isAuthLoading } = useAuth();\n\n  // UserProfileProvider はオプショナル\n  let profile: T | null = null;\n  let isProfileLoading = false;\n\n  try {\n    const profileContext = useUserProfile<T>();\n    profile = profileContext.profile;\n    isProfileLoading = profileContext.isLoading;\n  } catch {\n    // UserProfileProvider が存在しない場合は無視\n  }\n\n  const isLoading = isAuthLoading || isProfileLoading;\n\n  // 認証チェック\n  const isAuthenticated = !!user;\n\n  // ロールチェック\n  const hasRequiredRole = (): boolean => {\n    if (!roles || roles.length === 0) return true;\n    if (!profile) return false;\n\n    const userRole = profile[roleField];\n    if (Array.isArray(userRole)) {\n      // ユーザーが複数ロールを持つ場合\n      return roles.some((role) => userRole.includes(role));\n    }\n    return roles.includes(userRole as string);\n  };\n\n  // カスタム条件チェック\n  const meetsCondition = (): boolean => {\n    if (!condition) return true;\n    return condition(profile);\n  };\n\n  // 認可チェック (ロール + 条件)\n  const isAuthorized = hasRequiredRole() && meetsCondition();\n\n  // リダイレクト処理 (useEffect内でのみwindow操作)\n  useEffect(() => {\n    if (isLoading) return;\n\n    const performRedirect = (path: string) => {\n      if (onRedirect) {\n        onRedirect(path);\n      } else {\n        window.location.href = path;\n      }\n    };\n\n    if (!isAuthenticated) {\n      performRedirect(loginPath);\n      return;\n    }\n\n    if (!isAuthorized && unauthorizedPath) {\n      performRedirect(unauthorizedPath);\n    }\n  }, [isLoading, isAuthenticated, isAuthorized, loginPath, unauthorizedPath, onRedirect]);\n\n  // ローディング中\n  if (isLoading) {\n    return <>{fallback}</>;\n  }\n\n  // 未認証\n  if (!isAuthenticated) {\n    return null; // リダイレクト処理中\n  }\n\n  // 認可エラー\n  if (!isAuthorized) {\n    if (unauthorizedPath) {\n      return null; // リダイレクト処理中\n    }\n    return <>{unauthorizedFallback}</>;\n  }\n\n  // 認証・認可OK\n  return <>{children}</>;\n}\n\n/**\n * Conditional display settings; see ShowFor for usage.\n *\n * @typeParam T - Profile shape extending BaseProfile; defaults to BaseProfile.\n *\n * @see ShowFor for the canonical usage example.\n */\nexport interface ShowForProps<T extends BaseProfile = BaseProfile> {\n  /**\n   * Content to render when all supplied checks pass.\n   */\n  children: React.ReactNode;\n  /**\n   * Any one role must match; omission or empty array imposes no restriction.\n   */\n  roles?: string[];\n  /**\n   * Profile role property; defaults to role.\n   */\n  roleField?: keyof T;\n  /**\n   * Optional synchronous predicate receiving the current profile or null.\n   */\n  condition?: (profile: T | null) => boolean;\n  /**\n   * Content when a check fails; defaults to null.\n   */\n  fallback?: React.ReactNode;\n}\n\n/**\n * Conditionally displays children using profile roles and an optional predicate.\n *\n * @typeParam T - Profile shape extending BaseProfile; defaults to BaseProfile.\n *\n * @param props - Role checks, profile predicate, children and optional fallback.\n *\n * @returns Children when checks pass; otherwise fallback, defaulting to null.\n *\n * @throws Predicate errors propagate from render.\n *\n * @remarks UserProfileProvider supplies profile data but is optional; without it profile\n * is null. With no restrictions children render even without a profile. Does not redirect,\n * wait for loading, verify authentication or enforce backend access. No CSS is required.\n *\n * @example\n * ```tsx\n * import { ShowFor } from '@alneas/appkit-react/tools/auth';\n * export function RoleLabel() { return <ShowFor roles={['admin']}><span>Admin controls</span></ShowFor>; }\n * ```\n */\nexport function ShowFor<T extends BaseProfile = BaseProfile>({\n  children,\n  roles,\n  roleField = 'role' as keyof T,\n  condition,\n  fallback = null,\n}: ShowForProps<T>) {\n  const { hasAnyRole, profile } = useRoleCheck<T>(roleField);\n\n  const shouldShow = (): boolean => {\n    if (roles && roles.length > 0) {\n      if (!hasAnyRole(roles)) return false;\n    }\n    if (condition) {\n      if (!condition(profile)) return false;\n    }\n    return true;\n  };\n\n  return shouldShow() ? <>{children}</> : <>{fallback}</>;\n}\n"],"mappings":"A,+SAgFA,SAAgBU,EAAoD,CAClE,WACA,YAAY,SACZ,mBACA,QACA,YAAY,OACZ,YACA,WAAW,KACX,uBAAuB,KACvB,cACyB,CACzB,GAAM,CAAE,OAAM,UAAWC,GAAkBX,EAAAA,QAAQ,EAG/CY,EAAoB,KACpBC,EAAmB,GAEvB,GAAI,CACF,IAAMC,EAAiBb,EAAAA,eAAkB,EACzC,EAAUa,EAAe,QACzB,EAAmBA,EAAe,SACpC,MAAQ,CAER,CAEA,IAAMC,EAAYJ,GAAiBE,EAG7BG,EAAkB,CAAC,CAACC,EAsBpBC,OAnBiC,CACrC,GAAI,CAACC,GAASA,EAAM,SAAW,EAAG,MAAO,GACzC,GAAI,CAACP,EAAS,MAAO,GAErB,IAAMQ,EAAWR,EAAQS,GAKzB,OAJI,MAAM,QAAQD,CAAQ,EAEjBD,EAAM,KAAM,GAASC,EAAS,SAASE,CAAI,CAAC,EAE9CH,EAAM,SAASC,CAAkB,CAC1C,EASqB,CAAgB,IALnC,CAAKG,GACEA,EAAUX,CAAO,GA+C1B,OAxCA,EAAAH,EAAA,UAAA,KAAgB,CACd,GAAIM,EAAW,OAEf,IAAMS,EAAmB,GAAiB,CACpCC,EACFA,EAAWC,CAAI,EAEf,OAAO,SAAS,KAAOA,CAE3B,EAEKV,EAKD,CAACE,GAAgBS,GACnBH,EAAgBG,CAAgB,EALhCH,EAAgBI,CAAS,CAO7B,EAAG,CAACb,EAAWC,EAAiBE,EAAcU,EAAWD,EAAkBF,CAAU,CAAC,EAGlFV,GACK,EAAAP,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAA,SAAG2B,CAAW,CAAA,EAIlBb,EAKAE,GAQE,EAAAV,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAG,UAAW,CAAA,EAPfyB,EACK,MAEF,EAAAnB,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAA,SAAG4B,CAAuB,CAAA,EAR1B,IAaX,CAqDA,SAAgBC,EAA6C,CAC3D,WACA,QACA,YAAY,OACZ,YACA,WAAW,MACO,CAClB,GAAM,CAAE,aAAY,WAAY5B,EAAAA,aAAgBkB,CAAS,EAYzD,OATMF,GAASA,EAAM,OAAS,GACtB,CAACa,EAAWb,CAAK,GAEnBI,GACE,CAACA,EAAUX,CAAO,GAKc,EAAAJ,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAA,SAAG2B,CAAW,CAAA,GAAhC,EAAArB,EAAA,IAAA,CAAAN,EAAAA,SAAA,CAAG,UAAW,CAAA,CACtC,C"}

package/dist/tools/components/auth/ProtectedRoute.d.cts

@@ -1,112 +1,127 @@
 import { default as React } from 'react';
 import { BaseProfile } from './types.cjs';
+/**
+ * Route display restrictions and client redirects.
+ *
+ * @typeParam T - Profile shape extending BaseProfile; defaults to BaseProfile.
+ *
+ * @see ProtectedRoute for provider setup and semantics.
+ */
 export interface ProtectedRouteProps<T extends BaseProfile = BaseProfile> {
+    /**
+     * Content rendered only after loading and successful display checks.
+     */
     children: React.ReactNode;
     /**
-     * ログインページへのパス
-     * @default '/login'
+     * Unauthenticated redirect destination; defaults to /login.
      */
     loginPath?: string;
     /**
-     * 認可エラー時のリダイレクトパス (403)
-     * @default undefined (リダイレクトしない)
+     * Optional denied-access destination; omission renders unauthorizedFallback.
      */
     unauthorizedPath?: string;
     /**
-     * 許可されるロールの配列
-     * @example ['admin', 'manager']
+     * Any one listed role must match; omission or an empty array skips role restriction.
      */
     roles?: string[];
     /**
-     * プロファイル内のロールフィールド名
-     * @default 'role'
+     * Profile scalar/array role property; defaults to role.
      */
     roleField?: keyof T;
     /**
-     * カスタムアクセス条件
-     * @example (profile) => profile?.subscription === 'premium'
+     * Additional synchronous predicate receiving the profile or null; must pass after role checks. Thrown errors propagate from render.
      */
     condition?: (profile: T | null) => boolean;
     /**
-     * ロード中に表示するコンポーネント
+     * Loading content; defaults to null.
      */
     fallback?: React.ReactNode;
     /**
-     * 認可エラー時に表示するコンポーネント (unauthorizedPath が未設定の場合)
+     * Denied-access content when unauthorizedPath is omitted; defaults to null.
      */
     unauthorizedFallback?: React.ReactNode;
     /**
-     * リダイレクト処理をカスタマイズ
-     * @example (path) => navigate(path)
+     * Optional synchronous navigation callback receiving the destination; omission assigns window.location.href.
      */
     onRedirect?: (path: string) => void;
 }
 /**
- * ルート保護コンポーネント
+ * Renders or redirects according to current auth, optional roles and an optional predicate.
  *
- * 認証状態とロール/条件に基づいてページアクセスを制御します。
+ * @typeParam T - Profile shape used by roleField and condition; defaults to BaseProfile.
  *
- * @example
- * ```tsx
- * // 認証ユーザーのみ
- * <ProtectedRoute>
- *   <DashboardPage />
- * </ProtectedRoute>
- *
- * // 特定ロールのみ
- * <ProtectedRoute roles={['admin']} unauthorizedPath="/403">
- *   <AdminPage />
- * </ProtectedRoute>
- *
- * // カスタム条件
- * <ProtectedRoute
- *   condition={(profile) => profile?.plan === 'premium'}
- *   unauthorizedPath="/upgrade"
- * >
- *   <PremiumPage />
- * </ProtectedRoute>
- * ```
- */
-export declare function ProtectedRoute<T extends BaseProfile = BaseProfile>({ children, loginPath, unauthorizedPath, roles, roleField, condition, fallback, unauthorizedFallback, onRedirect, }: ProtectedRouteProps<T>): React.JSX.Element | null;
-/**
- * ロールベースの表示制御フック
+ * @param props - Children, access predicates, loading/denial content and navigation settings.
+ *
+ * @returns Loading fallback, permitted children, denied fallback or null while redirecting.
+ *
+ * @throws Error without AuthProvider; condition errors propagate during rendering.
+ *
+ * @remarks Requires AuthProvider inside QueryClientProvider. UserProfileProvider is optional
+ * but needed for profile-based roles. Redirects run in effects; missing profiles fail a
+ * nonempty role restriction. This uses display user state without isSessionVerified;
+ * backend authorization is still required. No CSS is required.
  *
  * @example
  * ```tsx
- * function MyComponent() {
- *   const { hasRole, hasAnyRole } = useRoleCheck();
- *
- *   return (
- *     <div>
- *       {hasRole('admin') && <AdminPanel />}
- *       {hasAnyRole(['admin', 'manager']) && <ManageButton />}
- *     </div>
- *   );
+ * import type { ReactNode } from 'react';
+ * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+ * import { AuthProvider, ProtectedRoute, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+ *
+ * function Content() { return <ProtectedRoute><span>Account</span></ProtectedRoute>; }
+ * export function Example({ adapter, queryClient }: { adapter: AuthAdapter; queryClient: QueryClient }) {
+ *   return <QueryClientProvider client={queryClient}><AuthProvider adapter={adapter}><Content /></AuthProvider></QueryClientProvider>;
  * }
  * ```
  */
+export declare function ProtectedRoute<T extends BaseProfile = BaseProfile>({ children, loginPath, unauthorizedPath, roles, roleField, condition, fallback, unauthorizedFallback, onRedirect, }: ProtectedRouteProps<T>): React.JSX.Element | null;
 /**
- * 条件付き表示コンポーネント
+ * Conditional display settings; see ShowFor for usage.
  *
- * @example
- * ```tsx
- * <ShowFor roles={['admin']}>
- *   <AdminOnlyContent />
- * </ShowFor>
+ * @typeParam T - Profile shape extending BaseProfile; defaults to BaseProfile.
  *
- * <ShowFor condition={(profile) => profile?.plan === 'premium'}>
- *   <PremiumContent />
- * </ShowFor>
- * ```
+ * @see ShowFor for the canonical usage example.
  */
 export interface ShowForProps<T extends BaseProfile = BaseProfile> {
+    /**
+     * Content to render when all supplied checks pass.
+     */
     children: React.ReactNode;
+    /**
+     * Any one role must match; omission or empty array imposes no restriction.
+     */
     roles?: string[];
+    /**
+     * Profile role property; defaults to role.
+     */
     roleField?: keyof T;
+    /**
+     * Optional synchronous predicate receiving the current profile or null.
+     */
     condition?: (profile: T | null) => boolean;
+    /**
+     * Content when a check fails; defaults to null.
+     */
     fallback?: React.ReactNode;
 }
 /**
- * ユーザーのロールやカスタム条件に基づいて、子要素の表示・非表示を切り替える条件付き表示コンポーネント。
+ * Conditionally displays children using profile roles and an optional predicate.
+ *
+ * @typeParam T - Profile shape extending BaseProfile; defaults to BaseProfile.
+ *
+ * @param props - Role checks, profile predicate, children and optional fallback.
+ *
+ * @returns Children when checks pass; otherwise fallback, defaulting to null.
+ *
+ * @throws Predicate errors propagate from render.
+ *
+ * @remarks UserProfileProvider supplies profile data but is optional; without it profile
+ * is null. With no restrictions children render even without a profile. Does not redirect,
+ * wait for loading, verify authentication or enforce backend access. No CSS is required.
+ *
+ * @example
+ * ```tsx
+ * import { ShowFor } from '@alneas/appkit-react/tools/auth';
+ * export function RoleLabel() { return <ShowFor roles={['admin']}><span>Admin controls</span></ShowFor>; }
+ * ```
  */
 export declare function ShowFor<T extends BaseProfile = BaseProfile>({ children, roles, roleField, condition, fallback, }: ShowForProps<T>): React.JSX.Element;