@gostack-framework/ui 0.0.0-stage → 0.1.0

package/src/support/types/viewCard.types.ts

@@ -0,0 +1,100 @@
+// ViewCard types
+
+// Field item in a section
+export interface ViewCardFieldItem {
+    label: string;
+    value: string | number | null | React.ReactNode | undefined;
+    colSpan?: number; // Number of columns this field should span (default: 1)
+    type?: "file" | "image";
+}
+
+// Row structure for ViewCard
+export interface ViewCardRow {
+    mainTitle?: string;
+    title?: string;
+    fields?: ViewCardFieldItem[];
+    customRender?: () => React.ReactNode; // Optional custom render function
+}
+
+// Generic data structure for ViewCard
+export interface ViewCardData {
+    rows: ViewCardRow[];
+}
+
+// Variant type
+export type ViewCardVariant = "user" | "vessel" | "tabs" | "default";
+
+// Props for the ViewCard component
+export interface ViewCardProps {
+    headerTitle?: string;
+    hideHeaderTitle?: boolean;
+    title?: string;
+    subtitle?: string;
+    variant?: ViewCardVariant;
+    image?: string;
+    data?: ViewCardData;
+    buttons?: boolean;
+    ticketButton?: boolean;
+    hideBorder?: boolean;
+    tabs?: ViewCardTabItem[];
+    gridCols?: number; // Number of columns for the grid layout (1-6)
+    onEdit?: () => void;
+    onDelete?: () => void;
+    onTicket?: () => void;
+
+    customButtonLabel?: string;
+    onCustomButton?: (() => void) | (() => React.ReactNode);
+}
+
+// Props for the ViewCardSection component
+export interface ViewCardSectionProps {
+    label?: string;
+    children: React.ReactNode;
+}
+
+// Props for the ViewCardField component
+export interface ViewCardFieldProps {
+    label: string;
+    value?: string | number | React.ReactNode | null;
+    type?: "file" | "image";
+}
+
+// Props for the ViewCardButtons component
+export interface ViewCardButtonsProps {
+    customButtonLabel?: string;
+    ticketButton?: boolean;
+    onEdit?: () => void;
+    onDelete?: () => void;
+    onTicket?: () => void;
+    onCustomButton?: (() => void) | (() => React.ReactNode);
+}
+
+export interface ViewCardHeaderProps {
+    headerTitle?: string;
+    hideHeaderTitle?: boolean;
+    buttons?: boolean;
+    ticketButton?: boolean;
+    onEdit?: () => void;
+    onDelete?: () => void;
+    onTicket?: () => void;
+
+    customButtonLabel?: string;
+    onCustomButton?: (() => void) | (() => React.ReactNode);
+}
+
+export interface ViewCardTabItem {
+    label: string;
+    value: string;
+    buttonLabel?: string;
+    buttonHref?: string;
+    entity?: string | string[];
+    role?: string | string[];
+    children: React.ReactNode;
+    buttons?: boolean;
+    onEdit?: () => void;
+    onDelete?: () => void;
+    onTicket?: () => void;
+
+    customButtonLabel?: string;
+    onCustomButton?: (() => void) | (() => React.ReactNode);
+}

package/src/support/utils/fileUtils.ts

@@ -0,0 +1 @@
+export { exportToCSV, exportToExcel, exportToPrint } from '@gostack-framework/react';

package/src/support/utils.ts

@@ -0,0 +1,3 @@
+import * as icons from 'lucide-react';
+export { cn } from '@gostack-framework/react';
+export const lucid_icons = icons as unknown as Record<string, React.ComponentType<{ className?: string; size?: number | string }>>;

package/src/table/index.ts

@@ -0,0 +1,6 @@
+export * from "../components/table";
+export * from "../components/DataTable";
+export * from "../components/TableActions";
+export * from "../components/BulkActionBar";
+export * from "../components/DataCard";
+export * from "../components/StatusProgressBar";

package/src/tasks.ts

@@ -0,0 +1,3 @@
+export * from "./clickup";
+export * from "./components/ClickUpTaskModal";
+export { TaskDetailsModal } from "./components/TaskDetailsModal";

package/src/tours/TourContext.tsx

@@ -0,0 +1,142 @@
+import React, { createContext, useContext, useState, useEffect } from "react";
+
+export interface TourStep {
+    selector: string;
+    titleKey: string;
+    contentKey: string;
+    placement?: "top" | "bottom" | "left" | "right" | "center";
+}
+
+export interface Tour {
+    id: string;
+    steps: TourStep[];
+}
+
+interface TourContextType {
+    activeTourId: string | null;
+    currentStepIndex: number;
+    activeStep: TourStep | null;
+    steps: TourStep[];
+    startTour: (tourId: string, options?: { force?: boolean }) => void;
+    nextStep: () => void;
+    prevStep: () => void;
+    skipTour: () => void;
+    completeTour: () => void;
+    isFirstTime: (tourId: string) => boolean;
+}
+
+const TourContext = createContext<TourContextType | undefined>(undefined);
+
+export interface TourProviderProps {
+    children: React.ReactNode;
+    config: Record<string, Tour>;
+    storageKey?: string;
+}
+
+export const TourProvider: React.FC<TourProviderProps> = ({ children, config, storageKey = "gostack:seen-tours" }) => {
+    const [activeTourId, setActiveTourId] = useState<string | null>(null);
+    const [currentStepIndex, setCurrentStepIndex] = useState<number>(0);
+    const [seenTours, setSeenTours] = useState<Record<string, boolean>>({});
+
+    // Load seen tours from localStorage on mount
+    useEffect(() => {
+        try {
+            const stored = localStorage.getItem(storageKey);
+            if (stored) {
+                setSeenTours(JSON.parse(stored));
+            }
+        } catch (e) {
+            console.error("Failed to load seen tours from localStorage", e);
+        }
+    }, [storageKey]);
+
+    const saveSeenTour = (tourId: string) => {
+        const updated = { ...seenTours, [tourId]: true };
+        setSeenTours(updated);
+        try {
+            localStorage.setItem(storageKey, JSON.stringify(updated));
+        } catch (e) {
+            console.error("Failed to save seen tours to localStorage", e);
+        }
+    };
+
+    const isFirstTime = (tourId: string) => {
+        return !seenTours[tourId];
+    };
+
+    const steps = activeTourId ? config[activeTourId]?.steps || [] : [];
+    const activeStep = activeTourId ? steps[currentStepIndex] || null : null;
+
+    const startTour = (tourId: string, options?: { force?: boolean }) => {
+        const isSeen = seenTours[tourId];
+        const isForce = options?.force ?? false;
+        
+        // Only start if it hasn't been seen before or we are forcing it (e.g. from help button)
+        if (!isSeen || isForce) {
+            // Find if tour exists in config
+            if (config[tourId]) {
+                setActiveTourId(tourId);
+                setCurrentStepIndex(0);
+            }
+        }
+    };
+
+    const nextStep = () => {
+        if (!activeTourId) return;
+        if (currentStepIndex < steps.length - 1) {
+            setCurrentStepIndex((prev) => prev + 1);
+        } else {
+            completeTour();
+        }
+    };
+
+    const prevStep = () => {
+        if (!activeTourId) return;
+        if (currentStepIndex > 0) {
+            setCurrentStepIndex((prev) => prev - 1);
+        }
+    };
+
+    const skipTour = () => {
+        if (activeTourId) {
+            saveSeenTour(activeTourId);
+            setActiveTourId(null);
+            setCurrentStepIndex(0);
+        }
+    };
+
+    const completeTour = () => {
+        if (activeTourId) {
+            saveSeenTour(activeTourId);
+            setActiveTourId(null);
+            setCurrentStepIndex(0);
+        }
+    };
+
+    return (
+        <TourContext.Provider
+            value={{
+                activeTourId,
+                currentStepIndex,
+                activeStep,
+                steps,
+                startTour,
+                nextStep,
+                prevStep,
+                skipTour,
+                completeTour,
+                isFirstTime,
+            }}
+        >
+            {children}
+        </TourContext.Provider>
+    );
+};
+
+export const useTour = () => {
+    const context = useContext(TourContext);
+    if (!context) {
+        throw new Error("useTour must be used within a TourProvider");
+    }
+    return context;
+};

package/src/tours/TourOverlay.tsx

@@ -0,0 +1,281 @@
+import { AnimatePresence, motion } from "framer-motion";
+import { ChevronLeft, ChevronRight, X } from "lucide-react";
+import React, { useEffect, useRef, useState } from "react";
+import ReactDOM from "react-dom";
+import { Button } from "../components/button";
+import { useTour } from "./TourContext";
+
+export interface TourOverlayProps {
+    t: (key: string, options?: any) => string;
+    isRTL?: boolean;
+}
+
+export const TourOverlay: React.FC<TourOverlayProps> = ({ t, isRTL = false }) => {
+    const {
+        activeTourId,
+        currentStepIndex,
+        activeStep,
+        steps,
+        nextStep,
+        prevStep,
+        skipTour,
+    } = useTour();
+
+    const [targetRect, setTargetRect] = useState<DOMRect | null>(null);
+    const popoverRef = useRef<HTMLDivElement>(null);
+    const [popoverStyle, setPopoverStyle] = useState<React.CSSProperties>({});
+
+    const padding = 8;
+
+    // 1. Scroll target into view & update rect coordinates
+    useEffect(() => {
+        if (!activeStep) {
+            setTargetRect(null);
+            return;
+        }
+
+        const updateRect = () => {
+            const element = document.querySelector(activeStep.selector);
+            if (element) {
+                setTargetRect(element.getBoundingClientRect());
+            } else {
+                setTargetRect(null);
+            }
+        };
+
+        // Scroll smoothly to target element
+        const element = document.querySelector(activeStep.selector);
+        if (element) {
+            element.scrollIntoView({ behavior: "smooth", block: "center" });
+        }
+
+        // Wait a small delay for scroll animation to settle before measuring
+        const timer = setTimeout(updateRect, 100);
+
+        window.addEventListener("resize", updateRect);
+        window.addEventListener("scroll", updateRect, { capture: true });
+
+        return () => {
+            clearTimeout(timer);
+            window.removeEventListener("resize", updateRect);
+            window.removeEventListener("scroll", updateRect, { capture: true });
+        };
+    }, [activeStep, currentStepIndex]);
+
+    // 2. Position the tooltip card dynamically with collision detection
+    useEffect(() => {
+        if (!activeStep) return;
+
+        const popoverWidth = 320;
+        const popoverHeight = 160;
+        const spacing = 16;
+        const margin = 12;
+
+        let top = 0;
+        let left = 0;
+
+        const placement = activeStep.placement || "bottom";
+
+        if (!targetRect) {
+            // Center fallback if target not found
+            setPopoverStyle({
+                top: "50%",
+                left: "50%",
+                transform: "translate(-50%, -50%)",
+                position: "fixed",
+                width: `${popoverWidth}px`,
+            });
+            return;
+        }
+
+        switch (placement) {
+            case "top":
+                top = targetRect.top - popoverHeight - spacing;
+                left = targetRect.left + (targetRect.width - popoverWidth) / 2;
+                break;
+            case "bottom":
+                top = targetRect.bottom + spacing;
+                left = targetRect.left + (targetRect.width - popoverWidth) / 2;
+                break;
+            case "left":
+                top = targetRect.top + (targetRect.height - popoverHeight) / 2;
+                left = targetRect.left - popoverWidth - spacing;
+                break;
+            case "right":
+                top = targetRect.top + (targetRect.height - popoverHeight) / 2;
+                left = targetRect.left + targetRect.width + spacing;
+                break;
+            case "center":
+            default:
+                setPopoverStyle({
+                    top: "50%",
+                    left: "50%",
+                    transform: "translate(-50%, -50%)",
+                    position: "fixed",
+                    width: `${popoverWidth}px`,
+                });
+                return;
+        }
+
+        // Viewport boundaries
+        const viewportWidth = window.innerWidth;
+        const viewportHeight = window.innerHeight;
+
+        // Constraint checking
+        left = Math.max(
+            margin,
+            Math.min(left, viewportWidth - popoverWidth - margin),
+        );
+        top = Math.max(
+            margin,
+            Math.min(top, viewportHeight - popoverHeight - margin),
+        );
+
+        setPopoverStyle({
+            top: `${top}px`,
+            left: `${left}px`,
+            position: "absolute",
+            width: `${popoverWidth}px`,
+        });
+    }, [targetRect, activeStep, currentStepIndex]);
+
+    if (!activeTourId || !activeStep) return null;
+
+    const isLastStep = currentStepIndex === steps.length - 1;
+
+    // Render Portal to place elements at root of body
+    return ReactDOM.createPortal(
+        <div className="fixed inset-0 z-50 overflow-hidden select-none pointer-events-none">
+            {/* Backdrop SVG mask */}
+            <svg className="absolute inset-0 w-full h-full pointer-events-auto">
+                <defs>
+                    <mask id="tour-cutout-mask">
+                        {/* White block covers whole screen (blocks backdrop transparent layer) */}
+                        <rect
+                            x="0"
+                            y="0"
+                            width="100%"
+                            height="100%"
+                            fill="white"
+                        />
+                        {/* Black rect is cutout focus area */}
+                        {targetRect && (
+                            <motion.rect
+                                animate={{
+                                    x: targetRect.left - padding,
+                                    y: targetRect.top - padding,
+                                    width: targetRect.width + padding * 2,
+                                    height: targetRect.height + padding * 2,
+                                }}
+                                transition={{
+                                    type: "spring",
+                                    stiffness: 180,
+                                    damping: 24,
+                                }}
+                                rx={8}
+                                fill="black"
+                            />
+                        )}
+                    </mask>
+                </defs>
+                <rect
+                    x="0"
+                    y="0"
+                    width="100%"
+                    height="100%"
+                    fill="rgba(10, 10, 11, 0.75)"
+                    mask="url(#tour-cutout-mask)"
+                />
+            </svg>
+
+            {/* Helper Card */}
+            <AnimatePresence mode="wait">
+                <motion.div
+                    key={`${activeTourId}-${currentStepIndex}`}
+                    ref={popoverRef}
+                    initial={{ opacity: 0, scale: 0.96, y: 10 }}
+                    animate={{ opacity: 1, scale: 1, y: 0 }}
+                    exit={{ opacity: 0, scale: 0.96, y: -10 }}
+                    transition={{ type: "spring", stiffness: 200, damping: 25 }}
+                    style={popoverStyle}
+                    className="absolute pointer-events-auto bg-dashboard-card border border-dashboard-border rounded-xl p-5 shadow-[0_8px_32px_rgba(0,0,0,0.5)] z-55 flex flex-col gap-4 text-dashboard-foreground"
+                >
+                    {/* Header */}
+                    <div className="flex items-start justify-between gap-4">
+                        <h4 className="text-sm font-bold text-dashboard-foreground leading-tight">
+                            {t(activeStep.titleKey)}
+                        </h4>
+                        <button
+                            onClick={skipTour}
+                            className="p-1 rounded-lg text-dashboard-muted-foreground hover:text-dashboard-foreground hover:bg-dashboard-secondary transition-colors outline-none cursor-pointer border-0 bg-transparent"
+                            aria-label={t("shared:tour.buttons.skip")}
+                        >
+                            <X className="w-3.5 h-3.5" />
+                        </button>
+                    </div>
+
+                    {/* Content */}
+                    <p className="text-xs text-dashboard-muted-foreground font-medium leading-relaxed">
+                        {t(activeStep.contentKey)}
+                    </p>
+
+                    {/* Footer Nav */}
+                    <div className="flex items-center justify-between mt-2 pt-3 border-t border-dashboard-border/60">
+                        {/* Step Count */}
+                        <span className="text-[11px] font-semibold text-dashboard-muted-foreground">
+                            {t("shared:tour.stepCount", {
+                                current: currentStepIndex + 1,
+                                total: steps.length,
+                                defaultValue: `${currentStepIndex + 1} / ${steps.length}`,
+                            })}
+                        </span>
+
+                        {/* Actions */}
+                        <div className="flex items-center gap-2">
+                            {currentStepIndex > 0 && (
+                                <Button
+                                    variant="ghost"
+                                    onClick={prevStep}
+                                    className="h-8 px-2.5 rounded-lg text-[11px] font-bold text-dashboard-muted-foreground hover:text-dashboard-foreground hover:bg-dashboard-secondary"
+                                >
+                                    {isRTL ? (
+                                        <ChevronRight className="w-3.5 h-3.5 ml-1 inline" />
+                                    ) : (
+                                        <ChevronLeft className="w-3.5 h-3.5 mr-1 inline" />
+                                    )}
+                                    {t("shared:tour.buttons.back")}
+                                </Button>
+                            )}
+
+                            <Button
+                                variant={isLastStep ? "default" : "outline"}
+                                onClick={nextStep}
+                                className={`h-8 px-4 rounded-full text-[11px] font-bold transition-all ${
+                                    isLastStep
+                                        ? "bg-dashboard-primary text-dashboard-primary-foreground hover:bg-dashboard-primary/95"
+                                        : "border-dashboard-border hover:bg-dashboard-secondary"
+                                }`}
+                            >
+                                {isLastStep ? (
+                                    t("shared:tour.buttons.finish")
+                                ) : (
+                                    <>
+                                        {t("shared:tour.buttons.next")}
+                                        {isRTL ? (
+                                            <ChevronLeft className="w-3.5 h-3.5 mr-1 inline" />
+                                        ) : (
+                                            <ChevronRight className="w-3.5 h-3.5 ml-1 inline" />
+                                        )}
+                                    </>
+                                )}
+                            </Button>
+                        </div>
+                    </div>
+                </motion.div>
+            </AnimatePresence>
+        </div>,
+        document.body,
+    );
+};
+
+export default TourOverlay;

package/src/tours.ts

@@ -0,0 +1,2 @@
+export * from "./tours/TourContext";
+export * from "./tours/TourOverlay";

package/src/types.ts

@@ -0,0 +1,138 @@
+/**
+ * Design System - Shared Types
+ *
+ * Common types used across design system components.
+ */
+
+import type { ReactNode } from "react";
+
+// ============================================================================
+// Size Types
+// ============================================================================
+
+/**
+ * Standard size options
+ */
+export type Size = "sm" | "md" | "lg" | "xl";
+
+/**
+ * Compact size options
+ */
+export type CompactSize = "sm" | "md" | "lg";
+
+// ============================================================================
+// Variant Types
+// ============================================================================
+
+/**
+ * Color variants
+ */
+export type ColorVariant =
+    | "primary"
+    | "secondary"
+    | "success"
+    | "warning"
+    | "error"
+    | "info";
+
+/**
+ * State variants
+ */
+export type StateVariant =
+    | "default"
+    | "loading"
+    | "error"
+    | "empty"
+    | "success";
+
+// ============================================================================
+// Layout Types
+// ============================================================================
+
+/**
+ * Breadcrumb item
+ */
+export interface BreadcrumbItem {
+    label: string;
+    href?: string;
+    icon?: ReactNode;
+}
+
+/**
+ * Action button config
+ */
+export interface ActionButton {
+    label: string;
+    onClick: () => void;
+    variant?: "primary" | "secondary" | "outline" | "ghost";
+    icon?: ReactNode;
+    disabled?: boolean;
+    loading?: boolean;
+}
+
+// ============================================================================
+// Table Types
+// ============================================================================
+
+/**
+ * Pagination info
+ */
+export interface PaginationInfo {
+    currentPage: number;
+    totalPages: number;
+    pageSize: number;
+    totalItems: number;
+}
+
+// ============================================================================
+// State Types
+// ============================================================================
+
+/**
+ * Loading state props
+ */
+export interface LoadingStateProps {
+    message?: string;
+    size?: CompactSize;
+    fullScreen?: boolean;
+    overlay?: boolean;
+}
+
+/**
+ * Error state props
+ */
+export interface ErrorStateProps {
+    title?: string;
+    /** User-facing description. Derived from `error` when omitted. */
+    message?: string;
+    /** Raw error (Error, API error, string). */
+    error?: unknown;
+    onRetry?: () => void;
+    showIcon?: boolean;
+    variant?: "inline" | "card" | "fullPage";
+    /** Brand tint for full-page / card hero (e.g. tenant primary). */
+    primaryColor?: string;
+    accentColor?: string;
+}
+
+/**
+ * Empty state props
+ */
+export interface EmptyStateProps {
+    title?: string;
+    message?: string;
+    icon?: ReactNode;
+    action?: ActionButton;
+}
+
+// ============================================================================
+// Common Props
+// ============================================================================
+
+/**
+ * Base component props
+ */
+export interface BaseComponentProps {
+    className?: string;
+    testId?: string;
+}

package/src/typography/index.ts

@@ -0,0 +1,4 @@
+export * from "./typography.types";
+export * from "./typography.constants";
+export * from "./typography.adapter";
+export * from "./useTypography";