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._ # Changelog All notable changes to this project will be documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## 1.19.0 - 2026-08-18 - Added optional `bloomGroups` provider to `WidgetContext`, exposing a `fetchGroups()` function that supplies the tenant's Bloom Group definitions. Widgets can pass it through to their people pickers so Bloom Groups can be offered as suggestions. ## 1.18.0 - 2026-08-17 - Added optional `assetsBaseUrl` property to the `WidgetContext` interface, containing the base URL of the folder the widget bundle was loaded from. This allows widgets to fetch files that are published alongside their bundle, such as per-language translation files. ## 1.17.0 - 2026-07-16 - Moved `UserHelper`, `ICPersona`, `ICPersonaType`, `ICSite`, `ICTeam` and `ICTerm` to an internal package. ## 1.16.6 - 2026-06-03 - Replaced unused `design.header.activeTextColor` with `design.header.subTextColor` ## 1.16.5 - 2026-06-01 - Added `BuddyRenderOptions` interface, passed by the host to `BaseWidget.renderBuddy` to describe the slot the widget is about to render into. - Added optional `options` parameter to `BaseWidget.renderBuddy`, of type `BuddyRenderOptions`. Contains an `allowRichRendering` boolean that signals whether the slot has room for richer rendering than the standard buddy icon button — letting the widget decide synchronously between custom and default rendering. ## 1.16.4 - 2026-05-27 - Added `header` property to `WidgetDesignContext` interface, exposing the header's `textColor`, `iconColor`, `activeTextColor` and `activeIconColor` from the user's theme. - Deprecated `defaultColor` property on `WidgetBuddyContext` interface in favor of `design.header.iconColor` (and `design.header.activeIconColor` for the hover/active state). ## 1.16.3 - 2026-05-08 - Added `whatsNewUrl` property to `WidgetManifestConfig` to allow quick access to updates that the widget has received. - Added `aboutUrl` property to `WidgetManifestConfig` to allow quick access to more information about the widget. ## 1.16.2 - 2026-03-25 - Fixed issue with using internal library `@ic/caching` by publishing caching library as public (`@ichicraft/caching`) ## 1.16.1 - 2026-03-19 - Addition of `notificationBadgeCount` property to `CommandBarItemProps` to allow for a number to be displayed in the badge ## 1.16.0 - 2026-03-09 - Addition of `cache` property to `instance`, `variant` and `manifest` level of `WidgetContext` to centralize cache handling and functionality ## 1.15.4 - 2026-01-07 - Override version of deep dependency 'validator' to get rid of potential vulnerability ## 1.15.3 - 2025-12-09 - Added property `isIndeterminate` to `ICTerm` interface, used to represent a term's indeterminate checkmark state. ## 1.15.2 - 2025-11-21 - Added new interface `ICTerm`, used to represent a SharePoint Taxonomy Term object in code ## 1.15.1 - 2025-09-30 - Added new interface `ICTeam`, used to represent a Microsoft Teams team object in code ## 1.15.0 - 2025-09-29 - Deprecated `msGraphClientFactory` in favor of `msGraphClient` in the `WidgetManifestConfig` interface. ## 1.14.7 - 2025-08-21 - Added `parentId` property to the `WidgetInstanceContext` interface, to support checking the ID of the parent of a widget instance. ## 1.14.6 - 2025-08-11 - Added `updateInstanceConfiguration` property to the `WidgetInstanceContext` interface, to support updating the instance configuration directly in a widget, instead of through the settings panel. ## 1.14.5 - 2025-08-07 - Added `imageUrl` property to the `CommandBarTab` interface, to support displaying images in widget header tabs. ## 1.14.4 - 2025-08-01 - Added `releaseType` property to the `WidgetManifestConfig` interface, to indicate the current stage of the release lifecycle a widget is in. - Added `registerOnBuddyClick` property to the `WidgetBuddyContext` interface, to allow overriding default onClick behavior when clicking on a buddy (by default, it opens the widget in a Callout). ## 1.14.3 - 2025-07-04 - Added `justification` string property to widget manifest to describe the reasoning behind the need for certain API permisisons ## 1.14.2 - 2025-07-02 - Reverted `@microsoft/sp-http` dependency back to SPFx version `1.18.2` due to postponed upgrade - Added `isOptional` boolean to widget manifest to allow marking certain API permission requests as optional ## 1.14.1 - 2025-06-17 - Reverted module type 'commonjs' for backwards compatibility ## 1.14.0 - 2025-05-21 - Version bumped `@microsoft/sp-http` dependency to latest SPFx version `1.21.1` ## 1.13.2 - 2025-04-11 - Minor update in documentation of `WebApiPermissionRequest` interface ## 1.13.1 - 2025-03-11 - Added new interface `ICSite`, used to represent a SharePoint site object in code ## 1.13.0 - 2025-02-17 - Fixed an issue with detecting external users in `UserHelper` - Changed target JavaScript version to `ES6` ## 1.12.0 - 2025-02-11 - Added `ColorOption` interface. - Added `WidgetDesignContext` interface. - Added `design` property of type `WidgetDesignContext` to `WidgetContext` interface, to support UI settings within widgets. - Deprecated `elementBorderRadius` property which is renamed to `borderRadius` and moved under `design` property in `WidgetContext` interface. ## 1.11.6 - 2025-01-30 - Added `spServiceScope` property to `WidgetContext` interface. - Added `loadComponentById` function to `WidgetContext` interface. - Deprecated `definition` property which is replaced by `variant` property in `WidgetContext` interface. - Deprecated `instance.publishNotification` function in `WidgetContext` interface because feature is no longer available. ## 1.11.5 - 2025-01-21 - Added `defaultColor` property to `WidgetBuddyContext` interface. ## 1.11.4 - 2024-11-08 - Added `driveId` property to `FilePickerFileProps` interface. ## 1.11.3 - 2024-11-05 - Added `fileName` property to `FilePickerFileProps` interface. ## 1.11.2 - 2024-10-21 - Added optional `objectId` property to the `ICPersona` interface. ## 1.11.1 - 2024-10-17 - Made `buddy` property of type `WidgetBuddyContext` optional. ## 1.11.0 - 2024-10-17 - Added `renderBuddy` function to the `BaseWidget` class, to support rendering widgets as a buddy. - Added `buddy` property of type `WidgetBuddyContext` to the `WidgetContext` interface, to support utility functions specifically for a widget buddy. - Added `setBadgeProperties` function to the `WidgetBuddyContext` interface, to allow rendering a badge on top of the buddy. ## 1.10.8 - 2024-10-15 - Added `buddybar` to the `BoardType` type, to support widgets that run in the scope of the upcoming buddy bar feature ## 1.10.7 - 2024-08-20 - Replaced `onInit` function with a new asynchronous `init` function in the `BaseWidget` class, to allow waiting until initialization is complete. ## 1.10.6 - 2024-08-19 - Added `userDisplayName` property to the `WidgetContext` interface, to allow using the currently signed-in user's display name in widgets. ## 1.10.5 - 2024-08-07 - Added `onSearch` property to the `CommandBarSearchItem` interface, to allow executing a callback when the user presses enter in the search box. ## 1.10.4 - 2024-07-23 - Added `SearchBar` value to the `CommandBarItemType` enum, to allow rendering a command bar item as a search bar. - Added `CommandBarSearchItem` interface, to allow passing extra search-related props to a CommandBarItem of type `SearchBar`. - Added optional `overflowButtonIconName` and `overflowButtonTooltip` properties to the `CommandBarTabOptions` interface, to allow customization of the overflow menu button. - Added optional `itemCount` property to the `CommandBarTab` interface. - Added summaries to functions and interfaces related to widget command bar tabs. ## 1.10.3 - 2024-07-22 - Added override in package.json to use version `2.3.7` instead of `2.3.6` of `requirejs` because the latter has vulnerability CVE-2024-38999 ## 1.10.2 - 2024-07-19 - Added `registerTabs` function to the `WidgetInstanceContext` interface, to allow rendering of tabs in the widget header. - Added `setSelectedTab` function to the `WidgetInstanceContext` interface, to allow setting the current selected tab in the widget header. - Added `CommandBarTab` interface. - Added `CommandBarTabOptions` interface. ## 1.10.1 - 2024-07-08 - Added `widget-administrator` role to the `UserRole` type. ## 1.10.0 - 2024-06-25 - Added optional `updateDataAccess()` function to the `BaseWidget` class, used to update access to widget-specific data. - Added `administrators` property to the `WidgetVariantContext` interface. ## 1.9.14 - 2024-06-18 - Change import of `SPFI` type to decrease bundle sizes in widgets. ## 1.9.13 - 2024-06-18 - Added `spHttpClient` property to `WidgetContext` interface, to perform REST calls against SharePoint. - Added `spHttpClientConfiguration` property to `WidgetContext` interface. ## 1.9.12 - 2024-06-17 - Added `sp` property to `WidgetContext` interface, to allow using a centralized PnPjs version across all widgets. - Added `siteId` property to `WidgetContext` interface. - Added `boardsInstanceId` property to `WidgetContext` interface. ## 1.9.11 - 2024-06-14 - Fixed handling of null `ICPersonaType` values in `isCurrentUserInScope` function of `UserHelper` class. ## 1.9.10 - 2024-06-04 - Renamed `CustomCommandBarItemProps` interface to `CommandBarItemProps`. - Merged `CommandBarIcon`, `CommandBarLink` and `CommandBarItemBase` interfaces into the `CommandBarItemProps` interface, to simplify adding custom command bar items. - Added `Overflow` type to `CommandBarItemType` enum, to allow rendering an item inside the overflow menu. - Added `highlighted` property to the `CommandBarItemProps` interface, to allow rendering an item as if it is being hovered. - Added `cursor` property to the `CommandBarItemProps` interface, to allow a different cursor when hovering over an item. - Added `disabled` property to the `CommandBarItemProps` interface, to allow rendering an item in a disabled state. ## 1.9.9 - 2024-05-14 - Changed return type of `createDeepLink` function of the WidgetInstanceContext interface from `void` to `string`. ## 1.9.8 - 2024-05-13 - Added `createDeepLink` property to the WidgetInstanceContext interface, to allow creating a deep link URL based on the current board and a widget instance. - Added `setDeepLinkData` property to the WidgetInstanceContext interface, to allow setting deep link data related to a widget instance in the URL of the current page. - Added `getDeepLinkData` property to the WidgetInstanceContext interface, to allow getting deep link data related to a widget instance from the URL of the current page. ## 1.9.7 - 2024-04-19 - Added `hideSpHubNav` property to the IFrameDialogOptions interface, to allow hiding the Hub navigation on SharePoint sites. - Added `hideSpSiteHeader` property to the IFrameDialogOptions interface, to allow hiding the site header on SharePoint sites. - Added `showHistoryButtons` property to the IFrameDialogOptions interface, to render back and forward buttons, allowing the user to navigate the browser history. - Added `showOpenInNewWindow` property to the IFrameDialogOptions interface, to render an 'open in new window' button, allowing the user to open the iframe url in a new browser window. ## 1.9.6 - 2024-04-19 - Changed `onRenderHeaderIcon` property of the IFrameDialogOptions interface, to work similarly to the widget render functions. ## 1.9.5 - 2024-04-18 - Added `title` property to the IFrameDialogOptions interface, to allow rendering a title in the dialog header. - Added `titleUrl` property to the IFrameDialogOptions interface, to allow making the dialog header title clickable. - Added `onRenderHeaderIcon` property to the IFrameDialogOptions interface, to allow rendering an icon in the dialog header. - Added `onLoad` property to the IFrameDialogOptions interface, to support executing some code after the iframe finishes loading. ## 1.9.4 - 2024-04-11 - Reintroduced the following types: `AadHttpClient`,`AadHttpClientConfiguration`,`AadHttpClientFactory`,`AadHttpClientResponse`, `AadTokenProvider`, `AadTokenProviderFactory` ## 1.9.2 - 2024-03-21 - Added `CommandBarIcon` interface, to allow rendering a `CustomCommandBarItem` as a single icon or an icon button. - Added `CommandBarLink` interface, to allow rendering a `CustomCommandBarItem` as a clickable link. - Added `CommandBarItemBase` interface, to act as a base for different types of `CustomCommandBarItem`. - Added `elementBorderRadius` property to the `WidgetContext` interface, to allow styling widgets according to the configured design preferences. - Changed `CustomCommandBarItemProps` type to accept either a `CommandBarIcon` or a `CommandBarLink`. ## 1.9.1 - 2023-10-20 - Added `WidgetInstanceContext` interface, to allow typing the `instance` property of the `WidgetContext` interface. - Added `WidgetVariantContext` interface, to allow typing the `definition` property of the `WidgetContext` interface. - Added `WidgetManifestContext` interface, to allow typing the `manifest` property of the `WidgetContext` interface. ## 1.9.0 - 2023-10-20 - Added optional `importData()` function to the `BaseWidget` class, used to import widget-specific data. - Added optional `exportData()` function to the `BaseWidget` class, used to export widget-specific data. - Added new exported `ExportData` type. ## 1.8.17 - 2023-10-09 - Added `iconName` property to the `definition` object of the `WidgetContext` interface, to support using an icon to represent a widget. ## 1.8.16 - 2023-09-26 - Added `Custom` value to `ICPersonaType` enum, to support a custom ICPersona. ## 1.8.15 - 2023-09-01 - Added `thumbnailUrl` property to `WidgetManifestConfig` interface, as a non-translatable substitute of the newly deprecated `preview_small` property from `WidgetImages` interface. - Removed the deprecated `preview_small` property from `WidgetImages` interface. ## 1.8.14 - 2023-09-01 - Added `iconName` property to `WidgetManifestConfig` interface, to support using an icon to represent a widget, e.g. in the widget library or widget header. - Removed the deprecated `notificationIcon` property from `WidgetManifestConfig` interface. ## 1.8.13 - 2023-06-08 - Removed the deprecated `resolved` property from `ICPersona` interface ## 1.8.12 - 2023-04-04 - Changed `openFilePicker` function to return more details of the picked file in the shape of `FilePickerFileProps` ## 1.8.11 - 2023-04-03 - Changed `openFilePicker` function to return more details of the picked file in the shape of `FilePickerFileProps` ## 1.8.10 - 2023-03-30 - Changed `openFilePicker` function to accept `options`, to support configuration of picker behavior ## 1.8.9 - 2023-03-06 - Added `registerCustomCommandBarItems` function to the `instance` object of the `WidgetContext` interface, to support multiple custom buttons in the widget header. - Added `unregisterCustomCommandBarItems` function to the `instance` object of the `WidgetContext` interface, to support removing all custom buttons in the widget header. - Added optional `id` property to exported `CustomCommandBarItemProps` type, to support removing a custom command bar item by id. - Added optional `pinned` property to exported `CustomCommandBarItemProps` type, to support forcing the widget header to always be visible. - Added optional `showNotificationBadge` property to exported `CustomCommandBarItemProps` type, to support showing a red notification badge over the custom command bar item. - Added optional `order` property to exported `CustomCommandBarItemProps` type, to support changing the order of custom command bar items. - Changed `unregisterCustomCommandBarItem` function of the `instance` object of the `WidgetContext` interface, to support removing a custom command bar item by id. ## 1.8.8 - 2023-02-16 - Removed all SharePoint and Teams dependencies. ## 1.8.7 - 2022-12-13 - Added `userRoles` property to the `WidgetContext` interface, to inform widgets of the roles of the current user. - Added new exported `UserRole` type. ## 1.8.6 - 2022-12-08 - Added `boardType` property to the `instance` object of the `WidgetContext` interface, to inform widgets of the type of their board. - Added `allowedBoardTypes` property to the `definition` object of the `WidgetContext` interface, to inform widget variants of the types of boards it is allowed to be added to. - Added new exported `BoardType` type. ## 1.8.5 - 2022-09-30 - Added `setWidgetTitleSuffix()` function to the `instance` object of the `WidgetContext` interface, to support appending the title of the widget with additional text. - Added `setWidgetSubtitle()` function to the `instance` object of the `WidgetContext` interface, to support overriding the subtitle of the widget. - Added `setUserConfigButtonVisibilty()` function to the `instance` object of the `WidgetContext` interface, to support hiding the settings button from the widget header. - Fixed spelling of `setWidgetHeaderVisibilty()` function. The function is now called `setWidgetHeaderVisibility()`. ## 1.8.4 - 2022-09-05 - Added `openIFrameDialog()` function to the `WidgetContext` interface. This has the same functionality as the `openUrlInDialog()` function of the `instance` object, but adds more control over the dimensions of the dialog. The function `openUrlInDialog()` is now deprecated. ## 1.8.3 - 2022-08-16 - Added `openFilePicker()` function to the `WidgetContext` interface to support file selection from within a widget. ## 1.8.2 - 2022-07-06 - Added `subtitle` property to the `WidgetResource` interface. ## 1.8.1 - 2022-06-17 - Added new section `analytics` to `WidgetManifestConfig` interface to allow definition of time-based events that can be raised by a widget. - Added `raiseEvent(...)` to the `instance` object of the `WidgetContent` interface, allowing widgets to raise an event. ## 1.7.11 - 2022-03-23 - Added `setWidgetHeaderVisibilty()` function to the `instance` object of the `WidgetContext` interface, allowing widgets to render in full height. ## 1.7.9 - 2022-01-20 - Added `userAccountCreated` date/time to the `WidgetContext` interface. ## 1.7.8 - 2022-01-18 ### Changed - Added `initiateWidgetDeletion()` function to the `WidgetContext` interface. ## 1.7.7 - 2022-01-14 ### Changed - Added `tenantId` property to the `WidgetContext` interface. ## 1.7.6 - 2021-11-04 ### Changed - Added `theme` property to the `WidgetContext` interface to give access to currently applied theme. ## 1.7.5 - 2021-10-26 ### Changed - Added `userSecurityGroups` and `userSharePointGroups` properties to the `WidgetContext` interface to inform widgets of SharePoint and security group memberships of the current user. ## 1.7.4 - 2021-10-20 ### Changed - Added `contentLanguages` property to the `WidgetContext` interface to inform widgets of the available content languages as configured in Ichicraft Boards. ## 1.7.3 - 2021-10-04 ### Changed - Added `manifestVersion` property to the `WidgetManifestConfig` interface to support multiple versions of the manifest. Current version is 2 which introduced this and the `externals` property. - Added `externals` property to the `WidgetManifestConfig` interface to support libraries that can be loaded separately from the widget bundle. This reduces widget bundle size and improves overal performance of Ichicraft Boards. ## 1.6.1 - 2021-02-18 ### Changed - Added `userEmail` property to the `WidgetContext` interface to provide current user's email address to widgets. ## 1.5.0 - 2021-02-16 ### Changed - Added `teamsSdk` property to the `WidgetContext` interface to allow interaction with Teams in case widget board is running in Teams client. Will be `undefined` if running in SharePoint. ## 1.4.0 - 2021-01-25 ### Changed - Added several properties to the `WidgetContext` interface to identify the context in which the widget is shown (e.g. Team Browser hosted) ## 1.3.0 - 2021-01-15 ### Changed - `registerCustomCommandBarItem()` is added to the `WidgetContext` interface as a function to call from within a widget instance to render an additional command bar item in the widget header. - `unregisterCustomCommandBarItem()` is added to the `WidgetContext` interface as a function to call from within a widget instance to remove a previously added command bar item from the widget header. ## 1.2.0 - 2021-01-15 ### Changed - `loadScript()` is added to the `WidgetContext` interface as a function to call from within a widget in case an external script needs to be loaded. This allows the widget board to load external javascript. ## 1.1.0 - 2021-01-11 ### Changed - `handleFatalError()` is added to the `WidgetContext` interface as a function to call from within a widget in case of an unhandled/unresolvable error. This allows the widget board to handle this situation gracefully. - **deps:** removed dependency ajv ## <= 1.0.5 - 2020-12-07 No changelog was maintained for the earlier versions.