@medyll/idae-be 0.1.0 → 0.3.0

package/README.md

@@ -1,58 +1,154 @@
-# create-svelte
 
-Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
+# @medyll/idae-be
 
-Read more about creating a library [in the docs](https://kit.svelte.dev/docs/packaging).
+A powerful DOM manipulation library with a callback-based approach for precise element targeting.
 
-## Creating a project
-
-If you're seeing this, you've probably already done this step. Congrats!
+## Installation
 
 ```bash
-# create a new project in the current directory
-npm create svelte@latest
-
-# create a new project in my-app
-npm create svelte@latest my-app
+npm install @medyll/idae-be
 ```
 
-## Developing
+## Key Features
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+- Root object persistence for consistent chaining
+- Callback-based element manipulation for precise targeting
+- Comprehensive DOM traversal and manipulation
+- Event handling, style management, and attribute control
+- Timer integration for dynamic operations
 
-```bash
-npm run dev
+## Unique Approach
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
-```
+Unlike jQuery and other chained libraries, `@medyll/idae-be` always returns the root object. This approach allows for consistent chaining while using callbacks to manipulate targeted elements. This design provides more control and clarity in complex DOM operations.
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+## Basic Usage
 
-## Building
+```javascript
+import { be, toBe } from '@medyll/idae-be';
 
-To build your library:
+be('#container')
+  .append(toBe('<div>New content</div>'), ({ be }) => {
+    be
+      .addClass('highlight')
+      .on('click', () => console.log('Clicked!'));
+  })
+  .prepend(toBe('<h1>Title</h1>'))
+  .children(undefined, ({ be }) => {
+    be.setStyle({ color: 'blue' });
+  });
+```
 
-```bash
-npm run package
+## API Reference
+
+### Core Methods
+
+- `be(selector: string | HTMLElement | HTMLElement[]): Be` - Create a new Be instance
+- `toBe(str: string | HTMLElement, options?: { tag?: string }): Be` - Convert string or HTMLElement to Be instance
+- `createBe(tagOrHtml: string, options?: Object): Be` - Create a new Be element
+
+### DOM Manipulation
+
+- `update(content: string): Be`
+- `append(content: string | HTMLElement): Be`
+- `prepend(content: string | HTMLElement): Be`
+- `insert(mode: 'afterbegin' | 'afterend' | 'beforebegin' | 'beforeend', element: HTMLElement | Be): Be`
+- `remove(): Be`
+- `replace(content: string | HTMLElement): Be`
+- `clear(): Be`
+- `normalize(): Be`
+- `wrap(tag?: string): Be`
+
+### Traversal
+
+- `up(selector?: string, callback?: HandlerCallBackFn): Be`
+- `next(selector?: string, callback?: HandlerCallBackFn): Be`
+- `previous(selector?: string, callback?: HandlerCallBackFn): Be`
+- `siblings(selector?: string, callback?: HandlerCallBackFn): Be`
+- `children(selector?: string, callback?: HandlerCallBackFn): Be`
+- `closest(selector: string, callback?: HandlerCallBackFn): Be`
+- `firstChild(selector?: string, callback?: HandlerCallBackFn): Be`
+- `lastChild(selector?: string, callback?: HandlerCallBackFn): Be`
+- `find(selector: string, callback?: HandlerCallBackFn): Be`
+- `findAll(selector: string, callback?: HandlerCallBackFn): Be`
+- `without(selector: string, callback?: HandlerCallBackFn): Be`
+
+### Styling
+
+- `setStyle(styles: Record<string, string>): Be`
+- `getStyle(property: string): string | null`
+- `unsetStyle(properties: string[]): Be`
+- `addClass(className: string): Be`
+- `removeClass(className: string): Be`
+- `toggleClass(className: string): Be`
+- `replaceClass(oldClass: string, newClass: string): Be`
+
+### Events
+
+- `on(eventName: string, handler: EventListener): Be`
+- `off(eventName: string, handler: EventListener): Be`
+- `fire(eventName: string, detail?: any): Be`
+
+### Attributes and Properties
+
+- `setAttr(name: string, value: string): Be`
+- `getAttr(name: string): string | null`
+- `deleteAttr(name: string): Be`
+- `setData(key: string, value: string): Be`
+- `getData(key: string): string | null`
+- `deleteData(key: string): Be`
+
+### Timers
+
+- `timeout(delay: number, callback: HandlerCallBackFn): Be`
+- `interval(delay: number, callback: HandlerCallBackFn): Be`
+- `clearTimeout(): Be`
+- `clearInterval(): Be`
+
+## Advanced Example
+
+```javascript
+be('#app')
+  .append(toBe('<div id="content"></div>'), ({ be  }) => {
+    be
+      .append(toBe('<button>Add Item</button>'), ({ be }) => {
+        be.on('click', () => {
+          content.append(toBe('<p>New item</p>'), ({ be }) => {
+            be
+              .addClass('item')
+              .setStyle({ color: 'blue' })
+              .on('click', ({ target }) => {
+                be(target).toggleClass('selected');
+              });
+          });
+        });
+      })
+      .children('.item', ({ be }) => {
+        be.setStyle({ padding: '5px', margin: '2px' });
+      });
+  })
+  .up(({ be }) => {
+    be.setStyle({ backgroundColor: '#f0f0f0' });
+  });
 ```
 
-To create a production version of your showcase app:
+This example demonstrates:
+1. Nested element creation and manipulation
+2. Event handling with dynamic content addition
+3. Traversal and bulk operations on children
+4. Accessing and styling parent elements
 
-```bash
-npm run build
-```
+## TypeScript Support
 
-You can preview the production build with `npm run preview`.
+This library is written in TypeScript and includes type definitions for a great developer experience.
 
-> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
+## Browser Support
 
-## Publishing
+Designed for modern browsers. May require polyfills for older browser support.
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+## Contributing
 
-To publish your library to [npm](https://www.npmjs.com):
+Contributions are welcome! Please submit pull requests or open issues on our GitHub repository.
 
-```bash
-npm publish
-```
+## License
+
+This project is licensed under the MIT License.

package/dist/be.d.ts

@@ -1,68 +1,139 @@
-type IsWhat = 'element' | 'array' | 'qy';
-declare class DataHandler {
-    private element;
-    constructor(element: Be);
-    get(key: string): string | null;
-    set(keyOrObject: string | Record<string, string>, value?: string): Be;
-    get beElem(): Be;
-    valueOf(): DOMStringMap | null;
-}
-declare class PropHandler {
-    private element;
-    constructor(element: Be);
-    get(name: string): any;
-    set(nameOrObject: string | Record<string, any>, value?: any): Be;
-    valueOf(): Record<string, any> | null;
-}
-declare class DomHandler {
-    private element;
-    constructor(element: Be);
-    update(content: string): Be;
-    get text(): string | null;
-    textUpdate(content: string): Be;
-    valueOf(): string | null;
-}
-declare class AttrHandler {
-    private element;
-    constructor(element: Be);
-    get(name?: string): string | null;
-    set(nameOrObject: string | Record<string, string>, value?: string): Be;
-    valueOf(): Record<string, string> | null;
-}
+import { type AttrHandlerHandle, AttrHandler } from './modules/attrs.js';
+import { StylesHandler, type BeStylesHandler } from './modules/styles.js';
+import type { IsWhat } from './types.js';
+import { type DataHandlerHandle, DataHandler } from './modules/data.js';
+import { EventsHandler, type EventHandlerHandle } from './modules/events.js';
+import { type ClassHandlerHandler, ClassesHandler } from './modules/classes.js';
+import { type PropsHandlerHandle } from './modules/props.js';
+import { DomHandler, type DomHandlerHandle } from './modules/dom.js';
+import { PositionHandler, type PositionHandlerHandle } from './modules/position.js';
+import { WalkHandler } from './modules/walk.js';
+import { TextHandler, type TextHandlerHandle } from './modules/text.js';
+import { TimersHandler } from './modules/timers.js';
 export declare class Be {
     node: HTMLElement | HTMLElement[] | string;
     isWhat: IsWhat;
-    attr: AttrHandler;
-    dom: DomHandler;
-    prop: PropHandler;
-    data: DataHandler;
+    BeTimer: NodeJS.Timeout | null;
+    BeInterval: NodeJS.Timeout | null;
+    styles: (actions: BeStylesHandler) => Be;
+    private styleHandler;
+    setStyle: StylesHandler['set'];
+    getStyle: StylesHandler['get'];
+    unsetStyle: StylesHandler['unset'];
+    props: (actions: PropsHandlerHandle) => Be;
+    private propHandler;
+    data: (actions: DataHandlerHandle) => Be;
+    private dataHandler;
+    setData: DataHandler['set'];
+    getData: DataHandler['get'];
+    deleteData: DataHandler['delete'];
+    getKey: DataHandler['getKey'];
+    attrs: (actions: Partial<AttrHandlerHandle>) => Be;
+    private attrHandler;
+    setAttr: AttrHandler['set'];
+    getAttr: AttrHandler['get'];
+    deleteAttr: AttrHandler['delete'];
+    position: (actions: PositionHandlerHandle) => Be;
+    private positionHandler;
+    clonePosition: PositionHandler['clonePosition'];
+    overlapPosition: PositionHandler['overlapPosition'];
+    snapTo: PositionHandler['snapTo'];
+    dom: (actions: DomHandlerHandle) => Be;
+    private domHandler;
+    update: DomHandler['update'];
+    append: DomHandler['append'];
+    prepend: DomHandler['prepend'];
+    insert: DomHandler['insert'];
+    afterBegin: DomHandler['afterBegin'];
+    afterEnd: DomHandler['afterEnd'];
+    beforeBegin: DomHandler['beforeBegin'];
+    beforeEnd: DomHandler['beforeEnd'];
+    remove: DomHandler['remove'];
+    replace: DomHandler['replace'];
+    clear: DomHandler['clear'];
+    normalize: DomHandler['normalize'];
+    wrap: DomHandler['wrap'];
+    text: (actions: TextHandlerHandle) => Be;
+    private textHandler;
+    appendText: TextHandler['append'];
+    prependText: TextHandler['prepend'];
+    events: (actions: EventHandlerHandle) => Be;
+    private eventHandler;
+    on: EventsHandler['on'];
+    off: EventsHandler['off'];
+    fire: EventsHandler['fire'];
+    classes: (actions: ClassHandlerHandler) => Be;
+    private classesHandler;
+    addClass: ClassesHandler['add'];
+    removeClass: ClassesHandler['remove'];
+    toggleClass: ClassesHandler['toggle'];
+    replaceClass: ClassesHandler['replace'];
+    walk: (actions: DataHandlerHandle) => Be;
+    private walkHandler;
+    up: WalkHandler['up'];
+    next: WalkHandler['next'];
+    without: WalkHandler['without'];
+    previous: WalkHandler['previous'];
+    siblings: WalkHandler['siblings'];
+    children: WalkHandler['children'];
+    closest: WalkHandler['closest'];
+    lastChild: WalkHandler['lastChild'];
+    firstChild: WalkHandler['firstChild'];
+    find: WalkHandler['find'];
+    findAll: WalkHandler['findAll'];
+    timers: (actions: TextHandlerHandle) => Be;
+    private timerHandler;
+    timeout: TimersHandler['timeout'];
+    interval: TimersHandler['interval'];
+    clearTimeout: TimersHandler['clearTimeout'];
+    clearInterval: TimersHandler['clearInterval'];
     private constructor();
     static elem(node: HTMLElement | HTMLElement[] | string): Be;
-    classAdd(className: string): this;
-    classRemove(className: string): this;
-    classToggle(className: string): this;
-    find(qy: string): Element | (Element | null)[] | null;
-    findAll(qy: string): Element[];
-    get html(): string | null;
-    htmlSet(content: string): this;
-    get text(): string | null;
-    textSet(content: string): this;
-    up(qy?: string): Element | (Element | null)[] | null;
-    next(qy?: string): Element | (Element | null)[] | null;
-    previous(qy?: string): Element | (Element | null)[] | null;
-    styleSet(styles: Record<string, any>): this;
-    on(eventName: string, handler: EventListener): this;
-    off(eventName: string, handler: EventListener): this;
-    append(content: string | HTMLElement): this;
-    remove(): this;
+    static createBe(tagOrHtml: CreateFragment, options?: {
+        is?: string;
+        style?: Record<string, string> | string;
+        attributes?: Record<string, string>;
+        className?: string;
+    }): Be;
+    /**
+     * Creates a new `Be` element based on the provided string or HTMLElement.
+     * If the input is an HTMLElement, it creates a new `Be` element and sets it as the child of the provided element.
+     * If the input is a string, it checks if it is a valid HTML string and creates a new `Be` element based on it.
+     * If the input is neither a string nor an HTMLElement, it creates a new `Be` element with the default tag.
+     *
+     * @param str - The string or HTMLElement to create the `Be` element from.
+     * @param options - Additional options for creating the `Be` element.
+     * @returns The created `Be` element.
+     */
+    static toBe(str: string | HTMLElement, options?: {
+        tag?: string;
+    }): Be;
+    /**
+     * setStyle Sets one or more CSS styles for the selected element(s), including CSS custom properties.
+     * @param styles An object of CSS properties and values, or a string of CSS properties and values.
+     * @param value The value for a single CSS property when styles is a property name string.
+     * @returns The Be instance for method chaining.
+     */
     fetch<T extends object>(options: {
         url: string;
         method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | 'CONNECT' | 'TRACE';
         data?: T;
         headers?: Record<string, string>;
     }): Promise<any>;
-    each(callback: (el: HTMLElement) => void): void;
-    private findWhile;
+    eachNode(callback: (el: HTMLElement) => void): void;
+    /** DOM
+     * Handles various DOM operations on the element(s).
+     * @param actions An object specifying the DOM actions to perform.
+     * @returns The Be instance for method chaining.
+     */
+    get html(): string | null;
+    private attach;
+    private handle;
 }
-export declare function be(selector: string | HTMLElement | HTMLElement[]): Be;
+type CreateFragment = `<${string}>${string}</${string}>` | string;
+/** set exports as root */
+export declare const be: typeof Be.elem;
+export declare const toBe: typeof Be.toBe;
+export declare const beId: (id: string) => Be;
+export declare const createBe: typeof Be.createBe;
 export {};