# Shared Layer

## Table of Contents

- [Purpose](#purpose)
- [Recommended Structure](#recommended-structure)
  - [UI Components](#ui-components)
    - [Purpose](#ui-components-purpose)
    - [Core Principles](#ui-components-core-principles)
      1. [Simple Components](#ui-components-core-principles-1)
      2. [Composable Design](#ui-components-core-principles-2)
      3. [Easily Customizable](#ui-components-core-principles-3)
      4. [No Business Logic](#ui-components-core-principles-4)
    - [Styling Strategy](#ui-components-styling-strategy)
      - [Styling Philosophy](#ui-components-styling-strategy-philosophy)
      - [Technology Stack](#ui-components-styling-strategy-tech-stack)
  - [Hooks](#hooks)
  - [Utilities](#utilities)
  - [Libraries](#libraries)
  - [Assets](#assets)
  - [Styles](#styles)

## Purpose

The `shared` layer contains **global reusable building blocks used across the entire application**.
The goal is to keep these utilities **framework-level and reusable across the entire application**.

```plaintext
shared/
├── ui/                       # dumb or basic UI components
│   ├── Button.tsx
│   ├── Modal.tsx
│   └── Card.tsx
│
├── widgets/                  # reusable composed UI blocks
│   ├── DataGrid/
│   └── screens/
│
├── forms/                    # reusable form composition helpers
│   └── composed/
│
├── editors/                  # reusable editor integrations
│   ├── tinymce/
│   └── image_input/
│
├── hooks/                    # reusable hooks
│   ├── useDebounce.ts
│   ├── useToggle.ts
│   └── useLocalStorage.ts
│
├── lib/                      # pure helpers & utilities
│   └── formatDate.ts
│
├── assets/                   # images, icons, fonts
│   ├── icons/
│   └── fonts/
│
└── styles/                   # global CSS, variables, Tailwind overrides
    ├── globals.css
    └── variables.css
```

## Recommended Structure

```plaintext
shared/
|
| --- ui/                # primitive UI components
|
| --- widgets/           # reusable composed UI blocks
|
| --- forms/             # reusable form composition
|
| --- editors/           # reusable editor wrappers
|
| --- hooks/             # generic reusable hooks
|
| --- utils/             # pure helper functions
|
| --- lib/               # pure helpers and utility services
|
| --- assets/            # images, icons, fonts
|
| --- styles/            # global styling
|
| --- constants/         # global constants
```

### UI Components

#### Purpose {#ui-components-purpose}

The goal of the UI layer is to provide simple, composable, and customizable components that can be reused across the application.

- components are simple building blocks
- components are composable
- components are fully customizable
- components are not tied to business logic

UI components should behave like Lego blocks that can be combined into larger UI structures.

#### Core Principles {#ui-components-core-principles}

##### 1. Simple Components {#ui-components-core-principles-1}

Examples:

- Button
- Input
- Card
- Modal
- Dropdown

##### 2. Composable Design {#ui-components-core-principles-2}

Components must support composition.
Composition allows developers to build complex UI without modifying base components.

Example:

```tsx
<Card>
  <CardHeader />
  <CardContent />
  <CardFooter />
</Card>
```

```tsx
<Button>
  <Icon />
  Save
</Button>
```

##### 3. Easily Customizable {#ui-components-core-principles-3}

UI components should allow customization through:

- className
- variants
- props
- composition

```tsx
<Button variant="outline" size="lg">
  Save
</Button>
```

##### 4. No Business Logic {#ui-components-core-principles-4}

UI components must remain presentation-only. May include local state.

They should NOT:

- call API
- use React Query
- contain form submission logic
- contain domain-specific logic

#### Styling Strategy {#ui-components-styling-strategy}

##### Styling Philosophy {#ui-components-styling-strategy-philosophy}

Styling follows these principles:

- Utility-first styling
- Design tokens for consistency
- Component-level styling
- Variants instead of style duplication
- Minimal custom CSS

##### Technology Stack {#ui-components-styling-strategy-tech-stack}

- **TailwindCSS** - primary styling system
- **class-variance-authority (CVA)** - component variants
- **CSS variables** - design tokens
- **Radix primitives** - accessible UI building blocks

Custom CSS should be minimal and centralized.

### Hooks

The `shared/hooks/` folder contains generic reusable hooks.
These hooks must not depend on entities or business logic.

```plaintext
shared/hooks/
| --- useDebounce.ts
| --- useToggle.ts
| --- usePrevious.ts
| --- useLocalStorage.ts
```

### Utilities

The `shared/utils/` folder contains pure helper functions.
These functions should be stateless and reusable

```plaintext
shared/utils/
| --- formatDate.ts
| --- formatCurrency.ts
| --- generateId.ts
| --- sleep.ts
```

### Libraries

The `shared/lib/` folder contains pure helpers and utility services.

Examples include:

- date formatting helpers
- name formatting helpers
- URL/file path helpers
- phone-number formatting helpers

```plaintext
shared/lib/
| --- time/
| --- phone_number/
| --- resolveFileURL.ts
```

### Assets

The `shared/assets/` folder stores static resources used across the application.

```plaintext
shared/assets/
| --- icons/
| --- fonts/
```

### Styles

The `shared/styles/` folder contains global styling resources.

Typical usage:

- CSS variables
- Tailwind configuration extensions
- global resets

```plaintext
shared/styles/
| --- globals.css
| --- variables.css
| --- tailwind.css
```