Initial commit

2026-06-25 15:53:49 +03:00
commit 1bb0b7e68a
1517 changed files with 218469 additions and 0 deletions
@@ -0,0 +1,252 @@
+# 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
+```