@bluealba/pae-ui-react-core 4.5.1 → 4.6.0-feature-generalist-file-storage-a-398

package/README.md

@@ -149,6 +149,39 @@ this event and its version and the associated Application (if the module has one
 
 Alternatively you can also use `useTrackEvents()` (plural) hook to publish more than one event in a single call.
 
+### useFileStorage
+
+Imperative SDK client for the platform's File Storage API. Provides authenticated methods to upload, download, preview, update metadata, and delete files. Acts as a facade over the gateway's `/files` endpoints — you do not need to manage tokens, XHR configuration, or blob lifecycle manually.
+
+```typescript jsx
+import { useFileStorage } from '@bluealba/pae-ui-react-core';
+
+const { isEnabled, upload, download, getPreviewUrl, updateMetadata, remove } = useFileStorage();
+
+// Check availability before rendering file UI
+if (!isEnabled) return null;
+
+// Upload a file with optional progress tracking
+const result = await upload(file, {
+  isPublic: false,
+  description: 'Q1 report',
+  metadata: { project: 'alpha' },
+  onProgress: (percent) => console.log(`${percent}%`),
+});
+console.log('Uploaded file id:', result.id);
+
+// Trigger a save-to-disk download
+await download(result.id);
+```
+
+**`isEnabled`** is `false` when `FILE_STORAGE_DRIVER` is not configured on the gateway. All methods reject immediately with `"File storage is disabled on this platform"` in that case — always check `isEnabled` before rendering file controls.
+
+**`getPreviewUrl(id)`** returns a `URL.createObjectURL(blob)` string. The caller is responsible for revoking it via `URL.revokeObjectURL(url)` — typically in a `useEffect` cleanup — to avoid memory leaks.
+
+Requires RBAC operations `files::read` (download, preview) and `files::manage` (upload, update, delete) assigned to the user's role.
+
+For a complete usage guide including abort support, the preview pattern with proper cleanup, and error handling see the **[Using File Storage in React](apps/pae-documentation/docs/guides/using-file-storage-in-react.mdx)** guide.
+
 ## Authorization
 
 In order to render a piece of JSX conditionally based on authorization there are two ways to do this.