@acta-dev/web 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boris Khakhin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/astro.config.mjs

@@ -0,0 +1,31 @@
+import { defineConfig } from "astro/config";
+import { fileURLToPath } from "node:url";
+import react from "@astrojs/react";
+
+const isPagesBuild = process.env.GITHUB_PAGES === "true";
+
+// `acta site` drives the build from outside the monorepo and injects these.
+const siteUrl =
+  process.env.ACTA_SITE ?? (isPagesBuild ? "https://jentix.github.io" : "http://localhost:4321");
+const base = process.env.ACTA_BASE ?? (isPagesBuild ? "/acta" : undefined);
+const outDir = process.env.ACTA_SITE_OUT || undefined;
+
+export default defineConfig({
+  site: siteUrl,
+  base,
+  ...(outDir ? { outDir } : {}),
+  output: "static",
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en", "ru"],
+    routing: { prefixDefaultLocale: false },
+  },
+  integrations: [react()],
+  vite: {
+    resolve: {
+      alias: {
+        "@lib": fileURLToPath(new URL("./src/lib", import.meta.url)),
+      },
+    },
+  },
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@acta-dev/web",
+  "version": "1.0.0",
+  "description": "Prebuilt Astro viewer for Acta docs-as-code repositories, built on demand by `acta site`",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jentix/acta.git",
+    "directory": "apps/web"
+  },
+  "homepage": "https://github.com/jentix/acta#readme",
+  "keywords": [
+    "acta",
+    "adr",
+    "docs-as-code",
+    "astro",
+    "viewer"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "public",
+    "astro.config.mjs",
+    "tsconfig.json"
+  ],
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@astrojs/react": "^5.0.5",
+    "@dagrejs/dagre": "^3.0.0",
+    "@orama/orama": "^3.1.18",
+    "@xyflow/react": "^12.10.2",
+    "astro": "^6.3.7",
+    "i18next": "^26.2.0",
+    "i18next-resources-to-backend": "^1.2.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-i18next": "^17.0.8",
+    "@acta-dev/core": "1.1.0",
+    "@acta-dev/renderer": "1.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.9",
+    "@types/dagre": "^0.7.54",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "artifacts": "node scripts/build-artifacts.mjs",
+    "dev": "node scripts/build-artifacts.mjs && ASTRO_TELEMETRY_DISABLED=1 astro dev --host 127.0.0.1",
+    "build": "node scripts/build-artifacts.mjs && ASTRO_TELEMETRY_DISABLED=1 astro build",
+    "preview": "ASTRO_TELEMETRY_DISABLED=1 astro preview",
+    "test": "vitest run",
+    "typecheck": "ASTRO_TELEMETRY_DISABLED=1 astro check"
+  }
+}

package/src/components/DocumentSearchList.astro

@@ -0,0 +1,150 @@
+---
+import type { ActaDocument } from "@acta-dev/core";
+import {
+  buildDocumentHref,
+  buildDocumentOrderIndex,
+  collectFilterOptions,
+  documentPageSize,
+  formatDisplayDate,
+} from "../lib/documents.js";
+import { defaultLocale, getT, isLocale, localizedHref, type Locale } from "../lib/i18n.js";
+import Field from "./ui/Field.astro";
+import Input from "./ui/Input.astro";
+import Select from "./ui/Select.astro";
+import SegmentedControl from "./ui/SegmentedControl.astro";
+import Chip from "./ui/Chip.astro";
+import Button from "./ui/Button.astro";
+
+interface Props {
+  documents: ActaDocument[];
+  dependencyDocumentIds: string[];
+}
+
+const { documents, dependencyDocumentIds } = Astro.props;
+const filterOptions = collectFilterOptions(documents);
+const newestOrder = buildDocumentOrderIndex(documents);
+const documentsById = new Map(documents.map((document) => [document.id, document]));
+const dependencyOrderDocuments = dependencyDocumentIds
+  .map((id) => documentsById.get(id))
+  .filter((document) => document !== undefined);
+const dependencyOrder = buildDocumentOrderIndex(dependencyOrderDocuments);
+
+const rawLocale = Astro.currentLocale ?? defaultLocale;
+const locale: Locale = isLocale(rawLocale) ? rawLocale : defaultLocale;
+const t = await getT(locale);
+const td = (key: string) => t(`documents:${key}`);
+const tc = (key: string) => t(`common:${key}`);
+---
+
+<div data-document-search-root>
+  <section class="toolbar" aria-label={td("filters.legend")}>
+    <Field label={td("filters.search")}>
+      <Input type="search" placeholder={td("filters.searchPlaceholder")} data-search-query />
+    </Field>
+    <Field label={td("filters.kind")}>
+      <Select data-filter-kind>
+        <option value="">{tc("all")}</option>
+        {filterOptions.kinds.map((kind) => <option value={kind}>{kind.toUpperCase()}</option>)}
+      </Select>
+    </Field>
+    <Field label={td("filters.status")}>
+      <Select data-filter-status>
+        <option value="">{tc("all")}</option>
+        {filterOptions.statuses.map((status) => <option value={status}>{status}</option>)}
+      </Select>
+    </Field>
+    <Field label={td("filters.tag")}>
+      <Select data-filter-tag>
+        <option value="">{tc("all")}</option>
+        {filterOptions.tags.map((tag) => <option value={tag}>{tag}</option>)}
+      </Select>
+    </Field>
+    <Field label={td("filters.component")}>
+      <Select data-filter-component>
+        <option value="">{tc("all")}</option>
+        {
+          filterOptions.components.map((component) => (
+            <option value={component}>{component}</option>
+          ))
+        }
+      </Select>
+    </Field>
+    <SegmentedControl
+      name="sort-order"
+      legend={td("filters.sort")}
+      value="newest"
+      dataAttr="data-sort-order"
+      options={[
+        { value: "newest", label: td("filters.sortNewest") },
+        { value: "dependency", label: td("filters.sortDependency") },
+      ]}
+    />
+  </section>
+  <div class="toolbar-sub">
+    <label class="content-search">
+      <input type="checkbox" data-search-content />
+      <span>{td("filters.searchContent")}</span>
+    </label>
+    <span class="content-loading muted" data-search-content-loading hidden>
+      {td("filters.searchingContent")}
+    </span>
+  </div>
+
+  <section
+    class="document-list"
+    aria-live="polite"
+    data-document-list
+    data-page-size={documentPageSize}
+  >
+    {
+      documents.map((document) => (
+        <article
+          class="document-row"
+          data-document-row
+          data-document-id={document.id}
+          data-kind={document.kind}
+          data-status={document.status}
+          data-tags={document.tags.join(" ")}
+          data-components={document.component.join(" ")}
+          data-newest-order={newestOrder[document.id]}
+          data-dependency-order={dependencyOrder[document.id] ?? newestOrder[document.id]}
+        >
+          <div class="row-id">
+            <Chip kind={document.kind}>{document.kind}</Chip>
+            <span>{document.id.replace(/^(?:adr|spec)-/i, "")}</span>
+          </div>
+          <div class="row-main">
+            <a class="document-title" href={localizedHref(locale, buildDocumentHref(document.id))}>
+              {document.title}
+            </a>
+            {document.summary && <p class="row-summary">{document.summary}</p>}
+          </div>
+          <div class="row-status">
+            <Chip status={document.status}>{document.status}</Chip>
+          </div>
+          <span class="row-date">{formatDisplayDate(document.date)}</span>
+        </article>
+      ))
+    }
+    <p class="empty-state" data-empty-state hidden>{td("empty")}</p>
+  </section>
+  <div class="list-actions">
+    <Button data-show-more hidden>{td("showMore")}</Button>
+  </div>
+</div>
+
+<script>
+  import { initDocumentSearch } from "../lib/search-client.js";
+
+  for (const root of document.querySelectorAll<HTMLElement>("[data-document-search-root]")) {
+    initDocumentSearch(root);
+  }
+</script>
+
+<style>
+  .toolbar-sub {
+    display: flex;
+    align-items: center;
+    gap: var(--space-4);
+  }
+</style>

package/src/components/DocumentView.astro

@@ -0,0 +1,198 @@
+---
+import type { ActaDocument, ValidationIssue } from "@acta-dev/core";
+import Chip from "./ui/Chip.astro";
+import Tooltip from "./ui/Tooltip.astro";
+import {
+  buildDocumentHref,
+  formatDisplayDate,
+  getDocumentById,
+  hasBacklinks,
+  internalLinkKeys,
+} from "../lib/documents.js";
+import { getT, localizedHref, type Locale } from "../lib/i18n.js";
+
+interface Props {
+  document: ActaDocument;
+  documents: ActaDocument[];
+  issues: ValidationIssue[];
+  rendered: { html: string };
+  locale: Locale;
+}
+
+const { document, documents, issues, rendered, locale } = Astro.props;
+
+const t = await getT(locale);
+const td = (key: string, params?: Record<string, unknown>) => t(`documents:${key}`, params);
+const tc = (key: string) => t(`common:${key}`);
+const linkDesc = (key: string, dir: "outgoing" | "incoming") =>
+  t(`documents:linkTypes.${key}.${dir}`);
+const severityLabel = (sev: string) => t(`validation:severity.${sev}`);
+
+const prettyKey = (key: string) =>
+  key.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase());
+
+// Outgoing internal links, grouped by type (Related, Depends on, …)
+const linkGroups = internalLinkKeys
+  .filter((key) => document.links[key].length > 0)
+  .map((key) => ({ key, ids: document.links[key] }));
+
+// Backlinks flattened into a single list (deduped) for the meta column
+const backlinkIds = hasBacklinks(document)
+  ? [...new Set(internalLinkKeys.flatMap((key) => document.backlinks[key]))]
+  : [];
+
+const references = document.links.references;
+---
+
+<div class="crumbs">
+  <a href={localizedHref(locale, "/")}>← {td("detail.back")}</a>
+  <span>{document.id}</span>
+  <span class="grow"></span>
+  {
+    references.length > 0 && (
+      <a href={references[0]} target="_blank" rel="noreferrer">
+        ↗ {td("detail.externalReferences")}
+      </a>
+    )
+  }
+</div>
+
+<header class="page-header">
+  <div class="doc-kicker">
+    <Chip kind={document.kind}>{document.kind}</Chip>
+    <Chip status={document.status} class="doc-status">{document.status}</Chip>
+    <span>{formatDisplayDate(document.date)}</span>
+  </div>
+  <h1>{document.title}</h1>
+  <div class="doc-byline">
+    <span><b>{document.id}</b></span>
+    {
+      document.owners.length > 0 && (
+        <span>{td("detail.owners")} <b>{document.owners.join(", ")}</b></span>
+      )
+    }
+    <span><b>{formatDisplayDate(document.date)}</b></span>
+    <span><code>{document.file.relativePath}</code></span>
+  </div>
+  {document.summary && <p class="doc-standfirst">{document.summary}</p>}
+</header>
+
+<div class="document-grid">
+  <aside class="metadata-panel">
+    <dl>
+      <div class="meta-block">
+        <dt>{td("detail.owners")}</dt>
+        <dd>{document.owners.length > 0 ? document.owners.join(", ") : tc("none")}</dd>
+      </div>
+      <div class="meta-block">
+        <dt>{td("detail.tags")}</dt>
+        <dd>{document.tags.length > 0 ? document.tags.join(", ") : tc("none")}</dd>
+      </div>
+      <div class="meta-block">
+        <dt>{td("detail.components")}</dt>
+        <dd>
+          {
+            document.component.length > 0
+              ? document.component.map((component, index) => (
+                  <>
+                    {index > 0 ? ", " : ""}
+                    <code>{component}</code>
+                  </>
+                ))
+              : tc("none")
+          }
+        </dd>
+      </div>
+      <div class="meta-block">
+        <dt>{td("detail.file")}</dt>
+        <dd><code>{document.file.relativePath}</code></dd>
+      </div>
+
+      {
+        linkGroups.map(({ key, ids }) => (
+          <div class="meta-block">
+            <span class="meta-lbl">
+              {prettyKey(key)} <span class="ct">· {ids.length}</span>
+              <Tooltip
+                label={td("linkTypes.tooltipOutgoing", { key })}
+                text={linkDesc(key, "outgoing")}
+              />
+            </span>
+            <div class="meta-links">
+              {ids.map((id) => {
+                const target = getDocumentById(documents, id);
+                return (
+                  <a class="metalink" href={localizedHref(locale, buildDocumentHref(id))}>
+                    <span class="id">{id}</span>
+                    {target && <span class="t">{target.title}</span>}
+                  </a>
+                );
+              })}
+            </div>
+          </div>
+        ))
+      }
+
+      <div class="meta-block">
+        <span class="meta-lbl">
+          {td("detail.backlinks")} <span class="ct">· {backlinkIds.length}</span>
+        </span>
+        <div class="meta-links">
+          {
+            backlinkIds.length > 0 ? (
+              backlinkIds.map((id) => {
+                const source = getDocumentById(documents, id);
+                return (
+                  <a class="metalink" href={localizedHref(locale, buildDocumentHref(id))}>
+                    <span class="id">{id}</span>
+                    {source && <span class="t">{source.title}</span>}
+                  </a>
+                );
+              })
+            ) : (
+              <span class="metalink empty">
+                <span class="t">{td("detail.noBacklinks")}</span>
+              </span>
+            )
+          }
+        </div>
+      </div>
+    </dl>
+
+    {
+      issues.length > 0 && (
+        <section class="issue-list compact">
+          <h2>{td("detail.validation")}</h2>
+          {issues.map((issue) => (
+            <p class={`issue severity-${issue.severity}`}>
+              <strong>{severityLabel(issue.severity)}</strong> {issue.message}
+            </p>
+          ))}
+        </section>
+      )
+    }
+  </aside>
+
+  <article class="markdown" set:html={rendered.html} />
+</div>
+
+{
+  references.length > 0 && (
+    <section class="relations">
+      <div class="relation-group-header">
+        <h2>{td("detail.externalReferences")}</h2>
+        <Tooltip
+          label={td("linkTypes.tooltipOutgoing", { key: "references" })}
+          text={linkDesc("references", "outgoing")}
+        />
+      </div>
+      <div class="chip-list">
+        {references.map((reference) => (
+          <Chip as="a" href={reference} interactive>
+            {reference}
+          </Chip>
+        ))}
+      </div>
+    </section>
+  )
+}

package/src/components/LanguageSwitcher.tsx

@@ -0,0 +1,115 @@
+import { useEffect, useRef, useState } from "react";
+import { defaultLocale, isLocale, type Locale, locales } from "../lib/i18n.js";
+import { ensureClientI18n } from "../lib/i18n-client.js";
+
+const STORAGE_KEY = "acta-locale";
+const COOKIE_KEY = "acta-locale";
+
+function readLocale(): Locale {
+  if (typeof document === "undefined") return defaultLocale;
+  const stored = window.localStorage.getItem(STORAGE_KEY);
+  if (isLocale(stored ?? "")) return stored as Locale;
+  const lang = document.documentElement.lang;
+  return isLocale(lang) ? lang : defaultLocale;
+}
+
+function stripLocaleFromPath(path: string, base: string): string {
+  // Strip base prefix first ("/acta/" → "/acta", then remove from path start)
+  const basePrefix = base === "/" ? "" : base.replace(/\/$/, "");
+  const withoutBase =
+    basePrefix && path.startsWith(basePrefix) ? path.slice(basePrefix.length) || "/" : path;
+  const segments = withoutBase.split("/").filter(Boolean);
+  if (segments[0] && isLocale(segments[0])) {
+    return `/${segments.slice(1).join("/")}` || "/";
+  }
+  return withoutBase || "/";
+}
+
+function buildTargetUrl(locale: Locale, base: string): string {
+  const bare = stripLocaleFromPath(window.location.pathname, base);
+  const basePrefix = base === "/" ? "" : base.replace(/\/$/, "");
+  const localizedPath =
+    locale === defaultLocale
+      ? bare
+      : bare === "/"
+        ? `/${locale}/`
+        : `/${locale}${bare.startsWith("/") ? bare : `/${bare}`}`;
+  return `${basePrefix}${localizedPath}${window.location.search}${window.location.hash}`;
+}
+
+type Props = { labels: Record<Locale, string>; legend: string; base?: string };
+
+export default function LanguageSwitcher({
+  labels,
+  legend,
+  base = import.meta.env.BASE_URL,
+}: Props) {
+  ensureClientI18n();
+  const [current, setCurrent] = useState<Locale>(defaultLocale);
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    setCurrent(readLocale());
+  }, []);
+
+  useEffect(() => {
+    if (!open) return;
+    const onClick = (event: MouseEvent) => {
+      if (!rootRef.current?.contains(event.target as Node)) setOpen(false);
+    };
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setOpen(false);
+    };
+    document.addEventListener("mousedown", onClick);
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("mousedown", onClick);
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [open]);
+
+  const update = (next: Locale) => {
+    setOpen(false);
+    if (next === current) return;
+    window.localStorage.setItem(STORAGE_KEY, next);
+    document.cookie = `${COOKIE_KEY}=${next}; path=/; max-age=31536000; samesite=lax`;
+    window.location.assign(buildTargetUrl(next, base));
+  };
+
+  return (
+    <div className="lang-switcher" ref={rootRef}>
+      <button
+        type="button"
+        className="lang-trigger"
+        aria-label={legend}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        onClick={() => setOpen((value) => !value)}
+      >
+        <span className="code">{current.toUpperCase()}</span>
+        <span className="name">{labels[current]}</span>
+        <span className="caret" aria-hidden="true">
+          {open ? "▴" : "▾"}
+        </span>
+      </button>
+      {open && (
+        <div className="lang-menu" role="listbox" aria-label={legend}>
+          {locales.map((code) => (
+            <button
+              key={code}
+              type="button"
+              role="option"
+              aria-selected={code === current}
+              className={code === current ? "is-active" : ""}
+              onClick={() => update(code)}
+            >
+              <span className="code">{code.toUpperCase()}</span>
+              <span className="name">{labels[code]}</span>
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/SidebarToggle.tsx

@@ -0,0 +1,42 @@
+import { useEffect, useState } from "react";
+
+const STORAGE_KEY = "acta-sidebar";
+
+function readCollapsed(): boolean {
+  if (typeof window === "undefined") return false;
+  return window.localStorage.getItem(STORAGE_KEY) === "collapsed";
+}
+
+function applyCollapsed(collapsed: boolean): void {
+  document.documentElement.dataset.sidebar = collapsed ? "collapsed" : "expanded";
+}
+
+type Props = { labels: { collapse: string; expand: string } };
+
+export default function SidebarToggle({ labels }: Props) {
+  const [collapsed, setCollapsed] = useState(false);
+
+  useEffect(() => {
+    const initial = readCollapsed();
+    setCollapsed(initial);
+  }, []);
+
+  const toggle = () => {
+    const next = !collapsed;
+    setCollapsed(next);
+    window.localStorage.setItem(STORAGE_KEY, next ? "collapsed" : "expanded");
+    applyCollapsed(next);
+  };
+
+  return (
+    <button
+      type="button"
+      className="ui-sidebar-toggle"
+      aria-label={collapsed ? labels.expand : labels.collapse}
+      aria-pressed={collapsed}
+      onClick={toggle}
+    >
+      <span aria-hidden="true">{collapsed ? "›" : "‹"}</span>
+    </button>
+  );
+}