@tecof/theme-editor

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

API Client, Context Provider, Tecof Studio editörü, ç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 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"
>
  {children}
</TecofProvider>

2. Editör Sayfası

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

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

3. Public Sayfa (Render)

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

<TecofRender data={pageData} config={tecofConfig} />

Bileşenler

<TecofProvider />

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

<TecofEditor />

Tecof Studio sayfa editörü. Otomatik fetch/save, iframe postMessage desteği, canvas DnD, katman paneli ve inspector içerir.

TecofEditor, TecofStudio'nun takma adıdır (TecofEditor = TecofStudio) — ikisi de aynı editörü açar.

<TecofRender />

Önceden yüklenmiş sayfa verisini render eder. Fetch akışı için TecofApiClient.getPublishedPage(slug, locale?) kullanılıp dönen draftData/sayfa verisi bu bileşene verilir.

<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 (Editör Alanları)

Tüm alanlar createXField() factory fonksiyonları ile Tecof/Puck-compatible 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:save" }, "*");
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:changed") { /* değişiklik var (debounce'lu) */ }
  if (e.data.type === "puck:saved") { /* başarıyla kaydedildi, e.data.data güncel draft */ }
  if (e.data.type === "puck:saveError") { /* kayıt hatası */ }
  if (e.data.type === "puck:itemSelected") { /* e.data.item = { type, id } */ }
  if (e.data.type === "puck:itemDeselected") { /* seçim kalktı */ }
});

Güvenlik: hostOrigin prop'u verildiğinde gelen mesajlar e.origin'e göre doğrulanır ve giden mesajlar yalnızca o origin'e gönderilir. Embed senaryosunda hostOrigin vermeniz önerilir; aksi halde '*' kullanılır (geriye uyumluluk). Tüm köprü src/studio/bridge.ts içinde soyutlanmıştır.

Klavye Kısayolları (Studio)

Kopyalanan node'lar localStorage (tecof📋v1) üzerinden sekmeler/sayfalar arası yapıştırılabilir; yapıştırmada id'ler taze üretilir.

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. Tüm editör arayüzü src/styles.css içindeki :root token'larından beslenir.

Renk Paleti (lime-green)

:root altında tam bir --tecof-primary-50…950 lime-green paleti tanımlıdır. Kural: 600 ana renk, 700 hover. Bileşenler doğrudan -500/-600 skalasını değil, semantik accent token'larını kullanır:

Lime zemin üzerine beyaz yazı kontrast bırakmadığı için accent dolgular koyu yazı (--tecof-accent-fg) kullanır. Bu token'lar yalnızca editör arayüzünü boyar; kullanıcı sitesinin teması (--theme-*, generateCSSVariables) etkilenmez.

Studio arayüzü de aynı sistemdedir: canvas, drop zone, selection overlay, inspector ve field loader'ları bu accent token'larını ve .tecof-skeleton* primitive'lerini kullanır. Tüm yükleme durumları skeleton loader'dır (spinner yalnızca buton-içi mikro yüklemede). Inline style yalnızca gerçek runtime değerleri için bırakılır (örn. seçili node overlay koordinatı, layer indent CSS değişkeni, kullanıcı renk swatch'ı veya dışarıdan gelen render style prop'u).

Studio Editör Özellikleri

• Düzenleme / Önizleme modu — Üst bardaki toggle ile. Düzenleme'de tıklayınca bileşen seçilir, link/butonlar pasiftir; Önizleme'de link ve butonlar canlı çalışır, editör çerçevesi gizlenir.
• Inline metin düzenleme — Canvas'taki metne çift tıklayın; düzenlenen öğe accent kenarlıkla işaretlenir (öğenin kendi arka plan/yazı rengi korunur), Enter kaydeder, Esc iptal eder. Bileşenler düzenlenebilir metni data-tecof-prop="propAdı" (ve çok dilli için data-tecof-lang) ile işaretleyebilir; aksi halde string-eşleştirme fallback'i devreye girer.
• Çoklu seçim + kopyala/yapıştır — ⌘/Ctrl/Shift + tık ile çoklu seçim; kopyala/kes/yapıştır (sekmeler arası localStorage), toplu sil/çoğalt. Bkz. Klavye Kısayolları.
• Görsel stil editörü (Tailwind) — Inspector'daki "Stil" sekmesi; breakpoint + state bazlı, preset token'lar ve serbest (arbitrary) değerler. Bkz. docs/TAILWIND.md.
• Görsel blok paleti — Sol panelde bileşenler, varsa render önizleme görselleriyle (lazy yüklenir).
• Çökme dayanıklılığı — Bir bileşenin render hatası tüm canvas'ı düşürmez; node bazında error boundary ile izole edilir, prop düzeltilince kendiliğinden toparlanır.
• Global dil — Çoklu dilli içerikte dil, üst bardaki tek seçiciden (merchant-info) değiştirilir. Alanlar yalnızca aktif dili düzenler; alan-içi dil sekmeleri Studio'da gizlenir (provider yoksa eski sekmeli mod geçerlidir — geriye uyum). Bkz. studio/language/LanguageContext.
• Daraltılabilir paneller — Sol (blok/katman) ve sağ (inspector) paneller üst bar butonlarıyla daraltılıp ince ikon rayına iner; canvas genişler.
• Performans — Ağır editör alanları (Monaco / TipTap / FilePond) ayrı chunk'lara bölünüp talep üzerine yüklenir; ana paket ~1.37 MB → ~210 KB.

Stil Editörü & Tailwind

Inspector "Stil" sekmesi, node'lara yapısal token modeli (node.props._tecofStyles) olarak stil uygular ve bunu Tailwind class string'ine derler. Üretimde class'ların purge edilmemesi için host Tailwind config'ine safelist eklenmelidir:

import { getSafelist } from "@tecof/theme-editor";
export default { safelist: getSafelist(), /* ... */ };

Tam entegrasyon (Tailwind v4 @theme, arbitrary değerler, breakpoint/state) için: docs/TAILWIND.md.

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