@ekanos/sdk 0.3.0 → 0.4.0

package/dist/components/widgets/widget-preview-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"widget-preview-provider.js","sourceRoot":"","sources":["../../../src/components/widgets/widget-preview-provider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAkB,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGvE,OAAO,EACL,aAAa,GAId,MAAM,kBAAkB,CAAC;AAqB1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,EACpC,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,WAAW,EACX,SAAS,EACT,KAAK,GAAG,QAAQ,EAChB,aAAa,GAAG,KAAK,EACrB,UAAU,GAAG,KAAK,EAClB,gBAAgB,GAAG,KAAK,EACxB,aAAa,GAAG,KAAK,EACrB,gBAAgB,EAChB,UAAU,EACV,eAAe,GAAG,KAAK,EACvB,MAAM,EACN,QAAQ,GACmB;IAC3B,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC7D,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IAEpD,MAAM,eAAe,GAAG,WAAW,CACjC,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAC3C,EAAE,CACH,CAAC;IAEF,MAAM,YAAY,GAAG,WAAW,CAC9B,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EACxC,EAAE,CACH,CAAC;IAEF,MAAM,KAAK,GAAG,OAAO,CACnB,GAAG,EAAE,CAAC,CAAC;QACL,KAAK,EAAE;YACL,KAAK;YACL,SAAS;YACT,MAAM;YACN,eAAe,EAAE,KAAK;YACtB,UAAU,EAAE,KAAK;SAClB;QACD,OAAO,EAAE,EAAE,eAAe,EAAE,YAAY,EAAE;QAC1C,IAAI,EAAE;YACJ,QAAQ;YACR,KAAK;YACL,QAAQ;YACR,WAAW;YACX,SAAS;YACT,gBAAgB;YAChB,aAAa;YACb,UAAU;YACV,UAAU;YACV,eAAe;YACf,MAAM;SACP;KACF,CAAC,EACF;QACE,eAAe;QACf,UAAU;QACV,SAAS;QACT,SAAS;QACT,WAAW;QACX,MAAM;QACN,aAAa;QACb,UAAU;QACV,gBAAgB;QAChB,MAAM;QACN,KAAK;QACL,QAAQ;QACR,KAAK;QACL,eAAe;QACf,YAAY;QACZ,QAAQ;KACT,CACF,CAAC;IAEF,OAAO,KAAC,aAAa,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAiB,CAAC;AACjE,CAAC","sourcesContent":["'use client';\n\nimport { type ReactNode, useCallback, useMemo, useState } from 'react';\n\nimport type { WidgetAskContext } from '../../types/widget-ask-context';\nimport {\n  WidgetContext,\n  type WidgetContextValue,\n  type WidgetHealth,\n  type WidgetRenderState,\n} from './widget-context';\n\nexport interface WidgetPreviewProviderProps {\n  widgetId: string;\n  title?: string;\n  subtitle?: string;\n  description?: string;\n  className?: string;\n  /** Defaults to `'active'` — the state you almost always want to look at. */\n  state?: WidgetRenderState;\n  isCollapsible?: boolean;\n  isPinnable?: boolean;\n  defaultCollapsed?: boolean;\n  defaultPinned?: boolean;\n  maxContentHeight?: string;\n  askContext?: WidgetAskContext;\n  aiFooterEnabled?: boolean;\n  health?: WidgetHealth;\n  children: ReactNode;\n}\n\n/**\n * Renders a widget outside the Fusion dashboard.\n *\n * `Widget.*` reads everything — render state, collapse/pin, title — from\n * `WidgetContext`, which in production is filled by the host's\n * `DashboardWidgetProvider` (config hierarchy, persistence callbacks, health\n * resolution). None of that exists in a partner's own app, a Storybook story,\n * or a component test, and without SOME provider every `Widget.*` throws. This\n * is that provider: same context value, local state only, nothing persisted.\n *\n * ```tsx\n * <WidgetPreviewProvider widgetId=\"my-widget\" title=\"My widget\">\n *   <MyWidget accountId={accountId} productSlug=\"my-integration\" />\n * </WidgetPreviewProvider>\n * ```\n *\n * Flip `state` to walk every branch your widget renders (`'loading'`,\n * `'error'`, `'inactive'`, `'disabled'`) without faking a network condition.\n */\nexport function WidgetPreviewProvider({\n  widgetId,\n  title,\n  subtitle,\n  description,\n  className,\n  state = 'active',\n  isCollapsible = false,\n  isPinnable = false,\n  defaultCollapsed = false,\n  defaultPinned = false,\n  maxContentHeight,\n  askContext,\n  aiFooterEnabled = false,\n  health,\n  children,\n}: WidgetPreviewProviderProps) {\n  const [collapsed, setCollapsed] = useState(defaultCollapsed);\n  const [pinned, setPinned] = useState(defaultPinned);\n\n  const toggleCollapsed = useCallback(\n    () => setCollapsed((previous) => !previous),\n    [],\n  );\n\n  const togglePinned = useCallback(\n    () => setPinned((previous) => !previous),\n    [],\n  );\n\n  const value = useMemo<WidgetContextValue>(\n    () => ({\n      state: {\n        state,\n        collapsed,\n        pinned,\n        pendingCollapse: false,\n        pendingPin: false,\n      },\n      actions: { toggleCollapsed, togglePinned },\n      meta: {\n        widgetId,\n        title,\n        subtitle,\n        description,\n        className,\n        maxContentHeight,\n        isCollapsible,\n        isPinnable,\n        askContext,\n        aiFooterEnabled,\n        health,\n      },\n    }),\n    [\n      aiFooterEnabled,\n      askContext,\n      className,\n      collapsed,\n      description,\n      health,\n      isCollapsible,\n      isPinnable,\n      maxContentHeight,\n      pinned,\n      state,\n      subtitle,\n      title,\n      toggleCollapsed,\n      togglePinned,\n      widgetId,\n    ],\n  );\n\n  return <WidgetContext value={value}>{children}</WidgetContext>;\n}\n"]}
+{"version":3,"file":"widget-preview-provider.js","sourceRoot":"","sources":["../../../src/components/widgets/widget-preview-provider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAkB,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGvE,OAAO,EACL,aAAa,GAId,MAAM,kBAAkB,CAAC;AAqB1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,EACpC,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,WAAW,EACX,SAAS,EACT,KAAK,GAAG,QAAQ,EAChB,aAAa,GAAG,KAAK,EACrB,UAAU,GAAG,KAAK,EAClB,gBAAgB,GAAG,KAAK,EACxB,aAAa,GAAG,KAAK,EACrB,gBAAgB,EAChB,UAAU,EACV,eAAe,GAAG,KAAK,EACvB,MAAM,EACN,QAAQ,GACmB;IAC3B,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC7D,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IAEpD,MAAM,eAAe,GAAG,WAAW,CACjC,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAC3C,EAAE,CACH,CAAC;IAEF,MAAM,YAAY,GAAG,WAAW,CAC9B,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EACxC,EAAE,CACH,CAAC;IAEF,MAAM,KAAK,GAAG,OAAO,CACnB,GAAG,EAAE,CAAC,CAAC;QACL,KAAK,EAAE;YACL,KAAK;YACL,SAAS;YACT,MAAM;YACN,eAAe,EAAE,KAAK;YACtB,UAAU,EAAE,KAAK;SAClB;QACD,OAAO,EAAE,EAAE,eAAe,EAAE,YAAY,EAAE;QAC1C,IAAI,EAAE;YACJ,QAAQ;YACR,KAAK;YACL,QAAQ;YACR,WAAW;YACX,SAAS;YACT,gBAAgB;YAChB,aAAa;YACb,UAAU;YACV,UAAU;YACV,eAAe;YACf,MAAM;SACP;KACF,CAAC,EACF;QACE,eAAe;QACf,UAAU;QACV,SAAS;QACT,SAAS;QACT,WAAW;QACX,MAAM;QACN,aAAa;QACb,UAAU;QACV,gBAAgB;QAChB,MAAM;QACN,KAAK;QACL,QAAQ;QACR,KAAK;QACL,eAAe;QACf,YAAY;QACZ,QAAQ;KACT,CACF,CAAC;IAEF,OAAO,KAAC,aAAa,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAiB,CAAC;AACjE,CAAC","sourcesContent":["'use client';\n\nimport { type ReactNode, useCallback, useMemo, useState } from 'react';\n\nimport type { WidgetAskContext } from '../../types/widget-ask-context';\nimport {\n  WidgetContext,\n  type WidgetContextValue,\n  type WidgetHealth,\n  type WidgetRenderState,\n} from './widget-context';\n\nexport interface WidgetPreviewProviderProps {\n  widgetId: string;\n  title?: string;\n  subtitle?: string;\n  description?: string;\n  className?: string;\n  /** Defaults to `'active'` — the state you almost always want to look at. */\n  state?: WidgetRenderState;\n  isCollapsible?: boolean;\n  isPinnable?: boolean;\n  defaultCollapsed?: boolean;\n  defaultPinned?: boolean;\n  maxContentHeight?: string;\n  askContext?: WidgetAskContext;\n  aiFooterEnabled?: boolean;\n  health?: WidgetHealth;\n  children: ReactNode;\n}\n\n/**\n * Renders a widget outside the Ekanos dashboard.\n *\n * `Widget.*` reads everything — render state, collapse/pin, title — from\n * `WidgetContext`, which in production is filled by the host's\n * `DashboardWidgetProvider` (config hierarchy, persistence callbacks, health\n * resolution). None of that exists in a partner's own app, a Storybook story,\n * or a component test, and without SOME provider every `Widget.*` throws. This\n * is that provider: same context value, local state only, nothing persisted.\n *\n * ```tsx\n * <WidgetPreviewProvider widgetId=\"my-widget\" title=\"My widget\">\n *   <MyWidget accountId={accountId} productSlug=\"my-integration\" />\n * </WidgetPreviewProvider>\n * ```\n *\n * Flip `state` to walk every branch your widget renders (`'loading'`,\n * `'error'`, `'inactive'`, `'disabled'`) without faking a network condition.\n */\nexport function WidgetPreviewProvider({\n  widgetId,\n  title,\n  subtitle,\n  description,\n  className,\n  state = 'active',\n  isCollapsible = false,\n  isPinnable = false,\n  defaultCollapsed = false,\n  defaultPinned = false,\n  maxContentHeight,\n  askContext,\n  aiFooterEnabled = false,\n  health,\n  children,\n}: WidgetPreviewProviderProps) {\n  const [collapsed, setCollapsed] = useState(defaultCollapsed);\n  const [pinned, setPinned] = useState(defaultPinned);\n\n  const toggleCollapsed = useCallback(\n    () => setCollapsed((previous) => !previous),\n    [],\n  );\n\n  const togglePinned = useCallback(\n    () => setPinned((previous) => !previous),\n    [],\n  );\n\n  const value = useMemo<WidgetContextValue>(\n    () => ({\n      state: {\n        state,\n        collapsed,\n        pinned,\n        pendingCollapse: false,\n        pendingPin: false,\n      },\n      actions: { toggleCollapsed, togglePinned },\n      meta: {\n        widgetId,\n        title,\n        subtitle,\n        description,\n        className,\n        maxContentHeight,\n        isCollapsible,\n        isPinnable,\n        askContext,\n        aiFooterEnabled,\n        health,\n      },\n    }),\n    [\n      aiFooterEnabled,\n      askContext,\n      className,\n      collapsed,\n      description,\n      health,\n      isCollapsible,\n      isPinnable,\n      maxContentHeight,\n      pinned,\n      state,\n      subtitle,\n      title,\n      toggleCollapsed,\n      togglePinned,\n      widgetId,\n    ],\n  );\n\n  return <WidgetContext value={value}>{children}</WidgetContext>;\n}\n"]}

package/dist/components/widgets/widget-state-components.d.ts

@@ -1,5 +1,8 @@
 export declare function WidgetLoadingState(): import("react").JSX.Element;
-export declare function WidgetErrorState(): import("react").JSX.Element;
+export declare function WidgetErrorState({ onRetry, retrying, }: {
+    onRetry?: () => void;
+    retrying?: boolean;
+}): import("react").JSX.Element;
 export declare function WidgetInactiveState(): import("react").JSX.Element;
 export declare function WidgetDataLoading(): import("react").JSX.Element;
 export declare function WidgetDisabledState(): import("react").JSX.Element;

package/dist/components/widgets/widget-state-components.js

@@ -1,17 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@ekanos/ui/button';
 import { Icon } from '@ekanos/ui/icon';
 import { Trans } from '@ekanos/ui/trans';
+import { cn } from '@ekanos/ui/utils';
 export function WidgetLoadingState() {
-    return (_jsxs("div", { className: "flex flex-col items-center justify-center py-8 text-center", children: [_jsx(Icon, { name: "fa-light fa-spinner", className: "text-muted-foreground mb-4 h-8 w-8 animate-spin" }), _jsx("p", { className: "text-muted-foreground text-sm", children: _jsx(Trans, { i18nKey: "dashboard:widgetLoading", defaults: "Loading..." }) })] }));
+    return (_jsxs("div", { className: "flex flex-col items-center justify-center py-8 text-center", children: [_jsx(Icon, { name: "fa-light fa-spinner-third", className: "text-muted-foreground mb-4 h-8 w-8 animate-spin" }), _jsx("p", { className: "text-muted-foreground text-sm", children: _jsx(Trans, { i18nKey: "dashboard:widgetLoading", defaults: "Loading..." }) })] }));
 }
-export function WidgetErrorState() {
-    return (_jsxs("div", { className: "flex flex-col items-center justify-center py-8 text-center", children: [_jsx(Icon, { name: "fa-light fa-circle-exclamation", className: "text-destructive mb-4 h-8 w-8" }), _jsx("p", { className: "text-destructive mb-2 text-sm font-medium", children: _jsx(Trans, { i18nKey: "dashboard:widgetErrorTitle", defaults: "Unable to load data" }) }), _jsx("p", { className: "text-muted-foreground text-xs", children: _jsx(Trans, { i18nKey: "dashboard:widgetErrorBody", defaults: "Please try again later" }) })] }));
+export function WidgetErrorState({ onRetry, retrying = false, }) {
+    return (_jsxs("div", { role: "alert", className: "flex flex-col items-center justify-center gap-3 px-5 py-8 text-center", children: [_jsx("div", { className: "bg-destructive/10 flex h-10 w-10 items-center justify-center rounded-full", children: _jsx(Icon, { name: "fa-light fa-circle-exclamation", className: "text-destructive h-5 w-5", "aria-hidden": true }) }), _jsxs("div", { className: "space-y-1", children: [_jsx("p", { className: "text-foreground text-sm font-medium", children: _jsx(Trans, { i18nKey: "dashboard:widgetErrorTitle", defaults: "Couldn't load this widget" }) }), _jsx("p", { className: "text-muted-foreground text-sm", children: onRetry ? (_jsx(Trans, { i18nKey: "dashboard:widgetErrorBodyRetry", defaults: "Try again, or check back in a few minutes." })) : (_jsx(Trans, { i18nKey: "dashboard:widgetErrorBody", defaults: "Check back in a few minutes." })) })] }), onRetry ? (_jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: onRetry, disabled: retrying, "data-test": "widget-error-retry", children: [_jsx(Icon, { name: "fa-light fa-arrows-rotate", className: cn('h-4 w-4', retrying && 'animate-spin'), "aria-hidden": true }), _jsx(Trans, { i18nKey: "dashboard:widgetRetry", defaults: "Try again" })] })) : null] }));
 }
 export function WidgetInactiveState() {
     return (_jsx("div", { className: "flex flex-col items-center justify-center py-8 text-center", children: _jsx("p", { className: "text-muted-foreground text-sm", children: _jsx(Trans, { i18nKey: "dashboard:widgetInactive", defaults: "Widget inactive" }) }) }));
 }
 export function WidgetDataLoading() {
-    return (_jsx("div", { className: "flex flex-1 items-center justify-center py-12", children: _jsx(Icon, { name: "fa-light fa-spinner", className: "text-muted-foreground h-8 w-8 animate-spin" }) }));
+    return (_jsx("div", { className: "flex flex-1 items-center justify-center py-12", children: _jsx(Icon, { name: "fa-light fa-spinner-third", className: "text-muted-foreground h-8 w-8 animate-spin" }) }));
 }
 export function WidgetDisabledState() {
     return (_jsxs("div", { className: "flex flex-col items-center justify-center py-8 text-center", children: [_jsx(Icon, { name: "fa-light fa-ban", className: "text-muted-foreground mb-4 h-8 w-8" }), _jsx("p", { className: "text-muted-foreground text-sm", children: _jsx(Trans, { i18nKey: "dashboard:widgetDisabled", defaults: "Widget Disabled" }) })] }));

package/dist/components/widgets/widget-state-components.js.map

@@ -1 +1 @@
-{"version":3,"file":"widget-state-components.js","sourceRoot":"","sources":["../../../src/components/widgets/widget-state-components.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,MAAM,UAAU,kBAAkB;IAChC,OAAO,CACL,eAAK,SAAS,EAAC,4DAA4D,aACzE,KAAC,IAAI,IACH,IAAI,EAAC,qBAAqB,EAC1B,SAAS,EAAC,iDAAiD,GAC3D,EACF,YAAG,SAAS,EAAC,+BAA+B,YAC1C,KAAC,KAAK,IAAC,OAAO,EAAC,yBAAyB,EAAC,QAAQ,EAAC,YAAY,GAAG,GAC/D,IACA,CACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CACL,eAAK,SAAS,EAAC,4DAA4D,aACzE,KAAC,IAAI,IACH,IAAI,EAAC,gCAAgC,EACrC,SAAS,EAAC,+BAA+B,GACzC,EACF,YAAG,SAAS,EAAC,2CAA2C,YACtD,KAAC,KAAK,IACJ,OAAO,EAAC,4BAA4B,EACpC,QAAQ,EAAC,qBAAqB,GAC9B,GACA,EACJ,YAAG,SAAS,EAAC,+BAA+B,YAC1C,KAAC,KAAK,IACJ,OAAO,EAAC,2BAA2B,EACnC,QAAQ,EAAC,wBAAwB,GACjC,GACA,IACA,CACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,CACL,cAAK,SAAS,EAAC,4DAA4D,YACzE,YAAG,SAAS,EAAC,+BAA+B,YAC1C,KAAC,KAAK,IAAC,OAAO,EAAC,0BAA0B,EAAC,QAAQ,EAAC,iBAAiB,GAAG,GACrE,GACA,CACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,cAAK,SAAS,EAAC,+CAA+C,YAC5D,KAAC,IAAI,IACH,IAAI,EAAC,qBAAqB,EAC1B,SAAS,EAAC,4CAA4C,GACtD,GACE,CACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,CACL,eAAK,SAAS,EAAC,4DAA4D,aACzE,KAAC,IAAI,IACH,IAAI,EAAC,iBAAiB,EACtB,SAAS,EAAC,oCAAoC,GAC9C,EACF,YAAG,SAAS,EAAC,+BAA+B,YAC1C,KAAC,KAAK,IAAC,OAAO,EAAC,0BAA0B,EAAC,QAAQ,EAAC,iBAAiB,GAAG,GACrE,IACA,CACP,CAAC;AACJ,CAAC","sourcesContent":["import { Icon } from '@ekanos/ui/icon';\nimport { Trans } from '@ekanos/ui/trans';\n\nexport function WidgetLoadingState() {\n  return (\n    <div className=\"flex flex-col items-center justify-center py-8 text-center\">\n      <Icon\n        name=\"fa-light fa-spinner\"\n        className=\"text-muted-foreground mb-4 h-8 w-8 animate-spin\"\n      />\n      <p className=\"text-muted-foreground text-sm\">\n        <Trans i18nKey=\"dashboard:widgetLoading\" defaults=\"Loading...\" />\n      </p>\n    </div>\n  );\n}\n\nexport function WidgetErrorState() {\n  return (\n    <div className=\"flex flex-col items-center justify-center py-8 text-center\">\n      <Icon\n        name=\"fa-light fa-circle-exclamation\"\n        className=\"text-destructive mb-4 h-8 w-8\"\n      />\n      <p className=\"text-destructive mb-2 text-sm font-medium\">\n        <Trans\n          i18nKey=\"dashboard:widgetErrorTitle\"\n          defaults=\"Unable to load data\"\n        />\n      </p>\n      <p className=\"text-muted-foreground text-xs\">\n        <Trans\n          i18nKey=\"dashboard:widgetErrorBody\"\n          defaults=\"Please try again later\"\n        />\n      </p>\n    </div>\n  );\n}\n\nexport function WidgetInactiveState() {\n  return (\n    <div className=\"flex flex-col items-center justify-center py-8 text-center\">\n      <p className=\"text-muted-foreground text-sm\">\n        <Trans i18nKey=\"dashboard:widgetInactive\" defaults=\"Widget inactive\" />\n      </p>\n    </div>\n  );\n}\n\nexport function WidgetDataLoading() {\n  return (\n    <div className=\"flex flex-1 items-center justify-center py-12\">\n      <Icon\n        name=\"fa-light fa-spinner\"\n        className=\"text-muted-foreground h-8 w-8 animate-spin\"\n      />\n    </div>\n  );\n}\n\nexport function WidgetDisabledState() {\n  return (\n    <div className=\"flex flex-col items-center justify-center py-8 text-center\">\n      <Icon\n        name=\"fa-light fa-ban\"\n        className=\"text-muted-foreground mb-4 h-8 w-8\"\n      />\n      <p className=\"text-muted-foreground text-sm\">\n        <Trans i18nKey=\"dashboard:widgetDisabled\" defaults=\"Widget Disabled\" />\n      </p>\n    </div>\n  );\n}\n"]}
+{"version":3,"file":"widget-state-components.js","sourceRoot":"","sources":["../../../src/components/widgets/widget-state-components.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAEtC,MAAM,UAAU,kBAAkB;IAChC,OAAO,CACL,eAAK,SAAS,EAAC,4DAA4D,aACzE,KAAC,IAAI,IACH,IAAI,EAAC,2BAA2B,EAChC,SAAS,EAAC,iDAAiD,GAC3D,EACF,YAAG,SAAS,EAAC,+BAA+B,YAC1C,KAAC,KAAK,IAAC,OAAO,EAAC,yBAAyB,EAAC,QAAQ,EAAC,YAAY,GAAG,GAC/D,IACA,CACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,EAC/B,OAAO,EACP,QAAQ,GAAG,KAAK,GAIjB;IACC,OAAO,CACL,eACE,IAAI,EAAC,OAAO,EACZ,SAAS,EAAC,uEAAuE,aAEjF,cAAK,SAAS,EAAC,2EAA2E,YACxF,KAAC,IAAI,IACH,IAAI,EAAC,gCAAgC,EACrC,SAAS,EAAC,0BAA0B,wBAEpC,GACE,EACN,eAAK,SAAS,EAAC,WAAW,aACxB,YAAG,SAAS,EAAC,qCAAqC,YAChD,KAAC,KAAK,IACJ,OAAO,EAAC,4BAA4B,EACpC,QAAQ,EAAC,2BAA2B,GACpC,GACA,EACJ,YAAG,SAAS,EAAC,+BAA+B,YACzC,OAAO,CAAC,CAAC,CAAC,CACT,KAAC,KAAK,IACJ,OAAO,EAAC,gCAAgC,EACxC,QAAQ,EAAC,4CAA4C,GACrD,CACH,CAAC,CAAC,CAAC,CACF,KAAC,KAAK,IACJ,OAAO,EAAC,2BAA2B,EACnC,QAAQ,EAAC,8BAA8B,GACvC,CACH,GACC,IACA,EACL,OAAO,CAAC,CAAC,CAAC,CACT,MAAC,MAAM,IACL,IAAI,EAAC,QAAQ,EACb,OAAO,EAAC,SAAS,EACjB,IAAI,EAAC,IAAI,EACT,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,eACR,oBAAoB,aAE9B,KAAC,IAAI,IACH,IAAI,EAAC,2BAA2B,EAChC,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,QAAQ,IAAI,cAAc,CAAC,wBAEpD,EACF,KAAC,KAAK,IAAC,OAAO,EAAC,uBAAuB,EAAC,QAAQ,EAAC,WAAW,GAAG,IACvD,CACV,CAAC,CAAC,CAAC,IAAI,IACJ,CACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,CACL,cAAK,SAAS,EAAC,4DAA4D,YACzE,YAAG,SAAS,EAAC,+BAA+B,YAC1C,KAAC,KAAK,IAAC,OAAO,EAAC,0BAA0B,EAAC,QAAQ,EAAC,iBAAiB,GAAG,GACrE,GACA,CACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,cAAK,SAAS,EAAC,+CAA+C,YAC5D,KAAC,IAAI,IACH,IAAI,EAAC,2BAA2B,EAChC,SAAS,EAAC,4CAA4C,GACtD,GACE,CACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,CACL,eAAK,SAAS,EAAC,4DAA4D,aACzE,KAAC,IAAI,IACH,IAAI,EAAC,iBAAiB,EACtB,SAAS,EAAC,oCAAoC,GAC9C,EACF,YAAG,SAAS,EAAC,+BAA+B,YAC1C,KAAC,KAAK,IAAC,OAAO,EAAC,0BAA0B,EAAC,QAAQ,EAAC,iBAAiB,GAAG,GACrE,IACA,CACP,CAAC;AACJ,CAAC","sourcesContent":["import { Button } from '@ekanos/ui/button';\nimport { Icon } from '@ekanos/ui/icon';\nimport { Trans } from '@ekanos/ui/trans';\nimport { cn } from '@ekanos/ui/utils';\n\nexport function WidgetLoadingState() {\n  return (\n    <div className=\"flex flex-col items-center justify-center py-8 text-center\">\n      <Icon\n        name=\"fa-light fa-spinner-third\"\n        className=\"text-muted-foreground mb-4 h-8 w-8 animate-spin\"\n      />\n      <p className=\"text-muted-foreground text-sm\">\n        <Trans i18nKey=\"dashboard:widgetLoading\" defaults=\"Loading...\" />\n      </p>\n    </div>\n  );\n}\n\nexport function WidgetErrorState({\n  onRetry,\n  retrying = false,\n}: {\n  onRetry?: () => void;\n  retrying?: boolean;\n}) {\n  return (\n    <div\n      role=\"alert\"\n      className=\"flex flex-col items-center justify-center gap-3 px-5 py-8 text-center\"\n    >\n      <div className=\"bg-destructive/10 flex h-10 w-10 items-center justify-center rounded-full\">\n        <Icon\n          name=\"fa-light fa-circle-exclamation\"\n          className=\"text-destructive h-5 w-5\"\n          aria-hidden\n        />\n      </div>\n      <div className=\"space-y-1\">\n        <p className=\"text-foreground text-sm font-medium\">\n          <Trans\n            i18nKey=\"dashboard:widgetErrorTitle\"\n            defaults=\"Couldn't load this widget\"\n          />\n        </p>\n        <p className=\"text-muted-foreground text-sm\">\n          {onRetry ? (\n            <Trans\n              i18nKey=\"dashboard:widgetErrorBodyRetry\"\n              defaults=\"Try again, or check back in a few minutes.\"\n            />\n          ) : (\n            <Trans\n              i18nKey=\"dashboard:widgetErrorBody\"\n              defaults=\"Check back in a few minutes.\"\n            />\n          )}\n        </p>\n      </div>\n      {onRetry ? (\n        <Button\n          type=\"button\"\n          variant=\"outline\"\n          size=\"sm\"\n          onClick={onRetry}\n          disabled={retrying}\n          data-test=\"widget-error-retry\"\n        >\n          <Icon\n            name=\"fa-light fa-arrows-rotate\"\n            className={cn('h-4 w-4', retrying && 'animate-spin')}\n            aria-hidden\n          />\n          <Trans i18nKey=\"dashboard:widgetRetry\" defaults=\"Try again\" />\n        </Button>\n      ) : null}\n    </div>\n  );\n}\n\nexport function WidgetInactiveState() {\n  return (\n    <div className=\"flex flex-col items-center justify-center py-8 text-center\">\n      <p className=\"text-muted-foreground text-sm\">\n        <Trans i18nKey=\"dashboard:widgetInactive\" defaults=\"Widget inactive\" />\n      </p>\n    </div>\n  );\n}\n\nexport function WidgetDataLoading() {\n  return (\n    <div className=\"flex flex-1 items-center justify-center py-12\">\n      <Icon\n        name=\"fa-light fa-spinner-third\"\n        className=\"text-muted-foreground h-8 w-8 animate-spin\"\n      />\n    </div>\n  );\n}\n\nexport function WidgetDisabledState() {\n  return (\n    <div className=\"flex flex-col items-center justify-center py-8 text-center\">\n      <Icon\n        name=\"fa-light fa-ban\"\n        className=\"text-muted-foreground mb-4 h-8 w-8\"\n      />\n      <p className=\"text-muted-foreground text-sm\">\n        <Trans i18nKey=\"dashboard:widgetDisabled\" defaults=\"Widget Disabled\" />\n      </p>\n    </div>\n  );\n}\n"]}

package/dist/components/widgets/widget.d.ts

@@ -3,15 +3,35 @@ import type { WidgetAskContext } from '../../types/widget-ask-context.js';
 declare function WidgetCard({ children }: {
     children: ReactNode;
 }): import("react").JSX.Element;
-declare function WidgetHeader({ title, subtitle, description, children, }: {
+declare function WidgetHeader({ title, subtitle, description, menu, children, }: {
     /** Override the provider's title — useful when the rendered name differs from the config name. */
     title?: string;
     /** Override the provider's subtitle — useful for widget-computed values. */
     subtitle?: string;
     /** Override the provider's description — useful for widget-computed values. */
     description?: string;
+    /**
+     * `Widget.MenuItem`s placed at the top of the header's ⋯ menu. Use it for
+     * occasional actions — "Open in QuickBooks", "Open in Outlook" — and keep
+     * `children` for the controls people reach for every visit, like filters.
+     */
+    menu?: ReactNode;
     children?: ReactNode;
 }): import("react").JSX.Element | null;
+/**
+ * One widget-specific entry in the header's ⋯ menu; pass it through
+ * `Widget.Header`'s `menu` prop. With `href` it is a link, opened in a new tab
+ * when `external`; otherwise it runs `onSelect`.
+ */
+declare function WidgetMenuItem({ icon, href, external, onSelect, disabled, children, }: {
+    /** A Font Awesome class, e.g. `fa-light fa-envelope`. */
+    icon?: string;
+    href?: string;
+    external?: boolean;
+    onSelect?: () => void;
+    disabled?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
 /**
  * The standard padded body for content rendered inside `Widget.Active`.
  *
@@ -95,8 +115,22 @@ declare function WidgetHealthFooter(): import("react").JSX.Element | null;
  *   </Widget.DataState>
  * );
  * ```
+ *
+ * Pass `onRefresh`, `refreshing` and `updatedAt` to give the widget the
+ * shared Refresh menu item, a Try again button on its error view, and an
+ * "Updated 3 minutes ago" footer. With TanStack Query:
+ *
+ * ```tsx
+ * <Widget.DataState
+ *   loading={query.isLoading}
+ *   error={query.isError}
+ *   onRefresh={() => void query.refetch()}
+ *   refreshing={query.isFetching}
+ *   updatedAt={query.dataUpdatedAt}
+ * >
+ * ```
  */
-declare function WidgetDataState({ loading, error, inactive, children, }: {
+declare function WidgetDataState({ loading, error, inactive, onRefresh, refreshing, updatedAt, children, }: {
     loading?: boolean;
     error?: boolean;
     /**
@@ -106,11 +140,22 @@ declare function WidgetDataState({ loading, error, inactive, children, }: {
      * over `loading` / `error`.
      */
     inactive?: boolean;
+    /** Reloads the widget's data. */
+    onRefresh?: () => void;
+    /** A reload is in flight. */
+    refreshing?: boolean;
+    /**
+     * When the data on screen last loaded successfully: epoch milliseconds, an
+     * ISO string or a `Date`. `0` means never, which TanStack Query's
+     * `dataUpdatedAt` reports before the first success.
+     */
+    updatedAt?: number | string | Date | null;
     children: ReactNode;
 }): import("react").JSX.Element;
 export declare const Widget: {
     Card: typeof WidgetCard;
     Header: typeof WidgetHeader;
+    MenuItem: typeof WidgetMenuItem;
     DataState: typeof WidgetDataState;
     Active: typeof WidgetActive;
     Body: typeof WidgetBody;

package/dist/components/widgets/widget.js

@@ -1,13 +1,16 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Component, use, useMemo } from 'react';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component, use, useMemo, } from 'react';
+import Link from 'next/link.js';
 import { Button } from '@ekanos/ui/button';
 import { Card, CardContent, CardFooter, CardHeader, CardTitle, } from '@ekanos/ui/card';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from '@ekanos/ui/dropdown-menu';
 import { Icon } from '@ekanos/ui/icon';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, } from '@ekanos/ui/tooltip';
 import { Trans } from '@ekanos/ui/trans';
 import { cn } from '@ekanos/ui/utils';
 import { useAnimatedHeight } from './use-animated-height.js';
+import { useRelativeTime } from './use-relative-time.js';
 import { WidgetAskBar } from './widget-ask-bar.js';
 import { WidgetContext } from './widget-context.js';
 import { WidgetDisabledState, WidgetErrorState, WidgetInactiveState, WidgetLoadingState, } from './widget-state-components.js';
@@ -16,6 +19,11 @@ class WidgetErrorBoundary extends Component {
     constructor() {
         super(...arguments);
         this.state = { hasError: false };
+        this.retry = () => {
+            var _a, _b;
+            (_b = (_a = this.props).onRetry) === null || _b === void 0 ? void 0 : _b.call(_a);
+            this.setState({ hasError: false });
+        };
     }
     static getDerivedStateFromError() {
         return { hasError: true };
@@ -25,7 +33,7 @@ class WidgetErrorBoundary extends Component {
     }
     render() {
         if (this.state.hasError) {
-            return (_jsxs("div", { className: "flex flex-1 flex-col items-center justify-center gap-3 p-8", children: [_jsx("div", { className: "bg-destructive/10 flex h-16 w-16 items-center justify-center rounded-full", children: _jsx(Icon, { name: "fa-light fa-circle-exclamation", className: "text-destructive h-8 w-8" }) }), _jsx("p", { className: "text-muted-foreground text-base font-medium", children: _jsx(Trans, { i18nKey: "dashboard:widgetCrashedTitle", defaults: "Something went wrong" }) }), _jsx("p", { className: "text-muted-foreground max-w-xs text-center text-sm", children: _jsx(Trans, { i18nKey: "dashboard:widgetCrashedBody", defaults: "This widget encountered an error. Try refreshing the page." }) })] }));
+            return (_jsxs("div", { role: "alert", className: "flex flex-1 flex-col items-center justify-center gap-3 px-5 py-8 text-center", children: [_jsx("div", { className: "bg-destructive/10 flex h-10 w-10 items-center justify-center rounded-full", children: _jsx(Icon, { name: "fa-light fa-circle-exclamation", className: "text-destructive h-5 w-5", "aria-hidden": true }) }), _jsxs("div", { className: "space-y-1", children: [_jsx("p", { className: "text-foreground text-sm font-medium", children: _jsx(Trans, { i18nKey: "dashboard:widgetCrashedTitle", defaults: "This widget ran into a problem" }) }), _jsx("p", { className: "text-muted-foreground max-w-xs text-sm", children: _jsx(Trans, { i18nKey: "dashboard:widgetCrashedBody", defaults: "Try again. If it keeps happening, reload the page." }) })] }), _jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: this.retry, "data-test": "widget-crash-retry", children: [_jsx(Icon, { name: "fa-light fa-arrows-rotate", className: "h-4 w-4", "aria-hidden": true }), _jsx(Trans, { i18nKey: "dashboard:widgetRetry", defaults: "Try again" })] })] }));
         }
         return this.props.children;
     }
@@ -35,7 +43,7 @@ function useWidget() {
     const ctx = use(WidgetContext);
     if (!ctx) {
         throw new Error('Widget.* compound components must be rendered inside a widget provider. ' +
-            'On the Fusion dashboard the host supplies one. Anywhere else — your own ' +
+            'On the Ekanos dashboard the host supplies one. Anywhere else — your own ' +
             'app, a story, a component test — wrap the widget in ' +
             "`WidgetPreviewProvider` from '@ekanos/sdk/components'.");
     }
@@ -44,10 +52,10 @@ function useWidget() {
 // ─── Card ───────────────────────────────────────────────────────────────────
 function WidgetCard({ children }) {
     const { meta } = useWidget();
-    return (_jsx(Card, { className: cn(
+    return (_jsxs(Card, { className: cn(
         // Neutralize the shadcn card's own py-6/gap-6 box model — widget
         // chrome owns all vertical spacing via its header/content/footer.
-        'shadow-widget relative flex h-full flex-col gap-0 overflow-hidden rounded-lg border-0 py-0', meta.className), "data-widget-id": meta.widgetId, children: children }));
+        'shadow-widget relative flex h-full flex-col gap-0 overflow-hidden rounded-lg border-0 py-0', meta.className), "data-widget-id": meta.widgetId, children: [children, _jsx(WidgetFreshness, {})] }));
 }
 // ─── Header ─────────────────────────────────────────────────────────────────
 function CollapseButton() {
@@ -55,26 +63,68 @@ function CollapseButton() {
     const { state, actions, meta } = useWidget();
     return (_jsx(Button, { variant: "outline", size: "icon", onClick: actions.toggleCollapsed, disabled: state.pendingCollapse, className: "bg-background dark:bg-secondary relative h-6 w-6 rounded-full before:absolute before:top-1/2 before:left-1/2 before:h-11 before:w-11 before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']", "aria-expanded": !state.collapsed, "aria-controls": `widget-content-${meta.widgetId}`, "aria-label": state.collapsed
             ? `Expand ${(_a = meta.title) !== null && _a !== void 0 ? _a : 'widget'}`
-            : `Collapse ${(_b = meta.title) !== null && _b !== void 0 ? _b : 'widget'}`, children: _jsx(Icon, { name: "fa-light fa-chevron-right", className: cn('h-4 w-4 transition-transform duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none', !state.collapsed && 'rotate-90') }) }));
+            : `Collapse ${(_b = meta.title) !== null && _b !== void 0 ? _b : 'widget'}`, children: _jsx(Icon, { name: "fa-light fa-chevron-right", className: cn('ease-out-strong h-4 w-4 transition-transform duration-200 motion-reduce:transition-none', !state.collapsed && 'rotate-90') }) }));
 }
-function WidgetHeader({ title, subtitle, description, children, }) {
+function WidgetHeader({ title, subtitle, description, menu, children, }) {
     const { meta } = useWidget();
     const effectiveTitle = title !== null && title !== void 0 ? title : meta.title;
     const effectiveSubtitle = subtitle !== null && subtitle !== void 0 ? subtitle : meta.subtitle;
     const effectiveDescription = description !== null && description !== void 0 ? description : meta.description;
     if (!effectiveTitle)
         return null;
-    return (_jsx(CardHeader, { className: "flex-shrink-0 border-b pt-6 pb-4 [.border-b]:pb-4", children: _jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsxs("div", { className: "flex items-center gap-2", children: [meta.isCollapsible ? _jsx(CollapseButton, {}) : null, effectiveDescription ? (_jsxs(_Fragment, { children: [_jsx(TooltipProvider, { children: _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx(CardTitle, { className: "cursor-help text-lg font-semibold" }), children: effectiveTitle }), _jsx(TooltipContent, { children: _jsx("p", { children: effectiveDescription }) })] }) }), _jsx("span", { className: "sr-only", children: effectiveDescription })] })) : (_jsx(CardTitle, { className: "text-lg font-semibold", children: effectiveTitle })), effectiveSubtitle && (_jsx("span", { className: "text-muted-foreground text-base font-medium", children: effectiveSubtitle }))] }), children && (_jsx("div", { className: "flex shrink-0 items-center gap-2", children: children }))] }) }));
+    return (_jsx(CardHeader, { className: "flex-shrink-0 border-b pt-6 pb-4 [.border-b]:pb-4", children: _jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsxs("div", { className: "flex items-center gap-2", children: [meta.isCollapsible ? _jsx(CollapseButton, {}) : null, effectiveDescription ? (_jsxs(_Fragment, { children: [_jsx(TooltipProvider, { children: _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx(CardTitle, { className: "cursor-help text-lg font-semibold" }), children: effectiveTitle }), _jsx(TooltipContent, { children: _jsx("p", { children: effectiveDescription }) })] }) }), _jsx("span", { className: "sr-only", children: effectiveDescription })] })) : (_jsx(CardTitle, { className: "text-lg font-semibold", children: effectiveTitle })), effectiveSubtitle && (_jsx("span", { className: "text-muted-foreground text-base font-medium", children: effectiveSubtitle }))] }), _jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [children, _jsx(WidgetMenu, { items: menu })] })] }) }));
+}
+/**
+ * The actions every widget shares, whatever it renders: open its full
+ * surface, reload it, pin or unpin it. Each item needs something from the host
+ * or the widget's data layer, so the menu shows only what applies — and
+ * nothing at all when nothing does.
+ */
+function WidgetMenu({ items }) {
+    var _a;
+    const { state, actions, meta, data } = useWidget();
+    const refresh = state.state === 'active' ? data === null || data === void 0 ? void 0 : data.refresh : undefined;
+    const hasNavigation = !!items || !!meta.openHref || !!refresh;
+    if (!hasNavigation && !meta.isPinnable)
+        return null;
+    const title = (_a = meta.title) !== null && _a !== void 0 ? _a : 'widget';
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { render: _jsx(Button, { variant: "ghost", size: "icon-sm", className: "text-muted-foreground hover:text-foreground", "aria-label": `Actions for ${title}`, "data-test": `widget-menu-${meta.widgetId}` }), children: _jsx(Icon, { name: "fa-light fa-ellipsis", className: "h-4 w-4", "aria-hidden": true }) }), _jsxs(DropdownMenuContent, { align: "end", className: "min-w-48", children: [items, meta.openHref ? (_jsxs(DropdownMenuItem, { render: _jsx(Link, { href: meta.openHref }), children: [_jsx(Icon, { name: "fa-light fa-arrow-up-right-from-square", "aria-hidden": true }), _jsx(Trans, { i18nKey: "dashboard:widgetOpenInWorkspace", defaults: "Open in workspace" })] })) : null, refresh ? (_jsxs(DropdownMenuItem, { onClick: refresh, disabled: data === null || data === void 0 ? void 0 : data.refreshing, children: [_jsx(Icon, { name: "fa-light fa-arrows-rotate", "aria-hidden": true }), _jsx(Trans, { i18nKey: "dashboard:widgetRefresh", defaults: "Refresh" })] })) : null, hasNavigation && meta.isPinnable ? _jsx(DropdownMenuSeparator, {}) : null, meta.isPinnable ? (_jsxs(DropdownMenuItem, { onClick: actions.togglePinned, disabled: state.pendingPin, "data-test": `widget-menu-pin-${meta.widgetId}`, children: [_jsx(Icon, { name: state.pinned
+                                    ? 'fa-light fa-thumbtack-slash'
+                                    : 'fa-light fa-thumbtack', "aria-hidden": true }), state.pinned ? (_jsx(Trans, { i18nKey: "dashboard:widgetUnpin", defaults: "Unpin from board" })) : (_jsx(Trans, { i18nKey: "dashboard:widgetPin", defaults: "Pin to board" }))] })) : null] })] }));
+}
+/**
+ * One widget-specific entry in the header's ⋯ menu; pass it through
+ * `Widget.Header`'s `menu` prop. With `href` it is a link, opened in a new tab
+ * when `external`; otherwise it runs `onSelect`.
+ */
+function WidgetMenuItem({ icon, href, external = false, onSelect, disabled, children, }) {
+    const link = !href ? undefined : external ? (_jsx("a", { href: href, target: "_blank", rel: "noopener noreferrer" })) : (_jsx(Link, { href: href }));
+    return (_jsxs(DropdownMenuItem, { render: link, onClick: onSelect, disabled: disabled, children: [_jsx(Icon, { name: icon !== null && icon !== void 0 ? icon : (external
+                    ? 'fa-light fa-arrow-up-right-from-square'
+                    : 'fa-light fa-arrow-right'), "aria-hidden": true }), children] }));
+}
+/**
+ * "Updated 3 minutes ago" under an active widget whose data layer reports
+ * when it last loaded (see `Widget.DataState`'s `updatedAt`).
+ */
+function WidgetFreshness() {
+    const { state, data } = useWidget();
+    const updated = useRelativeTime(data === null || data === void 0 ? void 0 : data.updatedAt);
+    if (state.state !== 'active' || state.collapsed || !updated)
+        return null;
+    return (_jsx("div", { className: "text-muted-foreground border-border/60 flex shrink-0 items-center gap-1.5 border-t px-5 py-2.5 text-xs", "aria-live": "polite", children: (data === null || data === void 0 ? void 0 : data.refreshing) ? (_jsxs(_Fragment, { children: [_jsx(Icon, { name: "fa-light fa-arrows-rotate", className: "h-3 w-3 animate-spin", "aria-hidden": true }), _jsx(Trans, { i18nKey: "dashboard:widgetRefreshing", defaults: "Refreshing\u2026" })] })) : (_jsx(Trans, { i18nKey: "dashboard:widgetUpdated", defaults: "Updated {{time}}", values: { time: updated } })) }));
 }
 // ─── State-gated content ────────────────────────────────────────────────────
 function CollapsibleBody({ collapsed, maxContentHeight, widgetId, children, }) {
-    return (_jsx("div", { className: cn('grid min-h-0 flex-1 transition-[grid-template-rows] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none', collapsed ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]'), children: _jsx("div", { className: "min-h-0 overflow-hidden", children: _jsx(CardContent, { id: `widget-content-${widgetId}`, className: cn('flex h-full min-h-0 flex-1 flex-col overflow-y-auto p-0', 'transition-opacity duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none', collapsed ? 'opacity-0' : 'opacity-100'), style: maxContentHeight ? { maxHeight: maxContentHeight } : undefined, children: children }) }) }));
+    return (_jsx("div", { className: cn('ease-out-strong grid min-h-0 flex-1 transition-all duration-300 motion-reduce:transition-none', collapsed ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]'), children: _jsx("div", { className: "min-h-0 overflow-hidden", children: _jsx(CardContent, { id: `widget-content-${widgetId}`, className: cn('flex h-full min-h-0 flex-1 flex-col overflow-y-auto p-0', 'ease-out-strong transition-opacity duration-200 motion-reduce:transition-none', collapsed ? 'opacity-0' : 'opacity-100', maxContentHeight && 'max-h-(--widget-max-height)'), style: maxContentHeight
+                    ? { '--widget-max-height': maxContentHeight }
+                    : undefined, children: children }) }) }));
 }
 function StaticBody({ maxContentHeight, children, }) {
     const { innerRef, height } = useAnimatedHeight();
-    return (_jsx(CardContent, { className: "flex min-h-0 flex-1 flex-col p-0", children: _jsx("div", { className: "overflow-hidden transition-[height] duration-250 ease-out motion-reduce:transition-none", style: {
-                height: height === 'auto' ? 'auto' : height,
-                maxHeight: maxContentHeight !== null && maxContentHeight !== void 0 ? maxContentHeight : undefined,
+    return (_jsx(CardContent, { className: "flex min-h-0 flex-1 flex-col p-0", children: _jsx("div", { className: cn('h-(--body-height) overflow-hidden transition-all duration-250 ease-out motion-reduce:transition-none', maxContentHeight && 'max-h-(--widget-max-height)'), style: {
+                '--body-height': height === 'auto' ? 'auto' : `${height}px`,
+                '--widget-max-height': maxContentHeight,
             }, children: _jsx("div", { ref: innerRef, children: children }) }) }));
 }
 /**
@@ -111,10 +161,10 @@ function WidgetBody({ className, children, }) {
  * `Widget.Body` rather than hand-rolling a `px-*` wrapper.
  */
 function WidgetActive({ children }) {
-    const { state, meta } = useWidget();
+    const { state, meta, data } = useWidget();
     if (state.state !== 'active')
         return null;
-    const body = (_jsx(WidgetErrorBoundary, { widgetId: meta.widgetId, children: children }));
+    const body = (_jsx(WidgetErrorBoundary, { widgetId: meta.widgetId, onRetry: data === null || data === void 0 ? void 0 : data.refresh, children: children }));
     return meta.isCollapsible ? (_jsx(CollapsibleBody, { collapsed: state.collapsed, maxContentHeight: meta.maxContentHeight, widgetId: meta.widgetId, children: body })) : (_jsx(StaticBody, { maxContentHeight: meta.maxContentHeight, children: body }));
 }
 function WidgetLoading({ children }) {
@@ -124,10 +174,10 @@ function WidgetLoading({ children }) {
     return (_jsx(CardContent, { className: "flex min-h-0 flex-1 flex-col p-0", children: children !== null && children !== void 0 ? children : _jsx(WidgetLoadingState, {}) }));
 }
 function WidgetError({ children }) {
-    const { state } = useWidget();
+    const { state, data } = useWidget();
     if (state.state !== 'error')
         return null;
-    return (_jsx(CardContent, { className: "flex min-h-0 flex-1 flex-col p-0", children: children !== null && children !== void 0 ? children : _jsx(WidgetErrorState, {}) }));
+    return (_jsx(CardContent, { className: "flex min-h-0 flex-1 flex-col p-0", children: children !== null && children !== void 0 ? children : (_jsx(WidgetErrorState, { onRetry: data === null || data === void 0 ? void 0 : data.refresh, retrying: data === null || data === void 0 ? void 0 : data.refreshing })) }));
 }
 function WidgetInactive({ children }) {
     const { state } = useWidget();
@@ -146,7 +196,7 @@ function WidgetFooter({ children }) {
     const { state, meta } = useWidget();
     if (state.state !== 'active')
         return null;
-    return (_jsx(CardFooter, { className: cn('flex-shrink-0 pb-6 transition-opacity duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none', meta.isCollapsible && state.collapsed
+    return (_jsx(CardFooter, { className: cn('ease-out-strong flex-shrink-0 pb-6 transition-opacity duration-200 motion-reduce:transition-none', meta.isCollapsible && state.collapsed
             ? 'pointer-events-none opacity-0'
             : 'opacity-100'), "aria-hidden": meta.isCollapsible && state.collapsed, children: children }));
 }
@@ -175,14 +225,22 @@ function WidgetAskFooter({ context }) {
  * instead, so this only fires for the degraded middle ground.
  */
 function WidgetHealthFooter() {
-    var _a;
+    var _a, _b;
     const { state, meta } = useWidget();
+    const lastSuccessAt = toEpochMs((_a = meta.health) === null || _a === void 0 ? void 0 : _a.lastSuccessAt);
+    const lastSynced = useRelativeTime(lastSuccessAt);
     const shouldShow = state.state === 'active' &&
         !state.collapsed &&
-        ((_a = meta.health) === null || _a === void 0 ? void 0 : _a.status) === 'degraded';
+        ((_b = meta.health) === null || _b === void 0 ? void 0 : _b.status) === 'degraded';
     if (!shouldShow)
         return null;
-    return (_jsxs("div", { className: "text-warning border-warning/30 bg-warning/5 flex items-center gap-2 border-t px-4 py-2 text-xs", children: [_jsx(Icon, { name: "fa-light fa-circle-exclamation", className: "h-4 w-4 shrink-0", "aria-hidden": true }), _jsx("span", { children: _jsx(Trans, { i18nKey: "common:integrationHealth.degradedWidgetNotice", defaults: "This integration is degraded \u2014 data may be stale." }) })] }));
+    return (_jsxs("div", { className: "text-warning border-warning/30 bg-warning/5 flex items-center gap-2 border-t px-4 py-2 text-xs", children: [_jsx(Icon, { name: "fa-light fa-circle-exclamation", className: "h-4 w-4 shrink-0", "aria-hidden": true }), _jsx("span", { children: lastSynced ? (_jsx(Trans, { i18nKey: "common:integrationHealth.degradedWidgetNoticeSince", defaults: "Data may be out of date. Last synced {{time}}.", values: { time: lastSynced } })) : (_jsx(Trans, { i18nKey: "common:integrationHealth.degradedWidgetNotice", defaults: "This integration is degraded \u2014 data may be stale." })) })] }));
+}
+function toEpochMs(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    const ms = value instanceof Date ? value.getTime() : new Date(value).getTime();
+    return Number.isFinite(ms) && ms > 0 ? ms : undefined;
 }
 // ─── Data state override ────────────────────────────────────────────────────
 /**
@@ -204,8 +262,22 @@ function WidgetHealthFooter() {
  *   </Widget.DataState>
  * );
  * ```
+ *
+ * Pass `onRefresh`, `refreshing` and `updatedAt` to give the widget the
+ * shared Refresh menu item, a Try again button on its error view, and an
+ * "Updated 3 minutes ago" footer. With TanStack Query:
+ *
+ * ```tsx
+ * <Widget.DataState
+ *   loading={query.isLoading}
+ *   error={query.isError}
+ *   onRefresh={() => void query.refetch()}
+ *   refreshing={query.isFetching}
+ *   updatedAt={query.dataUpdatedAt}
+ * >
+ * ```
  */
-function WidgetDataState({ loading, error, inactive, children, }) {
+function WidgetDataState({ loading, error, inactive, onRefresh, refreshing = false, updatedAt, children, }) {
     const parent = useWidget();
     const overrideState = parent.state.state !== 'active'
         ? parent.state.state
@@ -216,17 +288,33 @@ function WidgetDataState({ loading, error, inactive, children, }) {
                 : error
                     ? 'error'
                     : 'active';
+    const updatedAtMs = toEpochMs(updatedAt);
+    const reportsData = onRefresh !== undefined || updatedAtMs !== undefined;
     const value = useMemo(() => ({
         state: Object.assign(Object.assign({}, parent.state), { state: overrideState }),
         actions: parent.actions,
         meta: parent.meta,
-    }), [parent.state, parent.actions, parent.meta, overrideState]);
+        data: reportsData
+            ? { updatedAt: updatedAtMs, refreshing, refresh: onRefresh }
+            : parent.data,
+    }), [
+        parent.state,
+        parent.actions,
+        parent.meta,
+        parent.data,
+        overrideState,
+        reportsData,
+        updatedAtMs,
+        refreshing,
+        onRefresh,
+    ]);
     return _jsx(WidgetContext, { value: value, children: children });
 }
 // ─── Compound export ────────────────────────────────────────────────────────
 export const Widget = {
     Card: WidgetCard,
     Header: WidgetHeader,
+    MenuItem: WidgetMenuItem,
     DataState: WidgetDataState,
     Active: WidgetActive,
     Body: WidgetBody,