Merge branch 'master' into master

Author: finetjul

.github/workflows/build-test.yml

@@ -35,7 +35,7 @@ jobs:
           npx tsc -p tsconfig.esm-check.json
           npx tsc -p tsconfig.umd-check.json
       - name: Chrome and Firefox tests
-        run: xvfb-run --auto-servernum npm run test -- --browsers Chrome,Firefox
+        run: xvfb-run --auto-servernum npm run test -- --browsers ChromeSwiftShader,Firefox
       - name: Archive test results
         if: github.event_name != 'merge_group' && (success() || failure())
         uses: actions/upload-artifact@v4

.github/workflows/pr-checks.yml

@@ -24,4 +24,4 @@ jobs:
       - name: Tests must not use test.only
         run: bash .github/workflows/test-only-check.sh
       - name: API docs should generate without error
-        run: npm run doc:generate-api
+        run: npm run docs:generate-api

.github/workflows/publish.yml

@@ -26,7 +26,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Setup node
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v4
         with:
           node-version: 22
       - name: Install dependencies
@@ -42,7 +42,7 @@ jobs:
           npx tsc -p tsconfig.esm-check.json
           npx tsc -p tsconfig.umd-check.json
       - name: Chrome and Firefox tests
-        run: xvfb-run --auto-servernum npm run test -- --browsers Chrome,Firefox
+        run: xvfb-run --auto-servernum npm run test -- --browsers ChromeSwiftShader,Firefox
       - name: Archive test results
         if: always()
         uses: actions/upload-artifact@v4
@@ -53,7 +53,8 @@ jobs:
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          # No need to set NPM_TOKEN because of OIDC
+          NPM_CONFIG_PROVENANCE: true
         run: |
           git config --global user.name "Github Actions"
           git config --global user.email "sebastien.jourdain@kitware.com"
@@ -80,13 +81,21 @@ jobs:
         run: npm ci
       - name: Build
         run: npm run build:release
-      - name: Build API docs
-        run: npm run doc:generate-api
+      - name: Generate API docs
+        run: npm run docs:generate-api
+      - name: Generate docs examples
+        run: npm run docs:generate-examples
+      - name: Generate docs sidebar
+        run: npm run docs:generate-sidebar
+      - name: Generate docs gallery
+        run: npm run docs:generate-gallery
       - name: Build docs
-        run: npm run doc:minified
+        run: npm run docs:build
+      - name: Build docs examples
+        run: npm run docs:build-examples
       - name: Upload docs as a Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./Documentation/build-tmp/public/
+          path: ./Documentation/.vitepress/dist/
       - name: Deploy docs
         uses: actions/deploy-pages@v4

.gitignore

@@ -10,3 +10,8 @@ coverage/
 .env
 Utilities/TestResults
 .idea
+Documentation/.vitepress/cache/
+Documentation/.vitepress/dist/
+Documentation/build-tmp/
+Documentation/content/
+Documentation/Examples/

CONTRIBUTING.md

@@ -33,36 +33,43 @@ Please follow the coding style:
     $ git checkout -b new_feature
     ```
 
-4. Start hacking. Additional information on how to create class/test/example can be found
+6. Start hacking. Additional information on how to create class/test/example can be found
    [here](https://kitware.github.io/vtk-js/docs/) in the __Development__ section.
 
     ```sh
     $ edit file1 file2 file3
     $ git add file1 file2 file3
     ```
 
-5. Use Commitizen to create commits
+7. Verify you have correctly formatted code, and that all tests pass:
+
+    ```sh
+    $ npm run reformat
+    $ npm run test
+    ```
+
+8. Use Commitizen to create commits
 
     ```sh
     $ npm run commit
     ```
 
-6. Push commits in your feature branch to your fork in GitHub:
+9. Push commits in your feature branch to your fork in GitHub:
 
     ```sh
     $ git push origin new_feature
     ```
 
-7. Visit your fork in Github, browse to the "**Pull Requests**" link on the left, and use the 
+10. Visit your fork in Github, browse to the "**Pull Requests**" link on the left, and use the
    "**New Pull Request**" button in the upper right to create a Pull Request.
 
-    For more information see: 
+    For more information see:
     [Create a Pull Request](https://help.github.com/articles/creating-a-pull-request/)
 
 If committing changes to `vtk.js@next` or `vtk.js@next-major`, then set your base branch to be `next`
 or `next-major`, respectively. For more info see the section on release channels below.
 
-8. vtk.js uses GitHub for code review and Github Actions to validate proposed patches before they are merged.
+11. vtk.js uses GitHub for code review and Github Actions to validate proposed patches before they are merged.
 
 ## Release Channels
 
@@ -99,7 +106,7 @@ you are satisfied with the staging branch changes, you can then merge into eithe
 ## Notice
 
 - Don't modify the version number in `package.json`.
-- Your pull request will only get merged when tests passed. Don't forget to run tests before 
+- Your pull request will only get merged when tests passed. Don't forget to run tests before
   submission.
 
     ```
@@ -116,18 +123,18 @@ To create and debug a test:
 
 ## Updating Documentation
 
-The vtk.js documentation is part of the code repository and is entirely written in 
+The vtk.js documentation is part of the code repository and is entirely written in
 [markdown](https://daringfireball.net/projects/markdown/).
 
 If you create an example, please list it in the [examples landing page](Documentation/content/examples/index.md).
 
-Images and GIF videos added to the [gallery](Documentation/content/docs/gallery) must be compressed as much as possible (e.g. 432px by 300px with 50% JPEG compression). You may want to use [ezgif.com](https://ezgif.com/).
+Images and GIF videos added to the [gallery](Documentation/public/gallery) must be compressed as much as possible (e.g. 432px by 300px with 50% JPEG compression). You may want to use [ezgif.com](https://ezgif.com/).
 
 ## Reporting Issues
 
 If you encounter problems using vtk.js you may be able to find the solutions in the
-[troubleshooting docs](https://kitware.github.io/vtk-js/docs/misc_troubleshooting.html), in an 
-existing [GitHub issue](https://github.com/kitware/vtk-js/issues), or via the 
+[troubleshooting docs](https://kitware.github.io/vtk-js/docs/misc_troubleshooting.html), in an
+existing [GitHub issue](https://github.com/kitware/vtk-js/issues), or via the
 [mailing list](http://www.vtk.org/VTK/help/mailing.html).
-If you can't find the answer, please 
+If you can't find the answer, please
 [report a new issue on GitHub](https://github.com/Kitware/vtk-js/issues/new).

Documentation/.gitignore

@@ -0,0 +1,51 @@
+import { defineConfig } from 'vitepress';
+import llmstxt from 'vitepress-plugin-llms';
+import { copyOrDownloadAsMarkdownButtons } from 'vitepress-plugin-llms';
+
+import { sidebar } from './sidebar';
+import { BASE_URL, withBase } from './utils';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  base: BASE_URL,
+  lang: 'en-US',
+  title: 'VTK.js ',
+  description: 'VTK.js a Visualization Toolkit for the Web',
+  lastUpdated: true,
+  ignoreDeadLinks: true,
+  srcExclude: ['**/scripts/**',],
+  vite: {
+    plugins: [
+      llmstxt({
+        ignoreFiles: ['examples/*', 'coverage/*', 'scripts/*'],
+      }),
+    ],
+  },
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    logo: '/logo-wide.svg',
+    siteTitle: '',
+    nav: [
+      { text: 'Docs', link: '/docs/' },
+      { text: 'API', link: '/api/' },
+      { text: 'Examples', link: '/examples/' },
+      { text: 'Datasets', link: 'https://kitware.github.io/vtk-js-datasets/' },
+    ],
+    sidebar: sidebar,
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/Kitware/vtk-js' },
+    ],
+    outline: 'deep',
+    search: {
+      provider: 'local',
+    },
+    footer: {
+      copyright: `© ${new Date().getFullYear()} <a href="https://www.kitware.com/" target="_blank">Kitware Inc</a>.`,
+    },
+  },
+  markdown: {
+    config(md) {
+      md.use(copyOrDownloadAsMarkdownButtons);
+    },
+  },
+});

Documentation/.vitepress/config.mts

@@ -0,0 +1,150 @@
+<template>
+  <div class="examples-page">
+    <h2>Examples Gallery</h2>
+    <div class="examples-controls">
+      <input v-model="search" placeholder="Search examples..." />
+      <div class="category-buttons">
+        <button :class="{ selected: !selectedCategory }" @click="selectedCategory = ''">All Categories</button>
+        <button v-for="cat in categories" :key="cat" :class="{ selected: selectedCategory === cat }"
+          @click="selectedCategory = cat">{{ cat }}</button>
+      </div>
+    </div>
+    <div class="examples-list">
+      <div v-for="ex in filteredExamples" :key="ex.title" class="example-card">
+        <a :href="withBase(`/examples/${ex.link}`)" :title="ex.title">
+          <img :src="withBase(`/${ex.image}`)" :alt="ex.title" />
+          <h3>{{ ex.title }}</h3>
+          <p class="category">{{ ex.category }}</p>
+        </a>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { withBase } from 'vitepress'
+import { ref, computed } from 'vue'
+import examples from '../../../examples/gallery.js'
+
+const search = ref('')
+const selectedCategory = ref('')
+
+const categories = computed(() =>
+  Array.from(new Set(examples.map(e => e.category))).sort()
+)
+
+const filteredExamples = computed(() => {
+  return examples.filter(ex => {
+    const matchesSearch = ex.title.toLowerCase().includes(search.value.toLowerCase())
+    const matchesCategory = !selectedCategory.value || ex.category === selectedCategory.value
+    return matchesSearch && matchesCategory
+  })
+})
+</script>
+
+<style scoped>
+.examples-page {
+  display: flex;
+  justify-content: space-between;
+  margin: 0 auto;
+  padding-top: calc(var(--spacing) * 24);
+  padding-bottom: calc(var(--spacing) * 12);
+  gap: calc(var(--spacing) * 8);
+  max-width: calc(var(--vp-layout-max-width) - 64px);
+  flex-direction: column;
+  align-items: center;
+}
+
+.examples-page h2 {
+  font-size: 2rem;
+  margin-bottom: 1.5rem;
+}
+
+.examples-controls input {
+  padding: 0.3em 1.2em;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: calc(var(--radius));
+  font-size: 1em;
+  width: 400px;
+}
+
+.examples-controls input::placeholder {
+  color: #aaa;
+}
+
+.examples-controls {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+  margin-bottom: 1.5rem;
+  justify-content: center;
+  align-items: center;
+}
+
+.category-buttons {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  align-content: center;
+  justify-content: center;
+}
+
+.category-buttons button {
+  padding: 0.2em 1em;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 0.375rem;
+  cursor: pointer;
+  font-size: 0.875rem;
+  font-weight: 500;
+  transition: all 0.2s;
+}
+
+.category-buttons button:hover {
+  background-color: color-mix(in oklab, var(--primary) 90%, transparent);
+  color: var(--primary-foreground);
+}
+
+.category-buttons button.selected {
+  background-color: color-mix(in oklab, var(--primary) 90%, transparent);
+  color: var(--primary-foreground);
+}
+
+.examples-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1.5rem;
+  flex-direction: row;
+  justify-content: center;
+  align-items: center;
+}
+
+.example-card {
+  width: 250px;
+  overflow: hidden;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 0.375rem;
+}
+
+.example-card:hover {
+  border-color: var(--vp-c-brand-1);
+}
+
+.example-card img {
+  width: 100%;
+  height: 140px;
+  object-fit: cover;
+}
+
+.example-card h3 {
+  margin: 0.5rem;
+  font-size: 1.1rem;
+  text-overflow: ellipsis;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.example-card .category {
+  margin: 0.5rem;
+  font-size: 0.9rem;
+}
+</style>

Documentation/.vitepress/sidebar.ts

@@ -0,0 +1,20 @@
+// https://vitepress.dev/guide/custom-theme
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import googleAnalytics from "vitepress-plugin-google-analytics";
+import CopyOrDownloadAsMarkdownButtons from 'vitepress-plugin-llms/vitepress-components/CopyOrDownloadAsMarkdownButtons.vue'
+
+import ExamplesGallery from './components/ExamplesGallery.vue'
+
+import './styles/index.css'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app, router, siteData }) {
+    app.component('ExamplesGallery', ExamplesGallery),
+    app.component('CopyOrDownloadAsMarkdownButtons', CopyOrDownloadAsMarkdownButtons)
+    googleAnalytics({
+      id: "G-5XH2Z0Y9LQ",
+    });
+  }
+} satisfies Theme