@hagicode/hagilight-starlight 0.1.0-dev.148.1.e0c630e

package/dist/language-routing.js

@@ -0,0 +1,95 @@
+import { locales } from './locales.js';
+export const DEFAULT_LANGUAGE_OPTIONS = Object.entries(locales).map(([code, locale]) => ({
+    code,
+    label: locale.label,
+    lang: locale.lang,
+}));
+const normalizeLang = (lang) => lang?.replaceAll('_', '-').toLowerCase();
+export function getConfiguredLanguageOptions(configuredLocales, currentLocale) {
+    const catalog = DEFAULT_LANGUAGE_OPTIONS;
+    return Object.entries(configuredLocales ?? {})
+        .map(([code, locale]) => {
+        const lang = typeof locale === 'string' ? locale : locale?.lang ?? code;
+        const catalogEntry = catalog.find((entry) => entry.code === code || normalizeLang(entry.lang) === normalizeLang(lang));
+        return {
+            code,
+            label: typeof locale === 'object' && locale?.label
+                ? locale.label
+                : catalogEntry?.label ?? code,
+            lang,
+            selected: code === currentLocale,
+            catalogOrder: catalogEntry ? catalog.indexOf(catalogEntry) : catalog.length,
+        };
+    })
+        .sort((left, right) => left.catalogOrder - right.catalogOrder)
+        .map(({ catalogOrder: _catalogOrder, ...option }) => option);
+}
+export function getKeyboardTargetIndex(index, key, count) {
+    if (count < 1)
+        return -1;
+    switch (key) {
+        case 'ArrowDown':
+        case 'ArrowRight':
+            return (index + 1) % count;
+        case 'ArrowUp':
+        case 'ArrowLeft':
+            return (index - 1 + count) % count;
+        case 'Home':
+            return 0;
+        case 'End':
+            return count - 1;
+        default:
+            return index;
+    }
+}
+export function buildLocaleNavigationTarget(currentUrl, targetLocale, configuredLocales, basePath = '/', trailingSlash = 'ignore') {
+    const targetUrl = new URL(currentUrl);
+    const base = basePath.replace(/\/+$/u, '');
+    const hasBase = base === ''
+        ? true
+        : targetUrl.pathname === base || targetUrl.pathname.startsWith(`${base}/`);
+    let pathname = hasBase ? targetUrl.pathname.slice(base.length) || '/' : targetUrl.pathname;
+    const [, firstSegment = '', remainder = ''] = pathname.match(/^\/([^/]*)(.*)$/u) ?? [];
+    const isHtmlRoute = firstSegment.endsWith('.html');
+    const currentSlug = isHtmlRoute ? firstSegment.slice(0, -5) : firstSegment;
+    const currentLocale = configuredLocales.find((locale) => locale !== 'root' && locale === currentSlug);
+    if (currentLocale) {
+        if (targetLocale === 'root') {
+            pathname = isHtmlRoute ? '/index.html' : remainder || '/';
+        }
+        else {
+            pathname = `/${targetLocale}${isHtmlRoute ? '.html' : remainder}`;
+        }
+    }
+    else if (targetLocale !== 'root') {
+        pathname = firstSegment === 'index.html'
+            ? `/${targetLocale}.html`
+            : `/${targetLocale}${pathname}`;
+    }
+    targetUrl.pathname = `${hasBase ? base : ''}${pathname}` || '/';
+    if (trailingSlash === 'never') {
+        targetUrl.pathname = targetUrl.pathname.replace(/\/+$/u, '') || '/';
+    }
+    return targetUrl;
+}
+export function persistStarlightLocaleSelection(locale) {
+    try {
+        const storedValue = window.localStorage.getItem('starlight-route');
+        let routePreference = {};
+        if (storedValue) {
+            try {
+                const parsed = JSON.parse(storedValue);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    routePreference = parsed;
+                }
+            }
+            catch {
+                routePreference = {};
+            }
+        }
+        window.localStorage.setItem('starlight-route', JSON.stringify({ ...routePreference, lang: locale }));
+    }
+    catch {
+        // Language navigation must remain available when browser storage is blocked.
+    }
+}

package/dist/locales.d.ts

@@ -0,0 +1,48 @@
+export interface LocaleDefinition {
+    label: string;
+    lang: string;
+}
+/** Starlight `locales` map for every language HagiCode documentation publishes. */
+export declare const locales: {
+    readonly root: {
+        readonly label: "English";
+        readonly lang: "en-US";
+    };
+    readonly 'zh-CN': {
+        readonly label: "简体中文";
+        readonly lang: "zh-CN";
+    };
+    readonly 'zh-Hant': {
+        readonly label: "繁體中文";
+        readonly lang: "zh-Hant";
+    };
+    readonly 'fr-FR': {
+        readonly label: "Français";
+        readonly lang: "fr-FR";
+    };
+    readonly 'de-DE': {
+        readonly label: "Deutsch";
+        readonly lang: "de-DE";
+    };
+    readonly 'es-ES': {
+        readonly label: "Español (España)";
+        readonly lang: "es-ES";
+    };
+    readonly 'ja-JP': {
+        readonly label: "日本語";
+        readonly lang: "ja-JP";
+    };
+    readonly 'ko-KR': {
+        readonly label: "한국어";
+        readonly lang: "ko-KR";
+    };
+    readonly 'pt-BR': {
+        readonly label: "Português (Brasil)";
+        readonly lang: "pt-BR";
+    };
+    readonly 'ru-RU': {
+        readonly label: "Русский";
+        readonly lang: "ru-RU";
+    };
+};
+export type HagicodeLocaleKey = keyof typeof locales;

package/dist/locales.js

@@ -0,0 +1,13 @@
+/** Starlight `locales` map for every language HagiCode documentation publishes. */
+export const locales = {
+    root: { label: 'English', lang: 'en-US' },
+    'zh-CN': { label: '简体中文', lang: 'zh-CN' },
+    'zh-Hant': { label: '繁體中文', lang: 'zh-Hant' },
+    'fr-FR': { label: 'Français', lang: 'fr-FR' },
+    'de-DE': { label: 'Deutsch', lang: 'de-DE' },
+    'es-ES': { label: 'Español (España)', lang: 'es-ES' },
+    'ja-JP': { label: '日本語', lang: 'ja-JP' },
+    'ko-KR': { label: '한국어', lang: 'ko-KR' },
+    'pt-BR': { label: 'Português (Brasil)', lang: 'pt-BR' },
+    'ru-RU': { label: 'Русский', lang: 'ru-RU' },
+};

package/dist/not-found.d.ts

@@ -0,0 +1,9 @@
+export type TrailingSlash = 'always' | 'never' | 'ignore';
+export declare function isNotFoundEntry(entryId: string): boolean;
+export interface NotFoundHomeHrefOptions {
+    basePath?: string;
+    locale?: string | undefined;
+    trailingSlash?: TrailingSlash;
+}
+export declare function getNotFoundHomeHref({ basePath, locale, trailingSlash }: NotFoundHomeHrefOptions): string;
+export declare function getNotFoundHomeLabel(lang: string | undefined): string;

package/dist/not-found.js

@@ -0,0 +1,28 @@
+const homeLabels = {
+    de: 'Zur Startseite',
+    en: 'Back to home',
+    es: 'Volver al inicio',
+    fr: 'Retour à l’accueil',
+    ja: 'ホームに戻る',
+    ko: '홈으로 돌아가기',
+    pt: 'Voltar ao início',
+    ru: 'На главную',
+    'zh-cn': '返回首页',
+    'zh-hant': '返回首頁',
+};
+export function isNotFoundEntry(entryId) {
+    return entryId === '404' || entryId.endsWith('/404');
+}
+export function getNotFoundHomeHref({ basePath = '/', locale, trailingSlash = 'ignore' }) {
+    const base = basePath.replace(/\/+$/u, '');
+    const localePath = locale && locale !== 'root' ? `/${locale}` : '';
+    const path = `${base}${localePath}` || '/';
+    if (trailingSlash === 'never') {
+        return path.replace(/\/+$/u, '') || '/';
+    }
+    return `${path.replace(/\/+$/u, '')}/`;
+}
+export function getNotFoundHomeLabel(lang) {
+    const language = lang?.replaceAll('_', '-').toLowerCase() ?? 'en';
+    return homeLabels[language] ?? homeLabels[language.split('-')[0]] ?? homeLabels.en;
+}

package/dist/rss-renderer.d.ts

@@ -0,0 +1,14 @@
+import { type RssLocale } from '@hagicode/hagilight-core/rss';
+import { type ResolvedRssContentOptions, type RssDocsEntry } from './rss-utils.js';
+/** Serialized configuration exposed to the Starlight RSS routes. */
+export interface StarlightRssRuntimeConfig {
+    options: ResolvedRssContentOptions;
+    locales: readonly RssLocale[];
+}
+export interface StarlightRssFeedInput extends StarlightRssRuntimeConfig {
+    site: string | URL | undefined;
+    baseUrl: string;
+    filename: string | undefined;
+    entries: readonly RssDocsEntry[];
+}
+export declare function generateRssFeed({ site, baseUrl, filename, locales, options, entries, }: StarlightRssFeedInput): Promise<Response>;

package/dist/rss-renderer.js

@@ -0,0 +1,30 @@
+import { generateRssFeed as generateCoreRssFeed } from '@hagicode/hagilight-core/rss';
+import { selectRssEntries } from './rss-utils.js';
+export function generateRssFeed({ site, baseUrl, filename, locales, options, entries, }) {
+    if (!site)
+        throw new Error('Hagilight RSS requires the Astro site option.');
+    const locale = locales.find((item) => item.filename === filename);
+    if (!locale && filename !== 'en') {
+        throw new Error(`Hagilight RSS has no configured locale for "${filename}".`);
+    }
+    const items = selectRssEntries(entries, { filename, locales, options }).map(({ id, data }) => {
+        const slug = id.replace(/(?:^|\/)index$/u, '');
+        const lastUpdated = data.lastUpdated;
+        return {
+            title: data.title,
+            description: data.description,
+            ...(lastUpdated instanceof Date && !Number.isNaN(lastUpdated.getTime())
+                ? { date: lastUpdated }
+                : {}),
+            link: slug ? `${slug}/` : '/',
+        };
+    });
+    return generateCoreRssFeed({
+        site,
+        baseUrl,
+        language: locale?.lang ?? 'en',
+        title: 'Documentation',
+        description: 'Recently updated documentation pages',
+        items,
+    });
+}

package/dist/rss-utils.d.ts

@@ -0,0 +1,27 @@
+import type { RssLocale } from '@hagicode/hagilight-core/rss';
+export interface RssContentOptions {
+    /** Include non-blog documentation pages. Defaults to `true`. */
+    includeDocs?: boolean;
+    /** Include pages under `blog/`. Defaults to `true`. */
+    includeBlog?: boolean;
+}
+export type ResolvedRssContentOptions = Required<RssContentOptions>;
+/** The subset of a Starlight docs collection entry used to build feeds. */
+export interface RssDocsEntry {
+    id: string;
+    data: {
+        title: string;
+        description?: string | undefined;
+        draft?: boolean | undefined;
+        rss?: unknown;
+        lastUpdated?: unknown;
+    };
+}
+export interface SelectRssEntriesOptions {
+    filename: string | undefined;
+    locales: readonly RssLocale[];
+    options: ResolvedRssContentOptions;
+}
+export declare function resolveRssOptions(options?: RssContentOptions): ResolvedRssContentOptions;
+export declare function isBlogEntry(id: string): boolean;
+export declare function selectRssEntries<Entry extends RssDocsEntry>(entries: readonly Entry[], { filename, locales, options }: SelectRssEntriesOptions): Entry[];

package/dist/rss-utils.js

@@ -0,0 +1,65 @@
+export function resolveRssOptions(options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError('Hagilight rss options must be an object.');
+    }
+    for (const key of ['includeDocs', 'includeBlog']) {
+        if (options[key] !== undefined && typeof options[key] !== 'boolean') {
+            throw new TypeError(`Hagilight rss ${key} option must be a boolean.`);
+        }
+    }
+    return {
+        includeDocs: options.includeDocs ?? true,
+        includeBlog: options.includeBlog ?? true,
+    };
+}
+function getLocaleForEntry(id, locales) {
+    const localized = locales
+        .filter(({ route }) => route !== 'root')
+        .sort((a, b) => b.route.length - a.route.length)
+        .find(({ route }) => id === route || id.startsWith(`${route}/`));
+    if (localized)
+        return { locale: localized, relativeId: id.slice(localized.route.length).replace(/^\/+/, '') };
+    const root = locales.find(({ route }) => route === 'root');
+    if (root)
+        return { locale: root, relativeId: id };
+    return undefined;
+}
+export function isBlogEntry(id) {
+    const segments = id.split('/').filter(Boolean);
+    if (segments.at(-1) === 'index')
+        segments.pop();
+    return segments[0] === 'blog' && segments.length > 1;
+}
+function timestamp(value) {
+    return value instanceof Date ? value.getTime() : undefined;
+}
+export function selectRssEntries(entries, { filename, locales, options }) {
+    const locale = locales.find((item) => item.filename === filename);
+    if (!locale) {
+        if (filename === 'en')
+            return [];
+        throw new Error(`Hagilight RSS has no configured locale for "${filename}".`);
+    }
+    return entries
+        .filter(({ id, data }) => {
+        if (data.rss !== undefined && typeof data.rss !== 'boolean') {
+            throw new TypeError(`Hagilight RSS frontmatter field "rss" for "${id}" must be a boolean.`);
+        }
+        if (data.draft || data.rss === false)
+            return false;
+        const entryLocale = getLocaleForEntry(id, locales);
+        if (!entryLocale || entryLocale.locale.filename !== filename)
+            return false;
+        const isBlog = isBlogEntry(entryLocale.relativeId);
+        return isBlog ? options.includeBlog : options.includeDocs;
+    })
+        .sort((a, b) => {
+        const aDate = timestamp(a.data.lastUpdated);
+        const bDate = timestamp(b.data.lastUpdated);
+        if (aDate === undefined || Number.isNaN(aDate))
+            return bDate === undefined || Number.isNaN(bDate) ? 0 : 1;
+        if (bDate === undefined || Number.isNaN(bDate))
+            return -1;
+        return bDate - aDate;
+    });
+}

package/dist/schema.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'astro/zod';
+/** Per-page AI disclosure flags that override the plugin `aiDisclosures` defaults. */
+export declare const aiDisclosureSchema: z.ZodObject<{
+    isAITranslation: z.ZodOptional<z.ZodBoolean>;
+    isAIAuthor: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Per-page switch for the end-of-article HagiCode introduction. */
+export declare const articlePromotionSchema: z.ZodObject<{
+    hagicodePromotion: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Per-page switch that excludes a page from generated RSS feeds when `false`. */
+export declare const rssSchema: z.ZodObject<{
+    rss: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Every frontmatter field read by the Hagilight Starlight plugin, including the
+ * shared `seo` object. Pass it to Starlight as `docsSchema({ extend: hagilightSchema })`.
+ */
+export declare const hagilightSchema: z.ZodObject<{
+    seo: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+        author: z.ZodOptional<z.ZodString>;
+        publishedDate: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    }, z.core.$strip>>;
+    rss: z.ZodOptional<z.ZodBoolean>;
+    hagicodePromotion: z.ZodOptional<z.ZodBoolean>;
+    isAITranslation: z.ZodOptional<z.ZodBoolean>;
+    isAIAuthor: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type HagilightFrontmatter = z.infer<typeof hagilightSchema>;

package/dist/schema.js

@@ -0,0 +1,25 @@
+import { z } from 'astro/zod';
+import { seoSchema } from '@hagicode/hagilight-core/seo-schema';
+/** Per-page AI disclosure flags that override the plugin `aiDisclosures` defaults. */
+export const aiDisclosureSchema = z.object({
+    isAITranslation: z.boolean().optional(),
+    isAIAuthor: z.boolean().optional(),
+});
+/** Per-page switch for the end-of-article HagiCode introduction. */
+export const articlePromotionSchema = z.object({
+    hagicodePromotion: z.boolean().optional(),
+});
+/** Per-page switch that excludes a page from generated RSS feeds when `false`. */
+export const rssSchema = z.object({
+    rss: z.boolean().optional(),
+});
+/**
+ * Every frontmatter field read by the Hagilight Starlight plugin, including the
+ * shared `seo` object. Pass it to Starlight as `docsSchema({ extend: hagilightSchema })`.
+ */
+export const hagilightSchema = z.object({
+    ...aiDisclosureSchema.shape,
+    ...articlePromotionSchema.shape,
+    ...rssSchema.shape,
+    ...seoSchema.shape,
+});

package/dist/seo-utils.d.ts

@@ -0,0 +1,74 @@
+import { type HeadEntry, type StructuredData } from '@hagicode/hagilight-core/seo';
+import type { TrailingSlash } from './not-found.js';
+export interface SeoLocale {
+    route: string;
+    lang: string;
+}
+export interface SeoPage {
+    route: string;
+    slug: string;
+}
+export interface SeoDocsEntry {
+    id: string;
+    body?: string | undefined;
+    data: {
+        title: string;
+        description?: string | undefined;
+        draft?: boolean | undefined;
+        author?: string | undefined;
+        publishedDate?: Date | string | number | undefined;
+        lastUpdated?: Date | string | number | undefined | unknown;
+        [key: string]: unknown;
+    };
+}
+export interface PublishedDocsLookup<Entry extends SeoDocsEntry = SeoDocsEntry> {
+    get(route: string, slug: string): Entry | undefined;
+    has(route: string, slug: string): boolean;
+}
+export type BuildFormat = 'directory' | 'file' | 'preserve';
+export interface SeoOrganization {
+    name: string;
+    url: string;
+    logo?: string;
+}
+export type SeoLocalesInput = Readonly<Record<string, string | {
+    lang?: string | undefined;
+} | undefined>>;
+export declare function resolveSeoLocales(locales: SeoLocalesInput | undefined): SeoLocale[];
+export declare function resolveSeoPage(entryId: string | undefined, locales: readonly SeoLocale[]): SeoPage;
+export declare function createPublishedDocsLookup<Entry extends SeoDocsEntry>(entries: readonly Entry[], locales: readonly SeoLocale[]): PublishedDocsLookup<Entry>;
+export interface FilterAlternatesOptions {
+    entryId: string;
+    locales: readonly SeoLocale[];
+    lookup: PublishedDocsLookup<SeoDocsEntry>;
+    basePath?: string;
+    explicitHead?: readonly (readonly HeadEntry[] | undefined)[];
+}
+export declare function filterPublishedLocaleAlternates<Entry extends HeadEntry>(head: readonly Entry[], { entryId, locales, lookup, basePath, explicitHead, }: FilterAlternatesOptions): Entry[];
+export interface DocsPageUrlOptions {
+    site: string | URL;
+    basePath?: string;
+    format?: BuildFormat;
+    trailingSlash?: TrailingSlash;
+}
+export declare function buildDocsPageUrl(route: string, slug: string, { site, basePath, format, trailingSlash, }: DocsPageUrlOptions): string;
+export interface BuildStructuredDataOptions {
+    entry: SeoDocsEntry | undefined;
+    entryId: string;
+    canonicalUrl: string | undefined;
+    site: string | URL;
+    siteTitle?: string | undefined;
+    pageSeo?: {
+        description?: string | undefined;
+        author?: string | undefined;
+        publishedDate?: Date | string | number | undefined;
+    };
+    organization?: SeoOrganization | undefined;
+    locales: readonly SeoLocale[];
+    defaultLocale?: string;
+    lookup: PublishedDocsLookup<SeoDocsEntry>;
+    basePath?: string;
+    format?: BuildFormat;
+    trailingSlash?: TrailingSlash;
+}
+export declare function buildStructuredData({ entry, entryId, canonicalUrl, site, siteTitle, pageSeo, organization, locales, defaultLocale, lookup, basePath, format, trailingSlash, }: BuildStructuredDataOptions): StructuredData[];