@jackuait/blok 0.11.1 → 0.12.1

package/src/components/utils/popover/popover-nested-position.ts

@@ -0,0 +1,132 @@
+/**
+ * Input for resolving the side (left / right of the parent popover) the
+ * nested popover should open on.
+ */
+export interface NestedPopoverPositionInput {
+  /** Viewport-relative rect of the parent popover container. */
+  parentRect: { left: number; right: number; width: number };
+  /** Measured nested popover width (container offsetWidth). */
+  nestedWidth: number;
+  /** Current viewport width (window.innerWidth). */
+  viewportWidth: number;
+  /**
+   * Preferred side derived from the parent's own positioning.
+   * True when the parent already sits "open-left" (right-aligned or
+   * placed left of its anchor) — the nested popover prefers to continue
+   * extending leftward unless no room remains.
+   */
+  parentPrefersLeft: boolean;
+  /**
+   * Horizontal overlap (px) between the parent and a right-side nested
+   * popover. The nested popover can overlap the parent's trailing edge by
+   * this many pixels, which effectively grants the nested popover extra
+   * horizontal room on the right.
+   * Defaults to 4 to match the `--nested-popover-overlap` CSS variable.
+   */
+  overlap?: number;
+}
+
+export interface NestedPopoverPositionOutput {
+  /** True when the nested popover should open to the left of the parent. */
+  openLeft: boolean;
+}
+
+/**
+ * Picks the side the nested popover should open on.
+ *
+ * The rules, in order:
+ *   1. If the nested popover fits on the preferred side, keep it there.
+ *   2. Otherwise, flip to the alternate side if it fits there.
+ *   3. If neither side fits, pick the side with more available space so the
+ *      popover stays as close to on-screen as possible.
+ *
+ * The decision is based purely on measured pixel geometry — never on the
+ * parent's own positioning flag alone. That flag may mean different things
+ * in different placement modes (open-left after right-edge flip vs.
+ * placeLeftOfAnchor), and blindly mirroring it onto the nested popover
+ * pushed it off-screen when the parent itself hugged the viewport's left
+ * edge. See `src/components/utils/popover/popover-desktop.ts`.
+ */
+export function resolveNestedPopoverSide(input: NestedPopoverPositionInput): NestedPopoverPositionOutput {
+  const {
+    parentRect,
+    nestedWidth,
+    viewportWidth,
+    parentPrefersLeft,
+    overlap = 4,
+  } = input;
+
+  const spaceOnLeft = Math.max(0, parentRect.left);
+  const spaceOnRight = Math.max(0, viewportWidth - parentRect.right + overlap);
+
+  const fitsLeft = nestedWidth <= spaceOnLeft;
+  const fitsRight = nestedWidth <= spaceOnRight;
+
+  if (parentPrefersLeft) {
+    if (fitsLeft) {
+      return { openLeft: true };
+    }
+
+    if (fitsRight) {
+      return { openLeft: false };
+    }
+  } else {
+    if (fitsRight) {
+      return { openLeft: false };
+    }
+
+    if (fitsLeft) {
+      return { openLeft: true };
+    }
+  }
+
+  // Neither side fits — pick the side with more space. Break ties by
+  // keeping the default (right) side so the nested popover stays anchored
+  // next to the trigger rather than flipping for no visible benefit.
+  return { openLeft: spaceOnLeft > spaceOnRight };
+}
+
+/**
+ * Input for clamping the nested popover's vertical position.
+ * All coordinates are in viewport space.
+ */
+export interface ClampNestedPopoverTopInput {
+  /** Desired top (viewport-relative) before any clamping — usually centered on the trigger item. */
+  desiredTop: number;
+  /** Measured nested popover height. */
+  nestedHeight: number;
+  /** Current viewport height (window.innerHeight). */
+  viewportHeight: number;
+  /** Minimum gap from the viewport's top/bottom edges. Defaults to 8. */
+  margin?: number;
+}
+
+export interface ClampNestedPopoverTopOutput {
+  /** Clamped top (viewport-relative). */
+  top: number;
+}
+
+/**
+ * Clamps the nested popover's vertical position so it stays inside the
+ * viewport. When the popover is taller than the viewport minus margins,
+ * pins it to the top margin so at least its first items remain reachable.
+ *
+ * Horizontal flipping is handled separately by {@link resolveNestedPopoverSide}.
+ */
+export function clampNestedPopoverTop(input: ClampNestedPopoverTopInput): ClampNestedPopoverTopOutput {
+  const {
+    desiredTop,
+    nestedHeight,
+    viewportHeight,
+    margin = 8,
+  } = input;
+
+  const topFloor = margin;
+  const maxTop = viewportHeight - nestedHeight - margin;
+
+  if (maxTop < topFloor) {
+    return { top: topFloor };
+  }
+
+  return { top: Math.max(topFloor, Math.min(maxTop, desiredTop)) };
+}

package/src/components/utils/popover/popover-position.ts

@@ -17,6 +17,19 @@ export interface PositionInput {
   offset?: number;
   /** Element rect whose left edge overrides anchor's left for horizontal alignment */
   leftAlignRect?: DOMRect;
+  /**
+   * When true, the popover is placed to the left of the anchor (its right edge
+   * sits one offset-gap before the anchor's left edge) and is vertically centered
+   * against the anchor. Clamping to scope boundaries still applies.
+   */
+  placeLeftOfAnchor?: boolean;
+  /**
+   * Minimum distance (in pixels) between the popover and the viewport top/bottom
+   * edges. Applied only when placeLeftOfAnchor is true. Keeps the popover
+   * within the viewport — shifting up if centered placement would overflow the
+   * bottom — so it remains fully visible near the anchor. Has no effect when 0.
+   */
+  viewportMargin?: number;
 }
 
 export interface ResolvedPosition {
@@ -62,12 +75,44 @@ export function resolvePosition(input: PositionInput): ResolvedPosition {
     scrollOffset,
     offset = 8,
     leftAlignRect,
+    placeLeftOfAnchor = false,
+    viewportMargin = 0,
   } = input;
 
-  // --- Vertical ---
   const boundaryBottom = Math.min(viewportSize.height, scopeBounds.bottom);
   const boundaryTop = Math.max(0, scopeBounds.top);
+  const boundaryRight = Math.min(viewportSize.width, scopeBounds.right);
+  const boundaryLeft = Math.max(0, scopeBounds.left);
+  const scopeTopInDocCoords = scopeBounds.top + scrollOffset.y;
+
+  // Placement mode: left of anchor, vertically centered.
+  if (placeLeftOfAnchor) {
+    const anchorCenterY = (anchor.top + anchor.bottom) / 2 + scrollOffset.y;
+    const anchorTopInDocCoords = anchor.top + scrollOffset.y;
+    const rawTop = anchorCenterY - popoverSize.height / 2;
+    const scopeBottomInDocCoords = scopeBounds.bottom + scrollOffset.y;
+    const viewportTopFloor = scrollOffset.y + viewportMargin;
+    const viewportBottomCeiling = scrollOffset.y + viewportSize.height - viewportMargin;
+
+    // Popover top must never sit below the anchor top — keeps the menu visually
+    // attached to the trigger instead of dropping underneath it when the viewport
+    // margin would otherwise force the top edge down.
+    const topFloor = Math.max(scopeTopInDocCoords, Math.min(viewportTopFloor, anchorTopInDocCoords));
+    const bottomCeiling = Math.min(scopeBottomInDocCoords, viewportBottomCeiling);
+    const maxTop = bottomCeiling - popoverSize.height;
+    const anchorCeiling = Math.max(topFloor, anchorTopInDocCoords);
+    const constrainedTop = Math.min(anchorCeiling, Math.max(topFloor, rawTop));
+    const top = maxTop < topFloor
+      ? topFloor
+      : Math.min(maxTop, constrainedTop);
+
+    const rawLeft = anchor.left - offset - popoverSize.width + scrollOffset.x;
+    const left = Math.max(boundaryLeft + scrollOffset.x, rawLeft);
+
+    return { top, left, openTop: false, openLeft: true };
+  }
 
+  // --- Vertical ---
   const spaceBelow = boundaryBottom - anchor.bottom - offset;
   const spaceAbove = anchor.top - offset - boundaryTop;
 
@@ -82,15 +127,11 @@ export function resolvePosition(input: PositionInput): ResolvedPosition {
   // than the viewport-clamped boundaryTop, so the clamp is correct when the page is
   // scrolled (boundaryTop is viewport-relative; adding scrollOffset converts it to
   // document coords but discards any negative scope top that was clamped to 0).
-  const scopeTopInDocCoords = scopeBounds.top + scrollOffset.y;
   const top = rawTop < scopeTopInDocCoords
     ? scopeTopInDocCoords
     : rawTop;
 
   // --- Horizontal ---
-  const boundaryRight = Math.min(viewportSize.width, scopeBounds.right);
-  const boundaryLeft = Math.max(0, scopeBounds.left);
-
   const alignLeft = (leftAlignRect?.left ?? anchor.left) + scrollOffset.x;
   const alignRight = anchor.right + scrollOffset.x;
 

package/src/components/utils/popover/popover.const.ts

@@ -5,19 +5,19 @@
  */
 export const css = {
   // Popover container - base styles
-  popoverContainer: 'absolute flex flex-col overflow-hidden box-border opacity-0 pointer-events-none p-0 border-none z-4 max-h-0 min-w-(--width) w-(--width) rounded-xl text-sm left-(--popover-left) top-(--popover-top) bg-popover-bg',
+  popoverContainer: 'absolute flex flex-col overflow-hidden box-border opacity-0 pointer-events-none p-0 border-none z-[var(--blok-z-popover)] max-h-0 min-w-(--width) w-(--width) rounded-xl text-sm left-(--popover-left) top-(--popover-top) bg-popover-bg',
 
   // Popover container - mobile styles (applied conditionally)
   // Reset left/top from base class since inset shorthand may not properly override them in twMerge
   popoverContainerMobile: 'fixed max-w-none rounded-[10px] min-w-[calc(100%-var(--offset)*2)] left-auto top-auto inset-[auto_var(--offset)_calc(var(--offset)+env(safe-area-inset-bottom))_var(--offset)]',
 
   // Popover container - opened state
-  popoverContainerOpened: 'opacity-100 pointer-events-auto p-1.5 max-h-(--max-height) border-none',
+  popoverContainerOpened: 'opacity-100 pointer-events-auto px-1.5 pt-1.5 pb-0 max-h-(--max-height) border-none',
 
   // Popover overlay
   popoverOverlay: 'hidden bg-dark',
 
-  items: 'overflow-y-auto overscroll-contain',
+  items: 'flex-1 min-h-0 overflow-y-auto overscroll-contain pb-1.5',
 
   scrollHaze: 'absolute inset-x-0 h-6 pointer-events-none z-1 transition-opacity duration-300 ease-in-out',
 };
@@ -32,6 +32,9 @@ export const cssInline = {
 
   // Container for inline popover
   popoverContainer: 'flex-row top-0 min-w-max w-max p-1 mobile:absolute',
+
+  // Opened state for inline popover - symmetric padding (no scroll area, so pb matches pt)
+  popoverContainerOpened: 'pb-1.5',
 };
 
 /**

package/src/components/utils/tooltip.ts

@@ -1,5 +1,9 @@
 import { DATA_ATTR, TOOLTIP_INTERFACE_VALUE } from '../constants';
 
+import {
+  promoteToTopLayer,
+  removeFromTopLayer,
+} from './top-layer';
 import { twJoin } from './tw';
 
 /**
@@ -70,11 +74,20 @@ class Tooltip {
   private get CSS(): CSSTooltipClasses {
     return {
       tooltip: twJoin(
-        'absolute z-overlay top-0 left-0',
+        /**
+         * `fixed` (not `absolute`) anchors the wrapper to the viewport. That
+         * matters because placement math feeds in viewport-relative coords
+         * (from `getBoundingClientRect()`, with no scroll offset added), and
+         * the CSS Top Layer does NOT give `position: absolute` a viewport
+         * containing block — Chrome keeps the initial containing block
+         * (document), so a scrolled page would push the tooltip up by
+         * `scrollY`. `fixed` side-steps that entirely, both before and after
+         * the wrapper is promoted to the Top Layer.
+         */
+        'fixed z-overlay top-0 left-0',
         'bg-tooltip-bg opacity-0',
         'select-none pointer-events-none',
         'rounded-lg shadow-tooltip',
-        'before:content-[\'\'] before:absolute before:inset-0 before:bg-tooltip-bg before:-z-10 before:rounded-lg',
         'mobile:hidden'
       ).split(' '),
       tooltipContent: twJoin(
@@ -237,10 +250,24 @@ class Tooltip {
 
       this.nodes.wrapper.classList.add(...classes);
       this.updateTooltipVisibility();
+      this.promoteToTopLayer();
     }
     this.showed = true;
   }
 
+  /**
+   * Promote the tooltip wrapper to the CSS Top Layer via the centralized
+   * helper. Necessary so the tooltip renders above any open popover —
+   * popovers themselves use the Top Layer, and no z-index can beat that.
+   */
+  private promoteToTopLayer(): void {
+    if (this.nodes.wrapper === null) {
+      return;
+    }
+
+    promoteToTopLayer(this.nodes.wrapper);
+  }
+
   /**
    * Prepare tooltip content node
    * @param {TooltipContent} content - tooltip content (Node or string)
@@ -276,10 +303,24 @@ class Tooltip {
 
       this.nodes.wrapper.classList.remove(...classes);
       this.updateTooltipVisibility();
+      this.removeFromTopLayer();
     }
     this.showed = false;
   }
 
+  /**
+   * Reverse of {@link promoteToTopLayer}. Delegates to the centralized helper
+   * which hides the popover, clears the `popover` attribute, and removes the
+   * top-layer marker so the wrapper returns to ordinary layout.
+   */
+  private removeFromTopLayer(): void {
+    if (this.nodes.wrapper === null) {
+      return;
+    }
+
+    removeFromTopLayer(this.nodes.wrapper);
+  }
+
   /**
    * Mouseover/Mouseleave decorator
    * @param {HTMLElement} element - target element to place Tooltip near that
@@ -501,14 +542,17 @@ class Tooltip {
   }
 
   /**
-   * Get current page vertical scroll offset
+   * Scroll offset to add to placement math.
+   *
+   * Always 0. The wrapper is `position: fixed`, so its containing block is
+   * the viewport regardless of Top-Layer promotion — and
+   * `getBoundingClientRect()` is already viewport-relative. Adding `scrollY`
+   * would double-count the offset and push the tooltip off-screen on any
+   * scrolled page. Kept as a method (not inlined) so future placements have
+   * a single chokepoint to revisit if the positioning model ever changes.
    */
   private getScrollTop(): number {
-    if (typeof window.scrollY === 'number') {
-      return window.scrollY;
-    }
-
-    return document.documentElement?.scrollTop ?? document.body.scrollTop ?? 0;
+    return 0;
   }
 
   /**

package/src/components/utils/top-layer.ts

@@ -0,0 +1,137 @@
+/**
+ * Centralized helper for promoting blok-owned elements into the browser's
+ * CSS Top Layer via the HTML Popover API.
+ *
+ * Why this module exists
+ * ----------------------
+ * The CSS Top Layer (entered via `popover="manual"` + `showPopover()`) escapes
+ * every ancestor stacking context. It's the only reliable way to render blok
+ * UI above arbitrary host-page content. But it comes with a UA stylesheet
+ * that styles the `[popover]` attribute as a modal dialog:
+ *
+ *   - `position: fixed; inset: 0; margin: auto` → pins the element to the
+ *     bottom-right corner of the viewport, ignoring any inline top/left.
+ *   - `width: fit-content; height: max-content; max-width: 100vw;
+ *     max-height: 100vh` → resizes the element.
+ *   - `border: solid; padding: 0.25em` → adds visual chrome.
+ *   - `background: Canvas` → paints a Canvas-color background underneath
+ *     transparent areas of the element.
+ *
+ * Every blok floating-UI element promoted to the Top Layer must override
+ * those defaults. Doing it per-element invites the bug where a new element
+ * is added, the dev forgets the CSS reset, and the element renders in the
+ * bottom-right corner of the viewport with a Canvas background.
+ *
+ * The chokepoint
+ * --------------
+ * `promoteToTopLayer` is the single sanctioned entry point. It tags the
+ * element with `data-blok-top-layer="true"` so a single CSS rule in
+ * `src/styles/main.css` can neutralize the UA defaults for every current and
+ * future caller. An architectural test
+ * (`test/unit/architecture/no-raw-popover-api.test.ts`) fails the build if
+ * any source file outside this module touches the Popover API directly.
+ */
+
+const POPOVER_ATTR = 'popover';
+const POPOVER_VALUE_MANUAL = 'manual';
+
+/**
+ * Marker attribute applied to every Top-Layer-promoted blok element. The
+ * `[data-blok-top-layer][popover]` CSS rule in `src/styles/main.css` keys off
+ * this attribute to neutralize UA `[popover]` defaults. Renaming this constant
+ * requires a coordinated update to that rule (and its coverage test in
+ * `test/unit/styles/top-layer-css.test.ts`).
+ */
+export const TOP_LAYER_MARKER_ATTR = 'data-blok-top-layer';
+
+/**
+ * Feature-detects the native HTML Popover API. Older Safari (<17) and older
+ * Firefox (<125) lack it; helper calls become safe no-ops on those platforms.
+ */
+export const supportsPopoverAPI = (): boolean => {
+  return typeof HTMLElement !== 'undefined' && 'popover' in HTMLElement.prototype;
+};
+
+/**
+ * Promote `el` into the CSS Top Layer.
+ *
+ * Sets `popover="manual"` (so the UA hands show/hide control to script),
+ * tags the element with `data-blok-top-layer="true"` (so the CSS reset
+ * applies), and calls `showPopover()`.
+ *
+ * @returns `true` if the element entered the Top Layer, `false` if the API
+ * is unsupported or the call was rejected (already open, etc.). Callers that
+ * need to fall back to z-index stacking can branch on the return value.
+ */
+export const promoteToTopLayer = (el: HTMLElement): boolean => {
+  if (!supportsPopoverAPI()) {
+    return false;
+  }
+
+  if (!el.hasAttribute(POPOVER_ATTR)) {
+    el.setAttribute(POPOVER_ATTR, POPOVER_VALUE_MANUAL);
+  }
+  el.setAttribute(TOP_LAYER_MARKER_ATTR, 'true');
+
+  try {
+    el.showPopover();
+
+    return true;
+  } catch {
+    /**
+     * Most common reason: the element is already in the Top Layer (double
+     * `show()` from racing event handlers). Caller can ignore.
+     */
+    return false;
+  }
+};
+
+/**
+ * Reverse of {@link promoteToTopLayer}. Hides the popover, removes the
+ * `popover` attribute (so the UA `[popover]:not(:popover-open)` display:none
+ * rule no longer applies) and clears the `data-blok-top-layer` marker.
+ */
+export const removeFromTopLayer = (el: HTMLElement): void => {
+  if (!supportsPopoverAPI()) {
+    return;
+  }
+
+  if (el.hasAttribute(POPOVER_ATTR)) {
+    try {
+      el.hidePopover();
+    } catch {
+      /**
+       * Element wasn't open (already hidden, never promoted). Still need to
+       * strip the attribute below.
+       */
+    }
+    el.removeAttribute(POPOVER_ATTR);
+  }
+
+  el.removeAttribute(TOP_LAYER_MARKER_ATTR);
+};
+
+/**
+ * @returns `true` if the element is currently tagged as Top-Layer-promoted by
+ * this helper. Used by positioning math that needs to know whether the
+ * containing block is the viewport (Top Layer) or the document (regular flow).
+ */
+export const isPromotedToTopLayer = (el: HTMLElement): boolean => {
+  return el.hasAttribute(TOP_LAYER_MARKER_ATTR);
+};
+
+/**
+ * Strip the `popover` attribute from an element WITHOUT calling hidePopover().
+ *
+ * Reserved for off-DOM measurement clones: the popover wrapper is cloned to
+ * measure its dimensions, but UA `[popover]:not(:popover-open) { display:none }`
+ * would zero out the clone's box. Removing the attribute restores layout for
+ * the measurement, after which the clone is detached and discarded.
+ *
+ * Using this helper (rather than calling `removeAttribute('popover')` inline)
+ * keeps the architectural rule "all popover-attribute manipulation lives in
+ * this module" intact, so reviewers and future devs see the single chokepoint.
+ */
+export const stripPopoverAttribute = (el: HTMLElement): void => {
+  el.removeAttribute(POPOVER_ATTR);
+};

package/src/playground/block-states-gallery.ts

@@ -0,0 +1,123 @@
+import type { OutputBlockData } from '@/types/data-formats/output-data';
+
+export interface BlockStatesSpec {
+  tool: string;
+  label: string;
+  blocks: OutputBlockData[];
+}
+
+export interface RenderBlockArgs {
+  container: HTMLElement;
+  blocks: OutputBlockData[];
+}
+
+export interface RenderBlockStatesGalleryOptions {
+  container: HTMLElement;
+  spec: BlockStatesSpec[];
+  renderBlock: (args: RenderBlockArgs) => void;
+  activeTool?: string;
+  onTabChange?: (tool: string) => void;
+}
+
+export interface BlockStatesGalleryHandle {
+  setActiveTool: (tool: string) => void;
+}
+
+function createTab(label: string, tool: string, isActive: boolean): HTMLButtonElement {
+  const tab = document.createElement('button');
+
+  tab.type = 'button';
+  tab.className = 'block-states-tab';
+  tab.setAttribute('data-tool', tool);
+  tab.setAttribute('role', 'tab');
+  tab.setAttribute('aria-selected', isActive ? 'true' : 'false');
+  tab.textContent = label;
+
+  return tab;
+}
+
+function createPanel(spec: BlockStatesSpec, isActive: boolean, renderBlock: (args: RenderBlockArgs) => void): HTMLElement {
+  const panel = document.createElement('div');
+
+  panel.className = 'block-states-panel';
+  panel.setAttribute('role', 'tabpanel');
+  panel.setAttribute('data-tool', spec.tool);
+
+  if (!isActive) {
+    panel.classList.add('hidden');
+  }
+
+  const preview = document.createElement('div');
+
+  preview.className = 'block-states-preview';
+
+  panel.appendChild(preview);
+
+  renderBlock({ container: preview, blocks: spec.blocks });
+
+  return panel;
+}
+
+export function renderBlockStatesGallery({
+  container,
+  spec,
+  renderBlock,
+  activeTool,
+  onTabChange,
+}: RenderBlockStatesGalleryOptions): BlockStatesGalleryHandle {
+  const tabBar = document.createElement('div');
+
+  tabBar.className = 'block-states-tabs';
+  tabBar.setAttribute('role', 'tablist');
+
+  const panelsWrap = document.createElement('div');
+
+  panelsWrap.className = 'block-states-panels';
+
+  const requestedIndex = activeTool ? spec.findIndex((entry) => entry.tool === activeTool) : -1;
+  const initialIndex = requestedIndex >= 0 ? requestedIndex : 0;
+
+  const entries = spec.map((entry, index) => {
+    const isActive = index === initialIndex;
+
+    return {
+      tool: entry.tool,
+      tab: createTab(entry.label, entry.tool, isActive),
+      panel: createPanel(entry, isActive, renderBlock),
+    };
+  });
+
+  entries.forEach(({ tab, panel }) => {
+    tabBar.appendChild(tab);
+    panelsWrap.appendChild(panel);
+  });
+
+  const selectIndex = (activeIndex: number): void => {
+    entries.forEach(({ tab: t, panel: p }, otherIndex) => {
+      const isTarget = otherIndex === activeIndex;
+
+      t.setAttribute('aria-selected', isTarget ? 'true' : 'false');
+      p.classList.toggle('hidden', !isTarget);
+    });
+  };
+
+  entries.forEach(({ tab, tool }, activeIndex) => {
+    tab.addEventListener('click', () => {
+      selectIndex(activeIndex);
+      onTabChange?.(tool);
+    });
+  });
+
+  container.appendChild(tabBar);
+  container.appendChild(panelsWrap);
+
+  return {
+    setActiveTool(tool: string) {
+      const targetIndex = entries.findIndex((e) => e.tool === tool);
+
+      if (targetIndex >= 0) {
+        selectIndex(targetIndex);
+      }
+    },
+  };
+}