Listings Allow ‘sort: false’ to disable sorting

fixes #3296

Author: dragonstyle

news/changelog-1.3.md

@@ -71,6 +71,7 @@
 - Improve support for `date-modified` in listings
 - Improve support for `yml` based listings by supporting usage of title and description from `yml`.
 - Allow listings in project to point directly to non-input files (such as `yml` files) to use for contents.
+- Allow `sort: false` to disable any sorting, allowing items to appear in their original / natural order. (#3296)
 
 ## Websites
 

src/project/types/website/listing/website-listing-read.ts

@@ -990,17 +990,27 @@ function computeListingSort(rawValue: unknown): ListingSort[] | undefined {
     }
   };
 
-  if (Array.isArray(rawValue)) {
-    return rawValue.map(parseValue).filter((val) =>
-      val !== undefined
-    ) as ListingSort[];
+  if (typeof (rawValue) === "boolean") {
+    if (rawValue) {
+      // Apply default sorting behavior
+      return undefined;
+    } else {
+      // Don't apply sorting
+      return [];
+    }
   } else {
-    const sort = parseValue(rawValue);
-    if (sort) {
-      return [sort];
+    // Apply sorting
+    if (Array.isArray(rawValue)) {
+      return rawValue.map(parseValue).filter((val) =>
+        val !== undefined
+      ) as ListingSort[];
+    } else {
+      const sort = parseValue(rawValue);
+      if (sort) {
+        return [sort];
+      }
     }
   }
-  return undefined;
 }
 
 function defaultFields(type: ListingType, itemFields: string[]) {

src/resources/editor/tools/vs-code.mjs

@@ -9941,10 +9941,15 @@ var require_yaml_intelligence_resources = __commonJS({
                 description: "The files or path globs of Quarto documents or YAML files that should be included in the listing."
               },
               sort: {
-                maybeArrayOf: "string",
+                anyOf: [
+                  "boolean",
+                  {
+                    maybeArrayOf: "string"
+                  }
+                ],
                 description: {
                   short: "Sort items in the listing by these fields.",
-                  long: "Sort items in the listing by these fields. The sort key is made up of a \nfield name followed by a direction `asc` or `desc`.\n\nFor example:\n`date asc`\n"
+                  long: "Sort items in the listing by these fields. The sort key is made up of a \nfield name followed by a direction `asc` or `desc`.\n\nFor example:\n`date asc`\n\nUse `sort:false` to use the unsorted original order of items.\n"
                 }
               },
               "max-items": {
@@ -19666,6 +19671,7 @@ var require_yaml_intelligence_resources = __commonJS({
         "The path to the locally referenced notebook.",
         "The title of the notebook when viewed.",
         "The url to use when viewing this notebook.",
+        "The style of document to render. Setting this to\n<code>notebook</code> will create additional notebook style\naffordances.",
         "Automatically generate the contents of a page from a list of Quarto\ndocuments or other custom data.",
         "Mermaid diagram options",
         "The mermaid built-in theme to use.",
@@ -20665,8 +20671,7 @@ var require_yaml_intelligence_resources = __commonJS({
           long: "Title of the volume of the item or container holding the item.\nAlso use for titles of periodical special issues, special sections,\nand the like."
         },
         "Disambiguating year suffix in author-date styles (e.g.&nbsp;\u201Ca\u201D in \u201CDoe,\n1999a\u201D).",
-        "internal-schema-hack",
-        "The style of document to render. Setting this to\n<code>notebook</code> will create additional notebook style\naffordances."
+        "internal-schema-hack"
       ],
       "schema/external-schemas.yml": [
         {
@@ -20880,12 +20885,12 @@ var require_yaml_intelligence_resources = __commonJS({
         mermaid: "%%"
       },
       "handlers/mermaid/schema.yml": {
-        _internalId: 146672,
+        _internalId: 146876,
         type: "object",
         description: "be an object",
         properties: {
           "mermaid-format": {
-            _internalId: 146664,
+            _internalId: 146868,
             type: "enum",
             enum: [
               "png",
@@ -20901,7 +20906,7 @@ var require_yaml_intelligence_resources = __commonJS({
             exhaustiveCompletions: true
           },
           theme: {
-            _internalId: 146671,
+            _internalId: 146875,
             type: "anyOf",
             anyOf: [
               {

src/resources/editor/tools/yaml/web-worker.js

@@ -2917,10 +2917,15 @@
             "description": "The files or path globs of Quarto documents or YAML files that should be included in the listing."
           },
           "sort": {
-            "maybeArrayOf": "string",
+            "anyOf": [
+              "boolean",
+              {
+                "maybeArrayOf": "string"
+              }
+            ],
             "description": {
               "short": "Sort items in the listing by these fields.",
-              "long": "Sort items in the listing by these fields. The sort key is made up of a \nfield name followed by a direction `asc` or `desc`.\n\nFor example:\n`date asc`\n"
+              "long": "Sort items in the listing by these fields. The sort key is made up of a \nfield name followed by a direction `asc` or `desc`.\n\nFor example:\n`date asc`\n\nUse `sort:false` to use the unsorted original order of items.\n"
             }
           },
           "max-items": {
@@ -12642,6 +12647,7 @@
     "The path to the locally referenced notebook.",
     "The title of the notebook when viewed.",
     "The url to use when viewing this notebook.",
+    "The style of document to render. Setting this to\n<code>notebook</code> will create additional notebook style\naffordances.",
     "Automatically generate the contents of a page from a list of Quarto\ndocuments or other custom data.",
     "Mermaid diagram options",
     "The mermaid built-in theme to use.",
@@ -13641,8 +13647,7 @@
       "long": "Title of the volume of the item or container holding the item.\nAlso use for titles of periodical special issues, special sections,\nand the like."
     },
     "Disambiguating year suffix in author-date styles (e.g.&nbsp;“a” in “Doe,\n1999a”).",
-    "internal-schema-hack",
-    "The style of document to render. Setting this to\n<code>notebook</code> will create additional notebook style\naffordances."
+    "internal-schema-hack"
   ],
   "schema/external-schemas.yml": [
     {
@@ -13856,12 +13861,12 @@
     "mermaid": "%%"
   },
   "handlers/mermaid/schema.yml": {
-    "_internalId": 146672,
+    "_internalId": 146876,
     "type": "object",
     "description": "be an object",
     "properties": {
       "mermaid-format": {
-        "_internalId": 146664,
+        "_internalId": 146868,
         "type": "enum",
         "enum": [
           "png",
@@ -13877,7 +13882,7 @@
         "exhaustiveCompletions": true
       },
       "theme": {
-        "_internalId": 146671,
+        "_internalId": 146875,
         "type": "anyOf",
         "anyOf": [
           {

src/resources/editor/tools/yaml/yaml-intelligence-resources.json

@@ -1248,7 +1248,9 @@
             - ref: website-listing-contents-object
         description: "The files or path globs of Quarto documents or YAML files that should be included in the listing."
       sort:
-        maybeArrayOf: string
+        anyOf:
+          - boolean
+          - maybeArrayOf: string
         description:
           short: "Sort items in the listing by these fields."
           long: |
@@ -1257,6 +1259,8 @@
 
             For example:
             `date asc`
+
+            Use `sort:false` to use the unsorted original order of items.
       max-items:
         number:
           description: The maximum number of items to include in this listing.

src/resources/schema/definitions.yml

@@ -808,13 +808,17 @@ place the contents into a `div` with this id. If no such `div` is defined on the
 page, a `div` with this id will be created and appended to the end of the page.
 
 In no `id` is provided for a listing, Quarto will synthesize one when rendering the page. */;
-  sort?: MaybeArrayOf<
-    string
-  > /* Sort items in the listing by these fields. The sort key is made up of a
+  sort?:
+    | boolean
+    | MaybeArrayOf<
+      string
+    > /* Sort items in the listing by these fields. The sort key is made up of a
 field name followed by a direction `asc` or `desc`.
 
 For example:
-`date asc` */;
+`date asc`
+
+Use `sort:false` to use the unsorted original order of items. */;
   type?:
     | "default"
     | "table"