@grafloria/element 0.4.22 → 0.4.23

package/package.json

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

package/src/index.d.ts

@@ -79,7 +79,7 @@ export type { JoinColumn, JoinEnd, MatchTier, JoinGuidanceApi, JoinGuidanceOptio
 export type { ErColumn, ErEntitySpec, ErRelationshipSpec, ErCardinality, ErSide, ErDiagramOptions, UmlClassSpec, UmlRelationshipSpec, UmlRelationKind, UmlSide, UmlDiagramOptions, ErEntityDelta, UmlClassDelta, CardEditingHandle, } from './lib/diagram-kit/index.js';
 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 { bindDashboardGrid, normalizeCaption, captionReserve, captionBandHeight, paintCaptionBand, CAPTION_HEIGHT, CAPTION_HEIGHT_SUBTITLE, CAPTION_HEIGHT_TIGHT, CAPTION_PASS_THROUGH, 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, 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';

package/src/index.js

@@ -230,7 +230,7 @@ export { erTable, umlClass, erTables, umlClasses, CardHandle, ErTable, ErField,
 // GridItemConfig. Element-local code, so the Phase-0 wholesale re-export
 // below does NOT cover it — this curated block is its only door.
 // ===========================================================================
-export { bindDashboardGrid, rowHeightFor, boardHeightFor, columnUnitFor, cellToRect, pointToCell, sizeToSpan, gridItemFromCell, cellFromGridItem, buildCommitCommands, ensureDashboardKitStyles, DASHBOARD_KIT_STYLE_ID, 
+export { bindDashboardGrid, normalizeCaption, captionReserve, captionBandHeight, paintCaptionBand, CAPTION_HEIGHT, CAPTION_HEIGHT_SUBTITLE, CAPTION_HEIGHT_TIGHT, CAPTION_PASS_THROUGH, rowHeightFor, boardHeightFor, columnUnitFor, cellToRect, pointToCell, sizeToSpan, gridItemFromCell, cellFromGridItem, buildCommitCommands, ensureDashboardKitStyles, DASHBOARD_KIT_STYLE_ID, 
 // The DATA-FIRST authoring API — the erDiagram()/umlDiagram() equivalent.
 dashboard, 
 // …and the built-in renderers behind `kind`, so a dashboard is useful with

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

@@ -40,7 +40,12 @@ export interface SectionCaptionOptions {
     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. */
+    /**
+     * 'inside' (default): a band across the top of the frame. 'tab': the same
+     * band sized to its text, a label chip at the leading corner. BOTH reserve
+     * their height inside the SECTION's own cell — a header that hangs over the
+     * neighbour above is the overlap bug this feature exists to end.
+     */
     position?: 'inside' | 'tab';
     /** Horizontal alignment (default 'start', mirrored on RTL). */
     align?: 'start' | 'center' | 'end';
@@ -73,6 +78,10 @@ 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;
+/** A band never paints thinner than this. */
+export declare const CAPTION_MIN_HEIGHT = 16;
+/** …nor takes the last pixels: the children keep at least this much. */
+export declare const CAPTION_MIN_CONTENT = 20;
 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;
@@ -84,9 +93,21 @@ export declare function captionOfGroup(grp: {
 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. */
+/**
+ * The band's height for a section of `sectionH` px: the authored height (or
+ * the tier), CLAMPED so the children always keep `CAPTION_MIN_CONTENT` px. A
+ * one-row section used to hand its whole 34 px to a 22 px band and paint a
+ * 12 px sliver of a child.
+ */
 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. */
+/**
+ * Pixels the nested board's frame gives up at the top: the band plus its
+ * vertical margins. A TAB reserves too — it is a narrower band, not a header
+ * hanging over whatever the parent board put above the section (the stress
+ * page had one lying across a chart's legend, and one clipped off the top of
+ * the canvas). Only `show: 'hover'` reserves nothing: it is an overlay by
+ * definition, and it paints opaque so the content beneath stays readable.
+ */
 export declare function captionReserve(c: SectionCaptionOptions | null, ctx: {
     static: boolean;
     sectionH: number;

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

@@ -19,6 +19,10 @@ 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;
+/** A band never paints thinner than this. */
+export const CAPTION_MIN_HEIGHT = 16;
+/** …nor takes the last pixels: the children keep at least this much. */
+export const CAPTION_MIN_CONTENT = 20;
 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) {
@@ -50,18 +54,31 @@ export function captionPainted(c, isStatic) {
         return false;
     return !(c.show === 'design' && isStatic);
 }
-/** The band's height for a section of `sectionH` px. */
+/**
+ * The band's height for a section of `sectionH` px: the authored height (or
+ * the tier), CLAMPED so the children always keep `CAPTION_MIN_CONTENT` px. A
+ * one-row section used to hand its whole 34 px to a 22 px band and paint a
+ * 12 px sliver of a child.
+ */
 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);
+    const want = captionTight(sectionH) ? CAPTION_HEIGHT_TIGHT : (_a = c.height) !== null && _a !== void 0 ? _a : (c.subtitle ? CAPTION_HEIGHT_SUBTITLE : CAPTION_HEIGHT);
+    if (sectionH <= 0)
+        return want;
+    return Math.max(CAPTION_MIN_HEIGHT, Math.min(want, sectionH - CAPTION_MIN_CONTENT));
 }
-/** Pixels the nested board's frame gives up at the top: the band plus its vertical margins. */
+/**
+ * Pixels the nested board's frame gives up at the top: the band plus its
+ * vertical margins. A TAB reserves too — it is a narrower band, not a header
+ * hanging over whatever the parent board put above the section (the stress
+ * page had one lying across a chart's legend, and one clipped off the top of
+ * the canvas). Only `show: 'hover'` reserves nothing: it is an overlay by
+ * definition, and it paints opaque so the content beneath stays readable.
+ */
 export function captionReserve(c, ctx) {
     if (!c || !captionPainted(c, ctx.static))
         return 0;
-    if (c.position === 'tab' || c.show === 'hover')
+    if (c.show === 'hover')
         return 0;
     const [mv] = pairOf(c.margin, [0, 0]);
     return captionBandHeight(c, ctx.sectionH) + 2 * mv;
@@ -72,13 +89,16 @@ export function captionKey(c, ctx) {
 }
 /** Is a section of `sectionH` px in the tight tier? */
 export const captionTight = (sectionH) => sectionH > 0 && sectionH < CAPTION_TIGHT_BELOW;
+/** Where the band's box sits horizontally: a tab hugs the LEADING edge, mirrored on RTL. */
+function bandSides(c, mh, rtl) {
+    if (c.position !== 'tab')
+        return { left: `${mh}px`, right: `${mh}px` };
+    return rtl ? { left: 'auto', right: `${mh}px` } : { left: `${mh}px`, right: 'auto' };
+}
 /** 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`;
+    band.style.height = `${captionBandHeight(c, sectionH)}px`;
 }
 /**
  * Is a press on `target`, inside `band`, content rather than the band? An
@@ -129,9 +149,10 @@ export function paintCaptionBand(band, c, ctx) {
             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
+    band.style.top = `${mv}px`;
+    const sides = bandSides(c, mh, ctx.rtl);
+    band.style.left = sides.left;
+    band.style.right = sides.right;
     const v = (name, value) => {
         if (value === undefined)
             band.style.removeProperty(name);

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

@@ -436,6 +436,14 @@ export interface DashboardGridHandle {
  * the feature).
  */
 interface BinderPeer {
+    /**
+     * Does this board paint SECTION CHROME (the slab overlay that carries the
+     * ring, the corner handle and the caption band) for its member groups? Only
+     * the grid binder does. A section reserves its caption's pixels ONLY when
+     * its parent paints one — otherwise a captioned section inside a SPLIT
+     * board pushed its children down by 44 px under a band nobody drew.
+     */
+    paintsCaptions?: boolean;
     group: GroupModel;
     /** True when this board's engine holds `id` as an item (member lookup). */
     hasItem(id: string): boolean;

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

@@ -453,7 +453,12 @@ export function bindDashboardGrid(api, group, options = {}) {
      * 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 ownReserve = () => {
+        var _a, _b, _c;
+        return ((_a = parentPeer()) === null || _a === void 0 ? void 0 : _a.paintsCaptions) === true
+            ? captionReserve(captionOfGroup(group), { static: isStatic, sectionH: (_c = (_b = group.size) === null || _b === void 0 ? void 0 : _b.height) !== null && _c !== void 0 ? _c : 0 })
+            : 0;
+    };
     const frame = () => {
         var _a, _b, _c, _d;
         const r = ownReserve();
@@ -2186,6 +2191,7 @@ export function bindDashboardGrid(api, group, options = {}) {
         containsWorldExtended: worldInsideBoardExtended,
         frameArea: boardArea,
         adopt,
+        paintsCaptions: true, // the grid binder owns the slab overlays (syncSlabs)
     };
     peersOnCanvas().add(selfPeer);
     selfPeerRef = selfPeer;
@@ -2412,10 +2418,34 @@ export function bindDashboardGrid(api, group, options = {}) {
      * container; the corner handle keeps its own cursor from the stylesheet.
      */
     let hoverHost = null;
+    /**
+     * A `show: 'hover'` caption cannot ride CSS `:hover`: the slab overlay takes
+     * no pointer (by design — it must never steal a press), and while the band
+     * is hidden it takes none either, so nothing in the section is ever hovered
+     * in CSS terms. The binder already tracks the pointer; it marks the section
+     * under it instead.
+     */
+    const markHotSection = (clientX, clientY) => {
+        if (!slabEls.size)
+            return;
+        for (const [id, el] of slabEls) {
+            if (!el.querySelector(':scope > .axdb-slab-h--hover'))
+                continue;
+            const r = el.getBoundingClientRect();
+            const hot = clientX >= r.left && clientX <= r.right && clientY >= r.top && clientY <= r.bottom;
+            el.classList.toggle('axdb-slab--hot', hot);
+            void id;
+        }
+    };
+    const onHoverLeave = () => {
+        for (const el of slabEls.values())
+            el.classList.remove('axdb-slab--hot');
+    };
     const onHover = (e) => {
         var _a, _b, _c, _d, _e, _f, _g, _h;
         if (disposed || gesture)
             return;
+        markHotSection(e.clientX, e.clientY);
         // The event may target the host, its content, or (when a host's content
         // is pointer-transparent) the canvas under it — find the member host by
         // the pointer's position in that case.
@@ -2465,6 +2495,7 @@ export function bindDashboardGrid(api, group, options = {}) {
             host.removeAttribute('data-axdb-edge');
     };
     api.container.addEventListener('pointermove', onHover, { passive: true });
+    api.container.addEventListener('pointerleave', onHoverLeave, { passive: true });
     /**
      * STATIC BOARDS LET CONTENT BE CLICKED. The renderer prevents the default of
      * every press a tool claims, which cancels the compatibility mouse events —
@@ -3041,6 +3072,7 @@ export function bindDashboardGrid(api, group, options = {}) {
             peersOnCanvas().delete(selfPeer);
             unregisterTool();
             api.container.removeEventListener('pointermove', onHover);
+            api.container.removeEventListener('pointerleave', onHoverLeave);
             guardedLayer === null || guardedLayer === void 0 ? void 0 : guardedLayer.removeEventListener('pointerdown', staticGuard);
             api.container.removeEventListener('focusin', onFocusIn);
             api.container.removeEventListener('keydown', onKey);

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

@@ -105,8 +105,19 @@ 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 }); };
+    /**
+     * Our own caption band's pixels, given up at the top of the pane — but only
+     * when the parent board actually paints one (see BinderPeer.paintsCaptions).
+     * A split board paints no section chrome, so a captioned section inside one
+     * reserves nothing until the tab-container round gives the split binder its
+     * own overlays.
+     */
+    const ownReserve = () => {
+        var _a, _b, _c;
+        return ((_a = parentPeerOf(api.container, group.id)) === null || _a === void 0 ? void 0 : _a.paintsCaptions) === true
+            ? captionReserve(captionOfGroup(group), { static: isStatic, sectionH: (_c = (_b = group.size) === null || _b === void 0 ? void 0 : _b.height) !== null && _c !== void 0 ? _c : 0 })
+            : 0;
+    };
     const frame = () => {
         var _a, _b, _c, _d;
         const r = ownReserve();

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

@@ -373,8 +373,10 @@ const CSS = `
   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);
+  background: var(--axdb-caption-bg, rgba(31, 36, 48, .055));
+  /* A hairline by default: two bands meeting (a captioned section inside a
+     captioned section) read as two headers, not one grey block. */
+  border-bottom: var(--axdb-caption-border, 1px solid rgba(31, 36, 48, .1));
   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);
@@ -388,13 +390,27 @@ const CSS = `
 .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; }
+/* 'tab': the same band sized to its text, a chip at the leading corner. It
+   reserves its height like 'inside' — see captionReserve. */
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--tab {
+  max-width: 100%; border-radius: var(--axdb-rs-radius, 3px);
+  border-bottom: var(--axdb-caption-border-tab, none);
+  box-shadow: inset 0 0 0 1px rgba(31, 36, 48, .08);
+}
+/* 'hover': an overlay. It reserves nothing, so while hidden it must not take
+   the pointer (an invisible band swallowed clicks on the content beneath),
+   and while shown it paints OPAQUE — a 5% tint over a chart is a smear. */
+.grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--hover {
+  opacity: 0; pointer-events: none;
+  background: var(--axdb-caption-bg, #fff);
+  box-shadow: 0 1px 4px rgba(31, 36, 48, .16);
+}
+/* .axdb-slab--hot is set by the binder from the live pointer (the overlay
+   takes no pointer of its own, so CSS :hover can never fire on it). */
+.grafloria-html-layer > .axdb-slab.axdb-slab--hot > .axdb-slab-h.axdb-slab-h--hover,
+.grafloria-html-layer > .axdb-slab.axdb-slab--selected > .axdb-slab-h.axdb-slab-h--hover { pointer-events: auto; opacity: 1; }
+/* the actions of a hovered or selected section */
+.grafloria-html-layer > .axdb-slab.axdb-slab--hot > .axdb-slab-h > .axdb-slab-h-actions { 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; }
@@ -416,7 +432,13 @@ const CSS = `
 .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); }
+  .grafloria-html-layer > .axdb-slab > .axdb-slab-h {
+    background: var(--axdb-caption-bg, rgba(236, 238, 244, .07));
+    color: var(--axdb-caption-fg, #eceef4);
+    border-bottom: var(--axdb-caption-border, 1px solid rgba(236, 238, 244, .12));
+  }
+  .grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--tab { box-shadow: inset 0 0 0 1px rgba(236, 238, 244, .12); }
+  .grafloria-html-layer > .axdb-slab > .axdb-slab-h.axdb-slab-h--hover { background: var(--axdb-caption-bg, #1a1d25); box-shadow: 0 1px 4px rgba(0, 0, 0, .5); }
   .axdb-slab-h-action:hover { background: rgba(236, 238, 244, .1); }
 }