vanilla-jui 1.4.8 → 1.5.2

package/src/core/component.ts

@@ -0,0 +1,332 @@
+import { flushSync } from 'vanilla-signal';
+
+import { isPlainObject } from '../utilities/object.ts';
+import { createOwnedView } from './view.ts';
+
+export type ComponentProps = Record<string, unknown>;
+export type ComponentState = Record<string, unknown>;
+export type ComponentCleanup =
+  | void
+  | (() => void)
+  | {
+      destroy: () => void;
+    };
+export type ComponentPluginOptions = Record<string, unknown> | undefined;
+
+export interface ComponentRuntime {
+  built: boolean;
+  mounted: boolean;
+  destroyed: boolean;
+}
+
+export type ComponentLifecycleEvent = 'build' | 'mount' | 'unmount' | 'destroy';
+export type ComponentListener = (...args: unknown[]) => void;
+
+export interface ComponentController<
+  TProps extends ComponentProps = ComponentProps,
+  TState extends ComponentState = ComponentState,
+  TElement extends Element = HTMLElement,
+> {
+  readonly props: TProps;
+  readonly state: TState;
+  readonly runtime: ComponentRuntime;
+  readonly element: TElement | null;
+  build(): this;
+  mount(container: Element | DocumentFragment): this;
+  unmount(): this;
+  setState(patch?: Partial<TState> | null): this;
+  setState<TKey extends keyof TState>(key: TKey, value: TState[TKey]): this;
+  own(cleanup: ComponentCleanup): this;
+  use(
+    plugin: ComponentPlugin<this> | null | undefined,
+    options?: ComponentPluginOptions
+  ): this;
+  on(event: string, listener: ComponentListener): this;
+  off(event: string, listener: ComponentListener): this;
+  emit(event: string, ...args: unknown[]): this;
+  destroy(): void;
+}
+
+export type ComponentPlugin<TComponent = ComponentController> =
+  | ((
+      component: TComponent,
+      options?: ComponentPluginOptions
+    ) => ComponentCleanup)
+  | {
+      install: (
+        component: TComponent,
+        options?: ComponentPluginOptions
+      ) => ComponentCleanup;
+    };
+
+export interface ComponentContext<
+  TProps extends ComponentProps,
+  TState extends ComponentState,
+  TElement extends Element,
+> {
+  readonly props: TProps;
+  readonly state: TState;
+  readonly runtime: ComponentRuntime;
+  readonly element: TElement | null;
+  own: (cleanup: ComponentCleanup) => void;
+  assertActive: (operation: string) => void;
+  emit: (event: string, ...args: unknown[]) => void;
+}
+
+export interface ComponentDefinition<
+  TProps extends ComponentProps,
+  TState extends ComponentState,
+  TElement extends Element,
+  TActions extends object,
+> {
+  name: string;
+  ownsElement?: boolean;
+  props: TProps;
+  state: TState;
+  view: (context: ComponentContext<TProps, TState, TElement>) => TElement;
+  actions?: TActions;
+  normalizeStatePatch?: (patch: Partial<TState>) => Partial<TState>;
+  validateStatePatch?: (patch: Partial<TState>, state: TState) => void;
+  onBuild?: (context: ComponentContext<TProps, TState, TElement>) => void;
+  onMount?: (context: ComponentContext<TProps, TState, TElement>) => void;
+  onUnmount?: (context: ComponentContext<TProps, TState, TElement>) => void;
+  onDestroy?: (context: ComponentContext<TProps, TState, TElement>) => void;
+}
+
+export type FunctionalComponent<
+  TProps extends ComponentProps,
+  TState extends ComponentState,
+  TElement extends Element,
+  TActions extends object = object,
+> = ComponentController<TProps, TState, TElement> & TActions;
+
+const globalPlugins = new Map<string, ComponentPlugin>();
+
+export function useComponentPlugin(
+  name: string,
+  plugin: ComponentPlugin | null | undefined
+): void {
+  if (!name || !plugin) return;
+  globalPlugins.set(name, plugin);
+}
+
+export function removeComponentPlugin(name: string): void {
+  globalPlugins.delete(name);
+}
+
+function runCleanup(cleanup: ComponentCleanup): void {
+  if (typeof cleanup === 'function') cleanup();
+  else if (cleanup && typeof cleanup.destroy === 'function') cleanup.destroy();
+}
+
+export function defineComponent<
+  TProps extends ComponentProps,
+  TState extends ComponentState,
+  TElement extends Element,
+  TActions extends object = object,
+>(
+  definition: ComponentDefinition<TProps, TState, TElement, TActions>
+): FunctionalComponent<TProps, TState, TElement, TActions> {
+  const runtime: ComponentRuntime = {
+    built: false,
+    mounted: false,
+    destroyed: false,
+  };
+  const listeners = new Map<string, Set<ComponentListener>>();
+  const resources = new Set<ComponentCleanup>();
+  const plugins = new Map<ComponentPlugin<unknown>, ComponentCleanup>();
+  let element: TElement | null = null;
+  let disposeView: (() => void) | null = null;
+  let component: FunctionalComponent<TProps, TState, TElement, TActions>;
+
+  const assertActive = (operation: string): void => {
+    if (runtime.destroyed) {
+      throw new Error(`${definition.name}.${operation}: instance destroyed`);
+    }
+  };
+
+  const emit = (event: string, ...args: unknown[]): void => {
+    for (const listener of listeners.get(event) || []) {
+      try {
+        listener(...args);
+      } catch {
+        // Listener failures must not interrupt the component lifecycle.
+      }
+    }
+  };
+
+  const context: ComponentContext<TProps, TState, TElement> = {
+    props: definition.props,
+    state: definition.state,
+    runtime,
+    get element() {
+      return element;
+    },
+    own(cleanup) {
+      if (cleanup) resources.add(cleanup);
+    },
+    assertActive,
+    emit,
+  };
+
+  const controller: ComponentController<TProps, TState, TElement> = {
+    props: definition.props,
+    state: definition.state,
+    runtime,
+    get element() {
+      return element;
+    },
+    build() {
+      assertActive('build');
+      if (runtime.built) return component;
+
+      const ownedView = createOwnedView(() => definition.view(context), {
+        removeOnDispose: definition.ownsElement,
+      });
+      element = ownedView.element;
+      disposeView = ownedView.dispose;
+      runtime.built = true;
+      definition.onBuild?.(context);
+      emit('build', component);
+      return component;
+    },
+    mount(container) {
+      assertActive('mount');
+      if (!runtime.built) component.build();
+      if (!element) {
+        throw new Error(
+          `${definition.name}.mount: view did not create an element.`
+        );
+      }
+      if (element.parentNode !== container) container.appendChild(element);
+      runtime.mounted = true;
+      definition.onMount?.(context);
+      emit('mount', component, container);
+      return component;
+    },
+    unmount() {
+      assertActive('unmount');
+      if (!runtime.mounted && !element?.parentNode) return component;
+      definition.onUnmount?.(context);
+      if (definition.ownsElement !== false) element?.remove();
+      runtime.mounted = false;
+      emit('unmount', component);
+      return component;
+    },
+    setState(
+      keyOrPatch: Partial<TState> | keyof TState | null | undefined = {},
+      value?: unknown
+    ) {
+      assertActive('setState');
+      const patch =
+        typeof keyOrPatch === 'string' && arguments.length > 1
+          ? { [keyOrPatch]: value }
+          : keyOrPatch;
+      if (!isPlainObject(patch)) {
+        throw new Error(
+          `${definition.name}.setState: expects a plain object patch.`
+        );
+      }
+
+      const normalized = definition.normalizeStatePatch
+        ? definition.normalizeStatePatch(patch as Partial<TState>)
+        : (patch as Partial<TState>);
+      if (!isPlainObject(normalized)) {
+        throw new Error(
+          `${definition.name}.setState: expects a plain object patch.`
+        );
+      }
+
+      if (definition.validateStatePatch) {
+        definition.validateStatePatch(normalized, definition.state);
+      } else {
+        for (const key of Object.keys(normalized)) {
+          if (!Object.hasOwn(definition.state, key)) {
+            throw new Error(
+              `${definition.name}.setState: "${key}" is not a supported state key.`
+            );
+          }
+        }
+      }
+
+      flushSync(() => {
+        Object.assign(definition.state, normalized);
+      });
+      return component;
+    },
+    own(cleanup) {
+      if (cleanup) resources.add(cleanup);
+      return component;
+    },
+    use(plugin, options) {
+      if (!plugin) return component;
+      const cleanup =
+        typeof plugin === 'function'
+          ? plugin(component, options)
+          : plugin.install(component, options);
+      plugins.set(plugin as ComponentPlugin<unknown>, cleanup);
+      return component;
+    },
+    on(event, listener) {
+      if (!event || typeof listener !== 'function') return component;
+      let eventListeners = listeners.get(event);
+      if (!eventListeners) {
+        eventListeners = new Set();
+        listeners.set(event, eventListeners);
+      }
+      eventListeners.add(listener);
+      return component;
+    },
+    off(event, listener) {
+      listeners.get(event)?.delete(listener);
+      return component;
+    },
+    emit(event, ...args) {
+      emit(event, ...args);
+      return component;
+    },
+    destroy() {
+      if (runtime.destroyed) return;
+      runtime.destroyed = true;
+      definition.onDestroy?.(context);
+      emit('destroy', component);
+
+      for (const cleanup of resources) {
+        try {
+          runCleanup(cleanup);
+        } catch {
+          // Cleanup is best-effort; remaining resources must still be released.
+        }
+      }
+      resources.clear();
+
+      for (const cleanup of plugins.values()) {
+        try {
+          runCleanup(cleanup);
+        } catch {
+          // Plugin cleanup must not prevent view disposal.
+        }
+      }
+      plugins.clear();
+
+      disposeView?.();
+      disposeView = null;
+      if (definition.ownsElement !== false) element?.remove();
+      element = null;
+      runtime.built = false;
+      runtime.mounted = false;
+      listeners.clear();
+    },
+  };
+
+  component = Object.assign(
+    controller,
+    definition.actions || {}
+  ) as FunctionalComponent<TProps, TState, TElement, TActions>;
+
+  for (const plugin of globalPlugins.values()) {
+    component.use(plugin as ComponentPlugin<typeof component>);
+  }
+
+  return component;
+}

package/src/core/motion.ts

@@ -0,0 +1,298 @@
+export type TransitionTarget = () => Element | null | undefined;
+
+export interface TransitionDefinition {
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;
+  options?: KeyframeAnimationOptions;
+  respectReducedMotion?: boolean;
+}
+
+export interface MotionController {
+  enter: (signal?: AbortSignal) => Promise<void>;
+  leave: (signal?: AbortSignal) => Promise<void>;
+  cancel: () => void;
+}
+
+export interface CollapseTransitionDefinition {
+  axis?: 'vertical' | 'horizontal';
+  options?: KeyframeAnimationOptions;
+  fade?: boolean;
+  respectReducedMotion?: boolean;
+}
+
+export interface CollapseMotionController extends MotionController {
+  setExpanded: (expanded: boolean) => void;
+}
+
+export function createMotionGroup(
+  ...motions: readonly MotionController[]
+): MotionController {
+  return {
+    async enter(signal) {
+      await Promise.all(motions.map((motion) => motion.enter(signal)));
+    },
+    async leave(signal) {
+      await Promise.all(motions.map((motion) => motion.leave(signal)));
+    },
+    cancel() {
+      for (const motion of motions) motion.cancel();
+    },
+  };
+}
+
+function waitForAnimation(
+  animation: Animation,
+  signal?: AbortSignal
+): Promise<void> {
+  const finished = animation.finished.then(
+    () => undefined,
+    () => undefined
+  );
+  if (!signal) return finished;
+  return new Promise((resolve) => {
+    const complete = (): void => {
+      signal.removeEventListener('abort', complete);
+      resolve();
+    };
+    if (signal.aborted) {
+      complete();
+      return;
+    }
+    signal.addEventListener('abort', complete, { once: true });
+    void finished.then(complete);
+  });
+}
+
+function resolvedOptions(
+  element: Element,
+  definition: TransitionDefinition
+): KeyframeAnimationOptions {
+  const options: KeyframeAnimationOptions = {
+    fill: 'both',
+    ...definition.options,
+  };
+  const view = element.ownerDocument.defaultView;
+  if (
+    definition.respectReducedMotion !== false &&
+    view?.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+  ) {
+    options.duration = 0;
+    options.delay = 0;
+    options.endDelay = 0;
+  }
+  return options;
+}
+
+export function createTransition(
+  target: TransitionTarget,
+  definition: TransitionDefinition
+): MotionController {
+  let animation: Animation | null = null;
+
+  const resolveElement = (): Element | null => {
+    const nextElement = target() || null;
+    if (!nextElement || typeof nextElement.animate !== 'function') return null;
+    return nextElement;
+  };
+
+  const keyframesFor = (
+    direction: 1 | -1
+  ): Keyframe[] | PropertyIndexedKeyframes => {
+    if (direction === 1 || !Array.isArray(definition.keyframes)) {
+      return definition.keyframes;
+    }
+    return definition.keyframes.slice().reverse();
+  };
+
+  const play = async (
+    direction: 1 | -1,
+    signal?: AbortSignal
+  ): Promise<void> => {
+    if (signal?.aborted) return;
+    const currentElement = resolveElement();
+    if (!currentElement) return;
+    animation?.cancel();
+    animation = currentElement.animate(
+      keyframesFor(direction),
+      resolvedOptions(currentElement, definition)
+    );
+    const currentAnimation = animation;
+    await waitForAnimation(currentAnimation, signal);
+    if (signal?.aborted || animation !== currentAnimation) return;
+  };
+
+  return {
+    enter: (signal) => play(1, signal),
+    leave: (signal) => play(-1, signal),
+    cancel() {
+      animation?.cancel();
+      animation = null;
+    },
+  };
+}
+
+interface CollapseInlineStyles {
+  size: string;
+  opacity: string;
+  overflow: string;
+  visibility: string;
+}
+
+export function createCollapseTransition(
+  target: () => HTMLElement | null | undefined,
+  definition: CollapseTransitionDefinition = {}
+): CollapseMotionController {
+  const axis = definition.axis || 'vertical';
+  let element: HTMLElement | null = null;
+  let animation: Animation | null = null;
+  let original: CollapseInlineStyles | null = null;
+  let visibleOpacity = '1';
+  let operation = 0;
+
+  const readSize = (current: HTMLElement): string =>
+    axis === 'vertical' ? current.style.height : current.style.width;
+
+  const writeSize = (current: HTMLElement, value: string): void => {
+    if (axis === 'vertical') current.style.height = value;
+    else current.style.width = value;
+  };
+
+  const restore = (): void => {
+    if (!element || !original) return;
+    writeSize(element, original.size);
+    element.style.opacity = original.opacity;
+    element.style.overflow = original.overflow;
+    element.style.visibility = original.visibility;
+  };
+
+  const resolveElement = (): HTMLElement | null => {
+    const next = target() || null;
+    if (next === element) return element;
+
+    animation?.cancel();
+    restore();
+    animation = null;
+    element = next;
+    original = next
+      ? {
+          size: readSize(next),
+          opacity: next.style.opacity,
+          overflow: next.style.overflow,
+          visibility: next.style.visibility,
+        }
+      : null;
+    visibleOpacity =
+      next?.ownerDocument.defaultView?.getComputedStyle(next).opacity || '1';
+    return element;
+  };
+
+  const applyBoundary = (expanded: boolean): void => {
+    const current = resolveElement();
+    if (!current || !original) return;
+    if (expanded) {
+      restore();
+      return;
+    }
+    writeSize(current, '0px');
+    current.style.overflow = 'hidden';
+    current.style.visibility = 'hidden';
+    if (definition.fade !== false) current.style.opacity = '0';
+  };
+
+  const measureExpandedSize = (current: HTMLElement): number => {
+    if (!original) return 0;
+    const size = readSize(current);
+    const visibility = current.style.visibility;
+    writeSize(current, original.size);
+    current.style.visibility = original.visibility;
+    const bounds = current.getBoundingClientRect();
+    const measured =
+      axis === 'vertical'
+        ? Math.max(bounds.height, current.scrollHeight)
+        : Math.max(bounds.width, current.scrollWidth);
+    writeSize(current, size);
+    current.style.visibility = visibility;
+    return measured;
+  };
+
+  const play = async (
+    expanded: boolean,
+    signal?: AbortSignal
+  ): Promise<void> => {
+    if (signal?.aborted) return;
+    const current = resolveElement();
+    if (!current || !original) return;
+
+    const bounds = current.getBoundingClientRect();
+    const currentSize = axis === 'vertical' ? bounds.height : bounds.width;
+    const computedOpacity =
+      current.ownerDocument.defaultView?.getComputedStyle(current).opacity;
+    const currentOpacity = animation
+      ? computedOpacity || (expanded ? '0' : visibleOpacity)
+      : current.style.opacity ||
+        computedOpacity ||
+        (expanded ? '0' : visibleOpacity);
+    const token = ++operation;
+
+    animation?.cancel();
+    animation = null;
+    const targetSize = expanded ? measureExpandedSize(current) : 0;
+    current.style.overflow = 'hidden';
+    current.style.visibility = original.visibility;
+
+    if (typeof current.animate !== 'function') {
+      applyBoundary(expanded);
+      return;
+    }
+
+    const options = resolvedOptions(current, {
+      keyframes: [],
+      options: {
+        duration: 250,
+        easing: 'ease',
+        ...definition.options,
+        fill: 'both',
+      },
+      respectReducedMotion: definition.respectReducedMotion,
+    });
+    animation = current.animate(
+      [
+        {
+          [axis === 'vertical' ? 'height' : 'width']: `${currentSize}px`,
+          ...(definition.fade === false ? {} : { opacity: currentOpacity }),
+        },
+        {
+          [axis === 'vertical' ? 'height' : 'width']: `${targetSize}px`,
+          ...(definition.fade === false
+            ? {}
+            : { opacity: expanded ? visibleOpacity : '0' }),
+        },
+      ],
+      options
+    );
+    const currentAnimation = animation;
+    await waitForAnimation(currentAnimation, signal);
+    if (token !== operation || signal?.aborted) return;
+    currentAnimation.cancel();
+    if (animation === currentAnimation) animation = null;
+    applyBoundary(expanded);
+  };
+
+  return {
+    enter: (signal) => play(true, signal),
+    leave: (signal) => play(false, signal),
+    setExpanded(expanded) {
+      operation += 1;
+      animation?.cancel();
+      animation = null;
+      applyBoundary(expanded);
+    },
+    cancel() {
+      operation += 1;
+      animation?.cancel();
+      animation = null;
+      restore();
+      element = null;
+      original = null;
+    },
+  };
+}