@dxos/react-ui-feed 0.11.1

package/dist/types/src/virtualizer/placement.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Where the rows go, in one number each.
+ *
+ * Scalars only — `start`, `extent`, `viewport` — never `top` or `height`, so the axis is the DOM
+ * binding's business and never gets baked in here (§9). No DOM, no React, no CodeMirror: everything
+ * this decides can be decided from arithmetic, and everything it cannot decide is a measurement
+ * somebody hands it.
+ *
+ * The model is one authoritative fact and derivations from it: an **anchor**, identified by message
+ * id, whose absolute position in content space is known. Every other row's position is that position
+ * plus or minus the extents in between. Prepending rows does not move the anchor, so it does not move
+ * anything at or after it — which is the property §7 needs and the reason this is not a prefix sum
+ * from index 0.
+ */
+export type Extents = {
+    /**
+     * Extent along the scroll axis of the row at `index`, when nothing has been measured for it.
+     */
+    of: (index: number) => number;
+    /**
+     * Never revised by measurement.
+     *
+     * The layout constrains the extent — a horizontal feed of declared-width items, a list of
+     * fixed-height rows — so offsets are an exact prefix sum and there is nothing to correct. It does
+     * **not** mean unchecked: the binding still measures in dev and reports a mismatch (§8).
+     */
+    exact?: boolean;
+};
+export type PlacementOptions = {
+    count: number;
+    /** Identity of the row at `index`. Extents are stored against this, so a prepend cannot shift them. */
+    getId: (index: number) => string;
+    extents: Extents;
+    /** Extent of the visible region along the scroll axis. */
+    viewport: number;
+    /** Rows to mount beyond the visible region, each side. */
+    overscan?: number;
+    /**
+     * Empty extent after the last row, so the reader can scroll it up to the start of the viewport.
+     *
+     * A number the host supplies, not a mode the list has. On the old design this was a flag that
+     * special-cased the tail everywhere it was consulted, and it could not be made stable; here it is
+     * added to the sizer and nothing else knows about it (§7).
+     */
+    reserve?: number;
+};
+/** The mounted range and where its parent goes. */
+export type Layout = {
+    /** First and last mounted row, inclusive — the visible rows plus overscan. */
+    first: number;
+    last: number;
+    /**
+     * First and last row the reader can actually see.
+     *
+     * Reported separately because it is what a readout means by "where am I": the mounted range
+     * includes rows deliberately kept off screen, and naming one of those would be describing the
+     * overscan rather than the reader.
+     */
+    visible: {
+        first: number;
+        last: number;
+    };
+    /** Absolute position of the first mounted row: what the parent is translated by (§7). */
+    offset: number;
+    /** Total extent of the scrollable content, which is what the thumb is computed from. */
+    sizerExtent: number;
+};
+/** What reaching an edge revealed about the estimates, when it revealed anything. */
+export type EdgeDrift = {
+    edge: 'start' | 'end';
+    /** How far out the estimate was. Positive means the region was shorter than assumed. */
+    delta: number;
+};
+/**
+ *
+ */
+export declare class Placement {
+    #private;
+    constructor({ count, getId, extents, viewport, overscan, reserve }: PlacementOptions);
+    get scroll(): number;
+    get count(): number;
+    /** The viewport is the binding's to know: it is the one thing here that comes from the DOM. */
+    setViewport(viewport: number): void;
+    /**
+     * The host's answer about extents can change — a row is edited, a panel opens, a story flips a
+     * fixture — and it is a *function*, so keeping the one handed over at construction quietly pins
+     * the layout to whatever was true then. Measured extents survive: they are keyed by id and this
+     * only replaces what the host would say about a row nobody has measured.
+     */
+    setExtents(extents: Extents): void;
+    setReserve(reserve: number): void;
+    /**
+     * The host's identity function, which is a closure over the host's own list.
+     *
+     * Appending a message gives a *new* `getId`, and a placement holding the one it was constructed
+     * with resolves the new row's index to an id nobody will ever measure. The binding then stores
+     * that row's measurement under the id the DOM carries and reads it back under the stale one, so
+     * the row is measured, found to disagree, measured again — every commit, for ever. It presents as
+     * a render loop rather than as a wrong size, which is what made `bridge/Tail` look like a tail
+     * defect (§8: measurement is only a correction if it can be read back).
+     */
+    setGetId(getId: (index: number) => string): void;
+    get anchor(): Readonly<{
+        id: string;
+        index: number;
+        start: number;
+    }>;
+    /** Extent of one row: what was measured, or what the host says. */
+    extentOf(index: number): number;
+    /**
+     * Absolute position of a row, derived from the anchor rather than summed from the start.
+     *
+     * Rows between here and the anchor are the only ones whose extents matter (§5): everything before
+     * the window is described by the anchor's position, not by adding up guesses about it.
+     */
+    positionOf(index: number): number;
+    /** The reader moved. Nothing is corrected here — only the mounted range changes. */
+    scrollTo(offset: number): void;
+    /**
+     * A row turned out to be a different size than assumed.
+     *
+     * Rows at or after the anchor push the ones after them and leave the anchor alone. A row *before*
+     * the anchor moves the rows between it and the anchor, which is correct and unavoidable: the
+     * anchor is the thing being held still, and it is still being held.
+     */
+    measure(id: string, extent: number): void;
+    /** The model changed length. `prepended` rows arrived before the anchor and shift its index. */
+    setCount(count: number, { prepended }?: {
+        prepended?: number;
+    }): void;
+    /**
+     * Move to a row that may be nowhere near the window.
+     *
+     * The only operation that positions from estimates rather than from measurement, because there is
+     * no measured path to somewhere the reader has never been. A jump is a discontinuity the reader
+     * asked for, so being approximately right is what it can be.
+     */
+    jumpTo(index: number, align?: 'start' | 'end'): void;
+    /**
+     * Where the reader has to be for `index` to sit at the start (or end) of the viewport.
+     *
+     * Reports; does not move. `jumpTo` re-anchors as well, which is right for a discontinuity and
+     * wrong for a glide: the anchor would arrive at the destination while the element was still
+     * travelling, so the reader would watch the rows they were scrolling *through* unmount and the
+     * journey happen over nothing.
+     */
+    offsetOf(index: number, align?: 'start' | 'end'): number;
+    /**
+     * Where the reader has to be for the last row to rest against the end of the viewport.
+     *
+     * Derived from the anchor, like every other position, and deliberately **not** from a sum over the
+     * model: a follow asks this again on every commit, and each answer mounts rows whose measurement
+     * replaces the estimates that sum is over — so a sum-based end moves every time it is consulted,
+     * and consulting it is what moves it. That is not slow convergence, it is a feedback loop, and in
+     * React it terminates by exceeding the update limit rather than by settling (`bridge/Tail`).
+     *
+     * Anchor-relative, the answer only changes as the rows *between the anchor and the last row* are
+     * measured — each of them once — so a follow settles in a couple of commits and rows the reader
+     * has already passed cannot disturb it.
+     */
+    endOffset(): number;
+    /** The mounted range, the parent's offset, and the extent the thumb is computed from. */
+    layout(): Layout;
+    /**
+     * Repay the start edge's drift: shift every position so row 0 starts at exactly zero, and move
+     * the scroll by the same amount so nothing the reader sees moves.
+     *
+     * The first row starting at zero is the one absolute fact of content space, and estimates being
+     * replaced above the anchor break it: a feed opened at its tail whose rows measure taller than
+     * assumed pushes row 0 *negative*, where no scroll can reach it — the reader arrives at the top
+     * and the first messages simply are not there. This is the single correction that must touch the
+     * scroll (§7's rule is about corrections and readers sharing a channel; here both the content and
+     * the offset move by the same delta in the same commit, so the reader sees nothing at all).
+     * Returns the shift for the binding to apply to the element.
+     */
+    rebaseStart(): number;
+    /**
+     * What an edge revealed, if the window has reached one.
+     *
+     * The edges are where estimate meets ground truth: the first row starts at zero and the last one
+     * ends at the content's end, by definition, so a computed position that says otherwise is the
+     * measure of how wrong the estimates were. Reported rather than silently applied — absorbing it
+     * into the anchor would move what the reader is looking at, and at an edge they are looking at
+     * exactly the thing that would move.
+     */
+    drift(): EdgeDrift | undefined;
+}
+//# sourceMappingURL=placement.d.ts.map

package/dist/types/src/virtualizer/placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../../../../src/virtualizer/placement.ts"],"names":[],"mappings":"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"}

package/dist/types/src/virtualizer/placement.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=placement.test.d.ts.map

package/dist/types/src/virtualizer/placement.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.test.d.ts","sourceRoot":"","sources":["../../../../src/virtualizer/placement.test.ts"],"names":[],"mappings":""}