@databricks/appkit-ui 0.18.0 → 0.19.1

package/docs/api/appkit/Interface.PluginManifest.md

@@ -1,7 +1,13 @@
-# Interface: PluginManifest
+# Interface: PluginManifest\<TName>
 
 Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property.
 
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter             | Default type |
+| -------------------------- | ------------ |
+| `TName` *extends* `string` | `string`     |
+
 ## Properties[​](#properties "Direct link to Properties")
 
 ### author?[​](#author "Direct link to author?")
@@ -89,11 +95,11 @@ optional license: string;
 ### name[​](#name "Direct link to name")
 
 ```ts
-name: string;
+name: TName;
 
 ```
 
-Plugin identifier (matches plugin.name)
+Plugin identifier — the single source of truth for the plugin's name
 
 ***
 

package/docs/api/appkit/TypeAlias.PluginData.md

@@ -0,0 +1,45 @@
+# Type Alias: PluginData\<T, U, N>
+
+```ts
+type PluginData<T, U, N> = {
+  config: U;
+  name: N;
+  plugin: T;
+};
+
+```
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+| `U`            |
+| `N`            |
+
+## Properties[​](#properties "Direct link to Properties")
+
+### config[​](#config "Direct link to config")
+
+```ts
+config: U;
+
+```
+
+***
+
+### name[​](#name "Direct link to name")
+
+```ts
+name: N;
+
+```
+
+***
+
+### plugin[​](#plugin "Direct link to plugin")
+
+```ts
+plugin: T;
+
+```

package/docs/api/appkit/TypeAlias.ToPlugin.md

@@ -21,4 +21,4 @@ type ToPlugin<T, U, N> = (config?: U) => PluginData<T, U, N>;
 
 ## Returns[​](#returns "Direct link to Returns")
 
-`PluginData`<`T`, `U`, `N`>
+[`PluginData`](./docs/api/appkit/TypeAlias.PluginData.md)<`T`, `U`, `N`>

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

@@ -0,0 +1,36 @@
+# DirectoryList
+
+Card-wrapped directory listing with loading, error, and empty states
+
+## DirectoryList[​](#directorylist-1 "Direct link to DirectoryList")
+
+Card-wrapped directory listing with loading, error, and empty states
+
+**Source:** [`packages/appkit-ui/src/react/file-browser/directory-list.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/file-browser/directory-list.tsx)
+
+### Props[​](#props "Direct link to Props")
+
+| Prop                 | Type                                                                                             | Required | Default | Description                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------- |
+| `entries`            | `DirectoryEntry[]`                                                                               | ✓        | -       | Directory entries to display                                                       |
+| `loading`            | `boolean`                                                                                        |          | -       | Whether the directory is currently loading                                         |
+| `error`              | `string \| null`                                                                                 |          | -       | Error message to display                                                           |
+| `onEntryClick`       | `(entry: DirectoryEntry) => void`                                                                | ✓        | -       | Called when an entry is clicked                                                    |
+| `onNavigateToParent` | `(() => void)`                                                                                   |          | -       | Called when the back/parent button is clicked                                      |
+| `onRetry`            | `(() => void)`                                                                                   |          | -       | Called when the retry button is clicked                                            |
+| `isAtRoot`           | `boolean`                                                                                        |          | -       | Whether the user is at the root directory (hides back button)                      |
+| `selectedPath`       | `string \| null`                                                                                 |          | -       | Currently selected file path for highlighting                                      |
+| `resolveEntryPath`   | `(entry: DirectoryEntry) => string`                                                              | ✓        | -       | Resolves a DirectoryEntry to its full path                                         |
+| `headerContent`      | `ReactNode`                                                                                      |          | -       | Content rendered between the back button and the entry list (e.g., NewFolderInput) |
+| `hasCurrentPath`     | `boolean`                                                                                        |          | -       | Whether a current path is set (affects empty state message)                        |
+| `formatSize`         | `((bytes: number) => string)`                                                                    |          | -       | Custom file size formatter                                                         |
+| `labels`             | `Pick<FileBrowserLabels, "backToParent" \| "emptyDirectory" \| "noVolumeConfigured" \| "retry">` |          | -       | Customizable labels                                                                |
+
+### Usage[​](#usage "Direct link to Usage")
+
+```tsx
+import { DirectoryList } from '@databricks/appkit-ui';
+
+<DirectoryList /* props */ />
+
+```

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

@@ -0,0 +1,27 @@
+# FileBreadcrumb
+
+Path-aware breadcrumb navigation built on top of Breadcrumb primitives
+
+## FileBreadcrumb[​](#filebreadcrumb-1 "Direct link to FileBreadcrumb")
+
+Path-aware breadcrumb navigation built on top of Breadcrumb primitives
+
+**Source:** [`packages/appkit-ui/src/react/file-browser/file-breadcrumb.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/file-browser/file-breadcrumb.tsx)
+
+### Props[​](#props "Direct link to Props")
+
+| Prop                  | Type                      | Required | Default | Description                                                          |
+| --------------------- | ------------------------- | -------- | ------- | -------------------------------------------------------------------- |
+| `rootLabel`           | `string`                  | ✓        | -       | Label for the root breadcrumb item                                   |
+| `segments`            | `string[]`                | ✓        | -       | Path segments after the root                                         |
+| `onNavigateToRoot`    | `() => void`              | ✓        | -       | Called when the root breadcrumb is clicked                           |
+| `onNavigateToSegment` | `(index: number) => void` | ✓        | -       | Called when a segment breadcrumb is clicked (receives segment index) |
+
+### Usage[​](#usage "Direct link to Usage")
+
+```tsx
+import { FileBreadcrumb } from '@databricks/appkit-ui';
+
+<FileBreadcrumb /* props */ />
+
+```

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.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) {