Card Editor: Documentation per Card (#5888)

* Doc-links

* Comments

* Fix

* Remove unneeded code

* undo the change

* better

src/data/lovelace_custom_cards.ts

@@ -3,6 +3,7 @@ export interface CustomCardEntry {
   name?: string;
   description?: string;
   preview?: boolean;
+  documentationURL?: string;
 }
 
 export interface CustomCardsWindow {

src/panels/lovelace/editor/card-editor/hui-card-picker.ts

@@ -30,52 +30,14 @@ import {
 import { createCardElement } from "../../create-element/create-card-element";
 import { LovelaceCard } from "../../types";
 import { getCardStubConfig } from "../get-card-stub-config";
-import { CardPickTarget } from "../types";
-
-interface Card {
-  type: string;
-  name?: string;
-  description?: string;
-  noElement?: boolean;
-  isCustom?: boolean;
-}
+import { CardPickTarget, Card } from "../types";
+import { coreCards } from "../lovelace-cards";
 
 interface CardElement {
   card: Card;
   element: TemplateResult;
 }
 
-const previewCards: string[] = [
-  "alarm-panel",
-  "button",
-  "entities",
-  "entity",
-  "gauge",
-  "glance",
-  "history-graph",
-  "light",
-  "map",
-  "markdown",
-  "media-control",
-  "picture",
-  "picture-elements",
-  "picture-entity",
-  "picture-glance",
-  "plant-status",
-  "sensor",
-  "thermostat",
-  "weather-forecast",
-];
-
-const nonPreviewCards: string[] = [
-  "conditional",
-  "entity-filter",
-  "horizontal-stack",
-  "iframe",
-  "vertical-stack",
-  "shopping-list",
-];
-
 @customElement("hui-card-picker")
 export class HuiCardPicker extends LitElement {
   @property() public hass?: HomeAssistant;
@@ -136,11 +98,7 @@ export class HuiCardPicker extends LitElement {
         )}
       </div>
       <div class="cards-container">
-        <div
-          class="card"
-          @click="${this._cardPicked}"
-          .config="${{ type: "" }}"
-        >
+        <div class="card" @click=${this._cardPicked} .config=${{ type: "" }}>
           <div class="preview description">
             ${this.hass!.localize(
               `ui.panel.lovelace.editor.card.generic.manual_description`
@@ -192,33 +150,22 @@ export class HuiCardPicker extends LitElement {
   }
 
   private _loadCards() {
-    let cards: Card[] = previewCards
-      .map((type: string) => ({
-        type,
-        name: this.hass!.localize(`ui.panel.lovelace.editor.card.${type}.name`),
-        description: this.hass!.localize(
-          `ui.panel.lovelace.editor.card.${type}.description`
-        ),
-      }))
-      .concat(
-        nonPreviewCards.map((type: string) => ({
-          type,
-          name: this.hass!.localize(
-            `ui.panel.lovelace.editor.card.${type}.name`
-          ),
-          description: this.hass!.localize(
-            `ui.panel.lovelace.editor.card.${type}.description`
-          ),
-          noElement: true,
-        }))
-      );
+    let cards: Card[] = coreCards.map((card: Card) => ({
+      name: this.hass!.localize(
+        `ui.panel.lovelace.editor.card.${card.type}.name`
+      ),
+      description: this.hass!.localize(
+        `ui.panel.lovelace.editor.card.${card.type}.description`
+      ),
+      ...card,
+    }));
     if (customCards.length > 0) {
       cards = cards.concat(
         customCards.map((ccard: CustomCardEntry) => ({
           type: ccard.type,
           name: ccard.name,
           description: ccard.description,
-          noElement: true,
+          showElement: ccard.preview,
           isCustom: true,
         }))
       );
@@ -341,7 +288,7 @@ export class HuiCardPicker extends LitElement {
 
   private async _renderCardElement(card: Card): Promise<TemplateResult> {
     let { type } = card;
-    const { noElement, isCustom, name, description } = card;
+    const { showElement, isCustom, name, description } = card;
     const customCard = isCustom ? getCustomCardEntry(type) : undefined;
     if (isCustom) {
       type = `${CUSTOM_TYPE_PREFIX}${type}`;
@@ -358,7 +305,7 @@ export class HuiCardPicker extends LitElement {
         this._usedEntities!
       );
 
-      if (!noElement || customCard?.preview) {
+      if (showElement) {
         element = this._createCardElement(cardConfig);
       }
     }

src/panels/lovelace/editor/card-editor/hui-dialog-edit-card.ts

@@ -1,3 +1,4 @@
+import "@polymer/paper-dialog-scrollable/paper-dialog-scrollable";
 import deepFreeze from "deep-freeze";
 import {
   css,
@@ -8,6 +9,7 @@ import {
   property,
   query,
   TemplateResult,
+  PropertyValues,
 } from "lit-element";
 import type { HASSDomEvent } from "../../../../common/dom/fire_event";
 import "../../../../components/dialog/ha-paper-dialog";
@@ -25,7 +27,7 @@ import type { ConfigChangedEvent, HuiCardEditor } from "./hui-card-editor";
 import "./hui-card-picker";
 import "./hui-card-preview";
 import type { EditCardDialogParams } from "./show-edit-card-dialog";
-import "@polymer/paper-dialog-scrollable/paper-dialog-scrollable";
+import { getCardDocumentationURL } from "../get-card-documentation-url";
 
 declare global {
   // for fire event
@@ -58,6 +60,8 @@ export class HuiDialogEditCard extends LitElement {
 
   @property() private _GUImode = true;
 
+  @property() private _documentationURL?: string;
+
   public async showDialog(params: EditCardDialogParams): Promise<void> {
     this._params = params;
     this._GUImode = true;
@@ -71,6 +75,22 @@ export class HuiDialogEditCard extends LitElement {
     }
   }
 
+  protected updated(changedProps: PropertyValues): void {
+    if (
+      !this._cardConfig ||
+      this._documentationURL !== undefined ||
+      !changedProps.has("_cardConfig")
+    ) {
+      return;
+    }
+
+    const oldConfig = changedProps.get("_cardConfig") as LovelaceCardConfig;
+
+    if (oldConfig?.type !== this._cardConfig!.type) {
+      this._documentationURL = getCardDocumentationURL(this._cardConfig!.type);
+    }
+  }
+
   protected render(): TemplateResult {
     if (!this._params) {
       return html``;
@@ -97,9 +117,26 @@ export class HuiDialogEditCard extends LitElement {
 
     return html`
       <ha-paper-dialog with-backdrop opened modal @keyup=${this._handleKeyUp}>
-        <h2>
-          ${heading}
-        </h2>
+        <div class="header">
+          <h2>
+            ${heading}
+          </h2>
+          ${this._documentationURL !== undefined
+            ? html`
+                <a
+                  class="help-icon"
+                  href=${this._documentationURL}
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  <ha-icon-button
+                    icon="hass:help-circle"
+                    .title=${this.hass!.localize("ui.panel.lovelace.menu.help")}
+                  ></ha-icon-button>
+                </a>
+              `
+            : ""}
+        </div>
         <paper-dialog-scrollable>
           ${this._cardConfig === undefined
             ? html`
@@ -275,6 +312,15 @@ export class HuiDialogEditCard extends LitElement {
         .gui-mode-button {
           margin-right: auto;
         }
+        .header {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+        }
+        .help-icon {
+          text-decoration: none;
+          color: inherit;
+        }
       `,
     ];
   }
@@ -318,6 +364,7 @@ export class HuiDialogEditCard extends LitElement {
     this._params = undefined;
     this._cardConfig = undefined;
     this._error = undefined;
+    this._documentationURL = undefined;
   }
 
   private get _canSave(): boolean {

src/panels/lovelace/editor/get-card-documentation-url.ts

@@ -0,0 +1,14 @@
+import {
+  getCustomCardEntry,
+  CUSTOM_TYPE_PREFIX,
+} from "../../../data/lovelace_custom_cards";
+
+const coreDocumentationURLBase = "https://www.home-assistant.io/lovelace/";
+
+export const getCardDocumentationURL = (type: string): string | undefined => {
+  if (type.startsWith(CUSTOM_TYPE_PREFIX)) {
+    return getCustomCardEntry(type)?.documentationURL;
+  }
+
+  return `${coreDocumentationURLBase}${type}`;
+};

src/panels/lovelace/editor/lovelace-cards.ts

@@ -0,0 +1,98 @@
+import { Card } from "./types";
+
+export const coreCards: Card[] = [
+  {
+    type: "alarm-panel",
+    showElement: true,
+  },
+  {
+    type: "button",
+    showElement: true,
+  },
+  {
+    type: "entities",
+    showElement: true,
+  },
+  {
+    type: "entity",
+    showElement: true,
+  },
+  {
+    type: "gauge",
+    showElement: true,
+  },
+  {
+    type: "glance",
+    showElement: true,
+  },
+  {
+    type: "history-graph",
+    showElement: true,
+  },
+  {
+    type: "light",
+    showElement: true,
+  },
+  {
+    type: "map",
+    showElement: true,
+  },
+  {
+    type: "markdown",
+    showElement: true,
+  },
+  {
+    type: "media-control",
+    showElement: true,
+  },
+  {
+    type: "picture",
+    showElement: true,
+  },
+  {
+    type: "picture-elements",
+    showElement: true,
+  },
+  {
+    type: "picture-entity",
+    showElement: true,
+  },
+  {
+    type: "picture-glance",
+    showElement: true,
+  },
+  {
+    type: "plant-status",
+    showElement: true,
+  },
+  {
+    type: "sensor",
+    showElement: true,
+  },
+  {
+    type: "thermostat",
+    showElement: true,
+  },
+  {
+    type: "weather-forecast",
+    showElement: true,
+  },
+  {
+    type: "conditional",
+  },
+  {
+    type: "entity-filter",
+  },
+  {
+    type: "horizontal-stack",
+  },
+  {
+    type: "iframe",
+  },
+  {
+    type: "vertical-stack",
+  },
+  {
+    type: "shopping-list",
+  },
+];

src/panels/lovelace/editor/types.ts

@@ -54,6 +54,14 @@ export interface EditorTarget extends EventTarget {
   config: ActionConfig;
 }
 
+export interface Card {
+  type: string;
+  name?: string;
+  description?: string;
+  showElement?: boolean;
+  isCustom?: boolean;
+}
+
 export interface CardPickTarget extends EventTarget {
   config: LovelaceCardConfig;
 }