@ichicraft/widgets-widget-base 1.21.0 → 1.22.0

package/README.md

@@ -1,5 +1,3 @@
-This package supports development of widgets built using the Widget Development Kit
-
 _This package is part of the Widget Development Kit, which is a collection of NPM packages that empower developers to create widgets for Bloom Intranet._
 
 # @ichicraft/widgets-widget-base
@@ -146,6 +144,20 @@ Entries from 1.21.0 onwards are generated from pull request descriptions when a
 
 <!-- changelog:insert -->
 
+## 1.22.0 - 2026-09-15
+
+### Added
+- Widgets can change how the board draws their header and body: the header can show as an overlay on hover instead of a bar, the actions can be limited to the essential ones the user can perform, and the body can be transparent without a card.
+- Widgets can show an icon before their title, with an optional color and tooltip. While a widget is being debugged, the debug icon takes its place.
+- Widgets can show a badge after their title, with a count or a short text.
+- The design settings now include the spacing between widgets on the board, so a widget can align its own columns with the board.
+- Widgets can read and follow properties that change while they are loaded: their title and subtitle, the selected tab, deep link data, their size in the board grid, the render options the board applies, whether they are being dragged or resized, whether the user can change their settings, and the current design and theme.
+- Widgets that follow design and theme changes themselves are no longer reloaded when the user switches themes, for example to dark mode.
+- Widgets can tell whether they are loaded from a local debug session instead of their published build.
+
+### Changed
+- Showing or hiding the widget header is replaced by the new render options. The previous function keeps working and maps to the header render mode.
+
 ## 1.21.0 - 2026-08-27
 
 ### Changed

package/lib/types/index.d.ts

@@ -345,14 +345,28 @@ export interface WidgetInstanceContext {
      * Functionality offered by the widget board to append the title of the widget with additional text.
      */
     setWidgetTitleSuffix?: (suffix: string) => void;
+    /**
+     * Displays a badge after the title of the widget. A number is displayed as a count badge, a string as its text.
+     * Provide `undefined`, `0` or an empty string to remove the badge.
+     */
+    setWidgetTitleBadge?: (badge: string | number | undefined) => void;
+    /**
+     * Displays an icon before the title of the widget. Provide `undefined` to remove the icon.
+     */
+    setWidgetHeaderIcon?: (icon: WidgetHeaderIconProps | undefined) => void;
     /**
      * Functionality offered by the widget board to change the subtitle of the widget.
      */
     setWidgetSubtitle?: (subtitle: string) => void;
     /**
      * Show or hide the header of the widget, allowing widgets to take control of full widget real estate.
+     * @deprecated Use `setWidgetRenderOptions` instead. `true` maps to `WidgetHeaderRenderMode.Default`, `false` to `WidgetHeaderRenderMode.Overlay`.
      */
     setWidgetHeaderVisibility?: (visible: boolean) => void;
+    /**
+     * Changes how the widget board renders the chrome around this widget. Only the provided options are changed.
+     */
+    setWidgetRenderOptions?: (options: Partial<WidgetRenderOptions>) => void;
     /**
      * Show or hide the settings button of the widget.
      */
@@ -410,6 +424,123 @@ export interface WidgetInstanceContext {
      * Data stored here is specific to this instance only.
      */
     cache: CacheManager;
+    /**
+     * Properties of this widget instance that can change while the widget is loaded, such as the size it occupies in the board grid.
+     * Subscribe to be notified of changes without the widget being reloaded.
+     */
+    dynamic?: DynamicWidgetInstanceContext;
+}
+export declare enum WidgetHeaderRenderMode {
+    /** A header bar at the top of the widget, showing the title and actions. */
+    Default = "default",
+    /** No header bar. Actions are shown on top of the widget body when hovering the widget. */
+    Overlay = "overlay"
+}
+export declare enum WidgetHeaderActionsMode {
+    /** All actions available to the user. */
+    All = "all",
+    /** Only essential actions the user can currently perform; informational, secondary and disabled actions are hidden. */
+    Limited = "limited"
+}
+export declare enum WidgetBodyRenderMode {
+    /** The widget is rendered on a card, with a background and shadow. */
+    Default = "default",
+    /** No background or shadow. The header is always rendered as `WidgetHeaderRenderMode.Overlay`. */
+    Transparent = "transparent"
+}
+export interface WidgetHeaderIconProps {
+    /** Name of a Fluent UI icon. */
+    iconName?: string;
+    /** Url of an image, used when no `iconName` is provided. */
+    imageUrl?: string;
+    /** Color of the icon. Only applies to `iconName`. Defaults to the theme's primary color. */
+    color?: string;
+    /** Tooltip displayed when hovering the icon. */
+    tooltip?: string;
+}
+export interface WidgetRenderOptions {
+    /** How the header is rendered. Defaults to `WidgetHeaderRenderMode.Default`. */
+    headerMode: WidgetHeaderRenderMode;
+    /** Which actions the header offers. Defaults to `WidgetHeaderActionsMode.All`. */
+    actionsMode: WidgetHeaderActionsMode;
+    /** How the widget body is rendered. Defaults to `WidgetBodyRenderMode.Default`. */
+    bodyMode: WidgetBodyRenderMode;
+}
+export declare enum WidgetUserConfigAccess {
+    /** The widget has no user configuration (`isConfigurableByUser` is `false` in its manifest). */
+    None = "none",
+    /** The current user can change this widget's user configuration. */
+    Editable = "editable",
+    /** The current user normally can, but not right now, e.g. while another user edits the shared board or the SharePoint page is in edit mode. */
+    Blocked = "blocked",
+    /** The current user can't change this widget's user configuration, e.g. when viewing someone else's shared board. */
+    ReadOnly = "readOnly"
+}
+export interface WidgetGridItemSize {
+    /** Number of board grid columns the widget occupies. */
+    columns: number;
+    /** Number of board grid rows the widget occupies. */
+    rows: number;
+}
+/** Widget properties that can change while the widget is loaded. */
+export interface DynamicWidgetInstanceContextValue {
+    /**
+     * The widget's current title: set through `setWidgetTitle`, renamed by the user, or the variant's title, in that order.
+     * Excludes the suffix set through `setWidgetTitleSuffix`.
+     */
+    title?: string;
+    /** The widget's current subtitle: set through `setWidgetSubtitle` or the variant's subtitle, with its tokens replaced. */
+    subtitle?: string;
+    /** The tab shown as selected, whether the widget or the user selected it. */
+    selectedTabId?: string;
+    /** This instance's deep link data in the current url; the same value `getDeepLinkData()` returns. */
+    deepLinkData: string;
+    /** The size the widget occupies in the board grid. Only set when the widget is on a board, not in the buddy bar or a web part. */
+    size?: WidgetGridItemSize;
+    /**
+     * The render options the widget board currently applies: the options requested through `setWidgetRenderOptions`,
+     * after the board's overrides. For example, the header renders as an overlay when the widget
+     * is scaled down, and the body keeps its card while an error is shown.
+     */
+    renderOptions: WidgetRenderOptions;
+    /** Whether the user is dragging the widget. */
+    isDragging: boolean;
+    /** Whether the user is resizing the widget. While `true`, `size` describes the size the widget will snap to. */
+    isResizing: boolean;
+    /** Pointer events on the widget body are blocked, e.g. while any widget on the board is dragged or resized. */
+    isPointerEventsDisabled: boolean;
+    /** Whether the current user can change this widget's user configuration right now. */
+    userConfigAccess: WidgetUserConfigAccess;
+    /**
+     * The design settings of the user's current theme; the live counterpart of `WidgetContext.design`.
+     * The widget is reloaded when this changes, unless it subscribed to `design` by name.
+     */
+    design: WidgetDesignContext;
+    /**
+     * The currently used theme, e.g. after switching to dark mode; the live counterpart of `WidgetContext.theme`.
+     * The widget is reloaded when this changes, unless it subscribed to `theme` by name.
+     */
+    theme: any;
+}
+export type DynamicWidgetInstanceContextKey = keyof DynamicWidgetInstanceContextValue;
+export type DynamicWidgetInstanceContextListener = (value: DynamicWidgetInstanceContextValue) => void;
+export interface DynamicWidgetInstanceContext {
+    /** The current value. Also available during `init` and `render`. */
+    readonly current: DynamicWidgetInstanceContextValue;
+    /**
+     * Calls the listener when one of `keys` changes, or on every change when `keys` is omitted.
+     * Subscribing to `design` or `theme` by name tells the widget board the widget applies those changes itself,
+     * so it isn't reloaded when they change. Subscribing the same listener again replaces its keys.
+     * @returns A function that removes this listener.
+     */
+    subscribe: (listener: DynamicWidgetInstanceContextListener, keys?: DynamicWidgetInstanceContextKey[]) => () => void;
+    /** Removes a listener passed to `subscribe`. Requires the same function reference. */
+    unsubscribe: (listener: DynamicWidgetInstanceContextListener) => void;
+    /**
+     * Removes all listeners of this widget, including those added by hooks of mounted components.
+     * Intended for teardown, e.g. in `cleanupResources`.
+     */
+    unsubscribeAll: () => void;
 }
 export interface WidgetBuddyContext {
     /**
@@ -491,14 +622,20 @@ export interface WidgetManifestContext {
      * Data stored here is shared across all variants and instances of this widget type.
      */
     cache: CacheManager;
+    /**
+     * Whether the widget board loaded this widget from a local debug session instead of its published build.
+     */
+    isDebugging?: boolean;
 }
 export interface WidgetDesignContext {
     /** Available options in the ColorPicker.*/
     colorOptions: ColorOption[];
     /** Preferred border radius of UI elements.*/
     borderRadius: number;
-    /** The height of a single row in the board grid. Use this to determine how many columns high a widget is. */
+    /** The height of a single row in the board grid. To know how many rows a widget occupies, use `instance.dynamic.current.size` instead. */
     rowHeight: number;
+    /** Spacing between widgets in the board grid, in pixels. Use this to align columns within a widget with the board's columns. */
+    gridSpacing?: number;
     /** Design settings related to icon badges. */
     badge: {
         /** Background color of an icon badge. */

package/lib/types/index.js

@@ -1,6 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CommandBarItemType = exports.CustomCommandBarItemSeverity = void 0;
+exports.CommandBarItemType = exports.CustomCommandBarItemSeverity = exports.WidgetUserConfigAccess = exports.WidgetBodyRenderMode = exports.WidgetHeaderActionsMode = exports.WidgetHeaderRenderMode = void 0;
+var WidgetHeaderRenderMode;
+(function (WidgetHeaderRenderMode) {
+    /** A header bar at the top of the widget, showing the title and actions. */
+    WidgetHeaderRenderMode["Default"] = "default";
+    /** No header bar. Actions are shown on top of the widget body when hovering the widget. */
+    WidgetHeaderRenderMode["Overlay"] = "overlay";
+})(WidgetHeaderRenderMode || (exports.WidgetHeaderRenderMode = WidgetHeaderRenderMode = {}));
+var WidgetHeaderActionsMode;
+(function (WidgetHeaderActionsMode) {
+    /** All actions available to the user. */
+    WidgetHeaderActionsMode["All"] = "all";
+    /** Only essential actions the user can currently perform; informational, secondary and disabled actions are hidden. */
+    WidgetHeaderActionsMode["Limited"] = "limited";
+})(WidgetHeaderActionsMode || (exports.WidgetHeaderActionsMode = WidgetHeaderActionsMode = {}));
+var WidgetBodyRenderMode;
+(function (WidgetBodyRenderMode) {
+    /** The widget is rendered on a card, with a background and shadow. */
+    WidgetBodyRenderMode["Default"] = "default";
+    /** No background or shadow. The header is always rendered as `WidgetHeaderRenderMode.Overlay`. */
+    WidgetBodyRenderMode["Transparent"] = "transparent";
+})(WidgetBodyRenderMode || (exports.WidgetBodyRenderMode = WidgetBodyRenderMode = {}));
+var WidgetUserConfigAccess;
+(function (WidgetUserConfigAccess) {
+    /** The widget has no user configuration (`isConfigurableByUser` is `false` in its manifest). */
+    WidgetUserConfigAccess["None"] = "none";
+    /** The current user can change this widget's user configuration. */
+    WidgetUserConfigAccess["Editable"] = "editable";
+    /** The current user normally can, but not right now, e.g. while another user edits the shared board or the SharePoint page is in edit mode. */
+    WidgetUserConfigAccess["Blocked"] = "blocked";
+    /** The current user can't change this widget's user configuration, e.g. when viewing someone else's shared board. */
+    WidgetUserConfigAccess["ReadOnly"] = "readOnly";
+})(WidgetUserConfigAccess || (exports.WidgetUserConfigAccess = WidgetUserConfigAccess = {}));
 /**
  * Tells the severity of the command bar item, resulting in
  * distinguishable presentation of the item

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@ichicraft/widgets-widget-base",
-    "version": "1.21.0",
-    "description": "Part of the Widget Development Kit for building widgets for Bloom Intranet",
+    "version": "1.22.0",
+    "description": "Part of the Widget Development Kit for building widgets for Bloom Intranet. The base class and context types every widget implements.",
     "main": "lib/index.js",
     "types": "lib/index.d.ts",
     "scripts": {