Gefest/README.md

# 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.

## Features

- **Class-based Element Creation**: Define HTML elements as TypeScript classes
- **Attribute Management**: Easy setting, getting, and removing of HTML attributes
- **CSS Class Handling**: Add and remove classes dynamically
- **Style System**: Extensible styling with custom style classes
- **Event Handling**: Built-in click event management with automatic re-rendering
- **Element Registration**: Automatic ID generation and DOM integration
- **Primitive Components**: Pre-built HTML element wrappers
- **Dynamic Updates**: Re-render elements on the fly

## Installation

Gefest is included as a module in this project. To use it in your TypeScript files:

```typescript
import { GefestEngine, GefestElement } from './engine';
import { GefestButton } from './primitives/button';
// ... other imports as needed
```

## 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

### 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

### 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()); // <button data-gefest-id="gefest-abc123">Click me!</button>
```

### 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);
```

## Primitives

Gefest includes several pre-built primitive elements:

### GefestButton

Wraps HTML `<button>` elements.

```typescript
const button = new GefestButton("Click me");
button.setAttribute('type', 'submit');
```

### GefestA

Wraps HTML `<a>` elements.

```typescript
const link = new GefestA("Visit site", "https://example.com");
link.setAttribute('target', '_blank');
```

### GefestImg

Wraps HTML `<img>` elements.

```typescript
const image = new GefestImg("", "path/to/image.jpg");
image.setAttribute('alt', 'Description');
```

### Other Primitives

- `GefestP`: Paragraph (`<p>`)
- `GefestSpan`: Span (`<span>`)
- `GefestHeader`: Header (`<h1>`)
- `GefestI`: Italic (`<i>`)
- `GefestSmall`: Small text (`<small>`)
- `GefestCenter`: Centered content (`<center>`)

## Advanced Features

### Nested Elements

```typescript
const link = new GefestA("Read more", "#");
const button = new GefestButton([link, " about this"]);
```

### Custom Elements

Create your own elements by extending `GefestElement`:

```typescript
import { GefestElement } from './element';

export class GefestDiv extends GefestElement {
    protected wrapHTML(content: string): string {
        const attrString = this.attributesToString();
        return `<div ${attrString}>${content}</div>`;
    }
}
```

### Custom Styles

Implement custom styling by extending `GefestStyle`:

```typescript
import { GefestStyle, GefestElement } from './style';

export class BootstrapStyle extends GefestStyle {
    applyStyle(html: string, element?: GefestElement): string {
        // Apply Bootstrap classes or inline styles
        if (element?.getClassList().includes('btn')) {
            return html.replace('<button', '<button class="btn btn-primary"');
        }
        return html;
    }
}
```

Apply styles to elements:

```typescript
const button = new GefestButton("Styled Button");
button.style = new BootstrapStyle();
```

### Parsing HTML

Convert existing HTML strings to Gefest elements:

```typescript
const element = GefestElement.fromHTML('<button class="btn">Click</button>');
```

## API Reference

### GefestElement

#### Properties
- `gefestId: string` - Unique identifier for the element (readonly)
- `style: GefestStyle | null` - Style to apply to the element
- `onClick: (() => void) | null` - Click event handler (getter/setter)
- `isHidden: boolean` - Whether the element should be hidden (sets the 'hidden' attribute when true)

#### Methods
- `constructor(content: (GefestElement | string)[] | string)`
- `build(isFromStyle?: boolean): string`
- `update(): void` - Re-renders the element in the DOM
- `setAttribute(key: string, value: string): void`
- `getAttribute(key: string): string | undefined`
- `removeAttribute(key: string): void`
- `addClass(className: string): void`
- `removeClass(className: string): void`
- `getClassList(): string[]`
- `setPersonalStyle(style: string | null): void`

#### Static Methods
- `fromHTML(html: string): GefestElement`

### GefestEngine

#### Static Methods
- `register(element: GefestElement): string`
- `activateOnClick(): Promise<void>`
- `main(main: () => Promise<void>): Promise<void>`
- `reRenderByGI(gefestId: string): void`

### GefestStyle

#### Methods
- `applyStyle(html: string, element?: GefestElement): string`

## Examples

### Complete Application

```typescript
import { GefestEngine } from './engine';
import { GefestButton, GefestP } from './primitives';

async function main() {
    const title = new GefestP("Welcome to Gefest!");
    title.addClass('title');

    const button = new GefestButton("Get Started");
    button.addClass('start-btn');
    button.onClick = () => {
        alert('Welcome!');
    };

    // For custom elements, define them as shown above
    const container = new (class extends GefestElement {
        protected wrapHTML(content: string): string {
            const attrString = this.attributesToString();
            return `<div ${attrString}>${content}</div>`;
        }
    })([title, button]);
    container.addClass('container');

    document.body.innerHTML = container.build();
}

GefestEngine.main(main);
```

### Form Creation

```typescript
import { GefestButton } from './primitives/button';

const submitBtn = new GefestButton("Submit");
submitBtn.setAttribute('type', 'submit');
submitBtn.addClass('btn-submit');

const form = document.createElement('form');
form.innerHTML = submitBtn.build();
document.body.appendChild(form);
```

## Contributing

To add new primitives or extend the framework:

1. Create new classes extending `GefestElement`
2. Implement the `wrapHTML` method to return the appropriate HTML tag
3. Add event handling if needed
4. Test with `GefestEngine.main()`

## License

This framework is part of the AmeVox project. See project license for details.