@ichicraft/widgets-widget-base 1.20.0 → 1.22.0

package/lib/dev/createWidgetDevServerConfig.js

@@ -12,7 +12,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createWidgetDevServerConfig = exports.DEFAULT_WIDGET_DEBUG_PORT = void 0;
+exports.DEFAULT_WIDGET_DEBUG_PORT = void 0;
+exports.createWidgetDevServerConfig = createWidgetDevServerConfig;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
@@ -27,8 +28,8 @@ exports.DEFAULT_WIDGET_DEBUG_PORT = 8080;
  * board always matches the port the server actually binds to.
  */
 function createWidgetDevServerConfig(options) {
-    var _a;
     return __awaiter(this, void 0, void 0, function* () {
+        var _a;
         const { projectPath, serveConfig } = options;
         const port = (_a = serveConfig.debugPort) !== null && _a !== void 0 ? _a : (yield (0, findAvailablePort_1.findAvailablePort)(exports.DEFAULT_WIDGET_DEBUG_PORT));
         const manifestUrl = `https://localhost:${port}/manifest.json`;
@@ -74,7 +75,6 @@ function createWidgetDevServerConfig(options) {
         };
     });
 }
-exports.createWidgetDevServerConfig = createWidgetDevServerConfig;
 /**
  * Uses the SPFx localhost certificate that was trusted with `gulp trust-dev-cert`,
  * falling back to the rushstack certificate on newer toolchains.

package/lib/dev/findAvailablePort.js

@@ -12,7 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.findAvailablePort = void 0;
+exports.findAvailablePort = findAvailablePort;
 const net_1 = __importDefault(require("net"));
 /** Both loopback stacks are checked: a dev server on one of them still owns the port. */
 const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
@@ -20,8 +20,8 @@ const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
  * Resolves the first free TCP port at or above `startPort`, so several widget dev servers
  * can run side by side without anyone having to hand out port numbers.
  */
-function findAvailablePort(startPort, attempts = 50) {
-    return __awaiter(this, void 0, void 0, function* () {
+function findAvailablePort(startPort_1) {
+    return __awaiter(this, arguments, void 0, function* (startPort, attempts = 50) {
         for (let port = startPort; port < startPort + attempts; port++) {
             if (yield isPortAvailable(port)) {
                 return port;
@@ -30,7 +30,6 @@ function findAvailablePort(startPort, attempts = 50) {
         throw new Error(`[widgets-widget-base] No free port found between ${startPort} and ${startPort + attempts - 1}. Stop a running dev server or set "debugPort" in config/serve.config.ts.`);
     });
 }
-exports.findAvailablePort = findAvailablePort;
 function isPortAvailable(port) {
     return __awaiter(this, void 0, void 0, function* () {
         for (const host of LOOPBACK_HOSTS) {

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/lib/utils/ConfigurationHelper.d.ts

@@ -6,8 +6,8 @@ export declare class ConfigurationHelper {
     /**
      *
      * @param config The serialized configuration to parse into an object
-     * @param schema Deprecated: schema validation is no longer possible
+     * @param _schema Deprecated: kept so existing two-argument callers still compile.
      */
-    static parseConfiguration<T>(config: string, schema?: any): T;
-    static stringifyConfiguration(config: any): string;
+    static parseConfiguration<T>(config: string, _schema?: unknown): T;
+    static stringifyConfiguration(config: unknown): string;
 }

package/lib/utils/ConfigurationHelper.js

@@ -9,9 +9,9 @@ class ConfigurationHelper {
     /**
      *
      * @param config The serialized configuration to parse into an object
-     * @param schema Deprecated: schema validation is no longer possible
+     * @param _schema Deprecated: kept so existing two-argument callers still compile.
      */
-    static parseConfiguration(config, schema) {
+    static parseConfiguration(config, _schema) {
         const data = JSON.parse(config ? config : '{}');
         return data;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@ichicraft/widgets-widget-base",
-    "version": "1.20.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": {
@@ -9,7 +9,8 @@
         "build:watch": "tsc --build --force --verbose --watch tsconfig.json tsconfig.dev.json",
         "clean": "rimraf lib",
         "pretty": "prettier --write \"./**/*.{js,jsx,mjs,cjs,ts,tsx,json}\"",
-        "prepublishOnly": "npm run clean && npm run build"
+        "prepublishOnly": "npm run clean && npm run build",
+        "lint": "eslint src"
     },
     "keywords": [
         "ichicraft",
@@ -22,27 +23,22 @@
         "lib/**/*",
         "!lib/**/*.tsbuildinfo"
     ],
-    "overrides": {
-        "requirejs": "2.3.7",
-        "validator@<13.15.26": "13.15.26",
-        "z-schema@<5.0.5": "5.0.5"
-    },
     "dependencies": {
-        "@ichicraft/caching": "~1.0.2",
+        "@ichicraft/caching": "~1.2.0",
         "@microsoft/microsoft-graph-client": "3.0.2",
-        "@microsoft/sp-http": "1.18.2",
+        "@microsoft/sp-http": "^1.23.2",
         "@pnp/sp": "4.0.1"
     },
     "devDependencies": {
-        "@ianvs/prettier-plugin-sort-imports": "4.4.1",
+        "@eslint/js": "^10.0.1",
+        "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
         "@types/node": "^18.19.0",
-        "eslint": "8.57.0",
-        "eslint-config-prettier": "9.1.0",
-        "eslint-plugin-prettier": "5.2.1",
-        "eslint-plugin-react": "7.35.2",
-        "eslint-plugin-react-hooks": "4.6.2",
-        "prettier": "3.3.3",
-        "typescript": "~5.3.3",
+        "eslint": "^10.9.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-prettier": "^5.5.6",
+        "prettier": "^3.9.6",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.68.0",
         "webpack": "^5.109.2",
         "webpack-dev-server": "^5.2.6"
     },