@blotch/dolan 0.0.0-stage → 22.2.0

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

@@ -0,0 +1,124 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { addSafeAreaUtilities, blotchPlugin } from './tailwind-plugin';
+
+/**
+ * These tests exercise the utility generator in isolation with mock Tailwind
+ * plugin callbacks — no real Tailwind runtime is needed. We assert the exact
+ * CSS strings emitted so a regression in the `env()` / `calc()` wiring (which is
+ * what makes safe area work on Lynx) is caught immediately.
+ */
+const setup = () => {
+  const addUtilities = vi.fn();
+  const matchUtilities = vi.fn();
+  // Minimal spacing scale — enough to prove offset utilities read the theme.
+  const spacing = { '0': '0px', '2': '0.5rem', '4': '1rem' };
+  const theme = vi.fn((key: string) =>
+    key === 'spacing' ? spacing : undefined,
+  );
+
+  addSafeAreaUtilities({
+    addUtilities: addUtilities as never,
+    matchUtilities: matchUtilities as never,
+    theme: theme as never,
+  });
+
+  return { addUtilities, matchUtilities, spacing };
+};
+
+describe('addSafeAreaUtilities', () => {
+  it('registers bare padding utilities equal to the inset', () => {
+    const { addUtilities } = setup();
+    const utilities = addUtilities.mock.calls[0][0];
+
+    expect(utilities['.pt-safe']).toEqual({
+      'padding-top': 'env(safe-area-inset-top)',
+    });
+    expect(utilities['.pb-safe']).toEqual({
+      'padding-bottom': 'env(safe-area-inset-bottom)',
+    });
+    expect(utilities['.px-safe']).toEqual({
+      'padding-left': 'env(safe-area-inset-left)',
+      'padding-right': 'env(safe-area-inset-right)',
+    });
+    expect(utilities['.p-safe']).toEqual({
+      'padding-top': 'env(safe-area-inset-top)',
+      'padding-right': 'env(safe-area-inset-right)',
+      'padding-bottom': 'env(safe-area-inset-bottom)',
+      'padding-left': 'env(safe-area-inset-left)',
+    });
+  });
+
+  it('registers one offset family per side, seeded from the spacing scale', () => {
+    const { matchUtilities, spacing } = setup();
+
+    // One matchUtilities call per physical side.
+    expect(matchUtilities).toHaveBeenCalledTimes(4);
+
+    // Every call must feed off the theme spacing scale so the safe offsets stay
+    // in sync with the normal padding scale.
+    for (const [, options] of matchUtilities.mock.calls) {
+      expect(options).toEqual({ values: spacing });
+    }
+  });
+
+  it('offset utilities compose base spacing with the inset via calc()', () => {
+    const { matchUtilities } = setup();
+
+    // Find the bottom family (`pb-safe`) and invoke its generator.
+    const bottomCall = matchUtilities.mock.calls.find(
+      ([utils]) => 'pb-safe' in utils,
+    );
+    expect(bottomCall).toBeDefined();
+
+    const generate = bottomCall![0]['pb-safe'];
+    expect(generate('1rem')).toEqual({
+      'padding-bottom': 'calc(1rem + env(safe-area-inset-bottom))',
+    });
+  });
+});
+
+describe('blotchPlugin', () => {
+  it('runs the plugin setup callback, registering base styles and safe area utilities', () => {
+    // Reach the plugin's `handler` (the first arg to the tailwind `plugin()`
+    // factory) so its `addBase` + `addSafeAreaUtilities` calls are covered.
+    const addBase = vi.fn();
+    const addUtilities = vi.fn();
+    const matchUtilities = vi.fn();
+    const theme = vi.fn(() => ({ '4': '1rem' }));
+
+    // The tailwindcss `plugin()` factory returns a `{ handler, config }`
+    // object at runtime. Cast through unknown so TypeScript accepts the
+    // internal shape.
+    const factory = blotchPlugin as unknown as {
+      handler: (api: unknown) => void;
+      config?: unknown;
+    };
+
+    factory.handler({
+      addBase,
+      addUtilities,
+      matchUtilities,
+      theme,
+    });
+
+    expect(addBase).toHaveBeenCalledWith({
+      '*': { 'border-color': 'var(--border)' },
+    });
+    // The safe area utilities came through — bare + matched variants added.
+    expect(addUtilities).toHaveBeenCalled();
+    expect(matchUtilities).toHaveBeenCalled();
+  });
+
+  it('exposes a config object containing the theme extension colors', () => {
+    // The second argument to `plugin()` is a config object that Tailwind
+    // deep-merges into the user's config. Verify our theme extensions round-
+    // trip so the colors are exposed to the utility classes.
+    const factory = blotchPlugin as unknown as {
+      config?: { theme?: { extend?: { colors?: Record<string, unknown> } } };
+    };
+    const colors = factory.config?.theme?.extend?.colors;
+    expect(colors).toBeDefined();
+    expect(colors!['background']).toBe('var(--background)');
+  });
+});

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

@@ -0,0 +1,151 @@
+import plugin from 'tailwindcss/plugin';
+import type { PluginAPI } from 'tailwindcss/types/config';
+
+/**
+ * The four physical sides, paired with their safe-area `env()` inset. Used to
+ * generate the padding utilities below without repeating the mapping.
+ */
+const SAFE_AREA_SIDES = {
+  t: { prop: 'padding-top', inset: 'env(safe-area-inset-top)' },
+  r: { prop: 'padding-right', inset: 'env(safe-area-inset-right)' },
+  b: { prop: 'padding-bottom', inset: 'env(safe-area-inset-bottom)' },
+  l: { prop: 'padding-left', inset: 'env(safe-area-inset-left)' },
+} as const;
+
+/**
+ * Registers safe-area-aware padding utilities driven by CSS `env(safe-area-inset-*)`.
+ *
+ * Why `env()` works on Lynx: the native CSS engine parses `env(safe-area-inset-*)`
+ * as a length (see references/lynx .../css_style_utils.cc `GetEnvValue`), and its
+ * calc parser accepts `env()` *inside* `calc()` too — so `calc(1rem + env(...))`
+ * is valid on device. The inset values default to `0` until the native host app
+ * populates them, so every utility here degrades gracefully to plain padding
+ * (the offset variants) or to no padding (the bare variants).
+ *
+ * Two flavors:
+ * - Bare (`.pb-safe`, `.px-safe`, `.p-safe`, …) — padding equal to the inset alone.
+ * - Offset (`.pb-safe-4`, `.pt-safe-2`, …) — a spacing-scale value PLUS the inset,
+ *   e.g. `calc(1rem + env(safe-area-inset-bottom))`. Use these when an element
+ *   already wants base padding but must also clear the notch/home indicator
+ *   (the toast wrapper is the canonical case).
+ */
+export const addSafeAreaUtilities = ({
+  addUtilities,
+  matchUtilities,
+  theme,
+}: Pick<PluginAPI, 'addUtilities' | 'matchUtilities' | 'theme'>): void => {
+  const { t, r, b, l } = SAFE_AREA_SIDES;
+
+  // Bare utilities: padding = the inset itself.
+  addUtilities({
+    '.pt-safe': { [t.prop]: t.inset },
+    '.pr-safe': { [r.prop]: r.inset },
+    '.pb-safe': { [b.prop]: b.inset },
+    '.pl-safe': { [l.prop]: l.inset },
+    '.px-safe': { [l.prop]: l.inset, [r.prop]: r.inset },
+    '.py-safe': { [t.prop]: t.inset, [b.prop]: b.inset },
+    '.p-safe': {
+      [t.prop]: t.inset,
+      [r.prop]: r.inset,
+      [b.prop]: b.inset,
+      [l.prop]: l.inset,
+    },
+  });
+
+  // Offset utilities: base spacing + the inset, one family per side. Generated
+  // from the theme spacing scale so `pb-safe-4`, `pt-safe-2`, etc. all exist and
+  // stay in sync with the rest of the padding scale.
+  const spacing = theme('spacing') as Record<string, string>;
+  for (const { prop, inset } of [t, r, b, l]) {
+    const side = prop.replace('padding-', '')[0]; // 't' | 'r' | 'b' | 'l'
+    matchUtilities(
+      {
+        [`p${side}-safe`]: (value) => ({
+          [prop]: `calc(${value} + ${inset})`,
+        }),
+      },
+      { values: spacing },
+    );
+  }
+};
+
+/**
+ * Tailwind plugin that maps @blotch/ui CSS variables to semantic color utilities
+ * and registers safe-area-aware padding utilities.
+ *
+ * Usage in tailwind.config.ts:
+ *   import { blotchPlugin } from '@blotch/ui/theme/tailwind-plugin';
+ *   export default { plugins: [blotchPlugin] };
+ *
+ * Colors reference CSS variables DIRECTLY (`var(--x)`) rather than the shadcn/ui
+ * pattern of wrapping raw HSL channels in `hsl(var(--x) / <alpha-value>)`. Lynx's
+ * native CSS engine only parses comma-separated hsl(); Tailwind emits the
+ * space-separated form `hsl(var(--x) / 1)`, which Lynx silently drops (colors
+ * render transparent on device while looking fine in the web preview). Storing
+ * complete rgba() values in the variables (see theme/default.css) and
+ * referencing them directly avoids color-function parsing entirely. This matches
+ * the official React Lynx Tailwind example.
+ *
+ * Tradeoff: Tailwind opacity modifiers on semantic colors (bg-primary/50) don't
+ * work — the value is opaque with no separable channels. For the rare
+ * translucent-semantic need, add a dedicated rgba() variable (see
+ * `--destructive-subtle` → `destructive.subtle`) or use `opacity-*` on the element.
+ *
+ * Safe area: see `addSafeAreaUtilities` for the `*-safe` / `*-safe-<n>` padding
+ * utilities that keep content clear of notches and home indicators.
+ */
+export const blotchPlugin = plugin(
+  ({ addBase, addUtilities, matchUtilities, theme }) => {
+    addBase({
+      '*': {
+        'border-color': 'var(--border)',
+      },
+    });
+    addSafeAreaUtilities({ addUtilities, matchUtilities, theme });
+  },
+  {
+    theme: {
+      extend: {
+        colors: {
+          background: 'var(--background)',
+          foreground: 'var(--foreground)',
+          primary: {
+            DEFAULT: 'var(--primary)',
+            foreground: 'var(--primary-foreground)',
+          },
+          secondary: {
+            DEFAULT: 'var(--secondary)',
+            foreground: 'var(--secondary-foreground)',
+          },
+          muted: {
+            DEFAULT: 'var(--muted)',
+            foreground: 'var(--muted-foreground)',
+          },
+          accent: {
+            DEFAULT: 'var(--accent)',
+            foreground: 'var(--accent-foreground)',
+          },
+          destructive: {
+            DEFAULT: 'var(--destructive)',
+            foreground: 'var(--destructive-foreground)',
+            // Pre-composed translucent red for subtle destructive backgrounds,
+            // since bg-destructive/10 (opacity modifier) can't work here.
+            subtle: 'var(--destructive-subtle)',
+          },
+          border: 'var(--border)',
+          input: 'var(--input)',
+          ring: 'var(--ring)',
+          card: {
+            DEFAULT: 'var(--card)',
+            foreground: 'var(--card-foreground)',
+          },
+        },
+        borderRadius: {
+          lg: 'var(--radius)',
+          md: 'calc(var(--radius) - 2px)',
+          sm: 'calc(var(--radius) - 4px)',
+        },
+      },
+    },
+  },
+);

package/dist/ui/utils/animate.test.ts

@@ -0,0 +1,324 @@
+// Exercises every helper in animate.ts against a mock element with a spy on
+// `.animate()`/.setStyle(). The Lynx animate() API doesn't run in jsdom
+// (nothing renders), but the helpers still need to be called so their keyframe
+// / options wiring is covered. Assert on the arguments handed to the mock —
+// each helper's keyframe shape and duration/easing defaults are the meaningful
+// behavior to lock in.
+import { describe, expect, it, vi } from 'vitest';
+import {
+  DURATION,
+  EASING,
+  SCALE,
+  directionalSlideIn,
+  fadeIn,
+  fadeOut,
+  overlayClose,
+  overlayOpen,
+  popIn,
+  popOut,
+  pressDown,
+  pressRelease,
+  pulse,
+  revealIn,
+  scaleIn,
+  scaleOut,
+  shake,
+  slideIn,
+  slideOut,
+  springTranslateX,
+} from './animate';
+
+const makeEl = () => ({
+  animate: vi.fn(() => ({ cancel: vi.fn() })),
+  setStyle: vi.fn(),
+});
+
+describe('animate — constants', () => {
+  it('exposes DURATION, EASING, SCALE lookup tables', () => {
+    expect(DURATION.instant).toBe(100);
+    expect(EASING.decelerate).toContain('cubic-bezier');
+    expect(SCALE.popFrom).toBeCloseTo(0.6);
+  });
+});
+
+describe('animate — primitive helpers on null/undefined', () => {
+  it('every helper short-circuits when the element is null', () => {
+    expect(fadeIn(null)).toBeUndefined();
+    expect(fadeOut(null)).toBeUndefined();
+    expect(scaleIn(null)).toBeUndefined();
+    expect(scaleOut(null)).toBeUndefined();
+    expect(slideIn(null, 'up')).toBeUndefined();
+    expect(slideOut(null, 'up')).toBeUndefined();
+    expect(popIn(null)).toBeUndefined();
+    expect(popOut(null)).toBeUndefined();
+    expect(pulse(null)).toBeUndefined();
+    expect(shake(null)).toBeUndefined();
+    expect(springTranslateX(null, 0, 10)).toBeUndefined();
+    expect(revealIn(null)).toBeUndefined();
+    expect(directionalSlideIn(null, 1)).toBeUndefined();
+    // Press helpers: an element without setStyle also short-circuits.
+    expect(pressDown(null)).toBeUndefined();
+    expect(pressRelease(null)).toBeUndefined();
+    expect(pressDown({})).toBeUndefined();
+  });
+});
+
+describe('animate — primitive helpers on a real element', () => {
+  it('fadeIn animates opacity 0 → 1 with the default duration/easing', () => {
+    const el = makeEl();
+    fadeIn(el);
+    const [keyframes, options] = el.animate.mock.calls[0];
+    expect(keyframes).toEqual([{ opacity: 0 }, { opacity: 1 }]);
+    expect(options.duration).toBe(DURATION.normal);
+    expect(options.easing).toBe(EASING.decelerate);
+    expect(options.fill).toBe('forwards');
+  });
+
+  it('fadeIn honors custom duration / easing / fill', () => {
+    const el = makeEl();
+    fadeIn(el, { duration: 999, easing: 'linear', fill: 'both' });
+    const [, options] = el.animate.mock.calls[0];
+    expect(options).toEqual({
+      duration: 999,
+      easing: 'linear',
+      fill: 'both',
+    });
+  });
+
+  it('fadeOut animates opacity 1 → 0 with the accelerate default easing', () => {
+    const el = makeEl();
+    fadeOut(el);
+    const [keyframes, options] = el.animate.mock.calls[0];
+    expect(keyframes).toEqual([{ opacity: 1 }, { opacity: 0 }]);
+    expect(options.easing).toBe(EASING.accelerate);
+    expect(options.duration).toBe(DURATION.fast);
+  });
+
+  it('scaleIn uses SCALE.dialogFrom by default and honors overrides', () => {
+    const el = makeEl();
+    scaleIn(el);
+    const [keyframes] = el.animate.mock.calls[0];
+    expect(keyframes[0].transform).toContain(`scale(${SCALE.dialogFrom})`);
+
+    const el2 = makeEl();
+    scaleIn(el2, { fromScale: 0.5, fromY: 20 });
+    const [kf2] = el2.animate.mock.calls[0];
+    expect(kf2[0].transform).toContain('scale(0.5)');
+    expect(kf2[0].transform).toContain('translateY(20px)');
+  });
+
+  it('scaleOut animates towards the dialog exit transform', () => {
+    const el = makeEl();
+    scaleOut(el);
+    const [keyframes] = el.animate.mock.calls[0];
+    expect(keyframes[1].transform).toContain(`scale(${SCALE.dialogTo})`);
+
+    const el2 = makeEl();
+    scaleOut(el2, { toScale: 0.7, toY: 40 });
+    const [kf2] = el2.animate.mock.calls[0];
+    expect(kf2[1].transform).toContain('scale(0.7)');
+    expect(kf2[1].transform).toContain('translateY(40px)');
+  });
+
+  it.each([
+    ['up', 'translateY(100%)'],
+    ['down', 'translateY(-100%)'],
+    ['left', 'translateX(-100%)'],
+    ['right', 'translateX(100%)'],
+  ] as const)('slideIn from %s starts at %s', (direction, expected) => {
+    const el = makeEl();
+    slideIn(el, direction);
+    const [keyframes] = el.animate.mock.calls[0];
+    expect(keyframes[0].transform).toBe(expected);
+  });
+
+  it.each([
+    ['up', 'translateY(-100%)'],
+    ['down', 'translateY(100%)'],
+    ['left', 'translateX(-100%)'],
+    ['right', 'translateX(100%)'],
+  ] as const)('slideOut to %s ends at %s', (direction, expected) => {
+    const el = makeEl();
+    slideOut(el, direction);
+    const [keyframes] = el.animate.mock.calls[0];
+    expect(keyframes[1].transform).toBe(expected);
+  });
+
+  it('popIn defaults from SCALE.popFrom and honors fromScale', () => {
+    const el = makeEl();
+    popIn(el);
+    const [keyframes] = el.animate.mock.calls[0];
+    expect(keyframes[0].transform).toContain(`scale(${SCALE.popFrom})`);
+
+    const el2 = makeEl();
+    popIn(el2, { fromScale: 0.4 });
+    const [kf2] = el2.animate.mock.calls[0];
+    expect(kf2[0].transform).toContain('scale(0.4)');
+  });
+
+  it('popOut defaults to 0.8 and honors toScale', () => {
+    const el = makeEl();
+    popOut(el);
+    const [keyframes] = el.animate.mock.calls[0];
+    expect(keyframes[1].transform).toContain('scale(0.8)');
+
+    const el2 = makeEl();
+    popOut(el2, { toScale: 0.3 });
+    const [kf2] = el2.animate.mock.calls[0];
+    expect(kf2[1].transform).toContain('scale(0.3)');
+  });
+
+  it('pulse loops opacity indefinitely with a 1500ms default', () => {
+    const el = makeEl();
+    pulse(el);
+    const [keyframes, options] = el.animate.mock.calls[0];
+    expect(keyframes).toEqual([
+      { opacity: 1 },
+      { opacity: 0.5 },
+      { opacity: 1 },
+    ]);
+    expect(options.duration).toBe(1500);
+    expect(options.iterations).toBe(Infinity);
+
+    const el2 = makeEl();
+    pulse(el2, { duration: 400 });
+    const [, opts2] = el2.animate.mock.calls[0];
+    expect(opts2.duration).toBe(400);
+  });
+
+  it('shake produces a six-keyframe X wobble with forwards fill', () => {
+    const el = makeEl();
+    shake(el);
+    const [keyframes, options] = el.animate.mock.calls[0];
+    expect(keyframes).toHaveLength(6);
+    expect(keyframes[0].transform).toBe('translateX(0)');
+    expect(options.fill).toBe('forwards');
+
+    const el2 = makeEl();
+    shake(el2, { duration: 999, easing: 'linear' });
+    const [, opts2] = el2.animate.mock.calls[0];
+    expect(opts2.duration).toBe(999);
+    expect(opts2.easing).toBe('linear');
+  });
+
+  it('springTranslateX interpolates through the midpoint with a squish', () => {
+    const el = makeEl();
+    springTranslateX(el, 0, 20);
+    const [keyframes] = el.animate.mock.calls[0];
+    expect(keyframes[0].transform).toContain('translateX(0px)');
+    expect(keyframes[1].transform).toContain('translateX(10px)');
+    expect(keyframes[1].transform).toContain('scale(1.1)');
+    expect(keyframes[2].transform).toContain('translateX(20px)');
+
+    const el2 = makeEl();
+    springTranslateX(el2, 0, 20, {
+      duration: 500,
+      easing: 'ease',
+      fill: 'none',
+    });
+    const [, opts2] = el2.animate.mock.calls[0];
+    expect(opts2).toEqual({ duration: 500, easing: 'ease', fill: 'none' });
+  });
+
+  it('revealIn slides in from a small Y offset', () => {
+    const el = makeEl();
+    revealIn(el);
+    const [keyframes] = el.animate.mock.calls[0];
+    expect(keyframes[0].transform).toContain('translateY(8px)');
+
+    const el2 = makeEl();
+    revealIn(el2, { fromY: 24 });
+    const [kf2] = el2.animate.mock.calls[0];
+    expect(kf2[0].transform).toContain('translateY(24px)');
+  });
+
+  it('directionalSlideIn respects the direction sign', () => {
+    const el = makeEl();
+    directionalSlideIn(el, 1);
+    const [keyframes] = el.animate.mock.calls[0];
+    expect(keyframes[0].transform).toContain('translateX(24px)');
+
+    const el2 = makeEl();
+    directionalSlideIn(el2, -1);
+    const [kf2] = el2.animate.mock.calls[0];
+    expect(kf2[0].transform).toContain('translateX(-24px)');
+
+    const el3 = makeEl();
+    directionalSlideIn(el3, 1, { distance: 100 });
+    const [kf3] = el3.animate.mock.calls[0];
+    expect(kf3[0].transform).toContain('translateX(100px)');
+  });
+});
+
+describe('animate — press helpers', () => {
+  it('pressDown writes a transition + scale via setStyle', () => {
+    const el = makeEl();
+    const handle = pressDown(el);
+    expect(el.setStyle).toHaveBeenCalledWith(
+      'transition',
+      expect.stringContaining(`transform ${DURATION.instant}ms`),
+    );
+    expect(el.setStyle).toHaveBeenCalledWith(
+      'transform',
+      `scale(${SCALE.pressDown})`,
+    );
+    // The returned handle exposes a no-op cancel() for API parity.
+    expect(handle).toBeDefined();
+    expect(() => handle!.cancel()).not.toThrow();
+  });
+
+  it('pressDown honors a custom scale', () => {
+    const el = makeEl();
+    pressDown(el, 0.5);
+    expect(el.setStyle).toHaveBeenCalledWith('transform', 'scale(0.5)');
+  });
+
+  it('pressRelease returns to scale(1) via a spring easing transition', () => {
+    const el = makeEl();
+    pressRelease(el);
+    expect(el.setStyle).toHaveBeenCalledWith('transform', 'scale(1)');
+    expect(el.setStyle).toHaveBeenCalledWith(
+      'transition',
+      expect.stringContaining(EASING.spring),
+    );
+  });
+});
+
+describe('animate — composite overlay helpers', () => {
+  it.each(['center', 'bottom', 'left', 'right'] as const)(
+    'overlayOpen(%s) fades the backdrop and staggers the panel entrance',
+    (type) => {
+      vi.useFakeTimers();
+      const backdrop = makeEl();
+      const panel = makeEl();
+
+      overlayOpen(backdrop, panel, type);
+
+      // Backdrop fades in immediately.
+      expect(backdrop.animate).toHaveBeenCalled();
+      // Panel is scheduled 30ms later — advance the timer to fire it.
+      vi.advanceTimersByTime(30);
+      expect(panel.animate).toHaveBeenCalled();
+      vi.useRealTimers();
+    },
+  );
+
+  it.each([
+    ['center', 180],
+    ['bottom', DURATION.normal],
+    ['left', DURATION.normal],
+    ['right', DURATION.normal],
+  ] as const)(
+    'overlayClose(%s) returns the correct cleanup duration and animates both nodes',
+    (type, expectedDuration) => {
+      const backdrop = makeEl();
+      const panel = makeEl();
+
+      const duration = overlayClose(backdrop, panel, type);
+
+      expect(duration).toBe(expectedDuration);
+      expect(panel.animate).toHaveBeenCalled();
+      expect(backdrop.animate).toHaveBeenCalled();
+    },
+  );
+});