@jaamd/astro 0.0.0-stage → 1.0.0

package/src/components/MarkdownContent.astro

@@ -0,0 +1,21 @@
+---
+import type { HTMLTag } from 'astro/types'
+import '../../dist/default.css'
+import '../../dist/styles.css'
+
+/**
+ * Kept deliberately non-generic: Astro's parser reads `<Tag extends HTMLTag>` as
+ * an HTML tag. The real generic type lives in MarkdownContent.astro.d.ts.
+ */
+type Props = {
+    as?: HTMLTag
+    class?: string
+}
+
+const { as: Tag = 'div', class: extraClass, ...attrs } = Astro.props
+const className = extraClass ? `jaamd-content ${extraClass}` : 'jaamd-content'
+---
+
+<Tag class={className} {...attrs}>
+    <slot />
+</Tag>

package/src/components/MarkdownContent.astro.d.ts

@@ -0,0 +1,12 @@
+import type { HTMLTag, Polymorphic } from 'astro/types'
+
+export type Props<Tag extends HTMLTag = 'div'> = Polymorphic<{
+    as: Tag
+    /** Appended to the always-present `jaamd-content` class, which the JS
+     *  enhancements select on. */
+    class?: string
+}>
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+declare const MarkdownContent: <Tag extends HTMLTag = 'div'>(_props: Props<Tag>) => any
+export default MarkdownContent

package/src/frontmatter.ts

@@ -0,0 +1,27 @@
+import type { z as Zod } from 'astro/zod'
+
+/**
+ * Frontmatter fields shared by JAAMD sites, to spread into a collection schema:
+ * `z.object({ ...frontmatterFields(z), order: z.number().optional() })`.
+ */
+export function frontmatterFields(z: typeof Zod) {
+    return {
+        title: z.string().optional(),
+        description: z.string().optional(),
+        /** Left out of production builds. */
+        draft: z.boolean().default(false),
+        /** Metadata and search weight; never rendered. */
+        keywords: z.array(z.string()).default([]),
+        author: z.string().optional(),
+        /** Public path or URL; false drops the site's. */
+        ogImage: z
+            .union([
+                z.string().refine((v) => v.startsWith('/') || /^https?:\/\//.test(v), {
+                    message: 'ogImage must be a public url, such as "/og/page.png"',
+                }),
+                z.literal(false),
+            ])
+            .optional(),
+        lastUpdated: z.coerce.date().optional(),
+    }
+}

package/src/integration.ts

@@ -0,0 +1,96 @@
+import type { AstroIntegration } from 'astro'
+import { fileURLToPath } from 'node:url'
+import { DEFAULT_SELECTOR } from '@jaamd/core/client'
+import { registerPlugins, type PluginOptions } from './processors.ts'
+import { withTheme, type ShikiTheme } from './shiki.ts'
+
+export interface JaamdOptions extends PluginOptions {
+    /**
+     * Elements the client script enhances. `<MarkdownContent>` renders
+     * `.jaamd-content`; a wrapper of your own needs its selector here.
+     * @default ".jaamd-content"
+     */
+    selector?: string
+
+    /**
+     * Shiki theme. `{ light, dark }` switches on a `.dark` class on `<html>`.
+     * Unset, `markdown.shikiConfig` is left as configured; "github-light"
+     * replaces only Astro's own default.
+     * @default "github-light"
+     */
+    theme?: ShikiTheme
+
+    /**
+     * Injects the default `--jaamd-*` values on every page. `<MarkdownContent>`
+     * imports them anyway.
+     * @default true
+     */
+    defaultVariables?: boolean
+}
+
+/** Absolute path of a stylesheet of this package, as a quoted specifier: injected
+ *  scripts resolve from the project, where `@jaamd/astro` may be unreachable. */
+const own = (relative: string) => JSON.stringify(fileURLToPath(new URL(relative, import.meta.url)))
+
+const STYLES = {
+    variables: own('../dist/default.css'),
+    shikiDual: own('../dist/shiki-dual.css'),
+    markdown: own('../dist/styles.css'),
+}
+
+const CLIENT = own('./client.ts')
+
+/** Registers JAAMD's plugins on Astro's markdown processor and injects its styles and client script. */
+export default function jaamd(options: JaamdOptions = {}): AstroIntegration {
+    const { selector = DEFAULT_SELECTOR, theme, defaultVariables = true, features, labels } = options
+    const client = JSON.stringify({ features, labels })
+
+    return {
+        name: '@jaamd/astro',
+        hooks: {
+            'astro:config:setup': ({ config, updateConfig, injectScript, logger }) => {
+                const { shikiConfig, dual } = withTheme(config.markdown.shikiConfig, theme)
+                const { processor } = config.markdown
+                const registration = registerPlugins(processor, { features, labels })
+
+                if (!registration) {
+                    logger.warn(
+                        `markdown processor "${processor.name}" is neither Sätteri nor unified: JAAMD's plugins were not added. Pass them to your processor yourself.`,
+                    )
+                } else if (registration.total > 0) {
+                    logger.info(
+                        `markdown processor: ${processor.name}, registered ${registration.added}/${registration.total} plugin(s)`,
+                    )
+                }
+
+                updateConfig({
+                    // Ships TypeScript and an Astro component, compiled by Vite.
+                    vite: { ssr: { noExternal: ['@jaamd/astro'] } },
+                    markdown: { shikiConfig },
+                })
+
+                // "page-ssr": the stylesheets render as <link> tags in every page's <head>.
+                injectScript(
+                    'page-ssr',
+                    [
+                        ...(defaultVariables ? [`import ${STYLES.variables};`] : []),
+                        ...(dual ? [`import ${STYLES.shikiDual};`] : []),
+                        `import ${STYLES.markdown};`,
+                    ].join('\n'),
+                )
+
+                // Again on every View Transitions navigation, releasing the previous run.
+                injectScript(
+                    'page',
+                    [
+                        `import { enhance } from ${CLIENT};`,
+                        `let dispose;`,
+                        `const run = () => { dispose?.(); dispose = enhance(${JSON.stringify(selector)}, ${client}); };`,
+                        `run();`,
+                        `document.addEventListener("astro:page-load", run);`,
+                    ].join('\n'),
+                )
+            },
+        },
+    }
+}

package/src/processors.ts

@@ -0,0 +1,135 @@
+import type { Features, Labels } from '@jaamd/core/client'
+import type { HeadingText } from '@jaamd/core/satteri'
+import type { AstroConfig, RehypePlugins, RemarkPlugins } from 'astro'
+import { satteriPlugins as coreSatteriPlugins } from '@jaamd/core/satteri'
+import { rehypeHeadingLinks, unifiedPlugins as coreUnifiedPlugins } from '@jaamd/core/unified'
+import { satteriCollectHastText, satteriHeadingIdsPlugin } from './astro-satteri.ts'
+
+export interface PluginOptions {
+    /** Features to turn off. All on by default. */
+    features?: Features
+    /** Text JAAMD writes into the page. English by default. */
+    labels?: Partial<Labels>
+}
+
+/** Astro's heading id plugin for unified, as a module URL: `@astrojs/markdown-remark`,
+ *  an optional peer, imports it only when unified runs. */
+const REHYPE_HEADING_IDS = new URL('./rehype-heading-ids.js', import.meta.url).href
+
+/** The heading text Astro records, frontmatter expressions resolved. */
+const headingText: HeadingText = (node, ctx) => {
+    const raw = ctx.textContent(node)
+    return raw.includes('frontmatter') ? satteriCollectHastText(node, ctx.data.astro?.frontmatter ?? {}) : raw
+}
+
+const isHeadingLinks = (plugin: unknown) => (Array.isArray(plugin) ? plugin[0] : plugin) === rehypeHeadingLinks
+
+/** JAAMD's plugins for Astro's `unified()`, Astro's heading ids included. */
+export function unifiedPlugins(options: PluginOptions = {}): {
+    remarkPlugins: RemarkPlugins
+    rehypePlugins: RehypePlugins
+} {
+    const preset = coreUnifiedPlugins(options)
+    return {
+        // unified's `[plugin, ...options]` is Astro's `[plugin, options]`.
+        remarkPlugins: preset.remarkPlugins as RemarkPlugins,
+        rehypePlugins: preset.rehypePlugins.flatMap((plugin) =>
+            isHeadingLinks(plugin) ? [REHYPE_HEADING_IDS, plugin] : [plugin],
+        ) as RehypePlugins,
+    }
+}
+
+/** JAAMD's plugins for Astro's `satteri()`, Astro's heading ids included. */
+export function satteriPlugins(options: PluginOptions = {}): ReturnType<typeof coreSatteriPlugins> {
+    return coreSatteriPlugins({ ...options, headingIds: satteriHeadingIdsPlugin(), headingText })
+}
+
+type Processor = AstroConfig['markdown']['processor']
+
+interface SatteriProcessorOptions {
+    features?: Record<string, unknown>
+    mdastPlugins: unknown[]
+    hastPlugins: unknown[]
+}
+
+interface UnifiedProcessorOptions {
+    remarkPlugins: unknown[]
+    rehypePlugins: unknown[]
+}
+
+export interface Registration {
+    /** Plugins added. */
+    added: number
+    /** Plugins JAAMD would add to an empty processor. */
+    total: number
+}
+
+/** Names of a Sätteri entry: definitions carry `name`, groups nest, factories have none. */
+const satteriNames = (entry: unknown): string[] =>
+    Array.isArray(entry)
+        ? entry.flatMap(satteriNames)
+        : entry && typeof entry === 'object' && 'name' in entry
+          ? [String(entry.name)]
+          : []
+
+/** Name of a unified entry: the plugin function or module, alone or as `[plugin, options]`. */
+const unifiedNames = (entry: unknown): string[] => {
+    const plugin = Array.isArray(entry) ? entry[0] : entry
+    if (typeof plugin === 'string') return [plugin]
+    return typeof plugin === 'function' && plugin.name ? [plugin.name] : []
+}
+
+/** Plugins whose names are not registered yet. Registering one twice would run it twice. */
+function missing<T>(existing: readonly unknown[], plugins: readonly T[], names: (entry: unknown) => string[]): T[] {
+    const taken = new Set(existing.flatMap(names))
+    return plugins.filter((plugin) => !names(plugin).some((name) => taken.has(name)))
+}
+
+const isFallback = (plugin: { name: string }) => plugin.name === 'jaamd-directive-fallback'
+
+/** Ahead of the user's mdast plugins, the directive fallback after them; hast plugins after the user's. */
+function registerSatteri(processor: SatteriProcessorOptions, options: PluginOptions): Registration {
+    const preset = satteriPlugins(options)
+    const mdast = missing(processor.mdastPlugins, preset.mdastPlugins, satteriNames)
+    const hast = missing(processor.hastPlugins, preset.hastPlugins, satteriNames)
+
+    processor.mdastPlugins = [
+        ...mdast.filter((plugin) => !isFallback(plugin)),
+        ...processor.mdastPlugins,
+        ...mdast.filter(isFallback),
+    ]
+    processor.hastPlugins = [...processor.hastPlugins, ...hast]
+    if (preset.features.directive) processor.features = { ...processor.features, directive: true }
+
+    return { added: mdast.length + hast.length, total: preset.mdastPlugins.length + preset.hastPlugins.length }
+}
+
+/** remark plugins ahead of the user's, rehype plugins after them. */
+function registerUnified(processor: UnifiedProcessorOptions, options: PluginOptions): Registration {
+    const preset = unifiedPlugins(options)
+    const remark = missing(processor.remarkPlugins, preset.remarkPlugins, unifiedNames)
+    const missingRehype = missing(processor.rehypePlugins, preset.rehypePlugins, unifiedNames)
+    // Astro's ids come along only with the links that read them.
+    const links = missingRehype.some(isHeadingLinks)
+    const rehype = missingRehype.filter((plugin) => links || plugin !== REHYPE_HEADING_IDS)
+
+    processor.remarkPlugins = [...remark, ...processor.remarkPlugins]
+    processor.rehypePlugins = [...processor.rehypePlugins, ...rehype]
+
+    return { added: remark.length + rehype.length, total: preset.remarkPlugins.length + preset.rehypePlugins.length }
+}
+
+/**
+ * Adds JAAMD's plugins to Astro's processor, in place, skipping those already
+ * there. New arrays each time: a processor shared across setup runs keeps no
+ * duplicates. `null` for a processor other than Sätteri and unified.
+ */
+export function registerPlugins(processor: Processor, options: PluginOptions = {}): Registration | null {
+    if (processor.name === 'satteri') {
+        return registerSatteri(processor.options as SatteriProcessorOptions, options)
+    }
+    if (processor.name === 'unified') {
+        return registerUnified(processor.options as UnifiedProcessorOptions, options)
+    }
+    return null
+}

package/src/rehype-heading-ids.js

@@ -0,0 +1,5 @@
+/**
+ * Astro's heading id plugin as a default export. Registered as a string in
+ * `rehypePlugins`, so `@astrojs/markdown-remark` imports it itself.
+ */
+export { rehypeHeadingIds as default } from '@astrojs/markdown-remark'

package/src/shiki.ts

@@ -0,0 +1,29 @@
+import type { ShikiConfig } from 'astro'
+
+/** A Shiki theme name, or one for each colour scheme. */
+export type ShikiTheme = string | { light: string; dark: string }
+
+/** Astro's default `shikiConfig.theme`, filled in before integrations run. */
+const ASTRO_DEFAULT_THEME = 'github-dark'
+
+/**
+ * `markdown.shikiConfig` with `theme` applied. Without one, the config stays
+ * as it is, except Astro's own default, which becomes "github-light".
+ * `{ light, dark }` sets Shiki's `themes` with no default colour: `dual`.
+ */
+export function withTheme(current: ShikiConfig, theme?: ShikiTheme): { shikiConfig: ShikiConfig; dual: boolean } {
+    const shikiConfig: ShikiConfig = { ...current }
+    const configured = Object.keys(shikiConfig.themes ?? {}).length > 0 || shikiConfig.theme !== ASTRO_DEFAULT_THEME
+    const resolved = theme ?? (configured ? undefined : 'github-light')
+
+    if (typeof resolved === 'object') {
+        if (!resolved.light || !resolved.dark) return { shikiConfig, dual: false }
+        delete shikiConfig.theme
+        shikiConfig.themes = { light: resolved.light, dark: resolved.dark } as ShikiConfig['themes']
+        shikiConfig.defaultColor = false
+        return { shikiConfig, dual: true }
+    }
+
+    if (resolved) shikiConfig.theme = resolved as ShikiConfig['theme']
+    return { shikiConfig, dual: false }
+}

package/src/themes.ts

@@ -0,0 +1 @@
+export * from '@jaamd/core/themes'