@icomponents/react 0.1.0

package/src/context/theme-provider.tsx

@@ -0,0 +1,108 @@
+import { getCookie, setCookie, removeCookie } from "@icomponents/react/lib/cookies";
+import { createContext, useContext, useEffect, useState, useMemo } from "react";
+
+type Theme = "dark" | "light" | "system";
+type ResolvedTheme = Exclude<Theme, "system">;
+
+const DEFAULT_THEME = "system";
+const THEME_COOKIE_NAME = "ui-theme";
+const THEME_COOKIE_MAX_AGE = 60 * 60 * 24 * 365; // 1 year
+
+type ThemeProviderProps = {
+  children: React.ReactNode;
+  defaultTheme?: Theme;
+  storageKey?: string;
+};
+
+type ThemeProviderState = {
+  defaultTheme: Theme;
+  resolvedTheme: ResolvedTheme;
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+  resetTheme: () => void;
+};
+
+const initialState: ThemeProviderState = {
+  defaultTheme: DEFAULT_THEME,
+  resolvedTheme: "light",
+  theme: DEFAULT_THEME,
+  setTheme: () => null,
+  resetTheme: () => null,
+};
+
+const ThemeContext = createContext<ThemeProviderState>(initialState);
+
+export function ThemeProvider({
+  children,
+  defaultTheme = DEFAULT_THEME,
+  storageKey = THEME_COOKIE_NAME,
+  ...props
+}: ThemeProviderProps) {
+  const [theme, _setTheme] = useState<Theme>(
+    () => (getCookie(storageKey) as Theme) || defaultTheme
+  );
+
+  // Optimized: Memoize the resolved theme calculation to prevent unnecessary re-computations
+  const resolvedTheme = useMemo((): ResolvedTheme => {
+    if (theme === "system") {
+      return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    }
+    return theme as ResolvedTheme;
+  }, [theme]);
+
+  useEffect(() => {
+    const root = window.document.documentElement;
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+
+    const applyTheme = (currentResolvedTheme: ResolvedTheme) => {
+      root.classList.remove("light", "dark"); // Remove existing theme classes
+      root.classList.add(currentResolvedTheme); // Add the new theme class
+    };
+
+    const handleChange = () => {
+      if (theme === "system") {
+        const systemTheme = mediaQuery.matches ? "dark" : "light";
+        applyTheme(systemTheme);
+      }
+    };
+
+    applyTheme(resolvedTheme);
+
+    mediaQuery.addEventListener("change", handleChange);
+
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, [theme, resolvedTheme]);
+
+  const setTheme = (theme: Theme) => {
+    setCookie(storageKey, theme, THEME_COOKIE_MAX_AGE);
+    _setTheme(theme);
+  };
+
+  const resetTheme = () => {
+    removeCookie(storageKey);
+    _setTheme(DEFAULT_THEME);
+  };
+
+  const contextValue = {
+    defaultTheme,
+    resolvedTheme,
+    resetTheme,
+    theme,
+    setTheme,
+  };
+
+  return (
+    <ThemeContext value={contextValue} {...props}>
+      {children}
+    </ThemeContext>
+  );
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export const useTheme = () => {
+  const context = useContext(ThemeContext);
+
+  if (!context) throw new Error("useTheme must be used within a ThemeProvider");
+
+  return context;
+};

package/src/hooks/sort-url.test.ts

@@ -0,0 +1,16 @@
+import { expect, test } from "bun:test";
+
+import { sortParamToState, sortStateToParam } from "./use-table-url-state";
+
+test("sortParamToState: '-name' → desc, 'name' → asc, empty → []", () => {
+  expect(sortParamToState("-name")).toEqual([{ id: "name", desc: true }]);
+  expect(sortParamToState("name")).toEqual([{ id: "name", desc: false }]);
+  expect(sortParamToState("")).toEqual([]);
+  expect(sortParamToState(undefined)).toEqual([]);
+  expect(sortParamToState("-")).toEqual([]);
+});
+test("sortStateToParam: round-trips, [] → undefined", () => {
+  expect(sortStateToParam([{ id: "name", desc: true }])).toBe("-name");
+  expect(sortStateToParam([{ id: "name", desc: false }])).toBe("name");
+  expect(sortStateToParam([])).toBeUndefined();
+});

package/src/hooks/use-dialog-state.tsx

@@ -0,0 +1,15 @@
+import { useState } from "react";
+
+/**
+ * Custom hook for confirm dialog
+ * @param initialState string | null
+ * @returns A stateful value, and a function to update it.
+ * @example const [open, setOpen] = useDialogState<"approve" | "reject">()
+ */
+export default function useDialogState<T extends string | boolean>(initialState: T | null = null) {
+  const [open, _setOpen] = useState<T | null>(initialState);
+
+  const setOpen = (str: T | null) => _setOpen((prev) => (prev === str ? null : str));
+
+  return [open, setOpen] as const;
+}

package/src/hooks/use-mobile.tsx

@@ -0,0 +1,16 @@
+import * as React from "react";
+
+const MOBILE_BREAKPOINT = 768;
+const MOBILE_QUERY = `(max-width: ${MOBILE_BREAKPOINT - 1}px)`;
+
+export function useIsMobile() {
+  return React.useSyncExternalStore(
+    (callback) => {
+      const mql = window.matchMedia(MOBILE_QUERY);
+      mql.addEventListener("change", callback);
+      return () => mql.removeEventListener("change", callback);
+    },
+    () => window.matchMedia(MOBILE_QUERY).matches,
+    () => false
+  );
+}

package/src/hooks/use-table-url-state.ts

@@ -0,0 +1,243 @@
+import type {
+  ColumnFiltersState,
+  OnChangeFn,
+  PaginationState,
+  SortingState,
+} from "@tanstack/react-table";
+import { useMemo, useState } from "react";
+
+type SearchRecord = Record<string, unknown>;
+
+export type NavigateFn = (opts: {
+  search: true | SearchRecord | ((prev: SearchRecord) => Partial<SearchRecord> | SearchRecord);
+  replace?: boolean;
+}) => void;
+
+/** URL sort param → single-column SortingState. `"-field"` = desc, `"field"` = asc, else []. */
+export function sortParamToState(raw: unknown): SortingState {
+  if (typeof raw !== "string" || raw.trim() === "") return [];
+  const isDesc = raw.startsWith("-");
+  const id = (isDesc ? raw.slice(1) : raw).trim();
+  if (!id) return [];
+  return [{ id, desc: isDesc }];
+}
+
+/** Single-column SortingState → URL sort param (`"-field"`/`"field"`), or undefined when unsorted. */
+export function sortStateToParam(sorting: SortingState): string | undefined {
+  const first = sorting[0];
+  if (!first) return undefined;
+  return `${first.desc ? "-" : ""}${first.id}`;
+}
+
+type UseTableUrlStateParams = {
+  search: SearchRecord;
+  navigate: NavigateFn;
+  pagination?: {
+    pageKey?: string;
+    pageSizeKey?: string;
+    defaultPage?: number;
+    defaultPageSize?: number;
+  };
+  globalFilter?: {
+    enabled?: boolean;
+    key?: string;
+    trim?: boolean;
+  };
+  columnFilters?: Array<
+    | {
+        columnId: string;
+        searchKey: string;
+        type?: "string";
+        // Optional transformers for custom types
+        serialize?: (value: unknown) => unknown;
+        deserialize?: (value: unknown) => unknown;
+      }
+    | {
+        columnId: string;
+        searchKey: string;
+        type: "array";
+        serialize?: (value: unknown) => unknown;
+        deserialize?: (value: unknown) => unknown;
+      }
+  >;
+  sorting?: {
+    enabled?: boolean; // default false — client-mode tables leave it off (local sort), unchanged
+    key?: string; // URL param, default "sort"
+  };
+};
+
+type UseTableUrlStateReturn = {
+  // Global filter
+  globalFilter?: string;
+  onGlobalFilterChange?: OnChangeFn<string>;
+  // Column filters
+  columnFilters: ColumnFiltersState;
+  onColumnFiltersChange: OnChangeFn<ColumnFiltersState>;
+  // Pagination
+  pagination: PaginationState;
+  onPaginationChange: OnChangeFn<PaginationState>;
+  // Sorting (present only when enabled)
+  sorting?: SortingState;
+  onSortingChange?: OnChangeFn<SortingState>;
+  // Helpers
+  ensurePageInRange: (pageCount: number, opts?: { resetTo?: "first" | "last" }) => void;
+};
+
+export function useTableUrlState(params: UseTableUrlStateParams): UseTableUrlStateReturn {
+  const {
+    search,
+    navigate,
+    pagination: paginationCfg,
+    globalFilter: globalFilterCfg,
+    columnFilters: columnFiltersCfg = [],
+    sorting: sortingCfg,
+  } = params;
+
+  const pageKey = paginationCfg?.pageKey ?? ("page" as string);
+  const pageSizeKey = paginationCfg?.pageSizeKey ?? ("pageSize" as string);
+  const defaultPage = paginationCfg?.defaultPage ?? 1;
+  const defaultPageSize = paginationCfg?.defaultPageSize ?? 10;
+
+  const globalFilterKey = globalFilterCfg?.key ?? ("filter" as string);
+  const globalFilterEnabled = globalFilterCfg?.enabled ?? true;
+  const trimGlobal = globalFilterCfg?.trim ?? true;
+
+  // Build initial column filters from the current search params
+  const initialColumnFilters: ColumnFiltersState = useMemo(() => {
+    const collected: ColumnFiltersState = [];
+    for (const cfg of columnFiltersCfg) {
+      const raw = (search as SearchRecord)[cfg.searchKey];
+      const deserialize = cfg.deserialize ?? ((v: unknown) => v);
+      if (cfg.type === "string") {
+        const value = (deserialize(raw) as string) ?? "";
+        if (typeof value === "string" && value.trim() !== "") {
+          collected.push({ id: cfg.columnId, value });
+        }
+      } else {
+        // default to array type
+        const value = (deserialize(raw) as unknown[]) ?? [];
+        if (Array.isArray(value) && value.length > 0) {
+          collected.push({ id: cfg.columnId, value });
+        }
+      }
+    }
+    return collected;
+  }, [columnFiltersCfg, search]);
+
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>(initialColumnFilters);
+
+  const pagination: PaginationState = useMemo(() => {
+    const rawPage = (search as SearchRecord)[pageKey];
+    const rawPageSize = (search as SearchRecord)[pageSizeKey];
+    const pageNum = typeof rawPage === "number" ? rawPage : defaultPage;
+    const pageSizeNum = typeof rawPageSize === "number" ? rawPageSize : defaultPageSize;
+    return { pageIndex: Math.max(0, pageNum - 1), pageSize: pageSizeNum };
+  }, [search, pageKey, pageSizeKey, defaultPage, defaultPageSize]);
+
+  const onPaginationChange: OnChangeFn<PaginationState> = (updater) => {
+    const next = typeof updater === "function" ? updater(pagination) : updater;
+    const nextPage = next.pageIndex + 1;
+    const nextPageSize = next.pageSize;
+    navigate({
+      search: (prev) => ({
+        ...(prev as SearchRecord),
+        [pageKey]: nextPage <= defaultPage ? undefined : nextPage,
+        [pageSizeKey]: nextPageSize === defaultPageSize ? undefined : nextPageSize,
+      }),
+    });
+  };
+
+  const sortingEnabled = sortingCfg?.enabled ?? false;
+  const sortKey = sortingCfg?.key ?? "sort";
+  const sortingState: SortingState = useMemo(
+    () => (sortingEnabled ? sortParamToState((search as SearchRecord)[sortKey]) : []),
+    [sortingEnabled, search, sortKey]
+  );
+  const onSortingChange: OnChangeFn<SortingState> = (updater) => {
+    const next = typeof updater === "function" ? updater(sortingState) : updater;
+    navigate({
+      search: (prev) => ({
+        ...(prev as SearchRecord),
+        [pageKey]: undefined, // a sort change resets to page 1 (mirrors filter/pagination changes)
+        [sortKey]: sortStateToParam(next),
+      }),
+    });
+  };
+
+  const [globalFilter, setGlobalFilter] = useState<string | undefined>(() => {
+    if (!globalFilterEnabled) return undefined;
+    const raw = (search as SearchRecord)[globalFilterKey];
+    return typeof raw === "string" ? raw : "";
+  });
+
+  const onGlobalFilterChange: OnChangeFn<string> | undefined = globalFilterEnabled
+    ? (updater) => {
+        const next = typeof updater === "function" ? updater(globalFilter ?? "") : updater;
+        const value = trimGlobal ? next.trim() : next;
+        setGlobalFilter(value);
+        navigate({
+          search: (prev) => ({
+            ...(prev as SearchRecord),
+            [pageKey]: undefined,
+            [globalFilterKey]: value ? value : undefined,
+          }),
+        });
+      }
+    : undefined;
+
+  const onColumnFiltersChange: OnChangeFn<ColumnFiltersState> = (updater) => {
+    const next = typeof updater === "function" ? updater(columnFilters) : updater;
+    setColumnFilters(next);
+
+    const patch: Record<string, unknown> = {};
+
+    for (const cfg of columnFiltersCfg) {
+      const found = next.find((f) => f.id === cfg.columnId);
+      const serialize = cfg.serialize ?? ((v: unknown) => v);
+      if (cfg.type === "string") {
+        const value = typeof found?.value === "string" ? (found.value as string) : "";
+        patch[cfg.searchKey] = value.trim() !== "" ? serialize(value) : undefined;
+      } else {
+        const value = Array.isArray(found?.value) ? (found!.value as unknown[]) : [];
+        patch[cfg.searchKey] = value.length > 0 ? serialize(value) : undefined;
+      }
+    }
+
+    navigate({
+      search: (prev) => ({
+        ...(prev as SearchRecord),
+        [pageKey]: undefined,
+        ...patch,
+      }),
+    });
+  };
+
+  const ensurePageInRange = (
+    pageCount: number,
+    opts: { resetTo?: "first" | "last" } = { resetTo: "first" }
+  ) => {
+    const currentPage = (search as SearchRecord)[pageKey];
+    const pageNum = typeof currentPage === "number" ? currentPage : defaultPage;
+    if (pageCount > 0 && pageNum > pageCount) {
+      navigate({
+        replace: true,
+        search: (prev) => ({
+          ...(prev as SearchRecord),
+          [pageKey]: opts.resetTo === "last" ? pageCount : undefined,
+        }),
+      });
+    }
+  };
+
+  return {
+    globalFilter: globalFilterEnabled ? (globalFilter ?? "") : undefined,
+    onGlobalFilterChange,
+    columnFilters,
+    onColumnFiltersChange,
+    pagination,
+    onPaginationChange,
+    sorting: sortingEnabled ? sortingState : undefined,
+    onSortingChange: sortingEnabled ? onSortingChange : undefined,
+    ensurePageInRange,
+  };
+}

package/src/i18n/common.ts

@@ -0,0 +1,164 @@
+import type { NamespaceBundle } from "@icomponents/react/i18n/types";
+
+/**
+ * Словарь ОБЩИХ shared-компонентов ядра — тех, что не принадлежат ни одному слайсу, а стоят в шапке
+ * и в таблицах на всех страницах: config-drawer, search, command-menu, theme-switch, faceted-filter.
+ * Неймспейс "common".
+ *
+ * Живёт в `packages/ui` рядом с самими компонентами (в отличие от per-slice бандлов, которые лежат у
+ * своего слайса): у этих компонентов нет слайса-владельца. Собирается тем же приёмом — продукт
+ * добавляет бандл в `appBundles` (см. `apps/web/src/client/i18n/bundles.ts`) и при желании
+ * переопределяет подписи через `createI18n({ overrides })`, не форкая ядро.
+ */
+export const commonBundle: NamespaceBundle = {
+  ns: "common",
+  messages: {
+    ru: {
+      // Общее — переиспользуется несколькими компонентами.
+      noResults: "Ничего не найдено.",
+      // Диалог подтверждения (ConfirmDialog) — подписи кнопок по умолчанию. Раньше были захардкожены
+      // по-английски, из-за чего КАЖДЫЙ диалог, не передавший свои подписи, говорил не на языке
+      // интерфейса — в том числе диалог выхода.
+      confirm: {
+        cancel: "Отмена",
+        continue: "Продолжить",
+      },
+      // Выход из консоли (SignOutDialog).
+      signOut: {
+        title: "Выйти?",
+        desc: "Вы уверены, что хотите выйти? Чтобы вернуться в консоль, потребуется войти заново.",
+        confirm: "Выйти",
+      },
+      theme: {
+        title: "Тема",
+        light: "Светлая",
+        dark: "Тёмная",
+        system: "Системная",
+        toggle: "Переключить тему",
+      },
+      search: {
+        button: "Поиск",
+      },
+      commandMenu: {
+        placeholder: "Введите команду или поисковый запрос…",
+      },
+      configDrawer: {
+        open: "Открыть настройки оформления",
+        title: "Настройки оформления",
+        description: "Настройте внешний вид и раскладку под свои предпочтения.",
+        reset: "Сбросить",
+        resetAllAria: "Сбросить все настройки к значениям по умолчанию",
+        selectOption: "Выбрать: {{label}}",
+        optionPreview: "Превью варианта «{{label}}»",
+        theme: {
+          selectAria: "Выберите тему оформления",
+          resetAria: "Сбросить тему оформления к значению по умолчанию",
+          hint: "Выберите системную, светлую или тёмную тему",
+        },
+        sidebar: {
+          title: "Боковая панель",
+          selectAria: "Выберите стиль боковой панели",
+          resetAria: "Сбросить стиль боковой панели к значению по умолчанию",
+          inset: "Встроенная",
+          floating: "Плавающая",
+          sidebar: "Обычная",
+          hint: "Выберите встроенную, плавающую или обычную боковую панель",
+        },
+        layout: {
+          title: "Раскладка",
+          selectAria: "Выберите стиль раскладки",
+          resetAria: "Сбросить параметры раскладки к значениям по умолчанию",
+          default: "Обычная",
+          compact: "Компактная",
+          full: "Во всю ширину",
+          hint: "Выберите обычную развёрнутую, компактную (только иконки) или полноширинную раскладку",
+        },
+        direction: {
+          title: "Направление",
+          selectAria: "Выберите направление письма",
+          resetAria: "Сбросить направление письма к значению по умолчанию",
+          ltr: "Слева направо",
+          rtl: "Справа налево",
+          hint: "Выберите направление письма — слева направо или справа налево",
+        },
+      },
+      facetedFilter: {
+        selected: "Выбрано: {{n}}",
+        clear: "Сбросить фильтры",
+      },
+    },
+    en: {
+      // Shared — reused by several components.
+      noResults: "No results found.",
+      // ConfirmDialog default button labels (previously hardcoded English literals, which made every
+      // dialog that relied on them speak a language the rest of the UI did not).
+      confirm: {
+        cancel: "Cancel",
+        continue: "Continue",
+      },
+      // Console sign-out (SignOutDialog).
+      signOut: {
+        title: "Sign out?",
+        desc: "Are you sure you want to sign out? You will need to sign in again to access the console.",
+        confirm: "Sign out",
+      },
+      theme: {
+        title: "Theme",
+        light: "Light",
+        dark: "Dark",
+        system: "System",
+        toggle: "Toggle theme",
+      },
+      search: {
+        button: "Search",
+      },
+      commandMenu: {
+        placeholder: "Type a command or search...",
+      },
+      configDrawer: {
+        open: "Open theme settings",
+        title: "Theme Settings",
+        description: "Adjust the appearance and layout to suit your preferences.",
+        reset: "Reset",
+        resetAllAria: "Reset all settings to default values",
+        selectOption: "Select {{label}}",
+        optionPreview: "{{label}} option preview",
+        theme: {
+          selectAria: "Select theme preference",
+          resetAria: "Reset theme preference to default",
+          hint: "Choose between system preference, light mode, or dark mode",
+        },
+        sidebar: {
+          title: "Sidebar",
+          selectAria: "Select sidebar style",
+          resetAria: "Reset sidebar style to default",
+          inset: "Inset",
+          floating: "Floating",
+          sidebar: "Sidebar",
+          hint: "Choose between inset, floating, or standard sidebar layout",
+        },
+        layout: {
+          title: "Layout",
+          selectAria: "Select layout style",
+          resetAria: "Reset layout options to default",
+          default: "Default",
+          compact: "Compact",
+          full: "Full layout",
+          hint: "Choose between default expanded, compact icon-only, or full layout mode",
+        },
+        direction: {
+          title: "Direction",
+          selectAria: "Select site direction",
+          resetAria: "Reset text direction to default",
+          ltr: "Left to Right",
+          rtl: "Right to Left",
+          hint: "Choose between left-to-right or right-to-left site direction",
+        },
+      },
+      facetedFilter: {
+        selected: "{{n}} selected",
+        clear: "Clear filters",
+      },
+    },
+  },
+};

package/src/i18n/create-i18n.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "bun:test";
+
+import { createI18n } from "./create-i18n";
+import type { NamespaceBundle } from "./types";
+
+const companies: NamespaceBundle = {
+  ns: "companies",
+  messages: {
+    ru: { title: "Компании" },
+    en: { title: "Companies" },
+  },
+};
+const nav: NamespaceBundle = {
+  ns: "nav",
+  messages: { ru: { home: "Главная" }, en: { home: "Home" } },
+};
+
+describe("createI18n — сборка per-feature бандлов", () => {
+  it("каждый неймспейс отдаёт свой перевод; язык переключается", async () => {
+    const i18n = createI18n({ bundles: [companies, nav], lng: "ru" });
+    expect(i18n.t("title", { ns: "companies" })).toBe("Компании");
+    expect(i18n.t("home", { ns: "nav" })).toBe("Главная");
+    await i18n.changeLanguage("en");
+    expect(i18n.t("title", { ns: "companies" })).toBe("Companies");
+  });
+
+  it("непереведённый язык падает на английский (fallback), а не на пустой ключ", async () => {
+    const partial: NamespaceBundle = {
+      ns: "x",
+      messages: { ru: {}, en: { only: "English only" } },
+    };
+    const i18n = createI18n({ bundles: [partial], lng: "ru" });
+    expect(i18n.t("only", { ns: "x" })).toBe("English only");
+  });
+
+  it("product-override меняет подпись ядра, НЕ мутируя исходный бандл (шов ядро/продукт)", () => {
+    const i18n = createI18n({
+      bundles: [companies],
+      lng: "ru",
+      overrides: { ru: { companies: { title: "Партнёры" } } },
+    });
+    // UI продукта видит своё слово…
+    expect(i18n.t("title", { ns: "companies" })).toBe("Партнёры");
+    // …а канонический бандл ядра не тронут (общий на все инстансы).
+    expect(companies.messages.ru.title).toBe("Компании");
+    // Другой инстанс без override видит канон.
+    const plain = createI18n({ bundles: [companies], lng: "ru" });
+    expect(plain.t("title", { ns: "companies" })).toBe("Компании");
+  });
+});

package/src/i18n/create-i18n.ts

@@ -0,0 +1,67 @@
+import i18next, { type i18n as I18n, type Resource } from "i18next";
+import { initReactI18next } from "react-i18next";
+
+import { LOCALES, type Locale, type Messages, type NamespaceBundle } from "./types";
+
+/**
+ * Продуктовые переопределения подписей. КЛЮЧЕВОЙ шов «ядро/продукт»: внутреннее представление
+ * остаётся в терминах шаблона (`organizations`/`companies`), а продукт МЕНЯЕТ ПОДПИСЬ в UI, не форкая
+ * бандл ядра. Например, продукт, где та же сущность зовётся иначе, передаёт
+ * `{ ru: { nav: { companies: "<своё слово>" }, companies: { title: "<своё слово>" } } }` — код
+ * по-прежнему знает про companies, пользователь видит термин продукта.
+ */
+export type Overrides = Partial<Record<Locale, Record<string, Messages>>>;
+
+function deepMerge(base: Record<string, unknown>, over: Record<string, unknown>): void {
+  for (const [k, v] of Object.entries(over)) {
+    if (v && typeof v === "object" && !Array.isArray(v) && typeof base[k] === "object") {
+      deepMerge(base[k] as Record<string, unknown>, v as Record<string, unknown>);
+    } else {
+      base[k] = v;
+    }
+  }
+}
+
+/**
+ * Собирает per-feature бандлы в один инстанс i18next.
+ *
+ * Ключевое: НЕТ центрального словаря. `bundles` приходят из composition root, где каждый слайс
+ * зарегистрировал свой `NamespaceBundle`. Здесь они лишь раскладываются в форму i18next
+ * (`resources[lng][ns] = messages`) — монолит не появляется даже на этом шаге, каждый неймспейс
+ * остаётся отдельным.
+ *
+ * Свой инстанс (`createInstance`), а не глобальный синглтон i18next: приложение может держать
+ * несколько (тесты, SSR), и глобальное состояние не течёт между ними.
+ */
+export function createI18n(opts: {
+  bundles: NamespaceBundle[];
+  lng: Locale;
+  /** Продуктовые переопределения подписей (см. Overrides) — накладываются ПОВЕРХ бандлов ядра. */
+  overrides?: Overrides;
+}): I18n {
+  const resources: Record<string, Record<string, unknown>> = {};
+  for (const lng of LOCALES) resources[lng] = {};
+  for (const b of opts.bundles) {
+    for (const lng of LOCALES) {
+      // Копия, чтобы override не мутировал исходный бандл фичи (он общий на все инстансы).
+      resources[lng]![b.ns] = structuredClone(b.messages[lng]);
+    }
+  }
+  // Продуктовые переопределения — точечный deep-merge на канонические бандлы (ядро не форкаем).
+  for (const lng of LOCALES) {
+    const over = opts.overrides?.[lng];
+    if (over) deepMerge(resources[lng]!, over as Record<string, unknown>);
+  }
+
+  const instance = i18next.createInstance();
+  instance.use(initReactI18next).init({
+    lng: opts.lng,
+    fallbackLng: "en", // язык не выбран/строка не переведена → английский, а не пустой ключ
+    resources: resources as Resource,
+    ns: opts.bundles.map((b) => b.ns),
+    defaultNS: false, // неймспейс указывается явно: useTranslation("companies") — не даём монолитному default прорасти
+    interpolation: { escapeValue: false }, // React сам экранирует
+    returnNull: false,
+  });
+  return instance;
+}