@gandalan/weblibs 2.0.9 → 2.0.11

package/api/neherApp3Types.js

@@ -70,6 +70,7 @@
  * @property {string | null} [parent] - Parent menu item (optional). If not set, the item will be added to the top level menu.
  * @property {boolean} [hidden] - If true, the menu item will not be displayed
  * @property {boolean} [separator] - If true, renders as a non-interactive divider between items (text/icon/url are ignored). Use `parent` to place the separator inside a sub-menu.
+ * @property {boolean} [heading] - If true, renders `text` as a non-interactive group heading inside a sub-menu (ALL CAPS, bold, extra space above; icon/url are ignored). Requires `parent`; ignored on the top level. `text` is translated like any other entry.
  * @property {string} [i18nNamespace] - Catalog in which `text` is translated. Set automatically to the registering module's name; only pass it explicitly for items added outside `setup`. See `NeherApp3I18n`.
  */
 
@@ -268,6 +269,92 @@
  * @property {NeherApp3LocaleInfo[]} locales - Languages offered by the shell.
  */
 
+/**
+ * Settings handle of a single namespace — what
+ * `neherapp3.settings.register("my-module")` returns.
+ * @typedef {Object} NeherApp3SettingsHandle
+ * @property {string} namespace - The bound namespace (lower case).
+ * @property {(key: string, fallback?: any) => any} get - Value of a setting, or `fallback`. Reactive.
+ * @property {(key: string, value: unknown) => void} set - Store a value: applied locally at once, sent to the server coalesced.
+ * @property {(key: string) => void} remove - Drop a setting; the user is back to its default.
+ * @property {() => Record<string, unknown>} all - All settings of this namespace.
+ * @property {() => Promise<void>} flush - Write pending changes now. Call before a reload.
+ */
+
+/**
+ * User settings, exposed at `neherapp3.settings`.
+ *
+ * The store is the **database**, not `localStorage`: inside the i3 WebView
+ * `localStorage` is ephemeral and would lose every setting on each start. A
+ * setting is addressed by namespace and key, both lower case; `shell` belongs
+ * to the framework, every module uses its own namespace — the same one it uses
+ * for `i18n.register`. Values are arbitrary JSON.
+ *
+ * Reads are reactive. Writes are applied locally at once and sent to the
+ * server after a short coalescing delay, so call `flush()` before a reload.
+ * @typedef {Object} NeherApp3Settings
+ * @property {string} scope - Namespace of the framework (`"shell"`).
+ * @property {boolean} loaded - `true` once the values from the database have arrived.
+ * @property {(namespace: string) => NeherApp3SettingsHandle} register - Settings handle bound to a module's namespace.
+ * @property {(scope: string, key: string, fallback?: any) => any} get - Value of a setting, or `fallback`. Reactive.
+ * @property {(scope: string, key: string, value: unknown) => void} set - Store a value.
+ * @property {(scope: string, key: string) => void} remove - Drop a setting.
+ * @property {(scope: string) => Record<string, unknown>} all - All settings of one namespace.
+ * @property {() => Promise<void>} flush - Write pending changes now. Call before a reload.
+ */
+
+/**
+ * The profile of *another* user, as returned by `profile.byEmail` and friends.
+ *
+ * Identity comes from the platform's user table — whoever has signed in here at
+ * least once; the remaining fields are filled in only where that user curated
+ * them.
+ * @typedef {Object} NeherApp3PublicProfile
+ * @property {string} userId - The user's `benutzerGuid`.
+ * @property {string} userName - Login name.
+ * @property {string} email - E-mail address.
+ * @property {string | null} displayName - Self-chosen name shown in the interface.
+ * @property {string | null} initials - Self-chosen initials, up to 3 characters.
+ * @property {string | null} jobTitle - Job title / function.
+ * @property {string | null} department - Department.
+ * @property {string | null} location - Site / plant.
+ * @property {string | null} mobile - Mobile number.
+ * @property {string | null} avatar - The avatar as a data URL, or `null` when none is stored.
+ * @property {string | null} avatarUpdatedAt - When the avatar was last uploaded.
+ */
+
+/**
+ * The signed-in user, exposed at `neherapp3.profile`.
+ *
+ * Two sources in one place: identity comes from the IDAS token (user id, login
+ * name, e-mail, roles, rights), the remaining fields from the platform's own
+ * profile table — above all the avatar, which IDAS does not carry.
+ *
+ * Read-only and reactive: the local fields arrive shortly after start and are
+ * edited in the framework's settings, not by a module. The same object carries
+ * the lookup of *other* users' profiles (`byEmail`, `byEmails`, `byUserId`) —
+ * the way to put a name and a face next to a user id in a list.
+ * @typedef {Object} NeherApp3Profile
+ * @property {string} userId - `benutzerGuid` from the token.
+ * @property {string} userName - Login name (`id` claim).
+ * @property {string} email - E-mail address from the token.
+ * @property {string[]} roles - Roles from the token.
+ * @property {string[]} rights - Rights from the token.
+ * @property {string} displayName - Best available name: the self-chosen one, otherwise the token's.
+ * @property {string} initials - Up to 3 characters: self-chosen, otherwise derived from the name.
+ * @property {string | null} avatar - The avatar as a data URL, or `null` when none is stored.
+ * @property {string | null} jobTitle - Job title / function.
+ * @property {string | null} department - Department.
+ * @property {string | null} location - Site / plant.
+ * @property {string | null} mobile - Mobile number (IDAS carries only one phone number).
+ * @property {boolean} loaded - `true` once the local profile has been fetched.
+ * @property {() => Promise<void>} reload - Fetch the local profile again.
+ * @property {(email: string) => Promise<NeherApp3PublicProfile | null>} byEmail - The profile of another user by e-mail address; `null` when this platform does not know them. Calls made close together are coalesced into one request and cached for the session.
+ * @property {(emails: string[]) => Promise<NeherApp3PublicProfile[]>} byEmails - The profiles of several users; unknown addresses are absent from the result.
+ * @property {(userId: string) => Promise<NeherApp3PublicProfile | null>} byUserId - The profile of another user by their `benutzerGuid`.
+ * @property {() => void} clearCache - Discard the cached profiles, so the next lookup asks again.
+ */
+
 /**
  * @typedef {Object} NeherApp3
  * @property {(menuItem: NeherApp3MenuItem) => void} addMenuItem - Adds a menu item. If an item with the same `id` already exists it is replaced.
@@ -280,6 +367,8 @@
  * @property {NeherApp3Messages} messages - In-realm message bus for module-to-module communication.
  * @property {NeherApp3I18n} i18n - Localization: register a module's translation catalog, translate, switch language, sort language-aware.
  * @property {Localize} localize - Shorthand for `i18n.localize` (namespace `shell`): a function for strings, a `use:` action for elements.
+ * @property {NeherApp3Settings} settings - Per-user settings, stored in the database (not `localStorage`).
+ * @property {NeherApp3Profile} profile - The signed-in user: identity from the IDAS token plus the platform's own profile fields (avatar, job title, …).
  * @property {boolean} isEmbedded - Indicates if the app is embedded inside i3
  */
 

package/index.d.ts

@@ -2077,6 +2077,8 @@ export type NeherApp3 = {
     messages: NeherApp3Messages;
     i18n: NeherApp3I18n;
     localize: Localize;
+    settings: NeherApp3Settings;
+    profile: NeherApp3Profile;
     isEmbedded: boolean;
 };
 
@@ -2142,6 +2144,7 @@ export type NeherApp3MenuItem = {
     parent?: string | null;
     hidden?: boolean;
     separator?: boolean;
+    heading?: boolean;
     i18nNamespace?: string;
 };
 
@@ -2165,6 +2168,27 @@ export type NeherApp3Module = {
 
 export type NeherApp3NotifyType = 0 | 1 | 2;
 
+export type NeherApp3Profile = {
+    userId: string;
+    userName: string;
+    email: string;
+    roles: string[];
+    rights: string[];
+    displayName: string;
+    initials: string;
+    avatar: string | null;
+    jobTitle: string | null;
+    department: string | null;
+    location: string | null;
+    mobile: string | null;
+    loaded: boolean;
+    reload: () => Promise<void>;
+    byEmail: (email: string) => Promise<NeherApp3PublicProfile | null>;
+    byEmails: (emails: string[]) => Promise<NeherApp3PublicProfile[]>;
+    byUserId: (userId: string) => Promise<NeherApp3PublicProfile | null>;
+    clearCache: () => void;
+};
+
 export type NeherApp3Props = {
     api: FluentApi;
     authManager?: FluentAuthManager;
@@ -2172,6 +2196,40 @@ export type NeherApp3Props = {
     mainCssPath?: string;
 };
 
+export type NeherApp3PublicProfile = {
+    userId: string;
+    userName: string;
+    email: string;
+    displayName: string | null;
+    initials: string | null;
+    jobTitle: string | null;
+    department: string | null;
+    location: string | null;
+    mobile: string | null;
+    avatar: string | null;
+    avatarUpdatedAt: string | null;
+};
+
+export type NeherApp3Settings = {
+    scope: string;
+    loaded: boolean;
+    register: (namespace: string) => NeherApp3SettingsHandle;
+    get: (scope: string, key: string, fallback?: any) => any;
+    set: (scope: string, key: string, value: unknown) => void;
+    remove: (scope: string, key: string) => void;
+    all: (scope: string) => Record<string, unknown>;
+    flush: () => Promise<void>;
+};
+
+export type NeherApp3SettingsHandle = {
+    namespace: string;
+    get: (key: string, fallback?: any) => any;
+    set: (key: string, value: unknown) => void;
+    remove: (key: string) => void;
+    all: () => Record<string, unknown>;
+    flush: () => Promise<void>;
+};
+
 export type NeherApp3SetupContext = NeherApp3Props & { neherapp3: NeherApp3 };
 
 export type NeherMessage = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gandalan/weblibs",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "description": "WebLibs for Gandalan JS/TS projects",
   "keywords": [
     "gandalan"