@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/index.ts

@@ -200,3 +200,75 @@ export { createWeightHover, type WeightHoverOptions, type WeightHoverInstance }
 export { createSticker, type StickerOptions, type StickerInstance, type StickerState } from './recipes/sticker/create-sticker';
 export { createScrollDock, type ScrollDockOptions, type ScrollDockInstance } from './recipes/scroll-dock/create-scroll-dock';
 export { createLocalClock, type LocalClockOptions, type LocalClockInstance } from './recipes/local-clock/create-local-clock';
+export { createAttachment, acceptsFile, describeAccept, formatBytes, type AttachmentOptions, type AttachmentInstance, type AttachmentFile, type AttachmentStatus, type AttachmentRejection, type AttachmentRejectCode, type AttachmentLabels } from './components/attachment/engine';
+export { createSkeleton, skeletonBones, type SkeletonOptions, type SkeletonInstance, type SkeletonShape, type SkeletonAnimation } from './components/skeleton/engine';
+export { createQuestionnaire, readAnswers, type QuestionnaireOptions, type QuestionnaireInstance, type QuestionnaireAnswers, type QuestionnaireLabels } from './components/questionnaire/engine';
+export { createCodeBlock, codeLines, type CodeBlockOptions, type CodeBlockInstance } from './components/code-block/engine';
+export { createContextMenu, type ContextMenuOptions, type ContextMenuInstance } from './components/context-menu/engine';
+export { createDrawer, type DrawerOptions, type DrawerInstance, type DrawerSide } from './components/drawer/engine';
+export { createLinkPreview, safeHref, safeImage, linkDomain, type LinkPreviewOptions, type LinkPreviewInstance, type LinkPreviewVariant } from './components/link-preview/engine';
+export { createProgress, type ProgressOptions, type ProgressInstance, type ProgressVariant } from './components/progress/engine';
+export { createRangeSlider, type RangeSliderOptions, type RangeSliderInstance, type RangeValue } from './components/range-slider/engine';
+export { createChart, type ChartOptions, type ChartInstance, type ChartSeries, type ChartPoint, type ChartType } from './components/chart/engine';
+export { press, blurIn, blurOut, collapse, shake, ringPulse, burst, rollDigits, type BlurInOptions, type BurstOptions } from './motion/micro';
+export { createCreditCard, type CreditCardOptions, type CreditCardInstance, type CreditCardField, type CreditCardValues, type CreditCardLabels } from './components/credit-card/engine';
+export { detectBrand, formatNumber, luhn, parseExpiry, cardLength, cvcLength, BRAND_LABELS, type CardBrand, type Expiry } from './components/credit-card/card';
+export { createCommandSearch, type CommandSearchOptions, type CommandSearchInstance, type CommandItem } from './components/command-search/engine';
+export { matchScore, type Match } from './components/command-search/match';
+export { createHoldConfirm, type HoldConfirmOptions, type HoldConfirmInstance } from './components/hold-confirm/engine';
+export { createImagePreview, type ImagePreviewOptions, type ImagePreviewInstance } from './components/image-preview/engine';
+export { createLikeButton, type LikeButtonOptions, type LikeButtonInstance } from './components/like-button/engine';
+export { createNotificationBell, type NotificationBellOptions, type NotificationBellInstance } from './components/notification-bell/engine';
+export { createPasswordStrength, type PasswordStrengthOptions, type PasswordStrengthInstance } from './components/password-strength/engine';
+export { scorePassword, STRENGTH_LABELS, type PasswordScore, type PasswordChecks } from './components/password-strength/score';
+export { createScratchCard, type ScratchCardOptions, type ScratchCardInstance } from './components/scratch-card/engine';
+export { createStarRating, type StarRatingOptions, type StarRatingInstance } from './components/star-rating/engine';
+export { createSwipeActions, type SwipeActionsOptions, type SwipeActionsInstance, type SwipeSide } from './components/swipe-actions/engine';
+export { tokenize, renderCode, languageFamily, type Token, type TokenType } from './components/code-block/highlight';
+export { createColorSlider, type ColorSliderOptions, type ColorSliderInstance } from './components/color-slider/engine';
+export { createColorArea, type ColorAreaOptions, type ColorAreaInstance } from './components/color-area/engine';
+export { createColorField, type ColorFieldOptions, type ColorFieldInstance } from './components/color-field/engine';
+export { createColorPicker, type ColorPickerOptions, type ColorPickerInstance } from './components/color-picker/engine';
+export { createTimeField, type TimeFieldOptions, type TimeFieldInstance } from './components/time-field/engine';
+export { createRangeCalendar, bandDuration, type RangeCalendarOptions, type RangeCalendarInstance } from './components/range-calendar/engine';
+export { createDateRangePicker, type DateRangePickerOptions, type DateRangePickerInstance } from './components/date-range-picker/engine';
+export {
+  parseColor, formatColor, toHex, toHsva, hsvToRgb, rgbToHsv, getChannel, setChannel, channelText, luminance, CHANNEL_LABELS,
+  type Hsva, type Rgba, type Hsla, type ColorFormat, type ColorChannel,
+} from './core/color';
+export { parseTime, formatTime, type TimeValue } from './core/segments';
+export { toRange, rangeKeys, rangeLength, type DateRange } from './core/date-range';
+export { createTooltip, type TooltipOptions, type TooltipInstance } from './components/tooltip/engine';
+export { place, type Placement, type Side, type Placed } from './core/position';
+export { createPopover, type PopoverOptions, type PopoverInstance } from './components/popover/engine';
+export { createLoadingButton, type LoadingButtonOptions, type LoadingButtonInstance, type LoadingState } from './components/loading-button/engine';
+export { createBreadcrumb, type BreadcrumbOptions, type BreadcrumbInstance, type BreadcrumbItem } from './components/breadcrumb/engine';
+export { createEmptyState, type EmptyStateOptions, type EmptyStateInstance, type EmptyIllustration, type EmptyAction } from './components/empty-state/engine';
+export { createStatCard, type StatCardOptions, type StatCardInstance } from './components/stat-card/engine';
+export { createChartTooltip, type ChartTooltipOptions, type ChartTooltipInstance, type ChartTooltipSeries } from './components/chart-tooltip/engine';
+export { createMultiSelect, type MultiSelectOptions, type MultiSelectInstance, type MultiSelectOption } from './components/multi-select/engine';
+export { createTagInput, type TagInputOptions, type TagInputInstance } from './components/tag-input/engine';
+export { createDateTimePicker, toDateTimeValue, dateTimeKey, type DateTimePickerOptions, type DateTimePickerInstance } from './components/date-time-picker/engine';
+export { createFilterBuilder, type FilterBuilderOptions, type FilterBuilderInstance } from './components/filter-builder/engine';
+export {
+  matchesFilter, describeFilter, emptyFilter, hasConditions, OPERATORS,
+  type FilterField, type FilterFieldType, type FilterGroup, type FilterRule, type FilterNode, type FilterValue,
+} from './core/filter';
+export { createTimeline, type TimelineOptions, type TimelineInstance, type TimelineEvent, type TimelineStatus } from './components/timeline/engine';
+export { relativeTime, dayLabel, type TimeInput } from './core/relative-time';
+export { createActivityFeed, type ActivityFeedOptions, type ActivityFeedInstance, type ActivityItem, type ActivityActor, type ActivityKind } from './components/activity-feed/engine';
+export { createTreeView, type TreeViewOptions, type TreeViewInstance } from './components/tree-view/engine';
+export { findNode, checkStates, toggleCheck, searchTree, type TreeNode, type CheckState } from './core/tree';
+export { createFileExplorer, type FileExplorerOptions, type FileExplorerInstance, type FileView, type FileChange } from './components/file-explorer/engine';
+export { formatSize, fileFamily, sortEntries, type FileEntry, type FileFamily, type FileSort } from './core/files';
+export { createJsonViewer, jsonPath, type JsonViewerOptions, type JsonViewerInstance, type JsonType } from './components/json-viewer/engine';
+export { createVirtualList, type VirtualListOptions, type VirtualListInstance, type VirtualKey, type VirtualScrollOptions } from './components/virtual-list/engine';
+export { createSizes, type VirtualSizes, type VirtualRange } from './core/virtual';
+export { createResizablePanel, normaliseSizes, type ResizablePanelOptions, type ResizablePanelInstance, type PanelOrientation } from './components/resizable-panel/engine';
+export { createSplitView, type SplitViewOptions, type SplitViewInstance, type SplitSide } from './components/split-view/engine';
+export {
+  createDataTable,
+  type DataTableOptions, type DataTableInstance, type DataColumn, type DataColumnType, type DataAction, type DataRow, type DataSort, type RowId, type SortDirection,
+} from './components/data-table/engine';
+export { createEditableTable, type EditableTableOptions, type EditableTableInstance, type EditableColumn, type RowChange, type EditorKind } from './components/editable-table/engine';
+export { createRichTextEditor, sanitizeHtml, type RichTextEditorOptions, type RichTextEditorInstance, type RichCommand } from './components/rich-text-editor/engine';

package/src/motion/micro.ts

@@ -0,0 +1,248 @@
+import { gsap, EASE, registerMotion } from '../core/gsap';
+import { reduced } from '../core/reduced';
+
+/*
+ * Melonmind microinteractions (sources/app/css/ui-elements/animations.css,
+ * button.css, popover.css) on GSAP, shared by the components:
+ * - press: buttonClickAnimation, scale .95 × .9 and back in 500 ms (click curve).
+ * - blurIn: search-result-item-in (blur 16, y −20, 500 ms, 50 ms apart),
+ *   animation-general-in-2 (pop: blur 32, scale .7, 300 ms) or general-in (soft).
+ * - blurOut: item-out / -left / -bottom (blur 16, 500 ms).
+ * - collapse: a removed row folds (height 0, blur 16, 250 ms).
+ * - shake: the error shake (±4 px, 500 ms).
+ * - ringPulse: animation-highlight-2 (inset ring 0 → 4 px → 0 in 1 s).
+ * - burst: particles flying out of a control (like, rating, confirm).
+ * - rollDigits: Melonmind's RollingNumber, changed characters roll in their direction.
+ * Every helper returns its animation, or null under reduced motion (final state at once).
+ */
+
+type Targets = Element | Element[] | NodeListOf<Element> | null | undefined;
+
+const list = (targets: Targets) => (!targets ? [] : targets instanceof Element ? [targets] : [...targets]);
+const live = () => {
+  registerMotion();
+  return !reduced();
+};
+
+/** Press bounce (Melonmind buttonClickAnimation). */
+export function press(el: Element | null | undefined) {
+  if (!el || !live()) return null;
+  gsap.killTweensOf(el, 'scaleX,scaleY');
+  return gsap
+    .timeline({
+      onComplete: () => {
+        gsap.set(el, { clearProps: 'scale,transform' });
+      },
+    })
+    .to(el, { scaleX: 0.95, scaleY: 0.9, duration: 0.1, ease: 'power2.out' })
+    .to(el, { scaleX: 1, scaleY: 1, duration: 0.5, ease: EASE.click });
+}
+
+export interface BlurInOptions {
+  /** rise: list item (y −20, blur 16); pop: surface (scale .7, blur 32); soft: scale .96, blur 16. */
+  from?: 'rise' | 'pop' | 'soft';
+  stagger?: number;
+  delay?: number;
+  duration?: number;
+}
+
+export function blurIn(targets: Targets, { from = 'rise', stagger = 0.05, delay = 0, duration }: BlurInOptions = {}) {
+  const items = list(targets);
+  if (!items.length || !live()) return null;
+  const start =
+    from === 'pop' ? { opacity: 0, scale: 0.7, filter: 'blur(32px)' } : from === 'soft' ? { opacity: 0, scale: 0.96, filter: 'blur(16px)' } : { opacity: 0, y: -20, filter: 'blur(16px)' };
+  return gsap.fromTo(items, start, {
+    opacity: 1,
+    y: 0,
+    scale: 1,
+    filter: 'blur(0px)',
+    duration: duration ?? (from === 'pop' ? 0.3 : 0.5),
+    ease: from === 'pop' ? EASE.pop : 'power2.out',
+    stagger,
+    delay,
+    clearProps: 'opacity,transform,filter',
+  });
+}
+
+export function blurOut(targets: Targets, { to = 'up', onComplete }: { to?: 'up' | 'left' | 'down'; onComplete?: () => void } = {}) {
+  const items = list(targets);
+  if (!items.length) return null;
+  if (!live()) {
+    onComplete?.();
+    return null;
+  }
+  const end = to === 'left' ? { x: -64 } : to === 'down' ? { y: 24 } : { y: -20 };
+  return gsap.to(items, { ...end, opacity: 0, filter: 'blur(16px)', duration: 0.5, ease: 'power2.out', onComplete });
+}
+
+/** Fold an element away (Melonmind today-appt-item-out). */
+export function collapse(el: HTMLElement | null | undefined, { onComplete }: { onComplete?: () => void } = {}) {
+  if (!el) return null;
+  if (!live()) {
+    onComplete?.();
+    return null;
+  }
+  return gsap.to(el, {
+    height: 0,
+    paddingTop: 0,
+    paddingBottom: 0,
+    marginTop: 0,
+    marginBottom: 0,
+    opacity: 0,
+    filter: 'blur(16px)',
+    overflow: 'hidden',
+    duration: 0.25,
+    ease: 'power2.in',
+    onComplete,
+  });
+}
+
+/** The error shake. */
+export function shake(el: Element | null | undefined, distance = 4) {
+  if (!el || !live()) return null;
+  gsap.killTweensOf(el, 'x');
+  return gsap.to(el, {
+    keyframes: { x: [0, -distance, distance, -distance, 0] },
+    duration: 0.5,
+    ease: EASE.shake,
+    clearProps: 'x,transform',
+  });
+}
+
+/** An inset ring that swells and fades (Melonmind animation-highlight-2). */
+export function ringPulse(el: HTMLElement | null | undefined, color = 'var(--mk-accent-soft)') {
+  if (!el || !live()) return null;
+  const before = { color: el.style.outlineColor, style: el.style.outlineStyle, offset: el.style.outlineOffset };
+  el.style.outlineColor = color;
+  el.style.outlineStyle = 'solid';
+  el.style.outlineOffset = '-4px';
+  const restore = () => {
+    el.style.outlineColor = before.color;
+    el.style.outlineStyle = before.style;
+    el.style.outlineOffset = before.offset;
+    el.style.removeProperty('outline-width');
+    if (el.getAttribute('style') === '') el.removeAttribute('style');
+  };
+  return gsap.fromTo(el, { outlineWidth: 0 }, { keyframes: { outlineWidth: [0, 4, 0] }, duration: 1, ease: 'power1.inOut', onComplete: restore, onInterrupt: restore });
+}
+
+export interface BurstOptions {
+  count?: number;
+  distance?: number;
+  /** CSS colours, used in turn. */
+  colors?: string[];
+  /** An expanding ring behind the particles. */
+  ring?: boolean;
+  size?: number;
+}
+
+/** Particles flying out of the centre of `origin` (like, rating, confirm). Removed when done. */
+export function burst(origin: HTMLElement | null | undefined, { count = 7, distance = 28, colors = ['var(--mk-accent)'], ring = true, size = 6 }: BurstOptions = {}) {
+  if (!origin || !live()) return null;
+  const layer = document.createElement('span');
+  layer.setAttribute('aria-hidden', 'true');
+  layer.dataset.mkBurst = '';
+  Object.assign(layer.style, { position: 'absolute', inset: '0', pointerEvents: 'none', overflow: 'visible', display: 'grid', placeItems: 'center' });
+  const positioned = getComputedStyle(origin).position !== 'static';
+  const previousPosition = origin.style.position;
+  if (!positioned) origin.style.position = 'relative';
+  origin.append(layer);
+  const cleanup = () => {
+    layer.remove();
+    if (!positioned) origin.style.position = previousPosition;
+    if (origin.getAttribute('style') === '') origin.removeAttribute('style');
+  };
+  const timeline = gsap.timeline({ onComplete: cleanup, onInterrupt: cleanup });
+  if (ring) {
+    const circle = document.createElement('span');
+    Object.assign(circle.style, { position: 'absolute', width: '100%', aspectRatio: '1', borderRadius: '50%', border: `2px solid ${colors[0]}` });
+    layer.append(circle);
+    timeline.fromTo(circle, { scale: 0.3, opacity: 0.9 }, { scale: 1.6, opacity: 0, duration: 0.5, ease: 'power2.out' }, 0);
+  }
+  for (let i = 0; i < count; i++) {
+    const angle = (i / count) * Math.PI * 2 - Math.PI / 2;
+    for (const [k, scale] of [[0, 1], [1, 0.6]] as const) {
+      const dot = document.createElement('span');
+      Object.assign(dot.style, {
+        position: 'absolute',
+        width: `${size * scale}px`,
+        height: `${size * scale}px`,
+        borderRadius: '50%',
+        background: colors[(i + k) % colors.length],
+      });
+      layer.append(dot);
+      const reach = distance * (k ? 0.72 : 1);
+      const turn = k ? 0.32 : 0;
+      timeline.fromTo(
+        dot,
+        { x: 0, y: 0, scale: 0, opacity: 1 },
+        { x: Math.cos(angle + turn) * reach, y: Math.sin(angle + turn) * reach, scale: 1, duration: 0.45, ease: 'power3.out' },
+        0.05,
+      );
+      timeline.to(dot, { scale: 0, opacity: 0, duration: 0.3, ease: 'power2.in' }, 0.38);
+    }
+  }
+  return timeline;
+}
+
+const rolling = new WeakMap<HTMLElement, gsap.core.Timeline>();
+
+/**
+ * Write `text` into `el`, rolling the characters that changed (up when the value
+ * grew, down when it shrank). Unchanged characters stay; the final DOM is plain text.
+ */
+export function rollDigits(el: HTMLElement | null | undefined, text: string, direction: 1 | -1 = 1, duration = 0.5) {
+  if (!el) return null;
+  rolling.get(el)?.progress(1).kill();
+  rolling.delete(el);
+  const previous = el.textContent ?? '';
+  if (previous === text || !live()) {
+    el.textContent = text;
+    return null;
+  }
+  // Right-aligned comparison: digits keep their place value.
+  const width = Math.max(previous.length, text.length);
+  const oldChars = previous.padStart(width, ' ');
+  const newChars = text.padStart(width, ' ');
+  el.textContent = '';
+  const label = document.createElement('span');
+  label.className = 'mk-sr-only';
+  label.textContent = text;
+  const visual = document.createElement('span');
+  visual.setAttribute('aria-hidden', 'true');
+  visual.style.display = 'inline-flex';
+  const moving: Array<[HTMLElement, HTMLElement]> = [];
+  // Only the padding added for the alignment is skipped; spaces inside the text stay.
+  const padding = Math.min(width - previous.length, width - text.length);
+  for (let i = padding; i < width; i++) {
+    const before = oldChars[i]!;
+    const after = newChars[i]!;
+    const cell = document.createElement('span');
+    Object.assign(cell.style, { position: 'relative', display: 'inline-block', overflow: 'hidden', whiteSpace: 'pre' });
+    const next = document.createElement('span');
+    next.style.display = 'inline-block';
+    next.textContent = after;
+    cell.append(next);
+    if (before !== after) {
+      const old = document.createElement('span');
+      Object.assign(old.style, { position: 'absolute', left: '0', top: '0', display: 'inline-block' });
+      old.textContent = before;
+      cell.append(old);
+      moving.push([old, next]);
+    }
+    visual.append(cell);
+  }
+  el.append(label, visual);
+  const timeline = gsap.timeline({
+    onComplete: () => {
+      el.textContent = text;
+      rolling.delete(el);
+    },
+  });
+  moving.forEach(([old, next], i) => {
+    timeline.to(old, { yPercent: -100 * direction, opacity: 0, filter: 'blur(4px)', duration, ease: EASE.signature }, i * 0.03);
+    timeline.fromTo(next, { yPercent: 100 * direction, opacity: 0, filter: 'blur(4px)' }, { yPercent: 0, opacity: 1, filter: 'blur(0px)', duration, ease: EASE.signature }, i * 0.03);
+  });
+  rolling.set(el, timeline);
+  return timeline;
+}

package/src/motion/sheet.ts

@@ -1,65 +1,88 @@
-import { gsap, EASE, registerMotion } from '../core/gsap';
-import { motionSpring } from '../core/physics-spring';
-import { reduced } from '../core/reduced';
-import { clearStyles } from '../core/styles';
-import { TIMING } from '../core/timing';
-import { backdropVeil, ghostOf } from './surface';
-
-/*
- * project sheet: the surface rises from below the screen (0.72 s,
- * cubic(.16,1,.3,1)) while the page behind ([data-mk-underlay]) sinks to
- * scale .98 / opacity .4 on a 300/30 spring. It closes through an inert copy
- * that drops away, so focus returns at once.
- */
-
-const UNDERLAY_STYLES = ['transform', 'translate', 'rotate', 'scale', 'transform-origin', 'opacity'];
-
-export function sheetOpen(surface: HTMLElement) {
-  if (reduced()) return null;
-  registerMotion();
-  return gsap.fromTo(surface, { yPercent: 100 }, { yPercent: 0, duration: TIMING.sheet.open, ease: EASE.sheet, clearProps: 'transform' });
-}
-
-/** Drop a copy of the (still open) sheet off the bottom of the screen. */
-export function sheetClose(surface: HTMLElement, { inPlace = false }: { inPlace?: boolean } = {}) {
-  registerMotion();
-  const dragged = inPlace ? Number(gsap.getProperty(surface, 'y')) || 0 : 0;
-  gsap.killTweensOf(surface);
-  clearStyles([surface], ['transform', 'translate', 'rotate', 'scale']);
-  const ghost = reduced() ? null : ghostOf(surface);
-  if (!ghost) return null;
-  const veil = backdropVeil(surface);
-  document.body.append(veil, ghost);
-  gsap.to(veil, { opacity: 0, duration: TIMING.sheet.close, ease: 'power3.in', onComplete: () => veil.remove() });
-  return gsap.fromTo(
-    ghost,
-    { y: dragged, yPercent: 0 },
-    { yPercent: 100, duration: TIMING.sheet.close, ease: EASE.sheet, onComplete: () => ghost.remove() },
-  );
-}
-
-export function pushUnderlay(elements: HTMLElement[]) {
-  if (!elements.length || reduced()) return;
-  registerMotion();
-  const { ease, duration } = motionSpring(...TIMING.springs.underlay);
-  gsap.to(elements, {
-    scale: TIMING.sheet.underlayScale,
-    opacity: TIMING.sheet.underlayOpacity,
-    transformOrigin: '50% 0',
-    duration,
-    ease,
-    overwrite: 'auto',
-  });
-}
-
-export function releaseUnderlay(elements: HTMLElement[], animated = true) {
-  if (!elements.length) return;
-  const restore = () => clearStyles(elements, UNDERLAY_STYLES);
-  if (!animated || reduced()) {
-    gsap.killTweensOf(elements);
-    restore();
-    return;
-  }
-  const { ease, duration } = motionSpring(...TIMING.springs.underlay);
-  gsap.to(elements, { scale: 1, opacity: 1, duration, ease, overwrite: 'auto', onComplete: restore });
-}
+import { gsap, EASE, registerMotion } from '../core/gsap';
+import { motionSpring } from '../core/physics-spring';
+import { reduced } from '../core/reduced';
+import { clearStyles } from '../core/styles';
+import { TIMING } from '../core/timing';
+import { backdropVeil, ghostOf } from './surface';
+
+/*
+ * project sheet: the surface rises from below the screen (0.72 s,
+ * cubic(.16,1,.3,1)) while the page behind ([data-mk-underlay]) sinks to
+ * scale .98 / opacity .4 on a 300/30 spring. It closes through an inert copy
+ * that drops away, so focus returns at once.
+ */
+
+const UNDERLAY_STYLES = ['transform', 'translate', 'rotate', 'scale', 'transform-origin', 'opacity'];
+
+export function sheetOpen(surface: HTMLElement) {
+  if (reduced()) return null;
+  registerMotion();
+  return gsap.fromTo(surface, { yPercent: 100 }, { yPercent: 0, duration: TIMING.sheet.open, ease: EASE.sheet, clearProps: 'transform' });
+}
+
+/** Side of a drawer surface: data-mk-drawer="left", else right. */
+const slideFrom = (surface: HTMLElement) => (surface.dataset.mkDrawer === 'left' ? -1 : 1);
+
+/** Drawer: the surface slides in from its side on the sheet curve. */
+export function slideOpen(surface: HTMLElement) {
+  if (reduced()) return null;
+  registerMotion();
+  return gsap.fromTo(surface, { xPercent: 104 * slideFrom(surface) }, { xPercent: 0, duration: TIMING.sheet.open, ease: EASE.sheet, clearProps: 'transform' });
+}
+
+/** Slide a copy of the (still open) drawer back off its side, so focus returns at once. */
+export function slideClose(surface: HTMLElement) {
+  registerMotion();
+  gsap.killTweensOf(surface);
+  clearStyles([surface], ['transform', 'translate', 'rotate', 'scale']);
+  const ghost = reduced() ? null : ghostOf(surface);
+  if (!ghost) return null;
+  const veil = backdropVeil(surface);
+  document.body.append(veil, ghost);
+  gsap.to(veil, { opacity: 0, duration: TIMING.sheet.close * 0.8, ease: 'power3.in', onComplete: () => veil.remove() });
+  return gsap.to(ghost, { xPercent: 104 * slideFrom(surface), duration: TIMING.sheet.close * 0.8, ease: 'power3.in', onComplete: () => ghost.remove() });
+}
+
+/** Drop a copy of the (still open) sheet off the bottom of the screen. */
+export function sheetClose(surface: HTMLElement, { inPlace = false }: { inPlace?: boolean } = {}) {
+  registerMotion();
+  const dragged = inPlace ? Number(gsap.getProperty(surface, 'y')) || 0 : 0;
+  gsap.killTweensOf(surface);
+  clearStyles([surface], ['transform', 'translate', 'rotate', 'scale']);
+  const ghost = reduced() ? null : ghostOf(surface);
+  if (!ghost) return null;
+  const veil = backdropVeil(surface);
+  document.body.append(veil, ghost);
+  gsap.to(veil, { opacity: 0, duration: TIMING.sheet.close, ease: 'power3.in', onComplete: () => veil.remove() });
+  return gsap.fromTo(
+    ghost,
+    { y: dragged, yPercent: 0 },
+    { yPercent: 100, duration: TIMING.sheet.close, ease: EASE.sheet, onComplete: () => ghost.remove() },
+  );
+}
+
+export function pushUnderlay(elements: HTMLElement[]) {
+  if (!elements.length || reduced()) return;
+  registerMotion();
+  const { ease, duration } = motionSpring(...TIMING.springs.underlay);
+  gsap.to(elements, {
+    scale: TIMING.sheet.underlayScale,
+    opacity: TIMING.sheet.underlayOpacity,
+    transformOrigin: '50% 0',
+    duration,
+    ease,
+    overwrite: 'auto',
+  });
+}
+
+export function releaseUnderlay(elements: HTMLElement[], animated = true) {
+  if (!elements.length) return;
+  const restore = () => clearStyles(elements, UNDERLAY_STYLES);
+  if (!animated || reduced()) {
+    gsap.killTweensOf(elements);
+    restore();
+    return;
+  }
+  const { ease, duration } = motionSpring(...TIMING.springs.underlay);
+  gsap.to(elements, { scale: 1, opacity: 1, duration, ease, overwrite: 'auto', onComplete: restore });
+}

package/src/motion/surface.ts

@@ -78,6 +78,15 @@ export function ghostOf(surface: HTMLElement): HTMLElement | null {
   const ghost = document.createElement('div');
   ghost.className = surface.className;
   ghost.innerHTML = surface.innerHTML;
+  // The markup carries attributes, not what was typed or chosen since: copy the live values too.
+  const live = surface.querySelectorAll<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>('input, textarea, select');
+  ghost.querySelectorAll<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>('input, textarea, select').forEach((copy, i) => {
+    const source = live[i];
+    if (!source) return;
+    if (copy instanceof HTMLSelectElement) copy.selectedIndex = (source as HTMLSelectElement).selectedIndex;
+    else copy.value = source.value;
+    if (copy instanceof HTMLInputElement && source instanceof HTMLInputElement) copy.checked = source.checked;
+  });
   ghost.setAttribute('aria-hidden', 'true');
   ghost.inert = true;
   ghost.dataset.mkGhost = '';

package/src/react/index.ts

@@ -99,3 +99,60 @@ export { useWeightHover } from './use-weight-hover';
 export { useSticker } from './use-sticker';
 export { useScrollDock } from './use-scroll-dock';
 export { useLocalClock } from './use-local-clock';
+export { Attachment, type AttachmentProps, type AttachmentUpload } from '../components/attachment/react';
+export { Skeleton, type SkeletonProps } from '../components/skeleton/react';
+export { Questionnaire, type QuestionnaireProps, type Question, type QuestionType, type QuestionOption } from '../components/questionnaire/react';
+export { CodeBlock, type CodeBlockProps } from '../components/code-block/react';
+export { ContextMenu, type ContextMenuProps } from '../components/context-menu/react';
+export { Drawer, useDrawer, type DrawerRootProps } from '../components/drawer/react';
+export { LinkPreview, type LinkPreviewProps } from '../components/link-preview/react';
+export { Progress, type ProgressProps } from '../components/progress/react';
+export { RangeSlider, type RangeSliderProps } from '../components/range-slider/react';
+export { Chart, type ChartProps } from '../components/chart/react';
+export { CreditCard, type CreditCardProps } from '../components/credit-card/react';
+export { CommandSearch, type CommandSearchProps } from '../components/command-search/react';
+export type { CommandItem } from '../components/command-search/engine';
+export { HoldConfirm, type HoldConfirmProps } from '../components/hold-confirm/react';
+export { ImagePreview, type ImagePreviewProps, type PreviewImage } from '../components/image-preview/react';
+export { LikeButton, type LikeButtonProps } from '../components/like-button/react';
+export { NotificationBell, type NotificationBellProps } from '../components/notification-bell/react';
+export { PasswordStrength, type PasswordStrengthProps } from '../components/password-strength/react';
+export { ScratchCard, type ScratchCardProps } from '../components/scratch-card/react';
+export { StarRating, type StarRatingProps } from '../components/star-rating/react';
+export { SwipeActions, type SwipeActionsProps, type SwipeRowProps, type SwipeAction } from '../components/swipe-actions/react';
+export { ColorSlider, type ColorSliderProps } from '../components/color-slider/react';
+export { ColorArea, type ColorAreaProps } from '../components/color-area/react';
+export { ColorField, type ColorFieldProps } from '../components/color-field/react';
+export { ColorPicker, type ColorPickerProps } from '../components/color-picker/react';
+export { TimeField, type TimeFieldProps } from '../components/time-field/react';
+export { RangeCalendar, type RangeCalendarProps } from '../components/range-calendar/react';
+export { DateRangePicker, type DateRangePickerProps } from '../components/date-range-picker/react';
+export { Tooltip, type TooltipProps } from '../components/tooltip/react';
+export { Popover, type PopoverProps } from '../components/popover/react';
+export { LoadingButton, type LoadingButtonProps } from '../components/loading-button/react';
+export { Breadcrumb, type BreadcrumbProps } from '../components/breadcrumb/react';
+export { EmptyState, type EmptyStateProps } from '../components/empty-state/react';
+export { StatCard, type StatCardProps } from '../components/stat-card/react';
+export { ChartTooltip, type ChartTooltipProps } from '../components/chart-tooltip/react';
+export { MultiSelect, type MultiSelectProps } from '../components/multi-select/react';
+export { TagInput, type TagInputProps } from '../components/tag-input/react';
+export { DateTimePicker, type DateTimePickerProps } from '../components/date-time-picker/react';
+export { FilterBuilder, type FilterBuilderProps } from '../components/filter-builder/react';
+export { Timeline, type TimelineProps } from '../components/timeline/react';
+export type { TimelineEvent, TimelineStatus } from '../components/timeline/engine';
+export { ActivityFeed, type ActivityFeedProps, type ActivityFeedHandle } from '../components/activity-feed/react';
+export type { ActivityItem, ActivityActor, ActivityKind } from '../components/activity-feed/engine';
+export { TreeView, type TreeViewProps, type TreeViewHandle } from '../components/tree-view/react';
+export type { TreeNode } from '../core/tree';
+export { FileExplorer, type FileExplorerProps, type FileExplorerHandle } from '../components/file-explorer/react';
+export type { FileEntry, FileView, FileChange } from '../components/file-explorer/engine';
+export { JsonViewer, type JsonViewerProps, type JsonViewerHandle } from '../components/json-viewer/react';
+export { VirtualList, type VirtualListProps, type VirtualListHandle } from '../components/virtual-list/react';
+export { ResizablePanel, type ResizablePanelProps, type ResizablePanelHandle } from '../components/resizable-panel/react';
+export { SplitView, type SplitViewProps, type SplitViewHandle } from '../components/split-view/react';
+export { DataTable, type DataTableProps, type DataTableHandle } from '../components/data-table/react';
+export type { DataColumn, DataAction, DataRow, DataSort, RowId } from '../components/data-table/engine';
+export { EditableTable, type EditableTableProps, type EditableTableHandle } from '../components/editable-table/react';
+export type { EditableColumn, RowChange, EditorKind } from '../components/editable-table/engine';
+export { RichTextEditor, type RichTextEditorProps, type RichTextEditorHandle } from '../components/rich-text-editor/react';
+export type { RichCommand } from '../components/rich-text-editor/engine';