From d08e418be489e5c9e74bd7764c761de885a66bcd Mon Sep 17 00:00:00 2001 From: poongaloo Date: Mon, 8 Jun 2026 23:12:48 +0200 Subject: [PATCH] =?UTF-8?q?diff=20api=20publique=20et=20priv=C3=A9e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.fr.md | 9 ++-- readme.md | 9 ++-- tests/unit/turn.unit.test.js | 85 ++++++++++++++++++++++++++++++++++++ turn.js | 16 +++++-- 4 files changed, 107 insertions(+), 12 deletions(-) diff --git a/README.fr.md b/README.fr.md index 16fb765..79c8fd3 100644 --- a/README.fr.md +++ b/README.fr.md @@ -126,21 +126,22 @@ Après `destroy`, les pages originales sont restaurées comme enfants directs de ## Notes d'API -Les méthodes courantes de la 3e release originale restent disponibles : +API publique supportée de turn : +- `init` / `$('#magazine').turn(options)` - `page` - `next` - `previous` - `addPage` - `removePage` -- `hasPage` - `pages` -- `display` - `size` -- `resize` +- `display` - `disable` - `destroy` +Les méthodes dont le nom commence par `_` sont des détails d'implémentation privés. D'autres helpers historiques peuvent encore exister pour compatibilité interne, mais ils ne sont pas documentés comme API supportée. + La nouvelle méthode `destroy` sert au démontage dans les applications monopages, les tests, les transitions de vue et tous les cas où un livre doit être supprimé ou réinitialisé sans laisser de wrappers DOM ni de handlers sur le document. ## Tests diff --git a/readme.md b/readme.md index be88687..efdb1ae 100644 --- a/readme.md +++ b/readme.md @@ -126,21 +126,22 @@ After `destroy`, the original page elements are restored as direct children of ` ## API Notes -Common methods from the original 3rd release remain available: +Supported public turn API: +- `init` / `$('#magazine').turn(options)` - `page` - `next` - `previous` - `addPage` - `removePage` -- `hasPage` - `pages` -- `display` - `size` -- `resize` +- `display` - `disable` - `destroy` +Methods whose names start with `_` are private implementation details. Other legacy helpers may still exist for internal compatibility, but they are not documented as supported API. + The new `destroy` method is intended for teardown in single-page applications, tests, page transitions, and any workflow where a book needs to be removed or initialized again without leaving DOM wrappers or document event handlers behind. ## Tests diff --git a/tests/unit/turn.unit.test.js b/tests/unit/turn.unit.test.js index ee84ab5..959089f 100644 --- a/tests/unit/turn.unit.test.js +++ b/tests/unit/turn.unit.test.js @@ -58,6 +58,14 @@ function expectTrackedWrappersToBeConnected($book) { } } +function captureThrownValue(callback) { + try { + callback(); + } catch (error) { + return error; + } +} + describe('turn.js jQuery plugin', () => { let fixture; @@ -78,6 +86,83 @@ describe('turn.js jQuery plugin', () => { expect($.fn.transform).toBeTypeOf('function'); }); + it('supports the documented public turn API methods', () => { + const { $ } = fixture; + const $book = $('#book'); + + $book.turn('init', { + width: 600, + height: 400, + display: 'double', + gradients: false, + acceleration: false + }); + + expect($book.turn('page')).toBe(1); + expect($book.turn('pages')).toBe(4); + expect($book.turn('size')).toEqual({ width: 600, height: 400 }); + + $book.turn('page', 2); + expect($book.turn('page')).toBe(2); + + $book.turn('addPage', $('
Page 5
'), 5); + expect($book.turn('pages')).toBe(5); + + $book.turn('removePage', 5); + expect($book.turn('pages')).toBe(4); + + $book.turn('pages', 4); + expect($book.turn('pages')).toBe(4); + + $book.turn('size', 320, 240); + expect($book.turn('size')).toEqual({ width: 320, height: 240 }); + + $book.turn('display', 'single'); + expect($book.turn('display')).toBe('single'); + + $book.turn('disable', true); + expect($book.data('disabled')).toBe(true); + $book.turn('disable', false); + expect($book.data('disabled')).toBe(false); + + expect(captureThrownValue(() => $book.turn('next'))).toBeUndefined(); + $book.turn('destroy'); + expect($book.data('opts')).toBeUndefined(); + + fixture.window.close(); + fixture = createFixture(); + const $bookForPrevious = fixture.$('#book'); + + $bookForPrevious.turn({ + width: 600, + height: 400, + display: 'double', + gradients: false, + acceleration: false, + page: 2 + }); + + expect(captureThrownValue(() => $bookForPrevious.turn('previous'))).toBeUndefined(); + $bookForPrevious.turn('destroy'); + }); + + it('rejects invalid and private turn method calls', () => { + const { $ } = fixture; + const $book = $('#book'); + + $book.turn({ + width: 600, + height: 400, + display: 'double', + gradients: false, + acceleration: false + }); + + expect(captureThrownValue(() => $book.turn('unknownMethod'))).toBe('unknownMethod is an invalid value'); + expect(captureThrownValue(() => $book.turn('_view'))).toBe('_view is an invalid value'); + expect(captureThrownValue(() => $book.turn('display', 'spread')).message).toBe('"spread" is not a value for display'); + }); + it('calculates fold geometry without DOM for every corner', () => { fixture.window.close(); fixture = createFixture(4, { diff --git a/turn.js b/turn.js index 7d5f28e..02ee0ec 100644 --- a/turn.js +++ b/turn.js @@ -394,6 +394,11 @@ var has3d, turnMethods = { + // Supported public turn API: + // init, page, next, previous, addPage, removePage, pages, size, + // display, disable and destroy. + // Methods prefixed with "_" are private implementation details. + // Singleton constructor // $('#selector').turn([options]); @@ -534,7 +539,7 @@ turnMethods = { return this; }, - // Restores one page element and removes flip wrappers/state + // Internal: restores one page element and removes flip wrappers/state _destroyPage: function(page) { @@ -572,7 +577,7 @@ turnMethods = { delete data.pagePlace[page]; }, - // Creates the visible DOM wrapper that hosts a source page + // Internal: creates the visible DOM wrapper that hosts a source page _createPageWrapper: function(page, width, height) { @@ -589,7 +594,7 @@ turnMethods = { return data.pageWrap[page]; }, - // Removes the turn page wrapper for one page + // Internal: removes the turn page wrapper for one page _removePageWrapper: function(page) { @@ -602,7 +607,7 @@ turnMethods = { delete data.pageWrap[page]; }, - // Removes flip-specific wrappers for one page element + // Internal: removes flip-specific wrappers for one page element _removeFlipWrappers: function(pageObj) { @@ -1500,6 +1505,9 @@ turnMethods = { flipMethods = { + // Flip methods are internal to the page-fold effect. They remain callable + // through $.fn.flip for historical compatibility, but are not turn API. + // Constructor init: function(opts) {