@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/star-rating/engine.ts

@@ -0,0 +1,217 @@
+import { gsap, ELASTIC, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { numberFormat } from '../../core/dates';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { burst } from '../../motion/micro';
+
+/*
+ * Star rating on native radios (arrow keys and forms come from the platform).
+ * Pointing previews the stars in a 20 ms cascade; choosing one springs it from
+ * 1.4 (elastic), throws a small burst and the label ("Excelente") changes with
+ * a blur. allowClear lets a click on the chosen star clear it. readonly draws a
+ * value (fractions too) as an image with its value as the name.
+ */
+
+export interface StarRatingOptions {
+  max?: number;
+  value?: number;
+  /** Form name (default 'rating'). */
+  name?: string;
+  /** Accessible name of the group (default 'Valoración'). */
+  label?: string;
+  /** One text per star, shown and read for the chosen value. */
+  labels?: string[];
+  readonly?: boolean;
+  allowClear?: boolean;
+  disabled?: boolean;
+  onChange?: (value: number) => void;
+}
+
+export interface StarRatingInstance extends Instance {
+  setValue(value: number, notify?: boolean): void;
+  readonly value: number;
+}
+
+const STAR = 'M12 3.2l2.6 5.4 5.9.8-4.3 4.1 1 5.9L12 16.6l-5.2 2.8 1-5.9-4.3-4.1 5.9-.8z';
+const LABELS = ['Mala', 'Regular', 'Buena', 'Muy buena', 'Excelente'];
+let sequence = 0;
+
+const star = () => {
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('aria-hidden', 'true');
+  const back = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+  back.setAttribute('d', STAR);
+  back.dataset.mkPart = 'empty';
+  const front = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+  front.setAttribute('d', STAR);
+  front.dataset.mkPart = 'full';
+  svg.append(back, front);
+  return svg;
+};
+
+export function createStarRating(root: HTMLElement | null, options: StarRatingOptions = {}): StarRatingInstance {
+  if (!root) return inert({ setValue() {}, value: 0 });
+  registerMotion();
+  const scope = createScope();
+  const max = Math.max(1, Math.min(10, Math.round(Number.isFinite(options.max) ? options.max! : 5)));
+  const texts = options.labels ?? (max === 5 ? LABELS : []);
+  const clamp = (n: number) => Math.max(0, Math.min(max, n));
+  let value = clamp(Number.isFinite(options.value) ? options.value! : 0);
+  const name = options.name ?? `rating-${++sequence}`;
+
+  const group = document.createElement('div');
+  group.dataset.mkStars = '';
+  const caption = document.createElement('span');
+  caption.dataset.mkStarLabel = '';
+  root.append(group, caption);
+  scope.add(() => {
+    group.remove();
+    caption.remove();
+  });
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'style', root.getAttribute('style'));
+
+  const stars: HTMLElement[] = [];
+  const inputs: HTMLInputElement[] = [];
+  if (options.readonly) {
+    group.setAttribute('role', 'img');
+    for (let i = 1; i <= max; i++) {
+      const item = document.createElement('span');
+      item.dataset.mkStar = String(i);
+      item.append(star());
+      group.append(item);
+      stars.push(item);
+    }
+  } else {
+    group.setAttribute('role', 'radiogroup');
+    group.setAttribute('aria-label', options.label ?? 'Valoración');
+    for (let i = 1; i <= max; i++) {
+      const item = document.createElement('label');
+      item.dataset.mkStar = String(i);
+      const input = document.createElement('input');
+      input.type = 'radio';
+      input.name = name;
+      input.value = String(i);
+      input.className = 'mk-sr-only';
+      input.disabled = Boolean(options.disabled);
+      input.setAttribute('aria-label', texts[i - 1] ? `${i} de ${max}: ${texts[i - 1]}` : `${i} de ${max}`);
+      item.append(input, star());
+      group.append(item);
+      stars.push(item);
+      inputs.push(input);
+    }
+  }
+
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+
+  const svgs = () => stars.map((item) => item.querySelector('svg')!);
+  /** Light the stars up to `upto` (fractions fill the last one partly). */
+  const light = (upto: number) => {
+    stars.forEach((item, i) => {
+      const fill = Math.max(0, Math.min(1, upto - i));
+      item.style.setProperty('--mk-star-fill', `${(fill * 100).toFixed(1)}%`);
+      item.toggleAttribute('data-mk-on', fill >= 1);
+    });
+  };
+  const describe = () => {
+    const text = value ? texts[Math.ceil(value) - 1] ?? '' : '';
+    if (options.readonly) {
+      const shown = numberFormat(root, { maximumFractionDigits: 1 }).format(value);
+      group.setAttribute('aria-label', `${options.label ?? 'Valoración'}: ${shown} de ${max}`);
+      caption.textContent = shown;
+      return;
+    }
+    if (caption.textContent === text) return;
+    if (reduced() || !caption.textContent) {
+      caption.textContent = text;
+      return;
+    }
+    gsap.killTweensOf(caption);
+    keep(
+      gsap
+        .timeline()
+        .to(caption, { opacity: 0, filter: 'blur(4px)', y: -3, duration: 0.12 })
+        .call(() => {
+          caption.textContent = text;
+        })
+        .fromTo(caption, { opacity: 0, filter: 'blur(4px)', y: 3 }, { opacity: 1, filter: 'blur(0px)', y: 0, duration: 0.25, clearProps: 'all' }),
+    );
+  };
+  const paint = () => {
+    inputs.forEach((input, i) => (input.checked = i + 1 === value));
+    light(value);
+    describe();
+  };
+
+  const choose = (next: number, notify: boolean, animate: boolean) => {
+    if (scope.disposed) return;
+    const target = clamp(Math.round(next));
+    if (target === value) return;
+    value = target;
+    paint();
+    if (animate && target && !reduced()) {
+      const item = stars[target - 1]!;
+      keep(gsap.fromTo(item.querySelector('svg'), { scale: 1.45, rotation: -12 }, { scale: 1, rotation: 0, duration: 0.8, ease: ELASTIC, clearProps: 'all' }));
+      keep(gsap.fromTo(svgs().slice(0, target - 1), { scale: 0.8 }, { scale: 1, duration: 0.4, ease: 'back.out(3)', stagger: 0.03, clearProps: 'all' }));
+      keep(burst(item, { count: 6, distance: 22, size: 5, colors: ['var(--mk-star-color)'] }));
+    }
+    if (!notify) return;
+    options.onChange?.(value);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value } }));
+  };
+
+  if (!options.readonly) {
+    let preview = 0;
+    scope.on(group, 'pointerover', (event) => {
+      const item = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-star]');
+      if (!item || options.disabled) return;
+      const upto = Number(item.dataset.mkStar);
+      if (upto === preview) return;
+      const from = preview;
+      preview = upto;
+      scope.attr(root, 'data-mk-preview', String(upto));
+      light(upto);
+      if (!reduced() && upto > from) keep(gsap.fromTo(svgs().slice(from, upto), { scale: 0.85 }, { scale: 1, duration: 0.3, ease: 'back.out(3)', stagger: 0.02, clearProps: 'all' }));
+    });
+    scope.on(group, 'pointerleave', () => {
+      preview = 0;
+      scope.attr(root, 'data-mk-preview', null);
+      light(value);
+    });
+    // A click on the chosen star (allowClear) clears it: radios cannot uncheck themselves.
+    let before = 0;
+    scope.on(group, 'pointerdown', () => {
+      before = value;
+    });
+    scope.on(group, 'click', (event) => {
+      const input = (event.target as Element | null)?.closest('input');
+      if (!input || !options.allowClear) return;
+      if (Number(input.value) === before && before === value) {
+        before = -1;
+        choose(0, true, false);
+      }
+    });
+    for (const input of inputs) scope.on(input, 'change', () => choose(Number(input.value), true, true));
+  }
+  paint();
+
+  return {
+    setValue: (next, notify = false) => choose(next, notify, !notify),
+    get value() {
+      return value;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/star-rating/react.tsx

@@ -0,0 +1,33 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createStarRating, type StarRatingInstance, type StarRatingOptions } from './engine';
+
+export interface StarRatingProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<StarRatingOptions, 'value'> {
+  /** Controlled value; without it the stars keep their own (defaultValue). */
+  value?: number;
+  defaultValue?: number;
+}
+
+/** <StarRating value={stars} onChange={setStars} allowClear /> or <StarRating readonly value={4.5} />. */
+export function StarRating({ value, defaultValue, max, name, label, labels, readonly, allowClear, disabled, onChange, className, ...props }: StarRatingProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<StarRatingInstance | null>(null);
+  const change = useLatest(onChange);
+  const start = useRef(value ?? defaultValue ?? 0);
+  const key = JSON.stringify(labels ?? null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createStarRating(ref.current, { value: value ?? start.current, max, name, label, labels, readonly, allowClear, disabled, onChange: (next) => change.current?.(next) });
+    instance.current = created;
+    return () => {
+      start.current = created.value;
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [max, name, label, key, readonly, allowClear, disabled]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined && instance.current && instance.current.value !== value) instance.current.setValue(value);
+  }, [value]);
+  return <div {...props} ref={ref} className={['mk-star-rating', className].filter(Boolean).join(' ')} />;
+}

package/src/components/star-rating/star-rating.css

@@ -0,0 +1,79 @@
+/* star-rating — stars outlined in the surface tone, filled with the star colour; a label beside them.
+   Hover previews; the focus ring sits on the star of the focused radio. */
+.mk-star-rating,
+mk-star-rating {
+  --mk-star-size: 2rem;
+  --mk-star-color: #f5b301;
+  --mk-star-empty: var(--mk-surface-4);
+  display: inline-flex;
+  align-items: center;
+  gap: 0.75rem;
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+
+:is(.mk-star-rating, mk-star-rating) [data-mk-stars] {
+  display: inline-flex;
+  gap: 0.15rem;
+}
+
+:is(.mk-star-rating, mk-star-rating) [data-mk-star] {
+  position: relative;
+  display: grid;
+  place-items: center;
+  width: calc(var(--mk-star-size) + 0.5rem);
+  height: calc(var(--mk-star-size) + 0.5rem);
+  border-radius: 50%;
+  cursor: pointer;
+}
+
+:is(.mk-star-rating, mk-star-rating) [role='img'] [data-mk-star] {
+  width: var(--mk-star-size);
+  height: var(--mk-star-size);
+  cursor: default;
+}
+
+:is(.mk-star-rating, mk-star-rating) [data-mk-star] svg {
+  width: var(--mk-star-size);
+  height: var(--mk-star-size);
+  overflow: visible;
+}
+
+:is(.mk-star-rating, mk-star-rating) [data-mk-part='empty'] {
+  fill: var(--mk-star-empty);
+}
+
+:is(.mk-star-rating, mk-star-rating) [data-mk-part='full'] {
+  fill: var(--mk-star-color);
+  clip-path: inset(0 calc(100% - var(--mk-star-fill, 0%)) 0 0);
+  transition: clip-path 0.15s ease;
+}
+
+/* While previewing, lit stars are a step lighter. */
+:is(.mk-star-rating, mk-star-rating)[data-mk-preview] [data-mk-part='full'] {
+  fill: color-mix(in srgb, var(--mk-star-color) 75%, white);
+}
+
+:is(.mk-star-rating, mk-star-rating) [data-mk-star]:has(input:focus-visible) {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 1px;
+}
+
+:is(.mk-star-rating, mk-star-rating) [data-mk-star]:has(input:disabled) {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+:is(.mk-star-rating, mk-star-rating) [data-mk-star-label] {
+  min-width: 5.5rem;
+  color: var(--mk-muted);
+  font-size: 0.9375rem;
+  font-weight: 500;
+  font-variant-numeric: tabular-nums;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-star-rating, mk-star-rating) [data-mk-part='full'] {
+    transition: none;
+  }
+}

package/src/components/stat-card/README.md

@@ -0,0 +1,42 @@
+# stat-card
+
+Tarjeta de KPI con su tendencia. Cuando entra en pantalla, la cifra cuenta hasta su valor (.9 s) con el formato del idioma de la página (moneda, porcentaje, compacto). La variación respecto a `previous` va en una insignia (▲ o ▼ y el porcentaje): verde cuando va en la buena dirección (`positive` dice cuál), roja cuando no, neutra si no cambia. Aparece con un pop mientras la flecha da un empujón. Una minigráfica de `series` se dibuja sola (.9 s) con un área suave y un punto final que rebota; `target` llena una barra de meta.
+
+`update()` cuenta desde la cifra mostrada hasta la nueva, hace rodar los dígitos de la insignia, gira la flecha si cambia la tendencia y transforma la minigráfica hacia los puntos nuevos.
+
+## HTML / Astro
+
+```html
+<mk-stat-card class="mk-stat-card" label="Ingresos" value="128400" previous="118900"
+  format='{"style":"currency","currency":"MXN","maximumFractionDigits":0}'
+  series="90,98,104,101,118,128" target="150000"></mk-stat-card>
+```
+
+## React
+
+```tsx
+<StatCard label="Cancelaciones" value={42} previous={51} positive="down" comparison="vs. mes pasado" series={trend} />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `label` | `label` | — | Nombre del indicador. |
+| `value` | `value` | — | Cifra actual. |
+| `previous` | `previous` | — | Cifra con la que se compara. |
+| `format` | `format` (JSON) | 1 decimal | Opciones de `Intl.NumberFormat` o una función. |
+| `locale` | `locale` | `lang` de la página | Idioma de los números. |
+| `positive` | `positive` | `'up'` | Qué dirección es buena (`down` para costos, bajas, latencia). |
+| `comparison` | `comparison` | `'vs. periodo anterior'` | Con qué se compara. |
+| `series` | `series` (lista con comas) | — | Valores de la minigráfica (dos o más). |
+| `target` | `target` | — | Meta: una barra muestra el avance. |
+| `countOnView` | `count-on-view` | `true` | Contar al entrar en pantalla; `false` la muestra al momento. |
+
+## API
+
+`update({ value, previous, series, target, … })`, `destroy()`.
+
+## Accesibilidad y estilo
+
+La cifra visible es `aria-hidden`; una frase con los valores finales habla por ella («Ingresos: $128,400. Sube 8,0 % vs. periodo anterior.»). Tarjeta de 20 px sobre `--mk-surface-1`. Variables: `--mk-stat-good`, `--mk-stat-bad`, `--mk-stat-line`. Con movimiento reducido todo aparece en su valor final.

package/src/components/stat-card/element.ts

@@ -0,0 +1,40 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createStatCard, type StatCardInstance } from './engine';
+
+/**
+ * <mk-stat-card class="mk-stat-card" label="Ingresos" value="128400" previous="118900"
+ *   format='{"style":"currency","currency":"MXN","maximumFractionDigits":0}' series="90,98,104,101,118,128"></mk-stat-card>
+ * Changing value, previous, series or target updates it in place (the figure counts).
+ */
+export class MkStatCardElement extends MkElement<StatCardInstance> {
+  static options: Record<string, OptionType> = {
+    label: 'string',
+    value: 'number',
+    previous: 'number',
+    format: 'json',
+    locale: 'string',
+    positive: 'string',
+    comparison: 'string',
+    series: 'list',
+    target: 'number',
+    countOnView: 'boolean',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createStatCard(this, normalise(options));
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'locale' || name === 'count-on-view') return super.attributeChangedCallback(name, previous, next);
+    this.instance.update(normalise(this.options));
+  }
+}
+
+/** The series attribute is a comma list: numbers. */
+const normalise = (options: Record<string, unknown>) => ({
+  ...options,
+  series: Array.isArray(options.series) ? (options.series as string[]).map(Number).filter(Number.isFinite) : undefined,
+});
+
+export const defineStatCard = () => defineElement('mk-stat-card', MkStatCardElement);