"use strict";

function round2(x) { return Math.round(x * 100) / 100; }
const RAD2DEG = 180 / Math.PI;

module.exports = {
  slug: "slope-grade-and-angle",
  title: "Slope grade percent and angle from rise and run",
  deck_category: "geometry",
  description: "Computes the percent grade and the angle from horizontal for a given rise and run.",
  inputs: [
    { name: "rise", type: "number", unit: "length units", required: true, description: "Vertical change.", min: 0 },
    { name: "run", type: "number", unit: "length units", required: true, description: "Horizontal change.", min: 0 }
  ],
  outputs: [
    { name: "grade_percent", unit: "%", description: "Slope expressed as percent grade." },
    { name: "angle_degrees", unit: "degrees", description: "Slope expressed as an angle from horizontal." }
  ],
  steps: [
    "Percent grade = (rise / run) * 100.",
    "Angle in degrees = atan(rise / run) converted from radians to degrees.",
    "Round both to 2 decimals."
  ],
  constants: [],
  sources: [
    { kind: "edition_page", value: "Standard geometry/surveying reference (e.g. Coxeter, H.S.M. Introduction to Geometry, 2nd ed., Wiley, 1969, right-triangle trigonometry).", title: "Grade percent and slope angle from rise over run", publisher: "Wiley", retrieved_utc: "2026-09-30T19:51:00Z", note: "Standard definitions: grade% = 100*rise/run; angle = atan(rise/run)." }
  ],
  disclaimer: null,
  questionText(inputs) {
    return `What are the percent grade and the angle from horizontal for a rise of ${inputs.rise} over a run of ${inputs.run}?`;
  },
  run(inputs) {
    const { rise, run } = inputs || {};
    if (typeof rise !== "number" || rise < 0) throw new Error("rise must be a non-negative number");
    if (typeof run !== "number" || run <= 0) throw new Error("run must be a positive number");
    const gradePercent = round2((rise / run) * 100);
    const angleDegrees = round2(Math.atan(rise / run) * RAD2DEG);
    return { answer: `grade ${gradePercent.toFixed(2)}%, angle ${angleDegrees.toFixed(2)} degrees`, values: { grade_percent: gradePercent, angle_degrees: angleDegrees } };
  },
  examples: [
    {
      name: "worked example",
      inputs: { rise: 1, run: 4 },
      expected: { answer: "grade 25.00%, angle 14.04 degrees" },
      check: "By hand: grade=100*(1/4)=25.00%, a well known road-grade reference value; angle=atan(0.25)=14.0362 degrees rounds to 14.04, cross-checked against a tangent table (tan(14 degrees)=0.2493, close to 0.25)."
    },
    {
      name: "test vector: 45-degree slope",
      inputs: { rise: 3, run: 3 },
      expected: { answer: "grade 100.00%, angle 45.00 degrees" },
      check: "Equal rise and run is the well known definition of a 45-degree slope (100% grade), since tan(45 degrees)=1 exactly."
    }
  ]
};