@hagicode/hagilight-starlight 0.1.2-dev.5.1.c41051d → 0.1.2-dev.6.1.f3f7b3d

package/Footer.astro

@@ -1,12 +1,82 @@
 ---
 import Copyright from '@hagicode/hagilight/Copyright';
 import DefaultFooter from '@astrojs/starlight/components/Footer.astro';
+import { resolveSiteLinks, type SiteLinksOptions } from '@hagicode/hagilight/site-links';
+
+interface Props {
+  locale?: string;
+  links?: SiteLinksOptions;
+}
+
+const { locale = Astro.locals?.starlightRoute?.locale, links } = Astro.props;
+const resolvedLinks = resolveSiteLinks(locale, links);
 ---
 
 <DefaultFooter />
+<nav class="hagilight-site-links" aria-label={resolvedLinks.labels.quickLinks}>
+  {resolvedLinks.relatedSites.length > 0 && (
+    <section>
+      <h2>{resolvedLinks.labels.relatedSites}</h2>
+      <ul>
+        {resolvedLinks.relatedSites.map((site) => (
+          <li><a href={site.href}>{site.name}</a></li>
+        ))}
+      </ul>
+    </section>
+  )}
+  <section>
+    <h2>{resolvedLinks.labels.quickLinks}</h2>
+    <ul>
+      {resolvedLinks.quick.map((link) => (
+        <li><a href={link.href} target={link.target} rel={link.rel}>{link.label}</a></li>
+      ))}
+    </ul>
+  </section>
+  <section>
+    <h2>{resolvedLinks.labels.community}</h2>
+    <ul>
+      {resolvedLinks.community.map((link) => (
+        <li><a href={link.href} target={link.target} rel={link.rel}>{link.label}</a></li>
+      ))}
+    </ul>
+  </section>
+</nav>
 <p class="hagilight-copyright"><Copyright name="HagiCode" /></p>
 
 <style>
+  .hagilight-site-links {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
+    gap: 1.5rem;
+    margin: 2rem auto 1rem;
+    max-width: 72rem;
+    padding-inline: 1rem;
+  }
+
+  .hagilight-site-links h2 {
+    margin: 0 0 0.75rem;
+    color: var(--sl-color-white);
+    font-size: var(--sl-text-sm);
+  }
+
+  .hagilight-site-links ul {
+    display: grid;
+    gap: 0.5rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .hagilight-site-links a {
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-sm);
+    text-decoration: none;
+  }
+
+  .hagilight-site-links a:hover {
+    color: var(--sl-color-white);
+  }
+
   .hagilight-copyright {
     margin-block: 1rem;
     color: var(--sl-color-gray-3);

package/index.mjs

@@ -1,19 +1,139 @@
+import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
+const GOOGLE_ID_PATTERN = /^G-[A-Z0-9]+$/u;
+const FIFTY_ONE_LA_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;
+
+function resolveProvider(config, { name, idKey, pattern }) {
+  if (config === undefined) return undefined;
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new TypeError(`Hagilight ${name} analytics options must be an object.`);
+  }
+
+  const enabled = config.enabled ?? Boolean(config[idKey]);
+  if (!enabled) return undefined;
+
+  const id = config[idKey];
+  if (typeof id !== 'string' || !id.trim()) {
+    throw new Error(`Hagilight ${name} analytics is enabled but its ${idKey} is missing.`);
+  }
+  if (!pattern.test(id)) {
+    throw new Error(`Hagilight ${name} analytics ${idKey} has an invalid format.`);
+  }
+  return id;
+}
+
+function createConfiguredIntegration(instanceId, serializedOptions, componentIds) {
+  const optionsId = `virtual:hagilight-starlight/${instanceId}/options`;
+  const footerPath = fileURLToPath(new URL('./Footer.astro', import.meta.url));
+  const promotionImport = serializedOptions.promotoEnabled
+    ? "import PromotoBanner from '@hagicode/hagilight/PromotoBanner';"
+    : '';
+  const promotionRender = serializedOptions.promotoEnabled ? '<PromotoBanner />' : '';
+  const analyticsImport = serializedOptions.fiftyOneLaId
+    ? "import Analytics51LA from '@hagicode/hagilight/Analytics51LA';"
+    : '';
+  const analyticsRender = serializedOptions.fiftyOneLaId
+    ? '<Analytics51LA siteId={options.fiftyOneLaId} />'
+    : '';
+  const footerSource = `---
+import Footer from ${JSON.stringify(footerPath)};
+${promotionImport}
+${analyticsImport}
+import options from '${optionsId}';
+---
+
+<Footer locale={Astro.locals?.starlightRoute?.locale} links={options.links} />
+${promotionRender}
+${analyticsRender}
+`;
+  const headSource = `---
+import DefaultHead from '@astrojs/starlight/components/Head.astro';
+import GoogleAnalytics from '@hagicode/hagilight/GoogleAnalytics';
+import options from '${optionsId}';
+const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
+---
+
+<DefaultHead />
+{!isNotFound && options.googleAnalyticsMeasurementId && (
+  <GoogleAnalytics measurementId={options.googleAnalyticsMeasurementId} />
+)}
+`;
+  const modules = new Map([
+    [componentIds.footer, footerSource],
+    ...(componentIds.head ? [[componentIds.head, headSource]] : []),
+    [optionsId, `export default ${JSON.stringify(serializedOptions)};`],
+  ]);
+  const vitePlugin = {
+    name: `@hagicode/hagilight-starlight:${instanceId}`,
+    resolveId(id) {
+      return modules.has(id) ? `\0${id}` : null;
+    },
+    load(id) {
+      return id.startsWith('\0') ? modules.get(id.slice(1)) ?? null : null;
+    },
+  };
+
+  return {
+    name: `@hagicode/hagilight-starlight:${instanceId}`,
+    hooks: {
+      'astro:config:setup'({ updateConfig }) {
+        updateConfig({ vite: { plugins: [vitePlugin] } });
+      },
+    },
+  };
+}
+
 export default function hagilight(options = {}) {
-  const footer = options.promoto?.enabled === false ? 'Footer.astro' : 'PromotoFooter.astro';
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('Hagilight Starlight options must be an object.');
+  }
+  if (options.analytics !== undefined
+    && (!options.analytics || typeof options.analytics !== 'object' || Array.isArray(options.analytics))) {
+    throw new TypeError('Hagilight analytics options must be an object.');
+  }
+  const analytics = options.analytics ?? {};
+  const googleAnalyticsMeasurementId = resolveProvider(analytics.googleAnalytics, {
+    name: 'Google Analytics',
+    idKey: 'measurementId',
+    pattern: GOOGLE_ID_PATTERN,
+  });
+  const fiftyOneLaId = resolveProvider(analytics.fiftyOneLa, {
+    name: '51LA',
+    idKey: 'siteId',
+    pattern: FIFTY_ONE_LA_ID_PATTERN,
+  });
+  const instanceId = randomUUID();
+  const componentIds = {
+    footer: `virtual:hagilight-starlight/${instanceId}/Footer.astro`,
+    head: googleAnalyticsMeasurementId
+      ? `virtual:hagilight-starlight/${instanceId}/Head.astro`
+      : undefined,
+  };
+  const serializedOptions = {
+    promotoEnabled: options.promoto?.enabled !== false,
+    links: options.links ?? {},
+    googleAnalyticsMeasurementId,
+    fiftyOneLaId,
+  };
+
   return {
     name: '@hagicode/hagilight-starlight',
     hooks: {
-      'config:setup'({ config, updateConfig }) {
+      'config:setup'({ config, updateConfig, addIntegration }) {
         if (config.components?.Footer) {
           throw new Error('Hagilight cannot replace an existing Starlight Footer override.');
         }
+        if (googleAnalyticsMeasurementId && config.components?.Head) {
+          throw new Error('Hagilight Google Analytics cannot replace an existing Starlight Head override. Compose @hagicode/hagilight/GoogleAnalytics in your Head instead.');
+        }
 
+        addIntegration(createConfiguredIntegration(instanceId, serializedOptions, componentIds));
         updateConfig({
           components: {
             ...config.components,
-            Footer: fileURLToPath(new URL(`./${footer}`, import.meta.url)),
+            Footer: componentIds.footer,
+            ...(componentIds.head ? { Head: componentIds.head } : {}),
           },
         });
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.1.2-dev.5.1.c41051d",
+  "version": "0.1.2-dev.6.1.f3f7b3d",
   "type": "module",
   "description": "Starlight customizations for HagiCode documentation",
   "repository": {
@@ -22,7 +22,7 @@
     "*.astro"
   ],
   "dependencies": {
-    "@hagicode/hagilight": "0.1.2-dev.5.1.c41051d"
+    "@hagicode/hagilight": "0.1.2-dev.6.1.f3f7b3d"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",