feat(yasgui): What's new in the help menu

Lists the changes of each version since 5.0.0 as New, Improved or Fixed,
with a filter per kind and a link to the GitHub release notes. A dot on
the help button marks a release the user hasn't opened yet (not on a
first visit); the newest seen version is persisted as whatsNewSeen. Also
in the Ctrl+K search, and showWhatsNew: false switches it off.

Author: MathiasVDA

.changeset/whats-new.md

@@ -0,0 +1,5 @@
+---
+"@matdata/yasgui": minor
+---
+
+**What's new**: the help button of the top bar now opens a menu with **What's new** and the **Documentation**. What's new lists the changes of each version since 5.0.0 as New, Improved or Fixed, with a filter per kind and a link to the full release notes. After an update a dot on the help button points to it until it is opened; first-time users get no dot. Also in the Ctrl+K search. Embedders can switch it off with `showWhatsNew: false` and add their own entries with `yasgui.helpMenu.addItem()`. `helpUrl: false` now only leaves out the documentation entry.

docs/developer-guide.md

@@ -718,9 +718,14 @@ interface Config {
   // Look up IRIs the endpoint doesn't describe in LOV (lov.linkeddata.es)
   iriHoverLovFallback?: boolean;  // default: true
 
-  // Page opened by the help button of the top bar; false hides the button
+  // Documentation link in the menu of the help button of the top bar; false leaves it out.
+  // The help button hides when its menu has no entries left
   helpUrl?: string | false;  // default: 'https://matgui-doc.matdata.eu/docs/user-guide'
 
+  // "What's new" in the help menu: the changes per version, with a dot on the help button
+  // until the user has seen the latest release. Also in the Ctrl+K search
+  showWhatsNew?: boolean;  // default: true
+
   // AI assistant (see AI Assistant Configuration); { enabled: false } removes it
   ai: Partial<AiConfig>;
   /**
@@ -2547,6 +2552,24 @@ The older entry points keep working and now drive the side panel:
 
 A pinned describe panel saved by an earlier version is restored as the pinned Endpoint view.
 
+#### Help menu and What's new
+
+The help button of the top bar opens `yasgui.helpMenu`. Add your own entries, for example a link to your site's documentation; entries are sorted on `order` (built-in: quick start 10, What's new 20, Documentation 90, default 100). With a single entry the button runs it directly, and without entries it is hidden.
+
+```javascript
+yasgui.helpMenu.addItem({
+  id: "contact",                 // an existing id is replaced
+  label: "Contact support",
+  icon: "externalLink",          // optional, a MatGUI icon name
+  order: 95,
+  onClick: () => window.open("https://example.org/support", "_blank"),
+});
+yasgui.helpMenu.setBadge("contact", true);  // dot on the entry and the help button
+yasgui.helpMenu.removeItem("contact");
+```
+
+`yasgui.whatsNew` (unless `showWhatsNew: false`) has `open()`, `close()`, `hasUnseen()` and `getLatestVersion()`. The release entries live in `packages/yasgui/src/whatsNew/releases.ts`, newest first; add the next version there when preparing a release. The newest version a user has opened is stored as `whatsNewSeen` in the persisted config.
+
 ### Tab Class
 
 Represents a query tab.

docs/user-guide.md

@@ -25,6 +25,7 @@
 - [The Interface](#the-interface)
   - [Top Bar](#top-bar)
   - [Search](#search)
+  - [Help Menu and What's New](#help-menu-and-whats-new)
   - [Query Card](#query-card)
   - [Endpoint Picker](#endpoint-picker)
   - [Run and Stop](#run-and-stop)
@@ -352,7 +353,7 @@ From left to right:
 - **MatGUI**: the name of the application (sites that embed MatGUI can hide it)
 - **Query tabs**: one tab per query. The active tab is raised. Tabs that hold a saved (managed) query show a small dot before their name; the dot turns amber when the query has unsaved changes. Hover a tab to show its close button (×), click **+** to add a tab
 - **Search queries and commands** (`Ctrl+K`, or `⌘K` on a Mac): see [Search](#search)
-- **Help** (?): opens the MatGUI user guide in a new browser tab
+- **Help** (?): opens the help menu with **What's new** and the **Documentation** (see [Help Menu and What's New](#help-menu-and-whats-new)). A blue dot on the button means there is a release you haven't seen yet
 - **Theme** (sun / moon): switches between the light and dark theme
 - **Settings** (gear): opens the settings of the active tab
 
@@ -362,11 +363,22 @@ Click **Search queries and commands** in the top bar, or press `Ctrl+K` (`⌘K`
 
 - **Queries**: the saved queries of all your workspaces, with the workspace and folder they are in. Pick one to open it in a new tab, or to go to the tab that already has it open
 - **Snippets**: the code snippets of the [Insert menu](#insert-menu), found by name, group or the code they write (`filter` finds the comparison snippets). Pick one to insert it at the cursor
-- **Commands**: Run query, New tab, Insert snippet, Insert PREFIX declarations, Switch endpoint, Explore endpoint, Show saved queries, Toggle side panel, Toggle side-by-side layout, Format, Share, Save, Download, full screen editor, dark mode and the documentation. Commands with a shortcut show it at the right
+- **Commands**: Run query, New tab, Insert snippet, Insert PREFIX declarations, Switch endpoint, Explore endpoint, Show saved queries, Toggle side panel, Toggle side-by-side layout, Format, Share, Save, Download, full screen editor, dark mode, What's new and the documentation. Commands with a shortcut show it at the right
 - **Settings**: every page of the settings (General, SPARQL endpoints, Workspaces, Prefixes, Editor, AI, Import / export, Keyboard shortcuts, About), for example type `prefixes` and pick **Settings: Prefixes**
 
 Type `>` first to search commands and settings only. Snippets and settings show up once you type something. Use `↑` and `↓` to move, `Enter` to open and `Esc` to close.
 
+### Help Menu and What's New
+
+Click **Help** (?) in the top bar to open the help menu:
+
+- **What's new**: what changed in each version of MatGUI since 5.0.0, newest first. Every change is marked **New**, **Improved** or **Fixed**; use the buttons at the top to show only one kind. Releases you haven't seen yet are marked **New to you**. **Full release notes on GitHub** opens the complete notes, including the changes for developers
+- **Documentation**: opens this user guide in a new browser tab
+
+After MatGUI is updated, a blue dot on the Help button and next to **What's new** tells you there is something new. The dot goes away once you open What's new. On your first visit there is no dot. You can also open it from the [search](#search) (`Ctrl+K`, then type `what's new`). Press `Esc` to close it.
+
+Sites that embed MatGUI can leave out What's new (`showWhatsNew: false`) or the documentation link (`helpUrl: false`).
+
 ### Query Card
 
 The head of the card shows:

packages/yasgui/src/CommandPalette.ts

@@ -386,6 +386,15 @@ export default class CommandPalette {
         },
       });
     }
+    if (yasgui.whatsNew) {
+      commands.push({
+        section: "commands",
+        label: "What's new",
+        icon: "sparkles",
+        keywords: "release notes changelog changes version update",
+        run: () => yasgui.whatsNew?.open(),
+      });
+    }
     if (yasgui.config.helpUrl) {
       const helpUrl = yasgui.config.helpUrl;
       commands.push({

packages/yasgui/src/PersistentConfig.ts

@@ -25,6 +25,7 @@ export interface PersistedJson {
   sidePanel?: SidePanelState; // Left side panel (Queries / Endpoint / AI)
   requestSettings?: RequestSettings; // Request settings of Settings → General, shared by all tabs
   editorSettings?: EditorSettings; // Formatter and checks of Settings → General and Editor, shared by all tabs
+  whatsNewSeen?: string; // Newest version the user has seen in What's new
 }
 /** Settings of the query editor that apply to every tab */
 export interface EditorSettings {
@@ -67,6 +68,8 @@ export default class PersistentConfig {
   private storageId: string | undefined;
   private yasgui: Yasgui;
   private storage: YStorage;
+  /** Whether a configuration was stored before this page load (false on a first visit) */
+  private hadStoredConfig = false;
   constructor(yasgui: Yasgui) {
     this.yasgui = yasgui;
     this.storageId = this.yasgui.getStorageId(this.yasgui.config.persistenceLabelConfig);
@@ -139,7 +142,9 @@ export default class PersistentConfig {
     );
   }
   private fromStorage(): PersistedJson {
-    this.persistedJson = this.storage.get<PersistedJson>(this.storageId) || getDefaults();
+    const stored = this.storage.get<PersistedJson>(this.storageId);
+    this.hadStoredConfig = !!stored;
+    this.persistedJson = stored || getDefaults();
     /**
      * Modify some settings for backwards compatability
      */
@@ -154,6 +159,18 @@ export default class PersistentConfig {
     PersistentConfig.clear();
   }
 
+  /** False on a first visit, before anything was stored */
+  public hasStoredConfig(): boolean {
+    return this.hadStoredConfig;
+  }
+  public getWhatsNewSeen(): string | undefined {
+    return this.persistedJson.whatsNewSeen;
+  }
+  public setWhatsNewSeen(version: string) {
+    this.persistedJson.whatsNewSeen = version;
+    this.toStorage();
+  }
+
   public getTabs() {
     return this.persistedJson.tabs;
   }

packages/yasgui/src/defaults.ts

@@ -37,6 +37,7 @@ export default function initialize(): Config<CatalogueItem> {
     iriHover: true,
     iriHoverLovFallback: true,
     helpUrl: "https://matgui-doc.matdata.eu/docs/user-guide",
+    showWhatsNew: true,
     endpointDescribe: {
       enabled: true,
       timeoutMs: 60000,

packages/yasgui/src/index.ts

@@ -27,6 +27,7 @@ import SparqlAnythingSupport from "./sparqlAnything/SparqlAnythingSupport";
 import SidePanel from "./sidePanel/SidePanel";
 import CommandPalette from "./CommandPalette";
 import HelpMenu from "./HelpMenu";
+import WhatsNew from "./whatsNew/WhatsNew";
 import AiAssistant from "./ai/AiAssistant";
 import type { AiConfig } from "./ai/types";
 import "./index.scss";
@@ -135,6 +136,10 @@ export interface Config<EndpointObject extends CatalogueItem = CatalogueItem> {
    * hides when its menu has no other entries, such as the quick start tour or what's new).
    */
   helpUrl?: string | false;
+  /**
+   * Show "What's new" in the help menu, with a dot on the help button after an update (default: true)
+   */
+  showWhatsNew?: boolean;
   /**
    * Show the label, description and type of an IRI when hovering it in the query editor, fetched from the
    * endpoint of the tab (default: true). Users can switch it off in the editor settings.
@@ -216,6 +221,8 @@ export class Yasgui extends EventEmitter {
   public commandPalette: CommandPalette | undefined;
   /** Menu of the help button in the top bar; add entries with `helpMenu.addItem()` */
   public helpMenu: HelpMenu;
+  /** What's new dialog (help menu and Ctrl+K search), unless `showWhatsNew` is false */
+  public whatsNew: WhatsNew | undefined;
   /** AI assistant (the "AI" view of the side panel), unless `ai.enabled` is false */
   public aiAssistant: AiAssistant | undefined;
   /** SPARQL Anything support (the "Source" view of the side panel), unless `sparqlAnything` is false */
@@ -254,6 +261,7 @@ export class Yasgui extends EventEmitter {
     }
 
     this.helpMenu = new HelpMenu(this);
+    if (this.config.showWhatsNew) this.whatsNew = new WhatsNew(this);
     this.tabElements = new TabElements(this);
     this.tabPanelsEl = document.createElement("div");
     addClass(this.tabPanelsEl, "yasgui-tabPanels");
@@ -605,6 +613,7 @@ export class Yasgui extends EventEmitter {
     this.sparqlAnything?.destroy();
     this.aiAssistant?.destroy();
     this.commandPalette?.destroy();
+    this.whatsNew?.destroy();
     this.helpMenu.destroy();
     this.sidePanel.destroy();
     this.tabElements.destroy();