@wordpress/widget-primitives 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# Widget Primitives
+
+<div class="callout callout-alert">
+This package is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+The host-agnostic toolkit for dashboard widgets: the contract types that define
+what a widget is, plus the runtime to discover the registered widget types and
+resolve their render modules.
+
+## Installation
+
+Install the module:
+
+```bash
+npm install @wordpress/widget-primitives --save
+```
+
+_This package assumes that your code will run in an **ES2015+** environment.
+If you're using an environment that has limited or no support for such
+language features and APIs, you should include [the polyfill shipped in
+`@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill)
+in your code._
+
+## Setup
+
+This package ships no stylesheets; there is nothing to enqueue or import.
+
+The contract types, `<WidgetRender>`, and `useWidgetTypes()` work in any
+React application. The host fetches the widget-module records however it
+wants and passes them in; `useWidgetTypes( records )` imports each record's
+metadata module and returns the resolved `WidgetType[]`.
+
+On a WordPress site the records come from the `/wp/v2/widget-modules` REST
+endpoint, exposed while the `gutenberg-dashboard-widgets` experiment is
+enabled. The dashboard reads it through a `@wordpress/core-data` entity and
+passes the records to the hook.
+
+With no records, or an empty list, `useWidgetTypes()` returns an empty list.
+
+## Public API
+
+-   `<WidgetRender>`: canonical entry point for any host that mounts a widget.
+    Resolves the widget's render module via a host-provided `resolveWidgetModule`
+    and mounts the resulting component with the standard `attributes` plus
+    `setAttributes` render contract. Suspense, error handling, and chrome are
+    host concerns.
+-   `useWidgetTypes( records )` → `[ widgetTypes, isResolvingWidgetTypes ]`:
+    takes host-supplied records (`WidgetModuleRecord[]`, or `null` while
+    loading), imports each record's metadata, and returns the resolved
+    `WidgetType[]` plus a flag that is true while they are still resolving.
+-   Contract types: `WidgetType`, `WidgetName`, `WidgetIcon`,
+    `WidgetRenderProps`, `ResolveWidgetModule`, `WidgetModuleRecord`.
+    `WidgetIcon` is a rendered SVG element; hosts pass it to their icon
+    primitive as is.
+
+## Architecture
+
+For how the full pipeline fits together (authoring, build, server registry, and
+hosts), see the
+[dashboard widget system architecture document](https://github.com/WordPress/gutenberg/blob/HEAD/docs/explanations/architecture/dashboard-widgets.md).
+
+## Contributing to this package
+
+This is an individual package that's part of the Gutenberg project.
+The project is organized as a monorepo. It's made up of multiple
+self-contained software packages, each with a specific purpose. The
+packages in this monorepo are published to [npm](https://www.npmjs.com/)
+and used by [WordPress](https://make.wordpress.org/core/) as well as
+other software projects.
+
+To find out more about contributing to this package or Gutenberg as a
+whole, please read the project's main
+[contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
+
+<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

package/build/components/widget-render/index.cjs

@@ -0,0 +1,31 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/widget-primitives/src/components/widget-render/index.ts
+var widget_render_exports = {};
+__export(widget_render_exports, {
+  WidgetRender: () => import_widget_render.WidgetRender
+});
+module.exports = __toCommonJS(widget_render_exports);
+var import_widget_render = require("./widget-render.cjs");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WidgetRender
+});
+//# sourceMappingURL=index.cjs.map

package/build/components/widget-render/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/components/widget-render/index.ts"],
+  "sourcesContent": ["export { WidgetRender } from './widget-render';\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,2BAA6B;",
+  "names": []
+}

package/build/components/widget-render/widget-render.cjs

@@ -0,0 +1,50 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/widget-primitives/src/components/widget-render/widget-render.tsx
+var widget_render_exports = {};
+__export(widget_render_exports, {
+  WidgetRender: () => WidgetRender
+});
+module.exports = __toCommonJS(widget_render_exports);
+var import_get_lazy_widget_component = require("../../tools/get-lazy-widget-component/index.cjs");
+var import_jsx_runtime = require("react/jsx-runtime");
+function WidgetRender({
+  widgetType,
+  attributes,
+  setAttributes,
+  resolveWidgetModule
+}) {
+  const WidgetComponent = (0, import_get_lazy_widget_component.getLazyWidgetComponent)(
+    widgetType.renderModule,
+    resolveWidgetModule
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    WidgetComponent,
+    {
+      attributes,
+      setAttributes
+    }
+  ) });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WidgetRender
+});
+//# sourceMappingURL=widget-render.cjs.map

package/build/components/widget-render/widget-render.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/components/widget-render/widget-render.tsx"],
+  "sourcesContent": ["/**\n * External dependencies\n */\n\n/**\n * Internal dependencies\n */\nimport { getLazyWidgetComponent } from '../../tools/get-lazy-widget-component';\nimport type { ResolveWidgetModule, WidgetType } from '../../types';\n\ninterface WidgetRenderProps< Item = unknown > {\n\twidgetType: WidgetType< Item >;\n\tattributes?: Item;\n\tsetAttributes?: ( next: Partial< Item > ) => void;\n\tresolveWidgetModule: ResolveWidgetModule;\n}\n\n/*\n * Resolves a widget type's `renderModule` via `resolveWidgetModule` and\n * mounts the resulting component with the `attributes`/`setAttributes`\n * render contract.\n */\nexport function WidgetRender< Item = unknown >( {\n\twidgetType,\n\tattributes,\n\tsetAttributes,\n\tresolveWidgetModule,\n}: WidgetRenderProps< Item > ) {\n\tconst WidgetComponent = getLazyWidgetComponent(\n\t\twidgetType.renderModule,\n\t\tresolveWidgetModule\n\t);\n\n\treturn (\n\t\t<>\n\t\t\t{ /* Cached `lazy()` keyed by renderModule; identity is stable across renders. */ }\n\t\t\t{ /* eslint-disable-next-line react-hooks/static-components */ }\n\t\t\t<WidgetComponent\n\t\t\t\tattributes={ attributes }\n\t\t\t\tsetAttributes={ setAttributes }\n\t\t\t/>\n\t\t</>\n\t);\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,uCAAuC;AA2BrC;AAZK,SAAS,aAAgC;AAAA,EAC/C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACD,GAA+B;AAC9B,QAAM,sBAAkB;AAAA,IACvB,WAAW;AAAA,IACX;AAAA,EACD;AAEA,SACC,2EAGC;AAAA,IAAC;AAAA;AAAA,MACA;AAAA,MACA;AAAA;AAAA,EACD,GACD;AAEF;",
+  "names": []
+}

package/build/hooks/index.cjs

@@ -0,0 +1,31 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/widget-primitives/src/hooks/index.ts
+var hooks_exports = {};
+__export(hooks_exports, {
+  useWidgetTypes: () => import_use_widget_types.useWidgetTypes
+});
+module.exports = __toCommonJS(hooks_exports);
+var import_use_widget_types = require("./use-widget-types.cjs");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useWidgetTypes
+});
+//# sourceMappingURL=index.cjs.map

package/build/hooks/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/hooks/index.ts"],
+  "sourcesContent": ["export { useWidgetTypes } from './use-widget-types';\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,8BAA+B;",
+  "names": []
+}

package/build/hooks/use-widget-types.cjs

@@ -0,0 +1,84 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/widget-primitives/src/hooks/use-widget-types.ts
+var use_widget_types_exports = {};
+__export(use_widget_types_exports, {
+  useWidgetTypes: () => useWidgetTypes
+});
+module.exports = __toCommonJS(use_widget_types_exports);
+var import_element = require("@wordpress/element");
+function useWidgetTypes(records) {
+  const [widgetTypes, setWidgetTypes] = (0, import_element.useState)([]);
+  const [isResolvingWidgetTypes, setIsResolvingWidgetTypes] = (0, import_element.useState)(true);
+  (0, import_element.useEffect)(() => {
+    if (records === null || records === void 0) {
+      setIsResolvingWidgetTypes(true);
+      return;
+    }
+    if (records.length === 0) {
+      setWidgetTypes([]);
+      setIsResolvingWidgetTypes(false);
+      return;
+    }
+    let cancelled = false;
+    setIsResolvingWidgetTypes(true);
+    Promise.all(
+      records.map(async (record) => {
+        if (!record.widget_module) {
+          return null;
+        }
+        try {
+          const module2 = await import(
+            /* webpackIgnore: true */
+            record.widget_module
+          );
+          if (!module2?.default) {
+            return null;
+          }
+          return {
+            ...module2.default,
+            name: record.name,
+            renderModule: record.render_module ?? "",
+            ...record.presentation ? { presentation: record.presentation } : {}
+          };
+        } catch {
+          return null;
+        }
+      })
+    ).then((results) => {
+      if (cancelled) {
+        return;
+      }
+      setWidgetTypes(
+        results.filter((t) => t !== null)
+      );
+      setIsResolvingWidgetTypes(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [records]);
+  return [widgetTypes, isResolvingWidgetTypes];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useWidgetTypes
+});
+//# sourceMappingURL=use-widget-types.cjs.map

package/build/hooks/use-widget-types.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/hooks/use-widget-types.ts"],
+  "sourcesContent": ["/**\n * WordPress dependencies\n */\nimport { useEffect, useState } from '@wordpress/element';\n\n/**\n * Internal dependencies\n */\nimport type { WidgetModuleRecord, WidgetName, WidgetType } from '../types';\n\n/* `true` while records or their metadata imports are still resolving; hosts\n   must not treat a widget instance as missing until it is `false`. */\ntype UseWidgetTypesResult = readonly [ WidgetType[], boolean ];\n\n/**\n * Resolves widget types from host-supplied records.\n *\n * For each record it dynamically imports `widget_module` and merges the\n * module's default export with the runtime fields (`name`, `renderModule`).\n * Pass `null`/`undefined` while records are still loading.\n *\n * @param records Host-supplied records, or `null`/`undefined` while loading.\n */\nexport function useWidgetTypes(\n\trecords: WidgetModuleRecord[] | null | undefined\n): UseWidgetTypesResult {\n\tconst [ widgetTypes, setWidgetTypes ] = useState< WidgetType[] >( [] );\n\tconst [ isResolvingWidgetTypes, setIsResolvingWidgetTypes ] =\n\t\tuseState( true );\n\n\tuseEffect( () => {\n\t\tif ( records === null || records === undefined ) {\n\t\t\tsetIsResolvingWidgetTypes( true );\n\t\t\treturn;\n\t\t}\n\n\t\tif ( records.length === 0 ) {\n\t\t\tsetWidgetTypes( [] );\n\t\t\tsetIsResolvingWidgetTypes( false );\n\t\t\treturn;\n\t\t}\n\n\t\tlet cancelled = false;\n\t\tsetIsResolvingWidgetTypes( true );\n\n\t\tPromise.all(\n\t\t\trecords.map( async ( record ) => {\n\t\t\t\tif ( ! record.widget_module ) {\n\t\t\t\t\treturn null;\n\t\t\t\t}\n\n\t\t\t\ttry {\n\t\t\t\t\tconst module = await import(\n\t\t\t\t\t\t/* webpackIgnore: true */ record.widget_module\n\t\t\t\t\t);\n\n\t\t\t\t\tif ( ! module?.default ) {\n\t\t\t\t\t\treturn null;\n\t\t\t\t\t}\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\t...( module.default as Partial< WidgetType > ),\n\t\t\t\t\t\tname: record.name as WidgetName,\n\t\t\t\t\t\trenderModule: record.render_module ?? '',\n\t\t\t\t\t\t...( record.presentation\n\t\t\t\t\t\t\t? { presentation: record.presentation }\n\t\t\t\t\t\t\t: {} ),\n\t\t\t\t\t} as WidgetType;\n\t\t\t\t} catch {\n\t\t\t\t\treturn null;\n\t\t\t\t}\n\t\t\t} )\n\t\t).then( ( results ) => {\n\t\t\tif ( cancelled ) {\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tsetWidgetTypes(\n\t\t\t\tresults.filter( ( t ): t is WidgetType => t !== null )\n\t\t\t);\n\t\t\tsetIsResolvingWidgetTypes( false );\n\t\t} );\n\n\t\treturn () => {\n\t\t\tcancelled = true;\n\t\t};\n\t}, [ records ] );\n\n\treturn [ widgetTypes, isResolvingWidgetTypes ];\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,qBAAoC;AAoB7B,SAAS,eACf,SACuB;AACvB,QAAM,CAAE,aAAa,cAAe,QAAI,yBAA0B,CAAC,CAAE;AACrE,QAAM,CAAE,wBAAwB,yBAA0B,QACzD,yBAAU,IAAK;AAEhB,gCAAW,MAAM;AAChB,QAAK,YAAY,QAAQ,YAAY,QAAY;AAChD,gCAA2B,IAAK;AAChC;AAAA,IACD;AAEA,QAAK,QAAQ,WAAW,GAAI;AAC3B,qBAAgB,CAAC,CAAE;AACnB,gCAA2B,KAAM;AACjC;AAAA,IACD;AAEA,QAAI,YAAY;AAChB,8BAA2B,IAAK;AAEhC,YAAQ;AAAA,MACP,QAAQ,IAAK,OAAQ,WAAY;AAChC,YAAK,CAAE,OAAO,eAAgB;AAC7B,iBAAO;AAAA,QACR;AAEA,YAAI;AACH,gBAAMA,UAAS,MAAM;AAAA;AAAA,YACM,OAAO;AAAA;AAGlC,cAAK,CAAEA,SAAQ,SAAU;AACxB,mBAAO;AAAA,UACR;AAEA,iBAAO;AAAA,YACN,GAAKA,QAAO;AAAA,YACZ,MAAM,OAAO;AAAA,YACb,cAAc,OAAO,iBAAiB;AAAA,YACtC,GAAK,OAAO,eACT,EAAE,cAAc,OAAO,aAAa,IACpC,CAAC;AAAA,UACL;AAAA,QACD,QAAQ;AACP,iBAAO;AAAA,QACR;AAAA,MACD,CAAE;AAAA,IACH,EAAE,KAAM,CAAE,YAAa;AACtB,UAAK,WAAY;AAChB;AAAA,MACD;AAEA;AAAA,QACC,QAAQ,OAAQ,CAAE,MAAwB,MAAM,IAAK;AAAA,MACtD;AACA,gCAA2B,KAAM;AAAA,IAClC,CAAE;AAEF,WAAO,MAAM;AACZ,kBAAY;AAAA,IACb;AAAA,EACD,GAAG,CAAE,OAAQ,CAAE;AAEf,SAAO,CAAE,aAAa,sBAAuB;AAC9C;",
+  "names": ["module"]
+}

package/build/index.cjs

@@ -0,0 +1,34 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/widget-primitives/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  WidgetRender: () => import_widget_render.WidgetRender,
+  useWidgetTypes: () => import_hooks.useWidgetTypes
+});
+module.exports = __toCommonJS(index_exports);
+var import_widget_render = require("./components/widget-render/index.cjs");
+var import_hooks = require("./hooks/index.cjs");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WidgetRender,
+  useWidgetTypes
+});
+//# sourceMappingURL=index.cjs.map

package/build/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["/**\n * Components\n */\nexport { WidgetRender } from './components/widget-render';\n\n/**\n * Hooks\n */\nexport { useWidgetTypes } from './hooks';\n\n/**\n * Types\n */\nexport type {\n\tWidgetName,\n\tWidgetIcon,\n\tWidgetType,\n\tWidgetRenderProps,\n\tResolveWidgetModule,\n\tWidgetModuleRecord,\n} from './types';\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,2BAA6B;AAK7B,mBAA+B;",
+  "names": []
+}

package/build/tools/get-lazy-widget-component/get-lazy-widget-component.cjs

@@ -0,0 +1,50 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/widget-primitives/src/tools/get-lazy-widget-component/get-lazy-widget-component.ts
+var get_lazy_widget_component_exports = {};
+__export(get_lazy_widget_component_exports, {
+  getLazyWidgetComponent: () => getLazyWidgetComponent
+});
+module.exports = __toCommonJS(get_lazy_widget_component_exports);
+var import_element = require("@wordpress/element");
+function isValidWidgetModule(module2) {
+  return typeof module2 === "object" && module2 !== null && "default" in module2 && typeof module2.default === "function";
+}
+var componentCache = /* @__PURE__ */ new Map();
+function getLazyWidgetComponent(renderModule, resolveWidgetModule) {
+  const cached = componentCache.get(renderModule);
+  if (cached) {
+    return cached;
+  }
+  const lazyComponent = (0, import_element.lazy)(async () => {
+    const module2 = await resolveWidgetModule(renderModule);
+    if (!isValidWidgetModule(module2)) {
+      throw new Error(`Invalid widget module: ${renderModule}`);
+    }
+    return module2;
+  });
+  componentCache.set(renderModule, lazyComponent);
+  return lazyComponent;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getLazyWidgetComponent
+});
+//# sourceMappingURL=get-lazy-widget-component.cjs.map

package/build/tools/get-lazy-widget-component/get-lazy-widget-component.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/tools/get-lazy-widget-component/get-lazy-widget-component.ts"],
+  "sourcesContent": ["/**\n * External dependencies\n */\nimport type { ComponentType } from 'react';\n\n/**\n * WordPress dependencies\n */\nimport { lazy } from '@wordpress/element';\n\n/**\n * Internal dependencies\n */\nimport type {\n\tResolveWidgetModule,\n\tWidgetModule,\n\tWidgetRenderProps,\n} from '../../types';\n\ntype LazyWidgetComponent = ComponentType< WidgetRenderProps< unknown > >;\n\nfunction isValidWidgetModule( module: unknown ): module is WidgetModule {\n\treturn (\n\t\ttypeof module === 'object' &&\n\t\tmodule !== null &&\n\t\t'default' in module &&\n\t\ttypeof ( module as { default: unknown } ).default === 'function'\n\t);\n}\n\n/*\n * Cache keyed by `renderModule`. The lazy component must keep a stable\n * identity across renders; rebuilding it inline (e.g. via `useMemo`) resets\n * the Suspense boundary and the resolved module.\n */\nconst componentCache = new Map< string, LazyWidgetComponent >();\n\n/*\n * Resolve a widget render module to a `lazy()` React component, cached by\n * `renderModule` id so repeated calls return the same instance.\n */\nexport function getLazyWidgetComponent(\n\trenderModule: string,\n\tresolveWidgetModule: ResolveWidgetModule\n): LazyWidgetComponent {\n\tconst cached = componentCache.get( renderModule );\n\tif ( cached ) {\n\t\treturn cached;\n\t}\n\n\tconst lazyComponent = lazy< LazyWidgetComponent >( async () => {\n\t\tconst module: unknown = await resolveWidgetModule( renderModule );\n\t\tif ( ! isValidWidgetModule( module ) ) {\n\t\t\tthrow new Error( `Invalid widget module: ${ renderModule }` );\n\t\t}\n\n\t\treturn module;\n\t} );\n\n\tcomponentCache.set( renderModule, lazyComponent );\n\treturn lazyComponent;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,qBAAqB;AAarB,SAAS,oBAAqBA,SAA0C;AACvE,SACC,OAAOA,YAAW,YAClBA,YAAW,QACX,aAAaA,WACb,OAASA,QAAiC,YAAY;AAExD;AAOA,IAAM,iBAAiB,oBAAI,IAAmC;AAMvD,SAAS,uBACf,cACA,qBACsB;AACtB,QAAM,SAAS,eAAe,IAAK,YAAa;AAChD,MAAK,QAAS;AACb,WAAO;AAAA,EACR;AAEA,QAAM,oBAAgB,qBAA6B,YAAY;AAC9D,UAAMA,UAAkB,MAAM,oBAAqB,YAAa;AAChE,QAAK,CAAE,oBAAqBA,OAAO,GAAI;AACtC,YAAM,IAAI,MAAO,0BAA2B,YAAa,EAAG;AAAA,IAC7D;AAEA,WAAOA;AAAA,EACR,CAAE;AAEF,iBAAe,IAAK,cAAc,aAAc;AAChD,SAAO;AACR;",
+  "names": ["module"]
+}

package/build/tools/get-lazy-widget-component/index.cjs

@@ -0,0 +1,31 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/widget-primitives/src/tools/get-lazy-widget-component/index.ts
+var get_lazy_widget_component_exports = {};
+__export(get_lazy_widget_component_exports, {
+  getLazyWidgetComponent: () => import_get_lazy_widget_component.getLazyWidgetComponent
+});
+module.exports = __toCommonJS(get_lazy_widget_component_exports);
+var import_get_lazy_widget_component = require("./get-lazy-widget-component.cjs");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getLazyWidgetComponent
+});
+//# sourceMappingURL=index.cjs.map

package/build/tools/get-lazy-widget-component/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/tools/get-lazy-widget-component/index.ts"],
+  "sourcesContent": ["export { getLazyWidgetComponent } from './get-lazy-widget-component';\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,uCAAuC;",
+  "names": []
+}

package/build/types.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/widget-primitives/src/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);
+//# sourceMappingURL=types.cjs.map

package/build/types.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/types.ts"],
+  "sourcesContent": ["/**\n * Widget type definitions.\n *\n * Canonical home for widget identity types consumed by the registry and\n * hosts that render widgets.\n *\n * Each type is generic over the widget's attribute object (`Item`), so a\n * widget binds its attribute shape once and gets typed `attributes`,\n * `example`, and `setAttributes`.\n */\n\n/**\n * External dependencies\n */\nimport type { ComponentProps, ComponentType, ReactElement } from 'react';\nimport type { Field } from '@wordpress/dataviews';\n\n/**\n * Widget type identifier, structured as `<widget-namespace>/<widget-name>`.\n * Both segments are lowercase, kebab-case.\n */\nexport type WidgetName = `${ string }/${ string }`;\n\n/**\n * Icon for a widget type: a rendered SVG element, typically one from\n * `@wordpress/icons`.\n */\nexport type WidgetIcon = ReactElement< ComponentProps< 'svg' > >;\n\n/**\n * Literal contents of a widget's `widget.json` metadata file.\n *\n * Captures the *authoring* shape only; module entry points and style\n * assets are discovered by convention from the widget directory, not\n * declared here.\n */\nexport interface WidgetTypeMetadata< Item = unknown > {\n\t/**\n\t * Version of the Widget API used by the widget.\n\t */\n\tapiVersion: number;\n\n\t/**\n\t * Stable type identifier.\n\t */\n\tname: WidgetName;\n\n\t/**\n\t * Display title; hosts surface it in pickers and chrome.\n\t */\n\ttitle: string;\n\n\t/**\n\t * Short description; hosts surface it in pickers and help panels.\n\t */\n\tdescription?: string;\n\n\t/**\n\t * Visual identifier for the widget type; hosts decide where, and\n\t * whether, to render it.\n\t */\n\ticon?: WidgetIcon;\n\n\t/**\n\t * Grouping category. Core provides `dashboard`; plugins and themes may\n\t * register custom categories.\n\t */\n\tcategory?: string;\n\n\t/**\n\t * Authoring intent about how the widget renders. Not a user-editable\n\t * attribute.\n\t *\n\t * - `'framed'` (default when absent): the widget renders its\n\t *   content only.\n\t * - `'content-bleed'`: the host's chrome stays visible while the\n\t *   content fills the content area edge-to-edge, with no padding.\n\t * - `'full-bleed'`: the widget renders edge-to-edge with no\n\t *   surrounding chrome.\n\t */\n\tpresentation?: 'framed' | 'content-bleed' | 'full-bleed';\n\n\t/**\n\t * Search aliases hosts use to match the widget in their pickers.\n\t */\n\tkeywords?: string[];\n\n\t/**\n\t * Widget version, used for asset cache invalidation.\n\t */\n\tversion?: string;\n\n\t/**\n\t * Gettext text domain for translations.\n\t */\n\ttextdomain?: string;\n\n\t/**\n\t * Experiment gate; boolean `true`, or a specific experiment name.\n\t */\n\t__experimental?: string | boolean;\n\n\t/**\n\t * Declarative attribute schema, bound to the widget's attribute\n\t * object via `Item`. Hosts render forms straight from this list\n\t * via `DataForm`, with no per-widget form wiring.\n\t */\n\tattributes?: Field< Item >[];\n\n\t/**\n\t * Structured example data hosts use for previews, and the default\n\t * attributes applied when a new instance is created without initial\n\t * attributes.\n\t */\n\texample?: {\n\t\tattributes?: Partial< Item >;\n\t};\n}\n\n/**\n * Runtime widget type consumed by hosts.\n *\n * Extends `WidgetTypeMetadata` with runtime-only fields, notably\n * `renderModule`. Hosts supply the raw records in snake_case\n * (`WidgetModuleRecord`); `useWidgetTypes` is the single boundary that\n * resolves them into this camelCase shape.\n */\nexport interface WidgetType< Item = unknown >\n\textends WidgetTypeMetadata< Item > {\n\t/**\n\t * Script-module identifier resolved to a React component at render\n\t * time, produced from the conventional `render.*` entry point.\n\t */\n\trenderModule: string;\n}\n\n/**\n * Props passed to a widget's render component by the host, bound over\n * `Item` so `attributes` and `setAttributes` are typed against the\n * widget's attribute object.\n */\nexport interface WidgetRenderProps< Item = unknown > {\n\t/**\n\t * User-configured attributes for this widget instance.\n\t */\n\tattributes: Item;\n\n\t/**\n\t * Updates the attributes of this instance. Optional because some\n\t * hosts render widgets in read-only contexts.\n\t */\n\tsetAttributes?: ( next: Partial< Item > ) => void;\n}\n\n/**\n * Widget render module shape returned by the module resolver.\n */\nexport interface WidgetModule {\n\tdefault: ComponentType< WidgetRenderProps< unknown > >;\n}\n\n/**\n * Resolver function: maps a `WidgetType.renderModule` id to a React\n * component. Override for tests, Storybook, or to load from a non-URL\n * source.\n */\nexport type ResolveWidgetModule = (\n\tmoduleId: string\n) => Promise< WidgetModule >;\n\n/**\n * Per-widget record a host feeds to `useWidgetTypes`, in snake_case wire\n * format. The host fetches these however it likes; only the field shape is\n * part of the contract.\n */\nexport interface WidgetModuleRecord {\n\t/**\n\t * Stable widget type identifier.\n\t */\n\tname: string;\n\n\t/**\n\t * Script-module id resolved to the render component at render time.\n\t */\n\trender_module?: string | null;\n\n\t/**\n\t * Script-module id dynamically imported for the widget's live metadata.\n\t */\n\twidget_module?: string | null;\n\n\t/**\n\t * Authoring presentation hint; overrides the metadata module's value.\n\t */\n\tpresentation?: WidgetTypeMetadata[ 'presentation' ] | null;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;",
+  "names": []
+}

package/build-module/components/widget-render/index.mjs

@@ -0,0 +1,6 @@
+// packages/widget-primitives/src/components/widget-render/index.ts
+import { WidgetRender } from "./widget-render.mjs";
+export {
+  WidgetRender
+};
+//# sourceMappingURL=index.mjs.map

package/build-module/components/widget-render/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/components/widget-render/index.ts"],
+  "sourcesContent": ["export { WidgetRender } from './widget-render';\n"],
+  "mappings": ";AAAA,SAAS,oBAAoB;",
+  "names": []
+}

package/build-module/components/widget-render/widget-render.mjs

@@ -0,0 +1,25 @@
+// packages/widget-primitives/src/components/widget-render/widget-render.tsx
+import { getLazyWidgetComponent } from "../../tools/get-lazy-widget-component/index.mjs";
+import { Fragment, jsx } from "react/jsx-runtime";
+function WidgetRender({
+  widgetType,
+  attributes,
+  setAttributes,
+  resolveWidgetModule
+}) {
+  const WidgetComponent = getLazyWidgetComponent(
+    widgetType.renderModule,
+    resolveWidgetModule
+  );
+  return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(
+    WidgetComponent,
+    {
+      attributes,
+      setAttributes
+    }
+  ) });
+}
+export {
+  WidgetRender
+};
+//# sourceMappingURL=widget-render.mjs.map

package/build-module/components/widget-render/widget-render.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/components/widget-render/widget-render.tsx"],
+  "sourcesContent": ["/**\n * External dependencies\n */\n\n/**\n * Internal dependencies\n */\nimport { getLazyWidgetComponent } from '../../tools/get-lazy-widget-component';\nimport type { ResolveWidgetModule, WidgetType } from '../../types';\n\ninterface WidgetRenderProps< Item = unknown > {\n\twidgetType: WidgetType< Item >;\n\tattributes?: Item;\n\tsetAttributes?: ( next: Partial< Item > ) => void;\n\tresolveWidgetModule: ResolveWidgetModule;\n}\n\n/*\n * Resolves a widget type's `renderModule` via `resolveWidgetModule` and\n * mounts the resulting component with the `attributes`/`setAttributes`\n * render contract.\n */\nexport function WidgetRender< Item = unknown >( {\n\twidgetType,\n\tattributes,\n\tsetAttributes,\n\tresolveWidgetModule,\n}: WidgetRenderProps< Item > ) {\n\tconst WidgetComponent = getLazyWidgetComponent(\n\t\twidgetType.renderModule,\n\t\tresolveWidgetModule\n\t);\n\n\treturn (\n\t\t<>\n\t\t\t{ /* Cached `lazy()` keyed by renderModule; identity is stable across renders. */ }\n\t\t\t{ /* eslint-disable-next-line react-hooks/static-components */ }\n\t\t\t<WidgetComponent\n\t\t\t\tattributes={ attributes }\n\t\t\t\tsetAttributes={ setAttributes }\n\t\t\t/>\n\t\t</>\n\t);\n}\n"],
+  "mappings": ";AAOA,SAAS,8BAA8B;AA2BrC,mBAGC,WAHD;AAZK,SAAS,aAAgC;AAAA,EAC/C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACD,GAA+B;AAC9B,QAAM,kBAAkB;AAAA,IACvB,WAAW;AAAA,IACX;AAAA,EACD;AAEA,SACC,gCAGC;AAAA,IAAC;AAAA;AAAA,MACA;AAAA,MACA;AAAA;AAAA,EACD,GACD;AAEF;",
+  "names": []
+}

package/build-module/hooks/index.mjs

@@ -0,0 +1,6 @@
+// packages/widget-primitives/src/hooks/index.ts
+import { useWidgetTypes } from "./use-widget-types.mjs";
+export {
+  useWidgetTypes
+};
+//# sourceMappingURL=index.mjs.map

package/build-module/hooks/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/hooks/index.ts"],
+  "sourcesContent": ["export { useWidgetTypes } from './use-widget-types';\n"],
+  "mappings": ";AAAA,SAAS,sBAAsB;",
+  "names": []
+}

package/build-module/hooks/use-widget-types.mjs

@@ -0,0 +1,59 @@
+// packages/widget-primitives/src/hooks/use-widget-types.ts
+import { useEffect, useState } from "@wordpress/element";
+function useWidgetTypes(records) {
+  const [widgetTypes, setWidgetTypes] = useState([]);
+  const [isResolvingWidgetTypes, setIsResolvingWidgetTypes] = useState(true);
+  useEffect(() => {
+    if (records === null || records === void 0) {
+      setIsResolvingWidgetTypes(true);
+      return;
+    }
+    if (records.length === 0) {
+      setWidgetTypes([]);
+      setIsResolvingWidgetTypes(false);
+      return;
+    }
+    let cancelled = false;
+    setIsResolvingWidgetTypes(true);
+    Promise.all(
+      records.map(async (record) => {
+        if (!record.widget_module) {
+          return null;
+        }
+        try {
+          const module = await import(
+            /* webpackIgnore: true */
+            record.widget_module
+          );
+          if (!module?.default) {
+            return null;
+          }
+          return {
+            ...module.default,
+            name: record.name,
+            renderModule: record.render_module ?? "",
+            ...record.presentation ? { presentation: record.presentation } : {}
+          };
+        } catch {
+          return null;
+        }
+      })
+    ).then((results) => {
+      if (cancelled) {
+        return;
+      }
+      setWidgetTypes(
+        results.filter((t) => t !== null)
+      );
+      setIsResolvingWidgetTypes(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [records]);
+  return [widgetTypes, isResolvingWidgetTypes];
+}
+export {
+  useWidgetTypes
+};
+//# sourceMappingURL=use-widget-types.mjs.map