@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/scratch-card/scratch-card.css

@@ -0,0 +1,74 @@
+/* scratch-card — a Melonmind card (20 px radius) whose content hides under a metallic cover; a small glass
+   "Revelar" pill sits on top for the keyboard. */
+.mk-scratch-card,
+mk-scratch-card {
+  position: relative;
+  display: block;
+  overflow: hidden;
+  border-radius: 20px;
+  background: var(--mk-surface-1);
+  box-shadow: inset 0 0 0 1px var(--mk-outline-soft);
+  isolation: isolate;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-content] {
+  position: relative;
+  min-height: 9rem;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-cover] {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  cursor: crosshair;
+  touch-action: none;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-cover] canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-cover][data-mk-scratch-fallback] {
+  display: grid;
+  place-items: center;
+  background: linear-gradient(135deg, #c9ccd2, #eef0f3 45%, #d7dadf 55%, #a9adb5);
+  color: rgb(40 42 48 / 0.75);
+  font-weight: 600;
+  cursor: default;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-cover][hidden] {
+  display: none;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-reveal] {
+  position: absolute;
+  right: 0.75rem;
+  bottom: 0.75rem;
+  z-index: 2;
+  min-height: 2.25rem;
+  padding: 0 0.9rem;
+  border: 0;
+  border-radius: 64px;
+  background: rgb(20 21 24 / 0.72);
+  box-shadow:
+    inset 1px 1px 1px rgb(255 255 255 / 0.14),
+    inset -1px -1px 1px rgb(255 255 255 / 0.05);
+  backdrop-filter: blur(12px);
+  color: #fff;
+  font: inherit;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-reveal]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-reveal][hidden] {
+  display: none;
+}

package/src/components/skeleton/README.md

@@ -0,0 +1,15 @@
+# skeleton
+
+Marcador de carga para texto, avatar, imagen o tarjeta. El placeholder es decorativo (`aria-hidden`) y el root marca `aria-busy` con un estado oculto que nombra lo que carga. El contenido real queda oculto sólo mientras carga.
+
+```html
+<mk-skeleton class="mk-skeleton" shape="card" animation="shimmer" label="Cargando perfil">
+  <article data-mk-skeleton-content>…contenido real…</article>
+</mk-skeleton>
+```
+
+Con `[data-mk-skeleton-placeholder]` propio se usa ese marcado; sin él, el motor crea los huesos de `shape`. `defineElements()` (atributo `loaded` para terminar), `createSkeleton(root, options)` o `<Skeleton loading={pending} shape="avatar" label="Cargando autor"><Author /></Skeleton>`.
+
+Opciones: `loading=true`, `animation='pulse'|'shimmer'|'none'`, `shape='text'|'avatar'|'image'|'card'`, `lines=3` (texto), `label='Cargando'`. API: `setLoading(boolean)`, `loading`, `destroy()`; evento `mk:loading` con `{loading}`. `skeletonBones(shape, lines)` devuelve los huesos para dibujar el mismo placeholder desde otro framework.
+
+El contenido que el autor ya tenía `hidden` sigue oculto al terminar. En React, placeholder y contenido son subárboles distintos de React; el motor sólo cambia `hidden` y el estado. `destroy()` quita lo generado y restaura atributos. Variables: `--mk-skeleton-bone`, `--mk-skeleton-sheen`, `--mk-skeleton-radius`, `--mk-skeleton-duration` (1.6s). Movimiento reducido: superficie estática, sin pulso ni brillo.

package/src/components/skeleton/element.ts

@@ -0,0 +1,32 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSkeleton, type SkeletonInstance } from './engine';
+
+/**
+ * <mk-skeleton class="mk-skeleton" shape="card" label="Cargando perfil">
+ *   <article data-mk-skeleton-content>…</article>
+ * </mk-skeleton>
+ * Loading until `loaded` is set (or `setLoading(false)`); a placeholder is made from `shape`.
+ */
+export class MkSkeletonElement extends MkElement<SkeletonInstance> {
+  static options: Record<string, OptionType> = { loaded: 'boolean', animation: 'string', shape: 'string', lines: 'number', label: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    return createSkeleton(this, { ...options, loading: !options.loaded });
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'loaded') this.instance.setLoading(next === null || next === 'false');
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  setLoading(loading: boolean) {
+    this.instance?.setLoading(loading);
+  }
+
+  get loading() {
+    return this.instance?.loading ?? false;
+  }
+}
+
+export const defineSkeleton = () => defineElement('mk-skeleton', MkSkeletonElement);

package/src/components/skeleton/engine.ts

@@ -0,0 +1,104 @@
+import type { gsap } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { blurIn } from '../../motion/micro';
+
+/*
+ * Skeleton: a decorative placeholder ([data-mk-skeleton-placeholder], made from
+ * `shape` when absent) stands in for the real content ([data-mk-skeleton-content])
+ * while loading. The root is aria-busy and a hidden status names what loads; the
+ * placeholder is aria-hidden. Content the author hid stays hidden. Pulse and
+ * shimmer are CSS; reduced motion keeps a still surface.
+ */
+
+export type SkeletonShape = 'text' | 'avatar' | 'image' | 'card';
+export type SkeletonAnimation = 'pulse' | 'shimmer' | 'none';
+
+export interface SkeletonOptions {
+  loading?: boolean;
+  animation?: SkeletonAnimation;
+  /** Placeholder made when the markup has none. */
+  shape?: SkeletonShape;
+  /** Text lines of a generated text placeholder (default 3). */
+  lines?: number;
+  /** Announced while loading (default 'Cargando'). */
+  label?: string;
+}
+
+export interface SkeletonInstance extends Instance {
+  setLoading(loading: boolean): void;
+  readonly loading: boolean;
+}
+
+/** Bones of each shape: block (image), circle (avatar), line (text). */
+export function skeletonBones(shape: SkeletonShape, lines = 3): Array<'block' | 'circle' | 'line' | 'short'> {
+  const count = Math.max(1, Math.round(lines) || 1);
+  const text = Array.from({ length: count }, (_, i) => (i === count - 1 && count > 1 ? 'short' : 'line') as 'line' | 'short');
+  if (shape === 'avatar') return ['circle', 'line', 'short'];
+  if (shape === 'image') return ['block'];
+  if (shape === 'card') return ['block', 'line', 'short'];
+  return text;
+}
+
+export function createSkeleton(root: HTMLElement | null, options: SkeletonOptions = {}): SkeletonInstance {
+  if (!root) return inert({ setLoading() {}, loading: false });
+  const scope = createScope();
+  const shape = options.shape ?? 'text';
+  const animation = options.animation ?? 'pulse';
+  let loading = options.loading ?? true;
+
+  let placeholder = root.querySelector<HTMLElement>('[data-mk-skeleton-placeholder]');
+  if (!placeholder) {
+    const made = document.createElement('div');
+    made.dataset.mkSkeletonPlaceholder = '';
+    made.dataset.mkShape = shape;
+    for (const bone of skeletonBones(shape, options.lines)) {
+      const element = document.createElement('span');
+      element.dataset.mkBone = bone;
+      made.append(element);
+    }
+    root.prepend(made);
+    scope.add(() => made.remove());
+    placeholder = made;
+  }
+  const contents = [...root.querySelectorAll<HTMLElement>('[data-mk-skeleton-content]')];
+  const authoredHidden = new Map(contents.map((content) => [content, content.hidden]));
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.dataset.mkSkeletonStatus = '';
+  root.append(status);
+  scope.add(() => status.remove());
+
+  scope.attr(placeholder, 'aria-hidden', 'true');
+  scope.attr(root, 'data-mk-shape', shape);
+  scope.attr(root, 'data-mk-animation', animation);
+  scope.attr(root, 'data-mk-ready', '');
+
+  // The reveal animates the content's inline style: the authored one comes back on destroy.
+  for (const content of contents) scope.attr(content, 'style', content.getAttribute('style'));
+  let reveal: gsap.core.Animation | null = null;
+  scope.add(() => reveal?.progress(1).kill());
+  const render = () => {
+    scope.attr(root, 'aria-busy', String(loading));
+    scope.attr(placeholder!, 'hidden', loading ? null : '');
+    for (const content of contents) scope.attr(content, 'hidden', loading || authoredHidden.get(content) ? '' : null);
+    status.textContent = loading ? options.label ?? 'Cargando' : '';
+  };
+  render();
+
+  return {
+    setLoading(next) {
+      if (scope.disposed || next === loading) return;
+      loading = next;
+      render();
+      // Melonmind's list entrance (blur 16, y −20, 50 ms apart) for what was waiting.
+      reveal?.progress(1).kill();
+      if (!loading) reveal = blurIn(contents.filter((content) => !content.hidden), { stagger: 0.05 });
+      root.dispatchEvent(new CustomEvent('mk:loading', { bubbles: true, detail: { loading } }));
+    },
+    get loading() {
+      return loading;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/skeleton/react.tsx

@@ -0,0 +1,41 @@
+'use client';
+import { useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { createSkeleton, skeletonBones, type SkeletonInstance, type SkeletonOptions } from './engine';
+
+export interface SkeletonProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, SkeletonOptions {
+  /** The real content, shown when loading ends. */
+  children?: ReactNode;
+  /** Custom placeholder instead of the shape's bones. */
+  placeholder?: ReactNode;
+}
+
+/**
+ * <Skeleton loading={pending} shape="card" label="Cargando perfil"><ProfileCard /></Skeleton>.
+ * React owns placeholder and content; the engine only toggles hidden and the busy state.
+ */
+export function Skeleton({ loading = true, animation, shape = 'text', lines, label, placeholder, children, className, ...props }: SkeletonProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<SkeletonInstance | null>(null);
+  const current = useRef(loading);
+  current.current = loading;
+  useIsomorphicLayoutEffect(() => {
+    const created = createSkeleton(ref.current, { loading: current.current, animation, shape, lines, label });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+  }, [animation, shape, lines, label]);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setLoading(loading);
+  }, [loading]);
+  return (
+    <div {...props} ref={ref} className={['mk-skeleton', className].filter(Boolean).join(' ')} data-mk-ssr-loading={loading ? '' : undefined}>
+      <div data-mk-skeleton-placeholder="" data-mk-shape={shape}>
+        {placeholder ?? skeletonBones(shape, lines).map((bone, i) => <span key={i} data-mk-bone={bone} />)}
+      </div>
+      <div data-mk-skeleton-content="">{children}</div>
+    </div>
+  );
+}

package/src/components/skeleton/skeleton.css

@@ -0,0 +1,107 @@
+/* skeleton — soft bones on the surface tone; pulse (opacity) or shimmer (a passing sheen). */
+.mk-skeleton,
+mk-skeleton {
+  --mk-skeleton-bone: var(--mk-surface-3);
+  --mk-skeleton-sheen: color-mix(in srgb, var(--mk-surface-1) 80%, transparent);
+  --mk-skeleton-radius: var(--mk-radius-md, 16px);
+  /* Melonmind animation-loading-2: a sheen crossing in 1 s. */
+  --mk-skeleton-duration: 1s;
+  display: block;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-skeleton-placeholder] {
+  display: grid;
+  gap: 0.625rem;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-skeleton-placeholder][hidden],
+:is(.mk-skeleton, mk-skeleton) [data-mk-skeleton-content][hidden] {
+  display: none !important;
+}
+
+/* Before the engine runs (server render), the React state decides what shows. */
+:is(.mk-skeleton, mk-skeleton):not([data-mk-ready])[data-mk-ssr-loading] > [data-mk-skeleton-content],
+:is(.mk-skeleton, mk-skeleton):not([data-mk-ready]):not([data-mk-ssr-loading]) > [data-mk-skeleton-placeholder] {
+  display: none;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-bone] {
+  position: relative;
+  display: block;
+  overflow: hidden;
+  height: 0.875rem;
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-skeleton-bone);
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-bone='short'] {
+  width: 62%;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-bone='circle'] {
+  width: 3.5rem;
+  height: 3.5rem;
+  border-radius: 50%;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-bone='block'] {
+  height: auto;
+  aspect-ratio: 16 / 9;
+  border-radius: var(--mk-skeleton-radius);
+}
+
+/* Avatar: circle beside two lines. */
+:is(.mk-skeleton, mk-skeleton) [data-mk-shape='avatar'] {
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: center;
+  column-gap: 1rem;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-shape='avatar'] [data-mk-bone='circle'] {
+  grid-row: span 2;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-shape='card'] {
+  padding: 0.5rem 0.5rem 1rem;
+  border-radius: var(--mk-radius-lg, 24px);
+  background: var(--mk-surface-1);
+  box-shadow: inset 0 0 0 1px var(--mk-outline-soft);
+}
+
+:is(.mk-skeleton, mk-skeleton)[data-mk-animation='pulse'][aria-busy='true'] [data-mk-bone] {
+  animation: mk-skeleton-pulse var(--mk-skeleton-duration) ease-in-out infinite;
+}
+
+:is(.mk-skeleton, mk-skeleton)[data-mk-animation='shimmer'][aria-busy='true'] [data-mk-bone]::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(90deg, transparent, var(--mk-skeleton-sheen), transparent);
+  transform: translateX(-100%);
+  animation: mk-skeleton-shimmer var(--mk-skeleton-duration) linear infinite;
+}
+
+
+@keyframes mk-skeleton-pulse {
+  50% { opacity: 0.45; }
+}
+
+@keyframes mk-skeleton-shimmer {
+  to { transform: translateX(100%); }
+}
+
+@keyframes mk-skeleton-reveal {
+  from { opacity: 0; transform: translateY(4px); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-skeleton, mk-skeleton) [data-mk-bone],
+  :is(.mk-skeleton, mk-skeleton) [data-mk-bone]::after,
+  :is(.mk-skeleton, mk-skeleton) [data-mk-skeleton-content] {
+    animation: none !important;
+  }
+
+  :is(.mk-skeleton, mk-skeleton) [data-mk-bone]::after {
+    display: none;
+  }
+}

package/src/components/split-view/README.md

@@ -0,0 +1,50 @@
+# split-view
+
+Vista dividida en dos áreas con tamaño configurable, lado a lado o una sobre otra. Por dentro usa el divisor de `resizable-panel`: se arrastra (cede como goma en los límites y regresa con un resorte), responde al teclado, cierra un lado de golpe si lo arrastras muy por debajo de su mínimo, y con doble clic vuelve a la proporción inicial. Sus botones cierran cualquiera de los dos lados y lo vuelven a abrir (.3 s, curva swing).
+
+`setRatio()` se desliza hasta la proporción pedida (.45 s, curva signature). Con `stackBelow`, cuando la vista es más angosta que esos píxeles, las áreas se apilan y el divisor gira con ellas. La proporción se puede recordar (`storageKey`).
+
+## HTML / Astro
+
+```html
+<mk-split-view class="mk-split-view" ratio="0.35" stack-below="640" labels="Bandeja,Mensaje" style="height: 28rem">
+  <section>…lista…</section>
+  <section>…mensaje…</section>
+</mk-split-view>
+```
+
+## React
+
+```tsx
+const split = useRef<SplitViewHandle>(null);
+
+<SplitView ref={split} ratio={0.35} stackBelow={640} labels={['Bandeja', 'Mensaje']} onChange={guardar}>
+  {[<Bandeja key="bandeja" />, <Mensaje key="mensaje" />]}
+</SplitView>;
+
+split.current?.toggle('start');
+```
+
+Una `ratio` nueva se desliza hasta ahí.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `orientation` | `orientation` | `'horizontal'` | `'horizontal'`: lado a lado; `'vertical'`: una sobre otra. |
+| `ratio` | `ratio` | `0.5` | Parte de la primera área (0–1). |
+| `min` | `min` | `15` | Tamaño mínimo de cada área, en %. |
+| `collapsible` | `collapsible` | `true` | Qué lados se pueden cerrar: `true` (ambos), `'start'`, `'end'` o `false`. |
+| `stackBelow` | `stack-below` | `0` | Apilar las áreas por debajo de este ancho en px. |
+| `storageKey` | `storage-key` | — | Recordar la proporción en `localStorage`. |
+| `labels` | `labels` | `'Primera área', 'Segunda área'` | Nombres de las áreas (o su `data-label`). |
+| `onChange(ratio)` | — | — | Al terminar un cambio. |
+| `onCollapse(side)` | — | — | `'start'`, `'end'` o `null` al abrirse. |
+
+## API
+
+`setRatio(ratio, animate = true)`, `collapse('start' | 'end')`, `expand()`, `toggle(side)`, `ratio`, `collapsed`, `orientation`, `destroy()`.
+
+## Accesibilidad
+
+El divisor es un `separator` de WAI-ARIA con su valor, su texto y una etiqueta con los nombres de las áreas; ← → (o ↑ ↓) lo mueven, Inicio y Fin lo llevan a los límites e Intro cierra o abre la primera área. Un área cerrada queda oculta también para los lectores de pantalla. Con movimiento reducido los cambios son inmediatos.

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.