@tetrascience-npm/tetrascience-react-ui 1.0.0-beta.156.1 → 1.0.0-beta.158.1

package/dist/components/composed/PlateMapEditor/PlateMapEditor.d.ts

@@ -1,10 +1,90 @@
+import { getPlateMapScopedWellId, PlateMapApplyScope } from './usePlateMapEditorState';
 import { PlateMapActionsMenuProps } from './PlateMapActionsMenu';
 import { PlateMapPlateSelectorVariant } from './PlateMapPlateSelector';
 import { WellShape } from './PlatePaintGrid';
-import { PlateFormat, PlateMapGroupOption, PlateMapPlateOption, WellColumn, WellField, WellId, WellRecord } from './types';
+import { PlateFormat, PlateMapEditorLabels, PlateMapGroupOption, PlateMapPlateOption, WellColumn, WellField, WellId, WellRecord } from './types';
+import { FilterColumnConfig } from '../../ui/data-table/data-table';
 import { Badge } from '../../ui/badge';
 import * as React from "react";
-export declare function getPlateMapScopedWellId(plateBarcode: string, wellId: WellId): WellId;
+/**
+ * Width at which the form and plate stop stacking and sit side by side.
+ *
+ * These are **container** widths, not viewport widths — the editor measures the
+ * space it is actually given, so it lays out correctly inside a narrow panel,
+ * split pane, or drawer on a wide monitor, not just on a small device. Below
+ * the chosen width both regions are full-width and stacked.
+ *
+ * `"sm"` 640px · `"md"` 768px (default) · `"lg"` 1024px · `"xl"` 1280px ·
+ * `"never"` always stacked.
+ */
+export type PlateMapEditorStackAt = "sm" | "md" | "lg" | "xl" | "never";
+/** Where the metadata form sits relative to the plate grid. */
+export type PlateMapEditorFormPlacement = "start" | "end" | "top" | "bottom";
+export { getPlateMapScopedWellId };
+/**
+ * Imperative handle for driving the editor's staged-edit state from outside —
+ * the supported way to render the metadata form somewhere the editor can't
+ * reach (a host sidebar, a drawer, a toolbar) while keeping the editor's
+ * selection and apply behaviour.
+ *
+ * Pair with `hideForm` and your own form:
+ *
+ * ```tsx
+ * const editor = React.useRef<PlateMapEditorHandle<MyWell>>(null);
+ * <PlateMapEditor ref={editor} hideForm … />
+ * <MySidebarForm
+ *   onChange={(next) => editor.current?.setStaged(next)}
+ *   onApply={() => editor.current?.apply()}
+ *   onClear={() => editor.current?.clear()}
+ * />
+ * ```
+ */
+/**
+ * Per-region class hooks. Each card also carries
+ * `data-plate-map-region="form|plate|manifest"`, so plain CSS can target the
+ * same regions without threading props.
+ */
+export interface PlateMapEditorClassNames {
+    /** The row (or column) holding the form and plate cards. */
+    layout?: string;
+    /** The form column `Card`. Merged after the width rules, so width utilities here win. */
+    formCard?: string;
+    /** The plate column `Card`. */
+    plateCard?: string;
+    /** The manifest `Card`. */
+    manifestCard?: string;
+    /** The `PlateMapForm` panel inside the form card. */
+    form?: string;
+    /** The `PlateMapGrid` panel inside the plate card. */
+    grid?: string;
+    /** The `PlateMapManifest` panel inside the manifest card. */
+    manifest?: string;
+}
+/** Manifest table behaviour. Structural bits (`hideManifest`, `manifestTitle`, `manifestSlot`) stay top-level. */
+export interface PlateMapEditorManifestOptions {
+    /** Enables the filter popover. */
+    filterable?: boolean;
+    /** Overrides which columns are filterable and how. */
+    filterColumns?: FilterColumnConfig[];
+    /** Enables the group-by selector. */
+    groupable?: boolean;
+    /** Field grouped by on first render. Requires `groupable`. */
+    defaultGroupBy?: string;
+    pageSize?: number;
+    pageSizeOptions?: number[];
+    /** Adds the copy-first-value-downward column action. Defaults to true. */
+    enableFillDown?: boolean;
+}
+export interface PlateMapEditorHandle<T extends WellRecord = WellRecord> {
+    /** Applies the staged record across the current selection. */
+    apply: (scope?: PlateMapApplyScope) => void;
+    /** Clears the current selection's wells. */
+    clear: (scope?: PlateMapApplyScope) => void;
+    /** Replaces the staged record. */
+    setStaged: (next: Partial<T>) => void;
+    /** Reads the staged record. */
+    getStaged: () => Partial<T>;
+}
 export interface PlateMapEditorProps<T extends WellRecord = WellRecord> extends Omit<PlateMapActionsMenuProps, "hasEntries" | "className"> {
     format: PlateFormat;
     rows?: number;
@@ -15,10 +95,14 @@ export interface PlateMapEditorProps<T extends WellRecord = WellRecord> extends
     onSelectionChange: (next: Set<WellId>) => void;
     fields: WellField<T>[];
     tableColumns: WellColumn<T>[];
-    /** Resolves the SVG fill color for a well. */
-    colorForWell: (well: T | undefined, wellId: WellId) => string;
-    /** Builds an empty record when a well is freshly created. */
-    emptyEntry: (wellId: WellId) => T;
+    /**
+     * Resolves the SVG fill color for a well. Optional — defaults to a filled
+     * swatch for populated wells and the empty-well token for the rest, which is
+     * enough for read-only or single-category views.
+     */
+    colorForWell?: (well: T | undefined, wellId: WellId) => string;
+    /** Builds an empty record when a well is freshly created. Defaults to `{}`. */
+    emptyEntry?: (wellId: WellId) => T;
     /**
      * Merges the staged form record onto an existing well record on Apply.
      * Defaults to a shallow merge (form keys overwrite existing keys when set).
@@ -28,14 +112,37 @@ export interface PlateMapEditorProps<T extends WellRecord = WellRecord> extends
     isPopulated?: (row: T) => boolean;
     /** Select field cycled when double-clicking a single well, e.g. role painting. */
     cycleFieldOnWellDoubleClick?: keyof T & string;
+    /**
+     * Names a `select` field whose options appear as a swatch strip anchored above
+     * the selection, so a value can be painted across it in one click without a
+     * trip to the form. Swatch colours come from each option's `swatch`.
+     *
+     * Applies immediately — this is a shortcut for the common case, not a staged
+     * edit. Off unless set.
+     */
+    quickPaintField?: keyof T & string;
+    /**
+     * Controlled staged form record. Pair with `onStagedChange` to prefill the
+     * form, read what's staged, or drive Apply from outside. When omitted the
+     * editor owns staged state internally.
+     */
+    staged?: Partial<T>;
+    onStagedChange?: (next: Partial<T>) => void;
     /** Optional header title (e.g. plate set name). */
     title?: string;
     /** Optional badges shown in the header next to the title. */
     badges?: React.ReactNode;
-    /** Optional banner (e.g. import/error alert) shown above the layout. */
+    /** Optional banner (e.g. import/error alert) shown above the whole layout. */
     banner?: React.ReactNode;
-    /** Legend block rendered under the form column. */
+    /** Legend block. Position controlled by `legendPlacement`. */
     legend?: React.ReactNode;
+    /**
+     * Where `legend` renders. `"form"` (default) puts it under the form column,
+     * separated by a divider. `"plate"` puts it under the grid inside the plate
+     * card, stacked above anything in `plateFooter`. With `hideForm`, `"form"`
+     * drops the legend entirely — use `"plate"` there.
+     */
+    legendPlacement?: "form" | "plate";
     /** Form helper slot rendered between fields and the action row. */
     formExtras?: React.ReactNode;
     /**
@@ -44,12 +151,41 @@ export interface PlateMapEditorProps<T extends WellRecord = WellRecord> extends
      * source palette. The legend slot still renders beneath the replacement.
      */
     formSlot?: React.ReactNode;
-    /** Footer actions (e.g. Save, Back). */
+    /** Hides the form column entirely, leaving grid (+ manifest). */
+    hideForm?: boolean;
+    /**
+     * Where the metadata form sits relative to the plate grid. `"start"` /
+     * `"end"` put it beside the grid (subject to `stackAt`); `"top"` / `"bottom"`
+     * stack it full-width at every breakpoint. Defaults to `"start"`.
+     */
+    formPlacement?: PlateMapEditorFormPlacement;
+    /**
+     * Viewport width at which the form and grid sit side by side. Below it they
+     * always stack full-width. Ignored when `formPlacement` is `"top"`/`"bottom"`.
+     * Defaults to `"md"`.
+     */
+    stackAt?: PlateMapEditorStackAt;
+    /**
+     * Width of the form column at and above `stackAt`. Any CSS length (`"420px"`,
+     * `"28rem"`, `"30%"`) or a number treated as px. Defaults to `"360px"`.
+     * Below `stackAt` the form is always full-width regardless of this value.
+     */
+    formWidth?: number | string;
+    /** Footer actions (e.g. Save, Back), rendered at the very bottom of the editor. */
     footer?: React.ReactNode;
     /** Title for the plate grid panel. */
     plateTitle?: React.ReactNode;
-    /** Optional controls shown next to the built-in actions menu. */
+    /** Optional controls shown above the grid, inside the plate card. */
     plateToolbar?: React.ReactNode;
+    /** Slot rendered above the grid's toolbar, scoped to the plate card only. */
+    plateBanner?: React.ReactNode;
+    /**
+     * Content for the plate card's footer — the one slot below the grid. Renders
+     * as a real `CardFooter`, so it picks up the card's footer styling. Use it
+     * for per-plate actions or a summary; for the editor-wide action row use
+     * `footer`.
+     */
+    plateFooter?: React.ReactNode;
     /** User-provided plates available for this editor. Barcodes are never generated by the editor. */
     plates?: PlateMapPlateOption[];
     activePlateId?: string;
@@ -65,6 +201,15 @@ export interface PlateMapEditorProps<T extends WellRecord = WellRecord> extends
     plateSelectorVariant?: PlateMapPlateSelectorVariant;
     /** Row field used to stamp the active user-provided barcode onto edited wells. Defaults to `plateBarcode`. */
     plateBarcodeField?: keyof T & string;
+    /**
+     * Which plates Apply/Clear write to. `"active-plate"` (default) touches only
+     * the plate on screen; `"all-plates"` writes the same well positions on every
+     * plate in `plates`, each row stamped with its own barcode.
+     *
+     * For a UI offering both side by side, use `usePlateMapEditorState` directly —
+     * `applyStagedToSelection("all-plates")` takes a per-call override.
+     */
+    applyScope?: PlateMapApplyScope;
     /** Header for the automatic manifest barcode column. */
     plateBarcodeColumnHeader?: string;
     /** Hide the automatic manifest barcode column when plate-scoped editing is active. */
@@ -81,6 +226,13 @@ export interface PlateMapEditorProps<T extends WellRecord = WellRecord> extends
     emptyWellFillColor?: string | null;
     /** Well shape forwarded to `PlatePaintGrid`. Defaults to `"rect"`. */
     wellShape?: WellShape;
+    /**
+     * How a selected well is filled. `"well"` (default) keeps the well's own
+     * colour and shows selection via the ring, so the result of an Apply is
+     * visible while the wells are still selected. `"selection"` replaces the
+     * fill with the selection tint.
+     */
+    selectionFillMode?: "selection" | "well";
     /** When true, wraps the grid in a card-like plate frame (rounded + border + soft shadow). */
     framedPlate?: boolean;
     /**
@@ -93,14 +245,118 @@ export interface PlateMapEditorProps<T extends WellRecord = WellRecord> extends
     highlightedWellIds?: ReadonlySet<WellId>;
     /** Fires whenever the currently hovered well changes (null on leave). */
     onHoveredWellChange?: (wellId: WellId | null) => void;
-    /** Enables the filter popover on the manifest table. */
+    /** Hides the grid's built-in "Select all" / "Deselect all" links. */
+    hideSelectionControls?: boolean;
+    /**
+     * Overrides every user-facing string the editor and its manifest render —
+     * the single place to localise. Omitted keys fall back to English defaults.
+     *
+     * Does not cover `plateTitle` / `manifestTitle` (own props, `ReactNode`) or
+     * the import/export menu's labels (`importCsvLabel` and friends, inherited
+     * from `PlateMapActionsMenuProps`).
+     */
+    labels?: PlateMapEditorLabels;
+    /** Hides the sample manifest panel entirely. */
+    hideManifest?: boolean;
+    /**
+     * Fully replaces the manifest panel's body, keeping the card and heading.
+     * Use for a bespoke summary table; pair with `hideManifest` to drop the
+     * region altogether.
+     */
+    manifestSlot?: React.ReactNode;
+    /** Heading for the manifest card. Defaults to `"Sample manifest"`. */
+    manifestTitle?: React.ReactNode;
+    /** Manifest table behaviour. See {@link PlateMapEditorManifestOptions}. */
+    manifest?: PlateMapEditorManifestOptions;
+    /** @deprecated Use `manifest={{ filterable }}`. */
     manifestFilterable?: boolean;
-    /** Enables the group-by selector on the manifest table. */
+    /** @deprecated Use `manifest={{ groupable }}`. */
     manifestGroupable?: boolean;
     autoScaleGrid?: boolean;
     minCellSize?: number;
     maxCellSize?: number;
+    /** Applied to the editor root. */
     className?: string;
+    /** Inline styles for the editor root. */
+    style?: React.CSSProperties;
+    /** Per-region class hooks. See {@link PlateMapEditorClassNames}. */
+    classNames?: PlateMapEditorClassNames;
+    /**
+     * Imperative handle for driving staged edits from outside the editor.
+     * See {@link PlateMapEditorHandle}.
+     */
+    ref?: React.Ref<PlateMapEditorHandle<T>>;
 }
-export declare function PlateMapEditor<T extends WellRecord = WellRecord>({ format, rows, columns, values, onChange, selection, onSelectionChange, fields, tableColumns, colorForWell, emptyEntry, mergeOnApply, isPopulated, cycleFieldOnWellDoubleClick, title, badges, banner, legend, formExtras, formSlot, footer, plateTitle, plateToolbar, plates, activePlateId, onPlateChange, onAddPlate, onRemovePlate, addPlateLabel, removePlateLabel, plateSelectorLabel, plateSelectorVariant, plateBarcodeField, plateBarcodeColumnHeader, hidePlateBarcodeColumn, groups, activeGroupId, onGroupClick, renderHoverSummary, cellSize, emptyWellFillColor, wellShape, framedPlate, wrapWell, highlightedWellIds, onHoveredWellChange, manifestFilterable, manifestGroupable, autoScaleGrid, minCellSize, maxCellSize, className, templates, templateId, onTemplateChange, onClearTemplate, onImportCsv, onExportCsv, onImportTemplate, onExportTemplate, csvAccept, templateAccept, label, align, side, importTemplateLabel, exportTemplateLabel, importCsvLabel, exportCsvLabel, clearLabel, }: PlateMapEditorProps<T>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Turnkey plate-map editing surface: a metadata form, an interactive plate
+ * grid, and a sample manifest, wired together with the staged-edit controller
+ * in {@link usePlateMapEditorState}.
+ *
+ * ## Choosing a level
+ *
+ * | You need | Use |
+ * | --- | --- |
+ * | The standard surface, tuned by props | `PlateMapEditor` (this) |
+ * | A layout these props can't express | {@link usePlateMapEditorState} + `PlateMapForm` / `PlateMapGrid` / `PlateMapManifest` |
+ * | One region only, wired yourself | The primitives directly |
+ *
+ * Dropping to the hook keeps the apply/clear semantics, plate scoping, and
+ * barcode stamping — you only take over layout.
+ *
+ * ## Customization map
+ *
+ * - **Layout** — `formPlacement` (`start`/`end`/`top`/`bottom`), `stackAt`,
+ *   `formWidth`, `hideForm`, `hideManifest`.
+ * - **Slots** — `title`, `badges`, `banner` (whole editor), `plateBanner`
+ *   (plate card only), `plateToolbar` (above grid), `plateFooter` (the plate
+ *   card's footer), `footer` (editor-wide action row), `legend` +
+ *   `legendPlacement`, `formExtras`, `formSlot` (replaces the form),
+ *   `manifestSlot` (replaces the manifest body).
+ * - **Edit semantics** — `mergeOnApply`, `emptyEntry`, `isPopulated`,
+ *   `cycleFieldOnWellDoubleClick`, and `staged` / `onStagedChange` to make the
+ *   staged record controlled.
+ * - **Labels** — one `labels` object covers every string the editor and its
+ *   manifest render. `plateTitle` / `manifestTitle` and the import/export menu
+ *   labels stay separate (they are `ReactNode` slots, not plain text).
+ * - **Styling** — `className` / `style` on the root plus one `classNames` map
+ *   for the regions. Each card also carries
+ *   `data-plate-map-region="form|plate|manifest"` for CSS targeting.
+ * - **Manifest** — one `manifest` options object; `hideManifest`,
+ *   `manifestTitle` and `manifestSlot` stay top-level.
+ *
+ * ## Responsiveness
+ *
+ * The editor responds to **its container's** width, not the viewport's, so it
+ * lays out correctly inside a narrow panel, split pane, or drawer on a wide
+ * screen. `stackAt` names a container width (`sm` 640 / `md` 768 / `lg` 1024 /
+ * `xl` 1280 / `never`); below it the form and grid stack full-width. A plate
+ * too dense to fit scrolls inside its own container rather than widening the
+ * page.
+ *
+ * @example Default surface
+ * ```tsx
+ * <PlateMapEditor
+ *   format="96"
+ *   values={values}
+ *   onChange={setValues}
+ *   selection={selection}
+ *   onSelectionChange={setSelection}
+ *   fields={FIELDS}
+ *   tableColumns={COLUMNS}
+ * />
+ * ```
+ *
+ * @example Grid-only, form on the right, localised
+ * ```tsx
+ * <PlateMapEditor
+ *   {...base}
+ *   formPlacement="end"
+ *   stackAt="lg"
+ *   formWidth="22rem"
+ *   hideManifest
+ *   labels={{ apply: "Appliquer", clearWells: "Vider les puits" }}
+ * />
+ * ```
+ */
+export declare function PlateMapEditor<T extends WellRecord = WellRecord>({ format, rows, columns, values, onChange, selection, onSelectionChange, fields, tableColumns, colorForWell, emptyEntry, mergeOnApply, isPopulated, cycleFieldOnWellDoubleClick, quickPaintField, staged: controlledStaged, onStagedChange, title, badges, banner, legend, legendPlacement, formExtras, formSlot, hideForm, formPlacement, stackAt, formWidth, footer, plateTitle, plateToolbar, plateBanner, plateFooter, plates, activePlateId, onPlateChange, onAddPlate, onRemovePlate, addPlateLabel, removePlateLabel, plateSelectorLabel, plateSelectorVariant, plateBarcodeField, applyScope, plateBarcodeColumnHeader, hidePlateBarcodeColumn, groups, activeGroupId, onGroupClick, renderHoverSummary, cellSize, emptyWellFillColor, wellShape, selectionFillMode, framedPlate, wrapWell, highlightedWellIds, onHoveredWellChange, hideSelectionControls, labels, hideManifest, manifestSlot, manifestTitle, manifest, manifestFilterable, manifestGroupable, autoScaleGrid, minCellSize, maxCellSize, className, style, classNames, ref, templates, templateId, onTemplateChange, onClearTemplate, onImportCsv, onExportCsv, onImportTemplate, onExportTemplate, csvAccept, templateAccept, label, align, side, importTemplateLabel, exportTemplateLabel, importCsvLabel, exportCsvLabel, clearLabel, }: PlateMapEditorProps<T>): import("react/jsx-runtime").JSX.Element;
 export { Badge as PlateBadge };