@databricks/appkit-ui 0.17.0 → 0.19.0

package/docs/api/appkit-ui/files/FileEntry.md

@@ -0,0 +1,27 @@
+# FileEntry
+
+Single file or directory row with icon, name, size, and selection state
+
+## FileEntry[​](#fileentry-1 "Direct link to FileEntry")
+
+Single file or directory row with icon, name, size, and selection state
+
+**Source:** [`packages/appkit-ui/src/react/file-browser/file-entry.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/file-browser/file-entry.tsx)
+
+### Props[​](#props "Direct link to Props")
+
+| Prop         | Type                          | Required | Default | Description                                             |
+| ------------ | ----------------------------- | -------- | ------- | ------------------------------------------------------- |
+| `entry`      | `DirectoryEntry`              | ✓        | -       | The directory entry to render                           |
+| `entryPath`  | `string`                      | ✓        | -       | Resolved full path for this entry                       |
+| `isSelected` | `boolean`                     |          | -       | Whether this entry is currently selected                |
+| `formatSize` | `((bytes: number) => string)` |          | -       | Custom file size formatter (defaults to formatFileSize) |
+
+### Usage[​](#usage "Direct link to Usage")
+
+```tsx
+import { FileEntry } from '@databricks/appkit-ui';
+
+<FileEntry /* props */ />
+
+```

package/docs/api/appkit-ui/files/FilePreviewPanel.md

@@ -0,0 +1,32 @@
+# FilePreviewPanel
+
+Preview panel displaying file metadata, image/text preview, and download/delete actions
+
+## FilePreviewPanel[​](#filepreviewpanel-1 "Direct link to FilePreviewPanel")
+
+Preview panel displaying file metadata, image/text preview, and download/delete actions
+
+**Source:** [`packages/appkit-ui/src/react/file-browser/file-preview-panel.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/file-browser/file-preview-panel.tsx)
+
+### Props[​](#props "Direct link to Props")
+
+| Prop              | Type                                                                                                                                                   | Required | Default | Description                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------- |
+| `selectedFile`    | `string \| null`                                                                                                                                       | ✓        | -       | Full path of the selected file (null when nothing is selected)            |
+| `preview`         | `FilePreview \| null`                                                                                                                                  | ✓        | -       | Preview data for the selected file                                        |
+| `previewLoading`  | `boolean`                                                                                                                                              |          | -       | Whether the preview is loading                                            |
+| `onDownload`      | `((filePath: string) => void)`                                                                                                                         |          | -       | Called when the download button is clicked                                |
+| `onDelete`        | `((filePath: string) => void)`                                                                                                                         |          | -       | Called when the delete button is clicked                                  |
+| `deleting`        | `boolean`                                                                                                                                              |          | -       | Whether a delete operation is in progress                                 |
+| `imagePreviewSrc` | `string \| ((filePath: string) => string)`                                                                                                             |          | -       | Image preview source — string URL or function that receives the file path |
+| `formatSize`      | `((bytes: number) => string)`                                                                                                                          |          | -       | Custom file size formatter (defaults to formatFileSize)                   |
+| `labels`          | `Pick<FileBrowserLabels, "type" \| "download" \| "size" \| "selectFilePrompt" \| "previewNotAvailable" \| "previewFailed" \| "modified" \| "unknown">` |          | -       | Customizable labels                                                       |
+
+### Usage[​](#usage "Direct link to Usage")
+
+```tsx
+import { FilePreviewPanel } from '@databricks/appkit-ui';
+
+<FilePreviewPanel /* props */ />
+
+```

package/docs/api/appkit-ui/files/NewFolderInput.md

@@ -0,0 +1,30 @@
+# NewFolderInput
+
+Inline folder-name input with create/cancel actions
+
+## NewFolderInput[​](#newfolderinput-1 "Direct link to NewFolderInput")
+
+Inline folder-name input with create/cancel actions
+
+**Source:** [`packages/appkit-ui/src/react/file-browser/new-folder-input.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/file-browser/new-folder-input.tsx)
+
+### Props[​](#props "Direct link to Props")
+
+| Prop        | Type                                                           | Required | Default | Description                            |
+| ----------- | -------------------------------------------------------------- | -------- | ------- | -------------------------------------- |
+| `value`     | `string`                                                       | ✓        | -       | Current folder name value              |
+| `onChange`  | `(value: string) => void`                                      | ✓        | -       | Called when folder name changes        |
+| `onCreate`  | `() => void`                                                   | ✓        | -       | Called when the user confirms creation |
+| `onCancel`  | `() => void`                                                   | ✓        | -       | Called when the user cancels           |
+| `creating`  | `boolean`                                                      |          | -       | Whether folder creation is in progress |
+| `autoFocus` | `boolean`                                                      |          | `true`  | Auto-focus the input on mount          |
+| `labels`    | `Pick<FileBrowserLabels, "create" \| "folderNamePlaceholder">` |          | -       | Customizable labels                    |
+
+### Usage[​](#usage "Direct link to Usage")
+
+```tsx
+import { NewFolderInput } from '@databricks/appkit-ui';
+
+<NewFolderInput /* props */ />
+
+```

package/docs/api/appkit-ui/genie/GenieQueryVisualization.md

@@ -0,0 +1,29 @@
+# GenieQueryVisualization
+
+Renders a chart + data table for a Genie query result.
+
+## GenieQueryVisualization[​](#geniequeryvisualization-1 "Direct link to GenieQueryVisualization")
+
+Renders a chart + data table for a Genie query result.
+
+* When a chart type can be inferred: shows Tabs with "Chart" (default) and "Table"
+* When no chart fits: shows only the data table
+* When data is empty/malformed: renders nothing
+
+**Source:** [`packages/appkit-ui/src/react/genie/genie-query-visualization.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/genie/genie-query-visualization.tsx)
+
+### Props[​](#props "Direct link to Props")
+
+| Prop        | Type                     | Required | Default | Description                                |
+| ----------- | ------------------------ | -------- | ------- | ------------------------------------------ |
+| `data`      | `GenieStatementResponse` | ✓        | -       | Raw statement\_response from the Genie API |
+| `className` | `string`                 |          | -       | Additional CSS classes                     |
+
+### Usage[​](#usage "Direct link to Usage")
+
+```tsx
+import { GenieQueryVisualization } from '@databricks/appkit-ui';
+
+<GenieQueryVisualization /* props */ />
+
+```

package/docs/api/appkit.md

@@ -51,6 +51,7 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | [ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md)             | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
 | [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md)                 | Express router type for plugin route registration                                                           |
+| [PluginData](./docs/api/appkit/TypeAlias.PluginData.md)                 | -                                                                                                           |
 | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types.                                          |
 | [ToPlugin](./docs/api/appkit/TypeAlias.ToPlugin.md)                     | -                                                                                                           |
 

package/docs/configuration.md

@@ -46,6 +46,21 @@ env:
 
 This makes the warehouse ID available to your app at runtime. The `valueFrom: sql-warehouse` directive tells Databricks Apps to inject the configured warehouse ID.
 
+### Binding Unity Catalog volumes (files plugin)[​](#binding-unity-catalog-volumes-files-plugin "Direct link to Binding Unity Catalog volumes (files plugin)")
+
+The files plugin uses named volumes. Each volume key maps to an environment variable `DATABRICKS_VOLUME_{KEY_UPPERCASE}`:
+
+```yaml
+env:
+  - name: DATABRICKS_VOLUME_UPLOADS
+    valueFrom: volume
+  - name: DATABRICKS_VOLUME_EXPORTS
+    valueFrom: volume
+
+```
+
+See the [Files plugin](./docs/plugins/files.md) documentation for details.
+
 For advanced configuration options (authorization, networking, resource limits), see the [Databricks Apps Configuration](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/configuration) documentation.
 
 ## Environment variables[​](#environment-variables "Direct link to Environment variables")

package/docs/plugins/custom-plugins.md

@@ -14,13 +14,10 @@ For a deeper understanding of the plugin structure, read on.
 Extend the [`Plugin`](./docs/api/appkit/Class.Plugin.md) class and export with `toPlugin()`:
 
 ```typescript
-import { Plugin, toPlugin } from "@databricks/appkit";
+import { Plugin, toPlugin, type PluginManifest } from "@databricks/appkit";
 import type express from "express";
 
 class MyPlugin extends Plugin {
-  name = "myPlugin";
-
-  // Define resource requirements in the static manifest
   static manifest = {
     name: "myPlugin",
     displayName: "My Plugin",
@@ -41,7 +38,7 @@ class MyPlugin extends Plugin {
       ],
       optional: []
     }
-  };
+  } satisfies PluginManifest<"myPlugin">;
 
   async setup() {
     // Initialize your plugin
@@ -56,17 +53,13 @@ class MyPlugin extends Plugin {
   }
 
   exports() {
-    // an object with the methods from this plugin to expose
     return {
       myCustomMethod: this.myCustomMethod
     }
   }
 }
 
-export const myPlugin = toPlugin<typeof MyPlugin, Record<string, never>, "myPlugin">(
-  MyPlugin,
-  "myPlugin",
-);
+export const myPlugin = toPlugin(MyPlugin);
 
 ```
 
@@ -80,8 +73,6 @@ interface MyPluginConfig extends BasePluginConfig {
 }
 
 class MyPlugin extends Plugin<MyPluginConfig> {
-  name = "myPlugin";
-
   static manifest = {
     name: "myPlugin",
     displayName: "My Plugin",
@@ -95,7 +86,7 @@ class MyPlugin extends Plugin<MyPluginConfig> {
         { type: "database", alias: "cache", resourceKey: "cache", description: "Query result caching (if enabled)", permission: "CAN_CONNECT_AND_CREATE", fields: { instance_name: { env: "DATABRICKS_CACHE_INSTANCE" }, database_name: { env: "DATABRICKS_CACHE_DB" } } }
       ]
     }
-  };
+  } satisfies PluginManifest<"myPlugin">;
 
   // Runtime: Convert optional resources to required based on config
   static getResourceRequirements(config: MyPluginConfig) {

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,10 +112,16 @@ 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.
 - [GenieChatMessageList](./docs/api/appkit-ui/genie/GenieChatMessageList.md): Scrollable message list that renders Genie chat messages with auto-scroll, skeleton loaders, and a streaming indicator.
+- [GenieQueryVisualization](./docs/api/appkit-ui/genie/GenieQueryVisualization.md): Renders a chart + data table for a Genie query result.
 - [Styling](./docs/api/appkit-ui/styling.md): This guide covers how to style AppKit UI components using CSS variables and theming.
 - [Accordion](./docs/api/appkit-ui/ui/Accordion.md): Collapsible content sections organized in a vertical stack
 - [Alert](./docs/api/appkit-ui/ui/Alert.md): Displays important information with optional icon and multiple variants

package/package.json

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