Merge branch 'master' into documentation-updates

# Conflicts:
#	README.md
#	advanced-README.md

.eslintignore

@@ -1,2 +1,3 @@
-npm node_modules
-build
+node_modules/
+
+main.js

README.md

@@ -1,9 +1,8 @@
-# Simplified README.md
-
 > This is a simple version of README which highlights the **basic scenario and most commonly used feature**
 >
-> The [long and much more detailed README.md is here](./advanced-README.md)
+> The [long and much more detailed advanced-README.md is here](./advanced-README.md)
 
+---
 ## Freely arrange notes and folders in File Explorer (https://obsidian.md plugin)
 
 Take full control of the order of your notes and folders:
@@ -26,6 +25,7 @@ Take full control of the order of your notes and folders:
 - folders not set up for the custom order remain on the standard Obsidian sorting
 - support for imposing inheritance of order specifications with flexible exclusion and overriding logic
 
+---
 ## Basic scenario: set the custom sorting order for a specific folder
 
 Create a new note named `sortspec` in the folder for which you want to configure the sorting
@@ -39,8 +39,8 @@ sorting-spec: |
 ---
 ```
 
-Click the ribbon button (![Inactive](./docs/icons/icon-inactive.png)) to tell the plugin to read the sorting specification and apply it.
-The ribbon icon should turn (![Active](./docs/icons/icon-active.png)) and the sorting should be applied to the folder
+Click the ribbon button (![Inactive](./docs/icons/icon-inactive.png) or ![Static icon](./docs/icons/icon-mobile-initial.png) on phone) to tell the plugin to read the sorting specification and apply it.
+The sorting should be applied to the folder. On desktops and tablets the ribbon icon should turn (![Active](./docs/icons/icon-active.png))
 
 !!! **Done!** !!!
 
@@ -50,6 +50,7 @@ An illustrative image which shows the reverse alphabetical order applied to the
 
 ![Basic example](./docs/svg/simplest-example-3.svg)
 
+---
 ### Remarks
 
 > Remarks:
@@ -65,6 +66,7 @@ An illustrative image which shows the reverse alphabetical order applied to the
 > - indentation matters in YAML -> the two leading spaces in `  order-desc: a-z` are intentional and required
 > - this common example only touches the surface of the rich capabilities of this custom sorting plugin. For more details go to [advanced version of README.md](./advanced-README.md)
 
+---
 ## Basic automatic sorting methods
 
 The list of basic automatic sorting orders includes:
@@ -113,16 +115,30 @@ Refer to the [TL;DR section of advanced README.md](./advanced-README.md#tldr-usa
 
 Click the ribbon icon to toggle the plugin between enabled and suspended states.
 
-States of the ribbon icon:
+States of the ribbon icon on large-screen devices (desktops, laptops and tablets like iPad):
 
 - ![Inactive](./docs/icons/icon-inactive.png) Plugin suspended. Custom sorting NOT applied.
 - ![Active](./docs/icons/icon-active.png) Plugin active, custom sorting applied.
 - ![Error](./docs/icons/icon-error.png) Syntax error in custom sorting configuration.
 - ![General Error](./docs/icons/icon-general-error.png) Plugin suspended. General error.
-- ![Sorting not applied](./docs/icons/icon-not-applied.png) Plugin enabled but the custom sorting was not applied.
+- ![Sorting not applied](./docs/icons/icon-not-applied.png) Plugin enabled, but the custom sorting was not applied.
+- ![Static icon](./docs/icons/icon-mobile-initial.png) (Only on large-screen mobile devices like iPad). 
+  Plugin enabled. but the custom sorting was not applied.
+
+On small-screen mobile devices (phones) the icon is static:
+
+- ![Static icon](./docs/icons/icon-mobile-initial.png) The icon acts as a button to toggle between enabled and disabled. Its appearance doesn't change
 
 For more details on the icon states refer to [Ribbon icon section of the advanced-README.md](./advanced-README.md#ribbon-icon)
 
+## Small screen mobile devices remarks
+
+- you might need to activate the custom sorting on your mobile separately, even if on a shared vault the custom sorting was activated on desktop
+- the Obsidian command palette being easily available (swipe down gesture on small-screen mobiles) allows for quick steering of the plugin via commands: sort-on and sort-off.
+This could be easier than navigating to and expanding the ribbon 
+- the ribbon icon is static (![Static icon](./docs/icons/icon-mobile-initial.png)) and doesn't reflect the state of custom sorting.
+You can enable the _plugin state changes_ notifications in settings, for the mobile devices only
+
 ## Installing the plugin
 
 ### From the official Obsidian Community Plugins page
@@ -138,3 +154,18 @@ Search the plugin by its name 'CUSTOM FILE EXPLORER SORTING'
 Thanks to [Nothingislost](https://github.com/nothingislost) for the monkey-patching ideas of File Explorer
 in [obsidian-bartender](https://github.com/nothingislost/obsidian-bartender)
 
+## ...and before you go, maybe you'd like the visual separators in File Explorer?
+
+Do you want to have a nice-looking horizontal separators in File Explorer like this?
+
+![separators](./docs/img/separators-by-replete.png)
+
+If so, head on to [Instruction and more context](https://github.com/SebastianMC/obsidian-custom-sort/discussions/57#discussioncomment-4983763)
+by [@replete](https://github.com/replete)\
+Quick & easy!
+
+This feature is not dependent on the Custom Sorting plugin.
+At the same time I'm mentioning it here because it is a side effect of a discussion with [@replete](https://github.com/replete).
+We were considering a direct support of the Separators in the plugin. Eventually this boiled down to a very
+concise and smart CSS-snippet based solution, independent of the plugin. Go, see, copy to the CSS-snippets in Obsidian
+and enjoy the more grouped look

advanced-README.md

@@ -72,11 +72,11 @@ can be the root folder. Ensure the exact file name is `sortspec.md`. That file c
 > > ![sortspec.md](./docs/img/sortspec-md-dark.jpg)
 > 2. Enable the plugin in obsidian.
 >
-> 3. Click the ribbon button (![Inactive](./docs/icons/icon-inactive.png)) to tell the plugin to read the sorting
+> 3. Click the ribbon button (![Inactive](./docs/icons/icon-inactive.png) or ![Mobile](./docs/icons/icon-mobile-initial.png) on phone) to tell the plugin to read the sorting
 specification from `sortspec` note (the `sortspec.md` file which you downloaded a second ago). 
->   - The observable effect should be the change of appearance of the ribbon button to
-(![Active](./docs/icons/icon-active.png)) and reordering
-of items in root vault folder to reverse alphabetical with folders and files treated equally.
+>   - The observable effect should be reordering of items in root vault folder to reverse alphabetical with folders and files treated equally.
+And on computers and tablets be the change of appearance of the ribbon button to
+![Active](./docs/icons/icon-active.png) (on desktop and tablet only) and   
 >   - The notification balloon should confirm success: ![Success](./docs/icons/parsing-succeeded.png)
 > 4. Click the ribbon button again to suspend the plugin. The ribbon button should toggle its appearance again
 and the order of files and folders in the root folder of your vault should get back to the order selected in
@@ -570,7 +570,7 @@ reference.
 
 Click the ribbon icon to toggle the plugin between enabled and suspended states.
 
-States of the ribbon icon:
+States of the ribbon icon on large-screen devices (desktops, laptops and tablets like iPad):
 
 - ![Inactive](./docs/icons/icon-inactive.png) Plugin suspended. Custom sorting NOT applied.
 	- Click to enable and apply custom sorting.
@@ -591,6 +591,14 @@ States of the ribbon icon:
 - ![Sorting not applied](./docs/icons/icon-not-applied.png) Plugin enabled but the custom sorting was not applied.
 	- This can happen when reinstalling the plugin and in similar cases
 	- Click the ribbon icon twice to re-enable the custom sorting.
+- ![Static icon](./docs/icons/icon-mobile-initial.png) Only on large-screen mobile devices like iPad.
+    - Plugin enabled. but the custom sorting was not applied.
+
+On small-screen mobile devices (phones) the icon is static:
+
+- ![Static icon](./docs/icons/icon-mobile-initial.png) The icon acts as a button to toggle between enabled and disabled. Its appearance doesn't change
+    - Click to enable and apply custom sorting or to disable custom sorting
+    - To get notified about custom sort plugin state, enable the mobile-specific notifications in plugin settings
 
 ## Installing the plugin
 

docs/manual.md

@@ -1,10 +1,27 @@
 > Document is partial, creation in progress
-> Please refer to [README.md](../README.md) for more usage examples
+> Please refer to [README.md](../README.md) and [advanced-README.md](../advanced-README.md) for more usage examples
 > Check also [syntax-reference.md](./syntax-reference.md)
 
 ---
 Some sections added ad-hoc, to be integrated later
 
+# Hints, tips & tricks
+
+## Adding visual separators in File Explorer
+
+Do you want to have a nice-looking horizontal separators in File Explorer like this?
+
+![separators](./img/separators-by-replete.png)
+
+If so, head on to [Instruction and more context](https://github.com/SebastianMC/obsidian-custom-sort/discussions/57#discussioncomment-4983763)
+by [@replete](https://github.com/replete)
+
+This feature is not dependent on the Custom Sorting plugin.
+At the same time I'm mentioning it here because it is a side effect of a discussion with [@replete](https://github.com/replete).
+We were considering a direct support of the Separators in the plugin. Eventually this boiled down to a very
+concise and smart CSS-snippet based solution, independent of the plugin. Go, see, copy to the CSS-snippets in Obsidian
+and enjoy the more grouped look
+
 # Advanced features
 
 ## Priorities of sorting groups
@@ -70,7 +87,7 @@ For clarity: the three available prefixes `/!` and `/!!` and `/!!!` allow for fu
 
 ## Simple wildcards
 
-Currently, the below simple wildcard syntax is supported:
+Currently, the below simple wildcard syntax is supported for sorting group:
 
 ### A single digit (exactly one)
 
@@ -248,3 +265,186 @@ sorting-spec: |
   /! starred:
 ---
 ```
+
+## Options for target-folder: matching
+
+The `target-folder:` has the following variants, listed in the order of precedence:
+
+1. match by the **exact folder path** (the default)
+2. match by the **exact folder name**
+3. match by **regexp** (for experts, be careful!)
+4. match by **wildcard suffix** (aka match folders subtree)
+
+If a folder in the vault matches more than one `target-folder:` definitions,
+the above list shows the precedence, e.g. 1. has precedence over 2., 3. and 4. for example.
+In other words, match by exact folder path always wins, then goes the match by folder exact name,
+and so on.
+
+If a folder in the vault matches more than one `target-folder:` definitions of the same type,
+see the detailed description below for the behavior
+
+### By folder path (the default)
+
+If no additional modifiers follow the `target-folder:`, the remaining part of the line
+is treated as an exact folder path (leading and trailing spaces are ignored,
+infix spaces are treated literally as part of the folder path)
+
+Within the same vault duplicate definitions of same path in `target-folder:` are detected
+and error is raised in that case, indicating the duplicated path
+
+Examples of `target-folder:` with match by the exact folder path:
+
+- `target-folder: My Folder`
+  - this refers to the folder in the root of the vault and only to it
+- `target-folder: Archive/My Folder`
+  - matches the `My Folder` sub-folder in the `Archive` folder (a sub-folder of the root)
+- `target-folder: .`
+  - this refers to path of the folder where the sorting specification resides (the specification containing the line,
+    keep in mind that the sorting specification can reside in multiple locations in multiple notes) 
+- `target-folder: ./Some Subfolder`
+  - this refers to path of a sub-folder of the folder where the sorting specification resides (the specification containing the line,
+    keep in mind that the sorting specification can reside in multiple locations in multiple notes)
+
+### By folder name
+
+The modifier `name:` tells the `target-folder:` to match the folder name and not the full folder path
+
+This is an exact match of the full folder name, no partial matching
+
+Within the same vault duplicate definitions of same name in `target-folder: name:` are detected
+and error is raised in that case, indicating the duplicated folder name in sorting specification
+
+Examples of `target-folder:` with match by the exact folder name:
+
+- `target-folder: name: My Folder`
+  - matches all the folders with the name `My Folder` regardless of their location within the vault
+
+### By regexp (expert feature)
+
+> WARNING!!! This is an EXPERT FEATURE.
+> 
+> Involving and constructing the regexp-s requires at least basic knowledge about the potential pitfalls.\
+> If you introduce a heavy _regexp-backtracking_ it can **kill performance of Obsidian and even make it unresponsive**\
+> If you don't know what the _regexp-backtracking_ is, be careful when using regexp for `target-folder:`
+
+The modifier `regexp:` tells the `target-folder:` to involve the specified regular expressions in matching
+
+Additional dependent modifiers are supported for `regexp:`:
+- `for-name:`
+  - tells the matching to be done against the folder name, not the full path
+- `debug:`
+  - tells the regexp to report its match in the developer console, so that you can easily investigate
+    why the regexp matches (or why it doesn't match) as expected 
+- `/!:` `/!!:` `/!!!:`
+  - sets the priority of the regexp
+
+By default, the regexp is matched against the full path of the folder, unless the `for-name:` modifiers tells otherwise.
+
+By default, the regexp-es have no priority and are evaluated in the order of their definition.\
+If you store `sorting-spec:` configurations in notes spread all over the vault,
+consider the order of `target-folder: regexp:` to be undefined and - if needed - use
+explicit priority modifiers (`/!:` `/!!:` `/!!!:`) to impose the desired order of matching.
+  - a regexp with modifier `/!!!:` if evaluated before all other regexps, regardless of where they are configured
+    - if two or more regexps are stamped with `/!!!:`, they are matched in the order in which they were defined.\
+      Within a single YAML section of a note the order is obvious.\
+      For sorting specifications spread over many notes in the vault consider the order to be undefined.
+  - a regexp with modifier `/!!:` if evaluated after any `/!!!:` and before all other regexps
+    - the same logic as described above applies when multiple regexps have the `/!!:` stamp
+  - a regexp with modifier `/!:` indicates the lowest of explicitly defined priorities.\
+    Such a regexp is matched after all priority-stamped regexps, before the regexps not having 
+    any explicit priority stamp  
+
+The escape character is \ - the standard one in regexp world.
+
+Examples of `target-folder:` with match by regexp:
+
+- `target-folder: regexp: reading`
+  - matches any folder which contains the word `reading` in its path or name
+- `target-folder: regexp: \d?\d-\d?\d-\d\d\d\d$`
+  - matches any folder which ends with date-alike numerical expression, e.g.:
+    - `1-1-2023`
+    - `Archive/Monthly/12/05-12-2022`
+    - `Inbox/Not digested notes from 20-7-2019`
+- `target-folder: regexp: for-name: I am everywhere`
+  - matches all folders which contain the phrase `I am everywhere` in their name, e.g.:
+    - `Reports/Not processed/What the I am everywhere report from Paul means?`
+    - `Chapters/I am everywhere`
+- `target-folder: regexp: for-name: ^I am (everyw)?here$`
+  - matches all folders with name exactly `I am everywhere` or `I am here` 
+- `target-folder: regexp: for-name: debug: ^...$`
+  - matches all folders with name comprising exactly 3 character
+  - when a folder is matched, a diagnostic line is written to the console - `debug:` modifiers enables the logging
+- `target-folder: regexp: debug: ^.{13,15}$`
+  - matches all folders with path length between 13 and 15 characters
+  - diagnostic line is written to the console due to `debug:`
+- `target-folder: regexp: for-name: /!: ^[aA]`
+  - matches all folders with name starting with `a` or `A`
+  - the priority `/!:` modifier causes the matching to be done before all other regexps
+    which don't have any priority 
+- `target-folder: regexp: /!!!: debug: for-name: abc|def|ghi`
+  - matches all folders with name containing the sequence `abc` or `def` or `ghi`
+  - the modifier `/!!!:` imposes the highest priority of regexp matching
+  - `debug:` tells to report each matching folder in the console
+- `target-folder: regexp: ^[^/]+/[^/]+$`
+  - matches all folders which are at the 2nd level of vault tree, e.g.:
+    - `Inbox/Priority input`
+    - `Archive/2021`
+- `target-folder: regexp: ^[^\/]+(\/[^\/]+){2}$`
+  - matches all folders which are at the 3rd level of vault tree, e.g.:
+  - `Archive/2019/05`
+  - `Aaaa/Bbbb/Test test`
+
+### By wildcard
+
+In the default usage of `target-folder:` with the exact full folder path, if the path contains
+the `/...` or `/*` suffix its meaning is extended to:
+- match the folder and all its immediate (child) subfolders - `/...` suffix
+- match the folder and all its subfolders at any level (all descendants, the entire subtree) - `/*` suffix
+
+For example:
+
+- `target-folder: /*`
+  - matches all folders in the vault (the root folder and all its descendants)
+- `target-folder: /...`
+  - matches the root folder and its immediate children (aka immediate subfolders of the root)
+
+If the sorting specification contains duplicate wildcard-ed path in `target-folder:`
+an error is raised, indicating the duplicate path
+
+If a folder is matched by two (or more) wildcarded paths, the one with more path segments
+(the deeper one) wins. For example:
+- a folder `Book/Chapters/12/a` is matched by:
+  - (a) `target-folder: Book/*`, and
+  - (b) `target-folder: Book/Chapters/*`
+  - In this case the (b) wins, because it contains a deeper path
+
+If the depth of matches specification is the same, the `/...` takes precedence over `/*`
+- a folder `Book/Appendix/III` is matched by:
+  - (a) `target-folder: Book/Appendix/...`, and
+  - (b) `target-folder: Book/Appendix/*`
+  - In this case the (a) wins
+
+## Excluding folders from custom sorting
+
+Having the ability to wildard- and regexp-based match of `target-folder:` in some cases
+you might want to exclude folder(s) from custom sorting.
+
+This can be done by combination of the `target-folder:` (in any of its variants)
+and specification of the sort order as `sorting: standard`
+
+An example piece of YAML frontmatter could look like:
+
+```yaml
+---
+sorting-spec: |
+
+  // ... some sorting specification above
+ 
+  target-folder: Reviews/Attachments
+  target-folder: TODOs
+  sorting: standard
+ 
+  // ... some sorting specification below 
+  
+---
+```