@estiva-app/ui 0.94.0 → 0.96.0

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.
Files changed (189) hide show
  1. package/dist/AppShell.d.ts +25 -7
  2. package/dist/AppShell.d.ts.map +1 -1
  3. package/dist/ArchivedNotice.d.ts +28 -0
  4. package/dist/ArchivedNotice.d.ts.map +1 -0
  5. package/dist/Button.d.ts +4 -3
  6. package/dist/Button.d.ts.map +1 -1
  7. package/dist/Card.d.ts.map +1 -1
  8. package/dist/CommentBox.d.ts.map +1 -1
  9. package/dist/ConversationActions.d.ts +24 -0
  10. package/dist/ConversationActions.d.ts.map +1 -0
  11. package/dist/ConversationCard.d.ts +88 -0
  12. package/dist/ConversationCard.d.ts.map +1 -0
  13. package/dist/ConversationLayout.d.ts +50 -0
  14. package/dist/ConversationLayout.d.ts.map +1 -0
  15. package/dist/ConversationMenu.d.ts +24 -0
  16. package/dist/ConversationMenu.d.ts.map +1 -0
  17. package/dist/Divider.d.ts +23 -4
  18. package/dist/Divider.d.ts.map +1 -1
  19. package/dist/EditedMarker.d.ts +11 -0
  20. package/dist/EditedMarker.d.ts.map +1 -0
  21. package/dist/IconButton.d.ts +3 -3
  22. package/dist/IconButton.d.ts.map +1 -1
  23. package/dist/LinkParts.d.ts +3 -1
  24. package/dist/LinkParts.d.ts.map +1 -1
  25. package/dist/LinkRow.d.ts.map +1 -1
  26. package/dist/ListColumn.d.ts +3 -1
  27. package/dist/ListColumn.d.ts.map +1 -1
  28. package/dist/MetaText.d.ts +22 -0
  29. package/dist/MetaText.d.ts.map +1 -0
  30. package/dist/NavItem.d.ts.map +1 -1
  31. package/dist/PageHeader.d.ts +50 -0
  32. package/dist/PageHeader.d.ts.map +1 -0
  33. package/dist/Panel.d.ts +6 -0
  34. package/dist/Panel.d.ts.map +1 -1
  35. package/dist/PartCard.d.ts +4 -7
  36. package/dist/PartCard.d.ts.map +1 -1
  37. package/dist/PinnedComment.d.ts +17 -0
  38. package/dist/PinnedComment.d.ts.map +1 -0
  39. package/dist/QuotedLine.d.ts +16 -0
  40. package/dist/QuotedLine.d.ts.map +1 -0
  41. package/dist/ReactionHorizon.d.ts +14 -0
  42. package/dist/ReactionHorizon.d.ts.map +1 -0
  43. package/dist/RepliesRow.d.ts +26 -0
  44. package/dist/RepliesRow.d.ts.map +1 -0
  45. package/dist/ResolveDialog.d.ts +13 -0
  46. package/dist/ResolveDialog.d.ts.map +1 -0
  47. package/dist/Select.d.ts +1 -1
  48. package/dist/Select.d.ts.map +1 -1
  49. package/dist/ShowMore.d.ts +1 -7
  50. package/dist/ShowMore.d.ts.map +1 -1
  51. package/dist/Skeleton.d.ts +8 -4
  52. package/dist/Skeleton.d.ts.map +1 -1
  53. package/dist/Thread.d.ts +38 -0
  54. package/dist/Thread.d.ts.map +1 -0
  55. package/dist/TopBar.d.ts +3 -2
  56. package/dist/TopBar.d.ts.map +1 -1
  57. package/dist/UrgentMark.d.ts +6 -0
  58. package/dist/UrgentMark.d.ts.map +1 -0
  59. package/dist/commentBoxFrame.d.ts +3 -1
  60. package/dist/commentBoxFrame.d.ts.map +1 -1
  61. package/dist/conversation.examples.d.ts +52 -0
  62. package/dist/conversation.examples.d.ts.map +1 -0
  63. package/dist/editor.js +32 -24
  64. package/dist/editor.js.map +2 -2
  65. package/dist/eslint/index.js +2 -1
  66. package/dist/eslint/index.js.map +2 -2
  67. package/dist/eslint/no-native-title.d.ts +1 -1
  68. package/dist/eslint/no-native-title.d.ts.map +1 -1
  69. package/dist/eslint/no-restyled-part.d.ts.map +1 -1
  70. package/dist/index.d.ts +18 -2
  71. package/dist/index.d.ts.map +1 -1
  72. package/dist/index.js +1379 -442
  73. package/dist/index.js.map +4 -4
  74. package/dist/looks.d.ts +13 -1
  75. package/dist/looks.d.ts.map +1 -1
  76. package/dist/threadCard.d.ts +46 -0
  77. package/dist/threadCard.d.ts.map +1 -0
  78. package/package.json +1 -1
  79. package/registry.json +1872 -557
  80. package/src/AppShell.mdx +24 -10
  81. package/src/AppShell.stories.tsx +65 -31
  82. package/src/AppShell.test.tsx +92 -10
  83. package/src/AppShell.tsx +108 -18
  84. package/src/ArchivedNotice.mdx +46 -0
  85. package/src/ArchivedNotice.stories.tsx +52 -0
  86. package/src/ArchivedNotice.test.tsx +42 -0
  87. package/src/ArchivedNotice.tsx +71 -0
  88. package/src/Button.mdx +2 -2
  89. package/src/Button.tsx +8 -6
  90. package/src/Card.test.tsx +4 -4
  91. package/src/Card.tsx +6 -2
  92. package/src/CommentBox.test.tsx +2 -1
  93. package/src/CommentBox.tsx +14 -7
  94. package/src/ConfirmDialog.stories.tsx +12 -0
  95. package/src/ConversationActions.mdx +47 -0
  96. package/src/ConversationActions.stories.tsx +39 -0
  97. package/src/ConversationActions.tsx +96 -0
  98. package/src/ConversationCard.mdx +72 -0
  99. package/src/ConversationCard.states.test.tsx +330 -0
  100. package/src/ConversationCard.stories.tsx +135 -0
  101. package/src/ConversationCard.test.tsx +159 -0
  102. package/src/ConversationCard.tsx +522 -0
  103. package/src/ConversationLayout.mdx +61 -0
  104. package/src/ConversationLayout.stories.tsx +161 -0
  105. package/src/ConversationLayout.test.tsx +240 -0
  106. package/src/ConversationLayout.tsx +233 -0
  107. package/src/ConversationMenu.mdx +47 -0
  108. package/src/ConversationMenu.stories.tsx +42 -0
  109. package/src/ConversationMenu.test.tsx +47 -0
  110. package/src/ConversationMenu.tsx +57 -0
  111. package/src/Divider.mdx +36 -1
  112. package/src/Divider.stories.tsx +57 -0
  113. package/src/Divider.test.tsx +24 -1
  114. package/src/Divider.tsx +49 -9
  115. package/src/EditedMarker.mdx +36 -0
  116. package/src/EditedMarker.stories.tsx +24 -0
  117. package/src/EditedMarker.tsx +20 -0
  118. package/src/IconButton.mdx +2 -1
  119. package/src/IconButton.tsx +8 -5
  120. package/src/LinkCard.test.tsx +5 -2
  121. package/src/LinkParts.mdx +4 -0
  122. package/src/LinkParts.stories.tsx +10 -0
  123. package/src/LinkParts.tsx +5 -1
  124. package/src/LinkRow.mdx +1 -1
  125. package/src/LinkRow.tsx +10 -5
  126. package/src/ListColumn.tsx +9 -3
  127. package/src/MetaText.mdx +41 -0
  128. package/src/MetaText.stories.tsx +29 -0
  129. package/src/MetaText.tsx +38 -0
  130. package/src/NavItem.tsx +2 -11
  131. package/src/PageHeader.mdx +123 -0
  132. package/src/PageHeader.stories.tsx +174 -0
  133. package/src/PageHeader.test.tsx +99 -0
  134. package/src/PageHeader.tsx +105 -0
  135. package/src/Panel.mdx +12 -0
  136. package/src/Panel.stories.tsx +47 -5
  137. package/src/Panel.test.tsx +40 -0
  138. package/src/Panel.tsx +8 -2
  139. package/src/PartCard.mdx +1 -1
  140. package/src/PartCard.stories.tsx +2 -9
  141. package/src/PartCard.test.tsx +13 -1
  142. package/src/PartCard.tsx +6 -9
  143. package/src/PinnedComment.mdx +40 -0
  144. package/src/PinnedComment.stories.tsx +21 -0
  145. package/src/PinnedComment.tsx +40 -0
  146. package/src/QuotedLine.mdx +44 -0
  147. package/src/QuotedLine.stories.tsx +30 -0
  148. package/src/QuotedLine.test.tsx +34 -0
  149. package/src/QuotedLine.tsx +33 -0
  150. package/src/ReactionHorizon.mdx +36 -0
  151. package/src/ReactionHorizon.stories.tsx +27 -0
  152. package/src/ReactionHorizon.tsx +27 -0
  153. package/src/RepliesRow.mdx +45 -0
  154. package/src/RepliesRow.stories.tsx +33 -0
  155. package/src/RepliesRow.test.tsx +47 -0
  156. package/src/RepliesRow.tsx +86 -0
  157. package/src/ReplyCard.mdx +50 -0
  158. package/src/ReplyCard.stories.tsx +68 -0
  159. package/src/ResolveDialog.mdx +44 -0
  160. package/src/ResolveDialog.stories.tsx +23 -0
  161. package/src/ResolveDialog.test.tsx +53 -0
  162. package/src/ResolveDialog.tsx +58 -0
  163. package/src/Select.tsx +12 -2
  164. package/src/ShowMore.mdx +2 -5
  165. package/src/ShowMore.stories.tsx +0 -14
  166. package/src/ShowMore.test.tsx +0 -16
  167. package/src/ShowMore.tsx +2 -16
  168. package/src/Skeleton.stories.tsx +4 -1
  169. package/src/Skeleton.tsx +33 -4
  170. package/src/Thread.mdx +53 -0
  171. package/src/Thread.stories.tsx +167 -0
  172. package/src/Thread.test.tsx +83 -0
  173. package/src/Thread.tsx +113 -0
  174. package/src/TopBar.mdx +8 -6
  175. package/src/TopBar.stories.tsx +4 -3
  176. package/src/TopBar.tsx +8 -3
  177. package/src/UrgentMark.mdx +37 -0
  178. package/src/UrgentMark.stories.tsx +27 -0
  179. package/src/UrgentMark.tsx +15 -0
  180. package/src/commentBoxFrame.tsx +8 -4
  181. package/src/conversation.examples.tsx +135 -0
  182. package/src/eslint/no-native-title.ts +1 -1
  183. package/src/eslint/no-restyled-part.ts +1 -0
  184. package/src/index.ts +19 -2
  185. package/src/looks.ts +18 -2
  186. package/src/registry/registry.test.ts +7 -6
  187. package/src/threadCard.ts +84 -0
  188. package/stories/Choosing.mdx +21 -1
  189. package/tokens.css +14 -10
package/src/AppShell.mdx CHANGED
@@ -29,8 +29,7 @@ Layout only: no data, no routes.
29
29
  and bottom, with 8px corners, and the Sidebar drops its line and surface
30
30
  by itself. Any theme: the ground and the card are its base and surface.
31
31
  - **`floating` + Rail** — an app with a handful of top-level places and
32
- its content in one card; the `menu` button in the bar collapses the
33
- rail (the collapsing stays the app's).
32
+ its content in one card.
34
33
  - The **banner belongs to the content area**: it draws at the top of the
35
34
  main column — inside the card, in the floating manner — never across
36
35
  the navigation.
@@ -63,11 +62,14 @@ height and grows with a tall page — which is what lets the bar know the
63
62
  page changed — so a percentage height has nothing to resolve against.
64
63
 
65
64
  ```tsx
66
- import { AppShell, Banner, IdentityMenu, Rail, RailItem } from '@estiva-app/ui'
65
+ import { AppShell, Banner, IdentityMenu, Rail, RailItem, useSidebarFold } from '@estiva-app/ui'
66
+
67
+ const [navOpen, setNavOpen] = useSidebarFold({ storageKey: 'peek.sidebarFolded' })
67
68
 
68
69
  <AppShell
69
70
  variant="floating"
70
- menu={menuButton}
71
+ navOpen={navOpen}
72
+ onNavOpenChange={setNavOpen}
71
73
  logo="Estiva"
72
74
  onSearch={openLauncher}
73
75
  identity={<IdentityMenu me={me} signedIn={signedIn} />}
@@ -85,12 +87,22 @@ import { AppShell, Banner, IdentityMenu, Rail, RailItem } from '@estiva-app/ui'
85
87
  Ctrl+K.
86
88
  - In the floating manner the card owns `overflow-hidden` — your content
87
89
  manages its own scrolling inside it.
88
- - **Folding the navigation**, in the solid and inset manners: pass `navOpen`
89
- and `onNavOpenChange`, and the frame draws the fold as the top bar's menu
90
- button ("Hide the sidebar" / "Show the sidebar") and, folded, keeps only
91
- the content's own margin. Where the state is kept (remembered, started
92
- folded in a narrow window) is yours. A `menu` you pass replaces the fold
93
- button.
90
+ - **Folding the navigation**, in every manner: pass `navOpen` and
91
+ `onNavOpenChange`, and the frame draws the fold as the top bar's menu
92
+ button ("Hide the sidebar" / "Show the sidebar"), the same button in every
93
+ app (Katerina, 31 October). Folding narrows and fades the navigation in
94
+ 300ms, Peek's motion, down to the content's own margin: none in the solid
95
+ manner, 16px in the others. Folded, it stays mounted, and nothing in it can
96
+ be reached. A `menu` you pass replaces the fold button.
97
+ - **Remembering the fold**: `useSidebarFold({ storageKey })` gives `navOpen`
98
+ and `onNavOpenChange`, and keeps a folded sidebar folded on this browser,
99
+ across pages and reloads. `isFile` says whether the page open now is a
100
+ file: a file opened from a link unfolds a folded sidebar, as its button
101
+ would, and a reload does not. `foldWhen` is a media query: a window that
102
+ matches it opens folded.
103
+
104
+ <Canvas of={AppShellStories.SolidFolds} />
105
+
94
106
  - Desktop only for now — no narrow-screen behaviour is provided.
95
107
  - In the Signal theme the floating frame draws the control-room dot grid on
96
108
  its ground, behind the card. Nothing to add: the preset makes it.
@@ -110,6 +122,8 @@ It does these by itself. Write none of them around it.
110
122
  | It does | So you never write | Refused when written by hand |
111
123
  |---|---|---|
112
124
  | Scrolls the page's content column, in a ScrollArea | `overflow-auto` on the page or on `main` | |
125
+ | Draws the fold button, and folds the navigation with its motion | a menu button of your own, a width transition around the navigation | |
126
+ | Keeps a folded sidebar folded (`useSidebarFold`) | a `localStorage` key of your own for it | |
113
127
 
114
128
  ## Props
115
129
 
@@ -1,11 +1,10 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { useState } from 'react'
3
- import { IconMenu2, IconSquareRounded } from '@tabler/icons-react'
4
- import { expect, userEvent, within } from 'storybook/test'
5
- import { AppShell } from './AppShell'
3
+ import { IconSquareRounded } from '@tabler/icons-react'
4
+ import { expect, userEvent, waitFor, within } from 'storybook/test'
5
+ import { AppShell, useSidebarFold } from './AppShell'
6
6
  import { Banner } from './Banner'
7
7
  import { EmptyState } from './EmptyState'
8
- import { IconButton } from './IconButton'
9
8
  import { NavItem } from './NavItem'
10
9
  import { PersonTrigger } from './PersonTrigger'
11
10
  import { Rail } from './Rail'
@@ -24,7 +23,7 @@ const meta = {
24
23
  },
25
24
  args: { nav: null, children: null },
26
25
  argTypes: {
27
- variant: { control: 'inline-radio', options: ['solid', 'floating'] },
26
+ variant: { control: 'inline-radio', options: ['solid', 'inset', 'floating'] },
28
27
  menu: { control: false },
29
28
  logo: { control: false },
30
29
  search: { control: false },
@@ -41,11 +40,6 @@ export default meta
41
40
  type Story = StoryObj<typeof meta>
42
41
 
43
42
  const identity = <PersonTrigger name="Ana Duarte" />
44
- const menuButton = (
45
- <IconButton tooltip="Toggle menu" tooltipPlacement="bottom" aria-label="Toggle menu">
46
- <IconMenu2 size={16} stroke={1.5} />
47
- </IconButton>
48
- )
49
43
 
50
44
  const placeholder = <IconSquareRounded size={16} stroke={1.5} />
51
45
 
@@ -64,6 +58,26 @@ const rail = (
64
58
  </Rail>
65
59
  )
66
60
 
61
+ /**
62
+ * Folds from the top bar's menu button and comes back from the same place: folded, the navigation takes only the
63
+ * content's own margin and nothing in it can be seen; open, it takes its own width.
64
+ */
65
+ function foldsAndComesBack(margin: number, width: number) {
66
+ return async ({ canvasElement }: { canvasElement: HTMLElement }) => {
67
+ const canvas = within(canvasElement)
68
+ const nav = canvasElement.querySelector('nav') as HTMLElement
69
+ // The room the navigation takes beside the content: the folding box around it, which clips it.
70
+ const room = () => Math.round((nav.parentElement?.parentElement as HTMLElement).getBoundingClientRect().width)
71
+ await expect(room()).toBe(width)
72
+ await userEvent.click(canvas.getByRole('button', { name: 'Hide the sidebar' }))
73
+ await waitFor(() => expect(room()).toBe(margin), { timeout: 2000 })
74
+ await waitFor(() => expect(nav).not.toBeVisible())
75
+ await userEvent.click(canvas.getByRole('button', { name: 'Show the sidebar' }))
76
+ await waitFor(() => expect(room()).toBe(width), { timeout: 2000 })
77
+ await expect(nav).toBeVisible()
78
+ }
79
+ }
80
+
67
81
  /** The structured frame: solid bar, sidebar, content beside it. */
68
82
  export const Solid: Story = {
69
83
  render: (args) => (
@@ -89,6 +103,31 @@ export const SolidScrolls: Story = {
89
103
  ),
90
104
  }
91
105
 
106
+ /** The sidebar folds from the top bar's menu button: it narrows and fades in 300ms, and the content takes the room. */
107
+ export const SolidFolds: Story = {
108
+ render: function Render(args) {
109
+ const [open, setOpen] = useState(true)
110
+ return (
111
+ <AppShell {...args} logo="Estiva" onSearch={() => {}} identity={identity} nav={sidebar} navOpen={open} onNavOpenChange={setOpen}>
112
+ <EmptyState message="Nothing here yet." />
113
+ </AppShell>
114
+ )
115
+ },
116
+ play: foldsAndComesBack(0, 240),
117
+ }
118
+
119
+ /** `useSidebarFold` keeps it: fold the sidebar, reload the page, and it is still folded. */
120
+ export const RemembersItsFold: Story = {
121
+ render: function Render(args) {
122
+ const [open, setOpen] = useSidebarFold({ storageKey: 'estiva-ui.stories.sidebarFolded' })
123
+ return (
124
+ <AppShell {...args} logo="Estiva" onSearch={() => {}} identity={identity} nav={sidebar} navOpen={open} onNavOpenChange={setOpen}>
125
+ <EmptyState message="Fold the sidebar, then reload the page." />
126
+ </AppShell>
127
+ )
128
+ },
129
+ }
130
+
92
131
  export const SolidWithBanner: Story = {
93
132
  render: (args) => (
94
133
  <AppShell {...args} logo="Estiva" identity={identity} nav={sidebar} banner={<Banner tone="ok">Public key copied.</Banner>}>
@@ -107,7 +146,7 @@ export const Inset: Story = {
107
146
  ),
108
147
  }
109
148
 
110
- /** The navigation folds away from the top bar's menu button, and comes back from the same place. */
149
+ /** Folded, the inset card keeps a left margin as wide as its right one. */
111
150
  export const InsetFolds: Story = {
112
151
  args: { variant: 'inset' },
113
152
  render: function Render(args) {
@@ -118,16 +157,7 @@ export const InsetFolds: Story = {
118
157
  </AppShell>
119
158
  )
120
159
  },
121
- // Measured as drawn: in a Tailwind 3 app the `hidden` attribute alone loses to a display class (LED-3, 0.90.0).
122
- play: async ({ canvasElement }) => {
123
- const canvas = within(canvasElement)
124
- const drawn = () => canvasElement.querySelector('nav')?.getBoundingClientRect().width ?? 0
125
- await expect(drawn()).toBeGreaterThan(0)
126
- await userEvent.click(canvas.getByRole('button', { name: 'Hide the sidebar' }))
127
- await expect(drawn()).toBe(0)
128
- await userEvent.click(canvas.getByRole('button', { name: 'Show the sidebar' }))
129
- await expect(drawn()).toBeGreaterThan(0)
130
- },
160
+ play: foldsAndComesBack(16, 240),
131
161
  }
132
162
 
133
163
  export const InsetWithBanner: Story = {
@@ -142,27 +172,31 @@ export const InsetWithBanner: Story = {
142
172
  /** The floating frame: the bar floats over the top edge, the rail stands on the background, and the content lives in the rounded card. */
143
173
  export const Floating: Story = {
144
174
  render: (args) => (
145
- <AppShell
146
- {...args}
147
- variant="floating"
148
- menu={menuButton}
149
- logo="Estiva"
150
- onSearch={() => {}}
151
- identity={identity}
152
- nav={rail}
153
- >
175
+ <AppShell {...args} variant="floating" logo="Estiva" onSearch={() => {}} identity={identity} nav={rail}>
154
176
  <EmptyState message="Nothing here yet." />
155
177
  </AppShell>
156
178
  ),
157
179
  }
158
180
 
181
+ /** The rail folds as the sidebar does, to the 16px the card keeps from the window's edge. */
182
+ export const FloatingFolds: Story = {
183
+ render: function Render(args) {
184
+ const [open, setOpen] = useState(true)
185
+ return (
186
+ <AppShell {...args} variant="floating" logo="Estiva" onSearch={() => {}} identity={identity} nav={rail} navOpen={open} onNavOpenChange={setOpen}>
187
+ <EmptyState message="Nothing here yet." />
188
+ </AppShell>
189
+ )
190
+ },
191
+ play: foldsAndComesBack(16, 64),
192
+ }
193
+
159
194
  /** In the floating frame the banner draws inside the card, at its top. */
160
195
  export const FloatingWithBanner: Story = {
161
196
  render: (args) => (
162
197
  <AppShell
163
198
  {...args}
164
199
  variant="floating"
165
- menu={menuButton}
166
200
  logo="Estiva"
167
201
  identity={identity}
168
202
  nav={rail}
@@ -6,11 +6,11 @@
6
6
  * and whether an inner region still scrolls on its own, is measured in
7
7
  * Chrome on Ship's four pages.
8
8
  */
9
- import { afterEach, describe, expect, it } from 'vitest'
9
+ import { afterEach, describe, expect, it, vi } from 'vitest'
10
10
  import { useState } from 'react'
11
11
  import { cleanup, render, screen } from '@testing-library/react'
12
12
  import userEvent from '@testing-library/user-event'
13
- import { AppShell } from './AppShell'
13
+ import { AppShell, useSidebarFold, type SidebarFoldOptions } from './AppShell'
14
14
  import { Sidebar } from './Sidebar'
15
15
 
16
16
  afterEach(cleanup)
@@ -60,13 +60,15 @@ describe('AppShell', () => {
60
60
  const user = userEvent.setup()
61
61
  render(<Folding />)
62
62
  await user.click(screen.getByRole('button', { name: 'Hide the sidebar' }))
63
- expect(screen.queryByRole('navigation')).toBeNull()
63
+ // Folded, nothing in it can be reached; it stays mounted, to come back as it was left.
64
+ expect(screen.getByRole('navigation').closest('[inert]')).not.toBeNull()
64
65
  expect(screen.getByText('Page')).toBeTruthy()
65
66
  await user.click(screen.getByRole('button', { name: 'Show the sidebar' }))
67
+ expect(screen.getByRole('navigation').closest('[inert]')).toBeNull()
66
68
  expect(screen.getByRole('navigation').textContent).toBe('Rows')
67
69
  })
68
70
 
69
- it('keeps a menu the caller passes in place of the fold, and draws no fold on the floating rail', () => {
71
+ it('keeps a menu the caller passes in place of the fold, and folds the floating rail as the sidebar', async () => {
70
72
  const { unmount } = render(
71
73
  <AppShell variant="inset" menu={<button>Own menu</button>} nav={<Sidebar>Rows</Sidebar>} navOpen onNavOpenChange={() => {}}>
72
74
  <p>Page</p>
@@ -75,12 +77,18 @@ describe('AppShell', () => {
75
77
  expect(screen.getByRole('button', { name: 'Own menu' })).toBeTruthy()
76
78
  expect(screen.queryByRole('button', { name: /sidebar/ })).toBeNull()
77
79
  unmount()
78
- render(
79
- <AppShell variant="floating" nav={<nav>Rail</nav>} navOpen onNavOpenChange={() => {}}>
80
- <p>Page</p>
81
- </AppShell>,
82
- )
83
- expect(screen.queryByRole('button', { name: /sidebar/ })).toBeNull()
80
+ function Floating() {
81
+ const [open, setOpen] = useState(true)
82
+ return (
83
+ <AppShell variant="floating" nav={<nav>Rail</nav>} navOpen={open} onNavOpenChange={setOpen}>
84
+ <p>Page</p>
85
+ </AppShell>
86
+ )
87
+ }
88
+ render(<Floating />)
89
+ await userEvent.click(screen.getByRole('button', { name: 'Hide the sidebar' }))
90
+ expect(screen.getByRole('navigation').closest('[inert]')).not.toBeNull()
91
+ expect(screen.getByRole('button', { name: 'Show the sidebar' })).toBeTruthy()
84
92
  })
85
93
 
86
94
  it('draws no fold when the caller does not keep one', () => {
@@ -120,3 +128,77 @@ describe('AppShell', () => {
120
128
  expect(solid.container.querySelector('.signal-canvas')).toBeNull()
121
129
  })
122
130
  })
131
+
132
+ /** Folded stays folded on this browser (LED-3, Miky, 28 October; every app's, Katerina, 31 October). */
133
+ describe('useSidebarFold', () => {
134
+ afterEach(() => {
135
+ vi.restoreAllMocks()
136
+ vi.unstubAllGlobals()
137
+ window.localStorage.clear()
138
+ })
139
+ /** A fresh page load: the fold is read once per load, so each load takes the module again. */
140
+ async function load(how: 'navigate' | 'reload' = 'navigate') {
141
+ vi.resetModules()
142
+ vi.spyOn(performance, 'getEntriesByType').mockReturnValue([{ type: how }] as unknown as PerformanceEntryList)
143
+ const { useSidebarFold: fresh } = await import('./AppShell')
144
+ return function Shell(options: Partial<SidebarFoldOptions>) {
145
+ const [open, setOpen] = fresh({ storageKey: 'app.sidebarFolded', ...options })
146
+ return (
147
+ <AppShell nav={<nav>Rows</nav>} navOpen={open} onNavOpenChange={setOpen}>
148
+ <p>Page</p>
149
+ </AppShell>
150
+ )
151
+ }
152
+ }
153
+ const folded = () => window.localStorage.setItem('app.sidebarFolded', '1')
154
+
155
+ it('keeps the sidebar folded after a reload, until it is shown again', async () => {
156
+ let Shell = await load()
157
+ const first = render(<Shell />)
158
+ await userEvent.click(screen.getByRole('button', { name: 'Hide the sidebar' }))
159
+ first.unmount()
160
+ Shell = await load('reload')
161
+ const reloaded = render(<Shell />)
162
+ await userEvent.click(screen.getByRole('button', { name: 'Show the sidebar' }))
163
+ reloaded.unmount()
164
+ Shell = await load('reload')
165
+ render(<Shell />)
166
+ expect(screen.getByRole('button', { name: 'Hide the sidebar' })).toBeTruthy()
167
+ })
168
+
169
+ it('unfolds for a file opened from a link, and stays unfolded on this browser', async () => {
170
+ folded()
171
+ const Shell = await load('navigate')
172
+ render(<Shell isFile={() => true} />)
173
+ expect(screen.getByRole('button', { name: 'Hide the sidebar' })).toBeTruthy()
174
+ expect(window.localStorage.getItem('app.sidebarFolded')).toBeNull()
175
+ })
176
+
177
+ it('stays folded on a reload of the file, and on a page that is not a file', async () => {
178
+ folded()
179
+ let Shell = await load('reload')
180
+ const reloaded = render(<Shell isFile={() => true} />)
181
+ expect(screen.getByRole('button', { name: 'Show the sidebar' })).toBeTruthy()
182
+ reloaded.unmount()
183
+ Shell = await load('navigate')
184
+ render(<Shell isFile={() => false} />)
185
+ expect(screen.getByRole('button', { name: 'Show the sidebar' })).toBeTruthy()
186
+ })
187
+
188
+ it('stays as it was left when a page draws its frame again, even on a file reached by a link', async () => {
189
+ const Shell = await load('navigate')
190
+ const list = render(<Shell isFile={() => false} />)
191
+ await userEvent.click(screen.getByRole('button', { name: 'Hide the sidebar' }))
192
+ list.unmount()
193
+ render(<Shell isFile={() => true} />)
194
+ expect(screen.getByRole('button', { name: 'Show the sidebar' })).toBeTruthy()
195
+ })
196
+
197
+ it('opens folded in a window too narrow for it, whatever was kept, and keeps nothing for it', async () => {
198
+ vi.stubGlobal('matchMedia', (query: string) => ({ matches: query === '(max-width: 1023px)' }))
199
+ const Shell = await load()
200
+ render(<Shell foldWhen="(max-width: 1023px)" />)
201
+ expect(screen.getByRole('button', { name: 'Show the sidebar' })).toBeTruthy()
202
+ expect(window.localStorage.getItem('app.sidebarFolded')).toBeNull()
203
+ })
204
+ })
package/src/AppShell.tsx CHANGED
@@ -1,8 +1,9 @@
1
- import type { ReactNode } from 'react'
1
+ import { useCallback, useState, type ReactNode } from 'react'
2
2
  import { IconLayoutSidebarLeftCollapse, IconLayoutSidebarLeftExpand } from '@tabler/icons-react'
3
3
  import { cn } from './cn'
4
4
  import { Card } from './Card'
5
5
  import { IconButton } from './IconButton'
6
+ import { FOLDED_CLASSES, FOLD_MOTION_CLASSES, UNFOLDED_CLASSES } from './looks'
6
7
  import { ScrollArea } from './ScrollArea'
7
8
  import { SidebarOnGround } from './Sidebar'
8
9
  import { TopBar } from './TopBar'
@@ -18,7 +19,7 @@ import { TopBar } from './TopBar'
18
19
  * - `floating` — the floating frame: the TopBar floats over the top
19
20
  * edge, the rail stands on the app background, and the content lives
20
21
  * in the rounded card beside it (2026-09-02, the floating app's frame
21
- * geometry; its collapse animation and launcher stay in the app).
22
+ * geometry; its launcher stays in the app).
22
23
  * - `inset` — the structured frame, the other way round: the TopBar and
23
24
  * the Sidebar stand on the ground, and the content is a lighter card
24
25
  * beside them (Katerina, 28 September: Linear's layout, in any theme).
@@ -32,7 +33,7 @@ import { TopBar } from './TopBar'
32
33
  */
33
34
  export interface AppShellProps {
34
35
  variant?: 'solid' | 'floating' | 'inset'
35
- /** The top bar's menu button, in an app whose navigation collapses. */
36
+ /** The top bar's menu button, in place of the fold `onNavOpenChange` draws. */
36
37
  menu?: ReactNode
37
38
  /** The top bar's left: the app's logo mark, or its name as text. */
38
39
  logo?: ReactNode
@@ -49,10 +50,10 @@ export interface AppShellProps {
49
50
  /** The navigation: a `Sidebar` in the solid manner, a `Rail` in the floating one. */
50
51
  nav: ReactNode
51
52
  /**
52
- * Whether the navigation is shown, in the solid and inset manners. With `onNavOpenChange`, the frame draws the
53
- * fold as the top bar's menu button (unless `menu` is given) and, folded, leaves only the content's own margin
54
- * (LED-3, Katerina, 28 October: the sidebar fold top left, on the top bar's menu button). Where it is kept is
55
- * the caller's.
53
+ * Whether the navigation is shown. With `onNavOpenChange`, the frame draws the fold as the top bar's menu button
54
+ * (unless `menu` is given), in every manner, and folding narrows and fades the navigation to the content's own
55
+ * margin (LED-3, Katerina, 28 October: the sidebar fold top left, on the top bar's menu button; one fold in every
56
+ * app, with Peek's motion, 31 October). Where it is kept is the caller's: `useSidebarFold` remembers it.
56
57
  */
57
58
  navOpen?: boolean
58
59
  onNavOpenChange?: (open: boolean) => void
@@ -60,8 +61,7 @@ export interface AppShellProps {
60
61
  }
61
62
 
62
63
  export function AppShell({ variant = 'solid', menu, logo, search, onSearch, searchPlaceholder, identity, banner, nav, navOpen = true, onNavOpenChange, children }: AppShellProps) {
63
- // The floating manner's rail does not fold here: its collapse stays the app's.
64
- const fold = onNavOpenChange && variant !== 'floating' && (
64
+ const fold = onNavOpenChange && (
65
65
  <IconButton
66
66
  tooltip={navOpen ? 'Hide the sidebar' : 'Show the sidebar'}
67
67
  tooltipPlacement="bottom"
@@ -75,6 +75,30 @@ export function AppShell({ variant = 'solid', menu, logo, search, onSearch, sear
75
75
  const bar = <TopBar variant={variant} menu={menu ?? fold} logo={logo} search={search} onSearch={onSearch} searchPlaceholder={searchPlaceholder} right={identity} />
76
76
  const inset = variant === 'inset'
77
77
 
78
+ /* Folding, in every manner, as Peek's rail did (Katerina, 31 October): the navigation narrows and fades in 300ms,
79
+ to the content's own margin — none in the solid manner, 16px in the others, as wide as the right one. The
80
+ narrowing is a grid track going from `1fr` to `0fr`: the navigation keeps its own width and the track clips it,
81
+ so nothing here measures it. Folded, it stays mounted and comes back as it was left (its scroll, its open
82
+ rows), and nothing in it can be reached: inert at once, hidden once it has faded. */
83
+ const margin = variant === 'solid' ? 0 : 16
84
+ const folding = (
85
+ <div
86
+ className={cn('grid shrink-0 transition-[grid-template-columns]', FOLD_MOTION_CLASSES)}
87
+ style={{ gridTemplateColumns: navOpen ? '0px 1fr' : `${margin}px 0fr` }}
88
+ >
89
+ <div
90
+ inert={!navOpen}
91
+ className={cn(
92
+ 'col-start-2 flex min-w-0 overflow-hidden transition-[opacity,visibility]',
93
+ FOLD_MOTION_CLASSES,
94
+ navOpen ? UNFOLDED_CLASSES : FOLDED_CLASSES,
95
+ )}
96
+ >
97
+ <SidebarOnGround.Provider value={inset}>{nav}</SidebarOnGround.Provider>
98
+ </div>
99
+ </div>
100
+ )
101
+
78
102
  if (variant === 'floating') {
79
103
  return (
80
104
  // `signal-canvas`: in the Signal theme, the preset draws the control-room dot
@@ -83,7 +107,7 @@ export function AppShell({ variant = 'solid', menu, logo, search, onSearch, sear
83
107
  <div className="signal-canvas relative h-full min-h-0 overflow-hidden bg-bg-base">
84
108
  {bar}
85
109
  <div className="flex h-full pb-4 pr-4 pt-[52px]">
86
- {nav}
110
+ {folding}
87
111
  <div
88
112
  className={cn(
89
113
  'flex min-w-0 flex-1 flex-col overflow-hidden rounded-2xl bg-bg-surface',
@@ -135,14 +159,7 @@ export function AppShell({ variant = 'solid', menu, logo, search, onSearch, sear
135
159
  <div className="relative flex h-full min-h-0 flex-col overflow-hidden bg-bg-base text-text-primary">
136
160
  {bar}
137
161
  <div className="flex min-h-0 flex-1">
138
- {/* Folded, the navigation stays mounted and hidden, so it comes back as it was left (its scroll, its open
139
- rows); open, `contents` keeps it a direct flex child of the row. Hidden by the class as well as the
140
- attribute: in a Tailwind 3 app `[hidden]` loses to `.contents`, and the sidebar stayed drawn (0.90.0). */}
141
- <div className={navOpen ? 'contents' : 'hidden'} hidden={!navOpen}>
142
- <SidebarOnGround.Provider value={inset}>{nav}</SidebarOnGround.Provider>
143
- </div>
144
- {/* Folded: the inset card keeps a left margin as wide as its right one. */}
145
- {!navOpen && inset && <div className="w-4 flex-none" />}
162
+ {folding}
146
163
  {/* `inset`: the content is a card on the ground, the Card's own surface look,
147
164
  16px from the right and bottom as the floating card is, 8px corners (Katerina,
148
165
  28 September). */}
@@ -157,3 +174,76 @@ export function AppShell({ variant = 'solid', menu, logo, search, onSearch, sear
157
174
  </div>
158
175
  )
159
176
  }
177
+
178
+ export interface SidebarFoldOptions {
179
+ /** Where this browser keeps a folded sidebar: the app's own key, such as `ship.sidebarFolded`. */
180
+ storageKey: string
181
+ /**
182
+ * Whether the page open now is a file. A file opened from a link — another app's card, a link in a message —
183
+ * shows where it lives, so a folded sidebar unfolds for it, as its button would, and stays unfolded (Katerina,
184
+ * 30 October). Not on a reload, which keeps the sidebar as the person left it.
185
+ */
186
+ isFile?: () => boolean
187
+ /** A media query: a window that matches it opens folded, whatever was kept, with no room beside the page (Leaf's, `(max-width: 1023px)`). */
188
+ foldWhen?: string
189
+ }
190
+
191
+ const FOLDED = '1'
192
+
193
+ function keptFolded(key: string): boolean {
194
+ try {
195
+ return window.localStorage.getItem(key) === FOLDED
196
+ } catch {
197
+ return false
198
+ }
199
+ }
200
+
201
+ function keepFolded(key: string, folded: boolean) {
202
+ try {
203
+ if (folded) window.localStorage.setItem(key, FOLDED)
204
+ else window.localStorage.removeItem(key)
205
+ } catch {
206
+ // Storage refused (private mode, full): it folds for this visit only.
207
+ }
208
+ }
209
+
210
+ function reloaded(): boolean {
211
+ const [entry] = (typeof performance.getEntriesByType === 'function' ? performance.getEntriesByType('navigation') : []) as PerformanceNavigationTiming[]
212
+ return entry?.type === 'reload'
213
+ }
214
+
215
+ /**
216
+ * Each sidebar as it stands since this page loaded, by its key: a frame drawn again — a page that draws its own —
217
+ * finds it as it was left. The arrival and the window's width are read once, when the page loads, as Leaf's were.
218
+ */
219
+ const shown = new Map<string, boolean>()
220
+
221
+ function onLoad({ storageKey, isFile, foldWhen }: SidebarFoldOptions): boolean {
222
+ if (foldWhen && typeof window.matchMedia === 'function' && window.matchMedia(foldWhen).matches) return false
223
+ if (!keptFolded(storageKey)) return true
224
+ if (!isFile?.() || reloaded()) return false
225
+ keepFolded(storageKey, false)
226
+ return true
227
+ }
228
+
229
+ /**
230
+ * Whether the sidebar is shown, and the setter that remembers it, for `AppShell`'s `navOpen` and
231
+ * `onNavOpenChange`: folded stays folded on this browser, across pages and reloads, until unfolded (Ship's and
232
+ * Leaf's since LED-3, Miky, 28 October; every app's, Katerina, 31 October).
233
+ */
234
+ export function useSidebarFold(options: SidebarFoldOptions): [open: boolean, setOpen: (open: boolean) => void] {
235
+ const { storageKey } = options
236
+ const [open, setOpen] = useState(() => {
237
+ if (!shown.has(storageKey)) shown.set(storageKey, onLoad(options))
238
+ return shown.get(storageKey) as boolean
239
+ })
240
+ const change = useCallback(
241
+ (next: boolean) => {
242
+ setOpen(next)
243
+ shown.set(storageKey, next)
244
+ keepFolded(storageKey, !next)
245
+ },
246
+ [storageKey],
247
+ )
248
+ return [open, change]
249
+ }
@@ -0,0 +1,46 @@
1
+ import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
2
+ import * as Stories from './ArchivedNotice.stories'
3
+
4
+ <Meta of={Stories} />
5
+
6
+ # ArchivedNotice
7
+
8
+ The card an archived file shows: who archived it and when, the resolution they gave, and the way back.
9
+
10
+ <Canvas of={Stories.Archived} />
11
+
12
+ ## When
13
+
14
+ - At the top of an archived file's page, under its title.
15
+ - In the comment box's place on an archived file's page: there is nothing to write, and the card says why.
16
+ - Archived with a file above it, it names that one and opens it, since it is restored there.
17
+
18
+ <Canvas of={Stories.WithItsParent} />
19
+
20
+ ## When not
21
+
22
+ - One line in a closed comment box → **CommentBox**'s `closed`, with **archivedLine**'s words.
23
+ - News for the whole app, under the top bar → **Banner**.
24
+
25
+ ## How
26
+
27
+ ```tsx
28
+ import { ArchivedNotice } from '@estiva-app/ui'
29
+
30
+ <ArchivedNotice by={name} when={day} resolution={resolution} onUnarchive={unarchive} />
31
+ <ArchivedNotice by={name} when={day} withWhat="project" withTitle={title} onOpenParent={openProject} />
32
+ ```
33
+
34
+ - Give `when` its day, in the app's words: "Today", "Tue, Oct 28".
35
+ - Leave out `onUnarchive` when the reader cannot restore it: the card offers nothing.
36
+
37
+ ## What it owns
38
+
39
+ | It does | So you never write | Refused when written by hand |
40
+ |---|---|---|
41
+ | Waits for Unarchive's answer, and ignores a second press meanwhile | a busy state | |
42
+ | Says "Archived with its project “Title”" and offers Open project when it has one above it | the sentence and the button | |
43
+
44
+ ## Props
45
+
46
+ <Controls />
@@ -0,0 +1,52 @@
1
+ import type { Meta, StoryObj } from '@storybook/react-vite'
2
+ import { fn, userEvent, within } from 'storybook/test'
3
+ import { ArchivedNotice } from './ArchivedNotice'
4
+
5
+ /** The card at the top of an archived file, and in the comment box's place on its page. */
6
+ const meta = {
7
+ title: 'Status & feedback/ArchivedNotice',
8
+ component: ArchivedNotice,
9
+ parameters: { layout: 'padded' },
10
+ args: {
11
+ by: 'Person two',
12
+ when: 'Tue, Oct 28',
13
+ resolution: 'Shipped in the October release. The follow-ups live in the next project.',
14
+ onUnarchive: fn(),
15
+ },
16
+ decorators: [(Story) => <div className="max-w-xl">{Story()}</div>],
17
+ } satisfies Meta<typeof ArchivedNotice>
18
+
19
+ export default meta
20
+ type Story = StoryObj<typeof meta>
21
+
22
+ /** Archived by itself: who, when, the resolution, and Unarchive. */
23
+ export const Archived: Story = {}
24
+
25
+ /** Archived with no resolution: the line alone. */
26
+ export const NoResolution: Story = { name: 'No resolution', args: { resolution: undefined } }
27
+
28
+ /** Archived with the project above it: restored there, so it opens that project. */
29
+ export const WithItsParent: Story = {
30
+ name: 'With its parent',
31
+ args: { withWhat: 'project', withTitle: 'October release', resolution: undefined, onUnarchive: undefined, onOpenParent: fn() },
32
+ }
33
+
34
+ /** A resolution over several lines keeps its line breaks. */
35
+ export const LongResolution: Story = {
36
+ name: 'Long resolution',
37
+ args: {
38
+ resolution:
39
+ 'Shipped in the October release.\nThe two open questions moved to the next project, with their comments.\nThe old drafts stay here to read.',
40
+ },
41
+ }
42
+
43
+ /** Nothing can be done from here: the reader cannot restore it. */
44
+ export const ReadOnly: Story = { name: 'Read-only', args: { onUnarchive: undefined } }
45
+
46
+ /** Unarchive pressed: it waits for the answer, and a second press does nothing. */
47
+ export const Unarchiving: Story = {
48
+ args: { onUnarchive: fn(() => new Promise<void>(() => {})) },
49
+ play: async ({ canvasElement }) => {
50
+ await userEvent.click(within(canvasElement).getByRole('button', { name: 'Unarchive' }))
51
+ },
52
+ }