@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/components/nav/react.tsx

@@ -0,0 +1,90 @@
+'use client';
+
+import { useRef, type HTMLAttributes, type MouseEvent, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { revealShell, type NavStyle } from './engine';
+
+export interface NavItem {
+  value: string;
+  label: ReactNode;
+  icon?: ReactNode;
+  /** Render a link instead of a button. */
+  href?: string;
+  /** Hidden in the phone bar (Stepbro's hide-on-mobile). */
+  hideOnMobile?: boolean;
+}
+
+export interface NavProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'> {
+  items: NavItem[];
+  /** Value of the current page. */
+  active?: string;
+  onSelect?: (value: string, event: MouseEvent<HTMLElement>) => void;
+  navStyle?: NavStyle;
+  accent?: boolean;
+  /** Reveal the surrounding .mk-shell from the first button on mount. */
+  reveal?: boolean;
+  /** The top button (workspace, account…): give it className "mk-nav__button mk-nav__button--first". */
+  first?: ReactNode;
+  /** Buttons at the end (className "mk-nav__button mk-nav__button--action"). */
+  actions?: ReactNode;
+}
+
+/** Stepbro's navigation. Put it inside a <div className="mk-shell"> next to <main className="mk-shell__view">. */
+export function Nav({
+  items,
+  active,
+  onSelect,
+  navStyle = 'bonita',
+  accent = false,
+  reveal = false,
+  first,
+  actions,
+  className,
+  ...props
+}: NavProps) {
+  const ref = useRef<HTMLElement>(null);
+  useIsomorphicLayoutEffect(() => {
+    if (!reveal || !ref.current) return;
+    const handle = revealShell(ref.current);
+    return () => handle?.cancel();
+    // Only on mount, like Stepbro.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  const classes = ['mk-nav', `mk-nav--${navStyle}`, accent && 'mk-nav--accent', className].filter(Boolean).join(' ');
+  return (
+    <nav ref={ref} aria-label="Principal" {...props} className={classes}>
+      {first}
+      <div className="mk-nav__buttons">
+        {items.map((item) => {
+          const shared = {
+            className: 'mk-nav__button',
+            'aria-current': item.value === active ? ('page' as const) : undefined,
+            'data-mk-value': item.value,
+            'data-mk-hide-mobile': item.hideOnMobile ? '' : undefined,
+            onClick: (event: MouseEvent<HTMLElement>) => onSelect?.(item.value, event),
+          };
+          const content = (
+            <>
+              {item.icon ? (
+                <span className="mk-nav__icon" aria-hidden="true">
+                  {item.icon}
+                </span>
+              ) : null}
+              <span className="mk-nav__name">{item.label}</span>
+            </>
+          );
+          return item.href ? (
+            <a key={item.value} href={item.href} {...shared}>
+              {content}
+            </a>
+          ) : (
+            <button key={item.value} type="button" {...shared}>
+              {content}
+            </button>
+          );
+        })}
+      </div>
+      {actions ? <div className="mk-nav__actions">{actions}</div> : null}
+    </nav>
+  );
+}

package/src/components/steps/README.md

@@ -0,0 +1,70 @@
+# steps
+
+El onboarding de Stepbro: un paso a la vez. Al cambiar de paso, los elementos del actual se van hacia abajo con blur (0.5 s, 50 ms entre ellos, `flowSoft`), se cambia el paso, se espera un frame y los del siguiente caen desde arriba. Un contador rueda hasta el número del paso (0.9 s), el foco pasa al título del paso nuevo y, mientras un paso trabaja (`busy`), el fondo de chat de dentro acelera y crece (energía 1.6, escala 1.8 en 0.8 s; vuelta en 0.6 s).
+
+Origen: Stepbro `OnboardingView` (`step-change`, `onboarding-busy-background`, kit Money). El fondo va al 20 % de opacidad, como en Stepbro.
+
+## HTML / Astro
+
+```html
+<mk-steps class="mk-steps" style="height: 100dvh">
+  <mk-chat-background></mk-chat-background>
+  <p>Paso <span data-mk-counter>1</span> de 3</p>
+  <div class="mk-steps__track">
+    <section data-mk-step>
+      <h2 data-mk-flow-item>Hola</h2>
+      <p data-mk-flow-item>Vamos a preparar tu cuenta.</p>
+      <button class="mk-button" data-mk-flow-item data-mk-step-next>Empezar</button>
+    </section>
+    <section data-mk-step>
+      <h2 data-mk-step-title data-mk-flow-item>¿Cómo te llamas?</h2>
+      <button class="mk-button" data-mk-flow-item data-mk-step-prev>Atrás</button>
+    </section>
+  </div>
+</mk-steps>
+
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-steps', 'mk-chat-background']);
+  const steps = document.querySelector('mk-steps');
+  steps.addEventListener('mk:step', (event) => console.log(event.detail.index));
+  // mientras guardas: steps.busy(true) … steps.busy(false); steps.next()
+</script>
+```
+
+Sin custom element: `createSteps(root, opciones)`.
+
+Partes: `[data-mk-step]` (los pasos; uno visible), `[data-mk-flow-item]` (lo que fluye dentro de un paso; sin marcas fluyen sus hijos), `[data-mk-step-title]` (recibe el foco; si no, el primer encabezado), `[data-mk-counter]`, botones `[data-mk-step-next]`, `[data-mk-step-prev]`, `[data-mk-step-goto="2"]` (1-based).
+
+## React
+
+```tsx
+const [step, setStep] = useState(0);
+const [saving, setSaving] = useState(false);
+
+<Steps className="mk-steps" index={step} onChange={setStep} busy={saving}>
+  <ChatBackground />
+  <p>Paso <Steps.Counter /> de 2</p>
+  <Steps.Step>
+    <h2 data-mk-flow-item>Hola</h2>
+    <button data-mk-flow-item onClick={() => setStep(1)}>Empezar</button>
+  </Steps.Step>
+  <Steps.Step>
+    <h2 data-mk-flow-item>¿Cómo te llamas?</h2>
+  </Steps.Step>
+</Steps>
+```
+
+`Steps.Step` debe ser hijo directo de `Steps`. React escribe el `hidden` inicial y el primer número del contador; después los lleva el motor.
+
+## API
+
+`createSteps(root, { index, duration, animateFirst, target, onChange })` → `{ next(), prev(), goTo(i), busy(on), index, count, steps, destroy }`. `next`, `prev` y `goTo` devuelven una promesa que se cumple al terminar; si se piden varios cambios seguidos, termina en el último. Evento `mk:step` (`detail`: `index`, `previous`, `step`).
+
+## Variables CSS
+
+`--mk-chat-background-opacity` (0.2 dentro de `.mk-steps`).
+
+## Accesibilidad
+
+Los pasos ocultos llevan `hidden` (fuera del árbol de accesibilidad). Al cambiar, el foco va al título del paso nuevo (con `tabindex="-1"` si hace falta) sin mover el scroll. `busy(true)` pone `aria-busy="true"`. Con movimiento reducido el paso cambia sin fluir.

package/src/components/steps/element.ts

@@ -0,0 +1,43 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSteps, type StepsInstance } from './engine';
+
+/**
+ * <mk-steps index="0">
+ *   <mk-chat-background></mk-chat-background>
+ *   <section data-mk-step><h2 data-mk-flow-item>Hola</h2><button data-mk-flow-item data-mk-step-next>Seguir</button></section>
+ *   <section data-mk-step>…</section>
+ * </mk-steps>
+ * Emits `mk:step` (detail: index, previous, step) after each change.
+ */
+export class MkStepsElement extends MkElement<StepsInstance> {
+  static options: Record<string, OptionType> = { index: 'number', duration: 'number', animateFirst: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createSteps(this, options);
+  }
+
+  // A new index moves to that step; rebuilding would jump without the flow.
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'index') void this.instance.goTo(Number(next) || 0);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  next() {
+    return this.instance?.next();
+  }
+
+  prev() {
+    return this.instance?.prev();
+  }
+
+  goTo(index: number) {
+    return this.instance?.goTo(index);
+  }
+
+  busy(on: boolean) {
+    this.instance?.busy(on);
+  }
+}
+
+export const defineSteps = () => defineElement('mk-steps', MkStepsElement);

package/src/components/steps/engine.ts

@@ -0,0 +1,185 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { nextFrame } from '../../core/frame';
+import { entrances, reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { clearStyles } from '../../core/styles';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { revealCounter } from '../../motion/count';
+import { flowIn, flowOut } from '../../motion/flow';
+import { chatBackgroundOf } from '../chat-background/engine';
+
+/*
+ * Stepbro's onboarding: one step at a time. Changing step flows the current
+ * step's items out (down into a 16 px blur, 0.5 s, 50 ms apart), swaps the step,
+ * waits a frame and flows the next one's items in from above. A counter rolls
+ * to the step number (0.9 s), focus moves to the new step's title, and while a
+ * step works (busy) the chat background inside speeds up and grows (energy 1.6,
+ * scale 1.8 in 0.8 s; back in 0.6 s).
+ * Parts: [data-mk-step] (items: [data-mk-flow-item], else its children),
+ * [data-mk-step-title], [data-mk-counter], [data-mk-step-next|prev|goto="n"].
+ */
+
+export interface StepsOptions {
+  /** First step shown (0-based). Default: the one marked data-mk-current, else 0. */
+  index?: number;
+  duration?: number;
+  /** Flow the first step in on start (default, as Stepbro). */
+  animateFirst?: boolean;
+  /** Items of a step that flow (default [data-mk-flow-item], else the step's children). */
+  target?: string;
+  onChange?: (index: number, previous: number) => void;
+}
+
+export interface StepsInstance extends Instance {
+  next(): Promise<void>;
+  prev(): Promise<void>;
+  goTo(index: number): Promise<void>;
+  /** A step is working: drives the chat background inside (Stepbro's onBusy). */
+  busy(on: boolean): void;
+  readonly index: number;
+  readonly count: number;
+  readonly steps: HTMLElement[];
+}
+
+export interface StepDetail {
+  index: number;
+  previous: number;
+  step: HTMLElement;
+}
+
+const STEP = '[data-mk-step]';
+const ITEM_STYLES = ['transform', 'translate', 'rotate', 'scale', 'filter', 'opacity', 'visibility'];
+
+export function createSteps(root: HTMLElement | null, options: StepsOptions = {}): StepsInstance {
+  // Steps of this root only, not those of a nested one.
+  const steps = root
+    ? [...root.querySelectorAll<HTMLElement>(STEP)].filter((step) => {
+        const outer = step.parentElement?.closest(STEP);
+        return !outer || !root.contains(outer);
+      })
+    : [];
+  if (!root || !steps.length) {
+    warnOnce('steps: needs [data-mk-step] children');
+    return inert({ next: async () => {}, prev: async () => {}, goTo: async () => {}, busy() {}, index: -1, count: 0, steps: [] });
+  }
+  registerMotion();
+  const scope = createScope();
+  const { duration = TIMING.onboarding.step, animateFirst = true, target = '[data-mk-flow-item]' } = options;
+  const clamp = (value: number) => Math.min(steps.length - 1, Math.max(0, Math.round(value)));
+  const marked = steps.findIndex((step) => step.hasAttribute('data-mk-current'));
+  let index = clamp(options.index ?? (marked >= 0 ? marked : 0));
+  let wanted = index;
+  let running: Promise<void> | null = null;
+  let stopCounter = () => {};
+
+  const itemsOf = (step: HTMLElement) => {
+    const marked = [...step.querySelectorAll<HTMLElement>(target)];
+    return marked.length ? marked : ([...step.children] as HTMLElement[]);
+  };
+  const show = (current: number) => {
+    steps.forEach((step, i) => {
+      scope.attr(step, 'hidden', i === current ? null : '');
+      scope.attr(step, 'data-mk-current', i === current ? '' : null);
+    });
+  };
+  const counter = () => {
+    const el = root.querySelector<HTMLElement>('[data-mk-counter]');
+    if (!el) return;
+    stopCounter();
+    stopCounter = revealCounter(el, index + 1, { duration: TIMING.onboarding.counter });
+  };
+  const focusTitle = (step: HTMLElement) => {
+    const title = step.querySelector<HTMLElement>('[data-mk-step-title]') ?? step.querySelector<HTMLElement>('h1, h2, h3, h4, h5, h6');
+    if (!title) return;
+    if (!title.hasAttribute('tabindex') && title.tabIndex < 0) scope.attr(title, 'tabindex', '-1');
+    title.focus({ preventScroll: true });
+  };
+
+  // One loop at a time; it follows `wanted` until it settles. `running` is cleared
+  // in the same tick the loop ends, so a goTo right after starts a new one.
+  const change = async () => {
+    try {
+      while (wanted !== index && !scope.disposed) {
+        const previous = index;
+        const next = wanted;
+        const out = reduced() ? null : flowOut(itemsOf(steps[previous]!), { duration });
+        if (out) await out;
+        if (scope.disposed) return;
+        index = next;
+        show(index);
+        const step = steps[index]!;
+        await nextFrame();
+        if (scope.disposed) return;
+        // Opacity only: a visibility-hidden title could not take the focus.
+        const items = itemsOf(step);
+        clearStyles(items, ['visibility']);
+        flowIn(items, { duration, autoAlpha: false });
+        counter();
+        focusTitle(step);
+        root.dispatchEvent(new CustomEvent<StepDetail>('mk:step', { bubbles: true, detail: { index, previous, step } }));
+        options.onChange?.(index, previous);
+      }
+    } finally {
+      running = null;
+    }
+  };
+
+  const goTo = (to: number) => {
+    wanted = clamp(to);
+    if (wanted === index && !running) return Promise.resolve();
+    running ??= change();
+    return running;
+  };
+
+  show(index);
+  scope.add(() => {
+    stopCounter();
+    for (const step of steps) {
+      const items = itemsOf(step);
+      gsap.killTweensOf(items);
+      clearStyles(items, ITEM_STYLES);
+    }
+  });
+  scope.on(root, 'click', (event) => {
+    const trigger = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-step-next], [data-mk-step-prev], [data-mk-step-goto]');
+    if (!trigger || !root.contains(trigger)) return;
+    if (trigger.hasAttribute('data-mk-step-next')) void goTo(wanted + 1);
+    else if (trigger.hasAttribute('data-mk-step-prev')) void goTo(wanted - 1);
+    else void goTo(Number(trigger.dataset.mkStepGoto) - 1);
+  });
+  const counterEl = root.querySelector<HTMLElement>('[data-mk-counter]');
+  if (counterEl) {
+    const text = counterEl.textContent;
+    counterEl.textContent = String(index + 1);
+    scope.add(() => {
+      counterEl.textContent = text;
+    });
+  }
+  if (animateFirst && entrances()) flowIn(itemsOf(steps[index]!), { duration });
+  root.dataset.mkReady = '';
+
+  return {
+    next: () => goTo(wanted + 1),
+    prev: () => goTo(wanted - 1),
+    goTo,
+    busy(on: boolean) {
+      scope.attr(root, 'aria-busy', on ? 'true' : null);
+      const background = root.querySelector('.mk-chat-background, mk-chat-background');
+      chatBackgroundOf(background)?.busy(on);
+    },
+    get index() {
+      return index;
+    },
+    get count() {
+      return steps.length;
+    },
+    get steps() {
+      return steps;
+    },
+    destroy() {
+      scope.dispose();
+      delete root.dataset.mkReady;
+    },
+  };
+}

package/src/components/steps/react.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  useRef,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createSteps, type StepsInstance } from './engine';
+
+interface StepsContextValue {
+  /** The step shown on the first render: React sets `hidden` once, then the engine owns it. */
+  initial: number;
+}
+
+const StepsContext = createContext<StepsContextValue>({ initial: 0 });
+const StepIndex = createContext(-1);
+
+export interface StepsProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /** Current step (0-based). Changing it flows to that step. */
+  index?: number;
+  onChange?: (index: number, previous: number) => void;
+  /** A step is working: the chat background inside speeds up (Stepbro's onBusy). */
+  busy?: boolean;
+  duration?: number;
+  children?: ReactNode;
+}
+
+function Root({ index = 0, onChange, busy = false, duration, className, children, ...props }: StepsProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<StepsInstance | null>(null);
+  const initial = useRef(index);
+  const change = useLatest(onChange);
+  useIsomorphicLayoutEffect(() => {
+    const created = createSteps(ref.current, { index: initial.current, duration, onChange: (i, previous) => change.current?.(i, previous) });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // Created once; index and busy are pushed below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    void instance.current?.goTo(index);
+  }, [index]);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.busy(busy);
+  }, [busy]);
+  let count = 0;
+  const numbered = Children.map(children, (child) =>
+    isValidElement(child) && child.type === Step ? <StepIndex.Provider value={count++}>{child}</StepIndex.Provider> : child,
+  );
+  return (
+    <StepsContext.Provider value={{ initial: initial.current }}>
+      <div ref={ref} className={['mk-steps', className].filter(Boolean).join(' ')} {...props}>
+        {numbered}
+      </div>
+    </StepsContext.Provider>
+  );
+}
+
+function Step({ children, ...props }: HTMLAttributes<HTMLElement>) {
+  const { initial } = useContext(StepsContext);
+  const index = useContext(StepIndex);
+  return (
+    <section data-mk-step="" hidden={index !== initial} {...props}>
+      {children}
+    </section>
+  );
+}
+
+/** The step number; the engine rolls it (React only writes the first value). */
+function Counter(props: HTMLAttributes<HTMLSpanElement>) {
+  const { initial } = useContext(StepsContext);
+  return (
+    <span data-mk-counter="" suppressHydrationWarning {...props}>
+      {initial + 1}
+    </span>
+  );
+}
+
+/**
+ * Stepbro's onboarding: <Steps index={i} busy={working}><ChatBackground /><Steps.Counter />
+ * <Steps.Step><h2 data-mk-flow-item>…</h2></Steps.Step>…</Steps>. Steps must be direct children.
+ */
+export const Steps = Object.assign(Root, { Step, Counter });

package/src/components/steps/steps.css

@@ -0,0 +1,49 @@
+/* steps — Stepbro's onboarding: one step at a time, centred in a column up to 600 px wide. */
+.mk-steps,
+mk-steps {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: space-around;
+  min-height: 0;
+  color: var(--md-sys-color-on-background);
+  font-family: var(--mk-font);
+}
+
+/* Stepbro's onboarding background runs at 20 %. */
+:is(.mk-steps, mk-steps) > :is(.mk-chat-background, mk-chat-background) {
+  --mk-chat-background-opacity: 0.2;
+}
+
+.mk-steps__track {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+  width: 100%;
+  max-width: 600px;
+}
+
+[data-mk-step] {
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+  align-items: center;
+  justify-content: space-around;
+}
+
+/* A step's own display never brings a hidden step back. */
+[data-mk-step][hidden] {
+  display: none !important;
+}
+
+[data-mk-step-title]:focus,
+[data-mk-step] :is(h1, h2, h3, h4, h5, h6)[tabindex='-1']:focus {
+  outline: none;
+}
+
+[data-mk-counter] {
+  font-variant-numeric: tabular-nums;
+}

package/src/components/theme-picker/README.md

@@ -0,0 +1,57 @@
+# theme-picker
+
+Las bolas de color del selector de tema de Stepbro. Entran escalonadas (desde 50 %, blur 4 px, 10 ms entre bolas); al pasar el ratón la bola se redondea a 32 px y se satura, y la elegida queda como cuadrado redondeado de 16 px (0.5 s, `cubic-bezier(.38,.49,0,1.5)`), con dos luces difuminadas que se mueven dentro (3.5 s). Al elegir una se aplica el tema con `setTheme()`.
+
+Origen: Stepbro — `theme-picker` / `theme-picker-enter` en el kit; CSS de las bolas portada de Kayro (`.accent-swatch`).
+
+## HTML / Astro
+
+```html
+<mk-theme-picker></mk-theme-picker>
+<mk-theme-picker show-hidden></mk-theme-picker>
+<mk-theme-picker themes="neogreen,pink,oled"></mk-theme-picker>
+
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  import { initTheme } from '@yewdiel21/motion-kit/theme';
+  initTheme();
+  defineElements(['mk-theme-picker']);
+</script>
+```
+
+Con tus propias bolas (no genera ninguna):
+
+```html
+<div class="mk-theme-picker" id="picker">
+  <button class="mk-swatch" data-mk-swatch="neogreen" style="--mk-swatch:#00e563" aria-label="Neogreen"></button>
+  <button class="mk-swatch" data-mk-swatch="pink" style="--mk-swatch:#f7acff" aria-label="Pink"></button>
+</div>
+<script>createThemePicker(document.getElementById('picker'));</script>
+```
+
+## React
+
+```tsx
+<ThemeProvider defaultTheme="neogreen">
+  <ThemePicker onChange={(id) => console.log(id)} />
+</ThemeProvider>
+```
+
+`useTheme()` dentro del provider da `{ id, mode, resolved, setTheme, setMode }`.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `themes` | `themes="a,b"` | los 10 visibles de Stepbro | Ids y orden de las bolas |
+| `showHidden` | `show-hidden` | `false` | Incluye los 9 temas que Stepbro oculta |
+| `labels.group` | `aria-label` | `'Tema'` | Nombre accesible del grupo |
+| `onChange` | evento `mk:theme` en `document` | — | Tema elegido |
+
+## Variables CSS
+
+`--mk-swatch-size` (72px), `--mk-swatch-gap` (12px) y, por bola, `--mk-swatch` (su color).
+
+## Accesibilidad
+
+Grupo con nombre; cada bola es un botón con `aria-label` y `aria-pressed`. Con movimiento reducido no hay entrada ni transiciones.

package/src/components/theme-picker/element.ts

@@ -0,0 +1,20 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createThemePicker, type ThemePickerInstance } from './engine';
+
+/**
+ * <mk-theme-picker show-hidden themes="neogreen,pink"></mk-theme-picker>
+ * Emits `mk:theme` on document when a theme is chosen (from setTheme).
+ */
+export class MkThemePickerElement extends MkElement<ThemePickerInstance> {
+  static options: Record<string, OptionType> = { showHidden: 'boolean', themes: 'list' };
+
+  protected create(options: Record<string, unknown>) {
+    return createThemePicker(this, options);
+  }
+
+  select(id: string) {
+    this.instance?.select(id);
+  }
+}
+
+export const defineThemePicker = () => defineElement('mk-theme-picker', MkThemePickerElement);