@lowdefy/client 6.1.0 → 7.0.0

package/dist/createPageLifecycleManager.js

@@ -0,0 +1,172 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ // Page lifecycle events. Browser signals a page can react to, so apps do not
+// have to poll to notice that a tab went away and came back, that the network
+// dropped, or that the window was resized.
+//
+// - onVisible  document became visible again, or the window regained focus.
+// - onHidden   document became hidden, or the window lost focus.
+// - onOnline   the browser reports the network is back.
+// - onOffline  the browser reports the network is gone.
+// - onResize   the window was resized.
+//
+// None of these fire on the initial page load - the active state is seeded from
+// the document when the page mounts, and only transitions away from that seed
+// trigger an event.
+//
+// The same resize listener keeps _media current: once a resize settles, the
+// engine re-evaluates the blocks that read a media value that changed.
+const VISIBILITY_DEBOUNCE_MS = 300;
+const RESIZE_DEBOUNCE_MS = 150;
+function createPageLifecycleManager() {
+    let destroyed = false;
+    let removeListeners = [];
+    let timeouts = [];
+    function init(context) {
+        destroyed = false;
+        const globals = context?._internal?.lowdefy?._internal?.globals ?? {};
+        const win = globals.window;
+        const doc = globals.document;
+        // Server side render guard - there are no browser listeners to attach to.
+        if (typeof document === 'undefined' || !win || !doc) return;
+        if (typeof win.addEventListener !== 'function' || typeof doc.addEventListener !== 'function') {
+            return;
+        }
+        const events = context._internal.rootBlock?.events ?? {};
+        const configured = (name)=>!!events[name];
+        const trigger = (name, event)=>{
+            if (destroyed) return;
+            // Page lifecycle chains run like onMountAsync - non blocking, and a
+            // failure in the chain must not break the page.
+            try {
+                Promise.resolve(context._internal.triggerPageEvent({
+                    name,
+                    event
+                })).catch((error)=>{
+                    context._internal.lowdefy._internal.handleError?.(error);
+                });
+            } catch (error) {
+                context._internal.lowdefy._internal.handleError?.(error);
+            }
+        };
+        const setTimer = (fn, ms)=>{
+            const timeout = setTimeout(()=>{
+                timeouts = timeouts.filter((t)=>t !== timeout);
+                fn();
+            }, ms);
+            timeouts.push(timeout);
+            return timeout;
+        };
+        const listen = (target, name, handler)=>{
+            target.addEventListener(name, handler);
+            removeListeners.push(()=>target.removeEventListener(name, handler));
+        };
+        // --- onVisible / onHidden ------------------------------------------------
+        if (configured('onVisible') || configured('onHidden')) {
+            // Seeded from the document so the initial load never fires an event.
+            let active = doc.visibilityState !== 'hidden';
+            let pending = null;
+            const flush = ()=>{
+                const next = pending;
+                pending = null;
+                if (destroyed || !next) return;
+                // A focus that only restores a state we are already in is not an event.
+                if (next.active === active) return;
+                active = next.active;
+                trigger(next.active ? 'onVisible' : 'onHidden', {
+                    visible: next.active,
+                    reason: next.reason
+                });
+            };
+            // A tab coming back to the front fires visibilitychange and focus. Both
+            // are collected into one window so the event chain only runs once.
+            const signal = (nextActive, reason)=>{
+                if (destroyed) return;
+                if (pending) {
+                    pending.active = nextActive;
+                    // A visibilitychange is the more precise reason, so it wins the pair.
+                    if (reason === 'visibility') pending.reason = 'visibility';
+                    return;
+                }
+                pending = {
+                    active: nextActive,
+                    reason
+                };
+                setTimer(flush, VISIBILITY_DEBOUNCE_MS);
+            };
+            listen(doc, 'visibilitychange', ()=>{
+                signal(doc.visibilityState !== 'hidden', 'visibility');
+            });
+            listen(win, 'focus', ()=>signal(true, 'focus'));
+            listen(win, 'blur', ()=>signal(false, 'focus'));
+        }
+        // --- onOnline / onOffline ------------------------------------------------
+        if (configured('onOnline')) {
+            listen(win, 'online', ()=>trigger('onOnline', {
+                    online: true
+                }));
+        }
+        if (configured('onOffline')) {
+            listen(win, 'offline', ()=>trigger('onOffline', {
+                    online: false
+                }));
+        }
+        // --- onResize and _media -------------------------------------------------
+        // The operator registry holds the operators of every page loaded so far, so
+        // a page that can not reach _media attaches no listener for it.
+        const watchMedia = !!context._internal.lowdefy._internal.operators._media;
+        const onResize = configured('onResize');
+        if (watchMedia || onResize) {
+            let resizeTimeout = null;
+            // One trailing debounce for the whole page: a drag fires resize at frame
+            // rate, and this evaluates once when it settles. A requestAnimationFrame
+            // throttle would evaluate every frame of the drag instead.
+            const flush = ()=>{
+                resizeTimeout = null;
+                if (destroyed) return;
+                // Blocks first, so onResize actions see the page evaluated at the new size.
+                if (watchMedia) {
+                    context._internal.updateMedia();
+                }
+                if (onResize) {
+                    trigger('onResize', {
+                        width: win.innerWidth,
+                        height: win.innerHeight
+                    });
+                }
+            };
+            listen(win, 'resize', ()=>{
+                if (resizeTimeout) {
+                    clearTimeout(resizeTimeout);
+                    timeouts = timeouts.filter((t)=>t !== resizeTimeout);
+                }
+                resizeTimeout = setTimer(flush, RESIZE_DEBOUNCE_MS);
+            });
+        }
+    }
+    function destroy() {
+        destroyed = true;
+        removeListeners.forEach((remove)=>remove());
+        removeListeners = [];
+        timeouts.forEach((timeout)=>clearTimeout(timeout));
+        timeouts = [];
+    }
+    return {
+        init,
+        destroy
+    };
+}
+export { RESIZE_DEBOUNCE_MS, VISIBILITY_DEBOUNCE_MS };
+export default createPageLifecycleManager;

package/dist/formatIconTitle.js

@@ -0,0 +1,26 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+// Pencil -> "Pencil", ArrowLeftRight -> "Arrow left right", more-vertical ->
+// "More vertical", lucide:Pencil -> "Pencil".
+function formatIconTitle(name) {
+    if (!type.isString(name)) {
+        return '';
+    }
+    const iconName = name.slice(name.indexOf(':') + 1);
+    const words = iconName.replace(/-/g, ' ').replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+export default formatIconTitle;

package/dist/getActiveLocale.js

@@ -0,0 +1,27 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+// A language tag: a 2–3 letter language and optional subtags ("en", "en-US",
+// "zh-Hant-TW"). Intl throws on anything else, such as "en_US".
+const LANGUAGE_TAG = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$/;
+// The app's active locale that useLocale publishes, for formatting HTML dates
+// and numbers. Undefined (the browser's locale) when the app has no i18n or the
+// code is not a language tag Intl accepts.
+function getActiveLocale(window) {
+    const locale = window.__lowdefy_locale;
+    if (!type.isString(locale) || !LANGUAGE_TAG.test(locale)) return undefined;
+    return locale;
+}
+export default getActiveLocale;

package/dist/getContextKey.js

@@ -0,0 +1,29 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ const contextKeys = new WeakMap();
+let lastKey = 0;
+// A React key per engine context object. A page context rebuilt in place - an
+// organization switch, a dev config reset - is a new object under the same
+// instance key, and keying the page tree by it remounts the tree onto the new
+// context rather than reconciling mounted blocks against it, which React can
+// silently drop.
+function getContextKey(context) {
+    if (!contextKeys.has(context)) {
+        lastKey += 1;
+        contextKeys.set(context, lastKey);
+    }
+    return contextKeys.get(context);
+}
+export default getContextKey;

package/dist/getMessageIcon.js

@@ -0,0 +1,43 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ // Engine and DisplayMessage messages render through antd's App holders, above
+// the page's ConfigProvider, so each message carries its status icon itself.
+const messageIcons = {
+    error: {
+        name: 'error',
+        title: ''
+    },
+    info: {
+        name: 'info',
+        title: ''
+    },
+    loading: {
+        name: 'loading',
+        spin: true,
+        title: ''
+    },
+    success: {
+        name: 'success',
+        title: ''
+    },
+    warning: {
+        name: 'warning',
+        title: ''
+    }
+};
+function getMessageIcon({ status }) {
+    return messageIcons[status];
+}
+export default getMessageIcon;

package/dist/hasOtherRoles.js

@@ -0,0 +1,30 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { rolesHash, type } from '@lowdefy/helpers';
+// True when the server answered the rendered caller with other roles than the
+// page renders - a role was granted or taken away since the page loaded - so
+// _user.roles and role-gated blocks would show access the person no longer
+// holds, or hide access they now have. stamp is the response's parsed
+// x-lowdefy-caller header, user the rendered caller. A stamp that names no
+// roles (no header, or an anonymous caller) claims none.
+function hasOtherRoles({ stamp, user }) {
+    if (type.isNone(user) || type.isNone(stamp?.roles)) {
+        return false;
+    }
+    return stamp.roles !== rolesHash({
+        user
+    });
+}
+export default hasOtherRoles;

package/dist/index.js

@@ -15,5 +15,6 @@
 */ import Client from './Client.js';
 export default Client;
 export { default as getOrCreateAntdCssContainer } from './getOrCreateAntdCssContainer.js';
+export { default as IconProvider } from './IconProvider.js';
 export { default as useDarkMode } from './useDarkMode.js';
 export { default as useLocale } from './useLocale.js';

package/dist/initLowdefyContext.js

@@ -12,25 +12,52 @@
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-*/ import { translate } from '@lowdefy/helpers';
+*/ import React from 'react';
+import { registerHtmlEnhancements } from '@lowdefy/block-utils';
+import { rememberPath, resolveTarget } from '@lowdefy/engine';
+import { translate, type } from '@lowdefy/helpers';
 import createCallAPI from './createCallAPI.js';
 import createAuthMethods from './auth/createAuthMethods.js';
 import createCallRequest from './createCallRequest.js';
 import createWebSocketClient from './websocket/createWebSocketClient.js';
 import createIcon from './createIcon.js';
 import createShortcutBadge from './createShortcutBadge.js';
+import createStorage from './storage/createStorage.js';
 import createLinkComponent from './createLinkComponent.js';
 import createHandleError from './createHandleError.js';
+import getActiveLocale from './getActiveLocale.js';
 import { createBrowserLogger } from '@lowdefy/logger/browser';
+import setLowdefyUser from './setLowdefyUser.js';
 import setupLink from './setupLink.js';
-function initLowdefyContext({ auth, Components, config, lowdefy, router, stage, types, window }) {
+import { createUrl } from './adapters/url.js';
+// loadAllIcons (production server only) loads every icon the app bundles into
+// types.icons; a page loads only its own icons, so a name that arrives at
+// runtime may need it. Dev and e2e bundle every icon.
+//
+// matchedPath and pathParams are the server's match of the shown page: the
+// path it was matched on (no basePath, no leading "/") and the values it
+// carries.
+function initLowdefyContext({ auth, Components, config, loadAllIcons, lowdefy, matchedPath, pathParams, router, stage, types, window }) {
+    // The path memory lasts the session. A dev config reload clears initialised
+    // to rebuild the page contexts, but the paths this tab followed still name
+    // the same pages, and the page response it fetches next rewrites its own.
+    if (type.isUndefined(lowdefy.pathMemory)) {
+        lowdefy.pathMemory = new Map();
+    }
     if (!lowdefy._internal?.initialised) {
         lowdefy._internal = {
             actions: types.actions,
             blockComponents: types.blocks,
             blockMetas: types.blockMetas ?? {},
+            // The last caller stamp a response carried (recordCallerStamp). It names
+            // the session, not the page context, so it outlives a dev config reload,
+            // and the dev server records the first page config's before this runs.
+            callerStamp: lowdefy._internal?.callerStamp ?? null,
             components: {
-                Icon: createIcon(types.icons),
+                Icon: createIcon({
+                    icons: types.icons,
+                    loadAllIcons
+                }),
                 ShortcutBadge: createShortcutBadge(lowdefy)
             },
             displayMessage: ({ content })=>{
@@ -54,12 +81,21 @@ function initLowdefyContext({ auth, Components, config, lowdefy, router, stage,
             router
         };
         lowdefy.apiResponses = {};
+        // Rebuilt with the page contexts, so a dev config reload runs the app events again.
+        lowdefy.appContext = null;
         lowdefy.basePath = router.basePath;
         lowdefy.contexts = {};
         lowdefy.inputs = {};
+        lowdefy.pageInstances = {};
         lowdefy.lowdefyApp = config.rootConfig.lowdefyApp;
         lowdefy.lowdefyGlobal = config.rootConfig.lowdefyGlobal;
         lowdefy.theme = config.rootConfig.theme ?? {};
+        lowdefy._internal.storage = createStorage({
+            basePath: lowdefy.basePath,
+            getUserId: ()=>lowdefy.user?.id ?? null,
+            slug: lowdefy.lowdefyApp?.slug,
+            window
+        });
         lowdefy._internal.callAPI = createCallAPI(lowdefy);
         lowdefy._internal.auth = createAuthMethods(lowdefy, auth);
         lowdefy._internal.callRequest = createCallRequest(lowdefy);
@@ -74,14 +110,77 @@ function initLowdefyContext({ auth, Components, config, lowdefy, router, stage,
         lowdefy._internal.logger = createBrowserLogger();
         lowdefy._internal.handleError = createHandleError(lowdefy);
         lowdefy._internal.components.handleError = lowdefy._internal.handleError;
+        // HtmlComponent (block-utils) gives data-* attributes meaning in every
+        // sanitised HTML string. The overlay pulls in antd Tooltip and Popover, so
+        // it loads the first time HTML needs one. Links build hrefs with createUrl,
+        // the one place basePath is applied, and navigate like the Link action. A
+        // page link's pathname comes from resolveTarget, as the Link action's does.
+        registerHtmlEnhancements({
+            createHref: ({ pathname, query })=>createUrl({
+                    basePath: lowdefy.basePath,
+                    pathname,
+                    query
+                }),
+            createPageHref: ({ pageId, pathParams, urlQuery })=>{
+                const target = resolveTarget({
+                    lowdefy,
+                    target: {
+                        pageId,
+                        pathParams,
+                        urlQuery
+                    }
+                });
+                return createUrl({
+                    basePath: lowdefy.basePath,
+                    pathname: target.pathname,
+                    query: target.query
+                });
+            },
+            getLocale: ()=>getActiveLocale(window),
+            // The overlay is lazy, so the app's Icon is bound in when it loads.
+            HtmlOverlay: /*#__PURE__*/ React.lazy(async ()=>{
+                const { default: HtmlOverlay } = await import('./HtmlOverlay.js');
+                const Icon = lowdefy._internal.components.Icon;
+                function HtmlOverlayWithIcon(props) {
+                    return /*#__PURE__*/ React.createElement(HtmlOverlay, {
+                        ...props,
+                        Icon: Icon
+                    });
+                }
+                return {
+                    default: HtmlOverlayWithIcon
+                };
+            }),
+            Icon: lowdefy._internal.components.Icon,
+            icons: types.icons,
+            link: lowdefy._internal.link,
+            loadAllIcons,
+            translate: lowdefy._internal.translate
+        });
         if (stage === 'dev' || stage === 'e2e') {
             window.lowdefy = lowdefy;
         }
     }
     lowdefy.home = config.rootConfig.home || {};
+    lowdefy.linkPaths = config.pageConfig.linkPaths;
     lowdefy.menus = config.rootConfig.menus;
     lowdefy.pageId = config.pageConfig.pageId;
-    lowdefy.user = auth?.session?.user ?? null;
+    lowdefy.pagePaths = config.rootConfig.pagePaths;
+    setLowdefyUser({
+        lowdefy,
+        user: auth?.user
+    });
+    // Runs on every render, so it sees the person signed in on load and any later change.
+    lowdefy._internal.storage.clearUserStorageOnOwnerChange();
+    // The shown page's path joins the path memory before its context is built,
+    // so the first load's page is known before any plugin reads the memory.
+    rememberPath({
+        lowdefy,
+        path: matchedPath,
+        pageId: config.pageConfig.pageId,
+        pathParams,
+        pattern: config.pageConfig.path
+    });
     return lowdefy;
 }
 export default initLowdefyContext;

package/dist/isOtherCaller.js

@@ -0,0 +1,29 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { callerHash, type } from '@lowdefy/helpers';
+// True when the server answered as another caller than the one this page
+// renders: stamp is the response's parsed x-lowdefy-caller header (see the
+// server's stampCaller and parseCallerStamp), user the rendered caller.
+function isOtherCaller({ stamp, user }) {
+    // A response with no header was not answered by a route that resolved a
+    // caller (it failed before, or came from a proxy), so it claims no caller.
+    if (type.isNone(stamp)) {
+        return false;
+    }
+    return stamp.caller !== callerHash({
+        user
+    });
+}
+export default isOtherCaller;

package/dist/recordCallerStamp.js

@@ -0,0 +1,31 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { parseCallerStamp, type } from '@lowdefy/helpers';
+// Keeps the last caller stamp a response carried (see the server's stampCaller)
+// on lowdefy._internal.callerStamp, as { caller, session, roles, memberships }:
+// who the server last answered as, in full. A response with no header claims
+// no caller and leaves the last stamp in place.
+function recordCallerStamp({ lowdefy, serverCaller }) {
+    const stamp = parseCallerStamp(serverCaller);
+    if (type.isNone(stamp)) {
+        return;
+    }
+    // The dev server fetches the first page config before the page context exists
+    // (initLowdefyContext), which carries this stamp over when it builds
+    // _internal.
+    lowdefy._internal = lowdefy._internal ?? {};
+    lowdefy._internal.callerStamp = stamp;
+}
+export default recordCallerStamp;

package/dist/renderIconNodes.js

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import React from 'react';
+const shapeTags = new Set([
+    'circle',
+    'ellipse',
+    'line',
+    'path',
+    'polygon',
+    'polyline',
+    'rect'
+]);
+// lucide-react applies vector-effect only to the top-level nodes it renders
+// itself; icon data goes in as children, so shapes at every depth get it here.
+function renderIconNodes({ node, nonScalingStroke }) {
+    return node.map(([tag, attrs, children], index)=>{
+        const props = nonScalingStroke && shapeTags.has(tag) ? {
+            vectorEffect: 'non-scaling-stroke',
+            ...attrs,
+            key: index
+        } : {
+            ...attrs,
+            key: index
+        };
+        if (!children) {
+            return /*#__PURE__*/ React.createElement(tag, props);
+        }
+        return /*#__PURE__*/ React.createElement(tag, props, renderIconNodes({
+            node: children,
+            nonScalingStroke
+        }));
+    });
+}
+export default renderIconNodes;