@tjakoen/grain 0.1.12 → 0.1.14
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 +9 -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/presentation/presentation.css +265 -0
- package/components/organisms/presentation/presentation.md +128 -0
- package/components/organisms/presentation/presentation.test.ts +75 -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/scripts/presentation.js +315 -0
- package/scripts/presentation.test.ts +77 -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,15 @@ 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/presentation.js`** + the `presentation` organism: a deck. Slides, staged fragments, a
|
|
185
|
+
fit-to-box pass so a dense slide scales instead of overflowing, an overview grid, present mode, a
|
|
186
|
+
synced presenter window, and a print sheet. Opt in with `data-deck`. It owns which slide is up and
|
|
187
|
+
how far into it you are, and nothing else: an app hangs its own figures off one event,
|
|
188
|
+
`presentation:slide`.
|
|
189
|
+
- **`scripts/drawer.js`** + the `drawer` organism: the modal side panel. `[data-drawer-open="id"]`
|
|
190
|
+
opens, `[data-drawer-close]` (the scrim carries it) closes, and the script owns the modal
|
|
191
|
+
obligations — focus into the panel, Tab trapped, the rest of the page `inert`, focus returned to
|
|
192
|
+
the opener. Open/closed is the plain `hidden` attribute, so a server can ship it either way.
|
|
184
193
|
|
|
185
194
|
---
|
|
186
195
|
|
|
@@ -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
|
+
});
|