forgebook 0.2.0 → 0.3.0

package/dist/src/catalogue.js

@@ -120,6 +120,47 @@ const namedGroups = (lists) => ({
     storyGroups: lists.storyGroups ?? [],
     propGroups: lists.propGroups ?? []
 });
+/**
+ * Whether a catalogue checks accessibility: unless its lists say `a11y: false`.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+export const checksA11y = (lists) => lists.a11y !== false;
+/**
+ * Whether a catalogue reads its components' docs from their types: unless its lists say `componentDocs: false`.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+export const readsComponentDocs = (lists) => lists.componentDocs !== false;
+/**
+ * Whether a catalogue offers "Used in": unless its lists turn it off, or turn off the component docs, whose
+ * TypeScript programs read the import graph it is joined from.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+export const offersUsedIn = (lists) => lists.usedIn !== false && readsComponentDocs(lists);
+/**
+ * The panel's tabs a catalogue shows: Forgebook's then its plugins', less those it turns off, and the Accessibility
+ * tab when it checks nothing.
+ *
+ * @param lists - the lists its configuration sets.
+ * @param pluginTabs - the ids of the tabs its plugins add.
+ */
+const shownTabs = (lists, pluginTabs) => {
+    const tabsOff = lists.tabs ?? {};
+    const hasA11y = checksA11y(lists);
+    return [...PANEL_TAB_IDS, ...pluginTabs].filter((tab) => tabsOff[tab] !== false && (hasA11y || tab !== "a11y"));
+};
+/**
+ * A catalogue's accessibility rules, the defaults filled in; none when it checks nothing.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+const a11ySettings = (lists) => {
+    if (lists.a11y === false)
+        return undefined;
+    return { tags: lists.a11y?.tags ?? DEFAULT_A11Y_TAGS, disabledRules: lists.a11y?.disabledRules ?? [] };
+};
 /**
  * A catalogue's settings, its lists' defaults filled in.
  *
@@ -136,7 +177,6 @@ export const catalogueSettings = (title, switches, lists = {}, pluginTabs = [])
     const offered = builtIn === false
         ? []
         : BUILT_IN_BACKDROPS.filter((backdrop) => builtIn === undefined || builtIn.includes(backdrop.id));
-    const tabsOff = lists.tabs ?? {};
     const controlsOff = lists.controls ?? {};
     const ownControls = OWN_CONTROL_IDS.filter((control) => controlsOff[control] !== false);
     const named = lists.toolbar ?? defaultToolbar(switches, ownControls);
@@ -154,23 +194,22 @@ export const catalogueSettings = (title, switches, lists = {}, pluginTabs = [])
         textSizes: withHundred(lists.textSizes, [100, 125, 150]),
         backdrops: [...offered, ...(lists.backgrounds?.custom ?? []).map(customBackdrop)],
         ...namedGroups(lists),
-        tabs: [...PANEL_TAB_IDS, ...pluginTabs].filter((tab) => tabsOff[tab] !== false),
-        a11y: {
-            tags: lists.a11y?.tags ?? DEFAULT_A11Y_TAGS,
-            disabledRules: lists.a11y?.disabledRules ?? []
-        },
+        tabs: shownTabs(lists, pluginTabs),
+        a11y: a11ySettings(lists),
+        hasComponentDocs: readsComponentDocs(lists),
         gridStep: lists.gridStep ?? 8,
         strings: lists.strings ?? {},
         ownControls,
         toolbar,
-        hasUsedIn: lists.usedIn !== false,
+        hasUsedIn: offersUsedIn(lists),
         audience,
         hasEmbed: controlsOff.embed !== false,
         appearance: lists.appearance ?? "system",
         keys: usableKeys([...switches.map((each) => each.id), ...ownControls], lists.keys),
         views: catalogueViews(switches, lists.views),
         // checked when the configuration loads (`configFile.ts`): a model that is none is left out here
-        device: deviceDefaultOf(NO_DEVICE, lists.device)
+        device: deviceDefaultOf(NO_DEVICE, lists.device),
+        requiredFirst: lists.requiredFirst ?? "in-groups"
     };
 };
 /**

package/dist/src/frame/mountFrame.js

@@ -28,8 +28,7 @@ import { fixedViewOf, NOT_FIXED, withFixed } from "../storyGlobals.js";
 import { shownTexts, storyTextKeysOf, withStoryTexts } from "../storyTexts.js";
 import { findStory, storyTree } from "../storyTree.js";
 import { catalogueSwitches } from "../switches.js";
-import { codeGlobalsOf, frameAddress, languageOf, parseView } from "../viewState.js";
-import { checkStory } from "./checkStory.js";
+import { codeGlobalsOf, frameAddress, isSameLiveView, languageOf, liveView, parseView } from "../viewState.js";
 import { followTouch } from "./followTouch.js";
 import { storyFrameClock } from "./frameClock.js";
 import { FRAME_STARTED_ATTRIBUTE, STATUS_ATTRIBUTE } from "./frameStatus.js";
@@ -61,7 +60,7 @@ import.meta.hot?.on("vite:afterUpdate", () => {
  * @param message - the message.
  * @param controls - the rendered story's controls.
  * @param storyId - the story's id, for the answers.
- * @param rules - the catalogue's accessibility rules, for a check.
+ * @param rules - the catalogue's accessibility rules, for a check; none when it checks no accessibility.
  * @param axeUrl - the address of axe's script, for a check.
  * @param tellShell - tells the shell the check's result.
  */
@@ -81,7 +80,12 @@ const answerShell = (message, controls, storyId, rules, axeUrl, tellShell) => {
     else if (message.type === "forgebook:clock-restart")
         controls.restartClock();
     else if (message.type === "forgebook:check") {
-        checkStory(document, rules, axeUrl)
+        // loaded on the first check: a frame that is never checked, or one of a catalogue that checks nothing, never
+        // fetches the code that loads axe
+        const checked = rules === undefined
+            ? Promise.reject(new Error("The catalogue checks no accessibility (a11y: false)"))
+            : import("./checkStory.js").then((module) => module.checkStory(document, rules, axeUrl));
+        checked
             .then((violations) => tellShell({ type: "forgebook:checked", storyId, violations }))
             .catch((error) => tellShell({
             type: "forgebook:check-error",
@@ -119,6 +123,9 @@ export const mountFrame = async (container, config) => {
     let fixed = NOT_FIXED;
     // set once the story runs: a view the shell sends then changes its language and its globals without a new mount
     let changeShown;
+    // the view both the root and the story's drawing show; none when they may differ, so the next view is applied whatever
+    // it says: a view that comes before the story runs reaches only the root, and an edit draws the story with new globals
+    let shownView = liveView(view);
     // the shell sends the live part of a changed view: applied on the root, and kept in the address so a reload (an
     // edit, a stale module) shows the same view
     const showSpills = spillOutline(document, ".forgebook-frame", (count) => tellShell({ type: "forgebook:spills", storyId, count }));
@@ -165,8 +172,15 @@ export const mountFrame = async (container, config) => {
             showSpills(message.isOn);
         if (message.type !== "forgebook:view")
             return;
-        applyView(document.documentElement, withFixed(message.view, fixed), catalogue);
+        const shown = withFixed(message.view, fixed);
+        // the same view again draws nothing: a story's state, and the time its draw takes, are not the shell's to spend
+        if (changeShown !== undefined &&
+            shownView !== undefined &&
+            isSameLiveView(withFixed(shownView, fixed), shown))
+            return;
+        applyView(document.documentElement, shown, catalogue);
         changeShown?.(message.view);
+        shownView = changeShown === undefined ? undefined : message.view;
         const address = frameAddress(window.location.pathname, storyId, { ...view, ...message.view }, switches);
         window.history.replaceState(null, "", address);
     });
@@ -274,8 +288,11 @@ export const mountFrame = async (container, config) => {
                     })
                         .catch((error) => {
                         // a language another choice replaced meanwhile is no longer the frame's concern
-                        if (count === shownCount)
-                            reportError(error instanceof Error ? error.message : String(error));
+                        if (count !== shownCount)
+                            return;
+                        // the story still shows the view before this one: choosing this one again must try again
+                        shownView = undefined;
+                        reportError(error instanceof Error ? error.message : String(error));
                     });
                 };
             },
@@ -314,6 +331,7 @@ export const mountFrame = async (container, config) => {
                 return;
             }
             story = next;
+            shownView = undefined;
             running.setStory(next);
             if (controls !== undefined)
                 tellReady();
@@ -333,6 +351,7 @@ export const mountFrame = async (container, config) => {
                 return;
             }
             story = next;
+            shownView = undefined;
             running.setStory(next, [...preview.decorators, ...plugins.decorators]);
             if (controls !== undefined)
                 tellReady();

package/dist/src/frame/touchCaret.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What a simulated finger's tap does to an editable field: it focuses the field and puts the caret under the finger, the
+ * reactions a dispatched event never gets from the browser. Used by the touch layer (`touchLayer.ts`), which loads
+ * only when the Touch switch is on.
+ *
+ * @remarks
+ * `caretPositionFromPoint` answers the character's place for an input or a textarea (the field itself as its node, in
+ * Chromium, Firefox and WebKit) and for a contenteditable (a text node). `caretRangeFromPoint`, for a browser without it,
+ * answers only for a contenteditable: for the other two it names an unrelated place, so they go to their end there.
+ *
+ * @module
+ */
+import type { Point } from "./touchGesture.ts";
+/**
+ * The editable field a node is in, the one a finger on it would focus: an input with a caret or a textarea, not
+ * disabled (a read-only one still takes the caret, as under a real finger), or a contenteditable's editing host.
+ *
+ * @param node - the node (a contenteditable's text, for one).
+ * @returns the field; none when the node is in no such field.
+ */
+export declare const editableFieldOf: (node: Node) => HTMLElement | undefined;
+/**
+ * The element under a point, inside the open shadow roots on the way (`elementFromPoint` stops at their hosts).
+ *
+ * @param document - the frame's document.
+ * @param point - the point.
+ */
+export declare const deepElementAt: (document: Document, point: Point) => Element | undefined;
+/**
+ * A tap lands at a point: the editable field under it, if any, takes the focus and the caret.
+ *
+ * @param document - the frame's document.
+ * @param point - where the finger tapped.
+ */
+export declare const tapField: (document: Document, point: Point) => void;
+/**
+ * A tap's click reached a label: the editable field it names takes the focus, which a dispatched click does not give it.
+ * The caret stays where the field had it, as under a real finger. A tap on what is interactive inside the label (the
+ * field itself, a button) does not activate the label.
+ *
+ * @param origin - where the click began, inside any shadow root.
+ */
+export declare const tapLabel: (origin: EventTarget | undefined) => void;

package/dist/src/frame/touchCaret.js

@@ -0,0 +1,195 @@
+/** The input types with a caret: the others (a checkbox, a range, a date…) keep the browser's own reaction. */
+const CARET_INPUT_TYPES = new Set([
+    "text",
+    "search",
+    "url",
+    "tel",
+    "email",
+    "password",
+    "number"
+]);
+/** What is interactive by itself inside a label: a tap on it does not activate the label. */
+const LABEL_INTERACTIVE = "a[href], button, input, select, textarea, summary, [tabindex]";
+/**
+ * Whether a field is an input or a textarea.
+ *
+ * @param field - the field.
+ */
+const isTextControl = (field) => field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement;
+/**
+ * The editable field a node is in, the one a finger on it would focus: an input with a caret or a textarea, not
+ * disabled (a read-only one still takes the caret, as under a real finger), or a contenteditable's editing host.
+ *
+ * @param node - the node (a contenteditable's text, for one).
+ * @returns the field; none when the node is in no such field.
+ */
+export const editableFieldOf = (node) => {
+    const element = node instanceof Element ? node : node.parentElement;
+    if (!(element instanceof HTMLElement))
+        return undefined;
+    if (element instanceof HTMLTextAreaElement)
+        return element.matches(":disabled") ? undefined : element;
+    if (element instanceof HTMLInputElement)
+        return CARET_INPUT_TYPES.has(element.type) && !element.matches(":disabled") ? element : undefined;
+    if (!element.isContentEditable)
+        return undefined;
+    // only the editing host takes the focus: what is inside it is edited through it
+    let host = element;
+    while (host.parentElement?.isContentEditable === true)
+        host = host.parentElement;
+    return host;
+};
+/**
+ * The element under a point, inside the open shadow roots on the way (`elementFromPoint` stops at their hosts).
+ *
+ * @param document - the frame's document.
+ * @param point - the point.
+ */
+export const deepElementAt = (document, point) => {
+    let element = document.elementFromPoint(point.x, point.y);
+    while (element?.shadowRoot) {
+        const inner = element.shadowRoot.elementFromPoint(point.x, point.y);
+        if (inner === null || inner === element)
+            break;
+        element = inner;
+    }
+    return element ?? undefined;
+};
+/**
+ * The shadow roots a field is inside: the caret's lookup does not enter one it is not given.
+ *
+ * @param field - the field.
+ */
+const shadowRootsAround = (field) => {
+    const roots = [];
+    let root = field.getRootNode();
+    while (root instanceof ShadowRoot) {
+        roots.push(root);
+        root = root.host.getRootNode();
+    }
+    return roots;
+};
+/**
+ * Where the browser would put the caret at a point, when that is in the field.
+ *
+ * @param document - the frame's document.
+ * @param point - the point.
+ * @param field - the field.
+ * @returns the place; none when the browser cannot tell.
+ */
+const caretSpotAt = (document, point, field) => {
+    let spot;
+    if (typeof document.caretPositionFromPoint === "function") {
+        const position = document.caretPositionFromPoint(point.x, point.y, {
+            shadowRoots: shadowRootsAround(field)
+        });
+        if (position !== null)
+            spot = { node: position.offsetNode, offset: position.offset };
+    }
+    else if (!isTextControl(field)) {
+        const range = document.caretRangeFromPoint(point.x, point.y);
+        if (range !== null)
+            spot = { node: range.startContainer, offset: range.startOffset };
+    }
+    return spot !== undefined && field.contains(spot.node) ? spot : undefined;
+};
+/**
+ * Puts the caret in an input or a textarea, at the end without an offset.
+ *
+ * @param document - the frame's document.
+ * @param control - the field, focused.
+ * @param offset - how far into its value.
+ */
+const placeInControl = (document, control, offset) => {
+    if (control.selectionStart !== null) {
+        const place = offset ?? control.value.length;
+        control.setSelectionRange(place, place);
+        return;
+    }
+    // an email or a number field has no selection range to set, but the document's selection walks through it, focused:
+    // it lands on the place in Chromium and WebKit, not in Firefox
+    const selection = document.getSelection();
+    if (selection === null)
+        return;
+    if (offset === undefined) {
+        selection.modify("move", "forward", "lineboundary");
+        return;
+    }
+    selection.modify("move", "backward", "lineboundary");
+    // the offset counts UTF-16 code units, the steps whole characters
+    const before = control.value.slice(0, offset);
+    const steps = Array.from(new Intl.Segmenter().segment(before)).length;
+    for (let step = 0; step < steps; step += 1)
+        selection.modify("move", "forward", "character");
+};
+/**
+ * Puts the caret in a contenteditable, at its end without a place.
+ *
+ * @param document - the frame's document.
+ * @param host - the editing host, focused.
+ * @param spot - the place.
+ */
+const placeInEditable = (document, host, spot) => {
+    const selection = document.getSelection();
+    if (selection === null)
+        return;
+    // the spot was read before the focus: a focus handler may have changed the text since
+    if (spot !== undefined && host.contains(spot.node)) {
+        const { node } = spot;
+        const length = node instanceof CharacterData ? node.length : node.childNodes.length;
+        selection.collapse(node, Math.min(spot.offset, length));
+        return;
+    }
+    selection.selectAllChildren(host);
+    selection.collapseToEnd();
+};
+/**
+ * Whether a field holds the focus: a story's focus handler may have moved it on.
+ *
+ * @param field - the field.
+ */
+const holdsFocus = (field) => {
+    const root = field.getRootNode();
+    return (root instanceof Document || root instanceof ShadowRoot) && root.activeElement === field;
+};
+/**
+ * A tap lands at a point: the editable field under it, if any, takes the focus and the caret.
+ *
+ * @param document - the frame's document.
+ * @param point - where the finger tapped.
+ */
+export const tapField = (document, point) => {
+    const element = deepElementAt(document, point);
+    const field = element === undefined ? undefined : editableFieldOf(element);
+    if (field === undefined)
+        return;
+    // read before the focus, which may scroll a long field's text from under the finger
+    const spot = caretSpotAt(document, point, field);
+    field.focus();
+    if (!holdsFocus(field))
+        return;
+    if (isTextControl(field))
+        placeInControl(document, field, spot?.offset);
+    else
+        placeInEditable(document, field, spot);
+};
+/**
+ * A tap's click reached a label: the editable field it names takes the focus, which a dispatched click does not give it.
+ * The caret stays where the field had it, as under a real finger. A tap on what is interactive inside the label (the
+ * field itself, a button) does not activate the label.
+ *
+ * @param origin - where the click began, inside any shadow root.
+ */
+export const tapLabel = (origin) => {
+    if (!(origin instanceof Element))
+        return;
+    const label = origin.closest("label");
+    if (label === null)
+        return;
+    const interactive = origin.closest(LABEL_INTERACTIVE);
+    if (interactive !== null && label.contains(interactive))
+        return;
+    const { control } = label;
+    if (control instanceof HTMLElement && editableFieldOf(control) !== undefined)
+        control.focus();
+};

package/dist/src/frame/touchEvents.d.ts

@@ -4,7 +4,7 @@
  *
  * @remarks
  * A page cannot make trusted events, so these are dispatched ones: the story's handlers see a finger, the browser's
- * own reactions (scrolling, focus) do not follow them. A touch pointer is captured by the element it went down on,
+ * own reactions (scrolling, focus) do not follow them: the layer makes up for a tap's focus (`touchCaret.ts`). A touch pointer is captured by the element it went down on,
  * as the browser does; a story that captures it elsewhere moves it there (`touchLayer.ts` patches the capture calls
  * for the simulated pointers' ids).
  *
@@ -61,5 +61,6 @@ export declare const sendMouse: (type: string, finger: Finger) => boolean;
  *
  * @param target - the real click's target.
  * @param finger - the finger that tapped.
+ * @returns whether no handler cancelled it.
  */
-export declare const sendClick: (target: EventTarget, finger: Finger) => void;
+export declare const sendClick: (target: EventTarget, finger: Finger) => boolean;

package/dist/src/frame/touchEvents.js

@@ -130,22 +130,21 @@ export const sendMouse = (type, finger) => {
  *
  * @param target - the real click's target.
  * @param finger - the finger that tapped.
+ * @returns whether no handler cancelled it.
  */
-export const sendClick = (target, finger) => {
-    target.dispatchEvent(new PointerEvent("click", {
-        bubbles: true,
-        cancelable: true,
-        composed: true,
-        view: finger.startTarget.ownerDocument.defaultView,
-        detail: 1,
-        pointerId: finger.id,
-        pointerType: "touch",
-        isPrimary: true,
-        clientX: finger.point.x,
-        clientY: finger.point.y,
-        screenX: finger.point.x,
-        screenY: finger.point.y,
-        width: CONTACT_PX,
-        height: CONTACT_PX
-    }));
-};
+export const sendClick = (target, finger) => target.dispatchEvent(new PointerEvent("click", {
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+    view: finger.startTarget.ownerDocument.defaultView,
+    detail: 1,
+    pointerId: finger.id,
+    pointerType: "touch",
+    isPrimary: true,
+    clientX: finger.point.x,
+    clientY: finger.point.y,
+    screenX: finger.point.x,
+    screenY: finger.point.y,
+    width: CONTACT_PX,
+    height: CONTACT_PX
+}));

package/dist/src/frame/touchLayer.js

@@ -11,11 +11,14 @@
  * no button down sends nothing: a finger does not hover. Shift fixes a centre beside the mouse (the second finger shows 80 px to its left); a press then puts a
  * second finger mirrored around it, so dragging pinches and rotates. The real cursor is hidden and the fingers are
  * dots (`touchDots.ts`). While it is on, `navigator.maxTouchPoints` and `ontouchstart` say touch, and capturing a
- * simulated pointer works. A simulation: the events are not trusted, so the browser's own scrolling, focus from a
- * touch, a virtual keyboard and real Safari stay a device's (or `forgebook dev --touch`'s).
+ * simulated pointer works. A tap on an editable field focuses it and puts the caret there (`touchCaret.ts`), the real
+ * press on one doing nothing: a finger that drags or holds there must not focus it. A simulation: the events are not
+ * trusted, so the browser's own scrolling, a virtual keyboard and real Safari stay a device's (or
+ * `forgebook dev --touch`'s).
  *
  * @module
  */
+import { deepElementAt, editableFieldOf, tapField, tapLabel } from "./touchCaret.js";
 import { touchDots } from "./touchDots.js";
 import { sendClick, sendMouse, sendPointer, sendTouch } from "./touchEvents.js";
 import { dragAxis, isDragging, LONG_PRESS_MS, mirroredFinger } from "./touchGesture.js";
@@ -166,6 +169,18 @@ const pressMove = (state, press, event) => {
             sendPointer("pointermove", finger, true);
     drawDots(state);
 };
+/**
+ * A tap's compatibility mouse events, and the focus on an editable field a real finger's comes with: a handler that
+ * cancels the `mousedown` leaves the field without it.
+ *
+ * @param document - the frame's document.
+ * @param finger - the finger that tapped.
+ */
+const sendTapMouse = (document, finger) => {
+    if (sendMouse("mousedown", finger))
+        tapField(document, finger.point);
+    sendMouse("mouseup", finger);
+};
 /**
  * A press ends: the fingers lift, a scroll flings on, a tap sends the mouse's compatibility events and readies its
  * click.
@@ -198,12 +213,19 @@ const pressUp = (state, press, isCancel, time) => {
     const isTap = !isCancel && !press.isDrag && !press.isLongPress && press.fingers.length === 1;
     const isClicking = isTap && !press.isTouchCancelled && !isEndCancelled;
     state.tapper = isClicking ? first : undefined;
-    if (isClicking && !press.isDownCancelled && first !== undefined) {
-        sendMouse("mousedown", first);
-        sendMouse("mouseup", first);
-    }
+    if (isClicking && !press.isDownCancelled && first !== undefined)
+        sendTapMouse(state.document, first);
     drawDots(state);
 };
+/**
+ * Whether a real event began in an editable field.
+ *
+ * @param event - the event.
+ */
+const isInField = (event) => {
+    const [origin] = event.composedPath();
+    return origin instanceof Node && editableFieldOf(origin) !== undefined;
+};
 /**
  * A real event the layer handles apart from the pointer's, before the story: the mouse's click (a tap's is sent again as
  * a finger's, a drag's or a long press's is none), a text selection or an image dragged by the finger, the right
@@ -226,10 +248,12 @@ const handledApart = (state, event) => {
         state.tapper = undefined;
         // after the real click's dispatch: cancelling it undoes a checkbox's toggle at its end, a click sent inside it too
         const { target } = event;
+        const [origin] = event.composedPath();
         if (finger !== undefined && target !== null)
             state.clickTimer = window.setTimeout(() => {
                 state.clickTimer = undefined;
-                sendClick(target, finger);
+                if (sendClick(target, finger))
+                    tapLabel(origin);
             }, 0);
         return true;
     }
@@ -237,6 +261,9 @@ const handledApart = (state, event) => {
         return true;
     if (event.type !== "selectstart" && event.type !== "dragstart" && event.type !== "contextmenu")
         return false;
+    // inside a field the keyboard selects (Shift and an arrow): only the finger's selection of the page stays out
+    if (event.type === "selectstart" && isInField(event))
+        return true;
     event.preventDefault();
     event.stopImmediatePropagation();
     return true;
@@ -290,6 +317,18 @@ const pointerInput = (state, event) => {
         pressUp(state, press, event.type === "pointercancel", event.timeStamp);
     }
 };
+/**
+ * A real press on an editable field does nothing there: the browser would focus it and start a selection at once, when
+ * a finger's reaction waits for its lift (`touchCaret.ts`) and never comes from a drag or a long press.
+ *
+ * @param state - the simulation's state.
+ * @param event - the real press.
+ */
+const keepFieldForTap = (state, event) => {
+    const element = deepElementAt(state.document, { x: event.clientX, y: event.clientY });
+    if (element !== undefined && editableFieldOf(element) !== undefined)
+        event.preventDefault();
+};
 /**
  * What the simulation does with one real event, before the story sees it: the story never sees a real one.
  *
@@ -302,6 +341,8 @@ const intercept = (state, event) => {
     event.stopImmediatePropagation();
     if (event instanceof PointerEvent)
         pointerInput(state, event);
+    else if (event.type === "mousedown" && event instanceof MouseEvent)
+        keepFieldForTap(state, event);
 };
 /**
  * Makes the frame say it is a touch device, and lets the story capture a simulated pointer.

package/dist/src/propGroups.d.ts

@@ -1,16 +1,24 @@
 /**
- * A component's props in their groups, as its TSDoc names them (`@group Selection`): the API reference and the Props
- * tab list them the same way.
+ * A component's props in their groups, as its TSDoc names them (`@group Selection`), with its required props where the
+ * catalogue, the component or the story asks (`requiredFirst`): the API reference and the Props tab list them the same
+ * way.
  *
  * @remarks
  * The props that name no group come first: they are the ones an author left out of every group, most often the few
  * every use of the component sets (`value`, `onChange`). Then each group, in the order a configuration names them
  * (the component's meta, then the catalogue), the others in the order they first appear among the props. A component
  * whose props name no group is one list, as it always was. Every group starts open: a reader folds one away, never the
- * catalogue. Pure.
+ * catalogue.
+ *
+ * The required props come first inside each group by default, the others keeping the order of the source, so a reader
+ * sees at once what every use must set. A `section` layout gathers them in one section before the groups instead,
+ * which only means something when there are groups: without, it is the same single list. The narrowest setting wins
+ * (the story's, the component's, the catalogue's), and a reader's switch turns the ordering on or off over them,
+ * never choosing the layout, which stays the developer's. Pure.
  *
  * @module
  */
+import type { RequiredFirst } from "@forgebook/story-format/csf";
 /** A group of props: its name, none for the props that name no group, and its props in their order. */
 export type PropGroup<TProp> = {
     /** The group's name, as `@group` writes it; none for the props that name no group. */
@@ -44,3 +52,58 @@ export declare const groupedProps: <TProp extends {
 export declare const hasPropGroups: (props: readonly {
     readonly group?: string | undefined;
 }[]) => boolean;
+/** The layouts the required props can take, as a configuration and `parameters.requiredFirst` write them. */
+export declare const REQUIRED_FIRST_LAYOUTS: readonly RequiredFirst[];
+/**
+ * The layout a reader sees: the narrowest the developer set (the story's or the component's, else the catalogue's),
+ * with the reader's switch over it. Turned off, the source's order; turned on where the developer chose the source's
+ * order, the catalogue's layout, else `in-groups`.
+ *
+ * @param own - the story's or the component's setting; none leaves it to the catalogue.
+ * @param catalogue - the catalogue's setting.
+ * @param isReaderOn - the reader's switch; none when the reader never turned it.
+ */
+export declare const requiredFirstLayout: (own: RequiredFirst | undefined, catalogue: RequiredFirst, isReaderOn: boolean | undefined) => RequiredFirst;
+/** A prop as the layout reads it: its group, whether it is required, and whether it is an event. */
+type LaidOutProp = {
+    readonly group?: string | undefined;
+    readonly isRequired: boolean;
+    readonly kind?: string;
+};
+/** Props laid out for reading: the "Required" section, the groups, the events. */
+export type PropLayout<TProp> = {
+    /**
+     * The "Required" section's props, those naming no group first, then each group's in the groups' order, then the
+     * events; empty unless the layout is `section` and the props name a group.
+     */
+    readonly required: readonly TProp[];
+    /** The props but the events in their groups (`groupedProps`), without those in `required`; no group left empty. */
+    readonly groups: readonly PropGroup<TProp>[];
+    /** The events, without those in `required`. */
+    readonly events: readonly TProp[];
+};
+/**
+ * Whether putting the required props first changes anything: a required prop and one that is not. A table without
+ * shows no "Required first" switch.
+ *
+ * @param props - the props shown.
+ */
+export declare const canOrderRequired: (props: readonly {
+    readonly isRequired: boolean;
+}[]) => boolean;
+/**
+ * Props with the required ones first, the rest in their order.
+ *
+ * @param props - the props, in their order.
+ */
+export declare const requiredPropsFirst: <TProp extends LaidOutProp>(props: readonly TProp[]) => TProp[];
+/**
+ * Props laid out for reading: in their groups (`groupedProps`), the events apart, the required ones where the layout
+ * puts them.
+ *
+ * @param props - the props, events among them (`kind: "event"`), in the order of the source.
+ * @param order - the groups to show first, in this order (`propGroupOrder`).
+ * @param layout - where the required props go (`requiredFirstLayout`).
+ */
+export declare const laidOutProps: <TProp extends LaidOutProp>(props: readonly TProp[], order: readonly string[], layout: RequiredFirst) => PropLayout<TProp>;
+export {};