+Redirecting to API Documentation...
+ + + EOF + fi + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./deploy + keep_files: true + commit_message: 'Deploy documentation from ${{ github.sha }}' diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml new file mode 100644 index 000000000..f12eb5f5a --- /dev/null +++ b/.github/workflows/sync-docs.yml @@ -0,0 +1,111 @@ +name: Sync Documentation to gh-pages + +on: + push: + branches: [master, develop] + paths: + - 'doc/html/**' + - 'angular/doc/**' + - '.github/workflows/sync-docs.yml' + workflow_dispatch: + +jobs: + sync-docs: + runs-on: ubuntu-latest + if: github.repository == 'adumesny/gridstack.js' + + steps: + - name: Checkout master branch + uses: actions/checkout@v4 + with: + ref: master + fetch-depth: 0 + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Configure Git + run: | + git config --global user.name 'github-actions[bot]' + git config --global user.email 'github-actions[bot]@users.noreply.github.com' + + - name: Check if docs exist + id: check-docs + run: | + if [ -d "doc/html" ]; then + echo "main_docs=true" >> $GITHUB_OUTPUT + else + echo "main_docs=false" >> $GITHUB_OUTPUT + fi + + if [ -d "angular/doc/api" ]; then + echo "angular_docs=true" >> $GITHUB_OUTPUT + else + echo "angular_docs=false" >> $GITHUB_OUTPUT + fi + + - name: Checkout gh-pages branch + if: steps.check-docs.outputs.main_docs == 'true' || steps.check-docs.outputs.angular_docs == 'true' + run: | + git fetch origin gh-pages + git checkout gh-pages + + - name: Sync main library documentation + if: steps.check-docs.outputs.main_docs == 'true' + run: | + echo "Syncing main library documentation..." + + # Remove existing doc/html directory if it exists + if [ -d "doc/html" ]; then + rm -rf doc/html + fi + + # Extract docs from master branch using git archive + mkdir -p doc + git archive master doc/html | tar -xf - + + # Add changes + git add doc/html + + - name: Sync Angular documentation + if: steps.check-docs.outputs.angular_docs == 'true' + run: | + echo "Syncing Angular library documentation..." + + # Remove existing Angular docs if they exist + if [ -d "angular/doc" ]; then + rm -rf angular/doc + fi + + # Extract Angular docs from master branch using git archive + git archive master angular/doc | tar -xf - + + # Add changes + git add -f angular/doc + + - name: Commit and push changes + if: steps.check-docs.outputs.main_docs == 'true' || steps.check-docs.outputs.angular_docs == 'true' + run: | + # Check if there are changes to commit + if git diff --staged --quiet; then + echo "No documentation changes to sync" + exit 0 + fi + + # Create commit message + COMMIT_MSG="📚 Auto-sync documentation from master" + if [ "${{ steps.check-docs.outputs.main_docs }}" == "true" ]; then + COMMIT_MSG="${COMMIT_MSG}%0A%0A- Updated main library HTML docs (docs/html/)" + fi + if [ "${{ steps.check-docs.outputs.angular_docs }}" == "true" ]; then + COMMIT_MSG="${COMMIT_MSG}%0A%0A- Updated Angular library docs (angular/doc/)" + fi + + COMMIT_MSG="${COMMIT_MSG}%0A%0ASource: ${{ github.sha }}" + + # Decode URL-encoded newlines for the commit message + COMMIT_MSG=$(echo -e "${COMMIT_MSG//%0A/\\n}") + + # Commit and push + git commit -m "$COMMIT_MSG" + git push origin gh-pages + + echo "✅ Documentation synced to gh-pages successfully!" diff --git a/.gitignore b/.gitignore index 95ec03ef6..1451f9e98 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,12 @@ -node_modules -bower_components -coverage *.log +*.tgz +*.zip +.npmrc +coverage +dist +dist_save +node_modules +.vscode +.idea/ +.DS_Store +doc/html/ diff --git a/.jscsrc b/.jscsrc deleted file mode 100644 index 78a426e4c..000000000 --- a/.jscsrc +++ /dev/null @@ -1,19 +0,0 @@ -{ - "preset": "node-style-guide", - "validateIndentation": 4, - "maximumLineLength": 120, - "jsDoc": { - "checkAnnotations": { - "preset": "jsdoc3", - "extra": { - "preserve": true - } - } - }, - "requireCamelCaseOrUpperCaseIdentifiers": true, - "validateLineBreaks": false, - "requireTrailingComma": false, - "disallowTrailingWhitespace": true, - "requireCapitalizedComments": false, - "excludeFiles": ["dist/*.js", "demo/*", "spec/*"] -} diff --git a/.travis.yml b/.travis.yml index f8cde4730..2aba306bf 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,31 +1,29 @@ language: node_js node_js: -- 5.7.0 -env: -- CXX=g++-4.8 +- 10.19.0 +dist: trusty +sudo: required addons: - apt: - sources: - - ubuntu-toolchain-r-test - packages: - - g++-4.8 -before_install: -- npm install -g protractor + chrome: stable +#before_install: +#- yarn global add protractor@3.3.0 +cache: + directories: + - node_modules install: -- npm install -g npm@2 -- npm install -g grunt-cli -- npm install -g bower -- bower install -- npm install -- ./node_modules/protractor/bin/webdriver-manager update --standalone -before_script: -- export CHROME_BIN=chromium-browser -- export DISPLAY=:99.0 -- sh -e /etc/init.d/xvfb start +#- yarn global add npm@6.0.1 +- yarn global add grunt-cli +#- yarn add selenium-webdriver +- yarn +#- ./node_modules/protractor/bin/webdriver-manager update --standalone +#before_script: +#- export CHROME_BIN=chromium-browser +#- export DISPLAY=:99.0 +#- sh -e /etc/init.d/xvfb start script: -- npm run build -- npm test -- grunt e2e-test +- yarn build +- yarn test +# - grunt e2e-test notifications: slack: secure: iGLGsYyVIyKVpVVCskGh/zc6Pkqe0D7jpUtbywSbnq6l5seE6bvBVqm0F2FSCIN+AIC+qal2mPEWysDVsLACm5tTEeA8NfL8dmCrAKbiFbi+gHl4mnHHCHl7ii/7UkoIIXNc5UXbgMSXRS5l8UcsSDlN8VxC5zWstbJvjeYIvbA= diff --git a/.vitestrc.coverage.ts b/.vitestrc.coverage.ts new file mode 100644 index 000000000..4c8b203dd --- /dev/null +++ b/.vitestrc.coverage.ts @@ -0,0 +1,131 @@ +///
+
-#### v0.2.3 (2015-06-23)
+# The Team
-- gridstack-extra.css
-- add support of lodash.js
-- add `is_area_empty` method
-- nested grids
-- add `batch_update`/`commit` methods
-- add `update` method
-- allow to override `resizable`/`draggable` options
-- add `disable`/`enable` methods
-- add `get_cell_from_pixel` (thanks to @juchi)
-- AMD support
-- fix nodes sorting
-- improved touch devices support
-- add `always_show_resize_handle` option
-- minor fixes and improvements
-
-#### v0.2.2 (2014-12-23)
-
-- fix grid initialization
-- add `cell_height`/`cell_width` API methods
-- fix boolean attributes (issue #31)
-
-#### v0.2.1 (2014-12-09)
-
-- add widgets locking (issue #19)
-- add `will_it_fit` API method
-- fix auto-positioning (issue #20)
-- add animation (thanks to @ishields)
-- fix `y` coordinate calculation when dragging (issue #18)
-- fix `remove_widget` (issue #16)
-- minor fixes
-
-
-#### v0.2.0 (2014-11-30)
-
-- add `height` option
-- auto-generate css rules (widgets `height` and `top`)
-- add `GridStackUI.Utils.sort` utility function
-- add `remove_all` API method
-- add `resize` and `move` API methods
-- add `resizable` and `movable` API methods
-- add `data-gs-no-move` attribute
-- add `float` option
-- fix default css rule for inner content
-- minor fixes
-
-#### v0.1.0 (2014-11-18)
-
-Very first version.
-
-
-License
-=======
-
-The MIT License (MIT)
-
-Copyright (c) 2014-2016 Pavel Reznikov, Dylan Weiss
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+gridstack.js is currently maintained by [Alain Dumesny](https://github.com/adumesny), before that [Dylan Weiss](https://github.com/radiolips), originally created by [Pavel Reznikov](https://github.com/troolee). We appreciate [all contributors](https://github.com/gridstack/gridstack.js/graphs/contributors) for help.
diff --git a/TESTING.md b/TESTING.md
new file mode 100644
index 000000000..c12398b0c
--- /dev/null
+++ b/TESTING.md
@@ -0,0 +1,208 @@
+# Testing Guide
+
+This project uses **Vitest** as the modern testing framework, replacing the previous Karma + Jasmine setup. Vitest provides faster test execution, better TypeScript support, and enhanced developer experience.
+
+## Quick Start
+
+```bash
+# Install dependencies
+yarn install
+
+# Run all tests once
+yarn test
+
+# Run tests in watch mode (development)
+yarn test:watch
+
+# Run tests with coverage
+yarn test:coverage
+
+# Open coverage report in browser
+yarn test:coverage:html
+
+# Run tests with UI interface
+yarn test:ui
+```
+
+## Testing Framework
+
+### Vitest Features
+- ⚡ **Fast**: Native ESM support and Vite's dev server
+- 🔧 **Zero Config**: Works out of the box with TypeScript
+- 🎯 **Jest Compatible**: Same API as Jest for easy migration
+- 📊 **Built-in Coverage**: V8 coverage with multiple reporters
+- 🎨 **UI Interface**: Optional web UI for test debugging
+- 🔍 **Watch Mode**: Smart re-running of affected tests
+
+### Key Changes from Karma/Jasmine
+- `function() {}` → `() => {}` (arrow functions)
+- `jasmine.objectContaining()` → `expect.objectContaining()`
+- `toThrowError()` → `toThrow()`
+- Global `describe`, `it`, `expect` without imports
+
+## Test Scripts
+
+| Command | Description |
+|---------|-------------|
+| `yarn test` | Run tests once with linting |
+| `yarn test:watch` | Run tests in watch mode |
+| `yarn test:ui` | Open Vitest UI in browser |
+| `yarn test:coverage` | Run tests with coverage report |
+| `yarn test:coverage:ui` | Coverage with UI interface |
+| `yarn test:coverage:detailed` | Detailed coverage with thresholds |
+| `yarn test:coverage:html` | Generate and open HTML coverage |
+| `yarn test:coverage:lcov` | Generate LCOV format for CI |
+| `yarn test:ci` | CI-optimized run with JUnit output |
+
+## Coverage Reports
+
+### Coverage Thresholds
+- **Global**: 85% minimum for branches, functions, lines, statements
+- **Core Files**: 90% minimum for `gridstack.ts` and `gridstack-engine.ts`
+- **Utils**: 85% minimum for `utils.ts`
+
+### Coverage Formats
+- **HTML**: Interactive browser report at `coverage/index.html`
+- **LCOV**: For integration with CI tools and code coverage services
+- **JSON**: Machine-readable format for automated processing
+- **Text**: Terminal summary output
+- **JUnit**: XML format for CI/CD pipelines
+
+### Viewing Coverage
+```bash
+# Generate and view HTML coverage report
+yarn test:coverage:html
+
+# View coverage in terminal
+yarn test:coverage
+
+# Generate LCOV for external tools
+yarn test:coverage:lcov
+```
+
+## Configuration Files
+
+- **`vitest.config.ts`**: Main Vitest configuration
+- **`vitest.setup.ts`**: Test environment setup and global mocks
+- **`.vitestrc.coverage.ts`**: Enhanced coverage configuration
+- **`tsconfig.json`**: TypeScript configuration with Vitest types
+
+## Writing Tests
+
+### Basic Test Structure
+```typescript
+import { Utils } from '../src/utils';
+
+describe('Utils', () => {
+ it('should parse boolean values correctly', () => {
+ expect(Utils.toBool(true)).toBe(true);
+ expect(Utils.toBool(false)).toBe(false);
+ expect(Utils.toBool(1)).toBe(true);
+ expect(Utils.toBool(0)).toBe(false);
+ });
+});
+```
+
+### DOM Testing
+```typescript
+describe('GridStack DOM', () => {
+ beforeEach(() => {
+ document.body.innerHTML = '';
+ });
+
+ it('should create grid element', () => {
+ const grid = document.querySelector('.grid-stack');
+ expect(grid).toBeInTheDocument();
+ });
+});
+```
+
+### Mocking
+```typescript
+// Mock a module
+vi.mock('../src/utils', () => ({
+ Utils: {
+ toBool: vi.fn()
+ }
+}));
+
+// Mock DOM APIs
+Object.defineProperty(window, 'ResizeObserver', {
+ value: vi.fn().mockImplementation(() => ({
+ observe: vi.fn(),
+ unobserve: vi.fn(),
+ disconnect: vi.fn()
+ }))
+});
+```
+
+## File Organization
+
+```
+spec/
+├── utils-spec.ts # Utils module tests
+├── gridstack-spec.ts # Main GridStack tests
+├── gridstack-engine-spec.ts # Engine logic tests
+├── regression-spec.ts # Regression tests
+└── e2e/ # End-to-end tests (not in coverage)
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+```yaml
+- name: Run Tests
+ run: yarn test:ci
+
+- name: Upload Coverage
+ uses: codecov/codecov-action@v3
+ with:
+ file: ./coverage/lcov.info
+```
+
+### Test Results
+- **JUnit XML**: `coverage/junit-report.xml`
+- **Coverage LCOV**: `coverage/lcov.info`
+- **Coverage JSON**: `coverage/coverage-final.json`
+
+## Debugging Tests
+
+### VS Code Integration
+1. Install "Vitest" extension
+2. Run tests directly from editor
+3. Set breakpoints and debug
+
+### Browser UI
+```bash
+yarn test:ui
+```
+Opens a web interface for:
+- Running individual tests
+- Viewing test results
+- Coverage visualization
+- Real-time updates
+
+## Performance
+
+### Speed Comparison
+- **Karma + Jasmine**: ~15-20 seconds
+- **Vitest**: ~3-5 seconds
+- **Watch Mode**: Sub-second re-runs
+
+### Optimization Tips
+- Use `vi.mock()` for heavy dependencies
+- Prefer `toBe()` over `toEqual()` for primitives
+- Group related tests in `describe` blocks
+- Use `beforeEach`/`afterEach` for setup/cleanup
+
+## Migration Notes
+
+This project was migrated from Karma + Jasmine to Vitest with the following changes:
+
+1. **Dependencies**: Removed karma-\* packages, added vitest + utilities
+2. **Configuration**: Replaced `karma.conf.js` with `vitest.config.ts`
+3. **Syntax**: Updated test syntax to modern ES6+ style
+4. **Coverage**: Enhanced coverage with V8 provider and multiple formats
+5. **Scripts**: New npm scripts for various testing workflows
+
+All existing tests were preserved and converted to work with Vitest.
diff --git a/angular/.editorconfig b/angular/.editorconfig
new file mode 100644
index 000000000..59d9a3a3e
--- /dev/null
+++ b/angular/.editorconfig
@@ -0,0 +1,16 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false
diff --git a/angular/.gitignore b/angular/.gitignore
new file mode 100644
index 000000000..4d87fb81a
--- /dev/null
+++ b/angular/.gitignore
@@ -0,0 +1,43 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+
+# Compiled output
+/dist
+/tmp
+/out-tsc
+/bazel-out
+/doc/html/
+
+# Node
+/node_modules
+npm-debug.log
+yarn-error.log
+
+# IDEs and editors
+.idea/
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.history/*
+
+# Miscellaneous
+/.angular/cache
+.sass-cache/
+/connect.lock
+/coverage
+/libpeerconnection.log
+testem.log
+/typings
+
+# System files
+.DS_Store
+Thumbs.db
diff --git a/angular/README.md b/angular/README.md
new file mode 100644
index 000000000..79abfc0ff
--- /dev/null
+++ b/angular/README.md
@@ -0,0 +1,211 @@
+# Angular wrapper
+
+The Angular [wrapper component](projects/lib/src/lib/gridstack.component.ts)