@yewdiel21/motion-kit 0.10.0 → 0.15.0

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

@@ -0,0 +1,82 @@
+'use client';
+import { forwardRef, useImperativeHandle, useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createTreeView, type TreeNode, type TreeViewInstance, type TreeViewOptions } from './engine';
+
+export interface TreeViewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children' | 'draggable'>, Omit<TreeViewOptions, 'nodes'> {
+  nodes: TreeNode[];
+}
+
+export type TreeViewHandle = Pick<TreeViewInstance, 'expand' | 'collapse' | 'expandAll' | 'collapseAll' | 'reveal' | 'filter'>;
+
+/** <TreeView nodes={tree} checkable checked={ids} onCheck={setIds} search />. */
+export const TreeView = forwardRef<TreeViewHandle, TreeViewProps>(function TreeView(
+  { nodes, checkable, checked, expanded, selected, search, label, loadChildren, renderLabel, searchText, icons, draggable, onSelect, onCheck, onExpand, onMove, className, ...props },
+  handle,
+) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<TreeViewInstance | null>(null);
+  const select = useLatest(onSelect);
+  const check = useLatest(onCheck);
+  const expand = useLatest(onExpand);
+  const load = useLatest(loadChildren);
+  const draw = useLatest(renderLabel);
+  const text = useLatest(searchText);
+  const moved = useLatest(onMove);
+  useImperativeHandle(
+    handle,
+    () => ({
+      expand: (id, animate) => instance.current?.expand(id, animate),
+      collapse: (id, animate) => instance.current?.collapse(id, animate),
+      expandAll: () => instance.current?.expandAll(),
+      collapseAll: () => instance.current?.collapseAll(),
+      reveal: (id) => instance.current?.reveal(id),
+      filter: (query) => instance.current?.filter(query),
+    }),
+    [],
+  );
+  const nodesKey = JSON.stringify(nodes);
+  useIsomorphicLayoutEffect(() => {
+    const created = createTreeView(ref.current, {
+      nodes: JSON.parse(nodesKey) as TreeNode[],
+      checkable,
+      checked,
+      expanded,
+      selected,
+      search,
+      label,
+      loadChildren: loadChildren ? (node) => load.current?.(node) ?? [] : undefined,
+      renderLabel: renderLabel ? (node, element, query) => draw.current?.(node, element, query) : undefined,
+      searchText: searchText ? (node) => text.current?.(node) ?? node.label : undefined,
+      onSelect: (node) => select.current?.(node),
+      onCheck: (ids) => check.current?.(ids),
+      onExpand: (node, open) => expand.current?.(node, open),
+      icons,
+      draggable,
+      onMove: (node, into) => moved.current?.(node, into),
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [checkable, String(search), label, Boolean(loadChildren), Boolean(renderLabel), Boolean(searchText), icons, draggable]);
+  const first = useRef(true);
+  useIsomorphicLayoutEffect(() => {
+    if (first.current) {
+      first.current = false;
+      return;
+    }
+    instance.current?.setNodes(JSON.parse(nodesKey) as TreeNode[]);
+  }, [nodesKey]);
+  const checkedKey = JSON.stringify(checked ?? null);
+  useIsomorphicLayoutEffect(() => {
+    if (checked && instance.current && JSON.stringify([...instance.current.checked].sort()) !== JSON.stringify([...checked].sort())) instance.current.setChecked(checked);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [checkedKey]);
+  useIsomorphicLayoutEffect(() => {
+    if (selected !== undefined && instance.current && instance.current.selected !== selected) instance.current.select(selected);
+  }, [selected]);
+  return <div {...props} ref={ref} className={['mk-tree-view', className].filter(Boolean).join(' ')} />;
+});

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

@@ -0,0 +1,288 @@
+/* tree-view — 2.25rem rows indented 1.25rem a level; a chevron that turns, an 18 px check box (accent when checked, a
+   dash when mixed), an icon and the label; the selected row sits on a 10 px accent-soft pill that glides; the search
+   above on surface-3; matches underlined in the accent. */
+.mk-tree-view,
+mk-tree-view {
+  display: grid;
+  gap: 0.6rem;
+  min-width: 0;
+  color: var(--mk-text);
+}
+
+[data-mk-tree-search] {
+  box-sizing: border-box;
+  width: 100%;
+  height: 2.5rem;
+  padding: 0 0.85rem;
+  border: 0;
+  border-radius: 12px;
+  background: var(--mk-surface-3);
+  color: inherit;
+  font: inherit;
+  outline: none;
+}
+
+[data-mk-tree-search]:focus-visible {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
+}
+
+[data-mk-tree-box] {
+  position: relative;
+  min-width: 0;
+}
+
+[data-mk-tree-pill] {
+  position: absolute;
+  top: 0;
+  right: 0;
+  left: 0;
+  border-radius: 10px;
+  background: var(--mk-accent-soft);
+  opacity: 0;
+  pointer-events: none;
+}
+
+[data-mk-tree],
+[data-mk-tree] [role='group'] {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+[data-mk-tree] [role='group'][hidden],
+[data-mk-tree] [role='treeitem'][hidden] {
+  display: none;
+}
+
+[data-mk-tree] [role='treeitem'] {
+  outline: none;
+}
+
+[data-mk-tree-row] {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+  min-height: 2.25rem;
+  padding: 0 0.5rem 0 calc(0.25rem + var(--mk-tree-depth, 0) * 1.25rem);
+  border-radius: 10px;
+  cursor: pointer;
+  user-select: none;
+  transition: background-color 0.15s ease;
+}
+
+[data-mk-tree-row]:hover {
+  background: color-mix(in srgb, var(--mk-text) 5%, transparent);
+}
+
+[data-mk-tree] [role='treeitem']:focus-visible > [data-mk-tree-row] {
+  box-shadow: inset 0 0 0 2px var(--mk-accent);
+}
+
+[data-mk-tree] [role='treeitem'][aria-selected='true'] > [data-mk-tree-row] {
+  color: var(--mk-on-accent-soft, var(--mk-text));
+  font-weight: 600;
+}
+
+[data-mk-tree] [role='treeitem'][aria-disabled='true'] > [data-mk-tree-row] {
+  color: var(--mk-muted);
+  cursor: not-allowed;
+}
+
+[data-mk-tree-chevron] {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 1.25rem;
+  height: 1.25rem;
+  border-radius: 6px;
+  color: var(--mk-muted);
+  transition: rotate 0.3s cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+[data-mk-tree] [role='treeitem'][aria-expanded='true'] > [data-mk-tree-row] [data-mk-tree-chevron] {
+  rotate: 90deg;
+}
+
+[data-mk-tree-check] {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 1.125rem;
+  height: 1.125rem;
+  border: 1.5px solid var(--mk-outline);
+  border-radius: 5px;
+  color: transparent;
+  transition: background-color 0.2s ease, border-color 0.2s ease, color 0.2s ease;
+}
+
+[data-mk-tree-check] [data-mk-tree-dash] {
+  display: none;
+}
+
+[data-mk-tree] [role='treeitem'][aria-checked='true'] > [data-mk-tree-row] [data-mk-tree-check],
+[data-mk-tree] [role='treeitem'][aria-checked='mixed'] > [data-mk-tree-row] [data-mk-tree-check] {
+  border-color: var(--mk-accent);
+  background: var(--mk-accent);
+  color: var(--mk-on-accent);
+}
+
+[data-mk-tree] [role='treeitem'][aria-checked='mixed'] > [data-mk-tree-row] [data-mk-tree-tick] {
+  display: none;
+}
+
+[data-mk-tree] [role='treeitem'][aria-checked='mixed'] > [data-mk-tree-row] [data-mk-tree-dash] {
+  display: block;
+}
+
+[data-mk-tree-icon] {
+  flex: none;
+  width: 1.25rem;
+  text-align: center;
+}
+
+[data-mk-tree-label] {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+[data-mk-tree-label] mark {
+  background: transparent;
+  color: inherit;
+  font-weight: 700;
+  text-decoration: underline;
+  text-decoration-color: var(--mk-accent);
+  text-decoration-thickness: 2px;
+  text-underline-offset: 3px;
+}
+
+[data-mk-tree-loading] {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-height: 2.25rem;
+  padding-left: calc(1.75rem + var(--mk-tree-depth, 0) * 1.25rem);
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+}
+
+[data-mk-tree-loading]::before {
+  content: '';
+  width: 0.85rem;
+  height: 0.85rem;
+  border: 2px solid currentColor;
+  border-right-color: transparent;
+  border-radius: 50%;
+  animation: mk-tree-spin 0.8s linear infinite;
+}
+
+@keyframes mk-tree-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+[data-mk-tree-empty] {
+  margin: 0;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+}
+
+[data-mk-tree-empty][hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-tree-chevron],
+  [data-mk-tree-check],
+  [data-mk-tree-row] {
+    transition: none;
+  }
+
+  [data-mk-tree-loading]::before {
+    animation: none;
+  }
+}
+
+/* Folder and page icons (icons option): the folder's front opens like a lid with its branch, or under a dragged card. */
+:is([data-mk-tree-folder], [data-mk-tree-page]) {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  width: 1.15rem;
+  height: 1.15rem;
+}
+
+:is([data-mk-tree-folder], [data-mk-tree-page]) svg {
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}
+
+[data-mk-tree-folder-back] {
+  fill: color-mix(in srgb, var(--mk-accent) 70%, var(--mk-surface-1));
+}
+
+[data-mk-tree-folder-front] {
+  fill: var(--mk-accent);
+  transform-box: fill-box;
+  transform-origin: 50% 100%;
+  transition: transform 0.35s cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+[role='treeitem'][aria-expanded='true'] > [data-mk-tree-row] [data-mk-tree-folder-front],
+[role='treeitem'][data-mk-tree-over] > [data-mk-tree-row] [data-mk-tree-folder-front] {
+  transform: skewX(-14deg) scaleY(0.78);
+}
+
+[data-mk-tree-sheet] {
+  fill: var(--mk-surface-3);
+  stroke: var(--mk-outline);
+  stroke-width: 2;
+}
+
+[data-mk-tree-fold] {
+  fill: var(--mk-outline);
+}
+
+/* Dragging: the source row fades, the branch under the card lights up, the card floats with a shadow. */
+[role='treeitem'][data-mk-tree-dragging] > [data-mk-tree-row] {
+  opacity: 0.4;
+}
+
+[role='treeitem'][data-mk-tree-over] > [data-mk-tree-row] {
+  background: color-mix(in srgb, var(--mk-accent) 14%, transparent);
+  box-shadow: inset 0 0 0 1.5px color-mix(in srgb, var(--mk-accent) 55%, transparent);
+}
+
+[data-mk-tree-drag] {
+  position: fixed;
+  z-index: 2147483646;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  max-width: 16rem;
+  padding: 0.45rem 0.75rem;
+  overflow: hidden;
+  border-radius: 10px;
+  background: var(--mk-surface-1);
+  box-shadow:
+    0 0 0 1px var(--mk-outline-soft),
+    0 14px 30px -10px color-mix(in srgb, var(--mk-shadow-color, #000) 45%, transparent);
+  color: var(--mk-text);
+  font-size: 0.875rem;
+  font-weight: 500;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  pointer-events: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-tree-folder-front] {
+    transition: none;
+  }
+}

package/src/components/virtual-list/README.md

@@ -0,0 +1,81 @@
+# virtual-list
+
+Lista optimizada para miles de elementos: en la página solo están las filas visibles y unas cuantas alrededor, y se reciclan al desplazarse. Las alturas pueden ser fijas (`itemHeight`, lo más rápido) o medirse al aparecer, con una estimación para las demás; si una fila de arriba cambia de alto, lo que estás viendo no se mueve.
+
+Mientras te desplazas, una píldora acompaña el borde derecho con la posición («1 240 de 10 000») y se va con un blur cuando paras. `scrollToIndex()` se desliza hasta la fila (.6 s, curva signature; en un salto largo, recorre de golpe casi todo el camino y desliza el final) y la hace destellar. Con `selectable`, la lista es un `listbox`: un anillo se desliza entre filas al usar el teclado y la palomita de la fila elegida hace pop. `onEndReached()` trae más filas al llegar al final (una fila «Cargando…» mientras tanto y «No hay más elementos» cuando ya no hay). Las primeras filas entran en cascada desde un blur.
+
+## HTML / Astro
+
+```html
+<mk-virtual-list class="mk-virtual-list" item-height="44" selectable="multiple" label="Contactos"
+  items='["Ana Gómez","Luis Peña","Sofía Ruiz"]'></mk-virtual-list>
+
+<script>
+  const list = document.querySelector('mk-virtual-list');
+  // Filas más ricas: dibuja cada una (se reciclan, así que dibújala completa cada vez).
+  list.instance.setRenderer((person, index, row) => {
+    row.innerHTML = '';
+    const name = document.createElement('strong');
+    name.textContent = person;
+    row.append(name);
+  });
+  list.instance.scrollToIndex(1500, { align: 'center' });
+</script>
+```
+
+También lee una `<ul>` escrita dentro, con una fila de texto por `<li>`.
+
+## React
+
+```tsx
+const list = useRef<VirtualListHandle>(null);
+
+<VirtualList
+  ref={list}
+  items={contactos}
+  itemHeight={56}
+  selectable="multiple"
+  onSelect={(keys) => setElegidos(keys)}
+  renderItem={(contacto) => <Contacto {...contacto} />}
+  onEndReached={() => api.siguientePagina()}
+/>;
+
+list.current?.scrollToIndex(5000);
+```
+
+React dibuja solo las filas visibles; el motor las coloca, las mide y decide cuáles van.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `items` | `items` (JSON) | la `<ul>` escrita | Las filas (cualquier valor). |
+| `itemHeight` | `item-height` | — | Alto fijo de cada fila; sin él, las filas se miden. |
+| `estimatedHeight` | `estimated-height` | `itemHeight` o `48` | Alto supuesto de una fila sin medir. |
+| `overscan` | `overscan` | `6` | Filas extra dibujadas a cada lado. |
+| `renderItem(item, index, row)` | — | su texto | Dibuja una fila (en React, `renderItem(item, index)` devuelve el contenido). |
+| `itemText(item)` | — | `label`, `title`, `name` o el valor | El texto de una fila: dibujo por defecto, salto al escribir y anuncios. |
+| `getKey(item, index)` | — | su `id`, o el índice | Clave estable de una fila. |
+| `selectable` | `selectable` | `false` | `true` o `'single'`: una; `'multiple'`: varias (clic alterna, Mayús toma un rango). |
+| `selected` | `selected` (lista con comas) | `[]` | Claves elegidas. |
+| `label` | `label` | `'Lista'` | Nombre accesible. |
+| `emptyLabel` | `empty-label` | `'Sin elementos'` | Texto sin filas. |
+| `onSelect(keys, items)` | — | — | Cambió lo elegido. |
+| `onActivate(item, index)` | — | — | Intro o doble clic en una fila. |
+| `onEndReached()` | — | — | Más filas al final: resuelve con ellas, con `[]` cuando no hay más, o sin nada si tú las agregas a `items` (lo natural en React). Con la lista vacía, pide la primera página. |
+
+## API y eventos
+
+`setItems(items)`, `append(items)`, `scrollToIndex(index, { align: 'auto' \| 'start' \| 'center' \| 'end', animate = true })`, `refresh()`, `select(keys)`, `setRenderer(fn)`, `items`, `range`, `selected`, `container`, `destroy()`. Evento `mk:select` con `{ keys, items }`. El núcleo de ventanas (`createSizes`) también se exporta.
+
+## Variables CSS
+
+`--mk-vl-height` (alto visible, `24rem`).
+
+## Teclado
+
+En una lista elegible: ↑ ↓, Re Pág, Av Pág, Inicio y Fin mueven el anillo; Espacio elige; Intro elige y activa; Mayús + flechas amplía en modo múltiple, y escribir salta a la fila que empieza así. Una lista que no es elegible se desplaza con las teclas de siempre.
+
+## Accesibilidad
+
+Cada fila dice su posición en el total (`aria-posinset` y `aria-setsize`), aunque no estén todas en la página. En modo elegible, el foco se queda en la lista y `aria-activedescendant` apunta a la fila activa, que siempre está dibujada. Un estado discreto anuncia lo elegido y las filas que llegan. Con movimiento reducido no hay deslizamientos, destellos ni cascadas.

package/src/components/virtual-list/element.ts

@@ -0,0 +1,42 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createVirtualList, type VirtualListInstance } from './engine';
+
+/**
+ * <mk-virtual-list class="mk-virtual-list" item-height="44" selectable="multiple" items='["Uno","Dos", …]'></mk-virtual-list>
+ * Or an authored <ul><li>…</li></ul>. element.instance.setRenderer((item, i, row) => …) draws richer rows.
+ * Emits mk:select ({keys, items}).
+ */
+export class MkVirtualListElement extends MkElement<VirtualListInstance> {
+  static options: Record<string, OptionType> = {
+    items: 'json',
+    itemHeight: 'number',
+    estimatedHeight: 'number',
+    overscan: 'number',
+    selectable: 'string',
+    selected: 'list',
+    label: 'string',
+    emptyLabel: 'string',
+    locale: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    // selectable="" or "true" → one at a time; "multiple" → several.
+    const raw = this.getAttribute('selectable');
+    const selectable = raw === null || raw === 'false' ? false : raw === 'multiple' ? 'multiple' : 'single';
+    return createVirtualList(this, { ...options, selectable });
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'items') {
+      try {
+        this.instance.setItems(JSON.parse(next ?? '[]') as unknown[]);
+      } catch {
+        // Malformed JSON: keep the current rows.
+      }
+    } else if (name === 'selected') this.instance.select((next ?? '').split(',').map((key) => key.trim()).filter(Boolean));
+    else super.attributeChangedCallback(name, previous, next);
+  }
+}
+
+export const defineVirtualList = () => defineElement('mk-virtual-list', MkVirtualListElement);