npm - @ozsarman/clarityjs - Versions diffs - 0.6.0 - Mend

@ozsarman/clarityjs 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/src/layout.js ADDED Viewed

@@ -0,0 +1,342 @@
+/**
+ * Clarity.js — Layout System
+ *
+ * Next.js app/ layout.js / Nuxt layouts/ eşdeğeri.
+ * Dosya tabanlı nested layout konvansiyonu + programatik API.
+ *
+ * ── Dosya konvansiyonu ────────────────────────────────────────────────────────
+ *
+ *   pages/
+ *   ├── _layout.js          ← root layout (tüm sayfaları sarar)
+ *   ├── index.js
+ *   ├── about.js
+ *   └── blog/
+ *       ├── _layout.js      ← /blog/* için layout (root layout'u da devralır)
+ *       └── [slug].js
+ *
+ * ── _layout.js örneği ────────────────────────────────────────────────────────
+ *
+ *   // pages/_layout.js
+ *   export default function RootLayout({ children }) {
+ *     return (
+ *       <html lang="tr">
+ *         <body>
+ *           <Nav />
+ *           <main>{children}</main>
+ *           <Footer />
+ *         </body>
+ *       </html>
+ *     );
+ *   }
+ *
+ * ── Programatik API ───────────────────────────────────────────────────────────
+ *
+ *   import { defineLayout, applyLayouts, renderWithLayouts } from '@ozsarman/clarityjs/layout'
+ *
+ *   defineLayout('root', RootLayout);
+ *   defineLayout('blog', BlogLayout, { parent: 'root' });
+ *
+ *   // Bir sayfayı layout'larıyla render et:
+ *   const html = renderWithLayouts(BlogPost, { slug: 'hello' }, 'blog');
+ *
+ * ── definePageMeta ────────────────────────────────────────────────────────────
+ *
+ *   // pages/blog/[slug].js
+ *   export const pageMeta = definePageMeta({
+ *     layout: 'blog',         // kullanılacak layout
+ *     title:  'Blog Yazısı',
+ *     auth:   true,           // route guard
+ *   });
+ *
+ * ── SSR entegrasyonu ──────────────────────────────────────────────────────────
+ *
+ *   import { wrapWithLayouts } from '@ozsarman/clarityjs/layout'
+ *
+ *   // SSR pipeline'da:
+ *   const html = renderToString(wrapWithLayouts(PageComponent, layoutChain), { props });
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+import { renderToString } from './ssr.js';
+// ─── Layout Registry ──────────────────────────────────────────────────────────
+const _layoutRegistry = new Map();
+/**
+ * Programatik layout tanımı.
+ *
+ * @param {string}    name           – Layout adı (benzersiz)
+ * @param {Function}  ComponentFn   – Layout bileşeni ({ children, ...props }) => node
+ * @param {object}    [opts]
+ * @param {string}    [opts.parent]  – Ebeveyn layout adı (nested layouts)
+ */
+export function defineLayout(name, ComponentFn, opts = {}) {
+  const { parent = null } = opts;
+  _layoutRegistry.set(name, { name, ComponentFn, parent });
+}
+/**
+ * Kayıtlı layout'u al.
+ * @param {string} name
+ * @returns {{ name: string, ComponentFn: Function, parent: string|null } | null}
+ */
+export function getLayout(name) {
+  return _layoutRegistry.get(name) ?? null;
+}
+/**
+ * Tüm layout kayıtlarını sıfırla (test / SSR yeniden başlatma için).
+ */
+export function resetLayoutRegistry() {
+  _layoutRegistry.clear();
+}
+// ─── definePageMeta ───────────────────────────────────────────────────────────
+/**
+ * Sayfa metadata tanımla — layout seçimi, auth guard, title vb.
+ * Sayfa dosyasında `export const pageMeta = definePageMeta({...})` şeklinde kullanılır.
+ *
+ * @param {object}  opts
+ * @param {string}  [opts.layout]     – Kullanılacak layout adı (yoksa 'default')
+ * @param {string}  [opts.title]      – Sayfa başlığı
+ * @param {boolean} [opts.auth]       – Kimlik doğrulama gerektiriyor mu?
+ * @param {string}  [opts.middleware] – Middleware adı
+ * @param {object}  [opts.meta]       – Ek metadata
+ * @returns {PageMeta}
+ */
+export function definePageMeta(opts = {}) {
+  return {
+    __clarity_page_meta__: true,
+    layout:     opts.layout ?? 'default',
+    title:      opts.title  ?? null,
+    auth:       opts.auth   ?? false,
+    middleware: opts.middleware ?? null,
+    meta:       opts.meta   ?? {},
+    ...opts,
+  };
+}
+// ─── Layout zinciri oluştur ───────────────────────────────────────────────────
+/**
+ * Bir layout adından başlayarak en üst layout'a kadar zincir oluşturur.
+ * ['root', 'blog'] gibi dıştan içe sıralı döner.
+ *
+ * @param {string} layoutName
+ * @returns {Array<{ name: string, ComponentFn: Function }>}
+ */
+export function buildLayoutChain(layoutName) {
+  const chain = [];
+  let current = _layoutRegistry.get(layoutName) ?? null;
+  while (current) {
+    chain.unshift(current);  // en dıştan başla
+    current = current.parent ? _layoutRegistry.get(current.parent) ?? null : null;
+  }
+  return chain;
+}
+// ─── Runtime: children injection ─────────────────────────────────────────────
+/**
+ * Sayfa bileşenini layout zinciriyle sar.
+ * En dış layout en üstte, sayfa bileşeni en içte.
+ *
+ * @param {Function}  PageComponent
+ * @param {Array}     layoutChain    – buildLayoutChain() çıktısı
+ * @returns {Function}  Sarılmış bileşen (render için kullanılır)
+ */
+export function wrapWithLayouts(PageComponent, layoutChain) {
+  if (!layoutChain || layoutChain.length === 0) return PageComponent;
+  // Layout zincirini içten dışa sarar: page → innerLayout → ... → rootLayout
+  let Wrapped = PageComponent;
+  for (let i = layoutChain.length - 1; i >= 0; i--) {
+    const { ComponentFn } = layoutChain[i];
+    const Inner = Wrapped;
+    Wrapped = function LayoutWrapper(props) {
+      // children olarak Inner bileşenini ilet
+      return ComponentFn({ ...props, children: Inner(props) });
+    };
+    Wrapped.displayName = `Layout(${ComponentFn.name || '?'})`;
+  }
+  return Wrapped;
+}
+// ─── SSR: layout'larla render ─────────────────────────────────────────────────
+/**
+ * Bir sayfayı layout zinciriyle SSR render et.
+ *
+ * @param {Function}  PageComponent
+ * @param {object}    [props={}]
+ * @param {string}    [layoutName]     – layout adı; yoksa pageMeta.layout veya 'default'
+ * @returns {string}  HTML string
+ */
+export function renderWithLayouts(PageComponent, props = {}, layoutName = null) {
+  // Sayfa meta'sından layout adını belirle
+  const metaLayout = PageComponent.pageMeta?.layout
+    ?? PageComponent.__clarity_page_meta__?.layout
+    ?? null;
+  const finalLayout = layoutName ?? metaLayout ?? 'default';
+  const chain = buildLayoutChain(finalLayout);
+  const Wrapped = wrapWithLayouts(PageComponent, chain);
+  return renderToString(Wrapped, { props });
+}
+// ─── Dosya sistemi layout tarayıcı ───────────────────────────────────────────
+/**
+ * `pages/` dizin yapısını tarayıp _layout.js dosyalarını bulur,
+ * otomatik olarak defineLayout() ile kaydeder.
+ *
+ * File-router ve SSG pipeline'da çağrılır.
+ *
+ * @param {string}  pagesDir   – Mutlak yol
+ * @param {string}  [rootName='default']
+ * @returns {Promise<string[]>}  Kaydedilen layout adları
+ */
+export async function scanAndRegisterLayouts(pagesDir, rootName = 'default') {
+  const { readdir, stat }  = await import('node:fs/promises');
+  const { existsSync }     = await import('node:fs');
+  const { join, relative, dirname } = await import('node:path');
+  const { pathToFileURL }  = await import('node:url');
+  const registered = [];
+  async function scan(dir, parentName) {
+    if (!existsSync(dir)) return;
+    const entries = await readdir(dir).catch(() => []);
+    // _layout.js bu dizinde var mı?
+    const layoutFile = entries.find(e => e === '_layout.js' || e === '_layout.mjs');
+    if (layoutFile) {
+      const fullPath  = join(dir, layoutFile);
+      const relPath   = relative(pagesDir, dir) || '.';
+      const layoutName = relPath === '.' ? rootName : relPath.replace(/\\/g, '/');
+      try {
+        const mod = await import(pathToFileURL(fullPath).href + `?t=${Date.now()}`);
+        const ComponentFn = mod.default;
+        if (typeof ComponentFn === 'function') {
+          defineLayout(layoutName, ComponentFn, { parent: parentName !== layoutName ? parentName : null });
+          registered.push(layoutName);
+          console.log(`[clarity/layout] Layout kaydedildi: '${layoutName}' (parent: ${parentName ?? 'none'})`);
+        }
+      } catch (err) {
+        console.warn(`[clarity/layout] Layout yüklenemedi (${fullPath}): ${err.message}`);
+      }
+      // Alt dizinleri bu layout'u parent olarak kullanarak tara
+      for (const entry of entries) {
+        const fullEntry = join(dir, entry);
+        const info = await stat(fullEntry).catch(() => null);
+        if (info?.isDirectory()) {
+          await scan(fullEntry, layoutName);
+        }
+      }
+    } else {
+      // Bu dizinde layout yok — alt dizinleri parent ile tara
+      for (const entry of entries) {
+        const fullEntry = join(dir, entry);
+        const info = await stat(fullEntry).catch(() => null);
+        if (info?.isDirectory()) {
+          await scan(fullEntry, parentName);
+        }
+      }
+    }
+  }
+  await scan(pagesDir, null);
+  return registered;
+}
+// ─── Client-side: layout route değişimlerinde uygula ─────────────────────────
+/**
+ * Client router ile entegrasyon — route değiştiğinde layout'u güncelle.
+ * `hydrateRoot` ve router `navigate` ile birlikte çalışır.
+ *
+ * @param {object} opts
+ * @param {HTMLElement}  opts.container   – Layout wrapper DOM node
+ * @param {Function}     opts.getPage     – (path: string) => { ComponentFn, layoutName }
+ */
+export function initLayoutRouter(opts = {}) {
+  const { container, getPage } = opts;
+  if (typeof window === 'undefined') return;
+  function handleRouteChange() {
+    const path = window.location.pathname;
+    const page = getPage(path);
+    if (!page) return;
+    const { ComponentFn, layoutName } = page;
+    const chain = buildLayoutChain(layoutName ?? 'default');
+    const Wrapped = wrapWithLayouts(ComponentFn, chain);
+    // Container'ı temizle ve yeniden render et
+    if (container) {
+      // Clarity runtime ile hydrate
+      import('./hydrate.js').then(({ hydrateRoot }) => {
+        hydrateRoot(Wrapped, container, {});
+      }).catch(() => {
+        // Fallback: innerHTML (SSR olmadan)
+        const html = renderWithLayouts(ComponentFn, {}, layoutName);
+        container.innerHTML = html;
+      });
+    }
+  }
+  window.addEventListener('popstate', handleRouteChange);
+  window.addEventListener('clarity:navigate', handleRouteChange);
+  return {
+    destroy: () => {
+      window.removeEventListener('popstate', handleRouteChange);
+      window.removeEventListener('clarity:navigate', handleRouteChange);
+    },
+  };
+}
+// ─── Built-in layout bileşenleri ─────────────────────────────────────────────
+/**
+ * Boş layout — sadece children render eder, ek sarmalama yok.
+ * `layout: 'none'` veya doğrudan kullananlar için.
+ */
+export function BlankLayout({ children }) {
+  return children;
+}
+/**
+ * Gerektiğinde kullanılabilecek basit HTML shell layout.
+ * SSR root layout olarak kullanılabilir.
+ *
+ * @param {object} props
+ * @param {*}     props.children
+ * @param {string} [props.lang='tr']
+ * @param {string} [props.title]
+ * @param {string} [props.bodyClass]
+ */
+export function HTMLShellLayout({ children, lang = 'tr', title = '', bodyClass = '' }) {
+  // Bu bileşen SSR ortamında kullanılır — string tabanlı çıktı için basit tag üretimi
+  if (typeof document === 'undefined') {
+    // SSR ortam
+    return {
+      __clarity_html_shell__: true,
+      lang, title, bodyClass,
+      content: children,
+    };
+  }
+  // Client: sadece children
+  return children;
+}