Skip to content

Commit 25cd935

Browse files
EricAndrechekclaude
andcommitted
feat(docs): earned breakout, fit-first zoom, format tabs, SDK runtimes
Third response round to PR-review feedback: - Tables EARN breakout: a table whose prose wraps comfortably at 45rem stays at prose width; only overflow-or-crowd tables take the wide track, capped 2.5rem short of the rails. Diagram scrollers get an explicit min(natural, pane) width — fit-content can't measure a width:100% SVG child, which pinned wide diagrams at prose width while small ones stayed natural. Footer (edit/updated/prev-next) holds prose width. - Edge fades: threshold 3px -> 8px (DPR rounding painted "more to scroll" on blocks with nothing to scroll); left-edge fade added when scrolled right (the right-only mask read as amputated content). - Zoom modal always FITS (no scrollbars, corners intact); a 1:1 toggle appears for larger-than-stage diagrams (natural size + pan + fades); every inline diagram carries a persistent dimmed corner zoom chip. - configuration + access-control converted to .mdx: example config is YAML/Environment synced tabs (WH_* names verified against internal/config/config.go; config file is YAML-only by struct tags), complete policy example is YAML/JSON tabs (JSON twin machine-verified equal). File-representing code frames gain title= headers; all frames show a quiet bottom-right language badge. - SDK overview gains Imports & Runtimes: import-line tabs synced to the pkg choice (CDN reader sees esm.sh imports incl. a fully-tabbed Quick Start), Node CJS + WaveHouse IIFE global documented from the shipped exports map, runtime note verified empirically (EventSource global still flag-gated in Node 26 -> polyfill required for streaming). - Bare issue refs in prose became links (#97/#223/#224/#279); mobile icon-only search trigger joins the circular control family; external sidebar links carry an arrow marker. Verified: 19 pages x 8 widths (320-2560) x both themes — zero page or element overflow; zoom fit sw==cw both axes; 1:1 pan shows both edge fades; YAML/JSON policy twin parsed equal; every env var in the tab exists in config.go. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 0ee4cd0 commit 25cd935

16 files changed

Lines changed: 798 additions & 307 deletions

‎CHANGELOG.md‎

Lines changed: 4 additions & 3 deletions
Large diffs are not rendered by default.

‎docs/src/components/MermaidZoom.astro‎

Lines changed: 66 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
---
2-
// Click-to-zoom for Mermaid diagrams. Diagrams render inside the ~46–58rem
3-
// content column, so wide ones (and dense ones) read small inline; clicking
4-
// any diagram opens it in a lightbox — small diagrams scale up to fill the
5-
// viewport, wide ones show at natural size with pan-scroll for full detail.
2+
// Click-to-zoom for Mermaid diagrams. Dense diagrams read small inline;
3+
// clicking any diagram opens it in a lightbox that always FITS the viewport
4+
// (small diagrams scale up, capped 2.5×; oversized ones scale down — never
5+
// scrollbars by default). Diagrams larger than the stage also get a 1:1
6+
// toggle: natural size with pan + edge fades, for full label detail.
67
//
78
// Rendered once (from Footer.astro, which is on every page). The script uses
89
// event delegation on `document` so it survives Astro view-transition
@@ -42,12 +43,19 @@
4243
overlay.setAttribute("aria-modal", "true");
4344
overlay.setAttribute("aria-label", "Enlarged diagram");
4445
overlay.innerHTML =
46+
'<button class="wh-zoom__one" type="button" hidden aria-pressed="false" ' +
47+
'aria-label="Toggle natural size (pan to explore)">1:1</button>' +
4548
'<button class="wh-zoom__close" type="button" aria-label="Close enlarged diagram">' +
4649
'<svg viewBox="0 0 24 24" width="22" height="22" aria-hidden="true" fill="none" ' +
4750
'stroke="currentColor" stroke-width="2" stroke-linecap="round">' +
4851
'<path d="M6 6l12 12M18 6L6 18"/></svg></button>' +
4952
'<div class="wh-zoom__stage"></div>';
5053
overlay.addEventListener("click", (e) => {
54+
if (e.target.closest(".wh-zoom__one")) {
55+
const btn = e.target.closest(".wh-zoom__one");
56+
if (overlay.__whSetMode) overlay.__whSetMode(btn.getAttribute("aria-pressed") !== "true");
57+
return;
58+
}
5159
// Backdrop / stage padding click closes; clicks on the SVG itself don't.
5260
if (!e.target.closest("svg") || e.target.closest(".wh-zoom__close")) close();
5361
});
@@ -88,26 +96,43 @@
8896
(window.innerWidth * 0.94 - padX) / natW,
8997
(window.innerHeight * 0.9 - padY) / natH,
9098
);
91-
// Enlarge diagrams smaller than the viewport (cap 2.5×); show larger
92-
// ones at natural size and let the stage scroll for pan. Floor the
93-
// pixel sizes so fractional rounding can't tip a perfect fit into a
94-
// 1px overflow (which renders as phantom scrollbars).
95-
const scale = fit > 1 ? Math.min(fit, 2.5) : 1;
96-
clone.style.width = Math.floor(natW * scale) + "px";
97-
clone.style.height = Math.floor(natH * scale) + "px";
99+
// The modal ALWAYS fits the diagram to the stage — scaling UP small
100+
// diagrams (cap 2.5×) and DOWN oversized ones — so the default view
101+
// never grows scrollbars (which also squared the sheet's rounded
102+
// corners). Diagrams larger than the stage get a 1:1 toggle instead:
103+
// natural size + pan, with the ScrollHints edge fades as the wayfinding
104+
// (pinch-zoom also works natively on touch). Floor the pixel sizes so
105+
// fractional rounding can't tip a perfect fit into a 1px overflow.
106+
const fitScale = Math.min(fit, 2.5);
107+
const sizeTo = (scale) => {
108+
clone.style.width = Math.floor(natW * scale) + "px";
109+
clone.style.height = Math.floor(natH * scale) + "px";
110+
};
111+
sizeTo(fitScale);
98112
clone.style.maxWidth = "none";
99113
clone.style.minWidth = "0";
100114
stage.appendChild(clone);
101115

116+
const oneBtn = overlay.querySelector(".wh-zoom__one");
117+
oneBtn.hidden = !(fit < 0.98); // 1:1 only buys anything when fit shrank it
118+
oneBtn.setAttribute("aria-pressed", "false");
119+
overlay.__whSetMode = (natural) => {
120+
sizeTo(natural ? 1 : fitScale);
121+
oneBtn.setAttribute("aria-pressed", String(natural));
122+
stage.scrollLeft = 0;
123+
stage.scrollTop = 0;
124+
// Stamp the edge fades for the new size (ScrollHints' capture-phase
125+
// scroll listener keeps them updated as the user pans).
126+
requestAnimationFrame(() => {
127+
stage.toggleAttribute(
128+
"data-wh-more",
129+
stage.scrollWidth - stage.clientWidth - stage.scrollLeft > 8,
130+
);
131+
stage.toggleAttribute("data-wh-more-start", false);
132+
});
133+
};
134+
102135
overlay.removeAttribute("hidden");
103-
// Same right-edge fade contract as the inline scrollers (ScrollHints
104-
// owns the [data-wh-more] CSS + the capture-phase scroll listener that
105-
// clears/re-stamps it as the user pans) — without it the pannable stage
106-
// hard-clipped nodes at its edge with no hint that it scrolls.
107-
requestAnimationFrame(() => {
108-
const more = stage.scrollWidth - stage.clientWidth - stage.scrollLeft > 3;
109-
stage.toggleAttribute("data-wh-more", more);
110-
});
111136
// Next frame so the un-hide paints before the open transition.
112137
requestAnimationFrame(() => overlay.classList.add("is-open"));
113138
document.documentElement.style.overflow = "hidden";
@@ -205,7 +230,8 @@
205230
.wh-zoom__stage > svg {
206231
display: block;
207232
}
208-
.wh-zoom__close {
233+
.wh-zoom__close,
234+
.wh-zoom__one {
209235
position: fixed;
210236
top: clamp(0.5rem, 2vw, 1.25rem);
211237
right: clamp(0.5rem, 2vw, 1.25rem);
@@ -218,13 +244,30 @@
218244
background: var(--wh-surface, #14171c);
219245
color: var(--wh-ink, #f1f3f7);
220246
cursor: pointer;
221-
transition: background 0.12s ease, transform 0.12s ease;
247+
transition: background 0.12s ease, transform 0.12s ease,
248+
border-color 0.12s ease;
249+
}
250+
.wh-zoom__one {
251+
right: calc(clamp(0.5rem, 2vw, 1.25rem) + 3.1rem);
252+
font-family: var(--sl-font-mono);
253+
font-size: 0.75rem;
254+
font-weight: 650;
255+
letter-spacing: 0.02em;
256+
}
257+
.wh-zoom__one[hidden] {
258+
display: none;
259+
}
260+
.wh-zoom__one[aria-pressed="true"] {
261+
border-color: var(--wh-accent, #06b0bf);
262+
color: var(--wh-accent-text, var(--wh-accent-hi, #1dc9d8));
222263
}
223-
.wh-zoom__close:hover {
264+
.wh-zoom__close:hover,
265+
.wh-zoom__one:hover {
224266
background: var(--wh-surface-2, #1b1f26);
225267
transform: scale(1.05);
226268
}
227-
.wh-zoom__close:focus-visible {
269+
.wh-zoom__close:focus-visible,
270+
.wh-zoom__one:focus-visible {
228271
outline: 2px solid var(--wh-accent-text, var(--wh-accent-hi));
229272
outline-offset: 2px;
230273
}

‎docs/src/components/ScrollHints.astro‎

Lines changed: 77 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@
4343
)) {
4444
if (svg.style.maxWidth) {
4545
svg.style.setProperty("--wh-natural-w", svg.style.maxWidth);
46+
// The WRAPPER needs it too: its desktop breakout width is
47+
// min(natural, pane) — fit-content can't measure a width:100% svg.
48+
svg.parentElement?.style.setProperty("--wh-natural-w", svg.style.maxWidth);
4649
}
4750
}
4851
// Paired diagrams already live in a <p>/<div> wrapper that global.css
@@ -117,34 +120,48 @@
117120
}
118121
}
119122

123+
// 8px threshold, not ~0: fit-content widths and devicePixelRatio rounding
124+
// leave a few phantom pixels of "overflow" on blocks with nothing real to
125+
// scroll to — fading those reads as cut-off content that isn't there.
120126
function updateOne(el) {
121-
const more = el.scrollWidth - el.clientWidth - el.scrollLeft > 3;
122-
el.toggleAttribute("data-wh-more", more);
127+
const end = el.scrollWidth - el.clientWidth - el.scrollLeft > 8;
128+
const start = el.scrollLeft > 8;
129+
el.toggleAttribute("data-wh-more", end);
130+
el.toggleAttribute("data-wh-more-start", start);
123131
}
124132
function updateAll() {
125133
document.querySelectorAll(SCROLLERS).forEach(updateOne);
126134
}
127-
// Tables get their per-column min-width floors ONLY once they genuinely
128-
// overflow (data-wh-scrolls): floors stop auto layout crushing off-screen
129-
// columns inside a scroller, but applied unconditionally they FORCED
130-
// tables that would fit by wrapping into scrollers. Measure with floors
131-
// off (remove all attrs first so a single reflow covers every table),
132-
// then stamp the ones that still can't fit — plus the ones that "fit"
133-
// only by CROWDING: a many-column table squeezed to a sliver per column
134-
// wraps every other word and reads worse than a clean sideways pan, so
135-
// below ~8.5rem of average column width it scrolls instead.
135+
// Tables earn their treatments by measurement, in two passes:
136+
//
137+
// Pass 1 (at prose width): a table that overflows or CROWDS there —
138+
// ≥4 columns squeezed below ~8.5rem average wrap every other word —
139+
// gets data-wh-wide, which on desktop moves it to the breakout track
140+
// (wider, centered). A table whose prose wraps comfortably at 45rem
141+
// stays at prose width: stretching its sentences to 60rem line lengths
142+
// reads worse, not better.
143+
//
144+
// Pass 2 (re-measured at whatever width pass 1 granted): still
145+
// overflowing or crowded → data-wh-scrolls, which enables the
146+
// horizontal scroller and the per-column min-width floors (floors stop
147+
// auto layout crushing off-screen columns, but applied to a fitting
148+
// table they would CREATE the scroll).
136149
function classifyTables() {
137150
const CROWD_PX = 136;
138-
const wraps = document.querySelectorAll(".wh-table-wrap");
139-
wraps.forEach((el) => el.removeAttribute("data-wh-scrolls"));
140-
wraps.forEach((el) => {
151+
const overOrCrowded = (el) => {
141152
const row = el.querySelector("tr");
142153
const cols = row ? row.cells.length : 0;
143154
const crowded = cols >= 4 && el.clientWidth / cols < CROWD_PX;
144-
if (crowded || el.scrollWidth - el.clientWidth > 1) {
145-
el.setAttribute("data-wh-scrolls", "");
146-
}
155+
return crowded || el.scrollWidth - el.clientWidth > 1;
156+
};
157+
const wraps = document.querySelectorAll(".wh-table-wrap");
158+
wraps.forEach((el) => {
159+
el.removeAttribute("data-wh-scrolls");
160+
el.removeAttribute("data-wh-wide");
147161
});
162+
const wide = [...wraps].filter(overOrCrowded);
163+
wide.forEach((el) => el.setAttribute("data-wh-wide", ""));
164+
wide.filter(overOrCrowded).forEach((el) => el.setAttribute("data-wh-scrolls", ""));
148165
}
149166
function init() {
150167
wrapScrollables();
@@ -188,11 +205,26 @@
188205
margin-block: 1rem;
189206
position: relative;
190207
}
191-
/* The right-edge fade: content hidden past the edge reads as scrollable
192-
instead of amputated. Cleared by the script at scroll end. */
208+
/* Edge fades: content hidden past an edge reads as scrollable instead of
209+
amputated — on BOTH sides (a right-scrolled view fades its left edge so
210+
the way back reads as scrollable too). The combined two-attr rule must
211+
come last: each fade is a full mask-image (multiple mask layers union,
212+
they can't compose two opposite fades). */
193213
[data-wh-more] {
194214
mask-image: linear-gradient(90deg, #000 calc(100% - 32px), transparent);
195215
}
216+
[data-wh-more-start] {
217+
mask-image: linear-gradient(90deg, transparent, #000 32px);
218+
}
219+
[data-wh-more-start][data-wh-more] {
220+
mask-image: linear-gradient(
221+
90deg,
222+
transparent,
223+
#000 32px,
224+
#000 calc(100% - 32px),
225+
transparent
226+
);
227+
}
196228
/* Wrapped tables: the wrapper carries the card frame so the border doesn't
197229
scroll away with the content; the table inside reverts to true auto
198230
layout at full wrapper width (overriding the no-JS block fallback). */
@@ -240,25 +272,31 @@
240272
.wh-table-wrap .wh-tok-path {
241273
white-space: normal;
242274
}
243-
/* Touch screens get an explicit zoom affordance on diagrams — cursor:
244-
zoom-in means nothing without a pointer. */
245-
@media (pointer: coarse) {
246-
.wh-scroll-x:not(.wh-table-wrap)::after {
247-
content: "⤢";
248-
position: absolute;
249-
top: 0.4rem;
250-
right: 0.4rem;
251-
display: grid;
252-
place-items: center;
253-
width: 1.6rem;
254-
height: 1.6rem;
255-
border-radius: var(--radius-xs);
256-
background: var(--wh-surface-overlay);
257-
border: 1px solid var(--wh-border-strong);
258-
color: var(--wh-ink-muted);
259-
font-size: 0.95rem;
260-
line-height: 1;
261-
pointer-events: none;
262-
}
275+
/* Every diagram carries a quiet zoom affordance — cursor: zoom-in only
276+
speaks to a pointer that happens to hover, so the corner chip is always
277+
present (dimmed) and brightens on hover. */
278+
.wh-scroll-x:not(.wh-table-wrap)::after {
279+
content: "⤢";
280+
position: absolute;
281+
top: 0.4rem;
282+
right: 0.4rem;
283+
display: grid;
284+
place-items: center;
285+
width: 1.6rem;
286+
height: 1.6rem;
287+
border-radius: var(--radius-xs);
288+
background: var(--wh-surface-overlay);
289+
border: 1px solid var(--wh-border-strong);
290+
color: var(--wh-ink-muted);
291+
font-size: 0.95rem;
292+
line-height: 1;
293+
pointer-events: none;
294+
opacity: 0.6;
295+
transition: opacity 0.15s ease, border-color 0.15s ease, color 0.15s ease;
296+
}
297+
.wh-scroll-x:not(.wh-table-wrap):hover::after {
298+
opacity: 1;
299+
border-color: var(--wh-accent);
300+
color: var(--wh-accent-text);
263301
}
264302
</style>
Lines changed: 46 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ sidebar:
55
order: 5
66
---
77

8+
import { Tabs, TabItem } from "@astrojs/starlight/components";
9+
810
WaveHouse authorizes every request against a single **access control policy**: a per-table, per-role document that decides which columns a caller may see, which rows they may touch, what they may aggregate, and how much work a query may do. It is Hasura-style — column-level and row-level permissions with JWT claim templating — stored centrally and applied on every read, write, and live stream.
911

1012
This guide explains the whole model: where roles come from, how to write a policy, how each rule is enforced, and how the policy is loaded and changed at runtime. For the raw config knobs see [Configuration](/configuration#access-control-policy); for the HTTP surface see the [API reference](/api#authentication). Named query pipes have their own, simpler authorization model — see [Named Pipes](/pipes).
@@ -135,7 +137,7 @@ Supported comparison operators:
135137
| `_gt` | `col > ?` | greater than |
136138
| `_lt` | `col < ?` | less than |
137139

138-
> The policy `Filter` schema also accepts `_in`, but it is **not yet enforced** (tracked in #224) — an `_in` clause is silently ignored (no predicate is produced), so stick to the operators above.
140+
> The policy `Filter` schema also accepts `_in`, but it is **not yet enforced** (tracked in [#224](https://github.com/Wave-RF/WaveHouse/issues/224)) — an `_in` clause is silently ignored (no predicate is produced), so stick to the operators above.
139141

140142
Multiple columns (and multiple operators on one column) are combined with `AND`. The policy-derived predicate is ANDed with whatever filters the caller's own query supplies, so a caller can never widen their row visibility past the policy.
141143

@@ -264,7 +266,9 @@ Because a deleted policy is a total lockout (including admin), treat the bootstr
264266

265267
A multi-tenant analytics deployment: anonymous callers get nothing, `viewer` reads its own tenant's rows with sensitive columns masked and expensive aggregations blocked, `writer` ingests events that are stamped with the caller's identity, and `admin` is unrestricted.
266268

267-
```yaml
269+
<Tabs syncKey="policy">
270+
<TabItem label="YAML">
271+
```yaml title="policy.yaml"
268272
admin_role: admin # full access + the /v1/admin/* gate (this is also the default)
269273
default_role: "" # "" = closed: a request with no/!valid token is denied
270274
@@ -291,6 +295,46 @@ tables:
291295
tenant_id:
292296
_eq: "{{ jwt.app_metadata.tenant_id }}"
293297
```
298+
</TabItem>
299+
<TabItem label="JSON">
300+
```json title="policy.json"
301+
{
302+
"admin_role": "admin",
303+
"default_role": "",
304+
"tables": {
305+
"events": {
306+
"select": {
307+
"viewer": {
308+
"deny_columns": ["user_email", "ip_address"],
309+
"filter": {
310+
"tenant_id": {
311+
"_eq": "{{ jwt.app_metadata.tenant_id }}"
312+
}
313+
},
314+
"denied_aggregations": ["quantile", "median"],
315+
"max_rows": 1000,
316+
"max_execution_time_ms": 5000
317+
}
318+
},
319+
"insert": {
320+
"writer": {
321+
"allow_columns": ["event_name", "page", "score", "user_id", "tenant_id"],
322+
"check": {
323+
"user_id": {
324+
"_eq": "{{ jwt.sub }}"
325+
},
326+
"tenant_id": {
327+
"_eq": "{{ jwt.app_metadata.tenant_id }}"
328+
}
329+
}
330+
}
331+
}
332+
}
333+
}
334+
}
335+
```
336+
</TabItem>
337+
</Tabs>
294338

295339
With this policy loaded:
296340

‎docs/src/content/docs/architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ The package's design invariants — stdout always 100%, WARN+ERROR always export
140140
### `query/` — Structured Query Engine
141141

142142
- **ast.go** — `StructuredQuery` AST types: columns, aggregations, filters, group by, order by, limit, time range.
143-
- **builder.go** — `Build()` converts AST to parameterized SQL. It is the single chokepoint that validates every referenced identifier against the schema **and** authorizes every column reference — projection, aggregation args, filters, group_by, order_by, time_range — against the role's column allowlist (the #223 hard cap). A full-row read is requested with `select_all`, which expands to the role's allowed columns rather than emitting a raw `SELECT *`; an omitted projection selects nothing, and `*` in `columns` is a literal column name. Every identifier is backtick-quoted via `internal/chsql` (`QuoteIdent`) so any ClickHouse-legal name is accepted — a name containing `?` is refused fail-closed (#279). `InjectPermissionFilters()` adds row-level security. `ApplyMaxRows()` enforces limits. Timestamp bucketing for cache optimization.
143+
- **builder.go** — `Build()` converts AST to parameterized SQL. It is the single chokepoint that validates every referenced identifier against the schema **and** authorizes every column reference — projection, aggregation args, filters, group_by, order_by, time_range — against the role's column allowlist (the [#223](https://github.com/Wave-RF/WaveHouse/issues/223) hard cap). A full-row read is requested with `select_all`, which expands to the role's allowed columns rather than emitting a raw `SELECT *`; an omitted projection selects nothing, and `*` in `columns` is a literal column name. Every identifier is backtick-quoted via `internal/chsql` (`QuoteIdent`) so any ClickHouse-legal name is accepted — a name containing `?` is refused fail-closed ([#279](https://github.com/Wave-RF/WaveHouse/issues/279)). `InjectPermissionFilters()` adds row-level security. `ApplyMaxRows()` enforces limits. Timestamp bucketing for cache optimization.
144144

145145
### `chsql/` — ClickHouse SQL Helpers
146146

‎docs/src/content/docs/claude-code.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,7 @@ User-specific worktrunk config goes in `~/.config/worktrunk/config.toml`; the co
146146

147147
The GitHub MCP server is useful for cross-repo code search and bulk graph queries, but neither is a daily WaveHouse pattern. If you want it, add at user level:
148148

149-
```jsonc
149+
```jsonc title="~/.claude.json"
150150
// ~/.claude.json — your user-level config
151151
{
152152
"mcpServers": {
@@ -198,7 +198,7 @@ The deny list blocks:
198198

199199
Not committed at project level. Personal preference — put in `.claude/settings.local.json`:
200200

201-
```jsonc
201+
```jsonc title=".claude/settings.local.json"
202202
{
203203
"statusLine": { "type": "command", "command": "~/.config/claude/statusline.sh" },
204204
"outputStyle": "default",

0 commit comments

Comments
 (0)