@carto/ps-react-ui 4.7.1 → 4.9.0

package/src/widgets-v2/spread/types.ts

@@ -0,0 +1,27 @@
+import type { FormulaSeries } from '../formula'
+
+/**
+ * A single min/max pair rendered by the Spread widget. Mirrors
+ * {@link FormulaDataItem} — same optional `series`, `prefix`, `suffix`,
+ * `color`, and `note` slots — but the value is a range (`min` … `max`)
+ * rather than a single `value`.
+ */
+export interface SpreadDataItem {
+  min: number
+  max: number
+  prefix?: string
+  suffix?: string
+  /** Override the values' text colour (e.g. `'success.main'`). */
+  color?: string
+  /** Optional series indicator — coloured avatar with first letter of `name`. */
+  series?: FormulaSeries
+  /** Optional caption rendered below the values. */
+  note?: string
+}
+
+/**
+ * Spread widget data — an array of `{min, max, …}` pairs rendered
+ * top-to-bottom, one row per entry. Visual structure matches the Formula
+ * widget so the two can sit side-by-side without style drift.
+ */
+export type SpreadWidgetData = readonly SpreadDataItem[]

package/src/widgets-v2/state/labels.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest'
+import { DEFAULT_STATE_LABELS } from './labels'
+
+const { errorMessage } = DEFAULT_STATE_LABELS
+
+describe('DEFAULT_STATE_LABELS.errorMessage', () => {
+  it('returns Error.message for Error instances', () => {
+    expect(errorMessage(new Error('boom'))).toBe('boom')
+  })
+
+  it('returns the string verbatim when given a string', () => {
+    expect(errorMessage('plain text')).toBe('plain text')
+  })
+
+  it('coerces objects with a message field to that message', () => {
+    expect(errorMessage({ message: 'custom-msg' })).toBe('custom-msg')
+    // Non-string message coerces via String()
+    expect(errorMessage({ message: 42 })).toBe('42')
+  })
+
+  it('falls back to "Unknown error" for unknown shapes', () => {
+    expect(errorMessage(42)).toBe('Unknown error')
+    expect(errorMessage(null)).toBe('Unknown error')
+    expect(errorMessage(undefined)).toBe('Unknown error')
+    expect(errorMessage({ no: 'message-field' })).toBe('Unknown error')
+  })
+
+  it('exposes the default labels as plain strings', () => {
+    expect(DEFAULT_STATE_LABELS.errorTitle).toBe('Something went wrong')
+    expect(DEFAULT_STATE_LABELS.emptyTitle).toBe('No data')
+    expect(typeof DEFAULT_STATE_LABELS.emptyDescription).toBe('string')
+  })
+})

package/src/widgets-v2/state/labels.ts

@@ -0,0 +1,20 @@
+export interface StateLabels {
+  errorTitle: string
+  errorMessage: (error: unknown) => string
+  emptyTitle: string
+  emptyDescription: string
+}
+
+export const DEFAULT_STATE_LABELS: StateLabels = {
+  errorTitle: 'Something went wrong',
+  errorMessage: (error: unknown): string => {
+    if (error instanceof Error) return error.message
+    if (typeof error === 'string') return error
+    if (error && typeof error === 'object' && 'message' in error) {
+      return String((error as { message: unknown }).message)
+    }
+    return 'Unknown error'
+  },
+  emptyTitle: 'No data',
+  emptyDescription: 'Try adjusting filters or wait for data to load.',
+}

package/src/widgets-v2/state/style.ts

@@ -0,0 +1,25 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  emptyRoot: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1,
+    paddingTop: 1,
+    paddingBottom: 2,
+    paddingX: 2,
+    width: '100%',
+    minHeight: '100%',
+  },
+  // Stable wrapper around the success-path children. Real layout (flex
+  // column) so html2canvas has a non-zero bounding rect to rasterise.
+  // `flex: 1; min-height: 0` lets nested scroll regions / fixed-height
+  // chart canvases size correctly inside Widget.Content's flex column.
+  captureBox: {
+    width: '100%',
+    minHeight: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    flex: 1,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/state/widget-state.test.tsx

@@ -0,0 +1,294 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { act, render, screen } from '@testing-library/react'
+import { State } from './widget-state'
+import { Provider } from '../provider/widget-provider'
+import { clearAllWidgetStores, getCaptureEl, getWidgetStore } from '../stores'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+describe('<Widget.State>', () => {
+  it('renders skeleton when isLoading is true (loading wins)', () => {
+    render(
+      <Provider id='s1' data={null} isLoading>
+        <State skeleton={<div data-testid='skeleton' />}>
+          <div>content</div>
+        </State>
+      </Provider>,
+    )
+    expect(screen.getByTestId('skeleton')).toBeTruthy()
+  })
+
+  it('renders default error UI when store error is set', () => {
+    render(
+      <Provider id='s2' data={[1, 2]} error={new Error('boom')}>
+        <State skeleton={null}>
+          <div>content</div>
+        </State>
+      </Provider>,
+    )
+    expect(screen.getByRole('alert').textContent).toContain('boom')
+  })
+
+  it('renders custom fallback when provided', () => {
+    render(
+      <Provider id='s3' data={[1, 2]} error={new Error('x')}>
+        <State
+          skeleton={null}
+          fallback={(e) => <div data-testid='fb'>{e.message}</div>}
+        >
+          <div>content</div>
+        </State>
+      </Provider>,
+    )
+    expect(screen.getByTestId('fb').textContent).toBe('x')
+  })
+
+  it('renders empty UI when rawData is empty (default predicate)', () => {
+    render(
+      <Provider id='s4' data={[]}>
+        <State skeleton={null} labels={{ emptyTitle: 'NOTHING' }}>
+          <div>content</div>
+        </State>
+      </Provider>,
+    )
+    expect(screen.getByText('NOTHING')).toBeTruthy()
+  })
+
+  it('renders content when there is data and no error/loading', () => {
+    render(
+      <Provider id='s5' data={[1]}>
+        <State skeleton={null}>
+          <div data-testid='ok'>content</div>
+        </State>
+      </Provider>,
+    )
+    expect(screen.getByTestId('ok')).toBeTruthy()
+  })
+
+  it('catches a render error in children and routes through the error UI', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    function Bomb(): null {
+      throw new Error('render-throw')
+    }
+    render(
+      <Provider id='s6' data={[1]}>
+        <State skeleton={null}>
+          <Bomb />
+        </State>
+      </Provider>,
+    )
+    expect(screen.getByRole('alert').textContent).toContain('render-throw')
+    spy.mockRestore()
+  })
+
+  it('uses custom fallback for render errors too (single render path)', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    function Bomb(): null {
+      throw new Error('render-throw-2')
+    }
+    render(
+      <Provider id='s7' data={[1]}>
+        <State
+          skeleton={null}
+          fallback={(e) => <div data-testid='rb'>{e.message}</div>}
+        >
+          <Bomb />
+        </State>
+      </Provider>,
+    )
+    expect(screen.getByTestId('rb').textContent).toBe('render-throw-2')
+    spy.mockRestore()
+  })
+
+  it('uses custom isEmpty predicate against rawData', () => {
+    render(
+      <Provider id='s8' data={{ rows: [] }}>
+        <State
+          skeleton={null}
+          labels={{ emptyTitle: 'NO ROWS' }}
+          isEmpty={(d) =>
+            !!d &&
+            typeof d === 'object' &&
+            Array.isArray((d as { rows: unknown[] }).rows) &&
+            (d as { rows: unknown[] }).rows.length === 0
+          }
+        >
+          <div>content</div>
+        </State>
+      </Provider>,
+    )
+    expect(screen.getByText('NO ROWS')).toBeTruthy()
+  })
+
+  it('hides errors during fetch (loading wins)', () => {
+    render(
+      <Provider id='s9' data={[1]} isLoading error={new Error('x')}>
+        <State skeleton={<div data-testid='skel' />}>
+          <div>content</div>
+        </State>
+      </Provider>,
+    )
+    expect(screen.getByTestId('skel')).toBeTruthy()
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+
+  describe('captureEl registry', () => {
+    it('registers the success-path content wrapper as captureEl', () => {
+      render(
+        <Provider id='cap-success' data={[1]}>
+          <State skeleton={null}>
+            <div data-testid='inner'>content</div>
+          </State>
+        </Provider>,
+      )
+      const el = getCaptureEl('cap-success')
+      expect(el).not.toBeNull()
+      // The captured element wraps the rendered content.
+      expect(el?.contains(screen.getByTestId('inner'))).toBe(true)
+    })
+
+    it('does not register a captureEl on the loading branch', () => {
+      render(
+        <Provider id='cap-loading' data={null} isLoading>
+          <State skeleton={<div data-testid='skel' />}>
+            <div>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(getCaptureEl('cap-loading')).toBeNull()
+    })
+
+    it('does not register a captureEl on the error branch', () => {
+      render(
+        <Provider id='cap-error' data={[1]} error={new Error('x')}>
+          <State skeleton={null}>
+            <div>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(getCaptureEl('cap-error')).toBeNull()
+    })
+
+    it('does not register a captureEl on the empty branch', () => {
+      render(
+        <Provider id='cap-empty' data={[]}>
+          <State skeleton={null}>
+            <div>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(getCaptureEl('cap-empty')).toBeNull()
+    })
+
+    it('clears the captureEl on unmount', () => {
+      const { unmount } = render(
+        <Provider id='cap-unmount' data={[1]}>
+          <State skeleton={null}>
+            <div>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(getCaptureEl('cap-unmount')).not.toBeNull()
+      unmount()
+      expect(getCaptureEl('cap-unmount')).toBeNull()
+    })
+  })
+
+  describe('default isEmpty predicate', () => {
+    it('treats an empty object literal as empty', () => {
+      render(
+        <Provider id='isEmpty-empty-obj' data={{}}>
+          <State skeleton={null} labels={{ emptyTitle: 'EMPTY' }}>
+            <div>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(screen.getByText('EMPTY')).toBeTruthy()
+    })
+
+    it('treats an array of empty arrays as empty', () => {
+      render(
+        <Provider id='isEmpty-empty-rows' data={[[], []]}>
+          <State skeleton={null} labels={{ emptyTitle: 'EMPTY-ROWS' }}>
+            <div>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(screen.getByText('EMPTY-ROWS')).toBeTruthy()
+    })
+
+    it('treats a populated array of non-empty sub-arrays as non-empty', () => {
+      render(
+        <Provider id='isEmpty-populated' data={[[1], [2]]}>
+          <State skeleton={null}>
+            <div data-testid='content'>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(screen.getByTestId('content')).toBeTruthy()
+    })
+  })
+
+  describe('toError coercion', () => {
+    it('coerces a string error to an Error instance', () => {
+      render(
+        <Provider id='err-string' data={[1]} error='string-msg'>
+          <State skeleton={null}>
+            <div>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(screen.getByRole('alert').textContent).toContain('string-msg')
+    })
+
+    it('coerces an object-with-message to an Error instance', () => {
+      render(
+        <Provider id='err-objmsg' data={[1]} error={{ message: 'object-msg' }}>
+          <State skeleton={null}>
+            <div>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(screen.getByRole('alert').textContent).toContain('object-msg')
+    })
+
+    it('falls back to "Unknown error" for unknown shapes', () => {
+      render(
+        <Provider id='err-unknown' data={[1]} error={42}>
+          <State skeleton={null}>
+            <div>content</div>
+          </State>
+        </Provider>,
+      )
+      expect(screen.getByRole('alert').textContent).toContain('Unknown error')
+    })
+  })
+
+  it('routes a transform-throw error (set by middleware) through the same UI', () => {
+    render(
+      <Provider id='s10' data={[1, 2]}>
+        <State skeleton={null}>
+          <div>content</div>
+        </State>
+      </Provider>,
+    )
+    // Simulate a transform throw setting the error field
+    act(() => {
+      getWidgetStore('s10').setState({
+        dataTransforms: [
+          {
+            id: 'bad',
+            type: 'data',
+            order: 1,
+            enabled: true,
+            fn: () => {
+              throw new Error('transform-throw')
+            },
+          },
+        ],
+      })
+    })
+    expect(screen.getByRole('alert').textContent).toContain('transform-throw')
+  })
+})

package/src/widgets-v2/state/widget-state.tsx

@@ -0,0 +1,184 @@
+import { Component, useCallback, type ReactNode } from 'react'
+import { Alert, AlertTitle, Box, Typography } from '@mui/material'
+import { setCaptureEl, useWidgetId, useWidgetShallow } from '../stores'
+import { styles } from './style'
+import { DEFAULT_STATE_LABELS, type StateLabels } from './labels'
+
+export interface StateProps {
+  skeleton: ReactNode
+  children: ReactNode
+  /** Override the empty-state predicate. Receives `rawData` (pre-pipeline). */
+  isEmpty?: (rawData: unknown) => boolean
+  /** Render an alternative error UI. When omitted, the default ErrorView is used. */
+  fallback?: (error: Error) => ReactNode
+  labels?: Partial<StateLabels>
+}
+
+interface StateSlice {
+  isLoading: boolean
+  isFetching: boolean
+  error: unknown
+  rawData: unknown
+}
+
+const sliceSelector = (s: {
+  isLoading: boolean
+  isFetching: boolean
+  error: unknown
+  rawData: unknown
+}): StateSlice => ({
+  isLoading: s.isLoading,
+  isFetching: s.isFetching,
+  error: s.error,
+  rawData: s.rawData,
+})
+
+/**
+ * Priority chain: loading → error → empty → content. Both consumer-supplied
+ * errors (set via Provider's `error` prop) and transform-throw errors (set by
+ * the pipeline middleware) flow through the same `error` field. Render-time
+ * errors thrown by `children` are caught by the inlined error boundary and
+ * routed through the same path.
+ */
+export function State({
+  skeleton,
+  children,
+  isEmpty = defaultIsEmpty,
+  fallback,
+  labels,
+}: StateProps) {
+  const id = useWidgetId()
+  const slice = useWidgetShallow(id, sliceSelector)
+  const _labels = { ...DEFAULT_STATE_LABELS, ...labels }
+
+  // Loading wins over everything else (matches v1 — hides errors during fetch).
+  if (slice.isLoading) return <>{skeleton}</>
+
+  // Store-side error (consumer-supplied or transform-throw via middleware).
+  if (slice.error !== undefined && slice.error !== null) {
+    const err = toError(slice.error)
+    return fallback ? (
+      <>{fallback(err)}</>
+    ) : (
+      <ErrorView error={err} labels={_labels} />
+    )
+  }
+
+  // Empty (uses pre-pipeline rawData so a transform that filters everything
+  // doesn't get misclassified as "no data from upstream").
+  if (isEmpty(slice.rawData)) {
+    return <EmptyView labels={_labels} />
+  }
+
+  return (
+    <RenderErrorBoundary fallback={fallback} labels={_labels}>
+      <CaptureBox id={id}>{children}</CaptureBox>
+    </RenderErrorBoundary>
+  )
+}
+
+/**
+ * Wraps the success-path children in a stable flex column whose DOM ref is
+ * registered with the per-widget capture map. Per-widget download configs
+ * feed the wrapper element to `html2canvas` for PNG export. The callback
+ * ref auto-clears (React calls it with `null`) when Widget.State leaves
+ * the success branch or unmounts, so loading / error / empty states
+ * correctly report "no capture target" via `getCaptureEl`.
+ *
+ * Composition convention: render interactive controls that should *not*
+ * appear in the PNG (e.g. `<Widget.Searcher />`) as siblings of
+ * `<Widget.State>` rather than children, so they sit outside this box.
+ */
+function CaptureBox({ id, children }: { id: string; children: ReactNode }) {
+  const setRef = useCallback(
+    (el: HTMLDivElement | null) => setCaptureEl(id, el),
+    [id],
+  )
+  return (
+    <Box ref={setRef} sx={styles.captureBox}>
+      {children}
+    </Box>
+  )
+}
+
+function ErrorView({ error, labels }: { error: Error; labels: StateLabels }) {
+  return (
+    <Alert severity='error'>
+      <AlertTitle>{labels.errorTitle}</AlertTitle>
+      {labels.errorMessage(error)}
+    </Alert>
+  )
+}
+
+function EmptyView({ labels }: { labels: StateLabels }) {
+  return (
+    <Box sx={styles.emptyRoot}>
+      <Typography variant='body2' color='text.primary'>
+        {labels.emptyTitle}
+      </Typography>
+      <Typography variant='caption' color='text.secondary'>
+        {labels.emptyDescription}
+      </Typography>
+    </Box>
+  )
+}
+
+interface BoundaryProps {
+  fallback?: (error: Error) => ReactNode
+  labels: StateLabels
+  children: ReactNode
+}
+
+interface BoundaryState {
+  error: Error | null
+}
+
+class RenderErrorBoundary extends Component<BoundaryProps, BoundaryState> {
+  override state: BoundaryState = { error: null }
+
+  static getDerivedStateFromError(error: Error): BoundaryState {
+    return { error }
+  }
+
+  override componentDidCatch(error: Error): void {
+    // eslint-disable-next-line no-console
+    console.error('[widgets-v2] Render error in <Widget.State> child:', error)
+  }
+
+  override render(): ReactNode {
+    const { error } = this.state
+    if (error !== null) {
+      const { fallback, labels } = this.props
+      return fallback ? (
+        fallback(error)
+      ) : (
+        <ErrorView error={error} labels={labels} />
+      )
+    }
+    return this.props.children
+  }
+}
+
+function defaultIsEmpty(rawData: unknown): boolean {
+  if (rawData == null) return true
+  if (Array.isArray(rawData)) {
+    if (rawData.length === 0) return true
+    if (rawData.every((item) => Array.isArray(item) && item.length === 0)) {
+      return true
+    }
+    return false
+  }
+  if (typeof rawData === 'object' && Object.keys(rawData).length === 0) {
+    return true
+  }
+  return false
+}
+
+function toError(value: unknown): Error {
+  if (value instanceof Error) return value
+  if (typeof value === 'string') return new Error(value)
+  if (value && typeof value === 'object' && 'message' in value) {
+    return new Error(String((value as { message: unknown }).message))
+  }
+  return new Error('Unknown error')
+}

package/src/widgets-v2/stores/index.ts

@@ -0,0 +1,49 @@
+export type {
+  TransformType,
+  TransformDescriptor,
+  TransformFn,
+  Transform,
+  TransformPair,
+  WidgetState,
+  WidgetInit,
+  WidgetStoreApi,
+} from './types'
+
+export { applyTransforms, upsertTransform, removeTransform } from './transforms'
+
+export { pipelineMiddleware } from './pipeline-middleware'
+
+export { WidgetContext, useWidgetId } from './widget-context'
+
+export {
+  getWidgetStore,
+  hasWidgetStore,
+  deleteWidgetStore,
+  resetWidgetStore,
+  clearAllWidgetStores,
+  registerWidgetStore,
+  unregisterWidgetStore,
+  setWidgetStoreEntry,
+  createWidgetStore,
+  useWidget,
+  useWidgetShallow,
+  setCaptureEl,
+  getCaptureEl,
+  clearAllCaptureEls,
+  setEchartInstance,
+  getEchartInstance,
+  subscribeEchartInstance,
+  clearAllEchartInstances,
+  __debugListWidgetStores,
+} from './widget-store-registry'
+
+export { useEchartInstance } from './use-echart-instance'
+
+export {
+  useTransform,
+  useSingleTransform,
+  type UseTransformOptions,
+  type TransformControls,
+} from './use-transform'
+
+export { useTransformEnabled } from './use-transform-enabled'