import { DrawExpression as E } from "../graphics/draw-expression"; import { GrayImage } from "../graphics/image"; import { menuScrollList, slidingHighlightY, type MenuScrollHighlight } from "../graphics/menu-scroll-list"; import type { InputEvent } from "./gestures"; import { MenuHighlightMotion } from "./menu-highlight-motion"; import { MenuScrollMotion, scrollOffsetExpression, type MenuScrollAnimation } from "./menu-scroll-motion"; /** Selected-row fill while the menu owns input; the outline alone marks an unfocused menu's selection. */ export const MENU_HIGHLIGHT_FILL = 15; export const MENU_HIGHLIGHT_STROKE = 45; const SCROLLBAR_TRACK_VALUE = 30; const SCROLLBAR_THUMB_VALUE = 120; const SCROLLBAR_WIDTH = 3; const SCROLLBAR_MIN_THUMB = 8; /** Largest packed scroll strip, in bytes: the firmware's per-resource limit. */ const MAX_SCROLL_STRIP_BYTES = 65536; /** A bounce overshoots by this fraction of the end row's pitch, as if starting to reveal another row. */ export const BOUNCE_FRACTION = 0.4; export const MAX_BOUNCE = 24; /** * A rectangle in image coordinates. padTop and padBottom are blank rows * inside the scrolled content, before the first row and after the last * (default none): they scroll away with the rows. A list whose box runs to * a window's top or bottom edge passes the padding suggested for that edge * (viewport.ts), so its end rows keep clear of a border line there while * rows scrolled past them are cut off right at the edge. */ export type MenuBox = { x: number; y: number; width: number; height: number; padTop?: number; padBottom?: number }; export type MenuDrawArgs = { /** * Draw into this image, inside the (x, y, width, height) rect. For the * selected row this is a scratch image exactly the rect's size (so x and y * are 0), replayed over the highlight. While a scroll animates, rows are * also drawn into a strip image covering both viewports. Never draw * relative to image.width or image.height, and never outside the rect. */ image: GrayImage; item: T; index: number; x: number; y: number; width: number; height: number; selected: boolean; /** Whether the menu owns input right now: the `focused` flag the host passed to paint. */ focused: boolean; }; export type MenuHighlightStyle = { /** Corner radius of the selection box. Default 8. */ radius?: number; /** Stereo depth of the selection box. Default 0. */ depth?: number; }; export type MenuOptions = { items?: readonly T[]; /** Initial selection. Default: the first selectable item. */ selectedIndex?: number | null; /** Row pitch in pixels (including rowGap) for an item laid out at this width. */ getHeight: (item: T, width: number) => number; /** Default: every item is selectable. Non-selectable items (group labels) are skipped by navigation. */ isSelectable?: (item: T) => boolean; draw: (args: MenuDrawArgs) => void; /** Called by activate() / a click with the selected item. */ onSelect?: (item: T, index: number) => void | Promise; /** * Whether scrolling past either end wraps to the other. When false the * selection stays put and onExitTop / onExitBottom is called instead; with * no callback for that end, the list bounces. */ wrap?: boolean; onExitTop?: () => void; onExitBottom?: () => void; /** Pixels between consecutive rows, excluded from each row's drawable box and highlight. Default 0. */ rowGap?: number; /** Selection box style, or false to draw no highlight (the draw callback shows the selection itself). */ highlight?: MenuHighlightStyle | false; }; /** Row tops and pitches in content coordinates; `total` includes the box's padTop and padBottom. */ type MenuLayout = { tops: number[]; heights: number[]; total: number }; /** * A vertical list with one selected row: the menu proper, independent of the * Layer stack. A host paints it into a rect of its own image and forwards * scroll / click events while the menu has focus; the host keeps the rest * (title, box, focus between several menus, back navigation). * * Rows may vary in height and some may be unselectable; navigation skips * those. Scrolling is pixel-based: the viewport moves the minimum needed to * keep the selection and its neighbors fully visible (just the selection * when they don't all fit), then aligns to a row top so the list never * starts with a partially visible row. A row cut off by the viewport's edge * is drawn clipped, so a box that isn't a whole number of rows tall shows * part of the next row as a hint that there is more. * * Navigation that scrolls (without wrapping) animates on the glasses: the * rows visible before and after are drawn into one strip, and a display list * slides a viewport-sized copy of it while the highlight moves on the same * timeline. Scrolling past an end without wrap or an exit callback bounces * the same way, with the highlight carried along by its row. When the strip * would be too large or the menu doesn't fit the assumptions in scrollStrip, * the motion snaps instead. */ export class Menu { private itemList: readonly T[]; private selected: number | null; /** * The caller asked for no selection. Otherwise a null selection only means * nothing was selectable, and the first selectable item is chosen as soon * as one exists (a menu created empty and filled later starts on it). */ private deselected: boolean; private scrollY = 0; private lastBox: MenuBox | null = null; private readonly motion = new MenuHighlightMotion(); private readonly scrollMotion = new MenuScrollMotion(); constructor(private readonly options: MenuOptions) { this.itemList = options.items ?? []; this.deselected = options.selectedIndex === null; this.selected = this.settle(options.selectedIndex ?? null); } get items(): readonly T[] { return this.itemList; } get selectedIndex(): number | null { this.reconcile(); return this.selected; } get selectedItem(): T | null { const index = this.selectedIndex; return index === null ? null : this.itemList[index]!; } /** Content offset of the viewport's top edge, in pixels. */ get scrollTop(): number { return this.scrollY; } /** Move the viewport's top edge; the next paint clamps it and scrolls the selection back into view. */ set scrollTop(value: number) { this.scrollY = Math.max(0, value | 0); } /** True when the content did not fit the box given to the last paint. */ get overflows(): boolean { if (!this.lastBox) return false; return this.layout(this.lastBox).total > this.lastBox.height; } /** * Replace the items. `selectedIndex` names the new selection (null for * none); left out, the selection stays at the same index, clamped into * range, or lands on the first selectable item if there was none. The * viewport keeps the selected row at the same on-screen position when it can. */ setItems(items: readonly T[], selectedIndex?: number | null): void { const box = this.lastBox; const before = this.selected !== null && box ? this.layout(box).tops[this.selected]! - this.scrollY : null; this.itemList = items; if (selectedIndex !== undefined) this.deselected = selectedIndex === null; this.selected = this.settle(selectedIndex === undefined ? this.selected : selectedIndex); if (before !== null && this.selected !== null && box) { this.scrollY = Math.max(0, this.layout(box).tops[this.selected]! - before); } } /** * Move the selection; a non-selectable or out-of-range index lands on the * nearest selectable one. null clears it until the user scrolls or a * number is selected. */ select(index: number | null): void { this.deselected = index === null; this.selected = this.settle(index); } /** Step the selection by one selectable row; handles wrap and the exit callbacks. */ moveSelection(delta: -1 | 1): void { this.reconcile(); const from = this.selected; const next = this.nextSelectable(from, delta); if (next !== null) { if (from !== null) this.motion.navigate(from, false); this.scrollMotion.navigate(false); this.selected = next; this.deselected = false; return; } if (from === null && this.scrollContent(delta)) return; if (this.options.wrap) { const wrapped = this.nextSelectable(null, delta); if (wrapped !== null && wrapped !== from) { if (from !== null) this.motion.navigate(from, true); this.scrollMotion.navigate(true); this.selected = wrapped; this.deselected = false; } else if (from === null && this.lastBox) { this.scrollY = delta > 0 ? 0 : this.maxScroll(this.layout(this.lastBox), this.lastBox.height); } return; } const exit = delta > 0 ? this.options.onExitBottom : this.options.onExitTop; if (exit) exit(); else this.bounce(delta); } /** Invoke onSelect for the selected item. Returns false when nothing is selected. */ async activate(): Promise { this.reconcile(); if (this.selected === null) return false; await this.options.onSelect?.(this.itemList[this.selected]!, this.selected); return true; } /** Handle scroll-up, scroll-down and click. Returns false for any other event, or a click with nothing selected. */ async handleInput(event: InputEvent): Promise { switch (event.type) { case "scroll-up": this.moveSelection(-1); return true; case "scroll-down": this.moveSelection(1); return true; case "click": return this.activate(); default: return false; } } /** The selectable item under image-coordinate y in the last painted box, for touch/mirror input. */ indexAt(y: number): number | null { const box = this.lastBox; if (!box || y < box.y || y >= box.y + box.height) return null; const layout = this.layout(box); const contentY = y - box.y + this.scrollY; for (let index = 0; index < this.itemList.length; index++) { if (contentY >= layout.tops[index]! && contentY < layout.tops[index]! + layout.heights[index]!) { return this.isSelectable(index) ? index : null; } } return null; } paint(image: GrayImage, box: MenuBox, focused: boolean): void { this.lastBox = box; this.reconcile(); const layout = this.layout(box); this.ensureVisible(layout, box.height); const now = Date.now(); const scroll = this.scrollMotion.paint(this.scrollY, box, now); const strip = scroll ? this.scrollStrip(image, layout, box, focused, scroll) : null; if (scroll && !strip) this.scrollMotion.cancel(); const gap = this.options.rowGap ?? 0; const highlight = this.options.highlight; let scrollHighlight: MenuScrollHighlight | undefined; for (let index = 0; index < this.itemList.length; index++) { const top = layout.tops[index]! - this.scrollY; const height = layout.heights[index]! - gap; const selected = index === this.selected; if (top + height <= 0 || top >= box.height) continue; const rowY = box.y + top; const item = this.itemList[index]!; if (selected && highlight !== false) { const animation = this.motion.paint(index, this.scrollY, box.x, rowY, box.width, height, now, !!strip); const background = focused ? MENU_HIGHLIGHT_FILL : 0; if (strip && scroll) { // The strip already holds this row's content; only the box is drawn over it. let y = slidingHighlightY(top, animation, scroll.startedAt); // A bounce carries the highlight with its row. if (scroll.peak !== undefined) y = y.add(E.i32(scroll.to)).sub(scrollOffsetExpression(scroll)); scrollHighlight = { y, width: box.width, height, radius: highlight?.radius ?? 8, background, border: MENU_HIGHLIGHT_STROKE }; continue; } // A selected row taller than the box is drawn whole, from its top. const row = new GrayImage(box.width, height, 0); this.options.draw({ image: row, item, index, x: 0, y: 0, width: box.width, height, selected, focused }); image.drawMenuSelection(row, box.x, rowY, background, MENU_HIGHLIGHT_STROKE, highlight?.radius ?? 8, highlight?.depth ?? 0, animation); } else { this.drawRow(image, index, box.x, rowY, box.width, height, focused, box.y, box.y + box.height); } } // The rows painted above stay underneath: once the animation ends, the // strip's final frame and the static paint are pixel-identical. if (strip && scroll) { const sourceY = scrollOffsetExpression(scroll).sub(E.i32(strip.top)); image.drawDisplayList(menuScrollList(strip.image, strip.x, box.height, scroll, sourceY, scrollHighlight), box.x, box.y, box.width, box.height, 0); } } /** Draw a vertical scrollbar for the last painted box (no-op unless the content overflows it). */ drawScrollbar(image: GrayImage, x: number, y: number, height: number): void { const box = this.lastBox; if (!box) return; const layout = this.layout(box); if (layout.total <= box.height) return; const maxScroll = this.maxScroll(layout, box.height); const thumbHeight = Math.max(SCROLLBAR_MIN_THUMB, (height * box.height / layout.total) | 0); const fraction = Math.min(1, Math.max(0, this.scrollY) / maxScroll); image.fillRect(x, y, SCROLLBAR_WIDTH, height, SCROLLBAR_TRACK_VALUE); image.fillRect(x, y + (((height - thumbHeight) * fraction) | 0), SCROLLBAR_WIDTH, thumbHeight, SCROLLBAR_THUMB_VALUE); } /** * Draw one row at (x, y), clipped to target rows [clipTop, clipBottom). * Selected rows with a highlight are drawn in a scratch image the row's * size, like the static selection, which clips their ink to the row. */ private drawRow(target: GrayImage, index: number, x: number, y: number, width: number, height: number, focused: boolean, clipTop: number, clipBottom: number): void { const item = this.itemList[index]!; const selected = index === this.selected; const scratch = selected && this.options.highlight !== false; if (!scratch && y >= clipTop && y + height <= clipBottom) { this.options.draw({ image: target, item, index, x, y, width, height, selected, focused }); return; } const row = new GrayImage(width, height, 0); this.options.draw({ image: row, item, index, x: 0, y: 0, width, height, selected, focused }); const skip = Math.max(0, clipTop - y); target.bitBlt(row.withDrawsBaked(), x, y + skip, { sy: skip, height: Math.min(height, clipBottom - y) - skip, transparentZero: true }); } /** * Render every row visible at any point of the motion into one strip, or * return null to snap. Its first and last frames must match the static * paints on either side, which clip rows at the viewport's edges the same * way. The strip copy is opaque, so this also requires a black background * under the menu, a selected row that fits, and a highlight at the menu's * own depth. */ private scrollStrip(image: GrayImage, layout: MenuLayout, box: MenuBox, focused: boolean, scroll: MenuScrollAnimation): { image: GrayImage; x: number; top: number } | null { const highlight = this.options.highlight; if (highlight !== false && (highlight?.depth ?? 0) !== 0) return null; const gap = this.options.rowGap ?? 0; const selected = this.selected; if (selected !== null && layout.tops[selected]! + layout.heights[selected]! - gap - scroll.to > box.height) return null; const offsets = [scroll.from, scroll.to, scroll.peak ?? scroll.to]; const top = Math.min(...offsets); const bottom = Math.max(...offsets) + box.height; const strip = new GrayImage(box.width, bottom - top, 0); for (let index = 0; index < this.itemList.length; index++) { const rowTop = layout.tops[index]!; const height = layout.heights[index]! - gap; if (rowTop + height <= top || rowTop >= bottom) continue; this.drawRow(strip, index, 0, rowTop - top, box.width, height, focused, 0, strip.height); } // Crop to the columns with ink; the static paint shows the rest unchanged. const baked = strip.withDrawsBaked(); let left = baked.width, right = -1; for (let y = 0; y < baked.height; y++) { const row = y * baked.width; for (let x = 0; x < left; x++) if (baked.pixels[row + x]! >= 8) { left = x; break; } for (let x = baked.width - 1; x > right; x--) if (baked.pixels[row + x]! >= 8) { right = x; break; } } if (right < left) return null; const width = right - left + 1; if (5 + Math.ceil(width / 2) * baked.height > MAX_SCROLL_STRIP_BYTES) return null; // Whatever the host drew under the copied columns would be covered. for (let y = box.y; y < box.y + box.height; y++) { for (let x = box.x + left; x <= box.x + right; x++) { if (x >= 0 && y >= 0 && x < image.width && y < image.height && image.pixels[y * image.width + x]! >= 8) return null; } } const cropped = new GrayImage(width, baked.height, 0); cropped.bitBlt(baked, -left, 0); return { image: cropped, x: left, top }; } /** At an end with nowhere to go, overshoot a little past it and come back. */ private bounce(delta: -1 | 1): void { const count = this.itemList.length; if (!this.lastBox || !count) return; const layout = this.layout(this.lastBox); const pitch = layout.heights[delta > 0 ? count - 1 : 0]!; const amount = Math.min(MAX_BOUNCE, Math.round(pitch * BOUNCE_FRACTION)); if (amount > 0) this.scrollMotion.bounce(delta * amount); } private isSelectable(index: number): boolean { return this.options.isSelectable?.(this.itemList[index]!) ?? true; } /** The next selectable index after `from` in direction `delta`; from null, the first (or last) selectable. */ private nextSelectable(from: number | null, delta: -1 | 1): number | null { const count = this.itemList.length; let index = from === null ? (delta > 0 ? 0 : count - 1) : from + delta; for (; index >= 0 && index < count; index += delta) { if (this.isSelectable(index)) return index; } return null; } /** Resolve a stored selection: null stays null only when the caller deselected. */ private settle(index: number | null): number | null { if (index === null) return this.deselected ? null : this.nextSelectable(null, 1); return this.resolve(index); } /** Clamp an index into range and onto a selectable row (nearest below, else nearest above). */ private resolve(index: number): number | null { if (!this.itemList.length) return null; const clamped = Math.max(0, Math.min(this.itemList.length - 1, index | 0)); if (this.isSelectable(clamped)) return clamped; return this.nextSelectable(clamped, 1) ?? this.nextSelectable(clamped, -1); } /** Re-validate the selection against the current items (they may have been edited in place). */ private reconcile(): void { this.selected = this.settle(this.selected); } private layout(box: MenuBox): MenuLayout { const tops: number[] = []; const heights: number[] = []; let total = Math.max(0, (box.padTop ?? 0) | 0); for (const item of this.itemList) { const height = Math.max(0, this.options.getHeight(item, box.width) | 0); tops.push(total); heights.push(height); total += height; } if (this.itemList.length) total -= this.options.rowGap ?? 0; total += Math.max(0, (box.padBottom ?? 0) | 0); return { tops, heights, total }; } /** * Where the viewport's top rests to show row `index` from its start: the * row's top, or for the first row the content's, so the padding above it * shows too. */ private restTop(layout: MenuLayout, index: number): number { return index === 0 ? 0 : layout.tops[index]!; } private maxScroll(layout: MenuLayout, viewportHeight: number): number { return Math.max(0, layout.total - viewportHeight); } /** Scroll the viewport so the selected row is fully inside it, aligning the top to a row edge when it moves. */ private ensureVisible(layout: MenuLayout, viewportHeight: number): void { if (this.selected === null) { this.scrollY = Math.max(0, Math.min(this.maxScroll(layout, viewportHeight), this.scrollY)); return; } const gap = this.options.rowGap ?? 0; const selected = this.selected; const last = this.itemList.length - 1; const top = layout.tops[selected]!; const bottom = top + layout.heights[selected]! - gap; // The content's padding counts as part of its end rows: showing the // first row shows the padding above it, and the last the padding below. const startOf = (index: number) => this.restTop(layout, index); const endOf = (index: number) => index === last ? layout.total : layout.tops[index]! + layout.heights[index]! - gap; // Keep the neighbors in view too when all three fit, so the user sees // what the next step will reach. const contextTop = startOf(Math.max(0, selected - 1)); const contextBottom = endOf(Math.min(last, selected + 1)); const paddedFits = endOf(selected) - startOf(selected) <= viewportHeight; const fits = contextBottom - contextTop <= viewportHeight; const wantTop = fits ? contextTop : paddedFits ? startOf(selected) : top; const wantBottom = fits ? contextBottom : paddedFits ? endOf(selected) : bottom; let target = this.scrollY; if (wantTop < target) { target = wantTop; } else if (wantBottom > target + viewportHeight) { // A row taller than the viewport shows from its top. target = Math.min(top, wantBottom - viewportHeight); // Snap to the first row that starts inside the viewport: the wanted // rows still fit (their bottom is within viewportHeight of that top). for (let index = 0; index <= selected; index++) { if (startOf(index) >= target) { target = startOf(index); break; } } } // Never scroll past the end (setItems can leave the viewport there when // rows are removed or inserted above the selection): pull back to the // first row top that still shows the last row, so no partial row starts // the list. The selected row stays visible, since it ends by the list's end. const maxScroll = this.maxScroll(layout, viewportHeight); if (target > maxScroll) { const aligned = layout.tops.map((_, index) => startOf(index)).find((rowTop) => rowTop >= maxScroll); target = aligned !== undefined && aligned <= target ? aligned : maxScroll; } this.scrollY = Math.max(0, target); } /** With nothing selectable, up/down page the content by rows. Returns false at the end being scrolled past. */ private scrollContent(delta: -1 | 1): boolean { if (!this.lastBox) return false; const layout = this.layout(this.lastBox); const maxScroll = this.maxScroll(layout, this.lastBox.height); const stops = layout.tops.map((_, index) => this.restTop(layout, index)); if (delta > 0) { if (this.scrollY >= maxScroll) return false; const next = stops.find((top) => top > this.scrollY); this.scrollY = Math.min(maxScroll, next ?? maxScroll); } else { if (this.scrollY <= 0) return false; let previous = 0; for (const top of stops) if (top < this.scrollY) previous = top; this.scrollY = Math.max(0, previous); } return true; } }