fix(nearest-point-on-line): segmentIndex always returns i, add segment helper functions

[feliperm17]

Closes #3023
Design discussion: #3022

Summary

segmentIndex now always equals the index i of the segment on which the nearest point was found. The legacy "favour the next segment" behaviour (returning i + 1 when the nearest point lands exactly on an end vertex) has been removed entirely — for both intermediate vertices and the last vertex of a LineString. Three helper functions are added so callers can restore that behaviour when needed.

Breaking change ⚠️

Before:

nearestPointOnLine(line, point).properties.segmentIndex
// → i + 1 when nearest point is at an end vertex (intermediate segments)
// → coords.length - 1 when at the last vertex (invalid — out of bounds)

After:

nearestPointOnLine(line, point).properties.segmentIndex
// → always i (the segment where the point was found, always valid)

New helper functions

Three exported helpers allow callers to restore the previous behaviour or build their own logic (e.g. turn-by-turn navigation):

import {
  nearestPointOnLine,
  atEndOfSegment,
  atEndOfLineString,
  hasNextSegment,
} from "@turf/nearest-point-on-line";

const nearest = nearestPointOnLine(line, point);

atEndOfSegment(nearest, line);    // true if nearest point is at end vertex of its segment
atEndOfLineString(nearest, line); // true if nearest point is at the very last vertex
hasNextSegment(nearest, line);    // true if a next segment exists

// Reconstruct the old i+1 behaviour when desired:
const legacyIndex =
  nearest.properties.segmentIndex +
  (atEndOfSegment(nearest, line) && hasNextSegment(nearest, line) ? 1 : 0);

Tests

• Updated the pre-existing segmentIndex: 8 → 7 expectation (intermediate vertex case, intentional breaking change).
• Updated fixture test/out/multiLine1.geojson: segmentIndex/index 21 → 20 (the only real value change; full fixture regen was discarded as it produced 34k lines of pure formatting noise with no value changes).
• Added 7 new tests covering: last vertex, intermediate vertex, atEndOfSegment/hasNextSegment + legacy index reconstruction, atEndOfLineString, mid-segment, LineString↔MultiLineString parity via segment offsets, and helpers on bare geometry input.
• All 106 tape tests pass; test:types passes; eslint clean.

Note for maintainers

packages/turf-line-slice/index.ts:69 contains a fixSegmentIndexBounds workaround that was added explicitly to handle this bug. It is now a harmless no-op. Removing it is out of scope for this PR but worth a follow-up.

Checklist

• Meaningful title, including the name of the package being modified.
• Summary of the changes.
• Heads up that this is a breaking change.
• Resolves nearestPointOnLine returns invalid segmentIndex when result is at the end of the last segment of the lineString #3023.
• Added contributor details to contributors field of package.json.
• I have read the steps for preparing a pull request.

[feliperm17]

@smallsaucepan when you get a chance, would appreciate your review! Happy to adjust anything based on your feedback.