ods-component-lib

v1.23.2

Published

16 days ago

Odeon design system component lib

0High
0Medium
0Low

Odeon Component Library (ODS Component Lib)

Odeon Design System React Component Library - Modern, yeniden kullanılabilir UI bileşenleri.

📋 İçindekiler

Hakkında

Odeon Component Library, kurumsal React uygulamaları için tasarlanmış kapsamlı bir UI bileşen kütüphanesidir. Ant Design ve DevExtreme üzerine inşa edilmiş olup, tutarlı ve profesyonel bir kullanıcı deneyimi sunar.

Özellikler

🎨 50+ Hazır Bileşen - Form elemanlarından DataGrid'lere kadar geniş bileşen yelpazesi
🚀 Performans Odaklı Mimari - Zero re-render hedefli memoization stratejisi ve module-level constant kullanımı
🎨 Zero-Runtime Styling - SCSS Modules ve CSS Variables tabanlı, çalışma zamanı maliyeti olmayan stil yönetimi
🧩 Ant Design v6 Uyumluluğu - En güncel tasarım sistemi standartları ve CSS variable köprüleme
📊 High-Density Veri İşleme - 500+ satırlı kompleks tablolarda bile akıcı DevExtreme performansı
🎯 TypeScript Desteği - Tam tip güvenliği
📖 Storybook Dokümantasyonu - İnteraktif bileşen belgeleri
⚡ Tree Shaking - Sadece kullandığınız bileşenler bundle'a dahil edilir

Gereksinimler

Peer Dependencies (Zorunlu)

| Paket | Versiyon | |-------|----------| | Node.js | 24.11.1 | | React | ^19.2.0 | | React DOM | ^19.2.0 | | DevExtreme | 25.1.7 | | DevExtreme React | 25.1.7 |

Dahili Bağımlılıklar

Kütüphane aşağıdaki paketleri içermektedir (ayrıca kurmanıza gerek yok):

| Paket | Versiyon | Açıklama | |-------|----------|----------| | Ant Design | ^6.1.1 | UI bileşen kütüphanesi | | Ant Design Icons | 6.1.0 | İkon kütüphanesi | | Day.js | ^1.11.13 | Tarih işlemleri (Moment.js yerini almıştır) | | ExcelJS | ^4.3.0 | Excel export | | jsPDF | ^2.5.1 | PDF export | | Lodash | ^4.17.21 | Utility fonksiyonlar | | Sass | ^1.97.1 | Güçlü ve esnek stil katmanı |

Kurulum

NPM ile Projenize Kurulum

npm install ods-component-lib

Peer Dependencies Kurulumu

Aşağıdaki paketlerin projenizde yüklü olduğundan emin olun:

npm install react@^19.2.0 react-dom@^19.2.0 [email protected] [email protected]

DevExtreme Stilleri

DevExtreme bileşenlerini kullanıyorsanız, projenizin giriş noktasına DevExtreme CSS dosyasını eklemeyi unutmayın:

// App.tsx veya index.tsx
import 'devextreme/dist/css/dx.light.css'; // veya dx.dark.css

ODS Component Stilleri

Kütüphanedeki CSS Modules tabanlı bileşenlerin (OdsFilter, OdsTransfer vb.) stillerini kullanmak için:

// main.tsx veya App.tsx (tek seferlik import)
import 'ods-component-lib/style.css';

Not: Bu import, OdsPhoneInput dahil tüm CSS Modules stillerini içerir.

Kullanım

Temel Kullanım

import React from 'react';
import { OdsButton, OdsInput, OdsSelect } from 'ods-component-lib';

const MyForm = () => {
  return (
    <div>
      <OdsInput placeholder="Adınızı girin" />
      <OdsSelect 
        options={[
          { value: '1', label: 'Seçenek 1' },
          { value: '2', label: 'Seçenek 2' }
        ]} 
      />
      <OdsButton type="primary">Gönder</OdsButton>
    </div>
  );
};

export default MyForm;

OdsDataGrid Kullanımı

DataGrid bileşeni, DevExtreme DataGrid üzerine inşa edilmiş, "Optimal Performance Architecture" yaklaşımıyla optimize edilmiş bir bileşendir:

import React, { useRef } from 'react';
import { OdsDataGrid, Column } from 'ods-component-lib';

const data = [
  { id: 1, name: 'Ahmet', age: 28 },
  { id: 2, name: 'Mehmet', age: 32 },
];

const MyDataGrid = () => {
  const dataGridRef = useRef(null);

  return (
    <OdsDataGrid
      dataGridRef={dataGridRef}
      dataSource={data}
      compact={true}
      keyExpr="id"
      // Performans için memoized konfigürasyonlar desteklenir
    >
      <Column dataField="name" caption="Ad" />
      <Column dataField="age" caption="Yaş" />
    </OdsDataGrid>
  );
};

export default MyDataGrid;

Performans Prensipleri

Memoization: Inline object ve callback yerine useMemo ve useCallback kullanımı.
Stable Components: Hücre render component'lerinin bileşen dışına taşınarak yeniden yaratılmasının engellenmesi.
Selective Rendering: Sadece değişen state'lerin re-render tetiklemesi için rafine edilmiş component yapısı.

OdsDataGrid Props

| Prop | Tip | Varsayılan | Açıklama | |------|-----|------------|----------| | dataGridRef | React.RefObject | - | DataGrid referansı | | compact | boolean | false | Kompakt görünüm modu | | hasSummaryButton | boolean | false | Özet butonu gösterimi | | disableBodyClasses | boolean | false | Body class yönetimini devre dışı bırakır | | dataGridBorderRadius | number \| string | - | Border radius değeri |

Not: Tüm DevExtreme DataGrid props'ları da desteklenmektedir.

Stil Yönetimi ve CSS/SCSS

ODS Component Library, modern web standartlarına uygun, performanslı ve esnek bir stil yönetim sistemi sunar. Projede Zero-Runtime CSS stratejisi benimsenmiştir.

� Hızlı Başlangıç

// main.tsx veya App.tsx - giriş noktasında
import 'ods-component-lib/style.css';                    // CSS Modules stilleri (OdsFilter, OdsTransfer vb.)
import 'ods-component-lib/styles/OdsDataGrid.css';       // DataGrid ana stilleri (OdsDataGrid kullanıyorsanız)
import 'ods-component-lib/styles/datagrid-globals.css';  // DataGrid overlay stilleri (OdsDataGrid kullanıyorsanız)
import 'devextreme/dist/css/dx.light.css';               // DevExtreme teması

📦 Stil Dosyaları

| Import Path | İçerik | Ne Zaman Gerekli | |-------------|--------|------------------| | ods-component-lib/style.css | CSS Modules (OdsFilter, OdsTransfer, OdsPhoneInput vb.) | Her zaman | | ods-component-lib/styles/OdsDataGrid.css | DataGrid ana stilleri | OdsDataGrid/OdsDataGridV2 kullanıyorsanız | | ods-component-lib/styles/datagrid-globals.css | DataGrid overlay stilleri (dropdown, tooltip vb.) | OdsDataGrid/OdsDataGridV2 kullanıyorsanız | | ods-component-lib/styles/_variables.scss | SCSS değişkenleri | Kendi SCSS'inizde ODS token'ları kullanmak istiyorsanız |

💎 SCSS Modules

Bileşene özel stiller için .module.scss dosyaları kullanılır. Bu yaklaşım, class isimlerinin çakışmasını önler.

import styles from './MyComponent.module.scss';

const MyComponent = () => (
  <div className={styles.wrapper}>
    <span className={styles.title}>Merhaba</span>
  </div>
);

🌍 Ant Design CSS Variables

Ant Design v6 CSS değişkenleri projede aktif olarak kullanılır:

@use 'ods-component-lib/styles/variables' as *;

.my-custom-box {
  background-color: var(--ant-color-primary);
  border-radius: var(--ant-border-radius);
}

Bileşenler

Ant Design Tabanlı Bileşenler

| Kategori | Bileşenler | |----------|------------| | Form | OdsInput, OdsPassword, OdsTextArea, OdsSearch, OdsPhoneInput, OdsInputNumber, OdsCurrencyInput | | Seçim | OdsSelect, OdsMultiSelect, OdsCheckbox, OdsCheckboxGroup, OdsRadio, OdsRadioGroup, OdsSwitch, OdsTreeSelect | | Tarih/Zaman | OdsDatepicker, OdsDateRangePicker, OdsTimepicker, OdsRangeTimepicker, OdsCalendar | | Görüntüleme | OdsCard, OdsCollapse, OdsImage, OdsList, OdsTable, OdsBasicTable, OdsTag, OdsBadge, OdsDivider | | Tipografi | OdsTitle, OdsText, OdsParagraph, OdsLink | | Geri Bildirim | OdsAlert, OdsBannerAlert, OdsNotification, OdsModal, OdsSpin, OdsProgress | | Navigasyon | OdsTab, OdsDropdown, OdsTreeListMenu, OdsTimeline | | Diğer | OdsButton, OdsAutoComplete, OdsFileUpload, OdsRate, OdsChange |

DevExtreme Tabanlı Bileşenler

| Bileşen | Açıklama | |---------|----------| | OdsDataGridV2 | ⭐ Minimal DataGrid wrapper - Zero overhead (önerilen) | | OdsDataGrid | Modern DataGrid bileşeni (default settings ile) | | OdsDataGridMemoized | Memoized DataGrid versiyonu | | OdsMergeCellDataGrid | Hücre birleştirme özellikli DataGrid | | OdsTimelineTable | Zaman çizelgesi tablosu | | OdsTransfer | Transfer bileşeni | | OdsTransferV2 | Transfer bileşeni v2 |

OdsDataGridV2 Kullanımı

OdsDataGridV2, DevExtreme DataGrid'in birebir wrapper'ıdır - sadece className ekler:

import { OdsDataGridV2, Column } from 'ods-component-lib';

const MyGrid = () => (
  <OdsDataGridV2 dataSource={data} compact={true}>
    <Column dataField="name" />
    <Column dataField="age" />
  </OdsDataGridV2>
);

Deprecated DataGrid Bileşenleri

Aşağıdaki bileşenler ilerleyen sürümlerde kaldırılacaktır. Lütfen OdsDataGrid kullanımına geçin:

OdsDataGridLegacy
OdsBasicDataGrid
OdsBatchEditDataGrid
OdsDisplayGrid
OdsInlineEditDataGrid
OdsRemoteDataGrid
OdsServerSideDatagrid

Filtre Bileşenleri

| Bileşen | Açıklama | |---------|----------| | OdsFilter | Temel filtre bileşeni | | OdsFilterPlus | Gelişmiş filtre bileşeni | | OdsFilterTagView | Filtre etiketleri görünümü |

Hooks

| Hook | Açıklama | |------|----------| | useBodyClasses | Body class yönetimi için hook |

Geliştirme

Kaynak Koddan Kurulum

# Repository'yi klonlayın
git clone https://github.com/OdeonTechnology/ods-component-lib.git

# Proje dizinine gidin
cd odeon-component-library

# Bağımlılıkları yükleyin
npm install

# veya postinstall scriptini atlamak için
npm install --ignore-scripts

Storybook ile Geliştirme

Storybook, bileşenleri izole bir şekilde geliştirmek ve test etmek için kullanılır:

# Storybook'u başlatın (port: 3010)
npm run storybook

Storybook başladıktan sonra tarayıcınızda http://localhost:3010 adresini açın.

Yeni Bileşen Oluşturma

Plop generator kullanarak yeni bileşen oluşturabilirsiniz:

npm run plop

Scripts

| Script | Açıklama | |--------|----------| | npm run dev | Watch modunda build | | npm run build | Production build | | npm run storybook | Storybook'u başlat (port: 3010) | | npm run build-storybook | Storybook static build | | npm run test | Testleri çalıştır | | npm run test:watch | Testleri watch modunda çalıştır | | npm run test:lint | ESLint kontrolü | | npm run plop | Yeni bileşen oluştur | | npm run patch | Versiyon patch |

Klasör Yapısı

odeon-component-library/
├── src/
│   ├── components/
│   │   ├── antd/              # Ant Design tabanlı bileşenler
│   │   │   ├── alert/
│   │   │   ├── button/
│   │   │   ├── input/
│   │   │   └── ...
│   │   ├── devextreme/        # DevExtreme tabanlı bileşenler
│   │   │   ├── DataGrid/      # Modern OdsDataGrid
│   │   │   ├── OdsTimelineTable/
│   │   │   └── ...
│   │   ├── filter/            # Filtre bileşenleri
│   │   └── helpers/           # Yardımcı bileşenler
│   ├── hooks/                 # Custom hooks
│   ├── stories/               # Storybook hikayeleri
│   ├── tokens/                # Design tokens
│   ├── utils/                 # Utility fonksiyonlar
│   └── index.tsx              # Ana export dosyası
├── dist/                      # Build çıktısı
├── .storybook/                # Storybook yapılandırması
├── plop-templates/            # Plop template'leri
├── package.json
├── tsconfig.json
├── vite.config.ts
└── vitest.config.ts

Build Çıktısı

Kütüphane aşağıdaki formatlarda build edilir:

ES Modules: dist/index.js
TypeScript Types: dist/index.d.ts
CSS Modules Bundle: dist/ods-component-lib.css
DataGrid Stilleri: dist/styles/OdsDataGrid.css, dist/styles/datagrid-globals.css