'use strict';
// area-conversion.cjs -- METHOD DECK (X063), reversible area unit conversion.
// Factors are exact square-meter equivalents derived from the NIST SP 811 (2008 ed.) length
// definitions (ft2 = 0.3048^2, mi2 = 1609.344^2), and the exact acre and hectare definitions.

function roundSig(x, sig) {
  if (x === 0) return { value: 0, decimals: 0 };
  const neg = x < 0;
  const ax = Math.abs(x);
  let exp = Math.floor(Math.log10(ax));
  let decimals = Math.max(sig - exp - 1, 0);
  let factor = Math.pow(10, decimals);
  let value = Math.round(ax * factor) / factor;
  const newExp = value === 0 ? exp : Math.floor(Math.log10(value));
  if (newExp !== exp) {
    decimals = Math.max(sig - newExp - 1, 0);
    factor = Math.pow(10, decimals);
    value = Math.round(ax * factor) / factor;
  }
  return { value: neg ? -value : value, decimals };
}
function fmt(x, decimals) {
  return x.toLocaleString('en-US', { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
}
function fmtSig(x, sig) {
  const r = roundSig(x, sig);
  return fmt(r.value, r.decimals);
}

// Square meters per 1 unit.
const TO_M2 = {
  m2: 1,
  ha: 10000,
  km2: 1000000,
  ft2: 0.09290304,
  acre: 4046.8564224,
  mi2: 2589988.110336,
};
const UNITS = Object.keys(TO_M2);

module.exports = {
  slug: 'area-conversion',
  title: 'Area conversion',
  deck_category: 'units',
  description: 'Converts an area between metric and US customary units using exact square-meter equivalents.',
  inputs: [
    { name: 'value', type: 'number', unit: 'from_unit', required: true, description: 'The area to convert' },
    { name: 'from_unit', type: 'string', required: true, description: 'Unit of the input value', enum: UNITS },
    { name: 'to_unit', type: 'string', required: true, description: 'Unit to convert into', enum: UNITS },
  ],
  outputs: [ { name: 'result', unit: 'to_unit', description: 'The converted area' } ],
  steps: [
    'Look up the exact square-meter equivalent of from_unit and of to_unit.',
    'Convert the input to square meters: sqm = value * m2_per(from_unit).',
    'Convert square meters to the target unit: result = sqm / m2_per(to_unit).',
    'Round result to 6 significant figures.',
  ],
  constants: [
    { name: 'm2', value: 1, unit: 'm2', source: 0 },
    { name: 'ha', value: 10000, unit: 'm2', source: 0 },
    { name: 'km2', value: 1000000, unit: 'm2', source: 0 },
    { name: 'ft2', value: 0.09290304, unit: 'm2', source: 0 },
    { name: 'acre', value: 4046.8564224, unit: 'm2', source: 0 },
    { name: 'mi2', value: 2589988.110336, unit: 'm2', source: 0 },
  ],
  sources: [
    { kind: 'standard', value: 'NIST Special Publication 811 (2008 edition), Appendix B.8, Table for length and area (ft2 = 0.3048 m squared; mi2 = 1609.344 m squared; acre = 4046.8564224 m2 exactly; hectare = 10,000 m2 exactly)', title: 'Guide for the Use of the International System of Units (SI)', publisher: 'National Institute of Standards and Technology', retrieved_utc: '2026-09-30T19:29:48Z', note: 'ft2 and mi2 are exact squares of the NIST SP 811 exact length definitions; the international acre and the hectare are exact by definition.' },
  ],
  disclaimer: null,
  questionText(inputs) {
    return `How many ${inputs.to_unit} are in ${inputs.value} ${inputs.from_unit}?`;
  },
  run(inputs) {
    const { value, from_unit, to_unit } = inputs || {};
    if (typeof value !== 'number' || !isFinite(value)) throw new Error('value must be a finite number');
    if (!TO_M2.hasOwnProperty(from_unit)) throw new Error('from_unit must be one of: ' + UNITS.join(', '));
    if (!TO_M2.hasOwnProperty(to_unit)) throw new Error('to_unit must be one of: ' + UNITS.join(', '));
    const sqm = value * TO_M2[from_unit];
    const result = sqm / TO_M2[to_unit];
    return { answer: `${fmtSig(result, 6)} ${to_unit}`, values: { result } };
  },
  examples: [
    { name: 'worked example', inputs: { value: 1, from_unit: 'acre', to_unit: 'm2' },
      expected: { answer: '4,046.86 m2' },
      check: 'By definition 1 acre = 4046.8564224 m2 exactly; rounded to 6 significant figures is 4046.86.' },
    { name: 'test vector: square kilometers to hectares', inputs: { value: 1, from_unit: 'km2', to_unit: 'ha' },
      expected: { answer: '100.000 ha' },
      check: 'By hand: 1,000,000 m2 / 10,000 m2 = 100 exactly.' },
    { name: 'test vector: square miles to acres', inputs: { value: 1, from_unit: 'mi2', to_unit: 'acre' },
      expected: { answer: '640.000 acre' },
      check: 'By hand: 2,589,988.110336 m2 / 4046.8564224 m2 = 640 exactly, matching the known fact that 1 square mile = 640 acres.' },
  ],
};