Skip to content

Commit 2ce11af

Browse files
puikinshpuikinsh
committed
Improved docs
1 parent 5bece4a commit 2ce11af

File tree

2 files changed

+278
-374
lines changed

2 files changed

+278
-374
lines changed

‎docs/components.md‎

Lines changed: 113 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -17,52 +17,79 @@ This guide covers all the UI components available in the Metis Admin Template.
1717

1818
### Sidebar
1919

20-
The sidebar provides navigation and can be collapsed on smaller screens.
20+
The sidebar provides navigation and uses Bootstrap's collapse for submenus.
2121

2222
```html
23-
<aside class="sidebar" id="sidebar">
24-
<div class="sidebar-header">
25-
<a href="index.html" class="sidebar-brand">
26-
<span class="brand-icon">M</span>
27-
<span class="brand-text">Metis</span>
28-
</a>
23+
<aside class="admin-sidebar" id="admin-sidebar">
24+
<div class="sidebar-content">
25+
<nav class="sidebar-nav">
26+
<ul class="nav flex-column">
27+
<li class="nav-item">
28+
<a class="nav-link active" href="./index.html">
29+
<i class="bi bi-speedometer2"></i>
30+
<span>Dashboard</span>
31+
</a>
32+
</li>
33+
<!-- More nav items -->
34+
</ul>
35+
</nav>
2936
</div>
30-
<nav class="sidebar-nav">
31-
<!-- Navigation items -->
32-
</nav>
3337
</aside>
3438
```
3539

36-
**Alpine.js Integration:**
37-
```javascript
38-
Alpine.data('sidebar', () => ({
39-
collapsed: false,
40-
toggle() {
41-
this.collapsed = !this.collapsed;
42-
}
43-
}));
40+
**Submenu with Collapse:**
41+
```html
42+
<li class="nav-item">
43+
<a class="nav-link" href="#" data-bs-toggle="collapse" data-bs-target="#elementsSubmenu">
44+
<i class="bi bi-puzzle"></i>
45+
<span>Elements</span>
46+
<i class="bi bi-chevron-down ms-auto"></i>
47+
</a>
48+
<div class="collapse" id="elementsSubmenu">
49+
<ul class="nav nav-submenu">
50+
<li class="nav-item">
51+
<a class="nav-link" href="./elements.html">
52+
<i class="bi bi-grid"></i>
53+
<span>Overview</span>
54+
</a>
55+
</li>
56+
</ul>
57+
</div>
58+
</li>
4459
```
4560

4661
### Header
4762

48-
The header contains search, notifications, and user menu.
63+
The header contains the brand, search, and user controls.
4964

5065
```html
51-
<header class="main-header">
52-
<div class="header-left">
53-
<button class="sidebar-toggle" @click="toggleSidebar()">
54-
<i class="bi bi-list"></i>
55-
</button>
56-
</div>
57-
<div class="header-right">
58-
<!-- Search, notifications, user menu -->
59-
</div>
66+
<header class="admin-header">
67+
<nav class="navbar navbar-expand-lg navbar-light bg-white border-bottom">
68+
<div class="container-fluid">
69+
<!-- Brand -->
70+
<a class="navbar-brand d-flex align-items-center" href="./index.html">
71+
<img src="/assets/images/logo.svg" alt="Logo" height="32">
72+
<h1 class="h4 mb-0 fw-bold text-primary">Metis</h1>
73+
</a>
74+
75+
<!-- Search Bar with Alpine.js -->
76+
<div class="search-container flex-grow-1 mx-4" x-data="searchComponent">
77+
<input type="search" class="form-control" placeholder="Search... (Ctrl+K)"
78+
x-model="query" @input="search()" data-search-input>
79+
</div>
80+
81+
<!-- Right Side Controls -->
82+
<div class="navbar-nav flex-row">
83+
<!-- Theme toggle, notifications, user menu -->
84+
</div>
85+
</div>
86+
</nav>
6087
</header>
6188
```
6289

6390
### Cards
6491

65-
Standard card component with optional header, body, and footer.
92+
Standard Bootstrap 5 card component with custom styling.
6693

6794
```html
6895
<div class="card">
@@ -78,11 +105,7 @@ Standard card component with optional header, body, and footer.
78105
</div>
79106
```
80107

81-
**Variants:**
82-
- `.card-primary` - Primary themed card
83-
- `.card-success` - Success themed card
84-
- `.card-warning` - Warning themed card
85-
- `.card-danger` - Danger themed card
108+
**Note:** Cards in this template have `border-width: 0` and use `box-shadow` for elevation.
86109

87110
---
88111

@@ -192,45 +215,6 @@ Standard card component with optional header, body, and footer.
192215
</div>
193216
```
194217

195-
### Form Validation with Alpine.js
196-
197-
```html
198-
<form x-data="formValidation()" @submit.prevent="submit()">
199-
<div class="mb-3">
200-
<label class="form-label">Email</label>
201-
<input
202-
type="email"
203-
class="form-control"
204-
:class="{'is-invalid': errors.email}"
205-
x-model="form.email"
206-
>
207-
<div class="invalid-feedback" x-text="errors.email"></div>
208-
</div>
209-
<button type="submit" class="btn btn-primary">Submit</button>
210-
</form>
211-
```
212-
213-
```javascript
214-
Alpine.data('formValidation', () => ({
215-
form: { email: '' },
216-
errors: {},
217-
218-
validate() {
219-
this.errors = {};
220-
if (!this.form.email) {
221-
this.errors.email = 'Email is required';
222-
}
223-
return Object.keys(this.errors).length === 0;
224-
},
225-
226-
submit() {
227-
if (this.validate()) {
228-
// Handle form submission
229-
}
230-
}
231-
}));
232-
```
233-
234218
---
235219

236220
## Data Display Components
@@ -328,6 +312,18 @@ Alpine.data('formValidation', () => ({
328312

329313
### Toast Notifications (SweetAlert2)
330314

315+
The template uses a `NotificationManager` class that wraps SweetAlert2:
316+
317+
```javascript
318+
// Access via the global app instance
319+
window.AdminApp.notificationManager.success('Operation completed!');
320+
window.AdminApp.notificationManager.error('Something went wrong');
321+
window.AdminApp.notificationManager.warning('Please check your input');
322+
window.AdminApp.notificationManager.info('New update available');
323+
```
324+
325+
**Direct SweetAlert2 usage:**
326+
331327
```javascript
332328
import Swal from 'sweetalert2';
333329

@@ -348,8 +344,6 @@ Swal.fire({
348344
text: "You won't be able to revert this!",
349345
icon: 'warning',
350346
showCancelButton: true,
351-
confirmButtonColor: '#3085d6',
352-
cancelButtonColor: '#d33',
353347
confirmButtonText: 'Yes, delete it!'
354348
}).then((result) => {
355349
if (result.isConfirmed) {
@@ -386,24 +380,17 @@ Swal.fire({
386380

387381
### Tooltips
388382

383+
Tooltips are automatically initialized by `main.js`:
384+
389385
```html
390-
<button
391-
type="button"
392-
class="btn btn-secondary"
393-
data-bs-toggle="tooltip"
394-
data-bs-placement="top"
395-
title="Tooltip text"
396-
>
386+
<button type="button" class="btn btn-secondary"
387+
data-bs-toggle="tooltip"
388+
data-bs-placement="top"
389+
title="Tooltip text">
397390
Hover me
398391
</button>
399392
```
400393

401-
Initialize tooltips in JavaScript:
402-
```javascript
403-
const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]');
404-
[...tooltipTriggerList].forEach(el => new bootstrap.Tooltip(el));
405-
```
406-
407394
---
408395

409396
## Chart Components
@@ -413,7 +400,6 @@ const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]
413400
```javascript
414401
import ApexCharts from 'apexcharts';
415402

416-
// Line Chart
417403
const options = {
418404
chart: {
419405
type: 'line',
@@ -444,12 +430,7 @@ const myChart = new Chart(ctx, {
444430
labels: ['Red', 'Blue', 'Yellow', 'Green', 'Purple', 'Orange'],
445431
datasets: [{
446432
label: '# of Votes',
447-
data: [12, 19, 3, 5, 2, 3],
448-
backgroundColor: [
449-
'rgba(255, 99, 132, 0.2)',
450-
'rgba(54, 162, 235, 0.2)',
451-
// ...
452-
]
433+
data: [12, 19, 3, 5, 2, 3]
453434
}]
454435
}
455436
});
@@ -459,46 +440,42 @@ const myChart = new Chart(ctx, {
459440

460441
## Alpine.js Components
461442

462-
### Dropdown Component
443+
### Built-in Components
444+
445+
The template includes these Alpine.js components registered in `main.js`:
463446

447+
**searchComponent** - Global search functionality:
464448
```html
465-
<div x-data="{ open: false }" class="dropdown">
466-
<button @click="open = !open" class="btn btn-secondary dropdown-toggle">
467-
Dropdown
468-
</button>
469-
<ul x-show="open" @click.away="open = false" class="dropdown-menu show">
470-
<li><a class="dropdown-item" href="#">Action</a></li>
471-
<li><a class="dropdown-item" href="#">Another action</a></li>
472-
</ul>
449+
<div x-data="searchComponent">
450+
<input type="search" x-model="query" @input="search()">
451+
<template x-for="result in results">
452+
<a :href="result.url" x-text="result.title"></a>
453+
</template>
473454
</div>
474455
```
475456

476-
### Accordion Component
457+
**themeSwitch** - Dark/light mode toggle:
458+
```html
459+
<div x-data="themeSwitch">
460+
<button @click="toggle()">
461+
<i class="bi bi-sun-fill" x-show="currentTheme === 'light'"></i>
462+
<i class="bi bi-moon-fill" x-show="currentTheme === 'dark'"></i>
463+
</button>
464+
</div>
465+
```
477466

467+
**statsCounter** - Animated counter:
478468
```html
479-
<div x-data="{ active: null }">
480-
<div class="accordion-item">
481-
<h2 class="accordion-header">
482-
<button
483-
@click="active = active === 1 ? null : 1"
484-
class="accordion-button"
485-
:class="{ 'collapsed': active !== 1 }"
486-
>
487-
Section 1
488-
</button>
489-
</h2>
490-
<div x-show="active === 1" class="accordion-collapse">
491-
<div class="accordion-body">Content 1</div>
492-
</div>
493-
</div>
469+
<div x-data="statsCounter(1000, 5)">
470+
<span x-text="value"></span>
494471
</div>
495472
```
496473

497474
---
498475

499476
## Icon Usage
500477

501-
### Bootstrap Icons
478+
### Bootstrap Icons (Primary)
502479

503480
```html
504481
<!-- Inline icon -->
@@ -507,19 +484,19 @@ const myChart = new Chart(ctx, {
507484
<!-- With sizing -->
508485
<i class="bi bi-house" style="font-size: 2rem;"></i>
509486

510-
<!-- Common icons -->
511-
<i class="bi bi-person"></i> <!-- User -->
512-
<i class="bi bi-gear"></i> <!-- Settings -->
513-
<i class="bi bi-bell"></i> <!-- Notification -->
514-
<i class="bi bi-search"></i> <!-- Search -->
515-
<i class="bi bi-plus-lg"></i> <!-- Add -->
516-
<i class="bi bi-pencil"></i> <!-- Edit -->
517-
<i class="bi bi-trash"></i> <!-- Delete -->
518-
<i class="bi bi-download"></i> <!-- Download -->
519-
<i class="bi bi-upload"></i> <!-- Upload -->
487+
<!-- Common icons used in template -->
488+
<i class="bi bi-speedometer2"></i> <!-- Dashboard -->
489+
<i class="bi bi-people"></i> <!-- Users -->
490+
<i class="bi bi-graph-up"></i> <!-- Analytics -->
491+
<i class="bi bi-gear"></i> <!-- Settings -->
492+
<i class="bi bi-bell"></i> <!-- Notifications -->
493+
<i class="bi bi-search"></i> <!-- Search -->
494+
<i class="bi bi-plus-lg"></i> <!-- Add -->
495+
<i class="bi bi-pencil"></i> <!-- Edit -->
496+
<i class="bi bi-trash"></i> <!-- Delete -->
520497
```
521498

522-
### Font Awesome Icons
499+
### Font Awesome (Optional)
523500

524501
```html
525502
<i class="fa-solid fa-house"></i>
@@ -532,11 +509,11 @@ const myChart = new Chart(ctx, {
532509
## Best Practices
533510

534511
1. **Use semantic HTML** - Use appropriate elements for accessibility
535-
2. **Follow BEM naming** - Keep CSS classes organized and predictable
536-
3. **Leverage Alpine.js** - Use for interactive components instead of custom JS
512+
2. **Leverage Bootstrap 5 utilities** - Use utility classes instead of custom CSS
513+
3. **Use Alpine.js for interactivity** - Keep JavaScript simple and declarative
537514
4. **Mobile-first approach** - Design for mobile, then scale up
538-
5. **Accessibility** - Always include ARIA labels and keyboard navigation
539-
6. **Performance** - Lazy load components and images when possible
515+
5. **Accessibility** - Include ARIA labels and support keyboard navigation
516+
6. **Use the page data attribute** - Set `data-page` on body for page-specific JS
540517

541518
---
542519

0 commit comments

Comments
 (0)