@open-mercato/core 0.4.2-canary-10c7a8bf2a → 0.4.2-canary-e6bf6a353e

package/src/modules/dashboards/widgets/dashboard/top-customers/widget.client.tsx

@@ -0,0 +1,161 @@
+"use client"
+
+import * as React from 'react'
+import type { DashboardWidgetComponentProps } from '@open-mercato/shared/modules/dashboard/widgets'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { TopNTable, type TopNTableColumn } from '@open-mercato/ui/backend/charts'
+import { DateRangeSelect, type DateRangePreset } from '@open-mercato/ui/backend/date-range'
+import { DEFAULT_SETTINGS, hydrateSettings, type TopCustomersSettings } from './config'
+import type { WidgetDataResponse } from '../../../services/widgetDataService'
+import { formatCurrencySafe } from '../../../lib/formatters'
+
+type CustomerRow = {
+  rank: number
+  customerId: string
+  revenue: number
+}
+
+async function fetchTopCustomersData(settings: TopCustomersSettings): Promise<WidgetDataResponse> {
+  const body = {
+    entityType: 'sales:orders',
+    metric: {
+      field: 'grandTotalGrossAmount',
+      aggregate: 'sum',
+    },
+    groupBy: {
+      field: 'customerEntityId',
+      limit: settings.limit,
+      resolveLabels: true,
+    },
+    dateRange: {
+      field: 'placedAt',
+      preset: settings.dateRange,
+    },
+  }
+
+  const call = await apiCall<WidgetDataResponse>('/api/dashboards/widgets/data', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+
+  if (!call.ok) {
+    const errorMsg = (call.result as Record<string, unknown>)?.error
+    throw new Error(typeof errorMsg === 'string' ? errorMsg : 'Failed to fetch top customers data')
+  }
+
+  return call.result as WidgetDataResponse
+}
+
+function formatCustomerName(name: string | null, unknownLabel: string): string {
+  if (!name) return unknownLabel
+  return name
+}
+
+const TopCustomersWidget: React.FC<DashboardWidgetComponentProps<TopCustomersSettings>> = ({
+  mode,
+  settings = DEFAULT_SETTINGS,
+  onSettingsChange,
+  refreshToken,
+  onRefreshStateChange,
+}) => {
+  const t = useT()
+  const hydrated = React.useMemo(() => hydrateSettings(settings), [settings])
+  const [data, setData] = React.useState<CustomerRow[]>([])
+  const [loading, setLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+
+  const unknownLabel = t('dashboards.analytics.labels.unknown', 'Unknown')
+  const columns: TopNTableColumn<CustomerRow>[] = React.useMemo(
+    () => [
+      {
+        key: 'rank',
+        header: '#',
+        width: '40px',
+      },
+      {
+        key: 'customerId',
+        header: t('dashboards.analytics.widgets.topCustomers.column.customer', 'Customer'),
+        formatter: (value) => formatCustomerName(String(value || ''), unknownLabel),
+      },
+      {
+        key: 'revenue',
+        header: t('dashboards.analytics.widgets.topCustomers.column.revenue', 'Revenue'),
+        align: 'right',
+        formatter: (value: unknown) => formatCurrencySafe(value),
+      },
+    ],
+    [t, unknownLabel],
+  )
+
+  const refresh = React.useCallback(async () => {
+    onRefreshStateChange?.(true)
+    setLoading(true)
+    setError(null)
+    try {
+      const result = await fetchTopCustomersData(hydrated)
+      const tableData: CustomerRow[] = result.data.map((item, index) => ({
+        rank: index + 1,
+        customerId: item.groupLabel || String(item.groupKey || t('dashboards.analytics.labels.unknown', 'Unknown')),
+        revenue: item.value ?? 0,
+      }))
+      setData(tableData)
+    } catch (err) {
+      console.error('Failed to load top customers data', err)
+      setError(t('dashboards.analytics.widgets.topCustomers.error', 'Failed to load data'))
+    } finally {
+      setLoading(false)
+      onRefreshStateChange?.(false)
+    }
+  }, [hydrated, onRefreshStateChange, t])
+
+  React.useEffect(() => {
+    refresh().catch(() => {})
+  }, [refresh, refreshToken])
+
+  if (mode === 'settings') {
+    return (
+      <div className="space-y-4 text-sm">
+        <DateRangeSelect
+          id="top-customers-date-range"
+          label={t('dashboards.analytics.settings.dateRange', 'Date Range')}
+          value={hydrated.dateRange}
+          onChange={(dateRange: DateRangePreset) => onSettingsChange({ ...hydrated, dateRange })}
+        />
+        <div className="space-y-1.5">
+          <label
+            htmlFor="top-customers-limit"
+            className="text-xs font-semibold uppercase text-muted-foreground"
+          >
+            {t('dashboards.analytics.settings.limit', 'Number of items')}
+          </label>
+          <input
+            id="top-customers-limit"
+            type="number"
+            min={1}
+            max={20}
+            className="w-24 rounded-md border px-2 py-1 text-sm focus:border-primary focus:outline-none focus:ring-1 focus:ring-primary"
+            value={hydrated.limit}
+            onChange={(e) => {
+              const next = Number(e.target.value)
+              onSettingsChange({ ...hydrated, limit: Number.isFinite(next) ? next : hydrated.limit })
+            }}
+          />
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <TopNTable
+      data={data}
+      columns={columns}
+      loading={loading}
+      error={error}
+      emptyMessage={t('dashboards.analytics.widgets.topCustomers.empty', 'No customer data for this period')}
+    />
+  )
+}
+
+export default TopCustomersWidget

package/src/modules/dashboards/widgets/dashboard/top-customers/widget.ts

@@ -0,0 +1,24 @@
+import type { DashboardWidgetModule } from '@open-mercato/shared/modules/dashboard/widgets'
+import TopCustomersWidget from './widget.client'
+import { DEFAULT_SETTINGS, hydrateSettings, type TopCustomersSettings } from './config'
+
+const widget: DashboardWidgetModule<TopCustomersSettings> = {
+  metadata: {
+    id: 'dashboards.analytics.topCustomers',
+    title: 'Top Customers',
+    description: 'Top customers by revenue',
+    features: ['analytics.view', 'sales.orders.view', 'customers.people.view'],
+    defaultSize: 'md',
+    defaultEnabled: false,
+    defaultSettings: DEFAULT_SETTINGS,
+    tags: ['analytics', 'sales', 'customers', 'table'],
+    category: 'analytics',
+    icon: 'users',
+    supportsRefresh: true,
+  },
+  Widget: TopCustomersWidget,
+  hydrateSettings,
+  dehydrateSettings: (s) => ({ dateRange: s.dateRange, limit: s.limit }),
+}
+
+export default widget

package/src/modules/dashboards/widgets/dashboard/top-products/config.ts

@@ -0,0 +1,27 @@
+import { type DateRangePreset, isValidDateRangePreset } from '@open-mercato/ui/backend/date-range'
+
+export type ChartLayout = 'horizontal' | 'vertical'
+
+export type TopProductsSettings = {
+  dateRange: DateRangePreset
+  limit: number
+  layout: ChartLayout
+}
+
+export const DEFAULT_SETTINGS: TopProductsSettings = {
+  dateRange: 'this_month',
+  limit: 10,
+  layout: 'horizontal',
+}
+
+export function hydrateSettings(raw: unknown): TopProductsSettings {
+  if (!raw || typeof raw !== 'object') return { ...DEFAULT_SETTINGS }
+  const obj = raw as Record<string, unknown>
+  const parsedLimit = Number(obj.limit)
+  const layout = obj.layout === 'vertical' ? 'vertical' : 'horizontal'
+  return {
+    dateRange: isValidDateRangePreset(obj.dateRange) ? obj.dateRange : DEFAULT_SETTINGS.dateRange,
+    limit: Number.isFinite(parsedLimit) && parsedLimit >= 1 && parsedLimit <= 20 ? Math.floor(parsedLimit) : DEFAULT_SETTINGS.limit,
+    layout,
+  }
+}

package/src/modules/dashboards/widgets/dashboard/top-products/widget.client.tsx

@@ -0,0 +1,181 @@
+"use client"
+
+import * as React from 'react'
+import type { DashboardWidgetComponentProps } from '@open-mercato/shared/modules/dashboard/widgets'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { BarChart, type BarChartDataItem } from '@open-mercato/ui/backend/charts'
+import { DateRangeSelect, InlineDateRangeSelect, type DateRangePreset } from '@open-mercato/ui/backend/date-range'
+import { DEFAULT_SETTINGS, hydrateSettings, type TopProductsSettings } from './config'
+import type { WidgetDataResponse } from '../../../services/widgetDataService'
+import { formatCurrencyCompact } from '../../../lib/formatters'
+
+async function fetchTopProductsData(settings: TopProductsSettings): Promise<WidgetDataResponse> {
+  const body = {
+    entityType: 'sales:order_lines',
+    metric: {
+      field: 'totalGrossAmount',
+      aggregate: 'sum',
+    },
+    groupBy: {
+      field: 'productId',
+      limit: settings.limit,
+      resolveLabels: true,
+    },
+    dateRange: {
+      field: 'createdAt',
+      preset: settings.dateRange,
+    },
+  }
+
+  const call = await apiCall<WidgetDataResponse>('/api/dashboards/widgets/data', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+
+  if (!call.ok) {
+    const errorMsg = (call.result as Record<string, unknown>)?.error
+    throw new Error(typeof errorMsg === 'string' ? errorMsg : 'Failed to fetch top products data')
+  }
+
+  return call.result as WidgetDataResponse
+}
+
+function truncateLabel(
+  label: unknown,
+  t: (key: string, fallback: string) => string,
+  maxLength: number = 20
+): string {
+  if (label == null || label === '') return t('dashboards.analytics.labels.unknownProduct', 'Unknown Product')
+  const labelStr = String(label)
+  // Check for UUID-like strings or meaningless values
+  if (labelStr === '0' || labelStr === 'null' || labelStr === 'undefined') {
+    return t('dashboards.analytics.labels.unknownProduct', 'Unknown Product')
+  }
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(labelStr)) {
+    return t('dashboards.analytics.labels.unnamedProduct', 'Unnamed Product')
+  }
+  if (labelStr.length <= maxLength) return labelStr
+  return labelStr.slice(0, maxLength - 3) + '...'
+}
+
+const TopProductsWidget: React.FC<DashboardWidgetComponentProps<TopProductsSettings>> = ({
+  mode,
+  settings = DEFAULT_SETTINGS,
+  onSettingsChange,
+  refreshToken,
+  onRefreshStateChange,
+}) => {
+  const t = useT()
+  const hydrated = React.useMemo(() => hydrateSettings(settings), [settings])
+  const [data, setData] = React.useState<BarChartDataItem[]>([])
+  const [loading, setLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+  const fetchingRef = React.useRef(false)
+
+  const refresh = React.useCallback(async () => {
+    if (fetchingRef.current) return
+    fetchingRef.current = true
+    onRefreshStateChange?.(true)
+    setLoading(true)
+    setError(null)
+    try {
+      const result = await fetchTopProductsData(hydrated)
+      const chartData = result.data.map((item, index) => ({
+        name: truncateLabel(item.groupLabel ?? item.groupKey ?? `Product ${index + 1}`, t),
+        Revenue: item.value ?? 0,
+      }))
+      setData(chartData)
+    } catch (err) {
+      console.error('Failed to load top products data', err)
+      setError(t('dashboards.analytics.widgets.topProducts.error', 'Failed to load data'))
+    } finally {
+      setLoading(false)
+      onRefreshStateChange?.(false)
+      fetchingRef.current = false
+    }
+  }, [hydrated, onRefreshStateChange, t])
+
+  React.useEffect(() => {
+    refresh().catch(() => {})
+  }, [refresh, refreshToken])
+
+  if (mode === 'settings') {
+    return (
+      <div className="space-y-4 text-sm">
+        <DateRangeSelect
+          id="top-products-date-range"
+          label={t('dashboards.analytics.settings.dateRange', 'Date Range')}
+          value={hydrated.dateRange}
+          onChange={(dateRange: DateRangePreset) => onSettingsChange({ ...hydrated, dateRange })}
+        />
+        <div className="space-y-1.5">
+          <label
+            htmlFor="top-products-limit"
+            className="text-xs font-semibold uppercase text-muted-foreground"
+          >
+            {t('dashboards.analytics.settings.limit', 'Number of items')}
+          </label>
+          <input
+            id="top-products-limit"
+            type="number"
+            min={1}
+            max={20}
+            className="w-24 rounded-md border px-2 py-1 text-sm focus:border-primary focus:outline-none focus:ring-1 focus:ring-primary"
+            value={hydrated.limit}
+            onChange={(e) => {
+              const next = Number(e.target.value)
+              onSettingsChange({ ...hydrated, limit: Number.isFinite(next) ? next : hydrated.limit })
+            }}
+          />
+        </div>
+        <div className="space-y-1.5">
+          <label
+            htmlFor="top-products-layout"
+            className="text-xs font-semibold uppercase text-muted-foreground"
+          >
+            {t('dashboards.analytics.settings.chartLayout', 'Chart Layout')}
+          </label>
+          <select
+            id="top-products-layout"
+            className="w-full rounded-md border bg-background px-2 py-1 text-sm text-foreground focus:border-primary focus:outline-none focus:ring-1 focus:ring-primary"
+            value={hydrated.layout}
+            onChange={(e) => onSettingsChange({ ...hydrated, layout: e.target.value as 'horizontal' | 'vertical' })}
+          >
+            <option value="horizontal">{t('dashboards.analytics.settings.horizontal', 'Horizontal')}</option>
+            <option value="vertical">{t('dashboards.analytics.settings.vertical', 'Vertical')}</option>
+          </select>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex flex-col h-full">
+      <div className="flex justify-end mb-2">
+        <InlineDateRangeSelect
+          value={hydrated.dateRange}
+          onChange={(dateRange) => onSettingsChange({ ...hydrated, dateRange })}
+        />
+      </div>
+      <div className="flex-1 min-h-0">
+        <BarChart
+          data={data}
+          index="name"
+          categories={['Revenue']}
+          categoryLabels={{ Revenue: t('dashboards.analytics.widgets.topCustomers.column.revenue', 'Revenue') }}
+          loading={loading}
+          error={error}
+          layout={hydrated.layout}
+          valueFormatter={formatCurrencyCompact}
+          colors={['emerald']}
+          showLegend={false}
+          emptyMessage={t('dashboards.analytics.widgets.topProducts.empty', 'No product sales data for this period')}
+        />
+      </div>
+    </div>
+  )
+}
+
+export default TopProductsWidget

package/src/modules/dashboards/widgets/dashboard/top-products/widget.ts

@@ -0,0 +1,24 @@
+import type { DashboardWidgetModule } from '@open-mercato/shared/modules/dashboard/widgets'
+import TopProductsWidget from './widget.client'
+import { DEFAULT_SETTINGS, hydrateSettings, type TopProductsSettings } from './config'
+
+const widget: DashboardWidgetModule<TopProductsSettings> = {
+  metadata: {
+    id: 'dashboards.analytics.topProducts',
+    title: 'Top Products',
+    description: 'Top-selling products by revenue',
+    features: ['analytics.view', 'sales.orders.view'],
+    defaultSize: 'md',
+    defaultEnabled: false,
+    defaultSettings: DEFAULT_SETTINGS,
+    tags: ['analytics', 'sales', 'products', 'chart'],
+    category: 'analytics',
+    icon: 'bar-chart-2',
+    supportsRefresh: true,
+  },
+  Widget: TopProductsWidget,
+  hydrateSettings,
+  dehydrateSettings: (s) => ({ dateRange: s.dateRange, limit: s.limit, layout: s.layout }),
+}
+
+export default widget

package/src/modules/sales/analytics.ts

@@ -0,0 +1,64 @@
+import type { AnalyticsModuleConfig } from '@open-mercato/shared/modules/analytics'
+
+export const analyticsConfig: AnalyticsModuleConfig = {
+  entities: [
+    {
+      entityId: 'sales:orders',
+      requiredFeatures: ['sales.orders.view'],
+      entityConfig: {
+        tableName: 'sales_orders',
+        dateField: 'placed_at',
+        defaultScopeFields: ['tenant_id', 'organization_id'],
+      },
+      fieldMappings: {
+        id: { dbColumn: 'id', type: 'uuid' },
+        grandTotalGrossAmount: { dbColumn: 'grand_total_gross_amount', type: 'numeric' },
+        grandTotalNetAmount: { dbColumn: 'grand_total_net_amount', type: 'numeric' },
+        subtotalGrossAmount: { dbColumn: 'subtotal_gross_amount', type: 'numeric' },
+        subtotalNetAmount: { dbColumn: 'subtotal_net_amount', type: 'numeric' },
+        discountTotalAmount: { dbColumn: 'discount_total_amount', type: 'numeric' },
+        taxTotalAmount: { dbColumn: 'tax_total_amount', type: 'numeric' },
+        lineItemCount: { dbColumn: 'line_item_count', type: 'numeric' },
+        status: { dbColumn: 'status', type: 'text' },
+        fulfillmentStatus: { dbColumn: 'fulfillment_status', type: 'text' },
+        paymentStatus: { dbColumn: 'payment_status', type: 'text' },
+        customerEntityId: { dbColumn: 'customer_entity_id', type: 'uuid' },
+        channelId: { dbColumn: 'channel_id', type: 'uuid' },
+        placedAt: { dbColumn: 'placed_at', type: 'timestamp' },
+        currencyCode: { dbColumn: 'currency_code', type: 'text' },
+        shippingAddressSnapshot: { dbColumn: 'shipping_address_snapshot', type: 'jsonb' },
+      },
+      labelResolvers: {
+        customerEntityId: { table: 'customer_entities', idColumn: 'id', labelColumn: 'display_name' },
+        channelId: { table: 'sales_channels', idColumn: 'id', labelColumn: 'name' },
+      },
+    },
+    {
+      entityId: 'sales:order_lines',
+      requiredFeatures: ['sales.orders.view'],
+      entityConfig: {
+        tableName: 'sales_order_lines',
+        dateField: 'created_at',
+        defaultScopeFields: ['tenant_id', 'organization_id'],
+      },
+      fieldMappings: {
+        id: { dbColumn: 'id', type: 'uuid' },
+        totalGrossAmount: { dbColumn: 'total_gross_amount', type: 'numeric' },
+        totalNetAmount: { dbColumn: 'total_net_amount', type: 'numeric' },
+        unitGrossPrice: { dbColumn: 'unit_gross_price', type: 'numeric' },
+        quantity: { dbColumn: 'quantity', type: 'numeric' },
+        productId: { dbColumn: 'product_id', type: 'uuid' },
+        productVariantId: { dbColumn: 'product_variant_id', type: 'uuid' },
+        status: { dbColumn: 'status', type: 'text' },
+        createdAt: { dbColumn: 'created_at', type: 'timestamp' },
+      },
+      labelResolvers: {
+        productId: { table: 'catalog_products', idColumn: 'id', labelColumn: 'title' },
+        productVariantId: { table: 'catalog_product_variants', idColumn: 'id', labelColumn: 'name' },
+      },
+    },
+  ],
+}
+
+export default analyticsConfig
+export const config = analyticsConfig