@evanion/react-widget 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.1.0 (2026-08-26)
+
+First published release of `@evanion/react-widget`.
+
+Still 0.x deliberately: the API works and is type-checked, but has not been
+exercised by real consumers yet, so it may still move.
+
+### 🚀 Features
+
+- `createWidgets` infers from the component map you give it. An item's `type`
+  must be a key of the map, and its `props` are checked against that component,
+  so an unknown widget type is a compile error rather than a runtime warning.
+- `defineItems` helper, for item arrays declared in a variable — a bare array
+  literal widens `type` to `string` and silently loses the check.
+- Nested widgets via an injected `<Output />`, to any depth.
+- Custom chrome (`wrapper` and `item`), overridable per instance.
+- Built-in error boundary and Suspense fallback per widget.
+
+### 🩹 Fixes
+
+- Nesting silently stopped at depth 2 — `Output` never passed an `Output` to
+  grandchildren, so the third level was dropped.
+- The unknown-type guard used `in`, which walks the prototype chain, so a
+  CMS-supplied `type` of `constructor` or `toString` crashed the render instead
+  of warning and skipping.
+- Nested subtrees remounted on every parent render, discarding child state,
+  effects and focus, because a new `Output` component type was built each time.
+- Nested widgets ignored instance-level `chrome`.
+- `DefaultWrapper` and `DefaultItem` were documented but never exported.
+
+### 📦 Packaging
+
+- Declared a `react` peer dependency (`^18 || ^19`); there was previously no
+  dependency information at all.
+- Added `LICENSE`, `repository`, `engines` and `sideEffects`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mikael Pettersson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,424 @@
+# @evanion/react-widget
+
+A powerful React library for creating dynamic, reusable widget regions from structured data. Perfect for building CMS-driven layouts, dynamic sidebars, dashboards, and any interface that needs to render different components based on configuration data.
+
+## Features
+
+- 🎯 **Type-safe**: `createWidgets` infers from your component map, so an unknown
+  widget `type` or mismatched `props` is a compile error, not a runtime warning
+- 🔧 **Flexible**: Support for custom chrome components and wrappers
+- ⚡ **Lightweight**: Minimal bundle size with zero dependencies
+- 🎨 **Customizable**: Easy theming and styling through wrapper components
+- 🔄 **Context-aware**: Built-in React Context support for component sharing
+- 📦 **Tree-shakable**: Only import what you need
+
+## Installation
+
+```bash
+npm install @evanion/react-widget
+# or
+yarn add @evanion/react-widget
+# or
+pnpm add @evanion/react-widget
+```
+
+## Typing your items
+
+`createWidgets` infers the allowed `type` values and each item's `props` from the
+component map you give it.
+
+```tsx
+const { Widgets, defineItems } = createWidgets({
+  components: { news: NewsTeaser, weather: WeatherCard },
+});
+
+const items = defineItems([
+  { id: '1', type: 'news', props: { title: 'Hello' } },
+  { id: '2', type: 'nope', props: {} }, // ✗ 'nope' is not in the component map
+  { id: '3', type: 'weather', props: { celsius: 'warm' } }, // ✗ celsius is a number
+]);
+```
+
+`defineItems` is an identity function that exists purely to supply the contextual
+type. A bare `const items = [{ type: 'news', ... }]` widens `type` to `string`,
+which cannot narrow to the map's keys, and the check is silently lost. Writing
+the array inline in JSX works too — that is already contextually typed.
+
+## Quick Start
+
+```tsx
+import { createWidgets } from '@evanion/react-widget';
+import { PropsWithChildren } from 'react';
+
+// Define your widget components
+const NewsTeaser = ({ title, publishedAt, body }: NewsProps) => (
+  <article>
+    <h3>{title}</h3>
+    <time>{publishedAt.toLocaleDateString()}</time>
+    <p>{body}</p>
+  </article>
+);
+
+const UserSidebar = ({ username, avatar, messages }: UserProps) => (
+  <div className="user-info">
+    <img src={avatar} alt={username} />
+    <span>{username}</span>
+    <span>{messages} messages</span>
+  </div>
+);
+
+// Create your widget configuration
+const { Widgets } = createWidgets({
+  components: {
+    news: NewsTeaser,
+    userInfo: UserSidebar,
+  },
+  chrome: {
+    wrapper: ({ children }: PropsWithChildren) => (
+      <aside className="sidebar">{children}</aside>
+    ),
+  },
+});
+
+// Define your widget data
+const items = [
+  {
+    id: 'userinfo',
+    type: 'userInfo',
+    props: {
+      username: 'Evanion',
+      avatar: 'https://evanion.com/avatar.jpg',
+      messages: 5,
+    },
+  },
+  {
+    id: 'news1',
+    type: 'news',
+    props: {
+      title: 'Breaking News',
+      publishedAt: new Date(),
+      body: 'This is a sample news article...',
+    },
+  },
+];
+
+// Use in your layout
+function MyLayout({ children }: PropsWithChildren) {
+  return (
+    <main>
+      <article>{children}</article>
+      <Widgets items={items} />
+    </main>
+  );
+}
+```
+
+## API Reference
+
+### `createWidgets<Items>(config)`
+
+Creates a widget system with the given configuration.
+
+#### Parameters
+
+- `config.components` - Object mapping widget types to React components
+- `config.chrome` - Optional wrapper components for styling
+- `config.context` - Optional React Context for component sharing
+
+#### Returns
+
+- `Widgets` - Component for rendering widget items
+- `WidgetsProvider` - Context provider for sharing components
+- `useWidgets` - Hook for accessing widget components in context
+
+### `Widgets` Component
+
+Renders a list of widget items.
+
+#### Props
+
+- `items` - Array of widget items to render
+- `components` - Optional override components for this instance
+- `chrome` - Optional chrome overrides for this instance
+
+### Widget Item Structure
+
+```tsx
+interface WidgetItem {
+  id: string; // Unique identifier
+  type: string; // Widget type -- must be a key of your component map
+  props: object; // Props for that component, checked against it
+  children?: WidgetItem[]; // Nested widgets, rendered by the injected <Output />
+}
+```
+
+## Advanced Usage
+
+### Custom Chrome Components
+
+```tsx
+const { Widgets } = createWidgets({
+  components: {/* your components */},
+  chrome: {
+    wrapper: ({ children }) => (
+      <div className="widget-container">
+        <header>My Widgets</header>
+        <div className="widget-content">{children}</div>
+      </div>
+    ),
+    item: ({ children }) => <div className="widget-item">{children}</div>,
+  },
+});
+```
+
+### Using Context for Component Sharing
+
+```tsx
+import { createContext } from 'react';
+
+const MyWidgetContext = createContext({});
+
+const { Widgets, WidgetsProvider } = createWidgets({
+  components: {/* your components */},
+  context: MyWidgetContext,
+});
+
+// Use the context in your app
+function App() {
+  return (
+    <WidgetsProvider>
+      <MyLayout />
+    </WidgetsProvider>
+  );
+}
+```
+
+### Instance-specific Component Overrides
+
+```tsx
+function MyPage() {
+  const specialNewsComponent = ({ title, ...props }) => (
+    <div className="featured-news">
+      <h2>Featured: {title}</h2>
+    </div>
+  );
+
+  return <Widgets items={items} components={{ news: specialNewsComponent }} />;
+}
+```
+
+### Nested Widgets
+
+Use the `<Output />` component to render nested widgets within your components:
+
+```tsx
+const { Widgets, Output } = createWidgets({
+  components: {
+    card: CardWidget,
+    text: TextWidget,
+  },
+});
+
+// Card component that can contain nested widgets
+const CardWidget = ({ title, Output }) => (
+  <div className="card">
+    <h3>{title}</h3>
+    <Output />
+  </div>
+);
+
+const TextWidget = ({ content }) => <p>{content}</p>;
+
+// Usage with nested widgets
+const items = [
+  {
+    id: 'card1',
+    type: 'card',
+    props: {
+      title: 'My Card',
+    },
+    children: [
+      {
+        id: 'text1',
+        type: 'text',
+        props: { content: 'This is nested content' },
+      },
+    ],
+  },
+];
+```
+
+### Error Handling & Performance
+
+The library includes built-in error handling and performance optimizations:
+
+#### Error Boundaries
+
+Each widget is automatically wrapped in an error boundary that:
+
+- Catches rendering errors and displays a fallback UI
+- Logs detailed error information to the console
+- Prevents one failing widget from breaking the entire page
+
+#### Suspense Support
+
+Widgets support React Suspense for loading states:
+
+- Automatic loading fallback for lazy-loaded components
+- Customizable loading UI through chrome components
+- Graceful handling of async operations
+
+#### Performance Optimizations
+
+- `React.memo` for preventing unnecessary re-renders
+- `useCallback` for stable function references
+- Optimized dependency arrays for `useMemo`
+- Silent error handling with console warnings for unknown widget types
+
+#### Unknown Widget Handling
+
+When a widget type is not found:
+
+- Logs a warning with widget type and ID
+- Silently skips rendering (doesn't break the page)
+- Continues rendering other widgets normally
+
+```tsx
+// Example: Custom error boundary and loading states
+const CustomItem = ({ children, ...props }) => (
+  <div {...props}>
+    <ErrorBoundary fallback={<div>Custom error UI</div>}>
+      <Suspense fallback={<div>Custom loading...</div>}>{children}</Suspense>
+    </ErrorBoundary>
+  </div>
+);
+
+const { Widgets } = createWidgets({
+  components: {/* ... */},
+  chrome: { item: CustomItem },
+});
+```
+
+### TypeScript Support
+
+The library provides full TypeScript support with type inference:
+
+```tsx
+interface NewsProps {
+  title: string;
+  publishedAt: Date;
+  body: string;
+}
+
+interface UserProps {
+  username: string;
+  avatar: string;
+  messages: number;
+}
+
+const { Widgets } = createWidgets<{
+  news: NewsProps;
+  userInfo: UserProps;
+}>({
+  components: {
+    news: NewsTeaser,
+    userInfo: UserSidebar,
+  },
+});
+
+// TypeScript will now enforce correct prop types
+const items = [
+  {
+    id: 'news1',
+    type: 'news',
+    props: {
+      title: 'Hello World',
+      publishedAt: new Date(),
+      body: 'Content here',
+      // TypeScript will error if any required props are missing
+    },
+  },
+];
+```
+
+## Use Cases
+
+- **CMS-driven layouts**: Render page content based on CMS configuration
+- **Dashboard widgets**: Dynamic dashboard with configurable components
+- **Sidebar content**: Dynamic sidebar with different widget types
+- **Marketing pages**: A/B testing different content layouts
+- **Admin panels**: Configurable admin interface components
+- **E-commerce**: Dynamic product showcases and recommendations
+
+## Examples
+
+### E-commerce Product Showcase
+
+```tsx
+const { Widgets } = createWidgets({
+  components: {
+    productCard: ProductCard,
+    banner: Banner,
+    categoryFilter: CategoryFilter,
+  },
+  chrome: {
+    wrapper: ({ children }) => (
+      <div className="product-showcase">{children}</div>
+    ),
+  },
+});
+
+const showcaseItems = [
+  {
+    id: 'banner1',
+    type: 'banner',
+    props: {
+      image: '/banner.jpg',
+      title: 'Summer Sale',
+      cta: 'Shop Now',
+    },
+  },
+  {
+    id: 'filter1',
+    type: 'categoryFilter',
+    props: {
+      categories: ['Electronics', 'Clothing', 'Books'],
+    },
+  },
+  {
+    id: 'product1',
+    type: 'productCard',
+    props: {
+      name: 'Wireless Headphones',
+      price: 99.99,
+      image: '/headphones.jpg',
+    },
+  },
+];
+```
+
+### Blog Layout with Sidebar
+
+```tsx
+const { Widgets } = createWidgets({
+  components: {
+    authorBio: AuthorBio,
+    relatedPosts: RelatedPosts,
+    newsletterSignup: NewsletterSignup,
+    socialShare: SocialShare,
+  },
+  chrome: {
+    wrapper: ({ children }) => (
+      <aside className="blog-sidebar">{children}</aside>
+    ),
+  },
+});
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see LICENSE file for details.

package/dist/constants.d.ts

@@ -0,0 +1,24 @@
+export declare const ERROR_MESSAGES: {
+    readonly UNKNOWN_WIDGET: (type: string, id: string) => string;
+    readonly WIDGET_ERROR: (type: string, id: string) => string;
+    readonly WIDGET_FAILED: (type: string) => string;
+    readonly LOADING: "Loading widget...";
+    readonly UNKNOWN: "unknown";
+};
+export declare const DEFAULT_STYLES: {
+    readonly ERROR: {
+        readonly padding: "8px";
+        readonly border: "1px solid #ff6b6b";
+        readonly borderRadius: "4px";
+        readonly backgroundColor: "#ffe0e0";
+        readonly color: "#d63031";
+    };
+    readonly LOADING: {
+        readonly padding: "8px";
+        readonly border: "1px solid #ddd";
+        readonly borderRadius: "4px";
+        readonly backgroundColor: "#f8f9fa";
+        readonly color: "#666";
+    };
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc;oCACF,MAAM,MAAM,MAAM;kCAEpB,MAAM,MAAM,MAAM;mCAEjB,MAAM;;;CAGpB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;CAejB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './widget.js';
+export * from './widgets.js';
+export * from './types.js';
+export * from './constants.js';
+export * from './utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,116 @@
+import e, { Component as t, Suspense as n, createContext as r, memo as i, useContext as a, useMemo as o } from "react";
+import { Fragment as s, jsx as c } from "react/jsx-runtime";
+//#region src/constants.ts
+var l = {
+	UNKNOWN_WIDGET: (e, t) => `Unknown widget type "${e}" for widget ID "${t}". Skipping render.`,
+	WIDGET_ERROR: (e, t) => `Widget Error: ${e} (ID: ${t})`,
+	WIDGET_FAILED: (e) => `Widget failed to render: ${e}`,
+	LOADING: "Loading widget...",
+	UNKNOWN: "unknown"
+}, u = {
+	ERROR: {
+		padding: "8px",
+		border: "1px solid #ff6b6b",
+		borderRadius: "4px",
+		backgroundColor: "#ffe0e0",
+		color: "#d63031"
+	},
+	LOADING: {
+		padding: "8px",
+		border: "1px solid #ddd",
+		borderRadius: "4px",
+		backgroundColor: "#f8f9fa",
+		color: "#666"
+	}
+};
+//#endregion
+//#region src/widgets.tsx
+function d(e) {
+	return /* @__PURE__ */ c("section", { ...e });
+}
+var f = class extends t {
+	constructor(e) {
+		super(e), this.state = { hasError: !1 };
+	}
+	static getDerivedStateFromError(e) {
+		return {
+			hasError: !0,
+			error: e
+		};
+	}
+	componentDidCatch(e, t) {
+		console.error(l.WIDGET_ERROR(this.props.widgetType, this.props.widgetId), e, t);
+	}
+	render() {
+		return this.state.hasError ? /* @__PURE__ */ c("div", {
+			style: u.ERROR,
+			children: l.WIDGET_FAILED(this.props.widgetType)
+		}) : this.props.children;
+	}
+}, p = () => /* @__PURE__ */ c("div", {
+	style: u.LOADING,
+	children: l.LOADING
+});
+function m(e) {
+	let { "data-widget-id": t, "data-widget-type": r, ...i } = e;
+	return /* @__PURE__ */ c("div", {
+		...i,
+		children: /* @__PURE__ */ c(f, {
+			widgetId: t || l.UNKNOWN,
+			widgetType: r || l.UNKNOWN,
+			children: /* @__PURE__ */ c(n, {
+				fallback: /* @__PURE__ */ c(p, {}),
+				children: e.children
+			})
+		})
+	});
+}
+var h = e.createContext({
+	items: [],
+	ItemWrapper: (e) => /* @__PURE__ */ c("div", { ...e })
+});
+function g(e, t, n, r) {
+	let i = Object.prototype.hasOwnProperty.call(t, e.type) ? t[e.type] : void 0;
+	if (!i) return console.warn(l.UNKNOWN_WIDGET(e.type, e.id)), null;
+	let a = e.children ?? [];
+	return /* @__PURE__ */ c(h.Provider, {
+		value: {
+			items: a,
+			ItemWrapper: n
+		},
+		children: /* @__PURE__ */ c(n, {
+			"data-widget-id": e.id,
+			"data-widget-type": e.type,
+			children: /* @__PURE__ */ c(i, {
+				...e.props,
+				Output: r
+			})
+		})
+	}, e.id);
+}
+//#endregion
+//#region src/widget.tsx
+function _(e) {
+	let { components: t, chrome: n, context: l } = e, u = l || r(t), f = u.Provider, p = () => a(u), _ = i(function e() {
+		let { items: t, ItemWrapper: n } = a(h), r = p();
+		return !t || t.length === 0 ? null : /* @__PURE__ */ c(s, { children: t.map((t) => g(t, r, n, e)) });
+	});
+	return {
+		Widgets: i(function({ items: e, components: r, chrome: i }) {
+			let a = i?.wrapper || n?.wrapper || d, s = i?.item || n?.item || m, l = o(() => ({
+				...t,
+				...r
+			}), [r]);
+			return /* @__PURE__ */ c(f, {
+				value: l,
+				children: /* @__PURE__ */ c(a, { children: e.map((e) => g(e, l, s, _)) })
+			});
+		}),
+		WidgetsProvider: f,
+		useWidgets: p,
+		Output: _,
+		defineItems: (e) => e
+	};
+}
+//#endregion
+export { u as DEFAULT_STYLES, m as DefaultItem, d as DefaultWrapper, l as ERROR_MESSAGES, h as NestedWidgetsContext, _ as createWidgets, g as renderWidget };

package/dist/types.d.ts

@@ -0,0 +1,115 @@
+import { ComponentProps, ComponentType, Context, ReactNode } from 'react';
+/**
+ * The prop every widget component receives so it can render its own children.
+ * Injected by the renderer; it is never part of the item data.
+ */
+export interface WidgetOutputProps {
+    Output: ComponentType;
+}
+/**
+ * Any widget component, for use in a generic *constraint*.
+ *
+ * `any` is load-bearing here and cannot be tightened. `ComponentType<unknown>`
+ * would reject a component with concrete props, because component props are
+ * contravariant -- a `ComponentType<{title: string}>` is not assignable to a
+ * `ComponentType<unknown>`. TypeScript offers no "some component, props
+ * unknown" type for this position.
+ *
+ * This does not weaken inference: `ComponentProps<C[K]>` below resolves against
+ * the concrete component that was actually passed, not against this constraint.
+ */
+export type AnyWidgetComponent = ComponentType<any>;
+/**
+ * A map of widget type name -> component.
+ *
+ * This is the type that drives inference for a whole widget set: pass a literal
+ * object to {@link createWidgets} and every item's `type` and `props` are
+ * checked against it.
+ */
+export type WidgetComponentMap = Record<string, AnyWidgetComponent>;
+/**
+ * The props a widget component accepts as *data*, i.e. everything except the
+ * injected {@link WidgetOutputProps.Output}.
+ */
+export type WidgetDataProps<C extends AnyWidgetComponent> = Omit<ComponentProps<C>, keyof WidgetOutputProps>;
+/**
+ * A single item in a widget set, discriminated on `type`.
+ *
+ * Distributing over the keys of the component map is what makes this checked:
+ * `type: 'news'` forces `props` to the props of the `news` component, and an
+ * unknown `type` is a compile error rather than a runtime `console.warn`.
+ */
+export type WidgetItem<C extends WidgetComponentMap> = {
+    [K in keyof C & string]: {
+        /** Stable identity for this item; used as the React key. */
+        id: string;
+        /** Which component to render. Must be a key of the component map. */
+        type: K;
+        /** Props for that component, minus the injected `Output`. */
+        props: WidgetDataProps<C[K]>;
+        /** Nested items, rendered by the item's injected `Output`. */
+        children?: WidgetItem<C>[];
+    };
+}[keyof C & string];
+/**
+ * Loose item shape, for callers that build item data before a component map
+ * exists (a CMS payload, a fixture, a network response).
+ *
+ * Prefer {@link WidgetItem}, which is checked against the component map.
+ */
+export interface WidgetProps<Type extends string = string, Props = object> {
+    id: string;
+    type: Type;
+    props: Props;
+    children?: WidgetProps[];
+}
+/**
+ * Type-erased view of an item, used internally by the renderer.
+ *
+ * The checked {@link WidgetItem} union is widened to this exactly once, at the
+ * boundary between the public props and the render loop. Spreading the
+ * discriminated union directly onto a component makes TypeScript give up with
+ * "union type that is too complex to represent" (TS2590), and the renderer
+ * gains nothing from the discrimination -- it looks the type up at runtime.
+ */
+export interface RenderableWidgetItem {
+    id: string;
+    type: string;
+    props: Record<string, unknown>;
+    children?: RenderableWidgetItem[];
+}
+/** Chrome wrapped around the whole widget set. */
+export type WidgetsWrapperComponent = ComponentType<{
+    children?: ReactNode;
+}>;
+/** Chrome wrapped around each individual widget. */
+export type WidgetItemComponent = ComponentType<{
+    children?: ReactNode;
+    'data-widget-id': string;
+    'data-widget-type': string;
+}>;
+export interface WidgetsChrome {
+    wrapper?: WidgetsWrapperComponent;
+    item?: WidgetItemComponent;
+}
+/**
+ * Configuration for {@link createWidgets}.
+ */
+export interface WidgetsConfig<C extends WidgetComponentMap> {
+    /** The component map. Its shape drives inference for the whole set. */
+    components: C;
+    chrome?: WidgetsChrome;
+    /** Supply your own context to share a component map across widget sets. */
+    context?: Context<C>;
+}
+/**
+ * Props of the `Widgets` component returned by {@link createWidgets}.
+ */
+export interface WidgetsProps<C extends WidgetComponentMap> {
+    items: WidgetItem<C>[];
+    /** Per-instance component overrides, merged over the factory's map. */
+    components?: Partial<C>;
+    /** Per-instance chrome overrides. */
+    chrome?: WidgetsChrome;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE/E;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,kBAAkB,IAAI,IAAI,CAC9D,cAAc,CAAC,CAAC,CAAC,EACjB,MAAM,iBAAiB,CACxB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,kBAAkB,IAAI;KACpD,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG;QACvB,4DAA4D;QAC5D,EAAE,EAAE,MAAM,CAAC;QACX,qEAAqE;QACrE,IAAI,EAAE,CAAC,CAAC;QACR,6DAA6D;QAC7D,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,8DAA8D;QAC9D,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5B;CACF,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,GAAG,MAAM;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACnC;AAED,kDAAkD;AAClD,MAAM,MAAM,uBAAuB,GAAG,aAAa,CAAC;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAE9E,oDAAoD;AACpD,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC;IAC9C,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAClC,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,kBAAkB;IACzD,uEAAuE;IACvE,UAAU,EAAE,CAAC,CAAC;IACd,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,kBAAkB;IACxD,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IACvB,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,qCAAqC;IACrC,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB"}

package/dist/utils.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { AnyWidgetComponent, RenderableWidgetItem, WidgetItemComponent } from './types.js';
+/**
+ * Context carrying the current widget's children down to the injected `Output`
+ * component, together with the chrome resolved for this render.
+ *
+ * Passing children through context (rather than closing over them in a
+ * freshly-created component) is what keeps `Output` a single stable component
+ * type, and what lets nesting recurse to arbitrary depth.
+ */
+export interface NestedWidgets {
+    items: RenderableWidgetItem[];
+    ItemWrapper: WidgetItemComponent;
+}
+export declare const NestedWidgetsContext: React.Context<NestedWidgets>;
+export declare function renderWidget(item: RenderableWidgetItem, components: Record<string, AnyWidgetComponent>, ItemWrapper: WidgetItemComponent, Output: React.ComponentType): React.JSX.Element | null;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAMD,eAAO,MAAM,oBAAoB,8BAG/B,CAAC;AAEH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,oBAAoB,EAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC9C,WAAW,EAAE,mBAAmB,EAChC,MAAM,EAAE,KAAK,CAAC,aAAa,4BA+B5B"}

package/dist/widget.d.ts

@@ -0,0 +1,27 @@
+import { WidgetComponentMap, WidgetItem, WidgetsConfig, WidgetsProps } from './types.js';
+/**
+ * Builds a widget set from a component map.
+ *
+ * The map drives inference: each item's `type` must be a key of it, and that
+ * item's `props` must match the corresponding component's props.
+ *
+ * @example
+ * ```tsx
+ * const { Widgets } = createWidgets({
+ *   components: { news: NewsTeaser, profile: UserSidebar },
+ * });
+ *
+ * <Widgets items={[
+ *   { id: '1', type: 'news', props: { title: 'Hello' } },
+ *   { id: '2', type: 'nope', props: {} },  // ← compile error: unknown type
+ * ]} />
+ * ```
+ */
+export declare function createWidgets<const C extends WidgetComponentMap>(config: WidgetsConfig<C>): {
+    Widgets: import('react').MemoExoticComponent<({ items, components: instanceComponents, chrome, }: WidgetsProps<C>) => import("react").JSX.Element>;
+    WidgetsProvider: import('react').Provider<C>;
+    useWidgets: () => C;
+    Output: import('react').MemoExoticComponent<() => import("react").JSX.Element | null>;
+    defineItems: (items: WidgetItem<C>[]) => WidgetItem<C>[];
+};
+//# sourceMappingURL=widget.d.ts.map

package/dist/widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../src/widget.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAC9D,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;sGA2CrB,YAAY,CAAC,CAAC,CAAC;;;;yBAsCU,UAAU,CAAC,CAAC,CAAC,EAAE,KAAG,UAAU,CAAC,CAAC,CAAC,EAAE;EAG9D"}

package/dist/widgets.d.ts

@@ -0,0 +1,7 @@
+import { default as React, HTMLProps } from 'react';
+export declare function DefaultWrapper(props: HTMLProps<HTMLDivElement>): React.JSX.Element;
+export declare function DefaultItem(props: HTMLProps<HTMLDivElement> & {
+    'data-widget-id'?: string;
+    'data-widget-type'?: string;
+}): React.JSX.Element;
+//# sourceMappingURL=widgets.d.ts.map

package/dist/widgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widgets.d.ts","sourceRoot":"","sources":["../src/widgets.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAkC,MAAM,OAAO,CAAC;AAGzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC,cAAc,CAAC,qBAE9D;AA8CD,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,qBAoBF"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@evanion/react-widget",
+  "version": "0.1.0",
+  "description": "Render dynamic, type-safe React widget regions from structured data. Built for CMS-driven layouts, dashboards and configurable sidebars.",
+  "keywords": [
+    "react",
+    "widget",
+    "cms",
+    "dynamic",
+    "layout",
+    "components",
+    "registry",
+    "typescript"
+  ],
+  "homepage": "https://github.com/Evanion/libraries/tree/main/libs/widget#readme",
+  "bugs": {
+    "url": "https://github.com/Evanion/libraries/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Evanion/libraries.git",
+    "directory": "libs/widget"
+  },
+  "license": "MIT",
+  "author": "Mikael Pettersson",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@evanion/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.test-d.*",
+    "!src/test-setup.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,26 @@
+export const ERROR_MESSAGES = {
+  UNKNOWN_WIDGET: (type: string, id: string) =>
+    `Unknown widget type "${type}" for widget ID "${id}". Skipping render.`,
+  WIDGET_ERROR: (type: string, id: string) =>
+    `Widget Error: ${type} (ID: ${id})`,
+  WIDGET_FAILED: (type: string) => `Widget failed to render: ${type}`,
+  LOADING: 'Loading widget...',
+  UNKNOWN: 'unknown',
+} as const;
+
+export const DEFAULT_STYLES = {
+  ERROR: {
+    padding: '8px',
+    border: '1px solid #ff6b6b',
+    borderRadius: '4px',
+    backgroundColor: '#ffe0e0',
+    color: '#d63031',
+  },
+  LOADING: {
+    padding: '8px',
+    border: '1px solid #ddd',
+    borderRadius: '4px',
+    backgroundColor: '#f8f9fa',
+    color: '#666',
+  },
+} as const;

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './widget.js';
+export * from './widgets.js';
+export * from './types.js';
+export * from './constants.js';
+export * from './utils.js';

package/src/types.ts

@@ -0,0 +1,128 @@
+import type { ComponentProps, ComponentType, Context, ReactNode } from 'react';
+
+/**
+ * The prop every widget component receives so it can render its own children.
+ * Injected by the renderer; it is never part of the item data.
+ */
+export interface WidgetOutputProps {
+  Output: ComponentType;
+}
+
+/**
+ * Any widget component, for use in a generic *constraint*.
+ *
+ * `any` is load-bearing here and cannot be tightened. `ComponentType<unknown>`
+ * would reject a component with concrete props, because component props are
+ * contravariant -- a `ComponentType<{title: string}>` is not assignable to a
+ * `ComponentType<unknown>`. TypeScript offers no "some component, props
+ * unknown" type for this position.
+ *
+ * This does not weaken inference: `ComponentProps<C[K]>` below resolves against
+ * the concrete component that was actually passed, not against this constraint.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyWidgetComponent = ComponentType<any>;
+
+/**
+ * A map of widget type name -> component.
+ *
+ * This is the type that drives inference for a whole widget set: pass a literal
+ * object to {@link createWidgets} and every item's `type` and `props` are
+ * checked against it.
+ */
+export type WidgetComponentMap = Record<string, AnyWidgetComponent>;
+
+/**
+ * The props a widget component accepts as *data*, i.e. everything except the
+ * injected {@link WidgetOutputProps.Output}.
+ */
+export type WidgetDataProps<C extends AnyWidgetComponent> = Omit<
+  ComponentProps<C>,
+  keyof WidgetOutputProps
+>;
+
+/**
+ * A single item in a widget set, discriminated on `type`.
+ *
+ * Distributing over the keys of the component map is what makes this checked:
+ * `type: 'news'` forces `props` to the props of the `news` component, and an
+ * unknown `type` is a compile error rather than a runtime `console.warn`.
+ */
+export type WidgetItem<C extends WidgetComponentMap> = {
+  [K in keyof C & string]: {
+    /** Stable identity for this item; used as the React key. */
+    id: string;
+    /** Which component to render. Must be a key of the component map. */
+    type: K;
+    /** Props for that component, minus the injected `Output`. */
+    props: WidgetDataProps<C[K]>;
+    /** Nested items, rendered by the item's injected `Output`. */
+    children?: WidgetItem<C>[];
+  };
+}[keyof C & string];
+
+/**
+ * Loose item shape, for callers that build item data before a component map
+ * exists (a CMS payload, a fixture, a network response).
+ *
+ * Prefer {@link WidgetItem}, which is checked against the component map.
+ */
+export interface WidgetProps<Type extends string = string, Props = object> {
+  id: string;
+  type: Type;
+  props: Props;
+  children?: WidgetProps[];
+}
+
+/**
+ * Type-erased view of an item, used internally by the renderer.
+ *
+ * The checked {@link WidgetItem} union is widened to this exactly once, at the
+ * boundary between the public props and the render loop. Spreading the
+ * discriminated union directly onto a component makes TypeScript give up with
+ * "union type that is too complex to represent" (TS2590), and the renderer
+ * gains nothing from the discrimination -- it looks the type up at runtime.
+ */
+export interface RenderableWidgetItem {
+  id: string;
+  type: string;
+  props: Record<string, unknown>;
+  children?: RenderableWidgetItem[];
+}
+
+/** Chrome wrapped around the whole widget set. */
+export type WidgetsWrapperComponent = ComponentType<{ children?: ReactNode }>;
+
+/** Chrome wrapped around each individual widget. */
+export type WidgetItemComponent = ComponentType<{
+  children?: ReactNode;
+  'data-widget-id': string;
+  'data-widget-type': string;
+}>;
+
+export interface WidgetsChrome {
+  wrapper?: WidgetsWrapperComponent;
+  item?: WidgetItemComponent;
+}
+
+/**
+ * Configuration for {@link createWidgets}.
+ */
+export interface WidgetsConfig<C extends WidgetComponentMap> {
+  /** The component map. Its shape drives inference for the whole set. */
+  components: C;
+  chrome?: WidgetsChrome;
+  /** Supply your own context to share a component map across widget sets. */
+  context?: Context<C>;
+}
+
+/**
+ * Props of the `Widgets` component returned by {@link createWidgets}.
+ */
+export interface WidgetsProps<C extends WidgetComponentMap> {
+  items: WidgetItem<C>[];
+  /** Per-instance component overrides, merged over the factory's map. */
+  components?: Partial<C>;
+  /** Per-instance chrome overrides. */
+  chrome?: WidgetsChrome;
+}

package/src/utils.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import { ERROR_MESSAGES } from './constants.js';
+import type {
+  AnyWidgetComponent,
+  RenderableWidgetItem,
+  WidgetItemComponent,
+} from './types.js';
+
+/**
+ * Context carrying the current widget's children down to the injected `Output`
+ * component, together with the chrome resolved for this render.
+ *
+ * Passing children through context (rather than closing over them in a
+ * freshly-created component) is what keeps `Output` a single stable component
+ * type, and what lets nesting recurse to arbitrary depth.
+ */
+export interface NestedWidgets {
+  items: RenderableWidgetItem[];
+  ItemWrapper: WidgetItemComponent;
+}
+
+const DefaultNestedItemWrapper: WidgetItemComponent = (props) => (
+  <div {...props} />
+);
+
+export const NestedWidgetsContext = React.createContext<NestedWidgets>({
+  items: [],
+  ItemWrapper: DefaultNestedItemWrapper,
+});
+
+export function renderWidget(
+  item: RenderableWidgetItem,
+  components: Record<string, AnyWidgetComponent>,
+  ItemWrapper: WidgetItemComponent,
+  Output: React.ComponentType,
+) {
+  // `in` walks the prototype chain, so a CMS-supplied type of "constructor",
+  // "toString" or "__proto__" would pass this guard and hand React something
+  // off Object.prototype. Items are explicitly untrusted input.
+  //
+  // The truthiness check is not redundant: an own key can still hold undefined,
+  // and noUncheckedIndexedAccess makes that possibility explicit.
+  const Component = Object.prototype.hasOwnProperty.call(components, item.type)
+    ? components[item.type]
+    : undefined;
+
+  if (!Component) {
+    console.warn(ERROR_MESSAGES.UNKNOWN_WIDGET(item.type, item.id));
+    return null;
+  }
+
+  const children = item.children ?? [];
+
+  return (
+    // Each widget provides its own children, so a nested `Output` renders that
+    // widget's children rather than its parent's -- at any depth.
+    <NestedWidgetsContext.Provider
+      key={item.id}
+      value={{ items: children, ItemWrapper }}
+    >
+      <ItemWrapper data-widget-id={item.id} data-widget-type={item.type}>
+        <Component {...item.props} Output={Output} />
+      </ItemWrapper>
+    </NestedWidgetsContext.Provider>
+  );
+}

package/src/widget.tsx

@@ -0,0 +1,115 @@
+import { createContext, useContext, useMemo, memo } from 'react';
+import type {
+  RenderableWidgetItem,
+  WidgetComponentMap,
+  WidgetItem,
+  WidgetsConfig,
+  WidgetsProps,
+} from './types.js';
+import { DefaultItem, DefaultWrapper } from './widgets.js';
+import { renderWidget, NestedWidgetsContext } from './utils.js';
+
+/**
+ * Builds a widget set from a component map.
+ *
+ * The map drives inference: each item's `type` must be a key of it, and that
+ * item's `props` must match the corresponding component's props.
+ *
+ * @example
+ * ```tsx
+ * const { Widgets } = createWidgets({
+ *   components: { news: NewsTeaser, profile: UserSidebar },
+ * });
+ *
+ * <Widgets items={[
+ *   { id: '1', type: 'news', props: { title: 'Hello' } },
+ *   { id: '2', type: 'nope', props: {} },  // ← compile error: unknown type
+ * ]} />
+ * ```
+ */
+export function createWidgets<const C extends WidgetComponentMap>(
+  config: WidgetsConfig<C>,
+) {
+  const {
+    components: defaultComponents,
+    chrome: defaultChrome,
+    context,
+  } = config;
+
+  const WidgetsContext = context || createContext<C>(defaultComponents);
+
+  const WidgetsProvider = WidgetsContext.Provider;
+  const useWidgets = () => useContext(WidgetsContext);
+
+  /**
+   * Renders the children of whichever widget is currently rendering.
+   *
+   * Defined once per `createWidgets` call, so its component type is stable for
+   * the lifetime of the factory. Previously a new component was built on every
+   * render, and because React compares element types by identity that
+   * unmounted and remounted every nested subtree on each parent render --
+   * discarding child state, effects and focus.
+   */
+  const Output = memo(function Output() {
+    const { items, ItemWrapper } = useContext(NestedWidgetsContext);
+    const components = useWidgets();
+
+    if (!items || items.length === 0) {
+      return null;
+    }
+
+    return (
+      <>
+        {items.map((item) =>
+          renderWidget(item, components, ItemWrapper, Output),
+        )}
+      </>
+    );
+  });
+
+  const Widgets = memo(function Widgets({
+    items,
+    components: instanceComponents,
+    chrome,
+  }: WidgetsProps<C>) {
+    const Wrapper = chrome?.wrapper || defaultChrome?.wrapper || DefaultWrapper;
+    const ItemWrapper = chrome?.item || defaultChrome?.item || DefaultItem;
+    const components = useMemo(
+      () => ({ ...defaultComponents, ...instanceComponents }),
+      [instanceComponents],
+    );
+
+    return (
+      <WidgetsProvider value={components}>
+        <Wrapper>
+          {/* The single, documented widening from the checked WidgetItem<C>
+              union to the renderer's erased view. See RenderableWidgetItem. */}
+          {(items as unknown as RenderableWidgetItem[]).map((item) =>
+            renderWidget(item, components, ItemWrapper, Output),
+          )}
+        </Wrapper>
+      </WidgetsProvider>
+    );
+  });
+
+  /**
+   * Identity function that supplies the contextual type for an item array.
+   *
+   * A bare `const items = [{ type: 'news', ... }]` infers `type: string`, which
+   * will not narrow to the component map's keys, so the check is lost. Passing
+   * the array through here gives TypeScript the contextual type it needs:
+   *
+   * ```ts
+   * const items = defineItems([
+   *   { id: '1', type: 'news', props: { title: 'Hello' } },
+   *   { id: '2', type: 'nope', props: {} },  // ← compile error
+   * ]);
+   * ```
+   *
+   * Not needed when the array is written inline in JSX -- that is already
+   * contextually typed. `satisfies WidgetItem<typeof components>[]` works too.
+   */
+  const defineItems = (items: WidgetItem<C>[]): WidgetItem<C>[] => items;
+
+  return { Widgets, WidgetsProvider, useWidgets, Output, defineItems };
+}

package/src/widgets.tsx

@@ -0,0 +1,76 @@
+import React, { HTMLProps, Suspense, Component, ReactNode } from 'react';
+import { ERROR_MESSAGES, DEFAULT_STYLES } from './constants.js';
+
+export function DefaultWrapper(props: HTMLProps<HTMLDivElement>) {
+  return <section {...props} />;
+}
+
+// Error boundary for individual widgets
+class WidgetErrorBoundary extends Component<
+  { children: ReactNode; widgetId: string; widgetType: string },
+  { hasError: boolean; error?: Error }
+> {
+  constructor(props: {
+    children: ReactNode;
+    widgetId: string;
+    widgetType: string;
+  }) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  override componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    console.error(
+      ERROR_MESSAGES.WIDGET_ERROR(this.props.widgetType, this.props.widgetId),
+      error,
+      errorInfo,
+    );
+  }
+
+  override render() {
+    if (this.state.hasError) {
+      return (
+        <div style={DEFAULT_STYLES.ERROR}>
+          {ERROR_MESSAGES.WIDGET_FAILED(this.props.widgetType)}
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+// Default loading fallback
+const DefaultLoadingFallback = () => (
+  <div style={DEFAULT_STYLES.LOADING}>{ERROR_MESSAGES.LOADING}</div>
+);
+
+export function DefaultItem(
+  props: HTMLProps<HTMLDivElement> & {
+    'data-widget-id'?: string;
+    'data-widget-type'?: string;
+  },
+) {
+  const {
+    'data-widget-id': widgetId,
+    'data-widget-type': widgetType,
+    ...restProps
+  } = props;
+
+  return (
+    <div {...restProps}>
+      <WidgetErrorBoundary
+        widgetId={widgetId || ERROR_MESSAGES.UNKNOWN}
+        widgetType={widgetType || ERROR_MESSAGES.UNKNOWN}
+      >
+        <Suspense fallback={<DefaultLoadingFallback />}>
+          {props.children}
+        </Suspense>
+      </WidgetErrorBoundary>
+    </div>
+  );
+}