@tapestry-ui/modal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Minton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @tapestry-ui/modal
+
+A WCAG 2.1 AA modal panel for **Preact**, built on the native
+`<dialog>` element. Pinned title, pinned header, **one scrollable
+middle**, pinned footer — [@tapestry-ui/drawer](https://www.npmjs.com/package/@tapestry-ui/drawer)'s
+container contract shipped as a component instead of a README warning.
+
+```sh
+npm i @tapestry-ui/modal
+```
+
+```tsx
+import { Modal } from '@tapestry-ui/modal';
+import '@tapestry-ui/modal/styles.css';   // structural only — optional
+
+const [open, setOpen] = useState(false);
+
+<Modal
+  open={open}
+  onClose={() => setOpen(false)}
+  title="THE BUNDLE"
+  header={<WeaponPicker />}      /* pinned above the scroll        */
+  footer="I closes the bundle"   /* pinned below it                */
+>
+  <TokenList />                  {/* THE scrollable middle          */}
+  <Drawer summary="SOUND">…</Drawer>
+</Modal>
+```
+
+## The skeleton is the point
+`title` / `header` / `footer` never scroll out of reach; `children`
+render in the ONE region that grows and scrolls
+(`[data-part="content"]`: `flex: 1 1 auto; min-height: 0;
+overflow-y: auto`). Drop an open drawer or a long list in there and
+nothing escapes the panel's bounds — that exact escape is the shipped
+bug this family of packages was born from.
+
+## Modal vs panel
+- **`modal` (default)** — `dialog.showModal()`: top layer, `::backdrop`,
+  focus held inside, Escape via the platform's own `cancel` event,
+  backdrop click closes (`closeOnBackdrop={false}` to opt out).
+- **`modal={false}`** — `dialog.show()`: a non-blocking **panel**. Still
+  a dialog to assistive tech, but the page (or game) behind stays live;
+  Escape is handled at the document (`closeOnEscape={false}` to own the
+  key yourself). This is the mode a HUD wants.
+
+Either way the component **only reports intent** through `onClose` —
+it never closes itself. State stays yours.
+
+## Accessibility (by design, not by audit)
+- Native `<dialog>`: implicit role, honest platform semantics.
+- `title` wires `aria-labelledby`; with no title, `label` is the
+  accessible name — a dialog here can never be nameless.
+- The × is a real `<button>` whose name (`closeLabel`) you localize;
+  `showClose={false}` if you bring your own affordance.
+- Closed means **gone from the DOM**, not visually hidden.
+- `:focus-visible` outlines ship structural and restylable
+  (`--tui-modal-focus`), never removable by accident.
+
+## Skin
+Structural CSS only — nothing picks a color. Hooks: every part carries
+`data-part` (`root` · `close` · `title` · `header` · `content` ·
+`footer`) and a merge-in class prop (`class`, `titleClass`,
+`headerClass`, `contentClass`, `footerClass`, `closeClass`).
+
+| custom property | what |
+|---|---|
+| `--tui-modal-max-w` / `--tui-modal-max-h` | panel bounds |
+| `--tui-modal-pad` | panel padding |
+| `--tui-modal-backdrop` | `::backdrop` (modal mode) |
+| `--tui-modal-close-size` / `--tui-modal-close-inset` | the × |
+| `--tui-modal-focus` | the focus ring |
+
+## API
+`<Modal open onClose title? label? header? footer? modal?
+closeOnEscape? closeOnBackdrop? closeLabel? showClose? …classes id?>`
+— `open` is required and controlled; `children` are the scrollable
+content region.

package/dist/modal.d.ts

@@ -0,0 +1,40 @@
+import { type ComponentChildren, type JSX } from 'preact';
+export interface ModalProps {
+    /** controlled visibility — the component follows it and reports intent
+     *  through onClose (Escape, ×, backdrop); it never closes itself */
+    open: boolean;
+    onClose: () => void;
+    /** pinned title line; wires aria-labelledby */
+    title?: ComponentChildren;
+    /** accessible name when there is no title (required then — a dialog
+     *  must never be nameless to assistive tech) */
+    label?: string;
+    /** pinned region between the title and the scrollable content */
+    header?: ComponentChildren;
+    /** THE scrollable middle — the one region that grows and scrolls */
+    children?: ComponentChildren;
+    /** pinned footer */
+    footer?: ComponentChildren;
+    /** true (default) = dialog.showModal(): top layer, backdrop, focus held.
+     *  false = dialog.show(): a non-blocking panel; the page stays live */
+    modal?: boolean;
+    /** close on Escape (default true). In modal mode Escape arrives as the
+     *  platform's own `cancel`; in non-modal mode the component listens */
+    closeOnEscape?: boolean;
+    /** modal mode only: clicking the backdrop closes (default true) */
+    closeOnBackdrop?: boolean;
+    /** accessible name for the × button (default "Close" — pass your own
+     *  locale's word; the default exists so the name can never be empty) */
+    closeLabel?: string;
+    /** omit the × entirely (the consumer provides its own affordance) */
+    showClose?: boolean;
+    /** skin hooks — tapestry-ui components style through CSS, never props */
+    class?: string;
+    titleClass?: string;
+    headerClass?: string;
+    contentClass?: string;
+    footerClass?: string;
+    closeClass?: string;
+    id?: string;
+}
+export declare function Modal(props: ModalProps): JSX.Element | null;

package/dist/modal.js

@@ -0,0 +1,72 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+import { useEffect, useId, useRef } from 'preact/hooks';
+export function Modal(props) {
+    const dialogRef = useRef(null);
+    const autoId = useId();
+    const id = props.id ?? `tui-modal-${autoId}`;
+    const titleId = `${id}-title`;
+    const modal = props.modal !== false;
+    const closeOnEscape = props.closeOnEscape !== false;
+    // follow `open` with the platform's own verbs; a runtime without
+    // showModal (old browsers, some test DOMs) falls back to the open
+    // attribute, which keeps rendering honest even where the top layer
+    // does not exist
+    useEffect(() => {
+        const dialog = dialogRef.current;
+        if (!dialog)
+            return;
+        if (props.open && !dialog.open) {
+            const show = modal ? dialog.showModal : dialog.show;
+            if (typeof show === 'function') {
+                try {
+                    show.call(dialog);
+                }
+                catch {
+                    dialog.setAttribute('open', '');
+                }
+            }
+            else {
+                dialog.setAttribute('open', '');
+            }
+        }
+        else if (!props.open && dialog.open) {
+            if (typeof dialog.close === 'function')
+                dialog.close();
+            else
+                dialog.removeAttribute('open');
+        }
+    }, [props.open, modal]);
+    // non-modal Escape: the platform only fires `cancel` for showModal(),
+    // so a panel listens for itself — while open, at the document, so the
+    // key works wherever focus sits (a game canvas, the page behind)
+    useEffect(() => {
+        if (!props.open || modal || !closeOnEscape)
+            return;
+        const onKey = (e) => {
+            if (e.key === 'Escape')
+                props.onClose();
+        };
+        document.addEventListener('keydown', onKey);
+        return () => document.removeEventListener('keydown', onKey);
+    }, [props.open, modal, closeOnEscape, props.onClose]);
+    // modal Escape arrives as `cancel`: report intent, never self-close
+    const onCancel = (e) => {
+        e.preventDefault();
+        if (closeOnEscape)
+            props.onClose();
+    };
+    // a click on the <dialog> itself (not its parts) is the backdrop —
+    // every real part of the panel is inside [data-part] children
+    const onBackdropClick = (e) => {
+        if (!modal || props.closeOnBackdrop === false)
+            return;
+        if (e.target === dialogRef.current)
+            props.onClose();
+    };
+    if (!props.open)
+        return null;
+    return (_jsxs("dialog", { ref: dialogRef, id: id, class: cx('tui-modal', props.class), "data-part": "root", "data-modal": modal ? '' : undefined, "aria-labelledby": props.title != null ? titleId : undefined, "aria-label": props.title == null ? props.label : undefined, onCancel: onCancel, onClick: onBackdropClick, children: [props.showClose !== false && (_jsx("button", { type: "button", class: cx('tui-modal-close', props.closeClass), "data-part": "close", "aria-label": props.closeLabel ?? 'Close', onClick: () => props.onClose(), children: "\u00D7" })), props.title != null && (_jsx("div", { id: titleId, class: cx('tui-modal-title', props.titleClass), "data-part": "title", children: props.title })), props.header != null && (_jsx("div", { class: cx('tui-modal-header', props.headerClass), "data-part": "header", children: props.header })), _jsx("div", { class: cx('tui-modal-content', props.contentClass), "data-part": "content", children: props.children }), props.footer != null && (_jsx("footer", { class: cx('tui-modal-footer', props.footerClass), "data-part": "footer", children: props.footer }))] }));
+}
+function cx(...parts) {
+    return parts.filter(Boolean).join(' ');
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tapestry-ui/modal",
+  "version": "0.1.0",
+  "description": "A WCAG 2.1 AA modal panel for Preact on the native <dialog> element — pinned header, ONE scrollable middle, pinned footer. The drawer's container contract, shipped as a component instead of a README warning.",
+  "license": "MIT",
+  "author": "Brandon Minton",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/modal.d.ts",
+      "default": "./dist/modal.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "files": [
+    "dist",
+    "styles.css",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "preact": ">=10.24.0"
+  },
+  "devDependencies": {
+    "jsdom": "^25.0.1",
+    "preact": "^10.29.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryurage/brandonminton.git",
+    "directory": "packages/tapestry-ui/modal"
+  },
+  "keywords": [
+    "preact",
+    "modal",
+    "dialog",
+    "panel",
+    "a11y",
+    "wcag",
+    "headless",
+    "tapestry-ui"
+  ]
+}

package/styles.css

@@ -0,0 +1,53 @@
+/* @tapestry-ui/modal — STRUCTURAL styles only. The skin is yours:
+   override the custom properties, or ignore this file entirely and
+   style [data-part] hooks from scratch. Nothing here picks a color
+   (the dialog's UA background is the browser's, not ours).
+
+   THE SKELETON IS THE POINT: title, header and footer are pinned;
+   .tui-modal-content is the ONE region that grows and scrolls. That
+   flex/min-height/overflow trio is the container contract the drawer's
+   README warns about — here it is load-bearing, not advice. */
+.tui-modal {
+  border: none;
+  padding: var(--tui-modal-pad, 1em 1.5em);
+  max-width: var(--tui-modal-max-w, min(36em, 90vw));
+  max-height: var(--tui-modal-max-h, min(80vh, 40em));
+}
+.tui-modal[open] {
+  display: flex;
+  flex-direction: column;
+}
+.tui-modal::backdrop {
+  background: var(--tui-modal-backdrop, rgba(0, 0, 0, 0.4));
+}
+.tui-modal-content {
+  flex: 1 1 auto;          /* the ONE scrollable middle…        */
+  min-height: 0;           /* …allowed to actually shrink…      */
+  overflow-y: auto;        /* …owns ALL the growth. THE CONTRACT. */
+  overscroll-behavior: contain;
+}
+.tui-modal-close {
+  position: absolute;
+  top: var(--tui-modal-close-inset, 0.4em);
+  right: var(--tui-modal-close-inset, 0.4em);
+  width: var(--tui-modal-close-size, 1.6em);
+  height: var(--tui-modal-close-size, 1.6em);
+  display: grid;
+  place-items: center;
+  background: none;
+  border: none;
+  cursor: pointer;
+  font: inherit;
+  color: inherit;
+  opacity: 0.7;
+  line-height: 1;
+}
+.tui-modal-close:hover { opacity: 1; }
+.tui-modal-close:focus-visible,
+.tui-modal :focus-visible {
+  outline: var(--tui-modal-focus, 2px solid currentColor);
+  outline-offset: 2px;
+}
+.tui-modal-footer { flex: none; }
+.tui-modal-title,
+.tui-modal-header { flex: none; }