feat(plugins): redesign flow editor documentation panel by flcarre · Pull Request #17048 · kestra-io/kestra

flcarre · 2026-06-24T15:26:20Z

Closes https://github.com/kestra-io/kestra-ee/issues/8879

What & why

Redesigns the flow-editor documentation panel (the plugin/task docs shown while editing a flow) for a shadcn-grade reading experience. This panel reaches ~98% of flow-editor users and is the highest-volume editor surface, so its clarity matters. The redesign covers both states of the panel: the default intro page (no task at cursor) and the task-bound view. It reworks the Flow properties presentation flagged in the linked issue (the old 2-column table is replaced by clean stacked rows with intentional spacing).

Changes

Intro / default page (PluginDocumentation.vue)

Hero, a contextual callout, a reference search, and tabbed sections (Overview / Flow / Tasks / Inputs / Pebble / Examples) split from the bundled basic.md.
A "Start here" guide whose 3 steps are now real buttons that jump to the matching reference tab (id/namespace, tasks, inputs).
A "Learn more" link grid.
The intro now renders immediately instead of being gated behind the plugins fetch, so it survives a slow or flaky /plugins load.

Task-bound view

Redesigned header: package kicker, task icon, name, kind chip, copyable full type, version, release link, and a summary line.
A controlled section nav (Overview / Properties N / Outputs N / Examples).
A compact, filterable properties reference (All / Required) via a new compact mode in SchemaToHtml / SchemaPropertiesSection.

Design system (KsTable.vue)

Exposes a --ks-table-row-hover-bg token (defaults to --ks-bg-hover), so the panel can disable row-hover on read-only markdown tables through a CSS variable instead of a :deep override.

How it was verified

npm run check:types (design-system + app + test), eslint, and node check.js all green.
Live QA on the running app driving every flow (intro, actionable steps, search, bound task view, properties): 0 console / page errors, all states render in light and dark mode.
A short demo video of the flows was recorded; I will drag-drop the mp4 into this PR.

doc-panel-demo.mp4

Notes

No backend changes. PluginList.vue shows no net diff (an exploratory change was reverted).
This is a UI redesign and would benefit from a design sign-off before merge.

🤖 Generated with Claude Code

github-actions · 2026-06-24T15:30:48Z

📄 OpenAPI Spec Changes

❌ Failed to generate EE OpenAPI spec (EE branch: develop).

rResponse;
                                    ^
/home/runner/work/kestra-ee/kestra/webserver/src/main/java/io/kestra/webserver/controllers/api/NamespaceController.java:95: warning: [unchecked] unchecked cast
                    .build()
                          ^
  required: N
  found:    CAP#1
  where N is a type-variable:
    N extends Namespace declared in class NamespaceController
  where CAP#1 is a fresh type-variable:
    CAP#1 extends Namespace from capture of ?
/home/runner/work/kestra-ee/kestra/webserver/src/main/java/io/kestra/webserver/controllers/api/NamespaceController.java:131: warning: [unchecked] unchecked cast
        return (N) Namespace.builder().id(id).build();
                                                   ^
  required: N
  found:    CAP#1
  where N is a type-variable:
    N extends Namespace declared in class NamespaceController
  where CAP#1 is a fresh type-variable:
    CAP#1 extends Namespace from capture of ?
/home/runner/work/kestra-ee/kestra/webserver/src/main/java/io/kestra/webserver/services/ai/AiServiceManager.java:68: warning: [unchecked] unchecked conversion
            Map<String, Object> rawConfig = propertyResolver.get("kestra.ai." + legacyType, Map.class).orElse(null);
                                                                                                             ^
  required: Map<String,Object>
  found:    Map
/home/runner/work/kestra-ee/kestra/webserver/src/main/java/io/kestra/webserver/services/ai/AiServiceManager.java:86: warning: [this-escape] possible 'this' escape before subclass is fully initialized
                AiServiceInterface aiService = createAiService(
                                                              ^
/home/runner/work/kestra-ee/kestra/webserver/src/main/java/io/kestra/webserver/services/ai/AiService.java:278: warning: [rawtypes] found raw type: Class
                return parentPlugin.allClassGrouped().entrySet().stream().flatMap(e -> e.getValue().stream().map(pluginClass ->
                                                                                  ^
  missing type arguments for generic class Class<T>
  where T is a type-variable:
    T extends Object declared in class Class
/home/runner/work/kestra-ee/kestra/webserver/src/main/java/io/kestra/webserver/controllers/api/SecretController.java:58: warning: [unchecked] unchecked cast
            (ApiSecretListResponse<META>) new ApiSecretListResponse<>(
                                          ^
  required: ApiSecretListResponse<META>
  found:    ApiSecretListResponse<ApiSecretMeta>
  where META is a type-variable:
    META extends ApiSecretMeta declared in class SecretController
/home/runner/work/kestra-ee/kestra/webserver/src/main/java/io/kestra/webserver/services/FlowAutoLoaderService.java:70: warning: [rawtypes] found raw type: PagedResults
                .map(response -> ((PagedResults<ApiBlueprintItem>) response.body()).getResults())
                     ^
  missing type arguments for generic class PagedResults<T>
  where T is a type-variable:
    T extends Object declared in class PagedResults
15 warnings

> Task :webserver:generateOpenapiSpec
> Task :webserver-ee:compileJava
/home/runner/work/kestra-ee/kestra-ee/webserver-ee/src/main/java/io/kestra/ee/webserver/controllers/api/MiscController.java:564: warning: Ambiguous: Jackson2 and Jackson3 exist; define which variant(s) you want in 'lombok.config'. See https://projectlombok.org/features/experimental/Jacksonized
    @Jacksonized
    ^
Note: Generating OpenAPI Documentation
Note: Expanding properties: [\$\{version}->2.0.0-SNAPSHOT]
Note: Writing OpenAPI file to destination: /home/runner/work/kestra-ee/kestra-ee/webserver-ee/build/classes/java/main/META-INF/swagger/kestra-ee.yml
Note: Expanding properties: [\$\{version}->2.0.0-SNAPSHOT]
Note: Writing OpenAPI file to destination: /home/runner/work/kestra-ee/kestra-ee/webserver-ee/build/classes/java/main/META-INF/swagger/kestra-ee.yml
Note: Expanding properties: [\$\{version}->2.0.0-SNAPSHOT]
Note: Writing OpenAPI file to destination: /home/runner/work/kestra-ee/kestra-ee/webserver-ee/build/classes/java/main/META-INF/swagger/kestra-ee.yml
/home/runner/work/kestra-ee/kestra-ee/webserver-ee/src/main/java/io/kestra/ee/webserver/controllers/api/ExecutionController.java:9: error: cannot find symbol
import io.kestra.webserver.controllers.api.FileFormat;
                                          ^
  symbol:   class FileFormat
  location: package io.kestra.webserver.controllers.api
/home/runner/work/kestra-ee/kestra-ee/webserver-ee/src/main/java/io/kestra/ee/webserver/controllers/api/ExecutionController.java:249: error: cannot find symbol
    public HttpResponse<StreamedFile> downloadFileFromExecution(String executionId, URI path, FileFormat format) throws IOException, URISyntaxException {
                                                                                              ^
  symbol:   class FileFormat
  location: class ExecutionController
Note: Expanding properties: [\$\{version}->2.0.0-SNAPSHOT]
Note: Writing OpenAPI file to destination: /home/runner/work/kestra-ee/kestra-ee/webserver-ee/build/classes/java/main/META-INF/swagger/kestra-ee.yml
/home/runner/work/kestra-ee/kestra-ee/webserver-ee/src/main/java/io/kestra/ee/webserver/controllers/api/ExecutionController.java:72: warning: Bean definition generation [io.kestra.ee.webserver.controllers.api.ExecutionController] skipped from processing because of prior error: [io.kestra.ee.webserver.controllers.api.ExecutionController format]. This error is normally due to missing classes on the classpath. Verify the compilation classpath is correct to resolve the problem.
public class ExecutionController extends io.kestra.webserver.controllers.api.ExecutionController implements SecuritySchemeControllerAnnotation {
       ^
2 errors
2 warnings

> Task :webserver-ee:compileJava FAILED
gradle/actions: Writing build results to /home/runner/work/_temp/.gradle-actions/build-results/openapi-diff-1782314831955.json

[Incubating] Problems report is available at: file:///home/runner/work/kestra-ee/kestra-ee/build/reports/problems/problems-report.html

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':webserver-ee:compileJava'.
> Compilation failed; see the compiler output below.
  /home/runner/work/kestra-ee/kestra-ee/webserver-ee/src/main/java/io/kestra/ee/webserver/controllers/api/MiscController.java:564: warning: Ambiguous: Jackson2 and Jackson3 exist; define which variant(s) you want in 'lombok.config'. See https://projectlombok.org/features/experimental/Jacksonized
      @Jacksonized
      ^
  /home/runner/work/kestra-ee/kestra-ee/webserver-ee/src/main/java/io/kestra/ee/webserver/controllers/api/ExecutionController.java:72: warning: Bean definition generation [io.kestra.ee.webserver.controllers.api.ExecutionController] skipped from processing because of prior error: [io.kestra.ee.webserver.controllers.api.ExecutionController format]. This error is normally due to missing classes on the classpath. Verify the compilation classpath is correct to resolve the problem.
  public class ExecutionController extends io.kestra.webserver.controllers.api.ExecutionController implements SecuritySchemeControllerAnnotation {
         ^
  /home/runner/work/kestra-ee/kestra-ee/webserver-ee/src/main/java/io/kestra/ee/webserver/controllers/api/ExecutionController.java:9: error: cannot find symbol
  import io.kestra.webserver.controllers.api.FileFormat;
                                            ^
    symbol:   class FileFormat
    location: package io.kestra.webserver.controllers.api
  /home/runner/work/kestra-ee/kestra-ee/webserver-ee/src/main/java/io/kestra/ee/webserver/controllers/api/ExecutionController.java:249: error: cannot find symbol
      public HttpResponse<StreamedFile> downloadFileFromExecution(String executionId, URI path, FileFormat format) throws IOException, URISyntaxException {
                                                                                                ^
    symbol:   class FileFormat
    location: class ExecutionController
  Note: Generating OpenAPI Documentation
  Note: Expanding properties: [\$\{version}->2.0.0-SNAPSHOT]
  Note: Writing OpenAPI file to destination: /home/runner/work/kestra-ee/kestra-ee/webserver-ee/build/classes/java/main/META-INF/swagger/kestra-ee.yml
  2 errors
  2 warnings

* Try:
> Check your code and dependencies to fix the compilation error(s)
> Run with --scan to get full insights from a Build Scan (powered by Develocity).

Deprecated Gradle features were used in this build, making it incompatible with Gradle 10.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/9.4.1/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD FAILED in 3m 49s
10 actionable tasks: 10 executed

🐋 Docker image

ghcr.io/kestra-io/kestra-pr:17048

docker run --pull=always --rm -it -p 8080:8080 --user=root -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp ghcr.io/kestra-io/kestra-pr:17048 server local

flcarre · 2026-06-24T15:32:03Z

@anna-geller @tchiotludo @Nico-Kestra @loicmathieu proposol of an improvement of the doc tab as saw yesterday. What do you think of this ?

tchiotludo · 2026-06-24T21:05:34Z

definitely better, love it ❤️

Piyush-r-bhaskar

Hey,

Issue is about revamp for Flow Properties Docs only but you have changed the Plugin documentation as well in panel. is this related ?
If Yes, could we have a FIGMA to track please ?
If no, revert the changes for Schema and Plugin documentation and we are good.

flcarre · 2026-07-21T09:31:25Z

Yes it's intentional: both docs share the same panel and the same components (SchemaToHtml), restyling only the flow properties would have left it half old / half new.

No Figma here, it was designed code-first with the DS tokens, the demo video above is the reference.

@Nico-Kestra can you take a look design-wise?

Piyush-r-bhaskar · 2026-07-22T05:52:30Z

can you fix the conflicts please @flcarre

Redesign the flow-editor documentation panel for a shadcn-grade reading experience, covering both the default intro page and the task-bound view. - Intro: hero, contextual callout, reference search, and tabbed sections (Overview/Flow/Tasks/Inputs/Pebble/Examples) split from basic.md, with a "Start here" guide whose steps jump to the matching reference tab. - Bound view: redesigned header (kicker, icon, name, kind chip, copyable type, version, release link, summary), a controlled section nav, and a compact, filterable properties reference (All/Required) via SchemaToHtml / SchemaPropertiesSection compact mode. - KsTable: expose --ks-table-row-hover-bg (defaults to --ks-bg-hover) so the panel can disable row-hover on read-only markdown tables without :deep. - Render the intro immediately instead of gating it behind the plugins fetch. - Add plugins.intro_* / nav_* / filter_* i18n keys across all 13 locales. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The documentation-panel redesign (#17048) replaced the intro's plain markdown render with a hardcoded, flow-centric tabbed layout, which silently stopped honoring the `overrideIntro` prop. Every editor that supplies a feature-specific intro fell back to showing the generic flow documentation: dashboards (dashboard_home.md), plus apps (apps_home.md) and test suites (tests_home.md) in EE, which reuse this same component. Render `overrideIntro` verbatim when provided, and keep the rich flow intro for the default (flow-editor) case. Cover both branches in the Storybook story. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…stWrapper Nothing has assigned isLoading since #17048 removed the assignments around the plugin fetch, so `isLoading || !pluginsData` only ever evaluated `!pluginsData`. The store's `plugins` is `ref<Plugin[]>()`, undefined until the fetch lands, so that guard alone still drives the skeleton branch. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TAug4a76FHxVfXWtQ7UwzT

github-project-automation Bot added this to Pull Requests Jun 24, 2026

github-project-automation Bot moved this to To review in Pull Requests Jun 24, 2026

flcarre requested review from a team and Piyush-r-bhaskar June 25, 2026 10:12

Piyush-r-bhaskar requested changes Jul 2, 2026

View reviewed changes

flcarre requested a review from Piyush-r-bhaskar July 22, 2026 05:06

flcarre force-pushed the claude/goofy-keller-75d680 branch from dd128c4 to e37bc2a Compare July 22, 2026 06:26

Piyush-r-bhaskar approved these changes Jul 22, 2026

View reviewed changes

flcarre merged commit e0db713 into develop Jul 22, 2026
13 checks passed

flcarre deleted the claude/goofy-keller-75d680 branch July 22, 2026 08:31

github-project-automation Bot moved this from To review to Done in Pull Requests Jul 22, 2026

flcarre mentioned this pull request Jul 27, 2026

fix(plugins): show feature-specific docs in the editor documentation panel #17648

Merged

flcarre mentioned this pull request Jul 27, 2026

fix(dashboards): documentation panel not updating on chart block sele… #17640

Closed

elevatebart mentioned this pull request Sep 7, 2026

fix(plugins): flow description block in the editor Docs panel #19082

Merged

5 tasks

Navigation Menu

Uh oh!

feat(plugins): redesign flow editor documentation panel - #17048

feat(plugins): redesign flow editor documentation panel#17048
flcarre merged 1 commit into
developfrom
claude/goofy-keller-75d680

flcarre commented Jun 24, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

flcarre commented Jun 24, 2026

Uh oh!

tchiotludo commented Jun 24, 2026

Uh oh!

Piyush-r-bhaskar left a comment •

edited

Loading

Uh oh!

flcarre commented Jul 21, 2026

Uh oh!

Piyush-r-bhaskar commented Jul 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

flcarre commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What & why

Changes

How it was verified

Notes

Uh oh!

github-actions Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📄 OpenAPI Spec Changes

🐋 Docker image

Uh oh!

flcarre commented Jun 24, 2026

Uh oh!

tchiotludo commented Jun 24, 2026

Uh oh!

Piyush-r-bhaskar left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

flcarre commented Jul 21, 2026

Uh oh!

Piyush-r-bhaskar commented Jul 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

flcarre commented Jun 24, 2026 •

edited

Loading

github-actions Bot commented Jun 24, 2026 •

edited

Loading

Piyush-r-bhaskar left a comment •

edited

Loading