@familyboat/mini-framework 0.1.0

package/lib/animate/index.ts

@@ -0,0 +1,198 @@
+import { disableInteraction } from "../interaction";
+import { hideElement, showElement } from "../router";
+import { withResolvers } from "../util";
+import "./index.css";
+
+/**
+ * The CSS class and animation name used by an animation entry point.
+ * The class name and the `@keyframes` name must be identical.
+ */
+export type AnimationName = string
+
+/** Options for customizing one animation call. */
+export type AnimationOptions = {
+  /** CSS time value, such as `300ms` or `1.5s`. */
+  duration?: string
+  /** CSS time value applied before the animation starts. */
+  delay?: string
+}
+
+type ActiveAnimation = {
+  cancel: () => void
+}
+
+const activeAnimations = new WeakMap<HTMLElement, ActiveAnimation>()
+
+function animateElement(
+  root: HTMLElement,
+  animationType: AnimationName,
+  onEnd: () => void,
+  options?: AnimationOptions,
+): Promise<boolean> {
+  activeAnimations.get(root)?.cancel()
+
+  const {promise, resolve} = withResolvers<boolean>()
+  const restoreInteraction = disableInteraction(root)
+  const previousDuration = root.style.getPropertyValue('--duration')
+  const previousDelay = root.style.getPropertyValue('--delay')
+  let finished = false
+
+  if (options?.duration !== undefined) {
+    root.style.setProperty('--duration', options.duration)
+  }
+  if (options?.delay !== undefined) {
+    root.style.setProperty('--delay', options.delay)
+  }
+
+  const finish = (completed: boolean) => {
+    if (finished) {
+      return
+    }
+    finished = true
+    root.removeEventListener('animationend', handleAnimationEnd)
+    root.removeEventListener('animationcancel', handleAnimationCancel)
+    root.classList.remove(animationType)
+    if (completed) {
+      onEnd()
+    }
+    restoreInteraction()
+    root.style.setProperty('--duration', previousDuration)
+    root.style.setProperty('--delay', previousDelay)
+    if (activeAnimations.get(root)?.cancel === cancel) {
+      activeAnimations.delete(root)
+    }
+    resolve(completed)
+  }
+
+  const cancel = () => finish(false)
+
+  const handleAnimationEnd = (event: AnimationEvent) => {
+    if (event.target === root && event.animationName === animationType) {
+      finish(true)
+    }
+  }
+
+  const handleAnimationCancel = (event: AnimationEvent) => {
+    if (event.target === root && event.animationName === animationType) {
+      finish(false)
+    }
+  }
+
+  root.addEventListener('animationend', handleAnimationEnd)
+  root.addEventListener('animationcancel', handleAnimationCancel)
+  activeAnimations.set(root, {cancel})
+  root.classList.add(animationType)
+
+  return promise
+}
+
+/**
+ * Shows an element with any CSS animation class.
+ * The class name must match the CSS animation name.
+ * Starting another animation on the same element cancels the previous one.
+ *
+ * @param root Element to animate.
+ * @param enterType CSS class and animation name to apply.
+ * @param options Optional duration and delay overrides.
+ * @returns A promise that resolves to `true` when the animation ends, or
+ * `false` when it is cancelled.
+ */
+export function enterElement(
+  root: HTMLElement,
+  enterType: AnimationName,
+  options?: AnimationOptions,
+): Promise<boolean> {
+  showElement(root)
+  return animateElement(root, enterType, () => {}, options)
+}
+
+/**
+ * Hides an element after any CSS animation class completes.
+ * The class name must match the CSS animation name.
+ * Starting another animation on the same element cancels the previous one.
+ *
+ * @param root Element to animate and hide.
+ * @param leaveType CSS class and animation name to apply.
+ * @param options Optional duration and delay overrides.
+ * @returns A promise that resolves to `true` when the animation ends, or
+ * `false` when it is cancelled.
+ */
+export function leaveElement(
+  root: HTMLElement,
+  leaveType: AnimationName,
+  options?: AnimationOptions,
+): Promise<boolean> {
+  return animateElement(root, leaveType, () => hideElement(root), options)
+}
+
+/**
+ * Shows an element with a fade-in animation.
+ *
+ * @param root Element to animate.
+ * @param options Optional duration and delay overrides.
+ * @returns A promise that resolves to `true` when the animation ends, or
+ * `false` when it is cancelled.
+ */
+export function fadeIn(root: HTMLElement, options?: AnimationOptions): Promise<boolean> {
+  return enterElement(root, 'fade-in', options)
+}
+
+/**
+ * Hides an element with a fade-out animation.
+ *
+ * @param root Element to animate and hide.
+ * @param options Optional duration and delay overrides.
+ * @returns A promise that resolves to `true` when the animation ends, or
+ * `false` when it is cancelled.
+ */
+export function fadeOut(root: HTMLElement, options?: AnimationOptions): Promise<boolean> {
+  return leaveElement(root, 'fade-out', options)
+}
+
+/**
+ * Shows an element by sliding in from the left.
+ *
+ * @param root Element to animate.
+ * @param options Optional duration and delay overrides.
+ * @returns A promise that resolves to `true` when the animation ends, or
+ * `false` when it is cancelled.
+ */
+export function leftSlideIn(root: HTMLElement, options?: AnimationOptions): Promise<boolean> {
+  return enterElement(root, 'left-slide-in', options)
+}
+
+/**
+ * Shows an element by sliding in from the right.
+ *
+ * @param root Element to animate.
+ * @param options Optional duration and delay overrides.
+ * @returns A promise that resolves to `true` when the animation ends, or
+ * `false` when it is cancelled.
+ */
+export function rightSlideIn(root: HTMLElement, options?: AnimationOptions): Promise<boolean> {
+  return enterElement(root, 'right-slide-in', options)
+}
+
+/**
+ * Hides an element by sliding out to the left.
+ *
+ * @param root Element to animate and hide.
+ * @param options Optional duration and delay overrides.
+ * @returns A promise that resolves to `true` when the animation ends, or
+ * `false` when it is cancelled.
+ */
+export function leftSlideOut(root: HTMLElement, options?: AnimationOptions): Promise<boolean> {
+  return leaveElement(root, 'left-slide-out', options)
+}
+
+/**
+ * Hides an element by sliding out to the right.
+ *
+ * @param root Element to animate and hide.
+ * @param options Optional duration and delay overrides.
+ * @returns A promise that resolves to `true` when the animation ends, or
+ * `false` when it is cancelled.
+ */
+export function rightSlideOut(root: HTMLElement, options?: AnimationOptions): Promise<boolean> {
+  return leaveElement(root, 'right-slide-out', options)
+}

package/lib/index.ts

@@ -0,0 +1,25 @@
+export {
+  Route,
+  Router,
+  hideElement,
+  showElement,
+} from "./router";
+export type { RouteProps } from "./router";
+export {
+  fadeIn,
+  fadeOut,
+  enterElement,
+  leaveElement,
+  leftSlideIn,
+  rightSlideIn,
+  leftSlideOut,
+  rightSlideOut,
+} from "./animate";
+export type { AnimationOptions } from "./animate";
+export type { AnimationName } from "./animate";
+export { Modal } from "./modal";
+export type { ModalProps } from "./modal";
+export { Toast } from "./toast";
+export type { ToastKind, ToastPosition, ToastProps } from "./toast";
+export { html, renderTemplate, withResolvers } from './util'
+export { disableInteraction } from './interaction';

package/lib/interaction/index.ts

@@ -0,0 +1,16 @@
+type InteractionState = {
+  inert: boolean
+}
+
+/** Disables interaction and returns a function that restores the previous state. */
+export function disableInteraction(root: HTMLElement): () => void {
+  const previousState: InteractionState = {
+    inert: root.inert,
+  }
+
+  root.inert = true
+
+  return () => {
+    root.inert = previousState.inert
+  }
+}

package/lib/modal/index.css

@@ -0,0 +1,5 @@
+.modal {
+  position: fixed;
+  inset: 0;
+  z-index: var(--z-index-modal);
+}

package/lib/modal/index.ts

@@ -0,0 +1,153 @@
+import { hideElement } from "../router";
+import "./index.css";
+
+export type ModalProps = {
+  name: string;
+};
+
+const modalCache = new Map<string, Modal>();
+
+export abstract class Modal {
+  private _props: ModalProps;
+  private _initialized = false;
+  private _destroyed = false;
+  private _operationId = 0;
+
+  protected get root() {
+    return this._root;
+  }
+  private _root: HTMLElement;
+
+  protected constructor(props: ModalProps) {
+    this._props = props;
+    if (modalCache.has(this._props.name)) {
+      throw new Error(`The modal named ${this._props.name} has existed.`);
+    }
+
+    this._root = document.createElement("div");
+    this._root.classList.add(`modal-${this._props.name}`, "modal");
+    hideElement(this._root);
+    document.body.appendChild(this._root);
+  }
+
+  protected abstract render(): void;
+
+  /** Creates, initializes, and registers a modal instance. */
+  static create<T extends Modal>(this: any, props: ModalProps): T {
+    const modal = new this(props);
+    modal.initialize();
+    return modal;
+  }
+
+  /** Shows this modal and starts a new modal operation. */
+  show(): void {
+    this.assertUsable();
+    const operationId = this.beginOperation();
+    this.onShow(operationId);
+  }
+
+  /** Hides this modal and starts a new modal operation. */
+  hide(): void {
+    this.assertUsable();
+    const operationId = this.beginOperation();
+    this.onHide(operationId);
+  }
+
+  protected abstract onShow(operationId: number): void;
+  protected abstract onHide(operationId: number): void;
+
+  /** Renders and registers this modal once. */
+  protected initialize(): void {
+    if (this._destroyed) {
+      throw new Error(`The modal named ${this._props.name} has been destroyed.`);
+    }
+
+    if (this._initialized) {
+      throw new Error(`The modal named ${this._props.name} has already been initialized.`);
+    }
+
+    try {
+      this.render();
+      if (modalCache.has(this._props.name)) {
+        throw new Error(`The modal named ${this._props.name} has existed.`);
+      }
+      modalCache.set(this._props.name, this);
+      this._initialized = true;
+    } catch (error) {
+      this._initialized = false;
+      if (modalCache.get(this._props.name) === this) {
+        modalCache.delete(this._props.name);
+      }
+      this._root.remove();
+      throw error;
+    }
+  }
+
+  /** Hook for subclasses to release resources they created. */
+  protected dispose(): void {}
+
+  /** Starts a new operation and invalidates callbacks from earlier operations. */
+  protected beginOperation(): number {
+    this._operationId += 1;
+    return this._operationId;
+  }
+
+  /** Returns whether an asynchronous operation is still current. */
+  protected isCurrentOperation(operationId: number): boolean {
+    return operationId === this._operationId;
+  }
+
+  /** Throws when a modal is used after it has been destroyed. */
+  private assertUsable(): void {
+    if (this._destroyed) {
+      throw new Error(`The modal named ${this._props.name} has been destroyed.`);
+    }
+  }
+
+  /** Shows a registered modal by name. */
+  static show(modalName: string): void {
+    const modal = modalCache.get(modalName);
+    if (!modal) {
+      throw new Error(`Can't show unknown modal: ${modalName}.`);
+    }
+
+    modal.show();
+  }
+
+  /** Hides a registered modal by name. */
+  static hide(modalName: string): void {
+    const modal = modalCache.get(modalName);
+    if (!modal) {
+      throw new Error(`Can't hide unknown modal: ${modalName}.`);
+    }
+
+    modal.hide();
+  }
+
+  /** Destroys a registered modal by name. */
+  static destroy(modalName: string): void {
+    const modal = modalCache.get(modalName);
+    if (!modal) {
+      throw new Error(`Can't destroy unknown modal: ${modalName}.`);
+    }
+
+    modal.destroy();
+  }
+
+  /** Removes this modal from the registry and document. */
+  destroy(): void {
+    if (this._destroyed) {
+      return;
+    }
+
+    this._destroyed = true;
+    this.beginOperation();
+    this.dispose();
+
+    if (modalCache.get(this._props.name) === this) {
+      modalCache.delete(this._props.name);
+    }
+
+    this._root.remove();
+  }
+}

package/lib/router/index.css

@@ -0,0 +1,9 @@
+.page {
+  position: absolute;
+  inset: 0;
+  z-index: var(--z-index-page);
+}
+
+.hide {
+  display: none;
+}

package/lib/router/index.ts

@@ -0,0 +1,130 @@
+import "./index.css";
+
+/** Configuration required to create a route. */
+export type RouteProps = {
+  name: string;
+};
+
+const routeCache = new Map<string, Route>();
+
+export abstract class Route {
+  private _props: RouteProps;
+  private _initialized = false;
+  private _operationId = 0;
+  protected get root() {
+    return this._root;
+  }
+  private _root: HTMLElement;
+
+  /**
+   * Base constructor for route factories.
+   * Concrete routes can use the inherited static `create()` method instead of
+   * exposing their own factory logic.
+   */
+  protected constructor(props: RouteProps) {
+    this._props = props;
+    if (routeCache.has(this._props.name)) {
+      throw new Error(`The route named ${this._props.name} has existed.`);
+    }
+
+    this._root = document.createElement("div");
+    this._root.classList.add(`page-${this._props.name}`, "page");
+    hideElement(this._root);
+    document.body.appendChild(this._root);
+  }
+
+  protected abstract render(): void;
+
+  /** Optional hook called when this route becomes active. */
+  protected abstract onEnter(operationId?: number): void
+
+  /** Optional hook called when this route becomes inactive. */
+  protected abstract onLeave(operationId?: number): void
+
+  /** Creates, initializes, and registers a route instance. */
+  static create<T extends Route>(this: any, props: RouteProps): T {
+    const route = new this(props);
+    route.initialize();
+    return route;
+  }
+
+  /** Renders and registers this route once. Called by a concrete route factory. */
+  protected initialize(): void {
+    if (this._initialized) {
+      throw new Error(`The route named ${this._props.name} has already been initialized.`);
+    }
+
+    try {
+      this.render();
+      if (routeCache.has(this._props.name)) {
+        throw new Error(`The route named ${this._props.name} has existed.`);
+      }
+      routeCache.set(this._props.name, this);
+      this._initialized = true;
+    } catch (error) {
+      this._root.remove();
+      throw error;
+    }
+  }
+
+  /** Starts a new operation and invalidates callbacks from earlier operations. */
+  protected beginOperation(): number {
+    this._operationId += 1;
+    return this._operationId;
+  }
+
+  /** Returns whether an asynchronous operation is still current. */
+  protected isCurrentOperation(operationId: number): boolean {
+    return operationId === this._operationId;
+  }
+
+  /** Shows the route and runs the enter hook. */
+  show(): void {
+    const operationId = this.beginOperation();
+    this.onEnter(operationId);
+  }
+
+  /** Hides the route and runs the leave hook. */
+  hide(): void {
+    const operationId = this.beginOperation();
+    this.onLeave(operationId);
+  }
+}
+
+export class Router {
+  private static _previousRoute: Route | null = null;
+  private static _navigationId = 0;
+
+  /**
+   * Navigates to a registered route.
+   * Repeated navigation to the active route is ignored.
+   */
+  static navigate(name: string): void {
+    if (!routeCache.has(name)) {
+      throw new Error(`Can't navigate to unknown route: ${name}.`);
+    }
+
+    const route = routeCache.get(name)!;
+    if (this._previousRoute === route) {
+      return;
+    }
+
+    this._navigationId += 1;
+    this._previousRoute?.hide();
+    route.show();
+    this._previousRoute = route;
+  }
+
+  /** Returns the id of the most recent route navigation. */
+  static getNavigationId(): number {
+    return this._navigationId;
+  }
+}
+
+export function hideElement(root: HTMLElement) {
+  root.classList.add("hide");
+}
+
+export function showElement(root: HTMLElement) {
+  root.classList.remove("hide");
+}

package/lib/toast/index.css

@@ -0,0 +1,57 @@
+.toast-container {
+  position: fixed;
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  z-index: var(--z-index-toast);
+  pointer-events: none;
+}
+
+.toast-container--top {
+  top: 24px;
+}
+
+.toast-container--bottom {
+  bottom: 24px;
+}
+
+.toast {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  min-width: 240px;
+  max-width: 420px;
+  padding: 12px 16px;
+  border-radius: 12px;
+  box-shadow: 0 8px 20px rgba(0, 0, 0, 0.18);
+  color: #ffffff;
+  background: rgba(31, 41, 55, 0.96);
+  pointer-events: auto;
+}
+
+.toast--success {
+  background: rgba(22, 163, 74, 0.96);
+}
+
+.toast--error {
+  background: rgba(220, 38, 38, 0.96);
+}
+
+.toast__message {
+  flex: 1;
+  font-size: 14px;
+  line-height: 1.4;
+}
+
+.toast__close {
+  border: 0;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font-size: 18px;
+  line-height: 1;
+  opacity: 0.85;
+}