michaelschiemer/docs/framework/data-attributes-reference.md

# Data Attributes Reference

Complete reference for all `data-*` HTML attributes used in the framework, organized by feature area.

## Overview

All data attributes are centrally managed through PHP Enums and JavaScript Constants to ensure:
- **Type Safety**: IDE autocomplete and compile-time checks
- **Consistency**: Unified naming conventions
- **Refactoring**: Easy renaming across the entire codebase
- **Documentation**: Central overview of all attributes

## Structure

Attributes are organized into specialized Enums/Constants by feature area:

- **LiveComponent Core** (`LiveComponentCoreAttribute` / `LiveComponentCoreAttributes`)
- **LiveComponent Features** (`LiveComponentFeatureAttribute` / `LiveComponentFeatureAttributes`)
- **LiveComponent Lazy Loading** (`LiveComponentLazyAttribute` / `LiveComponentLazyAttributes`)
- **Admin Tables** (`AdminTableAttribute` / `AdminTableAttributes`)
- **Bulk Operations** (`BulkOperationAttribute` / `BulkOperationAttributes`)
- **Action Handler** (`ActionHandlerAttribute` / `ActionHandlerAttributes`)
- **Form Data** (`FormDataAttribute` / `FormDataAttributes`)
- **State Management** (`StateDataAttribute` / `StateDataAttributes`)
- **UI Enhancements** (`UIDataAttribute` / `UIDataAttributes`)
- **Module System** (`ModuleDataAttribute` / `ModuleDataAttributes`)

## Usage

### PHP Backend

```php
use App\Framework\View\ValueObjects\LiveComponentCoreAttribute;
use App\Framework\View\Dom\ElementNode;

// Get attribute name
$attr = LiveComponentCoreAttribute::LIVE_COMPONENT->value();
// Returns: "data-live-component"

// Convert to CSS selector
$selector = LiveComponentCoreAttribute::LIVE_COMPONENT->toSelector();
// Returns: "[data-live-component]"

// Convert to JavaScript dataset key
$datasetKey = LiveComponentCoreAttribute::LIVE_COMPONENT->toDatasetKey();
// Returns: "liveComponent"

// Use directly in methods (no ->value() needed!)
$element = new ElementNode('div');
$element->setAttribute(LiveComponentCoreAttribute::LIVE_COMPONENT, 'my-component');
$element->hasAttribute(LiveComponentCoreAttribute::LIVE_COMPONENT); // true
$value = $element->getAttribute(LiveComponentCoreAttribute::LIVE_COMPONENT); // "my-component"

// For array keys, ->value() is still required (PHP limitation)
$attributes = [
    LiveComponentCoreAttribute::LIVE_COMPONENT->value() => 'my-component',
    LiveComponentCoreAttribute::STATE->value() => '{}',
];
```

### JavaScript Frontend

```javascript
import { LiveComponentCoreAttributes, toDatasetKey } from '/assets/js/core/DataAttributes.js';

// Get attribute name
const attr = LiveComponentCoreAttributes.LIVE_COMPONENT;
// Returns: "data-live-component"

// Use in getAttribute
element.getAttribute(LiveComponentCoreAttributes.LIVE_COMPONENT);

// Use in dataset (with helper)
element.dataset[toDatasetKey(LiveComponentCoreAttributes.LIVE_COMPONENT)];

// Use in querySelector
document.querySelector(`[${LiveComponentCoreAttributes.LIVE_COMPONENT}]`);
```

## LiveComponent Core Attributes

Core data-* attributes for component identification, state, security, and real-time communication.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-live-component` | `LIVE_COMPONENT` | Component root element identifier |
| `data-component-id` | `COMPONENT_ID` | Unique component instance ID |
| `data-live-id` | `LIVE_ID` | Alternative component ID |
| `data-state` | `STATE` | Component state (JSON) |
| `data-live-state` | `LIVE_STATE` | Alternative state attribute |
| `data-live-content` | `LIVE_CONTENT` | Component content container |
| `data-live-action` | `LIVE_ACTION` | Action name to trigger |
| `data-csrf-token` | `CSRF_TOKEN` | Component-specific CSRF token |
| `data-sse-channel` | `SSE_CHANNEL` | Server-Sent Events channel |
| `data-poll-interval` | `POLL_INTERVAL` | Polling interval in milliseconds |
| `data-live-upload` | `LIVE_UPLOAD` | File upload handler |
| `data-live-dropzone` | `LIVE_DROPZONE` | File dropzone handler |
| `data-live-polite` | `LIVE_POLITE` | Accessibility politeness level |

## LiveComponent Feature Attributes

Advanced feature attributes (data-lc-*) for data binding, fragments, URL management, transitions, and triggers.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-lc-model` | `LC_MODEL` | Two-way data binding |
| `data-lc-fragment` | `LC_FRAGMENT` | Fragment identifier |
| `data-lc-fragments` | `LC_FRAGMENTS` | Comma-separated fragment list |
| `data-lc-key` | `LC_KEY` | Element key for DOM matching |
| `data-lc-boost` | `LC_BOOST` | Progressive enhancement |
| `data-lc-push-url` | `LC_PUSH_URL` | Push URL to browser history |
| `data-lc-replace-url` | `LC_REPLACE_URL` | Replace URL without history entry |
| `data-lc-target` | `LC_TARGET` | Target element selector |
| `data-lc-swap` | `LC_SWAP` | DOM swap strategy |
| `data-lc-swap-transition` | `LC_SWAP_TRANSITION` | Transition animation |
| `data-lc-keep-focus` | `LC_KEEP_FOCUS` | Preserve focus after update |
| `data-lc-scroll` | `LC_SCROLL` | Enable scrolling |
| `data-lc-scroll-target` | `LC_SCROLL_TARGET` | Scroll target selector |
| `data-lc-scroll-behavior` | `LC_SCROLL_BEHAVIOR` | Scroll behavior (smooth/instant) |
| `data-lc-indicator` | `LC_INDICATOR` | Loading indicator selector |
| `data-lc-trigger-delay` | `LC_TRIGGER_DELAY` | Trigger delay in milliseconds |
| `data-lc-trigger-throttle` | `LC_TRIGGER_THROTTLE` | Trigger throttle in milliseconds |
| `data-lc-trigger-once` | `LC_TRIGGER_ONCE` | Trigger only once |
| `data-lc-trigger-changed` | `LC_TRIGGER_CHANGED` | Trigger only on value change |
| `data-lc-trigger-from` | `LC_TRIGGER_FROM` | Trigger from another element |
| `data-lc-trigger-load` | `LC_TRIGGER_LOAD` | Trigger on page load |

## LiveComponent Lazy Loading Attributes

Attributes for lazy loading and island rendering of LiveComponents.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-live-component-lazy` | `LIVE_COMPONENT_LAZY` | Lazy-loaded component ID |
| `data-live-component-island` | `LIVE_COMPONENT_ISLAND` | Island component ID |
| `data-island-component` | `ISLAND_COMPONENT` | Mark as island component |
| `data-lazy-priority` | `LAZY_PRIORITY` | Loading priority (high/normal/low) |
| `data-lazy-threshold` | `LAZY_THRESHOLD` | Intersection observer threshold |
| `data-lazy-placeholder` | `LAZY_PLACEHOLDER` | Placeholder text |

## Admin Table Attributes

Data attributes for admin table functionality including sorting, pagination, searching, and column configuration.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-resource` | `RESOURCE` | Resource name |
| `data-api-endpoint` | `API_ENDPOINT` | API endpoint URL |
| `data-sortable` | `SORTABLE` | Enable sorting |
| `data-searchable` | `SEARCHABLE` | Enable searching |
| `data-paginated` | `PAGINATED` | Enable pagination |
| `data-per-page` | `PER_PAGE` | Items per page |
| `data-column` | `COLUMN` | Column identifier |
| `data-sort-dir` | `SORT_DIR` | Sort direction (asc/desc) |
| `data-page` | `PAGE` | Page number |
| `data-table-search` | `TABLE_SEARCH` | Search container selector |
| `data-table-pagination` | `TABLE_PAGINATION` | Pagination container selector |

## Bulk Operation Attributes

Data attributes for bulk operations on admin tables.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-bulk-operations` | `BULK_OPERATIONS` | Enable bulk operations |
| `data-bulk-toolbar` | `BULK_TOOLBAR` | Toolbar container selector |
| `data-bulk-count` | `BULK_COUNT` | Selected count element selector |
| `data-bulk-buttons` | `BULK_BUTTONS` | Action buttons container selector |
| `data-bulk-initialized` | `BULK_INITIALIZED` | Initialization flag |
| `data-bulk-select-all` | `BULK_SELECT_ALL` | Select all checkbox |
| `data-bulk-item-id` | `BULK_ITEM_ID` | Item ID for bulk selection |
| `data-bulk-action` | `BULK_ACTION` | Bulk action name |
| `data-bulk-method` | `BULK_METHOD` | HTTP method for bulk action |
| `data-bulk-confirm` | `BULK_CONFIRM` | Confirmation message |

## Action Handler Attributes

Data attributes for the ActionHandler system.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-action` | `ACTION` | Action name |
| `data-action-handler` | `ACTION_HANDLER` | Handler name |
| `data-action-url` | `ACTION_URL` | Direct action URL |
| `data-action-method` | `ACTION_METHOD` | HTTP method |
| `data-action-type` | `ACTION_TYPE` | Action type (e.g., "window") |
| `data-action-handler-container` | `ACTION_HANDLER_CONTAINER` | Container selector |
| `data-action-confirm` | `ACTION_CONFIRM` | Confirmation message |
| `data-action-loading-text` | `ACTION_LOADING_TEXT` | Loading text |
| `data-action-success-toast` | `ACTION_SUCCESS_TOAST` | Success message |
| `data-action-error-toast` | `ACTION_ERROR_TOAST` | Error message |

**Note**: `data-action-param-*` is a pattern (not an enum case) for dynamic parameters.

## Form Data Attributes

Data attributes for form handling and validation.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-field` | `FIELD` | Form field identifier |
| `data-selected-if` | `SELECTED_IF` | Conditional selection |
| `data-checked-if` | `CHECKED_IF` | Conditional check |

**Note**: `data-param-*` is a pattern (not an enum case) for dynamic parameters.

## State Management Attributes

Data attributes for client-side state management and data binding.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-bind` | `BIND` | Bind to state key |
| `data-bind-attr` | `BIND_ATTR` | Bind attribute to state |
| `data-bind-attr-name` | `BIND_ATTR_NAME` | Attribute name for binding |
| `data-bind-class` | `BIND_CLASS` | Bind class to state |
| `data-bind-input` | `BIND_INPUT` | Two-way input binding |
| `data-persistent` | `PERSISTENT` | Persist state in localStorage |

## UI Enhancement Attributes

Data attributes for UI enhancements including loading states, optimistic updates, confirmations, modals, themes, and other UI features.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-loading` | `LOADING` | Enable loading state |
| `data-loading-text` | `LOADING_TEXT` | Loading text |
| `data-original-text` | `ORIGINAL_TEXT` | Original text (for restoration) |
| `data-optimistic` | `OPTIMISTIC` | Enable optimistic updates |
| `data-rollback` | `ROLLBACK` | Rollback flag |
| `data-confirm-ok` | `CONFIRM_OK` | Confirm OK button |
| `data-confirm-cancel` | `CONFIRM_CANCEL` | Confirm cancel button |
| `data-close-modal` | `CLOSE_MODAL` | Close modal button |
| `data-tag` | `TAG` | Tag identifier |
| `data-theme` | `THEME` | Theme name |
| `data-theme-icon` | `THEME_ICON` | Theme icon selector |
| `data-mobile-menu-open` | `MOBILE_MENU_OPEN` | Mobile menu state |
| `data-section-id` | `SECTION_ID` | Section identifier |
| `data-tab` | `TAB` | Tab identifier |
| `data-view-mode` | `VIEW_MODE` | View mode |
| `data-asset-id` | `ASSET_ID` | Asset identifier |

## Module System Attributes

Data attributes for the JavaScript module initialization system.

| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-module` | `MODULE` | Module name |
| `data-options` | `OPTIONS` | Module options (JSON) |

## Related Documentation

- [LiveComponents API Reference](../livecomponents/api-reference.md)
- [Action Handler Guide](../javascript/action-handler-guide.md)
- [Framework Architecture](../README.md)