#index

@statelyjs/files - File System Plugin

File system integration plugin for Stately applications. Provides comprehensive file management capabilities for both schema and UI.

#Features

• File Browsing: Directory navigation with breadcrumbs
• File Uploads: Drag-and-drop with automatic versioning
• File Downloads: Support for multiple storage targets (data, cache, upload)
• RelativePath Field: Form components for file path selection
• Version History: Track and manage file versions

#Installation

pnpm add @statelyjs/files

#Setup

#1. Add Schema Plugin

// stately.ts
import { stately } from '@statelyjs/stately/schema';
import { filesPlugin } from '@statelyjs/files';

const schema = stately<MySchemas>(openapiDoc, PARSED_SCHEMAS)
  .withPlugin(filesPlugin());

#2. Add UI Plugin

// stately.ts
import { statelyUi } from '@statelyjs/stately';
import { filesUiPlugin } from '@statelyjs/files';

const runtime = statelyUi<MySchemas>({ schema, client, options })
  .withPlugin(filesUiPlugin({ api: { pathPrefix: '/files' } }));

#3. Access in Components

import { useFilesStatelyUi } from '@statelyjs/files';

function FileManager() {
  const { plugins } = useFilesStatelyUi();
  const files = plugins.files;

  // Use file operations
  const upload = () => files.api.upload({ body: formData });
  const list = () => files.api.list_files({ params: { query: { dir: '/' } } });
}

#Type Aliases

#FilesOptions

FilesOptions = DefineOptions<{ api?: { pathPrefix?: string; }; navigation?: { routes?: UiNavigationOptions["routes"]; }; }>

Defined in: files/src/plugin.tsx:93

Configuration options for the Files plugin.

#Example

const options: FilesOptions = {
  api: { pathPrefix: '/api/v1/files' },
  navigation: { routes: { label: 'Documents', icon: FileIcon } },
};

#FilesPlugin

FilesPlugin = DefinePlugin<typeof FILES_PLUGIN_NAME, FilesNodeMap, FilesTypes, FilesData, FilesUtils>

Defined in: files/src/plugin.tsx:108

Files schema plugin type definition.

This type augments the Stately schema runtime with file-related node types, data structures, and utilities.

#See

filesPlugin - Factory function to create this plugin

#FilesUiPlugin

FilesUiPlugin = DefineUiPlugin<typeof FILES_PLUGIN_NAME, FilesPaths, typeof FILES_OPERATIONS, FilesUiUtils, FilesOptions, typeof filesRoutes>

Defined in: files/src/plugin.tsx:150

Files UI plugin type definition.

This type defines the shape of the Files UI plugin, including its API operations, configuration options, and utilities.

#See

filesUiPlugin - Factory function to create this plugin

#FilesUiUtils

FilesUiUtils = DefineUiUtils<{ formatFileSize: (bytes) => string; formatTimestamp: (timestamp?, withTime?) => string | null; getFileEntryIcon: (entryType, isSelected?) => ComponentType<any>; }>

Defined in: files/src/utils.ts:21

Files UI plugin utilities

#FilesUtils

FilesUtils = Record<string, never>

Defined in: files/src/utils.ts:16

Files plugin utilities

#Variables

#FILES_PLUGIN_NAME

const FILES_PLUGIN_NAME: "files"

Defined in: files/src/plugin.tsx:80

Plugin identifier for the Files plugin.

#filesPlugin()

const filesPlugin: <S>() => PluginFactory<S>

Defined in: files/src/plugin.tsx:136

Creates the Files schema plugin factory.

This plugin registers file-related types and utilities into the Stately schema runtime. It should be used with stately().withPlugin().

#Type Parameters

#S

S extends StatelySchemas<any, any>

#Returns

PluginFactory<S>

A plugin factory function that augments the runtime

#Example

import { stately } from '@statelyjs/stately/schema';
import { filesPlugin } from '@statelyjs/files';

const schema = stately<MySchemas>(openapiDoc, PARSED_SCHEMAS)
  .withPlugin(filesPlugin());

#filesUiPlugin

const filesUiPlugin: UiPluginFactoryFn<FilesUiPlugin>

Defined in: files/src/plugin.tsx:186

Creates the Files UI plugin factory.

This plugin registers file-related components, API operations, and navigation routes into the Stately UI runtime. It provides:

• RelativePath field components for edit and view modes
• String primitive transformers
• Typed API operations for file management

#Example

import { statelyUi } from '@statelyjs/stately';
import { filesUiPlugin } from '@statelyjs/files';

const ui = statelyUi({
  plugins: [
    filesUiPlugin({
      api: { pathPrefix: '/api/files' },
    }),
  ],
});

// Access Files API in components
const { plugins } = useStatelyUi();
const result = await plugins.files.api.list_files();

#filesUiUtils

const filesUiUtils: FilesUiUtils

Defined in: files/src/utils.ts:39

Files plugin utilities implementation

#useFilesStatelyUi()

const useFilesStatelyUi: () => StatelyUiRuntime<Schemas<any, any>, readonly [CoreUiPlugin, FilesUiPlugin]>

Defined in: files/src/context.tsx:19

Default hook instance for files plugin Use this in files plugin components and hooks

Access the Stately runtime from React context.

Use this hook in components to access the runtime's plugins, utilities, and configuration. The runtime must be provided via statelyUiProvider.

#Returns

StatelyUiRuntime<Schemas<any, any>, readonly [CoreUiPlugin, FilesUiPlugin]>

The current Stately runtime from context

#Throws

If called outside of a StatelyUiProvider

#Example

function MyComponent() {
  const runtime = useStatelyUi<MySchemas>();

  // Access core plugin utilities
  const icon = runtime.plugins.core.utils.getEntityIcon('Pipeline');

  // Access schema information
  const entities = runtime.schema.utils.getStateEntries();

  return <div>...</div>;
}

#Functions

#createUseFilesStatelyUi()

createUseFilesStatelyUi<Schema>(): () => StatelyUiRuntime<Schema, readonly [CoreUiPlugin, FilesUiPlugin]>

Defined in: files/src/context.tsx:11

Hook for accessing Stately UI runtime with Files plugin

Assumes core plugin is available (since files uses core components like Editor) Returns runtime with type-safe access to core and files plugins

#Type Parameters

#Schema

Schema extends Schemas<any, any> = Schemas<any, any>

#Returns

(): StatelyUiRuntime<Schema, readonly [CoreUiPlugin, FilesUiPlugin]>

Access the Stately runtime from React context.

Use this hook in components to access the runtime's plugins, utilities, and configuration. The runtime must be provided via statelyUiProvider.

#Returns

StatelyUiRuntime<Schema, readonly [CoreUiPlugin, FilesUiPlugin]>

The current Stately runtime from context

#Throws

If called outside of a StatelyUiProvider

#Example

function MyComponent() {
  const runtime = useStatelyUi<MySchemas>();

  // Access core plugin utilities
  const icon = runtime.plugins.core.utils.getEntityIcon('Pipeline');

  // Access schema information
  const entities = runtime.schema.utils.getStateEntries();

  return <div>...</div>;
}

#References

#FilesApi

Re-exports FilesApi

#FilesData

Re-exports FilesData

#FilesNodeType

Re-exports FilesNodeType

#FilesOperations

Re-exports FilesOperations

#FilesPaths

Re-exports FilesPaths

#FilesTypes

Re-exports FilesTypes

#RelativePathNode

Re-exports RelativePathNode

#TFilesNodeType

Re-exports TFilesNodeType