Add Widgets API documentation and enable unstableWidgetsApi feature flag

docusaurus/docs/cms/configurations/features.md

@@ -4,10 +4,10 @@ sidebar_label: Features
 description: Enable experimental Strapi features
 displayed_sidebar: cmsSidebar
 tags:
-- additional configuration
-- configuration
-- features configuration
-- future flag
+  - additional configuration
+  - configuration
+  - features configuration
+  - future flag
 ---
 
 # Features configuration
@@ -31,17 +31,17 @@ To enable a future flag:
 
 1. (_optional_) If the server is running, stop it with `Ctrl-C`.
 2. Open the `config/features.js|ts` file or create it if the file does not exist yet. The file will export a `future` object with all the future flags to enable.
-3. To enable a future flag, add its property name (see [full list](#available-future-flags)) to the `future` object and ensure the property's value is set to `true`. The following example shows how to enable the `contentReleasesScheduling` future flag:
+3. To enable a future flag, add its property name (see [full list](#available-future-flags)) to the `future` object and ensure the property's value is set to `true`. The following example shows how to enable the `unstableWidgetsApi` future flag:
 
   <Tabs groupId='js-ts'>
 
   <TabItem value="js" label="JavaScript">
 
-  ```ts title="/config/features.ts"
-  module.export = ({ env }) => ({
+  ```js title="/config/features.js"
+  module.exports = ({ env }) => ({
     future: {
-      // You could also simply write: contentReleases: true
-      contentReleasesScheduling: env.bool('STRAPI_FUTURE_CONTENT_RELEASES_SCHEDULING', false),
+      // You could also simply write: unstableWidgetsApi: true
+      unstableWidgetsApi: env.bool('STRAPI_FUTURE_UNSTABLE_WIDGETS_API', false),
     },
   })
 
@@ -50,10 +50,10 @@ To enable a future flag:
   This example assumes that you have an `.env` environment file at the root of your application and that the file includes the following line:
 
   ```json title=".env"
-  STRAPI_FUTURE_CONTENT_RELEASES_SCHEDULING=true
+  STRAPI_FUTURE_UNSTABLE_WIDGETS_API=true
   ```
 
-  If your environment file does not include this value, the `contentReleasesScheduling` future flag property value  will default to `false` and the experimental feature will not be enabled.
+  If your environment file does not include this value, the `unstableWidgetsApi` future flag property value will default to `false` and the experimental feature will not be enabled.
 
   </TabItem>
 
@@ -62,19 +62,19 @@ To enable a future flag:
   ```ts title="/config/features.ts"
   export default {
     future: {
-      // You could also simply write: contentReleases: true
-      contentReleasesScheduling: env.bool('STRAPI_FUTURE_CONTENT_RELEASES_SCHEDULING', false),
+      // You could also simply write: unstableWidgetsApi: true
+      unstableWidgetsApi: env.bool('STRAPI_FUTURE_UNSTABLE_WIDGETS_API', false),
     },
   };
   ```
 
   This example assumes that you have an `.env` environment file at the root of your application and that the file includes the following line:
 
   ```json title=".env"
-  STRAPI_FUTURE_CONTENT_RELEASES_SCHEDULING=true
+  STRAPI_FUTURE_UNSTABLE_WIDGETS_API=true
   ```
 
-  If your environment file does not include this value, the `contentReleases` future flag property value will default to `false` and the experimental feature will not be enabled.
+  If your environment file does not include this value, the `unstableWidgetsApi` future flag property value will default to `false` and the experimental feature will not be enabled.
 
   </TabItem>
   </Tabs>
@@ -107,10 +107,8 @@ Developers can use the following APIs to interact with future flags:
 
 ## Available future flags
 
-There are currently no available future flags. This section will be updated once new experimental features are available for testing.
-
-<!-- The following future flags are currently available and can be used in the `future` object of the `config/features` configuration file:
+The following future flags are currently available and can be used in the `future` object of the `config/features` configuration file:
 
 | Property name     | Related feature                              | Suggested environment variable name       |
 | ----------------- | -------------------------------------------- | ----------------------------------------- |
-| `contentReleasesScheduling` | [Releases Scheduling](/cms/features/releases#usage) | `STRAPI_FUTURE_CONTENT_RELEASES_SCHEDULING` | -->
+| `unstableWidgetsApi` | Experimental Widgets API | `STRAPI_FUTURE_UNSTABLE_WIDGETS_API` |

docusaurus/docs/cms/plugins-development/widgets-api.md

@@ -0,0 +1,124 @@
+---
+title: Widgets API
+description: Learn how to use the Widgets API to create and manage widgets in the Strapi admin panel.
+displayed_sidebar: cmsSidebar
+tags:
+  - widgets
+  - admin panel
+  - plugins development
+---
+
+# Widgets API
+
+The Widgets API allows you to create and manage widgets in the Strapi admin panel. Widgets are customizable components that can be added to various parts of the admin interface to display information or provide additional functionality.
+
+## Creating a Widget
+
+To create a widget, you need to use the `Widgets` class from the `@strapi/admin` package. Here's an example of how to create a widget:
+
+```javascript
+import { Widgets } from '@strapi/admin';
+
+const widgets = new Widgets();
+
+widgets.register({
+  id: 'my-widget',
+  pluginId: 'my-plugin',
+  icon: MyWidgetIcon,
+  title: {
+    id: 'my-widget.title',
+    defaultMessage: 'My Widget',
+  },
+  component: () => import('./components/MyWidget'),
+});
+```
+
+The `register` method accepts an object with the following properties:
+
+- `id` (string): A unique identifier for the widget.
+- `pluginId` (string, optional): The ID of the plugin if the widget belongs to a specific plugin.
+- `icon` (React.ComponentType): The icon component to display for the widget.
+- `title` (MessageDescriptor): The title of the widget, using React Intl format.
+- `component` (function): A function that returns a Promise resolving to the widget's React component.
+- `permissions` (array, optional): An array of permission objects to control access to the widget.
+
+## Managing Widgets
+
+The `Widgets` class provides methods to manage widgets:
+
+### getAll()
+
+Retrieves all registered widgets:
+
+```javascript
+const allWidgets = widgets.getAll();
+```
+
+### register()
+
+Registers one or multiple widgets:
+
+```javascript
+// Register a single widget
+widgets.register({
+  id: 'widget1',
+  // ... other properties
+});
+
+// Register multiple widgets
+widgets.register([
+  {
+    id: 'widget1',
+    // ... other properties
+  },
+  {
+    id: 'widget2',
+    // ... other properties
+  },
+]);
+```
+
+## Widget UID
+
+Widgets are identified by a unique UID, which is automatically generated based on the `pluginId` and `id`:
+
+- For plugin widgets: `plugin::{pluginId}.{id}`
+- For global widgets: `global::{id}`
+
+## Best Practices
+
+1. Use meaningful and unique IDs for your widgets to avoid conflicts.
+2. Implement lazy loading for widget components to improve performance.
+3. Use the `permissions` property to control access to widgets based on user roles.
+4. Provide clear and concise titles for widgets to improve user experience.
+5. Use appropriate icons that represent the widget's functionality.
+
+## Example: Creating a Dashboard Widget
+
+Here's an example of how to create a dashboard widget that displays recent content:
+
+```javascript
+import { Widgets } from '@strapi/admin';
+import RecentContentIcon from './icons/RecentContent';
+
+const widgets = new Widgets();
+
+widgets.register({
+  id: 'recent-content',
+  icon: RecentContentIcon,
+  title: {
+    id: 'dashboard.widgets.recent-content.title',
+    defaultMessage: 'Recent Content',
+  },
+  component: () => import('./components/RecentContentWidget'),
+  permissions: [
+    { action: 'plugin::content-manager.explorer.read', subject: 'api::article.article' },
+  ],
+});
+```
+
+In this example, we create a widget that displays recent content. The widget is only accessible to users who have permission to read articles in the Content Manager.
+
+Remember to implement the `RecentContentWidget` component and define the necessary translations for the widget title.
+
+By using the Widgets API, you can create powerful and customizable widgets to enhance the Strapi admin panel experience for your users.