@jaamd/jaad 0.11.0 → 1.0.0

package/src/integration.ts

@@ -1,235 +1,24 @@
-import type { JaadResolvedConfig, resolveStylesheets } from './config.ts'
-import type { AstroIntegration, AstroUserConfig } from 'astro'
-import { existsSync, readFileSync, readdirSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { join, relative, resolve } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import { fonts } from './fonts.ts'
-import { prefixedLocales } from './locales.ts'
-import { docsPageHref, normaliseBasePath, type DocsUrlOptions } from './urls.ts'
-import { getCleanSlug, getDocCollectionId, sortDocPages, splitDocLocale } from './utils/docs.ts'
-import { jaadVirtualPlugin } from './virtual.ts'
-
-type Stylesheets = ReturnType<typeof resolveStylesheets>
-type VitePlugins = NonNullable<NonNullable<AstroUserConfig['vite']>['plugins']>
-
-const NOT_INSTALLED = new Set(['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'])
-
-/** The site's own `@tailwindcss/vite`, unless it already registered one. */
-export function loadTailwindPlugin(root: string, registered: VitePlugins | undefined): VitePlugins {
-    const plugins = ([registered] as unknown[]).flat(Infinity) as ({
-        name?: string
-    } | null)[]
-    if (plugins.some((p) => p?.name?.startsWith('@tailwindcss/vite'))) return []
-
-    const load = createRequire(join(root, 'package.json'))
-    let tailwindcss: () => VitePlugins
-    try {
-        load.resolve('tailwindcss/package.json')
-        ;({ default: tailwindcss } = load('@tailwindcss/vite') as {
-            default: () => VitePlugins
-        })
-    } catch (error) {
-        if (!NOT_INSTALLED.has((error as { code?: string }).code ?? '')) throw error
-        throw new Error(
-            'jaad: `tailwind: true` needs Tailwind in your project:\n  npm i -D tailwindcss @tailwindcss/vite',
-            { cause: error },
-        )
-    }
-    return tailwindcss()
-}
-
-/** One per locale: each has its own first page, and its own redirect. */
-export interface OpeningPage {
-    locale?: string
-    slug: string
-}
-
-export interface IntegrationState {
-    deploymentBase: string
-    openingPages: OpeningPage[]
-    docsFrame: string
-}
-
-const INDEX_PAGE_NAMES = ['index.astro', 'index.md', 'index.mdx', 'index.html', 'index.js', 'index.ts']
-
-const NOT_FOUND_PAGE_NAMES = ['404.astro', '404.md', '404.mdx', '404.html', '404.js', '404.ts']
-
-const routeEntrypoint = (file: string) => fileURLToPath(new URL(`./routes/${file}`, import.meta.url))
-
-export function shouldInjectNotFound(docsBase: string, srcDir: URL): boolean {
-    return docsBase === '' && !NOT_FOUND_PAGE_NAMES.some((name) => existsSync(new URL(`pages/${name}`, srcDir)))
-}
-
-/** The two fields that move the opening page. The content collection is not
- *  available this early, so `order` and `draft` are read from the file. */
-function readFrontmatter(source: string): { order?: number; draft?: boolean } {
-    const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source)
-    if (!block) return {}
-
-    const order = /^order:\s*(-?\d+)\s*$/m.exec(block[1])
-    const draft = /^draft:\s*(true|false)\s*$/m.exec(block[1])
-    return {
-        order: order ? Number(order[1]) : undefined,
-        draft: draft ? draft[1] === 'true' : undefined,
-    }
-}
-
-export function findOpeningPages(dir: string, locales: string[] = []): OpeningPage[] {
-    if (!existsSync(dir)) return []
-
-    const pages: {
-        id: string
-        localeId: string
-        locale: string | null
-        data: { order?: number }
-    }[] = []
-
-    const visit = (current: string) => {
-        for (const entry of readdirSync(current, { withFileTypes: true }).toSorted((a, b) =>
-            a.name.localeCompare(b.name),
-        )) {
-            const file = join(current, entry.name)
-            if (entry.isDirectory()) visit(file)
-            else if (entry.isFile() && entry.name.endsWith('.md')) {
-                const front = readFrontmatter(readFileSync(file, 'utf8'))
-                if (front.draft) continue
-
-                const id = getDocCollectionId(relative(dir, file))
-                const split = splitDocLocale(id, locales)
-                pages.push({
-                    id,
-                    localeId: split.id,
-                    locale: split.locale,
-                    data: { order: front.order },
-                })
-            }
-        }
-    }
-
-    visit(dir)
-
-    const groups = locales.length > 0 ? locales : [null]
-    return groups.flatMap((locale) => {
-        const first = sortDocPages(pages.filter((page) => page.locale === locale))[0]
-        // Indexed access is typed as always present; a locale can have no pages.
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        if (!first) return []
-        return [{ locale: locale ?? undefined, slug: getCleanSlug(first.localeId) }]
-    })
-}
-
-export function getInjectedRoutes(docsBase: string, locales: string[] = []): [string, string][] {
-    // `[...slug]` already absorbs "it/guide" and "it". Only the two fixed
-    // endpoints need a route of their own, and `[locale]` hands them the code.
-    const perLocale: [string, string][] =
-        locales.length > 0
-            ? [
-                  [`${docsBase}/[locale]/search-index.json`, 'search-index-locale.json.ts'],
-                  [`${docsBase}/[locale]/llms.txt`, 'llms-locale.txt.ts'],
-              ]
-            : []
-
-    return [
-        [docsBase, 'docs-index.astro'],
-        [`${docsBase}/search-index.json`, 'search-index.json.ts'],
-        [`${docsBase}/llms.txt`, 'llms.txt.ts'],
-        ...perLocale,
-        [`${docsBase}/[...slug]`, 'docs-slug.astro'],
-        [`${docsBase}/[...slug].md`, 'docs-slug.md.ts'],
-    ]
-}
-
-export function createIntegrationState(): IntegrationState {
-    return {
-        deploymentBase: '',
-        openingPages: [],
-        docsFrame: fileURLToPath(new URL('./layouts/DefaultDocsFrame.astro', import.meta.url)),
-    }
-}
-
-export function createCoreIntegration(
+import type { JaadResolvedConfig } from './config.ts'
+import type { IntegrationState } from './docs/integration.ts'
+import type { SiteStylesheets } from './site/virtual.ts'
+import type { AstroIntegration } from 'astro'
+import { setupDocs } from './docs/integration.ts'
+import { setupSite } from './site/integration.ts'
+import { normaliseBasePath } from './site/urls.ts'
+
+/** The site, then the docs on it. */
+export function createJaadIntegration(
     config: JaadResolvedConfig,
-    stylesheets: Stylesheets,
+    stylesheets: SiteStylesheets,
     state: IntegrationState,
-    discoverOpeningPage: boolean,
+    discoverAliases: boolean,
 ): AstroIntegration {
     return {
         name: 'jaad',
         hooks: {
-            'astro:config:setup': ({ config: astroConfig, updateConfig, injectRoute, addWatchFile, logger }) => {
-                updateConfig({
-                    vite: {
-                        plugins: [
-                            jaadVirtualPlugin(
-                                config,
-                                stylesheets.user,
-                                stylesheets.theme,
-                                stylesheets.bridge,
-                                stylesheets.tailwind,
-                                () => state.docsFrame,
-                            ),
-                            ...(config.tailwind
-                                ? [loadTailwindPlugin(fileURLToPath(astroConfig.root), astroConfig.vite.plugins)]
-                                : []),
-                        ],
-                        // Package .astro sources must reach the Astro compiler.
-                        ssr: { noExternal: ['@jaamd/jaad'] },
-                    },
-                    fonts,
-                })
-
-                for (const [pattern, entrypoint] of getInjectedRoutes(
-                    config.docsBase,
-                    prefixedLocales(config.docsLocales, config.defaultLocale),
-                )) {
-                    injectRoute({
-                        pattern,
-                        entrypoint: routeEntrypoint(entrypoint),
-                        prerender: true,
-                    })
-                }
-
-                const customDocsFrame = new URL('jaad/DocsFrame.astro', astroConfig.srcDir)
-                if (existsSync(customDocsFrame)) {
-                    state.docsFrame = fileURLToPath(customDocsFrame)
-                    addWatchFile(customDocsFrame)
-                }
-
-                if (shouldInjectNotFound(config.docsBase, astroConfig.srcDir)) {
-                    injectRoute({
-                        pattern: '/404',
-                        entrypoint: routeEntrypoint('404.astro'),
-                        prerender: true,
-                    })
-                }
-
-                const docsDirPath = resolve(fileURLToPath(astroConfig.root), config.docsDir)
-                const docsDir = pathToFileURL(docsDirPath)
-                if (!existsSync(docsDir)) {
-                    logger.warn(
-                        `${config.docsDir} does not exist, so the site has no pages. ` +
-                            'Create it, or point docsDir at your markdown.',
-                    )
-                } else if (discoverOpeningPage) {
-                    state.openingPages = findOpeningPages(
-                        docsDirPath,
-                        config.docsLocales.map((locale) => locale.code),
-                    )
-                }
-                addWatchFile(docsDir)
-
-                if (config.docsBase === '') {
-                    const ownIndex = INDEX_PAGE_NAMES.find((name) =>
-                        existsSync(new URL(`pages/${name}`, astroConfig.srcDir)),
-                    )
-                    if (ownIndex) {
-                        logger.warn(
-                            `${ownIndex} owns the site root while JAAD docs are mounted there. ` +
-                                'Set routeBase: "/docs" to keep a landing page and mount the docs below it.',
-                        )
-                    }
-                }
+            'astro:config:setup': (params) => {
+                setupSite(params, config, stylesheets)
+                setupDocs(params, config, state, discoverAliases)
             },
 
             'astro:config:done': ({ config: astroConfig, injectTypes }) => {
@@ -245,26 +34,3 @@ export function createCoreIntegration(
         },
     }
 }
-
-const withoutTrailingSlash = (value: string) => (value.length > 1 ? value.replace(/\/$/, '') : value)
-
-export function createSitemapFilter(
-    docsBase: string,
-    state: Pick<IntegrationState, 'deploymentBase' | 'openingPages'>,
-    defaultLocale?: string,
-): (page: string) => boolean {
-    return (page) => {
-        if (state.openingPages.length === 0) return true
-
-        const pathname = withoutTrailingSlash(new URL(page).pathname)
-        return !state.openingPages.some((opening) => {
-            const urls: DocsUrlOptions = {
-                docsBase,
-                deploymentBase: state.deploymentBase,
-                locale: opening.locale,
-                defaultLocale,
-            }
-            return pathname === withoutTrailingSlash(docsPageHref(opening.slug, urls))
-        })
-    }
-}

package/src/{components → site/components}/Footer.astro

@@ -1,7 +1,7 @@
 ---
 import config from 'virtual:jaad/config'
 
-const CREDIT = 'Built with <a href="https://jaamd.org/docs/jaad" rel="noopener">JAAD</a>.'
+const CREDIT = 'Built with <a href="https://docs.jaamd.org/jaad" rel="noopener">JAAD</a>.'
 
 // Unset is the credit alone; `footer: false` removes it.
 const line = config.footer === undefined ? ':credit' : config.footer

package/src/{components → site/components}/Header.astro

@@ -1,7 +1,7 @@
 ---
+import type { LocaleAlternate } from '../locales.ts'
 import config from 'virtual:jaad/config'
-import { getLocaleAlternates, type LocaleAlternate } from '../collection.ts'
-import { DEFAULT_LOCALE, ui } from '../docs-config.ts'
+import { DEFAULT_LOCALE, ui } from '../runtime.ts'
 import { withDeploymentBase } from '../urls.ts'
 import LocaleSwitcher from './LocaleSwitcher.astro'
 import Nav from './Nav.astro'
@@ -11,21 +11,24 @@ import SocialLinks from './SocialLinks.astro'
 import ThemeSwitcher from './ThemeSwitcher.astro'
 
 interface Props {
-    /** Whether this page is part of the docs. */
-    inDocs?: boolean
     locale?: string
-    alternates?: LocaleAlternate[]
+    /** The page in every locale, for the switcher. */
+    alternates: LocaleAlternate[]
+    search: {
+        /** `search-index.json` of the reader's locale. */
+        indexUrl: string
+        /** The full search field on wide screens, not just its icon. */
+        prominent?: boolean
+    }
 }
 
-const { inDocs = false, locale = DEFAULT_LOCALE } = Astro.props
-// A page of the reader's own has no translations: offer each locale's opener.
-const alternates = Astro.props.alternates ?? (await getLocaleAlternates(''))
+const { locale = DEFAULT_LOCALE, alternates, search } = Astro.props
 const t = ui(locale)
-const homeHref = withDeploymentBase('/', import.meta.env.BASE_URL)
+const homeHref = withDeploymentBase(config.homeLink, import.meta.env.BASE_URL)
 const logoSrc = config.logo ? withDeploymentBase(config.logo, import.meta.env.BASE_URL) : null
 ---
 
-<header class="jaad-chrome" transition:persist>
+<header class="jaad-header" transition:persist>
     <div class="jaad-header-inner">
         <div class="jaad-header-row">
             <span class="jaad-brand font-brand">
@@ -35,7 +38,7 @@ const logoSrc = config.logo ? withDeploymentBase(config.logo, import.meta.env.BA
             </span>
 
             <div class="jaad-header-actions">
-                <SearchPalette inDocs={inDocs} locale={locale} />
+                <SearchPalette indexUrl={search.indexUrl} prominent={search.prominent} {locale} />
                 <Nav />
                 <SocialLinks />
                 {config.appearance === 'auto' && <ThemeSwitcher {locale} />}

package/src/{components → site/components}/LocaleSwitcher.astro

@@ -1,6 +1,6 @@
 ---
-import type { LocaleAlternate } from '../collection.ts'
-import { ui } from '../docs-config.ts'
+import type { LocaleAlternate } from '../locales.ts'
+import { ui } from '../runtime.ts'
 
 interface Props {
     alternates: LocaleAlternate[]

package/src/{components → site/components}/NavMobile.astro

@@ -1,6 +1,6 @@
 ---
 import config from 'virtual:jaad/config'
-import { ui } from '../docs-config.ts'
+import { ui } from '../runtime.ts'
 import { withDeploymentBase } from '../urls.ts'
 
 const links = config.nav