@toolbox-web/grid 2.5.0 → 2.7.0

package/lib/core/internal/aria.d.ts

@@ -10,8 +10,12 @@ export interface AriaState {
     colCount: number;
     /** Last set aria-label */
     ariaLabel: string | undefined;
+    /** Last set aria-labelledby */
+    ariaLabelledBy: string | undefined;
     /** Last set aria-describedby */
     ariaDescribedBy: string | undefined;
+    /** Last set aria-roledescription */
+    ariaRoleDescription: string | undefined;
     /** Last source row count announced via `dataLoaded`; used to suppress duplicate announcements */
     lastAnnouncedSourceCount: number;
 }

package/lib/core/types.d.ts

@@ -12,34 +12,6 @@ import { AfterCellRenderContext, AfterRowRenderContext, CellMouseEvent } from '.
  * @category Plugin Development
  */
 export type RowPositionEntry = RowPosition;
-/**
- * The compiled web component interface for DataGrid.
- *
- * This interface represents the `<tbw-grid>` custom element, combining
- * the public grid API with standard HTMLElement functionality.
- *
- * @example
- * ```typescript
- * // Query existing grid with type safety
- * import { queryGrid } from '@toolbox-web/grid';
- * const grid = queryGrid<Employee>('tbw-grid');
- * grid.rows = employees;
- * grid.on('cell-click', (detail) => console.log(detail));
- *
- * // Create grid programmatically
- * import { createGrid } from '@toolbox-web/grid';
- * const grid = createGrid<Employee>({
- *   columns: [{ field: 'name' }, { field: 'email' }],
- * });
- * document.body.appendChild(grid);
- * ```
- *
- * @see {@link PublicGrid} for the public API methods and properties
- * @see {@link createGrid} for typed grid creation
- * @see {@link queryGrid} for typed grid querying
- */
-export interface DataGridElement extends PublicGrid, HTMLElement {
-}
 /**
  * Options for the {@link PublicGrid.scrollToRow} method.
  *
@@ -1287,7 +1259,7 @@ export interface ColumnEditorContext<TRow = any, TValue = any> {
      *
      * @see {@link CellRenderContext.grid}
      */
-    grid?: DataGridElement;
+    grid?: PublicGrid<TRow> & HTMLElement;
 }
 /**
  * Context passed to custom view renderers (pure display – no commit helpers).
@@ -1343,7 +1315,7 @@ export interface CellRenderContext<TRow = any, TValue = any> {
      * };
      * ```
      */
-    grid?: DataGridElement;
+    grid?: PublicGrid<TRow> & HTMLElement;
     /**
      * The cell DOM element being rendered into.
      * Framework adapters can use this to cache per-cell state (e.g., React roots).
@@ -2521,12 +2493,36 @@ export interface GridConfig<TRow = any> {
      *
      * If not provided and `shell.header.title` is set, the title is used automatically.
      *
+     * If [`gridAriaLabelledBy`](#gridarialabelledby) is also set, `aria-labelledby`
+     * takes precedence per WAI-ARIA accessible-name computation and `aria-label`
+     * is omitted.
+     *
      * @example
      * ```ts
      * gridConfig = { gridAriaLabel: 'Employee data' };
      * ```
      */
     gridAriaLabel?: string;
+    /**
+     * ID of an element that labels the grid.
+     * Sets `aria-labelledby` on the grid's internal table element so screen
+     * readers can use the referenced element's text as the accessible name —
+     * useful when the grid already sits next to a heading.
+     *
+     * Per WAI-ARIA accessible-name precedence, `aria-labelledby` takes priority
+     * over `aria-label` and over the auto-derived shell title. When this option
+     * is set, the grid omits `aria-label` to avoid conflicting names.
+     *
+     * @example
+     * ```html
+     * <h2 id="grid-heading">Employees</h2>
+     * <tbw-grid></tbw-grid>
+     * ```
+     * ```ts
+     * gridConfig = { gridAriaLabelledBy: 'grid-heading' };
+     * ```
+     */
+    gridAriaLabelledBy?: string;
     /**
      * ID of an element that describes the grid.
      * Sets `aria-describedby` on the grid's internal table element.
@@ -2541,6 +2537,25 @@ export interface GridConfig<TRow = any> {
      * ```
      */
     gridAriaDescribedBy?: string;
+    /**
+     * Override the screen-reader-announced role name for the grid via
+     * `aria-roledescription`. Useful for localization (e.g. `"Tabell"` in
+     * Norwegian) or domain-specific naming (e.g. `"Employee table"`).
+     *
+     * :::caution
+     * Per [WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/#aria-roledescription),
+     * the value should still describe a grid-like widget. Overriding with an
+     * unrelated label confuses assistive-technology users about the available
+     * interactions (cell navigation, sort, etc.). Leave unset to use the
+     * default role name announced by the AT.
+     * :::
+     *
+     * @example
+     * ```ts
+     * gridConfig = { gridAriaRoleDescription: 'Employee table' };
+     * ```
+     */
+    gridAriaRoleDescription?: string;
     /**
      * Accessibility configuration for screen reader announcements.
      *
@@ -3576,6 +3591,34 @@ export interface ColumnResizeDetail {
     /** New width in pixels. */
     width: number;
 }
+/**
+ * Column resize-reset event detail.
+ *
+ * Fired when a user-resized column is restored to its original configured width
+ * (e.g., via the column header context menu "Reset width" action). The `width`
+ * field reflects the column's `__originalWidth` and may be `undefined` if the
+ * column was originally auto-sized.
+ *
+ * @example
+ * ```typescript
+ * grid.on('column-resize-reset', ({ field, width }) => {
+ *   if (width === undefined) {
+ *     console.log(`Column ${field} restored to auto-size`);
+ *   } else {
+ *     console.log(`Column ${field} restored to ${width}px`);
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link ColumnResizeDetail} for the resize-in-progress event
+ * @category Events
+ */
+export interface ColumnResizeResetDetail {
+    /** Reset column field key. */
+    field: string;
+    /** Original configured width in pixels, or `undefined` if auto-sized. */
+    width: number | undefined;
+}
 /**
  * Trigger type for cell activation.
  * - `'keyboard'`: Enter key pressed on focused cell
@@ -3714,7 +3757,6 @@ export interface ExternalMountEditorDetail<TRow = unknown> {
  *
  * @see {@link DataGridElement.on} for the recommended subscription API
  * @see {@link DataGridCustomEvent} for typed CustomEvent wrapper
- * @see {@link DGEvents} for event name constants
  * @category Events
  */
 export interface DataGridEventMap<TRow = unknown> {
@@ -3931,6 +3973,23 @@ export interface DataGridEventMap<TRow = unknown> {
      * @group Core Events
      */
     'column-resize': ColumnResizeDetail;
+    /**
+     * Fired when a user-resized column is reset to its original configured width.
+     * Triggered by the column header context menu "Reset width" action.
+     *
+     * @example
+     * ```typescript
+     * grid.on('column-resize-reset', ({ field, width }) => {
+     *   const widths = JSON.parse(localStorage.getItem('col-widths') ?? '{}');
+     *   delete widths[field];
+     *   localStorage.setItem('col-widths', JSON.stringify(widths));
+     * });
+     * ```
+     *
+     * @see {@link ColumnResizeResetDetail}
+     * @group Core Events
+     */
+    'column-resize-reset': ColumnResizeResetDetail;
     /**
      * Fired when column state changes — reordering, resizing, visibility toggle,
      * or sort changes. Use with `getColumnState()` / `columnState` setter for

package/lib/features/sticky-rows.d.ts

@@ -0,0 +1,9 @@
+import { StickyRowsConfig } from '../plugins/sticky-rows';
+declare module '../core/types' {
+    interface FeatureConfig {
+        /** Pin selected data rows below the header as the user scrolls past them. */
+        stickyRows?: StickyRowsConfig;
+    }
+}
+/** @internal Type anchor — forces bundlers to preserve this module's FeatureConfig augmentation when re-exported. */
+export type _Augmentation = true;

package/lib/features/sticky-rows.js

@@ -0,0 +1,2 @@
+import{StickyRowsPlugin as o}from"@toolbox-web/grid/plugins/sticky-rows";import{registerFeature as i}from"@toolbox-web/grid/features/registry";i("stickyRows",i=>new o(i??{isSticky:()=>!1}));
+//# sourceMappingURL=sticky-rows.js.map

package/lib/features/sticky-rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sticky-rows.js","sources":["../../../../../libs/grid/src/lib/features/sticky-rows.ts"],"sourcesContent":["/**\n * Sticky Rows feature for @toolbox-web/grid\n *\n * @example\n * ```typescript\n * import '@toolbox-web/grid/features/sticky-rows';\n *\n * grid.gridConfig = { features: { stickyRows: { isSticky: 'isSection' } } };\n * ```\n */\n\nimport { StickyRowsPlugin, type StickyRowsConfig } from '../plugins/sticky-rows';\nimport { registerFeature } from './registry';\n\ndeclare module '../core/types' {\n  interface FeatureConfig {\n    /** Pin selected data rows below the header as the user scrolls past them. */\n    stickyRows?: StickyRowsConfig;\n  }\n}\n\nregisterFeature('stickyRows', (config) => {\n  // `stickyRows` requires an `isSticky` value — `boolean` shorthand is not\n  // meaningful. The TS type prevents `true`/`false` callers from compiling;\n  // at runtime we coerce to a no-op predicate for safety.\n  const options = (config as StickyRowsConfig | undefined) ?? { isSticky: () => false };\n  return new StickyRowsPlugin(options);\n});\n\n/** @internal Type anchor — forces bundlers to preserve this module's FeatureConfig augmentation when re-exported. */\nexport type _Augmentation = true;\n"],"names":["registerFeature","config","StickyRowsPlugin","isSticky"],"mappings":"+IAqBAA,EAAgB,aAAeC,GAKtB,IAAIC,EADMD,GAA2C,CAAEE,SAAU,KAAM"}