proje-react-panel 1.7.0 → 1.8.0

package/{DASHBOARD_GUIDE.md → guides/DASHBOARD_GUIDE.md}

@@ -527,5 +527,5 @@ The Dashboard components are part of the `proje-react-panel` library and require
 
 ## Related Components
 
-- [Counter Component](./README.md#counter-component) - For displaying animated counters
+- [Counter Component](../README.md#counter-component) - For displaying animated counters
 - [Layout Component](./AUTH_LAYOUT_GUIDE.md) - For page layouts with sidebar

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.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "",
   "author": "SEFA DEMİR",
@@ -30,6 +30,8 @@
     "@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",
@@ -41,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",

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/components/form/CustomField.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import { InputConfiguration } from '../../decorators/form/Input';
+import { useFormContext, Controller } from 'react-hook-form';
+import { CustomInputConfiguration } from '../../decorators/form/inputs/CustomInput';
+
+interface CustomFieldProps {
+  input: InputConfiguration;
+  fieldName: string;
+  error?: string;
+}
+
+export function CustomField({ input, fieldName, error }: CustomFieldProps) {
+  const inputCustom = input as CustomInputConfiguration;
+  const { control } = useFormContext();
+
+  return (
+    <Controller
+      name={fieldName}
+      control={control}
+      render={({ field }) => {
+        return (
+          <>
+            {inputCustom.render({
+              fieldName,
+              value: field.value,
+              onChange: field.onChange,
+              error,
+            })}
+          </>
+        );
+      }}
+    />
+  );
+}

package/src/components/form/FormField.tsx

@@ -5,6 +5,7 @@ import { Uploader } from './Uploader';
 import { Checkbox } from './Checkbox';
 import { Label } from './Label';
 import { Select } from './Select';
+import { CustomField } from './CustomField';
 
 interface FormFieldProps {
   input: InputConfiguration;
@@ -82,6 +83,8 @@ export function FormField({ input, register, error, baseName }: FormFieldProps)
         return <textarea {...register(fieldName)} placeholder={input.placeholder} />;
       case 'select':
         return <Select input={input} fieldName={fieldName} />;
+      case 'custom':
+        return <CustomField input={input} fieldName={fieldName} error={error?.message} />;
       case 'input': {
         return (
           <input type={input.inputType} {...register(fieldName)} placeholder={input.placeholder} />
@@ -98,7 +101,8 @@ export function FormField({ input, register, error, baseName }: FormFieldProps)
       default:
         return null;
     }
-  }, [input, register, fieldName]);
+    // NOTE: error message is a dependency because 'custom' forwards it into the render prop.
+  }, [input, register, fieldName, error?.message]);
 
   return (
     <div className={`form-field ${input.type === 'nested' ? 'nested-form-field' : ''}`}>

package/src/components/layout/Layout.tsx

@@ -1,5 +1,6 @@
-import React from 'react';
+import React, { useEffect, useRef } from 'react';
 import { SideBar } from './SideBar';
+import { LoadingScreen } from '../LoadingScreen';
 import { useAppStore } from '../../store/store';
 
 export function Layout<IconType>({
@@ -16,8 +17,23 @@ export function Layout<IconType>({
   const { user } = useAppStore(s => ({
     user: s.user,
   }));
-  if (!user) {
+  const redirected = useRef(false);
+
+  // Yonlendirme render govdesinde degil effect'te yapiliyor: render sirasindaki
+  // yan etki React kuralini ihlal ediyor ve StrictMode'da iki kez tetikleniyordu.
+  useEffect(() => {
+    if (user || redirected.current) {
+      return;
+    }
+    redirected.current = true;
     logout?.('redirect');
+  }, [user, logout]);
+
+  // Oturum yokken children RENDER EDILMEZ. Eskiden `logout('redirect')` cagrilip
+  // yine de tum layout donuluyordu; tarayici korumali ekrani boyayip ancak
+  // ondan sonra login'e gidiyordu (panelin bir an gorunup kaybolmasi).
+  if (!user) {
+    return <LoadingScreen id="layout-auth-redirect" />;
   }
 
   return (

package/src/components/list/ListPage.tsx

@@ -60,7 +60,7 @@ export function ListPage<T extends AnyClass>({
     const filtersFromUrl: Record<string, string> = {};
     searchParams.forEach((value, key) => {
       filtersFromUrl[key] = value;
-    });
+    }); 
     setActiveFilters(filtersFromUrl);
   }, []);
 

package/src/decorators/form/Input.ts

@@ -8,7 +8,7 @@ const isFieldSensitive = (fieldName: string): boolean => {
 };
 
 export type InputTypes = 'input' | 'textarea' | 'file-upload' | 'checkbox' | 'hidden' | 'nested';
-export type ExtendedInputTypes = InputTypes | 'select';
+export type ExtendedInputTypes = InputTypes | 'select' | 'custom';
 
 export interface InputOptions {
   type?: InputTypes;

package/src/decorators/form/inputs/CustomInput.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+import { ExtendedInput, ExtendedInputOptions, InputConfiguration, InputOptions } from '../Input';
+
+export interface CustomRenderProps {
+  fieldName: string;
+  value: unknown;
+  onChange: (value: unknown) => void;
+  error?: string;
+}
+
+export interface CustomInputOptions extends Omit<InputOptions, 'type'> {
+  render: (props: CustomRenderProps) => ReactNode;
+}
+
+export interface CustomInputConfiguration extends InputConfiguration {
+  type: 'custom';
+  render: (props: CustomRenderProps) => ReactNode;
+}
+
+//NOTE: the render function travels through Reflect metadata like any other option value.
+export function CustomInput(options: CustomInputOptions): PropertyDecorator {
+  return ExtendedInput({
+    ...options,
+    type: 'custom',
+  } as ExtendedInputOptions);
+}

package/src/index.ts

@@ -21,6 +21,11 @@ export { FormPage } from './components/form/FormPage';
 export { Form, type OnSubmitFN } from './decorators/form/Form';
 export { Input } from './decorators/form/Input';
 export { SelectInput } from './decorators/form/inputs/SelectInput';
+export {
+  CustomInput,
+  type CustomInputOptions,
+  type CustomRenderProps,
+} from './decorators/form/inputs/CustomInput';
 //for nested form fields
 export { getInputFields } from './decorators/form/Input';