keystone-design-bootstrap 1.0.3

package/README.md

@@ -0,0 +1,179 @@
+# Keystone Design Bootstrap
+
+A comprehensive design system for Keystone customer websites. Provides themed sections, elements, and utilities for building consistent, server-rendered Next.js sites.
+
+## Installation
+
+```bash
+npm install @keystone-pzjr/design-bootstrap
+```
+
+## Package Exports
+
+```typescript
+// Sections (hero, footer, header, testimonials, etc.)
+import { HeroHome, FooterHome, TestimonialsHome } from '@keystone-pzjr/design-bootstrap/sections'
+
+// Elements (buttons, inputs, carousels, etc.)
+import { Button, Input, Carousel } from '@keystone-pzjr/design-bootstrap/elements'
+
+// Hooks
+import { useBreakpoint } from '@keystone-pzjr/design-bootstrap/hooks'
+
+// Theme context
+import { ThemeProvider } from '@keystone-pzjr/design-bootstrap/contexts'
+
+// Server API utilities
+import { getServices, getTestimonials } from '@keystone-pzjr/design-bootstrap/lib/server-api'
+
+// Types
+import type { Service, Testimonial } from '@keystone-pzjr/design-bootstrap/types'
+
+// Themes
+import { themes } from '@keystone-pzjr/design-bootstrap/themes'
+```
+
+## Styles
+
+Import CSS in your `app/globals.css`:
+
+```css
+@import "@keystone-pzjr/design-bootstrap/styles/theme.css";
+@import "@keystone-pzjr/design-bootstrap/styles/typography.css";
+@import "@keystone-pzjr/design-bootstrap/styles/style-overrides.aman.css";
+```
+
+## Theme System
+
+### Available Themes
+
+- **`aman`** - Warm, elegant serif theme (Playfair Display + Inter)
+- **`classic`** - Clean, modern sans-serif theme (Inter)
+
+Themes are defined in `src/themes/index.ts`.
+
+### Component Variants
+
+Components automatically load theme variants based on the active theme:
+
+- `hero-home.tsx` - Base/classic variant
+- `hero-home.aman.tsx` - Aman theme variant
+
+The `createThemedExport()` function in `sections/index.tsx` handles this automatically.
+
+### Tailwind Classes
+
+The design system provides semantic Tailwind classes:
+
+**Backgrounds:**
+- `bg-primary` - Main page background
+- `bg-secondary` - Section backgrounds  
+- `bg-fg-primary` - Dark backgrounds (buttons, accents)
+
+**Text:**
+- `text-fg-primary` - Primary text (dark)
+- `text-secondary` - Secondary text
+- `text-tertiary` - Muted text
+- `text-white` - White text
+
+**Borders:**
+- `border-primary` - Primary borders
+- `border-secondary` - Subtle borders
+
+**Fonts:**
+- `font-display` - Display font for headings
+- `font-body` - Body font for text
+
+### Theme Customization
+
+Override CSS variables in your site's `styles/custom-overrides.css`:
+
+```css
+[data-theme="aman"] {
+  --color-bg-primary: #F9F7F0;
+  --color-text-primary: #1E1E1E;
+  --font-body: "Inter", sans-serif;
+  --font-display: "Playfair Display", serif;
+}
+```
+
+**CSS Cascade:**
+1. `theme.css` - Base design system
+2. `style-overrides.aman.css` - Theme-specific overrides
+3. `custom-overrides.css` - Site-specific customizations (highest priority)
+
+## Using Sections
+
+Sections are pre-built page components that accept data via props:
+
+```typescript
+// In your page.tsx (Server Component)
+import { HeroHome, TestimonialsHome } from '@keystone-pzjr/design-bootstrap/sections'
+import { getTestimonials } from '@keystone-pzjr/design-bootstrap/lib/server-api'
+
+export default async function HomePage() {
+  const testimonials = await getTestimonials()
+  
+  return (
+    <main>
+      <HeroHome config={config} />
+      <TestimonialsHome testimonials={testimonials} config={config} />
+    </main>
+  )
+}
+```
+
+### Available Sections
+
+**Heroes:** `HeroHome`, `HeroServiceDetail`, `HeroLocationDetail`, `HeroFAQ`, `HeroTestimonials`, `HeroSocialMedia`, `HeroGenericText`
+
+**Content:** `ServicesHome`, `ServicesGrid`, `LocationGrid`, `LocationDetailsSection`, `TeamGrid`, `JobGallery`, `AboutHome`, `ValuesSection`, `StatisticsSection`
+
+**Interactive:** `TestimonialsHome`, `BlogSection`, `BlogGallery`, `BlogPost`, `FAQGrid`, `FAQHome`, `SocialMediaGrid`, `ContactSection`
+
+**Navigation:** `HeaderNavigation`, `FooterHome`
+
+## Using Elements
+
+Elements are reusable UI components:
+
+```typescript
+import { Button, Input, Carousel } from '@keystone-pzjr/design-bootstrap/elements'
+
+<Button variant="primary">Click Me</Button>
+<Input label="Email" type="email" />
+<Carousel items={photos} />
+```
+
+## Server API Functions
+
+```typescript
+import {
+  getCompanyInformation,
+  getServices,
+  getService,
+  getLocations,
+  getLocation,
+  getTestimonials,
+  getFAQs,
+  getBlogPosts,
+  getBlogPost,
+  getTeamMembers,
+  getWebsitePhotos,
+  getJobPostings
+} from '@keystone-pzjr/design-bootstrap/lib/server-api'
+```
+
+All functions are async and designed for server-side use only.
+
+## Architecture
+
+- **Server-Side Only**: All components fetch data server-side
+- **Theme Variants**: Automatic component selection based on active theme
+- **Type-Safe**: Full TypeScript support
+- **CSS Variables**: Theme customization via CSS custom properties
+- **Tailwind First**: Semantic utility classes for consistent styling
+
+## License
+
+Private - Keystone PZJR

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "keystone-design-bootstrap",
+  "version": "1.0.3",
+  "description": "Keystone Design Bootstrap - Sections, Elements, and Theme System for customer websites",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./sections": "./src/design_system/sections/index.tsx",
+    "./elements": "./src/design_system/elements/index.tsx",
+    "./logo": "./src/design_system/logo/keystone-logo.tsx",
+    "./hooks": "./src/lib/hooks/index.ts",
+    "./contexts": "./src/contexts/index.ts",
+    "./lib/server-api": "./src/lib/server-api.ts",
+    "./lib/component-registry": "./src/lib/component-registry.ts",
+    "./styles/*": "./src/styles/*",
+    "./types": "./src/types/index.ts",
+    "./themes": "./src/themes/index.ts",
+    "./utils/*": "./src/utils/*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Keystone-PZJR/keystone-design-bootstrap.git"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "dependencies": {
+    "@untitledui/icons": "^0.0.19",
+    "clsx": "^2.1.1",
+    "embla-carousel-react": "^8.6.0",
+    "motion": "^12.23.12",
+    "react-aria": "^3.42.0",
+    "react-aria-components": "^1.12.0",
+    "react-markdown": "^10.1.0",
+    "react-stately": "^3.42.0",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^3.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "tsup": "^8.5.1",
+    "typescript": "^5"
+  }
+}

package/src/contexts/ThemeContext.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+import { Theme, isValidTheme } from '../themes';
+
+interface ThemeContextValue {
+  theme: Theme;
+}
+
+const ThemeContext = createContext<ThemeContextValue>({ theme: 'classic' });
+
+export function ThemeProvider({ 
+  theme, 
+  children 
+}: { 
+  theme: Theme; 
+  children: React.ReactNode;
+}) {
+  // Validate theme at runtime
+  if (!isValidTheme(theme)) {
+    console.warn(`Invalid theme "${theme}", falling back to "classic"`);
+    theme = 'classic';
+  }
+  
+  return (
+    <ThemeContext.Provider value={{ theme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  return useContext(ThemeContext);
+}

package/src/contexts/index.ts

@@ -0,0 +1 @@
+export * from './ThemeContext';

package/src/design_system/elements/IconComponent.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+
+interface IconComponentProps {
+  icon: string;
+  color?: string;
+  className?: string;
+}
+
+const IconComponent = ({ icon, color = 'blue', className = '' }: IconComponentProps) => {
+  const getIconColor = (colorName: string) => {
+    switch (colorName) {
+      case 'blue':
+        return 'text-blue-600';
+      case 'green':
+        return 'text-green-600';
+      case 'red':
+        return 'text-red-600';
+      case 'yellow':
+        return 'text-yellow-600';
+      case 'purple':
+        return 'text-purple-600';
+      case 'gray':
+        return 'text-gray-600';
+      case 'white':
+        return 'text-white';
+      default:
+        return 'text-blue-600';
+    }
+  };
+
+  const renderIcon = () => {
+    switch (icon) {
+      case 'star':
+        return (
+          <svg className={`w-full h-full ${getIconColor(color)}`} fill="currentColor" viewBox="0 0 20 20">
+            <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.175 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81h3.461a1 1 0 00.951-.69l1.07-3.292z"/>
+          </svg>
+        );
+      case 'heart':
+        return (
+          <svg className={`w-full h-full ${getIconColor(color)}`} fill="currentColor" viewBox="0 0 20 20">
+            <path fillRule="evenodd" d="M3.172 5.172a4 4 0 015.656 0L10 6.343l1.172-1.171a4 4 0 115.656 5.656L10 17.657l-6.828-6.829a4 4 0 010-5.656z" clipRule="evenodd"/>
+          </svg>
+        );
+      case 'home':
+        return (
+          <svg className={`w-full h-full ${getIconColor(color)}`} fill="currentColor" viewBox="0 0 20 20">
+            <path d="M10.707 2.293a1 1 0 00-1.414 0l-7 7a1 1 0 001.414 1.414L4 10.414V17a1 1 0 001 1h2a1 1 0 001-1v-2a1 1 0 011-1h2a1 1 0 011 1v2a1 1 0 001 1h2a1 1 0 001-1v-6.586l.293.293a1 1 0 001.414-1.414l-7-7z"/>
+          </svg>
+        );
+      case 'person':
+        return (
+          <svg className={`w-full h-full ${getIconColor(color)}`} fill="currentColor" viewBox="0 0 20 20">
+            <path fillRule="evenodd" d="M10 9a3 3 0 100-6 3 3 0 000 6zm-7 9a7 7 0 1114 0H3z" clipRule="evenodd"/>
+          </svg>
+        );
+      case 'phone':
+        return (
+          <svg className={`w-full h-full ${getIconColor(color)}`} fill="currentColor" viewBox="0 0 20 20">
+            <path d="M2 3a1 1 0 011-1h2.153a1 1 0 01.986.836l.74 4.435a1 1 0 01-.01 1.01l-.804 1.646a1 1 0 00.01 1.01l.74 4.435a1 1 0 01-.986.836H3a1 1 0 01-1-1V3z"/>
+          </svg>
+        );
+      case 'email':
+        return (
+          <svg className={`w-full h-full ${getIconColor(color)}`} fill="currentColor" viewBox="0 0 20 20">
+            <path d="M2.003 5.884L10 9.882l7.997-3.998A2 2 0 0016 4H4a2 2 0 00-1.997 1.884z"/>
+            <path d="M18 8.118l-8 4-8-4V14a2 2 0 002 2h12a2 2 0 002-2V8.118z"/>
+          </svg>
+        );
+      case 'location':
+        return (
+          <svg className={`w-full h-full ${getIconColor(color)}`} fill="currentColor" viewBox="0 0 20 20">
+            <path fillRule="evenodd" d="M5.05 4.05a7 7 0 119.9 9.9L10 18.9l-4.95-4.95a7 7 0 010-9.9zM10 11a2 2 0 100-4 2 2 0 000 4z" clipRule="evenodd"/>
+          </svg>
+        );
+      case 'clock':
+        return (
+          <svg className={`w-full h-full ${getIconColor(color)}`} fill="currentColor" viewBox="0 0 20 20">
+            <path fillRule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm1-12a1 1 0 10-2 0v4a1 1 0 00.293.707l2.828 2.829a1 1 0 101.415-1.415L11 9.586V6z" clipRule="evenodd"/>
+          </svg>
+        );
+      default:
+        return (
+          <svg className={`w-full h-full ${getIconColor(color)}`} fill="currentColor" viewBox="0 0 20 20">
+            <path fillRule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z" clipRule="evenodd"/>
+          </svg>
+        );
+    }
+  };
+
+  return (
+    <div className={className}>
+      {renderIcon()}
+    </div>
+  );
+};
+
+export default IconComponent;

package/src/design_system/elements/avatar/avatar-label-group.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { type ReactNode } from "react";
+import { cx } from '../../../utils/cx';
+import { Avatar, type AvatarProps } from "./avatar";
+
+const styles = {
+    sm: { root: "gap-2", title: "text-sm font-semibold", subtitle: "text-xs" },
+    md: { root: "gap-2", title: "text-sm font-semibold", subtitle: "text-sm" },
+    lg: { root: "gap-3", title: "text-md font-semibold", subtitle: "text-md" },
+    xl: { root: "gap-4", title: "text-lg font-semibold", subtitle: "text-md" },
+};
+
+interface AvatarLabelGroupProps extends AvatarProps {
+    size: "sm" | "md" | "lg" | "xl";
+    title: string | ReactNode;
+    subtitle: string | ReactNode;
+}
+
+export const AvatarLabelGroup = ({ title, subtitle, className, ...props }: AvatarLabelGroupProps) => {
+    return (
+        <figure className={cx("group flex min-w-0 flex-1 items-center", styles[props.size].root, className)}>
+            <Avatar {...props} />
+            <figcaption className="min-w-0 flex-1">
+                <p className={cx("text-primary", styles[props.size].title)}>{title}</p>
+                <p className={cx("truncate text-tertiary", styles[props.size].subtitle)}>{subtitle}</p>
+            </figcaption>
+        </figure>
+    );
+};

package/src/design_system/elements/avatar/avatar-profile-photo.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import { useState } from "react";
+import { User01 } from "@untitledui/icons";
+import { cx } from '../../../utils/cx';
+import { type AvatarProps } from "./avatar";
+import { AvatarOnlineIndicator, VerifiedTick } from "./base-components";
+
+const styles = {
+    sm: {
+        root: "size-18 p-0.75",
+        rootWithPlaceholder: "p-1",
+        content: "",
+        icon: "size-9",
+        initials: "text-display-sm font-semibold",
+        badge: "bottom-0.5 right-0.5",
+    },
+    md: {
+        root: "size-24 p-1",
+        rootWithPlaceholder: "p-1.25",
+        content: "shadow-xl",
+        icon: "size-12",
+        initials: "text-display-md font-semibold",
+        badge: "bottom-1 right-1",
+    },
+    lg: {
+        root: "size-40 p-1.5",
+        rootWithPlaceholder: "p-1.75",
+        content: "shadow-2xl",
+        icon: "size-20",
+        initials: "text-display-xl font-semibold",
+        badge: "bottom-2 right-2",
+    },
+};
+
+const tickSizeMap = {
+    sm: "2xl",
+    md: "3xl",
+    lg: "4xl",
+} as const;
+
+interface AvatarProfilePhotoProps extends AvatarProps {
+    size: "sm" | "md" | "lg";
+}
+
+export const AvatarProfilePhoto = ({
+    contrastBorder = true,
+    size = "md",
+    src,
+    alt,
+    initials,
+    placeholder,
+    placeholderIcon: PlaceholderIcon,
+    verified,
+    badge,
+    status,
+    className,
+}: AvatarProfilePhotoProps) => {
+    const [isFailed, setIsFailed] = useState(false);
+
+    const renderMainContent = () => {
+        if (src && !isFailed) {
+            return (
+                <img
+                    src={src}
+                    alt={alt}
+                    onError={() => setIsFailed(true)}
+                    className={cx(
+                        "size-full rounded-full object-cover",
+                        contrastBorder && "outline-1 -outline-offset-1 outline-avatar-contrast-border",
+                        styles[size].content,
+                    )}
+                />
+            );
+        }
+
+        if (initials) {
+            return (
+                <div className={cx("flex size-full items-center justify-center rounded-full bg-tertiary ring-1 ring-secondary_alt", styles[size].content)}>
+                    <span className={cx("text-quaternary", styles[size].initials)}>{initials}</span>
+                </div>
+            );
+        }
+
+        if (PlaceholderIcon) {
+            return (
+                <div className={cx("flex size-full items-center justify-center rounded-full bg-tertiary ring-1 ring-secondary_alt", styles[size].content)}>
+                    <PlaceholderIcon className={cx("text-fg-quaternary", styles[size].icon)} />
+                </div>
+            );
+        }
+
+        return (
+            <div className={cx("flex size-full items-center justify-center rounded-full bg-tertiary ring-1 ring-secondary_alt", styles[size].content)}>
+                {placeholder || <User01 className={cx("text-fg-quaternary", styles[size].icon)} />}
+            </div>
+        );
+    };
+
+    const renderBadgeContent = () => {
+        if (status) {
+            return <AvatarOnlineIndicator status={status} size={tickSizeMap[size]} className={styles[size].badge} />;
+        }
+
+        if (verified) {
+            return <VerifiedTick size={tickSizeMap[size]} className={cx("absolute", styles[size].badge)} />;
+        }
+
+        return badge;
+    };
+
+    return (
+        <div
+            className={cx(
+                "relative flex shrink-0 items-center justify-center rounded-full bg-primary ring-1 ring-secondary_alt",
+                styles[size].root,
+                (!src || isFailed) && styles[size].rootWithPlaceholder,
+                className,
+            )}
+        >
+            {renderMainContent()}
+            {renderBadgeContent()}
+        </div>
+    );
+};

package/src/design_system/elements/avatar/avatar.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+import { type FC, type ReactNode, useState } from "react";
+import { User01 } from "@untitledui/icons";
+import { cx } from '../../../utils/cx';
+import { AvatarOnlineIndicator, VerifiedTick } from "./base-components";
+
+type AvatarSize = "xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+
+export interface AvatarProps {
+    size?: AvatarSize;
+    className?: string;
+    src?: string | null;
+    alt?: string;
+    /**
+     * Display a contrast border around the avatar.
+     */
+    contrastBorder?: boolean;
+    /**
+     * Display a badge (i.e. company logo).
+     */
+    badge?: ReactNode;
+    /**
+     * Display a status indicator.
+     */
+    status?: "online" | "offline";
+    /**
+     * Display a verified tick icon.
+     *
+     * @default false
+     */
+    verified?: boolean;
+
+    /**
+     * The initials of the user to display if no image is available.
+     */
+    initials?: string;
+    /**
+     * An icon to display if no image is available.
+     */
+    placeholderIcon?: FC<{ className?: string }>;
+    /**
+     * A placeholder to display if no image is available.
+     */
+    placeholder?: ReactNode;
+
+    /**
+     * Whether the avatar should show a focus ring when the parent group is in focus.
+     * For example, when the avatar is wrapped inside a link.
+     *
+     * @default false
+     */
+    focusable?: boolean;
+}
+
+const styles = {
+    xxs: { root: "size-4 outline-[0.5px] -outline-offset-[0.5px]", initials: "text-xs font-semibold", icon: "size-3" },
+    xs: { root: "size-6 outline-[0.5px] -outline-offset-[0.5px]", initials: "text-xs font-semibold", icon: "size-4" },
+    sm: { root: "size-8 outline-[0.75px] -outline-offset-[0.75px]", initials: "text-sm font-semibold", icon: "size-5" },
+    md: { root: "size-10 outline-1 -outline-offset-1", initials: "text-md font-semibold", icon: "size-6" },
+    lg: { root: "size-12 outline-1 -outline-offset-1", initials: "text-lg font-semibold", icon: "size-7" },
+    xl: { root: "size-14 outline-1 -outline-offset-1", initials: "text-xl font-semibold", icon: "size-8" },
+    "2xl": { root: "size-16 outline-1 -outline-offset-1", initials: "text-display-xs font-semibold", icon: "size-8" },
+};
+
+export const Avatar = ({
+    contrastBorder = true,
+    size = "md",
+    src,
+    alt,
+    initials,
+    placeholder,
+    placeholderIcon: PlaceholderIcon,
+    badge,
+    status,
+    verified,
+    focusable = false,
+    className,
+}: AvatarProps) => {
+    const [isFailed, setIsFailed] = useState(false);
+
+    const renderMainContent = () => {
+        if (src && !isFailed) {
+            return <img data-avatar-img className="size-full rounded-full object-cover" src={src} alt={alt} onError={() => setIsFailed(true)} />;
+        }
+
+        if (initials) {
+            return <span className={cx("text-quaternary", styles[size].initials)}>{initials}</span>;
+        }
+
+        if (PlaceholderIcon) {
+            return <PlaceholderIcon className={cx("text-fg-quaternary", styles[size].icon)} />;
+        }
+
+        return placeholder || <User01 className={cx("text-fg-quaternary", styles[size].icon)} />;
+    };
+
+    const renderBadgeContent = () => {
+        if (status) {
+            return <AvatarOnlineIndicator status={status} size={size === "xxs" ? "xs" : size} />;
+        }
+
+        if (verified) {
+            return (
+                <VerifiedTick
+                    size={size === "xxs" ? "xs" : size}
+                    className={cx("absolute right-0 bottom-0", (size === "xxs" || size === "xs") && "-right-px -bottom-px")}
+                />
+            );
+        }
+
+        return badge;
+    };
+
+    return (
+        <div
+            data-avatar
+            className={cx(
+                "relative inline-flex shrink-0 items-center justify-center rounded-full bg-avatar-bg outline-transparent",
+                // Focus styles
+                focusable && "group-outline-focus-ring group-focus-visible:outline-2 group-focus-visible:outline-offset-2",
+                contrastBorder && "outline outline-avatar-contrast-border",
+                styles[size].root,
+                className,
+            )}
+        >
+            {renderMainContent()}
+            {renderBadgeContent()}
+        </div>
+    );
+};