@gostack-framework/ui 0.0.0-stage → 0.1.0

package/src/typography/typography.types.ts

@@ -0,0 +1,156 @@
+/**
+ * Typography System Types & Configurations
+ * Centralized type definitions for the design system's typography engine.
+ */
+
+export type SupportedLatinFont =
+    | "inter"
+    | "poppins"
+    | "outfit"
+    | "space-grotesk"
+    | "plus-jakarta-sans"
+    | "syne"
+    | "baloo";
+
+export type SupportedArabicFont =
+    | "cairo"
+    | "tajawal"
+    | "almarai"
+    | "noto-kufi-arabic"
+    | "amiri";
+
+export type SupportedHeadingFont =
+    | "default"
+    | "space-grotesk"
+    | "outfit"
+    | "syne"
+    | "playfair"
+    | "inter"
+    | "poppins";
+
+export type FontSizeScale = "compact" | "normal" | "comfortable";
+
+export type ThemedTextSize =
+    | "xs"
+    | "sm"
+    | "base"
+    | "lg"
+    | "xl"
+    | "2xl"
+    | "3xl"
+    | "4xl"
+    | "5xl"
+    | "6xl";
+
+export type ThemedTextWeight =
+    | "thin"
+    | "light"
+    | "normal"
+    | "medium"
+    | "semibold"
+    | "bold"
+    | "extrabold"
+    | "black";
+
+export type ThemedTextColor =
+    | "primary"
+    | "secondary"
+    | "accent"
+    | "success"
+    | "warning"
+    | "error"
+    | "info"
+    | "foreground"
+    | "muted"
+    | "background";
+
+export type ThemedTextVariant =
+    | "h1"
+    | "h2"
+    | "h3"
+    | "h4"
+    | "title"
+    | "section"
+    | "subheading"
+    | "subtitle"
+    | "lead"
+    | "body"
+    | "caption"
+    | "label"
+    | "metric"
+    | "code"
+    | "heading"
+    | "sidebar";
+
+export type ThemedTextAlign =
+    | "left"
+    | "center"
+    | "right"
+    | "justify"
+    | "start"
+    | "end";
+
+export type ThemedTextTransform =
+    | "none"
+    | "lowercase"
+    | "capitalize"
+    | "uppercase";
+
+export type AnyFontOption =
+    | SupportedLatinFont
+    | SupportedArabicFont
+    | "akaya-telivigala"
+    | "segoe-arabic"
+    | "expo-arabic";
+
+/**
+ * Variant Item Definition
+ * Encapsulates the font size and font weight (plus line-height/letter-spacing)
+ * for a specific variant under a selected density scale.
+ */
+export interface TypographyVariantItem {
+    variant: ThemedTextVariant;
+    size: string;
+    weight: string;
+    lineHeight?: string;
+    letterSpacing?: string;
+    extraClasses?: string;
+}
+
+/**
+ * Full typography configuration object stored in persistence layer.
+ */
+export interface TypographyConfig {
+    latinFont: SupportedLatinFont;
+    arabicFont: SupportedArabicFont;
+    headingFont: SupportedHeadingFont;
+    fontScale: FontSizeScale;
+    baseFontSize?: number;
+}
+
+export interface FontOptionItem<T extends string = string> {
+    id: T;
+    label: string;
+    nativeLabel?: string;
+    cssClass: string;
+    fontFamily: string;
+    description?: string;
+    sampleText?: string;
+}
+
+export interface FontScaleOptionItem {
+    id: FontSizeScale;
+    label: string;
+    description: string;
+    multiplier: number;
+}
+
+/**
+ * Repository interface for Typography configuration.
+ * Allows effortless swapping from LocalStorage to REST/GraphQL API.
+ */
+export interface TypographyRepository {
+    getConfig(): Promise<TypographyConfig> | TypographyConfig;
+    saveConfig(config: TypographyConfig): Promise<void> | void;
+    resetConfig(): Promise<void> | void;
+}

package/src/typography/useTypography.ts

@@ -0,0 +1,211 @@
+import { useEffect, useState } from "react";
+import { getTypographyRepository } from "./typography.adapter";
+import {
+    ARABIC_FONT_OPTIONS,
+    DEFAULT_TYPOGRAPHY_CONFIG,
+    FONT_FAMILIES_MAP,
+    FONT_SCALE_OPTIONS,
+    getVariantStyle,
+    HEADING_FONT_OPTIONS,
+    LATIN_FONT_OPTIONS,
+} from "./typography.constants";
+import {
+    FontSizeScale,
+    SupportedArabicFont,
+    SupportedHeadingFont,
+    SupportedLatinFont,
+    ThemedTextVariant,
+    TypographyConfig,
+} from "./typography.types";
+
+/**
+ * Module-level in-memory cache to synchronize all hook instances
+ */
+let globalTypographyConfig: TypographyConfig = (() => {
+    const repo = getTypographyRepository();
+    const loaded = repo.getConfig();
+    // Support both synchronous config and Promise return
+    if (loaded && typeof (loaded as Promise<TypographyConfig>).then === "function") {
+        return DEFAULT_TYPOGRAPHY_CONFIG;
+    }
+    return (loaded as TypographyConfig) || DEFAULT_TYPOGRAPHY_CONFIG;
+})();
+
+const listeners = new Set<(cfg: TypographyConfig) => void>();
+
+function notifyListeners(cfg: TypographyConfig) {
+    globalTypographyConfig = cfg;
+    listeners.forEach((listener) => {
+        try {
+            listener(cfg);
+        } catch (e) {
+            console.error("[useTypography] Listener error:", e);
+        }
+    });
+}
+
+/**
+ * Resolve CSS font-family string from font identifier
+ */
+function resolveFontFamilyCss(
+    fontId: string,
+    fontList: { id: string; fontFamily: string }[],
+): string {
+    const match = fontList.find((f) => f.id === fontId);
+    return match?.fontFamily || "inherit";
+}
+
+/**
+ * Apply typography variables to documentElement for global CSS sync
+ */
+export function applyTypographyToDom(config: TypographyConfig) {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+
+    const latinFamily = resolveFontFamilyCss(
+        config.latinFont,
+        LATIN_FONT_OPTIONS,
+    );
+    const arabicFamily = resolveFontFamilyCss(
+        config.arabicFont,
+        ARABIC_FONT_OPTIONS,
+    );
+    const headingFamily =
+        config.headingFont && config.headingFont !== "default"
+            ? resolveFontFamilyCss(config.headingFont, HEADING_FONT_OPTIONS)
+            : latinFamily;
+
+    root.style.setProperty("--font-current-latin", latinFamily);
+    root.style.setProperty("--font-current-arabic", arabicFamily);
+    root.style.setProperty("--font-current-heading", headingFamily);
+    root.setAttribute("data-font-scale", config.fontScale);
+}
+
+// Apply on script load
+if (typeof document !== "undefined") {
+    try {
+        applyTypographyToDom(globalTypographyConfig);
+    } catch {}
+}
+
+/**
+ * Primary React Hook for consuming and modifying Typography configurations.
+ */
+export function useTypography() {
+    const [config, setConfig] = useState<TypographyConfig>(
+        globalTypographyConfig,
+    );
+
+    useEffect(() => {
+        const listener = (newCfg: TypographyConfig) => {
+            setConfig(newCfg);
+        };
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    }, []);
+
+    // Async hydration if repository is remote API
+    useEffect(() => {
+        const repo = getTypographyRepository();
+        const res = repo.getConfig();
+        if (res && typeof (res as Promise<TypographyConfig>).then === "function") {
+            (res as Promise<TypographyConfig>).then((remoteConfig) => {
+                if (remoteConfig) {
+                    notifyListeners(remoteConfig);
+                    applyTypographyToDom(remoteConfig);
+                }
+            });
+        }
+    }, []);
+
+    const updateConfig = (updater: Partial<TypographyConfig>) => {
+        const next: TypographyConfig = {
+            ...globalTypographyConfig,
+            ...updater,
+        };
+        notifyListeners(next);
+        applyTypographyToDom(next);
+
+        const repo = getTypographyRepository();
+        repo.saveConfig(next);
+    };
+
+    const setLatinFont = (font: SupportedLatinFont) => {
+        updateConfig({ latinFont: font });
+    };
+
+    const setArabicFont = (font: SupportedArabicFont) => {
+        updateConfig({ arabicFont: font });
+    };
+
+    const setHeadingFont = (font: SupportedHeadingFont) => {
+        updateConfig({ headingFont: font });
+    };
+
+    const setFontScale = (scale: FontSizeScale) => {
+        updateConfig({ fontScale: scale });
+    };
+
+    const resetTypography = () => {
+        notifyListeners(DEFAULT_TYPOGRAPHY_CONFIG);
+        applyTypographyToDom(DEFAULT_TYPOGRAPHY_CONFIG);
+
+        const repo = getTypographyRepository();
+        repo.resetConfig();
+    };
+
+    /**
+     * Resolves the appropriate Tailwind font family class
+     */
+    const getFontFamilyClass = (
+        font?: string,
+        isRTL = false,
+        isHeading = false,
+    ): string => {
+        // Explicit prop passed to component takes highest precedence
+        if (font && font !== "default" && FONT_FAMILIES_MAP[font]) {
+            return FONT_FAMILIES_MAP[font];
+        }
+
+        // RTL / Arabic context
+        if (isRTL) {
+            return FONT_FAMILIES_MAP[config.arabicFont] || "font-cairo";
+        }
+
+        // Heading variant with specific heading font configured
+        if (isHeading && config.headingFont && config.headingFont !== "default") {
+            return FONT_FAMILIES_MAP[config.headingFont] || "font-sans";
+        }
+
+        // Default Latin font from configuration
+        return FONT_FAMILIES_MAP[config.latinFont] || "font-sans";
+    };
+
+    /**
+     * Resolves the complete variant style (size + weight + leading + tracking)
+     * based on active density scale (compact, normal, comfortable).
+     */
+    const getVariantStyleClass = (variant: ThemedTextVariant = "body"): string => {
+        return getVariantStyle(variant, config.fontScale || "normal");
+    };
+
+    return {
+        config,
+        updateConfig,
+        setLatinFont,
+        setArabicFont,
+        setHeadingFont,
+        setFontScale,
+        resetTypography,
+        getFontFamilyClass,
+        getVariantStyleClass,
+        options: {
+            latinFonts: LATIN_FONT_OPTIONS,
+            arabicFonts: ARABIC_FONT_OPTIONS,
+            headingFonts: HEADING_FONT_OPTIONS,
+            fontScales: FONT_SCALE_OPTIONS,
+        },
+    };
+}

package/src/ui/accordion.tsx

@@ -0,0 +1,66 @@
+import { cn } from "../support/utils";
+import { ChevronDownIcon } from "lucide-react";
+import { Accordion as AccordionPrimitive } from "radix-ui";
+import * as React from "react";
+
+function Accordion({
+    ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Root>) {
+    return <AccordionPrimitive.Root data-slot="accordion" {...props} />;
+}
+
+function AccordionItem({
+    className,
+    ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
+    return (
+        <AccordionPrimitive.Item
+            data-slot="accordion-item"
+            className={cn(
+                "border-b border-dashboard-border last:border-b-0",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+function AccordionTrigger({
+    className,
+    children,
+    ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Trigger>) {
+    return (
+        <AccordionPrimitive.Header className="flex">
+            <AccordionPrimitive.Trigger
+                data-slot="accordion-trigger"
+                className={cn(
+                    "flex flex-1 items-center justify-between gap-3 py-2.5 text-left text-xs font-medium text-dashboard-foreground transition-colors outline-none hover:text-dashboard-primary focus-visible:ring-1 focus-visible:ring-dashboard-primary/40 disabled:pointer-events-none disabled:opacity-50 cursor-pointer [&[data-state=open]>svg]:rotate-180",
+                    className,
+                )}
+                {...props}
+            >
+                {children}
+                <ChevronDownIcon className="pointer-events-none size-3.5 shrink-0 text-dashboard-muted-foreground transition-transform duration-200" />
+            </AccordionPrimitive.Trigger>
+        </AccordionPrimitive.Header>
+    );
+}
+
+function AccordionContent({
+    className,
+    children,
+    ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Content>) {
+    return (
+        <AccordionPrimitive.Content
+            data-slot="accordion-content"
+            className="overflow-hidden text-xs text-dashboard-muted-foreground data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
+            {...props}
+        >
+            <div className={cn("pt-0 pb-3", className)}>{children}</div>
+        </AccordionPrimitive.Content>
+    );
+}
+
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger };

package/src/ui/avatar.tsx

@@ -0,0 +1,106 @@
+import * as React from "react"
+import { cn } from "../support/utils"
+import { Avatar as AvatarPrimitive } from "radix-ui"
+
+function Avatar({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Root> & {
+  size?: "default" | "sm" | "lg"
+}) {
+  return (
+    <AvatarPrimitive.Root
+      data-slot="avatar"
+      data-size={size}
+      className={cn(
+        "group/avatar relative flex size-8 shrink-0 overflow-hidden rounded-full select-none data-[size=lg]:size-10 data-[size=sm]:size-6",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarImage({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Image>) {
+  return (
+    <AvatarPrimitive.Image
+      data-slot="avatar-image"
+      className={cn("aspect-square size-full", className)}
+      {...props}
+    />
+  )
+}
+
+function AvatarFallback({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Fallback>) {
+  return (
+    <AvatarPrimitive.Fallback
+      data-slot="avatar-fallback"
+      className={cn(
+        "flex size-full items-center justify-center rounded-full bg-dashboard-secondary font-medium text-xs text-dashboard-muted-foreground group-data-[size=sm]/avatar:text-[10px]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="avatar-badge"
+      className={cn(
+        "absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-dashboard-primary text-white ring-2 ring-dashboard-background select-none",
+        "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
+        "group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
+        "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="avatar-group"
+      className={cn(
+        "group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-dashboard-background",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroupCount({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="avatar-group-count"
+      className={cn(
+        "relative flex size-8 shrink-0 items-center justify-center rounded-full bg-dashboard-secondary text-xs text-dashboard-muted-foreground ring-2 ring-dashboard-background group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+  AvatarBadge,
+  AvatarGroup,
+  AvatarGroupCount,
+}

package/src/ui/badge.tsx

@@ -0,0 +1,58 @@
+import { cn } from "../support/utils";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Slot } from "radix-ui";
+import * as React from "react";
+
+const badgeVariants = cva(
+    "inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-[5px] border px-2 py-0.5 text-[10.5px] font-semibold whitespace-nowrap transition-colors focus-visible:outline-none [&>svg]:pointer-events-none [&>svg]:size-3",
+    {
+        variants: {
+            variant: {
+                default:
+                    "bg-dashboard-primary/15 text-dashboard-primary border-dashboard-primary/30",
+                secondary:
+                    "bg-dashboard-secondary text-dashboard-muted-foreground border-dashboard-border",
+                destructive:
+                    "bg-dashboard-destructive/15 text-dashboard-destructive border-dashboard-destructive/30",
+                outline:
+                    "border-dashboard-border text-dashboard-muted-foreground bg-dashboard-card/50",
+                ghost: "border-transparent text-dashboard-muted-foreground hover:bg-dashboard-secondary hover:text-dashboard-foreground",
+                success:
+                    "bg-emerald-500/15 text-emerald-600 dark:text-emerald-400 border-emerald-500/30",
+                warning: "bg-amber-500/15 text-amber-600 dark:text-amber-400 border-amber-500/30",
+                info: "bg-sky-500/15 text-sky-600 dark:text-sky-400 border-sky-500/30",
+                link: "text-dashboard-primary underline-offset-4 hover:underline border-transparent",
+            },
+            shape: {
+                default: "rounded-[5px]",
+                pill: "rounded-full",
+            },
+        },
+        defaultVariants: {
+            variant: "default",
+            shape: "default",
+        },
+    },
+);
+
+function Badge({
+    className,
+    variant = "default",
+    shape = "default",
+    asChild = false,
+    ...props
+}: React.ComponentProps<"span"> &
+    VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+    const Comp = asChild ? Slot.Root : "span";
+
+    return (
+        <Comp
+            data-slot="badge"
+            data-variant={variant}
+            className={cn(badgeVariants({ variant, shape }), className)}
+            {...props}
+        />
+    );
+}
+
+export { Badge, badgeVariants };

package/src/ui/button.tsx

@@ -0,0 +1,69 @@
+import { cn } from "../support/utils";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Slot } from "radix-ui";
+import * as React from "react";
+
+const buttonVariants = cva(
+    "inline-flex shrink-0 items-center justify-center gap-1.5 rounded-md text-xs font-medium whitespace-nowrap transition-all outline-none focus-visible:ring-1 focus-visible:ring-dashboard-primary/40 disabled:pointer-events-none disabled:opacity-50 select-none cursor-pointer [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5",
+    {
+        variants: {
+            variant: {
+                default:
+                    "bg-dashboard-primary text-white hover:bg-dashboard-primary/90 shadow-xs active:scale-[0.98]",
+                destructive:
+                    "bg-dashboard-destructive/15 text-dashboard-destructive border border-dashboard-destructive/30 hover:bg-dashboard-destructive/25 focus-visible:ring-dashboard-destructive/30",
+                outline:
+                    "border border-dashboard-border bg-dashboard-card/60 text-dashboard-foreground shadow-xs hover:bg-dashboard-secondary hover:text-dashboard-foreground",
+                secondary:
+                    "bg-dashboard-secondary text-dashboard-foreground hover:bg-dashboard-secondary/80 border border-dashboard-border",
+                ghost: "text-dashboard-muted-foreground hover:bg-dashboard-secondary hover:text-dashboard-foreground",
+                link: "text-dashboard-primary underline-offset-4 hover:underline",
+            },
+            size: {
+                default: "h-8 px-3 py-1 text-xs",
+                xs: "h-6 gap-1 rounded-[5px] px-2 text-[11px] [&_svg:not([class*='size-'])]:size-3",
+                sm: "h-7 gap-1.5 rounded-md px-2.5 text-xs",
+                lg: "h-9 rounded-md px-4 text-xs font-semibold gap-2 [&_svg:not([class*='size-'])]:size-4",
+                icon: "size-8 rounded-md",
+                "icon-xs": "size-6 rounded-[5px] [&_svg:not([class*='size-'])]:size-3",
+                "icon-sm": "size-7 rounded-[5px] [&_svg:not([class*='size-'])]:size-3.5",
+                "icon-lg": "size-9 rounded-md [&_svg:not([class*='size-'])]:size-4",
+            },
+            shape: {
+                default: "",
+                pill: "rounded-full",
+            },
+        },
+        defaultVariants: {
+            variant: "default",
+            size: "default",
+            shape: "default",
+        },
+    },
+);
+
+function Button({
+    className,
+    variant = "default",
+    size = "default",
+    shape = "default",
+    asChild = false,
+    ...props
+}: React.ComponentProps<"button"> &
+    VariantProps<typeof buttonVariants> & {
+        asChild?: boolean;
+    }) {
+    const Comp = asChild ? Slot.Root : "button";
+
+    return (
+        <Comp
+            data-slot="button"
+            data-variant={variant}
+            data-size={size}
+            className={cn(buttonVariants({ variant, size, shape, className }))}
+            {...props}
+        />
+    );
+}
+
+export { Button, buttonVariants };