@drawnagency/primitives 0.1.77 → 0.1.78

package/src/lib/media-folders.ts

@@ -0,0 +1,232 @@
+import type { MediaFolder, MediaItem, MediaManifest } from "../media/types";
+
+export interface FolderTreeNode {
+  id: string;
+  name: string;
+  children: FolderTreeNode[];
+}
+
+export interface FolderUploadPlan {
+  /** New folder entities to merge into manifest.folders, keyed by new id. */
+  newFolders: Record<string, MediaFolder>;
+  /** Display-folder target per uploaded file (null = root). */
+  fileTargets: { file: File; folderId: string | null }[];
+}
+
+/** Display-folder id. NOT related to MediaItem.folder (the git storage dir). */
+export function createFolderId(): string {
+  const bytes = new Uint8Array(6);
+  crypto.getRandomValues(bytes);
+  return `f_${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+/** True when this folder's parent chain loops back to itself. */
+export function isCyclicFolder(folders: Record<string, MediaFolder>, id: string): boolean {
+  const max = Object.keys(folders).length;
+  let cursor = folders[id]?.parentId ?? null;
+  for (let steps = 0; cursor !== null && folders[cursor] && steps <= max; steps++) {
+    if (cursor === id) return true;
+    cursor = folders[cursor].parentId;
+  }
+  return false;
+}
+
+/**
+ * Effective parent for rendering: null (root) when the parent is missing,
+ * dangling, or `id` itself sits on a parent cycle. Cycle members re-root,
+ * which breaks the loop for their (kept) descendants — corrupt manifests
+ * always render, and healMediaManifest persists this view on save.
+ */
+export function effectiveParentId(folders: Record<string, MediaFolder>, id: string): string | null {
+  const parentId = folders[id]?.parentId ?? null;
+  if (parentId === null || !folders[parentId]) return null;
+  return isCyclicFolder(folders, id) ? null : parentId;
+}
+
+/** Direct children of `parentId`, alphabetically (case-insensitive). */
+export function childFolderIds(folders: Record<string, MediaFolder>, parentId: string | null): string[] {
+  return Object.keys(folders)
+    .filter((id) => effectiveParentId(folders, id) === parentId)
+    .sort((a, b) => folders[a].name.localeCompare(folders[b].name, undefined, { sensitivity: "base" }));
+}
+
+export function buildFolderTree(folders: Record<string, MediaFolder>): FolderTreeNode[] {
+  const build = (parentId: string | null): FolderTreeNode[] =>
+    childFolderIds(folders, parentId).map((id) => ({
+      id,
+      name: folders[id].name,
+      children: build(id),
+    }));
+  return build(null);
+}
+
+/** Names from root to `id` inclusive, cycle-safe. */
+export function folderPathNames(folders: Record<string, MediaFolder>, id: string): string[] {
+  const names: string[] = [];
+  let cursor: string | null = id;
+  while (cursor !== null && folders[cursor]) {
+    names.unshift(folders[cursor].name);
+    cursor = effectiveParentId(folders, cursor);
+  }
+  return names;
+}
+
+/** Folder ids from root to `id` inclusive, cycle-safe. */
+export function folderPathIds(folders: Record<string, MediaFolder>, id: string): string[] {
+  const ids: string[] = [];
+  let cursor: string | null = id;
+  while (cursor !== null && folders[cursor]) {
+    ids.unshift(cursor);
+    cursor = effectiveParentId(folders, cursor);
+  }
+  return ids;
+}
+
+/** All folders under `id` (by effective parent), INCLUDING `id` itself. */
+export function descendantFolderIds(folders: Record<string, MediaFolder>, id: string): Set<string> {
+  const result = new Set<string>([id]);
+  const ids = Object.keys(folders);
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const fid of ids) {
+      if (result.has(fid)) continue;
+      const parent = effectiveParentId(folders, fid);
+      if (parent !== null && result.has(parent)) {
+        result.add(fid);
+        grew = true;
+      }
+    }
+  }
+  return result;
+}
+
+/** May `id` re-parent to `targetParentId`? Blocks self/descendant targets and no-ops. */
+export function canMoveFolder(
+  folders: Record<string, MediaFolder>,
+  id: string,
+  targetParentId: string | null,
+): boolean {
+  if (!folders[id]) return false;
+  if (targetParentId === null) return effectiveParentId(folders, id) !== null;
+  if (!folders[targetParentId]) return false;
+  if (descendantFolderIds(folders, id).has(targetParentId)) return false;
+  return effectiveParentId(folders, id) !== targetParentId;
+}
+
+/** Trimmed `desired`, auto-suffixed " (2)", " (3)"… on case-insensitive sibling collision. */
+export function uniqueFolderName(
+  folders: Record<string, MediaFolder>,
+  parentId: string | null,
+  desired: string,
+  excludeId?: string,
+): string {
+  const base = desired.trim();
+  const siblings = new Set(
+    childFolderIds(folders, parentId)
+      .filter((id) => id !== excludeId)
+      .map((id) => folders[id].name.toLowerCase()),
+  );
+  if (!siblings.has(base.toLowerCase())) return base;
+  for (let n = 2; ; n++) {
+    const candidate = `${base} (${n})`;
+    if (!siblings.has(candidate.toLowerCase())) return candidate;
+  }
+}
+
+/** The folder an item renders in: its folderId when it points at a real folder, else root. */
+export function itemFolderId(
+  folders: Record<string, MediaFolder>,
+  item: Pick<MediaItem, "folderId">,
+): string | null {
+  return item.folderId && folders[item.folderId] ? item.folderId : null;
+}
+
+/** Recursive item counts per folder id (an item counts toward every ancestor). */
+export function recursiveItemCounts(
+  folders: Record<string, MediaFolder>,
+  items: MediaItem[],
+): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const item of items) {
+    let cursor = itemFolderId(folders, item);
+    const seen = new Set<string>();
+    while (cursor !== null && !seen.has(cursor)) {
+      seen.add(cursor);
+      counts[cursor] = (counts[cursor] ?? 0) + 1;
+      cursor = effectiveParentId(folders, cursor);
+    }
+  }
+  return counts;
+}
+
+/** Pure heal: dangling folderIds dropped, orphan/cyclic folders re-rooted. */
+export function healMediaManifest(manifest: MediaManifest): MediaManifest {
+  const folders: Record<string, MediaFolder> = {};
+  for (const [id, f] of Object.entries(manifest.folders)) {
+    folders[id] = { ...f, parentId: effectiveParentId(manifest.folders, id) };
+  }
+  const images: MediaManifest["images"] = {};
+  for (const [id, entry] of Object.entries(manifest.images)) {
+    if (entry.folderId && !folders[entry.folderId]) {
+      const { folderId: _dropped, ...rest } = entry;
+      images[id] = rest;
+    } else {
+      images[id] = entry;
+    }
+  }
+  return { ...manifest, images, folders };
+}
+
+/**
+ * Save-time manifest assembly: merge uploaded pending items, apply deletions,
+ * preserve every other manifest key (folders!), then heal.
+ */
+export function assembleSavedManifest(
+  manifest: MediaManifest,
+  uploadedItems: MediaItem[],
+  deletedIds: string[],
+): MediaManifest {
+  const images = { ...manifest.images };
+  for (const entry of uploadedItems) images[entry.id] = entry;
+  for (const id of deletedIds) delete images[id];
+  return healMediaManifest({ ...manifest, images });
+}
+
+/**
+ * Map webkitRelativePath-style paths onto folder entities under
+ * `currentFolderId`, merging with existing folders by case-insensitive name.
+ */
+export function planFolderUpload(
+  files: { file: File; relativePath: string }[],
+  folders: Record<string, MediaFolder>,
+  currentFolderId: string | null,
+  newId: () => string = createFolderId,
+): FolderUploadPlan {
+  const newFolders: Record<string, MediaFolder> = {};
+  // (parentId, lowercased name) -> folder id, seeded from existing folders.
+  const byName = new Map<string, string>();
+  for (const [fid, f] of Object.entries(folders)) {
+    byName.set(`${effectiveParentId(folders, fid)}/${f.name.toLowerCase()}`, fid);
+  }
+  const ensureDir = (segments: string[]): string | null => {
+    let parent = currentFolderId;
+    for (const segment of segments) {
+      const key = `${parent}/${segment.toLowerCase()}`;
+      let fid = byName.get(key);
+      if (!fid) {
+        fid = newId();
+        newFolders[fid] = { name: segment, parentId: parent };
+        byName.set(key, fid);
+      }
+      parent = fid;
+    }
+    return parent;
+  };
+  const fileTargets = files.map(({ file, relativePath }) => {
+    const segments = relativePath.split("/").filter(Boolean);
+    segments.pop(); // filename
+    return { file, folderId: ensureDir(segments) };
+  });
+  return { newFolders, fileTargets };
+}

package/src/media/folder-drop.ts

@@ -0,0 +1,62 @@
+export interface DroppedFile {
+  file: File;
+  relativePath: string;
+}
+
+/** Structural subset of FileSystemEntry — lets tests fake the tree. */
+export interface EntryLike {
+  isFile: boolean;
+  isDirectory: boolean;
+  name: string;
+  fullPath: string;
+  file?: (cb: (f: File) => void, err: (e: unknown) => void) => void;
+  createReader?: () => {
+    readEntries: (cb: (entries: EntryLike[]) => void, err: (e: unknown) => void) => void;
+  };
+}
+
+const readAll = (reader: NonNullable<ReturnType<NonNullable<EntryLike["createReader"]>>>): Promise<EntryLike[]> =>
+  new Promise((resolve, reject) => {
+    const all: EntryLike[] = [];
+    const step = () =>
+      reader.readEntries((batch) => {
+        if (batch.length === 0) return resolve(all);
+        all.push(...batch);
+        // Defer rather than call step() synchronously: readers return results
+        // in batches and loop until empty, but a synchronous re-entrant call
+        // here would run before any state a caller sets after this callback
+        // returns (e.g. a "served" flag in a synchronous test fake) — causing
+        // infinite recursion. Real FileSystemDirectoryReader impls are async
+        // anyway, so the microtask tick is free in the browser.
+        queueMicrotask(step);
+      }, reject);
+    step();
+  });
+
+export async function traverseEntries(entries: EntryLike[]): Promise<DroppedFile[]> {
+  const out: DroppedFile[] = [];
+  for (const entry of entries) {
+    if (entry.isFile && entry.file) {
+      const file = await new Promise<File>((resolve, reject) => entry.file!(resolve, reject));
+      out.push({ file, relativePath: entry.fullPath.replace(/^\//, "") });
+    } else if (entry.isDirectory && entry.createReader) {
+      out.push(...(await traverseEntries(await readAll(entry.createReader()))));
+    }
+  }
+  return out;
+}
+
+/**
+ * Dropped-payload traversal. Returns null when nothing in the drop is a
+ * directory — the caller should fall back to the plain flat-file path.
+ */
+export async function collectDroppedFiles(dataTransfer: DataTransfer): Promise<DroppedFile[] | null> {
+  const entries: EntryLike[] = [];
+  for (const item of Array.from(dataTransfer.items)) {
+    const getEntry = (item as DataTransferItem & { webkitGetAsEntry?: () => EntryLike | null }).webkitGetAsEntry;
+    const entry = typeof getEntry === "function" ? getEntry.call(item) : null;
+    if (entry) entries.push(entry);
+  }
+  if (!entries.some((e) => e.isDirectory)) return null;
+  return traverseEntries(entries);
+}

package/src/media/types.ts

@@ -3,10 +3,12 @@ export {
   MediaItemSchema,
   ImageManifestSchema,
   MediaConfigSchema,
+  MediaFolderSchema,
   type Variant,
   type MediaItem,
   type MediaManifest,
   type MediaConfig,
+  type MediaFolder,
 } from "../schemas/media";
 
 import type { MediaItem } from "../schemas/media";

package/src/media/utils.ts

@@ -1,4 +1,5 @@
 import { slugifyPageSlug } from "../lib/pages";
+import type { MediaItem } from "./types";
 
 export async function hashFileBuffer(buffer: ArrayBuffer): Promise<string> {
   if (typeof crypto !== "undefined" && crypto.subtle) {
@@ -65,3 +66,12 @@ export function formatFileSize(bytes: number): string {
   if (bytes >= 1024) return `${Math.round(bytes / 1024)}KB`;
   return `${bytes}B`;
 }
+
+/**
+ * Display name for a media item. v2 batch-rename seam: will read a future
+ * optional `displayName` field with originalName fallback — UI must call this
+ * instead of touching originalName directly.
+ */
+export function displayName(item: Pick<MediaItem, "originalName">): string {
+  return item.originalName;
+}

package/src/schemas/media.ts

@@ -8,6 +8,15 @@ export const VariantSchema = z.object({
 
 export type Variant = z.infer<typeof VariantSchema>;
 
+// Display folders for the media library. Pure metadata: a folder assignment
+// never moves files in git (that's MediaItem.folder, the storage dir).
+export const MediaFolderSchema = z.object({
+  name: z.string().min(1),
+  parentId: z.string().nullable(), // null = root
+});
+
+export type MediaFolder = z.infer<typeof MediaFolderSchema>;
+
 export const MediaItemSchema = z.object({
   id: z.string(),
   hash: z.string(),
@@ -29,12 +38,16 @@ export const MediaItemSchema = z.object({
   url: z.string().optional(),
   // Seconds; videos only. Informational (library UI).
   duration: z.number().positive().optional(),
+  // Display folder (MediaFolderSchema key). Absent = root/unfiled. NOT the
+  // git storage dir — that's `folder` above, which never changes.
+  folderId: z.string().optional(),
 });
 
 export type MediaItem = z.infer<typeof MediaItemSchema>;
 
 export const ImageManifestSchema = z.object({
   images: z.record(z.string(), MediaItemSchema),
+  folders: z.record(z.string(), MediaFolderSchema).default({}),
 });
 
 export type MediaManifest = z.infer<typeof ImageManifestSchema>;