@yewdiel21/motion-kit 0.14.0 → 0.16.0

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/toolbar/README.md

@@ -0,0 +1,46 @@
+# toolbar
+
+Barra de herramientas con selector elástico tipo slime, etiquetas flotantes y navegación con flechas.
+
+## Instalación
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { Toolbar } from '@yewdiel21/motion-kit/react';
+```
+
+```sh
+npx @yewdiel21/motion-kit add toolbar --react --elements
+```
+
+## React
+
+```tsx
+<Toolbar value={tool} onChange={setTool} aria-label="Herramientas"><button data-mk-tool="draw" aria-label="Dibujar">✎</button><button data-mk-tool="erase" aria-label="Borrar">⌫</button></Toolbar>
+```
+
+Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
+
+## HTML / Astro
+
+```html
+<mk-toolbar aria-label="Herramientas" value="draw"><button data-mk-tool="draw" aria-label="Dibujar">✎</button><button data-mk-tool="erase" aria-label="Borrar">⌫</button></mk-toolbar>
+<script type="module">
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-toolbar']);
+</script>
+```
+
+En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createToolbar } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
+
+## Opciones
+
+value: data-mk-tool elegido. orientation: vertical (por defecto) u horizontal. tips: etiquetas (true). onChange(value): selección del usuario. Instancia: setValue(value, notify?), value.
+
+Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
+
+## Estilos y accesibilidad
+
+Variables: --mk-toolbar-tool, --mk-toolbar-rail, --mk-toolbar-blob, --mk-toolbar-on-rail, --mk-toolbar-on-blob.
+
+Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.

package/src/components/toolbar/element.ts

@@ -0,0 +1,30 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createToolbar, type ToolbarInstance } from './engine';
+
+/**
+ * <mk-toolbar class="mk-toolbar" aria-label="Herramientas" value="lapiz">
+ *   <button data-mk-tool="lapiz" aria-label="Lápiz">…svg…</button> …
+ * </mk-toolbar>
+ * The chosen tool's blob stretches like slime to the next one. Emits mk:change ({value}).
+ */
+export class MkToolbarElement extends MkElement<ToolbarInstance> {
+  static options: Record<string, OptionType> = { value: 'string', orientation: 'string', tips: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createToolbar(this, options);
+  }
+
+  get value() {
+    return this.instance?.value ?? '';
+  }
+
+  set value(next: string) { this.instance?.setValue(next); }
+  setValue(value: string, notify = false) { this.instance?.setValue(value, notify); }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (name === 'value' && this.instance) { if (next !== null) this.instance.setValue(next); return; }
+    super.attributeChangedCallback(name, previous, next);
+  }
+}
+
+export const defineToolbar = () => defineElement('mk-toolbar', MkToolbarElement);