@tpzdsp/next-toolkit 1.0.1

package/src/components/layout/header/Header.tsx

@@ -0,0 +1,89 @@
+import type { ComponentType } from 'react';
+
+import { FaHouse } from 'react-icons/fa6';
+
+import { HeaderAuthClient } from './HeaderAuthClient';
+import { HeaderNavClient } from './HeaderNavClient';
+import type { Credentials, NavLink } from '../../../types';
+import { DefraLogo } from '../../images/DefraLogo';
+import { EaLogo } from '../../images/EaLogo';
+import { ExternalLink } from '../../link/ExternalLink';
+import { Link } from '../../link/Link';
+
+type HeaderProps = {
+  credentials: Credentials | null;
+  dspUrl: string;
+  appName: string;
+  navLinks: NavLink[];
+  // headerAuthClientComponent: ComponentType<{ credentials: Credentials | null; hostname: string }>;
+  headerNavClientComponent?: ComponentType<{ navLinks: NavLink[] }>;
+};
+
+export const Header = ({
+  credentials,
+  dspUrl,
+  appName,
+  navLinks,
+  // headerAuthClientComponent,
+  headerNavClientComponent = HeaderNavClient,
+}: HeaderProps) => {
+  const HeaderNav = headerNavClientComponent;
+
+  return (
+    <header className="bg-black w-full text-white border-b-2 border-brand">
+      <div
+        className="grid grid-rows-[min-content_min-content] grid-cols-2 md:grid-cols-3 gap-x-4
+          gap-y-2 md:gap-y-0 py-2 px-3 border-b border-gray-500"
+      >
+        <ExternalLink
+          href="https://www.gov.uk/government/organisations/department-for-environment-food-rural-affairs"
+          className="justify-center text-white visited:text-white active:text-black hover:text-white
+            text-base"
+        >
+          <span className="flex flex-col sm:flex-row sm:items-center gap-1 flex-1">
+            <DefraLogo className="w-[50px] h-[50px]" />
+
+            <span>Department for Environment Food &amp; Rural Affairs</span>
+          </span>
+        </ExternalLink>
+
+        <ExternalLink
+          href="/"
+          className="flex gap-1 text-base items-center text-white md:justify-self-center
+            justify-self-end h-min self-center visited:text-white active:text-black
+            hover:text-white"
+        >
+          <FaHouse className="shrink-0" />
+
+          <span>Data Services Platform</span>
+        </ExternalLink>
+
+        {dspUrl ? <HeaderAuthClient hostname={dspUrl} credentials={credentials} /> : <></>}
+      </div>
+
+      <div
+        className="w-full bg-white grid grid-cols-[1fr_min-content]
+          2xs:grid-cols-[min-content_minmax(0,_1fr)_min-content] grid-rows-1 sm:grid-rows-none py-2
+          px-1 sm:px-3 items-center gap-y-4 gap-2"
+      >
+        <ExternalLink
+          href="https://www.gov.uk/government/organisations/environment-agency"
+          className="justify-self-start text-black hidden 2xs:block min-w-32"
+        >
+          <EaLogo className="text-nowrap overflow-hidden pl-2" />
+        </ExternalLink>
+
+        <Link
+          href="/"
+          className="text-center font-bold text-base sm:text-lg text-black visited:text-black
+            active:text-black hover:text-black"
+        >
+          {appName}
+        </Link>
+
+        {/* <HeaderNavClient navLinks={navLinks} /> */}
+        <HeaderNav navLinks={navLinks} />
+      </div>
+    </header>
+  );
+};

package/src/components/layout/header/HeaderAuthClient.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+import type { Credentials } from '../../../types';
+import { Link } from '../../link/Link';
+
+type HeaderAuthClientProps = {
+  credentials: Credentials | null;
+  hostname: string;
+};
+
+export const HeaderAuthClient = ({ hostname, credentials }: HeaderAuthClientProps) => {
+  console.log('HeaderAuthClient: ', { hostname, credentials });
+
+  return (
+    <span
+      className="flex gap-2 justify-self-start text-base col-span-2 row-start-2 col-start-1
+        md:row-start-1 md:col-start-3 h-min md:justify-self-end self-center items-center"
+    >
+      <span className="text-base border-r border-white pr-2 wrap break-anywhere sm:break-word">
+        <span>Welcome,</span> {credentials ? credentials.user.email : 'Guest'}
+      </span>
+
+      <Link
+        href={`${hostname}/${credentials ? 'api/logout' : 'login'}?redirect-uri=${encodeURIComponent(window?.location?.href)}`}
+        className="text-white visited:text-white active:text-black hover:text-white"
+        prefetch={false}
+      >
+        <span className="text-base">{credentials ? 'Logout' : 'Login'}</span>
+      </Link>
+    </span>
+  );
+};

package/src/components/layout/header/HeaderNavClient.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import type { NavLink } from '../../../types';
+import { DropdownMenu, type DropdownMenuItem } from '../../dropdown/DropdownMenu';
+import { ExternalLink } from '../../link/ExternalLink';
+import { Link } from '../../link/Link';
+
+type HeaderNavClientProps = {
+  navLinks: NavLink[];
+};
+
+const ExternalNavItem = ({ label, url, icon, ...props }: DropdownMenuItem<NavLink>) => (
+  <ExternalLink href={url} {...props}>
+    {icon ?? null}
+    <span>{label}</span>
+  </ExternalLink>
+);
+
+const InternalNavItem = ({ label, url, icon, ...props }: DropdownMenuItem<NavLink>) => (
+  <Link {...props} href={url}>
+    {icon ?? null}
+    <span>{label}</span>
+  </Link>
+);
+
+const NavItem = (props: DropdownMenuItem<NavLink>) => {
+  if (props.isExternal) {
+    return <ExternalNavItem {...props} />;
+  }
+
+  return <InternalNavItem {...props} />;
+};
+
+export const HeaderNavClient = ({ navLinks }: HeaderNavClientProps) => {
+  return (
+    <>
+      <nav className="block sm:hidden" aria-label="Small Screen Navigation">
+        <DropdownMenu
+          items={navLinks}
+          itemRenderer={NavItem}
+          itemClassName="text-black cursor-pointer px-2 py-1 gap-1 text-base flex items-center shrink-0"
+        />
+      </nav>
+
+      <nav
+        className="hidden sm:block col-span-full sm:col-span-1 sm:justify-self-end sm:gap-4 min-w-0
+          px-2 gap-2"
+        aria-label="Large Screen Navigation"
+      >
+        <ul className="flex flex-row gap-2 order-1 shrink-0">
+          {navLinks.map((link) => (
+            <li key={link.label} className="w-full py-1">
+              <NavItem
+                {...link}
+                className="text-black visited:text-black active:text-black hover:text-black gap-1
+                  text-base flex items-center justify-center shrink-0 w-max"
+              />
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </>
+  );
+};

package/src/components/link/ExternalLink.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+
+import { twMerge } from 'tailwind-merge';
+
+import type { ExtendProps } from '../../types';
+
+type Props = {
+  children: ReactNode;
+};
+
+export type ExternalLinkProps = ExtendProps<'a', Props>;
+
+export const ExternalLink = ({ href, className, children, ...props }: ExternalLinkProps) => (
+  <a
+    {...props}
+    className={twMerge(
+      `cursor-pointer text-link hover:decoration-[max(3px,_.1875rem,_.12em)] hover:text-link-hover
+      visited:text-link-visited focus:decoration-[max(3px,_.1875rem,_.12em)]
+      decoration-[max(1px,_.0625rem)] underline-offset-[0.1578em] underline outline-none
+      focus:text-focus-text focus:bg-focus inline-block`,
+      className,
+    )}
+    href={href}
+    rel="noopener noreferrer"
+    target="_blank"
+  >
+    {children}
+  </a>
+);

package/src/components/link/Link.tsx

@@ -0,0 +1,26 @@
+import NextLink from 'next/link';
+import { twMerge } from 'tailwind-merge';
+
+import type { ExtendProps } from '../../types';
+
+type Props = {
+  href: string | object;
+};
+
+export type LinkProps = ExtendProps<typeof NextLink, Props>;
+
+export const Link = ({ href, className, children, ...props }: LinkProps) => (
+  <NextLink
+    {...props}
+    className={twMerge(
+      `cursor-pointer text-link hover:decoration-[max(3px,_.1875rem,_.12em)] hover:text-link-hover
+      visited:text-link-visited active:text-black focus:decoration-[max(3px,_.1875rem,_.12em)]
+      decoration-[max(1px,_.0625rem)] underline-offset-[0.1578em] underline outline-none
+      focus:text-focus-text focus:bg-focus inline-block`,
+      className,
+    )}
+    href={href}
+  >
+    <>{children}</>
+  </NextLink>
+);

package/src/components/link/NextLinkWrapper.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import Link from 'next/link';
+
+import { cn } from '../../utils';
+
+export type NextLinkWrapperProps = {
+  href: string;
+  children: ReactNode;
+  className?: string;
+  target?: '_blank' | '_self' | '_parent' | '_top';
+  rel?: string;
+  prefetch?: boolean;
+  replace?: boolean;
+  scroll?: boolean;
+  shallow?: boolean;
+};
+
+export const NextLinkWrapper = ({
+  href,
+  children,
+  className,
+  target,
+  rel,
+  prefetch,
+  replace,
+  scroll,
+  shallow,
+  ...props
+}: NextLinkWrapperProps) => {
+  // Handle external links
+  const isExternal =
+    href.startsWith('http') || href.startsWith('mailto:') || href.startsWith('tel:');
+
+  if (isExternal) {
+    return (
+      <a
+        href={href}
+        className={cn('text-blue-600 hover:text-blue-800 transition-colors', className)}
+        target={target ?? '_blank'}
+        rel={rel ?? 'noopener noreferrer'}
+        {...props}
+      >
+        {children}
+      </a>
+    );
+  }
+
+  return (
+    <Link
+      href={href}
+      className={cn('text-blue-600 hover:text-blue-800 transition-colors', className)}
+      prefetch={prefetch}
+      replace={replace}
+      scroll={scroll}
+      shallow={shallow}
+      target={target}
+      rel={rel}
+      {...props}
+    >
+      {children}
+    </Link>
+  );
+};

package/src/components/theme/ThemeProvider.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { ThemeContext } from '../../contexts';
+import { useLocalStorage } from '../../hooks';
+
+export type ThemeProviderProps = {
+  children: ReactNode;
+  defaultTheme?: 'light' | 'dark';
+};
+
+export const ThemeProvider = ({ children, defaultTheme = 'light' }: ThemeProviderProps) => {
+  const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('theme', defaultTheme);
+
+  const toggleTheme = () => {
+    setTheme(theme === 'light' ? 'dark' : 'light');
+  };
+
+  const value = {
+    theme,
+    toggleTheme,
+  };
+
+  return (
+    <ThemeContext.Provider value={value}>
+      <div className={theme === 'dark' ? 'dark' : ''}>{children}</div>
+    </ThemeContext.Provider>
+  );
+};

package/src/contexts/ThemeContext.tsx

@@ -0,0 +1,72 @@
+'use client'; // This is necessary for Next.js to treat this file as a client-side component
+
+import { createContext, useContext, useState, useEffect } from 'react';
+import type { ReactNode } from 'react';
+
+import type { ThemeContextValue } from '../types';
+
+export const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+type ThemeProviderProps = {
+  children: ReactNode;
+  defaultTheme?: 'light' | 'dark';
+};
+
+export const ThemeProvider = ({ children, defaultTheme = 'light' }: ThemeProviderProps) => {
+  const [theme, setTheme] = useState<'light' | 'dark'>(() => {
+    if (typeof window === 'undefined') {
+      return defaultTheme;
+    }
+
+    // Check localStorage first
+    const savedTheme = localStorage.getItem('theme') as 'light' | 'dark';
+
+    if (savedTheme) {
+      return savedTheme;
+    }
+
+    // Check system preference
+    if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+      return 'dark';
+    }
+
+    return defaultTheme;
+  });
+
+  const toggleTheme = () => {
+    const newTheme = theme === 'light' ? 'dark' : 'light';
+
+    setTheme(newTheme);
+
+    if (typeof window !== 'undefined') {
+      localStorage.setItem('theme', newTheme);
+    }
+  };
+
+  useEffect(() => {
+    // Add theme class to document element
+    if (typeof window !== 'undefined') {
+      const root = window.document.documentElement;
+
+      root.classList.remove('light', 'dark');
+      root.classList.add(theme);
+    }
+  }, [theme]);
+
+  const value: ThemeContextValue = {
+    theme,
+    toggleTheme,
+  };
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+};
+
+export const useTheme = (): ThemeContextValue => {
+  const context = useContext(ThemeContext);
+
+  if (context === undefined) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+
+  return context;
+};

package/src/contexts/index.ts

@@ -0,0 +1,5 @@
+// Export all contexts and hooks
+export { useTheme, ThemeContext } from './ThemeContext';
+
+// Export context types
+export type { ThemeContextValue } from '../types';

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+// Export all hooks
+export { useLocalStorage } from './useLocalStorage';
+export { useDebounce } from './useDebounce';
+
+// Export hook types
+export type { UseLocalStorageReturn } from './useLocalStorage';

package/src/hooks/useDebounce.ts

@@ -0,0 +1,18 @@
+import { useState, useEffect } from 'react';
+
+export const useDebounce = <T>(value: T, delay: number): T => {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    // Cleanup function to clear the timeout if value changes
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]); // Re-run effect when value or delay changes
+
+  return debouncedValue;
+};

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,57 @@
+import { useState, useCallback } from 'react';
+
+export type UseLocalStorageReturn<T> = [T, (value: T | ((val: T) => T)) => void, () => void];
+
+export const useLocalStorage = <T>(key: string, initialValue: T): UseLocalStorageReturn<T> => {
+  // State to store our value
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    if (typeof window === 'undefined') {
+      return initialValue;
+    }
+
+    try {
+      const item = window.localStorage.getItem(key);
+
+      return item ? JSON.parse(item) : initialValue;
+    } catch (error) {
+      console.error(`Error reading localStorage key "${key}":`, error);
+
+      return initialValue;
+    }
+  });
+
+  // Return a wrapped version of useState's setter function that persists to localStorage
+  const setValue = useCallback(
+    (value: T | ((val: T) => T)) => {
+      try {
+        // Allow value to be a function so we have the same API as useState
+        const valueToStore = value instanceof Function ? value(storedValue) : value;
+
+        setStoredValue(valueToStore);
+
+        // Save to localStorage
+        if (typeof window !== 'undefined') {
+          window.localStorage.setItem(key, JSON.stringify(valueToStore));
+        }
+      } catch (error) {
+        console.error(`Error setting localStorage key "${key}":`, error);
+      }
+    },
+    [key, storedValue],
+  );
+
+  // Function to remove the item from localStorage
+  const removeValue = useCallback(() => {
+    try {
+      setStoredValue(initialValue);
+
+      if (typeof window !== 'undefined') {
+        window.localStorage.removeItem(key);
+      }
+    } catch (error) {
+      console.error(`Error removing localStorage key "${key}":`, error);
+    }
+  }, [key, initialValue]);
+
+  return [storedValue, setValue, removeValue];
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+// Export all components.
+export * from './components';
+
+// Export all utilities (these can be used in both client and server)
+export * from './utils';
+
+// Export all types
+export * from './types';

package/src/types.ts

@@ -0,0 +1,99 @@
+// Common types used throughout the library and consuming applications
+import type { ComponentProps, ReactNode } from 'react';
+
+export type BaseProps = {
+  className?: string;
+  children?: ReactNode;
+};
+
+export type NextLinkProps = {
+  href: string;
+  children: ReactNode;
+  className?: string;
+  target?: '_blank' | '_self' | '_parent' | '_top';
+  rel?: string;
+};
+
+export type ThemeContextValue = {
+  theme: 'light' | 'dark';
+  toggleTheme: () => void;
+};
+
+// Component variant types
+export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+export type CardVariant = 'default' | 'elevated' | 'outlined';
+export type ContainerSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+// Common utility types that apps might need
+export type Variant = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info';
+export type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type Status = 'idle' | 'loading' | 'success' | 'error';
+export type Theme = 'light' | 'dark' | 'system';
+
+// Form related types
+export type FormFieldProps = {
+  name: string;
+  label?: string;
+  error?: string;
+  required?: boolean;
+  disabled?: boolean;
+  className?: string;
+};
+
+// API related types
+export type ApiResponse<T = unknown> = {
+  data: T;
+  success: boolean;
+  message?: string;
+  errors?: Record<string, string[]>;
+};
+
+export type PaginationMeta = {
+  page: number;
+  perPage: number;
+  total: number;
+  totalPages: number;
+};
+
+export type PaginatedResponse<T = unknown> = {
+  meta: PaginationMeta;
+} & ApiResponse<T[]>;
+
+// Event handler types
+export type ClickHandler = (event: React.MouseEvent<HTMLElement>) => void;
+export type ChangeHandler<T = HTMLInputElement> = (event: React.ChangeEvent<T>) => void;
+export type SubmitHandler = (event: React.FormEvent<HTMLFormElement>) => void;
+
+// Utility types for better developer experience
+export type PropsWithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
+export type PropsWithOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+export type ExtendProps<
+  // `ComponentProps` internally constrains `Comp` to be `JSXElementConstructor<any>`,
+  // and since our type must have the same constraints to avoid errors, `any` is required here
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  Comp extends keyof React.JSX.IntrinsicElements | React.JSXElementConstructor<any>,
+  Props = object,
+> = Props & Omit<ComponentProps<Comp>, keyof Props>;
+
+// Define an interface for the decoded JWT payload
+export type DecodedJWT = {
+  name: string;
+  email: string;
+  groupInfoIds: string[];
+  exp?: number; // Optional: JWT expiration timestamp
+  [key: string]: unknown; // Additional claims
+};
+
+export type Credentials = {
+  token: string;
+  user: DecodedJWT;
+};
+
+export type NavLink = {
+  label: string;
+  url: string;
+  isExternal: boolean;
+  icon?: ReactNode;
+};

package/src/utils/auth.ts

@@ -0,0 +1,19 @@
+'use server';
+
+import { cookies } from 'next/headers';
+import type { NextRequest } from 'next/server';
+
+import { COOKIE_NAME } from './constants';
+import { decodeAuthToken } from './utils';
+import type { Credentials } from '../types';
+
+export const getCredentials = async (source?: NextRequest | null): Promise<Credentials | null> => {
+  const cookieStore = source ? source?.cookies : await cookies();
+  const token = cookieStore.get(COOKIE_NAME)?.value;
+
+  if (!token) {
+    return null;
+  }
+
+  return decodeAuthToken(token);
+};

package/src/utils/constants.ts

@@ -0,0 +1,3 @@
+export const COOKIE_NAME = 'auth0-jwt-test';
+
+export const SUPPORT_URL = '/support';

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './utils';
+export * from './auth';
+export * from './constants';
+export * from './renderers'; // This has testing-library dependencies, so probably need to add them as peer dependencies