@riverbankcms/sdk 0.6.0 → 0.7.0

package/README.md

@@ -458,6 +458,245 @@ import { usePage, Page } from '@riverbankcms/sdk/client';
 
 The `/client` subpath exports React hooks that require client-side React features (useState, useEffect). The main entry point only exports server-safe code.
 
+## Navigation
+
+The SDK provides navigation utilities for transforming CMS navigation data into render-ready structures. All navigation functions return nested structures that support both direct links and dropdown menus.
+
+### Navigation Types
+
+Navigation items are discriminated unions using a `kind` field:
+
+```typescript
+import type {
+  NavItem,        // NavLink | NavDropdown
+  NavLink,        // Direct link with href
+  NavDropdown,    // Dropdown container with children
+} from '@riverbankcms/sdk/navigation';
+
+// NavLink - a direct navigation link
+type NavLink = {
+  kind: 'link';
+  id: string;
+  label: string;
+  href: string;
+  isExternal: boolean;
+};
+
+// NavDropdown - a dropdown menu container
+type NavDropdown = {
+  kind: 'dropdown';
+  id: string;
+  label: string;
+  children: NavLink[];  // Max 1 level of nesting
+};
+
+// NavItem - either a link or dropdown
+type NavItem = NavLink | NavDropdown;
+```
+
+### Type Guards
+
+Use the provided type guards for safe type narrowing:
+
+```typescript
+import { isNavLink, isNavDropdown } from '@riverbankcms/sdk/navigation';
+
+const items = getPrimaryNavItems(siteData.navigation);
+
+items.forEach(item => {
+  if (isNavLink(item)) {
+    // TypeScript knows this is NavLink
+    console.log(item.href);
+  } else if (isNavDropdown(item)) {
+    // TypeScript knows this is NavDropdown
+    console.log(`${item.label} has ${item.children.length} children`);
+  }
+});
+```
+
+Or use the `kind` discriminator directly:
+
+```typescript
+items.forEach(item => {
+  if (item.kind === 'link') {
+    console.log(item.href);
+  } else {
+    // item.kind === 'dropdown'
+    console.log(item.children);
+  }
+});
+```
+
+### Navigation Helper Functions
+
+```typescript
+import {
+  getPrimaryNavItems,
+  getNavItemsBySlug,
+  getPrimaryNavigation,
+  getNavigationBySlug,
+  transformToNavItems,
+} from '@riverbankcms/sdk/navigation';
+
+// Get nav items from the primary menu (marked isPrimary, or first menu)
+const headerNav = getPrimaryNavItems(siteData.navigation);
+
+// Get nav items from a specific menu by name/slug
+const footerNav = getNavItemsBySlug(siteData.navigation, 'footer');
+
+// Get the raw menu object (for accessing menu metadata)
+const primaryMenu = getPrimaryNavigation(siteData.navigation);
+const footerMenu = getNavigationBySlug(siteData.navigation, 'footer');
+
+// Transform a menu object to nav items
+const items = transformToNavItems(primaryMenu);
+```
+
+### Building Menu and Logo
+
+For rendering, use `buildMenu` and `buildLogo` which resolve all hrefs from the route map:
+
+```typescript
+import type { Menu, Logo } from '@riverbankcms/sdk/navigation';
+import { buildMenu, buildLogo } from '@riverbankcms/sdk/navigation';
+
+// Build menu with pre-resolved hrefs from route map
+const menu = buildMenu(siteData.navigation, siteData.routes);
+
+// menu.items is NavItem[] (links and dropdowns)
+// menu.ctaItem is NavLink | null (CTA is always a link, never dropdown)
+
+const logo = buildLogo(siteData.layout.logo, siteData.site.title);
+```
+
+### Rendering Navigation with Dropdowns
+
+```tsx
+import { getPrimaryNavItems, isNavLink, isNavDropdown } from '@riverbankcms/sdk/navigation';
+
+function Header({ navigation }) {
+  const items = getPrimaryNavItems(navigation);
+
+  return (
+    <nav>
+      {items.map(item => {
+        if (isNavLink(item)) {
+          return (
+            <a
+              key={item.id}
+              href={item.href}
+              target={item.isExternal ? '_blank' : undefined}
+              rel={item.isExternal ? 'noopener noreferrer' : undefined}
+            >
+              {item.label}
+            </a>
+          );
+        }
+
+        // Dropdown
+        return (
+          <div key={item.id} className="dropdown">
+            <button>{item.label}</button>
+            <div className="dropdown-menu">
+              {item.children.map(child => (
+                <a
+                  key={child.id}
+                  href={child.href}
+                  target={child.isExternal ? '_blank' : undefined}
+                >
+                  {child.label}
+                </a>
+              ))}
+            </div>
+          </div>
+        );
+      })}
+    </nav>
+  );
+}
+```
+
+### Rendering Menu in Components
+
+```tsx
+import { buildMenu, buildLogo } from '@riverbankcms/sdk/navigation';
+
+function SiteHeader({ siteData }) {
+  const menu = buildMenu(siteData.navigation, siteData.routes);
+  const logo = buildLogo(siteData.layout.logo, siteData.site.title);
+
+  return (
+    <header>
+      {logo && <img src={logo.src} alt={logo.alt} />}
+
+      <nav>
+        {menu.items.map(item => {
+          if (item.kind === 'link') {
+            return <a key={item.id} href={item.href}>{item.label}</a>;
+          }
+
+          return (
+            <div key={item.id} className="dropdown">
+              <span>{item.label}</span>
+              <ul>
+                {item.children.map(child => (
+                  <li key={child.id}>
+                    <a href={child.href}>{child.label}</a>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          );
+        })}
+      </nav>
+
+      {menu.ctaItem && (
+        <a href={menu.ctaItem.href} className="cta-button">
+          {menu.ctaItem.label}
+        </a>
+      )}
+    </header>
+  );
+}
+```
+
+### Navigation Exports
+
+```typescript
+import {
+  // Helper functions
+  getPrimaryNavItems,
+  getNavItemsBySlug,
+  getPrimaryNavigation,
+  getNavigationBySlug,
+  transformToNavItems,
+  buildMenu,
+  buildLogo,
+  buildMenuViewModel,
+  buildLogoViewModel,
+
+  // Type guards
+  isNavLink,
+  isNavDropdown,
+
+  // Types
+  type NavItem,
+  type NavLink,
+  type NavDropdown,
+  type Menu,
+  type Logo,
+  type MenuViewModel,
+  type MenuLinkViewModel,
+  type MenuCtaViewModel,
+  type LogoViewModel,
+  type LogoSource,
+  type LinkValue,
+  type InternalLinkValue,
+  type ExternalLinkValue,
+  type CustomLinkValue,
+} from '@riverbankcms/sdk/navigation';
+```
+
 ## Layout Component
 
 The `Layout` component renders the site header, footer, and wraps your page content. Use this when you want consistent site chrome across all pages.

package/dist/cli/index.js

@@ -7227,6 +7227,23 @@ ${contentType} (updated):`);
 }
 
 // src/cli/sync/executor.ts
+function hasFieldErrors(details) {
+  if (typeof details !== "object" || details === null || !("fieldErrors" in details)) {
+    return false;
+  }
+  const fieldErrors = details.fieldErrors;
+  return Array.isArray(fieldErrors) && fieldErrors.length > 0;
+}
+function formatApiError(error) {
+  if (!(error instanceof ManagementApiError)) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  let message = error.message;
+  if (hasFieldErrors(error.details)) {
+    message += "\n" + error.details.fieldErrors.map((fe) => `    ${fe.field} (${fe.code}): ${fe.message}`).join("\n");
+  }
+  return message;
+}
 function createEmptyResult() {
   return {
     entries: { created: 0, updated: 0, failed: 0 },
@@ -7266,7 +7283,7 @@ async function syncEntries(client, diff, local, options, result) {
         result.errors.push({
           resource: "entry",
           identifier: `${contentType}/${entryDiff.identifier}`,
-          error: error instanceof Error ? error.message : String(error)
+          error: formatApiError(error)
         });
       }
     }
@@ -7310,7 +7327,7 @@ async function syncPages(client, diff, local, options, result) {
       result.errors.push({
         resource: "page",
         identifier: pageDiff.identifier,
-        error: error instanceof Error ? error.message : String(error)
+        error: formatApiError(error)
       });
     }
   }
@@ -7342,7 +7359,7 @@ async function syncBlocks(client, pageIdentifier, blockDiffs, localBlocks, optio
       result.errors.push({
         resource: "block",
         identifier: `${pageIdentifier}/${blockDiff.identifier}`,
-        error: error instanceof Error ? error.message : String(error)
+        error: formatApiError(error)
       });
     }
   }
@@ -7380,7 +7397,7 @@ async function syncNavigation(client, diff, local, options, result) {
       result.errors.push({
         resource: "navigation",
         identifier: navDiff.name,
-        error: error instanceof Error ? error.message : String(error)
+        error: formatApiError(error)
       });
     }
   }
@@ -7399,7 +7416,7 @@ async function syncSettings(client, diff, local, options, result) {
     result.errors.push({
       resource: "settings",
       identifier: "site",
-      error: error instanceof Error ? error.message : String(error)
+      error: formatApiError(error)
     });
   }
 }