plugin.test.mjs

import assert from 'node:assert/strict';
import { mkdtemp, readFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';

import postcss from 'postcss';

import plugin from '../index.js';

const FIXTURE = `
@keyframes fade-up {
  from { opacity: 0; transform: translateY(40px); }
  to { opacity: 1; transform: translateY(0); }
}

.card {
  animation: fade-up 1s linear both;
  animation-timeline: view();
  animation-range: entry 0% entry 100%;
}
`;

/**
 * Run the plugin over some CSS.
 *
 * @param {string} css Input stylesheet.
 * @param {object} [options] Plugin options.
 * @returns {Promise<import('postcss').Result>} PostCSS result.
 */
function run (css, options) {
  return postcss([plugin(options)]).process(css, { from: undefined });
}

/**
 * Pull the manifest out of a PostCSS result's messages.
 *
 * @param {import('postcss').Result} result PostCSS result.
 * @returns {any} Manifest document.
 */
function manifestOf (result) {
  const message = result.messages.find((m) => m.type === 'scroll-anim-fallback-manifest');
  assert.ok(message, 'expected a manifest message');
  return message.manifest;
}

describe('@supports wrapping', () => {
  it('wraps scroll-driven rules in a native feature query', async () => {
    const { css } = await run(FIXTURE);
    assert.match(css, /@supports \(animation-timeline: scroll\(\)\) \{/);
    assert.match(css, /@supports \(animation-timeline: scroll\(\)\) \{\s*\.card \{/);
  });

  it('leaves rules without scroll-driven properties alone', async () => {
    const { css } = await run('.plain { color: red; }');
    assert.equal(css.trim(), '.plain { color: red; }');
  });

  it('detects every scroll-driven property family', async () => {
    for (const decl of [
      'scroll-timeline: --s block',
      'scroll-timeline-name: --s',
      'scroll-timeline-axis: inline',
      'view-timeline: --v y',
      'view-timeline-name: --v',
      'view-timeline-inset: 10%',
      'animation-range-start: entry 20%',
      'animation-range-end: exit 80%',
      'timeline-scope: --v'
    ]) {
      const { css } = await run(`.x { ${decl}; }`);
      assert.match(css, /@supports \(animation-timeline: scroll\(\)\)/, `missed: ${decl}`);
    }
  });

  it('can be disabled with supportsWrap: false', async () => {
    const { css } = await run(FIXTURE, { supportsWrap: false });
    assert.doesNotMatch(css, /@supports \(animation-timeline: scroll\(\)\)/);
    assert.match(css, /@supports not \(animation-timeline: scroll\(\)\)/);
  });

  it('keeps the unguarded rule with preserveOriginal: true', async () => {
    const { css } = await run(FIXTURE, { preserveOriginal: true });
    const occurrences = css.split('.card {').length - 1;
    assert.ok(occurrences >= 3, `expected original + guarded + fallback copies, saw ${occurrences}`);
  });
});

describe('idempotency', () => {
  it('does not double-wrap on a second pass', async () => {
    const first = await run(FIXTURE);
    const second = await run(first.css);
    const count = (css) => (css.match(/@supports \(animation-timeline: scroll\(\)\)/g) || []).length;
    assert.equal(count(first.css), 1);
    assert.equal(count(second.css), 1);
  });

  it('reuses a single fallback layer across passes', async () => {
    const first = await run(FIXTURE);
    const second = await run(first.css);
    const count = (second.css.match(/@supports not \(animation-timeline: scroll\(\)\)/g) || []).length;
    assert.equal(count, 1);
  });

  it('leaves a hand-written @supports guard untouched', async () => {
    const input = `
@keyframes fade-up { from { opacity: 0; } to { opacity: 1; } }
@supports (animation-timeline: view()) {
  .card { animation: fade-up 1s linear both; animation-timeline: view(); }
}
`;
    const { css } = await run(input);
    assert.equal((css.match(/@supports \(animation-timeline: view\(\)\)/g) || []).length, 1);
    assert.doesNotMatch(css, /@supports \(animation-timeline: scroll\(\)\)/);
  });
});

describe('manifest extraction', () => {
  it('records selector, timeline, range and animation metadata', async () => {
    const manifest = manifestOf(await run(FIXTURE));
    assert.equal(manifest.version, 1);
    assert.equal(manifest.classPrefix, 'saf');
    assert.equal(manifest.timelines.length, 1);

    const [entry] = manifest.timelines;
    assert.equal(entry.selector, '.card');
    assert.equal(entry.timeline.kind, 'view');
    assert.equal(entry.timeline.axis, 'block');
    assert.equal(entry.animationName, 'fade-up');
    assert.equal(entry.keyframes, 'fade-up');
    assert.equal(entry.duration, 1000);
    assert.deepEqual(entry.range.start, { name: 'entry', percent: 0 });
    assert.deepEqual(entry.range.end, { name: 'entry', percent: 100 });
    assert.equal(entry.progressProperty, '--saf-progress');
  });

  it('parses scroll() timelines including axis and scroller', async () => {
    const manifest = manifestOf(await run('.bar { animation: grow 1s; animation-timeline: scroll(root inline); }'));
    assert.deepEqual(manifest.timelines[0].timeline, {
      kind: 'scroll', name: null, axis: 'inline', scroller: 'root'
    });
  });

  it('parses named timelines', async () => {
    const manifest = manifestOf(await run('.bar { animation-timeline: --hero; }'));
    assert.equal(manifest.timelines[0].timeline.kind, 'named');
    assert.equal(manifest.timelines[0].timeline.name, '--hero');
  });

  it('defaults an omitted animation-range to the full cover range', async () => {
    const manifest = manifestOf(await run('.bar { animation: grow 1s; animation-timeline: view(); }'));
    assert.deepEqual(manifest.timelines[0].range, {
      start: { name: 'cover', percent: 0 },
      end: { name: 'cover', percent: 100 }
    });
  });

  it('expands a single-sided animation-range to both boundaries', async () => {
    const manifest = manifestOf(await run('.bar { animation-timeline: view(); animation-range: contain; }'));
    assert.deepEqual(manifest.timelines[0].range, {
      start: { name: 'contain', percent: 0 },
      end: { name: 'contain', percent: 100 }
    });
  });

  it('reads animation-range-start/end longhands', async () => {
    const manifest = manifestOf(await run(
      '.bar { animation-timeline: view(); animation-range-start: entry 25%; animation-range-end: exit 75%; }'
    ));
    assert.deepEqual(manifest.timelines[0].range, {
      start: { name: 'entry', percent: 25 },
      end: { name: 'exit', percent: 75 }
    });
  });

  it('assigns stable, unique ids in document order', async () => {
    const manifest = manifestOf(await run(
      '.a { animation-timeline: view(); } .b { animation-timeline: scroll(); }'
    ));
    assert.deepEqual(manifest.timelines.map((t) => t.id), ['saf-0', 'saf-1']);
  });

  it('writes the manifest to disk when a path is given', async () => {
    const dir = await mkdtemp(join(tmpdir(), 'saf-'));
    const path = join(dir, 'nested', 'manifest.json');
    await run(FIXTURE, { manifest: path });
    const written = JSON.parse(await readFile(path, 'utf8'));
    assert.equal(written.timelines[0].selector, '.card');
  });
});

describe('keyframe derivation', () => {
  it('normalises from/to and percentage selectors to 0–1 offsets', async () => {
    const manifest = manifestOf(await run(`
@keyframes pan { from { opacity: 0; } 40% { opacity: 0.5; } to { opacity: 1; } }
.bar { animation: pan 1s; animation-timeline: view(); }
`));
    assert.deepEqual(manifest.timelines[0].steps.map((s) => s.offset), [0, 0.4, 1]);
  });

  it('merges comma-separated keyframe selectors', async () => {
    const manifest = manifestOf(await run(`
@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
.bar { animation: pulse 1s; animation-timeline: view(); }
`));
    const offsets = manifest.timelines[0].steps.map((s) => s.offset);
    assert.deepEqual(offsets, [0, 0.5, 1]);
  });

  it('emits a two-state transition fallback for entry-style timelines', async () => {
    const { css } = await run(FIXTURE);
    const fallback = css.slice(css.indexOf('@supports not'));
    assert.match(fallback, /\.card \{[^}]*opacity: 0/);
    assert.match(fallback, /\.card\.saf-in-view \{[^}]*opacity: 1/);
    assert.match(fallback, /transition: opacity var\(--saf-duration, 600ms\)/);
    assert.match(fallback, /@media \(prefers-reduced-motion: reduce\)/);
  });

  it('picks the progress driver for continuous ranges', async () => {
    const manifest = manifestOf(await run(`
@keyframes pan { from { opacity: 0; } to { opacity: 1; } }
.bar { animation: pan 1s; animation-timeline: view(); animation-range: cover; }
`));
    assert.equal(manifest.timelines[0].mode, 'progress');
  });

  it('emits no fallback CSS when the animation has no keyframes', async () => {
    const { css } = await run('.bar { animation: missing 1s; animation-timeline: view(); }');
    assert.doesNotMatch(css, /@supports not/);
  });
});

describe('options', () => {
  it('fallbackMode: "progress" forces the progress driver everywhere', async () => {
    const result = await run(FIXTURE, { fallbackMode: 'progress' });
    const manifest = manifestOf(result);
    assert.equal(manifest.timelines[0].mode, 'progress');
    assert.match(result.css, /--saf-progress: 0/);
    assert.doesNotMatch(result.css, /saf-in-view/);
  });

  it('fallbackMode: "none" emits no fallback layer but still builds a manifest', async () => {
    const result = await run(FIXTURE, { fallbackMode: 'none' });
    assert.doesNotMatch(result.css, /@supports not/);
    assert.equal(manifestOf(result).timelines.length, 1);
    assert.equal(manifestOf(result).timelines[0].mode, 'none');
  });

  it('classPrefix renames classes, custom properties and ids', async () => {
    const result = await run(FIXTURE, { classPrefix: 'zz' });
    const [entry] = manifestOf(result).timelines;
    assert.equal(entry.id, 'zz-0');
    assert.equal(entry.classes.inView, 'zz-in-view');
    assert.equal(entry.progressProperty, '--zz-progress');
    assert.match(result.css, /\.card\.zz-in-view/);
    assert.doesNotMatch(result.css, /saf-/);
  });
});