@jaamd/jaad 0.0.0-stage → 0.11.0

package/src/routes/llms.txt.ts

@@ -0,0 +1,4 @@
+import type { APIRoute } from 'astro'
+import { llmsResponse } from '../utils/endpoints.ts'
+
+export const GET: APIRoute = ({ site }) => llmsResponse(site)

package/src/routes/search-index-locale.json.ts

@@ -0,0 +1,8 @@
+import type { APIRoute, GetStaticPaths } from 'astro'
+import { getServedLocales } from '../collection.ts'
+import { searchIndexResponse } from '../utils/endpoints.ts'
+
+export const getStaticPaths: GetStaticPaths = async () =>
+    (await getServedLocales()).map((locale) => ({ params: { locale } }))
+
+export const GET: APIRoute = ({ params }) => searchIndexResponse(params.locale)

package/src/routes/search-index.json.ts

@@ -0,0 +1,4 @@
+import type { APIRoute } from 'astro'
+import { searchIndexResponse } from '../utils/endpoints.ts'
+
+export const GET: APIRoute = () => searchIndexResponse()

package/src/social.ts

@@ -0,0 +1,44 @@
+import type { JaadResolvedConfig } from './config.ts'
+import { FORGES, forgeForUrl } from './forges.ts'
+
+export interface SocialLink {
+    href: string
+    label: string
+    /** Bundled forge icon. */
+    path?: string
+    /** User-supplied markup, which wins over the bundled icon. */
+    svg?: string
+}
+
+/** The configured links, plus the inferred repository unless already listed. */
+export function buildSocialLinks(config: JaadResolvedConfig): SocialLink[] {
+    const links: SocialLink[] = []
+
+    for (const [key, value] of Object.entries(config.social)) {
+        const entry = typeof value === 'string' ? { href: value } : value
+        const forge = FORGES[key]
+        links.push({
+            href: entry.href,
+            label:
+                // FORGES has no index signature guarantee: a missing key is undefined.
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                ('label' in entry ? entry.label : undefined) ?? forge?.label ?? key,
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            path: forge?.path,
+            svg: 'svg' in entry ? entry.svg : undefined,
+        })
+    }
+
+    const namedAForge = Object.keys(config.social).some((key) => key in FORGES)
+
+    if (config.repoUrl && !namedAForge && !links.some((l) => l.href === config.repoUrl)) {
+        const forge = forgeForUrl(config.repoUrl)
+        links.push({
+            href: config.repoUrl,
+            label: forge ? FORGES[forge].label : 'Repository',
+            path: forge ? FORGES[forge].path : undefined,
+        })
+    }
+
+    return links
+}

package/src/styles/components/breadcrumbs.css

@@ -0,0 +1,13 @@
+@layer components {
+    .docs-breadcrumbs {
+        @apply text-foreground-muted mb-4 flex items-center gap-1.5 text-xs;
+    }
+
+    .docs-breadcrumbs-link {
+        @apply hover:text-foreground-bright no-underline;
+    }
+
+    .docs-breadcrumbs-current {
+        @apply text-foreground-bright font-medium;
+    }
+}

package/src/styles/components/docs-mobile-nav.css

@@ -0,0 +1,9 @@
+@layer components {
+    .docs-mobile-nav {
+        @apply mb-8 space-y-4 lg:hidden;
+    }
+
+    .docs-select-field {
+        @apply border-primary/20 bg-surface text-foreground focus:border-primary w-full appearance-none rounded-lg border py-3 pr-10 pl-4 transition-colors focus:outline-none;
+    }
+}

package/src/styles/components/docs-page-nav.css

@@ -0,0 +1,31 @@
+@layer components {
+    .docs-page-nav {
+        @apply py-8;
+    }
+
+    .docs-page-nav-row {
+        @apply flex items-center justify-between gap-4;
+    }
+
+    .docs-page-nav-link {
+        @apply border-border-dark bg-background-tertiary text-foreground-bright hover:border-primary hover:bg-border-dark hover:text-primary flex max-w-[calc(45%-1rem)] min-w-0 items-center gap-2 rounded-lg border px-4 py-3 no-underline transition-all duration-300;
+    }
+
+    .docs-page-nav-icon {
+        @apply h-4 w-4 shrink-0 transition-transform;
+    }
+
+    @media (hover: hover) {
+        .docs-page-nav-link:hover .docs-page-nav-icon-prev {
+            @apply -translate-x-1;
+        }
+
+        .docs-page-nav-link:hover .docs-page-nav-icon-next {
+            @apply translate-x-1;
+        }
+    }
+
+    .docs-page-nav-label {
+        @apply overflow-hidden font-medium text-ellipsis whitespace-nowrap;
+    }
+}

package/src/styles/components/docs-page.css

@@ -0,0 +1,9 @@
+@layer components {
+    .docs-content {
+        @apply w-full leading-relaxed wrap-break-word;
+    }
+
+    .docs-updated {
+        @apply text-foreground-muted mt-8 text-xs;
+    }
+}

package/src/styles/components/docs-sidebar.css

@@ -0,0 +1,42 @@
+@layer components {
+    .docs-sidebar-page {
+        @apply mb-0.5;
+    }
+
+    .docs-sidebar-page:not(:first-child) {
+        @apply mt-0.5;
+    }
+
+    .docs-sidebar-link,
+    .docs-sidebar-sublink {
+        @apply text-foreground hover:bg-primary/10 hover:text-primary block px-3 py-1.5 text-sm no-underline transition-colors;
+    }
+
+    .docs-sidebar-link {
+        @apply rounded;
+    }
+
+    .docs-sidebar-sublink {
+        @apply rounded-r;
+    }
+
+    .docs-sidebar-link[aria-current='page'] {
+        @apply bg-primary/10 text-primary font-semibold;
+    }
+
+    .docs-sidebar-sublink[aria-current='page'] {
+        @apply border-primary bg-primary/10 text-primary -ml-px border-l-2 pl-2.75 font-semibold;
+    }
+
+    .docs-sidebar-chapter {
+        @apply mt-5 mb-5;
+    }
+
+    .docs-sidebar-chapter-title {
+        @apply text-primary/50 mb-1 px-3 text-[0.825rem] font-semibold tracking-widest uppercase;
+    }
+
+    .docs-sidebar-chapter-list {
+        @apply border-border/40 ml-3 space-y-0.5 border-l pl-0;
+    }
+}

package/src/styles/components/footer.css

@@ -0,0 +1,8 @@
+@layer components {
+    .jaad-footer {
+        @apply border-border-dark mt-4 border-t pt-2;
+    }
+    .jaad-footer-credit {
+        @apply text-foreground-muted mb-1 text-center text-[0.95rem] leading-[1.6] italic;
+    }
+}

package/src/styles/components/header.css

@@ -0,0 +1,20 @@
+@layer components {
+    .jaad-header-inner {
+        @apply container mx-auto p-4;
+    }
+    .jaad-header-row {
+        @apply flex items-center gap-4;
+    }
+    .jaad-brand {
+        @apply text-foreground-bright text-xl;
+    }
+    .jaad-brand-link {
+        @apply text-primary no-underline;
+    }
+    .jaad-logo {
+        @apply h-7;
+    }
+    .jaad-header-actions {
+        @apply ml-auto flex items-center gap-2;
+    }
+}

package/src/styles/components/locale-switcher.css

@@ -0,0 +1,20 @@
+@layer components {
+    .jaad-locale-switcher {
+        @apply relative;
+    }
+    .jaad-locale-trigger {
+        @apply w-auto gap-1.5 px-2;
+    }
+    .jaad-locale-code {
+        @apply text-xs font-medium uppercase;
+    }
+    .jaad-locale-chevron {
+        @apply h-3 w-3 shrink-0;
+    }
+    .jaad-locale-menu {
+        @apply p-1;
+    }
+    .jaad-locale-item {
+        @apply flex items-center gap-2 aria-[current]:font-semibold;
+    }
+}

package/src/styles/components/nav-mobile.css

@@ -0,0 +1,15 @@
+@layer components {
+    .jaad-nav-mobile {
+        @apply relative md:hidden;
+    }
+    .jaad-nav-mobile [aria-expanded='true'] [data-icon-open],
+    .jaad-nav-mobile [aria-expanded='false'] [data-icon-close] {
+        @apply hidden;
+    }
+    .jaad-nav-mobile-links {
+        @apply p-2;
+    }
+    .jaad-nav-mobile-list {
+        @apply flex flex-col gap-1;
+    }
+}

package/src/styles/components/nav.css

@@ -0,0 +1,11 @@
+@layer components {
+    .jaad-nav {
+        @apply hidden md:block;
+    }
+    .jaad-nav-list {
+        @apply flex space-x-4;
+    }
+    .jaad-nav-link {
+        @apply text-foreground-secondary hover:text-foreground-bright no-underline hover:underline;
+    }
+}

package/src/styles/components/not-found.css

@@ -0,0 +1,11 @@
+@layer components {
+    .jaad-not-found {
+        @apply m-auto flex h-full w-full flex-col items-center justify-center px-16 text-center;
+    }
+    .jaad-not-found-title {
+        @apply mb-16 text-6xl font-bold;
+    }
+    .jaad-not-found-text {
+        @apply mb-32 text-xl;
+    }
+}

package/src/styles/components/page-actions.css

@@ -0,0 +1,13 @@
+@layer components {
+    .docs-page-actions {
+        @apply mb-4 flex items-center gap-2 text-xs;
+    }
+
+    .docs-page-action {
+        @apply border-border bg-surface hover:bg-surface-hover text-foreground-secondary hover:text-foreground-bright flex cursor-pointer items-center gap-1.5 rounded-lg border px-3 py-1.5 no-underline transition-colors;
+    }
+
+    .docs-page-action-icon {
+        @apply h-3.5 w-3.5 shrink-0;
+    }
+}

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

@@ -0,0 +1,11 @@
+@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/search.css

@@ -0,0 +1,98 @@
+@layer components {
+    .jaad-search-trigger {
+        @apply border-border bg-surface hover:bg-surface-hover text-foreground-muted hidden cursor-pointer items-center gap-2 rounded-lg border px-3 py-1.5 text-sm transition-colors md:flex;
+    }
+
+    .jaad-search-trigger-icon {
+        @apply h-4 w-4 shrink-0;
+    }
+
+    .jaad-search-trigger-label {
+        @apply hidden lg:inline;
+    }
+
+    .jaad-search-shortcut {
+        @apply bg-background-secondary text-foreground-muted rounded px-1.5 py-0.5 text-xs font-medium;
+    }
+
+    /* Icon trigger on a docs page, where the desktop field is shown from md. */
+    .jaad-search-trigger-compact {
+        @apply md:hidden;
+    }
+
+    .jaad-search-overlay {
+        @apply fixed inset-0 z-50 flex items-start justify-center px-4 pt-[15vh];
+    }
+
+    .jaad-search-backdrop {
+        @apply absolute inset-0 bg-black/60 backdrop-blur-sm;
+    }
+
+    .jaad-search-panel {
+        @apply bg-surface border-border relative z-10 w-full max-w-lg overflow-hidden rounded-xl border shadow-2xl;
+    }
+
+    .jaad-search-bar {
+        @apply border-border flex items-center gap-3 border-b px-4 py-3;
+    }
+
+    .jaad-search-bar-icon {
+        @apply text-foreground-muted h-5 w-5 shrink-0;
+    }
+
+    .jaad-search-input {
+        @apply text-foreground placeholder:text-foreground-muted min-w-0 flex-1 bg-transparent text-sm outline-none;
+    }
+
+    .jaad-search-close {
+        @apply bg-background-secondary text-foreground-muted shrink-0 cursor-pointer rounded px-1.5 py-0.5 text-xs;
+    }
+
+    .jaad-search-results {
+        @apply max-h-80 overflow-y-auto p-2;
+    }
+
+    .jaad-search-footer {
+        @apply border-border text-foreground-muted flex items-center gap-4 border-t px-4 py-2 text-xs;
+    }
+
+    .jaad-search-key {
+        @apply bg-background-secondary rounded px-1 py-0.5;
+    }
+
+    .jaad-search-result {
+        @apply text-foreground cursor-pointer rounded-lg px-3 py-2.5 text-left transition-colors;
+    }
+
+    .jaad-search-result:not([aria-selected='true']) {
+        @apply hover:bg-primary/5;
+    }
+
+    .jaad-search-result[aria-selected='true'] {
+        @apply bg-primary/10 text-foreground-bright;
+    }
+
+    .jaad-search-result-head {
+        @apply flex items-center gap-2;
+    }
+
+    .jaad-search-result-title {
+        @apply text-sm font-medium;
+    }
+
+    .jaad-search-result-badge {
+        @apply text-foreground-muted bg-background-secondary rounded px-1.5 py-0.5 text-[0.65rem];
+    }
+
+    .jaad-search-result-snippet {
+        @apply text-foreground-secondary mt-1 line-clamp-1 text-xs;
+    }
+
+    .jaad-search-mark {
+        @apply bg-primary/20 text-foreground-bright rounded-sm px-0.5 font-semibold not-italic;
+    }
+
+    .jaad-search-message {
+        @apply text-foreground-muted px-3 py-6 text-center text-sm;
+    }
+}

package/src/styles/components/shell.css

@@ -0,0 +1,73 @@
+/* Shared shell classes; first in the layer so component files override them. */
+@layer components {
+    /* Header, footer and docs content share one measure. */
+    .jaad-chrome {
+        width: 100%;
+        max-width: var(--jaad-chrome-width);
+        margin-inline: auto;
+    }
+
+    .jaad-main {
+        flex: 1;
+        margin-block: 4rem;
+        padding-inline: var(--jaad-page-padding);
+    }
+
+    @media (min-width: 64rem) {
+        .jaad-main {
+            padding-inline: calc(var(--jaad-page-padding) * 2);
+        }
+    }
+
+    /* `bare` keeps the landmark without the spacing. */
+    .jaad-main-bare {
+        flex: 1;
+    }
+
+    .jaad-body {
+        @apply bg-background text-foreground flex min-h-screen flex-col text-[14px] leading-[1.6];
+    }
+
+    .jaad-icon {
+        @apply h-5 w-5;
+    }
+
+    .jaad-sr-only {
+        @apply sr-only;
+    }
+
+    .jaad-sidebar {
+        width: var(--jaad-sidebar-width);
+        overflow-y: auto;
+    }
+
+    .jaad-sidebar::-webkit-scrollbar {
+        width: 6px;
+    }
+
+    .jaad-sidebar::-webkit-scrollbar-track {
+        background: transparent;
+    }
+
+    .jaad-sidebar::-webkit-scrollbar-thumb {
+        background: rgb(from var(--color-primary) r g b / 0.2);
+        border-radius: 3px;
+    }
+
+    .jaad-sidebar::-webkit-scrollbar-thumb:hover {
+        background: rgb(from var(--color-primary) r g b / 0.4);
+    }
+
+    /* The header controls sit in one row and have to stay identical. */
+    .jaad-icon-button {
+        @apply text-foreground-secondary hover:text-foreground-bright flex h-9 w-9 cursor-pointer items-center justify-center rounded-lg no-underline transition-colors;
+    }
+
+    .jaad-menu {
+        @apply bg-surface border-border absolute top-full right-0 z-40 mt-2 w-44 overflow-hidden rounded-xl border shadow-lg;
+    }
+
+    .jaad-menu-item {
+        @apply text-foreground-secondary hover:text-foreground-bright hover:bg-primary/5 block rounded-lg px-3 py-2 text-sm no-underline transition-colors;
+    }
+}

package/src/styles/components/social-links.css

@@ -0,0 +1,8 @@
+@layer components {
+    .jaad-social-icon {
+        @apply flex h-5 w-5 items-center justify-center;
+    }
+    .jaad-social-label {
+        @apply text-xs;
+    }
+}

package/src/styles/components/theme-switcher.css

@@ -0,0 +1,14 @@
+@layer components {
+    /* Both icons ship; CSS picks one, so the server-rendered control is correct. */
+    .jaad-theme-icon-to-light {
+        display: none;
+    }
+
+    html.dark .jaad-theme-icon-to-dark {
+        display: none;
+    }
+
+    html.dark .jaad-theme-icon-to-light {
+        display: block;
+    }
+}

package/src/styles/components/toc.css

@@ -0,0 +1,21 @@
+@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

@@ -0,0 +1,112 @@
+/* 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;
+    }
+}