@faclon-labs/app-sdk 0.3.0 → 0.4.0

package/dist/IOSenseApp.js

@@ -5,6 +5,7 @@ import { configure, getConfig } from './config.js';
 import { publishSession } from './request.js';
 import { SAMPLE_NOTICE, SessionContext, useIOSense } from './session.js';
 import { SignIn } from './SignIn.js';
+import { startHostLook } from './host-look.js';
 /**
  * The root of an IOSense app: the session, and the sign-in screen when there is none.
  *
@@ -18,6 +19,8 @@ export function IOSenseApp({ name, auth = 'required', sample, apiBaseUrl, signIn
     const api = getConfig().apiBaseUrl;
     // Once, before the first child renders, so the first paint already has the session.
     const [phase, setPhase] = useState(() => {
+        // Framed in I/O Sense, the app may wear its look (chosen in the sidebar): asked for at once.
+        startHostLook();
         if (auth === 'none')
             return { kind: 'ready', token: null };
         const how = adoptHostSession();

package/dist/host-look.d.ts

@@ -0,0 +1,29 @@
+/**
+ * I/O Sense's look, worn over the app's own design system when the person chose it for this app in
+ * their sidebar. The host works out the variables for the app's own library (shadcn's `--primary`,
+ * MUI's `--mui-palette-primary-main`, a company library's own token names) and sends them; this puts
+ * them on the page over the library's, and follows each change the host sends, with no reload.
+ * Outside I/O Sense, or with the app's own look chosen, it does nothing.
+ */
+export interface HostLook {
+    mode: 'light' | 'dark';
+    vars: Record<string, string>;
+    /** More selectors that hold the library's variables themselves (Ant Design's `.css-var-*`). */
+    scope?: string[];
+    /** The `data-theme` the library's own light/dark switch reads. */
+    theme?: string;
+    /** A Google Fonts stylesheet. */
+    fonts?: string;
+}
+/** Read and clean a look from the host; null for "its own look", undefined for nonsense. */
+export declare function hostLookOf(raw: unknown): HostLook | null | undefined;
+/** The stylesheet a look makes: its variables over the library's, whatever the library's selectors. */
+export declare function hostLookCss(look: HostLook): string;
+/** Put a look on the page, or take it off (null). */
+export declare function wearHostLook(look: HostLook | null): void;
+/**
+ * Ask the host for its look and follow what it sends. Once per page; `<IOSenseApp>` calls it before
+ * its first render. The question carries nothing, so it may go to any parent; only a trusted host's
+ * answer is worn.
+ */
+export declare function startHostLook(): void;

package/dist/host-look.js

@@ -0,0 +1,115 @@
+import { isEmbedded, isTrustedHostOrigin } from './auth.js';
+const STYLE_ID = 'iosense-host-look';
+const FONTS_ID = 'iosense-host-look-fonts';
+const NAME = /^--[\w-]+$/;
+/** A value can say a colour, a length or a font stack; never end the rule or open another. */
+const VALUE = /^[^;{}<>\\]*$/;
+const SELECTOR = /^[\w\s\-[\]="*^$.:#>+~(),]+$/;
+let started = false;
+let worn = null;
+/** What the page had before the look, put back when it is taken off. */
+let before = null;
+let guard = null;
+/** Read and clean a look from the host; null for "its own look", undefined for nonsense. */
+export function hostLookOf(raw) {
+    if (raw === null)
+        return null;
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const look = raw;
+    if (look.mode !== 'light' && look.mode !== 'dark')
+        return undefined;
+    const vars = {};
+    for (const [name, value] of Object.entries(look.vars ?? {}))
+        if (NAME.test(name) && typeof value === 'string' && VALUE.test(value))
+            vars[name] = value;
+    const scope = Array.isArray(look.scope) ? look.scope.filter((s) => typeof s === 'string' && SELECTOR.test(s)) : [];
+    const theme = typeof look.theme === 'string' && /^[\w-]+$/.test(look.theme) ? look.theme : undefined;
+    const fonts = typeof look.fonts === 'string' && look.fonts.startsWith('https://fonts.googleapis.com/') ? look.fonts : undefined;
+    return { mode: look.mode, vars, ...(scope.length ? { scope } : {}), ...(theme ? { theme } : {}), ...(fonts ? { fonts } : {}) };
+}
+/** The stylesheet a look makes: its variables over the library's, whatever the library's selectors. */
+export function hostLookCss(look) {
+    const body = Object.entries(look.vars)
+        .map(([name, value]) => `  ${name}: ${value} !important;`)
+        .join('\n');
+    return body ? `${[':root', ...(look.scope ?? [])].join(',\n')} {\n${body}\n}\n` : '';
+}
+function setMode(look) {
+    const root = document.documentElement;
+    root.classList.toggle('dark', look.mode === 'dark');
+    root.classList.toggle('light', look.mode === 'light');
+    root.style.colorScheme = look.mode;
+    if (look.theme && root.getAttribute('data-theme') !== look.theme)
+        root.setAttribute('data-theme', look.theme);
+}
+/** Put a look on the page, or take it off (null). */
+export function wearHostLook(look) {
+    const root = document.documentElement;
+    if (look) {
+        if (!before)
+            before = { theme: root.getAttribute('data-theme'), dark: root.classList.contains('dark'), light: root.classList.contains('light'), scheme: root.style.colorScheme };
+        let style = document.getElementById(STYLE_ID);
+        if (!style) {
+            style = document.createElement('style');
+            style.id = STYLE_ID;
+        }
+        style.textContent = hostLookCss(look);
+        // Last in <head>, after the library's own sheets (a dev server adds them later; they still lose to !important).
+        document.head.appendChild(style);
+        const fonts = document.getElementById(FONTS_ID);
+        if (look.fonts && fonts?.href !== look.fonts) {
+            const link = fonts ?? document.createElement('link');
+            link.id = FONTS_ID;
+            link.rel = 'stylesheet';
+            link.href = look.fonts;
+            document.head.appendChild(link);
+        }
+        else if (!look.fonts)
+            fonts?.remove();
+        worn = look;
+        setMode(look);
+        // The app's own switch (main.tsx follows the computer's light or dark) must not undo the host's.
+        if (!guard && typeof MutationObserver !== 'undefined') {
+            guard = new MutationObserver(() => worn && setMode(worn));
+            guard.observe(root, { attributes: true, attributeFilter: ['class', 'data-theme'] });
+        }
+        return;
+    }
+    guard?.disconnect();
+    guard = null;
+    worn = null;
+    document.getElementById(STYLE_ID)?.remove();
+    document.getElementById(FONTS_ID)?.remove();
+    if (before) {
+        if (before.theme === null)
+            root.removeAttribute('data-theme');
+        else
+            root.setAttribute('data-theme', before.theme);
+        root.classList.toggle('dark', before.dark);
+        root.classList.toggle('light', before.light);
+        root.style.colorScheme = before.scheme;
+        before = null;
+    }
+}
+/**
+ * Ask the host for its look and follow what it sends. Once per page; `<IOSenseApp>` calls it before
+ * its first render. The question carries nothing, so it may go to any parent; only a trusted host's
+ * answer is worn.
+ */
+export function startHostLook() {
+    if (started || typeof window === 'undefined' || !isEmbedded())
+        return;
+    started = true;
+    window.addEventListener('message', (event) => {
+        if (event.source !== window.parent || !isTrustedHostOrigin(event.origin))
+            return;
+        const data = event.data;
+        if (!data || data.source !== 'iolens-studio' || data.type !== 'look')
+            return;
+        const look = hostLookOf(data.look);
+        if (look !== undefined)
+            wearHostLook(look);
+    });
+    window.parent.postMessage({ source: 'iosense-app', type: 'look-request', v: 1 }, '*');
+}

package/dist/index.d.ts

@@ -14,3 +14,4 @@ export { fetchLatest, fetchSeries, isSampleTopic, type SeriesPoint } from './dat
 export { request, useRequest, RequestError, isIOSenseHost, type RequestOptions, type UseRequestOptions, type UseRequestResult } from './request.js';
 export { configure, getConfig, type IOSenseConfig } from './config.js';
 export { adoptHostSession, exchangeSsoToken, getToken, setToken, clearToken, isSsoToken, isEmbedded, requestHostSession, isTrustedHostOrigin } from './auth.js';
+export { startHostLook, wearHostLook, type HostLook } from './host-look.js';

package/dist/index.js

@@ -14,3 +14,4 @@ export { fetchLatest, fetchSeries, isSampleTopic } from './data.js';
 export { request, useRequest, RequestError, isIOSenseHost } from './request.js';
 export { configure, getConfig } from './config.js';
 export { adoptHostSession, exchangeSsoToken, getToken, setToken, clearToken, isSsoToken, isEmbedded, requestHostSession, isTrustedHostOrigin } from './auth.js';
+export { startHostLook, wearHostLook } from './host-look.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faclon-labs/app-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "IOSense sign-in, plant data and maps for React apps: the launchpad SSO session, UNS latest values and series, the signed-in user, requests to IOSense's APIs, and the Map Engine on UNS (./map).",
   "type": "module",
   "main": "./dist/index.js",

package/vendor/SOURCE.txt

@@ -1 +1 @@
-Built from MapEngine c5b1f59 — do not edit; run npm run vendor.
+Built from MapEngine c24b05d — do not edit; run npm run vendor.