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

package/templates/astro-starter/src/components/global/Header.astro

@@ -0,0 +1,177 @@
+---
+// src/components/global/Header.astro
+
+import NavigationMenu from "@/components/global/NavigationMenu.astro";
+import KamaImage from "@/components/ui/KamaImage.astro";
+import { getTree, getTreeId, getChannel, getChannelId } from "@/lib/cms";
+import type { TreeNode } from "@/lib/cms";
+
+interface Props {
+  node?: Record<string, any>;
+  tree?: TreeNode[];
+}
+
+const props = Astro.props as Props;
+const currentPropsNode = props.node || {};
+let rawTree: TreeNode[] = props.tree || [];
+
+// 🎯 Read the safely extracted environment from middleware (Fixes Astro 7 crash)
+const safeEnv = (Astro.locals as any).safeEnv || {};
+const cmsWorker = safeEnv.CMS_WORKER;
+
+const customFetch = (input: RequestInfo | URL, init?: RequestInit) => {
+  const reqInit = { ...init };
+  delete reqInit.cache;
+
+  let urlStr = input instanceof URL ? input.toString() : String(input);
+
+  if (urlStr.startsWith("/")) {
+    const baseUrl =
+      import.meta.env.PUBLIC_API_URL ||
+      safeEnv.PUBLIC_API_URL ||
+      "http://127.0.0.1:8787";
+    urlStr = `${baseUrl}${urlStr}`;
+  }
+
+  const req = new Request(urlStr, reqInit);
+
+  if (cmsWorker && typeof cmsWorker.fetch === "function") {
+    return cmsWorker.fetch(req);
+  }
+  return fetch(req);
+};
+
+// 🎯 Fetch Global Channel Metadata and Nav Tree in Parallel
+const channelId = getChannelId() || "website";
+const treeId = getTreeId() || "main-nav";
+
+let channelData: Record<string, any> | null = null;
+
+try {
+  const [fetchedChannel, fetchedTree] = await Promise.all([
+    getChannel(channelId, customFetch),
+    !rawTree || rawTree.length === 0
+      ? getTree(treeId, channelId, customFetch)
+      : Promise.resolve(rawTree),
+  ]);
+
+  channelData = fetchedChannel;
+  if (!rawTree || rawTree.length === 0) {
+    rawTree = fetchedTree || [];
+  }
+} catch (e) {
+  console.error("[Header] Failed to load layout data:", e);
+}
+
+// 🎯 1. Resolve Logo Text (Strict waterfall prioritizing explicit strings)
+const rawLogoText = channelData?.logoText;
+const rawSiteTitle = channelData?.siteTitle;
+const rawLabel = channelData?.label;
+
+let logoText = "";
+
+if (typeof rawLogoText === "string" && rawLogoText.trim() !== "") {
+  logoText = rawLogoText;
+} else if (typeof rawSiteTitle === "string" && rawSiteTitle.trim() !== "") {
+  logoText = rawSiteTitle;
+} else if (typeof rawLabel === "string" && rawLabel.trim() !== "") {
+  logoText = rawLabel;
+} else if (currentPropsNode.logoText) {
+  logoText = currentPropsNode.logoText;
+} else {
+  logoText = import.meta.env.PUBLIC_SITE_NAME || "KAMA";
+}
+
+// 🎯 2. Extract Raw Logo Asset (Unwraps array wrappers if present)
+const rawLogoAsset = channelData?.logoImage || channelData?.logo;
+const targetLogo = Array.isArray(rawLogoAsset) ? rawLogoAsset[0] : rawLogoAsset;
+
+// 🎯 3. Strict Image Validation Guard (Guarantees non-empty string or populated object)
+const hasValidLogoImage = Boolean(
+  targetLogo &&
+  ((typeof targetLogo === "string" && targetLogo.trim() !== "") ||
+    targetLogo.url ||
+    targetLogo.path ||
+    targetLogo.variants),
+);
+---
+
+<header class="site-header">
+  <div class="header-container main-header-row">
+    <a href="/" class="logo-block">
+      {
+        hasValidLogoImage ? (
+          <KamaImage
+            image={targetLogo}
+            idealWidth={300}
+            class="logo-image"
+            loading="eager"
+            fetchpriority="high"
+          />
+        ) : (
+          <span class="logo-text">{logoText}</span>
+        )
+      }
+    </a>
+    <NavigationMenu tree={rawTree} />
+  </div>
+</header>
+
+<style>
+  .site-header {
+    background: #ffffff;
+    color: #1e293b;
+    position: sticky;
+    top: 0;
+    z-index: 100;
+    border-bottom: 1px solid #e2e8f0;
+  }
+
+  .header-container {
+    max-width: 1400px;
+    margin: 0 auto;
+    padding: 0 20px;
+    width: 100%;
+    box-sizing: border-box;
+  }
+
+  .main-header-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    height: 64px;
+  }
+
+  .logo-block {
+    text-decoration: none;
+    color: #0f172a;
+    font-weight: 700;
+    font-size: 20px;
+    display: inline-flex;
+    align-items: center;
+    z-index: 1001;
+  }
+
+  /* 🎯 Strict 16px Height Constraint for KamaImage output */
+  :global(.logo-image) {
+    height: 16px !important;
+    max-height: 16px !important;
+    width: auto !important;
+    object-fit: contain;
+    display: block;
+  }
+
+  .logo-text {
+    white-space: nowrap;
+    font-size: 16px;
+    line-height: 16px;
+  }
+
+  @media (min-width: 768px) {
+    .main-header-row {
+      height: 64px;
+      justify-content: space-between;
+      gap: 32px;
+    }
+  }
+</style>

package/templates/astro-starter/src/components/global/MetaHead.astro

@@ -0,0 +1,266 @@
+---
+// src/components/global/MetaHead.astro
+
+import type { ContentBlock } from "@/lib/cms";
+import { getChannel, getChannelId } from "@/lib/cms";
+import { getImageUri } from "@/lib/media/media-url";
+
+interface Props {
+  node: Record<string, any>;
+  content: Record<string, ContentBlock[]>;
+  normalizedSlug: string;
+  isHomePage: boolean;
+  headerBlocks?: ContentBlock[];
+  resolvedLanguage?: string;
+}
+
+const { 
+  node = {}, 
+  content = {}, 
+  normalizedSlug, 
+  isHomePage, 
+  headerBlocks = [],
+  resolvedLanguage
+} = Astro.props;
+
+// 🎯 0. Read the safely extracted environment from middleware (Fixes Astro 7 crash)
+const safeEnv = (Astro.locals as any).safeEnv || {};
+const cmsWorker = safeEnv.CMS_WORKER;
+
+const customFetch = (input: RequestInfo | URL, init?: RequestInit) => {
+  const reqInit = { ...init };
+  delete reqInit.cache;
+
+  let urlStr = input instanceof URL ? input.toString() : String(input);
+
+  if (urlStr.startsWith("/")) {
+    const baseUrl = import.meta.env.PUBLIC_API_URL || safeEnv.PUBLIC_API_URL || "http://127.0.0.1:8787";
+    urlStr = `${baseUrl}${urlStr}`;
+  }
+
+  const req = new Request(urlStr, reqInit);
+
+  if (cmsWorker && typeof cmsWorker.fetch === "function") {
+    return cmsWorker.fetch(req);
+  }
+  return fetch(req);
+};
+
+// 🎯 Fetch Global Channel Metadata
+const channel = await getChannel(getChannelId(), customFetch);
+
+// 🎯 Language Cascade Final Resolution:
+// Prop / Node Language -> Channel Default -> Undefined
+const activeLanguage = resolvedLanguage || node?.language || channel?.defaultLanguage || channel?.language || undefined;
+
+// Convert BCP 47 (e.g. et-EE, zh-CN) to Open Graph locale format (et_EE, zh_CN)
+const ogLocale = activeLanguage ? activeLanguage.replace("-", "_") : undefined;
+
+// 🎯 1. Resolve Origin Safely
+let siteOrigin = import.meta.env.PUBLIC_FRONTEND_URL || safeEnv.PUBLIC_FRONTEND_URL || Astro.site?.origin || Astro.url.origin;
+if (siteOrigin === "https://example.com") {
+  siteOrigin = Astro.url.origin;
+}
+siteOrigin = siteOrigin.replace(/\/$/, "");
+
+// 🎯 2. Favicon Resolution (Channel -> Fallback Static)
+const faviconUrl = getImageUri(channel?.favicon, {
+  fallback: "/favicon.png",
+})!;
+
+// Detect MIME type dynamically for the favicon link tag
+const getFaviconType = (url: string) => {
+  if (url.endsWith(".svg")) return "image/svg+xml";
+  if (url.endsWith(".ico")) return "image/x-icon";
+  return "image/png";
+};
+
+// 🎯 3. Detect Block-level LCP Image Candidate
+const firstHeaderBlock = headerBlocks && headerBlocks[0];
+const firstContentBlock = content?.content && content.content[0];
+const candidateBlock = (firstHeaderBlock?.data?.image ? firstHeaderBlock : null) 
+  || (firstContentBlock?.data?.image ? firstContentBlock : null);
+
+const lcpImageUrl = getImageUri(candidateBlock?.data?.image, {
+  width: 1352,
+  quality: 75,
+});
+
+// 🎯 4. Text Metadata Variables
+const brandName = channel?.siteTitle || channel?.label || import.meta.env.PUBLIC_SITE_NAME || safeEnv.PUBLIC_SITE_NAME || "KAMA";
+const agencyName = import.meta.env.PUBLIC_AGENCY_NAME || safeEnv.PUBLIC_AGENCY_NAME || "";
+
+const brandLogo = getImageUri(channel?.logoImage || channel?.logo, {
+  width: 512,
+  absoluteOrigin: siteOrigin,
+  fallback: `${siteOrigin}/logo.png`,
+})!;
+
+const prefix = node?.titlePrefix?.trim() ? `${node.titlePrefix.trim()} ` : "";
+
+// Suffix Waterfall: Page node -> Channel level (e.g. "- Suffix")
+const channelSuffix = channel?.titleSuffix?.trim() || "";
+const rawSuffix = node?.titleSuffix?.trim() || channelSuffix;
+const suffix = rawSuffix ? ` ${rawSuffix}` : "";
+
+const baseTitle = node?.title?.trim() || brandName;
+const fullTitle = `${prefix}${baseTitle}${suffix}`;
+
+// Description Waterfall: Page summary -> Channel metaDescription
+const metaDescription = node?.summary || channel?.metaDescription || "KAMA – The headless content engine built for omnichannel delivery and Cloudflare Edge computing.";
+
+const canonicalURL = new URL(Astro.url.pathname, siteOrigin).href;
+
+// 🎯 5. Social Text Waterfall
+const fbTitle = node?.fbTitle?.trim() || fullTitle;
+const xTitle = node?.xTitle?.trim() || fbTitle;
+const fbDescription = node?.fbDescription?.trim() || metaDescription;
+const xDescription = node?.xDescription?.trim() || fbDescription;
+
+// 🎯 6. Social Image Waterfall (Page -> LCP Candidate -> Channel Default -> Fallback)
+const channelDefaultOg = channel?.defaultSeoImage;
+const rawFbImage = node?.socialImages?.facebook?.url || candidateBlock?.data?.image || channelDefaultOg;
+const rawXImage = node?.socialImages?.x?.url || candidateBlock?.data?.image || channelDefaultOg;
+
+const fbImageUrl = getImageUri(rawFbImage, {
+  width: 1200,
+  quality: 80,
+  absoluteOrigin: siteOrigin,
+  fallback: `${siteOrigin}/default-og-image.png`,
+})!;
+
+const xImageUrl = getImageUri(rawXImage, {
+  width: 1200,
+  quality: 80,
+  absoluteOrigin: siteOrigin,
+  fallback: `${siteOrigin}/default-og-image.png`,
+})!;
+
+// 🎯 7. Structured Data Breadcrumbs
+const breadcrumbListItems = [
+  {
+    "@type": "ListItem",
+    "position": 1,
+    "name": "Home",
+    "item": `${siteOrigin}/`,
+  },
+];
+
+if (!isHomePage && normalizedSlug) {
+  const segments = normalizedSlug.split("/").filter(Boolean);
+  let currentPath = "";
+
+  segments.forEach((segment, index) => {
+    currentPath += `/${segment}`;
+    const isLast = index === segments.length - 1;
+
+    const fallbackTitle = segment
+      .replace(/-/g, " ")
+      .replace(/\b\w/g, (char) => char.toUpperCase());
+
+    const segmentTitle = isLast && node?.title ? node.title : fallbackTitle;
+
+    breadcrumbListItems.push({
+      "@type": "ListItem",
+      "position": index + 2,
+      "name": segmentTitle,
+      "item": `${siteOrigin}${currentPath}`,
+    });
+  });
+}
+
+// 🎯 8. JSON-LD Schema
+const structuredDataGraph = {
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "Organization",
+      "@id": `${siteOrigin}/#organization`,
+      "name": agencyName || brandName,
+      "url": siteOrigin,
+      "logo": {
+        "@type": "ImageObject",
+        "url": brandLogo,
+        "caption": brandName
+      },
+      "address": {
+        "@type": "PostalAddress",
+        "addressLocality": "",
+        "addressCountry": ""
+      }
+    },
+    {
+      "@type": "SoftwareApplication",
+      "@id": `${siteOrigin}/#application`,
+      "name": brandName,
+      "applicationCategory": "DeveloperApplication",
+      "softwareVersion": "v0.1.0",
+      "operatingSystem": "Cloudflare Workers, Node.js",
+      "description": metaDescription,
+      "url": siteOrigin,
+      "publisher": {
+        "@id": `${siteOrigin}/#organization`
+      },
+    },
+    {
+      "@type": "WebSite",
+      "@id": `${siteOrigin}/#website`,
+      "url": siteOrigin,
+      "name": brandName,
+      "description": metaDescription,
+      "inLanguage": activeLanguage,
+      "publisher": {
+        "@id": `${siteOrigin}/#organization`
+      }
+    },
+    {
+      "@type": "BreadcrumbList",
+      "@id": `${siteOrigin}${normalizedSlug ? `/${normalizedSlug}` : ''}/#breadcrumb`,
+      "itemListElement": breadcrumbListItems
+    }
+  ]
+};
+---
+
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+
+<title>{fullTitle}</title>
+<meta name="description" content={metaDescription} />
+
+<!-- 🎯 Channel Favicon -->
+<link rel="icon" type={getFaviconType(faviconUrl)} href={faviconUrl} />
+
+<link rel="canonical" href={canonicalURL} />
+<link rel="author" type="text/plain" href="/llms.txt" title="LLM Directory" />
+
+<!-- 🎯 Open Graph / Facebook -->
+<meta property="og:type" content={isHomePage ? "website" : "article"} />
+<meta property="og:url" content={canonicalURL} />
+<meta property="og:title" content={fbTitle} />
+<meta property="og:description" content={fbDescription} />
+<meta property="og:image" content={fbImageUrl} />
+<meta property="og:site_name" content={brandName} />
+{ogLocale && <meta property="og:locale" content={ogLocale} />}
+
+<!-- 🎯 X / Twitter -->
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:url" content={canonicalURL} />
+<meta name="twitter:title" content={xTitle} />
+<meta name="twitter:description" content={xDescription} />
+<meta name="twitter:image" content={xImageUrl} />
+
+{lcpImageUrl && (
+  <link
+    rel="preload"
+    as="image"
+    href={lcpImageUrl}
+    fetchpriority="high"
+  />
+)}
+
+<script
+  type="application/ld+json"
+  is:inline
+  set:html={JSON.stringify(structuredDataGraph)}
+/>