ink-framework 0.1.0-alpha.12 → 0.1.0-alpha.14

package/src/list.ts

@@ -5,9 +5,7 @@ import { Button, Stack, Text } from "./index";
 import { CompiledList, nativeListPlan } from "./native-list";
 import { ScrollToEndContext } from "./scroll";
 
-const OLDER_PAGE_AHEAD_ITEMS = 8;
-
-export function ListLoadError({ message, onRetry }: { message: string; onRetry: () => void }) {
+function ListLoadError({ message, onRetry }: { message: string; onRetry: () => void }) {
   return createElement(Stack, { gap: 24 },
     createElement(Text, { size: 18 }, message),
     createElement(Button, { onPress: onRetry }, "Try again"),
@@ -28,7 +26,65 @@ export type ListProps<T> = {
   initialPosition?: "start" | "end";
 };
 
+type PaginationProps = Pick<ListProps<unknown>, "onLoadMore" | "hasMore" | "onLoadOlder" | "hasOlder">;
+export type ListPagination = ReturnType<typeof useListPagination>;
+
+function useListPage(load: (() => Promise<void>) | undefined, available: boolean) {
+  const accepted = useRef<string | undefined>(undefined);
+  const action = useAction((edge?: string) => {
+    // useAction may decline a pending request; record acceptance only when it starts.
+    if (edge !== undefined) accepted.current = edge;
+    return load?.();
+  });
+  return {
+    available: available && action.status !== "error",
+    enabled: !!load,
+    pending: action.status === "pending",
+    error: action.status === "error" ? action.error : undefined,
+    retry: () => action.run(),
+    request(edge: string) {
+      if (available && load && action.status !== "pending" && action.status !== "error" && accepted.current !== edge) action.run(edge);
+    },
+  };
+}
+
+function useListPagination({ onLoadMore, hasMore = false, onLoadOlder, hasOlder = false }: PaginationProps) {
+  const more = useListPage(onLoadMore, hasMore);
+  const older = useListPage(onLoadOlder, hasOlder);
+  return {
+    more,
+    older,
+    wrap(list: ReactNode) {
+      return createElement(Fragment, null,
+        older.error && createElement(ListLoadError, { message: older.error.message, onRetry: older.retry }),
+        list,
+        more.error && createElement(ListLoadError, { message: more.error.message, onRetry: more.retry }),
+      );
+    },
+  };
+}
+
+export function useListPaginationEvents(pagination: ListPagination, paused: boolean, count: number, first?: string, last?: string) {
+  const [startRequest, setStartRequest] = useState<string>();
+  const [endRequest, setEndRequest] = useState<string>();
+  const start = JSON.stringify([count, first ?? null]);
+  const end = JSON.stringify([count, last ?? null]);
+  useEffect(() => {
+    if (!paused && startRequest === start) pagination.older.request(startRequest);
+    if (!paused && endRequest === end) pagination.more.request(endRequest);
+  }, [pagination, paused, startRequest, endRequest, start, end]);
+  return {
+    hasMore: !paused && pagination.more.available && !pagination.more.pending,
+    hasOlder: !paused && pagination.older.available && !pagination.older.pending,
+    moreAvailable: pagination.more.available && pagination.more.enabled,
+    // Retain notifications even when the current commit cannot start loading yet.
+    onEndReached: setEndRequest,
+    onStartReached: setStartRequest,
+  };
+}
+
 export function List<T>(props: ListProps<T>) {
+  const pagination = useListPagination(props);
   const requestEnd = useContext(ScrollToEndContext);
   const initialised = useRef(false);
   useLayoutEffect(() => {
@@ -37,10 +93,12 @@ export function List<T>(props: ListProps<T>) {
     if (props.initialPosition === "end") requestEnd?.();
   }, [props.initialPosition, props.items.length, requestEnd]);
   const plan = nativeListPlan(props.renderItem);
-  return plan ? createElement(CompiledList<T>, { ...props, plan, key: plan.template }) : createElement(ReactList<T>, props);
+  return pagination.wrap(plan
+    ? createElement(CompiledList<T>, { ...props, pagination, plan, key: plan.template })
+    : createElement(ReactList<T>, { ...props, pagination }));
 }
 
-export function ReactList<T>({ items, keyExtractor, renderItem, gap = 47, followEnd = false, measurementKey, onLoadMore, hasMore = false, onLoadOlder, hasOlder = false, initialPosition = "start" }: ListProps<T>) {
+export function ReactList<T>({ items, keyExtractor, renderItem, gap = 47, followEnd = false, measurementKey, initialPosition = "start", pagination }: ListProps<T> & { pagination: ListPagination }) {
   if (!Number.isFinite(gap) || gap < 0) {
     throw new Error("List gap must be finite and non-negative");
   }
@@ -51,11 +109,7 @@ export function ReactList<T>({ items, keyExtractor, renderItem, gap = 47, follow
     items: readonly T[]; keys: string[]; contentVersions: number[]; revision: number;
     records: Map<string, { item: T; version: number }>;
   } | null>(null);
-  const [window, setWindow] = useState({ start: initialPosition === "end" ? Math.max(0, items.length - 32) : 0, end: initialPosition === "end" ? items.length : 32, revision: 0, nearEnd: false });
-  const requested = useRef<string | null>(null);
-  const load = useAction(() => onLoadMore?.());
-  const olderRequested = useRef<string | null>(null);
-  const older = useAction(() => onLoadOlder?.());
+  const [window, setWindow] = useState({ start: initialPosition === "end" ? Math.max(0, items.length - 32) : 0, end: initialPosition === "end" ? items.length : 32, revision: 0 });
   let start = Math.min(window.start, items.length);
   let end = Math.min(window.end, items.length);
   if (initialWindow.current && items.length) {
@@ -80,12 +134,12 @@ export function ReactList<T>({ items, keyExtractor, renderItem, gap = 47, follow
       throw new Error("List metadata exceeds 128 KiB; use shorter keys or a bounded data window");
     }
     if (initialWindow.current && items.length) {
-      if (start !== window.start || end !== window.end) setWindow({ start, end, revision, nearEnd: false });
+      if (start !== window.start || end !== window.end) setWindow({ start, end, revision });
     } else if (old && window.revision !== revision && old.keys[window.start] !== undefined) {
       const mapped = keys.indexOf(old.keys[window.start]);
       start = mapped < 0 ? Math.min(window.start, Math.max(0, items.length - 1)) : mapped;
       end = Math.min(start + window.end - window.start, items.length);
-      if (start !== window.start || end !== window.end) setWindow({ start, end, revision, nearEnd: false });
+      if (start !== window.start || end !== window.end) setWindow({ start, end, revision });
     }
     data = { items, keys, keyExtractor, contentVersions, revision, records, measurementKey };
   }
@@ -95,40 +149,23 @@ export function ReactList<T>({ items, keyExtractor, renderItem, gap = 47, follow
     if (items.length) initialWindow.current = false;
   });
   const { revision, contentVersions } = data;
-  const boundary = JSON.stringify([keys.length, keys.at(-1)]);
-  useEffect(() => {
-    if (!onLoadMore || !hasMore || load.status === "pending" || load.status === "error"
-      || window.revision !== revision || !window.nearEnd || requested.current === boundary) return;
-    requested.current = boundary;
-    load.run();
-  }, [onLoadMore, hasMore, load.status, load.run, window, revision, boundary]);
-  const firstBoundary = JSON.stringify([keys.length, keys[0]]);
-  useEffect(() => {
-    if (!onLoadOlder || !hasOlder || older.status === "pending" || older.status === "error"
-      || window.revision !== revision || window.start > OLDER_PAGE_AHEAD_ITEMS || olderRequested.current === firstBoundary) return;
-    olderRequested.current = firstBoundary;
-    older.run();
-  }, [onLoadOlder, hasOlder, older.status, older.run, window, revision, firstBoundary]);
+  const paginationProps = useListPaginationEvents(pagination, window.revision !== revision, keys.length, keys[0], keys.at(-1));
   const children: ReactNode[] = [];
   for (let index = start; index < end; index++) {
     children.push(createElement("Stack", { key: keys[index], axis: "vertical", align: "stretch" }, renderItem(items[index], index)));
   }
   const props = {
+    ...paginationProps,
     keys: data.keys,
     contentVersions,
     revision,
     gap,
     followEnd,
     start,
-    onWindow(start: number, end: number, eventRevision: number, nearEnd: boolean) {
+    onWindow(start: number, end: number, eventRevision: number) {
       if (eventRevision !== revision) return;
-      setWindow(previous => previous.start === start && previous.end === end && previous.revision === eventRevision && previous.nearEnd === nearEnd ? previous : { start, end, revision: eventRevision, nearEnd });
+      setWindow(previous => previous.start === start && previous.end === end && previous.revision === eventRevision ? previous : { start, end, revision: eventRevision });
     },
   };
-  const list = createElement("List", props, children);
-  return createElement(Fragment, null,
-    older.status === "error" && createElement(ListLoadError, { message: older.error.message, onRetry: older.run }),
-    list,
-    load.status === "error" && createElement(ListLoadError, { message: load.error.message, onRetry: load.run }),
-  );
+  return createElement("List", props, children);
 }

package/src/native-list.ts

@@ -1,10 +1,11 @@
-import { createElement, Fragment, useLayoutEffect, useMemo, useRef, useState, type ComponentProps, type ReactNode } from "./react";
-import { ListLoadError, ReactList, type ListProps } from "./list";
-import { useAction } from "./action";
+import { createElement, useLayoutEffect, useMemo, useRef, useState, type ComponentProps, type ReactNode } from "./react";
+import { ReactList, useListPaginationEvents, type ListPagination, type ListProps } from "./list";
 import type { Row } from "./image";
 import { pressHandler } from "./press";
 import { rememberListPatch, type NativeListItem } from "./list-patch";
 
+export { fixedListRow } from "./fixed-list-row";
+
 type Captured = { value: unknown; prototype?: object | null; fields?: [PropertyKey, boolean, Captured][] };
 type Scope = { identity: string; values: readonly Captured[] };
 type Capture = { identity: string; values: () => readonly unknown[]; usesIndex?: boolean };
@@ -73,7 +74,7 @@ export function listText(parts: unknown[]): string {
 export function listRowFields(props: ComponentProps<typeof Row>) {
   return { image: props.image, title: props.title, titleMaxLines: props.titleMaxLines,
     titleIcon: props.titleIcon, subtitle: props.subtitle, subtitleIcon: props.subtitleIcon,
-    onLongPress: props.onLongPress,
+    selected: props.selected, onLongPress: props.onLongPress,
     onPress: pressHandler(props) ?? (props.onLongPress ? () => {} : undefined) };
 }
 
@@ -286,11 +287,9 @@ export function nativeListPlan<T>(render: ListProps<T>["renderItem"]): Plan<T> |
   return plans.get(render) as Plan<T> | undefined;
 }
 
-export function CompiledList<T>({ plan, ...props }: ListProps<T> & { plan: Plan<T> }) {
-  const { items, keyExtractor, gap = 47, followEnd, initialPosition, measurementKey, onLoadMore, onLoadOlder, hasMore = false, hasOlder = false } = props;
+export function CompiledList<T>({ plan, pagination, ...props }: ListProps<T> & { plan: Plan<T>; pagination: ListPagination }) {
+  const { items, keyExtractor, gap = 47, followEnd, initialPosition, measurementKey } = props;
   if (!Number.isFinite(gap) || gap < 0) throw new Error("List gap must be finite and non-negative");
-  const load = useAction(() => onLoadMore?.());
-  const older = useAction(() => onLoadOlder?.());
   const committed = useRef<Records<T> | null>(null);
   const committedRequest = useRef<Request<T> | null>(null);
   const committedPlan = useRef<Plan<T> | null>(null);
@@ -388,14 +387,13 @@ export function CompiledList<T>({ plan, ...props }: ListProps<T> & { plan: Plan<
       if (timer !== undefined) clearTimeout(timer);
     };
   }, [request]);
+  const paginationProps = useListPaginationEvents(pagination, preparing || !records,
+    records?.data.length ?? 0, records?.data[0]?.key, records?.data.at(-1)?.key);
   if (outcome?.status === "error") throw outcome.error;
-  if (!records) return createElement(ReactList<T>, props);
+  if (!records) return createElement(ReactList<T>, { ...props, pagination });
   const nativeProps = {
     items: records.data, keyField: "key", template: records.template, gap, followEnd, initialEnd: initialPosition === "end",
-    hasMore: !preparing && hasMore && load.status !== "pending" && load.status !== "error",
-    hasOlder: !preparing && hasOlder && older.status !== "pending" && older.status !== "error",
-    onEndReached: !preparing && onLoadMore ? load.run : undefined,
-    onStartReached: !preparing && onLoadOlder ? older.run : undefined,
+    ...paginationProps,
     onRowEvent(key: string, target: number, name: string, ...args: unknown[]) {
       const latest = events.current;
       const path = latest?.targets.get(target)?.[name];
@@ -432,11 +430,7 @@ export function CompiledList<T>({ plan, ...props }: ListProps<T> & { plan: Plan<
       if (typeof callback === "function") callback(...args);
     },
   };
-  return createElement(Fragment, null,
-    older.status === "error" && createElement(ListLoadError, { message: older.error.message, onRetry: older.run }),
-    createElement("NativeList", nativeProps),
-    load.status === "error" && createElement(ListLoadError, { message: load.error.message, onRetry: load.run }),
-  );
+  return createElement("NativeList", nativeProps);
 }
 
 /** @internal Fixed native descriptions for Ink's own list components. */

package/src/native.ts

@@ -34,6 +34,14 @@ Object.defineProperty(globalThis, "__inkReceive", {
   },
 });
 
+Object.defineProperty(globalThis, "__inkResolveNativeResult", {
+  value: (id: number, value?: string, kind?: string, message?: string, retryable?: boolean) => {
+    listeners.get("result")?.(typeof value === "string"
+      ? { id, type: "result", value }
+      : { id, kind, message, retryable, type: "result" });
+  },
+});
+
 onNativeMessage("result", message => {
   if (typeof message.id !== "number") throw new Error("Invalid native result ID");
   const request = pending.get(message.id);

package/src/playing.ts

@@ -2,7 +2,7 @@ import { createElement, useRef } from "./react";
 import { Screen, ErrorState, type IconAsset } from "./index";
 import { useAction } from "./action";
 import { playbackController } from "./playback-binding";
-import { forward10Filled, forward30Filled, forward5Filled, pauseFilled, playArrowFilled, replay10Filled, replay30Filled, replay5Filled, skipNextFilled, skipPreviousFilled } from "./icons";
+import { forward10Filled, forward15Filled, forward30Filled, forward5Filled, pauseFilled, playArrowFilled, replay10Filled, replay15Filled, replay30Filled, replay5Filled, skipNextFilled, skipPreviousFilled } from "./icons";
 
 type PlaybackAction = () => void | Promise<void>;
 export interface Playback {
@@ -17,7 +17,7 @@ export interface Playback {
 
 export type TransportControl = { onLongPress?: PlaybackAction; disabled?: boolean } & (
   | { kind: "track"; seconds?: never; icon?: never; onPress?: never }
-  | { kind: "skip"; seconds: 5 | 10 | 30; icon?: never; onPress?: never }
+  | { kind: "skip"; seconds: 5 | 10 | 15 | 30; icon?: never; onPress?: never }
   | { kind: "custom"; icon: IconAsset; onPress: PlaybackAction; seconds?: never }
 );
 export type PlayingScreenProps = {
@@ -32,8 +32,8 @@ export type PlayingScreenProps = {
   actions?: readonly (({ icon: IconAsset; label?: never } | { label: string; icon?: never }) & { selected?: boolean; disabled?: boolean; onPress: PlaybackAction })[];
 };
 
-const replayIcons = { 5: replay5Filled, 10: replay10Filled, 30: replay30Filled };
-const forwardIcons = { 5: forward5Filled, 10: forward10Filled, 30: forward30Filled };
+const replayIcons = { 5: replay5Filled, 10: replay10Filled, 15: replay15Filled, 30: replay30Filled };
+const forwardIcons = { 5: forward5Filled, 10: forward10Filled, 15: forward15Filled, 30: forward30Filled };
 
 export function PlayingScreen({ image, preloadImages = [], title, onTitlePress, artists, playback, previous = { kind: "track" }, next = { kind: "track" }, actions = [] }: PlayingScreenProps) {
   const retry = useRef<PlaybackAction>(() => {});

package/src/prefresh.d.ts

@@ -0,0 +1,3 @@
+declare module "@prefresh/utils" {
+  export function flush(): void;
+}

package/src/react-compat.ts

@@ -0,0 +1,24 @@
+import React from "preact/compat";
+import { cloneElement, isValidElement } from "preact";
+import { Activity, useEffect, useLayoutEffect, useSyncExternalStore, useImperativeHandle } from "./visibility";
+import { useRef, useCallback, useLayoutEffect as commitLayoutEffect } from "preact/hooks";
+const compatibleReact = /* @__PURE__ */ Object.assign({}, React, { Activity, cloneElement, isValidElement, useEffect, useLayoutEffect, useSyncExternalStore, useImperativeHandle, useEffectEvent });
+export default compatibleReact;
+export {
+  Children, Component, Fragment, PureComponent, StrictMode, Suspense, SuspenseList,
+  createContext, createElement, createFactory, createPortal, createRef,
+  findDOMNode, flushSync, forwardRef, hydrate, lazy, memo, render,
+  startTransition, unmountComponentAtNode, unstable_batchedUpdates,
+  useCallback, useContext, useDebugValue, useDeferredValue,
+  useId, useInsertionEffect, useMemo, useReducer,
+  useRef, useState, useTransition, version,
+} from "preact/compat";
+export { cloneElement, isValidElement } from "preact";
+export { Activity, useEffect, useLayoutEffect, useSyncExternalStore, useImperativeHandle } from "./visibility";
+
+/** Effect events retain their identity and read the latest committed callback. */
+export function useEffectEvent<T extends (...args: never[]) => unknown>(callback: T): T {
+  const current = useRef(callback);
+  commitLayoutEffect(() => { current.current = callback; });
+  return useCallback(((...args: Parameters<T>) => current.current(...args)) as T, []);
+}

package/src/react.ts

@@ -1,6 +1,26 @@
-// Share the CommonJS React import so unused component modules contribute no wrapper code.
-export {
-  Activity, Children, Fragment, createContext, createElement, isValidElement, memo,
-  useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState,
-  useSyncExternalStore, type ComponentProps, type ReactElement, type ReactNode,
-} from "react";
+import { createElement as element, createContext as context, isValidElement as valid, Fragment as fragment, Component, type ComponentChildren } from "preact";
+import { useCallback, useContext as contextValue, useMemo, useRef, useState } from "preact/hooks";
+import type * as React from "react";
+
+// Keep the public React declarations while executing Preact core in Ink.
+export const createElement = element as unknown as typeof React.createElement;
+export const createContext = context as unknown as typeof React.createContext;
+export const useContext = contextValue as unknown as typeof React.useContext;
+export const isValidElement = valid as unknown as typeof React.isValidElement;
+export const Fragment = fragment as unknown as typeof React.Fragment;
+export { Children } from "preact/compat";
+export { useCallback, useMemo, useRef, useState };
+export { Activity, useEffect, useLayoutEffect, useSyncExternalStore } from "./visibility";
+export type { ComponentProps, ComponentType, ReactElement, ReactNode } from "react";
+
+// A single core component avoids compat memo's extra function-component layer.
+export function memo<P extends object>(render: (props: P) => React.ReactNode) {
+  return class extends Component<P> {
+    shouldComponentUpdate(next: P) {
+      const previous = this.props;
+      const keys = Object.keys(next) as (keyof P)[];
+      return keys.length !== Object.keys(previous).length || keys.some(key => !Object.is(previous[key], next[key]));
+    }
+    render() { return render(this.props) as ComponentChildren; }
+  } as unknown as (props: P) => React.ReactNode;
+}

package/src/refresh.ts

@@ -0,0 +1,29 @@
+import "@prefresh/core";
+import { flush } from "@prefresh/utils";
+
+declare const self: { __PREFRESH__: {
+  register(type: unknown, id: string): void;
+  sign(type: unknown, key: string, forceReset: boolean, getCustomHooks: (() => unknown[]) | undefined, status: string): string;
+} };
+
+export const register = (type: unknown, id: string) => self.__PREFRESH__.register(type, id);
+export const performReactRefresh = flush;
+
+// Oxc emits React Refresh's signature protocol; translate it to Prefresh.
+export function createSignatureFunctionForTransform() {
+  let savedType: unknown;
+  let savedKey = "";
+  let savedReset = false;
+  let savedHooks: (() => unknown[]) | undefined;
+  let status = "begin";
+  return (type?: unknown, key?: string, forceReset = false, getCustomHooks?: () => unknown[]) => {
+    if (type) {
+      savedType = type;
+      savedKey = key ?? "";
+      savedReset = forceReset;
+      savedHooks = getCustomHooks;
+    }
+    status = self.__PREFRESH__.sign(savedType, savedKey, savedReset, savedHooks, status);
+    return type;
+  };
+}