@wordpress/widget-primitives 0.1.0

package/build-module/hooks/use-widget-types.mjs.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": ";AAGA,SAAS,WAAW,gBAAgB;AAoB7B,SAAS,eACf,SACuB;AACvB,QAAM,CAAE,aAAa,cAAe,IAAI,SAA0B,CAAC,CAAE;AACrE,QAAM,CAAE,wBAAwB,yBAA0B,IACzD,SAAU,IAAK;AAEhB,YAAW,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,gBAAM,SAAS,MAAM;AAAA;AAAA,YACM,OAAO;AAAA;AAGlC,cAAK,CAAE,QAAQ,SAAU;AACxB,mBAAO;AAAA,UACR;AAEA,iBAAO;AAAA,YACN,GAAK,OAAO;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": []
+}

package/build-module/index.mjs

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

package/build-module/index.mjs.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": ";AAGA,SAAS,oBAAoB;AAK7B,SAAS,sBAAsB;",
+  "names": []
+}

package/build-module/tools/get-lazy-widget-component/get-lazy-widget-component.mjs

@@ -0,0 +1,25 @@
+// packages/widget-primitives/src/tools/get-lazy-widget-component/get-lazy-widget-component.ts
+import { lazy } from "@wordpress/element";
+function isValidWidgetModule(module) {
+  return typeof module === "object" && module !== null && "default" in module && typeof module.default === "function";
+}
+var componentCache = /* @__PURE__ */ new Map();
+function getLazyWidgetComponent(renderModule, resolveWidgetModule) {
+  const cached = componentCache.get(renderModule);
+  if (cached) {
+    return cached;
+  }
+  const lazyComponent = lazy(async () => {
+    const module = await resolveWidgetModule(renderModule);
+    if (!isValidWidgetModule(module)) {
+      throw new Error(`Invalid widget module: ${renderModule}`);
+    }
+    return module;
+  });
+  componentCache.set(renderModule, lazyComponent);
+  return lazyComponent;
+}
+export {
+  getLazyWidgetComponent
+};
+//# sourceMappingURL=get-lazy-widget-component.mjs.map

package/build-module/tools/get-lazy-widget-component/get-lazy-widget-component.mjs.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": ";AAQA,SAAS,YAAY;AAarB,SAAS,oBAAqB,QAA0C;AACvE,SACC,OAAO,WAAW,YAClB,WAAW,QACX,aAAa,UACb,OAAS,OAAiC,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,gBAAgB,KAA6B,YAAY;AAC9D,UAAM,SAAkB,MAAM,oBAAqB,YAAa;AAChE,QAAK,CAAE,oBAAqB,MAAO,GAAI;AACtC,YAAM,IAAI,MAAO,0BAA2B,YAAa,EAAG;AAAA,IAC7D;AAEA,WAAO;AAAA,EACR,CAAE;AAEF,iBAAe,IAAK,cAAc,aAAc;AAChD,SAAO;AACR;",
+  "names": []
+}

package/build-module/tools/get-lazy-widget-component/index.mjs

@@ -0,0 +1,6 @@
+// packages/widget-primitives/src/tools/get-lazy-widget-component/index.ts
+import { getLazyWidgetComponent } from "./get-lazy-widget-component.mjs";
+export {
+  getLazyWidgetComponent
+};
+//# sourceMappingURL=index.mjs.map

package/build-module/tools/get-lazy-widget-component/index.mjs.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,SAAS,8BAA8B;",
+  "names": []
+}

package/build-module/types.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=types.mjs.map

package/build-module/types.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/build-types/components/widget-render/index.d.ts

@@ -0,0 +1,2 @@
+export { WidgetRender } from './widget-render';
+//# sourceMappingURL=index.d.ts.map

package/build-types/components/widget-render/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/widget-render/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/build-types/components/widget-render/stories/index.story.d.ts

@@ -0,0 +1,19 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryObj } from '@storybook/react-vite';
+/**
+ * WordPress dependencies
+ */
+import '@wordpress/components/build-style/style.css';
+import '@wordpress/dataviews/build-style/style.css';
+/**
+ * Internal dependencies
+ */
+import { WidgetRender } from '..';
+declare const meta: Meta<typeof WidgetRender>;
+export default meta;
+export declare const Default: StoryObj;
+export declare const WithSettings: StoryObj;
+export declare const WithHostChrome: StoryObj;
+//# sourceMappingURL=index.story.d.ts.map

package/build-types/components/widget-render/stories/index.story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../../src/components/widget-render/stories/index.story.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAG5D;;GAEG;AAGH,OAAO,6CAA6C,CAAC;AAErD,OAAO,4CAA4C,CAAC;AAOpD;;GAEG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AA4HlC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,YAAY,CAwBpC,CAAC;eAEa,IAAI;AAqBnB,eAAO,MAAM,OAAO,EAAE,QAgBrB,CAAC;AAyDF,eAAO,MAAM,YAAY,EAAE,QAiB1B,CAAC;AAwDF,eAAO,MAAM,cAAc,EAAE,QAe5B,CAAC"}

package/build-types/components/widget-render/widget-render.d.ts

@@ -0,0 +1,13 @@
+/**
+ * External dependencies
+ */
+import type { ResolveWidgetModule, WidgetType } from '../../types';
+interface WidgetRenderProps<Item = unknown> {
+    widgetType: WidgetType<Item>;
+    attributes?: Item;
+    setAttributes?: (next: Partial<Item>) => void;
+    resolveWidgetModule: ResolveWidgetModule;
+}
+export declare function WidgetRender<Item = unknown>({ widgetType, attributes, setAttributes, resolveWidgetModule }: WidgetRenderProps<Item>): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=widget-render.d.ts.map

package/build-types/components/widget-render/widget-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-render.d.ts","sourceRoot":"","sources":["../../../src/components/widget-render/widget-render.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEnE,UAAU,iBAAiB,CAAE,IAAI,GAAG,OAAO;IAC1C,UAAU,EAAE,UAAU,CAAE,IAAI,CAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,aAAa,CAAC,EAAE,CAAE,IAAI,EAAE,OAAO,CAAE,IAAI,CAAE,KAAM,IAAI,CAAC;IAClD,mBAAmB,EAAE,mBAAmB,CAAC;CACzC;AAOD,wBAAgB,YAAY,CAAE,IAAI,GAAG,OAAO,EAAI,EAC/C,UAAU,EACV,UAAU,EACV,aAAa,EACb,mBAAmB,EACnB,EAAE,iBAAiB,CAAE,IAAI,CAAE,+BAgB3B"}

package/build-types/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useWidgetTypes } from './use-widget-types';
+//# sourceMappingURL=index.d.ts.map

package/build-types/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/build-types/hooks/use-widget-types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+import type { WidgetModuleRecord, WidgetType } from '../types';
+type UseWidgetTypesResult = readonly [WidgetType[], boolean];
+/**
+ * Resolves widget types from host-supplied records.
+ *
+ * For each record it dynamically imports `widget_module` and merges the
+ * module's default export with the runtime fields (`name`, `renderModule`).
+ * Pass `null`/`undefined` while records are still loading.
+ *
+ * @param records Host-supplied records, or `null`/`undefined` while loading.
+ */
+export declare function useWidgetTypes(records: WidgetModuleRecord[] | null | undefined): UseWidgetTypesResult;
+export {};
+//# sourceMappingURL=use-widget-types.d.ts.map

package/build-types/hooks/use-widget-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-widget-types.d.ts","sourceRoot":"","sources":["../../src/hooks/use-widget-types.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAc,UAAU,EAAE,MAAM,UAAU,CAAC;AAI3E,KAAK,oBAAoB,GAAG,SAAS,CAAE,UAAU,EAAE,EAAE,OAAO,CAAE,CAAC;AAE/D;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC7B,OAAO,EAAE,kBAAkB,EAAE,GAAG,IAAI,GAAG,SAAS,GAC9C,oBAAoB,CAgEtB"}

package/build-types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Components
+ */
+export { WidgetRender } from './components/widget-render';
+/**
+ * Hooks
+ */
+export { useWidgetTypes } from './hooks';
+/**
+ * Types
+ */
+export type { WidgetName, WidgetIcon, WidgetType, WidgetRenderProps, ResolveWidgetModule, WidgetModuleRecord, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/build-types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D;;GAEG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC;;GAEG;AACH,YAAY,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,GAClB,MAAM,SAAS,CAAC"}

package/build-types/tools/get-lazy-widget-component/get-lazy-widget-component.d.ts

@@ -0,0 +1,12 @@
+/**
+ * External dependencies
+ */
+import type { ComponentType } from 'react';
+/**
+ * Internal dependencies
+ */
+import type { ResolveWidgetModule, WidgetRenderProps } from '../../types';
+type LazyWidgetComponent = ComponentType<WidgetRenderProps<unknown>>;
+export declare function getLazyWidgetComponent(renderModule: string, resolveWidgetModule: ResolveWidgetModule): LazyWidgetComponent;
+export {};
+//# sourceMappingURL=get-lazy-widget-component.d.ts.map

package/build-types/tools/get-lazy-widget-component/get-lazy-widget-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-lazy-widget-component.d.ts","sourceRoot":"","sources":["../../../src/tools/get-lazy-widget-component/get-lazy-widget-component.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAO3C;;GAEG;AACH,OAAO,KAAK,EACX,mBAAmB,EAEnB,iBAAiB,EACjB,MAAM,aAAa,CAAC;AAErB,KAAK,mBAAmB,GAAG,aAAa,CAAE,iBAAiB,CAAE,OAAO,CAAE,CAAE,CAAC;AAsBzE,wBAAgB,sBAAsB,CACrC,YAAY,EAAE,MAAM,EACpB,mBAAmB,EAAE,mBAAmB,GACtC,mBAAmB,CAiBrB"}

package/build-types/tools/get-lazy-widget-component/index.d.ts

@@ -0,0 +1,2 @@
+export { getLazyWidgetComponent } from './get-lazy-widget-component';
+//# sourceMappingURL=index.d.ts.map

package/build-types/tools/get-lazy-widget-component/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/get-lazy-widget-component/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/build-types/types.d.ts

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

package/build-types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,GAAI,MAAO,IAAK,MAAO,EAAE,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,CAAE,cAAc,CAAE,KAAK,CAAE,CAAE,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAE,IAAI,GAAG,OAAO;IAClD;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,eAAe,GAAG,YAAY,CAAC;IAEzD;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC;;;;OAIG;IACH,UAAU,CAAC,EAAE,KAAK,CAAE,IAAI,CAAE,EAAE,CAAC;IAE7B;;;;OAIG;IACH,OAAO,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,OAAO,CAAE,IAAI,CAAE,CAAC;KAC7B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU,CAAE,IAAI,GAAG,OAAO,CAC1C,SAAQ,kBAAkB,CAAE,IAAI,CAAE;IAClC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAE,IAAI,GAAG,OAAO;IACjD;;OAEG;IACH,UAAU,EAAE,IAAI,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAE,IAAI,EAAE,OAAO,CAAE,IAAI,CAAE,KAAM,IAAI,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,aAAa,CAAE,iBAAiB,CAAE,OAAO,CAAE,CAAE,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CACjC,QAAQ,EAAE,MAAM,KACZ,OAAO,CAAE,YAAY,CAAE,CAAC;AAE7B;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;;OAEG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAE,cAAc,CAAE,GAAG,IAAI,CAAC;CAC3D"}

package/package.json

@@ -0,0 +1,72 @@
+{
+	"name": "@wordpress/widget-primitives",
+	"version": "0.1.0",
+	"description": "Host-agnostic toolkit for dashboard widgets: the widget contract types, the discovery hook, and the render entry point.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"gutenberg",
+		"widgets",
+		"dashboard"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/widget-primitives/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/widget-primitives"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=20.10.0",
+		"npm": ">=10.2.3"
+	},
+	"files": [
+		"src",
+		"build",
+		"build-module",
+		"build-types",
+		"*.md"
+	],
+	"main": "build/index.cjs",
+	"module": "build-module/index.mjs",
+	"exports": {
+		".": {
+			"types": "./build-types/index.d.ts",
+			"import": "./build-module/index.mjs",
+			"default": "./build/index.cjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"wpScript": false,
+	"types": "build-types",
+	"sideEffects": false,
+	"dependencies": {
+		"@wordpress/dataviews": "^17.0.0",
+		"@wordpress/element": "^8.1.0"
+	},
+	"devDependencies": {
+		"@storybook/addon-docs": "^10.4.3",
+		"@storybook/react-vite": "^10.4.3",
+		"@wordpress/components": "^36.0.0",
+		"@wordpress/icons": "^15.0.0",
+		"@wordpress/ui": "^0.16.0",
+		"storybook": "^10.4.3"
+	},
+	"peerDependencies": {
+		"@types/react": "^18.3.27",
+		"react": "^18.0.0",
+		"react-dom": "^18.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@types/react": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "0e7112a4f4fde4ea15bd9060489b8f6fe11eb6ca"
+}

package/src/components/widget-render/index.ts

@@ -0,0 +1 @@
+export { WidgetRender } from './widget-render';