@jaamd/jaad 0.11.0 → 1.0.0-rc.1

package/src/styles/components/scroll-to-top.css

@@ -1,11 +0,0 @@
-@layer components {
-    .jaad-scroll-top-button {
-        @apply bg-background text-foreground hover:bg-background/80 border-foreground/20 pointer-events-none fixed right-6 bottom-6 z-50 flex h-12 w-12 items-center justify-center rounded-full border opacity-0 shadow-lg transition-opacity duration-300 lg:hidden;
-    }
-    .jaad-scroll-top-button[data-visible] {
-        @apply pointer-events-auto opacity-100;
-    }
-    .jaad-scroll-top-icon {
-        @apply h-6 w-6;
-    }
-}

package/src/styles/components/toc.css

@@ -1,21 +0,0 @@
-@layer components {
-    .docs-toc-title {
-        @apply text-primary/60 mb-4 text-xs font-semibold tracking-wider uppercase;
-    }
-
-    .docs-toc-list {
-        @apply space-y-2;
-    }
-
-    .docs-toc-link {
-        @apply text-foreground/60 hover:text-primary block border-l-2 border-transparent py-1 pl-3 text-xs no-underline transition-colors;
-    }
-
-    .docs-toc-link-nested {
-        @apply pl-6;
-    }
-
-    .docs-toc-link[aria-current='location'] {
-        @apply border-primary;
-    }
-}

package/src/styles/docs.css

@@ -1,112 +0,0 @@
-/* Layered, so a page's own utilities still win. */
-@layer components {
-    .docs-frame {
-        display: contents;
-    }
-
-    .docs-container {
-        position: relative;
-        width: 100%;
-        min-height: calc(100vh - 6.5rem);
-        display: flex;
-        justify-content: center;
-    }
-
-    /* The inline margin is deliberate and survives every breakpoint: it sits
-     outside the page padding, which only starts at 48rem. */
-    .docs-page-main {
-        flex: 1;
-        margin-block: 2rem;
-        margin-inline: 1rem;
-    }
-
-    @media (min-width: 48rem) {
-        .docs-page-main {
-            margin-block: 4rem;
-            padding-inline: var(--jaad-page-padding);
-        }
-    }
-
-    @media (min-width: 64rem) {
-        .docs-page-main {
-            margin-bottom: 8rem;
-            padding-inline: calc(var(--jaad-page-padding) * 2);
-        }
-    }
-
-    .docs-main {
-        width: 100%;
-        max-width: var(--jaad-content-width);
-        position: relative;
-    }
-
-    /* The room the sidebars need, so widening them widens the gutters too. */
-    @media (min-width: 64rem) {
-        .docs-main-gutters {
-            margin-inline: var(--jaad-sidebar-width);
-        }
-    }
-
-    @media (min-width: 64rem) {
-        [data-jaad-default-frame] .docs-sidebar-left,
-        [data-jaad-default-frame] .docs-sidebar-right {
-            position: fixed;
-            top: 0;
-            height: 100vh;
-            padding: 6rem 1.5rem 2rem;
-        }
-
-        /* max() keeps the sidebar on screen when the centred offset would be
-       negative, whatever the content and sidebar tokens are set to. */
-        [data-jaad-default-frame] .docs-sidebar-left {
-            left: max(1rem, var(--jaad-sidebar-offset));
-        }
-
-        [data-jaad-default-frame] .docs-sidebar-right {
-            right: max(1rem, var(--jaad-sidebar-offset));
-        }
-    }
-
-    @media (width < 64rem) {
-        [data-jaad-default-frame] .docs-sidebar-left,
-        [data-jaad-default-frame] .docs-sidebar-right {
-            display: none;
-        }
-    }
-
-    /* A mask, so the colour comes from the token and follows the theme.
-     Override --jaad-select-arrow for a different shape. */
-    .docs-select {
-        position: relative;
-    }
-
-    .docs-select::after {
-        content: '';
-        position: absolute;
-        top: 50%;
-        right: 0.75rem;
-        width: 1.25rem;
-        height: 1.25rem;
-        transform: translateY(-50%);
-        pointer-events: none;
-        background-color: var(--color-foreground);
-        mask: var(
-                --jaad-select-arrow,
-                url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='%23000' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.5' viewBox='0 0 20 20'%3E%3Cpath d='M6 8l4 4 4-4'/%3E%3C/svg%3E")
-            )
-            center / contain no-repeat;
-    }
-
-    .docs-mobile-nav optgroup {
-        font-weight: 600;
-        color: var(--color-primary);
-        background: var(--color-surface);
-    }
-
-    .docs-mobile-nav option {
-        font-weight: 400;
-        color: var(--color-foreground);
-        background: var(--color-surface);
-        padding: 0.5rem;
-    }
-}

package/src/utils/docs.ts

@@ -1,300 +0,0 @@
-import type { DocsHeadings, DocsPageData, ParsedDocsCollectionId } from '../@types/docs.ts'
-import GithubSlugger, { slug as githubSlug } from 'github-slugger'
-import { ucfirst } from './helpers.ts'
-
-/** The id without its locale directory: what routing and ordering read. */
-export function routedId(page: DocsPageLike): string {
-    return page.localeId ?? page.id
-}
-
-/** "it/02-guides/01-setup" becomes locale "it" and "02-guides/01-setup". */
-export function splitDocLocale(id: string, locales: string[]): { locale: string | null; id: string } {
-    const slash = id.indexOf('/')
-    if (slash === -1) return { locale: null, id }
-
-    const first = id.slice(0, slash)
-    if (!locales.includes(first)) return { locale: null, id }
-    return { locale: first, id: id.slice(slash + 1) }
-}
-
-/** Matches a numeric order prefix, e.g. "01-" or "123-" */
-const NUMBERED_PREFIX_RE = /^(\d+)-(.+)$/
-
-export function parseDocCollectionId(id: string): ParsedDocsCollectionId {
-    let order = 999
-    let orderChapter: number | undefined
-    let chapter: string | undefined
-
-    const parts = id.split('/')
-    let slug: string = parts[parts.length - 1]
-
-    if (parts.length >= 2) {
-        const chapterPart = parts[parts.length - 2]
-        const chapterMatch = NUMBERED_PREFIX_RE.exec(chapterPart)
-        if (chapterMatch) {
-            orderChapter = parseInt(chapterMatch[1], 10)
-            chapter = chapterMatch[2]
-        } else {
-            chapter = chapterPart
-        }
-    }
-
-    const match = NUMBERED_PREFIX_RE.exec(slug)
-    if (match) {
-        order = parseInt(match[1], 10)
-        slug = match[2]
-    }
-
-    return { order, orderChapter, chapter, slug, title: slugToTitle(slug) }
-}
-
-/** Chapter order first, then file order within it. Root pages interleave with
- *  chapters by their own number. */
-export function sortDocPages<T extends DocsPageLike>(pages: T[]): T[] {
-    return pages
-        .map((page) => ({ page, ...docOrder(page) }))
-        .toSorted((a, b) => a.primary - b.primary || a.secondary - b.secondary)
-        .map((entry) => entry.page)
-}
-
-/** Frontmatter `order` replaces the filename prefix number. A chapter keeps
- *  its own. */
-export function docOrder(page: DocsPageLike): {
-    primary: number
-    secondary: number
-} {
-    const parsed = parseDocCollectionId(routedId(page))
-    const order = page.data?.order ?? parsed.order
-    return { primary: parsed.orderChapter ?? order, secondary: order }
-}
-
-/** "01-chapter/02-section" → "chapter/section" */
-export function getCleanSlug(id: string): string {
-    return id
-        .split('/')
-        .map((part) => part.replace(NUMBERED_PREFIX_RE, '$2'))
-        .join('/')
-}
-
-/** Match the ids produced by Astro's glob loader, independently of the OS. */
-export function getDocCollectionId(filePath: string): string {
-    return filePath
-        .replace(/\.md$/, '')
-        .split(/[\\/]/)
-        .map((part) => githubSlug(part))
-        .join('/')
-}
-
-/** Fail before route generation when the file tree cannot produce one clear
- * navigation and URL for every page. */
-export function validateDocsStructure(pages: DocsPageLike[], locale?: string): void {
-    const idsBySlug = new Map<string, string[]>()
-    const directoriesByChapter = new Map<string, Set<string>>()
-    const issues: string[] = []
-    // Messages name the file on disk, locale directory included.
-    const named = (id: string) => (locale ? `${locale}/${id}` : id)
-
-    for (const id of pages.map(routedId).toSorted()) {
-        const parts = id.split('/')
-        if (parts.length > 2) {
-            issues.push(`${named(id)}: only one chapter directory is supported inside docs/`)
-        }
-
-        const slug = getCleanSlug(id)
-        const ids = idsBySlug.get(slug) ?? []
-        ids.push(id)
-        idsBySlug.set(slug, ids)
-
-        if (parts.length === 2) {
-            const directory = parts[0]
-            const chapter = getCleanSlug(directory)
-            const directories = directoriesByChapter.get(chapter) ?? new Set()
-            directories.add(directory)
-            directoriesByChapter.set(chapter, directories)
-        }
-    }
-
-    for (const [slug, ids] of idsBySlug) {
-        if (ids.length > 1) {
-            issues.push(`${ids.map(named).join(', ')} all resolve to /${slug}`)
-        }
-    }
-
-    const byKey = new Map<string, string[]>()
-    for (const page of pages) {
-        const key = page.data?.translationKey
-        if (!key) continue
-        const ids = byKey.get(key) ?? []
-        ids.push(routedId(page))
-        byKey.set(key, ids)
-    }
-    for (const [key, ids] of byKey) {
-        if (ids.length > 1) {
-            issues.push(`${ids.map(named).join(', ')} all claim translationKey ${key}`)
-        }
-    }
-
-    for (const [chapter, directories] of directoriesByChapter) {
-        if (directories.size > 1) {
-            issues.push(`${[...directories].map(named).join(', ')} all resolve to chapter /${chapter}`)
-        }
-    }
-
-    if (issues.length > 0) {
-        throw new Error(`jaad: invalid documentation structure\n${issues.map((issue) => `  ${issue}`).join('\n')}`)
-    }
-}
-
-/** The opening page owns routeBase; every later page keeps its named slug. */
-export function getCanonicalDocSlug(page: DocsPageLike, index: number): string {
-    return index === 0 ? '' : getCleanSlug(routedId(page))
-}
-
-/** Decodes percent-escapes, so "detail_%26_summary" → "Detail & Summary". */
-export function slugToTitle(slug: string): string {
-    return slug
-        .split(/[-_]+/)
-        .map((word) => ucfirst(decodeURIComponent(word)))
-        .join(' ')
-}
-
-export function formatChapterTitle(chapter: string | undefined): string | null {
-    if (!chapter) return null
-    return slugToTitle(chapter)
-}
-
-/** The authoritative title: Astro's glob loader strips special characters from
- *  filenames, so a slug-derived title is lossy. */
-export function extractTitleFromMarkdown(body: string): string | null {
-    for (const line of body.split('\n')) {
-        const match = line.match(/^#\s+(.+)$/)
-        if (match) return match[1].trim()
-    }
-    return null
-}
-
-/** Skips fenced blocks, so headings written as code samples stay out of the TOC. */
-/** Opening minus closing `tag` elements on one line. */
-function tagBalance(line: string, tag: string): number {
-    const count = (re: RegExp) => line.match(re)?.length ?? 0
-    return count(new RegExp(`<${tag}[\\s>]`, 'gi')) - count(new RegExp(`</${tag}>`, 'gi'))
-}
-
-export function extractHeadingsFromMarkdown(markdown: string): DocsHeadings[] {
-    const headings: DocsHeadings[] = []
-    // Per page, like the renderer: repeated headings get -1, -2 suffixes.
-    const slugger = new GithubSlugger()
-    let insideFence = false
-    // The open `data-toc-ignore` element, if any.
-    let ignored: { tag: string; depth: number } | null = null
-
-    for (const line of markdown.split('\n')) {
-        if (line.match(/^(`{3,}|~{3,})/)) {
-            insideFence = !insideFence
-            continue
-        }
-        if (insideFence) continue
-
-        if (ignored) {
-            ignored.depth += tagBalance(line, ignored.tag)
-            if (ignored.depth <= 0) ignored = null
-        } else {
-            const tag = line.match(/<([a-z][\w-]*)[^>]*\sdata-toc-ignore\b/i)?.[1]
-            const depth = tag ? tagBalance(line, tag) : 0
-            if (tag && depth > 0) ignored = { tag, depth }
-        }
-
-        const match = line.match(/^(#{2,3})\s+(.+)$/)
-        if (!match) continue
-        const depth = match[1].length as 2 | 3
-        const text = match[2].trim()
-        // Slugged even when skipped, so later duplicates keep the renderer's ids.
-        const slug = slugger.slug(text)
-        if (!ignored) headings.push({ depth, text, slug })
-    }
-
-    return headings
-}
-
-export interface DocsPageLike {
-    id: string
-    /** Set when the docs are localised; the id without its locale directory. */
-    localeId?: string
-    body?: string
-    data?: Partial<DocsPageData>
-}
-
-/** Frontmatter title, then the first H1, then the slug. */
-export function docTitle(page: DocsPageLike): string {
-    return (
-        page.data?.title ??
-        (page.body ? extractTitleFromMarkdown(page.body) : null) ??
-        parseDocCollectionId(routedId(page)).title
-    )
-}
-
-/** What pairs a page with its translations: the declared key, or the slug. */
-export function docTranslationKey(page: DocsPageLike): string {
-    return page.data?.translationKey ?? getCleanSlug(routedId(page))
-}
-
-/** The name navigation uses. */
-export function docLabel(page: DocsPageLike): string {
-    return page.data?.label ?? docTitle(page)
-}
-
-// ── Search index ────────────────────────────────────────────────────────────
-
-export interface DocsSearchEntry {
-    title: string
-    slug: string
-    chapter: string | null
-    keywords: string[]
-    body: string
-}
-
-/** Strip markdown (and inline HTML) syntax to plain text for search indexing. */
-export function stripMarkdown(text: string): string {
-    return text
-        .replace(/^#{1,6}\s+/gm, '')
-        .replace(/\*\*(.+?)\*\*/g, '$1')
-        .replace(/\*(.+?)\*/g, '$1')
-        .replace(/`{3,}[\s\S]*?`{3,}/g, '')
-        .replace(/(?<!`)<[^>]+>(?!`)/g, '')
-        .replace(/`(.+?)`/g, '$1')
-        .replace(/!\[([^\]]*)\]\([^)]+\)/g, '')
-        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
-        .replace(/^>\s?/gm, '')
-        .replace(/^[-*+]\s+/gm, '')
-        .replace(/^\d+\.\s+/gm, '')
-        .replace(/^:::.*$/gm, '')
-        .replace(/\n{3,}/g, '\n\n')
-        .trim()
-}
-
-/** Excerpt for <meta description>, when the page has no explicit one. */
-export function extractDescription(body: string, title: string, maxLength: number = 155): string | null {
-    const stripped = stripMarkdown(body)
-    const paragraphs = stripped
-        .split(/\n{2,}/)
-        .map((p) => p.replace(/\s+/g, ' ').trim())
-        .filter(Boolean)
-
-    const firstParagraph = paragraphs.find((p) => p.toLowerCase() !== title.trim().toLowerCase())
-    if (!firstParagraph) return null
-
-    if (firstParagraph.length <= maxLength) return firstParagraph
-    const truncated = firstParagraph.slice(0, maxLength)
-    const lastSpace = truncated.lastIndexOf(' ')
-    return `${truncated.slice(0, lastSpace > 0 ? lastSpace : maxLength)}…`
-}
-
-export function buildSearchIndex(sortedPages: DocsPageLike[]): DocsSearchEntry[] {
-    return sortedPages.map((page, index) => ({
-        title: docTitle(page),
-        slug: getCanonicalDocSlug(page, index),
-        chapter: formatChapterTitle(parseDocCollectionId(routedId(page)).chapter),
-        keywords: page.data?.keywords ?? [],
-        body: stripMarkdown(page.body || ''),
-    }))
-}

package/src/utils/endpoints.ts

@@ -1,80 +0,0 @@
-import config from 'virtual:jaad/config'
-import { getSortedDocsPages } from '../collection.ts'
-import { docsUrls } from '../docs-config.ts'
-import { docsMarkdownHref } from '../urls.ts'
-import {
-    buildSearchIndex,
-    docTitle,
-    extractDescription,
-    formatChapterTitle,
-    getCleanSlug,
-    parseDocCollectionId,
-    routedId,
-} from './docs.ts'
-
-export async function searchIndexResponse(locale?: string): Promise<Response> {
-    const index = buildSearchIndex(await getSortedDocsPages(locale))
-
-    return new Response(JSON.stringify(index), {
-        headers: { 'Content-Type': 'application/json; charset=utf-8' },
-    })
-}
-
-interface Row {
-    title: string
-    slug: string
-    description: string | null
-}
-
-/** Plain-text index of every page, per the llms.txt convention. */
-export async function llmsResponse(site: URL | undefined, locale?: string): Promise<Response> {
-    const sortedPages = await getSortedDocsPages(locale)
-
-    const markdownHref = (slug: string): string => {
-        const href = docsMarkdownHref(slug, docsUrls(locale))
-        return site ? new URL(href, site.origin).href : href
-    }
-
-    const standalone: Row[] = []
-    const chapters = new Map<string, Row[]>()
-
-    for (const page of sortedPages) {
-        const id = routedId(page)
-        const { chapter } = parseDocCollectionId(id)
-        const title = docTitle(page)
-        const row: Row = {
-            title,
-            slug: getCleanSlug(id),
-            description: page.data.description ?? extractDescription(page.body || '', title),
-        }
-
-        if (!chapter) {
-            standalone.push(row)
-            continue
-        }
-
-        const rows = chapters.get(chapter) ?? []
-        if (rows.length === 0) chapters.set(chapter, rows)
-        rows.push(row)
-    }
-
-    const toLine = (row: Row): string =>
-        `- [${row.title}](${markdownHref(row.slug)})${row.description ? `: ${row.description}` : ''}`
-
-    const sections: string[] = []
-    if (standalone.length > 0) {
-        sections.push(standalone.map(toLine).join('\n'))
-    }
-    for (const [chapter, rows] of chapters) {
-        const heading = formatChapterTitle(chapter) ?? chapter
-        sections.push(`## ${heading}\n\n${rows.map(toLine).join('\n')}`)
-    }
-
-    const content = [`# ${config.title}`, ...(config.description ? [`> ${config.description}`] : []), ...sections].join(
-        '\n\n',
-    )
-
-    return new Response(content + '\n', {
-        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-    })
-}

package/src/utils/search.ts

@@ -1,83 +0,0 @@
-export interface SearchItem {
-    title: string
-    slug: string
-    chapter: string | null
-    keywords?: string[]
-    body: string
-}
-
-const MAX_RESULTS = 10
-const EMPTY_QUERY_RESULTS = 8
-
-interface Folded {
-    title: string
-    chapter: string
-    keywords: string
-    body: string
-}
-
-/** Lowercased once per item, not once per keystroke. */
-const folded = new WeakMap<SearchItem, Folded>()
-
-function fold(item: SearchItem): Folded {
-    let f = folded.get(item)
-    if (!f) {
-        f = {
-            title: item.title.toLowerCase(),
-            chapter: item.chapter?.toLowerCase() ?? '',
-            keywords: (item.keywords ?? []).join(' ').toLowerCase(),
-            body: item.body.toLowerCase(),
-        }
-        folded.set(item, f)
-    }
-    return f
-}
-
-/** Rank by where the query appears: title, chapter, keywords, then body. */
-export function scoreItems(index: SearchItem[], query: string): SearchItem[] {
-    const q = query.trim().toLowerCase()
-    if (!q) return index.slice(0, EMPTY_QUERY_RESULTS)
-
-    return index
-        .map((item) => {
-            const f = fold(item)
-            let score = 0
-            if (f.title.includes(q)) score += 10
-            if (f.title.startsWith(q)) score += 5
-            if (f.chapter.includes(q)) score += 3
-            if (f.keywords.includes(q)) score += 2
-            if (f.body.includes(q)) score += 1
-            return { item, score }
-        })
-        .filter((s) => s.score > 0)
-        .toSorted((a, b) => b.score - a.score)
-        .slice(0, MAX_RESULTS)
-        .map((s) => s.item)
-}
-
-/** A window of body text around the first match, ellipsised at both ends. */
-export function getSnippet(body: string, query: string): string {
-    const q = query.trim()
-    if (!q) return ''
-    const idx = body.toLowerCase().indexOf(q.toLowerCase())
-    if (idx === -1) return ''
-
-    const start = Math.max(0, idx - 40)
-    const end = Math.min(body.length, idx + q.length + 80)
-    return (start > 0 ? '...' : '') + body.slice(start, end) + (end < body.length ? '...' : '')
-}
-
-/** Split around every case-insensitive occurrence, marking the matches. */
-export function splitOnMatches(text: string, query: string): { text: string; match: boolean }[] {
-    const q = query.trim()
-    if (!q) return [{ text, match: false }]
-
-    const escaped = q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-    return text
-        .split(new RegExp(`(${escaped})`, 'gi'))
-        .filter((part) => part !== '')
-        .map((part) => ({
-            text: part,
-            match: part.toLowerCase() === q.toLowerCase(),
-        }))
-}