watch-selector
Version:
Runs a function when a selector is added to dom
270 lines • 8.16 kB
TypeScript
/**
* @module fluent/generator
*
* Fluent API with generator support for yield* patterns.
* Provides a chainable interface that returns async generators (Workflows).
*/
import type { ElementFromSelector } from "../types";
/**
* Workflow type for async generator functions that can be used with yield*.
*/
export type Workflow<T = void> = AsyncGenerator<(element: Element) => any, T, unknown>;
/**
* FluentGeneratorSelector provides a chainable API that returns async generators.
* Each method returns an async generator that can be used with yield* for clean composition.
*
* @example
* ```typescript
* import { watch } from 'watch-selector';
* import { gen } from 'watch-selector/fluent/generator';
*
* watch('.card', async function* () {
* // Chain operations with yield*
* yield* gen()
* .addClass('active')
* .text('Updated')
* .style({ backgroundColor: 'blue' })
* .flow();
* });
* ```
*/
export declare class FluentGeneratorSelector<El extends Element = Element> {
private operations;
/**
* Adds a text operation to the chain.
*/
text(content: string | number): FluentGeneratorSelector<El>;
/**
* Adds an HTML operation to the chain.
*/
html(content: string): FluentGeneratorSelector<El>;
/**
* Adds a class addition operation to the chain.
*/
addClass(...classes: string[]): FluentGeneratorSelector<El>;
/**
* Adds a class removal operation to the chain.
*/
removeClass(...classes: string[]): FluentGeneratorSelector<El>;
/**
* Adds a class toggle operation to the chain.
*/
toggleClass(className: string, force?: boolean): FluentGeneratorSelector<El>;
/**
* Adds a style operation to the chain.
*/
style(styles: Partial<CSSStyleDeclaration>): FluentGeneratorSelector<El>;
/**
* Adds an attribute operation to the chain.
*/
attr(name: string, value: string | number | boolean): FluentGeneratorSelector<El>;
/**
* Adds an attribute removal operation to the chain.
*/
removeAttr(name: string): FluentGeneratorSelector<El>;
/**
* Adds a property operation to the chain.
*/
prop<K extends keyof El>(name: K, value: El[K]): FluentGeneratorSelector<El>;
/**
* Adds a data attribute operation to the chain.
*/
data(key: string, value: any): FluentGeneratorSelector<El>;
/**
* Adds a value operation to the chain (for form elements).
*/
val(value: string | number): FluentGeneratorSelector<El>;
/**
* Adds a checked operation to the chain (for checkboxes/radios).
*/
checked(state: boolean): FluentGeneratorSelector<El>;
/**
* Adds a show operation to the chain.
*/
show(): FluentGeneratorSelector<El>;
/**
* Adds a hide operation to the chain.
*/
hide(): FluentGeneratorSelector<El>;
/**
* Adds a focus operation to the chain.
*/
focus(): FluentGeneratorSelector<El>;
/**
* Adds a blur operation to the chain.
*/
blur(): FluentGeneratorSelector<El>;
/**
* Adds a click handler to the chain.
*/
click(handler: (event: MouseEvent) => void): FluentGeneratorSelector<El>;
/**
* Adds a generic event listener to the chain.
*/
on(event: string, handler: EventListener): FluentGeneratorSelector<El>;
/**
* Executes all chained operations as an async generator.
* This is the method that returns the Workflow for use with yield*.
*
* @returns Async generator that executes all operations when yielded with yield*
*
* @example
* ```typescript
* watch('.button', async function* () {
* yield* gen()
* .addClass('ready')
* .text('Click me!')
* .flow();
* });
* ```
*/
flow(): Workflow<void>;
/**
* Executes operations and returns a value from the element.
*
* @param getter - Function to extract a value from the element
* @returns Async generator that returns the extracted value
*
* @example
* ```typescript
* watch('.input', async function* () {
* const value = yield* gen()
* .addClass('active')
* .flowReturn(el => (el as HTMLInputElement).value);
* });
* ```
*/
flowReturn<T>(getter: (element: El) => T): Workflow<T>;
/**
* Conditionally executes the chain based on a predicate.
*
* @param condition - Function that returns true to execute the chain
* @returns FluentGeneratorSelector for continued chaining
*
* @example
* ```typescript
* watch('.item', async function* () {
* yield* gen()
* .if(el => !el.classList.contains('processed'))
* .addClass('processed')
* .text('Done')
* .flow();
* });
* ```
*/
if(condition: (element: El) => boolean): FluentGeneratorSelector<El>;
/**
* Applies operations to child elements matching a selector.
*
* @param selector - CSS selector for child elements
* @returns FluentGeneratorSelector for continued chaining
*
* @example
* ```typescript
* watch('.container', async function* () {
* yield* gen()
* .find('.item')
* .addClass('found')
* .flow();
* });
* ```
*/
find(selector: string): FluentGeneratorSelector<El>;
/**
* Delays execution for a specified time.
*
* @param ms - Milliseconds to delay
* @returns FluentGeneratorSelector for continued chaining
*
* @example
* ```typescript
* watch('.animated', async function* () {
* yield* gen()
* .addClass('fade-in')
* .delay(300)
* .removeClass('fade-in')
* .flow();
* });
* ```
*/
delay(ms: number): FluentGeneratorSelector<El>;
}
/**
* Creates a new fluent generator chain.
*
* @returns A new FluentGeneratorSelector instance
*
* @example
* ```typescript
* import { watch } from 'watch-selector';
* import { gen } from 'watch-selector/fluent/generator';
*
* watch('.card', async function* () {
* yield* gen()
* .addClass('active')
* .text('Active Card')
* .flow();
* });
* ```
*/
export declare function gen<El extends Element = Element>(): FluentGeneratorSelector<El>;
/**
* Creates a fluent generator chain with type inference from selector.
*
* @param _selector - CSS selector (used only for type inference)
* @returns A new FluentGeneratorSelector with inferred element type
*
* @example
* ```typescript
* watch('button', async function* () {
* yield* genFor('button')
* .prop('disabled', false)
* .text('Enabled')
* .flow();
* });
* ```
*/
export declare function genFor<S extends string>(_selector: S): FluentGeneratorSelector<ElementFromSelector<S>>;
/**
* Combines multiple generator workflows into a single workflow.
*
* @param workflows - Array of workflows to combine
* @returns Combined workflow that executes all in sequence
*
* @example
* ```typescript
* import { setTextFlow, addClassFlow } from 'watch-selector/explicit/generator-support';
*
* watch('.status', async function* () {
* yield* combine([
* setTextFlow('Loading...'),
* addClassFlow('loading'),
* delayFlow(1000),
* setTextFlow('Ready'),
* removeClassFlow('loading')
* ]);
* });
* ```
*/
export declare function combine<T = void>(workflows: Array<Workflow<any>>): Workflow<T>;
/**
* Executes a workflow conditionally.
*
* @param condition - Condition to check
* @param workflow - Workflow to execute if condition is true
* @returns Workflow that conditionally executes
*
* @example
* ```typescript
* watch('.button', async function* () {
* const isActive = yield* hasClassFlow('active');
* yield* when(!isActive, addClassFlow('inactive'));
* });
* ```
*/
export declare function when<T = void>(condition: boolean | (() => boolean), workflow: Workflow<T>): Workflow<T | undefined>;
/**
* Alias for gen() with jQuery-like syntax.
*/
export declare const $gen: typeof gen;
//# sourceMappingURL=generator.d.ts.map