@beechcms/widget-sdk 0.6.0-preview.3

package/dist/components/widget-empty.d.ts

@@ -0,0 +1,9 @@
+import type { LucideIcon } from 'lucide-react';
+export interface WidgetEmptyProps {
+    icon: LucideIcon;
+    title: string;
+    description?: string;
+}
+/** Placeholder shown by a widget when it has nothing to render. */
+export declare function WidgetEmpty({ icon: Icon, title, description }: WidgetEmptyProps): import("react").JSX.Element;
+//# sourceMappingURL=widget-empty.d.ts.map

package/dist/components/widget-empty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-empty.d.ts","sourceRoot":"","sources":["../../src/components/widget-empty.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,gBAAgB,+BAQ/E"}

package/dist/components/widget-empty.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Placeholder shown by a widget when it has nothing to render. */
+export function WidgetEmpty({ icon: Icon, title, description }) {
+    return (_jsxs("div", { className: "flex h-full min-h-[80px] flex-col items-center justify-center gap-2 text-center", children: [_jsx(Icon, { className: "size-8 text-muted-foreground/40" }), _jsx("p", { className: "text-sm font-medium text-muted-foreground", children: title }), description && _jsx("p", { className: "text-xs text-muted-foreground/70", children: description })] }));
+}

package/dist/components/widget-error.d.ts

@@ -0,0 +1,13 @@
+export interface WidgetErrorProps {
+    message?: string;
+    onRetry?: () => void;
+    /** Label for the retry button. Default: "Retry". */
+    retryLabel?: string;
+}
+/**
+ * Error state shown by a widget when its data fetch fails. Authors that
+ * need localized copy should pass `message`/`retryLabel` explicitly — this
+ * component has no i18n dependency.
+ */
+export declare function WidgetError({ message, onRetry, retryLabel }: WidgetErrorProps): import("react").JSX.Element;
+//# sourceMappingURL=widget-error.d.ts.map

package/dist/components/widget-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-error.d.ts","sourceRoot":"","sources":["../../src/components/widget-error.tsx"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,OAAiC,EAAE,OAAO,EAAE,UAAoB,EAAE,EAAE,gBAAgB,+BAsBjH"}

package/dist/components/widget-error.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { AlertCircle } from 'lucide-react';
+import { cn } from '../lib/cn.js';
+/**
+ * Error state shown by a widget when its data fetch fails. Authors that
+ * need localized copy should pass `message`/`retryLabel` explicitly — this
+ * component has no i18n dependency.
+ */
+export function WidgetError({ message = 'Something went wrong.', onRetry, retryLabel = 'Retry' }) {
+    return (_jsxs("div", { className: "flex h-full min-h-[80px] flex-col items-center justify-center gap-3 text-center", children: [_jsx(AlertCircle, { className: "size-8 text-destructive/60" }), _jsx("p", { className: "text-sm text-muted-foreground", children: message }), onRetry && (_jsx("button", { type: "button", onClick: onRetry, className: cn('inline-flex h-6 shrink-0 items-center justify-center gap-1.5 rounded-md border bg-background px-2', 'text-xs font-medium shadow-xs transition-all outline-none', 'hover:bg-accent hover:text-accent-foreground', 'focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50', 'dark:border-input dark:bg-input/30 dark:hover:bg-input/50'), children: retryLabel }))] }));
+}

package/dist/components/widget-shell.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import type { LucideIcon } from 'lucide-react';
+export interface WidgetShellProps {
+    children: ReactNode;
+    className?: string;
+    bare?: boolean;
+    title?: string;
+    icon?: LucideIcon;
+    action?: ReactNode;
+    contentClassName?: string;
+}
+/** Card chrome shared by every widget — built-in or custom. */
+export declare function WidgetShell({ children, className, bare, title, icon: Icon, action, contentClassName, }: WidgetShellProps): import("react").JSX.Element;
+//# sourceMappingURL=widget-shell.d.ts.map

package/dist/components/widget-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-shell.d.ts","sourceRoot":"","sources":["../../src/components/widget-shell.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,SAAS,EACT,IAAY,EACZ,KAAK,EACL,IAAI,EAAE,IAAI,EACV,MAAM,EACN,gBAAgB,GACjB,EAAE,gBAAgB,+BAiClB"}

package/dist/components/widget-shell.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../lib/cn.js';
+/** Card chrome shared by every widget — built-in or custom. */
+export function WidgetShell({ children, className, bare = false, title, icon: Icon, action, contentClassName, }) {
+    if (bare) {
+        return _jsx("div", { className: cn('h-full w-full', className), children: children });
+    }
+    const hasHeader = !!(title || Icon || action);
+    return (_jsxs("div", { className: cn('h-full w-full flex flex-col', 'rounded-2xl border border-neutral-200/80 bg-white/75 backdrop-blur-md overflow-hidden', 'shadow-[0_1px_3px_0_rgb(0,0,0,0.05),0_1px_2px_-1px_rgb(0,0,0,0.04)]', 'transition-all duration-200 hover:shadow-[0_4px_12px_0_rgb(0,0,0,0.08),0_2px_4px_-1px_rgb(0,0,0,0.06)]', 'hover:border-neutral-300/80', 'dark:border-neutral-700/50 dark:bg-card/65 dark:hover:border-neutral-600/60', 'dark:shadow-[0_1px_3px_0_rgb(0,0,0,0.2)] dark:hover:shadow-[0_4px_12px_0_rgb(0,0,0,0.3)]', 'p-5', className), children: [hasHeader && (_jsxs("div", { className: "flex items-center justify-between mb-4 shrink-0", children: [_jsxs("div", { className: "flex items-center gap-2 min-w-0", children: [Icon && _jsx(Icon, { className: "size-4 text-muted-foreground" }), title && _jsx("h3", { className: "font-heading text-sm font-semibold text-foreground truncate", children: title })] }), action && _jsx("div", { className: "flex items-center", children: action })] })), _jsx("div", { className: cn('flex-1 min-h-0', contentClassName), children: children })] }));
+}

package/dist/define-widget.d.ts

@@ -0,0 +1,10 @@
+import type { WidgetDefinition } from './widget-definition.js';
+/**
+ * Identity helper that gives widget authors full type inference for
+ * `defineWidget<TConfig>(...)` while validating the widget `type`.
+ *
+ * - `type` must match {@link WIDGET_TYPE_REGEX}.
+ * - The `core/` prefix is reserved for built-in widgets and is rejected.
+ */
+export declare function defineWidget<TConfig>(definition: WidgetDefinition<TConfig>): WidgetDefinition<TConfig>;
+//# sourceMappingURL=define-widget.d.ts.map

package/dist/define-widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-widget.d.ts","sourceRoot":"","sources":["../src/define-widget.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAE9D;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAYtG"}

package/dist/define-widget.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { WIDGET_TYPE_REGEX } from '@beechcms/core';
+/**
+ * Identity helper that gives widget authors full type inference for
+ * `defineWidget<TConfig>(...)` while validating the widget `type`.
+ *
+ * - `type` must match {@link WIDGET_TYPE_REGEX}.
+ * - The `core/` prefix is reserved for built-in widgets and is rejected.
+ */
+export function defineWidget(definition) {
+    if (definition.type.startsWith('core/')) {
+        throw new Error(`defineWidget: type "${definition.type}" uses the reserved "core/" prefix, which is reserved for built-in widgets.`);
+    }
+    if (!WIDGET_TYPE_REGEX.test(definition.type)) {
+        throw new Error(`defineWidget: type "${definition.type}" is invalid. It must match ${WIDGET_TYPE_REGEX}.`);
+    }
+    return definition;
+}

package/dist/hooks/use-widget-data.d.ts

@@ -0,0 +1,42 @@
+import { type AggregateFormula, type WidgetWindow, type TimeseriesPoint, type DistributionSlice } from '@beechcms/core';
+export interface WidgetAggregateResponse {
+    value: number;
+    window: WidgetWindow;
+}
+export interface WidgetGrowthResponse {
+    current: number;
+    previous: number;
+    percentageChange: number;
+    trend: 'up' | 'down' | 'flat';
+}
+export interface WidgetTimeseriesResponse {
+    points: TimeseriesPoint[];
+}
+export interface WidgetDistributionResponse {
+    slices: DistributionSlice[];
+}
+export interface WidgetListEntry {
+    id: string;
+    slug: string;
+    status: string;
+    createdAt: number;
+    updatedAt: number;
+    [key: string]: unknown;
+}
+export interface WidgetListResponse {
+    entries: WidgetListEntry[];
+    total: number;
+}
+export interface WidgetListParams {
+    limit: number;
+    offset: number;
+    search?: string;
+    orderByColumn?: string;
+    orderDirection?: 'ASC' | 'DESC';
+}
+export declare function useWidgetAggregate(seedSlug: string, formula: AggregateFormula, window: WidgetWindow): import("@tanstack/react-query").UseQueryResult<NoInfer<WidgetAggregateResponse>, Error>;
+export declare function useWidgetGrowth(seedSlug: string, formula: AggregateFormula, window: WidgetWindow): import("@tanstack/react-query").UseQueryResult<NoInfer<WidgetGrowthResponse>, Error>;
+export declare function useWidgetTimeseries(seedSlug: string, formula: AggregateFormula, window: WidgetWindow, groupColumn: string): import("@tanstack/react-query").UseQueryResult<NoInfer<WidgetTimeseriesResponse>, Error>;
+export declare function useWidgetDistribution(seedSlug: string, column: string, window: WidgetWindow, limit: number): import("@tanstack/react-query").UseQueryResult<NoInfer<WidgetDistributionResponse>, Error>;
+export declare function useWidgetList(seedSlug: string, params: WidgetListParams): import("@tanstack/react-query").UseQueryResult<NoInfer<WidgetListResponse>, Error>;
+//# sourceMappingURL=use-widget-data.d.ts.map

package/dist/hooks/use-widget-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-widget-data.d.ts","sourceRoot":"","sources":["../../src/hooks/use-widget-data.ts"],"names":[],"mappings":"AAIA,OAAO,EAAe,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAKpI,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;CACrB;AAOD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,gBAAgB,EAAE,MAAM,CAAA;IACxB,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,eAAe,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,iBAAiB,EAAE,CAAA;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,eAAe,EAAE,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CAChC;AAgFD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,YAAY,2FAQnG;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,YAAY,wFAQhG;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,MAAM,4FASpB;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,8FAQ1G;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,sFAQvE"}

package/dist/hooks/use-widget-data.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { useQuery } from '@tanstack/react-query';
+import { isDateRange } from '@beechcms/core';
+import { useWidgetSdkClient } from '../provider.js';
+const STALE_TIME = 60 * 1000;
+/** Serialises a {@link WidgetWindow} into the route's `window` or `from`/`to` query params. */
+function windowParams(window) {
+    return isDateRange(window) ? { from: window.from, to: window.to } : { window };
+}
+/** Translates the formula into the timeseries route's flat `formula`/`valueColumn` params. */
+function timeseriesFormulaParams(formula) {
+    switch (formula.op) {
+        case 'sum':
+        case 'avg':
+            return { formula: formula.op, valueColumn: formula.column };
+        default:
+            return { formula: 'count' };
+    }
+}
+async function fetchWidgetAggregate(client, seedSlug, formula, window) {
+    const res = await client.get(`/widget/aggregate/${seedSlug}`, {
+        params: { formula: JSON.stringify(formula), ...windowParams(window) },
+    });
+    return res.data;
+}
+async function fetchWidgetGrowth(client, seedSlug, formula, window) {
+    const res = await client.get(`/widget/growth/${seedSlug}`, {
+        params: { formula: JSON.stringify(formula), ...windowParams(window) },
+    });
+    return res.data;
+}
+async function fetchWidgetTimeseries(client, seedSlug, formula, window, groupColumn) {
+    const res = await client.get(`/widget/timeseries/${seedSlug}`, {
+        params: { ...timeseriesFormulaParams(formula), groupColumn, ...windowParams(window) },
+    });
+    return res.data;
+}
+async function fetchWidgetDistribution(client, seedSlug, column, window, limit) {
+    const res = await client.get(`/widget/distribution/${seedSlug}`, {
+        params: { column, limit, ...windowParams(window) },
+    });
+    return res.data;
+}
+async function fetchWidgetList(client, seedSlug, params) {
+    const res = await client.get(`/widget/list/${seedSlug}`, {
+        params: {
+            limit: params.limit,
+            offset: params.offset,
+            search: params.search,
+            orderBy: params.orderByColumn,
+            orderDir: params.orderDirection?.toLowerCase(),
+        },
+    });
+    return res.data;
+}
+export function useWidgetAggregate(seedSlug, formula, window) {
+    const client = useWidgetSdkClient();
+    return useQuery({
+        queryKey: ['widget', 'aggregate', seedSlug, formula, window],
+        queryFn: () => fetchWidgetAggregate(client, seedSlug, formula, window),
+        enabled: !!seedSlug,
+        staleTime: STALE_TIME,
+    });
+}
+export function useWidgetGrowth(seedSlug, formula, window) {
+    const client = useWidgetSdkClient();
+    return useQuery({
+        queryKey: ['widget', 'growth', seedSlug, formula, window],
+        queryFn: () => fetchWidgetGrowth(client, seedSlug, formula, window),
+        enabled: !!seedSlug,
+        staleTime: STALE_TIME,
+    });
+}
+export function useWidgetTimeseries(seedSlug, formula, window, groupColumn) {
+    const client = useWidgetSdkClient();
+    return useQuery({
+        queryKey: ['widget', 'timeseries', seedSlug, formula, window, groupColumn],
+        queryFn: () => fetchWidgetTimeseries(client, seedSlug, formula, window, groupColumn),
+        enabled: !!seedSlug,
+        staleTime: STALE_TIME,
+    });
+}
+export function useWidgetDistribution(seedSlug, column, window, limit) {
+    const client = useWidgetSdkClient();
+    return useQuery({
+        queryKey: ['widget', 'distribution', seedSlug, column, window, limit],
+        queryFn: () => fetchWidgetDistribution(client, seedSlug, column, window, limit),
+        enabled: !!seedSlug && !!column,
+        staleTime: STALE_TIME,
+    });
+}
+export function useWidgetList(seedSlug, params) {
+    const client = useWidgetSdkClient();
+    return useQuery({
+        queryKey: ['widget', 'list', seedSlug, params],
+        queryFn: () => fetchWidgetList(client, seedSlug, params),
+        enabled: !!seedSlug,
+        staleTime: STALE_TIME,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @beechcms/widget-sdk — public contract for custom dashboard widgets.
+ *
+ * Build-time registration only (decision D9): a custom widget is trusted
+ * code compiled into the operator's own dashboard build, not a runtime
+ * plugin. See `docs/custom-widgets.md`.
+ */
+export type { AggregateFormula, TimeWindow, DateRange, WidgetWindow, DistributionSlice, TimeseriesPoint, DashboardWidgetInstance, } from '@beechcms/core';
+export { isDateRange } from '@beechcms/core';
+export * from './widget-definition.js';
+export * from './define-widget.js';
+export * from './provider.js';
+export * from './hooks/use-widget-data.js';
+export { WidgetShell } from './components/widget-shell.js';
+export type { WidgetShellProps } from './components/widget-shell.js';
+export { WidgetEmpty } from './components/widget-empty.js';
+export type { WidgetEmptyProps } from './components/widget-empty.js';
+export { WidgetError } from './components/widget-error.js';
+export type { WidgetErrorProps } from './components/widget-error.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":"AAGA;;;;;;GAMG;AAEH,YAAY,EACV,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,uBAAuB,GACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,4BAA4B,CAAA;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export { isDateRange } from '@beechcms/core';
+export * from './widget-definition.js';
+export * from './define-widget.js';
+export * from './provider.js';
+export * from './hooks/use-widget-data.js';
+export { WidgetShell } from './components/widget-shell.js';
+export { WidgetEmpty } from './components/widget-empty.js';
+export { WidgetError } from './components/widget-error.js';

package/dist/lib/cn.d.ts

@@ -0,0 +1,3 @@
+import { type ClassValue } from 'clsx';
+export declare function cn(...inputs: ClassValue[]): string;
+//# sourceMappingURL=cn.d.ts.map

package/dist/lib/cn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cn.d.ts","sourceRoot":"","sources":["../../src/lib/cn.ts"],"names":[],"mappings":"AAGA,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,MAAM,CAAA;AAG5C,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,UAEzC"}

package/dist/lib/cn.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}

package/dist/provider.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from 'react';
+/**
+ * Minimal HTTP client contract the SDK's data hooks depend on. The
+ * dashboard's Axios instance satisfies this shape — no Axios import lives
+ * in this package.
+ */
+export interface WidgetSdkClient {
+    get<T>(url: string, config?: {
+        params?: Record<string, unknown>;
+    }): Promise<{
+        data: T;
+    }>;
+}
+export interface WidgetSdkProviderProps {
+    client: WidgetSdkClient;
+    children: ReactNode;
+}
+/** Mounted once by the host app, carrying its authenticated HTTP client. */
+export declare function WidgetSdkProvider({ client, children }: WidgetSdkProviderProps): import("react").JSX.Element;
+/** Used by SDK data hooks; throws if rendered outside a {@link WidgetSdkProvider}. */
+export declare function useWidgetSdkClient(): WidgetSdkClient;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAEjE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAA;CACzF;AAID,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,eAAe,CAAA;IACvB,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,sBAAsB,+BAE7E;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,IAAI,eAAe,CAMpD"}

package/dist/provider.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { createContext, useContext } from 'react';
+const WidgetSdkContext = createContext(null);
+/** Mounted once by the host app, carrying its authenticated HTTP client. */
+export function WidgetSdkProvider({ client, children }) {
+    return _jsx(WidgetSdkContext.Provider, { value: client, children: children });
+}
+/** Used by SDK data hooks; throws if rendered outside a {@link WidgetSdkProvider}. */
+export function useWidgetSdkClient() {
+    const client = useContext(WidgetSdkContext);
+    if (!client) {
+        throw new Error('useWidgetSdkClient must be used within a <WidgetSdkProvider>.');
+    }
+    return client;
+}

package/dist/widget-definition.d.ts

@@ -0,0 +1,32 @@
+import type { ComponentType } from 'react';
+import type { z } from 'zod';
+import type { DashboardWidgetInstance } from '@beechcms/core';
+/** Props every registered widget component receives. */
+export interface DashboardWidgetProps<TConfig = unknown> {
+    instance: DashboardWidgetInstance;
+    /** Parsed (and defaulted) via the definition's `configSchema`. */
+    config: TConfig;
+}
+/** Describes a widget type that can be placed on the dashboard. */
+export interface WidgetDefinition<TConfig = unknown> {
+    /** Namespaced type: `core/<name>` for built-ins, npm name for custom. */
+    type: string;
+    /** i18n key for the picker (built-ins); plain string allowed (custom). */
+    labelKey: string;
+    descriptionKey?: string;
+    /** Lucide icon name for the picker. */
+    icon?: string;
+    category: 'stats' | 'charts' | 'content' | 'system' | 'custom';
+    /** Schema with `.catch()`/`.optional()` so partial configs always parse. */
+    configSchema: z.ZodType<TConfig>;
+    defaultConfig: TConfig;
+    component: ComponentType<DashboardWidgetProps<TConfig>>;
+    /** Builder hint: minimum sensible column span out of 12. */
+    minColumnSpan?: number;
+    /** Builder hint: config panel. Absent = "no options" notice. */
+    ConfigPanel?: ComponentType<{
+        config: TConfig;
+        onChange: (next: TConfig) => void;
+    }>;
+}
+//# sourceMappingURL=widget-definition.d.ts.map

package/dist/widget-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-definition.d.ts","sourceRoot":"","sources":["../src/widget-definition.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAE7D,wDAAwD;AACxD,MAAM,WAAW,oBAAoB,CAAC,OAAO,GAAG,OAAO;IACrD,QAAQ,EAAE,uBAAuB,CAAA;IACjC,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB,CAAC,OAAO,GAAG,OAAO;IACjD,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;IAC9D,4EAA4E;IAC5E,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAChC,aAAa,EAAE,OAAO,CAAA;IACtB,SAAS,EAAE,aAAa,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAA;IACvD,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gEAAgE;IAChE,WAAW,CAAC,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAC,CAAA;CACpF"}

package/dist/widget-definition.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@beechcms/widget-sdk",
+  "version": "0.6.0-preview.3",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "@tanstack/react-query": "^5.0.0"
+  },
+  "dependencies": {
+    "@beechcms/core": "^0.6.0-preview.3",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.564.0",
+    "tailwind-merge": "^3.4.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.90.21",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.7",
+    "@vitest/coverage-v8": "^4.1.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w --preserveWatchOutput",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}