OSIT-AE-App-Svelte/documentation/AE__Components.md

# Aether Project Components

This document details the various UI components used throughout the Aether SvelteKit frontend project, categorized by their scope and functionality.

## 1. Aether Components (UI/UX)

### 1.1. System Components

These components are part of the core application shell and provide global functionalities.

- **`header`**: Application-wide header.
- **`main/module`s**: Main content area for modules.
- **`footer`**: Application-wide footer.
- **`app`**: Provides global application functionalities such as:
    - Refresh application state.
    - Clear IndexedDB.
    - Clear local storage (settings).
    - Toggle iframe visibility (also updates URL parameter).
    - Copy current URL.
    - Generate and display QR codes.
- **`menu`**: Various menus for different purposes:
    - **`mode`**: Edit mode toggle, more options (all or details).
    - **`access_type`**: Passcode input, clear access.
    - **`user`**: Sign in/out, reset password, email link, change username and email.
    - **`theme`**: Mode (light/dark), name (theme list).
- **`debug`**: Developer-facing tools:
    - Toggle debug mode (also updates URL parameter).
    - Show core and module storages.
    - Manually set initial timestamp.
- **`scroll_to`**: Navigation controls for scrolling:
    - Scroll to top of the page.
    - Scroll page up.
    - Scroll page down.
    - Scroll to bottom of the page.

### 1.2. Core Components

These are reusable components that provide common functionalities across different modules.

- **`copy_btn`**: A button to copy content to the clipboard.
    - Properties: `clipboard`, `bind:value`, `btn_text`, `btn_html`.
- **`txt_editor`**: A basic text area editor.
- **`md_editor`**: Markdown/rich-text editing handled by two active components:
    - `element_editor_codemirror.svelte` — CodeMirror 6, used for source/code editing
    - `element_editor_tiptap.svelte` — TipTap (WYSIWYG), used for rich-text content fields
- **`html_editor`**: HTML editor.
- **`media_player`**: Component for playing media files.
    - Properties: `hosted_file`, `archive_content`, `media_player`.
    - Bindings: `bind:host_id`, `bind:media_type`.
    - Status: `stopped`, `paused`, `playing`.
- **`hosted_file_li`**: Manages a list of hosted files, making them available for selection.
- **`hosted_file_link_to`**: Lists links per object, with bindings to add/remove links.
- **`upload_to_host`**: Component for uploading files to the host.
    - Handles multiple files.
    - Properties: `link_type`, `link_id`, `inner fragment` (label html).
    - Bindings: `bind:trigger`, `bind:show_spinner`, `bind:show_percent`.
    - Status: `started`, `uploading`, `finished`.
- **`upload_file_tbl`**: Table for uploaded files, includes checks for duplicate file hashes and removal from the list.
- **`download_from_host`**: Component for downloading files from the host.
    - Bindings: `bind:host_file_id`, `bind:filename`, `bind:file_ext`.
    - Properties: `btn inner fragment`.
    - Bindings: `bind:trigger`, `bind:show_spinner`, `bind:show_percent`.
    - Status: `started`, `downloading`, `finished`.
- **`data_store`**: Component for interacting with data stores.
- **`element_ae_obj_field_editor`**: Standard single-field inline editor. Replaces retired `ae_crud` v1/v2 components.
    - Props: `object_type`, `object_id`, `field_name`, `field_type`, `current_value`
    - Field types: `text`, `textarea`, `select`, `tiptap`, `checkbox`, `date`, `datetime`, `number`
    - Callbacks: `on_success`, `on_error`
    - Respects `$ae_loc.edit_mode` — edit trigger hidden when edit mode is off.
- **`sql_qry`**: Component for executing SQL queries.
- **`obj_tbl`**: Object SQL results table or similar.
- **`qr_scanner`**: Component for scanning QR codes.
- **`websocket`**: Component for WebSocket communication.

### 1.3. Main / Module Components

These are components specific to main application sections or individual modules.

- **`menu`**:
    - **`options`**: Various settings, show/hide content and options, limit, sorting options.
    - **`actions`**: Various actions, sign in/out, email.

### 1.4. Object Menu

A standardized menu for interacting with objects.

- **Properties Displayed:** `id`, `name`, `group`, `priority`, `sort`, `alert`, `hide`, `enable`, `note`.
- **Future Properties:** `ext_id`, `ext_sys_id`, `code` (not yet ready).
- **Actions:** `create`, `view`, `edit`, `update`, `hide`, `disable`, `delete`, `alert` (message), `archive` (not yet ready).
- **Future Actions:** `copy`, `import`.
- **Sort Options:**
    - `[default]`: `group > priority > sort (ASC/DESC) > alert > name`
    - `[sort_updated]`: `group > priority > sort (ASC/DESC) > alert > updated_on > created_on`
    - `[priority_updated]`: `group > priority > updated_on (ASC/DESC) > created_on`
    - `[priority_name]`: `group > priority > name (ASC/DESC) > sort > alert > updated_on > created_on`
    - `[name]`: `priority > name (ASC/DESC) > sort > alert > updated_on > created_on`
    - `[created_on]`: `priority > created_on (ASC/DESC)`
    - `[updated_on]`: `priority > updated_on (ASC/DESC) > created_on`

## 2. Pop-ups

Standardized structure for various types of pop-up elements.

- **`modal_header`**:
    - `title`
    - `close` button
- **`modal_main`**: Main content area of the modal.
- **`modal_meta`**: Meta-information section.
- **`modal_footer`**:
    - `close` button
- **`Pop-up Modal (blocking)`**: A modal that blocks interaction with the rest of the page.
    - `modal position`
- **`Pop-up Modal Inline`**: A modal that appears inline with content.
    - `inline`, `inline-block`, `block` display options.
- **`Pop-up Dialog`**: A dialog box.
    - `dialog position`

## 3. Containers

Generic container types used for layout and grouping.

### 3.1. Navigation

- `link`
- `download`

### 3.2. Forms

- `save` button/action
- `clear value` action
- `set null value` action

### 3.3. Other Containers

- `help`: Blue themed container.
- `info`: Blue themed container.
- `alert`: Yellow themed container.
- `warning`: Orange themed container.
- `error`: Red themed container.
- `message`: Green themed container.

## 4. CSS Styling for UI Elements

- **Warning/Hide Buttons:** `preset-tonal-warning hover:preset-filled-warning-500`
- **Error/Delete/Disable Buttons:** `preset-tonal-error hover:preset-filled-error-500`
- **Submenu:** `flex flex-row items-center justify-center gap-1`