@symbiote-native/angular 3.2.0 → 3.4.0

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

@@ -2,7 +2,6 @@
 // reducer only knows a delay for (the incremental fill and the viewability debounce)
 
 import {
-  EMPTY_OFFSET,
   LIST_ACTION_KIND,
   LIST_EFFECT_KIND,
   type IListAction,
@@ -24,13 +23,14 @@ export type IEffectHost<ItemT> = {
   }>;
 };
 
-type IViewableEffect<ItemT> = Extract<
-  IListEffect<ItemT>,
-  { kind: typeof LIST_EFFECT_KIND.fireViewable }
+type IScheduledViewable = Extract<
+  IListEffect<unknown>,
+  { kind: typeof LIST_EFFECT_KIND.scheduleViewable }
 >;
 
 export class ListEffectRunner<ItemT> {
-  private viewableTimer: ReturnType<typeof setTimeout> | null = null;
+  // RN never cancels a `minimumViewTime` timer, each one comes due and the reducer filters it
+  private readonly viewableTimers = new Set<ReturnType<typeof setTimeout>>();
   private batchTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(private readonly host: IEffectHost<ItemT>) {}
@@ -40,7 +40,8 @@ export class ListEffectRunner<ItemT> {
   }
 
   dispose(): void {
-    if (this.viewableTimer !== null) clearTimeout(this.viewableTimer);
+    for (const timer of this.viewableTimers) clearTimeout(timer);
+    this.viewableTimers.clear();
     if (this.batchTimer !== null) clearTimeout(this.batchTimer);
   }
 
@@ -71,7 +72,12 @@ export class ListEffectRunner<ItemT> {
         this.scheduleRefill(effect.delay);
         break;
       case LIST_EFFECT_KIND.fireViewable:
-        this.fireViewable(effect, inputs);
+        inputs.viewabilityPairs[effect.pairIndex]?.onViewableItemsChanged(
+          effect.info,
+        );
+        break;
+      case LIST_EFFECT_KIND.scheduleViewable:
+        this.scheduleViewable(effect);
         break;
     }
   }
@@ -84,33 +90,15 @@ export class ListEffectRunner<ItemT> {
     }, 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,
-        });
-      }
+  private scheduleViewable(effect: IScheduledViewable): void {
+    const timer = setTimeout(() => {
+      this.viewableTimers.delete(timer);
       this.host.dispatch({
-        kind: LIST_ACTION_KIND.viewableFired,
-        map: effect.map,
+        kind: LIST_ACTION_KIND.viewableDue,
+        pairIndex: effect.pairIndex,
+        indices: effect.indices,
       });
-    };
-    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);
+    this.viewableTimers.add(timer);
   }
 }

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

@@ -70,23 +70,36 @@ export abstract class VirtualizedListHandleBase<ItemT>
     this.scrollHandle.flashScrollIndicators();
   }
 
-  getNativeScrollRef(): IScrollViewHandle | null {
-    return this.scrollNode !== null ? this.scrollHandle : null;
+  // Null until the scroll tag commits, RN's "no scroll view yet" answer
+  private handleOrNull(): IScrollViewHandle | null {
+    return this.scrollNode === null ? null : this.scrollHandle;
+  }
+
+  getNativeScrollRef(): ISymbioteNode | null {
+    return this.scrollHandle.getScrollNode();
   }
 
   getScrollableNode(): IScrollViewHandle | null {
-    return this.scrollNode !== null ? this.scrollHandle : null;
+    return this.handleOrNull();
   }
 
   getScrollResponder(): IScrollViewHandle | null {
-    return this.scrollNode !== null ? this.scrollHandle : null;
+    return this.handleOrNull();
   }
 
   getScrollNode(): ISymbioteNode | null {
     return this.scrollHandle.getScrollNode();
   }
 
+  getScrollRef(): ISymbioteNode | null {
+    return this.scrollHandle.getScrollNode();
+  }
+
   recordInteraction(): void {
     this.dispatch({ kind: LIST_ACTION_KIND.recordInteraction });
   }
+
+  setNativeProps(props: Record<string, unknown>): void {
+    this.scrollNode?.setNativeProps(props);
+  }
 }

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

@@ -8,12 +8,16 @@ import {
   Input,
   Output,
   TemplateRef,
+  type Type,
 } from '@angular/core';
 import {
   DEFAULT_INITIAL_NUM_TO_RENDER,
   DEFAULT_MAX_TO_RENDER_PER_BATCH,
   DEFAULT_UPDATE_CELLS_BATCHING_PERIOD,
   DEFAULT_WINDOW_SIZE,
+  ITEM_RENDERER,
+  pickItemRenderer,
+  type IInnerViewRef,
   type IViewabilityConfig,
   type IViewabilityConfigCallbackPair,
   type IViewableItemsChangedInfo,
@@ -24,11 +28,13 @@ import type {
   IViewStyle,
 } from '@symbiote-native/engine';
 import {
+  VListCellDirective,
   VListEmptyDirective,
   VListFooterDirective,
   VListHeaderDirective,
   VListItemDirective,
   VListSeparatorDirective,
+  type IVListCellContext,
   type IVListItemContext,
   type IVListSeparatorContext,
 } from './directives';
@@ -66,6 +72,8 @@ export abstract class ListInputsBase<ItemT> extends ListEventsBase {
   @Input() maxToRenderPerBatch?: number;
   @Input() updateCellsBatchingPeriod?: number;
   @Input() windowSize?: number;
+  // Mounts every cell from the top and paints no spacer, the window only grows toward the end
+  @Input() disableVirtualization?: boolean;
   @Input() stickyHeaderIndices?: number[];
   @Input() maintainVisibleContentPosition?: {
     minIndexForVisible: number;
@@ -76,15 +84,23 @@ export abstract class ListInputsBase<ItemT> extends ListEventsBase {
   @Input() onScrollEndDrag?: (event: ISymbioteEvent) => void;
   @Input() onMomentumScrollBegin?: (event: ISymbioteEvent) => void;
   @Input() onMomentumScrollEnd?: (event: ISymbioteEvent) => void;
+  @Input() onContentSizeChange?: (width: number, height: number) => void;
   @Input() scrollEventThrottle?: number;
   @Input() keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
   @Input() keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
   @Input() removeClippedSubviews?: boolean;
   @Input() nestedScrollEnabled?: boolean;
+  @Input() stickyHeaderHiddenOnScroll?: boolean;
+  @Input() innerViewRef?: IInnerViewRef;
   @Input() style?: IStyleProp<IViewStyle>;
   @Input() contentContainerStyle?: IStyleProp<IViewStyle>;
+  @Input() listHeaderComponentStyle?: IStyleProp<IViewStyle>;
+  @Input() listFooterComponentStyle?: IStyleProp<IViewStyle>;
   @Input() testID?: string;
   @Input() nativeID?: string;
+  // RN's `ListItemComponent`: a component taking `item`, `index` and `separators` inputs, in place
+  // of the `vListItem` template, and it wins when both are given
+  @Input() listItemComponent?: Type<unknown>;
 
   // The cell and slot templates the app authors, captured from projected <ng-template> content
   @ContentChild(VListItemDirective) itemDir?: VListItemDirective<ItemT>;
@@ -93,11 +109,33 @@ export abstract class ListInputsBase<ItemT> extends ListEventsBase {
   @ContentChild(VListEmptyDirective) emptyDir?: VListEmptyDirective;
   @ContentChild(VListSeparatorDirective)
   separatorDir?: VListSeparatorDirective<ItemT>;
+  @ContentChild(VListCellDirective) cellDir?: VListCellDirective;
 
   get isHorizontal(): boolean {
     return this.horizontal === true;
   }
 
+  // The app's `vListCell`, which a list built on this one may replace with its own
+  get cellRendererTpl(): TemplateRef<IVListCellContext> | undefined {
+    return this.cellDir?.templateRef;
+  }
+
+  // The component to stamp per cell, RN's `_renderElement`: it wins over the item template, and a
+  // cell with neither throws
+  get itemComponent(): Type<unknown> | undefined {
+    const kind = pickItemRenderer({
+      hasRenderItem: this.hasItemTemplate,
+      hasComponent: this.listItemComponent !== undefined,
+    });
+    return kind === ITEM_RENDERER.component
+      ? this.listItemComponent
+      : undefined;
+  }
+
+  protected get hasItemTemplate(): boolean {
+    return this.itemDir !== undefined;
+  }
+
   protected get isInverted(): boolean {
     return this.inverted === true;
   }
@@ -137,11 +175,20 @@ export abstract class VirtualizedListInputs<
   // 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>>;
+  @Input() cellRendererTemplate?: TemplateRef<IVListCellContext>;
+
+  override get cellRendererTpl(): TemplateRef<IVListCellContext> | undefined {
+    return this.cellRendererTemplate ?? this.cellDir?.templateRef;
+  }
 
   get cellTemplate(): TemplateRef<IVListItemContext<ItemT>> | undefined {
     return this.itemTemplate ?? this.itemDir?.templateRef;
   }
 
+  protected override get hasItemTemplate(): boolean {
+    return this.cellTemplate !== undefined;
+  }
+
   get separatorTemplate():
     TemplateRef<IVListSeparatorContext<ItemT>> | undefined {
     return this.itemSeparatorTemplate ?? this.separatorDir?.templateRef;

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

@@ -3,6 +3,7 @@
 import type {
   IAccessibilityProps,
   IAriaProps,
+  IInnerViewRef,
   IViewabilityConfig,
   IViewabilityConfigCallbackPair,
   IViewableItemsChangedInfo,
@@ -14,57 +15,63 @@ import type {
 } 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;
+export type IVirtualizedListProps<ItemT> = 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;
+    disableVirtualization?: boolean;
+    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;
+    onContentSizeChange?: (width: number, height: number) => void;
+    scrollEventThrottle?: number;
+    keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
+    keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+    removeClippedSubviews?: boolean;
+    nestedScrollEnabled?: boolean;
+    stickyHeaderHiddenOnScroll?: boolean;
+    innerViewRef?: IInnerViewRef;
+    style?: IStyleProp<IViewStyle>;
+    contentContainerStyle?: IStyleProp<IViewStyle>;
+    listHeaderComponentStyle?: IStyleProp<IViewStyle>;
+    listFooterComponentStyle?: IStyleProp<IViewStyle>;
   };
-  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<

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

@@ -0,0 +1,66 @@
+// The rows the template stamps: the plan's spacers and cells, keyed so a window slide moves them
+
+import {
+  LIST_SEGMENT_KIND,
+  spacerStyleOf,
+  type IWindowPlan,
+} from '@symbiote-native/components';
+import type { IViewStyle } from '@symbiote-native/engine';
+import type { CellRegistry, IWindowCell } from './cell-registry';
+import type { IVListCellContext } from './directives';
+
+export type ISpacerRow = {
+  kind: typeof LIST_SEGMENT_KIND.spacer;
+  key: string;
+  style: IViewStyle;
+};
+
+export type ICellRow<ItemT> = {
+  kind: typeof LIST_SEGMENT_KIND.cell;
+  key: string;
+  cell: IWindowCell<ItemT>;
+  // Only when the app drew its own cell wrapper with `vListCell`
+  renderer: IVListCellContext | undefined;
+};
+
+export type IListRow<ItemT> = ISpacerRow | ICellRow<ItemT>;
+
+export type IRowsParams<ItemT> = {
+  windowPlan: IWindowPlan;
+  cells: CellRegistry<ItemT>;
+  count: number;
+  isHorizontal: boolean;
+  hasSeparators: boolean;
+  rendererFor: ((cell: IWindowCell<ItemT>) => IVListCellContext) | undefined;
+};
+
+// A cell and a spacer never share a row key, an item key cannot start with `spacer-`
+export function stampPlanRows<ItemT>(
+  params: IRowsParams<ItemT>,
+): IListRow<ItemT>[] {
+  const { windowPlan, cells, count, isHorizontal, hasSeparators, rendererFor } =
+    params;
+  return windowPlan.plan.segments.map((segment): IListRow<ItemT> => {
+    if (segment.kind === LIST_SEGMENT_KIND.spacer) {
+      return {
+        kind: segment.kind,
+        key: segment.key,
+        style: spacerStyleOf(segment.extent, isHorizontal),
+      };
+    }
+    // The separator gates on the last index of the data, not of the window, or a cell's height
+    // would shift as it slides past
+    const cell = cells.windowCell(
+      segment.index,
+      segment.key,
+      hasSeparators && segment.index < count - 1,
+      windowPlan.stickySet?.has(segment.index) === true,
+    );
+    return {
+      kind: segment.kind,
+      key: `cell-${segment.key}`,
+      cell,
+      renderer: rendererFor?.(cell),
+    };
+  });
+}

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

@@ -4,6 +4,7 @@
 import {
   INVERTED_X_STYLE,
   INVERTED_Y_STYLE,
+  cellStyleOf,
 } from '@symbiote-native/components';
 import {
   flattenStyle,
@@ -23,6 +24,8 @@ export type IListStyleInput = {
   hasHeader: boolean;
   style: IStyleProp<IViewStyle> | undefined;
   contentContainerStyle: IStyleProp<IViewStyle> | undefined;
+  listHeaderComponentStyle: IStyleProp<IViewStyle> | undefined;
+  listFooterComponentStyle: IStyleProp<IViewStyle> | undefined;
   // The class-derived style of the list's own anchor host
   anchorStyle: unknown;
   maintainVisibleContentPosition: IMaintainVisibleContentPosition | undefined;
@@ -34,9 +37,20 @@ export type IListStyles = {
   style: IViewStyle | undefined;
   contentContainerStyle: IStyleProp<IViewStyle> | undefined;
   cellStyle: IViewStyle | undefined;
+  // The slot wrappers counter-flip with an inverted list, then take the slot's own style
+  headerStyle: IViewStyle | undefined;
+  footerStyle: IViewStyle | undefined;
   maintainVisibleContentPosition: IMaintainVisibleContentPosition | undefined;
 };
 
+function slotStyle(
+  isInverted: boolean,
+  inversion: IViewStyle,
+  style: IStyleProp<IViewStyle> | undefined,
+): IViewStyle | undefined {
+  return flattenStyle(isInverted ? [inversion, style] : style);
+}
+
 export function resolveListStyles(input: IListStyleInput): IListStyles {
   const inversion = input.isHorizontal ? INVERTED_X_STYLE : INVERTED_Y_STYLE;
   const mvcp = input.maintainVisibleContentPosition;
@@ -49,7 +63,22 @@ export function resolveListStyles(input: IListStyleInput): IListStyles {
       input.anchorStyle,
       input.isInverted ? [inversion, input.style] : input.style,
     ]),
-    cellStyle: input.isInverted ? inversion : undefined,
+    cellStyle: flattenStyle(
+      cellStyleOf({
+        horizontal: input.isHorizontal,
+        inverted: input.isInverted,
+      }),
+    ),
+    headerStyle: slotStyle(
+      input.isInverted,
+      inversion,
+      input.listHeaderComponentStyle,
+    ),
+    footerStyle: slotStyle(
+      input.isInverted,
+      inversion,
+      input.listFooterComponentStyle,
+    ),
     maintainVisibleContentPosition:
       mvcp === undefined
         ? undefined