@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.

<TecofEditor />

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

<TecofRender />

Yayınlanmış sayfaları render eder.

<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" />

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

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)

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)

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

Ortak Alan Seçenekleri (BaseField)

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

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");

Backend API Endpoints

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

Utility Fonksiyonları

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

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