getConfigForm example in documentation - simple editor for a custom cards

[Misiu]

Some time ago, in #16142 the devs introduced getConfigForm method which should help us develop custom cards with simple editors.
The pull request got merged, but the docs weren't updated and there was no dev blog post about this new method.

Are there any plans to add this documentation? Many users developed custom cards, and like me, want to move them from YAML to a visual editor.
For new cards, I'd like to use this approach instead of creating a custom editor.

I wasn't sure if this should be an accessibility type of discussion, because the trend is to move from YAML to UI-based configuration.In that case, this method, docs, and a clear example would be very helpful.

[Misiu]

I was able to create a simple card that uses this method. https://community.home-assistant.io/t/getconfigform-configure-editor-for-custom-card/845004

class ProgressBarCard extends HTMLElement {
  // Called whenever Home Assistant updates the state
  set hass(hass) {
    // Get the sensor state object
    const entityId = this.config.entity;
    const stateObj = hass.states[entityId];
    const newStateStr = stateObj ? stateObj.state : "unavailable";

    // If the state has not changed, do nothing.
    if (this._lastState === newStateStr) {
      return;
    }
    this._lastState = newStateStr;

    // Build the card DOM if it hasn't been built yet.
    if (!this.content) {

      this.innerHTML = `
        <ha-card class="overflow-hidden">
          <style>
            .overflow-hidden {
              overflow: hidden;
            }
            .progress-bar {
              margin: 0;
              padding: 0;
              background-color: var(--mdc-theme-primary,#6200ee);
              height: 12px;
              width: 0%;
              transition: width 0.3s ease;
            }
          </style>
              <div class="progress-bar"></div>
        </ha-card>
      `;
      this.progressBar = this.querySelector(".progress-bar");
    }
    
    // Parse the sensor value and compute progress percentage.
    const stateValue = stateObj ? parseFloat(stateObj.state) : 0;
    const min = parseFloat(this.config.min);
    const max = parseFloat(this.config.max);
    let progressPercent = 0;
    if (max > min) {
      progressPercent = ((stateValue - min) / (max - min)) * 100;
      progressPercent = Math.min(Math.max(progressPercent, 0), 100);
    }
    
    // Update only if the computed progress has changed significantly.
    if (this._lastProgressPercent !== progressPercent) {
      this._lastProgressPercent = progressPercent;
      this.progressBar.style.width = `${progressPercent}%`;
    }
  }

  // Called with the user-provided YAML configuration.
  setConfig(config) {
    if (!config.entity) {
      throw new Error("You need to define an entity");
    }
    // Set defaults for min and max if they are not provided.
    this.config = {
      min: 0,
      max: 100,
      ...config,
    };
    
    this._lastState = null;
    this._lastProgressPercent = null;
  }

  // This function is used by Home Assistant to calculate card height in masonry view.
  getCardSize() {
    return 3;
  }

  // For grid-based layouts (sections view), you can provide layout options.
  getLayoutOptions() {
    return {
      grid_rows: 1,
      grid_columns: 2,
      grid_min_rows: 3,
      grid_max_rows: 3,
    };
  }

  static getConfigForm() {
    // Define the form schema.
    const SCHEMA = [
      { name: "entity", required: true, selector: { entity: {} } },
      { name: "min", selector: { text: { type: "number" } } },
      { name: "max", selector: { text: { type: "number" } } },
    ];

    // A simple assertion function to validate the configuration.
    const assertConfig = (config) => {
      if (!config.entity || typeof config.entity !== "string") {
        throw new Error('Configuration error: "entity" must be a non-empty string.');
      }
      if (config.min !== undefined && isNaN(Number(config.min))) {
        throw new Error('Configuration error: "min" must be a valid number.');
      }
      if (config.max !== undefined && isNaN(Number(config.max))) {
        throw new Error('Configuration error: "max" must be a valid number.');
      }
    };

    // computeLabel returns a localized label for a schema item.
    const computeLabel = (schema, localize) => {
      return localize(`ui.panel.lovelace.editor.card.generic.${schema.name}`);
    };

    return {
      schema: SCHEMA,
      assertConfig: assertConfig,
      computeLabel: computeLabel,
    };
  }

  // Provide default configuration when a new card is added.
  static getStubConfig() {
    return {
      entity: "sensor.example_progress",
      min: 0,
      max: 100
    };
  }
}

customElements.define("ha-progress-bar-card", ProgressBarCard);

// Register the card in Home Assistant’s custom card registry.
window.customCards = window.customCards || [];
window.customCards.push({
  type: "ha-progress-bar-card",
  name: "Progress Bar Card",
  description: "A custom card to show progress (for example, for a 3D printer)",
});

Proper documentation would still be helpful.