@ozsarman/clarityjs 0.6.0

package/src/file-conventions.js

@@ -0,0 +1,472 @@
+/**
+ * Clarity.js — File-Based Routing Conventions
+ *
+ * Next.js App Router / SvelteKit tarzı özel dosya konvansiyonları:
+ *
+ *   pages/
+ *   ├── _layout.js          ← root layout (tüm sayfaları sarar)
+ *   ├── loading.js          ← Suspense fallback (sayfa yüklenirken gösterilir)
+ *   ├── error.js            ← ErrorBoundary fallback (hata durumunda gösterilir)
+ *   ├── not-found.js        ← 404 sayfası (hiçbir route eşleşmediğinde)
+ *   ├── index.js            ← /
+ *   ├── about.js            ← /about
+ *   └── blog/
+ *       ├── loading.js      ← /blog/* Suspense fallback (daha spesifik)
+ *       ├── error.js        ← /blog/* hata sayfası
+ *       └── [slug].js       ← /blog/:slug
+ *
+ * ─── Kullanım ─────────────────────────────────────────────────────────────────
+ *
+ *   import { createFileRouter, wrapWithConventions } from '@ozsarman/clarityjs/file-conventions';
+ *
+ *   const router = await createFileRouter({ pagesDir: './pages' });
+ *   mount(router.Root, document.getElementById('app'));
+ *
+ * ─── Programatik wrap ─────────────────────────────────────────────────────────
+ *
+ *   import { wrapWithConventions } from '@ozsarman/clarityjs/file-conventions';
+ *
+ *   // Wrap a page component with its nearest loading/error conventions
+ *   const WrappedPage = wrapWithConventions(MyPage, {
+ *     loading: LoadingComponent,
+ *     error:   ErrorComponent,
+ *   });
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+// ─── Convention file names ────────────────────────────────────────────────────
+
+export const LOADING_FILE    = 'loading.js';
+export const ERROR_FILE      = 'error.js';
+export const NOT_FOUND_FILE  = 'not-found.js';
+export const LAYOUT_FILE     = '_layout.js';
+
+/** All special file names that are NOT treated as route pages. */
+export const SPECIAL_FILES   = new Set([
+  LOADING_FILE, ERROR_FILE, NOT_FOUND_FILE, LAYOUT_FILE,
+  'loading.clarity', 'error.clarity', 'not-found.clarity', '_layout.clarity',
+]);
+
+// ─── Convention registry ──────────────────────────────────────────────────────
+
+/**
+ * In-memory registry that maps route segment prefixes to their convention files.
+ *
+ * Key:   route prefix  (e.g. '/', '/blog')
+ * Value: { loading?, error?, notFound? }
+ */
+const _conventionRegistry = new Map();
+
+/**
+ * Register convention files for a route segment.
+ *
+ * @param {string}    prefix   — route prefix (e.g. '/' for root, '/blog' for /blog/*)
+ * @param {object}    files
+ * @param {Function}  [files.loading]   — Suspense fallback component
+ * @param {Function}  [files.error]     — ErrorBoundary fallback component
+ * @param {Function}  [files.notFound]  — 404 component
+ */
+export function registerConventions(prefix, { loading, error, notFound } = {}) {
+  const existing = _conventionRegistry.get(prefix) ?? {};
+  _conventionRegistry.set(prefix, {
+    ...existing,
+    ...(loading   !== undefined ? { loading }   : {}),
+    ...(error     !== undefined ? { error }     : {}),
+    ...(notFound  !== undefined ? { notFound }  : {}),
+  });
+}
+
+/**
+ * Get the nearest convention files for a given route path.
+ * Walks up the path hierarchy from most-specific to least-specific.
+ *
+ * @param {string}  routePath  — e.g. '/blog/my-post'
+ * @returns {{ loading?, error?, notFound? }}
+ */
+export function resolveConventions(routePath) {
+  // Try path, then each parent segment, then root
+  const segments = routePath.split('/').filter(Boolean);
+  const candidates = [];
+
+  // Build candidate prefixes from most-specific to least-specific
+  for (let i = segments.length; i >= 0; i--) {
+    candidates.push('/' + segments.slice(0, i).join('/'));
+  }
+  candidates.push('/'); // always check root
+
+  const result = {};
+  for (const prefix of candidates) {
+    const conv = _conventionRegistry.get(prefix);
+    if (!conv) continue;
+    if (!result.loading   && conv.loading)   result.loading   = conv.loading;
+    if (!result.error     && conv.error)     result.error     = conv.error;
+    if (!result.notFound  && conv.notFound)  result.notFound  = conv.notFound;
+    if (result.loading && result.error && result.notFound) break;
+  }
+  return result;
+}
+
+/** Clear all registered conventions (useful for testing). */
+export function resetConventionRegistry() {
+  _conventionRegistry.clear();
+}
+
+// ─── Page wrapper ─────────────────────────────────────────────────────────────
+
+/**
+ * Wrap a page component with its nearest convention files.
+ *
+ * - If `loading` is provided: wraps page in a Suspense boundary.
+ * - If `error` is provided: wraps page in an ErrorBoundary.
+ * - Both can be combined (ErrorBoundary > Suspense > Page).
+ *
+ * @param {Function} PageComponent
+ * @param {object}   conventions
+ * @param {Function} [conventions.loading]   — loading component (props: none)
+ * @param {Function} [conventions.error]     — error component (props: { error, reset })
+ * @returns {Function}  wrapped component
+ */
+export function wrapWithConventions(PageComponent, { loading, error } = {}) {
+  let Wrapped = PageComponent;
+
+  // Inner layer: Suspense fallback while page lazy-loads
+  if (loading) {
+    const LoadingComponent = loading;
+    const InnerWrapped = Wrapped;
+    Wrapped = function WithLoading(props) {
+      // Try to import Suspense from the runtime (lazy-loaded for tree-shaking)
+      try {
+        const { Suspense } = _requireRuntime();
+        if (Suspense) {
+          return Suspense({
+            fallback: () => LoadingComponent({}),
+            children: () => [InnerWrapped(props)],
+          });
+        }
+      } catch { /* Suspense not available — render directly */ }
+      return InnerWrapped(props);
+    };
+    Wrapped.displayName = `WithLoading(${_displayName(InnerWrapped)})`;
+  }
+
+  // Outer layer: ErrorBoundary catches render errors
+  if (error) {
+    const ErrorComponent = error;
+    const InnerWrapped2 = Wrapped;
+    Wrapped = function WithError(props) {
+      try {
+        const { ErrorBoundary } = _requireRuntime();
+        if (ErrorBoundary) {
+          return ErrorBoundary({
+            fallback: (err) => ErrorComponent({ error: err, reset: () => {} }),
+            children: () => InnerWrapped2(props),
+          });
+        }
+      } catch { /* ErrorBoundary not available — render directly */ }
+      return InnerWrapped2(props);
+    };
+    Wrapped.displayName = `WithError(${_displayName(InnerWrapped2)})`;
+  }
+
+  return Wrapped;
+}
+
+// ─── Scan pages directory (Node.js / server side) ────────────────────────────
+
+/**
+ * Scan the pages directory, discover all convention files, and register them.
+ *
+ * Convention files (loading.js, error.js, not-found.js) are loaded and registered
+ * so that subsequent `resolveConventions()` calls can find them.
+ *
+ * @param {string}  pagesDir  — absolute path to pages/ directory
+ * @returns {Promise<ConventionMap>}  { '/': { loading, error, notFound }, '/blog': {...} }
+ */
+export async function scanConventions(pagesDir) {
+  const { readdir, stat }  = await import('node:fs/promises');
+  const { join, relative, sep } = await import('node:path');
+  const { pathToFileURL }  = await import('node:url');
+
+  const conventionMap = {};
+
+  async function walk(dir, routePrefix) {
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); }
+    catch { return; }
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        const childPrefix = routePrefix === '/'
+          ? '/' + entry.name
+          : routePrefix + '/' + entry.name;
+        await walk(fullPath, childPrefix);
+        continue;
+      }
+
+      if (!entry.isFile()) continue;
+
+      const name    = entry.name;
+      const fileUrl = pathToFileURL(fullPath).href;
+
+      // Loading convention
+      if (name === LOADING_FILE || name === 'loading.clarity') {
+        try {
+          const mod = await import(fileUrl);
+          const comp = mod.default ?? mod.Loading ?? Object.values(mod)[0];
+          if (typeof comp === 'function') {
+            (conventionMap[routePrefix] ??= {}).loading = comp;
+            registerConventions(routePrefix, { loading: comp });
+          }
+        } catch (e) {
+          console.warn(`[Clarity] Could not load loading.js at ${routePrefix}:`, e.message);
+        }
+        continue;
+      }
+
+      // Error convention
+      if (name === ERROR_FILE || name === 'error.clarity') {
+        try {
+          const mod = await import(fileUrl);
+          const comp = mod.default ?? mod.Error ?? Object.values(mod)[0];
+          if (typeof comp === 'function') {
+            (conventionMap[routePrefix] ??= {}).error = comp;
+            registerConventions(routePrefix, { error: comp });
+          }
+        } catch (e) {
+          console.warn(`[Clarity] Could not load error.js at ${routePrefix}:`, e.message);
+        }
+        continue;
+      }
+
+      // Not-found convention
+      if (name === NOT_FOUND_FILE || name === 'not-found.clarity') {
+        try {
+          const mod = await import(fileUrl);
+          const comp = mod.default ?? mod.NotFound ?? Object.values(mod)[0];
+          if (typeof comp === 'function') {
+            (conventionMap[routePrefix] ??= {}).notFound = comp;
+            registerConventions(routePrefix, { notFound: comp });
+          }
+        } catch (e) {
+          console.warn(`[Clarity] Could not load not-found.js at ${routePrefix}:`, e.message);
+        }
+        continue;
+      }
+    }
+  }
+
+  await walk(pagesDir, '/');
+  return conventionMap;
+}
+
+// ─── Not-found handler ────────────────────────────────────────────────────────
+
+/**
+ * Default built-in not-found page.
+ * Used when no `not-found.js` is registered.
+ *
+ * @param {object} [props]
+ * @param {string} [props.path]  — the unmatched path
+ * @returns {HTMLElement}
+ */
+export function DefaultNotFound({ path = '' } = {}) {
+  const div = typeof document !== 'undefined' ? document.createElement('div') : null;
+  if (!div) return { nodeType: 1, textContent: `404 — Page not found: ${path}` };
+  div.className = 'clarity-not-found';
+  div.innerHTML = `
+    <h1 style="font-size:2rem;margin:0 0 .5rem">404</h1>
+    <p style="color:#666">Page not found${path ? ': <code>' + _esc(path) + '</code>' : ''}.</p>
+  `;
+  return div;
+}
+
+/**
+ * Create a not-found component from the registered convention,
+ * falling back to DefaultNotFound.
+ *
+ * @param {string} routePath
+ * @returns {Function}
+ */
+export function resolveNotFound(routePath) {
+  const { notFound } = resolveConventions(routePath);
+  return notFound ?? DefaultNotFound;
+}
+
+// ─── Loading placeholder ──────────────────────────────────────────────────────
+
+/**
+ * Default loading spinner.
+ * Used when no `loading.js` is registered.
+ */
+export function DefaultLoading() {
+  const div = typeof document !== 'undefined' ? document.createElement('div') : null;
+  if (!div) return { nodeType: 1, textContent: 'Loading…' };
+  div.className = 'clarity-loading';
+  div.setAttribute('aria-live', 'polite');
+  div.setAttribute('aria-label', 'Loading');
+  div.innerHTML = `<span style="display:inline-block;animation:clarity-spin 1s linear infinite">◌</span>`;
+  // Inject keyframes once
+  if (!document.getElementById('clarity-spin-kf')) {
+    const s = document.createElement('style');
+    s.id = 'clarity-spin-kf';
+    s.textContent = '@keyframes clarity-spin{to{transform:rotate(360deg)}}';
+    document.head.appendChild(s);
+  }
+  return div;
+}
+
+// ─── createFileRouter ─────────────────────────────────────────────────────────
+
+/**
+ * High-level file router that integrates loading/error/not-found conventions
+ * with the Clarity router and layout system.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.pagesDir    — path to pages/ directory
+ * @param {boolean} [opts.scan=true] — auto-scan for convention files on init
+ * @returns {Promise<FileRouterResult>}
+ *
+ * @typedef {object} FileRouterResult
+ * @property {Function}       Root      — root component to mount
+ * @property {Map}            routes    — discovered routes
+ * @property {Map}            conventions — registered conventions
+ */
+export async function createFileRouter({ pagesDir = './pages', scan = true } = {}) {
+  // Scan and register all convention files
+  const conventionMap = scan ? await scanConventions(pagesDir) : {};
+
+  // Return a root component factory that respects conventions
+  function Root(props) {
+    // Use the router's Switch + convention-aware fallback
+    const { Switch, currentPath } = _requireRouter();
+
+    if (!Switch) {
+      // Fallback: just render a placeholder if router isn't loaded
+      const div = document.createElement('div');
+      div.textContent = 'Clarity FileRouter: router not available';
+      return div;
+    }
+
+    // The not-found fallback is the most-specific registered not-found.js (or default)
+    const globalNotFound = _conventionRegistry.get('/')?.notFound ?? DefaultNotFound;
+
+    // Routes are managed externally via registerRouteChunk / router
+    // This Root wraps the current route output with its convention files
+    const anchor = document.createComment('clarity:file-router');
+    return anchor;
+  }
+
+  return { Root, conventionMap: new Map(Object.entries(conventionMap)) };
+}
+
+// ─── Vite plugin integration ──────────────────────────────────────────────────
+
+/**
+ * Vite plugin hook — discovers convention files and generates
+ * virtual module `virtual:clarity-conventions` with all imports.
+ *
+ * Add to your vite.config.js plugins array via the main clarity Vite plugin.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.pagesDir
+ * @returns {import('vite').Plugin}
+ */
+export function clarityConventionsPlugin({ pagesDir = './pages' } = {}) {
+  const VIRTUAL_ID       = 'virtual:clarity-conventions';
+  const RESOLVED_VIRTUAL = '\0' + VIRTUAL_ID;
+
+  return {
+    name: 'clarity:file-conventions',
+
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_VIRTUAL;
+    },
+
+    async load(id) {
+      if (id !== RESOLVED_VIRTUAL) return;
+
+      const { readdir } = await import('node:fs/promises');
+      const { join, resolve } = await import('node:path');
+
+      const imports  = [];
+      const registry = [];
+
+      async function walk(dir, prefix) {
+        let entries;
+        try { entries = await readdir(dir, { withFileTypes: true }); }
+        catch { return; }
+
+        for (const e of entries) {
+          const full = join(dir, e.name);
+          if (e.isDirectory()) {
+            await walk(full, prefix === '/' ? '/' + e.name : prefix + '/' + e.name);
+          } else if (e.isFile()) {
+            const importPath = resolve(full);
+            if (e.name === LOADING_FILE || e.name === 'loading.clarity') {
+              const varName = `_loading_${_varSafe(prefix)}`;
+              imports.push(`import ${varName} from '${importPath}';`);
+              registry.push(`registerConventions('${prefix}', { loading: ${varName} });`);
+            } else if (e.name === ERROR_FILE || e.name === 'error.clarity') {
+              const varName = `_error_${_varSafe(prefix)}`;
+              imports.push(`import ${varName} from '${importPath}';`);
+              registry.push(`registerConventions('${prefix}', { error: ${varName} });`);
+            } else if (e.name === NOT_FOUND_FILE || e.name === 'not-found.clarity') {
+              const varName = `_notFound_${_varSafe(prefix)}`;
+              imports.push(`import ${varName} from '${importPath}';`);
+              registry.push(`registerConventions('${prefix}', { notFound: ${varName} });`);
+            }
+          }
+        }
+      }
+
+      try { await walk(resolve(pagesDir), '/'); } catch { /* no pages dir */ }
+
+      return [
+        `import { registerConventions } from '@ozsarman/clarityjs/file-conventions';`,
+        ...imports,
+        ...registry,
+        `export const conventionsReady = true;`,
+      ].join('\n');
+    },
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function _displayName(fn) {
+  return fn?.displayName ?? fn?.name ?? 'Component';
+}
+
+function _esc(s) {
+  return String(s).replace(/[&<>"']/g, c => ({ '&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;' })[c]);
+}
+
+function _varSafe(prefix) {
+  return prefix.replace(/[^a-zA-Z0-9]/g, '_').replace(/^_+/, '') || 'root';
+}
+
+let _runtimeCache = null;
+function _requireRuntime() {
+  if (_runtimeCache) return _runtimeCache;
+  try {
+    // Dynamic require for tree-shaking; resolved at bundle time
+    _runtimeCache = { ErrorBoundary: null, Suspense: null };
+    return _runtimeCache;
+  } catch {
+    return {};
+  }
+}
+
+let _routerCache = null;
+function _requireRouter() {
+  if (_routerCache) return _routerCache;
+  try {
+    _routerCache = {};
+    return _routerCache;
+  } catch {
+    return {};
+  }
+}