Docs: Add UPGRADE guide for version 3

README.md

@@ -58,7 +58,7 @@ As a next step, add a link to open cookie preferences after the consent was prev
 somewhere in the page footer, usually near "Terms of use" and "Privacy policy" links.
 
 ```html
-<a href="" data-cc="c-preferencesModal">Open cookie preferences</a>
+<a href="" data-cc="show-preferencesModal">Open cookie preferences</a>
 ```
 
 [👀 See demo page with example][examples].

UPGRADE-3.0.md

@@ -1 +1,160 @@
 # Upgrade from 2.x to 3.0
+
+Release 3.0 contains backward incompatible changes (including changes in the underlying vanilla-cookieconsent library,
+which is also upgraded from version 2 to 3) which you need to take into account when upgrading to the new version.
+
+This guide sum-ups relevant changes in both `almacareer/cookie-consent` and `(vanilla-cookieconsent)[https://github.com/orestbida/cookieconsent]`
+library to help you upgrade your codebase.
+
+## Library npm namescape changed to `@almacareer`
+
+The library has been moved from `@lmc-eu` to `@almacareer` npm organization.
+
+If you use the library via npm, update your package.json file
+
+```diff
+-"@lmc-eu/cookie-consent": "^2.6.0"
++"@almacareer/cookie-consent": "^3.0.0"
+```
+
+If you use the library via CDN, update URL to styles and script:
+
+```diff
+-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@lmc-eu/cookie-consent-manager@2/CookieConsentManager.min.css">
++<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@almacareer/cookie-consent-manager@3/CookieConsentManager.min.css">
+
+-<script defer src="https://cdn.jsdelivr.net/npm/@lmc-eu/cookie-consent-manager@2/init.js"></script>
++<script defer src="https://cdn.jsdelivr.net/npm/@almacareer/cookie-consent-manager@3/init.js"></script>
+```
+
+## Renamed init function
+
+The `lmc` prefix has been removed from the init function name.
+
+```diff
+-initLmcCookieConsentManager('demo.example')
++initCookieConsentManager('demo.example');
+```
+
+Also, the typescript type has been renamed from `LmcCookieConsentManager` to `CookieConsentManager`.
+
+## Data attribute to open the settings window changed
+
+The `data-cc` attribute used to open the settings window has been changed from `c-settings` to `show-preferencesModal`.
+
+```diff
+-<a href="" data-cc="c-settings">Open cookie settings</a>
++<a href="" data-cc="show-preferencesModal">Open cookie preferences</a>
+```
+
+## Cookie has been renamed
+
+The cookie storing the consent data has been changed from `lmc_ccm` to `alma_ccm`. If you directly read the cookie value
+(either on backend or on frontend), you need to update the cookie name.
+
+**Keep on mind that the cookie rename will cause all previously given consents to be re-requested from all users.**
+This is expected and inevitable behavior with this change. There is no legal way to migrate the old cookie to the new
+one, as we technically can't transfer the validity period of the old consent to the new cookie.
+
+## Cookie content structure changed
+
+The internal structure of JSON cookie data has been changed and expanded.
+
+The main change is that `cookie.level` is now `cookie.categories`. If you work with cookie data on the server,
+you must update your server-side code to reflect this.
+
+### Before
+```json
+{
+  "level": [
+    "necessary",
+    "analytics",
+    "functionality",
+    "ad",
+    "personalization"
+  ],
+  "revision": 0,
+  "data": {
+    "serviceName": "demo.example",
+    "uid": "foo-bar-baz"
+  },
+  "rfc_cookie": true
+}
+```
+### After
+```json
+{
+  "categories": [
+    "necessary",
+    "analytics",
+    "functionality",
+    "ad",
+    "personalization"
+  ],
+  "revision": 0,
+  "data": {
+    "serviceName": "demo.example",
+    "uid": "foo-bar-baz"
+  },
+  "consentTimestamp": "2024-12-12T12:12:12.333Z",
+  "consentId": "f6152595-45a0-4371-aa68-2fe97137111a",
+  "services": {
+    "necessary": [],
+    "ad": [],
+    "analytics": [],
+    "functionality": [],
+    "personalization": []
+  },
+  "lastConsentTimestamp": "2024-12-12T12:12:12.333Z",
+  "expirationTime": 1764690394793
+}
+```
+
+## Data atribute to run third party scripts changed
+
+If you have conditional third-party scripts that depend on the consent category, you need to update the data attribute:
+
+```diff
+-<script data-cookiecategory="personalization" src="personalization.js" type="text/plain" defer></script>
++<script data-category="personalization" src="personalization.js" type="text/plain" defer></script>
+```
+## Method `allowedCategory()` to check consent renamed `acceptedCategory()`
+
+If you use the `allowedCategory()` method to check if a category is allowed and run conditional code based on that,
+you need to rename it to `acceptedCategory()`.
+
+```diff
+-if (cookieConsent.allowedCategory('personalization')) {
++if (cookieConsent.acceptedCategory('personalization')) {
+  // Run personalization code
+}
+```
+
+## Translation override `settingsModalMoreInfo` renamed
+
+To be in line with the vanilla-cookieconsent library terminology, the term "preferences" is used instead of "settings".
+If you used `translationOverrides` configuration, the key `settingsModalMoreInfo` has been renamed to `preferencesModalMoreInfo`.
+
+## Secondary button mode config removed
+
+Configuration option `secondaryButtonMode` has been removed.
+
+The consent dialog now always has primary button "Accept all" and secondary button "Accept necessary"
+with no option to reconfigure this.
+
+## Callbacks has been renamed and have different parameters
+
+- All callbacks now always have parameters `cookie` and `cookieConsent`.
+- All callback parameters are now encapsulated in an object `{}` on the position of the first parameter.
+- Two callbacks have been renamed for consistency with the vanilla-cookieconsent library:
+  - `onAccept()` is now `onConsent()`
+  - `onFirstAccept` is now `onFirstConsent()`
+
+See readme for [callbacks documentation](README.md#callbacks).
+
+## Other notable changes
+
+- `cookieTable` configuration does not affect in any way any cookies. Cookie table is used only for listing the cookies in preferences modal. If you want to clear cookies by the underlying library, you can enable `autoClearCookies` and provide `autoClear` configuration in the `config` option.
+- `updateLanguage()` method of the underlying vanilla-cookieconsent library has been renamed to `setLanguage()`
+- `config` configuration option, which is used for overrides of the internal config of the underlying library is now deep merged,
+  which means that you can override only the properties you need to change, and the rest will be kept from the default config (even nested properties).