vaadin · web-padawan · Aug 12, 2025 · Jul 25, 2025 · Jul 25, 2025 · Aug 8, 2025
diff --git a/.gitignore b/.gitignore
@@ -38,3 +38,7 @@ scripts/check-releases.html
 
 # TypeScript output
 tsconfig.build.tsbuildinfo
+
+# API docs generated files
+api-docs/dist
+api-docs/content/elements
diff --git a/api-docs/.eleventy.js b/api-docs/.eleventy.js
@@ -0,0 +1,75 @@
+import syntaxHighlightPlugin from '@11ty/eleventy-plugin-syntaxhighlight';
+import markdownIt from 'markdown-it';
+import markdownItAnchor from 'markdown-it-anchor';
+import { parse } from 'node-html-parser';
+
+export default function (config) {
+  // See https://www.11ty.dev/docs/config/
+  config.setInputDirectory('content');
+  config.setOutputDirectory('dist');
+  config.setDataDirectory('../_data');
+  config.setIncludesDirectory('../_includes');
+
+  // See https://www.11ty.dev/docs/languages/markdown/
+  config.setLibrary(
+    'md',
+    markdownIt({
+      html: true,
+      linkify: true,
+    }).use(markdownItAnchor, {
+      slugify: config.getFilter('slugify'),
+      level: [1, 2, 3, 4],
+      permalink: markdownItAnchor.permalink.ariaHidden({
+        placement: 'after',
+        class: 'anchor-link',
+        symbol: '#',
+      }),
+    }),
+  );
+
+  config.addPlugin(syntaxHighlightPlugin, {
+    preAttributes: {
+      class: ({ language }) => `code-block language-${language}`,
+    },
+  });
+
+  config.addPassthroughCopy('css');
+  config.addPassthroughCopy('js');
+  config.addPassthroughCopy({ img: '/' });
+
+  // Copy markdown files for "view as MD"
+  config.addPassthroughCopy({ 'content/elements': 'markdown' });
+
+  config.addCollection('elements', (api) => {
+    return api.getFilteredByGlob('./content/elements/*.md').sort((a, b) => {
+      return a.data.title.localeCompare(b.data.title);
+    });
+  });
+
+  // Table of contents
+  config.addFilter('toc', (content) => {
+    const html = parse(content);
+    const headings = html.querySelectorAll('h1, h2, h3, h4');
+    const toc = headings.map((heading) => {
+      // Remove anchor links
+      heading.querySelectorAll('[aria-hidden=true]').forEach((el) => el.remove());
+
+      const id = heading.attributes.id;
+      const text = heading.innerText;
+      const level = parseInt(heading.tagName.replace('H', ''), 10);
+
+      return { id, text, level };
+    });
+
+    // The page title already uses an h1, so it's recommended to start with h2
+    // in the content. If the first heading is an h2 or higher, we'll adjust the
+    // levels to start with level 1 to avoid unnecessary indentation in the TOC.
+    const minLevel = Math.min(...toc.map((item) => item.level));
+    if (minLevel > 1)
+      toc.forEach((item) => {
+        item.level -= minLevel - 1;
+      });
+
+    return toc;
+  });
+}
diff --git a/api-docs/_data/metadata.json b/api-docs/_data/metadata.json
@@ -0,0 +1,4 @@
+{
+  "title": "Vaadin WC API reference",
+  "description": "Vaadin web components API documentation"
+}
diff --git a/api-docs/_includes/layout.njk b/api-docs/_includes/layout.njk
@@ -0,0 +1,57 @@
+---
+toc: true
+---
+
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="description" content="{{ description or metadata.description }}" />
+  <title>{{ title or metadata.title }}</title>
+  <meta name="generator" content="{{ eleventy.generator }}" />
+  <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" />
+  <link href="/css/index.css" rel="stylesheet" />
+</head>
+
+<body>
+  <div class="app-layout">
+    {% include "partials/header.njk" %}
+
+    <div class="app-layout__wrapper">
+      {% include "partials/navigation.njk" %}
+
+      <div class="app-layout__content">
+        <div class="page">
+          <main class="page__main">
+            <article>
+              <div class="page__header">
+              <h1 class="page__title">
+                {{ title }}
+              </h1>
+
+              {% if toc %}
+                {% include "partials/actions.njk" %}
+              {% endif %}
+              </div>
+
+              <div class="article">
+                {{ content | safe }}
+              </div>
+            </article>
+          </main>
+
+          {% if toc %}
+            <div class="page__panel">
+              {% include 'partials/toc.njk' %}
+            </div>
+          {% endif %}
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <script src="/js/copy-code.js"></script>
+  <script src="/js/copy-markdown.js"></script>
+</body>
+</html>
diff --git a/api-docs/_includes/partials/actions.njk b/api-docs/_includes/partials/actions.njk
@@ -0,0 +1,20 @@
+<div class="actions">
+  <button id="copy-markdown" class="actions__btn">
+    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M3 5m0 2a2 2 0 0 1 2 -2h14a2 2 0 0 1 2 2v10a2 2 0 0 1 -2 2h-14a2 2 0 0 1 -2 -2z" />
+      <path d="M7 15v-6l2 2l2 -2v6" />
+      <path d="M14 13l2 2l2 -2m-2 2v-6" />
+    </svg>
+    <span>Copy as MD</span>
+  </button>
+  <a class="actions__btn" href="/markdown/{{ element | slugify }}.md" target="_blank">
+    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M12 6h-6a2 2 0 0 0 -2 2v10a2 2 0 0 0 2 2h10a2 2 0 0 0 2 -2v-6" />
+      <path d="M11 13l9 -9" />
+      <path d="M15 4h5v5" />
+    </svg>
+    <span>View as MD</span>
+  </a>
+</div>
diff --git a/api-docs/_includes/partials/header.njk b/api-docs/_includes/partials/header.njk
@@ -0,0 +1,12 @@
+<header class="app-header">
+
+  <label for="navigation" class="icon-btn">
+    <svg xmlns="http://www.w3.org/2000/svg" width="1.125em" height="1.125em" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <path d="M4 12h16"></path><path d="M4 18h16"></path><path d="M4 6h16"></path>
+    </svg>
+  </label>
+
+  <a href="/" class="app-header__title">
+    {{ metadata.title }}
+  </a>
+</header>
diff --git a/api-docs/_includes/partials/navigation.njk b/api-docs/_includes/partials/navigation.njk
@@ -0,0 +1,21 @@
+<input type="checkbox" name="navigation" id="navigation" class="visually-hidden" />
+
+<div class="app-layout__sidebar">
+  <div class="app-layout__sidebar-inner">
+
+    <nav class="nav-section">
+      <h3 class="nav-section__title">
+        Elements
+      </h3>
+      <ul role="list" class="nav-list">
+        {% for doc in collections.elements  %}
+          <li>
+            <a href="{{ doc.url }}" class="nav-list__link">
+              {{ doc.data.title }}
+            </a>
+          </li>
+        {% endfor %}
+      </ul>
+    </nav>
+  </div>
+</div>
diff --git a/api-docs/_includes/partials/toc.njk b/api-docs/_includes/partials/toc.njk
@@ -0,0 +1,19 @@
+<aside>
+  {% set toc = content | toc %}
+  {% if (toc | length) %}
+  <div class="toc">
+    <h2 class="toc__label" id="app-panel-toc">
+      On this page
+    </h2>
+    <ul class="toc__list" role="list" aria-labelledby="app-panel-toc">
+      {% for item in toc %}
+      <li style="--level: {{ item.level }}" class="toc__item">
+        <a href="#{{ item.id }}" class="toc__link">
+          {{ item.text | safe }}
+        </a>
+      </li>
+      {% endfor %}
+    </ul>
+  </div>
+  {% endif %}
+</aside>
diff --git a/api-docs/content/content.json b/api-docs/content/content.json
@@ -0,0 +1,3 @@
+{
+  "layout": "layout.njk"
+}
diff --git a/api-docs/content/index.md b/api-docs/content/index.md
@@ -0,0 +1,13 @@
+---
+title: Vaadin WC API Reference
+permalink: /
+toc: false
+---
+
+This is the API reference for the Vaadin Web Components. It contains information about the elements, their properties, methods, and events.
+
+This reference is intended for developers using either the plain Web Components, or their React wrappers, with either Javascript or TypeScript.
+
+The API documentation is generated from JSDoc annotations in the components source files. If you want to contribute to the documentation, please check corresponding packages.
+
+For the full component documentation, including examples and guides, please refer to the [Vaadin Components documentation](https://vaadin.com/docs/latest/components).