@yewdiel21/motion-kit 0.17.0 → 0.18.0

package/src/components/radio-group/radio-group.css

@@ -0,0 +1,28 @@
+/* Tonal selectors: the selected surface rounds into a pill on the swatch curve. */
+:is(.mk-radio-group, mk-radio-group) { display: block; min-width: 0; font: 500 .875rem/1.4 var(--mk-font); color: var(--mk-text); }
+[data-mk-radio-body] { display: grid; gap: .5rem; }
+[data-mk-radio-options] { display: flex; flex-wrap: wrap; gap: .375rem; }
+[data-mk-radio-option] { position: relative; display: flex; align-items: center; gap: .75rem; min-height: 44px; padding: .65rem 1rem; border: 1px solid transparent; border-radius: 16px; background: var(--mk-surface-2); cursor: pointer; transition: background .2s, color .2s, border-radius .4s var(--mk-ease-swatch), padding .4s var(--mk-ease-swatch), box-shadow .2s; -webkit-tap-highlight-color: transparent; }
+[data-mk-radio-input] { position: absolute; width: 1px; height: 1px; opacity: 0; }
+[data-mk-radio-copy] { display: grid; gap: .2rem; }
+[data-mk-radio-description] { color: var(--mk-muted); font-size: .8125rem; font-weight: 400; }
+[data-mk-radio-mark] { flex: none; display: none; width: 20px; height: 20px; border: 1.5px solid var(--mk-outline); border-radius: 50%; box-sizing: border-box; }
+[data-mk-radio-option][data-mk-selected] { border-radius: 64px; padding-inline: 1.2rem; background: var(--mk-text); color: var(--mk-bg); }
+[data-mk-radio-option][data-mk-selected] [data-mk-radio-description] { color: inherit; opacity: .7; }
+[data-mk-radio-option]:has(:focus-visible) { outline: 2px solid var(--mk-accent); outline-offset: 3px; }
+[data-mk-radio-option]:has(:disabled) { opacity: .4; cursor: not-allowed; }
+[data-mk-radio-message] { color: var(--mk-muted); font-size: .8125rem; font-weight: 400; }
+[data-mk-radio-message]:empty { display: none; }
+:is(.mk-radio-group, mk-radio-group)[data-mk-error] [data-mk-radio-message] { color: var(--mk-error); }
+:is(.mk-radio-group, mk-radio-group)[data-mk-variant='card'] [data-mk-radio-options] { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 9rem), 1fr)); gap: .75rem; }
+:is(.mk-radio-group, mk-radio-group)[data-mk-variant='card'] [data-mk-radio-option] { flex-direction: column; align-items: flex-start; padding: 1rem; border-radius: 24px; background: var(--mk-surface-1); border-color: var(--mk-outline-soft); }
+:is(.mk-radio-group, mk-radio-group)[data-mk-variant='card'] [data-mk-radio-option][data-mk-selected] { background: var(--mk-surface-3); color: var(--mk-text); box-shadow: inset 0 0 0 1px var(--mk-text); border-radius: 32px; }
+:is(.mk-radio-group, mk-radio-group)[data-mk-variant='list'] [data-mk-radio-options] { display: grid; gap: .375rem; }
+:is(.mk-radio-group, mk-radio-group)[data-mk-variant='list'] [data-mk-radio-option] { background: transparent; border-radius: 12px; }
+:is(.mk-radio-group, mk-radio-group)[data-mk-variant='list'] [data-mk-radio-option][data-mk-selected] { background: var(--mk-surface-2); color: var(--mk-text); border-radius: 16px; }
+:is(.mk-radio-group, mk-radio-group):is([data-mk-variant='card'], [data-mk-variant='list']) [data-mk-radio-mark] { display: block; }
+[data-mk-radio-option][data-mk-selected] [data-mk-radio-mark] { border: 6px solid var(--mk-text); }
+@media (hover: hover) { [data-mk-radio-option]:not(:has(:disabled)):hover { background: var(--mk-surface-3); border-radius: 24px; } [data-mk-radio-option][data-mk-selected]:hover { background: var(--mk-text); color: var(--mk-bg); border-radius: 64px; } }
+@media (hover: hover) { :is(.mk-radio-group, mk-radio-group):is([data-mk-variant='card'], [data-mk-variant='list']) [data-mk-radio-option][data-mk-selected]:hover { background: var(--mk-surface-3); color: var(--mk-text); border-radius: 24px; } }
+@media (prefers-reduced-motion: reduce) { [data-mk-radio-option] { transition: none; } }
+@media (forced-colors: active) { [data-mk-radio-option] { border: 1px solid ButtonText; } [data-mk-radio-option][data-mk-selected] { outline: 2px solid Highlight; } }

package/src/components/radio-group/react.tsx

@@ -0,0 +1,60 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createRadioGroup, type RadioGroupOptions, type RadioGroupInstance } from './engine';
+
+export interface RadioGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onInput' | 'defaultValue' | 'children' | 'dangerouslySetInnerHTML'>, Omit<RadioGroupOptions, 'value' | 'defaultValue'> {
+  value?: string | null;
+  defaultValue?: string | null;
+  instanceRef?: MutableRefObject<RadioGroupInstance | null>;
+  /** The engine owns this component's DOM. */
+  children?: never;
+  dangerouslySetInnerHTML?: never;
+}
+export function RadioGroup({ value, defaultValue, items, name, label, disabled, required, error, variant, onChange, instanceRef, className, children: _children, dangerouslySetInnerHTML: _html, ...props }: RadioGroupProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const engine = useRef<RadioGroupInstance | null>(null);
+  const latestValue = useLatest(value);
+  const change = useLatest(onChange);
+  
+  const baseline = useRef(value !== undefined ? value : defaultValue);
+  const current = useRef(baseline.current);
+  const reconcile = () => queueMicrotask(() => {
+    if (latestValue.current !== undefined) engine.current?.setValue(latestValue.current, false);
+  });
+  useIsomorphicLayoutEffect(() => {
+    const created = createRadioGroup(root.current, {
+      items, name, label, disabled, required, error, variant, value: latestValue.current !== undefined ? latestValue.current : current.current, defaultValue: baseline.current,
+      onChange: (next) => { change.current?.(next); reconcile(); },
+      
+    });
+    engine.current = created;
+    const form = root.current?.closest('form');
+    const pending = new Set<ReturnType<typeof setTimeout>>();
+    const reset = (event: Event) => {
+      const timer = setTimeout(() => {
+        pending.delete(timer);
+        if (!event.defaultPrevented && latestValue.current !== undefined) created.setValue(latestValue.current, false);
+      }, 0);
+      pending.add(timer);
+    };
+    form?.addEventListener('reset', reset);
+    return () => {
+      form?.removeEventListener('reset', reset);
+      pending.forEach((timer) => clearTimeout(timer));
+      current.current = created.value; created.destroy(); engine.current = null;
+    };
+    // Callbacks and controlled value are read through refs.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [items, name, label, disabled, required, error, variant]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined) engine.current?.setValue(value, false);
+  });
+  useIsomorphicLayoutEffect(() => {
+    if (!instanceRef) return;
+    instanceRef.current = engine.current;
+    return () => { instanceRef.current = null; };
+  }, [instanceRef, items, name, label, disabled, required, error, variant]);
+  return <div {...props} ref={root} className={['mk-radio-group', className].filter(Boolean).join(' ')} />;
+}
+

package/src/components/radio-group/shared.ts

@@ -0,0 +1,118 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, press, rollDigits } from '../../motion/micro';
+
+export interface ChoiceItem { value: string; label: string; description?: string; disabled?: boolean; symbol?: string }
+export interface ChoiceOptions {
+  items?: ChoiceItem[]; value?: string | null; defaultValue?: string | null; name?: string; label?: string;
+  disabled?: boolean; required?: boolean; error?: string; variant?: string;
+  caption?: (value: string | null) => string;
+  eventValue?: (value: string | null) => unknown;
+  onChange?: (value: string | null) => void;
+  /** Private: decorates the options after each paint; `animate` is true only for live changes. */
+  decorate?: (labels: HTMLLabelElement[], index: number, previous: number, animate: boolean, keep: (effect: gsap.core.Animation | null) => void) => void;
+}
+export interface ChoiceInstance extends Instance { readonly value: string | null; setValue(value: string | null, notify?: boolean): void; reset(notify?: boolean): void }
+let sequence = 0;
+
+/** Private native-radio renderer. The browser owns arrow keys, validation and submission. */
+export function createChoices(root: HTMLElement | null, prefix: string, options: ChoiceOptions): ChoiceInstance {
+  if (!root) return inert({ value: null, setValue() {}, reset() {} });
+  registerMotion();
+  const scope = createScope();
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (effect: gsap.core.Animation | null) => {
+    for (const prior of effects) if (prior.totalProgress() === 1) effects.delete(prior);
+    if (effect) effects.add(effect);
+  };
+  scope.add(() => { effects.forEach((effect) => effect.kill()); effects.clear(); });
+  const part = <K extends keyof HTMLElementTagNameMap>(tag: K, parent: Element, name: string) => {
+    const el = document.createElement(tag);
+    el.setAttribute(`data-mk-${prefix}-${name}`, '');
+    parent.append(el);
+    return el;
+  };
+  const shell = part('div', root, 'body');
+  scope.add(() => shell.remove());
+  const group = part('div', shell, 'options');
+  group.setAttribute('role', 'radiogroup');
+  group.setAttribute('aria-label', options.label ?? 'Elige una opción');
+  group.setAttribute('aria-required', String(Boolean(options.required)));
+  if (options.disabled) group.setAttribute('aria-disabled', 'true');
+  const message = part('span', shell, 'message');
+  message.id = `mk-${prefix}-message-${++sequence}`;
+  message.setAttribute('aria-live', 'polite');
+  group.setAttribute('aria-describedby', message.id);
+  if (options.error) group.setAttribute('aria-invalid', 'true');
+  const seen = new Set<string>();
+  const items = (Array.isArray(options.items) ? options.items : []).filter((item) => {
+    if (!item || typeof item.value !== 'string' || seen.has(item.value)) return false;
+    seen.add(item.value); return true;
+  });
+  const name = options.name ?? `mk-${prefix}-${sequence}`;
+  const valid = (candidate: string | null | undefined) => candidate != null && items.some((item) => item.value === candidate) ? candidate : null;
+  const initial = valid(options.defaultValue !== undefined ? options.defaultValue : options.value);
+  let value = valid(options.value !== undefined ? options.value : initial);
+  const labels: HTMLLabelElement[] = [];
+  const inputs: HTMLInputElement[] = [];
+  for (const item of items) {
+    const label = part('label', group, 'option');
+    const input = part('input', label, 'input');
+    input.type = 'radio'; input.name = name; input.value = item.value;
+    input.required = Boolean(options.required);
+    input.disabled = Boolean(options.disabled || item.disabled);
+    input.defaultChecked = item.value === initial;
+    const mark = part('span', label, 'mark');
+    mark.setAttribute('aria-hidden', 'true'); mark.textContent = item.symbol ?? '';
+    const copy = part('span', label, 'copy');
+    part('span', copy, 'label').textContent = item.label;
+    if (item.description) part('span', copy, 'description').textContent = item.description;
+    if (options.error) { input.setAttribute('aria-invalid', 'true'); input.setAttribute('aria-describedby', message.id); }
+    labels.push(label); inputs.push(input);
+  }
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-variant', options.variant ?? 'pill');
+  scope.attr(root, 'data-mk-disabled', options.disabled ? '' : null);
+  scope.attr(root, 'data-mk-error', options.error ? '' : null);
+  const paint = (animate: boolean, before: string | null) => {
+    inputs.forEach((input, index) => {
+      input.checked = input.value === value;
+      labels[index]!.toggleAttribute('data-mk-selected', input.checked);
+    });
+    const caption = options.error ?? (items.length ? options.caption?.(value) ?? '' : 'No hay opciones');
+    if (animate && !reduced()) keep(rollDigits(message, caption, Number(value) >= Number(before) ? 1 : -1, 0.28));
+    else message.textContent = caption;
+    const at = (candidate: string | null) => items.findIndex((item) => item.value === candidate);
+    options.decorate?.(labels, at(value), at(before), animate && before !== value && !reduced(), keep);
+  };
+  const choose = (next: string | null, notify = false, animate = true) => {
+    if (scope.disposed) return;
+    const target = valid(next); const before = value;
+    value = target; paint(animate, before);
+    if (before === value) return;
+    const index = items.findIndex((item) => item.value === value);
+    if (animate && index >= 0 && !reduced()) {
+      keep(press(labels[index]));
+      keep(gsap.fromTo(labels[index]!.querySelector(`[data-mk-${prefix}-mark]`), { scale: 0.65, filter: 'blur(4px)' }, { scale: 1, filter: 'blur(0px)', duration: 0.4, ease: EASE.swatch, overwrite: 'auto', clearProps: 'transform,filter' }));
+    }
+    if (notify) {
+      const emitted = value;
+      options.onChange?.(emitted);
+      if (!scope.disposed) root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value: options.eventValue ? options.eventValue(emitted) : emitted } }));
+    }
+  };
+  inputs.forEach((input) => scope.on(input, 'change', () => {
+    if (!input.disabled && !input.matches(':disabled') && input.checked) choose(input.value, true);
+    else paint(false, value);
+  }));
+  const form = inputs[0]?.form;
+  if (form) scope.on(form, 'reset', (event) => {
+    // Reset is cancelable. Run after the browser restores checked/defaultChecked.
+    scope.timeout(() => { if (!scope.disposed && !event.defaultPrevented) choose(initial, false); }, 0);
+  });
+  paint(false, value);
+  keep(blurIn(labels, { from: 'soft', stagger: 0.035, duration: 0.35 }));
+  return { get value() { return value; }, setValue: choose, reset: (notify = false) => choose(initial, notify), destroy: () => scope.dispose() };
+}

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

@@ -0,0 +1,43 @@
+# RatingScale
+
+Una escala de feedback, distinta de star-rating: once opciones numéricas 0–10 para NPS o cinco caras con etiquetas para sentimiento. Una cápsula oscura identifica la respuesta elegida y la cifra/caption cambia con rollDigits.
+
+```ts
+import { createRatingScale } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/rating-scale';
+
+const control = createRatingScale(document.querySelector('.mk-rating-scale'), {
+  name: 'recommend', label: '¿Lo recomendarías?', value: null, onChange: console.log,
+});
+control.setValue(8);
+```
+
+## Opciones y contrato
+
+`variant: numbered | sentiment` (numbered), `min` (0 o 1), `max` (10 o 5), `labels`, `value` / `defaultValue` (null), `name`, `label`, `required`, `disabled`, `error`, `onChange(value)`.
+
+Cero es una respuesta válida; null significa sin respuesta. Los valores se redondean y limitan al rango. La escala admite hasta 21 opciones. mk:change entrega un número o null, también en el elemento personalizado.
+
+La instancia expone `value: number | null`, `setValue(value, notify = false)`, `reset(notify = false)` y `destroy()`. Las escrituras imperativas actualizan el control incluso estando disabled. `setValue` no cambia el valor inicial al que vuelve reset. Las notificaciones usan callbacks y eventos `mk:change` con `detail: { value }`.
+
+## React y HTML
+
+```tsx
+import { RatingScale } from '@yewdiel21/motion-kit/react';
+
+<RatingScale value={score} onChange={setScore} name="recommend" />
+<RatingScale variant="sentiment" value={feeling} onChange={setFeeling} />
+```
+
+`value` controla la instancia; `defaultValue` inicia una instancia que conserva sus propios cambios. Las opciones pueden cambiar sin perder la selección no controlada. `instanceRef` recibe la instancia y admite cambiar de objeto ref. Los children y dangerouslySetInnerHTML no se pasan al host porque el motor posee ese DOM.
+
+```html
+<mk-rating-scale class="mk-rating-scale" name="recommend" label="¿Lo recomendarías?" value="8"></mk-rating-scale>
+```
+
+Registra con `defineRatingScale()` desde `@yewdiel21/motion-kit/elements` o utiliza el auto registro. Los atributos de opciones se pueden cambiar en vivo; el valor imperativo se conserva al cambiar otra opción. `disabled="false"` se lee como false. El elemento expone `value`, `setValue`, `reset`.
+
+## Accesibilidad y lifecycle
+
+Se conserva el input nativo, su etiqueta, teclado, tacto, validación y participación en formularios. El reset de formulario es cancelable; el control espera al reset nativo y verifica defaultPrevented. Movimiento reducido conserva toda la funcionalidad. destroy es idempotente y libera animaciones, eventos y timers, elimina solo las partes creadas y restaura los atributos del host. Los temas utilizan DM Sans y tokens --mk-*; el CSS de este componente es independiente de los otros estilos.
+

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

@@ -0,0 +1,41 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createRatingScale, type RatingScaleInstance } from './engine';
+
+/** Light DOM; attribute changes keep the current imperative value and reset baseline. */
+export class MkRatingScaleElement extends MkElement<RatingScaleInstance> {
+  static options: Record<string, OptionType> = {"min":"number","max":"number","value":"number","variant":"string","labels":"json","label":"string","name":"string","disabled":"boolean","required":"boolean","error":"string"};
+  private baseline: number | null | undefined;
+  private saved: number | null | undefined;
+  protected create(options: Record<string, unknown>) {
+    const created = createRatingScale(this, { ...options, value: this.saved !== undefined ? this.saved : options.value as number | null | undefined, defaultValue: this.baseline });
+    if (this.baseline === undefined) this.baseline = created.value;
+    this.saved = undefined;
+    return created;
+  }
+  disconnectedCallback() {
+    this.saved = this.instance?.value;
+    super.disconnectedCallback();
+  }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next) return;
+    if (name === 'value' && (!this.instance || !this.isConnected)) {
+      this.saved = next === null ? this.baseline ?? null : Number.isFinite(Number(next)) ? Number(next) : this.baseline ?? null;
+      return;
+    }
+    if (!this.instance || !this.isConnected) return;
+    if (name === 'value') {
+      const parsed = next === null ? this.baseline ?? null : Number(next);
+      this.instance.setValue(parsed, false);
+      return;
+    }
+    this.saved = this.instance.value;
+    super.attributeChangedCallback(name, previous, next);
+  }
+  get value(): number | null { return this.instance?.value ?? this.saved ?? null; }
+  set value(next: number | null) { this.setValue(next); }
+  setValue(value: number | null, notify = false) { if (this.instance) this.instance.setValue(value, notify); else this.saved = value; }
+  reset(notify = false) { this.instance?.reset(notify); }
+  
+}
+export const defineRatingScale = () => defineElement('mk-rating-scale', MkRatingScaleElement);
+

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

@@ -0,0 +1,63 @@
+import { gsap, EASE } from '../../core/gsap';
+import { createChoices } from '../radio-group/shared';
+import { inert, type Instance } from '../../core/types';
+
+export interface RatingScaleOptions {
+  /** Inclusive numeric scale; defaults to 0…10, or 1…5 for sentiment. */
+  min?: number; max?: number; value?: number | null; defaultValue?: number | null;
+  variant?: 'numbered' | 'sentiment';
+  labels?: string[]; label?: string; name?: string;
+  disabled?: boolean; required?: boolean; error?: string;
+  onChange?: (value: number | null) => void;
+}
+export interface RatingScaleInstance extends Instance {
+  readonly value: number | null;
+  setValue(value: number | null, notify?: boolean): void;
+  reset(notify?: boolean): void;
+}
+const SENTIMENTS = ['Muy mal', 'Mal', 'Regular', 'Bien', 'Muy bien'];
+const SYMBOLS = ['⌢', '⌢', '−', '⌣', '⌣'];
+export function createRatingScale(root: HTMLElement | null, options: RatingScaleOptions = {}): RatingScaleInstance {
+  if (!root) return inert({ value: null, setValue() {}, reset() {} });
+  const sentiment = options.variant === 'sentiment';
+  const min = Number.isFinite(options.min) ? Math.round(options.min!) : sentiment ? 1 : 0;
+  const max = Number.isFinite(options.max) ? Math.max(min, Math.min(min + 20, Math.round(options.max!))) : sentiment ? min + 4 : min + 10;
+  const labels = options.labels ?? (sentiment ? SENTIMENTS : []);
+  const items = Array.from({ length: max - min + 1 }, (_, i) => ({
+    value: String(min + i), label: labels[i] ?? String(min + i), symbol: sentiment ? SYMBOLS[Math.min(4, Math.round(i / Math.max(1, max - min) * 4))] : String(min + i),
+  }));
+  const normalize = (value: number | null | undefined) => value != null && Number.isFinite(value) ? String(Math.max(min, Math.min(max, Math.round(value)))) : null;
+  const instance = createChoices(root, 'rating-scale', {
+    ...options, variant: sentiment ? 'sentiment' : 'numbered', items, value: normalize(options.value !== undefined ? options.value : options.defaultValue), defaultValue: normalize(options.defaultValue !== undefined ? options.defaultValue : options.value),
+    caption: (value) => value === null ? 'Sin responder' : labels[Number(value) - min] ?? `${value} de ${max}`,
+    eventValue: (value) => value === null ? null : Number(value),
+    onChange: (value) => options.onChange?.(value === null ? null : Number(value)),
+    decorate(labels, index, previous, animate, keep) {
+      // Numbers fill up to the answer, like the equalizer's lit bars.
+      labels.forEach((label, i) => label.toggleAttribute('data-mk-in-range', !sentiment && index >= 0 && i < index));
+      if (!animate || index < 0) return;
+      if (sentiment) {
+        // The chosen face reacts to its mood: positive jumps, neutral wavers, negative nods down.
+        const mood = index / Math.max(1, labels.length - 1) * 2 - 1;
+        const mark = labels[index]!.querySelector('[data-mk-rating-scale-mark]');
+        keep(gsap.timeline()
+          .to(mark, { y: mood > 0 ? -8 * mood : 4 * -mood, rotate: mood === 0 ? 8 : 12 * mood, duration: .14, ease: 'power2.out' })
+          .to(mark, { y: 0, rotate: 0, duration: .55, ease: EASE.click, clearProps: 'y,rotate' }));
+        return;
+      }
+      // A short wave travels from the previous answer to the new one.
+      const from = previous >= 0 ? previous : 0, step = index >= from ? 1 : -1;
+      for (let i = from, k = 0; i !== index; i += step, k++) {
+        keep(gsap.timeline({ delay: Math.min(k * .03, .3) })
+          .to(labels[i]!, { y: -5, duration: .12, ease: 'power2.out' })
+          .to(labels[i]!, { y: 0, duration: .4, ease: EASE.click, clearProps: 'y' }));
+      }
+    },
+  });
+  return {
+    get value() { return instance.value === null ? null : Number(instance.value); },
+    setValue: (value, notify = false) => instance.setValue(normalize(value), notify),
+    reset: (notify = false) => instance.reset(notify),
+    destroy: () => instance.destroy(),
+  };
+}

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

@@ -0,0 +1,22 @@
+:is(.mk-rating-scale, mk-rating-scale) { display: block; min-width: 0; color: var(--mk-text); font: 500 .875rem/1.4 var(--mk-font); }
+[data-mk-rating-scale-body] { display: grid; gap: .875rem; }
+[data-mk-rating-scale-options] { display: flex; flex-wrap: wrap; gap: .375rem; }
+[data-mk-rating-scale-option] { position: relative; flex: 1 0 2.25rem; display: grid; place-items: center; gap: .5rem; min-width: 0; min-height: 44px; border: 1px solid transparent; border-radius: 12px; background: var(--mk-surface-2); cursor: pointer; transition: border-radius .4s var(--mk-ease-swatch), background .2s, color .2s, translate .35s var(--mk-ease-swatch); -webkit-tap-highlight-color: transparent; }
+[data-mk-rating-scale-input] { position: absolute; width: 1px; height: 1px; opacity: 0; }
+[data-mk-rating-scale-mark] { display: grid; place-items: center; width: 100%; min-height: 44px; font-variant-numeric: tabular-nums; }
+[data-mk-rating-scale-copy] { position: absolute; width: 1px; height: 1px; clip-path: inset(50%); overflow: hidden; white-space: nowrap; }
+[data-mk-rating-scale-option][data-mk-in-range] { background: color-mix(in srgb, var(--mk-text) 12%, var(--mk-surface-2)); }
+[data-mk-rating-scale-option][data-mk-selected] { background: var(--mk-text); color: var(--mk-bg); border-radius: 64px; }
+[data-mk-rating-scale-option]:has(:focus-visible) { outline: 2px solid var(--mk-accent); outline-offset: 3px; }
+[data-mk-rating-scale-option]:has(:disabled) { opacity: .4; cursor: not-allowed; }
+[data-mk-rating-scale-message] { min-height: 1.2em; text-align: center; color: var(--mk-muted); font-size: .8125rem; }
+:is(.mk-rating-scale, mk-rating-scale)[data-mk-error] [data-mk-rating-scale-message] { color: var(--mk-error); }
+:is(.mk-rating-scale, mk-rating-scale)[data-mk-variant='sentiment'] [data-mk-rating-scale-options] { gap: .5rem; }
+:is(.mk-rating-scale, mk-rating-scale)[data-mk-variant='sentiment'] [data-mk-rating-scale-option] { padding: .875rem .375rem .65rem; border-radius: 24px; flex-basis: 3rem; }
+:is(.mk-rating-scale, mk-rating-scale)[data-mk-variant='sentiment'] [data-mk-rating-scale-option][data-mk-selected] { border-radius: 32px; }
+:is(.mk-rating-scale, mk-rating-scale)[data-mk-variant='sentiment'] [data-mk-rating-scale-mark] { position: relative; box-sizing: border-box; width: 38px; height: 38px; min-height: 0; padding-top: 10px; border: 1.5px solid currentColor; border-radius: 50%; font: 500 25px/.7 var(--mk-font); }
+:is(.mk-rating-scale, mk-rating-scale)[data-mk-variant='sentiment'] [data-mk-rating-scale-mark]::before { content: '··'; position: absolute; top: -2px; left: 8px; letter-spacing: 5px; font-size: 24px; line-height: 1; }
+:is(.mk-rating-scale, mk-rating-scale)[data-mk-variant='sentiment'] [data-mk-rating-scale-copy] { position: static; width: auto; height: auto; clip-path: none; white-space: normal; text-align: center; font-size: .6875rem; }
+@media (hover: hover) { [data-mk-rating-scale-option]:not(:has(:disabled)):hover { translate: 0 -3px; border-radius: 24px; background: var(--mk-surface-3); } [data-mk-rating-scale-option][data-mk-selected]:hover { background: var(--mk-text); border-radius: 64px; } }
+@media (prefers-reduced-motion: reduce) { [data-mk-rating-scale-option] { transition: none; } }
+@media (forced-colors: active) { [data-mk-rating-scale-option] { border: 1px solid ButtonText; } [data-mk-rating-scale-option][data-mk-selected] { outline: 2px solid Highlight; } }

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

@@ -0,0 +1,60 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createRatingScale, type RatingScaleOptions, type RatingScaleInstance } from './engine';
+
+export interface RatingScaleProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onInput' | 'defaultValue' | 'children' | 'dangerouslySetInnerHTML'>, Omit<RatingScaleOptions, 'value' | 'defaultValue'> {
+  value?: number | null;
+  defaultValue?: number | null;
+  instanceRef?: MutableRefObject<RatingScaleInstance | null>;
+  /** The engine owns this component's DOM. */
+  children?: never;
+  dangerouslySetInnerHTML?: never;
+}
+export function RatingScale({ value, defaultValue, min, max, variant, labels, label, name, disabled, required, error, onChange, instanceRef, className, children: _children, dangerouslySetInnerHTML: _html, ...props }: RatingScaleProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const engine = useRef<RatingScaleInstance | null>(null);
+  const latestValue = useLatest(value);
+  const change = useLatest(onChange);
+  
+  const baseline = useRef(value !== undefined ? value : defaultValue);
+  const current = useRef(baseline.current);
+  const reconcile = () => queueMicrotask(() => {
+    if (latestValue.current !== undefined) engine.current?.setValue(latestValue.current, false);
+  });
+  useIsomorphicLayoutEffect(() => {
+    const created = createRatingScale(root.current, {
+      min, max, variant, labels, label, name, disabled, required, error, value: latestValue.current !== undefined ? latestValue.current : current.current, defaultValue: baseline.current,
+      onChange: (next) => { change.current?.(next); reconcile(); },
+      
+    });
+    engine.current = created;
+    const form = root.current?.closest('form');
+    const pending = new Set<ReturnType<typeof setTimeout>>();
+    const reset = (event: Event) => {
+      const timer = setTimeout(() => {
+        pending.delete(timer);
+        if (!event.defaultPrevented && latestValue.current !== undefined) created.setValue(latestValue.current, false);
+      }, 0);
+      pending.add(timer);
+    };
+    form?.addEventListener('reset', reset);
+    return () => {
+      form?.removeEventListener('reset', reset);
+      pending.forEach((timer) => clearTimeout(timer));
+      current.current = created.value; created.destroy(); engine.current = null;
+    };
+    // Callbacks and controlled value are read through refs.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [min, max, variant, labels, label, name, disabled, required, error]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined) engine.current?.setValue(value, false);
+  });
+  useIsomorphicLayoutEffect(() => {
+    if (!instanceRef) return;
+    instanceRef.current = engine.current;
+    return () => { instanceRef.current = null; };
+  }, [instanceRef, min, max, variant, labels, label, name, disabled, required, error]);
+  return <div {...props} ref={root} className={['mk-rating-scale', className].filter(Boolean).join(' ')} />;
+}
+

package/src/components/scroll-preview-dock/README.md

@@ -0,0 +1,24 @@
+# Scroll preview dock
+
+Section links with thumbnails, a travelling selected pill and an adjacent hover/focus preview. Selection follows the actual scroll position in the supplied scroller.
+
+```ts
+const dock = createScrollPreviewDock(document.querySelector('#dock'), {
+  scroller: document.querySelector('#story'),
+  offset: 12,
+  items: [
+    { id: 'idea', label: 'La idea', description: 'Un punto de partida', thumbnail: '/idea.webp' },
+    { id: 'shape', label: 'La forma', thumbnail: '/shape.webp' },
+  ],
+});
+dock.select('shape');
+dock.destroy();
+```
+
+Exports: `createScrollPreviewDock`, `ScrollPreviewDockItem`, `ScrollPreviewDockOptions`, `ScrollPreviewDockInstance`; React `ScrollPreviewDock`, `ScrollPreviewDockProps`; elements `MkScrollPreviewDockElement`, `defineScrollPreviewDock` (`mk-scroll-preview-dock`). CSS: `scroll-preview-dock.css` plus kit tokens/theme/fonts.
+
+Options: `items`, `scroller` (element/selector, otherwise window), `offset` (pixels), `label`, `disabled`, `onChange(id)`. Each item has `id`, `label`, optional `description`, `thumbnail`, `section` (element/selector, defaults to the element with that ID), `disabled`. Give each target section a real `id` to preserve native fragment-link behavior. Missing sections leave a working native link and do not initiate scripted scrolling.
+
+Instance: `select(id)`, `update()`, `setOptions(partial)`, readonly `value`, `destroy()`. `mk:change` emits `{value}` for the tracked section. Hover/focus changes only the preview. ArrowLeft/ArrowRight and Home/End move focus among enabled links; normal Tab/Enter and modified link clicks retain native semantics. Wheel/touch interrupts scripted scrolling. Reduced motion jumps immediately.
+
+React owns an empty host and accepts data through `items`, with optional `instanceRef`; children/HTML are ignored at runtime. An element accepts JSON `items`, scalar attributes and `setOptions`, `items`, `select`/`update` methods. Updates retain the engine and restore focus to a surviving link. Destroy removes listeners, pending animation frames and scroll tweens, restoring authored content.

package/src/components/scroll-preview-dock/element.ts

@@ -0,0 +1,20 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createScrollPreviewDock, type ScrollPreviewDockInstance, type ScrollPreviewDockOptions, type ScrollPreviewDockItem } from './engine';
+
+export class MkScrollPreviewDockElement extends MkElement<ScrollPreviewDockInstance> {
+  static options: Record<string, OptionType> = {"items":"json","scroller":"string","offset":"number","label":"string","disabled":"boolean"};
+  protected create(options: Record<string, unknown>) { return createScrollPreviewDock(this, options); }
+  setOptions(options: Partial<ScrollPreviewDockOptions>) { this.instance?.setOptions(options); }
+
+  select(id: string) { this.instance?.select(id); }
+  update() { this.instance?.update(); }
+  get value() { return this.instance?.value ?? ''; }
+  set items(value: ScrollPreviewDockItem[]) { this.instance?.setOptions({ items: value }); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const option = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    const defaults: Record<string, unknown> = {"items":[],"scroller":null,"offset":0,"label":"Explorar secciones","disabled":false};
+    this.instance.setOptions({ [option]: this.options[option] ?? defaults[option] });
+  }
+}
+export const defineScrollPreviewDock = () => defineElement('mk-scroll-preview-dock', MkScrollPreviewDockElement);