@jaamd/jaad 0.0.0-stage → 0.11.0

package/src/components/NavMobile.astro

@@ -0,0 +1,105 @@
+---
+import config from 'virtual:jaad/config'
+import { ui } from '../docs-config.ts'
+import { withDeploymentBase } from '../urls.ts'
+
+const links = config.nav
+const t = ui(Astro.props.locale)
+---
+
+{links.length > 0 && (
+    <jaad-nav-mobile class="jaad-nav-mobile">
+        <button
+            class="jaad-icon-button"
+            aria-label={t('nav.mobile')}
+            aria-expanded="false"
+            aria-haspopup="true"
+            aria-controls="jaad-nav-menu"
+        >
+            <svg class="jaad-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path
+                    data-icon-open
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    stroke-width="2"
+                    d="M4 6h16M4 12h16M4 18h16"
+                />
+                <path
+                    data-icon-close
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    stroke-width="2"
+                    d="M6 18L18 6M6 6l12 12"
+                />
+            </svg>
+        </button>
+
+        <div id="jaad-nav-menu" data-menu hidden class="jaad-menu">
+            <nav class="jaad-nav-mobile-links">
+                <ul class="jaad-nav-mobile-list">
+                    {links.map((link) => (
+                        <li>
+                            <a
+                                href={withDeploymentBase(link.href, import.meta.env.BASE_URL)}
+                                class="jaad-menu-item"
+                                {...(link.href.startsWith('http')
+                                    ? { target: '_blank', rel: 'noopener noreferrer' }
+                                    : {})}
+                            >
+                                {link.label}
+                            </a>
+                        </li>
+                    ))}
+                </ul>
+            </nav>
+        </div>
+    </jaad-nav-mobile>
+)}
+
+<script>
+    class JaadNavMobile extends HTMLElement {
+        #button!: HTMLButtonElement
+        #menu!: HTMLElement
+
+        #onPointer = (e: PointerEvent) => {
+            if (!this.contains(e.target as Node)) this.#setOpen(false)
+        }
+        #onKey = (e: KeyboardEvent) => {
+            if (e.key === 'Escape') this.#setOpen(false)
+        }
+
+        #setOpen(open: boolean) {
+            this.#menu.hidden = !open
+            this.#button.setAttribute('aria-expanded', String(open))
+
+            if (open) {
+                document.addEventListener('pointerdown', this.#onPointer)
+                document.addEventListener('keydown', this.#onKey)
+            } else {
+                document.removeEventListener('pointerdown', this.#onPointer)
+                document.removeEventListener('keydown', this.#onKey)
+            }
+        }
+
+        connectedCallback() {
+            this.#button = this.querySelector('button')!
+            this.#menu = this.querySelector('[data-menu]')!
+
+            this.#button.addEventListener('click', () => {
+                this.#setOpen(Boolean(this.#menu.hidden))
+            })
+            this.#menu.addEventListener('click', (e) => {
+                if ((e.target as HTMLElement).closest('a')) this.#setOpen(false)
+            })
+        }
+
+        disconnectedCallback() {
+            document.removeEventListener('pointerdown', this.#onPointer)
+            document.removeEventListener('keydown', this.#onKey)
+        }
+    }
+
+    if (!customElements.get('jaad-nav-mobile')) {
+        customElements.define('jaad-nav-mobile', JaadNavMobile)
+    }
+</script>

package/src/components/ScrollToTop.astro

@@ -0,0 +1,43 @@
+---
+import { ui } from '../docs-config.ts'
+
+const t = ui(Astro.props.locale)
+---
+
+<jaad-scroll-top>
+    <button class="jaad-scroll-top-button" aria-label={t('scrollTop')}>
+        <svg class="jaad-scroll-top-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 10l7-7m0 0l7 7m-7-7v18"></path>
+        </svg>
+    </button>
+</jaad-scroll-top>
+
+<script>
+    const SHOW_AFTER = 300
+
+    class JaadScrollTop extends HTMLElement {
+        #button: HTMLButtonElement | null = null
+        #onScroll = () => {
+            const shown = window.scrollY > SHOW_AFTER
+            this.#button?.toggleAttribute('data-visible', shown)
+        }
+
+        connectedCallback() {
+            this.#button = this.querySelector('button')
+            this.#button?.addEventListener('click', () => {
+                const reduced = matchMedia('(prefers-reduced-motion: reduce)').matches
+                window.scrollTo({ top: 0, behavior: reduced ? 'auto' : 'smooth' })
+            })
+            window.addEventListener('scroll', this.#onScroll, { passive: true })
+            this.#onScroll()
+        }
+
+        disconnectedCallback() {
+            window.removeEventListener('scroll', this.#onScroll)
+        }
+    }
+
+    if (!customElements.get('jaad-scroll-top')) {
+        customElements.define('jaad-scroll-top', JaadScrollTop)
+    }
+</script>

package/src/components/SearchPalette.astro

@@ -0,0 +1,328 @@
+---
+import { DEFAULT_LOCALE, docsUrls, ui } from '../docs-config.ts'
+import { docsPageHref } from '../urls.ts'
+
+interface Props {
+    /** Whether this page is part of the docs. Off them the palette keeps its
+     *  icon trigger and its shortcut, and searches the default locale. */
+    inDocs?: boolean
+    /** Search covers one locale: the one the reader is in. */
+    locale?: string
+}
+
+const { inDocs = false, locale = DEFAULT_LOCALE } = Astro.props
+const urls = docsUrls(locale)
+const t = ui(locale)
+const base = docsPageHref('', urls)
+const indexUrl = docsPageHref('search-index.json', urls)
+
+const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
+---
+
+<jaad-search
+    data-in-docs={inDocs ? '' : null}
+    data-base={base}
+    data-index-url={indexUrl}
+    data-loading={t('search.loading')}
+    data-empty={t('search.empty')}
+>
+    <button data-trigger-desktop hidden={!inDocs} class="jaad-search-trigger" aria-label={t('search.label')}>
+        <svg class="jaad-search-trigger-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d={MAGNIFIER}></path>
+        </svg>
+        <span class="jaad-search-trigger-label">{t('search.trigger')}</span>
+        <kbd data-shortcut class="jaad-search-shortcut">
+            Ctrl K
+        </kbd>
+    </button>
+
+    <button
+        data-trigger-icon
+        class:list={['jaad-icon-button', inDocs && 'jaad-search-trigger-compact']}
+        aria-label={t('search.label')}
+    >
+        <svg class="jaad-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d={MAGNIFIER}></path>
+        </svg>
+    </button>
+
+    <div data-overlay hidden class="jaad-search-overlay" role="dialog" aria-modal="true" aria-label={t('search.label')}>
+        <div data-backdrop class="jaad-search-backdrop"></div>
+
+        <div class="jaad-search-panel">
+            <div class="jaad-search-bar">
+                <svg
+                    class="jaad-search-bar-icon"
+                    fill="none"
+                    stroke="currentColor"
+                    viewBox="0 0 24 24"
+                    aria-hidden="true"
+                >
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d={MAGNIFIER}></path>
+                </svg>
+                <input
+                    data-input
+                    type="text"
+                    placeholder={t('search.placeholder')}
+                    class="jaad-search-input"
+                    autocomplete="off"
+                    spellcheck="false"
+                    role="combobox"
+                    aria-expanded="true"
+                    aria-controls="search-results"
+                    aria-autocomplete="list"
+                    aria-label={t('search.label')}
+                />
+                <kbd data-close class="jaad-search-close">
+                    ESC
+                </kbd>
+            </div>
+
+            <ul
+                data-results
+                id="search-results"
+                class="jaad-search-results"
+                role="listbox"
+                aria-label={t('search.results')}
+            ></ul>
+
+            <div class="jaad-search-footer">
+                <span>
+                    <kbd class="jaad-search-key">↑↓</kbd>
+                    {t('search.navigate')}
+                </span>
+                <span>
+                    <kbd class="jaad-search-key">↵</kbd>
+                    {t('search.open')}
+                </span>
+                <span>
+                    <kbd class="jaad-search-key">esc</kbd>
+                    {t('search.close')}
+                </span>
+            </div>
+        </div>
+    </div>
+</jaad-search>
+
+<script>
+    import { navigate } from 'astro:transitions/client'
+    import { scoreItems, getSnippet, splitOnMatches, type SearchItem } from '../utils/search.ts'
+
+    class JaadSearch extends HTMLElement {
+        #overlay!: HTMLElement
+        #input!: HTMLInputElement
+        #list!: HTMLUListElement
+        #index: SearchItem[] | null = null
+        #request: Promise<SearchItem[]> | null = null
+        #results: SearchItem[] = []
+        #selected = 0
+        #restoreFocus: HTMLElement | null = null
+        #previousOverflow = ''
+
+        get #open() {
+            return !this.#overlay.hidden
+        }
+
+        connectedCallback() {
+            this.#overlay = this.querySelector('[data-overlay]')!
+            this.#input = this.querySelector('[data-input]')!
+            this.#list = this.querySelector('[data-results]')!
+
+            if (/Mac|iPod|iPhone|iPad/.test(navigator.userAgent)) {
+                this.querySelector('[data-shortcut]')!.textContent = '⌘K'
+            }
+
+            for (const sel of ['[data-trigger-desktop]', '[data-trigger-icon]']) {
+                const trigger = this.querySelector<HTMLElement>(sel)!
+                trigger.addEventListener('click', () => this.#setOpen(true))
+                trigger.addEventListener('mouseenter', () => void this.#loadIndex())
+                trigger.addEventListener('focus', () => void this.#loadIndex())
+            }
+
+            this.querySelector('[data-backdrop]')!.addEventListener('click', () => this.#setOpen(false))
+            this.querySelector('[data-close]')!.addEventListener('click', () => this.#setOpen(false))
+
+            this.#input.addEventListener('input', () => this.#render())
+            this.#input.addEventListener('keydown', (e) => this.#onInputKey(e))
+
+            document.addEventListener('keydown', this.#onGlobalKey)
+            document.addEventListener('astro:before-swap', this.#syncLocale)
+        }
+
+        disconnectedCallback() {
+            document.removeEventListener('keydown', this.#onGlobalKey)
+            document.removeEventListener('astro:before-swap', this.#syncLocale)
+        }
+
+        /** Each locale has its own index, so a language switch drops the cache. */
+        #syncLocale = (event: Event) => {
+            const next = (event as Event & { newDocument: Document }).newDocument.querySelector<HTMLElement>(
+                'jaad-search',
+            )
+            if (!next) return
+
+            const indexUrl = next.dataset.indexUrl
+            if (indexUrl && indexUrl !== this.dataset.indexUrl) {
+                this.dataset.indexUrl = indexUrl
+                this.#index = null
+                this.#request = null
+            }
+            if (next.dataset.base) this.dataset.base = next.dataset.base
+        }
+
+        #onGlobalKey = (e: KeyboardEvent) => {
+            if ((e.ctrlKey || e.metaKey) && e.key === 'k') {
+                e.preventDefault()
+                this.#setOpen(!this.#open)
+            } else if (e.key === 'Escape' && this.#open) {
+                e.preventDefault()
+                this.#setOpen(false)
+            }
+        }
+
+        #onInputKey(e: KeyboardEvent) {
+            if (e.key === 'ArrowDown') {
+                e.preventDefault()
+                this.#select(Math.min(this.#selected + 1, this.#results.length - 1))
+            } else if (e.key === 'ArrowUp') {
+                e.preventDefault()
+                this.#select(Math.max(this.#selected - 1, 0))
+            } else if (e.key === 'Enter' && this.#results[this.#selected]) {
+                this.#go(this.#results[this.#selected].slug)
+            }
+        }
+
+        #loadIndex(): Promise<SearchItem[]> {
+            if (this.#index) return Promise.resolve(this.#index)
+            if (!this.#request) {
+                const url = this.dataset.indexUrl ?? '/search-index.json'
+                this.#request = fetch(url)
+                    .then((res) => (res.ok ? res.json() : []))
+                    .then((data: SearchItem[]) => (this.#index = data))
+                    .catch(() => {
+                        // Drop the failed promise so a later attempt can retry.
+                        this.#request = null
+                        return []
+                    })
+            }
+            return this.#request
+        }
+
+        #setOpen(open: boolean) {
+            if (open === this.#open) return
+            this.#overlay.hidden = !open
+
+            if (open) {
+                this.#restoreFocus = document.activeElement as HTMLElement | null
+                this.#previousOverflow = document.body.style.overflow
+                document.body.style.overflow = 'hidden'
+                requestAnimationFrame(() => this.#input.focus())
+                void this.#loadIndex().then(() => this.#render())
+                this.#render()
+            } else {
+                document.body.style.overflow = this.#previousOverflow
+                this.#input.value = ''
+                this.#restoreFocus?.focus?.()
+            }
+        }
+
+        #go(slug: string) {
+            this.#setOpen(false)
+            const base = this.dataset.base ?? '/'
+            const prefix = base === '/' ? '' : base.replace(/\/$/, '')
+            navigate(slug ? `${prefix}/${slug}` : base)
+        }
+
+        #select(i: number) {
+            this.#selected = i
+            this.#input.setAttribute('aria-activedescendant', `search-option-${i}`)
+            ;[...this.#list.children].forEach((li, n) => {
+                const active = n === i
+                li.setAttribute('aria-selected', String(active))
+            })
+            ;(this.#list.children[i] as HTMLElement | undefined)?.scrollIntoView({
+                block: 'nearest',
+            })
+        }
+
+        #marked(text: string, query: string): DocumentFragment {
+            const frag = document.createDocumentFragment()
+            for (const part of splitOnMatches(text, query)) {
+                if (part.match) {
+                    const mark = document.createElement('mark')
+                    mark.className = 'jaad-search-mark'
+                    mark.textContent = part.text
+                    frag.append(mark)
+                } else {
+                    frag.append(document.createTextNode(part.text))
+                }
+            }
+            return frag
+        }
+
+        #render() {
+            const query = this.#input.value
+            this.#list.replaceChildren()
+            this.#input.removeAttribute('aria-activedescendant')
+
+            if (!this.#index) {
+                this.#list.append(this.#message(this.dataset.loading ?? 'Loading...'))
+                return
+            }
+
+            this.#results = scoreItems(this.#index, query)
+
+            if (this.#results.length === 0) {
+                this.#list.append(this.#message(`${this.dataset.empty ?? 'No results for'} “${query}”`))
+                return
+            }
+
+            this.#results.forEach((item, i) => {
+                const li = document.createElement('li')
+                li.id = `search-option-${i}`
+                li.setAttribute('role', 'option')
+                li.className = 'jaad-search-result'
+                li.addEventListener('click', () => this.#go(item.slug))
+                li.addEventListener('mouseenter', () => this.#select(i))
+
+                const head = document.createElement('div')
+                head.className = 'jaad-search-result-head'
+                const title = document.createElement('span')
+                title.className = 'jaad-search-result-title'
+                title.append(this.#marked(item.title, query))
+                head.append(title)
+
+                if (item.chapter) {
+                    const badge = document.createElement('span')
+                    badge.className = 'jaad-search-result-badge'
+                    badge.textContent = item.chapter
+                    head.append(badge)
+                }
+                li.append(head)
+
+                const snippet = getSnippet(item.body, query)
+                if (snippet) {
+                    const p = document.createElement('p')
+                    p.className = 'jaad-search-result-snippet'
+                    p.append(this.#marked(snippet, query))
+                    li.append(p)
+                }
+
+                this.#list.append(li)
+            })
+
+            this.#select(0)
+        }
+
+        #message(text: string): HTMLLIElement {
+            const li = document.createElement('li')
+            li.className = 'jaad-search-message'
+            li.textContent = text
+            return li
+        }
+    }
+
+    if (!customElements.get('jaad-search')) {
+        customElements.define('jaad-search', JaadSearch)
+    }
+</script>

package/src/components/SocialLinks.astro

@@ -0,0 +1,27 @@
+---
+import config from 'virtual:jaad/config'
+import { buildSocialLinks } from '../social.ts'
+
+const links = buildSocialLinks(config)
+---
+
+{links.map((link) => (
+    <a
+        href={link.href}
+        target="_blank"
+        rel="noopener noreferrer"
+        title={link.label}
+        aria-label={link.label}
+        class="jaad-icon-button"
+    >
+        {link.svg ? (
+            <span class="jaad-social-icon" set:html={link.svg} />
+        ) : link.path ? (
+            <svg class="jaad-icon" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+                <path d={link.path} />
+            </svg>
+        ) : (
+            <span class="jaad-social-label">{link.label}</span>
+        )}
+    </a>
+))}

package/src/components/ThemeSwitcher.astro

@@ -0,0 +1,55 @@
+---
+// The theme class and the icon are already set in <head>; only the click is JS.
+import { ui } from '../docs-config.ts'
+
+const t = ui(Astro.props.locale)
+---
+
+<jaad-theme-toggle>
+    <button class="jaad-icon-button" aria-label={t('theme.toggle')} title={t('theme.toggle')}>
+        <svg
+            class="jaad-theme-icon-to-dark jaad-icon"
+            fill="none"
+            stroke="currentColor"
+            viewBox="0 0 24 24"
+            aria-hidden="true"
+        >
+            <path
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                stroke-width="2"
+                d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z"
+            ></path>
+        </svg>
+
+        <svg
+            class="jaad-theme-icon-to-light jaad-icon"
+            fill="none"
+            stroke="currentColor"
+            viewBox="0 0 24 24"
+            aria-hidden="true"
+        >
+            <path
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                stroke-width="2"
+                d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z"
+            ></path>
+        </svg>
+    </button>
+</jaad-theme-toggle>
+
+<script>
+    class JaadThemeToggle extends HTMLElement {
+        connectedCallback() {
+            this.querySelector('button')?.addEventListener('click', () => {
+                const isDark = document.documentElement.classList.toggle('dark')
+                localStorage.setItem('theme', isDark ? 'dark' : 'light')
+            })
+        }
+    }
+
+    if (!customElements.get('jaad-theme-toggle')) {
+        customElements.define('jaad-theme-toggle', JaadThemeToggle)
+    }
+</script>

package/src/components/docs/Breadcrumbs.astro

@@ -0,0 +1,36 @@
+---
+import config from 'virtual:jaad/config'
+import { docsUrls, ui } from '../../docs-config.ts'
+import { docsPageHref } from '../../urls.ts'
+import { formatChapterTitle } from '../../utils/docs.ts'
+
+interface Props {
+    chapter?: string
+    title: string
+    locale?: string
+}
+
+const { chapter, title, locale } = Astro.props
+const t = ui(locale)
+const chapterTitle = formatChapterTitle(chapter)
+
+const rootSegment = config.docsBase.split('/').filter(Boolean).at(-1)
+const rootLabel = formatChapterTitle(rootSegment) ?? t('breadcrumb.root')
+const rootHref = docsPageHref('', docsUrls(locale))
+---
+
+<nav aria-label={t('breadcrumb.label')} class="docs-breadcrumbs">
+    <a href={rootHref} class="docs-breadcrumbs-link">
+        {rootLabel}
+    </a>
+    {chapterTitle && (
+        <>
+            <span aria-hidden="true">/</span>
+            <span>{chapterTitle}</span>
+        </>
+    )}
+    <span aria-hidden="true">/</span>
+    <span class="docs-breadcrumbs-current" aria-current="page">
+        {title}
+    </span>
+</nav>

package/src/components/docs/DocsMobileNav.astro

@@ -0,0 +1,93 @@
+---
+import type { DocsHeadings } from '../../@types/docs.ts'
+import type { NavSection } from '../../navigation.ts'
+import { ui } from '../../docs-config.ts'
+import { formatChapterTitle } from '../../utils/docs.ts'
+import ScrollToTop from '../ScrollToTop.astro'
+
+interface Props {
+    locale?: string
+    sections: NavSection[]
+    headings: DocsHeadings[]
+}
+
+const { sections, headings, locale } = Astro.props
+const t = ui(locale)
+---
+
+<div class="docs-mobile-nav">
+    <div class="docs-select">
+        <label for="page-select" class="jaad-sr-only">
+            {t('nav.selectPage')}
+        </label>
+        <select id="page-select" class="docs-select-field">
+            {sections.map((section) =>
+                section.type === 'page' ? (
+                    <option value={section.item.href} selected={section.item.isActive}>
+                        {section.item.title}
+                    </option>
+                ) : (
+                    <optgroup label={formatChapterTitle(section.chapter) || section.chapter}>
+                        {section.items.map((page) => (
+                            <option value={page.href} selected={page.isActive}>
+                                {page.title}
+                            </option>
+                        ))}
+                    </optgroup>
+                ),
+            )}
+        </select>
+    </div>
+
+    {headings.length > 0 && (
+        <div id="section-select-wrapper" class="docs-select">
+            <label for="section-select" class="jaad-sr-only">
+                Jump to section
+            </label>
+            <select id="section-select" class="docs-select-field">
+                <option value="">{t('nav.jumpToSection')}</option>
+                {headings.map((heading) => {
+                    const prefix = heading.depth === 3 ? '\u00A0\u00A0\u00A0\u00A0' : ''
+                    return (
+                        <option value={`#${heading.slug}`}>
+                            {prefix}
+                            {heading.text}
+                        </option>
+                    )
+                })}
+            </select>
+        </div>
+    )}
+</div>
+
+<ScrollToTop {locale} />
+
+<script>
+    import { navigate } from 'astro:transitions/client'
+
+    function initMobileNav(): void {
+        const pageSelect = document.querySelector<HTMLSelectElement>('#page-select')
+        const sectionSelect = document.querySelector<HTMLSelectElement>('#section-select')
+
+        if (pageSelect && !pageSelect.dataset.navInit) {
+            pageSelect.dataset.navInit = '1'
+            pageSelect.addEventListener('change', () => {
+                if (pageSelect.value) navigate(pageSelect.value)
+            })
+        }
+
+        if (sectionSelect && !sectionSelect.dataset.navInit) {
+            sectionSelect.dataset.navInit = '1'
+            sectionSelect.addEventListener('change', () => {
+                const target = sectionSelect.value
+                if (!target) return
+                document.querySelector(target)?.scrollIntoView({ behavior: 'smooth', block: 'start' })
+                // Reset so picking the same section twice in a row fires again.
+                setTimeout(() => (sectionSelect.value = ''), 500)
+            })
+        }
+    }
+
+    initMobileNav()
+    document.addEventListener('astro:page-load', initMobileNav)
+</script>