@excom/content-drawer 0.1.0

package/src/content-drawer.css

@@ -0,0 +1,344 @@
+@import "@excom/valence/src/aliases.css";
+@import "@excom/valence/src/util.default.css";
+@import "@excom/valence/src/components/modal.css";
+
+/**
+ * Styles for `<content-drawer>`.
+ * @element content-drawer
+ */
+
+/* Aliases */
+@custom-selector :--content-drawer content-drawer, .tag-content-drawer;
+@custom-selector :--content-drawer--is-open [is-open], [aria-expanded="true"];
+/* Doubled so a scrub outranks the `is-open` + `open-stage` rules */
+@custom-selector :--content-drawer--is-scrubbing
+  [is-scrubbing][is-scrubbing],
+  [data-scrubbing][data-scrubbing];
+@custom-selector :--content-drawer--open-stage-1
+  [open-stage="1"],
+  [data-open="1"];
+@custom-selector :--content-drawer--open-stage-2
+  [open-stage="2"],
+  [data-open="2"];
+@custom-selector :--content-drawer--from-side [from-side], [data-placement];
+@custom-selector :--content-drawer--from-side-bottom
+  [from-side="bottom"],
+  [data-placement="bottom"];
+@custom-selector :--content-drawer--from-side-top
+  [from-side="top"],
+  [data-placement="top"];
+@custom-selector :--content-drawer--from-side-left
+  [from-side="left"],
+  [data-placement="left"];
+@custom-selector :--content-drawer--from-side-right
+  [from-side="right"],
+  [data-placement="right"];
+
+@define-mixin module-content-drawer {
+  :root {
+    /**
+     * Slide transition duration.
+     * @cssproperty
+     * @syntax <time>
+     * @default 0.25s
+     */
+    --content-drawer-transition-duration: var(
+      --v-transition-duration-standard,
+      0.25s
+    );
+    /**
+     * Slide transition easing.
+     * @cssproperty
+     * @syntax <easing-function>
+     * @default ease-out
+     */
+    --content-drawer-transition-ease: var(--v-transition-ease-out, ease-out);
+    /**
+     * Off-screen translate amount (closed).
+     * @cssproperty
+     * @syntax <percentage>
+     * @default 101%
+     */
+    --content-drawer-closed: 101%;
+    /**
+     * Full-open translate (`open-stage` unset or `0`).
+     * @cssproperty
+     * @syntax <percentage>
+     * @default 0%
+     */
+    --content-drawer-open-full: 0%;
+    /**
+     * Half-open translate (`open-stage="1"`).
+     * @cssproperty
+     * @syntax <percentage>
+     * @default 50%
+     */
+    --content-drawer-open-half: 50%;
+    /**
+     * Peek translate (`open-stage="2"`).
+     * @cssproperty
+     * @syntax <percentage>
+     * @default 75%
+     */
+    --content-drawer-open-peek: 75%;
+    /**
+     * Max width when open in `.relative` mode, used unless
+     * `--content-drawer-max-width` is set.
+     * @cssproperty
+     * @syntax <length>
+     * @default 200px
+     */
+    --content-drawer-relative-max-width: 200px;
+    /**
+     * Stack order for the drawer panel.
+     * @cssproperty
+     * @syntax <integer>
+     * @default 3
+     */
+    --content-drawer-z-index: 3;
+    /**
+     * Stack order for the sibling backdrop (`:--dialog-backdrop-aliases`).
+     * @cssproperty
+     * @syntax <integer>
+     * @default 2
+     */
+    --content-drawer-overlay-z-index: 2;
+  }
+
+  *:has(> :--content-drawer) {
+    position: relative;
+    overflow: hidden;
+  }
+
+  :--content-drawer {
+    /**
+     * How far open the drawer is while `is-scrubbing`: `0` closed, `1`
+     * full. Declared on the drawer (not `:root`) so it follows a wrapping
+     * `<gesture-handler>`'s inherited `--gesture-progress` unless set
+     * explicitly — a swipe-to-open / drag-to-close bottom sheet.
+     * @cssproperty
+     * @syntax <number>
+     * @default var(--gesture-progress, 0)
+     */
+    --content-drawer-open-progress: var(--gesture-progress, 0);
+  }
+
+  :--content-drawer:not(.relative) {
+    /* Not `display: none` when closed. Child intersection observers must
+       keep working, and a discrete display transition would animate a
+       drawer that starts `[is-open]` on first paint. */
+    display: block;
+    position: fixed;
+    z-index: var(--content-drawer-z-index);
+    /* Needed for an accurate height */
+    box-sizing: border-box;
+    background-color: var(--v-card-background-color, #f7f7f7);
+    box-shadow: 2px 0 16px rgba(0, 0, 0, 0.08);
+    overscroll-behavior-y: contain;
+    transition: transform var(--content-drawer-transition-duration)
+      var(--content-drawer-transition-ease);
+    /* A finger drives the position: no easing between frames */
+    &:--content-drawer--is-scrubbing {
+      transition: none;
+    }
+
+    /**
+     * Close control — empty `.close` / `[rel="prev"]`
+     * button or link (theme close icon).
+     * @cssclass close
+     */
+    @mixin modal-inner;
+    overflow-y: scroll;
+    margin: 0;
+    padding: var(--v-spacing);
+
+    /**
+     * `position: sticky` instead of the default `absolute` placement.
+     * @cssclass
+     */
+    &.sticky {
+      position: sticky;
+    }
+    /**
+     * `position: absolute` instead of the default `fixed` placement —
+     * a sheet inside its (`position: relative`) parent.
+     * @cssclass
+     */
+    &.absolute {
+      position: absolute;
+    }
+
+    /* bottom (default) */
+    &:not(:--content-drawer--from-side),
+    &:--content-drawer--from-side-bottom {
+      border-radius: var(--v-border-radius, 10px) var(--v-border-radius, 10px)
+        0px 0px;
+      transform: translateY(var(--content-drawer-closed));
+      left: 0;
+      right: 0;
+      bottom: 0;
+      &:--content-drawer--is-open {
+        transform: translateY(var(--content-drawer-open-full));
+      }
+      &:--content-drawer--is-open:--content-drawer--open-stage-1 {
+        transform: translateY(var(--content-drawer-open-half));
+      }
+      &:--content-drawer--is-open:--content-drawer--open-stage-2 {
+        transform: translateY(var(--content-drawer-open-peek));
+      }
+      &:--content-drawer--is-scrubbing {
+        transform: translateY(
+          calc(
+            var(--content-drawer-closed) *
+              (1 - var(--content-drawer-open-progress))
+          )
+        );
+      }
+    }
+
+    /* top */
+    &:--content-drawer--from-side-top {
+      border-radius: 0px 0px var(--v-border-radius, 10px)
+        var(--v-border-radius, 10px);
+      transform: translateY(calc(var(--content-drawer-closed) * -1));
+      left: 0;
+      right: 0;
+      top: 0;
+      &:--content-drawer--is-open {
+        transform: translateY(calc(var(--content-drawer-open-full) * -1));
+      }
+      &:--content-drawer--is-open:--content-drawer--open-stage-1 {
+        transform: translateY(calc(var(--content-drawer-open-half) * -1));
+      }
+      &:--content-drawer--is-open:--content-drawer--open-stage-2 {
+        transform: translateY(calc(var(--content-drawer-open-peek) * -1));
+      }
+      &:--content-drawer--is-scrubbing {
+        transform: translateY(
+          calc(
+            var(--content-drawer-closed) *
+              (var(--content-drawer-open-progress) - 1)
+          )
+        );
+      }
+    }
+
+    /* left */
+    &:--content-drawer--from-side-left {
+      border-radius: 0px var(--v-border-radius, 10px)
+        var(--v-border-radius, 10px) 0px;
+      transform: translateX(calc(var(--content-drawer-closed) * -1));
+      top: 0;
+      bottom: 0;
+      left: 0;
+      &:--content-drawer--is-open {
+        transform: translateX(calc(var(--content-drawer-open-full) * -1));
+      }
+      &:--content-drawer--is-open:--content-drawer--open-stage-1 {
+        transform: translateX(calc(var(--content-drawer-open-half) * -1));
+      }
+      &:--content-drawer--is-open:--content-drawer--open-stage-2 {
+        transform: translateX(calc(var(--content-drawer-open-peek) * -1));
+      }
+      &:--content-drawer--is-scrubbing {
+        transform: translateX(
+          calc(
+            var(--content-drawer-closed) *
+              (var(--content-drawer-open-progress) - 1)
+          )
+        );
+      }
+    }
+
+    /* right */
+    &:--content-drawer--from-side-right {
+      border-radius: var(--v-border-radius, 10px) 0px 0px
+        var(--v-border-radius, 10px);
+      transform: translateX(var(--content-drawer-closed));
+      top: 0;
+      bottom: 0;
+      right: 0;
+      &:--content-drawer--is-open {
+        transform: translateX(var(--content-drawer-open-full));
+      }
+      &:--content-drawer--is-open:--content-drawer--open-stage-1 {
+        transform: translateX(var(--content-drawer-open-half));
+      }
+      &:--content-drawer--is-open:--content-drawer--open-stage-2 {
+        transform: translateX(var(--content-drawer-open-peek));
+      }
+      &:--content-drawer--is-scrubbing {
+        transform: translateX(
+          calc(
+            var(--content-drawer-closed) *
+              (1 - var(--content-drawer-open-progress))
+          )
+        );
+      }
+    }
+
+    /**
+     * Sibling dimmer: Valence.css `:--dialog-backdrop-aliases`
+     * (`[role="presentation"]` / `.tag-backdrop`). Place as the immediate
+     * next sibling; click-to-close is `<event-handler>` / `<dismiss-watcher>`.
+     */
+    & + :--dialog-backdrop-aliases {
+      @mixin modal-backdrop;
+      display: none;
+      position: fixed;
+      z-index: var(--content-drawer-overlay-z-index);
+      opacity: 0;
+      transition:
+        opacity var(--content-drawer-transition-duration)
+          var(--content-drawer-transition-ease),
+        display var(--content-drawer-transition-duration) allow-discrete;
+      &.sticky {
+        position: sticky;
+      }
+      &.absolute {
+        position: absolute;
+      }
+    }
+
+    &:--content-drawer--is-open + :--dialog-backdrop-aliases {
+      display: block;
+      opacity: 1;
+      @starting-style {
+        opacity: 0;
+      }
+    }
+  }
+
+  /**
+   * In-flow mode: the drawer participates in layout and animates
+   * `max-width` instead of overlaying via `position`, pushing sibling
+   * content aside as it opens. Currently only affects
+   * `from-side="left"`.
+   * @cssclass
+   */
+  :--content-drawer.relative {
+    display: block;
+    position: relative;
+    overflow: hidden;
+
+    &:--content-drawer--from-side-left {
+      height: 100%;
+      max-width: 0;
+      width: 100%;
+      transition: max-width var(--content-drawer-transition-duration)
+        var(--content-drawer-transition-ease);
+      &:--content-drawer--is-open {
+        /**
+         * Overrides `--content-drawer-relative-max-width` for this
+         * drawer only.
+         * @cssproperty --content-drawer-max-width
+         * @syntax <length>
+         */
+        max-width: var(
+          --content-drawer-max-width,
+          var(--content-drawer-relative-max-width)
+        );
+      }
+    }
+  }
+}

package/support/custom-elements.json

@@ -0,0 +1,360 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "content-drawer.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ContentDrawer",
+          "customElement": true,
+          "tagName": "content-drawer",
+          "summary": "Slide-in drawer / sheet — bottom, top, left, or right, with peek stages.",
+          "description": "Props the invoker of `--open` / `--toggle` may set through its `data-*` attributes (`data-open-stage=\"1\"` → `openStage`). Keys are whitelisted against declared, non-private props; `isOpen` is always the command's.",
+          "attributes": [
+            {
+              "name": "from-side",
+              "type": {
+                "text": "string"
+              },
+              "description": "Edge the drawer slides from.",
+              "fieldName": "fromSide",
+              "default": "bottom",
+              "values": [
+                "bottom",
+                "top",
+                "left",
+                "right"
+              ]
+            },
+            {
+              "name": "disappear-after",
+              "type": {
+                "text": "number"
+              },
+              "description": "Auto-close after this many seconds once opened — toast-style / transient confirmations.",
+              "fieldName": "disappearAfter"
+            },
+            {
+              "name": "singleton-name",
+              "type": {
+                "text": "string"
+              },
+              "description": "Shared group name. Opening one drawer closes others with the same name (singleton coordination).",
+              "fieldName": "singletonName"
+            },
+            {
+              "name": "open-stage",
+              "type": {
+                "text": "number"
+              },
+              "description": "How far the drawer opens: `0` full, `1` half, `2` peek. Unset = full. Set statically, or per open through `data-open-stage` on the `--open` / `--toggle` invoker.",
+              "fieldName": "openStage",
+              "values": [
+                "0",
+                "1",
+                "2"
+              ]
+            },
+            {
+              "name": "is-open",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Open state. Toggle directly, or through the `--open` / `--close` / `--toggle` commands. For Escape / outside-click dismissal pair with `<dismiss-watcher command-name=\"--close\">`.",
+              "fieldName": "isOpen"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "fromSide",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Edge the drawer slides from.",
+              "default": "bottom",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "disappearAfter",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Auto-close after this many seconds once opened — toast-style / transient confirmations.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "singletonName",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Shared group name. Opening one drawer closes others with the same name (singleton coordination).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "openStage",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "How far the drawer opens: `0` full, `1` half, `2` peek. Unset = full. Set statically, or per open through `data-open-stage` on the `--open` / `--toggle` invoker.",
+              "_neutron": {
+                "surface": "hybrid"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Open state. Toggle directly, or through the `--open` / `--close` / `--toggle` commands. For Escape / outside-click dismissal pair with `<dismiss-watcher command-name=\"--close\">`.",
+              "_neutron": {
+                "surface": "hybrid"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "content-drawer-opened",
+              "description": "After open (`is-open` set), `detail` is the drawer. When `singleton-name` is set it is also broadcast so drawers sharing that name close.",
+              "type": {
+                "text": "ContentDrawerOpenedEvent",
+                "expanded": "CustomEvent & { type: \"content-drawer-opened\"; detail: HTMLElement; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "content-drawer-closed",
+              "description": "After close (`is-open` unset), `detail` is the drawer.",
+              "type": {
+                "text": "ContentDrawerClosedEvent",
+                "expanded": "CustomEvent & { type: \"content-drawer-closed\"; detail: HTMLElement; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "commands": [
+              {
+                "name": "--open",
+                "description": "Opens the drawer (`is-open` set). `data-*` attributes on the invoker that name a declared prop (`data-open-stage`, `data-from-side`, …) are applied first; unknown, private and `isOpen` keys are ignored."
+              },
+              {
+                "name": "--close",
+                "description": "Closes the drawer (`is-open` unset)."
+              },
+              {
+                "name": "--toggle",
+                "description": "Toggles open / closed. Reads the invoker's `data-*` like `--open`."
+              }
+            ],
+            "cssClasses": [
+              {
+                "name": "close",
+                "description": "Close control — empty `.close` / `[rel=\"prev\"]` button or link (theme close icon)."
+              },
+              {
+                "name": "sticky",
+                "description": "`position: sticky` instead of the default `absolute` placement."
+              },
+              {
+                "name": "absolute",
+                "description": "`position: absolute` instead of the default `fixed` placement — a sheet inside its (`position: relative`) parent."
+              },
+              {
+                "name": "relative",
+                "description": "In-flow mode: the drawer participates in layout and animates `max-width` instead of overlaying via `position`, pushing sibling content aside as it opens. Currently only affects `from-side=\"left\"`."
+              }
+            ],
+            "cssAliases": [
+              {
+                "name": ":--content-drawer",
+                "selectors": [
+                  "content-drawer",
+                  ".tag-content-drawer"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--content-drawer--is-open",
+                "selectors": [
+                  "[is-open]",
+                  "[aria-expanded=\"true\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-drawer--is-scrubbing",
+                "selectors": [
+                  "[is-scrubbing][is-scrubbing]",
+                  "[data-scrubbing][data-scrubbing]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-drawer--open-stage-1",
+                "selectors": [
+                  "[open-stage=\"1\"]",
+                  "[data-open=\"1\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-drawer--open-stage-2",
+                "selectors": [
+                  "[open-stage=\"2\"]",
+                  "[data-open=\"2\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-drawer--from-side",
+                "selectors": [
+                  "[from-side]",
+                  "[data-placement]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-drawer--from-side-bottom",
+                "selectors": [
+                  "[from-side=\"bottom\"]",
+                  "[data-placement=\"bottom\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-drawer--from-side-top",
+                "selectors": [
+                  "[from-side=\"top\"]",
+                  "[data-placement=\"top\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-drawer--from-side-left",
+                "selectors": [
+                  "[from-side=\"left\"]",
+                  "[data-placement=\"left\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-drawer--from-side-right",
+                "selectors": [
+                  "[from-side=\"right\"]",
+                  "[data-placement=\"right\"]"
+                ],
+                "kind": "state"
+              }
+            ]
+          },
+          "cssProperties": [
+            {
+              "name": "--content-drawer-transition-duration",
+              "description": "Slide transition duration.",
+              "syntax": "<time>",
+              "default": "0.25s"
+            },
+            {
+              "name": "--content-drawer-transition-ease",
+              "description": "Slide transition easing.",
+              "syntax": "<easing-function>",
+              "default": "ease-out"
+            },
+            {
+              "name": "--content-drawer-closed",
+              "description": "Off-screen translate amount (closed).",
+              "syntax": "<percentage>",
+              "default": "101%"
+            },
+            {
+              "name": "--content-drawer-open-full",
+              "description": "Full-open translate (`open-stage` unset or `0`).",
+              "syntax": "<percentage>",
+              "default": "0%"
+            },
+            {
+              "name": "--content-drawer-open-half",
+              "description": "Half-open translate (`open-stage=\"1\"`).",
+              "syntax": "<percentage>",
+              "default": "50%"
+            },
+            {
+              "name": "--content-drawer-open-peek",
+              "description": "Peek translate (`open-stage=\"2\"`).",
+              "syntax": "<percentage>",
+              "default": "75%"
+            },
+            {
+              "name": "--content-drawer-relative-max-width",
+              "description": "Max width when open in `.relative` mode, used unless `--content-drawer-max-width` is set.",
+              "syntax": "<length>",
+              "default": "200px"
+            },
+            {
+              "name": "--content-drawer-z-index",
+              "description": "Stack order for the drawer panel.",
+              "syntax": "<integer>",
+              "default": "3"
+            },
+            {
+              "name": "--content-drawer-overlay-z-index",
+              "description": "Stack order for the sibling backdrop (`:--dialog-backdrop-aliases`).",
+              "syntax": "<integer>",
+              "default": "2"
+            },
+            {
+              "name": "--content-drawer-open-progress",
+              "description": "How far open the drawer is while `is-scrubbing`: `0` closed, `1` full. Declared on the drawer (not `:root`) so it follows a wrapping `<gesture-handler>`'s inherited `--gesture-progress` unless set explicitly — a swipe-to-open / drag-to-close bottom sheet.",
+              "syntax": "<number>",
+              "default": "var(--gesture-progress, 0)"
+            },
+            {
+              "name": "--content-drawer-max-width",
+              "description": "Overrides `--content-drawer-relative-max-width` for this drawer only.",
+              "syntax": "<length>"
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ContentDrawer",
+          "declaration": {
+            "name": "ContentDrawer",
+            "module": "content-drawer.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "content-drawer",
+          "declaration": {
+            "name": "ContentDrawer",
+            "module": "content-drawer.ts"
+          }
+        }
+      ]
+    }
+  ]
+}