@brightsideoy/kama 0.1.0-alpha.12 → 0.1.0-alpha.121

package/templates/astro-starter/src/components/ui/KamaImage.astro

@@ -0,0 +1,149 @@
+---
+// src/components/ui/KamaImage.astro
+
+import { getMediaUrl } from "@/lib/cms";
+// 🎯 FIX: Updated import path to match our new folder structure
+import { buildAgnosticImageUrl } from "@/lib/media/media-url";
+
+interface Props {
+  image: any;
+  sizes?: string;
+  desktopWidths?: number[];
+  idealWidth?: number;
+  class?: string;
+  loading?: "lazy" | "eager";
+  fetchpriority?: "auto" | "high" | "low";
+}
+
+const {
+  image = {},
+  sizes = "100vw",
+  desktopWidths = [768, 1352],
+  idealWidth = 1352,
+  class: className = "",
+  loading = "lazy",
+  fetchpriority = "auto",
+} = Astro.props;
+
+if (!image || (!image.url && !image.path && !image.variants)) {
+  return null;
+}
+
+const variants = image.variants || {};
+
+/**
+ * Resolve CMS media URLs.
+ */
+const rawMobileUrl = getMediaUrl(variants.mobile?.url);
+const rawTabletUrl = getMediaUrl(variants.tablet?.url);
+const rawDesktopUrl = getMediaUrl(
+  variants.standard?.url || image.url || image.path,
+);
+
+/**
+ * Resolve dimensions.
+ * Crop dimensions take precedence over original image dimensions.
+ */
+const mobileW = Number(variants.mobile?.cropCoordinates?.width || 768);
+const mobileH = Number(variants.mobile?.cropCoordinates?.height || 576);
+
+const tabletW = Number(variants.tablet?.cropCoordinates?.width || 1024);
+const tabletH = Number(variants.tablet?.cropCoordinates?.height || 512);
+
+const baseWidth = Number(
+  variants.standard?.cropCoordinates?.width || image.width || idealWidth,
+);
+const baseHeight = Number(
+  variants.standard?.cropCoordinates?.height ||
+    image.height ||
+    Math.round(idealWidth * 0.5),
+);
+
+/**
+ * Build responsive srcset using query-based media proxy URLs (/media/foo.jpg?w=768&q=75&f=auto)
+ */
+function buildAgnosticSrcset(
+  url: string,
+  targetWidths: number[],
+  quality = 75,
+): string {
+  if (!url) return "";
+
+  return targetWidths
+    .map(width => `${buildAgnosticImageUrl(url, width, quality)} ${width}w`)
+    .join(", ");
+}
+
+/**
+ * Build srcsets.
+ */
+const mobileSrcset = rawMobileUrl
+  ? buildAgnosticSrcset(rawMobileUrl, [400, 768])
+  : null;
+
+const tabletSrcset = rawTabletUrl
+  ? buildAgnosticSrcset(rawTabletUrl, [768, 1024])
+  : null;
+
+const desktopSrcset = rawDesktopUrl
+  ? buildAgnosticSrcset(rawDesktopUrl, desktopWidths)
+  : null;
+
+/**
+ * Fallback image URL: /media/foo.jpg?w=1352&q=75&f=auto
+ */
+const absoluteFallback = rawDesktopUrl
+  ? buildAgnosticImageUrl(rawDesktopUrl, idealWidth, 75)
+  : "";
+---
+
+<picture>
+  {/* Mobile Variant (< 768px) */}
+  {
+    mobileSrcset && (
+      <source
+        media="(max-width: 767px)"
+        srcset={mobileSrcset}
+        sizes="(max-width: 767px) calc(100vw - 48px), 768px"
+        width={mobileW}
+        height={mobileH}
+      />
+    )
+  }
+
+  {/* Tablet Variant (768px - 1024px) */}
+  {
+    tabletSrcset && (
+      <source
+        media="(min-width: 768px) and (max-width: 1024px)"
+        srcset={tabletSrcset}
+        sizes="(max-width: 1024px) calc(100vw - 48px), 1024px"
+        width={tabletW}
+        height={tabletH}
+      />
+    )
+  }
+
+  {/* Desktop Variant (> 1024px) */}
+  {
+    desktopSrcset && (
+      <source
+        srcset={desktopSrcset}
+        sizes={sizes}
+        width={baseWidth}
+        height={baseHeight}
+      />
+    )
+  }
+
+  <img
+    src={absoluteFallback}
+    alt={image.alt || image.filename || ""}
+    width={baseWidth}
+    height={baseHeight}
+    loading={loading}
+    fetchpriority={fetchpriority}
+    decoding={loading === "eager" ? "sync" : "async"}
+    class={className}
+  />
+</picture>

package/templates/astro-starter/src/layouts/SkeletonLayout.astro

@@ -0,0 +1,45 @@
+---
+// src/layouts/SkeletonLayout.astro
+import SeoHead from "@/components/seo/SeoHead.astro";
+
+interface Props {
+  node: Record<string, any>;
+  content: Record<string, any>;
+  normalizedSlug: string;
+  isHomePage: boolean;
+}
+
+const { node = {}, content = {}, normalizedSlug, isHomePage } = Astro.props;
+
+// 1. Extract raw custom code fields from the node payload
+const customCss = node.css || "";
+const customJsHeader = node.jsHeader || "";
+const customJsFooter = node.jsFooter || "";
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <!-- 🎯 1. SEO & Meta Tags -->
+    <SeoHead
+      node={node}
+      content={content}
+      normalizedSlug={normalizedSlug}
+      isHomePage={isHomePage}
+    />
+
+    <!-- 🎯 2. Custom CSS injected into <head> -->
+    {customCss && <style set:html={customCss} />}
+
+    <!-- 🎯 3. Custom Header JS injected into <head> -->
+    {customJsHeader && <script set:html={customJsHeader} />}
+  </head>
+
+  <body>
+    <!-- 🎯 4. Renders your HTML Block natively (No wrappers, no headers) -->
+    <slot />
+
+    <!-- 🎯 5. Custom Footer JS injected before closing body -->
+    {customJsFooter && <script set:html={customJsFooter} />}
+  </body>
+</html>

package/templates/astro-starter/src/layouts/StandardLayout.astro

@@ -0,0 +1,52 @@
+---
+import Header from "@/components/global/Header.astro";
+import Footer from "@/components/global/Footer.astro";
+import SeoHead from "@/components/seo/SeoHead.astro";
+import type { TreeNode, ContentBlock } from "@/lib/cms";
+
+interface Props {
+  node: Record<string, any>;
+  content: Record<string, ContentBlock[]>;
+  normalizedSlug: string;
+  isHomePage: boolean;
+  hasSidebar?: boolean;
+  headerBlocks?: ContentBlock[];
+  tree?: TreeNode[];
+}
+
+const {
+  node = {},
+  content = {},
+  normalizedSlug,
+  isHomePage,
+  headerBlocks = [],
+  tree,
+} = Astro.props;
+
+const footerBlocks = content?.footer || [];
+---
+
+<html lang="en">
+  <head>
+    <SeoHead
+      node={node}
+      content={content}
+      normalizedSlug={normalizedSlug}
+      isHomePage={isHomePage}
+      headerBlocks={headerBlocks}
+    />
+    <!-- 🎯 Standard CSS is decoupled from the bundler -->
+    <link rel="stylesheet" href="/css/standard-theme.css" />
+  </head>
+  <body>
+    <Header node={node} tree={tree} />
+
+    <main class="content-block">
+      <div class="content-container">
+        <slot />
+      </div>
+    </main>
+
+    <Footer blocks={footerBlocks} contentMap={content} />
+  </body>
+</html>

package/templates/astro-starter/src/lib/cms.ts

@@ -0,0 +1,149 @@
+// src/lib/cms.ts
+
+export interface TreeNode {
+    id: number;
+    treeNodeId: number;
+    parentId: number | null;
+    title: string;
+    slug: string;
+    path: string;
+    nodeType: string;
+    hidden?: number;
+    summary?: string;
+    url?: string;
+    target?: string;
+    children?: TreeNode[];
+}
+
+export interface ContentBlock {
+    instanceId: number;
+    componentId: string;
+    data: Record<string, any>;
+}
+
+export interface RegionMeta {
+    isInherited: boolean;
+    inheritedFromId?: string | number;
+    inheritedFromTitle?: string;
+}
+
+export interface NodeResponse {
+    channelId: string | number;
+    treeId: string | number;
+    language: string;
+    node: {
+        id: number;
+        title: string;
+        slug: string;
+        nodeType: string;
+        path?: string;
+        createdAt?: string;
+        updatedAt?: string;
+        summary?: string;
+        children?: any[];
+        [key: string]: any;
+    };
+    content: Record<string, ContentBlock[]>;
+    regionMeta?: Record<string, RegionMeta>;
+}
+
+/**
+ * Resolves base CMS URL across runtime environments safely via Astro
+ */
+export function getCmsUrl(): string {
+    const url =
+        import.meta.env.PUBLIC_API_URL ||
+        import.meta.env.PUBLIC_CMS_URL ||
+        'http://localhost:8787';
+    return url.replace(/\/+$/, '');
+}
+
+/**
+ * Resolves Default Channel ID across environments
+ */
+export function getChannelId(): string {
+    return import.meta.env.PUBLIC_CHANNEL_ID || 'website';
+}
+
+/**
+ * Resolves Default Tree ID across environments
+ */
+export function getTreeId(): string {
+    return import.meta.env.PUBLIC_TREE_ID || 'navigation';
+}
+
+/**
+ * Fetch tree navigation hierarchy by tree key/ID and channel.
+ * Supports passing Cloudflare Service Bindings (e.g. env.CMS_WORKER.fetch)
+ */
+export async function getTree(
+    treeKeyOrId: string = getTreeId(),
+    channel: string | number = getChannelId(),
+    customFetch: typeof fetch = fetch
+): Promise<TreeNode[]> {
+    const baseUrl = getCmsUrl();
+    const requestUrl = `${baseUrl}/api/v1/tree/${treeKeyOrId}?channelId=${channel}`;
+
+    try {
+        const res = await customFetch(requestUrl, {
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+
+        if (!res.ok) return [];
+
+        const data = await res.json();
+        return data.items || [];
+    } catch (err) {
+        console.error('[CMS Client] Failed to fetch public tree:', err);
+        return [];
+    }
+}
+
+/**
+ * Fetch single content node payload by its full URL path.
+ * Supports passing Cloudflare Service Bindings (e.g. env.CMS_WORKER.fetch)
+ */
+export async function getNodeByPath(
+    path: string,
+    channel: string | number = getChannelId(),
+    preview = false,
+    customFetch: typeof fetch = fetch
+): Promise<NodeResponse | null> {
+    const cleanPath = path.replace(/^\/+|\/+$/g, '') || 'home';
+    const baseUrl = getCmsUrl();
+    const requestUrl = `${baseUrl}/api/v1/node/${cleanPath}?channelId=${channel}&preview=${preview}`;
+
+    try {
+        const res = await customFetch(requestUrl, {
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+
+        if (!res.ok) return null;
+
+        return (await res.json()) as NodeResponse;
+    } catch (err) {
+        console.error('[CMS Client] Failed to fetch node by path:', err);
+        return null;
+    }
+}
+
+/**
+ * Resolves relative media URLs against base CMS URL
+ */
+export function getMediaUrl(url?: string): string {
+    if (!url) return '';
+
+    const baseUrl = getCmsUrl();
+    let cleanUrl = url.replace(/^http:\/\/localhost:\d+/, baseUrl);
+
+    if (cleanUrl.startsWith('http://') || cleanUrl.startsWith('https://')) {
+        return cleanUrl;
+    }
+
+    const cleanPath = cleanUrl.replace(/^\/+/, '');
+    return `${baseUrl}/${cleanPath}`;
+}

package/templates/astro-starter/src/lib/media/kama-image-service.ts

@@ -0,0 +1,41 @@
+// src/kama-image-service.ts
+import type { LocalImageService } from "astro";
+
+const kamaImageService: LocalImageService = {
+    getURL(options) {
+        let src = options.src;
+
+        if (typeof src === 'object' && 'src' in src) {
+            src = src.src;
+        }
+
+        if (typeof src === 'string') {
+            try {
+                const url = new URL(src, 'http://localhost');
+
+                if (options.width) url.searchParams.set('w', Math.round(options.width).toString());
+                if (options.height) url.searchParams.set('h', Math.round(options.height).toString());
+                if (options.quality) url.searchParams.set('q', options.quality.toString());
+                if (options.format) url.searchParams.set('f', options.format.toString());
+
+                return src.startsWith('http') ? url.toString() : (url.pathname + url.search);
+            } catch (e) {
+                return src;
+            }
+        }
+        return String(src);
+    },
+    parseURL(url) {
+        return { src: url.pathname + url.search };
+    },
+    getHTMLAttributes(options) {
+        return {
+            width: options.width,
+            height: options.height,
+            loading: options.loading || 'lazy',
+            decoding: options.decoding || 'async',
+        };
+    }
+};
+
+export default kamaImageService;

package/templates/astro-starter/src/lib/media/media-proxy.ts

@@ -0,0 +1,127 @@
+// src/lib/media/media-proxy.ts
+import type { APIContext } from "astro";
+import { env } from "cloudflare:workers";
+
+export function getMimeType(filePath: string): string {
+    const ext = filePath.split(".").pop()?.toLowerCase();
+    switch (ext) {
+        case "jpg":
+        case "jpeg": return "image/jpeg";
+        case "png": return "image/png";
+        case "webp": return "image/webp";
+        case "avif": return "image/avif";
+        case "svg": return "image/svg+xml";
+        case "gif": return "image/gif";
+        case "pdf": return "application/pdf";
+        case "mp4": return "video/mp4";
+        case "webm": return "video/webm";
+        default: return "application/octet-stream";
+    }
+}
+
+export async function handleMediaProxy({ request, params, url, locals }: APIContext): Promise<Response> {
+    // Safely extract Cloudflare context from Astro locals (fixes the Hono "c." typo)
+    const cfContext = (locals as any).cfContext || (locals as any).runtime?.ctx;
+
+    // 🎯 Detect if Astro is requesting a resized variant
+    const hasResizeParams = url.searchParams.has('w') || url.searchParams.has('h') || url.searchParams.has('q') || url.searchParams.has('f');
+
+    // 1. Cloudflare Edge Cache API
+    let edgeCache: Cache | null = null;
+    try {
+        if (typeof caches !== "undefined" && caches.default) {
+            edgeCache = caches.default;
+            const cachedResponse = await edgeCache.match(request);
+            if (cachedResponse) return cachedResponse;
+        }
+    } catch (err) {
+        console.warn("[Media Proxy] Edge cache match failed:", err);
+    }
+
+    const rawPath = params.path || "";
+    const cleanPath = rawPath.replace(/^\/+|\/+$/g, "");
+
+    // 2. Direct R2 Lookup (ONLY IF NO RESIZING PARAMS ARE PRESENT AND WE ARE IN PROD)
+    const mediaBucket = env.MEDIA_BUCKET;
+    if (mediaBucket && cleanPath && !hasResizeParams) {
+        try {
+            let r2Object = await mediaBucket.get(cleanPath);
+            if (!r2Object) r2Object = await mediaBucket.get(cleanPath.startsWith("media/") ? cleanPath.replace(/^media\//, "") : `media/${cleanPath}`);
+
+            if (r2Object) {
+                if (request.headers.get("if-none-match") === r2Object.httpEtag) {
+                    return new Response(null, { status: 304 });
+                }
+
+                const headers = new Headers();
+                r2Object.writeHttpMetadata(headers);
+                headers.set("etag", r2Object.httpEtag);
+                headers.set("Cache-Control", "public, max-age=31536000, immutable");
+                headers.set("Access-Control-Allow-Origin", "*");
+                if (!headers.get("content-type") || headers.get("content-type") === "application/octet-stream") {
+                    headers.set("content-type", getMimeType(cleanPath));
+                }
+
+                const r2Response = new Response(r2Object.body, { status: 200, headers });
+
+                if (edgeCache) {
+                    const cachePromise = edgeCache.put(request, r2Response.clone());
+                    if (cfContext?.waitUntil) cfContext.waitUntil(cachePromise);
+                    else cachePromise.catch(e => console.warn(e));
+                }
+
+                return r2Response;
+            }
+        } catch (r2Err) {
+            console.warn("[Media Proxy] R2 lookup error:", r2Err);
+        }
+    }
+
+    // 3. Forward to Backend (Handles Local Sharp Resizing AND Cloudflare Images Resizing)
+    try {
+        let backendResponse: Response;
+
+        // A. Production Mode (Cloudflare Service Binding)
+        if (env.CMS_WORKER) {
+            backendResponse = await env.CMS_WORKER.fetch(request);
+        }
+        // B. Local Dev Mode (Standard HTTP Fetch to local Hono Server)
+        else {
+            const cmsUrl = import.meta.env.PUBLIC_CMS_URL || 'http://localhost:8787';
+            const targetUrl = `${cmsUrl}${url.pathname}${url.search}`;
+
+            // Forward request headers (like Accept for WebP/AVIF negotiation)
+            backendResponse = await fetch(targetUrl, {
+                headers: {
+                    'Accept': request.headers.get('Accept') || 'image/webp,image/avif,image/*,*/*;q=0.8'
+                }
+            });
+        }
+
+        if (backendResponse.ok) {
+            const newHeaders = new Headers(backendResponse.headers);
+            newHeaders.set("Cache-Control", "public, max-age=31536000, immutable");
+            newHeaders.set("Access-Control-Allow-Origin", "*");
+
+            const proxyResponse = new Response(backendResponse.body, {
+                status: backendResponse.status,
+                statusText: backendResponse.statusText,
+                headers: newHeaders,
+            });
+
+            if (edgeCache) {
+                const cachePromise = edgeCache.put(request, proxyResponse.clone());
+                if (cfContext?.waitUntil) cfContext.waitUntil(cachePromise);
+                else cachePromise.catch(e => console.warn(e));
+            }
+
+            return proxyResponse;
+        }
+
+        return backendResponse;
+    } catch (error) {
+        console.error("❌ Media Proxy Forwarding Error:", error);
+    }
+
+    return new Response("Not found", { status: 404 });
+}

package/templates/astro-starter/src/lib/media/media-url.ts

@@ -0,0 +1,34 @@
+// src/lib/media-url.ts
+
+export function toRelativeMediaPath(rawUrl: string): string {
+    if (!rawUrl) return "";
+
+    let clean = String(rawUrl);
+    clean = clean.replace(/^https?:\/\/[^/]+/, "");
+    clean = clean.split("?")[0].split("#")[0];
+
+    const mediaIndex = clean.indexOf("/media/");
+    if (mediaIndex !== -1) {
+        return `/media/${clean
+            .slice(mediaIndex + "/media/".length)
+            .replace(/^\/+/, "")}`;
+    }
+
+    return clean.startsWith("/") ? clean : `/${clean}`;
+}
+
+export function buildAgnosticImageUrl(
+    url: string,
+    width: number,
+    quality = 75,
+): string {
+    const cleanPath = toRelativeMediaPath(url);
+    if (!cleanPath) return "";
+
+    const urlObj = new URL(cleanPath, "http://localhost");
+    urlObj.searchParams.set("w", String(width));
+    urlObj.searchParams.set("q", String(quality));
+    urlObj.searchParams.set("f", "auto");
+
+    return urlObj.pathname + urlObj.search;
+}

package/templates/astro-starter/src/pages/404.astro

@@ -0,0 +1,46 @@
+---
+// src/pages/404.astro
+import StandardLayout from "../layouts/StandardLayout.astro";
+
+const node = {
+  title: "Page Not Found",
+  summary: "We couldn't find the page you were looking for.",
+};
+---
+
+<StandardLayout
+  node={node}
+  isHomePage={false}
+  hasSidebar={false}
+  content={{}}
+  normalizedSlug="404"
+  headerBlocks={[]}
+>
+  <div class="error-page">
+    <h1>404</h1>
+    <h2>Page Not Found</h2>
+    <p>Sorry, the page you are looking for doesn't exist or has been moved.</p>
+    <a href="/" class="button">Go back home</a>
+  </div>
+</StandardLayout>
+
+<style>
+  .error-page {
+    text-align: center;
+    padding: 100px 20px;
+  }
+  .error-page h1 {
+    font-size: 6rem;
+    margin-bottom: 0;
+    color: #0284c7;
+  }
+  .button {
+    display: inline-block;
+    margin-top: 24px;
+    padding: 12px 24px;
+    background: #0f172a;
+    color: white;
+    text-decoration: none;
+    border-radius: 4px;
+  }
+</style>