keystone-design-bootstrap 1.0.3

package/src/design_system/elements/pagination/pagination.tsx

@@ -0,0 +1,330 @@
+"use client";
+
+import { ArrowLeft, ArrowRight } from "@untitledui/icons";
+import { Button } from '../buttons/button';
+import { ButtonGroup, ButtonGroupItem } from '../button-group/button-group';
+import { useBreakpoint } from '../../../lib/hooks/use-breakpoint';
+import { cx } from '../../../utils/cx';
+import type { PaginationRootProps } from "./pagination-base";
+import { Pagination } from "./pagination-base";
+
+interface PaginationProps extends Partial<Omit<PaginationRootProps, "children">> {
+    /** Whether the pagination buttons are rounded. */
+    rounded?: boolean;
+}
+
+const PaginationItem = ({ value, rounded, isCurrent }: { value: number; rounded?: boolean; isCurrent: boolean }) => {
+    return (
+        <Pagination.Item
+            value={value}
+            isCurrent={isCurrent}
+            className={({ isSelected }) =>
+                cx(
+                    "flex size-10 cursor-pointer items-center justify-center p-3 text-sm font-medium text-quaternary outline-focus-ring transition duration-100 ease-linear hover:bg-primary_hover hover:text-secondary focus-visible:z-10 focus-visible:bg-primary_hover focus-visible:outline-2 focus-visible:outline-offset-2",
+                    rounded ? "rounded-full" : "rounded-lg",
+                    isSelected && "bg-primary_hover text-secondary",
+                )
+            }
+        >
+            {value}
+        </Pagination.Item>
+    );
+};
+
+interface MobilePaginationProps {
+    /** The current page. */
+    page?: number;
+    /** The total number of pages. */
+    total?: number;
+    /** The class name of the pagination component. */
+    className?: string;
+    /** The function to call when the page changes. */
+    onPageChange?: (page: number) => void;
+}
+
+const MobilePagination = ({ page = 1, total = 10, className, onPageChange }: MobilePaginationProps) => {
+    return (
+        <nav aria-label="Pagination" className={cx("flex items-center justify-between md:hidden", className)}>
+            <Button
+                aria-label="Go to previous page"
+                iconLeading={ArrowLeft}
+                color="secondary"
+                size="sm"
+                onClick={() => onPageChange?.(Math.max(0, page - 1))}
+            />
+
+            <span className="text-sm text-fg-secondary">
+                Page <span className="font-medium">{page}</span> of <span className="font-medium">{total}</span>
+            </span>
+
+            <Button
+                aria-label="Go to next page"
+                iconLeading={ArrowRight}
+                color="secondary"
+                size="sm"
+                onClick={() => onPageChange?.(Math.min(total, page + 1))}
+            />
+        </nav>
+    );
+};
+
+export const PaginationPageDefault = ({ rounded, page = 1, total = 10, className, ...props }: PaginationProps) => {
+    const isDesktop = useBreakpoint("md");
+
+    return (
+        <Pagination.Root
+            {...props}
+            page={page}
+            total={total}
+            className={cx("flex w-full items-center justify-between gap-3 border-t border-secondary pt-4 md:pt-5", className)}
+        >
+            <div className="hidden flex-1 justify-start md:flex">
+                <Pagination.PrevTrigger asChild>
+                    <Button iconLeading={ArrowLeft} color="link-gray" size="sm">
+                        {isDesktop ? "Previous" : undefined}{" "}
+                    </Button>
+                </Pagination.PrevTrigger>
+            </div>
+
+            <Pagination.PrevTrigger asChild className="md:hidden">
+                <Button iconLeading={ArrowLeft} color="secondary" size="sm">
+                    {isDesktop ? "Previous" : undefined}
+                </Button>
+            </Pagination.PrevTrigger>
+
+            <Pagination.Context>
+                {({ pages, currentPage, total }) => (
+                    <>
+                        <div className="hidden justify-center gap-0.5 md:flex">
+                            {pages.map((page, index) =>
+                                page.type === "page" ? (
+                                    <PaginationItem key={index} rounded={rounded} {...page} />
+                                ) : (
+                                    <Pagination.Ellipsis key={index} className="flex size-10 shrink-0 items-center justify-center text-tertiary">
+                                        &#8230;
+                                    </Pagination.Ellipsis>
+                                ),
+                            )}
+                        </div>
+
+                        <div className="flex justify-center text-sm whitespace-pre text-fg-secondary md:hidden">
+                            Page <span className="font-medium">{currentPage}</span> of <span className="font-medium">{total}</span>
+                        </div>
+                    </>
+                )}
+            </Pagination.Context>
+
+            <div className="hidden flex-1 justify-end md:flex">
+                <Pagination.NextTrigger asChild>
+                    <Button iconTrailing={ArrowRight} color="link-gray" size="sm">
+                        {isDesktop ? "Next" : undefined}
+                    </Button>
+                </Pagination.NextTrigger>
+            </div>
+            <Pagination.NextTrigger asChild className="md:hidden">
+                <Button iconTrailing={ArrowRight} color="secondary" size="sm">
+                    {isDesktop ? "Next" : undefined}
+                </Button>
+            </Pagination.NextTrigger>
+        </Pagination.Root>
+    );
+};
+
+export const PaginationPageMinimalCenter = ({ rounded, page = 1, total = 10, className, ...props }: PaginationProps) => {
+    const isDesktop = useBreakpoint("md");
+
+    return (
+        <Pagination.Root
+            {...props}
+            page={page}
+            total={total}
+            className={cx("flex w-full items-center justify-between gap-3 border-t border-secondary pt-4 md:pt-5", className)}
+        >
+            <div className="flex flex-1 justify-start">
+                <Pagination.PrevTrigger asChild>
+                    <Button iconLeading={ArrowLeft} color="secondary" size="sm">
+                        {isDesktop ? "Previous" : undefined}
+                    </Button>
+                </Pagination.PrevTrigger>
+            </div>
+
+            <Pagination.Context>
+                {({ pages, currentPage, total }) => (
+                    <>
+                        <div className="hidden justify-center gap-0.5 md:flex">
+                            {pages.map((page, index) =>
+                                page.type === "page" ? (
+                                    <PaginationItem key={index} rounded={rounded} {...page} />
+                                ) : (
+                                    <Pagination.Ellipsis key={index} className="flex size-10 shrink-0 items-center justify-center text-tertiary">
+                                        &#8230;
+                                    </Pagination.Ellipsis>
+                                ),
+                            )}
+                        </div>
+
+                        <div className="flex justify-center text-sm whitespace-pre text-fg-secondary md:hidden">
+                            Page <span className="font-medium">{currentPage}</span> of <span className="font-medium">{total}</span>
+                        </div>
+                    </>
+                )}
+            </Pagination.Context>
+
+            <div className="flex flex-1 justify-end">
+                <Pagination.NextTrigger asChild>
+                    <Button iconTrailing={ArrowRight} color="secondary" size="sm">
+                        {isDesktop ? "Next" : undefined}
+                    </Button>
+                </Pagination.NextTrigger>
+            </div>
+        </Pagination.Root>
+    );
+};
+
+export const PaginationCardDefault = ({ rounded, page = 1, total = 10, ...props }: PaginationProps) => {
+    const isDesktop = useBreakpoint("md");
+
+    return (
+        <Pagination.Root
+            {...props}
+            page={page}
+            total={total}
+            className="flex w-full items-center justify-between gap-3 border-t border-secondary px-4 py-3 md:px-6 md:pt-3 md:pb-4"
+        >
+            <div className="flex flex-1 justify-start">
+                <Pagination.PrevTrigger asChild>
+                    <Button iconLeading={ArrowLeft} color="secondary" size="sm">
+                        {isDesktop ? "Previous" : undefined}
+                    </Button>
+                </Pagination.PrevTrigger>
+            </div>
+
+            <Pagination.Context>
+                {({ pages, currentPage, total }) => (
+                    <>
+                        <div className="hidden justify-center gap-0.5 md:flex">
+                            {pages.map((page, index) =>
+                                page.type === "page" ? (
+                                    <PaginationItem key={index} rounded={rounded} {...page} />
+                                ) : (
+                                    <Pagination.Ellipsis key={index} className="flex size-10 shrink-0 items-center justify-center text-tertiary">
+                                        &#8230;
+                                    </Pagination.Ellipsis>
+                                ),
+                            )}
+                        </div>
+
+                        <div className="flex justify-center text-sm whitespace-pre text-fg-secondary md:hidden">
+                            Page <span className="font-medium">{currentPage}</span> of <span className="font-medium">{total}</span>
+                        </div>
+                    </>
+                )}
+            </Pagination.Context>
+
+            <div className="flex flex-1 justify-end">
+                <Pagination.NextTrigger asChild>
+                    <Button iconTrailing={ArrowRight} color="secondary" size="sm">
+                        {isDesktop ? "Next" : undefined}
+                    </Button>
+                </Pagination.NextTrigger>
+            </div>
+        </Pagination.Root>
+    );
+};
+
+interface PaginationCardMinimalProps {
+    /** The current page. */
+    page?: number;
+    /** The total number of pages. */
+    total?: number;
+    /** The alignment of the pagination. */
+    align?: "left" | "center" | "right";
+    /** The class name of the pagination component. */
+    className?: string;
+    /** The function to call when the page changes. */
+    onPageChange?: (page: number) => void;
+}
+
+export const PaginationCardMinimal = ({ page = 1, total = 10, align = "left", onPageChange, className }: PaginationCardMinimalProps) => {
+    return (
+        <div className={cx("border-t border-secondary px-4 py-3 md:px-6 md:pt-3 md:pb-4", className)}>
+            <MobilePagination page={page} total={total} onPageChange={onPageChange} />
+
+            <nav aria-label="Pagination" className={cx("hidden items-center gap-3 md:flex", align === "center" && "justify-between")}>
+                <div className={cx(align === "center" && "flex flex-1 justify-start")}>
+                    <Button isDisabled={page === 1} color="secondary" size="sm" onClick={() => onPageChange?.(Math.max(0, page - 1))}>
+                        Previous
+                    </Button>
+                </div>
+
+                <span
+                    className={cx(
+                        "text-sm font-medium text-fg-secondary",
+                        align === "right" && "order-first mr-auto",
+                        align === "left" && "order-last ml-auto",
+                    )}
+                >
+                    Page {page} of {total}
+                </span>
+
+                <div className={cx(align === "center" && "flex flex-1 justify-end")}>
+                    <Button isDisabled={page === total} color="secondary" size="sm" onClick={() => onPageChange?.(Math.min(total, page + 1))}>
+                        Next
+                    </Button>
+                </div>
+            </nav>
+        </div>
+    );
+};
+
+interface PaginationButtonGroupProps extends Partial<Omit<PaginationRootProps, "children">> {
+    /** The alignment of the pagination. */
+    align?: "left" | "center" | "right";
+}
+
+export const PaginationButtonGroup = ({ align = "left", page = 1, total = 10, ...props }: PaginationButtonGroupProps) => {
+    const isDesktop = useBreakpoint("md");
+
+    return (
+        <div
+            className={cx(
+                "flex border-t border-secondary px-4 py-3 md:px-6 md:pt-3 md:pb-4",
+                align === "left" && "justify-start",
+                align === "center" && "justify-center",
+                align === "right" && "justify-end",
+            )}
+        >
+            <Pagination.Root {...props} page={page} total={total}>
+                <Pagination.Context>
+                    {({ pages }) => (
+                        <ButtonGroup size="md">
+                            <Pagination.PrevTrigger asChild>
+                                <ButtonGroupItem iconLeading={ArrowLeft}>{isDesktop ? "Previous" : undefined}</ButtonGroupItem>
+                            </Pagination.PrevTrigger>
+
+                            {pages.map((page, index) =>
+                                page.type === "page" ? (
+                                    <Pagination.Item key={index} {...page} asChild>
+                                        <ButtonGroupItem isSelected={page.isCurrent} className="size-10 items-center justify-center">
+                                            {page.value}
+                                        </ButtonGroupItem>
+                                    </Pagination.Item>
+                                ) : (
+                                    <Pagination.Ellipsis key={index}>
+                                        <ButtonGroupItem className="pointer-events-none size-10 items-center justify-center rounded-none!">
+                                            &#8230;
+                                        </ButtonGroupItem>
+                                    </Pagination.Ellipsis>
+                                ),
+                            )}
+
+                            <Pagination.NextTrigger asChild>
+                                <ButtonGroupItem iconTrailing={ArrowRight}>{isDesktop ? "Next" : undefined}</ButtonGroupItem>
+                            </Pagination.NextTrigger>
+                        </ButtonGroup>
+                    )}
+                </Pagination.Context>
+            </Pagination.Root>
+        </div>
+    );
+};

package/src/design_system/elements/photo-fallback/photo-fallback.tsx

@@ -0,0 +1,143 @@
+'use client';
+
+import React, { useState, useEffect, useMemo } from 'react';
+import { getGradientUrl } from '../../../utils/gradient-placeholder';
+import type { WebsitePhotos } from '../../../types/api/website-photos';
+import type { CompanyInformation } from '../../../types/api/company-information';
+
+interface PhotoWithFallbackProps {
+  // Generic object with photo_attachments (service, location, team member, blog post, etc.)
+  item?: {
+    id?: number;
+    name?: string;
+    title?: string;
+    photo_attachments?: Array<{
+      id: number;
+      featured: boolean;
+      photo?: {
+        id: number;
+        title: string;
+        thumbnail_url?: string;
+        medium_url?: string;
+        large_url?: string;
+        original_url?: string;
+      };
+    }>;
+  };
+  // Generic photo props (for direct photo URLs)
+  photoUrl?: string;
+  photoAlt?: string;
+  // Fallback props
+  fallbackId?: number | string;
+  // Image props
+  className?: string;
+  alt?: string;
+  // SSR data props (optional)
+  websitePhotos?: WebsitePhotos | null;
+  companyInformation?: CompanyInformation | null;
+}
+
+/**
+ * Reusable component that displays a photo with automatic fallback to gradient.
+ * Supports photo_attachments from any object (services, locations, team members, blog posts, etc.),
+ * direct photo URLs, or gradient fallback.
+ */
+export default function PhotoWithFallback({
+  item,
+  photoUrl,
+  photoAlt,
+  fallbackId,
+  className = '',
+  alt,
+  websitePhotos,
+  companyInformation,
+}: PhotoWithFallbackProps) {
+  // Use data from props (SSR)
+  const isStubMode = (companyInformation as any)?.account_status === 'stub';
+  const stockPhotos = websitePhotos?.stock_photos || [];
+
+  // Determine the image URL synchronously to avoid gradient flash
+  const { imageUrl, imageAlt } = useMemo(() => {
+    // Priority 1: Direct photoUrl prop
+    if (photoUrl) {
+      return { imageUrl: photoUrl, imageAlt: photoAlt || alt || "" };
+    }
+
+    // Priority 2: Photo from photo_attachments
+    if (item?.photo_attachments && item.photo_attachments.length > 0) {
+      const photoAttachments = item.photo_attachments;
+      const featuredPhoto = photoAttachments.find((pa) => pa.featured) || photoAttachments[0];
+      const photo = featuredPhoto?.photo;
+      
+      if (photo) {
+        const url = photo.large_url || photo.medium_url || photo.thumbnail_url || photo.original_url;
+        if (url) {
+          return {
+            imageUrl: url,
+            imageAlt: photo.title || item.name || item.title || alt || "Image"
+          };
+        }
+      }
+    }
+
+    // Priority 3: In stub mode, use random stock photo if available
+    if (isStubMode && stockPhotos.length > 0) {
+      const randomIndex = Math.floor(Math.random() * stockPhotos.length);
+      const stockPhoto = stockPhotos[randomIndex];
+      if (stockPhoto?.url) {
+        return {
+          imageUrl: stockPhoto.url,
+          imageAlt: stockPhoto.alt || item?.name || item?.title || alt || "Image"
+        };
+      }
+    }
+
+    // Priority 4: Fallback to gradient
+    const id = fallbackId || item?.id || 1;
+    return {
+      imageUrl: getGradientUrl(id),
+      imageAlt: item?.name || item?.title || alt || "Image"
+    };
+  }, [item, photoUrl, photoAlt, fallbackId, alt, isStubMode, stockPhotos]);
+
+  const [isLoaded, setIsLoaded] = useState(false);
+  const imgRef = React.useRef<HTMLImageElement>(null);
+
+  // Reset loaded state when image URL changes
+  useEffect(() => {
+    setIsLoaded(false);
+    
+    const timer = setTimeout(() => {
+      if (imgRef.current?.complete && imgRef.current.naturalWidth > 0) {
+        setIsLoaded(true);
+      }
+    }, 0);
+    
+    return () => clearTimeout(timer);
+  }, [imageUrl]);
+
+  // Callback ref to check if image is already loaded (cached images)
+  const setImgRef = React.useCallback((img: HTMLImageElement | null) => {
+    imgRef.current = img;
+    if (img && img.complete && img.naturalWidth > 0) {
+      setIsLoaded(true);
+    }
+  }, []);
+
+  if (!imageUrl) {
+    return null;
+  }
+
+  return (
+    <img
+      ref={setImgRef}
+      src={imageUrl}
+      alt={imageAlt}
+      className={`${className} transition-opacity duration-500 ease-in-out ${
+        isLoaded ? 'opacity-100' : 'opacity-0'
+      }`}
+      onLoad={() => setIsLoaded(true)}
+      onError={() => setIsLoaded(true)}
+    />
+  );
+}

package/src/design_system/elements/progress-indicators/progress-circles.tsx

@@ -0,0 +1,176 @@
+"use client";
+
+import { cx as clx, sortCx } from '../../../utils/cx';
+
+interface ProgressBarProps {
+    value: number;
+    min?: number;
+    max?: number;
+    size: "xxs" | "xs" | "sm" | "md" | "lg";
+    label?: string;
+    valueFormatter?: (value: number, valueInPercentage: number) => string | number;
+}
+
+const sizes = sortCx({
+    xxs: {
+        strokeWidth: 6,
+        radius: 29,
+        valueClass: "text-sm font-semibold text-primary",
+        labelClass: "text-xs font-medium text-tertiary",
+        halfCircleTextPosition: "absolute bottom-0.5 text-center",
+    },
+    xs: {
+        strokeWidth: 16,
+        radius: 72,
+        valueClass: "text-display-xs font-semibold text-primary",
+        labelClass: "text-xs font-medium text-tertiary",
+        halfCircleTextPosition: "absolute bottom-0.5 text-center",
+    },
+    sm: {
+        strokeWidth: 20,
+        radius: 90,
+        valueClass: "text-display-sm font-semibold text-primary",
+        labelClass: "text-xs font-medium text-tertiary",
+        halfCircleTextPosition: "absolute bottom-1 text-center",
+    },
+    md: {
+        strokeWidth: 24,
+        radius: 108,
+        valueClass: "text-display-md font-semibold text-primary",
+        labelClass: "text-sm font-medium text-tertiary",
+        halfCircleTextPosition: "absolute bottom-1 text-center",
+    },
+    lg: {
+        strokeWidth: 28,
+        radius: 126,
+        valueClass: "text-display-lg font-semibold text-primary",
+        labelClass: "text-sm font-medium text-tertiary",
+        halfCircleTextPosition: "absolute bottom-0 text-center",
+    },
+});
+
+export const ProgressBarCircle = ({ value, min = 0, max = 100, size, label, valueFormatter }: ProgressBarProps) => {
+    const percentage = Math.round(((value - min) * 100) / (max - min));
+
+    const sizeConfig = sizes[size];
+
+    const { strokeWidth, radius, valueClass, labelClass } = sizeConfig;
+
+    const diameter = 2 * (radius + strokeWidth / 2);
+    const width = diameter;
+    const height = diameter;
+    const viewBox = `0 0 ${width} ${height}`;
+    const cx = diameter / 2;
+    const cy = diameter / 2;
+
+    const textPosition = label ? "absolute text-center" : "absolute text-primary";
+    const strokeDashoffset = 100 - percentage;
+
+    return (
+        <div className="flex flex-col items-center gap-0.5">
+            <div role="progressbar" aria-valuenow={value} aria-valuemin={min} aria-valuemax={max} className="relative flex w-max items-center justify-center">
+                <svg className="-rotate-90" width={width} height={height} viewBox={viewBox}>
+                    {/* Background circle */}
+                    <circle
+                        className="stroke-bg-quaternary"
+                        cx={cx}
+                        cy={cy}
+                        r={radius}
+                        fill="none"
+                        strokeWidth={strokeWidth}
+                        pathLength="100"
+                        strokeDasharray="100"
+                        strokeLinecap="round"
+                    />
+
+                    {/* Foreground circle */}
+                    <circle
+                        className="stroke-fg-brand-primary"
+                        cx={cx}
+                        cy={cy}
+                        r={radius}
+                        fill="none"
+                        strokeWidth={strokeWidth}
+                        pathLength="100"
+                        strokeDasharray="100"
+                        strokeLinecap="round"
+                        strokeDashoffset={strokeDashoffset}
+                    />
+                </svg>
+                {label && size !== "xxs" ? (
+                    <div className="absolute text-center">
+                        <div className={labelClass}>{label}</div>
+                        <div className={valueClass}>{valueFormatter ? valueFormatter(value, percentage) : `${percentage}%`}</div>
+                    </div>
+                ) : (
+                    <span className={clx(textPosition, valueClass)}>{valueFormatter ? valueFormatter(value, percentage) : `${percentage}%`}</span>
+                )}
+            </div>
+
+            {label && size === "xxs" && <div className={labelClass}>{label}</div>}
+        </div>
+    );
+};
+
+export const ProgressBarHalfCircle = ({ value, min = 0, max = 100, size, label, valueFormatter }: ProgressBarProps) => {
+    const percentage = Math.round(((value - min) * 100) / (max - min));
+
+    const sizeConfig = sizes[size];
+
+    const { strokeWidth, radius, valueClass, labelClass, halfCircleTextPosition } = sizeConfig;
+
+    const width = 2 * (radius + strokeWidth / 2);
+    const height = radius + strokeWidth;
+    const viewBox = `0 0 ${width} ${height}`;
+    const cx = "50%";
+    const cy = radius + strokeWidth / 2;
+
+    const strokeDashoffset = -50 - (100 - percentage) / 2;
+
+    return (
+        <div className="flex flex-col items-center gap-0.5">
+            <div role="progressbar" aria-valuenow={value} aria-valuemin={min} aria-valuemax={max} className="relative flex w-max items-center justify-center">
+                <svg width={width} height={height} viewBox={viewBox}>
+                    {/* Background half-circle */}
+                    <circle
+                        className="stroke-bg-quaternary"
+                        cx={cx}
+                        cy={cy}
+                        r={radius}
+                        fill="none"
+                        strokeWidth={strokeWidth}
+                        pathLength="100"
+                        strokeDasharray="100"
+                        strokeDashoffset="-50"
+                        strokeLinecap="round"
+                    />
+
+                    {/* Foreground half-circle */}
+                    <circle
+                        className="origin-center -scale-x-100 stroke-fg-brand-primary"
+                        cx={cx}
+                        cy={cy}
+                        r={radius}
+                        fill="none"
+                        strokeWidth={strokeWidth}
+                        pathLength="100"
+                        strokeDasharray="100"
+                        strokeDashoffset={strokeDashoffset}
+                        strokeLinecap="round"
+                    />
+                </svg>
+
+                {label && size !== "xxs" ? (
+                    <div className={halfCircleTextPosition}>
+                        <div className={labelClass}>{label}</div>
+                        <div className={valueClass}>{valueFormatter ? valueFormatter(value, percentage) : `${percentage}%`}</div>
+                    </div>
+                ) : (
+                    <span className={clx(halfCircleTextPosition, valueClass)}>{valueFormatter ? valueFormatter(value, percentage) : `${percentage}%`}</span>
+                )}
+            </div>
+
+            {label && size === "xxs" && <div className={labelClass}>{label}</div>}
+        </div>
+    );
+};