SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Cell content: what a cell shows, as text and fields, how it should fit, and the cell text rule
//! that places a label and a value in a cell. These are the rules every table of cells shares:
//! title blocks now, parts lists later. Plain data in sheet millimetres, like
//! [`crate::drawing_sheet`]: nothing here reads a field's value, measures text or draws.
//!
//! - [`Content`] is a list of [`Part`]s: text as written, or a field naming a value by its
//! [`Source`] and key, with a [`Format`]. Keys, units and decimals are kept as written; the
//! resolver checks them against each source. [`Content::validate`] bounds its size, and
//! [`check_label`] a label's.
//! - A value is never cut: when it has more than its [`Fit`] allows, it is shown whole with a
//! [`Warning`].
//!
//! The cell text rule (x to the right, y up), in the cell inside its lines, so the padding is
//! measured from a line's inner edge whatever the line's width:
//! - a label's baseline starts [`PADDING_MM`] in from the cell's left side, and its cap height
//! plus [`PADDING_MM`] down from the cell's top ([`label_at`]);
//! - the value box is the cell inset by [`PADDING_MM`], its top [`PADDING_MM`] below the label's
//! baseline when there is a label ([`value_box`]);
//! - one line of a value that doesn't wrap is centred top to bottom in the value box; otherwise the
//! lines run down from the box's top at the font's line pitch, the first baseline a cap height
//! below it ([`place_lines`]). Each baseline stays in the box, and its descenders
//! ([`DESCENDER_OF_CAP`]) may reach into the padding under it but never past it to a line;
//! - a line's anchor is on its baseline, at the box's left side, middle or right side: a writer
//! aligns the line on it.
//!
//! Breaking a value into lines that fit the box's width, and warning about width, need the text
//! measured: they come with the paper scene's text.
use serde::{Deserialize, Serialize};
use crate::paper::MAX_COORDINATE_MM;
use crate::{Aabb2, EPS};
use solidcore_record::Vec2;
/// The most parts a cell's content may have.
pub const MAX_PARTS: usize = 64;
/// The most bytes of text a cell's content may hold in all, and a label.
pub const MAX_TEXT_BYTES: usize = 4096;
/// The space between the inner edge of a cell's lines and its text, in millimetres.
pub const PADDING_MM: f64 = 1.0;
/// How far a line's descenders reach below its baseline, as a share of its cap height: ISO 3098's
/// lettering B, whose lower-case tails are 3/10 of the capitals' height. They may reach into the
/// padding under a value box, never past it.
pub const DESCENDER_OF_CAP: f64 = 0.3;
/// Where a field's value comes from.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Source {
/// The component the sheet documents.
Component,
/// The drawing.
Drawing,
/// The sheet the cell is on.
Sheet,
/// The drawing's newest revision.
Revision,
/// An answer given when the block was placed.
Prompt,
}
/// One part of a cell's content. Externally tagged: `{"text": "Sheet "}`,
/// `{"field": {"source": "sheet", "key": "number"}}`.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", deny_unknown_fields)]
pub enum Part {
/// Text shown as written.
Text(String),
/// The value `source` holds under `key` (such as `component` `mass`), shown by `format`.
Field {
source: Source,
key: String,
#[serde(default)]
format: Format,
},
}
/// How a field's number is shown; what isn't given comes from the caller's settings.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Format {
pub unit: Option<String>,
pub decimals: Option<u8>,
}
/// What a cell shows: its parts in order.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Content(pub Vec<Part>);
/// What a value should fit beyond its box.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Fit {
/// The most characters a value should have, line breaks not counted.
pub max_chars: Option<u32>,
/// The most for a value with a wide character (Chinese, Japanese, Korean or Yi), when it
/// differs from `max_chars`.
pub wide_max_chars: Option<u32>,
/// The value breaks between words to fit the box's width, its lines running down from the top.
#[serde(default)]
pub wrap: bool,
}
/// Where a line sits across its box.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum HAlign {
#[default]
Left,
Centre,
Right,
}
/// The projection a drawing's views use, first or third angle (ISO 5456-2): the value of
/// `drawing.projection`, which the views and the title block's symbol both read.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Projection {
First,
Third,
}
/// What doesn't fit, when a value is shown whole.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Warning {
/// More characters than the fit allows.
Chars { count: usize, max: u32 },
/// More lines than the value box holds.
Height,
}
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("cell: {0}")]
pub struct Invalid(pub &'static str);
type Result<T> = std::result::Result<T, Invalid>;
fn require(condition: bool, message: &'static str) -> Result<()> {
if condition { Ok(()) } else { Err(Invalid(message)) }
}
/// Checks text by the module's rule: at most [`MAX_TEXT_BYTES`] in all, and no control character
/// but a line break.
fn check_text<'a>(texts: impl IntoIterator<Item = &'a str>) -> Result<()> {
let mut bytes = 0usize;
for text in texts {
bytes = bytes.saturating_add(text.len());
require(bytes <= MAX_TEXT_BYTES, "a cell's text is at most 4096 bytes")?;
require(!text.chars().any(|c| c.is_control() && c != '\n'), "a cell's text has no control character but a line break")?;
}
Ok(())
}
impl Part {
/// Its text, or its key and unit.
fn texts(&self) -> impl Iterator<Item = &str> {
let (first, unit) = match self {
Part::Text(text) => (text.as_str(), None),
Part::Field { key, format, .. } => (key.as_str(), format.unit.as_deref()),
};
std::iter::once(first).chain(unit)
}
}
impl Content {
/// Checks the content's size: at most [`MAX_PARTS`] parts, counted first, and its text, keys
/// and units by the module's text rule.
pub fn validate(&self) -> Result<()> {
require(self.0.len() <= MAX_PARTS, "a cell has at most 64 parts")?;
check_text(self.0.iter().flat_map(Part::texts))
}
}
/// Checks a label's text: one line of at most [`MAX_TEXT_BYTES`], without control characters.
pub fn check_label(text: &str) -> Result<()> {
require(text.len() <= MAX_TEXT_BYTES && !text.chars().any(char::is_control), "a label is one line of at most 4096 bytes")
}
impl Fit {
/// [`Warning::Chars`] when `text` has more characters than the fit allows. A text with a wide
/// character is held to `wide_max_chars` when it is given.
pub fn warn_chars(&self, text: &str) -> Option<Warning> {
let wide = text.chars().any(is_wide);
let max = if wide { self.wide_max_chars.or(self.max_chars) } else { self.max_chars }?;
let count = text.chars().filter(|&c| c != '\n').count();
(count > max as usize).then_some(Warning::Chars { count, max })
}
}
/// The Unicode blocks of the scripts written in wide characters (Chinese, Japanese, Korean and Yi),
/// with their full-width and vertical forms.
const WIDE: &[(u32, u32)] = &[
(0x1100, 0x115F),
(0x2E80, 0x303E),
(0x3041, 0x33FF),
(0x3400, 0x4DBF),
(0x4E00, 0x9FFF),
(0xA000, 0xA4CF),
(0xA960, 0xA97F),
(0xAC00, 0xD7A3),
(0xF900, 0xFAFF),
(0xFE10, 0xFE19),
(0xFE30, 0xFE6F),
(0xFF00, 0xFF60),
(0xFFE0, 0xFFE6),
(0x20000, 0x2FFFD),
(0x30000, 0x3FFFD),
];
fn is_wide(c: char) -> bool {
let c = u32::from(c);
WIDE.iter().any(|&(first, last)| (first..=last).contains(&c))
}
/// Where a label `cap_mm` high goes in `cell` (the cell inside its lines): its baseline's left end.
pub fn label_at(cell: Aabb2, cap_mm: f64) -> Vec2 {
Vec2::new(cell.min.x + PADDING_MM, cell.max.y - PADDING_MM - cap_mm)
}
/// The box a cell's value goes in, under a label `label_cap_mm` high when it has one (`cell`: the
/// cell inside its lines).
pub fn value_box(cell: Aabb2, label_cap_mm: Option<f64>) -> Aabb2 {
let inset = cell.inflated(-PADDING_MM);
match label_cap_mm {
Some(cap_mm) => Aabb2 { max: Vec2::new(inset.max.x, label_at(cell, cap_mm).y - PADDING_MM), ..inset },
None => inset,
}
}
/// Where `lines` lines `cap_mm` high go in `value_box`, `pitch_mm` apart, by the module's rule:
/// the first line's anchor, each next line `pitch_mm` below the one before, and
/// [`Warning::Height`] when the last baseline is below the box or its descenders below the padding
/// under it. The box lies within the paper's coordinates ([`MAX_COORDINATE_MM`]), so the anchor is
/// always finite.
pub fn place_lines(value_box: Aabb2, lines: usize, cap_mm: f64, pitch_mm: f64, align: HAlign, wrap: bool) -> Result<(Vec2, Option<Warning>)> {
let Aabb2 { min, max } = value_box;
let on_paper = [min.x, min.y, max.x, max.y].into_iter().all(|v| v.abs() <= MAX_COORDINATE_MM);
require(on_paper && min.x <= max.x && min.y <= max.y, "a value box is not inside out and lies within the paper's coordinates")?;
require([cap_mm, pitch_mm].into_iter().all(|v| v.is_finite() && v > 0.0), "a cap height and a line pitch are finite and above 0")?;
let x = match align {
HAlign::Left => min.x,
HAlign::Centre => value_box.center().x,
HAlign::Right => max.x,
};
let y = if lines == 1 && !wrap { value_box.center().y - cap_mm / 2.0 } else { max.y - cap_mm };
let last = y - lines.saturating_sub(1) as f64 * pitch_mm;
// How far above the box's bottom the last baseline must be for its descenders to stay in the padding.
let reach = (cap_mm * DESCENDER_OF_CAP - PADDING_MM).max(0.0);
let overflows = lines > 0 && last - reach < min.y - EPS;
Ok((Vec2::new(x, y), overflows.then_some(Warning::Height)))
}
#[cfg(test)]
#[path = "cell_tests.rs"]
mod tests;