@pie-element/venn-classification 0.1.1-next.6 → 0.1.1-next.8

package/dist/delivery/layout.d.ts

@@ -1,30 +1,66 @@
 /**
  * 2-set Venn layout + hit-testing helpers.
  *
- * Geometry lives in SVG viewBox coordinates so the delivery component can
- * render on any responsive size; the layout returns per-region descriptors
- * (label, hitRect for the rectangular drop-zone highlight, `pointInRegion`
- * for pointer hit-testing, and a `gridSlot` function for neatly placing
- * multiple tiles in the same region).
+ * Geometry lives in SVG viewBox coordinates. At the base size one unit is one
+ * CSS px when the diagram renders at `DIAGRAM_MAX_WIDTH_PX`; the delivery
+ * component scales everything, placed tiles included, with the rendered width.
+ * The layout returns per-region descriptors: label, `hitRect` (a rectangle
+ * inside the region, used for the 120×120 drop-target minimum from the PRD and
+ * to anchor the region's accessible element), `pointInRegion` for pointer
+ * hit-testing, and `slots` for placing tiles on a grid fitted to the region's
+ * shape.
  *
  * The diagram rectangle IS the universal set: circles live in the upper
  * portion, and the "outside" region is everything inside the rect that
- * doesn't fall inside a circle. Outside-region tiles land in the bottom
- * strip (below the circles, still inside the rect) where there's room for
- * a horizontal row of tiles — that strip is what `hitRect` for the outside
- * region describes (used for the drop-highlight overlay and the 120×120
- * a11y minimum from the PRD). `pointInRegion` for outside is the broader
- * "inside rect, not in any circle" check, so the learner can drop anywhere
- * around the circles naturally.
+ * doesn't fall inside a circle. Outside-region tiles land in the bottom strip
+ * (below the circles, still inside the rect). `pointInRegion` for outside is
+ * the broader "inside rect, not in any circle" check, so the learner can drop
+ * anywhere around the circles naturally.
+ *
+ * Every slot keeps its whole tile cell, plus `REGION_MARGIN`, inside its
+ * region, and no two cells of one region overlap. A region holds a fixed number
+ * of cells for a given geometry; `fitGeometry2Set` grows the geometry until each
+ * region holds the tiles placed in it.
  */
 import type { Region, VennCircle, VennModel } from '../types.js';
 import { enumerateRegions, getRegionLabel, regionKey } from '../controller/region.js';
+/** A placed tile's grid cell, in viewBox units. */
+export interface TileCell {
+    w: number;
+    h: number;
+}
+/** Cell of a text (or math) tile: two lines of label. */
+export declare const TEXT_TILE_CELL: TileCell;
+/** Cell of a tile with an image and a one-line caption. */
+export declare const IMAGE_TILE_CELL: TileCell;
+/** Space between neighbouring cells. */
+export declare const TILE_GAP = 8;
+/** Clearance between a cell and its region's edge; the circle stroke is 2 wide. */
+export declare const REGION_MARGIN = 6;
+/** CSS max width of the diagram. */
+export declare const DIAGRAM_MAX_WIDTH_PX = 720;
+/** Share of the viewport height the diagram may take, so the tray stays in view. */
+export declare const DIAGRAM_MAX_VIEWPORT_HEIGHT = 0.6;
+/** The PRD's minimum tile hit target, in CSS px. */
+export declare const MIN_TILE_PX = 44;
+/**
+ * Placed tiles shrink with the diagram down to this factor of their cell,
+ * which keeps the cell's shorter side at `MIN_TILE_PX`. A diagram rendered at
+ * less than this factor of its viewBox width draws its tiles larger than their
+ * cells.
+ */
+export declare function minTileScale(cell: TileCell): number;
 export interface DiagramGeometry {
     width: number;
     height: number;
+    /**
+     * Size of the diagram chrome (labels, strokes, margins) relative to the base
+     * geometry. Tile cells do not grow with it.
+     */
+    scale: number;
     /** Vertical gap between the bottom of the circles and the outside landing strip. */
     outsideGap: number;
-    /** Minimum height reserved below the circles for outside tiles. */
+    /** Height reserved below the circles for outside tiles. */
     outsideStripHeight: number;
     circles: Array<{
         cx: number;
@@ -32,27 +68,37 @@ export interface DiagramGeometry {
         r: number;
     }>;
 }
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
 export interface RegionLayout {
     region: Region;
     key: string;
     label: string;
-    /** Rectangular drop-zone bounds in viewBox coords. Used for highlight + keyboard focus rect. */
-    hitRect: {
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    };
+    /** A rectangle inside the region, in viewBox coords: the guaranteed drop target. */
+    hitRect: Rect;
     /** True iff `(x, y)` falls in this region, given the geometry. */
     pointInRegion: (x: number, y: number) => boolean;
-    /** Return the (x, y) center where tile `index` should land within this region. */
-    gridSlot: (index: number, tileWidth: number, tileHeight: number) => {
-        x: number;
-        y: number;
-    };
+    /** How many cells the region holds. */
+    capacity: number;
+    /**
+     * Cell centers for `count` tiles in this region, in reading order. Past
+     * `capacity` (a geometry `fitGeometry2Set` did not size for the count) the
+     * extra tiles share the last cell, or the middle of `hitRect` in a region
+     * too small for one.
+     */
+    slots: (count: number) => Point[];
 }
 export interface DiagramLayout {
     geometry: DiagramGeometry;
+    cell: TileCell;
     regions: RegionLayout[];
     regionByKey: Record<string, RegionLayout>;
     /**
@@ -62,21 +108,45 @@ export interface DiagramLayout {
     outsideStripTop: number;
 }
 /**
- * Default 2-set geometry. The entire rectangle is the "universal set":
- * circles occupy the top portion, and the outside strip beneath them is
- * where outside-region tiles land. Tuned so each region's `hitRect` clears
- * the 120×120 minimum hit-target from the PRD:
- *   left-only   ≈ 230 × 340
- *   right-only  ≈ 230 × 340
- *   overlap     ≈ 120 × 340
- *   outside     = 900 × 140 strip at the bottom of the rect
+ * The 2-set geometry at `scale` times the base size, with an outside strip at
+ * least `outsideStripHeight` tall. The base holds a 120×120 CSS px square in
+ * each region at the 720 px max width:
+ *   left-only / right-only  ≈ 182 × 182 around the circle's center line
+ *   overlap                 ≈ 235 × 235
+ *   outside                 = 720 × 136 strip at the bottom of the rect
  */
+export declare function geometry2Set(scale?: number, outsideStripHeight?: number): DiagramGeometry;
+/** The base 2-set geometry. */
 export declare function defaultGeometry2Set(): DiagramGeometry;
+/**
+ * The diagram's CSS width: `DIAGRAM_MAX_WIDTH_PX`, or less where the height
+ * would pass `DIAGRAM_MAX_VIEWPORT_HEIGHT` of the viewport. It never drops
+ * below the width that draws `cell` tiles at `minTileScale`, where each tile
+ * exactly fills its cell at the 44 px minimum; a crowded region can push that
+ * past the max width. Only a narrower container renders it smaller, and there
+ * tiles outgrow their cells. The aspect ratio sets the height, so the box
+ * matches the viewBox: tile positions and pointer hits map onto the box, and a
+ * letterboxed drawing would leave them off the circles.
+ */
+export declare function diagramCssWidth(geometry: DiagramGeometry, cell: TileCell): string;
+/**
+ * Scale for placed tiles when the diagram renders `renderedWidth` CSS px wide:
+ * each tile stays the size of its cell, down to `minTileScale(cell)`.
+ * Unmeasured (0) renders at full size.
+ */
+export declare function placedTileScale(renderedWidth: number, geometry: DiagramGeometry, cell: TileCell): number;
+/**
+ * The smallest geometry holding `counts[key]` tiles of `cell` in each region:
+ * the diagram grows in `SCALE_STEP`s while a circle region is short of cells,
+ * and the outside strip adds rows for the outside tiles. Tile cells keep their
+ * size, so a grown diagram renders them smaller at the same CSS width.
+ */
+export declare function fitGeometry2Set(counts: Record<string, number>, cell?: TileCell): DiagramGeometry;
 /**
  * Build the 2-set layout for a concrete model (uses model circle labels to
  * compose accessible names, and `model.regionLabels` for overrides).
  */
-export declare function buildLayout2Set(model: Pick<VennModel, 'circles' | 'regionLabels'>, geometry?: DiagramGeometry): DiagramLayout;
+export declare function buildLayout2Set(model: Pick<VennModel, 'circles' | 'regionLabels' | 'language'>, geometry?: DiagramGeometry, cell?: TileCell): DiagramLayout;
 /**
  * Resolve a pointer hit to its region. `pointer` is in viewBox coords.
  * Returns the matched region's descriptor, or `null` for "no region".

package/dist/delivery/tile-accessible-name.d.ts

@@ -1,4 +1,16 @@
 import type { VennTile } from '../types.js';
 export declare function stripHtml(s: string): string;
 /** Accessible name for a tile (button aria-label, live-region announcements). */
-export declare function tileAccessibleName(tile: Pick<VennTile, 'label' | 'imageUrl' | 'imageAlt'>): string;
+export declare function tileAccessibleName(tile: Pick<VennTile, 'label' | 'imageUrl' | 'imageAlt'>, language?: string): string;
+export type TileVerdict = 'correct' | 'incorrect' | 'unanswered';
+/**
+ * A tile button's accessible name: what it is, where it sits, and in `evaluate`
+ * mode whether that is right - "Crocodile, in Reptile and Egg-layer, incorrect".
+ * The placed tiles render in a layer apart from the region anchors, and the
+ * verdict badge is an `aria-hidden` icon, so the name is where assistive
+ * technology learns both.
+ *
+ * `regionLabel` is `null` for a tile in the tray. An unplaced tile's verdict is
+ * `unanswered`, which "not placed" already says.
+ */
+export declare function tileStatusName(tile: Pick<VennTile, 'label' | 'imageUrl' | 'imageAlt'>, regionLabel: string | null, verdict?: TileVerdict | null, language?: string): string;

package/dist/i18n.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A learner-facing string in `language`, the model's `language`. i18next falls
+ * back to English for a language or key it does not hold. Values are not
+ * HTML-escaped: they are circle and tile names, and Svelte escapes what it
+ * renders.
+ */
+export declare function t(key: string, language?: string, values?: Record<string, unknown>): string;
+/** A string shared across elements, such as the correct-answer toggle's labels. */
+export declare function tCommon(key: string, language?: string): string;