@webstir-io/webstir 0.1.0

package/assets/features/content_nav/content_nav.ts

@@ -0,0 +1,358 @@
+export {};
+
+type DocsNavEntry = {
+    path: string;
+    title: string;
+    section?: string;
+    order?: number;
+};
+
+type NavNode = {
+    segment: string;
+    path: string;
+    title: string;
+    children: NavNode[];
+    isPage: boolean;
+    position: number;
+};
+
+type ContentNavState = {
+    navEntries?: DocsNavEntry[];
+};
+
+const STATE_KEY = '__webstirContentNavState';
+const BASE_PATH = resolveBasePath();
+const NAV_URL = withBasePath('/docs-nav.json');
+const NAV_LAYOUT_SELECTOR = '[data-content-nav="true"]';
+const APP_NAV_SELECTOR = '.app-nav';
+const APP_NAV_DOCS_SELECTOR = '[data-docs-nav-menu]';
+
+function getState(): ContentNavState {
+    const w = window as unknown as Record<string, ContentNavState | undefined>;
+    if (!w[STATE_KEY]) {
+        w[STATE_KEY] = {};
+    }
+    return w[STATE_KEY] as ContentNavState;
+}
+
+function normalizeDocsPath(pathname: string): string {
+    const normalized = stripBasePath(pathname);
+    if (!normalized.startsWith('/docs')) {
+        return normalized;
+    }
+    if (normalized === '/docs') {
+        return '/docs/';
+    }
+    return normalized.endsWith('/') ? normalized : `${normalized}/`;
+}
+
+function resolveBasePath(): string {
+    const raw = document.documentElement?.getAttribute('data-webstir-base') ?? '';
+    return normalizeBasePath(raw);
+}
+
+function normalizeBasePath(value: string): string {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === '/') {
+        return '';
+    }
+    if (!trimmed.startsWith('/')) {
+        return `/${trimmed}`;
+    }
+    return trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
+}
+
+function withBasePath(value: string): string {
+    if (!BASE_PATH) {
+        return value;
+    }
+    if (!value.startsWith('/') || value.startsWith('//')) {
+        return value;
+    }
+    if (value === BASE_PATH || value.startsWith(`${BASE_PATH}/`) || value.startsWith(`${BASE_PATH}?`) || value.startsWith(`${BASE_PATH}#`)) {
+        return value;
+    }
+    return `${BASE_PATH}${value}`;
+}
+
+function stripBasePath(value: string): string {
+    if (!BASE_PATH || !value.startsWith('/')) {
+        return value;
+    }
+    if (value === BASE_PATH) {
+        return '/';
+    }
+    if (value.startsWith(`${BASE_PATH}/`) || value.startsWith(`${BASE_PATH}?`) || value.startsWith(`${BASE_PATH}#`)) {
+        return value.slice(BASE_PATH.length);
+    }
+    return value;
+}
+
+async function fetchDocsNav(): Promise<DocsNavEntry[]> {
+    const state = getState();
+    if (state.navEntries) {
+        return state.navEntries;
+    }
+
+    try {
+        const response = await fetch(NAV_URL, { headers: { Accept: 'application/json' } });
+        if (!response.ok) {
+            state.navEntries = [];
+            return [];
+        }
+
+        const payload = await response.json();
+        if (!Array.isArray(payload)) {
+            state.navEntries = [];
+            return [];
+        }
+
+        const entries = payload
+            .filter((entry): entry is DocsNavEntry => Boolean(entry && entry.path && entry.title))
+            .map((entry) => ({
+                path: String(entry.path),
+                title: String(entry.title),
+                section: typeof entry.section === 'string' ? entry.section : undefined,
+                order: typeof entry.order === 'number' ? entry.order : undefined
+            }));
+
+        state.navEntries = entries;
+        return entries;
+    } catch {
+        state.navEntries = [];
+        return [];
+    }
+}
+
+function buildNavTree(entries: readonly DocsNavEntry[]): NavNode {
+    let position = 0;
+    const root: NavNode = {
+        segment: 'docs',
+        path: '/docs/',
+        title: 'Docs',
+        children: [],
+        isPage: false,
+        position: position++
+    };
+
+    for (const entry of entries) {
+        const normalizedPath = normalizeDocsPath(entry.path);
+        const segments = normalizedPath.split('/').filter(Boolean);
+        if (segments.length === 0) {
+            continue;
+        }
+
+        let current = root;
+        for (let index = 1; index < segments.length; index += 1) {
+            const segment = segments[index];
+            const nodePath = `/${segments.slice(0, index + 1).join('/')}/`;
+            let child = current.children.find((node) => node.segment === segment);
+            if (!child) {
+                child = {
+                    segment,
+                    path: nodePath,
+                    title: toTitleCase(segment.replace(/[-_]/g, ' ')),
+                    children: [],
+                    isPage: false,
+                    position: position++
+                };
+                current.children.push(child);
+            }
+            current = child;
+        }
+
+        current.title = entry.title;
+        current.isPage = true;
+    }
+
+    return root;
+}
+
+function renderNavList(nodes: readonly NavNode[], currentPath: string, depth = 0): HTMLOListElement {
+    const list = document.createElement('ol');
+    list.className = depth === 0 ? 'docs-nav__list' : 'docs-nav__list docs-nav__list--nested';
+
+    const sorted = [...nodes].sort((a, b) => a.position - b.position);
+    for (const node of sorted) {
+        const item = document.createElement('li');
+        item.className = 'docs-nav__item';
+
+        const isActive = node.path === currentPath;
+        const isBranch = !isActive && currentPath.startsWith(node.path);
+        if (isActive) {
+            item.dataset.active = 'true';
+        } else if (isBranch) {
+            item.dataset.activeBranch = 'true';
+        }
+
+        if (node.isPage) {
+            const link = document.createElement('a');
+            link.className = 'docs-nav__link';
+            link.href = withBasePath(node.path);
+            link.textContent = node.title;
+            if (isActive) {
+                link.setAttribute('aria-current', 'page');
+            }
+            item.appendChild(link);
+        } else {
+            const label = document.createElement('span');
+            label.className = 'docs-nav__label';
+            label.textContent = node.title;
+            item.appendChild(label);
+        }
+
+        if (node.children.length > 0) {
+            item.appendChild(renderNavList(node.children, currentPath, depth + 1));
+        }
+
+        list.appendChild(item);
+    }
+
+    return list;
+}
+
+function clearAppMenuDocsNav(): void {
+    const appNav = document.querySelector<HTMLElement>(APP_NAV_SELECTOR);
+    const existing = appNav?.querySelector<HTMLElement>(APP_NAV_DOCS_SELECTOR);
+    existing?.remove();
+}
+
+function renderAppMenuDocsNav(tree: NavNode, currentPath: string): void {
+    const appNav = document.querySelector<HTMLElement>(APP_NAV_SELECTOR);
+    if (!appNav) {
+        return;
+    }
+
+    const section = document.createElement('div');
+    section.className = 'app-nav__docs';
+    section.dataset.docsNavMenu = 'true';
+
+    const topNodes = tree.children;
+    const nodes =
+        topNodes.length === 1 && !topNodes[0].isPage && topNodes[0].children.length > 0
+            ? topNodes[0].children
+            : topNodes;
+
+    const list = renderNavList(nodes, currentPath);
+    section.appendChild(list);
+
+    const docsHref = withBasePath('/docs/');
+    const docsHrefNoSlash = docsHref.endsWith('/') ? docsHref.slice(0, -1) : docsHref;
+    const docsLink = appNav.querySelector<HTMLAnchorElement>(`a[href="${docsHref}"], a[href="${docsHrefNoSlash}"]`);
+    if (docsLink) {
+        docsLink.insertAdjacentElement('afterend', section);
+    } else {
+        appNav.appendChild(section);
+    }
+}
+
+function renderBreadcrumb(
+    root: HTMLElement,
+    titleByPath: ReadonlyMap<string, string>,
+    currentPath: string
+): boolean {
+    if (!currentPath.startsWith('/docs/')) {
+        root.setAttribute('aria-hidden', 'true');
+        root.dataset.breadcrumbVisible = 'false';
+        root.innerHTML = '';
+        return false;
+    }
+
+    const list = document.createElement('ol');
+    list.className = 'docs-breadcrumb__list';
+
+    const segments = currentPath.replace(/^\/docs\/?/, '').split('/').filter(Boolean);
+    const crumbs: Array<{ title: string; href: string }> = [];
+
+    const rootTitle = titleByPath.get('/docs/') ?? 'Docs';
+    crumbs.push({ title: rootTitle, href: '/docs/' });
+
+    let current = '/docs/';
+    for (const segment of segments) {
+        current = `${current}${segment}/`;
+        const title = titleByPath.get(current) ?? toTitleCase(segment.replace(/[-_]/g, ' '));
+        crumbs.push({ title, href: current });
+    }
+
+    for (let index = 0; index < crumbs.length; index += 1) {
+        const crumb = crumbs[index];
+        const item = document.createElement('li');
+        item.className = 'docs-breadcrumb__item';
+
+        if (index === crumbs.length - 1) {
+            const label = document.createElement('span');
+            label.textContent = crumb.title;
+            label.setAttribute('aria-current', 'page');
+            item.appendChild(label);
+        } else {
+            const link = document.createElement('a');
+            link.className = 'docs-breadcrumb__link';
+            link.href = withBasePath(crumb.href);
+            link.textContent = crumb.title;
+            item.appendChild(link);
+        }
+
+        list.appendChild(item);
+    }
+
+    root.innerHTML = '';
+    root.appendChild(list);
+    root.removeAttribute('aria-hidden');
+    root.dataset.breadcrumbVisible = 'true';
+    return true;
+}
+
+function toTitleCase(value: string): string {
+    return value
+        .split(/\s+/)
+        .filter((part) => part.length > 0)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+
+async function initContentNav(): Promise<void> {
+    const layouts = Array.from(document.querySelectorAll<HTMLElement>(NAV_LAYOUT_SELECTOR));
+    clearAppMenuDocsNav();
+    if (layouts.length === 0) {
+        return;
+    }
+
+    const navEntries = await fetchDocsNav();
+    const titleByPath = new Map<string, string>(
+        navEntries.map((entry) => [normalizeDocsPath(entry.path), entry.title])
+    );
+
+    const tree = buildNavTree(navEntries);
+    const currentPath = normalizeDocsPath(window.location.pathname);
+    if (navEntries.length > 0) {
+        renderAppMenuDocsNav(tree, currentPath);
+    }
+
+    for (const layout of layouts) {
+        const sidebar = layout.querySelector<HTMLElement>('[data-docs-sidebar]');
+        const navRoot = layout.querySelector<HTMLElement>('[data-docs-nav]');
+        const breadcrumb = layout.querySelector<HTMLElement>('[data-docs-breadcrumb]');
+        let hasNav = false;
+        if (navRoot && sidebar && navEntries.length > 0) {
+            const list = renderNavList(tree.children, currentPath);
+            navRoot.innerHTML = '';
+            navRoot.appendChild(list);
+            hasNav = true;
+        }
+
+        if (breadcrumb) {
+            renderBreadcrumb(breadcrumb, titleByPath, currentPath);
+        }
+
+        if (hasNav) {
+            layout.dataset.contentNavReady = 'true';
+        } else {
+            layout.dataset.contentNavReady = 'false';
+        }
+    }
+}
+
+void initContentNav();
+window.addEventListener('webstir:client-nav', () => {
+    void initContentNav();
+});

package/assets/features/router/router-types.ts

@@ -0,0 +1,6 @@
+export type RouteParams = Record<string, string | undefined>;
+
+export type RouteHandler = {
+    onEnter?: (params: RouteParams) => void | Promise<void>;
+    onLeave?: () => void | Promise<void>;
+};

package/assets/features/router/router.ts

@@ -0,0 +1,118 @@
+import type { RouteHandler, RouteParams } from './router-types.js';
+
+export class Router {
+    private routes = new Map<string, RouteHandler>();
+    private currentHandler: RouteHandler | null = null;
+
+    public constructor() {
+        this.setupBrowserNavigation();
+        this.interceptLinkClicks();
+    }
+
+    public registerRoute(path: string, handler: RouteHandler): void {
+        this.routes.set(path, handler);
+    }
+
+    public async navigate(url: string): Promise<void> {
+        const targetPath = new URL(url, window.location.origin).pathname;
+        const routeHandler = this.routes.get(targetPath);
+
+        if (!routeHandler) {
+            window.location.href = url;
+            return;
+        }
+
+        window.history.pushState({}, '', url);
+        await this.handleRouteChange();
+    }
+
+    private setupBrowserNavigation(): void {
+        window.addEventListener('popstate', () => {
+            this.handleRouteChange();
+        });
+    }
+
+    private interceptLinkClicks(): void {
+        document.addEventListener('click', (event) => {
+            const target = event.target as EventTarget | null;
+            if (!(target instanceof Element)) {
+                return;
+            }
+            if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+                return;
+            }
+
+            const clickedLink = target.closest('a');
+            if (!clickedLink || !this.shouldInterceptLink(clickedLink as HTMLAnchorElement)) {
+                return;
+            }
+
+            event.preventDefault();
+            this.navigate((clickedLink as HTMLAnchorElement).href);
+        });
+    }
+
+    private async handleRouteChange(): Promise<void> {
+        const currentPath = window.location.pathname;
+        const routeParams = this.extractQueryParams();
+
+        await this.callOnLeaveHandler();
+
+        const newHandler = this.routes.get(currentPath);
+        if (newHandler) {
+            this.currentHandler = newHandler;
+            await this.callOnEnterHandler(newHandler, routeParams);
+        }
+    }
+
+    private async callOnLeaveHandler(): Promise<void> {
+        if (this.currentHandler?.onLeave) {
+            await this.currentHandler.onLeave();
+        }
+    }
+
+    private async callOnEnterHandler(handler: RouteHandler, params: RouteParams): Promise<void> {
+        if (handler.onEnter) {
+            await handler.onEnter(params);
+        }
+    }
+
+    private shouldInterceptLink(link: HTMLAnchorElement): boolean {
+        const isExternalLink = link.origin !== window.location.origin;
+        const isDownloadLink = link.hasAttribute('download');
+        const opensInNewTab = link.getAttribute('target') === '_blank';
+        const hasRouteHandler = this.routes.has(link.pathname);
+
+        return !isExternalLink && !isDownloadLink && !opensInNewTab && hasRouteHandler;
+    }
+
+    private extractQueryParams(): RouteParams {
+        const params: RouteParams = {};
+        const urlSearchParams = new URLSearchParams(window.location.search);
+
+        urlSearchParams.forEach((value, key) => {
+            params[key] = value;
+        });
+
+        return params;
+    }
+}
+
+let singleton: Router | null = null;
+
+export function startRouter(): Router {
+    if (!singleton) {
+        singleton = new Router();
+    }
+    return singleton;
+}
+
+export function getRouter(): Router | null {
+    return singleton;
+}
+
+export function navigate(url: string): Promise<void> {
+    return startRouter().navigate(url);
+}
+
+export type { RouteHandler, RouteParams };

package/assets/features/search/search.css

@@ -0,0 +1,204 @@
+@layer features {
+  #webstir-search {
+    position: fixed;
+    inset-inline: 0;
+    bottom: 0;
+    top: var(--ws-drawer-top, 0px);
+    z-index: 9999;
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  #webstir-search[data-open="true"] {
+    opacity: 1;
+    pointer-events: auto;
+  }
+
+  #webstir-search[data-open="true"] .ws-drawer-backdrop {
+    opacity: 1;
+    pointer-events: auto;
+  }
+
+  body.webstir-search-open {
+    overflow: hidden;
+  }
+
+  .webstir-search__trigger-icon {
+    display: inline-flex;
+    opacity: 0.9;
+    pointer-events: none;
+  }
+
+  .webstir-search__trigger-icon * {
+    pointer-events: none;
+  }
+
+  .webstir-search__drawer {
+    position: relative;
+    background: var(--ws-bg);
+    border-bottom: 1px solid var(--ws-border);
+    box-shadow: 0 1.5rem 3rem -1.5rem rgba(0, 0, 0, 0.28);
+    z-index: 20;
+  }
+
+  .webstir-search__drawer-inner {
+    padding-block: 1.25rem 1.5rem;
+  }
+
+  .webstir-search__field {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding-block: 0.25rem;
+  }
+
+  .webstir-search__icon {
+    display: inline-flex;
+    opacity: 0.7;
+  }
+
+  .webstir-search__input {
+    flex: 1;
+    min-width: 0;
+    border: 0;
+    background: transparent;
+    color: inherit;
+    outline: none;
+    font-size: 1.75rem;
+    font-weight: 600;
+    padding: 0.25rem 0;
+  }
+
+  .webstir-search__input::placeholder {
+    color: var(--ws-muted);
+    opacity: 1;
+  }
+
+  .webstir-search__close {
+    padding: 0.375rem 0.625rem;
+    border-radius: 999px;
+    border: 1px solid var(--ws-border);
+    background: transparent;
+    color: var(--ws-muted);
+    font-size: 0.75rem;
+    font-weight: 600;
+    cursor: pointer;
+  }
+
+  .webstir-search__close:hover {
+    background: rgba(17, 24, 39, 0.04);
+  }
+
+  [data-theme="dark"] .webstir-search__close:hover {
+    background: rgba(255, 255, 255, 0.06);
+  }
+
+  .webstir-search__scopes {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    margin-top: 0.75rem;
+  }
+
+  .webstir-search__scopes[hidden] {
+    display: none;
+  }
+
+  .webstir-search__scopes button {
+    padding: 0.375rem 0.625rem;
+    border-radius: 999px;
+    border: 1px solid var(--ws-border);
+    background: transparent;
+    color: inherit;
+    cursor: pointer;
+    font-weight: 600;
+    font-size: 0.875rem;
+  }
+
+  .webstir-search__scopes button[aria-pressed="true"] {
+    background: rgba(37, 99, 235, 0.12);
+    border-color: rgba(37, 99, 235, 0.35);
+  }
+
+  .webstir-search__body {
+    margin-top: 1.25rem;
+    max-height: min(60vh, 36rem);
+    overflow: auto;
+    padding-bottom: 0.5rem;
+  }
+
+  .webstir-search__hint {
+    color: var(--ws-muted);
+  }
+
+  .webstir-search__label {
+    margin-top: 0.5rem;
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: var(--ws-muted);
+  }
+
+  .webstir-search__quicklinks[hidden],
+  .webstir-search__matches[hidden] {
+    display: none;
+  }
+
+  .webstir-search__quicklinks-list,
+  .webstir-search__results-list {
+    margin: 0.5rem 0 0;
+  }
+
+  .webstir-search__quicklinks-list a:focus-visible,
+  .webstir-search__results-list a:focus-visible {
+    outline: 0.1875rem solid var(--ws-focus);
+    outline-offset: 0.125rem;
+  }
+
+  .webstir-search__results-list strong {
+    display: block;
+    font-weight: 600;
+    margin-bottom: 0.25rem;
+  }
+
+  .webstir-search__results-list span {
+    display: block;
+    color: var(--ws-muted);
+    line-height: 1.35;
+  }
+
+  .webstir-search__arrow {
+    opacity: 0.7;
+  }
+
+  .webstir-search__group {
+    margin-top: 0.75rem;
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: var(--ws-muted);
+  }
+
+  .webstir-search__empty {
+    padding: 0.5rem 0;
+    color: var(--ws-muted);
+  }
+
+  @media (--ws-sm) {
+    .webstir-search__trigger {
+      order: -1;
+    }
+
+    .webstir-search__drawer-inner {
+      padding-block: 1rem 1.25rem;
+    }
+
+    .webstir-search__input {
+      font-size: 1.375rem;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    #webstir-search {
+      transition: none;
+    }
+  }
+}