1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
// Copyright © The Daybrite Project
// SPDX-License-Identifier: MPL-2.0
//! Ambient state: values a piece reads without being handed them.
//!
//! Two families live here. The first is what a backend reports about a window
//! (docs/size-classes.md): its [`SizeClass`] and its safe-area insets. The second is what an
//! app provides for its own subtree (docs/state.md): [`with_environment`] / [`environment`],
//! and the [`Ambient`] trait over them that carries per-window and app-wide state.
//!
//! They sit together because they answer the same question from opposite ends, and because the
//! app half belongs below day-pieces: an app's `*-core` crate holds its view-model and has to be
//! able to `impl Ambient` for it, which the orphan rule forbids when the trait lives one crate
//! further up.
//!
//! Both are reactive, so a piece that reads one re-runs when the backend reports a new value, and
//! both are keyed by window root for the same reason [`crate::toolbar`] is: one process can show
//! two windows at different sizes at once (a narrow window beside a wide one, iPadOS Stage
//! Manager, Android split-screen), and a single global would lay the second window out for the
//! first one's size.
//!
//! Signals are created in the root reactive scope. Backends report from native callbacks that can
//! fire while some transient scope is current, and a signal owned by a scope that later disposes
//! would take the window's state with it.
use RefCell;
use ;
use SizeClass;
use cratePiece;
use crate::;
use crate;
/// The reactive values one window carries.
tls_slots!
/// One window's signals, created on first touch.
///
/// Returns them by value and drops the registry borrow before the caller touches either. Writing
/// a signal runs its bindings synchronously, and those bindings read ambient state (a nav host
/// re-presenting on a class change reads the class right back), so holding the borrow across a
/// write is a reentrant panic waiting to happen.
/// Seeded from the launch environment so a page built during startup, before the backend's first
/// live report lands, already sees the right top inset (the same lazy-env pattern as
/// `layout_direction`/`DAY_LOCALE`). Points, not px.
/// Backend-facing: the first window's safe-area insets, known before its content builds and
/// before the tree that owns them exists (an overlay title bar's height, docs/window-chrome.md).
/// The first window's content reads them at build time; later changes go through
/// [`set_safe_area`].
/// The window a read or report targets: the one being built, else the primary root. Shared with
/// [`crate::toolbar`], which scopes the same way for the same reason: an app's one `toolbar(…)`
/// or `size_class()` call inside a shared `build_shell` must mean "this window".
/// The current window's size class, or `None` on a backend that does not report one yet.
/// Tracked: a piece that lays out from this rebuilds when the window crosses a breakpoint.
///
/// Outside a window's content build this reads the primary window, so a long-lived effect that
/// wants a secondary window's class must capture its root at build time and use
/// [`window_size_class`], the same discipline `toolbar_reactive` follows.
/// [`size_class`] against an explicit window root.
/// [`size_class`] without subscribing, for code that reacts to the change itself.
/// Backend-facing: report a window's size class. Call whenever the window's size changes; the
/// signal only notifies when the bucket changes, so a resize within one class is free.
/// [`set_window_size_class`] against the primary window, which is what a single-window backend
/// reports.
/// Force a class the window is not at: dayscript's `size_class:` step and tests.
///
/// Leaves the reported class alone: this is a claim about the window, not a report from it, so
/// [`restore_reported_size_class`] can still put back what the backend last said. The force
/// holds until then, through any reports the backend makes in the meantime.
/// Undo an [`override_size_class`]: back to the class the window itself last reported.
///
/// A no-op where the backend has reported nothing yet: there is nothing to restore, and the
/// forced class is better than none.
/// The window's safe-area insets, in points. Zero on every backend that clamps Day's root to
/// the safe area natively (the default everywhere); nonzero only where a backend runs the root
/// edge-to-edge, today day-toolkit-material's opt-in immersive mode (docs/layout.md, the android
/// platform page). Compose it yourself where a background should run under the system bars:
/// paint the background unpadded, pad the content by these insets. The read is tracked, but
/// layout attributes like `.padding` capture the value at build time, so a mid-run inset change
/// (rotation) does not re-pad already-built pages.
/// [`safe_area`] against an explicit window root.
/// Backend-facing: report a window's safe-area insets (points). Call from the native inset pass
/// whenever the value changes; apps observe it through [`safe_area`].
/// [`set_window_safe_area`] against the primary window, which is what a single-window backend
/// reports.
/// Drop a closed window's ambient state (called from the window teardown path).
pub
/// Reset every window's ambient state (tests; pairs with `uninstall_tree`).
// ---------------------------------------------------------------------------
// @Environment: ambient values over day-reactive's scope context (§4.3). No backend work.
// ---------------------------------------------------------------------------
/// Provide an ambient value `T` to `content` and its entire descendant subtree (the SwiftUI
/// `@Environment`/`.environment(_)` analog, layered over day-reactive's scope context). `content`,
/// and any piece built within it, reads it back with [`environment`]. A thin, non-reactive
/// wrapper: `T` is a snapshot captured here; for a value that must react, provide a `Signal<T>`
/// (or a `Memo<T>`) and read it reactively inside the subtree.
///
/// ```ignore
/// #[derive(Clone)] struct Theme { accent: Color }
/// with_environment(Theme { accent: BLUE }, || my_screen())
/// // deep inside my_screen(): let accent = environment::<Theme>().unwrap().accent;
/// ```
/// Read the nearest ambient `T` provided by an enclosing [`with_environment`], or `None` if none is
/// in scope. Call it while constructing or building a piece within that subtree.
/// The ambient `T` of the window that currently has focus (docs/state.md): SwiftUI's
/// `@FocusedValue`.
///
/// [`environment`] answers "what did my ancestors provide", which is the right question inside a
/// piece and the wrong one inside an app-wide menu action: a desktop menu bar is one bar for the
/// whole app, and its commands act on the front window. This resolves through that window's own
/// scope instead of the calling scope, so `File ▸ New Item` adds to the list the user is
/// looking at. A cover that provides no `T` answers with the primary window's, since the
/// cover renders inside it (following the window scope chain). `None` ⇒ no window is
/// open, or the front one provides no `T`.
/// The app-wide `T`: created on the reactive root scope the first time it is asked for, and
/// returned unchanged by every later call (docs/state.md).
///
/// The counterpart to [`with_environment`]'s subtree scope: state that belongs to the app
/// rather than to a window or a page, reachable from every window, every menu action, and every
/// task, and alive for as long as the process. `make` runs at most once.
/// State an ancestor provides once and any descendant reads back by type: SwiftUI's
/// `@EnvironmentObject`, and Day's answer to "where does app state live?" (docs/state.md).
///
/// Implement it on a `Copy` struct of handles. `Signal`, `Memo`, `Trigger` and `Store` are all
/// `Copy` and all cheap, so the struct is a bundle of pointers that rides into closures without
/// `Rc` or `clone()` ceremony:
///
/// ```ignore
/// #[derive(Clone, Copy)]
/// struct Scene { selected: Signal<Option<u32>>, items: Store<Keyed<Item>> }
///
/// impl Ambient for Scene {
/// fn create() -> Self { Scene { selected: Signal::new(None), items: Store::new(..) } }
/// }
///
/// // one per window; File ▸ New Window gets its own:
/// Scene::scoped(|scene| my_shell(scene))
/// // anywhere below it:
/// let scene = Scene::ambient();
/// // in an app-wide menu action, which belongs to no window:
/// menu_item("New").action(|| if let Some(s) = Scene::focused() { s.add() })
/// ```
///
/// The alternative, a `thread_local!` holding `Signal::global`, is one instance for the whole
/// process, which is indistinguishable from correct until the app opens a second window
/// (docs/windows.md) and both windows start sharing a selection.