@semiont/react-ui 0.4.14 → 0.4.15

package/README.md

@@ -74,26 +74,32 @@ Import the styles in your app's main CSS file:
 import {
   TranslationProvider,
   ApiClientProvider,
-  SessionProvider,
+  KnowledgeBaseSessionProvider,
+  ProtectedErrorBoundary,
+  SessionExpiredModal,
+  PermissionDeniedModal,
 } from '@semiont/react-ui';
 import { QueryClientProvider } from '@tanstack/react-query';
 
 function App({ children }) {
   const translationManager = useTranslationManager(); // Your implementation
-  const apiClientManager = useApiClientManager();     // Your implementation
-  const sessionManager = useSessionManager();         // Your implementation
   const queryClient = new QueryClient();
 
   return (
-    <SessionProvider sessionManager={sessionManager}>
-      <TranslationProvider translationManager={translationManager}>
-        <ApiClientProvider apiClientManager={apiClientManager}>
-          <QueryClientProvider client={queryClient}>
-            {children}
-          </QueryClientProvider>
+    <TranslationProvider translationManager={translationManager}>
+      <QueryClientProvider client={queryClient}>
+        <ApiClientProvider baseUrl="https://api.example.com">
+          {/* Mount KnowledgeBaseSessionProvider only on protected routes */}
+          <KnowledgeBaseSessionProvider>
+            <ProtectedErrorBoundary>
+              <SessionExpiredModal />
+              <PermissionDeniedModal />
+              {children}
+            </ProtectedErrorBoundary>
+          </KnowledgeBaseSessionProvider>
         </ApiClientProvider>
-      </TranslationProvider>
-    </SessionProvider>
+      </QueryClientProvider>
+    </TranslationProvider>
   );
 }
 ```
@@ -187,7 +193,7 @@ See [docs/STYLES.md](docs/STYLES.md) for detailed CSS documentation.
 
 All cross-cutting concerns use the Provider Pattern:
 
-- **SessionProvider** - Authentication state management
+- **KnowledgeBaseSessionProvider** - KB list, active KB, validated session, modal state — one merged provider that's the single source of truth for "which KB and what's the session against it"
 - **TranslationProvider** - Internationalization
 - **ApiClientProvider** - Authenticated API client
 - **OpenResourcesProvider** - Recently opened resources

package/dist/KnowledgeBaseSessionContext-CpYaCbnC.d.mts

@@ -0,0 +1,174 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default from 'react';
+import { components } from '@semiont/core';
+
+/**
+ * Open Resources Manager Interface
+ *
+ * Manages a list of open resources (documents/files) with persistence.
+ * This interface allows apps to provide their own implementation of resource management
+ * (localStorage, sessionStorage, database, etc.) while components remain framework-agnostic.
+ *
+ * Components accept this manager as a prop instead of consuming from Context.
+ *
+ * @example
+ * ```tsx
+ * // In app (e.g., frontend/src/hooks/useOpenResourcesManager.ts)
+ * export function useOpenResourcesManager(): OpenResourcesManager {
+ *   const [openResources, setOpenResources] = useState<OpenResource[]>([]);
+ *
+ *   // Implementation details...
+ *
+ *   return {
+ *     openResources,
+ *     addResource,
+ *     removeResource,
+ *     updateResourceName,
+ *     reorderResources
+ *   };
+ * }
+ *
+ * // Pass to components as props
+ * <KnowledgeNavigation openResourcesManager={openResourcesManager} />
+ * ```
+ */
+interface OpenResource {
+    /** Unique identifier for the resource */
+    id: string;
+    /** Display name of the resource */
+    name: string;
+    /** Timestamp when the resource was opened */
+    openedAt: number;
+    /** Order/position for manual sorting (optional for backward compatibility) */
+    order?: number;
+    /** Media type for icon display (e.g., 'application/pdf', 'text/plain') */
+    mediaType?: string;
+    /** Working-tree URI (e.g. "file://docs/overview.md") — used as tooltip in navigation */
+    storageUri?: string;
+}
+interface OpenResourcesManager {
+    /** List of currently open resources */
+    openResources: OpenResource[];
+    /**
+     * Add a new resource to the open list or update if already exists
+     * @param id - Unique resource identifier
+     * @param name - Display name of the resource
+     * @param mediaType - Optional media type for icon display
+     * @param storageUri - Optional working-tree URI (e.g. "file://docs/overview.md")
+     */
+    addResource: (id: string, name: string, mediaType?: string, storageUri?: string) => void;
+    /**
+     * Remove a resource from the open list
+     * @param id - Resource identifier to remove
+     */
+    removeResource: (id: string) => void;
+    /**
+     * Update the display name of an open resource
+     * @param id - Resource identifier
+     * @param name - New display name
+     */
+    updateResourceName: (id: string, name: string) => void;
+    /**
+     * Reorder resources by moving from one index to another
+     * @param oldIndex - Current position index
+     * @param newIndex - Desired position index
+     */
+    reorderResources: (oldIndex: number, newIndex: number) => void;
+}
+
+/**
+ * KnowledgeBase — a connection to a Semiont backend instance.
+ *
+ * Each KB has its own JWT, its own API base URL, and its own session.
+ * The user is "authenticated against KB X" — never globally authenticated.
+ */
+interface KnowledgeBase {
+    id: string;
+    label: string;
+    host: string;
+    port: number;
+    protocol: 'http' | 'https';
+    email: string;
+}
+/**
+ * Input shape for adding a new KB. The id is generated by the provider.
+ */
+type NewKnowledgeBase = Omit<KnowledgeBase, 'id'>;
+/**
+ * Status of the locally-stored credential for a KB. Derived from the
+ * presence and validity of the JWT in localStorage.
+ */
+type KbSessionStatus = 'authenticated' | 'expired' | 'signed-out' | 'unreachable';
+
+/**
+ * Translation management interface
+ * Apps implement this to provide translations using their preferred i18n library
+ */
+interface TranslationManager {
+    /**
+     * Translate a key within a namespace
+     * @param namespace - Translation namespace (e.g., 'Toolbar', 'ResourceViewer')
+     * @param key - Translation key within the namespace
+     * @param params - Optional parameters for interpolation
+     * @returns Translated string
+     */
+    t: (namespace: string, key: string, params?: Record<string, any>) => string;
+}
+
+type UserInfo = components['schemas']['UserResponse'];
+interface AuthSession {
+    token: string;
+    user: UserInfo;
+}
+
+interface KnowledgeBaseSessionValue {
+    knowledgeBases: KnowledgeBase[];
+    activeKnowledgeBase: KnowledgeBase | null;
+    session: AuthSession | null;
+    isLoading: boolean;
+    user: UserInfo | null;
+    token: string | null;
+    isAuthenticated: boolean;
+    hasValidBackendToken: boolean;
+    isFullyAuthenticated: boolean;
+    displayName: string;
+    avatarUrl: string | null;
+    userDomain: string | undefined;
+    isAdmin: boolean;
+    isModerator: boolean;
+    expiresAt: Date | null;
+    sessionExpiredAt: number | null;
+    sessionExpiredMessage: string | null;
+    permissionDeniedAt: number | null;
+    permissionDeniedMessage: string | null;
+    addKnowledgeBase: (kb: NewKnowledgeBase, access: string, refresh: string) => KnowledgeBase;
+    removeKnowledgeBase: (id: string) => void;
+    setActiveKnowledgeBase: (id: string) => void;
+    updateKnowledgeBase: (id: string, updates: Partial<Pick<KnowledgeBase, 'label'>>) => void;
+    /** Re-auth on an existing KB: store the new tokens and refresh the session. */
+    signIn: (id: string, access: string, refresh: string) => void;
+    /** Sign out of a KB: clear its stored tokens. If it's the active KB, clear in-memory session too. */
+    signOut: (id: string) => void;
+    /**
+     * Refresh the active KB's access token. Returns the new access token, or
+     * null if no refresh token is available or the refresh failed. Concurrent
+     * calls deduplicate via an in-flight Promise per KB. Used by the api-client's
+     * 401-recovery hook and by the proactive refresh timer.
+     */
+    refreshActive: () => Promise<string | null>;
+    acknowledgeSessionExpired: () => void;
+    acknowledgePermissionDenied: () => void;
+}
+/**
+ * Raw context export. Exposed for test utilities that need to construct
+ * a mock provider without going through localStorage and JWT validation.
+ * Production code should always use {@link useKnowledgeBaseSession} instead.
+ */
+declare const KnowledgeBaseSessionContext: React__default.Context<KnowledgeBaseSessionValue | undefined>;
+
+declare function KnowledgeBaseSessionProvider({ children }: {
+    children: React__default.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useKnowledgeBaseSession(): KnowledgeBaseSessionValue;
+
+export { type AuthSession as A, type KbSessionStatus as K, type NewKnowledgeBase as N, type OpenResourcesManager as O, type TranslationManager as T, type KnowledgeBase as a, type OpenResource as b, KnowledgeBaseSessionContext as c, KnowledgeBaseSessionProvider as d, type KnowledgeBaseSessionValue as e, useKnowledgeBaseSession as u };

package/dist/{PdfAnnotationCanvas.client-CW6SKH2U.mjs → PdfAnnotationCanvas.client-CHDCGQBR.mjs}

@@ -2,8 +2,8 @@
 "use client";
 import {
   createHoverHandlers
-} from "./chunk-BQJWOK4C.mjs";
-import "./chunk-HNZOXH4L.mjs";
+} from "./chunk-VN5NY4SN.mjs";
+import "./chunk-OZICDVH7.mjs";
 import "./chunk-D4GAAQMM.mjs";
 
 // src/components/pdf-annotation/PdfAnnotationCanvas.tsx
@@ -487,4 +487,4 @@ function PdfAnnotationCanvas({
 export {
   PdfAnnotationCanvas
 };
-//# sourceMappingURL=PdfAnnotationCanvas.client-CW6SKH2U.mjs.map
+//# sourceMappingURL=PdfAnnotationCanvas.client-CHDCGQBR.mjs.map

package/dist/{chunk-HNZOXH4L.mjs → chunk-OZICDVH7.mjs}

@@ -29,6 +29,7 @@ import { jsx as jsx2 } from "react/jsx-runtime";
 var ApiClientContext = createContext2(void 0);
 function ApiClientProvider({
   baseUrl: url,
+  tokenRefresher,
   children
 }) {
   const eventBus = useEventBus();
@@ -37,9 +38,10 @@ function ApiClientProvider({
       baseUrl: baseUrl(url),
       eventBus,
       // Use no timeout in test environment to avoid AbortController issues with ky + vitest
-      ...process.env.NODE_ENV !== "test" && { timeout: 3e4 }
+      ...process.env.NODE_ENV !== "test" && { timeout: 3e4 },
+      ...tokenRefresher && { tokenRefresher }
     }),
-    [url, eventBus]
+    [url, eventBus, tokenRefresher]
   );
   return /* @__PURE__ */ jsx2(ApiClientContext.Provider, { value: client, children });
 }
@@ -57,4 +59,4 @@ export {
   ApiClientProvider,
   useApiClient
 };
-//# sourceMappingURL=chunk-HNZOXH4L.mjs.map
+//# sourceMappingURL=chunk-OZICDVH7.mjs.map

package/dist/chunk-OZICDVH7.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contexts/EventBusContext.tsx","../src/contexts/ApiClientContext.tsx"],"sourcesContent":["'use client';\n\nimport { createContext, useContext, useRef, type ReactNode } from 'react';\nimport { EventBus } from '@semiont/core';\n\nconst EventBusContext = createContext<EventBus | null>(null);\n\nexport interface EventBusProviderProps {\n  children: ReactNode;\n}\n\n/**\n * Unified event bus provider for all application events.\n *\n * Each provider mount creates a fresh EventBus instance. This means:\n * - Workspace switches (which remount via key prop) get isolated buses\n * - Tests get isolation naturally — no resetEventBusForTesting needed\n *\n * Operation handlers (API calls triggered by events) are set up separately via\n * the useBindFlow hook, which should be called at the resource page level.\n */\nexport function EventBusProvider({ children }: EventBusProviderProps) {\n  const eventBusRef = useRef<EventBus | null>(null);\n  if (!eventBusRef.current) {\n    eventBusRef.current = new EventBus();\n  }\n  const eventBus = eventBusRef.current;\n\n  return (\n    <EventBusContext.Provider value={eventBus}>\n      {children}\n    </EventBusContext.Provider>\n  );\n}\n\n/**\n * Hook to access the unified event bus\n *\n * Use this everywhere instead of:\n * - useMakeMeaningEvents()\n * - useNavigationEvents()\n * - useGlobalSettingsEvents()\n *\n * @example\n * ```typescript\n * const eventBus = useEventBus();\n *\n * // Emit any event\n * eventBus.get('beckon:hover').next({ annotationId: '123' });\n * eventBus.get('browse:sidebar-toggle').next(undefined);\n * eventBus.get('settings:theme-changed').next({ theme: 'dark' });\n *\n * // Subscribe to any event\n * useEffect(() => {\n *   const unsubscribe = eventBus.on('beckon:hover', ({ annotationId }) => {\n *     console.log(annotationId);\n *   });\n *   return () => unsubscribe();\n * }, []);\n * ```\n */\nexport function useEventBus(): EventBus {\n  const eventBus = useContext(EventBusContext);\n  if (!eventBus) {\n    throw new Error('useEventBus must be used within EventBusProvider');\n  }\n  return eventBus;\n}\n","'use client';\n\nimport { createContext, useContext, ReactNode, useMemo } from 'react';\nimport { baseUrl } from '@semiont/core';\nimport { SemiontApiClient, type TokenRefresher } from '@semiont/api-client';\nimport { useEventBus } from './EventBusContext';\n\nconst ApiClientContext = createContext<SemiontApiClient | undefined>(undefined);\n\nexport interface ApiClientProviderProps {\n  baseUrl: string;\n  /**\n   * Optional 401-recovery hook. If provided, the api-client will retry\n   * requests once with a fresh token when a 401 is encountered. The\n   * frontend's protected layouts pass `useKnowledgeBaseSession().refreshActive`\n   * here so the api-client can transparently recover from expired access tokens.\n   */\n  tokenRefresher?: TokenRefresher;\n  children: ReactNode;\n}\n\n/**\n * Provider for API client — must be nested inside EventBusProvider.\n * The client is re-created when the baseUrl changes (workspace switch).\n * The EventBus is taken from EventBusContext so client and UI components\n * share the same workspace-scoped bus.\n */\nexport function ApiClientProvider({\n  baseUrl: url,\n  tokenRefresher,\n  children,\n}: ApiClientProviderProps) {\n  const eventBus = useEventBus();\n\n  const client = useMemo(\n    () => new SemiontApiClient({\n      baseUrl: baseUrl(url),\n      eventBus,\n      // Use no timeout in test environment to avoid AbortController issues with ky + vitest\n      ...(process.env.NODE_ENV !== 'test' && { timeout: 30000 }),\n      ...(tokenRefresher && { tokenRefresher }),\n    }),\n    [url, eventBus, tokenRefresher]\n  );\n\n  return (\n    <ApiClientContext.Provider value={client}>\n      {children}\n    </ApiClientContext.Provider>\n  );\n}\n\n/**\n * Hook to access the stateless API client singleton\n * Must be used within an ApiClientProvider\n * @returns Stateless SemiontApiClient instance\n */\nexport function useApiClient(): SemiontApiClient {\n  const context = useContext(ApiClientContext);\n\n  if (context === undefined) {\n    throw new Error('useApiClient must be used within an ApiClientProvider');\n  }\n\n  return context;\n}\n"],"mappings":";;;AAEA,SAAS,eAAe,YAAY,cAA8B;AAClE,SAAS,gBAAgB;AA0BrB;AAxBJ,IAAM,kBAAkB,cAA+B,IAAI;AAgBpD,SAAS,iBAAiB,EAAE,SAAS,GAA0B;AACpE,QAAM,cAAc,OAAwB,IAAI;AAChD,MAAI,CAAC,YAAY,SAAS;AACxB,gBAAY,UAAU,IAAI,SAAS;AAAA,EACrC;AACA,QAAM,WAAW,YAAY;AAE7B,SACE,oBAAC,gBAAgB,UAAhB,EAAyB,OAAO,UAC9B,UACH;AAEJ;AA4BO,SAAS,cAAwB;AACtC,QAAM,WAAW,WAAW,eAAe;AAC3C,MAAI,CAAC,UAAU;AACb,UAAM,IAAI,MAAM,kDAAkD;AAAA,EACpE;AACA,SAAO;AACT;;;ACjEA,SAAS,iBAAAA,gBAAe,cAAAC,aAAuB,eAAe;AAC9D,SAAS,eAAe;AACxB,SAAS,wBAA6C;AA0ClD,gBAAAC,YAAA;AAvCJ,IAAM,mBAAmBC,eAA4C,MAAS;AAoBvE,SAAS,kBAAkB;AAAA,EAChC,SAAS;AAAA,EACT;AAAA,EACA;AACF,GAA2B;AACzB,QAAM,WAAW,YAAY;AAE7B,QAAM,SAAS;AAAA,IACb,MAAM,IAAI,iBAAiB;AAAA,MACzB,SAAS,QAAQ,GAAG;AAAA,MACpB;AAAA;AAAA,MAEA,GAAI,QAAQ,IAAI,aAAa,UAAU,EAAE,SAAS,IAAM;AAAA,MACxD,GAAI,kBAAkB,EAAE,eAAe;AAAA,IACzC,CAAC;AAAA,IACD,CAAC,KAAK,UAAU,cAAc;AAAA,EAChC;AAEA,SACE,gBAAAD,KAAC,iBAAiB,UAAjB,EAA0B,OAAO,QAC/B,UACH;AAEJ;AAOO,SAAS,eAAiC;AAC/C,QAAM,UAAUE,YAAW,gBAAgB;AAE3C,MAAI,YAAY,QAAW;AACzB,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACzE;AAEA,SAAO;AACT;","names":["createContext","useContext","jsx","createContext","useContext"]}