# DesktopLocations > Manage the folders a desktop app may use, such as Orchestra workspace roots. Add and remove folders, set read, write and index permissions per folder, see status and the default, plus a DesktopLocationPicker. Source: https://docs.nasaqui.com/components/desktop-locations ## Install ```bash npx shadcn@latest add https://docs.nasaqui.com/r/desktop-locations.json ``` The settings screen for "which folders can this app touch". Each location is an absolute path on the user's computer with a status (ready, indexing, missing, not a folder, access denied), three permissions (read, write, include in the search index) and an optional default mark. It matches how an Orchestra workspace works: the roots confine the file tools and the search index, the first root is the default and relative paths resolve against it. Add opens a dialog that checks the path as you type: it must be absolute, must not repeat an existing location, and it warns when the folder is inside or contains another one. `onBrowse` plugs in the system folder picker from the desktop bridge. Removing a location only stops the app using it, files on disk stay. `DesktopLocationPicker` is a small `Select` to choose one of the locations elsewhere in the app. ## When to use - A desktop app or local agent settings page where the user grants folder access. ## When not to use - Server storage or cloud files: use `FileExplorer`. - A single path text field: use `Input`. ## Import ```tsx import { DesktopLocations, DesktopLocationPicker } from "@fadymondy/nasaq/web"; // inside this monorepo: "@nasaq/web" ``` ## Quick start ```tsx import { DesktopLocations, type DesktopLocation } from "@fadymondy/nasaq/web"; declare const locations: DesktopLocation[]; declare const bridge: { pickFolder(): Promise; add(path: string): Promise; remove(id: string): Promise }; export function Roots() { return ( bridge.add(path)} onRemove={bridge.remove} /> ); } ``` ## Anatomy ``` DesktopLocations data-slot="desktop-locations" ├─ heading, description, Add folder ├─ list data-slot="desktop-location": name, path, Status, Default badge, counts │ ├─ permissions Read, Write, Index switches │ └─ actions Make default, Re-index, Remove ├─ Alert explains an unusable location (missing, not a folder, denied) └─ Dialog, AlertDialog add (with path check and Browse), remove confirm DesktopLocationPicker Select of usable locations ``` ## API **DesktopLocations**: every `section` prop except `children` and `title`, plus: | Prop | Type | Default | Description | | --- | --- | --- | --- | | `locations` | `DesktopLocation[]` | required | `{ id, path, label?, status, permissions: { read, write, index }, primary?, fileCount?, indexedAt?, addedAt? }`. | | `onAdd` | `(path, permissions) => Promise` | | Shows Add folder. `{ error }` keeps the dialog open. | | `onRemove` | `(id) => Promise<...>` | | Shows Remove, after a confirm. | | `onPermissionsChange` | `(id, permissions) => Promise<...>` | | Makes the switches editable. | | `onMakeDefault` | `(id) => Promise<...>` | | Shows Make default on the other locations. | | `onReindex` | `(id) => Promise<...>` | | Shows a refresh on ready locations that have Index on. | | `onBrowse` | `() => Promise` | | Opens the system picker. Shows Browse in the dialog. | | `loading` | `boolean` | `false` | Skeleton rows. | | `title`, `description` | `ReactNode` | | Replace the heading and the line under it. | | `labels` | `Partial` | | Override any string. | **DesktopLocationPicker**: `locations`, `value`, `onValueChange(id, location)`, `requires` (`read`, `write` or `index`, default `read`), `disabled`, `placeholder`, `aria-label`, `labels`. **Helpers** (pure, tested): `checkLocationPath`, `isAbsolutePath`, `normalizePath`, `samePath`, `pathContains`, `baseName`, `shortenPath`. ## Examples **Choose where to save** ```tsx setTarget(id)} aria-label="Save to" /> ``` ## Accessibility - Each permission is a labelled switch that names its folder. Status is a word plus a shape, not colour alone. - Dialog errors and path problems are announced with `role="alert"`. Remove asks through an `AlertDialog`. ## RTL & i18n - English and Arabic strings follow the Nasaq locale. Paths are always ``, with Windows and POSIX styles both supported. - Windows paths compare case-insensitively, POSIX paths do not. ## Styling & tokens - Built on `Status`, `Badge`, `Switch`, `Dialog`, `AlertDialog`, `Select`, `Alert` and `--nq-*` tokens. - Target `[data-slot="desktop-locations"]` and `[data-slot="desktop-location"]`. ## Do / Don't - Do check the path again in the desktop app: the component cannot see the disk. - Do report a missing or denied folder through `status`, so the user can fix or remove it. - Don't add a broad folder such as the drive root without a warning of your own. - Don't treat the permissions here as the sandbox: enforce them in the app that reads files. ## Related - [`FileExplorer`](https://docs.nasaqui.com/components/file-explorer) - [`Select`](https://docs.nasaqui.com/components/select) - [`Status`](https://docs.nasaqui.com/components/status) ## Lab https://docs.nasaqui.com/?path=/docs/components-apps-platforms-desktop-locations--docs ## Code ### React ```tsx import { DesktopLocations, type DesktopLocation } from "@fadymondy/nasaq/web"; declare const locations: DesktopLocation[]; declare const bridge: { pickFolder(): Promise; add(path: string): Promise; remove(id: string): Promise }; export function Roots() { return ( bridge.add(path)} onRemove={bridge.remove} /> ); } ``` ### shadcn ```tsx import { DesktopLocations, type DesktopLocation } from "@/components/ui/desktop-locations"; declare const locations: DesktopLocation[]; declare const bridge: { pickFolder(): Promise; add(path: string): Promise; remove(id: string): Promise }; export function Roots() { return ( bridge.add(path)} onRemove={bridge.remove} /> ); } ``` ### Vue ```vue ``` ### Blade ```blade @php $locations = [ ['id' => 'l1', 'path' => 'C:\Users\sara\projects\app', 'label' => 'App', 'status' => 'ready', 'permissions' => ['read' => true, 'write' => true, 'index' => true], 'primary' => true, 'fileCount' => 1240, 'indexedAt' => '2025-03-01T08:00:00Z'], ['id' => 'l2', 'path' => '/home/sara/notes', 'status' => 'ready', 'permissions' => ['read' => true, 'write' => false, 'index' => false], 'fileCount' => 38], ['id' => 'l3', 'path' => 'D:\archive', 'status' => 'missing', 'permissions' => ['read' => true, 'write' => false, 'index' => false]], ]; @endphp
``` ### HTML + Alpine ```html

Locations on this computer

Folders the desktop app can read and change for you. It cannot open anything outside them.

  • App Default Ready
    C:\Users\sara\projects\app 1,240 files · Indexed
  • notes Ready
    /home/sara/notes 38 files · Not indexed
  • archive Folder not found
    D:\archive

3 folders · Relative paths resolve against the default folder.

```