@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/split-view/element.ts

@@ -0,0 +1,34 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSplitView, type SplitViewInstance } from './engine';
+
+/**
+ * <mk-split-view class="mk-split-view" ratio="0.35" stack-below="640" labels="Bandeja,Mensaje">
+ *   <section>…</section><section>…</section>
+ * </mk-split-view>. Emits mk:resize and mk:collapse from its separator.
+ */
+export class MkSplitViewElement extends MkElement<SplitViewInstance> {
+  static options: Record<string, OptionType> = {
+    orientation: 'string',
+    ratio: 'number',
+    min: 'number',
+    collapsible: 'string',
+    stackBelow: 'number',
+    storageKey: 'string',
+    labels: 'list',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    const raw = this.getAttribute('collapsible');
+    const collapsible = raw === null || raw === '' || raw === 'true' ? true : raw === 'false' ? false : raw === 'start' || raw === 'end' ? raw : true;
+    const labels = Array.isArray(options.labels) && options.labels.length === 2 ? (options.labels as [string, string]) : undefined;
+    return createSplitView(this, { ...options, collapsible, labels });
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'ratio' && next !== null && Number.isFinite(Number(next))) this.instance.setRatio(Number(next));
+    else super.attributeChangedCallback(name, previous, next);
+  }
+}
+
+export const defineSplitView = () => defineElement('mk-split-view', MkSplitViewElement);

package/src/components/split-view/engine.ts

@@ -0,0 +1,114 @@
+import { registerMotion } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { createResizablePanel, type PanelOrientation } from '../resizable-panel/engine';
+
+/*
+ * Split view: two areas side by side (or one over the other) with
+ * resizable-panel's separator between them: it drags with a rubber band at the
+ * limits, keys, snaps a side shut when dragged well past its minimum, and a
+ * double click centres it back. Its buttons shut either side and open it
+ * again (.3 s, swing). setRatio() glides to a split (.45 s, signature). Under
+ * `stackBelow` pixels of width the areas stack, the separator turning with
+ * them. The split can be remembered (storageKey).
+ */
+
+export type SplitSide = 'start' | 'end';
+
+export interface SplitViewOptions {
+  /** 'horizontal' (default): side by side; 'vertical': one over the other. */
+  orientation?: PanelOrientation;
+  /** The first area's share, 0–1 (default .5). */
+  ratio?: number;
+  /** Smallest share of an area in percent (default 15). */
+  min?: number;
+  /** Which sides can shut: true (default) both, 'start', 'end' or false. */
+  collapsible?: boolean | SplitSide;
+  /** Stack the areas when the view is narrower than this many pixels (default 0: never). */
+  stackBelow?: number;
+  storageKey?: string;
+  /** Names of the two areas (default 'Primera área', 'Segunda área'; or their data-label). */
+  labels?: [string, string];
+  /** After a change of the split ends. */
+  onChange?: (ratio: number) => void;
+  onCollapse?: (side: SplitSide | null) => void;
+}
+
+export interface SplitViewInstance extends Instance {
+  setRatio(ratio: number, animate?: boolean): void;
+  collapse(side: SplitSide): void;
+  /** Open the side that is shut. */
+  expand(): void;
+  toggle(side: SplitSide): void;
+  readonly ratio: number;
+  readonly collapsed: SplitSide | null;
+  readonly orientation: PanelOrientation;
+}
+
+export function createSplitView(root: HTMLElement | null, options: SplitViewOptions = {}): SplitViewInstance {
+  const areas = root ? [...root.children].filter((child): child is HTMLElement => child instanceof HTMLElement) : [];
+  if (!root || areas.length !== 2) {
+    return inert({ setRatio() {}, collapse() {}, expand() {}, toggle() {}, ratio: 0.5, collapsed: null, orientation: 'horizontal' as PanelOrientation });
+  }
+  registerMotion();
+  const scope = createScope();
+  const ratio = Math.min(1, Math.max(0, Number.isFinite(options.ratio) ? options.ratio! : 0.5));
+  const sides = options.collapsible === false ? [] : options.collapsible === 'start' ? [0] : options.collapsible === 'end' ? [1] : [0, 1];
+  const preferred: PanelOrientation = options.orientation === 'vertical' ? 'vertical' : 'horizontal';
+  const sideOf = (index: number): SplitSide => (index === 0 ? 'start' : 'end');
+  scope.attr(root, 'data-mk-split', '');
+  const panel = createResizablePanel(root, {
+    orientation: preferred,
+    sizes: [ratio * 100, (1 - ratio) * 100],
+    min: options.min ?? 15,
+    collapsible: sides,
+    handleButtons: sides.length > 0,
+    storageKey: options.storageKey,
+    labels: options.labels ?? [areas[0]!.dataset.label ?? 'Primera área', areas[1]!.dataset.label ?? 'Segunda área'],
+    onResizeEnd: (sizes) => options.onChange?.(Math.round(sizes[0]! * 10) / 1000),
+    onCollapse: (index, shut) => options.onCollapse?.(shut ? sideOf(index) : null),
+  });
+  scope.add(() => panel.destroy());
+
+  // Narrow: stacked.
+  if (options.stackBelow && options.stackBelow > 0 && typeof ResizeObserver === 'function') {
+    const limit = options.stackBelow;
+    scope.observe(
+      new ResizeObserver(() => {
+        const width = root.getBoundingClientRect().width;
+        panel.setOrientation(width && width < limit ? 'vertical' : preferred);
+      }),
+    ).observe(root);
+  }
+
+  const collapsedSide = () => (panel.collapsed.includes(0) ? 'start' : panel.collapsed.includes(1) ? 'end' : null);
+  return {
+    setRatio(next, animate = true) {
+      const share = Math.min(1, Math.max(0, next));
+      panel.setSizes([share * 100, (1 - share) * 100], animate);
+    },
+    collapse(side) {
+      const other = side === 'start' ? 1 : 0;
+      if (panel.collapsed.includes(other)) panel.expand(other);
+      panel.collapse(side === 'start' ? 0 : 1);
+    },
+    expand() {
+      for (const index of panel.collapsed) panel.expand(index);
+    },
+    toggle(side) {
+      const index = side === 'start' ? 0 : 1;
+      if (panel.collapsed.includes(index)) panel.expand(index);
+      else this.collapse(side);
+    },
+    get ratio() {
+      return Math.round(panel.sizes[0]! * 10) / 1000;
+    },
+    get collapsed() {
+      return collapsedSide();
+    },
+    get orientation() {
+      return panel.orientation;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/split-view/react.tsx

@@ -0,0 +1,63 @@
+'use client';
+import { forwardRef, useImperativeHandle, useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createSplitView, type SplitViewInstance, type SplitViewOptions } from './engine';
+
+export interface SplitViewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'>, SplitViewOptions {
+  /** The two areas. */
+  children: [ReactNode, ReactNode];
+}
+
+export type SplitViewHandle = Pick<SplitViewInstance, 'setRatio' | 'collapse' | 'expand' | 'toggle'>;
+
+/** <SplitView ratio={0.35} stackBelow={640} labels={['Bandeja', 'Mensaje']}><List /><Detail /></SplitView>. A new `ratio` glides there. */
+export const SplitView = forwardRef<SplitViewHandle, SplitViewProps>(function SplitView(
+  { orientation, ratio, min, collapsible, stackBelow, storageKey, labels, onChange, onCollapse, className, children, ...props },
+  handle,
+) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<SplitViewInstance | null>(null);
+  const change = useLatest(onChange);
+  const collapse = useLatest(onCollapse);
+  const shown = useRef(ratio);
+  useImperativeHandle(
+    handle,
+    () => ({
+      setRatio: (next, animate) => instance.current?.setRatio(next, animate),
+      collapse: (side) => instance.current?.collapse(side),
+      expand: () => instance.current?.expand(),
+      toggle: (side) => instance.current?.toggle(side),
+    }),
+    [],
+  );
+  useIsomorphicLayoutEffect(() => {
+    const created = createSplitView(ref.current, {
+      orientation,
+      ratio: shown.current,
+      min,
+      collapsible,
+      stackBelow,
+      storageKey,
+      labels,
+      onChange: (next) => change.current?.(next),
+      onCollapse: (side) => collapse.current?.(side),
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [orientation, min, String(collapsible), stackBelow, storageKey, String(labels)]);
+  useIsomorphicLayoutEffect(() => {
+    if (ratio === undefined || ratio === shown.current) return;
+    shown.current = ratio;
+    instance.current?.setRatio(ratio);
+  }, [ratio]);
+  return (
+    <div {...props} ref={ref} className={['mk-split-view', className].filter(Boolean).join(' ')}>
+      {children[0]}
+      {children[1]}
+    </div>
+  );
+});

package/src/components/split-view/split-view.css

@@ -0,0 +1,18 @@
+/* split-view — two areas on a 20 px panel (surface-1, outline-soft border) with resizable-panel's separator between
+   them (its hairline, grip, bubble and the buttons that shut a side). Give it a height; each area scrolls on its own. */
+.mk-split-view,
+mk-split-view {
+  position: relative;
+  box-sizing: border-box;
+  display: flex;
+  min-width: 0;
+  min-height: 12rem;
+  overflow: hidden;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: 20px;
+  background: var(--mk-surface-1);
+}
+
+:is(.mk-split-view, mk-split-view)[data-mk-orientation='vertical'] {
+  flex-direction: column;
+}

package/src/components/star-rating/README.md

@@ -0,0 +1,14 @@
+# star-rating
+
+Valoración con estrellas sobre radios nativos (flechas del teclado y formularios incluidos). Al señalar, las estrellas se previsualizan en cascada de 20 ms; al elegir, la estrella rebota desde 1.4 con curva elástica, salta un destello y la etiqueta («Excelente») cambia con blur. `allowClear` permite quitar la valoración pulsando la estrella elegida. `readonly` dibuja un valor fijo (con fracciones) como imagen con su valor de nombre.
+
+```html
+<mk-star-rating class="mk-star-rating" name="valoracion" value="4" allow-clear></mk-star-rating>
+<mk-star-rating class="mk-star-rating" readonly value="4.5"></mk-star-rating>
+```
+
+`defineElements()`, `createStarRating(root, options)` o `<StarRating value={stars} onChange={setStars} />` (con `value` es controlado; `defaultValue` si no).
+
+Opciones: `max=5`, `value=0`, `name` (formulario), `label='Valoración'`, `labels` (un texto por estrella; por defecto Mala → Excelente), `readonly`, `allowClear`, `disabled`, `onChange(value)`. API: `setValue(n, notify=false)`, `value`, `destroy()`. Evento `mk:change` con `{value}`.
+
+Variables: `--mk-star-size` (2rem), `--mk-star-color` (#f5b301), `--mk-star-empty`. Movimiento reducido: sin rebote, cascada ni destello.

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

@@ -0,0 +1,26 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createStarRating, type StarRatingInstance } from './engine';
+
+/**
+ * <mk-star-rating class="mk-star-rating" name="valoracion" value="4" allow-clear></mk-star-rating>
+ * readonly with value="4.5" draws a fixed rating. Emits mk:change ({value}).
+ */
+export class MkStarRatingElement extends MkElement<StarRatingInstance> {
+  static options: Record<string, OptionType> = { max: 'number', value: 'number', name: 'string', label: 'string', labels: 'list', readonly: 'boolean', allowClear: 'boolean', disabled: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createStarRating(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'value') this.instance.setValue(Number(next) || 0);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  get value() {
+    return this.instance?.value ?? 0;
+  }
+}
+
+export const defineStarRating = () => defineElement('mk-star-rating', MkStarRatingElement);

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.