geop_ops_model/parameters/

steps.rs

//! The steps a program says what its part is by, besides its shape: its
//! parameters ([`DefineParameters`]), the tables a part family looks its
//! size up in ([`LookupTable`]) and its properties ([`PartProperties`]).
//! Each produces targets as any step does: a formula reads a parameter's
//! target, and what lists the part reads its properties'. Every step that
//! defines parameters adds them to the part's [`ParameterValues`], a chain.
//!
//! What a parameter is set to where the part is built is the run's input
//! of its name — a [`Setting`] a program placing the part gives — and its
//! own definition where none is given. The colour is set the same way, by
//! the input [`COLOR`], and the part is drawn in it ([`PartColor`]).

use std::borrow::Cow;

use geop_core_editor::{
    edit_form::{EditForm, FormState},
    editable::{Context, OperationGroup, OperationInfo, OperationTier},
    editing::{
        Action, Cell, Choice, Column, ColumnKind, Control, Layout, Table, TableEdit, TableRow,
        Tone, Unit,
    },
    part_operation,
    part_operation::PartOperation,
    registry::{Drawer, StructureItem},
    view::PartView,
};
use geop_core_math::geop_error::{GeopError, GeopResult, WithContext};
use geop_core_program::{
    element::{ElementReference, HasElements, Kind, whole},
    numeric::{
        ParameterValue, ParameterValues, evaluate, names_in, parameter, parameter_values,
        read_parameter, read_parameter_values,
    },
    part::StepContext,
    reader::Reader,
    target::{Target, TargetReference},
    values::Setting,
};
use serde::{Deserialize, Serialize};

use crate::{
    Face, NamedModel,
    parameters::definition::{
        COLOR, Material, NumberParameter, Row, validate_color, validate_name,
    },
};

/// The kind of the step defining a program's parameters, and its id.
pub const PARAMETERS: &str = "parameters";

/// The kind of the step defining a part's properties, and its id.
pub const PROPERTIES: &str = "properties";

/// The kind of the step looking a part family's size up in a table.
pub const LOOKUP: &str = "lookup_table";

/// Defines the program's number parameters, each a target of its own
/// ([`parameter`]): what the run's input of its name sets it to, else what
/// it is defined as. A formula may read any other parameter of the step,
/// defined before it or after, and those the steps before defined — a
/// table's columns; one reading one that reads it back fails, saying so.
#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct DefineParameters;

#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct DefineParametersArgs {
    #[serde(default)]
    pub values: Vec<NumberParameter>,
}

part_operation!(DefineParameters(DefineParametersArgs));

impl PartOperation for DefineParameters {
    const KIND: &'static str = PARAMETERS;
    const INFO: OperationInfo = OperationInfo::new(
        "Parameters",
        "The numbers the design is given by, which a program placing the part may set.",
        OperationGroup::Part,
        OperationTier::Small,
    )
    .shortcut("Shift+V")
    .icon(crate::parameters::icons::PARAMETERS);
    type Args = DefineParametersArgs;
    type Session = ();

    fn new_args(_: &Context) -> DefineParametersArgs {
        DefineParametersArgs::default()
    }

    /// Each parameter, in an order in which a formula's parameters come
    /// before it, and then the step's entries of the part's parameter
    /// values.
    fn run(ctx: &mut StepContext, args: &DefineParametersArgs) -> GeopResult<()> {
        let step = ctx.step();
        for (i, p) in args.values.iter().enumerate() {
            validate_name(&p.name).map_err(|e| e.with_context(format!("parameters({step})")))?;
            if args.values[..i].iter().any(|q| q.name == p.name) {
                return Err(GeopError::new(format!(
                    "there is more than one parameter {:?}",
                    p.name
                )));
            }
        }
        for p in in_order(&args.values) {
            ctx.produce(&parameter(&p.name), p, value_of)?;
        }
        let names: Vec<String> = args.values.iter().map(|p| p.name.clone()).collect();
        ctx.produce(&parameter_values(), &names, add_values)
    }

    /// The parameters as a table, in a popup: a row each, of its name, its
    /// value — a number or a formula, and what it comes to in the part as
    /// the step built it — and what a slider offers, from and to. A row
    /// added is a fresh `length` of 10. A name typed here renames the
    /// definition alone: a formula still reading the old name fails,
    /// naming it, until it is changed too.
    fn form<'a>(
        ctx: &'a Context<'a>,
        args: &DefineParametersArgs,
        _: &FormState<()>,
    ) -> EditForm<'a, DefineParametersArgs> {
        let mut f = EditForm::<DefineParametersArgs>::default();
        f.layout(Layout::Popup);
        let reader = ctx.built.as_ref().unwrap_or(&ctx.before);
        let columns = vec![
            Column::new("Name", ColumnKind::Text),
            Column::new("Value", ColumnKind::Formula),
            Column::new("Slider from", ColumnKind::Number { unit: Unit::Length }),
            Column::new("to", ColumnKind::Number { unit: Unit::Length }),
        ];
        let optional = |n: Option<f64>| Cell::new(n.map(|n| n.to_string()).unwrap_or_default());
        let rows = (args.values.iter())
            .map(|p| {
                let value = match evaluate(&p.expression, |name| read_parameter(reader, name)) {
                    Ok(value) => Cell::new(&p.expression).detail(format!("= {value}"), Tone::Hint),
                    Err(e) => Cell::new(&p.expression).detail(e.root_message(), Tone::Error),
                };
                TableRow::new(vec![
                    Cell::new(&p.name),
                    value,
                    optional(p.min),
                    optional(p.max),
                ])
            })
            .collect();
        let table = Table::new(columns, rows, "No parameters yet: add a row.");
        f.table("parameters", table, |edit, what| {
            let values = &mut edit.args.values;
            match what {
                TableEdit::Cell { row, column, text } => {
                    let Some(p) = values.get_mut(row) else {
                        return;
                    };
                    match column {
                        0 => p.name = text.trim().to_string(),
                        1 => p.expression = text.trim().to_string(),
                        2 => p.min = text.trim().parse().ok(),
                        3 => p.max = text.trim().parse().ok(),
                        _ => {}
                    }
                }
                TableEdit::AddRow => {
                    let names: Vec<String> = values.iter().map(|p| p.name.clone()).collect();
                    values.push(NumberParameter {
                        name: fresh_name(&names, "length"),
                        expression: "10".into(),
                        min: None,
                        max: None,
                    });
                }
                TableEdit::RemoveRow { row } => {
                    if row < values.len() {
                        values.remove(row);
                    }
                }
                TableEdit::MoveRow { row, to } => move_row(values, row, to),
                // No row is chosen, and the columns are the step's.
                TableEdit::SelectRow { .. }
                | TableEdit::Column { .. }
                | TableEdit::AddColumn
                | TableEdit::RemoveColumn { .. }
                | TableEdit::Paste { .. } => {}
            }
        });
        f
    }
}

/// The row `row` of `rows` moved to be the row `to`; nothing, for a row
/// there is none of.
fn move_row<R>(rows: &mut Vec<R>, row: usize, to: usize) {
    if row < rows.len() {
        let moved = rows.remove(row);
        rows.insert(to.min(rows.len()), moved);
    }
}

/// The part's parameter values as the steps before left them, and the
/// parameters `names` as they come to — a parameter that failed left out.
/// The make of a step's entries of the [`ParameterValues`] chain.
#[allow(clippy::ptr_arg, reason = "a make takes its arguments as produced")]
fn add_values(reader: &Reader, names: &Vec<String>) -> GeopResult<ParameterValues> {
    let mut values: ParameterValues = reader.previous()?;
    values.0.extend((names.iter()).filter_map(|name| {
        let value = reader.retrieve_element(&ElementReference::whole(parameter(name)));
        Some((name.clone(), value.ok()?.clone()))
    }));
    Ok(values)
}

/// `values` in an order in which a number comes after every parameter of
/// the step its formula names: the numbers as their formulas' names are
/// defined, then — reading what is not there, or reading each other — the
/// rest, which fail.
fn in_order(values: &[NumberParameter]) -> Vec<&NumberParameter> {
    let mut ordered: Vec<&NumberParameter> = Vec::with_capacity(values.len());
    let mut left: Vec<&NumberParameter> = values.iter().collect();
    loop {
        let ready = left.iter().position(|p| {
            names_in(&p.expression).iter().all(|name| {
                ordered.iter().any(|q| q.name == *name) || !values.iter().any(|q| q.name == *name)
            })
        });
        match ready {
            Some(at) => ordered.push(left.remove(at)),
            None => break,
        }
    }
    ordered.extend(left);
    ordered
}

/// What the parameter `p` is set to: the run's input of its name if it is
/// given a number, else its formula of the other parameters.
fn value_of(reader: &Reader, p: &NumberParameter) -> GeopResult<ParameterValue> {
    match reader.retrieve_input(&p.name) {
        Some(Setting::Number(value)) => Ok(ParameterValue::Number(value)),
        _ => Ok(ParameterValue::Number(evaluate(&p.expression, |name| {
            read_parameter(reader, name)
        })?)),
    }
}

/// Looks the row a part family is built in up in a table: the row the
/// run's text input `input` names — `size = "M4"` from a program placing
/// the part — else the row `selected`. Defines the parameter `input` as the
/// row's name, and `input.column` as its value in each column (`size.d`),
/// each a target of its own ([`parameter`]), and adds them to the part's
/// [`ParameterValues`]. A text that names no row fails, naming the input
/// and the rows.
#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct LookupTable;

/// A table of the variants of a part family, one per row, looked up by the
/// input `input`.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct LookupTableArgs {
    pub input: String,
    pub columns: Vec<String>,
    pub rows: Vec<Row>,
    /// The row built where the run names none.
    pub selected: String,
}

impl LookupTableArgs {
    /// Checks the names of the input and the columns, that every row has a
    /// value per column, and that the row `selected` is there.
    pub fn validate(&self) -> GeopResult<()> {
        let ctx = |e: GeopError| e.with_context(format!("the table {:?}", self.input));
        validate_name(&self.input).map_err(ctx)?;
        for c in &self.columns {
            validate_name(c).map_err(|e| ctx(e.with_context("a column")))?;
        }
        for row in &self.rows {
            if row.values.len() != self.columns.len() {
                return Err(ctx(GeopError::new(format!(
                    "row {:?} has {} values for {} columns",
                    row.name,
                    row.values.len(),
                    self.columns.len()
                ))));
            }
        }
        if !self.rows.iter().any(|r| r.name == self.selected) {
            return Err(ctx(GeopError::new(format!(
                "there is no row {:?} to select",
                self.selected
            ))));
        }
        Ok(())
    }

    /// The name the value of `column` is read by: `size.d`.
    pub fn column(&self, column: &str) -> String {
        format!("{}.{column}", self.input)
    }
}

part_operation!(LookupTable(LookupTableArgs));

impl PartOperation for LookupTable {
    const KIND: &'static str = LOOKUP;
    const INFO: OperationInfo = OperationInfo::new(
        "Table",
        "A table of the variants of a part family — screw sizes, say — of which a program placing the part picks one by name.",
        OperationGroup::Part,
        OperationTier::Small,
    )
    .icon(crate::parameters::icons::LOOKUP_TABLE);
    type Args = LookupTableArgs;
    type Session = ();

    fn new_args(_: &Context) -> LookupTableArgs {
        LookupTableArgs {
            input: "size".into(),
            columns: vec!["d".into()],
            rows: vec![Row {
                name: "A".into(),
                values: vec![1.0],
            }],
            selected: "A".into(),
        }
    }

    /// The row, then each column of it, then the step's entries of the
    /// part's parameter values.
    fn run(ctx: &mut StepContext, args: &LookupTableArgs) -> GeopResult<()> {
        args.validate()
            .map_err(|e| e.with_context(format!("lookup_table({})", ctx.step())))?;
        ctx.produce(&parameter(&args.input), args, row_of)?;
        let mut names = vec![args.input.clone()];
        for (k, column) in args.columns.iter().enumerate() {
            let name = args.column(column);
            ctx.produce(
                &parameter(&name),
                &(args.input.clone(), k, args.rows.clone()),
                column_of,
            )?;
            names.push(name);
        }
        ctx.produce(&parameter_values(), &names, add_values)
    }

    /// The table, in a popup: the input it is looked up by, and its rows —
    /// each named in the first column, the one built where the run names
    /// none chosen — with a value per column; the columns are the user's,
    /// named in their headers. A column or a row added is named afresh and
    /// its values are 0; the last row is not taken out, and taking out the
    /// row chosen chooses the first left.
    fn form<'a>(
        _: &'a Context<'a>,
        args: &LookupTableArgs,
        _: &FormState<()>,
    ) -> EditForm<'a, LookupTableArgs> {
        let mut f = EditForm::<LookupTableArgs>::default();
        f.layout(Layout::Popup);
        f.input(
            "input",
            "Looked up by",
            &args.input,
            Some("size"),
            |edit, name| edit.args.input = name.trim().to_string(),
        );
        let mut columns = vec![Column::new("Row", ColumnKind::Text)];
        columns.extend((args.columns.iter()).map(|column| {
            Column::new(column, ColumnKind::Number { unit: Unit::Length }).editable()
        }));
        let rows = (args.rows.iter())
            .map(|row| TableRow {
                cells: (std::iter::once(Cell::new(&row.name)))
                    .chain(row.values.iter().map(|v| Cell::number(*v)))
                    .collect(),
                selected: row.name == args.selected,
                removable: args.rows.len() > 1,
            })
            .collect();
        let table = Table::new(columns, rows, "No rows: add one.")
            .columns_editable()
            .selectable();
        f.table("table", table, |edit, what| {
            let args = &mut *edit.args;
            match what {
                TableEdit::Cell {
                    row,
                    column: 0,
                    text,
                } => {
                    let Some(r) = args.rows.get_mut(row) else {
                        return;
                    };
                    let name = text.trim().to_string();
                    if args.selected == r.name {
                        args.selected = name.clone();
                    }
                    r.name = name;
                }
                TableEdit::Cell { row, column, text } => {
                    let cell = (args.rows.get_mut(row)).and_then(|r| r.values.get_mut(column - 1));
                    if let (Ok(n), Some(cell)) = (text.trim().parse::<f64>(), cell) {
                        *cell = n;
                    }
                }
                TableEdit::AddRow => {
                    let names: Vec<String> = args.rows.iter().map(|r| r.name.clone()).collect();
                    args.rows.push(Row {
                        name: fresh_name(&names, "row"),
                        values: vec![0.0; args.columns.len()],
                    });
                }
                TableEdit::RemoveRow { row } => {
                    if args.rows.len() > 1 && row < args.rows.len() {
                        let removed = args.rows.remove(row);
                        if removed.name == args.selected {
                            args.selected = args.rows[0].name.clone();
                        }
                    }
                }
                TableEdit::MoveRow { row, to } => move_row(&mut args.rows, row, to),
                TableEdit::SelectRow { row } => {
                    if let Some(r) = args.rows.get(row) {
                        args.selected = r.name.clone();
                    }
                }
                // The first column names the rows, and is the step's.
                TableEdit::Column { column: 0, .. } | TableEdit::RemoveColumn { column: 0 } => {}
                TableEdit::Column { column, text } => {
                    if let Some(c) = args.columns.get_mut(column - 1) {
                        *c = text.trim().to_string();
                    }
                }
                TableEdit::AddColumn => {
                    args.columns.push(fresh_name(&args.columns, "value"));
                    for row in &mut args.rows {
                        row.values.push(0.0);
                    }
                }
                TableEdit::RemoveColumn { column } => {
                    if column - 1 < args.columns.len() {
                        args.columns.remove(column - 1);
                        for row in &mut args.rows {
                            if column - 1 < row.values.len() {
                                row.values.remove(column - 1);
                            }
                        }
                    }
                }
                TableEdit::Paste { .. } => {}
            }
        });
        f
    }
}

/// `base`, or `base2`, `base3`, ... — the first not among `names`.
fn fresh_name(names: &[String], base: &str) -> String {
    let taken = |name: &str| names.iter().any(|n| n == name);
    let mut name = base.to_string();
    let mut n = 1;
    while taken(&name) {
        n += 1;
        name = format!("{base}{n}");
    }
    name
}

/// The row the table `args` is set to: the one the run's input names, else
/// its own selection. Fails for an input naming no row, or no text.
fn row_of(reader: &Reader, args: &LookupTableArgs) -> GeopResult<ParameterValue> {
    let wanted = match reader.retrieve_input(&args.input) {
        None => args.selected.clone(),
        Some(Setting::Text(row)) => row,
        Some(Setting::Number(n)) => {
            return Err(GeopError::new(format!(
                "the input {:?} is the number {n}: it names a row of its table by text",
                args.input
            )));
        }
    };
    match args.rows.iter().any(|row| row.name == wanted) {
        true => Ok(ParameterValue::Text(wanted)),
        false => {
            let rows: Vec<&str> = args.rows.iter().map(|row| row.name.as_str()).collect();
            Err(GeopError::new(format!(
                "the input {:?} is {wanted:?}, which names no row of its table: {}",
                args.input,
                rows.join(", ")
            )))
        }
    }
}

/// The value in the column at `k` of the row the table looked up by
/// `input`, of `rows`, is set to.
fn column_of(
    reader: &Reader,
    (input, k, rows): &(String, usize, Vec<Row>),
) -> GeopResult<ParameterValue> {
    let row = reader.retrieve_element(&ElementReference::whole(parameter(input)))?;
    let ParameterValue::Text(row) = row else {
        return Err(GeopError::new(format!(
            "the parameter {input:?} names no row"
        )));
    };
    let values = (rows.iter().find(|r| r.name == *row))
        .map(|r| &r.values)
        .ok_or_else(|| GeopError::new(format!("the table {input:?} has no row {row:?}")))?;
    (values.get(*k).copied())
        .map(ParameterValue::Number)
        .ok_or_else(|| {
            GeopError::new(format!(
                "row {row:?} of the table {input:?} has no column {k}"
            ))
        })
}

/// Defines what the part is called and ordered as, its colours, and what
/// it is made of: its [`properties`]. The colour is the run's input
/// [`COLOR`] where it is given one.
///
/// Its colours of faces name faces later steps make, and it comes first in
/// most programs, so it reads none of them: it holds their names, and the
/// viewer asks for a face's colour by the face's name. A name no face has
/// now fails nothing, and its dialog says so; a colour changed builds
/// nothing again. It is edited with the whole part built and picks in that
/// ([`OperationInfo::picks_whole`]).
#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct PartProperties;

/// What a part is, besides its shape.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct PartPropertiesArgs {
    /// What the part is, in words — `ISO 4762 socket head cap screw` —
    /// where it is listed: a bill of materials, a drawing's. None for a
    /// part known by its file's name.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    /// What the part is ordered as, before the parameters it is built with
    /// (see [`Properties::designation`]): a norm — `ISO 4762` — or a
    /// catalogue or part number. None for a part that is made rather than
    /// bought.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub designation: Option<String>,
    /// The part's colour, `#rrggbb`; none for the viewer's own.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub color: Option<String>,
    /// What the part is made of; none for a part whose material is not
    /// given, which has a volume and a centroid but no mass.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub material: Option<Material>,
    /// Faces in a colour of their own, over the part's: of a face named
    /// twice, the later.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub face_colors: Vec<FaceColor>,
}

/// Faces of the part in one colour.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct FaceColor {
    pub faces: Vec<ElementReference<NamedModel, Face>>,
    /// `#rrggbb`.
    pub color: String,
}

impl FaceColor {
    /// The list of `args`' colours of faces, each its faces picked, its
    /// colour and a button taking it out, and a button adding one. Which
    /// of the faces picked no longer are in `whole`, the part as built, or
    /// are not the part's own, is said beside each; `whole` is only asked
    /// for a dialog open (`open`), not for a list of steps.
    fn fields<'a>(
        f: &mut EditForm<'a, PartPropertiesArgs>,
        whole: &Reader<'a>,
        args: &PartPropertiesArgs,
        open: bool,
    ) {
        f.form.dialog.heading("face_colors", "Colours of faces");
        for (i, entry) in args.face_colors.iter().enumerate() {
            let key = face_color_key(i, "faces");
            f.pick(&key, "Faces", whole, &entry.faces, true, move |e, faces| {
                if let Some(entry) = e.args.face_colors.get_mut(i) {
                    entry.faces = faces;
                }
            });
            let field = f.form.dialog.0.iter_mut().find(|field| field.key == key);
            if let Some(Control::Reference(reference)) = field.map(|field| &mut field.control) {
                for (picked, face) in reference.value.iter_mut().zip(&entry.faces) {
                    // The face in its colour says that it is held: lit,
                    // the colour would not show.
                    picked.drawn.clear();
                    if let Some(why) = open.then(|| not_drawn(face, whole)).flatten() {
                        picked.tone = Tone::Error;
                        picked.detail = Some(why);
                    }
                }
            }
            let color = face_color_key(i, "color");
            f.color(&color, "Colour", &entry.color, move |e, c| {
                if let Some(entry) = e.args.face_colors.get_mut(i) {
                    entry.color = c.trim().to_string();
                }
            });
            let actions = vec![Action::new(REMOVE, "Take out")];
            f.actions(&face_color_key(i, "remove"), actions, move |e, _| {
                if i < e.args.face_colors.len() {
                    e.args.face_colors.remove(i);
                }
            });
        }
        let actions = vec![Action::new(ADD, "Add a colour of faces")];
        f.actions("face_color_add", actions, |e, _| {
            e.args.face_colors.push(FaceColor {
                faces: Vec::new(),
                color: NEW_FACE_COLOR.to_string(),
            });
        });
    }
}

/// The key of the field `field` of the `i`th colour of faces.
fn face_color_key(i: usize, field: &str) -> String {
    format!("face_color:{i}:{field}")
}

/// The value of the button taking a colour of faces out.
const REMOVE: &str = "remove";

/// The value of the button adding a colour of faces.
const ADD: &str = "add";

/// The colour a new colour of faces starts in: one a face picked shows
/// itself in at once, whatever the part's.
const NEW_FACE_COLOR: &str = "#d9483b";

/// Why the face `face` is drawn in no colour of the properties of the part
/// `reader` reads, if it is not: it is not a face of that part.
fn not_drawn(face: &ElementReference<NamedModel, Face>, reader: &Reader) -> Option<String> {
    if !face.instance().is_empty() {
        return Some(format!(
            "of the placed part `{}`: give it a colour in that part's properties",
            face.instance()
        ));
    }
    (reader.retrieve_element(face).err())
        .map(|_| "no face of the part has this name now: take it out, or pick another".into())
}

part_operation!(PartProperties(PartPropertiesArgs));

impl PartOperation for PartProperties {
    const KIND: &'static str = PROPERTIES;
    const INFO: OperationInfo = OperationInfo::new(
        "Properties",
        "What the part is called and ordered as, its colour, and what it is made of.",
        OperationGroup::Part,
        OperationTier::Small,
    )
    .icon(crate::parameters::icons::PROPERTIES)
    .picks_whole();
    type Args = PartPropertiesArgs;
    type Session = ();

    fn new_args(_: &Context) -> PartPropertiesArgs {
        PartPropertiesArgs::default()
    }

    fn run(ctx: &mut StepContext, args: &PartPropertiesArgs) -> GeopResult<()> {
        let step = ctx.step();
        if let Some(color) = &args.color {
            validate_color(color).map_err(|e| e.with_context(format!("properties({step})")))?;
        }
        for (i, entry) in args.face_colors.iter().enumerate() {
            validate_color(&entry.color)
                .map_err(|e| e.with_context(format!("properties({step}), colour of faces {i}")))
                .concerning(&face_color_key(i, "color"))?;
        }
        if let Some(Material { name, density }) = &args.material
            && !(density.is_finite() && *density > 0.0)
        {
            return Err(GeopError::new(format!(
                "the material {name:?} has a density of {density} kg/m³: it must be a positive number"
            )));
        }
        ctx.produce(&properties(), args, |reader, args| {
            let color = match reader.retrieve_input(COLOR) {
                Some(Setting::Text(color)) if validate_color(&color).is_ok() => Some(color),
                _ => args.color.clone(),
            };
            let designation = (args.designation.clone()).map(|designation| {
                let values = read_parameter_values(reader).unwrap_or_default();
                designate(&designation, &values)
            });
            Ok(Properties {
                title: args.title.clone(),
                designation,
                color,
                material: args.material.clone(),
                face_colors: args.face_colors.clone(),
            })
        })
    }

    /// Its title and designation typed, its colour picked, some faces in
    /// colours of their own, and its material chosen from the list
    /// ([`Material::listed`]), or none, or any other by its name and
    /// density.
    fn form<'a>(
        context: &'a Context<'a>,
        args: &PartPropertiesArgs,
        _: &FormState<()>,
    ) -> EditForm<'a, PartPropertiesArgs> {
        let mut f = EditForm::<PartPropertiesArgs>::default();
        let text = |text: &str| (!text.trim().is_empty()).then(|| text.trim().to_string());
        let title = args.title.clone().unwrap_or_default();
        f.input(
            "title",
            "Title",
            title,
            Some("the file's name"),
            move |e, t| {
                e.args.title = text(t);
            },
        );
        let designation = args.designation.clone().unwrap_or_default();
        f.input(
            "designation",
            "Designation",
            designation,
            Some("none"),
            move |e, t| {
                e.args.designation = text(t);
            },
        );
        let color = args.color.clone().unwrap_or_default();
        f.color("color", "Colour", color, move |e, c| e.args.color = text(c));
        FaceColor::fields(&mut f, &context.whole, args, context.built.is_some());
        let listed = |m: &Material| Material::named(&m.name).as_ref() == Some(m);
        let chosen = match &args.material {
            None => NO_MATERIAL,
            Some(m) if listed(m) => m.name.as_str(),
            Some(_) => OTHER_MATERIAL,
        };
        let options = (std::iter::once(Choice::new(NO_MATERIAL, "None")))
            .chain(Material::listed().map(|m| {
                let label = format!("{} — {} kg/m³", m.name, m.density);
                Choice::new(m.name, label)
            }))
            .chain(std::iter::once(Choice::new(
                OTHER_MATERIAL,
                "Other, by its density…",
            )))
            .collect();
        f.select(
            "material",
            "Material",
            chosen,
            options,
            true,
            move |e, choice| {
                e.args.material = match choice {
                    NO_MATERIAL => None,
                    // One not listed already stays as it is; one listed gives
                    // its density to start from.
                    OTHER_MATERIAL => match e.args.material.take() {
                        Some(m) if !listed(&m) => Some(m),
                        m => Some(Material {
                            name: "Other".into(),
                            density: m.map_or(OTHER_DENSITY, |m| m.density),
                        }),
                    },
                    name => Material::named(name),
                };
            },
        );
        if let Some(material) = args.material.as_ref().filter(|m| !listed(m)) {
            f.input(
                "material_name",
                "Name",
                material.name.clone(),
                None,
                move |e, t| {
                    if let (Some(material), Some(name)) = (&mut e.args.material, text(t)) {
                        material.name = name;
                    }
                },
            );
            let density = material.density.to_string();
            f.input("density", "Density (kg/m³)", density, None, |e, t| {
                if let (Some(material), Ok(density)) = (&mut e.args.material, t.trim().parse()) {
                    material.density = density;
                }
            });
        }
        if args.material.is_none() {
            let hint = "No material: the part has a volume, but no mass.";
            f.form.dialog.text("no_material", hint, Tone::Hint);
        }
        f
    }
}

/// What the material field sends for none.
const NO_MATERIAL: &str = "";

/// What the material field sends for one not listed, given by its density.
const OTHER_MATERIAL: &str = "other";

/// The density (kg/m³) a material not listed starts from when no material
/// was chosen before, until its own is typed.
const OTHER_DENSITY: f64 = 1000.0;

/// What the part designated `designation` built with `values` is ordered
/// as: the designation, then each parameter in order — a table's row by its
/// name, a number after its own, a table's columns not at all —
/// `ISO 4762 M4x12`, `T-slot 2020 length 500`.
fn designate(designation: &str, values: &ParameterValues) -> String {
    let mut words = vec![designation.to_string()];
    for (name, value) in &values.0 {
        match value {
            ParameterValue::Text(row) => words.push(row.clone()),
            ParameterValue::Number(_) if name.contains('.') => {}
            ParameterValue::Number(n) => words.push(format!("{name} {n}")),
        }
    }
    words.join(" ")
}

/// What a part is, besides its shape, as its program says: what it is
/// called and ordered as, its colour and what it is made of.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Properties {
    pub title: Option<String>,
    /// What it is ordered as, with what it was built with: none for a part
    /// made rather than bought.
    pub designation: Option<String>,
    pub color: Option<String>,
    pub material: Option<Material>,
    pub face_colors: Vec<FaceColor>,
}

/// Defined once, by the program's [`PartProperties`] step.
impl Target for Properties {}

/// Read whole.
impl Kind for Properties {
    const NAME: &'static str = "properties";
}

impl HasElements<Properties> for Properties {
    type Element<'a> = &'a Properties;
    const SINGLETON: Option<&'static str> = Some(PROPERTIES);

    fn element(&self, name: &str) -> GeopResult<&Properties> {
        whole(self, name)
    }
}

/// The part's properties, defined by its [`PartProperties`] step.
pub fn properties() -> TargetReference<Properties> {
    TargetReference::new(PROPERTIES)
}

/// The properties of the part `reader` reads: none set, for a part whose
/// program says nothing of them.
pub fn read_properties<'a>(reader: &Reader<'a>) -> GeopResult<Cow<'a, Properties>> {
    if !reader.defines(&properties()) {
        return Ok(Cow::Owned(Properties::default()));
    }
    Ok(Cow::Borrowed(reader.retrieve_element(
        &ElementReference::whole(properties()),
    )?))
}

/// Draws a part in the colour its properties give it (see
/// [`PartProperties`]).
pub struct PartColor;

impl Drawer for PartColor {
    fn draw(&self, reader: &Reader, view: &mut PartView) -> GeopResult<()> {
        read_properties(reader)?.draw(view);
        Ok(())
    }

    fn structure(&self, _: &Reader) -> GeopResult<Vec<StructureItem>> {
        Ok(Vec::new())
    }
}

impl Properties {
    /// What its part is made of: none for a part whose material is not
    /// given, which then has no mass.
    pub fn material(&self) -> Option<&Material> {
        self.material.as_ref()
    }

    /// Its part's colour, `#rrggbb`: none for the viewer's own.
    pub fn color(&self) -> Option<&str> {
        self.color.as_deref()
    }

    /// Its colours drawn: its part's, and its faces', by name, of the part's
    /// own faces: nothing of the faces is read, so changing one draws
    /// them again, and meshes nothing.
    pub fn draw(&self, view: &mut PartView) {
        view.color = self.color.clone();
        view.face_colors = (self.face_colors.iter())
            .flat_map(|entry| entry.faces.iter().map(|face| (face, &entry.color)))
            .filter(|(face, _)| face.instance().is_empty())
            .map(|(face, color)| (face.name().to_string(), color.clone()))
            .collect();
    }

    /// What its part is called where it is listed: its title, else `stem`
    /// — the name of the file it is placed from.
    pub fn name<'a>(&'a self, stem: &'a str) -> &'a str {
        self.title.as_deref().unwrap_or(stem)
    }
}

/// The name of the file `file`, without folders or `.geop`: what a part
/// placed from it is listed as without a title, and what a file written
/// from it is named after — `part` if that leaves nothing.
pub fn stem(file: &str) -> &str {
    let file = file.rsplit(['/', ':']).next().unwrap_or_default();
    match file.trim_end_matches(".geop") {
        "" => "part",
        stem => stem,
    }
}