@databricks/appkit-ui 0.18.0 → 0.19.1

package/docs/plugins/files.md

@@ -0,0 +1,350 @@
+# Files plugin
+
+File operations against Databricks Unity Catalog Volumes. Supports listing, reading, downloading, uploading, deleting, and previewing files with built-in caching, retry, and timeout handling via the execution interceptor pipeline.
+
+**Key features:**
+
+* **Multi-volume**: Define named volumes (e.g. `uploads`, `exports`) and access them independently
+* CRUD operations on Unity Catalog Volume files
+* Streaming downloads with content-type resolution
+* Inline raw serving with XSS-safe content type enforcement
+* Upload size limits with streaming enforcement
+* Automatic cache invalidation on write operations
+* Custom content type mappings
+* Per-user execution context (OBO)
+
+## Basic usage[​](#basic-usage "Direct link to Basic usage")
+
+```ts
+import { createApp, files, server } from "@databricks/appkit";
+
+await createApp({
+  plugins: [
+    server(),
+    files(),
+  ],
+});
+
+```
+
+Set `DATABRICKS_VOLUME_*` environment variables in your `app.yaml` (or `.env`). The plugin auto-discovers them at startup:
+
+```bash
+DATABRICKS_VOLUME_UPLOADS=/Volumes/catalog/schema/uploads
+DATABRICKS_VOLUME_EXPORTS=/Volumes/catalog/schema/exports
+
+```
+
+That's it — no `volumes` config needed. The env var suffix becomes the volume key (lowercased):
+
+| Environment variable        | Volume key |
+| --------------------------- | ---------- |
+| `DATABRICKS_VOLUME_UPLOADS` | `uploads`  |
+| `DATABRICKS_VOLUME_EXPORTS` | `exports`  |
+
+## Auto-discovery[​](#auto-discovery "Direct link to Auto-discovery")
+
+The plugin scans `process.env` for keys matching `DATABRICKS_VOLUME_*` and registers each as a volume with default `{}` config. Env vars with an empty value or the bare `DATABRICKS_VOLUME_` prefix (no suffix) are skipped.
+
+**Merge semantics:** auto-discovered volumes are always merged with explicitly configured ones. Explicit config wins for per-volume overrides (e.g., `maxUploadSize`), while discovered-only volumes get default settings.
+
+```ts
+// Explicit overrides for uploads; exports is auto-discovered from env
+files({
+  volumes: {
+    uploads: { maxUploadSize: 100_000_000 },
+  },
+});
+
+```
+
+This produces two volumes (`uploads` with a 100 MB limit, `exports` with defaults), assuming both `DATABRICKS_VOLUME_UPLOADS` and `DATABRICKS_VOLUME_EXPORTS` are set.
+
+## Configuration[​](#configuration "Direct link to Configuration")
+
+```ts
+interface IFilesConfig {
+  /** Named volumes to expose. Each key becomes a volume accessor. */
+  volumes?: Record<string, VolumeConfig>;
+  /** Operation timeout in milliseconds. Overrides the per-tier defaults. */
+  timeout?: number;
+  /** Map of file extensions to MIME types (priority over built-in map). Inherited by all volumes. */
+  customContentTypes?: Record<string, string>;
+  /** Maximum upload size in bytes. Defaults to 5 GB. Inherited by all volumes. */
+  maxUploadSize?: number;
+}
+
+interface VolumeConfig {
+  /** Maximum upload size in bytes for this volume. Overrides plugin-level default. */
+  maxUploadSize?: number;
+  /** Map of file extensions to MIME types for this volume. Overrides plugin-level default. */
+  customContentTypes?: Record<string, string>;
+}
+
+```
+
+### Per-volume overrides[​](#per-volume-overrides "Direct link to Per-volume overrides")
+
+Each volume inherits the plugin-level `maxUploadSize` and `customContentTypes` unless overridden:
+
+```ts
+files({
+  maxUploadSize: 5_000_000_000, // 5 GB default for all volumes
+  customContentTypes: { ".avro": "application/avro" },
+  volumes: {
+    uploads: { maxUploadSize: 100_000_000 }, // 100 MB limit for uploads only
+    exports: {},                              // uses plugin-level defaults
+  },
+});
+
+```
+
+### Custom content types[​](#custom-content-types "Direct link to Custom content types")
+
+Override or extend the built-in extension → MIME map:
+
+```ts
+files({
+  volumes: { data: {} },
+  customContentTypes: {
+    ".avro": "application/avro",
+    ".ndjson": "application/x-ndjson",
+  },
+});
+
+```
+
+Dangerous MIME types (`text/html`, `text/javascript`, `application/javascript`, `application/xhtml+xml`, `image/svg+xml`) are blocked to prevent stored-XSS when files are served inline via `/raw`.
+
+## HTTP routes[​](#http-routes "Direct link to HTTP routes")
+
+Routes are mounted at `/api/files/*`. All routes except `/volumes` execute in user context via `asUser(req)`.
+
+| Method | Path                   | Query / Body                 | Response                                                     |
+| ------ | ---------------------- | ---------------------------- | ------------------------------------------------------------ |
+| GET    | `/volumes`             | —                            | `{ volumes: string[] }`                                      |
+| GET    | `/:volumeKey/list`     | `?path` (optional)           | `DirectoryEntry[]`                                           |
+| GET    | `/:volumeKey/read`     | `?path` (required)           | `text/plain` body                                            |
+| GET    | `/:volumeKey/download` | `?path` (required)           | Binary stream (`Content-Disposition: attachment`)            |
+| GET    | `/:volumeKey/raw`      | `?path` (required)           | Binary stream (inline for safe types, attachment for unsafe) |
+| GET    | `/:volumeKey/exists`   | `?path` (required)           | `{ exists: boolean }`                                        |
+| GET    | `/:volumeKey/metadata` | `?path` (required)           | `FileMetadata`                                               |
+| GET    | `/:volumeKey/preview`  | `?path` (required)           | `FilePreview`                                                |
+| POST   | `/:volumeKey/upload`   | `?path` (required), raw body | `{ success: true }`                                          |
+| POST   | `/:volumeKey/mkdir`    | `body.path` (required)       | `{ success: true }`                                          |
+| DELETE | `/:volumeKey`          | `?path` (required)           | `{ success: true }`                                          |
+
+The `:volumeKey` parameter must match one of the configured volume keys. Unknown volume keys return a `404` with the list of available volumes.
+
+### Path validation[​](#path-validation "Direct link to Path validation")
+
+All endpoints that accept a `path` parameter enforce:
+
+* Path is required (non-empty)
+* Maximum 4096 characters
+* No null bytes
+
+### Raw endpoint security[​](#raw-endpoint-security "Direct link to Raw endpoint security")
+
+The `/:volumeKey/raw` endpoint serves files inline for browser display but applies security headers:
+
+* `X-Content-Type-Options: nosniff`
+* `Content-Security-Policy: sandbox`
+* Unsafe content types (HTML, JS, SVG) are forced to download via `Content-Disposition: attachment`
+
+## Execution defaults[​](#execution-defaults "Direct link to Execution defaults")
+
+Every operation runs through the interceptor pipeline with tier-specific defaults:
+
+| Tier         | Cache | Retry | Timeout | Operations                            |
+| ------------ | ----- | ----- | ------- | ------------------------------------- |
+| **Read**     | 60 s  | 3x    | 30 s    | list, read, exists, metadata, preview |
+| **Download** | none  | 3x    | 30 s    | download, raw                         |
+| **Write**    | none  | none  | 600 s   | upload, mkdir, delete                 |
+
+Retry uses exponential backoff with a 1 s initial delay.
+
+The download timeout applies to the stream start, not the full transfer.
+
+## Cache isolation[​](#cache-isolation "Direct link to Cache isolation")
+
+Cache keys include the volume key, ensuring volumes have independent caches. For example, `uploads:list` and `exports:list` are cached separately.
+
+Write operations (`upload`, `mkdir`, `delete`) automatically invalidate the cached `list` entry for the parent directory of the affected volume.
+
+## Programmatic API[​](#programmatic-api "Direct link to Programmatic API")
+
+The `exports()` API is a callable that accepts a volume key and returns a `VolumeHandle`. The handle exposes all `VolumeAPI` methods directly (service principal, logs a warning) and an `asUser(req)` method for OBO access (recommended).
+
+```ts
+// OBO access (recommended)
+const entries = await appkit.files("uploads").asUser(req).list();
+const content = await appkit.files("exports").asUser(req).read("report.csv");
+
+// Service principal access (logs a warning encouraging OBO)
+const entries = await appkit.files("uploads").list();
+
+// Named accessor
+const vol = appkit.files.volume("uploads");
+await vol.asUser(req).list();
+
+```
+
+### VolumeAPI methods[​](#volumeapi-methods "Direct link to VolumeAPI methods")
+
+| Method            | Signature                                                                                             | Returns            |
+| ----------------- | ----------------------------------------------------------------------------------------------------- | ------------------ |
+| `list`            | `(directoryPath?: string)`                                                                            | `DirectoryEntry[]` |
+| `read`            | `(filePath: string, options?: { maxSize?: number })`                                                  | `string`           |
+| `download`        | `(filePath: string)`                                                                                  | `DownloadResponse` |
+| `exists`          | `(filePath: string)`                                                                                  | `boolean`          |
+| `metadata`        | `(filePath: string)`                                                                                  | `FileMetadata`     |
+| `upload`          | `(filePath: string, contents: ReadableStream \| Buffer \| string, options?: { overwrite?: boolean })` | `void`             |
+| `createDirectory` | `(directoryPath: string)`                                                                             | `void`             |
+| `delete`          | `(filePath: string)`                                                                                  | `void`             |
+| `preview`         | `(filePath: string)`                                                                                  | `FilePreview`      |
+
+> `read()` loads the entire file into memory as a string. Files larger than 10 MB (default) are rejected — use `download()` for large files, or pass `{ maxSize: <bytes> }` to override.
+
+## Path resolution[​](#path-resolution "Direct link to Path resolution")
+
+Paths can be **absolute** or **relative**:
+
+* **Absolute** — starts with `/`, must begin with `/Volumes/` (e.g. `/Volumes/catalog/schema/vol/data.csv`)
+* **Relative** — prepended with the volume path resolved from the environment variable (e.g. `data.csv` → `/Volumes/catalog/schema/uploads/data.csv`)
+
+Path traversal (`../`) is rejected. If a relative path is used and the volume's environment variable is not set, an error is thrown.
+
+The `list()` method with no arguments lists the volume root.
+
+## Types[​](#types "Direct link to Types")
+
+```ts
+// Re-exported from @databricks/sdk-experimental
+type DirectoryEntry = files.DirectoryEntry;
+type DownloadResponse = files.DownloadResponse;
+
+interface FileMetadata {
+  /** File size in bytes. */
+  contentLength: number | undefined;
+  /** MIME content type of the file. */
+  contentType: string | undefined;
+  /** ISO 8601 timestamp of the last modification. */
+  lastModified: string | undefined;
+}
+
+interface FilePreview extends FileMetadata {
+  /** First portion of text content, or null for non-text files. */
+  textPreview: string | null;
+  /** Whether the file is detected as a text format. */
+  isText: boolean;
+  /** Whether the file is detected as an image format. */
+  isImage: boolean;
+}
+
+interface VolumeConfig {
+  /** Maximum upload size in bytes for this volume. */
+  maxUploadSize?: number;
+  /** Map of file extensions to MIME types for this volume. */
+  customContentTypes?: Record<string, string>;
+}
+
+interface VolumeAPI {
+  list(directoryPath?: string): Promise<DirectoryEntry[]>;
+  read(filePath: string, options?: { maxSize?: number }): Promise<string>;
+  download(filePath: string): Promise<DownloadResponse>;
+  exists(filePath: string): Promise<boolean>;
+  metadata(filePath: string): Promise<FileMetadata>;
+  upload(filePath: string, contents: ReadableStream | Buffer | string, options?: { overwrite?: boolean }): Promise<void>;
+  createDirectory(directoryPath: string): Promise<void>;
+  delete(filePath: string): Promise<void>;
+  preview(filePath: string): Promise<FilePreview>;
+}
+
+/** Volume handle: all VolumeAPI methods (service principal) + asUser() for OBO. */
+type VolumeHandle = VolumeAPI & {
+  asUser: (req: Request) => VolumeAPI;
+};
+
+```
+
+## Content-type resolution[​](#content-type-resolution "Direct link to Content-type resolution")
+
+`contentTypeFromPath(filePath, reported?, customTypes?)` resolves a file's MIME type:
+
+1. Check `customContentTypes` map first (if configured).
+2. Match the file extension against the built-in map.
+3. Fall back to the server-reported type, or `application/octet-stream`.
+
+Built-in extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.bmp`, `.ico`, `.html`, `.css`, `.js`, `.ts`, `.py`, `.txt`, `.md`, `.csv`, `.json`, `.jsonl`, `.xml`, `.yaml`, `.yml`, `.sql`, `.pdf`, `.ipynb`, `.parquet`, `.zip`, `.gz`.
+
+## User context[​](#user-context "Direct link to User context")
+
+Routes use `this.asUser(req)` so operations execute with the requesting user's Databricks credentials (on-behalf-of / OBO). The `/volumes` route is the only exception since it only reads plugin config.
+
+The programmatic API returns a `VolumeHandle` that exposes all `VolumeAPI` methods directly (service principal) and an `asUser(req)` method for OBO access. Calling any method without `asUser()` logs a warning encouraging OBO usage but does not throw. OBO access is strongly recommended for production use.
+
+## Resource requirements[​](#resource-requirements "Direct link to Resource requirements")
+
+Volume resources are declared **dynamically** via `getResourceRequirements(config)` based on discovered + configured volumes. Each volume key generates a required resource with `WRITE_VOLUME` permission and a `DATABRICKS_VOLUME_{KEY_UPPERCASE}` environment variable.
+
+For example, if `DATABRICKS_VOLUME_UPLOADS` and `DATABRICKS_VOLUME_EXPORTS` are set, calling `files()` generates two required volume resources validated at startup — no explicit `volumes` config needed.
+
+## Error responses[​](#error-responses "Direct link to Error responses")
+
+All errors return JSON:
+
+```json
+{
+  "error": "Human-readable message",
+  "plugin": "files"
+}
+
+```
+
+| Status | Description                                                   |
+| ------ | ------------------------------------------------------------- |
+| 400    | Missing or invalid `path` parameter                           |
+| 404    | Unknown volume key                                            |
+| 413    | Upload exceeds `maxUploadSize`                                |
+| 500    | Operation failed (SDK, network, upstream, or unhandled error) |
+
+## Frontend components[​](#frontend-components "Direct link to Frontend components")
+
+The `@databricks/appkit-ui` package provides ready-to-use React components for building a file browser:
+
+### FileBrowser[​](#filebrowser "Direct link to FileBrowser")
+
+A composable set of components for browsing, previewing, and managing files in a Unity Catalog Volume:
+
+```tsx
+import {
+  DirectoryList,
+  FileBreadcrumb,
+  FilePreviewPanel,
+} from "@databricks/appkit-ui/react";
+
+function FileBrowserPage() {
+  return (
+    <div style={{ display: "flex", gap: 16 }}>
+      <div style={{ flex: 1 }}>
+        <FileBreadcrumb
+          rootLabel="uploads"
+          segments={["data"]}
+          onNavigateToRoot={() => {}}
+          onNavigateToSegment={() => {}}
+        />
+        <DirectoryList
+          entries={[]}
+          onEntryClick={() => {}}
+          resolveEntryPath={(entry) => entry.path ?? ""}
+        />
+      </div>
+      <FilePreviewPanel selectedFile={null} preview={null} />
+    </div>
+  );
+}
+
+```
+
+See the [Files (UC) components](./docs/api/appkit-ui/files/DirectoryList.md) reference for the full props API.

package/docs/plugins.md

@@ -9,13 +9,14 @@ For complete API documentation, see the [`Plugin`](./docs/api/appkit/Class.Plugi
 Configure plugins when creating your AppKit instance:
 
 ```typescript
-import { createApp, server, analytics, genie } from "@databricks/appkit";
+import { createApp, server, analytics, genie, files } from "@databricks/appkit";
 
 const AppKit = await createApp({
   plugins: [
     server({ port: 8000 }),
     analytics(),
     genie(),
+    files(),
   ],
 });
 

package/llms.txt

@@ -44,6 +44,7 @@ npx @databricks/appkit docs <query>
 - [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
 - [Creating custom plugins](./docs/plugins/custom-plugins.md): If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
 - [Execution context](./docs/plugins/execution-context.md): AppKit manages Databricks authentication via two contexts:
+- [Files plugin](./docs/plugins/files.md): File operations against Databricks Unity Catalog Volumes. Supports listing, reading, downloading, uploading, deleting, and previewing files with built-in caching, retry, and timeout handling via the execution interceptor pipeline.
 - [Genie plugin](./docs/plugins/genie.md): Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.
 - [Lakebase plugin](./docs/plugins/lakebase.md): Currently, the Lakebase plugin currently requires a one-time manual setup to connect your Databricks App with your Lakebase database. An automated setup process is planned for an upcoming future release.
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
@@ -83,7 +84,7 @@ npx @databricks/appkit docs <query>
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
 - [Interface: LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md): Configuration for creating a Lakebase connection pool
-- [Interface: PluginManifest](./docs/api/appkit/Interface.PluginManifest.md): Plugin manifest that declares metadata and resource requirements.
+- [Interface: PluginManifest<TName>](./docs/api/appkit/Interface.PluginManifest.md): Plugin manifest that declares metadata and resource requirements.
 - [Interface: RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md): Optional claims for fine-grained Unity Catalog table permissions
 - [Interface: RequestedResource](./docs/api/appkit/Interface.RequestedResource.md): Resource to request permissions for in Unity Catalog
 - [Interface: ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md): Internal representation of a resource in the registry.
@@ -94,6 +95,7 @@ npx @databricks/appkit docs <query>
 - [Interface: ValidationResult](./docs/api/appkit/Interface.ValidationResult.md): Result of validating all registered resources against the environment.
 - [Type Alias: ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md): Configuration schema definition for plugin config.
 - [Type Alias: IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md): Express router type for plugin route registration
+- [Type Alias: PluginData<T, U, N>](./docs/api/appkit/TypeAlias.PluginData.md): Type Parameters
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
 - [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Type Parameters
 - [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
@@ -110,6 +112,11 @@ npx @databricks/appkit docs <query>
 - [PieChart](./docs/api/appkit-ui/data/PieChart.md): Pie Chart component for proportional data visualization.
 - [RadarChart](./docs/api/appkit-ui/data/RadarChart.md): Radar Chart component for multi-dimensional data comparison.
 - [ScatterChart](./docs/api/appkit-ui/data/ScatterChart.md): Scatter Chart component for correlation and distribution visualization.
+- [DirectoryList](./docs/api/appkit-ui/files/DirectoryList.md): Card-wrapped directory listing with loading, error, and empty states
+- [FileBreadcrumb](./docs/api/appkit-ui/files/FileBreadcrumb.md): Path-aware breadcrumb navigation built on top of Breadcrumb primitives
+- [FileEntry](./docs/api/appkit-ui/files/FileEntry.md): Single file or directory row with icon, name, size, and selection state
+- [FilePreviewPanel](./docs/api/appkit-ui/files/FilePreviewPanel.md): Preview panel displaying file metadata, image/text preview, and download/delete actions
+- [NewFolderInput](./docs/api/appkit-ui/files/NewFolderInput.md): Inline folder-name input with create/cancel actions
 - [GenieChat](./docs/api/appkit-ui/genie/GenieChat.md): Full-featured chat interface for a single Databricks AI/BI Genie space. Handles message streaming, conversation history, and auto-reconnection via SSE.
 - [GenieChatInput](./docs/api/appkit-ui/genie/GenieChatInput.md): Auto-expanding textarea input with a send button for chat messages. Submits on Enter (Shift+Enter for newline).
 - [GenieChatMessage](./docs/api/appkit-ui/genie/GenieChatMessage.md): Renders a single Genie message bubble with optional expandable SQL query attachments.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",