@taprootio/espalier 2.1.2 → 2.2.0

package/dist/flyout/esp-flyout.d.ts

@@ -0,0 +1,393 @@
+import { type PropertyValues } from "lit";
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+import type { FlyoutCloseReason } from "../shared/flyout-events.js";
+/**
+ * A transient panel for help, more-info, and preview content that
+ * claims designed spare width before ever covering the page.
+ *
+ * Place one `esp-flyout` in an `esp-page`'s `flyout` slot. The panel
+ * lives on the canvas, outside the content surface. The page decides
+ * where it goes, from widest viewport to narrowest:
+ *
+ * 1. **Gutter** — the panel occupies the right canvas gutter. When the
+ *    gutter already has room, it claims existing spare canvas and the
+ *    main content does not move at all, on any alignment.
+ * 2. **Shift** — when the gutter is not quite wide enough, the surface
+ *    slides toward `start` by exactly the shortfall (no more) to free
+ *    the difference.
+ * 3. **Docked sidebar** — once the gutter is gone, the panel competes
+ *    for width with the main well; content narrows but is never
+ *    covered.
+ * 4. **Overlay drawer** — below the mobile threshold (`50em`, the
+ *    same one the `esp-menu` drawer uses) the panel becomes a fixed
+ *    drawer over a vellum backdrop. Set `mode="overlay"` to get this
+ *    presentation at every width.
+ *
+ * The panel is styled as a tear-off piece: a dotted perforation on
+ * its leading edge, rounded trailing corners, and no shadow — all
+ * overridable through the `--esp-flyout-*` tokens below.
+ *
+ * A11y follows the presentation. In the in-grid modes (1–3) the
+ * flyout is a non-modal `complementary` landmark named by its
+ * `heading`, and opening it never steals focus. In the overlay-drawer
+ * mode (4) it is a true modal: `role="dialog"` + `aria-modal`, the
+ * background goes inert, scroll is locked, focus moves into the drawer
+ * and is trapped, and focus is restored on close. `Escape` closes it
+ * in every mode.
+ *
+ * ```html
+ * <style>
+ * esp-page.flyout-demo {
+ *   --esp-page-max-width: 420px;
+ *   --esp-page-canvas-background: var(--esp-color-layer-1);
+ *   &::part(wrapper) {
+ *     min-height: 320px;
+ *     height: 320px;
+ *   }
+ *   > div {
+ *     padding: var(--esp-size-padding);
+ *   }
+ * }
+ * </style>
+ * <esp-page class="flyout-demo" align="center">
+ *   <esp-flyout slot="flyout" heading="More info" id="demo-flyout" standalone>
+ *     <p>Spare width claimed; the well shifted only enough to make room.</p>
+ *   </esp-flyout>
+ *   <div>
+ *     <esp-button id="toggle-flyout" label="Toggle flyout" collapsed></esp-button>
+ *   </div>
+ * </esp-page>
+ * <script>
+ *   const flyout = findById("demo-flyout");
+ *   findById("toggle-flyout").addEventListener("clicked", () => flyout.toggle());
+ * </script>
+ * ```
+ *
+ * By default the panel is a tear-off — a dotted perforation on its
+ * leading edge, rounded trailing corners, no shadow. Add
+ * `match-surface` to lift the trailing edge with the page's surface
+ * edge shadow, so the flyout reads as a raised peer of the content it
+ * flies out from while staying attached at the leading perforation:
+ *
+ * ```html
+ * <style>
+ * esp-page.flyout-match-demo {
+ *   --esp-page-max-width: 420px;
+ *   &::part(wrapper) {
+ *     min-height: 320px;
+ *     height: 320px;
+ *   }
+ *   > div {
+ *     padding: var(--esp-size-padding);
+ *   }
+ * }
+ * </style>
+ * <esp-page class="flyout-match-demo" align="center">
+ *   <esp-flyout slot="flyout" heading="More info" id="match-flyout" match-surface standalone>
+ *     <p>Attached at the perforation, trailing edge raised like the surface.</p>
+ *   </esp-flyout>
+ *   <div>
+ *     <esp-button id="toggle-match" label="Toggle flyout" collapsed></esp-button>
+ *   </div>
+ * </esp-page>
+ * <script>
+ *   const matchFlyout = findById("match-flyout");
+ *   findById("toggle-match").addEventListener("clicked", () => matchFlyout.toggle());
+ * </script>
+ * ```
+ *
+ * When the page has no spare width to claim — a `kind="full"` page,
+ * or a capped page on a viewport at the cap — the open flyout docks
+ * as a right sidebar and the content makes room:
+ *
+ * ```html
+ * <style>
+ * esp-page.flyout-docked-demo {
+ *   &::part(wrapper) {
+ *     min-height: 320px;
+ *     height: 320px;
+ *   }
+ *   > div {
+ *     padding: var(--esp-size-padding);
+ *   }
+ * }
+ * </style>
+ * <esp-page class="flyout-docked-demo" kind="full">
+ *   <esp-flyout slot="flyout" heading="Docked" id="docked-flyout" standalone>
+ *     <p>No gutter to claim, so the content narrows instead.</p>
+ *   </esp-flyout>
+ *   <div>
+ *     <p>A <code>kind="full"</code> page has no canvas gutters at any
+ *     width — the flyout squeezes the main well and never covers it.</p>
+ *     <esp-button id="toggle-docked" label="Toggle flyout" collapsed></esp-button>
+ *   </div>
+ * </esp-page>
+ * <script>
+ *   const dockedFlyout = findById("docked-flyout");
+ *   findById("toggle-docked").addEventListener("clicked", () => dockedFlyout.toggle());
+ * </script>
+ * ```
+ *
+ * Below the `50em` viewport threshold every flyout becomes a fixed
+ * overlay drawer over a vellum — there is no room for a side-by-side
+ * split on a phone. `mode="overlay"` forces that presentation at any
+ * width (try it here; `Escape` or the vellum closes it):
+ *
+ * ```html
+ * <style>
+ * esp-page.flyout-overlay-demo {
+ *   &::part(wrapper) {
+ *     min-height: 160px;
+ *     height: 160px;
+ *   }
+ *   > div {
+ *     padding: var(--esp-size-padding);
+ *   }
+ * }
+ * </style>
+ * <esp-page class="flyout-overlay-demo">
+ *   <esp-flyout slot="flyout" heading="Overlay drawer" mode="overlay" id="overlay-flyout" standalone>
+ *     <p>A fixed drawer over a vellum — what every flyout becomes on
+ *     small viewports.</p>
+ *   </esp-flyout>
+ *   <div>
+ *     <esp-button id="open-overlay" label="Open overlay flyout" collapsed></esp-button>
+ *   </div>
+ * </esp-page>
+ * <script>
+ *   const overlayFlyout = findById("overlay-flyout");
+ *   findById("open-overlay").addEventListener("clicked", () => overlayFlyout.toggle());
+ * </script>
+ * ```
+ *
+ * Components that cannot know where the flyout lives can request it
+ * over the bus with `showFlyout()` — the same pattern `showToast()`
+ * uses. A second request swaps the content in place; it never
+ * stacks. Content passed as a string renders as plain text; pass a
+ * `Node` for rich content. Pass the triggering element as `anchor` to
+ * align the in-grid panel with that control and keep both in the same
+ * scroll flow. If the panel would cross the visible viewport's bottom,
+ * it shifts up only far enough to fit and returns to its natural trigger
+ * alignment as the page scrolls. Content taller than the viewport
+ * scrolls inside the panel. Overlay drawers stay viewport-fixed.
+ *
+ * The bus is a global broadcast, so every listening flyout on the
+ * page answers a `showFlyout()` call. The demos above are each driven
+ * by their own toggle button, so they are marked `standalone` to opt
+ * out of the bus — leaving this one flyout as the page's shared
+ * surface. In a real app you typically have a single flyout and need
+ * no attribute at all.
+ *
+ * ```html
+ * <style>
+ * esp-page.flyout-bus-demo {
+ *   --esp-page-max-width: 420px;
+ *   &::part(wrapper) {
+ *     min-height: 320px;
+ *   }
+ *   > div {
+ *     padding: var(--esp-size-padding);
+ *   }
+ *   .flyout-demo-copy {
+ *     max-inline-size: 42ch;
+ *   }
+ * }
+ * </style>
+ * <esp-page class="flyout-bus-demo">
+ *   <esp-flyout slot="flyout"></esp-flyout>
+ *   <div>
+ *     <esp-button id="show-apples" label="Apples" collapsed></esp-button>
+ *     <div class="flyout-demo-copy">
+ *       <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod
+ *       tempor incididunt ut labore et dolore magna aliqua.</p>
+ *       <p>Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
+ *       ut aliquip ex ea commodo consequat.</p>
+ *       <p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
+ *       dolore eu fugiat nulla pariatur.</p>
+ *     </div>
+ *     <esp-button id="show-pears" label="Pears" collapsed></esp-button>
+ *     <template id="pears-description">
+ *       <p>Ripen pears at room temperature until the neck yields gently to
+ *       pressure, then refrigerate them to slow further ripening.</p>
+ *       <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
+ *       nec odio. Praesent libero. Sed cursus ante dapibus diam.</p>
+ *       <p>Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis
+ *       sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper
+ *       porta.</p>
+ *       <p>Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent
+ *       taciti sociosqu ad litora torquent per conubia nostra.</p>
+ *       <p>Curabitur sodales ligula in libero. Sed dignissim lacinia nunc.
+ *       Curabitur tortor. Pellentesque nibh. Aenean quam.</p>
+ *       <p>In scelerisque sem at dolor. Maecenas mattis. Sed convallis
+ *       tristique sem. Proin ut ligula vel nunc egestas porttitor.</p>
+ *       <p>Morbi lectus risus, iaculis vel, suscipit quis, luctus non,
+ *       massa. Fusce ac turpis quis ligula lacinia aliquet.</p>
+ *       <p>Mauris ipsum. Nulla metus metus, ullamcorper vel, tincidunt sed,
+ *       euismod in, nibh. Quisque volutpat condimentum velit.</p>
+ *     </template>
+ *     <div class="flyout-demo-copy">
+ *       <p>Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia
+ *       deserunt mollit anim id est laborum.</p>
+ *       <p>Curabitur pretium tincidunt lacus. Nulla gravida orci a odio, nullam
+ *       varius, turpis et commodo pharetra.</p>
+ *     </div>
+ *   </div>
+ * </esp-page>
+ * <script>
+ *   const applesButton = findById("show-apples");
+ *   applesButton.addEventListener("clicked", () => {
+ *     showFlyout({ heading: "Apples", content: "Crisp. Store cold.", anchor: applesButton });
+ *   });
+ *   const pearsButton = findById("show-pears");
+ *   const pearsDescription = findById("pears-description");
+ *   pearsButton.addEventListener("clicked", () => {
+ *     showFlyout({
+ *       heading: "Pears",
+ *       content: pearsDescription.content.cloneNode(true),
+ *       anchor: pearsButton,
+ *     });
+ *   });
+ * </script>
+ * ```
+ *
+ * @slot - The flyout's content.
+ *
+ * @event {CustomEvent<{}>} flyout-opened - Fired by `show()` when the
+ * flyout opens.
+ * @event {CustomEvent<{reason: FlyoutCloseReason}>} flyout-closed -
+ * Fired by `close()` when the flyout closes. `reason` is `"escape"`,
+ * `"vellum"`, `"button"`, or `"programmatic"`.
+ * @event {CustomEvent<{}>} flyout-state-changed - Fired on every
+ * `open`, `mode`, or `anchor` change, including direct property
+ * assignment (not just `show()`/`close()`). `esp-page` uses it to keep
+ * its layout in sync; most consumers want
+ * `flyout-opened`/`flyout-closed` instead.
+ *
+ * @csspart panel - The panel surface.
+ * @csspart header - The heading/close-button row.
+ * @csspart content - The scrollable content region wrapping the slot.
+ *
+ * @cssprop --esp-flyout-background - The background color of the
+ * panel. Defaults to `var(--esp-color-background)`.
+ * @cssprop --esp-flyout-border - The border on the panel's leading
+ * edge. Defaults to the tear-off perforation,
+ * `1px dotted var(--esp-color-border)`.
+ * @cssprop --esp-flyout-radius - The radius of the panel's trailing
+ * corners. Defaults to `var(--esp-size-border-radius)`; the overlay
+ * drawer squares them.
+ * @cssprop --esp-flyout-shadow - The panel's shadow. Defaults to
+ * `none` in the gutter/docked modes (the perforation does the
+ * separating) and to a drawer shadow in overlay mode.
+ * @cssprop --esp-flyout-padding - Padding inside the panel's header
+ * and content regions. Defaults to `var(--esp-size-padding)`.
+ * @cssprop --esp-flyout-z-index - Stack order of the overlay-drawer
+ * mode. Defaults to `3000` — above page chrome, below the dialog
+ * drop zone (4000). Set it on the `esp-page` (or an ancestor), not on
+ * the flyout itself: the page reads the same token to hoist the
+ * drawer's aside above its header.
+ *
+ * @docPageTitle Flyout
+ * @docUrl /components/flyout
+ * @menuGroup Structure
+ * @menuOrder 3
+ * @menuLabel Flyout
+ * @menuIcon layout
+ *
+ */
+export declare class EspalierFlyout extends EspalierElementBase {
+    /**
+     * Whether the flyout is open. Reflected so the initial state can
+     * be declared in markup; `esp-page` mirrors it (via the lifecycle
+     * events and the slot) onto its own `flyout-open` attribute to
+     * drive the grid.
+     */
+    open: boolean;
+    /**
+     * Heading text for the panel's header row. Also becomes the
+     * flyout's accessible name unless the author set an `aria-label`.
+     * An open overlay without either uses the fallback name "Flyout" so
+     * its dialog is never exposed without an accessible name.
+     */
+    heading: string;
+    /**
+     * Placement behavior.
+     *
+     * - `"auto"` (default) — the page's placement ladder: gutter,
+     *   docked sidebar, then overlay drawer below the `50em` viewport
+     *   threshold.
+     * - `"overlay"` — always the fixed overlay drawer, at any width.
+     *   The page never reserves a grid track for an overlay-mode
+     *   flyout.
+     */
+    mode: "auto" | "overlay";
+    /**
+     * Triggering element whose block-start edge the in-grid panel should
+     * align with. Anchored panels stay in normal page flow, shift upward
+     * only while needed to fit the visible scrollport, and return to their
+     * natural alignment as the page scrolls. Oversized content scrolls
+     * inside the panel. Overlay drawers ignore this geometry and remain
+     * fixed to the viewport.
+     */
+    anchor: HTMLElement | undefined;
+    /**
+     * When set on a flyout slotted into an `esp-page`, the panel lifts
+     * its **trailing** edge with the page's surface edge shadow, so it
+     * reads as a raised peer of the content surface it flies out from
+     * rather than the shadowless tear-off. The **leading** edge keeps
+     * its dotted perforation and casts no shadow, so the panel stays
+     * attached at the tear line instead of floating over the content.
+     * The trailing-corner radius is still `--esp-flyout-radius`. No
+     * effect on a standalone flyout — there is no page surface to match.
+     */
+    matchSurface: boolean;
+    /**
+     * Whether this flyout ignores the shared `showFlyout()` /
+     * `closeFlyout()` bus and is driven only through its own
+     * `show()` / `close()` / `toggle()` API.
+     *
+     * By default a flyout services the bus, so a single flyout in a
+     * page "just works" as the target of `showFlyout()` — the same
+     * zero-config model as `<esp-toaster>` and `showToast()`. Because
+     * the bus is a global broadcast, **every** listening flyout on the
+     * page answers a `showFlyout()` call; set `standalone` on any
+     * flyout you drive directly so only your one designated help
+     * surface responds.
+     */
+    standalone: boolean;
+    /**
+     * Element to return focus to when the flyout closes. In the in-grid
+     * modes it is focused only if focus is inside the flyout at close;
+     * in the overlay-drawer mode it overrides the modal treatment's
+     * automatic restore-to-opener. Usually supplied through
+     * `showFlyout({ returnFocusTo })`.
+     */
+    returnFocusTo: HTMLElement | undefined;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Open the flyout with its current content. In the in-grid modes it
+     * does not move focus; in the overlay-drawer mode it moves focus
+     * into the drawer as a modal.
+     */
+    show(): void;
+    /**
+     * Close the flyout. In the in-grid modes, if focus is inside the
+     * flyout it is returned to `returnFocusTo` when one was provided; in
+     * the overlay-drawer mode the modal treatment restores focus to
+     * wherever it was when the drawer opened, unless `returnFocusTo`
+     * names an explicit target — the explicit target wins.
+     */
+    close(reason?: FlyoutCloseReason): void;
+    /**
+     * Toggle the flyout between open and closed.
+     */
+    toggle(): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-flyout": EspalierFlyout;
+    }
+}

package/dist/flyout/esp-flyout.js

@@ -0,0 +1,153 @@
+var h=function(c,e,t,i){var o=arguments.length,s=o<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,t):i,n;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(c,e,t,i);else for(var a=c.length-1;a>=0;a--)(n=c[a])&&(s=(o<3?n(s):o>3?n(e,t,s):n(e,t))||s);return o>3&&s&&Object.defineProperty(e,t,s),s};import{css as p,html as y,nothing as R}from"lit";import{customElement as k,property as l}from"lit/decorators.js";import{createRef as x,ref as C}from"lit/directives/ref.js";import{EspalierElementBase as v}from"../shared/esp-element-base.js";import{getEspBus as f}from"../shared/bus-events.js";import{OverlayController as T}from"../shared/overlay-controller.js";import{cancelSVG as E}from"../shared/svgs/cancel.js";import{traverseToClosest as b}from"../shared/utilities.js";const P="(max-width: 50em)",O="Flyout",m=p`
+  position: fixed;
+  inset: 0;
+  margin-block-start: 0;
+  width: auto;
+  
+  height: 100vh;
+  height: 100dvh;
+  z-index: var(--esp-flyout-z-index, 3000);
+`,w=p`
+  display: block;
+  position: absolute;
+  inset: 0;
+  background-color: var(--esp-vellum-background, var(--esp-color-layer-3));
+  opacity: var(--esp-vellum-opacity, 0.85);
+`,g=p`
+  position: absolute;
+  inset-block: 0;
+  inset-inline-end: 0;
+  width: min(var(--esp-page-flyout-width, 20rem), 85vw);
+  overflow-y: auto;
+  
+  border-start-end-radius: 0;
+  border-end-end-radius: 0;
+  box-shadow: var(--esp-flyout-shadow, -0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow));
+  translate: 0 0;
+  transition: translate 0.25s ease;
+
+  @starting-style {
+    translate: 100% 0;
+  }
+`;let r=class extends v{constructor(){super(...arguments),this.open=!1,this.heading="",this.mode="auto",this.matchSurface=!1,this.standalone=!1,this.lastGeneratedAriaLabel=null,this.boundKeydown=e=>this.handleKeydown(e),this.boundShowRequest=e=>this.handleShowRequest(e),this.boundCloseRequest=()=>this.close(),this.boundOverlayMediaChange=()=>{this.syncOverlayModal(),this.syncAnchorTracking(),this.syncAnchorGeometry()},this.boundAnchorViewportChange=()=>this.scheduleAnchorGeometrySync(),this.anchorPositionRaf=0,this.trackingAnchorPosition=!1,this.busSubscribed=!1,this.panelRef=x(),this.overlay=new T({host:this,getFocusTrapContainer:()=>this.panelRef.value??null,getFocusFallback:()=>this.panelRef.value??null,promote:!1}),this.overlayActive=!1,this.baseRole="complementary"}get effectiveOverlay(){return this.mode==="overlay"||(this.overlayMediaQuery?.matches??!1)}connectedCallback(){super.connectedCallback(),this.hasAttribute("role")||this.setAttribute("role","complementary"),this.baseRole=this.getAttribute("role")??"complementary",!this.overlayMediaQuery&&typeof window<"u"&&"matchMedia"in window&&(this.overlayMediaQuery=window.matchMedia(P)),this.overlayMediaQuery?.addEventListener("change",this.boundOverlayMediaChange),this.syncBusSubscription(),document.addEventListener("keydown",this.boundKeydown),this.syncOverlayModal(),this.syncAnchorTracking(),this.syncAnchorGeometry()}disconnectedCallback(){super.disconnectedCallback(),this.unsubscribeBus(),this.overlayMediaQuery?.removeEventListener("change",this.boundOverlayMediaChange),document.removeEventListener("keydown",this.boundKeydown),this.stopAnchorTracking(),this.overlayActive&&(this.overlayActive=!1,this.setAttribute("role",this.baseRole),this.removeAttribute("aria-modal"),this.updateGeneratedAriaLabel()),this.overlayReturnFocusTo=void 0}syncBusSubscription(){if(this.standalone||!this.isConnected){this.unsubscribeBus();return}this.busSubscribed||(f().subscribe("show-flyout",this.boundShowRequest),f().subscribe("close-flyout",this.boundCloseRequest),this.busSubscribed=!0)}unsubscribeBus(){this.busSubscribed&&(f().unsubscribe("show-flyout",this.boundShowRequest),f().unsubscribe("close-flyout",this.boundCloseRequest),this.busSubscribed=!1)}show(){this.open||(this.open=!0,this.dispatchEvent(new CustomEvent("flyout-opened",{detail:{},bubbles:!0,composed:!0})))}close(e="programmatic"){if(this.open){if(this.open=!1,this.overlayActive)this.overlayReturnFocusTo=this.returnFocusTo;else{const t=this.focusIsInside();this.overlay.close(),t&&this.returnFocusTo?.focus()}this.returnFocusTo=void 0,this.dispatchEvent(new CustomEvent("flyout-closed",{detail:{reason:e},bubbles:!0,composed:!0}))}}toggle(){this.open?this.close():this.show()}handleShowRequest(e){e.heading!==void 0&&(this.heading=e.heading),e.content!==void 0&&this.replaceChildren(typeof e.content=="string"?document.createTextNode(e.content):e.content),this.anchor=e.anchor,this.returnFocusTo=e.returnFocusTo,this.show()}handleKeydown(e){if(this.open){if(this.overlayActive&&e.key==="Tab"){this.overlay.trapFocus(e);return}e.key!=="Escape"||e.defaultPrevented||(e.preventDefault(),this.close("escape"))}}focusIsInside(){const e=document.activeElement;return e&&this.contains(e)?!0:this.shadowRoot?.activeElement!=null}updated(e){super.updated(e),e.has("standalone")&&this.syncBusSubscription(),e.has("heading")&&this.updateGeneratedAriaLabel(),(e.has("anchor")||e.has("open")||e.has("mode"))&&(this.syncAnchorTracking(),this.syncAnchorGeometry()),(e.has("open")||e.has("mode"))&&this.syncOverlayModal(),(e.has("open")||e.has("mode")||e.has("anchor"))&&this.dispatchEvent(new CustomEvent("flyout-state-changed",{detail:{},bubbles:!0,composed:!0}))}syncAnchorGeometry(){const e=b(this,"esp-page"),t=this.anchor?b(this.anchor,"esp-page"):null,i=e?.shadowRoot?.querySelector(".esp-page-main"),o=this.panelRef.value;if(!this.open||this.effectiveOverlay||!this.anchor||!e||t!==e||!i||!o){this.clearAnchorGeometry();return}const s=this.anchor.getBoundingClientRect(),n=Math.max(0,s.top-i.getBoundingClientRect().top),a=this.getVisibleBlockBounds(),d=Math.max(0,a.bottom-a.top);this.setGeometryProperty("--_esp-flyout-anchor-offset",`${n}px`),this.setGeometryProperty("--_esp-flyout-max-block-size",`${d}px`);const u=o.getBoundingClientRect().height,A=Math.max(0,s.top+u-a.bottom);this.setGeometryProperty("--_esp-flyout-viewport-shift",`${A}px`)}getVisibleBlockBounds(){const e=window.visualViewport;let t=e?.offsetTop??0,i=t+(e?.height??window.innerHeight);for(let o=this.composedParent(this);o;o=this.composedParent(o)){const s=getComputedStyle(o).overflowY;if(s!=="auto"&&s!=="scroll")continue;const n=o.getBoundingClientRect(),a=o instanceof HTMLElement?o.clientTop:0,d=o instanceof HTMLElement?o.clientHeight:n.height;if(d<=0)continue;const u=n.top+a;t=Math.max(t,u),i=Math.min(i,u+d)}return{top:t,bottom:Math.max(t,i)}}composedParent(e){if(e.parentElement)return e.parentElement;const t=e.getRootNode();return t instanceof ShadowRoot?t.host:null}setGeometryProperty(e,t){this.style.getPropertyValue(e)!==t&&this.style.setProperty(e,t)}clearAnchorGeometry(){this.style.removeProperty("--_esp-flyout-anchor-offset"),this.style.removeProperty("--_esp-flyout-viewport-shift"),this.style.removeProperty("--_esp-flyout-max-block-size")}scheduleAnchorGeometrySync(){!this.isConnected||this.anchorPositionRaf||(this.anchorPositionRaf=requestAnimationFrame(()=>{this.anchorPositionRaf=0,this.syncAnchorGeometry()}))}syncAnchorTracking(){if(!(this.isConnected&&this.open&&!!this.anchor&&!this.effectiveOverlay)){this.stopAnchorTracking();return}this.trackingAnchorPosition||(this.trackingAnchorPosition=!0,window.addEventListener("scroll",this.boundAnchorViewportChange,{capture:!0,passive:!0}),window.addEventListener("resize",this.boundAnchorViewportChange,{passive:!0}));const t=this.panelRef.value;t&&t!==this.observedAnchorPanel&&typeof ResizeObserver<"u"&&(this.anchorResizeObserver??=new ResizeObserver(this.boundAnchorViewportChange),this.anchorResizeObserver.disconnect(),this.anchorResizeObserver.observe(t),this.observedAnchorPanel=t)}stopAnchorTracking(){this.trackingAnchorPosition&&(window.removeEventListener("scroll",this.boundAnchorViewportChange,{capture:!0}),window.removeEventListener("resize",this.boundAnchorViewportChange),this.trackingAnchorPosition=!1),this.anchorPositionRaf&&(cancelAnimationFrame(this.anchorPositionRaf),this.anchorPositionRaf=0),this.anchorResizeObserver?.disconnect(),this.observedAnchorPanel=void 0}syncOverlayModal(){const e=this.isConnected&&this.open&&this.effectiveOverlay;if(e===this.overlayActive){!e&&!this.open&&this.overlay.close();return}e?(this.overlayActive=!0,this.setAttribute("role","dialog"),this.setAttribute("aria-modal","true"),this.updateGeneratedAriaLabel(),this.overlay.open(),this.updateComplete.then(()=>{this.overlayActive&&this.overlay.moveFocusInto()})):(this.overlayActive=!1,this.overlay.close(),this.overlayReturnFocusTo&&(this.overlayReturnFocusTo.focus(),this.overlayReturnFocusTo=void 0),this.setAttribute("role",this.baseRole),this.removeAttribute("aria-modal"),this.updateGeneratedAriaLabel())}updateGeneratedAriaLabel(){const e=this.getAttribute("aria-label");if(e!==null&&e!==this.lastGeneratedAriaLabel)return;const t=this.heading||(this.overlayActive?O:"");t?(this.setAttribute("aria-label",t),this.lastGeneratedAriaLabel=t):(this.removeAttribute("aria-label"),this.lastGeneratedAriaLabel=null)}render(){return y`
+      <div class="vellum" aria-hidden="true" @click=${()=>this.close("vellum")}></div>
+      <div class="panel" part="panel" ${C(this.panelRef)}>
+        <header part="header">
+          ${this.heading?y`<h2>${this.heading}</h2>`:R}
+          
+          <button class="close" aria-label="Close" @click=${()=>this.close("button")}>
+            ${E}
+          </button>
+        </header>
+        <div class="content" part="content">
+          <slot @slotchange=${this.boundAnchorViewportChange}></slot>
+        </div>
+      </div>
+    `}};r.styles=[...v.styles,p`
+      :host {
+        display: none;
+      }
+
+      :host([open]) {
+        display: block;
+        
+        width: var(--esp-page-flyout-width, 20rem);
+        margin-block-start: calc(
+          var(--_esp-flyout-anchor-offset, 0px) - var(--_esp-flyout-viewport-shift, 0px)
+        );
+      }
+
+      .vellum {
+        display: none;
+      }
+
+      .panel {
+        background: var(--esp-flyout-background, var(--esp-color-background));
+        
+        width: var(--esp-page-flyout-width, 20rem);
+        display: flex;
+        flex-direction: column;
+        max-block-size: var(--_esp-flyout-max-block-size, none);
+        overflow: hidden;
+        
+        border-inline-start: var(--esp-flyout-border, 1px dotted var(--esp-color-border));
+        border-start-end-radius: var(--esp-flyout-radius, var(--esp-size-border-radius));
+        border-end-end-radius: var(--esp-flyout-radius, var(--esp-size-border-radius));
+        box-shadow: var(--esp-flyout-shadow, none);
+        font-family: var(--esp-font-body);
+        color: var(--esp-color-text);
+
+        > header {
+          display: flex;
+          align-items: center;
+          gap: var(--esp-size-tiny-to-small);
+          padding: var(--esp-flyout-padding, var(--esp-size-padding));
+          padding-block-end: 0;
+
+          > h2 {
+            flex: 1;
+            margin: 0;
+            font-size: var(--esp-type-large);
+            line-height: 1.2;
+          }
+
+          > .close {
+            margin-inline-start: auto;
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            border: none;
+            background: transparent;
+            color: var(--esp-color-text);
+            cursor: pointer;
+            padding: var(--esp-size-tiny);
+
+            svg {
+              width: 1.25em;
+              height: 1.25em;
+            }
+          }
+        }
+
+        > .content {
+          min-block-size: 0;
+          overflow-y: auto;
+          overscroll-behavior-block: contain;
+          padding: var(--esp-flyout-padding, var(--esp-size-padding));
+        }
+      }
+
+      
+      :host([open][mode="overlay"]) {
+        ${m}
+      }
+
+      :host([open][mode="overlay"]) .vellum {
+        ${w}
+      }
+
+      :host([open][mode="overlay"]) .panel {
+        ${g}
+      }
+
+      
+      @media (max-width: 50em) {
+        :host([open]) {
+          ${m}
+        }
+
+        .vellum {
+          ${w}
+        }
+
+        .panel {
+          ${g}
+        }
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        .panel {
+          transition: none;
+        }
+      }
+    `],h([l({type:Boolean,reflect:!0})],r.prototype,"open",void 0),h([l({type:String})],r.prototype,"heading",void 0),h([l({reflect:!0})],r.prototype,"mode",void 0),h([l({attribute:!1})],r.prototype,"anchor",void 0),h([l({type:Boolean,reflect:!0,attribute:"match-surface"})],r.prototype,"matchSurface",void 0),h([l({type:Boolean,reflect:!0})],r.prototype,"standalone",void 0),r=h([k("esp-flyout")],r);export{r as EspalierFlyout};

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./breadcrumbs/esp-breadcrumbs.js";
 export * from "./button/esp-button.js";
 export * from "./button/esp-button-group.js";
 export * from "./color-picker/esp-color-picker.js";
+export * from "./flyout/esp-flyout.js";
 export * from "./form/esp-form.js";
 export * from "./form-item/esp-form-item.js";
 export * from "./header/index.js";
@@ -57,7 +58,8 @@ export { type ValidationError, VALIDITY_CHANGED_EVENT, type ValidityChangedDetai
 export { FormFieldController, type FormFieldControllerOptions, } from "./shared/form-field-controller.js";
 export { traverseToClosest } from "./shared/utilities.js";
 export { showToast, type ToastConfig } from "./shared/toast-events.js";
-export { getEspBus, type EspBusEventMap, type SchemeEvents, type ToastEvents, type PopoverEvents, type SizeEvents, type PageEventMap, type SeedColorRoot, } from "./shared/bus-events.js";
+export { showFlyout, closeFlyout, type FlyoutConfig, type FlyoutCloseReason, } from "./shared/flyout-events.js";
+export { getEspBus, type EspBusEventMap, type SchemeEvents, type ToastEvents, type FlyoutEvents, type PopoverEvents, type SizeEvents, type PageEventMap, type SeedColorRoot, } from "./shared/bus-events.js";
 export * from "./shared/events.js";
 export { getImageDetails, releasePreviewUrl, type EspalierUploadImage, type ImageDetailsOptions, type SelectedUploadImage, type ExistingUploadImage, type ExistingImage, type ResponsiveImageUrl, type UploadCallbacks, type UploadEventDetail, } from "./image-upload/image-helpers.js";
 export { calculatePhotoLayout, type LayoutImage, type PhotoRow, } from "./shared/justified-layout.js";

package/dist/index.js

@@ -1 +1 @@
-export*from"./box/esp-box.js";export*from"./action-menu/esp-action-menu.js";export*from"./action-menu/esp-action-menu-item.js";export*from"./avatar/esp-avatar.js";export*from"./avatar/esp-profile-chip.js";export*from"./badge/esp-badge.js";export*from"./checkbox/esp-checkbox.js";export*from"./checkbox/esp-checkbox-group.js";export*from"./data-cell/esp-data-cell.js";export*from"./radio-button/esp-radio-button.js";export*from"./radio-button/esp-radio-button-group.js";export*from"./repeater/esp-repeater.js";export*from"./breadcrumbs/esp-breadcrumbs.js";export*from"./button/esp-button.js";export*from"./button/esp-button-group.js";export*from"./color-picker/esp-color-picker.js";export*from"./form/esp-form.js";export*from"./form-item/esp-form-item.js";export*from"./header/index.js";export*from"./page/esp-page.js";export*from"./popover/esp-popover.js";export*from"./dialog/esp-dialog.js";export*from"./empty-state/esp-empty-state.js";export*from"./image-upload/esp-image-upload.js";export*from"./file-upload/esp-file-upload.js";export*from"./font-picker/esp-font-picker.js";export*from"./grid/esp-grid.js";export*from"./image/esp-image.js";export*from"./lightbox/esp-lightbox.js";export*from"./info/esp-info.js";export*from"./input/esp-input.js";export*from"./textarea/esp-textarea.js";export*from"./pickers/esp-pick-one.js";export*from"./pickers/esp-pick-some.js";export*from"./pickers/esp-picker-menu.js";export*from"./pickers/esp-picker-item.js";export*from"./root/esp-root.js";export*from"./menu/index.js";export*from"./burger/esp-burger.js";export*from"./date-picker/esp-date-picker.js";export*from"./details/esp-details.js";export*from"./details/esp-details-group.js";export*from"./tabs/esp-tab.js";export*from"./tabs/esp-tab-group.js";export*from"./slider/esp-slider.js";export*from"./switch/esp-switch.js";export*from"./toaster/esp-toaster.js";export*from"./tooltip/esp-tooltip.js";export*from"./progress/esp-progress.js";export*from"./search/esp-search.js";export*from"./status-indicator/esp-status-indicator.js";export*from"./tree/esp-tree.js";export*from"./tree/esp-tree-item.js";import{DEFAULT_ICON_SPRITE_URL as ro,DEFAULT_ICON_VIEW_BOX as eo,INTENT_VARIANTS as to,normalizeIntentVariant as mo,getIconHref as po,getIconHrefForHost as fo,getIconSpriteUrl as xo}from"./shared/intent-values.js";import{EspalierElementBase as lo}from"./shared/esp-element-base.js";import{VALIDITY_CHANGED_EVENT as so}from"./shared/validation.js";import{FormFieldController as io}from"./shared/form-field-controller.js";import{traverseToClosest as Io}from"./shared/utilities.js";import{showToast as _o}from"./shared/toast-events.js";import{getEspBus as co}from"./shared/bus-events.js";export*from"./shared/events.js";import{getImageDetails as Lo,releasePreviewUrl as No}from"./image-upload/image-helpers.js";import{calculatePhotoLayout as Ho}from"./shared/justified-layout.js";import{encodeTheme as bo,parseTheme as uo,mergePartials as Co,layerThemes as Uo,buildTaprootLightTheme as Vo,buildTaprootDarkTheme as Wo,NESTED_THEME_KEYS as Bo}from"./shared/theme.js";import{WEIGHT_LABELS as vo,extractWeights as yo,normalizeWeight as Go,bestAvailableWeight as Oo,extractFamily as Ro,getFallbackFont as ko}from"./shared/font-helpers.js";import{getGoogleFonts as zo}from"./font-picker/esp-font-picker.js";export{ro as DEFAULT_ICON_SPRITE_URL,eo as DEFAULT_ICON_VIEW_BOX,lo as EspalierElementBase,io as FormFieldController,to as INTENT_VARIANTS,Bo as NESTED_THEME_KEYS,so as VALIDITY_CHANGED_EVENT,vo as WEIGHT_LABELS,Oo as bestAvailableWeight,Wo as buildTaprootDarkTheme,Vo as buildTaprootLightTheme,Ho as calculatePhotoLayout,bo as encodeTheme,Ro as extractFamily,yo as extractWeights,co as getEspBus,ko as getFallbackFont,zo as getGoogleFonts,po as getIconHref,fo as getIconHrefForHost,xo as getIconSpriteUrl,Lo as getImageDetails,Uo as layerThemes,Co as mergePartials,mo as normalizeIntentVariant,Go as normalizeWeight,uo as parseTheme,No as releasePreviewUrl,_o as showToast,Io as traverseToClosest};
+export*from"./box/esp-box.js";export*from"./action-menu/esp-action-menu.js";export*from"./action-menu/esp-action-menu-item.js";export*from"./avatar/esp-avatar.js";export*from"./avatar/esp-profile-chip.js";export*from"./badge/esp-badge.js";export*from"./checkbox/esp-checkbox.js";export*from"./checkbox/esp-checkbox-group.js";export*from"./data-cell/esp-data-cell.js";export*from"./radio-button/esp-radio-button.js";export*from"./radio-button/esp-radio-button-group.js";export*from"./repeater/esp-repeater.js";export*from"./breadcrumbs/esp-breadcrumbs.js";export*from"./button/esp-button.js";export*from"./button/esp-button-group.js";export*from"./color-picker/esp-color-picker.js";export*from"./flyout/esp-flyout.js";export*from"./form/esp-form.js";export*from"./form-item/esp-form-item.js";export*from"./header/index.js";export*from"./page/esp-page.js";export*from"./popover/esp-popover.js";export*from"./dialog/esp-dialog.js";export*from"./empty-state/esp-empty-state.js";export*from"./image-upload/esp-image-upload.js";export*from"./file-upload/esp-file-upload.js";export*from"./font-picker/esp-font-picker.js";export*from"./grid/esp-grid.js";export*from"./image/esp-image.js";export*from"./lightbox/esp-lightbox.js";export*from"./info/esp-info.js";export*from"./input/esp-input.js";export*from"./textarea/esp-textarea.js";export*from"./pickers/esp-pick-one.js";export*from"./pickers/esp-pick-some.js";export*from"./pickers/esp-picker-menu.js";export*from"./pickers/esp-picker-item.js";export*from"./root/esp-root.js";export*from"./menu/index.js";export*from"./burger/esp-burger.js";export*from"./date-picker/esp-date-picker.js";export*from"./details/esp-details.js";export*from"./details/esp-details-group.js";export*from"./tabs/esp-tab.js";export*from"./tabs/esp-tab-group.js";export*from"./slider/esp-slider.js";export*from"./switch/esp-switch.js";export*from"./toaster/esp-toaster.js";export*from"./tooltip/esp-tooltip.js";export*from"./progress/esp-progress.js";export*from"./search/esp-search.js";export*from"./status-indicator/esp-status-indicator.js";export*from"./tree/esp-tree.js";export*from"./tree/esp-tree-item.js";import{DEFAULT_ICON_SPRITE_URL as eo,DEFAULT_ICON_VIEW_BOX as to,INTENT_VARIANTS as mo,normalizeIntentVariant as po,getIconHref as fo,getIconHrefForHost as xo,getIconSpriteUrl as ao}from"./shared/intent-values.js";import{EspalierElementBase as so}from"./shared/esp-element-base.js";import{VALIDITY_CHANGED_EVENT as Eo}from"./shared/validation.js";import{FormFieldController as go}from"./shared/form-field-controller.js";import{traverseToClosest as no}from"./shared/utilities.js";import{showToast as _o}from"./shared/toast-events.js";import{showFlyout as co,closeFlyout as Ao}from"./shared/flyout-events.js";import{getEspBus as No}from"./shared/bus-events.js";export*from"./shared/events.js";import{getImageDetails as Ho,releasePreviewUrl as So}from"./image-upload/image-helpers.js";import{calculatePhotoLayout as yo}from"./shared/justified-layout.js";import{encodeTheme as Uo,parseTheme as Vo,mergePartials as Wo,layerThemes as Bo,buildTaprootLightTheme as Po,buildTaprootDarkTheme as vo,NESTED_THEME_KEYS as wo}from"./shared/theme.js";import{WEIGHT_LABELS as Oo,extractWeights as Ro,normalizeWeight as ko,bestAvailableWeight as zo,extractFamily as Yo,getFallbackFont as Ko}from"./shared/font-helpers.js";import{getGoogleFonts as Xo}from"./font-picker/esp-font-picker.js";export{eo as DEFAULT_ICON_SPRITE_URL,to as DEFAULT_ICON_VIEW_BOX,so as EspalierElementBase,go as FormFieldController,mo as INTENT_VARIANTS,wo as NESTED_THEME_KEYS,Eo as VALIDITY_CHANGED_EVENT,Oo as WEIGHT_LABELS,zo as bestAvailableWeight,vo as buildTaprootDarkTheme,Po as buildTaprootLightTheme,yo as calculatePhotoLayout,Ao as closeFlyout,Uo as encodeTheme,Yo as extractFamily,Ro as extractWeights,No as getEspBus,Ko as getFallbackFont,Xo as getGoogleFonts,fo as getIconHref,xo as getIconHrefForHost,ao as getIconSpriteUrl,Ho as getImageDetails,Bo as layerThemes,Wo as mergePartials,po as normalizeIntentVariant,ko as normalizeWeight,Vo as parseTheme,So as releasePreviewUrl,co as showFlyout,_o as showToast,no as traverseToClosest};

package/dist/page/esp-page.d.ts

@@ -34,6 +34,15 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  *
  * @slot sidebar - Contextual navigation placed in the left aside.
  * @slot right - Content to place in the right aside.
+ * @slot flyout - A transient `esp-flyout` panel that lives on the
+ * canvas, outside the content surface. Closed it costs no width; open
+ * it claims the right canvas gutter first — the surface keeps its
+ * alignment weighting and shifts only as far as the flyout's width
+ * requires — then docks as a width-competing right sidebar when no
+ * gutter exists, and becomes an overlay drawer on small viewports.
+ * The persistent `right` aside and the transient flyout are
+ * complementary, not alternatives. A flyout opened with an `anchor`
+ * aligns to that trigger and stays in the same document scroll flow.
  * @slot footer - Content to place in the footer.
  * @slot - The main page content. The main content region applies
  * `contain: inline-size` so child components cannot push the
@@ -122,7 +131,16 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  * only shows above the cap. Set to `none` to remove it.
  * @cssprop --esp-page-surface-border - An optional border on the inline
  * edges of the surface, for themes preferring a hairline over a shadow.
- * Defaults to `none` (e.g. `1px solid var(--esp-color-border)`).
+ * Defaults to `none` (e.g. `1px solid var(--esp-color-border)`). Combine
+ * with `--esp-page-surface-shadow: none` to switch the content frame
+ * from a drop shadow to a hairline, or turn both off for no frame.
+ * @cssprop --esp-page-main-background - The background of the main
+ * content well. Defaults to `transparent` (the well shows the page
+ * background). Set it to give the content well its own card color, or
+ * pair the transparent default with `--esp-page-surface-shadow: none`
+ * for content that floats directly on the page with no frame.
+ * @cssprop --esp-page-flyout-width - The width of the open flyout
+ * track (and of the `esp-flyout` overlay drawer). Defaults to `20rem`.
  * @cssprop --esp-page-fixed-header-offset - Offset reserved for fixed
  * headers. Defaults to `var(--esp-header-height)`.
  * @cssprop --esp-page-sticky-header-top - Top inset for sticky headers.
@@ -251,6 +269,7 @@ export declare class EspalierPage extends EspalierElementBase {
      * @param dialog The EspalierDialog to show.
      */
     AddDialog(dialog: EspalierDialog | DocumentFragment | HTMLElement): void;
+    protected firstUpdated(changedProperties: PropertyValues): void;
     protected updated(changedProperties: PropertyValues): void;
     protected render(): import("lit-html").TemplateResult<1>;
     static styles: import("lit").CSSResult[];