@carto/ps-react-ui 5.0.0-widgets.9 → 5.0.0

package/src/widgets/README.md

@@ -0,0 +1,277 @@
+# Widgets Architecture
+
+> **⚠️ Project-Side Implementation Required**
+>
+> Starting with v4.3.x, widgets should be implemented on the **project side** using the building blocks provided by this library. The library exports UI components, configuration helpers, and state management hooks—you compose them in your project to create complete widgets.
+>
+> **Benefits:**
+>
+> - Full customization tailored to your project's specific needs
+> - Direct integration with your data sources and state management
+> - Independent updates without waiting for library releases
+> - Include only the widget features you actually need
+>
+> **See the internal Storybook for complete implementation examples** of all widget types (Bar, Pie, Histogram, Timeseries, Scatterplot, Formula, etc.).
+
+---
+
+This directory contains the CARTO PS widget system with an optimized architecture for code reuse and maintainability.
+
+## Directory Structure
+
+```
+widgets/
+├── utils/              # Shared utilities (exported as @carto/ps-react-ui/widgets/utils)
+│   ├── chart-config/     # Chart widget configuration utilities
+│   │   ├── config-factory.ts     # Factory for creating chart widget configs
+│   │   ├── csv-modifiers.ts      # CSV export utilities
+│   │   ├── option-builders.ts    # EChart option builders
+│   │   └── index.ts             # Exports
+│   └── skeleton/         # Shared skeleton styles
+│       ├── styles.ts            # Base skeleton container styles
+│       └── index.ts            # Exports
+├── bar/                  # Bar chart widget
+├── histogram/            # Histogram widget
+├── pie/                  # Pie chart widget
+├── scatterplot/          # Scatterplot widget
+├── timeseries/           # Timeseries/line chart widget
+├── formula/              # Formula/KPI widget
+├── note/                 # Note widget
+├── markdown/             # Markdown renderer
+├── echart/               # Base EChart component
+├── wrapper/              # Widget wrapper with header/actions
+├── actions/              # Download, fullscreen actions
+├── config-loader/        # Config loading system
+├── skeleton-loader/      # Skeleton components
+├── stores/               # Zustand widget state
+├── loader/               # WidgetLoader container
+└── widget/               # Main widget orchestrator
+```
+
+## Shared Utilities (`utils/`)
+
+The `utils` directory contains shared utilities used by multiple widgets. These are exported as `@carto/ps-react-ui/widgets/utils`.
+
+### Chart Config Factory
+
+**File:** `utils/chart-config/config-factory.ts`
+
+Creates standardized chart widget configurations, eliminating code duplication.
+
+**Example:**
+
+```typescript
+import {
+  createChartWidgetConfig,
+  flattenObjectArrayToCSV,
+} from '../utils/chart-config'
+
+export const myWidgetConfig = createChartWidgetConfig({
+  type: 'my-widget',
+  getOptions: ({ data, theme }) => ({
+    // EChart configuration
+    legend: buildLegendConfig({ hasLegend }),
+    // ...
+  }),
+  csvModifier: (data) => flattenObjectArrayToCSV(data),
+})
+```
+
+### CSV Modifiers
+
+**File:** `utils/chart-config/csv-modifiers.ts`
+
+- `flattenObjectArrayToCSV()` - For widgets with object-based data (bar, pie, histogram, timeseries)
+- `scatterplotDataToCSV()` - For scatterplot with array-based data
+
+### EChart Option Builders
+
+**File:** `utils/chart-config/option-builders.ts`
+
+- `buildLegendConfig({ hasLegend, labelFormatter? })` - Standard legend configuration
+- `buildGridConfig(hasLegend, theme, additionalConfig?)` - Grid with legend-aware spacing
+- `createTooltipPositioner(theme)` - Tooltip positioning with overflow handling
+
+### Skeleton Styles
+
+**File:** `utils/skeleton/styles.ts`
+
+- `baseSkeletonStyles.graph.container` - Base container styles for all chart skeletons
+
+## Creating a New Chart Widget
+
+1. **Create widget directory:**
+
+   ```bash
+   mkdir src/widgets/my-widget
+   ```
+
+2. **Create `types.ts`:**
+
+   ```typescript
+   import type { BaseWidgetProps } from '../widget/types'
+   import type { BaseConfig } from '../config-loader'
+   import type {
+     EchartWidgetConfig,
+     EchartWidgetData,
+     EchartWidgetState,
+   } from '../echart'
+
+   export interface MyWidgetProps extends BaseWidgetProps<MyWidgetConfig> {
+     type: 'my-widget'
+     data: MyWidgetData | undefined
+   }
+
+   export type MyWidgetData = EchartWidgetData
+   export type MyWidgetState = EchartWidgetState
+   export type MyWidgetConfig = MyConfig &
+     EchartWidgetConfig & { type: MyWidgetProps['type'] }
+
+   export interface MyConfig extends Omit<BaseConfig, 'data'> {
+     data?: MyWidgetData
+   }
+   ```
+
+3. **Create `config.ts` using shared factory:**
+
+   ```typescript
+   import type { EchartOptionsProps } from '../echart'
+   import type { MyConfig, MyWidgetConfig, MyWidgetData } from './types'
+   import {
+     createChartWidgetConfig,
+     flattenObjectArrayToCSV,
+     buildLegendConfig,
+     buildGridConfig,
+   } from '../utils/chart-config'
+
+   export const myWidgetConfig = createChartWidgetConfig<
+     MyWidgetData,
+     MyConfig
+   >({
+     type: 'my-widget',
+     getOptions,
+     csvModifier: (data) => flattenObjectArrayToCSV(data),
+   })
+
+   function getOptions({
+     data = [],
+     theme,
+   }: Omit<MyConfig, 'refUI'>): EchartOptionsProps {
+     const hasLegend = (data?.length ?? 0) > 1
+     return {
+       legend: buildLegendConfig({ hasLegend }),
+       grid: buildGridConfig(hasLegend, theme),
+       // ... widget-specific configuration
+     }
+   }
+   ```
+
+4. **Create `skeleton.tsx` and `style.ts`:**
+
+   ```typescript
+   // style.ts
+   import type { SxProps, Theme } from '@mui/material'
+   import { baseSkeletonStyles } from '../utils/skeleton'
+
+   export const styles = {
+     skeleton: {
+       graph: baseSkeletonStyles.graph,
+       // Add widget-specific styles here
+     },
+   } satisfies Record<string, SxProps<Theme>>
+   ```
+
+5. **Create `index.ts`:**
+
+   ```typescript
+   export type {
+     MyWidgetProps,
+     MyWidgetData,
+     MyWidgetState,
+     MyWidgetConfig,
+     MyConfig,
+   } from './types'
+   export { myWidgetConfig } from './config'
+   export { MyWidgetSkeleton as Skeleton } from './skeleton'
+   ```
+
+6. **Run build automation:**
+
+   ```bash
+   pnpm generate:exports
+   ```
+
+   This will automatically:
+   - Add the widget to vite.config.ts entry points
+   - Add the widget to package.json exports
+   - Validate all exports
+
+## Build Automation
+
+### Scripts
+
+- `pnpm exports:validate` - Validate all package.json exports have corresponding source files
+
+### How It Works
+
+**package.json is the source of truth!**
+
+The `scripts/generate-widget-config.ts` script:
+
+1. Reads widget exports from `package.json`
+2. Converts export paths to source file paths
+3. Generates vite entry points dynamically
+4. Validates that all exports have corresponding source files
+
+The script uses **Node 22's native TypeScript support** with the `--experimental-strip-types` flag, so no compilation step is needed!
+
+### Adding a New Widget
+
+1. **Create widget folder and files:**
+
+   ```bash
+   mkdir src/widgets/my-widget
+   # Create index.ts, config.ts, types.ts, etc.
+   ```
+
+2. **Add export to package.json:**
+
+   ```json
+   {
+     "exports": {
+       "./widgets/my-widget": {
+         "import": "./dist/widgets/my-widget.js",
+         "types": "./dist/types/widgets/my-widget/index.d.ts"
+       }
+     }
+   }
+   ```
+
+3. **Build:**
+   ```bash
+   pnpm build
+   ```
+
+The vite config automatically reads from package.json and builds all declared exports!
+
+## Code Reduction Achieved
+
+| Widget                | Before     | After     | Reduction |
+| --------------------- | ---------- | --------- | --------- |
+| bar/config.ts         | ~150 lines | ~65 lines | ~57%      |
+| histogram/config.ts   | ~155 lines | ~68 lines | ~56%      |
+| pie/config.ts         | ~160 lines | ~50 lines | ~69%      |
+| scatterplot/config.ts | ~145 lines | ~90 lines | ~38%      |
+| timeseries/config.ts  | ~130 lines | ~70 lines | ~46%      |
+
+**Total:** ~400-500 lines of duplicated code eliminated
+
+## Benefits
+
+✅ **Reduced Duplication** - Shared utilities eliminate repeated code
+✅ **Better Maintainability** - Changes to common patterns update all widgets
+✅ **Automated Builds** - No manual vite/package.json updates needed
+✅ **Consistent Patterns** - All widgets follow the same structure
+✅ **Type Safety** - Full TypeScript support throughout
+✅ **Easy to Extend** - Adding new widgets is straightforward
+✅ **Backwards Compatible** - All external imports remain unchanged