@ktfth/stickjs 3.0.0

package/stick.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Stick.js — declarative behavior for HTML elements
+ * https://github.com/kaiquekandykoga/Stickjs
+ */
+
+/**
+ * Stick.js 3.0.0
+ *
+ * New in 3.0: error boundary, fire(), on(), group, transition, set-aria, toggle-aria
+ */
+
+/** Synthetic event passed for the "ready", "watch", and "intersect" events */
+export type StickSyntheticEvent =
+  | { type: 'ready' }
+  | { type: 'watch' }
+  | { type: 'intersect'; entry: IntersectionObserverEntry };
+
+/**
+ * Handler function signature.
+ * @param el     The trigger element (the one with data-stick)
+ * @param param  The resolved param string ({{tokens}} already interpolated)
+ * @param event  The DOM Event, or a synthetic event object
+ * @param target The resolved data-stick-target element (falls back to el)
+ */
+export type StickHandler = (
+  el: Element,
+  param: string,
+  event: Event | StickSyntheticEvent,
+  target: Element
+) => void | Promise<void>;
+
+/**
+ * A Stick plugin. One of:
+ * - A function that receives the Stick instance and calls `.add()` on it
+ * - An object with an `install(stick)` method (Vue-style)
+ * - A plain object mapping handler names to functions
+ */
+export type StickPlugin =
+  | ((stick: StickInstance) => void)
+  | { install(stick: StickInstance): void }
+  | Record<string, StickHandler>;
+
+export interface StickInstance {
+  /** Semver string, e.g. "2.5.0" */
+  readonly version: string;
+
+  /** Register a named handler. Chainable. */
+  add(name: string, fn: StickHandler): this;
+
+  /** Unregister a named handler. Chainable. */
+  remove(name: string): this;
+
+  /**
+   * Register a plugin.
+   * Accepts: fn(stick), { install(stick) {} }, or { 'handler-name': fn, … }
+   * Chainable.
+   */
+  use(plugin: StickPlugin): this;
+
+  /**
+   * Remove all event listeners from el and clear its data-stick-bound attribute,
+   * allowing it to be re-bound cleanly. Chainable.
+   */
+  unbind(el: Element): this;
+
+  /** Enable or disable verbose console logging (dev mode). Chainable. */
+  debug(enabled?: boolean): this;
+
+  /** Register a lifecycle hook. Events: 'bind', 'unbind'. Chainable. */
+  on(event: 'bind' | 'unbind', fn: (el: Element) => void): this;
+
+  /** Frozen snapshot of all registered handler names → functions. */
+  readonly handlers: Readonly<Record<string, StickHandler>>;
+
+  /**
+   * Parse a data-stick attribute value.
+   * Returns { event, handler, param } or null if the format is invalid.
+   */
+  parse(value: string): { event: string; handler: string; param: string } | null;
+
+  /** Invoke a handler programmatically on an element. Chainable. */
+  fire(el: Element, handler: string, param?: string, event?: Event | StickSyntheticEvent): this;
+
+  /**
+   * Bind a single element (attaches its declared listeners).
+   * No-op if already bound (data-stick-bound present).
+   */
+  bind(el: Element): void;
+
+  /**
+   * Scan root for [data-stick] elements and bind them.
+   * @param root Defaults to document. Chainable.
+   */
+  init(root?: Document | Element): this;
+
+  /**
+   * Watch root for new [data-stick] elements via MutationObserver and auto-bind them.
+   * Called automatically on DOMContentLoaded.
+   * @param root Defaults to document.body. Chainable.
+   */
+  observe(root?: Element): this;
+}
+
+declare const Stick: StickInstance;
+export default Stick;