venuekit 0.0.0-stage → 0.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Cruz Fernández
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,332 @@
-# Temporary Holding Version
+# VenueKit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/venuekit.svg)](https://www.npmjs.com/package/venuekit)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+**Seating charts for ticketing apps.** A floor-plan editor for organizers and an interactive
+seat map for buyers, in one React package with a framework-free core.
+
+Draw a venue with numbered seat blocks, tables, standing-room zones and landmarks (stage,
+bar, restrooms…), assign each piece to a ticket type, and let buyers pick their exact seat.
+VenueKit handles the drawing, numbering, validation and the "don't break what's already
+sold" rules; your app keeps the money, the inventory and the database.
+
+- **Editor (`<VenueDesigner />`)** — guided by your ticket types: blocks of seats (straight or
+  curved), round and square tables, general-admission zones, landmarks, a background image to
+  trace over, resize handles, smart alignment guides, multi-select with align/distribute,
+  undo/redo, keyboard support, and a phone layout.
+- **Numbering your way** — rows with letters (optionally with Ñ, then AA, AB…) or numbers;
+  seats in sequence, odd only, even only, or from the center out; any starting point,
+  left-to-right or right-to-left, skipped numbers, and removed seats for aisles.
+- **Capacity aware** — give each ticket type its capacity and the editor sizes new blocks to
+  it, refuses to go over, and offers to trim the surplus if the capacity goes down.
+- **Sold seats are safe** — pieces with sold or held seats can be moved, rotated or resized,
+  but never deleted, renumbered or reassigned.
+- **Buyer map (`<SeatMap />`, `<VenueOverview />`)** — the whole venue at a glance, tap a zone
+  or a section to pick it, zoom into a section to choose seats, clear free / yours / sold
+  states, screen-reader and keyboard friendly, built for touch.
+- **Server-side core** — the same validation runs on your server: schema, limits, unit IDs,
+  lock checks, capacity checks. No DOM, no React.
+
+## Install
+
+```bash
+npm install venuekit
+```
+
+`react` and `react-dom` ≥ 18 are peer dependencies, needed only for `venuekit/react`. The
+core (`venuekit`) has no DOM or React dependency.
+
+The package has two entry points:
+
+| Import | What | Where |
+| --- | --- | --- |
+| `venuekit` | Core: the plan format, validation, expansion to sellable units, locking, capacity. | Server and client |
+| `venuekit/react` | `<VenueDesigner />`, `<SeatMap />`, `<VenueOverview />`, messages and themes. Starts with `"use client"`. | Client |
+
+> **Language:** the built-in UI text defaults to Spanish (Argentina). Pass the English
+> messages shown in the examples (`designerEn`, `en`) or your own overrides.
+
+## Quick start
+
+### 1. Describe your ticket types
+
+Each ticket type that can be placed on the plan is a `PlaceTypeOption`:
+
+```ts
+import type { PlaceTypeOption } from "venuekit"
+
+const placeTypes: PlaceTypeOption[] = [
+  { ref: "orchestra", label: "Orchestra", color: "#e5482c", accepts: "seats", capacitySteps: [120] },
+  { ref: "boxes", label: "Boxes", color: "#f2b14c", accepts: "tableWhole" },
+  { ref: "floor", label: "Floor (standing)", color: "#3fc59a", accepts: "zone" },
+]
+```
+
+- `ref` — your ID for the ticket type. VenueKit stores it on each piece.
+- `accepts` — `"seats"` (numbered seats), `"tableWhole"` (a whole table or box is one
+  unit), `"tablePerPlace"` (each chair is a unit) or `"zone"` (a standing area sold by
+  quantity; drawing its zone is optional).
+- `capacitySteps` — optional. The cumulative capacity of the type's price tiers, in sale
+  order. Tiers of 30, 50 and 100 seats are `[30, 80, 180]`: the editor offers blocks of 30,
+  50 and 100, and caps the type at 180. Leave it out for no cap.
+
+### 2. Let organizers draw the plan
+
+```tsx
+"use client"
+import { useMemo, useState } from "react"
+import { migrate, rebindPlaceTypes, type Layout } from "venuekit"
+import { VenueDesigner, designerEn } from "venuekit/react"
+
+export function PlanEditor({ saved, soldOrHeld }: { saved: unknown; soldOrHeld: string[] }) {
+  // A new `layout` object means "load another plan": memoize it.
+  const initial = useMemo(() => (saved ? rebindPlaceTypes(migrate(saved), placeTypes) : null), [saved])
+  const locked = useMemo(() => new Set(soldOrHeld), [soldOrHeld])
+  const [draft, setDraft] = useState<Layout | null>(initial)
+
+  return (
+    // The editor fills its container: give the container a height.
+    <div style={{ height: "100dvh" }}>
+      <VenueDesigner
+        layout={initial}              // null = a blank plan named after `name`
+        name="Main theater"
+        placeTypes={placeTypes}
+        lockedUnitIds={locked}        // sold or held by anyone
+        onChange={setDraft}
+        onDone={async (layout) => { await savePlan(layout) }}   // the "Done" button
+        theme="dark"                  // "light" (default) or "dark"
+        background={{ onPick: uploadImageAndReturnUrl }}
+        messages={designerEn}
+      />
+    </div>
+  )
+}
+```
+
+### 3. Let buyers pick their seats
+
+```tsx
+"use client"
+import { useState } from "react"
+import type { Layout } from "venuekit"
+import { SeatMap, en } from "venuekit/react"
+
+export function ChooseSeats({ layout, taken }: { layout: Layout; taken: string[] }) {
+  const [selection, setSelection] = useState<string[]>([])
+  return (
+    <SeatMap
+      layout={layout}
+      placeTypes={[
+        { ref: "orchestra", label: "Orchestra", color: "#e5482c", priceLabel: "$40" },
+        { ref: "boxes", label: "Boxes", color: "#f2b14c", priceLabel: "$160" },
+      ]}
+      focusRef="orchestra"            // zoom into the section the buyer picked
+      takenUnitIds={taken}            // sold + held by other buyers
+      selection={selection}
+      onSelectionChange={setSelection}
+      maxSelection={6}
+      totalLabel="$80"                // preformatted: VenueKit never formats money
+      onContinue={() => checkout(selection)}
+      messages={en}
+    />
+  )
+}
+```
+
+Need the whole venue first? `<VenueOverview />` shows every section and zone and calls
+`onSelect(ref)` when the buyer taps one. See [Buyer map in a card](#buyer-map-in-a-card).
+
+### 4. Validate on the server
+
+Plans come from the browser: always validate before saving.
+
+```ts
+import { migrate, expand, findLockViolations, summarize, LayoutError, type Layout } from "venuekit"
+
+export function checkIncomingPlan(input: unknown, current: Layout | null, soldOrHeld: Set<string>) {
+  let next: Layout
+  try {
+    next = migrate(input)                     // schema + size limits; throws LayoutError
+  } catch (e) {
+    if (e instanceof LayoutError) return { ok: false as const, reason: e.message }
+    throw e
+  }
+  if (current && findLockViolations(current, next, soldOrHeld).length > 0) {
+    return { ok: false as const, reason: "The change would remove, renumber or reassign a sold seat." }
+  }
+  const units = expand(next)                  // every sellable unit with a stable ID
+  const perType = summarize(next).byRef       // per type: units, duplicated names…
+  return { ok: true as const, next, units, perType }
+}
+```
+
+## Core concepts
+
+**Plan (`Layout`).** A JSON document `{ meta, elements }`. `meta` holds `id`, `name`,
+`version`, `width`, `height` and an optional `background` image. `elements` are:
+
+| Element | What |
+| --- | --- |
+| `seatBlock` | Rows × seats, straight or curved, with its own row and seat numbering and removed seats. |
+| `table` | Round or rectangular, sold whole or per chair. |
+| `zone` | A standing-room area for a general-admission ticket, straight or curved. No units. |
+| `landmark` | A reference shape (stage, bar, restrooms, entrance…). Not for sale. |
+
+Each sellable piece may carry `placeType: { ref, name }` linking it to a ticket type.
+`ref: ""` means "unassigned, but remember the name", so a saved plan can be re-linked by name
+with `rebindPlaceTypes` when it is reused for another event.
+
+**Units.** `expand(layout)` returns every sellable unit with a stable ID: a seat is
+`"<block>:<row>:<seat>"`, a chair is `"<table>:<n>"`, a whole table is the table's ID.
+Moving, rotating or resizing a piece never changes IDs. Store these IDs in your inventory.
+
+**Locking.** Pass the IDs of sold or held units as `lockedUnitIds` to the editor. Pieces can
+still be moved, rotated, resized or curved, but anything that would delete a locked unit,
+change its label or move a label to a different physical seat (renumbering) is refused.
+`findLockViolations(before, after, locked)` runs the same check on the server.
+
+**Capacity.** With `capacitySteps`, the editor shows "30 of 100 spots", sizes new blocks to
+the next tier, blocks any edit that would exceed the cap and, if the cap goes down, shows
+how many spots are left over with an "Adjust" action that removes them from the end
+without touching locked units.
+
+**Limits.** Plans are untrusted input, so the schema has hard limits (exported as constants):
+`MAX_UNITS`, `MAX_ELEMENTS`, `MAX_ID_LENGTH`, `MAX_NAME_LENGTH`, `MAX_REF_LENGTH`,
+`MAX_TABLE_LABEL_LENGTH`, `MAX_SRC_LENGTH`, `MAX_SKIP`, `MAX_LETTERS_START`.
+
+## API
+
+### `venuekit` (core)
+
+| Export | Purpose |
+| --- | --- |
+| `migrate(input)` | Validates an external plan (schema and limits) and returns a `Layout`. Throws `LayoutError`. |
+| `layoutSchema`, `CURRENT_VERSION` | The zod schema and the current plan version. |
+| `expand(layout)` | Sellable units with stable IDs, positions and labels. |
+| `summarize(layout)` | Counts for the plan and per type: seats, tables, places, zones, and duplicated seat or table names. |
+| `findLockViolations(before, after, locked)` | Changes that would break sold or held units. |
+| `rebindPlaceTypes(layout, options)` | Re-links a saved plan to the current event's ticket types by name. |
+| `canAssign(piece, option)` | Whether a piece accepts a ticket type. |
+| `placeTypeCapacity`, `nextBlockUnits`, `capacityViolations` | Capacity helpers used by the editor. |
+| `landmarks`, `landmarkById` | The landmark catalog. |
+| `expandLabels`, `labelSequence`, `SPANISH_ALPHABET` | Row and seat numbering. |
+
+Types: `Layout`, `Element`, `SeatBlock`, `Table`, `Zone`, `Landmark`, `PlaceTypeOption`,
+`PlaceTypeAccepts`, `SellableUnit`, `PlanSummary`, `LockViolation`, `CapacityViolation`.
+
+### `<VenueDesigner />`
+
+| Prop | Type | |
+| --- | --- | --- |
+| `layout` | `Layout \| null` | The plan to edit; `null` starts a blank plan. A new object reloads the editor (memoize it); passing back what came from `onChange` is safe. |
+| `name` | `string` | Name for a blank plan. |
+| `placeTypes` | `PlaceTypeOption[]` | Ticket types that can be placed. They may change while the editor is open. |
+| `lockedUnitIds` | `ReadonlySet<string>` | Sold or held units. |
+| `onChange` | `(layout) => void` | Called on every change. |
+| `onDone` | `(layout) => void \| Promise<void>` | The "Done" button. Without it, a "Save" button calls `onSave`. |
+| `onClose` | `() => void` | The "Back" button (hidden without it). |
+| `background` | `{ onPick: () => Promise<string \| null>; suggestedSrc?: string \| null }` | You upload the image and return its URL. |
+| `sidePanel` | `(api: DesignerHostApi) => ReactNode` | Replaces the built-in ticket-type panel with your own (for example, ticket types with their prices). `api` offers `addPiece(kind, ref)`, `placed(ref)`, `nextPieceUnits(ref)`, `overCapacity(ref)`, `trimToCapacity(ref)`, `select(id)`, `reveal(id)`, `selectedRef`, `summary`… Keep the function stable (`useCallback`). |
+| `theme` | `"light" \| "dark"` | Default token values. |
+| `messages` | `DesignerOverrides` | `designerEn`, `designerEs`, or partial overrides via `mergeDesignerMessages`. |
+
+Gestures: drag to move; corner handles to resize; Shift/⌘/Ctrl-click or drag on empty space to
+multi-select; Space + drag, middle button or wheel to pan and zoom; Alt/Option disables
+snapping. On touch: drag pans, long-press and drag selects. Arrow keys move the selection.
+Below 768 px of container width the editor switches to bottom sheets.
+
+### `<SeatMap />`
+
+| Prop | Type | |
+| --- | --- | --- |
+| `layout` | `Layout` | |
+| `placeTypes` | `{ ref, label, color, priceLabel? }[]` | Pass every type on the plan; pieces of unknown types render muted. |
+| `focusRef` | `string` | The section the buyer is choosing in: the map zooms there and dims the rest. |
+| `takenUnitIds` | `string[]` | Sold, plus held by other buyers. |
+| `heldUnitIds` | `string[]` | Held for this buyer. |
+| `selection`, `onSelectionChange` | `string[]`, `(ids) => void` | Controlled selection. |
+| `maxSelection` | `number` | |
+| `conflictUnitIds` | `string[]` | IDs lost to another buyer (for example after a 409): marked sold and announced. |
+| `totalLabel`, `continueLabel`, `onContinue`, `holdMinutes` | | The bottom bar. |
+| `embedded`, `onBack`, `onFocusChange`, `height` | | For use inside a card (see below). |
+| `fill` | `boolean` | The map is the whole page. |
+| `messages` | `MessageOverrides` | `en`, `es`, or partial overrides via `mergeMessages`. |
+
+### `<VenueOverview />`
+
+The whole venue for buyers. Tapping a zone or any unit of a type calls `onSelect(ref)`.
+Props: `layout`, `placeTypes` (`{ ref, label, color, priceLabel?, available? }`; `available:
+false` shows "Sold out"), `onSelect`, `hideList`, `showHint`, `selectedRefs`,
+`takenUnitIds`, `selectedUnitIds`, `height`, `messages`.
+
+### Buyer map in a card
+
+```tsx
+{focus === null ? (
+  <VenueOverview
+    layout={layout}
+    placeTypes={types}
+    onSelect={(ref) => (isZone(ref) ? addOneTicket(ref) : setFocus(ref))}
+    hideList
+    showHint
+    takenUnitIds={taken}
+    selectedUnitIds={selection}
+    messages={en}
+  />
+) : (
+  <SeatMap
+    embedded
+    onBack={() => setFocus(null)}
+    onFocusChange={setFocus}
+    layout={layout}
+    placeTypes={types}
+    focusRef={focus}
+    takenUnitIds={taken}
+    selection={selection}
+    onSelectionChange={setSelection}
+    messages={en}
+  />
+)}
+```
+
+## Theming
+
+Everything is styled with CSS custom properties on `.vk-root`, declared with `:where()` so
+any rule of yours wins: `--vk-accent`, `--vk-bg`, `--vk-fg`, `--vk-line`, `--vk-muted`,
+`--vk-surface`, `--vk-radius`, `--vk-font`… The buyer map adds `--vk-mine`, `--vk-sold`,
+`--vk-unit-fg`, `--vk-landmark`…; the editor adds `--vk-panel`, `--vk-canvas`,
+`--vk-primary-bg` and more. Set `--vk-font` to your app's font.
+
+## What your app is responsible for
+
+VenueKit draws and validates plans. It does not know about money or orders. Your app:
+
+- stores plans and ticket types, and uploads background images;
+- formats prices (`priceLabel`, `totalLabel`);
+- tracks sold and held units, passes them to the editor and the map, and re-checks
+  `findLockViolations` on the server before saving a plan;
+- holds seats during checkout and resolves conflicts between buyers;
+- refuses to publish a plan with duplicated seat names (`summarize(layout).byRef[ref].duplicates`).
+
+## Development
+
+Requires Node ≥ 20.
+
+```bash
+npm install
+npm test                   # unit tests (Vitest)
+npm run typecheck
+npm run build              # builds packages/venuekit/dist
+npm run dev -w playground  # http://localhost:5173 (/ buyer map, /?designer editor)
+npx playwright install chromium webkit   # once
+npm run test:e2e           # browser tests (desktop and mobile)
+```
+
+`packages/core`, `packages/canvas` and `packages/react` are internal; `packages/venuekit`
+bundles them into the published package. A Spanish reference with every detail lives in
+[`docs/reference.es.md`](./docs/reference.es.md).
+
+## License
+
+[MIT](./LICENSE) © Juan Cruz Fernández