proje-react-panel 1.6.0 → 1.8.0

package/guides/USAGE.md

@@ -0,0 +1,85 @@
+# React Panel Library
+
+A powerful and flexible React-based panel library for building administrative interfaces and data management systems.
+
+## Features
+
+- **List Page Component**: Built-in list view with customizable cells and image handling
+- **Form Page Component**: Flexible form creation and management
+- **Login Component**: Authentication handling
+- **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
+
+## Installation
+
+```bash
+npm install proje-react-panel
+# or
+yarn add proje-react-panel
+```
+
+## Usage
+
+```typescript
+import { Panel, ListPage, FormPage, Login, Layout, DashboardGrid, DashboardItem } from 'proje-react-panel';
+
+// Initialize the panel
+const panel = new Panel({
+  // configuration options
+});
+
+// Use components
+<Layout>
+  <ListPage />
+  <FormPage />
+  <Login />
+</Layout>
+
+// Dashboard example
+<DashboardGrid columns={3}>
+  <DashboardItem>Content 1</DashboardItem>
+  <DashboardItem>Content 2</DashboardItem>
+  <DashboardItem>Content 3</DashboardItem>
+</DashboardGrid>
+```
+
+## Guides
+
+- **[Dashboard Guide](./guides/DASHBOARD_GUIDE.md)** - Complete guide for using Dashboard components
+- **[Auth Layout Guide](./guides/AUTH_LAYOUT_GUIDE.md)** - Guide for implementing authentication layouts with sidebar
+- **[Auth Layout Example](./guides/AUTH_LAYOUT_EXAMPLE.md)** - Complete working example of AuthLayout implementation
+- **[Color System Guide](./guides/COLOR_SYSTEM_GUIDE.md)** - Complete documentation of the color system, SCSS variables, and CSS custom properties
+- **[Implementation Guide](./guides/IMPLEMENTATION_GUIDE.md)** - Comprehensive guide for implementing the library in your React applications
+
+## Type Definitions
+
+The library includes TypeScript definitions for better development experience:
+
+- `InitPanelOptions`: Configuration options for panel initialization
+- `ScreenCreatorData`: Data structure for screen creation
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

package/how_to.md

@@ -0,0 +1,184 @@
+# How To — `proje-react-panel`
+
+A decorator-driven admin-panel kit for React. You declare your resources as TypeScript classes (`@List`, `@Form`, `@Details`); the library renders the table / form / detail pages and talks to your REST backend.
+
+For deep walkthroughs see [`guides/IMPLEMENTATION_GUIDE.md`](./guides/IMPLEMENTATION_GUIDE.md). For a runnable demo see [`examples/`](./examples).
+
+---
+
+## 1. What you're getting
+
+- `<ListPage model={...} />`, `<FormPage model={...} />`, `<DetailsPage model={...} />` — page components driven by class metadata.
+- `<Panel>`, `<Layout>`, `<Login>` — app shell, sidebar, and login page.
+- `<Dashboard>`, `<DashboardGrid>`, `<DashboardItem>`, `<Counter>` — dashboard widgets.
+- `initApi`, `setAuthToken`, `getAll`, `getOne`, `create`, `update`, `remove`, `createFormData`, `updateFormData` — backend wiring helpers.
+- Decorators: `@List`, `@Form`, `@Details`, `@Cell`, `@LinkCell`, `@ImageCell`, `@DownloadCell`, `@Input`, `@SelectInput`, `@DetailsItem`.
+
+See the full export surface in [`src/index.ts`](./src/index.ts).
+
+---
+
+## 2. Backend expectations
+
+The library is built against a plain REST backend with these conventions. Any backend that respects them will work — a compatible NestJS reference implementation is available as a sibling project; use it as a starting point if you don't have a backend yet.
+
+| Concern | Shape |
+| --- | --- |
+| Auth header | `Authorization: Bearer <jwt>` on every protected request |
+| Login | `POST /auth/login` → `{ access_token, admin: { id, email } }` |
+| List | `GET /:resource?page=<n>&limit=<n>` → `{ total: number, data: T[] }` |
+| Item | `GET /:resource/:id` → entity JSON (no envelope) |
+| Mutations | `POST /:resource`, `PUT /:resource/:id`, `DELETE /:resource/:id` |
+| File upload | `multipart/form-data`, field name `file` |
+| Errors | `{ statusCode, message, error }` (NestJS default works out of the box) |
+| 401 | The library auto-clears the token and redirects to `/login` |
+
+---
+
+## 3. Client-side data flow
+
+```mermaid
+flowchart LR
+    Model["Model class<br/>(@List/@Form/@Details)"] -->|reflect-metadata| Page["ListPage / FormPage / DetailsPage"]
+    Page -->|getData / onSubmit / getDetailsData| DF["dataFetchers"]
+    DF -->|getAll/getOne/create/update/remove| Crud["CrudApi (axios)"]
+    Crud -->|REST + Bearer| API[("Your backend")]
+    API -->|"{ total, data }" or entity| Crud
+    Crud --> Page
+    Page --> UI["Rendered table / form / details"]
+
+    LS[("localStorage<br/>token")] -.read on boot.- Crud
+    API -.401.-> Logout["setAuthLogout()<br/>→ /login"]
+```
+
+---
+
+## 4. Quick start (5 steps)
+
+### 4.1 Install
+
+```bash
+npm install proje-react-panel \
+  react react-router react-hook-form \
+  zustand axios react-select use-sync-external-store
+```
+
+Peer-dep versions: `react >= 19`, `react-router 7.3.0`, `react-hook-form >= 7.54.2`, `zustand >= 5.0.3`, `axios >= 1.0.0`, `react-select ^5.10.1`, `use-sync-external-store >= 1.4.0` (see [`package.json`](./package.json)).
+
+### 4.2 Initialize at app root
+
+```ts
+import { Panel, initApi, initAuthToken, setAuthToken } from 'proje-react-panel';
+import 'reflect-metadata';
+
+initApi({ baseUrl: import.meta.env.VITE_API_BASE_URL });
+initAuthToken();
+
+export function App() {
+  return (
+    <Panel onInit={(appData) => { if (appData.token) setAuthToken(appData.token); }}>
+      <Router>{/* routes */}</Router>
+    </Panel>
+  );
+}
+```
+
+### 4.3 Wire data fetchers
+
+```ts
+// src/api/dataFetchers.ts
+import { getAll, getOne, create, update, remove } from 'proje-react-panel';
+import { ProductList, CreateProductForm, EditProductForm, ProductDetails } from '../models/Product';
+
+export const dataFetchers = Object.freeze({
+  products: {
+    getAll:  getAll<ProductList>('products'),
+    details: getOne<ProductDetails>('products'),
+    create:  create<CreateProductForm>('products'),
+    update:  update<EditProductForm>('products'),
+    remove:  remove('products', 'id'),
+  },
+});
+```
+
+### 4.4 Declare a model with decorators
+
+```ts
+// src/models/Product.ts
+import { List, Cell, LinkCell, Form, Input, Details, DetailsItem } from 'proje-react-panel';
+import { IsNotEmpty, MinLength } from 'class-validator';
+import { dataFetchers } from '../api/dataFetchers';
+
+@List({ getData: dataFetchers.products.getAll, primaryId: 'id' })
+export class ProductList {
+  @Cell({ title: 'ID', type: 'uuid' }) id!: string;
+  @Cell({ title: 'Name' }) name!: string;
+  @LinkCell({ path: '/products/:id', placeHolder: 'open' }) open!: string;
+}
+
+@Form({ onSubmit: dataFetchers.products.create, redirectSuccessUrl: '/products' })
+export class CreateProductForm {
+  @Input({ label: 'Name' })
+  @IsNotEmpty()
+  @MinLength(2)
+  name!: string;
+}
+
+@Details({ getDetailsData: dataFetchers.products.details, primaryId: 'id' })
+export class ProductDetails {
+  @DetailsItem() id!: string;
+  @DetailsItem() name!: string;
+}
+```
+
+### 4.5 Route the pages
+
+```tsx
+import { ListPage, FormPage, DetailsPage } from 'proje-react-panel';
+import { ProductList, CreateProductForm, ProductDetails } from './models/Product';
+
+<Route path="products">
+  <Route path=""        element={<ListPage    model={ProductList} />} />
+  <Route path="create"  element={<FormPage    model={CreateProductForm} />} />
+  <Route path=":id"     element={<DetailsPage model={ProductDetails} />} />
+</Route>
+```
+
+That's it — you have a fully functional list / create / detail flow against `GET|POST|GET /products`.
+
+---
+
+## 5. File uploads
+
+Swap `create` → `createFormData` (and `update` → `updateFormData`) in your `dataFetchers`, set `type: 'formData'` on the `@Form` decorator, and name the file field `file`. The library then sends `multipart/form-data` with the file under the `file` key — which is what the reference backend's upload endpoint expects.
+
+A complete worked example lives in [`examples/src/models/Asset.ts`](./examples/src/models/Asset.ts) and [`examples/src/api/dataFetchers.ts`](./examples/src/api/dataFetchers.ts).
+
+---
+
+## 6. Login & 401
+
+- `initAuthToken()` reads `localStorage["token"]` on boot and applies it to axios.
+- `setAuthToken(token)` writes the token to `localStorage` and axios defaults — call it from your login form's success handler (or use the built-in `<Login model={DefaultLoginForm} />`).
+- A 401 response anywhere triggers `setAuthLogout()` and a hard redirect to `/login`. See [`src/api/ApiConfig.ts`](./src/api/ApiConfig.ts) for the interceptor.
+
+---
+
+## 7. Where to next
+
+| Topic | File |
+| --- | --- |
+| Step-by-step walkthrough (the deepest doc) | [`guides/IMPLEMENTATION_GUIDE.md`](./guides/IMPLEMENTATION_GUIDE.md) |
+| Sidebar + authenticated layout | [`guides/AUTH_LAYOUT_GUIDE.md`](./guides/AUTH_LAYOUT_GUIDE.md) |
+| Layout example code | [`guides/AUTH_LAYOUT_EXAMPLE.md`](./guides/AUTH_LAYOUT_EXAMPLE.md) |
+| Dashboard widgets | [`guides/DASHBOARD_GUIDE.md`](./guides/DASHBOARD_GUIDE.md) |
+| Colors / theme tokens | [`guides/COLOR_SYSTEM_GUIDE.md`](./guides/COLOR_SYSTEM_GUIDE.md) |
+| Feature overview | [`guides/USAGE.md`](./guides/USAGE.md) |
+| Live runnable example | [`examples/`](./examples) |
+| Product/tech doc | [`PTD.md`](./PTD.md) |
+
+---
+
+## 8. Version & license
+
+`proje-react-panel` v1.7.0 — ISC license. See [`package.json`](./package.json).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proje-react-panel",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "",
   "author": "SEFA DEMİR",
@@ -30,9 +30,12 @@
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@svgr/rollup": "^8.1.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.0.10",
     "@typescript-eslint/eslint-plugin": "^8.26.1",
     "@typescript-eslint/parser": "^8.29.1",
+    "axios": "^1.12.2",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1",
     "eslint": "^9.24.0",
@@ -40,9 +43,11 @@
     "eslint-plugin-react-hooks": "^5.2.0",
     "globals": "^16.0.0",
     "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "prettier": "^3.5.3",
     "prettier-eslint": "^16.3.0",
     "react": "^19.0.0",
+    "react-dom": "19.0.0",
     "react-hook-form": "^7.54.2",
     "react-router": "^7.3.0",
     "react-select": "^5.10.1",
@@ -61,6 +66,7 @@
     "zustand": "^5.0.3"
   },
   "peerDependencies": {
+    "axios": ">=1.0.0",
     "react": ">=19.0.0",
     "react-hook-form": ">=7.54.2",
     "react-router": "7.3.0",

package/src/__tests__/components/form/CustomField.test.tsx

@@ -0,0 +1,92 @@
+/**
+ * @jest-environment jsdom
+ */
+import 'reflect-metadata';
+import React from 'react';
+import { describe, expect, it, beforeEach } from '@jest/globals';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { FormProvider, useForm } from 'react-hook-form';
+import { CustomInput, CustomRenderProps } from '../../../decorators/form/inputs/CustomInput';
+import { Input, getInputFields } from '../../../decorators/form/Input';
+import { FormField } from '../../../components/form/FormField';
+
+// Every call the library makes into the consumer supplied render prop.
+let renderCalls: CustomRenderProps[] = [];
+
+function renderControl(props: CustomRenderProps) {
+  renderCalls.push(props);
+  return (
+    <button type="button" data-testid="custom-control" onClick={() => props.onChange('picked-42')}>
+      {String(props.value ?? '')}
+    </button>
+  );
+}
+
+class AssetForm {
+  @Input({ label: 'Title' })
+  title: string;
+
+  @CustomInput({ label: 'Asset', render: renderControl })
+  asset: unknown;
+}
+
+// The values react-hook-form currently holds, mirrored out of the harness.
+let formValues: Record<string, unknown> = {};
+
+function Harness() {
+  const form = useForm({ defaultValues: { title: '', asset: 'initial' } });
+  formValues = form.watch();
+  const inputs = getInputFields(AssetForm);
+  return (
+    <FormProvider {...form}>
+      {inputs.map(input => (
+        <FormField key={input.name} input={input} register={form.register} />
+      ))}
+    </FormProvider>
+  );
+}
+
+describe('CustomInput', () => {
+  beforeEach(() => {
+    renderCalls = [];
+    formValues = {};
+  });
+
+  it('carries the render function through the metadata', () => {
+    const asset = getInputFields(AssetForm).find(input => input.name === 'asset');
+    expect(asset?.type).toBe('custom');
+    expect(typeof (asset as unknown as { render?: unknown })?.render).toBe('function');
+  });
+
+  it('calls the render prop with the field name and current value', () => {
+    render(<Harness />);
+
+    expect(renderCalls.length).toBeGreaterThan(0);
+    expect(renderCalls[0].fieldName).toBe('asset');
+    expect(renderCalls[0].value).toBe('initial');
+    expect(renderCalls[0].error).toBeUndefined();
+    expect(screen.getByTestId('custom-control').textContent).toBe('initial');
+  });
+
+  it('renders the label like any other field', () => {
+    render(<Harness />);
+
+    expect(screen.getByText('Asset:')).toBeTruthy();
+  });
+
+  it('updates the form value when the render prop calls onChange', () => {
+    render(<Harness />);
+
+    fireEvent.click(screen.getByTestId('custom-control'));
+
+    expect(formValues.asset).toBe('picked-42');
+    expect(screen.getByTestId('custom-control').textContent).toBe('picked-42');
+  });
+
+  it('leaves the other field types untouched', () => {
+    render(<Harness />);
+
+    expect(screen.getByText('Title:')).toBeTruthy();
+    expect(formValues.title).toBe('');
+  });
+});

package/src/api/ApiConfig.ts

@@ -0,0 +1,63 @@
+import axios, { AxiosInstance } from 'axios';
+
+let axiosInstance: AxiosInstance;
+
+export interface ApiConfig {
+  baseUrl: string;
+}
+
+export function initApi(config: ApiConfig): void {
+  axiosInstance = axios.create({
+    baseURL: config.baseUrl,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  });
+
+  axiosInstance.interceptors.response.use(
+    response => response,
+    error => {
+      if (error.response && error.response.status === 401) {
+        setAuthLogout();
+        window.location.href = '/login';
+      }
+      return Promise.reject(error);
+    }
+  );
+}
+
+export function initAuthToken(): void {
+  if (!axiosInstance) {
+    throw new Error('API not initialized. Call initApi first.');
+  }
+  const token = localStorage.getItem('token');
+  if (token) {
+    axiosInstance.defaults.headers.common['Authorization'] = `Bearer ${token}`;
+  }
+}
+
+export function setAuthToken(token: string): void {
+  if (!axiosInstance) {
+    throw new Error('API not initialized. Call initApi first.');
+  }
+  axiosInstance.defaults.headers.common['Authorization'] = `Bearer ${token}`;
+  localStorage.setItem('token', token);
+}
+
+export function setAuthLogout(): void {
+  if (!axiosInstance) {
+    throw new Error('API not initialized. Call initApi first.');
+  }
+  axiosInstance.defaults.headers.common['Authorization'] = null;
+  localStorage.removeItem('token');
+}
+
+export function getAxiosInstance(): AxiosInstance {
+  if (!axiosInstance) {
+    throw new Error('API not initialized. Call initApi first.');
+  }
+  return axiosInstance;
+}
+
+// Export the axios instance for external use
+export { axiosInstance };

package/src/api/AuthApi.ts

@@ -0,0 +1,8 @@
+import { LoginForm, LoginResponse } from '../types/Login';
+import { getAxiosInstance } from './ApiConfig';
+
+export async function login<T>(data: LoginForm | FormData): Promise<LoginResponse<T>> {
+  const axiosInstance = getAxiosInstance();
+  const response = await axiosInstance.post<LoginResponse<T>>('/auth/login', data);
+  return response.data;
+}

package/src/api/CrudApi.ts

@@ -1,65 +1,101 @@
-interface FetchOptions {
-  token: string;
-  baseUrl: string;
-}
+import { GetDataForList, PaginatedResponse, GetDataParams } from '../decorators/list/List';
+import { OnSubmitFN } from '../decorators/form/Form';
+import { GetDetailsDataFN } from '../decorators/details/Details';
+import { getAxiosInstance } from './ApiConfig';
+import { AxiosError } from 'axios';
 
-export const CrudApi = {
-  getList: (options: FetchOptions, api: string) => {
-    return fetch(`${options.baseUrl}/${api}`, {
-      method: 'GET',
-      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${options.token}` },
-    }).then(res => {
-      if (res.ok) {
-        return res.json();
-      }
-      throw res;
+export function getAll<T>(endpoint: string): GetDataForList<T> {
+  return async (params: GetDataParams): Promise<PaginatedResponse<T>> => {
+    const axiosInstance = getAxiosInstance();
+    const { page = 1, limit = 10 } = params;
+    const response = await axiosInstance.get<{
+      data: T[];
+      total: number;
+    }>(`/${endpoint}`, {
+      params: { page, limit, ...(params.filters ?? {}) },
     });
-  },
-  //TODO: fix this
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  create: (options: FetchOptions, api: string, data: any) => {
-    const headers: HeadersInit = { Authorization: `Bearer ${options.token}` };
-    // Don't set Content-Type for FormData
-    if (!(data instanceof FormData)) {
-      headers['Content-Type'] = 'application/json';
-    }
+    return {
+      data: response.data.data,
+      total: response.data.total,
+      page,
+      limit,
+    };
+  };
+}
+
+export function getOne<T>(endpoint: string, key = 'id'): GetDetailsDataFN<T> {
+  return async (params: Record<string, string>): Promise<T> => {
+    const axiosInstance = getAxiosInstance();
+    const response = await axiosInstance.get<T>(`/${endpoint}/${params[key]}`);
+    return response.data;
+  };
+}
 
-    return fetch(`${options?.baseUrl ?? ''}/${api}`, {
-      method: 'POST',
-      headers,
-      body: data instanceof FormData ? data : JSON.stringify(data),
-    }).then(res => res.json());
-  },
-  //TODO: fix this
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  details: (options: FetchOptions, api: string, id: any) => {
-    return fetch(`${options?.baseUrl ?? ''}/${api}/${id}`, {
-      method: 'GET',
-      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${options.token}` },
-    }).then(res => {
-      return res.json();
+export function create<T>(endpoint: string): OnSubmitFN<T> {
+  return async (data: T | FormData): Promise<T> => {
+    const axiosInstance = getAxiosInstance();
+    const response = await axiosInstance.post<T>(`/${endpoint}`, data);
+    return response.data;
+  };
+}
+
+export function createFormData<T>(endpoint: string): OnSubmitFN<T> {
+  return async (data: T | FormData): Promise<T> => {
+    const axiosInstance = getAxiosInstance();
+    const response = await axiosInstance.post<T>(`/${endpoint}`, data, {
+      headers: {
+        'Content-Type': 'multipart/form-data',
+      },
     });
-  },
-  //TODO: fix this
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  edit: (options: FetchOptions, api: string, data: any) => {
-    const headers: HeadersInit = { Authorization: `Bearer ${options.token}` };
-    // Don't set Content-Type for FormData
-    if (!(data instanceof FormData)) {
-      headers['Content-Type'] = 'application/json';
-    }
-    return fetch(`${options?.baseUrl ?? ''}/${api}/${data.id}`, {
-      method: 'PUT',
-      headers,
-      body: data instanceof FormData ? data : JSON.stringify(data),
-    }).then(res => res.json());
-  },
-  delete: (options: FetchOptions, api: string, id: string) => {
-    return fetch(`${options?.baseUrl ?? ''}/${api}/${id}`, {
-      method: 'DELETE',
-      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${options.token}` },
-    }).then(res => {
-      return res.clone().json();
+    return response.data;
+  };
+}
+
+export function update<T>(endpoint: string, key = 'id'): OnSubmitFN<T> {
+  return async (data: T | FormData): Promise<T> => {
+    const axiosInstance = getAxiosInstance();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const id = (data as any)[key];
+    const response = await axiosInstance.put<T>(`/${endpoint}/${id}`, data);
+    return response.data;
+  };
+}
+
+export function updateFormData<T>(endpoint: string, key = 'id'): OnSubmitFN<T> {
+  return async (data: T | FormData): Promise<T> => {
+    const axiosInstance = getAxiosInstance();
+    const id = (data as any)[key];
+    const response = await axiosInstance.put<T>(`/${endpoint}/${id}`, data, {
+      headers: {
+        'Content-Type': 'multipart/form-data',
+      },
     });
-  },
-};
+    return response.data;
+  };
+}
+
+export function updateSimple<T>(endpoint: string): OnSubmitFN<T> {
+  return async (data: T | FormData): Promise<T> => {
+    const axiosInstance = getAxiosInstance();
+    const response = await axiosInstance.put<T>(`/${endpoint}`, data);
+    return response.data;
+  };
+}
+
+export function remove<T>(endpoint: string, key = 'id'): (data: T) => Promise<void> {
+  return async (data: T): Promise<void> => {
+    const axiosInstance = getAxiosInstance();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const id = (data as any)[key];
+    await axiosInstance
+      .delete<T>(`/${endpoint}/${id}`)
+      .then((res: any) => res.data)
+      .catch((err: AxiosError) => {
+        const messageError = err.response?.data as { message: string };
+        if (messageError?.message) {
+          throw new Error(messageError.message);
+        }
+        throw err;
+      });
+  };
+}

package/src/components/dashboard/Dashboard.tsx

@@ -0,0 +1,11 @@
+import React from 'react';
+import { DashboardGrid } from './DashboardGrid';
+
+interface DashboardProps {
+  children: React.ReactNode;
+  columns?: number;
+}
+
+export function Dashboard({ children, columns }: DashboardProps) {
+  return <DashboardGrid columns={columns}>{children}</DashboardGrid>;
+}

package/src/components/dashboard/DashboardGrid.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+
+interface DashboardGridProps {
+  children: React.ReactNode;
+  columns?: number;
+}
+
+export function DashboardGrid({ children, columns = 3 }: DashboardGridProps) {
+  return (
+    <div className="dashboard-grid" style={{ gridTemplateColumns: `repeat(${columns}, 1fr)` }}>
+      {children}
+    </div>
+  );
+}

package/src/components/dashboard/DashboardItem.tsx

@@ -0,0 +1,9 @@
+import React from 'react';
+
+interface DashboardItemProps {
+  children: React.ReactNode;
+}
+
+export function DashboardItem({ children }: DashboardItemProps) {
+  return <div className="dashboard-item">{children}</div>;
+}