@tecof/theme-editor

Tecof platform için Puck CMS tabanlı sayfa editörü ve render kütüphanesi. API client, context provider ve Puck wrapper bileşenleri içerir.

Kurulum

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

Hızlı Başlangıç

1. Puck Config Oluştur

// puck-config.tsx
import type { Config } from "@puckeditor/core";
import { Header } from "./components/puck/Header";
import { HeroSection } from "./components/puck/Hero";
import { Footer } from "./components/puck/Footer";

export const puckConfig: Config = {
  components: {
    Header,
    HeroSection,
    Footer,
  },
};

2. Editör Sayfası

// app/editor/[slug]/page.tsx
"use client";

import { TecofProvider, TecofEditor } from "@tecof/theme-editor";
import "@tecof/theme-editor/styles.css";
import "@puckeditor/core/puck.css";
import { puckConfig } from "@/puck-config";

export default function EditorPage() {
  return (
    <TecofProvider
      apiUrl="https://api.example.com"
      accessToken="your-merchant-token"
      config={puckConfig}
    >
      <TecofEditor
        slug="home"
        onSave={(data) => console.log("Saved:", data)}
      />
    </TecofProvider>
  );
}

3. Public Sayfa (Render)

// app/[slug]/page.tsx
import { TecofProvider, TecofRender } from "@tecof/theme-editor";
import { puckConfig } from "@/puck-config";

export default function PublicPage() {
  return (
    <TecofProvider
      apiUrl="https://api.example.com"
      accessToken="your-merchant-token"
      config={puckConfig}
    >
      <TecofRender slug="home" />
    </TecofProvider>
  );
}

Direkt data ile de render edebilirsiniz:

<TecofRender data={puckData} />

API

<TecofProvider />

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

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

<TecofEditor />

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

| Prop | Tip | Açıklama | |------|-----|----------| | slug | string | Düzenlenecek sayfa slug'ı | | 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ı | | plugins | any[] | Ek Puck plugin'leri | | className | string | CSS class |

<TecofRender />

Puck <Render> wrapper — 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österilecek bileşen | | className | string | CSS class |

useTecof()

Provider context'ine erişim hook'u:

const { apiClient, config, accessToken, apiUrl } = useTecof();

TecofApiClient

Standalone API client:

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

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

// Sayfa draft'ını getir
const page = await client.getPage("home");

// Sayfa kaydet
await client.savePage("home", puckData);

// Yayınlanmış sayfayı getir
const published = await client.getPublishedPage("about");

Utility Fonksiyonları

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

| Fonksiyon | Açıklama | |-----------|----------| | getDefaultTheme() | Varsayılan tema config'i döner | | 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 |

Custom Fields (Özel Alanlar)

Kütüphane içinde Tecof platformuna özel olarak hazırlanmış gelişmiş Puck alanları (fields) bulunmaktadır:

| Alan Adı | Özellikler | |----------|------------| | LanguageField | Çok dilli, sekmeli düz metin girişi. Uygulama ayarlarından tanımlı dilleri otomatik çeker. | | EditorField | Çok dilli, zengin metin editörü (TipTap tabanlı). Bold, italic, link, liste gibi temel araç çubuğuna sahiptir. | | UploadField | FilePond ve Vaul Drawer tabanlı medya yöneticisi. Yeni görsel yükleme ve sunucudaki eski medyaları seçme yeteneğine sahiptir. | | CodeEditorField | Monaco Editor tabanlı kod editörü. HTML, CSS, JSON gibi özel kod alanları eklemek için kullanılır. |

Örnek Kullanım:

import { 
  createLanguageField, 
  createEditorField, 
  createUploadField, 
  createCodeEditorField 
} from "@tecof/theme-editor";

const myComponent = {
  fields: {
    title: createLanguageField({ label: "Başlık" }),
    content: createEditorField({ label: "İçerik" }),
    images: createUploadField({ 
      label: "Görseller", 
      allowMultiple: true, 
      maxFiles: 5 
    }),
    customHtml: createCodeEditorField({ 
      label: "Özel Kod", 
      defaultLanguage: "html" 
    })
  },
  // ...
};

iframe postMessage API

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

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

// 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 */ }
});

Backend API Endpoints

Kütüphane aşağıdaki endpoint'leri kullanır (Authorization header ile):

| Method | Endpoint | Açıklama | |--------|----------|----------| | GET | /api/store/page/:slug | Sayfa draft'ını getir | | PUT | /api/store/page/:slug | Sayfa draft'ını kaydet | | GET | /api/store/published/:slug | Yayınlanmış sayfayı getir |

Geliştirme

npm run dev        # Watch mode
npm run build      # Production build
npm run lint       # ESLint
npm run test       # Vitest

Lisans

MIT