@djangocfg/nextjs 1.0.1

package/src/navigation/utils.ts

@@ -0,0 +1,181 @@
+/**
+ * Navigation Utilities
+ *
+ * Common utilities for route definitions and navigation
+ */
+
+import type { RouteDefinition, RouteMetadata, MenuItem } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Route Definition Helper
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface RouteConfig {
+  /** Base path for static builds (optional) */
+  basePath?: string;
+  /** Whether this is a static build (optional, defaults to false) */
+  isStaticBuild?: boolean;
+}
+
+/**
+ * Manage base path for routes
+ */
+function manageBasePath(path: string, config?: RouteConfig): string {
+  if (!config?.isStaticBuild || !config?.basePath) {
+    return path;
+  }
+  return `${config.basePath}${path}`;
+}
+
+/**
+ * Define a route with automatic basePath injection
+ *
+ * NOTE: For static builds, Next.js automatically prepends basePath to <Link> hrefs,
+ * so we don't add it here. For dev mode, we need to add it manually.
+ */
+export function defineRoute(
+  path: string,
+  metadata: RouteMetadata,
+  config?: RouteConfig
+): RouteDefinition {
+  // In static builds, Next.js handles basePath automatically
+  // In dev mode, we need to add it manually for consistency
+  const fullPath = manageBasePath(path, config);
+
+  return {
+    path: fullPath,
+    metadata,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Route Guards
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get redirect path for unauthenticated users
+ */
+export function getUnauthenticatedRedirect(
+  path: string,
+  authPath: string = '/auth',
+  config?: RouteConfig
+): string | null {
+  if (path.startsWith('/private') || path.startsWith('/admin')) {
+    // In static builds, Next.js handles basePath automatically
+    return manageBasePath(authPath, config);
+  }
+  return null;
+}
+
+/**
+ * Get redirect path to auth page
+ */
+export function redirectToAuth(
+  authPath: string = '/auth',
+  config?: RouteConfig
+): string {
+  // In static builds, Next.js handles basePath automatically
+  return manageBasePath(authPath, config);
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Route Lookup
+// ─────────────────────────────────────────────────────────────────────────
+
+export function findRoute(
+  routes: RouteDefinition[],
+  path: string
+): RouteDefinition | undefined {
+  return routes.find((r) => r.path === path);
+}
+
+export function findRouteByPattern(
+  routes: RouteDefinition[],
+  path: string
+): RouteDefinition | undefined {
+  const exact = findRoute(routes, path);
+  if (exact) return exact;
+
+  const segments = path.split('/').filter(Boolean);
+  for (let i = segments.length; i > 0; i--) {
+    const parentPath = '/' + segments.slice(0, i).join('/');
+    const parent = findRoute(routes, parentPath);
+    if (parent) return parent;
+  }
+
+  return undefined;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Page Title
+// ─────────────────────────────────────────────────────────────────────────
+
+export function getPageTitle(
+  routes: RouteDefinition[],
+  path: string,
+  fallback = 'Dashboard'
+): string {
+  const route = findRouteByPattern(routes, path);
+  return route?.metadata.label || fallback;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Active Route
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if a route is active
+ *
+ * @param current - Current pathname
+ * @param target - Target route path to check
+ * @param allRoutes - Optional array of all routes to prevent parent paths from being active when child paths are active
+ * @returns true if the route is active
+ */
+export function isActive(
+  current: string,
+  target: string,
+  allRoutes?: RouteDefinition[]
+): boolean {
+  const matches =
+    current === target || (target !== '/' && current.startsWith(target + '/'));
+
+  // If allRoutes is provided, check for more specific paths
+  if (matches && allRoutes) {
+    return !allRoutes.some(
+      (otherRoute) =>
+        otherRoute.path !== target &&
+        otherRoute.path.startsWith(target + '/') &&
+        (current === otherRoute.path ||
+          current.startsWith(otherRoute.path + '/'))
+    );
+  }
+
+  return matches;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Menu Generation Helper
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Filter and convert routes to menu items
+ */
+export function routesToMenuItems(
+  routes: RouteDefinition[],
+  groupName: string
+): MenuItem[] {
+  return routes
+    .filter(
+      (r) =>
+        r.metadata.group === groupName &&
+        r.metadata.icon &&
+        (r.metadata.show === undefined || r.metadata.show === true)
+    )
+    .sort((a, b) => (a.metadata.order || 0) - (b.metadata.order || 0))
+    .map((r) => ({
+      path: r.path,
+      label: r.metadata.label,
+      icon: r.metadata.icon!,
+    }));
+}
+

package/src/og-image/README.md

@@ -0,0 +1,66 @@
+# OG Image Metadata Helper
+
+Automatically add `og:image` to Next.js metadata.
+
+## Usage
+
+### In layout.tsx or page.tsx
+
+```typescript
+import type { Metadata } from 'next';
+import { generateOgImageMetadata } from '@djangocfg/nextjs/og-image';
+import { settings } from '@core/settings';
+
+export const metadata: Metadata = generateOgImageMetadata(
+  {
+    title: 'My Page',
+    description: 'Page description',
+  },
+  {
+    title: 'My Page',
+    description: 'Page description',
+  },
+  {
+    ogImageBaseUrl: '/api/og',
+    siteUrl: settings.app.siteUrl,
+    defaultParams: {
+      siteName: settings.app.name,
+      logo: settings.app.icons.logoVector,
+    },
+  }
+);
+```
+
+### With Generator (Recommended)
+
+```typescript
+// lib/metadata.ts
+import { createOgImageMetadataGenerator } from '@djangocfg/nextjs/og-image';
+import { settings } from '@core/settings';
+
+export const generateMetadata = createOgImageMetadataGenerator({
+  ogImageBaseUrl: '/api/og',
+  siteUrl: settings.app.siteUrl,
+  defaultParams: {
+    siteName: settings.app.name,
+    logo: settings.app.icons.logoVector,
+  },
+});
+
+// page.tsx
+import { generateMetadata } from '@/lib/metadata';
+
+export const metadata = generateMetadata(
+  { title: 'My Page', description: 'Description' },
+  { title: 'My Page', description: 'Description' }
+);
+```
+
+## What It Does
+
+Automatically adds to HTML:
+- `<meta property="og:image" content="...">`
+- `<meta name="twitter:image" content="...">`
+- `<meta name="twitter:card" content="summary_large_image">`
+
+The URL is generated based on parameters and automatically added to metadata.

package/src/og-image/components/DefaultTemplate.tsx

@@ -0,0 +1,369 @@
+/**
+ * Default OG Image Template
+ *
+ * A modern, gradient-based template for OG images
+ */
+
+import type { ReactElement } from 'react';
+import type { OgImageTemplateProps } from '../types';
+
+/**
+ * Default OG Image Template Component
+ *
+ * Features:
+ * - Modern gradient background
+ * - Responsive text sizing
+ * - Optional logo and site name
+ * - Clean typography
+ * - Full customization support
+ *
+ * @param props - Template props with title, description, siteName, logo and optional customization
+ */
+export function DefaultTemplate({
+  title,
+  description,
+  siteName,
+  logo,
+  // Visibility flags
+  showLogo = true,
+  showSiteName = true,
+  // Background customization
+  backgroundType = 'gradient',
+  gradientStart = '#667eea',
+  gradientEnd = '#764ba2',
+  backgroundColor = '#ffffff',
+  // Typography - Title
+  titleSize,
+  titleWeight = 800,
+  titleColor = 'white',
+  // Typography - Description
+  descriptionSize = 32,
+  descriptionColor = 'rgba(255, 255, 255, 0.85)',
+  // Typography - Site Name
+  siteNameSize = 28,
+  siteNameColor = 'rgba(255, 255, 255, 0.95)',
+  // Layout
+  padding = 80,
+  logoSize = 48,
+  // Dev mode
+  devMode = false,
+}: OgImageTemplateProps): ReactElement {
+  // Calculate title size if not provided (responsive based on title length)
+  const calculatedTitleSize = titleSize || (title.length > 60 ? 56 : 72);
+  
+  // Determine background style
+  const backgroundStyle =
+    backgroundType === 'gradient'
+      ? `linear-gradient(135deg, ${gradientStart} 0%, ${gradientEnd} 100%)`
+      : backgroundColor;
+
+  // Grid overlay for dev mode
+  const gridOverlay = devMode ? (
+    <div
+      style={{
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        backgroundImage: `
+          linear-gradient(rgba(0, 0, 0, 0.1) 1px, transparent 1px),
+          linear-gradient(90deg, rgba(0, 0, 0, 0.1) 1px, transparent 1px)
+        `,
+        backgroundSize: '20px 20px',
+        pointerEvents: 'none',
+        zIndex: 10,
+      }}
+    />
+  ) : null;
+
+  return (
+    <div
+      style={{
+        height: '100%',
+        width: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'flex-start',
+        justifyContent: 'space-between',
+        background: backgroundStyle,
+        padding: `${padding}px`,
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+        position: 'relative',
+      }}
+    >
+      {gridOverlay}
+      
+      {/* Header with logo and site name */}
+      {((showLogo && logo) || (showSiteName && siteName)) && (
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '16px',
+          }}
+        >
+          {showLogo && logo && (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={logo}
+              alt="Logo"
+              width={logoSize}
+              height={logoSize}
+              style={{
+                borderRadius: '8px',
+              }}
+            />
+          )}
+          {showSiteName && siteName && (
+            <div
+              style={{
+                fontSize: siteNameSize,
+                fontWeight: 600,
+                color: siteNameColor,
+                letterSpacing: '-0.02em',
+              }}
+            >
+              {siteName}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Main content */}
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '24px',
+          flex: 1,
+          justifyContent: 'center',
+        }}
+      >
+        {/* Title */}
+        <div
+          style={{
+            fontSize: calculatedTitleSize,
+            fontWeight: titleWeight,
+            color: titleColor,
+            lineHeight: 1.1,
+            letterSpacing: '-0.03em',
+            textShadow: backgroundType === 'gradient' ? '0 2px 20px rgba(0, 0, 0, 0.2)' : 'none',
+            maxWidth: '100%',
+            wordWrap: 'break-word',
+          }}
+        >
+          {title}
+        </div>
+
+        {/* Description */}
+        {description && (
+          <div
+            style={{
+              fontSize: descriptionSize,
+              fontWeight: 400,
+              color: descriptionColor,
+              lineHeight: 1.5,
+              letterSpacing: '-0.01em',
+              maxWidth: '90%',
+              display: '-webkit-box',
+              WebkitLineClamp: 2,
+              WebkitBoxOrient: 'vertical',
+              overflow: 'hidden',
+            }}
+          >
+            {description}
+          </div>
+        )}
+      </div>
+
+      {/* Footer decoration */}
+      <div
+        style={{
+          display: 'flex',
+          width: '100%',
+          height: '4px',
+          background: backgroundType === 'gradient' 
+            ? `linear-gradient(90deg, ${gradientStart} 0%, ${gradientEnd} 100%)`
+            : gradientStart,
+          borderRadius: '2px',
+        }}
+      />
+    </div>
+  );
+}
+
+/**
+ * Simple light template variant
+ * 
+ * Light background variant with dark text
+ */
+export function LightTemplate({
+  title,
+  description,
+  siteName,
+  logo,
+  // Visibility flags
+  showLogo = true,
+  showSiteName = true,
+  // Background customization (defaults to light theme)
+  backgroundType = 'solid',
+  gradientStart = '#667eea',
+  gradientEnd = '#764ba2',
+  backgroundColor = '#ffffff',
+  // Typography - Title
+  titleSize,
+  titleWeight = 800,
+  titleColor = '#111',
+  // Typography - Description
+  descriptionSize = 32,
+  descriptionColor = '#666',
+  // Typography - Site Name
+  siteNameSize = 28,
+  siteNameColor = '#111',
+  // Layout
+  padding = 80,
+  logoSize = 48,
+  // Dev mode
+  devMode = false,
+}: OgImageTemplateProps): ReactElement {
+  // Calculate title size if not provided (responsive based on title length)
+  const calculatedTitleSize = titleSize || (title.length > 60 ? 56 : 72);
+  
+  // Determine background style
+  const backgroundStyle =
+    backgroundType === 'gradient'
+      ? `linear-gradient(135deg, ${gradientStart} 0%, ${gradientEnd} 100%)`
+      : backgroundColor;
+
+  // Grid overlay for dev mode
+  const gridOverlay = devMode ? (
+    <div
+      style={{
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        backgroundImage: `
+          linear-gradient(rgba(0, 0, 0, 0.1) 1px, transparent 1px),
+          linear-gradient(90deg, rgba(0, 0, 0, 0.1) 1px, transparent 1px)
+        `,
+        backgroundSize: '20px 20px',
+        pointerEvents: 'none',
+        zIndex: 10,
+      }}
+    />
+  ) : null;
+
+  return (
+    <div
+      style={{
+        height: '100%',
+        width: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'flex-start',
+        justifyContent: 'space-between',
+        background: backgroundStyle,
+        padding: `${padding}px`,
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+        position: 'relative',
+      }}
+    >
+      {gridOverlay}
+      
+      {/* Header with logo and site name */}
+      {((showLogo && logo) || (showSiteName && siteName)) && (
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '16px',
+          }}
+        >
+          {showLogo && logo && (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={logo}
+              alt="Logo"
+              width={logoSize}
+              height={logoSize}
+              style={{
+                borderRadius: '8px',
+              }}
+            />
+          )}
+          {showSiteName && siteName && (
+            <div
+              style={{
+                fontSize: siteNameSize,
+                fontWeight: 600,
+                color: siteNameColor,
+                letterSpacing: '-0.02em',
+              }}
+            >
+              {siteName}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Main content */}
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '24px',
+          flex: 1,
+          justifyContent: 'center',
+        }}
+      >
+        {/* Title */}
+        <div
+          style={{
+            fontSize: calculatedTitleSize,
+            fontWeight: titleWeight,
+            color: titleColor,
+            lineHeight: 1.1,
+            letterSpacing: '-0.03em',
+            maxWidth: '100%',
+            wordWrap: 'break-word',
+          }}
+        >
+          {title}
+        </div>
+
+        {/* Description */}
+        {description && (
+          <div
+            style={{
+              fontSize: descriptionSize,
+              fontWeight: 400,
+              color: descriptionColor,
+              lineHeight: 1.5,
+              letterSpacing: '-0.01em',
+              maxWidth: '90%',
+            }}
+          >
+            {description}
+          </div>
+        )}
+      </div>
+
+      {/* Footer decoration */}
+      <div
+        style={{
+          display: 'flex',
+          width: '100%',
+          height: '4px',
+          background: backgroundType === 'gradient' 
+            ? `linear-gradient(90deg, ${gradientStart} 0%, ${gradientEnd} 100%)`
+            : gradientStart,
+          borderRadius: '2px',
+        }}
+      />
+    </div>
+  );
+}
+

package/src/og-image/components/index.ts

@@ -0,0 +1,9 @@
+/**
+ * OG Image Template Components
+ * 
+ * Client-safe exports (no server dependencies)
+ */
+
+export { DefaultTemplate, LightTemplate } from './DefaultTemplate';
+export type { OgImageTemplateProps } from '../types';
+

package/src/og-image/index.ts

@@ -0,0 +1,27 @@
+/**
+ * OG Image exports
+ */
+
+export { createOgImageHandler, createOgImageDynamicRoute } from './route';
+export type { OgImageHandlerConfig } from './route';
+export type { OgImageTemplateProps } from './types';
+
+export { DefaultTemplate, LightTemplate } from './components';
+
+export {
+  loadGoogleFont,
+  loadGoogleFonts,
+  createFontLoader,
+  generateOgImageUrl,
+  getAbsoluteOgImageUrl,
+  createOgImageUrlBuilder,
+  parseOgImageUrl,
+  parseOgImageData,
+  encodeBase64,
+  decodeBase64,
+  generateOgImageMetadata,
+  createOgImageMetadataGenerator,
+  type FontConfig,
+  type OgImageUrlParams,
+  type OgImageMetadataOptions,
+} from './utils';