From b210ccc5b8d5cad05688f14e1e81e29c27d75592 Mon Sep 17 00:00:00 2001
From: Agent Zero <agent@media-on.de>
Date: Sat, 29 Aug 2026 03:09:35 +0200
Subject: [PATCH] task(H5): polygon area calculation - shoelace polygonArea,
 formatArea with quadratic scaling, measure-area tool, properties panel area
 display

---
 frontend/src/components/PropertiesPanel.tsx   |  10 +-
 .../src/plugins/builtin/core-measure/index.ts |  69 ++++++++-
 frontend/src/tools/modification/geometry.ts   |  16 ++
 frontend/src/utils/format.ts                  |  25 ++++
 frontend/tests/measureArea.test.ts            | 137 ++++++++++++++++++
 5 files changed, 254 insertions(+), 3 deletions(-)
 create mode 100644 frontend/tests/measureArea.test.ts

diff --git a/frontend/src/components/PropertiesPanel.tsx b/frontend/src/components/PropertiesPanel.tsx
index 1c973f5..ee14b9e 100644
--- a/frontend/src/components/PropertiesPanel.tsx
+++ b/frontend/src/components/PropertiesPanel.tsx
@@ -1,4 +1,6 @@
 import React, { useState, useEffect } from 'react';
+import { polygonArea } from '../tools/modification/geometry';
+import { formatArea } from '../utils/format';
 import type { PropertiesPanelProps } from '../types/ui.types';
 import { formatInputValue, parseDistance, type UnitType } from '../utils/format';
 
@@ -69,7 +71,13 @@ const PropertiesPanel: React.FC<PropertiesPanelProps> = ({
     <>
       <div className="panel-section">
         <div className="panel-section-title">
-          <span>Auswahl {el ? `· ${el.type}` : ''}</span>
+          <span>Auswahl {el ? `· ${el.type}
+        {((el.type === 'polygon' || el.type === 'polyline') && ((el.properties.points as Array<{ x: number; y: number }> | undefined)?.length ?? 0) >= 3) && (
+          <div className="prop-row">
+            <label className="prop-label">Fläche</label>
+            <span className="prop-value">{formatArea(polygonArea(el.properties.points as Array<{ x: number; y: number }>), unit, scaleFactor)}</span>
+          </div>
+        )}` : ''}</span>
           <div style={{ display: 'flex', gap: '4px' }}>
             {onDelete && el && (
               <button
diff --git a/frontend/src/plugins/builtin/core-measure/index.ts b/frontend/src/plugins/builtin/core-measure/index.ts
index 8d50e85..ece51d4 100644
--- a/frontend/src/plugins/builtin/core-measure/index.ts
+++ b/frontend/src/plugins/builtin/core-measure/index.ts
@@ -6,7 +6,8 @@
  * Distanzformatierung via bestehendem formatDistance(unit, scaleFactor).
  */
 import type { PluginV2, ToolExtensionV2, FullToolContext } from '../../types';
-import { formatDistance } from '../../../utils/format';
+import { formatDistance, formatArea } from '../../../utils/format';
+import { polygonArea } from '../../../tools/modification/geometry';
 
 type MeasurePhase = 0 | 1; // 0=wartet auf Start, 1=wartet auf Ende
 let measureStart: import('../../../tools/modification/geometry').Pt | null = null;
@@ -46,6 +47,70 @@ export const measureTool: ToolExtensionV2 = {
 };
 
 /** V2-Plugin: Messwerkzeuge. */
+// ─────────────────────────────────────────────────────────────
+// Task H5: measure-area — Polygon-Fläche messen (Status-only).
+// Klick: Punkt hinzufügen; ENTER: committet Fläche ab 3 Punkten;
+// ESC/Rechtsklick: Abbruch. Kein Element-Commit (wie measure).
+// ─────────────────────────────────────────────────────────────
+let areaPts: Array<{ x: number; y: number }> = [];
+
+export const measureAreaTool: ToolExtensionV2 = {
+  manifest: {
+    id: 'measure-area',
+    label: 'Fläche messen',
+    icon: '\u25a9',
+    ribbonTab: 'canvas',
+    tags: ['basic'],
+    description: 'Polygon-Fläche messen: Punkte klicken, ENTER schließt ab',
+  },
+  optionsSchema: [
+    { key: 'unit', label: 'Einheit', type: 'select', options: [
+      { value: 'mm', label: 'mm' }, { value: 'cm', label: 'cm' }, { value: 'm', label: 'm' },
+    ] },
+    { key: 'scaleFactor', label: 'Maßstab (Welt→mm)', type: 'number' },
+  ],
+  handlers: {
+    down(e, ctx) {
+      areaPts.push({ x: e.world.x, y: e.world.y });
+      if (areaPts.length === 1) {
+        ctx.setStatus(`Flächenmessung gestartet (1 Punkt) — weitere Punkte klicken, ENTER schließt ab`);
+      } else if (areaPts.length >= 3) {
+        const unit = (ctx.options.unit as string | undefined) ?? 'mm';
+        const scale = (ctx.options.scaleFactor as number | undefined) ?? 1;
+        ctx.setStatus(`Fläche: ${formatArea(polygonArea(areaPts), unit as never, scale)} — weiter klicken oder ENTER`);
+      } else {
+        ctx.setStatus(`${areaPts.length} Punkte — mindestens 3 benötigt, weitere Punkte klicken`);
+      }
+    },
+    move(e, ctx) {
+      if (areaPts.length < 2) return;
+      const probe = [...areaPts, { x: e.world.x, y: e.world.y }];
+      if (probe.length < 3) return;
+      const unit = (ctx.options.unit as string | undefined) ?? 'mm';
+      const scale = (ctx.options.scaleFactor as number | undefined) ?? 1;
+      ctx.setStatus(`Fläche: ${formatArea(polygonArea(probe), unit as never, scale)}`);
+    },
+    key(k, ctx) {
+      if (k.key === 'Enter' || k.key === 'ENTER') {
+        if (areaPts.length >= 3) {
+          const unit = (ctx.options.unit as string | undefined) ?? 'mm';
+          const scale = (ctx.options.scaleFactor as number | undefined) ?? 1;
+          ctx.setStatus(`Flächenmessung: ${formatArea(polygonArea(areaPts), unit as never, scale)} (${areaPts.length} Punkte)`);
+          areaPts = [];
+        } else {
+          ctx.setStatus(`Flächenmessung benötigt mindestens 3 Punkte (aktuell ${areaPts.length})`);
+        }
+        return true; // ENTER konsumiert
+      }
+      return false;
+    },
+    cancel(ctx) {
+      areaPts = [];
+      ctx.setStatus('Flächenmessung abgebrochen');
+    },
+  },
+};
+
 export const coreMeasurePlugin: PluginV2 = {
   manifest: {
     id: 'core-measure',
@@ -56,5 +121,5 @@ export const coreMeasurePlugin: PluginV2 = {
     category: 'tools',
     enabledByDefault: true,
   },
-  tools: [measureTool],
+  tools: [measureTool, measureAreaTool],
 };
diff --git a/frontend/src/tools/modification/geometry.ts b/frontend/src/tools/modification/geometry.ts
index dc44d05..33bf3bf 100644
--- a/frontend/src/tools/modification/geometry.ts
+++ b/frontend/src/tools/modification/geometry.ts
@@ -588,3 +588,19 @@ export function distance(p1: { x: number; y: number }, p2: { x: number; y: numbe
 export function angleBetween(p1: { x: number; y: number }, p2: { x: number; y: number }): number {
   return (Math.atan2(p2.y - p1.y, p2.x - p1.x) * 180) / Math.PI;
 }
+
+/**
+ * Fläche eines Polygons via Shoelace-Formel (Task H5).
+ * Absolutwert — Uhrzeigersinn und gegen Uhrzeigersinn ergeben dasselbe.
+ * Weniger als 3 Punkte oder kollineare Punkte → 0.
+ */
+export function polygonArea(pts: Array<{ x: number; y: number }>): number {
+  if (!Array.isArray(pts) || pts.length < 3) return 0;
+  let sum = 0;
+  for (let i = 0; i < pts.length; i++) {
+    const a = pts[i];
+    const b = pts[(i + 1) % pts.length];
+    sum += a.x * b.y - b.x * a.y;
+  }
+  return Math.abs(sum / 2);
+}
diff --git a/frontend/src/utils/format.ts b/frontend/src/utils/format.ts
index c9d460a..666be24 100644
--- a/frontend/src/utils/format.ts
+++ b/frontend/src/utils/format.ts
@@ -92,3 +92,28 @@ export function formatInputValue(
       return `${(mm / 1000).toFixed(3)}`;
   }
 }
+
+/**
+ * Format a raw world-unit squared area value (Task H5).
+ * @param rawSquared squared world-units (e.g. polygonArea result)
+ * @param unit target display unit
+ * @param scaleFactor world-units → mm conversion (like formatDistance)
+ * @returns formatted string like "5000 mm²", "50.0 cm²", "5.00 m²"
+ */
+export function formatArea(
+  rawSquared: number,
+  unit: UnitType,
+  scaleFactor: number = 1,
+): string {
+  const mmSquared = rawSquared * scaleFactor * scaleFactor;
+  switch (unit) {
+    case 'mm':
+      return `${mmSquared.toFixed(0)} mm²`;
+    case 'cm':
+      return `${(mmSquared / 100).toFixed(1)} cm²`;
+    case 'm':
+      return `${(mmSquared / 1000000).toFixed(2)} m²`;
+    default:
+      return `${mmSquared.toFixed(0)} mm²`;
+  }
+}
diff --git a/frontend/tests/measureArea.test.ts b/frontend/tests/measureArea.test.ts
new file mode 100644
index 0000000..05a86f4
--- /dev/null
+++ b/frontend/tests/measureArea.test.ts
@@ -0,0 +1,137 @@
+/**
+ * Task H5 – Flächenberechnung Polygon (m²) + measure-area Tool.
+ *
+ * polygonArea: Shoelace-Formel (Absolutwert, CW/CCW egal),
+ * formatArea: Einheiten-Formatierung analog formatDistance,
+ * measureAreaTool: Klick-Sequenz, Live-Fläche im Status, ENTER
+ * committet ab 3 Punkten, cancel setzt zurück.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { polygonArea } from '../src/tools/modification/geometry';
+import { formatArea } from '../src/utils/format';
+import { measureAreaTool } from '../src/plugins/builtin/core-measure';
+import type { CADElement } from '../src/types/cad.types';
+
+describe('H5: polygonArea (Shoelace)', () => {
+  it('Rechteck 100×50 = 5000 Welt-Einheiten²', () => {
+    const pts = [
+      { x: 0, y: 0 }, { x: 100, y: 0 },
+      { x: 100, y: 50 }, { x: 0, y: 50 },
+    ];
+    expect(polygonArea(pts)).toBeCloseTo(5000, 6);
+  });
+
+  it('Dreieck 100×50/2 = 2500', () => {
+    const pts = [{ x: 0, y: 0 }, { x: 100, y: 0 }, { x: 0, y: 50 }];
+    expect(polygonArea(pts)).toBeCloseTo(2500, 6);
+  });
+
+  it('Uhrzeigersinn und gegen Uhrzeigersinn ergeben denselben Absolutwert', () => {
+    const ccw = [{ x: 0, y: 0 }, { x: 100, y: 0 }, { x: 100, y: 100 }, { x: 0, y: 100 }];
+    const cw = [...ccw].reverse();
+    expect(polygonArea(cw)).toBeCloseTo(polygonArea(ccw), 6);
+    expect(polygonArea(cw)).toBeCloseTo(10000, 6);
+  });
+
+  it('weniger als 3 Punkte → 0; kollineare Punkte → 0', () => {
+    expect(polygonArea([{ x: 0, y: 0 }, { x: 1, y: 1 }])).toBe(0);
+    expect(polygonArea([{ x: 0, y: 0 }, { x: 100, y: 0 }, { x: 200, y: 0 }])).toBe(0);
+  });
+});
+
+describe('H5: formatArea', () => {
+  it('mm: 5000 → "5000 mm²" (scaleFactor 1)', () => {
+    expect(formatArea(5000, 'mm', 1)).toBe('5000 mm²');
+  });
+
+  it('cm: 5000mm² → "50.0 cm²"', () => {
+    expect(formatArea(5000, 'cm', 1)).toBe('50.0 cm²');
+  });
+
+  it('m: 5000000mm² → "5.00 m²"', () => {
+    expect(formatArea(5000000, 'm', 1)).toBe('5.00 m²');
+  });
+
+  it('Flächen skalieren QUADRATISCH: 5 WE² bei scaleFactor 1000 = 5000000 mm²', () => {
+    // 1 Welt-Einheit = 1000mm → 1 WE² = 1.000.000 mm²
+    expect(formatArea(5, 'mm', 1000)).toBe('5000000 mm²');
+  });
+});
+
+describe('H5: measureAreaTool', () => {
+  // Module-State areaPts leakt zwischen Tests — vor jedem Test resetten:
+  beforeEach(() => {
+    measureAreaTool.handlers.cancel?.({ setStatus: () => {} } as never);
+  });
+  function fireSeq(events: Array<{ type: 'down' | 'move' | 'key' | 'cancel'; x?: number; y?: number; key?: string }>, options: Record<string, unknown> = {}) {
+    const statuses: string[] = [];
+    const ctx: any = {
+      options,
+      setStatus: (m: string) => statuses.push(m),
+      setPreview: (_el: CADElement | null) => {},
+      doc: null,
+    };
+    for (const ev of events) {
+      if (ev.type === 'down') measureAreaTool.handlers.down!({ world: { x: ev.x!, y: ev.y! } } as never, ctx);
+      if (ev.type === 'move') measureAreaTool.handlers.move!({ world: { x: ev.x!, y: ev.y! } } as never, ctx);
+      if (ev.type === 'key' && ev.key) measureAreaTool.handlers.key?.({ key: ev.key } as never, ctx);
+      if (ev.type === 'cancel') measureAreaTool.handlers.cancel?.(ctx);
+    }
+    return statuses;
+  }
+
+  it('erster Klick startet Messung, Status fordert weitere Punkte', () => {
+    const s = fireSeq([{ type: 'down', x: 0, y: 0 }]);
+    expect(s[0]).toContain('Fläche');
+    expect(s[s.length - 1]).toContain('klicken');
+  });
+
+  it('Live-Fläche im Status ab 3 Punkten bei move', () => {
+    const s = fireSeq([
+      { type: 'down', x: 0, y: 0 },
+      { type: 'down', x: 100, y: 0 },
+      { type: 'down', x: 100, y: 50 },
+      { type: 'move', x: 0, y: 50 },
+    ]);
+    expect(s.some((m) => m.includes('5000'))).toBe(true);
+    expect(s[s.length - 1]).toContain('mm²');
+  });
+
+  it('ENTER committet ab 3 Punkten mit Endfläche im Status', () => {
+    const s = fireSeq([
+      { type: 'down', x: 0, y: 0 },
+      { type: 'down', x: 100, y: 0 },
+      { type: 'down', x: 100, y: 100 },
+      { type: 'key', key: 'Enter' },
+    ]);
+    // Dreieck (0,0),(100,0),(100,100): Shoelace = 1/2 · 100 · 100 = 5000
+    expect(s[s.length - 1]).toContain('5000');
+    expect(s[s.length - 1]).toContain('3 Punkte');
+  });
+
+  it('ENTER mit weniger als 3 Punkten committet NICHT (Status erklärt)', () => {
+    const s = fireSeq([
+      { type: 'down', x: 0, y: 0 },
+      { type: 'down', x: 100, y: 0 },
+      { type: 'key', key: 'Enter' },
+    ]);
+    expect(s[s.length - 1]).toContain('3');
+  });
+
+  it('cancel setzt Messung zurück', () => {
+    const s = fireSeq([
+      { type: 'down', x: 0, y: 0 },
+      { type: 'down', x: 50, y: 50 },
+      { type: 'cancel' },
+      { type: 'down', x: 0, y: 0 },
+    ]);
+    // Nach cancel startet eine frische Messung (kein altes Polygon)
+    expect(s[s.length - 1]).toContain('klicken');
+  });
+
+  it('Manifest: id measure-area, tags basic, ribbonTab canvas', () => {
+    expect(measureAreaTool.manifest.id).toBe('measure-area');
+    expect(measureAreaTool.manifest.ribbonTab).toBe('canvas');
+    expect((measureAreaTool.manifest.tags ?? [])).toContain('basic');
+  });
+});