proje-react-panel 1.6.0-test-1 → 1.7.0

package/DASHBOARD_GUIDE.md

@@ -0,0 +1,531 @@
+# Dashboard Components Guide
+
+This guide explains how to use the Dashboard components from the `proje-react-panel` library to create flexible and responsive dashboard layouts.
+
+## Overview
+
+The Dashboard components provide a simple and flexible way to create grid-based dashboard layouts with:
+
+- Configurable grid columns
+- Responsive item containers
+- Simple CSS styling
+- Flexible component composition
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Components](#components)
+3. [Basic Usage](#basic-usage)
+4. [Advanced Usage](#advanced-usage)
+5. [Styling](#styling)
+6. [Examples](#examples)
+
+## Quick Start
+
+### Installation
+
+The Dashboard components are part of the `proje-react-panel` library:
+
+```bash
+npm install proje-react-panel
+# or
+yarn add proje-react-panel
+```
+
+### Basic Example
+
+```tsx
+import { DashboardGrid, DashboardItem, Counter } from 'proje-react-panel';
+
+export function MyDashboard() {
+  return (
+    <DashboardGrid columns={3}>
+      <DashboardItem>
+        <Counter targetNumber={100} duration={2000} image={''} text={'Products'} />
+      </DashboardItem>
+      <DashboardItem>
+        <Counter targetNumber={50} duration={2000} image={''} text={'Orders'} />
+      </DashboardItem>
+      <DashboardItem>
+        <Counter targetNumber={25} duration={2000} image={''} text={'Users'} />
+      </DashboardItem>
+    </DashboardGrid>
+  );
+}
+```
+
+## Components
+
+### Dashboard
+
+A convenience wrapper component that uses `DashboardGrid` internally.
+
+**Props:**
+
+- `children` (React.ReactNode): Child components to render
+- `columns?` (number): Number of columns in the grid (default: 3)
+
+**Example:**
+
+```tsx
+import { Dashboard } from 'proje-react-panel';
+
+<Dashboard columns={3}>
+  <DashboardItem>Content 1</DashboardItem>
+  <DashboardItem>Content 2</DashboardItem>
+</Dashboard>;
+```
+
+### DashboardGrid
+
+The main grid container component that creates a CSS Grid layout.
+
+**Props:**
+
+- `children` (React.ReactNode): Child components to render
+- `columns?` (number): Number of columns in the grid (default: 3)
+
+**Example:**
+
+```tsx
+import { DashboardGrid } from 'proje-react-panel';
+
+<DashboardGrid columns={3}>{/* Your dashboard items */}</DashboardGrid>;
+```
+
+### DashboardItem
+
+A wrapper component for individual dashboard items. Ensures items take full width within their grid cell.
+
+**Props:**
+
+- `children` (React.ReactNode): Content to render inside the item
+
+**Example:**
+
+```tsx
+import { DashboardItem } from 'proje-react-panel';
+
+<DashboardItem>
+  <YourComponent />
+</DashboardItem>;
+```
+
+## Basic Usage
+
+### Simple Grid Layout
+
+Create a basic 3-column grid:
+
+```tsx
+import { DashboardGrid, DashboardItem } from 'proje-react-panel';
+
+export function SimpleDashboard() {
+  return (
+    <DashboardGrid columns={3}>
+      <DashboardItem>
+        <div>Item 1</div>
+      </DashboardItem>
+      <DashboardItem>
+        <div>Item 2</div>
+      </DashboardItem>
+      <DashboardItem>
+        <div>Item 3</div>
+      </DashboardItem>
+    </DashboardGrid>
+  );
+}
+```
+
+### Using Dashboard Wrapper
+
+The `Dashboard` component is a convenience wrapper:
+
+```tsx
+import { Dashboard, DashboardItem } from 'proje-react-panel';
+
+export function WrappedDashboard() {
+  return (
+    <Dashboard columns={3}>
+      <DashboardItem>Content 1</DashboardItem>
+      <DashboardItem>Content 2</DashboardItem>
+      <DashboardItem>Content 3</DashboardItem>
+    </Dashboard>
+  );
+}
+```
+
+### Different Column Counts
+
+Adjust the number of columns based on your needs:
+
+```tsx
+// 2 columns
+<DashboardGrid columns={2}>
+  {/* items */}
+</DashboardGrid>
+
+// 4 columns
+<DashboardGrid columns={4}>
+  {/* items */}
+</DashboardGrid>
+
+// 6 columns
+<DashboardGrid columns={6}>
+  {/* items */}
+</DashboardGrid>
+```
+
+## Advanced Usage
+
+### Dynamic Columns
+
+Set columns dynamically based on screen size or state:
+
+```tsx
+import { useState } from 'react';
+import { DashboardGrid, DashboardItem } from 'proje-react-panel';
+
+export function ResponsiveDashboard() {
+  const [columns, setColumns] = useState(3);
+
+  return (
+    <>
+      <select value={columns} onChange={e => setColumns(Number(e.target.value))}>
+        <option value={1}>1 Column</option>
+        <option value={2}>2 Columns</option>
+        <option value={3}>3 Columns</option>
+        <option value={4}>4 Columns</option>
+      </select>
+      <DashboardGrid columns={columns}>
+        <DashboardItem>Item 1</DashboardItem>
+        <DashboardItem>Item 2</DashboardItem>
+        <DashboardItem>Item 3</DashboardItem>
+        <DashboardItem>Item 4</DashboardItem>
+      </DashboardGrid>
+    </>
+  );
+}
+```
+
+### Using with Counter Component
+
+Combine Dashboard components with the Counter component:
+
+```tsx
+import { DashboardGrid, DashboardItem, Counter } from 'proje-react-panel';
+
+export function StatsDashboard() {
+  return (
+    <DashboardGrid columns={3}>
+      <DashboardItem>
+        <Counter targetNumber={100} duration={2000} image={<Icon />} text={'Products'} />
+      </DashboardItem>
+      <DashboardItem>
+        <Counter targetNumber={50} duration={2000} image={<Icon />} text={'Downloads'} />
+      </DashboardItem>
+      <DashboardItem>
+        <Counter targetNumber={25} duration={2000} image={<Icon />} text={'Services'} />
+      </DashboardItem>
+    </DashboardGrid>
+  );
+}
+```
+
+### Custom Content
+
+Wrap any content in DashboardItem:
+
+```tsx
+import { DashboardGrid, DashboardItem } from 'proje-react-panel';
+
+export function CustomDashboard() {
+  return (
+    <DashboardGrid columns={2}>
+      <DashboardItem>
+        <div className="card">
+          <h2>Title</h2>
+          <p>Content goes here</p>
+        </div>
+      </DashboardItem>
+      <DashboardItem>
+        <div className="chart">{/* Chart component */}</div>
+      </DashboardItem>
+      <DashboardItem>
+        <div className="table">{/* Table component */}</div>
+      </DashboardItem>
+    </DashboardGrid>
+  );
+}
+```
+
+### Conditional Rendering
+
+Render items conditionally:
+
+```tsx
+import { DashboardGrid, DashboardItem } from 'proje-react-panel';
+
+export function ConditionalDashboard({ showStats, showCharts }) {
+  return (
+    <DashboardGrid columns={3}>
+      {showStats && (
+        <DashboardItem>
+          <StatsComponent />
+        </DashboardItem>
+      )}
+      {showCharts && (
+        <DashboardItem>
+          <ChartComponent />
+        </DashboardItem>
+      )}
+      <DashboardItem>
+        <AlwaysVisibleComponent />
+      </DashboardItem>
+    </DashboardGrid>
+  );
+}
+```
+
+## Styling
+
+### Default Styles
+
+The dashboard components come with minimal default styles:
+
+```scss
+.dashboard-grid,
+.dashboard {
+  display: grid;
+  gap: 1rem;
+}
+
+.dashboard-item {
+  width: 100%;
+}
+```
+
+### Custom Styling
+
+You can override styles by targeting the CSS classes:
+
+```scss
+.dashboard-grid {
+  gap: 2rem; // Custom gap
+  padding: 1rem;
+}
+
+.dashboard-item {
+  width: 100%;
+  padding: 1rem;
+  background-color: var(--bg-primary);
+  border-radius: 8px;
+}
+```
+
+### Responsive Styles
+
+Use media queries for responsive layouts:
+
+```scss
+.dashboard-grid {
+  display: grid;
+  gap: 1rem;
+
+  // Responsive columns
+  @media (max-width: 768px) {
+    grid-template-columns: 1fr !important;
+  }
+
+  @media (min-width: 769px) and (max-width: 1024px) {
+    grid-template-columns: repeat(2, 1fr) !important;
+  }
+}
+```
+
+### CSS Variables
+
+Use CSS variables for theming:
+
+```scss
+:root {
+  --dashboard-gap: 1rem;
+  --dashboard-item-padding: 1rem;
+  --dashboard-item-radius: 8px;
+}
+
+.dashboard-grid {
+  gap: var(--dashboard-gap);
+}
+
+.dashboard-item {
+  padding: var(--dashboard-item-padding);
+  border-radius: var(--dashboard-item-radius);
+}
+```
+
+## Examples
+
+### Complete Dashboard Example
+
+```tsx
+import React from 'react';
+import { DashboardGrid, DashboardItem, Counter } from 'proje-react-panel';
+
+export function CompleteDashboard() {
+  return (
+    <DashboardGrid columns={3}>
+      <DashboardItem>
+        <Counter targetNumber={100} duration={2000} image={<ProductsIcon />} text={'Products'} />
+      </DashboardItem>
+      <DashboardItem>
+        <Counter targetNumber={50} duration={2000} image={<DownloadsIcon />} text={'Downloads'} />
+      </DashboardItem>
+      <DashboardItem>
+        <Counter targetNumber={25} duration={2000} image={<ServicesIcon />} text={'Services'} />
+      </DashboardItem>
+      <DashboardItem>
+        <Counter targetNumber={10} duration={2000} image={<AdminsIcon />} text={'Admins'} />
+      </DashboardItem>
+    </DashboardGrid>
+  );
+}
+```
+
+### Mixed Content Dashboard
+
+```tsx
+import { DashboardGrid, DashboardItem, Counter } from 'proje-react-panel';
+
+export function MixedDashboard() {
+  return (
+    <DashboardGrid columns={2}>
+      <DashboardItem>
+        <Counter targetNumber={100} duration={2000} image={''} text={'Total Users'} />
+      </DashboardItem>
+      <DashboardItem>
+        <div className="recent-activity">
+          <h3>Recent Activity</h3>
+          {/* Activity list */}
+        </div>
+      </DashboardItem>
+      <DashboardItem>
+        <div className="chart">
+          <h3>Sales Chart</h3>
+          {/* Chart component */}
+        </div>
+      </DashboardItem>
+      <DashboardItem>
+        <div className="table">
+          <h3>Latest Orders</h3>
+          {/* Table component */}
+        </div>
+      </DashboardItem>
+    </DashboardGrid>
+  );
+}
+```
+
+### Responsive Dashboard
+
+```tsx
+import { useEffect, useState } from 'react';
+import { DashboardGrid, DashboardItem } from 'proje-react-panel';
+
+export function ResponsiveDashboard() {
+  const [columns, setColumns] = useState(3);
+
+  useEffect(() => {
+    const handleResize = () => {
+      if (window.innerWidth < 768) {
+        setColumns(1);
+      } else if (window.innerWidth < 1024) {
+        setColumns(2);
+      } else {
+        setColumns(3);
+      }
+    };
+
+    handleResize();
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize);
+  }, []);
+
+  return (
+    <DashboardGrid columns={columns}>
+      <DashboardItem>Item 1</DashboardItem>
+      <DashboardItem>Item 2</DashboardItem>
+      <DashboardItem>Item 3</DashboardItem>
+      <DashboardItem>Item 4</DashboardItem>
+    </DashboardGrid>
+  );
+}
+```
+
+## API Reference
+
+### Dashboard Props
+
+```typescript
+interface DashboardProps {
+  children: React.ReactNode;
+  columns?: number; // Default: 3
+}
+```
+
+### DashboardGrid Props
+
+```typescript
+interface DashboardGridProps {
+  children: React.ReactNode;
+  columns?: number; // Default: 3
+}
+```
+
+### DashboardItem Props
+
+```typescript
+interface DashboardItemProps {
+  children: React.ReactNode;
+}
+```
+
+## Best Practices
+
+1. **Always wrap content in DashboardItem**: This ensures proper spacing and width within grid cells
+2. **Use appropriate column counts**: Consider your content and screen sizes when choosing columns
+3. **Keep styles simple**: The components are designed to be minimal - add custom styling as needed
+4. **Use Dashboard for convenience**: Use `Dashboard` if you prefer a simpler API, or `DashboardGrid` for more control
+5. **Responsive design**: Consider using responsive breakpoints or dynamic column counts for mobile devices
+
+## Troubleshooting
+
+### Items not displaying correctly
+
+- Ensure you're wrapping content in `DashboardItem`
+- Check that CSS styles are properly imported
+- Verify the `columns` prop is set correctly
+
+### Grid not responsive
+
+- The grid uses CSS Grid with fixed columns
+- Use media queries or dynamic column state for responsive behavior
+- Consider using CSS `grid-template-columns: repeat(auto-fit, minmax(300px, 1fr))` for auto-responsive grids
+
+### Styling issues
+
+- Check that dashboard styles are imported in your main stylesheet
+- Verify CSS specificity isn't being overridden
+- Use browser DevTools to inspect computed styles
+
+## Dependencies
+
+The Dashboard components are part of the `proje-react-panel` library and require:
+
+- React (^16.8.0 or later)
+- TypeScript (optional, but recommended)
+
+## Related Components
+
+- [Counter Component](./README.md#counter-component) - For displaying animated counters
+- [Layout Component](./AUTH_LAYOUT_GUIDE.md) - For page layouts with sidebar

package/README.md

@@ -10,17 +10,21 @@ A powerful and flexible React-based panel library for building administrative in
 - **Layout System**: Consistent layout management
 - **Panel Component**: Core panel functionality
 - **Counter Component**: Utility component for counting operations
+- **Dashboard Components**: Flexible grid-based dashboard layout system
+- **Color System**: Centralized color system with SCSS variables and CSS custom properties
 
 ## Decorators
 
 The library provides several decorators for enhanced functionality:
 
 ### List Decorators
+
 - `@List`: Main list decorator for creating list views
 - `@ImageCell`: Specialized cell for handling images in lists
 - `@Cell`: Base cell decorator for list items
 
 ### Form Decorators
+
 - `@Input`: Form input decorator
 - `@Crud`: CRUD operations decorator
 
@@ -35,7 +39,7 @@ yarn add proje-react-panel
 ## Usage
 
 ```typescript
-import { Panel, ListPage, FormPage, Login, Layout } from 'proje-react-panel';
+import { Panel, ListPage, FormPage, Login, Layout, DashboardGrid, DashboardItem } from 'proje-react-panel';
 
 // Initialize the panel
 const panel = new Panel({
@@ -48,8 +52,21 @@ const panel = new Panel({
   <FormPage />
   <Login />
 </Layout>
+
+// Dashboard example
+<DashboardGrid columns={3}>
+  <DashboardItem>Content 1</DashboardItem>
+  <DashboardItem>Content 2</DashboardItem>
+  <DashboardItem>Content 3</DashboardItem>
+</DashboardGrid>
 ```
 
+## Guides
+
+- **[Dashboard Guide](./DASHBOARD_GUIDE.md)** - Complete guide for using Dashboard components
+- **[Auth Layout Guide](./AUTH_LAYOUT_GUIDE.md)** - Guide for implementing authentication layouts with sidebar
+- **[Color System Guide](./COLOR_SYSTEM_GUIDE.md)** - Complete documentation of the color system, SCSS variables, and CSS custom properties
+
 ## Type Definitions
 
 The library includes TypeScript definitions for better development experience:

package/dist/components/DashboardContainer.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface DashboardContainerProps {
+    children: React.ReactNode;
+    className?: string;
+}
+export declare function DashboardContainer({ children, className }: DashboardContainerProps): React.JSX.Element;
+export {};

package/dist/components/DashboardGrid.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+interface DashboardGridProps {
+    children: React.ReactNode;
+    columns?: number;
+    gap?: string;
+    className?: string;
+}
+export declare function DashboardGrid({ children, columns, gap, className, }: DashboardGridProps): React.JSX.Element;
+export {};

package/dist/components/DashboardItem.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+interface DashboardItemProps {
+    targetNumber: number;
+    duration?: number;
+    image: React.ReactNode;
+    text: string;
+    className?: string;
+}
+export declare function DashboardItem({ targetNumber, duration, image, text, className, }: DashboardItemProps): React.JSX.Element;
+export {};

package/dist/components/ThemeSwitcher.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface ThemeSwitcherProps {
+    variant?: 'button' | 'dropdown';
+    className?: string;
+}
+export declare function ThemeSwitcher({ variant, className }: ThemeSwitcherProps): React.JSX.Element;
+export {};

package/dist/components/dashboard/Dashboard.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface DashboardProps {
+    children: React.ReactNode;
+    columns?: number;
+}
+export declare function Dashboard({ children, columns }: DashboardProps): React.JSX.Element;
+export {};

package/dist/components/dashboard/DashboardGrid.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface DashboardGridProps {
+    children: React.ReactNode;
+    columns?: number;
+}
+export declare function DashboardGrid({ children, columns }: DashboardGridProps): React.JSX.Element;
+export {};

package/dist/components/dashboard/DashboardItem.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+interface DashboardItemProps {
+    children: React.ReactNode;
+}
+export declare function DashboardItem({ children }: DashboardItemProps): React.JSX.Element;
+export {};

package/dist/components/dashboard/index.d.ts

@@ -0,0 +1,3 @@
+export { Dashboard } from './Dashboard';
+export { DashboardGrid } from './DashboardGrid';
+export { DashboardItem } from './DashboardItem';