@carto/ps-react-ui 5.3.0 → 6.1.0

package/dist/types/migration/v4/transforms/v6-v7.d.ts

@@ -0,0 +1,54 @@
+import { RuleContext } from './helpers.js';
+/**
+ * `<Grid item xs={12} md={8}>` → `<Grid size={{ xs: 12, md: 8 }}>`.
+ *
+ * `item` disappears, a single breakpoint collapses to `size={8}` rather
+ * than an object, and a bare `xs` becomes `size='grow'` — the v7 spelling
+ * of "take the remaining space".
+ */
+export declare function gridItemProp({ j, root }: RuleContext): number;
+/**
+ * `GridLegacy` → `Grid`.
+ *
+ * It exists so the Grid work can be deferred, and it is removed in v9, so
+ * deferring only moves the cost one jump later. Renaming it here hands the
+ * element to `gridItemProp`, which must run after this.
+ */
+export declare function gridLegacy({ j, root }: RuleContext): number;
+/**
+ * Flags a `Grid container` that does not set its own width.
+ *
+ * No rewrite: whether it needs `width: '100%'` depends on the parent, which
+ * is usually in another file. The v1 container was 100% wide by default and
+ * the v7 one shrinks to its content inside a flex parent, so the column
+ * split silently collapses — the sizes still apply, to a container that is
+ * now too narrow.
+ */
+export declare function gridContainerWidth({ j, root }: RuleContext): number;
+/**
+ * `@mui/material/styles/createTypography` → `@mui/material/styles`.
+ *
+ * Where it lands depends on how the file imports it, and getting this wrong
+ * compiles into a different error rather than failing loudly:
+ *
+ * - A DEFAULT import goes to the one-level entry point, which is what has
+ *   the default export: `@mui/material/Box/Box` → `@mui/material/Box`.
+ * - NAMED imports go to the package root. The one-level entry point only
+ *   re-exports part of its own surface —
+ *   `@mui/material/TablePagination/TablePaginationActions` truncated to
+ *   `@mui/material/TablePagination` loses `TablePaginationActionsProps`,
+ *   which lives on the root.
+ */
+export declare function deepImport({ j, root }: RuleContext): number;
+/** Moves the graduated `@mui/lab` imports to `@mui/material`. */
+export declare function muiLabImport({ j, root }: RuleContext): number;
+/**
+ * Removes the dead narrowing around a `Slider` value.
+ *
+ * v7 narrows the value from `number | number[]` to `number`, so the cast is
+ * redundant and the `Array.isArray` guard is unreachable — and the
+ * unreachable branch narrows to `never`, which leaks `any` into the setter.
+ * `tsc` stays silent about both; only ESLint fails, which is why the guide
+ * insists on running it.
+ */
+export declare function sliderValueNarrowing({ j, root }: RuleContext): number;

package/dist/types/migration/v4/transforms/v7-v9-dom.d.ts

@@ -0,0 +1,63 @@
+import { RuleContext } from './helpers.js';
+/**
+ * Rewrites consolidated class names wherever they appear as text: a
+ * selector in `styled()`, a `className`, a test query, a `styleOverrides`
+ * key spelled as a full class.
+ */
+export declare function consolidatedClassNames({ j, root }: RuleContext): number;
+/** The same rewrite for stylesheets and documentation. */
+export declare function consolidatedClassNamesText(source: string): string;
+/**
+ * Flags `styleOverrides` keys naming a consolidated class.
+ *
+ * No rewrite: a theme key is a slot name, and splitting `textPrimary` into
+ * two means deciding whether the override belongs on the slot, on the color
+ * or on a nested selector — which is a design decision about the theme.
+ */
+export declare function styleOverridesConsolidatedKeys({ j, root, }: RuleContext): number;
+/**
+ * Flags a `styled()` wrapper that reaches into MUI internals.
+ *
+ * `consolidatedClassNames` has already rewritten the names it recognises;
+ * this says the selector is still worth reading, because a wrapper aimed at
+ * another component's internals is the most common silent breakage in
+ * consumer code and v9 moved slots as well as renaming classes.
+ */
+export declare function styledTargetingMuiClasses({ j, root }: RuleContext): number;
+/**
+ * `locator('[role="button"]')` → `getByRole('button')`.
+ *
+ * Components that used to render a generic element with an explicit role now
+ * render the native element, which carries the role implicitly. A role query
+ * matches both spellings; an attribute selector matches only the old one and
+ * fails with "element(s) not found", naming neither MUI nor the version that
+ * changed it.
+ */
+export declare function roleAttributeSelector({ j, root }: RuleContext): number;
+export declare function menuItemOutsideMenuList({ j, root }: RuleContext): number;
+/**
+ * Renames the `*Outline` icons v9 removed, and their `data-testid`s.
+ *
+ * The replacement appends `Outlined` to the WHOLE name. Swapping the
+ * `Outline` suffix for `Outlined` also compiles, and resolves to a
+ * different icon.
+ */
+export declare function outlineIcons({ j, root }: RuleContext): number;
+/** The same rename for documentation, which no codemod otherwise touches. */
+export declare function outlineIconsText(source: string): string;
+/**
+ * Flags the icon names a naive rename produces.
+ *
+ * These are valid v9 icons, so nothing fails — they are just the outlined
+ * variant of the solid glyph. A legitimate use of the solid variant looks
+ * identical to a bad rename, and only the author knows which it is.
+ */
+export declare function outlineIconNaiveRename({ j, root }: RuleContext): number;
+/**
+ * Flags queries against the old pickers DOM.
+ *
+ * The field renders editable `role='spinbutton'` sections instead of one
+ * `<input>`, and the `PickersYear` / `PickersMonth` wrappers are gone. What
+ * a given query should become depends on what it was asserting.
+ */
+export declare function pickersFieldDom({ j, root }: RuleContext): number;

package/dist/types/migration/v4/transforms/v7-v9-props.d.ts

@@ -0,0 +1,64 @@
+import { RuleContext } from './helpers.js';
+/** System props are gone from Box/Typography/Grid/Stack/Link; move to `sx`. */
+export declare function systemProps({ j, root }: RuleContext): number;
+/** `PaperProps={{…}}` → `slotProps={{ paper: {…} }}`. */
+export declare function renamedPropBags({ j, root }: RuleContext): number;
+/** `components`/`componentsProps` → `slots`/`slotProps`. */
+export declare function componentsProp({ j, root }: RuleContext): number;
+/** `Typography`'s dot-path `color`, which survived until v9. */
+export declare function typographyColorSystemProp(context: RuleContext): number;
+/** The same break on every other component, including re-exported ones. */
+export declare function dotPathColor(context: RuleContext): number;
+/**
+ * Removes `disableEscapeKeyDown`, and says so where it changes behaviour.
+ *
+ * With no `onClose` the prop was already doing nothing. With one, escape now
+ * reaches the handler, so a dialog that could only be closed explicitly
+ * becomes dismissable unless the handler ignores that reason — which is not
+ * something a codemod can write into someone else's close logic.
+ */
+export declare function disableEscapeKeyDown({ j, root }: RuleContext): number;
+/** `slots={{ actions: X }}` → `ActionsComponent={X}` on TablePagination. */
+export declare function tablePaginationSlotsActions({ j, root }: RuleContext): number;
+/** `renderTags` → `renderValue`; `ListboxComponent`/`PaperComponent` → slots. */
+export declare function autocompleteRenderTags({ j, root }: RuleContext): number;
+/** `Divider` lost `light`. */
+export declare function dividerLight({ j, root }: RuleContext): number;
+/** Removes a `placeholder` the pickers field no longer renders. */
+export declare function datepickerPlaceholder({ j, root }: RuleContext): number;
+/**
+ * Flags a `freeSolo` Autocomplete.
+ *
+ * v9 types what `freeSolo` always did at runtime: the committed value can be
+ * a string that is not an option. The fix is to narrow inside the handler,
+ * and which branch means what is the author's decision — a cast would put
+ * the old lie back.
+ */
+export declare function autocompleteFreeSoloValue({ j, root }: RuleContext): number;
+/**
+ * Flags a `@mui/codemod` rewrite that landed on something that is not a
+ * Material UI component.
+ *
+ * `deprecations/all` matches on the prop name, not on where the component
+ * comes from, so a third-party component that happens to take `PaperProps`
+ * or `inputProps` gets its API rewritten to one it does not have. On this
+ * codebase it turned `PaperProps` into `slotProps.paper` on a design-system
+ * component and broke the build.
+ *
+ * A component declared in the same file is left alone; one imported from
+ * anywhere but `@mui/*` is flagged, a relative path included — the codemod is
+ * just as wrong about your own components as about a vendor's.
+ */
+export declare function slotPropsOffMui({ j, root }: RuleContext): number;
+/**
+ * Flags a palette path written into an inline `style`, where nothing resolves
+ * it.
+ *
+ * `sx` is what reads the theme; `style` goes straight to the DOM, so
+ * `'text.secondary'` is invalid CSS and the browser drops the declaration —
+ * no error, no styling. It is a plausible landing spot for a value moved out
+ * of a `color` prop during this jump, and it is the shape the rewrite above
+ * cannot produce for you: only the author knows whether the element should
+ * use `sx` instead or resolve the path against the theme first.
+ */
+export declare function themePathInInlineStyle({ j, root }: RuleContext): number;

package/dist/types/migration/v4/widgets-v1.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The names widgets v1 exported that widgets v2 does not export anywhere.
+ *
+ * Generated with the TypeScript checker from every `./widgets/*` entry point
+ * of the last release that shipped v1, minus every `./widgets-v2/*` export.
+ * The 89 names both surfaces share (`CategoryUI`, `Download`, the
+ * `*Skeleton`s, …) are left out on purpose: after the rename they resolve to
+ * v2, so a leftover v1 use of one fails in `tsc` on its props, not here.
+ * That is also what keeps the rule idempotent: a second run over renamed v2
+ * imports finds none of these names.
+ */
+export declare const WIDGETS_V1_ONLY: ReadonlySet<string>;

package/dist/types/widgets/actions/brush-toggle/brush-toggle.d.ts

@@ -1,29 +1,56 @@
-import { BrushToggleProps } from './types.js';
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { BrushToggleLabels } from './labels.js';
+export interface BrushToggleProps {
+    initialEnabled?: boolean;
+    /**
+     * ECharts brush type. `'lineX'` (default) selects a range on the
+     * x-axis — appropriate for bar / histogram / timeseries. `'rect'`
+     * selects a 2-D rectangle — use for scatterplot. Other ECharts
+     * brush types (`'lineY'`, `'polygon'`) are also accepted.
+     */
+    brushType?: 'lineX' | 'lineY' | 'rect' | 'polygon';
+    /**
+     * `'multiple'` (default) lets the user draw additional brushes on
+     * top of existing ones. `'single'` replaces the previous brush on
+     * each new draw.
+     */
+    brushMode?: 'multiple' | 'single';
+    /**
+     * Optional view of the consumer-owned selection. When provided and
+     * the array is empty (`[]`), any brush rectangles currently drawn on
+     * the chart are wiped — keeps the UI in sync when the parent clears
+     * the selection externally (e.g. via `Widget.SelectionSummary`'s
+     * `onClear`). Pass the same array that drives `useChartSelection` /
+     * the option factory's `selection` input.
+     *
+     * Leave `undefined` to opt out — the sync effect becomes a no-op.
+     */
+    selection?: readonly unknown[] | null;
+    labels?: Partial<BrushToggleLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
 /**
- * Kept for backwards compatibility. The tool is no longer registered with the
- * widget store — brush state is now owned directly by this component and the
- * associated DOM overlay instead of being driven through the config pipeline.
- * Existing code that looks this constant up in `registeredTools` will simply
- * find no match.
- */
-export declare const BRUSH_TOGGLE_TOOL_ID = "brush-toggle";
-/**
- * Widget action to toggle brush-style selection on bar and histogram widgets.
+ * Toggle ECharts' brush selection mode. Two-part wiring:
  *
- * Renders a toggle button and a portaled overlay rendered inside the chart's
- * `<div>`. The overlay handles all pointer interactions, draws selection
- * rectangles in DOM, and hit-tests against the widget data. All state lives
- * in the widget store — rectangles survive config-pipeline re-renders
- * (`setOption({ notMerge: true })`) automatically.
+ *   1. The config transform (`addBrush`) installs the `brush`
+ *      component on the option so brushed items get the
+ *      `outOfBrush` dim treatment.
+ *   2. ECharts only enters "brush cursor" mode when something
+ *      dispatches `takeGlobalCursor({ key: 'brush', ... })`. This
+ *      component drives that dispatch via {@link useEchartInstance},
+ *      reacting when the chart instance becomes available (the
+ *      `BrushToggle` mounts before `Widget.Echart` in tree order, so
+ *      on first mount the chart isn't ready yet).
  *
- * Only intended for bar and histogram widgets (both use `xAxis.type === 'category'`).
+ *   3. ECharts clears the global cursor on every `setOption`, so we
+ *      re-dispatch on each `'finished'` event — required for
+ *      `brushMode: 'multiple'` to keep working across selection-driven
+ *      re-renders, RelativeData toggles, etc.
  *
- * @example
- * ```tsx
- * <BrushToggle
- *   id="my-widget"
- *   onBrushSelected={(items) => console.log(items)}
- * />
- * ```
+ * Selection events (`brushSelected` / `brushEnd`) flow through the
+ * existing `useChartSelection` wiring at the consumer level — no extra
+ * plumbing here.
  */
-export declare function BrushToggle({ id, onBrushSelected, multiBrush, selections, defaultEnabled, labels, Icon, IconButtonProps, }: BrushToggleProps): import('react').JSX.Element;
+export declare function BrushToggle({ initialEnabled, brushType, brushMode, selection, labels, icon: Icon, iconProps, }: BrushToggleProps): import('react').JSX.Element;

package/dist/types/widgets/actions/brush-toggle/style.d.ts

@@ -1,21 +1,12 @@
 import { Theme } from '@mui/material';
-import { CSSProperties } from 'react';
 export declare const styles: {
-    container: {
-        display: "flex";
-        alignItems: "center";
-        gap: ({ spacing }: Theme) => string;
-    };
-    trigger: {
-        '&[data-active="true"]': {
-            background: (theme: Theme) => string;
+    toggle: {
+        p: number;
+        '& .MuiSvgIcon-root': {
+            fontSize: number;
         };
     };
+    toggleActive: {
+        background: (theme: Theme) => string;
+    };
 };
-/**
- * Plain CSS objects for the brush overlay — we're outside MUI's sx pipeline
- * here because the rectangles are rendered via a React portal into the chart
- * div (not part of the MUI tree). Colors borrow from the base palette; if
- * theme-aware styling is needed later, move to styled components.
- */
-export declare const overlayStyles: Record<string, CSSProperties>;

package/dist/types/widgets/actions/change-column/change-column-icon.d.ts

@@ -1 +1,2 @@
-export declare const ChangeColumnIcon: () => import('react').JSX.Element;
+import { SvgIconProps } from '@mui/material';
+export declare function ChangeColumnIcon(props: SvgIconProps): import('react').JSX.Element;

package/dist/types/widgets/actions/change-column/change-column.d.ts

@@ -1,20 +1,29 @@
-import { ChangeColumnProps } from './types.js';
-export declare const CHANGE_COLUMN_TOOL_ID = "change-column";
+import { ComponentType, ReactNode } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { ChangeColumnLabels } from './labels.js';
+export interface ChangeColumnItem {
+    id: string;
+    label: ReactNode;
+}
+export interface ChangeColumnProps {
+    /**
+     * Master list of columns (id + label) in their default order. The current
+     * effective order is derived by combining this list with the widget's
+     * `columnOrder` extension state.
+     */
+    columns: readonly ChangeColumnItem[];
+    labels?: Partial<ChangeColumnLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    dragHandleIcon?: ComponentType<SvgIconProps>;
+}
 /**
- * Widget action to reorder columns in a table widget via drag-and-drop.
+ * Action that lets users reorder columns via drag-and-drop. The new order is
+ * persisted on the widget store as `columnOrder` (an array of ids) on the
+ * {@link ChangeColumnWidgetState} extension. `<Table>` (and other column-aware
+ * bridges) merge that order with their own `columns` prop via
+ * `resolveColumns()` from the table primitives.
  *
- * This action reads the columns from the widget store and allows users to
- * drag and drop columns to reorder them. All columns are displayed and
- * can be reordered.
- *
- * Registers as a config pipeline tool so that column order is automatically
- * re-applied when the base config is updated (e.g., by WidgetLoader).
- *
- * Returns null if there are fewer than 2 columns.
- *
- * @example
- * ```tsx
- * <ChangeColumn id="my-table-widget" />
- * ```
+ * Returns `null` when there are fewer than two columns to reorder.
  */
-export declare function ChangeColumn({ id, labels, Icon, IconButtonProps, MenuProps, }: ChangeColumnProps): import('react').JSX.Element | null;
+export declare function ChangeColumn({ columns, labels, icon: Icon, iconProps, dragHandleIcon, }: ChangeColumnProps): import('react').JSX.Element | null;

package/dist/types/widgets/actions/change-column/sortable-column-item.d.ts

@@ -1,9 +1,14 @@
-import { TableColumn } from '../../table/types.js';
+import { ComponentType, ReactNode } from 'react';
+import { SvgIconProps } from '@mui/material';
 export interface SortableColumnItemProps {
-    column: TableColumn;
+    id: string;
+    label: ReactNode;
+    dragHandleIcon?: ComponentType<SvgIconProps>;
 }
 /**
- * A draggable menu item for column reordering.
- * Uses @dnd-kit/sortable for drag-and-drop functionality.
+ * Draggable menu item used inside ChangeColumn's `<DndContext>`. Wraps a
+ * MUI `<MenuItem>` so it inherits keyboard / theming behavior, and exposes
+ * the dnd-kit listeners on the whole row so the user can grab anywhere on
+ * the row to reorder.
  */
-export declare function SortableColumnItem({ column }: SortableColumnItemProps): import('react').JSX.Element;
+export declare function SortableColumnItem({ id, label, dragHandleIcon: HandleIcon, }: SortableColumnItemProps): import('react').JSX.Element;

package/dist/types/widgets/actions/change-column/types.d.ts

@@ -1,19 +1,10 @@
-import { IconButtonProps, MenuProps } from '@mui/material';
-import { ReactNode } from 'react';
-export interface ChangeColumnProps {
-    /** Widget ID to update column configuration in the widget store */
-    id: string;
-    /** Custom labels for the action */
-    labels?: {
-        /** Tooltip label */
-        tooltip?: string;
-        /** Accessibility label */
-        ariaLabel?: string;
-    };
-    /** Props passed to the IconButton component */
-    IconButtonProps?: IconButtonProps;
-    /** Props passed to the Menu component */
-    MenuProps?: Partial<MenuProps>;
-    /** Custom icon to display */
-    Icon?: ReactNode;
+import { WidgetState } from '../../stores/index.js';
+/**
+ * State extension owned by the ChangeColumn action. Stored on the per-widget
+ * Zustand store; read by `<Table>` (and any other column-aware bridge) to
+ * resolve the effective column order.
+ */
+export interface ChangeColumnWidgetState extends WidgetState {
+    /** Ordered list of column ids. Empty / unset means "use props order". */
+    columnOrder?: readonly string[];
 }

package/dist/types/widgets/actions/download/download.d.ts

@@ -1,13 +1,18 @@
-import { DownloadProps } from './types.js';
-/**
- * Dropdown menu action for exporting widget data in various formats (CSV, PNG, etc.).
- *
- * Reads widget data from the store and triggers downloads using the modifier
- * function defined in each `DownloadItem`.
- *
- * @example
- * ```tsx
- * <Download id={widgetId} items={barDownloadConfig({ refUI })} />
- * ```
- */
-export declare function Download({ id, items, labels, Icon, IconButtonProps, }: DownloadProps): import('react').JSX.Element;
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { DownloadItem } from './types.js';
+import { DownloadLabels } from './labels.js';
+export interface DownloadProps {
+    items: readonly DownloadItem[];
+    labels?: Partial<DownloadLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Fires when an item's `resolve()` rejects (or any step in the click-through
+     * path throws). The error is normalised to a real `Error` first. Surface
+     * to your telemetry / toast layer here; the trigger already shows a visual
+     * error indicator independently.
+     */
+    onError?: (err: Error) => void;
+}
+export declare function Download({ items, labels, icon: Icon, iconProps, onError, }: DownloadProps): import('react').JSX.Element;

package/dist/types/widgets/actions/download/exports.d.ts

@@ -1,21 +1,37 @@
-import { Ref } from 'react';
-import { DownloadItem } from './types.js';
 /**
- * Pre-configured download item for exporting widget data as a CSV file.
- *
- * Converts a 2D array of data into CSV format with proper escaping and
- * triggers a browser download. Revokes the object URL after download.
+ * Pure download helpers — no React, no DOM lifecycle outside the link click.
+ * Component layer in {@link ./download.tsx} orchestrates these.
  */
-export declare const downloadToCSV: DownloadItem<unknown[][]>;
+export interface DownloadHandle {
+    url: string;
+    revoke: () => void;
+}
+export declare function toCsvString(rows: readonly (readonly unknown[])[]): string;
+export declare function downloadToCSV(rows: readonly (readonly unknown[])[]): DownloadHandle;
+export declare function sanitizeFilename(name: string): string;
 /**
- * Pre-configured download item for exporting a widget as a PNG image.
- *
- * Uses html2canvas to capture the widget DOM element referenced by a React ref.
- * Strips toolbar and action elements before capturing.
- *
- * @remarks
- * The modifier expects a React ref to the widget's root HTML element, not raw data.
+ * Triggers a browser download for the given URL by synthesizing an anchor,
+ * clicking it, and removing it. Pure DOM — no React. The filename is run
+ * through {@link sanitizeFilename} before being assigned to `a.download`.
  */
-export declare const downloadToPNG: Omit<DownloadItem, 'modifier'> & {
-    modifier: (ref: Ref<HTMLElement | null> | undefined) => Promise<string | undefined>;
-};
+export declare function triggerLinkDownload(args: {
+    url: string;
+    filename: string;
+}): void;
+export interface DownloadDOMToPNGOptions {
+    element: HTMLElement;
+    /** html2canvas `scale`. Default 2 — crisp on hi-DPI displays. */
+    pixelRatio?: number;
+    /**
+     * html2canvas `backgroundColor`. Default `null` (transparent) so the PNG
+     * inherits whatever surface it lands on when the user pastes it.
+     */
+    backgroundColor?: string | null;
+}
+/**
+ * Rasterise an HTMLElement to PNG via `html2canvas` and wrap the result in
+ * a `DownloadHandle`. The caller is responsible for calling `handle.revoke`
+ * after the link click is dispatched. Used by per-widget download configs
+ * to power the PNG menu item.
+ */
+export declare function downloadDOMToPNG(opts: DownloadDOMToPNGOptions): Promise<DownloadHandle>;

package/dist/types/{widgets-v2 → widgets}/actions/download/index.d.ts

@@ -3,6 +3,7 @@ export { downloadToCSV, downloadDOMToPNG, toCsvString, triggerLinkDownload, type
 export { CSVIcon, PNGIcon, MarkdownIcon } from './icons.js';
 export { buildPngDownloadItem, type BuildPngDownloadItemArgs } from './png-item.js';
 export { buildCsvDownloadItem, type BuildCsvDownloadItemArgs } from './csv-item.js';
+export { withPngItem, type WidgetDownloadArgs } from './widget-download.js';
 export { DOWNLOAD_ITEM_IDS, type DownloadItemId } from './constants.js';
 export type { DownloadItem, DownloadContext } from './types.js';
 export { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels.js';

package/dist/types/{widgets-v2 → widgets}/actions/download/png-item.d.ts

@@ -5,7 +5,7 @@ export interface BuildPngDownloadItemArgs {
     /**
      * Reads the capture element to rasterise. Called at click time so the
      * download config doesn't capture a stale reference. Wire it to
-     * `() => getCaptureEl(id)` from `widgets-v2/stores`.
+     * `() => getCaptureEl(id)` from `widgets/stores`.
      */
     getCaptureEl: (ctx: DownloadContext) => HTMLElement | null;
     /** html2canvas `scale`. Default 2. */

package/dist/types/widgets/actions/download/types.d.ts

@@ -1,21 +1,46 @@
-import { JSX, ReactNode } from 'react';
-import { IconButtonProps } from '@mui/material';
-import { WidgetState } from '../../stores/types.js';
-export interface DownloadItem<D = unknown> {
+import { ReactElement } from 'react';
+/**
+ * Passed to {@link DownloadItem.resolve} by `<Widget.Download>`.
+ */
+export interface DownloadContext {
+    /**
+     * Id of the widget store the menu was opened from — the dialog's own
+     * store when opened from `FullScreen.Slot`'s header, so an export matches
+     * what the user is looking at. `null` outside a `<Widget.Provider>`.
+     */
+    id: string | null;
+}
+export interface DownloadItem {
+    /** Unique key (also used as menu label key). */
     id: string;
+    /** Display label in the menu. */
     label: string;
-    icon?: JSX.Element;
+    /**
+     * Optional leading icon shown next to the label. Pass a rendered element
+     * (e.g. `<DownloadIcon fontSize='small' />`) so consumers can fully
+     * control sizing / colour. Rendered inside an MUI `<ListItemIcon>`.
+     */
+    icon?: ReactElement;
+    /**
+     * When `true`, the menu item is rendered but non-clickable (greyed out).
+     * Useful for items whose underlying export is unavailable in the current
+     * widget state (no rows, missing permission, etc.).
+     */
     disabled?: boolean;
+    /**
+     * Override for the resolved filename. When set, `resolve()`'s `filename`
+     * is ignored and this value is used instead — handy when the consumer
+     * wants to template the filename with widget metadata without having to
+     * close over it inside `resolve()`.
+     */
     filename?: string;
-    modifier: (data: D) => Promise<string | undefined>;
-    callback?: (data: string) => void;
-}
-export interface DownloadProps {
-    id: WidgetState['id'];
-    items: DownloadItem[];
-    labels?: {
-        ariaLabel?: string;
-    };
-    IconButtonProps?: IconButtonProps;
-    Icon?: ReactNode;
+    /**
+     * Resolves to a Blob URL the trigger will click. Optional `revoke` is
+     * called after the click is dispatched.
+     */
+    resolve: (ctx: DownloadContext) => Promise<{
+        url: string;
+        filename: string;
+        revoke?: () => void;
+    }>;
 }

package/dist/types/widgets/actions/download/widget-download.d.ts

@@ -0,0 +1,26 @@
+import { DownloadContext, DownloadItem } from './types.js';
+/** Arguments every per-widget `create*DownloadConfig` shares. */
+export interface WidgetDownloadArgs<T> {
+    /** Base filename (without extension). */
+    filename: string;
+    /**
+     * Reads the data to export at click time. `ctx.id` is the store the menu
+     * was opened from — the fullscreen dialog's own while it's open. See
+     * `widgetStoreData` in `widgets/stores`.
+     */
+    getData: (ctx: DownloadContext) => T;
+    /**
+     * Reads the element the PNG item rasterises. When given, a PNG item is
+     * prepended to the menu. See `widgetCaptureEl` in `widgets/stores`.
+     */
+    getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null;
+    /** PNG `pixelRatio` (default 2). */
+    pngPixelRatio?: number;
+    /** PNG `backgroundColor` (default transparent). */
+    pngBackgroundColor?: string | null;
+}
+/**
+ * `items`, with a PNG item in front when `args.getCaptureEl` is given — the
+ * order every widget's download menu uses.
+ */
+export declare function withPngItem(args: Omit<WidgetDownloadArgs<unknown>, 'getData'>, ...items: DownloadItem[]): DownloadItem[];