From 56a5639c57d4b606e99a6355eeb5dc79f66d20cc Mon Sep 17 00:00:00 2001 From: FullGreaM Date: Tue, 28 Apr 2026 03:12:31 +0300 Subject: [PATCH] Update README.md for Gefest. And.. I meant at the last commit: I got tired for describing all changes --- frontend/src/modules/Gefest/README.md | 536 ++++++++------------------ 1 file changed, 169 insertions(+), 367 deletions(-) diff --git a/frontend/src/modules/Gefest/README.md b/frontend/src/modules/Gefest/README.md index ea6744d..fa0237d 100644 --- a/frontend/src/modules/Gefest/README.md +++ b/frontend/src/modules/Gefest/README.md @@ -1,361 +1,100 @@ # Gefest Framework -Gefest is a lightweight, TypeScript-based framework for building and managing HTML elements programmatically. It provides a class-based approach to create reusable UI components with built-in support for attributes, classes, styles, and event handling. +Gefest is a lightweight TypeScript framework for building HTML UI components with a class-based API. It makes it easy to create reusable elements, bind events, manage styles and classes, and rerender elements dynamically. -## Features +## Overview -- **Class-based Element Creation**: Define HTML elements as TypeScript classes -- **Attribute Management**: Easy setting, getting, and removing of HTML attributes with reserved attribute validation -- **CSS Class Handling**: Add and remove classes dynamically with full control over class lists -- **Style System**: Extensible styling with custom style classes and inline personal styles -- **Event Handling**: Multiple event listeners with custom event emission and data passing -- **Element Registration**: Automatic ID generation and DOM integration with unique identifiers -- **Primitive Components**: Pre-built HTML element wrappers for common elements -- **Dynamic Updates**: Re-render elements on the fly with automatic DOM synchronization -- **HTML Parsing**: Convert HTML strings to Gefest elements with `fromHTML()` -- **Personal Inline Styling**: Set and manage inline CSS styles directly on elements -- **Async Event System**: Promise-based event handling with custom event data +Gefest provides: +- A base `GefestElement` class for elements with nested content and attributes +- Automatic `data-gefest-id` registration for DOM element tracking +- Class and style management via helper methods +- Event handling with `onClick`, `on`, `once`, and `emit` +- Expression of UI elements as TypeScript classes instead of raw HTML strings +- A simple engine that binds click handlers and supports rerendering -## Installation - -Gefest is included as a module in this project. To use it in your TypeScript files: +## Quick Start ```typescript -import { GefestEngine, GefestElement } from './engine'; +import { GefestEngine } from './engine'; import { GefestButton } from './primitives/button'; -// ... other imports as needed + +async function main() { + const button = new GefestButton('Click me'); + button.addClass('btn'); + button.onClick = () => { + alert('Button clicked'); + }; + + document.body.innerHTML = button.build(); +} + +GefestEngine.main(main); ``` ## Core Concepts ### GefestElement -The base abstract class for all Gefest elements. It provides: - -- Content management (strings or nested elements) -- Attribute handling -- Class management -- Style application -- Event binding -- Automatic re-rendering on updates +The base class for all Gefest components. It handles: +- Content rendering from strings or nested `GefestElement` instances +- HTML attributes and reserved attribute protection +- CSS class list management +- Inline personal styles +- Event registration and emission +- Unique element registration via `GefestEngine` +- Automatic rerendering when `update()` is called ### GefestEngine -Manages the lifecycle of Gefest elements: - -- Registers elements with unique IDs -- Activates event handlers on DOM elements -- Provides the main entry point for applications -- Handles re-rendering of updated elements +The runtime engine that manages registered elements. +- `register(element)` assigns a unique `data-gefest-id` +- `activateOnClick()` binds click handlers for registered elements +- `main(mainFn)` runs your app and activates click bindings +- `render(gefestId)` rerenders one or all registered elements ### GefestStyle -Abstract base class for styling systems. Implement custom styles by extending this class. - -## Basic Usage - -### Creating Elements - -```typescript -import { GefestButton } from './primitives/button'; - -// Create a simple button -const button = new GefestButton("Click me!"); -console.log(button.build()); // -``` - -### Setting Attributes - -```typescript -const button = new GefestButton("Submit"); -button.setAttribute('type', 'submit'); -button.setAttribute('disabled', 'true'); -``` - -### Managing Classes - -```typescript -const button = new GefestButton("Button"); -button.addClass('btn'); -button.addClass('btn-primary'); -button.removeClass('btn'); -console.log(button.getClassList()); // ['btn-primary'] -``` - -### Hiding Elements - -```typescript -const button = new GefestButton("Hidden Button"); -button.isHidden = true; // Sets the 'hidden' attribute on the element -``` - -### Event Handling - -```typescript -const button = new GefestButton("Click me!"); -button.onClick = () => { - console.log('Button clicked!'); - // The framework automatically re-renders after click -}; -``` - -### Updating Elements - -```typescript -const button = new GefestButton("Initial"); -button.update(); // Re-renders the element in the DOM -``` - -### Running the Application - -```typescript -import { GefestEngine } from './engine'; - -async function main() { - // Create and configure your elements here - const button = new GefestButton("Hello World"); - button.onClick = () => alert('Hello!'); - - // Insert into DOM - document.body.innerHTML = button.build(); -} - -GefestEngine.main(main); -``` +A base class for custom styling strategies. Extend `GefestStyle` and implement `applyStyle(html, element)` to transform rendered HTML. ## Primitives -Gefest includes several pre-built primitive elements: - -### GefestButton - -Wraps HTML `'); -``` - -### Personal Styling - -Set inline styles directly on elements: - -```typescript -const button = new GefestButton("Styled"); -button.setPersonalStyle('background-color: blue; color: white; padding: 10px;'); -``` - -Remove personal styles: - -```typescript -button.setPersonalStyle(null); // Removes inline styles -``` - -### Event System - -#### Using onClick Handler - -```typescript -const button = new GefestButton("Click me"); -button.onClick = () => { - console.log('Button was clicked!'); -}; -``` - -#### Registering Multiple Event Listeners - -Use the `on()` method to register multiple event handlers for the same event: - -```typescript -const button = new GefestButton("Multi-Listener"); - -// First listener -button.on("onClick", (data) => { - console.log('Handler 1 called', data); -}); - -// Second listener -button.on("onClick", (data) => { - console.log('Handler 2 called', data); -}); -``` - -#### Registering One-Time Event Listeners - -Use the `once()` method to register an event handler that only fires once: - -```typescript -const button = new GefestButton("One-Time"); - -// This handler will only execute on the first click -button.once("onClick", (data) => { - console.log('First click only!', data); - // Handler is automatically removed after first execution -}); -``` - -#### Emitting Events - -Emit custom events with optional data: - -```typescript -const button = new GefestButton("Action"); - -button.on("onClick", (data) => { - console.log('Click event with data:', data); -}); - -button.onClick = () => { - // onClick handler is automatically emitted with event data - button.emit("onClick", { timestamp: Date.now(), action: 'clicked' }); -}; -``` - -### Element Re-rendering - -Trigger manual re-renders when element state changes: - -```typescript -const button = new GefestButton("Click me"); -let clickCount = 0; - -button.onClick = () => { - clickCount++; - // Update content or attributes - button.update(); // Re-renders in the DOM -}; -``` - -### Attribute Management - -Full control over element attributes: - -```typescript -const button = new GefestButton("Submit"); - -// Set attribute -button.setAttribute('type', 'submit'); -button.setAttribute('aria-label', 'Submit form'); - -// Get attribute -const type = button.getAttribute('type'); // 'submit' - -// Remove attribute -button.removeAttribute('disabled'); - -// Check for reserved attributes (will throw error) -// button.setAttribute('class', 'btn'); // Error: 'class' is reserved -``` +Gefest ships with simple element wrappers: +- `GefestButton` — `