@tjakoen/grain 0.1.12 → 0.1.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/PLAN.md +1 -1
- package/README.md +4 -0
- package/components/molecules/data-table/data-table.css +47 -0
- package/components/molecules/data-table/data-table.md +65 -0
- package/components/molecules/data-table/data-table.test.ts +54 -0
- package/components/molecules/nav-item/nav-item.css +12 -0
- package/components/molecules/nav-item/nav-item.md +11 -0
- package/components/molecules/table/table.md +3 -0
- package/components/organisms/drawer/drawer.css +59 -0
- package/components/organisms/drawer/drawer.md +69 -0
- package/components/organisms/drawer/drawer.test.ts +43 -0
- package/components/organisms/side-rail/side-rail.css +40 -0
- package/components/organisms/side-rail/side-rail.md +30 -0
- package/components/organisms/topbar/topbar.css +30 -0
- package/components/organisms/topbar/topbar.md +22 -0
- package/package.json +1 -1
- package/scripts/drawer.js +113 -0
- package/scripts/drawer.test.ts +70 -0
package/PLAN.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
> (`/ai/manifest`), grade-as-signal, and the SSE dispatcher island. This file is GRAIN's **roadmap**:
|
|
6
6
|
> planned/deferred features, one line each. It is an *index*, **not** a second source of truth — the AI
|
|
7
7
|
> contract lives in [AI-INTERFACE](https://tjakoen.github.io/grain/docs/ai-interface), the build rules in
|
|
8
|
-
> [CONVENTIONS](https://tjakoen.github.io/batch/docs/conventions), the beliefs in [
|
|
8
|
+
> [CONVENTIONS](https://tjakoen.github.io/batch/docs/conventions), the beliefs in [`PHILOSOPHY.md`](https://github.com/tjakoen/tjakoen.github.io/blob/main/docs/PHILOSOPHY.md). When a
|
|
9
9
|
> feature is built, follow the CLAUDE.md alignment table (contract → reasoner → tests → docs).
|
|
10
10
|
|
|
11
11
|
## Planned
|
package/README.md
CHANGED
|
@@ -181,6 +181,10 @@ data-attributes, no composition-root wiring and no AI layer required:
|
|
|
181
181
|
trigger (if it's an `<a href>`, the href is the full image, so it stays a real link with no JS);
|
|
182
182
|
a `[data-lightbox-group]` ancestor turns its triggers into one gallery with prev/next + a dot rail.
|
|
183
183
|
Caption comes from `data-lightbox-caption` or the child `<img>` alt.
|
|
184
|
+
- **`scripts/drawer.js`** + the `drawer` organism: the modal side panel. `[data-drawer-open="id"]`
|
|
185
|
+
opens, `[data-drawer-close]` (the scrim carries it) closes, and the script owns the modal
|
|
186
|
+
obligations — focus into the panel, Tab trapped, the rest of the page `inert`, focus returned to
|
|
187
|
+
the opener. Open/closed is the plain `hidden` attribute, so a server can ship it either way.
|
|
184
188
|
|
|
185
189
|
---
|
|
186
190
|
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/* molecules/data-table — a DENSE table of records: the list view of a workspace app (rows you
|
|
2
|
+
scan, sort and open), as opposed to the `table` molecule, which is a CONTENT table (MILL maps
|
|
3
|
+
Markdown pipe tables to it, prose padding, first column flush left). Two components on purpose,
|
|
4
|
+
not one variant: they differ in header treatment, density, rules and affordance, and reaching
|
|
5
|
+
for the wrong one should be a decision, not an accident. See table.md.
|
|
6
|
+
|
|
7
|
+
Monochrome and ruled, never zebra-striped (DESIGN-SYSTEM §2). CSS-only: nothing data-binds it —
|
|
8
|
+
the rows are the consumer's, rendered server-side or by an island. */
|
|
9
|
+
.data-table { width: 100%; border-collapse: collapse; font-size: var(--text-sm); }
|
|
10
|
+
|
|
11
|
+
/* The header STICKS to the top of the scroll container — which is the container's job, not this
|
|
12
|
+
file's: `position: sticky` resolves against the nearest scrollable ancestor, so in an app-shell
|
|
13
|
+
that's `.app-shell__main` and it works, while in a page that scrolls on <body> it simply never
|
|
14
|
+
engages. That's the parent-context requirement stated in data-table.md; it's opaque (its own
|
|
15
|
+
background) so rows can't show through as they pass under it. */
|
|
16
|
+
.data-table thead th {
|
|
17
|
+
position: sticky; top: 0; z-index: 1;
|
|
18
|
+
text-align: left; font-size: var(--text-xs); font-weight: var(--font-weight-semibold);
|
|
19
|
+
text-transform: uppercase; letter-spacing: 0.05em; color: var(--color-muted);
|
|
20
|
+
padding: var(--space-3) var(--space-4);
|
|
21
|
+
background: var(--color-bg);
|
|
22
|
+
border-bottom: 1px solid var(--color-line);
|
|
23
|
+
}
|
|
24
|
+
.data-table tbody td {
|
|
25
|
+
padding: var(--space-3) var(--space-4); vertical-align: middle;
|
|
26
|
+
color: var(--color-fg); border-bottom: 1px solid var(--color-line);
|
|
27
|
+
}
|
|
28
|
+
/* the last rule would double up with the border of whatever box wraps the table */
|
|
29
|
+
.data-table tbody tr:last-child td { border-bottom: 0; }
|
|
30
|
+
.data-table tbody tr:hover td { background: var(--color-bg); }
|
|
31
|
+
|
|
32
|
+
/* A whole row can be the link to its record. Grain shows the AFFORDANCE only (the cursor); the
|
|
33
|
+
navigation is the consumer's — `data-href` is a plain markup hint, not a vocabulary verb, and
|
|
34
|
+
nothing in grain reads it. Keep a real <a> in the row too: a pointer cursor is not a link, and
|
|
35
|
+
a row that only works on click is unreachable by keyboard. */
|
|
36
|
+
.data-table tbody tr[data-href] { cursor: pointer; }
|
|
37
|
+
.data-table td a { color: var(--color-fg); font-weight: var(--font-weight-semibold); text-decoration: none; }
|
|
38
|
+
.data-table td a:hover { color: var(--color-accent); }
|
|
39
|
+
/* the quiet second line in a cell — an email under a name, a description under a title */
|
|
40
|
+
.data-table__sub { color: var(--color-muted); font-weight: var(--font-weight-regular); }
|
|
41
|
+
/* the empty state is a row, not a replacement for the table: the header stays, so the columns
|
|
42
|
+
still say what WOULD be here once there's data. */
|
|
43
|
+
.data-table__empty td { color: var(--color-muted); text-align: center; padding: var(--space-6); }
|
|
44
|
+
|
|
45
|
+
/* AI / in-transit: dashed terminal edge (the non-text grain idiom, same as `table` and the atoms) */
|
|
46
|
+
.data-table[data-commit="pending"],
|
|
47
|
+
[data-grade="grain"] .data-table { border: 1px dashed var(--ink); }
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Data table
|
|
2
|
+
|
|
3
|
+
A **dense table of records** — the list view of a workspace app: rows you scan and open.
|
|
4
|
+
Uppercase sticky header, tight cells, full-width rules, hover, and an optional
|
|
5
|
+
whole-row link affordance.
|
|
6
|
+
|
|
7
|
+
This is not the `table` molecule. That one is a **content** table (MILL maps Markdown pipe
|
|
8
|
+
tables to it; prose padding, first column flush left) for reading. This one is for working.
|
|
9
|
+
Reaching for the wrong one should be a decision, not an accident — if you are rendering
|
|
10
|
+
Markdown, you want `table`.
|
|
11
|
+
|
|
12
|
+
CSS-only (no `.html`): nothing data-binds it, the rows are yours.
|
|
13
|
+
|
|
14
|
+
**Parent context (optional but load-bearing):** the header only sticks if an **ancestor** is
|
|
15
|
+
the scroll container — `position: sticky` resolves against the nearest scrollable ancestor.
|
|
16
|
+
Inside an `app-shell` that is `.app-shell__main` and it works with no effort. On a page that
|
|
17
|
+
scrolls on `<body>`, or inside a box with no `overflow`, the header simply scrolls away with
|
|
18
|
+
the rows; nothing breaks, but you don't get what the demo shows.
|
|
19
|
+
|
|
20
|
+
## Example
|
|
21
|
+
|
|
22
|
+
```html
|
|
23
|
+
<table class="data-table">
|
|
24
|
+
<thead><tr><th>Name</th><th>Code</th><th>Owner</th></tr></thead>
|
|
25
|
+
<tbody>
|
|
26
|
+
<tr data-href="/clients/acme">
|
|
27
|
+
<td><a href="/clients/acme">Acme Advisory</a><br><span class="data-table__sub">since 2021</span></td>
|
|
28
|
+
<td>acme</td>
|
|
29
|
+
<td><span class="data-table__sub">jane@acme.test</span></td>
|
|
30
|
+
</tr>
|
|
31
|
+
<tr data-href="/clients/borden">
|
|
32
|
+
<td><a href="/clients/borden">Borden & Co</a></td>
|
|
33
|
+
<td>borden</td>
|
|
34
|
+
<td><span class="data-table__sub">ops@borden.test</span></td>
|
|
35
|
+
</tr>
|
|
36
|
+
</tbody>
|
|
37
|
+
</table>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Whole-row links
|
|
41
|
+
|
|
42
|
+
`tr[data-href]` gets the pointer cursor and nothing else. The navigation is yours to wire —
|
|
43
|
+
`data-href` is a plain markup hint, not a vocabulary verb, and no grain script reads it.
|
|
44
|
+
|
|
45
|
+
**Keep a real `<a>` in the row anyway.** A pointer cursor is not a link: a row that only
|
|
46
|
+
responds to a click handler can't be tabbed to, opened in a new tab, or read out as a
|
|
47
|
+
destination. The anchor is the navigation; the row affordance is a convenience over it.
|
|
48
|
+
|
|
49
|
+
## Empty
|
|
50
|
+
|
|
51
|
+
The empty state is a **row**, not a replacement for the table — the header stays, so the
|
|
52
|
+
columns still say what would be here once there is data.
|
|
53
|
+
|
|
54
|
+
```html
|
|
55
|
+
<table class="data-table">
|
|
56
|
+
<thead><tr><th>Name</th><th>Code</th><th>Owner</th></tr></thead>
|
|
57
|
+
<tbody><tr class="data-table__empty"><td colspan="3">No clients yet.</td></tr></tbody>
|
|
58
|
+
</table>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## AI
|
|
62
|
+
|
|
63
|
+
Carries the shared in-transit idiom: `data-commit="pending"` on the table, or a
|
|
64
|
+
`[data-grade="grain"]` ancestor, draws the dashed terminal edge — the same signal the atoms
|
|
65
|
+
and `table` use.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
// grain/components/molecules/data-table/data-table.test.ts — conformance guards for the record
|
|
2
|
+
// table upstreamed from STEWARD (0007).
|
|
3
|
+
//
|
|
4
|
+
// Two of these encode decisions that are easy to undo by accident and expensive to notice:
|
|
5
|
+
// data-table and table are deliberately SEPARATE components (merging them looks like a cleanup
|
|
6
|
+
// and quietly changes what MILL renders), and the sticky header depends on an ancestor scroll
|
|
7
|
+
// container, which is a parent-context requirement the .md must keep stating (lesson 3: a
|
|
8
|
+
// contract that fails silently is the bug).
|
|
9
|
+
import { test, expect } from "bun:test";
|
|
10
|
+
import { readFileSync } from "node:fs";
|
|
11
|
+
import { join } from "node:path";
|
|
12
|
+
|
|
13
|
+
const here = import.meta.dir;
|
|
14
|
+
const root = join(here, "..", "..", "..");
|
|
15
|
+
const css = readFileSync(join(here, "data-table.css"), "utf8");
|
|
16
|
+
const md = readFileSync(join(here, "data-table.md"), "utf8");
|
|
17
|
+
const tableMd = readFileSync(join(root, "components/molecules/table/table.md"), "utf8");
|
|
18
|
+
|
|
19
|
+
test("the header is sticky and opaque — a transparent one lets rows show through as they pass", () => {
|
|
20
|
+
const th = css.match(/\.data-table thead th\s*\{([^}]*)\}/);
|
|
21
|
+
expect(th).not.toBeNull();
|
|
22
|
+
expect(th![1]).toMatch(/position:\s*sticky/);
|
|
23
|
+
expect(th![1]).toMatch(/top:\s*0/);
|
|
24
|
+
expect(th![1]).toMatch(/background:\s*var\(--color-/);
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
test("the sticky header's parent-context requirement is documented, not just implied", () => {
|
|
28
|
+
// it resolves against the nearest scrollable ancestor: silently inert on a body-scrolled page.
|
|
29
|
+
expect(md).toMatch(/scroll(able)? (container|ancestor)/i);
|
|
30
|
+
expect(md).toMatch(/app-shell__main/);
|
|
31
|
+
});
|
|
32
|
+
|
|
33
|
+
test("data-table and table stay two components, each pointing at the other", () => {
|
|
34
|
+
expect(md).toMatch(/\btable\b/);
|
|
35
|
+
expect(md).toMatch(/Markdown/); // "if you're rendering Markdown, you want table"
|
|
36
|
+
expect(tableMd).toMatch(/data-table/); // and the reverse, so neither is a dead end
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
test("a whole-row link ships the affordance only — the anchor is still required", () => {
|
|
40
|
+
expect(css).toMatch(/\.data-table tbody tr\[data-href\]\s*\{\s*cursor:\s*pointer/);
|
|
41
|
+
// grain must not imply it navigates: no grain script reads data-href.
|
|
42
|
+
expect(md).toMatch(/keep a real `?<a>`?/i);
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
test("carries the shared in-transit idiom (dashed edge), like table and the atoms", () => {
|
|
46
|
+
expect(css).toMatch(/\.data-table\[data-commit="pending"\]/);
|
|
47
|
+
expect(css).toMatch(/\[data-grade="grain"\] \.data-table/);
|
|
48
|
+
expect(css).toMatch(/border:\s*1px dashed/);
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
test("the empty state is a row, so the header still names the columns", () => {
|
|
52
|
+
expect(css).toMatch(/\.data-table__empty td/);
|
|
53
|
+
expect(md).toMatch(/<tr class="data-table__empty">/);
|
|
54
|
+
});
|
|
@@ -17,3 +17,15 @@
|
|
|
17
17
|
color: var(--color-fg); background: var(--color-bg); border-color: var(--color-line);
|
|
18
18
|
}
|
|
19
19
|
.nav-item__label { font-size: var(--text-base); }
|
|
20
|
+
/* OPTIONAL trailing count — "how much is in there" beside the label, in the grid's trailing
|
|
21
|
+
column (the same slot the group chevron uses; an item never carries both). Tabular figures so
|
|
22
|
+
the column can't jitter as the number changes, and it follows the item's own state rather than
|
|
23
|
+
staying muted under an active row. The collapsed rail hides it with the labels (side-rail.css,
|
|
24
|
+
which owns every collapsed rule so there's one place to read them). */
|
|
25
|
+
.nav-item__count {
|
|
26
|
+
font-size: var(--text-sm); color: var(--color-muted);
|
|
27
|
+
font-variant-numeric: tabular-nums;
|
|
28
|
+
}
|
|
29
|
+
.nav-item:hover .nav-item__count,
|
|
30
|
+
.nav-item[aria-current="page"] .nav-item__count,
|
|
31
|
+
.nav-item[data-active="true"] .nav-item__count { color: var(--color-fg); }
|
|
@@ -19,3 +19,14 @@ sub-items) indent past the gutter — the side-rail handles that.
|
|
|
19
19
|
<a class="nav-item"><b-icon sym="/assets/sprite.svg#tasks"></b-icon><span class="nav-item__label">Tasks</span></a>
|
|
20
20
|
<a class="nav-item"><b-icon sym="/assets/sprite.svg#rules"></b-icon><span class="nav-item__label">Rules</span></a>
|
|
21
21
|
```
|
|
22
|
+
|
|
23
|
+
### With a count
|
|
24
|
+
A destination can carry how much is waiting in it. The count sits in the grid's trailing
|
|
25
|
+
column — the same slot a group's chevron uses, so an item never carries both — and renders
|
|
26
|
+
in tabular figures so the column doesn't jitter as the number changes. The value is the
|
|
27
|
+
consumer's to keep current; the molecule only styles it.
|
|
28
|
+
|
|
29
|
+
```html
|
|
30
|
+
<a class="nav-item" aria-current="page"><b-icon sym="/assets/sprite.svg#tasks"></b-icon><span class="nav-item__label">Tickets</span><span class="nav-item__count">12</span></a>
|
|
31
|
+
<a class="nav-item"><b-icon sym="/assets/sprite.svg#rules"></b-icon><span class="nav-item__label">Clients</span><span class="nav-item__count">3</span></a>
|
|
32
|
+
```
|
|
@@ -4,6 +4,9 @@ A content data table — MILL maps Markdown pipe tables (`| a | b |` + `|---|---
|
|
|
4
4
|
Ruled and monochrome, not zebra-striped; the `.table-scroll` wrapper keeps wide tables
|
|
5
5
|
scrolling inside their own box. CSS-only: composed by MILL or written by hand.
|
|
6
6
|
|
|
7
|
+
For a **list of records** — a workspace app's rows you scan and open, with a sticky header
|
|
8
|
+
and whole-row links — reach for `data-table` instead. This one is for reading.
|
|
9
|
+
|
|
7
10
|
## Table
|
|
8
11
|
```html
|
|
9
12
|
<div class="table-scroll">
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/* organisms/drawer — a modal side panel: a scrim over the page plus a column that slides in
|
|
2
|
+
from the edge. Where a lightbox (styles/lightbox.css) centers one thing to LOOK at, a drawer
|
|
3
|
+
docks a place to WORK — a create/edit form, a record's detail, a preview — beside the list you
|
|
4
|
+
opened it from, so the context behind it stays visible.
|
|
5
|
+
|
|
6
|
+
CSS-only (no `.html`); the behavior is `grain/scripts/drawer.js` (open/close, Escape, scrim
|
|
7
|
+
click, focus). The visible/hidden state is the plain `hidden` attribute, so a server can ship
|
|
8
|
+
an open drawer and a page with no JS at all still renders a closed one instead of an overlay
|
|
9
|
+
stuck across the screen. */
|
|
10
|
+
.drawer[hidden] { display: none; }
|
|
11
|
+
.drawer { position: fixed; inset: 0; z-index: 60; }
|
|
12
|
+
|
|
13
|
+
/* the scrim: ink receding, the same mechanism as the AI veil — never a raw rgba (tokens only) */
|
|
14
|
+
.drawer__backdrop {
|
|
15
|
+
position: absolute; inset: 0;
|
|
16
|
+
background: color-mix(in srgb, var(--ink) 32%, transparent);
|
|
17
|
+
animation: drawer-fade 0.15s ease;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/* The panel is `min(28rem, 100vw)` — a fixed comfortable column that becomes full-bleed rather
|
|
21
|
+
than overflowing once the viewport is narrower than it. It's a flex column so a long form
|
|
22
|
+
scrolls in the BODY while the head stays put; without that the head scrolls away and there's
|
|
23
|
+
no close button on screen. */
|
|
24
|
+
.drawer__panel {
|
|
25
|
+
position: absolute; inset-block: 0; inset-inline-end: 0;
|
|
26
|
+
width: min(28rem, 100vw);
|
|
27
|
+
display: flex; flex-direction: column; overflow: hidden;
|
|
28
|
+
background: var(--color-surface);
|
|
29
|
+
border-inline-start: 1px solid var(--color-line);
|
|
30
|
+
box-shadow: -12px 0 40px color-mix(in srgb, var(--ink) 22%, transparent);
|
|
31
|
+
animation: drawer-slide 0.18s ease;
|
|
32
|
+
}
|
|
33
|
+
@keyframes drawer-fade { from { opacity: 0; } }
|
|
34
|
+
@keyframes drawer-slide { from { transform: translateX(100%); } }
|
|
35
|
+
@media (prefers-reduced-motion: reduce) {
|
|
36
|
+
.drawer__backdrop, .drawer__panel { animation: none; }
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/* the head aligns with the shell's topbar (same height token) so an open drawer reads as part
|
|
40
|
+
of the same chrome rather than a slab laid over it */
|
|
41
|
+
.drawer__head {
|
|
42
|
+
display: flex; align-items: center; justify-content: space-between; gap: var(--space-3);
|
|
43
|
+
flex: none; min-height: var(--editor-header-h, 2.9rem); padding: 0 var(--space-5);
|
|
44
|
+
border-bottom: 1px solid var(--color-line);
|
|
45
|
+
}
|
|
46
|
+
.drawer__head h2 { margin: 0; font-size: var(--text-lg); font-weight: var(--font-weight-semibold); }
|
|
47
|
+
.drawer__body { flex: 1; min-height: 0; overflow-y: auto; padding: var(--space-5); }
|
|
48
|
+
|
|
49
|
+
/* ---- OPT-IN: `data-side="start"` docks the drawer to the leading edge instead (a filter or
|
|
50
|
+
navigation panel, where the trailing edge is the working one). Only the anchoring and the
|
|
51
|
+
direction of the slide change. ---- */
|
|
52
|
+
.drawer[data-side="start"] .drawer__panel {
|
|
53
|
+
inset-inline: 0 auto;
|
|
54
|
+
border-inline-start: none;
|
|
55
|
+
border-inline-end: 1px solid var(--color-line);
|
|
56
|
+
box-shadow: 12px 0 40px color-mix(in srgb, var(--ink) 22%, transparent);
|
|
57
|
+
animation-name: drawer-slide-start;
|
|
58
|
+
}
|
|
59
|
+
@keyframes drawer-slide-start { from { transform: translateX(-100%); } }
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Drawer
|
|
2
|
+
|
|
3
|
+
A **modal side panel**: a scrim over the page and a column that slides in from the edge.
|
|
4
|
+
Where a lightbox centers one thing to *look* at, a drawer docks a place to *work* — a
|
|
5
|
+
create/edit form, a record's detail, a preview — beside the list you opened it from, so the
|
|
6
|
+
context behind it stays visible.
|
|
7
|
+
|
|
8
|
+
CSS-only (no `.html`). The behavior is `grain/scripts/drawer.js`; load it and the markup
|
|
9
|
+
below is live with no per-page wiring.
|
|
10
|
+
|
|
11
|
+
**State is the plain `hidden` attribute**, not a class. A server can ship an open drawer,
|
|
12
|
+
and a page with no JS at all renders a closed one rather than an overlay stranded across
|
|
13
|
+
the screen.
|
|
14
|
+
|
|
15
|
+
## Markup
|
|
16
|
+
|
|
17
|
+
```html
|
|
18
|
+
<button class="btn" data-drawer-open="new-client">New client</button>
|
|
19
|
+
|
|
20
|
+
<aside class="drawer" id="new-client" data-drawer hidden>
|
|
21
|
+
<div class="drawer__backdrop" data-drawer-close></div>
|
|
22
|
+
<div class="drawer__panel" role="dialog" aria-modal="true" aria-labelledby="new-client-title">
|
|
23
|
+
<header class="drawer__head">
|
|
24
|
+
<h2 id="new-client-title">New client</h2>
|
|
25
|
+
<button class="icon-btn" data-variant="ghost" data-drawer-close aria-label="Close">✕</button>
|
|
26
|
+
</header>
|
|
27
|
+
<div class="drawer__body">…a form…</div>
|
|
28
|
+
</div>
|
|
29
|
+
</aside>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`data-drawer-open` names the drawer's id; with no value it opens the page's only
|
|
33
|
+
`[data-drawer]`. Anything marked `data-drawer-close` closes it — the scrim carries it, and so
|
|
34
|
+
should a close button in the head. The close control is a plain grain `.icon-btn`, not a
|
|
35
|
+
drawer-specific class; the organism owns the panel, not the button.
|
|
36
|
+
|
|
37
|
+
The catalog renders this example as an empty panel on purpose: the drawer is
|
|
38
|
+
`position: fixed`, so a live one would cover the whole catalog rather than sit in its box.
|
|
39
|
+
Read the code, or see it in a shell.
|
|
40
|
+
|
|
41
|
+
## What the script does that a hand-rolled drawer usually doesn't
|
|
42
|
+
|
|
43
|
+
A drawer is modal, and three obligations come with covering the page. `drawer.js` ships all
|
|
44
|
+
three so no consumer has to remember them:
|
|
45
|
+
|
|
46
|
+
- **Focus moves in** on open — to the first control in the panel, or the panel itself.
|
|
47
|
+
- **Tab stays inside** while it's up, wrapping at both ends, and the rest of the page goes
|
|
48
|
+
`inert` (one attribute that stops focus, pointer events and screen-reader attention alike —
|
|
49
|
+
the `aria-hidden` + `tabindex` dance it replaces never stopped a click).
|
|
50
|
+
- **Focus returns** to the control that opened it on close. Dropping focus to `<body>` leaves
|
|
51
|
+
a keyboard user at the top of the page with no idea where they were.
|
|
52
|
+
|
|
53
|
+
Escape and a scrim click both close. Only one drawer is ever open; opening a second closes
|
|
54
|
+
the first.
|
|
55
|
+
|
|
56
|
+
**Seam:** `window.grain.drawer` — `{ open(idOrElement), close(), current() }`. The element
|
|
57
|
+
also emits `grain:drawer-open` / `grain:drawer-close` (bubbling), which is where a consumer
|
|
58
|
+
hangs its own work: loading a fragment into `.drawer__body`, resetting a form, saving a
|
|
59
|
+
draft.
|
|
60
|
+
|
|
61
|
+
## Docking to the other edge
|
|
62
|
+
|
|
63
|
+
`data-side="start"` puts the panel on the leading edge instead — a filter or navigation
|
|
64
|
+
panel, where the trailing edge is the working one. Only the anchoring and the slide
|
|
65
|
+
direction change.
|
|
66
|
+
|
|
67
|
+
```html
|
|
68
|
+
<aside class="drawer" data-side="start" data-drawer hidden>…</aside>
|
|
69
|
+
```
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
// grain/components/organisms/drawer/drawer.test.ts — conformance guards for the drawer's CSS
|
|
2
|
+
// contract (its behavior is guarded in scripts/drawer.test.ts).
|
|
3
|
+
import { test, expect } from "bun:test";
|
|
4
|
+
import { readFileSync } from "node:fs";
|
|
5
|
+
import { join } from "node:path";
|
|
6
|
+
|
|
7
|
+
const here = import.meta.dir;
|
|
8
|
+
const css = readFileSync(join(here, "drawer.css"), "utf8");
|
|
9
|
+
const md = readFileSync(join(here, "drawer.md"), "utf8");
|
|
10
|
+
|
|
11
|
+
test("closed is the `hidden` attribute — a no-JS page must not get a stranded overlay", () => {
|
|
12
|
+
expect(css).toMatch(/\.drawer\[hidden\]\s*\{\s*display:\s*none/);
|
|
13
|
+
});
|
|
14
|
+
|
|
15
|
+
test("the panel is a flex column so the BODY scrolls and the head (with its close button) stays", () => {
|
|
16
|
+
const panel = css.match(/\.drawer__panel\s*\{([^}]*)\}/);
|
|
17
|
+
expect(panel).not.toBeNull();
|
|
18
|
+
expect(panel![1]).toMatch(/display:\s*flex/);
|
|
19
|
+
expect(panel![1]).toMatch(/flex-direction:\s*column/);
|
|
20
|
+
expect(css).toMatch(/\.drawer__head\s*\{[^}]*flex:\s*none/);
|
|
21
|
+
expect(css).toMatch(/\.drawer__body\s*\{[^}]*overflow-y:\s*auto/);
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
test("the panel goes full-bleed rather than overflowing a narrow viewport", () => {
|
|
25
|
+
expect(css).toMatch(/width:\s*min\([\d.]+rem,\s*100vw\)/);
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
test("both animations opt out under prefers-reduced-motion", () => {
|
|
29
|
+
const block = css.match(/@media \(prefers-reduced-motion: reduce\)\s*\{([^}]*)\}/);
|
|
30
|
+
expect(block).not.toBeNull();
|
|
31
|
+
expect(block![1]).toMatch(/\.drawer__backdrop/);
|
|
32
|
+
expect(block![1]).toMatch(/\.drawer__panel/);
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
test("the close control is a plain grain icon-btn — the organism owns the panel, not the button", () => {
|
|
36
|
+
expect(css).not.toMatch(/\.drawer__close/);
|
|
37
|
+
expect(md).toMatch(/class="icon-btn"[^>]*data-drawer-close/);
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
test("the .md states why the catalog renders this one empty (a fixed overlay can't sit in a panel)", () => {
|
|
41
|
+
expect(md).toMatch(/position: fixed/);
|
|
42
|
+
expect(md).toMatch(/catalog/i);
|
|
43
|
+
});
|
|
@@ -29,6 +29,40 @@
|
|
|
29
29
|
.side-rail__brand > b-icon { color: var(--color-accent); }
|
|
30
30
|
.side-rail__spacer { flex: 1 1 auto; }
|
|
31
31
|
|
|
32
|
+
/* ---- OPTIONAL: a section heading between runs of items — for a rail with more destinations
|
|
33
|
+
than a flat list reads well as. Not a `__group` (that's a collapsible <details>); this only
|
|
34
|
+
separates. Indented past the gutter so it aligns with the LABELS, not the glyph column. ---- */
|
|
35
|
+
.side-rail__label {
|
|
36
|
+
padding: var(--space-4) 0 var(--space-1) calc(var(--rail-icon-col, 2.5rem) + var(--space-2));
|
|
37
|
+
font-size: var(--text-xs); text-transform: uppercase; letter-spacing: 0.06em;
|
|
38
|
+
color: var(--color-muted); white-space: nowrap;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/* ---- OPTIONAL: the foot — a mark plus two lines of identity, pinned under the spacer. Grain
|
|
42
|
+
ships the SHAPE only; who it names (an account, a workspace, "signed out") is the consumer's,
|
|
43
|
+
like the topbar's presence label. Same two-column grid as the brand, so the mark lands in the
|
|
44
|
+
gutter and the text lines up with every label above it. ---- */
|
|
45
|
+
.side-rail__foot {
|
|
46
|
+
display: grid; grid-template-columns: var(--rail-icon-col, 2.5rem) 1fr;
|
|
47
|
+
align-items: center; column-gap: var(--space-2);
|
|
48
|
+
margin-top: var(--space-2); padding-top: var(--space-3);
|
|
49
|
+
border-top: 1px solid var(--color-line); white-space: nowrap;
|
|
50
|
+
}
|
|
51
|
+
.side-rail__avatar {
|
|
52
|
+
width: 1.75rem; height: 1.75rem; border-radius: 50%; justify-self: center;
|
|
53
|
+
display: grid; place-items: center;
|
|
54
|
+
background: var(--color-accent-soft); color: var(--color-accent);
|
|
55
|
+
font-size: var(--text-xs); font-weight: var(--font-weight-semibold);
|
|
56
|
+
}
|
|
57
|
+
.side-rail__foot > b-icon, .side-rail__foot > .icon { justify-self: center; }
|
|
58
|
+
/* min-width:0 lets the ellipsis below actually fire — a grid item's default `auto` minimum
|
|
59
|
+
would let a long account name push the rail wider instead of truncating. */
|
|
60
|
+
.side-rail__who { min-width: 0; font-size: var(--text-xs); color: var(--color-muted); line-height: 1.2; }
|
|
61
|
+
.side-rail__who strong {
|
|
62
|
+
display: block; overflow: hidden; text-overflow: ellipsis;
|
|
63
|
+
font-size: var(--text-sm); font-weight: var(--font-weight-semibold); color: var(--color-fg);
|
|
64
|
+
}
|
|
65
|
+
|
|
32
66
|
/* ---- grouped nav — a collapsible section for nested navigation (e.g. a BREAD group over
|
|
33
67
|
BATCH / GRAIN / MILL). Native <details>/<summary>, no JS: the summary IS a nav-item, the
|
|
34
68
|
sub-items indent under it. Open/closed is the browser's; a rotating chevron shows state. ---- */
|
|
@@ -53,3 +87,9 @@
|
|
|
53
87
|
[data-rail-collapsed="true"] .side-rail__brand { grid-template-columns: var(--rail-icon-col, 2.5rem); }
|
|
54
88
|
[data-rail-collapsed="true"] .side-rail__group > summary .nav-item__chev { display: none; }
|
|
55
89
|
[data-rail-collapsed="true"] .side-rail__sub .nav-item { padding-left: 0; }
|
|
90
|
+
/* the optional pieces collapse the same way: text goes, glyphs stay. A section label is ONLY
|
|
91
|
+
text, so it goes entirely; the foot keeps its mark (the one thing still legible at 3.25rem). */
|
|
92
|
+
[data-rail-collapsed="true"] .side-rail__label { display: none; }
|
|
93
|
+
[data-rail-collapsed="true"] .side-rail__who { display: none; }
|
|
94
|
+
[data-rail-collapsed="true"] .nav-item__count { display: none; }
|
|
95
|
+
[data-rail-collapsed="true"] .side-rail__foot { grid-template-columns: var(--rail-icon-col, 2.5rem); }
|
|
@@ -22,3 +22,33 @@ icon column (see `activity-bar.md`).
|
|
|
22
22
|
<a class="nav-item"><b-icon sym="/assets/sprite.svg#settings"></b-icon><span class="nav-item__label">Settings</span></a>
|
|
23
23
|
</aside>
|
|
24
24
|
```
|
|
25
|
+
|
|
26
|
+
## Grouped, counted, and signed
|
|
27
|
+
|
|
28
|
+
Three optional pieces for a rail with more in it than a handful of destinations — a workspace
|
|
29
|
+
app rather than a site. All three collapse with the rail: the label goes entirely, the counts
|
|
30
|
+
go with the nav-item labels, and the foot keeps its mark and drops its text.
|
|
31
|
+
|
|
32
|
+
- `.side-rail__label` — a section heading between runs of items. Not a `.side-rail__group`
|
|
33
|
+
(that's a collapsible `<details>`); this only separates.
|
|
34
|
+
- `.nav-item__count` — how much is waiting in a destination (see `nav-item.md`). The value is
|
|
35
|
+
the consumer's to keep current.
|
|
36
|
+
- `.side-rail__foot` — a mark plus two lines of identity, pinned under the spacer.
|
|
37
|
+
**Persona-neutral:** grain ships the shape; who it names — an account, a workspace,
|
|
38
|
+
"signed out" — is the consumer's, exactly like the topbar's presence label.
|
|
39
|
+
|
|
40
|
+
```html
|
|
41
|
+
<aside class="side-rail" style="height:280px;border:1px solid var(--color-line)">
|
|
42
|
+
<div class="side-rail__brand"><b-icon sym="/assets/sprite.svg#spark"></b-icon><span>Grain</span></div>
|
|
43
|
+
<a class="nav-item"><b-icon sym="/assets/sprite.svg#loop"></b-icon><span class="nav-item__label">Home</span></a>
|
|
44
|
+
<span class="side-rail__label">Workspace</span>
|
|
45
|
+
<a class="nav-item" aria-current="page"><b-icon sym="/assets/sprite.svg#tasks"></b-icon><span class="nav-item__label">Tickets</span><span class="nav-item__count">12</span></a>
|
|
46
|
+
<a class="nav-item"><b-icon sym="/assets/sprite.svg#knowledge"></b-icon><span class="nav-item__label">Clients</span><span class="nav-item__count">3</span></a>
|
|
47
|
+
<div class="side-rail__spacer"></div>
|
|
48
|
+
<a class="nav-item"><b-icon sym="/assets/sprite.svg#settings"></b-icon><span class="nav-item__label">Settings</span></a>
|
|
49
|
+
<div class="side-rail__foot">
|
|
50
|
+
<span class="side-rail__avatar">TS</span>
|
|
51
|
+
<span class="side-rail__who"><strong>Local workspace</strong>no account</span>
|
|
52
|
+
</div>
|
|
53
|
+
</aside>
|
|
54
|
+
```
|
|
@@ -6,3 +6,33 @@
|
|
|
6
6
|
brand/presence text. See topbar.md. */
|
|
7
7
|
.topbar-ctl { display: flex; align-items: center; gap: var(--space-3); margin-left: auto; padding: 0 var(--space-4); }
|
|
8
8
|
.presence { display: inline-flex; align-items: center; gap: 0.35rem; color: var(--color-muted); font-size: var(--text-sm); }
|
|
9
|
+
|
|
10
|
+
/* ---- the LEFT slot: WHERE you are (a breadcrumb trail, a record title). Pairs with
|
|
11
|
+
`.topbar-ctl`'s `margin-left: auto` with no change to it — put both in the region and the
|
|
12
|
+
crumbs sit left, the controls right. `min-width: 0` so a long trail truncates instead of
|
|
13
|
+
pushing the control cluster off the bar. ---- */
|
|
14
|
+
.topbar-crumbs {
|
|
15
|
+
display: flex; align-items: center; gap: var(--space-2); min-width: 0;
|
|
16
|
+
padding: 0 var(--space-4); font-size: var(--text-sm); color: var(--color-muted);
|
|
17
|
+
}
|
|
18
|
+
.topbar-crumbs strong { color: var(--color-fg); font-weight: var(--font-weight-semibold); }
|
|
19
|
+
.topbar-crumbs a { color: var(--color-muted); }
|
|
20
|
+
.topbar-crumbs a:hover { color: var(--color-fg); }
|
|
21
|
+
|
|
22
|
+
/* ---- a search / filter box for the bar. GRAIN SHIPS THE BOX AND NOTHING ELSE: whether typing
|
|
23
|
+
in it filters rows on the page, queries a server, or opens a palette is the consumer's, wired
|
|
24
|
+
to the input. That split is deliberate — a component that LOOKS like it searches but ships no
|
|
25
|
+
search is a contract that fails silently (CLAUDE.md lesson 3), so the promise here is only
|
|
26
|
+
"an input that belongs in a topbar". ---- */
|
|
27
|
+
.topbar-search { position: relative; flex: 1 1 auto; max-width: 22rem; align-self: center; }
|
|
28
|
+
.topbar-search input {
|
|
29
|
+
width: 100%; font: inherit; font-size: var(--text-sm);
|
|
30
|
+
padding: var(--space-2) var(--space-3) var(--space-2) 1.9rem;
|
|
31
|
+
border: 1px solid var(--color-line); border-radius: var(--radius-md);
|
|
32
|
+
background: var(--color-bg); color: var(--color-fg);
|
|
33
|
+
}
|
|
34
|
+
.topbar-search input:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 1px; }
|
|
35
|
+
.topbar-search::before {
|
|
36
|
+
content: "⌕"; position: absolute; left: var(--space-2); top: 50%; transform: translateY(-50%);
|
|
37
|
+
color: var(--color-muted); pointer-events: none;
|
|
38
|
+
}
|
|
@@ -24,3 +24,25 @@ CSS-only (no `.html`): compose the markup in your frame.
|
|
|
24
24
|
|
|
25
25
|
Persona-neutral: the presence label ("online", a product name, "Acme's assistant") is the consumer's — the
|
|
26
26
|
primitive ships no persona. The flavor list the cycle rotates is declared on `<html data-themes="…">`.
|
|
27
|
+
|
|
28
|
+
## The left slot, and a search box
|
|
29
|
+
|
|
30
|
+
A workspace bar usually says **where you are** on the left and **what you can do here** on the
|
|
31
|
+
right. `.topbar-crumbs` is that left slot; it needs no coordination with `.topbar-ctl`, which
|
|
32
|
+
pushes itself right on its own. A long trail truncates rather than shoving the controls off
|
|
33
|
+
the bar.
|
|
34
|
+
|
|
35
|
+
`.topbar-search` is the optional box between them. **Grain ships the box and nothing else** —
|
|
36
|
+
whether typing filters rows already on the page, queries a server, or opens a palette is yours
|
|
37
|
+
to wire to the input. A box that looks like it searches but ships no search is a contract that
|
|
38
|
+
fails silently, so the promise here is only "an input that belongs in a topbar".
|
|
39
|
+
|
|
40
|
+
```html
|
|
41
|
+
<header class="app-shell__topbar">
|
|
42
|
+
<span class="topbar-crumbs"><a href="/tickets">Tickets</a> / <strong>Annual Review</strong></span>
|
|
43
|
+
<div class="topbar-search"><input type="search" placeholder="Filter…" aria-label="Filter"></div>
|
|
44
|
+
<div class="topbar-ctl">
|
|
45
|
+
<button class="icon-btn" data-variant="ghost" data-toggle-scheme aria-label="Toggle light / dark">◐</button>
|
|
46
|
+
</div>
|
|
47
|
+
</header>
|
|
48
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tjakoen/grain",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.13",
|
|
4
4
|
"description": "GRAIN — an AI-interaction design system where every surface is operable by both a human and an AI through one shared vocabulary.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
// grain/scripts/drawer.js — the drawer organism's behavior: open, close, and the modal
|
|
2
|
+
// obligations that come with covering the page.
|
|
3
|
+
//
|
|
4
|
+
// A drawer is a MODAL overlay, and the three things that make one usable are the three every
|
|
5
|
+
// hand-rolled implementation skips: focus goes INTO it on open, Tab stays inside while it's up,
|
|
6
|
+
// and focus comes BACK to the control that opened it on close. Ship those here so no consumer has
|
|
7
|
+
// to remember them — the drawer that scrolls a form under a scrim while the page behind it still
|
|
8
|
+
// takes Tab is the failure mode this file exists to prevent.
|
|
9
|
+
//
|
|
10
|
+
// The visible state is the plain `hidden` attribute, so a server can render an open drawer and a
|
|
11
|
+
// page with no JS renders a closed one (never an overlay stranded across the screen). Delegated
|
|
12
|
+
// off document, so markup swapped in later — a fragment loaded into the body, a re-rendered
|
|
13
|
+
// list — is wired with no re-init. Pure UI chrome: it knows nothing about the AI door.
|
|
14
|
+
//
|
|
15
|
+
// OPT-IN markup:
|
|
16
|
+
// <button data-drawer-open="my-drawer">New</button> // value = the drawer's id
|
|
17
|
+
// <aside class="drawer" id="my-drawer" data-drawer hidden>
|
|
18
|
+
// <div class="drawer__backdrop" data-drawer-close></div>
|
|
19
|
+
// <div class="drawer__panel" role="dialog" aria-modal="true" aria-labelledby="my-drawer-t">
|
|
20
|
+
// <header class="drawer__head"><h2 id="my-drawer-t">New</h2>
|
|
21
|
+
// <button class="icon-btn" data-drawer-close aria-label="Close">✕</button></header>
|
|
22
|
+
// <div class="drawer__body">…</div>
|
|
23
|
+
// </div>
|
|
24
|
+
// </aside>
|
|
25
|
+
// A `data-drawer-open` with no value opens the page's only `[data-drawer]`.
|
|
26
|
+
(() => {
|
|
27
|
+
"use strict";
|
|
28
|
+
if (window.grain && window.grain.drawer) return; // idempotent
|
|
29
|
+
|
|
30
|
+
// what can hold focus inside the panel — the Tab cycle's endpoints come from this list
|
|
31
|
+
const FOCUSABLE = [
|
|
32
|
+
"a[href]", "button:not([disabled])", "input:not([disabled])", "select:not([disabled])",
|
|
33
|
+
"textarea:not([disabled])", "[tabindex]:not([tabindex='-1'])",
|
|
34
|
+
].join(",");
|
|
35
|
+
|
|
36
|
+
let openEl = null; // the drawer currently up (only ever one)
|
|
37
|
+
let opener = null; // the control that opened it, to hand focus back to
|
|
38
|
+
let inerted = []; // the body children we made inert, to undo exactly
|
|
39
|
+
|
|
40
|
+
const panelOf = (d) => d.querySelector(".drawer__panel") || d;
|
|
41
|
+
const focusables = (d) => [...panelOf(d).querySelectorAll(FOCUSABLE)]
|
|
42
|
+
.filter((el) => el.offsetParent !== null || el === document.activeElement);
|
|
43
|
+
|
|
44
|
+
const find = (id) => (id ? document.getElementById(id) : document.querySelector("[data-drawer]"));
|
|
45
|
+
|
|
46
|
+
function open(target, from) {
|
|
47
|
+
const d = typeof target === "string" ? find(target) : target;
|
|
48
|
+
if (!d || d === openEl) return null;
|
|
49
|
+
if (openEl) close(); // never stack drawers
|
|
50
|
+
openEl = d;
|
|
51
|
+
opener = from || (document.activeElement instanceof HTMLElement ? document.activeElement : null);
|
|
52
|
+
d.removeAttribute("hidden");
|
|
53
|
+
|
|
54
|
+
// everything else on the page stops taking focus, pointer events and AT attention. `inert`
|
|
55
|
+
// is one attribute that does all three — the aria-hidden + tabindex dance it replaces was
|
|
56
|
+
// always partial (it never stopped a click reaching what it hid).
|
|
57
|
+
inerted = [...document.body.children].filter((c) => c !== d && !c.hasAttribute("inert"));
|
|
58
|
+
for (const c of inerted) c.setAttribute("inert", "");
|
|
59
|
+
|
|
60
|
+
// focus the first real control, else the panel itself (a body of prose still needs to
|
|
61
|
+
// receive Escape and be where the screen reader lands).
|
|
62
|
+
const first = focusables(d)[0];
|
|
63
|
+
if (first) first.focus();
|
|
64
|
+
else {
|
|
65
|
+
const p = panelOf(d);
|
|
66
|
+
if (!p.hasAttribute("tabindex")) p.setAttribute("tabindex", "-1");
|
|
67
|
+
p.focus();
|
|
68
|
+
}
|
|
69
|
+
d.dispatchEvent(new CustomEvent("grain:drawer-open", { bubbles: true }));
|
|
70
|
+
return d;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function close() {
|
|
74
|
+
const d = openEl;
|
|
75
|
+
if (!d) return null;
|
|
76
|
+
openEl = null;
|
|
77
|
+
d.setAttribute("hidden", "");
|
|
78
|
+
for (const c of inerted) c.removeAttribute("inert");
|
|
79
|
+
inerted = [];
|
|
80
|
+
// hand focus back to whatever opened it — losing it to <body> drops a keyboard user at the
|
|
81
|
+
// top of the page with no idea where they were.
|
|
82
|
+
if (opener && opener.isConnected) opener.focus();
|
|
83
|
+
opener = null;
|
|
84
|
+
d.dispatchEvent(new CustomEvent("grain:drawer-close", { bubbles: true }));
|
|
85
|
+
return d;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
document.addEventListener("click", (e) => {
|
|
89
|
+
const t = e.target instanceof Element ? e.target : null;
|
|
90
|
+
if (!t) return;
|
|
91
|
+
const closer = t.closest("[data-drawer-close]");
|
|
92
|
+
if (closer) { e.preventDefault(); close(); return; }
|
|
93
|
+
const btn = t.closest("[data-drawer-open]");
|
|
94
|
+
if (btn) { e.preventDefault(); open(btn.getAttribute("data-drawer-open"), btn); }
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
document.addEventListener("keydown", (e) => {
|
|
98
|
+
if (!openEl) return;
|
|
99
|
+
if (e.key === "Escape") { e.preventDefault(); close(); return; }
|
|
100
|
+
if (e.key !== "Tab") return;
|
|
101
|
+
// the trap: wrap at the ends rather than letting Tab walk out behind the scrim. `inert` above
|
|
102
|
+
// already blocks the page, but the browser chrome/address bar is still in the cycle without
|
|
103
|
+
// this, and Shift+Tab off the first control would leave the panel entirely.
|
|
104
|
+
const items = focusables(openEl);
|
|
105
|
+
if (!items.length) { e.preventDefault(); return; }
|
|
106
|
+
const first = items[0], last = items[items.length - 1];
|
|
107
|
+
if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
|
|
108
|
+
else if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
window.grain = window.grain || {};
|
|
112
|
+
window.grain.drawer = { open, close, current: () => openEl };
|
|
113
|
+
})();
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
// grain/scripts/drawer.test.ts — DRIFT GUARD for the drawer island.
|
|
2
|
+
//
|
|
3
|
+
// Scope, stated honestly: this package has no DOM in test (zero runtime deps, and a hand-rolled
|
|
4
|
+
// fake would test the fake). So these are grep-style contract guards in the tabs.test.ts mould —
|
|
5
|
+
// they catch a modal obligation being DELETED, which is the realistic regression, not one being
|
|
6
|
+
// subtly wrong. The behavior itself (focus lands in the panel, Tab wraps, focus returns to the
|
|
7
|
+
// opener) is asserted in a browser against a consumer — see plans/0007 in STEWARD. Lesson 9 cuts
|
|
8
|
+
// both ways: don't claim a behavior a mechanism can't render, and don't claim a test proves more
|
|
9
|
+
// than it does.
|
|
10
|
+
import { test, expect } from "bun:test";
|
|
11
|
+
import { readFileSync } from "node:fs";
|
|
12
|
+
import { join } from "node:path";
|
|
13
|
+
|
|
14
|
+
const js = readFileSync(join(import.meta.dir, "drawer.js"), "utf8");
|
|
15
|
+
const md = readFileSync(join(import.meta.dir, "..", "components/organisms/drawer/drawer.md"), "utf8");
|
|
16
|
+
|
|
17
|
+
test("idempotent, like every grain island", () => {
|
|
18
|
+
expect(js).toMatch(/if \(window\.grain && window\.grain\.drawer\) return/);
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
test("state is the `hidden` attribute, not a class — SSR ships it, no-JS renders it closed", () => {
|
|
22
|
+
expect(js).toMatch(/removeAttribute\("hidden"\)/);
|
|
23
|
+
expect(js).toMatch(/setAttribute\("hidden", ""\)/);
|
|
24
|
+
expect(js).not.toMatch(/classList\.(add|remove)\("(is-)?open"\)/);
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
test("focus moves INTO the panel on open", () => {
|
|
28
|
+
expect(js).toMatch(/focusables\(d\)\[0\]/);
|
|
29
|
+
expect(js).toMatch(/first\.focus\(\)/);
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
test("focus RETURNS to the opener on close — never dropped to <body>", () => {
|
|
33
|
+
expect(js).toMatch(/opener = from \|\| /);
|
|
34
|
+
expect(js).toMatch(/if \(opener && opener\.isConnected\) opener\.focus\(\)/);
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
test("Tab is trapped inside the panel, wrapping at BOTH ends", () => {
|
|
38
|
+
expect(js).toMatch(/e\.key !== "Tab"/);
|
|
39
|
+
expect(js).toMatch(/!e\.shiftKey && document\.activeElement === last/);
|
|
40
|
+
expect(js).toMatch(/e\.shiftKey && document\.activeElement === first/);
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
test("the rest of the page goes inert while open, and is restored exactly", () => {
|
|
44
|
+
expect(js).toMatch(/setAttribute\("inert", ""\)/);
|
|
45
|
+
expect(js).toMatch(/removeAttribute\("inert"\)/);
|
|
46
|
+
// only the children WE inerted are un-inerted — a page that inerts something itself keeps it.
|
|
47
|
+
expect(js).toMatch(/!c\.hasAttribute\("inert"\)/);
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
test("Escape and the scrim both close", () => {
|
|
51
|
+
expect(js).toMatch(/e\.key === "Escape"/);
|
|
52
|
+
expect(js).toMatch(/\[data-drawer-close\]/);
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
test("never stacks: opening a second drawer closes the first", () => {
|
|
56
|
+
expect(js).toMatch(/if \(openEl\) close\(\)/);
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
test("delegated off document, so swapped-in markup needs no re-init", () => {
|
|
60
|
+
expect(js).toMatch(/document\.addEventListener\("click"/);
|
|
61
|
+
expect(js).toMatch(/document\.addEventListener\("keydown"/);
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
test("exposes the window.grain.drawer seam and the open/close events the .md promises", () => {
|
|
65
|
+
expect(js).toMatch(/window\.grain\.drawer\s*=\s*\{[\s\S]*\bopen\b[\s\S]*\bclose\b/);
|
|
66
|
+
expect(js).toMatch(/grain:drawer-open/);
|
|
67
|
+
expect(js).toMatch(/grain:drawer-close/);
|
|
68
|
+
expect(md).toMatch(/grain:drawer-open/);
|
|
69
|
+
expect(md).toMatch(/window\.grain\.drawer/);
|
|
70
|
+
});
|