@terrafirmagreg-team/ui 0.0.0-stage → 0.1.0

package/src/lib/utils/merge-refs.ts

@@ -0,0 +1,13 @@
+import type * as React from 'react';
+
+export function mergeRefs<T>(...refs: (React.Ref<T> | undefined)[]): React.RefCallback<T> {
+  return (value) => {
+    refs.forEach((ref) => {
+      if (typeof ref === 'function') {
+        ref(value);
+      } else if (ref) {
+        ref.current = value;
+      }
+    });
+  };
+}

package/src/lib/utils/nav-active.ts

@@ -0,0 +1,58 @@
+import type * as PageTree from '@terrafirmagreg-team/translate/types/tree';
+
+export type NavItemMatch = (url: string) => boolean;
+
+function sameValue(want: string, have: string | null): boolean {
+  return have === want;
+}
+
+export function isNavItemActive(
+  href: string,
+  pathname: string,
+  search: string,
+  navKeys?: ReadonlySet<string>,
+  nested = false,
+) {
+  const q = href.indexOf('?');
+  const query = q >= 0 ? href.slice(q + 1) : undefined;
+  let path = q >= 0 ? href.slice(0, q) : href;
+  if (path.length > 1 && path.endsWith('/')) path = path.slice(0, -1);
+  if (pathname.length > 1 && pathname.endsWith('/'))
+    pathname = pathname.slice(0, -1);
+  if (path !== pathname && !(nested && pathname.startsWith(`${path}/`)))
+    return false;
+  const want = new URLSearchParams(query ?? '');
+  const have = new URLSearchParams(search);
+  const keys = new Set<string>();
+  for (const key of want.keys()) keys.add(key);
+  for (const key of have.keys()) if (navKeys?.has(key)) keys.add(key);
+  for (const key of keys) {
+    const wantValue = want.get(key);
+    if (wantValue === null) return false;
+    if (!sameValue(wantValue, have.get(key))) return false;
+  }
+  return true;
+}
+
+export function hasActiveDescendant(
+  node: PageTree.Node,
+  match: NavItemMatch,
+): boolean {
+  if (node.type === 'page') return match(node.url);
+  if (node.type === 'folder') {
+    return (
+      (node.index !== undefined && match(node.index.url)) ||
+      node.children.some((child) => hasActiveDescendant(child, match))
+    );
+  }
+  return false;
+}
+
+export function langScopeKey(
+  id: string | undefined,
+  languages: readonly string[],
+) {
+  for (const lang of languages)
+    id = id?.replaceAll(`:${lang}`, '').replaceAll(`/${lang}`, '');
+  return id;
+}

package/src/lib/utils/stored-value.ts

@@ -0,0 +1,136 @@
+'use client';
+
+import { useCallback, useSyncExternalStore } from 'react';
+
+export type StoredCodec<T> = {
+  read: (raw: string | null) => T;
+  write: (value: T) => string;
+};
+
+const listenersByKey = new Map<string, Set<() => void>>();
+const memoryByKey = new Map<string, string>();
+
+export function subscribeStoredValue(
+  key: string,
+  onChange: () => void,
+): () => void {
+  let set = listenersByKey.get(key);
+  if (!set) {
+    set = new Set();
+    listenersByKey.set(key, set);
+  }
+  set.add(onChange);
+  const onStorage = (event: StorageEvent) => {
+    if (event.key === null || event.key === key) onChange();
+  };
+  window.addEventListener('storage', onStorage);
+  return () => {
+    set.delete(onChange);
+    window.removeEventListener('storage', onStorage);
+  };
+}
+
+export function readStoredValue<T>(
+  key: string,
+  read: (raw: string | null) => T,
+): T {
+  const memory = memoryByKey.get(key) ?? null;
+  try {
+    return read(memory ?? localStorage.getItem(key));
+  } catch {
+    return read(memory);
+  }
+}
+
+export function writeStoredValue<T>(
+  key: string,
+  value: T,
+  write: (v: T) => string,
+) {
+  const raw = write(value);
+  try {
+    localStorage.setItem(key, raw);
+    memoryByKey.delete(key);
+  } catch {
+    memoryByKey.set(key, raw);
+  }
+  for (const listener of listenersByKey.get(key) ?? []) listener();
+}
+
+export function createStoredValue<T>(key: string, codec: StoredCodec<T>) {
+  let cache: { raw: string | null; value: T } | undefined;
+  const fallback = codec.read(null);
+
+  const getSnapshot = (): T => {
+    let raw: string | null = memoryByKey.get(key) ?? null;
+    if (raw === null) {
+      try {
+        raw = localStorage.getItem(key);
+      } catch {
+
+      }
+    }
+    if (cache?.raw === raw) return cache.value;
+    try {
+      const value = codec.read(raw);
+      cache = { raw, value };
+      return value;
+    } catch {
+      return fallback;
+    }
+  };
+
+  return function useStoredValue() {
+    const value = useSyncExternalStore(
+      (onChange) => subscribeStoredValue(key, onChange),
+      getSnapshot,
+      () => fallback,
+    );
+    const set = useCallback((next: T | ((prev: T) => T)) => {
+      const value =
+        typeof next === 'function' ? (next as (p: T) => T)(getSnapshot()) : next;
+      writeStoredValue(key, value, codec.write);
+    }, []);
+    return [value, set] as const;
+  };
+}
+
+export function boolCodec(defaultValue: boolean): StoredCodec<boolean> {
+  return {
+    read: (raw) => (raw == null ? defaultValue : raw !== '0' && raw !== 'false'),
+    write: (value) => (value ? '1' : '0'),
+  };
+}
+
+export function literalCodec<T extends string>(
+  values: readonly T[],
+  defaultValue: T,
+): StoredCodec<T> {
+  return {
+    read: (raw) =>
+      raw != null && (values as readonly string[]).includes(raw)
+        ? (raw as T)
+        : defaultValue,
+    write: (value) => value,
+  };
+}
+
+export function jsonCodec<T>(defaultValue: T): StoredCodec<T> {
+  return {
+    read: (raw) => (raw == null ? defaultValue : (JSON.parse(raw) as T)),
+    write: (value) => JSON.stringify(value),
+  };
+}
+
+export function numberCodec(
+  defaultValue: number,
+  min: number,
+  max: number,
+): StoredCodec<number> {
+  const clamp = (value: number) =>
+    Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : defaultValue;
+  return {
+    read: (raw) => (raw == null ? defaultValue : clamp(Number(raw))),
+    write: (value) => String(clamp(value)),
+  };
+}

package/src/lib/utils/urls.ts

@@ -0,0 +1,17 @@
+export function safeURL(value?: string): string | undefined {
+  // oxlint-disable-next-line no-control-regex
+  if (!value || /[\u0000-\u0020\\]/.test(value)) return undefined;
+  return /^(https?:\/\/|\/(?!\/)|#)/i.test(value) ? value : undefined;
+}
+
+export function normalize(urlOrPath: string) {
+  if (urlOrPath.length > 1 && urlOrPath.endsWith('/')) return urlOrPath.slice(0, -1);
+  return urlOrPath;
+}
+
+export function isActive(href: string, pathname: string, nested = false): boolean {
+  href = normalize(href);
+  pathname = normalize(pathname);
+
+  return href === pathname || (nested && pathname.startsWith(`${href}/`));
+}

package/src/locales/en_us.json

@@ -0,0 +1,119 @@
+{
+  "ui": {
+    "on_this_page": "On this page",
+    "search_trigger": "Search",
+    "search_dialog": "Search",
+    "search_empty": "No results found",
+    "choose_language": "Choose a language",
+    "last_updated": "Last updated on",
+    "copy_markdown": "Copy Markdown",
+    "open_github": "Open in GitHub",
+    "open": "Open",
+    "next_page": "Next Page",
+    "prev_page": "Previous Page",
+    "edit_github": "Edit on GitHub",
+    "copied_markdown": "Copied Markdown",
+    "sidebar_open": "Open Sidebar",
+    "sidebar_close": "Close Sidebar",
+    "sidebar_collapse": "Collapse Sidebar",
+    "no_headings": "No Headings",
+    "copy_anchor": "Copy Anchor Link",
+    "copied_anchor": "Copied Anchor Link",
+    "search_close": "Close Search",
+    "search_failed": "Search failed",
+    "search_failed_results": "Search failed, showing results for {query}",
+    "open_search": "Open Search",
+    "menu_toggle": "Toggle Menu",
+    "theme_light": "Light",
+    "theme_dark": "Dark",
+    "theme_system": "System",
+    "banner_close": "Close Banner",
+    "copy_link": "Copy Link",
+    "copied_link": "Copied Link",
+    "close": "Close",
+    "next_image": "Next Image",
+    "prev_image": "Previous Image",
+    "image_viewer": "Image Viewer",
+    "copy_text": "Copy Text",
+    "copied_text": "Copied Text",
+    "type": "Type",
+    "default": "Default",
+    "parameters": "Parameters",
+    "prop": "Prop",
+    "returns": "Returns",
+    "readability": {
+      "menu": "Readability",
+      "layout": "Layout",
+      "layout.unavailable": "Layout switch is not available on small screens",
+      "layout.help": "Adjust the site layout to fit different reading needs and screens",
+      "layout.full": "Expand all",
+      "layout.full.help": "The article takes the full panel width; the sidebar stays at the screen edge",
+      "layout.sidebar": "Adjustable page width",
+      "layout.sidebar.help": "The slider narrows the whole page block — the sidebar moves with it",
+      "layout.both": "Adjustable page and content",
+      "layout.both.help": "Both sliders apply: page block width and the text column inside",
+      "layout.original": "Original width",
+      "layout.original.help": "Default centered page width",
+      "page_width": "Page width",
+      "page_width.help": "Adjust the maximum width of the page layout to fit different reading needs and screens",
+      "page_width.slider": "Page width slider",
+      "page_width.slider.help": "A ranged slider to choose the maximum width of the page layout",
+      "content_width": "Content width",
+      "content_width.help": "Adjust the maximum width of the text column to fit different reading needs and screens",
+      "content_width.slider": "Content width slider",
+      "content_width.slider.help": "A ranged slider to choose the maximum width of the content column",
+      "spotlight": "Spotlight",
+      "spotlight.help": "Highlight the line or block under the cursor to help readers stay focused",
+      "spotlight.unavailable": "Spotlight is not available on touch screens",
+      "spotlight.on": "On",
+      "spotlight.on.help": "Turn on Spotlight",
+      "spotlight.off": "Off",
+      "spotlight.off.help": "Turn off Spotlight",
+      "spotlight.styles": "Style",
+      "spotlight.styles.help": "Adjust how the spotlight highlight is drawn",
+      "spotlight.under": "Under",
+      "spotlight.under.help": "A solid background under the hovered block shows where the cursor is",
+      "spotlight.aside": "Aside",
+      "spotlight.aside.help": "A solid line beside the hovered element shows where the cursor is"
+    },
+    "canvas": {
+      "zoom_in": "Zoom in",
+      "zoom_out": "Zoom out",
+      "fit": "Fit view",
+      "prev": "Previous",
+      "next": "Next",
+      "fullscreen": "Fullscreen",
+      "exit_fullscreen": "Exit fullscreen"
+    },
+    "viewer": {
+      "settings": "Viewer settings",
+      "autoplay": "Autoplay",
+      "autoplay_speed": "Autoplay speed",
+      "spin": "Spin",
+      "grid": "Grid",
+      "rotate_speed": "Rotate speed",
+      "reset_view": "Reset view",
+      "label": "3D model",
+      "loading": "Loading…",
+      "width": "Width",
+      "height": "Height"
+    },
+    "redirecting": "Redirecting…",
+    "input": "Input",
+    "output": "Output",
+    "image_unavailable": "Image unavailable",
+    "back": "Back",
+    "not_found": "Page not found",
+    "site_menu": "Site menu",
+    "sign_in": "Sign in",
+    "sign_out": "Sign out",
+    "website": "Website"
+  },
+  "untranslated": {
+    "title": "This page is not translated",
+    "body": "Showing the English version. A translation is not available yet.",
+    "partial_title": "This page is not fully translated",
+    "partial_body": "Some content is still shown in English.",
+    "translate": "Translate on Crowdin"
+  }
+}

package/src/locales/pl_pl.json

@@ -0,0 +1,35 @@
+{
+  "ui": {
+    "sidebar_open": "Otwórz panel",
+    "sidebar_close": "Zamknij panel",
+    "sidebar_collapse": "Zwiń panel",
+    "no_headings": "Brak nagłówków",
+    "copy_anchor": "Kopiuj link do nagłówka",
+    "copied_anchor": "Link do nagłówka skopiowany",
+    "search_close": "Zamknij wyszukiwanie",
+    "search_failed": "Wyszukiwanie nie powiodło się",
+    "search_failed_results": "Wyszukiwanie nie powiodło się, wyniki dla {query}",
+    "open_search": "Otwórz wyszukiwanie",
+    "menu_toggle": "Przełącz menu",
+    "theme_light": "Jasny",
+    "theme_dark": "Ciemny",
+    "theme_system": "Systemowy",
+    "banner_close": "Zamknij baner",
+    "copy_link": "Kopiuj link",
+    "copied_link": "Link skopiowany",
+    "close": "Zamknij",
+    "next_image": "Następny obraz",
+    "prev_image": "Poprzedni obraz",
+    "image_viewer": "Przeglądarka obrazów",
+    "copy_text": "Kopiuj tekst",
+    "copied_text": "Tekst skopiowany",
+    "type": "Typ",
+    "default": "Domyślne",
+    "parameters": "Parametry",
+    "prop": "Właściwość",
+    "returns": "Zwraca",
+    "search_trigger": "Szukaj",
+    "search_dialog": "Szukaj",
+    "search_empty": "Brak wyników"
+  }
+}

package/src/locales/ru_ru.json

@@ -0,0 +1,119 @@
+{
+  "ui": {
+    "on_this_page": "На этой странице",
+    "search_trigger": "Поиск",
+    "search_dialog": "Поиск",
+    "search_empty": "Ничего не найдено",
+    "choose_language": "Выберите язык",
+    "last_updated": "Обновлено",
+    "copy_markdown": "Скопировать Markdown",
+    "open_github": "Открыть в GitHub",
+    "open": "Открыть",
+    "next_page": "Следующая",
+    "prev_page": "Предыдущая",
+    "edit_github": "Редактировать на GitHub",
+    "copied_markdown": "Markdown скопирован",
+    "sidebar_open": "Открыть панель",
+    "sidebar_close": "Закрыть панель",
+    "sidebar_collapse": "Свернуть панель",
+    "no_headings": "Нет заголовков",
+    "copy_anchor": "Скопировать ссылку на заголовок",
+    "copied_anchor": "Ссылка на заголовок скопирована",
+    "search_close": "Закрыть поиск",
+    "search_failed": "Поиск не удался",
+    "search_failed_results": "Поиск не удался, результаты для {query}",
+    "open_search": "Открыть поиск",
+    "menu_toggle": "Переключить меню",
+    "theme_light": "Светлая",
+    "theme_dark": "Тёмная",
+    "theme_system": "Системная",
+    "banner_close": "Закрыть баннер",
+    "copy_link": "Копировать ссылку",
+    "copied_link": "Ссылка скопирована",
+    "close": "Закрыть",
+    "next_image": "Следующее изображение",
+    "prev_image": "Предыдущее изображение",
+    "image_viewer": "Просмотр изображения",
+    "copy_text": "Копировать текст",
+    "copied_text": "Текст скопирован",
+    "type": "Тип",
+    "default": "По умолчанию",
+    "parameters": "Параметры",
+    "prop": "Свойство",
+    "returns": "Возвращает",
+    "readability": {
+      "menu": "Читаемость",
+      "layout": "Макет",
+      "layout.unavailable": "Недоступно на маленьких экранах",
+      "layout.help": "Настройка макета сайта под разные задачи чтения и экраны",
+      "layout.full": "Во всю ширину",
+      "layout.full.help": "Статья занимает всю ширину панели, сайдбар остаётся у края",
+      "layout.sidebar": "Настраиваемая страница",
+      "layout.sidebar.help": "Слайдер сужает весь блок страницы — сайдбар двигается вместе с ним",
+      "layout.both": "Настраиваемая страница и текст",
+      "layout.both.help": "Работают оба слайдера: ширина страницы и текстовой колонки",
+      "layout.original": "Обычная ширина",
+      "layout.original.help": "Стандартная центрированная ширина страницы",
+      "page_width": "Ширина страницы",
+      "page_width.help": "Максимальная ширина страницы под разные задачи чтения и экраны",
+      "page_width.slider": "Слайдер ширины страницы",
+      "page_width.slider.help": "Ползунок для выбора максимальной ширины блока страницы",
+      "content_width": "Ширина текста",
+      "content_width.help": "Максимальная ширина текстовой колонки под разные задачи чтения и экраны",
+      "content_width.slider": "Слайдер ширины текста",
+      "content_width.slider.help": "Ползунок для выбора максимальной ширины текстовой колонки",
+      "spotlight": "Подсветка",
+      "spotlight.help": "Подсвечивает строку или блок под курсором, помогая держать фокус при чтении",
+      "spotlight.unavailable": "Недоступно на сенсорных экранах",
+      "spotlight.on": "Вкл",
+      "spotlight.on.help": "Включить подсветку",
+      "spotlight.off": "Выкл",
+      "spotlight.off.help": "Выключить подсветку",
+      "spotlight.styles": "Стиль",
+      "spotlight.styles.help": "Как отображается подсветка",
+      "spotlight.under": "Под текстом",
+      "spotlight.under.help": "Подложка под наведённым блоком показывает, где находится курсор",
+      "spotlight.aside": "Сбоку",
+      "spotlight.aside.help": "Цветная полоса у левого края блока показывает, где находится курсор"
+    },
+    "canvas": {
+      "zoom_in": "Приблизить",
+      "zoom_out": "Отдалить",
+      "fit": "По размеру",
+      "prev": "Назад",
+      "next": "Вперёд",
+      "fullscreen": "Во весь экран",
+      "exit_fullscreen": "Выйти из полноэкранного режима"
+    },
+    "viewer": {
+      "settings": "Настройки просмотра",
+      "autoplay": "Автопрокрутка",
+      "autoplay_speed": "Скорость автопрокрутки",
+      "spin": "Вращение",
+      "grid": "Сетка",
+      "rotate_speed": "Скорость вращения",
+      "reset_view": "Сбросить вид",
+      "label": "3D-модель",
+      "loading": "Загрузка…",
+      "width": "Ширина",
+      "height": "Высота"
+    },
+    "redirecting": "Перенаправление…",
+    "input": "Исходник",
+    "output": "Результат",
+    "image_unavailable": "Изображение недоступно",
+    "back": "Назад",
+    "not_found": "Страница не найдена",
+    "site_menu": "Меню сайта",
+    "sign_in": "Войти",
+    "sign_out": "Выйти",
+    "website": "Сайт"
+  },
+  "untranslated": {
+    "title": "Страница не переведена",
+    "body": "Показана английская версия. Перевод пока недоступен.",
+    "partial_title": "Страница переведена не полностью",
+    "partial_body": "Часть содержимого показана на английском.",
+    "translate": "Перевести на Crowdin"
+  }
+}

package/src/locales/uk_ua.json

@@ -0,0 +1,35 @@
+{
+  "ui": {
+    "sidebar_open": "Відкрити панель",
+    "sidebar_close": "Закрити панель",
+    "sidebar_collapse": "Згорнути панель",
+    "no_headings": "Немає заголовків",
+    "copy_anchor": "Скопіювати посилання на заголовок",
+    "copied_anchor": "Посилання на заголовок скопійовано",
+    "search_close": "Закрити пошук",
+    "search_failed": "Пошук не вдався",
+    "search_failed_results": "Пошук не вдався, результати для {query}",
+    "open_search": "Відкрити пошук",
+    "menu_toggle": "Перемкнути меню",
+    "theme_light": "Світла",
+    "theme_dark": "Темна",
+    "theme_system": "Системна",
+    "banner_close": "Закрити банер",
+    "copy_link": "Копіювати посилання",
+    "copied_link": "Посилання скопійовано",
+    "close": "Закрити",
+    "next_image": "Наступне зображення",
+    "prev_image": "Попереднє зображення",
+    "image_viewer": "Перегляд зображення",
+    "copy_text": "Копіювати текст",
+    "copied_text": "Текст скопійовано",
+    "type": "Тип",
+    "default": "За замовчуванням",
+    "parameters": "Параметри",
+    "prop": "Властивість",
+    "returns": "Повертає",
+    "search_trigger": "Пошук",
+    "search_dialog": "Пошук",
+    "search_empty": "Нічого не знайдено"
+  }
+}

package/src/locales/zh_cn.json

@@ -0,0 +1,17 @@
+{
+  "ui": {
+    "sidebar_open": "Open Sidebar",
+    "sidebar_close": "Close Sidebar",
+    "sidebar_collapse": "Collapse Sidebar",
+    "no_headings": "No Headings",
+    "copy_anchor": "Copy Anchor Link",
+    "copied_anchor": "Copied Anchor Link",
+    "search_close": "Close Search",
+    "search_failed": "Search failed",
+    "search_failed_results": "Search failed, showing results for {query}",
+    "search_trigger": "搜索",
+    "search_dialog": "搜索",
+    "search_empty": "未找到结果",
+    "open_search": "打开搜索"
+  }
+}

package/src/locales/zh_tw.json

@@ -0,0 +1,17 @@
+{
+  "ui": {
+    "sidebar_open": "Open Sidebar",
+    "sidebar_close": "Close Sidebar",
+    "sidebar_collapse": "Collapse Sidebar",
+    "no_headings": "No Headings",
+    "copy_anchor": "Copy Anchor Link",
+    "copied_anchor": "Copied Anchor Link",
+    "search_close": "Close Search",
+    "search_failed": "Search failed",
+    "search_failed_results": "Search failed, showing results for {query}",
+    "search_trigger": "搜尋",
+    "search_dialog": "搜尋",
+    "search_empty": "找不到結果",
+    "open_search": "開啟搜尋"
+  }
+}

package/src/locales.ts

@@ -0,0 +1,5 @@
+import { createLocaleCatalog } from '@terrafirmagreg-team/translate/lib/locales';
+
+export const locales = createLocaleCatalog(
+  import.meta.glob('./locales/*.json', { eager: true, import: 'default' }),
+);