ink-framework-files 0.0.0-stage → 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vandam Dinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ink-native.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "modules": {
+    "src/index.ts": [
+      "files"
+    ],
+    "src/images.ts": [
+      "file-images"
+    ],
+    "src/media.ts": [
+      "media-library"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "ink-framework-files",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.10",
+  "exports": {
+    ".": "./src/index.ts",
+    "./images": "./src/images.ts",
+    "./media": "./src/media.ts"
+  },
+  "peerDependencies": {
+    "ink": "npm:ink-framework@0.1.0-alpha.10",
+    "react": "19.2.8"
+  },
+  "dependencies": {
+    "@ink/lightos": "npm:ink-framework-lightos@0.1.0-alpha.10"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/No-Scrolling/ink.git",
+    "directory": "packages/files"
+  },
+  "files": [
+    "src",
+    "*.json",
+    "*.ts"
+  ]
+}

package/src/decode.ts

@@ -0,0 +1,16 @@
+import { NativeError } from "ink/native";
+import type { FileRef } from "./index";
+
+export function decodeFileRef(value: string): FileRef | null {
+  const file: unknown = JSON.parse(value);
+  if (file === null) return null;
+  if (typeof file !== "object" || !["id", "src", "name", "mimeType"].every(key => typeof Reflect.get(file, key) === "string")
+    || typeof Reflect.get(file, "size") !== "number" || !Number.isSafeInteger(Reflect.get(file, "size")) || Reflect.get(file, "size") < 0) {
+    throw new NativeError("protocol", "Invalid managed file");
+  }
+  for (const key of ["width", "height", "duration"]) {
+    const number: unknown = Reflect.get(file, key);
+    if (number !== undefined && (typeof number !== "number" || !Number.isFinite(number) || number < 0)) throw new NativeError("protocol", "Invalid media metadata");
+  }
+  return file as FileRef;
+}

package/src/images.ts

@@ -0,0 +1,10 @@
+import { callNative, NativeError } from "ink/native";
+import { decodeFileRef } from "./decode";
+import type { FileRef } from "./index";
+
+export async function prepareImage(file: FileRef, options: { maxWidth: number; maxHeight: number }): Promise<FileRef> {
+  for (const size of [options.maxWidth, options.maxHeight]) if (!Number.isSafeInteger(size) || size < 1 || size > 4096) throw new RangeError("Image bounds must be whole numbers between 1 and 4096");
+  const result = decodeFileRef(await callNative("files", "prepare-image", { id: file.id, ...options }, { timeoutMs: 120_000 }));
+  if (!result) throw new NativeError("protocol", "Image preparation returned no file");
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import { callNative } from "ink/native";
+import { decodeFileRef } from "./decode";
+
+export interface FileRef {
+  id: string;
+  src: string;
+  name: string;
+  mimeType: string;
+  size: number;
+  width?: number;
+  height?: number;
+  duration?: number;
+}
+
+export const files = {
+  async pick(options: { types?: readonly string[]; signal?: AbortSignal } = {}) {
+    return decodeFileRef(await callNative("files", "pick", { types: options.types }, { timeoutMs: 600_000, signal: options.signal }));
+  },
+  open: async (id: string) => decodeFileRef(await callNative("files", "open", { id })),
+  remove: async (id: string): Promise<void> => { await callNative("files", "remove", { id }); },
+  save: async (file: FileRef): Promise<void> => { await callNative("files", "save", { id: file.id }, { timeoutMs: 600_000 }); },
+  share: async (file: FileRef): Promise<void> => { await callNative("files", "share", { id: file.id }); },
+};

package/src/media.ts

@@ -0,0 +1,153 @@
+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 { 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"),
+  }))));
+
+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;
+  onSelect: (files: FileRef[]) => void | Promise<void>;
+};
+
+function decodePage(value: string): MediaPage {
+  const page: unknown = JSON.parse(value);
+  if (typeof page !== "object" || page === null || !("items" in page) || !Array.isArray(page.items)
+    || !("nextCursor" in page) || (page.nextCursor !== null && typeof page.nextCursor !== "string")) throw new NativeError("protocol", "Invalid media page");
+  for (const item of page.items) {
+    if (typeof item !== "object" || item === null || !["id", "src", "name", "mimeType"].every(key => typeof Reflect.get(item, key) === "string")
+      || !["width", "height"].every(key => typeof Reflect.get(item, key) === "number")) throw new NativeError("protocol", "Invalid media item");
+  }
+  return page as MediaPage;
+}
+
+export function MediaPicker({ kind = "all", title = kind === "image" ? "Photos" : kind === "video" ? "Videos" : "Photos and videos", onSelect }: MediaPickerProps) {
+  const [items, setItems] = useState<MediaItem[]>([]);
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [permission, setPermission] = useState<PermissionStatus | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [importing, setImporting] = useState(false);
+  const [hasMore, setHasMore] = useState(false);
+  const cursor = useRef<string | null>(null);
+  const nextPage = useRef<Promise<MediaPage> | null>(null);
+  const active = useRef<AbortController | null>(null);
+  const loadingPage = useRef<AbortSignal | null>(null);
+  const confirming = useRef<AbortSignal | null>(null);
+
+  const loadPage = useCallback(async (signal: AbortSignal, first = false) => {
+    if (loadingPage.current || signal.aborted) return;
+    loadingPage.current = signal;
+    const prefetched = first ? null : nextPage.current;
+    nextPage.current = null;
+    try {
+      const page = await prefetched
+        ?? decodePage(await callNative("files", "media-list", { kind, cursor: first ? undefined : cursor.current, limit: 60 }, { signal }));
+      if (signal.aborted) return;
+      if (!first && page.nextCursor !== null && page.nextCursor === cursor.current) throw new NativeError("protocol", "Media pagination did not advance");
+      setItems(previous => {
+        const seen = new Set(first ? [] : previous.map(item => item.id));
+        return [...(first ? [] : previous), ...page.items.filter(item => { if (seen.has(item.id)) return false; seen.add(item.id); return true; })];
+      });
+      cursor.current = page.nextCursor;
+      setHasMore(page.nextCursor !== null);
+      if (page.nextCursor !== null) {
+        nextPage.current = callNative("files", "media-list", { kind, cursor: page.nextCursor, limit: 60 }, { signal }).then(decodePage);
+        // The next load awaits this promise and exposes any failure through List's retry action.
+        void nextPage.current.catch(() => {});
+      }
+    } finally { if (loadingPage.current === signal) loadingPage.current = null; }
+  }, [kind]);
+
+  const refresh = useCallback(async () => {
+    active.current?.abort();
+    nextPage.current = null;
+    const controller = new AbortController(); active.current = controller;
+    loadingPage.current = null;
+    setLoading(true); setError(null);
+    try {
+      const name = kind === "image" ? "photos" : kind === "video" ? "videos" : "photos-and-videos";
+      const result = await lightos.getPermission(name, { signal: controller.signal });
+      if (controller.signal.aborted) return;
+      setPermission(result);
+      if (result === "granted") await loadPage(controller.signal, true);
+    } catch (reason) {
+      if (!controller.signal.aborted) setError(reason instanceof Error ? reason : new Error(String(reason)));
+    } finally { if (!controller.signal.aborted) setLoading(false); }
+  }, [kind, loadPage]);
+
+  useEffect(() => {
+    setSelected(new Set()); setItems([]); cursor.current = null;
+    confirming.current = null; setImporting(false);
+    void refresh();
+    return () => { active.current?.abort(); active.current = null; };
+  }, [refresh]);
+
+  const confirm = async () => {
+    if (confirming.current || !selected.size || !active.current) return;
+    const signal = active.current.signal;
+    confirming.current = signal; setImporting(true); setError(null);
+    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 }));
+        if (!file) throw new NativeError("protocol", "Media import returned no file");
+        imported.push(file);
+      }
+      signal.throwIfAborted();
+      delivered = true;
+      await onSelect(imported);
+    } catch (reason) {
+      if (!signal.aborted) setError(reason instanceof Error ? reason : new Error(String(reason)));
+    } finally {
+      if (!delivered) await Promise.all(imported.map(file => files.remove(file.id).catch(() => {})));
+      if (confirming.current === signal) {
+        confirming.current = null;
+        if (!signal.aborted) setImporting(false);
+      }
+    }
+  };
+
+  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,
+    onRetry: () => { if (permission !== "granted" || items.length === 0) void refresh(); else setError(null); },
+  }));
+  if (permission !== "granted") return createElement(Screen, { title },
+    createElement(Text, { size: 18 }, `Access to all ${kind === "image" ? "photos" : kind === "video" ? "videos" : "photos and videos"} is required to browse the library.`));
+  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,
+        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),
+      }));
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.