Add unit tests, modernize tooling and release 7.0.0 (ESM output)

.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      devDependencies:
+        dependency-type: "development"
+    open-pull-requests-limit: 3
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

.github/workflows/build.yml

@@ -1,6 +1,3 @@
-# This workflow will do a clean installation of node dependencies, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
 name: build
 
 on:
@@ -9,26 +6,32 @@ on:
   pull_request:
     branches: [ main ]
 
+permissions:
+  contents: read
+
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x]
+        node-version: [20.x, 22.x]
+
+    env:
+      CI: true
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
       with:
         node-version: ${{ matrix.node-version }}
-    - run: npm audit
-      continue-on-error: true
+        cache: 'npm'
     - run: npm ci
-    - run: npm outdated
-      continue-on-error: true
+    # Scoped to shipped dependencies so a devDependency advisory cannot red-build unrelated PRs.
+    - run: npm audit --audit-level=high --omit=dev
     - run: npm run lint
-      env:
-        CI: true
+    - run: npm run test:typecheck
+    - run: npx playwright install --with-deps chromium
+    - run: npm run test:coverage
+    - run: npm run build

.github/workflows/codeql-analysis.yml

@@ -2,9 +2,9 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev, certification]
   pull_request:
-    branches: [main]
+    branches: [main, dev, certification]
   schedule:
     - cron: '0 0 * * 3'
 
@@ -25,25 +25,25 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
       with:
         fetch-depth: 2
 
-    - name: Use Node.js 18
-      uses: actions/setup-node@v2
+    - name: Use Node.js 20
+      uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
       with:
-        node-version: 18.x
+        node-version: 20.x
 
     - name: Install Dependencies
       run: npm ci
 
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@6f5948dfacef28e207b48d0905cf90c03365536d # v3.37.9
       with:
         languages: ${{ matrix.language }}
 
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v3
+      uses: github/codeql-action/autobuild@6f5948dfacef28e207b48d0905cf90c03365536d # v3.37.9
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@6f5948dfacef28e207b48d0905cf90c03365536d # v3.37.9

.github/workflows/release.yml

@@ -1,35 +1,57 @@
-name: build
+name: release
 
 on:
   release:
-    types: [created]
+    types: [ created ]
+
+permissions:
+  contents: write
 
 jobs:
   build:
     environment: automated-release
     runs-on: ubuntu-latest
-    env: 
-      GH_TOKEN: ${{secrets.GH_TOKEN}}
+
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
     steps:
-    - uses: actions/checkout@v4
+    - name: Checkout repository
+      uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+
+    - name: Use Node.js 20
+      uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
       with:
-        ref: ${{ vars.BRANCH_NAME }}
-    - name: Add config details
-      run: |
-        git config --global user.name ${{secrets.NAME}}
-        git config --global user.email ${{secrets.EMAIL}}
+        node-version: 20.x
+        cache: 'npm'
+
     - name: Move release to draft
-      run: gh release edit $TAG_NAME --draft=true
+      run: gh release edit "$TAG_NAME" --draft=true
       env:
         TAG_NAME: ${{ github.event.release.tag_name }}
-    - name: Run npm install, build and test
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Lint
+      run: npm run lint
+
+    - name: Build
+      run: npm run build
+
+    - name: Install Playwright browser
+      run: npx playwright install --with-deps chromium
+
+    - name: Test
+      run: npm test
+
+    - name: Create release archive
       run: |
-        npm i
-        npm run build
-    - run: zip -r lib.zip . -x '.*' 'node_modules/*' 'src/*' 'spec/*'
+        zip -r lib.zip lib *.md LICENSE package.json package-lock.json
+
     - name: Upload production artifacts
       run: |
-        gh release upload $TAG_NAME "lib.zip#build"
-        gh release edit $TAG_NAME --draft=false
+        gh release upload "$TAG_NAME" "lib.zip"
+        gh release edit "$TAG_NAME" --draft=false
       env:
-        TAG_NAME: ${{ github.event.release.tag_name }}
+        TAG_NAME: ${{ github.event.release.tag_name }}

.gitignore

@@ -1,4 +1,8 @@
+.DS_Store
 .vs/
 node_modules/
 dist/
-lib/
+lib/
+coverage/
+.tmp/
+*.log

CHANGELOG.md

@@ -1,3 +1,25 @@
+## 7.0.0
+### Breaking changes
+* the package is published as ES2020 modules instead of CommonJS, in line with the other `powerbi-visuals-utils-*` v7 packages
+* `powerbi-visuals-api` moved to `devDependencies`: it is no longer installed transitively and has to be declared by the visual
+* `HtmlSubSelectionHelper.getDataForElement` is now typed as `SubSelectionElementData | null`, matching what it returns for elements without the data attribute: consumers on `strictNullChecks` have to handle the `null` case
+* `ISubSelectionHelper.getAllSubSelectables` takes a new optional `filterType` parameter: existing implementations outside this repo still compile, but they silently ignore the filter and return every sub-selectable until they are updated
+
+### Fixed
+* `createVisualSubSelectionForSingleObject` did not anchor the selection origin for `NumericText` and wrongly anchored it for `None`: the sub-selection type was matched with `in`, which checks array indices instead of values
+* `getAllSubSelectables` ignored the filter when it was `SubSelectionStylesType.None` and returned every sub-selectable instead: the member is `0`, so it did not pass the truthiness check the filter was guarded with
+* the sub-selection type of an element whose `data-sub-selection-type` attribute is missing or not a known member now falls back to `SubSelectionStylesType.None`, instead of putting `undefined` or `NaN` into the `subSelectionType` of the emitted sub-selection
+* added the missing `typescript` dev dependency
+
+### Other changes
+* `isArrayEmpty` is now generic and returns a type predicate (`array is undefined | null | []`) instead of taking `any[]` and returning `boolean`: existing calls still compile, but the argument is no longer inferred as `any` and the result now narrows the array at the call site
+* the published package is limited to `lib` and the docs via the `files` field, instead of relying on the ignore rules
+* unit tests migrated to Vitest 4 and run in Chromium via `@vitest/browser` and Playwright, so the outline geometry is validated against real browser layout instead of a stubbed `getBoundingClientRect`
+* ESLint migrated to the flat config, updated to ESLint 9 and typescript-eslint 8
+* `strict` mode enabled
+* new scripts: `prebuild`, `prepublishOnly`, `test:typecheck`, `lint:fix`
+* CI runs audit, lint, typecheck, tests and build on Node 20 and 22; added Dependabot
+
 ## 6.0.2
 * powerbi-visuals-api updated to 5.9.0
 * added codeql.yml and build.yml

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# How to contribute
+If you would like to contribute to the Power BI visuals OnObjectUtils there are many ways you can help.
+
+## Reporting issues
+We use [GitHub issues](https://github.com/Microsoft/powerbi-visuals-utils-onobjectutils/issues) as an issue tracker for the repository. Firstly, please search in open issues and try to make sure your problem doesn't exist. If there is an issue, add your comments to this issue.
+If there are no issues yet, please open a new one.
+
+## Contributing Code
+Before submitting a pull request please make sure the following is done:
+
+1. Fork [the repository](https://github.com/Microsoft/powerbi-visuals-utils-onobjectutils)
+2. Create a branch from `main`
+3. Install the dependencies: `npm ci`
+4. Ensure that the code style checks are passed: `npm run lint`
+5. Ensure that the types are valid: `npm run test:typecheck`
+6. Ensure that the unit tests are passed: `npm run test:coverage`
+7. Ensure that the package builds: `npm run build`
+8. Complete the [CLA](#contributor-license-agreement-cla)
+
+### Code of Conduct
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+### Contributor License Agreement (CLA)
+You will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you are granting us permission to use the submitted change according to the terms of the project's license, and that the work being submitted is under appropriate copyright.
+
+Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit [https://cla.microsoft.com](https://cla.microsoft.com) to sign digitally. Be sure to include your github user name along with the agreement. Once we have received the signed CLA, we'll review the request.

README.md

@@ -4,6 +4,13 @@ Run the following command to install the util:
     npm i powerbi-visuals-utils-onobjectutils
 ```
 
+Starting with 7.0.0 the visual has to declare `powerbi-visuals-api` itself. It is no longer installed as a transitive dependency, and the published typings import from it, so the types will not resolve without it:
+```cmd
+    npm i -D powerbi-visuals-api@^5.11.1
+```
+
+The package is also published as ES2020 modules instead of CommonJS, so it has to be consumed from a build that supports ES modules; `require()` no longer resolves it.
+
 # On-object utils
 
 The `HTMLSubSelectionHelper` provides an easy way for your Power BI custom visual to emit subselections to Power BI, get and render outlines.

eslint.config.mjs

@@ -0,0 +1,27 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import powerbiVisualsPlugin from "eslint-plugin-powerbi-visuals";
+
+export default [
+    {
+        ignores: [
+            "node_modules/**",
+            "dist/**",
+            "coverage/**",
+            "lib/**",
+            ".tmp/**",
+            "eslint.config.mjs"
+        ]
+    },
+    js.configs.recommended,
+    ...tseslint.configs.recommended,
+    powerbiVisualsPlugin.configs.recommended,
+    {
+        files: ["**/*.ts", "**/*.mts"],
+        rules: {
+            "@typescript-eslint/explicit-module-boundary-types": "off",
+            "@typescript-eslint/no-explicit-any": "off",
+            "@typescript-eslint/no-inferrable-types": "off"
+        }
+    }
+];