Repository navigation
Commit 8a1f467
feat(console): on a narrow window the sidebar is the icon rail, and a click expands it over the content (#27893)
<!-- claude-projects-attribution: {"github_login":"os-bill"} -->
_Requested by **Bill** · [project
thread](https://claude.ai/code/project/chan_016iMXWSZDzqWRWvWzdNo8wg?thread=cmsg_016iMXWSZDzqWRWvWzdNo8wgDFH4S5pR1C8YvYCWWsZfXx)_
## 维护者速读
- 改了什么:窗口窄于 1416 px(分栏要的 1160 px 内容 + 展开侧栏 256
px)时,控制台侧栏挂载为图标轨;点图标轨空白处、顶栏侧栏按钮或 ⌘B 把整个侧栏浮在内容上展开,内容不挪;选导航、点外面或 Esc
收回。浮出时底部有「保持侧栏展开」,按下后这个浏览器的窄窗也保持宽窗侧栏。
- 为什么改:1280 px 的笔记本窗口里展开的侧栏只留 1024 px 内容,放不下记录分栏;折成图标轨后剩 1232 px。
- 风险与回滚:只动控制台外壳(app-shell 两个文件 + 一个新模块)、components 新增一个 hook、i18n
一个新键;`components/src/ui/**` 没碰。≥1416 px 与手机抽屉行为不变。回滚即还原本 PR。
-
先看:`ui/packages/app-shell/src/layout/consoleSidebarRail.ts`(阈值推导、浮出、收回);`ui/packages/app-shell/src/hooks/useResponsiveSidebar.ts`(折叠与宽窗状态暂存);`UnifiedSidebar.tsx`
的外框与底部开关。
- 两分钟验证:`pnpm --dir ui exec vitest run
packages/app-shell/src/layout/__tests__/UnifiedSidebar.railOverlay-27593.test.tsx
packages/app-shell/src/hooks/__tests__/useResponsiveSidebar.test.tsx`,预期全绿;或在
1280 px 窗口打开任一应用,侧栏是图标轨,点轨道空白处浮出。
- 需要你做的:无,席位落地。
Fixes #27593
Clause-②: yes (widening)
Metadata-protocol: none
## What changes
- **The fold (`app-shell` `useResponsiveSidebar`, extended in place).**
While the window is narrower than `CONSOLE_SIDEBAR_RAIL_BELOW_WIDTH` and
wider than the phone breakpoint, the console sidebar is folded to its
icon rail; when the window widens past it, the sidebar unfolds. It
replaces the old one-time 768–1023 px collapse. A layout effect, so a
window that opens narrow paints the rail first.
- **The width is derived, in one named constant**
(`app-shell/src/layout/consoleSidebarRail.ts`):
`RECORD_SPLIT_MIN_CONTENT_WIDTH` (the split's list 440 + pane 720 =
1160) + `CONSOLE_EXPANDED_SIDEBAR_WIDTH` (256, the primitive's
`--sidebar-width`; a test reads the primitive's value and holds the two
equal) = 1416. A 1280 px window folds (1232 px left for the split); a
1440 px window keeps the expanded sidebar (1184 px left).
- **Expand over the content (`UnifiedSidebar`, `railOverlay` prop set by
`ConsoleLayout`).** A click on the rail's background, the app bar's
trigger, or ⌘B / Ctrl+B expands the folded sidebar as an overlay: the
fixed panel takes its expanded width above the page (`z-40`, a shadow),
while a `display: contents` frame around the sidebar holds the
primitive's in-flow gap at the rail width, so the content does not move.
A navigation (an entry chosen in it, the command palette, Back), a press
outside it, or an Esc no other layer handled folds it again. A press
inside the sidebar's React tree, its entries' portaled menus included,
does not; a press on the app bar's trigger is left to the trigger. Hover
does nothing; a click on a rail icon opens the entry as before.
- **Keep sidebar open.** The expanded overlay's footer carries one
toggle, `aria-pressed`, stored per browser as the workspace preference
`console.sidebar.keepOpen` (`os:pref:` store). On, a narrow window keeps
the wide-window sidebar (expanded beside the content, ⌘B collapses it as
on a wide window) and the toggle stays in the footer to turn it off.
- **The wide window keeps its state.** The sidebar primitive writes its
`sidebar_state` cookie on every open and close, the fold's included, so
the fold now stashes the wide-window state
(`os:console-sidebar:wide-open`) when it takes over and hands it back
when the window widens, or on the next load that opens wide.
- **`@object-ui/components`**: new export
`useIsViewportBelow(breakpoint)` beside `useIsMobile`, read
synchronously on the first render and live through `matchMedia`.
- **`@object-ui/i18n`**: `sidebar.keepOpen` in all ten packs.
- No change under `components/src/ui/**`, `packages/spec/**`, or any
metadata key.
## Tests
- New `layout/__tests__/UnifiedSidebar.railOverlay-27593.test.tsx` (11):
1280 mounts the rail; a background click expands the overlay, the panel
carries the overlay classes and the frame's variant reaches the
primitive's gap (not the panel); hover does not expand and a rail icon
navigates; a nav choice, a route change from elsewhere, an outside
press, Esc fold it; an Esc another layer handled does not; a press in an
entry's portaled menu does not; the trigger toggles once; keep-open ends
the fold, survives a remount, and turning it off folds again; 1440
unchanged; 700 mounts the phone drawer.
- `hooks/__tests__/useResponsiveSidebar.test.tsx` rewritten (7): 1280
folds / 1440 open; a manual expand on a narrow window holds; widening
hands back an open and a collapsed wide state; a wide load after a
narrow one gets the wide state; keep-open; the phone breakpoint is left
alone.
- New `layout/__tests__/consoleSidebarRail.width-27593.test.tsx` (3):
the expanded width equals the primitive's `--sidebar-width`; the
derivation; 1280 / 1440 on either side.
- New `components/src/hooks/__tests__/use-viewport-below.test.tsx` (3):
first-render answer with no wrong frame, the breakpoint edge, live
across resizes.
- Two existing pins follow the new behaviour:
`KeyboardShortcutsDialog.wiredOnly-11674` mounts a 1440 px window (its
⌘B probe starts from the expanded sidebar); `consoleTopBar.height-12639`
reads `CONSOLE_BELOW_TOP_BAR` as the sidebar's leading class (the
overlay adds its own after it).
## Acceptance notes
- **Deviation: the threshold.** The card's Target 1 says "below a window
width of 1100 px", while its Acceptance 1 says "at 1280 px the sidebar
mounts as the icon rail … at 1440 px nothing changes" and its title says
a 1280 px window keeps room for the split. A 1280 px window is wider
than 1100, so the two cannot both hold. Agreed with the seat before
implementing: the threshold follows the Acceptance, the title and the
card's own Source derivation (the split needs 1160 px of content, the
expanded sidebar is 256 px), so it is 1416 px, derived in one named
constant from the sidebar's width rather than written as a number. The
epic seat is asked to confirm it at the preview.
- **Premise corrections (measured on `main` `ddab8b99`).** The
"resizable rail (200–480 px, remembered in localStorage)" the card's
Source describes does not exist: the only remembered sidebar state is
the primitive's `sidebar_state` open/closed cookie. The sidebar was
already `collapsible="icon"` with rail tooltips (the entries' own
labels), and `useResponsiveSidebar` already collapsed it once between
768 and 1023 px, writing that into the cookie. There was no pin toggle
in the expanded sidebar (the shell's one trigger is in the app bar), so
"Keep sidebar open" is new, with one new i18n key.
- **No edit under `components/src/ui/**`** (ui `AGENTS.md` #7): the
overlay is built from the outside, through the primitive's `className` /
props on the panel and a `display: contents` frame whose arbitrary
variant narrows the gap (the first child of the primitive's
`data-collapsible` element). The overlay test pins that the variant
reaches the gap, so a primitive sync that moves it turns the test red.
- **The rail's background click is a mouse convenience**; its keyboard
twins are the app bar's trigger and ⌘B. The handler arrives through a
props spread on the `Sidebar` element, which the clickable non-control
census (`clickableNonControlCensus-13461`) does not judge.
- **Record page tiers.** `recordPageColumns.ts` (plugin-detail) derives
its 1120 / 760 container floors from example windows with the sidebar
expanded. The tiers are container-measured, so they follow the fold on
their own: at 1280 the content area is 1232 px instead of 1024, so a
full record page there can now reach the wider tier. The docblock's
window examples still describe an expanded sidebar; not edited here
(outside this card's surface).
- **HotCRM.** This container reaches only this repository, so the
screenshots are taken on the in-repo CRM example (`examples/app-crm`,
Contacts); the shell is app-independent.
- **Docs.** No page under `content/docs/` describes the console shell's
sidebar, and the components README lists no hooks; nothing to update.
## Verification
All readings on head `bc7935f4` (the branch merged with `origin/main` at
`c4cb5ec0`; of the files this diff edits, the merge touched only the ten
locale packs, and merged them cleanly), unless a line says otherwise.
<details><summary>Browser measurement (Chromium, the CRM example's
Contacts list)</summary>
Branch code at `fdb717ea` (pre-merge; the merge brought nothing under
the edited surface), backend `objectstack dev --seed-admin --fresh` on
`examples/app-crm`, console on its Vite dev server. Screenshots,
readings and the script are on the never-merged evidence branch
`claude/issue-27593-evidence` @ `b86187c2`, folder `evidence/27593/`.
| Window, state | sidebar | gap (in flow) | panel | panel z | content
left / width |
|---|---|---|---|---|---|
| 1280, on load | collapsed, `data-console-rail=rail` | 48 | 48 | 10 |
48 / 1232 |
| 1280, rail background clicked | expanded, `overlay` | 48 | 256 | 40 |
48 / 1232 |
| 1280, after Esc | collapsed | 48 | 48 | 10 | 48 / 1232 |
| 1280, app bar trigger | expanded, `overlay` | 48 | 256 | 40 | 48 /
1232 |
| 1280, press on the page | collapsed | 48 | 48 | 10 | 48 / 1232 |
| 1440, on load | expanded, no rail attribute | 256 | 256 | 10 | 256 /
1184 |
| 700, trigger | phone drawer (`data-mobile`), no desktop sidebar | – |
– | – | 0 / 700 |
The overlay leaves the content box exactly where it was (48 / 1232 in
every 1280 state); the "Keep sidebar open" footer is present only while
expanded.
</details>
<details><summary>Tests and type-check</summary>
- New and rewritten files (4: `use-viewport-below`,
`useResponsiveSidebar`, `consoleSidebarRail.width-27593`,
`UnifiedSidebar.railOverlay-27593`): Test Files 4 passed (4), Tests 24
passed (24); os-verify-lock VERDICT command-exit 0.
- Every existing test file that names `UnifiedSidebar`, `ConsoleLayout`,
`useResponsiveSidebar`, `LocalizedSidebarTrigger` or the `sidebar_state`
cookie (135 files) plus `packages/i18n/`, on `48346663`: Test Files 2
failed | 223 passed (225), Tests 2 failed | 2443 passed | 13 skipped.
The two were the pins this PR updates
(`KeyboardShortcutsDialog.wiredOnly-11674`: its ⌘B probe mounted at
happy-dom's default 1024 px and expected an expanded sidebar;
`consoleTopBar.height-12639`: its source regex read
`className={CONSOLE_BELOW_TOP_BAR}` verbatim); after the update both
files pass (17/17).
- On the merged head `bc7935f4`, after rebuilding `@object-ui/i18n` and
`@object-ui/components`: `type-check` of `@object-ui/components` and
`@object-ui/app-shell` (tsc --noEmit and tsconfig.test.json) exit 0, and
the four new files, the two updated pins,
`LocalizedSidebarTrigger.appBar-12429` and `packages/i18n/`: Test Files
98 passed (98), Tests 1428 passed | 13 skipped; VERDICT command-exit 0.
- Ablations, one per behaviour, each through
`scripts/ablation-replace.mjs` (anchor 1 -> 0, blob changed, restored,
`git diff HEAD` empty after); app-shell tests import `src`, so no dist
rebuild:
- the frame's gap-keeping class removed: 1 failed | 17 passed — "the gap
keeps the rail's width";
- the wide-state stash write removed: 5 failed | 13 passed — every
hand-back case, and the phone-breakpoint case (its transient fold is no
longer undone);
- the inside-press check removed: 1 failed | 17 passed — "a press in an
entry's own menu, drawn in a portal, does not fold it".
- `pnpm --dir ui run check:i18n-drift` (1 key added, 0 en values
changed), `check:i18n-keys`, `check:i18n-dead-keys`: exit 0. `pnpm --dir
ui run check:new-line-citations`: 0 new, exit 0.
- Not run locally, left to CI's Test UI shards: the rest of the
`components`, `app-shell` and `i18n`-consuming suites.
</details>
<details><summary>Gates</summary>
- `dispatch-gates --commands` on `bc7935f4` derived 35 families; all 35
ran, each `exit 0` (`check-sdui-manifest` and its `--self-test`, and
`pnpm --dir ui exec vitest run scripts/`, among them). `--ran`
reconciliation: 35 derived, 35 run, 0 NOT-MEASURED, 0 UNRUN.
- Repo-wide families and Test UI belong to CI; see this PR's check-runs.
</details>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01Utp6CaPpqK4cmqg5XJnjsj
---
_Generated by [Claude
Code](https://claude.ai/code/session_01Utp6CaPpqK4cmqg5XJnjsj)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent f3fe660 commit 8a1f467
23 files changed
Lines changed: 1007 additions & 56 deletions
File tree
- .changeset
- ui/packages
- app-shell/src
- chrome
- hooks
- __tests__
- layout
- __tests__
- components/src
- hooks
- __tests__
- i18n/src/locales
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
118 | 118 | | |
119 | 119 | | |
120 | 120 | | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
121 | 128 | | |
122 | 129 | | |
123 | 130 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | | - | |
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
2 | 12 | | |
3 | | - | |
| 13 | + | |
4 | 14 | | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
5 | 20 | | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
6 | 25 | | |
7 | | - | |
8 | | - | |
9 | | - | |
10 | | - | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
11 | 36 | | |
12 | 37 | | |
13 | 38 | | |
14 | 39 | | |
15 | 40 | | |
16 | | - | |
| 41 | + | |
17 | 42 | | |
18 | 43 | | |
19 | 44 | | |
20 | 45 | | |
21 | 46 | | |
22 | 47 | | |
23 | 48 | | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
24 | 52 | | |
25 | 53 | | |
26 | 54 | | |
27 | 55 | | |
28 | | - | |
29 | | - | |
30 | | - | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
31 | 100 | | |
32 | | - | |
33 | | - | |
34 | | - | |
35 | | - | |
36 | | - | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
37 | 109 | | |
38 | | - | |
39 | | - | |
40 | | - | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
41 | 114 | | |
| 115 | + | |
| 116 | + | |
42 | 117 | | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
43 | 142 | | |
44 | | - | |
45 | | - | |
46 | | - | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
47 | 147 | | |
48 | 148 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
5 | 8 | | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
6 | 15 | | |
7 | 16 | | |
8 | 17 | | |
9 | | - | |
| 18 | + | |
10 | 19 | | |
11 | | - | |
12 | | - | |
13 | | - | |
14 | | - | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
15 | 25 | | |
16 | 26 | | |
17 | | - | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
18 | 30 | | |
19 | 31 | | |
20 | | - | |
| 32 | + | |
| 33 | + | |
21 | 34 | | |
22 | | - | |
23 | | - | |
24 | | - | |
25 | | - | |
26 | | - | |
27 | | - | |
28 | | - | |
29 | | - | |
30 | | - | |
31 | | - | |
32 | | - | |
33 | | - | |
34 | | - | |
35 | | - | |
36 | | - | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
37 | 44 | | |
38 | | - | |
39 | | - | |
40 | | - | |
41 | | - | |
42 | | - | |
43 | | - | |
44 | | - | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
45 | 52 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
216 | 216 | | |
217 | 217 | | |
218 | 218 | | |
| 219 | + | |
219 | 220 | | |
220 | 221 | | |
221 | 222 | | |
| |||
0 commit comments