@devjuliovilla/jv-ui 1.6.0 → 1.6.2

package/README.md

@@ -45,6 +45,7 @@ export class App {}
 | Forms | `JvInput`, `JvTextarea`, `JvSelect`, `JvCheckbox`, `JvRadio`, `JvSwitch`, `JvFormContainer` |
 | Data Grid | `JvGrid` — full-featured data table (see below) |
 | Containers | `JvCard`, `JvSection`, `JvDivider` |
+| List | `JvList`, `JvListItem` — list with title, description, icons, badges, and interactive items |
 | Feedback | `JvAlert`, `JvBadge`, `JvLoader`, `JvToast` |
 | Dialogs | `JvDialog`, `JvConfirmDialog` |
 | Layout | `JvDashboardShell`, `JvSidebar`, `JvTopbar`, `JvBreadcrumb`, `JvPage` |
@@ -196,6 +197,83 @@ export class ProductsComponent {
 }
 ```
 
+## List API
+
+```typescript
+import { JvListComponent, JvListItemComponent } from '@devjuliovilla/jv-ui';
+```
+
+**JvList inputs:**
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `role` | `'list' \| 'navigation'` | `'list'` | ARIA role for the list |
+| `variant` | `'bordered' \| null` | `null` | Outer border + border-radius around the list (items always have bottom border) |
+| `ariaLabel` | `string` | `''` | Accessible label |
+
+**JvListItem inputs:**
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` (required) | — | Primary text |
+| `description` | `string` | `''` | Secondary text below title |
+| `leadingIcon` | `string \| null` | `null` | Lucide icon name on the left |
+| `disabled` | `boolean` | `false` | Gray out and block interaction |
+| `active` | `boolean` | `false` | Highlight with primary color and left border |
+
+**JvListItem outputs:**
+
+| Output | Type |
+|---|---|
+| `activated` | `void` |
+
+**Content projection:** use the `meta` attribute selector for badges, icons, or any content on the right side:
+
+```html
+<jv-list-item title="Inbox" description="New messages">
+  <jv-badge tone="primary" meta>3</jv-badge>
+  <jv-icon name="chevron-right" meta />
+</jv-list-item>
+```
+
+### Example
+
+```typescript
+import { Component } from '@angular/core';
+import { JvListComponent, JvListItemComponent, JvBadgeComponent } from '@devjuliovilla/jv-ui';
+
+@Component({
+  selector: 'app-nav-list',
+  standalone: true,
+  imports: [JvListComponent, JvListItemComponent, JvBadgeComponent],
+  template: `
+    <jv-list variant="bordered">
+      <jv-list-item
+        title="Dashboard"
+        description="Main overview"
+        leadingIcon="layout-dashboard"
+        [active]="true"
+      />
+      <jv-list-item
+        title="Notifications"
+        description="3 pending"
+        (activated)="onOpen()"
+      >
+        <jv-badge tone="primary" meta>3</jv-badge>
+      </jv-list-item>
+      <jv-list-item
+        title="Reports"
+        description="Coming soon"
+        [disabled]="true"
+      />
+    </jv-list>
+  `,
+})
+export class NavListComponent {
+  onOpen() { /* handle activation */ }
+}
+```
+
 ## Pagination API
 
 ```typescript
@@ -281,7 +359,68 @@ node tools/generate-icons.mjs
 
 This reads all SVG files from `lucide-static/icons` and produces `jv-icon-registry.ts` with the complete set (~1500 icons). Run it after updating `lucide-static` to keep icons in sync.
 
-## Services
+ ## Layout API
+
+### JvDashboardShell
+
+```typescript
+import { JvDashboardShellComponent } from '@devjuliovilla/jv-ui';
+```
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | App / brand title |
+| `sidebarSubtitle` | `string` | `''` | Subtitle below brand |
+| `brandIcon` | `string` | `'monitor'` | Brand Lucide icon |
+| `navItems` | `JvNavItem[]` | `[]` | Navigation items (supports nested children) |
+| `sidebarCollapsed` | `boolean` | `false` | Desktop sidebar collapsed state |
+| `mobileSidebarOpen` | `boolean` | `false` | Mobile sidebar open/closed |
+| `topbarTitle` | `string` | `''` | Topbar page title |
+| `topbarSubtitle` | `string` | `''` | Topbar subtitle |
+| `currentTheme` | `JvTheme` | `'light'` | Active theme value |
+| `themeOptions` | `JvThemeOption[]` | `[]` | Theme selector options |
+| `topbarActions` | `JvTopbarAction[]` | `[]` | Icon buttons in topbar |
+| `showThemeSelector` | `boolean` | `true` | Show theme pills |
+
+| Output | Description |
+|---|---|
+| `menuClick` | Hamburger button clicked — toggle mobile sidebar |
+| `mobileClose` | Backdrop clicked or navigation selected — close mobile sidebar |
+| `sidebarCollapseToggle` | Collapse toggle clicked — collapse/expand sidebar |
+| `themeChange` | Theme pill clicked |
+| `topbarActionClick` | Topbar action button clicked |
+
+**Mobile behavior:** at viewports ≤ 900px the sidebar becomes a fixed overlay with slide-in animation (`transform: translateX`) and a semi-transparent backdrop. The sidebar emits `mobileClose` when the backdrop is clicked or a nav link is followed.
+
+### JvSidebar
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Brand title |
+| `subtitle` | `string` | `''` | Brand subtitle |
+| `brandIcon` | `string` | `'monitor'` | Brand icon |
+| `items` | `JvNavItem[]` | `[]` | Navigation items |
+| `collapsed` | `boolean` | `false` | Collapse to icon-only |
+| `mobileOpen` | `boolean` | `false` | Show on mobile |
+| `ariaLabel` | `string` | `'Sidebar navigation'` | Accessible label |
+
+| Output | Description |
+|---|---|
+| `collapseToggle` | Collapse button clicked |
+| `mobileClose` | Backdrop or nav item interaction — request close |
+
+## Responsive Design
+
+The library includes basic responsive behavior:
+
+- **Breakpoints** defined as CSS custom properties: `--jv-breakpoint-sm` (640px), `--jv-breakpoint-md` (768px), `--jv-breakpoint-lg` (1024px), `--jv-breakpoint-xl` (1280px)
+- **Dashboard shell** collapses to single column at ≤ 900px; sidebar becomes a slide-in overlay with backdrop
+- **Topbar** stacks vertically at ≤ 900px
+- **Grid** pagination and toolbar stack at ≤ 640px; table scrolls horizontally with `overflow-x: auto`
+- **Flex-wrap** is used extensively for natural overflow handling
+- **Dialog** and **Toast** constrain width with `min()` to never exceed the viewport
+
+## Services
 
 | Service | Import Path | Description |
 |---|---|---|