@kerros/schema 0.0.0-stage → 0.1.0-rc.1

package/dist/types/model/vertical.d.ts

@@ -0,0 +1,145 @@
+import type { Floor, Point, ProjectDocument, Ring, SiteObject } from './types';
+/** True for the kinds that connect levels. */
+export declare const isVertical: (kind: string) => kind is "elevator" | "stairs";
+/** Which shaft this object is part of.
+ *
+ *  A shaft is one thing standing in one place reaching several levels, and that is how the document
+ *  can describe it: one object, one position, one `servedFloorIds`. Older documents — the demo among
+ *  them — instead repeat the object on every storey it serves, because that is what you had to do
+ *  before anything read the served list. Both must draw as one lift, so a shaft is identified by what
+ *  makes it the same shaft: its kind, its name, and where it stands. */
+export declare const shaftKey: (object: SiteObject) => string;
+/** Every level this shaft reaches, lowest first.
+ *
+ *  `servedFloorIds` when it is authored — that is the document's own statement and outranks any
+ *  inference. A shaft that declares nothing serves the floor it stands on and no other: better to
+ *  draw a stair going nowhere, which is visibly wrong and easy to fix, than to invent a connection
+ *  that routing would then happily send someone through. */
+export declare function servedFloors(project: ProjectDocument, object: SiteObject): Floor[];
+/** One climb between two levels the shaft serves. */
+export interface Flight {
+    from: Floor;
+    to: Floor;
+    /** Metres climbed, always positive. */
+    rise: number;
+}
+/** The climbs this shaft makes, bottom first.
+ *
+ *  Consecutive served levels, so a stair serving 0-1-2 makes two flights and a lift serving the same
+ *  three makes two hops of shaft. A level in between that the shaft passes without stopping is simply
+ *  not in the list, and the flight spanning it is the taller for it — which is the right picture: an
+ *  express lift's shaft does pass those floors, and a spiral stair's helix does wind past a mezzanine
+ *  it has no landing on. */
+export declare function flights(project: ProjectDocument, object: SiteObject): Flight[];
+/** Does this shaft reach the given level? Includes the floor it is filed under. */
+export declare const reaches: (project: ProjectDocument, object: SiteObject, floorId: string | null) => boolean;
+/** The flight arriving at a level from below, and the one leaving it upward — what you would see
+ *  standing on that level. Either may be absent at the ends of the run. */
+export declare function flightsAt(project: ProjectDocument, object: SiteObject, floorId: string | null): {
+    up?: Flight;
+    down?: Flight;
+};
+/** How far a shaft's body runs, as absolute elevations: the lowest level it serves to the highest.
+ *  Null when it serves fewer than two levels and so has no body to speak of. */
+export declare function span(project: ProjectDocument, object: SiteObject): {
+    bottom: number;
+    top: number;
+} | null;
+/** The angle a flight of this kind wants to climb at, in degrees from horizontal.
+ *
+ *  An escalator is a machine built to one geometry: 30°, the world over. A stair is free-er but a
+ *  comfortable flight is around 32°, and anything past about 42° is a ladder. These are what the
+ *  plan should be *checked against* — the footprint stays the truth of where the thing is — so a run
+ *  too short for its rise reads as the steep slope it would really be. */
+export declare const PITCH: {
+    readonly escalator: 30;
+    readonly stairs: 32;
+};
+/** The run a flight of this rise needs to climb at its natural pitch. Use it to size a shaft the
+ *  drawing has not sized, and to tell whether one it has sized is plausible. */
+export declare const runFor: (rise: number, pitch?: number) => number;
+/** The pitch a flight actually climbs at, given the run the plan gives it. */
+export declare const pitchOf: (rise: number, run: number) => number;
+/** The deepest tread that is still a tread. Past about a third of a metre a flight stops being a
+ *  stair: the going grows with the box while the rise per step does not, and what you get is a ramp
+ *  with slabs laid on it. A box longer than the climb needs keeps its length — the surplus is
+ *  landing, which is what that spare floor really is. */
+export declare const MAX_GOING = 0.32;
+/** The treads one flight of this rise gets, and how deep each is in a run of this length. Capped
+ *  both ways: a handful of boxes reads as a stair, two hundred reads as a stair and costs a level. */
+export declare function treads(rise: number, run: number): {
+    steps: number;
+    going: number;
+};
+export type StairModel = NonNullable<SiteObject['stairModel']>;
+/** How a shaft is built — as the document says, or as its own footprint implies.
+ *
+ *  A footprint that cannot take the rise at a civil pitch is describing a stair that turns, which is
+ *  what a short wide core box always is. Both the renderer and the plate it cuts its hole in have to
+ *  agree about that, so the reading lives here rather than in either of them. */
+export declare function stairModel(project: ProjectDocument, object: SiteObject): StairModel;
+/** A bank of escalators is stacked criss-cross: every other flight runs the other way, so you step
+ *  off one and turn to step onto the next. Which way round a given flight is decides which end of
+ *  the footprint it arrives at, and so which end of it the floor above has to be open. */
+export declare const flightReversed: (model: StairModel, index: number) => boolean;
+/** Where one flight's sloping part actually lies inside the box the plan drew.
+ *
+ *  The plan gives a footprint; the climb is what has to fit in it. An escalator keeps a metre of flat
+ *  comb plate at each end and then climbs at the machine's own 30°, so a box with run to spare gets a
+ *  longer landing at its foot instead of a shallower ramp — a 1.6 m rise in a 12 m box is a stair with
+ *  a lot of floor round it, not a slide. A stair's treads are capped at MAX_GOING for the same reason.
+ *  A box too short for its rise is left alone: it really is that steep and the picture should say so.
+ *
+ *  `t` runs along the object's depth axis from its centre. The foot of a flight is at +depth/2 and its
+ *  head at -depth/2, which is how the renderer has always laid one out; the surplus goes to whichever
+ *  end that leaves free — the foot of an escalator, whose comb plates must stay at the ends the plan
+ *  drew them at, and the head of a stair, which has none. */
+export interface FlightRun {
+    /** The rotation this flight is drawn at — see flightReversed. */
+    rotation: number;
+    /** A point t metres along the run from the object's centre. */
+    at: (t: number) => Point;
+    /** How long the box is along that axis, and half of it. */
+    length: number;
+    half: number;
+    /** The flat plate at each end of an escalator; zero for a stair. */
+    pad: number;
+    /** The sloping part: how long it is, and where it starts and ends along the run. */
+    incline: number;
+    topT: number;
+    footT: number;
+}
+export declare function flightRun(project: ProjectDocument, object: SiteObject, rise: number, model: StairModel, index?: number): FlightRun;
+/** The one twin that stands for the shaft: the lowest, so the flights count upward from the bottom.
+ *  A shaft described the modern way — one object — is trivially its own primary. */
+export declare function primaryShafts(project: ProjectDocument): Set<string>;
+/** Does something come up through this level's floor? The shaft starts below it and reaches it or
+ *  goes past — so a flight arrives here and the plate it arrives through has to be open.
+ *
+ *  This is one half of what `passesThrough` used to answer for both. Requiring a served level above
+ *  as well meant the flight arriving at the top of a run was drawn under an uncut slab: on Stockmann's
+ *  ninth floor all twelve shafts arrive and not one of them cut a hole, so the last flight of every
+ *  stair in the building was invisible from the storey it lands on. */
+export declare function arrivesAt(project: ProjectDocument, object: SiteObject, floorId: string): boolean;
+/** The other half: does something climb out through this level's ceiling? The shaft stands on this
+ *  level or lower and carries on above it, so the lid a walked storey gets has to be open over it —
+ *  which the bottom of a run needs just as much as the middle of one. */
+export declare function departsFrom(project: ProjectDocument, object: SiteObject, floorId: string): boolean;
+/** Does this shaft pass THROUGH a level — arriving from below and carrying on above? Both halves at
+ *  once, which is the question a level in the middle of a run answers yes to and no end of one does. */
+export declare const passesThrough: (project: ProjectDocument, object: SiteObject, floorId: string) => boolean;
+export interface VoidOptions {
+    /** `floor` (the default) cuts what arrives from below; `ceiling` cuts what departs upward. */
+    through?: 'floor' | 'ceiling';
+    /** Ignore flights that set off below this elevation. An above-ground view draws nothing under
+     *  grade, and a hole with nothing beneath it is worse than no hole at all. */
+    lowest?: number;
+}
+/** What to cut out of a level's floor plate, or out of the lid over a walked storey.
+ *
+ *  A stairwell is a hole. Drawing the slab whole and the stair beneath it puts a lid over the flight,
+ *  so from the landing above you see a plate where the opening should be and the stair appears to
+ *  climb into the ceiling. The hole is only as big as the flight needs, though: a lift or a turning
+ *  core is a shaft and takes its whole footprint, but a straight flight or an escalator lies under
+ *  the floor for most of its length and wants opening only where it comes up — see headroomBand. */
+export declare function shaftVoids(project: ProjectDocument, floorId: string, primary?: Set<string>, options?: VoidOptions): Ring[];

package/dist/types/schema/index.d.ts

@@ -0,0 +1,25 @@
+export type { ProjectDocument, ProjectSummary, Building, BuildingRoof, RoofSection, Floor, InteriorLight, LightFixture, Junction, VirtualBoundary, BoundaryUse, SpaceGeometry, Barrier, SiteObject, Drawing, Origin, Point, Ring, ObjectKind, Slope, MaterialKind, ModelKind, AssetRepository, NavNode, NavEdge, NavEdgeKind, Zone, Portal, PortalGroup, } from '../model/types';
+export { spaces, spaceAt, spacePoint, inSpace } from '../model/spaces';
+export { entryInto, perimeter, captive, zoneSpaces, addZone, removeZone, setZoneMembers, nestZone, addPortalGroup, removePortalGroup, setPortalGroupMembers, pruneOntology, } from '../model/ontology';
+export { inferPortals, inferOpenBoundaries, refreshPortals, divideSpaces, spacesDividedBy, spacesRejoinedBy, mergeSpaces, } from '../model/inference';
+export { derivedGraph } from '../model/topology';
+export { sharedBoundaryPortals, effectivePortals } from '../model/portals';
+export { isArea, isDevice, isOpening, isSpace, uid, OBJECT_KINDS } from '../model/types';
+export { createObject, emptyProject } from '../model/factory';
+export { enclosedRegion, enclosedRegions, refitEnclosedRooms } from '../model/spaces';
+export { boundaryEdges, boundaryRegions, boundaryRegionAt, boundaryRings, derivedSpaceRings, bindSpaceToRegion, followsBoundaries, connectSpace, disconnectSpace, addVirtualBoundary, drawVirtualBoundary, addBoundaryHole, normalizeBoundaries, refreshBoundarySpaces, } from '../model/boundaries';
+export type { BoundaryEdge, BoundaryRegion } from '../model/boundaries';
+export { coverageOf, DEFAULT_RANGE, DEFAULT_FOV } from '../model/coverage';
+export { copyProject, openingFloorId } from '../model/project';
+export { MIN_SEGMENT, OPENING_MIN_SEGMENT, geoOrigin, moveOrigin, segmentsCross, toLngLat, toLocal, addBarrier, duplicateFloor, removeFloor, rectangle, rotate, centroid, distance, footprint, closeRing, openRing, ringArea, objectArea, pointInRing, objectPosition, objectRotation, barrierEnds, segmentProjection, slopeElevation, } from '../model/geometry';
+export { exportProject, importProject, parseExport, blobDataUrl } from '../model/document';
+export { validateProject, validateRelationships, validateRings, validateNavigation, transact, freezeProject, COORD_LIMIT, } from '../model/validate';
+export type { TransactResult } from '../model/validate';
+export { applyMutation, applyMutations } from '../model/mutations';
+export type { Mutation, MutationOutcome, MutationResult } from '../model/mutations';
+export { findRoute, navNodes, navEdges, HERE, routeSteps, routeAnchors, floorPhrase, addNavNode, addNavEdge, navPath, chainVertical, edgeCost, edgeLength, ELEVATOR_BASE, ELEVATOR_PER_METRE, STAIR_CLIMB_FACTOR, DOOR_COST, NAV_WELD, } from '../model/navigation';
+export type { Route, RouteStep, RouteLeg, RouteOptions, RouteEnd, RoutePlace } from '../model/navigation';
+export { EXTERIOR_PRESETS, type ExteriorPreset } from '../model/materials';
+export { flights, flightsAt, isVertical, passesThrough, PITCH, pitchOf, primaryShafts, reaches, runFor, servedFloors, shaftKey, shaftVoids, span, type Flight, } from '../model/vertical';
+export { buildRoomNavigation } from '../model/roomNavigation';
+export type { RoomAccess, RoomNavigationGraph } from '../model/roomNavigation';

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@kerros/schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.1",
+  "description": "Kerros floor-plan project schema: types, validation, portable import/export and indoor-navigation routing. Pure functions \u2014 no React, no rendering.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kherrala/kerros.git",
+    "directory": "packages/schema"
+  },
+  "homepage": "https://github.com/kherrala/kerros#readme",
+  "bugs": "https://github.com/kherrala/kerros/issues",
+  "keywords": ["floor-plan", "indoor-mapping", "routing", "typescript"],
+  "module": "./dist/index.js",
+  "types": "./dist/types/schema/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/schema/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.dts.json",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}