@seatlayer/core 0.53.0 → 0.55.0

package/dist/core/layout/index.d.cts

@@ -0,0 +1,376 @@
+import { P as Point, r as CubicPath, s as TextObject } from '../../types-DTSG6_Hq.cjs';
+export { E as ExpandChartOptions, R as RowSeatSlot, T as TableSeatSlot, a as allObjects, c as chartBounds, e as expandBooth, b as expandChart, d as expandRow, f as expandRowSlots, g as expandTable, h as expandTableSlots, i as floorObjects, j as floorOverviewTranslations, k as floorsOf, l as layoutFloorOverview, o as objectCenter, m as owningSectionForObject, p as pointInPolygon, n as pointInPolygonWithHoles, q as polygonLabelPoint, r as rowInventoryCount, s as rowSeatPositions, t as stackFloors, u as tableInventoryCount, v as tableSeatCountsBySide, w as translateObject } from '../../layout-Dlv5bIf2.cjs';
+export { a as SegmentedRowComponent, S as SegmentedRowPlacement, r as resolveSegmentedRowGroups, s as segmentedRowComponentSeats, b as segmentedRowComponents, c as segmentedRowSeatTotal } from '../../segmentedRowModel-BNXEUeHp.cjs';
+import { E as ExpandedSeat } from '../../renderer-DySMcKAR.cjs';
+
+type SectionShellMode = 'auto' | 'rectangle' | 'tapered' | 'bezier';
+declare function cubicPoint(path: CubicPath, t: number): Point;
+/**
+ * Build a predictable single-bend cubic whose midpoint passes exactly through
+ * `middle`. At t=.5 a cubic weighs both controls by 3/8, so moving both
+ * controls together by 4/3 of the requested midpoint offset makes the visible
+ * curve pass through the point the author dragged to.
+ *
+ * Lives here rather than in the Designer because two features need the same
+ * answer: the row bend handle (`renderRowPathHandles`) and the row curvature
+ * operations in `controller/rowOpsFacet`.
+ */
+declare function smoothCubicThroughMiddle(start: Point, end: Point, middle: Point): CubicPath;
+/** Equal-arc-length points on a cubic path, including both endpoints. */
+declare function distributeAlongCubic(path: CubicPath, count: number, resolution?: number): Point[];
+/**
+ * Convert a server-mapped rectangle into an editable complex shell. The four
+ * corners must be clockwise. No caller-supplied control points are accepted.
+ */
+declare function buildSectionShell(corners: Point[], focal: Point, requested: SectionShellMode): {
+    mode: Exclude<SectionShellMode, 'auto'>;
+    outline: Point[];
+};
+/** Server-owned straight aisle cutouts spanning the near/far edges. */
+declare function buildAisleHoles(corners: Point[], focal: Point, count: number, mode: Exclude<SectionShellMode, 'auto'>): Point[][];
+
+/** Axis-aligned chart bounds used to derive a stable, document-relative camera. */
+interface PerspectiveBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A deterministic pinhole camera for the projected 2.5D buyer/Designer views.
+ * Coordinates stay in chart units so the ordinary Stage camera (pan/zoom) can
+ * remain the only screen-space transform.
+ */
+interface PerspectiveCamera {
+    target: Point;
+    /** Horizontal distance from target to camera, in chart units. */
+    distance: number;
+    /** Camera height above the chart datum, in chart units. */
+    height: number;
+    /** Pinhole focal length, in chart units. */
+    focalLength: number;
+    /** Small plan rotation which keeps the venue from reading as a flat elevation. */
+    yawRad: number;
+}
+/** Canvas/Konva affine: x' = a·x + c·y + e; y' = b·x + d·y + f. */
+interface Affine2D {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+}
+interface PerspectivePoint extends Point {
+    /** Positive camera-space distance; larger values are farther away. */
+    depth: number;
+    /** Perspective size multiplier at this point (1 at the camera target). */
+    scale: number;
+}
+/**
+ * Choose a camera from venue bounds rather than fixed pixels. The camera rises
+ * above the tallest authored surface, so even the (deliberately generous)
+ * 120-m validation ceiling cannot cross the near plane.
+ */
+declare function createPerspectiveCamera(bounds: PerspectiveBounds, maxSurfaceHeightWorld?: number): PerspectiveCamera;
+/** Project one 3D chart point through the pinhole camera. */
+declare function projectPerspectivePoint(camera: PerspectiveCamera, point: Point, heightWorld?: number): PerspectivePoint;
+declare function applyAffine(affine: Affine2D, point: Point): Point;
+declare function invertAffine(affine: Affine2D): Affine2D;
+/** Return `left(right(point))`. */
+declare function composeAffine(left: Affine2D, right: Affine2D): Affine2D;
+/**
+ * First-order projection around one object/section anchor. The height callback
+ * may describe a raked surface; sampling one chart unit along x/y captures its
+ * local slope. Per-section tangents are the intentional shell-performance
+ * contract. Buyer seat anchors are projected exactly by `projectPerspectivePoint`;
+ * only non-interactive section surfaces use this bounded approximation.
+ */
+declare function perspectiveTangentAffine(camera: PerspectiveCamera, anchor: Point, heightAt?: (point: Point) => number): Affine2D;
+/** Parameters accepted by Konva's rotation/scale/skew decomposition. */
+declare function decomposeAffineLinear(affine: Affine2D): {
+    rotationDeg: number;
+    scaleX: number;
+    scaleY: number;
+    skewX: number;
+};
+
+/**
+ * Where a label belongs inside a polygon.
+ *
+ * A polygon's average-of-vertices centroid is not a label anchor. Two things
+ * break it on real venue geometry:
+ *
+ *  - Concavity. An L-shaped concourse block, a C-shaped bowl tier, or a wedge
+ *    with an aisle cut out can have its centroid land in the notch — outside
+ *    the shape entirely.
+ *  - Vertex density. A traced contour samples a curved outer arc with dozens of
+ *    points and the two straight radial edges with two. The average is dragged
+ *    onto the arc, so the label sits hard against the boundary and its pill
+ *    spills into the neighbouring section.
+ *
+ * The right anchor is the *pole of inaccessibility*: the interior point
+ * furthest from every edge — the centre of the largest circle that fits inside
+ * the polygon. That is the fattest part of the shape, which is exactly where a
+ * label has room. This is the Mapbox `polylabel` algorithm: subdivide the
+ * bounding box into cells, keep the cell whose optimistic upper bound is best,
+ * and stop once no cell can beat the incumbent by more than `precision`.
+ *
+ * The returned `radius` is as useful as the point: it is the half-width of the
+ * room available, so a caller can shrink a label to fit — or decide it never
+ * will — without measuring glyphs.
+ */
+interface InscribedAnchor {
+    /** Interior point furthest from every ring (outer boundary and holes). */
+    point: Point;
+    /** Distance from `point` to the nearest edge — the inscribed circle radius. */
+    radius: number;
+}
+/** Distance from `p` to the closest edge of any ring (unsigned). */
+declare function distanceToRings(p: Point, rings: readonly (readonly Point[])[]): number;
+/** Area of a ring (absolute, shoelace). */
+declare function polygonArea(ring: readonly Point[]): number;
+/** Net area of a polygon with holes — the space a section actually occupies. */
+declare function polygonNetArea(outer: readonly Point[], holes?: readonly (readonly Point[])[]): number;
+/**
+ * Largest-inscribed-circle anchor for a polygon (with optional holes).
+ *
+ * Deterministic: no randomness, no dependence on vertex order or winding, so
+ * the same geometry always produces the same anchor. Callers can therefore
+ * memoize on geometry alone.
+ */
+declare function polygonInscribedAnchor(outer: readonly Point[], holes?: readonly (readonly Point[])[]): InscribedAnchor;
+
+/**
+ * Pure-TypeScript spatial index for seat hit-testing.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `src/engine/SeatmapRenderer.ts` currently leans on Konva's built-in hit graph
+ * (the `listening` property, ~58 call sites) for "which seat did the pointer
+ * land on". No other renderer we care about ships an equivalent: React Native
+ * Skia has nothing at all, and Flutter / SwiftUI / Compose canvases all expect
+ * the app to own hit-testing. So the index has to exist on every path — and on
+ * the web it additionally lets us drop Konva's hit graph, which is a real win at
+ * 5k–13k seats (no per-seat hit-canvas rasterisation, no hit-graph traversal).
+ *
+ * This module is deliberately DEPENDENCY-FREE: no DOM, no Konva, no browser
+ * globals. It runs unchanged in a Web Worker, in workerd, and under React
+ * Native. All coordinates are WORLD space — converting screen→world is the
+ * caller's job, exactly as `SeatmapRenderer.screenToWorld` does today.
+ *
+ * STRUCTURE: uniform grid, not a quadtree
+ * ---------------------------------------
+ * Seats in a venue chart are close to uniformly dense by construction — they sit
+ * in rows on a near-regular pitch. That is the single case a uniform grid is
+ * optimal for, and it beats a quadtree on every axis that matters here:
+ * O(n) build with no rebalancing, flat typed-array storage (one contiguous
+ * scan per query, no pointer chasing), and O(1) expected candidates per point
+ * query. A quadtree only starts to pay when density varies by orders of
+ * magnitude across the extent, which a seating chart does not do. If a future
+ * chart shape ever breaks that assumption, `gridStats()` exposes the occupancy
+ * numbers needed to prove it before reaching for a tree.
+ *
+ * Each seat is inserted into EVERY cell its axis-aligned bounding box overlaps
+ * (not just the cell holding its centre). That is what makes {@link hitTest}
+ * examine exactly one cell: any seat whose shape contains a point also has an
+ * AABB containing that point, so it is guaranteed to be registered in that
+ * point's cell.
+ */
+
+/**
+ * Default seat radius in world units. Mirrors `SEAT_RADIUS` in
+ * `SeatmapRenderer.ts` and `DesignerController.ts` (both 9). The renderer scales
+ * this by `theme.seatScale` clamped to [0.7, 1.6]; callers that do the same must
+ * pass the scaled value via {@link BuildOptions.seatRadius} so the index agrees
+ * with what is actually drawn.
+ */
+declare const DEFAULT_SEAT_RADIUS = 9;
+/**
+ * Hit geometry for one seat. Real seats are circles; trade-show booths render as
+ * rotated rounded rects whose dimensions live on the booth object in the
+ * ChartDoc, not on `ExpandedSeat` — so the caller supplies them through
+ * {@link BuildOptions.shapeOf} rather than this module reaching for the doc.
+ */
+type SeatShape = {
+    kind: 'circle';
+    r: number;
+} | {
+    kind: 'rect';
+    width: number;
+    height: number;
+    rotation?: number;
+};
+interface BuildOptions {
+    /** Radius for circular seats when {@link shapeOf} is absent. Default {@link DEFAULT_SEAT_RADIUS}. */
+    seatRadius?: number;
+    /**
+     * Per-seat hit geometry. Return `null`/`undefined` to fall back to a circle of
+     * `seatRadius`. Called exactly once per seat during construction.
+     */
+    shapeOf?: (seat: ExpandedSeat) => SeatShape | null | undefined;
+    /**
+     * Upper bound on grid cells, to stop a chart with one far-flung stray object
+     * from allocating a huge sparse grid. Default `max(64, 4 * seats.length)`.
+     * When the natural cell size would exceed this, cells are grown until it fits.
+     */
+    maxCells?: number;
+}
+interface QueryOptions {
+    /**
+     * Restrict results to seats this predicate accepts — used to reproduce the
+     * renderer's `isSelectable(id) || selection.has(id)` gate. Kept as a query
+     * argument rather than build state on purpose: seat statuses change on every
+     * websocket tick, and the geometry does not.
+     */
+    filter?: (id: string, seat: ExpandedSeat) => boolean;
+}
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface RectQueryOptions extends QueryOptions {
+    /**
+     * `'center'` (default) keeps a seat when its CENTRE falls inside the rect,
+     * bounds inclusive. This is what `SeatmapRenderer.finishMarquee` does today,
+     * so it is the default in order to be a drop-in replacement.
+     *
+     * `'overlap'` keeps a seat when its hit SHAPE intersects the rect at all —
+     * the right mode for "which seats are on screen" viewport culling and
+     * label-rendering passes, where a partially visible seat still counts.
+     */
+    mode?: 'center' | 'overlap';
+}
+interface IndexedSeat {
+    seat: ExpandedSeat;
+    shape: SeatShape;
+    /** Half-extents of the shape's axis-aligned bounding box (rotation applied). */
+    hx: number;
+    hy: number;
+}
+interface SeatIndex {
+    readonly seats: readonly ExpandedSeat[];
+    /** @internal */
+    readonly entries: readonly IndexedSeat[];
+    /** @internal */
+    readonly minX: number;
+    /** @internal */
+    readonly minY: number;
+    /** @internal */
+    readonly cell: number;
+    /** @internal */
+    readonly cols: number;
+    /** @internal */
+    readonly rows: number;
+    /** @internal Prefix-sum offsets into {@link items}; length cols*rows+1. */
+    readonly cellStart: Int32Array;
+    /** @internal Seat indices grouped by cell. */
+    readonly items: Int32Array;
+    /** @internal Per-seat visit stamps, for dedup across multi-cell scans. */
+    readonly stamp: Int32Array;
+    /** @internal Monotonically increasing stamp epoch. */
+    epoch: number;
+}
+/**
+ * Build a uniform-grid index over `seats`. O(n) in time and memory.
+ *
+ * CELL SIZE
+ * ---------
+ * The nominal cell is `4 × maxHalfExtent`, i.e. twice the largest seat's
+ * bounding-box width. Two properties fall out of that choice:
+ *
+ *  - A seat's AABB is at most half a cell across, so it lands in at most 2×2 = 4
+ *    cells. Build stays O(n) with a small constant, and the index does not blow
+ *    up in memory from duplicated references.
+ *  - For the default 9px seat radius the cell is 36 world units, versus a real
+ *    row/seat pitch of roughly 20–26. That works out to ~1–2 seats per occupied
+ *    cell, so a point query examines about one or two candidates. Halving the
+ *    cell would quadruple cell count to shave a fraction of a candidate;
+ *    doubling it would put ~6 seats in every cell. 4× the half-extent is the
+ *    flat part of that curve.
+ *
+ * The one pathological input is a chart whose bounds are enormous relative to
+ * its seat count — a single stray object parked far from the venue. `maxCells`
+ * caps the grid and grows the cell size until it fits, trading query sharpness
+ * for bounded memory. Real charts never hit it.
+ */
+declare function buildSeatIndex(seats: readonly ExpandedSeat[], opts?: BuildOptions): SeatIndex;
+/**
+ * The seat whose hit shape contains `p`, or null.
+ *
+ * On overlap — seats drawn close enough that their circles intersect — the seat
+ * whose CENTRE is nearest to `p` wins. That matches what a user perceives (you
+ * hit the thing you aimed at) and, unlike Konva, is order-independent: Konva's
+ * hit graph resolves overlap by draw order, returning the topmost/last-added
+ * node regardless of how far off-centre the pointer was.
+ */
+declare function hitTest(index: SeatIndex, p: Point, opts?: QueryOptions): string | null;
+/**
+ * Nearest seat CENTRE strictly within `radius` world units of `p`, or null.
+ *
+ * This is the near-miss rescue from `SeatmapRenderer.nearestSeatToScreen`,
+ * lifted verbatim. The caller computes the radius the same way the renderer
+ * does today:
+ *
+ *     const reachWorld = seatR + slopPx / stageScale;   // SEAT_TAP_SLOP_PX = 14
+ *     nearestWithin(index, screenToWorld(pointer), reachWorld, { filter });
+ *
+ * Note the comparison is STRICTLY less-than, mirroring the renderer's
+ * `bestD = reachWorld; ... if (d < bestD)` loop: a seat centre sitting exactly
+ * `reachWorld` away does not qualify. Distance is measured to the seat centre,
+ * not the shape edge — so for the default circle, "centre within seatR + slop"
+ * is identical to "edge within slop", which is what the renderer's docstring
+ * describes.
+ */
+declare function nearestWithin(index: SeatIndex, p: Point, radius: number, opts?: QueryOptions): string | null;
+/**
+ * Seat ids inside a world-space rect. Negative width/height are normalised, so a
+ * marquee dragged up-and-left works without the caller sorting the corners.
+ *
+ * Default `mode: 'center'` reproduces `SeatmapRenderer.finishMarquee` exactly:
+ * a seat is kept when its centre is within the rect, bounds INCLUSIVE. Use
+ * `mode: 'overlap'` for viewport culling, where a seat straddling the edge
+ * should still be drawn.
+ *
+ * Results come back in ascending seat-array order, so the output is stable
+ * across calls regardless of grid layout.
+ */
+declare function queryRect(index: SeatIndex, rect: Rect, opts?: RectQueryOptions): string[];
+/**
+ * Occupancy stats for the built grid. Diagnostic only — this is the evidence to
+ * check before anyone argues the uniform grid has stopped being good enough and
+ * a tree is warranted.
+ */
+declare function gridStats(index: SeatIndex): {
+    cell: number;
+    cols: number;
+    rows: number;
+    cells: number;
+    occupiedCells: number;
+    refs: number;
+    maxPerCell: number;
+    meanPerOccupiedCell: number;
+};
+
+declare const TEXT_WIDTH_MIN = 40;
+declare const TEXT_WIDTH_MAX = 1200;
+declare const TEXT_LINE_HEIGHT_MIN = 0.8;
+declare const TEXT_LINE_HEIGHT_MAX = 3;
+declare const TEXT_LETTER_SPACING_MIN = -2;
+declare const TEXT_LETTER_SPACING_MAX = 20;
+declare const TEXT_OPACITY_MIN = 0.1;
+declare const TEXT_BACKGROUND_PADDING_MAX = 40;
+declare const TEXT_BACKGROUND_RADIUS_MAX = 40;
+interface TextLayoutMetrics {
+    width: number;
+    height: number;
+    lineCount: number;
+    padding: number;
+}
+/** Conservative renderer-independent box used by chart bounds, quality and
+ * collision checks. Konva remains authoritative for exact glyph metrics. */
+declare function textLayoutMetrics(text: TextObject): TextLayoutMetrics;
+
+export { type Affine2D, type BuildOptions, DEFAULT_SEAT_RADIUS, type InscribedAnchor, type PerspectiveBounds, type PerspectiveCamera, type PerspectivePoint, type QueryOptions, type Rect, type RectQueryOptions, type SeatIndex, type SeatShape, type SectionShellMode, TEXT_BACKGROUND_PADDING_MAX, TEXT_BACKGROUND_RADIUS_MAX, TEXT_LETTER_SPACING_MAX, TEXT_LETTER_SPACING_MIN, TEXT_LINE_HEIGHT_MAX, TEXT_LINE_HEIGHT_MIN, TEXT_OPACITY_MIN, TEXT_WIDTH_MAX, TEXT_WIDTH_MIN, type TextLayoutMetrics, applyAffine, buildAisleHoles, buildSeatIndex, buildSectionShell, composeAffine, createPerspectiveCamera, cubicPoint, decomposeAffineLinear, distanceToRings, distributeAlongCubic, gridStats, hitTest, invertAffine, nearestWithin, perspectiveTangentAffine, polygonArea, polygonInscribedAnchor, polygonNetArea, projectPerspectivePoint, queryRect, smoothCubicThroughMiddle, textLayoutMetrics };