@elabs-ai/components-ui 4.0.0

package/src/lib/download.ts

@@ -0,0 +1,93 @@
+/**
+ * Browser file-download helpers — the single home for the
+ * `Blob`/URL → hidden `<a download>` → click → revoke dance that was previously
+ * copy-pasted across `@elabs-ai/components-ai` (ConversationDownload), `@elabs-ai/components-data`
+ * (downloadCsv) and now `@elabs-ai/components-ai` Gallery.
+ *
+ * Pure DOM mechanics, no React, no other deps — and SSR-guarded
+ * (`typeof document === "undefined"` → no-op) so it's safe to import from
+ * dependency-light modules. The CONTENT (CSV serialization, markdown export,
+ * image source) stays with each caller; this only triggers the save.
+ */
+
+/** Internal: click a hidden anchor for `url`, optionally suggesting `filename`. */
+function clickAnchor(url: string, filename?: string): void {
+  const a = document.createElement("a");
+  a.href = url;
+  // `download` is only honored for same-origin / blob: / data: URLs; harmless otherwise.
+  if (filename) a.download = filename;
+  a.rel = "noopener";
+  a.style.display = "none";
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+}
+
+/** Best-effort filename from a URL path; falls back to "download". */
+function filenameFromUrl(url: string): string {
+  try {
+    const base = "http://localhost";
+    const ref = typeof window === "undefined" ? base : window.location.href;
+    const { pathname } = new URL(url, ref);
+    const last = pathname.split("/").filter(Boolean).pop();
+    return last && last.length > 0 ? decodeURIComponent(last) : "download";
+  } catch {
+    return "download";
+  }
+}
+
+/** True for sources `<a download>` can save directly (same-origin, blob:, data:). */
+function isDirectlyDownloadable(url: string): boolean {
+  if (url.startsWith("data:") || url.startsWith("blob:")) return true;
+  if (typeof window === "undefined") return true;
+  try {
+    return new URL(url, window.location.href).origin === window.location.origin;
+  } catch {
+    // Relative or unparseable → treat as same-origin (the anchor resolves it).
+    return true;
+  }
+}
+
+/**
+ * Trigger a download for an in-memory `Blob`. No-op in non-DOM environments.
+ * Revokes the object URL immediately after the click (the browser captures the
+ * download synchronously, mirroring the prior call sites).
+ */
+export function downloadBlob(blob: Blob, filename: string): void {
+  if (typeof document === "undefined") return;
+  const url = URL.createObjectURL(blob);
+  try {
+    clickAnchor(url, filename);
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/**
+ * Trigger a download for an existing `url` (an http(s)/relative URL, or a
+ * `data:`/`blob:` URI). No-op in non-DOM environments.
+ *
+ * Same-origin / `blob:` / `data:` → a direct `<a download>` (honors `filename`).
+ * Cross-origin → the browser ignores the `download` filename, so we `fetch` the
+ * bytes and save via {@link downloadBlob}. This requires the server to allow CORS;
+ * on failure (CORS/opaque/offline) we fall back to opening the source in a new
+ * tab so the user still gets the asset. Fire-and-forget: `void downloadUrl(...)`.
+ */
+export async function downloadUrl(url: string, filename?: string): Promise<void> {
+  if (typeof document === "undefined") return;
+
+  if (isDirectlyDownloadable(url)) {
+    clickAnchor(url, filename);
+    return;
+  }
+
+  try {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+    const blob = await res.blob();
+    downloadBlob(blob, filename ?? filenameFromUrl(url));
+  } catch {
+    // CORS / opaque / offline: best effort so the user still reaches the asset.
+    window.open(url, "_blank", "noopener,noreferrer");
+  }
+}

package/src/lib/file-icon.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { FILE_CATEGORY_ICONS, fileIconFor } from "./file-icon";
+import type { FileCategory } from "./file-kind";
+
+const CATEGORIES: FileCategory[] = [
+  "image",
+  "video",
+  "audio",
+  "document",
+  "spreadsheet",
+  "presentation",
+  "code",
+  "text",
+  "data",
+  "archive",
+  "unknown",
+];
+
+describe("FILE_CATEGORY_ICONS", () => {
+  it("covers every category", () => {
+    for (const category of CATEGORIES) {
+      expect(FILE_CATEGORY_ICONS[category], category).toBeDefined();
+    }
+    expect(Object.keys(FILE_CATEGORY_ICONS).sort()).toEqual([...CATEGORIES].sort());
+  });
+
+  it("gives each category a distinct glyph, so the icon is a real second channel", () => {
+    const glyphs = new Set(Object.values(FILE_CATEGORY_ICONS));
+    expect(glyphs.size).toBe(CATEGORIES.length);
+  });
+});
+
+describe("fileIconFor", () => {
+  it("resolves through the file kind", () => {
+    expect(fileIconFor("a.png")).toBe(FILE_CATEGORY_ICONS.image);
+    expect(fileIconFor("a.xlsx")).toBe(FILE_CATEGORY_ICONS.spreadsheet);
+    expect(fileIconFor("download", "video/mp4")).toBe(FILE_CATEGORY_ICONS.video);
+  });
+
+  it("falls back to the generic glyph rather than throwing", () => {
+    expect(fileIconFor("mystery.wat")).toBe(FILE_CATEGORY_ICONS.unknown);
+    expect(fileIconFor("")).toBe(FILE_CATEGORY_ICONS.unknown);
+  });
+});

package/src/lib/file-icon.ts

@@ -0,0 +1,58 @@
+/**
+ * One glyph per {@link FileCategory} — the single icon map for file-shaped UI.
+ *
+ * Supersedes two package-private maps that could not see each other:
+ * `PRODUCED_ASSET_ICONS` (`@elabs-ai/components-ai` file-tree, keyed by
+ * the five-member `ContextAssetType`) and `mediaCategoryIcons` (same package,
+ * attachments, keyed by six MIME buckets) — so the same `.csv` drew a table glyph
+ * in one surface and a generic document glyph in the other.
+ *
+ * Lucide per `.claude/rules/icons.md`: these are generic UI glyphs, not product
+ * vocabulary, so nothing here belongs in
+ * `@elabs-ai/components-icons`.
+ *
+ * Values only — this module holds component REFERENCES, it renders nothing.
+ * Icons inherit color from `currentColor`; the category is never carried by hue
+ * alone, so a caller must still supply a text label or an `aria-label` on the
+ * control (WCAG 1.4.1).
+ */
+
+import {
+  File,
+  FileArchive,
+  FileCode,
+  FileDigit,
+  FileImage,
+  FileMusic,
+  FileSpreadsheet,
+  FileText,
+  FileType,
+  FileVideoCamera,
+  type LucideIcon,
+  Presentation,
+} from "lucide-react";
+
+import { type FileCategory, resolveFileKind } from "./file-kind";
+
+/** The glyph for each coarse file shape. Exhaustive over {@link FileCategory}. */
+export const FILE_CATEGORY_ICONS: Readonly<Record<FileCategory, LucideIcon>> = {
+  image: FileImage,
+  video: FileVideoCamera,
+  audio: FileMusic,
+  document: FileText,
+  spreadsheet: FileSpreadsheet,
+  presentation: Presentation,
+  code: FileCode,
+  text: FileType,
+  data: FileDigit,
+  archive: FileArchive,
+  unknown: File,
+};
+
+/**
+ * The glyph for a file, resolved from its name and (optionally) MIME.
+ * Falls back to the generic file glyph rather than throwing.
+ */
+export function fileIconFor(name: string, mediaType?: string): LucideIcon {
+  return FILE_CATEGORY_ICONS[resolveFileKind(name, mediaType).category];
+}

package/src/lib/file-kind.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+
+import { extensionOf, mediaTypeFromName, resolveFileKind } from "./file-kind";
+
+describe("extensionOf", () => {
+  it("lowercases and drops the dot", () => {
+    expect(extensionOf("Report.PDF")).toBe("pdf");
+  });
+
+  it("uses the last dot", () => {
+    expect(extensionOf("archive.tar.gz")).toBe("gz");
+  });
+
+  it("strips a path", () => {
+    expect(extensionOf("/some/dir/notes.md")).toBe("md");
+    expect(extensionOf("C:\\docs\\notes.md")).toBe("md");
+  });
+
+  it("strips a query and hash, so a URL-derived name still resolves", () => {
+    expect(extensionOf("chart.svg?v=2")).toBe("svg");
+    expect(extensionOf("chart.svg#top")).toBe("svg");
+  });
+
+  it("is empty for a dotfile, a trailing dot and no extension", () => {
+    expect(extensionOf(".gitignore")).toBe("");
+    expect(extensionOf("noext.")).toBe("");
+    expect(extensionOf("README")).toBe("");
+    expect(extensionOf("")).toBe("");
+  });
+});
+
+describe("mediaTypeFromName", () => {
+  it("infers from the extension", () => {
+    expect(mediaTypeFromName("a.pdf")).toBe("application/pdf");
+    expect(mediaTypeFromName("a.tsx")).toBe("text/x-typescript");
+  });
+
+  it("is undefined for an unknown extension, so callers own the fallback", () => {
+    expect(mediaTypeFromName("a.wat")).toBeUndefined();
+  });
+});
+
+describe("resolveFileKind", () => {
+  it("resolves the common categories", () => {
+    expect(resolveFileKind("photo.png").category).toBe("image");
+    expect(resolveFileKind("clip.mp4", "video/mp4").category).toBe("video");
+    expect(resolveFileKind("song.mp3", "audio/mpeg").category).toBe("audio");
+    expect(resolveFileKind("report.pdf").category).toBe("document");
+    expect(resolveFileKind("book.xlsx").category).toBe("spreadsheet");
+    expect(resolveFileKind("deck.pptx").category).toBe("presentation");
+    expect(resolveFileKind("main.rs").category).toBe("code");
+    expect(resolveFileKind("notes.md").category).toBe("text");
+    expect(resolveFileKind("rows.csv").category).toBe("data");
+    expect(resolveFileKind("bundle.zip").category).toBe("archive");
+  });
+
+  it("returns the extension and resolved MIME alongside the category", () => {
+    expect(resolveFileKind("Report.PDF")).toEqual({
+      category: "document",
+      mediaType: "application/pdf",
+      extension: "pdf",
+    });
+  });
+
+  it("prefers a meaningful declared MIME over the extension", () => {
+    // The name says nothing; the server does.
+    expect(resolveFileKind("download", "image/webp")).toMatchObject({
+      category: "image",
+      mediaType: "image/webp",
+    });
+  });
+
+  it("ignores the placeholder MIMEs a source uses to mean 'unknown'", () => {
+    expect(resolveFileKind("a.pdf", "application/octet-stream").mediaType).toBe("application/pdf");
+    expect(resolveFileKind("a.pdf", "binary/octet-stream").mediaType).toBe("application/pdf");
+    expect(resolveFileKind("a.pdf", "").mediaType).toBe("application/pdf");
+  });
+
+  it("strips MIME parameters and casing", () => {
+    expect(resolveFileKind("rows.csv", "TEXT/CSV; charset=utf-8").mediaType).toBe("text/csv");
+  });
+
+  it("lets the extension win where it is strictly more specific than a text/* MIME", () => {
+    // Servers routinely send text/plain for these; "text" would be the wrong surface.
+    expect(resolveFileKind("rows.csv", "text/plain").category).toBe("data");
+    expect(resolveFileKind("app.ts", "text/plain").category).toBe("code");
+    expect(resolveFileKind("page.html", "text/html").category).toBe("code");
+  });
+
+  it("falls back to unknown without throwing", () => {
+    expect(resolveFileKind("mystery.wat")).toEqual({
+      category: "unknown",
+      mediaType: "application/octet-stream",
+      extension: "wat",
+    });
+    expect(resolveFileKind("")).toMatchObject({ category: "unknown", extension: "" });
+  });
+});

package/src/lib/file-kind.ts

@@ -0,0 +1,303 @@
+/**
+ * The one file-type resolver for the whole library — extension + MIME → a
+ * COARSE, CLOSED category.
+ *
+ * Before this existed the repo had three competing, package-private ideas of
+ * "what kind of file is this": `ContextAssetType`
+ * (`markdown|code|sql|csv|image`, `@elabs-ai/components-ai`),
+ * `AttachmentMediaCategory` (six MIME buckets, same package) and
+ * `UploadFile` (no kind at all, `@elabs-ai/components-ui`). None could
+ * see the others, so each grew its own icon map and its own gaps.
+ *
+ * ## Why the category is closed and coarse (ADR 0024 §4)
+ *
+ * {@link FileCategory} answers "what SHAPE of thing is this" — enough to pick an
+ * icon, a label, or a fallback surface. It is deliberately NOT the routing key
+ * for a renderer. Fine-grained format matching (`.docx` vs `.odt`,
+ * `.tsx` vs `.rs`) belongs to the adapter manifests in the package that owns the
+ * parsers, so adding a format never means editing this file — and never means a
+ * `@elabs-ai/components-ui` release.
+ *
+ * Pure data + string handling: no React, no DOM, no other deps.
+ */
+
+/**
+ * Coarse file shape. CLOSED — adding a member is a breaking change for any
+ * consumer with an exhaustive `switch`, so extend the adapter manifests instead.
+ */
+export type FileCategory =
+  | "image"
+  | "video"
+  | "audio"
+  | "document"
+  | "spreadsheet"
+  | "presentation"
+  | "code"
+  | "text"
+  | "data"
+  | "archive"
+  | "unknown";
+
+/** What {@link resolveFileKind} knows about a file before anything reads it. */
+export interface FileKind {
+  /** Coarse shape, for icons, labels and fallback surfaces. */
+  category: FileCategory;
+  /**
+   * Best-known MIME type. The caller's value wins when it is meaningful;
+   * otherwise inferred from the extension, else `"application/octet-stream"`.
+   */
+  mediaType: string;
+  /** Lowercased extension WITHOUT the dot (`"pdf"`), or `""` when there is none. */
+  extension: string;
+}
+
+/**
+ * Extension → MIME. Only entries whose MIME we would otherwise have to guess;
+ * the browser fills `File.type` correctly for common web formats, but leaves it
+ * empty for most source-code and data files.
+ */
+const EXTENSION_MEDIA_TYPES: Readonly<Record<string, string>> = {
+  // Media. The browser fills `File.type` for these, but a NAME on its own (a
+  // URL, an agent-produced filename, a drag-and-drop path) carries no MIME —
+  // and resolving `photo.png` to "unknown" is the whole failure this map exists
+  // to prevent.
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  bmp: "image/bmp",
+  ico: "image/x-icon",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  heic: "image/heic",
+  mp4: "video/mp4",
+  m4v: "video/mp4",
+  webm: "video/webm",
+  mov: "video/quicktime",
+  avi: "video/x-msvideo",
+  mkv: "video/x-matroska",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  oga: "audio/ogg",
+  m4a: "audio/mp4",
+  flac: "audio/flac",
+  aac: "audio/aac",
+  // Documents
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  odt: "application/vnd.oasis.opendocument.text",
+  rtf: "application/rtf",
+  epub: "application/epub+zip",
+  // Spreadsheets
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ods: "application/vnd.oasis.opendocument.spreadsheet",
+  // Presentations
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  odp: "application/vnd.oasis.opendocument.presentation",
+  // Data
+  csv: "text/csv",
+  tsv: "text/tab-separated-values",
+  json: "application/json",
+  ndjson: "application/x-ndjson",
+  jsonl: "application/x-ndjson",
+  parquet: "application/vnd.apache.parquet",
+  // Text
+  txt: "text/plain",
+  log: "text/plain",
+  md: "text/markdown",
+  markdown: "text/markdown",
+  rst: "text/x-rst",
+  // Code & markup
+  html: "text/html",
+  htm: "text/html",
+  xml: "application/xml",
+  svg: "image/svg+xml",
+  css: "text/css",
+  js: "text/javascript",
+  mjs: "text/javascript",
+  cjs: "text/javascript",
+  jsx: "text/javascript",
+  ts: "text/x-typescript",
+  tsx: "text/x-typescript",
+  py: "text/x-python",
+  rb: "text/x-ruby",
+  go: "text/x-go",
+  rs: "text/x-rust",
+  java: "text/x-java",
+  kt: "text/x-kotlin",
+  swift: "text/x-swift",
+  c: "text/x-c",
+  h: "text/x-c",
+  cpp: "text/x-c++src",
+  cs: "text/x-csharp",
+  php: "text/x-php",
+  sh: "application/x-sh",
+  bash: "application/x-sh",
+  zsh: "application/x-sh",
+  sql: "application/sql",
+  yaml: "application/yaml",
+  yml: "application/yaml",
+  toml: "application/toml",
+  ini: "text/plain",
+  // Archives
+  zip: "application/zip",
+  tar: "application/x-tar",
+  gz: "application/gzip",
+  tgz: "application/gzip",
+  bz2: "application/x-bzip2",
+  "7z": "application/x-7z-compressed",
+  rar: "application/vnd.rar",
+};
+
+/** Extensions whose category cannot be read off the MIME type. */
+const EXTENSION_CATEGORIES: Readonly<Record<string, FileCategory>> = {
+  // Code & markup — most carry a `text/*` MIME, which alone would say "text".
+  html: "code",
+  htm: "code",
+  xml: "code",
+  css: "code",
+  js: "code",
+  mjs: "code",
+  cjs: "code",
+  jsx: "code",
+  ts: "code",
+  tsx: "code",
+  py: "code",
+  rb: "code",
+  go: "code",
+  rs: "code",
+  java: "code",
+  kt: "code",
+  swift: "code",
+  c: "code",
+  h: "code",
+  cpp: "code",
+  cs: "code",
+  php: "code",
+  sh: "code",
+  bash: "code",
+  zsh: "code",
+  sql: "code",
+  yaml: "code",
+  yml: "code",
+  toml: "code",
+  ini: "code",
+  // Data — `text/csv` would otherwise land in "text".
+  csv: "data",
+  tsv: "data",
+  json: "data",
+  ndjson: "data",
+  jsonl: "data",
+  parquet: "data",
+  // Prose
+  txt: "text",
+  log: "text",
+  md: "text",
+  markdown: "text",
+  rst: "text",
+};
+
+/** MIME (exact match) → category, for types no prefix rule covers. */
+const MEDIA_TYPE_CATEGORIES: Readonly<Record<string, FileCategory>> = {
+  "application/pdf": "document",
+  "application/msword": "document",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "document",
+  "application/vnd.oasis.opendocument.text": "document",
+  "application/rtf": "document",
+  "application/epub+zip": "document",
+  "application/vnd.ms-excel": "spreadsheet",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "spreadsheet",
+  "application/vnd.oasis.opendocument.spreadsheet": "spreadsheet",
+  "application/vnd.ms-powerpoint": "presentation",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation": "presentation",
+  "application/vnd.oasis.opendocument.presentation": "presentation",
+  "application/json": "data",
+  "application/x-ndjson": "data",
+  "application/vnd.apache.parquet": "data",
+  "application/xml": "code",
+  "application/sql": "code",
+  "application/yaml": "code",
+  "application/toml": "code",
+  "application/x-sh": "code",
+  "application/zip": "archive",
+  "application/x-tar": "archive",
+  "application/gzip": "archive",
+  "application/x-bzip2": "archive",
+  "application/x-7z-compressed": "archive",
+  "application/vnd.rar": "archive",
+};
+
+/** The MIME we treat as "the caller told us nothing". */
+const UNKNOWN_MEDIA_TYPE = "application/octet-stream";
+
+/**
+ * Lowercased extension without the dot. `""` when the name has none, is a
+ * dotfile (`.gitignore` — the whole name is the "extension" to a human, but it
+ * is not a format), or ends in a dot.
+ */
+export function extensionOf(name: string): string {
+  // Strip any path and any query/hash a URL-derived name may carry.
+  const base = (name.split(/[\\/]/).pop() ?? "").split(/[?#]/)[0] ?? "";
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0 || dot === base.length - 1) return "";
+  return base.slice(dot + 1).toLowerCase();
+}
+
+/**
+ * Best-known MIME for a filename, from its extension alone.
+ * `undefined` when the extension is unknown — callers decide the fallback.
+ */
+export function mediaTypeFromName(name: string): string | undefined {
+  return EXTENSION_MEDIA_TYPES[extensionOf(name)];
+}
+
+/** Strip parameters and casing: `"TEXT/CSV; charset=utf-8"` → `"text/csv"`. */
+function normalizeMediaType(mediaType: string | undefined): string {
+  const bare = (mediaType ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+  // Browsers and servers both use these to mean "I don't know".
+  if (bare === "" || bare === UNKNOWN_MEDIA_TYPE || bare === "binary/octet-stream") return "";
+  return bare;
+}
+
+function categoryFor(mediaType: string, extension: string): FileCategory {
+  // The extension is more specific than a `text/*` MIME, so it wins for the
+  // formats that would otherwise collapse into "text" (see EXTENSION_CATEGORIES).
+  const byExtension = EXTENSION_CATEGORIES[extension];
+  if (byExtension) return byExtension;
+
+  const exact = MEDIA_TYPE_CATEGORIES[mediaType];
+  if (exact) return exact;
+
+  if (mediaType.startsWith("image/")) return "image";
+  if (mediaType.startsWith("video/")) return "video";
+  if (mediaType.startsWith("audio/")) return "audio";
+  if (mediaType.startsWith("text/")) return "text";
+
+  return "unknown";
+}
+
+/**
+ * Resolve what a file is from its name and (optionally) the MIME the source
+ * reported. Never throws; unknown input resolves to
+ * `{ category: "unknown", mediaType: "application/octet-stream", extension: "" }`.
+ *
+ * A caller-supplied `mediaType` wins over the extension EXCEPT where the
+ * extension is strictly more specific — `report.csv` served as `text/plain`
+ * still resolves to `"data"`, because servers routinely under-specify.
+ */
+export function resolveFileKind(name: string, mediaType?: string): FileKind {
+  const extension = extensionOf(name);
+  const declared = normalizeMediaType(mediaType);
+  const resolved = declared || mediaTypeFromName(name) || UNKNOWN_MEDIA_TYPE;
+  return {
+    category: categoryFor(resolved, extension),
+    mediaType: resolved,
+    extension,
+  };
+}