@hagicode/hagilight-starlight 0.1.2-dev.8.1.a91b4b9 → 0.1.2-dev.9.1.eccbdf8

package/AIDisclosureNotice.astro

@@ -0,0 +1,12 @@
+---
+import { getAIDisclosureCopy } from './ai-disclosures.mjs';
+const { kind, lang, sourceHref } = Astro.props;
+const copy = getAIDisclosureCopy(lang);
+---
+
+<aside class="hagilight-ai-disclosure" role="note">
+  {kind === 'author' ? copy.author : copy.translation}
+  {kind === 'translation' && sourceHref && (
+    <> <a href={sourceHref}>{copy.source}</a></>
+  )}
+</aside>

package/ContentLayoutToggle.astro

@@ -0,0 +1,31 @@
+---
+import { getContentWidthLabels } from './content-width-i18n.mjs';
+const { lang } = Astro.locals.starlightRoute;
+const labels = getContentWidthLabels(lang);
+---
+
+<div class="hagilight-content-width-toggle" role="group" aria-label={labels.group}>
+  <button type="button" data-hagilight-content-width-choice="wide" aria-pressed="true">
+    {labels.wide}
+  </button>
+  <button type="button" data-hagilight-content-width-choice="narrow" aria-pressed="false">
+    {labels.narrow}
+  </button>
+</div>
+
+<script>
+  import {
+    restoreContentWidth,
+    setContentWidth,
+    synchronizeContentWidthFromStorage,
+  } from './content-width.mjs';
+
+  const root = document.documentElement;
+  restoreContentWidth(root);
+  document.querySelectorAll('[data-hagilight-content-width-choice]').forEach((button) => {
+    button.addEventListener('click', () => {
+      setContentWidth(button.dataset.hagilightContentWidthChoice, root);
+    });
+  });
+  window.addEventListener('storage', (event) => synchronizeContentWidthFromStorage(event, root));
+</script>

package/MarkdownContent.astro

@@ -0,0 +1,36 @@
+---
+import { getCollection } from 'astro:content';
+import DefaultMarkdownContent from '@astrojs/starlight/components/MarkdownContent.astro';
+import AIDisclosureNotice from './AIDisclosureNotice.astro';
+import {
+  getSourcePath,
+  isTranslationLocale,
+  resolveAIDisclosureFlags,
+} from './ai-disclosures.mjs';
+
+const { aiDisclosures = { isAITranslation: false, isAIAuthor: false, sourceLocale: 'root' } } = Astro.props;
+const route = Astro.locals.starlightRoute;
+const isDocsEntry = route.entry.id !== '404' && !route.entry.id.endsWith('/404');
+const flags = isDocsEntry
+  ? resolveAIDisclosureFlags(route.entry.data, aiDisclosures)
+  : { isAITranslation: false, isAIAuthor: false };
+const showTranslation = flags.isAITranslation
+  && isTranslationLocale(route.entryMeta.locale, aiDisclosures.sourceLocale);
+let sourceHref;
+
+if (showTranslation) {
+  const docs = await getCollection('docs');
+  sourceHref = getSourcePath({
+    docs,
+    routeId: route.id,
+    currentLocale: route.locale,
+    sourceLocale: aiDisclosures.sourceLocale,
+    pathname: Astro.url.pathname,
+    baseUrl: import.meta.env.BASE_URL,
+  });
+}
+---
+
+{flags.isAIAuthor && <AIDisclosureNotice kind="author" lang={route.lang} />}
+<DefaultMarkdownContent><slot /></DefaultMarkdownContent>
+{showTranslation && <AIDisclosureNotice kind="translation" lang={route.lang} sourceHref={sourceHref} />}

package/PageTitle.astro

@@ -0,0 +1,7 @@
+---
+import DefaultPageTitle from '@astrojs/starlight/components/PageTitle.astro';
+import ContentLayoutToggle from './ContentLayoutToggle.astro';
+---
+
+<DefaultPageTitle />
+<ContentLayoutToggle />

package/ai-disclosure-schema.mjs

@@ -0,0 +1,9 @@
+import { z } from 'astro/zod';
+
+const aiDisclosureSchema = z.object({
+  isAITranslation: z.boolean().optional(),
+  isAIAuthor: z.boolean().optional(),
+});
+
+export { aiDisclosureSchema };
+export default aiDisclosureSchema;

package/ai-disclosures.mjs

@@ -0,0 +1,108 @@
+const COPY = {
+  'de-DE': {
+    author: 'Dieser Inhalt wurde mit KI-Unterstützung erstellt. Bitte prüfen Sie wichtige Angaben.',
+    translation: 'Dieser Beitrag wurde mit KI übersetzt.',
+    source: 'Original ansehen',
+  },
+  'en-US': {
+    author: 'This content was created with AI assistance. Please verify important details.',
+    translation: 'This post was translated with AI.',
+    source: 'View source',
+  },
+  'es-ES': {
+    author: 'Este contenido se creó con ayuda de IA. Verifica los detalles importantes.',
+    translation: 'Esta publicación se tradujo con IA.',
+    source: 'Ver original',
+  },
+  'fr-FR': {
+    author: 'Ce contenu a été créé avec l’aide de l’IA. Vérifiez les informations importantes.',
+    translation: 'Cet article a été traduit avec l’IA.',
+    source: 'Voir la source',
+  },
+  'ja-JP': {
+    author: 'この記事は AI の支援を受けて作成されました。重要な情報はご確認ください。',
+    translation: 'この記事は AI によって翻訳されました。',
+    source: '原文を見る',
+  },
+  'ko-KR': {
+    author: '이 콘텐츠는 AI의 도움을 받아 작성되었습니다. 중요한 세부 정보는 확인해 주세요.',
+    translation: '이 게시물은 AI로 번역되었습니다.',
+    source: '원문 보기',
+  },
+  'pt-BR': {
+    author: 'Este conteúdo foi criado com auxílio de IA. Confira os detalhes importantes.',
+    translation: 'Esta publicação foi traduzida com IA.',
+    source: 'Ver original',
+  },
+  'ru-RU': {
+    author: 'Этот материал создан с помощью ИИ. Проверьте важные сведения.',
+    translation: 'Эта публикация переведена с помощью ИИ.',
+    source: 'Открыть оригинал',
+  },
+  'zh-CN': {
+    author: '本文内容由 AI 辅助创作。请核实重要信息。',
+    translation: '本文由 AI 翻译。',
+    source: '查看原文',
+  },
+  'zh-Hant': {
+    author: '本文內容由 AI 輔助創作。請核實重要資訊。',
+    translation: '本文由 AI 翻譯。',
+    source: '查看原文',
+  },
+};
+
+export function resolveAIDisclosureFlags(frontmatter, defaults) {
+  for (const key of ['isAITranslation', 'isAIAuthor']) {
+    if (frontmatter[key] !== undefined && typeof frontmatter[key] !== 'boolean') {
+      throw new TypeError(`Hagilight frontmatter ${key} must be a boolean.`);
+    }
+    if (typeof defaults[key] !== 'boolean') {
+      throw new TypeError(`Hagilight aiDisclosures ${key} default must be a boolean.`);
+    }
+  }
+  return {
+    isAITranslation: frontmatter.isAITranslation ?? defaults.isAITranslation,
+    isAIAuthor: frontmatter.isAIAuthor ?? defaults.isAIAuthor,
+  };
+}
+
+export function getAIDisclosureCopy(lang) {
+  if (COPY[lang]) return COPY[lang];
+  const language = lang?.split('-')[0];
+  return COPY[language] ?? COPY['en-US'];
+}
+
+export function getSourceEntryId(routeId, currentLocale, sourceLocale) {
+  const prefix = currentLocale && currentLocale !== 'root' ? `${currentLocale}/` : '';
+  const routeSlug = prefix && routeId.startsWith(prefix) ? routeId.slice(prefix.length) : routeId;
+  if (sourceLocale === 'root') return routeSlug === 'index' ? '' : routeSlug;
+  return `${sourceLocale}/${routeSlug || 'index'}`;
+}
+
+export function normalizeDocsEntryId(id) {
+  return id === 'index' ? '' : id;
+}
+
+export function getSourcePath({ docs, routeId, currentLocale, sourceLocale, pathname, baseUrl }) {
+  const sourceId = getSourceEntryId(routeId, currentLocale, sourceLocale);
+  if (!docs.some((entry) => normalizeDocsEntryId(entry.id) === sourceId)) return undefined;
+  return buildSourcePathname(pathname, baseUrl, currentLocale, sourceLocale);
+}
+
+export function isTranslationLocale(locale, sourceLocale) {
+  return (locale ?? 'root') !== sourceLocale;
+}
+
+export function buildSourcePathname(pathname, baseUrl, currentLocale, sourceLocale) {
+  const basePath = new URL(baseUrl, 'https://hagilight.invalid').pathname;
+  const normalizedBase = basePath.endsWith('/') ? basePath : `${basePath}/`;
+  const relativePath = pathname.startsWith(normalizedBase)
+    ? pathname.slice(normalizedBase.length)
+    : pathname.startsWith('/') ? pathname.slice(1) : pathname;
+  const segments = relativePath.split('/');
+  if (currentLocale && currentLocale !== 'root' && segments[0] === currentLocale) segments.shift();
+  if (sourceLocale !== 'root') segments.unshift(sourceLocale);
+  return `${normalizedBase}${segments.join('/')}`;
+}
+
+export { COPY };

package/content-width-i18n.mjs

@@ -0,0 +1,16 @@
+const labels = {
+  'de-DE': { group: 'Inhaltsbreite', wide: 'Breit', narrow: 'Schmal' },
+  'en-US': { group: 'Content width', wide: 'Wide', narrow: 'Narrow' },
+  'es-ES': { group: 'Ancho del contenido', wide: 'Ancho', narrow: 'Estrecho' },
+  'fr-FR': { group: 'Largeur du contenu', wide: 'Large', narrow: 'Étroit' },
+  'ja-JP': { group: 'コンテンツ幅', wide: '広い', narrow: '狭い' },
+  'ko-KR': { group: '콘텐츠 너비', wide: '넓게', narrow: '좁게' },
+  'pt-BR': { group: 'Largura do conteúdo', wide: 'Ampla', narrow: 'Estreita' },
+  'ru-RU': { group: 'Ширина содержимого', wide: 'Широкая', narrow: 'Узкая' },
+  'zh-CN': { group: '内容宽度', wide: '宽', narrow: '窄' },
+  'zh-Hant': { group: '內容寬度', wide: '寬', narrow: '窄' },
+};
+
+export function getContentWidthLabels(lang) {
+  return labels[lang] ?? labels['en-US'];
+}

package/content-width.css

@@ -0,0 +1,51 @@
+@media (min-width: 50em) {
+  :root[data-hagilight-content-width='wide'] {
+    --sl-content-width: min(67.5rem, calc(100vw - 2rem));
+  }
+
+  .hagilight-content-width-toggle {
+    display: inline-flex;
+    gap: 0.25rem;
+    padding: 0.25rem;
+    border: 1px solid var(--sl-color-hairline);
+    border-radius: 0.5rem;
+    background: var(--sl-color-bg-sidebar);
+  }
+
+  .hagilight-content-width-toggle button {
+    border: 0;
+    border-radius: 0.25rem;
+    padding: 0.35rem 0.75rem;
+    color: var(--sl-color-text);
+    background: transparent;
+    cursor: pointer;
+  }
+
+  .hagilight-content-width-toggle button[aria-pressed='true'] {
+    color: var(--sl-color-text-invert);
+    background: var(--sl-color-bg-accent);
+  }
+
+  .hagilight-content-width-toggle button:focus-visible {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 2px;
+  }
+}
+
+@media (max-width: 49.999em) {
+  .hagilight-content-width-toggle {
+    display: none;
+  }
+}
+
+.hagilight-ai-disclosure {
+  border-inline-start: 0.25rem solid var(--sl-color-accent);
+  padding: 0.75rem 1rem;
+  color: var(--sl-color-text);
+  background: var(--sl-color-bg-sidebar);
+  font-size: var(--sl-text-sm);
+}
+
+.hagilight-ai-disclosure a {
+  margin-inline-start: 0.5rem;
+}

package/content-width.mjs

@@ -0,0 +1,46 @@
+const STORAGE_KEY = 'hagilight-content-width';
+const VALID_MODES = new Set(['wide', 'narrow']);
+
+function normalizeMode(value) {
+  return VALID_MODES.has(value) ? value : 'wide';
+}
+
+export function restoreContentWidth(root = document.documentElement) {
+  let mode = 'wide';
+  try {
+    mode = normalizeMode(globalThis.localStorage.getItem(STORAGE_KEY));
+  } catch {
+    mode = 'wide';
+  }
+  root.dataset.hagilightContentWidth = mode;
+  synchronizeButtons(root, mode);
+  return mode;
+}
+
+export function setContentWidth(mode, root = document.documentElement) {
+  if (!VALID_MODES.has(mode)) {
+    throw new TypeError('Hagilight content width must be "wide" or "narrow".');
+  }
+  root.dataset.hagilightContentWidth = mode;
+  synchronizeButtons(root, mode);
+  try {
+    globalThis.localStorage.setItem(STORAGE_KEY, mode);
+  } catch {
+    return;
+  }
+}
+
+export function synchronizeContentWidthFromStorage(event, root = document.documentElement) {
+  if (event.key !== STORAGE_KEY && event.key !== null) return;
+  const mode = normalizeMode(event.newValue);
+  root.dataset.hagilightContentWidth = mode;
+  synchronizeButtons(root, mode);
+}
+
+function synchronizeButtons(root, mode) {
+  root.querySelectorAll('[data-hagilight-content-width-choice]').forEach((button) => {
+    button.setAttribute('aria-pressed', String(button.dataset.hagilightContentWidthChoice === mode));
+  });
+}
+
+export { STORAGE_KEY };

package/index.mjs

@@ -3,18 +3,30 @@ 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;
+const DEFAULT_GOOGLE_ANALYTICS_ID = 'G-EN03FMT2Q4';
+const DEFAULT_51LA_ID = 'L6b88a5yK4h2Xnci';
 const defaultLogo = fileURLToPath(import.meta.resolve('@hagicode/hagilight/logo.png'));
+const contentWidthCssPath = fileURLToPath(new URL('./content-width.css', import.meta.url));
+const contentWidthHeadScript = `(() => {
+  let mode = 'wide';
+  try {
+    const stored = localStorage.getItem('hagilight-content-width');
+    if (stored === 'wide' || stored === 'narrow') mode = stored;
+  } catch {
+    mode = 'wide';
+  }
+  document.documentElement.dataset.hagilightContentWidth = mode;
+})();`;
 
-function resolveProvider(config, { name, idKey, pattern }) {
-  if (config === undefined) return undefined;
-  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+function resolveProvider(config, { name, idKey, pattern, defaultId }) {
+  if (config !== undefined && (!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]);
+  const enabled = config === undefined ? true : config.enabled ?? Boolean(config[idKey]);
   if (!enabled) return undefined;
 
-  const id = config[idKey];
+  const id = config === undefined ? defaultId : config[idKey];
   if (typeof id !== 'string' || !id.trim()) {
     throw new Error(`Hagilight ${name} analytics is enabled but its ${idKey} is missing.`);
   }
@@ -24,12 +36,41 @@ function resolveProvider(config, { name, idKey, pattern }) {
   return id;
 }
 
+function resolveAIDisclosures(config) {
+  if (config === undefined) {
+    return {
+      isAITranslation: false,
+      isAIAuthor: false,
+      sourceLocale: 'root',
+    };
+  }
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new TypeError('Hagilight aiDisclosures options must be an object.');
+  }
+  for (const key of ['isAITranslation', 'isAIAuthor']) {
+    if (config[key] !== undefined && typeof config[key] !== 'boolean') {
+      throw new TypeError(`Hagilight aiDisclosures ${key} option must be a boolean.`);
+    }
+  }
+  const sourceLocale = config.sourceLocale === undefined ? 'root' : config.sourceLocale;
+  if (typeof sourceLocale !== 'string' || !sourceLocale.trim() || /[/\\]/u.test(sourceLocale)) {
+    throw new TypeError('Hagilight aiDisclosures sourceLocale option must be a non-empty string.');
+  }
+  return {
+    isAITranslation: config.isAITranslation ?? false,
+    isAIAuthor: config.isAIAuthor ?? false,
+    sourceLocale: sourceLocale.trim(),
+  };
+}
+
 function createConfiguredIntegration(instanceId, serializedOptions, componentIds) {
   const optionsId = `virtual:hagilight-starlight/${instanceId}/options`;
   const headerPath = componentIds.header
     ? fileURLToPath(new URL('./Header.astro', import.meta.url))
     : undefined;
   const footerPath = fileURLToPath(new URL('./Footer.astro', import.meta.url));
+  const pageTitlePath = fileURLToPath(new URL('./PageTitle.astro', import.meta.url));
+  const markdownContentPath = fileURLToPath(new URL('./MarkdownContent.astro', import.meta.url));
   const headerSource = headerPath
     ? `---
 import Header from ${JSON.stringify(headerPath)};
@@ -59,6 +100,19 @@ import options from '${optionsId}';
 <Footer locale={Astro.locals?.starlightRoute?.locale} links={options.links} />
 ${promotionRender}
 ${analyticsRender}
+`;
+  const pageTitleSource = `---
+import PageTitle from ${JSON.stringify(pageTitlePath)};
+---
+
+<PageTitle />
+`;
+  const markdownContentSource = `---
+import MarkdownContent from ${JSON.stringify(markdownContentPath)};
+import options from '${optionsId}';
+---
+
+<MarkdownContent aiDisclosures={options.aiDisclosures}><slot /></MarkdownContent>
 `;
   const headSource = `---
 import DefaultHead from '@astrojs/starlight/components/Head.astro';
@@ -75,6 +129,8 @@ const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
   const modules = new Map([
     ...(componentIds.header ? [[componentIds.header, headerSource]] : []),
     [componentIds.footer, footerSource],
+    ...(componentIds.pageTitle ? [[componentIds.pageTitle, pageTitleSource]] : []),
+    ...(componentIds.markdownContent ? [[componentIds.markdownContent, markdownContentSource]] : []),
     ...(componentIds.head ? [[componentIds.head, headSource]] : []),
     [optionsId, `export default ${JSON.stringify(serializedOptions)};`],
   ]);
@@ -113,24 +169,42 @@ export default function hagilight(options = {}) {
     && (!options.analytics || typeof options.analytics !== 'object' || Array.isArray(options.analytics))) {
     throw new TypeError('Hagilight analytics options must be an object.');
   }
+  if (options.contentComponents !== undefined
+    && (!options.contentComponents || typeof options.contentComponents !== 'object' || Array.isArray(options.contentComponents))) {
+    throw new TypeError('Hagilight contentComponents options must be an object.');
+  }
+  for (const key of ['pageTitle', 'markdownContent']) {
+    if (options.contentComponents?.[key] !== undefined && typeof options.contentComponents[key] !== 'boolean') {
+      throw new TypeError(`Hagilight contentComponents ${key} option must be a boolean.`);
+    }
+  }
   const analytics = options.analytics ?? {};
+  const aiDisclosures = resolveAIDisclosures(options.aiDisclosures);
   const googleAnalyticsMeasurementId = resolveProvider(analytics.googleAnalytics, {
     name: 'Google Analytics',
     idKey: 'measurementId',
     pattern: GOOGLE_ID_PATTERN,
+    defaultId: DEFAULT_GOOGLE_ANALYTICS_ID,
   });
   const fiftyOneLaId = resolveProvider(analytics.fiftyOneLa, {
     name: '51LA',
     idKey: 'siteId',
     pattern: FIFTY_ONE_LA_ID_PATTERN,
+    defaultId: DEFAULT_51LA_ID,
   });
   const instanceId = randomUUID();
   const headerEnabled = options.header?.enabled !== false;
+  const pageTitleEnabled = options.contentComponents?.pageTitle !== false;
+  const markdownContentEnabled = options.contentComponents?.markdownContent !== false;
   const componentIds = {
     header: headerEnabled
       ? `virtual:hagilight-starlight/${instanceId}/Header.astro`
       : undefined,
     footer: `virtual:hagilight-starlight/${instanceId}/Footer.astro`,
+    pageTitle: pageTitleEnabled ? `virtual:hagilight-starlight/${instanceId}/PageTitle.astro` : undefined,
+    markdownContent: markdownContentEnabled
+      ? `virtual:hagilight-starlight/${instanceId}/MarkdownContent.astro`
+      : undefined,
     head: googleAnalyticsMeasurementId
       ? `virtual:hagilight-starlight/${instanceId}/Head.astro`
       : undefined,
@@ -140,6 +214,7 @@ export default function hagilight(options = {}) {
     links: options.links ?? {},
     googleAnalyticsMeasurementId,
     fiftyOneLaId,
+    aiDisclosures,
   };
 
   return {
@@ -152,6 +227,12 @@ export default function hagilight(options = {}) {
         if (config.components?.Footer) {
           throw new Error('Hagilight cannot replace an existing Starlight Footer override.');
         }
+        if (pageTitleEnabled && config.components?.PageTitle) {
+          throw new Error('Hagilight cannot replace an existing Starlight PageTitle override. Set contentComponents: { pageTitle: false } and compose @hagicode/hagilight-starlight/ContentLayoutToggle into your PageTitle component.');
+        }
+        if (markdownContentEnabled && config.components?.MarkdownContent) {
+          throw new Error('Hagilight cannot replace an existing Starlight MarkdownContent override. Set contentComponents: { markdownContent: false } and compose @hagicode/hagilight-starlight/MarkdownContent into your MarkdownContent component.');
+        }
         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.');
         }
@@ -159,10 +240,17 @@ export default function hagilight(options = {}) {
         addIntegration(createConfiguredIntegration(instanceId, serializedOptions, componentIds));
         updateConfig({
           ...(config.logo === undefined ? { logo: { src: defaultLogo, alt: 'HagiCode' } } : {}),
+          customCss: [...(config.customCss ?? []), contentWidthCssPath],
+          head: [
+            ...(config.head ?? []),
+            { tag: 'script', content: contentWidthHeadScript },
+          ],
           components: {
             ...config.components,
             ...(componentIds.header ? { Header: componentIds.header } : {}),
             Footer: componentIds.footer,
+            ...(componentIds.pageTitle ? { PageTitle: componentIds.pageTitle } : {}),
+            ...(componentIds.markdownContent ? { MarkdownContent: componentIds.markdownContent } : {}),
             ...(componentIds.head ? { Head: componentIds.head } : {}),
           },
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.1.2-dev.8.1.a91b4b9",
+  "version": "0.1.2-dev.9.1.eccbdf8",
   "type": "module",
   "description": "Starlight customizations for HagiCode documentation",
   "repository": {
@@ -14,17 +14,22 @@
   },
   "exports": {
     ".": "./index.mjs",
+    "./ai-disclosure-schema": "./ai-disclosure-schema.mjs",
+    "./ContentLayoutToggle": "./ContentLayoutToggle.astro",
     "./Header": "./Header.astro",
     "./Footer": "./Footer.astro",
+    "./MarkdownContent": "./MarkdownContent.astro",
+    "./PageTitle": "./PageTitle.astro",
     "./PromotoFooter": "./PromotoFooter.astro"
   },
   "files": [
     "index.mjs",
+    "*.css",
     "*.mjs",
     "*.astro"
   ],
   "dependencies": {
-    "@hagicode/hagilight": "0.1.2-dev.8.1.a91b4b9"
+    "@hagicode/hagilight": "0.1.2-dev.9.1.eccbdf8"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",