@loomweaver/plugin-sdk 0.7.7 → 0.7.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomweaver/plugin-sdk",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "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/content-route.d.ts

@@ -199,9 +199,8 @@ export interface ContentRouteBase {
     /** Whether the user may close a tab of this route — carried through from {@link Surface.closable}. */
     readonly closable?: boolean;
     /**
-     * Whether the host insets this surface from its pane edges (default `true`). Declare `false` for a
-     * surface that owns its own edges — a viewer, a canvas, a map, an edge-to-edge table. See
-     * `SurfaceBase.padded`.
+     * Whether the host insets this surface from its pane edges. Absent, the product's own default
+     * applies, which is no inset unless the distribution asked for one. See `SurfaceBase.padded`.
      */
     readonly padded?: boolean;
 }

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,9 +46,25 @@ 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).
+     *
+     * The host never marks such an item as current, not even while the address its command opened is
+     * the one on screen: only a {@link workspace} entry is marked, because a command may do anything
+     * and the host cannot tell what "being there" would mean for it. An entry meant to read as a
+     * place the user is *in* belongs to a workspace, not to a command that navigates.
      */
     readonly command?: string;
     /**

package/src/lib/surface.d.ts

@@ -190,13 +190,18 @@ export interface SurfaceBase {
      */
     readonly closable?: boolean;
     /**
-     * Whether the host insets this surface from its pane edges. Defaults to `true` — comfortable for the
-     * prose, forms and lists most surfaces are. Declare `false` for a surface that **is** the content and
-     * owns its own edges: a viewer, a canvas, a map, an edge-to-edge table. It travels with the surface,
-     * so it holds wherever the user puts it — the URL pane, a split, a sidebar, a pop-out window.
+     * Whether the host insets this surface from its pane edges. Leave it out and the product decides:
+     * the host insets nothing unless the distribution asked it to, with `padding` on `provideShell`.
      *
-     * Only the inset is yours to switch off; how wide it is stays a styling question, so a product that
-     * wants a different amount everywhere writes plain unlayered CSS rather than asking for a token.
+     * Declare it where this surface differs from the product's answer, in either direction. `true` for
+     * the prose, forms and lists that read better with air around them; `false` for a surface that
+     * **is** the content and owns its own edges — a viewer, a canvas, a map, an edge-to-edge table —
+     * in a product that insets everything else. It travels with the surface, so it holds wherever the
+     * user puts it: the URL pane, a split, a sidebar, a pop-out window.
+     *
+     * Only whether there is an inset is yours; how wide it is stays a styling question, so a product
+     * that wants a different amount everywhere writes plain unlayered CSS rather than asking for a
+     * token.
      */
     readonly padded?: boolean;
     /**

package/src/lib/view.d.ts

@@ -84,9 +84,8 @@ export interface View {
     /** Whether the user may close a tab of this view — carried through from {@link Surface.closable}. */
     readonly closable?: boolean;
     /**
-     * Whether the host insets this surface from its pane edges (default `true`). Declare `false` for a
-     * surface that owns its own edges — a viewer, a canvas, a map, an edge-to-edge table. See
-     * `SurfaceBase.padded`.
+     * Whether the host insets this surface from its pane edges. Absent, the product's own default
+     * applies, which is no inset unless the distribution asked for one. See `SurfaceBase.padded`.
      */
     readonly padded?: boolean;
     /** Component the host renders as the view body. */