@jaamd/jaad 0.11.0 → 1.0.0

package/src/{docs-config.ts → site/runtime.ts}

@@ -1,23 +1,12 @@
 import type { Locale } from './locales.ts'
-import type { DocsUrlOptions } from './urls.ts'
 import config from 'virtual:jaad/config'
 import * as locales from './locales.ts'
 import { uiString, type UiKey } from './ui.ts'
 
 /** The virtual config, read once. */
-export const LOCALES: Locale[] = config.docsLocales
+export const LOCALES: Locale[] = config.locales
 export const DEFAULT_LOCALE: string = config.defaultLocale
 
-/** The four fields every href builder takes, in one place. */
-export function docsUrls(locale?: string): DocsUrlOptions {
-    return {
-        docsBase: config.docsBase,
-        deploymentBase: import.meta.env.BASE_URL,
-        locale,
-        defaultLocale: DEFAULT_LOCALE,
-    }
-}
-
 export const localePrefix = (locale?: string) => locales.localePrefix(locale, DEFAULT_LOCALE)
 
 export const buildLocales = () => locales.routedLocales(LOCALES)

package/src/site/search.ts

@@ -0,0 +1,227 @@
+/** The search index of one locale, as `search-index.json` serves it. */
+export interface SearchIndex {
+    /** Empty when the docs are not split into sections. */
+    sections: { key: string; label: string }[]
+    pages: SearchPage[]
+    entries: SearchEntry[]
+}
+
+export interface SearchPage {
+    title: string
+    href: string
+    section?: string
+    /** Display title of the chapter. */
+    chapter?: string
+    keywords?: string[]
+}
+
+/** The text under one heading, or before the first one. */
+export interface SearchEntry {
+    /** Position in `pages`. */
+    page: number
+    heading?: string
+    anchor?: string
+    text: string
+}
+
+export interface SearchHit {
+    entry: SearchEntry
+    href: string
+    score: number
+}
+
+/** A page and the headings inside it that matched. */
+export interface SearchGroup {
+    page: SearchPage
+    score: number
+    /** Set when the text before the first heading matched. */
+    intro?: SearchEntry
+    hits: SearchHit[]
+}
+
+const MAX_GROUPS = 8
+const MAX_HITS = 3
+const PAGES_PER_SECTION = 4
+
+/** Page fields count fully on the text before the first heading, and as
+ *  context everywhere else. */
+const WEIGHTS = {
+    title: { intro: 8, heading: 2 },
+    keywords: { intro: 4, heading: 1 },
+    chapter: { intro: 2, heading: 1 },
+    heading: 6,
+    text: 1,
+}
+
+const WORD = /[\p{L}\p{M}\p{N}]+/gu
+
+/** Lowercase, without accents. */
+export function fold(text: string): string {
+    return text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase()
+}
+
+/** The words of a query, folded. */
+export function queryTerms(query: string): string[] {
+    return fold(query).match(WORD) ?? []
+}
+
+const words = (text: string | undefined) => (text ? (fold(text).match(WORD) ?? []) : [])
+
+interface Prepared {
+    title: string[]
+    keywords: string[]
+    chapter: string[]
+    heading: string[]
+    text: string[]
+}
+
+/** The folded words of each entry, computed on first use. */
+const prepared = new WeakMap<SearchEntry, Prepared>()
+
+function prepare(entry: SearchEntry, page: SearchPage): Prepared {
+    let found = prepared.get(entry)
+    if (!found) {
+        found = {
+            title: words(page.title),
+            keywords: words(page.keywords?.join(' ')),
+            chapter: words(page.chapter),
+            heading: words(entry.heading),
+            text: words(entry.text),
+        }
+        prepared.set(entry, found)
+    }
+    return found
+}
+
+/** 2 for a whole word, 1 for a word it starts, 0 for none. */
+function match(fieldWords: string[], term: string): number {
+    let best = 0
+    for (const word of fieldWords) {
+        if (word === term) return 2
+        if (best === 0 && word.startsWith(term)) best = 1
+    }
+    return best
+}
+
+/** The score of an entry, null unless every term is in it or in its page.
+ *  `own` tells whether the heading or its text matched, not just the page. */
+function scoreEntry(fields: Prepared, terms: string[], intro: boolean): { score: number; own: boolean } | null {
+    const place = intro ? 'intro' : 'heading'
+    let score = 0
+    let own = false
+
+    for (const term of terms) {
+        const candidates: [number, number, boolean][] = [
+            [match(fields.title, term), WEIGHTS.title[place], false],
+            [match(fields.keywords, term), WEIGHTS.keywords[place], false],
+            [match(fields.chapter, term), WEIGHTS.chapter[place], false],
+            [match(fields.heading, term), WEIGHTS.heading, true],
+            [match(fields.text, term), WEIGHTS.text, true],
+        ]
+        let best = 0
+        for (const [quality, weight, isOwn] of candidates) {
+            if (quality === 0) continue
+            best = Math.max(best, quality * weight)
+            if (isOwn) own = true
+        }
+        if (best === 0) return null
+        score += best
+    }
+
+    return { score, own }
+}
+
+const entryHref = (page: SearchPage, entry: SearchEntry) => (entry.anchor ? `${page.href}#${entry.anchor}` : page.href)
+
+/** Pages ranked by their best entry, each with the headings that matched.
+ *  Every word must appear; a word also matches the words it starts. */
+export function search(index: SearchIndex, query: string, section?: string): SearchGroup[] {
+    const terms = queryTerms(query)
+    if (terms.length === 0) return []
+
+    const groups = new Map<number, SearchGroup>()
+    for (const entry of index.entries) {
+        const page = index.pages[entry.page]
+        if (section && page.section !== section) continue
+
+        const intro = entry.heading === undefined
+        const scored = scoreEntry(prepare(entry, page), terms, intro)
+        if (!scored) continue
+
+        let group = groups.get(entry.page)
+        if (!group) {
+            group = { page, score: 0, hits: [] }
+            groups.set(entry.page, group)
+        }
+        group.score = Math.max(group.score, scored.score)
+        if (!scored.own) continue
+        if (intro) group.intro = entry
+        else group.hits.push({ entry, href: entryHref(page, entry), score: scored.score })
+    }
+
+    return [...groups.values()]
+        .toSorted((a, b) => b.score - a.score)
+        .slice(0, MAX_GROUPS)
+        .map((group) => ({ ...group, hits: group.hits.toSorted((a, b) => b.score - a.score).slice(0, MAX_HITS) }))
+}
+
+/** What an empty query shows: the pages outside the sections, then the first
+ *  pages of each section; without sections, the first pages of the docs. */
+export function openingPages(index: SearchIndex, section?: string): { label?: string; pages: SearchPage[] }[] {
+    if (index.sections.length === 0) return [{ pages: index.pages.slice(0, MAX_GROUPS) }]
+
+    const loose = section ? [] : index.pages.filter((page) => !page.section).slice(0, PAGES_PER_SECTION)
+    return [
+        { pages: loose },
+        ...index.sections
+            .filter(({ key }) => !section || key === section)
+            .map(({ key, label }) => ({
+                label,
+                pages: index.pages.filter((page) => page.section === key).slice(0, PAGES_PER_SECTION),
+            })),
+    ].filter((group) => group.pages.length > 0)
+}
+
+/** The text around the first matching word, or its start when none matches,
+ *  ellipsised where cut. */
+export function getSnippet(text: string, terms: string[], before = 40, after = 100): string {
+    const parts = markWords(text, terms)
+    const first = parts.findIndex((part) => part.match)
+    const start = parts.slice(0, Math.max(first, 0)).reduce((length, part) => length + part.text.length, 0)
+    const from = Math.max(0, start - before)
+    const to = Math.min(text.length, start + after)
+    return (from > 0 ? '…' : '') + text.slice(from, to).trim() + (to < text.length ? '…' : '')
+}
+
+/** How many characters of `word` fold into the first `length` folded ones,
+ *  accents on the last of them included. */
+function foldedPrefix(word: string, length: number): number {
+    let folded = 0
+    let at = 0
+    for (const char of word) {
+        const size = fold(char).length
+        if (folded >= length && size > 0) break
+        folded += size
+        at += char.length
+    }
+    return at
+}
+
+/** Splits text around the words the terms start, marking the matched starts.
+ *  Case and accents are ignored. */
+export function markWords(text: string, terms: string[]): { text: string; match: boolean }[] {
+    const parts: { text: string; match: boolean }[] = []
+    let last = 0
+    for (const word of text.matchAll(WORD)) {
+        const folded = fold(word[0])
+        const term = terms.find((candidate) => folded.startsWith(candidate))
+        if (!term) continue
+
+        const end = word.index + foldedPrefix(word[0], term.length)
+        if (word.index > last) parts.push({ text: text.slice(last, word.index), match: false })
+        parts.push({ text: text.slice(word.index, end), match: true })
+        last = end
+    }
+    if (last < text.length) parts.push({ text: text.slice(last), match: false })
+    return parts
+}

package/src/{social.ts → site/social.ts}

@@ -1,4 +1,4 @@
-import type { JaadResolvedConfig } from './config.ts'
+import type { SiteResolvedConfig } from './config.ts'
 import { FORGES, forgeForUrl } from './forges.ts'
 
 export interface SocialLink {
@@ -11,7 +11,7 @@ export interface SocialLink {
 }
 
 /** The configured links, plus the inferred repository unless already listed. */
-export function buildSocialLinks(config: JaadResolvedConfig): SocialLink[] {
+export function buildSocialLinks(config: SiteResolvedConfig): SocialLink[] {
     const links: SocialLink[] = []
 
     for (const [key, value] of Object.entries(config.social)) {

package/src/site/styles/components/header.css

@@ -0,0 +1,31 @@
+@layer components {
+    /* Fixed to the top of the window: only the page scrolls below it. */
+    .jaad-header {
+        position: fixed;
+        inset: 0 0 auto;
+        z-index: 40;
+        height: var(--jaad-header-height);
+        background: var(--color-background);
+    }
+    .jaad-header-inner {
+        height: 100%;
+        max-width: var(--jaad-chrome-width);
+        margin-inline: auto;
+        padding-inline: 1rem;
+    }
+    .jaad-header-row {
+        @apply flex h-full 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 → site/styles}/components/search.css

@@ -48,8 +48,24 @@
         @apply bg-background-secondary text-foreground-muted shrink-0 cursor-pointer rounded px-1.5 py-0.5 text-xs;
     }
 
+    .jaad-search-filters {
+        @apply border-border flex flex-wrap gap-1.5 border-b px-4 py-2;
+    }
+
+    .jaad-search-filter {
+        @apply border-border text-foreground-muted hover:text-foreground cursor-pointer rounded-full border px-2.5 py-0.5 text-xs transition-colors;
+    }
+
+    .jaad-search-filter[aria-pressed='true'] {
+        @apply border-primary/40 bg-primary/10 text-foreground-bright;
+    }
+
     .jaad-search-results {
-        @apply max-h-80 overflow-y-auto p-2;
+        @apply max-h-96 overflow-y-auto p-2;
+    }
+
+    .jaad-search-group {
+        @apply text-foreground-muted px-3 pt-3 pb-1 text-xs font-semibold tracking-wide uppercase;
     }
 
     .jaad-search-footer {
@@ -72,6 +88,10 @@
         @apply bg-primary/10 text-foreground-bright;
     }
 
+    .jaad-search-result-heading {
+        @apply border-border ml-3 rounded-l-none border-l py-2;
+    }
+
     .jaad-search-result-head {
         @apply flex items-center gap-2;
     }

package/src/{styles → site/styles}/components/shell.css

@@ -28,6 +28,10 @@
         @apply bg-background text-foreground flex min-h-screen flex-col text-[14px] leading-[1.6];
     }
 
+    .jaad-body {
+        padding-top: var(--jaad-header-height);
+    }
+
     .jaad-icon {
         @apply h-5 w-5;
     }

package/src/site/styles/components.css

@@ -0,0 +1,10 @@
+@import './components/shell.css';
+@import './components/header.css';
+@import './components/footer.css';
+@import './components/nav.css';
+@import './components/nav-mobile.css';
+@import './components/social-links.css';
+@import './components/theme-switcher.css';
+@import './components/locale-switcher.css';
+@import './components/not-found.css';
+@import './components/search.css';

package/src/{styles → site/styles}/global.css

@@ -1,23 +1,3 @@
-@import 'tailwindcss' source(none);
-@import './components/shell.css';
-@import './components/header.css';
-@import './components/footer.css';
-@import './components/nav.css';
-@import './components/nav-mobile.css';
-@import './components/social-links.css';
-@import './components/theme-switcher.css';
-@import './components/locale-switcher.css';
-@import './components/scroll-to-top.css';
-@import './components/not-found.css';
-@import './components/search.css';
-@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';
-
 @theme static {
     /* Seeds */
 
@@ -55,18 +35,16 @@
 
     /* Layout */
     --jaad-content-width: 56rem;
-    --jaad-chrome-width: var(--jaad-content-width);
+    /* Sidebar, page and table of contents, with their gaps and the gutters. */
+    --jaad-chrome-width: calc(var(--jaad-content-width) + 2 * var(--jaad-sidebar-width) + 6rem);
     --jaad-sidebar-width: 16rem;
+    --jaad-header-height: 4.25rem;
     --jaad-page-padding: 2rem;
-
-    /* Where a sidebar sits beside centred content. Derived, so moving the
-     content width moves the sidebars with it. */
-    --jaad-sidebar-offset: calc(50% - (var(--jaad-content-width) / 2) - var(--jaad-sidebar-width) - 2rem);
 }
 
 @layer base {
     html {
-        scroll-padding-top: 8rem;
+        scroll-padding-top: calc(var(--jaad-header-height) + 1.5rem);
         background-color: var(--color-background);
         color: var(--color-foreground);
         font-family: var(--font-sans);

package/src/{themes/index.ts → site/themes.ts}

@@ -1,4 +1,4 @@
-import { themes } from '@jaamd/jaamd/themes'
+import { themes } from '@jaamd/astro/themes'
 
 export interface Preset {
     /** Shiki theme, or a light/dark pair, for code blocks. */

package/src/{ui → site/ui}/en.ts

@@ -1,19 +1,16 @@
 /** The canonical UI catalogue: its keys define every catalogue JAAD accepts. */
 export const ENGLISH_UI = {
     'breadcrumb.label': 'Breadcrumb',
-    'breadcrumb.root': 'Docs',
     home: 'Home',
     'locale.change': 'Change language',
     'nav.documentation': 'Documentation navigation',
-    'nav.jumpToSection': 'Jump to section...',
     'nav.mobile': 'Toggle mobile menu',
     'nav.page': 'Page navigation',
-    'nav.selectPage': 'Select page',
     'page.copied': 'Copied!',
     'page.copy': 'Copy page',
     'page.edit': 'Edit this page',
     'page.lastUpdated': 'Last updated on',
-    scrollTop: 'Scroll to top',
+    'search.all': 'All',
     'search.close': 'close',
     'search.empty': 'No results for',
     'search.label': 'Search documentation',
@@ -22,8 +19,9 @@ export const ENGLISH_UI = {
     'search.open': 'open',
     'search.placeholder': 'Search documentation...',
     'search.results': 'Search results',
+    'search.sections': 'Search in',
     'search.trigger': 'Search docs...',
     'theme.toggle': 'Toggle color theme',
     'toc.label': 'Table of contents',
-    'toc.title': 'On This Page',
+    'toc.title': 'On this page',
 } as const

package/src/{ui → site/ui}/it.ts

@@ -2,19 +2,16 @@ import type { UiCatalog } from '../ui.ts'
 
 export const ITALIAN_UI = {
     'breadcrumb.label': 'Percorso di navigazione',
-    'breadcrumb.root': 'Documentazione',
     home: 'Pagina iniziale',
     'locale.change': 'Cambia lingua',
     'nav.documentation': 'Navigazione della documentazione',
-    'nav.jumpToSection': 'Vai alla sezione…',
     'nav.mobile': 'Apri o chiudi il menu',
     'nav.page': 'Navigazione tra le pagine',
-    'nav.selectPage': 'Seleziona una pagina',
     'page.copied': 'Copiata!',
     'page.copy': 'Copia',
     'page.edit': 'Modifica',
     'page.lastUpdated': 'Ultimo aggiornamento il',
-    scrollTop: 'Torna in cima',
+    'search.all': 'Tutte',
     'search.close': 'chiudi',
     'search.empty': 'Nessun risultato per',
     'search.label': 'Cerca nella documentazione',
@@ -23,6 +20,7 @@ export const ITALIAN_UI = {
     'search.open': 'apri',
     'search.placeholder': 'Cerca nella documentazione…',
     'search.results': 'Risultati della ricerca',
+    'search.sections': 'Cerca in',
     'search.trigger': 'Cerca…',
     'theme.toggle': 'Cambia modalità',
     'toc.label': 'Indice dei contenuti',

package/src/site/urls.ts

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

package/src/{virtual.ts → site/virtual.ts}

@@ -1,5 +1,3 @@
-import type { JaadResolvedConfig } from './config.ts'
-
 const MODULE_ID = 'virtual:jaad/config'
 const RESOLVED_ID = '\0' + MODULE_ID
 
@@ -15,33 +13,29 @@ const BRIDGE_CSS_ID = 'virtual:jaad/bridge.css'
 const TAILWIND_CSS_ID = 'virtual:jaad/tailwind.css'
 const RESOLVED_TAILWIND_CSS = '\0' + TAILWIND_CSS_ID
 
-const DOCS_FRAME_ID = 'virtual:jaad/docs-frame'
-const RESOLVED_DOCS_FRAME = '\0' + DOCS_FRAME_ID
+export interface SiteStylesheets {
+    user: string | null
+    theme: string | null
+    bridge: string
+    tailwind: string | null
+}
 
-export function jaadVirtualPlugin(
-    config: JaadResolvedConfig,
-    userCss: string | null,
-    themeCss: string | null,
-    bridgeCss: string,
-    tailwindCss: string | null,
-    docsFrame: () => string,
-) {
+/** The resolved config, serialised, and the stylesheets the site may or may not have. */
+export function siteVirtualPlugin(config: object, stylesheets: SiteStylesheets) {
     return {
         name: 'jaad:virtual',
         resolveId(source: string) {
             if (source === MODULE_ID) return RESOLVED_ID
             // Redirecting to the real path lets Vite process it as ordinary CSS.
-            if (source === USER_CSS_ID) return userCss ?? RESOLVED_USER_CSS
-            if (source === THEME_CSS_ID) return themeCss ?? RESOLVED_THEME_CSS
-            if (source === BRIDGE_CSS_ID) return bridgeCss
-            if (source === TAILWIND_CSS_ID) return tailwindCss ?? RESOLVED_TAILWIND_CSS
-            if (source === DOCS_FRAME_ID) return RESOLVED_DOCS_FRAME
+            if (source === USER_CSS_ID) return stylesheets.user ?? RESOLVED_USER_CSS
+            if (source === THEME_CSS_ID) return stylesheets.theme ?? RESOLVED_THEME_CSS
+            if (source === BRIDGE_CSS_ID) return stylesheets.bridge
+            if (source === TAILWIND_CSS_ID) return stylesheets.tailwind ?? RESOLVED_TAILWIND_CSS
             return null
         },
         load(id: string) {
             if (id === RESOLVED_ID) return `export default ${JSON.stringify(config)};`
             if (id === RESOLVED_USER_CSS || id === RESOLVED_THEME_CSS || id === RESOLVED_TAILWIND_CSS) return ''
-            if (id === RESOLVED_DOCS_FRAME) return `export { default } from ${JSON.stringify(docsFrame())};`
             return null
         },
     }

package/src/styles.css

@@ -0,0 +1,5 @@
+/* The package stylesheet: Tailwind, the site's components, the docs', then the tokens. */
+@import 'tailwindcss' source(none);
+@import './site/styles/components.css';
+@import './docs/styles/components.css';
+@import './site/styles/global.css';

package/src/collection.ts

@@ -1,97 +0,0 @@
-import type { DocsEntry } from './@types/docs.ts'
-import type { Locale } from './locales.ts'
-import { getCollection } from 'astro:content'
-import { DEFAULT_LOCALE, LOCALES, docsUrls, prefixedCodes } from './docs-config.ts'
-import { docsPageHref } from './urls.ts'
-import {
-    docTranslationKey,
-    getCleanSlug,
-    routedId,
-    sortDocPages,
-    splitDocLocale,
-    validateDocsStructure,
-} from './utils/docs.ts'
-
-const cached = new Map<string, DocsEntry[]>()
-// Keyed on the array: the same object in production, a fresh one in dev.
-const keyIndex = new WeakMap<DocsEntry[], Map<string, number>>()
-
-function indexOfKey(pages: DocsEntry[], key: string): number {
-    let index = keyIndex.get(pages)
-    if (!index) {
-        index = new Map(pages.map((page, at) => [docTranslationKey(page), at]))
-        keyIndex.set(pages, index)
-    }
-    return index.get(key) ?? -1
-}
-
-const CODES = LOCALES.map((locale) => locale.code)
-
-/** Attaches the locale and the id routing reads, leaving `id` the real
- *  collection id: the edit link points at the file on disk. */
-function localise(page: DocsEntry): DocsEntry {
-    if (CODES.length === 0) return page
-    const split = splitDocLocale(page.id, CODES)
-    return { ...page, locale: split.locale ?? undefined, localeId: split.id }
-}
-
-/** The pages of one locale, or every page when the docs are not localised.
- *  Cached in production only: in dev the module would go stale on edit. */
-export async function getSortedDocsPages(locale: string = DEFAULT_LOCALE): Promise<DocsEntry[]> {
-    const key = CODES.length > 0 ? locale : ''
-    const hit = cached.get(key)
-    if (import.meta.env.PROD && hit) return hit
-
-    const pages = ((await getCollection('docsPages')) as unknown as DocsEntry[])
-        .map(localise)
-        .filter((page) => key === '' || page.locale === key)
-
-    // Validated before drafts are dropped, so a draft's slug conflict is an error.
-    validateDocsStructure(pages, key || undefined)
-    const sorted = sortDocPages(import.meta.env.PROD ? pages.filter((page) => !page.data.draft) : pages)
-    if (import.meta.env.PROD) cached.set(key, sorted)
-    return sorted
-}
-
-export interface LocaleAlternate {
-    locale: Locale
-    href: string
-    /** False when this locale has no such page and the href is its opening one. */
-    translated: boolean
-}
-
-/** Where a page lives in every locale, paired by `translationKey` or by slug.
- *  An untranslated page falls back to that locale's opening page. Empty asks
- *  for the opening pages themselves. */
-export async function getLocaleAlternates(key: string): Promise<LocaleAlternate[]> {
-    const alternates: LocaleAlternate[] = []
-
-    for (const locale of LOCALES) {
-        const pages = await getSortedDocsPages(locale.code)
-        // Every page drafted leaves a locale with nothing to link to.
-        if (pages.length === 0) continue
-
-        const index = key ? indexOfKey(pages, key) : 0
-        const match = index >= 0 ? pages[index] : undefined
-
-        alternates.push({
-            locale,
-            translated: Boolean(match),
-            href: docsPageHref(match && index > 0 ? getCleanSlug(routedId(match)) : '', docsUrls(locale.code)),
-        })
-    }
-
-    return alternates
-}
-
-/** The prefixed locales that have something to serve. */
-export async function getServedLocales(): Promise<string[]> {
-    const served: string[] = []
-
-    for (const code of prefixedCodes()) {
-        const pages = await getSortedDocsPages(code)
-        if (pages.length > 0) served.push(code)
-    }
-
-    return served
-}