@gandalan/weblibs 2.0.8 → 2.0.10

package/JSDOC.md

@@ -273,6 +273,35 @@ export {};
 If that type must be visible to consumers, make sure the file is part of the generator input and regenerate declarations.
 
 
+### Add an overloaded function type
+
+Some public entry points behave differently depending on the argument type —
+`NeherApp3I18n.localize` translates a string but acts as a Svelte action when
+it gets a DOM node. `@callback` cannot express that (one signature only), so
+write the type as a typedef with **call signatures**:
+
+```js
+/**
+ * @typedef {{
+ *     (key: string, params?: LocalizeParams, namespace?: string): string;
+ *     (node: Element, options?: LocalizeActionOptions): LocalizeActionHandle;
+ * }} Localize
+ */
+```
+
+The generator copies the type expression verbatim, so `index.d.ts` gets a real
+overload set and consumers see the precise return type per call form.
+
+Two things to know when a consumer *implements* such a type:
+
+- Annotate the implementation with the type instead of repeating `@overload`
+  blocks — `/** @type {Localize} */ const localize = (…) => …`. Two separately
+  declared overload sets are not assignable to each other in TypeScript, even
+  when they look identical.
+- The implementation itself has one signature, so widen its return
+  (`/** @type {*} */ (…)`) and give trailing parameters defaults so it also
+  accepts the shorter call form.
+
 ## Root Consumption Model
 
 There are two public surfaces:

package/README.md

@@ -14,6 +14,15 @@
 - IDAS API (Swagger): https://api.dev.idas-cloudservices.net/swagger/
 - JSDoc-Regeln und Typing-Konventionen: [JSDOC.md](./JSDOC.md)
 
+### NeherApp3-Hosttypen
+`api/neherApp3Types.js` ist die Master-Referenz fuer die Vertraege der
+NeherApp3-Rahmen-App: `NeherApp3` (Host-API), `NeherApp3Module` (Modul-Einstieg),
+`NeherApp3Messages` (In-Realm-Nachrichtenbus) und `NeherApp3I18n`
+(Lokalisierung: `localize` als Funktion *und* Svelte-Action, Modul-Kataloge,
+sprachrichtige Sortierung). Die Datei enthaelt nur Typen und wird von Hand
+gepflegt; die Leitfaeden liegen im NeherApp3-Repository
+(`docs/MODULE.md`, `docs/MESSAGING.md`, `docs/I18N.md`).
+
 ### Voraussetzungen
 - Browser-Umgebung
 - Gueltiger App-Token im UUID-Format

package/api/neherApp3Types.js

@@ -1,6 +1,7 @@
 /**
- * Auto-generated NeherApp3 root type definitions.
- * Do not modify manually - changes will be overwritten by scripts/generate-root-dto-typedefs.mjs
+ * NeherApp3 root type definitions — the master reference for the shell's host
+ * API. Maintained by hand; `scripts/generate-dts.mjs` reads these typedefs and
+ * emits them into `index.d.ts`.
  */
 
 /** @typedef {import("./fluentApi.js").FluentApi} FluentApi */
@@ -69,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 {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`.
  */
 
 /**
@@ -156,6 +158,10 @@
  * In-realm message bus for module-to-module communication, exposed at
  * `neherapp3.messages`. Messaging, not RPC: `send`/`broadcast` return delivery
  * information, never a handler's result.
+ *
+ * Topics the shell itself broadcasts: `i18n.localeChanged` with payload
+ * `{ locale: string }` (sent with `retain: true`, so late subscribers receive
+ * the current language as well).
  * @typedef {Object} NeherApp3Messages
  * @property {(moduleName: string) => Endpoint} register - Register a module as a reachable endpoint.
  * @property {(to: string, type: string, payload?: any, options?: SendOptions) => Delivery} send - Directed message (`from` via `options.from`).
@@ -165,6 +171,189 @@
  * @property {string[]} reachable - Reactive list of all currently reachable module names.
  */
 
+/**
+ * A translation table: key (the German source text) -> translation.
+ * @typedef {Record<string, string>} TranslationTable
+ */
+
+/**
+ * Translation tables by BCP-47 language code, e.g. `{ en: { "Bestand": "Stock" } }`.
+ * @typedef {Record<string, TranslationTable>} TranslationCatalogs
+ */
+
+/**
+ * Values for `{placeholder}` markers inside a translated text.
+ * @typedef {Record<string, string | number>} LocalizeParams
+ */
+
+/**
+ * A language offered by the shell.
+ * @typedef {Object} NeherApp3LocaleInfo
+ * @property {string} code - BCP-47 code, e.g. `de`, `de-x-du`, `en`.
+ * @property {string} label - Display name in its own language.
+ */
+
+/**
+ * Options for the `use:localize` action.
+ *
+ * Without options the action translates the element's own text nodes (child
+ * elements are left untouched) and every attribute listed in the element's
+ * `data-i18n` attribute, using each attribute's current value as the key.
+ * These fields cover everything that cannot be written statically in markup.
+ * @typedef {Object} LocalizeActionOptions
+ * @property {string} [text] - Key for the whole text content (replaces it).
+ * @property {string} [html] - Like `text`, but the translation contains markup.
+ * @property {LocalizeParams} [params] - Values for `{placeholder}` markers in text, html and attributes.
+ * @property {Record<string, string>} [attrs] - Attribute name -> key, for dynamic attribute values.
+ * @property {string} [ns] - Namespace to look in first (defaults to the endpoint's namespace, otherwise `shell`).
+ */
+
+/**
+ * Return value of the `use:localize` action (a Svelte action handle).
+ * @typedef {Object} LocalizeActionHandle
+ * @property {(options?: LocalizeActionOptions) => void} update - Re-translate with new options (called by Svelte when the parameter changes).
+ * @property {() => void} destroy - Detach from language/catalog changes.
+ */
+
+/**
+ * Dual-purpose translation entry point: pass a **key** to translate a string,
+ * pass a **DOM node** to use it as a Svelte action (`use:localize`).
+ *
+ * ```js
+ * localize("Speichern");                       // -> "Save"
+ * localize("{n} Treffer", { n: 3 });           // placeholders
+ * ```
+ * ```svelte
+ * <h2 use:localize>Persönliche Daten</h2>
+ * <button title="Kopieren" use:localize data-i18n="title">…</button>
+ * ```
+ *
+ * @typedef {{
+ *     (key: string, params?: LocalizeParams, namespace?: string): string;
+ *     (node: Element, options?: LocalizeActionOptions): LocalizeActionHandle;
+ * }} Localize
+ */
+
+/**
+ * A registered translation namespace, returned by `i18n.register`. `register`
+ * is idempotent; each handle's `dispose` only removes the tables added through
+ * it. Lookups fall back to the shell catalog, so shared terms such as
+ * "Speichern" need not be translated again per module.
+ * @typedef {Object} NeherApp3I18nEndpoint
+ * @property {string} namespace - The namespace of this handle (usually the module name).
+ * @property {Localize} localize - Translate in this namespace: as a function for script code, as a `use:` action for markup.
+ * @property {(translations: TranslationCatalogs) => void} add - Add further tables later (e.g. lazily loaded language files).
+ * @property {(key: string) => boolean} has - Is there a real translation (not just the key)?
+ * @property {() => void} dispose - Remove exactly the tables registered through this handle.
+ */
+
+/**
+ * Localization, exposed at `neherapp3.i18n`.
+ *
+ * German is the source language and **the key is the German text**
+ * (`localize("Speichern")`); a missing translation falls back to the key, so an
+ * untranslated UI is never broken, just German. There is therefore no `de`
+ * catalog. The shell carries only its own texts (namespace `shell`); every
+ * module registers its own catalog under its module name.
+ * @typedef {Object} NeherApp3I18n
+ * @property {(namespace: string, translations?: TranslationCatalogs) => NeherApp3I18nEndpoint} register - Register a namespace's translation tables.
+ * @property {Localize} localize - Translate a key, or translate an element via `use:localize`.
+ * @property {(key: string, namespace?: string) => boolean} has - Is there a real translation for the key?
+ * @property {(a: string, b: string) => number} compare - Compare two **display texts** with the collator of the active language.
+ * @property {<T>(items: readonly T[], selector?: (item: T) => string) => T[]} sort - Sorted copy, ordered by the **translated** text (translate first, then sort).
+ * @property {(code: string) => void} setLocale - Switch the language and persist the choice.
+ * @property {(listener: (locale: string) => void) => (() => void)} onLocaleChange - Listen for language changes (for consumers without Svelte reactivity); returns an unsubscribe function.
+ * @property {string} sourceLocale - The source language — the keys themselves are texts in this language (`"de"`).
+ * @property {string} locale - Active language (reactive).
+ * @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.
@@ -175,6 +364,10 @@
  * @property {NeherApp3ApiCollection} api
  * @property {NeherApp3CacheCollection} cache
  * @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

@@ -1847,6 +1847,26 @@ export type LieferzusageDTO = {
     ChangedDate: Date;
 };
 
+export type Localize = {
+    (key: string, params?: LocalizeParams, namespace?: string): string;
+    (node: Element, options?: LocalizeActionOptions): LocalizeActionHandle;
+};
+
+export type LocalizeActionHandle = {
+    update: (options?: LocalizeActionOptions) => void;
+    destroy: () => void;
+};
+
+export type LocalizeActionOptions = {
+    text?: string;
+    html?: string;
+    params?: LocalizeParams;
+    attrs?: Record<string, string>;
+    ns?: string;
+};
+
+export type LocalizeParams = Record<string, string | number>;
+
 export type LoginAttemptDTO = {
     UserGuid: string;
     FailCount: number;
@@ -2055,6 +2075,10 @@ export type NeherApp3 = {
     api: NeherApp3ApiCollection;
     cache: NeherApp3CacheCollection;
     messages: NeherApp3Messages;
+    i18n: NeherApp3I18n;
+    localize: Localize;
+    settings: NeherApp3Settings;
+    profile: NeherApp3Profile;
     isEmbedded: boolean;
 };
 
@@ -2084,6 +2108,32 @@ export type NeherApp3ErfassungCache = {
     createUIMachine: (v: Variante) => void;
 };
 
+export type NeherApp3I18n = {
+    register: (namespace: string, translations?: TranslationCatalogs) => NeherApp3I18nEndpoint;
+    localize: Localize;
+    has: (key: string, namespace?: string) => boolean;
+    compare: (a: string, b: string) => number;
+    sort: <T>(items: readonly T[], selector?: (item: T) => string) => T[];
+    setLocale: (code: string) => void;
+    onLocaleChange: (listener: (locale: string) => void) => (() => void);
+    sourceLocale: string;
+    locale: string;
+    locales: NeherApp3LocaleInfo[];
+};
+
+export type NeherApp3I18nEndpoint = {
+    namespace: string;
+    localize: Localize;
+    add: (translations: TranslationCatalogs) => void;
+    has: (key: string) => boolean;
+    dispose: () => void;
+};
+
+export type NeherApp3LocaleInfo = {
+    code: string;
+    label: string;
+};
+
 export type NeherApp3MenuItem = {
     id?: string;
     selected?: boolean;
@@ -2094,6 +2144,7 @@ export type NeherApp3MenuItem = {
     parent?: string | null;
     hidden?: boolean;
     separator?: boolean;
+    i18nNamespace?: string;
 };
 
 export type NeherApp3Messages = {
@@ -2116,6 +2167,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;
@@ -2123,6 +2195,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 = {
@@ -2832,6 +2938,10 @@ export type TemplateDTO = {
     Benutzer: string;
 };
 
+export type TranslationCatalogs = Record<string, TranslationTable>;
+
+export type TranslationTable = Record<string, string>;
+
 export type TypePattern = string | string[];
 
 export type UiApi = {

package/package.json

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