@warkypublic/svelix 0.1.33 → 0.1.35

package/dist/components/GlobalStateStore/GlobalStateStore.d.ts

@@ -9,14 +9,14 @@ type GlobalStateStoreApi = {
 declare const createGlobalStateStore: () => GlobalStateStoreApi;
 declare const GlobalStateStore: GlobalStateStoreApi;
 declare const languageStore: Readable<SupportedLanguage>;
+declare const isLoggedInStore: Readable<boolean>;
 declare function useGlobalStateStore(): Readable<GlobalStateStoreType>;
 declare function useGlobalStateStore<T>(selector: (state: GlobalStateStoreType) => T): Readable<T>;
 declare const setApiURL: (url: string) => void;
 declare const getApiURL: () => string;
 declare const getAuthToken: () => string;
-declare const isLoggedIn: () => boolean;
 declare const setAuthToken: (token: string) => void;
 declare const GetGlobalState: () => GlobalStateStoreType;
 declare const setLanguage: (lang: SupportedLanguage) => void;
 export type { GlobalStateStoreApi };
-export { createGlobalStateStore, getApiURL, getAuthToken, GetGlobalState, GlobalStateStore, isLoggedIn, languageStore, setApiURL, setAuthToken, setLanguage, useGlobalStateStore, };
+export { createGlobalStateStore, getApiURL, getAuthToken, GetGlobalState, GlobalStateStore, isLoggedInStore, languageStore, setApiURL, setAuthToken, setLanguage, useGlobalStateStore, };

package/dist/components/GlobalStateStore/GlobalStateStore.js

@@ -102,20 +102,50 @@ const hasSessionValidationSignal = (session, user) => {
         user?.guid ||
         user?.username);
 };
+const computeIsLoggedIn = (session) => {
+    if (!session.validated || !session.loggedIn || !session.authToken) {
+        return false;
+    }
+    return !isSessionExpired(session);
+};
 const createGlobalStateStore = () => {
     const initialState = createInitialState();
     let isStorageInitialized = false;
     let initializationPromise = null;
     let operationLock = Promise.resolve();
+    let hasAutoValidated = false;
+    let validationScheduled = false;
+    const scheduleValidation = () => {
+        if (validationScheduled)
+            return;
+        validationScheduled = true;
+        waitForInitialization()
+            .then(() => withOperationLock(() => fetchDataInternal()))
+            .finally(() => {
+            validationScheduled = false;
+        });
+    };
     const store = writable(undefined);
     const getState = () => get(store);
     const setState = (partial, replace = false) => {
+        const before = get(store);
         store.update((current) => {
             const nextPartial = typeof partial === "function" ? partial(current) : partial;
             return replace
                 ? nextPartial
                 : { ...current, ...nextPartial };
         });
+        const after = get(store);
+        const handlerJustRegistered = !hasAutoValidated &&
+            typeof after.onFetchSession === "function" &&
+            typeof before?.onFetchSession !== "function";
+        if (handlerJustRegistered) {
+            hasAutoValidated = true;
+            const session = after.session;
+            if (hasSessionCredentials(session) && !session.validated) {
+                scheduleValidation();
+            }
+        }
     };
     const setGlobalState = (partial) => {
         setState((state) => {
@@ -152,8 +182,8 @@ const createGlobalStateStore = () => {
         }));
         try {
             const currentState = getState();
+            const hasFetchHandler = typeof currentState.onFetchSession === "function";
             const result = await currentState.onFetchSession?.(currentState);
-            const hasExistingSession = hasSessionCredentials(currentState.session);
             const nextUser = { ...currentState.user, ...result?.user };
             const nextSession = {
                 ...currentState.session,
@@ -162,6 +192,14 @@ const createGlobalStateStore = () => {
                 connected: true,
                 loading: false,
             };
+            if (!hasFetchHandler) {
+                setGlobalState((state) => ({
+                    ...state,
+                    session: { ...state.session, connected: true, loading: false },
+                }));
+                return;
+            }
+            const hasExistingSession = hasSessionCredentials(currentState.session);
             const serverConfirmsSession = result?.session?.loggedIn === true || Boolean(result?.session?.authToken);
             const serverConfirmsUser = Boolean(result?.user?.guid || result?.user?.username);
             const alreadyValidated = currentState.session.validated === true;
@@ -237,16 +275,7 @@ const createGlobalStateStore = () => {
             await waitForInitialization();
             return withOperationLock(() => fetchDataInternal(url));
         },
-        isLoggedIn: () => {
-            const session = getState().session;
-            if (!session.validated || !session.loggedIn || !session.authToken) {
-                return false;
-            }
-            if (isSessionExpired(session)) {
-                return false;
-            }
-            return true;
-        },
+        isLoggedIn: () => computeIsLoggedIn(getState().session),
         login: async (authToken, user) => {
             await waitForInitialization();
             return withOperationLock(async () => {
@@ -442,9 +471,6 @@ const createGlobalStateStore = () => {
                 ...loadedState.session,
                 connected: true,
                 loading: false,
-                loggedIn: hasPersistedSession
-                    ? false
-                    : loadedState.session?.loggedIn ?? current.session.loggedIn,
                 validated: hasPersistedSession
                     ? false
                     : loadedState.session?.validated ?? current.session.validated,
@@ -463,6 +489,12 @@ const createGlobalStateStore = () => {
         if (!isStorageInitialized) {
             return;
         }
+        if (hasSessionCredentials(state.session) &&
+            !state.session.validated &&
+            !computeIsLoggedIn(state.session) &&
+            typeof state.onFetchSession === "function") {
+            scheduleValidation();
+        }
         saveStorage(toPersistedState(state)).catch((e) => {
             console.error("Error saving storage:", e);
         });
@@ -478,6 +510,7 @@ const GlobalStateStoreReadable = {
     subscribe: GlobalStateStore.subscribe,
 };
 const languageStore = derived(GlobalStateStoreReadable, (state) => state.user.language ?? "en");
+const isLoggedInStore = derived(GlobalStateStoreReadable, (state) => computeIsLoggedIn(state.session));
 initTranslation(languageStore);
 function useGlobalStateStore(selector) {
     if (!selector) {
@@ -494,9 +527,6 @@ const getApiURL = () => {
 const getAuthToken = () => {
     return GlobalStateStore.getState().session.authToken ?? "";
 };
-const isLoggedIn = () => {
-    return GlobalStateStore.getState().isLoggedIn();
-};
 const setAuthToken = (token) => {
     GlobalStateStore.getState().setAuthToken(token);
 };
@@ -506,4 +536,4 @@ const GetGlobalState = () => {
 const setLanguage = (lang) => {
     GlobalStateStore.getState().setLanguage(lang);
 };
-export { createGlobalStateStore, getApiURL, getAuthToken, GetGlobalState, GlobalStateStore, isLoggedIn, languageStore, setApiURL, setAuthToken, setLanguage, useGlobalStateStore, };
+export { createGlobalStateStore, getApiURL, getAuthToken, GetGlobalState, GlobalStateStore, isLoggedInStore, languageStore, setApiURL, setAuthToken, setLanguage, useGlobalStateStore, };

package/dist/components/GlobalStateStore/GlobalStateStore.mdx

@@ -0,0 +1,209 @@
+# GlobalStateStore
+
+Singleton Svelte store for app-wide authenticated state. Persists all slices to `localStorage` and re-validates credentials on every page load.
+
+---
+
+## Setup
+
+Wrap your app with `GlobalStateStoreProvider` and wire up the three server callbacks:
+
+```svelte
+<script lang="ts">
+  import { GlobalStateStoreProvider } from '@warkypublic/svelix';
+
+  const onLogin = async (state) => {
+    const res = await api.post('/auth/login', { token: state.session.authToken });
+    return { session: res.session, user: res.user };
+  };
+
+  const onLogout = async () => {
+    await api.post('/auth/logout');
+  };
+
+  const onFetchSession = async (state) => {
+    const res = await api.get('/app/bootstrap');
+    return { session: res.session, user: res.user, navigation: res.nav, program: res.program };
+  };
+</script>
+
+<GlobalStateStoreProvider {onLogin} {onLogout} {onFetchSession}>
+  {@render children()}
+</GlobalStateStoreProvider>
+```
+
+### Provider props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `apiURL` | `string` | — | Sets `session.apiURL` on mount |
+| `autoFetch` | `boolean` | `true` | Enables automatic `fetchData` calls |
+| `fetchOnMount` | `boolean` | `true` | Calls `fetchData` once after mount |
+| `onFetchSession` | `fn` | — | Called by `fetchData`; must return state slice or void |
+| `onLogin` | `fn` | — | Called after credentials are set; return confirms the session |
+| `onLogout` | `fn` | — | Called during logout |
+| `program` | `Partial<ProgramState>` | — | Merged into `program` slice on mount |
+| `throttleMs` | `number` | `0` | Minimum ms between `fetchData` calls |
+
+---
+
+## State slices
+
+### `session`
+
+| Field | Type | Description |
+|---|---|---|
+| `apiURL` | `string` | Base API URL |
+| `authToken` | `string` | Bearer token |
+| `loggedIn` | `boolean` | Persisted login intent |
+| `validated` | `boolean` | Server has confirmed the session this load |
+| `expiryDate` | `string` | ISO date; `isLoggedIn` returns false after this |
+| `connected` | `boolean` | Last fetch succeeded |
+| `loading` | `boolean` | Fetch in progress |
+| `error` | `string` | Last fetch error message |
+
+### `user`
+
+`guid`, `username`, `email`, `fullNames`, `language`, `isAdmin`, `avatarUrl`, `theme`, `parameters`
+
+### `owner`
+
+`id`, `guid`, `name`, `logo`, `settings`, `theme`
+
+### `program`
+
+`guid`, `name`, `slug`, `environment`, `version`, `controls`, `globals`, `database`, `meta`
+
+### `layout`
+
+`topBar`, `leftBar`, `rightBar`, `bottomBar` — each is `{ open, pinned, size, collapsed, menuItems }`
+
+### `navigation`
+
+`menu: MenuItem[]`, `currentPage: { title, path, breadcrumbs, meta }`
+
+---
+
+## Auth lifecycle
+
+```
+login(token)
+  → sets authToken, loggedIn:false, validated:false
+  → calls onLogin  ──► server confirms  → loggedIn:true, validated:true
+  → calls fetchData (onFetchSession)    → merges server state
+```
+
+```
+logout()
+  → clears all auth state, loading:true
+  → calls onLogout
+  → calls fetchData (onFetchSession)
+```
+
+```
+fetchData(url?)
+  → no-op if onFetchSession not registered
+  → calls onFetchSession
+  → validates or clears session (see Session Validation below)
+```
+
+---
+
+## Session validation
+
+Credentials from `localStorage` start each page load as `loggedIn: true, validated: false`. `isLoggedInStore` emits `false` until validated.
+
+Validation is triggered automatically — no manual call needed — in priority order:
+
+1. **`onFetchSession` registered** while unvalidated credentials exist (`setState` detects handler transition)
+2. **Any state change** with unvalidated credentials + handler present (`store.subscribe`)
+
+`fetchData` clears the session when the server response indicates invalidity:
+
+| Condition | Result |
+|---|---|
+| `onFetchSession` not registered | No-op, session unchanged |
+| Server returns no session/user fields | Session preserved, `validated` stays `false` |
+| Server returns `loggedIn: false` | Session cleared |
+| Server returns a different `authToken` | Session cleared |
+| Server returns a different `user.guid` or `username` | Session cleared |
+| `expiryDate` is in the past | Session cleared |
+| Server confirms credentials | `validated: true`, session kept |
+
+---
+
+## Reactive usage (Svelte components)
+
+```svelte
+<script lang="ts">
+  import { isLoggedInStore, useGlobalStateStore } from '@warkypublic/svelix';
+
+  const username = useGlobalStateStore((s) => s.user.username);
+</script>
+
+{#if $isLoggedInStore}
+  <p>Welcome, {$username}</p>
+{/if}
+```
+
+### Reactive stores
+
+| Export | Type | Value |
+|---|---|---|
+| `isLoggedInStore` | `Readable<boolean>` | `true` only when `loggedIn && validated && !expired` |
+| `languageStore` | `Readable<'en' \| 'af'>` | `user.language` |
+| `useGlobalStateStore(selector?)` | `Readable<T>` | Derived slice of the full store |
+
+---
+
+## Imperative usage (outside components)
+
+```ts
+import { GlobalStateStore, getAuthToken, getApiURL, setAuthToken, setApiURL } from '@warkypublic/svelix';
+
+const state = GlobalStateStore.getState();
+
+await state.login('my-token');
+await state.logout();
+await state.fetchData();
+
+state.isLoggedIn();          // boolean — checks validated + loggedIn + authToken + expiry
+state.setAuthToken('token');
+state.setApiURL('https://api.example.com');
+state.setUser({ username: 'alice' });
+state.setSession({ expiryDate: '2099-01-01T00:00:00.000Z' });
+
+getAuthToken();  // shorthand
+getApiURL();
+setAuthToken('token');
+setApiURL('https://api.example.com');
+```
+
+---
+
+## Persistence
+
+All slices are written to `localStorage` under `APP_GLO:<slice>` on every state change.
+
+**Not persisted:** `session.connected`, `session.error`, `session.loading`, `session.validated`
+
+On load, `validated` is forced to `false` when credentials exist. `loggedIn` is preserved as-is so the UI can optimistically render the logged-in shell while re-validation completes in the background.
+
+---
+
+## Callback return shapes
+
+```ts
+// onLogin / onLogout
+Promise<{
+  session?: Partial<SessionState>;
+  user?: Partial<UserState>;
+  owner?: Partial<OwnerState>;
+  program?: Partial<ProgramState>;
+} | void>
+
+// onFetchSession  (superset — also accepts layout + navigation)
+Promise<Partial<GlobalState>>
+```
+
+Return only the fields that changed. Omitted fields are left as-is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warkypublic/svelix",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "Svelte 5 component library with Skeleton UI and Tailwind CSS",
   "license": "Apache-2.0",
   "exports": {