@grafloria/element 0.4.21 → 0.4.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafloria/element",
-  "version": "0.4.21",
+  "version": "0.4.22",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",

package/src/index.d.ts

@@ -80,7 +80,7 @@ export type { ErColumn, ErEntitySpec, ErRelationshipSpec, ErCardinality, ErSide,
 export { erTable, umlClass, erTables, umlClasses, CardHandle, ErTable, ErField, ErColumnList, UmlClass, UmlMemberList, } from './lib/diagram-kit/index.js';
 export type { HandleApi } from './lib/diagram-kit/index.js';
 export { bindDashboardGrid, rowHeightFor, boardHeightFor, columnUnitFor, cellToRect, pointToCell, sizeToSpan, gridItemFromCell, cellFromGridItem, buildCommitCommands, ensureDashboardKitStyles, DASHBOARD_KIT_STYLE_ID, dashboard, defaultWidgetRenderer, renderKpiWidget, renderLineWidget, renderBarWidget, renderDonutWidget, renderFunnelWidget, renderTableWidget, BUILT_IN_WIDGET_KINDS, } from './lib/dashboard-kit/index.js';
-export type { DashboardGridApi, DashboardGridOptions, DashboardGridHandle, CellRect, WorldRect, DashboardGridGeometry, TileDelta, DashboardOptions, DashboardSpec, DashboardSnapshot, DragHandleOption, DragGripOptions, DashboardHandle, DashboardViewSpec, DashboardWidgetSpec, WidgetHandle, WidgetRenderer, KpiWidgetData, LineWidgetData, LineSeries, BarWidgetData, DonutWidgetData, FunnelWidgetData, TableWidgetData, } from './lib/dashboard-kit/index.js';
+export type { DashboardGridApi, DashboardGridOptions, DashboardGridHandle, CellRect, WorldRect, DashboardGridGeometry, TileDelta, DashboardOptions, DashboardSpec, DashboardSnapshot, DragHandleOption, DragGripOptions, DashboardHandle, DashboardViewSpec, DashboardWidgetSpec, SectionCaption, SectionCaptionOptions, SectionCaptionAction, SectionCaptionFont, WidgetHandle, WidgetRenderer, KpiWidgetData, LineWidgetData, LineSeries, BarWidgetData, DonutWidgetData, FunnelWidgetData, TableWidgetData, } from './lib/dashboard-kit/index.js';
 export { bindStencilPalette, bindShapeDataPanel, ensureStencilKitStyles } from './lib/stencil-kit/index.js';
 export type { StencilPaletteApi, StencilPaletteOptions, StencilPaletteHandle, ShapeDataPanelApi, ShapeDataPanelOptions, ShapeDataPanelHandle, } from './lib/stencil-kit/index.js';
 export * from '@grafloria/engine';

package/src/lib/dashboard-kit/caption.d.ts

@@ -0,0 +1,123 @@
+/**
+ * SECTION CAPTIONS — the header a section (container widget) may carry,
+ * painted by the kit on the slab overlay it already owns.
+ *
+ * Three things only the kit can do for a section header, and this module is
+ * where they are decided: RESERVE the pixels (`captionReserve` — the nested
+ * board's frame starts below the band, so no child may take it), PAINT it
+ * (`paintCaptionBand` — one DOM shape, one set of CSS variables, one theme),
+ * and ROUTE its presses (`captionPassThrough` — a button or an input in the
+ * band is content, everything else is the band, which selects the section).
+ * Persistence is the container's business: the caption rides on the group's
+ * `containerWidget` metadata beside `layout` and `sizing`, and `toJSON()`
+ * writes it back.
+ *
+ * Plan and defaults: documentation/api-architecture/section-caption-plan.html.
+ */
+export interface SectionCaptionAction {
+    id: string;
+    /** Accessible name; painted as the glyph when there is no `icon`. */
+    label: string;
+    /** A glyph (emoji or short text). */
+    icon?: string;
+    /** Tooltip; default: the label. */
+    title?: string;
+    disabled?: boolean;
+}
+export interface SectionCaptionFont {
+    size?: number;
+    weight?: number | string;
+    family?: string;
+    color?: string;
+    transform?: 'none' | 'uppercase';
+}
+export interface SectionCaptionOptions {
+    /** Default: the container's `title`. */
+    text?: string;
+    /** A muted second line; the band grows to 44 px. */
+    subtitle?: string;
+    /** An ⓘ after the text: tooltip and the section's accessible description. */
+    description?: string;
+    /** A glyph before the text (emoji or short text). */
+    icon?: string;
+    /** 'inside' (default): a band inside the frame, reserved. 'tab': above the frame, nothing reserved. */
+    position?: 'inside' | 'tab';
+    /** Horizontal alignment (default 'start', mirrored on RTL). */
+    align?: 'start' | 'center' | 'end';
+    /** Vertical alignment within the band (default 'center'). */
+    valign?: 'top' | 'center' | 'bottom';
+    /** Band height, px (default 28; 44 with a subtitle). */
+    height?: number;
+    font?: SectionCaptionFont;
+    /** Inside the band: px, or [vertical, horizontal] (default [0, 10]). */
+    padding?: number | [number, number];
+    /** Between the band and the frame: px, or [vertical, horizontal] (default 0). Adds to the reserve. */
+    margin?: number | [number, number];
+    /** Band fill (default: the theme's). */
+    background?: string;
+    /** The band's bottom rule, a CSS border value (default none). */
+    border?: string;
+    /** 'always' (default); 'design' is not painted (nor reserved) under static; 'hover' overlays the content, nothing reserved. */
+    show?: 'always' | 'design' | 'hover';
+    /** Buttons at the end of the band; a press fires `onCaptionAction` and never selects. */
+    actions?: SectionCaptionAction[];
+    /** Presses inside descendants matching this selector are content, never the band's. */
+    passThrough?: string;
+    /** Your class on the band. */
+    className?: string;
+}
+/** `false`/absent: no band. `true`: the title. A string: that text. */
+export type SectionCaption = false | true | string | SectionCaptionOptions;
+export declare const CAPTION_HEIGHT = 28;
+export declare const CAPTION_HEIGHT_SUBTITLE = 44;
+export declare const CAPTION_HEIGHT_TIGHT = 22;
+/** A section shorter than this steps its band down to the tight tier. */
+export declare const CAPTION_TIGHT_BELOW = 90;
+export declare const CAPTION_PASS_THROUGH = "button, a, input, select, textarea, [data-axdb-pass]";
+/** The caption as options, or null when there is none. `title` fills the text. */
+export declare function normalizeCaption(c: SectionCaption | undefined, title?: string): SectionCaptionOptions | null;
+/** The caption a section GROUP carries, from its persisted `containerWidget` metadata. */
+export declare function captionOfGroup(grp: {
+    getMetadata(key: string): unknown;
+    name?: string;
+} | undefined): SectionCaptionOptions | null;
+export declare function pairOf(v: number | [number, number] | undefined, dflt: [number, number]): [number, number];
+/** Painted at all? `show: 'design'` disappears under static. */
+export declare function captionPainted(c: SectionCaptionOptions | null, isStatic: boolean): boolean;
+/** The band's height for a section of `sectionH` px. */
+export declare function captionBandHeight(c: SectionCaptionOptions, sectionH: number): number;
+/** Pixels the nested board's frame gives up at the top: the band plus its vertical margins. */
+export declare function captionReserve(c: SectionCaptionOptions | null, ctx: {
+    static: boolean;
+    sectionH: number;
+}): number;
+/** Identity of a painted band: repaint only when this changes (the tier is a class toggle, not a repaint). */
+export declare function captionKey(c: SectionCaptionOptions, ctx: {
+    rtl: boolean;
+    static: boolean;
+}): string;
+/** Is a section of `sectionH` px in the tight tier? */
+export declare const captionTight: (sectionH: number) => boolean;
+/** The per-sync geometry of a painted band: height and tier follow the section's live size. */
+export declare function sizeCaptionBand(band: HTMLElement, c: SectionCaptionOptions, sectionH: number): void;
+/**
+ * Is a press on `target`, inside `band`, content rather than the band? An
+ * action button is always content: no tool claims it, so the browser's own
+ * `click` reaches it — from a mouse, a touch, or Enter/Space on the keyboard
+ * (a pointerdown-only action never fired from the keyboard, and the
+ * interaction gate's DEAD-BUTTON check, which clicks, called it dead).
+ */
+export declare function captionPassThrough(target: Element | null, band: Element, c: SectionCaptionOptions | null): boolean;
+/**
+ * Paint the band: geometry (inline, so the reserve and the pixels agree),
+ * classes for alignment and mode, CSS variables for typography and box, and
+ * the default content — icon, text, subtitle, ⓘ, actions. With `render` the
+ * content is yours: the band is handed over empty and keeps its press rules.
+ */
+export declare function paintCaptionBand(band: HTMLElement, c: SectionCaptionOptions, ctx: {
+    rtl: boolean;
+    static: boolean;
+    sectionH: number;
+    render?: (host: HTMLElement) => void;
+    onAction?: (actionId: string) => void;
+}): void;

package/src/lib/dashboard-kit/caption.js

@@ -0,0 +1,200 @@
+/**
+ * SECTION CAPTIONS — the header a section (container widget) may carry,
+ * painted by the kit on the slab overlay it already owns.
+ *
+ * Three things only the kit can do for a section header, and this module is
+ * where they are decided: RESERVE the pixels (`captionReserve` — the nested
+ * board's frame starts below the band, so no child may take it), PAINT it
+ * (`paintCaptionBand` — one DOM shape, one set of CSS variables, one theme),
+ * and ROUTE its presses (`captionPassThrough` — a button or an input in the
+ * band is content, everything else is the band, which selects the section).
+ * Persistence is the container's business: the caption rides on the group's
+ * `containerWidget` metadata beside `layout` and `sizing`, and `toJSON()`
+ * writes it back.
+ *
+ * Plan and defaults: documentation/api-architecture/section-caption-plan.html.
+ */
+export const CAPTION_HEIGHT = 28;
+export const CAPTION_HEIGHT_SUBTITLE = 44;
+export const CAPTION_HEIGHT_TIGHT = 22;
+/** A section shorter than this steps its band down to the tight tier. */
+export const CAPTION_TIGHT_BELOW = 90;
+export const CAPTION_PASS_THROUGH = 'button, a, input, select, textarea, [data-axdb-pass]';
+/** The caption as options, or null when there is none. `title` fills the text. */
+export function normalizeCaption(c, title) {
+    if (c === undefined || c === false)
+        return null;
+    const o = c === true ? {} : typeof c === 'string' ? { text: c } : Object.assign({}, c);
+    if (o.text === undefined && title !== undefined)
+        o.text = title;
+    return o;
+}
+/** The caption a section GROUP carries, from its persisted `containerWidget` metadata. */
+export function captionOfGroup(grp) {
+    var _a;
+    if (!grp)
+        return null;
+    const meta = grp.getMetadata('containerWidget');
+    if (!meta || meta.caption === undefined)
+        return null;
+    return normalizeCaption(meta.caption, (_a = meta.title) !== null && _a !== void 0 ? _a : grp.name);
+}
+export function pairOf(v, dflt) {
+    if (v === undefined)
+        return dflt;
+    return typeof v === 'number' ? [v, v] : [v[0], v[1]];
+}
+/** Painted at all? `show: 'design'` disappears under static. */
+export function captionPainted(c, isStatic) {
+    if (!c)
+        return false;
+    return !(c.show === 'design' && isStatic);
+}
+/** The band's height for a section of `sectionH` px. */
+export function captionBandHeight(c, sectionH) {
+    var _a;
+    if (sectionH > 0 && sectionH < CAPTION_TIGHT_BELOW)
+        return CAPTION_HEIGHT_TIGHT;
+    return (_a = c.height) !== null && _a !== void 0 ? _a : (c.subtitle ? CAPTION_HEIGHT_SUBTITLE : CAPTION_HEIGHT);
+}
+/** Pixels the nested board's frame gives up at the top: the band plus its vertical margins. */
+export function captionReserve(c, ctx) {
+    if (!c || !captionPainted(c, ctx.static))
+        return 0;
+    if (c.position === 'tab' || c.show === 'hover')
+        return 0;
+    const [mv] = pairOf(c.margin, [0, 0]);
+    return captionBandHeight(c, ctx.sectionH) + 2 * mv;
+}
+/** Identity of a painted band: repaint only when this changes (the tier is a class toggle, not a repaint). */
+export function captionKey(c, ctx) {
+    return JSON.stringify([c, ctx.rtl, ctx.static]);
+}
+/** Is a section of `sectionH` px in the tight tier? */
+export const captionTight = (sectionH) => sectionH > 0 && sectionH < CAPTION_TIGHT_BELOW;
+/** The per-sync geometry of a painted band: height and tier follow the section's live size. */
+export function sizeCaptionBand(band, c, sectionH) {
+    const h = captionBandHeight(c, sectionH);
+    band.classList.toggle('axdb-slab-h--tight', captionTight(sectionH));
+    band.style.height = `${h}px`;
+    if (c.position === 'tab')
+        band.style.top = `${-h}px`;
+}
+/**
+ * Is a press on `target`, inside `band`, content rather than the band? An
+ * action button is always content: no tool claims it, so the browser's own
+ * `click` reaches it — from a mouse, a touch, or Enter/Space on the keyboard
+ * (a pointerdown-only action never fired from the keyboard, and the
+ * interaction gate's DEAD-BUTTON check, which clicks, called it dead).
+ */
+export function captionPassThrough(target, band, c) {
+    var _a;
+    if (!target || !band.contains(target))
+        return false;
+    const sel = `${(_a = c === null || c === void 0 ? void 0 : c.passThrough) !== null && _a !== void 0 ? _a : CAPTION_PASS_THROUGH}, .axdb-slab-h-action`;
+    const hit = target.closest(sel);
+    return !!hit && band.contains(hit) && hit !== band;
+}
+const el = (doc, cls, text) => {
+    const e = doc.createElement('div');
+    e.className = cls;
+    if (text !== undefined)
+        e.textContent = text;
+    return e;
+};
+/**
+ * Paint the band: geometry (inline, so the reserve and the pixels agree),
+ * classes for alignment and mode, CSS variables for typography and box, and
+ * the default content — icon, text, subtitle, ⓘ, actions. With `render` the
+ * content is yours: the band is handed over empty and keeps its press rules.
+ */
+export function paintCaptionBand(band, c, ctx) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    const doc = band.ownerDocument;
+    const h = captionBandHeight(c, ctx.sectionH);
+    const [mv, mh] = pairOf(c.margin, [0, 0]);
+    const [pv, ph] = pairOf(c.padding, [0, 10]);
+    band.className = 'axdb-slab-h';
+    band.textContent = '';
+    const cls = (name, on) => band.classList.toggle(name, on);
+    cls('axdb-slab-h--tab', c.position === 'tab');
+    cls('axdb-slab-h--hover', c.show === 'hover');
+    cls('axdb-slab-h--tight', captionTight(ctx.sectionH));
+    cls('axdb-slab-h--center', c.align === 'center');
+    cls('axdb-slab-h--end', c.align === 'end');
+    cls('axdb-slab-h--vtop', c.valign === 'top');
+    cls('axdb-slab-h--vbottom', c.valign === 'bottom');
+    if (c.className)
+        for (const k of c.className.split(/\s+/).filter(Boolean))
+            band.classList.add(k);
+    band.setAttribute('dir', ctx.rtl ? 'rtl' : 'ltr');
+    band.style.height = `${h}px`;
+    band.style.top = c.position === 'tab' ? `${-h}px` : `${mv}px`;
+    band.style.left = `${mh}px`;
+    band.style.right = c.position === 'tab' ? 'auto' : `${mh}px`; // a tab is sized to its text
+    const v = (name, value) => {
+        if (value === undefined)
+            band.style.removeProperty(name);
+        else
+            band.style.setProperty(name, value);
+    };
+    v('--axdb-caption-pad', `${pv}px ${ph}px`);
+    // Clamped to the CONFIGURED band (the tight tier caps it again in CSS), so
+    // the text never exceeds the band whatever size the section is painted at.
+    const bandH = (_a = c.height) !== null && _a !== void 0 ? _a : (c.subtitle ? CAPTION_HEIGHT_SUBTITLE : CAPTION_HEIGHT);
+    v('--axdb-caption-font-size', ((_b = c.font) === null || _b === void 0 ? void 0 : _b.size) !== undefined ? `${Math.min(c.font.size, Math.max(8, bandH - 2 * pv - 4))}px` : undefined);
+    v('--axdb-caption-font-weight', ((_c = c.font) === null || _c === void 0 ? void 0 : _c.weight) !== undefined ? String(c.font.weight) : undefined);
+    v('--axdb-caption-font-family', (_d = c.font) === null || _d === void 0 ? void 0 : _d.family);
+    v('--axdb-caption-fg', (_e = c.font) === null || _e === void 0 ? void 0 : _e.color);
+    v('--axdb-caption-transform', (_f = c.font) === null || _f === void 0 ? void 0 : _f.transform);
+    v('--axdb-caption-bg', c.background);
+    v('--axdb-caption-border', c.border);
+    if (ctx.render) {
+        ctx.render(band);
+        return;
+    }
+    if (c.icon)
+        band.appendChild(el(doc, 'axdb-slab-h-icon', c.icon));
+    const body = el(doc, 'axdb-slab-h-body');
+    const text = el(doc, 'axdb-slab-h-text', (_g = c.text) !== null && _g !== void 0 ? _g : '');
+    text.setAttribute('title', (_h = c.text) !== null && _h !== void 0 ? _h : '');
+    body.appendChild(text);
+    if (c.subtitle)
+        body.appendChild(el(doc, 'axdb-slab-h-sub', c.subtitle));
+    band.appendChild(body);
+    if (c.description) {
+        const info = el(doc, 'axdb-slab-h-info', 'ⓘ');
+        info.setAttribute('title', c.description);
+        info.setAttribute('aria-label', c.description);
+        band.appendChild(info);
+    }
+    if ((_j = c.actions) === null || _j === void 0 ? void 0 : _j.length) {
+        const row = el(doc, 'axdb-slab-h-actions');
+        for (const a of c.actions) {
+            const b = doc.createElement('button');
+            b.type = 'button';
+            b.className = 'axdb-slab-h-action';
+            b.setAttribute('data-action', a.id);
+            b.setAttribute('aria-label', a.label);
+            b.setAttribute('title', (_k = a.title) !== null && _k !== void 0 ? _k : a.label);
+            b.textContent = (_l = a.icon) !== null && _l !== void 0 ? _l : a.label;
+            if (a.disabled)
+                b.disabled = true;
+            // Out of the tab order: a board keeps exactly ONE tab stop (the roving
+            // tabindex over its widgets — the accessibility scenario asserts it).
+            // The band becomes the section's tab stop, with its actions reachable
+            // from it, in the section-keyboard round; a click (mouse, touch, or a
+            // script) fires the action today.
+            b.tabIndex = -1;
+            b.addEventListener('click', (e) => {
+                var _a;
+                e.stopPropagation();
+                if (!b.disabled)
+                    (_a = ctx.onAction) === null || _a === void 0 ? void 0 : _a.call(ctx, a.id);
+            });
+            row.appendChild(b);
+        }
+        band.appendChild(row);
+    }
+}
+//# sourceMappingURL=caption.js.map

package/src/lib/dashboard-kit/dashboard.d.ts

@@ -46,6 +46,7 @@ import { GroupModel, NodeModel, type GridColumnLayout } from '@grafloria/engine'
 import { type DashboardGridHandle, type DashboardGridOptions, type DashboardResponsiveOptions } from './grid-binder.js';
 import type { DragHandleOption } from './grid-binder.js';
 import type { SplitNode } from './split-layout.js';
+import type { SectionCaption } from './caption.js';
 /** A widget, declared as data. */
 export interface DashboardWidgetSpec {
     id: string;
@@ -113,6 +114,14 @@ export interface DashboardWidgetSpec {
      * `toJSON()` writes it per container.
      */
     layout?: 'grid' | 'split';
+    /**
+     * Container only: a CAPTION painted by the kit on the section's slab —
+     * `true` for the title, a string, or the full options (subtitle,
+     * description, icon, position, alignment, typography, box, show, actions,
+     * pass-through, className). Reserved inside the frame, selectable, themed,
+     * persisted by `toJSON()`; live through `setCaption()`. Default: none.
+     */
+    caption?: SectionCaption;
     /**
      * Container only, split layout: the authored splitter tree. Omit it and the
      * tree is derived from the children's cells. `toJSON()` writes it back.
@@ -258,6 +267,15 @@ export interface DashboardOptions {
      * press on a section's empty band selects the section.
      */
     onSelect?: (id: string | undefined, viewId: string) => void;
+    /**
+     * Paint a section's caption band yourself (the escape hatch `renderWidget`
+     * is for cards): the band arrives empty, sized and themed, and keeps its
+     * press rules — a press on it selects the section, a pass-through element
+     * (a button, an input, `[data-axdb-pass]`) reaches your content.
+     */
+    renderCaption?: (widget: DashboardWidgetSpec, host: HTMLElement) => void;
+    /** A press on a caption action (`caption.actions`): the section, the action id, the view. */
+    onCaptionAction?: (sectionId: string, actionId: string, viewId: string) => void;
     /** Fires after any committed gesture, with the view whose layout changed. */
     onLayoutChange?: (viewId: string, widgets: DashboardWidgetSpec[]) => void;
     /** Extra binder options, merged last (escape hatch to the layer below). */
@@ -325,6 +343,15 @@ export interface DashboardHandle {
      */
     setLayout(layout: 'grid' | 'split', viewId?: string): void;
     getLayout(viewId?: string): 'grid' | 'split';
+    /**
+     * Set a SECTION's caption live — `false` removes it, `true` is the title, a
+     * string or the options. Repaints the band, gives the reserve back or takes
+     * it, persists on the section, one undo step. False for anything that is
+     * not a container.
+     */
+    setCaption(id: string, caption: SectionCaption): boolean;
+    /** The caption as authored or last set; undefined when the section has none. */
+    getCaption(id: string): SectionCaption | undefined;
     /** Live sizing/float switches — the two prototype toggles. */
     setSizing(mode: 'fit' | 'grow'): void;
     getSizing(): 'fit' | 'grow';
@@ -500,18 +527,6 @@ export interface DashboardApiRef {
         onChange?(listener: (state: unknown) => void): () => void;
     };
 }
-/**
- * Everything one `DashboardHandle` closes over, gathered into ONE object so a
- * single builder can serve both `dashboard()` (context built from the authored
- * literal) and `fromDocument()` (context reconstructed from the loaded model).
- *
- * `active` and `apiRef` are the two MUTABLE cells: the handle READS them on
- * every call and the builder WRITES them (showView reassigns `active`, the
- * caller's finalize sets `apiRef`). They live here rather than as free `let`s
- * precisely because there are now two call sites — a boxed cell one builder
- * reads and writes is the whole reason a second handle implementation, which
- * would silently drift, is not needed.
- */
 export interface DashboardHandleContext {
     /** The views — MUTATED in place by addWidget (push) and remove (filter). */
     views: DashboardViewSpec[];

package/src/lib/dashboard-kit/dashboard.js

@@ -290,6 +290,37 @@ function assignCells(widgets, columns) {
         w.rows = rows;
     }
 }
+/**
+ * Everything one `DashboardHandle` closes over, gathered into ONE object so a
+ * single builder can serve both `dashboard()` (context built from the authored
+ * literal) and `fromDocument()` (context reconstructed from the loaded model).
+ *
+ * `active` and `apiRef` are the two MUTABLE cells: the handle READS them on
+ * every call and the builder WRITES them (showView reassigns `active`, the
+ * caller's finalize sets `apiRef`). They live here rather than as free `let`s
+ * precisely because there are now two call sites — a boxed cell one builder
+ * reads and writes is the whole reason a second handle implementation, which
+ * would silently drift, is not needed.
+ */
+/** `setCaption` as one history step: execute re-applies the value, undo the previous one. */
+class SetCaptionCommand extends Command {
+    constructor(sectionId, before, after, apply) {
+        super('Set section caption');
+        this.sectionId = sectionId;
+        this.before = before;
+        this.after = after;
+        this.apply = apply;
+    }
+    execute() {
+        this.apply(this.after);
+    }
+    undo() {
+        this.apply(this.before);
+    }
+    serialize() {
+        return { id: this.id, name: this.name, timestamp: this.timestamp, data: { sectionId: this.sectionId, before: this.before, after: this.after } };
+    }
+}
 /**
  * Build THE `DashboardHandle` — the one and only implementation, shared by
  * `dashboard()` and `fromDocument()`. Reads/writes the mutable `ctx.active` /
@@ -564,6 +595,41 @@ export function createDashboardHandle(ctx) {
             reportChanged();
         },
         getLayout: (viewId) => { var _a; return (_a = ctx.layoutOf.get(viewId !== null && viewId !== void 0 ? viewId : ctx.active)) !== null && _a !== void 0 ? _a : 'grid'; },
+        setCaption(id, caption) {
+            const cg = ctx.boardGroups.get(id);
+            const w = specById.get(id);
+            if (!cg || !w || !w.widgets || views.some((v) => v.id === id))
+                return false;
+            const before = w.caption;
+            if (JSON.stringify(before !== null && before !== void 0 ? before : null) === JSON.stringify(caption !== null && caption !== void 0 ? caption : null))
+                return true;
+            const apply = (c) => {
+                var _a, _b, _c, _d, _e;
+                if (c === undefined)
+                    delete w.caption;
+                else
+                    w.caption = c;
+                const cw = (_a = cg.getMetadata('containerWidget')) !== null && _a !== void 0 ? _a : {};
+                const next = Object.assign({}, cw);
+                if (c === undefined)
+                    delete next['caption'];
+                else
+                    next['caption'] = c;
+                cg.setMetadata('containerWidget', next);
+                // The section's own board re-projects under its new frame; the parent
+                // repaints the slab (the band lives there).
+                (_b = binders.get(id)) === null || _b === void 0 ? void 0 : _b.sync();
+                (_d = binders.get((_c = viewOfWidget.get(id)) !== null && _c !== void 0 ? _c : '')) === null || _d === void 0 ? void 0 : _d.sync();
+                (_e = ctx.apiRef) === null || _e === void 0 ? void 0 : _e.renderNow();
+            };
+            // Applied NOW (a caller reads the band right after), then recorded as
+            // one history step whose execute re-applies the same value.
+            apply(caption);
+            execCommand(new SetCaptionCommand(id, before, caption, apply));
+            reportChanged();
+            return true;
+        },
+        getCaption: (id) => { var _a; return (_a = specById.get(id)) === null || _a === void 0 ? void 0 : _a.caption; },
         setSizing(mode) {
             var _a;
             for (const b of binders.values())
@@ -1194,7 +1260,7 @@ export function dashboard(options) {
                         cg.setMetadata('gridItem', gridItemFromCell({ x: w.x, y: w.y, w: w.span, h: w.rows }));
                         // The container's own spec fields, persisted ON the group — a
                         // reloaded document has no authored literal to read them from.
-                        cg.setMetadata('containerWidget', Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (w.kind !== undefined ? { kind: w.kind } : {})), (w.title !== undefined ? { title: w.title } : {})), { columns: innerColumns, maxRows: innerRows }), (w.data !== undefined ? { data: w.data } : {})), (w.layout !== undefined ? { layout: w.layout } : {})), (w.sizing !== undefined ? { sizing: w.sizing } : {})));
+                        cg.setMetadata('containerWidget', Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (w.kind !== undefined ? { kind: w.kind } : {})), (w.title !== undefined ? { title: w.title } : {})), { columns: innerColumns, maxRows: innerRows }), (w.data !== undefined ? { data: w.data } : {})), (w.layout !== undefined ? { layout: w.layout } : {})), (w.sizing !== undefined ? { sizing: w.sizing } : {})), (w.caption !== undefined ? { caption: w.caption } : {})));
                         // Item 7: the container's own layout and bound, persisted like a view's.
                         ctx.layoutOf.set(w.id, (_c = w.layout) !== null && _c !== void 0 ? _c : 'grid');
                         if (w.layout === 'split' && w.tree !== undefined)
@@ -1257,14 +1323,27 @@ export function dashboard(options) {
              * switched to static, RTL or drag-by-header LIVE snapped back to its
              * authored options the moment its layout changed (s34 caught it).
              */
+            /** The caption escape hatches, with the spec and the view filled in. */
+            function captionHooks(viewId) {
+                const render = options.renderCaption;
+                return Object.assign(Object.assign({}, (render
+                    ? {
+                        renderCaption: (sectionId, host) => {
+                            const spec = specById.get(sectionId);
+                            if (spec)
+                                render(spec, host);
+                        },
+                    }
+                    : {})), { onCaptionAction: (sectionId, actionId) => { var _a; return (_a = options.onCaptionAction) === null || _a === void 0 ? void 0 : _a.call(options, sectionId, actionId, viewId); } });
+            }
             function bindView(v, g, viewLayout, live) {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
-                const common = Object.assign(Object.assign(Object.assign({ gap, padding: gap, rtl: (_b = (_a = live === null || live === void 0 ? void 0 : live.rtl) !== null && _a !== void 0 ? _a : options.rtl) !== null && _b !== void 0 ? _b : false, fluid: mode === 'fluid', static: (_d = (_c = live === null || live === void 0 ? void 0 : live.static) !== null && _c !== void 0 ? _c : options.static) !== null && _d !== void 0 ? _d : false, dragHandle: (_f = (_e = live === null || live === void 0 ? void 0 : live.dragHandle) !== null && _e !== void 0 ? _e : options.dragHandle) !== null && _f !== void 0 ? _f : false }, (options.squeeze !== undefined ? { squeeze: options.squeeze } : {})), ((_g = options.binder) !== null && _g !== void 0 ? _g : {})), { onGesture: (e) => {
+                const common = Object.assign(Object.assign(Object.assign(Object.assign({ gap, padding: gap, rtl: (_b = (_a = live === null || live === void 0 ? void 0 : live.rtl) !== null && _a !== void 0 ? _a : options.rtl) !== null && _b !== void 0 ? _b : false, fluid: mode === 'fluid', static: (_d = (_c = live === null || live === void 0 ? void 0 : live.static) !== null && _c !== void 0 ? _c : options.static) !== null && _d !== void 0 ? _d : false, dragHandle: (_f = (_e = live === null || live === void 0 ? void 0 : live.dragHandle) !== null && _e !== void 0 ? _e : options.dragHandle) !== null && _f !== void 0 ? _f : false }, (options.squeeze !== undefined ? { squeeze: options.squeeze } : {})), ((_g = options.binder) !== null && _g !== void 0 ? _g : {})), { onGesture: (e) => {
                         var _a, _b;
                         if (e.type === 'commit')
                             reportChanged();
                         (_b = (_a = options.binder) === null || _a === void 0 ? void 0 : _a.onGesture) === null || _b === void 0 ? void 0 : _b.call(_a, e);
-                    }, onSelect: (id) => { var _a; return (_a = options.onSelect) === null || _a === void 0 ? void 0 : _a.call(options, id, v.id); } });
+                    }, onSelect: (id) => { var _a; return (_a = options.onSelect) === null || _a === void 0 ? void 0 : _a.call(options, id, v.id); } }), captionHooks(v.id));
                 if (viewLayout === 'split') {
                     return bindDashboardSplit(a, g, Object.assign(Object.assign(Object.assign({}, common), { columns: (_h = v.columns) !== null && _h !== void 0 ? _h : columns, baseRowHeight: rowHeight, designHeight: viewH(v) }), (v.tree !== undefined ? { tree: v.tree } : {})));
                 }
@@ -1272,18 +1351,18 @@ export function dashboard(options) {
             }
             /** Bind (or re-bind) a container's inner grid on its group. */
             function bindContainer(cg, w, viewId, innerRows) {
-                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
                 void viewId;
                 // The LIVE switches ride on the view's binder when it exists (a
                 // container bound after a setStatic/setRtl/setDragHandle must match).
                 const vb = binders.get((_a = ctx.viewOfBoard.get(w.id)) !== null && _a !== void 0 ? _a : ctx.active);
-                const inner = Object.assign(Object.assign({ columns: innerColumnsOf(w), gap, padding: 0, baseRowHeight: rowHeight, rtl: (_c = (_b = vb === null || vb === void 0 ? void 0 : vb.getRtl()) !== null && _b !== void 0 ? _b : options.rtl) !== null && _c !== void 0 ? _c : false, static: (_e = (_d = vb === null || vb === void 0 ? void 0 : vb.getStatic()) !== null && _d !== void 0 ? _d : options.static) !== null && _e !== void 0 ? _e : false, dragHandle: (_g = (_f = vb === null || vb === void 0 ? void 0 : vb.getDragHandle()) !== null && _f !== void 0 ? _f : options.dragHandle) !== null && _g !== void 0 ? _g : false }, (options.squeeze !== undefined ? { squeeze: options.squeeze } : {})), { onGesture: (e) => {
+                const inner = Object.assign(Object.assign(Object.assign({ columns: innerColumnsOf(w), gap, padding: 0, baseRowHeight: rowHeight, rtl: (_c = (_b = vb === null || vb === void 0 ? void 0 : vb.getRtl()) !== null && _b !== void 0 ? _b : options.rtl) !== null && _c !== void 0 ? _c : false, static: (_e = (_d = vb === null || vb === void 0 ? void 0 : vb.getStatic()) !== null && _d !== void 0 ? _d : options.static) !== null && _e !== void 0 ? _e : false, dragHandle: (_g = (_f = vb === null || vb === void 0 ? void 0 : vb.getDragHandle()) !== null && _f !== void 0 ? _f : options.dragHandle) !== null && _g !== void 0 ? _g : false }, (options.squeeze !== undefined ? { squeeze: options.squeeze } : {})), { onGesture: (e) => {
                         var _a, _b;
                         if (e.type === 'commit')
                             reportChanged();
                         (_b = (_a = options.binder) === null || _a === void 0 ? void 0 : _a.onGesture) === null || _b === void 0 ? void 0 : _b.call(_a, e);
-                    }, onSelect: (id) => { var _a, _b; return (_a = options.onSelect) === null || _a === void 0 ? void 0 : _a.call(options, id, (_b = ctx.viewOfBoard.get(w.id)) !== null && _b !== void 0 ? _b : ctx.active); } });
-                if (((_h = ctx.layoutOf.get(w.id)) !== null && _h !== void 0 ? _h : w.layout) === 'split') {
+                    }, onSelect: (id) => { var _a, _b; return (_a = options.onSelect) === null || _a === void 0 ? void 0 : _a.call(options, id, (_b = ctx.viewOfBoard.get(w.id)) !== null && _b !== void 0 ? _b : ctx.active); } }), captionHooks((_h = ctx.viewOfBoard.get(w.id)) !== null && _h !== void 0 ? _h : ctx.active));
+                if (((_j = ctx.layoutOf.get(w.id)) !== null && _j !== void 0 ? _j : w.layout) === 'split') {
                     // A splitter tree covering the pane; the pane's frame is the parent's
                     // slab, so no design height of its own.
                     binders.set(w.id, bindDashboardSplit(a, cg, Object.assign(Object.assign({}, inner), (w.tree !== undefined ? { tree: w.tree } : {}))));
@@ -1292,7 +1371,7 @@ export function dashboard(options) {
                 binders.set(w.id, bindDashboardGrid(a, cg, Object.assign(Object.assign({}, inner), { sizing: 'fit', designHeight: 0, 
                     // The DESIGN: authored, else what the group was mounted with, else
                     // the children's extent — the binder's live bound follows the cells.
-                    maxRows: (_l = (_j = innerRows !== null && innerRows !== void 0 ? innerRows : w.maxRows) !== null && _j !== void 0 ? _j : (_k = cg.getMetadata('containerWidget')) === null || _k === void 0 ? void 0 : _k.maxRows) !== null && _l !== void 0 ? _l : rowExtentOf((_m = w.widgets) !== null && _m !== void 0 ? _m : []), float: false, escalate: w.sizing !== 'fit' })));
+                    maxRows: (_m = (_k = innerRows !== null && innerRows !== void 0 ? innerRows : w.maxRows) !== null && _k !== void 0 ? _k : (_l = cg.getMetadata('containerWidget')) === null || _l === void 0 ? void 0 : _l.maxRows) !== null && _m !== void 0 ? _m : rowExtentOf((_o = w.widgets) !== null && _o !== void 0 ? _o : []), float: false, escalate: w.sizing !== 'fit' })));
             }
             /**
              * One reporter for every binder on a view — the view's own and each

package/src/lib/dashboard-kit/grid-binder.d.ts

@@ -198,6 +198,14 @@ export interface DashboardGridOptions {
     /** Inject the hover-revealed corner resize handle into member hosts (default true). */
     /** The selection on this board changed: the selected member — a widget or a SECTION (container) — or undefined. */
     onSelect?: (id: string | undefined) => void;
+    /**
+     * SECTION CAPTIONS (0.4.22). Paint a member section's caption band yourself:
+     * the band is handed over empty, sized and themed, and keeps its press rules.
+     * Default: the kit's icon · text · subtitle · ⓘ · actions.
+     */
+    renderCaption?: (sectionId: string, host: HTMLElement) => void;
+    /** A press on a caption action button (see `SectionCaptionOptions.actions`). */
+    onCaptionAction?: (sectionId: string, actionId: string) => void;
     resizeHandles?: boolean;
     /**
      * FLUID board: the group's frame follows the CANVAS CONTAINER — width

package/src/lib/dashboard-kit/grid-binder.js

@@ -54,6 +54,7 @@ import { AddToGroupCommand, BatchCommand, Command, GridPackEngine, RemoveFromGro
 import { LiveRegionController, registerTool } from '@grafloria/renderer';
 import { buildCommitCommands, cellFromGridItem, cellToRect, columnUnitFor, gridItemFromCell, pointToCell, rowHeightFor, sizeToSpan, } from './grid-mapping.js';
 import { ensureDashboardKitStyles } from './styles.js';
+import { captionOfGroup, captionPainted, captionPassThrough, captionKey, captionReserve, paintCaptionBand, sizeCaptionBand } from './caption.js';
 /** The class of the painted grip element (a child of the node host). */
 export const GRIP_CLASS = 'axdb-grip';
 /** The container class that turns the caption strip's grip dots on. */
@@ -103,12 +104,24 @@ export function syncGrip(host, cfg, movable) {
  * diagram's object, not a namesake from another model.
  */
 export function ownsPress(container, diagram, ev, hit) {
-    var _a;
+    var _a, _b, _c, _d;
     const t = (_a = ev.source) === null || _a === void 0 ? void 0 : _a.target;
     if (typeof Node !== 'undefined' && t instanceof Node && !container.contains(t))
         return false;
     if (hit.node && diagram.getNode(hit.node.id) !== hit.node)
         return false;
+    // A press on a PASS-THROUGH element of a caption band (a button, an input,
+    // anything the caption's `passThrough` names) is the content's, not any
+    // tool's: no selection, no drag, no resize — the DOM handles it.
+    if (typeof Element !== 'undefined' && t instanceof Element) {
+        const band = t.closest('.axdb-slab > .axdb-slab-h');
+        const sid = (_b = band === null || band === void 0 ? void 0 : band.parentElement) === null || _b === void 0 ? void 0 : _b.getAttribute('data-slab-id');
+        if (band && sid) {
+            const grp = (_d = (_c = diagram).getGroup) === null || _d === void 0 ? void 0 : _d.call(_c, sid);
+            if (captionPassThrough(t, band, captionOfGroup(grp)))
+                return false;
+        }
+    }
     return true;
 }
 export function gripHostOf(target) {
@@ -434,14 +447,22 @@ export function bindDashboardGrid(api, group, options = {}) {
     let adoptedGhostId = null;
     let glideTimer = null;
     let ghostTimer = null;
+    /**
+     * OUR OWN CAPTION RESERVE: a section carrying a caption gives the band's
+     * pixels up at the top of its frame, so no child may take them — and the
+     * band is outside `containsWorld`, so a press on it is the PARENT's (it
+     * selects the section) rather than an empty press of this board.
+     */
+    const ownReserve = () => { var _a, _b; return captionReserve(captionOfGroup(group), { static: isStatic, sectionH: (_b = (_a = group.size) === null || _a === void 0 ? void 0 : _a.height) !== null && _b !== void 0 ? _b : 0 }); };
     const frame = () => {
         var _a, _b, _c, _d;
-        return ({
+        const r = ownReserve();
+        return {
             x: group.position.x,
-            y: group.position.y,
+            y: group.position.y + r,
             width: (_b = (_a = group.size) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : 0,
-            height: (_d = (_c = group.size) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : 0,
-        });
+            height: Math.max(0, ((_d = (_c = group.size) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : 0) - r),
+        };
     };
     /** Entity size with GroupModel's optionality flattened away. */
     const sizeOf = (e) => { var _a; return (_a = e.size) !== null && _a !== void 0 ? _a : { width: 0, height: 0 }; };
@@ -621,6 +642,12 @@ export function bindDashboardGrid(api, group, options = {}) {
             writing = false;
         }
         syncPlaceholder();
+        // The section overlays are projected chrome like the placeholder: they
+        // follow every frame write, not only a rebuild. Painted at bind time only,
+        // a section two levels down kept the geometry of its parent's placeholder
+        // frame (100 × 34) after the view board had laid the parent out (the kit
+        // lab's L47, 2026-09-08).
+        syncSlabs();
     };
     // -- placeholder / ghost chrome --------------------------------------------
     /** The placeholder exists ONLY while a gesture is live — so at any moment
@@ -1145,6 +1172,7 @@ export function bindDashboardGrid(api, group, options = {}) {
             el.classList.toggle('axdb-slab--selected', selectedId === id);
             el.classList.toggle('axdb-slab--static', isStatic);
             (_b = el.querySelector(':scope > .axdb-rs')) === null || _b === void 0 ? void 0 : _b.classList.toggle('axdb-rs--rtl', rtl);
+            syncCaption(el, id, grp, sz.height);
         }
         for (const [id, el] of slabEls) {
             if (!seen.has(id)) {
@@ -1153,6 +1181,38 @@ export function bindDashboardGrid(api, group, options = {}) {
             }
         }
     };
+    /**
+     * THE CAPTION BAND of a section, on its slab overlay. Painted from the
+     * group's persisted caption; repainted only when its identity changes (the
+     * options, RTL, static, the tier) so a custom `renderCaption` is not run
+     * per frame. The band takes the pointer (the slab itself does not): a press
+     * on it selects the section, an action fires, pass-through reaches content.
+     */
+    const syncCaption = (el, id, grp, sectionH) => {
+        const cap = captionOfGroup(grp);
+        let band = el.querySelector(':scope > .axdb-slab-h');
+        if (!cap || !captionPainted(cap, isStatic)) {
+            band === null || band === void 0 ? void 0 : band.remove();
+            el.removeAttribute('aria-label');
+            return;
+        }
+        const ctx = { rtl, static: isStatic, sectionH };
+        const key = captionKey(cap, ctx);
+        if (band && band.getAttribute('data-key') === key) {
+            sizeCaptionBand(band, cap, sectionH); // the tier follows the live size
+            return;
+        }
+        band === null || band === void 0 ? void 0 : band.remove();
+        band = document.createElement('div');
+        el.prepend(band);
+        const render = options.renderCaption;
+        paintCaptionBand(band, cap, Object.assign(Object.assign(Object.assign({}, ctx), (render ? { render: (host) => render(id, host) } : {})), { onAction: (actionId) => { var _a; return (_a = options.onCaptionAction) === null || _a === void 0 ? void 0 : _a.call(options, id, actionId); } }));
+        band.setAttribute('data-key', key);
+        if (cap.text)
+            el.setAttribute('aria-label', cap.text);
+        else
+            el.removeAttribute('aria-label');
+    };
     const insideMemberGroupFrame = (x, y) => {
         var _a;
         for (const id of (_a = group.members) !== null && _a !== void 0 ? _a : []) {
@@ -2135,15 +2195,22 @@ export function bindDashboardGrid(api, group, options = {}) {
         id: `dashboard-grid:${group.id}:${++binderSeq}`,
         priority: 2, // point-specific claim — outranks mode-style tools (see ext/tools.ts)
         hitTest(ev, hit) {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
             if (disposed)
                 return false;
             if (gesture || slabGesture || forwardSlab)
                 return true; // own the rest of an in-flight gesture
             if (!ownsPress(api.container, diagram, ev, hit))
                 return false;
+            // A press on one of OUR sections' caption bands is ours by the DOM: a
+            // 'tab' band sits above the frame, over the gap or the tile above,
+            // where the geometry says otherwise.
+            const bandTarget = (_c = (_b = (_a = ev.source) === null || _a === void 0 ? void 0 : _a.target) === null || _b === void 0 ? void 0 : _b.closest) === null || _c === void 0 ? void 0 : _c.call(_b, '.axdb-slab > .axdb-slab-h');
+            const bandId = (_d = bandTarget === null || bandTarget === void 0 ? void 0 : bandTarget.parentElement) === null || _d === void 0 ? void 0 : _d.getAttribute('data-slab-id');
+            if (bandId && ((_e = group.members) !== null && _e !== void 0 ? _e : new Set()).has(bandId))
+                return true;
             if (hit.node) {
-                if (((_a = group.members) !== null && _a !== void 0 ? _a : new Set()).has(hit.node.id))
+                if (((_f = group.members) !== null && _f !== void 0 ? _f : new Set()).has(hit.node.id))
                     return true;
                 // A press on a tile that belongs to a NESTED board must reach that
                 // board's tool. The dead-zone claim below deadens the slab's EMPTY
@@ -2152,7 +2219,7 @@ export function bindDashboardGrid(api, group, options = {}) {
                 // parent's tool won the registration-order tie and the child's resize
                 // never armed; grid-options binds parent-first and worked by
                 // accident).
-                for (const p of (_b = BOARD_REGISTRY.get(api.container)) !== null && _b !== void 0 ? _b : []) {
+                for (const p of (_g = BOARD_REGISTRY.get(api.container)) !== null && _g !== void 0 ? _g : []) {
                     if (p !== selfPeer && p.hasItem(hit.node.id))
                         return false;
                 }
@@ -2165,8 +2232,8 @@ export function bindDashboardGrid(api, group, options = {}) {
             // divider press in a split section (dead dividers) and, near the
             // section's edge, turned it into a section resize (the width changed
             // while a control's height was being dragged — Quantia, Groups page).
-            for (const p of (_c = BOARD_REGISTRY.get(api.container)) !== null && _c !== void 0 ? _c : []) {
-                if (p !== selfPeer && ((_d = group.members) !== null && _d !== void 0 ? _d : new Set()).has(p.group.id) && p.containsWorld(ev.world.x, ev.world.y))
+            for (const p of (_h = BOARD_REGISTRY.get(api.container)) !== null && _h !== void 0 ? _h : []) {
+                if (p !== selfPeer && ((_j = group.members) !== null && _j !== void 0 ? _j : new Set()).has(p.group.id) && p.containsWorld(ev.world.x, ev.world.y))
                     return false;
             }
             // Claim (and deaden) empty presses inside a member group's frame so the
@@ -2178,7 +2245,7 @@ export function bindDashboardGrid(api, group, options = {}) {
             return insideMemberGroupFrame(ev.world.x, ev.world.y) || worldInsideBoard(ev.world.x, ev.world.y);
         },
         onPointerDown(ev, hit) {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
             if (gesture)
                 return; // mid-palette
             const target = ((_b = (_a = ev.source) === null || _a === void 0 ? void 0 : _a.target) !== null && _b !== void 0 ? _b : null);
@@ -2191,12 +2258,21 @@ export function bindDashboardGrid(api, group, options = {}) {
             // A SECTION's corner handle sits on top of whatever tile shares that
             // corner; the DOM target names the section, the hit test the tile.
             const sectionHandle = (_e = target === null || target === void 0 ? void 0 : target.closest) === null || _e === void 0 ? void 0 : _e.call(target, '.axdb-slab > .axdb-rs');
-            if ((!hit.node && !onGrip) || sectionHandle) {
-                // A press on a SECTION — its empty band, its corner handle or its
-                // frame edge — selects the section; the handle or an edge resizes it.
-                const slabHandle = (_f = target === null || target === void 0 ? void 0 : target.closest) === null || _f === void 0 ? void 0 : _f.call(target, '.axdb-slab > .axdb-rs');
-                const slabId = (_h = (_g = slabHandle === null || slabHandle === void 0 ? void 0 : slabHandle.parentElement) === null || _g === void 0 ? void 0 : _g.getAttribute('data-slab-id')) !== null && _h !== void 0 ? _h : memberGroupAt(ev.world.x, ev.world.y);
-                const grp = slabId && ((_j = group.members) !== null && _j !== void 0 ? _j : new Set()).has(slabId) ? diagram.getGroup(slabId) : undefined;
+            // A SECTION's CAPTION BAND names its section the same way — a 'tab'
+            // band sits above the frame, over the gap or the tile above. An action
+            // button in it fires and does nothing else.
+            const captionBand = (_f = target === null || target === void 0 ? void 0 : target.closest) === null || _f === void 0 ? void 0 : _f.call(target, '.axdb-slab > .axdb-slab-h');
+            const captionId = (_h = (_g = captionBand === null || captionBand === void 0 ? void 0 : captionBand.parentElement) === null || _g === void 0 ? void 0 : _g.getAttribute('data-slab-id')) !== null && _h !== void 0 ? _h : null;
+            const ownCaption = !!captionId && ((_j = group.members) !== null && _j !== void 0 ? _j : new Set()).has(captionId);
+            // (An action button never reaches here: it is pass-through, and its own
+            // `click` fires onCaptionAction — see captionPassThrough.)
+            if ((!hit.node && !onGrip) || sectionHandle || ownCaption) {
+                // A press on a SECTION — its empty band, its caption, its corner
+                // handle or its frame edge — selects the section; the handle or an
+                // edge resizes it.
+                const slabHandle = (_k = target === null || target === void 0 ? void 0 : target.closest) === null || _k === void 0 ? void 0 : _k.call(target, '.axdb-slab > .axdb-rs');
+                const slabId = (_o = (_m = (_l = slabHandle === null || slabHandle === void 0 ? void 0 : slabHandle.parentElement) === null || _l === void 0 ? void 0 : _l.getAttribute('data-slab-id')) !== null && _m !== void 0 ? _m : (ownCaption ? captionId : null)) !== null && _o !== void 0 ? _o : memberGroupAt(ev.world.x, ev.world.y);
+                const grp = slabId && ((_p = group.members) !== null && _p !== void 0 ? _p : new Set()).has(slabId) ? diagram.getGroup(slabId) : undefined;
                 if (slabId && grp) {
                     selectWidget(slabId);
                     api.render();
@@ -2215,7 +2291,7 @@ export function bindDashboardGrid(api, group, options = {}) {
                 // forwards the pointer sequence.
                 const parent = parentPeer();
                 if ((parent === null || parent === void 0 ? void 0 : parent.selectMember) && worldInsideBoard(ev.world.x, ev.world.y)) {
-                    const ownHandle = ((_k = slabHandle === null || slabHandle === void 0 ? void 0 : slabHandle.parentElement) === null || _k === void 0 ? void 0 : _k.getAttribute('data-slab-id')) === group.id;
+                    const ownHandle = ((_q = slabHandle === null || slabHandle === void 0 ? void 0 : slabHandle.parentElement) === null || _q === void 0 ? void 0 : _q.getAttribute('data-slab-id')) === group.id;
                     parent.selectMember(group.id);
                     if (!isStatic && parent.beginSlabResize) {
                         const edges = ownHandle
@@ -2228,7 +2304,7 @@ export function bindDashboardGrid(api, group, options = {}) {
                 }
                 // The board's own empty area: a void click. Nothing to drag, and the
                 // selection clears exactly as a click outside any board would.
-                (_m = (_l = diagram).clearSelection) === null || _m === void 0 ? void 0 : _m.call(_l);
+                (_s = (_r = diagram).clearSelection) === null || _s === void 0 ? void 0 : _s.call(_r);
                 selectWidget(undefined);
                 api.render();
                 return;
@@ -2237,17 +2313,17 @@ export function bindDashboardGrid(api, group, options = {}) {
             if (!node)
                 return;
             selectWidget(node.id); // a press selects, whether or not it starts a gesture
-            if (((_o = node.state) === null || _o === void 0 ? void 0 : _o.locked) === true)
+            if (((_t = node.state) === null || _t === void 0 ? void 0 : _t.locked) === true)
                 return; // pinned: refuse; click still focuses
             if (isStatic)
                 return; // a static board: claimed and deadened, click still focuses
             // Which edges did the press take? The corner handle names its own (s+e,
             // or s+w on RTL); a bare press within EDGE_GRIP of the tile's border
             // takes that border; anywhere else is a move. A grip press is a move.
-            const onHandle = !!((_p = target === null || target === void 0 ? void 0 : target.closest) === null || _p === void 0 ? void 0 : _p.call(target, '.axdb-rs'));
+            const onHandle = !!((_u = target === null || target === void 0 ? void 0 : target.closest) === null || _u === void 0 ? void 0 : _u.call(target, '.axdb-rs'));
             const hostEl = hostOf(node.id);
-            const resizable = ((_q = node.getMetadata) === null || _q === void 0 ? void 0 : _q.call(node, 'widgetResizable')) !== false;
-            const movable = ((_r = node.getMetadata) === null || _r === void 0 ? void 0 : _r.call(node, 'widgetMovable')) !== false;
+            const resizable = ((_v = node.getMetadata) === null || _v === void 0 ? void 0 : _v.call(node, 'widgetResizable')) !== false;
+            const movable = ((_w = node.getMetadata) === null || _w === void 0 ? void 0 : _w.call(node, 'widgetMovable')) !== false;
             // `ev.screen` is ELEMENT-LOCAL px; host rects are in client px. Compare
             // like with like — the source event's clientX/Y when there is one, else
             // the container's origin plus the local offset.
@@ -2295,7 +2371,7 @@ export function bindDashboardGrid(api, group, options = {}) {
                 startSize: { width: node.size.width, height: node.size.height },
                 startPos: { x: node.position.x, y: node.position.y },
                 edges,
-                spans: { w: (_s = it === null || it === void 0 ? void 0 : it.w) !== null && _s !== void 0 ? _s : 1, h: (_t = it === null || it === void 0 ? void 0 : it.h) !== null && _t !== void 0 ? _t : 1 },
+                spans: { w: (_x = it === null || it === void 0 ? void 0 : it.w) !== null && _x !== void 0 ? _x : 1, h: (_y = it === null || it === void 0 ? void 0 : it.h) !== null && _y !== void 0 ? _y : 1 },
                 removedFromBoard: false,
                 leg: null,
                 lastWorld: null,
@@ -2832,6 +2908,9 @@ export function bindDashboardGrid(api, group, options = {}) {
             isStatic = on;
             if (gesture)
                 cancelActiveGesture(false);
+            // A `show: 'design'` caption leaves under static and its reserve with
+            // it (or comes back): the frame moved, re-project the tiles.
+            project();
             syncHandles();
             api.renderNow();
         },

package/src/lib/dashboard-kit/index.d.ts

@@ -3,5 +3,6 @@ export { bindDashboardSplit, SetSplitTreeCommand, SPLIT_TREE_KEY, type Dashboard
 export { projectSplit, dividersOf, addSplitLeaf, removeSplitLeaf, insertSplitLeaf, moveSplitDivider, splitFromCells, cellsFromSplit, splitLeaves, type SplitNode, type SplitGroup, type SplitLeaf, type SplitDir, type SplitSide, type SplitDivider, } from './split-layout.js';
 export { rowHeightFor, boardHeightFor, columnUnitFor, cellToRect, pointToCell, sizeToSpan, spanWidthPx, gridItemFromCell, cellFromGridItem, buildCommitCommands, type CellRect, type WorldRect, type DashboardGridGeometry, type TileDelta, } from './grid-mapping.js';
 export { ensureDashboardKitStyles, DASHBOARD_KIT_STYLE_ID } from './styles.js';
+export { normalizeCaption, captionReserve, captionBandHeight, paintCaptionBand, CAPTION_HEIGHT, CAPTION_HEIGHT_SUBTITLE, CAPTION_HEIGHT_TIGHT, CAPTION_PASS_THROUGH, type SectionCaption, type SectionCaptionOptions, type SectionCaptionAction, type SectionCaptionFont, } from './caption.js';
 export { dashboard, type DashboardOptions, type DashboardSpec, type DashboardSnapshot, type DashboardHandle, type DashboardViewSpec, type DashboardWidgetSpec, type WidgetHandle, } from './dashboard.js';
 export { defaultWidgetRenderer, renderKpiWidget, renderLineWidget, renderBarWidget, renderDonutWidget, renderFunnelWidget, renderTableWidget, BUILT_IN_WIDGET_KINDS, type WidgetRenderer, type KpiWidgetData, type LineWidgetData, type LineSeries, type BarWidgetData, type DonutWidgetData, type FunnelWidgetData, type TableWidgetData, } from './widgets.js';

package/src/lib/dashboard-kit/index.js

@@ -3,6 +3,7 @@ export { bindDashboardSplit, SetSplitTreeCommand, SPLIT_TREE_KEY, } from './spli
 export { projectSplit, dividersOf, addSplitLeaf, removeSplitLeaf, insertSplitLeaf, moveSplitDivider, splitFromCells, cellsFromSplit, splitLeaves, } from './split-layout.js';
 export { rowHeightFor, boardHeightFor, columnUnitFor, cellToRect, pointToCell, sizeToSpan, spanWidthPx, gridItemFromCell, cellFromGridItem, buildCommitCommands, } from './grid-mapping.js';
 export { ensureDashboardKitStyles, DASHBOARD_KIT_STYLE_ID } from './styles.js';
+export { normalizeCaption, captionReserve, captionBandHeight, paintCaptionBand, CAPTION_HEIGHT, CAPTION_HEIGHT_SUBTITLE, CAPTION_HEIGHT_TIGHT, CAPTION_PASS_THROUGH, } from './caption.js';
 // The DATA-FIRST authoring API (the erDiagram/umlDiagram equivalent).
 export { dashboard, } from './dashboard.js';
 // The built-in renderers behind `kind` — dashboard()'s default renderWidget.

package/src/lib/dashboard-kit/split-binder.js

@@ -29,6 +29,7 @@ import { anyEdge, clearOtherSelections, dragHandleSelector, gripHostOf, gripOf,
 import { cellFromGridItem } from './grid-mapping.js';
 import { addSplitLeaf, cellsFromSplit, cloneSplit, dividersOf, groupRectsOf, insertSplitLeaf, moveSplitDivider, normalizeSplit, pathToLeaf, projectSplit, removeSplitLeaf, splitFromCells, splitLeaves, } from './split-layout.js';
 import { ensureDashboardKitStyles } from './styles.js';
+import { captionOfGroup, captionReserve } from './caption.js';
 /** Group metadata key the tree persists under. */
 export const SPLIT_TREE_KEY = 'dashboardTree';
 /**
@@ -104,14 +105,17 @@ export function bindDashboardSplit(api, group, options = {}) {
     let focusedId;
     const live = liveRegionFor(api.container);
     // -- geometry ---------------------------------------------------------------
+    /** Our own caption band's pixels, given up at the top of the pane (see grid-binder). */
+    const ownReserve = () => { var _a, _b; return captionReserve(captionOfGroup(group), { static: isStatic, sectionH: (_b = (_a = group.size) === null || _a === void 0 ? void 0 : _a.height) !== null && _b !== void 0 ? _b : 0 }); };
     const frame = () => {
         var _a, _b, _c, _d;
-        return ({
+        const r = ownReserve();
+        return {
             x: group.position.x,
-            y: group.position.y,
+            y: group.position.y + r,
             width: (_b = (_a = group.size) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : designW,
-            height: (_d = (_c = group.size) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : designH,
-        });
+            height: Math.max(0, ((_d = (_c = group.size) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : designH) - r),
+        };
     };
     const containerBox = () => ({
         w: api.container.clientWidth || 0,

package/src/lib/dashboard-kit/styles.js

@@ -365,6 +365,61 @@ const CSS = `
 .grafloria-html-layer > .axdb-slab.axdb-slab--selected > .axdb-rs { pointer-events: auto; opacity: 1; }
 .grafloria-html-layer > .axdb-slab.axdb-slab--static > .axdb-rs { display: none; }
 
+/* SECTION CAPTION (0.4.22): the band on the slab. Geometry is inline (the
+   reserve and the pixels come from one function); everything visual is a
+   variable the options write and a theme may override. The band takes the
+   pointer — the slab does not — so a press on it is the section's. */
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h {
+  position: absolute; box-sizing: border-box; pointer-events: auto; z-index: 1;
+  display: flex; align-items: center; gap: 6px; min-width: 0;
+  padding: var(--axdb-caption-pad, 0 10px);
+  background: var(--axdb-caption-bg, rgba(31, 36, 48, .045));
+  border-bottom: var(--axdb-caption-border, none);
+  color: var(--axdb-caption-fg, #1f2430);
+  font: var(--axdb-caption-font-weight, 600) var(--axdb-caption-font-size, 13px)/1.2 var(--axdb-caption-font-family, system-ui, -apple-system, "Segoe UI", sans-serif);
+  text-transform: var(--axdb-caption-transform, none);
+  letter-spacing: .01em;
+  border-radius: var(--axdb-rs-radius, 3px) var(--axdb-rs-radius, 3px) 0 0;
+  cursor: default; user-select: none; -webkit-user-select: none; overflow: hidden;
+  transition: opacity .12s;
+}
+/* The modifiers carry the band's own selector so they outrank its defaults. */
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--center { justify-content: center; }
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--end { justify-content: flex-end; }
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--vtop { align-items: flex-start; }
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--vbottom { align-items: flex-end; }
+/* 'tab': above the frame, sized to its text */
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--tab { right: auto; max-width: 100%; }
+/* 'hover': an overlay that appears with the pointer or the selection */
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--hover { opacity: 0; }
+.grafloria-html-layer > .axdb-slab:hover > .axdb-slab-h.axdb-slab-h--hover,
+.grafloria-html-layer > .axdb-slab.axdb-slab--selected > .axdb-slab-h.axdb-slab-h--hover,
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--hover:focus-within { opacity: 1; }
+/* the tight tier: a section under 90 px */
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--tight { font-size: min(var(--axdb-caption-font-size, 12px), 12px); gap: 4px; }
+.axdb-slab-h--tight .axdb-slab-h-sub, .axdb-slab-h--tight .axdb-slab-h-actions { display: none; }
+.axdb-slab-h-icon { flex: none; }
+.axdb-slab-h-body { display: flex; flex-direction: column; justify-content: center; min-width: 0; flex: 0 1 auto; }
+.axdb-slab-h-text, .axdb-slab-h-sub { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.axdb-slab-h-sub { font-size: .85em; font-weight: 500; opacity: .72; }
+.axdb-slab-h-info { flex: none; opacity: .6; font-size: .9em; cursor: help; }
+.axdb-slab-h-actions { flex: none; display: flex; gap: 2px; margin-inline-start: auto; opacity: 0; transition: opacity .12s; }
+.axdb-slab-h--center .axdb-slab-h-actions, .axdb-slab-h--end .axdb-slab-h-actions { margin-inline-start: 0; }
+.axdb-slab-h:hover > .axdb-slab-h-actions, .axdb-slab--selected > .axdb-slab-h > .axdb-slab-h-actions, .axdb-slab-h:focus-within > .axdb-slab-h-actions { opacity: 1; }
+.axdb-slab-h-action {
+  all: unset; box-sizing: border-box; width: 24px; height: 24px; display: inline-flex; align-items: center; justify-content: center;
+  border-radius: 4px; cursor: pointer; font-size: 14px; line-height: 1; color: inherit;
+}
+.axdb-slab-h-action:hover { background: rgba(31, 36, 48, .08); }
+.axdb-slab-h-action:focus-visible { outline: 2px solid var(--axdb-accent-ring, rgba(59, 82, 217, .55)); outline-offset: -2px; }
+.axdb-slab-h-action[disabled] { opacity: .4; cursor: default; }
+.axdb-slab-h-action[disabled]:hover { background: none; }
+.grafloria-html-layer > .axdb-slab.axdb-slab--static > .axdb-slab-h { cursor: default; }
+@media (prefers-color-scheme: dark) {
+  .grafloria-html-layer > .axdb-slab > .axdb-slab-h { background: var(--axdb-caption-bg, rgba(236, 238, 244, .06)); color: var(--axdb-caption-fg, #eceef4); }
+  .axdb-slab-h-action:hover { background: rgba(236, 238, 244, .1); }
+}
+
 /* legend chips, shared by line and donut */
 .axdb-lg { display: flex; flex-wrap: wrap; gap: 4px 12px; margin-top: 9px; }
 .axdb-lg--col { flex-direction: column; flex-wrap: nowrap; gap: 6px; margin-top: 0; }