@jjlmoya/utils-motor 1.3.0 → 1.4.0

package/src/tool/motorcycleSkidMarkSpeedEstimator/logic.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, it } from 'vitest';
+import {
+  clamp,
+  dragFactor,
+  estimateSkidSpeed,
+  getSurfaceSpec,
+  gradeTilt,
+  isBrakeUse,
+  isSurfaceId,
+  isUnitSystem,
+  lengthToMeters,
+  markRatio,
+  metersToLength,
+  METERS_PER_FOOT,
+  parsePositiveNumber,
+  parseSignedNumber,
+  speedFromMps,
+  speedFromSkid,
+  SURFACE_SPECS,
+} from './logic';
+import { evaluateSkid } from './evaluator';
+import { buildSceneView, formatGrade, formatLength, formatRange, formatSpeed, gradeCaption, lengthUnit, speedUnit } from './dom-views';
+import type { MotorcycleSkidMarkSpeedEstimatorUI } from './ui';
+import { loadSkidState, saveSkidState } from './storage';
+
+describe('motorcycle skid mark speed logic', () => {
+  it('converts length and speed units without changing the physical value', () => {
+    expect(lengthToMeters(40, 'imperial')).toBeCloseTo(40 * METERS_PER_FOOT, 8);
+    expect(metersToLength(12.192, 'imperial')).toBeCloseTo(40, 4);
+    expect(lengthToMeters(18, 'metric')).toBe(18);
+    expect(metersToLength(18, 'metric')).toBe(18);
+    expect(speedFromMps(13.7426, 'imperial')).toBeCloseTo(30.74, 1);
+    expect(speedFromMps(13.7426, 'metric')).toBeCloseTo(49.47, 1);
+    expect(lengthToMeters(Number.NaN, 'metric')).toBe(0);
+    expect(metersToLength(Number.NaN, 'imperial')).toBe(0);
+    expect(speedFromMps(Number.NaN, 'metric')).toBe(0);
+  });
+
+  it('matches the locked-wheel energy example of 40 ft at 0.79 drag', () => {
+    const meters = lengthToMeters(40, 'imperial');
+    const speed = speedFromSkid(meters, 0.79);
+    expect(speed).not.toBeNull();
+    expect(speedFromMps(speed ?? 0, 'imperial')).toBeCloseTo(30.75, 1);
+  });
+
+  it('adds grade to drag uphill and subtracts it downhill', () => {
+    expect(dragFactor(0.7, 1, 10)).toBeCloseTo(0.8, 8);
+    expect(dragFactor(0.7, 1, -10)).toBeCloseTo(0.6, 8);
+    const up = estimateSkidSpeed({
+      lengthMeters: 20,
+      friction: 0.7,
+      gradePercent: 10,
+      surface: 'custom',
+      brakeUse: 'both',
+    });
+    const down = estimateSkidSpeed({
+      lengthMeters: 20,
+      friction: 0.7,
+      gradePercent: -10,
+      surface: 'custom',
+      brakeUse: 'both',
+    });
+    expect(up.band?.midMps).toBeGreaterThan(down.band?.midMps ?? 0);
+  });
+
+  it('rejects a downhill case where gravity exceeds available drag', () => {
+    const result = estimateSkidSpeed({
+      lengthMeters: 20,
+      friction: 0.05,
+      gradePercent: -20,
+      surface: 'custom',
+      brakeUse: 'rear',
+    });
+    expect(result.status).toBe('invalid');
+    expect(result.band).toBeNull();
+    expect(speedFromSkid(0, 0.7)).toBeNull();
+    expect(speedFromSkid(10, 0)).toBeNull();
+  });
+
+  it('widens the band when brake use is unknown', () => {
+    const known = estimateSkidSpeed({
+      lengthMeters: 18,
+      friction: 0.7,
+      gradePercent: 0,
+      surface: 'dry-asphalt',
+      brakeUse: 'both',
+    });
+    const unknown = estimateSkidSpeed({
+      lengthMeters: 18,
+      friction: 0.7,
+      gradePercent: 0,
+      surface: 'dry-asphalt',
+      brakeUse: 'unknown',
+    });
+    expect(known.status).toBe('ready');
+    expect(unknown.status).toBe('ready');
+    expect(unknown.band?.lowMps).toBeLessThan(known.band?.lowMps ?? 0);
+    expect(unknown.band?.highMps).toBeGreaterThanOrEqual(known.band?.highMps ?? 0);
+  });
+
+  it('uses surface ranges and a custom plus-minus friction span', () => {
+    const asphalt = estimateSkidSpeed({
+      lengthMeters: 18,
+      friction: 0.7,
+      gradePercent: 0,
+      surface: 'dry-asphalt',
+      brakeUse: 'both',
+    });
+    const custom = estimateSkidSpeed({
+      lengthMeters: 18,
+      friction: 0.7,
+      gradePercent: 0,
+      surface: 'custom',
+      brakeUse: 'both',
+    });
+    expect(asphalt.band?.lowMps).not.toBe(asphalt.band?.highMps);
+    expect(custom.band?.dragLow).toBeCloseTo(0.6, 8);
+    expect(custom.band?.dragHigh).toBeCloseTo(0.8, 8);
+    expect(getSurfaceSpec('wet-asphalt').mu).toBe(0.5);
+    expect(getSurfaceSpec('missing' as never).id).toBe('dry-asphalt');
+  });
+
+  it('parses inputs, clamps scene helpers, and validates enumerations', () => {
+    expect(parsePositiveNumber('18')).toBe(18);
+    expect(parsePositiveNumber('0')).toBeNull();
+    expect(parsePositiveNumber('x')).toBeNull();
+    expect(parseSignedNumber('-4')).toBe(-4);
+    expect(parseSignedNumber('nope')).toBeNull();
+    expect(clamp(9, 0, 5)).toBe(5);
+    expect(markRatio(1)).toBeCloseTo(0.28, 2);
+    expect(markRatio(18)).toBeGreaterThan(0.55);
+    expect(markRatio(200)).toBeCloseTo(0.92, 2);
+    expect(gradeTilt(20)).toBeCloseTo(11, 4);
+    expect(isUnitSystem('metric')).toBe(true);
+    expect(isUnitSystem('stone')).toBe(false);
+    expect(isBrakeUse('rear')).toBe(true);
+    expect(isBrakeUse('abs')).toBe(false);
+    expect(isSurfaceId('ice')).toBe(true);
+    expect(isSurfaceId('sand')).toBe(false);
+    expect(SURFACE_SPECS).toHaveLength(7);
+  });
+
+  it('applies front and rear efficiency below a full locked-wheel both-brake case', () => {
+    const both = estimateSkidSpeed({
+      lengthMeters: 25,
+      friction: 0.7,
+      gradePercent: 0,
+      surface: 'custom',
+      brakeUse: 'both',
+    });
+    const front = estimateSkidSpeed({
+      lengthMeters: 25,
+      friction: 0.7,
+      gradePercent: 0,
+      surface: 'custom',
+      brakeUse: 'front',
+    });
+    const rear = estimateSkidSpeed({
+      lengthMeters: 25,
+      friction: 0.7,
+      gradePercent: 0,
+      surface: 'custom',
+      brakeUse: 'rear',
+    });
+    expect(front.band?.midMps).toBeLessThan(both.band?.midMps ?? 0);
+    expect(rear.band?.midMps).toBeLessThan(front.band?.midMps ?? 0);
+  });
+
+  it('evaluates status and formats the road stencil', () => {
+    const readyInput = {
+      lengthMeters: 18,
+      friction: 0.7,
+      gradePercent: 0,
+      surface: 'dry-asphalt' as const,
+      brakeUse: 'both' as const,
+    };
+    const invalidInput = {
+      lengthMeters: 18,
+      friction: 0.05,
+      gradePercent: -20,
+      surface: 'custom' as const,
+      brakeUse: 'rear' as const,
+    };
+    const ui = {
+      invalidMessage: 'bad',
+      educationalBadge: 'edu',
+      rangeLabel: 'band',
+      readyMessage: 'ok',
+      stencilUnitKmh: 'km/h',
+      stencilUnitMph: 'mph',
+      lengthUnitM: 'm',
+      lengthUnitFt: 'ft',
+      gradeUphill: 'up',
+      gradeDownhill: 'down',
+      gradeLevel: 'flat',
+      lowAssumption: 'L',
+      highAssumption: 'H',
+      dragMidLabel: 'M',
+    } as MotorcycleSkidMarkSpeedEstimatorUI;
+    expect(evaluateSkid(readyInput)).toBe('ready');
+    expect(evaluateSkid(invalidInput)).toBe('invalid');
+    expect(formatSpeed(40, 'metric')).toBe('144');
+    expect(formatSpeed(10, 'metric')).toBe('36.0');
+    expect(formatLength(18, 'metric')).toBe('18.0');
+    expect(formatLength(12.192, 'imperial')).toBe('40.0');
+    expect(formatGrade(0)).toBe('0');
+    expect(formatGrade(-4)).toBe('-4');
+    expect(formatRange(10, 12, 'metric')).toContain('to');
+    expect(speedUnit(ui, 'imperial')).toBe('mph');
+    expect(lengthUnit(ui, 'metric')).toBe('m');
+    expect(gradeCaption(2, ui)).toBe('up');
+    expect(gradeCaption(-2, ui)).toBe('down');
+    expect(gradeCaption(0, ui)).toBe('flat');
+    const readyView = buildSceneView(readyInput, estimateSkidSpeed(readyInput), 'metric', ui);
+    const invalidView = buildSceneView(invalidInput, estimateSkidSpeed(invalidInput), 'metric', ui);
+    expect(readyView.rangeText).toContain('to');
+    expect(invalidView.speedText).toBe('bad');
+    expect(loadSkidState()).toBeNull();
+    saveSkidState({
+      lengthMeters: 18,
+      unit: 'metric',
+      surface: 'dry-asphalt',
+      friction: 0.7,
+      gradePercent: 0,
+      brakeUse: 'both',
+    });
+  });
+});
+

package/src/tool/motorcycleSkidMarkSpeedEstimator/logic.ts

@@ -0,0 +1,179 @@
+export const GRAVITY = 9.80665;
+export const METERS_PER_FOOT = 0.3048;
+export const MPS_TO_KMH = 3.6;
+export const MPS_TO_MPH = 2.236936292;
+export const MIN_FRICTION = 0.05;
+export const MAX_FRICTION = 1.2;
+export const MIN_LENGTH_M = 1;
+export const MAX_LENGTH_M = 200;
+export const MIN_GRADE = -20;
+export const MAX_GRADE = 20;
+
+export type UnitSystem = 'metric' | 'imperial';
+export type BrakeUse = 'both' | 'front' | 'rear' | 'unknown';
+export type SurfaceId =
+  | 'dry-asphalt'
+  | 'wet-asphalt'
+  | 'dry-concrete'
+  | 'gravel'
+  | 'grass'
+  | 'ice'
+  | 'custom';
+
+export interface SurfaceSpec {
+  id: SurfaceId;
+  mu: number;
+  muLow: number;
+  muHigh: number;
+}
+
+export interface SkidInput {
+  lengthMeters: number;
+  friction: number;
+  gradePercent: number;
+  surface: SurfaceId;
+  brakeUse: BrakeUse;
+}
+
+export interface SpeedBand {
+  lowMps: number;
+  midMps: number;
+  highMps: number;
+  dragLow: number;
+  dragMid: number;
+  dragHigh: number;
+}
+
+export interface SkidEstimate {
+  status: 'ready' | 'invalid';
+  band: SpeedBand | null;
+  friction: number;
+  lengthMeters: number;
+}
+
+export const SURFACE_SPECS: readonly SurfaceSpec[] = [
+  { id: 'dry-asphalt', mu: 0.7, muLow: 0.55, muHigh: 0.85 },
+  { id: 'wet-asphalt', mu: 0.5, muLow: 0.35, muHigh: 0.65 },
+  { id: 'dry-concrete', mu: 0.75, muLow: 0.6, muHigh: 0.9 },
+  { id: 'gravel', mu: 0.5, muLow: 0.35, muHigh: 0.7 },
+  { id: 'grass', mu: 0.4, muLow: 0.25, muHigh: 0.55 },
+  { id: 'ice', mu: 0.1, muLow: 0.05, muHigh: 0.18 },
+  { id: 'custom', mu: 0.7, muLow: 0.6, muHigh: 0.8 },
+];
+
+const BRAKE_SPAN: Record<BrakeUse, { low: number; mid: number; high: number }> = {
+  both: { low: 1, mid: 1, high: 1 },
+  front: { low: 0.7, mid: 0.7, high: 0.7 },
+  rear: { low: 0.45, mid: 0.45, high: 0.45 },
+  unknown: { low: 0.45, mid: 0.7, high: 1 },
+};
+
+export function isUnitSystem(value: string): value is UnitSystem {
+  return value === 'metric' || value === 'imperial';
+}
+
+export function isBrakeUse(value: string): value is BrakeUse {
+  return value === 'both' || value === 'front' || value === 'rear' || value === 'unknown';
+}
+
+export function isSurfaceId(value: string): value is SurfaceId {
+  return SURFACE_SPECS.some((spec) => spec.id === value);
+}
+
+const DEFAULT_SURFACE: SurfaceSpec = { id: 'dry-asphalt', mu: 0.7, muLow: 0.55, muHigh: 0.85 };
+
+export function getSurfaceSpec(id: SurfaceId): SurfaceSpec {
+  return SURFACE_SPECS.find((spec) => spec.id === id) ?? DEFAULT_SURFACE;
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function lengthToMeters(length: number, unit: UnitSystem): number {
+  const safe = Number.isFinite(length) ? Math.max(0, length) : 0;
+  return unit === 'imperial' ? safe * METERS_PER_FOOT : safe;
+}
+
+export function metersToLength(meters: number, unit: UnitSystem): number {
+  const safe = Number.isFinite(meters) ? Math.max(0, meters) : 0;
+  return unit === 'imperial' ? safe / METERS_PER_FOOT : safe;
+}
+
+export function speedFromMps(mps: number, unit: UnitSystem): number {
+  const safe = Number.isFinite(mps) ? Math.max(0, mps) : 0;
+  return unit === 'imperial' ? safe * MPS_TO_MPH : safe * MPS_TO_KMH;
+}
+
+export function parsePositiveNumber(raw: string): number | null {
+  const value = Number.parseFloat(raw);
+  if (!Number.isFinite(value) || value <= 0) return null;
+  return value;
+}
+
+export function parseSignedNumber(raw: string): number | null {
+  const value = Number.parseFloat(raw);
+  if (!Number.isFinite(value)) return null;
+  return value;
+}
+
+export function dragFactor(friction: number, efficiency: number, gradePercent: number): number {
+  const mu = clamp(friction, MIN_FRICTION, MAX_FRICTION);
+  const n = clamp(efficiency, 0, 1);
+  const grade = clamp(gradePercent, MIN_GRADE, MAX_GRADE) / 100;
+  return mu * n + grade;
+}
+
+export function speedFromSkid(lengthMeters: number, drag: number): number | null {
+  if (!(lengthMeters > 0) || !(drag > 0)) return null;
+  return Math.sqrt(2 * GRAVITY * drag * lengthMeters);
+}
+
+function customSensitivity(friction: number): { low: number; high: number } {
+  return {
+    low: clamp(friction - 0.1, MIN_FRICTION, MAX_FRICTION),
+    high: clamp(friction + 0.1, MIN_FRICTION, MAX_FRICTION),
+  };
+}
+
+function frictionBand(input: SkidInput): { low: number; mid: number; high: number } {
+  const spec = getSurfaceSpec(input.surface);
+  if (input.surface === 'custom') {
+    const span = customSensitivity(input.friction);
+    return { low: span.low, mid: clamp(input.friction, MIN_FRICTION, MAX_FRICTION), high: span.high };
+  }
+  return { low: spec.muLow, mid: spec.mu, high: spec.muHigh };
+}
+
+function buildBand(input: SkidInput): SpeedBand | null {
+  const brakes = BRAKE_SPAN[input.brakeUse];
+  const mu = frictionBand(input);
+  const dragLow = dragFactor(mu.low, brakes.low, input.gradePercent);
+  const dragMid = dragFactor(mu.mid, brakes.mid, input.gradePercent);
+  const dragHigh = dragFactor(mu.high, brakes.high, input.gradePercent);
+  const low = speedFromSkid(input.lengthMeters, dragLow);
+  const mid = speedFromSkid(input.lengthMeters, dragMid);
+  const high = speedFromSkid(input.lengthMeters, dragHigh);
+  if (low === null || mid === null || high === null) return null;
+  return { lowMps: low, midMps: mid, highMps: high, dragLow, dragMid, dragHigh };
+}
+
+export function estimateSkidSpeed(input: SkidInput): SkidEstimate {
+  const lengthMeters = clamp(input.lengthMeters, MIN_LENGTH_M, MAX_LENGTH_M);
+  const friction = clamp(input.friction, MIN_FRICTION, MAX_FRICTION);
+  const band = buildBand({ ...input, lengthMeters, friction });
+  if (!band) {
+    return { status: 'invalid', band: null, friction, lengthMeters };
+  }
+  return { status: 'ready', band, friction, lengthMeters };
+}
+
+export function markRatio(lengthMeters: number): number {
+  const clamped = clamp(lengthMeters, MIN_LENGTH_M, MAX_LENGTH_M);
+  const t = Math.log(clamped) / Math.log(MAX_LENGTH_M);
+  return 0.28 + t * 0.64;
+}
+
+export function gradeTilt(gradePercent: number): number {
+  return clamp(gradePercent, MIN_GRADE, MAX_GRADE) * 0.55;
+}