@ozdao/scriptorium 0.0.0-stage → 0.1.0

package/src/content/sidebar.js

@@ -0,0 +1,99 @@
+// Дерево сайдбара из списка страниц — правила прежнего сайта (vitepress-sidebar
+// 1.40.0 + arrangeSidebar из .vitepress/config.mts):
+//  - папка = узел с подписью-именем папки, страница = пункт с подписью title;
+//  - порядок внутри папки: имена по возрастанию (обычный sort по кодам символов,
+//    как у vitepress-sidebar: заглавные раньше строчных), затем sidebar.priority
+//    выносит перечисленные имена вперёд в своём порядке; при folders_to_bottom
+//    папки идут после файлов;
+//  - AGENTS.md папки отдаёт ей свою ссылку и отдельным пунктом не показывается;
+//    корневой AGENTS.md — «Обзор» в шапке, в сайдбаре его нет;
+//  - папки из sidebar.hidden (по имени, на любой глубине) — страницы сайта, но
+//    не пункты сайдбара;
+//  - папка глубины collapse_depth и глубже изначально свёрнута.
+//
+// Узел: { text, url?, items?, collapsed }. url папки — адрес её AGENTS.md.
+
+function isFolderIndex(file_name) {
+  return file_name === 'AGENTS.md' || file_name === 'index.md';
+}
+
+function prioritize(names, priority) {
+  const rank = new Map(priority.map((name, index) => [name, index]));
+  const first = names.filter((name) => rank.has(name)).sort((a, b) => rank.get(a) - rank.get(b));
+  return [...first, ...names.filter((name) => !rank.has(name))];
+}
+
+function folderTree(pages, hidden) {
+  const root = { folders: new Map(), files: new Map() };
+
+  for (const page of pages) {
+    const parts = page.file.split('/');
+    const file_name = parts.pop();
+    if (parts.some((part) => hidden.includes(part))) continue;
+
+    let folder = root;
+    for (const part of parts) {
+      if (!folder.folders.has(part)) folder.folders.set(part, { folders: new Map(), files: new Map() });
+      folder = folder.folders.get(part);
+    }
+    folder.files.set(file_name, page);
+  }
+
+  return root;
+}
+
+function folderItems(folder, depth, options) {
+  const names = prioritize([...folder.files.keys(), ...folder.folders.keys()].sort(), options.priority);
+  const items = [];
+
+  for (const name of names) {
+    if (folder.files.has(name)) {
+      if (isFolderIndex(name)) continue;
+      const page = folder.files.get(name);
+      items.push({ text: page.title, url: page.url });
+      continue;
+    }
+
+    const sub_folder = folder.folders.get(name);
+    const index_page = sub_folder.files.get('AGENTS.md') || sub_folder.files.get('index.md');
+    const children = folderItems(sub_folder, depth + 1, options);
+
+    if (!index_page && children.length === 0) continue;
+
+    items.push({
+      text: name,
+      folder: true,
+      ...(index_page ? { url: index_page.url } : {}),
+      ...(children.length ? { items: children, collapsed: depth >= options.collapse_depth } : {}),
+    });
+  }
+
+  if (!options.folders_to_bottom) return items.map(({ folder, ...item }) => item);
+
+  return [
+    ...items.filter((item) => !item.folder),
+    ...items.filter((item) => item.folder),
+  ].map(({ folder, ...item }) => item);
+}
+
+export function buildSidebar(pages, config) {
+  const { priority, folders_to_bottom, collapse_depth, hidden } = config.sidebar;
+  return folderItems(folderTree(pages, hidden), 1, { priority, folders_to_bottom, collapse_depth });
+}
+
+// Плоский порядок ссылок сайдбара для «Назад / Дальше»: ссылка папки идёт
+// перед её содержимым.
+export function flattenSidebar(items) {
+  const links = [];
+  for (const item of items) {
+    if (item.url) links.push({ text: item.text, url: item.url });
+    if (item.items) links.push(...flattenSidebar(item.items));
+  }
+  return links;
+}
+
+// Есть ли среди потомков узла текущая страница — такие папки раскрыты.
+export function containsUrl(item, url) {
+  if (item.url === url) return true;
+  return Boolean(item.items?.some((child) => containsUrl(child, url)));
+}

package/src/content/site-config.js

@@ -0,0 +1,95 @@
+// Конфиг сайта потребителя (documentation/config.js) → полный конфиг
+// с умолчаниями. Чистая функция без node-импортов: её зовут и сборка (loader'ы
+// в node), и бандл сайта (configs/site.config.js), и умолчания обязаны совпадать,
+// иначе сайдбар и список страниц разойдутся.
+
+const default_labels = {
+  menu: 'Menu',
+  theme: 'Appearance',
+  top: 'Return to top',
+  prev: 'Previous page',
+  next: 'Next page',
+  // Страница 404 — подписи как у VitePress.
+  not_found: 'Page not found',
+  home: 'Take me home',
+  // Поиск (SearchButton, SearchBox) — подписи как у локального поиска VitePress.
+  search: {
+    button: 'Search',
+    placeholder: 'Search docs',
+    no_results: 'No results for',
+    reset: 'Reset search',
+    select: 'to select',
+    navigate: 'to navigate',
+    close: 'to close',
+  },
+};
+
+const appearances = ['dark', 'light', 'auto'];
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function stringList(value, field) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    throw new TypeError(`[scriptorium] documentation/config.js: ${field} — ожидается массив строк`);
+  }
+  return value;
+}
+
+export function resolveSiteConfig(raw) {
+  if (!isObject(raw)) {
+    throw new TypeError('[scriptorium] documentation/config.js должен отдавать объект (export default { ... })');
+  }
+
+  const appearance = raw.appearance ?? 'dark';
+  if (!appearances.includes(appearance)) {
+    throw new TypeError(`[scriptorium] documentation/config.js: appearance "${appearance}" — допустимо ${appearances.join(', ')}`);
+  }
+
+  const nav = raw.nav ?? [];
+  if (!Array.isArray(nav) || nav.some((item) => !isObject(item) || typeof item.text !== 'string' || typeof item.link !== 'string')) {
+    throw new TypeError('[scriptorium] documentation/config.js: nav — ожидается массив { text, link }');
+  }
+
+  const sidebar = isObject(raw.sidebar) ? raw.sidebar : {};
+  const outline = isObject(raw.outline) ? raw.outline : {};
+  const level = outline.level ?? [2, 3];
+  if (!Array.isArray(level) || level.length !== 2 || level.some((entry) => !Number.isInteger(entry))) {
+    throw new TypeError('[scriptorium] documentation/config.js: outline.level — ожидается [от, до], например [2, 3]');
+  }
+
+  const labels = isObject(raw.labels) ? raw.labels : {};
+
+  const lang = raw.lang ?? 'en-US';
+
+  return {
+    title: raw.title ?? 'Documentation',
+    description: raw.description ?? '',
+    lang,
+    // Язык интерфейса martyrs (vue-i18n) — первая часть кода: 'ru-RU' → 'ru'.
+    locale: lang.split('-')[0].toLowerCase(),
+    appearance,
+    skipped_names: stringList(raw.skipped_names, 'skipped_names'),
+    skipped_paths: stringList(raw.skipped_paths, 'skipped_paths'),
+    nav,
+    sidebar: {
+      priority: stringList(sidebar.priority, 'sidebar.priority'),
+      folders_to_bottom: sidebar.folders_to_bottom ?? true,
+      collapse_depth: sidebar.collapse_depth ?? 2,
+      hidden: stringList(sidebar.hidden, 'sidebar.hidden'),
+    },
+    outline: {
+      level,
+      label: outline.label ?? 'On this page',
+    },
+    // labels.search — вложенный объект: сливается отдельно, иначе частичный
+    // блок потребителя затёр бы остальные подписи поиска.
+    labels: {
+      ...default_labels,
+      ...labels,
+      search: { ...default_labels.search, ...(isObject(labels.search) ? labels.search : {}) },
+    },
+  };
+}

package/src/content/use-docs.js

@@ -0,0 +1,21 @@
+// Данные сайта для компонентов темы потребителя (аналог useData у VitePress):
+//   page        — открытая страница { url, file, title, frontmatter, headers } или null (404);
+//   frontmatter — её frontmatter ({} на 404);
+//   config      — конфиг сайта с умолчаниями;
+//   pages       — все страницы сайта { url, file, title, frontmatter }.
+// Открытая страница живёт в сторе запроса (store.core.state.docs): её ставит
+// гард роутера, сервер отдаёт в data-state, клиент гидрирует. config и pages —
+// константы сборки, в стор их класть незачем.
+import { computed } from 'vue';
+import { useStore } from '@ozdao/martyrs/modules/core/client';
+
+import site_config from '../configs/site.config.js';
+import { pages } from './pages.js';
+
+export function useDocs() {
+  const store = useStore();
+  const page = computed(() => store.core.state.docs ?? null);
+  const frontmatter = computed(() => page.value?.frontmatter ?? {});
+
+  return { page, frontmatter, config: site_config, pages };
+}

package/src/design-system/doc.scss

@@ -0,0 +1,257 @@
+// ============================================================================
+// Содержимое страницы документации (.doc) — HTML из markdown.loader.js
+// ============================================================================
+// Reset martyrs снимает браузерные отступы и маркеры списков — здесь они
+// возвращаются для текста документации. Цвета — токены martyrs, отступы —
+// шкала martyrs, кегли — --fs-* и --doc-h*.
+
+.doc {
+  font-size: var(--fs-regular);
+  line-height: 1.75;
+  color: rgb(var(--text-primary));
+  overflow-wrap: break-word;
+
+  > :first-child {
+    margin-top: 0;
+  }
+
+  // ---- Заголовки ----
+
+  h1, h2, h3, h4, h5, h6 {
+    position: relative;
+    font-family: var(--font-main);
+    line-height: 1.3;
+    letter-spacing: 0;
+    scroll-margin-top: var(--medium);
+  }
+
+  h1 {
+    font-size: var(--doc-h1);
+    margin-bottom: var(--medium);
+  }
+
+  h2 {
+    font-size: var(--doc-h2);
+    margin-top: var(--big);
+    margin-bottom: var(--medium);
+    padding-top: var(--medium);
+    border-top: 1px solid var(--border-subtle);
+  }
+
+  h3 {
+    font-size: var(--doc-h3);
+    margin-top: var(--semi);
+    margin-bottom: var(--regular);
+  }
+
+  h4, h5, h6 {
+    font-size: var(--doc-h4);
+    margin-top: var(--medium);
+    margin-bottom: var(--small);
+  }
+
+  // Якорь заголовка: виден при наведении, стоит слева от текста, как у VitePress.
+  .header-anchor {
+    position: absolute;
+    left: 0;
+    margin-left: -0.87em;
+    color: rgb(var(--doc-link));
+    opacity: 0;
+    text-decoration: none;
+    transition: opacity 0.2s ease;
+  }
+
+  h1:hover .header-anchor,
+  h2:hover .header-anchor,
+  h3:hover .header-anchor,
+  h4:hover .header-anchor,
+  h5:hover .header-anchor,
+  h6:hover .header-anchor,
+  .header-anchor:focus {
+    opacity: 1;
+  }
+
+  // ---- Текст ----
+
+  p, ul, ol, blockquote, table, pre, details, .custom-block {
+    margin: var(--regular) 0;
+  }
+
+  p {
+    font-size: inherit;
+    line-height: inherit;
+  }
+
+  a {
+    color: rgb(var(--doc-link));
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    transition: opacity 0.2s ease;
+
+    &:hover {
+      opacity: 0.8;
+    }
+  }
+
+  strong {
+    color: rgb(var(--text-primary));
+  }
+
+  hr {
+    margin: var(--semi) 0;
+    border: none;
+    border-top: 1px solid var(--border-subtle);
+  }
+
+  img {
+    max-width: 100%;
+    height: auto;
+  }
+
+  // ---- Списки ----
+
+  ul, ol {
+    padding-left: var(--medium);
+  }
+
+  ul {
+    list-style: disc;
+  }
+
+  ol {
+    list-style: decimal;
+  }
+
+  // reset martyrs ставит list-style: none на сам li — маркер берём у списка.
+  li {
+    list-style: inherit;
+  }
+
+  li + li {
+    margin-top: var(--thin);
+  }
+
+  li > ul, li > ol {
+    margin: var(--thin) 0 0;
+  }
+
+  // ---- Цитата ----
+
+  blockquote {
+    padding-left: var(--regular);
+    border-left: 2px solid var(--border-strong);
+    color: rgb(var(--text-secondary));
+  }
+
+  // ---- Таблицы (блок .table martyrs + прокрутка широких) ----
+
+  table {
+    display: block;
+    width: 100%;
+    overflow-x: auto;
+    border-collapse: collapse;
+    font-size: var(--fs-small);
+  }
+
+  th, td {
+    padding: var(--thin) var(--regular);
+    border: 1px solid var(--border-subtle);
+    text-align: left;
+    vertical-align: top;
+  }
+
+  th {
+    background: rgb(var(--bg-card));
+  }
+
+  tr:nth-child(2n) td {
+    background: rgba(var(--bg-card), 0.5);
+  }
+
+  // ---- Код ----
+
+  code {
+    font-family: var(--font-mono);
+    font-size: 0.875em;
+  }
+
+  :not(pre) > code {
+    padding: 0.15em 0.4em;
+    border-radius: var(--thin);
+    background: rgb(var(--bg-card));
+    color: rgb(var(--text-primary));
+  }
+
+  a > code {
+    color: inherit;
+  }
+
+  pre {
+    padding: var(--regular) var(--medium);
+    border-radius: var(--small);
+    background: rgb(var(--bg-card));
+    overflow-x: auto;
+    line-height: 1.6;
+    font-size: var(--fs-small);
+
+    code {
+      font-size: inherit;
+    }
+  }
+
+  // ---- Блоки ::: tip / info / warning / danger / details ----
+
+  .custom-block {
+    --block-rgb: var(--text-muted);
+    padding: var(--small) var(--regular);
+    border-radius: var(--small);
+    background: rgba(var(--block-rgb), 0.12);
+    border: 1px solid rgba(var(--block-rgb), 0.3);
+
+    > :first-child { margin-top: 0; }
+    > :last-child { margin-bottom: 0; }
+
+    p { margin: var(--thin) 0; }
+  }
+
+  .custom-block-title {
+    color: rgb(var(--block-rgb));
+  }
+
+  .info { --block-rgb: var(--text-muted); }
+  .tip { --block-rgb: var(--color-accent-secondary); }
+  .warning { --block-rgb: var(--color-warning); }
+  .danger { --block-rgb: var(--color-negative); }
+
+  details.custom-block summary {
+    cursor: pointer;
+    color: rgb(var(--text-primary));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Подсветка кода shiki: две темы в CSS-переменных (--shiki-light / --shiki-dark),
+// фон — поверхность martyrs, а не фон темы подсветки. Тёмная — по data-theme
+// на :root и по системной теме, пока выбора не было (как тема martyrs).
+// ---------------------------------------------------------------------------
+
+.shiki,
+.shiki span {
+  color: var(--shiki-light);
+}
+
+:root[data-theme='dark'] {
+  .shiki,
+  .shiki span {
+    color: var(--shiki-dark);
+  }
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']) {
+    .shiki,
+    .shiki span {
+      color: var(--shiki-dark);
+    }
+  }
+}

package/src/design-system/index.js

@@ -0,0 +1,19 @@
+// ============================================================================
+// Дизайн-система сайта документации — единая точка подключения
+// ============================================================================
+// client.js импортирует только эту папку.
+//
+// Порядок важен: база дизайн-системы martyrs (слои @layer) → JIT-утилиты
+// (unlayered, бьют слои) → тема сайта (unlayered, последняя — бьёт всё).
+// Тема потребителя (documentation/theme/style.scss) подключается позже, через
+// роутер, и перекрывает эту.
+//
+// Состав папки:
+//   theme.scss   — токены сайта: шрифты, ширины колонок, кегли содержимого
+//   layout.scss  — шапка, сайдбар, оглавление, «Назад / Дальше»
+//   doc.scss     — типографика содержимого страницы (.doc) и подсветка кода
+import '@ozdao/martyrs/design-system';
+import 'martyrs-jit.css';
+import './theme.scss';
+import './layout.scss';
+import './doc.scss';