# UnifiedFiler Product v1.0 Public API Contract

UnifiedFiler Product v1.0.0 is the first stable Host-facing product API release. The package remains an AMD / RequireJS frontend package and is intended to be embedded by a Host system such as UnifiedDesktop, UnifiedViewer, UnifiedEditor, Owners Reform, or Sappane Tools.

## Runtime policy

- jQuery 2.1.4
- jQuery UI 1.12.1
- RequireJS / AMD
- classic `<script>` loading
- no Vue / React
- HTTP-served frontend runtime, not `file://`
- Google Drive integration is frontend-only: Google Identity Services, OAuth token, Drive API v3, and `fetch`

## Stable package entry

```javascript
require(['UnifiedFiler/main'], function (UnifiedFiler) {
    console.log(UnifiedFiler.productVersion); // 1.0.0
});
```

## Stable top-level helpers

```javascript
var app = UnifiedFiler.create({ language: 'ja' });
var explorer = UnifiedFiler.createExplorer('#host', { defaultStorage: 'appStorage' });
var picker = UnifiedFiler.createPicker({ selectionType: 'file' });
var saver = UnifiedFiler.createSaver({ workflow: 'saveAs' });
```

## Stable Control APIs

### UnifiedFilerControl

- `createExplorer(container, options)`
- `createPicker(options)`
- `openPicker(options)`
- `createSaver(options)`
- `openSaver(options)`
- `registerPreviewProvider(provider)`
- `registerPreviewProviders(providers)`
- `registerCreateType(type)`
- `registerCreateTypes(types)`
- `unregisterCreateType(typeId)`
- `registerProfile(name, profile)`
- `destroy()`

### FileExplorerControl

- `mount()` / `destroy()`
- `exec(commandId, args)` / `canExec(commandId)`
- `getCommandState()` / `getCommandStateMap()` / `getCommandsForSurface(surface)`
- `openFolder(pathOrEntry, adapterId)` / `openPath(adapterId, path)`
- `refresh(options)` / `setStorage(adapterId)` / `setViewMode(viewMode)`
- `getSelection()` / `clearSelection()` / `startInlineRename(entry)`
- `getState()` / `getView()`
- `registerCommand(command)`
- `registerCreateType(type)` / `registerCreateTypes(types)` / `unregisterCreateType(typeId)` / `createItem(typeId, options)`
- `registerPreviewProvider(provider)` / `registerPreviewProviders(providers)` / `unregisterPreviewProvider(providerId)`
- `on(name, handler)` / `off(name, handler)` / `emit(name, payload)`

### FilePickerControl

- `mount()` / `destroy()` / `open()` / `select()`
- `refresh()` / `openPath(adapterId, path)` / `openFolder(pathOrEntry, adapterId)` / `setStorage(adapterId)`
- `mountStorage(adapterId)` for This Device / LocalDisk folder attach flow
- `getSelection()` / `getState()`
- `registerPreviewProvider(provider)` / `registerPreviewProviders(providers)` / `unregisterPreviewProvider(providerId)`
- `on(name, handler)` / `off(name, handler)` / `emit(name, payload)`

### FileSaverControl

- `mount()` / `destroy()` / `open()`
- `save(data, options)` / `getSaveRequest()`
- `setFileName(name)` / `setData(data)` / `setWorkflow(workflow)`
- `refresh()` / `openPath(adapterId, path)` / `openFolder(pathOrEntry, adapterId)` / `setStorage(adapterId)`
- `mountStorage(adapterId)` for This Device / LocalDisk folder attach flow
- `getState()`
- `on(name, handler)` / `off(name, handler)` / `emit(name, payload)`

## Extension contracts

### Create Type

```javascript
explorer.registerCreateType({
    id: 'dokuwiki-page',
    kind: 'file',
    label: 'DokuWiki Page',
    defaultName: 'new-page.txt',
    mimeType: 'text/plain',
    content: '====== New Page ======\n\n'
});

explorer.exec('createItem', { typeId: 'dokuwiki-page' });
```

### Preview Provider

```javascript
explorer.registerPreviewProvider({
    id: 'model-preview',
    extensions: ['.umdlx'],
    priority: 100,
    render: function (context) {
        return context.read().then(function (result) {
            return result.data.text();
        }).then(function (text) {
            return { html: '<pre>' + context.escape(text) + '</pre>' };
        });
    }
});
```

### Command

```javascript
explorer.registerCommand({
    id: 'hostAction',
    labelKey: 'hostAction',
    toolbar: true,
    context: true,
    isVisible: function () { return true; },
    isEnabled: function (state) { return state.selection.length === 1; },
    execute: function (args, state) { return Promise.resolve(state.selection[0]); },
    getState: function (state) {
        return {
            id: 'hostAction',
            labelKey: 'hostAction',
            visible: true,
            enabled: state.selection.length === 1,
            toolbar: true,
            context: true
        };
    }
});
```

## Contract inspection

```javascript
var contract = UnifiedFiler.getPublicApiContract();
console.log(contract.version, contract.stability);
```

The same contract is exposed by `services.PublicApiContractService`.


## Product v1.0.0 additions based on dev-2.1.0

- Extended metadata editing UI.
- PermissionPolicyService and capability badges.
- FileSaver workflow/export-format UI.
- HostApplicationBridgeService for UnifiedDesktop / Viewer / Editor / Owners Reform / Sappane Tools.
- GoogleDriveWorkflowService descriptors.
- PHP / Node.js backend API samples.