@mindlogic-ai/logician-ui 4.0.0-alpha.9 → 4.0.0

package/src/theme/motionGuards.test.ts

@@ -0,0 +1,137 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+/**
+ * The two ways `animationStyle` goes wrong are both silent, and neither can be
+ * caught by types. Chakra declares the prop as
+ * `ConditionalValue<UtilityValues["animationStyle"] | CssVars | AnyString>`:
+ * `AnyString` swallows every typo, and `ConditionalValue` accepts every array.
+ * Both compile. A typo then does nothing at all, and an array is read as
+ * *breakpoints* — one motion below `sm`, another above — which is the only
+ * mistake here that looks correct on the machine that wrote it.
+ *
+ * So the guard is a pair of `no-restricted-syntax` rules, and this is the test
+ * that the guard still guards. Without it those rules are two entries in a
+ * config that any unrelated cleanup can delete with nothing failing to say so.
+ *
+ * ESLint runs as a subprocess rather than through its Node API because its
+ * plugin loader resolves through the filesystem, which the jsdom environment
+ * these tests run in cannot provide.
+ */
+const CASES = {
+  vocabulary: `<div animationStyle="feedback" transitionProperty="opacity" />`,
+  chakraOwn: `<div animationStyle="scale-fade-in" />`,
+  typo: `<div animationStyle="sprng" transitionProperty="opacity" />`,
+  moved: `<div animationStyle="spin" />`,
+  array: `<div animationStyle={['travel', 'spring']} />`,
+  breakpoints: `<div animationStyle={{ base: 'travel', md: 'spring' }} />`,
+  // The scope guard: these three set the clock and leave the property at
+  // `none`, so the call site has to name what moves.
+  noScope: `<div animationStyle="travel" />`,
+  scopeViaShorthand: `<div animationStyle="travel" transition="width 1s" />`,
+  scopeViaCss: `<div animationStyle="spring" css={{ transitionProperty: 'translate' }} />`,
+  scopeViaSpread: `<div animationStyle="feedback" {...rest} />`,
+  // The two presets that carry their own scope and must not be asked for one.
+  pressNeedsNoScope: `<div animationStyle="press" />`,
+  presenceNeedsNoScope: `<div animationStyle="presence" />`,
+  anchoredNeedsNoScope: `<div animationStyle="presence-anchored" />`,
+};
+
+type Case = keyof typeof CASES;
+
+/** ESLint messages from the motion guards, keyed by case name. */
+const reported = new Map<Case, string[]>();
+
+beforeAll(() => {
+  const dir = mkdtempSync(join(tmpdir(), 'motion-guards-'));
+  const file = join(dir, 'probe.tsx');
+  // One line per case, so a single lint run tells us all six answers and the
+  // reported line number says which case each message belongs to.
+  const names = Object.keys(CASES) as Case[];
+  writeFileSync(
+    file,
+    names.map((n, i) => `export const C${i} = () => ${CASES[n]};`).join('\n')
+  );
+
+  let raw = '[]';
+  try {
+    raw = execFileSync(
+      'npx',
+      ['eslint', '--no-eslintrc', '-c', '.eslintrc.js', '-f', 'json', file],
+      { cwd: process.cwd(), encoding: 'utf-8' }
+    );
+  } catch (error) {
+    // ESLint exits non-zero when it reports errors, which is the expected case.
+    raw = (error as { stdout?: string }).stdout ?? raw;
+  }
+  rmSync(dir, { recursive: true, force: true });
+
+  const [result] = JSON.parse(raw) as {
+    messages: { ruleId: string | null; line: number; message: string }[];
+  }[];
+
+  names.forEach((n) => reported.set(n, []));
+  result?.messages
+    .filter((m) => m.ruleId === 'no-restricted-syntax')
+    .forEach((m) => reported.get(names[m.line - 1])?.push(m.message));
+});
+
+describe('the animationStyle guards', () => {
+  it('lets the vocabulary through', () => {
+    expect(reported.get('vocabulary')).toEqual([]);
+  });
+
+  it("lets Chakra's own names through, since they are real", () => {
+    expect(reported.get('chakraOwn')).toEqual([]);
+  });
+
+  it('catches a typo, which Chakra would otherwise ignore in silence', () => {
+    expect(reported.get('typo')?.join()).toContain('Unknown animationStyle');
+  });
+
+  it('catches a preset that moved to its component', () => {
+    // `spin` was global once, so anyone reading an older branch will try it.
+    expect(reported.get('moved')?.join()).toContain('Unknown animationStyle');
+  });
+
+  it('catches the array, which is breakpoints rather than two motions', () => {
+    expect(reported.get('array')?.join()).toContain('one name');
+  });
+
+  it('catches the breakpoint object for the same reason', () => {
+    expect(reported.get('breakpoints')?.join()).toContain('one name');
+  });
+});
+
+describe('the scope guard', () => {
+  it('catches a transition preset with nothing to move', () => {
+    // `transition-property: none` is the preset's own default, so this
+    // compiles, renders, and does nothing — the failure a diff cannot show.
+    expect(reported.get('noScope')?.join()).toContain('say what moves');
+  });
+
+  it.each([
+    ['the transition shorthand', 'scopeViaShorthand'],
+    ['a css object', 'scopeViaCss'],
+    ['a spread that may carry it', 'scopeViaSpread'],
+  ] as const)('accepts scope named through %s', (_label, key) => {
+    // Three real ways to say what moves. The spread is the loose one on
+    // purpose: what a caller passes is unknowable here, and a guard that
+    // cried wolf on every `{...rest}` would be turned off within the week.
+    expect(reported.get(key)).toEqual([]);
+  });
+
+  it.each([
+    ['press', 'pressNeedsNoScope'],
+    ['presence', 'presenceNeedsNoScope'],
+    ['presence-anchored', 'anchoredNeedsNoScope'],
+  ] as const)('leaves %s alone, since it carries its own scope', (_n, key) => {
+    // press defaults to `scale`; presence is an `animation-*` preset and its
+    // keyframe already names what moves. Asking either for a property would
+    // teach the opposite of what the vocabulary means.
+    expect(reported.get(key)).toEqual([]);
+  });
+});

package/src/theme/recipes/accordion.ts

@@ -0,0 +1,20 @@
+import { defineSlotRecipe } from '@chakra-ui/react';
+
+import { PRESENCE_TIMING } from '../motion';
+
+/**
+ * Logician overrides for Chakra's `accordion` slot recipe.
+ *
+ * Only the clock. Chakra opens and closes the item content over a symmetric
+ * 200 / 200, while `Collapsible` — the same height animation — already runs on
+ * the house `presence` policy (300 in, 150 out). Consumers render
+ * `Accordion.ItemContent` straight from Chakra, so a component prop cannot
+ * reach it; the recipe can. The recipe's own `expand-height` /
+ * `collapse-height` names are untouched and still decide what moves.
+ */
+export const accordionSlotRecipe = defineSlotRecipe({
+  slots: ['itemContent'],
+  base: {
+    itemContent: { ...PRESENCE_TIMING },
+  },
+});

package/src/translations/Defaults.translations.json

@@ -229,5 +229,12 @@
     "zh": "删除中",
     "ja": "削除中",
     "es": "Eliminando"
+  },
+  "close": {
+    "ko": "닫기",
+    "en": "Close",
+    "zh": "关闭",
+    "ja": "閉じる",
+    "es": "Cerrar"
   }
-}
+}

package/src/types/polymorphic.ts

@@ -0,0 +1,114 @@
+import type {
+  ComponentPropsWithoutRef,
+  ComponentPropsWithRef,
+  ElementType,
+  ReactElement,
+} from 'react';
+
+/**
+ * Types for a component whose rendered element can be swapped with `as`.
+ *
+ * ## Why this exists
+ *
+ * Chakra v3's prop types are bound to one element: `ButtonProps` extends
+ * `HTMLChakraProps<"button">`, so `as={Link}` swaps what RENDERS without
+ * swapping what type-checks. v2's polymorphic `ComponentWithAs` is gone, and
+ * Chakra's own answer is `asChild` — which is the right tool when you control
+ * the markup, because the child types itself.
+ *
+ * It is the wrong tool for a component library's consumers. `asChild` requires
+ * restructuring the call site to nest exactly one child, and a consuming app
+ * that just wants a link-shaped button ends up writing
+ * `href` under a `@ts-expect-error` instead. FactChat had **51 of those across
+ * 41 files** before this existed.
+ *
+ * ## What it does
+ *
+ * `as` picks the element; the element's own props join the component's own.
+ * Where they collide the component wins — `color` is a Chakra style prop here,
+ * not `<a>`'s deprecated presentational attribute — so a component's contract
+ * is never silently widened by the element it happens to render.
+ *
+ * ```tsx
+ * <Button as="a" href="/docs" target="_blank">문서</Button>
+ * <Button as={Link} href="/admin" prefetch={false}>관리자</Button>
+ * <Button onClick={save}>저장</Button>   // still a <button>, unchanged
+ * ```
+ */
+export type PolymorphicProps<TElement extends ElementType, TOwn> = TOwn & {
+  /** The element or component to render. Defaults to the component's own. */
+  as?: TElement;
+} & Omit<ComponentPropsWithoutRef<TElement>, keyof TOwn | 'as'>;
+
+/**
+ * The `ref` a polymorphic component takes, typed for the element `as` picked.
+ *
+ * Without this an `as="a"` call site still gets a `Ref<HTMLButtonElement>` and
+ * has to cast — the same defect one prop over.
+ */
+export type PolymorphicRef<TElement extends ElementType> =
+  ComponentPropsWithRef<TElement>['ref'];
+
+/**
+ * The public type of a polymorphic component: a generic call signature whose
+ * props follow whatever `as` renders, defaulting to `TDefault`.
+ */
+export type PolymorphicComponent<TOwn, TDefault extends ElementType> = (<
+  TElement extends ElementType = TDefault,
+>(
+  props: PolymorphicProps<TElement, TOwn> & { ref?: PolymorphicRef<TElement> }
+) => ReactElement) & { displayName?: string };
+
+/**
+ * Give a component the generic call signature above. **Type-level only** — the
+ * implementation, its behaviour and its rendered markup are untouched.
+ *
+ * ```tsx
+ * const ButtonImpl = forwardRef<HTMLButtonElement, ButtonOwnProps>(…);
+ * ButtonImpl.displayName = 'Button';
+ * export const Button = polymorphic<ButtonOwnProps>(ButtonImpl);
+ *
+ * const CardImpl = forwardRef<HTMLDivElement, CardOwnProps>(…);
+ * CardImpl.displayName = 'Card';
+ * export const Card = polymorphic<CardOwnProps, 'div'>(CardImpl);
+ * ```
+ *
+ * ## Why a cast, and why a helper
+ *
+ * `forwardRef` erases generics: its signature is fixed at the type it was
+ * instantiated with, so a generic component cannot be expressed through it.
+ * Re-declaring the call signature is the standard way around that. Doing it
+ * inline costs a dozen lines per component, which is how a design system ends
+ * up polymorphic in two places and not the other seventy-nine — so it lives
+ * here once, and each component spends one line.
+ *
+ * The `Impl` parameter is `unknown` on purpose. It is the erased signature we
+ * are replacing; accepting it as a typed component would only re-assert the
+ * type this function exists to discard.
+ *
+ * `displayName` stays on the implementation, where `react/display-name` can
+ * see it — the lint rule is the thing that stops a component shipping without
+ * one, and it cannot follow a name through this call.
+ *
+ * ## Consumers wrapping these components
+ *
+ * Call this the same way the components above do — a wrapper that pins the
+ * element back to its default undoes the polymorphism one layer up:
+ *
+ * ```ts
+ * export const ClickableCard = polymorphic<ClickableCardOwnProps, 'div'>(ClickableCardImpl);
+ * ```
+ *
+ * One thing to know: this is a runtime export, so a test that mocks
+ * `@mindlogic-ai/logician-ui` wholesale has to include it or the wrapper's
+ * module throws on import. The mock is `<T,>(Impl: T) => Impl` — this function
+ * is a type-level identity, so that IS the implementation. Casting against
+ * `PolymorphicComponent` instead works and needs no mock, but it costs the call
+ * site an `as unknown as` double cast, which is the kind of escape hatch a
+ * wrapper should not have to write.
+ */
+export function polymorphic<TOwn, TDefault extends ElementType = 'button'>(
+  Impl: unknown
+): PolymorphicComponent<TOwn, TDefault> {
+  return Impl as PolymorphicComponent<TOwn, TDefault>;
+}

package/src/utils/cubicBezier.ts

@@ -0,0 +1,69 @@
+import { MOTION_EASE, type MotionEaseToken } from '@/theme/motion';
+
+/**
+ * Turns one of the house curves into a function of progress, for motion that
+ * JavaScript has to drive frame by frame.
+ *
+ * Most motion never needs this: CSS reads `--chakra-easings-*` and
+ * framer-motion takes the `MOTION_EASE` tuples directly. What is left is the
+ * handful of things neither can animate — a *number* counting up, a canvas, a
+ * scroll position — where the value is interpolated in JS and the curve has to
+ * be evaluated rather than declared.
+ *
+ * Without this, that code reaches for `easeOutCubic` off the internet, and the
+ * count-up next to a card ends up on a different curve from the card. The point
+ * of a scale is that the exceptions stay on it.
+ *
+ * **Shared rather than local, even though `CountUp` is its only caller in this
+ * library.** The rule that sends a one-caller motion down next to its component
+ * (`spin` → `Spinner.styles.ts`) is about compositions the library owns; this is
+ * a reader of the scale, and its real audience is app code driving motion the
+ * library never sees — a framer-motion `animate`, an `Element.animate`, a rAF
+ * loop. Filing it under `CountUp/` would mean reaching into a component folder
+ * for a curve, which is the wrong shape for the thing it is.
+ *
+ * ```ts
+ * const ease = cubicBezier('emphasized');
+ * const value = from + (to - from) * ease(elapsed / duration);
+ * ```
+ */
+export const cubicBezier = (
+  curve: MotionEaseToken | readonly [number, number, number, number]
+): ((t: number) => number) => {
+  const [x1, y1, x2, y2] =
+    typeof curve === 'string' ? MOTION_EASE[curve] : curve;
+
+  // The classic 1-D cubic Bézier basis with P0 = 0 and P3 = 1, so only the two
+  // control coordinates vary. Written as the Horner form the browsers use.
+  const a = (c1: number, c2: number) => 1 - 3 * c2 + 3 * c1;
+  const b = (c1: number, c2: number) => 3 * c2 - 6 * c1;
+  const c = (c1: number) => 3 * c1;
+
+  const at = (t: number, c1: number, c2: number) =>
+    ((a(c1, c2) * t + b(c1, c2)) * t + c(c1)) * t;
+  const slope = (t: number, c1: number, c2: number) =>
+    3 * a(c1, c2) * t * t + 2 * b(c1, c2) * t + c(c1);
+
+  return (progress: number) => {
+    // Clamp rather than extrapolate: a caller that overshoots its own clock by
+    // a frame should land on the end value, not past it.
+    const t = progress <= 0 ? 0 : progress >= 1 ? 1 : progress;
+
+    // `t` is time along the curve's *x* axis, which is not the same as the
+    // parameter — solve for the parameter, then read `y`. Newton-Raphson from
+    // `t` itself converges in three or four steps for every curve here; the
+    // guard is for the flat-slope case, where the derivative gives no direction.
+    let u = t;
+    for (let i = 0; i < 6; i += 1) {
+      const dx = slope(u, x1, x2);
+      if (Math.abs(dx) < 1e-6) break;
+      const error = at(u, x1, x2) - t;
+      if (Math.abs(error) < 1e-6) break;
+      u -= error / dx;
+    }
+
+    // `overshoot` deliberately leaves [0, 1] in the middle — that is the whole
+    // point of it — so this is not clamped.
+    return at(u, y1, y2);
+  };
+};

package/src/utils/focusRing.ts

@@ -2,8 +2,13 @@
  * Standard focus ring styles for interactive components.
  *
  * - _focus: suppresses the browser's default outline on all focus events (including mouse)
- * - _focusVisible: shows the ring only on keyboard focus (CSS :focus-visible),
- *   with a 0.15s ease-out transition on box-shadow
+ * - _focusVisible: shows the ring only on keyboard focus (CSS :focus-visible)
+ *
+ * No transition, on purpose. The ring answers a key press, and keyboard
+ * actions should land instantly — Tab is pressed hundreds of times a day. It
+ * also used to be a `transition` *shorthand* under `:focus-visible`, which
+ * replaced the element's whole transition list while focused, so a
+ * keyboard-focused Switch or Checkbox snapped its fill instead of fading it.
  */
 export const focusRing = {
   _focus: { outline: 'none' },
@@ -11,7 +16,5 @@ export const focusRing = {
     outline: 'none',
     boxShadow:
       'rgb(255, 255, 255) 0px 0px 0px 2px, var(--chakra-colors-primary-main) 0px 0px 0px 4px',
-    transition: 'box-shadow 0.15s ease-out',
-    _motionReduce: { transition: 'none' },
   },
 } as const;

package/src/utils/mergeCss.ts

@@ -1,5 +1,5 @@
 import type { SystemStyleObject } from '@chakra-ui/react';
-import { merge } from 'lodash';
+import merge from 'lodash/merge';
 
 export const mergeCss = (
   ...styles: (SystemStyleObject | undefined | null | false)[]

package/src/utils/staggerProps.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+
+import { system } from '@/theme';
+import { MOTION_DURATION_MS, MOTION_STAGGER_MAX } from '@/theme/motion';
+
+import { staggerDelayMs, staggerProps } from './staggerProps';
+
+const applied = system.css({ animationStyle: 'stagger' }) as Record<
+  string,
+  any
+>;
+const REDUCED_QUERY = '@media (prefers-reduced-motion: reduce)';
+
+/**
+ * The delay is computed in two places — a `calc()` the browser evaluates and a
+ * function JS callers can evaluate — and the pair is only useful if they agree.
+ * These tests hold the two halves against each other and against the one rule
+ * that makes the whole primitive safe: the cap.
+ */
+describe('staggerProps', () => {
+  it('sends nothing down but the index', () => {
+    // Everything else — keyframe, duration, curve, cap — is one shared class.
+    // Only this number varies per item, and inlining just this number is what
+    // keeps a 200-row list from compiling 200 classes.
+    expect(staggerProps(3)).toEqual({
+      animationStyle: 'stagger',
+      style: { '--stagger-index': 3 },
+    });
+  });
+
+  it('grows one step per item', () => {
+    expect(staggerDelayMs(0)).toBe(0);
+    expect(staggerDelayMs(1)).toBe(MOTION_DURATION_MS.staggerStep);
+    expect(staggerDelayMs(4)).toBe(4 * MOTION_DURATION_MS.staggerStep);
+  });
+
+  it('stops growing at the cap, which is the point of the cap', () => {
+    const ceiling = MOTION_STAGGER_MAX * MOTION_DURATION_MS.staggerStep;
+
+    expect(staggerDelayMs(MOTION_STAGGER_MAX)).toBe(ceiling);
+    expect(staggerDelayMs(MOTION_STAGGER_MAX + 1)).toBe(ceiling);
+    // The number that matters: uncapped, the fortieth row of a list would
+    // arrive 1.4s after the first, which is not a stagger but a queue.
+    expect(staggerDelayMs(40)).toBe(ceiling);
+    expect(staggerDelayMs(40)).toBeLessThan(250);
+  });
+
+  it('treats a negative index as the first item rather than a negative delay', () => {
+    expect(staggerDelayMs(-3)).toBe(0);
+  });
+
+  it('resolves in CSS to exactly what the JS mirror computes', () => {
+    // The two have to stay in step, so the `calc()` is asserted term by term
+    // rather than as an opaque string: same cap, same step token, same `min()`.
+    expect(applied.animationDelay).toBe(
+      'calc(min(var(--stagger-index, 0), var(--stagger-max)) * var(--chakra-durations-motion-stagger-step))'
+    );
+    expect(applied['--stagger-max']).toBe(String(MOTION_STAGGER_MAX));
+    expect(system.token('durations.motion.stagger.step')).toBe(
+      `${MOTION_DURATION_MS.staggerStep}ms`
+    );
+  });
+
+  it('defaults the index to 0, so an un-indexed item is not held back', () => {
+    // A consumer who applies the preset directly, without `staggerProps`, gets
+    // an ordinary enter rather than an item that never arrives.
+    expect(applied.animationDelay).toContain('var(--stagger-index, 0)');
+  });
+});
+
+/**
+ * The stagger's one real failure mode is applying on anything other than the
+ * enter. A `transition-delay` would apply to every later property change on the
+ * element — a hover, a selection, a re-render from a filter keystroke — and
+ * re-deal a list the reader is in the middle of reading.
+ */
+describe('the enter-only gate', () => {
+  it('delays an animation, never a transition', () => {
+    expect(applied.animationDelay).toBeDefined();
+    expect(applied.transitionDelay).toBeUndefined();
+    // An animation runs when the element mounts and not again, which is the
+    // enter and nothing else.
+    expect(applied.animationName).toBe('stagger-in');
+  });
+
+  it('holds the opening frame through the delay instead of flashing first', () => {
+    expect(applied.animationFillMode).toBe('both');
+  });
+
+  it('parks at `none` while the ancestor is closed, so reopening re-deals', () => {
+    // Ark keeps menu and select content mounted after the first open, so mount
+    // alone would stagger once and never again. A changed `animation-name` is
+    // the only way CSS has to say "run that again".
+    expect(applied['[data-state="closed"] &']).toEqual({
+      animationName: 'none',
+    });
+  });
+
+  it('drops the delay entirely under reduced motion', () => {
+    expect(applied[REDUCED_QUERY]).toEqual({
+      animationName: 'none',
+      animationDelay: '0ms',
+    });
+  });
+});

package/src/utils/staggerProps.ts

@@ -0,0 +1,63 @@
+import { MOTION_DURATION_MS, MOTION_STAGGER_MAX } from '@/theme/motion';
+
+/** What `staggerProps` hands back — spreadable onto any Chakra element. */
+export interface StaggerProps {
+  animationStyle: 'stagger';
+  style: Record<string, string | number>;
+}
+
+/**
+ * Makes one list item arrive `index` beats after the first.
+ *
+ * ```tsx
+ * {options.map((option, i) => (
+ *   <Select.Item key={option.value} item={option} {...staggerProps(i)}>
+ * ))}
+ * ```
+ *
+ * A function rather than a `<Stagger>` wrapper. A wrapper has to render
+ * something to hold the index, and an extra node inside a `Menu.Content` or a
+ * `Select.Content` is not free: Ark walks those children to build its typeahead
+ * and roving-focus collections, and a grid or flex list would gain a layout box
+ * between the container and every row. This adds no DOM at all, and it composes
+ * with a list that is already being mapped rather than asking for the list to be
+ * restructured around it.
+ *
+ * The index rides an inline custom property rather than the `css` prop on
+ * purpose: `css` would compile one class per index and grow the stylesheet with
+ * the length of the longest list ever rendered, while the *only* thing that
+ * varies per item is this one number. Everything else — the keyframe, the
+ * duration, the curve, the cap — lives in the `stagger` preset, which is one
+ * class shared by every item on the page.
+ *
+ * Where **not** to use it, and why the list is short: stagger costs the reader
+ * time in exchange for rhythm, so it is worth it only where the list is short,
+ * arrives once, and is looked at as a whole. `Masonry` and `Table` are the
+ * explicit exclusions — both are long, both are candidates for virtualization
+ * (where "index" means position in a window that scrolls, so items would
+ * re-stagger as they scroll into view), and a sortable table re-orders its rows
+ * on click, which would deal the whole grid out again on every header press.
+ *
+ * @param index - The item's position in its list, from 0.
+ * @returns Props to spread onto the item. Merge `style` by hand if the call
+ *   site already sets one.
+ */
+export const staggerProps = (index: number): StaggerProps => ({
+  animationStyle: 'stagger',
+  // Not clamped here even though the preset's `min()` makes it redundant in
+  // CSS: an out-of-range value passed straight through is what makes a wrong
+  // index visible in the DOM instead of silently flattened.
+  style: { '--stagger-index': index },
+});
+
+/**
+ * The delay `staggerProps(index)` resolves to, in milliseconds.
+ *
+ * Exists for the two callers that cannot read a CSS variable — a test asserting
+ * the cap holds, and JS animation tech sequencing alongside a staggered list.
+ * It has to mirror the `calc()` in the `stagger` preset exactly, which is why
+ * both read the same two constants.
+ */
+export const staggerDelayMs = (index: number): number =>
+  Math.min(Math.max(index, 0), MOTION_STAGGER_MAX) *
+  MOTION_DURATION_MS.staggerStep;