@brightsideoy/kama 0.1.0-alpha.98 → 1.0.0-alpha.10

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

@@ -0,0 +1,180 @@
+---
+// src/components/ui/KamaImage.astro
+
+import {
+  buildAgnosticImageUrl,
+  isSvgImage,
+  getImageUri,
+} 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, 1920, 2560],
+  idealWidth = 1352,
+  class: className = "",
+  loading = "lazy",
+  fetchpriority = "auto",
+} = Astro.props;
+
+// Unpack array wrappers if passed
+const targetImage = Array.isArray(image) ? image[0] : image;
+
+// 🎯 FIX 1: Support string paths in addition to object payloads
+const isValidImage = Boolean(
+  targetImage &&
+  (typeof targetImage === "string" ||
+    targetImage.url ||
+    targetImage.path ||
+    targetImage.variants),
+);
+
+// Detect if this asset is a vector SVG
+const isSvg =
+  isSvgImage(targetImage?.mimeType || "") ||
+  isSvgImage(targetImage?.filename || "") ||
+  isSvgImage(targetImage?.url || targetImage?.path || "") ||
+  (typeof targetImage === "string" && isSvgImage(targetImage));
+
+const variants = targetImage?.variants || {};
+
+// Resolve base paths using getImageUri to ensure CSP compliance & relativity
+const rawMobileUrl = getImageUri(variants.mobile?.url);
+const rawTabletUrl = getImageUri(variants.tablet?.url);
+const rawDesktopUrl = getImageUri(
+  variants.standard?.url ||
+    targetImage?.url ||
+    targetImage?.path ||
+    targetImage,
+);
+
+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);
+
+// 🎯 FIX 2: Omit explicit width/height attributes on SVGs if intrinsic dimensions are missing/0
+const rawWidth = Number(
+  variants.standard?.cropCoordinates?.width || targetImage?.width,
+);
+const rawHeight = Number(
+  variants.standard?.cropCoordinates?.height || targetImage?.height,
+);
+
+const baseWidth =
+  rawWidth && !isNaN(rawWidth) && rawWidth > 0 ? rawWidth : idealWidth;
+const baseHeight =
+  rawHeight && !isNaN(rawHeight) && rawHeight > 0
+    ? rawHeight
+    : Math.round(idealWidth * 0.5);
+
+function buildAgnosticSrcset(
+  url: string,
+  targetWidths: number[],
+  quality = 75,
+): string {
+  if (!url) return "";
+  return targetWidths
+    .map(width => `${buildAgnosticImageUrl(url, width, quality)} ${width}w`)
+    .join(", ");
+}
+
+// 🎯 High-DPI / Retina Optimization:
+// - Mobile: Includes 320, 640, 768 (covers 2x and 3x Retina mobile displays)
+// - Tablet: Includes 768, 1024, 1352 (covers iPad Pro Retina density)
+// - Desktop: Uses desktopWidths (defaults to 768, 1352, 1920, 2560 for 1440p and 4K)
+const mobileSrcset =
+  !isSvg && rawMobileUrl
+    ? buildAgnosticSrcset(rawMobileUrl, [320, 640, 768])
+    : null;
+
+const tabletSrcset =
+  !isSvg && rawTabletUrl
+    ? buildAgnosticSrcset(rawTabletUrl, [768, 1024, 1352])
+    : null;
+
+const desktopSrcset =
+  !isSvg && rawDesktopUrl
+    ? buildAgnosticSrcset(
+        rawDesktopUrl,
+        desktopWidths.length ? desktopWidths : [768, 1352, 1920, 2560],
+      )
+    : null;
+
+const fallbackUrl =
+  getImageUri(rawDesktopUrl, {
+    width: isSvg ? undefined : baseWidth,
+    quality: 75,
+  }) || "";
+---
+
+{
+  isValidImage &&
+    (isSvg ? (
+      /* 🎯 Clean single <img> for SVG Vectors */
+      <img
+        src={fallbackUrl}
+        alt={targetImage.alt || targetImage.filename || ""}
+        width={rawWidth > 0 ? rawWidth : undefined}
+        height={rawHeight > 0 ? rawHeight : undefined}
+        loading={loading}
+        fetchpriority={fetchpriority}
+        decoding={loading === "eager" ? "sync" : "async"}
+        class={className}
+      />
+    ) : (
+      /* 🎯 Responsive <picture> for Raster Images (.png, .jpg, .webp) */
+      <picture>
+        {Boolean(mobileSrcset) && (
+          <source
+            media="(max-width: 767px)"
+            srcset={mobileSrcset as string}
+            sizes="(max-width: 767px) calc(100vw - 48px), 768px"
+            width={mobileW}
+            height={mobileH}
+          />
+        )}
+
+        {Boolean(tabletSrcset) && (
+          <source
+            media="(min-width: 768px) and (max-width: 1024px)"
+            srcset={tabletSrcset as string}
+            sizes="(max-width: 1024px) calc(100vw - 48px), 1024px"
+            width={tabletW}
+            height={tabletH}
+          />
+        )}
+
+        {Boolean(desktopSrcset) && (
+          <source
+            srcset={desktopSrcset as string}
+            sizes={sizes}
+            width={baseWidth}
+            height={baseHeight}
+          />
+        )}
+
+        <img
+          src={fallbackUrl}
+          alt={targetImage.alt || targetImage.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,56 @@
+---
+// src/layouts/SkeletonLayout.astro
+
+import MetaHead from "@/components/global/MetaHead.astro";
+
+interface Props {
+  node: Record<string, any>;
+  content: Record<string, any>;
+  normalizedSlug: string;
+  isHomePage: boolean;
+  // 🎯 1. Added language to Props
+  language?: string;
+}
+
+// 🎯 2. Destructure language
+const {
+  node = {},
+  content = {},
+  normalizedSlug,
+  isHomePage,
+  language,
+} = Astro.props;
+
+const customCss = node.css || "";
+const customJsHeader = node.jsHeader || "";
+const customJsFooter = node.jsFooter || "";
+
+// Now this works without crashing!
+const pageLang = language || node?.language || "en";
+---
+
+<!doctype html>
+<html lang={pageLang}>
+  <head>
+    <MetaHead
+      node={node}
+      content={content}
+      normalizedSlug={normalizedSlug}
+      isHomePage={isHomePage}
+    />
+
+    <!-- 🎯 3. Added is:inline so Astro actually renders your database CSS -->
+    {customCss && <style is:inline set:html={customCss} />}
+
+    <!-- 🎯 4. Added is:inline so Astro executes your header JS -->
+    {customJsHeader && <script is:inline set:html={customJsHeader} />}
+  </head>
+
+  <body>
+    <!-- Renders your Blocks (like the HTML Block) natively -->
+    <slot />
+
+    <!-- 🎯 5. Added is:inline to footer JS -->
+    {customJsFooter && <script is:inline set:html={customJsFooter} />}
+  </body>
+</html>

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

@@ -0,0 +1,63 @@
+---
+// src/layouts/StandardLayout.astro
+
+import "@/styles/standard-theme.css";
+import Header from "@/components/global/Header.astro";
+import Footer from "@/components/global/Footer.astro";
+import MetaHead from "@/components/global/MetaHead.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[];
+  language?: string;
+}
+
+const {
+  node = {},
+  content = {},
+  normalizedSlug,
+  isHomePage,
+  headerBlocks = [],
+  tree,
+  language,
+} = Astro.props;
+
+// 🎯 Language Cascade: explicit prop -> node language -> fallback undefined
+// (MetaHead will resolve channel.defaultLanguage if this remains undefined)
+const pageLang = language || node?.language || undefined;
+
+// 🎯 FIX: Extract the footer blocks from the payload again
+const footerBlocks = content?.footer || [];
+---
+
+<!doctype html>
+<html lang={pageLang}>
+  <head>
+    <MetaHead
+      node={node}
+      content={content}
+      normalizedSlug={normalizedSlug}
+      isHomePage={isHomePage}
+      headerBlocks={headerBlocks}
+      resolvedLanguage={pageLang}
+    />
+  </head>
+  <body>
+    <Header node={node} tree={tree} />
+
+    <main class="content-block">
+      <div class="content-container">
+        <slot />
+      </div>
+    </main>
+
+    {/* 🎯 FIX: Pass the blocks and contentMap into the Footer */}
+    <Footer blocks={footerBlocks} contentMap={content} />
+  </body>
+</html>

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

@@ -0,0 +1,219 @@
+// 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[];
+    [key: string]: any;
+}
+
+export interface ContentBlock {
+    instanceId: number;
+    componentId: string;
+    data: Record<string, any>;
+    [key: string]: any;
+}
+
+export interface RegionMeta {
+    isInherited: boolean;
+    inheritedFromId?: string | number;
+    inheritedFromTitle?: string;
+    [key: string]: any;
+}
+
+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>;
+    [key: string]: any;
+}
+
+export interface ChannelResponse {
+    id: number;
+    key: string;
+    label: string;
+    channelType: string;
+    defaultLanguage: string;
+    // Core branding & SEO properties typed for IDE auto-complete:
+    logo?: string;
+    logoText?: string;
+    favicon?: string;
+    siteTitle?: string;
+    titleSuffix?: string;
+    defaultSeoImage?: string;
+    // 🎯 Dynamically captures all public fields defined in YAML channel schemas:
+    [key: string]: any;
+}
+
+/**
+ * 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';
+}
+
+// 🎯 Safely resolve global authorization header for default CMS fetches
+function getAuthHeaders(): Record<string, string> {
+    const secret = import.meta.env.FRONTEND_API_SECRET;
+    const headers: Record<string, string> = { Accept: 'application/json' };
+    if (secret) headers['Authorization'] = `Bearer ${secret}`;
+    return headers;
+}
+
+/**
+ * Fetch channel metadata by key/ID.
+ * Serves global site branding, logos, favicons, and schema-defined public fields.
+ */
+export async function getChannel(
+    channelKeyOrId: string = getChannelId(),
+    customFetch: typeof fetch = fetch
+): Promise<ChannelResponse | null> {
+    const baseUrl = getCmsUrl();
+    const requestUrl = `${baseUrl}/api/v1/channel/${channelKeyOrId}`;
+
+    try {
+        const res = await customFetch(requestUrl, {
+            headers: getAuthHeaders(),
+        });
+
+        if (!res.ok) return null;
+
+        // 🎯 Defensive HTML check
+        if (res.headers.get("content-type")?.includes("text/html")) {
+            console.error(`❌ [CMS Client] API returned HTML instead of JSON for Channel: ${requestUrl}`);
+            return null;
+        }
+
+        return (await res.json()) as ChannelResponse;
+    } catch (err) {
+        console.error('[CMS Client] Failed to fetch public channel:', err);
+        return null;
+    }
+}
+
+/**
+ * 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: getAuthHeaders(),
+        });
+
+        if (!res.ok) return [];
+
+        // 🎯 Defensive HTML check
+        if (res.headers.get("content-type")?.includes("text/html")) {
+            console.error(`❌ [CMS Client] API returned HTML instead of JSON for Tree: ${requestUrl}`);
+            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> {
+    // 🎯 We keep 'index' as the fallback string for Hono routing compatibility,
+    // because the backend dynamically intercepts 'index' and returns the channelRoot!
+    const cleanPath = path.replace(/^\/+|\/+$/g, '') || 'index';
+    const baseUrl = getCmsUrl();
+    const requestUrl = `${baseUrl}/api/v1/node/${cleanPath}?channelId=${channel}&preview=${preview}`;
+
+    try {
+        const res = await customFetch(requestUrl, {
+            headers: getAuthHeaders(),
+        });
+
+        if (!res.ok) return null;
+
+        // 🎯 Defensive HTML check (Prevents the dreaded "<!DOCTYPE html" JSON parse crash)
+        if (res.headers.get("content-type")?.includes("text/html")) {
+            console.error(`❌ [CMS Client] API returned HTML instead of JSON for Node: ${requestUrl}`);
+            return null;
+        }
+
+        return (await res.json()) as NodeResponse;
+    } catch (err) {
+        console.error(`[CMS Client] Failed to fetch node by path (${cleanPath}):`, 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,67 @@
+// src/lib/media/kama-image-service.ts
+
+import type { LocalImageService } from "astro";
+
+/**
+ * Checks whether a given path or URL represents a vector SVG image.
+ */
+function isSvgImage(src: string): boolean {
+    if (!src) return false;
+    const lower = src.toLowerCase();
+    return lower.endsWith('.svg') || lower.includes('image/svg+xml') || lower.includes('.svg?');
+}
+
+const kamaImageService: LocalImageService = {
+    getURL(options) {
+        let src = options.src;
+
+        if (typeof src === 'object' && 'src' in src) {
+            src = src.src;
+        }
+
+        if (typeof src === 'string') {
+            try {
+                // 🎯 SVG Guard: Bypass raster query params for vector graphics
+                if (isSvgImage(src)) {
+                    return src;
+                }
+
+                const url = new URL(src, 'http://localhost');
+
+                // 🎯 Pass width if defined (snapped on backend by assets.ts)
+                if (options.width && !isNaN(options.width)) {
+                    url.searchParams.set('w', Math.round(options.width).toString());
+                }
+
+                // 🎯 Pass height only if explicitly provided to maintain intrinsic aspect ratios
+                if (options.height && !isNaN(options.height)) {
+                    url.searchParams.set('h', Math.round(options.height).toString());
+                }
+
+                // 🎯 Default quality to 75 if unsupplied
+                url.searchParams.set('q', (options.quality || 75).toString());
+
+                // 🎯 Default format to 'auto' for backend WebP/AVIF negotiation
+                url.searchParams.set('f', options.format ? options.format.toString() : 'auto');
+
+                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;