///|
/// ParamSpec describes one named, unit-tagged, bounded design parameter.
///
/// The unit is a label only (`"mm"`, `"deg"`, `"count"`); the numeric value is
/// stored as a bare `Double`. Dimensions in this library are millimetres unless
/// a spec says otherwise.
pub(all) struct ParamSpec {
  name : String
  unit : String
  default_mm : Double
  min_mm : Double
  max_mm : Double
  description : String
}

///|
/// ParamSpec::new builds a parameter declaration. `min_mm` is inclusive and
/// `default_mm` must lie inside the range; `ParamSpec::validate` checks that.
pub fn ParamSpec::new(
  name~ : String,
  default_mm~ : Double,
  min_mm~ : Double = 0.0,
  max_mm~ : Double = 1.0e9,
  unit~ : String = "mm",
  description~ : String = "",
) -> ParamSpec {
  { name, unit, default_mm, min_mm, max_mm, description, }
}

///|
/// ParamSpec::validate checks a spec declaration itself.
pub fn ParamSpec::validate(self : ParamSpec) -> Result[Unit, SpecError] {
  if self.name == "" {
    return Err(InvalidParameter("parameter spec has an empty name"))
  }
  if self.min_mm > self.max_mm {
    return Err(
      InvalidParameter(
        "parameter '\{self.name}' has min > max (\{self.min_mm} > \{self.max_mm})",
      ),
    )
  }
  match
    require_in_range(
      "parameter '\{self.name}' default",
      self.default_mm,
      self.min_mm,
      self.max_mm,
    ) {
    Err(e) => return Err(e)
    Ok(_) => ()
  }
  Ok(())
}

///|
/// ParamSpec::documentation returns one human-readable spec line.
pub fn ParamSpec::documentation(self : ParamSpec) -> String {
  let unit = if self.unit == "" { "" } else { " " + self.unit }
  let range = if self.min_mm == 0.0 && self.max_mm == 1.0e9 {
    ""
  } else {
    " [\{self.min_mm}, \{self.max_mm}]"
  }
  let note = if self.description == "" {
    ""
  } else {
    " — " + self.description
  }
  "\{self.name} = \{self.default_mm}\{unit}\{range}\{note}"
}

///|
/// ParamSet is a validated name-to-value set declared by a list of specs.
///
/// Every spec is present exactly once. Values are validated against their spec
/// on construction and on every `with` update.
pub(all) struct ParamSet {
  specs : Array[ParamSpec]
  values : Map[String, Double]
}

///|
/// ParamSet::defaults builds a set using every spec's default value.
pub fn ParamSet::defaults(
  specs : Array[ParamSpec],
) -> Result[ParamSet, SpecError] {
  let values : Map[String, Double] = Map([])
  for spec in specs {
    match spec.validate() {
      Err(e) => return Err(e)
      Ok(_) => ()
    }
    if values.get(spec.name) is Some(_) {
      return Err(InvalidParameter("duplicate parameter '\{spec.name}'"))
    }
    values.set(spec.name, spec.default_mm)
  }
  Ok({ specs, values, })
}

///|
/// ParamSet::from_values builds a set from defaults plus named overrides.
///
/// Unknown names are rejected rather than ignored.
pub fn ParamSet::from_values(
  specs : Array[ParamSpec],
  values : Array[(String, Double)],
) -> Result[ParamSet, SpecError] {
  let mut set = match ParamSet::defaults(specs) {
    Ok(s) => s
    Err(e) => return Err(e)
  }
  for entry in values {
    let (name, value) = entry
    match set.set_value(name, value) {
      Err(e) => return Err(e)
      Ok(s) => set = s
    }
  }
  Ok(set)
}

///|
/// ParamSet::spec returns the declaration for a name.
pub fn ParamSet::spec(
  self : ParamSet,
  name : String,
) -> Result[ParamSpec, SpecError] {
  for spec in self.specs {
    if spec.name == name {
      return Ok(spec)
    }
  }
  Err(InvalidParameter("unknown parameter '\{name}'"))
}

///|
/// ParamSet::get returns a validated value.
pub fn ParamSet::get(
  self : ParamSet,
  name : String,
) -> Result[Double, SpecError] {
  match self.values.get(name) {
    Some(v) => Ok(v)
    None => Err(InvalidParameter("unknown parameter '\{name}'"))
  }
}

///|
/// ParamSet::set_value returns a copy with one parameter replaced and
/// validated.
pub fn ParamSet::set_value(
  self : ParamSet,
  name : String,
  value : Double,
) -> Result[ParamSet, SpecError] {
  let spec = match self.spec(name) {
    Err(e) => return Err(e)
    Ok(s) => s
  }
  match
    require_in_range("parameter '\{name}'", value, spec.min_mm, spec.max_mm) {
    Err(e) => return Err(e)
    Ok(_) => ()
  }
  let values = self.values.copy()
  values.set(name, value)
  Ok({ specs: self.specs, values, })
}

///|
/// ParamSet::length returns a parameter as a typed `@cad.Length`.
///
/// The parameter's unit must be `"mm"` or empty.
pub fn ParamSet::length(
  self : ParamSet,
  name : String,
) -> Result[@cad.Length, SpecError] {
  let spec = match self.spec(name) {
    Err(e) => return Err(e)
    Ok(s) => s
  }
  if spec.unit != "mm" && spec.unit != "" {
    return Err(
      InvalidParameter(
        "parameter '\{name}' has unit '\{spec.unit}', not a length",
      ),
    )
  }
  match self.get(name) {
    Err(e) => Err(e)
    Ok(v) => Ok(@cad.Length::mm(v))
  }
}

///|
/// ParamSet::names returns the declared parameter names in order.
pub fn ParamSet::names(self : ParamSet) -> Array[String] {
  self.specs.map(fn(spec) { spec.name })
}

///|
/// ParamSet::documentation returns one line per parameter.
pub fn ParamSet::documentation(self : ParamSet) -> String {
  let lines : Array[String] = []
  for spec in self.specs {
    let value = self.values.get(spec.name).unwrap_or(spec.default_mm)
    lines.push(
      "\{spec.name} = \{value}\{if spec.unit == "" { "" } else { " " + spec.unit }}",
    )
  }
  lines.join("\n")
}

///|
/// DesignFamily is a named parametric design with a validated parameter schema
/// and a builder from a `ParamSet` to a `Component`.
///
/// It is additive: existing builders keep their direct `Double` signatures, and
/// a family wraps one for interactive or scripted design exploration.
pub(all) struct DesignFamily {
  name : String
  description : String
  specs : Array[ParamSpec]
  build_fn : (ParamSet) -> Result[Component, SpecError]
  variants : Array[(String, ParamSet)]
}

///|
/// DesignFamily::new builds a design family and validates its parameter schema.
pub fn DesignFamily::new(
  name~ : String,
  specs~ : Array[ParamSpec],
  build~ : (ParamSet) -> Result[Component, SpecError],
  description~ : String = "",
) -> Result[DesignFamily, SpecError] {
  if name == "" {
    return Err(InvalidParameter("design family has an empty name"))
  }
  match ParamSet::defaults(specs) {
    Err(e) => Err(e)
    Ok(_) => Ok({ name, description, specs, build_fn: build, variants: [], })
  }
}

///|
/// DesignFamily::parameter_names returns the declared parameter names.
pub fn DesignFamily::parameter_names(self : DesignFamily) -> Array[String] {
  self.specs.map(fn(spec) { spec.name })
}

///|
/// DesignFamily::defaults returns the default parameter set.
pub fn DesignFamily::defaults(
  self : DesignFamily,
) -> Result[ParamSet, SpecError] {
  ParamSet::defaults(self.specs)
}

///|
/// DesignFamily::from_values validates a named override list.
pub fn DesignFamily::from_values(
  self : DesignFamily,
  values : Array[(String, Double)],
) -> Result[ParamSet, SpecError] {
  ParamSet::from_values(self.specs, values)
}

///|
/// DesignFamily::build validates and builds a component from a parameter set.
pub fn DesignFamily::build(
  self : DesignFamily,
  parameters : ParamSet,
) -> Result[Component, SpecError] {
  for spec in self.specs {
    match parameters.get(spec.name) {
      Err(e) => return Err(e)
      Ok(v) =>
        match require_in_range(spec.name, v, spec.min_mm, spec.max_mm) {
          Err(e) => return Err(e)
          Ok(_) => ()
        }
    }
  }
  (self.build_fn)(parameters)
}

///|
/// DesignFamily::build_values validates overrides and builds in one step.
pub fn DesignFamily::build_values(
  self : DesignFamily,
  values : Array[(String, Double)],
) -> Result[Component, SpecError] {
  let parameters = match self.from_values(values) {
    Err(e) => return Err(e)
    Ok(p) => p
  }
  self.build(parameters)
}

///|
/// DesignFamily::with_variant registers a named parameter preset.
pub fn DesignFamily::with_variant(
  self : DesignFamily,
  variant_name : String,
  values : Array[(String, Double)],
) -> Result[DesignFamily, SpecError] {
  let parameters = match self.from_values(values) {
    Err(e) => return Err(e)
    Ok(p) => p
  }
  let variants = self.variants.copy()
  variants.push((variant_name, parameters))
  Ok({ ..self, variants, })
}

///|
/// DesignFamily::variant returns a named preset, or an error when absent.
pub fn DesignFamily::variant(
  self : DesignFamily,
  variant_name : String,
) -> Result[ParamSet, SpecError] {
  for entry in self.variants {
    let (name, parameters) = entry
    if name == variant_name {
      return Ok(parameters)
    }
  }
  Err(
    InvalidParameter(
      "unknown variant '\{variant_name}' in family '\{self.name}'",
    ),
  )
}

///|
/// DesignFamily::variant_names returns the registered preset names.
pub fn DesignFamily::variant_names(self : DesignFamily) -> Array[String] {
  self.variants.map(fn(entry) { entry.0 })
}

///|
/// DesignFamily::build_variant builds a registered preset.
pub fn DesignFamily::build_variant(
  self : DesignFamily,
  variant_name : String,
) -> Result[Component, SpecError] {
  let parameters = match self.variant(variant_name) {
    Err(e) => return Err(e)
    Ok(p) => p
  }
  self.build(parameters)
}

///|
/// DesignFamily::documentation returns the family description and every
/// parameter spec with its current default.
pub fn DesignFamily::documentation(self : DesignFamily) -> String {
  let lines : Array[String] = ["Design family: " + self.name]
  if self.description != "" {
    lines.push(self.description)
  }
  for spec in self.specs {
    lines.push("  " + spec.documentation())
  }
  if self.variants.length() > 0 {
    lines.push("Variants: " + self.variant_names().join(", "))
  }
  lines.join("\n")
}