update evaluator docs, workspace snippet (#995)

* add missing docs and code hints

* update app evaluator docs and code hints

.gitignore

@@ -23,6 +23,7 @@
 !.vscode/tasks.json
 !.vscode/launch.json
 !.vscode/extensions.json
+!.vscode/*.code-snippets
 .history
 
 # misc

.vscode/typescript.code-snippets

@@ -0,0 +1,19 @@
+{
+  "ext-evaluator": {
+    "description": "Generate a new evaluator.",
+    "scope": "typescript",
+    "prefix": "ext-evaluator",
+    "body": [
+      "/**",
+      " * Checks if ${2:<description>}.",
+      " * JSON ref: `app.$1`",
+      " */",
+      "export function ${1:name}(",
+      "\tcontext: AppRuleContext,",
+      "\t...args: RuleParameter[]",
+      "): boolean {",
+      "\treturn ${3:true};${0}",
+      "}"
+    ]
+  }
+}

docs/extending/rules.md

@@ -140,9 +140,10 @@ The button will be visible only when the linked rule evaluates to `true`.
 | app.selection.first.canUpdate       | User has permission to update selected node(s).              |
 | app.selection.file                  | A single File node is selected.                              |
 | app.selection.file.canShare         | User is able to share the selected file.                     |
-| app.selection.file.isShared         | A shared node is selected                                    |
-| app.selection.file.isLocked         | File is locked for editing                                   |
-| app.selection.file.canUploadVersion | User can update file version                                 |
+| app.selection.file.isShared         | A shared node is selected.                                   |
+| app.selection.file.isLocked         | File is locked for editing.                                  |
+| app.selection.file.isLockOwner      | File is locked and current user is the lock owner.           |
+| app.selection.file.canUploadVersion | User can update file version.                                |
 | app.selection.library               | A single Library node is selected.                           |
 | app.selection.isPrivateLibrary      | A private Library node is selected.                          |
 | app.selection.hasLibraryRole        | The selected Library node has a role property.               |
@@ -164,25 +165,28 @@ for example mixing `core.every` and `core.not`.
 **Tip:** You can also negate any rule by utilizing a `!` prefix:
 `!app.navigation.isTrashcan` is the opposite of the `app.navigation.isTrashcan`.
 
-| Key                               | Description                                             |
-| --------------------------------- | ------------------------------------------------------- |
-| app.navigation.folder.canCreate   | User can create content in the currently opened folder. |
-| app.navigation.folder.canUpload   | User can upload content to the currently opened folder. |
-| app.navigation.isTrashcan         | User is using the **Trashcan** page.                    |
-| app.navigation.isNotTrashcan      | Current page is not a **Trashcan**.                     |
-| app.navigation.isLibraries        | User is using a **Libraries** page.                     |
-| app.navigation.isNotLibraries     | Current page is not a **Libraries** page.               |
-| app.navigation.isSharedFiles      | User is using the **Shared Files** page.                |
-| app.navigation.isNotSharedFiles   | Current page is not **Shared Files**.                   |
-| app.navigation.isFavorites        | User is using the **Favorites** page.                   |
-| app.navigation.isNotFavorites     | Current page is not **Favorites**                       |
-| app.navigation.isRecentFiles      | User is using the **Recent Files** page.                |
-| app.navigation.isNotRecentFiles   | Current page is not **Recent Files**.                   |
-| app.navigation.isSearchResults    | User is using the **Search Results** page.              |
-| app.navigation.isNotSearchResults | Current page is not the **Search Results**.             |
-| app.navigation.isSharedPreview    | Current page is preview **Shared Files**                |
-| app.navigation.isFavoritesPreview | Current page is preview **Favorites**                   |
-| app.navigation.isSharedFileViewer | Current page is shared file preview page                |
+| Key                               | Description                                                      |
+| --------------------------------- | ---------------------------------------------------------------- |
+| app.navigation.folder.canCreate   | User can create content in the currently opened folder.          |
+| app.navigation.folder.canUpload   | User can upload content to the currently opened folder.          |
+| app.navigation.isTrashcan         | User is using the **Trashcan** page.                             |
+| app.navigation.isNotTrashcan      | Current page is not a **Trashcan**.                              |
+| app.navigation.isLibraries        | User is using a **Libraries** or **Library Search Result** page. |
+| app.navigation.isNotLibraries     | Current page is not a **Libraries** page.                        |
+| app.navigation.isSharedFiles      | User is using the **Shared Files** page.                         |
+| app.navigation.isNotSharedFiles   | Current page is not **Shared Files**.                            |
+| app.navigation.isFavorites        | User is using the **Favorites** page.                            |
+| app.navigation.isNotFavorites     | Current page is not **Favorites**.                               |
+| app.navigation.isRecentFiles      | User is using the **Recent Files** page.                         |
+| app.navigation.isNotRecentFiles   | Current page is not **Recent Files**.                            |
+| app.navigation.isSearchResults    | User is using the **Search Results** page.                       |
+| app.navigation.isNotSearchResults | Current page is not the **Search Results**.                      |
+| app.navigation.isSharedPreview    | Current page is preview **Shared Files**.                        |
+| app.navigation.isFavoritesPreview | Current page is preview **Favorites**.                           |
+| app.navigation.isSharedFileViewer | Current page is shared file preview page.                        |
+| app.navigation.isPreview          | Current page is **Preview**.                                     |
+| app.navigation.isPersonalFiles    | Current page is **Personal Files**.                              |
+| app.navigation.isLibraryFiles     | Current page is **Library Files**.                               |
 
 **Tip:** See the [Registration](/extending/registration) section for more details
 on how to register your own entries to be re-used at runtime.

src/app/extensions/core.extensions.module.ts

@@ -123,6 +123,7 @@ export class CoreExtensionsModule {
       'app.selection.file.canShare': app.canShareFile,
       'app.selection.file.isShared': app.isShared,
       'app.selection.file.isLocked': app.hasLockedFiles,
+      'app.selection.file.isLockOwner': app.isUserWriteLockOwner,
       'app.selection.file.canUploadVersion': app.canUploadVersion,
       'app.selection.library': app.hasLibrarySelected,
       'app.selection.isPrivateLibrary': app.isPrivateLibrary,

src/app/extensions/evaluators/app.evaluators.ts

@@ -36,6 +36,10 @@ import {
   isPreview
 } from './navigation.evaluators';
 
+/**
+ * Checks if user can mark selected nodes as **Favorite**.
+ * JSON ref: `app.selection.canAddFavorite`
+ */
 export function canAddFavorite(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -53,6 +57,10 @@ export function canAddFavorite(
   return false;
 }
 
+/**
+ * Checks if user can un-mark selected nodes as **Favorite**.
+ * JSON ref: `app.selection.canRemoveFavorite`
+ */
 export function canRemoveFavorite(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -66,6 +74,10 @@ export function canRemoveFavorite(
   return false;
 }
 
+/**
+ * Checks if user can share selected file.
+ * JSON ref: `app.selection.file.canShare`
+ */
 export function canShareFile(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -76,6 +88,10 @@ export function canShareFile(
   return false;
 }
 
+/**
+ * Checks if the selected file is already shared.
+ * JSON ref: `app.selection.file.isShared`
+ */
 export function isShared(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -98,6 +114,10 @@ export function isShared(
   return false;
 }
 
+/**
+ * Checks if user can delete selected nodes.
+ * JSON ref: `app.selection.canDelete`
+ */
 export function canDeleteSelection(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -133,6 +153,10 @@ export function canDeleteSelection(
   return false;
 }
 
+/**
+ * Checks if user can un-share selected nodes.
+ * JSON ref: `app.selection.canUnshare`
+ */
 export function canUnshareNodes(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -145,13 +169,21 @@ export function canUnshareNodes(
   return false;
 }
 
+/**
+ * Checks if user selected anything.
+ * JSON ref: `app.selection.notEmpty`
+ */
 export function hasSelection(
   context: RuleContext,
   ...args: RuleParameter[]
 ): boolean {
   return !context.selection.isEmpty;
 }
 
+/**
+ * Checks if user can create a new folder with current path.
+ * JSON ref: `app.navigation.folder.canCreate`
+ */
 export function canCreateFolder(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -163,6 +195,10 @@ export function canCreateFolder(
   return false;
 }
 
+/**
+ * Checks if user can upload content to current folder.
+ * JSON ref: `app.navigation.folder.canUpload`
+ */
 export function canUpload(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -174,6 +210,10 @@ export function canUpload(
   return false;
 }
 
+/**
+ * Checks if user can download selected nodes (either files or folders).
+ * JSON ref: `app.selection.canDownload`
+ */
 export function canDownloadSelection(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -189,6 +229,10 @@ export function canDownloadSelection(
   return false;
 }
 
+/**
+ * Checks if user has selected a folder.
+ * JSON ref: `app.selection.folder`
+ */
 export function hasFolderSelected(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -197,6 +241,10 @@ export function hasFolderSelected(
   return folder ? true : false;
 }
 
+/**
+ * Checks if user has selected a library (site).
+ * JSON ref: `app.selection.library`
+ */
 export function hasLibrarySelected(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -205,6 +253,10 @@ export function hasLibrarySelected(
   return library ? true : false;
 }
 
+/**
+ * Checks if user has selected a **private** library (site)
+ * JSON ref: `app.selection.isPrivateLibrary`
+ */
 export function isPrivateLibrary(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -219,6 +271,10 @@ export function isPrivateLibrary(
     : false;
 }
 
+/**
+ * Checks if the selected library has a **role** property defined.
+ * JSON ref: `app.selection.hasLibraryRole`
+ */
 export function hasLibraryRole(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -227,13 +283,21 @@ export function hasLibraryRole(
   return library ? !!(library.entry && library.entry.role) : false;
 }
 
+/**
+ * Checks if the selected library has no **role** property defined.
+ * JSON ref: `app.selection.hasNoLibraryRole`
+ */
 export function hasNoLibraryRole(
   context: RuleContext,
   ...args: RuleParameter[]
 ): boolean {
   return !hasLibraryRole(context, ...args);
 }
 
+/**
+ * Checks if user has selected a file.
+ * JSON ref: `app.selection.file`
+ */
 export function hasFileSelected(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -242,6 +306,10 @@ export function hasFileSelected(
   return file ? true : false;
 }
 
+/**
+ * Checks if user can update the first selected node.
+ * JSON ref: `app.selection.first.canUpdate`
+ */
 export function canUpdateSelectedNode(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -264,6 +332,10 @@ export function canUpdateSelectedNode(
   return false;
 }
 
+/**
+ * Checks if user can update the first selected folder.
+ * JSON ref: `app.selection.folder.canUpdate`
+ */
 export function canUpdateSelectedFolder(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -279,6 +351,10 @@ export function canUpdateSelectedFolder(
   return false;
 }
 
+/**
+ * Checks if user has selected a **locked** file node.
+ * JSON ref: `app.selection.file.isLocked`
+ */
 export function hasLockedFiles(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -300,6 +376,10 @@ export function hasLockedFiles(
   return false;
 }
 
+/**
+ * Checks if the selected file has **write** or **read-only** locks specified.
+ * JSON ref: `app.selection.file.isLocked`
+ */
 export function isWriteLocked(
   context: AppRuleContext,
   ...args: RuleParameter[]
@@ -316,6 +396,11 @@ export function isWriteLocked(
   );
 }
 
+/**
+ * Checks if the selected file has **write** or **read-only** locks specified,
+ * and that current user is the owner of the lock.
+ * JSON ref: `app.selection.file.isLockOwner`
+ */
 export function isUserWriteLockOwner(
   context: AppRuleContext,
   ...args: RuleParameter[]
@@ -328,6 +413,10 @@ export function isUserWriteLockOwner(
   );
 }
 
+/**
+ * Checks if user can lock selected file.
+ * JSON ref: `app.selection.file.canLock`
+ */
 export function canLockFile(
   context: AppRuleContext,
   ...args: RuleParameter[]
@@ -337,6 +426,10 @@ export function canLockFile(
   );
 }
 
+/**
+ * Checks if user can unlock selected file.
+ * JSON ref: `app.selection.file.canLock`
+ */
 export function canUnlockFile(
   context: AppRuleContext,
   ...args: RuleParameter[]
@@ -349,6 +442,10 @@ export function canUnlockFile(
   );
 }
 
+/**
+ * Checks if user can upload a new version of the file.
+ * JSON ref: `app.selection.file.canUploadVersion`
+ */
 export function canUploadVersion(
   context: AppRuleContext,
   ...args: RuleParameter[]