@devjuliovilla/jv-ui 1.16.0 → 1.18.0

package/README.md

@@ -974,20 +974,21 @@ This reads all SVG files from `lucide-static/icons` and produces `jv-icon-regist
 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                            |
+| Input               | Type                    | Default     | Description                                 |
+| ------------------- | ----------------------- | ----------- | ------------------------------------------- |
+| `title`             | `string`                | —           | App / brand title                           |
+| `navigationMode`    | `'sidebar' \| 'topbar'` | `'sidebar'` | Main navigation presentation                |
+| `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                                                    |
 | ----------------------- | -------------------------------------------------------------- |
@@ -997,7 +998,27 @@ import { JvDashboardShellComponent } from '@devjuliovilla/jv-ui';
 | `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.
+**Mobile behavior:** at viewports ≤ 900px the selected navigation becomes a fixed overlay with slide-in animation (`transform: translateX`) and a semi-transparent backdrop. The selected navigation emits `mobileClose` when the backdrop is clicked or a nav link is followed.
+
+Use `navigationMode="topbar"` to render the brand, expandable navigation sections, and right-side actions in a horizontal menu. The default `sidebar` mode preserves the desktop sidebar and contextual topbar composition.
+
+#### Switch an existing shell to topbar
+
+The navigation data does not change. Keep the same `navItems` and set the mode explicitly:
+
+```html
+<jv-dashboard-shell
+  title="Admin"
+  navigationMode="topbar"
+  [navItems]="navItems"
+  [topbarActions]="topbarActions"
+  (topbarActionClick)="onTopbarAction($event)"
+>
+  <router-outlet />
+</jv-dashboard-shell>
+```
+
+This renders one navigation surface at a time. `sidebar` remains the default, so existing shell integrations do not need to change.
 
 ### JvSidebar
 
@@ -1016,13 +1037,55 @@ import { JvDashboardShellComponent } from '@devjuliovilla/jv-ui';
 | `collapseToggle` | Collapse button clicked                          |
 | `mobileClose`    | Backdrop or nav item interaction — request close |
 
+### JvTopbarMenu
+
+Use this component directly when the application has its own shell instead of `JvDashboardShell`:
+
+```typescript
+import { JvTopbarMenuComponent } from '@devjuliovilla/jv-ui';
+```
+
+```html
+<jv-topbar-menu
+  title="Admin"
+  [items]="navItems"
+  [actions]="topbarActions"
+  [mobileOpen]="mobileMenuOpen"
+  (menuClick)="mobileMenuOpen = !mobileMenuOpen"
+  (mobileClose)="mobileMenuOpen = false"
+  (actionClick)="onTopbarAction($event)"
+>
+</jv-topbar-menu>
+```
+
+| Input               | Type               | Default     | Description                                |
+| ------------------- | ------------------ | ----------- | ------------------------------------------ |
+| `title`             | `string`           | —           | Brand title                                |
+| `subtitle`          | `string`           | `''`        | Brand subtitle                             |
+| `brandIcon`         | `string`           | `'monitor'` | Brand icon                                 |
+| `items`             | `JvNavItem[]`      | `[]`        | Horizontal navigation with nested sections |
+| `mobileOpen`        | `boolean`          | `false`     | Mobile navigation panel state              |
+| `currentTheme`      | `JvTheme`          | `'light'`   | Active theme value                         |
+| `themeOptions`      | `JvThemeOption[]`  | `[]`        | Theme selector options                     |
+| `actions`           | `JvTopbarAction[]` | `[]`        | Right-side action buttons                  |
+| `showThemeSelector` | `boolean`          | `true`      | Show theme pills                           |
+
+| Output        | Description                                |
+| ------------- | ------------------------------------------ |
+| `menuClick`   | Mobile menu button clicked                 |
+| `mobileClose` | Backdrop or navigation item requests close |
+| `themeChange` | Theme option clicked                       |
+| `actionClick` | Right-side action clicked; emits its `id`  |
+
+The topbar keeps one expandable section open at a time. Selecting a child route closes its dropdown. At mobile widths, the navigation becomes a slide-in panel.
+
 ## 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
+- **Topbar menu** keeps the brand and actions visible and changes navigation to a slide-in panel 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
@@ -1047,6 +1110,7 @@ The library includes basic responsive behavior:
 - `aria-sort` on sortable grid headers
 - `aria-selected` on selectable grid rows
 - `aria-label` and `aria-labelledby` on interactive controls
+- Icon actions expose a visible text label alongside the icon and provide a hover/focus tooltip for screen readers
 - Supports `prefers-reduced-motion`
 
 ## Requirements