@pascal-app/editor 1.0.3 → 1.0.5

package/src/lib/wall-region-handles.ts

@@ -0,0 +1,368 @@
+import {
+  getWallArcData,
+  getWallChordFrame,
+  getWallFaceOffsets,
+  type WallFace,
+  type WallFaceRegion,
+  type WallNode,
+} from '@pascal-app/core'
+import { Matrix4, Quaternion, Vector3 } from 'three'
+import type { WallRegionBounds } from './paint-regions'
+
+// Geometry for editing a selected wall's paint regions in place. Everything is
+// in the wall mesh's local frame: x along the chord from the start (= region
+// `u`), y up from the wall base, z toward the reference line's left (face a).
+// A region's `v` is measured above its face's own base, so callers pass the
+// face base as `baseAt(u)`.
+
+export const REGION_MIN_SIZE = 0.02
+export const REGION_EDGE_SNAP_TOLERANCE = 0.08
+const EDGE_EPSILON = 1e-4
+
+export type RegionEdge = 'u0' | 'u1' | 'v0' | 'v1'
+export const REGION_EDGES: readonly RegionEdge[] = ['u0', 'u1', 'v0', 'v1']
+
+export type WallFaceSurface =
+  | { kind: 'plane'; face: WallFace; length: number; z: number }
+  | {
+      kind: 'arc'
+      face: WallFace
+      length: number
+      cx: number
+      cz: number
+      radius: number
+      direction: number
+    }
+
+type WallSurfaceInput = Pick<
+  WallNode,
+  'start' | 'end' | 'curveOffset' | 'thickness' | 'justification'
+>
+
+/** The face's surface in wall-local coordinates: a vertical plane or a vertical cylinder. */
+export function getWallFaceSurface(wall: WallSurfaceInput, face: WallFace): WallFaceSurface {
+  const chord = getWallChordFrame(wall)
+  const offset = getWallFaceOffsets(wall)[face]
+  const arc = getWallArcData(wall)
+  if (!arc) return { kind: 'plane', face, length: chord.length, z: offset }
+  const dx = arc.center.x - chord.start.x
+  const dy = arc.center.y - chord.start.y
+  // Left of a counter-clockwise arc points at its centre, so an offset toward
+  // the left shrinks the radius there.
+  return {
+    kind: 'arc',
+    face,
+    length: chord.length,
+    cx: dx * chord.tangent.x + dy * chord.tangent.y,
+    cz: dx * chord.normal.x + dy * chord.normal.y,
+    radius: Math.max(1e-6, arc.radius - arc.direction * offset),
+    direction: arc.direction,
+  }
+}
+
+const Y_AXIS = new Vector3(0, 1, 0)
+const UNIT_SCALE = new Vector3(1, 1, 1)
+
+/** Wall-local → parent (level) matrix, the transform the wall mesh renders with. */
+export function wallLocalMatrix(
+  wall: Pick<WallNode, 'start' | 'end'>,
+  baseElevation: number,
+  target = new Matrix4(),
+): Matrix4 {
+  const angle = Math.atan2(wall.end[1] - wall.start[1], wall.end[0] - wall.start[0])
+  return target.compose(
+    new Vector3(wall.start[0], baseElevation, wall.start[1]),
+    new Quaternion().setFromAxisAngle(Y_AXIS, -angle),
+    UNIT_SCALE,
+  )
+}
+
+export type FaceSurfacePoint = {
+  x: number
+  z: number
+  /** Outward normal of this face, wall-local XZ. */
+  nx: number
+  nz: number
+  /** Unit tangent toward increasing u, wall-local XZ. */
+  tx: number
+  tz: number
+}
+
+/** The point on the face above chord station `u`, with its outward normal and tangent. */
+export function faceSurfacePoint(surface: WallFaceSurface, u: number): FaceSurfacePoint {
+  const outward = surface.face === 'a' ? 1 : -1
+  if (surface.kind === 'plane') {
+    return { x: u, z: surface.z, nx: 0, nz: outward, tx: 1, tz: 0 }
+  }
+  const du = u - surface.cx
+  const root = Math.sqrt(Math.max(0, surface.radius * surface.radius - du * du))
+  const z = surface.cz - surface.direction * root
+  // Left normal of the curve: toward the centre on a counter-clockwise arc.
+  const lx = (surface.direction * (surface.cx - u)) / surface.radius
+  const lz = (surface.direction * (surface.cz - z)) / surface.radius
+  const length = Math.hypot(lx, lz) || 1
+  const nx = (lx / length) * outward
+  const nz = (lz / length) * outward
+  return { x: u, z, nx, nz, tx: lz / length, tz: -lx / length }
+}
+
+type Vec3 = { x: number; y: number; z: number }
+
+/**
+ * Where a wall-local ray meets the face: `u` along the chord and local `y`.
+ * Null when the ray runs parallel to the face or misses it.
+ */
+export function intersectFaceSurface(
+  surface: WallFaceSurface,
+  origin: Vec3,
+  direction: Vec3,
+): { u: number; y: number } | null {
+  if (surface.kind === 'plane') {
+    if (Math.abs(direction.z) < 1e-9) return null
+    const t = (surface.z - origin.z) / direction.z
+    if (!(t >= 0)) return null
+    return { u: origin.x + direction.x * t, y: origin.y + direction.y * t }
+  }
+  const ox = origin.x - surface.cx
+  const oz = origin.z - surface.cz
+  const a = direction.x * direction.x + direction.z * direction.z
+  if (a < 1e-12) return null
+  const b = 2 * (ox * direction.x + oz * direction.z)
+  const c = ox * ox + oz * oz - surface.radius * surface.radius
+  const discriminant = b * b - 4 * a * c
+  if (discriminant < 0) return null
+  const root = Math.sqrt(discriminant)
+  for (const t of [(-b - root) / (2 * a), (-b + root) / (2 * a)]) {
+    if (t < 0) continue
+    const z = origin.z + direction.z * t
+    // Only the branch the wall bulges along is the face.
+    if ((z - surface.cz) * -surface.direction < -1e-9) continue
+    return { u: origin.x + direction.x * t, y: origin.y + direction.y * t }
+  }
+  return null
+}
+
+export type ResolvedRegionBounds = { u0: number; u1: number; v0: number; v1: number }
+
+/** Region bounds with absent edges resolved to the face's edges. */
+export function resolveRegionBounds(
+  region: Pick<WallFaceRegion, 'u0' | 'u1' | 'v0' | 'v1'>,
+  length: number,
+  faceHeight: number,
+): ResolvedRegionBounds {
+  return {
+    u0: Math.max(0, region.u0 ?? 0),
+    u1: Math.min(length, region.u1 ?? length),
+    v0: Math.max(0, region.v0 ?? 0),
+    v1: Math.min(faceHeight, region.v1 ?? faceHeight),
+  }
+}
+
+export function regionBoundsOf(region: WallFaceRegion): WallRegionBounds {
+  const bounds: WallRegionBounds = {}
+  for (const edge of REGION_EDGES) if (region[edge] !== undefined) bounds[edge] = region[edge]
+  return bounds
+}
+
+export type RegionBoundDragInput = {
+  region: WallFaceRegion
+  edge: RegionEdge
+  /** Unsnapped pointer value for the edge: metres along (u) or above the face base (v). */
+  raw: number
+  length: number
+  faceHeight: number
+  gridStep?: number | null
+  /** Openings' and other regions' bounds on this face (`wallRegionSnapTargets`); face edges are always targets. */
+  snapTargets?: readonly number[]
+  edgeSnap?: boolean
+  snapTolerance?: number
+}
+
+/**
+ * The region's bounds after dragging one edge. Snaps to the grid, then (when
+ * edge snapping is on) to the face edges and other regions within tolerance;
+ * clamps so the region keeps REGION_MIN_SIZE and stays on the face. An edge
+ * dragged onto the face edge becomes absent, so it follows the wall.
+ */
+export function resolveRegionBoundDrag(input: RegionBoundDragInput): WallRegionBounds {
+  const { region, edge, raw, length, faceHeight } = input
+  const isU = edge[0] === 'u'
+  const extent = isU ? length : faceHeight
+  let value = raw
+  if (input.gridStep && input.gridStep > 0)
+    value = Math.round(raw / input.gridStep) * input.gridStep
+  if (input.edgeSnap) {
+    const tolerance = input.snapTolerance ?? REGION_EDGE_SNAP_TOLERANCE
+    let best: number | null = null
+    for (const target of [0, extent, ...(input.snapTargets ?? [])]) {
+      const distance = Math.abs(target - raw)
+      if (distance <= tolerance && (best === null || distance < Math.abs(best - raw))) {
+        best = target
+      }
+    }
+    if (best !== null) value = best
+  }
+
+  const current = resolveRegionBounds(region, length, faceHeight)
+  const low = edge === 'u0' || edge === 'v0'
+  const other = current[isU ? (low ? 'u1' : 'u0') : low ? 'v1' : 'v0']
+  const min = low ? 0 : Math.min(extent, other + REGION_MIN_SIZE)
+  const max = low ? Math.max(0, other - REGION_MIN_SIZE) : extent
+  value = Math.min(max, Math.max(min, value))
+
+  const bounds = regionBoundsOf(region)
+  const atFaceEdge = low ? value <= EDGE_EPSILON : value >= extent - EDGE_EPSILON
+  if (atFaceEdge) delete bounds[edge]
+  else bounds[edge] = value
+  return bounds
+}
+
+/** The region list with one region's bounds replaced (absent = to the edge). */
+export function withRegionBounds(
+  regions: readonly WallFaceRegion[],
+  regionId: string,
+  bounds: WallRegionBounds,
+): WallFaceRegion[] {
+  return regions.map((region) => {
+    if (region.id !== regionId) return region
+    const { u0: _u0, u1: _u1, v0: _v0, v1: _v1, ...rest } = region
+    const next: WallFaceRegion = { ...rest }
+    for (const edge of REGION_EDGES) if (bounds[edge] !== undefined) next[edge] = bounds[edge]
+    return next
+  })
+}
+
+export type RegionHandlePlacement = {
+  edge: RegionEdge
+  position: [number, number, number]
+  /** Yaw turning local +x onto the face tangent. */
+  yaw: number
+  /** Direction the handle points in the face plane: 0 = +u, π/2 = up. */
+  tipAngle: number
+}
+
+const TIP_ANGLE: Record<RegionEdge, number> = {
+  u0: Math.PI,
+  u1: 0,
+  v0: -Math.PI / 2,
+  v1: Math.PI / 2,
+}
+
+function yawOf(point: FaceSurfacePoint) {
+  return Math.atan2(-point.tz, point.tx)
+}
+
+/**
+ * One handle per bounded edge: u edges at the region's mid-height, v edges at
+ * its mid-width, lifted `lift` off the face. `keep` holds an edge that is
+ * being dragged, so its handle survives being dragged onto the face edge.
+ */
+export function regionHandlePlacements(
+  surface: WallFaceSurface,
+  region: WallFaceRegion,
+  faceHeight: number,
+  baseAt: (u: number) => number,
+  keep: RegionEdge | null = null,
+  lift = 0.01,
+): RegionHandlePlacement[] {
+  const bounds = resolveRegionBounds(region, surface.length, faceHeight)
+  const midU = (bounds.u0 + bounds.u1) / 2
+  const midV = (bounds.v0 + bounds.v1) / 2
+  const placements: RegionHandlePlacement[] = []
+  for (const edge of REGION_EDGES) {
+    if (region[edge] === undefined && edge !== keep) continue
+    const u = edge === 'u0' ? bounds.u0 : edge === 'u1' ? bounds.u1 : midU
+    const v = edge === 'v0' ? bounds.v0 : edge === 'v1' ? bounds.v1 : midV
+    const point = faceSurfacePoint(surface, u)
+    placements.push({
+      edge,
+      position: [point.x + point.nx * lift, baseAt(u) + v, point.z + point.nz * lift],
+      yaw: yawOf(point),
+      tipAngle: TIP_ANGLE[edge],
+    })
+  }
+  return placements
+}
+
+export type OutlinePoint = { position: [number, number, number]; normal: [number, number] }
+
+/** Closed outline of a region on its face (counter-clockwise seen from outside), lifted off it. */
+export function regionOutline(
+  surface: WallFaceSurface,
+  region: WallFaceRegion,
+  faceHeight: number,
+  baseAt: (u: number) => number,
+  lift = 0.004,
+): OutlinePoint[] {
+  const bounds = resolveRegionBounds(region, surface.length, faceHeight)
+  const width = bounds.u1 - bounds.u0
+  const segments = surface.kind === 'arc' ? Math.min(48, Math.max(2, Math.ceil(width / 0.2))) : 1
+  const at = (u: number, v: number): OutlinePoint => {
+    const point = faceSurfacePoint(surface, u)
+    return {
+      position: [point.x + point.nx * lift, baseAt(u) + v, point.z + point.nz * lift],
+      normal: [point.nx, point.nz],
+    }
+  }
+  const stations = Array.from(
+    { length: segments + 1 },
+    (_, index) => bounds.u0 + (width * index) / segments,
+  )
+  return [
+    ...stations.map((u) => at(u, bounds.v0)),
+    ...stations.reverse().map((u) => at(u, bounds.v1)),
+  ]
+}
+
+/**
+ * Triangles for a ribbon of half-width `halfWidth` running along a closed
+ * outline, lying in the face. Each segment is extended by the half-width so
+ * corners close.
+ */
+export function buildOutlineRibbon(
+  points: readonly OutlinePoint[],
+  halfWidth: number,
+): Float32Array {
+  const out: number[] = []
+  const count = points.length
+  for (let index = 0; index < count; index += 1) {
+    const a = points[index]!
+    const b = points[(index + 1) % count]!
+    const dx = b.position[0] - a.position[0]
+    const dy = b.position[1] - a.position[1]
+    const dz = b.position[2] - a.position[2]
+    const length = Math.hypot(dx, dy, dz)
+    if (length < 1e-9) continue
+    const ux = dx / length
+    const uy = dy / length
+    const uz = dz / length
+    const nx = (a.normal[0] + b.normal[0]) / 2
+    const nz = (a.normal[1] + b.normal[1]) / 2
+    // In-face perpendicular: normal × direction.
+    let wx = -nz * uy
+    let wy = nz * ux - nx * uz
+    let wz = nx * uy
+    const wLength = Math.hypot(wx, wy, wz) || 1
+    wx = (wx / wLength) * halfWidth
+    wy = (wy / wLength) * halfWidth
+    wz = (wz / wLength) * halfWidth
+    const p0 = [
+      a.position[0] - ux * halfWidth,
+      a.position[1] - uy * halfWidth,
+      a.position[2] - uz * halfWidth,
+    ]
+    const p1 = [
+      b.position[0] + ux * halfWidth,
+      b.position[1] + uy * halfWidth,
+      b.position[2] + uz * halfWidth,
+    ]
+    const q = [
+      [p0[0]! - wx, p0[1]! - wy, p0[2]! - wz],
+      [p0[0]! + wx, p0[1]! + wy, p0[2]! + wz],
+      [p1[0]! + wx, p1[1]! + wy, p1[2]! + wz],
+      [p1[0]! - wx, p1[1]! - wy, p1[2]! - wz],
+    ]
+    for (const corner of [0, 1, 2, 0, 2, 3]) out.push(...q[corner]!)
+  }
+  return new Float32Array(out)
+}

package/src/lib/wall-region-list.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  type SceneMaterial,
+  type SceneMaterialId,
+  WALL_FACE_REGION_LIMIT,
+  type WallFaceRegion,
+  WallNode,
+} from '@pascal-app/core'
+import {
+  describeRegionFinish,
+  formatRegionBounds,
+  wallRegionCapNotice,
+  wallRegionFaceLabels,
+  wallRegionRows,
+} from './wall-region-list'
+
+const LEVEL = 'level_region-list'
+const SCENE_ID = 'scene-material_region-list' as SceneMaterialId
+const materials = {
+  [SCENE_ID]: {
+    id: SCENE_ID,
+    name: 'Sage green',
+    material: { properties: { color: '#8fa98a' } },
+  } as SceneMaterial,
+}
+
+function wall(id: string, start: [number, number], end: [number, number]) {
+  return WallNode.parse({ id, parentId: LEVEL, start, end })
+}
+
+function nodesOf(walls: WallNode[]) {
+  return Object.fromEntries(walls.map((node) => [node.id, node])) as Record<string, AnyNode>
+}
+
+describe('bounds text', () => {
+  test('reads each axis in the viewer unit; absent bounds run to the edge', () => {
+    expect(formatRegionBounds({ v1: 0.9 }, 'metric')).toBe('0–0.90 m high')
+    expect(formatRegionBounds({ u0: 1.2, u1: 2.4 }, 'metric')).toBe('1.20–2.40 m along')
+    expect(formatRegionBounds({ u0: 1.2, u1: 2.4, v0: 0.9, v1: 2.1 }, 'metric')).toBe(
+      '1.20–2.40 m along, 0.90–2.10 m high',
+    )
+    expect(formatRegionBounds({ v0: 0.9 }, 'metric')).toBe('Above 0.90 m')
+    expect(formatRegionBounds({ u0: 1.5 }, 'metric')).toBe('From 1.50 m along')
+    expect(formatRegionBounds({}, 'metric')).toBe('Whole face')
+  })
+
+  test('imperial converts to feet', () => {
+    expect(formatRegionBounds({ v1: 0.9144 }, 'imperial')).toBe('0–3.00 ft high')
+  })
+})
+
+describe('face labels', () => {
+  test('a lone wall reads Face A / Face B', () => {
+    const lone = wall('wall_lone', [0, 0], [4, 0])
+    expect(wallRegionFaceLabels(nodesOf([lone]), lone.id)).toEqual({ a: 'Face A', b: 'Face B' })
+    expect(wallRegionFaceLabels({}, 'wall_missing')).toEqual({ a: 'Face A', b: 'Face B' })
+  })
+
+  test('a room wall names its inside and outside faces', () => {
+    const walls = [
+      wall('wall_s', [0, 0], [4, 0]),
+      wall('wall_e', [4, 0], [4, 3]),
+      wall('wall_n', [4, 3], [0, 3]),
+      wall('wall_w', [0, 3], [0, 0]),
+    ]
+    const labels = wallRegionFaceLabels(nodesOf(walls), 'wall_s')
+    expect(new Set(Object.values(labels))).toEqual(new Set(['Inside', 'Outside']))
+    // Drawn counter-clockwise, the room sits on the left: face a.
+    expect(labels.a).toBe('Inside')
+  })
+})
+
+describe('finish', () => {
+  test('a scene material shows its name and colour', () => {
+    expect(describeRegionFinish(`scene:${SCENE_ID}`, materials)).toEqual({
+      name: 'Sage green',
+      color: '#8fa98a',
+    })
+  })
+
+  test('unknown refs fall back to a neutral swatch', () => {
+    expect(describeRegionFinish('scene:missing', {}).name).toBe('Custom finish')
+    expect(describeRegionFinish('not-a-ref', {}).name).toBe('Custom finish')
+    expect(describeRegionFinish('library:no-such-material', {}).name).toBe('Library finish')
+  })
+})
+
+describe('rows', () => {
+  test('one row per region, face a first, with label, finish and bounds', () => {
+    const faceRegions: WallFaceRegion[] = [
+      { id: 'r1', face: 'b', v1: 0.9, finish: `scene:${SCENE_ID}` },
+      { id: 'r2', face: 'a', u0: 1.2, u1: 2.4, finish: `scene:${SCENE_ID}` },
+    ]
+    const rows = wallRegionRows({ faceRegions }, { a: 'Inside', b: 'Outside' }, materials, 'metric')
+    expect(rows.map(({ id, faceLabel, boundsText }) => ({ id, faceLabel, boundsText }))).toEqual([
+      { id: 'r2', faceLabel: 'Inside', boundsText: '1.20–2.40 m along' },
+      { id: 'r1', faceLabel: 'Outside', boundsText: '0–0.90 m high' },
+    ])
+    expect(rows[0]!.finish.name).toBe('Sage green')
+  })
+
+  test('the cap notice appears only when a face is full', () => {
+    const full = (face: 'a' | 'b') =>
+      Array.from({ length: WALL_FACE_REGION_LIMIT }, (_, index) => ({
+        id: `${face}${index}`,
+        face,
+        finish: 'x',
+      }))
+    const labels = { a: 'Face A', b: 'Face B' }
+    expect(wallRegionCapNotice({ faceRegions: full('a').slice(1) }, labels)).toBeNull()
+    expect(wallRegionCapNotice({ faceRegions: full('b') }, labels)).toBe(
+      `Face B is full: up to ${WALL_FACE_REGION_LIMIT} regions per face`,
+    )
+    expect(wallRegionCapNotice({ faceRegions: [...full('a'), ...full('b')] }, labels)).toBe(
+      `Up to ${WALL_FACE_REGION_LIMIT} regions per face`,
+    )
+  })
+})

package/src/lib/wall-region-list.ts

@@ -0,0 +1,136 @@
+import {
+  type AnyNode,
+  getCatalogMaterialById,
+  parseMaterialRef,
+  roomSideFaces,
+  type SceneMaterial,
+  type SceneMaterialId,
+  WALL_FACE_REGION_LIMIT,
+  type WallFace,
+  type WallFaceRegion,
+  type WallNode,
+} from '@pascal-app/core'
+import { getLinearUnitLabel, type LinearUnit, metersToLinearUnit } from './measurements'
+
+// Rows for the wall panel's "Paint regions" list: finish swatch + name, the
+// face in room terms when the wall has a room on exactly one side, and the
+// bounds in the viewer unit.
+
+const FALLBACK_SWATCH_COLOR = '#d4d4d8'
+
+export type WallRegionFinish = { name: string; color: string; imageUrl?: string }
+
+export type WallRegionRow = {
+  id: string
+  face: WallFace
+  faceLabel: string
+  finish: WallRegionFinish
+  boundsText: string
+}
+
+/** "Inside" / "Outside" when a room sits on exactly one side of the wall, else "Face A" / "Face B". */
+export function wallRegionFaceLabels(
+  nodes: Readonly<Record<string, AnyNode>>,
+  wallId: string,
+): Record<WallFace, string> {
+  try {
+    const sides = roomSideFaces(nodes as Parameters<typeof roomSideFaces>[0], wallId)
+    if (sides.inside && sides.outside) {
+      return {
+        [sides.inside]: 'Inside',
+        [sides.outside]: 'Outside',
+      } as Record<WallFace, string>
+    }
+  } catch {
+    // Not a wall (any more): fall through to the neutral labels.
+  }
+  return { a: 'Face A', b: 'Face B' }
+}
+
+/** Name and swatch for a region's finish ref (library or scene material). */
+export function describeRegionFinish(
+  ref: string,
+  materials: Readonly<Record<SceneMaterialId, SceneMaterial>>,
+): WallRegionFinish {
+  const parsed = parseMaterialRef(ref)
+  if (parsed?.kind === 'scene') {
+    const scene = materials[parsed.id as SceneMaterialId]
+    return {
+      name: scene?.name ?? 'Custom finish',
+      color: scene?.material.properties?.color ?? FALLBACK_SWATCH_COLOR,
+      ...(scene?.material.texture?.url ? { imageUrl: scene.material.texture.url } : {}),
+    }
+  }
+  if (parsed?.kind === 'library') {
+    const item = getCatalogMaterialById(parsed.id)
+    const imageUrl = item?.previewThumbnailUrl ?? item?.preset.maps.albedoMap
+    return {
+      name: item?.label ?? 'Library finish',
+      color: item?.previewColor ?? item?.preset.mapProperties.color ?? FALLBACK_SWATCH_COLOR,
+      ...(imageUrl ? { imageUrl } : {}),
+    }
+  }
+  return { name: 'Custom finish', color: FALLBACK_SWATCH_COLOR }
+}
+
+function range(low: number | undefined, high: number | undefined, unit: LinearUnit, axis: string) {
+  const value = (meters: number) => metersToLinearUnit(meters, unit).toFixed(2)
+  const label = getLinearUnitLabel(unit)
+  if (low === undefined && high === undefined) return null
+  if (low === undefined) return `0–${value(high!)} ${label} ${axis}`
+  if (high === undefined)
+    return axis === 'high' ? `Above ${value(low)} ${label}` : `From ${value(low)} ${label} along`
+  return `${value(low)}–${value(high)} ${label} ${axis}`
+}
+
+/** "1.20–2.40 m along, 0–0.90 m high"; absent bounds run to the face edge. */
+export function formatRegionBounds(
+  region: Pick<WallFaceRegion, 'u0' | 'u1' | 'v0' | 'v1'>,
+  unit: LinearUnit,
+): string {
+  const parts = [
+    range(region.u0, region.u1, unit, 'along'),
+    range(region.v0, region.v1, unit, 'high'),
+  ].filter((part): part is string => part !== null)
+  return parts.length > 0 ? parts.join(', ') : 'Whole face'
+}
+
+export function wallRegionRows(
+  wall: Pick<WallNode, 'faceRegions'>,
+  faceLabels: Record<WallFace, string>,
+  materials: Readonly<Record<SceneMaterialId, SceneMaterial>>,
+  unit: LinearUnit,
+): WallRegionRow[] {
+  const regions = wall.faceRegions ?? []
+  return (['a', 'b'] as const).flatMap((face) =>
+    regions
+      .filter((region) => region.face === face)
+      .map((region) => ({
+        id: region.id,
+        face,
+        faceLabel: faceLabels[face],
+        finish: describeRegionFinish(region.finish, materials),
+        boundsText: formatRegionBounds(region, unit),
+      })),
+  )
+}
+
+/** Faces that already hold the maximum number of regions. */
+export function fullWallFaces(wall: Pick<WallNode, 'faceRegions'>): WallFace[] {
+  const regions = wall.faceRegions ?? []
+  return (['a', 'b'] as const).filter(
+    (face) => regions.filter((region) => region.face === face).length >= WALL_FACE_REGION_LIMIT,
+  )
+}
+
+/** The cap notice under the list, naming the full face when only one is. */
+export function wallRegionCapNotice(
+  wall: Pick<WallNode, 'faceRegions'>,
+  faceLabels: Record<WallFace, string>,
+): string | null {
+  const full = fullWallFaces(wall)
+  const cap = `up to ${WALL_FACE_REGION_LIMIT} regions per face`
+  if (full.length === 0) return null
+  if (full.length === 2) return `Up to ${WALL_FACE_REGION_LIMIT} regions per face`
+  return `${faceLabels[full[0]!]} is full: ${cap}`
+}