@loomweaver/plugin-sdk 0.7.6 → 0.7.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomweaver/plugin-sdk",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "LoomWeaver plugin contract: the public SDK a weaver depends on — ProductIdentity, Command, PluginContext and the host UI vocabulary.",
   "keywords": [
     "loomweaver",

package/src/lib/bar-item.d.ts

@@ -1,5 +1,6 @@
 import { Type } from '@angular/core';
 import { AccessRequirement } from './auth.js';
+import { MenuHeader, MenuTrigger } from './menu.js';
 /** Bar slots. */
 export type BarSlot = 'start' | 'center' | 'end';
 interface BarItemBase {
@@ -34,6 +35,19 @@ export interface BarButtonItem extends BarItemBase {
     readonly icon?: string;
     /** Transloco key/literal for a visible text label (optional). */
     readonly label?: string;
+    /**
+     * One or two letters the host draws **instead of** {@link icon}, for a button standing for
+     * someone or something named rather than for an action. Keep it to two characters.
+     */
+    readonly initials?: string;
+    /**
+     * A picture of what this button stands for, as anything an image element accepts. Drawn in place
+     * of {@link icon} and {@link initials}, cropped round. The order is picture, then initials, then
+     * icon, and the host falls back on its own where the picture is absent or fails to load. Reaching
+     * it is yours: the workbench does not fetch it, and another origin has to be allowed by your own
+     * content policy.
+     */
+    readonly image?: string;
     /** Transloco key/literal for the tooltip; falls back to {@link label}. */
     readonly tooltip?: string;
     /**
@@ -42,6 +56,16 @@ export interface BarButtonItem extends BarItemBase {
      * Contribute items to the slot with `ctx.registerMenuItem({ menu, … })`. Omit for no context menu.
      */
     readonly menu?: string;
+    /**
+     * Which gesture opens {@link menu}. Defaults to `'context'`, so a button that says nothing keeps
+     * the right-click it always had. Ignored without {@link menu}.
+     */
+    readonly menuTrigger?: MenuTrigger;
+    /**
+     * A heading naming what the menu is about, drawn above its first entry. Only where activation
+     * opens the menu, since a right-click already points at this button; ignored otherwise.
+     */
+    readonly menuHeader?: MenuHeader;
     /**
      * Id of a registered {@link Command} this button triggers. Provide this **or** {@link run}; when
      * set, the host runs that command (so a keybinding/palette can share the same behaviour).

package/src/lib/menu.d.ts

@@ -46,3 +46,42 @@ export interface MenuItem {
      */
     readonly checkedWhen?: MenuContext;
 }
+/**
+ * Which gesture opens the menu slot a chrome item names: its context menu on right-click (the
+ * default), its primary activation — a click, Enter or Space — with the menu anchored to the
+ * control the host drew, or both.
+ *
+ * Activation opens the item's **own** slot alone: the workbench's entries for that item, such as
+ * the ones that hide or move it, stay on the right-click, where a curation entry beside "Sign out"
+ * would be noise. An item whose activation opens its menu needs no `command` or `run` of its own,
+ * and the host draws it all the same.
+ */
+export type MenuTrigger = 'context' | 'primary' | 'both';
+/**
+ * A heading for a menu, naming the thing it was opened against — an account, a document, a tenant.
+ * The host draws it above the first entry of a menu opened by ACTIVATION (see {@link MenuTrigger});
+ * a menu opened at the pointer carries none, because what it acts on is under the pointer.
+ *
+ * It is not an entry: it cannot be focused or activated, and the keyboard passes over it the way it
+ * passes over a separator. The menu is announced by what it names, so the name reaches the user
+ * exactly once.
+ */
+export interface MenuHeader {
+    /** The name — Transloco key or literal. */
+    readonly title: string;
+    /** A second line under the name, for an address, a role or a tenant — key or literal. */
+    readonly detail?: string;
+    /** Icon name drawn beside the name, resolved by the host icon registry. */
+    readonly icon?: string;
+    /**
+     * A picture of what the menu was opened against, drawn in place of {@link icon} and
+     * {@link initials} and cropped round. Same ladder as a launcher entry's: picture, initials, icon,
+     * with the host falling back on its own where the picture is absent or fails to load.
+     */
+    readonly image?: string;
+    /**
+     * One or two letters the host draws **instead of** {@link icon}, for a name that is the user's
+     * rather than yours. Same rule as a launcher entry's: keep it to two characters.
+     */
+    readonly initials?: string;
+}

package/src/lib/rail-item.d.ts

@@ -1,4 +1,5 @@
 import { AccessRequirement } from './auth.js';
+import { MenuHeader, MenuTrigger } from './menu.js';
 /**
  * A Rail/Ribbon item: an **independent command** triggered from the far
  * rail — not a view switcher (switching views is the panel's tab bar). Mirrors
@@ -21,6 +22,18 @@ export interface RailItem {
      * so hover and the active marker behave exactly as elsewhere.
      */
     readonly initials?: string;
+    /**
+     * A picture of what this entry stands for — a person, a project, a tenant — as anything an image
+     * element accepts, an address you serve or a data URL. Drawn in place of {@link icon} and
+     * {@link initials}, cropped round.
+     *
+     * The order is picture, then {@link initials}, then {@link icon}, and the **host** falls back: a
+     * picture that is absent or fails to load leaves the entry exactly as it would look without one,
+     * so you never have to handle the ordinary case of there being no photograph. Reaching the picture
+     * at all is yours: the workbench does not fetch it, and another origin has to be allowed by your
+     * own content policy.
+     */
+    readonly image?: string;
     /** Transloco key (or literal) for the tooltip/label. */
     readonly title: string;
     /** Lower renders first within its anchor group (default 0). */
@@ -33,6 +46,17 @@ export interface RailItem {
      * Contribute items to the slot with `ctx.registerMenuItem({ menu, … })`. Omit for no context menu.
      */
     readonly menu?: string;
+    /**
+     * Which gesture opens {@link menu}. Defaults to `'context'`, so an item that says nothing keeps
+     * the right-click it always had. Ignored without {@link menu}, and on an item that names a
+     * {@link workspace}, where activating it is the switch.
+     */
+    readonly menuTrigger?: MenuTrigger;
+    /**
+     * A heading naming what the menu is about, drawn above its first entry. Only where activation
+     * opens the menu, since a right-click already points at this item; ignored otherwise.
+     */
+    readonly menuHeader?: MenuHeader;
     /**
      * Id of a registered {@link Command} this item triggers. Provide this **or** {@link run}; when
      * set, the host runs that command (so a keybinding/palette can share the same behaviour).