@pascal-app/editor 0.9.1 → 1.0.0-beta.1

package/src/lib/measurement-parser.ts

@@ -0,0 +1,116 @@
+import { type Kind, parseQuantity, quantity } from '@pascal-app/lingo'
+
+/**
+ * Natural-language measurement parsing for editor property fields, backed by
+ * `@pascal-app/lingo`. Lets a user type `6ft`, `180cm`, `1m80`, `5'11"`, `45°`
+ * or `1.57rad` into any measurement field and have it canonicalized to the
+ * unit the field stores its value in — independent of the metric/imperial
+ * display toggle.
+ *
+ * The editor stores linear values in meters and angular values in radians (a
+ * few fields store inches or degrees); lingo's `length` base is meters and its
+ * `angle` base is radians, so a field's `unit` prop already names the stored /
+ * canonical unit and doubles as the parse target.
+ */
+
+export interface LingoUnitSpec {
+  kind: Kind
+  /** Unit id the field's stored `value` is expressed in — the parse target. */
+  unitId: string
+}
+
+/**
+ * Map an editor field `unit` prop to a lingo kind + canonical unit. Returns
+ * `null` for units we deliberately do NOT natural-language-parse (plain
+ * numbers, percentages, angular rates, counts) so those keep exact
+ * `Number.parseFloat` behavior.
+ */
+export function lingoUnitSpec(unit: string | undefined): LingoUnitSpec | null {
+  switch (unit) {
+    case 'm':
+    case 'cm':
+    case 'mm':
+    case 'in':
+    case 'ft':
+      return { kind: 'length', unitId: unit }
+    case '°':
+    case 'deg':
+    case 'degrees':
+      return { kind: 'angle', unitId: 'deg' }
+    case 'rad':
+    case 'radians':
+      return { kind: 'angle', unitId: 'rad' }
+    default:
+      return null
+  }
+}
+
+export interface ParseMeasurementOptions {
+  /**
+   * Implied unit for a BARE number (e.g. `6` → `6 ft`). Defaults to the field's
+   * own `unitId`. A typed unit (`180cm`) is always honored regardless.
+   */
+  bareUnit?: string
+  /** Disambiguates gal/ton/cup families; harmless for length/angle. */
+  system?: 'metric' | 'us' | 'imperial'
+}
+
+/**
+ * Parse typed field text into the field's stored numeric unit. Returns `null`
+ * when the text can't be read as a quantity, so the caller can fall back to a
+ * plain number parse or revert to the previous value.
+ */
+export function parseMeasurement(
+  raw: string,
+  spec: LingoUnitSpec,
+  options: ParseMeasurementOptions = {},
+): number | null {
+  const result = parseQuantity(raw, {
+    kind: spec.kind,
+    unit: options.bareUnit ?? spec.unitId,
+    system: options.system,
+    strictness: 'forgiving',
+  })
+  if (!result.ok) return null
+  const value = result.quantity.to(spec.unitId).value
+  return Number.isFinite(value) ? value : null
+}
+
+export interface MeasurementHintOptions extends ParseMeasurementOptions {
+  /** Unit id the preview is rendered in (the field's displayed unit). */
+  displayUnit?: string
+  /** Max fraction digits in the preview. */
+  precision?: number
+  /**
+   * Clamp applied to the parsed stored value before previewing, so the hint
+   * reflects what a commit would actually store on a bounded field.
+   */
+  clamp?: (stored: number) => number
+}
+
+const PLAIN_NUMBER = /^[+-]?\d*\.?\d*$/
+
+/**
+ * A faint "= 1.83 m" preview of the value currently being typed, shown only
+ * when the user typed something beyond a plain decimal in the field's own unit
+ * (an explicit unit, a compound like `1m80`, or a number word) and it parses.
+ * Returns `null` when there's nothing useful to preview.
+ */
+export function measurementHint(
+  raw: string,
+  spec: LingoUnitSpec,
+  options: MeasurementHintOptions = {},
+): string | null {
+  const trimmed = raw.trim()
+  if (!trimmed || PLAIN_NUMBER.test(trimmed)) return null
+
+  const parsed = parseMeasurement(trimmed, spec, options)
+  if (parsed === null) return null
+  const stored = options.clamp ? options.clamp(parsed) : parsed
+
+  const displayUnit = options.displayUnit ?? spec.unitId
+  const precision = options.precision ?? 2
+  const q = quantity(stored, spec.unitId)
+  const shown = displayUnit === spec.unitId ? q : q.to(displayUnit)
+  return `= ${shown.format({ precision })}`
+}

package/src/lib/measurements.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  buildMeasurementAngleArcPoints,
+  cubicMetersToVolumeUnit,
+  formatAreaLabel,
+  formatLinearMeasurement,
+  formatVolumeLabel,
+  getAreaUnitLabel,
+  getLinearUnitLabel,
+  getVolumeUnitLabel,
+  linearControlValueToMeters,
+  linearUnitToMeters,
+  MEASUREMENT_ACTIVE_COLOR,
+  MEASUREMENT_DANGLING_COLOR,
+  MEASUREMENT_FLOORPLAN_COLOR,
+  MEASUREMENT_PERSISTENT_COLOR,
+  measurementFloorplanPresentationColor,
+  measurementPresentationColor,
+  metersToLinearUnit,
+  squareMetersToAreaUnit,
+} from './measurements'
+
+describe('measurement presentation', () => {
+  test('uses black at rest, indigo while active, and red for dangling references', () => {
+    expect(measurementPresentationColor(false, false)).toBe(MEASUREMENT_PERSISTENT_COLOR)
+    expect(measurementPresentationColor(false, true)).toBe(MEASUREMENT_ACTIVE_COLOR)
+    expect(measurementPresentationColor(true, false)).toBe(MEASUREMENT_DANGLING_COLOR)
+    expect(measurementPresentationColor(true, true)).toBe(MEASUREMENT_DANGLING_COLOR)
+  })
+
+  test('uses an indigo analysis color for resting 2D measurements', () => {
+    expect(measurementFloorplanPresentationColor(false, false)).toBe(MEASUREMENT_FLOORPLAN_COLOR)
+    expect(measurementFloorplanPresentationColor(false, true)).toBe(MEASUREMENT_ACTIVE_COLOR)
+    expect(measurementFloorplanPresentationColor(true, false)).toBe(MEASUREMENT_DANGLING_COLOR)
+  })
+})
+
+describe('angle arc presentation', () => {
+  test('samples the smaller angle from the first ray to the second', () => {
+    const arc = buildMeasurementAngleArcPoints([1, 0, 0], [0, 0, 0], [0, 0, 1], {
+      radius: 0.25,
+      sampleCount: 8,
+    })
+
+    expect(arc).toHaveLength(9)
+    expect(arc[0]?.[0]).toBeCloseTo(0.25)
+    expect(arc[0]?.[2]).toBeCloseTo(0)
+    expect(arc.at(-1)?.[0]).toBeCloseTo(0)
+    expect(arc.at(-1)?.[2]).toBeCloseTo(0.25)
+    expect(arc[4]?.[0]).toBeGreaterThan(0)
+    expect(arc[4]?.[2]).toBeGreaterThan(0)
+  })
+
+  test('keeps a constant radius on an arbitrary 3D angle plane', () => {
+    const arc = buildMeasurementAngleArcPoints([1, 0, 0], [0, 0, 0], [0, 1, 0], {
+      radius: 0.3,
+    })
+
+    expect(arc.length).toBeGreaterThan(4)
+    for (const point of arc) expect(Math.hypot(...point)).toBeCloseTo(0.3)
+    expect(arc.at(-1)?.[1]).toBeCloseTo(0.3)
+  })
+
+  test('omits an arc when either ray is degenerate', () => {
+    expect(buildMeasurementAngleArcPoints([0, 0, 0], [0, 0, 0], [1, 0, 0])).toEqual([])
+  })
+})
+
+describe('linear measurements', () => {
+  test('formats metric measurements in meters', () => {
+    expect(formatLinearMeasurement(3, 'metric')).toBe('3m')
+    expect(formatLinearMeasurement(3.456, 'metric')).toBe('3.46m')
+  })
+
+  test('formats metric measurements in whole millimeters', () => {
+    expect(formatLinearMeasurement(3.456, 'metric', 'millimeters')).toBe('3456mm')
+    expect(formatLinearMeasurement(-0.1524, 'metric', 'millimeters')).toBe('-152mm')
+  })
+
+  test('formats imperial measurements as feet and inches', () => {
+    expect(formatLinearMeasurement(3.048, 'imperial')).toBe(`10'0"`)
+    expect(formatLinearMeasurement(3.2004, 'imperial')).toBe(`10'6"`)
+  })
+
+  test('carries rounded 12 inches into the next foot', () => {
+    expect(formatLinearMeasurement(3.047, 'imperial')).toBe(`10'0"`)
+  })
+
+  test('returns a placeholder for non-finite measurements', () => {
+    expect(formatLinearMeasurement(NaN, 'imperial')).toBe('--')
+    expect(formatLinearMeasurement(Infinity, 'imperial')).toBe('--')
+    expect(formatLinearMeasurement(NaN, 'metric')).toBe('--')
+  })
+
+  test('formats zero measurements', () => {
+    expect(formatLinearMeasurement(0, 'imperial')).toBe(`0'0"`)
+    expect(formatLinearMeasurement(0, 'metric')).toBe('0m')
+  })
+
+  test('formats sub-foot imperial measurements', () => {
+    expect(formatLinearMeasurement(0.1524, 'imperial')).toBe(`0'6"`)
+  })
+
+  test('formats negative measurements with a sign', () => {
+    expect(formatLinearMeasurement(-0.1524, 'imperial')).toBe(`-0'6"`)
+    expect(formatLinearMeasurement(-0.1524, 'metric')).toBe('-0.15m')
+  })
+
+  test('converts between meters and the active linear unit', () => {
+    expect(metersToLinearUnit(0, 'imperial')).toBe(0)
+    expect(linearUnitToMeters(0, 'imperial')).toBe(0)
+
+    expect(metersToLinearUnit(1, 'metric')).toBe(1)
+    expect(linearUnitToMeters(1, 'metric')).toBe(1)
+
+    expect(metersToLinearUnit(0.3048, 'imperial')).toBeCloseTo(1)
+    expect(linearUnitToMeters(1, 'imperial')).toBeCloseTo(0.3048)
+  })
+
+  test('converts numeric control input back to meters for wall panel edits', () => {
+    expect(linearControlValueToMeters(10, 'imperial')).toBeCloseTo(3.048)
+    expect(linearControlValueToMeters(0.5, 'imperial')).toBeCloseTo(0.1524)
+    expect(linearControlValueToMeters(-1, 'imperial')).toBeCloseTo(-0.3048)
+    expect(linearControlValueToMeters(3.5, 'metric')).toBe(3.5)
+  })
+
+  test('clamps numeric control input after converting to meters', () => {
+    expect(linearControlValueToMeters(0.1, 'imperial', { minMeters: 0.1 })).toBe(0.1)
+    expect(linearControlValueToMeters(0.3, 'imperial', { minMeters: 0.1 })).toBe(0.1)
+    expect(linearControlValueToMeters(19.7, 'imperial', { maxMeters: 6 })).toBe(6)
+    expect(linearControlValueToMeters(0.2, 'metric', { minMeters: 0.1 })).toBe(0.2)
+    expect(linearControlValueToMeters(0.2, 'metric', { maxMeters: 0.15 })).toBe(0.15)
+  })
+
+  test('returns the display label for numeric controls', () => {
+    expect(getLinearUnitLabel('metric')).toBe('m')
+    expect(getLinearUnitLabel('imperial')).toBe('ft')
+  })
+})
+
+describe('area measurements', () => {
+  test('converts square meters to the active area unit', () => {
+    expect(squareMetersToAreaUnit(0, 'imperial')).toBe(0)
+    expect(squareMetersToAreaUnit(12.5, 'metric')).toBe(12.5)
+    expect(squareMetersToAreaUnit(1, 'imperial')).toBeCloseTo(10.7639)
+  })
+
+  test('returns the display label for area readouts', () => {
+    expect(getAreaUnitLabel('metric')).toBe('m²')
+    expect(getAreaUnitLabel('imperial')).toBe('ft²')
+  })
+
+  test('formats an area label with value and unit', () => {
+    expect(formatAreaLabel(12.34, 'metric')).toBe('12.3m²')
+    expect(formatAreaLabel(1, 'imperial')).toBe('10.8ft²')
+    expect(formatAreaLabel(12.34, 'metric', 2)).toBe('12.34m²')
+  })
+
+  test('returns a placeholder for non-finite areas', () => {
+    expect(formatAreaLabel(NaN, 'metric')).toBe('--')
+    expect(formatAreaLabel(Infinity, 'imperial')).toBe('--')
+  })
+})
+
+describe('volume measurements', () => {
+  test('converts cubic meters to the active volume unit', () => {
+    expect(cubicMetersToVolumeUnit(0, 'imperial')).toBe(0)
+    expect(cubicMetersToVolumeUnit(12.5, 'metric')).toBe(12.5)
+    expect(cubicMetersToVolumeUnit(1, 'imperial')).toBeCloseTo(35.3147)
+  })
+
+  test('returns the display label for volume readouts', () => {
+    expect(getVolumeUnitLabel('metric')).toBe('m³')
+    expect(getVolumeUnitLabel('imperial')).toBe('ft³')
+  })
+
+  test('formats a volume label with value and unit', () => {
+    expect(formatVolumeLabel(12.34, 'metric')).toBe('12.3m³')
+    expect(formatVolumeLabel(1, 'imperial')).toBe('35.3ft³')
+    expect(formatVolumeLabel(12.34, 'metric', 2)).toBe('12.34m³')
+  })
+
+  test('returns a placeholder for non-finite volumes', () => {
+    expect(formatVolumeLabel(NaN, 'metric')).toBe('--')
+    expect(formatVolumeLabel(Infinity, 'imperial')).toBe('--')
+    expect(formatVolumeLabel(Number.NEGATIVE_INFINITY, 'metric')).toBe('--')
+  })
+})

package/src/lib/measurements.ts

@@ -0,0 +1,210 @@
+import type { MeasurementPoint } from '@pascal-app/core'
+
+export type LinearUnit = 'metric' | 'imperial'
+export type MetricNotation = 'meters' | 'millimeters'
+
+export const MEASUREMENT_ACTIVE_COLOR = '#6366f1'
+export const MEASUREMENT_DANGLING_COLOR = '#dc2626'
+export const MEASUREMENT_FLOORPLAN_COLOR = '#4f46e5'
+export const MEASUREMENT_PERSISTENT_COLOR = '#111827'
+
+export function measurementPresentationColor(dangling: boolean, active: boolean): string {
+  if (dangling) return MEASUREMENT_DANGLING_COLOR
+  return active ? MEASUREMENT_ACTIVE_COLOR : MEASUREMENT_PERSISTENT_COLOR
+}
+
+export function measurementFloorplanPresentationColor(dangling: boolean, active: boolean): string {
+  if (dangling) return MEASUREMENT_DANGLING_COLOR
+  return active ? MEASUREMENT_ACTIVE_COLOR : MEASUREMENT_FLOORPLAN_COLOR
+}
+
+type MeasurementAngleArcOptions = {
+  radius?: number
+  sampleCount?: number
+}
+
+const ANGLE_ARC_EPSILON = 1e-9
+
+const subtractPoint = (point: MeasurementPoint, origin: MeasurementPoint): MeasurementPoint => [
+  point[0] - origin[0],
+  point[1] - origin[1],
+  point[2] - origin[2],
+]
+
+const pointLength = (point: MeasurementPoint): number => Math.hypot(...point)
+
+const scalePoint = (point: MeasurementPoint, scale: number): MeasurementPoint => [
+  point[0] * scale,
+  point[1] * scale,
+  point[2] * scale,
+]
+
+const crossPoint = (first: MeasurementPoint, second: MeasurementPoint): MeasurementPoint => [
+  first[1] * second[2] - first[2] * second[1],
+  first[2] * second[0] - first[0] * second[2],
+  first[0] * second[1] - first[1] * second[0],
+]
+
+const dotPoint = (first: MeasurementPoint, second: MeasurementPoint): number =>
+  first[0] * second[0] + first[1] * second[1] + first[2] * second[2]
+
+export function buildMeasurementAngleArcPoints(
+  start: MeasurementPoint,
+  vertex: MeasurementPoint,
+  end: MeasurementPoint,
+  options: MeasurementAngleArcOptions = {},
+): MeasurementPoint[] {
+  if (![...start, ...vertex, ...end].every(Number.isFinite)) return []
+
+  const startVector = subtractPoint(start, vertex)
+  const endVector = subtractPoint(end, vertex)
+  const startLength = pointLength(startVector)
+  const endLength = pointLength(endVector)
+  if (startLength <= ANGLE_ARC_EPSILON || endLength <= ANGLE_ARC_EPSILON) return []
+
+  const startDirection = scalePoint(startVector, 1 / startLength)
+  const endDirection = scalePoint(endVector, 1 / endLength)
+  const cosine = Math.max(-1, Math.min(1, dotPoint(startDirection, endDirection)))
+  const angle = Math.acos(cosine)
+  if (angle <= 1e-4) return []
+
+  let normal = crossPoint(startDirection, endDirection)
+  let normalLength = pointLength(normal)
+  if (normalLength <= ANGLE_ARC_EPSILON) {
+    const reference: MeasurementPoint = Math.abs(startDirection[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0]
+    normal = crossPoint(startDirection, reference)
+    normalLength = pointLength(normal)
+  }
+  if (normalLength <= ANGLE_ARC_EPSILON) return []
+  normal = scalePoint(normal, 1 / normalLength)
+  const tangent = crossPoint(normal, startDirection)
+
+  const shortestSide = Math.min(startLength, endLength)
+  const preferredRadius = options.radius ?? Math.min(Math.max(shortestSide * 0.28, 0.08), 0.75)
+  const radius = Math.min(Math.max(preferredRadius, 0), shortestSide * 0.45)
+  if (radius <= ANGLE_ARC_EPSILON) return []
+
+  const sampleCount = Math.min(
+    64,
+    Math.max(4, Math.round(options.sampleCount ?? Math.max(8, (angle / Math.PI) * 32))),
+  )
+  return Array.from({ length: sampleCount + 1 }, (_, index) => {
+    const sampleAngle = angle * (index / sampleCount)
+    const direction: MeasurementPoint = [
+      startDirection[0] * Math.cos(sampleAngle) + tangent[0] * Math.sin(sampleAngle),
+      startDirection[1] * Math.cos(sampleAngle) + tangent[1] * Math.sin(sampleAngle),
+      startDirection[2] * Math.cos(sampleAngle) + tangent[2] * Math.sin(sampleAngle),
+    ]
+    return [
+      vertex[0] + direction[0] * radius,
+      vertex[1] + direction[1] * radius,
+      vertex[2] + direction[2] * radius,
+    ]
+  })
+}
+
+const METERS_PER_FOOT = 0.3048
+const FEET_PER_METER = 1 / METERS_PER_FOOT
+
+type LinearControlValueOptions = {
+  minMeters?: number
+  maxMeters?: number
+}
+
+export function metersToLinearUnit(meters: number, unit: LinearUnit): number {
+  return unit === 'imperial' ? meters * FEET_PER_METER : meters
+}
+
+export function linearUnitToMeters(value: number, unit: LinearUnit): number {
+  return unit === 'imperial' ? value * METERS_PER_FOOT : value
+}
+
+export function linearControlValueToMeters(
+  value: number,
+  unit: LinearUnit,
+  options: LinearControlValueOptions = {},
+): number {
+  const meters = linearUnitToMeters(value, unit)
+  const minMeters = options.minMeters ?? Number.NEGATIVE_INFINITY
+  const maxMeters = options.maxMeters ?? Number.POSITIVE_INFINITY
+
+  return Math.min(Math.max(meters, minMeters), maxMeters)
+}
+
+export function getLinearUnitLabel(unit: LinearUnit): string {
+  return unit === 'imperial' ? 'ft' : 'm'
+}
+
+const SQUARE_FEET_PER_SQUARE_METER = FEET_PER_METER * FEET_PER_METER
+const CUBIC_FEET_PER_CUBIC_METER = SQUARE_FEET_PER_SQUARE_METER * FEET_PER_METER
+
+export function squareMetersToAreaUnit(squareMeters: number, unit: LinearUnit): number {
+  return unit === 'imperial' ? squareMeters * SQUARE_FEET_PER_SQUARE_METER : squareMeters
+}
+
+export function getAreaUnitLabel(unit: LinearUnit): string {
+  return unit === 'imperial' ? 'ft²' : 'm²'
+}
+
+export function formatAreaLabel(
+  squareMeters: number,
+  unit: LinearUnit,
+  fractionDigits = 1,
+): string {
+  if (!Number.isFinite(squareMeters)) return '--'
+
+  return `${squareMetersToAreaUnit(squareMeters, unit).toFixed(fractionDigits)}${getAreaUnitLabel(unit)}`
+}
+
+export function cubicMetersToVolumeUnit(cubicMeters: number, unit: LinearUnit): number {
+  return unit === 'imperial' ? cubicMeters * CUBIC_FEET_PER_CUBIC_METER : cubicMeters
+}
+
+export function getVolumeUnitLabel(unit: LinearUnit): string {
+  return unit === 'imperial' ? 'ft³' : 'm³'
+}
+
+export function formatVolumeLabel(
+  cubicMeters: number,
+  unit: LinearUnit,
+  fractionDigits = 1,
+): string {
+  if (!Number.isFinite(cubicMeters)) return '--'
+
+  return `${cubicMetersToVolumeUnit(cubicMeters, unit).toFixed(fractionDigits)}${getVolumeUnitLabel(unit)}`
+}
+
+export function formatLinearMeasurement(
+  meters: number,
+  unit: LinearUnit,
+  metricNotation: MetricNotation = 'meters',
+): string {
+  if (!Number.isFinite(meters)) return '--'
+
+  const absoluteMeters = Math.abs(meters)
+
+  if (unit === 'imperial') {
+    const feet = metersToLinearUnit(absoluteMeters, unit)
+    let wholeFeet = Math.floor(feet)
+    let inches = Math.round((feet - wholeFeet) * 12)
+    if (inches === 12) {
+      wholeFeet += 1
+      inches = 0
+    }
+
+    const sign = meters < 0 && (wholeFeet !== 0 || inches !== 0) ? '-' : ''
+
+    return `${sign}${wholeFeet}'${inches}"`
+  }
+
+  if (metricNotation === 'millimeters') {
+    const roundedMillimeters = Math.round(absoluteMeters * 1000)
+    const sign = meters < 0 && roundedMillimeters !== 0 ? '-' : ''
+    return `${sign}${roundedMillimeters}mm`
+  }
+
+  const roundedMeters = Number.parseFloat(absoluteMeters.toFixed(2))
+  const sign = meters < 0 && roundedMeters !== 0 ? '-' : ''
+
+  return `${sign}${roundedMeters}m`
+}