@blotch/dolan 22.2.3 → 22.2.4

package/dist/ui/theme/dark.css

@@ -1,8 +1,9 @@
 /*
  * @blotch/ui dark theme
  *
- * Complete rgba() color values referenced directly via var(--x) — see
- * default.css for why complete rgba values are used instead of HSL on Lynx.
+ * Complete rgba() color values referenced directly via var(--x), each with
+ * its `-rgb` channels for opacity modifiers — see default.css for why both,
+ * and why not HSL, on Lynx.
  *
  * Apply via a `.dark` class on the page element, or import as an
  * alternative to default.css.
@@ -10,40 +11,75 @@
 
 page.dark {
   --background: rgba(9, 9, 11, 1);
+  --background-rgb: 9, 9, 11;
   --foreground: rgba(250, 250, 250, 1);
+  --foreground-rgb: 250, 250, 250;
 
   --card: rgba(9, 9, 11, 1);
+  --card-rgb: 9, 9, 11;
   --card-foreground: rgba(250, 250, 250, 1);
+  --card-foreground-rgb: 250, 250, 250;
 
   --primary: rgba(250, 250, 250, 1);
+  --primary-rgb: 250, 250, 250;
   --primary-foreground: rgba(24, 24, 27, 1);
+  --primary-foreground-rgb: 24, 24, 27;
 
   --secondary: rgba(39, 39, 42, 1);
+  --secondary-rgb: 39, 39, 42;
   --secondary-foreground: rgba(250, 250, 250, 1);
+  --secondary-foreground-rgb: 250, 250, 250;
 
   --muted: rgba(39, 39, 42, 1);
+  --muted-rgb: 39, 39, 42;
   --muted-foreground: rgba(161, 161, 170, 1);
+  --muted-foreground-rgb: 161, 161, 170;
 
   --accent: rgba(39, 39, 42, 1);
+  --accent-rgb: 39, 39, 42;
   --accent-foreground: rgba(250, 250, 250, 1);
+  --accent-foreground-rgb: 250, 250, 250;
 
   --destructive: rgba(127, 29, 29, 1);
+  --destructive-rgb: 127, 29, 29;
   --destructive-foreground: rgba(250, 250, 250, 1);
+  --destructive-foreground-rgb: 250, 250, 250;
   --destructive-subtle: rgba(127, 29, 29, 0.1);
 
   --border: rgba(39, 39, 42, 1);
+  --border-rgb: 39, 39, 42;
   --input: rgba(39, 39, 42, 1);
+  --input-rgb: 39, 39, 42;
   --ring: rgba(212, 212, 216, 1);
+  --ring-rgb: 212, 212, 216;
   /* Translucent variant of --ring for a softer focus outline (see default.css). */
   --ring-subtle: rgba(212, 212, 216, 0.4);
 
   /* Series palette for charts (bg-chart-1, and chart-theme.ts in the chart
      component, which mirrors these values for SVG). */
   --chart-1: rgba(38, 98, 217, 1);
+  --chart-1-rgb: 38, 98, 217;
   --chart-2: rgba(46, 184, 138, 1);
+  --chart-2-rgb: 46, 184, 138;
   --chart-3: rgba(232, 140, 48, 1);
+  --chart-3-rgb: 232, 140, 48;
   --chart-4: rgba(175, 87, 219, 1);
+  --chart-4-rgb: 175, 87, 219;
   --chart-5: rgba(226, 54, 112, 1);
+  --chart-5-rgb: 226, 54, 112;
+
+  /* Liquid Glass (the glass component): see default.css. */
+  --glass-tint: rgba(250, 250, 250, 1);
+  --glass-tint-rgb: 250, 250, 250;
+  --glass-tint-foreground: rgba(24, 24, 27, 1);
+  --glass-tint-foreground-rgb: 24, 24, 27;
+  --glass-foreground: rgba(250, 250, 250, 1);
+  --glass-foreground-rgb: 250, 250, 250;
+  --glass-muted-foreground: rgba(212, 212, 216, 1);
+  --glass-muted-foreground-rgb: 212, 212, 216;
+  --glass-clear-foreground: rgba(255, 255, 255, 1);
+  --glass-clear-foreground-rgb: 255, 255, 255;
+  --glass-dim: rgba(0, 0, 0, 0.35);
 
   --radius: 8px;
 }

package/dist/ui/theme/default.css

@@ -13,52 +13,100 @@
  * rgba() values and referencing them directly sidesteps color-function parsing
  * entirely and renders correctly on Lynx.
  *
- * Tradeoff: Tailwind opacity modifiers on semantic colors (e.g. bg-primary/50)
- * do NOT work, because the color is an opaque value with no separable channels.
- * Where a translucent semantic color is genuinely needed, add a dedicated
- * rgba() variable (see --destructive-subtle) or use a solid token.
+ * Each opaque color also has its channels in a `-rgb` twin
+ * (`--primary-rgb: 24, 24, 27`) for Tailwind's opacity modifiers:
+ * `bg-primary/50` becomes `rgba(var(--primary-rgb), 0.5)`. Lynx substitutes
+ * var() as text before it parses the color, so the comma-separated list fills
+ * three arguments. Keep each pair the same color when you edit one: plain
+ * classes read `--x` and modifiers read `--x-rgb`.
  *
  * Apply to `page` (Lynx root element) or import globally.
  */
 
 page {
   --background: rgba(255, 255, 255, 1);
+  --background-rgb: 255, 255, 255;
   --foreground: rgba(9, 9, 11, 1);
+  --foreground-rgb: 9, 9, 11;
 
   --card: rgba(255, 255, 255, 1);
+  --card-rgb: 255, 255, 255;
   --card-foreground: rgba(9, 9, 11, 1);
+  --card-foreground-rgb: 9, 9, 11;
 
   --primary: rgba(24, 24, 27, 1);
+  --primary-rgb: 24, 24, 27;
   --primary-foreground: rgba(250, 250, 250, 1);
+  --primary-foreground-rgb: 250, 250, 250;
 
   --secondary: rgba(244, 244, 245, 1);
+  --secondary-rgb: 244, 244, 245;
   --secondary-foreground: rgba(24, 24, 27, 1);
+  --secondary-foreground-rgb: 24, 24, 27;
 
   --muted: rgba(244, 244, 245, 1);
+  --muted-rgb: 244, 244, 245;
   --muted-foreground: rgba(113, 113, 122, 1);
+  --muted-foreground-rgb: 113, 113, 122;
 
   --accent: rgba(244, 244, 245, 1);
+  --accent-rgb: 244, 244, 245;
   --accent-foreground: rgba(24, 24, 27, 1);
+  --accent-foreground-rgb: 24, 24, 27;
 
   --destructive: rgba(239, 68, 68, 1);
+  --destructive-rgb: 239, 68, 68;
   --destructive-foreground: rgba(250, 250, 250, 1);
+  --destructive-foreground-rgb: 250, 250, 250;
   --destructive-subtle: rgba(239, 68, 68, 0.1);
 
   --border: rgba(228, 228, 231, 1);
+  --border-rgb: 228, 228, 231;
   --input: rgba(228, 228, 231, 1);
+  --input-rgb: 228, 228, 231;
   --ring: rgba(24, 24, 27, 1);
-  /* Translucent variant of --ring for a softer focus outline. A separate
-     pre-composed value is needed because Tailwind opacity modifiers can't
-     apply to the opaque --ring, and Lynx can't inject alpha into it either. */
+  --ring-rgb: 24, 24, 27;
+  /* Translucent variant of --ring for the soft outer focus ring. Input and
+     textarea set it in an inline box-shadow, where no Tailwind modifier
+     reaches, so it stays a complete color. */
   --ring-subtle: rgba(24, 24, 27, 0.4);
 
   /* Series palette for charts (bg-chart-1, and chart-theme.ts in the chart
      component, which mirrors these values for SVG). */
   --chart-1: rgba(231, 110, 80, 1);
+  --chart-1-rgb: 231, 110, 80;
   --chart-2: rgba(42, 157, 144, 1);
+  --chart-2-rgb: 42, 157, 144;
   --chart-3: rgba(39, 71, 84, 1);
+  --chart-3-rgb: 39, 71, 84;
   --chart-4: rgba(232, 196, 104, 1);
+  --chart-4-rgb: 232, 196, 104;
   --chart-5: rgba(244, 164, 98, 1);
+  --chart-5-rgb: 244, 164, 98;
+
+  /* Liquid Glass (the glass component). Glass draws its own material, so
+     these color what sits on it, and tint it:
+     - glass-tint: the color tinted glass takes, such as a prominent glass
+       button's, and glass-tint-foreground what sits on it.
+     - glass-foreground and glass-muted-foreground: text and icons on regular
+       glass. Darker than muted-foreground, since what shows through the
+       glass varies.
+     - glass-clear-foreground: on clear glass, which sits over photos and
+       video, so it's white in both themes.
+     - glass-dim: the dimming layer under clear glass over bright content,
+       black at about a third, as Apple suggests. Already translucent, so it
+       has no channels. */
+  --glass-tint: rgba(24, 24, 27, 1);
+  --glass-tint-rgb: 24, 24, 27;
+  --glass-tint-foreground: rgba(250, 250, 250, 1);
+  --glass-tint-foreground-rgb: 250, 250, 250;
+  --glass-foreground: rgba(9, 9, 11, 1);
+  --glass-foreground-rgb: 9, 9, 11;
+  --glass-muted-foreground: rgba(63, 63, 70, 1);
+  --glass-muted-foreground-rgb: 63, 63, 70;
+  --glass-clear-foreground: rgba(255, 255, 255, 1);
+  --glass-clear-foreground-rgb: 255, 255, 255;
+  --glass-dim: rgba(0, 0, 0, 0.35);
 
   --radius: 8px;
 }

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

@@ -1,3 +1,6 @@
+/// <reference types="node" />
+// Not copied into apps (it checks the theme against a component), so it can
+// read the theme files with Node.
 import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 import {
@@ -11,7 +14,9 @@ import {
  * theme's colors. This keeps the copy in step with default.css and dark.css.
  */
 const tokens = (file: string): Record<string, string> => {
-  const css = readFileSync(new URL(file, import.meta.url), 'utf8');
+  // Relative to the package, where `ng test` runs: the test runs from a build
+  // of it elsewhere, so `import.meta.url` doesn't point next to the CSS.
+  const css = readFileSync(`src/lib/theme/${file}`, 'utf8');
   const values: Record<string, string> = {};
   for (const match of css.matchAll(/--([\w-]+):\s*(rgba\([^)]*\))/g)) {
     values[match[1]!] = match[2]!;
@@ -21,10 +26,10 @@ const tokens = (file: string): Record<string, string> => {
 
 describe('icon color tables', () => {
   it('match default.css', () => {
-    expect(ICON_LIGHT_COLORS).toEqual(tokens('./default.css'));
+    expect(ICON_LIGHT_COLORS).toEqual(tokens('default.css'));
   });
 
   it('match dark.css', () => {
-    expect(ICON_DARK_COLORS).toEqual(tokens('./dark.css'));
+    expect(ICON_DARK_COLORS).toEqual(tokens('dark.css'));
   });
 });

package/dist/ui/theme/rgb-channels.test.ts

@@ -0,0 +1,84 @@
+/// <reference types="node" />
+// Not copied into apps (it reads the theme's CSS with Node), like the other
+// theme checks next to it.
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+import { blotchPlugin } from './tailwind-plugin';
+
+/**
+ * Each opaque theme color is written twice: complete (`--primary:
+ * rgba(24, 24, 27, 1)`) for plain classes, and as channels (`--primary-rgb:
+ * 24, 24, 27`) for opacity modifiers. Nothing at runtime ties the two
+ * together, so a typo would make `bg-primary/50` a different color from
+ * `bg-primary`. These tests keep the pairs in step.
+ */
+const variables = (file: string): Map<string, string> => {
+  // Comments mention variables too, so they go first.
+  // Relative to the package, where `ng test` runs: the test runs from a build
+  // of it elsewhere, so `import.meta.url` doesn't point next to the CSS.
+  const css = readFileSync(`src/lib/theme/${file}`, 'utf8').replace(
+    /\/\*[\s\S]*?\*\//g,
+    '',
+  );
+  return new Map(
+    [...css.matchAll(/(--[\w-]+):\s*([^;{}]+);/g)].map((match) => [
+      match[1]!,
+      match[2]!.trim(),
+    ]),
+  );
+};
+
+/**
+ * The `--x-rgb` variables the plugin's opacity modifiers read.
+ */
+const channelVariables = (): string[] => {
+  const factory = blotchPlugin as unknown as {
+    config: { theme: { extend: { colors: Record<string, unknown> } } };
+  };
+  const names: string[] = [];
+  const walk = (value: unknown) => {
+    if (typeof value === 'function') {
+      const css = (value as (options: object) => string)({
+        opacityValue: '0.5',
+      });
+      names.push(
+        ...[...css.matchAll(/var\((--[\w-]+-rgb)\)/g)].map((m) => m[1]!),
+      );
+    } else if (typeof value === 'object' && value !== null) {
+      Object.values(value).forEach(walk);
+    }
+  };
+  walk(factory.config.theme.extend.colors);
+  return names;
+};
+
+describe.each(['./default.css', './dark.css'])('%s', (file) => {
+  const vars = variables(file);
+
+  it('has the channels of every color the plugin takes a modifier on', () => {
+    const names = channelVariables();
+    expect(names.length).toBeGreaterThan(0);
+    for (const name of names) {
+      expect(vars.get(name), name).toMatch(/^\d+, \d+, \d+$/);
+    }
+  });
+
+  it("gives each color's channels the same values as the color", () => {
+    for (const [name, value] of vars) {
+      if (!name.endsWith('-rgb')) continue;
+      const color = vars.get(name.slice(0, -'-rgb'.length));
+      expect(color, `${name} has no color`).toBe(`rgba(${value}, 1)`);
+    }
+  });
+
+  it('has channels for every opaque color', () => {
+    // A new token added without its channels would draw nothing with a
+    // modifier.
+    for (const [name, value] of vars) {
+      const channels = /^rgba\((\d+, \d+, \d+), 1\)$/.exec(value);
+      if (!channels) continue;
+      expect(vars.get(`${name}-rgb`), `${name}-rgb`).toBe(channels[1]);
+    }
+  });
+});

package/dist/ui/theme/tailwind-build.test.ts

@@ -0,0 +1,114 @@
+/// <reference types="node" />
+// Not copied into apps, unlike tailwind-plugin.test.ts, which covers the
+// plugin there: this runs Tailwind's own build, through Node and postcss, which
+// an app's `ng test` can't count on. It checks the classes the plugin's colors
+// make, with the Lynx preset, as an app's build does.
+import { createRequire } from 'node:module';
+import preset from '@lynx-js/tailwind-preset';
+import tailwindcss from 'tailwindcss';
+import { describe, expect, it } from 'vitest';
+
+import { blotchPlugin } from './tailwind-plugin';
+
+/**
+ * The part of postcss these tests use.
+ */
+type PostCss = (plugins: unknown[]) => {
+  process: (
+    css: string,
+    options: { from: undefined },
+  ) => Promise<{ css: string }>;
+};
+
+// postcss runs Tailwind. It's Tailwind's own dependency, so it's loaded from
+// there rather than added to this package.
+const postcss = createRequire(
+  createRequire(import.meta.url).resolve('tailwindcss'),
+)('postcss') as PostCss;
+
+/**
+ * Compiles `classes` with Tailwind, the Lynx preset and the plugin, as an
+ * app's build does, and returns the CSS.
+ */
+const compile = async (classes: string): Promise<string> => {
+  const result = await postcss([
+    tailwindcss({
+      content: [{ raw: classes, extension: 'html' }],
+      presets: [preset],
+      plugins: [blotchPlugin],
+    }),
+  ]).process('@tailwind utilities;', { from: undefined });
+  return result.css;
+};
+
+describe('blotchPlugin colors in a Tailwind build', () => {
+  it('keeps plain color classes on the complete color', async () => {
+    const css = await compile('bg-primary text-foreground border-border');
+
+    expect(css).toContain('background-color: var(--primary)');
+    expect(css).toContain('color: var(--foreground)');
+    expect(css).toContain('border-color: var(--border)');
+    // No class reads the channels, so a theme without them still draws.
+    expect(css).not.toContain('-rgb');
+  });
+
+  it('turns opacity modifiers into rgba() over the channels', async () => {
+    const css = await compile(
+      'bg-primary/50 text-foreground/70 border-border/60 bg-destructive/10 bg-chart-1/[.35]',
+    );
+
+    expect(css).toContain('background-color: rgba(var(--primary-rgb), 0.5)');
+    expect(css).toContain('color: rgba(var(--foreground-rgb), 0.7)');
+    expect(css).toContain('border-color: rgba(var(--border-rgb), 0.6)');
+    expect(css).toContain(
+      'background-color: rgba(var(--destructive-rgb), 0.1)',
+    );
+    expect(css).toContain('background-color: rgba(var(--chart-1-rgb), .35)');
+  });
+
+  it('gives every mapped color a modifier, except the translucent destructive-subtle and glass-dim', async () => {
+    const names = [
+      'background',
+      'foreground',
+      'card',
+      'card-foreground',
+      'primary',
+      'primary-foreground',
+      'secondary',
+      'secondary-foreground',
+      'muted',
+      'muted-foreground',
+      'accent',
+      'accent-foreground',
+      'destructive',
+      'destructive-foreground',
+      'border',
+      'input',
+      'ring',
+      'chart-1',
+      'chart-2',
+      'chart-3',
+      'chart-4',
+      'chart-5',
+      'glass-tint',
+      'glass-tint-foreground',
+      'glass-foreground',
+      'glass-muted-foreground',
+      'glass-clear-foreground',
+    ];
+    const css = await compile(
+      [
+        ...names.map((name) => `bg-${name}/50`),
+        'bg-destructive-subtle/50',
+        'bg-glass-dim/50',
+      ].join(' '),
+    );
+
+    for (const name of names) {
+      expect(css).toContain(`rgba(var(--${name}-rgb), 0.5)`);
+    }
+    // Tailwind can't add alpha to a complete color, so it makes no class.
+    expect(css).not.toContain('destructive-subtle');
+    expect(css).not.toContain('glass-dim');
+  });
+});

package/dist/ui/theme/tailwind-css.test.ts

@@ -0,0 +1,83 @@
+/// <reference types="node" />
+// Not copied into apps (it reads the theme's CSS with Node), like the other
+// theme checks next to it.
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+import { blotchPlugin } from './tailwind-plugin';
+
+/**
+ * tailwind.css is tailwind-plugin.ts for Tailwind 4. Nothing ties the two
+ * together, so these tests keep them mapping the same colors and radii, and
+ * keep every color it maps backed by the theme files.
+ */
+const read = (file: string): string =>
+  // Relative to the package, where `ng test` runs: the test runs from a build
+  // of it elsewhere, so `import.meta.url` doesn't point next to the CSS.
+  readFileSync(`src/lib/theme/${file}`, 'utf8');
+
+const tailwindCss = (): string =>
+  read('./tailwind.css').replace(/\/\*[\s\S]*?\*\//g, '');
+
+/**
+ * `--color-x` → the theme variable it reads, from the `@theme` block.
+ */
+const mappedColors = (): Map<string, string> =>
+  new Map(
+    [...tailwindCss().matchAll(/--color-([\w-]+):\s*var\((--[\w-]+)\);/g)].map(
+      (match) => [match[1]!, match[2]!],
+    ),
+  );
+
+/**
+ * The plugin's color classes, flattened as Tailwind names them.
+ */
+const pluginColors = (): Map<string, string> => {
+  const factory = blotchPlugin as unknown as {
+    config: { theme: { extend: { colors: Record<string, unknown> } } };
+  };
+  const colors = new Map<string, string>();
+  const walk = (value: unknown, path: string[]) => {
+    if (typeof value === 'object' && value !== null) {
+      for (const [key, child] of Object.entries(value)) {
+        walk(child, key === 'DEFAULT' ? path : [...path, key]);
+      }
+      return;
+    }
+    const css =
+      typeof value === 'function'
+        ? (value as (options: object) => string)({})
+        : String(value);
+    colors.set(path.join('-'), /var\((--[\w-]+)\)/.exec(css)![1]!);
+  };
+  walk(factory.config.theme.extend.colors, []);
+  return colors;
+};
+
+describe('tailwind.css', () => {
+  it('maps the same colors to the same variables as the plugin', () => {
+    expect(mappedColors()).toEqual(pluginColors());
+  });
+
+  it('maps the radii as the plugin does', () => {
+    const css = tailwindCss();
+    expect(css).toContain('--radius-lg: var(--radius);');
+    expect(css).toContain('--radius-md: calc(var(--radius) - 2px);');
+    expect(css).toContain('--radius-sm: calc(var(--radius) - 4px);');
+  });
+
+  it.each(['./default.css', './dark.css'])(
+    'reads only variables %s sets, each opaque one with its channels',
+    (file) => {
+      const css = read(file);
+      for (const variable of mappedColors().values()) {
+        const value = new RegExp(`${variable}:\\s*([^;]+);`).exec(css)?.[1];
+        expect(value, variable).toBeDefined();
+        if (value!.endsWith(', 1)')) {
+          // The build writes bg-primary/50 as rgba(var(--primary-rgb), 0.5).
+          expect(css, `${variable}-rgb`).toContain(`${variable}-rgb:`);
+        }
+      }
+    },
+  );
+});

package/dist/ui/theme/tailwind-plugin.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it, vi } from 'vitest';
 
-import { addSafeAreaUtilities, blotchPlugin } from './tailwind-plugin';
+import {
+  addSafeAreaUtilities,
+  blotchPlugin,
+  themeColor,
+} from './tailwind-plugin';
 
 /**
  * These tests exercise the utility generator in isolation with mock Tailwind
@@ -119,6 +123,42 @@ describe('blotchPlugin', () => {
     };
     const colors = factory.config?.theme?.extend?.colors;
     expect(colors).toBeDefined();
-    expect(colors!['background']).toBe('var(--background)');
+    const background = colors!['background'] as (options?: object) => string;
+    expect(background()).toBe('var(--background)');
+  });
+});
+
+describe('themeColor', () => {
+  const primary = themeColor('primary');
+
+  it('reads the complete color when no alpha is asked for', () => {
+    // caret-primary, shadow-primary: Tailwind passes no options.
+    expect(primary()).toBe('var(--primary)');
+    expect(primary({})).toBe('var(--primary)');
+  });
+
+  it("reads the complete color for a plain class with Tailwind's opacity variable", () => {
+    // bg-primary: the opacity variable is always 1 unless a deprecated
+    // bg-opacity-* utility changes it, and that never worked on these colors.
+    expect(
+      primary({
+        opacityVariable: '--tw-bg-opacity',
+        opacityValue: 'var(--tw-bg-opacity, 1)',
+      }),
+    ).toBe('var(--primary)');
+  });
+
+  it('reads the complete color for an alpha of 1', () => {
+    // bg-primary/100 passes '1'; theme('colors.primary') passes the number 1.
+    expect(primary({ opacityValue: '1' })).toBe('var(--primary)');
+    expect(primary({ opacityValue: 1 })).toBe('var(--primary)');
+  });
+
+  it('reads the channels for an opacity modifier', () => {
+    expect(primary({ opacityValue: '0.5' })).toBe(
+      'rgba(var(--primary-rgb), 0.5)',
+    );
+    // A gradient's transparent end stop asks for 0.
+    expect(primary({ opacityValue: 0 })).toBe('rgba(var(--primary-rgb), 0)');
   });
 });