Merge branch 'learningequality:develop' into main

.eslintrc.js

@@ -25,4 +25,14 @@ esLintConfig.settings['import/resolver'].nuxt = {
   nuxtSrcDir: 'docs',
 };
 
+// Remove linting errors for the globals defined in the jest-puppeteer package and testUtils
+esLintConfig.globals = {
+  ...esLintConfig.globals,
+  page: true,
+  browser: true,
+  context: true,
+  puppeteerConfig: true,
+  jestPuppeteer: true,
+};
+
 module.exports = esLintConfig;

.github/githubUtils.js

@@ -1,5 +1,44 @@
 const GithubAPI = require('./GithubAPI');
 
+async function generateComment(percyUrl) {
+  return `
+### Percy Visual Test Results
+
+**Percy Dashboard:** [View Detailed Report](${percyUrl})
+
+**Environment:**
+- **Node.js Version:** 18.x
+- **OS:** Ubuntu-latest
+
+**Instructions for Reviewers:**
+- Click on the [Percy Dashboard](${percyUrl}) link to view detailed visual diffs.
+- Review the visual changes highlighted in the report.
+- Approve or request changes based on the visual differences.
+`;
+}
+
+async function findComment(github, context, issue_number) {
+  let comment;
+  let page = 1
+  while (!comment) {
+    const request = await github.rest.issues.listComments({
+      issue_number,
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      page,
+    })
+    const comments = request.data
+    if (!comments.length) {
+      return;
+    }
+    comment = comments.find(c => c.body && c.body.includes('### Percy Visual Test Results'));
+    if (comment) {
+      return comment.id.toString()
+    }
+    page += 1;
+  }
+}
+
 /**
  * Will synchronize the KDS Roadmap project statuses synced
  * with the Iteration backlog project items statuses. So if an issue belongs to
@@ -199,6 +238,8 @@ const updateReleasedItemsStatuses = async ({context, github, projectNumber}) =>
 
 
 module.exports = {
+  findComment,
+  generateComment,
   synchronizeProjectsStatuses,
   updateReleasedItemsStatuses,
 };

.github/workflows/visual_tests.yml

@@ -0,0 +1,109 @@
+name: Percy Visual Tests
+
+on: [pull_request_target]
+
+jobs:
+  pre_job:
+    name: Path match check
+    runs-on: ubuntu-latest
+    # Map a step output to a job output
+    outputs:
+      should_skip: ${{ steps.skip_check.outputs.should_skip }}
+    steps:
+      - id: skip_check
+        uses: fkirc/skip-duplicate-actions@master
+        with:
+          github_token: ${{ github.token }}
+          paths: '["**.vue", "**.js", "**.css", "**.scss", "yarn.lock"]'
+
+  visual_tests:
+    name: Frontend Visual Tests
+    needs: pre_job
+    if: ${{ needs.pre_job.outputs.should_skip != 'true' }}
+    runs-on: ubuntu-latest
+    environment: percy_tests
+    outputs:
+      percy_url: ${{ steps.extract-url.outputs.percy_url }}
+    steps:
+      - name: Checkout code from PR
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18.x'
+      - name: Cache Node.js modules
+        uses: actions/cache@v4
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.OS }}-node-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.OS }}-node-
+      - name: Install dependencies
+        run: |
+          yarn --frozen-lockfile
+          npm rebuild node-sass
+      - name: Download Chromium
+        run: npx puppeteer browsers install chrome
+      - name: Extract jsdocs and environment info 
+        run: yarn pregenerate
+      - name: Run visual tests
+        run: yarn test:visual 2>&1 | tee test-output.log
+        env:
+          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
+      - name: Extract Percy build URL
+        id: extract-url
+        run: |
+          url=$(grep -o 'https://percy.io/[a-zA-Z0-9/_-]*' test-output.log | tail -1)
+          echo "percy_url=$url" >> $GITHUB_OUTPUT
+    
+  comment:
+    name: Comment Percy results
+    needs: visual_tests
+    if: ${{ needs.visual_tests.result == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code from PR
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Define comment body
+        id: comment-text
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const percyUrl = "${{ needs.visual_tests.outputs.percy_url }}";
+            const utils = require('./.github/githubUtils.js');
+            return await utils.generateComment(percyUrl);
+      - name: Find existing comment
+        id: find-comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const utils = require('./.github/githubUtils.js');
+            return await utils.findComment(github, context, context.issue.number);
+      - name: Create build comment
+        if: ${{!steps.find-comment.outputs.result}}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+              github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: ${{ steps.comment-text.outputs.result }}
+              })
+      - name: Update build comment
+        if: ${{steps.find-comment.outputs.result}}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+              github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: ${{steps.find-comment.outputs.result}},
+                body: ${{ steps.comment-text.outputs.result }}
+              })

.gitignore

@@ -23,7 +23,7 @@ docs/jsdocs.js
 kolibri-design-system.iml
 
 # dev playground
-docs/pages/playground.vue
+docs/pages/playground/index.vue
 
 # env
 .envrc

.percy.yml

@@ -0,0 +1,19 @@
+version: 2
+snapshot:
+  widths:
+    - 375
+    - 1280
+  minHeight: 1024
+  percyCSS: ""
+  enableJavaScript: false #disable Javascript by default to capture initial page state without JS-driven changes
+  cliEnableJavaScript: true #enable Javascript when running Percy through CLI, for dynamic content
+  disableShadowDOM: false
+discovery:
+  allowedHostnames: []
+  disallowedHostnames: []
+  networkIdleTimeout: 100
+  captureMockedServiceWorker: false
+upload:
+  files: "**/*.{png,jpg,jpeg}"
+  ignore: ""
+  stripExtensions: false

CHANGELOG.md

@@ -7,6 +7,97 @@ Changelog is rather internal in nature. See release notes for the public overvie
 <!-- [DO NOT REMOVE-USED BY GH ACTION] PASTE CHANGELOG -->
 
 
+- [#923]
+  - **Description:** Fixes glob query in extrac api script.
+  - **Products impact:** bugfix.
+  - **Addresses:** -.
+  - **Components:** Docs.
+  - **Breaking:** no
+  - **Impacts a11y:** no
+  - **Guidance:** .
+
+[#923]: https://github.com/learningequality/kolibri-design-system/pull/923
+
+
+
+- [#922]
+  - **Description:** Fixes playground path in dev docs and gitignore
+  - **Products impact:** internal docs.
+  - **Addresses:** -.
+  - **Components:** -.
+  - **Breaking:** -
+  - **Impacts a11y:** -
+  - **Guidance:** -.
+
+[#922]: https://github.com/learningequality/kolibri-design-system/pull/922
+
+
+
+- [#873]
+  - **Description:**  Implemented `DocsExample` component with toggle functionality for switching between an example and its code snippet in the KDS documentation.
+  - **Products impact:** none
+  - **Addresses:** https://github.com/learningequality/kolibri-design-system/issues/826
+  - **Components:** -
+  - **Breaking:** no
+  - **Impacts a11y:** no
+  - **Guidance:** -
+
+[#873]: https://github.com/learningequality/kolibri-design-system/pull/873
+
+
+
+- [#916]
+  - **Description:** Fixes the no usable sandbox error observed in visual test workflow after merging of visual testing PR.
+  - **Products impact:** bugfix
+  - **Addresses:** -
+  - **Components:** -
+  - **Breaking:** -
+  - **Impacts a11y:** -
+  - **Guidance:** -
+
+[#916]: https://github.com/learningequality/kolibri-design-system/pull/916
+
+
+
+- [#901]
+  - **Description:** Integrates visual testing setup to KDS.
+  - **Products impact:** -
+  - **Addresses:** -
+  - **Components:** -
+  - **Breaking:** -
+  - **Impacts a11y:** -
+  - **Guidance:** -
+
+[#901]: https://github.com/learningequality/kolibri-design-system/pull/901
+
+
+
+- [#804]
+  - **Description:** Refactored `handleKeydown` method into smaller, modular methods for handling different key events. Ensured that the `Tab` key mimics the functionality of the `ArrowRight` key, and the `Shift+Tab` key mimics the functionality of the `ArrowLeft` key. \
+  - **Products impact:** none
+  - **Addresses:** #795
+  - **Components:** `KTable `
+  - **Breaking:** no
+  - **Impacts a11y:** yes
+  - **Guidance:** No special guidance required for consumers.
+
+[#804]: https://github.com/learningequality/kolibri-design-system/pull/804
+
+
+
+- [#870]
+  - **Description:** remove text truncation for the download button
+  - **Products impact:** Choose from - none
+  - **Addresses:** https://github.com/learningequality/kolibri/issues/5557
+  - **Components:** KDropdownMenu,UiMenu
+  - **Breaking:** no
+  - **Impacts a11y:** yes
+  - **Guidance:** -
+
+[#870]: https://github.com/learningequality/kolibri-design-system/pull/870
+
+
+
 - [#907]
   - **Description:** Skip sync projects job if the owner is not LearningEquality
   - **Products impact:**  -.

dev_docs/01_getting_started.md

@@ -52,6 +52,7 @@ You're now ready to code!
 - If you'd like to update the component library, continue to [How to update the component library](./03_how_to_update_library.md).
 
 The guidelines referenced above should be sufficient for the most common tasks. There are a few additional developer documentation pages available. However, these pages contain information that is more internal in nature or related to specialized tasks:
+- [Visual Testing](./07_visual_testing_guide.md)
 - [How to update the documentation website](./04_how_to_update_docs.md)
 - [Icons](./05_icons.md)
 - [Miscellaneous](./06_misc.md)

dev_docs/03_how_to_update_library.md

@@ -33,7 +33,7 @@ The documentation development server can be used to visually test components upd
 
 **Playground page**
 
-Open [/docs/pages/playground.vue](../docs/pages/playground.vue) and add a component you're working on there. Then, as you're developing, you will see it update live at http://localhost:4000/playground. See an example in the playground file.
+Open [/docs/pages/playground/index.vue](../docs/pages/playground/index.vue) and add a component you're working on there. Then, as you're developing, you will see it update live at http://localhost:4000/playground. See an example in the playground file.
 
 If you are working on a new component, make sure to register it first in `KThemePlugin` as described in the "How to add a new component" section above in order to make it available on the playground page.
 
@@ -43,7 +43,7 @@ Please do not commit any updates to the playground file as it's meant as your lo
 
 The majority of existing components have documentation pages that often show live components in different states. One example of this can be seen on the `KBreadcrumbs` component documentation page at http://localhost:4000/kbreadcrumbs. The documentation page source code is located in [`/docs/pages/kbreadcrumbs.vue`](../docs/pages/kbreadcrumbs.vue).
 
-You can find links to documentation pages for existing components on the documentation website in the "Code library components" section at the bottom of the side navigation. 
+You can find links to documentation pages for existing components on the documentation website in the "Code library components" section at the bottom of the side navigation.
 
 If there is already a documentation page for a component, please ensure that any new updates don't break examples on the page. Additionally, you may also consider adding new examples to the documentation if applicable. See [How to update the documentation website](./04_how_to_update_docs.md) to find out more about updating documentation content. You can also review existing documentation pages in the [`/docs/pages`](../docs/pages) directory to familiarize yourself with the source code for the documentation.