diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..78da212 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,32 @@ +# .github/workflows/deploy.yml +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout Code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' # Use a specific version like '3.10', '3.11', or '3.12' + + - name: Install MkDocs, Material for MkDocs, and PyMdown Extensions + run: pip install mkdocs mkdocs-material pymdown-extensions + + - name: Deploy Docs to GitHub Pages + run: mkdocs gh-deploy --force --clean diff --git a/README.md b/README.md index 31503bd..3f96d59 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,16 @@ [![HACS][hacsBadge]][hacsUrl] [![Codacy][codacyBadge]][codacyUrl] -![Preview GIF](./docs/preview.gif) +![Preview GIF](docs/images/preview.gif)
More images... -![Automatic](./docs/auto.png) +![Automatic](docs/images/auto.png) -![Views](./docs/views.png) +![Views](docs/images/views.png) -![customizable](./docs/customizable.png) +![customizable](docs/images/customizable.png)
## What is the Mushroom Dashboard Strategy? diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..86bacf0 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,167 @@ +# 🤝 Contributing to Mushroom Strategy + +We love contributions from the community! Whether you're reporting a bug, suggesting a new feature, or submitting code +changes, your help makes the Mushroom Strategy better for everyone. + +Please take a moment to review this guide before making a contribution. + +## 📜 Code of Conduct + +To ensure a welcoming and inclusive environment, all contributors are expected to adhere to +our [Code of Conduct](https://github.com/DigiLive/mushroom-strategy/blob/main/CODE_OF_CONDUCT.md). Please read it +carefully. + +--- + +## 🐞 Reporting Bugs + +Found a bug? That's not ideal, but your report helps us squash it! + +1. **Check existing issues:** Before opening a new issue, please search + our GitHub [Issues](https://github.com/DigiLive/mushroom-strategy/issues) + or [Discussions](https://github.com/DigiLive/mushroom-strategy/discussions) to see if the bug has already been + reported. +2. **Open a new issue:** If it's a new bug, please open + a [new issue](https://github.com/DigiLive/mushroom-strategy/issues/new?template=bug_report.yml). +3. **Provide details:** In your report, please include: + +* A clear and concise description of the bug. +* Steps to reproduce the behavior. +* Expected behavior. +* Screenshots or animated GIFs (if applicable). +* Your Home Assistant version and Mushroom Strategy version. + +--- + +## ✨ Suggesting Features + +Have a great idea for a new feature or enhancement? We'd love to hear it! + +1. **Check existing suggestions:** Search our GitHub [Issues](https://github.com/DigiLive/mushroom-strategy/issues) + or [Discussions](https://github.com/DigiLive/mushroom-strategy/discussions) to see if the feature has already been + requested. +2. **Open a new issue:** If it's a new idea, open + a [new issue](https://github.com/DigiLive/mushroom-strategy/issues/new?template=feature_request.yml). +3. **Describe your idea:** Clearly explain the feature, why you think it's useful, and any potential use cases. + +--- + +## 💻 Contributing Code + +Want to get your hands dirty with the code? Awesome! We appreciate all code contributions. + +1. **Fork the Repository:** Start by forking + the [DigiLive/mushroom-strategy](https://github.com/DigiLive/mushroom-strategy) repository to your own GitHub + account. +2. **Clone Your Fork:** Clone your forked repository to your local machine. + + ```bash + git clone https://github.com/YOUR_USERNAME/mushroom-strategy.git + cd mushroom-strategy + ``` + +3. **Create a New Branch:** Create a new branch for your feature or bug fix. Use a descriptive name (e.g., + `feature/my-awesome-feature`, `bugfix/fix-admonition-rendering`). + + ```bash + git checkout -b feature/my-new-feature + ``` + +4. **Set up Development Environment:** + + * Ensure you have Node.js and npm installed. + * Install project dependencies: `npm install` + * You can build the strategy with `npm run build` (for production) or `npm run build-dev` (for development/testing). + * Copy the built files to your Home Assistant's `www/community/mushroom-strategy` folder for testing. + +5. **Make Your Changes:** Implement your bug fix or new feature. +6. **Test Your Changes:** Thoroughly test your changes to ensure they work as expected and don't introduce new issues. +7. **Commit Your Changes:** + + * We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for clear commit history. + * Example: `feat: add new card option` or `fix: correct card rendering issue` + + ```bash + git add . + git commit -m "feat: add super cool new feature" + ``` + +8. **Push to Your Fork:** + + ```bash + git push origin feature/my-new-feature + ``` + +9. **Create a Pull Request (PR):** + + * Go to your forked repository on GitHub. + * You should see a prompt to create a pull request from your new branch to the `main` branch of + `DigiLive/mushroom-strategy`. + * Provide a clear title and description for your PR, referencing any related issues. + * Be prepared to discuss your changes and address any feedback during the review process. + +--- + +## 📄 Improving Documentation + +Good documentation is vital! If you find typos, unclear sections, or want to add more examples, please open a pull +request. The documentation is located in the `docs/` folder of this repository. + +--- + +## 🌐 Translations + +Help us make Mushroom Strategy accessible to more users around the world by contributing and improving translations! + +Language tags have to follow [BCP 47](https://tools.ietf.org/html/bcp47). +A list of most language tags can be found +here: [IANA subtag registry](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). +Examples: fr, fr-CA, zh-Hans. + +1. **Check for Existing Translations:** See if your language is already being worked on or exists. +2. **Locate Translation Files:** Language files are found within the `src/translations` directory. + Each language has its own `locale.json` file (e.g., `en.json`, `nl.json`, `pt-BR.json`). +3. **Create or Update:** + + * **To create a new language:** Copy an existing `.json` file (e.g., `en.json`), rename it to your language + code (e.g., `de.json` for German), and translate the property values. + * **To update an existing language:** Open the `.json` file for your language and update any missing or + outdated translations. + +4. **Submit a Pull Request:** Once your translations are complete, submit a pull request with your changes. Clearly + state which language you are contributing to or updating. + +!!! info +**Integrating a new Translation:** + + * For your new language file to be picked up, it needs to be imported and registered at file + `src/utilities/localize.ts`. + * You will need to add an `import` statement for your new `.json` file at the top, following the existing pattern. + * Then, you'll need to add it to the `languages` map, associating the language code with the imported module. + + **Special Handling for `language-country` Locales:** + If you are adding a country-specific locale (e.g., `es-ES` for Spanish (Spain) or `en-GB` for English + (United Kingdom)), you should create a file like `en-GB.json` in the `translations` folder. In + `src/utilities/localize.ts`, you'll import it similarly and add it to the `languages` map using the full locale + code. + Please ensure you follow existing patterns for `language-country` codes, which typically use a hyphen (`-`) + a + UPPER-cased country code in the file name and an underscore (`_`) + a lower-cased country code in the import key. + + !!! example + ```typescript + import * as en from '../translations/en.json'; + import * as pt_br from '../translations/pt-BR.json'; + + /** Registry of currently supported languages */ + const languages: Record = { + en, + 'pt-BR': pt_br, + }; + ``` + +--- + +## 🙏 Get Support + +If you have questions about contributing or need help with your setup, please open +a [discussion](https://github.com/DigiLive/mushroom-strategy/discussions) on our GitHub repository. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..ba4af19 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,56 @@ +??? question "How do I add a device or entity to an area?" + + You can add devices to an area by going to `Settings` found at the bottom of the sidebar. + + 1. Select `Devices & services`. + 2. Select `Devices` or `Entities`at the top. + 3. Choose the device or entity you wish to add to an area. + 4. Select :material-pencil: or :material-cog: in the top right corner. + 5. Choose an area in the area field. + + !!! warning + If you created an entity manually (in your `configuration.yaml`), you may need to create a `unique_id` before + you can set an area to it. + See Home Assistant's [documentation][uniqueIdUrl] for more info about unique ids. + +??? question "How do I hide entities from the Strategy?" + + When creating this dashboard for the first time, you might be overwhelmed by the number of entities. + To reduce the number of entities shown, you can hide these entities by following the steps below: + + 1. Click and hold the entity. + 2. Click :material-cog: in the top right corner of the popup. + 3. Set `Visible` to `off`. + + + !!! note + If you don't want to hide the entity from all dashboards, you can use [Card Options][cardOptionsUrl] to hide + specific entities and devices. + +??? question "How do I get the id of entities, devices and areas?" + + * Entity Id + 1. Select `Settings` at the bottom of the sidebar. + 2. Select `Devices & services`. + 3. Select `Entities` at the top. + 4. Choose the entity you want to get the id of. + 5. Click :material-cog: in the top right corner of the popup. + + * Device Id + 1. Select `Settings` at the bottom of the sidebar. + 2. Select `Devices & services`. + 3. Select `Devices` at the top. + 4. Select the device you want to get the id of. + 5. The device id is shown as the **last** part of the url in the address bar. + E.g.: `https://.../config/devices/device/h55b6k54j76g56` + + * Area Id + 1. Select `Settings` at the bottom of the sidebar. + 2. Select `Areas`. + 3. Select :material-pencil: of the area you want to get the id of. + + + +[uniqueIdUrl]: https://www.home-assistant.io/faq/unique_id + +[cardOptionsUrl]: options/card-options.md diff --git a/docs/full-example.md b/docs/full-example.md new file mode 100644 index 0000000..394a99d --- /dev/null +++ b/docs/full-example.md @@ -0,0 +1,119 @@ +Here is a full example using all the options provided with the strategy. + +```yaml +strategy: + type: custom:mushroom-strategy + options: + views: + light: + order: 1 + title: illumination + switches: + hidden: true + icon: mdi:toggle-switch + home_view: + hidden: + - areasTitle + - greeting + stack_count: + areas: [2, 1] + persons: 3 + domains: + _: + hide_config_entities: true + stack_count: 1 + light: + order: 1 + stack_count: 2 + title: "My cool lights" + chips: + weather_entity: weather.forecast_home + climate_count: false + cover_count: false + extra_chips: + - type: conditional + conditions: + - entity: lock.front_door + state: unlocked + chip: + type: entity + entity: lock.front_door + icon_color: red + content_info: none + icon: '' + use_entity_picture: false + tap_action: + action: toggle + - type: conditional + conditions: + - entity: cover.garage_door + state_not: closed + chip: + type: entity + entity: cover.garage_door + icon_color: red + content_info: none + tap_action: + action: toggle + areas: + _: + type: default + family_room_id: + name: Family Room + icon: mdi:television + icon_color: green + extra_cards: + - type: custom:mushroom-chips-card + chips: + - type: entity + entity: sensor.family_room_temperature + icon: mdi:thermometer + icon_color: pink + alignment: center + kitchen_id: + name: Kitchen + icon: mdi:silverware-fork-knife + icon_color: red + order: 1 + master_bedroom_id: + name: Master Bedroom + icon: mdi:bed-king + icon_color: blue + kids_bedroom_id: + name: Kids Bedroom + icon: mdi:flower-tulip + icon_color: green + card_options: + fan.master_bedroom_fan: + type: custom:mushroom-fan-card + remote.harmony_hub_wk: + hidden: true + quick_access_cards: + - type: custom:mushroom-cover-card + entity: cover.garage_door + show_buttons_control: true + - type: horizontal-stack + cards: + - type: custom:mushroom-lock-card + entity: lock.front_door + - type: custom:mushroom-entity-card + entity: sensor.front_door_lock_battery + name: Battery + extra_cards: + - type: custom:xiaomi-vacuum-map-card + map_source: + camera: camera.xiaomi_cloud_map_extractor + calibration_source: + camera: true + entity: vacuum.robot_vacuum + vacuum_platform: default + extra_views: + - theme: Backend-selected + title: Cool view + path: cool-view + icon: mdi:emoticon-cool + badges: [] + cards: + - type: markdown + content: I am cool +``` diff --git a/docs/getting-started/basic-setup.md b/docs/getting-started/basic-setup.md new file mode 100644 index 0000000..180371f --- /dev/null +++ b/docs/getting-started/basic-setup.md @@ -0,0 +1,30 @@ +# Basic Setup + +To apply the Mushroom Strategy to a dashboard: + +1. In the UI of the dashboard, select :material-pencil: in the top right corner. +2. If not taken to a Raw Configuration editor, click the three-dot menu in the top right corner. +3. Select `Raw configuration editor`. +4. Empty the configuration and add the following lines: + + ```yaml + strategy: + type: custom:mushroom-strategy + views: [] + ``` + +> [!NOTE] +> You may see the following error: + +``` + Error loading the dashboard strategy: + Error: Timeout waiting for strategy + element ||-strategy-mushroom-strategy to + be registered +``` + +This is mainly because of cache issues or HACS didn't create a reference. +Try clearing the cache of your client and/or re-downloading the strategy from HACS. + +If it still doesn't work, please consult guide +[How to solve: Error loading the dashboard strategy](https://github.com/DigiLive/mushroom-strategy/discussions/90). diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..e793602 --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,71 @@ +# Installation + +## Prerequisites + +Mushroom dashboard strategy and dependencies are available in [HACS][hacsUrl] (Home Assistant Community Store). +Install HACS if you don't have it already. +For assistance, you can follow the [installation guide][hacsInstallationGuideUrl]. + +Once you have HACS installed, you can install custom integration and plug-ins. +This guide offers you badges to open your Home Assistant on the correct page. +If the badges don't work, try installing from HACS manually: + +1. Open HACS in Home Assistant (Usually in the menu on the left side). +2. At the top, search for the component you want to install. +3. Select the `three-dot` menu on the right side of the component and select `Download`. +4. Choose the desired version and select `Download` again. + +You need to install the following HACS integrations before you can use this strategy. +Click the badges below and follow the installation instructions. +They will open the HACS repository at your Home Assistant instance directly. + +[![Open in HACS at your Home Assistant instance.][hacsBadge]][hacsMushroomUrl] to install [Mushroom][mushroomUrl]. +[![Open in HACS at your Home Assistant instance.][hacsBadge]][hacsMiniGraphUrl] to +install [Mini graph card][miniGraphUrl]. + +## Dashboard Installation + +If you meet all the prerequisites, click the badge below to install the strategy. + +[![Open in HACS at your Home Assistant instance.][hacsBadge]][hacsStrategyUrl] + +## Local Installation + +Please install the strategy with HACS as described above. +If you require testing a custom build for debug purposes, follow these steps: + +1. Build the strategy with `npm build` or `npm build-dev`. +2. Copy the build file(s) to folder `/www/community/mushroom-strategy`. +3. If file `mushroom-strategy.js.gz` exists in that folder, rename or delete it. + +!!! note +Refresh the cache of the client you use to access Home Assistant. + +## Updating + +By default, Home Assistant will notify you when an update of the strategy is available. +You can update the strategy by going to `Settings` found at the bottom of the sidebar. + +!!! tip +You can enable notifications of pre-releases. + + * Go to `Settings` > `Devices & services` > `Entities`. + * Search for `Mushroom Dashboard` and switch on the `Pre-release` entity. + + + +[hacsUrl]: https://hacs.xyz + +[hacsInstallationGuideUrl]: https://hacs.xyz/docs/setup/prerequisites + +[hacsBadge]: https://img.shields.io/badge/Open%20my%20HACS%20Repository-%2318BCF2?logo=homeassistant&logoColor=%23FFFFFF&labelColor=%2318BCF2 + +[mushroomUrl]: https://github.com/piitaya/lovelace-mushroom + +[hacsMushroomUrl]: https://my.home-assistant.io/redirect/hacs_repository/?owner=piitaya&repository=lovelace-mushroom&category=frontend + +[miniGraphUrl]: https://github.com/kalkih/mini-graph-card + +[hacsMiniGraphUrl]: https://my.home-assistant.io/redirect/hacs_repository/?owner=kalkih&repository=mini-graph-card&category=frontend + +[hacsStrategyUrl]: https://my.home-assistant.io/redirect/hacs_repository/?owner=DigiLive&repository=mushroom-strategy&category=frontend diff --git a/docs/Hidden.png b/docs/images/Hidden.png similarity index 100% rename from docs/Hidden.png rename to docs/images/Hidden.png diff --git a/docs/additonal_cards.png b/docs/images/additonal_cards.png similarity index 100% rename from docs/additonal_cards.png rename to docs/images/additonal_cards.png diff --git a/docs/auto.png b/docs/images/auto.png similarity index 100% rename from docs/auto.png rename to docs/images/auto.png diff --git a/docs/chips.png b/docs/images/chips.png similarity index 100% rename from docs/chips.png rename to docs/images/chips.png diff --git a/docs/customizable.png b/docs/images/customizable.png similarity index 100% rename from docs/customizable.png rename to docs/images/customizable.png diff --git a/docs/light_view.png b/docs/images/light_view.png similarity index 100% rename from docs/light_view.png rename to docs/images/light_view.png diff --git a/docs/preview.gif b/docs/images/preview.gif similarity index 100% rename from docs/preview.gif rename to docs/images/preview.gif diff --git a/docs/views.png b/docs/images/views.png similarity index 100% rename from docs/views.png rename to docs/images/views.png diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..cafb9e1 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,49 @@ +# Welcome to the Mushroom Strategy Documentation 🍄 + +The **Mushroom Strategy** is an innovative solution for Home Assistant that empowers you to effortlessly create +beautiful, intuitive, and automatically generated dashboards using the +popular [Mushroom cards](https://github.com/piitaya/lovelace-mushroom). + +Say goodbye to tedious manual YAML configuration for every card! With the Mushroom Strategy, you can define your +entities, areas, and devices and let the strategy intelligently build a dynamic and responsive dashboard tailored to +your smart home. + +## ✨ Key Features & Benefits + +* **Automated Dashboard Generation:** Create a comprehensive dashboard with minimal YAML, saving you countless hours. +* **Leverages Mushroom Cards:** Enjoy the stunning aesthetics and rich functionality of Mushroom cards, renowned for + their clean design and user-friendliness. +* **Entity, Device, and Area-Aware:** Automatically organizes your Home Assistant components into logical, navigable + views. +* **Built-in Views:** Access pre-built views for specific domains like lights, fans, climate, and more, ensuring quick + control. +* **Highly Customizable:** While automated, the strategy provides ample options to fine-tune the appearance and behavior + to match your preferences. +* **Responsive Design:** Your generated dashboard will look great and function seamlessly across all devices – mobile, + tablet, and desktop. + +## 🚀 Get Started in Minutes + +Ready to transform your Home Assistant interface? Follow these guides to get your Mushroom Strategy dashboard up and +running: + +* [**Installation Guide**](getting-started/installation.md): Step-by-step instructions to install the strategy via HACS + or manually. +* [**Basic Setup**](getting-started/basic-setup.md): Learn the fundamental configuration to generate your first + dashboard. +* [**Configuration Options**](options/index.md): Dive deeper into all available settings to customize your dashboard to + perfection. +* [**Usage Example**](full-example.md): An example to show most of the configuration options. + +--- + +We're excited for you to experience the simplicity and power of the Mushroom Strategy. If you have questions, encounter +issues, or want to contribute, please visit our [GitHub repository](https://github.com/DigiLive/mushroom-strategy) and +engage with the community! + +**Enjoying the Mushroom Strategy?** Consider giving our project a +⭐ [star on GitHub](https://github.com/DigiLive/mushroom-strategy) and exploring ways +to ❤️ [sponsor the project](https://github.com/sponsors/DigiLive) to support its continued development! Your support +helps us grow and improve. + +// TODO: add contribution and pre-release diff --git a/docs/options/area-options.md b/docs/options/area-options.md new file mode 100644 index 0000000..d41420f --- /dev/null +++ b/docs/options/area-options.md @@ -0,0 +1,99 @@ +# Area Options + +The `areas` group enables you to specify the configuration of specific areas. +Each configuration is identified by an area id and can have the following options: + +| Name | Type | Default | Description | +|:--------------|:---------------|:----------------|:---------------------------------------------------------------------------| +| `extra_cards` | array of cards | `[]` | A list of cards to show on the top of the area sub-view. | +| `hidden` | boolean | `false` | Set to `true` to exclude the area from the dashboard and views. | +| `name` | string | `Area specific` | The name of the area. | +| `order` | number | `unset` | Ordering position of the area in the list of available areas. | +| `type` | string | `default` | Set to a type of area card. (Currently supported: `default` & `HaAreaCard` | + +Also, all options from the Template mushroom card and/or Home Assistant Area card are supported. +Please follow the links below to see the additional options per card type. + +* [Mushroom Template Card][templateDocUrl]. +* [Home Assistant Area Card][areaDocUrl]. + +## Extra Cards + +The `extra_cards` group enables you to specify the configuration of additional cards an Area view. +These cards will be shown last in the view. + +See Home View Options → [Extra Cards](#extra-cards) for more information. + +## Example + +```yaml +strategy: + type: custom:mushroom-strategy + options: + areas: + family_room_id: + name: Family Room + icon: mdi:television + icon_color: green + order: 1 + extra_cards: + - type: custom:mushroom-chips-card + chips: + - type: entity + entity: sensor.family_room_temperature + icon: mdi:thermometer + icon_color: pink + alignment: center + kitchen_id: + name: Kitchen + icon: mdi:silverware-fork-knife + icon_color: red + order: 2 + garage_id: + hidden: true + hallway_id: + type: HaAreaCard + extra_cards: + - type: custom:xiaomi-vacuum-map-card + map_source: + camera: camera.xiaomi_cloud_map_extractor + calibration_source: + camera: true + entity: vacuum.robot_vacuum + vacuum_platform: default +views: [] +``` + +## Undisclosed Area + +The strategy has a special area, named `undisclosed`. +This area is enabled by default and includes the entities that aren't linked to any Home Assistant area. + +The area can be configured like any other area as described above. +To exclude this area from the dashboard and views, set its property `hidden` to `true`. + +## Setting options for all areas + +Use `_` as an identifier to set the options for all areas. +The following example sets the type of all area-cards to the one of Home Assistant: + +### Example + +```yaml +strategy: + type: custom:mushroom-strategy + options: + areas: + _: + type: HaAreaCard +views: [] +``` + +!!! note +Area specific options take precedence over options set for all areas.! + + + +[templateDocUrl]: https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/template.md + +[areaDocUrl]: https://www.home-assistant.io/dashboards/area/#configuration-variables diff --git a/docs/options/card-options.md b/docs/options/card-options.md new file mode 100644 index 0000000..0752c98 --- /dev/null +++ b/docs/options/card-options.md @@ -0,0 +1,35 @@ +# Card Options + +The `card_options` group enables you to specify the configuration of entity cards. +Each configuration is identified by an entity id and can have the following options: + +| name | type | default | description | +|:-------|:--------|:------------------|:------------------------------------------------------| +| hidden | boolean | `false` | Set to `true` to exclude the card from the dashboard. | +| type | string | `domain specific` | The type for card to apply. | +| ... | ... | `type specific` | An option belonging to the given card type. | + +Depending on the type of card, you can also specify options belonging to that type. + +Providing a device id will enable you to hide all the entities associated with that device. + +## Example + +```yaml +strategy: + type: custom:mushroom-strategy + options: + card_options: + fan.master_bedroom_fan: + type: custom:mushroom-fan-card + icon: mdi:fan + remote.harmony_hub_wk: + hidden: true + 077ba0492c9bb3b3134f1f3a626a: # this is a device id + hidden: true +``` + +!!! tip +You can build your card at another dashboard and copy the `cards` group from the YAML of that dashboard into group +`card_options` of the strategy configuration. +The YAML can be found in the Raw configuration editor. diff --git a/docs/options/domain-options.md b/docs/options/domain-options.md new file mode 100644 index 0000000..7af5225 --- /dev/null +++ b/docs/options/domain-options.md @@ -0,0 +1,72 @@ +# Domain Options + +The `domains` group enables you to specify the configuration of a domain in a view. +Each configuration is identified by a domain name and can have the following options: + +| Option | type | Default | Description | +|:-------------------------|:--------|:------------------|:--------------------------------------------------------------------------| +| hidden | boolean | `false` | Set to `true` to exclude the domain from the dashboard. | +| hide_config_entities | boolean | `true` | Set to `false` to include config-entities to the dashboard. | +| hide_diagnostic_entities | boolean | `true` | Set to `false` to include diagnostic-entities to the dashboard. | +| order | number | `unset` | Ordering position of the domain entities in a view. | +| showControls | boolean | `true` | Weather to show controls in a view, to switch all entities of the domain. | +| stack_count | object | `{_: 1}` | Cards per row.[^1] | +| title | string | `domain specific` | Title of the domain in a view. | + +[^1]: +In the different views, the cards belonging to a specific domain will be horizontally stacked into a row. +The number of cards per row can be configured with this option. + +!!! note +* Domain `default` represents any other domain than supported by this strategy. +* The `showControls` option will default to false for domain which can't be controlled. +* The `hide_config_entities` and `hide_diagnostic_entities` options are only available as an "All domains" option. + +--- + +## Setting options for all domains + +Use `_` as the identifier to set options for all domains. + +## Example + +```YAML +strategy: + type: custom:mushroom-strategy + options: + domains: + _: + stack_count: 2 + hide_config_entities: false + light: + title: "My cool lights" + order: 1 + switch: + stack_count: 3 + showControls: false + default: # All other domains + hidden: true +``` + +??? info "Click to expand the full list of supported domains" + + - _ (All domains) + - area + - binary_sensor + - camera + - climate + - cover + - default (Miscellaneous) + - fan + - input_select + - light + - lock + - media_player + - number + - person + - scene + - select + - sensor + - switch + - vacuum + - valve diff --git a/docs/options/home-view-options.md b/docs/options/home-view-options.md new file mode 100644 index 0000000..7d8295c --- /dev/null +++ b/docs/options/home-view-options.md @@ -0,0 +1,197 @@ +# Home View Options + +The `home_view` group enables you to specify the configuration of the Home view. + +| Option | type | default | Description | +|:--------------|:-------|:---------|:----------------------------------------------| +| `hidden` | array | `[]` | Array of sections to hide from the home view. | +| `stack_count` | object | `{_: 2}` | Cards per row. | + +--- + +## Hiding sections + +The following sections can be hidden from the Home view: + +* areas +* areasTitle +* chips +* greeting +* persons + +### Example + +```YAML +strategy: + type: custom:mushroom-strategy + options: + home_view: + hidden: + - greeting + - areasTitle +``` + +--- + +## Stack Count + +The `stack_count` option is a map of sections to define the number of cards per row. +The key of the map is the section, while the value is the number of cards per row. + +The `areas` section is a special case, where the value is an array of two numbers. +The first number is the number of default cards per row, while the second number is the number of +[Home Assistant cards](https://www.home-assistant.io/dashboards/area/) per row. + +### example + +```yaml +home_view: + stack_count: + _: 2 # Two cards per row for all sections. + persons: 3 # Three person cards per row. + areas: [2,1] # [Two Strategy Card per row, 1 HASS card per row] +``` + +!!! note +Section specific options take precedence over options set for all sections.! + +--- + +## Chip Options + +The mushroom strategy has chips that indicate the number of entities for a specific domain which are in an "active" +state. Hidden/Disabled entities are excluded from this count. + +* Tapping a chip will set corresponding entities to an "inactive" state.[^1] +* Tap and hold a chip, will navigate to the corresponding view. + +[^1]: For some chips, the tap action is disabled. + +The `chips` group enables you to specify the configuration of chips. + +| Name | type | default | Description | +|:-----------------|:--------|:--------|:--------------------------------------------| +| `light_count` | boolean | `false` | Number of lights on. | +| `fan_count` | boolean | `false` | Number of fans on. | +| `cover_count` | boolean | `false` | Number of covers not closed. No tap action. | +| `switch_count` | boolean | `false` | Number of switches on. | +| `climate_count` | boolean | `false` | Number of climate not off. No tap action. | +| `weather_entity` | string | `auto` | Entity id for the weather chip to use. | +| `extra_chips` | array | `[]` | List of extra chips to show. | + +If `weather_entity` is set to `auto`, the weather chip uses the first entity of the weather domain it finds. +You can define a custom entity to use by setting an entity id. + +!!! note +To hide the weather chip, you should hide or disable the entity itself. + +```yaml +strategy: + type: custom:mushroom-strategy + options: + chips: + climate_count: false + cover_count: false + weather_entity: weather.forecast_home +``` + +--- + +## Extra Chips + +To add custom chips, you can configure them in `extra_chips`. +See [Mushroom Chips][chipDocUrl] for all available chips. + +!!! tip +You can build your chips in a temporary card in another dashboard and copy the `chips` group from the YAML of that +card into group `extra_chips` of the strategy configuration. The YAML can be found in the Raw configuration editor. + +### Example + +```yaml +strategy: + type: custom:mushroom-strategy + options: + chips: + extra_chips: + - type: conditional + conditions: + - entity: lock.front_door + state: unlocked + chip: + type: entity + entity: lock.front_door + icon_color: red + content_info: none + tap_action: + action: toggle +``` + +--- + +## Quick Access Cards + +The `quick_access_cards` group enables you to specify the configuration of additional cards in the view. +These cards will be shown between the greeting card and area cards. + +Each card can have the options as described at [Card Options](card-options.md). + +!!! tip +You can build your view in a temporary dashboard and copy the `views` group from the YAML of that dashboard into +group `extra_views` of the strategy configuration. +The YAML can be found in the Raw configuration editor. + +### Example + +```yaml +strategy: + type: custom:mushroom-strategy + options: + quick_access_cards: + - type: custom:mushroom-title-card + title: Security + - type: custom:mushroom-cover-card + entity: cover.garage_door + show_buttons_control: true + - type: horizontal-stack + cards: + - type: custom:mushroom-lock-card + entity: lock.front_door + - type: custom:mushroom-entity-card + entity: sensor.front_door_lock_battery + name: Battery +``` + +--- + +### Extra Cards + +The `extra_cards` group enables you to specify the configuration of additional cards in the view. +These cards will be shown below the areas. + +Each card can have the options as described at [Card Options](card-options.md). + +!!! tip +You can build your view in a temporary dashboard and copy the `views` group from the YAML of that dashboard into +group `extra_cards` of the strategy configuration. +The YAML can be found in the Raw configuration editor. + +#### Example + +```yaml +strategy: + type: custom:mushroom-strategy + options: + extra_cards: + - type: custom:xiaomi-vacuum-map-card + map_source: + camera: camera.xiaomi_cloud_map_extractor + calibration_source: + camera: true + entity: vacuum.robot_vacuum + vacuum_platform: default +``` + + + +[chipDocUrl]: https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/chips.md diff --git a/docs/options/index.md b/docs/options/index.md new file mode 100644 index 0000000..4679094 --- /dev/null +++ b/docs/options/index.md @@ -0,0 +1,47 @@ +# Overview + +The dashboard can be highly customized using the `options` parameter in the yaml configuration of your dashboard. + + ```yaml + strategy: + type: custom:mushroom-strategy + options: + # Custom Configuration + ``` + +By default, + +- All views and domains are enabled. +- All chips are enabled and count the number of "active" entities. +- For the weather chip, the entity is selected automatically unless you specify one. +- All entities without an area are added to the `undisclosed` area. +- All configuration- and diagnostic entities are hidden. + +The options are divided into groups as described below. + +| Name | Type | Default | Description | +|:-------------------|:---------------|:----------------------|:------------------------------------------------------------------------------------------------------------------------------------------| +| areas | object | undisclosed | See [Area Options](area-options.md). | +| card_options | object | empty | See [Card Options](card-options.md). | +| domains | object | All supported domains | See [Domain Options](domain-options.md). | +| home_view | object | unset | See [Home View Options](home-view-options.md). | +| chips | object | All supported chips | See [Chip Options](home-view-options.md#chip-options). | +| quick_access_cards | array of cards | empty | List of cards to show between the greeting card and the area cards.
See [Quick Access Cards](home-view-options.md#quick-access-cards). | +| extra_cards | array of cards | empty | List of cards to show below the area cards.
See [extra Cards](home-view-options.md#extra-cards). | +| views | object | All supported views | See [View Options](view-options.md). | +| extra_views | array of views | empty | List of user defined views to add to the dashboard.
See [Extra Views](view-options.md#extra-views). | + +## Example + +```yaml +strategy: + type: custom:mushroom-strategy + options: + areas: + family_room_id: + name: Family Room + icon: mdi:sofa + icon_color: green +``` + + diff --git a/docs/options/view-options.md b/docs/options/view-options.md new file mode 100644 index 0000000..2dbeb86 --- /dev/null +++ b/docs/options/view-options.md @@ -0,0 +1,80 @@ +# View Options + +Mushroom strategy includes several views to control/view entities of a specific domain. +Hidden/Disabled entities or linked to a hidden area are excluded from the view. + +The following views are supported and enabled by default: + +| View | Type | Description | +|:--------|:-------|:-------------------------------------------| +| camera | object | View to control cameras. | +| climate | object | View to control climates. | +| cover | object | View to control covers. | +| fan | object | View to control fans. | +| home | object | An overview of several entities and areas. | +| light | object | View to control lights. | +| lock | object | View to control locks. | +| scene | object | View to control scenes. | +| switch | object | View to control switches. | +| vacuum | object | View to control vacuums. | +| valve | object | View to control valves. | + +The `views` group enables you to specify the configuration of a view. +Each configuration is identified by a view name and can have the following options: + +| name | type | Default | description | +|:-------|:--------|:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------| +| hidden | boolean | `false` | Set to `true` to exclude the view from the dashboard | +| icon | string | `domain specific` | Icon of the view in the navigation bar. | +| order | string | home, light, fan, cover, switch, climate, camera, vacuum, scene, lock, valve | Ordering position of the view in the navigation bar. | +| title | string | `domain specific` | Title of the view in the navigation bar. (Shown when no icon is defined or hovering above it.) | + +## Example + +```yaml +strategy: + type: custom:mushroom-strategy + options: + views: + light: + order: 0 + title: illumination + switch: + order: 1 + hidden: true + icon: mdi:toggle-switch +views: [] +``` + +--- + +## Extra Views + +The `extra_views` group enables you to specify the configuration of additional views. +Each view can have the options as described in the [Home Assistant documentation][viewDocUrl]. + +!!! tip +You can build your view in a temporary dashboard and copy the `views` group from the YAML of that dashboard into +group `extra_views` of the strategy configuration. The YAML can be found in the Raw configuration editor. + +### Example + +```yaml +strategy: + type: custom:mushroom-strategy + options: + extra_views: + - theme: Backend-selected + title: cool view + path: cool-view + icon: mdi:emoticon-cool + badges: [] + cards: + - type: markdown + content: I am cool +``` + + + +[viewDocUrl]: https://www.home-assistant.io/dashboards/views/#views + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..3bcedaf --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,74 @@ +site_name: Mushroom Strategy Documentation +site_url: https://digilive.github.io/mushroom-strategy/ +site_description: The official documentation for Home Assistant's Mushroom Dashboard Strategy. + +repo_url: https://github.com/DigiLive/mushroom-strategy/ +edit_uri: edit/main/docs/ + +site_author: Ferry Cools +copyright: Copyright © 2024 - DigiLive. All Rights Reserved. + +theme: + name: material + icon: + logo: material/mushroom + palette: + - scheme: default + primary: blue + accent: light blue + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: blue + accent: light blue + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.tabs + - navigation.sections + - toc.integrate + - toc.follow + - search.suggest + - search.highlight + - content.code.copy + - content.tabs + - content.action.edit + - content.footnote.tooltips + +nav: + - Home: index.md + - Getting Started: + - Installation: getting-started/installation.md + - Basic Setup: getting-started/basic-setup.md + - Strategy Options: + - Overview: options/index.md + - Area Options: options/area-options.md + - Card Options: options/card-options.md + - Domain Options: options/domain-options.md + - Home View Options: options/home-view-options.md + - View Options: options/view-options.md + - Full Example: full-example.md + - FAQ: faq.md + - Contributing: contributing.md + +markdown_extensions: + - toc: + permalink: "#" + - admonition + - pymdownx.superfences + - pymdownx.details + - footnotes + - attr_list + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + +validation: + nav: + not_found: warn + links: + not_found: warn + anchors: warn + unrecognized_links: warn