vlist 3.0.0-next.1 → 3.0.0-next.3

package/dist/config.d.ts

@@ -15,14 +15,22 @@
  * lean and tree-shakeable; only consumers that opt into the batteries-included
  * config (the adapters) pull in this module and, with it, every plugin it wires.
  */
-import type { VListItem, GroupsConfig, VListAdapter } from "./types";
+import type { VListItem, GroupsConfig, VListAdapter, ScrollConfig } from "./types";
 import { createVList } from "./core/create";
-import type { NativeScrollConfig } from "./native";
-import type { CreateVListConfig, VList, VListPlugin } from "./core/types";
+import type { CreateVListConfig, VList, VListPlugin, PluginMethods } from "./core/types";
+import type { AutosizeMethods } from "./plugins/autosize/plugin";
+import type { DataMethods } from "./plugins/data/plugin";
+import type { GridMethods } from "./plugins/grid/plugin";
+import type { MasonryMethods } from "./plugins/masonry/plugin";
+import type { GroupsMethods } from "./plugins/groups/plugin";
+import type { SelectionMethods } from "./plugins/selection/plugin";
+import type { ScrollbarMethods } from "./plugins/scrollbar/plugin";
+import type { SnapshotsMethods } from "./plugins/snapshots/plugin";
 import type { DataPluginConfig } from "./plugins/data";
 import type { GridPluginConfig } from "./plugins/grid";
 import type { MasonryPluginConfig } from "./plugins/masonry";
 import type { SelectionPluginConfig } from "./plugins/selection";
+import type { A11yPluginConfig } from "./plugins/a11y";
 import type { ScrollbarPluginConfig } from "./plugins/scrollbar";
 /** List creation function injected by an adapter consumer. */
 export type VListFactory<T extends VListItem = VListItem> = typeof createVList<T>;
@@ -33,8 +41,8 @@ export type VListFactory<T extends VListItem = VListItem> = typeof createVList<T
  * translated into plugins by {@link resolvePlugins}.
  */
 export interface VListConfig<T extends VListItem = VListItem> extends Omit<CreateVListConfig<T>, "container" | "scroll"> {
-    /** Input model; native scrolling requires a factory imported from vlist/native. */
-    scroll?: NativeScrollConfig;
+    /** Scroll options; select synthetic input with a factory from vlist/synthetic. */
+    scroll?: ScrollConfig;
     /** List factory; defaults to core createVList. Fixed for this instance. */
     factory?: VListFactory<T>;
     /** Layout mode. Wires the grid or masonry plugin from `grid`/`masonry`. */
@@ -45,10 +53,31 @@ export interface VListConfig<T extends VListItem = VListItem> extends Omit<Creat
     masonry?: MasonryPluginConfig;
     /** Sticky group headers. */
     groups?: GroupsConfig;
-    /** Row selection (single / multi). */
+    /**
+     * Row selection (single / multi). Omit it for a display-only list: nothing
+     * is wired then, so the list keeps `role="list"` and stays out of the tab
+     * order, exactly like a core list created without the plugin.
+     */
     selection?: SelectionPluginConfig;
-    /** Custom scrollbar options, or `"none"` to disable the custom scrollbar. */
-    scrollbar?: ScrollbarPluginConfig | "none";
+    /**
+     * Keyboard navigation, focus management and the WAI-ARIA listbox roles.
+     * Off by default, as in core: pass `true` for the defaults or an object to
+     * tune it. A selection mode other than `"none"` already provides both, so a
+     * list with one does not need this as well.
+     */
+    a11y?: A11yPluginConfig | boolean;
+    /**
+     * Custom overlay scrollbar. Off by default, as in core, which leaves the
+     * browser's native scrollbar in place: pass `true` for the defaults or an
+     * object to tune them. `"none"` is accepted for symmetry with
+     * `scroll.scrollbar` and wires nothing.
+     */
+    scrollbar?: ScrollbarPluginConfig | "none" | boolean;
+    /**
+     * Scroll position save/restore (`saveScroll` / `restoreScroll`).
+     * Off by default, as in core.
+     */
+    snapshots?: boolean;
     /** Async data source — enables the data plugin. */
     adapter?: VListAdapter<T>;
     /** Async loading tuning (used together with `adapter`). */
@@ -63,18 +92,80 @@ export interface VListConfig<T extends VListItem = VListItem> extends Omit<Creat
 }
 /**
  * Translate a {@link VListConfig} into the ordered plugin array that the core
- * `createVList` expects. Mirrors the adapters' historical behavior exactly:
- * `snapshots` is always included, and `selection` is always
- * present (in `"none"` mode when unset) so its API is available. Any user
- * `plugins` are appended last as an escape hatch.
+ * `createVList` expects. Every plugin comes from a field the caller set, so a
+ * config with no feature fields resolves to no plugins and an adapter list
+ * behaves like a core list given the same options. Any user `plugins` are
+ * appended last as an escape hatch.
  */
 export declare function resolvePlugins<T extends VListItem = VListItem>(config: VListConfig<T>): VListPlugin<T>[];
+/** A field value that wires no plugin. `"none"` is the scrollbar's spelling of off. */
+type Off = false | undefined | null | "none";
+/**
+ * The methods a field adds when it is on. Distributive on purpose: a widened
+ * `boolean` is `true | false`, so the result is `M | {}` and a call on it is a
+ * type error — the honest answer when the compiler cannot know whether the
+ * plugin is seated. Narrow the config, or spell the field as a literal.
+ */
+type OnOff<V, M> = V extends Off ? {} : M;
+/**
+ * The methods field `K` adds, or nothing when the config has no such field.
+ * Indexing `C[K]` directly would fall back to the constraint's type for an
+ * absent key and hand a plain config every plugin's methods.
+ */
+type Field<C, K extends PropertyKey, M> = C extends Record<K, infer V> ? OnOff<V, M> : {};
+/** Whether the item spec carries an estimate, which wires autosize(). */
+type Estimated<C> = C extends {
+    item: {
+        estimatedHeight: number;
+    } | {
+        estimatedWidth: number;
+    };
+} ? C extends {
+    item: {
+        height: number;
+    } | {
+        width: number;
+    };
+} ? {} : AutosizeMethods : {};
+/**
+ * The plugin methods a {@link VListConfig} wires, derived from its fields the
+ * same way {@link resolvePlugins} derives the plugins — the two are the type
+ * and runtime halves of one mapping, and `test/types/config.ts` asserts they
+ * agree. This is what lets an adapter list carry `select()` or `reload()` the
+ * way a core list built with `createVList(config, [selection()])` does.
+ */
+export type ConfigMethods<T extends VListItem, C extends VListConfig<T>> = Field<C, "adapter", DataMethods> & (C extends {
+    layout: "grid";
+} ? GridMethods : {}) & (C extends {
+    layout: "masonry";
+} ? MasonryMethods : {}) & Field<C, "groups", GroupsMethods> & Field<C, "selection", SelectionMethods<T>> & Field<C, "scrollbar", ScrollbarMethods> & Field<C, "snapshots", SnapshotsMethods> & Estimated<C> & (C extends {
+    plugins: infer P extends readonly unknown[];
+} ? PluginMethods<P> : {});
+/**
+ * The item type a config is written for: the element type of its `items`, else
+ * the parameter of its template. `VListConfig<infer T>` would do neither
+ * reliably — a config with no `items` inferred `any`.
+ */
+export type ConfigItem<C> = C extends {
+    items: readonly (infer T extends VListItem)[];
+} ? T : C extends {
+    item: {
+        template: (item: infer T extends VListItem, ...rest: never[]) => unknown;
+    };
+} ? T : VListItem;
 /**
  * Create a vlist instance from a high-level {@link VListConfig}, resolving its
  * feature fields into plugins via {@link resolvePlugins}. This is the single
  * entry point every framework adapter delegates to.
+ *
+ * One type parameter, the config itself: the item type comes from its `items`
+ * or `template`, and the list's methods from its feature fields
+ * ({@link ConfigMethods}). Do not pass a type argument — `createVListFromConfig<Row>`
+ * would name a config type, not an item type, and fail to compile; the same
+ * trap `createVList<Row>` falls into is closed here by having no second slot.
  */
-export declare function createVListFromConfig<T extends VListItem = VListItem>(config: VListConfig<T> & {
+export declare function createVListFromConfig<const C extends VListConfig<any> & {
     container: HTMLElement | string;
-}): VList<T>;
+}>(config: C): VList<ConfigItem<C>> & ConfigMethods<ConfigItem<C>, C>;
+export {};
 //# sourceMappingURL=config.d.ts.map