@yewdiel21/motion-kit 0.16.0 → 0.17.0

package/src/components/drilldown-menu/README.md

@@ -0,0 +1,163 @@
+# Drilldown Menu
+
+A hierarchical action menu that shows one level at a time. Opening a branch slides the new level in from the right through a 6 px blur; going back reverses the direction. Motion uses the kit's signature curve over 360 ms. The engine keeps one live menu, cancels interrupted motion, and honors reduced motion.
+
+## Vanilla
+
+```html
+<div id="actions" class="mk-drilldown-menu"></div>
+```
+
+```ts
+import { createDrilldownMenu, type DrilldownMenuItem } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css';
+
+const items: DrilldownMenuItem[] = [
+  {
+    id: 'project', label: 'Project', description: 'Manage your workspace',
+    children: [{
+      id: 'share', label: 'Share',
+      children: [
+        { id: 'link', label: 'Copy link', description: 'Anyone with the link can view' },
+        { id: 'invite', label: 'Invite people', disabled: true },
+      ],
+    }],
+  },
+  { id: 'help', label: 'Help' },
+];
+
+const menu = createDrilldownMenu(document.querySelector('#actions'), {
+  items,
+  label: 'Workspace actions',
+  onSelect: (item, path) => console.log(item.label, path),
+  onPathChange: (path) => console.log('Level', path),
+});
+
+menu.open('project');
+menu.open('share');
+menu.back();
+menu.root(); // reset() also returns to the root
+menu.setPath(['project', 'share']);
+menu.setItems(items);
+menu.update({ label: 'Quick actions', emptyText: 'No available actions' });
+// When the component is removed:
+menu.destroy();
+```
+
+Use `@yewdiel21/motion-kit/css/components/drilldown-menu` for just this component's styles; theme tokens must already be present. The root needs `mk-drilldown-menu`; the custom element receives the same styles directly.
+
+## React
+
+```tsx
+import { useState } from 'react';
+import { DrilldownMenu } from '@yewdiel21/motion-kit/react';
+import type { DrilldownMenuItem } from '@yewdiel21/motion-kit';
+
+function Actions({ items }: { items: DrilldownMenuItem[] }) {
+  const [path, setPath] = useState<string[]>([]);
+  const [selection, setSelection] = useState('Choose an action');
+  return <>
+    <DrilldownMenu
+      items={items}
+      label="Workspace actions"
+      path={path}
+      onPathChange={setPath}
+      onSelect={(item) => setSelection(item.label)}
+    />
+    <p role="status">{selection}</p>
+  </>;
+}
+```
+
+Omit `path` for internal navigation; use `defaultPath` to choose its initial level. Passing `path` makes navigation controlled: `onPathChange` requests the next branch path, and the parent accepts it by updating the prop. A parent that keeps the previous path declines the request. Invalid paths are safely truncated to their valid prefix. Updating `items` retains a valid path and focused action; removing or disabling an ancestor returns to the nearest valid parent and reports the repaired path.
+
+`DrilldownMenuProps` also accepts normal `<div>` attributes, excluding children and the native `onSelect`. A forwarded `DrilldownMenuHandle` exposes `open`, `back`, `root`, `reset`, `setPath`, and `focusItem`. In controlled mode the `path` prop remains authoritative over ref-driven navigation.
+
+## Custom element
+
+```ts
+import { defineDrilldownMenu, type MkDrilldownMenuElement } from '@yewdiel21/motion-kit/elements';
+defineDrilldownMenu(); // safe to call more than once
+
+const element = document.querySelector<MkDrilldownMenuElement>('mk-drilldown-menu')!;
+element.items = items; // may also be assigned before connection
+element.path = ['project'];
+element.addEventListener('mk:select', (event) => {
+  console.log((event as CustomEvent).detail); // { item, path }
+});
+```
+
+```html
+<mk-drilldown-menu
+  label="Workspace actions"
+  back-label="Previous level"
+  empty-text="No available actions"
+  items='[{"id":"project","label":"Project","children":[{"id":"share","label":"Share","children":[{"id":"link","label":"Copy link"}]}]}]'
+  path='["project"]'
+></mk-drilldown-menu>
+```
+
+`items` and `path` attributes accept JSON arrays and update the live instance; malformed JSON leaves the last valid value intact. `items`/`path` properties and `setItems`/`setPath` methods accept arrays directly. `open`, `back`, `root`, `reset`, and `focusItem` forward to the live engine. The `instance` property is null while disconnected. Reconnecting creates a fresh instance from the current attributes/properties. The element uses light DOM, so inherited themes apply.
+
+## Data and API
+
+```ts
+interface DrilldownMenuItem {
+  id: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  children?: DrilldownMenuItem[];
+}
+```
+
+IDs must be unique among siblings. The same ID may appear in unrelated levels. A `children` array marks a branch; `children: []` opens an empty level. An item without children is an action. Labels/descriptions are inserted as text; they never execute HTML. Input data and returned item arrays are copied, so the engine does not mutate application data. Supply finite, acyclic data.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `items` | `[]` | Root actions and branches |
+| `path` | `[]` | Initial branch IDs (engine); controlled branch IDs (React) |
+| `label` | `Actions` | Root heading and accessible menu name |
+| `backLabel` | `Back` | Accessible name of the back button |
+| `emptyText` | `No actions available` | Empty-level status |
+| `onSelect(item, path)` | — | Leaf action and full ID path, including the leaf |
+| `onPathChange(path)` | — | User/programmatic navigation or a repaired data path |
+
+`DrilldownMenuInstance` exposes:
+
+| Member | Behavior |
+| --- | --- |
+| `open(id): boolean` | Opens a current-level enabled branch and focuses its first action |
+| `back(): boolean` | Returns one level and restores focus to its parent branch |
+| `root()` / `reset()` | Returns to the root; keeps focus inside if it was inside |
+| `setPath(path, notify = false)` | Navigates to a valid prefix; optional path callback/event |
+| `setItems(items)` | Replaces root data, repairs invalid paths and preserves focus |
+| `update(options)` | Updates data, path, text and callbacks together |
+| `focusItem(id)` | Focuses an enabled current-level item |
+| `path` | Copy of the current branch ID path |
+| `items` | Copy of the current level's items |
+| `element` | Original root element |
+| `destroy()` | Cancels motion, removes listeners, restores original child nodes/attributes; idempotent |
+
+`open`, `back`, `root`, and `reset` notify on a changed path. Explicit `setPath` and `update({ path })` are silent by default. `setItems` reports a path repaired by removed/disabled/non-branch ancestors. `mk:path-change` bubbles with `{ path }`; `mk:select` bubbles with `{ item, path }`. Callbacks receive the same information. Choosing an action leaves the menu at its current level.
+
+## Keyboard and accessibility
+
+The current level has `role="menu"`, named by its visible header. Each action is a button with `role="menuitem"`; its label provides its accessible name and its description is referenced separately. Branches expose `aria-haspopup="menu"`. Disabled actions use both native `disabled` and `aria-disabled` and are skipped by focus navigation. Header/back and ancestor breadcrumbs sit outside the menu. The current breadcrumb uses `aria-current="location"`.
+
+| Key | Action |
+| --- | --- |
+| Up / Down | Previous / next enabled item, wrapping |
+| Home / End | First / last enabled item |
+| Enter / Space | Open branch or choose leaf action |
+| Right | Open a focused branch |
+| Left / Escape | Return one level and focus the branch you came from |
+| Tab / Shift+Tab | Normal page navigation through header/crumb controls and one roving menu stop |
+
+At the root, Left/Escape are left available to a containing surface. Empty and all-disabled levels keep the menu itself focusable so the back keys work. The initial render does not take focus; opening a branch intentionally focuses the new level. Updates preserve focus only when focus was already inside. Reduced-motion users receive immediate navigation without slide, blur or animated height.
+
+## Styling
+
+The component inherits `--mk-text`, `--mk-muted`, `--mk-surface-1`, `--mk-surface-3`, `--mk-outline-soft`, and `--mk-accent`. Override `--mk-drilldown-radius` (28 px) and `--mk-drilldown-item-radius` (18 px) for corner shapes. Width is fluid up to 26 rem; override `max-width` on the root for wider panels. Labels wrap, breadcrumbs wrap, and descriptions remain readable in narrow surfaces.
+
+This is an inline hierarchical action menu. Place it in an existing dialog/popover if you need an anchored or dismissible surface. It does not route to URLs, fetch children, virtualize data, or provide typeahead.

package/src/components/drilldown-menu/drilldown-menu.css

@@ -0,0 +1,129 @@
+/* Drilldown menu: a single live level travels in the navigation direction. */
+.mk-drilldown-menu,
+mk-drilldown-menu {
+  --mk-drilldown-radius: 28px;
+  --mk-drilldown-item-radius: 18px;
+  display: block;
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 26rem;
+  min-width: 0;
+  padding: 10px;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: var(--mk-drilldown-radius);
+  background: var(--mk-surface-1);
+  color: var(--mk-text);
+  font-family: var(--md-sys-typescale-body-large-font, inherit);
+  box-shadow: 0 12px 36px -20px rgb(0 0 0 / 0.25);
+}
+
+[data-mk-drilldown-header] {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-height: 48px;
+  padding: 4px 10px;
+}
+
+[data-mk-drilldown-heading] {
+  min-width: 0;
+  overflow-wrap: anywhere;
+  font-size: 1.1rem;
+  font-weight: 650;
+  letter-spacing: -0.025em;
+}
+
+[data-mk-drilldown-back] {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  cursor: pointer;
+}
+
+[data-mk-drilldown-back] > svg { transform: rotate(180deg); }
+[data-mk-drilldown-back][hidden],
+[data-mk-drilldown-empty][hidden] { display: none; }
+
+[data-mk-drilldown-breadcrumb] ol {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+  margin: 0;
+  padding: 0 12px 12px;
+  list-style: none;
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+  line-height: 1.5;
+}
+
+[data-mk-drilldown-breadcrumb] li {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+[data-mk-drilldown-breadcrumb] li + li::before { content: '/'; opacity: 0.5; }
+[data-mk-drilldown-breadcrumb] [aria-current] { color: var(--mk-text); }
+[data-mk-drilldown-crumb] {
+  padding: 2px;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+[data-mk-drilldown-viewport] { overflow: hidden; border-radius: var(--mk-drilldown-item-radius); }
+[data-mk-drilldown-level] { display: grid; gap: 3px; }
+[data-mk-drilldown-item] {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 18px;
+  width: 100%;
+  min-height: 58px;
+  padding: 13px 15px;
+  border: 0;
+  border-radius: var(--mk-drilldown-item-radius);
+  background: transparent;
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.9rem;
+  line-height: 1.4;
+  text-align: start;
+  cursor: pointer;
+  transition: background-color 0.16s ease;
+}
+
+[data-mk-drilldown-item]:enabled:hover,
+[data-mk-drilldown-item]:focus-visible { background: var(--mk-surface-3); }
+[data-mk-drilldown-item]:disabled { opacity: 0.42; cursor: default; }
+[data-mk-drilldown-text] { display: grid; gap: 3px; min-width: 0; overflow-wrap: anywhere; }
+[data-mk-drilldown-label] { font-weight: 550; }
+[data-mk-drilldown-description] { color: var(--mk-muted); font-size: 0.8rem; }
+[data-mk-drilldown-arrow] { display: inline-flex; flex: none; color: var(--mk-muted); }
+[data-mk-drilldown-empty] { margin: 0; padding: 24px 16px; color: var(--mk-muted); font-size: 0.875rem; }
+
+[data-mk-drilldown-item]:focus-visible,
+[data-mk-drilldown-back]:focus-visible,
+[data-mk-drilldown-crumb]:focus-visible,
+[data-mk-drilldown-level]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: -2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-drilldown-item] { transition: none; }
+}

package/src/components/drilldown-menu/element.ts

@@ -0,0 +1,59 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createDrilldownMenu, type DrilldownMenuInstance, type DrilldownMenuItem, type DrilldownMenuOptions } from './engine';
+
+/** Light DOM action menu; items/path accept JSON. Emits mk:select and mk:path-change. */
+export class MkDrilldownMenuElement extends MkElement<DrilldownMenuInstance> {
+  static options: Record<string, OptionType> = { items: 'json', path: 'json', label: 'string', backLabel: 'string', emptyText: 'string' };
+  private pendingItems: DrilldownMenuItem[] | undefined;
+  private pendingPath: string[] | undefined;
+
+  protected create(options: Record<string, unknown>) {
+    return createDrilldownMenu(this, {
+      ...options,
+      ...(this.pendingItems !== undefined ? { items: this.pendingItems } : {}),
+      ...(this.pendingPath !== undefined ? { path: this.pendingPath } : {}),
+    } as DrilldownMenuOptions);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next) return;
+    if (name === 'items' || name === 'path') {
+      try {
+        const value: unknown = JSON.parse(next ?? '[]');
+        if (!Array.isArray(value)) return;
+        if (name === 'items') {
+          this.pendingItems = value as DrilldownMenuItem[];
+          this.instance?.setItems(this.pendingItems);
+        } else {
+          this.pendingPath = value as string[];
+          this.instance?.setPath(this.pendingPath);
+        }
+      } catch {
+        // Invalid JSON leaves the last valid data and path intact.
+      }
+    } else if (this.instance) {
+      const { label, backLabel, emptyText } = this.options;
+      this.instance.update({ label, backLabel, emptyText } as DrilldownMenuOptions);
+    }
+  }
+
+  get items() { return this.pendingItems ?? (this.options.items as DrilldownMenuItem[] | undefined) ?? []; }
+  set items(items: DrilldownMenuItem[]) {
+    this.pendingItems = items;
+    this.instance?.setItems(items);
+  }
+  get path() { return this.instance?.path ?? this.pendingPath ?? (this.options.path as string[] | undefined) ?? []; }
+  set path(path: string[]) {
+    this.pendingPath = path;
+    this.instance?.setPath(path);
+  }
+  open(id: string) { return this.instance?.open(id) ?? false; }
+  back() { return this.instance?.back() ?? false; }
+  root() { this.instance?.root(); }
+  reset() { this.instance?.reset(); }
+  setItems(items: DrilldownMenuItem[]) { this.items = items; }
+  setPath(path: string[]) { this.path = path; }
+  focusItem(id: string) { this.instance?.focusItem(id); }
+}
+
+export const defineDrilldownMenu = () => defineElement('mk-drilldown-menu', MkDrilldownMenuElement);