@devjuliovilla/jv-ui 1.6.1 → 1.6.2

package/README.md

@@ -44,7 +44,7 @@ export class App {}
 | Buttons | `JvButton`, `JvButtonGroup`, `JvIconButton` |
 | Forms | `JvInput`, `JvTextarea`, `JvSelect`, `JvCheckbox`, `JvRadio`, `JvSwitch`, `JvFormContainer` |
 | Data Grid | `JvGrid` — full-featured data table (see below) |
-| Containeres | `JvCard`, `JvSection`, `JvDivider` |
+| Containers | `JvCard`, `JvSection`, `JvDivider` |
 | List | `JvList`, `JvListItem` — list with title, description, icons, badges, and interactive items |
 | Feedback | `JvAlert`, `JvBadge`, `JvLoader`, `JvToast` |
 | Dialogs | `JvDialog`, `JvConfirmDialog` |
@@ -359,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 |
 |---|---|---|