Skip to content

Commit 078f137

Browse files
puikinshclaude
puikinsh
and
claude
committed
docs: add documentation for all JavaScript components
Add doc pages for Layout, Card Widget, Direct Chat, Fullscreen, and Accessibility modules. Expand PushMenu docs with configuration, responsive behavior, and CSS class reference. All 7 JS components now documented and linked in the sidebar navigation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent f1e5956 commit 078f137

12 files changed

Lines changed: 693 additions & 4 deletions

File tree

‎src/html/components/dashboard/_sidenav.astro‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,7 @@ const deploymentPath = depth === 0 ? './' : '../'.repeat(depth);
231231
href={htmlPath + "/layout/collapsed-sidebar-without-hover.html"}
232232
class:list={[
233233
"nav-link",
234-
page === "collapsed-sidebar-without-hover" && "active",
234+
page === "collapsed-sidebar-without-hover" && "active"
235235
]}
236236
>
237237
<i class="nav-icon bi bi-circle"></i>
@@ -485,6 +485,24 @@ const deploymentPath = depth === 0 ? './' : '../'.repeat(depth);
485485
</p>
486486
</a>
487487
<ul class="nav nav-treeview">
488+
<li class="nav-item">
489+
<a
490+
href={htmlPath + "/docs/javascript/layout.html"}
491+
class:list={["nav-link", page === "layout" && "active"]}
492+
>
493+
<i class="nav-icon bi bi-circle"></i>
494+
<p>Layout</p>
495+
</a>
496+
</li>
497+
<li class="nav-item">
498+
<a
499+
href={htmlPath + "/docs/javascript/pushmenu.html"}
500+
class:list={["nav-link", page === "pushmenu" && "active"]}
501+
>
502+
<i class="nav-icon bi bi-circle"></i>
503+
<p>PushMenu</p>
504+
</a>
505+
</li>
488506
<li class="nav-item">
489507
<a
490508
href={htmlPath + "/docs/javascript/treeview.html"}
@@ -494,6 +512,42 @@ const deploymentPath = depth === 0 ? './' : '../'.repeat(depth);
494512
<p>Treeview</p>
495513
</a>
496514
</li>
515+
<li class="nav-item">
516+
<a
517+
href={htmlPath + "/docs/javascript/card-widget.html"}
518+
class:list={["nav-link", page === "card-widget" && "active"]}
519+
>
520+
<i class="nav-icon bi bi-circle"></i>
521+
<p>Card Widget</p>
522+
</a>
523+
</li>
524+
<li class="nav-item">
525+
<a
526+
href={htmlPath + "/docs/javascript/direct-chat.html"}
527+
class:list={["nav-link", page === "direct-chat" && "active"]}
528+
>
529+
<i class="nav-icon bi bi-circle"></i>
530+
<p>Direct Chat</p>
531+
</a>
532+
</li>
533+
<li class="nav-item">
534+
<a
535+
href={htmlPath + "/docs/javascript/fullscreen.html"}
536+
class:list={["nav-link", page === "fullscreen" && "active"]}
537+
>
538+
<i class="nav-icon bi bi-circle"></i>
539+
<p>Fullscreen</p>
540+
</a>
541+
</li>
542+
<li class="nav-item">
543+
<a
544+
href={htmlPath + "/docs/javascript/accessibility.html"}
545+
class:list={["nav-link", page === "accessibility" && "active"]}
546+
>
547+
<i class="nav-icon bi bi-circle"></i>
548+
<p>Accessibility</p>
549+
</a>
550+
</li>
497551
</ul>
498552
</li>
499553
<li class="nav-item">

‎src/html/components/javascript/accessibility.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
The Accessibility module provides WCAG 2.1 AA compliance features that are automatically initialized when AdminLTE loads.
2+
3+
##### Features
4+
5+
| Feature | WCAG Criterion | Description |
6+
|---------|---------------|-------------|
7+
| Skip Links | 2.4.1 Bypass Blocks | Adds "Skip to main content" and "Skip to navigation" links. |
8+
| Focus Management | 2.4.3 & 2.4.7 | Tab cycling, focus trapping in modals, and focus restoration. |
9+
| Keyboard Navigation | 2.1.1 Keyboard | Arrow key navigation in menus, Enter/Space for custom buttons. |
10+
| Reduced Motion | 2.3.3 Animation | Respects `prefers-reduced-motion` by disabling animations. |
11+
| Live Announcements | 4.1.3 Status Messages | Announces errors and success messages to screen readers. |
12+
| Error Identification | 3.3.1 & 3.3.2 | Auto-labels unlabelled inputs, announces form validation errors. |
13+
| Table Accessibility | 1.3.1 Info & Relationships | Adds `scope` attributes to table headers automatically. |
14+
15+
##### Configuration
16+
17+
The module is initialized in `adminlte.ts` with all features enabled by default:
18+
19+
```js
20+
initAccessibility({
21+
announcements: true,
22+
skipLinks: true,
23+
focusManagement: true,
24+
keyboardNavigation: true,
25+
reducedMotion: true
26+
})
27+
```
28+
29+
Set any option to `false` to disable that feature.
30+
31+
##### Public API
32+
33+
```js
34+
import { initAccessibility } from 'admin-lte'
35+
36+
const a11y = initAccessibility()
37+
38+
// Announce a message to screen readers
39+
a11y.announce('Item saved successfully', 'polite')
40+
a11y.announce('Form has errors', 'assertive')
41+
42+
// Focus a specific element
43+
a11y.focusElement('#my-input')
44+
45+
// Trap focus inside a container (useful for custom modals/dialogs)
46+
a11y.trapFocus(document.querySelector('.my-dialog'))
47+
48+
// Add semantic landmarks to the page
49+
a11y.addLandmarks()
50+
```
51+
52+
##### Utility Functions
53+
54+
```js
55+
import { accessibilityUtils } from 'admin-lte'
56+
57+
// Check color contrast ratio (WCAG 1.4.3)
58+
const result = accessibilityUtils.checkColorContrast('rgb(0,0,0)', 'rgb(255,255,255)')
59+
// { ratio: 21, passes: true }
60+
61+
// Check if an element is focusable
62+
accessibilityUtils.isFocusable(element)
63+
64+
// Generate a unique ID for ARIA attributes
65+
accessibilityUtils.generateId('modal') // "modal-x7k2m9p4q"
66+
```
67+
68+
##### CSS Classes
69+
70+
| Class | Description |
71+
|-------|-------------|
72+
| `skip-links` | Container for skip navigation links. |
73+
| `skip-link` | Individual skip link, visible only on focus. |
74+
| `reduce-motion` | Added to `<body>` when user prefers reduced motion. |
75+
| `sr-only` | Screen reader only content (visually hidden). |
76+
| `live-region` | ARIA live region for dynamic announcements. |
77+
78+
##### Notes
79+
80+
- The module integrates with Bootstrap's modal and dropdown events for focus management.
81+
- Modal Escape key handling is deferred to Bootstrap to respect `keyboard: false` and stacked modals.
82+
- Form validation announcements work automatically for any input with HTML5 validation attributes.

‎src/html/components/javascript/card-widget.mdx‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
The CardWidget plugin provides collapse, expand, remove, and maximize functionality for card components.
2+
3+
##### Usage
4+
5+
This plugin is activated via data attributes on buttons inside a `.card` element.
6+
7+
**Data API**
8+
9+
Add `data-lte-toggle="card-collapse"` to toggle card body visibility, `data-lte-toggle="card-remove"` to remove the card, or `data-lte-toggle="card-maximize"` to maximize it.
10+
11+
```html
12+
<div class="card">
13+
<div class="card-header">
14+
<h3 class="card-title">Card Title</h3>
15+
<div class="card-tools">
16+
<button type="button" class="btn btn-tool" data-lte-toggle="card-collapse" title="Collapse">
17+
<i data-lte-icon="expand" class="bi bi-plus-lg"></i>
18+
<i data-lte-icon="collapse" class="bi bi-dash-lg"></i>
19+
</button>
20+
<button type="button" class="btn btn-tool" data-lte-toggle="card-maximize" title="Maximize">
21+
<i class="bi bi-fullscreen"></i>
22+
</button>
23+
<button type="button" class="btn btn-tool" data-lte-toggle="card-remove" title="Remove">
24+
<i class="bi bi-x-lg"></i>
25+
</button>
26+
</div>
27+
</div>
28+
<div class="card-body">Card content here.</div>
29+
<div class="card-footer">Card footer</div>
30+
</div>
31+
```
32+
33+
##### Events
34+
35+
The plugin dispatches the following events on the trigger element:
36+
37+
| Event | Description |
38+
|-------|-------------|
39+
| `collapsed.lte.card-widget` | Fired when the card body is collapsed. |
40+
| `expanded.lte.card-widget` | Fired when the card body is expanded. |
41+
| `remove.lte.card-widget` | Fired when the card is removed. |
42+
| `maximized.lte.card-widget` | Fired when the card is maximized. |
43+
| `minimized.lte.card-widget` | Fired when the card is minimized (restored from maximized). |
44+
45+
##### CSS Classes
46+
47+
| Class | Description |
48+
|-------|-------------|
49+
| `collapsed-card` | Applied to the card when collapsed. |
50+
| `maximized-card` | Applied to the card when maximized. |
51+
52+
##### Notes
53+
54+
- Nested cards are handled correctly: collapsing a parent card does not affect child cards.
55+
- The animation speed defaults to 500ms.

‎src/html/components/javascript/direct-chat.mdx‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
The DirectChat plugin toggles the contacts pane in a direct chat widget.
2+
3+
##### Usage
4+
5+
This plugin is activated via data attributes.
6+
7+
**Data API**
8+
9+
Add `data-lte-toggle="chat-pane"` to a button inside a `.direct-chat` container to toggle the contacts list.
10+
11+
```html
12+
<div class="card direct-chat">
13+
<div class="card-header">
14+
<h3 class="card-title">Direct Chat</h3>
15+
<div class="card-tools">
16+
<button type="button" class="btn btn-tool" data-lte-toggle="chat-pane" title="Toggle Contacts">
17+
<i class="bi bi-people-fill"></i>
18+
</button>
19+
</div>
20+
</div>
21+
<div class="card-body">
22+
<div class="direct-chat-messages">
23+
<!-- Chat messages go here -->
24+
</div>
25+
<div class="direct-chat-contacts">
26+
<!-- Contacts list goes here -->
27+
</div>
28+
</div>
29+
</div>
30+
```
31+
32+
##### Events
33+
34+
| Event | Description |
35+
|-------|-------------|
36+
| `expanded.lte.direct-chat` | Fired when the contacts pane is opened. |
37+
| `collapsed.lte.direct-chat` | Fired when the contacts pane is closed. |
38+
39+
##### CSS Classes
40+
41+
| Class | Description |
42+
|-------|-------------|
43+
| `direct-chat-contacts-open` | Applied to the `.direct-chat` container when the contacts pane is visible. |

‎src/html/components/javascript/fullscreen.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
The FullScreen plugin toggles the browser's native fullscreen mode.
2+
3+
##### Usage
4+
5+
This plugin is activated via data attributes.
6+
7+
**Data API**
8+
9+
Add `data-lte-toggle="fullscreen"` to a button element. Use `data-lte-icon="maximize"` and `data-lte-icon="minimize"` on child icon elements to toggle their visibility.
10+
11+
```html
12+
<button type="button" class="btn" data-lte-toggle="fullscreen">
13+
<i data-lte-icon="maximize" class="bi bi-arrows-fullscreen"></i>
14+
<i data-lte-icon="minimize" class="bi bi-fullscreen-exit" style="display: none"></i>
15+
</button>
16+
```
17+
18+
##### Events
19+
20+
| Event | Description |
21+
|-------|-------------|
22+
| `maximized.lte.fullscreen` | Fired when entering fullscreen mode. |
23+
| `minimized.lte.fullscreen` | Fired when exiting fullscreen mode. |
24+
25+
##### Notes
26+
27+
- Requires browser support for the Fullscreen API (`document.fullscreenEnabled`).
28+
- The maximize icon is hidden when in fullscreen mode, and the minimize icon is shown (and vice versa).

‎src/html/components/javascript/layout.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
The Layout plugin manages CSS transitions during layout changes and signals when the app has finished loading.
2+
3+
##### Behavior
4+
5+
The Layout plugin performs two key tasks automatically:
6+
7+
1. **Hold Transitions** - During window resize, CSS transitions on the sidebar, navbar, and content area are temporarily disabled to prevent visual glitches. The `hold-transition` class is added to `<body>` for the duration.
8+
9+
2. **App Loaded Signal** - After a 400ms delay on DOMContentLoaded, the `app-loaded` class is added to `<body>`. Use this class in CSS to defer animations until the app is ready, preventing flicker on initial page load.
10+
11+
##### CSS Classes
12+
13+
| Class | Description |
14+
|-------|-------------|
15+
| `hold-transition` | Temporarily disables CSS transitions on layout elements. Applied during window resize. |
16+
| `app-loaded` | Added to `<body>` after the initial layout is ready. Use for entrance animations. |
17+
18+
##### Usage in CSS
19+
20+
```css
21+
/* Hide sidebar transitions until the app is loaded */
22+
body:not(.app-loaded) .app-sidebar {
23+
transition: none !important;
24+
}
25+
26+
/* Only animate after app is loaded */
27+
body.app-loaded .app-sidebar {
28+
transition: width 0.3s ease;
29+
}
30+
```
31+
32+
##### Notes
33+
34+
- The `hold-transition` class is automatically removed after 200ms (on resize) or 100ms (default).
35+
- No data attributes or manual initialization required. The plugin initializes automatically.

‎src/html/components/javascript/pushmenu.mdx‎

Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,54 @@
1-
The Pushmenu plugin is used to toggle the visibility of a sidebar menu. It allows users to collapse or expand the sidebar by clicking on a button or a link.
1+
The PushMenu plugin toggles the sidebar between expanded and collapsed states. It handles responsive behavior, optional localStorage persistence, and overlay management on mobile.
22

33
##### Usage
44

5-
This plugin can be used as the data api.
5+
This plugin is activated via data attributes on the sidebar element and toggle buttons.
66

77
**Data API**
88

9-
Add `data-lte-toggle="sidebar"` to any button or link element to activate the plugin.
9+
Add `data-lte-toggle="sidebar"` to any button or link to toggle the sidebar.
1010

1111
```html
1212
<a href="#" data-lte-toggle="sidebar">Toggle Sidebar</a>
1313
```
1414

15+
##### Configuration
16+
17+
Configure the sidebar via data attributes on the `.app-sidebar` element:
18+
19+
| Attribute | Default | Description |
20+
|-----------|---------|-------------|
21+
| `data-sidebar-breakpoint` | `992` | Screen width (px) below which the sidebar is considered mobile. |
22+
| `data-enable-persistence` | `false` | Save sidebar state to localStorage across page loads. |
23+
24+
```html
25+
<aside class="app-sidebar" data-enable-persistence="true" data-sidebar-breakpoint="768">
26+
<!-- sidebar content -->
27+
</aside>
28+
```
29+
30+
##### Responsive Behavior
31+
32+
- **Desktop** (above breakpoint): Sidebar is expanded by default. Collapse is remembered if persistence is enabled.
33+
- **Mobile** (at or below breakpoint): Sidebar is collapsed by default. An overlay appears when the sidebar is open, clicking it collapses the sidebar.
34+
35+
##### CSS Classes
36+
37+
| Class | Applied to | Description |
38+
|-------|-----------|-------------|
39+
| `sidebar-collapse` | `<body>` | Sidebar is collapsed. |
40+
| `sidebar-open` | `<body>` | Sidebar is explicitly open on mobile. |
41+
| `sidebar-mini` | `<body>` | Enables mini sidebar mode (icons only when collapsed). |
42+
| `sidebar-without-hover` | `<body>` | Prevents collapsed sidebar from expanding on hover. |
43+
| `sidebar-expand-{breakpoint}` | `<body>` | Sets the responsive breakpoint (`sm`, `md`, `lg`, `xl`, `xxl`). |
44+
45+
##### Events
46+
47+
| Event | Description |
48+
|-------|-------------|
49+
| `open.lte.push-menu` | Fired when the sidebar is expanded. |
50+
| `collapse.lte.push-menu` | Fired when the sidebar is collapsed. |
51+
1552
##### Example
1653

1754
<a href="#" data-lte-toggle="sidebar">Toggle Sidebar</a>

0 commit comments

Comments
 (0)