@ojiepermana/angular-navigation 22.0.27

package/README.md

@@ -0,0 +1,231 @@
+# Navigation
+
+`@ojiepermana/angular-navigation` renders input-driven navigation with configurable types and instance-aware state.
+
+```ts
+import {
+  NavigationContainerComponent,
+  NavigationSidebarComponent, // type: NavigationDockbar/Navbar/FlyoutComponent
+  NavigationHeaderComponent,
+  NavigationContentComponent,
+  NavigationFooterComponent,
+  type NavigationItem,
+} from '@ojiepermana/angular-navigation';
+import { NavigationService } from '@ojiepermana/angular-navigation/service';
+
+const items: NavigationItem[] = [
+  { id: 'dashboard', title: 'Dashboard', link: '/dashboard', icon: 'dashboard' },
+  {
+    id: 'reports',
+    title: 'Reports',
+    type: 'collapsible',
+    children: [{ id: 'monthly', title: 'Monthly', link: '/reports/monthly' }],
+  },
+];
+```
+
+```html
+<Navigation id="erp-sidebar" [data]="items" class="h-full">
+  <NavigationSidebar>
+    <NavigationHeader class="px-1" [toggle]="true">
+      <div class="text-sm font-semibold">Workspace</div>
+    </NavigationHeader>
+
+    <NavigationContent />
+
+    <NavigationFooter class="p-3">
+      <button type="button">Sign out</button>
+    </NavigationFooter>
+  </NavigationSidebar>
+</Navigation>
+
+<Navigation id="erp-topbar" [data]="items">
+  <NavigationNavbar />
+</Navigation>
+```
+
+Type dipilih lewat komponen anak deklaratif — `NavigationSidebar`, `NavigationDockbar`, `NavigationNavbar`, atau `NavigationFlyout` — satu type hidup per `<Navigation>`. Di dalam type, `NavigationHeader` dan `NavigationFooter` opsional, sedangkan `NavigationContent` selalu dirender (otomatis dibuat bila tidak diproyeksikan).
+
+## API Notes
+
+- `data` is the preferred source of navigation data.
+- `items` is still accepted as a compatibility alias while consumers migrate.
+- Type is declared by the child component: `NavigationSidebar`/`NavigationDockbar` (vertical), `NavigationNavbar`/`NavigationFlyout` (horizontal). Orientation is implied by the type child.
+- `id` identifies a navigation instance so multiple navs can keep distinct service state.
+- `position` on `NavigationSidebar`/`NavigationDockbar` accepts `left` or `right` (vertical).
+- `collapsed` on `NavigationSidebar` controls the icon-only sidebar state.
+- `mode` on `NavigationDockbar` accepts `sticky` or `drawer`.
+- `ariaLabel` overrides the host navigation label and defaults to `Primary navigation`.
+- `label` on `NavigationFlyout` sets the single trigger label and defaults to `Menu`.
+- `icon` on `NavigationFlyout` renders a Material Symbols icon on the trigger; `icon-position` (`start`/`end`) sets its placement and `icon-only` hides the label visually while keeping it as the accessible name (compact mode is always icon-only and falls back to the `menu` icon).
+- `nav-position` on `NavigationNavbar`/`NavigationFlyout` accepts `top` (default) or `bottom`. With `bottom`, the navbar grid panel opens upward with squared bottom corners, and the flyout panel anchors to the container's bottom edge with the tab row docked at the bottom — seamless for bars placed below the content.
+- `nav-type-style` on `NavigationNavbar`/`NavigationFlyout` accepts `default` or `border-rail`. `border-rail` squares the panel (no rounding), frames entry icons with dimmed blueprint-style rail lines plus dashed center cross lines (instead of rounded boxes), renders the nested-collapse rail dashed, and replaces hover/active backgrounds with primary-colored text. `default` keeps the current visuals.
+- The `navbar` type renders root items inline immediately; clicking a group (hover does not open it) opens a full-width grid panel below the bar with the same flyout-style entries, responsive columns, and nested collapse.
+- The `flyout` type renders one trigger button that opens a floating panel overlaying the parent container exactly (same top position and width, covering the trigger with no visible gap; `display: contents` wrappers are skipped when measuring the container). Root items with children become the horizontal navigation inside the panel (their `icon` renders in the row), their children render as title/subtitle entries in a responsive grid (1 column on mobile, 2 from `sm`, 3 from `md`, 4 from `lg` and up; `columns` caps the maximum at 1–4), and deeper children render as a vertical collapse below their entry — expanded by default every time the panel opens, collapsible per entry via the chevron, with the child icons aligned on the same vertical line as the parent entry icon. The panel closes on `Escape`, outside clicks, the close button, or leaf selection.
+- Items with children render a `chevron_right` icon pinned at the right edge and vertically centered: it points right by default and rotates down (in place, no layout shift) only while open — hover does not move it. This applies to flyout tabs and entries, navbar branch triggers, and collapsible items.
+- Angular Router is supported for internal links through `link`, `queryParams`, `fragment`, `exactMatch`, and `isActiveMatchOptions`.
+- External links can use `href` or `link` with `externalLink: true`.
+- `activeIds` lets consumers force active state by nav id or normalized key.
+- `activeUrl` lets consumers drive active matching without relying on the current router URL.
+- `openedIds` owns collapsible state and supports two-way binding.
+- `previewExpanded` on `NavigationSidebar` forces a collapsed sidebar instance to render in expanded-preview mode.
+- `itemSelected` emits for action, router, and external items.
+- `class` applies classes to the host `nav` element.
+- `itemClass` applies shared classes to rendered items.
+- `nav-group-class` (`groupClass`) applies Tailwind classes to the container of each horizontal group — the flyout tab `<li>` and the navbar group `<li>` — so consumers can tune height, padding, or borders of the group container. Per-group control is also available via `item.classes.container`.
+- `compact` is still supported as a compatibility alias for collapsed vertical sidebars.
+- `nav-sidebar-collapse` on `NavigationSidebar` enables hover-preview behavior for collapsed vertical sidebars.
+- `collapse-tree` accepts `stairs` or `straight` for nested collapsible connector styling.
+- `NavigationHeader` is optional, accepts Tailwind classes through `class`, and can render a built-in collapse toggle with `[toggle]="true"`.
+- `NavigationFooter` is optional and accepts Tailwind classes through `class`.
+- `NavigationContent` wraps the active navigation renderer and owns the scrollable region between the optional header and footer slots. It is rendered automatically by the type component when not projected, and accepts `class` when used explicitly.
+
+## Nav Inputs And Outputs
+
+Inputs pada `<Navigation>` (container):
+
+| API               | Type                                               | Notes                                                                           |
+| ----------------- | -------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `id`              | `string`                                           | Navigation instance id. `main` is the only id persisted to `localStorage`.      |
+| `data`            | `readonly NavigationItem[]`                        | Preferred source of items.                                                      |
+| `items`           | `readonly NavigationItem[]`                        | Compatibility alias for `data`.                                                 |
+| `ariaLabel`       | `string`                                           | Accessible label on the host navigation landmark.                               |
+| `compact`         | `boolean`                                          | Compatibility alias for collapsed-rail item layout.                             |
+| `collapse-tree`   | `stairs \| straight`                               | Controls nested connector styling for collapsible items.                        |
+| `class`           | `string`                                           | Extra classes for the host `nav`.                                               |
+| `itemClass`       | `string`                                           | Shared classes applied to rendered nav items.                                   |
+| `nav-group-class` | `string`                                           | Classes for each horizontal group container (flyout tab / navbar group `<li>`). |
+| `activeIds`       | `ReadonlySet<string> \| readonly string[] \| null` | Explicit active state override by item id or normalized key.                    |
+| `activeUrl`       | `string \| null`                                   | Explicit URL used during active matching.                                       |
+| `openedIds`       | `readonly string[]`                                | Two-way bound open state for collapsible items.                                 |
+| `itemSelected`    | `NavigationSelection`                              | Emits when a leaf item is selected.                                             |
+
+Inputs pada komponen type:
+
+| Component           | API                    | Type                       | Notes                                                                         |
+| ------------------- | ---------------------- | -------------------------- | ----------------------------------------------------------------------------- |
+| `NavigationSidebar` | `position`             | `left \| right \| null`    | Side the rail docks to.                                                       |
+| `NavigationSidebar` | `collapsed`            | `boolean \| null`          | Controls collapsed vertical sidebar state.                                    |
+| `NavigationSidebar` | `nav-sidebar-collapse` | `boolean`                  | Enables hover-driven preview expansion on collapsed sidebars.                 |
+| `NavigationSidebar` | `previewExpanded`      | `boolean`                  | Forces a collapsed sidebar to render expanded for preview.                    |
+| `NavigationDockbar` | `mode`                 | `sticky \| drawer \| null` | Docked aside beside the rail, or overlay drawer.                              |
+| `NavigationDockbar` | `position`             | `left \| right \| null`    | Side the rail docks to.                                                       |
+| `NavigationNavbar`  | `nav-type-style`       | `default \| border-rail`   | Style variant. `border-rail` = squared panel, dashed icon rails, no hover bg. |
+| `NavigationFlyout`  | `label`                | `string`                   | Trigger label. Defaults to `Menu`.                                            |
+| `NavigationFlyout`  | `nav-type-style`       | `default \| border-rail`   | Style variant. `border-rail` = squared panel, dashed icon rails, no hover bg. |
+
+Semua type juga menerima `class` untuk kelas tambahan pada elemen shell-nya.
+
+## NavigationItem
+
+`NavigationItem` supports deeper trees, mixed item kinds, and both router and external navigation.
+
+| Field                                                                | Type                                                                                         | Notes                                                                              |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `id`                                                                 | `string`                                                                                     | Stable item id. Reused for active/open state when present.                         |
+| `type`                                                               | `item \| basic \| aside \| group \| collapsible \| collapsable \| mega \| divider \| spacer` | `collapsable` is accepted as a compatibility alias of `collapsible`.               |
+| `title`, `subtitle`, `tooltip`                                       | `string`                                                                                     | Primary labels and optional compact tooltip.                                       |
+| `active`, `disabled`                                                 | `boolean`                                                                                    | Explicit active and disabled flags.                                                |
+| `icon`                                                               | `string`                                                                                     | Rendered through the default icon slot unless overridden.                          |
+| `badge`                                                              | `{ title?: string; classes?: string }`                                                       | Small label rendered beside the item title.                                        |
+| `classes`                                                            | `{ wrapper?, container?, icon?, title?, subtitle? }`                                         | Per-item class overrides. `container` targets the horizontal group `<li>` wrapper. |
+| `meta`                                                               | `Record<string, unknown>`                                                                    | Consumer-owned metadata bag.                                                       |
+| `isHidden`                                                           | `(item) => boolean`                                                                          | Filters items at normalization time.                                               |
+| `link`                                                               | `string \| readonly unknown[] \| UrlTree`                                                    | Angular Router link target.                                                        |
+| `href`                                                               | `string`                                                                                     | Direct external URL.                                                               |
+| `queryParams`, `queryParamsHandling`, `fragment`, `preserveFragment` | Router options                                                                               | Extra Angular Router navigation options.                                           |
+| `externalLink`, `target`, `rel`                                      | link options                                                                                 | External navigation behavior and rel handling.                                     |
+| `exactMatch`, `isActiveMatchOptions`                                 | Router match options                                                                         | Control how router activity is resolved.                                           |
+| `action`                                                             | `(item) => void`                                                                             | Callback for action-driven leaf items.                                             |
+| `columns`                                                            | `number`                                                                                     | Column count for `mega` style items.                                               |
+| `children`                                                           | `readonly NavigationItem[]`                                                                  | Nested items. Trees can be deeper than one level.                                  |
+
+## Public Shell APIs
+
+- `NavigationHeader` exposes `[toggle]` and `class`.
+- `NavigationFooter` exposes `class`.
+- `NavigationContent` exposes `class` and renders the active type menu; declare it explicitly to control slot order, or omit it for the automatic default.
+- `[NavigationCollapseRoot]` adjusts layout for collapsible shell content when the sidebar rail is collapsed.
+- `[NavigationCollapseExpanded]` only renders its template while the vertical shell is not in collapsed display mode.
+
+```html
+<div NavigationCollapseRoot class="flex items-center gap-3 px-3">
+  <Icon name="work" />
+
+  <span *NavigationCollapseExpanded>Workspace</span>
+</div>
+```
+
+## Nav Service
+
+`@ojiepermana/angular-navigation/service` exposes `NavigationService` as a singleton registry for navigation type and overlay state.
+
+```ts
+import { NavigationService } from '@ojiepermana/angular-navigation/service';
+
+const nav = inject(NavigationService);
+
+nav.setType('erp-sidebar', 'dockbar');
+nav.setCollapsed('erp-sidebar', true);
+nav.toggleCollapsed('erp-sidebar');
+nav.setPosition('erp-sidebar', 'right');
+nav.setDockbarMode('erp-sidebar', 'drawer');
+nav.openDrawer('erp-sidebar');
+nav.closeDrawer('erp-sidebar');
+```
+
+Available service helpers include:
+
+- `register`, `unregister`, `state`, `currentState`, and `update` for instance lifecycle and state access.
+- `setType`, `setPosition`, `setCollapsed`, `toggleCollapsed`, and `setDockbarMode` for instance configuration.
+- `currentPanelKey`, `isPanelOpen`, `openPanel`, `togglePanel`, and `closePanel` for flyout or mega-panel state.
+- `isDrawerOpen`, `openDrawer`, `toggleDrawer`, and `closeDrawer` for drawer dockbar mode.
+- `exactMatchOptions` and `subsetMatchOptions` for router matching defaults.
+
+Only the primary sidebar navigation (`id="main"`) persists preferences in `localStorage` under:
+
+- `nav-orientation`
+- `nav-type`
+- `nav-position`
+- `nav-type-mode`
+
+`nav-type-mode` depends on the active vertical type:
+
+- sidebar: `default` or `collapsed`
+- dockbar: `sticky` or `drawer`
+
+Any other navigation id, such as `erp-navbar`, only keeps its state in memory for the active instance. Consumers should provide those values explicitly at usage time or rely on the built-in defaults.
+
+## Icons
+
+Saat `item.icon` tersedia, `nav` akan merender Material Symbols secara default melalui `@ojiepermana/angular-component/icon`. Jalankan `provideUiTheme()` untuk preload global, atau biarkan `IconComponent` melakukan lazy-load saat icon pertama dipakai.
+
+```html
+<Navigation [items]="items">
+  <NavigationSidebar />
+</Navigation>
+```
+
+Gunakan template `NavigationIcon` hanya bila consumer ingin override renderer bawaan.
+
+```html
+<Navigation [items]="items">
+  <NavigationSidebar />
+
+  <ng-template NavigationIcon let-icon let-item="item" let-active="active" let-level="level">
+    <Icon [name]="icon" class="text-primary" />
+  </ng-template>
+</Navigation>
+```
+
+`NavigationIcon` template context exposes:
+
+- `$implicit` and `icon`: resolved icon name.
+- `item`: source `NavigationItem`.
+- `active`: current active state.
+- `orientation`: current nav orientation.
+- `level`: current nesting depth.
+
+## Boundaries
+
+Entry point ini tetap extensible di layer consumer. Type defaults, instance registration, overlay state, dan affordance icon bawaan dikelola di library, sementara consumer masih bisa mengganti renderer icon dan komposisi layout sesuai kebutuhan.