@blotch/dolan 22.2.3 → 22.2.4

package/dist/ui/components/tab-bar/tab-bar.test.ts

@@ -0,0 +1,280 @@
+import { Component, signal, viewChildren } from '@angular/core';
+import { Router, RouterOutlet, type Routes } from '@angular/router';
+import {
+  fireEvent,
+  render,
+  waitForUpdate,
+} from '@blotch/angular-lynx-testing-library';
+import { LYNX_ELEMENTS, provideRouter } from '@blotch/angular-lynx';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireLynxEvent } from '../../../test-utils/fire-lynx-event';
+import { UiTabBar, UiTabBarItem } from './tab-bar';
+
+@Component({
+  selector: 'home-page',
+  imports: [LYNX_ELEMENTS],
+  template: `<text>Home page</text>`,
+})
+class HomePage {}
+
+@Component({
+  selector: 'inbox-page',
+  imports: [LYNX_ELEMENTS],
+  template: `<text>Inbox page</text>`,
+})
+class InboxPage {}
+
+@Component({
+  selector: 'profile-page',
+  imports: [LYNX_ELEMENTS],
+  template: `<text>Profile page</text>`,
+})
+class ProfilePage {}
+
+const routes: Routes = [
+  { path: '', component: HomePage },
+  { path: 'inbox', component: InboxPage },
+  { path: 'inbox/:id', component: InboxPage },
+  { path: 'profile', component: ProfilePage },
+];
+
+@Component({
+  imports: [LYNX_ELEMENTS, RouterOutlet, UiTabBar, UiTabBarItem],
+  template: `
+    <router-outlet />
+    <ui-tab-bar>
+      <ui-tab-bar-item
+        route="/"
+        icon="home"
+        label="Home"
+        [routerLinkActiveOptions]="{ exact: true }"
+      />
+      <ui-tab-bar-item
+        route="/inbox"
+        icon="inbox"
+        label="Inbox"
+        [badge]="inboxBadge()"
+        [class]="inboxClass()"
+      />
+      <ui-tab-bar-item
+        route="/profile"
+        icon="user"
+        label="Profile"
+        [queryParams]="{ tab: 'posts' }"
+      />
+    </ui-tab-bar>
+  `,
+})
+class TabBarHost {
+  readonly inboxBadge = signal<string | number | null | undefined>(undefined);
+  readonly inboxClass = signal('');
+  readonly items = viewChildren(UiTabBarItem);
+}
+
+/** The theme's light colors, as icon-theme.ts resolves them for an SVG. */
+const PRIMARY = 'rgba(24, 24, 27, 1)';
+const MUTED_FOREGROUND = 'rgba(113, 113, 122, 1)';
+
+/**
+ * Runs change detection until `done` holds: a navigation takes a few ticks,
+ * and RouterLinkActive reports the result in a microtask after it.
+ */
+const until = async (done: () => boolean): Promise<void> => {
+  for (let i = 0; i < 20 && !done(); i++) {
+    await waitForUpdate();
+  }
+  expect(done()).toBe(true);
+};
+
+const renderTabBar = async () => {
+  const result = await render(TabBarHost, {
+    providers: [provideRouter(routes)],
+  });
+  const { container } = result;
+  const host = result.componentRef.instance as TabBarHost;
+  const router = result.componentRef.injector.get(Router);
+  /**
+   * An item's host is the accessibility element, named by its label.
+   */
+  const tab = (label: string) =>
+    container.querySelector(`[accessibility-label^="${label}"]`)!;
+  const isActive = (label: string) =>
+    tab(label).getAttribute('accessibility-traits') === 'button,selected';
+  await until(() => isActive('Home'));
+  return {
+    ...result,
+    host,
+    router,
+    tab,
+    isActive,
+    item: (label: string) =>
+      host.items().find((item) => item.label() === label)!,
+    labelOf: (label: string) =>
+      Array.from(tab(label).querySelectorAll('text')).find(
+        (text) => text.textContent === label,
+      )!,
+    iconOf: (label: string) =>
+      tab(label).querySelector('svg')!.getAttribute('content') ?? '',
+    page: () =>
+      Array.from(container.querySelectorAll('text'))
+        .map((text) => text.textContent ?? '')
+        .find((text) => text.endsWith(' page')),
+  };
+};
+
+describe('UiTabBar', () => {
+  // Item and page selectors aren't Lynx elements, so the renderer falls back
+  // to a <view> for each and warns.
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  it('lays the bar out as a row above the bottom safe area', async () => {
+    const { container, componentRef } = await render(UiTabBar);
+    const bar = container.querySelector('[accessibility-traits="tabbar"]')!;
+    expect(bar.classList).toContain('flex-row');
+    expect(bar.classList).toContain('pb-safe');
+    expect(bar.classList).toContain('border-t');
+
+    componentRef.setInput('class', 'border-t-0');
+    await waitForUpdate();
+    expect(bar.classList).toContain('border-t-0');
+    expect(bar.classList).not.toContain('border-t');
+  });
+
+  it('draws an icon and a label in each tab', async () => {
+    const { tab, labelOf, iconOf } = await renderTabBar();
+    for (const label of ['Home', 'Inbox', 'Profile']) {
+      expect(labelOf(label)).toBeTruthy();
+      expect(iconOf(label)).toContain('<svg');
+      // Each tab is one button for a screen reader, and takes an equal share
+      // of the row.
+      expect(tab(label).getAttribute('accessibility-element')).toBe('true');
+      expect(tab(label).classList).toContain('flex-1');
+    }
+  });
+
+  it('marks the tab of the current route as selected, in the primary color', async () => {
+    const { isActive, labelOf, iconOf } = await renderTabBar();
+    expect(isActive('Home')).toBe(true);
+    expect(labelOf('Home').classList).toContain('text-primary');
+    expect(iconOf('Home')).toContain(PRIMARY);
+
+    expect(isActive('Inbox')).toBe(false);
+    expect(labelOf('Inbox').classList).toContain('text-muted-foreground');
+    expect(iconOf('Inbox')).toContain(MUTED_FOREGROUND);
+  });
+
+  it('reads to a screen reader as a tab bar, the current tab selected', async () => {
+    const { getByRole, queryByRole } = await renderTabBar();
+    expect(getByRole('tablist')).toBeTruthy();
+    expect(getByRole('button', { name: 'Home', selected: true })).toBeTruthy();
+    expect(queryByRole('button', { name: 'Inbox', selected: true })).toBeNull();
+  });
+
+  it('navigates on a tap, and moves the selection to the tapped tab', async () => {
+    const { tab, isActive, page, labelOf, item } = await renderTabBar();
+    const pressed = vi.fn();
+    item('Inbox').pressed.subscribe(pressed);
+    expect(page()).toBe('Home page');
+
+    fireEvent.tap(tab('Inbox'));
+
+    await until(() => page() === 'Inbox page');
+    expect(isActive('Inbox')).toBe(true);
+    expect(labelOf('Inbox').classList).toContain('text-primary');
+    // `exact` keeps "/" from matching every route.
+    expect(isActive('Home')).toBe(false);
+    expect(labelOf('Home').classList).toContain('text-muted-foreground');
+    expect(pressed).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps a tab selected on the routes under it', async () => {
+    const { router, isActive, page } = await renderTabBar();
+    await router.navigateByUrl('/inbox/7');
+    await until(() => page() === 'Inbox page');
+    expect(isActive('Inbox')).toBe(true);
+    expect(isActive('Home')).toBe(false);
+  });
+
+  it("navigates with the item's RouterLink options", async () => {
+    const { router, tab, isActive } = await renderTabBar();
+    fireEvent.tap(tab('Profile'));
+    await until(() => isActive('Profile'));
+    expect(router.url).toBe('/profile?tab=posts');
+  });
+
+  it('emits pressed for a tap on the selected tab too', async () => {
+    const { router, tab, item } = await renderTabBar();
+    const pressed = vi.fn();
+    item('Home').pressed.subscribe(pressed);
+    fireEvent.tap(tab('Home'));
+    await waitForUpdate();
+    expect(pressed).toHaveBeenCalledTimes(1);
+    expect(router.url).toBe('/');
+  });
+
+  it("shows a badge over the icon, and says it after the tab's name", async () => {
+    const { host, tab } = await renderTabBar();
+    const badge = () =>
+      Array.from(tab('Inbox').querySelectorAll('text')).find(
+        (text) => text.textContent !== 'Inbox',
+      );
+    expect(badge()).toBeUndefined();
+
+    host.inboxBadge.set(3);
+    await waitForUpdate();
+    expect(badge()?.textContent).toBe('3');
+    expect(badge()?.parentElement?.classList).toContain('bg-destructive');
+    expect(tab('Inbox').getAttribute('accessibility-label')).toBe('Inbox, 3');
+
+    host.inboxBadge.set('New');
+    await waitForUpdate();
+    expect(badge()?.textContent).toBe('New');
+
+    // A count of 0 and an empty value show nothing, so a count binds as is.
+    for (const empty of [0, '', null, undefined]) {
+      host.inboxBadge.set(empty);
+      await waitForUpdate();
+      expect(badge()).toBeUndefined();
+      expect(tab('Inbox').getAttribute('accessibility-label')).toBe('Inbox');
+    }
+  });
+
+  it('shrinks a tab while it is pressed', async () => {
+    const { tab } = await renderTabBar();
+    const inbox = tab('Inbox') as HTMLElement;
+    const scale = () => inbox.style.getPropertyValue('transform');
+
+    fireEvent.touchstart(inbox);
+    expect(scale()).toBe('scale(0.97)');
+    fireEvent.touchend(inbox);
+    expect(scale()).toBe('scale(1)');
+
+    fireEvent.touchstart(inbox);
+    // A scroll taking over cancels the touch.
+    fireEvent.touchcancel(inbox);
+    expect(scale()).toBe('scale(1)');
+
+    // The web preview, in a browser, sends mouse events instead.
+    fireEvent.mousedown(inbox);
+    expect(scale()).toBe('scale(0.97)');
+    fireEvent.mouseup(inbox);
+    expect(scale()).toBe('scale(1)');
+    fireEvent.mousedown(inbox);
+    fireLynxEvent(inbox, 'mouseleave');
+    expect(scale()).toBe('scale(1)');
+  });
+
+  it("merges an item's class into its content, the given class winning", async () => {
+    const { host, tab } = await renderTabBar();
+    const content = () => tab('Inbox').querySelector('view')!;
+    expect(content().classList).toContain('pt-2');
+
+    host.inboxClass.set('pt-3');
+    await waitForUpdate();
+    expect(content().classList).toContain('pt-3');
+    expect(content().classList).not.toContain('pt-2');
+  });
+});

package/dist/ui/components/tab-bar/tab-bar.ts

@@ -0,0 +1,230 @@
+import {
+  Component,
+  ElementRef,
+  ViewEncapsulation,
+  computed,
+  inject,
+  input,
+  output,
+} from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { LYNX_ELEMENTS, LynxRouterLinkActive } from '@blotch/angular-lynx';
+
+import {
+  type AnimationHandle,
+  pressDown,
+  pressRelease,
+} from '../../utils/animate';
+import { cn } from '../../utils/cn';
+import { injectIconColor } from '../icon/icon-theme';
+import { type IconName, ICONS } from '../icon/icons';
+
+/**
+ * The bar along the bottom of the screen that switches between an app's
+ * top-level screens. Put a `<ui-tab-bar-item>` in it for each screen, and
+ * place it under the `<router-outlet>`.
+ */
+@Component({
+  selector: 'ui-tab-bar',
+  imports: [LYNX_ELEMENTS],
+  encapsulation: ViewEncapsulation.None,
+  // `pb-safe` pads the bar by the bottom safe-area inset, so the items sit
+  // above the iPhone's home indicator while the bar's background still runs
+  // to the bottom edge, as a native tab bar's does. Lynx reports no insets on
+  // Android, nor does the web preview have any, so it's 0 there.
+  //
+  // `tabbar` is UIKit's tab bar trait (UIAccessibilityTraitTabBar), the one a
+  // native tab bar's container has: it tells VoiceOver that the buttons in it
+  // are tabs. Android reads a single trait and has no tab bar trait, so there
+  // the row stays a plain container.
+  template: `
+    <view accessibility-traits="tabbar" [class]="barClass()">
+      <ng-content />
+    </view>
+  `,
+})
+export class UiTabBar {
+  readonly userClass = input<string>('', { alias: 'class' });
+
+  protected readonly barClass = computed(() =>
+    cn(
+      'flex-row border-t border-border bg-background flex pb-safe',
+      this.userClass(),
+    ),
+  );
+}
+
+/**
+ * One tab: an icon over a label that navigates to its `route` on a tap.
+ *
+ * The host itself is the link. Angular's own `RouterLink` and
+ * `RouterLinkActive` sit on it as host directives, so every `RouterLink`
+ * option (`queryParams`, `replaceUrl`, `state`, …) and
+ * `routerLinkActiveOptions` work as they do on the web, and the item knows
+ * whether its route is active without the app wiring `routerLinkActive` up.
+ * Host directives don't match selectors, so `LynxRouterLinkActive`, which
+ * marks the active item `selected` for screen readers, is listed too.
+ */
+@Component({
+  selector: 'ui-tab-bar-item',
+  imports: [LYNX_ELEMENTS],
+  encapsulation: ViewEncapsulation.None,
+  hostDirectives: [
+    {
+      directive: RouterLink,
+      // `route`, not `routerLink`: an app that imports RouterLink would
+      // otherwise put a second RouterLink on the item (its selector matches
+      // `routerLink`), and Angular rejects two of one directive on an element.
+      inputs: [
+        'routerLink: route',
+        'queryParams',
+        'queryParamsHandling',
+        'fragment',
+        'preserveFragment',
+        'state',
+        'info',
+        'relativeTo',
+        'replaceUrl',
+        'skipLocationChange',
+      ],
+    },
+    { directive: RouterLinkActive, inputs: ['routerLinkActiveOptions'] },
+    LynxRouterLinkActive,
+  ],
+  host: {
+    // The host is the tap target and fills an equal share of the bar's row.
+    // `flex-1` has to be on the host, the row's real child: on an inner view
+    // it would share out the host's width instead (same lesson as
+    // ui-nav-drawer-content).
+    class: 'flex-1 flex-col flex',
+    // One accessibility element per tab, named by its label, so a screen
+    // reader reads "Inbox, 3, button" instead of an unlabeled SVG and a word.
+    // LynxRouterLinkActive adds `selected` to `button` while the route is
+    // active. The label is an attribute binding: a property binding on a
+    // component's host is checked against the DOM schema, which has no
+    // `accessibility-label`.
+    'accessibility-element': 'true',
+    'accessibility-traits': 'button',
+    '[attr.accessibility-label]': 'accessibilityLabel()',
+    // Press feedback binds touch and mouse events: native fires only touch,
+    // and the web preview, in a browser, fires only mouse. See pressDown().
+    '(bindtouchstart)': 'onPressStart()',
+    '(bindmousedown)': 'onPressStart()',
+    // A canceled touch (a scroll taking over) and a cursor leaving mid-press
+    // release too, or the tab would stay shrunk.
+    '(bindtouchend)': 'onPressEnd()',
+    '(bindtouchcancel)': 'onPressEnd()',
+    '(bindmouseup)': 'onPressEnd()',
+    '(bindmouseleave)': 'onPressEnd()',
+    // RouterLink navigates on the same tap through its own listener: Lynx
+    // keeps one handler per event, and the runtime runs both from it.
+    '(bindtap)': 'pressed.emit()',
+  },
+  template: `
+    <view [class]="contentClass()">
+      <view class="relative">
+        <svg [attr.content]="iconSvg()" style="width: 24px; height: 24px;" />
+        @if (badgeText()) {
+          <!-- Hangs off the icon's top-right corner, as on a native tab bar.
+               min-w-4 keeps a one-digit badge round; longer ones grow into
+               a pill. -->
+          <view
+            class="h-4 min-w-4 items-center rounded-full bg-destructive px-1 flex absolute -right-2.5 -top-1 justify-center"
+          >
+            <text
+              class="text-[10px] font-semibold leading-4 text-destructive-foreground"
+              >{{ badgeText() }}</text
+            >
+          </view>
+        }
+      </view>
+      <text [class]="labelClass()">{{ label() }}</text>
+    </view>
+  `,
+})
+export class UiTabBarItem {
+  readonly icon = input.required<IconName>();
+  readonly label = input.required<string>();
+  /**
+   * A count or short text over the icon's corner, such as unread messages.
+   * Nothing shows for `0`, an empty string, `null` or `undefined`, so a count
+   * can be bound as it is.
+   */
+  readonly badge = input<string | number | null | undefined>(undefined);
+  readonly userClass = input<string>('', { alias: 'class' });
+
+  /** Emits on every tap, including a tap on the tab that's already active. */
+  readonly pressed = output<void>();
+
+  /**
+   * Whether the item's route is active, from the RouterLinkActive on the host.
+   * RouterLinkActive reports only changes, and starts from not active.
+   */
+  protected readonly active = toSignal(
+    inject(RouterLinkActive).isActiveChange,
+    { initialValue: false },
+  );
+
+  // The host, not an inner view, shrinks on a press: it's the whole tap
+  // target, and injecting it needs no view query.
+  readonly #host = inject(ElementRef);
+  #pressAnim?: AnimationHandle;
+
+  protected readonly badgeText = computed(() => {
+    const text = String(this.badge() ?? '');
+    return text === '0' ? '' : text;
+  });
+
+  protected readonly accessibilityLabel = computed(() =>
+    this.badgeText() ? `${this.label()}, ${this.badgeText()}` : this.label(),
+  );
+
+  readonly #resolveColor = injectIconColor();
+
+  // The active tab takes the theme's primary color and the others its muted
+  // foreground, like the tint of a native tab bar. They're solid tokens, not
+  // an opacity modifier, which a theme copied before the `--x-rgb` channels
+  // can't draw.
+  //
+  // The icon is drawn here, as the spinner and pagination draw theirs, rather
+  // than by a nested <ui-icon>: each tab stays a single component, with no
+  // child whose inputs it has to keep in step. An SVG can't read the label's
+  // text class (Lynx doesn't pass `color` down, and the markup is parsed
+  // apart from the page's CSS), so the token is resolved to its value and
+  // written into the markup (see icon-theme.ts). split/join, not
+  // replaceAll(), which PrimJS's ES2019 runtime lacks (see UiIcon).
+  protected readonly iconSvg = computed(() =>
+    ICONS[this.icon()]
+      .split('currentColor')
+      .join(
+        this.#resolveColor(
+          this.active() ? 'var(--primary)' : 'var(--muted-foreground)',
+        ),
+      ),
+  );
+
+  protected readonly labelClass = computed(() =>
+    cn(
+      'text-xs font-medium',
+      this.active() ? 'text-primary' : 'text-muted-foreground',
+    ),
+  );
+
+  protected readonly contentClass = computed(() =>
+    cn(
+      'flex-1 flex-col items-center gap-1 px-1 pb-1.5 pt-2 flex justify-center',
+      this.userClass(),
+    ),
+  );
+
+  protected onPressStart(): void {
+    this.#pressAnim?.cancel();
+    this.#pressAnim = pressDown(this.#host.nativeElement);
+  }
+
+  protected onPressEnd(): void {
+    this.#pressAnim?.cancel();
+    this.#pressAnim = pressRelease(this.#host.nativeElement);
+  }
+}