ink-framework 0.1.0-alpha.10 → 0.1.0-alpha.13

package/src/image.ts

@@ -12,17 +12,19 @@ export function Avatar({ src = "", unread = false, onPress, onLongPress }: {
   return createElement("Avatar", { src, unread, onPress, onLongPress });
 }
 
-function RowComponent<const D extends Destination>({ image, title, titleMaxLines, titleIcon, subtitle, subtitleIcon, href, url, onPress, onLongPress }: PressProps<D> & {
+function RowComponent<const D extends Destination>({ image, title, titleMaxLines, titleIcon, subtitle, subtitleIcon, selected, href, url, onPress, onLongPress }: PressProps<D> & {
   image?: string;
   title: string;
   titleMaxLines?: number;
   titleIcon?: IconAsset;
   subtitle?: string;
   subtitleIcon?: IconAsset;
+  /** Underlines the row's text block, such as for the current choice. */
+  selected?: boolean;
   onLongPress?: () => void;
 }) {
   return createElement("RowContent", {
-    image, title, titleMaxLines, titleIcon, subtitle, subtitleIcon,
+    image, title, titleMaxLines, titleIcon, subtitle, subtitleIcon, selected,
     onPress: pressHandler({ href, url, onPress }) ?? (onLongPress ? () => {} : undefined),
     onLongPress,
   });
@@ -30,16 +32,42 @@ function RowComponent<const D extends Destination>({ image, title, titleMaxLines
 
 export const Row = /* @__PURE__ */ memo(RowComponent) as typeof RowComponent;
 
+export type ImageCrop = { zoom: number; x: number; y: number };
+export type ImageOverlay = { src: string; x: number; y: number; width: number; height: number };
+
 export function Image(props: {
   src: string;
   width: number;
   height: number;
   fit?: "contain" | "cover";
+  /** Clockwise quarter turns. Reuses one decoded texture across rotation and fit changes. */
+  rotation?: 0 | 90 | 180 | 270;
+  background?: string;
+  /** Normalised centre in the rotated source, with zoom relative to cover (1–4). */
+  crop?: ImageCrop;
+  /** Native gesture updates, delivered before subsequent press callbacks. */
+  onCropChange?: (crop: ImageCrop) => void;
+  /** Dashed horizontal guides at normalised frame positions (0–1), independent of crop. */
+  horizontalGuides?: readonly number[];
+  /** Transparent image in normalised frame coordinates, independent of crop and rotation. */
+  overlay?: ImageOverlay;
   bleed?: boolean;
   /** Fill the available content width, using width and height as the aspect ratio. */
   fillWidth?: boolean;
   zoomable?: boolean;
   loop?: boolean;
+  /** Up to two sources decoded ahead at this image's size, such as neighbouring photos. */
+  preload?: readonly string[];
+  onPress?: () => void;
+  /** A play triangle centred over the image, such as on a video poster. */
+  playIcon?: boolean;
+  /** A video from `useVideo` drawn over this image, such as over its poster frame. */
+  videoController?: number | null;
+  /** A horizontal swipe: `"next"` when swiped left, `"previous"` when swiped right. */
+  onSwipe?: (direction: "next" | "previous") => void;
+  /** Whether a swipe can continue in each direction. Both default to true. */
+  hasNext?: boolean;
+  hasPrevious?: boolean;
 }) {
   return createElement("Image", props);
 }

package/src/index.ts

@@ -13,7 +13,19 @@ export { useAction, type Action } from "./action";
 export { NativeError } from "./native";
 export { Tabs, Slot, navigate, replace, back, useRouteParams, type Destination } from "./navigation";
 
-export function Screen({ header, children, leftAction, rightAction, ...props }: {
+export type ActionBarItem = { icon?: IconAsset; label?: string; onPress: () => void; disabled?: boolean } | null;
+
+/** @internal Host props for a bottom action bar of up to three slots. */
+export function actionBarProps(items: readonly ActionBarItem[] | undefined) {
+  if (!items) return {};
+  const props: Record<string, unknown> = {
+    actionBar: items.map(item => item && { icon: item.icon, label: item.label, disabled: item.disabled ?? false }),
+  };
+  items.forEach((item, index) => { if (item && !item.disabled) props[`onAction${index}`] = item.onPress; });
+  return props;
+}
+
+export function Screen({ header, children, overlay, leftAction, rightAction, actionBar, ...props }: {
   children?: ReactNode;
   header?: ReactNode;
   title?: string;
@@ -21,15 +33,29 @@ export function Screen({ header, children, leftAction, rightAction, ...props }:
   centered?: boolean;
   wide?: boolean;
   bottomInset?: boolean;
-  waitForImages?: boolean;
   leftAction?: { icon: IconAsset; onPress: () => void };
   rightAction?: { icon: IconAsset; onPress: () => void };
+  /** Up to three actions in equal slots along the bottom; `null` leaves a slot empty. */
+  actionBar?: readonly ActionBarItem[];
+  /** `"auto"` hides the scrollbar until the page scrolls. */
+  scrollBar?: "auto";
+  /** Hides the header and action bar while keeping their space, so content stays in place. */
+  immersive?: boolean;
+  /** Lets content fill the screen, with the header and action bar drawn over it. */
+  overlayBars?: boolean;
+  /** Content above the bottom action bar, such as video progress. Hidden in immersive mode. */
+  overlay?: ReactNode;
+  /** Makes the title pressable, such as to choose what the page shows. */
+  onTitlePress?: () => void;
+  /** An icon after the title, such as a chevron for `onTitlePress`. */
+  titleIcon?: IconAsset;
 }) {
   const [scrollToEnd, setScrollToEnd] = useState(0);
   const requestEnd = useMemo(() => () => setScrollToEnd(value => value + 1), []);
-  return createElement(ScrollToEndContext.Provider, { value: requestEnd }, createElement("Screen", { ...props, scrollToEnd, pinnedHeader: header != null, leftIcon: leftAction?.icon, onLeftPress: leftAction?.onPress, rightIcon: rightAction?.icon, onRightPress: rightAction?.onPress },
+  return createElement(ScrollToEndContext.Provider, { value: requestEnd }, createElement("Screen", { ...props, ...actionBarProps(actionBar), scrollToEnd, pinnedHeader: header != null, leftIcon: leftAction?.icon, onLeftPress: leftAction?.onPress, rightIcon: rightAction?.icon, onRightPress: rightAction?.onPress },
     header != null && createElement(Stack, { gap: 47 }, header),
     children,
+    overlay != null && createElement("ScreenOverlay", null, overlay),
   ));
 }
 
@@ -91,10 +117,11 @@ export function Button<const D extends Destination>(props: PressProps<D> & {
 }
 
 export { Row, Image, Avatar } from "./image";
-export { Canvas, Rectangle, CanvasText, CanvasIcon } from "./canvas";
+export { Canvas, Rectangle, CanvasPath, CanvasRange, CanvasText, CanvasIcon } from "./canvas";
 
 export function Field<const D extends Destination>(props: PressProps<D> & {
   label: string;
+  disabled?: boolean;
   children?: ReactNode;
 }) {
   const { href, url, onPress, ...rest } = props;

package/src/jsx-runtime.ts

@@ -0,0 +1,21 @@
+import { Fragment, options, type ComponentType, type VNode } from "preact";
+export { Fragment };
+let nextId = 0;
+
+/** Preact's vnode contract without unused browser/debug fields on every node. */
+export function jsx(type: string | ComponentType, incoming: Record<string, unknown> | null, key?: string) {
+  let props = incoming ?? {};
+  let ref: unknown;
+  if ("ref" in props) {
+    ({ ref, ...props } = props);
+  }
+  if (typeof type === "function" && type.defaultProps) {
+    for (const name in type.defaultProps) {
+      if (props[name] === undefined) props[name] = (type.defaultProps as Record<string, unknown>)[name];
+    }
+  }
+  const vnode = { type, props, key, ref, constructor: undefined, __v: --nextId } as unknown as VNode;
+  if (typeof type === "function") options.vnode?.(vnode);
+  return vnode;
+}
+export { jsx as jsxs, jsx as jsxDEV };

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);
 }