@tapestry-ui/drawer 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,85 @@
+# @tapestry-ui/drawer
+
+A nestable, accessible disclosure drawer for **Preact**. Headless
+behavior, skin via CSS. Forged inside a woven-tapestry video game,
+where it learned its most important lesson the hard way (see **The
+container contract**).
+
+```sh
+npm i @tapestry-ui/drawer
+```
+
+```tsx
+import { Drawer, DrawerList } from '@tapestry-ui/drawer';
+import '@tapestry-ui/drawer/styles.css';   // structural only — optional
+
+<Drawer summary="SOUND">
+  <VolumeSliders />
+</Drawer>
+
+// nesting is just children
+<Drawer summary="settings" defaultOpen>
+  <Drawer summary="advanced">…</Drawer>
+</Drawer>
+
+// the data-source layer; `exclusive` makes it an accordion
+<DrawerList
+  exclusive
+  items={[
+    { summary: 'one', content: <A /> },
+    { summary: 'two', content: <B /> },
+  ]}
+/>
+```
+
+## Accessibility (WCAG 2.1 AA by design, not by audit)
+- The summary is a **real `<button>`** — Enter/Space, focus, and every
+  assistive tech behavior come free and honest.
+- `aria-expanded` + `aria-controls` wire the WAI-ARIA disclosure
+  pattern; ids are auto-generated and collision-free under nesting.
+- `headingLevel={2..6}` wraps the button in a real heading, so a drawer
+  that titles a section never lies to the document outline.
+- The closed body is **removed from the DOM**, not visually hidden —
+  screen readers never wade through collapsed forests.
+- `:focus-visible` outline ships in the structural CSS and is yours to
+  restyle, never to remove.
+
+## ⭐ The container contract
+**A drawer is only half a component. The other half is the scroll
+contract of whatever contains it.** A Drawer never owns scrolling and
+never constrains its container; when open drawers can exceed the
+available space, some ancestor **you choose** must be the scroll
+region:
+
+```css
+.my-modal-content {           /* ONE scrollable middle… */
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;           /* …owns ALL the growth */
+}
+```
+
+Skip this and an open drawer will push its tail past your modal's
+bounds — this exact bug is the reason this package exists. Put the
+drawer INSIDE the region that scrolls, never as a sibling below it.
+
+## Skin
+Structural CSS only — nothing in `styles.css` picks a color. Hooks:
+
+| hook | what |
+|---|---|
+| `[data-part="root"]` `[data-state="open"\|"closed"]` | the drawer + its state |
+| `[data-part="summary"]` / `"caret"` / `"body"` / `"heading"` | the parts |
+| `class` / `summaryClass` / `bodyClass` props | merge your own classes |
+| `--tui-drawer-gap` · `--tui-drawer-indent` · `--tui-drawer-summary-pad` | spacing |
+| `--tui-drawer-caret-closed` / `-open` (content strings) · `--tui-drawer-caret-size` | the caret |
+| `--tui-drawer-focus` | the focus ring |
+
+## API
+`<Drawer summary children defaultOpen? open? onOpenChange? disabled?
+headingLevel? class? summaryClass? bodyClass? id?>` — controlled when
+`open` is passed (the component then only reports intent through
+`onOpenChange`), uncontrolled otherwise.
+
+`<DrawerList items exclusive? headingLevel? onOpenChange? …classes>` —
+sugar over composition; `exclusive` = accordion.

package/dist/drawer.d.ts

@@ -0,0 +1,42 @@
+import { type ComponentChildren, type JSX } from 'preact';
+export interface DrawerProps {
+    /** what the closed drawer shows — text or any inline nodes */
+    summary: ComponentChildren;
+    children?: ComponentChildren;
+    /** uncontrolled initial state (default closed) */
+    defaultOpen?: boolean;
+    /** controlled state — when provided, the component follows it and only
+     *  reports intent through onOpenChange */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    disabled?: boolean;
+    /** wrap the summary button in a heading of this level (2–6) so the
+     *  drawer can title a section without lying to the document outline */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /** skin hooks — tapestry-ui components style through CSS, never props */
+    class?: string;
+    summaryClass?: string;
+    bodyClass?: string;
+    id?: string;
+}
+export declare function Drawer(props: DrawerProps): JSX.Element;
+export interface DrawerItem {
+    id?: string;
+    summary: ComponentChildren;
+    content: ComponentChildren;
+    defaultOpen?: boolean;
+    disabled?: boolean;
+}
+export interface DrawerListProps {
+    items: DrawerItem[];
+    /** at most one open at a time — the accordion behavior */
+    exclusive?: boolean;
+    headingLevel?: DrawerProps['headingLevel'];
+    class?: string;
+    summaryClass?: string;
+    bodyClass?: string;
+    onOpenChange?: (openIds: string[]) => void;
+}
+/** A list of drawers from data — and with `exclusive`, an accordion.
+ *  Purely a layer over <Drawer/>: everything it can do, composition can. */
+export declare function DrawerList(props: DrawerListProps): JSX.Element;

package/dist/drawer.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+// @tapestry-ui/drawer — the disclosure drawer (Tapestry UI citizen #1).
+//
+// DESIGN RULINGS (Brandon, 2026-09-25): WCAG 2.1 AA from the ground up ·
+// nestable · skin via CSS · as little coupling as we can get away with ·
+// composition-first, with a data-source layer as sugar on top.
+//
+// THE CONTAINER CONTRACT (the lesson this component was born from): a
+// drawer is only half a component — the other half is the scroll contract
+// of whatever contains it. A Drawer NEVER owns scrolling and never grows
+// its container; the CONSUMER decides which ancestor scrolls when open
+// drawers exceed the space. See README "The container contract" — a modal
+// that skips that section will push this drawer's tail out of its own
+// bounds, exactly once, and then read the section.
+//
+// A11y shape: the WAI-ARIA disclosure pattern. The summary is a real
+// <button> (Enter/Space free, focusable, honest in every AT) carrying
+// aria-expanded + aria-controls; the body is a region the button controls.
+// `headingLevel` wraps the button in <h2>..<h6> so document outlines stay
+// truthful when the drawer titles a section.
+import { h, Fragment } from 'preact';
+import { useId, useState } from 'preact/hooks';
+export function Drawer(props) {
+    const autoId = useId();
+    const id = props.id ?? `tui-drawer-${autoId}`;
+    const bodyId = `${id}-body`;
+    const controlled = props.open !== undefined;
+    const [ownOpen, setOwnOpen] = useState(props.defaultOpen ?? false);
+    const open = controlled ? props.open : ownOpen;
+    const toggle = () => {
+        if (props.disabled)
+            return;
+        const next = !open;
+        if (!controlled)
+            setOwnOpen(next);
+        props.onOpenChange?.(next);
+    };
+    const button = (_jsxs("button", { type: "button", class: cx('tui-drawer-summary', props.summaryClass), "data-part": "summary", "aria-expanded": open, "aria-controls": bodyId, disabled: props.disabled, onClick: toggle, children: [_jsx("span", { class: "tui-drawer-caret", "data-part": "caret", "aria-hidden": "true" }), props.summary] }));
+    const H = props.headingLevel ? `h${props.headingLevel}` : null;
+    return (_jsxs("div", { id: id, class: cx('tui-drawer', props.class), "data-part": "root", "data-state": open ? 'open' : 'closed', "data-disabled": props.disabled ? '' : undefined, children: [H ? h(H, { class: 'tui-drawer-heading', 'data-part': 'heading' }, button) : button, open && (_jsx("div", { id: bodyId, class: cx('tui-drawer-body', props.bodyClass), "data-part": "body", role: "group", children: props.children }))] }));
+}
+/** A list of drawers from data — and with `exclusive`, an accordion.
+ *  Purely a layer over <Drawer/>: everything it can do, composition can. */
+export function DrawerList(props) {
+    const autoId = useId();
+    const ids = props.items.map((it, i) => it.id ?? `tui-dl-${autoId}-${i}`);
+    const [openIds, setOpenIds] = useState(props.items.flatMap((it, i) => (it.defaultOpen ? [ids[i]] : []))
+        .slice(0, props.exclusive ? 1 : undefined));
+    const setOpen = (itemId, open) => {
+        const next = open
+            ? props.exclusive ? [itemId] : [...openIds, itemId]
+            : openIds.filter((x) => x !== itemId);
+        setOpenIds(next);
+        props.onOpenChange?.(next);
+    };
+    return (_jsx(Fragment, { children: props.items.map((it, i) => (_jsx(Drawer, { id: ids[i], summary: it.summary, open: openIds.includes(ids[i]), onOpenChange: (o) => setOpen(ids[i], o), disabled: it.disabled, headingLevel: props.headingLevel, class: props.class, summaryClass: props.summaryClass, bodyClass: props.bodyClass, children: it.content }, ids[i]))) }));
+}
+function cx(...parts) {
+    return parts.filter(Boolean).join(' ');
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tapestry-ui/drawer",
+  "version": "0.1.0",
+  "description": "A nestable, WCAG 2.1 AA disclosure drawer for Preact \u2014 headless behavior, skin via CSS. Forged inside a woven-tapestry game; ships with its container contract, not just its markup.",
+  "license": "MIT",
+  "author": "Brandon Minton",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/drawer.d.ts",
+      "default": "./dist/drawer.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/drawer"
+  },
+  "keywords": [
+    "preact",
+    "disclosure",
+    "accordion",
+    "drawer",
+    "a11y",
+    "wcag",
+    "headless",
+    "tapestry-ui"
+  ]
+}

package/styles.css

@@ -0,0 +1,33 @@
+/* @tapestry-ui/drawer — 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. */
+.tui-drawer-summary {
+  display: flex;
+  align-items: center;
+  gap: var(--tui-drawer-gap, 0.4em);
+  width: 100%;
+  text-align: left;
+  cursor: pointer;
+  background: none;
+  border: none;
+  padding: var(--tui-drawer-summary-pad, 0.25em 0);
+  font: inherit;
+  color: inherit;
+}
+.tui-drawer-summary:disabled { cursor: default; opacity: 0.5; }
+.tui-drawer-summary:focus-visible {
+  outline: var(--tui-drawer-focus, 2px solid currentColor);
+  outline-offset: 2px;
+}
+.tui-drawer-caret {
+  width: var(--tui-drawer-caret-size, 0.6em);
+  flex: none;
+  opacity: 0.7;
+}
+.tui-drawer-caret::before { content: var(--tui-drawer-caret-closed, "▸"); }
+[data-state="open"] > * > .tui-drawer-caret::before,
+[data-state="open"] > .tui-drawer-summary .tui-drawer-caret::before {
+  content: var(--tui-drawer-caret-open, "▾");
+}
+.tui-drawer-body { padding-inline-start: var(--tui-drawer-indent, 1em); }
+.tui-drawer-heading { margin: 0; font: inherit; }