@dloizides/ui-nav 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0
+
+Initial release. `Sidebar` (leaf + expandable items, active-route highlight, header/footer
+slots), `Topbar` (logo/language/notification/user/account/logout slots), and the
+`accessibleNavItems` / `roleRoutesToNavItems` role-gating helpers (reusing
+`resolveAccessibleRoutes` from `@dloizides/auth-web`). Chrome + metrics ported verbatim from
+the byte-identical erevna-web / katalogos-web nav twins; every colour reads from the
+`@dloizides/ui-feedback` UiProvider theme.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dloizides
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @dloizides/ui-nav
+
+Config-driven, brand-agnostic React Native (RN-web) **navigation shell** for the
+dloizides.com portfolio: `Sidebar` + `Topbar`, promoted from the byte-identical
+erevna-web / katalogos-web nav twins. The *chrome* is shared; the *item data* stays with
+your app — the components render a caller-supplied `NavItem[]` (labels already localized,
+icons as render slots) and route every colour through the shared `@dloizides/ui-feedback`
+UiProvider theme.
+
+## Install
+
+```bash
+npm install @dloizides/ui-nav @dloizides/ui-feedback @dloizides/auth-web
+```
+
+Peer deps: `@dloizides/ui-feedback >= 1.2.0`, `@dloizides/auth-web >= 1.5.0`, `react >= 18`,
+`react-native >= 0.74` (use `react-native-web` on web).
+
+## Usage
+
+```tsx
+import { Sidebar, Topbar, accessibleNavItems, type NavItem } from '@dloizides/ui-nav';
+
+const items: NavItem[] = buildItems(); // your role-filtered / grouped items
+
+<Sidebar
+  items={items}
+  pathname={usePathname()}
+  onNavigate={(route) => router.push(route)}
+  title={FM('menu.title')}
+  regionLabel={FM('accessibility.navigationRegion')}
+  navigateHint={(label) => FM('menu.navigateToHint', label)}
+  expandHint={FM('menu.expandSection')}
+  collapseHint={FM('menu.collapseSection')}
+  renderChevron={(open, color, size) => <SvgIcon name={open ? 'chevronUp' : 'chevronDown'} color={color} size={size} />}
+  header={<HomeShortcut />}
+  footer={<><DarkModeToggle /><LogoutButton /></>}
+/>
+
+<Topbar
+  left={<TenantLogo />}
+  language={{ label: FM(`topbar.lang.${locale}`), hint: FM('topbar.langHint'), onPress: toggleLocale }}
+  notificationSlot={<NotificationBell />}
+  user={{ name: displayName, email }}
+  logout={{ label: FM('topbar.logout'), hint: FM('topbar.logoutHint'), onPress: logout, testID: 'logout-button' }}
+/>
+```
+
+### Role gating
+
+`accessibleNavItems(user, roleRouteTable, translate)` builds the `NavItem[]` a user's roles
+unlock, reusing `resolveAccessibleRoutes` from `@dloizides/auth-web` (most privileged first,
+empty when none) — no duplicated role logic.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,271 @@
+import React from 'react';
+import { ViewStyle } from 'react-native';
+import { resolveAccessibleRoutes, RoleRouteTable, RoleRoute } from '@dloizides/auth-web';
+
+/**
+ * Active-route matcher shared by the sidebar entries. Ported verbatim from the
+ * twin app sidebars: an item is active when the current pathname equals its
+ * route or is nested under it (`/foo` matches `/foo` and `/foo/bar`, but `/`
+ * only matches `/`).
+ */
+declare function isRouteActive(pathname: string, route: string): boolean;
+
+/**
+ * Public prop types for the `@dloizides/ui-nav` config-driven navigation shell.
+ *
+ * The rendering chrome (sidebar + topbar) was byte-identical across erevna-web
+ * and katalogos-web; only the *item data* (which routes, how they group) differs
+ * per app. So this package renders a caller-supplied `NavItem[]` — labels are
+ * pre-localized strings and icons are render slots, keeping the package free of
+ * any app's i18n helper, icon set, router, or store.
+ */
+
+/** One navigation entry. Labels are already localized by the caller. */
+interface NavItem {
+    /** Stable key + default testID. */
+    key: string;
+    /** Localized display label. */
+    label: string;
+    /** Route/path this item navigates to (passed back to `onNavigate`). */
+    route: string;
+    /** Optional testID override (defaults to `key`). */
+    testID?: string;
+    /**
+     * Optional leading icon. Receives the resolved foreground colour and a size,
+     * so the app supplies its own icon component without this package importing
+     * an icon set.
+     */
+    renderIcon?: (color: string, size: number) => React.ReactNode;
+    /** Optional nested items — rendered as an expandable section. */
+    children?: NavItem[];
+}
+
+/**
+ * Sidebar — the config-driven left navigation shell promoted from the
+ * byte-identical erevna-web / katalogos-web `Sidebar`. It renders a caller
+ * supplied `NavItem[]` (leaf + expandable), highlights the active route, and
+ * exposes header/footer slots for app-specific chrome (title, dark-mode toggle,
+ * logout, notification bell). Every colour is read from the UiProvider theme.
+ */
+
+interface SidebarProps {
+    /** Nav entries — already role-filtered / grouped by the app. */
+    items: NavItem[];
+    /** Current active route/path. */
+    pathname: string;
+    /** Navigation callback — receives a `NavItem.route`. */
+    onNavigate: (route: string) => void;
+    /** Localized menu title (heading). */
+    title: string;
+    /** Localized accessibility label for the navigation landmark. */
+    regionLabel: string;
+    /** a11y hint for a leaf item, given its label. Defaults to the label. */
+    navigateHint?: (label: string) => string;
+    /** a11y hint shown when an expandable section is collapsed. */
+    expandHint?: string;
+    /** a11y hint shown when an expandable section is expanded. */
+    collapseHint?: string;
+    /** Optional chevron renderer for expandable sections. */
+    renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
+    /** Optional header slot rendered above the items (e.g. a Home shortcut). */
+    header?: React.ReactNode;
+    /** Optional footer slot rendered after a flex spacer (dark-mode toggle, logout). */
+    footer?: React.ReactNode;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+}
+declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
+
+/**
+ * Topbar — the config-driven top navigation bar promoted from the byte-identical
+ * erevna-web / katalogos-web `Topbar`. Structured slots replace the app-specific
+ * wiring: a `left` logo slot, an optional language toggle, a notification slot,
+ * an optional user block, an optional account button, and a required logout
+ * action. Every colour comes from the UiProvider theme.
+ */
+
+interface TopbarAction {
+    label: string;
+    hint: string;
+    onPress: () => void;
+    testID?: string;
+}
+interface TopbarUser {
+    name: string;
+    email: string;
+}
+interface TopbarProps {
+    /** Left slot — typically the tenant logo. */
+    left?: React.ReactNode;
+    /** Optional language toggle. */
+    language?: {
+        label: string;
+        hint: string;
+        onPress: () => void;
+    };
+    /** Optional notification slot (e.g. a notification bell). */
+    notificationSlot?: React.ReactNode;
+    /** Optional user identity block. */
+    user?: TopbarUser;
+    /** Optional account button. */
+    account?: TopbarAction;
+    /** Required logout action. */
+    logout: TopbarAction;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+}
+declare const Topbar: ({ left, language, notificationSlot, user, account, logout, containerStyle, }: TopbarProps) => React.ReactElement;
+
+/**
+ * NavExpandableItem — a single sidebar entry that is either a leaf (navigates)
+ * or an expandable section (toggles nested children). Ported from the twin
+ * erevna/katalogos `Sidebar/NavExpandableItem`, made config-driven: labels are
+ * pre-localized strings, icons are render slots, colours come from `useUi`.
+ */
+
+interface NavExpandableItemProps {
+    item: NavItem;
+    pathname: string;
+    onNavigate: (route: string) => void;
+    /** a11y hint for a leaf item, given its label. */
+    navigateHint: (label: string) => string;
+    /** a11y hint shown when the section is collapsed (press expands). */
+    expandHint: string;
+    /** a11y hint shown when the section is expanded (press collapses). */
+    collapseHint: string;
+    /** Optional chevron icon renderer for expandable sections. */
+    renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
+    depth?: number;
+}
+declare const NavExpandableItem: ({ item, pathname, onNavigate, navigateHint, expandHint, collapseHint, renderChevron, depth, }: NavExpandableItemProps) => React.ReactElement;
+
+/**
+ * Role-gated nav helpers — build a `NavItem[]` from a user's roles, reusing the
+ * existing `resolveAccessibleRoutes` from `@dloizides/auth-web` (the same helper
+ * the multi-role dashboard nav uses) rather than reimplementing role filtering.
+ *
+ * The app supplies its ordered `RoleRouteTable` (role → route + optional
+ * `labelKey`) and a `translate` fn (its `FM`); this returns the ordered set of
+ * `NavItem`s the user's roles unlock — most privileged first, empty when none.
+ */
+
+/** The user shape `resolveAccessibleRoutes` accepts (derived — no extra dep). */
+type NavUser = Parameters<typeof resolveAccessibleRoutes>[0];
+/** Map already-resolved role routes to nav items, localizing each `labelKey`. */
+declare function roleRoutesToNavItems(routes: RoleRoute[], translate: (key: string) => string): NavItem[];
+/**
+ * Resolve the nav items a user can reach, in table (priority) order. Wraps
+ * `resolveAccessibleRoutes` so role gating lives in one place.
+ */
+declare function accessibleNavItems(user: NavUser, table: RoleRouteTable, translate: (key: string) => string): NavItem[];
+
+declare const ACTIVE_BORDER_RADIUS = 4;
+declare const navStyles: {
+    sidebarContainer: {
+        width: number;
+        paddingTop: number;
+        paddingHorizontal: number;
+        borderRightWidth: number;
+        height: "100%";
+    };
+    sidebarTitle: {
+        fontWeight: "700";
+        marginBottom: number;
+    };
+    sidebarItem: {
+        paddingVertical: number;
+        paddingHorizontal: number;
+        borderRadius: number;
+    };
+    sidebarItemText: {
+        fontSize: number;
+    };
+    sidebarSpacer: {
+        flex: number;
+    };
+    topbarContainer: {
+        height: number;
+        paddingHorizontal: number;
+        borderBottomWidth: number;
+        flexDirection: "row";
+        alignItems: "center";
+        justifyContent: "space-between";
+    };
+    topbarLeft: {
+        flex: number;
+    };
+    topbarRight: {
+        flexDirection: "row";
+        alignItems: "center";
+    };
+    topbarRowItem: {
+        marginHorizontal: number;
+        alignItems: "center";
+    };
+    topbarLabel: {
+        fontSize: number;
+    };
+    userBlock: {
+        marginHorizontal: number;
+        alignItems: "flex-end";
+    };
+    userName: {
+        fontWeight: "600";
+    };
+    userEmail: {
+        fontSize: number;
+    };
+    accountBtn: {
+        marginLeft: number;
+        paddingHorizontal: number;
+        paddingVertical: number;
+        borderRadius: number;
+    };
+    accountText: {
+        fontWeight: "600";
+    };
+};
+declare const expandableStyles: {
+    childItem: {
+        borderRadius: number;
+        flexDirection: "row";
+        alignItems: "center";
+        paddingVertical: number;
+    };
+    childItemText: {
+        fontSize: number;
+    };
+    childItemTextWithIcon: {
+        fontSize: number;
+        marginLeft: number;
+    };
+    chevron: {
+        marginLeft: "auto";
+    };
+    childrenContainer: {
+        overflow: "hidden";
+    };
+    header: {
+        borderRadius: number;
+        flexDirection: "row";
+        alignItems: "center";
+        paddingVertical: number;
+    };
+    headerText: {
+        fontSize: number;
+        fontWeight: "600";
+        marginLeft: number;
+    };
+    iconWrapper: {
+        width: number;
+        alignItems: "center";
+    };
+};
+/** Base indent applied per nesting depth in the expandable item. */
+declare const BASE_INDENT = 12;
+/** Default icon size for nav item icons. */
+declare const NAV_ICON_SIZE = 14;
+/** Chevron icon size for expandable sections. */
+declare const CHEVRON_ICON_SIZE = 12;
+
+export { ACTIVE_BORDER_RADIUS, BASE_INDENT, CHEVRON_ICON_SIZE, NAV_ICON_SIZE, NavExpandableItem, type NavExpandableItemProps, type NavItem, type NavUser, Sidebar, type SidebarProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, expandableStyles, isRouteActive, navStyles, roleRoutesToNavItems };

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+import React from 'react';
+import { ViewStyle } from 'react-native';
+import { resolveAccessibleRoutes, RoleRouteTable, RoleRoute } from '@dloizides/auth-web';
+
+/**
+ * Active-route matcher shared by the sidebar entries. Ported verbatim from the
+ * twin app sidebars: an item is active when the current pathname equals its
+ * route or is nested under it (`/foo` matches `/foo` and `/foo/bar`, but `/`
+ * only matches `/`).
+ */
+declare function isRouteActive(pathname: string, route: string): boolean;
+
+/**
+ * Public prop types for the `@dloizides/ui-nav` config-driven navigation shell.
+ *
+ * The rendering chrome (sidebar + topbar) was byte-identical across erevna-web
+ * and katalogos-web; only the *item data* (which routes, how they group) differs
+ * per app. So this package renders a caller-supplied `NavItem[]` — labels are
+ * pre-localized strings and icons are render slots, keeping the package free of
+ * any app's i18n helper, icon set, router, or store.
+ */
+
+/** One navigation entry. Labels are already localized by the caller. */
+interface NavItem {
+    /** Stable key + default testID. */
+    key: string;
+    /** Localized display label. */
+    label: string;
+    /** Route/path this item navigates to (passed back to `onNavigate`). */
+    route: string;
+    /** Optional testID override (defaults to `key`). */
+    testID?: string;
+    /**
+     * Optional leading icon. Receives the resolved foreground colour and a size,
+     * so the app supplies its own icon component without this package importing
+     * an icon set.
+     */
+    renderIcon?: (color: string, size: number) => React.ReactNode;
+    /** Optional nested items — rendered as an expandable section. */
+    children?: NavItem[];
+}
+
+/**
+ * Sidebar — the config-driven left navigation shell promoted from the
+ * byte-identical erevna-web / katalogos-web `Sidebar`. It renders a caller
+ * supplied `NavItem[]` (leaf + expandable), highlights the active route, and
+ * exposes header/footer slots for app-specific chrome (title, dark-mode toggle,
+ * logout, notification bell). Every colour is read from the UiProvider theme.
+ */
+
+interface SidebarProps {
+    /** Nav entries — already role-filtered / grouped by the app. */
+    items: NavItem[];
+    /** Current active route/path. */
+    pathname: string;
+    /** Navigation callback — receives a `NavItem.route`. */
+    onNavigate: (route: string) => void;
+    /** Localized menu title (heading). */
+    title: string;
+    /** Localized accessibility label for the navigation landmark. */
+    regionLabel: string;
+    /** a11y hint for a leaf item, given its label. Defaults to the label. */
+    navigateHint?: (label: string) => string;
+    /** a11y hint shown when an expandable section is collapsed. */
+    expandHint?: string;
+    /** a11y hint shown when an expandable section is expanded. */
+    collapseHint?: string;
+    /** Optional chevron renderer for expandable sections. */
+    renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
+    /** Optional header slot rendered above the items (e.g. a Home shortcut). */
+    header?: React.ReactNode;
+    /** Optional footer slot rendered after a flex spacer (dark-mode toggle, logout). */
+    footer?: React.ReactNode;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+}
+declare const Sidebar: ({ items, pathname, onNavigate, title, regionLabel, navigateHint, expandHint, collapseHint, renderChevron, header, footer, containerStyle, }: SidebarProps) => React.ReactElement;
+
+/**
+ * Topbar — the config-driven top navigation bar promoted from the byte-identical
+ * erevna-web / katalogos-web `Topbar`. Structured slots replace the app-specific
+ * wiring: a `left` logo slot, an optional language toggle, a notification slot,
+ * an optional user block, an optional account button, and a required logout
+ * action. Every colour comes from the UiProvider theme.
+ */
+
+interface TopbarAction {
+    label: string;
+    hint: string;
+    onPress: () => void;
+    testID?: string;
+}
+interface TopbarUser {
+    name: string;
+    email: string;
+}
+interface TopbarProps {
+    /** Left slot — typically the tenant logo. */
+    left?: React.ReactNode;
+    /** Optional language toggle. */
+    language?: {
+        label: string;
+        hint: string;
+        onPress: () => void;
+    };
+    /** Optional notification slot (e.g. a notification bell). */
+    notificationSlot?: React.ReactNode;
+    /** Optional user identity block. */
+    user?: TopbarUser;
+    /** Optional account button. */
+    account?: TopbarAction;
+    /** Required logout action. */
+    logout: TopbarAction;
+    /** Extra container style overrides. */
+    containerStyle?: ViewStyle | ViewStyle[];
+}
+declare const Topbar: ({ left, language, notificationSlot, user, account, logout, containerStyle, }: TopbarProps) => React.ReactElement;
+
+/**
+ * NavExpandableItem — a single sidebar entry that is either a leaf (navigates)
+ * or an expandable section (toggles nested children). Ported from the twin
+ * erevna/katalogos `Sidebar/NavExpandableItem`, made config-driven: labels are
+ * pre-localized strings, icons are render slots, colours come from `useUi`.
+ */
+
+interface NavExpandableItemProps {
+    item: NavItem;
+    pathname: string;
+    onNavigate: (route: string) => void;
+    /** a11y hint for a leaf item, given its label. */
+    navigateHint: (label: string) => string;
+    /** a11y hint shown when the section is collapsed (press expands). */
+    expandHint: string;
+    /** a11y hint shown when the section is expanded (press collapses). */
+    collapseHint: string;
+    /** Optional chevron icon renderer for expandable sections. */
+    renderChevron?: (expanded: boolean, color: string, size: number) => React.ReactNode;
+    depth?: number;
+}
+declare const NavExpandableItem: ({ item, pathname, onNavigate, navigateHint, expandHint, collapseHint, renderChevron, depth, }: NavExpandableItemProps) => React.ReactElement;
+
+/**
+ * Role-gated nav helpers — build a `NavItem[]` from a user's roles, reusing the
+ * existing `resolveAccessibleRoutes` from `@dloizides/auth-web` (the same helper
+ * the multi-role dashboard nav uses) rather than reimplementing role filtering.
+ *
+ * The app supplies its ordered `RoleRouteTable` (role → route + optional
+ * `labelKey`) and a `translate` fn (its `FM`); this returns the ordered set of
+ * `NavItem`s the user's roles unlock — most privileged first, empty when none.
+ */
+
+/** The user shape `resolveAccessibleRoutes` accepts (derived — no extra dep). */
+type NavUser = Parameters<typeof resolveAccessibleRoutes>[0];
+/** Map already-resolved role routes to nav items, localizing each `labelKey`. */
+declare function roleRoutesToNavItems(routes: RoleRoute[], translate: (key: string) => string): NavItem[];
+/**
+ * Resolve the nav items a user can reach, in table (priority) order. Wraps
+ * `resolveAccessibleRoutes` so role gating lives in one place.
+ */
+declare function accessibleNavItems(user: NavUser, table: RoleRouteTable, translate: (key: string) => string): NavItem[];
+
+declare const ACTIVE_BORDER_RADIUS = 4;
+declare const navStyles: {
+    sidebarContainer: {
+        width: number;
+        paddingTop: number;
+        paddingHorizontal: number;
+        borderRightWidth: number;
+        height: "100%";
+    };
+    sidebarTitle: {
+        fontWeight: "700";
+        marginBottom: number;
+    };
+    sidebarItem: {
+        paddingVertical: number;
+        paddingHorizontal: number;
+        borderRadius: number;
+    };
+    sidebarItemText: {
+        fontSize: number;
+    };
+    sidebarSpacer: {
+        flex: number;
+    };
+    topbarContainer: {
+        height: number;
+        paddingHorizontal: number;
+        borderBottomWidth: number;
+        flexDirection: "row";
+        alignItems: "center";
+        justifyContent: "space-between";
+    };
+    topbarLeft: {
+        flex: number;
+    };
+    topbarRight: {
+        flexDirection: "row";
+        alignItems: "center";
+    };
+    topbarRowItem: {
+        marginHorizontal: number;
+        alignItems: "center";
+    };
+    topbarLabel: {
+        fontSize: number;
+    };
+    userBlock: {
+        marginHorizontal: number;
+        alignItems: "flex-end";
+    };
+    userName: {
+        fontWeight: "600";
+    };
+    userEmail: {
+        fontSize: number;
+    };
+    accountBtn: {
+        marginLeft: number;
+        paddingHorizontal: number;
+        paddingVertical: number;
+        borderRadius: number;
+    };
+    accountText: {
+        fontWeight: "600";
+    };
+};
+declare const expandableStyles: {
+    childItem: {
+        borderRadius: number;
+        flexDirection: "row";
+        alignItems: "center";
+        paddingVertical: number;
+    };
+    childItemText: {
+        fontSize: number;
+    };
+    childItemTextWithIcon: {
+        fontSize: number;
+        marginLeft: number;
+    };
+    chevron: {
+        marginLeft: "auto";
+    };
+    childrenContainer: {
+        overflow: "hidden";
+    };
+    header: {
+        borderRadius: number;
+        flexDirection: "row";
+        alignItems: "center";
+        paddingVertical: number;
+    };
+    headerText: {
+        fontSize: number;
+        fontWeight: "600";
+        marginLeft: number;
+    };
+    iconWrapper: {
+        width: number;
+        alignItems: "center";
+    };
+};
+/** Base indent applied per nesting depth in the expandable item. */
+declare const BASE_INDENT = 12;
+/** Default icon size for nav item icons. */
+declare const NAV_ICON_SIZE = 14;
+/** Chevron icon size for expandable sections. */
+declare const CHEVRON_ICON_SIZE = 12;
+
+export { ACTIVE_BORDER_RADIUS, BASE_INDENT, CHEVRON_ICON_SIZE, NAV_ICON_SIZE, NavExpandableItem, type NavExpandableItemProps, type NavItem, type NavUser, Sidebar, type SidebarProps, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, expandableStyles, isRouteActive, navStyles, roleRoutesToNavItems };