@gandalan/weblibs 2.0.10 → 2.0.12

package/README.md

@@ -17,9 +17,10 @@
 ### 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`
+`NeherApp3Messages` (In-Realm-Nachrichtenbus), `NeherApp3I18n`
 (Lokalisierung: `localize` als Funktion *und* Svelte-Action, Modul-Kataloge,
-sprachrichtige Sortierung). Die Datei enthaelt nur Typen und wird von Hand
+sprachrichtige Sortierung) und `NeherApp3Theme` (Hell-/Dunkel-Modus; Module im
+Shadow DOM liefern beide Themes mit, das `data-theme` setzt die Rahmen-App). 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`).
 

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`.
  */
 
@@ -84,7 +85,7 @@
  * @property {(node: HTMLElement, props: NeherApp3SetupContext) => void | function} [mount] - Must return an optional unmount function
  * @property {string} [embedUrl]
  * @property {string[]} [extraCSS]
- * @property {boolean} [useShadowDom] - If true, the app will be embedded in a shadow DOM. This is required for CSS isolation.
+ * @property {boolean} [useShadowDom] - If true, the app will be embedded in a shadow DOM. This is required for CSS isolation. The module then ships all of its styles itself — including **both** themes (`neher`, `neher-dark`), because the shell mirrors `data-theme` onto the module's root inside the shadow root (see `NeherApp3Theme`).
  */
 
 /**
@@ -354,6 +355,43 @@
  * @property {() => void} clearCache - Discard the cached profiles, so the next lookup asks again.
  */
 
+/**
+ * Theme handle, exposed at `neherapp3.theme`.
+ *
+ * The shell writes the resolved theme name to `data-theme` on `<html>`, so
+ * anything in the light DOM follows it by inheritance. **Inside a Shadow DOM
+ * module it does not**: an attribute selector never crosses the shadow
+ * boundary, and the module's own `:host` rules override the inherited custom
+ * properties — a module built with the shell's daisyUI setup would stay light
+ * forever. The shell therefore mirrors `data-theme` onto the module's root
+ * element inside the shadow root and keeps it in sync; a module only needs to
+ * ship both themes (`neher`, `neher-dark`) in its stylesheet.
+ *
+ * `subscribe` is for consumers without Svelte reactivity (and for reacting to
+ * a switch, e.g. to repaint a canvas or reload a themed asset).
+ * @typedef {Object} NeherApp3Theme
+ * @property {NeherApp3ThemeName} current - Active, resolved theme name (reactive).
+ * @property {NeherApp3ThemePreference} preference - Stored choice, including `"system"` (reactive).
+ * @property {boolean} isDark - Shorthand for `current === "neher-dark"` (reactive).
+ * @property {(preference: NeherApp3ThemePreference) => void} set - Store a preference and apply it.
+ * @property {() => void} toggle - Switch light/dark as an explicit choice (replaces `"system"`).
+ * @property {(listener: (theme: NeherApp3ThemeName) => void) => (() => void)} subscribe - Listen for theme changes; called immediately with the current theme, returns an unsubscribe function.
+ * @property {"neher"} LIGHT - Theme name of the light mode.
+ * @property {"neher-dark"} DARK - Theme name of the dark mode.
+ * @property {"system"} SYSTEM - Preference "follow the operating system".
+ */
+
+/**
+ * Resolved theme name — the value of the `data-theme` attribute.
+ * @typedef {"neher" | "neher-dark"} NeherApp3ThemeName
+ */
+
+/**
+ * Stored theme choice: a theme name, or `"system"` to follow
+ * `prefers-color-scheme` live.
+ * @typedef {NeherApp3ThemeName | "system"} NeherApp3ThemePreference
+ */
+
 /**
  * @typedef {Object} NeherApp3
  * @property {(menuItem: NeherApp3MenuItem) => void} addMenuItem - Adds a menu item. If an item with the same `id` already exists it is replaced.
@@ -368,6 +406,7 @@
  * @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 {NeherApp3Theme} theme - Light/dark mode: the active theme, the stored preference, and a subscription for theme changes.
  * @property {boolean} isEmbedded - Indicates if the app is embedded inside i3
  */
 

package/index.d.ts

@@ -2079,6 +2079,7 @@ export type NeherApp3 = {
     localize: Localize;
     settings: NeherApp3Settings;
     profile: NeherApp3Profile;
+    theme: NeherApp3Theme;
     isEmbedded: boolean;
 };
 
@@ -2144,6 +2145,7 @@ export type NeherApp3MenuItem = {
     parent?: string | null;
     hidden?: boolean;
     separator?: boolean;
+    heading?: boolean;
     i18nNamespace?: string;
 };
 
@@ -2231,6 +2233,22 @@ export type NeherApp3SettingsHandle = {
 
 export type NeherApp3SetupContext = NeherApp3Props & { neherapp3: NeherApp3 };
 
+export type NeherApp3Theme = {
+    current: NeherApp3ThemeName;
+    preference: NeherApp3ThemePreference;
+    isDark: boolean;
+    set: (preference: NeherApp3ThemePreference) => void;
+    toggle: () => void;
+    subscribe: (listener: (theme: NeherApp3ThemeName) => void) => (() => void);
+    LIGHT: "neher";
+    DARK: "neher-dark";
+    SYSTEM: "system";
+};
+
+export type NeherApp3ThemeName = "neher" | "neher-dark";
+
+export type NeherApp3ThemePreference = NeherApp3ThemeName | "system";
+
 export type NeherMessage = {
     id: string;
     type: string;

package/package.json

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