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

package/ink-native.json

@@ -9,6 +9,10 @@
     ],
     "src/media.ts": [
       "media-library"
+    ],
+    "src/library.ts": [
+      "media-library",
+      "media-library-manage"
     ]
   }
 }

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "ink-framework-files",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.13",
   "exports": {
     ".": "./src/index.ts",
     "./images": "./src/images.ts",
-    "./media": "./src/media.ts"
+    "./media": "./src/media.ts",
+    "./library": "./src/library.ts"
   },
   "peerDependencies": {
-    "ink": "npm:ink-framework@0.1.0-alpha.10",
+    "ink": "npm:ink-framework@0.1.0-alpha.13",
     "react": "19.2.8"
   },
   "dependencies": {
-    "@ink/lightos": "npm:ink-framework-lightos@0.1.0-alpha.10"
+    "@ink/lightos": "npm:ink-framework-lightos@0.1.0-alpha.13"
   },
   "license": "MIT",
   "repository": {
@@ -22,6 +23,7 @@
   "files": [
     "src",
     "*.json",
-    "*.ts"
+    "*.ts",
+    "*.md"
   ]
 }

package/src/library.ts

@@ -0,0 +1,133 @@
+import { createElement, type ReactNode } from "ink/internal/react";
+import { actionBarProps, type ActionBarItem, type IconAsset } from "ink";
+import { callNative, NativeError, onNativeMessage } from "ink/native";
+import { MediaGridView } from "./media-grid";
+
+export type MediaKind = "image" | "video" | "all";
+
+export type MediaItem = {
+  id: string;
+  src: string;
+  name: string;
+  mimeType: string;
+  width: number;
+  height: number;
+  /** Seconds since the epoch when the item was added to the library. */
+  added: number;
+  duration?: number;
+};
+
+export type MediaPage = { items: MediaItem[]; nextCursor: string | null; version: string };
+export type MediaCounts = { all: number; image: number; video: number; groups: Record<string, number> };
+
+function decodeItem(item: unknown): MediaItem {
+  if (typeof item !== "object" || item === null || !["id", "src", "name", "mimeType"].every(key => typeof Reflect.get(item, key) === "string")
+    || !["width", "height", "added"].every(key => typeof Reflect.get(item, key) === "number")) throw new NativeError("protocol", "Invalid media item");
+  return item as MediaItem;
+}
+
+export const mediaLibrary = {
+  /** Newest additions first. Pass the previous page's `nextCursor` to continue. */
+  async list(options: { kind?: MediaKind; ids?: readonly string[]; cursor?: string | null; limit?: number; signal?: AbortSignal } = {}): Promise<MediaPage> {
+    const page: unknown = JSON.parse(await callNative("files", "media-list", {
+      kind: options.kind ?? "all", ids: options.ids, cursor: options.cursor ?? undefined, limit: options.limit ?? 60, order: "added", previews: true,
+    }, { signal: options.signal }));
+    if (typeof page !== "object" || page === null || !("items" in page) || !Array.isArray(page.items) || !("nextCursor" in page) || !("version" in page)
+      || (page.nextCursor !== null && typeof page.nextCursor !== "string") || typeof page.version !== "string") throw new NativeError("protocol", "Invalid media page");
+    return { items: page.items.map(decodeItem), nextCursor: page.nextCursor, version: page.version };
+  },
+  /** Counts the whole library and optional groups of IDs without loading their media items. */
+  async counts(options: { groups?: Readonly<Record<string, readonly string[]>>; signal?: AbortSignal } = {}): Promise<MediaCounts> {
+    const counts: unknown = JSON.parse(await callNative("files", "media-counts", { groups: options.groups ?? {} }, { signal: options.signal }));
+    const count = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+    if (typeof counts !== "object" || counts === null || !("all" in counts) || !count(counts.all)
+      || !("image" in counts) || !count(counts.image) || !("video" in counts) || !count(counts.video)
+      || !("groups" in counts) || typeof counts.groups !== "object" || counts.groups === null || Array.isArray(counts.groups)
+      || !Object.values(counts.groups).every(count)) throw new NativeError("protocol", "Invalid media counts");
+    return counts as MediaCounts;
+  },
+  /** Deletes items from the device. Resolves with the deleted IDs, or null when declined. */
+  async remove(ids: readonly string[]): Promise<string[] | null> {
+    const result: unknown = JSON.parse(await callNative("files", "media-delete", { ids }, { timeoutMs: 600_000 }));
+    if (result === null) return null;
+    if (!Array.isArray(result) || !result.every(id => typeof id === "string")) throw new NativeError("protocol", "Invalid deleted media IDs");
+    return result;
+  },
+  /** Rotates a photo clockwise. Resolves with the updated item, or null when declined. */
+  async rotate(id: string, degrees: 90 | 180 | 270): Promise<MediaItem | null> {
+    const result: unknown = JSON.parse(await callNative("files", "media-rotate", { id, degrees }, { timeoutMs: 600_000 }));
+    return result === null ? null : decodeItem(result);
+  },
+  /** Prepares instant grid previews for the supplied library items in the background. */
+  async preparePreviews(options: { ids: readonly string[]; signal?: AbortSignal }): Promise<number> {
+    return Number(await callNative("files", "media-previews", { ids: options.ids }, { signal: options.signal }));
+  },
+  /** Calls `listener` after photos or videos are added, changed or removed, including while the app was hidden. */
+  watch(listener: (version: string) => void, onError: (error: Error) => void): () => void {
+    watchers.set(listener, onError);
+    const request = watchRequest ??= callNative("files", "media-watch", {});
+    void request.catch(error => {
+      if (watchRequest === request) watchRequest = null;
+      if (watchers.get(listener) === onError) onError(error instanceof Error ? error : new Error(String(error)));
+    });
+    return () => {
+      watchers.delete(listener);
+      if (!watchers.size) {
+        watchRequest = null;
+        void callNative("files", "media-unwatch", {}).catch(error => onError(error instanceof Error ? error : new Error(String(error))));
+      }
+    };
+  },
+};
+
+const watchers = new Map<(version: string) => void, (error: Error) => void>();
+let watchRequest: Promise<string> | null = null;
+onNativeMessage("media-changed", message => {
+  if (typeof message.data !== "object" || message.data === null || !("version" in message.data) || typeof message.data.version !== "string") {
+    throw new NativeError("protocol", "Invalid media library change");
+  }
+  for (const listener of [...watchers.keys()]) listener(message.data.version);
+});
+
+/** Full-resolution source for a photo, decoded at the size it is displayed. */
+export function fullSource(item: MediaItem) {
+  return item.src + "&full=1";
+}
+
+/** A `content://` URI for video playback. */
+export function contentUri(item: MediaItem) {
+  const [kind, id] = item.id.split(":");
+  return `content://media/external/${kind === "video" ? "video" : "images"}/media/${id}`;
+}
+
+export type MediaGridProps = {
+  items: readonly MediaItem[];
+  /** A selection dims the other items. Omit it or pass null to browse normally. */
+  selected?: ReadonlySet<string> | null;
+  onPress: (item: MediaItem, index: number) => void;
+  onLongPress?: (item: MediaItem, index: number) => void;
+  hasMore?: boolean;
+  onLoadMore?: () => Promise<void>;
+};
+
+/** Three-column, edge-to-edge grid of library items. Place it in `MediaGridScreen`. */
+export function MediaGrid(props: MediaGridProps) {
+  return createElement(MediaGridView<MediaItem>, {
+    ...props, selectionStyle: "dimmed", hideIncompleteRow: true,
+    onLongPress: (item, index) => props.onLongPress?.(item, index),
+  });
+}
+
+/** A screen without margins for `MediaGrid`, with an optional bottom action bar. */
+export function MediaGridScreen({ title, onTitlePress, titleIcon, rightAction, actionBar, children }: {
+  title?: string;
+  onTitlePress?: () => void;
+  titleIcon?: IconAsset;
+  rightAction?: { icon: IconAsset; onPress: () => void };
+  actionBar?: readonly ActionBarItem[];
+  children?: ReactNode;
+}) {
+  return createElement("MediaPickerScreen", {
+    title, onTitlePress, titleIcon, scrollBar: "auto", rightIcon: rightAction?.icon, onRightPress: rightAction?.onPress, ...actionBarProps(actionBar),
+  }, children);
+}

package/src/media-grid.ts

@@ -0,0 +1,74 @@
+import { createElement, useLayoutEffect, useMemo, useRef } from "ink/internal/react";
+import { List } from "ink";
+import { fixedListRow } from "ink/internal/list";
+import { checkCircleFilled, videoFileFilled } from "ink/icons";
+
+type MediaGridItem = { id: string; src: string; mimeType: string };
+type MediaGridViewProps<T> = {
+  items: readonly T[];
+  selected?: ReadonlySet<string> | null;
+  selectionStyle: "selected" | "dimmed";
+  onPress: (item: T, index: number) => void;
+  onLongPress?: (item: T, index: number) => void;
+  hideIncompleteRow?: boolean;
+  hasMore?: boolean;
+  onLoadMore?: () => Promise<void>;
+};
+
+const mediaRow = /* @__PURE__ */ fixedListRow<ReturnType<typeof gridCell>[]>((node, field) => node("MediaGridRow", {},
+  Array.from({ length: 3 }, (_, index) => node("MediaCell", {
+    key: field(cells => cells[index].key),
+    hidden: field(cells => cells[index].hidden), src: field(cells => cells[index].src),
+    selected: field(cells => cells[index].selected), dimmed: field(cells => cells[index].dimmed),
+    video: field(cells => cells[index].video), checkIcon: checkCircleFilled, videoIcon: videoFileFilled,
+    onPress: field(cells => cells[index].onPress), onLongPress: field(cells => cells[index].onLongPress),
+  }))));
+
+type GridCell<T> = { item: T; index: number; selected: boolean; dimmed: boolean };
+type GridRow<T> = { key: string; cells: GridCell<T>[]; longPress: boolean };
+type GridHandlers<T> = Pick<MediaGridViewProps<T>, "onPress" | "onLongPress">;
+
+function gridCell<T extends MediaGridItem>(handlers: { current: GridHandlers<T> }, row: GridRow<T>, index: number) {
+  const entry = row.cells[index];
+  return {
+    key: entry?.item.id,
+    hidden: !entry, src: (entry ?? row.cells[0]).item.src, selected: !!entry?.selected, dimmed: !!entry?.dimmed,
+    video: !!entry?.item.mimeType.startsWith("video/"),
+    // Handlers are read when pressed, so unchanged rows never hold stale callbacks.
+    onPress: entry && (() => handlers.current.onPress(entry.item, entry.index)),
+    onLongPress: entry && row.longPress ? () => handlers.current.onLongPress?.(entry.item, entry.index) : undefined,
+  };
+}
+
+export function MediaGridView<T extends MediaGridItem>({ items, selected, selectionStyle, onPress, onLongPress, hideIncompleteRow, hasMore, onLoadMore }: MediaGridViewProps<T>) {
+  const handlers = useRef<GridHandlers<T>>({ onPress, onLongPress });
+  useLayoutEffect(() => { handlers.current = { onPress, onLongPress }; });
+  const cache = useRef(new Map<string, GridRow<T>>());
+  const longPress = !!onLongPress;
+  const rows = useMemo(() => {
+    const next = new Map<string, GridRow<T>>();
+    const rows: GridRow<T>[] = [];
+    const count = hideIncompleteRow && hasMore ? items.length - items.length % 3 : items.length;
+    for (let index = 0; index < count; index += 3) {
+      const cells = items.slice(index, index + 3).map((item, offset) => ({
+        item, index: index + offset,
+        selected: selectionStyle === "selected" && !!selected?.has(item.id),
+        dimmed: selectionStyle === "dimmed" && selected != null && !selected.has(item.id),
+      }));
+      const key = cells[0].item.id;
+      const previous = cache.current.get(key);
+      // Rows keep their identity unless an item, its position or its presentation changes.
+      const row = previous && previous.longPress === longPress && previous.cells.length === cells.length && previous.cells.every((cell, offset) =>
+        cell.item === cells[offset].item && cell.index === cells[offset].index && cell.selected === cells[offset].selected && cell.dimmed === cells[offset].dimmed)
+        ? previous : { key, cells, longPress };
+      next.set(key, row);
+      rows.push(row);
+    }
+    cache.current = next;
+    return rows;
+  }, [items, selected, selectionStyle, hideIncompleteRow, hasMore, longPress]);
+  return createElement(List<GridRow<T>>, {
+    items: rows, keyExtractor: row => row.key, gap: 0, hasMore, onLoadMore,
+    renderItem: mediaRow((row: GridRow<T>) => Array.from({ length: 3 }, (_, index) => gridCell(handlers, row, index))),
+  });
+}

package/src/media.ts

@@ -1,24 +1,19 @@
 import { lightos, type PermissionStatus } from "@ink/lightos";
-import { createElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { EmptyState, ErrorState, List, LoadingState, Screen, Text } from "ink";
-import { nativeListRow, nativeListTemplate } from "ink/internal/list";
+import { createElement, useCallback, useEffect, useRef, useState } from "ink/internal/react";
+import { EmptyState, ErrorState, LoadingState, Screen, Text } from "ink";
 import { callNative, NativeError } from "ink/native";
 import { files, type FileRef } from "./index";
 import { decodeFileRef } from "./decode";
-import { check, checkCircleFilled, videoFileFilled } from "ink/icons";
-
-const mediaTemplate = nativeListTemplate((node, field) => node("MediaGridRow", {},
-  Array.from({ length: 3 }, (_, index) => node("MediaCell", {
-    hidden: field(index, "hidden"), src: field(index, "src"), selected: field(index, "selected"),
-    video: field(index, "video"), checkIcon: checkCircleFilled, videoIcon: videoFileFilled,
-    onPress: field(index, "onPress"),
-  }))));
+import { check } from "ink/icons";
+import { MediaGridView } from "./media-grid";
 
 type MediaItem = { id: string; src: string; name: string; mimeType: string; width: number; height: number };
 type MediaPage = { items: MediaItem[]; nextCursor: string | null };
 export type MediaPickerProps = {
   kind?: "image" | "video" | "all";
   title?: string;
+  selectionOrder?: "library" | "selection";
+  multiple?: boolean;
   onSelect: (files: FileRef[]) => void | Promise<void>;
 };
 
@@ -33,9 +28,14 @@ function decodePage(value: string): MediaPage {
   return page as MediaPage;
 }
 
-export function MediaPicker({ kind = "all", title = kind === "image" ? "Photos" : kind === "video" ? "Videos" : "Photos and videos", onSelect }: MediaPickerProps) {
+export function MediaPicker({ kind = "all", title = kind === "image" ? "Photos" : kind === "video" ? "Videos" : "Photos and videos", selectionOrder = "library", multiple = true, onSelect }: MediaPickerProps) {
   const [items, setItems] = useState<MediaItem[]>([]);
   const [selected, setSelected] = useState<Set<string>>(new Set());
+  const toggleSelected = useCallback((id: string) => setSelected(previous => {
+    const next = new Set(multiple ? previous : []);
+    if (previous.has(id)) next.delete(id); else next.add(id);
+    return next;
+  }), [multiple]);
   const [permission, setPermission] = useState<PermissionStatus | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<Error | null>(null);
@@ -102,8 +102,9 @@ export function MediaPicker({ kind = "all", title = kind === "image" ? "Photos"
     const imported: FileRef[] = [];
     let delivered = false;
     try {
-      for (const item of items.filter(item => selected.has(item.id))) {
-        const file = decodeFileRef(await callNative("files", "media-import", { id: item.id }, { signal, timeoutMs: 600_000 }));
+      const orderedIds = selectionOrder === "selection" ? [...selected] : items.filter(item => selected.has(item.id)).map(item => item.id);
+      for (const id of orderedIds) {
+        const file = decodeFileRef(await callNative("files", "media-import", { id }, { signal, timeoutMs: 600_000 }));
         if (!file) throw new NativeError("protocol", "Media import returned no file");
         imported.push(file);
       }
@@ -121,11 +122,6 @@ export function MediaPicker({ kind = "all", title = kind === "image" ? "Photos"
     }
   };
 
-  const rows = useMemo(() => {
-    const rows: MediaItem[][] = [];
-    for (let index = 0; index < items.length; index += 3) rows.push(items.slice(index, index + 3));
-    return rows;
-  }, [items]);
   if (loading) return createElement(Screen, { title }, createElement(LoadingState, { label: "Loading library…" }));
   if (error) return createElement(Screen, { title }, createElement(ErrorState, {
     message: error.message,
@@ -136,18 +132,9 @@ export function MediaPicker({ kind = "all", title = kind === "image" ? "Photos"
   if (importing) return createElement(Screen, { title }, createElement(LoadingState, { label: "Preparing attachments…" }));
   return createElement("MediaPickerScreen", { title, rightIcon: selected.size ? check : undefined, onRightPress: selected.size ? confirm : undefined },
     items.length === 0 ? createElement(EmptyState, { title: kind === "video" ? "No videos" : kind === "image" ? "No photos" : "No photos or videos" }) :
-      createElement(List<MediaItem[]>, {
-        items: rows, keyExtractor: row => row[0].id, gap: 0, hasMore,
+      createElement(MediaGridView<MediaItem>, {
+        items, selected, selectionStyle: "selected", hasMore,
+        onPress: item => toggleSelected(item.id),
         onLoadMore: async () => { if (active.current) await loadPage(active.current.signal); },
-        renderItem: nativeListRow((row: MediaItem[]) => createElement("MediaGridRow", null, row.map(item => createElement("MediaCell", {
-          key: item.id, src: item.src, selected: selected.has(item.id), video: item.mimeType.startsWith("video/"), checkIcon: checkCircleFilled, videoIcon: videoFileFilled,
-          onPress: () => setSelected(previous => { const next = new Set(previous); if (next.has(item.id)) next.delete(item.id); else next.add(item.id); return next; }),
-        }))), row => [Array.from({ length: 3 }, (_, index) => {
-          const item = row[index];
-          return { hidden: !item, src: item?.src ?? row[0].src, selected: !!item && selected.has(item.id),
-            video: !!item?.mimeType.startsWith("video/"), onPress: item && (() => setSelected(previous => {
-              const next = new Set(previous); if (next.has(item.id)) next.delete(item.id); else next.add(item.id); return next;
-            })) };
-        })], mediaTemplate),
       }));
 }