@ozsarman/clarityjs 0.6.0

package/src/image.js

@@ -0,0 +1,352 @@
+/**
+ * Clarity.js — Image Optimization
+ *
+ * next/image / @nuxt/image eşdeğeri.
+ * Responsive srcset, lazy loading, blur placeholder, CLS önleme, WebP/AVIF.
+ *
+ * ── Clarity şablonunda kullanım ───────────────────────────────────────────────
+ *
+ *   import { ClarityImage } from '@ozsarman/clarityjs/image'
+ *
+ *   component Hero() {
+ *     render {
+ *       { ClarityImage({
+ *           src:     '/images/hero.jpg',
+ *           alt:     'Hero görseli',
+ *           width:   1200,
+ *           height:  600,
+ *           priority: true,       // LCP görüntüsü — hemen yükle
+ *           sizes:   '100vw',
+ *       }) }
+ *
+ *       { ClarityImage({
+ *           src:    '/images/avatar.jpg',
+ *           alt:    'Profil fotoğrafı',
+ *           width:  80,
+ *           height: 80,
+ *           quality: 80,
+ *           placeholder: 'blur',
+ *           blurDataURL: 'data:image/jpeg;base64,...',
+ *       }) }
+ *     }
+ *   }
+ *
+ * ── Vite plugin entegrasyonu (otomatik) ──────────────────────────────────────
+ *
+ *   clarityPlugin({ imageOptimization: true })
+ *   // Build sırasında: görüntüleri WebP'ye çevirir, birden fazla boyut üretir
+ *   // Dev: orijinal görüntüyü döndürür
+ *
+ * ── Loader API (özel CDN) ─────────────────────────────────────────────────────
+ *
+ *   import { setImageLoader } from '@ozsarman/clarityjs/image'
+ *
+ *   setImageLoader(({ src, width, quality }) =>
+ *     `https://cdn.example.com/${src}?w=${width}&q=${quality}&fmt=webp`
+ *   );
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+// ─── Varsayılan görüntü boyutları (responsive breakpoints) ───────────────────
+
+const DEFAULT_SIZES = [16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+const DEVICE_SIZES  = [640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+const IMAGE_SIZES   = [16, 32, 48, 64, 96, 128, 256, 384];
+
+// ─── Loader ───────────────────────────────────────────────────────────────────
+
+let _loader = null;
+
+/**
+ * Özel görüntü URL oluşturucu tanımla (CDN entegrasyonu için).
+ *
+ * @param {Function} loaderFn  – ({ src, width, quality, format }) => string
+ */
+export function setImageLoader(loaderFn) {
+  _loader = loaderFn;
+}
+
+function _buildUrl(src, width, quality = 75, format = 'webp') {
+  if (_loader) return _loader({ src, width, quality, format });
+
+  // Varsayılan: Clarity image endpoint (geliştirme sunucusu + production)
+  if (src.startsWith('http://') || src.startsWith('https://')) {
+    // Harici URL — optimize edilemez, doğrudan döndür
+    return src;
+  }
+  return `/_clarity/image?url=${encodeURIComponent(src)}&w=${width}&q=${quality}&fmt=${format}`;
+}
+
+// ─── ClarityImage runtime component ──────────────────────────────────────────
+
+/**
+ * Optimize edilmiş görüntü elementi oluştur.
+ *
+ * @param {object} props
+ * @param {string}   props.src           – görüntü yolu (zorunlu)
+ * @param {string}   props.alt           – erişilebilirlik metni (zorunlu)
+ * @param {number}   props.width         – görüntü genişliği px (zorunlu — CLS önleme)
+ * @param {number}   props.height        – görüntü yüksekliği px (zorunlu — CLS önleme)
+ * @param {string}   [props.sizes]       – CSS sizes değeri (örn: '(max-width: 768px) 100vw, 50vw')
+ * @param {number}   [props.quality=75]  – sıkıştırma kalitesi 1-100
+ * @param {boolean}  [props.priority]    – LCP görüntüsü: preload ekle, lazy yükleme kapat
+ * @param {string}   [props.placeholder] – 'blur' | 'empty' (default: 'empty')
+ * @param {string}   [props.blurDataURL] – base64 blur placeholder
+ * @param {string}   [props.className]   – CSS sınıfı
+ * @param {string}   [props.style]       – inline stil
+ * @param {string}   [props.objectFit]   – CSS object-fit: 'cover' | 'contain' | ...
+ * @param {string}   [props.objectPosition] – CSS object-position
+ * @param {Function} [props.onLoad]      – yükleme tamamlandığında callback
+ * @param {Function} [props.onError]     – hata durumunda callback
+ * @returns {HTMLElement}
+ */
+export function ClarityImage(props = {}) {
+  const {
+    src,
+    alt            = '',
+    width,
+    height,
+    sizes          = '100vw',
+    quality        = 75,
+    priority       = false,
+    placeholder    = 'empty',
+    blurDataURL    = null,
+    className      = '',
+    style          = '',
+    objectFit      = null,
+    objectPosition = null,
+    onLoad         = null,
+    onError        = null,
+  } = props;
+
+  if (!src) throw new Error('[clarity/image] ClarityImage: src zorunludur');
+
+  // Wrapper div — CLS önlemek için aspect ratio tutar
+  const wrapper = typeof document !== 'undefined'
+    ? _createClientImage(props)
+    : null;
+
+  return wrapper || _createSSRImage(props);
+}
+
+function _createSSRImage({ src, alt, width, height, sizes, quality, priority, placeholder, blurDataURL, className, style, objectFit, objectPosition }) {
+  // SSR: <img> tag HTML string olarak üretilir — ssr.js tarafından kullanılır
+  // Bu fonksiyon doğrudan HTMLElement döndürür — server ortamında string tabanlı render
+
+  // srcset üret
+  const relevantSizes = _getRelevantSizes(width);
+  const srcset = relevantSizes
+    .map(w => `${_buildUrl(src, w, quality)} ${w}w`)
+    .join(', ');
+
+  // Placeholder stili
+  let imgStyle = '';
+  if (objectFit)      imgStyle += `object-fit:${objectFit};`;
+  if (objectPosition) imgStyle += `object-position:${objectPosition};`;
+  if (style)          imgStyle += style;
+
+  // Blur placeholder
+  if (placeholder === 'blur' && blurDataURL) {
+    imgStyle += `background-image:url(${blurDataURL});background-size:cover;`;
+  }
+
+  const loading = priority ? 'eager' : 'lazy';
+  const decoding = priority ? 'sync' : 'async';
+  const fetchpriority = priority ? ' fetchpriority="high"' : '';
+
+  // SSR için basit string döndür (ssr.js h() fonksiyonuyla entegre olur)
+  return {
+    __clarityImageSSR: true,
+    html: `<img
+      src="${_buildUrl(src, width ?? 1200, quality)}"
+      srcset="${srcset}"
+      sizes="${sizes}"
+      alt="${_escAttr(alt)}"
+      width="${width || ''}"
+      height="${height || ''}"
+      loading="${loading}"
+      decoding="${decoding}"${fetchpriority}
+      ${className ? `class="${_escAttr(className)}"` : ''}
+      ${imgStyle ? `style="${_escAttr(imgStyle)}"` : ''}
+    />`,
+  };
+}
+
+function _createClientImage({ src, alt, width, height, sizes, quality, priority, placeholder, blurDataURL, className, style, objectFit, objectPosition, onLoad, onError }) {
+  const img = document.createElement('img');
+
+  // Zorunlu attr
+  img.alt = alt;
+  if (width)  img.width  = width;
+  if (height) img.height = height;
+
+  // Stil
+  const styles = [];
+  if (objectFit)      styles.push(`object-fit:${objectFit}`);
+  if (objectPosition) styles.push(`object-position:${objectPosition}`);
+  if (style)          styles.push(style);
+  if (styles.length)  img.style.cssText = styles.join(';');
+
+  if (className) img.className = className;
+
+  // Blur placeholder
+  if (placeholder === 'blur' && blurDataURL) {
+    img.style.backgroundImage = `url(${blurDataURL})`;
+    img.style.backgroundSize  = 'cover';
+    img.addEventListener('load', () => {
+      img.style.backgroundImage = '';
+    }, { once: true });
+  }
+
+  // srcset
+  const relevantSizes = _getRelevantSizes(width);
+  img.srcset  = relevantSizes.map(w => `${_buildUrl(src, w, quality)} ${w}w`).join(', ');
+  img.sizes   = sizes;
+  img.src     = _buildUrl(src, width ?? 1200, quality);
+  img.loading = priority ? 'eager' : 'lazy';
+  img.decoding = priority ? 'sync' : 'async';
+
+  if (priority) {
+    img.setAttribute('fetchpriority', 'high');
+    // Preload link ekle
+    _injectPreload(src, sizes, relevantSizes, quality);
+  }
+
+  if (onLoad)  img.addEventListener('load', onLoad);
+  if (onError) img.addEventListener('error', onError);
+
+  return img;
+}
+
+// ─── Vite / Dev Server: görüntü endpoint'i ───────────────────────────────────
+
+/**
+ * Express/Vite için görüntü optimizasyon endpoint'i.
+ * Dev server'da `/_clarity/image` isteğini karşılar.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.sharp=false]  – sharp kütüphanesi varsa kullan (prod)
+ * @returns {Function}  Express middleware
+ */
+export function createImageMiddleware(opts = {}) {
+  const { sharp: useSharp = false } = opts;
+
+  return async function imageMiddleware(req, res, next) {
+    if (!req.path.startsWith('/_clarity/image')) return next();
+
+    const { url, w, q = '75', fmt = 'webp' } = req.query;
+    if (!url) return res.status(400).json({ error: 'url parametresi gerekli' });
+
+    const width   = parseInt(w, 10) || null;
+    const quality = Math.min(100, Math.max(1, parseInt(q, 10)));
+
+    try {
+      // Dev modda: orijinal görüntüyü döndür (optimizasyon yok)
+      if (!useSharp) {
+        const { createReadStream, existsSync } = await import('node:fs');
+        const { resolve } = await import('node:path');
+        const filePath = resolve('.' + decodeURIComponent(url));
+        if (!existsSync(filePath)) return res.status(404).end();
+        res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+        return createReadStream(filePath).pipe(res);
+      }
+
+      // Production: sharp ile WebP dönüşümü
+      const sharp = await import('sharp');
+      const { resolve } = await import('node:path');
+      const filePath = resolve('.' + decodeURIComponent(url));
+
+      let pipeline = sharp.default(filePath);
+      if (width) pipeline = pipeline.resize(width);
+
+      const buffer = await pipeline[fmt === 'avif' ? 'avif' : 'webp']({ quality }).toBuffer();
+      res.setHeader('Content-Type', `image/${fmt}`);
+      res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+      res.send(buffer);
+
+    } catch (err) {
+      console.error('[clarity/image] middleware hata:', err.message);
+      next(err);
+    }
+  };
+}
+
+// ─── Build-time görüntü optimizasyonu (Vite plugin hook) ─────────────────────
+
+/**
+ * Vite plugin için görüntü optimizasyon hook'u.
+ * vite-plugin.js içinde `generateBundle` hook'undan çağrılır.
+ *
+ * @param {string}  publicDir  – public/ dizini
+ * @param {string}  outDir     – dist/ dizini
+ * @param {object}  [opts]
+ */
+export async function optimizeImages(publicDir, outDir, opts = {}) {
+  const { quality = 80, formats = ['webp'], sizes = DEVICE_SIZES } = opts;
+
+  let sharp;
+  try {
+    sharp = (await import('sharp')).default;
+  } catch {
+    console.warn('[clarity/image] sharp bulunamadı — görüntü optimizasyonu atlandı. npm install sharp');
+    return;
+  }
+
+  const { readdir, mkdir: mkdirFn, stat: statFn } = await import('node:fs/promises');
+  const { join: joinFn, extname: extnFn }          = await import('node:path');
+  const IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.tiff']);
+
+  async function processDir(dir, outBase) {
+    const entries = await readdir(dir).catch(() => []);
+    for (const entry of entries) {
+      const srcFull  = joinFn(dir, entry);
+      const info     = await statFn(srcFull).catch(() => null);
+      if (!info) continue;
+
+      if (info.isDirectory()) {
+        await processDir(srcFull, joinFn(outBase, entry));
+        continue;
+      }
+
+      const ext = extnFn(entry).toLowerCase();
+      if (!IMAGE_EXTS.has(ext)) continue;
+
+      await mkdirFn(joinFn(outBase, '_clarity_images'), { recursive: true });
+
+      for (const fmt of formats) {
+        for (const w of sizes) {
+          const outName = `${entry.replace(ext, '')}_${w}.${fmt}`;
+          const outFull = joinFn(outBase, '_clarity_images', outName);
+          try {
+            await sharp(srcFull).resize(w)[fmt]({ quality }).toFile(outFull);
+          } catch { /* skip */ }
+        }
+      }
+    }
+  }
+
+  await processDir(publicDir, outDir);
+  console.log('[clarity/image] ✅ Görüntü optimizasyonu tamamlandı');
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function _getRelevantSizes(width) {
+  const max = width ? width * 2 : 3840;
+  return DEFAULT_SIZES.filter(s => s <= max);
+}
+
+function _injectPreload(src, sizes, widths, quality) {
+  if (typeof document === 'undefined') return;
+  const link = document.createElement('link');
+  link.rel         = 'preload';
+  link.as          = 'image';
+  link.imageSrcset = widths.map(w => `${_buildUrl(src, w, quality)} ${w}w`).join(', ');
+  link.imageSizes  = sizes;
+  document.head.appendChild(link);
+}
+
+function _escAttr(str) {
+  return String(str ?? '').replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}

package/src/index.js

@@ -0,0 +1,193 @@
+/**
+ * Clarity.js — Public API
+ *
+ * The full compiler pipeline:
+ *   source (.clarity) → tokens → AST → JavaScript
+ *
+ * Author: Claude (Anthropic)
+ */
+
+import { Lexer, tokenize }    from './lexer.js';
+import { Parser, parse }      from './parser.js';
+import { CodeGenerator, generate } from './codegen.js';
+import { TypeGenerator, generateTypes } from './typegen.js';
+
+export { Lexer, tokenize, T } from './lexer.js';
+export { Parser, parse }      from './parser.js';
+export { CodeGenerator, generate } from './codegen.js';
+export { TypeGenerator, generateTypes } from './typegen.js';
+
+// Router — re-exported for convenience (also importable from '@ozsarman/clarityjs/router')
+export {
+  navigate, navigateReplace, back, forward,
+  currentPath, currentQuery, routeParams,
+  matchRoute, Route, Link, Switch, Outlet,
+  beforeEnter, removeGuard,
+  createRouter, setServerPath, createSSRMiddleware, renderWithPath,
+  prefetchRoute, registerRouteChunk, injectModulepreloads,
+  useViewTransition,
+} from './router.js';
+
+// File-based pages router — consumes the Vite `scanPages` virtual module
+export {
+  filePathToRoutePattern, routeScore, sortRoutes, selectRoute,
+  buildRouteTable, createPagesRouter,
+} from './pages-router.js';
+
+// Reactivity extras
+export { reactive, createContext, useContext, _pushContext, _popContext,
+         _withComponent, beforeMount, onMount, onCleanup, onUpdate,
+         createRef, useRef } from './runtime.js';
+
+// AI Agent SDK — audit log + permission enforcement
+export { getAIAuditLog, clearAIAuditLog, onAIAction,
+         _aiAuditRecord, _setAIActionContext, _protectedSignal,
+         ClarityAIForbiddenError, _aiThrowForbidden } from './runtime.js';
+
+// Error boundary
+export { ErrorBoundary } from './runtime.js';
+
+// Portal — render children outside the component tree
+export { createPortal } from './runtime.js';
+
+// Suspense — show fallback while lazy children load
+export { Suspense } from './runtime.js';
+
+// SSR — server-side rendering utilities
+export { renderToString, renderToStringAsync, renderToDocument, renderToStream, escapeHTML, escapeAttr, SSRElement } from './ssr.js';
+
+// Hydration — client-side adoption of server-rendered HTML
+export { hydrateRoot, isHydrated, getSSRData } from './hydrate.js';
+
+// Component-level SSR data fetching — server fetch + serialize + hydrate
+export { useServerData, renderWithServerData, renderToDocumentWithData } from './server-data.js';
+
+// Game / animation loop — requestAnimationFrame with fixed/variable timestep
+export { createGameLoop, useRaf } from './game-loop.js';
+
+// Async state — TanStack Query / SWR style reactive data fetching
+export {
+  createQuery, useFetch, createMutation,
+  invalidateQuery, prefetchQuery, clearQueryCache, getCacheEntry,
+} from './async-state.js';
+
+// Transitions — Vue-compatible enter/leave animations + FLIP list animations
+export { Transition, TransitionGroup, useTransition, injectTransitionStyles } from './transitions.js';
+
+// Scoped CSS — <style scoped> processor for .clarity files
+export { extractStyles, scopeCSS, injectScopeAttr, collectStyles, hashId, cssModules } from './scoped-css.js';
+
+// Global Store — Pinia/Zustand style cross-component reactive state
+export { createStore, getStoreRegistry, resetAllStores, disposeAllStores } from './store.js';
+
+// Head / Meta management — reactive <title>, <meta>, <og:*>, <link rel="canonical">
+export { createHead, getHead, useHead, renderHead, _setHeadLifecycleHook } from './head.js';
+
+// Image Optimization — next/image eşdeğeri: responsive srcset, lazy, blur placeholder, WebP/AVIF
+export { ClarityImage, setImageLoader, createImageMiddleware, optimizeImages } from './image.js';
+
+// Font Optimization — next/font eşdeğeri: Google Fonts self-hosting, lokal font, sıfır layout shift
+export { GoogleFont, LocalFont, SystemFonts, renderFontHead, resetFontRegistry, getRegisteredFonts, downloadGoogleFonts, optimizeFonts, applyFontDisplay } from './font.js';
+
+// SSG — Static Site Generation: getStaticProps/getStaticPaths, build-time HTML
+export { generateStaticSite, fetchStaticProps, fetchStaticPaths, createSSGContext } from './ssg.js';
+
+// ISR — Incremental Static Regeneration: stale-while-revalidate, on-demand revalidation
+export { revalidatePath, revalidateTag, createISRMiddleware, startISRScheduler } from './isr.js';
+
+// Islands Architecture — selective hydration, zero JS server components
+export { createIsland, hydrateIslands, defineServerComponent, isServerComponent, renderPageWithIslands } from './islands.js';
+
+// Layout System — nested layouts, definePageMeta, dosya tabanlı _layout.js konvansiyonu
+export { defineLayout, getLayout, resetLayoutRegistry, definePageMeta, buildLayoutChain, wrapWithLayouts, renderWithLayouts, scanAndRegisterLayouts, initLayoutRouter, BlankLayout, HTMLShellLayout } from './layout.js';
+
+// Formatter & Linter — clarity format / clarity lint
+export { formatCode, formatFile, lintCode, lintFile, processDirectory, formatLintReport, loadConfig, DEFAULT_FORMAT_OPTIONS, DEFAULT_LINT_RULES } from './linter.js';
+
+// File-based routing conventions — loading.js, error.js, not-found.js
+export {
+  registerConventions, resolveConventions, resetConventionRegistry,
+  wrapWithConventions, scanConventions,
+  resolveNotFound,
+  DefaultNotFound, DefaultLoading,
+  createFileRouter, clarityConventionsPlugin,
+  LOADING_FILE, ERROR_FILE, NOT_FOUND_FILE, LAYOUT_FILE, SPECIAL_FILES,
+} from './file-conventions.js';
+
+// TypeScript Language Service Plugin + Volar integration
+export { init, createClarityTypeChecker, createClarityVolarPlugin, TSCONFIG_PRESET, AMBIENT_DECLARATIONS } from './ts-plugin.js';
+
+// Edge Runtime — Cloudflare Workers, Deno Deploy, Vercel Edge, Bun support
+export {
+  detectEdgeRuntime, isEdgeRuntime,
+  normalizeRequest,
+  htmlResponse, jsonResponse, redirectResponse, streamResponse,
+  renderEdge,
+  createEdgeHandler, adaptFetchHandler,
+  createEdgeCache,
+  getGeo, getEnv,
+  randomId, hmacSign,
+} from './edge.js';
+
+// Server Actions — type-safe client→server RPC, "use server" directive support
+export {
+  defineServerAction, listServerActions,
+  createActionRouter,
+  createServerClient,
+  useServerAction,
+  registerServerModule,
+  composeActionMiddleware, logActionMiddleware, createAuthMiddleware,
+} from './server-actions.js';
+
+// Devtools — in-page overlay (Shadow DOM, no external deps)
+export { initDevtools,
+         _devRecordSignalUpdate, _devRenderStart, _devRenderEnd, _devClearPerfData } from './devtools.js';
+
+// Error Overlay — dev mode compiler + runtime error UI (Shadow DOM)
+export { initErrorOverlay, _overlayShowError, _overlayDismiss } from './error-overlay.js';
+
+// i18n — Internationalization with RTL support
+export { createI18n, useI18n, t, getLocale, getIsRTL,
+         isRTLLocale, RTL_LOCALES, applyDir, BiDiWrapper } from './i18n.js';
+
+/**
+ * Full compilation pipeline: .clarity source → JavaScript string
+ *
+ * @param {string} source   - Clarity source code
+ * @param {object} options  - Compilation options
+ * @returns {{ code: string, ast: object, tokens: array }}
+ */
+export function compile(source, options = {}) {
+  const filename = options.filename ?? '<anonymous>';
+
+  // Step 1: Lex
+  const lexer  = new Lexer(source, filename);
+  const tokens = lexer.tokenize();
+
+  // Step 2: Parse
+  const parser = new Parser(tokens, source);
+  const ast    = parser.parse();
+
+  // Step 3: Generate
+  const codegen = new CodeGenerator({
+    ...options,
+    sourceFile:    filename,
+    outputFile:    filename.replace(/\.clarity$/, '.js'),
+    sourceContent: source,
+  });
+  const { code, map } = codegen.generate(ast);
+
+  // Optionally generate TypeScript declarations
+  const dts = options.types
+    ? new TypeGenerator({ runtimePath: options.runtimePath }).generate(ast, { filename })
+    : null;
+
+  return { code, map, dts, ast, tokens };
+}
+
+/**
+ * Quick compile — just returns the JavaScript string
+ */
+export function compileToJS(source, options = {}) {
+  return compile(source, options).code;
+}