@dloizides/ui-nav 1.36.0 → 1.38.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.38.0
+
+- NAV-BRAND-1 D-NAVB-3 "One brand options prop": `NavShell` takes one `brand={{ placement, railWidth, drawerHeader, drawerWidth }}` prop instead of the four 1.37.0 props; `Sidebar.width` removed (the shell sets the rail width through `containerStyle`). The top-bar brand cell carries the top bar background and bottom border, so the header line runs over the rail.
+
+## 1.37.0
+
+- NAV-BRAND-1 "Wider sidebar, logo and name in the top bar": `NavShell` gains `brandPlacement`, `sidebarWidth`, `drawerHeader`, `drawerWidth` (defaults = today); `Sidebar.width`; `AppShell.mobileMenu` takes `header` / `width` / `sidebar`. Exports `SIDEBAR_WIDTH_PX`, `NAV_BRAND_DEFAULTS`.
+
 ## 1.35.0
 
 - NAV-SCROLL-1 "Opening sidebar groups never hides the items below" (AC-UI-1, AC-UI-2): `Sidebar` items (header slot + list) scroll in a `ScrollView` between the pinned title/search and the pinned footer, with a `theme.colors.surface` fade on each edge that hides items. Inside `MobileDrawer` opening a top-level group closes the other (through `NavAccordionContext`, which `MobileDrawer` provides; no new `Sidebar` prop). `NavExpandableItem` takes optional controlled `expanded` + `onToggle`. No prop changes for existing consumers.

package/README.md

@@ -151,6 +151,24 @@ import { NavShell, type NavItem } from '@dloizides/ui-nav';
 `NavShell` composes existing components, so it stays purely additive — `AppShell`,
 `NavBar`, and `Sidebar` are unchanged.
 
+### Brand position, rail width and phone drawer (`NavShell`, NAV-BRAND-1)
+
+One `brand` prop holds every choice; every default (`NAV_BRAND_DEFAULTS`) keeps today's layout.
+
+| `brand` field | Values | Default |
+|---|---|---|
+| `placement` | `'sidebar'` (rail top) · `'topbar'` (top-left of the header, >= 768 px, same background and bottom border as the top bar) | `'sidebar'` |
+| `railWidth` | `'default'` 220 · `'sm'` 240 · `'md'` 264 · `'lg'` 288 px (`SIDEBAR_WIDTH_PX`) | `'default'` |
+| `drawerHeader` | `'none'` · `'brand'` (brand once in the open drawer's header, with a close button) | `'none'` |
+| `drawerWidth` | `'default'` (280 px panel + scrim) · `'full'` (whole screen, close button) | `'default'` |
+
+```tsx
+<NavShell layout="side" brand={{ placement: 'topbar', railWidth: 'sm', drawerHeader: 'brand', drawerWidth: 'full' }}
+  sideRail={{ items, title, brand: <AppBrand /> }} header={<Topbar ... />} {...rest} />
+```
+
+The brand node is the same `sideRail.brand` in every position; only where it renders changes.
+
 ### Three-tier responsive rail (`AppShell.collapsedSidebar` / `CollapsedRail`)
 
 Supply a `collapsedSidebar` (or `NavShell`'s `sideRail.collapsed`) to opt the rail

package/dist/index.d.mts

@@ -43,6 +43,25 @@ interface NavItem {
      */
     exact?: boolean;
 }
+/** Where the shell's brand sits on desktop: the rail top (today) or the top-left of the top bar. */
+type BrandPlacement = 'sidebar' | 'topbar';
+/** Named side-rail widths; `default` is today's 220 px. */
+type SidebarWidth = 'default' | 'sm' | 'md' | 'lg';
+/** What the open phone drawer shows in its header: nothing (today) or the brand. */
+type DrawerHeader = 'none' | 'brand';
+/** Phone drawer width: today's fixed panel or the full screen. */
+type DrawerWidth = 'default' | 'full';
+/** Pixel width of each named side-rail width token. */
+declare const SIDEBAR_WIDTH_PX: Readonly<Record<SidebarWidth, number>>;
+/** Fields of NavShell's one `brand` prop; each has a default that keeps today's layout. */
+interface NavBrandOptions {
+    placement?: BrandPlacement;
+    railWidth?: SidebarWidth;
+    drawerHeader?: DrawerHeader;
+    drawerWidth?: DrawerWidth;
+}
+/** Defaults of {@link NavBrandOptions}: today's layout. */
+declare const NAV_BRAND_DEFAULTS: Readonly<Required<NavBrandOptions>>;
 
 /**
  * Active-route matching for the nav shells.
@@ -154,7 +173,7 @@ interface SidebarProps {
     pathname: string;
     /** Navigation callback — receives a `NavItem.route`. */
     onNavigate: (route: string) => void;
-    /** Localized menu title (heading). */
+    /** Localized menu title (heading); `null` leaves the slot empty. */
     title: React.ReactNode;
     /** Localized accessibility label for the navigation landmark. */
     regionLabel: string;
@@ -558,6 +577,15 @@ interface DrawerLabels {
     /** Accessible hint of the scrim (tap to close). */
     closeHint: string;
 }
+/** Optional drawer options, passed with the labels through `AppShell.mobileMenu`. */
+interface DrawerOptions {
+    /** Shown once in the drawer's header row (with a close button). */
+    header?: React.ReactNode;
+    /** `full` = the whole screen; default = today's 280 px panel. */
+    width?: DrawerWidth;
+    /** Drawer content in place of the rail's `sidebar` node. */
+    sidebar?: React.ReactNode;
+}
 
 /**
  * Rail responsive mode — the pure (viewport → which rail face) rule behind
@@ -679,12 +707,8 @@ interface AppShellProps {
      * `{ min: 768, max: 1024 }`. Only consulted when `collapsedSidebar` is supplied.
      */
     collapsedRailRange?: CollapsedRailRange;
-    /**
-     * Pre-localized labels for the mobile nav drawer (only used in the `sidebar`
-     * layout, below the breakpoint): the hamburger's open label/hint and the scrim's
-     * close label/hint. Optional — English defaults apply. NO i18n in this package.
-     */
-    mobileMenu?: Partial<DrawerLabels>;
+    /** Mobile drawer labels (English defaults) plus optional header brand, width and content. */
+    mobileMenu?: Partial<DrawerLabels> & DrawerOptions;
     /** Banner slot (e.g. verification-pending). */
     banner?: React.ReactNode;
     /** Content-width policy. Defaults to full-bleed. */
@@ -846,6 +870,8 @@ interface NavShellSideRail {
  */
 type ForwardedShellProps = Omit<AppShellProps, 'header' | 'sidebar' | 'children'>;
 interface NavShellProps extends ForwardedShellProps {
+    /** Brand placement, rail width and phone drawer options; defaults keep today's layout. */
+    brand?: NavBrandOptions;
     /** Which regions to render: a top bar, a side rail, or both. */
     layout: NavShellLayout;
     /** Current active route/path — drives active highlighting on both regions. */
@@ -877,7 +903,7 @@ interface NavShellProps extends ForwardedShellProps {
     sideRail?: NavShellSideRail;
     children: React.ReactNode;
 }
-declare const NavShell: ({ layout, pathname, onNavigate, regionLabel, navigateHint, topBar, header, sideRail, children, collapsedSidebar: collapsedSidebarProp, collapsedRailRange: collapsedRailRangeProp, ...shellProps }: NavShellProps) => React.ReactElement | null;
+declare const NavShell: ({ layout, pathname, onNavigate, regionLabel, navigateHint, topBar, header, sideRail, children, collapsedSidebar: collapsedSidebarProp, collapsedRailRange: collapsedRailRangeProp, brand, mobileMenu, ...shellProps }: NavShellProps) => React.ReactElement | null;
 
 /**
  * CollapsedRail — the icon-only vertical rail for the intermediate (tablet) tier
@@ -1363,7 +1389,6 @@ declare const HOVER_TINT_OPACITY = 0.06;
 declare const NAV_LINK_GAP = 4;
 declare const navStyles: {
     sidebarContainer: {
-        width: number;
         paddingTop: number;
         paddingHorizontal: number;
         borderRightWidth: number;
@@ -1668,4 +1693,4 @@ interface BottomTabBarProps {
 /** Phone tab bar; `tabFeedback` picks the press feedback, `Default` adds no motion. */
 declare const BottomTabBar: ({ items, pathname, onNavigate, tabFeedback, navigateHint, regionLabel, containerStyle, testID, }: BottomTabBarProps) => React.ReactElement;
 
-export { ACTIVE_BORDER_RADIUS, ACTIVE_TINT_OPACITY, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellBackdrop, type AppShellBackdropBand, type AppShellProps, type AppShellWidth, BASE_INDENT, BottomTabBar, type BottomTabBarProps, BrandHomeLink, type BrandHomeLinkProps, BrandMark, type BrandMarkProps, CHEVRON_ICON_SIZE, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, DEFAULT_COLLAPSED_RAIL_MAX, DEFAULT_SEARCH_BREAKPOINT, DarkModeControl, type DarkModeControlProps, type DarkModeOption, type DarkModeVariant, HOVER_TINT_OPACITY, NAV_ICON_SIZE, NAV_LINK_GAP, NAV_ROW_RADIUS, NAV_TEST_IDS, Nav, NavBar, type NavBarProps, NavExpandableItem, type NavExpandableItemProps, NavHoverFeedback, type NavItem, type NavOrientation, NavOverflowMenu, type NavOverflowMenuProps, type NavProps, NavShell, type NavShellCollapsedRail, type NavShellLayout, type NavShellProps, type NavShellSideRail, type NavShellTopBar, type NavUser, PillNav, type PillNavProps, PillNavVariant, RAIL_FULL_BREAKPOINT, type RailMode, type ResolveRailModeArgs, type SearchAffordance, type ShellMessage, Sidebar, SidebarChevron, type SidebarChevronProps, type SidebarPaletteTriggerConfig, type SidebarProps, SidebarSearch, type SidebarSearchConfig, type SidebarSearchLabels, type SidebarSearchProps, TabFeedback, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, collapsedRailStyles, darkModeStyles, expandableStyles, filterCommands, filterNavItems, isFilterActive, isRouteActive, navStyles, pillNavStyles, resolveActiveRoute, resolveContentMaxWidth, resolvePillMenuLabel, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };
+export { ACTIVE_BORDER_RADIUS, ACTIVE_TINT_OPACITY, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellBackdrop, type AppShellBackdropBand, type AppShellProps, type AppShellWidth, BASE_INDENT, BottomTabBar, type BottomTabBarProps, BrandHomeLink, type BrandHomeLinkProps, BrandMark, type BrandMarkProps, type BrandPlacement, CHEVRON_ICON_SIZE, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, DEFAULT_COLLAPSED_RAIL_MAX, DEFAULT_SEARCH_BREAKPOINT, DarkModeControl, type DarkModeControlProps, type DarkModeOption, type DarkModeVariant, type DrawerHeader, type DrawerOptions, type DrawerWidth, HOVER_TINT_OPACITY, NAV_BRAND_DEFAULTS, NAV_ICON_SIZE, NAV_LINK_GAP, NAV_ROW_RADIUS, NAV_TEST_IDS, Nav, NavBar, type NavBarProps, type NavBrandOptions, NavExpandableItem, type NavExpandableItemProps, NavHoverFeedback, type NavItem, type NavOrientation, NavOverflowMenu, type NavOverflowMenuProps, type NavProps, NavShell, type NavShellCollapsedRail, type NavShellLayout, type NavShellProps, type NavShellSideRail, type NavShellTopBar, type NavUser, PillNav, type PillNavProps, PillNavVariant, RAIL_FULL_BREAKPOINT, type RailMode, type ResolveRailModeArgs, SIDEBAR_WIDTH_PX, type SearchAffordance, type ShellMessage, Sidebar, SidebarChevron, type SidebarChevronProps, type SidebarPaletteTriggerConfig, type SidebarProps, SidebarSearch, type SidebarSearchConfig, type SidebarSearchLabels, type SidebarSearchProps, type SidebarWidth, TabFeedback, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, collapsedRailStyles, darkModeStyles, expandableStyles, filterCommands, filterNavItems, isFilterActive, isRouteActive, navStyles, pillNavStyles, resolveActiveRoute, resolveContentMaxWidth, resolvePillMenuLabel, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };

package/dist/index.d.ts

@@ -43,6 +43,25 @@ interface NavItem {
      */
     exact?: boolean;
 }
+/** Where the shell's brand sits on desktop: the rail top (today) or the top-left of the top bar. */
+type BrandPlacement = 'sidebar' | 'topbar';
+/** Named side-rail widths; `default` is today's 220 px. */
+type SidebarWidth = 'default' | 'sm' | 'md' | 'lg';
+/** What the open phone drawer shows in its header: nothing (today) or the brand. */
+type DrawerHeader = 'none' | 'brand';
+/** Phone drawer width: today's fixed panel or the full screen. */
+type DrawerWidth = 'default' | 'full';
+/** Pixel width of each named side-rail width token. */
+declare const SIDEBAR_WIDTH_PX: Readonly<Record<SidebarWidth, number>>;
+/** Fields of NavShell's one `brand` prop; each has a default that keeps today's layout. */
+interface NavBrandOptions {
+    placement?: BrandPlacement;
+    railWidth?: SidebarWidth;
+    drawerHeader?: DrawerHeader;
+    drawerWidth?: DrawerWidth;
+}
+/** Defaults of {@link NavBrandOptions}: today's layout. */
+declare const NAV_BRAND_DEFAULTS: Readonly<Required<NavBrandOptions>>;
 
 /**
  * Active-route matching for the nav shells.
@@ -154,7 +173,7 @@ interface SidebarProps {
     pathname: string;
     /** Navigation callback — receives a `NavItem.route`. */
     onNavigate: (route: string) => void;
-    /** Localized menu title (heading). */
+    /** Localized menu title (heading); `null` leaves the slot empty. */
     title: React.ReactNode;
     /** Localized accessibility label for the navigation landmark. */
     regionLabel: string;
@@ -558,6 +577,15 @@ interface DrawerLabels {
     /** Accessible hint of the scrim (tap to close). */
     closeHint: string;
 }
+/** Optional drawer options, passed with the labels through `AppShell.mobileMenu`. */
+interface DrawerOptions {
+    /** Shown once in the drawer's header row (with a close button). */
+    header?: React.ReactNode;
+    /** `full` = the whole screen; default = today's 280 px panel. */
+    width?: DrawerWidth;
+    /** Drawer content in place of the rail's `sidebar` node. */
+    sidebar?: React.ReactNode;
+}
 
 /**
  * Rail responsive mode — the pure (viewport → which rail face) rule behind
@@ -679,12 +707,8 @@ interface AppShellProps {
      * `{ min: 768, max: 1024 }`. Only consulted when `collapsedSidebar` is supplied.
      */
     collapsedRailRange?: CollapsedRailRange;
-    /**
-     * Pre-localized labels for the mobile nav drawer (only used in the `sidebar`
-     * layout, below the breakpoint): the hamburger's open label/hint and the scrim's
-     * close label/hint. Optional — English defaults apply. NO i18n in this package.
-     */
-    mobileMenu?: Partial<DrawerLabels>;
+    /** Mobile drawer labels (English defaults) plus optional header brand, width and content. */
+    mobileMenu?: Partial<DrawerLabels> & DrawerOptions;
     /** Banner slot (e.g. verification-pending). */
     banner?: React.ReactNode;
     /** Content-width policy. Defaults to full-bleed. */
@@ -846,6 +870,8 @@ interface NavShellSideRail {
  */
 type ForwardedShellProps = Omit<AppShellProps, 'header' | 'sidebar' | 'children'>;
 interface NavShellProps extends ForwardedShellProps {
+    /** Brand placement, rail width and phone drawer options; defaults keep today's layout. */
+    brand?: NavBrandOptions;
     /** Which regions to render: a top bar, a side rail, or both. */
     layout: NavShellLayout;
     /** Current active route/path — drives active highlighting on both regions. */
@@ -877,7 +903,7 @@ interface NavShellProps extends ForwardedShellProps {
     sideRail?: NavShellSideRail;
     children: React.ReactNode;
 }
-declare const NavShell: ({ layout, pathname, onNavigate, regionLabel, navigateHint, topBar, header, sideRail, children, collapsedSidebar: collapsedSidebarProp, collapsedRailRange: collapsedRailRangeProp, ...shellProps }: NavShellProps) => React.ReactElement | null;
+declare const NavShell: ({ layout, pathname, onNavigate, regionLabel, navigateHint, topBar, header, sideRail, children, collapsedSidebar: collapsedSidebarProp, collapsedRailRange: collapsedRailRangeProp, brand, mobileMenu, ...shellProps }: NavShellProps) => React.ReactElement | null;
 
 /**
  * CollapsedRail — the icon-only vertical rail for the intermediate (tablet) tier
@@ -1363,7 +1389,6 @@ declare const HOVER_TINT_OPACITY = 0.06;
 declare const NAV_LINK_GAP = 4;
 declare const navStyles: {
     sidebarContainer: {
-        width: number;
         paddingTop: number;
         paddingHorizontal: number;
         borderRightWidth: number;
@@ -1668,4 +1693,4 @@ interface BottomTabBarProps {
 /** Phone tab bar; `tabFeedback` picks the press feedback, `Default` adds no motion. */
 declare const BottomTabBar: ({ items, pathname, onNavigate, tabFeedback, navigateHint, regionLabel, containerStyle, testID, }: BottomTabBarProps) => React.ReactElement;
 
-export { ACTIVE_BORDER_RADIUS, ACTIVE_TINT_OPACITY, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellBackdrop, type AppShellBackdropBand, type AppShellProps, type AppShellWidth, BASE_INDENT, BottomTabBar, type BottomTabBarProps, BrandHomeLink, type BrandHomeLinkProps, BrandMark, type BrandMarkProps, CHEVRON_ICON_SIZE, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, DEFAULT_COLLAPSED_RAIL_MAX, DEFAULT_SEARCH_BREAKPOINT, DarkModeControl, type DarkModeControlProps, type DarkModeOption, type DarkModeVariant, HOVER_TINT_OPACITY, NAV_ICON_SIZE, NAV_LINK_GAP, NAV_ROW_RADIUS, NAV_TEST_IDS, Nav, NavBar, type NavBarProps, NavExpandableItem, type NavExpandableItemProps, NavHoverFeedback, type NavItem, type NavOrientation, NavOverflowMenu, type NavOverflowMenuProps, type NavProps, NavShell, type NavShellCollapsedRail, type NavShellLayout, type NavShellProps, type NavShellSideRail, type NavShellTopBar, type NavUser, PillNav, type PillNavProps, PillNavVariant, RAIL_FULL_BREAKPOINT, type RailMode, type ResolveRailModeArgs, type SearchAffordance, type ShellMessage, Sidebar, SidebarChevron, type SidebarChevronProps, type SidebarPaletteTriggerConfig, type SidebarProps, SidebarSearch, type SidebarSearchConfig, type SidebarSearchLabels, type SidebarSearchProps, TabFeedback, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, collapsedRailStyles, darkModeStyles, expandableStyles, filterCommands, filterNavItems, isFilterActive, isRouteActive, navStyles, pillNavStyles, resolveActiveRoute, resolveContentMaxWidth, resolvePillMenuLabel, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };
+export { ACTIVE_BORDER_RADIUS, ACTIVE_TINT_OPACITY, APP_SHELL_SUFFIX, type AccountPlan, type AccountState, AppShell, type AppShellBackdrop, type AppShellBackdropBand, type AppShellProps, type AppShellWidth, BASE_INDENT, BottomTabBar, type BottomTabBarProps, BrandHomeLink, type BrandHomeLinkProps, BrandMark, type BrandMarkProps, type BrandPlacement, CHEVRON_ICON_SIZE, CollapsedRail, type CollapsedRailProps, type CollapsedRailRange, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, DEFAULT_COLLAPSED_RAIL_MAX, DEFAULT_SEARCH_BREAKPOINT, DarkModeControl, type DarkModeControlProps, type DarkModeOption, type DarkModeVariant, type DrawerHeader, type DrawerOptions, type DrawerWidth, HOVER_TINT_OPACITY, NAV_BRAND_DEFAULTS, NAV_ICON_SIZE, NAV_LINK_GAP, NAV_ROW_RADIUS, NAV_TEST_IDS, Nav, NavBar, type NavBarProps, type NavBrandOptions, NavExpandableItem, type NavExpandableItemProps, NavHoverFeedback, type NavItem, type NavOrientation, NavOverflowMenu, type NavOverflowMenuProps, type NavProps, NavShell, type NavShellCollapsedRail, type NavShellLayout, type NavShellProps, type NavShellSideRail, type NavShellTopBar, type NavUser, PillNav, type PillNavProps, PillNavVariant, RAIL_FULL_BREAKPOINT, type RailMode, type ResolveRailModeArgs, SIDEBAR_WIDTH_PX, type SearchAffordance, type ShellMessage, Sidebar, SidebarChevron, type SidebarChevronProps, type SidebarPaletteTriggerConfig, type SidebarProps, SidebarSearch, type SidebarSearchConfig, type SidebarSearchLabels, type SidebarSearchProps, type SidebarWidth, TabFeedback, Topbar, type TopbarAction, type TopbarProps, type TopbarUser, accessibleNavItems, collapsedRailStyles, darkModeStyles, expandableStyles, filterCommands, filterNavItems, isFilterActive, isRouteActive, navStyles, pillNavStyles, resolveActiveRoute, resolveContentMaxWidth, resolvePillMenuLabel, resolveRailMode, resolveSearchAffordance, roleRoutesToNavItems, searchTokens, useCommandPaletteHotkey, useContentMaxWidth };