@unofficialbox/box-open-elements 0.3.0 → 0.4.0

package/dist/components/overlays/guide-tooltip.d.ts

@@ -0,0 +1,51 @@
+import { BaseElement } from "../../core/index.js";
+/**
+ * A guided-tour callout that points at a target element and walks a user through
+ * a sequence of steps. Anchor it with `for` (the id of a target) or a slotted
+ * `anchor` element; it self-anchors to the host otherwise. It renders a
+ * `heading`, a body (default slot), a `step`/`total` indicator, and Back/Next/
+ * Close controls, emitting `next`, `back`, and `close` (each with `detail.step`)
+ * so the host can advance the tour (moving `for`/`step`). Positioned as a
+ * viewport-fixed overlay via `foundations/overlay`.
+ */
+export declare class BoxGuideTooltipElement extends BaseElement {
+    static get observedAttributes(): string[];
+    private openValue;
+    private positionCleanup;
+    private headingId;
+    private calloutEl;
+    private closeEl;
+    private headingEl;
+    private stepEl;
+    private backEl;
+    private nextEl;
+    private anchorSlot;
+    get open(): boolean;
+    set open(value: boolean);
+    get heading(): string;
+    set heading(value: string);
+    get placement(): string;
+    set placement(value: string);
+    private resolvedPlacement;
+    /** 1-based current step; paired with `total` for the "n of m" indicator. */
+    get step(): number;
+    set step(value: number);
+    get total(): number;
+    set total(value: number);
+    get htmlFor(): string;
+    set htmlFor(value: string);
+    private get nextLabel();
+    private get backLabel();
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    show(): void;
+    hide(): void;
+    /** Resolve the element the callout points at. */
+    private resolveAnchor;
+    private stopTracking;
+    disconnectedCallback(): void;
+    protected renderTemplate(): void;
+    private emit;
+    protected setupListeners(): void;
+    protected update(): void;
+}
+export declare const defineBoxGuideTooltipElement: (tagName?: string) => typeof BoxGuideTooltipElement;

package/dist/components/overlays/guide-tooltip.js

@@ -0,0 +1,361 @@
+import { BaseElement } from "../../core/index.js";
+import { boeControl, boeOverlay, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
+import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
+import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+import { parsePlacement, trackAnchor, } from "../../foundations/overlay/index.js";
+const DEFAULT_TAG_NAME = "box-guide-tooltip";
+const guideTooltipStyles = `
+  :host {
+    display: contents;
+    color: inherit;
+    font: inherit;
+  }
+
+  /* Positioned by JS (foundations/overlay) as a viewport-fixed callout, so it
+     escapes ancestor overflow and flips/shifts to stay on-screen. */
+  [part="callout"] {
+    position: fixed;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    z-index: 60;
+    inline-size: max-content;
+    max-inline-size: min(20rem, calc(100vw - 2rem));
+    padding: ${boeSpace[4]};
+    border-radius: ${boeOverlay.radius};
+    border: 1px solid color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 24%, transparent);
+    background: var(--boe-token-surface-tooltip-surface, #4e4e4e);
+    color: rgba(255, 255, 255, 0.95);
+    box-shadow: 0 18px 40px rgba(16, 24, 32, 0.28);
+    line-height: 1.5;
+  }
+
+  [part="callout"][hidden] {
+    display: none;
+  }
+
+  [part="close"] {
+    position: absolute;
+    inset-block-start: ${boeSpace[2]};
+    inset-inline-end: ${boeSpace[2]};
+    inline-size: 1.5rem;
+    block-size: 1.5rem;
+    display: inline-grid;
+    place-items: center;
+    padding: 0;
+    border: 0;
+    border-radius: ${boeRadius.med};
+    background: transparent;
+    color: rgba(255, 255, 255, 0.8);
+    font: inherit;
+    font-size: 1rem;
+    line-height: 1;
+    cursor: pointer;
+    transition: background ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
+  }
+
+  [part="close"]:hover {
+    background: rgba(255, 255, 255, 0.14);
+    color: #ffffff;
+  }
+
+  [part="close"]:focus-visible {
+    outline: 2px solid #ffffff;
+    outline-offset: 1px;
+  }
+
+  [part="heading"] {
+    margin: 0 1.5rem 0.35rem 0;
+    font-size: 0.95rem;
+    font-weight: 700;
+  }
+
+  [part="heading"][hidden] {
+    display: none;
+  }
+
+  [part="body"] {
+    font-size: 0.86rem;
+  }
+
+  [part="footer"] {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: ${boeSpace[3]};
+    margin-block-start: ${boeSpace[4]};
+  }
+
+  [part="step"] {
+    font-size: 0.76rem;
+    color: rgba(255, 255, 255, 0.7);
+  }
+
+  [part="step"][hidden] {
+    display: none;
+  }
+
+  [part="actions"] {
+    display: inline-flex;
+    gap: ${boeSpace[2]};
+    margin-inline-start: auto;
+  }
+
+  [part="back"],
+  [part="next"] {
+    appearance: none;
+    min-height: 1.9rem;
+    padding: 0 ${boeSpace[3]};
+    border-radius: ${boeRadius.control};
+    font: inherit;
+    font-size: 0.82rem;
+    font-weight: 700;
+    letter-spacing: ${boeControl.letterSpacing};
+    cursor: pointer;
+    transition: background ${boeMotionDuration.interactive} ${boeMotionEasing.standard}, border-color ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
+  }
+
+  [part="back"] {
+    border: 1px solid rgba(255, 255, 255, 0.4);
+    background: transparent;
+    color: rgba(255, 255, 255, 0.92);
+  }
+
+  [part="back"]:hover:not(:disabled) {
+    border-color: #ffffff;
+  }
+
+  [part="back"][hidden] {
+    display: none;
+  }
+
+  [part="next"] {
+    border: 1px solid transparent;
+    background: var(--boe-token-surface-surface-brand, #0061d5);
+    color: var(--boe-token-text-text-on-brand, #ffffff);
+  }
+
+  [part="next"]:hover:not(:disabled) {
+    background: var(--boe-token-surface-surface-brand-hover, #006ae9);
+  }
+
+  [part="back"]:disabled,
+  [part="next"]:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  ${boeNeutralInteractiveStyles('[part="close"]')}
+`;
+/**
+ * A guided-tour callout that points at a target element and walks a user through
+ * a sequence of steps. Anchor it with `for` (the id of a target) or a slotted
+ * `anchor` element; it self-anchors to the host otherwise. It renders a
+ * `heading`, a body (default slot), a `step`/`total` indicator, and Back/Next/
+ * Close controls, emitting `next`, `back`, and `close` (each with `detail.step`)
+ * so the host can advance the tour (moving `for`/`step`). Positioned as a
+ * viewport-fixed overlay via `foundations/overlay`.
+ */
+export class BoxGuideTooltipElement extends BaseElement {
+    static get observedAttributes() {
+        return [
+            "open",
+            "heading",
+            "placement",
+            "step",
+            "total",
+            "for",
+            "next-label",
+            "back-label",
+            "close-label",
+        ];
+    }
+    openValue = false;
+    positionCleanup = null;
+    headingId = `box-guide-heading-${Math.random().toString(36).slice(2, 10)}`;
+    calloutEl;
+    closeEl;
+    headingEl;
+    stepEl;
+    backEl;
+    nextEl;
+    anchorSlot;
+    get open() {
+        return this.openValue;
+    }
+    set open(value) {
+        const next = Boolean(value);
+        if (this.openValue === next) {
+            return;
+        }
+        this.openValue = next;
+        this.toggleAttribute("open", next);
+        this.dispatchEvent(new CustomEvent("open-changed", { bubbles: true, composed: true, detail: { open: next } }));
+        if (this.isRendered) {
+            this.update();
+        }
+    }
+    get heading() {
+        return this.getAttribute("heading") ?? "";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    get placement() {
+        return this.getAttribute("placement") ?? "bottom-center";
+    }
+    set placement(value) {
+        this.setAttribute("placement", value);
+    }
+    resolvedPlacement() {
+        return parsePlacement(this.getAttribute("placement")) ?? { side: "bottom", align: "center" };
+    }
+    /** 1-based current step; paired with `total` for the "n of m" indicator. */
+    get step() {
+        const raw = Number(this.getAttribute("step"));
+        return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 0;
+    }
+    set step(value) {
+        this.setAttribute("step", String(value));
+    }
+    get total() {
+        const raw = Number(this.getAttribute("total"));
+        return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 0;
+    }
+    set total(value) {
+        this.setAttribute("total", String(value));
+    }
+    get htmlFor() {
+        return this.getAttribute("for") ?? "";
+    }
+    set htmlFor(value) {
+        this.setAttribute("for", value);
+    }
+    get nextLabel() {
+        const explicit = this.getAttribute("next-label");
+        if (explicit) {
+            return explicit;
+        }
+        // On the final step Next becomes a finish action.
+        return this.total > 0 && this.step >= this.total ? "Done" : "Next";
+    }
+    get backLabel() {
+        return this.getAttribute("back-label") ?? "Back";
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (name === "open") {
+            this.openValue = this.hasAttribute("open");
+        }
+        super.attributeChangedCallback(name, oldValue, newValue);
+    }
+    show() {
+        this.open = true;
+    }
+    hide() {
+        this.open = false;
+    }
+    /** Resolve the element the callout points at. */
+    resolveAnchor() {
+        const forId = this.htmlFor;
+        if (forId) {
+            const root = this.getRootNode();
+            const found = root.getElementById?.(forId) ??
+                (this.ownerDocument ?? document).getElementById(forId);
+            if (found) {
+                return found;
+            }
+        }
+        const slotted = this.anchorSlot?.assignedElements({ flatten: true })[0];
+        return slotted ?? this;
+    }
+    stopTracking() {
+        this.positionCleanup?.();
+        this.positionCleanup = null;
+    }
+    disconnectedCallback() {
+        this.stopTracking();
+        super.disconnectedCallback?.();
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${guideTooltipStyles}</style>
+      <slot name="anchor"></slot>
+      <div part="callout" role="dialog" aria-labelledby="${this.headingId}" hidden>
+        <button type="button" part="close" aria-label="Close">
+          <svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M4 4l8 8M12 4l-8 8" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>
+        </button>
+        <h2 part="heading" id="${this.headingId}" hidden></h2>
+        <div part="body"><slot></slot></div>
+        <div part="footer">
+          <span part="step" hidden></span>
+          <div part="actions">
+            <button type="button" part="back">Back</button>
+            <button type="button" part="next">Next</button>
+          </div>
+        </div>
+      </div>
+    `;
+        this.calloutEl = this.shadowRoot.querySelector('[part="callout"]');
+        this.closeEl = this.shadowRoot.querySelector('[part="close"]');
+        this.headingEl = this.shadowRoot.querySelector('[part="heading"]');
+        this.stepEl = this.shadowRoot.querySelector('[part="step"]');
+        this.backEl = this.shadowRoot.querySelector('[part="back"]');
+        this.nextEl = this.shadowRoot.querySelector('[part="next"]');
+        this.anchorSlot = this.shadowRoot.querySelector('slot[name="anchor"]');
+    }
+    emit(type) {
+        this.dispatchEvent(new CustomEvent(type, { bubbles: true, composed: true, detail: { step: this.step } }));
+    }
+    setupListeners() {
+        this.closeEl.addEventListener("click", () => {
+            this.emit("close");
+            this.hide();
+        });
+        this.backEl.addEventListener("click", () => this.emit("back"));
+        this.nextEl.addEventListener("click", () => this.emit("next"));
+        this.calloutEl.addEventListener("keydown", event => {
+            if (event.key === "Escape") {
+                event.preventDefault();
+                this.emit("close");
+                this.hide();
+            }
+        });
+    }
+    update() {
+        if (!this.calloutEl) {
+            return;
+        }
+        this.calloutEl.hidden = !this.openValue;
+        const heading = this.heading;
+        this.headingEl.hidden = !heading;
+        this.headingEl.textContent = heading;
+        const step = this.step;
+        const total = this.total;
+        const showStep = step > 0 && total > 0;
+        this.stepEl.hidden = !showStep;
+        this.stepEl.textContent = showStep ? `${step} of ${total}` : "";
+        // Back hides on the first step; Next label finishes on the last.
+        this.backEl.hidden = showStep && step <= 1;
+        this.backEl.textContent = this.backLabel;
+        this.nextEl.textContent = this.nextLabel;
+        this.stopTracking();
+        if (this.openValue) {
+            this.positionCleanup = trackAnchor(this.resolveAnchor(), this.calloutEl, {
+                placement: this.resolvedPlacement(),
+                offset: 10,
+            });
+            // Move focus into the callout for keyboard users.
+            queueMicrotask(() => this.nextEl?.focus());
+        }
+    }
+}
+export const defineBoxGuideTooltipElement = (tagName = DEFAULT_TAG_NAME) => {
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxGuideTooltipElement);
+    return BoxGuideTooltipElement;
+};

package/dist/components/overlays/tooltip.d.ts

@@ -1,17 +1,25 @@
 import { BaseElement } from "../../core/index.js";
+export type TooltipTheme = "default" | "error" | "callout";
 export declare class BoxTooltipElement extends BaseElement {
     static get observedAttributes(): string[];
+    private positionCleanup;
     private openValue;
     private tooltipId;
     private triggerHostEl;
     private triggerSlot;
     private fallbackTriggerEl;
     private tooltipEl;
+    private labelEl;
     private describedTrigger;
     get label(): string;
     set label(value: string);
     get triggerLabel(): string;
     set triggerLabel(value: string);
+    get placement(): string;
+    set placement(value: string);
+    private resolvedPlacement;
+    get theme(): TooltipTheme;
+    set theme(value: TooltipTheme);
     get open(): boolean;
     set open(value: boolean);
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
@@ -22,5 +30,7 @@ export declare class BoxTooltipElement extends BaseElement {
     protected renderTemplate(): void;
     protected setupListeners(): void;
     protected update(): void;
+    private stopTracking;
+    disconnectedCallback(): void;
 }
 export declare const defineBoxTooltipElement: (tagName?: string) => typeof BoxTooltipElement;

package/dist/components/overlays/tooltip.js

@@ -1,6 +1,7 @@
 import { BaseElement } from "../../core/index.js";
 import { boeRadius } from "../../foundations/geometry/index.js";
 import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
+import { parsePlacement, trackAnchor, } from "../../foundations/overlay/index.js";
 const DEFAULT_TAG_NAME = "box-tooltip";
 const DEFAULT_TRIGGER_LABEL = "More information";
 const tooltipStyles = `
@@ -37,13 +38,15 @@ const tooltipStyles = `
 
   ${boeNeutralInteractiveStyles('[part="trigger"]')}
 
+  /* Positioned by JS (foundations/overlay) as position: fixed, so it escapes
+     ancestor overflow and flips/shifts to stay in the viewport. */
   [part="tooltip"] {
-    position: absolute;
-    inset-block-start: calc(100% + 0.5rem);
-    inset-inline-start: 50%;
-    transform: translateX(-50%);
-    z-index: 1;
-    width: min(13.75rem, calc(100vw - 6rem));
+    position: fixed;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    z-index: 40;
+    width: max-content;
+    max-width: min(18rem, calc(100vw - 2rem));
     padding: 0.5rem 0.65rem;
     border-radius: ${boeRadius.xlarge};
     border: 1px solid color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, rgba(255, 255, 255, 0.08));
@@ -53,20 +56,42 @@ const tooltipStyles = `
     line-height: 1.45;
   }
 
+  /* Error theme — for validation hints. */
+  [part="tooltip"][data-theme="error"] {
+    background: var(--boe-token-surface-status-surface-error, #ed3757);
+    border-color: var(--boe-token-surface-status-surface-error, #ed3757);
+    color: #ffffff;
+  }
+
+  /* Callout theme — light surface for richer, longer content. */
+  [part="tooltip"][data-theme="callout"] {
+    background: var(--boe-token-surface-surface, #ffffff);
+    border-color: var(--boe-token-stroke-stroke, #e8e8e8);
+    color: var(--boe-token-text-text, #222222);
+  }
+
+  [part="tooltip"] ::slotted(img) {
+    max-width: 100%;
+    border-radius: ${boeRadius.med};
+    display: block;
+  }
+
   [part="tooltip"][hidden] {
     display: none;
   }
 `;
 export class BoxTooltipElement extends BaseElement {
     static get observedAttributes() {
-        return ["label", "open", "trigger-label"];
+        return ["label", "open", "trigger-label", "placement", "theme"];
     }
+    positionCleanup = null;
     openValue = false;
     tooltipId = `box-tooltip-${Math.random().toString(36).slice(2, 10)}`;
     triggerHostEl;
     triggerSlot;
     fallbackTriggerEl;
     tooltipEl;
+    labelEl;
     describedTrigger = null;
     get label() {
         return this.getAttribute("label") ?? "Helpful context";
@@ -80,6 +105,22 @@ export class BoxTooltipElement extends BaseElement {
     set triggerLabel(value) {
         this.setAttribute("trigger-label", value);
     }
+    get placement() {
+        return this.getAttribute("placement") ?? "bottom-center";
+    }
+    set placement(value) {
+        this.setAttribute("placement", value);
+    }
+    resolvedPlacement() {
+        return parsePlacement(this.getAttribute("placement")) ?? { side: "bottom", align: "center" };
+    }
+    get theme() {
+        const value = this.getAttribute("theme");
+        return value === "error" || value === "callout" ? value : "default";
+    }
+    set theme(value) {
+        this.setAttribute("theme", value);
+    }
     get open() {
         return this.openValue;
     }
@@ -138,13 +179,14 @@ export class BoxTooltipElement extends BaseElement {
         <span part="trigger-host">
           <slot><button type="button" part="trigger">?</button></slot>
         </span>
-        <div id="${this.tooltipId}" part="tooltip" role="tooltip" hidden></div>
+        <div id="${this.tooltipId}" part="tooltip" role="tooltip" hidden><span part="label"></span><slot name="content"></slot></div>
       </span>
     `;
         this.triggerHostEl = this.shadowRoot.querySelector('[part="trigger-host"]');
-        this.triggerSlot = this.shadowRoot.querySelector("slot");
+        this.triggerSlot = this.shadowRoot.querySelector("slot:not([name])");
         this.fallbackTriggerEl = this.shadowRoot.querySelector('[part="trigger"]');
         this.tooltipEl = this.shadowRoot.querySelector('[part="tooltip"]');
+        this.labelEl = this.shadowRoot.querySelector('[part="label"]');
     }
     setupListeners() {
         this.triggerHostEl.addEventListener("mouseenter", () => this.show());
@@ -180,19 +222,40 @@ export class BoxTooltipElement extends BaseElement {
         if (!this.triggerHostEl || !this.tooltipEl || !this.triggerSlot) {
             return;
         }
-        const label = this.label;
-        this.tooltipEl.textContent = label;
+        this.labelEl.textContent = this.label;
+        const theme = this.theme;
+        if (theme === "default") {
+            this.tooltipEl.removeAttribute("data-theme");
+        }
+        else {
+            this.tooltipEl.setAttribute("data-theme", theme);
+        }
         this.tooltipEl.hidden = !this.openValue;
         const trigger = this.resolveDescribedTrigger();
         if (trigger === this.fallbackTriggerEl) {
             this.fallbackTriggerEl.setAttribute("aria-label", this.triggerLabel);
         }
         this.clearDescribedBy();
+        this.stopTracking();
         if (this.openValue) {
             trigger.setAttribute("aria-describedby", this.tooltipId);
             this.describedTrigger = trigger;
+            // Position as a fixed-coordinate overlay so it escapes ancestor overflow
+            // and flips/shifts to stay on-screen.
+            this.positionCleanup = trackAnchor(this.triggerHostEl, this.tooltipEl, {
+                placement: this.resolvedPlacement(),
+                offset: 8,
+            });
         }
     }
+    stopTracking() {
+        this.positionCleanup?.();
+        this.positionCleanup = null;
+    }
+    disconnectedCallback() {
+        this.stopTracking();
+        super.disconnectedCallback?.();
+    }
 }
 export const defineBoxTooltipElement = (tagName = DEFAULT_TAG_NAME) => {
     const existingElement = customElements.get(tagName);

package/dist/foundations/overlay/positioning.js

@@ -146,7 +146,11 @@ export const trackAnchor = (anchor, floating, options = {}, onReposition) => {
     const reposition = () => {
         if (!anchor.isConnected || !floating.isConnected)
             return;
-        onReposition?.(anchorFloating(anchor, floating, options));
+        // Compute+apply the position first, then notify. Do NOT inline this into
+        // `onReposition?.(anchorFloating(...))`: optional-call short-circuits its
+        // argument when the callback is undefined, so anchorFloating would never run.
+        const result = anchorFloating(anchor, floating, options);
+        onReposition?.(result);
     };
     reposition();
     window.addEventListener("scroll", reposition, true);

package/dist/index.d.ts

@@ -80,6 +80,7 @@ export * from "./components/layout/split-view.js";
 export * from "./components/overlays/context-menu.js";
 export * from "./components/overlays/dialog.js";
 export * from "./components/overlays/drawer.js";
+export * from "./components/overlays/guide-tooltip.js";
 export * from "./components/overlays/popover.js";
 export * from "./components/overlays/tooltip.js";
 export * from "./patterns/content-explorer/index.js";

package/dist/index.js

@@ -89,6 +89,7 @@ export * from "./components/layout/split-view.js";
 export * from "./components/overlays/context-menu.js";
 export * from "./components/overlays/dialog.js";
 export * from "./components/overlays/drawer.js";
+export * from "./components/overlays/guide-tooltip.js";
 export * from "./components/overlays/popover.js";
 export * from "./components/overlays/tooltip.js";
 // Patterns: content explorer (headless blocks, contracts, transport, adapters)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-elements",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Box Open Elements: an open, framework-agnostic design system and web component library for Box-style experiences",
   "license": "MIT",
   "homepage": "https://unofficialbox.github.io/box-open-elements",