@tecof/theme-editor

Tecof platform için Puck CMS tabanlı sayfa editörü, render motoru ve gelişmiş alan bileşenleri kütüphanesi.

API Client, Context Provider, Puck wrapper bileşenleri, çok dilli alan yöneticileri, medya yöneticisi, link seçici, resim görüntüleyici ve tema araçları içerir.

Kurulum

npm install @tecof/theme-editor @puckeditor/core react react-dom

Hızlı Başlangıç

1. TecofProvider ile Sarma

import { TecofProvider } from "@tecof/theme-editor";

<TecofProvider
  apiUrl="https://api.example.com"
  secretKey="your-merchant-secret-key"
  config={puckConfig}
>
  {children}
</TecofProvider>

2. Editör Sayfası

"use client";
import { TecofEditor } from "@tecof/theme-editor";
import { puckConfig } from "@/puck-config";

export default function EditorPage({ params }) {
  return <TecofEditor pageId={params.id} />;
}

3. Public Sayfa (Render)

import { TecofRender } from "@tecof/theme-editor";

// Slug ile otomatik fetch
<TecofRender slug="home" />

// Direkt data ile
<TecofRender data={puckData} />

Bileşenler

<TecofProvider />

Tüm Tecof bileşenlerini sarar, API client ve config context'i sağlar.

| Prop | Tip | Açıklama | |------|-----|----------| | apiUrl | string | Backend API base URL | | secretKey | string | Merchant secret key | | config | Config | Puck component configuration | | children | ReactNode | Alt bileşenler |

<TecofEditor />

Puck wrapper — sayfa editörü. Otomatik fetch/save ve iframe postMessage desteği.

| Prop | Tip | Açıklama | |------|-----|----------| | pageId | string | Düzenlenecek sayfa ID'si | | onSave | (data) => void | Kayıt sonrası callback | | onPublish | (data) => void | Yayınlama sonrası callback | | onChange | (data) => void | Her değişiklikte callback | | overrides | object | Puck UI override'ları |

<TecofRender />

Yayınlanmış sayfaları render eder.

| Prop | Tip | Açıklama | |------|-----|----------| | slug | string | Sayfa slug'ı (otomatik fetch) | | data | PuckPageData | Direkt puck data (fetch yapmaz) | | fallback | ReactNode | Yükleme sırasında gösterilen bileşen |

<TecofPicture />

Akıllı medya bileşeni — görsel/video otomatik algılama, responsive boyutlar, fancybox desteği.

import { TecofPicture } from "@tecof/theme-editor";
import Image from "next/image";

// Basit kullanım
<TecofPicture data={file} alt="Hero" />

// Fill modu
<TecofPicture data={file} fill />

// Next.js Image ile
<TecofPicture
  data={file}
  ImageComponent={Image}
  imageProps={{ quality: 85, priority: true }}
/>

// Fancybox lightbox
<TecofPicture data={file} fancybox fancyboxName="gallery" />

| Prop | Tip | Açıklama | |------|-----|----------| | data | UploadedFile | Yüklenen dosya verisi | | alt | string | Alt metin | | size | thumbnail \| medium \| large \| full | Responsive boyut | | fill | boolean | Parent'ı kaplar | | ImageComponent | ComponentType | Özel image bileşeni (örn: Next.js Image) | | imageProps | Record<string,any> | ImageComponent'e ek prop'lar | | fancybox | boolean | Fancybox lightbox desteği |

Custom Fields (Puck Alanları)

Tüm alanlar createXField() factory fonksiyonları ile Puck config'e entegre edilir.

LanguageField — Çok Dilli Metin

Sekmeli çok dilli metin girişi. Merchant ayarlarından dilleri otomatik çeker.

import { createLanguageField } from "@tecof/theme-editor";

fields: {
  title: createLanguageField({ label: "Başlık" }),
  description: createLanguageField({
    label: "Açıklama",
    isTextarea: true,
    textareaRows: 4,
  }),
  htmlContent: createLanguageField({
    label: "HTML İçerik",
    isHtml: true,
  }),
}

Özellikler:

• 🌐 Otomatik dil algılama (merchant ayarlarından)
• 📋 Hızlı Doldur — Aktif sekmedeki metni tüm dillere kopyalar
• 🔄 Çevir — Aktif metni API üzerinden diğer dillere otomatik çevirir (DeepL / Google / OpenAI / Ollama)
• isHtml desteği — HTML taglarını koruyarak çeviri yapar

| Option | Tip | Default | Açıklama | |--------|-----|---------|----------| | isTextarea | boolean | false | Textarea modu | | textareaRows | number | 3 | Textarea satır sayısı | | placeholder | string | '' | Placeholder metni | | isHtml | boolean | false | HTML içerik çevirisi |

EditorField — Zengin Metin Editörü

TipTap tabanlı, çok dilli WYSIWYG editörü.

fields: {
  content: createEditorField({ label: "İçerik" }),
}

Özellikler: Bold, italic, link, liste, heading ve daha fazlası.

UploadField — Gelişmiş Medya Yöneticisi

FilePond tabanlı dosya yükleme + Vaul Drawer medya kütüphanesi + Doka görseldüzenleyici.

fields: {
  images: createUploadField({
    label: "Görseller",
    allowMultiple: true,
    maxFiles: 10,
    maxFileSize: "50MB",
    showUploadedFiles: true,
  }),
  document: createUploadField({
    label: "Doküman",
    allowMultiple: false,
    acceptedTypes: ["application/pdf"],
  }),
}

Özellikler:

• 📁 Medya Seç — Vaul drawer ile sunucudaki mevcut dosyaları seçin
• 📤 Yeni Yükle — FilePond ile sürükle-bırak dosya yükleme
• 🖼️ Doka Görsel Düzenleyici — Kırp, döndür, parlaklık, kontrast, markup, çıkartma
• 🗜️ Resim Sıkıştırma — Otomatik WebP dönüşümü (browser-image-compression)
• 📄 24+ dosya türü desteği (görseller, PDF, Office, CSV, video)
• 👁️ Dosya önizleme, indirme ve kaldırma butonları
• 🇹🇷 Tamamen Türkçe etiketler (FilePond + Doka)

| Option | Tip | Default | Açıklama | |--------|-----|---------|----------| | allowMultiple | boolean | true | Çoklu dosya | | maxFiles | number | 100 | Maksimum dosya sayısı | | maxFileSize | string | 100MB | Tek dosya limiti | | maxTotalFileSize | string | 200MB | Toplam limit | | acceptedTypes | string[] | [all] | İzin verilen MIME türleri | | showUploadedFiles | boolean | false | Başlık göster | | imageCompressionEnabled | boolean | true | Sıkıştırma aktif | | allowReorder | boolean | true | Sürükle-bırak sıralama |

LinkField — Sayfa / URL Seçici

Mevcut sayfalardan seçim veya manuel URL girişi.

fields: {
  link: createLinkField({ label: "Bağlantı" }),
  ctaLink: createLinkField({
    label: "CTA Link",
    showTarget: true,
    placeholder: "https://example.com",
  }),
}

Özellikler:

• 📄 Sayfa Seç — Vaul drawer ile merchant sayfalarını listeler, aranabilir
• 🔗 Manuel Link — URL + etiket + hedef (aynı/yeni sekme) girişi
• 🟢 Durum göstergesi (yayınlanmış / değiştirilmiş / taslak)
• 🏷️ Tip badge'i (Sayfa / Link)

| Option | Tip | Default | Açıklama | |--------|-----|---------|----------| | showTarget | boolean | true | Hedef sekme seçici | | placeholder | string | https://... | URL placeholder |

Değer Tipi (LinkFieldValue):

{
  url: string;       // "/about" veya "https://..."
  label?: string;    // "Hakkımızda"
  target?: "_self" | "_blank";
  type?: "page" | "custom";
}

CodeEditorField — Kod Editörü

Monaco Editor tabanlı syntax-highlighted kod editörü.

fields: {
  customHtml: createCodeEditorField({
    label: "Özel Kod",
    defaultLanguage: "html",
  }),
  jsonConfig: createCodeEditorField({
    label: "Config",
    defaultLanguage: "json",
  }),
}

ColorField — Renk Seçici

Yerel renk seçici, HEX giriş, hazır palet ve opsiyonel opaklık kaydırıcısı.

import { createColorField } from "@tecof/theme-editor";

fields: {
  bgColor: createColorField({ label: "Arka Plan Rengi" }),
  textColor: createColorField({
    label: "Metin Rengi",
    showOpacity: true,
    defaultColor: "#18181b",
  }),
  accentColor: createColorField({
    label: "Vurgu Rengi",
    showPresets: false,
  }),
}

Özellikler:

• 🎨 Yerel Renk Seçici — Sistem renk picker'ı ile kolay seçim
• 🔤 HEX Giriş — Monospace font ile doğrudan HEX kodu yazma
• 🎯 Hazır Palet — 9×n grid ile hızlı renk seçimi (tamamen özelleştirilebilir)
• 🔲 Opaklık — Opsiyonel alpha/opaklık kaydırıcısı (8-digit hex)
• ↩️ Sıfırla — Varsayılan renge geri dönme butonu

| Option | Tip | Default | Açıklama | |--------|-----|---------|----------| | showOpacity | boolean | false | Opaklık kaydırıcısı | | showPresets | boolean | true | Hazır renk paleti göster | | presetColors | string[] | [built-in] | Özel hazır renk listesi | | defaultColor | string | '' | Varsayılan/sıfırlama rengi | | placeholder | string | #000000 | HEX giriş placeholder | | showReset | boolean | true | Sıfırlama butonu göster |

Ortak Alan Seçenekleri (BaseField)

Tüm create*Field() factory fonksiyonları aşağıdaki ortak seçenekleri destekler:

| Option | Tip | Açıklama | |--------|-----|----------| | label | string | Puck sidebar'da görünen alan etiketi | | labelIcon | ReactElement | Etiketin yanında gösterilen ikon (ör: Lucide) | | visible | boolean | Alanın sidebar'da görünür olup olmadığı |

import { Globe, Image, Palette } from "lucide-react";

fields: {
  title: createLanguageField({
    label: "Başlık",
    labelIcon: <Globe size={16} />,
  }),
  bgColor: createColorField({
    label: "Arka Plan",
    labelIcon: <Palette size={16} />,
  }),
  logo: createUploadField({
    label: "Logo",
    labelIcon: <Image size={16} />,
    visible: true,
  }),
}

API Client

import { TecofApiClient } from "@tecof/theme-editor";

const client = new TecofApiClient("https://api.example.com", "secret-key");

| Metot | Açıklama | |-------|----------| | getPage(id) | Sayfa draft'ını getir | | savePage(id, data) | Sayfa kaydet | | getPublishedPage(slug, locale?) | Yayınlanmış sayfayı getir | | getMerchantInfo() | Dil ayarlarını getir | | uploadFile(file, folder?) | Dosya yükle | | getUploads(page, limit) | Yüklenen dosyaları listele | | getPages() | Merchant sayfalarını listele | | translate(text, sourceLang, locales, isHtml?) | Metni birden çok dile çevir | | cdnUrl | CDN base URL |

Backend API Endpoints

Kütüphane aşağıdaki endpoint'leri kullanır (x-secret-key header ile):

| Method | Endpoint | Açıklama | |--------|----------|----------| | GET | /api/store/editor/:id | Sayfa draft'ını getir | | PUT | /api/store/editor/:id | Sayfa kaydet | | POST | /api/store/render | Yayınlanmış sayfayı getir (slug + locale) | | GET | /api/store/merchant-info | Merchant dil ayarları | | POST | /api/store/upload | Dosya yükle | | GET | /api/store/uploads | Yüklenen dosyaları listele | | GET | /api/store/pages | Merchant sayfalarını listele | | POST | /api/store/translate | Metni çok dile çevir |

Utility Fonksiyonları

import {
  getDefaultTheme,
  generateCSSVariables,
  mergeTheme,
  hexToHsl,
  hslToHex,
  lighten,
  darken,
} from "@tecof/theme-editor";

| Fonksiyon | Açıklama | |-----------|----------| | getDefaultTheme() | Varsayılan tema config'i | | generateCSSVariables(theme) | ThemeConfig → CSS custom properties | | mergeTheme(base, overrides) | Tema config deep-merge | | hexToHsl(hex) | Hex → HSL dönüşümü | | hslToHex(h, s, l) | HSL → Hex dönüşümü | | lighten(hex, amount) | Rengi açar | | darken(hex, amount) | Rengi koyulaştırır |

iframe postMessage API

TecofEditor iframe içinde çalıştığında parent ile iletişim kurar:

// Parent → Editor
iframe.postMessage({ type: "puck:publish" }, "*");
iframe.postMessage({ type: "puck:undo" }, "*");
iframe.postMessage({ type: "puck:redo" }, "*");
iframe.postMessage({ type: "puck:viewport", width: "375px" }, "*");

// Editor → Parent
window.addEventListener("message", (e) => {
  if (e.data.type === "puck:save") { /* değişiklik var */ }
  if (e.data.type === "puck:saved") { /* başarıyla kaydedildi */ }
});

CSS ve Tema Yapısı

Kütüphane %100 oranında izole bir CSS altyapısı sunar. Önceden kullanılan inline "CSS-in-JS" tarzı sabit tasarımlar kaldırılmış, field modüllerine ait tüm UI stilleri (EditorField, LinkField, UploadField vs.) merkezi dist/styles.css içerisine taşınmıştır.

Tasarım çakışmalarını önlemek için kütüphanenin sunduğu tüm CSS sınıfları sadece .tecof-[component]-[element] (örnek: .tecof-upload-file-list) ön ekini kullanır. :root altındaki renk değişkenlerinden (örn: --tecof-primary-500) beslenir.

Editör alanlarının tam verimle (FilePond, Doka Editor vs.) düzgün işleyebilmesi için bu CSS dosyasını layout ana dosyanıza dahil edin:

// Ana Layout / Editor bileşenine yakın
import "@tecof/theme-editor/dist/styles.css";

Geliştirme

npm run dev        # Watch mode (tsup)
npm run build      # Production build + CSS bundle
npm run lint       # ESLint
npm run test       # Vitest
npm run storybook  # Storybook

Lisans

MIT © Tecof