@rcarls/rc-virtual-scroller 0.0.0 → 0.7.0

package/dist/types/packages/rc-virtual-scroller/src/rc-virtual-scroller.d.ts

@@ -0,0 +1,211 @@
+import { LitElement } from 'lit';
+import { LogicalAxis } from '@rcarls/rc-common';
+export type RCVirtualScrollerAxis = LogicalAxis;
+export type RCVirtualScrollerAlign = 'start' | 'center' | 'end' | 'nearest';
+export interface RCVirtualScrollerRangeDetail {
+    /** First item index the consumer should render, inclusive. */
+    readonly start: number;
+    /** Item index one past the last the consumer should render. */
+    readonly end: number;
+    /**
+     * Effective items in one line: the explicit override, inferred uniform grid
+     * capacity accounting for spans, or one for a non-grid collection.
+     */
+    readonly itemsPerLine: number;
+    /** Line pitch in pixels along the scrolling axis, including the gap. */
+    readonly lineSize: number;
+    /** `false` while `lineSize` is still the `item-size` estimate, `true` once a real line was measured. */
+    readonly measured: boolean;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'rc-virtual-scroller': RCVirtualScroller;
+    }
+    interface HTMLElementEventMap {
+        'rc-virtual-scroller-range': CustomEvent<RCVirtualScrollerRangeDetail>;
+    }
+}
+/**
+ * Reports which slice of a long collection is currently on screen and reserves
+ * the scroll space for the rest, so the consumer can render a few dozen items
+ * instead of a few thousand.
+ *
+ * The element is deliberately headless: it never creates, recycles, or
+ * positions item DOM. It measures geometry, dispatches
+ * `rc-virtual-scroller-range`, and sizes two spacers around the default slot.
+ * The consumer slots its own single container element (a `<ul>`, an
+ * `<rc-list>`, a `<table>` body) and renders `detail.start`..`detail.end` into
+ * it with whatever framework it already uses. That keeps the markup, the CSS
+ * layout, and the accessibility semantics with the code that owns them, and it
+ * means a native `grid-template-columns: repeat(auto-fill, ...)` keeps working
+ * untouched.
+ *
+ * `axis` is logical. `block` (the default) windows lines stacked the way
+ * paragraphs stack, which is vertical in horizontal writing modes and
+ * horizontal in vertical ones. `inline` windows a row of items running the way
+ * text runs, such as a horizontal shelf; the slotted container then lays its
+ * items along the inline axis (`display: flex`, or a grid with
+ * `grid-auto-flow: column`). Direction and writing mode are read from the
+ * element's own computed style, so RTL and vertical text need no configuration.
+ *
+ * Virtualization requires sequential DOM-order items with uniform line pitch
+ * and capacity (the final line may be partial). Regular grids, uniform numeric
+ * spans, lists, and nonwrapping shelves are measured from CSS. Use
+ * `items-per-line` for ambiguous grid capacity; it does not enable variable
+ * pitch, masonry, dense placement, or reordered items. Detectably unsupported
+ * layouts render the full collection and warn in development. `item-size` is
+ * only a bootstrap estimate. Hidden layouts retain their last valid window.
+ *
+ * Accessibility is the consumer's, because the consumer owns the roles. A
+ * virtualized set must still tell assistive technology its real size: put
+ * `aria-setsize` (the true total) and `aria-posinset` (the item's real index,
+ * not its DOM position) on each item, or `aria-rowcount` / `aria-rowindex` for
+ * a grid. See the package README. The one part this element does handle is
+ * focus: the reported range is always widened to include the focused item, so
+ * scrolling never silently drops focus to `<body>`.
+ *
+ * @slot - The consumer's single container element, holding only the items in the current range.
+ *
+ * @csspart spacer-start - Space along the scrolling axis standing in for the lines before the range.
+ * @csspart spacer-end - Space along the scrolling axis standing in for the lines after the range.
+ *
+ * @attr axis - Logical axis to window along: `block` (the default) or `inline`.
+ * @attr count - Total number of items in the collection, including the ones not rendered.
+ * @attr item-size - Estimated line pitch in pixels, used until a real line can be measured.
+ * @attr items-per-line - Explicit grid capacity; zero (the default) restores automatic inference.
+ * @attr overscan - Extra lines rendered beyond each edge of the viewport. Defaults to `2`.
+ * @attr disabled - Reports the whole collection as the range and stops measuring.
+ * @attr [first] - Reflected, computed. First item index in the current range.
+ * @attr [last] - Reflected, computed. Last item index in the current range, inclusive. `-1` when the range is empty.
+ *
+ * @fires rc-virtual-scroller-range - The visible range changed, or its geometry was re-measured.
+ *
+ * @see {@link https://richardcarls.github.io/rc-webcomponents/components/rc-virtual-scroller}
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/feed/ | WAI-ARIA APG: Feed pattern}
+ */
+export declare class RCVirtualScroller extends LitElement {
+    static styles: import('lit').CSSResult;
+    static enabledWarnings: ("migration" | "async-perform-update")[];
+    /** Logical axis to window along. */
+    axis: RCVirtualScrollerAxis;
+    private _count;
+    private _itemSize;
+    private _overscan;
+    private _capacity;
+    /** Total collection size, normalized to a nonnegative integer. Invalid values become zero. Host writes are silent. */
+    get count(): number;
+    set count(value: number);
+    /**
+     * Estimated line pitch in pixels, used for the first frame and whenever no
+     * line is available to measure. Get this roughly right: it is what the very
+     * first `rc-virtual-scroller-range` is computed from, and what a restored
+     * scroll position lands against. Invalid or nonpositive values become zero.
+     * Host writes are silent.
+     */
+    get itemSize(): number;
+    set itemSize(value: number);
+    /** Grid capacity override, normalized to a nonnegative integer; zero means automatic. Host writes are silent. */
+    get itemsPerLine(): number;
+    set itemsPerLine(value: number);
+    /** Extra lines beyond each viewport edge, floored to an integer. Invalid/negative values become two. Host writes are silent. */
+    get overscan(): number;
+    set overscan(value: number);
+    /**
+     * Reports the whole collection as the range and stops measuring. An escape
+     * hatch for short collections, printing, and A/B measurement; the consumer's
+     * render path stays the same either way.
+     */
+    disabled: boolean;
+    /**
+     * The scroll container to measure against. Defaults to the nearest scrolling
+     * ancestor. Set this when the ancestor only becomes scrollable after its own
+     * upgrade, or when the intended scrollport is further up than the first
+     * `overflow: auto` element.
+     */
+    scrollTarget: Element | null;
+    /** Read-only first reported item index, also exposed as the computed `first` attribute. */
+    get first(): number;
+    /** Read-only last reported item index, or -1 for an empty range; also exposed as `last`. */
+    get last(): number;
+    /**
+     * The most recently reported range, or `null` before the first measurement.
+     * The element measures on its own schedule, which can be before a consumer
+     * has attached its listener; render from this once when subscribing, then
+     * follow `rc-virtual-scroller-range`. Identical ranges are never re-sent, so
+     * a subscriber that skips this can wait for an event that will not come.
+     */
+    get range(): RCVirtualScrollerRangeDetail | null;
+    private _spacerStart;
+    private _spacerEnd;
+    private readonly _frame;
+    private _geometry;
+    private _needsSample;
+    private _resetGeometry;
+    private _unsupported;
+    private readonly _warnedLayouts;
+    private _$container;
+    private _$scrollSource;
+    private _contentObserver;
+    /** The host's own flow, resolved with the scroll target rather than per frame. */
+    private _flow;
+    private _resolvedTarget;
+    private _resizeObserver;
+    private _unobserveLocale;
+    private _lastDetail;
+    /** Set when the surrounding layout changed enough to re-find the scrollport. */
+    private _needsResolve;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(): void;
+    protected updated(changed: Map<PropertyKey, unknown>): void;
+    protected render(): import('lit-html').TemplateResult<1>;
+    /**
+     * Scrolls the item at `index` into view along `axis`. Accurate to the current
+     * line pitch, which means accurate to `item-size` until at least one line has
+     * rendered.
+     */
+    scrollToIndex(index: number, options?: {
+        align?: RCVirtualScrollerAlign;
+        behavior?: ScrollBehavior;
+    }): void;
+    /**
+     * Re-measures the slotted container and re-evaluates the range. Call this
+     * when something outside the element's own observers changed the item size,
+     * such as a font load or a theme swap.
+     */
+    measure(): void;
+    /**
+     * Schedules an evaluation. `RafScheduler` keeps only the most recently
+     * scheduled callback, so every path has to funnel through this single one:
+     * a scroll arriving between a resize and its frame must not be able to drop
+     * the resize's work.
+     */
+    private readonly _requestEvaluate;
+    private readonly _requestSample;
+    /** Requests an evaluation that re-finds the scrollport and flow first. */
+    private readonly _requestResolve;
+    private _attachScrollTarget;
+    private _detachScrollTarget;
+    /** The scroll target's visible client box in viewport coordinates. */
+    private _portViewportRect;
+    private _documentScroller;
+    /**
+     * Where the visible part of the scroll target sits relative to the host,
+     * measured from the host's start edge along `axis` in the host's own flow.
+     * Working from the two rects rather than from `scrollTop`/`scrollLeft`
+     * keeps the arithmetic identical in every writing mode and direction.
+     * Reported in the host's own CSS pixels, the unit its spacers are written in.
+     */
+    private _view;
+    private _effectiveLineSize;
+    /** Rebind observers only when their actual targets changed. */
+    private _observeLayout;
+    private _observingLayout;
+    /**
+     * Focus retargets to a closed shadow host. Stop at the item that owns it,
+     * rather than asking ordinary contains() to cross a shadow boundary.
+     */
+    private _focusedIndex;
+    private _evaluate;
+    private _applyRange;
+}

package/dist/types/packages/rc-virtual-scroller/src/rc-virtual-scroller.styles.d.ts

@@ -0,0 +1,2 @@
+export declare const virtualScrollerStyles: import('lit').CSSResult;
+export default virtualScrollerStyles;

package/dist/types/packages/rc-virtual-scroller/src/sample.d.ts

@@ -0,0 +1,15 @@
+import { Flow, LogicalAxis } from '@rcarls/rc-common';
+import { Geometry } from './range.js';
+export type LayoutSample = {
+    kind: 'ready' | 'incomplete';
+    geometry: Geometry;
+} | {
+    kind: 'unsupported';
+    reason: string;
+};
+/**
+ * Sample regular line geometry without changing the consumer's layout.
+ * Geometry is reported in the host's CSS pixels, whatever units each
+ * measurement is read in.
+ */
+export declare function sampleLayout($container: Element, axis: LogicalAxis, flow: Flow, override: number, previous: Geometry, hostZoom?: number): LayoutSample;

package/package.json

@@ -1,14 +1,65 @@
 {
   "name": "@rcarls/rc-virtual-scroller",
-  "version": "0.0.0",
-  "description": "Placeholder published only to register this package name on npm before configuring Trusted Publishing. Contains no code. Do not install or depend on this version.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.7.0",
+  "description": "Headless virtualization wrapper that reports the visible index range for a consumer-owned list or grid and reserves the off-range scroll space.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/richardcarls/rc-webcomponents.git"
+    "url": "git+https://github.com/richardcarls/rc-webcomponents.git",
+    "directory": "packages/rc-virtual-scroller"
   },
+  "homepage": "https://richardcarls.github.io/rc-webcomponents/components/rc-virtual-scroller",
   "license": "MIT",
-  "private": false,
-  "publishConfig": {
-    "access": "public"
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/rc-virtual-scroller.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/packages/rc-virtual-scroller/src/index.d.ts",
+        "default": "./dist/rc-virtual-scroller.js"
+      }
+    },
+    "./define": {
+      "import": {
+        "types": "./dist/types/packages/rc-virtual-scroller/src/define.d.ts",
+        "default": "./dist/rc-virtual-scroller-define.js"
+      }
+    }
+  },
+  "types": "./dist/types/packages/rc-virtual-scroller/src/index.d.ts",
+  "sideEffects": [
+    "./dist/rc-virtual-scroller-define.js"
+  ],
+  "customElements": "dist/custom-elements.json",
+  "scripts": {
+    "build": "tsc && vite build && cem analyze",
+    "cem:analyze": "cem analyze",
+    "preview": "vite preview",
+    "test:browser": "vitest --run",
+    "test:browser:chrome": "vitest --run --project=chromium",
+    "test:browser:firefox": "vitest --run --project=firefox"
+  },
+  "dependencies": {
+    "@rcarls/rc-common": "0.7.0"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "0.11.0",
+    "@vitest/browser-playwright": "4.1.5",
+    "lit": "^3.0.0",
+    "playwright": "^1.56.0",
+    "rollup": "^4.60.2",
+    "typescript": "~5.9.3",
+    "vite": "^7.1.7",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.6",
+    "vitest-browser-lit": "^1.0.1"
+  },
+  "peerDependencies": {
+    "lit": "^3.0.0"
   }
-}
+}