@ozdao/scriptorium 0.0.0-stage → 0.1.1

package/src/design-system/layout.scss

@@ -0,0 +1,416 @@
+// ============================================================================
+// Раскладка сайта документации: страница, сайдбар, оглавление, «Назад / Дальше»
+// ============================================================================
+// Шапку, сайдбар и мобильное меню рисует layoutClient martyrs; здесь —
+// визуальные пресеты наших компонентов и ширины колонок. Отступы — шкала
+// martyrs (--thin … --big), цвета — токены martyrs.
+
+// ---------------------------------------------------------------------------
+// Страница: содержимое + оглавление справа (≥960px, как у VitePress)
+// ---------------------------------------------------------------------------
+
+.docs-layout {
+  display: flex;
+  justify-content: center;
+  gap: var(--big);
+  padding: var(--medium) var(--medium) var(--big);
+}
+
+.docs-layout__content {
+  width: 100%;
+  max-width: var(--doc-content-width);
+  min-width: 0;
+}
+
+.docs-layout__outline {
+  display: none;
+  width: var(--doc-outline-width);
+  flex-shrink: 0;
+}
+
+@media (min-width: 960px) {
+  .docs-layout {
+    padding: var(--semi) var(--big) var(--big);
+  }
+
+  .docs-layout__outline {
+    display: block;
+  }
+}
+
+.docs-layout__top {
+  font-size: var(--fs-small);
+  color: rgb(var(--text-secondary));
+  background: transparent;
+  cursor: pointer;
+}
+
+// ---------------------------------------------------------------------------
+// Шапка: логотип-текст и ссылки nav
+// ---------------------------------------------------------------------------
+
+.docs-site-title {
+  font-size: var(--fs-semi);
+  color: rgb(var(--text-primary));
+}
+
+.docs-header-nav__link {
+  font-size: var(--fs-small);
+  color: rgb(var(--text-primary));
+  transition: color 0.2s ease;
+
+  &:hover,
+  &--active {
+    color: rgb(var(--doc-link));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Сайдбар: дерево папок
+// ---------------------------------------------------------------------------
+
+.docs-sidebar__list--nested {
+  padding-left: var(--regular);
+}
+
+.docs-sidebar__link {
+  display: block;
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: var(--thin) 0;
+  font-size: var(--fs-small);
+  line-height: 1.5;
+  text-align: left;
+  color: rgb(var(--text-secondary));
+  background: transparent;
+  cursor: pointer;
+  transition: color 0.2s ease;
+
+  &:hover {
+    color: rgb(var(--text-primary));
+  }
+
+  &--active,
+  &--active:hover {
+    color: rgb(var(--doc-link));
+  }
+}
+
+// Папка — узел дерева: подпись ярче страниц.
+.docs-sidebar__item--folder > .docs-sidebar__row > .docs-sidebar__link:not(.docs-sidebar__link--active) {
+  color: rgb(var(--text-primary));
+}
+
+.docs-sidebar__caret {
+  flex-shrink: 0;
+  width: var(--medium);
+  height: var(--medium);
+  background: transparent;
+  cursor: pointer;
+  border-radius: var(--thin);
+  transform: rotate(-90deg);
+  transition: transform 0.2s ease, background 0.2s ease;
+
+  &:hover {
+    background: rgb(var(--bg-hover));
+  }
+
+  &--open {
+    transform: none;
+  }
+}
+
+.docs-sidebar__nav {
+  padding-bottom: var(--medium);
+  border-bottom: 1px solid var(--border-subtle);
+}
+
+// ---------------------------------------------------------------------------
+// Переключатель темы (низ сайдбара)
+// ---------------------------------------------------------------------------
+
+.docs-theme-toggle {
+  border-top: 1px solid var(--border-subtle);
+}
+
+.docs-theme-toggle__button {
+  font-size: var(--fs-small);
+  color: rgb(var(--text-secondary));
+  background: transparent;
+  cursor: pointer;
+
+  &:hover {
+    background: rgb(var(--bg-hover));
+    color: rgb(var(--text-primary));
+  }
+}
+
+// Значок по теме <html>: светлая — солнце, тёмная (явная или системная) — луна.
+.docs-theme-toggle__icon--dark {
+  display: none;
+}
+
+:root[data-theme='dark'] {
+  .docs-theme-toggle__icon--dark { display: inline; }
+  .docs-theme-toggle__icon--light { display: none; }
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']) {
+    .docs-theme-toggle__icon--dark { display: inline; }
+    .docs-theme-toggle__icon--light { display: none; }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Оглавление страницы
+// ---------------------------------------------------------------------------
+
+.docs-outline {
+  position: sticky;
+  top: var(--semi);
+  padding-left: var(--regular);
+  border-left: 1px solid var(--border-subtle);
+}
+
+// Заголовок оглавления: кегль на ступень выше пунктов и отступ снизу, чтобы
+// читался как заголовок, а не как первый пункт списка.
+.docs-outline__label {
+  font-size: var(--fs-regular);
+  color: rgb(var(--text-primary));
+  margin-bottom: var(--small);
+}
+
+.docs-outline__link {
+  display: block;
+  font-size: var(--fs-small);
+  line-height: 1.5;
+  color: rgb(var(--text-secondary));
+  transition: color 0.2s ease;
+
+  &:hover {
+    color: rgb(var(--text-primary));
+  }
+
+  &--active,
+  &--active:hover {
+    color: rgb(var(--doc-link));
+  }
+}
+
+.docs-outline__level-1 {
+  padding-left: var(--regular);
+}
+
+.docs-outline__level-2 {
+  padding-left: var(--medium);
+}
+
+// ---------------------------------------------------------------------------
+// «Назад / Дальше»
+// ---------------------------------------------------------------------------
+
+.docs-prev-next {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  border-top: 1px solid var(--border-subtle);
+}
+
+.docs-prev-next__link {
+  border: 1px solid var(--border-subtle);
+  transition: border-color 0.2s ease;
+
+  &:hover {
+    border-color: rgb(var(--doc-link));
+  }
+
+  &--next {
+    text-align: right;
+  }
+}
+
+.docs-prev-next__label {
+  font-size: var(--fs-micro);
+  color: rgb(var(--text-secondary));
+}
+
+.docs-prev-next__title {
+  font-size: var(--fs-small);
+  color: rgb(var(--doc-link));
+}
+
+// ---------------------------------------------------------------------------
+// Поиск: кнопка в шапке (SearchButton) и окно (SearchBox на Popup martyrs)
+// ---------------------------------------------------------------------------
+
+.docs-search-button {
+  font-size: var(--fs-small);
+  color: rgb(var(--text-secondary));
+  background: rgb(var(--bg-card));
+  border: 1px solid transparent;
+  cursor: pointer;
+  transition: border-color 0.2s ease, color 0.2s ease;
+
+  &:hover {
+    border-color: rgb(var(--doc-link));
+    color: rgb(var(--text-primary));
+  }
+}
+
+.docs-search-button__keys {
+  font-family: var(--font);
+  font-size: var(--fs-small);
+  color: rgb(var(--text-muted));
+  border: 1px solid var(--border-subtle);
+}
+
+// Окно: ширина как у VitePress (до 900px), на телефоне — весь экран. Popup
+// ставит панели h-max-100 и o-y-scroll; здесь прокручивается только список
+// результатов, поэтому селектор сильнее одиночных JIT-классов.
+.popup-content.docs-search {
+  display: flex;
+  flex-direction: column;
+  width: min(100vw - 2 * var(--medium), 900px);
+  max-height: min(100vh - 2 * var(--big), 900px);
+  margin-top: var(--big);
+  overflow: hidden;
+  border: 1px solid var(--border-subtle);
+  color: rgb(var(--text-primary));
+}
+
+@media (max-width: 767px) {
+  .popup-content.docs-search {
+    width: 100vw;
+    height: 100vh;
+    max-height: none;
+    margin-top: 0;
+    border: none;
+    border-radius: 0;
+  }
+}
+
+.docs-search__shell {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.docs-search__bar {
+  flex-shrink: 0;
+  background: rgb(var(--bg-input));
+  border: 1px solid var(--border-subtle);
+  cursor: text;
+}
+
+.docs-search__icon {
+  flex-shrink: 0;
+  color: rgb(var(--text-muted));
+}
+
+.docs-search__input {
+  min-width: 0;
+  font-size: var(--fs-regular);
+  color: rgb(var(--text-primary));
+  background: transparent;
+  border: none;
+  outline: none;
+
+  &::placeholder {
+    color: rgb(var(--text-muted));
+  }
+
+  // Свой крестик браузера у type="search" — лишний: сброс делает кнопка рядом.
+  &::-webkit-search-cancel-button {
+    appearance: none;
+  }
+}
+
+.docs-search__reset {
+  flex-shrink: 0;
+  background: transparent;
+  cursor: pointer;
+
+  &:hover .docs-search__icon {
+    color: rgb(var(--doc-link));
+  }
+}
+
+.docs-search__results {
+  min-height: 0;
+  overflow-x: hidden;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+.docs-search__result {
+  font-size: var(--fs-small);
+  line-height: 1.5;
+  color: rgb(var(--text-secondary));
+  background: rgb(var(--bg-card));
+  border: 1px solid transparent;
+  outline: none;
+
+  &--selected {
+    color: rgb(var(--text-primary));
+    border-color: rgb(var(--doc-link));
+  }
+}
+
+.docs-search__hash {
+  flex-shrink: 0;
+  color: rgb(var(--doc-link));
+  opacity: 0.6;
+}
+
+.docs-search__title--main {
+  color: rgb(var(--text-primary));
+}
+
+.docs-search__separator {
+  color: rgb(var(--text-muted));
+}
+
+.docs-search__mark {
+  color: rgb(var(--text-primary));
+  background: rgba(var(--doc-link), 0.25);
+  border-radius: var(--thin);
+}
+
+.docs-search__result--selected .docs-search__title--main {
+  color: rgb(var(--doc-link));
+}
+
+.docs-search__empty {
+  font-size: var(--fs-small);
+  color: rgb(var(--text-secondary));
+}
+
+.docs-search__keys {
+  flex-shrink: 0;
+  font-size: var(--fs-small);
+  color: rgb(var(--text-muted));
+}
+
+.docs-search__key {
+  min-width: var(--medium);
+  padding: 0 var(--thin);
+  font-family: var(--font);
+  text-align: center;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--thin);
+  background: rgb(var(--bg-card));
+}
+
+// ---------------------------------------------------------------------------
+// 404
+// ---------------------------------------------------------------------------
+
+.docs-not-found {
+  max-width: var(--doc-content-width);
+  margin: 0 auto;
+  text-align: center;
+  align-items: center;
+}
+
+.docs-not-found__home {
+  color: rgb(var(--doc-link));
+}

package/src/design-system/theme.scss

@@ -0,0 +1,45 @@
+// ============================================================================
+// Scriptorium — тема сайта документации
+// ============================================================================
+// База и UI-кит дизайн-системы martyrs здесь НЕ импортятся: они приходят через
+// JS-энтрипоинт '@ozdao/martyrs/design-system' в ./index.js (до
+// этой темы). Цвета и тёмная/светлая темы — токены martyrs (brand.scss:
+// --text-*, --bg-*, --border-*, --color-*), переключение — data-theme на :root.
+// Здесь только то, чего в martyrs нет: шрифты сайта, ширины колонок
+// документации и кегли содержимого.
+
+:root {
+  --font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  --font-main: var(--font);
+  --font-second: var(--font);
+  --font-mono: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, 'Liberation Mono', monospace;
+
+  // Ширины колонок — как у VitePress: содержимое до 688px, оглавление 224px
+  // (сайдбар 272px задаёт w-17r в meta роута).
+  --doc-content-width: 688px;
+  --doc-outline-width: 224px;
+
+  // Заголовки содержимого: шкала h1–h5 martyrs рассчитана на лендинги и для
+  // текста документации крупна.
+  --doc-h1: 2rem;
+  --doc-h2: var(--fs-extra);
+  --doc-h3: var(--fs-semi);
+  --doc-h4: var(--fs-medium);
+
+  // Ссылки в тексте: синий акцент martyrs читается и на светлом, и на тёмном фоне.
+  --doc-link: var(--color-accent-secondary);
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  font-family: var(--font);
+  background: rgb(var(--bg-base));
+  color: rgb(var(--text-primary));
+  min-height: 100vh;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}

package/src/localization/index.js

@@ -0,0 +1,27 @@
+import { createI18n } from 'vue-i18n';
+import { i18nManager } from '@ozdao/martyrs/modules/core/client';
+
+import site_config from '../configs/site.config.js';
+
+// Язык сайта один — из config.lang потребителя ('ru-RU' → 'ru'). Языковых
+// префиксов в адресах нет: адреса страниц повторяют папки репозитория.
+// Словарь — только интерфейс martyrs (core.*, его регистрирует core.app.js);
+// мета-теги страницы — в app.messages (configs/client.config.js).
+const locale = site_config.locale;
+
+export function getLocales() {
+  i18nManager.setSupportedLocales({ [locale]: locale.toUpperCase() });
+  i18nManager.setDefaultLocale(locale);
+
+  return createI18n({
+    legacy: false,
+    locale,
+    // Интерфейс martyrs (core.*) переведён на en и ru: для другого языка сайта
+    // его подписи берутся английскими.
+    fallbackLocale: [locale, 'en'],
+    messages: i18nManager.getAllMessages(),
+    globalInjection: true,
+    availableLocales: [locale],
+    pluralRules: i18nManager.pluralRules,
+  });
+}

package/src/main.js

@@ -0,0 +1,8 @@
+// Публичный API пакета для темы потребителя: import { Badge, useDocs } from '@ozdao/scriptorium'.
+// Файл собирается бандлом сайта (алиас '@docs-theme' ставит bin/scriptorium.js),
+// поэтому импортировать его можно только из documentation/ потребителя.
+export { default as Badge } from './components/Badge.vue';
+export { default as ThemeToggle } from './components/ThemeToggle.vue';
+export { default as SearchButton } from './components/SearchButton.vue';
+export { default as SearchBox } from './components/SearchBox.vue';
+export { useDocs } from './content/use-docs.js';

package/src/router/index.js

@@ -0,0 +1,101 @@
+import {
+  createRouter,
+  createMemoryHistory,
+  createWebHistory,
+} from 'vue-router';
+
+import { scrollBehavior, layoutClient, Header, Sidebar } from '@ozdao/martyrs/modules/core/client';
+
+import theme from '@docs-theme/theme/index.js';
+
+import { findPage, openPage } from '../content/current-page.js';
+
+import Page from '../components/Page.vue';
+import SidebarTree from '../components/SidebarTree.vue';
+import HeaderNav from '../components/HeaderNav.vue';
+import ThemeToggle from '../components/ThemeToggle.vue';
+import SiteTitle from '../components/SiteTitle.vue';
+
+// Имя 'Home' у корневого роута обязательно: core.app.js вешает на него
+// заглушки backoffice/organizations/users через router.addRoute('Home', ...).
+// Раскладка — layoutClient martyrs: шапка, сайдбар и мобильное меню задаются
+// meta роута. Все страницы документации — один дочерний роут на Page.vue.
+const routes = [{
+  path: '/',
+
+  components: {
+    default: layoutClient,
+  },
+
+  name: 'Home',
+
+  meta: {
+    // Один ключ раскладки на все страницы сайта: Client.vue martyrs ключует
+    // router-view по route.meta.layoutKey (иначе по route.name), и при смене
+    // ключа проигрывает scaleTransition с лоадером в паузе. Главная и остальные
+    // страницы — разные маршруты (Index / Page), без общего ключа переход между
+    // ними шёл с анимацией поверх уже подменённого содержимого.
+    layoutKey: 'docs',
+    header: Header,
+    // Логотип потребителя (theme.Logo) вместо текстового заголовка.
+    logotype: theme?.Logo ?? SiteTitle,
+    location: false,
+    header_show_profile: false,
+    header_show_notifications: false,
+    header_right_component: HeaderNav,
+
+    sidebar: Sidebar,
+    sidebar_navigation: SidebarTree,
+    sidebar_bottom_component: ThemeToggle,
+    // 272px, как у VitePress.
+    sidebar_width: 'w-17r',
+    // На десктопе сайдбар открыт всегда; на мобильном он выезжает по кнопке меню.
+    sidebarOpenOnEnter: true,
+  },
+
+  children: [{
+    // Главная ('/'): без пустого ребёнка адрес '/' достаётся самому 'Home' —
+    // статичный путь весит больше catch-all ниже, и страница не рендерится.
+    path: '',
+    name: 'Index',
+    component: Page,
+  }, {
+    // Любой адрес: страницу по нему ищет гард ниже. Core martyrs добавляет свой
+    // catch-all (NotFound) позже — при равном весе пути побеждает объявленный раньше.
+    path: ':path(.*)*',
+    name: 'Page',
+    component: Page,
+  }],
+}];
+
+export function getRouter(context) {
+  const router = createRouter({
+    routes,
+    // История — на каждый вызов: в SSR getRouter зовётся на каждый запрос,
+    // общая memory-история смешала бы навигацию разных запросов.
+    history: typeof window === 'undefined' ? createMemoryHistory() : createWebHistory(),
+    scrollBehavior: scrollBehavior(),
+  });
+
+  // Страница грузится до рендера: на сервере — внутри router.push запроса, на
+  // клиенте — до гидратации (router.isReady) и до каждого перехода. Стор —
+  // стор этого запроса из контекста.
+  router.beforeResolve(async (to) => {
+    const state = context.store.core.state;
+    const { page, redirect_url } = findPage(to.path);
+
+    if (redirect_url) return { path: redirect_url, query: to.query, hash: to.hash, replace: true };
+
+    if (!page) {
+      state.docs = null;
+      // 404 в ответе сервера: vue-app-renderer martyrs берёт статус из notFound.
+      state.notFound = true;
+      return;
+    }
+
+    state.docs = await openPage(page);
+    state.notFound = false;
+  });
+
+  return router;
+}

package/src/router/links.js

@@ -0,0 +1,56 @@
+// Переходы по обычным <a> внутри сайта — роутером, как у VitePress: HTML
+// страниц (markdown) и компоненты темы потребителя (логотип, PageMeta) пишут
+// ссылки тегом <a>, и без перехвата каждый клик перезагружал бы страницу.
+// Якорь на текущей странице прокручивает скроллер раскладки martyrs (#scrollview).
+import { findPage } from '../content/current-page.js';
+
+// Прокрутка к заголовку внутри #scrollview: окно документа у раскладки martyrs
+// не скроллится, скроллится этот контейнер. Отступ — чтобы заголовок не лип к краю.
+export function scrollToAnchor(id, behavior = 'smooth') {
+  const scrollview = document.getElementById('scrollview');
+  const target = document.getElementById(id);
+  if (!scrollview || !target) return false;
+
+  const top = target.getBoundingClientRect().top - scrollview.getBoundingClientRect().top + scrollview.scrollTop;
+  scrollview.scrollTo({ top: Math.max(top - 24, 0), behavior });
+  return true;
+}
+
+function decodeHash(hash) {
+  try {
+    return decodeURIComponent(hash.slice(1));
+  } catch {
+    return hash.slice(1);
+  }
+}
+
+export function interceptLinks(router) {
+  document.addEventListener('click', (event) => {
+    if (event.defaultPrevented || event.button !== 0) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+
+    const link = event.target.closest?.('a[href]');
+    if (!link || link.hasAttribute('download')) return;
+    if (link.target && link.target !== '_self') return;
+
+    const url = new URL(link.href, window.location.href);
+    if (url.origin !== window.location.origin) return;
+
+    const same_page = url.pathname === window.location.pathname && url.search === window.location.search;
+    if (same_page && url.hash) {
+      // Якорь текущей страницы: прокрутка и адрес с якорем без новой навигации.
+      event.preventDefault();
+      scrollToAnchor(decodeHash(url.hash));
+      window.history.replaceState(window.history.state, '', url.hash);
+      return;
+    }
+
+    // Роутером — только страницы сайта. Ссылка на файл (картинка, PDF, статика
+    // из public) уходит браузеру как есть.
+    const { page, redirect_url } = findPage(url.pathname);
+    if (!page && !redirect_url) return;
+
+    event.preventDefault();
+    router.push(url.pathname + url.search + url.hash);
+  });
+}