From 260c4cd0bbe327c6139cef6dfadf6f5cef5dcc25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?He=CC=84sperus?= Date: Sat, 31 Jan 2026 00:32:53 +0800 Subject: [PATCH 1/4] dev(all): refurbish architecture and add inertial support - refactor the types and architecture to support augmentation and implement more decent options definition - implement `lubricator` that enables inertial interaction - update tests - other minor improvements - update docs to make it more readable (not fully finished). --- .github/dependabot.yml | 16 +- .github/workflows/ci-main.yml | 146 +-- .github/workflows/ci-pr.yml | 90 +- .github/workflows/publish.yml | 48 +- .oxfmtrc.json | 10 +- .oxlintrc.json | 22 +- README.md | 20 +- docs/.vitepress/config.ts | 3 +- docs/components/playground.vue | 54 +- docs/en/development/custom-modules.md | 14 +- docs/en/development/testing.md | 6 +- docs/en/get-started.md | 17 +- docs/en/index.md | 57 +- docs/en/whats-pointeract.md | 30 +- .../{chaoticTest.svg => monkeyTest.svg} | 0 docs/public/robots.txt | 5 +- package.json | 24 +- pnpm-lock.yaml | 994 +++++++++--------- src/baseModule.ts | 90 +- src/declarations.ts | 63 +- src/index.ts | 17 +- src/modules/click.ts | 29 +- src/modules/drag.ts | 8 +- src/modules/lubricator.ts | 168 +++ src/modules/multitouchPanZoom.ts | 26 +- src/modules/preventDefault.ts | 12 +- src/modules/wheelPanZoom.ts | 42 +- src/pointeract.ts | 113 +- src/utils.ts | 13 + tests/dev/script.ts | 28 +- tests/integration.test.ts | 37 +- tests/lubricate.test.ts | 43 + tests/mockRect.ts | 32 - tests/testUtils.ts | 79 +- vite.config.ts | 2 +- 35 files changed, 1349 insertions(+), 1009 deletions(-) rename docs/public/{chaoticTest.svg => monkeyTest.svg} (100%) create mode 100644 src/modules/lubricator.ts create mode 100644 src/utils.ts create mode 100644 tests/lubricate.test.ts delete mode 100644 tests/mockRect.ts diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 6de8c1a..12566c2 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,10 +1,10 @@ version: 2 updates: - - package-ecosystem: 'npm' - directory: '/' - schedule: - interval: 'weekly' - groups: - all: - patterns: - - '*' + - package-ecosystem: 'npm' + directory: '/' + schedule: + interval: 'weekly' + groups: + all: + patterns: + - '*' diff --git a/.github/workflows/ci-main.yml b/.github/workflows/ci-main.yml index bf4763a..475fc3f 100644 --- a/.github/workflows/ci-main.yml +++ b/.github/workflows/ci-main.yml @@ -1,82 +1,82 @@ name: CI for Main on: - push: - branches: [main] + push: + branches: [main] concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true # Cancel previous runs for same PR/branch + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true # Cancel previous runs for same PR/branch permissions: - contents: read - pages: write - id-token: write + contents: read + pages: write + id-token: write jobs: - ci-main: - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@v6 - with: - fetch-depth: 0 - - - name: Set up pnpm - uses: pnpm/action-setup@v4.2.0 - - - name: Set up Node.js - uses: actions/setup-node@v6 - with: - node-version: latest - cache: 'pnpm' - - - name: Install dependencies - run: pnpm install - - - name: Detect changed roots - id: detect - run: ./.github/scripts/detect_changes.sh - - - name: Run checks - run: pnpm check - - - name: Run build - run: pnpm build - - # region Test - - name: Run coverage tests (src or test changes) - if: | - contains(steps.detect.outputs.changed_roots, 'src') || - contains(steps.detect.outputs.changed_roots, 'test') - run: pnpm test:coverage - - - name: Upload coverage reports to Codecov - if: | - contains(steps.detect.outputs.changed_roots, 'src') || - contains(steps.detect.outputs.changed_roots, 'test') - uses: codecov/codecov-action@v5 - with: - token: ${{ secrets.CODECOV_TOKEN }} - # endregion ======================================================================== - - # region Deploy Documentation - - name: Build - if: contains(steps.detect.outputs.changed_roots, 'docs') - run: pnpm docs:build - - - name: Setup Pages - if: contains(steps.detect.outputs.changed_roots, 'docs') - uses: actions/configure-pages@v5.0.0 - - - name: Upload artifact - if: contains(steps.detect.outputs.changed_roots, 'docs') - uses: actions/upload-pages-artifact@v4.0.0 - with: - path: './docs/.vitepress/dist' - - - name: Deploy to GitHub Pages - if: contains(steps.detect.outputs.changed_roots, 'docs') - uses: actions/deploy-pages@v4.0.5 - # endregion ======================================================================== + ci-main: + runs-on: ubuntu-slim + + steps: + - name: Checkout + uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - name: Set up pnpm + uses: pnpm/action-setup@v4.2.0 + + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + node-version: latest + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install + + - name: Detect changed roots + id: detect + run: ./.github/scripts/detect_changes.sh + + - name: Run checks + run: pnpm check + + - name: Run build + run: pnpm build + + # region Test + - name: Run coverage tests (src or test changes) + if: | + contains(steps.detect.outputs.changed_roots, 'src') || + contains(steps.detect.outputs.changed_roots, 'test') + run: pnpm test:coverage + + - name: Upload coverage reports to Codecov + if: | + contains(steps.detect.outputs.changed_roots, 'src') || + contains(steps.detect.outputs.changed_roots, 'test') + uses: codecov/codecov-action@v5 + with: + token: ${{ secrets.CODECOV_TOKEN }} + # endregion ======================================================================== + + # region Deploy Documentation + - name: Build + if: contains(steps.detect.outputs.changed_roots, 'docs') + run: pnpm docs:build + + - name: Setup Pages + if: contains(steps.detect.outputs.changed_roots, 'docs') + uses: actions/configure-pages@v5.0.0 + + - name: Upload artifact + if: contains(steps.detect.outputs.changed_roots, 'docs') + uses: actions/upload-pages-artifact@v4.0.0 + with: + path: './docs/.vitepress/dist' + + - name: Deploy to GitHub Pages + if: contains(steps.detect.outputs.changed_roots, 'docs') + uses: actions/deploy-pages@v4.0.5 + # endregion ======================================================================== diff --git a/.github/workflows/ci-pr.yml b/.github/workflows/ci-pr.yml index 4a0fd2e..51bd701 100644 --- a/.github/workflows/ci-pr.yml +++ b/.github/workflows/ci-pr.yml @@ -1,52 +1,52 @@ name: CI for Pull Requests on: - pull_request: - branches: [main] - types: [opened, synchronize, reopened, ready_for_review] + pull_request: + branches: [main] + types: [opened, synchronize, reopened, ready_for_review] concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true # Cancel previous runs for same PR/branch + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true # Cancel previous runs for same PR/branch jobs: - ci-pr: - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@v6 - with: - fetch-depth: 0 - - - name: Set up pnpm - uses: pnpm/action-setup@v4.2.0 - - - name: Set up Node.js - uses: actions/setup-node@v6 - with: - node-version: latest - cache: 'pnpm' - - - name: Install dependencies - run: pnpm install - - - name: Detect changed roots - id: detect - run: ./.github/scripts/detect_changes.sh - - - name: Run checks - run: pnpm check - - - name: Run build - run: pnpm build - - - name: Run tests (src or test changes) - if: | - contains(steps.detect.outputs.changed_roots, 'src') || - contains(steps.detect.outputs.changed_roots, 'test') - run: pnpm test - - - name: Run docs build (docs changes) - if: contains(steps.detect.outputs.changed_roots, 'docs') - run: pnpm docs:build + ci-pr: + runs-on: ubuntu-slim + + steps: + - name: Checkout + uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - name: Set up pnpm + uses: pnpm/action-setup@v4.2.0 + + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + node-version: latest + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install + + - name: Detect changed roots + id: detect + run: ./.github/scripts/detect_changes.sh + + - name: Run checks + run: pnpm check + + - name: Run build + run: pnpm build + + - name: Run tests (src or test changes) + if: | + contains(steps.detect.outputs.changed_roots, 'src') || + contains(steps.detect.outputs.changed_roots, 'test') + run: pnpm test + + - name: Run docs build (docs changes) + if: contains(steps.detect.outputs.changed_roots, 'docs') + run: pnpm docs:build diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 6033929..9dd086e 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -1,37 +1,37 @@ name: Build and Publish to npm on: - push: - tags: - - 'v*.*.*' + push: + tags: + - 'v*.*.*' permissions: - id-token: write - contents: read + id-token: write + contents: read jobs: - build-and-publish: - runs-on: ubuntu-latest + build-and-publish: + runs-on: ubuntu-slim - steps: - - name: Checkout code - uses: actions/checkout@v6 + steps: + - name: Checkout code + uses: actions/checkout@v6 - - name: Set up pnpm - uses: pnpm/action-setup@v4.2.0 + - name: Set up pnpm + uses: pnpm/action-setup@v4.2.0 - - name: Set up Node.js - uses: actions/setup-node@v6 - with: - node-version: latest - registry-url: 'https://registry.npmjs.org' - cache: 'pnpm' + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + node-version: latest + registry-url: 'https://registry.npmjs.org' + cache: 'pnpm' - - name: Install dependencies - run: pnpm install + - name: Install dependencies + run: pnpm install - - name: Build - run: pnpm build + - name: Build + run: pnpm build - - name: Publish to npm - run: pnpm publish --no-git-checks + - name: Publish to npm + run: pnpm publish --no-git-checks diff --git a/.oxfmtrc.json b/.oxfmtrc.json index af8250d..72b3864 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -14,5 +14,13 @@ ["sibling", "sibling-type"], ["index", "index-type"] ] - } + }, + "overrides": [ + { + "files": ["*.md", "*.yaml", "*.yml"], + "options": { + "tabWidth": 2 + } + } + ] } diff --git a/.oxlintrc.json b/.oxlintrc.json index f60e904..b9b43a2 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -77,6 +77,8 @@ "typescript/no-extra-non-null-assertion": "warn", "typescript/no-floating-promises": "warn", "typescript/no-for-in-array": "warn", + "typescript/no-non-null-assertion": "warn", + "typescript/no-explicit-any": "warn", "typescript/no-implied-eval": "warn", "typescript/no-meaningless-void-operator": "warn", "typescript/no-misused-new": "warn", @@ -108,26 +110,6 @@ "unicorn/prefer-set-size": "warn", "unicorn/prefer-string-starts-ends-with": "warn" }, - "settings": { - "jsdoc": { - "ignorePrivate": false, - "ignoreInternal": false, - "ignoreReplacesDocs": true, - "overrideReplacesDocs": true, - "augmentsExtendsReplacesDocs": false, - "implementsReplacesDocs": false, - "exemptDestructuredRootsFromChecks": false, - "tagNamePreference": {} - }, - "vitest": { - "typecheck": false - }, - "plugins": ["typescript"], - "rules": { - "typescript/no-floating-promises": "error", - "typescript/no-unsafe-assignment": "warn" - } - }, "env": { "builtin": true }, diff --git a/README.md b/README.md index 6a72e28..618230e 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ Access our documentation [in the website](https://pointeract.consensia.cc/). ## Advantages - **🐣 Tiny**: With base **1KB** minified and gzipped, **1-2KB** for normal usage. -- **πŸ’ͺ Robust**: Excels at complex gestures where most interaction libraries fail, [Why?](https://pointeract.consensia.cc/development/testing#chaotic-testing) +- **πŸ’ͺ Robust**: Excels at complex gestures where most interaction libraries fail, [Why?](https://pointeract.consensia.cc/development/testing#monkey-test) - **🧩 Extensible**: Extend Pointeract effortlessly via our module API. - **πŸ”Œ Flexible during Runtime**: Options are updated reactively. Stop/start any module during runtime. - **πŸ›‘οΈ Safe**: Not modifying the DOM (except the `PreventDefault` module). Meticulous clean up prevents memory leaks. @@ -108,15 +108,15 @@ Missing your desired interaction? [Write your own module](https://pointeract.con There're already plenty of interaction libraries out there, most famous ones are `Interact.js` and `Hammer.js`, but Pointeract is different. -| Criteria | Pointeract | [Hammer.js](https://hammerjs.github.io) | [Interact.js](https://interactjs.io) | -| :------------------------------------------------------------------------------------------- | :---------------------------------------------------: | :----------------------------------------------: | :-------------------------------------------------: | -| Written in TypeScript? | βœ… | ❌ | βœ… | -| Tree-shakeable? | [βœ…](https://bundlephobia.com/package/pointeract) | [❌](https://bundlephobia.com/package/hammerjs) | [❌](https://bundlephobia.com/package/interactjs) | -| Bundle Size (Minified + Gzipped) | πŸ‘‘ [2KB](https://bundlephobia.com/package/pointeract) | [7KB](https://bundlephobia.com/package/hammerjs) | [28KB](https://bundlephobia.com/package/interactjs) | -| Last Updated | πŸ‘‘ Actively Maintained | 2015 | 2023 | -| Features | Pointer and Wheel Related | Pointer Related | πŸ‘‘ Pointer and Wheel Related + Comprehensive Utils | -| Robust? (See [Testing](https://pointeract.consensia.cc/development/testing#chaotic-testing)) | βœ… | ❌ Element Jerks | ❌ Element Ignores the Second Touch | -| Extensible? | βœ… | ❌ | ❌ | +| Criteria | Pointeract | [Hammer.js](https://hammerjs.github.io) | [Interact.js](https://interactjs.io) | +| :--------------------------------------------------------------------------------------- | :---------------------------------------------------: | :----------------------------------------------: | :-------------------------------------------------: | +| Written in TypeScript? | βœ… | ❌ | βœ… | +| Tree-shakeable? | [βœ…](https://bundlephobia.com/package/pointeract) | [❌](https://bundlephobia.com/package/hammerjs) | [❌](https://bundlephobia.com/package/interactjs) | +| Bundle Size (Minified + Gzipped) | πŸ‘‘ [2KB](https://bundlephobia.com/package/pointeract) | [7KB](https://bundlephobia.com/package/hammerjs) | [28KB](https://bundlephobia.com/package/interactjs) | +| Last Updated | πŸ‘‘ Actively Maintained | 2015 | 2023 | +| Features | Pointer and Wheel Related | Pointer Related | πŸ‘‘ Pointer and Wheel Related + Comprehensive Utils | +| Robust? (See [Testing](https://pointeract.consensia.cc/development/testing#monkey-test)) | βœ… | ❌ Element Jerks | ❌ Element Ignores the Second Touch | +| Extensible? | βœ… | ❌ | ❌ | ## Get Involved diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index d5a6342..26301be 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -20,7 +20,8 @@ export default defineConfig({ 'meta', { name: 'keywords', - content: 'user interaction,pan zoom,multitouch,custom modules,modern lightweight', + content: + 'user interaction,pan zoom,multitouch,custom modules,gestures,javascript,typescript,pointeract', }, ], ], diff --git a/docs/components/playground.vue b/docs/components/playground.vue index c1a5629..6697ec8 100644 --- a/docs/components/playground.vue +++ b/docs/components/playground.vue @@ -11,8 +11,20 @@