Meridian Sheets — спецификация приложения

Документ приложения по разделу 8 библии (docs/00-foundation.md). Версия 0.1 · 2026-10-03. Собственный формат: .msx (шаблон .mst, плоский XML .msxf), пространство имён urn:meridian:office:sheets:1, MIME application/vnd.meridian.sheets. Цвет приложения --app-sheets #1E8E5A, значок — сетка 2×2. Крейты ядра: kernel/crates/meridian-grid (модель книги, хранение ячеек), meridian-calc (лексер, парсер, байткод, граф зависимостей, пересчёт, каталог функций), meridian-pivot (сводные), meridian-chart (общий Meridian Chart), meridian-numfmt (числовые форматы), meridian-solver (подбор параметра, Solver), meridian-codecs-{ooxml,odf,msbinary,csv}; оболочка — shell/src/sheets/ (QML/C++); скрипты — meridian-script. Фаза по библии: 2 (6–16 мес от старта); совместная работа — фаза 6; потоки данных и богатые типы — P1/P2.

Содержание

1. Назначение и аналоги
2. Функции (по группам, P0/P1/P2)
3. Экраны
4. Модель данных (Rust)
5. Алгоритмы · 5.23 Каталог функций
6. MeridianScript API для Sheets
7. Форматы
8. Горячие клавиши
9. Критерии готовности 1.0
10. Риски
11. Вопросы к библии

1. Назначение и аналоги

1.1 Назначение

Meridian Sheets — электронные таблицы пакета: ввод и правка табличных данных, формулы (500+ функций, динамические массивы, LAMBDA), форматирование и условное форматирование, структурированные таблицы, сортировка/фильтры/проверка данных, сводные таблицы и диаграммы (Meridian Chart), импорт внешних данных, анализ «что если» (подбор параметра, Solver, сценарии, таблицы данных), печать, скрипты MeridianScript вместо VBA. Единая модель сетки (grid-model) и движок формул (calc-engine) из Meridian Kernel используются также таблицами в Write, Slides, Notes и ответами Forms.

Главные сценарии: финансовые модели и бюджеты; реестры и списки (клиенты, склад, задачи); отчёты из выгрузок (CSV/БД → сводная → диаграмма); обработка больших выгрузок (1–10 млн строк); учебные расчёты; формы Forms → лист ответов.

1.2 Аналоги

1.3 Чем будем лучше Excel и Calc

1.4 Границы версии 1.0

Не входит в 1.0: Power Pivot/DAX и модели данных с миллиардами строк; полноценный аналог Power Query (потоки данных — ограниченный набор шагов, P1/P2); совместное редактирование (фаза 6); богатые типы «География/Акции» (P2, нужен поставщик данных); выполнение VBA (только трансляция простых макросов); сводные по OLAP-кубам (P2).

2. Функции

Приоритеты: P0 — без этого нельзя выпустить 1.0; P1 — в 1.x; P2 — позже.

2.1 Ввод и правка

2.2 Форматирование ячеек

2.3 Стили ячеек и структурированные таблицы

2.4 Формулы

2.5 Данные

2.6 Сводные таблицы и сводные диаграммы

2.7 Диаграммы

Движок — Meridian Chart (общий для всех приложений; спецификация в docs/algorithms/chart-engine.md); здесь — что доступно из Sheets.

2.8 Импорт данных и потоки данных

2.9 Защита

2.10 Общие книги и совместная работа (фаза 6)

2.11 Печать

2.12 Окна

2.13 Буфер обмена, поиск и замена

2.14 Примечания, обсуждения, гиперссылки

2.15 Типы данных

2.16 Макросы и скрипты

2.17 Доступность

3. Экраны

Идентификаторы: SH-01…SH-09 — главное окно и его постоянные части; SH-10…SH-19 — боковые панели; SH-20…SH-59 — диалоги; SH-60…SH-69 — контекстные меню; SH-70+ — всплывающие элементы. Макет — mockups/sheets.html, по одному <section class="screen"> на идентификатор.

3.1 SH-01 Главное окно

Каркас — по §5.3 библии. Отличия Sheets: над холстом — строка формул (SH-02); под холстом — ярлычки листов (SH-03) в одной строке с горизонтальной полосой прокрутки; строка состояния (SH-04) показывает статистику выделения.

┌──────────────────────────────────────────────────────────────────────────────────┐
│ [▦] Бюджет 2026.msx — Meridian Sheets        [⌘K Поиск команд]   [☁ Сохранено] [👤] │
├──────────────────────────────────────────────────────────────────────────────────┤
│ Файл  Главная  Вставка  Макет страницы  Формулы  Данные  Рецензирование  Вид  Скрипты │ Таблица │
│ [Буфер][Шрифт][Выравнивание][Число][Стили][Ячейки][Редактирование]       [⌄]     │
├──────────┬───────────────────────────────────────────────────────────────────────┤
│ B4      ▾│ fx │ =SUM(B2:B3)                                            [⌃ развернуть]│  ← SH-02
├──────────┴──┬────┬────────┬────────┬────────┬────────┬─────────────┬──────────────┤
│  Навигатор  │    │   A    │   B    │   C    │   D    │  …          │ Поля сводной │
│  (SH-14,    │  1 │ Статья │ План   │ Факт   │ Откл.  │             │ / Свойства   │
│   опц.)     │  2 │ Аренда │ 120000 │ 118500 │ -1500  │             │ (SH-10…SH-16)│
│             │  3 │ Зарпл. │ 540000 │ 552300 │ 12300  │             │              │
│             │  4 │ Итого  │▌660000▐│        │        │             │              │
├─────────────┴────┴────────┴────────┴────────┴────────┴─────────────┴──────────────┤
│ ◂ ▸ │ Бюджет │ Данные │ Сводная │ ⊕ │              ◂═══════════════▸               │  ← SH-03
├──────────────────────────────────────────────────────────────────────────────────┤
│ Готово │ Среднее: 330 000  Количество: 2  Сумма: 660 000 │ ⚠ Циклы: 0 │ ▦ ▤ ▥ │ ─●─ 100 % │  ← SH-04
└──────────────────────────────────────────────────────────────────────────────────┘

Элементы холста: заголовки строк/столбцов (клик — выделить, перетаскивание границы — размер, двойной клик — автоподбор), угол «выделить всё», линии закрепления, рамка активной ячейки с маркером заполнения (квадрат 6×6 px цвета --app-sheets), бегущая рамка копирования, цветные рамки ссылок при правке формулы, значки автофильтра в заголовках, кнопки структуры (+/−) слева/сверху, индикаторы примечаний (красный треугольник) и обсуждений (фиолетовый), треугольник проверки ошибок (зелёный), раскрывающиеся списки проверки данных, объекты поверх сетки (диаграммы, рисунки, фигуры).

3.2 Ribbon — вкладки и группы

Компактный режим: одна строка 40 px с самыми частыми командами, вкладки открываются как выпадающие панели. Командная палитра Ctrl+K ищет команды, функции («СУММЕСЛИ» → вставить), имена, листы, скрипты.

3.3 Постоянные части окна

3.4 Боковые панели (правая зона, вкладки с переключением, ширина 280–480 px)

3.5 Диалоги

3.6 Контекстные меню

3.7 Мини-панель и всплывающие элементы

4. Модель данных

Крейт meridian-grid. Модель не знает об интерфейсе и форматах файлов; изменения проходят только через операции (§4.15), что даёт undo, журнал автосохранения и CRDT одной механикой.

4.1 Обзор

Workbook
 ├─ sheets: Vec<Sheet>                 ← порядок ярлычков
 ├─ names: NameTable                   ← имена книги (+ ссылки на имена листов)
 ├─ styles: StyleTable                 ← общие стили ячеек (индексы)
 ├─ strings: StringPool                ← общие строки
 ├─ formulas: FormulaStore             ← скомпилированные формулы (общие)
 ├─ tables: Vec<Table>, pivots: Vec<Pivot>, charts: Vec<ChartObject>
 ├─ pivot_caches: Vec<PivotCache>, connections: Vec<DataConnection>, flows: Vec<DataFlow>
 ├─ theme: Theme, calc: CalcSettings, protection: WorkbookProtection, props: DocProps
 ├─ scripts: ScriptBundle, history: OpLog (CRDT/undo), external_links: Vec<ExternalLink>
 └─ deps: DependencyGraph (в meridian-calc, строится из формул)
Sheet
 ├─ id: SheetId (стабильный, не меняется при переименовании/перемещении)
 ├─ cells: CellStore  (чанки 256×256)
 ├─ rows: AxisProps, cols: AxisProps   (высоты/ширины/скрытие/группы/стили — RLE)
 ├─ merges: MergeIndex, cf: Vec<CfRule>, validations: Vec<Validation>
 ├─ autofilter, sparklines, hyperlinks, notes, threads, objects (диаграммы/рисунки/фигуры/контролы)
 ├─ view: SheetView (закрепление, масштаб, выделение, разделение), print: PrintSetup, protection
 └─ kind: SheetKind { Worksheet, ChartSheet, Macro(legacy), Dialog(legacy, только round-trip) }

4.2 Выбор хранения ячеек: чанки 256×256

Рассмотрены два варианта.

Решение: чанки 256 строк × 256 столбцов, два представления внутри чанка — разреженное (битовая карта занятости + плотный вектор занятых слотов, индексация через rank) и плотное (массив 65 536 слотов), переход при заполненности > 40 % (и обратно < 20 %, с гистерезисом). Чанки лежат в BTreeMap<ChunkKey, Box<Chunk>> (обход в порядке строк нужен для сохранения файла и печати; при 262 144 чанках полного листа дерево мало).

// kernel/crates/meridian-grid/src/store.rs

/// Координаты ячейки / Cell coordinates (0-based)
#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct CellRef { pub row: u32, pub col: u32 }

/// Ключ чанка: 256×256 / Chunk key: 256×256
#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct ChunkKey { pub crow: u32, pub ccol: u32 }           // crow = row >> 8, ccol = col >> 8

pub const CHUNK: usize = 256;
pub const CHUNK_CELLS: usize = CHUNK * CHUNK;                     // 65 536

/// Слот ячейки — то, что лежит в чанке / Cell slot stored in a chunk (24 B value + 8 B meta)
#[derive(Clone)]
pub struct CellSlot {
    pub value: Value,             // 24 Б: тег + f64 | Arc<str> | …
    pub style: StyleId,           // u32, индекс в StyleTable (0 = Обычный)
    pub extra: ExtraId,           // u32, 0 = нет; иначе индекс в side-table (формула, примечание, ссылка, spill, rich)
}

pub enum Chunk {
    /// Разреженный: битовая карта занятости + rank-таблица + вектор слотов в порядке row-major
    /// Sparse: occupancy bitmap + rank table + slot vector in row-major order
    Sparse {
        occupancy: Box<[u64; 1024]>,  // 65 536 бит = 8 КБ
        rank: Box<[u16; 1024]>,       // число занятых бит до слова i (префиксные суммы) → O(1) индекс
        slots: Vec<CellSlot>,
    },
    /// Плотный: прямой массив / Dense: direct array (всегда 65 536 слотов, ~2 МБ)
    Dense { slots: Box<[CellSlot; CHUNK_CELLS]>, count: u32 },
}

impl Chunk {
    #[inline]
    fn local(r: u32, c: u32) -> usize { ((r & 255) as usize) << 8 | (c & 255) as usize }

    pub fn get(&self, r: u32, c: u32) -> Option<&CellSlot> {
        let i = Self::local(r, c);
        match self {
            Chunk::Dense { slots, .. } => slots[i].is_empty().not().then(|| &slots[i]),
            Chunk::Sparse { occupancy, rank, slots } => {
                let (w, b) = (i >> 6, i & 63);
                if occupancy[w] >> b & 1 == 0 { return None; }
                // rank(i) = занятых до слова + занятых в слове до бита / popcount prefix
                let idx = rank[w] as usize + (occupancy[w] & ((1u64 << b) - 1)).count_ones() as usize;
                Some(&slots[idx])
            }
        }
    }
    // set/remove: вставка в Vec — O(занятых в чанке); массовые операции идут через ChunkBuilder
    // set/remove: Vec insert is O(occupied in chunk); bulk loads go through ChunkBuilder
}

pub struct CellStore {
    chunks: BTreeMap<ChunkKey, Box<Chunk>>,
    /// Ограничивающий прямоугольник данных (UsedRange) / used-range bounds, кэш
    used: Option<Rect>,
    /// Карта «есть ли непустые в строке/столбце» для Ctrl+стрелок и UsedRange
    row_nonempty: RoaringBitmap, col_nonempty: RoaringBitmap,
}

Для колоночных агрегатов (SUM, COUNT, сортировка) чанк отдаёт итератор по столбцу col_iter(c) — в плотном представлении это шаг 256 слотов, в разреженном — проход по словам битовой карты с маской столбца; при импорте больших CSV используется ChunkBuilder, формирующий плотные чанки напрямую (без промежуточных вставок).

4.3 Значения

// kernel/crates/meridian-grid/src/value.rs

#[derive(Clone)]
pub enum Value {
    Empty,
    Number(f64),                       // число, дата, время, валюта, процент — тип в NumKind (см. extra/стиль)
    Text(Arc<str>),                    // общий текст из StringPool (интернирование: равные строки — один Arc)
    Bool(bool),
    Error(ErrorKind),                  // причина (ErrorInfo) — в side-table по ExtraId, чтобы не раздувать enum
    Array(Arc<Array>),                 // результат формулы (spill) или константа {…}; Array = rows×cols Vec<Value>
    Rich(Arc<RichValue>),              // богатый тип: запись с полями / изображение в ячейке (P1/P2)
}
// size_of::<Value>() == 24 (тег + fat pointer Arc<str>). Вариант уменьшения до 16 Б: ThinArc<str> (triomphe) —
// решение отложено до бенчмарков (§10). / 24 bytes; ThinArc option deferred until benchmarks.

/// Подтип числа — переносится формулами (§5.8.3) / numeric subtype propagated by formulas
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum NumKind { Plain, Date, Time, DateTime, Duration, Percent, Currency(CurrencyId), Fraction, Scientific }

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[repr(u8)]
pub enum ErrorKind {
    Null = 1, Div0 = 2, Value = 3, Ref = 4, Name = 5, Num = 6, NA = 7, GettingData = 8,
    Spill = 9, Connect = 10, Blocked = 11, Unknown = 12, Field = 13, Calc = 14,
}

/// Текст с форматированием фрагментов / rich text runs — хранится в side-table, Value::Text держит плоский текст
pub struct RichText { pub text: Arc<str>, pub runs: Vec<TextRun> }       // TextRun { start: u32, font: FontId }

Общие строки. StringPool — интернер (HashMap<Arc<str>, ()> + weak-подсчёт) с дедупликацией: текст столбца «Москва» в 100 000 строк хранится один раз; при экспорте в xlsx пул отображается в sharedStrings.xml напрямую. Строки короче 16 байт можно хранить inline (SSO) — отложено (§10).

Стили по индексам. StyleTable хранит уникальные CellStyle (шрифт, заливка, граница, число, выравнивание, защита — каждый сам по индексу в своей таблице, как cellXfs в xlsx); ячейка несёт только StyleId. Стили строк/столбцов («весь столбец зелёный») — в AxisProps, разрешение: ячейка → строка → столбец → «Обычный».

pub struct StyleTable {
    pub fonts: Vec<Font>, pub fills: Vec<Fill>, pub borders: Vec<Border>,
    pub numfmts: Vec<NumFmt>,            // код + скомпилированный формат (§5.10)
    pub xfs: Vec<CellXf>,                // комбинация индексов + выравнивание + защита; дедупликация по хэшу
    pub named: Vec<NamedStyle>,          // стили ячеек (Обычный, Заголовок 1, …), xf-наследование
    pub table_styles: Vec<TableStyle>,   // стили таблиц/сводных (элементы: wholeTable, headerRow, firstRowStripe, …)
    xf_index: HashMap<CellXf, StyleId>,
}

4.4 Строки и столбцы

/// Свойства оси (строки или столбцы) — RLE по диапазонам, чтобы 1M одинаковых строк занимали одну запись
/// Axis properties (rows or columns), run-length encoded by ranges
pub struct AxisProps {
    runs: Vec<AxisRun>,              // отсортированы по start, не пересекаются
    default_size: f32,               // высота 15 pt / ширина 8.43 символа (в единицах §5.17.1)
    outline_levels: u8,              // макс. уровень структуры (≤ 8)
    size_prefix: FenwickTree<f64>,   // префиксные суммы размеров для прокрутки/печати (ленивая перестройка)
}
pub struct AxisRun {
    pub start: u32, pub end: u32,          // включительно
    pub size: Option<f32>,                 // None = по умолчанию; для строк: ручная или автоподбор (флаг)
    pub custom_size: bool,                 // высота задана вручную (не пересчитывать автоподбор)
    pub hidden: bool, pub collapsed: bool, pub outline_level: u8,
    pub style: Option<StyleId>,            // стиль всей строки/столбца
    pub page_break: bool,
}

4.5 Объединённые ячейки

MergeIndex — список Rect + R-дерево (rstar) для запросов «в какое объединение входит (r,c)» при рендере, навигации и вставке. Значение и стиль живут в левой верхней ячейке; остальные пусты; формулы, ссылающиеся на внутренние ячейки, видят Empty (как Excel). Операции вставки/удаления строк корректируют прямоугольники; частичное пересечение объединения с удаляемым диапазоном — ошибка операции («нельзя изменить часть объединённой ячейки»), как в Excel.

4.6 Формулы: AST и байткод

Ячейка с формулой: CellSlot.extra → Extra::Formula { formula: FormulaId, base: CellRef }; Value хранит последний результат (кэш). Формулы хранятся общими: одна скомпилированная формула для =B2*C2, =B3*C3, … (относительные ссылки в R1C1-виде), base — ячейка, относительно которой разрешаются ссылки. Это копия механизма shared formulas xlsx и даёт 100-кратную экономию для столбцов из 1M формул.

// kernel/crates/meridian-calc/src/ast.rs

pub enum Expr {
    Num(f64), Str(Arc<str>), Bool(bool), Err(ErrorKind),
    ArrayConst(Arc<Array>),
    Ref(RefExpr),                                   // A1, $A$1, Лист!A1, Лист1:Лист3!A1, [Книга]Лист!A1
    Range(Box<Expr>, Box<Expr>),                    // оператор ':' между выражениями (INDEX(..):INDEX(..))
    Name(NameId),                                   // определённое имя / LET-переменная / параметр LAMBDA
    StructRef(StructRef),                           // Таблица1[[#Данные];[Сумма]]
    Spill(Box<Expr>),                               // A1#
    Call { func: FuncId, args: Vec<Expr> },         // функция (встроенная, UDF, LAMBDA)
    Unary(UnOp, Box<Expr>),                         // -x, +x, x%
    Binary(BinOp, Box<Expr>, Box<Expr>),            // + - * / ^ & = <> < > <= >= : , (union) ' ' (intersect)
    Implicit(Box<Expr>),                            // @expr — неявное пересечение
    Lambda { params: Vec<NameId>, body: Box<Expr> },
    Let { bindings: Vec<(NameId, Expr)>, body: Box<Expr> },
    Missing,                                        // пропущенный аргумент IF(A1;;B1)
}

/// Ссылка: каждая координата абсолютная или относительная (хранится относительно base формулы)
/// Reference: each coordinate absolute or relative (stored relative to formula base)
pub struct RefExpr {
    pub sheet: SheetRange,            // Current | One(SheetId) | Span(SheetId, SheetId) | External(LinkId, SheetName)
    pub r1: Coord, pub c1: Coord, pub r2: Coord, pub c2: Coord,   // Coord::Abs(u32) | Coord::Rel(i32) | Coord::All
    pub flags: RefFlags,              // row_span (1:1), col_span (A:A), trim (A.:.B — P2), deleted → #REF!
}

Байткод — стековая машина с типизированными операндами Val (как Value, плюс RangeRef — ленивая ссылка на диапазон, материализуемая только когда функция требует значения):

pub struct CompiledFormula {
    pub code: Vec<Op>,                 // линейный байткод
    pub consts: Vec<Value>,
    pub refs: Vec<RefExpr>,            // статические ссылки → регистрация в графе зависимостей
    pub flags: FormulaFlags,           // volatile, has_dynamic_refs (INDIRECT/OFFSET), array_result_possible, is_udf, is_legacy_cse
    pub src_hash: u64,                 // для дедупликации общих формул
}
#[repr(u8)]
pub enum Op {
    PushConst(u32), PushRef(u32), PushName(u32), PushStructRef(u32),
    Add, Sub, Mul, Div, Pow, Concat, Eq, Ne, Lt, Le, Gt, Ge, Neg, Pos, Percent,
    RangeOp, UnionOp, IntersectOp, SpillOp, ImplicitOp,
    Call { func: u16, argc: u8 },      // встроенная функция по индексу в каталоге
    CallLambda { argc: u8 }, CallUdf { id: u32, argc: u8 },
    JumpIfFalse(u32), Jump(u32),       // ленивые IF/IFS/IFERROR/SWITCH/AND/OR — короткое замыкание
    LetBind(u16), LetLoad(u16), LetPop(u16),
    MakeLambda { id: u32 },
    Ret,
}

4.7 Именованные диапазоны, таблицы, сводные, диаграммы

pub struct NamedItem {
    pub id: NameId, pub name: Arc<str>,          // имя: буквы/цифры/_/., не похоже на ссылку, уникально в области (без учёта регистра)
    pub scope: NameScope,                        // Workbook | Sheet(SheetId)
    pub def: NameDef,                            // Range(RefExpr) | Formula(FormulaId) | Const(Value) | Lambda(FormulaId, Vec<ParamDoc>) | TableRef(TableId)
    pub comment: Option<Arc<str>>, pub hidden: bool, pub builtin: Option<BuiltinName>, // _FilterDatabase, Print_Area, Print_Titles
}

pub struct Table {
    pub id: TableId, pub name: Arc<str>, pub sheet: SheetId, pub area: Rect,
    pub columns: Vec<TableColumn>,               // { name, id, calc_formula: Option<FormulaId>, totals: TotalsKind, dxf_ids }
    pub header_row: bool, pub totals_row: bool, pub style: TableStyleRef,
    pub style_opts: TableStyleOptions,           // row_stripes, col_stripes, first_col, last_col
    pub autofilter: Option<AutoFilter>, pub source: TableSource,   // Range | Query(ConnectionId) | Flow(FlowId)
}

pub struct PivotCache {
    pub id: CacheId, pub source: PivotSource,    // Range(SheetId, Rect) | Table(TableId) | Connection(ConnectionId) | Flow(FlowId)
    pub fields: Vec<CacheField>,                 // { name, kind: Text|Number|Date|Bool|Mixed, dict: Vec<Value>, stats: min/max/count, groups: Option<GroupSpec> }
    pub records: Vec<Vec<u32>>,                  // column-major: records[field][row] = индекс в dict (dictionary encoding); числа — dict тоже (сортированный)
    pub record_count: u32, pub refreshed_at: Timestamp, pub save_data: bool,
}
pub struct Pivot {
    pub id: PivotId, pub name: Arc<str>, pub cache: CacheId, pub sheet: SheetId, pub location: Rect,
    pub rows: Vec<PivotField>, pub cols: Vec<PivotField>, pub filters: Vec<PivotField>,
    pub values: Vec<DataField>,                  // { field, name, aggregate: Agg, show_as: ShowAs, numfmt }
    pub calc_fields: Vec<CalcField>, pub calc_items: Vec<CalcItem>,
    pub layout: PivotLayout,                     // Compact|Outline|Tabular, subtotals, grand totals, blank rows, repeat labels
    pub style: PivotStyleRef, pub options: PivotOptions, pub slicers: Vec<SlicerId>,
    pub rendered: Option<PivotRender>,           // кэш развёрнутой сетки для рендера/GETPIVOTDATA
}

pub struct ChartObject {                          // объект на листе; модель диаграммы — в meridian-chart
    pub id: ObjectId, pub anchor: Anchor,         // TwoCell { from, to, move_resize } | OneCell | Absolute
    pub chart: meridian_chart::Chart,             // типы, ряды (SeriesRef → RefExpr), оси, оформление
    pub pivot_source: Option<PivotId>,            // сводная диаграмма
}

4.8 Условное форматирование и проверка данных

Оба — «диапазоны-правила»: правило хранит sqref: Vec<Rect> и условие; индекс по R-дереву листа даёт для ячейки список правил при рендере/вводе. Формульные правила компилируются как обычные формулы с base = левая верхняя ячейка sqref (относительные ссылки сдвигаются для каждой ячейки — переиспользование общих формул).

pub struct CfRule {
    pub id: u32, pub sqref: Vec<Rect>, pub priority: i32, pub stop_if_true: bool,
    pub kind: CfKind, pub dxf: Option<DxfId>,     // DxfId — дифференциальный стиль (только изменяемые атрибуты)
}
pub enum CfKind {
    CellIs { op: CmpOp, f1: FormulaId, f2: Option<FormulaId> },
    Expression(FormulaId),
    ContainsText { kind: TextMatch, text: Arc<str> }, ContainsBlanks, NotContainsBlanks, ContainsErrors, NotContainsErrors,
    TimePeriod(TimePeriod), DuplicateValues, UniqueValues,
    Top { rank: u32, percent: bool, bottom: bool }, AboveAverage { below: bool, equal: bool, std_dev: u8 },
    DataBar(DataBar),                             // min/max: Cfvo{Auto|Min|Max|Num|Percent|Percentile|Formula}, color, gradient, negative, axis, direction
    ColorScale(Vec<(Cfvo, Color)>),               // 2 или 3 точки
    IconSet { set: IconSetId, thresholds: Vec<(Cfvo, CmpGte)>, reverse: bool, icons_only: bool, custom: Option<Vec<IconRef>> },
}
pub struct Validation {
    pub sqref: Vec<Rect>, pub kind: ValidationKind,   // Any | Whole | Decimal | List | Date | Time | TextLength | Custom(FormulaId) | Regex(Arc<str>)
    pub op: CmpOp, pub f1: Option<FormulaId>, pub f2: Option<FormulaId>,
    pub allow_blank: bool, pub show_dropdown: bool,
    pub input: Option<(Arc<str>, Arc<str>)>, pub error: Option<(ErrorStyle, Arc<str>, Arc<str>)>,
}

4.9 Прочие структуры листа

4.10 Ограничения и «большой режим»

Большой режим включается на книгу при импорте файла с > 2^20 строк (CSV, Parquet, БД) или вручную; книга помечается флагом big_mode, экспорт в xlsx/ods обрезает с предупреждением (§7). В большом режиме сетка та же, но импорт «ленивый»: чанки материализуются из источника при первом обращении (ChunkSource::Lazy(ParquetRowGroup)), а агрегатные функции по целым столбцам идут потоком по источнику. Ограничение памяти: ~40 Б/ячейку → 10M заполненных ячеек ≈ 400 МБ; выше — предупреждение и предложение открыть в Base.

4.11 Операции, undo и CRDT

Все изменения модели — значения перечисления Op; Workbook::apply(op) -> Result<Inverse> выполняет и возвращает обратную операцию; undo — стек обратных операций, объединяемых в группы (Transaction) по действию пользователя. Журнал операций пишется в history/ пакета (автосохранение каждые 2 с — §6 библии) и в фазе 6 отображается в CRDT Yrs: лист = YMap<cell_key → YMap{v,f,s}> + YArray порядка строк/столбцов для корректного слияния вставок.

pub enum Op {
    SetCells { sheet: SheetId, cells: Vec<(CellRef, CellPatch)> },         // значения/формулы/стили, пакетно
    InsertRows { sheet: SheetId, at: u32, count: u32 }, DeleteRows { sheet: SheetId, at: u32, count: u32 },
    InsertCols { .. }, DeleteCols { .. },
    InsertCells { sheet, rect, shift: ShiftDir }, DeleteCells { .. },
    MoveRange { sheet, from: Rect, to: CellRef, to_sheet: SheetId },        // вырезать-вставить с переадресацией ссылок
    SetAxis { sheet, axis: Axis, runs: Vec<AxisRun> }, Merge { sheet, rect }, Unmerge { .. },
    SheetAdd { .. }, SheetDelete { .. }, SheetRename { .. }, SheetMove { .. }, SheetProps { .. },
    NameSet { .. }, NameDelete { .. }, TableOp(TableOp), PivotOp(PivotOp), ChartOp(ChartOp), ObjectOp(ObjectOp),
    CfOp(CfOp), ValidationOp(ValidationOp), FilterOp(FilterOp), SortRows { sheet, rect, permutation: Vec<u32> },
    NoteOp(..), ThreadOp(..), HyperlinkOp(..), ProtectionOp(..), WorkbookProps(..),
    Batch(Vec<Op>),                                                         // атомарная группа (одна запись undo)
}

Правила слияния CRDT для таблиц (фаза 6, детали — docs/03-architecture.md (раздел о совместной работе)): ячейка — регистр «последний пишущий побеждает» по часам Лэмпорта (LWW) — одновременная правка одной ячейки двумя людьми разрешается детерминированно, а «проигравшее» значение показывается в истории; вставка строк — позиция в YArray (строки получают стабильные RowId, индексы вычисляются), поэтому одновременные вставки не затирают друг друга; удаление строки с чужой одновременной правкой в ней — правка сохраняется в «корзине конфликтов» и показывается в панели.

5. Алгоритмы

Крейт meridian-calc (кроме §5.17–5.21, которые в meridian-grid и оболочке).

5.1 Лексер формул

Вход — строка формулы в локали ввода (FormulaLocale { arg_sep: ';' | ',', decimal: ',' | '.', array_row_sep, array_col_sep, func_names: &LocaleTable, bool_names }); хранение формулы — всегда канонический английский вид (, аргументы, . десятичная, английские имена), поэтому лексер применяется дважды: при вводе (локаль пользователя → канон) и при отображении (канон → локаль).

Токены:

pub struct Lexer<'a> { src: &'a str, pos: usize, loc: &'a FormulaLocale, mode: RefMode /* A1 | R1C1 */ }
impl<'a> Lexer<'a> {
    pub fn next_token(&mut self) -> Result<Token, LexError> {
        self.skip_ws_recording_intersection();          // пробел между двумя ссылочными токенами → Token::Intersect
        let c = self.peek()?;
        match c {
            '"' => self.string(),
            '#' if self.at_error_literal() => self.error_literal(),
            '#' => Ok(Token::Op(Op::Spill)),
            '\'' | '[' => self.sheet_or_external_prefix_or_structref(),
            c if c.is_ascii_digit() || (c == self.loc.decimal && self.peek_at(1).is_ascii_digit()) => self.number(),
            c if is_name_start(c) => self.ident_or_ref(),   // решает: FuncName (если далее '('), CellRef, ColRef, Bool, Name
            _ => self.operator_or_punct(),
        }
    }
}

Разбор идентификатора: регулярный вид ^\$?[A-Za-z]{1,3}\$?\d{1,7}$ с проверкой границ (col ≤ XFD, row ≤ 1048576 или 2^31 в большом режиме) → CellRef; в R1C1-режиме — ^R(\[-?\d+\]|\d+)?C(\[-?\d+\]|\d+)?$; TRUE/FALSE и локальные формы → Bool; имя функции — если следующий непробельный символ ( (таблица имён по локали, затем английская, затем _xlfn.); иначе — Name (имена не чувствительны к регистру, нормализуются NFC + upper для поиска).

5.2 Парсер (Pratt)

Грамматика Excel с приоритетами (от высшего к низшему):

// kernel/crates/meridian-calc/src/parser.rs — Pratt-парсер / Pratt parser

pub struct Parser<'a> { lex: Peekable<Lexer<'a>>, ctx: &'a ParseCtx /* книга, текущий лист, имена, таблицы, функции */ }

impl<'a> Parser<'a> {
    pub fn parse_formula(&mut self) -> Result<Expr, ParseError> {
        let e = self.expr(0)?;
        self.expect_eof()?;                         // лишние токены → "#NAME?" при вводе → диалог исправления (как Excel предлагает)
        Ok(e)
    }

    /// Разбор выражения с минимальной силой связывания / parse expression with min binding power
    fn expr(&mut self, min_bp: u8) -> Result<Expr, ParseError> {
        let mut lhs = self.prefix()?;
        loop {
            let tok = match self.lex.peek() { Some(t) => t, None => break };
            // постфиксные / postfix: % и #
            if let Some(bp) = postfix_bp(tok) {
                if bp < min_bp { break; }
                let t = self.lex.next().unwrap();
                lhs = match t { Token::Op(Op::Percent) => Expr::Unary(UnOp::Percent, lhs.into()),
                                Token::Op(Op::Spill)   => Expr::Spill(lhs.into()), _ => unreachable!() };
                continue;
            }
            let Some((lbp, rbp)) = infix_bp(tok) else { break };    // (lbp, rbp): лево-ассоц. — rbp = lbp+1
            if lbp < min_bp { break; }
            let op = self.lex.next().unwrap();
            let rhs = self.expr(rbp)?;
            lhs = self.make_binary(op, lhs, rhs)?;   // ':' требует ссылочных операндов: A1:B2, INDEX():INDEX(), Имя:Имя
        }
        Ok(lhs)
    }

    fn prefix(&mut self) -> Result<Expr, ParseError> {
        match self.lex.next() {
            Some(Token::Number(n)) => Ok(Expr::Num(n)),
            Some(Token::String(s)) => Ok(Expr::Str(s)),
            Some(Token::Bool(b))   => Ok(Expr::Bool(b)),
            Some(Token::Error(e))  => Ok(Expr::Err(e)),
            Some(Token::Op(Op::Minus)) => Ok(Expr::Unary(UnOp::Neg, self.expr(bp::UNARY)?.into())),
            Some(Token::Op(Op::Plus))  => Ok(Expr::Unary(UnOp::Pos, self.expr(bp::UNARY)?.into())),
            Some(Token::Op(Op::At))    => Ok(Expr::Implicit(self.expr(bp::UNARY)?.into())),
            Some(Token::LParen) => { let e = self.union_list()?; self.expect(Token::RParen)?; Ok(e) }  // (A1,B2) — объединение
            Some(Token::LBrace) => self.array_const(),
            Some(Token::FuncName(name)) => self.call(name),         // LET/LAMBDA — особые: вводят области имён
            Some(Token::CellRef(r)) | Some(Token::ColRef(r)) | Some(Token::RowRef(r)) => Ok(Expr::Ref(r)),
            Some(Token::SheetPrefix(sh)) => self.ref_after_sheet(sh),   // Лист!A1, Лист1:Лист3!A1:B2, Лист!Имя
            Some(Token::StructRef(sr)) => Ok(Expr::StructRef(self.resolve_struct(sr)?)),
            Some(Token::Name(n)) => Ok(self.resolve_name(n)?),      // имя книги/листа/таблицы/LET-переменная/параметр λ, иначе Name(unresolved) → #NAME?
            t => Err(ParseError::Unexpected(t)),
        }
    }

    fn call(&mut self, name: FuncName) -> Result<Expr, ParseError> {
        let mut args = Vec::new();
        if !self.eat(Token::RParen) {
            loop {
                args.push(if self.peek_is_sep_or_rparen() { Expr::Missing } else { self.expr(0)? });
                if self.eat(Token::ArgSep) { continue; }
                self.expect(Token::RParen)?; break;
            }
        }
        match name {
            FuncName::Let    => self.build_let(args),              // пары (имя, значение)…, тело; имена видны в последующих парах
            FuncName::Lambda => self.build_lambda(args),           // параметры…, тело; при вызове LAMBDA(..)(x) — Call на Lambda
            FuncName::Builtin(id) => { self.ctx.check_arity(id, args.len())?; Ok(Expr::Call { func: id, args }) }
            FuncName::Udf(id) => Ok(Expr::Call { func: FuncId::Udf(id), args }),
            FuncName::Unknown(s) => Ok(Expr::Call { func: FuncId::Unknown(s), args }),  // → #NAME? при вычислении, но формула сохраняется
        }
    }
}

Особенности:

• Локализация. ArgSep берётся из локали; при вводе =SUM(A1,B1) в ru-локали парсер даёт ошибку «ожидалась ;» с предложением автоисправления (как Excel). Имена функций ищутся в локальной таблице, затем в английской (пользователь может писать по-английски в любой локали).
• Ссылки R1C1 разбираются относительно ячейки формулы (ParseCtx.base); хранение — всегда R1C1-подобное (относительные смещения), отображение — по режиму книги.
• 3D-ссылки Лист1:Лист3!A1 разворачиваются в SheetRange::Span, порядок листов берётся из книги на момент вычисления (перемещение листов меняет состав — как в Excel).
• Структурированные ссылки резолвятся в StructRef { table, item: Data|Headers|Totals|All|ThisRow, cols: Option<(ColId, ColId)> } по идентификаторам столбцов, поэтому переименование столбца не ломает формулы (при отображении — текущее имя).
• Внешние ссылки [Книга.xlsx]Лист!A1 → SheetRange::External(link, sheet); значения берутся из кэша связи.
• Отображение (Expr → String) — обратный проход с минимальной расстановкой скобок по тем же приоритетам, локализацией имён, разделителей и десятичной точки; форматирование «красиво» (переносы и отступы по вложенности) — опция редактора.

5.3 Компиляция в байткод

compile(expr, base):
  walk(expr):
    Num/Str/Bool/Err → PushConst(idx)
    Ref r            → refs.push(normalize_relative(r, base)); PushRef(idx)      // относительные → смещения
    Name n           → PushName(id)   (имя → при выполнении: Range/Const/Formula; LET-переменные → LetLoad(slot))
    Binary(op,a,b)   → walk(a); walk(b); Op
    Unary            → walk(x); Neg/Pos/Percent
    Call{IF,[c,t,e]} → walk(c); JumpIfFalse(L1); walk(t); Jump(L2); L1: walk(e); L2:     // ленивость
    Call{AND/OR/IFS/SWITCH/IFERROR/IFNA/CHOOSE} → аналогично с короткими замыканиями
    Call{f,args}     → for a in args: walk(a) (Missing → PushConst(Missing)); Call{f, argc}
    Let              → for (n,v): walk(v); LetBind(slot) ; walk(body); LetPop(count)
    Lambda           → MakeLambda(id)  (тело компилируется отдельно; захват LET-слотов по значению)
    Spill(x)         → walk(x); SpillOp         Implicit(x) → walk(x); ImplicitOp
  flags.volatile = любой вызов из VOLATILE = {NOW, TODAY, RAND, RANDBETWEEN, RANDARRAY, INFO (всегда),
                   CELL с аргументами среды ("filename", "address" без ссылки, "protect", "width")}
  flags.has_dynamic_refs = INDIRECT | OFFSET | INDEX с диапазоном-результатом | ADDRESS→INDIRECT
  Общие формулы: src_hash = hash(code, consts, refs) — одинаковые относительные формулы соседних ячеек делят CompiledFormula.

Аргументы функций имеют декларированные типы в каталоге (ArgKind: Number | Text | Bool | Any | Range | RangeOrArray | Lambda | Criteria); при Call интерпретатор приводит операнды по правилам Excel (§5.8) и выполняет лифтинг по массивам: если функция скалярная, а операнд — массив/диапазон в контексте динамических массивов, функция применяется поэлементно (с расширением по правилам broadcasting: 1×N против M×1 → M×N; несовпадающие размеры → #N/A в лишних позициях).

5.4 Граф зависимостей

pub struct DependencyGraph {
    /// прямые ссылки на ячейки: ячейка → формулы, которые её читают / cell → dependent formulas
    cell_deps: HashMap<(SheetId, CellRef), SmallVec<[FormulaCell; 2]>>,
    /// диапазонные слушатели: R-дерево по листу (прямоугольник → формулы) / range listeners per sheet (R-tree)
    range_deps: HashMap<SheetId, RTree<RangeListener>>,
    /// крупные диапазоны (≥ 1 чанка или целые строки/столбцы): по чанкам, чтобы не раздувать R-дерево
    chunk_deps: HashMap<(SheetId, ChunkKey), SmallVec<[FormulaCell; 4]>>,
    col_deps: HashMap<(SheetId, u32), Vec<FormulaCell>>, row_deps: HashMap<(SheetId, u32), Vec<FormulaCell>>,
    /// имена и таблицы: имя → формулы, использующие имя / name → formulas
    name_deps: HashMap<NameId, Vec<FormulaCell>>, table_deps: HashMap<TableId, Vec<FormulaCell>>,
    /// динамические зависимости (INDIRECT/OFFSET): формула → фактически прочитанные диапазоны в прошлом расчёте
    dynamic: HashMap<FormulaCell, Vec<ReadRange>>,
    volatile: HashSet<FormulaCell>,
    /// порядок последнего успешного расчёта (calc chain) — начальное приближение для топологии
    calc_chain: Vec<FormulaCell>,
}

Регистрация формулы: для каждого RefExpr после разрешения относительно base: одиночная ячейка → cell_deps; прямоугольник < 1 чанка → range_deps (R-дерево rstar с AABB<[u32;2]>); иначе → chunk_deps по всем покрываемым чанкам (целые столбцы/строки → col_deps/row_deps, чтобы SUM(A:A) не регистрировалось в 4096 чанках). Запрос «кто зависит от (r,c)»: объединение cell_deps[(r,c)], точечный запрос в R-дерево, chunk_deps[chunk(r,c)], col_deps[c], row_deps[r].

INDIRECT/OFFSET — в Excel волатильны (пересчитываются всегда). У нас: формула с has_dynamic_refs после каждого вычисления записывает фактически прочитанные диапазоны в dynamic и регистрирует их как обычные слушатели (с пометкой «динамический»); при следующем изменении этих ячеек она становится грязной. Результат идентичен Excel (функции детерминированы), но без пересчёта на каждое нажатие. Опция совместимости «считать INDIRECT/OFFSET волатильными» — для книг, где это важно (например, OFFSET над изменяющимся через скрипт диапазоном без ссылок). Истинно волатильные (NOW, RAND, …) — в volatile, грязны при каждом пересчёте.

5.5 Пересчёт

recalc(trigger: Changed{cells} | Full | FullRebuild):
  1. dirty := ∅
     для каждой изменённой ячейки c: dirty ∪= dependents(c)      // BFS по графу, посещённое не повторяем
     dirty ∪= volatile; при Full — все формулы; при FullRebuild — перестроить граф из всех формул
  2. Разбиение на компоненты: union-find по рёбрам между грязными формулами → компоненты K1..Kn
     (рёбра: f → g, если g читает ячейку, которую пишет f; для spill — весь spill-диапазон)
  3. Для каждой компоненты параллельно (rayon, пул = ядра − 1; компоненты > 50k формул делятся уровнями):
       order := топологическая сортировка (Kahn) по подграфу компоненты, начальное приближение — calc_chain
       если найден цикл (остались вершины с in-degree > 0):
           scc := Tarjan(остаток)
           если iterative_calc выключен: все ячейки scc ← 0 + флаг Circular; сообщить в строку состояния
           иначе: повторять вычисление scc в порядке calc_chain до max_iter или |Δ| < max_change для всех
       для f in order: результат ← eval(f) → буфер результатов (не в сетку: другие потоки читают старые значения
         только своих компонент; компоненты независимы по построению)
  4. commit: буферы → сетка (одним проходом, с обновлением spill-диапазонов и типов NumKind), calc_chain := конкатенация порядков
  5. уведомления: рендер (изменённые прямоугольники), условное форматирование, диаграммы, сводные (если «автообновление»),
     скрипты (onRecalc)

Детали:

• Вычисление по требованию внутри компоненты. eval(f) при чтении операнда, который грязен и ещё не вычислен (возможно при неполной топологии из-за динамических ссылок), вычисляет его рекурсивно (явный стек, глубина не ограничена рекурсией Rust); повторное попадание в стек = цикл.
• Инкрементальность. Пересчитываются только грязные; формула, чьё значение не изменилось (по Value::eq с учётом точности), не помечает своих зависимых («отсечение по равенству»), что сильно уменьшает каскады.
• Отмена. Длинный пересчёт идёт в фоне порциями, UI показывает «Вычисление: N %» и кнопку остановки; при остановке грязные остаются грязными, строка состояния показывает «Вычислить» (как Excel в ручном режиме).
• Профайлер. В режиме профилирования каждая формула получает elapsed и calls; панель SH-16 показывает топ-50.
• Вставка/удаление строк и столбцов (сдвиг ссылок). shift_refs(sheet, axis, at, delta): через R-дерево/chunk_deps находятся все формулы со ссылками на лист, пересекающие или лежащие ниже/правее at; для каждой ссылки:
  • полностью ниже/правее → смещение координат (абсолютные и относительные — одинаково; относительные смещения формул, чьи base тоже сдвинулись, не меняются);
  • пересекает диапазон вставки → расширяется (вставка внутри диапазона) или остаётся (вставка на границе — как Excel: вставка строки под последней строкой SUM(A1:A5) не расширяет; опция «расширять диапазоны при вставке на границе» — P1, выключена по умолчанию для совместимости);
  • полностью внутри удаляемого → #REF! (ссылка помечается deleted, формула показывает #REF! на месте ссылки);
  • частично пересекает удаляемое → сжимается. То же — для имён, таблиц, сводных, диаграмм, УФ, проверок, объединений, спарклайнов, гиперссылок, обсуждений, разрывов. Общие формулы: сдвигаются один раз на CompiledFormula, если все ячейки-владельцы сдвинулись одинаково; иначе — расщепление.
• Перемещение (вырезать-вставить) диапазона: ссылки на перемещённые ячейки следуют за ними (как Excel), ссылки внутри перемещённых формул не меняются.

5.6 Динамические массивы и spill

after eval(f) at anchor A:
  если результат — Array(rows×cols) и формула не legacy-CSE:
     target := Rect(A, rows, cols); clip по границам листа (выход за край → #SPILL! «выходит за пределы листа»)
     blockers := ячейки в target \ {A}, у которых непустое значение или формула, или которые входят в объединение,
                 или принадлежат структурированной таблице (в таблицах spill запрещён — как в Excel)
     если blockers ≠ ∅: A ← Error(Spill, info{blockers}); очистить прошлый spill-диапазон A (если был)
     иначе: записать значения в target; ячейки target \ {A} получают Extra::SpillChild{anchor: A} (без формулы,
            не редактируются «как есть»: ввод в такую ячейку делает её блокером → A становится #SPILL!, при очистке — восстанавливается)
     зарегистрировать f как «пишущую» в target → зависимые от target становятся грязными
  если результат скаляр, а раньше был spill → очистить старый диапазон

• A1# → Expr::Spill: ссылка на текущий spill-диапазон якоря (зависимость от размера — ячейка-якорь); если A1 не якорь — #REF!.
• @expr (неявное пересечение): массив/диапазон → значение на пересечении со строкой/столбцом формулы, иначе #VALUE!. При импорте формул из старых xlsx (без cm метаданных) все ссылки, где старый Excel применял неявное пересечение, обёртываются в @ — так же, как делает Excel 365; при экспорте @ пишется как есть, а формулы с динамическими результатами — с t="array" + cm="1" (метаданные XLDAPR).
• Legacy CSE {=...}: вычисляется в массивном контексте, результат пишется только в заданный диапазон (обрезка/#N/A при нехватке), отображается в фигурных скобках, редактируется только целиком.
• Размер spill меняется динамически; при пересчёте, если новая область пересекает другие spill-области, порядок разрешения — по порядку вычисления; взаимные блокировки дают #SPILL! обоим, что совпадает с Excel.

5.7 Ошибки

Распространение: ошибка в операнде → ошибка результата; при нескольких — первая по порядку вычисления аргументов (слева направо), как в Excel. Функции IFERROR, IFNA, ISERROR, ISERR, ISNA, ERROR.TYPE, AGGREGATE (опция игнорирования), SUMIF-семейство (пропуск ошибок в диапазоне суммирования не выполняется — как Excel) — единственные, кто «видит» ошибку как значение. Ошибки в массиве — поэлементны.

5.8 Числовая точность и приведение типов

1. Представление. IEEE 754 f64. Отображение — не более 15 значащих цифр (Общий), вычисления — полная точность. Сохранение в xlsx — через кратчайшее round-trip представление (алгоритм Ryū), не 15-значное, чтобы не терять биты.
2. Сравнение. Операторы =, <>, <, <=, >, >= и функции поиска сравнивают числа через approx_eq (как LibreOffice rtl::math::approxEqual): равны, если |a−b| ≤ 2^-48·max(|a|,|b|) (≈ 15,6 десятичных цифр). Это даёт =0.1+0.2=0.3 → TRUE. Опция книги «строгое сравнение IEEE» выключает. Excel поведение — ровное сравнение битов, но с «косметической» коррекцией (п. 3); на корпусе тестов различия с Excel зафиксированы как допустимые.
3. Косметическая коррекция вычитания (как Excel): если последняя операция формулы — +/- и |result| < 2^-50·max(|a|,|b|), результат → 0. Применяется только к финальной операции (=(0.1+0.2-0.3) в скобках Excel не корректирует; мы — тоже).
4. Округление. ROUND работает через десятичное представление (строка 17 значащих → округление → парсинг), чтобы ROUND(2.675;2) = 2.68, как в Excel, а не 2.67 как в наивном f64.
5. Приведение типов (в скалярных операциях): текст → число по правилам ввода локали книги ("1 000,5", "12%", "03.10.2026" → сериал, "1e3"), иначе #VALUE!; Bool → 0/1; Empty → 0 ("" в текстовом контексте); число → текст по формату Общий при &; в SUM-семействе текстовые и логические в диапазонах игнорируются, в аргументах-литералах — приводятся (как Excel: SUM("3")=3, SUM(A1) с "3" = 0).
6. NumKind переносится: дата + число → дата, дата − дата → длительность (отображается как число дней, формат по умолчанию «Общий» — как Excel, но тип Duration позволяет «Формат: длительность» в один клик), валюта × число → валюта, валюта(RUB) + валюта(USD) → #VALUE! при включённой проверке валют, процент сохраняется только для ×/÷ на скаляр. Правило: результат формулы получает NumKind по таблице операций, числовой формат ячейки при первом вводе формулы подбирается автоматически (как Excel: =A1+1 над датой форматируется датой).

5.9 Даты и время

• Сериал: 1 = 1900-01-01 (система 1900), дробь — доля суток (0.5 = 12:00). Время хранится как f64, точность ~ 1 мкс для дат XXI века.
• Ошибка 1900 года воспроизводится: сериал 60 = «1900-02-29» (несуществующий день); для сериалов ≤ 60 преобразования сериал ↔︎ дата используют календарь с високосным 1900 годом; WEEKDAY для дат до 1900-03-01 — как в Excel (т.е. неверно на 1 день, для совместимости). Сериал 0 = «1900-01-00» (отображение времени без даты).
• Система 1904 (флаг книги, Mac Excel ≤ 2011): 0 = 1904-01-01, без ошибки високосного года; при переключении системы значения ячеек не меняются (даты «сдвигаются» на 1462 дня — как в Excel, с предупреждением).
• Диапазон дат: 1900-01-01 … 9999-12-31 (отрицательные сериалы → #####; опция «отрицательные даты» — P2).
• Разбор ввода: порядок полей по локали (dd.mm.yyyy ru, m/d/yyyy en-US), двузначный год (00–29 → 20xx, 30–99 → 19xx, настраивается), названия месяцев (полные/сокращённые, локаль + английский), ISO 8601 всегда, T-разделитель, время h:mm, h:mm:ss, AM/PM, [h] > 24. Опция «не распознавать даты при вводе/импорте» (частая боль CSV).
• Функции календаря: пролептический григорианский; NETWORKDAYS.INTL с масками выходных "0000011"; DATEDIF — по алгоритму Excel с его известной особенностью "MD" (может давать отрицательные/неверные значения для некоторых пар — воспроизводим документированно, с предупреждением в справке).
• Локальное время: NOW()/TODAY() — локальный часовой пояс системы; часовые пояса в значениях не хранятся (как Excel); MS.NOWUTC() — расширение.

5.10 Числовые форматы

5.10.1 Грамматика кода формата

format      := section (';' section){0,3}            // положительные ; отрицательные ; ноль ; текст
section     := condition? color? locale? body
condition   := '[' ('<' | '<=' | '>' | '>=' | '=' | '<>') number ']'
color       := '[' ('Black'|'Blue'|'Cyan'|'Green'|'Magenta'|'Red'|'White'|'Yellow'|'Color' 1..56) ']'   // локализованные имена тоже
locale      := '[$' currency_symbol? ('-' LCID_hex)? ']'          // [$₽-419], [$-F800] (системная длинная дата), [$-x-sysdate]
body        := token*
token       := '0' | '#' | '?' | '.' | ',' | '%' | 'E+' | 'E-' | '/' | '"text"' | '\' char | '_' char | '*' char
             | 'General' | '@' | date_token | elapsed_token | literal_safe_char (' ', '-', '+', '(', ')', ':', '$', …)
date_token  := 'yy' | 'yyyy' | 'm' | 'mm' | 'mmm' | 'mmmm' | 'mmmmm' | 'd' | 'dd' | 'ddd' | 'dddd' | 'h' | 'hh' | 's' | 'ss'
             | 'AM/PM' | 'A/P' | 'am/pm' | '.0' | '.00' | '.000' (доли секунды) | 'e' (эра) | 'g','gg','ggg' (яп. эра) | 'b' (буддийский год)
elapsed_token := '[h]' | '[hh]' | '[m]' | '[mm]' | '[s]' | '[ss]'

Компиляция (meridian-numfmt): код → CompiledFormat { sections: [Section; ≤4], kind_hint: NumKind }, где секция — список инструкций (Digit{zero,space,hash}, Group, Decimal, Percent, Exponent, Fraction{den_digits|fixed}, Literal, Fill(char), Pad(char), Text, DateTime(part), Elapsed(unit), General) + условие + цвет + локаль. Неоднозначность m (месяц/минута) разрешается по контексту: после h/hh или перед s/ss — минуты. Кэш скомпилированных форматов по коду.

5.10.2 Выбор секции и рендер

render(value, fmt, locale):
  если value — Text: секция 4 (если есть) с '@', иначе текст как есть
  если Bool/Error: как в General
  секция := по условиям [..] если заданы; иначе: 1 секция — все числа; 2 — (≥0, <0 с автознаком '-' отбрасываемым);
            3 — (>0, <0, =0); 4 — (+, −, 0, текст)
  x := |value| если секция отрицательных и условие не задано явно (знак рисует сама секция: "(#,##0)" или "-")
  если секция дата/время: разложить сериал (с ошибкой 1900 г., AM/PM, elapsed [h] = floor(x·24) и т.д.), подставить части,
     локализованные названия месяцев/дней по [$-LCID] или локали книги, доли секунды с округлением
  иначе числовая секция:
     масштаб: ×100 за каждый '%', ÷1000 за каждую запятую в конце целой части (`#,##0,` → тысячи), E+/E- → мантисса/экспонента
     дробь '# ?/?': подобрать знаменатель (цепные дроби, ограничение по числу '?' или фиксированный знаменатель)
     округлить до числа десятичных плейсхолдеров (0/#/?), переполнение разрядов — расширить целую часть
     собрать строку: целая часть с группировкой по ',' (разделители из locale), литералы, '_x' → пробел ширины x,
     '*x' → заполнитель (расширяется до ширины ячейки при рендере), '?' → пробел-цифра
  результат: DisplayString { text, color: Option<Color>, fill: Option<(pos, char)>, align_hint }

5.10.3 Локализация

Разделители группы/десятичной — из локали книги (не ОС), переопределяются [$-LCID] и настройками Параметров; названия месяцев/дней — ICU4X; валюты из [$€-407] отображаются как записано. При экспорте в xlsx коды пишутся без изменений; встроенные форматы (numFmtId 0–49 и локальные 164+) отображаются на таблицу Excel.

5.10.4 Формат «Общий»

Подбор представления под ширину столбца (как Excel): целое → как есть; если не влезает — десятичные обрезаются до влезающих; если целая часть не влезает (или число ≥ 1e11 / < 1e-? при 11 символах) → экспоненциальный #.##E+## с уменьшением мантиссы; минимум 1E+10-подобное; если и это не влезает → #####. Текст не обрезается (переливается в соседние пустые ячейки вправо, если выравнивание общее/левое). Отрицательные числа при ##### — тоже решётки.

5.11 Автозаполнение

5.11.1 Распознавание серии (маркер заполнения, Прогрессия → «автозаполнение»)

detect_series(cells: &[CellSlot]) -> Series:
  если все формулы              → Series::CopyFormulas (относительные ссылки сдвигаются по позиции)
  если все числа (NumKind::Plain):
      1 ячейка                  → Copy (с Ctrl → Linear{step: 1})
      ≥2                        → Linear{step: by least squares} если точки лежат на прямой (|resid| < 1e-9·scale), иначе
                                   LinearTrend (МНК по всем точкам — как Excel «Прогрессия с трендом»)
  если все даты/время:
      шаг := разность сериалов; если разности равны целым дням → Date{Day, step}
      если даты — одинаковое число месяца и шаг в месяцах равен → Date{Month, step}; то же для Year
      если одинаковый день/месяц, шаг в годах → Date{Year, step}; время → Linear по сериалу
  если все тексты:
      t = разобрать как <prefix><число><suffix> (число — последняя группа цифр, ведущие нули сохраняются по ширине):
         одинаковые prefix/suffix и числа образуют арифметическую прогрессию → TextNumber{step, width}
      иначе искать в списках: дни недели (полные/короткие, локаль + en), месяцы, кварталы ("Кв1", "Q1", "1-й квартал"),
         пользовательские списки (SH-25): элемент найден → ListSeries{list, start_index, step по позициям, циклично}
      иначе → Copy
  смешанные типы → Copy (с чередованием блока: Excel повторяет блок как шаблон — воспроизводим: Pattern{block})
apply: для i-й новой ячейки — значение по серии; стиль копируется циклически из исходного блока («только форматы» / «без форматов» — опции);
       при заполнении вверх/влево — шаг отрицателен

Двойной клик по маркеру: заполнение вниз до последней непустой строки соседних столбцов (слева, затем справа), с остановкой на первой пустой в целевом столбце (как Excel).

5.11.2 Прогрессия (диалог SH-51)

Арифметическая (a + i·step), геометрическая (a · step^i), даты (единицы день/рабочий день/месяц/год — с нормализацией конца месяца: 31.01 + 1 мес = 28.02), «автозаполнение» (п. 5.11.1), «тренд» (МНК линейный/экспоненциальный по выделенным, заменяет значения), предел.

5.11.3 Заполнение по образцу (Flash Fill, P1)

Синтез программ в DSL над строками (упрощённый FlashFill/PROSE): примеры — пары (входная строка соседних столбцов, выход). DSL: Concat(atom…), где atom ∈ { Const(s), SubStr(col, pos1, pos2), Case(atom, Upper|Lower|Proper), NumFmt(atom, fmt), DatePart(col, part) }, pos ∈ { Abs(k), RegexMatch(token_regex, occurrence, start|end) } с токенами (цифры, буквы, пробелы, знаки, заглавные). Алгоритм: для каждого примера строится граф всех способов получить каждую подстроку выхода из входа (DAG путей); программы — пересечение DAG-ов по примерам; ранжирование: меньше констант, больше регулярных токенов, короче. Применяется к остальным строкам; результат показывается серым (предпросмотр), подтверждается Enter; расхождения с новыми примерами переобучают. Ограничение: ≤ 10 входных столбцов, строки ≤ 256 символов, время синтеза ≤ 200 мс (иначе — «не удалось распознать образец»).

5.12 Сортировка

sort(range, keys: [SortKey{col|row, by: Value|CellColor|FontColor|Icon, order: Asc|Desc|CustomList(id)|ColorOnTop(c)}],
     opts: {case_sensitive, orientation, has_header, locale})
  1. извлечь строки (или столбцы) как массив индексов perm = [0..n)
  2. компаратор по ключам (последовательно, первый ненулевой):
       Value: ранг типа Number < Text < Bool < Error < Empty (Empty всегда последним при любом порядке — как Excel);
              числа — по значению (approx_eq → 0); текст — ICU Collator(locale, strength = Secondary или Tertiary при case_sensitive,
              numeric=on при опции «естественная сортировка 'a2' < 'a10'» — P1); Bool: FALSE < TRUE; ошибки — порядок ERROR.TYPE
       CellColor/FontColor/Icon: заданный цвет/значок наверх (или вниз); остальные — сохраняют порядок
       CustomList: позиция в списке (нет в списке → после, по значению)
  3. стабильная сортировка perm (merge sort / `slice::sort_by` — стабильный в Rust); 1M строк ≈ 0,3–0,6 с (ключи
     предвычислены в массив `SortKeyVec` — числа как f64, текст как ICU sort key `Vec<u8>` для memcmp)
  4. применить Op::SortRows{permutation}: перестановка слотов построчно во всех столбцах диапазона (значения, стили, extra),
     объединения внутри диапазона → ошибка «нельзя сортировать объединённые ячейки разного размера» (как Excel);
     формулы: относительные ссылки *внутри* строки сохраняются (строка переезжает целиком), ссылки на другие строки диапазона —
     не корректируются (как Excel; предупреждение в справке)
  5. строки, скрытые вручную, сортируются вместе с остальными; строки, скрытые автофильтром, в сортировке не участвуют и остаются
     на месте (поведение Excel)

Сортировка по столбцам (orientation = Columns) — симметрично. Undo — обратная перестановка.

5.13 Автофильтр и расширенный фильтр

apply_autofilter(af):
  hidden := RoaringBitmap::new()
  для каждой строки r в области (кроме заголовка), для каждого столбца с критерием:
     v := значение (r, col) → если !matches(criteria, v): hidden.insert(r); break
  criteria:
     Values(set)       — множество выбранных значений: числа и текст сравниваются по значению, даты — по дереву год/месяц/день
                         (DateTree{years→months→days} раскрывается в предикат по сериалу), как в Excel
     Custom(op1, v1, and|or, op2, v2) — операторы Eq/Ne/Gt/Ge/Lt/Le/BeginsWith/EndsWith/Contains/NotContains с `* ? ~`
     Top{n, percent, bottom}          — предвычислить порог по столбцу
     Color(cell|font, color) / Icon(set, id) — по вычисленному стилю (с учётом УФ)
     Dynamic(period)                  — Today/Yesterday/ThisWeek/LastMonth/NextQuarter/YearToDate/… относительно NOW()
     AboveAverage / BelowAverage
  rows.hidden_by_filter := hidden; перерисовать; строка состояния «Найдено N из M»

Расширенный фильтр: диапазон условий → для каждой строки условий (И между столбцами) → ИЛИ между строками; ячейка условия — значение с оператором (>100, <>Москва, М*) или формула-критерий (заголовок пустой/не совпадает с полем; формула вычисляется относительно первой строки данных, относительные ссылки сдвигаются по строкам — как Excel). Копирование в другое место — Op::SetCells, «только уникальные» — хэш по кортежу строки.

5.14 Сводные таблицы

build_cache(source):
  для каждого столбца: dict := уникальные значения (HashMap<Value, u32>, отсортированный после сбора), records[f][i] = dict idx
  тип поля: все числа → Number; все даты → Date (создать иерархию Годы/Кварталы/Месяцы как групповые поля); иначе Text/Mixed
  (1M записей × 10 полей ≈ 40 МБ индексов; dict хранит Value)

refresh_pivot(p):
  // 1. фильтры страницы и срезы → bitmap допустимых записей
  // 2. группировка: ключ строки = кортеж индексов полей строк (с учётом группировок дат/чисел: idx → group idx),
  //    ключ столбца — аналогично
  agg: HashMap<(RowKey, ColKey), Vec<Accumulator>>   // по одному аккумулятору на поле значений
  для i in records (параллельно по блокам, с последующим слиянием): agg[(rk(i), ck(i))].update(values…)
  Accumulator: Sum{f64}, Count{u64}, Avg{sum,n}, Max, Min, Product, CountNums, StdDev/Var{Welford: n, mean, m2}, DistinctCount{HashSet<u32>}
  // 3. деревья заголовков: RowTree из всех встреченных ключей, сортировка по уровням (по подписи ICU / по значению поля данных /
  //    ручная; «показывать элементы без данных» — из dict), фильтры по подписям/значениям/первые N на каждом уровне
  // 4. промежуточные итоги: для каждого узла дерева — агрегат по поддереву (Sum/Count — сложение детей; Avg/StdDev/Distinct —
  //    пересчёт по записям узла: храним для узла bitmap записей или пересчитываем вторым проходом)
  // 5. «показать как»: второй проход по сетке: % от итогов (деление на итог строки/столбца/общий/родителя), отличие (минус базовый
  //    элемент), нарастающий итог (префиксная сумма по базовому полю), ранг (сортировка в группе), индекс ((v·total)/(row_total·col_total))
  // 6. вычисляемые поля: формула над агрегатами (Sum(Выручка) - Sum(Себестоимость)) — вычисляется на каждом узле после агрегации
  //    (семантика Excel: не по записям); вычисляемые элементы — формула над элементами одного поля, применяется на уровне ключей
  // 7. render: PivotRender { grid: Vec<Vec<Value>>, styles (элементы стиля: header/subtotal/grandtotal/rowstripe), outline buttons,
  //    layout (compact: один столбец с отступами; outline/tabular: по столбцу на уровень), пустые строки, повтор подписей }
  //    → записывается в лист как значения (не формулы) с меткой PivotArea для контекстных команд и GETPIVOTDATA

Детализация (drill-through): bitmap записей узла → новый лист с исходными строками. Срез: список dict поля с состоянием; изменение → bitmap → refresh всех сводных на кэше. Временная шкала — срез по датам с уровнем (годы/кварталы/месяцы/дни). Сводная диаграмма берёт PivotRender как источник рядов (категории = строки, ряды = столбцы).

5.15 Подбор параметра

Метод секущих (как в Excel) с защитой бисекцией:

goal_seek(target_cell, goal, var_cell, max_iter = 100, tol = 1e-3 /* «Относительная погрешность» из параметров книги */):
  f(x) := { var_cell ← x; recalc(partial, только компонента target_cell); target_cell − goal }
  x0 := текущее значение (или 0), x1 := x0 + (x0 == 0 ? 0.01 : x0·0.01)
  f0, f1 := f(x0), f(x1)
  for it in 0..max_iter:
      if |f1| ≤ tol: return Ok(x1)
      if f1 == f0: x1 += perturb; f1 = f(x1); continue              // плато
      x2 := x1 − f1·(x1 − x0)/(f1 − f0)                               // секущая
      if !finite(x2) || |x2 − x1| > 1e6·max(1,|x1|): x2 := bisect_fallback(bracket)  // при наличии скобки знака
      x0, f0, x1, f1 := x1, f1, x2, f(x2)
      report_progress(it, x1, f1 + goal)                              // окно SH-37: «Шаг/Пауза»
  return Err(NoConvergence { best: x1 })                              // «Решение не найдено», значение оставляется, пользователь выбирает OK/Отмена

Все пробные значения выполняются внутри одной транзакции undo; «Отмена» возвращает исходное.

5.16 Поиск решения (Solver)

Модель: SolverModel { objective: CellRef, goal: Max|Min|Value(f64), vars: Vec<Rect>, constraints: Vec<Constraint{lhs: Rect, op: Le|Eq|Ge|Int|Bin|Dif, rhs: Expr}>, nonneg: bool, method, options }. Сохраняется в скрытых именах листа (solver_*, совместимо с Excel Solver) и в settings.xml.

Каждая оценка целевой = частичный пересчёт компонент графа, затронутых переменными (кэшируется подграф); для LP оценка нужна только для извлечения матрицы. Параллелизм: популяции DE и мультистарт GRG — на копиях книги (Workbook::fork_calc_state), по потокам. Ограничение времени по умолчанию 100 с, итераций 100 (LP — не ограничивается), «Показывать результаты итераций» — пошаговый режим.

5.17 Виртуализация отрисовки сетки

5.17.1 Единицы и размеры

Ширина столбца хранится в «символах» (как Excel: число символов 0 шрифта по умолчанию + 5 px поля) и переводится в пиксели: px = trunc((chars·max_digit_width + 5) / max_digit_width · 256) / 256 · max_digit_width (формула OOXML); высота строки — в пунктах. Для рендера всё переводится в DIP с учётом масштаба и HiDPI.

5.17.2 Алгоритм

GridView::paint(viewport):
  // 1. Видимые строки/столбцы: по префиксным суммам размеров (Fenwick в AxisProps, скрытые = 0) → бинарный поиск
  first_row := axis_rows.index_at(scroll_y), last_row := axis_rows.index_at(scroll_y + viewport.h)
  // Автовысота: строки с переносом измеряются лениво — только попавшие в окно ± 2 экрана; остальные — по оценке (строки
  // по умолчанию); при измерении префиксные суммы корректируются (ползунок немного «дышит» — допустимо, как в браузерах)
  // 2. Тайлы: сетка делится на тайлы 512×512 px (в DIP·scale); для видимых тайлов — Skia Picture (список отображения) в кэше
  //    по ключу (tile, zoom, generation листа); инвалидация по изменённым прямоугольникам (dirty rects от Op), а не всего тайла
  // 3. Ячейка рисуется: заливка (стиль/УФ/таблица) → границы (с разрешением конфликтов соседних границ: толще побеждает,
  //    затем правая/нижняя) → содержимое: число/дата по формату (DisplayString кэш по (value, numfmt, width)) с выравниванием
  //    и `#####` при нехватке; текст — shaped layout из кэша (ключ: текст, шрифт, ширина при переносе) через meridian text-layout;
  //    переливание текста в пустые соседи; гистограммы/значки/шкалы УФ; спарклайны; индикаторы (примечание, ошибка, список)
  // 4. Объединения: рисуются как одна ячейка (рект из MergeIndex), накрывают сетку
  // 5. Поверх: линии сетки (цвет темы, скрываются под заливкой — как Excel), закреплённые области (отдельные тайловые слои),
  //    выделение (полупрозрачная заливка цвета приложения + рамка), рамки ссылок, бегущая рамка (анимация 120 мс шаг), объекты
  // 6. Заголовки строк/столбцов — отдельные слои; при 2^31 строк — ширина заголовка по максимальному видимому номеру
  // Прокрутка: смещение слоя текстуры без перерисовки (субпиксельная, плавная на колесе/трекпаде); при пересечении границы тайла —
  // отрисовка новых тайлов в фоновом потоке (упреждающе ±1 экран); цель — 120 FPS на 4K при прокрутке 1M строк

Полоса прокрутки: диапазон = используемая область + 1 экран (как Excel), в большом режиме — логарифмическая «грубая» прокрутка с точным позиционированием по полю имени. Масштаб: Ctrl+колесо с центром в курсоре; размеры шрифтов масштабируются, толщины линий — ≥ 1 px.

5.18 Выделение и навигация

• Модель выделения: Selection { ranges: Vec<Rect>, active: CellRef, anchor: CellRef, mode: Cells|Rows|Cols|All }; Shift — расширение от якоря, Ctrl — добавление диапазона, Shift+F8 — режим добавления; выделение целых строк/столбцов — специальные Rect с All.
• Ctrl+стрелки (переход по блокам), пример для «вниз»:

  jump_down(r, c):
    cur := nonempty(r,c); next := nonempty(r+1,c)
    если cur && next: идти вниз, пока nonempty(r+1,c) — «конец блока» (пропуск по словам битовых карт чанков: находим первый нулевой бит
                      в столбце c начиная с r+1 — O(число слов), пустые чанки пропускаются по col_nonempty)
    иначе: идти вниз до первой непустой (первый единичный бит в столбце c после r+1); если нет — последняя строка листа
    скрытые строки пропускаются; объединения считаются непустыми целиком

  Shift+Ctrl+стрелка — расширяет выделение по тому же алгоритму. End-режим (End, затем стрелка) — то же.
• Ctrl+Home — A1 (или левый верхний угол незакреплённой области), Ctrl+End — последняя ячейка используемой области, Ctrl+A — текущая область (прямоугольник непустых вокруг курсора, расширяется до данных; второе нажатие — весь лист), Ctrl+Shift+* — текущая область, Ctrl+/ — текущий массив, Ctrl+[/] — влияющие/зависимые, Ctrl+Пробел/Shift+Пробел — столбец/строка, Ctrl+. — углы выделения, Tab в выделении — обход по ячейкам выделения.
• Клавиатурный ввод адреса в поле имени, F5 — переход; «Перейти назад» (F5, Enter — Excel-поведение), Ctrl+G.
• Клик по заголовку с Shift/Ctrl, двойной клик по границе ячейки — переход к краю блока (как Excel).

5.19 Копирование и вставка

• Внутренний буфер: ClipboardPayload { source: Rect (на листе SheetId книги), cells: Vec<CellSlotFull> (значения, формулы в R1C1-относительном виде, стили, extra), merges, col_widths, row_heights, mode: Copy|Cut, origin_doc: Uuid } + системные форматы: text/plain (TSV, значения как отображены), text/html (таблица с инлайн-стилями и data-sheets-*-подобными атрибутами для round-trip формул), text/csv, application/vnd.meridian.sheets+cbor (полный payload), image/png (при «копировать как рисунок»), text/rtf (Windows).
• Вставка (Ctrl+V) из своего payload: относительные ссылки формул пересчитываются от новой базы (R1C1-смещения не меняются — это и есть «адаптация»); абсолютные — не меняются; ссылки на другие листы — сохраняются; при вставке в другую книгу ссылки на листы источника превращаются во внешние ссылки [Книга]Лист!A1 (как Excel) или в значения — по опции. Вырезание: Op::MoveRange — ссылки, указывающие на вырезанный диапазон, перенаправляются на новое место; объединения переносятся.
• Многократная вставка: один диапазон в большее выделение — тайлинг, если выделение кратно; одна ячейка — во все.
• Специальная вставка (SH-59): фильтр атрибутов payload + операция (target = target op source для чисел, формулы → =(старая)+(новая) как Excel), транспонирование (ссылки в формулах транспонируются вместе — Excel не умеет корректно, мы — с предупреждением), «вставить связь» → формулы =Лист!A1, «ширины столбцов», «проверка», «все условные форматы объединить».
• Из внешних источников: HTML-таблица → разбор с сохранением жирности/цвета/объединений; текст → мастер «текст по столбцам» с запоминанием разделителя; изображения → объект.
• Параметры вставки (SH-59b) — кнопка после вставки с переключением вариантов без повторного Ctrl+V.

5.20 Поиск

find(query, opts{scope: Sheet|Workbook, in: Formulas|Values|Notes|Threads, by: Rows|Cols, case, whole, mode: Plain|Wildcard|Regex, format: Option<StyleMatch>}):
  matcher := скомпилировать: Plain → memchr/Boyer-Moore по NFC-нормализованной строке с опциональным case-folding (ICU);
             Wildcard → перевести `* ? ~*` в regex; Regex → `regex` crate (Unicode, таймаут на бэктрекинг не нужен — RE2-семантика)
  обход: по чанкам в порядке by (строки — чанки слева направо по ряду чанков, внутри — построчно; столбцы — по столбцам чанков),
         начиная с ячейки после активной, циклически; в Values — сопоставляется DisplayString (как видит пользователь), в Formulas —
         текст формулы в локали пользователя (или значение для констант); пропуск скрытых — опция
  «Найти всё» → список (лист, адрес, значение, формула) в SH-15 с живой подсветкой; замена → Op::SetCells пакетом в одной транзакции,
  для формул замена в тексте формулы с перепарсингом (ошибка парсинга → пропустить и сообщить)
  производительность: 1M непустых ячеек — < 150 мс на Plain (без аллокаций, параллельно по чанкам с сохранением порядка результатов)

5.21 Импорт CSV

import_csv(path, opts: Option<CsvOptions>) -> (Sheet | Flow):
  1. Чтение первых 64 КБ → кодировка: BOM (UTF-8/16LE/16BE/32) → иначе валидный UTF-8 → иначе статистика байтов:
     cp1251 vs koi8-r vs cp866 vs iso-8859-1/-5 vs windows-1252 — по частотам букв и биграмм (таблицы для ru/en/de/fr);
     неуверенность < 0.8 → показать мастер SH-40 с выбором (предпросмотр с кандидатами)
  2. Разделитель: кандидаты `, ; \t |` и ' ' (только при фиксированной ширине нет); для каждого — число вхождений по строкам
     (учитывая кавычки); побеждает тот, у которого дисперсия числа полей минимальна и число полей > 1; ограничитель — `"` (если
     в строках есть `"`), иначе `'`; десятичный разделитель — по доле `\d,\d` против `\d\.\d` в полях (при `;`-разделителе чаще `,`)
  3. Типы столбцов: выборка 1000 строк (равномерно по файлу): для каждого столбца — доля значений, разбираемых как число
     (с учётом тысячных пробелов/NBSP, валют, %, скобок отрицательных), дата (по локали и ISO), bool, пусто; порог 95 % → тип;
     ведущие нули (`007`, телефоны, ИНН) → текст (опция «сохранить ведущие нули» по умолчанию включена); длинные цифровые
     строки > 15 цифр → текст (предупреждение); столбцы «общий» — автоопределение по ячейке
  4. Разбор: потоковый парсер по RFC 4180 с расширениями (CR/LF/CRLF, многострочные поля в кавычках, `""`), SIMD-поиск разделителей
     (`memchr`), порциями 8 МБ в пул потоков: разбор → ChunkBuilder (плотные чанки) → сборка листа; прогресс и отмена; строки > 2^20
     → предложение «большой режим» или потока данных
  5. Результат: лист с заголовком (если обнаружен: первая строка — текст, остальные — типизированы), автоширина столбцов по выборке,
     типы ячеек по столбцу; журнал импорта (сколько строк, ошибок разбора, пример проблемных строк)
  Производительность: 1 ГБ CSV (10M строк × 10 столбцов) — < 20 с на 8 ядрах в большом режиме, память ≈ 1,5× данных

Экспорт CSV: кодировка (UTF-8 с BOM по умолчанию для Excel-совместимости; опция без BOM), разделитель, ограничитель всегда при необходимости, формат чисел «как отображено» или «сырые», даты ISO или по формату, только видимые строки — опция.

5.22 Экспорт

5.23 Каталог функций

Каталог — meridian-calc/src/functions/<category>.rs, регистрация через макрос func! с сигнатурой, типами аргументов, флагами (волатильность, массивный результат, ленивые аргументы) и локализованными именами из locale/*.toml. Сводка: P0 — 317 функций (+ 38 алиасов совместимости), P1 — 147, P2 — 16; всего 518 имён. Русские имена даны для самых употребимых; полная таблица — в locale/ru.toml.

Математические и тригонометрические (81)

Статистические (111)

Совместимость (38 алиасов; фаза = фаза целевой функции)

Текстовые (50)

Логические (11) и массивы/LAMBDA (9)

Дата и время (25)

Ссылки и поиск (41)

Финансовые (55)

Инженерные (54)

Информационные (20), базы данных (12), куб (7), веб (3), прочее

Семантика критериев (COUNTIF-семейство, SUMIFS, AVERAGEIFS, MINIFS, MAXIFS, D-функции): строка критерия разбирается как [оператор][значение] (">=10", "<>", "=*а?", "10", "текст"), подстановочные * ? ~, число в строке сравнивается как число (с разбором по локали), текст — без учёта регистра; пустой критерий "" соответствует пустым и пустым строкам, "<>" — непустым; критерий-число соответствует и числам-текстам в ячейках (Excel-совместимость).

5.24 Особенности реализации сложных функций

6. MeridianScript API для Sheets

Общие положения MeridianScript (песочница QuickJS-ng, транспиляция TypeScript, разрешения, подписи, магазин) — в docs/03-architecture.md (раздел MeridianScript). Здесь — объектная модель Sheets. Декларации: meridian-sheets.d.ts (генерируются из Rust-атрибутов #[script_api]). Все вызовы синхронны по отношению к модели (выполняются в потоке документа между пересчётами), сетевые и файловые — Promise. Пакетирование: изменения внутри одного обработчика объединяются в одну транзакцию undo и один пересчёт.

6.1 Объектная модель

Application (глобальный объект `sheets`)
 ├─ workbooks: WorkbookCollection → Workbook (active, open(), create(), byName())
 ├─ ui: UI (ribbon, sidebar, dialogs, toast, prompt, commandPalette)
 ├─ clipboard, locale, version, edition (Features), user (Meridian ID, если вошёл)
 └─ schedule: Scheduler (every/at/cron — только для скриптов книги с разрешением)
Workbook
 ├─ sheets: SheetCollection → Sheet (add, byName, byIndex, active, move, delete)
 ├─ names: NamedItemCollection → NamedItem
 ├─ tables, pivots, charts (сквозь листы), connections, flows, styles, theme, properties, protection
 ├─ calculation: { mode, recalc(), recalcAll(), iterative }
 ├─ history (undo/redo, beginGroup/endGroup), save(), saveAs(), export(), close()
 └─ events: onOpen, onBeforeSave, onBeforeClose, onSheetActivate, onEdit, onRecalc, onSelectionChange, onCommentAdded, onProtectionChange
Sheet
 ├─ range(a1 | row,col[,rows,cols]) → Range; cell(row,col) → Range 1×1; usedRange; selection; activeCell
 ├─ rows/columns: AxisCollection (height/width/hidden/group); freeze(rows, cols); split; zoom; view
 ├─ tables → Table; pivots → PivotTable; charts → Chart; images, shapes, controls; comments (threads), notes; hyperlinks
 ├─ conditionalFormats, validations, autoFilter, sparklines, protection, pageSetup, printAreas
 ├─ name, tabColor, visibility (visible|hidden|veryHidden), index, id
 └─ events: onEdit, onSelectionChange, onActivate, onDoubleClick, onRightClick (отменяемые)
Range  (прямоугольник или объединение прямоугольников — `areas`)
 ├─ address, sheet, row/column/rowCount/columnCount, cells(), rows(), columns(), offset(), resize(), intersect(), union()
 ├─ values: CellValue[][] (get/set), formulas (локаль-независимые, английские; formulasLocal), formulasR1C1, text (отображаемый)
 ├─ numberFormat, style/font/fill/borders/alignment/protection (get/set, пакетно), merge()/unmerge(), clear(what)
 ├─ sort(), autoFilter(), find()/replace(), removeDuplicates(), textToColumns(), fill(direction|series), copyTo()/moveTo()/paste()
 ├─ insert(shift), delete(shift), hyperlink, note, comments, validation, conditionalFormats, spillParent, spillRange, hasSpill
 ├─ dependents(), precedents(), calculate(), errorInfo
 └─ табличные: table (если внутри), pivot (если внутри)
Table → columns (TableColumn: name, range, dataBodyRange, totalsFormula, calculatedFormula), rows, headerRange, totalsRange, style, resize(), convertToRange(), addRow(), filters
PivotTable → cache, fields (rows/columns/filters/values), layout, refresh(), addDataField(), group(), slicers, render → Range
Chart → type, series (SeriesCollection), axes, title, legend, dataLabels, trendlines, style, position (anchor), export(png|svg|pdf), pivotSource
NamedItem → name, scope, type (range|constant|formula|lambda), value, formula, comment, delete()
DataConnection / DataFlow → source, steps, refresh(), schedule, lastRefresh

Типы значений: CellValue = number | string | boolean | null | ErrorValue | RichValue; ErrorValue = { error: '#N/A' | ..., message?: string }; даты — number сериал плюс помощники sheets.dates.fromDate(Date), toDate(serial); Range.typedValues возвращает { kind: 'date', value: Date } и т.д.

6.2 Декларации (фрагмент meridian-sheets.d.ts)

declare namespace sheets {
  const workbooks: WorkbookCollection;
  const ui: UI;
  const schedule: Scheduler;
  function customFunction(opts?: CustomFunctionOptions): MethodDecorator;   // @sheets.customFunction()

  interface Workbook {
    readonly name: string; readonly path: string | null; readonly sheets: SheetCollection;
    readonly names: NamedItemCollection; readonly tables: Table[]; readonly pivots: PivotTable[]; readonly charts: Chart[];
    calculation: { mode: 'auto' | 'autoExceptTables' | 'manual'; iterative: { enabled: boolean; maxIterations: number; maxChange: number } };
    recalc(full?: boolean): void;
    save(): Promise<void>; saveAs(path: string, format?: FileFormat): Promise<void>;
    export(format: 'pdf' | 'csv' | 'html' | 'json' | 'parquet', opts?: ExportOptions): Promise<Uint8Array>;
    batch<T>(fn: () => T): T;                       // одна транзакция undo + один пересчёт + одна перерисовка
    on(event: 'edit', handler: (e: EditEvent) => void): Disposable;
    on(event: 'recalc', handler: (e: RecalcEvent) => void): Disposable;
    on(event: 'open' | 'beforeSave' | 'beforeClose', handler: (e: WorkbookEvent) => void): Disposable;
    on(event: 'selectionChange', handler: (e: SelectionEvent) => void): Disposable;
  }
  interface Sheet {
    name: string; tabColor: string | null; visibility: 'visible' | 'hidden' | 'veryHidden'; readonly index: number;
    range(address: string): Range; range(row: number, col: number, rows?: number, cols?: number): Range;
    readonly usedRange: Range; readonly selection: Range; activeCell: Range;
    readonly rows: Axis; readonly columns: Axis;
    freeze(rows: number, cols: number): void;
    readonly tables: TableCollection; readonly pivots: PivotCollection; readonly charts: ChartCollection;
    readonly conditionalFormats: ConditionalFormatCollection; readonly validations: ValidationCollection;
    protect(opts?: SheetProtectionOptions): void; unprotect(password?: string): void;
    on(event: 'edit', handler: (e: EditEvent) => void): Disposable;
  }
  interface Range {
    readonly address: string; readonly sheet: Sheet;
    readonly row: number; readonly column: number; readonly rowCount: number; readonly columnCount: number;  // 1-based, как в Excel
    values: CellValue[][]; formulas: (string | null)[][]; formulasLocal: (string | null)[][]; readonly text: string[][];
    numberFormat: string | string[][]; style: string | null; font: Font; fill: Fill; borders: Borders; alignment: Alignment;
    offset(rows: number, cols: number): Range; resize(rows?: number, cols?: number): Range; cell(row: number, col: number): Range;
    getRow(i: number): Range; getColumn(i: number): Range; intersect(other: Range): Range | null;
    clear(what?: 'all' | 'contents' | 'formats' | 'notes' | 'hyperlinks'): void;
    insert(shift: 'down' | 'right'): void; delete(shift: 'up' | 'left'): void;
    merge(across?: boolean): void; unmerge(): void;
    sort(keys: SortKey[], opts?: SortOptions): void; removeDuplicates(columns?: number[], hasHeader?: boolean): number;
    find(what: string | RegExp, opts?: FindOptions): Range | null; findAll(what: string | RegExp, opts?: FindOptions): Range[];
    replace(what: string | RegExp, by: string, opts?: FindOptions): number;
    fill(direction: 'down' | 'right' | 'up' | 'left', mode?: 'copy' | 'series' | 'formats'): void;
    copyTo(target: Range, what?: PasteWhat, opts?: PasteOptions): void; moveTo(target: Range): void;
    readonly spillParent: Range | null; readonly spillRange: Range | null; readonly errorInfo: ErrorInfo | null;
    dependents(direct?: boolean): Range[]; precedents(direct?: boolean): Range[];
    readonly table: Table | null; readonly pivot: PivotTable | null;
    validation: Validation | null; hyperlink: Hyperlink | null; note: string | null; readonly comments: CommentThread[];
  }
  interface EditEvent { range: Range; oldValues: CellValue[][]; newValues: CellValue[][]; source: 'user' | 'script' | 'paste' | 'fill' | 'import'; cancel(): void }
  interface RecalcEvent { changed: Range[]; durationMs: number; circular: Range[] }
  interface UI {
    ribbon: { addButton(opts: { tab: string; group: string; label: string; icon?: string; onClick: () => void; key?: string }): Disposable };
    sidebar: { open(opts: { title: string; html: string; onMessage?: (m: unknown) => void }): SidebarHandle };
    toast(text: string, kind?: 'info' | 'success' | 'warning' | 'error'): void;
    prompt(opts: PromptOptions): Promise<string | null>; confirm(text: string): Promise<boolean>;
    pickRange(prompt: string): Promise<Range | null>;
  }
}

6.3 События

6.4 Примеры

1. Обработка диапазона — нормализация телефонов в выделении (пакетно, одна транзакция):

// Нормализуем телефоны к виду +7XXXXXXXXXX / Normalize phone numbers to +7XXXXXXXXXX
const wb = sheets.workbooks.active;
const rng = wb.sheets.active.selection;
wb.batch(() => {
  const v = rng.values;                                  // одно чтение / single read
  for (const row of v) for (let c = 0; c < row.length; c++) {
    const s = String(row[c] ?? '').replace(/\D/g, '');
    if (s.length === 11 && (s[0] === '7' || s[0] === '8')) row[c] = '+7' + s.slice(1);
    else if (s.length === 10) row[c] = '+7' + s;
  }
  rng.values = v;                                        // одна запись / single write
  rng.numberFormat = '@';
});
sheets.ui.toast(`Обработано ${rng.rowCount * rng.columnCount} ячеек`, 'success');

2. Пользовательская функция (UDF) с типами и массивным результатом:

/** Налог по прогрессивной шкале / Progressive tax. Доступна в формулах как =ПРОГРНАЛОГ(доход) или =SCRIPT.PROGTAX(income) */
@sheets.customFunction({ name: 'PROGTAX', localName: { ru: 'ПРОГРНАЛОГ' }, description: 'Налог по прогрессивной шкале',
  args: [{ name: 'income', type: 'number', description: 'Доход за год' }], volatile: false })
export function progTax(income: number): number {
  const brackets: [number, number][] = [[2_400_000, 0.13], [5_000_000, 0.15], [20_000_000, 0.18], [50_000_000, 0.20], [Infinity, 0.22]];
  let tax = 0, prev = 0;
  for (const [limit, rate] of brackets) { if (income <= prev) break; tax += (Math.min(income, limit) - prev) * rate; prev = limit; }
  return Math.round(tax * 100) / 100;
}

/** Возвращает массив → разливается (spill) / returns array → spills */
@sheets.customFunction({ name: 'FIBS', args: [{ name: 'n', type: 'number' }] })
export function fibs(n: number): number[][] {
  const out: number[][] = [[0], [1]];
  for (let i = 2; i < n; i++) out.push([out[i - 1][0] + out[i - 2][0]]);
  return out.slice(0, n);
}

3. Импорт JSON по расписанию в структурированную таблицу:

// Каждый час тянем курсы валют и обновляем таблицу «Курсы» / Hourly FX rates into table "Курсы"
sheets.schedule.every('1h', async () => {
  const resp = await sheets.net.fetch('https://api.example.com/rates?base=RUB');   // требует разрешения «сеть: api.example.com»
  const data = await resp.json() as { date: string; rates: Record<string, number> };
  const wb = sheets.workbooks.active;
  const table = wb.sheets.byName('Данные').tables.byName('Курсы');
  wb.batch(() => {
    table.dataBodyRange?.clear('contents');
    const rows = Object.entries(data.rates).map(([code, rate]) => [code, rate, sheets.dates.fromDate(new Date(data.date))]);
    table.addRows(rows);                                        // таблица расширяется, форматы и вычисляемые столбцы применяются
    table.columns.byName('Дата').dataBodyRange.numberFormat = 'dd.mm.yyyy';
  });
  wb.pivots.filter(p => p.cache.source === table).forEach(p => p.refresh());
});

4. Построение отчёта: сводная + диаграмма + форматирование на новом листе:

const wb = sheets.workbooks.active;
const src = wb.sheets.byName('Продажи').tables.byName('Продажи');
const rep = wb.sheets.add('Отчёт');
const pv = rep.pivots.add({ source: src, at: rep.range('A3'), name: 'СводПродажи' });
pv.rows.add('Регион'); pv.columns.add('Квартал'); pv.values.add('Сумма', { aggregate: 'sum', numberFormat: '#,##0 ₽' });
pv.values.add('Сумма', { aggregate: 'sum', showAs: { kind: 'percentOfRowTotal' }, name: 'Доля' });
pv.layout = { form: 'tabular', subtotals: 'none', grandTotals: 'both' };
pv.refresh();

const ch = rep.charts.add({ type: 'columnClustered', pivot: pv, anchor: rep.range('H3:P20') });
ch.title.text = 'Продажи по регионам'; ch.legend.position = 'bottom'; ch.style = 7;

rep.range('A1').values = [['Отчёт по продажам']]; rep.range('A1').style = 'Заголовок 1';
rep.range('A2').formulas = [['="Сформирован "&TEXT(NOW();"dd.mm.yyyy hh:mm")']];
rep.columns.autoFit(); rep.freeze(3, 0);
await wb.export('pdf', { sheets: ['Отчёт'], fitTo: { width: 1, height: 0 } }).then(bytes => sheets.files.save('Отчёт.pdf', bytes));

5. Кнопка в ленте и панель:

// Кнопка «Закрыть месяц» на вкладке Скрипты / Ribbon button "Close month"
sheets.ui.ribbon.addButton({ tab: 'Скрипты', group: 'Финансы', label: 'Закрыть месяц', icon: 'lock', key: 'Ctrl+Shift+M',
  onClick: async () => {
    if (!(await sheets.ui.confirm('Закрыть текущий месяц? Ячейки ввода будут защищены.'))) return;
    const sh = sheets.workbooks.active.sheets.byName('Ввод');
    sheets.workbooks.active.batch(() => {
      sh.range('B2:M200').protection = { locked: true };
      sh.protect({ allowFilter: true, allowSort: false });
      sh.range('A1').note = `Закрыт ${new Date().toLocaleDateString('ru-RU')} пользователем ${sheets.user?.name ?? 'локальный'}`;
    });
    sheets.ui.toast('Месяц закрыт', 'success');
  }});

6. Проверка ввода через onEdit с отменой и журналом:

const wb = sheets.workbooks.active;
const log = wb.sheets.byName('Журнал') ?? wb.sheets.add('Журнал', { visibility: 'hidden' });
wb.sheets.byName('Заказы').on('edit', e => {
  const col = e.range.table?.columns.byName('Количество');
  if (col && e.range.intersect(col.dataBodyRange)) {
    for (const row of e.newValues) for (const v of row)
      if (typeof v !== 'number' || v <= 0 || !Number.isInteger(v)) { sheets.ui.toast('Количество — целое число > 0', 'error'); e.cancel(); return; }
  }
  log.usedRange.offset(log.usedRange.rowCount, 0).resize(1, 4).values =
    [[sheets.dates.fromDate(new Date()), sheets.user?.email ?? 'local', e.range.address, JSON.stringify(e.newValues)]];
});

7. Запись действий — что получает пользователь после «Записать» (сортировка, УФ, итог):

// Записано 2026-10-03 12:41 / Recorded by MeridianScript recorder
export function main(wb = sheets.workbooks.active) {
  const sh = wb.sheets.byName('Данные');
  sh.range('A1:D500').sort([{ column: 3, order: 'desc' }], { hasHeader: true });
  sh.range('C2:C500').conditionalFormats.add({ kind: 'dataBar', color: '#1E8E5A', min: { kind: 'auto' }, max: { kind: 'auto' } });
  sh.range('C501').formulas = [['=SUBTOTAL(109;C2:C500)']];
  sh.range('A501:C501').style = 'Итог';
}

8. Поток данных из Base по запросу и обновление сводных:

const flow = sheets.workbooks.active.flows.add({
  name: 'Заказы из CRM',
  source: { kind: 'base', connection: 'crm-postgres', query: 'SELECT id, customer, total, created_at FROM orders WHERE created_at > now() - interval \'90 days\'' },
  steps: [
    { kind: 'setTypes', columns: { total: 'currency:RUB', created_at: 'date' } },
    { kind: 'filterRows', formula: '[total] > 0' },
    { kind: 'addColumn', name: 'Месяц', formula: 'EOMONTH([created_at];0)' },
  ],
  target: { kind: 'table', sheet: 'Данные', name: 'Заказы' },
});
await flow.refresh();

6.5 Соответствие объектам VBA Excel (для транслятора и миграции)

Транслятор VBA (P1) покрывает: Sub/Function, переменные и типы (Dim … As), If/Select Case/For/For Each/Do While/With, операции над Range/Cells/Worksheets/Workbooks, WorksheetFunction, MsgBox/InputBox, события листа/книги. Непереводимые конструкции (Declare, COM-объекты, UserForm, GoTo) сохраняются комментариями // TODO VBA: с исходным текстом.

7. Форматы

Подробно — docs/04-file-formats.md (структура пакетов, таблицы соответствия элементов, корпус тестов). Здесь — особенности Sheets.