@taprootio/espalier 6.3.0 → 6.4.0

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

@@ -136,6 +136,41 @@ export declare class EspalierBox extends EspalierElementBase {
      * </script>
      * ```
      *
+     * A full-screen box fills the viewport. Inside a
+     * [bounded dialog](/components/dialog) it fills exactly the dialog's
+     * rectangle instead: it takes its position and size from the same
+     * `--esp-dialog-inset-*` custom properties, set on the `esp-dialog` or any
+     * ancestor of the box.
+     *
+     * ```html
+     * <style>
+     *   esp-dialog.bounded-box {
+     *     --esp-dialog-inset-block-start: 6rem;
+     *     --esp-dialog-inset-inline-start: 3rem;
+     *     --esp-dialog-inset-inline-end: 3rem;
+     *     --esp-dialog-inset-block-end: 2rem;
+     *   }
+     * </style>
+     * <esp-dialog class="bounded-box" full-screen>
+     *   <esp-box full-screen>
+     *     <h2>Box in a bounded dialog</h2>
+     *     <p>This box fills the rectangle the dialog is bounded to.</p>
+     *     <esp-button intent="danger" label="Close"></esp-button>
+     *   </esp-box>
+     * </esp-dialog>
+     * <esp-button label="Show Dialog"></esp-button>
+     * <script>
+     *   const theDialog = findByTagName("esp-dialog")[0];
+     *   const buttons = findByTagName("esp-button");
+     *   buttons[0].addEventListener("esp-clicked", () => {
+     *     theDialog.toggleOpen();
+     *   });
+     *   buttons[1].addEventListener("esp-clicked", () => {
+     *     theDialog.toggleOpen();
+     *   });
+     * </script>
+     * ```
+     *
      * @type {boolean}
      */
     fullScreen: boolean;

package/dist/box/esp-box.js

@@ -1,10 +1,10 @@
-var n=function(t,e,r,i){var a=arguments.length,o=a<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,r):i,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(t,e,r,i);else for(var p=t.length-1;p>=0;p--)(l=t[p])&&(o=(a<3?l(o):a>3?l(e,r,o):l(e,r))||o);return a>3&&o&&Object.defineProperty(e,r,o),o};import{paintedSurface as c}from"../shared/surface-layer.js";import{css as b,html as v}from"lit";import{customElement as h,property as f}from"lit/decorators.js";import{classMap as u}from"lit/directives/class-map.js";import{EspalierElementBase as d}from"../shared/esp-element-base.js";let s=class extends d{constructor(){super(...arguments),this.fullScreen=!1}render(){const{fullScreen:e}=this;return v`
+var p=function(r,e,s,i){var a=arguments.length,o=a<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,s):i,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(r,e,s,i);else for(var n=r.length-1;n>=0;n--)(l=r[n])&&(o=(a<3?l(o):a>3?l(e,s,o):l(e,s))||o);return a>3&&o&&Object.defineProperty(e,s,o),o};import{paintedSurface as c}from"../shared/surface-layer.js";import{css as v,html as b}from"lit";import{customElement as f,property as h}from"lit/decorators.js";import{classMap as u}from"lit/directives/class-map.js";import{EspalierElementBase as d}from"../shared/esp-element-base.js";let t=class extends d{constructor(){super(...arguments),this.fullScreen=!1}render(){const{fullScreen:e}=this;return b`
       <div class=${u({"esp-box":!0,"full-screen":e})}>
         <div part="box">
           <slot></slot>
         </div>
       </div>
-    `}};s.styles=[...d.styles,c(1),b`
+    `}};t.styles=[...d.styles,c(1),v`
       :host {
         display: block;
       }
@@ -42,16 +42,31 @@ var n=function(t,e,r,i){var a=arguments.length,o=a<3?e:i===null?i=Object.getOwnP
         }
 
         &.full-screen {
-          width: 100vw;
-          
-          height: 100vh;
-          height: 100dvh;
+          width: calc(
+            100vw - var(--esp-dialog-inset-inline-start, 0px) - var(
+                --esp-dialog-inset-inline-end,
+                0px
+              )
+          );
+          height: calc(
+            100vh - var(--esp-dialog-inset-block-start, 0px) - var(
+                --esp-dialog-inset-block-end,
+                0px
+              )
+          );
+          height: calc(
+            100dvh - var(--esp-dialog-inset-block-start, 0px) - var(
+                --esp-dialog-inset-block-end,
+                0px
+              )
+          );
           position: fixed;
-          top: 0;
-          left: 0;
+          inset-block-start: var(--esp-dialog-inset-block-start, 0px);
+          inset-inline-start: var(--esp-dialog-inset-inline-start, 0px);
           z-index: 10;
 
           > div {
+            position: relative;
             overflow-y: auto;
             
             padding-bottom: max(
@@ -61,4 +76,4 @@ var n=function(t,e,r,i){var a=arguments.length,o=a<3?e:i===null?i=Object.getOwnP
           }
         }
       }
-    `],n([f({attribute:"full-screen",type:Boolean})],s.prototype,"fullScreen",void 0),s=n([h("esp-box")],s);export{s as EspalierBox};
+    `],p([h({attribute:"full-screen",type:Boolean})],t.prototype,"fullScreen",void 0),t=p([f("esp-box")],t);export{t as EspalierBox};

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

@@ -20,6 +20,78 @@ import { LitElement } from "lit";
  * - Restores focus to the element that was focused before the
  *   dialog was opened.
  *
+ * ### Bounded dialog
+ *
+ * A dialog covers the whole viewport by default. Set the four inset custom
+ * properties on the `esp-dialog` host to confine it to a rectangle and leave
+ * the rest of the page visible, for example to keep a header or a live preview
+ * on screen while a full-screen editor is open. The vellum (the dialog's
+ * scrolling surface) and its backdrop paint only inside the rectangle, and a
+ * slotted `esp-box full-screen` fills exactly that rectangle.
+ *
+ * The insets are lengths (`0px`, `4rem`, `var(--header-height)`), not unitless
+ * numbers, and they are measured from the viewport edges. They are logical, so
+ * "inline start" is the left edge in left-to-right text and the right edge in
+ * right-to-left text. Because custom properties inherit, a dialog nested inside
+ * a bounded dialog's markup is bounded the same way unless it sets its own
+ * insets.
+ *
+ * Bounds change only where the dialog paints. What stays reachable is decided
+ * by the same rules as an unbounded dialog:
+ *
+ * - The dialog has no click-outside dismissal, bounded or not. It closes on
+ *   `Escape`, an `esp-form-dialog-close-requested` event, or `toggleOpen()`, so
+ *   a click on the uncovered region never counts as an "outside" click.
+ * - The dialog marks `inert` the siblings of its anchor element, not the
+ *   regions its bounds leave uncovered. The anchor is `esp-page`'s dialog drop
+ *   zone when the dialog sits in the page's markup, so there the page's
+ *   internal tracks (header, menus, preview, help, footer) are inert and not
+ *   clickable even where the dialog does not cover them. A dialog that is a
+ *   direct child of another component's shadow root is anchored on the nearest
+ *   ancestor host that has a light-DOM parent, and only that host's siblings
+ *   go inert; the page around it stays live. A dialog wrapped in an element
+ *   inside that shadow root is anchored on itself, so its siblings in the
+ *   wrapper go inert instead.
+ * - A region that is not inert receives clicks and keyboard focus. The focus
+ *   trap wraps `Tab` and `Shift+Tab` at the dialog's first and last focusable
+ *   elements, and `Escape` is handled on the dialog, both only while focus is
+ *   inside it. A click on an uncovered control moves focus there, and from then
+ *   on `Tab` continues through the page and `Escape` no longer closes the
+ *   dialog. Set `inert` on the uncovered regions that must not be reachable
+ *   while the dialog is open (an inert region is also skipped by screen
+ *   readers).
+ * - Bounds assume a horizontal writing mode: the insets are logical, but the
+ *   dialog's width and height are physical.
+ *
+ * ```html
+ * <style>
+ *   esp-dialog.bounded {
+ *     --esp-dialog-inset-block-start: 6rem;
+ *     --esp-dialog-inset-inline-start: 3rem;
+ *     --esp-dialog-inset-inline-end: 3rem;
+ *     --esp-dialog-inset-block-end: 2rem;
+ *   }
+ * </style>
+ * <esp-dialog class="bounded" full-screen>
+ *   <esp-box full-screen>
+ *     <h2>Bounded dialog</h2>
+ *     <p>The page above and around this box stays visible.</p>
+ *     <esp-button intent="danger" label="Close"></esp-button>
+ *   </esp-box>
+ * </esp-dialog>
+ * <esp-button label="Show Dialog"></esp-button>
+ * <script>
+ *   const theDialog = findByTagName("esp-dialog")[0];
+ *   const buttons = findByTagName("esp-button");
+ *   buttons[0].addEventListener("esp-clicked", () => {
+ *     theDialog.toggleOpen();
+ *   });
+ *   buttons[1].addEventListener("esp-clicked", () => {
+ *     theDialog.toggleOpen();
+ *   });
+ * </script>
+ * ```
+ *
  * @slot - Place content to show modally in the default slot.
  *
  * ```html
@@ -105,6 +177,10 @@ import { LitElement } from "lit";
  *
  * @cssprop --esp-color-dialog-bg - The background color of the dialog overlay.
  * @cssprop --esp-dialog-bg-opacity - The opacity of the dialog overlay background.
+ * @cssprop --esp-dialog-inset-block-start - The top edge of the area the dialog covers, as a length from the viewport top. Defaults to `0px`.
+ * @cssprop --esp-dialog-inset-inline-start - The leading edge (left in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`.
+ * @cssprop --esp-dialog-inset-inline-end - The trailing edge (right in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`.
+ * @cssprop --esp-dialog-inset-block-end - The bottom edge of the area the dialog covers, as a length from the viewport bottom. Defaults to `0px`.
  * @attr {"1"|"2"|"3"|"4"} surface-layer - Declares the painted surface depth; defaults to layer 3.
  * @customElement esp-dialog
  * @docPageTitle Dialog

package/dist/dialog/esp-dialog.js

@@ -1,14 +1,14 @@
-var c=function(l,e,t,o){var n=arguments.length,i=n<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,t):o,r;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(l,e,t,o);else for(var a=l.length-1;a>=0;a--)(r=l[a])&&(i=(n<3?r(i):n>3?r(e,t,i):r(e,t))||i);return n>3&&i&&Object.defineProperty(e,t,i),i};import{paintedSurface as f,surfaceLayerAttributes as v}from"../shared/surface-layer.js";import{LitElement as m,css as b,html as g,nothing as u}from"lit";import{customElement as y,property as _,state as O}from"lit/decorators.js";import{classMap as k}from"lit/directives/class-map.js";import{createRef as d,ref as h}from"lit/directives/ref.js";import{OverlayController as E}from"../shared/overlay-controller.js";import{ESP_EVENTS as p}from"../shared/events.js";let s=class extends m{constructor(){super(...arguments),this.dialogSlot=d(),this.vellumRef=d(),this.isOpen=!1,this._overlay=new E({host:this,getFocusTrapContainer:()=>this.vellumRef.value??null,getFocusFallback:()=>this.vellumRef.value??null}),this._closeReason="api",this._lifecycleToken=0,this.fullScreen=!1}toggleOpen(){if(this.isOpen){const e=this._closeReason;this._closeReason="api";const t=new CustomEvent(p.DIALOG_CLOSING,{detail:{reason:e},bubbles:!0,composed:!0,cancelable:!0});if(!this.dispatchEvent(t))return;const o=++this._lifecycleToken;this.removeAttribute("is-open"),this.isOpen=!1,this._overlay.close(),this.updateComplete.then(()=>{this.isOpen||this._lifecycleToken!==o||this.dispatchEvent(new CustomEvent(p.DIALOG_CLOSED,{detail:{reason:e},bubbles:!0,composed:!0}))})}else{const e=++this._lifecycleToken;this.setAttribute("is-open","true"),this.isOpen=!0,this._overlay.open(),this.updateComplete.then(()=>{!this.isOpen||this._lifecycleToken!==e||(this._moveFocusIntoDialog(),this.dispatchEvent(new CustomEvent(p.DIALOG_OPENED,{detail:{},bubbles:!0,composed:!0})))})}}_handleKeyDown(e){if(this.isOpen){if(e.key==="Escape"){e.preventDefault(),this._closeReason="escape",this.toggleOpen();return}e.key==="Tab"&&this._overlay.trapFocus(e)}}_moveFocusIntoDialog(){this._overlay.moveFocusInto()}firstUpdated(){this.dialogSlot.value&&this.dialogSlot.value.addEventListener("esp-form-dialog-close-requested",e=>{this._closeReason="close-dialog",this.toggleOpen(),e.preventDefault()})}disconnectedCallback(){super.disconnectedCallback()}render(){const{isOpen:e,fullScreen:t}=this,o={"is-open":e,"full-screen":t};return g`<div
+var p=function(l,e,t,i){var n=arguments.length,s=n<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,t):i,a;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(l,e,t,i);else for(var r=l.length-1;r>=0;r--)(a=l[r])&&(s=(n<3?a(s):n>3?a(e,t,s):a(e,t))||s);return n>3&&s&&Object.defineProperty(e,t,s),s};import{paintedSurface as v,surfaceLayerAttributes as f}from"../shared/surface-layer.js";import{LitElement as g,css as b,html as m,nothing as d}from"lit";import{customElement as y,property as k,state as _}from"lit/decorators.js";import{classMap as x}from"lit/directives/class-map.js";import{createRef as u,ref as h}from"lit/directives/ref.js";import{OverlayController as O}from"../shared/overlay-controller.js";import{ESP_EVENTS as c}from"../shared/events.js";let o=class extends g{constructor(){super(...arguments),this.dialogSlot=u(),this.vellumRef=u(),this.isOpen=!1,this._overlay=new O({host:this,getFocusTrapContainer:()=>this.vellumRef.value??null,getFocusFallback:()=>this.vellumRef.value??null}),this._closeReason="api",this._lifecycleToken=0,this.fullScreen=!1}toggleOpen(){if(this.isOpen){const e=this._closeReason;this._closeReason="api";const t=new CustomEvent(c.DIALOG_CLOSING,{detail:{reason:e},bubbles:!0,composed:!0,cancelable:!0});if(!this.dispatchEvent(t))return;const i=++this._lifecycleToken;this.removeAttribute("is-open"),this.isOpen=!1,this._overlay.close(),this.updateComplete.then(()=>{this.isOpen||this._lifecycleToken!==i||this.dispatchEvent(new CustomEvent(c.DIALOG_CLOSED,{detail:{reason:e},bubbles:!0,composed:!0}))})}else{const e=++this._lifecycleToken;this.setAttribute("is-open","true"),this.isOpen=!0,this._overlay.open(),this.updateComplete.then(()=>{!this.isOpen||this._lifecycleToken!==e||(this._moveFocusIntoDialog(),this.dispatchEvent(new CustomEvent(c.DIALOG_OPENED,{detail:{},bubbles:!0,composed:!0})))})}}_handleKeyDown(e){if(this.isOpen){if(e.key==="Escape"){e.preventDefault(),this._closeReason="escape",this.toggleOpen();return}e.key==="Tab"&&this._overlay.trapFocus(e)}}_moveFocusIntoDialog(){this._overlay.moveFocusInto()}firstUpdated(){this.dialogSlot.value&&this.dialogSlot.value.addEventListener("esp-form-dialog-close-requested",e=>{this._closeReason="close-dialog",this.toggleOpen(),e.preventDefault()})}disconnectedCallback(){super.disconnectedCallback()}render(){const{isOpen:e,fullScreen:t}=this,i={"is-open":e,"full-screen":t};return m`<div
       ${h(this.vellumRef)}
-      class="vellum ${k(o)}"
+      class="vellum ${x(i)}"
       data-no-swipe
-      role=${e?"dialog":u}
-      aria-modal=${e?"true":u}
+      role=${e?"dialog":d}
+      aria-modal=${e?"true":d}
       tabindex="-1"
       @keydown=${this._handleKeyDown}
     >
       <slot ${h(this.dialogSlot)}></slot>
-    </div>`}};s.styles=[f(3),v(":host"),b`
+    </div>`}};o.styles=[v(3),f(":host"),b`
       :host {
         display: block;
       }
@@ -20,12 +20,21 @@ var c=function(l,e,t,o){var n=arguments.length,i=n<3?e:o===null?o=Object.getOwnP
         visibility: hidden;
         position: fixed;
         z-index: 10000;
-        left: 0;
-        top: 0;
+        inset-inline-start: var(--esp-dialog-inset-inline-start, 0px);
+        inset-block-start: var(--esp-dialog-inset-block-start, 0px);
         
-        height: 100vh;
-        height: 100dvh;
-        width: 100vw;
+        width: calc(
+          100vw - var(--esp-dialog-inset-inline-start, 0px) - var(
+              --esp-dialog-inset-inline-end,
+              0px
+            )
+        );
+        height: calc(
+          100vh - var(--esp-dialog-inset-block-start, 0px) - var(--esp-dialog-inset-block-end, 0px)
+        );
+        height: calc(
+          100dvh - var(--esp-dialog-inset-block-start, 0px) - var(--esp-dialog-inset-block-end, 0px)
+        );
         overflow-y: auto;
         outline: none;
 
@@ -34,11 +43,18 @@ var c=function(l,e,t,o){var n=arguments.length,i=n<3?e:o===null?o=Object.getOwnP
           position: relative;
         }
 
-        &::before {
+        &::before,
+        &::after {
           content: "";
           display: block;
           position: fixed;
-          inset: 0;
+          inset-inline: var(--esp-dialog-inset-inline-start, 0px)
+            var(--esp-dialog-inset-inline-end, 0px);
+          inset-block: var(--esp-dialog-inset-block-start, 0px)
+            var(--esp-dialog-inset-block-end, 0px);
+        }
+
+        &::before {
           opacity: var(--esp-dialog-bg-opacity, var(--esp-vellum-opacity, 0.85));
           background: var(
             --esp-color-dialog-bg,
@@ -48,10 +64,6 @@ var c=function(l,e,t,o){var n=arguments.length,i=n<3?e:o===null?o=Object.getOwnP
         }
 
         &::after {
-          content: "";
-          display: block;
-          position: fixed;
-          inset: 0;
           background-image: var(--esp-vellum-background-image, none);
           background-repeat: repeat;
           opacity: var(--esp-vellum-background-image-opacity, 0.3);
@@ -74,4 +86,4 @@ var c=function(l,e,t,o){var n=arguments.length,i=n<3?e:o===null?o=Object.getOwnP
           }
         }
       }
-    `],c([O()],s.prototype,"isOpen",void 0),c([_({attribute:"full-screen",type:Boolean})],s.prototype,"fullScreen",void 0),s=c([y("esp-dialog")],s);export{s as EspalierDialog};
+    `],p([_()],o.prototype,"isOpen",void 0),p([k({attribute:"full-screen",type:Boolean})],o.prototype,"fullScreen",void 0),o=p([y("esp-dialog")],o);export{o as EspalierDialog};

package/espalier.css-data.json

@@ -469,6 +469,22 @@
       "name": "--esp-dialog-bg-opacity",
       "description": "The opacity of the dialog overlay background."
     },
+    {
+      "name": "--esp-dialog-inset-block-end",
+      "description": "The bottom edge of the area the dialog covers, as a length from the viewport bottom. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-block-start",
+      "description": "The top edge of the area the dialog covers, as a length from the viewport top. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-inline-end",
+      "description": "The trailing edge (right in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-inline-start",
+      "description": "The leading edge (left in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`."
+    },
     {
       "name": "--esp-field-background",
       "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins."

package/espalier.token-manifest.json

@@ -633,6 +633,30 @@
       "component": "esp-dialog",
       "description": "The opacity of the dialog overlay background."
     },
+    {
+      "name": "--esp-dialog-inset-block-end",
+      "category": "component",
+      "component": "esp-dialog",
+      "description": "The bottom edge of the area the dialog covers, as a length from the viewport bottom. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-block-start",
+      "category": "component",
+      "component": "esp-dialog",
+      "description": "The top edge of the area the dialog covers, as a length from the viewport top. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-inline-end",
+      "category": "component",
+      "component": "esp-dialog",
+      "description": "The trailing edge (right in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-inline-start",
+      "category": "component",
+      "component": "esp-dialog",
+      "description": "The leading edge (left in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`."
+    },
     {
       "name": "--esp-field-background",
       "category": "shared-hook",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/espalier",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "packageManager": "bun@1.3.12",
   "description": "Espalier — a themeable, accessible, framework-agnostic, enterprise-grade design system built on web standards and love.",
   "customElements": "custom-elements.json",