@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/scroll-island/react.tsx

@@ -0,0 +1,26 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createScrollIsland, type ScrollIslandOptions } from './engine';
+
+export interface ScrollIslandProps extends HTMLAttributes<HTMLDivElement>, ScrollIslandOptions {}
+
+/**
+ * <ScrollIsland style={{ height: 400, overflow: 'auto' }}>…</ScrollIsland> scrolls its children with the island;
+ * <ScrollIsland page /> puts it on the page (it renders nothing of its own then).
+ */
+export function ScrollIsland({ sections, reach, idle, page, onSection, className, children, ...props }: ScrollIslandProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const section = useLatest(onSection);
+  useIsomorphicLayoutEffect(() => {
+    const created = createScrollIsland(page ? document.documentElement : ref.current, { sections, reach, idle, page, onSection: (name) => section.current?.(name) });
+    return () => created.destroy();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sections, reach, idle, page]);
+  if (page) return null;
+  return (
+    <div {...props} ref={ref} className={['mk-scroll-island', className].filter(Boolean).join(' ')}>
+      {children}
+    </div>
+  );
+}

package/src/components/scroll-island/scroll-island.css

@@ -0,0 +1,110 @@
+/* scroll-island — the scroller's bar hides and a thin pill takes its place while scrolling; near the edge it swells
+   into a dark capsule (iOS-island style) with the percentage and the current section, which can be dragged. */
+.mk-scroll-island,
+mk-scroll-island {
+  display: block;
+}
+
+[data-mk-scroll-island-host] {
+  scrollbar-width: none;
+}
+
+[data-mk-scroll-island-host]::-webkit-scrollbar {
+  display: none;
+}
+
+[data-mk-scroll-island] {
+  position: fixed;
+  z-index: 2147483640;
+  pointer-events: none;
+}
+
+[data-mk-island-rail] {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 1.5rem;
+  cursor: pointer;
+  pointer-events: none;
+}
+
+[data-mk-island-thumb] {
+  position: absolute;
+  top: 0;
+  right: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 4px;
+  overflow: hidden;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--mk-text) 42%, transparent);
+  color: #fff;
+  opacity: 0;
+  transition:
+    opacity 0.25s ease,
+    background-color 0.3s ease,
+    box-shadow 0.3s ease;
+}
+
+[data-mk-scroll-island][data-mk-state='bar'] [data-mk-island-thumb] {
+  opacity: 1;
+}
+
+[data-mk-scroll-island][data-mk-state='island'] [data-mk-island-rail],
+[data-mk-scroll-island][data-mk-state='island'] [data-mk-island-thumb] {
+  pointer-events: auto;
+}
+
+[data-mk-scroll-island][data-mk-state='island'] [data-mk-island-thumb] {
+  background: #0c0c0e;
+  box-shadow:
+    inset 0 0 0 1px rgb(255 255 255 / 0.08),
+    0 12px 30px -8px rgb(0 0 0 / 0.45);
+  opacity: 1;
+  cursor: grab;
+}
+
+[data-mk-scroll-island][data-mk-dragging] [data-mk-island-thumb] {
+  cursor: grabbing;
+}
+
+[data-mk-island-content] {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0 14px;
+  font-family: var(--mk-font);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+  opacity: 0;
+  transition: opacity 0.18s ease;
+}
+
+[data-mk-scroll-island][data-mk-state='island'] [data-mk-island-content] {
+  opacity: 1;
+  transition-delay: 0.1s;
+}
+
+[data-mk-island-section] {
+  max-width: 12rem;
+  overflow: hidden;
+  color: rgb(255 255 255 / 0.68);
+  font-weight: 500;
+  text-overflow: ellipsis;
+}
+
+[data-mk-island-section][hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-island-thumb],
+  [data-mk-island-content] {
+    transition: none;
+  }
+}

package/src/components/select/README.md

@@ -0,0 +1,34 @@
+# select
+
+Qué hace, en una frase.
+
+Origen: archivo del kit y parámetros (tiempos, curvas).
+
+## HTML / Astro
+
+```html
+<mk-select></mk-select>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-select']);
+</script>
+```
+
+## React
+
+```tsx
+<Select />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+
+## Variables CSS
+
+`--mk-select-radius`
+
+## Accesibilidad
+
+Roles, foco y teclado. Con movimiento reducido…

package/src/components/select/element.ts

@@ -0,0 +1,26 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSelect, type SelectInstance } from './engine';
+
+/**
+ * <mk-select class="mk-select" label="Equipo"><select name="equipo">…</select></mk-select>
+ * The select inside gives the options and stays in step (forms post it). Emits mk:change ({value}).
+ */
+export class MkSelectElement extends MkElement<SelectInstance> {
+  static options: Record<string, OptionType> = { value: 'string', name: 'string', label: 'string', placeholder: 'string', disabled: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createSelect(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'value' && next !== null) this.instance.setValue(next, false);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  get value() {
+    return this.instance?.value ?? '';
+  }
+}
+
+export const defineSelect = () => defineElement('mk-select', MkSelectElement);

package/src/components/select/engine.ts

@@ -0,0 +1,267 @@
+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 { press } from '../../motion/micro';
+import { createMenu } from '../menu/engine';
+
+/*
+ * Select: one choice from a list, opened as the kit's menu (it grows out of its
+ * button and its items flow in) instead of the system's list, so it looks and
+ * moves like every other menu. It enhances an authored <select> (hidden, kept in
+ * step: forms post it and its `change` listeners keep working) or builds one from
+ * `options`. The chosen label slides in out of a blur, the chevron turns, typing
+ * a letter on the closed button picks the next option that starts with it, and
+ * ↓ ↑ Enter Space open the menu. Changes made to the select's options (by the app)
+ * show up on their own.
+ */
+
+export interface SelectOption {
+  value: string;
+  label: string;
+  disabled?: boolean;
+  /** A heading the option sits under (an <optgroup>). */
+  group?: string;
+}
+
+export interface SelectOptions {
+  /** The choices; without them, the authored <select> gives them. */
+  options?: SelectOption[];
+  value?: string;
+  /** Form name of the select it builds (an authored one keeps its own). */
+  name?: string;
+  /** Accessible name; the button reads "<label>: <chosen>". */
+  label?: string;
+  /** Text while nothing is chosen (default: the empty option's text, else 'Elige…'). */
+  placeholder?: string;
+  disabled?: boolean;
+  onChange?: (value: string) => void;
+}
+
+export interface SelectInstance extends Instance {
+  setValue(value: string, notify?: boolean): void;
+  setOptions(options: SelectOption[]): void;
+  /** Read the select's options again (changes to them are also noticed on their own). */
+  refresh(): void;
+  open(): void;
+  close(): void;
+  readonly value: string;
+}
+
+const CHEVRON = '<svg aria-hidden="true" data-mk-select-chevron width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M7 10l5 5 5-5"/></svg>';
+const CHECK = '<svg aria-hidden="true" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12.5l4.5 4.5L19 7.5"/></svg>';
+const fold = (text: string) => text.normalize('NFD').replace(/[̀-ͯ]/g, '').toLocaleLowerCase();
+
+/** Fill a select with options (groups become <optgroup>s, in order of first appearance). */
+function fillSelect(select: HTMLSelectElement, list: SelectOption[]) {
+  const groups = new Map<string, HTMLOptGroupElement>();
+  const nodes: Array<HTMLOptionElement | HTMLOptGroupElement> = [];
+  for (const choice of list) {
+    const option = new Option(choice.label, choice.value);
+    option.disabled = Boolean(choice.disabled);
+    if (!choice.group) {
+      nodes.push(option);
+      continue;
+    }
+    let group = groups.get(choice.group);
+    if (!group) {
+      group = document.createElement('optgroup');
+      group.label = choice.group;
+      groups.set(choice.group, group);
+      nodes.push(group);
+    }
+    group.append(option);
+  }
+  select.replaceChildren(...nodes);
+}
+
+export function createSelect(root: HTMLElement | null, options: SelectOptions = {}): SelectInstance {
+  if (!root) return inert({ setValue() {}, setOptions() {}, refresh() {}, open() {}, close() {}, value: '' });
+  registerMotion();
+  const scope = createScope();
+  const made: Element[] = [];
+  scope.add(() => made.forEach((element) => element.remove()));
+
+  let native = root.querySelector<HTMLSelectElement>('select:not([multiple])');
+  if (!native) {
+    native = document.createElement('select');
+    if (options.name) native.name = options.name;
+    root.append(native);
+    made.push(native);
+  } else {
+    // An authored select gets its own options and value back.
+    const select = native;
+    const children = [...select.childNodes];
+    const value = select.value;
+    scope.add(() => {
+      if (select.childNodes.length !== children.length || children.some((node, i) => select.childNodes[i] !== node)) select.replaceChildren(...children);
+      select.value = value;
+    });
+  }
+  const select = native;
+  if (options.options) fillSelect(select, options.options);
+  if (options.value !== undefined) select.value = options.value;
+  scope.attr(select, 'hidden', '');
+  scope.attr(select, 'tabindex', '-1');
+  scope.attr(select, 'aria-hidden', 'true');
+
+  const trigger = document.createElement('button');
+  trigger.type = 'button';
+  trigger.dataset.mkSelectTrigger = '';
+  trigger.setAttribute('aria-haspopup', 'menu');
+  trigger.setAttribute('aria-expanded', 'false');
+  const valueText = document.createElement('span');
+  valueText.dataset.mkSelectValue = '';
+  trigger.append(valueText);
+  trigger.insertAdjacentHTML('beforeend', CHEVRON);
+  select.after(trigger);
+  made.push(trigger);
+
+  const dialog = document.createElement('dialog');
+  dialog.className = 'mk-dialog mk-menu mk-select-menu';
+  dialog.dataset.mkSelectMenu = '';
+  dialog.setAttribute('aria-label', options.label ?? 'Opciones');
+  root.append(dialog);
+  made.push(dialog);
+  scope.attr(root, 'data-mk-ready', '');
+
+  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 choices = () => [...select.options];
+  const buildItems = () => {
+    const nodes: HTMLElement[] = [];
+    const item = (option: HTMLOptionElement) => {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.dataset.mkItem = '';
+      button.dataset.mkValue = option.value;
+      const text = document.createElement('span');
+      text.textContent = option.text;
+      button.append(text);
+      button.insertAdjacentHTML('beforeend', CHECK);
+      if (option.disabled) button.setAttribute('aria-disabled', 'true');
+      return button;
+    };
+    for (const child of select.children) {
+      if (child instanceof HTMLOptGroupElement) {
+        const heading = document.createElement('p');
+        heading.dataset.mkSelectGroup = '';
+        heading.setAttribute('aria-hidden', 'true');
+        heading.textContent = child.label;
+        nodes.push(heading, ...[...child.children].filter((node): node is HTMLOptionElement => node instanceof HTMLOptionElement).map(item));
+      } else if (child instanceof HTMLOptionElement) nodes.push(item(child));
+    }
+    dialog.replaceChildren(...nodes);
+  };
+
+  const placeholderText = () => options.placeholder ?? choices().find((option) => option.value === '')?.text ?? 'Elige…';
+  /** The items are a choice: the menu marks them plain menuitems when it opens. */
+  const markItems = () => {
+    for (const item of dialog.querySelectorAll<HTMLElement>('[data-mk-item]')) {
+      item.setAttribute('role', 'menuitemradio');
+      item.setAttribute('aria-checked', String(item.dataset.mkValue === select.value));
+    }
+  };
+  const paint = () => {
+    const chosen = select.selectedOptions[0];
+    const empty = !chosen || chosen.value === '';
+    valueText.textContent = empty ? placeholderText() : chosen.text;
+    root.toggleAttribute('data-mk-placeholder', empty);
+    if (options.label) trigger.setAttribute('aria-label', `${options.label}: ${valueText.textContent}`);
+    trigger.disabled = Boolean(options.disabled) || select.disabled;
+    markItems();
+  };
+  scope.add(() => root.removeAttribute('data-mk-placeholder'));
+
+  const choose = (value: string, notify: boolean) => {
+    if (value === select.value) return;
+    const before = choices().findIndex((option) => option.value === select.value);
+    select.value = value;
+    if (select.value !== value) return;
+    const after = choices().findIndex((option) => option.value === value);
+    paint();
+    if (!reduced()) {
+      gsap.killTweensOf(valueText);
+      keep(gsap.fromTo(valueText, { y: after >= before ? 6 : -6, opacity: 0, filter: 'blur(4px)' }, { y: 0, opacity: 1, filter: 'blur(0px)', duration: 0.28, ease: EASE.pop, clearProps: 'transform,opacity,filter' }));
+    }
+    if (!notify) return;
+    select.dispatchEvent(new Event('input', { bubbles: true }));
+    select.dispatchEvent(new Event('change', { bubbles: true }));
+    options.onChange?.(value);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value } }));
+  };
+
+  const menu = createMenu(dialog, {
+    triggers: false,
+    onOpen: markItems,
+    onClose: () => trigger.setAttribute('aria-expanded', 'false'),
+    onSelect: (value) => choose(value, true),
+  });
+  scope.add(() => menu.destroy());
+  // The menu's own selection stays inside: listeners on the select hear its change.
+  scope.on(dialog, 'mk:select', (event) => event.stopPropagation());
+
+  const open = () => {
+    if (trigger.disabled || menu.isOpen) return;
+    trigger.setAttribute('aria-expanded', 'true');
+    dialog.style.setProperty('--mk-select-width', `${trigger.offsetWidth}px`);
+    menu.open(trigger);
+  };
+  scope.on(trigger, 'click', () => {
+    if (!reduced()) keep(press(trigger));
+    open();
+  });
+  scope.on(trigger, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    if (key.ctrlKey || key.metaKey || key.altKey) return;
+    if (['ArrowDown', 'ArrowUp', 'Enter', ' '].includes(key.key)) {
+      key.preventDefault();
+      open();
+    } else if (key.key.length === 1 && key.key.trim()) {
+      // Type to pick: the next option (after the chosen one) whose label starts with the letter.
+      const letter = fold(key.key);
+      const list = choices();
+      const from = list.findIndex((option) => option.value === select.value);
+      for (let step = 1; step <= list.length; step++) {
+        const option = list[(from + step) % list.length]!;
+        if (!option.disabled && option.value !== '' && fold(option.text).startsWith(letter)) {
+          choose(option.value, true);
+          break;
+        }
+      }
+    }
+  });
+
+  const refresh = () => {
+    buildItems();
+    paint();
+  };
+  // The app may change the select's options (or its disabled state) itself.
+  if (typeof MutationObserver === 'function') scope.observe(new MutationObserver(() => !scope.disposed && refresh())).observe(select, { childList: true, subtree: true, attributes: true, attributeFilter: ['disabled', 'label'] });
+  refresh();
+
+  return {
+    setValue: (value, notify = true) => choose(value, notify),
+    setOptions(next) {
+      fillSelect(select, next);
+      refresh();
+    },
+    refresh,
+    open,
+    close: () => menu.close(),
+    get value() {
+      return select.value;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/select/react.tsx

@@ -0,0 +1,33 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createSelect, type SelectInstance, type SelectOptions } from './engine';
+
+export interface SelectProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<SelectOptions, 'value'> {
+  /** Controlled value; without it the select keeps its own (defaultValue). */
+  value?: string;
+  defaultValue?: string;
+}
+
+/** <Select label="Equipo" options={teams} value={team} onChange={setTeam} />. */
+export function Select({ options, value, defaultValue, name, label, placeholder, disabled, onChange, className, ...props }: SelectProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<SelectInstance | null>(null);
+  const change = useLatest(onChange);
+  const start = useRef(value ?? defaultValue);
+  const key = JSON.stringify(options ?? null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createSelect(ref.current, { options, value: value ?? start.current, name, label, placeholder, 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
+  }, [key, name, label, placeholder, disabled]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined && instance.current && instance.current.value !== value) instance.current.setValue(value, false);
+  }, [value]);
+  return <div {...props} ref={ref} className={['mk-select', className].filter(Boolean).join(' ')} />;
+}

package/src/components/select/select.css

@@ -0,0 +1,135 @@
+/* select — a 12 px field button (surface-3) with the chosen label and a chevron that turns, opening the kit's menu:
+   a 16 px surface-1 panel with 8 px items, group headings and a check on the chosen one. The label slides in out of a
+   blur when it changes. The <select> it keeps in step is hidden. */
+.mk-select,
+mk-select {
+  display: inline-flex;
+  min-width: 0;
+  max-width: 100%;
+  vertical-align: middle;
+}
+
+:is(.mk-select, mk-select) > select[hidden] {
+  display: none;
+}
+
+[data-mk-select-trigger] {
+  display: inline-flex;
+  flex: 1;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  min-width: 0;
+  height: 2.5rem;
+  padding: 0 0.55rem 0 0.8rem;
+  border: 0;
+  border-radius: 12px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.875rem;
+  text-align: start;
+  cursor: pointer;
+  transition:
+    background-color 0.15s,
+    box-shadow 0.2s;
+}
+
+[data-mk-select-trigger]:hover:not(:disabled),
+[data-mk-select-trigger][aria-expanded='true'] {
+  background: color-mix(in srgb, var(--mk-surface-3) 80%, var(--mk-text) 8%);
+}
+
+[data-mk-select-trigger]:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
+}
+
+[data-mk-select-trigger]:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+
+[data-mk-select-value] {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+:is(.mk-select, mk-select)[data-mk-placeholder] [data-mk-select-value] {
+  color: var(--mk-muted);
+}
+
+[data-mk-select-chevron] {
+  flex: none;
+  color: var(--mk-muted);
+  transition: transform 0.3s cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+[data-mk-select-trigger][aria-expanded='true'] [data-mk-select-chevron] {
+  transform: rotate(180deg);
+}
+
+/* The menu: like the panels of the data table (surface-1, a hairline, 8 px items). */
+.mk-dialog.mk-select-menu {
+  --mk-dialog-bg: var(--mk-surface-1);
+  --mk-dialog-radius: 16px;
+  --mk-dialog-shadow: 0 0 0 1px var(--mk-outline-soft), 0 16px 48px -12px color-mix(in srgb, var(--mk-shadow-color, #000) 35%, transparent);
+  gap: 0.125rem;
+  min-width: max(10rem, var(--mk-select-width, 0px));
+  max-height: min(20rem, 60dvh);
+  padding: 0.375rem;
+  overflow-y: auto;
+  -webkit-backdrop-filter: none;
+  backdrop-filter: none;
+}
+
+.mk-dialog.mk-select-menu [data-mk-item] {
+  flex: none;
+  gap: 0.625rem;
+  min-height: 2.25rem;
+  padding: 0 0.625rem;
+  border-radius: 8px;
+  font-family: inherit;
+  font-size: 0.875rem;
+  font-weight: 500;
+  letter-spacing: normal;
+}
+
+.mk-dialog.mk-select-menu [data-mk-item]:hover,
+.mk-dialog.mk-select-menu [data-mk-item]:focus-visible {
+  background: var(--mk-surface-2);
+}
+
+.mk-dialog.mk-select-menu [data-mk-item] svg {
+  flex: none;
+  margin-left: auto;
+  opacity: 0;
+}
+
+.mk-dialog.mk-select-menu [data-mk-item][aria-checked='true'] {
+  font-weight: 600;
+}
+
+.mk-dialog.mk-select-menu [data-mk-item][aria-checked='true'] svg {
+  opacity: 1;
+}
+
+[data-mk-select-group] {
+  flex: none;
+  margin: 0.375rem 0.625rem 0.125rem;
+  color: var(--mk-muted);
+  font-size: 0.6875rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-select-trigger],
+  [data-mk-select-chevron] {
+    transition: 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);