@riverbankcms/sdk 0.6.0 → 0.6.1

package/dist/server/navigation.d.mts

@@ -12,26 +12,28 @@ import '@riverbankcms/db';
  * Navigation helper utilities for SDK sites.
  *
  * Provides helpers to transform CMS navigation data into render-ready structures.
- * Supports both simple NavItem arrays and full MenuViewModels for block rendering.
+ * All navigation functions return nested structures supporting dropdowns.
  *
- * @example Simple usage
+ * @example Getting nav items
  * ```ts
- * import { getPrimaryNavItems } from '@riverbankcms/sdk/navigation';
+ * import { getPrimaryNavItems, isNavLink, isNavDropdown } from '@riverbankcms/sdk/navigation';
  *
  * const headerNav = getPrimaryNavItems(siteData.navigation);
- * // [{ href: '/', label: 'Home', isExternal: false }, ...]
+ * headerNav.forEach(item => {
+ *   if (isNavLink(item)) {
+ *     console.log(item.href);
+ *   } else {
+ *     console.log(`${item.label} has ${item.children.length} children`);
+ *   }
+ * });
  * ```
  *
- * @example Block rendering usage
+ * @example Building menu and logo
  * ```ts
- * import { buildMenuViewModel, buildLogoViewModel } from '@riverbankcms/sdk/navigation';
- *
- * const menu = buildMenuViewModel(siteData.navigation);
- * const logo = buildLogoViewModel(siteData.layout.logo, siteData.site.title);
+ * import { buildMenu, buildLogo } from '@riverbankcms/sdk/navigation';
  *
- * renderBlock(siteHeaderManifest, layout.header, {
- *   viewModelOverrides: { menu, content: { logo } },
- * });
+ * const menu = buildMenu(siteData.navigation, siteData.routes);
+ * const logo = buildLogo(siteData.layout.logo, siteData.site.title);
  * ```
  *
  * @packageDocumentation
@@ -110,17 +112,6 @@ type LogoViewModel = {
     storagePath?: string;
     storageBucket?: string;
 } | null;
-/**
- * A simplified navigation item structure for component rendering.
- */
-type NavItem = {
-    /** The URL to navigate to */
-    href: string;
-    /** Display text for the navigation link */
-    label: string;
-    /** Whether link should open in new tab (external links) */
-    isExternal: boolean;
-};
 /**
  * A navigation link item with a direct URL.
  * Use `kind` discriminator for type-safe narrowing.
@@ -160,12 +151,12 @@ type NavDropdown = {
     children: NavLink[];
 };
 /**
- * Unified navigation item supporting both links and dropdowns.
+ * Navigation item - either a link or a dropdown container.
  * Use `kind` property for type-safe discrimination.
  *
  * @example
  * ```ts
- * const items = getNestedPrimaryNavItems(navigation);
+ * const items = getPrimaryNavItems(navigation);
  * items.forEach(item => {
  *   if (item.kind === 'link') {
  *     console.log(item.href);
@@ -175,72 +166,63 @@ type NavDropdown = {
  * });
  * ```
  */
-type NestedNavItem = NavLink | NavDropdown;
+type NavItem = NavLink | NavDropdown;
 /**
  * Type guard to check if a navigation item is a link.
  */
-declare function isNavLink(item: NestedNavItem): item is NavLink;
+declare function isNavLink(item: NavItem): item is NavLink;
 /**
  * Type guard to check if a navigation item is a dropdown.
  */
-declare function isNavDropdown(item: NestedNavItem): item is NavDropdown;
-/**
- * Simple nav link with pre-resolved href for block rendering.
- */
-type SimpleNavLink = {
-    id: string;
-    label: string;
-    href: string;
-    isExternal: boolean;
-};
+declare function isNavDropdown(item: NavItem): item is NavDropdown;
 /**
- * Simple menu view model with pre-resolved hrefs.
- * Use this instead of MenuViewModel for cleaner data flow.
- */
-type SimpleMenuViewModel = {
-    items: SimpleNavLink[];
-    ctaItem: SimpleNavLink | null;
-};
-/**
- * Simple nested nav link with pre-resolved href.
- */
-type SimpleNestedNavLink = {
-    kind: 'link';
-    id: string;
-    label: string;
-    href: string;
-    isExternal: boolean;
-};
-/**
- * Simple nested dropdown with pre-resolved children.
- */
-type SimpleNestedNavDropdown = {
-    kind: 'dropdown';
-    id: string;
-    label: string;
-    children: SimpleNestedNavLink[];
-};
-/**
- * Unified simple nested navigation item.
- */
-type SimpleNestedNavItem = SimpleNestedNavLink | SimpleNestedNavDropdown;
-/**
- * Simple menu view model with nested navigation support.
+ * Navigation menu with items and optional CTA.
+ * Built from CMS navigation data with pre-resolved hrefs.
+ *
+ * @example
+ * ```ts
+ * const menu = buildMenu(siteData.navigation, siteData.routes);
+ * menu.items.forEach(item => {
+ *   if (item.kind === 'link') {
+ *     console.log(item.href);
+ *   } else {
+ *     console.log(item.children);
+ *   }
+ * });
+ * ```
  */
-type SimpleNestedMenuViewModel = {
-    items: SimpleNestedNavItem[];
-    ctaItem: SimpleNestedNavLink | null;
+type Menu = {
+    items: NavItem[];
+    ctaItem: NavLink | null;
 };
 /**
- * Simple logo data for block rendering.
+ * Logo data for site rendering.
+ *
+ * @example
+ * ```ts
+ * const logo = buildLogo(siteData.layout.logo, siteData.site.title);
+ * if (logo) {
+ *   <img src={logo.src} alt={logo.alt} />
+ * }
+ * ```
  */
-type SimpleLogo = {
+type Logo = {
     type: 'image';
     src: string;
     alt: string;
     width?: number;
     height?: number;
 } | null;
+/** @deprecated Use `NavLink` instead */
+type SimpleNavLink = NavLink;
+/** @deprecated Use `NavDropdown` instead */
+type SimpleNavDropdown = NavDropdown;
+/** @deprecated Use `NavItem` instead */
+type SimpleNavItem = NavItem;
+/** @deprecated Use `Menu` instead */
+type SimpleMenuViewModel = Menu;
+/** @deprecated Use `Logo` instead */
+type SimpleLogo = Logo;
 /**
  * Get the primary navigation menu object.
  * Returns menu marked as isPrimary, or first menu if none marked.
@@ -248,7 +230,7 @@ type SimpleLogo = {
  * @example
  * ```ts
  * const menu = getPrimaryNavigation(siteData.navigation);
- * console.log(menu?.title); // "Main Navigation"
+ * console.log(menu?.name); // "main"
  * ```
  */
 declare function getPrimaryNavigation(navigation: NavigationMenuWithItems[]): NavigationMenuWithItems | null;
@@ -263,19 +245,22 @@ declare function getPrimaryNavigation(navigation: NavigationMenuWithItems[]): Na
 declare function getNavigationBySlug(navigation: NavigationMenuWithItems[], slug: string): NavigationMenuWithItems | null;
 /**
  * Get nav items from the primary menu (marked isPrimary, or first menu).
- * Returns empty array if no navigation configured.
+ * Returns nested structure supporting both links and dropdowns.
  *
  * @example
  * ```ts
  * const headerNav = getPrimaryNavItems(siteData.navigation);
- * // [{ href: '/', label: 'Home', isExternal: false }, ...]
+ * headerNav.forEach(item => {
+ *   if (item.kind === 'dropdown') {
+ *     console.log(`${item.label} has ${item.children.length} children`);
+ *   }
+ * });
  * ```
  */
 declare function getPrimaryNavItems(navigation: NavigationMenuWithItems[]): NavItem[];
 /**
  * Get nav items from a specific menu by slug.
- * Useful for footer nav, secondary nav, etc.
- * Returns empty array if menu not found.
+ * Returns nested structure supporting both links and dropdowns.
  *
  * @example
  * ```ts
@@ -284,47 +269,19 @@ declare function getPrimaryNavItems(navigation: NavigationMenuWithItems[]): NavI
  */
 declare function getNavItemsBySlug(navigation: NavigationMenuWithItems[], slug: string): NavItem[];
 /**
- * Transform a menu into simple NavItem array.
- */
-declare function transformToNavItems(menu: NavigationMenuWithItems | null): NavItem[];
-/**
- * Transform a menu into nested NestedNavItem array.
- * Builds tree structure from flat items, supporting dropdowns with children.
+ * Transform a menu into NavItem array.
+ * Builds nested structure from flat items, supporting dropdowns with children.
  *
  * @example
  * ```ts
- * const nav = transformToNestedNavItems(menu);
+ * const nav = transformToNavItems(menu);
  * // [
  * //   { kind: 'link', href: '/', label: 'Home', ... },
  * //   { kind: 'dropdown', label: 'Services', children: [...] },
  * // ]
  * ```
  */
-declare function transformToNestedNavItems(menu: NavigationMenuWithItems | null): NestedNavItem[];
-/**
- * Get nested nav items from the primary menu.
- * Supports dropdowns with children for complex navigation structures.
- *
- * @example
- * ```ts
- * const nav = getNestedPrimaryNavItems(siteData.navigation);
- * nav.forEach(item => {
- *   if (item.kind === 'dropdown') {
- *     console.log(`${item.label} has ${item.children.length} children`);
- *   }
- * });
- * ```
- */
-declare function getNestedPrimaryNavItems(navigation: NavigationMenuWithItems[]): NestedNavItem[];
-/**
- * Get nested nav items from a specific menu by slug.
- *
- * @example
- * ```ts
- * const footerNav = getNestedNavItemsBySlug(siteData.navigation, 'footer');
- * ```
- */
-declare function getNestedNavItemsBySlug(navigation: NavigationMenuWithItems[], slug: string): NestedNavItem[];
+declare function transformToNavItems(menu: NavigationMenuWithItems | null): NavItem[];
 /**
  * Build a MenuViewModel from navigation data for block rendering.
  * Extracts CTA item separately and preserves full link data.
@@ -356,26 +313,15 @@ declare function buildMenuViewModel(navigation: NavigationMenuWithItems[]): Menu
  */
 declare function buildLogoViewModel(logo: LogoSource, fallbackTitle: string | null | undefined): LogoViewModel;
 /**
- * Build a SimpleMenuViewModel from navigation data with pre-resolved hrefs.
- * Use this instead of buildMenuViewModel for cleaner data flow.
+ * Build a Menu from navigation data with pre-resolved hrefs.
+ * Supports dropdown containers with nested children.
  *
  * @param navigation - Navigation menus from site data
  * @param routes - Route map for resolving internal links
  *
  * @example
  * ```ts
- * const menu = buildSimpleMenu(siteData.navigation, siteData.routes);
- * // { items: [{ id, label, href: '/', isExternal: false }], cta: null }
- * ```
- */
-declare function buildSimpleMenu(navigation: NavigationMenuWithItems[], routes: RouteMap): SimpleMenuViewModel;
-/**
- * Build a SimpleNestedMenuViewModel with pre-resolved hrefs.
- * Supports dropdown containers with nested children.
- *
- * @example
- * ```ts
- * const menu = buildSimpleNestedMenu(siteData.navigation, siteData.routes);
+ * const menu = buildMenu(siteData.navigation, siteData.routes);
  * menu.items.forEach(item => {
  *   if (item.kind === 'dropdown') {
  *     console.log(item.children);
@@ -383,34 +329,23 @@ declare function buildSimpleMenu(navigation: NavigationMenuWithItems[], routes:
  * });
  * ```
  */
-declare function buildSimpleNestedMenu(navigation: NavigationMenuWithItems[], routes: RouteMap): SimpleNestedMenuViewModel;
+declare function buildMenu(navigation: NavigationMenuWithItems[], routes: RouteMap): Menu;
+/** @deprecated Use `buildMenu` instead */
+declare const buildSimpleMenu: typeof buildMenu;
 /**
- * Build a SimpleLogo from site layout data.
+ * Build a Logo from site layout data.
  *
  * @param logo - Logo data from site layout
  * @param fallbackAlt - Fallback alt text (usually site title)
  *
  * @example
  * ```ts
- * const logo = buildSimpleLogo(siteData.layout.logo, siteData.site.title);
+ * const logo = buildLogo(siteData.layout.logo, siteData.site.title);
  * // { src: 'https://...', alt: 'Site Name', width: 200, height: 50 }
  * ```
  */
-declare function buildSimpleLogo(logo: {
-    url?: string | null;
-    alt?: string | null;
-    width?: number | null;
-    height?: number | null;
-} | null, fallbackAlt: string | null | undefined): SimpleLogo;
-/**
- * @deprecated Use `transformToNavItems` instead.
- * This alias is maintained for backwards compatibility only.
- */
-declare const transformNavItems: typeof transformToNavItems;
-/**
- * @deprecated Use `getPrimaryNavigation` instead.
- * This alias is maintained for backwards compatibility only.
- */
-declare const selectPrimaryMenu: typeof getPrimaryNavigation;
+declare function buildLogo(logo: Partial<LogoSource> | null, fallbackAlt: string | null | undefined): Logo;
+/** @deprecated Use `buildLogo` instead */
+declare const buildSimpleLogo: typeof buildLogo;
 
-export { type CustomLinkValue, type ExternalLinkValue, type InternalLinkValue, type LinkValue, type LogoSource, type LogoViewModel, type MenuCtaViewModel, type MenuLinkViewModel, type MenuViewModel, type NavDropdown, type NavItem, type NavLink, NavigationMenuWithItems, type NestedNavItem, type SimpleLogo, type SimpleMenuViewModel, type SimpleNavLink, type SimpleNestedMenuViewModel, type SimpleNestedNavDropdown, type SimpleNestedNavItem, type SimpleNestedNavLink, buildLogoViewModel, buildMenuViewModel, buildSimpleLogo, buildSimpleMenu, buildSimpleNestedMenu, getNavItemsBySlug, getNavigationBySlug, getNestedNavItemsBySlug, getNestedPrimaryNavItems, getPrimaryNavItems, getPrimaryNavigation, isNavDropdown, isNavLink, selectPrimaryMenu, transformNavItems, transformToNavItems, transformToNestedNavItems };
+export { type CustomLinkValue, type ExternalLinkValue, type InternalLinkValue, type LinkValue, type Logo, type LogoSource, type LogoViewModel, type Menu, type MenuCtaViewModel, type MenuLinkViewModel, type MenuViewModel, type NavDropdown, type NavItem, type NavLink, NavigationMenuWithItems, type SimpleLogo, type SimpleMenuViewModel, type SimpleNavDropdown, type SimpleNavItem, type SimpleNavLink, buildLogo, buildLogoViewModel, buildMenu, buildMenuViewModel, buildSimpleLogo, buildSimpleMenu, getNavItemsBySlug, getNavigationBySlug, getPrimaryNavItems, getPrimaryNavigation, isNavDropdown, isNavLink, transformToNavItems };