narraleaf-react 0.39.2 → 0.40.1

package/dist/game/player/elements/player/stageClickIntent.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What a click that landed on the stage is asking for.
+ *
+ * The stage announcer decides *whether* a click belongs to the stage at all - it is over the player,
+ * it is not inside a menu, a notification, a page or a word that takes its own clicks. This decides
+ * what the ones that survive that walk actually mean, and it is kept apart from the walk because the
+ * walk is DOM and this is not: the rules below are the ones worth pinning, and pinning them needs no
+ * document.
+ *
+ * Comments in English per project convention.
+ */
+/**
+ * The three things a click on the stage can mean.
+ *
+ * - `advance` - settle the line, the ordinary case.
+ * - `restoreDialog` - bring the dialog box back, because it has been put away.
+ * - `ignore` - the click reached nothing that wants it.
+ */
+export type StageClickIntent = "advance" | "restoreDialog" | "ignore";
+export type StageClickInput = {
+    /**
+     * Whether the announcer's DOM walk decided this click belongs to the stage rather than to
+     * something drawn on it.
+     */
+    onStage: boolean;
+    /**
+     * The `showDialog` preference: `false` means the player has put the box away to look at the
+     * picture behind it.
+     */
+    dialogShown: boolean;
+    /** Whether anything is currently holding the line - see `GameState.suspendAdvance`. */
+    advanceSuspended: boolean;
+};
+/**
+ * Decide what one click on the stage means.
+ *
+ * Two rules, in the order they are asked:
+ *
+ * - **A click with the box put away brings it back; it does not spend a line.** The box is the thing
+ *   a click on the stage acts on, so with the box gone there is nothing on screen the click could
+ *   have been aimed at - and the line it would have settled is one the player never saw. Every
+ *   visual novel treats the next click after a hide as the one that undoes the hide, which is also
+ *   the only reading that cannot lose text.
+ * - **That outranks a hold on the line.** A suspension is a hold on *advancing*, taken by something
+ *   drawn over a line that wants the player's attention first - a definition popup on an inline
+ *   word. Everything that takes one is drawn inside the box, so while the box is away the hold is
+ *   invisible; leaving it in charge would mean a player who put the box away had no way to bring it
+ *   back and no way to reach the thing holding the line either. Restoring the box does not settle
+ *   the line, so it takes nothing away from whatever holds it: the hold is still there, and still
+ *   in charge, the moment the box is back.
+ */
+export declare function resolveStageClickIntent({ onStage, dialogShown, advanceSuspended, }: StageClickInput): StageClickIntent;

package/dist/game/player/elements/say/dialogVisibility.d.ts

@@ -0,0 +1,42 @@
+/**
+ * How a dialog box that has been put away is hidden.
+ *
+ * Hiding the box is how a player looks at the picture behind it; it is not the box going away. The
+ * box keeps its line, its typing task, its animations and - the part this file exists for - its
+ * place in hit testing, because whatever a game has drawn inside the box is still a thing the player
+ * can be reaching for. The engine's own UI has nothing in there, but a host that renders its own
+ * dialog into this box does, and that content is the only route it has to the pointer.
+ *
+ * Comments in English per project convention.
+ */
+export type DialogVisibility = {
+    /** The class the box carries while in this state, or an empty string for none. */
+    className: string;
+    /** Whether the box should be hidden from assistive technology. */
+    ariaHidden: boolean;
+};
+/**
+ * Decide how a box in the given `showDialog` state is presented.
+ *
+ * **Not `visibility: hidden`, and not `display: none`.** Both take the whole subtree out of hit
+ * testing, which is a different statement from "do not draw this": with either of them the box is
+ * not merely invisible, it is unreachable, and so is everything a host has rendered inside it. The
+ * box used to be hidden that way while also asking for `pointer-events: auto` on the same element -
+ * two instructions that cannot both be followed, and the one that lost is the one that was meant.
+ * What it cost: a panel inside the box could not be scrolled, tapped or dismissed while the box was
+ * away, and nothing said why, because the elements were all still there and all still styled to
+ * receive the pointer.
+ *
+ * Transparency says only "do not draw this", which is what hiding the box means. It costs a stacking
+ * context, which this element already has wherever the stage is scaled to fit, and it leaves the box
+ * in the accessibility tree - so a hidden box is marked `aria-hidden` here rather than relying on a
+ * side effect of how it is drawn.
+ *
+ * **No `pointer-events` of its own, in either state.** Whether a box is reachable at all is its
+ * layer's to say, not the box's: a scene parked behind a returnable jump keeps a layer that covers
+ * the stage with nothing in it, and that layer turns the pointer off for everything inside it. A box
+ * asserting `pointer-events: auto` would overrule that and go back to swallowing the clicks meant
+ * for the scene in front of it. The old hidden state did assert it, which was harmless only because
+ * it was paired with a rule that removed the box from hit testing anyway.
+ */
+export declare function resolveDialogVisibility(shown: boolean): DialogVisibility;