feat: Implement basic general folder support (#2051)

- Related: #1748
2025-05-21 19:59:21 -07:00
parent 2eb0d9e35e
commit c6a4c8aea2
350 changed files with 12837 additions and 4509 deletions
@@ -0,0 +1,91 @@
+# `folders`
+
+[](./common/experimental-warning.md ':include')
+
+The `folders` stanza is used for configuring folders from which media/subfolders may be viewed.
+
+?> To configure the behavior of the gallery in which folders are displayed, see the [`media_gallery` configuration](./media-gallery.md).
+
+```yaml
+folders:
+  # [...]
+```
+
+| Option  | Default | Description                                                                                                                                    |
+| ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`    |         | An optional folder `id` which can be used by the [`folder` action](./actions/custom/README.md?id=folder) to show a particular folder contents. |
+| `ha`    |         | Options for `ha` folder types. See below.                                                                                                      |
+| `icon`  |         | An optional folder icon.                                                                                                                       |
+| `title` |         | An optional folder title.                                                                                                                      |
+| `type`  | `ha`    | The type of folder, `ha` for Home Assistant media folders (currently the only supported type of folder).                                       |
+
+## `ha`
+
+Used to specify a Home Assistant media folder.
+
+```yaml
+folders:
+  - type: ha
+    ha:
+      # [...]
+```
+
+| Option | Default                     | Description                                                                                                                                                                             |
+| ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`  |                             | An optional Home Assistant `Media` browser URL to use as the query base. If `path` is also specified, those matchers are applied against folders "below" the folder specified in `url`. |
+| `path` | [`{ id: media-source:// }`] | An optional array of matchers to dynamically compare against the Home Assistant media folder hierarchy. See below.                                                                      |
+
+?> `url` is never fetched, nor sent over the network. It is only processed
+locally in your browser. The host part of the URL can optionally be removed.
+
+### `path`
+
+An array of matchers to navigate "down" a folder hierarchy. If `url` is also
+specified, matchers are applied starting at that folder, otherwise they are
+applied at the media source root (i.e. `media-source://`).
+
+```yaml
+folders:
+  - type: ha
+    ha:
+      path:
+        # [...]
+```
+
+| Option     | Default | Description                                            |
+| ---------- | ------- | ------------------------------------------------------ |
+| `id`       |         | An optional media source `id` to match against.        |
+| `title`    |         | An optional title name to match against.               |
+| `title_re` |         | An optional title regular expression to match against. |
+
+?> Specifying multiple `path` matchers (other than `id`) requires a query at
+each level of the folder hierarchy and is slower than directly specifying the
+media source `id` (if known) or the `url` of the folder.
+
+#### Examples
+
+See [Folder Examples](../examples.md?id=folders).
+
+#### Understanding Media Source IDs and "parent folders"
+
+Home Assistant Media Source IDs are typically long integration-specific non-user
+friendly strings that refer to a media item, or folder of media items. Media
+source "folders" do not have an intrinsic parent as with filesystem folders,
+rather a trail is built as the user navigates "downwards" -- but anything could
+theoretically be the parent of anything.
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+folders:
+  - type: ha
+    ha:
+      url: https://my-ha-instance.local/media-browser/browser/app%2Cmedia-source%3A%2F%2Ffrigate
+      path:
+        - id: 'media-source://'
+        - title: 'Frigate'
+        - title_re: 'Clips.*'
+        - title_re: 'Person.*'
+```