@blotch/dolan 22.2.2 → 22.2.4

package/dist/ui/components/glass/glass.ts

@@ -0,0 +1,360 @@
+import {
+  booleanAttribute,
+  Component,
+  computed,
+  effect,
+  ElementRef,
+  inject,
+  input,
+  numberAttribute,
+  ViewEncapsulation,
+} from '@angular/core';
+import { LYNX_ELEMENTS, LynxAccessibilitySettings } from '@blotch/angular-lynx';
+
+import { cn } from '../../utils/cn';
+import {
+  injectColorScheme,
+  resolveIconColor,
+  UI_ICON_COLOR,
+  UI_ICON_THEME,
+} from '../icon/icon-theme';
+import { injectGlassDesign, injectSystemDrawsGlass } from './glass-design';
+
+/**
+ * `'regular'` glass, the default, frosts what's behind it and suits most
+ * controls. `'clear'` glass barely frosts it, for controls over photos and
+ * video; put a dimming layer under it when what's behind is bright (see
+ * `bg-glass-dim`). Don't mix the two on one screen.
+ */
+export type GlassVariant = 'regular' | 'clear';
+
+/**
+ * A capsule (fully rounded ends, the default for controls), a circle (give
+ * it equal width and height) or a rectangle with `radius` corners.
+ */
+export type GlassShape = 'capsule' | 'circle' | 'rounded';
+
+/**
+ * What a glass element draws:
+ *
+ * - `'glass'`: Liquid Glass.
+ * - `'frosted'`: a blur material, on iOS 15 to 25.
+ * - `'solid'`: an opaque surface. That's Material on Android, unless the app
+ *   opted into glass there, and glass under Reduce Transparency on Android
+ *   and the web, which can't adapt the glass they draw. iOS adapts its own.
+ */
+export type GlassSurface = 'glass' | 'frosted' | 'solid';
+
+/**
+ * How much the glass blurs where the blur is drawn by the runtime: Android's
+ * approximation, and the web before WebGL takes over. iOS's glass ignores it.
+ * Clear glass barely blurs.
+ */
+const GLASS_BLUR: Readonly<Record<GlassVariant, string>> = {
+  regular: '16px',
+  clear: '6px',
+};
+
+/** The blur of the frosted materials before iOS 26. */
+const FROSTED_BLUR = '20px';
+
+/**
+ * A solid surface floats over the content as glass does, so it gets
+ * Material's elevation shadow (level 2). An inline style, because Tailwind's
+ * shadow classes draw nothing on Lynx.
+ */
+const SOLID_ELEVATION =
+  '0 1px 2px rgba(0, 0, 0, 0.3), 0 2px 6px rgba(0, 0, 0, 0.15)';
+
+/** AngularLynx's wrapper of the native `blur-view` the component sits on. */
+type BlurViewElement = { setAttribute(name: string, value: unknown): void };
+
+/**
+ * The color an icon projected into the glass draws with when it's given
+ * none: the glass's foreground (see UI_ICON_COLOR), the way text there reads
+ * `text-glass-foreground`. A named function, not an inline factory: the
+ * component's metadata keeps its own copy of an inline one, which nothing
+ * calls, so an app's coverage report would show it as uncovered.
+ */
+const glassIconColor = () => {
+  const glass = inject(UiGlass);
+  return computed(() => glass.foreground());
+};
+
+/**
+ * Liquid Glass, for the controls and bars that float above an app's content:
+ * a `<blur-view>` that draws the right material on each platform.
+ *
+ * ```html
+ * <blur-view ui-glass class="flex-row items-center gap-2 px-4 py-2">
+ *   <text class="text-glass-foreground">Now playing</text>
+ * </blur-view>
+ * ```
+ *
+ * It sits on the `<blur-view>` itself rather than wrapping one, so the
+ * element you lay out and style is the glass, and what you put in it is
+ * inside the glass. That matters on iOS: interactive glass reacts only to
+ * touches on itself and what's in it, not on views stacked over it.
+ *
+ * What it draws follows the platform (see GlassDesign): UIKit's Liquid Glass
+ * on iOS 26 and later, a frosted blur material on iOS 15 to 25, an opaque
+ * Material surface on Android unless the app opts into glass with
+ * `provideGlass({ android: 'glass' })`, and the runtime's WebGL glass in the
+ * web preview. It also follows the user's accessibility settings where the
+ * platform doesn't: see {@link surface}.
+ *
+ * Text and icons inside read `text-glass-foreground` (and
+ * `text-glass-muted-foreground`), which the glass points at the right color
+ * for its variant and the user's contrast setting. Glass belongs to the
+ * layer above content, and shouldn't be layered on glass.
+ */
+@Component({
+  selector: 'blur-view[ui-glass]',
+  imports: [LYNX_ELEMENTS],
+  encapsulation: ViewEncapsulation.None,
+  // Icons projected into the glass inject this through its element injector,
+  // which content projection keeps them under.
+  providers: [{ provide: UI_ICON_COLOR, useFactory: glassIconColor }],
+  host: {
+    '[class]': 'surfaceClass()',
+    '[style.border-radius.px]': 'cornerRadius()',
+    '[style.background-color]': 'solidTint()',
+    '[style.box-shadow]': 'elevation()',
+  },
+  // iOS draws no background on a blur view, so a frosted material takes its
+  // tint from a fill under the content, the shape of the glass: the filled
+  // button of the design before Liquid Glass.
+  template: `
+    @if (frostedTint(); as color) {
+      <view
+        [class]="fillClass()"
+        [style.background-color]="color"
+        [style.border-radius.px]="cornerRadius()"
+      ></view>
+    }
+    <ng-content />
+  `,
+})
+export class UiGlass {
+  /** `'regular'` or `'clear'`; see GlassVariant. */
+  readonly variant = input<GlassVariant>('regular');
+  /** `'capsule'`, `'circle'` or `'rounded'`; see GlassShape. */
+  readonly shape = input<GlassShape>('capsule');
+  /**
+   * The corner radius of a `'rounded'` shape, in px. For a shape nested in
+   * it, see `concentricRadius()`.
+   */
+  readonly radius = input(20, { transform: numberAttribute });
+  /**
+   * A color the glass takes on, such as `var(--glass-tint)` for the theme's
+   * tint or `#2563eb`: a theme token or any CSS color. Use it sparingly, for
+   * the screen's main action. It fills a solid surface or a frosted
+   * material, as Material, and iOS before Liquid Glass, fill a button.
+   */
+  readonly tint = input<string | undefined>(undefined);
+  /**
+   * The glass reacts to touch, swelling and brightening under the finger as
+   * a Liquid Glass control does: on iOS 26 and later, and in the web preview.
+   */
+  readonly interactive = input(false, { transform: booleanAttribute });
+
+  readonly #settings = inject(LynxAccessibilitySettings);
+  readonly #systemDrawsGlass = injectSystemDrawsGlass();
+  readonly #scheme = injectColorScheme();
+  readonly #theme = inject(UI_ICON_THEME);
+  readonly #host = inject<ElementRef<BlurViewElement>>(ElementRef);
+
+  /**
+   * The design on this platform, which components built on the glass follow
+   * for their own form (see GlassDesign).
+   */
+  readonly design = injectGlassDesign();
+
+  /**
+   * What the glass draws (see GlassSurface): the design's material, or an
+   * opaque surface. Where the runtime draws the glass (Android's opt-in and
+   * the web), Reduce Transparency turns it opaque, as UIKit turns its own.
+   */
+  readonly surface = computed<GlassSurface>(() => {
+    const design = this.design();
+    if (design === 'material') return 'solid';
+    if (!this.#systemDrawsGlass && this.#settings.reduceTransparency()) {
+      return 'solid';
+    }
+    return design;
+  });
+
+  /** Whether what's behind shows through clear glass. */
+  readonly #seeThrough = computed(
+    () => this.variant() === 'clear' && this.surface() !== 'solid',
+  );
+
+  /**
+   * The color of text and icons on this glass, as a `var()`: the clear
+   * foreground on see-through clear glass, which sits over photos and video,
+   * and the glass foreground otherwise. Projected `<ui-icon>`s get it, and an
+   * SVG of your own can resolve it the way icons do (see icon-theme.ts).
+   */
+  readonly foreground = computed(() =>
+    this.#seeThrough()
+      ? 'var(--glass-clear-foreground)'
+      : 'var(--glass-foreground)',
+  );
+
+  /**
+   * The tint as a color the native element can parse: an attribute can't
+   * read CSS variables, so a theme token is swapped for its value in the
+   * active scheme, as icons do.
+   */
+  readonly #tintColor = computed(() => {
+    const tint = this.tint();
+    return tint ? resolveIconColor(tint, this.#theme[this.#scheme()]) : null;
+  });
+
+  /**
+   * A tinted solid surface is filled with the tint, as Material's filled
+   * buttons are, and as iOS draws tinted glass under Reduce Transparency.
+   */
+  protected readonly solidTint = computed(() =>
+    this.surface() === 'solid' ? this.#tintColor() : null,
+  );
+
+  protected readonly frostedTint = computed(() =>
+    this.surface() === 'frosted' ? this.#tintColor() : null,
+  );
+
+  protected readonly fillClass = computed(() =>
+    cn(
+      'h-full w-full absolute left-0 top-0',
+      this.shape() !== 'rounded' && 'rounded-full',
+    ),
+  );
+
+  protected readonly elevation = computed(() =>
+    this.surface() === 'solid' ? SOLID_ELEVATION : null,
+  );
+
+  protected readonly cornerRadius = computed(() =>
+    this.shape() === 'rounded' ? this.radius() : null,
+  );
+
+  protected readonly surfaceClass = computed(() => {
+    const increaseContrast = this.#settings.increaseContrast();
+    return cn(
+      this.shape() !== 'rounded' && 'rounded-full',
+      // Material's tonal surface, and the opaque glass of Reduce
+      // Transparency, unless a tint fills it (see solidTint). iOS ignores a
+      // blur-view's background, but never draws a solid surface.
+      this.surface() === 'solid' && !this.tint() && 'bg-secondary',
+      // Increase Contrast gives the glass a visible edge, as UIKit gives its
+      // own glass one.
+      increaseContrast &&
+        !this.#systemDrawsGlass &&
+        'border border-glass-foreground',
+      // The glass points the foreground tokens its content reads at the
+      // right color (a variable redefined here reaches the projected text,
+      // since variables inherit and `color` doesn't): white on see-through
+      // clear glass, and full strength for muted text under Increase
+      // Contrast.
+      this.#seeThrough()
+        ? '[--glass-foreground:var(--glass-clear-foreground)] [--glass-muted-foreground:var(--glass-clear-foreground)]'
+        : increaseContrast &&
+            '[--glass-muted-foreground:var(--glass-foreground)]',
+    );
+  });
+
+  /**
+   * The blur-view's attributes for the surface. Glass is forced to the app's
+   * color scheme (`ios-user-interface-style`), which iOS would otherwise take
+   * from the device: an app in its light theme on a phone in dark mode would
+   * get dark glass under dark text. The frosted materials before iOS 26 don't
+   * adapt to dark mode, so the scheme picks one. A solid surface turns the
+   * blur off, and on Android stops the blur-view redrawing the page behind it
+   * on every frame (`enable-auto-blur`), which it does even with no radius.
+   */
+  readonly #attributes = computed(() => {
+    const surface = this.surface();
+    const variant = this.variant();
+    const dark = this.#scheme() === 'dark';
+    let effect = 'light';
+    let radius = '0px';
+    if (surface === 'glass') {
+      effect = 'glass';
+      radius = GLASS_BLUR[variant];
+    } else if (surface === 'frosted') {
+      // Apple's controls over media used the dark material in either theme.
+      effect = dark || variant === 'clear' ? 'dark' : 'extra-light';
+      radius = FROSTED_BLUR;
+    }
+    return {
+      'blur-effect': effect,
+      'blur-radius': radius,
+      'enable-auto-blur': surface !== 'solid',
+      'glass-style': variant,
+      'glass-tint-color': this.#tintColor(),
+      'glass-interactive': this.interactive() || null,
+      'ios-user-interface-style': dark ? 'dark' : 'light',
+    };
+  });
+
+  // Set on the element as they are, rather than through host attribute
+  // bindings, which turn every value into a string: Lynx reads
+  // `glass-interactive` and `enable-auto-blur` as booleans. `null` removes an
+  // attribute, which restores Lynx's default.
+  protected readonly material = effect(() => {
+    const element = this.#host.nativeElement;
+    for (const [name, value] of Object.entries(this.#attributes())) {
+      element.setAttribute(name, value);
+    }
+  });
+}
+
+/**
+ * Merges the glass elements inside it, as iOS 26 draws a group of glass
+ * controls: shapes closer than `spacing` flow into each other like droplets,
+ * and the group draws them in one pass. Put a `<blur-view ui-glass>` directly
+ * inside it for each shape: iOS merges the glass in the group's own content,
+ * and a wrapper that draws anything of its own comes between them.
+ *
+ * ```html
+ * <blur-view ui-glass-group [spacing]="16" class="flex-row gap-2">
+ *   <blur-view ui-glass shape="circle" class="h-12 w-12">…</blur-view>
+ *   <blur-view ui-glass shape="circle" class="h-12 w-12">…</blur-view>
+ * </blur-view>
+ * ```
+ *
+ * The group draws nothing itself. Shapes merge on iOS 26 and later and in
+ * the web preview. Android's glass doesn't merge, and the frosted and
+ * Material designs have no glass to merge.
+ *
+ * Moving or resizing a shape, with a CSS transition for example, morphs the
+ * merged glass with it. A shape that's added or removed appears or
+ * disappears at once: iOS's glass doesn't animate that in Lynx.
+ */
+@Component({
+  selector: 'blur-view[ui-glass-group]',
+  encapsulation: ViewEncapsulation.None,
+  template: `<ng-content />`,
+})
+export class UiGlassGroup {
+  /** How close two glass shapes come before they merge, in px. */
+  readonly spacing = input(0, { transform: numberAttribute });
+
+  readonly #design = injectGlassDesign();
+  readonly #host = inject<ElementRef<BlurViewElement>>(ElementRef);
+
+  // As UiGlass sets its own (see there). A container that isn't merging
+  // glass is a plain transparent view: `light` with no radius draws nothing,
+  // where `glass-container` would log an error before iOS 26. It never blurs,
+  // so on Android it never redraws the page behind it either.
+  protected readonly material = effect(() => {
+    const element = this.#host.nativeElement;
+    element.setAttribute(
+      'blur-effect',
+      this.#design() === 'glass' ? 'glass-container' : 'light',
+    );
+    element.setAttribute('blur-radius', '0px');
+    element.setAttribute('enable-auto-blur', false);
+    element.setAttribute('spacing', this.spacing());
+  });
+}

package/dist/ui/components/glass/index.ts

@@ -0,0 +1,18 @@
+export {
+  UiGlass,
+  UiGlassGroup,
+  type GlassShape,
+  type GlassSurface,
+  type GlassVariant,
+} from './glass';
+export {
+  FIRST_GLASS_IOS,
+  UI_GLASS_OPTIONS,
+  glassDesignFor,
+  injectGlassDesign,
+  injectSystemDrawsGlass,
+  provideGlass,
+  type GlassDesign,
+  type GlassOptions,
+} from './glass-design';
+export { concentricRadius } from './concentric-radius';

package/dist/ui/components/icon/icon-theme.test.ts

@@ -0,0 +1,169 @@
+import {
+  Injector,
+  type Provider,
+  runInInjectionContext,
+  signal,
+} from '@angular/core';
+import { LynxTheme } from '@blotch/angular-lynx';
+import { describe, expect, it } from 'vitest';
+import {
+  ICON_DARK_COLORS,
+  ICON_LIGHT_COLORS,
+  UI_ICON_COLOR,
+  UI_ICON_THEME,
+  injectColorScheme,
+  injectIconColor,
+  provideIconTheme,
+  resolveIconColor,
+} from './icon-theme';
+
+const LIGHT_FOREGROUND = ICON_LIGHT_COLORS['foreground'];
+const DARK_FOREGROUND = ICON_DARK_COLORS['foreground'];
+
+/**
+ * Runs injectIconColor() against a device appearance and extra providers. A
+ * plain Injector has no root scope, so it gets the default theme explicitly;
+ * the token's own factory is covered by the component tests.
+ */
+const setup = (providers: Provider[] = [], dark = signal(false)) => {
+  const injector = Injector.create({
+    providers: [
+      { provide: LynxTheme, useValue: { isDarkMode: dark } },
+      {
+        provide: UI_ICON_THEME,
+        useValue: { light: ICON_LIGHT_COLORS, dark: ICON_DARK_COLORS },
+      },
+      ...providers,
+    ],
+  });
+  return runInInjectionContext(injector, () => injectIconColor());
+};
+
+describe('resolveIconColor', () => {
+  it('passes a literal color through', () => {
+    expect(resolveIconColor('#2563eb', ICON_LIGHT_COLORS)).toBe('#2563eb');
+    expect(resolveIconColor(' rgba(1, 2, 3, 1) ', ICON_LIGHT_COLORS)).toBe(
+      'rgba(1, 2, 3, 1)',
+    );
+  });
+
+  it('swaps a theme token for its value', () => {
+    expect(resolveIconColor('var(--primary)', ICON_LIGHT_COLORS)).toBe(
+      ICON_LIGHT_COLORS['primary'],
+    );
+    expect(resolveIconColor('var( --destructive )', ICON_DARK_COLORS)).toBe(
+      ICON_DARK_COLORS['destructive'],
+    );
+  });
+
+  it("falls back to the var()'s fallback for an unknown token", () => {
+    expect(resolveIconColor('var(--brand, #ff0000)', ICON_LIGHT_COLORS)).toBe(
+      '#ff0000',
+    );
+    // The fallback may itself be a token.
+    expect(
+      resolveIconColor('var(--brand, var(--primary))', ICON_LIGHT_COLORS),
+    ).toBe(ICON_LIGHT_COLORS['primary']);
+  });
+
+  it('falls back to the foreground for an unknown token with no fallback', () => {
+    expect(resolveIconColor('var(--brand)', ICON_LIGHT_COLORS)).toBe(
+      LIGHT_FOREGROUND,
+    );
+  });
+
+  it('leaves an unknown token as it is when the table has no foreground', () => {
+    expect(resolveIconColor('var(--brand)', {})).toBe('var(--brand)');
+  });
+});
+
+describe('provideIconTheme', () => {
+  it('merges the overrides over the default tables', () => {
+    const provider = provideIconTheme({
+      light: { primary: '#123456' },
+      colorScheme: 'dark',
+    }) as { provide: unknown; useValue: Record<string, unknown> };
+    expect(provider.provide).toBe(UI_ICON_THEME);
+    expect(provider.useValue['light']).toEqual({
+      ...ICON_LIGHT_COLORS,
+      primary: '#123456',
+    });
+    expect(provider.useValue['dark']).toEqual(ICON_DARK_COLORS);
+    expect(provider.useValue['colorScheme']).toBe('dark');
+  });
+});
+
+describe('injectColorScheme', () => {
+  const scheme = (providers: Provider[], dark = signal(false)) =>
+    runInInjectionContext(
+      Injector.create({
+        providers: [
+          { provide: LynxTheme, useValue: { isDarkMode: dark } },
+          {
+            provide: UI_ICON_THEME,
+            useValue: { light: ICON_LIGHT_COLORS, dark: ICON_DARK_COLORS },
+          },
+          ...providers,
+        ],
+      }),
+      () => injectColorScheme(),
+    );
+
+  it("is light unless the theme says otherwise, whatever the device's appearance", () => {
+    expect(scheme([], signal(true))()).toBe('light');
+    expect(scheme([provideIconTheme({ colorScheme: 'dark' })])()).toBe('dark');
+  });
+
+  it("follows the device with 'system', or the app's own state", () => {
+    const dark = signal(false);
+    const system = scheme([provideIconTheme({ colorScheme: 'system' })], dark);
+    expect(system()).toBe('light');
+    dark.set(true);
+    expect(system()).toBe('dark');
+
+    const own = signal<'light' | 'dark'>('dark');
+    expect(scheme([provideIconTheme({ colorScheme: () => own() })])()).toBe(
+      'dark',
+    );
+  });
+});
+
+describe('injectIconColor', () => {
+  it('draws with the light foreground by default, even on a dark device', () => {
+    const resolve = setup([], signal(true));
+    expect(resolve(undefined)).toBe(LIGHT_FOREGROUND);
+  });
+
+  it('resolves an explicit color against the active table', () => {
+    const resolve = setup([provideIconTheme({ colorScheme: 'dark' })]);
+    expect(resolve('var(--primary)')).toBe(ICON_DARK_COLORS['primary']);
+    expect(resolve('#00ff00')).toBe('#00ff00');
+  });
+
+  it("follows the device appearance with 'system'", () => {
+    const dark = signal(false);
+    const resolve = setup([provideIconTheme({ colorScheme: 'system' })], dark);
+    expect(resolve(undefined)).toBe(LIGHT_FOREGROUND);
+    dark.set(true);
+    expect(resolve(undefined)).toBe(DARK_FOREGROUND);
+  });
+
+  it("reads the app's own theme state from a function", () => {
+    const scheme = signal<'light' | 'dark'>('dark');
+    const resolve = setup([provideIconTheme({ colorScheme: () => scheme() })]);
+    expect(resolve(undefined)).toBe(DARK_FOREGROUND);
+    scheme.set('light');
+    expect(resolve(undefined)).toBe(LIGHT_FOREGROUND);
+  });
+
+  it("uses the container's color when the icon sets none", () => {
+    const inherited = signal<string | undefined>('var(--destructive)');
+    const resolve = setup([{ provide: UI_ICON_COLOR, useValue: inherited }]);
+    expect(resolve(undefined)).toBe(ICON_LIGHT_COLORS['destructive']);
+    // The icon's own color still wins.
+    expect(resolve('var(--primary)')).toBe(ICON_LIGHT_COLORS['primary']);
+    // A container that sets no color leaves the foreground.
+    inherited.set(undefined);
+    expect(resolve(undefined)).toBe(LIGHT_FOREGROUND);
+  });
+});