@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/stores/widget-store.ts

@@ -0,0 +1,239 @@
+import { create } from 'zustand'
+import type { WidgetState, WidgetStore, ToolRegistration } from './types'
+
+// Track active pipeline executions for cancellation
+const activePipelines = new Map<string, number>()
+
+/**
+ * Zustand store for managing widget state across the application.
+ *
+ * This store provides centralized state management for all widget UI components
+ *
+ * @example
+ * ```tsx
+ * // Import the store
+ * import { useWidgetStore } from '@carto/ps-react-ui/widgets'
+ *
+ * // Use in a component
+ * function MyWidget() {
+ *   const setWidget = useWidgetStore((state) => state.setWidget)
+ *   const widget = useWidgetStore((state) => state.widgets['my-widget'])
+ *
+ *   useEffect(() => {
+ *     setWidget({
+ *       id: 'my-widget',
+ *       type: 'formula',
+ *       title: 'Total Sales',
+ *       isLoading: false,
+ *       visible: true,
+ *       data: { value: 1000, prefix: '$' }
+ *     })
+ *   }, [setWidget])
+ *
+ *   return <div>{widget?.data?.value}</div>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Get widgets by type
+ * const getWidgetsByType = useWidgetStore((state) => state.getWidgetsByType)
+ * const formulaWidgets = getWidgetsByType('formula')
+ * ```
+ */
+export const useWidgetStore = create<WidgetStore>()((set, get) => ({
+  // State
+  widgets: {},
+
+  // Actions
+  setWidget: (id, widget) =>
+    set((state) => {
+      const current =
+        state.widgets[id] ?? ({} as WidgetStore['widgets'][string])
+      return {
+        widgets: {
+          ...state.widgets,
+          [id]: {
+            ...current,
+            ...widget,
+            id,
+          },
+        },
+      }
+    }),
+
+  removeWidget: (id) =>
+    set((state) => {
+      const widgets = { ...state.widgets }
+
+      delete widgets[id]
+
+      return { widgets }
+    }),
+
+  clearWidgets: () =>
+    set({
+      widgets: {},
+    }),
+
+  getWidget: <T extends WidgetState>(id: string) => {
+    return get().widgets[id] as T | undefined
+  },
+
+  registerTool: (widgetId: string, tool: ToolRegistration) =>
+    set((state) => {
+      const current = state.widgets[widgetId] ?? ({} as WidgetState)
+      const registeredTools = current.registeredTools ?? []
+
+      // Remove existing tool with same id if present
+      const filteredTools = registeredTools.filter(
+        (t: ToolRegistration) => t.id !== tool.id,
+      )
+
+      return {
+        widgets: {
+          ...state.widgets,
+          [widgetId]: {
+            ...current,
+            id: widgetId,
+            registeredTools: [...filteredTools, tool],
+          },
+        },
+      }
+    }),
+
+  unregisterTool: (widgetId: string, toolId: string) =>
+    set((state) => {
+      const current = state.widgets[widgetId]
+      if (!current) return state
+
+      const registeredTools = current.registeredTools ?? []
+      const filteredTools = registeredTools.filter(
+        (t: ToolRegistration) => t.id !== toolId,
+      )
+
+      return {
+        widgets: {
+          ...state.widgets,
+          [widgetId]: {
+            ...current,
+            registeredTools: filteredTools,
+          },
+        },
+      }
+    }),
+
+  updateToolConfig: (
+    widgetId: string,
+    toolId: string,
+    config: Record<string, unknown>,
+  ) =>
+    set((state) => {
+      const current = state.widgets[widgetId]
+      if (!current) return state
+
+      const registeredTools = current.registeredTools ?? []
+      const updatedTools = registeredTools.map((tool: ToolRegistration) =>
+        tool.id === toolId
+          ? {
+              ...tool,
+              config: { ...tool.config, ...config },
+            }
+          : tool,
+      )
+
+      return {
+        widgets: {
+          ...state.widgets,
+          [widgetId]: {
+            ...current,
+            registeredTools: updatedTools,
+          },
+        },
+      }
+    }),
+
+  setToolEnabled: (widgetId: string, toolId: string, enabled: boolean) =>
+    set((state) => {
+      const current = state.widgets[widgetId]
+      if (!current) return state
+
+      const registeredTools = current.registeredTools ?? []
+      const updatedTools = registeredTools.map((tool: ToolRegistration) =>
+        tool.id === toolId ? { ...tool, enabled } : tool,
+      )
+
+      return {
+        widgets: {
+          ...state.widgets,
+          [widgetId]: {
+            ...current,
+            registeredTools: updatedTools,
+          },
+        },
+      }
+    }),
+
+  executeToolPipeline: async (widgetId: string, sourceData: unknown) => {
+    const widget = get().widgets[widgetId]
+    if (!widget) return
+
+    // Cancel any in-progress pipeline for this widget
+    const currentExecution = (activePipelines.get(widgetId) ?? 0) + 1
+    activePipelines.set(widgetId, currentExecution)
+
+    const widgetWithTools = widget
+
+    // Build set of tool IDs that should be disabled
+    const disabledToolIds = new Set<string>()
+    for (const tool of widgetWithTools.registeredTools ?? []) {
+      if (tool.enabled && tool.disables) {
+        tool.disables.forEach((id) => disabledToolIds.add(id))
+      }
+    }
+
+    // Sort tools by order and filter enabled only, excluding disabled tools
+    const sortedTools = [...(widgetWithTools.registeredTools ?? [])]
+      .filter((tool) => tool.enabled && !disabledToolIds.has(tool.id))
+      .sort((a, b) => a.order - b.order)
+
+    // Execute pipeline - handle both sync and async tools
+    let transformedData = sourceData
+    for (const tool of sortedTools) {
+      // Check if this execution was cancelled
+      if (activePipelines.get(widgetId) !== currentExecution) {
+        return
+      }
+
+      try {
+        // Call tool function (may return Promise or direct value)
+        transformedData = await tool.fn(transformedData, tool.config)
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(`Tool ${tool.id} failed for widget ${widgetId}:`, error)
+        // Continue with current data to prevent one tool from breaking all
+      }
+    }
+
+    // Single store update with final transformed data
+    set((state) => {
+      const currentWidget = state.widgets[widgetId]
+      if (!currentWidget) return state
+
+      return {
+        widgets: {
+          ...state.widgets,
+          [widgetId]: {
+            ...currentWidget,
+            data: transformedData,
+          },
+        },
+      }
+    })
+
+    // Clean up tracking
+    if (activePipelines.get(widgetId) === currentExecution) {
+      activePipelines.delete(widgetId)
+    }
+  },
+}))

package/src/widgets/subheader/index.ts

@@ -0,0 +1,3 @@
+export { WidgetSubHeader } from './subheader'
+
+export type { WidgetSubHeaderProps } from './types'

package/src/widgets/subheader/style.ts

@@ -0,0 +1,20 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(1),
+    minHeight: ({ spacing }) => spacing(3),
+  },
+  slotLeft: {
+    flexShrink: 0,
+  },
+  slotRight: {
+    flexGrow: 1,
+    display: 'flex',
+    justifyContent: 'flex-end',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(1),
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/subheader/subheader.test.tsx

@@ -0,0 +1,45 @@
+import { describe, test, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { WidgetSubHeader } from './subheader'
+
+describe('WidgetSubHeader', () => {
+  test('renders empty right slot by default', () => {
+    const { container } = render(<WidgetSubHeader />)
+    expect(container.firstChild).toBeTruthy()
+  })
+
+  test('renders slotLeft content', () => {
+    render(<WidgetSubHeader slotLeft={<span>Left Content</span>} />)
+    expect(screen.getByText('Left Content')).toBeTruthy()
+  })
+
+  test('renders slotRight content', () => {
+    render(<WidgetSubHeader slotRight={<span>Right Content</span>} />)
+    expect(screen.getByText('Right Content')).toBeTruthy()
+  })
+
+  test('renders both slots when provided', () => {
+    render(
+      <WidgetSubHeader
+        slotLeft={<span>Left</span>}
+        slotRight={<span>Right</span>}
+      />,
+    )
+    expect(screen.getByText('Left')).toBeTruthy()
+    expect(screen.getByText('Right')).toBeTruthy()
+  })
+
+  test('right slot takes full width when left is empty (flex layout)', () => {
+    const { container } = render(<WidgetSubHeader />)
+    // The right slot should have flexGrow: 1 for full width behavior
+    const rightSlot = container.querySelector('[class*="MuiBox-root"]')
+    expect(rightSlot).toBeTruthy()
+  })
+
+  test('renders with custom sx prop', () => {
+    const { container } = render(
+      <WidgetSubHeader sx={{ backgroundColor: 'red' }} />,
+    )
+    expect(container.firstChild).toBeTruthy()
+  })
+})

package/src/widgets/subheader/subheader.tsx

@@ -0,0 +1,16 @@
+import { Box } from '@mui/material'
+import { styles } from './style'
+import type { WidgetSubHeaderProps } from './types'
+
+export function WidgetSubHeader({
+  slotLeft,
+  slotRight,
+  sx,
+}: WidgetSubHeaderProps) {
+  return (
+    <Box sx={{ ...styles.root, ...sx }}>
+      {slotLeft && <Box sx={styles.slotLeft}>{slotLeft}</Box>}
+      <Box sx={styles.slotRight}>{slotRight}</Box>
+    </Box>
+  )
+}

package/src/widgets/subheader/types.ts

@@ -0,0 +1,11 @@
+import type { SxProps, Theme } from '@mui/material'
+import type { ReactNode } from 'react'
+
+export interface WidgetSubHeaderProps {
+  /** Content for the left slot */
+  slotLeft?: ReactNode
+  /** Content for the right slot*/
+  slotRight?: ReactNode
+  /** Custom styles */
+  sx?: SxProps<Theme>
+}

package/src/widgets/table/components/cell-header.tsx

@@ -0,0 +1,58 @@
+import { TableCell, TableSortLabel, Checkbox } from '@mui/material'
+import type { CellHeaderProps } from '../types'
+
+/**
+ * Table cell header component with optional sorting and select-all checkbox
+ */
+export function CellHeader({
+  column,
+  sortState,
+  onSort,
+  isSelectAll,
+  isAllSelected,
+  isIndeterminate,
+  onSelectAll,
+}: CellHeaderProps) {
+  // Render select-all checkbox
+  if (isSelectAll) {
+    return (
+      <TableCell padding='checkbox'>
+        <Checkbox
+          checked={isAllSelected}
+          indeterminate={isIndeterminate}
+          onChange={onSelectAll}
+          inputProps={{ 'aria-label': 'select all rows' }}
+        />
+      </TableCell>
+    )
+  }
+
+  const isSorted = sortState?.columnId === column.id
+  const sortDirection = isSorted ? sortState.direction : undefined
+
+  // Render sortable column header
+  if (column.sortable && onSort) {
+    return (
+      <TableCell
+        align={column.align}
+        style={{ width: column.width }}
+        sortDirection={sortDirection}
+      >
+        <TableSortLabel
+          active={isSorted}
+          direction={sortDirection ?? 'asc'}
+          onClick={() => onSort(column.id)}
+        >
+          {column.label}
+        </TableSortLabel>
+      </TableCell>
+    )
+  }
+
+  // Render non-sortable column header
+  return (
+    <TableCell align={column.align} style={{ width: column.width }}>
+      {column.label}
+    </TableCell>
+  )
+}

package/src/widgets/table/components/cell.tsx

@@ -0,0 +1,80 @@
+import { TableCell as MuiTableCell, Link, Typography } from '@mui/material'
+import ReactMarkdown, { type Components } from 'react-markdown'
+import type { TableColumn } from '../types'
+import { getCellValue } from '../helpers'
+import type { ReactNode } from 'react'
+
+/**
+ * Props for Cell component
+ */
+export interface CellProps {
+  /** Column definition */
+  column: TableColumn
+  /** Cell value */
+  value: unknown
+}
+
+const DEFAULT_P = ({ children }: { children?: ReactNode }) => (
+  <Typography component='span' variant='body2' color='inherit'>
+    {children}
+  </Typography>
+)
+
+/**
+ * Markdown components for cell content
+ * Uses compact styling suitable for table cells (reusing Note widget pattern)
+ */
+const CELL_MARKDOWN_COMPONENTS: Components = {
+  h1: DEFAULT_P,
+  h2: DEFAULT_P,
+  h3: DEFAULT_P,
+  p: DEFAULT_P,
+  a: ({ children, href }) => {
+    const isExternal = href?.startsWith('http')
+    return (
+      <Link
+        href={href}
+        target={isExternal ? '_blank' : undefined}
+        rel={isExternal ? 'noopener noreferrer' : undefined}
+        color='text.primary'
+        underline='always'
+      >
+        {children}
+      </Link>
+    )
+  },
+  img: () => null,
+  ul: DEFAULT_P,
+  ol: DEFAULT_P,
+  li: DEFAULT_P,
+}
+
+/**
+ * Table cell component with automatic markdown support for string values
+ * Markdown is rendered when the raw value is a string and no formatter is defined.
+ * If a formatter is used, its output is rendered directly without markdown parsing.
+ */
+export function Cell({ column, value }: CellProps) {
+  // If formatter is defined, use it directly without markdown
+  if (column.formatter) {
+    return (
+      <MuiTableCell align={column.align}>
+        {column.formatter(value)}
+      </MuiTableCell>
+    )
+  }
+
+  // For string values without formatter, render as markdown
+  if (typeof value === 'string') {
+    return (
+      <MuiTableCell align={column.align}>
+        <ReactMarkdown components={CELL_MARKDOWN_COMPONENTS}>
+          {value}
+        </ReactMarkdown>
+      </MuiTableCell>
+    )
+  }
+
+  // For non-string values, render directly
+  return <MuiTableCell align={column.align}>{getCellValue(value)}</MuiTableCell>
+}

package/src/widgets/table/components/index.ts

@@ -0,0 +1,4 @@
+export { CellHeader } from './cell-header'
+export { Row } from './row'
+export { Pagination } from './pagination'
+export { PaginationActions } from './pagination-actions'

package/src/widgets/table/components/pagination-actions.tsx

@@ -0,0 +1,67 @@
+import { Box, IconButton } from '@mui/material'
+import FirstPageIcon from '@mui/icons-material/FirstPage'
+import KeyboardArrowLeft from '@mui/icons-material/KeyboardArrowLeft'
+import KeyboardArrowRight from '@mui/icons-material/KeyboardArrowRight'
+import LastPageIcon from '@mui/icons-material/LastPage'
+import type { PaginationActionsProps } from '../types'
+
+/**
+ * Custom pagination actions with first/prev/next/last buttons
+ */
+export function PaginationActions({
+  count,
+  page,
+  rowsPerPage,
+  onPageChange,
+}: PaginationActionsProps) {
+  const lastPage = Math.max(0, Math.ceil(count / rowsPerPage) - 1)
+
+  const handleFirstPage = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onPageChange(event, 0)
+  }
+
+  const handlePreviousPage = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onPageChange(event, page - 1)
+  }
+
+  const handleNextPage = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onPageChange(event, page + 1)
+  }
+
+  const handleLastPage = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onPageChange(event, lastPage)
+  }
+
+  return (
+    <Box sx={{ flexShrink: 0, ml: 2.5 }}>
+      <IconButton
+        onClick={handleFirstPage}
+        disabled={page === 0}
+        aria-label='first page'
+      >
+        <FirstPageIcon />
+      </IconButton>
+      <IconButton
+        onClick={handlePreviousPage}
+        disabled={page === 0}
+        aria-label='previous page'
+      >
+        <KeyboardArrowLeft />
+      </IconButton>
+      <IconButton
+        onClick={handleNextPage}
+        disabled={page >= lastPage}
+        aria-label='next page'
+      >
+        <KeyboardArrowRight />
+      </IconButton>
+      <IconButton
+        onClick={handleLastPage}
+        disabled={page >= lastPage}
+        aria-label='last page'
+      >
+        <LastPageIcon />
+      </IconButton>
+    </Box>
+  )
+}

package/src/widgets/table/components/pagination.tsx

@@ -0,0 +1,41 @@
+import { TablePagination as MuiTablePagination } from '@mui/material'
+import type { PaginationProps } from '../types'
+import { PaginationActions } from './pagination-actions'
+
+/**
+ * Table pagination component
+ */
+export function Pagination({
+  page,
+  rowsPerPage,
+  total,
+  rowsPerPageOptions = [5, 10, 25, 50],
+  onPageChange,
+  onRowsPerPageChange,
+}: PaginationProps) {
+  const handlePageChange = (
+    _event: React.MouseEvent<HTMLButtonElement> | null,
+    newPage: number,
+  ) => {
+    onPageChange(newPage)
+  }
+
+  const handleRowsPerPageChange = (
+    event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>,
+  ) => {
+    onRowsPerPageChange(parseInt(event.target.value, 10))
+  }
+
+  return (
+    <MuiTablePagination
+      component='div'
+      count={total}
+      page={page}
+      rowsPerPage={rowsPerPage}
+      rowsPerPageOptions={rowsPerPageOptions}
+      onPageChange={handlePageChange}
+      onRowsPerPageChange={handleRowsPerPageChange}
+      ActionsComponent={PaginationActions}
+    />
+  )
+}

package/src/widgets/table/components/row.tsx

@@ -0,0 +1,60 @@
+import { TableRow as MuiTableRow, TableCell, Checkbox } from '@mui/material'
+import type { RowProps } from '../types'
+import { Cell } from './cell'
+
+/**
+ * Table row component with selection and hover support
+ */
+export function Row({
+  row,
+  columns,
+  isSelected = false,
+  selectable = false,
+  onClick,
+  onSelect,
+  onMouseEnter,
+  onMouseLeave,
+}: RowProps) {
+  const handleClick = () => {
+    onClick?.(row)
+  }
+
+  const handleCheckboxClick = (event: React.MouseEvent) => {
+    event.stopPropagation()
+    onSelect?.(row)
+  }
+
+  const handleMouseEnter = () => {
+    onMouseEnter?.(row)
+  }
+
+  const handleMouseLeave = () => {
+    onMouseLeave?.()
+  }
+
+  return (
+    <MuiTableRow
+      hover={!!onMouseEnter || !!onMouseLeave || !!onClick}
+      selected={isSelected}
+      onClick={handleClick}
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+      sx={{
+        cursor: onClick ? 'pointer' : 'default',
+      }}
+    >
+      {selectable && (
+        <TableCell padding='checkbox'>
+          <Checkbox
+            checked={isSelected}
+            onClick={handleCheckboxClick}
+            inputProps={{ 'aria-label': `select row ${row.id}` }}
+          />
+        </TableCell>
+      )}
+      {columns.map((column) => (
+        <Cell key={column.id} column={column} value={row[column.id]} />
+      ))}
+    </MuiTableRow>
+  )
+}