@celestia-island/hikari 0.55.339 → 0.55.340

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.
@@ -10,37 +10,47 @@ import "./HkRangeRibbon.scss";
10
10
  * projected from ONE host-supplied sequence.
11
11
  *
12
12
  * The ribbon owns no content vocabulary. `lanes` is the consumer's row
13
- * structure and `segments` are its parts, each fed in ABSOLUTE fractions of
14
- * the whole progress (0..1). Both layers derive their x from that same
15
- * number, which is what keeps them mutually legible:
13
+ * structure, `segments` are its parts and `domain` is the axis they are
14
+ * measured on (default `[0, 1]`, the familiar 0%..100%; a caller may declare
15
+ * `[-0.1, 1]`, `[0, 2]`, `[-0.5, 1.5]` or a narrower `[0.2, 0.8]`). Segment
16
+ * starts/ends, the window and `windowChange` all live in those axis units.
16
17
  *
17
18
  * · data-layer="minimap" — the top, compact strip. It paints every lane's
18
- * segments across the FULL domain and never clips, so the window stays
19
- * locatable; the window frame, the two outside scrims, both edge handles
20
- * and the reset button ride on it, and it owns the brush surface.
19
+ * segments clipped to the DOMAIN and never follows the window, so the
20
+ * window stays locatable; the window frame, the two outside scrims, both
21
+ * edge handles and the reset button ride on it, and it owns the brush
22
+ * surface. Its x is `(f - domain[0]) / span`.
21
23
  * · data-layer="detail" — the lower, taller lane list focused on the
22
- * selected window: a window of [0.35, 0.67] starts the detail at 35% and
23
- * ends it at 67% of the whole progress, because only segments that
24
- * intersect the window survive, clipped at its edges and re-normalized to
25
- * the track. With no window the detail is the full domain.
24
+ * selected window: the track is always 0..100% of the WINDOW, in the
25
+ * caller's domain units, so a window of [0.35, 0.67] starts the detail at
26
+ * 0 and ends it at 100% however the domain is placed (with the default
27
+ * axis those are the familiar 35%..67%). Only segments intersecting the
28
+ * window survive, clipped at its edges. With no window the detail is the
29
+ * full view, i.e. the caller's domain.
26
30
  *
27
31
  * The minimap shares the lanes' label column (an empty gutter), so both
28
32
  * layers always start at the same inline x. Their x% agree only in the
29
33
  * FULL-DOMAIN view: a window re-normalizes the detail against the selected
30
- * sub-domain, and a headroom compresses the minimap by `1 + headroom`.
34
+ * sub-domain, and a non-unit domain rescales the minimap.
31
35
  *
32
- * HEADROOM: a host whose sequence is read against more than 100% (a 110%
33
- * budget, a "10% still unknown" tail) reserves that space with `headroom`, a
34
- * fraction clamped to 0..1. The minimap axis is then `1 + headroom` wide and
35
- * every minimap x is `fraction / span`: content 100% sits at 100/110 ≈ 90.9%
36
- * and the tail stays blank. The detail layer NEVER sees the headroom — its
37
- * axis is always the content window mapped to 0..100%, so a zoomed detail is
38
- * never polluted by reserved space. Windows and every emitted value stay
39
- * CONTENT fractions in 0..1; a pointer in the blank tail clamps to content
40
- * 100%, because the tail is padding, not selectable progress. `minimal` mode
41
- * suppresses the minimap lane rows and the whole detail layer (its bare bar
42
- * still lives in the overview container), so it ignores the headroom
43
- * entirely and stays on the content axis.
36
+ * DOMAIN: the axis is the caller's `domain`; content outside it is clipped
37
+ * away, and space inside it the content does not fill stays blank (a 200%
38
+ * budget, a 10% lead-in, a zoomed window of interest). `headroom` is the
39
+ * DEPRECATED shorthand for the trailing-axis case — the axis is
40
+ * `[0, 1 + headroom]`, so the "110%" reading is headroom 0.1 — and a valid
41
+ * `domain` wins over it. The alias is SOURCE-compatible with the old
42
+ * `headroom` prop but NOT behaviour-compatible: there is no special
43
+ * tail-clamp, because the whole component reads `[0, 1 + headroom]` as the
44
+ * coordinate system — the reserved tail is selectable axis, the axis end
45
+ * (not content 100%) is the reset state, the keyboard steps 5% of the span,
46
+ * the no-window detail and the minimal bar draw it, and ARIA reads it.
47
+ * Windows and every emitted value stay absolute coordinates in the caller's
48
+ * domain units: pointer x maps back onto the domain (`d0 + x * span`) and
49
+ * clamps to it, the keyboard nudges by 5% of the span, and labels/ARIA read
50
+ * domain percentages (negative or above 100% when the domain says so).
51
+ * `minimal` mode suppresses the minimap lane rows and the whole detail layer
52
+ * (its bare bar still lives in the overview container) and draws the same
53
+ * domain axis.
44
54
  *
45
55
  * Editing: drag on the strip to brush a new window, drag either edge handle
46
56
  * to resize it, and reset back to the full domain — the reset button, a
@@ -50,10 +60,11 @@ import "./HkRangeRibbon.scss";
50
60
  * nudge their own edge. Hovering or focusing a segment floats its tip card
51
61
  * (tip.title + tip.lines); the card anchors inside the ribbon at the edges.
52
62
  *
53
- * Contract with the host: `segments` are fed in FULL-DOMAIN fractions
54
- * (0..1) and `windowChange` always answers in those same absolute
55
- * fractions — never fractions of the currently zoomed sub-domain — so a
56
- * consumer can filter its own row list with the emitted range unchanged.
63
+ * Contract with the host: `segments` are fed in ABSOLUTE coordinates on the
64
+ * caller's domain axis (default 0..1) and `windowChange` always answers in
65
+ * those same coordinates — never fractions of the currently zoomed
66
+ * sub-domain — so a consumer can filter its own row list with the emitted
67
+ * range unchanged.
57
68
  * `window === null` is a controlled full view; omitting the prop entirely
58
69
  * (undefined) makes the ribbon keep its own window state.
59
70
  */
@@ -73,13 +84,13 @@ export interface RibbonLane {
73
84
  label: string;
74
85
  }
75
86
 
76
- /** One bar on a lane, in fractions of the FULL domain (`start < end`). */
87
+ /** One bar on a lane, in the caller's DOMAIN units (`start < end`). */
77
88
  export interface RibbonSegment {
78
89
  id: string;
79
90
  lane: string;
80
- /** Fraction of the full sequence, 0..1. */
91
+ /** Start coordinate on the caller's domain axis. */
81
92
  start: number;
82
- /** Fraction of the full sequence, 0..1. */
93
+ /** End coordinate on the caller's domain axis. */
83
94
  end: number;
84
95
  label: string;
85
96
  tone?: RibbonTone;
@@ -94,13 +105,45 @@ type WindowRange = [number, number];
94
105
  /** Assumed minimum window width when the host hands over something that is
95
106
  * not a positive finite number (0 / negative / NaN). */
96
107
  const MIN_WINDOW_FALLBACK = 0.02;
97
- /** Keyboard nudge (fraction of the full domain) for move and resize. */
108
+ /** Keyboard nudge as a fraction of the AXIS SPAN for move and resize. */
98
109
  const KEYBOARD_STEP = 0.05;
99
110
  /** Slack for "did this interaction change anything" comparisons. */
100
111
  const WINDOW_EPSILON = 1e-9;
101
112
 
102
- function clamp01(value: number): number {
103
- return value < 0 ? 0 : value > 1 ? 1 : value;
113
+ /** An ordered pair of caller coordinates: the axis everything is drawn on. */
114
+ type DomainRange = [number, number];
115
+
116
+ /** The fallback axis: the familiar 0%..100% reading. */
117
+ const UNIT_DOMAIN: DomainRange = [0, 1];
118
+
119
+ function clampTo(value: number, lo: number, hi: number): number {
120
+ return value < lo ? lo : value > hi ? hi : value;
121
+ }
122
+
123
+ function domainSpan(domain: DomainRange): number {
124
+ return domain[1] - domain[0];
125
+ }
126
+
127
+ /** Sanitize a caller axis into an ordered, positive-width pair — `null` when
128
+ * the value cannot be one (not an array, fewer than two entries, a
129
+ * non-finite member, zero width).
130
+ * An inverted pair is sorted. Stays `null`-able instead of defaulting here
131
+ * because the component has a second fallback (the `headroom` alias). */
132
+ function sanitizeDomain(input: unknown): DomainRange | null {
133
+ if (!Array.isArray(input) || input.length < 2) return null;
134
+ const first = Number(input[0]);
135
+ const second = Number(input[1]);
136
+ if (!Number.isFinite(first) || !Number.isFinite(second)) return null;
137
+ const lo = Math.min(first, second);
138
+ const hi = Math.max(first, second);
139
+ return hi > lo ? [lo, hi] : null;
140
+ }
141
+
142
+ /** The axis a caller meant, never `null`: malformed input is the unit axis.
143
+ * Shared by the component and `normalizeHkRangeWindow` so hosts and the
144
+ * ribbon fall back the same way. */
145
+ function resolveDomain(input: unknown): DomainRange {
146
+ return sanitizeDomain(input) ?? UNIT_DOMAIN;
104
147
  }
105
148
 
106
149
  /** Percent with adaptive precision. An integer percentage stays an integer —
@@ -139,38 +182,47 @@ function percent(fraction: number): string {
139
182
  * @param input Any host window value. `null` / `undefined`, a non-array, an
140
183
  * array with fewer than two entries, or either member non-finite all mean
141
184
  * "no window" and return `null` (the host reads that as the full domain).
142
- * @param minWidth Narrowest window the ribbon will produce, defaulting to
143
- * 0.02. Clamped to [0, 1]; a non-finite or non-positive value falls back
144
- * to the default.
145
- * @returns An ordered, domain-clamped `[start, end]` pair of full-domain
146
- * fractions, never narrower than `minWidth`, or `null` for "no window".
185
+ * @param minWidth Narrowest window the ribbon will produce, in domain units,
186
+ * defaulting to 0.02. Capped at the axis span; a non-finite or non-positive
187
+ * value falls back to the default.
188
+ * @param domain The axis the window lives on, defaulting to `[0, 1]`. An
189
+ * inverted pair is sorted; anything malformed (not an array, fewer than two
190
+ * entries, non-finite members, zero width) falls back to `[0, 1]`, which
191
+ * keeps the two-argument host calls byte-identical to the pre-domain
192
+ * contract.
193
+ * @returns An ordered, domain-clamped `[start, end]` pair in the caller's
194
+ * axis units, never narrower than `minWidth` (or than the span), or `null`
195
+ * for "no window".
147
196
  */
148
197
  export function normalizeHkRangeWindow(
149
198
  input: unknown,
150
199
  minWidth: number = MIN_WINDOW_FALLBACK,
200
+ domain: readonly number[] | null = UNIT_DOMAIN,
151
201
  ): [number, number] | null {
152
202
  if (input == null || !Array.isArray(input) || input.length < 2) return null;
153
203
  const first = Number(input[0]);
154
204
  const second = Number(input[1]);
155
205
  if (!Number.isFinite(first) || !Number.isFinite(second)) return null;
206
+ const [d0, d1] = resolveDomain(domain);
207
+ const span = d1 - d0;
156
208
  const min =
157
209
  Number.isFinite(minWidth) && minWidth > 0
158
- ? Math.min(minWidth, 1)
159
- : MIN_WINDOW_FALLBACK;
160
- let lo = clamp01(Math.min(first, second));
161
- let hi = clamp01(Math.max(first, second));
210
+ ? Math.min(minWidth, span)
211
+ : Math.min(MIN_WINDOW_FALLBACK, span);
212
+ let lo = clampTo(Math.min(first, second), d0, d1);
213
+ let hi = clampTo(Math.max(first, second), d0, d1);
162
214
  if (hi - lo < min) {
163
- // Expand around the point, then shift inward at a domain edge.
215
+ // Expand around the point, then shift inward at the domain edges.
164
216
  const middle = (lo + hi) / 2;
165
217
  lo = middle - min / 2;
166
218
  hi = middle + min / 2;
167
- if (lo < 0) {
168
- lo = 0;
169
- hi = Math.min(1, min);
219
+ if (lo < d0) {
220
+ lo = d0;
221
+ hi = Math.min(d1, d0 + min);
170
222
  }
171
- if (hi > 1) {
172
- hi = 1;
173
- lo = Math.max(0, 1 - min);
223
+ if (hi > d1) {
224
+ hi = d1;
225
+ lo = Math.max(d0, d1 - min);
174
226
  }
175
227
  }
176
228
  return [lo, hi];
@@ -196,11 +248,13 @@ function intersectsWindow(placed: PlacedSegment, win: WindowRange): boolean {
196
248
  return placed.end > win[0] && placed.start < win[1];
197
249
  }
198
250
 
199
- /** Clamp every segment into the domain; drop NaN/unusable entries (a broken
200
- * row must not take the whole ribbon down). A zero-length segment is kept:
201
- * the LANE sheet gives it a 2px min-width floor under `box-sizing:
202
- * border-box`, so a lane tick is exactly that 2px (the 1px borders sit
203
- * inside it); the overview twin draws 1px. */
251
+ /** Keep every usable segment, in the caller's DOMAIN units; drop NaN /
252
+ * unusable entries (a broken row must not take the whole ribbon down).
253
+ * Segments are deliberately NOT clamped here: content may extend past the
254
+ * axis the caller chose to show, and the projections clip to the domain at
255
+ * render time. A zero-length segment is kept: the LANE sheet gives it a 2px
256
+ * min-width floor under `box-sizing: border-box`, so a lane tick is exactly
257
+ * that 2px (the 1px borders sit inside it); the overview twin draws 1px. */
204
258
  function placeSegments(segments: RibbonSegment[] | undefined): PlacedSegment[] {
205
259
  if (!Array.isArray(segments)) return [];
206
260
  const placed: PlacedSegment[] = [];
@@ -211,8 +265,8 @@ function placeSegments(segments: RibbonSegment[] | undefined): PlacedSegment[] {
211
265
  if (!Number.isFinite(first) || !Number.isFinite(second)) continue;
212
266
  placed.push({
213
267
  segment,
214
- start: clamp01(Math.min(first, second)),
215
- end: clamp01(Math.max(first, second)),
268
+ start: Math.min(first, second),
269
+ end: Math.max(first, second),
216
270
  });
217
271
  }
218
272
  return placed;
@@ -225,17 +279,37 @@ type SegmentBox = {
225
279
  width: number;
226
280
  };
227
281
 
228
- function fullDomainBox(placed: PlacedSegment): SegmentBox {
282
+ /** Clip a placed segment to the DOMAIN, in content units. This is the one
283
+ * domain-clipping rule: the minimap and the no-window detail both paint the
284
+ * domain, so anything wholly outside it is not drawn. A zero-length point is
285
+ * kept only when it lies on the domain (the strict `start < end` test above
286
+ * cannot express a point). */
287
+ function clipToDomain(placed: PlacedSegment, domain: DomainRange): WindowRange | null {
288
+ const [d0, d1] = domain;
289
+ if (placed.start === placed.end) {
290
+ return placed.start >= d0 && placed.start <= d1 ? [placed.start, placed.start] : null;
291
+ }
292
+ if (placed.end <= d0 || placed.start >= d1) return null;
293
+ return [Math.max(placed.start, d0), Math.min(placed.end, d1)];
294
+ }
295
+
296
+ /** The box a segment paints on the FULL-DOMAIN axis (0..1 = domain start..
297
+ * domain end). The minimap draws it directly and the no-window detail draws
298
+ * it too — with no window the detail's axis IS the domain — so the two
299
+ * layers agree by construction in the full-domain view. */
300
+ function domainBox(placed: PlacedSegment, domain: DomainRange): SegmentBox | null {
301
+ const clipped = clipToDomain(placed, domain);
302
+ if (!clipped) return null;
229
303
  return {
230
- left: placed.start,
231
- width: placed.end - placed.start,
304
+ left: projectToAxis(clipped[0], domain),
305
+ width: projectToAxisLength(clipped[1] - clipped[0], domain),
232
306
  };
233
307
  }
234
308
 
235
- /** The ONLY place clipping happens: with a window, a segment is clipped to
236
- * the window and re-normalized against it. Segments (and zero-length
237
- * points) wholly outside the window return null and render nowhere in the
238
- * lanes. */
309
+ /** One of the TWO clipping sites (the other is `clipToDomain`, the domain
310
+ * axis): with a window, a segment is clipped to the window and
311
+ * re-normalized against it. Segments (and zero-length points) wholly
312
+ * outside the window return null and render nowhere in the lanes. */
239
313
  function windowedBox(placed: PlacedSegment, win: WindowRange): SegmentBox | null {
240
314
  if (!intersectsWindow(placed, win)) return null;
241
315
  const [lo, hi] = win;
@@ -248,28 +322,35 @@ function windowedBox(placed: PlacedSegment, win: WindowRange): SegmentBox | null
248
322
  };
249
323
  }
250
324
 
251
- /** The minimap projection for one CONTENT scalar — a coordinate or a length:
252
- * its AXIS value is `value / span` (span = 1 + headroom). This pair
253
- * (`projectToAxis` + `axisBox`) is the ONLY place the minimap axis is
254
- * computed, and every axis value is one of them: the overview segments, the
255
- * window frame and the before scrim go through `axisBox`; both handles and
256
- * the after scrim's left edge go through `projectToAxis`. The after scrim's
257
- * width is `1 - its left`, which is what makes it reach the axis end.
258
- * `fractionFrom` is the inverse (axis → content) for pointer input. The
259
- * detail layer is never projected — its axis is the window itself, so none
260
- * of this may leak into `windowedBox` / `fullDomainBox`. */
261
- function projectToAxis(value: number, span: number): number {
262
- return value / span;
325
+ /** Project one CONTENT COORDINATE onto the minimap axis:
326
+ * `(value - domain[0]) / span`. This pair (`projectToAxis` for
327
+ * coordinates, `projectToAxisLength` for lengths) is the ONLY place a
328
+ * content value becomes an axis x: the window frame, both scrims, both
329
+ * handles and `domainBox` (the clipped-domain segments, which delegates
330
+ * here) all go through them, and `fractionFrom` is the inverse (axis →
331
+ * content) for pointer input. The WINDOWED detail is never projected — its
332
+ * axis is the window itself — so none of this may leak into `windowedBox`;
333
+ * the no-window detail reuses `domainBox`, i.e. the domain axis.
334
+ * A coordinate and a length are different projections: a length has no
335
+ * origin and only divides by the span, which is why a box must not scale
336
+ * its width through the coordinate function. */
337
+ function projectToAxis(value: number, domain: DomainRange): number {
338
+ return (value - domain[0]) / domainSpan(domain);
339
+ }
340
+
341
+ /** Project a CONTENT LENGTH (a box width) onto the minimap axis: no origin to
342
+ * subtract, so it only scales by `1/span`. */
343
+ function projectToAxisLength(length: number, domain: DomainRange): number {
344
+ return length / domainSpan(domain);
263
345
  }
264
346
 
265
- /** Project a CONTENT box onto the minimap's `1 + headroom` axis: the content
266
- * is compressed into the left 1/span of the strip and the reserved tail
267
- * stays empty. Delegates to `projectToAxis` so the axis arithmetic has one
268
- * home. The detail layer is never projected. */
269
- function axisBox(box: SegmentBox, span: number): SegmentBox {
347
+ /** Project a CONTENT box onto the minimap axis. The left edge is a
348
+ * coordinate, the width a length — scaling the width through
349
+ * `projectToAxis` would wrongly subtract the domain start from it. */
350
+ function axisBox(box: SegmentBox, domain: DomainRange): SegmentBox {
270
351
  return {
271
- left: projectToAxis(box.left, span),
272
- width: projectToAxis(box.width, span),
352
+ left: projectToAxis(box.left, domain),
353
+ width: projectToAxisLength(box.width, domain),
273
354
  };
274
355
  }
275
356
 
@@ -298,7 +379,7 @@ export default defineComponent({
298
379
  segments: { type: Array as PropType<RibbonSegment[]>, required: true },
299
380
  /** Id of the segment to paint as selected (host-owned). */
300
381
  selectedId: { type: String as PropType<string | null>, default: null },
301
- /** Controlled window in FULL-DOMAIN fractions; null = full domain.
382
+ /** Controlled window in the caller's DOMAIN units; null = full domain.
302
383
  * Omitting the prop (undefined) turns the uncontrolled fallback on. */
303
384
  window: {
304
385
  type: Array as PropType<number[] | null>,
@@ -307,28 +388,44 @@ export default defineComponent({
307
388
  /** Kill switch for the window feature: false = a static full-domain
308
389
  * view (a supplied window is ignored, all window UI disappears). */
309
390
  windowEnabled: { type: Boolean, default: true },
310
- /** Narrowest window the ribbon will produce, in domain fractions. */
391
+ /** Narrowest window the ribbon will produce, in DOMAIN units. Capped at
392
+ * the axis span, because a floor wider than the axis could never fit
393
+ * inside it. */
311
394
  minWindow: { type: Number, default: MIN_WINDOW_FALLBACK },
312
- /** Trailing blank axis the MINIMAP reserves after content 100%, in
313
- * content fractions (0..1). The axis span is `1 + headroom`, so 0.1
314
- * reads the sequence against a 110% budget: content 100% lands at
315
- * ~90.9% of the strip and the last ~9.1% stays blank. Sanitized —
316
- * non-finite / negative means no headroom, above 1 caps at 1. This is a
317
- * MINIMAP-only axis: the detail layer ignores it (its axis is always
318
- * the window), `minimal` mode suppresses the minimap lane rows so there
319
- * is nothing to reserve (its bare bar stays on the content axis), and
320
- * windows plus every emitted value stay content fractions. */
395
+ /** The axis the whole ribbon is drawn against: `[start, end]` in the SAME
396
+ * units as `segments` and `window`. Defaults to the unit axis `[0, 1]`
397
+ * (the familiar 0%..100%). A caller may declare a negative start or an
398
+ * end above 1 — `[-0.1, 1]` for a lead-in, `[0, 2]` for a 200% budget,
399
+ * `[-0.5, 1.5]` for a centred one — or a narrower window of interest
400
+ * such as `[0.2, 0.8]`. Sanitized: two finite numbers with a positive
401
+ * span; an inverted pair is sorted and anything else (not an array,
402
+ * non-finite members, zero width — or fewer than two entries) falls back
403
+ * to the unit axis `[0, 1]`, or to the deprecated `headroom` alias when
404
+ * one is set. Content
405
+ * outside the domain is clipped away and space inside it the content
406
+ * does not fill stays blank; every emitted window is a coordinate on
407
+ * this axis. */
408
+ domain: { type: Array as PropType<number[] | null>, default: undefined },
409
+ /** @deprecated Use `domain`. Trailing-axis shorthand: a positive value
410
+ * means the axis is `[0, 1 + headroom]` (the "110%" reading is headroom
411
+ * 0.1), sanitized to 0..1 and ignored when a valid `domain` is
412
+ * supplied. SOURCE-compatible with the old prop, NOT
413
+ * behaviour-compatible: there is no special tail-clamp — the component
414
+ * treats `[0, 1 + headroom]` as its coordinate system, so the old
415
+ * reserved tail becomes selectable axis, the axis end becomes the reset
416
+ * state, the keyboard step is 5% of the span and the no-window detail /
417
+ * minimal bar draw the axis. Kept for the 0.55 patch line. */
321
418
  headroom: { type: Number, default: 0 },
322
419
  /** Wave (2026-11-06 raw-records five): MINIMAL MODE — a bare dual-handle
323
420
  * range bar: no lane rows and no detail layer (the strip still lives in
324
- * the overview container, which keeps data-layer="minimap"), no label
325
- * gutter. The strip spans the full width and its track uses muted-based
326
- * tokens (the surface-based track read whitish inside dark phone
327
- * modals).
421
+ * the overview container, which keeps data-layer="minimap"). The shared
422
+ * label gutter is still rendered and hidden in this mode, so the strip
423
+ * spans the full width; its track uses muted-based tokens (the
424
+ * surface-based track read whitish inside dark phone modals).
328
425
  * The grips paint only for a NON-null window, so an uncontrolled
329
426
  * minimal bar starts as a bare track; a host that wants the "default =
330
- * everything selected" reading feeds the controlled window `[0, 1]`
331
- * (the chest raw-records adapter does exactly that).
427
+ * everything selected" reading feeds the controlled window covering the
428
+ * whole axis (`[d0, d1]`, i.e. `[0, 1]` on the default domain).
332
429
  * `segments` / `selectedId` are IGNORED in this mode (no segment DOM to
333
430
  * select from). */
334
431
  minimal: { type: Boolean, default: false },
@@ -348,25 +445,36 @@ export default defineComponent({
348
445
 
349
446
  let gesture: Gesture | null = null;
350
447
 
351
- const minWidth = computed(() => {
352
- const raw = Number(props.minWindow);
353
- return Number.isFinite(raw) && raw > 0 ? Math.min(raw, 1) : MIN_WINDOW_FALLBACK;
354
- });
355
-
356
- /** Sanitized trailing headroom: a non-finite or negative value is no
357
- * headroom at all, and more than a full domain of padding is capped
358
- * (the axis never exceeds 2× the content). */
448
+ /** Sanitized trailing headroom (the DEPRECATED `domain` alias): a
449
+ * non-finite or negative value is no headroom at all, and more than a
450
+ * full axis of extra range is capped, so the alias axis never exceeds
451
+ * `[0, 2]`. */
359
452
  const headroom = computed(() => {
360
453
  const raw = Number(props.headroom);
361
454
  return Number.isFinite(raw) && raw > 0 ? Math.min(raw, 1) : 0;
362
455
  });
363
456
 
364
- /** Width of the minimap's axis in content fractions. Every minimap x is
365
- * divided by it; the detail layer never is. `minimal` mode suppresses
366
- * the lane rows and the detail layer (its bare bar still lives in the
367
- * overview container), so it ignores the headroom and keeps the content
368
- * axis — 100% stays at the right edge. */
369
- const axisSpan = computed(() => (props.minimal ? 1 : 1 + headroom.value));
457
+ /** The effective axis: the caller's valid `domain`, else the deprecated
458
+ * `headroom` shorthand `[0, 1 + headroom]`, else the unit axis. Every
459
+ * geometry path (minimap x, scrims, handles, pointer input) reads this
460
+ * one pair, so a declared domain and the alias cannot disagree, and
461
+ * `minimal` mode draws the same axis as the full ribbon. */
462
+ const domain = computed<DomainRange>(() => {
463
+ const provided = sanitizeDomain(props.domain);
464
+ if (provided) return provided;
465
+ const extra = headroom.value;
466
+ return extra > 0 ? [0, 1 + extra] : UNIT_DOMAIN;
467
+ });
468
+
469
+ /** Narrowest window the ribbon will produce, in DOMAIN units. A request
470
+ * wider than the axis is capped at the span: a minWindow longer than the
471
+ * domain could never be satisfied inside it. */
472
+ const minWidth = computed(() => {
473
+ const raw = Number(props.minWindow);
474
+ const span = domainSpan(domain.value);
475
+ const requested = Number.isFinite(raw) && raw > 0 ? raw : MIN_WINDOW_FALLBACK;
476
+ return Math.min(requested, span);
477
+ });
370
478
 
371
479
  /** A supplied `window` prop (even null) is the controlled contract; no
372
480
  * prop at all means "keep your own state". */
@@ -375,7 +483,7 @@ export default defineComponent({
375
483
  const activeWindow = computed<WindowRange | null>(() => {
376
484
  if (!props.windowEnabled) return null;
377
485
  const source = controlled.value ? props.window : internalWindow.value;
378
- return normalizeHkRangeWindow(source, minWidth.value);
486
+ return normalizeHkRangeWindow(source, minWidth.value, domain.value);
379
487
  });
380
488
 
381
489
  const lanes = computed<RibbonLane[]>(() =>
@@ -395,11 +503,15 @@ export default defineComponent({
395
503
  * would otherwise resurrect the card with no pointer or focus. */
396
504
  const renderedSegmentIds = computed(() => {
397
505
  const win = activeWindow.value;
506
+ const axis = domain.value;
398
507
  const declared = new Set(lanes.value.map((lane) => lane.key));
399
508
  const ids = new Set<string>();
400
509
  for (const placed of placedSegments.value) {
401
510
  if (!declared.has(placed.segment.lane)) continue;
402
- if (win && !intersectsWindow(placed, win)) continue;
511
+ // With a window the clipping site is the window; without one it is
512
+ // the domain (the detail's no-window axis), so a segment outside the
513
+ // caller's axis cannot leave a tip card behind.
514
+ if (win ? !intersectsWindow(placed, win) : clipToDomain(placed, axis) === null) continue;
403
515
  ids.add(placed.segment.id);
404
516
  }
405
517
  return ids;
@@ -411,9 +523,10 @@ export default defineComponent({
411
523
  }
412
524
  });
413
525
 
414
- /** Emit the window in FULL-DOMAIN fractions; the uncontrolled fallback
415
- * mirrors it into local state so the ribbon still zooms without a host
416
- * listener. Controlled hosts own the prop and are never overwritten. */
526
+ /** Emit the window in absolute coordinates on the caller's domain axis;
527
+ * the uncontrolled fallback mirrors it into local state so the ribbon
528
+ * still zooms without a host listener. Controlled hosts own the prop and
529
+ * are never overwritten. */
417
530
  function commitWindow(next: WindowRange | null): void {
418
531
  if (!props.windowEnabled) return;
419
532
  if (!controlled.value) internalWindow.value = next;
@@ -432,11 +545,12 @@ export default defineComponent({
432
545
  /** A window that covers the whole domain IS the unfiltered state — there
433
546
  * is nothing to reset back to (2026-11-07, the raw-records consumer: a
434
547
  * minimal bar paints its grips for a non-null window, so its rest state
435
- * is the FULL selection `[0, 1]`; without this check Escape "reset" it
548
+ * is the full axis `[d0, d1]`; without this check Escape "reset" it
436
549
  * every press, swallowed the key, and the hosting dialog could never
437
550
  * close while the bar held focus). */
438
551
  function isFullDomain(win: WindowRange | null): boolean {
439
- return win !== null && win[0] <= WINDOW_EPSILON && win[1] >= 1 - WINDOW_EPSILON;
552
+ const [d0, d1] = domain.value;
553
+ return win !== null && win[0] <= d0 + WINDOW_EPSILON && win[1] >= d1 - WINDOW_EPSILON;
440
554
  }
441
555
 
442
556
  /** Returns true when a window actually existed AND was narrower than the
@@ -452,23 +566,28 @@ export default defineComponent({
452
566
  return true;
453
567
  }
454
568
 
455
- /** Pointer x → absolute CONTENT fraction (0..1 of the real progress).
456
- * The pointer reads as a fraction of the strip's WHOLE width — the
457
- * axis, headroom included — so the reading is scaled by the span and
458
- * clamped: a press in the blank tail lands on content 100% instead of
459
- * inventing progress the host never declared. This is the only
460
- * axis→content conversion in the component. */
569
+ /** Pointer x → a CONTENT coordinate in the caller's DOMAIN units. The
570
+ * pointer reads as a fraction of the strip's WHOLE width, so the reading
571
+ * is mapped onto the axis (`d0 + x * span`) and clamped to it: a press
572
+ * past either edge lands on that domain edge, never outside the
573
+ * caller's coordinates. This is the only axis→content conversion in the
574
+ * component. */
461
575
  function fractionFrom(clientX: number): number | null {
462
576
  const strip = stripRef.value;
463
577
  if (!strip) return null;
464
578
  const rect = strip.getBoundingClientRect();
465
579
  if (!(rect.width > 0)) return null;
466
- return clamp01(((clientX - rect.left) / rect.width) * axisSpan.value);
580
+ const [d0, d1] = domain.value;
581
+ return clampTo(d0 + ((clientX - rect.left) / rect.width) * (d1 - d0), d0, d1);
467
582
  }
468
583
 
469
584
  function brushTo(fraction: number): void {
470
585
  if (!gesture || gesture.kind !== "brush") return;
471
- const anchor = gesture.anchor;
586
+ const [d0, d1] = domain.value;
587
+ // The anchor was captured at pointerdown; a `domain` prop that changes
588
+ // mid-gesture would otherwise let a stale anchor build a window outside
589
+ // the current axis.
590
+ const anchor = clampTo(gesture.anchor, d0, d1);
472
591
  const min = minWidth.value;
473
592
  let lo = Math.min(anchor, fraction);
474
593
  let hi = Math.max(anchor, fraction);
@@ -486,31 +605,33 @@ export default defineComponent({
486
605
  hi = anchor;
487
606
  lo = anchor - min;
488
607
  }
489
- if (lo < 0) {
490
- lo = 0;
491
- hi = Math.min(1, min);
492
- } else if (hi > 1) {
493
- hi = 1;
494
- lo = Math.max(0, 1 - min);
608
+ if (lo < d0) {
609
+ lo = d0;
610
+ hi = Math.min(d1, d0 + min);
611
+ } else if (hi > d1) {
612
+ hi = d1;
613
+ lo = Math.max(d0, d1 - min);
495
614
  }
496
615
  }
497
616
  commitWindow([lo, hi]);
498
617
  }
499
618
 
500
- /** The window produced by moving ONE edge to `fraction` (absolute domain
501
- * fraction), clamped so the window never crosses itself and never drops
502
- * below minWindow. Pure: drag and keyboard share it. */
619
+ /** The window produced by moving ONE edge to `fraction` (a DOMAIN-unit
620
+ * coordinate), clamped so the window never crosses itself, never drops
621
+ * below minWindow and never leaves the caller's axis. Pure: drag and
622
+ * keyboard share it. */
503
623
  function edgeWindow(
504
624
  win: WindowRange,
505
625
  edge: "start" | "end",
506
626
  fraction: number,
507
627
  ): WindowRange {
508
628
  const min = minWidth.value;
629
+ const [d0, d1] = domain.value;
509
630
  const [lo, hi] = win;
510
631
  if (edge === "start") {
511
- return [Math.max(0, Math.min(fraction, hi - min)), hi];
632
+ return [Math.max(d0, Math.min(fraction, hi - min)), hi];
512
633
  }
513
- return [lo, Math.min(1, Math.max(fraction, lo + min))];
634
+ return [lo, Math.min(d1, Math.max(fraction, lo + min))];
514
635
  }
515
636
 
516
637
  function dragEdge(edge: "start" | "end", fraction: number): void {
@@ -573,41 +694,52 @@ export default defineComponent({
573
694
  /** Arrow = slide the whole window; Shift+Arrow = resize from the
574
695
  * trailing (end) edge. A plain arrow with no window is inert, so the
575
696
  * full-domain view cannot be nudged into a meaningless window; a
576
- * Shift+Arrow contracts the full domain into one (keyboard entry).
577
- * Inert and no-op arrows are decided FIRST and left un-prevented, so
578
- * the host's normal arrow behaviour survives them. */
697
+ * Shift+Arrow contracts the full domain into one (keyboard entry). The
698
+ * nudge is 5% of the VISIBLE span, so a domain of [0, 2] steps 0.1 while
699
+ * the unit axis keeps the classic 0.05. Inert and no-op arrows are
700
+ * decided FIRST and left un-prevented, so the host's normal arrow
701
+ * behaviour survives them. */
579
702
  function onStripKeyDown(event: KeyboardEvent): void {
580
703
  if (!props.windowEnabled) return;
581
704
  if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
582
705
  const direction = event.key === "ArrowRight" ? 1 : -1;
706
+ const [d0, d1] = domain.value;
707
+ const step = KEYBOARD_STEP * (d1 - d0);
583
708
  const win = activeWindow.value;
584
709
  const min = minWidth.value;
585
710
  let next: WindowRange | null = null;
586
711
  if (!event.shiftKey) {
587
712
  if (!win) return; // inert without a window
588
713
  const width = win[1] - win[0];
589
- const nextLo = Math.min(Math.max(win[0] + direction * KEYBOARD_STEP, 0), 1 - width);
714
+ const nextLo = Math.min(Math.max(win[0] + direction * step, d0), d1 - width);
590
715
  next = [nextLo, nextLo + width];
591
716
  } else if (!win) {
592
717
  if (direction > 0) return; // the full domain cannot grow
593
- const end = Math.max(min, 1 - KEYBOARD_STEP);
594
- if (end >= 1) return;
595
- next = [0, end];
718
+ // `min` is a WIDTH and the stop is a COORDINATE, so the floor is
719
+ // `d0 + min`, never the bare width. Using the width went dead on
720
+ // axes whose end sits below minWindow (the floor exceeded the domain
721
+ // end) and emitted sub-minimum windows on tight axes.
722
+ const end = Math.max(d0 + min, d1 - step);
723
+ if (end >= d1) return;
724
+ next = [d0, end];
596
725
  } else {
597
- next = [win[0], Math.min(1, Math.max(win[0] + min, win[1] + direction * KEYBOARD_STEP))];
726
+ next = [win[0], Math.min(d1, Math.max(win[0] + min, win[1] + direction * step))];
598
727
  }
599
728
  if (next && commitIfChanged(next)) event.preventDefault();
600
729
  }
601
730
 
602
- /** Handle sliders keep their own edge keyboard-editable. */
731
+ /** Handle sliders keep their own edge keyboard-editable (same 5%-of-span
732
+ * nudge as the strip). */
603
733
  function onHandleKeyDown(edge: "start" | "end", event: KeyboardEvent): void {
604
734
  if (!props.windowEnabled) return;
605
735
  if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
606
736
  const win = activeWindow.value;
607
737
  if (!win) return;
608
738
  const direction = event.key === "ArrowRight" ? 1 : -1;
739
+ const [d0, d1] = domain.value;
740
+ const step = KEYBOARD_STEP * (d1 - d0);
609
741
  const current = edge === "start" ? win[0] : win[1];
610
- const next = edgeWindow(win, edge, current + direction * KEYBOARD_STEP);
742
+ const next = edgeWindow(win, edge, current + direction * step);
611
743
  if (commitIfChanged(next)) event.preventDefault();
612
744
  }
613
745
 
@@ -782,14 +914,14 @@ export default defineComponent({
782
914
  }
783
915
 
784
916
  // Minimap geometry, content → axis (projected through the two helpers
785
- // only). The after scrim runs to the AXIS end, tail included: left is
786
- // the projection of the window end and width is `1 - left`, whereas
787
- // `1 - win[1]` would leave the reserved tail undimmed and read as
788
- // progress the host still owes.
789
- const span = axisSpan.value;
790
- const minimapFrame = win ? axisBox({ left: win[0], width: win[1] - win[0] }, span) : null;
791
- const minimapBefore = win ? axisBox({ left: 0, width: win[0] }, span) : null;
792
- const minimapAfterLeft = win ? projectToAxis(win[1], span) : 0;
917
+ // only). The before scrim starts at the DOMAIN start (axis 0) and the
918
+ // after scrim runs to the DOMAIN end, so both cover exactly the
919
+ // coordinates outside the window — content the domain shows but the
920
+ // caller did not select.
921
+ const axis = domain.value;
922
+ const minimapFrame = win ? axisBox({ left: win[0], width: win[1] - win[0] }, axis) : null;
923
+ const minimapBefore = win ? { left: 0, width: projectToAxis(win[0], axis) } : null;
924
+ const minimapAfterLeft = win ? projectToAxis(win[1], axis) : 0;
793
925
  const minimapAfter = win
794
926
  ? { left: minimapAfterLeft, width: 1 - minimapAfterLeft }
795
927
  : null;
@@ -805,10 +937,12 @@ export default defineComponent({
805
937
  aria-label={t("hikari::ribbon.rangeAria", "Observation range")}
806
938
  aria-describedby={props.windowEnabled ? hintId : undefined}
807
939
  aria-disabled={props.windowEnabled ? undefined : "true"}
808
- aria-valuemin={0}
809
- aria-valuemax={100}
810
- aria-valuenow={percentNumber(win ? win[0] : 0)}
811
- aria-valuetext={`${percentText(win ? win[0] : 0)} – ${percentText(win ? win[1] : 1)}`}
940
+ aria-valuemin={percentNumber(axis[0])}
941
+ aria-valuemax={percentNumber(axis[1])}
942
+ aria-valuenow={percentNumber(win ? win[0] : axis[0])}
943
+ aria-valuetext={`${percentText(win ? win[0] : axis[0])} – ${percentText(
944
+ win ? win[1] : axis[1],
945
+ )}`}
812
946
  title={
813
947
  props.windowEnabled
814
948
  ? t(
@@ -825,15 +959,16 @@ export default defineComponent({
825
959
  }}
826
960
  onKeydown={onStripKeyDown}
827
961
  >
828
- {/* The overview paints the FULL domain only — it never follows
829
- the zoom, so the window's position stays locatable. Its x-axis
830
- is the content plus the reserved headroom, so every bar here is
831
- projected by `axisBox`. */}
962
+ {/* The overview paints the whole DOMAIN only — it never follows
963
+ the zoom, so the window's position stays locatable. Bars are
964
+ clipped to the caller's axis, so content beyond it simply does
965
+ not exist here. */}
832
966
  <div class="hk-range-ribbon-overview-lanes" aria-hidden="true">
833
967
  {!props.minimal && lanes.value.map((lane) => (
834
968
  <div class="hk-range-ribbon-overview-row" key={lane.key} data-lane={lane.key}>
835
969
  {(byLane.get(lane.key) ?? []).map((placed) => {
836
- const box = axisBox(fullDomainBox(placed), span);
970
+ const box = domainBox(placed, axis);
971
+ if (!box) return null;
837
972
  return (
838
973
  <div
839
974
  key={placed.segment.id}
@@ -881,19 +1016,19 @@ export default defineComponent({
881
1016
  data-window-enabled={props.windowEnabled ? "true" : "false"}
882
1017
  onKeydown={onRootKeyDown}
883
1018
  >
884
- {/* LAYER 1 — the minimap: the full domain, the brush surface, the
885
- window chrome. It shares the lanes' label column (an empty
886
- gutter first), so both layers always start at the same inline
887
- x; their x% agree only in the full-domain view (a window
888
- re-normalizes the detail, a headroom compresses the minimap by
889
- `1/span`). */}
1019
+ {/* LAYER 1 — the minimap: the caller's whole domain, the brush
1020
+ surface, the window chrome. It shares the lanes' label column
1021
+ (an empty gutter first), so both layers always start at the same
1022
+ inline x; their x% agree only in the full-domain view (a window
1023
+ re-normalizes the detail, a non-unit domain rescales the
1024
+ minimap). */}
890
1025
  <div class="hk-range-ribbon-overview" data-layer="minimap">
891
1026
  {/* The gutter's width IS the shared label column: the
892
1027
  component JS-measures the widest rendered label and
893
1028
  publishes it on the root (two-phase free/measure/pin), so
894
1029
  this empty cell keeps both layers' inline START aligned at
895
1030
  any label width (their x% only agree in the full-domain
896
- view, with no headroom). */}
1031
+ view). */}
897
1032
  <span class="hk-range-ribbon-overview-gutter" aria-hidden="true" />
898
1033
  <div class="hk-range-ribbon-overview-field">
899
1034
  {strip}
@@ -906,11 +1041,11 @@ export default defineComponent({
906
1041
  aria-orientation="horizontal"
907
1042
  tabindex={0}
908
1043
  aria-label={t("hikari::ribbon.windowStart", "Window start")}
909
- aria-valuemin={0}
1044
+ aria-valuemin={percentNumber(axis[0])}
910
1045
  aria-valuemax={percentNumber(win[1] - minWidth.value)}
911
1046
  aria-valuenow={percentNumber(win[0])}
912
1047
  aria-valuetext={percentText(win[0])}
913
- style={{ left: percent(projectToAxis(win[0], span)) }}
1048
+ style={{ left: percent(projectToAxis(win[0], axis)) }}
914
1049
  onPointerdown={(event: PointerEvent) => onHandlePointerDown("start", event)}
915
1050
  onKeydown={(event: KeyboardEvent) => onHandleKeyDown("start", event)}
916
1051
  />
@@ -922,10 +1057,10 @@ export default defineComponent({
922
1057
  tabindex={0}
923
1058
  aria-label={t("hikari::ribbon.windowEnd", "Window end")}
924
1059
  aria-valuemin={percentNumber(win[0] + minWidth.value)}
925
- aria-valuemax={100}
1060
+ aria-valuemax={percentNumber(axis[1])}
926
1061
  aria-valuenow={percentNumber(win[1])}
927
1062
  aria-valuetext={percentText(win[1])}
928
- style={{ left: percent(projectToAxis(win[1], span)) }}
1063
+ style={{ left: percent(projectToAxis(win[1], axis)) }}
929
1064
  onPointerdown={(event: PointerEvent) => onHandlePointerDown("end", event)}
930
1065
  onKeydown={(event: KeyboardEvent) => onHandleKeyDown("end", event)}
931
1066
  />
@@ -968,11 +1103,14 @@ export default defineComponent({
968
1103
  </span>
969
1104
  )}
970
1105
  </div>
971
- {/* LAYER 2 — the detail: the same segments, focused. With a window
972
- each bar is clipped to it and re-normalized to the track (so a
973
- [0.35, 0.67] window spans 0..100% here); with no window it is
974
- the full domain. The headroom is deliberately absent: this axis
975
- is the selected content, never the reserved padding. */}
1106
+ {/* LAYER 2 — the detail: the same segments, focused. Its track is
1107
+ always 0..100% of the SELECTED WINDOW, in the caller's domain
1108
+ units: a window of [0.35, 0.67] (the familiar 35%..67% on the
1109
+ default [0, 1] axis) starts the detail at 0 and ends it at 100%,
1110
+ and a segment at 1.0 inside a [0.5, 1.5] window lands at 50%.
1111
+ With no window the map is absent, so the detail's axis is the
1112
+ caller's DOMAIN (the full view): a domain wider than the content
1113
+ leaves blank space instead of stretching the content. */}
976
1114
  {!props.minimal && (
977
1115
  <div class="hk-range-ribbon-detail" data-layer="detail">
978
1116
  <div class="hk-range-ribbon-lanes">
@@ -983,7 +1121,7 @@ export default defineComponent({
983
1121
  </span>
984
1122
  <div class="hk-range-ribbon-lane-track" role="group" aria-label={lane.label}>
985
1123
  {(byLane.get(lane.key) ?? []).map((placed) => {
986
- const box = win ? windowedBox(placed, win) : fullDomainBox(placed);
1124
+ const box = win ? windowedBox(placed, win) : domainBox(placed, axis);
987
1125
  return box ? renderSegment(placed, box) : null;
988
1126
  })}
989
1127
  </div>