@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/no-data/no-data.test.tsx

@@ -0,0 +1,447 @@
+import { render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, test } from 'vitest'
+import { WidgetNoData } from './no-data'
+import { useWidgetStore } from '../stores/widget-store'
+
+describe('WidgetNoData', () => {
+  const widgetId = 'test-no-data-widget'
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  describe('when data is empty', () => {
+    test('renders NoData UI with empty array', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [],
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(
+        screen.getByText(/There are no results for the combination of filters/),
+      ).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('renders NoData UI with null data', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: null,
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('renders NoData UI with undefined data', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: undefined,
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('renders NoData UI with array of empty arrays (CategoryWidget pattern)', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [[], []],
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('renders NoData UI with empty object', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: {},
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+  })
+
+  describe('when data exists', () => {
+    test('renders children with array data', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [{ value: 1 }],
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('renders children with object data', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: { content: 'Hello' },
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('renders children with nested array data', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [[{ name: 'A', value: 1 }]],
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('renders children with primitive data (number)', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: 0,
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('renders children with primitive data (string)', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: 'test',
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('renders children with primitive data (boolean)', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: false,
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+  })
+
+  describe('when loading or fetching', () => {
+    test('renders children when isLoading=true even if data is empty', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: true,
+        isFetching: false,
+        data: [],
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('renders children when isFetching=true even if data is empty', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: true,
+        data: [],
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('renders children when both isLoading and isFetching are true', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: true,
+        isFetching: true,
+        data: [],
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+  })
+
+  describe('customization', () => {
+    test('renders custom title', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [],
+      })
+
+      render(
+        <WidgetNoData id={widgetId} title='No results found'>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No results found')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('renders custom description', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [],
+      })
+
+      render(
+        <WidgetNoData id={widgetId} description='Try adjusting your filters'>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Try adjusting your filters')).toBeTruthy()
+      expect(
+        screen.queryByText(/There are no results for the combination/),
+      ).toBeNull()
+    })
+
+    test('uses custom isEmpty function', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: { customField: 'value' },
+      })
+
+      // Custom isEmpty that treats this object as empty
+      const customIsEmpty = (data: unknown) => {
+        const d = data as { customField: string }
+        return d?.customField === 'value'
+      }
+
+      render(
+        <WidgetNoData id={widgetId} isEmpty={customIsEmpty}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('custom isEmpty returning false renders children', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [],
+      })
+
+      // Custom isEmpty that treats empty array as having data
+      const customIsEmpty = () => false
+
+      render(
+        <WidgetNoData id={widgetId} isEmpty={customIsEmpty}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+  })
+
+  describe('when widget does not exist in store', () => {
+    test('treats as empty and shows NoData UI', () => {
+      // Widget not initialized in store
+      render(
+        <WidgetNoData id='non-existent-widget'>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+  })
+
+  describe('reactivity to store changes', () => {
+    test('updates from NoData to content when data arrives', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [],
+      })
+
+      const { rerender } = render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+
+      // Update with data
+      useWidgetStore.getState().setWidget(widgetId, {
+        data: [{ value: 1 }],
+      })
+
+      // Force rerender to pick up store changes
+      rerender(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('updates from content to NoData when data becomes empty', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [{ value: 1 }],
+      })
+
+      const { rerender } = render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+
+      // Clear data
+      useWidgetStore.getState().setWidget(widgetId, { data: [] })
+
+      // Force rerender to pick up store changes
+      rerender(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('updates from NoData to content when loading starts', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        data: [],
+      })
+
+      const { rerender } = render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+
+      // Start loading
+      useWidgetStore.getState().setWidget(widgetId, { isLoading: true })
+
+      // Force rerender to pick up store changes
+      rerender(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+  })
+})

package/src/widgets/no-data/no-data.tsx

@@ -0,0 +1,116 @@
+import { Box, Typography } from '@mui/material'
+import { useShallow } from 'zustand/shallow'
+import { useWidgetStore } from '../stores/widget-store'
+import type { WidgetNoDataProps } from './types'
+import { styles } from './style'
+
+/**
+ * NoData wrapper component that displays empty state UI when widget has no data
+ *
+ * Integrates with widget store to check loading/fetching state and data availability.
+ * Works in conjunction with SkeletonLoader for complete loading/empty state handling.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <NoData id="my-widget">
+ *   <WidgetContent id="my-widget" />
+ * </NoData>
+ * ```
+ *
+ * @example With SkeletonLoader
+ * ```tsx
+ * <SkeletonLoader id="my-widget" Skeleton={MySkeleton}>
+ *   <NoData id="my-widget">
+ *     <WidgetContent id="my-widget" />
+ *   </NoData>
+ * </SkeletonLoader>
+ * ```
+ *
+ * @example With custom messages
+ * ```tsx
+ * <NoData
+ *   id="my-widget"
+ *   title="No results found"
+ *   description="Try adjusting your filters"
+ * >
+ *   <WidgetContent id="my-widget" />
+ * </NoData>
+ * ```
+ */
+export function WidgetNoData({
+  id,
+  children,
+  title = 'No data available',
+  description = 'There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust filters',
+  isEmpty = defaultIsEmpty,
+}: WidgetNoDataProps) {
+  // Subscribe to widget store with selective subscription for optimal performance
+  const widget = useWidgetStore(
+    useShallow((state) => {
+      const w = state.widgets[id]
+      return {
+        isLoading: w?.isLoading,
+        isFetching: w?.isFetching,
+        data: w?.data,
+      }
+    }),
+  )
+
+  // If loading or fetching, show children
+  // SkeletonLoader handles loading state, this allows proper composition
+  if (widget?.isLoading || widget?.isFetching) {
+    return children
+  }
+
+  // Check if data is empty
+  if (isEmpty(widget?.data)) {
+    return (
+      <Box sx={styles.root}>
+        <Typography variant='body2' color='text.primary'>
+          {title}
+        </Typography>
+        <Typography variant='caption' color='text.secondary'>
+          {description}
+        </Typography>
+      </Box>
+    )
+  }
+
+  // Data exists, render children
+  return children
+}
+
+/**
+ * Default function to determine if data is empty
+ * Handles various data structures commonly used in widgets
+ */
+function defaultIsEmpty(data: unknown): boolean {
+  // Null or undefined
+  if (data == null) {
+    return true
+  }
+
+  // Arrays (most common case)
+  if (Array.isArray(data)) {
+    // Empty array
+    if (data.length === 0) {
+      return true
+    }
+
+    // Array of arrays (CategoryWidget pattern: [[],[]])
+    // Check if all inner arrays are empty
+    if (data.every((item) => Array.isArray(item) && item.length === 0)) {
+      return true
+    }
+
+    return false
+  }
+
+  // Objects
+  if (typeof data === 'object') {
+    return Object.keys(data).length === 0
+  }
+
+  // Primitives (numbers, strings, booleans) are considered valid data
+  return false
+}

package/src/widgets/no-data/style.ts

@@ -0,0 +1,18 @@
+import type { SxProps, Theme } from '@mui/material'
+
+/**
+ * Styles for NoData component matching Figma design specifications
+ * Design reference: node 5781-11028
+ */
+export const styles: Record<string, SxProps<Theme>> = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1, // 8px
+    paddingTop: 1, // 8px
+    paddingBottom: 2, // 16px
+    paddingX: 2, // 16px
+    width: '100%',
+    minHeight: '100%',
+  },
+}

package/src/widgets/no-data/types.ts

@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react'
+import type { WidgetState } from '../stores/types'
+
+/**
+ * Props for the WidgetNoData wrapper component
+ *
+ * @example Basic usage
+ * ```tsx
+ * <WidgetNoData id="my-widget">
+ *   <WidgetContent id="my-widget" />
+ * </WidgetNoData>
+ * ```
+ *
+ * @example With custom messages
+ * ```tsx
+ * <WidgetNoData
+ *   id="my-widget"
+ *   title="No results found"
+ *   description="Try adjusting your filters"
+ * >
+ *   <WidgetContent id="my-widget" />
+ * </WidgetNoData>
+ * ```
+ *
+ * @example With custom isEmpty logic
+ * ```tsx
+ * <WidgetNoData
+ *   id="my-widget"
+ *   isEmpty={(data) => {
+ *     const d = data as CustomData
+ *     return !d?.items?.length
+ *   }}
+ * >
+ *   <WidgetContent id="my-widget" />
+ * </WidgetNoData>
+ * ```
+ */
+export interface WidgetNoDataProps {
+  /**
+   * Widget ID to fetch state from store
+   */
+  id: WidgetState['id']
+
+  /**
+   * Children to render when data is available
+   */
+  children: ReactNode
+
+  /**
+   * Optional custom title for empty state
+   * @default "No data available"
+   */
+  title?: string
+
+  /**
+   * Optional custom description for empty state
+   * @default "There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust filters"
+   */
+  description?: string
+
+  /**
+   * Optional custom function to determine if data is empty
+   * If not provided, uses default isEmpty logic that handles:
+   * - null/undefined → empty
+   * - [] (empty array) → empty
+   * - [[]] (nested empty arrays) → empty
+   * - {} (empty object) → empty
+   * - Primitives → not empty
+   * - Arrays/objects with content → not empty
+   */
+  isEmpty?: (data: unknown) => boolean
+}

package/src/widgets/note/index.ts

@@ -0,0 +1,2 @@
+export { WidgetNote } from './note'
+export type { WidgetNoteProps } from './types'