@chesapeake/stack 0.1.0

package/components/ux/auth/google/default-client.ts

@@ -0,0 +1,69 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { createGoogleAuthConfig } from "./config.ts";
+import { GoogleAuthClient } from "./client.ts";
+import type { GoogleOAuthProfile } from "./types.ts";
+
+/**
+ * Default Google OAuth client (convention-over-configuration)
+ * Uses sensible defaults and environment variables for easy setup
+ */
+
+let defaultClient: GoogleAuthClient | null = null;
+
+/**
+ * Gets or creates the default Google Auth client
+ */
+function getDefaultClient(): GoogleAuthClient {
+  if (!defaultClient) {
+    const config = createGoogleAuthConfig();
+    defaultClient = new GoogleAuthClient(config);
+  }
+  return defaultClient;
+}
+
+/**
+ * Initiates Google OAuth login with default configuration
+ * Reads from VITE_GOOGLE_CLIENT_ID and VITE_REDIRECT_URI environment variables
+ */
+export function initiateGoogleLogin(): void {
+  getDefaultClient().initiateLogin();
+}
+
+/**
+ * Handles OAuth callback with default configuration
+ * Calls POST /api/auth/google/callback by default
+ * @param code Authorization code from Google OAuth callback
+ * @returns User profile from backend
+ */
+export async function handleGoogleCallback(
+  code: string
+): Promise<GoogleOAuthProfile> {
+  return await getDefaultClient().handleCallback(code);
+}
+
+/**
+ * Default Google Auth class for common use cases
+ */
+export class DefaultGoogleAuth {
+  private client: GoogleAuthClient;
+
+  constructor() {
+    this.client = getDefaultClient();
+  }
+
+  /**
+   * Initiates Google OAuth login
+   */
+  login(): void {
+    this.client.initiateLogin();
+  }
+
+  /**
+   * Handles OAuth callback
+   */
+  async handleCallback(code: string): Promise<GoogleOAuthProfile> {
+    return await this.client.handleCallback(code);
+  }
+}

package/components/ux/auth/google/index.ts

@@ -0,0 +1,43 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+// Types
+export type { GoogleOAuthProfile, GoogleUserProfile } from "./types.ts";
+export { toUserProfile } from "./types.ts";
+
+// Configuration
+export type { GoogleAuthCallbackResponse, GoogleAuthConfig } from "./config.ts";
+export { createGoogleAuthConfig, DEFAULT_SCOPE } from "./config.ts";
+
+// Configurable client (config-over-convention)
+export { GoogleAuthClient, initiateGoogleLogin } from "./client.ts";
+
+// Default client (convention-over-configuration)
+export {
+  DefaultGoogleAuth,
+  handleGoogleCallback,
+  initiateGoogleLogin as defaultInitiateGoogleLogin,
+} from "./default-client.ts";
+
+// Auth Provider
+export {
+  DefaultGoogleAuthProvider,
+  GoogleAuthProvider,
+} from "./AuthProvider.tsx";
+// Hook
+export { useGoogleAuth } from "./useGoogleAuth.ts";
+export type {
+  AuthUser,
+  GoogleAuthContextType,
+  GoogleAuthProviderProps,
+} from "./context.ts";
+
+// Auth Callback
+export {
+  DefaultGoogleAuthCallback,
+  GoogleAuthCallback,
+} from "./AuthCallback.tsx";
+export type {
+  DefaultGoogleAuthCallbackProps,
+  GoogleAuthCallbackProps,
+} from "./AuthCallback.tsx";

package/components/ux/auth/google/types.ts

@@ -0,0 +1,42 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Google OAuth user profile returned from Google's userinfo endpoint
+ */
+export interface GoogleOAuthProfile {
+  sub: string; // Google user ID
+  name: string;
+  email: string;
+  picture?: string;
+  email_verified?: boolean;
+}
+
+/**
+ * User profile structure that can be used by applications
+ * This is the format returned from the backend after OAuth callback
+ */
+export interface GoogleUserProfile {
+  id: string;
+  displayName: string;
+  email: string;
+  profilePicture?: string;
+  googleOAuthId: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Converts Google OAuth profile to application user profile format
+ */
+export function toUserProfile(profile: GoogleOAuthProfile): GoogleUserProfile {
+  return {
+    id: profile.sub,
+    displayName: profile.name,
+    email: profile.email,
+    profilePicture: profile.picture,
+    googleOAuthId: profile.sub,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}

package/components/ux/auth/google/useGoogleAuth.ts

@@ -0,0 +1,16 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { useContext } from "react";
+import { GoogleAuthContext, type GoogleAuthContextType } from "./context.ts";
+
+/**
+ * Hook to access Google Auth context
+ */
+export function useGoogleAuth(): GoogleAuthContextType {
+  const context = useContext(GoogleAuthContext);
+  if (!context) {
+    throw new Error("useGoogleAuth must be used within a GoogleAuthProvider");
+  }
+  return context;
+}

package/components/ux/auth/index.ts

@@ -0,0 +1,72 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+// Multi-Provider Auth
+export { MultiAuthProvider } from "./MultiAuthProvider.tsx";
+export { useAuth } from "./useAuth.ts";
+export type {
+  AuthProviderConfig,
+  AuthUser,
+  MultiAuthContextType,
+  MultiAuthProviderProps,
+} from "./context.ts";
+
+// Auth Selector Component
+export { AuthSelector } from "./AuthSelector.tsx";
+export type { AuthSelectorProps } from "./AuthSelector.tsx";
+
+// Google Auth (re-export for convenience)
+export {
+  createGoogleAuthConfig,
+  DEFAULT_SCOPE as GOOGLE_DEFAULT_SCOPE,
+  DefaultGoogleAuth,
+  DefaultGoogleAuthCallback,
+  DefaultGoogleAuthProvider,
+  defaultInitiateGoogleLogin,
+  GoogleAuthCallback,
+  GoogleAuthClient,
+  GoogleAuthProvider,
+  handleGoogleCallback,
+  initiateGoogleLogin,
+  toUserProfile as toGoogleUserProfile,
+  useGoogleAuth,
+} from "./google/index.ts";
+export type {
+  AuthUser as GoogleAuthUser,
+  DefaultGoogleAuthCallbackProps,
+  GoogleAuthCallbackProps,
+  GoogleAuthCallbackResponse,
+  GoogleAuthConfig,
+  GoogleAuthContextType,
+  GoogleAuthProviderProps,
+  GoogleOAuthProfile,
+  GoogleUserProfile,
+} from "./google/index.ts";
+
+// GitHub Auth (re-export for convenience)
+export {
+  createGitHubAuthConfig,
+  DEFAULT_SCOPE as GITHUB_DEFAULT_SCOPE,
+  DefaultGitHubAuth,
+  DefaultGitHubAuthCallback,
+  DefaultGitHubAuthProvider,
+  defaultInitiateGitHubLogin,
+  GitHubAuthCallback,
+  GitHubAuthClient,
+  GitHubAuthProvider,
+  handleGitHubCallback,
+  initiateGitHubLogin,
+  toUserProfile as toGitHubUserProfile,
+  useGitHubAuth,
+} from "./github/index.ts";
+export type {
+  AuthUser as GitHubAuthUser,
+  DefaultGitHubAuthCallbackProps,
+  GitHubAuthCallbackProps,
+  GitHubAuthCallbackResponse,
+  GitHubAuthConfig,
+  GitHubAuthContextType,
+  GitHubAuthProviderProps,
+  GitHubOAuthProfile,
+  GitHubUserProfile,
+} from "./github/index.ts";

package/components/ux/auth/useAuth.ts

@@ -0,0 +1,16 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { useContext } from "react";
+import { MultiAuthContext, type MultiAuthContextType } from "./context.ts";
+
+/**
+ * Hook to access Multi Auth context
+ */
+export function useAuth(): MultiAuthContextType {
+  const context = useContext(MultiAuthContext);
+  if (!context) {
+    throw new Error("useAuth must be used within a MultiAuthProvider");
+  }
+  return context;
+}

package/components/ux/index.ts

@@ -0,0 +1,46 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+// User Search and Selection Components
+export { UserSearch } from "./UserSearch.tsx";
+export type { UserSearchProps } from "./UserSearch.tsx";
+
+export { SelectedUsersList } from "./SelectedUsersList.tsx";
+export type {
+  SelectedUser,
+  SelectedUsersListProps,
+} from "./SelectedUsersList.tsx";
+
+export { UserSelector } from "./UserSelector.tsx";
+export type { UserSelectorProps } from "./UserSelector.tsx";
+
+// Friend Management Components
+export { FriendList } from "./FriendList.tsx";
+export type { Friend, FriendListProps } from "./FriendList.tsx";
+
+export { FriendRequestList } from "./FriendRequestList.tsx";
+export type {
+  FriendRequest,
+  FriendRequestListProps,
+} from "./FriendRequestList.tsx";
+
+// StandardLayout Components (backward compatibility for PageLayout)
+export {
+  PageContainer,
+  PageContent,
+  PageHeader,
+  PageLayout,
+} from "./StandardLayout/index.ts";
+export type {
+  PageContainerProps,
+  PageContentProps,
+  PageHeaderProps,
+  PageLayoutProps,
+} from "./StandardLayout/index.ts";
+
+// StandardLayout exports
+export { ProfilePage, StandardLayout } from "./StandardLayout/index.ts";
+export type {
+  ProfilePageProps,
+  StandardLayoutProps,
+} from "./StandardLayout/index.ts";

package/components/ux/theme-provider-context.ts

@@ -0,0 +1,20 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { createContext } from "react";
+
+export type Theme = "dark" | "light" | "system";
+
+export interface ThemeProviderState {
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+}
+
+export const initialState: ThemeProviderState = {
+  theme: "system",
+  setTheme: () => null,
+};
+
+export const ThemeProviderContext = createContext<ThemeProviderState | null>(
+  null
+);

package/components/ux/theme-provider.tsx

@@ -0,0 +1,114 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import React, { useEffect, useState } from "react";
+
+import { ThemeProviderContext, type Theme } from "./theme-provider-context.ts";
+
+/**
+ * Props for the ThemeProvider component
+ */
+interface ThemeProviderProps {
+  /** Child components to be wrapped by the provider */
+  children: React.ReactNode;
+  /** Default theme to use if none is stored in localStorage */
+  defaultTheme?: Theme;
+  /** Key used for storing theme preference in localStorage */
+  storageKey?: string;
+}
+
+/**
+ * Provider component for managing application theme (light/dark/system).
+ *
+ * This component manages the theme state and applies the appropriate
+ * CSS class to the document root element. It persists the user's
+ * preference in localStorage.
+ *
+ * The theme system supports:
+ * - `light`: Always use light theme
+ * - `dark`: Always use dark theme
+ * - `system`: Follow the user's OS preference
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <ThemeProvider defaultTheme="system" storageKey="app-theme">
+ *       <YourApp />
+ *     </ThemeProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using the theme in a component
+ * import { useTheme } from "./useTheme";
+ *
+ * function ThemeToggle() {
+ *   const { theme, setTheme } = useTheme();
+ *
+ *   return (
+ *     <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+ *       <option value="light">Light</option>
+ *       <option value="dark">Dark</option>
+ *       <option value="system">System</option>
+ *     </select>
+ *   );
+ * }
+ * ```
+ *
+ * @sideeffect
+ * - Modifies `localStorage` to persist theme preference
+ * - Modifies `document.documentElement.classList` to apply theme class
+ * - Listens to system preference changes when theme is "system"
+ */
+export function ThemeProvider({
+  children,
+  defaultTheme,
+  storageKey,
+  ...props
+}: ThemeProviderProps) {
+  const [theme, setTheme] = useState<Theme>(() => {
+    const stored = localStorage.getItem(storageKey ?? "theme");
+    if (
+      stored &&
+      (stored === "dark" || stored === "light" || stored === "system")
+    ) {
+      return stored as Theme;
+    }
+    return defaultTheme ?? "system";
+  });
+
+  useEffect(() => {
+    const root = globalThis.document.documentElement;
+
+    root.classList.remove("light", "dark");
+
+    if (theme === "system") {
+      const systemTheme = globalThis.matchMedia("(prefers-color-scheme: dark)")
+        .matches
+        ? "dark"
+        : "light";
+
+      root.classList.add(systemTheme);
+      return;
+    }
+
+    root.classList.add(theme);
+  }, [theme]);
+
+  const value = {
+    theme,
+    setTheme: (theme: Theme) => {
+      localStorage.setItem(storageKey ?? "dark", theme);
+      setTheme(theme);
+    },
+  };
+
+  return (
+    <ThemeProviderContext.Provider {...props} value={value}>
+      {children}
+    </ThemeProviderContext.Provider>
+  );
+}

package/components/ux/useTheme.ts

@@ -0,0 +1,42 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { useContext } from "react";
+import {
+  ThemeProviderContext,
+  type ThemeProviderState,
+} from "./theme-provider-context.ts";
+
+/**
+ * Hook for accessing the current theme and theme setter.
+ *
+ * Must be used within a ThemeProvider component.
+ *
+ * @returns {ThemeProviderState} Object containing the current theme and setTheme function
+ * @throws {Error} If used outside of a ThemeProvider
+ *
+ * @example
+ * ```tsx
+ * function ThemeToggle() {
+ *   const { theme, setTheme } = useTheme();
+ *
+ *   return (
+ *     <div className="flex items-center gap-2">
+ *       <span>Current theme: {theme}</span>
+ *       <Button onClick={() => setTheme("dark")}>Dark</Button>
+ *       <Button onClick={() => setTheme("light")}>Light</Button>
+ *       <Button onClick={() => setTheme("system")}>System</Button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const useTheme = (): ThemeProviderState => {
+  const context = useContext(ThemeProviderContext);
+
+  if (!context) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+
+  return context;
+};

package/index.ts

@@ -0,0 +1,29 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @chesapeake/stack
+ *
+ * A reusable React component library and design system built on top of
+ * shadcn/ui with Tailwind CSS.
+ *
+ * @example
+ * ```tsx
+ * import { Button } from '@chesapeake/stack/components/ui/button';
+ * import { ThemeProvider } from '@chesapeake/stack/components/ux/theme-provider';
+ *
+ * function App() {
+ *   return (
+ *     <ThemeProvider>
+ *       <Button variant="default">Click me</Button>
+ *     </ThemeProvider>
+ *   );
+ * }
+ * ```
+ */
+
+// Re-export everything from subdirectories for convenient imports
+export * from "./components/ui/index.ts";
+export * from "./components/ux/index.ts";
+export * from "./lib/utils.ts";
+export { default as tailwindPreset } from "./tailwind.preset.ts";

package/lib/utils.ts

@@ -0,0 +1,57 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * A utility function for conditionally joining class names together.
+ *
+ * Combines the power of `clsx` (for conditional class joining) with
+ * `tailwind-merge` (for resolving Tailwind CSS class conflicts).
+ *
+ * This function is used throughout the component library to handle
+ * className merging with proper Tailwind CSS specificity resolution.
+ *
+ * @param inputs - Class values to be merged. Can be strings, objects, arrays, or falsy values.
+ * @returns A merged and deduplicated className string with resolved Tailwind conflicts.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * cn('px-4 py-2', 'bg-blue-500')
+ * // Result: 'px-4 py-2 bg-blue-500'
+ *
+ * // Conditional classes
+ * cn('px-4', isActive && 'bg-blue-500', !isActive && 'bg-gray-200')
+ * // Result when isActive=true: 'px-4 bg-blue-500'
+ *
+ * // Resolving Tailwind conflicts (tailwind-merge)
+ * cn('px-4 py-2', 'px-6')
+ * // Result: 'py-2 px-6' (px-6 wins over px-4)
+ *
+ * // Object syntax
+ * cn('base-class', {
+ *   'text-red-500': hasError,
+ *   'text-green-500': isSuccess,
+ *   'hidden': !isVisible
+ * })
+ *
+ * // Array syntax
+ * cn(['flex', 'items-center'], 'justify-between')
+ *
+ * // Combining all features
+ * cn(
+ *   'base-styles',
+ *   isLarge && 'text-lg',
+ *   {
+ *     'bg-blue-500': variant === 'primary',
+ *     'bg-gray-500': variant === 'secondary'
+ *   },
+ *   className // External className prop
+ * )
+ * ```
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}