@blotch/dolan 22.2.2 → 22.2.4

package/dist/ui/components/dock/dock-scroll.test.ts

@@ -0,0 +1,130 @@
+import { Component, signal } from '@angular/core';
+import {
+  fireEvent,
+  render,
+  waitForUpdate,
+} from '@blotch/angular-lynx-testing-library';
+import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
+import { describe, expect, it } from 'vitest';
+import { UiDockScroll, UiDockState } from './dock-scroll';
+
+@Component({
+  imports: [LYNX_ELEMENTS, UiDockScroll],
+  template: `
+    @if (shown()) {
+      <scroll-view ui-dock-scroll scroll-orientation="vertical">
+        <view style="height: 2000px"></view>
+      </scroll-view>
+    }
+  `,
+})
+class ScrollHost {
+  readonly shown = signal(true);
+}
+
+const renderScroll = async () => {
+  const result = await render(ScrollHost);
+  const host = result.componentRef.instance as ScrollHost;
+  const state = result.componentRef.injector.get(UiDockState);
+  const scrollView = () => result.container.querySelector('scroll-view')!;
+  /**
+   * Scrolls the content to `scrollTop`, as Lynx reports it.
+   */
+  const scrollTo = (scrollTop: number) =>
+    fireEvent.scroll(scrollView(), {
+      detail: { scrollTop, scrollHeight: 2000 },
+    });
+  return { ...result, host, state, scrollView, scrollTo };
+};
+
+describe('UiDockScroll', () => {
+  it('minimizes the dock as content scrolls down, and expands it as it scrolls up', async () => {
+    const { state, scrollTo } = await renderScroll();
+    expect(state.minimized()).toBe(false);
+
+    // A little way down isn't enough: a small drag leaves the dock whole.
+    scrollTo(10);
+    scrollTo(20);
+    expect(state.minimized()).toBe(false);
+    scrollTo(30);
+    expect(state.minimized()).toBe(true);
+
+    // Further down keeps it minimized.
+    scrollTo(300);
+    expect(state.minimized()).toBe(true);
+
+    // A glance back up brings it back.
+    scrollTo(295);
+    scrollTo(290);
+    expect(state.minimized()).toBe(true);
+    scrollTo(287);
+    expect(state.minimized()).toBe(false);
+  });
+
+  it('counts the distance again when content turns', async () => {
+    const { state, scrollTo } = await renderScroll();
+    scrollTo(100);
+    expect(state.minimized()).toBe(true);
+    scrollTo(80);
+    expect(state.minimized()).toBe(false);
+
+    // Down 20 after coming up 20 starts a new count, short of minimizing.
+    scrollTo(100);
+    expect(state.minimized()).toBe(false);
+    // An event with no movement keeps the count.
+    scrollTo(100);
+    scrollTo(104);
+    expect(state.minimized()).toBe(true);
+  });
+
+  it('expands the dock at the top, including the bounce above it', async () => {
+    const { state, scrollTo } = await renderScroll();
+    scrollTo(200);
+    expect(state.minimized()).toBe(true);
+
+    scrollTo(5);
+    expect(state.minimized()).toBe(false);
+
+    scrollTo(200);
+    expect(state.minimized()).toBe(true);
+    scrollTo(-30);
+    expect(state.minimized()).toBe(false);
+  });
+
+  it("ignores iOS's bounce back from past the end", async () => {
+    const { state, scrollTo, scrollView } = await renderScroll();
+    // The scroll view is 800px tall, so its content ends at 1200.
+    fireEvent.layoutchange(scrollView(), {
+      detail: { width: 400, height: 800 },
+    });
+    scrollTo(1150);
+    scrollTo(1250);
+    expect(state.minimized()).toBe(true);
+
+    // Bouncing back from 1250 to the end reads as scrolling up, but isn't.
+    scrollTo(1230);
+    scrollTo(1210);
+    expect(state.minimized()).toBe(true);
+
+    // Scrolling up from the end is.
+    scrollTo(1200);
+    scrollTo(1180);
+    expect(state.minimized()).toBe(false);
+  });
+
+  it('expands the dock when the scroll view goes, and stops listening', async () => {
+    const { host, state, scrollTo, scrollView } = await renderScroll();
+    const removed = scrollView();
+    scrollTo(200);
+    expect(state.minimized()).toBe(true);
+
+    host.shown.set(false);
+    await waitForUpdate();
+    expect(state.minimized()).toBe(false);
+
+    fireEvent.scroll(removed, {
+      detail: { scrollTop: 600, scrollHeight: 2000 },
+    });
+    expect(state.minimized()).toBe(false);
+  });
+});

package/dist/ui/components/dock/dock-scroll.ts

@@ -0,0 +1,133 @@
+import {
+  DestroyRef,
+  Directive,
+  ElementRef,
+  Injectable,
+  Renderer2,
+  inject,
+  signal,
+} from '@angular/core';
+
+/**
+ * Whether the dock is minimized, shared by the dock and the scroll views that
+ * minimize it. A service rather than an input, because the two sit in
+ * different parts of the app: the dock beside the `<router-outlet>`, and the
+ * scroll views inside the routed screens, which can't reach it.
+ *
+ * ```ts
+ * // Bring the dock back from code, after a search, for example.
+ * inject(UiDockState).minimized.set(false);
+ * ```
+ *
+ * This is what the app asks for. Whether the dock is minimized now is the
+ * dock's own `minimized()`: it stays whole where its design doesn't minimize.
+ */
+@Injectable({ providedIn: 'root' })
+export class UiDockState {
+  /**
+   * Whether the dock should be minimized: on iOS 26 and later and the web,
+   * the bar shrinks to the selected item's icon, and on Android's Material
+   * design it slides away. The frosted design of iOS 15 to 25 doesn't
+   * minimize, as Apple's tab bars didn't, so there it stays expanded whatever
+   * this says.
+   */
+  readonly minimized = signal(false);
+}
+
+/**
+ * How far content scrolls the same way before the dock follows, in px: a
+ * longer way down than up, as iOS's tab bar does, so a small drag doesn't
+ * hide it, but a glance back up brings it back.
+ */
+const MINIMIZE_AFTER = 24;
+const EXPAND_AFTER = 12;
+
+/**
+ * Near enough to the top that the dock expands, in px: content scrolled back
+ * to its start always shows the whole dock.
+ */
+const TOP = 8;
+
+/** What Lynx sends with `scroll` and `layoutchange`, as far as this reads. */
+type ScrollDetail = { scrollTop: number; scrollHeight: number };
+type LayoutDetail = { height: number };
+
+/**
+ * Minimizes the dock while this scroll view scrolls down, and expands it when
+ * it scrolls up or back to the top, as iOS 26 minimizes its tab bar
+ * (`tabBarMinimizeBehavior(.onScrollDown)`). Put it on each screen's
+ * `<scroll-view>` (or `<list>`) that should minimize the dock:
+ *
+ * ```html
+ * <scroll-view ui-dock-scroll scroll-orientation="vertical" class="h-full">
+ *   …
+ * </scroll-view>
+ * ```
+ *
+ * It listens to the scroll view's `scroll` events itself, outside Angular's
+ * templates: a template listener would run change detection for every event,
+ * many times a second while content moves, where this updates the dock only
+ * when it should change. AngularLynx already runs it on Lynx's main thread,
+ * beside the native scroll, so it needs no main-thread script.
+ *
+ * Leaving the screen expands the dock again, so the next screen starts with
+ * it whole.
+ */
+@Directive({ selector: 'scroll-view[ui-dock-scroll], list[ui-dock-scroll]' })
+export class UiDockScroll {
+  readonly #state = inject(UiDockState);
+  readonly #renderer = inject(Renderer2);
+  readonly #element = inject(ElementRef).nativeElement;
+
+  /** The last scroll position, to tell which way content moved. */
+  #lastTop = 0;
+  /** How far content has moved the same way, negative upward. */
+  #travel = 0;
+  /** The scroll view's own height, once Lynx has laid it out. */
+  #viewport = 0;
+
+  protected readonly listeners = [
+    this.#renderer.listen(
+      this.#element,
+      'bindscroll',
+      (event: { detail: ScrollDetail }) => this.#scrolled(event.detail),
+    ),
+    this.#renderer.listen(
+      this.#element,
+      'bindlayoutchange',
+      (event: { detail: LayoutDetail }) => {
+        this.#viewport = event.detail.height;
+      },
+    ),
+  ];
+
+  protected readonly cleanup = inject(DestroyRef).onDestroy(() => {
+    for (const remove of this.listeners) remove();
+    this.#state.minimized.set(false);
+  });
+
+  #scrolled({ scrollTop, scrollHeight }: ScrollDetail): void {
+    const delta = scrollTop - this.#lastTop;
+    this.#lastTop = scrollTop;
+
+    // At the top, including iOS's bounce above it, the dock is whole.
+    if (scrollTop <= TOP) {
+      this.#travel = 0;
+      this.#state.minimized.set(false);
+      return;
+    }
+    // iOS bounces past the end and back, which reads as scrolling up. The
+    // user didn't, so the dock stays as it is.
+    if (this.#viewport > 0 && scrollTop > scrollHeight - this.#viewport) {
+      return;
+    }
+
+    // Count the distance moved one way, starting again when content turns.
+    this.#travel = delta * this.#travel >= 0 ? this.#travel + delta : delta;
+    if (this.#travel >= MINIMIZE_AFTER) {
+      this.#state.minimized.set(true);
+    } else if (this.#travel <= -EXPAND_AFTER) {
+      this.#state.minimized.set(false);
+    }
+  }
+}