Merge pull request #13 from PoongalOO/api/ticket6

diff api publique et privée

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

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

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', $('<div class="page">Page 5</div>'), 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, {

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) {