Skip to content

Commit 130e514

Browse files
devvaannshdevvaannsh
committed
feat: add placeholder(preview) tab docs in file management
1 parent 7b8bce0 commit 130e514

File tree

4 files changed

+408
-0
lines changed

4 files changed

+408
-0
lines changed

‎docs/05-file-management.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,24 @@ When multiple tabs have the same filename, **Phoenix Code** displays their paren
9595

9696
> The image above shows various UI elements of a tab.
9797
98+
### Preview Tabs
99+
100+
Preview Tabs are temporary tabs created when you single-click a file in the File Tree. They are useful for quick navigation without cluttering your workspace.
101+
102+
Preview Tabs are only visible in the Tab Bar and are not added to the Working Set. They appear in *italic* with a lighter *gray* text.
103+
104+
![Preview Tab](./images/fileManagement/preview-tab.png "Preview Tab")
105+
106+
A preview tab becomes a permanent tab and is added to your Working Set when you:
107+
- Make any change to the file
108+
- Click the preview tab itself
109+
- Save the file
110+
- Double-click the file in the File Tree
111+
112+
Only one preview tab can exist per pane. Opening another file replaces the current preview tab, unless it has already been converted to a permanent tab.
113+
114+
> Double-clicking a file skips the preview and opens it as a permanent tab immediately.
115+
98116
### Tab Bar in Split Panes
99117
When multiple panes are open, each pane has its own Tab Bar and maintains its own list of open tabs.
100118

‎docs/05-file-management.md~‎

Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
---
2+
title: File Management
3+
---
4+
5+
import React from 'react';
6+
import VideoPlayer from '@site/src/components/Video/player';
7+
8+
This section covers how **Phoenix Code** lets you manage, organize, and navigate files and folders within your projects.
9+
10+
---
11+
12+
## File Tree
13+
14+
The **File Tree** appears in the sidebar and shows the complete folder structure of the open project.
15+
It lists all files and folders in a hierarchical view.
16+
17+
![File Tree](./images/fileManagement/file-tree.png "File Tree")
18+
19+
### File Tree Context Menu
20+
21+
When you right-click within the File Tree, a context menu appears which allows you to perform various operations.
22+
> All file and folder operations, such as creating, renaming, deleting and many more are generally performed through this context menu.
23+
24+
The element you right-click in the File Tree becomes the selected context, meaning any operation performed will apply to that item. For example:
25+
- Right-click a **file** → the action applies to that file.
26+
- Right-click a **folder** → the action applies to or inside that folder (e.g., add file, create subfolder, delete contents).
27+
- Right-click on **empty space** → the action applies to the project’s root directory.
28+
29+
> In the image shown below, `index.html` is selected as the context. Any action from the context menu will apply to that file.
30+
31+
![File Tree Keyboard Shortcuts](./images/fileManagement/file-tree-context-menu-key-shortcut.png "File Tree Keyboard Shortcuts")
32+
33+
You can also assign or update keyboard shortcuts for any File Tree action through the context menu using the keyboard button at the side.
34+
35+
See the [Keyboard Shortcuts Guide](./Features/keyboard-shortcuts) for complete details.
36+
37+
### Sorting Files and Folders
38+
39+
By default, the File Tree sorts folders first (in ascending order *a-z*), followed by files.
40+
41+
To sort folders and files together:
42+
1. Click the **double-arrow** at the top-right of the sidebar.
43+
2. In the dropdown, uncheck **Sort Folders First**.
44+
45+
![File Tree folders sort](./images/fileManagement/file-tree-sort-folders-option.png "File Tree folders sort")
46+
47+
Alternatively, you can control this behavior by updating the `sortDirectoriesFirst` property in the preferences file.
48+
See [Editing Preferences](./editing-text#editing-preferences) for details.
49+
50+
Now, files and folders are sorted together in one ascending list.
51+
![File tree sorted](./images/fileManagement/file-tree-sorted.png "File Tree sorted")
52+
> Notice how the `images` folder now appears in alphabetical order with other items.
53+
54+
### Collapse All Folders
55+
56+
The **Collapse All Folders** feature helps you quickly reset your view by collapsing all expanded folders to their root level, leaving only the top-level items visible in the File Tree.
57+
58+
To collapse all folders:
59+
1. Hover over the File Tree header at the top-right.
60+
2. Click the `collapse icon` (two arrows pointing toward each other) that appears.
61+
62+
<VideoPlayer
63+
src="https://docs-images.phcode.dev/videos/file-management/collapse-folders.mp4"
64+
/>
65+
66+
---
67+
68+
## Tab Bar
69+
70+
The **Tab Bar** appears at the top of the editor and displays all open files.
71+
Each file in the Tab Bar is referred to as a **tab**, and you can open as many tabs as you like.
72+
*The Tab Bar helps you switch quickly between files while working.*
73+
74+
![Tab Bar](./images/fileManagement/tab-bar.png "Tab Bar")
75+
76+
The active tab is highlighted with a *blue* marker to distinguish it from inactive ones.
77+
To switch between tabs, simply click the tab you want to view.
78+
79+
To close a tab, click the `×` button beside its name.
80+
For inactive tabs, this button appears only when you hover over them.
81+
82+
**Phoenix Code** shows a small `•` icon on tabs that have unsaved changes.
83+
84+
If you try to close a tab with unsaved changes, **Phoenix Code** displays a confirmation dialog with three options:
85+
* **Don't Save**: Closes the tab without saving changes. All unsaved changes will be lost.
86+
* **Save**: Saves the file and then closes the tab.
87+
* **Cancel**: Keeps the tab open and returns you to editing.
88+
89+
![Save File Dialog](./images/fileManagement/save-file-dialog.png "Save File Dialog")
90+
91+
When multiple tabs have the same filename, **Phoenix Code** displays their parent folder name so you can easily tell them apart.
92+
> Hovering over a tab will show a tooltip with its full path.
93+
94+
![Tab Bar UI](./images/fileManagement/tab-bar-main.png "Tab Bar UI")
95+
96+
> The image above shows various UI elements of a tab.
97+
98+
### Preview Tabs
99+
100+
Preview Tabs are temporary tabs created when you single-click a file in the File Tree. They are useful for quick navigation without cluttering your workspace.
101+
102+
Preview Tabs are only visible in the Tab Bar and are not added to the Working Set. They appear in *italic* with a lighter *gray* text.
103+
104+
![Preview Tab](./images/fileManagement/preview-tab.png "Preview Tab")
105+
106+
A preview tab becomes a normal tab and is added to your Working Set when you:
107+
- Make any change to the file
108+
- Click the preview tab itself
109+
- Save the file
110+
- Double-click the file in the File Tree
111+
112+
Only one preview tab can exist per pane. Opening another file replaces the current preview tab, unless it has already been converted to a permanent tab.
113+
114+
> Double-clicking a file skips the preview and opens it as a permanent tab immediately.
115+
116+
### Tab Bar in Split Panes
117+
When multiple panes are open, each pane has its own Tab Bar and maintains its own list of open tabs.
118+
119+
The active tab in the **active pane** is marked in *blue*,
120+
while the active tab in an **inactive pane** appears in *gray*.
121+
122+
![Split Pane Tab Bar](./images/fileManagement/split-panes-tabs.png "Split Pane Tab Bar")
123+
124+
> A file can appear as a tab in more than one pane.
125+
126+
### Hidden Tabs
127+
When you open a new file, its tab is added to the right of the existing tabs.
128+
If there are more tabs than can fit within the visible area, **Phoenix Code** displays a **Show Hidden Tabs** button.
129+
130+
![Show hidden tabs button](./images/fileManagement/overflow-button.png "Show Hidden Tabs button")
131+
132+
Clicking this button opens a dropdown list of all tabs that are not fully visible.
133+
From this list, you can select a tab to bring it into view or close tabs directly from the dropdown.
134+
135+
<VideoPlayer
136+
src="https://docs-images.phcode.dev/videos/file-management/overflow-tabs.mp4"
137+
/>
138+
139+
### Drag-Drop Tabs
140+
You can reorder tabs by dragging and dropping them.
141+
While dragging, **Phoenix Code** highlights the drop position with a vertical blue marker, showing exactly where the tab will be placed.
142+
143+
Tabs can also be dragged between panes.
144+
<VideoPlayer
145+
src="https://docs-images.phcode.dev/videos/file-management/drag-drop-tabs.mp4"
146+
/>
147+
148+
### Tab Bar Context Menu
149+
When you right-click a tab, a context menu appears which has multiple options so that you can work with tabs easily.
150+
151+
![Tab bar context menu](./images/fileManagement/tab-bar-context-menu.png "Tab bar context menu")
152+
> These options provide quick access to common file operations directly from the Tab Bar.
153+
154+
### Git - Tab Bar
155+
The Tab Bar displays Git file status indicators, showing which files are **untracked** or **modified**.
156+
157+
![Tab bar Git](./images/fileManagement/tab-bar-git.png "Tab bar Git")
158+
159+
- A **green marker** indicates an **untracked** file.
160+
- An **orange marker** indicates a **modified** file.
161+
162+
For files that are **gitignored**, **Phoenix Code** shows the tab name in *gray italics*.
163+
164+
> These indicators appear only when your project is a Git repository.
165+
166+
### Limiting the Number of Tabs
167+
**Phoenix Code** allows you to control the maximum number of tabs displayed in the Tab Bar at once.
168+
By default, the value is set to `-1`, which means all open tabs are displayed.
169+
170+
For example, if you want to show a maximum of **3 tabs** in the Tab Bar, you can add the following to your preferences file:
171+
172+
```json
173+
"tabBar.options": {
174+
"numberOfTabs": 3,
175+
"showTabBar": true
176+
}
177+
```
178+
You can set `numberOfTabs` to any positive number to define the maximum tab limit.
179+
If you set it to `0`, the Tab Bar will be hidden entirely.
180+
Any negative value (such as `-1`) displays all open tabs without restriction.
181+
> The active tab is always visible, except when the `numberOfTabs` value is set to `0`.
182+
183+
### Showing or Hiding the Tab Bar
184+
You can enable or disable the Tab Bar in several ways:
185+
186+
#### 1. From the View Menu
187+
Go to `View > File Tab Bar` to toggle it on or off.
188+
189+
![View > File Tab Bar](./images/fileManagement/disable-tab-bar-1.png "View > File Tab Bar")
190+
191+
#### 2. From the Sidebar
192+
Click the **double-arrow** icon in the top-right corner of the sidebar,
193+
then use the `Show File Tab Bar` option in the dropdown to toggle the Tab Bar.
194+
195+
![Disable Tab Bar](./images/fileManagement/disable-tab-bar-2.png "Disable Tab Bar")
196+
197+
#### 3. From Preferences
198+
You can also toggle the Tab Bar by updating the `showTabBar` option in the preferences file.
199+
```json
200+
"tabBar.options": {
201+
"showTabBar": false
202+
}
203+
```
204+
*Add this in your preferences file to hide the Tab Bar.*
205+
Set the value to `true` to enable it.
206+
See [Editing Preferences](./editing-text#editing-preferences) if you need help in editing the preferences.
207+
208+
---
209+
210+
## Working Files
211+
**Working Files** (also called **Working Tree**) provides another way to view and manage open files. It appears in the sidebar, above the **File Tree**.
212+
213+
![Working Files](./images/fileManagement/working-files.png "Working Files")
214+
215+
Working Files and Tab Bar are synchronized, which means that any operation performed on one (closing, reordering, opening files, etc.) is automatically reflected on the other.
216+
217+
Working Files displays the same UI elements as the Tab Bar:
218+
* `•` icon for unsaved files
219+
* `×` button to close files
220+
* Parent folder names when multiple files have the same filename
221+
* Tooltip showing full file path on hover
222+
* Git status indicators (green for untracked, orange for modified files and gray italics for gitignored files)
223+
224+
> See the [Tab Bar](#tab-bar) section for detailed explanations of these features.
225+
226+
> **Note**: Unlike Tab Bar, you cannot control the maximum number of files displayed in Working Files.
227+
228+
### Working Files in Split Panes
229+
When using split panes, each pane maintains its own list of open files in Working Files.
230+
231+
The panes are labeled based on the split orientation:
232+
* **Vertical Split**: *Left* (first pane) and *Right* (second pane)
233+
* **Horizontal Split**: *Top* (first pane) and *Bottom* (second pane)
234+
235+
![Working Files Split Panes](./images/fileManagement/working-files-split-panes.png "Working Files Split Panes")
236+
237+
### Drag-Drop in Working Files
238+
You can reorder files in Working Files by dragging and dropping them, just like in the Tab Bar.
239+
240+
<VideoPlayer
241+
src="https://docs-images.phcode.dev/videos/file-management/drag-drop-working-files.mp4"
242+
/>
243+
244+
### Working Files Context Menu
245+
When you right-click a file in Working Files, a context menu appears with various file operations.
246+
247+
![Working Files context menu](./images/fileManagement/working-files-context-menu.png "Working Files context menu")
248+
> These options provide quick access to common file operations directly from Working Files.
249+
250+
### Showing or Hiding Working Files
251+
You can show or hide the Working Files panel in two ways:
252+
253+
#### 1. From the Sidebar
254+
Click the **double-arrow** icon in the top-right corner of the sidebar, then use the `Show Working Files` option in the dropdown to toggle Working Files.
255+
256+
![Disable Working Files](./images/fileManagement/disable-working-files.png "Disable Working Files")
257+
258+
#### 2. From Preferences
259+
You can also toggle Working Files by updating the `showWorkingSet` property in the preferences file.
260+
```json
261+
"showWorkingSet": true
262+
```
263+
Set the value to `false` to hide Working Files.
264+
See [Editing Preferences](./editing-text#editing-preferences) if you need help editing the preferences.
265+
266+
---
267+
268+
## Recent Files
269+
270+
The **Recent Files** dialog provides quick access to files you've recently worked on.
271+
272+
### Opening Recent Files
273+
* **Desktop App**: Press `Ctrl + R`.
274+
* **Browser**: Press `Ctrl + Alt + Shift + O` (as `Ctrl + R` is reserved for browser reloads).
275+
276+
To customize the keyboard shortcut, refer to the [Keyboard Shortcuts Guide](./Features/keyboard-shortcuts#changing-a-keyboard-shortcut).
277+
278+
![Recent Files Dialog](./images/fileManagement/recent-files.png "Recent Files Dialog Box")
279+
280+
The dialog shows your recently opened files. Closed files appear in gray. Hover over them to see an `x` icon. Click it to remove them from the list. The `Clear` button at the bottom removes all closed files at once.
281+
282+
> Currently open files cannot be removed from this list. Close them first to remove them.
283+
284+
To view a file's full path, hover over it or check the bottom-left corner of the dialog when a file is selected.
285+
286+
---
287+
288+
## File Recovery
289+
290+
**Phoenix Code** has a built-in **File Recovery** feature to help you retrieve unsaved changes after unexpected events like crashes or accidental closures.
291+
292+
### Recovering Files After a Crash
293+
When you reopen the editor, if there are any unsaved changes from the previous session, a dialog box will appear with two options: `Discard` and `Restore`.
294+
295+
![File Recovery Dialog Box](./images/fileManagement/file-recovery.png "File Recovery Dialog Box")
296+
297+
* **Restore**: Recovers your unsaved files by reinstating all changes made before the last save.
298+
299+
* **Discard**: Removes the unsaved changes. *This will permanently delete the data.*
300+

0 commit comments

Comments
 (0)