@sentropic/design-system-svelte 0.34.72 → 0.34.75

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 (49) hide show
  1. package/README.md +31 -1
  2. package/dist/PanelSection.svelte +243 -0
  3. package/dist/PanelSection.svelte.d.ts +13 -0
  4. package/dist/PanelSection.svelte.d.ts.map +1 -0
  5. package/dist/PanelStack.svelte +509 -0
  6. package/dist/PanelStack.svelte.d.ts +89 -0
  7. package/dist/PanelStack.svelte.d.ts.map +1 -0
  8. package/dist/PanelStackFixture.svelte.d.ts +23 -0
  9. package/dist/PanelStackFixture.svelte.d.ts.map +1 -0
  10. package/dist/index.d.ts +4 -0
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +2 -0
  13. package/package.json +7 -2
  14. package/dist/AppChrome.test.d.ts +0 -2
  15. package/dist/AppChrome.test.d.ts.map +0 -1
  16. package/dist/AppChrome.test.js +0 -146
  17. package/dist/AppShell.panelCollapse.test.d.ts +0 -2
  18. package/dist/AppShell.panelCollapse.test.d.ts.map +0 -1
  19. package/dist/AppShell.panelCollapse.test.js +0 -129
  20. package/dist/AppShell.panelResize.test.d.ts +0 -2
  21. package/dist/AppShell.panelResize.test.d.ts.map +0 -1
  22. package/dist/AppShell.panelResize.test.js +0 -338
  23. package/dist/Collapsible.test.d.ts +0 -2
  24. package/dist/Collapsible.test.d.ts.map +0 -1
  25. package/dist/Collapsible.test.js +0 -76
  26. package/dist/ContourChart.test.d.ts +0 -2
  27. package/dist/ContourChart.test.d.ts.map +0 -1
  28. package/dist/ContourChart.test.js +0 -59
  29. package/dist/EventFeedPanel.test.d.ts +0 -2
  30. package/dist/EventFeedPanel.test.d.ts.map +0 -1
  31. package/dist/EventFeedPanel.test.js +0 -66
  32. package/dist/Icon.test.d.ts +0 -2
  33. package/dist/Icon.test.d.ts.map +0 -1
  34. package/dist/Icon.test.js +0 -38
  35. package/dist/PointAndFigureChart.test.d.ts +0 -2
  36. package/dist/PointAndFigureChart.test.d.ts.map +0 -1
  37. package/dist/PointAndFigureChart.test.js +0 -73
  38. package/dist/RenkoChart.test.d.ts +0 -2
  39. package/dist/RenkoChart.test.d.ts.map +0 -1
  40. package/dist/RenkoChart.test.js +0 -66
  41. package/dist/TimeRangePicker.test.d.ts +0 -2
  42. package/dist/TimeRangePicker.test.d.ts.map +0 -1
  43. package/dist/TimeRangePicker.test.js +0 -482
  44. package/dist/VectorFieldChart.test.d.ts +0 -2
  45. package/dist/VectorFieldChart.test.d.ts.map +0 -1
  46. package/dist/VectorFieldChart.test.js +0 -59
  47. package/dist/WindBarbChart.test.d.ts +0 -2
  48. package/dist/WindBarbChart.test.d.ts.map +0 -1
  49. package/dist/WindBarbChart.test.js +0 -65
@@ -0,0 +1,509 @@
1
+ <script lang="ts" module>
2
+ import type { Snippet } from "svelte";
3
+
4
+ export type PanelStackShape = "split-primary" | "sticky-item";
5
+
6
+ /**
7
+ * Bound ratified by the chat consumer lane: beyond 4 sections, stacking
8
+ * collapsible regions in a pane capped at 640px makes scrolling unmanageable
9
+ * and the single-owner rule becomes untenable. Enforced as a dev-time
10
+ * `console.warn` in `register()` (this package's established convention —
11
+ * see NavActionStack/WaterfallChart — is to warn and degrade, never throw
12
+ * or silently truncate); exported here so the bound is also visible through
13
+ * types/docs to a consumer reading `PanelStackProps`.
14
+ */
15
+ export const PANEL_STACK_MAX_SECTIONS = 4;
16
+
17
+ /**
18
+ * Default of `PanelStackProps.primaryMinHeight` (the primary section's
19
+ * usable floor, in px) — exported so a consumer can reference the default
20
+ * without hardcoding it. This is also the ONLY place the number is
21
+ * hardcoded: PanelStack mirrors the live `primaryMinHeight` prop (which
22
+ * defaults to this constant) onto the
23
+ * `--st-component-panelStack-primaryMinBlockSize` custom property on its
24
+ * own root, and the stylesheet's `min-block-size` reads that same
25
+ * property — so the JS auto-collapse threshold and the CSS floor read the
26
+ * same number and can no longer drift apart the way two independently
27
+ * hardcoded copies could.
28
+ */
29
+ export const PRIMARY_MIN_BLOCK_SIZE_PX = 160;
30
+
31
+ export type PanelStackProps = {
32
+ /** "sticky-item" (default): one section expanded at a time, all headers stay visible.
33
+ "split-primary": the `primary` section is always expanded and owns the scroll;
34
+ the others are content-sized disclosures. */
35
+ shape?: PanelStackShape;
36
+ /** Accessible name for the stack region. */
37
+ label?: string;
38
+ /** sticky-item, controlled: id of the expanded section. */
39
+ expanded?: string | null;
40
+ /** sticky-item, uncontrolled seed. */
41
+ defaultExpanded?: string | null;
42
+ onExpandedChange?: (id: string | null) => void;
43
+ /**
44
+ * split-primary: id of the section that owns the scroll. Falls back to the
45
+ * first EXPANDED section (DOM order) when unset or stale, and — if nothing
46
+ * is expanded — to the first registered section, so the stack never
47
+ * degrades to zero scroll owners.
48
+ */
49
+ primary?: string;
50
+ /** Usable floor for the primary section, in px. While the primary sits above it the
51
+ primary absorbs overflow; once it would drop below, a secondary auto-collapses
52
+ instead of compressing the primary further. Default 160. */
53
+ primaryMinHeight?: number;
54
+ /**
55
+ * At most {@link PANEL_STACK_MAX_SECTIONS} `PanelSection` children are
56
+ * supported — see that constant's doc comment for why.
57
+ */
58
+ children?: Snippet;
59
+ class?: string;
60
+ };
61
+
62
+ /**
63
+ * Context contract shared with PanelSection. Every shape-dependent branch
64
+ * (sticky-item vs split-primary) is decided HERE and only here — PanelSection
65
+ * never reads `shape`, it only calls these four functions/callback. If the
66
+ * consumer-lane contract for these two shapes changes, this is the one place
67
+ * to touch.
68
+ */
69
+ export const PANEL_STACK_KEY = Symbol("st-panel-stack");
70
+
71
+ export type PanelStackContext = {
72
+ /** Is this section the (non-collapsible) primary of a split-primary stack? */
73
+ isPrimary: (id: string) => boolean;
74
+ /** Is this section currently expanded (body visible, content-sized or scrolling)? */
75
+ isExpanded: (id: string) => boolean;
76
+ /** Is this section's body THE single scroll owner right now (flex:1 1 0, overflow:auto)? */
77
+ isScrollOwner: (id: string) => boolean;
78
+ /** Header was activated (click / Space / Enter on the disclosure button). */
79
+ toggle: (id: string) => void;
80
+ /**
81
+ * Register a section's root AND header element, in mount/DOM order;
82
+ * returns an unregister callback. NOT just bookkeeping — the stack falls
83
+ * back to the first registered section as the scroll owner whenever
84
+ * nothing else designates one (unset/stale `expanded` or `primary`), so
85
+ * the invariant "exactly one scroll owner whenever the stack has ≥1
86
+ * section" holds even for a misconfigured or dynamically-changing stack.
87
+ * `headerEl` is used only by split-primary's auto-collapse measurement
88
+ * (the header of whichever section is CURRENTLY primary is observed for
89
+ * its height); sticky-item ignores it.
90
+ */
91
+ register: (id: string, rootEl: HTMLElement, headerEl: HTMLElement) => () => void;
92
+ };
93
+ </script>
94
+
95
+ <script lang="ts">
96
+ import { setContext, untrack } from "svelte";
97
+
98
+ let {
99
+ shape = "sticky-item",
100
+ label,
101
+ expanded,
102
+ defaultExpanded = null,
103
+ onExpandedChange,
104
+ primary,
105
+ primaryMinHeight = PRIMARY_MIN_BLOCK_SIZE_PX,
106
+ children,
107
+ class: className
108
+ }: PanelStackProps = $props();
109
+
110
+ // --- Mount-order registry -------------------------------------------------
111
+ // Both fallbacks below ("the first registered section becomes the de-facto
112
+ // scroll owner") need to know which section is first, in DOM order — not
113
+ // effect-run order, which isn't guaranteed to match visual order once
114
+ // sections are reordered or conditionally rendered. Same registration
115
+ // technique as SelectableList/SelectableRow: a section registers its root
116
+ // element in an effect on mount and unregisters on destroy; the ordered view
117
+ // is derived lazily via `compareDocumentPosition` rather than sorted eagerly
118
+ // on every register.
119
+ type Entry = { id: string; el: HTMLElement; headerEl: HTMLElement };
120
+ let entries = $state<Entry[]>([]);
121
+
122
+ function sortByDom(list: Entry[]): Entry[] {
123
+ return [...list].sort((a, b) => {
124
+ const pos = a.el.compareDocumentPosition(b.el);
125
+ if (pos & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
126
+ if (pos & Node.DOCUMENT_POSITION_PRECEDING) return 1;
127
+ return 0;
128
+ });
129
+ }
130
+
131
+ const orderedEntries = $derived.by(() => sortByDom(entries));
132
+ const firstId = $derived(orderedEntries[0]?.id ?? null);
133
+
134
+ function register(id: string, el: HTMLElement, headerEl: HTMLElement): () => void {
135
+ untrack(() => {
136
+ entries = [...entries.filter((e) => e.el !== el), { id, el, headerEl }];
137
+ // Dev-time visibility only — see PANEL_STACK_MAX_SECTIONS' doc comment.
138
+ // Never truncated/hidden: every registered section still renders and
139
+ // participates normally, this is a nudge, not an enforcement mechanism.
140
+ if (entries.length > PANEL_STACK_MAX_SECTIONS) {
141
+ console.warn(
142
+ `[PanelStack] ${entries.length} sections registered — the stack is designed for at most ${PANEL_STACK_MAX_SECTIONS}. Beyond that, stacked collapsible regions in a capped pane become unmanageable to scroll and the single-scroll-owner contract gets hard to reason about. Consider splitting into multiple panes.`
143
+ );
144
+ }
145
+ });
146
+ const observer = ensureResizeObserver();
147
+ observer?.observe(el);
148
+ return () => {
149
+ observer?.unobserve(el);
150
+ untrack(() => {
151
+ entries = entries.filter((e) => e.el !== el);
152
+ // Drop any stale open/closed/measurement record for a section that no
153
+ // longer exists, so a LATER section re-registered under the same id
154
+ // doesn't silently inherit a dead instance's state.
155
+ if (openSecondary.has(id)) {
156
+ const next = new Set(openSecondary);
157
+ next.delete(id);
158
+ openSecondary = next;
159
+ }
160
+ if (autoCollapsed.has(id)) {
161
+ const next = new Set(autoCollapsed);
162
+ next.delete(id);
163
+ autoCollapsed = next;
164
+ }
165
+ if (expansionOrder.includes(id)) {
166
+ expansionOrder = expansionOrder.filter((x) => x !== id);
167
+ }
168
+ if (rootHeights.has(id)) {
169
+ const next = new Map(rootHeights);
170
+ next.delete(id);
171
+ rootHeights = next;
172
+ }
173
+ });
174
+ };
175
+ }
176
+
177
+ // Controlled vs uncontrolled `expanded` — same dual-prop idiom as
178
+ // SelectableList's `value`/`internal` (controlled whenever the prop is
179
+ // passed at all, including explicit `null`). `internalExpanded` is the raw
180
+ // seed / last explicit choice. `effectiveExpandedId` is the RAW resolved
181
+ // value — controlled or the uncontrolled/first-registered fallback — used
182
+ // below as `toggle`'s "is this already the selection" reference. It is NOT
183
+ // what `isExpanded` reports for sticky-item any more (see
184
+ // `effectiveScrollOwnerId` below): the two agree in every normal case, and
185
+ // diverge only for a controlled `expanded` matching no registered section.
186
+ const controlled = $derived(expanded !== undefined);
187
+ // `untrack`: this is a one-time SEED, not a live binding to `defaultExpanded`
188
+ // — same idiom as RangeSlider's `defaultValue`.
189
+ let internalExpanded = $state<string | null>(untrack(() => defaultExpanded));
190
+
191
+ const effectiveExpandedId = $derived.by((): string | null => {
192
+ if (controlled) return expanded ?? null;
193
+ if (internalExpanded !== null && entries.some((e) => e.id === internalExpanded)) {
194
+ return internalExpanded;
195
+ }
196
+ return firstId;
197
+ });
198
+
199
+ // sticky-item's expanded-AND-scroll-owner section — the two are the same
200
+ // thing by definition in this shape (exactly one section is expanded and
201
+ // it owns the scroll), so this single value backs BOTH `isExpanded` and
202
+ // `isScrollOwner` for sticky-item. Normally identical to
203
+ // `effectiveExpandedId` above, with ONE exception: a controlled `expanded`
204
+ // set to a STRING that matches no registered section. The consumer clearly
205
+ // intended some section open and got none — that is content unreachable by
206
+ // the wheel, the one state this whole component pair exists to prevent —
207
+ // so a fallback section is resolved here, invisibly, via the same
208
+ // first-registered fallback everything else in this file uses, WITHOUT
209
+ // touching `expanded` itself (overriding a controlled prop would be a
210
+ // worse violation than the one being fixed). That fallback section is
211
+ // reported as genuinely expanded — aria-expanded="true", scroll-owner
212
+ // styling — because it IS what is actually rendered and scrolling; ARIA
213
+ // must describe the DOM, not an unmatched prop value a screen reader user
214
+ // can't see anyway. A controlled `expanded` of exactly `null`, by contrast,
215
+ // is a DELIBERATE "everything collapsed" and is honoured as-is: nothing is
216
+ // hidden from the user in that state (every section is visibly, correctly,
217
+ // collapsed), so zero scroll owners is legitimate there, not a bug to
218
+ // heal. The uncontrolled path already resolves its own first-registered
219
+ // fallback inside `effectiveExpandedId` above, so it needs no separate
220
+ // handling here. split-primary has its own equivalent (`effectivePrimary`)
221
+ // and never reads `expanded` at all.
222
+ const effectiveScrollOwnerId = $derived.by((): string | null => {
223
+ if (shape === "split-primary") return null; // handled by effectivePrimary instead.
224
+ if (!controlled) return effectiveExpandedId;
225
+ if (expanded == null) return null; // deliberate "everything collapsed" — legitimate zero.
226
+ if (entries.some((e) => e.id === expanded)) return expanded;
227
+ return firstId; // invalid id — heal the rendered section only, never the prop.
228
+ });
229
+
230
+ // Dev-time visibility for the fallback above — same `[PanelStack] …`
231
+ // convention as PANEL_STACK_MAX_SECTIONS' warning in `register()`. Fired at
232
+ // most once per instance, not once per registration: sections register
233
+ // incrementally as each PanelSection mounts, and the condition below can
234
+ // keep holding across several of those ticks before `entries` settles.
235
+ let warnedInvalidControlledExpanded = false;
236
+ $effect(() => {
237
+ if (shape === "split-primary") return; // `expanded` has no effect on that shape.
238
+ if (!controlled || expanded == null) return;
239
+ if (entries.some((e) => e.id === expanded)) return;
240
+ if (warnedInvalidControlledExpanded) return;
241
+ warnedInvalidControlledExpanded = true;
242
+ console.warn(
243
+ `[PanelStack] expanded="${expanded}" does not match any registered section. The prop is left untouched, but the first registered section is resolved internally as the expanded, scroll-owning fallback so the stack never has zero scroll owners (and ARIA matches what actually renders).`
244
+ );
245
+ });
246
+
247
+ // Independent open/closed state for split-primary's NON-primary sections.
248
+ // Always uncontrolled — the API exposes no prop for it, only `primary` is
249
+ // stable for that shape. Several sections may be open at once; a section
250
+ // starts closed (header only) until the user opens it. This is the user's
251
+ // INTENT, separate from `autoCollapsed` below (what's actually visible).
252
+ let openSecondary = $state<Set<string>>(new Set());
253
+
254
+ // split-primary: the section matching `primary`, or — if `primary` is unset
255
+ // or matches no registered section (a misconfiguration) — the first
256
+ // EXPANDED section in DOM order (ratified answer: "always the expanded one"
257
+ // is unambiguous only until two are expanded, hence DOM order as the
258
+ // tiebreak), or — if nothing is expanded either — the first registered
259
+ // section, so the stack still never degrades to zero scroll owners.
260
+ const effectivePrimary = $derived.by((): string | null => {
261
+ if (shape !== "split-primary") return null;
262
+ if (primary !== undefined && entries.some((e) => e.id === primary)) return primary;
263
+ const firstExpandedId = orderedEntries.find((e) => openSecondary.has(e.id))?.id;
264
+ if (firstExpandedId !== undefined) return firstExpandedId;
265
+ return firstId;
266
+ });
267
+
268
+ // --- Auto-collapse (split-primary only): secondaries yield to the primary's
269
+ // floor -------------------------------------------------------------------
270
+ // Ratified contract: the pane NEVER scrolls, and the primary NEVER shrinks
271
+ // below a usable minimum (CSS `min-block-size` on the scroll-owner body,
272
+ // token below). Since secondaries render `flex: 0 0 auto` (they never
273
+ // shrink under pressure — only the primary, `flex: 1 1 0`, does) their
274
+ // rendered ROOT height is always an accurate read of "how much space this
275
+ // section currently occupies", whether collapsed (header only) or expanded
276
+ // (header + natural body) — no separate body/header split needed for THEM.
277
+ // The primary's own header needs its own measurement (it never collapses,
278
+ // so there's no "collapsed" snapshot to read a header-only height from the
279
+ // way a secondary's initial closed state gives one "for free").
280
+ let stackEl: HTMLElement | null = $state(null);
281
+ let stackHeight = $state(0);
282
+ let primaryHeaderHeight = $state(0);
283
+ /** Latest observed ROOT (header+current body) height per registered id. */
284
+ let rootHeights = $state<Map<string, number>>(new Map());
285
+ /** Secondaries force-collapsed by the algorithm despite `openSecondary`
286
+ * wanting them open — distinct from the user's own intent so an explicit
287
+ * re-open (toggle) can always clear it. */
288
+ let autoCollapsed = $state<Set<string>>(new Set());
289
+ /** MRU order (oldest first) of ids the user explicitly opened. Drives
290
+ * "collapse the LEAST recently expanded secondary first" — the algorithm
291
+ * never touches this list itself, only `toggle()` does, so a user re-open
292
+ * always makes that section the last one considered for collapse again. */
293
+ let expansionOrder = $state<string[]>([]);
294
+
295
+ let resizeObserver: ResizeObserver | null = null;
296
+ let observedPrimaryHeaderEl: HTMLElement | null = null;
297
+
298
+ function ensureResizeObserver(): ResizeObserver | null {
299
+ if (resizeObserver) return resizeObserver;
300
+ // Guard: jsdom (this package's test environment) and some SSR/older
301
+ // environments have no ResizeObserver at all. Auto-collapse simply never
302
+ // engages there — `stackHeight` stays 0, the decision effect below is a
303
+ // permanent no-op — rather than throwing.
304
+ if (typeof ResizeObserver === "undefined") return null;
305
+ resizeObserver = new ResizeObserver((observedEntries) => {
306
+ for (const entry of observedEntries) {
307
+ const height = entry.contentRect.height;
308
+ if (entry.target === stackEl) {
309
+ stackHeight = height;
310
+ } else if (entry.target === observedPrimaryHeaderEl) {
311
+ primaryHeaderHeight = height;
312
+ } else {
313
+ const found = entries.find((e) => e.el === entry.target);
314
+ if (found) {
315
+ const next = new Map(rootHeights);
316
+ next.set(found.id, height);
317
+ rootHeights = next;
318
+ }
319
+ }
320
+ }
321
+ });
322
+ return resizeObserver;
323
+ }
324
+
325
+ $effect(() => {
326
+ if (!stackEl) return;
327
+ const observer = ensureResizeObserver();
328
+ if (!observer) return;
329
+ observer.observe(stackEl);
330
+ return () => observer.disconnect();
331
+ });
332
+
333
+ // Retarget the header observer whenever the primary changes (designation,
334
+ // fallback resolution, or a section unmounting).
335
+ $effect(() => {
336
+ const primaryId = effectivePrimary;
337
+ const nextHeaderEl = primaryId ? (entries.find((e) => e.id === primaryId)?.headerEl ?? null) : null;
338
+ untrack(() => {
339
+ const observer = ensureResizeObserver();
340
+ if (!observer) {
341
+ observedPrimaryHeaderEl = nextHeaderEl;
342
+ return;
343
+ }
344
+ if (observedPrimaryHeaderEl && observedPrimaryHeaderEl !== nextHeaderEl) {
345
+ observer.unobserve(observedPrimaryHeaderEl);
346
+ }
347
+ if (nextHeaderEl && nextHeaderEl !== observedPrimaryHeaderEl) {
348
+ observer.observe(nextHeaderEl);
349
+ }
350
+ observedPrimaryHeaderEl = nextHeaderEl;
351
+ });
352
+ });
353
+
354
+ // THE decision. Re-evaluates only when a REAL measurement changes
355
+ // (stackHeight / primaryHeaderHeight / rootHeights / entries), the primary
356
+ // itself changes, or the consumer tunes `primaryMinHeight` at runtime —
357
+ // `openSecondary`/`autoCollapsed`/`expansionOrder` are read
358
+ // through `untrack` so that THIS effect's own write to `autoCollapsed` never
359
+ // re-triggers itself with stale (pre-layout) measurements. That is what
360
+ // guarantees convergence: each pass collapses at most one NEW secondary,
361
+ // using measurements that are always either accurate (untouched by this
362
+ // pass) or correctly reflect an EARLIER pass once the observer catches up —
363
+ // never a same-tick avalanche. `autoCollapsed` only ever grows here; it only
364
+ // shrinks via an explicit user `toggle()`, so no id can be added and removed
365
+ // in a loop by this effect alone, and the candidate pool is bounded by the
366
+ // section count (≤ PANEL_STACK_MAX_SECTIONS - 1 secondaries) — so it always
367
+ // reaches a fixed point in a bounded number of measurement-driven passes.
368
+ $effect(() => {
369
+ if (shape !== "split-primary") return;
370
+ const primaryId = effectivePrimary;
371
+ if (primaryId === null) return;
372
+ if (stackHeight === 0) return; // not measured yet — nothing to decide.
373
+
374
+ let secondaryTotal = 0;
375
+ for (const e of entries) {
376
+ if (e.id === primaryId) continue;
377
+ secondaryTotal += rootHeights.get(e.id) ?? 0;
378
+ }
379
+ const available = stackHeight - primaryHeaderHeight - secondaryTotal;
380
+ if (available >= primaryMinHeight) return;
381
+
382
+ // Both the candidate search AND the Set construction below must read
383
+ // `autoCollapsed` inside `untrack` — reading it ANYWHERE untracked in
384
+ // this effect (even just to build the next Set) would re-register it as
385
+ // a dependency of this very effect, since assignment doesn't erase a
386
+ // read that already happened. That subtle leak is exactly what causes
387
+ // the same-tick avalanche this design avoids: the effect would then
388
+ // immediately re-run off its own write, before any real (post-collapse)
389
+ // measurement exists.
390
+ const nextAutoCollapsed = untrack(() => {
391
+ const candidate = expansionOrder.find(
392
+ (id) => id !== primaryId && openSecondary.has(id) && !autoCollapsed.has(id)
393
+ );
394
+ if (candidate === undefined) return null; // nothing left to collapse — degenerate case, do no more.
395
+ return new Set(autoCollapsed).add(candidate);
396
+ });
397
+ if (nextAutoCollapsed) autoCollapsed = nextAutoCollapsed;
398
+ });
399
+
400
+ function setExpanded(id: string | null) {
401
+ if (!controlled) internalExpanded = id;
402
+ onExpandedChange?.(id);
403
+ }
404
+
405
+ function isPrimary(id: string): boolean {
406
+ return shape === "split-primary" && id === effectivePrimary;
407
+ }
408
+
409
+ function isExpanded(id: string): boolean {
410
+ if (shape === "split-primary") {
411
+ if (id === effectivePrimary) return true;
412
+ return openSecondary.has(id) && !autoCollapsed.has(id);
413
+ }
414
+ // sticky-item: expanded and scroll owner are the same thing by
415
+ // definition — exactly one section is expanded and it owns the scroll —
416
+ // so this reads `effectiveScrollOwnerId`, NOT `effectiveExpandedId`.
417
+ // They agree in every normal case (uncontrolled, controlled-valid,
418
+ // controlled-null); they diverge only when a controlled `expanded`
419
+ // matches no registered section, and THAT is exactly the case where
420
+ // aria-expanded must track what is actually rendered (the fallback
421
+ // section, visibly scrolling), not the unmatched prop value — otherwise
422
+ // a screen reader announces "collapsed" for an on-screen, scrolling
423
+ // region. The controlled prop itself is still never written here; this
424
+ // only changes what `isExpanded` reports.
425
+ return id === effectiveScrollOwnerId;
426
+ }
427
+
428
+ function isScrollOwner(id: string): boolean {
429
+ return shape === "split-primary" ? id === effectivePrimary : id === effectiveScrollOwnerId;
430
+ }
431
+
432
+ function toggle(id: string) {
433
+ if (shape === "split-primary") {
434
+ if (id === effectivePrimary) return; // primary has no disclosure button; guard anyway.
435
+ // Toggle acts on what's currently RENDERED (isExpanded), not the raw
436
+ // `openSecondary` flag, so a click on an auto-collapsed (visually
437
+ // closed) section always reads as "open it" to the user, never as a
438
+ // second, confusing "close" of a section they already see as closed.
439
+ if (isExpanded(id)) {
440
+ const next = new Set(openSecondary);
441
+ next.delete(id);
442
+ openSecondary = next;
443
+ expansionOrder = expansionOrder.filter((x) => x !== id);
444
+ } else {
445
+ const next = new Set(openSecondary);
446
+ next.add(id);
447
+ openSecondary = next;
448
+ if (autoCollapsed.has(id)) {
449
+ const nextAuto = new Set(autoCollapsed);
450
+ nextAuto.delete(id);
451
+ autoCollapsed = nextAuto;
452
+ }
453
+ // Move to the most-recently-expanded end — an explicit re-open always
454
+ // makes this section the LAST one the algorithm would collapse again.
455
+ expansionOrder = [...expansionOrder.filter((x) => x !== id), id];
456
+ }
457
+ return;
458
+ }
459
+ // sticky-item: radio semantics — clicking the already-expanded header
460
+ // (including the first-section fallback) is a no-op, there is no
461
+ // "collapse to zero" gesture.
462
+ if (effectiveExpandedId === id) return;
463
+ setExpanded(id);
464
+ }
465
+
466
+ setContext<PanelStackContext>(PANEL_STACK_KEY, {
467
+ isPrimary,
468
+ isExpanded,
469
+ isScrollOwner,
470
+ toggle,
471
+ register
472
+ });
473
+
474
+ const classes = $derived(["st-panelStack", className].filter(Boolean).join(" "));
475
+ </script>
476
+
477
+ <div
478
+ class={classes}
479
+ role="group"
480
+ aria-label={label}
481
+ bind:this={stackEl}
482
+ style="--st-component-panelStack-primaryMinBlockSize: {primaryMinHeight}px"
483
+ >
484
+ {@render children?.()}
485
+ </div>
486
+
487
+ <style>
488
+ /* The stack is a plain flex column that clips its own edges — it NEVER
489
+ scrolls itself. Exactly one descendant (a PanelSection body) is ever the
490
+ scroll owner; see PanelSection.svelte for the single scrolling
491
+ declaration in this component pair. */
492
+ .st-panelStack {
493
+ block-size: 100%;
494
+ display: flex;
495
+ flex-direction: column;
496
+ min-block-size: 0;
497
+ overflow: hidden;
498
+ }
499
+
500
+ /* Separator between adjacent PanelSection instances. Declared here (the
501
+ parent, whose own root class IS statically present in this template)
502
+ rather than in PanelSection.svelte, where a sibling-combinator against the
503
+ child's own root class would only ever match ACROSS separate component
504
+ instances — something svelte-check cannot verify and flags as an unused
505
+ selector. Mirrors ButtonGroup's `> :global(* + *)` idiom. */
506
+ .st-panelStack > :global(.st-panelSection) + :global(.st-panelSection) {
507
+ border-top: 1px solid var(--st-component-control-border, var(--st-semantic-border-subtle));
508
+ }
509
+ </style>
@@ -0,0 +1,89 @@
1
+ import type { Snippet } from "svelte";
2
+ export type PanelStackShape = "split-primary" | "sticky-item";
3
+ /**
4
+ * Bound ratified by the chat consumer lane: beyond 4 sections, stacking
5
+ * collapsible regions in a pane capped at 640px makes scrolling unmanageable
6
+ * and the single-owner rule becomes untenable. Enforced as a dev-time
7
+ * `console.warn` in `register()` (this package's established convention —
8
+ * see NavActionStack/WaterfallChart — is to warn and degrade, never throw
9
+ * or silently truncate); exported here so the bound is also visible through
10
+ * types/docs to a consumer reading `PanelStackProps`.
11
+ */
12
+ export declare const PANEL_STACK_MAX_SECTIONS = 4;
13
+ /**
14
+ * Default of `PanelStackProps.primaryMinHeight` (the primary section's
15
+ * usable floor, in px) — exported so a consumer can reference the default
16
+ * without hardcoding it. This is also the ONLY place the number is
17
+ * hardcoded: PanelStack mirrors the live `primaryMinHeight` prop (which
18
+ * defaults to this constant) onto the
19
+ * `--st-component-panelStack-primaryMinBlockSize` custom property on its
20
+ * own root, and the stylesheet's `min-block-size` reads that same
21
+ * property — so the JS auto-collapse threshold and the CSS floor read the
22
+ * same number and can no longer drift apart the way two independently
23
+ * hardcoded copies could.
24
+ */
25
+ export declare const PRIMARY_MIN_BLOCK_SIZE_PX = 160;
26
+ export type PanelStackProps = {
27
+ /** "sticky-item" (default): one section expanded at a time, all headers stay visible.
28
+ "split-primary": the `primary` section is always expanded and owns the scroll;
29
+ the others are content-sized disclosures. */
30
+ shape?: PanelStackShape;
31
+ /** Accessible name for the stack region. */
32
+ label?: string;
33
+ /** sticky-item, controlled: id of the expanded section. */
34
+ expanded?: string | null;
35
+ /** sticky-item, uncontrolled seed. */
36
+ defaultExpanded?: string | null;
37
+ onExpandedChange?: (id: string | null) => void;
38
+ /**
39
+ * split-primary: id of the section that owns the scroll. Falls back to the
40
+ * first EXPANDED section (DOM order) when unset or stale, and — if nothing
41
+ * is expanded — to the first registered section, so the stack never
42
+ * degrades to zero scroll owners.
43
+ */
44
+ primary?: string;
45
+ /** Usable floor for the primary section, in px. While the primary sits above it the
46
+ primary absorbs overflow; once it would drop below, a secondary auto-collapses
47
+ instead of compressing the primary further. Default 160. */
48
+ primaryMinHeight?: number;
49
+ /**
50
+ * At most {@link PANEL_STACK_MAX_SECTIONS} `PanelSection` children are
51
+ * supported — see that constant's doc comment for why.
52
+ */
53
+ children?: Snippet;
54
+ class?: string;
55
+ };
56
+ /**
57
+ * Context contract shared with PanelSection. Every shape-dependent branch
58
+ * (sticky-item vs split-primary) is decided HERE and only here — PanelSection
59
+ * never reads `shape`, it only calls these four functions/callback. If the
60
+ * consumer-lane contract for these two shapes changes, this is the one place
61
+ * to touch.
62
+ */
63
+ export declare const PANEL_STACK_KEY: unique symbol;
64
+ export type PanelStackContext = {
65
+ /** Is this section the (non-collapsible) primary of a split-primary stack? */
66
+ isPrimary: (id: string) => boolean;
67
+ /** Is this section currently expanded (body visible, content-sized or scrolling)? */
68
+ isExpanded: (id: string) => boolean;
69
+ /** Is this section's body THE single scroll owner right now (flex:1 1 0, overflow:auto)? */
70
+ isScrollOwner: (id: string) => boolean;
71
+ /** Header was activated (click / Space / Enter on the disclosure button). */
72
+ toggle: (id: string) => void;
73
+ /**
74
+ * Register a section's root AND header element, in mount/DOM order;
75
+ * returns an unregister callback. NOT just bookkeeping — the stack falls
76
+ * back to the first registered section as the scroll owner whenever
77
+ * nothing else designates one (unset/stale `expanded` or `primary`), so
78
+ * the invariant "exactly one scroll owner whenever the stack has ≥1
79
+ * section" holds even for a misconfigured or dynamically-changing stack.
80
+ * `headerEl` is used only by split-primary's auto-collapse measurement
81
+ * (the header of whichever section is CURRENTLY primary is observed for
82
+ * its height); sticky-item ignores it.
83
+ */
84
+ register: (id: string, rootEl: HTMLElement, headerEl: HTMLElement) => () => void;
85
+ };
86
+ declare const PanelStack: import("svelte").Component<PanelStackProps, {}, "">;
87
+ type PanelStack = ReturnType<typeof PanelStack>;
88
+ export default PanelStack;
89
+ //# sourceMappingURL=PanelStack.svelte.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"PanelStack.svelte.d.ts","sourceRoot":"","sources":["../src/lib/PanelStack.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,aAAa,CAAC;AAE9D;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,MAAM,MAAM,eAAe,GAAG;IAC5B;;oDAEgD;IAChD,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;mEAE+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,eAA2B,CAAC;AAExD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8EAA8E;IAC9E,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,qFAAqF;IACrF,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC,4FAA4F;IAC5F,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,6EAA6E;IAC7E,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,KAAK,MAAM,IAAI,CAAC;CAClF,CAAC;AA6YJ,QAAA,MAAM,UAAU,qDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}
@@ -0,0 +1,23 @@
1
+ import { type PanelStackShape } from "./PanelStack.svelte";
2
+ type Section = {
3
+ id: string;
4
+ label: string;
5
+ content?: string;
6
+ action?: string;
7
+ class?: string;
8
+ };
9
+ type $$ComponentProps = {
10
+ shape?: PanelStackShape;
11
+ label?: string;
12
+ expanded?: string | null;
13
+ defaultExpanded?: string | null;
14
+ onExpandedChange?: (id: string | null) => void;
15
+ primary?: string;
16
+ primaryMinHeight?: number;
17
+ sections: Section[];
18
+ class?: string;
19
+ };
20
+ declare const PanelStackFixture: import("svelte").Component<$$ComponentProps, {}, "">;
21
+ type PanelStackFixture = ReturnType<typeof PanelStackFixture>;
22
+ export default PanelStackFixture;
23
+ //# sourceMappingURL=PanelStackFixture.svelte.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"PanelStackFixture.svelte.d.ts","sourceRoot":"","sources":["../src/lib/PanelStackFixture.svelte.ts"],"names":[],"mappings":"AAMA,OAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAIrE,KAAK,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACjG,KAAK,gBAAgB,GAAI;IACtB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAqCJ,QAAA,MAAM,iBAAiB,sDAAwC,CAAC;AAChE,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9D,eAAe,iBAAiB,CAAC"}
package/dist/index.d.ts CHANGED
@@ -195,6 +195,10 @@ export { default as ContextPanel } from "./ContextPanel.svelte";
195
195
  export type { ContextPanelProps } from "./ContextPanel.svelte";
196
196
  export { default as UtilityPanel } from "./UtilityPanel.svelte";
197
197
  export type { UtilityPanelMode, UtilityPanelProps, UtilityPanelSide } from "./UtilityPanel.svelte";
198
+ export { default as PanelStack, PANEL_STACK_MAX_SECTIONS } from "./PanelStack.svelte";
199
+ export type { PanelStackShape, PanelStackProps } from "./PanelStack.svelte";
200
+ export { default as PanelSection } from "./PanelSection.svelte";
201
+ export type { PanelSectionProps } from "./PanelSection.svelte";
198
202
  export { default as SkeletonText } from "./SkeletonText.svelte";
199
203
  export { default as SkipLink } from "./SkipLink.svelte";
200
204
  export { default as SlideIndicator } from "./SlideIndicator.svelte";