Relevant source files

The following files were used as context for generating this wiki page: - [packages/ui/README.md](https://github.com/zoonk/zoonk/blob/main/packages/ui/README.md) - [packages/ui/src/components/button.tsx](https://github.com/zoonk/zoonk/blob/main/packages/ui/src/components/button.tsx) - [packages/ui/src/patterns/courses/course-list.tsx](https://github.com/zoonk/zoonk/blob/main/packages/ui/src/patterns/courses/course-list.tsx) - [packages/ui/src/hooks/use-auto-save.ts](https://github.com/zoonk/zoonk/blob/main/packages/ui/src/hooks/use-auto-save.ts) - [packages/ui/src/styles/globals.css](https://github.com/zoonk/zoonk/blob/main/packages/ui/src/styles/globals.css) - [AGENTS.md](https://github.com/zoonk/zoonk/blob/main/AGENTS.md) - [README.md](https://github.com/zoonk/zoonk/blob/main/README.md)

# Package: 'ui' The `ui` package is a shared internal library within the Zoonk monorepo that provides a collection of reusable React components, patterns, hooks, and global styles. Its purpose is to ensure a consistent and polished user interface across all applications in the project, such as `main`, `admin`, and `editor`. The design philosophy emphasizes clarity, minimalism, and intuitiveness, drawing inspiration from brands like Apple, Linear, and Vercel. Sources: [README.md](), [AGENTS.md]() ## Styling The `ui` package establishes the foundational styling for the entire Zoonk project using Tailwind CSS v4. Global styles and CSS variables are defined in `packages/ui/src/styles/globals.css`. Sources: [packages/ui/src/styles/globals.css](), [AGENTS.md]() ### CSS Variables The `globals.css` file defines a set of CSS variables under the `:root` selector, which are used throughout the application for consistent theming. These variables cover aspects like background colors, foreground colors, borders, and radii. | Variable | Description | | :--- | :--- | | `--background` | Main background color of the application. | | `--foreground` | Main foreground/text color. | | `--card` | Background color for card components. | | `--card-foreground` | Text color for card components. | | `--border` | Default border color. | | `--input` | Border color for input elements. | | `--primary` | Primary brand color for active elements. | | `--secondary` | Secondary color for emphasized elements. | | `--destructive` | Color for destructive actions (e.g., delete). | | `--muted` | Muted background color. | | `--accent` | Accent color for highlighted elements. | | `--radius` | Border radius for components like cards and inputs. | Sources: [packages/ui/src/styles/globals.css:4-38]() ### CSS Conventions The project follows specific CSS conventions to maintain consistency: - Use Tailwind CSS v4. - Use variables defined in `globals.css`. - Prefer `size-*` over separate `w-*` and `h-*` classes. - Use `gap-*` for spacing instead of `space-y-*` or `space-x-*`. Sources: [AGENTS.md:112-116]() ## Core Components The `ui` package contains core, reusable components. The project follows a compound component pattern where each component ideally wraps a single HTML element and uses `children` for content rather than specific props like `title` or `description`. Sources: [AGENTS.md:92-101]() ### Button The `Button` component is a fundamental interactive element based on `shadcn/ui`. It is built using `class-variance-authority` (CVA) to handle different stylistic variants and sizes. Sources: [packages/ui/src/components/button.tsx]() #### Variants and Props The `buttonVariants` helper defines the styles for the button based on its props. The component accepts standard button attributes along with custom `variant` and `size` props. ```mermaid classDiagram class ButtonProps { <> +variant: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" +size: "default" | "sm" | "lg" | "icon" +asChild: boolean } class Button { <> props: ButtonProps } ``` This diagram shows the custom props available for the `Button` component. Sources: [packages/ui/src/components/button.tsx:7-39]() The project guidelines recommend using the `outline` variant for most buttons and links, reserving the `default` variant for active/selected states or submit buttons. Sources: [AGENTS.md:52-54]() #### Styling Links as Buttons The `buttonVariants` can be exported and used to style `` components from Next.js to look like buttons, ensuring visual consistency for navigation actions. ```tsx import { buttonVariants } from "@zoonk/ui/components/button"; Click here; ``` Sources: [AGENTS.md:128-134]() ## Patterns Patterns are higher-level components that compose core UI elements to solve recurring design problems. The `CourseList` is an example of such a pattern. Sources: [packages/ui/src/patterns/courses/course-list.tsx]() ### CourseList The `CourseList` component is a client-side component (`"use client"`) designed to display a list of courses. It is a compound component composed of several sub-components like `CourseList.Root`, `CourseList.Title`, and `CourseList.Items`. The component structure is as follows: ```mermaid graph TD A[CourseList.Root] --> B[CourseList.Title] A --> C[CourseList.Items] C --> D["CourseList.Item (loop)"] D --> E["Link (next/link)"] E --> F["Image (next/image)"] E --> G["div"] G --> H["p (Title)"] G --> I["p (Description)"] ``` This diagram illustrates the nested structure of the `CourseList` pattern component. Sources: [packages/ui/src/patterns/courses/course-list.tsx:10-74]() ## Hooks The package includes custom React hooks to encapsulate common UI logic. ### useAutoSave The `useAutoSave` hook provides functionality to automatically save data after a user stops typing for a specified delay. It manages the saving state and provides feedback to the UI. Sources: [packages/ui/src/hooks/use-auto-save.ts]() #### Functionality 1. **Debouncing**: It uses a `setTimeout` to delay the execution of the `onSave` function. If the user provides new data before the delay is over, the timer is reset. 2. **State Management**: It tracks the current saving status, which can be one of `idle`, `saving`, `success`, or `error`. 3. **Callbacks**: It accepts an `onSave` function to perform the actual data persistence and an optional `onSuccess` callback. #### State Machine The hook operates as a state machine, transitioning between states based on user input and the save operation's outcome. ```mermaid stateDiagram-v2 [*] --> idle idle --> saving: onSave triggered saving --> success: onSave resolves saving --> error: onSave rejects success --> idle: after 2s delay error --> idle: after 2s delay ``` This state diagram shows the possible states of the `useAutoSave` hook and the transitions between them. Sources: [packages/ui/src/hooks/use-auto-save.ts:6-12, 23-45]() #### Sequence Diagram The following diagram shows the sequence of events when a user interacts with a component using `useAutoSave`. ```mermaid sequenceDiagram participant User participant Component participant useAutoSave participant API User->>Component: Types in input Component->>useAutoSave: Receives new data useAutoSave->>useAutoSave: Sets up debounce timer (1s) Note over useAutoSave: Timer resets on new input loop Debounce Timeout useAutoSave-->>useAutoSave: 1s passes end useAutoSave->>useAutoSave: Sets state to 'saving' useAutoSave->>API: Calls onSave(data) API-->>useAutoSave: Returns success useAutoSave->>useAutoSave: Sets state to 'success' useAutoSave->>Component: Calls onSuccess() callback Note over useAutoSave: State resets to 'idle' after 2s ``` This sequence diagram illustrates the debouncing and state transition flow of the `useAutoSave` hook. Sources: [packages/ui/src/hooks/use-auto-save.ts:14-46]() ## Summary The `ui` package is the cornerstone of the Zoonk frontend, providing a consistent, minimal, and high-quality set of shared components, patterns, hooks, and styles. It leverages `shadcn/ui` and Tailwind CSS, and follows clear conventions like the compound component pattern to ensure modularity and maintainability across the project's applications.