atmos/os_lib/layout/

multicol.rs

//! CSS 多段組（`column-count` / `column-width` / `columns` / `column-gap`）の
//! 列幾何計算（純粋モジュール）。
//!
//! ハードウェアにもグローバル状態にも依存しない算術だけなので、
//! QEMU 抜きでホスト側から検証できる。
//!
//! # 仕様の要点（CSS Multi-column Layout Level 1）
//!
//! - `column-count` は列数の指定、`column-width` は 1 列の**最小**目安幅。
//!   両方指定されたときは「`column-width` から求まる列数」と
//!   `column-count` の**小さい方**を採る（`column-count` は上限として働く）。
//! - `column-gap` の既定は `normal`＝`1em` 相当。ここでは呼び出し側が
//!   解決したピクセル値を受け取る。
//! - 列は等幅で、`gap` は列と列の**間だけ**に入る（外側には入らない）。
//!   よって `列幅 = (使用可能幅 - gap * (列数 - 1)) / 列数`。
//!
//! # 割り切り
//!
//! 段抜き（`column-span`）・段区切り（`break-inside`）・段罫線
//! （`column-rule`）は扱わない。本モジュールは「何列で、各列はどの
//! x 座標にどの幅で並ぶか」だけを決める。

extern crate alloc;
use alloc::vec::Vec;

/// 多段組の指定。いずれも解決済みのピクセル値／個数。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MultiColSpec {
    /// `column-count`。未指定は `None`。
    pub count: Option<i32>,
    /// `column-width`（1 列の最小目安幅、px）。未指定は `None`。
    pub width: Option<i32>,
    /// `column-gap`（px）。`normal` は呼び出し側で 1em 相当へ解決しておく。
    pub gap: i32,
}

/// 列の位置と幅。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Column {
    /// コンテンツボックス左端からの x オフセット（px）。
    pub x: i32,
    /// 列の幅（px）。
    pub width: i32,
}

/// 実際に使う列数を決める（純粋関数）。
///
/// - どちらも未指定なら 1 列（多段組ではない）。
/// - `count` だけなら その値（1 未満は 1 に切り上げ）。
/// - `width` だけなら 使用可能幅から入るだけ詰める。
/// - 両方あれば **小さい方**（`count` が上限）。
///
/// `avail_w` が 0 以下、または `width` が 0 以下のときは 1 列へ倒す
/// （ゼロ除算と無限列を防ぐ）。
pub fn resolve_column_count(spec: &MultiColSpec, avail_w: i32) -> i32 {
    if avail_w <= 0 {
        return 1;
    }
    // `column-width` から入る列数を求める。gap も 1 列分ずつ消費する。
    let from_width = spec.width.and_then(|w| {
        if w <= 0 {
            return None;
        }
        // n 列入る条件: n*w + (n-1)*gap <= avail_w
        //            → n <= (avail_w + gap) / (w + gap)
        let denom = w.saturating_add(spec.gap.max(0));
        if denom <= 0 {
            return None;
        }
        let n = (avail_w.saturating_add(spec.gap.max(0))) / denom;
        Some(n.max(1))
    });
    let from_count = spec.count.map(|c| c.max(1));

    match (from_count, from_width) {
        (None, None) => 1,
        (Some(c), None) => c,
        (None, Some(w)) => w,
        // 仕様上 `column-count` は上限として働く。
        (Some(c), Some(w)) => c.min(w),
    }
}

/// 列の x 座標と幅を計算する（純粋関数）。
///
/// `gap` は列間にだけ入る。端数は最後の列へ寄せず、各列を等幅にしたうえで
/// 余りぶんだけ最終列を広げる（合計が `avail_w` を超えないようにする）。
/// 列幅が負になる（gap が広すぎる）場合は 0 幅の列を返し、パニックしない。
pub fn layout_columns(spec: &MultiColSpec, avail_w: i32) -> Vec<Column> {
    let n = resolve_column_count(spec, avail_w);
    let gap = spec.gap.max(0);
    if n <= 1 {
        return alloc::vec![Column {
            x: 0,
            width: avail_w.max(0),
        }];
    }
    let total_gap = gap.saturating_mul(n - 1);
    let usable = avail_w.saturating_sub(total_gap);
    if usable <= 0 {
        // gap だけで埋まってしまう場合。列は作るが幅 0 にする。
        return (0..n)
            .map(|i| Column {
                x: (gap.saturating_add(0)).saturating_mul(i),
                width: 0,
            })
            .collect();
    }
    let base = usable / n;
    let mut cols = Vec::with_capacity(n as usize);
    let mut x = 0;
    for i in 0..n {
        // 端数（usable % n）は最終列で吸収し、合計が avail_w を超えないようにする。
        let w = if i == n - 1 { usable - base * (n - 1) } else { base };
        cols.push(Column { x, width: w });
        x = x.saturating_add(w).saturating_add(gap);
    }
    cols
}

/// `columns` ショートハンドを `column-width` と `column-count` へ分解する。
///
/// 仕様上、値は「長さ」と「整数」が任意順で高々 1 つずつ。
/// `auto` は「その成分は未指定」を意味する。
/// 解決できない字句は無視する（不正値でページ全体を壊さない）。
///
/// 長さの解決（`px` 以外の単位）は呼び出し側の責務。ここでは
/// **末尾が `px` か単位無しの数値**だけを長さとして受け取り、
/// 整数だけの値は列数として扱う。
pub fn parse_columns_shorthand(s: &str) -> (Option<i32>, Option<i32>) {
    let mut width = None;
    let mut count = None;
    for tok in s.split_whitespace() {
        let t = tok.trim();
        if t.is_empty() || t.eq_ignore_ascii_case("auto") {
            continue;
        }
        if let Some(px) = t.strip_suffix("px") {
            if let Ok(v) = px.trim().parse::<f32>() {
                if v.is_finite() && v > 0.0 {
                    width = Some(v as i32);
                }
            }
            continue;
        }
        // 単位無しの整数は列数。小数や負数は無視する。
        if let Ok(v) = t.parse::<i32>() {
            if v > 0 {
                count = Some(v);
            }
            continue;
        }
        // それ以外（`2em` 等の未対応単位）は長さとして扱えないので無視する。
    }
    (width, count)
}

/// 子ボックスを列へ振り分けた結果。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Placement {
    /// 何列目へ入れるか（0 起点）。
    pub col: usize,
    /// その列の中での上端オフセット（px）。
    pub y: i32,
}

/// 子の高さ列を受け取り、各子をどの列のどの高さへ置くかを決める（純粋関数）。
///
/// 不変条件 M-6 のとおり「その時点で高さが最小の列」へ順に入れる貪欲法。
/// 同じ高さの列が複数あるときは**左の列を優先**する（見た目の安定のため。
/// 右から埋まると 1 件だけのときに不自然に右へ寄る）。
///
/// 返り値の長さは `heights` と同じ。列数が 0 のときは全て 0 列目へ倒す。
///
/// 計算量: **O(子数 × 列数)**。列数は高々数十なので実用上問題ない。
pub fn assign_to_columns(heights: &[i32], n_cols: usize) -> Vec<Placement> {
    let n = n_cols.max(1);
    let mut bottoms = alloc::vec![0i32; n];
    let mut out = Vec::with_capacity(heights.len());
    for &h in heights {
        // 最小の列を探す。`<` で比較するので同値なら先に見た（左の）列が残る。
        let mut min_i = 0usize;
        for i in 1..n {
            if bottoms[i] < bottoms[min_i] {
                min_i = i;
            }
        }
        out.push(Placement {
            col: min_i,
            y: bottoms[min_i],
        });
        bottoms[min_i] = bottoms[min_i].saturating_add(h.max(0));
    }
    out
}

/// 振り分け後の各列の高さを返す（純粋関数）。
///
/// 多段組ブロック自身の高さは、この最大値になる。
pub fn column_heights(heights: &[i32], n_cols: usize) -> Vec<i32> {
    let n = n_cols.max(1);
    let mut bottoms = alloc::vec![0i32; n];
    for &h in heights {
        let mut min_i = 0usize;
        for i in 1..n {
            if bottoms[i] < bottoms[min_i] {
                min_i = i;
            }
        }
        bottoms[min_i] = bottoms[min_i].saturating_add(h.max(0));
    }
    bottoms
}