@svgrid/grid 3.0.4 → 3.0.6

package/dist/SvGrid.types.d.ts

@@ -1,4 +1,5 @@
 import type { Snippet } from "svelte";
+import type { GridRowModel } from "./row-model.js";
 import type { CellEditorType, ColumnDef, RowData, SvGridApi, TableFeatures } from "./index.js";
 import type { ConditionalFormat } from "./conditional-formatting.js";
 import type { GroupDisplayType } from "./group-display.js";
@@ -1074,8 +1075,256 @@ export type SchedulerConfig<TFeatures extends TableFeatures = TableFeatures, TDa
     searchable?: boolean;
     searchPlaceholder?: string;
 };
+/**
+ * The Gantt axis presets: which unit is a tick and which is the coarser row
+ * grouping them. `week` (day ticks under month majors) is the default.
+ */
+export type GanttZoom = "day" | "week" | "month" | "quarter" | "year";
+/**
+ * The four classic dependency kinds. `FS` (finish-to-start) is the default:
+ * the successor may not start before the predecessor finishes.
+ */
+export type GanttDependencyType = "FS" | "SS" | "FF" | "SF";
+/**
+ * A link from a predecessor task (`from`) to a successor (`to`). Both are row
+ * ids (the grid's `getRowId`). `lag` is in DAYS - negative for a lead, so
+ * `{ type: 'FS', lag: -1 }` lets the successor start a day before the
+ * predecessor finishes.
+ */
+export type GanttDependency = {
+    id: string;
+    from: string;
+    to: string;
+    type?: GanttDependencyType;
+    lag?: number;
+};
+/** Fired when a task bar is dragged to new dates. {@link GanttConfig.onTaskMove}. */
+export type GanttTaskMoveEvent<TData extends RowData = RowData> = {
+    row: TData;
+    start: Date;
+    end: Date;
+    /**
+     * The moved row's descendants, shifted by the same delta - present only when
+     * a summary (parent) bar was dragged. Cascaded successors are NOT here; they
+     * arrive through {@link GanttConfig.onDependenciesChange}.
+     */
+    subtree?: Array<{
+        row: TData;
+        start: Date;
+        end: Date;
+    }>;
+};
+/** Fired when a task bar's edge is dragged. {@link GanttConfig.onTaskResize}. */
+export type GanttTaskResizeEvent<TData extends RowData = RowData> = {
+    row: TData;
+    start: Date;
+    end: Date;
+    /** Which edge the user dragged. */
+    edge: "start" | "end";
+};
+/** Fired when a bar's progress grip is dragged. {@link GanttConfig.onProgressChange}. */
+export type GanttProgressChangeEvent<TData extends RowData = RowData> = {
+    row: TData;
+    /** 0-100, in whole percent. */
+    progress: number;
+};
+/** Fired when the Gantt's detail drawer is saved. {@link GanttConfig.onTaskCommit}. */
+export type GanttTaskCommitEvent<TData extends RowData = RowData> = {
+    row: TData;
+    values: Partial<TData>;
+};
+/**
+ * The Gantt's built-in task drawer. Same shape as the scheduler's - a field
+ * list, a title and a width - so one drawer config type covers both views.
+ */
+export type GanttDrawerConfig<TData extends RowData = RowData> = SchedulerDrawerConfig<TData>;
+/**
+ * Turns the grid into a Gantt chart. Set `gantt` and the grid renders its rows
+ * as a task table beside a time chart: one bar per row positioned by start /
+ * end, nested into a work-breakdown tree by `parentField`, with dependency
+ * arrows between linked tasks.
+ *
+ * Like the Kanban board and the scheduler it is a pure *view of the grid*: it
+ * renders the grid's filtered + sorted rows and writes back only through
+ * callbacks, never mutating your data. Dragging a bar fires
+ * {@link GanttConfig.onTaskMove} where you reassign the dates on your own rows.
+ *
+ * Dates are local calendar days and `end` is EXCLUSIVE, except that a date-only
+ * string (`'2026-09-14'`, no time part) is read as the end OF that day - the
+ * inclusive convention planning tools use. So
+ * `{ start: '2026-09-14', end: '2026-09-16' }` draws a three-day bar.
+ */
+export type GanttConfig<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData> = {
+    /** Field holding each task's start (`Date` | epoch-ms | ISO string). Required. */
+    startField: keyof TData & string;
+    /** Field holding the end. Omit to use `durationField`, else the task is a milestone. */
+    endField?: keyof TData & string;
+    /** Field holding the length in WORKING days, used when `endField` is absent. */
+    durationField?: keyof TData & string;
+    /** Field for the task name. Defaults to the first column's field. */
+    titleField?: keyof TData & string;
+    /** Field holding percent complete (0-100). Drives the bar's inner fill. */
+    progressField?: keyof TData & string;
+    /**
+     * Field holding each row's PARENT task id, nesting the flat rows into a
+     * work-breakdown tree. Parents render a rolled-up summary bar and a collapse
+     * chevron. Rows whose parent is missing become roots rather than vanishing.
+     *
+     * This is the Gantt's own tree - do NOT also set the grid's `treeData` prop.
+     * `treeData` hides collapsed children from the view entirely, which would
+     * drop them out of their phase's summary bar.
+     */
+    parentField?: keyof TData & string;
+    /**
+     * Boolean field marking a task as a milestone (a diamond, no length). A task
+     * whose end equals its start renders as one regardless.
+     */
+    milestoneField?: keyof TData & string;
+    /** Field holding a per-task accent color (any CSS color). Else `color`. */
+    colorField?: keyof TData & string;
+    /** Fallback accent color for every bar. */
+    color?: string;
+    /**
+     * Predecessor -> successor links, drawn as arrows between bars. `from` / `to`
+     * are row ids (your `getRowId`). See {@link GanttDependency}.
+     */
+    dependencies?: ReadonlyArray<GanttDependency>;
+    /**
+     * Per-row field holding that row's links (as `GanttDependency[]` or a plain
+     * list of successor ids). An alternative to the flat `dependencies` array.
+     */
+    dependencyField?: keyof TData & string;
+    /**
+     * Cascade successors forward on move / resize so every link stays legal,
+     * preserving each task's duration. Defaults to `true` when any dependency is
+     * present. Cascading never pulls a task earlier.
+     */
+    autoReschedule?: boolean;
+    /**
+     * Schedule in working time (see `nonWorkingDays` / `holidays`): a moved
+     * or cascaded task lands on a working day and keeps its WORKING length, so
+     * a five-day task dragged over a weekend stays five days of work, and the
+     * critical path measures slack in working days. `false` schedules in
+     * calendar time. Default `true`.
+     */
+    respectWorkingTime?: boolean;
+    /** Fired with the cascaded shifts after a move / resize (never mutates rows). */
+    onDependenciesChange?: (moves: Array<{
+        id: string;
+        start: Date;
+        end: Date;
+    }>) => void;
+    /** Fired when the user draws a new link (drag from one bar's edge to another). */
+    onDependencyAdd?: (dep: GanttDependency) => void;
+    /** Fired when the user removes a link (arrow context menu). */
+    onDependencyRemove?: (id: string) => void;
+    /** The axis preset the chart opens on. Default `'week'`. */
+    zoom?: GanttZoom;
+    /**
+     * The presets the toolbar's zoom stepper offers. Default all five; a single
+     * entry hides the stepper.
+     */
+    zoomLevels?: ReadonlyArray<GanttZoom>;
+    /** Fired when the zoom preset changes (stepper or Ctrl+wheel). */
+    onZoomChange?: (zoom: GanttZoom) => void;
+    /** First day of the week, 0-6 (0 = Sunday). Default 0. */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Weekday numbers (0 = Sun ... 6 = Sat) that are non-working: shaded in the
+     * chart and skipped by duration + cascade arithmetic. Default `[0, 6]`.
+     */
+    nonWorkingDays?: ReadonlyArray<number>;
+    /** Specific dates that are non-working (holidays, closures). */
+    holidays?: ReadonlyArray<Date | number | string>;
+    /** Shade the non-working columns. Default `true`. */
+    showNonWorking?: boolean;
+    /** Draw the dashed "today" line across the chart. Default `true`. */
+    todayLine?: boolean;
+    /** Earliest date the axis shows and a drag may reach. */
+    minDate?: Date | number | string;
+    /** Latest date the axis shows and a drag may reach. */
+    maxDate?: Date | number | string;
+    /** Calendar days of slack around the first start / last end. Default 7. */
+    rangePaddingDays?: number;
+    /**
+     * Column ids shown in the task table, in order. Defaults to every leaf
+     * column. Two built-ins need no column definition: `'__duration'` (working
+     * days) and `'__progress'` (a small bar).
+     */
+    tableColumns?: ReadonlyArray<string>;
+    /** Width (px) of the task table pane. Default 360; a splitter resizes it. */
+    tableWidth?: number;
+    /** Height (px) of one task row. Default 32. */
+    rowHeight?: number;
+    /** Parents draw a rolled-up summary bar spanning their children. Default `true`. */
+    summaryBars?: boolean;
+    /**
+     * Where a bar's label sits: `'inside'` (default, falling back to the right
+     * when the bar is too narrow), always `'right'`, or `'none'`.
+     */
+    labelPosition?: "inside" | "right" | "none";
+    /**
+     * Controlled collapse: the ids of the parent rows whose children are hidden.
+     * Omit to let the Gantt own its own collapse state.
+     */
+    collapsed?: ReadonlyArray<string>;
+    /** Fired when a chevron (or Expand / Collapse all) changes the collapsed set. */
+    onCollapseChange?: (collapsed: string[]) => void;
+    /**
+     * Enable drag-to-move, edge resize, the progress grip and link drawing.
+     * Without it the chart is read-only.
+     */
+    editable?: boolean;
+    /**
+     * Enable undo / redo of move, resize and progress edits with `Ctrl/Cmd+Z` and
+     * `Ctrl/Cmd+Shift+Z` (or `Ctrl+Y`). The callbacks re-fire with the reversed
+     * values, so your data follows.
+     */
+    history?: boolean;
+    /** Fired when a bar is dragged to new dates. */
+    onTaskMove?: (event: GanttTaskMoveEvent<TData>) => void;
+    /** Fired when a bar's edge is dragged. */
+    onTaskResize?: (event: GanttTaskResizeEvent<TData>) => void;
+    /** Fired when the progress grip is dragged. */
+    onProgressChange?: (event: GanttProgressChangeEvent<TData>) => void;
+    /** Fired when empty chart space is double-clicked - create a task there. */
+    onTaskAdd?: (start: Date, end: Date, parentId?: string) => void;
+    /**
+     * Fired from the bar's Delete action. Setting this shows Delete in the
+     * drawer and the context menu. Remove the row from your data in the handler.
+     */
+    onTaskDelete?: (row: TData) => void;
+    /**
+     * Custom body for a TASK bar. Receives the row. Omit for the built-in label.
+     * A phase's summary bar is a thin spine with no room for a body, so it keeps
+     * its plain label; a milestone has no body at all.
+     */
+    task?: Snippet<[TData]>;
+    /**
+     * Hover tooltip for a bar. A `Snippet<[TData]>` for custom content, or `true`
+     * for the built-in one (title, dates, duration, percent). Omit to disable.
+     */
+    tooltip?: boolean | Snippet<[TData]>;
+    /** Delay (ms) before the hover tooltip opens. Default 400. */
+    tooltipDelay?: number;
+    /** Built-in task drawer: `true` for all fields, or a config object. */
+    drawer?: boolean | GanttDrawerConfig<TData>;
+    /** Fired when the drawer is saved. */
+    onTaskCommit?: (event: GanttTaskCommitEvent<TData>) => void;
+    /** Right-click menu for a bar. Return items or `undefined` to suppress. */
+    taskMenu?: (row: TData) => MenuItem[] | undefined;
+    /** Show the search box (binds to the grid's global filter). Default `true`. */
+    searchable?: boolean;
+    searchPlaceholder?: string;
+};
 export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData> = {
-    data: ReadonlyArray<TData>;
+    /**
+     * The rows to render.
+     *
+     * Optional only because `rowModel` can supply them instead; a grid with
+     * neither renders empty. When both are present `data` wins.
+     */
+    data?: ReadonlyArray<TData>;
     columns: Array<ColumnDef<TFeatures, TData>>;
     /**
      * Kanban board mode. When set, the grid renders its rows as cards in
@@ -1089,6 +1338,15 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * {@link SchedulerConfig}.
      */
     scheduler?: SchedulerConfig<TFeatures, TData>;
+    /**
+     * Gantt mode. When set, the grid renders its rows as a task table beside a
+     * time chart: one bar per row by start / end, a work-breakdown tree from
+     * `parentField`, and dependency arrows. See {@link GanttConfig}.
+     *
+     * A view of the grid like the board and scheduler; the renderer ships in
+     * `@svgrid/enterprise` (call `enableGanttView()`).
+     */
+    gantt?: GanttConfig<TFeatures, TData>;
     /**
      * Chart view. When set, the grid renders its FILTERED + SORTED rows as a chart
      * instead of a table (search / filters / sort flow through). Unlike board and
@@ -1694,6 +1952,15 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         rowIndex: number;
         columnId: string;
     }) => unknown;
+    /**
+     * Whether a collapsed row still takes part in a copy or a fill that
+     * spans it. Left out, both skip every collapsed row, which is what
+     * "filter, copy, paste" needs and what a fill dragged over a filtered
+     * list expects: the series runs over the rows that show. A spreadsheet
+     * answers per row: a row hidden by hand is copied and filled, as Excel
+     * does, while a row a filter folded away is not.
+     */
+    includeCollapsedRows?: (rowIndex: number) => boolean;
     /**
      * An HTML rendering of what Ctrl+C copies, written to the clipboard as
      * `text/html` beside the TSV. Excel and Google Sheets read the HTML
@@ -1857,10 +2124,11 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      */
     onRowSelectionChange?: (selection: Record<string, boolean>, rows: TData[]) => void;
     /**
-     * Fires whenever the cell-selection rectangle changes (mouse, keyboard,
-     * or `api.selectCells()`). `ranges` matches `api.getSelected()` -
-     * `[rowStart, colStart, rowEnd, colEnd]` rectangles in grid coords.
-     * Empty array when the user clears the selection.
+     * Fires whenever the cell selection changes (mouse, keyboard, or
+     * `api.selectCells()`). `ranges` is every selected rectangle, matching
+     * `api.getSelected()`: the ones a Ctrl+click committed and the active one
+     * last, each `[rowStart, colStart, rowEnd, colEnd]` in grid coords. Empty
+     * array when the user clears the selection.
      */
     onCellSelectionChange?: (ranges: Array<[number, number, number, number]>) => void;
     /**
@@ -2078,6 +2346,99 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         scrollHeight: number;
         clientHeight: number;
     }) => void;
+    /**
+     * Fires when the range of rows on screen changes, with the first and last
+     * row INDEX (not pixels). Coalesced to one call per frame, so it is cheap
+     * to wire to something that fetches.
+     *
+     * This is the hook a block-loading data source needs and
+     * `onScrollBottomReached` cannot give it: "the user is looking at rows
+     * 4,000-4,020" answers which block to fetch and which to keep, while
+     * "they hit the bottom" only ever means "append more". Both are free; use
+     * this one with `createServerDataSource({ mode: 'infinite' })`, or let
+     * `rowModel` wire it for you.
+     *
+     * Reports `0, data.length - 1` when virtualization is off, since every row
+     * really is rendered.
+     */
+    onVisibleRangeChange?: (range: {
+        startIndex: number;
+        endIndex: number;
+    }) => void;
+    /**
+     * Marks a row as one whose data has not arrived: `"loading"` draws a
+     * shimmer in every cell, `"failed"` draws a full-width "could not load"
+     * row with a Retry button, and `null` (the default for every row) renders
+     * normally.
+     *
+     * Placeholder rows are inert - not selectable, not editable, and skipped
+     * by cell navigation - because there is nothing there to act on yet.
+     *
+     * `createServerDataSource` in `infinite` mode fills the gaps with rows this
+     * recognises, so the usual wiring is `rowPlaceholder={rowPlaceholderState}`
+     * (or nothing at all, via `rowModel`).
+     */
+    rowPlaceholder?: (row: TData, rowIndex: number) => "loading" | "failed" | null;
+    /** Called by the Retry button on a `"failed"` placeholder row. */
+    onRetryRow?: (row: TData, rowIndex: number) => void;
+    /**
+     * Hand selection over to an external model.
+     *
+     * The grid normally tracks selection as a record of the row ids it has
+     * seen, which is right until the rows it has seen are a window onto a
+     * million on a server: "select all" then means 20 ticked checkboxes rather
+     * than a million, and the header checkbox cannot honestly say `all`. A
+     * model that stores the RULE ("everything except these three") can answer
+     * both, so when this is set the header checkbox, the row checkboxes and
+     * `api.selectAllRows()` all route through it instead.
+     *
+     * `@svgrid/enterprise` ships one for the server-side row model; this is the
+     * seam it plugs into.
+     */
+    /**
+     * Drive the grid from a row model instead of wiring a dozen props.
+     *
+     * `createServerDataSource` returns one, and so does the Enterprise
+     * server-side row model, so server-backed grids become:
+     *
+     * ```svelte
+     * <SvGrid rowModel={ctl} {columns} />
+     * ```
+     *
+     * The model supplies `data`, `loading`, `getRowId`, the external sort
+     * and filter wiring, the visible range, placeholder rows, group
+     * accessors, selection and paging - each one only if it implements that
+     * part. A prop written explicitly on the grid always wins, so you can
+     * adopt it and still override one piece.
+     */
+    rowModel?: GridRowModel<TData>;
+    /**
+     * Columns that REPLACE `columns` while set. The server-side row model
+     * supplies them in pivot mode - one column per pivoted value, grouped
+     * under a header per pivot key - and clears them when pivot mode ends,
+     * so `columns` stays the app's own list. Rarely set by hand.
+     */
+    pivotResultColumns?: Array<ColumnDef<TFeatures, TData>> | null;
+    rowSelectionModel?: {
+        isSelected: (rowId: string, row: TData) => boolean;
+        /** Whether the header checkbox shows empty, indeterminate, or ticked. */
+        headerState: () => "none" | "some" | "all";
+        toggle: (rowId: string, row: TData, next: boolean) => void;
+        /** The header checkbox: select or clear everything, loaded or not. */
+        toggleAll: (next: boolean) => void;
+        /**
+         * How many rows the rule selects, counting the ones the grid never
+         * loaded; `null` when it cannot say. The selection bar shows this
+         * instead of counting ticked rows on screen.
+         */
+        selectedCount?: () => number | null;
+        /**
+         * Apply one patch to every selected row, loaded or not. When present,
+         * the bulk-edit drawer sends its edits here instead of writing the
+         * loaded cells. Resolves with how many rows changed.
+         */
+        bulkUpdate?: (patch: Record<string, unknown>) => Promise<number>;
+    };
     /**
      * Marks a row as an expandable "detail row". When this returns true the
      * grid renders that row as a SINGLE full-width cell (colspan across every
@@ -2097,12 +2458,43 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         row: TData;
         rowIndex: number;
     }]>;
+    /**
+     * The height of a detail row, in px, or a function of its data. With it
+     * the virtualizer can size detail rows, so master-detail works with
+     * `virtualization` on (the panel scrolls inside its cell when taller).
+     * Without it a detail row is auto height, which needs
+     * `virtualization={false}`.
+     */
+    detailRowHeight?: number | ((row: TData) => number);
+    /**
+     * A row-header column of chevrons that open and close detail rows. It
+     * sits with the row-number and selection columns: sticky at the left,
+     * no column menu, not resizable, not reorderable, outside the active
+     * cell and the selection. The chevron calls `onDetailToggle` (or, on a
+     * server row model, the model's own toggle) and reads `isDetailOpen`
+     * for its direction; `hasDetail` hides it on rows that have nothing to
+     * open. Detail rows themselves get an empty cell.
+     */
+    showDetailToggle?: boolean;
+    /**
+     * Open or close the detail under a row. The chevron of `showDetailToggle`
+     * and Ctrl+Enter on a row call it; you keep the open set and insert or
+     * remove the detail row in `data`. A server row model supplies its own
+     * (the `rowModel` prop wires `toggleDetail`), so this is the client side.
+     */
+    onDetailToggle?: (row: TData, rowIndex: number) => void;
+    /** Whether the detail under a row is open: the chevron's direction and `aria-expanded`. */
+    isDetailOpen?: (row: TData) => boolean;
+    /** Whether a row has a detail to open; the chevron is left out where this returns false. */
+    hasDetail?: (row: TData) => boolean;
     /**
      * Server-side group / tree keyboard + accessibility, built into the grid. When
      * set, the grid uses the treegrid role and marks matching rows with
      * `aria-level` / `aria-expanded`, and ArrowRight / ArrowLeft expand / collapse
-     * the focused group row (no app-level key handling). Pair with `serverGroupRows`
-     * + `SvGroupCell` for the visual expander. Every accessor receives the row data.
+     * the focused group row (no app-level key handling). Pair with
+     * `serverGroupRows` + `SvGroupCell` from `@svgrid/enterprise` for the visual
+     * expander, or drive it from your own tree state. Every accessor receives the
+     * row data.
      */
     serverGroup?: {
         /** Whether a row is an expandable group / branch. */
@@ -2113,6 +2505,12 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         expanded?: (row: TData) => boolean;
         /** Expand / collapse a group row. Called on ArrowRight / ArrowLeft. */
         onToggle: (row: TData) => void;
+        /** Open / close the detail panel under a leaf. Called on Ctrl+Enter when `renderDetailRow` is set, and by the `showDetailToggle` chevron. */
+        toggleDetail?: (row: TData) => void;
+        /** Whether the detail under a leaf is open (the chevron's direction). */
+        detailOpen?: (row: TData) => boolean;
+        /** Whether a row can open a detail at all; a group, a placeholder or a detail row cannot. */
+        hasDetail?: (row: TData) => boolean;
     };
     /**
      * Server-side set-filter values. When set, a column's filter checklist is
@@ -2140,6 +2538,17 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * skips them.
      */
     frozenRows?: number;
+    /**
+     * Keep the group a row belongs to in view: while the rows of an open
+     * group scroll past, the group's row (and its parents' rows) stay under
+     * the header, the way a section heading stays put in a long list, so a
+     * screen deep inside a 60,000-row group still says which group it is.
+     * Works for server-side groups (`rowModel` / `serverGroup`), client
+     * grouping and tree data. Under `virtualization` the band shows a copy
+     * of each ancestor row; without it the rows themselves stick. Off by
+     * default.
+     */
+    stickyGroupRows?: boolean;
     /**
      * Merged cells: rectangles drawn as one cell, a spreadsheet's Merge &
      * Center. Each entry is the top-left cell (display indices) and how many
@@ -2221,6 +2630,23 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         fromGridId: number;
         toGridId: number;
     }) => void;
+    /**
+     * Take the drop yourself. With this set the grid keeps the drag
+     * affordance and the drop indicator but does not touch its data: the
+     * handler gets the dragged row, the row it landed on (null for the
+     * empty space below the rows) and the side - `before` / `after`, or
+     * `into` when it landed on the middle of a group or tree row, which
+     * makes it that row's child. The path for a `rowModel`, whose rows the
+     * grid does not own: hand the move to the model (`moveRow`) or to your
+     * server. Only fires within one grid; a drop from another grid stays
+     * managed.
+     */
+    onRowDrop?: (event: {
+        row: TData;
+        target: TData | null;
+        targetIndex: number | null;
+        side: "before" | "after" | "into";
+    }) => void;
     /**
      * Align this grid with others that share the same non-empty
      * `alignedGridGroup` string: horizontal scroll and column-resize widths are

package/dist/SvGridDropdown.svelte

@@ -45,6 +45,18 @@
      *  loading line instead of "No options", which would read as "nothing to
      *  pick" when the truth is "not here yet". */
     loading?: boolean
+    /**
+     * The trigger's element id, so a form's `<label for>` reaches it and
+     * clicking the label focuses it. Without one a select in a form was a
+     * button with no name.
+     */
+    id?: string
+    /** Accessible name for the trigger when no label points at `id`. */
+    ariaLabel?: string
+    /** Marks the trigger `aria-invalid`, the way an input in the same form is. */
+    invalid?: boolean
+    /** `aria-describedby` for the trigger: the error or help text of the field. */
+    describedBy?: string
   }
 
   let {
@@ -59,6 +71,10 @@
     onCommit,
     onCancel,
     loading = false,
+    id,
+    ariaLabel,
+    invalid = false,
+    describedBy,
   }: Props = $props()
 
   /** Stable per-instance id used to build option ids for
@@ -348,10 +364,14 @@
   <!-- svelte-ignore a11y_role_supports_aria_props_implicit -->
   <button
     type="button"
+    {id}
     class="sv-grid-dropdown-trigger"
     class:sv-grid-dropdown-trigger-chips={renderChipsInTrigger && selectedArr.length > 0}
     aria-haspopup="listbox"
     aria-expanded={open}
+    aria-label={ariaLabel}
+    aria-invalid={invalid || undefined}
+    aria-describedby={describedBy}
     aria-activedescendant={open ? optionId(highlighted) : undefined}
     bind:this={triggerEl}
     use:focusTrigger

package/dist/SvGridDropdown.svelte.d.ts

@@ -42,6 +42,18 @@ type Props = {
      *  loading line instead of "No options", which would read as "nothing to
      *  pick" when the truth is "not here yet". */
     loading?: boolean;
+    /**
+     * The trigger's element id, so a form's `<label for>` reaches it and
+     * clicking the label focuses it. Without one a select in a form was a
+     * button with no name.
+     */
+    id?: string;
+    /** Accessible name for the trigger when no label points at `id`. */
+    ariaLabel?: string;
+    /** Marks the trigger `aria-invalid`, the way an input in the same form is. */
+    invalid?: boolean;
+    /** `aria-describedby` for the trigger: the error or help text of the field. */
+    describedBy?: string;
 };
 declare const SvGridDropdown: import("svelte").Component<Props, {}, "">;
 type SvGridDropdown = ReturnType<typeof SvGridDropdown>;

package/dist/SvModal.svelte

@@ -16,6 +16,7 @@
   import { portalToBody } from './popover'
   import { nextEditorId } from './editor-contract'
   import { createOverlay } from './createOverlay.svelte'
+  import { getFocusable } from './a11y/focus-trap'
 
   type Props = {
     open?: boolean
@@ -33,6 +34,13 @@
     closeOnEsc?: boolean
     /** Hide the header close (x) button. */
     hideClose?: boolean
+    /**
+     * The element to focus when the dialog opens. Defaults to the first
+     * focusable control in the body or footer - never the header Close (x),
+     * so opening a dialog lands on its content and Enter does not dismiss it.
+     * Pass a getter to target a specific field (e.g. a search input).
+     */
+    initialFocus?: () => HTMLElement | null
     children?: Snippet
     footer?: Snippet
   }
@@ -48,6 +56,7 @@
     closeOnBackdrop = true,
     closeOnEsc = true,
     hideClose = false,
+    initialFocus,
     children,
     footer,
   }: Props = $props()
@@ -69,6 +78,19 @@
     closeOnEsc: () => closeOnEsc,
     closeOnBackdrop: () => closeOnBackdrop,
     onOpen: () => { drag = { x: 0, y: 0 }; box = null },
+    // Land focus on the dialog's content, not the header Close (x). The x is
+    // the first focusable in DOM order, so the trap's "first focusable"
+    // default sent focus there - where Enter immediately dismissed the
+    // dialog and the loud focus ring pointed at "close" over the primary
+    // action. Prefer the first focusable outside the header; fall back to the
+    // panel itself when the body has no control of its own.
+    initialFocus: () => {
+      const explicit = initialFocus?.()
+      if (explicit) return explicit
+      if (!dialogEl) return null
+      const first = getFocusable(dialogEl).find((el) => !el.closest('.sv-modal__header'))
+      return first ?? dialogEl
+    },
   })
 
   // --- Drag (header) ---------------------------------------------------------

package/dist/SvModal.svelte.d.ts

@@ -28,6 +28,13 @@ type Props = {
     closeOnEsc?: boolean;
     /** Hide the header close (x) button. */
     hideClose?: boolean;
+    /**
+     * The element to focus when the dialog opens. Defaults to the first
+     * focusable control in the body or footer - never the header Close (x),
+     * so opening a dialog lands on its content and Enter does not dismiss it.
+     * Pass a getter to target a specific field (e.g. a search input).
+     */
+    initialFocus?: () => HTMLElement | null;
     children?: Snippet;
     footer?: Snippet;
 };

package/dist/a11y/dismissable.d.ts

@@ -37,6 +37,16 @@ export declare function dismissableDepth(): number;
  * window listener gets wrong: inner scroll containers don't bubble, so the
  * capture listener sees them and dismisses the panel the user is scrolling.
  *
+ * The listener arms one animation frame after it is asked for, not at once.
+ * Scroll events are queued and dispatched in the next rendering step, so a
+ * scroll that FINISHED before the click that opened the panel - the browser
+ * pulling a half-hidden funnel button into view as it focuses it, a test
+ * driver scrolling the header into place - still lands after the panel has
+ * mounted and wired this listener, and used to close it on the spot. The
+ * panel measured its anchor after that scroll, so the event carries nothing
+ * it needs to react to. Rendering runs the scroll steps before the animation
+ * frame callbacks, which is why one frame is exactly the right delay.
+ *
  * Returns the unsubscribe function.
  */
 export declare function onScrollOutside(element: () => DismissTarget, onOutside: () => void): () => void;