@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/frontend/application/src/@aurora/modules/dashboard/components/dashboard-grid/dashboard-grid.component.ts

@@ -0,0 +1,776 @@
+import { NgTemplateOutlet } from '@angular/common';
+import {
+  afterNextRender,
+  afterRenderEffect,
+  Component,
+  ElementRef,
+  inject,
+  input,
+  OnDestroy,
+  output,
+  TemplateRef,
+  ViewEncapsulation,
+} from '@angular/core';
+import {
+  GridStack,
+  type GridItemHTMLElement,
+  type GridStackNode,
+  type GridStackOptions,
+} from 'gridstack';
+import type { AuroraWidgetSpan } from '../../../widget/aurora-widget-def';
+import {
+  buildDockPacking,
+  buildResponsiveColumnOpts,
+  currentViewportWidth,
+  dockColsForViewport,
+  dockTileWidth,
+  FIXED_CELL_RESIZE_DISABLED,
+  isEditableAtWidth,
+  mapItemGeometry,
+  mapResizeGeometry,
+} from './dashboard-grid.helpers';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Rendering mode for `<au-dashboard-grid>`.
+ *
+ * - `'grid'` (default): the standard responsive multi-row dashboard grid (12 columns, responsive
+ *   breakpoints, vertical growth).
+ * - `'dock'`: a single-row horizontal-scrolling strip. Tile width is computed from the container
+ *   breakpoint so a row of dock tiles matches the others-grid card width (4 fill the container at
+ *   desktop); when there are more tiles than fit the grid grows wider than its container, enabling
+ *   `overflow-x: auto` scrolling in the parent wrapper. `editableByWidthChange` is suppressed — dock
+ *   editing is governed solely by `editMode`.
+ * - `'grid-fixed'`: a 2D wrapping grid of equal-sized tiles. Column count mirrors the dock/others
+ *   breakpoints (`dockColsForViewport`); the grid fills 100% of the container width so each
+ *   1×1 tile matches the dock tile width. Items wrap to additional rows; no scroll, no maxRow.
+ *   `disableResize:true` — all tiles are equal size. On drag-stop, emits `itemChange` (moved tile
+ *   only) and `layoutChange` (the full settled layout read from the live engine), which the consumer
+ *   persists directly as each tile's `(x, y)`. `editableByWidthChange` is NOT emitted.
+ */
+export type DashboardGridMode = 'grid' | 'dock' | 'grid-fixed';
+
+/** A placed widget item with its grid position, span constraints, and widget id. */
+export interface DashboardGridItem {
+  /** Widget's globally unique namespaced id (maps to `AuroraWidgetDef.id`). */
+  id: string;
+  x: number;
+  y: number;
+  cols: number;
+  rows: number;
+  /** Span constraints used to enforce min/max at resize time. */
+  span: AuroraWidgetSpan;
+}
+
+/** The geometry payload emitted by `itemChange` and `itemResize`. */
+export interface DashboardGridItemGeometry {
+  id: string;
+  x: number;
+  y: number;
+  cols: number;
+  rows: number;
+}
+
+/** Context shape passed to the consumer's `tileTemplate` for each placed item. */
+export interface DashboardGridTileContext {
+  /** The item this template instance renders (`let-item` in the consumer template). */
+  $implicit: DashboardGridItem;
+}
+
+// ── Grid config constants ─────────────────────────────────────────────────────
+
+const GRID_COLUMNS = 12;
+/** Cell height in px — keeps the previous gridster fixed-row footprint (~105px tall cells). */
+const CELL_HEIGHT = 105;
+
+/**
+ * Tile height (px) for dock mode. Gridstack subtracts `2 × margin` from `cellHeight` for the
+ * `.grid-stack-item-content` box, so the card's usable area is `DOCK_TILE_HEIGHT − 2 × DOCK_MARGIN`.
+ * We size that usable area to an "others"-grid card with a one-line description so a favorite has the
+ * same footprint AND its description is visible (not collapsed to a clipped sliver):
+ *   fixed parts ≈ 132 (4 border-t-4 + 40 p-5 + 40 icon row + 2×16 gap-4 + ~16 "Open →") + 20 (1-line
+ *   text-sm description) ≈ 152 content area → cellHeight = 152 + 2 × 8 = 168.
+ * Longer descriptions clip via the card's own `line-clamp-3`; the common 1-line case sits flush.
+ */
+export const DOCK_TILE_HEIGHT = 168;
+/** Gap between dock tiles (px) — equals the grid margin for visual consistency. */
+const DOCK_MARGIN = 8;
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+/**
+ * Facade component wrapping Gridstack (vanilla core, NOT the `gridstack/dist/angular`
+ * wrapper). Consumers never import Gridstack directly; all layout interaction goes through
+ * this component's inputs and outputs.
+ *
+ * ## Why the vanilla core and not the official Angular wrapper
+ * The previous engine (angular-gridster2) recomputed its `$options` object on every change
+ * detection pass, so under Angular's zoneless change detection (the default since v21) it never
+ * stabilized → NG0103 infinite change detection. We could not fix that from the consumer side.
+ * The official Gridstack Angular wrapper (`GridstackComponent`) also runs `Default` change
+ * detection and is not instrumented for zoneless. So we drive the VANILLA core ourselves: it
+ * owns the layout DOM and mutates it directly, and Angular is notified ONLY on the TERMINAL
+ * `dragstop` / `resizestop` events (and the width observer) — never per mousemove. Those
+ * handlers emit outputs whose consumers write signals, which is what schedules change detection
+ * in this zoneless app; no `NgZone` plumbing is needed.
+ *
+ * ## Content projection (the design challenge)
+ * Gridstack owns the layout DOM of each `.grid-stack-item`. A single `<ng-content>` cannot
+ * project per-item, so the consumer passes a `tileTemplate` (a `TemplateRef`) and we render
+ * it inside each item's `.grid-stack-item-content` via `ngTemplateOutlet`, handing the item
+ * as `$implicit` context. This keeps the widget/tile contract intact — only the page↔grid
+ * wiring moves from `<ng-content>` to a template ref.
+ *
+ * ## items() ↔ Gridstack synchronization
+ * - Geometry (drag/resize): Gridstack is the live source of truth. We emit on the terminal
+ *   events and let the PARENT update its `items()` for the eventual save. We do NOT re-bind
+ *   that geometry back into Gridstack in the same gesture (that would feed back into a loop).
+ * - Membership (add/remove): Angular renders/removes the `.grid-stack-item` element via
+ *   `@for`. An `afterRenderEffect` reconciles the engine: it `makeWidget`s newly-rendered
+ *   elements and `removeWidget`s elements whose id left `items()` (engine-only removal;
+ *   Angular owns the DOM lifecycle).
+ *
+ * IMPORTANT: the host element MUST have an explicit height — Gridstack grows vertically from
+ * its cell rows, but the host should still fill its container. Set `class="h-full"`.
+ *
+ * @example Grid mode (default)
+ * ```html
+ * <au-dashboard-grid
+ *   class="h-full"
+ *   [items]="layoutItems()"
+ *   [editMode]="editMode()"
+ *   [tileTemplate]="tile"
+ *   (itemChange)="onItemChange($event)"
+ *   (itemResize)="onItemResize($event)"
+ * />
+ * <ng-template #tile let-item>
+ *   <au-dashboard-tile [editMode]="editMode()" (delete)="onDelete(item.id)">
+ *     <ng-container [ngComponentOutlet]="componentFor(item.id)" />
+ *   </au-dashboard-tile>
+ * </ng-template>
+ * ```
+ *
+ * @example Dock mode (horizontal-scrolling single-row strip)
+ * ```html
+ * <!-- Wrap in overflow-x-auto so the dock can scroll: -->
+ * <div class="hub-favorites-dock overflow-x-auto" auScrollFade>
+ *   <au-dashboard-grid
+ *     mode="dock"
+ *     [items]="dockItems()"
+ *     [editMode]="true"
+ *     [tileTemplate]="dockTile"
+ *     (itemChange)="onReorder($event)"
+ *   />
+ * </div>
+ * ```
+ */
+@Component({
+  selector: 'au-dashboard-grid',
+  imports: [NgTemplateOutlet],
+  // None: Gridstack manages the layout DOM and matches GLOBAL `.grid-stack*` selectors; emulated
+  // encapsulation would rewrite them to scoped attribute selectors and the engine CSS would miss.
+  // The styles still ship in this component's lazy chunk, not the eager global bundle.
+  encapsulation: ViewEncapsulation.None,
+  // Two stylesheets: the vendored Gridstack engine CSS first, then our theming overrides. Split so
+  // each stays under the per-file `anyComponentStyle` budget (see dashboard-grid.gridstack.css).
+  styleUrls: ['./dashboard-grid.gridstack.css', './dashboard-grid.component.css'],
+  host: {
+    class: 'block h-full',
+    // Dock mode marker — scopes the dock-only CSS overrides (e.g. neutralizing the
+    // .grid-stack-item-content chrome so the tile shows ONLY the hub-app-card). Standard
+    // 'grid' mode never gets this class, so the dashboard widget chrome is unaffected.
+    '[class.au-dashboard-grid--dock]': "mode() === 'dock'",
+    // Grid-fixed mode marker — same chrome neutralization as dock (no double-box), but
+    // multi-row wrapping. Scoped separately so the two tile modes can diverge in future.
+    '[class.au-dashboard-grid--grid-fixed]': "mode() === 'grid-fixed'",
+  },
+  template: `
+    <div class="grid-stack">
+      @for (item of items(); track item.id) {
+        <div
+          class="grid-stack-item"
+          [attr.gs-id]="item.id"
+          [attr.gs-x]="item.x"
+          [attr.gs-y]="item.y"
+          [attr.gs-w]="item.cols"
+          [attr.gs-h]="item.rows"
+          [attr.gs-min-w]="item.span.minCols"
+          [attr.gs-max-w]="item.span.maxCols"
+          [attr.gs-min-h]="item.span.minRows"
+          [attr.gs-max-h]="item.span.maxRows"
+        >
+          <div class="grid-stack-item-content">
+            @if (tileTemplate(); as tpl) {
+              <ng-container
+                [ngTemplateOutlet]="tpl"
+                [ngTemplateOutletContext]="{ $implicit: item }"
+              />
+            }
+          </div>
+        </div>
+      }
+    </div>
+  `,
+})
+export class AuDashboardGrid implements OnDestroy {
+  // ── DI ──────────────────────────────────────────────────────────────────────
+
+  private readonly host: ElementRef<HTMLElement> = inject(ElementRef);
+
+  // ── Inputs ──────────────────────────────────────────────────────────────────
+
+  /** Placed widget items with their geometry and span constraints. */
+  readonly items = input<DashboardGridItem[]>([]);
+
+  /**
+   * When `true`, drag and resize handles are active.
+   * When `false` (default/use mode), the grid is fully static.
+   */
+  readonly editMode = input<boolean>(false);
+
+  /**
+   * Per-item content template. Rendered inside each `.grid-stack-item-content` with the
+   * item as `$implicit` context. The consumer owns the tile chrome and widget projection.
+   */
+  readonly tileTemplate = input<TemplateRef<DashboardGridTileContext> | null>(null);
+
+  /**
+   * Rendering mode (default: `'grid'`).
+   * - `'grid'`: standard responsive multi-row dashboard (12 cols, responsive breakpoints).
+   * - `'dock'`: single-row horizontal strip. Tile width is computed from the container breakpoint
+   *   (4/3/2/1) to match the others-grid card width; the grid grows wider than its container when
+   *   there are more tiles than fit, enabling `overflow-x: auto` in the parent wrapper.
+   *   Wrap in a scrollable container with `auScrollFade` to get the edge-fade effect.
+   *   `editableByWidthChange` is NOT emitted in dock mode — use `editMode` directly.
+   * - `'grid-fixed'`: 2D wrapping fixed-cell grid. Columns = `dockColsForViewport` (4/3/2/1),
+   *   grid width = 100% container (no explicit px width), `cellHeight = DOCK_TILE_HEIGHT`.
+   *   Items wrap into multiple rows; no scroll. All tiles 1×1, not resizable.
+   *   On drag-stop emits `itemChange` (moved tile only) and `layoutChange` (full settled layout);
+   *   the consumer persists each tile's `(x, y)` directly.
+   *   `editableByWidthChange` is NOT emitted — use `editMode` directly.
+   */
+  readonly mode = input<DashboardGridMode>('grid');
+
+  // ── Outputs ─────────────────────────────────────────────────────────────────
+
+  /** Emitted when an item is moved (drag). Maps 1:1 to `DashboardLayoutItem`. */
+  readonly itemChange = output<DashboardGridItemGeometry>();
+
+  /** Emitted when an item is resized. Payload is clamped to the widget's span. */
+  readonly itemResize = output<DashboardGridItemGeometry>();
+
+  /**
+   * Emitted when the grid crosses the desktop/tablet width threshold — `true` when the grid is
+   * wide enough to edit (desktop), `false` below it. The page uses this to hide its edit
+   * affordances (Edit/Save/add-widget) so editing is only offered where it is actually allowed.
+   */
+  readonly editableByWidthChange = output<boolean>();
+
+  /**
+   * Emitted on dragstop in `dock` and `grid-fixed` modes with the COMPLETE settled layout —
+   * every managed node's live `{ id, x, y, cols, rows }` read directly from the engine. Use this
+   * (NOT `itemChange`, which carries only the moved tile) to persist reorder in those modes: the
+   * full layout reflects where gridstack actually settled EVERY tile, so the persisted order can
+   * never diverge from the visible one. NOT emitted in `'grid'` mode — `itemChange` serves that.
+   */
+  readonly layoutChange = output<DashboardGridItemGeometry[]>();
+
+  // ── Public API ────────────────────────────────────────────────────────────────
+
+  /**
+   * Reads the COMPLETE settled layout from the live Gridstack engine on demand — the same data
+   * `layoutChange` emits on dragstop, but available at any time (e.g. a consumer building a
+   * combined save payload from MULTIPLE grids, where only one grid emitted this gesture).
+   * Returns `[]` when the engine is not yet initialized (e.g. during tests with no DOM).
+   */
+  readLiveLayout(): DashboardGridItemGeometry[] {
+    return this.readFullLayout();
+  }
+
+  // ── Gridstack state (managed outside Angular's zone) ──────────────────────────
+
+  /** The live Gridstack instance. `null` until `afterNextRender` initializes it. */
+  private grid: GridStack | null = null;
+
+  /** Elements already converted to Gridstack widgets, keyed by item id. */
+  private readonly managed = new Map<string, GridItemHTMLElement>();
+
+  /** Whether the grid is currently wide enough to allow editing (desktop width). */
+  private editableByWidth = true;
+
+  /** Observes the grid's own width to drive the responsive edit gate. Disposed on destroy. */
+  private widthObserver: ResizeObserver | null = null;
+
+  constructor() {
+    // Initialize Gridstack once, after the first render (the `.grid-stack` DOM must exist).
+    afterNextRender(() => this.initGrid());
+
+    // Reconcile membership (add/remove) and edit-mode after every render that changed
+    // `items()` or `editMode()`. afterRenderEffect runs post-DOM, so newly `@for`-rendered
+    // `.grid-stack-item` elements already exist when we makeWidget() them. This is pure
+    // DOM/engine work — Gridstack owns its layout DOM and triggers no Angular change detection.
+    afterRenderEffect(() => {
+      this.reconcileMembership(this.items());
+      this.applyEditMode(this.editMode());
+    });
+  }
+
+  ngOnDestroy(): void {
+    this.widthObserver?.disconnect();
+    this.widthObserver = null;
+    this.grid?.destroy();
+    this.grid = null;
+    this.managed.clear();
+  }
+
+  // ── Gridstack lifecycle ───────────────────────────────────────────────────────
+
+  /** Boots the Gridstack engine on the host's `.grid-stack` element. */
+  private initGrid(): void {
+    const gridEl = this.host.nativeElement.querySelector<HTMLElement>('.grid-stack');
+    if (gridEl === null) {
+      return;
+    }
+
+    if (this.mode() === 'dock') {
+      this.initDock(gridEl);
+    } else if (this.mode() === 'grid-fixed') {
+      this.initGridFixed(gridEl);
+    } else {
+      this.initStandardGrid(gridEl);
+    }
+
+    // The effect that runs before initGrid saw no grid; reconcile once now so any items
+    // rendered after init but not auto-converted get picked up.
+    this.reconcileMembership(this.items());
+    this.applyEditMode(this.editMode());
+  }
+
+  // ── Shared init helpers (dock + grid-fixed fixed-cell modes) ──────────────────
+
+  /**
+   * Builds the gridstack options shared by the two fixed-cell modes (`dock`, `grid-fixed`):
+   * same cell height, margin, static gate, placeholder, grip-only drag, and disabled resize.
+   * Per-mode deltas (column source, `row`, etc.) are passed via `overrides`.
+   */
+  private buildFixedCellOptions(overrides: Partial<GridStackOptions>): GridStackOptions {
+    return {
+      cellHeight: DOCK_TILE_HEIGHT,
+      // float:false → items compact (vertical gravity); horizontal packing is done in repackDock.
+      float: false,
+      margin: DOCK_MARGIN,
+      // No columnOpts — the column count is managed per-mode (item count for dock, viewport
+      // breakpoints for grid-fixed), not by gridstack's own responsive reflow.
+      columnOpts: undefined,
+      staticGrid: !this.editMode(),
+      placeholderClass: 'au-grid-placeholder',
+      draggable: { handle: '.au-widget-drag-handle' },
+      // Disable resizing — both fixed-cell modes use equal-sized 1×1 tiles (drag-only). The CSS
+      // also hard-hides any handle gridstack still injects (see dashboard-grid.component.css).
+      ...FIXED_CELL_RESIZE_DISABLED,
+      ...overrides,
+    };
+  }
+
+  /**
+   * Registers gridstack's auto-converted children (they carry `gs-*` attrs) into `managed`,
+   * keyed by item id. Shared by every init path. No-op until the grid exists.
+   */
+  private registerExistingItems(): void {
+    if (this.grid === null) {
+      return;
+    }
+    for (const el of this.grid.getGridItems()) {
+      const id = el.gridstackNode?.id;
+      if (typeof id === 'string') {
+        this.managed.set(id, el);
+      }
+    }
+  }
+
+  /**
+   * Wires the terminal `dragstop` handler. Shared by every init path. NOT per-move — gridstack
+   * mutates its own DOM during the drag and only this terminal event re-enters Angular to emit.
+   */
+  private attachDragStop(): void {
+    this.grid?.on('dragstop', (_event: Event, el: GridItemHTMLElement) => this.onDragStop(el));
+  }
+
+  /**
+   * Initialises the standard multi-row responsive dashboard grid.
+   * Responsive breakpoints, width-gated edit mode, and `editableByWidthChange` output.
+   */
+  private initStandardGrid(gridEl: HTMLElement): void {
+    // Seed the edit gate from the grid's current width BEFORE init, so `staticGrid` starts correct.
+    this.editableByWidth = isEditableAtWidth(gridEl.clientWidth);
+
+    const options: GridStackOptions = {
+      column: GRID_COLUMNS,
+      cellHeight: CELL_HEIGHT,
+      // float:false → items compact upward; vertical growth is unbounded (no maxRow).
+      float: false,
+      margin: 8,
+      // Responsive: reflow by the grid's own width (12 → 6 → 1 columns) so widgets stay usable on
+      // tablet/phone instead of shrinking 12 fixed columns into uselessness. See the helper.
+      columnOpts: buildResponsiveColumnOpts(),
+      // Start static unless editing AND wide enough to edit; reconciliation keeps it in sync.
+      staticGrid: !this.isEffectivelyEditable(),
+      // Shadcn-styled placeholder. Drag ONLY from the tile's grip handle (`.au-widget-drag-
+      // handle`), never the whole content — so a widget's own clickable content (buttons,
+      // links, charts) stays interactive and a click never starts a drag.
+      placeholderClass: 'au-grid-placeholder',
+      draggable: { handle: '.au-widget-drag-handle' },
+    };
+
+    this.grid = GridStack.init(options, gridEl);
+
+    // init() auto-converts existing children (they carry gs-* attrs) — register them.
+    this.registerExistingItems();
+
+    // Terminal events only — re-enter the zone to emit. NOT drag/resize (per-move) events.
+    this.attachDragStop();
+    this.grid.on('resizestop', (_event, el) => this.onResizeStop(el));
+
+    // Watch the grid's OWN width to drive the desktop-only edit gate. Stays outside the zone;
+    // re-enters only to emit the terminal threshold-cross event. Gridstack handles the column
+    // reflow itself (via columnOpts) — this observer only governs whether editing is allowed.
+    this.widthObserver = new ResizeObserver((entries) => {
+      const width = entries[0]?.contentRect.width ?? gridEl.clientWidth;
+      // Drive the responsive column reflow from this (reliable) observer rather than depending
+      // solely on Gridstack's internal resize trigger: `onResize` re-evaluates the breakpoints
+      // for the current grid width and is idempotent, so it both collapses and RESTORES the
+      // cached 12-column layout when the grid widens again.
+      this.grid?.onResize(width);
+      this.applyEditableByWidth(isEditableAtWidth(width));
+    });
+    this.widthObserver.observe(gridEl);
+
+    // Emit the SEEDED editability once so the page syncs on a FRESH load at any width. Without
+    // this, a dashboard that loads directly at tablet/phone width never gets an emit (the
+    // observer's change-guard suppresses the no-op), leaving the page's `canEditByWidth` at its
+    // default `true` → edit affordances shown over a grid that is already static (dead clicks).
+    this.editableByWidthChange.emit(this.editableByWidth);
+  }
+
+  /**
+   * Initialises the dock (single-row horizontal-scroll strip) grid.
+   *
+   * Key differences from the standard grid:
+   * - `row: 1` — locks the grid to a single row (Gridstack shorthand for minRow:1, maxRow:1).
+   * - `column` = number of items — each item occupies exactly 1 column of a computed pixel width.
+   * - No `columnOpts` — responsive reflow is intentionally disabled; tile width comes from the
+   *   container breakpoint (see `applyDockWidth`) and the parent scroll container absorbs overflow.
+   * - explicit `width` on the grid element — sizes the `.grid-stack` to `itemCount × tileWidth`,
+   *   where `tileWidth = containerWidth / visibleCols` (visibleCols = 4/3/2/1 by breakpoint). This
+   *   makes each tile the SAME width as an others-grid card (4 fill the container at desktop). A
+   *   `min-width` instead would let Gridstack keep the element at 100% and stretch columns. Few
+   *   favorites → grid ≤ container, row fills/left-aligns; more than fit → grid overflows and the
+   *   `overflow-x: auto` parent scrolls with the `auScrollFade` edge fade.
+   * - a ResizeObserver on the host recomputes `tileWidth` on container resize (breakpoint tracking).
+   * - `editableByWidthChange` is NOT emitted — dock editability is controlled by `editMode` only.
+   */
+  private initDock(gridEl: HTMLElement): void {
+    const count = this.items().length;
+    const cols = Math.max(count, 1);
+
+    // One gridstack column per tile (`column: cols`) on a single locked row (`row: 1`); the rest
+    // of the options come from the shared fixed-cell base.
+    const options = this.buildFixedCellOptions({ column: cols, row: 1 });
+    this.grid = GridStack.init(options, gridEl);
+
+    // Apply the initial width: tiles sized to the container breakpoint (4/3/2/1 fill the width).
+    this.applyDockWidth(gridEl, cols);
+
+    // init() auto-converts existing children — register them, then wire the terminal drag event.
+    this.registerExistingItems();
+    this.attachDragStop();
+
+    // Recompute tile width on container resize (viewport change, sidebar collapse) so the dock
+    // tracks the same breakpoint counts as the others-grid. Observe the HOST (a block child of the
+    // scroll wrapper) — its width tracks the visible container, not the wider grid element. Stays
+    // outside Angular's zone; it only mutates the grid element's inline width (no change detection).
+    this.widthObserver = new ResizeObserver(() => {
+      this.applyDockWidth(gridEl, this.items().length);
+    });
+    this.widthObserver.observe(this.host.nativeElement);
+  }
+
+  /**
+   * Initialises the 2D wrapping fixed-cell grid (`grid-fixed` mode).
+   *
+   * Key differences from dock:
+   * - `column` = `dockColsForViewport(window.innerWidth)` — mirrors the Tailwind breakpoints so
+   *   tiles are the SAME width as dock tiles and old others-grid cards.
+   * - NO explicit width — the grid fills 100% of the container; gridstack divides the container
+   *   width by the column count, giving each tile ≈ container/cols (same as dock).
+   * - `cellHeight = DOCK_TILE_HEIGHT` — tiles are the same height as dock tiles.
+   * - NO `row` / `maxRow` — items wrap into as many rows as needed (unbounded vertical growth).
+   * - `float:false` — items compact to the top-left; gridstack handles the 2D packing.
+   * - `disableResize:true` — all tiles are 1×1, never resizable.
+   * - On viewport resize, `column()` is updated to the new breakpoint count so the grid reflows.
+   * - `editableByWidthChange` is NOT emitted — editability is controlled by `editMode` only.
+   */
+  private initGridFixed(gridEl: HTMLElement): void {
+    const cols = dockColsForViewport(currentViewportWidth(gridEl.clientWidth));
+
+    // Column count from the viewport breakpoint; the rest comes from the shared fixed-cell base
+    // (no `row` → items wrap into as many rows as needed).
+    const options = this.buildFixedCellOptions({ column: cols });
+    this.grid = GridStack.init(options, gridEl);
+
+    // init() auto-converts existing children — register them, then wire the terminal drag event.
+    this.registerExistingItems();
+    this.attachDragStop();
+
+    // On viewport resize, update the column count so the grid reflows to the new breakpoint.
+    // Observe the HOST (reliable container width); stays outside Angular's zone.
+    this.widthObserver = new ResizeObserver(() => {
+      this.applyGridFixedColumns();
+    });
+    this.widthObserver.observe(this.host.nativeElement);
+  }
+
+  /**
+   * Recomputes the column count for `grid-fixed` mode from the current viewport width and
+   * updates the gridstack engine. Idempotent — gridstack no-ops if the column count is unchanged.
+   */
+  private applyGridFixedColumns(): void {
+    const cols = dockColsForViewport(currentViewportWidth());
+    this.grid?.column(cols, 'moveScale');
+  }
+
+  /**
+   * Computes and applies an explicit `width` on the dock's `.grid-stack` element so each tile is
+   * the SAME width as an "others"-grid card (4 fill the container at desktop), and the row scrolls
+   * when there are more favorites than fit.
+   *
+   * Sizing model:
+   * - `cols` = target columns per row, from the VIEWPORT width (4/3/2/1 via `dockColsForViewport`).
+   *   Tailwind's `sm:`/`lg:`/`xl:` prefixes are viewport media queries, so the count MUST come from
+   *   `window.innerWidth` to match the others grid — using the container width here would pick the
+   *   wrong count when the sidebar+padding shrink the container below a breakpoint.
+   * - `tileWidth` = `containerWidth / cols` (a gridstack column cell). gridstack insets the card by
+   *   `margin` on each side, so the visible card = `tileWidth − 2×margin` with `2×margin` gaps —
+   *   matching the others-grid `gap-4`. The DIVISION uses the actual container width so the row
+   *   fills exactly.
+   * - grid element width = `itemCount × tileWidth`. When `itemCount ≤ cols` the grid is ≤ the
+   *   container, so the row fills / left-aligns; when `itemCount > cols` it overflows and the parent
+   *   `overflow-x: auto` scrolls (with the `auScrollFade` edge fade).
+   *
+   * `containerWidth` is the dock scroll wrapper's inner width — the host's `clientWidth` (the host
+   * is a block child of the wrapper, so its clientWidth tracks the wrapper, not the wider grid).
+   * Uses `width` (NOT `min-width`) so gridstack resolves each column to exactly `tileWidth` instead
+   * of stretching columns to fill a 100%-width element.
+   */
+  private applyDockWidth(gridEl: HTMLElement, itemCount: number): void {
+    const containerWidth = this.host.nativeElement.clientWidth;
+    // Column COUNT from the viewport (Tailwind media-query semantics); DIVISION by the container.
+    const viewportWidth = currentViewportWidth(containerWidth);
+    const cols = dockColsForViewport(viewportWidth);
+    const tileWidth = dockTileWidth(containerWidth, cols);
+    const width = Math.max(itemCount, 1) * tileWidth;
+    gridEl.style.width = `${width}px`;
+  }
+
+  /**
+   * Whether editing is effectively active right now: the consumer asked for edit mode AND the
+   * grid is wide enough (desktop). Used for `staticGrid` so a narrow grid is always static.
+   */
+  private isEffectivelyEditable(): boolean {
+    return this.editMode() && this.editableByWidth;
+  }
+
+  /**
+   * Updates the width-based edit gate. On a threshold crossing, re-applies the effective static
+   * state and emits `editableByWidthChange` so the page can sync its edit affordances. No-op when
+   * the gate value is unchanged (avoids churn on every resize tick).
+   */
+  private applyEditableByWidth(editable: boolean): void {
+    if (editable === this.editableByWidth) {
+      return;
+    }
+    this.editableByWidth = editable;
+    this.applyEditMode(this.editMode());
+    this.editableByWidthChange.emit(editable);
+  }
+
+  // ── Membership reconciliation (add / remove) ─────────────────────────────────
+
+  /**
+   * Brings the Gridstack engine in line with `items()`:
+   * - converts newly-rendered `.grid-stack-item` elements into widgets (`makeWidget`),
+   * - removes (engine-only) widgets whose id no longer appears in `items()`.
+   * In dock mode, also updates `column` count + explicit width and re-packs the row so tiles are
+   * always contiguous from the left (no gaps after a remove/reorder).
+   * No-op until the grid is initialized.
+   */
+  private reconcileMembership(items: readonly DashboardGridItem[]): void {
+    const grid = this.grid;
+    if (grid === null) {
+      return;
+    }
+
+    const wanted = new Set(items.map((i) => i.id));
+
+    // Remove widgets that left items(). Engine-only removal (removeDOM=false): Angular's
+    // @for owns the DOM and will drop the element on its own pass.
+    for (const [id, el] of this.managed) {
+      if (!wanted.has(id)) {
+        grid.removeWidget(el, false, false);
+        this.managed.delete(id);
+      }
+    }
+
+    // Convert newly-rendered elements (present in the DOM, not yet a widget) into widgets.
+    const gridEl = grid.el;
+    const domItems = gridEl.querySelectorAll<HTMLElement>('.grid-stack-item');
+    for (const el of Array.from(domItems)) {
+      const id = el.getAttribute('gs-id');
+      if (id !== null && !this.managed.has(id)) {
+        const widgetEl = grid.makeWidget(el);
+        this.managed.set(id, widgetEl);
+      }
+    }
+
+    // In dock mode, keep the gridstack column count (one per tile) and the explicit grid width in
+    // sync with the item count so adding/removing a favorite adjusts the strip, and re-pack
+    // horizontally so the row is always contiguous from the left with NO gaps. Tile WIDTH itself
+    // comes from the container breakpoint inside applyDockWidth.
+    if (this.mode() === 'dock') {
+      const cols = Math.max(items.length, 1);
+      grid.column(cols, 'none');
+      this.repackDock(grid, items);
+      this.applyDockWidth(gridEl, cols);
+    }
+  }
+
+  /**
+   * Re-packs the dock so every surviving tile sits contiguously from the left (x = 0,1,2,…, y = 0)
+   * in `items()` order — eliminating the gaps that `float:false` leaves behind on remove/reorder
+   * (gridstack's `float:false` is VERTICAL gravity only; it never compacts horizontally).
+   *
+   * The desired positions come from the pure `buildDockPacking` helper; we apply them to each
+   * managed engine node via `grid.update()` between `batchUpdate(true)` … `batchUpdate(false)` so
+   * the whole reflow is a single, gap-free layout pass. Dock mode only.
+   */
+  private repackDock(grid: GridStack, items: readonly DashboardGridItem[]): void {
+    const positions = buildDockPacking(items);
+
+    grid.batchUpdate(true);
+    for (const pos of positions) {
+      const el = this.managed.get(pos.id);
+      if (el !== undefined) {
+        grid.update(el, { x: pos.x, y: pos.y, w: 1, h: 1 });
+      }
+    }
+    grid.batchUpdate(false);
+  }
+
+  /**
+   * Toggles drag/resize for the whole grid.
+   * - `'grid'` mode: interactive only when `editMode` AND the width allows it (desktop). The width
+   *   gate prevents a responsive-collapsed layout from being saved.
+   * - `'dock'` / `'grid-fixed'` modes: interactive whenever `editMode` is true (no width gate —
+   *   these modes are always fixed-cell and the width never affects the interaction model).
+   * No-op until init.
+   */
+  private applyEditMode(_edit: boolean): void {
+    // `_edit` is the afterRenderEffect's tracked read of editMode(); the effective state is
+    // computed per-mode so the logic lives in ONE place.
+    const mode = this.mode();
+    const isStatic =
+      mode === 'dock' || mode === 'grid-fixed' ? !this.editMode() : !this.isEffectivelyEditable();
+    this.grid?.setStatic(isStatic);
+  }
+
+  // ── Terminal event handlers ───────────────────────────────────────────────────
+
+  private onDragStop(el: GridItemHTMLElement): void {
+    const item = this.recoverItem(el.gridstackNode);
+    if (item === null) {
+      return;
+    }
+    this.itemChange.emit(mapItemGeometry(item));
+
+    // In the fixed-cell modes, also emit the FULL settled layout read from the live engine, so the
+    // consumer can persist the correct order WITHOUT relying on a stale snapshot of the other
+    // tiles' positions (those may have been displaced by gridstack's compaction during this drag).
+    const mode = this.mode();
+    if (mode === 'dock' || mode === 'grid-fixed') {
+      this.layoutChange.emit(this.readFullLayout());
+    }
+  }
+
+  /**
+   * Reads the COMPLETE settled layout from the live Gridstack engine — one geometry entry per node
+   * with a valid string id. `grid.engine.nodes` holds the engine's current nodes (positions as
+   * gridstack settled them after compaction), which is the only source that reflects where EVERY
+   * tile actually ended up. Used by `onDragStop` to emit `layoutChange` in dock/grid-fixed modes.
+   */
+  private readFullLayout(): DashboardGridItemGeometry[] {
+    if (this.grid === null) {
+      return [];
+    }
+    const nodes: GridStackNode[] = this.grid.engine.nodes;
+    return nodes
+      .filter((node): node is GridStackNode & { id: string } => typeof node.id === 'string')
+      .map((node) => ({
+        id: node.id,
+        x: node.x ?? 0,
+        y: node.y ?? 0,
+        cols: node.w ?? 1,
+        rows: node.h ?? 1,
+      }));
+  }
+
+  private onResizeStop(el: GridItemHTMLElement): void {
+    const item = this.recoverItem(el.gridstackNode);
+    if (item === null) {
+      return;
+    }
+    this.itemResize.emit(mapResizeGeometry(item));
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Recovers the originating `DashboardGridItem` (with its `span`) from the Gridstack node,
+   * matching by `id` and overlaying the node's current geometry (post drag/resize). Falls
+   * back to a synthetic item when the id is absent from the current `items()` list.
+   */
+  private recoverItem(node: GridStackNode | undefined): DashboardGridItem | null {
+    if (node === undefined) {
+      return null;
+    }
+
+    const id = typeof node.id === 'string' ? node.id : String(node.id ?? '');
+    const x = node.x ?? 0;
+    const y = node.y ?? 0;
+    const cols = node.w ?? 1;
+    const rows = node.h ?? 1;
+
+    const found = this.items().find((i) => i.id === id);
+    if (found !== undefined) {
+      return { ...found, x, y, cols, rows };
+    }
+
+    return {
+      id,
+      x,
+      y,
+      cols,
+      rows,
+      span: {
+        minCols: cols,
+        maxCols: cols,
+        minRows: rows,
+        maxRows: rows,
+        defaultCols: cols,
+        defaultRows: rows,
+      },
+    };
+  }
+}
+
+export const AuDashboardGridImports = [AuDashboardGrid] as const;