@acta-dev/web 1.0.0

package/src/components/ui/Tooltip.astro

@@ -0,0 +1,94 @@
+---
+interface Props {
+  label: string;
+  text: string;
+  id?: string;
+  class?: string;
+}
+
+const { label, text, id, class: className } = Astro.props;
+const tipId =
+  id ?? `tip-${Math.random().toString(36).slice(2, 9)}-${Date.now().toString(36).slice(-4)}`;
+const classes = ["ui-tooltip", className].filter(Boolean).join(" ");
+---
+
+<span class={classes}>
+  <button
+    type="button"
+    class="ui-tooltip__trigger"
+    aria-label={label}
+    aria-describedby={tipId}
+  >
+    ?
+  </button>
+  <span role="tooltip" id={tipId} class="ui-tooltip__bubble">{text}</span>
+</span>
+
+<style>
+  .ui-tooltip {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .ui-tooltip__trigger {
+    display: inline-grid;
+    place-items: center;
+    width: 16px;
+    height: 16px;
+    padding: 0;
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-pill);
+    background: var(--color-panel);
+    color: var(--color-text-muted);
+    font: inherit;
+    font-size: 10px;
+    font-weight: var(--weight-bold);
+    line-height: 1;
+    cursor: help;
+    transition:
+      color var(--duration-hover) var(--ease-out),
+      border-color var(--duration-hover) var(--ease-out);
+  }
+
+  .ui-tooltip__trigger:hover,
+  .ui-tooltip__trigger:focus-visible {
+    color: var(--color-accent);
+    border-color: var(--color-accent);
+    outline: none;
+  }
+
+  .ui-tooltip__bubble {
+    position: absolute;
+    bottom: calc(100% + var(--space-1-5));
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 50;
+    width: max-content;
+    max-width: 240px;
+    padding: var(--space-2) var(--space-3);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-sm);
+    background: var(--color-panel);
+    color: var(--color-text);
+    box-shadow: var(--shadow-md);
+    font-size: var(--text-sm);
+    font-weight: var(--weight-regular);
+    line-height: var(--leading-snug);
+    text-transform: none;
+    letter-spacing: 0;
+    pointer-events: none;
+    opacity: 0;
+    transform: translateX(-50%) scale(0.97);
+    transform-origin: bottom center;
+    transition:
+      opacity var(--duration-popover) var(--ease-out),
+      transform var(--duration-popover) var(--ease-out);
+  }
+
+  .ui-tooltip__trigger:hover + .ui-tooltip__bubble,
+  .ui-tooltip__trigger:focus-visible + .ui-tooltip__bubble {
+    opacity: 1;
+    transform: translateX(-50%) scale(1);
+  }
+</style>

package/src/layouts/BaseLayout.astro

@@ -0,0 +1,147 @@
+---
+import "../styles/global.css";
+import ThemeToggle from "../components/ThemeToggle.tsx";
+import SidebarToggle from "../components/SidebarToggle.tsx";
+import LanguageSwitcher from "../components/LanguageSwitcher.tsx";
+import { defaultLocale, getT, isLocale, localizedHref, type Locale } from "@lib/i18n.js";
+
+interface Props {
+  title: string;
+  description?: string;
+}
+
+const { title, description } = Astro.props;
+
+const rawLocale = Astro.currentLocale ?? defaultLocale;
+const locale: Locale = isLocale(rawLocale) ? rawLocale : defaultLocale;
+const t = await getT(locale);
+const tCommon = (key: string, params?: Record<string, unknown>) => t(`common:${key}`, params);
+const tSidebar = (key: string, params?: Record<string, unknown>) => t(`sidebar:${key}`, params);
+
+const finalDescription = description ?? tCommon("metaDefault") ?? "Acta document viewer";
+
+const base = import.meta.env.BASE_URL; // "/" in dev, "/acta/" in prod
+const basePrefix = base === "/" ? "" : base.replace(/\/$/, ""); // "" or "/acta"
+const rawPathname = Astro.url.pathname;
+const pathname = basePrefix && rawPathname.startsWith(basePrefix)
+  ? rawPathname.slice(basePrefix.length) || "/"
+  : rawPathname;
+const segments = pathname.split("/").filter(Boolean);
+const bareSegments = segments[0] && isLocale(segments[0]) ? segments.slice(1) : segments;
+const barePath = `/${bareSegments.join("/")}${bareSegments.length > 0 ? "/" : ""}` || "/";
+
+const isActive = (href: string) => {
+  if (href === "/") return barePath === "/" || barePath.startsWith("/documents");
+  return barePath === href || barePath.startsWith(href);
+};
+
+const navItems = [
+  { href: "/", label: tSidebar("nav.documents"), num: "01" },
+  { href: "/graph/", label: tSidebar("nav.graph"), num: "02" },
+  { href: "/validation/", label: tSidebar("nav.validation"), num: "03" },
+];
+
+const languageLabels = { en: tSidebar("language.en"), ru: tSidebar("language.ru") };
+---
+
+<!doctype html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content={finalDescription} />
+    <title>{title}</title>
+    <link rel="icon" href={`${basePrefix}/favicon.png`} />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      rel="stylesheet"
+      href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;1,6..72,400;1,6..72,500&family=Inter+Tight:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap"
+    />
+    <script is:inline>
+      (() => {
+        try {
+          const t = localStorage.getItem("acta-theme") ?? "system";
+          const r =
+            t === "system"
+              ? matchMedia("(prefers-color-scheme: dark)").matches
+                ? "dark"
+                : "light"
+              : t;
+          document.documentElement.dataset.theme = r;
+          document.documentElement.dataset.themePref = t;
+          const s = localStorage.getItem("acta-sidebar");
+          document.documentElement.dataset.sidebar = s === "collapsed" ? "collapsed" : "expanded";
+        } catch {
+          document.documentElement.dataset.theme = "light";
+          document.documentElement.dataset.themePref = "system";
+          document.documentElement.dataset.sidebar = "expanded";
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div class="app-shell">
+      <aside class="sidebar">
+        <div class="sidebar-head">
+          <a class="brand" href={localizedHref(locale, "/", base)}>
+            <span class="brand-mark"><img src={`${basePrefix}/favicon.png`} alt="A" /></span>
+            <span class="brand-label">
+              <strong class="brand-wordmark">Acta</strong>
+              <small class="brand-kicker">{tSidebar("brand.subtitle")}</small>
+            </span>
+          </a>
+          <SidebarToggle
+            client:load
+            labels={{
+              collapse: tSidebar("sidebar.collapse"),
+              expand: tSidebar("sidebar.expand"),
+            }}
+          />
+        </div>
+        <nav class="nav">
+          {
+            navItems.map((item) => {
+              const active = isActive(item.href);
+              return (
+                <a
+                  href={localizedHref(locale, item.href, base)}
+                  title={item.label}
+                  aria-label={item.label}
+                  class:list={[{ "is-active": active }]}
+                  aria-current={active ? "page" : undefined}
+                >
+                  <span class="nav-num" aria-hidden="true">{item.num}</span>
+                  <span class="nav-letter" aria-hidden="true">{item.label.charAt(0)}</span>
+                  <span class="nav-label">{item.label}</span>
+                  <span class="nav-bar" aria-hidden="true"></span>
+                </a>
+              );
+            })
+          }
+        </nav>
+        <slot name="sidebar" />
+        <div class="sidebar-foot">
+          <LanguageSwitcher
+            client:load
+            labels={languageLabels}
+            legend={tSidebar("language.legend")}
+            base={base}
+          />
+          <ThemeToggle
+            client:load
+            labels={{
+              legend: tSidebar("theme.legend"),
+              system: tSidebar("theme.system"),
+              light: tSidebar("theme.light"),
+              dark: tSidebar("theme.dark"),
+            }}
+          />
+        </div>
+      </aside>
+      <main class="content">
+        <slot />
+      </main>
+    </div>
+  </body>
+</html>

package/src/lib/documents.test.ts

@@ -0,0 +1,175 @@
+import type { ActaDocument } from "@acta-dev/core";
+import { describe, expect, it } from "vitest";
+import {
+  buildDocumentHref,
+  buildDocumentOrderIndex,
+  collectFilterOptions,
+  filterDocuments,
+  formatDisplayDate,
+  getDocumentSearchText,
+  getNextDocumentLimit,
+  shouldShowMoreDocuments,
+  sortDocumentsByNewest,
+} from "./documents.js";
+
+describe("web document utilities", () => {
+  it("builds stable document URLs from document IDs", () => {
+    expect(buildDocumentHref("ADR-0001")).toBe("/documents/ADR-0001/");
+    expect(buildDocumentHref("SPEC 0002")).toBe("/documents/SPEC%200002/");
+  });
+
+  it("collects sorted tags, components, statuses, and kinds for filters", () => {
+    const options = collectFilterOptions([
+      documentFixture({
+        id: "ADR-0001",
+        kind: "adr",
+        status: "accepted",
+        tags: ["architecture", "core"],
+        component: ["acta-core"],
+      }),
+      documentFixture({
+        id: "SPEC-0001",
+        kind: "spec",
+        status: "active",
+        tags: ["core"],
+        component: ["acta-web"],
+      }),
+    ]);
+
+    expect(options.kinds).toEqual(["adr", "spec"]);
+    expect(options.statuses).toEqual(["accepted", "active"]);
+    expect(options.tags).toEqual(["architecture", "core"]);
+    expect(options.components).toEqual(["acta-core", "acta-web"]);
+  });
+
+  it("filters by free text, kind, status, tag, and component", () => {
+    const documents = [
+      documentFixture({
+        id: "ADR-0001",
+        title: "Use Markdown as source of truth",
+        kind: "adr",
+        status: "accepted",
+        tags: ["source"],
+        component: ["acta-core"],
+        body: "Markdown files stay in Git.",
+      }),
+      documentFixture({
+        id: "SPEC-0004",
+        title: "Acta web viewer",
+        kind: "spec",
+        status: "active",
+        tags: ["web"],
+        component: ["acta-web"],
+        body: "Static Astro interface for documents.",
+      }),
+    ];
+
+    expect(
+      filterDocuments(documents, {
+        query: "astro",
+        kind: "spec",
+        status: "active",
+        tag: "web",
+        component: "acta-web",
+      }).map((document) => document.id),
+    ).toEqual(["SPEC-0004"]);
+  });
+
+  it("sorts newest documents first and uses descending IDs for matching dates", () => {
+    const documents = [
+      documentFixture({ id: "SPEC-0001", date: "2026-04-26" }),
+      documentFixture({ id: "SPEC-0002", date: "2026-04-26" }),
+      documentFixture({ id: "ADR-0004", date: "2026-05-01" }),
+      documentFixture({ id: "SPEC-0004", date: "2026-05-01" }),
+    ];
+
+    expect(sortDocumentsByNewest(documents).map((document) => document.id)).toEqual([
+      "SPEC-0004",
+      "ADR-0004",
+      "SPEC-0002",
+      "SPEC-0001",
+    ]);
+  });
+
+  it("builds document order indexes for client-side sorting", () => {
+    const documents = [
+      documentFixture({ id: "SPEC-0001", date: "2026-04-26" }),
+      documentFixture({ id: "ADR-0004", date: "2026-05-01" }),
+      documentFixture({ id: "SPEC-0004", date: "2026-05-01" }),
+    ];
+
+    expect(buildDocumentOrderIndex(sortDocumentsByNewest(documents))).toEqual({
+      "SPEC-0004": 0,
+      "ADR-0004": 1,
+      "SPEC-0001": 2,
+    });
+  });
+
+  it("increments the document list limit without exceeding the matching count", () => {
+    expect(getNextDocumentLimit(20, 45)).toBe(40);
+    expect(getNextDocumentLimit(40, 45)).toBe(45);
+    expect(shouldShowMoreDocuments(45, 40)).toBe(true);
+    expect(shouldShowMoreDocuments(45, 45)).toBe(false);
+  });
+
+  it("formats display date by dropping the time portion of ISO datetime", () => {
+    expect(formatDisplayDate("2026-04-26T08:15:00.000Z")).toBe("2026-04-26");
+    expect(formatDisplayDate("2026-04-26")).toBe("2026-04-26");
+    expect(formatDisplayDate("")).toBe("");
+    expect(formatDisplayDate("not-a-date")).toBe("not-a-date");
+  });
+
+  it("includes metadata and section content in search text", () => {
+    const document = documentFixture({
+      id: "SPEC-0004",
+      summary: "Static document viewer",
+      owners: ["Boris"],
+      sections: [{ level: 1, title: "Requirements", content: "Client-side filtering" }],
+    });
+
+    expect(getDocumentSearchText(document)).toContain("spec-0004");
+    expect(getDocumentSearchText(document)).toContain("static document viewer");
+    expect(getDocumentSearchText(document)).toContain("boris");
+    expect(getDocumentSearchText(document)).toContain("client-side filtering");
+  });
+});
+
+function documentFixture(overrides: Partial<ActaDocument> = {}): ActaDocument {
+  return {
+    id: "ADR-0001",
+    kind: "adr",
+    title: "Use Markdown",
+    status: "accepted",
+    date: "2026-05-01",
+    tags: [],
+    component: [],
+    owners: [],
+    links: {
+      related: [],
+      supersedes: [],
+      replacedBy: [],
+      decidedBy: [],
+      dependsOn: [],
+      validates: [],
+      references: [],
+    },
+    backlinks: {
+      related: [],
+      supersedes: [],
+      replacedBy: [],
+      decidedBy: [],
+      dependsOn: [],
+      validates: [],
+      references: [],
+    },
+    sections: [],
+    body: "",
+    file: {
+      path: "/repo/docs/decisions/ADR-0001-use-markdown.md",
+      relativePath: "docs/decisions/ADR-0001-use-markdown.md",
+      slug: "ADR-0001-use-markdown",
+      contentHash: "hash",
+    },
+    ...overrides,
+  } as ActaDocument;
+}

package/src/lib/documents.ts

@@ -0,0 +1,156 @@
+import type { ActaDocument, InternalLinkKey, ValidationIssue } from "@acta-dev/core";
+
+export interface DocumentFilters {
+  query?: string;
+  kind?: string;
+  status?: string;
+  tag?: string;
+  component?: string;
+}
+
+export interface FilterOptions {
+  kinds: string[];
+  statuses: string[];
+  tags: string[];
+  components: string[];
+}
+
+export const documentPageSize = 20;
+
+export const internalLinkKeys: InternalLinkKey[] = [
+  "related",
+  "supersedes",
+  "replacedBy",
+  "decidedBy",
+  "dependsOn",
+  "validates",
+];
+
+export function buildDocumentHref(id: string): string {
+  return `/documents/${encodeURIComponent(id)}/`;
+}
+
+export function collectFilterOptions(documents: ActaDocument[]): FilterOptions {
+  return {
+    kinds: uniqueSorted(documents.map((document) => document.kind)),
+    statuses: uniqueSorted(documents.map((document) => document.status)),
+    tags: uniqueSorted(documents.flatMap((document) => document.tags)),
+    components: uniqueSorted(documents.flatMap((document) => document.component)),
+  };
+}
+
+export function filterDocuments(
+  documents: ActaDocument[],
+  filters: DocumentFilters,
+): ActaDocument[] {
+  const query = normalize(filters.query ?? "");
+
+  return documents.filter((document) => {
+    if (filters.kind && document.kind !== filters.kind) {
+      return false;
+    }
+
+    if (filters.status && document.status !== filters.status) {
+      return false;
+    }
+
+    if (filters.tag && !document.tags.includes(filters.tag)) {
+      return false;
+    }
+
+    if (filters.component && !document.component.includes(filters.component)) {
+      return false;
+    }
+
+    return query.length === 0 || getDocumentSearchText(document).includes(query);
+  });
+}
+
+export function sortDocumentsByNewest(documents: ActaDocument[]): ActaDocument[] {
+  return documents.slice().sort((left, right) => {
+    const dateOrder = right.date.localeCompare(left.date);
+    return dateOrder === 0 ? right.id.localeCompare(left.id) : dateOrder;
+  });
+}
+
+/**
+ * Format an ISO 8601 datetime for human display as `YYYY-MM-DD`. Time portion is dropped.
+ * Falls back to the original value if parsing fails so historical day-only values keep working.
+ */
+export function formatDisplayDate(value: string): string {
+  if (!value) {
+    return "";
+  }
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return value;
+  }
+  const year = parsed.getUTCFullYear();
+  const month = String(parsed.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(parsed.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+export function buildDocumentOrderIndex(documents: ActaDocument[]): Record<string, number> {
+  return Object.fromEntries(documents.map((document, index) => [document.id, index]));
+}
+
+export function getNextDocumentLimit(
+  currentLimit: number,
+  matchingCount: number,
+  pageSize = documentPageSize,
+): number {
+  return Math.min(currentLimit + pageSize, matchingCount);
+}
+
+export function shouldShowMoreDocuments(matchingCount: number, visibleLimit: number): boolean {
+  return matchingCount > visibleLimit;
+}
+
+export function getDocumentSearchText(document: ActaDocument): string {
+  return normalize(
+    [
+      document.id,
+      document.title,
+      document.summary ?? "",
+      document.status,
+      document.kind,
+      ...document.tags,
+      ...document.component,
+      ...document.owners,
+      ...document.sections.flatMap((section) => [section.title, section.content]),
+      document.body,
+    ].join(" "),
+  );
+}
+
+export function getIssuesForDocument(
+  issues: ValidationIssue[],
+  document: ActaDocument,
+): ValidationIssue[] {
+  return issues.filter(
+    (issue) => issue.documentId === document.id || issue.path === document.file.path,
+  );
+}
+
+export function getDocumentById(documents: ActaDocument[], id: string): ActaDocument | undefined {
+  return documents.find((document) => document.id === id);
+}
+
+export function hasInternalLinks(document: ActaDocument): boolean {
+  return internalLinkKeys.some((key) => document.links[key].length > 0);
+}
+
+export function hasBacklinks(document: ActaDocument): boolean {
+  return internalLinkKeys.some((key) => document.backlinks[key].length > 0);
+}
+
+function normalize(value: string): string {
+  return value.toLowerCase().trim();
+}
+
+function uniqueSorted(values: string[]): string[] {
+  return [...new Set(values.filter((value) => value.length > 0))].sort((left, right) =>
+    left.localeCompare(right),
+  );
+}

package/src/lib/i18n-client.ts

@@ -0,0 +1,32 @@
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { defaultLocale, isLocale, type Locale, resources } from "./i18n.js";
+
+let started = false;
+
+export function ensureClientI18n(): void {
+  if (started) return;
+  started = true;
+  const lang = readClientLocale();
+  i18next.use(initReactI18next).init({
+    lng: lang,
+    fallbackLng: defaultLocale,
+    ns: Object.keys(resources[defaultLocale] ?? {}),
+    defaultNS: "common",
+    resources: Object.fromEntries(
+      Object.entries(resources).map(([code, ns]) => [
+        code,
+        Object.fromEntries(Object.entries(ns).map(([k, v]) => [k, v as object])),
+      ]),
+    ),
+    interpolation: { escapeValue: false },
+    returnNull: false,
+  });
+}
+
+export function readClientLocale(): Locale {
+  if (typeof document === "undefined") return defaultLocale;
+  const fromHtml = document.documentElement.lang;
+  if (isLocale(fromHtml)) return fromHtml;
+  return defaultLocale;
+}

package/src/lib/i18n.ts

@@ -0,0 +1,92 @@
+import i18next, { type i18n as I18nInstance } from "i18next";
+
+const localeModules = import.meta.glob("../locales/**/*.json", { eager: true }) as Record<
+  string,
+  { default: Record<string, unknown> }
+>;
+
+export type Locale = "en" | "ru";
+export const locales: Locale[] = ["en", "ru"];
+export const defaultLocale: Locale = "en";
+
+type Resources = Record<string, Record<string, Record<string, unknown>>>;
+
+function buildResources(): Resources {
+  const out: Resources = {};
+  for (const [path, mod] of Object.entries(localeModules)) {
+    const match = path.match(/\/locales\/([^/]+)\/([^/]+)\.json$/);
+    if (!match) continue;
+    const [, lang, ns] = match;
+    out[lang] ??= {};
+    out[lang][ns] = mod.default;
+  }
+  return out;
+}
+
+export const resources = buildResources();
+
+const namespaces = Object.keys(resources[defaultLocale] ?? {});
+
+let initPromise: Promise<I18nInstance> | null = null;
+
+export function getI18n(locale: Locale = defaultLocale): Promise<I18nInstance> {
+  if (!initPromise) {
+    initPromise = i18next
+      .init({
+        lng: locale,
+        fallbackLng: defaultLocale,
+        ns: namespaces,
+        defaultNS: "common",
+        resources: Object.fromEntries(
+          Object.entries(resources).map(([lang, ns]) => [
+            lang,
+            Object.fromEntries(Object.entries(ns).map(([k, v]) => [k, v as object])),
+          ]),
+        ),
+        interpolation: { escapeValue: false },
+        returnNull: false,
+      })
+      .then(() => i18next);
+  }
+  return initPromise.then(async (instance) => {
+    if (instance.language !== locale) {
+      await instance.changeLanguage(locale);
+    }
+    return instance;
+  });
+}
+
+export type TFunc = (key: string, params?: Record<string, unknown>) => string;
+
+export async function getT(locale: Locale = defaultLocale): Promise<TFunc> {
+  const instance = await getI18n(locale);
+  const fixedT = instance.getFixedT(locale);
+  return (key, params) => fixedT(key, params) as string;
+}
+
+export function isLocale(value: string | undefined): value is Locale {
+  return value === "en" || value === "ru";
+}
+
+export function getLocaleFromUrl(url: URL): Locale {
+  const segments = url.pathname.split("/").filter(Boolean);
+  if (segments[0] && isLocale(segments[0])) return segments[0];
+  return defaultLocale;
+}
+
+export function localizedHref(
+  locale: Locale,
+  path: string,
+  base = import.meta.env.BASE_URL,
+): string {
+  const normalized = path.startsWith("/") ? path : `/${path}`;
+  const localizedPath =
+    locale === defaultLocale
+      ? normalized
+      : normalized === "/"
+        ? `/${locale}/`
+        : `/${locale}${normalized}`;
+  // BASE_URL is "/" in dev or "/acta/" in prod — strip trailing slash for concat
+  const basePrefix = base === "/" ? "" : base.replace(/\/$/, "");
+  return `${basePrefix}${localizedPath}`;
+}