@ti-engine/web-framework 1.20.0 → 1.21.0

package/bin/static/scripts/ti-framework.js

@@ -1301,6 +1301,320 @@ document.addEventListener( "htmx:responseError", ( event ) => {
     }
 } );
 
+/* ============================================================================================================
+   Read-only "facts" screens — Profile and About.
+
+   Both render the same descriptor shape: an identity header plus an ordered list of titled sections, each
+   holding label/value items. The server decides the content (see TiWebAppManager#getProfileInfo /
+   #getApplicationInfo); everything below only shapes it for the template, so the fragments stay free of
+   formatting logic — which is also what keeps them within Alpine's CSP expression subset.
+   ============================================================================================================ */
+
+/**
+ * Rendered in place of an item value the server left empty. Keeping it here rather than in each fragment means a
+ * section never has to be conditionally assembled just to avoid a blank cell.
+ *
+ * @type {string}
+ */
+const INFO_VALUE_PLACEHOLDER = "—";
+
+/**
+ * URL schemes an info item may link to. Descriptor content is server-authored, but an `href` becomes a live
+ * navigation target, so the set is an allowlist rather than a `javascript:` denylist.
+ *
+ * @type {string[]}
+ */
+const INFO_LINK_SCHEMES = [ "http:", "https:", "mailto:" ];
+
+/**
+ * Returns the href for an info item, or an empty string when it has none or names a scheme that is not in
+ * {@link INFO_LINK_SCHEMES}. A rejected href degrades the item to plain text rather than dropping it.
+ *
+ * @method
+ * @param {Object} item
+ * @returns {string}
+ * @private
+ */
+const sanitizeInfoHref = ( item ) => {
+    const href = String( ( item && item.href ) || "" ).trim();
+    if ( !href ) {
+        return "";
+    }
+    try {
+        return INFO_LINK_SCHEMES.includes( new URL( href, window.location.origin ).protocol ) ? href : "";
+    } catch {
+        return "";
+    }
+};
+
+/**
+ * Normalizes one label/value item: fills in the placeholder for an absent value, collapses the presentational
+ * flags into a single class string, and vets any link target.
+ *
+ * @method
+ * @param {Object} item
+ * @returns {Object}
+ * @private
+ */
+const normalizeInfoItem = ( item ) => {
+    const source = ( item && typeof item === "object" ) ? item : {};
+    const value = String( source.value === undefined || source.value === null ? "" : source.value ).trim();
+    const classes = [];
+    if ( source.mono ) classes.push( "mono" );
+    if ( source.muted || !value ) classes.push( "muted" );
+
+    return {
+        label: String( source.label || "" ),
+        value: value || INFO_VALUE_PLACEHOLDER,
+        valueClass: classes.join( " " ),
+        wide: source.wide === true,
+        href: value ? sanitizeInfoHref( source ) : ""
+    };
+};
+
+/**
+ * Normalizes a descriptor's section list so the template can iterate it without guarding for missing keys.
+ * A section carrying no items at all is dropped — an empty panel is noise, not information.
+ *
+ * @method
+ * @param {Array} sections
+ * @returns {Array}
+ * @private
+ */
+const normalizeInfoSections = ( sections ) => {
+    return ( Array.isArray( sections ) ? sections : [] )
+        .filter( ( section ) => section && Array.isArray( section.items ) && section.items.length > 0 )
+        .map( ( section ) => ( {
+            title: String( section.title || "" ),
+            description: String( section.description || "" ),
+            icon: String( section.icon || "info-circle" ),
+            wide: section.wide === true,
+            items: section.items.map( normalizeInfoItem )
+        } ) );
+};
+
+/**
+ * Normalizes an identity tag into a ready-to-bind pill.
+ *
+ * @method
+ * @param {Object} tag
+ * @returns {Object}
+ * @private
+ */
+const normalizeInfoTag = ( tag ) => {
+    const source = ( tag && typeof tag === "object" ) ? tag : {};
+    const classes = [ source.mono ? "ti-tag mono" : "ti-status-pill" ];
+    if ( source.tone ) classes.push( String( source.tone ) );
+    return {
+        text: String( source.text || "" ),
+        dot: source.dot === true && !source.mono,
+        pillClass: classes.join( " " )
+    };
+};
+
+/**
+ * Runs `load` once the application store has finished initializing — the descriptor endpoints are session-scoped,
+ * so requesting them before `/app/config` has resolved would race the session bootstrap.
+ *
+ * @method
+ * @param {Object} component The Alpine component (for `$watch`).
+ * @param {Function} load
+ * @private
+ */
+const loadWhenInitialized = ( component, load ) => {
+    const tiApplication = Alpine.store( "tiApplication" );
+    if ( tiApplication.isInitialized ) {
+        load();
+    } else {
+        component.$watch( () => tiApplication.isInitialized, ( isInitialized ) => {
+            if ( isInitialized ) {
+                load();
+            }
+        } );
+    }
+};
+
+/**
+ * Returns a configuration object for the Profile screen "frame-profile.html".
+ * <br/>
+ * The descriptor comes from `GET /app/profile` (JSON), which the application's web app manager builds — this
+ * component only shapes it for the template and never decides what a profile contains.
+ *
+ * @method
+ * @returns {Object}
+ * @public
+ */
+const configureScreenProfile = () => {
+    const tiToolbox = Alpine.store( "tiToolbox" );
+    const tiApplication = Alpine.store( "tiApplication" );
+
+    return {
+
+        profile: null,
+        busy: true,
+
+        init() {
+            loadWhenInitialized( this, () => this.load() );
+        },
+
+        load() {
+            this.busy = true;
+            tiApplication.sendRequest( "/app/profile" ).then( ( result ) => {
+                const data = ( result && result.data && typeof result.data === "object" ) ? result.data : {};
+                const identity = ( data.identity && typeof data.identity === "object" ) ? data.identity : {};
+                this.profile = {
+                    identity: {
+                        name: String( identity.name || "" ),
+                        subtitle: String( identity.subtitle || "" ),
+                        caption: String( identity.caption || "" ),
+                        avatarSeed: String( identity.avatarSeed || identity.name || "" ),
+                        badge: identity.badge ? { text: String( identity.badge.text || "" ), tone: String( identity.badge.tone || "" ) } : null,
+                        tags: ( Array.isArray( identity.tags ) ? identity.tags : [] ).map( normalizeInfoTag )
+                    },
+                    sections: normalizeInfoSections( data.sections )
+                };
+                this.busy = false;
+            } ).catch( ( error ) => {
+                this.busy = false;
+                if ( error && ( error.name === "AbortError" || error.isAborted ) ) return;
+                tiApplication.notify( tiApplication.formatException( error ) );
+            } );
+        },
+
+        avatarStyle() {
+            const identity = this.profile ? this.profile.identity : {};
+            return tiToolbox.generateAvatarStyle( identity.avatarSeed, identity.name );
+        },
+
+        avatarInitial() {
+            const identity = this.profile ? this.profile.identity : {};
+            return String( identity.name || "?" ).charAt( 0 ).toUpperCase();
+        }
+
+    };
+};
+
+/**
+ * Returns a configuration object for the About screen "frame-about.html".
+ * <br/>
+ * The server descriptor carries the application's identity as flat fields; the release, component and runtime
+ * sections are assembled here rather than server-side, because their labels are fixed framework chrome and the
+ * client's `getLabel` takes a fallback — which is what keeps the screen readable inside a consuming application
+ * that loads only its own label catalogue.
+ *
+ * @method
+ * @returns {Object}
+ * @public
+ */
+const configureScreenAbout = () => {
+    const tiToolbox = Alpine.store( "tiToolbox" );
+    const tiApplication = Alpine.store( "tiApplication" );
+
+    // Runtime keys the framework itself supplies; anything else an application adds falls back to its own key.
+    const RUNTIME_LABELS = {
+        node: [ "interface.about.runtime-node", "Node.js" ],
+        platform: [ "interface.about.runtime-platform", "Platform" ],
+        application: [ "interface.about.runtime-application", "Application ID" ]
+    };
+
+    const label = ( key, fallback ) => tiApplication.getLabel( key, fallback );
+
+    return {
+
+        application: null,
+        sections: [],
+        busy: true,
+
+        init() {
+            loadWhenInitialized( this, () => this.load() );
+        },
+
+        load() {
+            this.busy = true;
+            tiApplication.sendRequest( "/app/about" ).then( ( result ) => {
+                const data = ( result && result.data && typeof result.data === "object" ) ? result.data : {};
+                this.application = {
+                    name: String( data.name || "" ),
+                    version: String( data.version || "" ),
+                    releaseDate: String( data.releaseDate || "" ),
+                    description: String( data.description || "" )
+                };
+                this.sections = normalizeInfoSections( [
+                    this._releaseSection( data ),
+                    this._componentsSection( data ),
+                    this._runtimeSection( data )
+                ].concat( Array.isArray( data.sections ) ? data.sections : [] ) );
+                this.busy = false;
+            } ).catch( ( error ) => {
+                this.busy = false;
+                if ( error && ( error.name === "AbortError" || error.isAborted ) ) return;
+                tiApplication.notify( tiApplication.formatException( error ) );
+            } );
+        },
+
+        applicationInitial() {
+            return String( ( this.application && this.application.name ) || "?" ).charAt( 0 ).toUpperCase();
+        },
+
+        versionTag() {
+            return "v" + ( ( this.application && this.application.version ) || "" );
+        },
+
+        releaseDateText() {
+            const released = label( "interface.about.released", "Released" );
+            return released + " " + tiToolbox.formatDate( ( this.application && this.application.releaseDate ) || "" );
+        },
+
+        _releaseSection( data ) {
+            return {
+                title: label( "interface.about.section-release", "Release" ),
+                icon: "info-circle",
+                items: [
+                    { label: label( "interface.about.field-version", "Version" ), value: data.version, mono: true },
+                    { label: label( "interface.about.field-release-date", "Release date" ), value: tiToolbox.formatDate( data.releaseDate ) },
+                    { label: label( "interface.about.field-license", "License" ), value: data.license },
+                    { label: label( "interface.about.field-author", "Author" ), value: data.author },
+                    { label: label( "interface.about.field-package", "Package" ), value: data.packageName, mono: true, wide: true },
+                    { label: label( "interface.about.field-homepage", "Homepage" ), value: data.homepage, href: data.homepage, wide: true }
+                ]
+            };
+        },
+
+        _componentsSection( data ) {
+            const components = Array.isArray( data.components ) ? data.components : [];
+            return {
+                title: label( "interface.about.section-components", "Framework components" ),
+                description: label( "interface.about.section-components-desc", "The ti-engine packages this application is built on." ),
+                icon: "folder",
+                items: components.map( ( component ) => ( {
+                    label: String( component.name || "" ),
+                    value: String( component.version || "" ),
+                    mono: true
+                } ) )
+            };
+        },
+
+        _runtimeSection( data ) {
+            // Present only for an admin session — the server withholds `runtime` from everyone else.
+            const runtime = ( data.runtime && typeof data.runtime === "object" ) ? data.runtime : {};
+            return {
+                title: label( "interface.about.section-runtime", "Runtime" ),
+                description: label( "interface.about.section-runtime-desc", "Visible to administrators only." ),
+                icon: "settings",
+                items: Object.keys( runtime ).map( ( key ) => {
+                    const known = RUNTIME_LABELS[ key ];
+                    return {
+                        label: known ? label( known[ 0 ], known[ 1 ] ) : key,
+                        value: String( runtime[ key ] || "" ),
+                        mono: true
+                    };
+                } )
+            };
+        }
+
+    };
+};
+
 /**
  * Returns a configuration object for the login screen test user pill panel.
  * <br/>
@@ -1424,4 +1738,6 @@ document.addEventListener( "alpine:init", () => {
     Alpine.data( "tiComponentNotificationBar", configureComponentNotificationBar );
     Alpine.data( "tiComponentTooltip", configureComponentTooltip );
     Alpine.data( "tiLoginTestUserPanel", configureLoginTestUserPanel );
+    Alpine.data( "tiScreenProfile", configureScreenProfile );
+    Alpine.data( "tiScreenAbout", configureScreenAbout );
 } );

package/bin/web-app-manager.js

@@ -14,8 +14,9 @@ const fs = require( "node:fs" );
 const configRegistry = require( "#config-registry" );
 const configService = require( "#config-service" );
 const authorization = require( "#authorization" );
+const applicationInfo = require( "#application-info" );
 
-/** @import { TiSession } from "#definitions" */
+/** @import { TiApplicationInfo, TiInfoSection, TiProfileInfo, TiSession } from "#definitions" */
 
 const RE_NONCE_ATTR = /\{ti-nonce-placeholder}/g;
 const RE_CSRF_ATTR = /\{ti-csrf-placeholder}/g;
@@ -124,6 +125,7 @@ class TiWebAppManager {
     #staticFileCache = {};
     #staticFileCacheEnabled;
     #enabledAuthMethods = [];
+    #baseApplicationInfo = null;
 
     /**
      * @constructor
@@ -165,6 +167,10 @@ class TiWebAppManager {
             title: "Profile",
             path: "fragments/frame-profile.html"
         };
+        this.#fragments[ 'about' ] = {
+            title: "About",
+            path: "fragments/frame-about.html"
+        };
         this.#fragments[ 'not-found' ] = {
             title: "Not Found",
             path: "fragments/frame-not-found.html"
@@ -393,13 +399,20 @@ class TiWebAppManager {
      * @public
      */
     processDataRequest( session, view, options = {} ) {
+        if ( view === "profile" ) {
+            return this.getProfileInfo( session );
+        }
+        if ( view === "about" ) {
+            return this.getApplicationInfo( session );
+        }
         return new Promise( ( resolve, reject ) => {
             if ( view === "config" ) {
                 resolve( {
                     labels: localization.getAllLabels( session?.language ),
                     auth: {
                         isAuthenticated: Boolean( session && session.user )
-                    }
+                    },
+                    componentsConfig: this.buildComponentsConfig( session )
                 } );
             } else {
                 reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, { view: view } ) );
@@ -407,6 +420,198 @@ class TiWebAppManager {
         } );
     }
 
+    /**
+     * Returns the configuration for the shared UI components the application shell renders — currently the sidebar
+     * user flyout menu. Shipped as part of the `config` data payload and merged into the `tiComponentsConfig`
+     * Alpine store on the client.
+     * <br/>
+     * The default menu links the two screens the framework itself provides (Profile and About) plus sign-out, so a
+     * consuming application gets a working user menu without configuring one. Override to replace it; a subclass
+     * that supplies its own `componentsConfig` naturally supersedes this.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {Object}
+     * @virtual
+     * @public
+     */
+    buildComponentsConfig( session ) {
+        const language = session && session.language;
+        return {
+            userProfileMenu: {
+                menuTitle: localization.getLabel( "interface.topbar.user-profile", language, "Your profile" ),
+                placement: "right-end",
+                offset: 0,
+                buttonConfigs: [ {
+                    title: localization.getLabel( "interface.user-menu.profile", language, "Your profile" ),
+                    icon: "user-profile",
+                    action: { href: "/app/profile", target: "#ti-content", swap: "innerHTML" }
+                }, {
+                    title: localization.getLabel( "interface.user-menu.about", language, "About" ),
+                    icon: "info-circle",
+                    action: { href: "/app/about", target: "#ti-content", swap: "innerHTML" }
+                }, {
+                    title: localization.getLabel( "interface.user-menu.logout", language, "Logout" ),
+                    icon: "logout",
+                    action: { href: "/logout", method: "post", target: "body", swap: "outerHTML" }
+                } ]
+            }
+        };
+    }
+
+    /**
+     * Returns the descriptor rendered by the "Profile" screen — the identity header plus an ordered list of titled
+     * label/value sections. Every string in it is display-ready: the server resolves labels and formats values,
+     * because this is where the session language and the label catalogue are (see {@link resolveLabel}).
+     * <br/>
+     * The default implementation reports what the framework itself knows about the session user — name, username,
+     * e-mail, language and roles. Override in subclasses to show application-owned data instead; the screen, its
+     * Alpine component and its styling are inherited unchanged, so an override only decides the content.
+     * <br/>
+     * NOTE: The descriptor is always about the SESSION user. There is deliberately no "whose profile" parameter —
+     * viewing another person's record belongs to an application screen that carries its own scoping rules.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {Promise<TiProfileInfo>}
+     * @exception {TiException.E_SEC_UNAUTHORIZED_ACCESS} (401) When the session carries no user.
+     * @virtual
+     * @public
+     */
+    getProfileInfo( session ) {
+        return new Promise( ( resolve, reject ) => {
+            const user = session && session.user;
+            if ( !user ) {
+                return reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 ) );
+            }
+            resolve( {
+                identity: this.buildSessionIdentity( session ),
+                sections: this.buildAccountSections( session )
+            } );
+        } );
+    }
+
+    /**
+     * Returns the descriptor rendered by the "About" screen — the application's own identity (name, version,
+     * release date, description, license, homepage) plus the ti-engine component versions it runs on, and any
+     * extra sections the application contributes.
+     * <br/>
+     * The baseline is resolved once from the consuming application's `package.json`, overridable through
+     * `TI_WEB_APP_NAME` / `TI_WEB_APP_VERSION` / `TI_WEB_APP_RELEASE_DATE` (see `#application-info`), and cached —
+     * the manifest cannot change while the process runs.
+     * <br/>
+     * NOTE: Runtime facts (node version, platform, instance identity) are attached only for an `admin` session.
+     * They are operational detail that helps support and means nothing to an ordinary user, so they are not handed
+     * to every signed-in visitor. Override in subclasses to append application-specific sections; call `super` and
+     * extend the result rather than rebuilding it.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {Promise<TiApplicationInfo>}
+     * @virtual
+     * @public
+     */
+    getApplicationInfo( session ) {
+        return new Promise( ( resolve ) => {
+            if ( !this.#baseApplicationInfo ) {
+                this.#baseApplicationInfo = applicationInfo.buildApplicationInfo( {
+                    manifest: applicationInfo.readApplicationManifest(),
+                    env: process.env,
+                    components: TiWebAppManager.resolveFrameworkComponents()
+                } );
+            }
+
+            const info = structuredClone( this.#baseApplicationInfo );
+            if ( authorization.hasAnyRole( session, [ authorization.ADMIN_ROLE ] ) ) {
+                info.runtime = {
+                    node: process.version,
+                    platform: `${ process.platform } · ${ process.arch }`,
+                    application: this.#webAppIdentifier
+                };
+            }
+            resolve( info );
+        } );
+    }
+
+    /**
+     * Builds the identity header of the Profile screen from the session user. Kept separate from
+     * {@link TiWebAppManager#getProfileInfo} so a subclass that replaces the sections can still reuse — or fall
+     * back to — the framework's identity block when the application has no richer identity to show.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {Object}
+     * @public
+     */
+    buildSessionIdentity( session ) {
+        const user = ( session && session.user ) || {};
+        return {
+            name: String( user.name || user.username || user.userID || "" ),
+            subtitle: "",
+            caption: String( user.email || "" ),
+            avatarSeed: String( user.userID || user.username || "" ),
+            // No pills by default: the framework knows roles only as opaque codes, and a stack of pills reading
+            // "1" / "2" beside the name is noise. The Access section lists them, and an application that has
+            // meaningful status to show (employment state, an ID, a badge) supplies its own.
+            tags: []
+        };
+    }
+
+    /**
+     * Builds the framework's account-level Profile sections from the session user. A subclass showing richer
+     * application data can append these so the account facts remain visible alongside it.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {TiInfoSection[]}
+     * @public
+     */
+    buildAccountSections( session ) {
+        const user = ( session && session.user ) || {};
+        const language = session && session.language;
+        const roles = Array.isArray( user.roles ) ? user.roles : [];
+
+        return [ {
+            title: localization.getLabel( "interface.profile.section-account", language, "Account" ),
+            icon: "user",
+            items: [
+                { label: localization.getLabel( "interface.profile.field-name", language, "Full name" ), value: String( user.name || "" ) },
+                { label: localization.getLabel( "interface.profile.field-username", language, "Username" ), value: String( user.username || "" ) },
+                { label: localization.getLabel( "interface.profile.field-email", language, "E-mail" ), value: String( user.email || "" ), wide: true },
+                { label: localization.getLabel( "interface.profile.field-user-id", language, "User ID" ), value: String( user.userID || "" ), mono: true },
+                { label: localization.getLabel( "interface.profile.field-language", language, "Language" ), value: String( user.language || language || "" ) }
+            ]
+        }, {
+            title: localization.getLabel( "interface.profile.section-access", language, "Access" ),
+            icon: "check-circle",
+            items: [
+                { label: localization.getLabel( "interface.profile.field-roles", language, "Roles" ), value: roles.join( " · " ), wide: true }
+            ]
+        } ];
+    }
+
+    /**
+     * Resolves the versions of the ti-engine packages the running application is built on, for the About screen.
+     * <br/>
+     * NOTE: `@ti-engine/core` does not expose `./package.json` through its exports map, so its manifest is located
+     * by walking up from a module it *does* export. A package that cannot be resolved is simply omitted — an
+     * informational screen must never be the reason a request fails.
+     *
+     * @method
+     * @static
+     * @returns {Array<{name: string, version: string}>}
+     * @public
+     */
+    static resolveFrameworkComponents() {
+        const manifests = [
+            applicationInfo.readApplicationManifest( path.join( __dirname, ".." ) ),
+            TiWebAppManager.#readManifestForModule( "@ti-engine/core/tools" )
+        ];
+        return manifests
+            .filter( ( manifest ) => manifest && manifest.name && manifest.version )
+            .map( ( manifest ) => ( { name: manifest.name, version: manifest.version } ) );
+    }
+
     /**
      * Used to process an application service request.
      *
@@ -452,6 +657,34 @@ class TiWebAppManager {
 
     /* Private interface */
 
+    /**
+     * Locates the `package.json` owning a resolvable module specifier by walking up from the resolved file.
+     *
+     * @method
+     * @static
+     * @param {string} moduleSpecifier
+     * @returns {Object} The manifest, or an empty object when it cannot be located.
+     */
+    static #readManifestForModule( moduleSpecifier ) {
+        try {
+            let directory = path.dirname( require.resolve( moduleSpecifier ) );
+            for ( let depth = 0; depth < 8; depth++ ) {
+                const manifest = applicationInfo.readApplicationManifest( directory );
+                if ( manifest && manifest.name ) {
+                    return manifest;
+                }
+                const parent = path.dirname( directory );
+                if ( parent === directory ) {
+                    break;
+                }
+                directory = parent;
+            }
+        } catch {
+            // An unresolvable package simply does not appear in the component list.
+        }
+        return {};
+    }
+
     /**
      * Returns the HTML fragment for the requested route.
      *