From 1ba9dedb12709be78430615a5a24d132bb0703d5 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Tue, 5 May 2026 22:22:53 -0500 Subject: [PATCH 1/4] Document upstream esphome source for advanced/hidden flags --- src/api/types.ts | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/src/api/types.ts b/src/api/types.ts index ed6a4057..9b727abd 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -588,9 +588,27 @@ export interface ConfigEntry { pin_mode: PinMode | null; // === UI / i18n === - /** When True frontend collapses this entry under an "Advanced" section. */ + /** + * When True frontend collapses this entry under an "Advanced" section. + * + * Source of truth: upstream esphome's ``cv.Optional(..., + * advanced=True)`` schema kwarg (esphome/esphome#16267) when the + * field author marked it explicitly. The catalog generator's + * ``_classify_advanced`` heuristic in ``script/sync_components.py`` + * is the fallback for fields the schema doesn't yet annotate; as + * upstream adoption grows, the heuristic shrinks toward zero. + */ advanced: boolean; - /** When True frontend hides the entry entirely. */ + /** + * When True frontend hides the entry entirely. + * + * Source of truth: upstream esphome's ``cv.Optional(..., + * yaml_only=True)`` schema kwarg (esphome/esphome#16267). Marks + * fields the user shouldn't edit through a visual editor — e.g. + * ``setup_priority`` on every component, where casual UI-driven + * tweaks can break boot. The YAML escape hatch stays available + * for the rare power-user override. + */ hidden: boolean; /** Optional URL pointing to documentation specific to this field. */ help_link: string | null; From c1a8f332aa4890cdd1b19eb7f1c3a3e9461e5269 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Tue, 5 May 2026 22:28:29 -0500 Subject: [PATCH 2/4] Switch JSDoc to single backticks; drop cross-repo path reference --- src/api/types.ts | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/api/types.ts b/src/api/types.ts index 9b727abd..7119fa42 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -591,21 +591,21 @@ export interface ConfigEntry { /** * When True frontend collapses this entry under an "Advanced" section. * - * Source of truth: upstream esphome's ``cv.Optional(..., - * advanced=True)`` schema kwarg (esphome/esphome#16267) when the - * field author marked it explicitly. The catalog generator's - * ``_classify_advanced`` heuristic in ``script/sync_components.py`` - * is the fallback for fields the schema doesn't yet annotate; as - * upstream adoption grows, the heuristic shrinks toward zero. + * Source of truth: upstream esphome's `cv.Optional(..., + * advanced=True)` schema kwarg (esphome/esphome#16267) when the + * field author marked it explicitly. The device-builder catalog + * generator's name-based heuristic is the fallback for fields the + * schema doesn't yet annotate; as upstream adoption grows, the + * heuristic shrinks toward zero. */ advanced: boolean; /** * When True frontend hides the entry entirely. * - * Source of truth: upstream esphome's ``cv.Optional(..., - * yaml_only=True)`` schema kwarg (esphome/esphome#16267). Marks + * Source of truth: upstream esphome's `cv.Optional(..., + * yaml_only=True)` schema kwarg (esphome/esphome#16267). Marks * fields the user shouldn't edit through a visual editor — e.g. - * ``setup_priority`` on every component, where casual UI-driven + * `setup_priority` on every component, where casual UI-driven * tweaks can break boot. The YAML escape hatch stays available * for the rare power-user override. */ From ab1432accc13fbb965bc98d531ff16e9968fd492 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Tue, 5 May 2026 22:55:10 -0500 Subject: [PATCH 3/4] Update doc to reference upstream visibility enum + cascade pass --- src/api/types.ts | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/src/api/types.ts b/src/api/types.ts index 7119fa42..aeacf949 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -591,23 +591,30 @@ export interface ConfigEntry { /** * When True frontend collapses this entry under an "Advanced" section. * - * Source of truth: upstream esphome's `cv.Optional(..., - * advanced=True)` schema kwarg (esphome/esphome#16267) when the - * field author marked it explicitly. The device-builder catalog - * generator's name-based heuristic is the fallback for fields the - * schema doesn't yet annotate; as upstream adoption grows, the - * heuristic shrinks toward zero. + * Sourced from upstream esphome's `cv.Optional(..., + * visibility=cv.Visibility.ADVANCED)` schema kwarg + * (esphome/esphome#16267) when the field author marked it + * explicitly, or pushed down by the catalog generator's cascade + * pass when an ancestor is `ADVANCED` or stricter. The + * device-builder catalog's name-based heuristic is the + * fallback for fields the schema doesn't yet annotate; as + * upstream adoption grows, the heuristic shrinks toward zero. */ advanced: boolean; /** * When True frontend hides the entry entirely. * - * Source of truth: upstream esphome's `cv.Optional(..., - * yaml_only=True)` schema kwarg (esphome/esphome#16267). Marks - * fields the user shouldn't edit through a visual editor — e.g. - * `setup_priority` on every component, where casual UI-driven - * tweaks can break boot. The YAML escape hatch stays available - * for the rare power-user override. + * Sourced from upstream esphome's `cv.Optional(..., + * visibility=cv.Visibility.YAML_ONLY)` schema kwarg + * (esphome/esphome#16267). Marks fields the user shouldn't + * edit through a visual editor — e.g. `setup_priority` on + * every component, where casual UI-driven tweaks can break + * boot. The YAML escape hatch stays available for the rare + * power-user override. Also pushed down by the catalog + * generator's cascade pass when an ancestor is `YAML_ONLY`: a + * hidden parent takes its descendants with it (otherwise the + * editor would render an unrooted control with no surrounding + * context). */ hidden: boolean; /** Optional URL pointing to documentation specific to this field. */ From 0fd3eef59feaf3376fbfd1a8f2b4a2c556837800 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Tue, 5 May 2026 23:02:36 -0500 Subject: [PATCH 4/4] Keep visibility-enum inline-code spans on a single line in JSDoc Multi-line backticked spans render poorly in TS-tooling hovers (VS Code in particular). Shorten the references to bare `Visibility.ADVANCED` / `Visibility.YAML_ONLY` so each inline- code span sits on a single line. --- src/api/types.ts | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/src/api/types.ts b/src/api/types.ts index aeacf949..911ca5a1 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -591,12 +591,11 @@ export interface ConfigEntry { /** * When True frontend collapses this entry under an "Advanced" section. * - * Sourced from upstream esphome's `cv.Optional(..., - * visibility=cv.Visibility.ADVANCED)` schema kwarg - * (esphome/esphome#16267) when the field author marked it - * explicitly, or pushed down by the catalog generator's cascade - * pass when an ancestor is `ADVANCED` or stricter. The - * device-builder catalog's name-based heuristic is the + * Sourced from upstream esphome's `Visibility.ADVANCED` schema + * kwarg (esphome/esphome#16267) when the field author marked + * it explicitly, or pushed down by the catalog generator's + * cascade pass when an ancestor is `ADVANCED` or stricter. + * The device-builder catalog's name-based heuristic is the * fallback for fields the schema doesn't yet annotate; as * upstream adoption grows, the heuristic shrinks toward zero. */ @@ -604,17 +603,16 @@ export interface ConfigEntry { /** * When True frontend hides the entry entirely. * - * Sourced from upstream esphome's `cv.Optional(..., - * visibility=cv.Visibility.YAML_ONLY)` schema kwarg - * (esphome/esphome#16267). Marks fields the user shouldn't - * edit through a visual editor — e.g. `setup_priority` on - * every component, where casual UI-driven tweaks can break - * boot. The YAML escape hatch stays available for the rare - * power-user override. Also pushed down by the catalog - * generator's cascade pass when an ancestor is `YAML_ONLY`: a - * hidden parent takes its descendants with it (otherwise the - * editor would render an unrooted control with no surrounding - * context). + * Sourced from upstream esphome's `Visibility.YAML_ONLY` + * schema kwarg (esphome/esphome#16267). Marks fields the user + * shouldn't edit through a visual editor — e.g. + * `setup_priority` on every component, where casual UI-driven + * tweaks can break boot. The YAML escape hatch stays + * available for the rare power-user override. Also pushed down + * by the catalog generator's cascade pass when an ancestor is + * `YAML_ONLY`: a hidden parent takes its descendants with it + * (otherwise the editor would render an unrooted control with + * no surrounding context). */ hidden: boolean; /** Optional URL pointing to documentation specific to this field. */