fix(ties): clarify .ties() messages for the last steps of the sorting…

… process

make it clear which teams are separated at what step during 'additional', 'shootout', 'flag' and 'final' just like it is for the standard overall / h2h criteria; add none option for span.sorting.h2h

README.md

@@ -120,6 +120,8 @@ But here is the catch: according to official European Championship regulations,
 
 **Whether the full list of criteria is expected to run out before resetting the head-to-head procedure is decided by the `sorting.h2h.span` key,** which can take the string value `"all"` to signify the style that we have just seen (the one where we must wait until all criteria are applied before re-evaluating any head-to-head sub-tables) or the string value `"single"` to mean the opposite, i.e. the case when head-to-head restarts from the beginning every single time some teams separate from others (basically the same line of reasoning that, in our fictional example, had made Belgium the winner of the group).
 
+Notice, however, how some competitions do not have this provision at all: the FIFA World Cup is one prime example, where head-to-head criteria apply after the overall one but there is no requirement to restart them at any point should they only help to separate some teams, but not others. This behavior can be replicated via the third and last accepted value, `"none"`.
+
 ### Optional sorting keys
 
 In addition to the subkeys seen above, that are required whenever the `sorting` key is stated explicitly as an object, there are some more that may or may not be provided when initializing the object.
@@ -243,7 +245,7 @@ with `.ties()` now saying
 
 ### Displaying a description of how ties were broken via `.ties()`
 
-- There is currently one point of improvement that I would like to focus on next: the `additional`, `shootout`, `flag` and `final` steps all count as one step, meaning that if more than two teams are involved and some of them are separated by one of these steps while the others are separated by another, only one message will be displayed. ***The teams will be sorted correctly in any case,*** but it is the text description that is insufficient in this scenario.
+~~- There is currently one point of improvement that I would like to focus on next: the `additional`, `shootout`, `flag` and `final` steps all count as one step, meaning that if more than two teams are involved and some of them are separated by one of these steps while the others are separated by another, only one message will be displayed. ***The teams will be sorted correctly in any case,*** but it is the text description that is insufficient in this scenario.~~ **(solved as of v.1.0.2)**
 
 ## Helping with the package
 

docs/index.md

@@ -12,14 +12,16 @@ where the input object must have the following compulsory key.
 |                        |                                                                |
 |------------------------|----------------------------------------------------------------|
 | **Description**        | The list of the teams that are taking part in the league.      |
-| **Expected value**     | An array of unique identifiers of any type.                    |
+| **Expected value**     | An array of unique identifiers of any type, or an array of objects with keys `"team"` and `"flags"` where the values of the first keys are unique identifiers of any type, while the values of the second key are arrays of integers all of which have the same length that is equal to the length of `sorting.flags`. |
 | **Compulsory**         | **Yes.**                                                       |
 
 It is best if `teams` is an array of strings comprising of the (unique) names of the teams involved, but any other type of unique identifier works; repeated entries **will throw an error** of type
 
 ```
 Team identifiers must be unique.
 ```
+Notice that explicitly submitting [`sorting.flags`](#optional-subkey-flags) as a nonempty array will require `teams` to be an array of objects as opposed to an array of strings; this includes circumstances in which `sorting` is decided via a keyword (e.g. `"FIFA World Cup"`) that is defined in the code to have a nonempty `sorting.flags` array (see [`sorting`](#optional-key-sorting) down below for a list of the default kewords, as well as the flags associated with them).
+
 Additionally, the starting object may have any of the following optional keys.
 
 ## Optional key `format`
@@ -83,7 +85,7 @@ messages: [
 | **Compulsory**         | No.                                                                |
 | **Default**            | *See below*                                                        |
 
-When wanting to initialize the `sorting` key to a preset corresponding to a real-world tournament, then the above accepts either the string `"FIFA World Cup"`, the string `"UEFA Euro"`, the string `"pre-2021 UEFA Champions League"` or the string `"2021-2024 UEFA Champions League"`; leaving out this key during object creation will default it to the object
+When wanting to initialize the `sorting` key to a preset corresponding to a real-world tournament, then the above accepts either the string `"FIFA World Cup"` (accepts a single [flag](#optional-subkey-flags): fair play points), the string `"UEFA Euro"` (accepts two flags: disciplinary points and European Qualifiers overall ranking), the string `"pre-2021 UEFA Champions League"` or the string `"2021-2024 UEFA Champions League"` (each accepting two flags: disciplinary points and UEFA club coefficient); leaving out this key during object creation will default it to the object
 
 ```js
 {
@@ -115,7 +117,7 @@ The criteria correspond respectively to the goal difference, the number of goals
 |                        |                                                                    |
 |------------------------|--------------------------------------------------------------------|
 | **Description**        | Handles the head-to-head section of the sorting procedure.         |
-| **Expected value**     | An object with keys `when` (accepting only either the string `"before"` or the string `"after"`) and `span` (accepting only either the string `"all"` or the string `"single"`). |
+| **Expected value**     | An object with keys `when` (accepting only either the string `"before"` or the string `"after"`) and `span` (accepting only either the string `"all"` the string `"single"`, or the string `"none"`). |
 | **Compulsory**         | **Yes** if `sorting` is specified explicitly as an object.         |
 
 See [**Head-to-head v. overall**](https://github.com/SuzuSuzu-HaruHaru/league-standings?tab=readme-ov-file#head-to-head-v-overall) and [**Head-to-head reapplication**](https://github.com/SuzuSuzu-HaruHaru/league-standings?tab=readme-ov-file#head-to-head-reapplication) on Github for a pratical explanation of the real-world effects that these parameters have.

docs/methods.md

@@ -68,7 +68,7 @@ See [**`shootout`**](https://github.com/SuzuSuzu-HaruHaru/league-standings?tab=r
 |------------------------|--------------------------------------------------------------------|
 | **Description**        | Retrieves the standings, as computed from the matches.             |
 | **Expected input**     | Either none or the string `"all"`.                                 |
-| **Expected output**    | An array of objects with keys `id`, `points`, `for`, `against`, `diff`, `won`, `drawn`, `lost`, `played` (additionally `away_for`, `away_won` if the input is set to `"all"`). |
+| **Expected output**    | An array of objects with keys `id`, `points`, `for`, `against`, `diff`, `won`, `drawn`, `lost`, `played` (additionally `away_for`, `away_won` and any other user-submitted flag if the input is set to `"all"`). |
 
 The array in question will already be ordered as per the final standings of the league; for example, calling `table.standings()[2].for` on an `table` object of type `LeagueTable` will retrieve the number of goals scored by the team that placed third in the league (as per usual, Javascript arrays are zero-indexed so the third element in the array is accessible via the index two).
 

release.config.cjs

@@ -1,3 +1,21 @@
 module.exports = {
-    branches: ["main"]
+    branches: ["main"],
+    plugins: [
+        "@semantic-release/commit-analyzer",
+        "@semantic-release/release-notes-generator",
+        "@semantic-release/changelog",
+        "@semantic-release/npm",
+        [
+            "@semantic-release/github",
+            {
+                "assets":
+                    [
+                        {
+                            "path": "dist",
+                            "label": "league-standings-${nextRelease.gitTag}"
+                        }
+                    ]
+            }
+        ]
+    ]
 }