@jaamd/jaad 0.11.0 → 1.0.0

package/src/docs/styles/components/breadcrumbs.css

@@ -0,0 +1,26 @@
+@layer components {
+    .docs-breadcrumbs {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.375rem;
+        margin-bottom: 0.5rem;
+        font-size: 0.8125rem;
+        color: var(--color-foreground-muted);
+    }
+
+    .docs-breadcrumbs-link {
+        color: inherit;
+        text-decoration: none;
+    }
+
+    .docs-breadcrumbs-link:hover {
+        color: var(--color-foreground-bright);
+    }
+
+    /* Narrow, the navigation menu above already names them. */
+    @media (width < 64rem) {
+        [data-jaad-default-frame] .docs-breadcrumbs {
+            display: none;
+        }
+    }
+}

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

@@ -0,0 +1,47 @@
+@layer components {
+    .docs-mobile-nav {
+        margin-bottom: 1.5rem;
+        border-top: 1px solid var(--color-border);
+        font-size: 0.875rem;
+    }
+
+    .docs-mobile-menu {
+        border-bottom: 1px solid var(--color-border);
+    }
+
+    .docs-mobile-summary {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 0.375rem;
+        min-height: 2.75rem;
+        color: var(--color-foreground-muted);
+        cursor: pointer;
+        list-style: none;
+    }
+
+    .docs-mobile-summary::-webkit-details-marker {
+        display: none;
+    }
+
+    .docs-mobile-icon {
+        width: 1rem;
+        height: 1rem;
+        margin-right: 0.25rem;
+    }
+
+    .docs-mobile-current {
+        color: var(--color-foreground-bright);
+        font-weight: 500;
+    }
+
+    .docs-mobile-tree {
+        padding: 0.25rem 0 1rem 0.75rem;
+    }
+
+    @media (min-width: 64rem) {
+        .docs-mobile-nav {
+            display: none;
+        }
+    }
+}

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

@@ -0,0 +1,41 @@
+@layer components {
+    .docs-page-nav {
+        margin-top: 3rem;
+        padding-top: 0.5rem;
+        border-top: 1px solid var(--color-border);
+    }
+
+    .docs-page-nav-row {
+        display: flex;
+        justify-content: space-between;
+        gap: 1rem;
+    }
+
+    .docs-page-nav-link {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        min-width: 0;
+        max-width: calc(50% - 0.5rem);
+        min-height: 2.75rem;
+        color: var(--color-foreground-bright);
+        font-size: 0.875rem;
+        text-decoration: none;
+    }
+
+    .docs-page-nav-link:hover {
+        color: var(--color-foreground-muted);
+    }
+
+    .docs-page-nav-icon {
+        flex: none;
+        width: 1rem;
+        height: 1rem;
+    }
+
+    .docs-page-nav-label {
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+}

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

@@ -0,0 +1,59 @@
+@layer components {
+    .docs-sidebar-left nav {
+        font-size: 0.875rem;
+        line-height: 1.5;
+    }
+
+    .docs-sidebar-list {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+    }
+
+    /* The bar of the current page sits in the gutter, so every label lines up. */
+    .docs-sidebar-link {
+        display: block;
+        margin-left: -0.75rem;
+        padding: 0.25rem 0 0.25rem calc(0.75rem - 2px);
+        border-left: 2px solid transparent;
+        color: var(--color-foreground);
+        text-decoration: none;
+    }
+
+    .docs-sidebar-link:hover {
+        color: var(--color-foreground-bright);
+    }
+
+    .docs-sidebar-link[aria-current='page'] {
+        border-color: var(--color-foreground-bright);
+        color: var(--color-foreground-bright);
+        font-weight: 500;
+    }
+
+    .docs-sidebar-chapter {
+        margin-top: 1rem;
+    }
+
+    .docs-sidebar-chapter + li:not(.docs-sidebar-chapter) {
+        margin-top: 1rem;
+    }
+
+    .docs-sidebar-chapter-title {
+        margin: 0 0 0.25rem;
+        font-size: 0.75rem;
+        font-weight: 500;
+        color: var(--color-foreground-muted);
+    }
+
+    .docs-sidebar-section {
+        margin-top: 1rem;
+        padding-top: 0.75rem;
+        border-top: 1px solid var(--color-border);
+    }
+
+    .docs-sidebar-section-title {
+        margin: 0 0 0.25rem;
+        color: var(--color-foreground-bright);
+        font-weight: 600;
+    }
+}

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

@@ -0,0 +1,51 @@
+@layer components {
+    .docs-page-actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.25rem 1.25rem;
+        margin-top: 2rem;
+        font-size: 0.8125rem;
+    }
+
+    .docs-page-action {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        min-height: 2.75rem;
+        padding: 0;
+        border: 0;
+        background: none;
+        color: var(--color-foreground-muted);
+        font: inherit;
+        text-decoration: none;
+        cursor: pointer;
+    }
+
+    .docs-page-action:hover {
+        color: var(--color-foreground-bright);
+    }
+
+    .docs-page-action-icon {
+        flex: none;
+        width: 0.875rem;
+        height: 0.875rem;
+    }
+
+    /* Under the table of contents: a column of quiet links. */
+    @media (min-width: 64rem) {
+        .docs-page-actions {
+            flex-direction: column;
+            margin-top: 0;
+        }
+
+        .docs-page-action {
+            min-height: 1.75rem;
+        }
+
+        .docs-toc ~ .docs-page-actions {
+            margin-top: 1.5rem;
+            padding-top: 1rem;
+            border-top: 1px solid var(--color-border);
+        }
+    }
+}

package/src/docs/styles/components/toc.css

@@ -0,0 +1,38 @@
+@layer components {
+    .docs-toc-title {
+        margin: 0 0 0.5rem;
+        font-family: var(--font-sans);
+        font-size: 0.75rem;
+        font-weight: 500;
+        color: var(--color-foreground-muted);
+    }
+
+    .docs-toc-list {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+    }
+
+    .docs-toc-link {
+        display: block;
+        padding: 0.1875rem 0 0.1875rem calc(0.625rem - 2px);
+        border-left: 2px solid transparent;
+        color: var(--color-foreground-muted);
+        font-size: 0.8125rem;
+        line-height: 1.5;
+        text-decoration: none;
+    }
+
+    .docs-toc-link-nested {
+        padding-left: calc(1.375rem - 2px);
+    }
+
+    .docs-toc-link:hover {
+        color: var(--color-foreground-bright);
+    }
+
+    .docs-toc-link[aria-current='location'] {
+        border-color: var(--color-foreground-bright);
+        color: var(--color-foreground-bright);
+    }
+}

package/src/docs/styles/components.css

@@ -0,0 +1,7 @@
+@import './components/docs-page.css';
+@import './components/docs-sidebar.css';
+@import './components/toc.css';
+@import './components/docs-mobile-nav.css';
+@import './components/docs-page-nav.css';
+@import './components/page-actions.css';
+@import './components/breadcrumbs.css';

package/src/docs/styles/docs.css

@@ -0,0 +1,81 @@
+/* Layered, so a page's own utilities still win. */
+@layer components {
+    .docs-frame {
+        display: contents;
+    }
+
+    /* The header's column. Wide, it holds the page between two sidebars fixed
+     to the window: only the page scrolls. */
+    .docs-container {
+        width: 100%;
+        max-width: var(--jaad-chrome-width);
+        margin-inline: auto;
+        padding-inline: 1rem;
+    }
+
+    .docs-main {
+        width: 100%;
+        min-width: 0;
+        max-width: var(--jaad-content-width);
+        margin-inline: auto;
+    }
+
+    .docs-page-main {
+        padding-top: 2rem;
+    }
+
+    [data-jaad-default-frame] .docs-container > .jaad-footer {
+        width: 100%;
+        max-width: var(--jaad-content-width);
+        margin-inline: auto;
+    }
+
+    @media (48rem <= width < 64rem) {
+        .docs-page-main {
+            padding-inline: var(--jaad-page-padding);
+        }
+    }
+
+    @media (min-width: 64rem) {
+        .docs-page-main {
+            padding-top: 2.5rem;
+        }
+
+        [data-jaad-default-frame] .docs-container {
+            display: grid;
+            grid-template-columns: var(--jaad-sidebar-width) minmax(0, 1fr) var(--jaad-sidebar-width);
+            column-gap: 3rem;
+        }
+
+        [data-jaad-default-frame] .docs-main,
+        [data-jaad-default-frame] .docs-container > .jaad-footer {
+            grid-column: 2;
+        }
+
+        [data-jaad-default-frame] .docs-sidebar-left,
+        [data-jaad-default-frame] .docs-sidebar-right {
+            position: fixed;
+            top: var(--jaad-header-height);
+            bottom: 0;
+            padding-block: 2rem;
+        }
+
+        /* Widened into the gutter, where the bar of the current page sits. */
+        [data-jaad-default-frame] .docs-sidebar-left {
+            left: max(1rem, calc(50% - var(--jaad-chrome-width) / 2 + 1rem));
+            margin-left: -0.75rem;
+            padding-left: 0.75rem;
+        }
+
+        [data-jaad-default-frame] .docs-sidebar-right {
+            right: max(1rem, calc(50% - var(--jaad-chrome-width) / 2 + 1rem));
+        }
+    }
+
+    @media (width < 64rem) {
+        [data-jaad-default-frame] .docs-sidebar-left,
+        [data-jaad-default-frame] .docs-sidebar-right .docs-toc {
+            display: none;
+        }
+    }
+}

package/src/{@types/docs.ts → docs/types.ts}

@@ -1,20 +1,15 @@
-export interface ParsedDocsCollectionId {
-    slug: string
-    orderChapter?: number
-    chapter?: string
-    order: number
-    title: string
-}
+import type { RenderedMarkdown } from './model/rendered.ts'
 
 export interface DocsNavItem {
     title: string
-    chapter: string | undefined
-    primaryOrder: number
+    /** Set when the docs are split into sections. */
+    section?: string
+    chapter?: string
     href: string
     isActive: boolean
 }
 
-export interface DocsHeadings {
+export interface DocsHeading {
     depth: 2 | 3
     slug: string
     text: string
@@ -34,14 +29,11 @@ export interface DocsPageData {
     lastUpdated?: Date
 }
 
-/** The shape jaad requires of the docs collection. Astro generates collection
- *  types in the consumer project, so the package states its own contract. */
+/** The shape jaad requires of a docs collection entry. Astro generates
+ *  collection types in the consumer project, so the package states its own contract. */
 export interface DocsEntry {
     id: string
-    /** Set when the docs are localised; the id without its locale directory. */
-    localeId?: string
-    /** Set when the docs are localised. */
-    locale?: string
     body?: string
     data: DocsPageData
+    rendered?: RenderedMarkdown
 }

package/src/{urls.ts → docs/urls.ts}

@@ -1,19 +1,5 @@
-import { localeSegment } from './locales.ts'
-
-/** Empty at the site root, otherwise one leading slash and no trailing slash. */
-export function normaliseBasePath(value: string): string {
-    const trimmed = value.replace(/^\/+/, '').replace(/\/+$/, '')
-    return trimmed ? `/${trimmed}` : ''
-}
-
-/** Apply Astro's deployment base to an application-local, root-relative href. */
-export function withDeploymentBase(href: string, deploymentBase: string): string {
-    if (!href.startsWith('/') || href.startsWith('//')) return href
-
-    const prefix = normaliseBasePath(deploymentBase)
-    if (!prefix) return href
-    return href === '/' ? `${prefix}/` : `${prefix}${href}`
-}
+import { localeSegment } from '../site/locales.ts'
+import { normaliseBasePath, withDeploymentBase } from '../site/urls.ts'
 
 export interface DocsUrlOptions {
     /** routeBase, normalised here: empty at the application root. */

package/src/env.d.ts

@@ -8,6 +8,6 @@ declare module 'virtual:jaad/config' {
 
 declare module 'virtual:jaad/docs-frame' {
     // oxlint-disable-next-line typescript/consistent-type-imports
-    const DocsFrame: typeof import('./layouts/DefaultDocsFrame.astro').default
+    const DocsFrame: typeof import('./docs/layouts/DefaultDocsFrame.astro').default
     export default DocsFrame
 }