Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
DocumentBrowser control
Build a library view with a precise root and binding
DocumentBrowser is a normal screen node backed by secured DMS operations. It can show a read-only library, select governed references into a field, or offer individually enabled actions under the user’s actual rights. It is not a full document application, an iframe or a source of new permission grants.
Use a deliberately resolved cabinet and optional subtree root. A screen expression that has not resolved to a valid root must not trigger a request for some other cabinet. Design preview is static chrome; ordinary published/Preview interaction is a separate runtime context.
| Setup choice | Decide explicitly |
|---|---|
| Browse-only | selectionMode:none; no bind is required if selection-dependent mutations are off |
| One evidence value | single plus a document-compatible bound field |
| Multiple evidence values | multiple plus a compatible collection field |
| Allowed actions | allowUpload/Download/Move/Delete/Convert/Share describe authored affordances, not server grants |
| Confinement | Cabinet/rootFolder determine navigation scope; move destinations stay in its admitted root |
| Selected reference | kind:document, actual documentId, optional pinned versionNumber and metadata |
| Events | Inspect actual event contracts; LiveForm currently emits onSelect with folderId:null |
Selection can be promoted to single when a move/delete/convert/share affordance needs a target, even if authored selection mode is none. That promotion still does not authorize the effect. A task-bound document operation has its own server admission; embedding a control cannot create it.
The JSON snippets below are individual node/value fragments, not complete screens or importable applications. Validate the owning screen through the actual screen contract and publication workflow. These source-reviewed examples do not claim a newly executed browser, upload or permission-matrix result.
Worked examples
Example FLOW-BC-01 — Embed a browse-only HR policy library
Scenario and inputs. Nadia adds a document library to an admitted leave application screen. The intended users can view its policy cabinet/subtree, but the field must not collect a selection or offer mutation tools. The cabinet/folder strings below stand for actual returned IDs selected by the builder.
{
"id": "hrPolicies",
"type": "DocumentBrowser",
"label": "HR policies",
"cabinetId": "actual-policy-cabinet-id",
"rootFolderId": "actual-policy-root-id",
"selectionMode": "none",
"allowUpload": false,
"allowMove": false,
"allowDelete": false,
"allowConvert": false,
"allowShare": false,
"allowDownload": true
}
Procedure. Place the node through the actual designer and configure its root. With no selection-dependent mutation enabled, omit bind. Save/validate/publish the owning screen with its current revision and impact protocol. In an admitted runtime, navigate the folder tree and breadcrumbs only within the configured root; inspect the actual DMS list response rather than static design chrome.
Expected result. The library can be browsed without inventing a hidden form answer. The author’s root and the server’s current document admission both apply.
Failure and recovery. If the cabinet expression is empty/unresolved, keep the supported empty/unavailable presentation. Do not list all cabinets as a fallback or treat allowDownload as an override for denied content rights.
Sources. LiveForm.tsx:5363; DocumentBrowserControl.tsx:248.
Example FLOW-BC-02 — Store a single governed evidence reference
Scenario and inputs. Mohammad’s published form has an allowed document-compatible evidence field. Nadia configures the library with single selection and the actual supported bind. The value below is an illustrative reference projection; its document ID/version and metadata must come from the selected current response.
{
"kind": "document",
"documentId": "actual-document-id",
"versionNumber": 1,
"name": "Leave evidence.docx",
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"sizeBytes": 12000
}
Procedure. Select the permitted document in the rooted library. Inspect the bound field value and preserve its exact document/version pair when the form is saved/submitted. For multiple selection, author a compatible collection and expect an array of these references rather than silently joining names. Read the actual onSelect/onChange event data if an automation depends on selection; do not infer a folder from a currently null event field.
Expected result. The form stores a governed reference, not file bytes, a download URL or a title used as authority. The optional metadata describes the selection but does not grant download or mutation rights.
Failure and recovery. Correct a field/cardinality mismatch in the authored screen. Do not coerce arbitrary strings/objects into valid references, substitute a latest version for recorded evidence, or add an attachment to a task merely because its label was visible.
Sources. documentBinding.ts:1; DocumentAttachmentRef.java:10; LiveForm.tsx:5417.
Example FLOW-BC-03 — Upload to the current permitted folder inside a subtree
Scenario and inputs. The application deliberately offers upload in a case-evidence library, and the signed-in actor actually has the required destination/task admission. The root is a permitted subtree; it is not a starting hint that allows upward navigation. Upload size/count limits remain the actual DMS capabilities.
Procedure. Configure allowUpload:true only for the intended authored use and resolve cabinet/root correctly. Navigate to the desired admitted descendant and choose a small synthetic file. The control uploads to that current folder and emits onUpload with versions and folderId. Retain the actual returned references and, if selection is part of the form, select/store the supported document reference rather than assuming upload alone submitted the task. Keep mutation flags for move/delete/share off unless each is required and admitted.
Expected result. The uploaded version is associated with the actual current permitted folder, and the form/task still follows its own save/completion operation. Breadcrumbs and move targets do not escape the configured root.
Failure and recovery. A true authoring flag does not grant server rights. On refusal, correct the actual destination/actor/form constraint; do not switch cabinets, spoof a task context or retry through a broad raw API to bypass the denied operation. Reconcile an uncertain upload before another copy.
Sources. DocumentBrowserControl.tsx:276; LiveForm.tsx:5430; DocumentController.java:321.
Example FLOW-BC-04 — Tell empty, denied and temporarily unavailable apart
Scenario and inputs. Three admitted test situations are deliberately different: an authorized folder has no documents; the current reader cannot access the configured root; or an authorized read is temporarily unavailable. Nadia must teach support staff to recognize those states without using sample data or disclosing a protected library’s existence.
Procedure. Open the published node with the intended ordinary reader and inspect its actual state. For a genuinely authorized empty folder, show the normal no-files presentation. For denied access, apply the shared neutral unavailable behavior and omit unauthorized controls/requests. For an access/load outage, use the supported read recovery and refresh only after current access is established. If an action promotes selection to single, inspect that as a targeting behavior, not as newly granted authority.
Expected result. The user is not told that an inaccessible folder is an empty library, and a temporary failure is not mistaken for a permanent denial. Previous protected selection/content does not become a cached disclosure path when current admission fails.
Failure and recovery. Never add a permission-error banner, hidden-object Retry control or fabricated sample file to make the panel look populated. An available convert/share button still needs its actual server checks; an unavailable engine or object grant has its own owner-controlled recovery. Design-canvas screenshots alone cannot prove these runtime permission states.
Sources. DocumentBrowserControl.tsx:338; authorization-visibility-policy.md:1.
Detailed reference
Purpose
DocumentBrowser is an embeddable screen control that exposes the governed
Documents (DMS) library inside forms, App Shells, and dashboards.
Consultants place it like any other design control and configure roots,
selection, and mutation flags with expression-enabled properties.
It is not a full-page Documents app and not an iframe. It is a first-class
ISL control that calls the same /api/documents/* APIs with workspace ACL.
Product decisions (v1)
| Decision | Choice |
|---|---|
| Name | DocumentBrowser |
| Modes | Browse-only and browse + select into a field and browse + upload |
| Default root | Whole cabinet (cabinetId) |
| Selection cardinality | Consultant property: none | single | multiple |
| Drill-down confinement | Cannot navigate above the configured root |
| Document preview | Out of scope (later) |
| Expression dialect | Same as other screen props (${…} / ex!) |
Authoring properties
| Key | Kind | Expression | Meaning |
|---|---|---|---|
label |
text | yes | Field label |
bind |
bind | — | Where selection is stored (when mode ≠ none, or when move/delete/convert/share promotes selection). Not required for browse-only (selectionMode=none with those mutation flags off). |
cabinetId |
text | yes | Root cabinet id (required for load) |
rootFolderId |
text | yes | Optional subtree root; empty = cabinet roots |
selectionMode |
select | no | none | single | multiple |
allowUpload |
exprbool | yes | Show upload into current folder (default false) |
allowDownload |
exprbool | yes | Allow download of listed docs (default true) |
allowMove |
exprbool | yes | Move selected docs within the configured root (default false) |
allowDelete |
exprbool | yes | Soft-delete selected docs (default false) |
allowConvert |
exprbool | yes | Convert Word → PDF when engine available (default false) |
allowShare |
exprbool | yes | Open object security / grants for selected doc (default false) |
showTree |
bool | no | Show left folder tree (default true) |
height |
number | no | Min height in px for the panel (default 360) |
visibleWhen / disabled |
shared | yes | Standard control flags |
When move/delete/convert/share is enabled and selectionMode is none, runtime
promotes selection to single so users can target documents.
Unresolved / empty cabinetId → empty state (fail closed; no cross-cabinet leak).
Runtime behavior
- Resolve expression props in Live / published context.
- Load folders for the cabinet; if
rootFolderIdset, only show that subtree (ancestors above root are not navigable). - Breadcrumb + folder tree (optional) + document list for the current folder.
- Selection: when mode is single/multiple, update
bindwithDocumentAttachmentReforDocumentAttachmentRef[](same shape as FileUpload DMS mode). - Upload: when
allowUploadand actor may mutate, multi-file upload into the current folder (not above root). - Download: when allowed, use
documentsApi.download. - Move / delete / convert / share: when the matching
allow*property is true, selection toolbar actions call the secured DMS APIs (move stays inside root; convert requires a healthy conversion engine; share opens object security). - All list/get/mutation paths use existing secured DMS APIs.
Design canvas (ScreenRenderer) shows a static chrome preview (no live DMS
unless Live mode / published).
Events
| Trigger | Payload |
|---|---|
onSelect |
selection (refs), folderId: null in the current LiveForm adapter |
onNavigate |
folderId, cabinetId |
onUpload |
versions, folderId |
onMove |
documentIds, folderId |
onDelete |
documentIds |
onConvert |
sourceDocumentId, pdfDocumentId, pdfName |
onShare |
documentId |
Surfaces
- Form / task interfaces (LiveForm)
- App Shell pages hosting published screens
- Dashboards embedding the control in a widget region
Security
- Server object grants remain authoritative.
- Cross-workspace cabinet contracts stay read-only as today.
- The control never invents visibility. A permission denial is not proof of an empty document library. Apply the shared neutral unavailable state for denied access; keep transient load failures distinct and never substitute sample files. See authorization visibility policy.
Out of scope (still)
- In-panel document preview / PDF viewer
- Workspace-wide cabinet picker (pass
cabinetIdfrom process/form) - Soft-delete restore UI inside the control
Tests
- Unit: property defaults, expression root resolution, selection write shape, confinement above root
- Registry drift: vocabulary ↔ schema ↔ nodeRegistry
- Human Playwright: toolbox insert → props → Live browse/select/upload shots
Related code
studio/frontend/src/features/screens/document-browser/documentsApi/documentBinding.tsScreenVocabulary/screen.schema.json/nodeRegistry.ts