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/font.js ADDED Viewed

@@ -0,0 +1,513 @@
+/**
+ * Clarity.js — Font Optimization
+ *
+ * next/font eşdeğeri.
+ * Google Fonts otomatik self-hosting, lokal font preload, sıfır layout shift,
+ * font-display:swap otomasyonu, subset & unicode-range desteği.
+ *
+ * ── Google Fonts kullanımı (.clarity şablonunda) ─────────────────────────────
+ *
+ *   import { GoogleFont } from '@ozsarman/clarityjs/font'
+ *
+ *   const inter = GoogleFont('Inter', {
+ *     weights:  [400, 500, 700],
+ *     subsets:  ['latin', 'latin-ext'],
+ *     display:  'swap',      // varsayılan
+ *     variable: '--font-inter',
+ *   });
+ *
+ *   component App() {
+ *     render {
+ *       <div class={inter.className}>
+ *         <h1 style={`font-family: ${inter.style.fontFamily}`}>Başlık</h1>
+ *       </div>
+ *     }
+ *   }
+ *
+ * ── Lokal font kullanımı ──────────────────────────────────────────────────────
+ *
+ *   import { LocalFont } from '@ozsarman/clarityjs/font'
+ *
+ *   const myFont = LocalFont({
+ *     src: [
+ *       { path: '/fonts/MyFont-Regular.woff2', weight: '400', style: 'normal' },
+ *       { path: '/fonts/MyFont-Bold.woff2',    weight: '700', style: 'normal' },
+ *     ],
+ *     variable: '--font-my',
+ *     display:  'swap',
+ *     preload:  true,
+ *   });
+ *
+ * ── CSS Variable kullanımı ────────────────────────────────────────────────────
+ *
+ *   // CSS'te:
+ *   body { font-family: var(--font-inter); }
+ *
+ *   // Component'te:
+ *   <html class={`${inter.variable} ${mono.variable}`}>
+ *
+ * ── SSR / Head entegrasyonu ───────────────────────────────────────────────────
+ *
+ *   import { renderFontHead } from '@ozsarman/clarityjs/font'
+ *
+ *   // SSR layout'unda:
+ *   const headHTML = renderFontHead();  // <link rel="preload"> + <style> etiketleri
+ *
+ * ── Vite plugin entegrasyonu (otomatik) ──────────────────────────────────────
+ *
+ *   clarityPlugin({ fontOptimization: true })
+ *   // Build sırasında Google Fonts'u local'e indirir, CSS'i inline eder
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+// ─── Kayıtlı fontlar (SSR head injection için) ────────────────────────────────
+const _registeredFonts = [];
+// ─── Unique class name üretici ────────────────────────────────────────────────
+let _fontCounter = 0;
+function _uid() { return `clarity-font-${++_fontCounter}`; }
+// ─── Google Fonts ─────────────────────────────────────────────────────────────
+/**
+ * Google Fonts entegrasyonu — next/font/google eşdeğeri.
+ * Runtime'da preconnect + stylesheet URL üretir.
+ * Build sırasında (Vite plugin ile) fontları self-host eder.
+ *
+ * @param {string}  family   – Font ailesi adı (örn: 'Inter', 'Roboto Mono')
+ * @param {object}  opts
+ * @param {number[]}  [opts.weights=[400]]  – Yüklenecek font ağırlıkları
+ * @param {string[]}  [opts.subsets=['latin']]  – unicode subset'leri
+ * @param {string}    [opts.display='swap']  – CSS font-display değeri
+ * @param {boolean}   [opts.preload=true]    – <link rel="preload"> ekle
+ * @param {string[]}  [opts.axes]           – Variable font axis'leri (örn: ['wght'])
+ * @param {string}    [opts.variable]       – CSS custom property adı (örn: '--font-inter')
+ * @param {boolean}   [opts.italic=false]   – italic varyantları da yükle
+ * @returns {FontObject}
+ */
+export function GoogleFont(family, opts = {}) {
+  const {
+    weights  = [400],
+    subsets  = ['latin'],
+    display  = 'swap',
+    preload  = true,
+    axes     = null,
+    variable = null,
+    italic   = false,
+  } = opts;
+  const className   = _uid();
+  const fontFamily  = `'${family}', sans-serif`;
+  const cssVariable = variable ?? `--clarity-font-${family.toLowerCase().replace(/\s+/g, '-')}`;
+  // Google Fonts URL oluştur (v2 API)
+  const gFamilyStr = _buildGoogleFamilyStr(family, weights, italic, axes);
+  const gSubsets   = subsets.join(',');
+  const googleUrl  = `https://fonts.googleapis.com/css2?family=${gFamilyStr}&subset=${gSubsets}&display=${display}`;
+  const fontObj = {
+    className,
+    variable: cssVariable,
+    style: { fontFamily },
+    // SSR için gerekli bilgiler
+    __clarity_font__: true,
+    __type__:         'google',
+    family,
+    googleUrl,
+    preload,
+    display,
+    weights,
+    subsets,
+    cssVariable,
+  };
+  _registeredFonts.push(fontObj);
+  // Client-side: DOM'a inject et (SSR değilse)
+  if (typeof document !== 'undefined') {
+    _injectGoogleFont(fontObj);
+  }
+  return fontObj;
+}
+function _buildGoogleFamilyStr(family, weights, italic, axes) {
+  const name = family.replace(/ /g, '+');
+  if (axes) {
+    // Variable font — axis değerleri
+    const axisStr = axes.join(',');
+    const wghtRange = `${Math.min(...weights)}..${Math.max(...weights)}`;
+    return `${name}:${axisStr}@${wghtRange}`;
+  }
+  if (italic) {
+    const parts = weights.flatMap(w => [`0,${w}`, `1,${w}`]).join(';');
+    return `${name}:ital,wght@${parts}`;
+  }
+  const wStr = weights.join(';');
+  return `${name}:wght@${wStr}`;
+}
+function _injectGoogleFont(fontObj) {
+  // Preconnect
+  _injectLinkOnce('preconnect', 'https://fonts.googleapis.com');
+  _injectLinkOnce('preconnect', 'https://fonts.gstatic.com', { crossorigin: true });
+  // Stylesheet
+  _injectLinkOnce('stylesheet', fontObj.googleUrl, { id: `gf-${fontObj.className}` });
+  // CSS variable → className rule
+  _injectFontClassStyle(fontObj.className, fontObj.cssVariable, fontObj.style.fontFamily);
+}
+// ─── Local Fonts ──────────────────────────────────────────────────────────────
+/**
+ * Lokal font tanımı — next/font/local eşdeğeri.
+ * Sistemde kayıtlı veya /public/fonts/ altındaki fontlar için @font-face üretir.
+ *
+ * @param {object}  opts
+ * @param {Array<{path:string, weight?:string, style?:string, format?:string}>} opts.src
+ * @param {string}  [opts.variable]    – CSS custom property adı
+ * @param {string}  [opts.display='swap']
+ * @param {boolean} [opts.preload=true]
+ * @param {string}  [opts.family]     – Belirtilmezse dosya adından çıkarılır
+ * @param {string}  [opts.unicodeRange]
+ * @returns {FontObject}
+ */
+export function LocalFont(opts = {}) {
+  const {
+    src,
+    variable  = null,
+    display   = 'swap',
+    preload   = true,
+    family    = null,
+    unicodeRange = null,
+  } = opts;
+  if (!src || !Array.isArray(src) || src.length === 0) {
+    throw new Error('[clarity/font] LocalFont: src dizisi zorunludur');
+  }
+  const className   = _uid();
+  const fontFamily  = family ?? _inferFamilyFromPath(src[0].path);
+  const cssVariable = variable ?? `--clarity-font-${fontFamily.toLowerCase().replace(/\s+/g, '-')}`;
+  const fontFaceCSS = src.map(({ path, weight = '400', style: fStyle = 'normal', format }) =>
+    _buildFontFaceRule(fontFamily, path, weight, fStyle, display, unicodeRange, format)
+  ).join('\n');
+  const fontObj = {
+    className,
+    variable: cssVariable,
+    style: { fontFamily: `'${fontFamily}', sans-serif` },
+    __clarity_font__: true,
+    __type__:         'local',
+    family:           fontFamily,
+    src,
+    preload,
+    display,
+    fontFaceCSS,
+    cssVariable,
+  };
+  _registeredFonts.push(fontObj);
+  if (typeof document !== 'undefined') {
+    _injectLocalFont(fontObj);
+  }
+  return fontObj;
+}
+function _inferFamilyFromPath(path) {
+  const name = path.split('/').pop().replace(/\.(woff2?|ttf|otf|eot)$/i, '');
+  return name.replace(/[-_](Regular|Bold|Light|Medium|SemiBold|Italic|Black)/i, '').trim() || 'CustomFont';
+}
+function _buildFontFaceRule(family, path, weight, style, display, unicodeRange, format) {
+  const formatHint = format
+    ? `format('${format}')`
+    : path.endsWith('.woff2') ? "format('woff2')"
+    : path.endsWith('.woff')  ? "format('woff')"
+    : path.endsWith('.ttf')   ? "format('truetype')"
+    : path.endsWith('.otf')   ? "format('opentype')"
+    : '';
+  return `@font-face {
+  font-family: '${family}';
+  src: url('${path}') ${formatHint};
+  font-weight: ${weight};
+  font-style: ${style};
+  font-display: ${display};${unicodeRange ? `\n  unicode-range: ${unicodeRange};` : ''}
+}`;
+}
+function _injectLocalFont(fontObj) {
+  // @font-face kurallarını <style> olarak göm
+  const styleId = `lf-${fontObj.className}`;
+  if (!document.getElementById(styleId)) {
+    const style = document.createElement('style');
+    style.id    = styleId;
+    style.textContent = fontObj.fontFaceCSS;
+    document.head.appendChild(style);
+  }
+  // Preload: sadece woff2 dosyalarını preload et
+  if (fontObj.preload) {
+    for (const { path, format } of fontObj.src) {
+      const isWoff2 = (format === 'woff2') || path.endsWith('.woff2');
+      if (isWoff2) {
+        const link   = document.createElement('link');
+        link.rel     = 'preload';
+        link.as      = 'font';
+        link.href    = path;
+        link.type    = 'font/woff2';
+        link.setAttribute('crossorigin', 'anonymous');
+        document.head.appendChild(link);
+      }
+    }
+  }
+  // className CSS rule
+  _injectFontClassStyle(fontObj.className, fontObj.cssVariable, fontObj.style.fontFamily);
+}
+// ─── SSR: head HTML üret ──────────────────────────────────────────────────────
+/**
+ * Kayıtlı tüm fontlar için SSR <head> HTML'i üret.
+ * `renderToDocument()` içinde veya manuel layout'larda çağrılır.
+ *
+ * @returns {string}  HTML string — <link> + <style> etiketleri
+ */
+export function renderFontHead() {
+  const parts = [];
+  for (const font of _registeredFonts) {
+    if (font.__type__ === 'google') {
+      // Preconnect
+      parts.push(`<link rel="preconnect" href="https://fonts.googleapis.com">`);
+      parts.push(`<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>`);
+      // Stylesheet — preload ilk, sonra stylesheet
+      if (font.preload) {
+        parts.push(`<link rel="preload" as="style" href="${_escAttr(font.googleUrl)}">`);
+      }
+      parts.push(`<link rel="stylesheet" href="${_escAttr(font.googleUrl)}">`);
+    } else if (font.__type__ === 'local') {
+      // @font-face CSS
+      parts.push(`<style id="lf-${font.className}">${font.fontFaceCSS}</style>`);
+      // woff2 preload
+      if (font.preload) {
+        for (const { path, format } of font.src) {
+          const isWoff2 = (format === 'woff2') || path.endsWith('.woff2');
+          if (isWoff2) {
+            parts.push(`<link rel="preload" as="font" type="font/woff2" href="${_escAttr(path)}" crossorigin="anonymous">`);
+          }
+        }
+      }
+    }
+    // CSS variable + className rule
+    parts.push(`<style>.${font.className}{font-family:${font.style.fontFamily};${font.cssVariable}:${font.style.fontFamily}}</style>`);
+  }
+  return parts.join('\n');
+}
+/**
+ * Kayıtlı fontları temizle (SSR arasında state sıfırlama için).
+ */
+export function resetFontRegistry() {
+  _registeredFonts.length = 0;
+  _fontCounter = 0;
+}
+/**
+ * Kayıtlı font listesini döndür (Vite plugin build entegrasyonu için).
+ */
+export function getRegisteredFonts() {
+  return [..._registeredFonts];
+}
+// ─── Build-time: Google Fonts self-hosting ────────────────────────────────────
+/**
+ * Google Fonts CSS'ini indir ve @font-face kurallarını woff2 dosyaları
+ * ile birlikte outDir'e kaydet. Vite plugin `generateBundle` hook'undan çağrılır.
+ *
+ * @param {Array}   fonts     – getRegisteredFonts() çıktısı (sadece google tipi)
+ * @param {string}  outDir    – dist/ dizini
+ * @param {string}  fontsDir  – font dosyaları alt dizini (default: 'fonts')
+ * @returns {Promise<{ css: string, downloaded: number }>}
+ */
+export async function downloadGoogleFonts(fonts, outDir, fontsDir = 'fonts') {
+  const { mkdir, writeFile } = await import('node:fs/promises');
+  const { join, resolve }    = await import('node:path');
+  const { fetch: nodeFetch } = await _getFetch();
+  const outFontsDir = join(resolve(outDir), fontsDir);
+  await mkdir(outFontsDir, { recursive: true });
+  let allCSS      = '';
+  let downloaded  = 0;
+  for (const font of fonts) {
+    if (font.__type__ !== 'google') continue;
+    // Google Fonts CSS'ini çek (woff2 URL'lerini bulmak için)
+    let css;
+    try {
+      const resp = await nodeFetch(font.googleUrl, {
+        headers: { 'User-Agent': 'Mozilla/5.0 (compatible; clarity-js build)' },
+      });
+      css = await resp.text();
+    } catch (err) {
+      console.warn(`[clarity/font] Google Fonts indirilemedi (${font.family}): ${err.message}`);
+      // Fallback: orijinal URL'yi kullan
+      allCSS += `/* ${font.family} — bağlantı hatası, CDN kullanılıyor */\n`;
+      continue;
+    }
+    // @font-face içindeki woff2 URL'lerini bul ve indir
+    const urlRegex = /url\((https:\/\/fonts\.gstatic\.com\/[^)]+\.woff2)\)/g;
+    let match;
+    let localCSS = css;
+    while ((match = urlRegex.exec(css)) !== null) {
+      const remoteUrl = match[1];
+      const fileName  = remoteUrl.split('/').pop().split('?')[0];
+      const localPath = join(outFontsDir, fileName);
+      try {
+        const fontResp = await nodeFetch(remoteUrl);
+        const buffer   = Buffer.from(await fontResp.arrayBuffer());
+        await writeFile(localPath, buffer);
+        localCSS = localCSS.replace(remoteUrl, `/${fontsDir}/${fileName}`);
+        downloaded++;
+      } catch (err) {
+        console.warn(`[clarity/font] Font dosyası indirilemedi (${fileName}): ${err.message}`);
+      }
+    }
+    allCSS += localCSS + '\n';
+  }
+  // Self-hosted CSS dosyasını yaz
+  if (allCSS) {
+    await writeFile(join(resolve(outDir), 'fonts.css'), allCSS, 'utf8');
+    console.log(`[clarity/font] ✅ ${downloaded} font dosyası indirildi → ${fontsDir}/`);
+  }
+  return { css: allCSS, downloaded };
+}
+// ─── Vite plugin entegrasyon hook'u ──────────────────────────────────────────
+/**
+ * Vite plugin'i için font optimization hook'u.
+ * clarityPlugin({ fontOptimization: true }) ile otomatik aktif olur.
+ *
+ * @param {object} opts
+ * @param {string}  opts.outDir
+ * @param {string}  [opts.fontsDir='fonts']
+ */
+export async function optimizeFonts(opts = {}) {
+  const { outDir = 'dist', fontsDir = 'fonts' } = opts;
+  const googleFonts = _registeredFonts.filter(f => f.__type__ === 'google');
+  if (googleFonts.length === 0) return;
+  return downloadGoogleFonts(googleFonts, outDir, fontsDir);
+}
+// ─── Font display utility ─────────────────────────────────────────────────────
+/**
+ * Tüm @font-face kurallarına font-display değerini uygula.
+ * Mevcut bir CSS string'ine uygulanır.
+ *
+ * @param {string} css           – Mevcut @font-face CSS
+ * @param {string} [display='swap']
+ * @returns {string}  Güncellenmiş CSS
+ */
+export function applyFontDisplay(css, display = 'swap') {
+  // Zaten font-display varsa güncelle, yoksa ekle
+  return css.replace(
+    /(@font-face\s*\{[^}]*?)(font-display\s*:[^;]*;)?([^}]*?\})/gs,
+    (match, before, existing, after) => {
+      if (existing) {
+        return `${before}font-display: ${display};${after}`;
+      }
+      return `${before}font-display: ${display};\n  ${after}`;
+    }
+  );
+}
+// ─── Sistem fontları (zero-layout-shift, zero-download) ──────────────────────
+/**
+ * Hazır sistem font stack'leri — indirme yok, layout shift yok.
+ * next/font/local + system-ui stack eşdeğeri.
+ */
+export const SystemFonts = {
+  /** Modern cross-platform sans-serif */
+  sans: {
+    className: 'clarity-font-system-sans',
+    variable:  '--font-system-sans',
+    style: { fontFamily: 'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif' },
+  },
+  /** Sistem mono */
+  mono: {
+    className: 'clarity-font-system-mono',
+    variable:  '--font-system-mono',
+    style: { fontFamily: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace' },
+  },
+  /** Serif */
+  serif: {
+    className: 'clarity-font-system-serif',
+    variable:  '--font-system-serif',
+    style: { fontFamily: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif' },
+  },
+};
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function _injectLinkOnce(rel, href, attrs = {}) {
+  if (typeof document === 'undefined') return;
+  const existing = document.querySelector(`link[rel="${rel}"][href="${href}"]`);
+  if (existing) return;
+  const link = document.createElement('link');
+  link.rel   = rel;
+  link.href  = href;
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === true) link.setAttribute(k, '');
+    else if (k !== 'id' || !v) link.setAttribute(k, v);
+  }
+  if (attrs.id) link.id = attrs.id;
+  document.head.appendChild(link);
+}
+function _injectFontClassStyle(className, cssVar, fontFamily) {
+  if (typeof document === 'undefined') return;
+  const styleId = `cls-${className}`;
+  if (document.getElementById(styleId)) return;
+  const style = document.createElement('style');
+  style.id    = styleId;
+  style.textContent = `.${className}{font-family:${fontFamily};${cssVar}:${fontFamily}}`;
+  document.head.appendChild(style);
+}
+function _escAttr(str) {
+  return String(str ?? '').replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+async function _getFetch() {
+  // Node 18+ global fetch destekler; daha eski sürümlerde node-fetch
+  if (typeof globalThis.fetch === 'function') return { fetch: globalThis.fetch };
+  try {
+    return await import('node-fetch');
+  } catch {
+    throw new Error('[clarity/font] fetch API gerekli (Node 18+ veya node-fetch paketi)');
+  }
+}

package/src/game-loop.js ADDED Viewed

@@ -0,0 +1,106 @@
+/**
+ * Clarity.js — game / animation loop helper
+ *
+ * A small, honest requestAnimationFrame loop. Clarity is a DOM/UI framework,
+ * not a WebGL engine — but DOM games and animations are perfectly doable, and
+ * this gives them a clean fixed/variable timestep loop that integrates with the
+ * component lifecycle.
+ *
+ *   import { createGameLoop, useRaf } from '@ozsarman/clarityjs/game-loop';
+ *
+ *   const loop = createGameLoop({
+ *     fps: 60,                       // fixed timestep (0 = uncapped, native rAF)
+ *     update: (dt) => { ... },       // dt in seconds
+ *     render: () => { ... },         // optional, after each update batch
+ *   });
+ *   loop.start();  loop.stop();  loop.toggle();
+ *
+ *   // Inside a component — auto-stops on unmount:
+ *   useRaf((dt) => { x += speed * dt; });
+ *
+ * Author: Claude (Anthropic) + Özdemir Şarman
+ */
+import { onCleanup } from './runtime.js';
+const _raf = (cb) =>
+  (typeof globalThis.requestAnimationFrame === 'function')
+    ? globalThis.requestAnimationFrame(cb)
+    : setTimeout(() => cb(Date.now()), 16);
+const _caf = (id) =>
+  (typeof globalThis.cancelAnimationFrame === 'function')
+    ? globalThis.cancelAnimationFrame(id)
+    : clearTimeout(id);
+/**
+ * Create a game loop.
+ * @param {object} opts
+ * @param {(dt:number)=>void} [opts.update]  per-step callback, dt in seconds
+ * @param {()=>void}          [opts.render]  called once after the update(s) each frame
+ * @param {number}            [opts.fps=0]   fixed timestep target; 0 = uncapped
+ * @param {number}            [opts.maxStepsPerFrame=5]  clamp to avoid spiral-of-death
+ * @returns {{ start, stop, toggle, isRunning }}
+ */
+export function createGameLoop(opts = {}) {
+  const { update, render, fps = 0, maxStepsPerFrame = 5 } = opts;
+  const step = fps > 0 ? 1 / fps : 0; // seconds per fixed step
+  let rafId = null;
+  let last = 0;
+  let acc = 0;
+  let running = false;
+  function frame(now) {
+    if (!running) return;
+    const dt = last ? (now - last) / 1000 : 0;
+    last = now;
+    if (step > 0) {
+      acc += dt;
+      let steps = 0;
+      while (acc >= step && steps < maxStepsPerFrame) {
+        if (update) update(step);
+        acc -= step;
+        steps++;
+      }
+      if (steps === maxStepsPerFrame) acc = 0; // dropped frames — resync
+    } else if (update) {
+      update(dt);
+    }
+    if (render) render();
+    rafId = _raf(frame);
+  }
+  return {
+    start() {
+      if (running) return;
+      running = true;
+      last = 0;
+      acc = 0;
+      rafId = _raf(frame);
+    },
+    stop() {
+      running = false;
+      if (rafId != null) _caf(rafId);
+      rafId = null;
+    },
+    toggle() { this.isRunning() ? this.stop() : this.start(); },
+    isRunning() { return running; },
+  };
+}
+/**
+ * Run a callback every animation frame, auto-stopping when the surrounding
+ * component unmounts. Returns the loop so you can stop/toggle it manually too.
+ *
+ * @param {(dt:number)=>void} fn  per-frame callback, dt in seconds
+ * @param {object} [opts]         same options as createGameLoop (minus update)
+ * @returns {{ start, stop, toggle, isRunning }}
+ */
+export function useRaf(fn, opts = {}) {
+  const loop = createGameLoop({ ...opts, update: fn });
+  loop.start();
+  try { onCleanup(() => loop.stop()); } catch { /* outside a component — caller owns lifecycle */ }
+  return loop;
+}