@arbidocs/blocks 0.4.95 → 0.4.97

package/dist/files/views/gridViews.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Saved grid views: the model behind the views menu of an AG Grid table (the Files table, a
+ * database). A view is a named layout: which columns show and in what order, their widths, and, for
+ * a grid that has them, the row height and the Gallery zoom. Pure functions over the grid's column
+ * state, so a host persists views however it likes (user settings, …) and the same rules decide
+ * which view is on screen everywhere.
+ */
+import type { GridApi } from 'ag-grid-community';
+/** AG Grid's own row-selection checkbox column: never part of a view. */
+export declare const SELECTION_COL_ID = "ag-Grid-SelectionColumn";
+/** A saved (or built-in) layout of a grid. Field names follow the API's `TableView`. */
+export interface SavedGridView {
+    name: string;
+    /** Visible columns, in order. */
+    columns: string[];
+    /** colId → width (px) of the columns that have a fixed width (flex columns are never stored). */
+    column_widths?: Record<string, number> | null;
+    /** Gallery zoom (tile width), for a grid that has a Gallery. */
+    tile_size?: number | null;
+    /** Table row height (px). */
+    row_height?: number | null;
+    /**
+     * Built-ins only: the columns to pin left when the view loads (`[]` unpins everything). Saved
+     * views never carry it, so loading one leaves pins alone.
+     */
+    pinned_left?: string[];
+}
+/** The live columns of a grid: visible ones (in order) and every column. */
+export interface GridColumnsSnapshot {
+    visible: string[];
+    /** colId → header name, in the grid's current order (hidden columns too). */
+    all: Array<{
+        colId: string;
+        label: string;
+    }>;
+    widths: Map<string, number | undefined>;
+    pinnedLeft: Set<string>;
+}
+/** Visible columns of the grid, in order, without the ignored ones (the selection column, …). */
+export declare function visibleColumns<T>(api: GridApi<T> | null, ignored: ReadonlySet<string>, fallback: string[]): string[];
+/**
+ * Does `viewColumns` match the visible columns? Same set in the same order, ignoring columns of the
+ * view the grid no longer has (a deleted field).
+ */
+export declare function columnsMatch<T>(api: GridApi<T> | null, current: string[], viewColumns: string[]): boolean;
+/**
+ * Do the view's stored widths still match the grid? Only columns the view stored a width for count
+ * (flex columns are never stored), so a window resize re-flexing a column cannot flip the view.
+ */
+export declare function widthsMatch<T>(api: GridApi<T> | null, widths: SavedGridView['column_widths']): boolean;
+/** Ids of the columns pinned left right now. */
+export declare function pinnedLeftColumns<T>(api: GridApi<T> | null): Set<string>;
+/** Widths of the visible fixed-width columns, to store with a view. */
+export declare function captureColumnWidths<T>(api: GridApi<T> | null, ignored: ReadonlySet<string>): Record<string, number>;
+/**
+ * Every column (but the ignored ones) for the menu's field list, in a stable order: `canonical`
+ * first (the default view's order), then the rest as the grid has them.
+ */
+export declare function columnItems<T>(api: GridApi<T> | null, visible: string[], canonical: string[], ignored: ReadonlySet<string>): Array<{
+    colId: string;
+    label: string;
+    hidden: boolean;
+}>;
+/**
+ * The visible columns after toggling `colId`: hidden, or shown again at its place in `canonical`
+ * (after the last visible column that comes before it). The last visible column stays.
+ */
+export declare function toggleColumn(current: string[], colId: string, canonical: string[]): string[];
+/**
+ * Show exactly `columns`, in that order (the selection column stays first), and hide the rest.
+ * Columns not yet in the grid's state get their definition's width.
+ */
+export declare function applyColumnLayout<T>(api: GridApi<T>, columns: string[]): void;
+/**
+ * Load a view's column layout: columns (`applyColumns`, default `applyColumnLayout`), then the
+ * stored widths, then the built-in's pins. Row height and zoom are the host's (it owns them).
+ */
+export declare function applyViewColumns<T>(api: GridApi<T>, view: SavedGridView, applyColumns?: (columns: string[], api: GridApi<T>) => void): void;
+/** Replace the view named like `view` (or add it), keeping the others in order. */
+export declare function upsertView<V extends SavedGridView>(views: V[], view: V): V[];

package/dist/files/views/index.d.ts

@@ -3,3 +3,5 @@ export { FieldRow, FieldsApplyBar, FieldsEditorList, FieldsEditorRoot, FieldsEdi
 export { fieldsApplyBarCopy, fieldsEmptyText, filterFieldsByName, sortFields, type FieldsApplyBarCopy, type FieldsApplyBarCopyInput, type SortableField, } from './fieldsEditorModel';
 export { FieldsManagerBody, FieldsManagerDefinition, FieldsManagerTitle, type FieldsManagerTitleProps, } from './FieldsManagerParts';
 export { TagFormRoot, TagFormField, TagFormNameField, TagFormSelectField, TagFormNote, TagFormOptionsEditor, TagFormInstructionField, TagFormMeta, TagFormFooter, TagFormSharedToggle, type TagFormFieldProps, type TagFormNameFieldProps, type TagFormSelectOption, type TagFormSelectFieldProps, type TagFormOptionsEditorProps, type TagFormInstructionFieldProps, type TagFormMetaLine, type TagFormFooterProps, } from './TagFormParts';
+export { SELECTION_COL_ID, applyColumnLayout, applyViewColumns, captureColumnWidths, columnItems, columnsMatch, pinnedLeftColumns, toggleColumn, upsertView, visibleColumns, widthsMatch, type SavedGridView, } from './gridViews';
+export { useGridViews, type GridBuiltinView, type GridViewsMenuProps, type UseGridViewsOptions, } from './useGridViews';

package/dist/files/views/useGridViews.d.ts

@@ -0,0 +1,38 @@
+import type { GridApi } from 'ag-grid-community';
+import type { ViewBuiltinItem, ViewSelectorMenuProps } from './ViewSelectorMenu';
+import { type SavedGridView } from './gridViews';
+/** A view that ships with the grid (keyed by a stable id, so renaming its label keeps it matching). */
+export interface GridBuiltinView extends ViewBuiltinItem {
+    columns: string[];
+    /** The row height the view loads with (and must match to be active). */
+    rowHeight?: number;
+    /** Columns pinned left by this view (`[]`: none, the selection column unpinned). */
+    pinnedLeft?: string[];
+}
+export interface UseGridViewsOptions<T, V extends SavedGridView> {
+    getGridApi: () => GridApi<T> | null;
+    /** The default view's columns: also the stable order of the field list. */
+    defaultColumns: string[];
+    builtins: GridBuiltinView[];
+    savedViews: V[];
+    /** Changes whenever the grid's column state changes (recomputes the active view). */
+    stateVersion?: unknown;
+    /** Columns never part of a view besides the selection column (an "add a column" column…). */
+    ignoredColumns?: string[];
+    /** Current layout outside the grid; omitted, it never decides which view is active. */
+    currentRowHeight?: number;
+    currentTileSize?: number;
+    /** The Gallery zoom the built-ins load with. */
+    defaultTileSize?: number;
+    /** Show these columns in this order (a field toggled in the menu). */
+    onApplyColumns: (columns: string[], api: GridApi<T>) => void;
+    /** Restore a whole view (built-in or saved): columns, widths, pins, row height, zoom. */
+    onLoadView: (view: SavedGridView | V, api: GridApi<T>) => void;
+    /** Store a view (replacing one of the same name); resolve once stored. */
+    onSaveView: (view: SavedGridView) => Promise<unknown> | void;
+    /** Delete a saved view; resolve `false` if it was not deleted (e.g. not confirmed). */
+    onDeleteView: (name: string) => Promise<boolean | void> | boolean | void;
+    isSaving?: boolean;
+}
+export type GridViewsMenuProps = Omit<ViewSelectorMenuProps, 'labels' | 'testIds' | 'className'>;
+export declare function useGridViews<T, V extends SavedGridView>({ getGridApi, defaultColumns, builtins, savedViews, stateVersion, ignoredColumns, currentRowHeight, currentTileSize, defaultTileSize, onApplyColumns, onLoadView, onSaveView, onDeleteView, isSaving, }: UseGridViewsOptions<T, V>): GridViewsMenuProps;