@symbiote-native/angular 3.1.3 → 3.3.0

package/src/components/virtualized-list/list-a11y-forward.ts

@@ -0,0 +1,42 @@
+// Forwards every accessibility input and gated event of a wrapper list to the list it renders
+// Angular has no attribute spread, and a template must be one static string
+
+export const LIST_ACCESSIBILITY_FORWARD = `
+  [accessible]="accessible"
+  [accessibilityLabel]="accessibilityLabel"
+  [accessibilityHint]="accessibilityHint"
+  [accessibilityRole]="accessibilityRole"
+  [accessibilityState]="accessibilityState"
+  [accessibilityValue]="accessibilityValue"
+  [accessibilityActions]="accessibilityActions"
+  [accessibilityLabelledBy]="accessibilityLabelledBy"
+  [importantForAccessibility]="importantForAccessibility"
+  [accessibilityLiveRegion]="accessibilityLiveRegion"
+  [screenReaderFocusable]="screenReaderFocusable"
+  [accessibilityViewIsModal]="accessibilityViewIsModal"
+  [accessibilityElementsHidden]="accessibilityElementsHidden"
+  [accessibilityIgnoresInvertColors]="accessibilityIgnoresInvertColors"
+  [accessibilityLanguage]="accessibilityLanguage"
+  [accessibilityRespondsToUserInteraction]="accessibilityRespondsToUserInteraction"
+  [accessibilityShowsLargeContentViewer]="accessibilityShowsLargeContentViewer"
+  [accessibilityLargeContentTitle]="accessibilityLargeContentTitle"
+  (accessibilityAction)="accessibilityAction.emit($event)"
+  (accessibilityTap)="accessibilityTap.emit($event)"
+  (magicTap)="magicTap.emit($event)"
+  (accessibilityEscape)="accessibilityEscape.emit($event)"
+  [role]="role"
+  [aria-label]="ariaLabel"
+  [aria-labelledby]="ariaLabelledBy"
+  [aria-live]="ariaLive"
+  [aria-hidden]="ariaHidden"
+  [aria-busy]="ariaBusy"
+  [aria-checked]="ariaChecked"
+  [aria-disabled]="ariaDisabled"
+  [aria-expanded]="ariaExpanded"
+  [aria-selected]="ariaSelected"
+  [aria-modal]="ariaModal"
+  [aria-valuemax]="ariaValueMax"
+  [aria-valuemin]="ariaValueMin"
+  [aria-valuenow]="ariaValueNow"
+  [aria-valuetext]="ariaValueText"
+`;

package/src/components/virtualized-list/list-bags.ts

@@ -0,0 +1,142 @@
+// The prop bags the list writes onto its scroll tag and refresh control, with the native callbacks
+// that feed them, kept apart from the windowing lifecycle of the component
+
+import { Directive, computed, signal, type OnChanges } from '@angular/core';
+import {
+  LIST_ACTION_KIND,
+  readLayoutLength,
+  readScrollOffset,
+  resolveAccessibilityProps,
+  type IAccessibilityProps,
+  type IAriaProps,
+} from '@symbiote-native/components';
+import {
+  dlog,
+  type IStyleProp,
+  type ISymbioteEvent,
+  type IViewStyle,
+} from '@symbiote-native/engine';
+import { countAngular } from '../../diagnostics';
+import { VirtualizedListHandleBase } from './list-handle';
+
+@Directive()
+export abstract class VirtualizedListBagsBase<ItemT>
+  extends VirtualizedListHandleBase<ItemT>
+  implements OnChanges
+{
+  resolvedStyle: IViewStyle | undefined = undefined;
+  resolvedContentContainerStyle: IStyleProp<IViewStyle> | undefined = undefined;
+  resolvedMaintainVisibleContentPosition:
+    | { minIndexForVisible: number; autoscrollToTopThreshold?: number }
+    | undefined = undefined;
+  // A fresh object per push, so the commit re-applies a repeated offset
+  commandedOffset: { x: number; y: number } | undefined = undefined;
+
+  // Only inputs may feed this signal, window state changes skip `ngOnChanges`
+  private readonly inputsRevision = signal(0);
+
+  // A computed hands back one object until an input changes, a getter rebuilt it per binding
+  readonly foldedAccessibility = computed<
+    IAccessibilityProps & IAriaProps & Record<string, unknown>
+  >(() => {
+    this.inputsRevision();
+    return resolveAccessibilityProps({
+      testID: this.testID,
+      nativeID: this.nativeID,
+      ...this.accessibilityInputProps(),
+    });
+  });
+
+  // The one moment every changed input is written, before `ngDoCheck`
+  ngOnChanges(): void {
+    this.inputsRevision.update(revision => revision + 1);
+  }
+
+  get shouldRenderRefreshControl(): boolean {
+    return this.refreshRequested ?? this.refresh.observed;
+  }
+
+  // A method, not a computed: most fields are plain and the directive diffs per key anyway
+  scrollViewBag(): Record<string, unknown> {
+    return {
+      ...this.foldedAccessibility(),
+      style: this.resolvedStyle,
+      contentContainerStyle: this.resolvedContentContainerStyle,
+      onScroll: this.onScrollTick,
+      onLayout: this.onLayoutTick,
+      onScrollBeginDrag: this.onScrollBeginDrag,
+      onScrollEndDrag: this.onScrollEndDrag,
+      onMomentumScrollBegin: this.onMomentumScrollBegin,
+      onMomentumScrollEnd: this.onMomentumScrollEnd,
+      scrollEventThrottle: this.scrollEventThrottle,
+      keyboardShouldPersistTaps: this.keyboardShouldPersistTaps,
+      keyboardDismissMode: this.keyboardDismissMode,
+      removeClippedSubviews: this.removeClippedSubviews,
+      nestedScrollEnabled: this.nestedScrollEnabled,
+      // Android moves the scrollbar back after the `scale: -1` flip
+      isInvertedVirtualizedList: this.isInverted ? true : undefined,
+      contentOffset: this.commandedOffset,
+      // `stickyHeaderIndices` is not forwarded, the cells carry the `sticky-header` tag instead
+      maintainVisibleContentPosition:
+        this.resolvedMaintainVisibleContentPosition,
+      // The tag has no `.observed`, so `wantsGate` decides whether the flag reaches Fabric
+      onAccessibilityAction: this.wantsGate('accessibilityAction')
+        ? this.accessibilityActionTick
+        : undefined,
+      onAccessibilityTap: this.wantsGate('accessibilityTap')
+        ? this.accessibilityTapTick
+        : undefined,
+      onMagicTap: this.wantsGate('magicTap') ? this.magicTapTick : undefined,
+      onAccessibilityEscape: this.wantsGate('accessibilityEscape')
+        ? this.accessibilityEscapeTick
+        : undefined,
+    };
+  }
+
+  refreshControlBag(): Record<string, unknown> {
+    return {
+      refreshing: this.refreshing ?? false,
+      progressViewOffset: this.progressViewOffset,
+      onRefresh: this.handleRefresh,
+    };
+  }
+
+  // `onScroll` stays a callback so an `Animated.event` target can flow through it
+  onScrollTick = (event: ISymbioteEvent): void => {
+    countAngular('scrollTicks');
+    const offset = readScrollOffset(event, this.isHorizontal);
+    if (offset === undefined) return;
+    dlog(`Angular VirtualizedList onScroll offset=${offset}`);
+    // A real native scroll supersedes any pending commanded offset
+    this.commandedOffset = undefined;
+    this.dispatch({ kind: LIST_ACTION_KIND.scroll, offset });
+    this.onScroll?.(event);
+  };
+
+  onLayoutTick = (event: ISymbioteEvent): void => {
+    const length = readLayoutLength(event, this.isHorizontal);
+    if (length === undefined) return;
+    dlog(`Angular VirtualizedList onLayout viewport=${length}`);
+    this.dispatch({ kind: LIST_ACTION_KIND.layout, length });
+  };
+
+  handleRefresh = (): void => {
+    this.refresh.emit();
+  };
+
+  accessibilityActionTick = (event: ISymbioteEvent): void => {
+    this.accessibilityAction.emit(event);
+  };
+
+  accessibilityTapTick = (event: ISymbioteEvent): void => {
+    this.accessibilityTap.emit(event);
+  };
+
+  magicTapTick = (event: ISymbioteEvent): void => {
+    this.magicTap.emit(event);
+  };
+
+  accessibilityEscapeTick = (event: ISymbioteEvent): void => {
+    this.accessibilityEscape.emit(event);
+  };
+}

package/src/components/virtualized-list/list-effects.ts

@@ -0,0 +1,116 @@
+// Runs the effects the shared list reducer hands back: scrolls, edge events and the two timers the
+// reducer only knows a delay for (the incremental fill and the viewability debounce)
+
+import {
+  EMPTY_OFFSET,
+  LIST_ACTION_KIND,
+  LIST_EFFECT_KIND,
+  type IListAction,
+  type IListEffect,
+  type IListReducerInputs,
+} from '@symbiote-native/components';
+
+type IEmitter<TValue> = { emit: (value: TValue) => void };
+
+export type IEffectHost<ItemT> = {
+  scrollToPixel: (offset: number, animated: boolean) => void;
+  dispatch: (action: IListAction<ItemT>) => void;
+  endReached: IEmitter<{ distanceFromEnd: number }>;
+  startReached: IEmitter<{ distanceFromStart: number }>;
+  scrollToIndexFailed: IEmitter<{
+    index: number;
+    highestMeasuredFrameIndex: number;
+    averageItemLength: number;
+  }>;
+};
+
+type IViewableEffect<ItemT> = Extract<
+  IListEffect<ItemT>,
+  { kind: typeof LIST_EFFECT_KIND.fireViewable }
+>;
+
+export class ListEffectRunner<ItemT> {
+  private viewableTimer: ReturnType<typeof setTimeout> | null = null;
+  private batchTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly host: IEffectHost<ItemT>) {}
+
+  run(effects: IListEffect<ItemT>[], inputs: IListReducerInputs<ItemT>): void {
+    for (const effect of effects) this.runOne(effect, inputs);
+  }
+
+  dispose(): void {
+    if (this.viewableTimer !== null) clearTimeout(this.viewableTimer);
+    if (this.batchTimer !== null) clearTimeout(this.batchTimer);
+  }
+
+  private runOne(
+    effect: IListEffect<ItemT>,
+    inputs: IListReducerInputs<ItemT>,
+  ): void {
+    switch (effect.kind) {
+      case LIST_EFFECT_KIND.scrollTo:
+        this.host.scrollToPixel(effect.offset, effect.animated);
+        break;
+      case LIST_EFFECT_KIND.fireEndReached:
+        this.host.endReached.emit({ distanceFromEnd: effect.distanceFromEnd });
+        break;
+      case LIST_EFFECT_KIND.fireStartReached:
+        this.host.startReached.emit({
+          distanceFromStart: effect.distanceFromStart,
+        });
+        break;
+      case LIST_EFFECT_KIND.fireScrollToIndexFailed:
+        this.host.scrollToIndexFailed.emit({
+          index: effect.index,
+          highestMeasuredFrameIndex: effect.highestMeasuredFrameIndex,
+          averageItemLength: effect.averageItemLength,
+        });
+        break;
+      case LIST_EFFECT_KIND.scheduleRefill:
+        this.scheduleRefill(effect.delay);
+        break;
+      case LIST_EFFECT_KIND.fireViewable:
+        this.fireViewable(effect, inputs);
+        break;
+    }
+  }
+
+  private scheduleRefill(delay: number): void {
+    if (this.batchTimer !== null) clearTimeout(this.batchTimer);
+    this.batchTimer = setTimeout(() => {
+      this.batchTimer = null;
+      this.host.dispatch({ kind: LIST_ACTION_KIND.batchTick });
+    }, delay);
+  }
+
+  private fireViewable(
+    effect: IViewableEffect<ItemT>,
+    inputs: IListReducerInputs<ItemT>,
+  ): void {
+    const fire = (): void => {
+      for (const pair of inputs.viewabilityPairs) {
+        pair.onViewableItemsChanged({
+          ...effect.info,
+          viewabilityConfig: pair.viewabilityConfig,
+        });
+      }
+      this.host.dispatch({
+        kind: LIST_ACTION_KIND.viewableFired,
+        map: effect.map,
+      });
+    };
+    if (this.viewableTimer !== null) {
+      clearTimeout(this.viewableTimer);
+      this.viewableTimer = null;
+    }
+    if (effect.delay <= EMPTY_OFFSET) {
+      fire();
+      return;
+    }
+    this.viewableTimer = setTimeout(() => {
+      this.viewableTimer = null;
+      fire();
+    }, effect.delay);
+  }
+}

package/src/components/virtualized-list/list-events.ts

@@ -0,0 +1,31 @@
+// The events every list component exposes, from `VirtualizedList` up to `SectionList`, so the
+// wrappers stop redeclaring them
+
+import { Directive, EventEmitter, Output } from '@angular/core';
+import { AccessibilityEventsBase } from '../../accessibility-events';
+import {
+  gateWanted,
+  injectGateDemandAbove,
+  type IGatedAccessibilityEvent,
+} from '../../gate-demand';
+
+@Directive()
+export abstract class ListEventsBase extends AccessibilityEventsBase {
+  // The edge and refresh events are real Angular events: `(endReached)`, not `[onEndReached]`
+  @Output() readonly endReached = new EventEmitter<{
+    distanceFromEnd: number;
+  }>();
+  @Output() readonly startReached = new EventEmitter<{
+    distanceFromStart: number;
+  }>();
+  @Output() readonly refresh = new EventEmitter<void>();
+
+  // A list binds the four gated accessibility events on what it renders, which Angular forces to be
+  // unconditional and which would light that component's gates on every instance. It answers for
+  // them instead, see `gate-demand.ts`
+  private readonly gateDemandAbove = injectGateDemandAbove();
+
+  wantsGate(name: IGatedAccessibilityEvent): boolean {
+    return gateWanted(this.gateDemandAbove, name, this[name]);
+  }
+}

package/src/components/virtualized-list/list-handle.ts

@@ -0,0 +1,92 @@
+// The imperative scroll surface of the list, kept apart so the component stays on windowing
+
+import { Directive } from '@angular/core';
+import {
+  EMPTY_OFFSET,
+  FIRST_INDEX,
+  LIST_ACTION_KIND,
+  type IListAction,
+  type IScrollViewHandle,
+  type IVirtualizedListHandle,
+} from '@symbiote-native/components';
+import type { ISymbioteNode } from '@symbiote-native/engine';
+import { VirtualizedListInputs } from './list-inputs';
+
+@Directive()
+export abstract class VirtualizedListHandleBase<ItemT>
+  extends VirtualizedListInputs<ItemT>
+  implements IVirtualizedListHandle
+{
+  protected abstract readonly scrollHandle: IScrollViewHandle;
+
+  protected abstract get scrollNode(): ISymbioteNode | null;
+
+  protected abstract dispatch(action: IListAction<ItemT>): void;
+
+  scrollToOffset(params: { offset: number; animated?: boolean }): void {
+    this.dispatch({
+      kind: LIST_ACTION_KIND.scrollToOffset,
+      offset: params.offset,
+      animated: params.animated ?? true,
+    });
+  }
+
+  scrollToIndex(params: {
+    index: number;
+    animated?: boolean;
+    viewOffset?: number;
+    viewPosition?: number;
+  }): void {
+    this.dispatch({
+      kind: LIST_ACTION_KIND.scrollToIndex,
+      index: params.index,
+      animated: params.animated ?? true,
+      viewPosition: params.viewPosition ?? FIRST_INDEX,
+      viewOffset: params.viewOffset ?? EMPTY_OFFSET,
+    });
+  }
+
+  scrollToItem(params: {
+    item: unknown;
+    animated?: boolean;
+    viewPosition?: number;
+  }): void {
+    this.dispatch({
+      kind: LIST_ACTION_KIND.scrollToItem,
+      item: params.item,
+      animated: params.animated ?? true,
+      viewPosition: params.viewPosition ?? FIRST_INDEX,
+    });
+  }
+
+  scrollToEnd(params?: { animated?: boolean }): void {
+    this.dispatch({
+      kind: LIST_ACTION_KIND.scrollToEnd,
+      animated: params?.animated ?? true,
+    });
+  }
+
+  flashScrollIndicators(): void {
+    this.scrollHandle.flashScrollIndicators();
+  }
+
+  getNativeScrollRef(): IScrollViewHandle | null {
+    return this.scrollNode !== null ? this.scrollHandle : null;
+  }
+
+  getScrollableNode(): IScrollViewHandle | null {
+    return this.scrollNode !== null ? this.scrollHandle : null;
+  }
+
+  getScrollResponder(): IScrollViewHandle | null {
+    return this.scrollNode !== null ? this.scrollHandle : null;
+  }
+
+  getScrollNode(): ISymbioteNode | null {
+    return this.scrollHandle.getScrollNode();
+  }
+
+  recordInteraction(): void {
+    this.dispatch({ kind: LIST_ACTION_KIND.recordInteraction });
+  }
+}

package/src/components/virtualized-list/list-inputs.ts

@@ -0,0 +1,149 @@
+// The list surface Angular binds statically: inputs, outputs and projected templates. Kept apart
+// from the components so the windowing lifecycle reads on its own
+
+import {
+  ContentChild,
+  Directive,
+  EventEmitter,
+  Input,
+  Output,
+  TemplateRef,
+} from '@angular/core';
+import {
+  DEFAULT_INITIAL_NUM_TO_RENDER,
+  DEFAULT_MAX_TO_RENDER_PER_BATCH,
+  DEFAULT_UPDATE_CELLS_BATCHING_PERIOD,
+  DEFAULT_WINDOW_SIZE,
+  type IViewabilityConfig,
+  type IViewabilityConfigCallbackPair,
+  type IViewableItemsChangedInfo,
+} from '@symbiote-native/components';
+import type {
+  IStyleProp,
+  ISymbioteEvent,
+  IViewStyle,
+} from '@symbiote-native/engine';
+import {
+  VListEmptyDirective,
+  VListFooterDirective,
+  VListHeaderDirective,
+  VListItemDirective,
+  VListSeparatorDirective,
+  type IVListItemContext,
+  type IVListSeparatorContext,
+} from './directives';
+import { ListEventsBase } from './list-events';
+
+// What `VirtualizedList` and `FlatList` share: the windowing inputs and the slot templates
+@Directive()
+export abstract class ListInputsBase<ItemT> extends ListEventsBase {
+  @Output() readonly viewableItemsChanged = new EventEmitter<
+    IViewableItemsChangedInfo<ItemT>
+  >();
+  @Output() readonly scrollToIndexFailed = new EventEmitter<{
+    index: number;
+    highestMeasuredFrameIndex: number;
+    averageItemLength: number;
+  }>();
+
+  @Input() keyExtractor?: (item: ItemT, index: number) => string;
+  @Input() getItemLayout?: (
+    data: unknown,
+    index: number,
+  ) => { length: number; offset: number; index: number };
+  @Input() horizontal?: boolean;
+  @Input() inverted?: boolean;
+  @Input() extraData?: unknown;
+  @Input() onEndReachedThreshold?: number;
+  @Input() onStartReachedThreshold?: number;
+  @Input() refreshing?: boolean | null;
+  @Input() progressViewOffset?: number;
+  @Input() viewabilityConfig?: IViewabilityConfig;
+  @Input()
+  viewabilityConfigCallbackPairs?: IViewabilityConfigCallbackPair<ItemT>[];
+  @Input() initialNumToRender?: number;
+  @Input() initialScrollIndex?: number;
+  @Input() maxToRenderPerBatch?: number;
+  @Input() updateCellsBatchingPeriod?: number;
+  @Input() windowSize?: number;
+  @Input() stickyHeaderIndices?: number[];
+  @Input() maintainVisibleContentPosition?: {
+    minIndexForVisible: number;
+    autoscrollToTopThreshold?: number;
+  };
+  @Input() onScroll?: (event: ISymbioteEvent) => void;
+  @Input() onScrollBeginDrag?: (event: ISymbioteEvent) => void;
+  @Input() onScrollEndDrag?: (event: ISymbioteEvent) => void;
+  @Input() onMomentumScrollBegin?: (event: ISymbioteEvent) => void;
+  @Input() onMomentumScrollEnd?: (event: ISymbioteEvent) => void;
+  @Input() scrollEventThrottle?: number;
+  @Input() keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
+  @Input() keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+  @Input() removeClippedSubviews?: boolean;
+  @Input() nestedScrollEnabled?: boolean;
+  @Input() style?: IStyleProp<IViewStyle>;
+  @Input() contentContainerStyle?: IStyleProp<IViewStyle>;
+  @Input() testID?: string;
+  @Input() nativeID?: string;
+
+  // The cell and slot templates the app authors, captured from projected <ng-template> content
+  @ContentChild(VListItemDirective) itemDir?: VListItemDirective<ItemT>;
+  @ContentChild(VListHeaderDirective) headerDir?: VListHeaderDirective;
+  @ContentChild(VListFooterDirective) footerDir?: VListFooterDirective;
+  @ContentChild(VListEmptyDirective) emptyDir?: VListEmptyDirective;
+  @ContentChild(VListSeparatorDirective)
+  separatorDir?: VListSeparatorDirective<ItemT>;
+
+  get isHorizontal(): boolean {
+    return this.horizontal === true;
+  }
+
+  protected get isInverted(): boolean {
+    return this.inverted === true;
+  }
+
+  protected get windowSizeValue(): number {
+    return this.windowSize ?? DEFAULT_WINDOW_SIZE;
+  }
+
+  protected get initialNumToRenderValue(): number {
+    return this.initialNumToRender ?? DEFAULT_INITIAL_NUM_TO_RENDER;
+  }
+
+  protected get maxToRenderPerBatchValue(): number {
+    return this.maxToRenderPerBatch ?? DEFAULT_MAX_TO_RENDER_PER_BATCH;
+  }
+
+  protected get updateCellsBatchingPeriodValue(): number {
+    return (
+      this.updateCellsBatchingPeriod ?? DEFAULT_UPDATE_CELLS_BATCHING_PERIOD
+    );
+  }
+}
+
+@Directive()
+export abstract class VirtualizedListInputs<
+  ItemT,
+> extends ListInputsBase<ItemT> {
+  @Input({ required: true }) data!: unknown;
+  @Input({ required: true }) getItem!: (data: unknown, index: number) => ItemT;
+  @Input({ required: true }) getItemCount!: (data: unknown) => number;
+  // Set by a wrapper (`FlatList`, `VirtualizedSectionList`) that always binds `(refresh)` here to
+  // re-forward the event, which keeps `refresh.observed` permanently true. The wrapper passes its
+  // own public `refresh.observed` instead, direct usage falls back to this component's own
+  @Input() refreshRequested?: boolean;
+
+  // A wrapping list hands its app's cell and separator templates straight in, so a cell is one
+  // outlet deep instead of a wrapper outlet around the app's own. Each wins over projection
+  @Input() itemTemplate?: TemplateRef<IVListItemContext<ItemT>>;
+  @Input() itemSeparatorTemplate?: TemplateRef<IVListSeparatorContext<ItemT>>;
+
+  get cellTemplate(): TemplateRef<IVListItemContext<ItemT>> | undefined {
+    return this.itemTemplate ?? this.itemDir?.templateRef;
+  }
+
+  get separatorTemplate():
+    TemplateRef<IVListSeparatorContext<ItemT>> | undefined {
+    return this.itemSeparatorTemplate ?? this.separatorDir?.templateRef;
+  }
+}

package/src/components/virtualized-list/list-props.ts

@@ -0,0 +1,81 @@
+// The public prop surface of the Angular VirtualizedList, kept apart from the component class
+
+import type {
+  IAccessibilityProps,
+  IAriaProps,
+  IViewabilityConfig,
+  IViewabilityConfigCallbackPair,
+  IViewableItemsChangedInfo,
+} from '@symbiote-native/components';
+import type {
+  IStyleProp,
+  ISymbioteEvent,
+  IViewStyle,
+} from '@symbiote-native/engine';
+
+// The React and Vue surface minus element-returning props, which are `<ng-template>` here
+export interface IVirtualizedListProps<ItemT>
+  extends IAccessibilityProps, IAriaProps {
+  data: unknown;
+  getItem: (data: unknown, index: number) => ItemT;
+  getItemCount: (data: unknown) => number;
+  keyExtractor?: (item: ItemT, index: number) => string;
+  getItemLayout?: (
+    data: unknown,
+    index: number,
+  ) => { length: number; offset: number; index: number };
+  horizontal?: boolean;
+  inverted?: boolean;
+  extraData?: unknown;
+  onEndReached?: (info: { distanceFromEnd: number }) => void;
+  onEndReachedThreshold?: number;
+  onStartReached?: (info: { distanceFromStart: number }) => void;
+  onStartReachedThreshold?: number;
+  onRefresh?: () => void;
+  refreshing?: boolean | null;
+  progressViewOffset?: number;
+  onViewableItemsChanged?: (info: IViewableItemsChangedInfo<ItemT>) => void;
+  viewabilityConfig?: IViewabilityConfig;
+  viewabilityConfigCallbackPairs?: IViewabilityConfigCallbackPair<ItemT>[];
+  onScrollToIndexFailed?: (info: {
+    index: number;
+    highestMeasuredFrameIndex: number;
+    averageItemLength: number;
+  }) => void;
+  initialNumToRender?: number;
+  initialScrollIndex?: number;
+  maxToRenderPerBatch?: number;
+  updateCellsBatchingPeriod?: number;
+  windowSize?: number;
+  stickyHeaderIndices?: number[];
+  maintainVisibleContentPosition?: {
+    minIndexForVisible: number;
+    autoscrollToTopThreshold?: number;
+  };
+  onScroll?: (event: ISymbioteEvent) => void;
+  onScrollBeginDrag?: (event: ISymbioteEvent) => void;
+  onScrollEndDrag?: (event: ISymbioteEvent) => void;
+  onMomentumScrollBegin?: (event: ISymbioteEvent) => void;
+  onMomentumScrollEnd?: (event: ISymbioteEvent) => void;
+  scrollEventThrottle?: number;
+  keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
+  keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+  removeClippedSubviews?: boolean;
+  nestedScrollEnabled?: boolean;
+  style?: IStyleProp<IViewStyle>;
+  contentContainerStyle?: IStyleProp<IViewStyle>;
+}
+
+// The plain inputs: the full surface minus the events exposed as real outputs
+export type IVirtualizedListInputs<ItemT> = Omit<
+  IVirtualizedListProps<ItemT>,
+  | 'onEndReached'
+  | 'onStartReached'
+  | 'onRefresh'
+  | 'onViewableItemsChanged'
+  | 'onScrollToIndexFailed'
+  | 'onAccessibilityAction'
+  | 'onAccessibilityTap'
+  | 'onMagicTap'
+  | 'onAccessibilityEscape'
+>;