@prezly/theme-kit-nextjs 1.3.3 → 1.3.4-0

package/build/intl/localeObject.js

@@ -21,6 +21,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocaleObject = void 0;
 var localeConfig_1 = __importDefault(require("./localeConfig"));
+/**
+ * This class is created to simplify working with locales and transforming between different locale code formats.
+ * Prezly API uses underscore-codes, while most frontend application tend to use hyphen-codes or slugs.
+ * Note that `fromAnyCode` constructor only accepts locales supported by Prezly backend. See `localeConfig` for reference.
+ */
 var LocaleObject = /** @class */ (function () {
     function LocaleObject(localeCode) {
         if (localeCode.indexOf('_') !== -1) {
@@ -49,19 +54,34 @@ var LocaleObject = /** @class */ (function () {
         }
         return new LocaleObject(foundCode);
     };
+    /**
+     * @returns Code formatted into hyphen format: `nl-BE`, `en-US`, `fr`, `fil`
+     */
     LocaleObject.prototype.toHyphenCode = function () {
         return this.localeCode;
     };
+    /**
+     * @returns Code formatted into underscore format, as expected by Prezly API: `nl_BE`, `en_US`, `fr`, `fil`
+     */
     LocaleObject.prototype.toUnderscoreCode = function () {
         return this.localeCode.replace('-', '_');
     };
+    /**
+     * @returns Code formatted to a URL-friendly lowercase slug format: `nl-be`, `en-us`, `fr`, `fil`
+     */
     LocaleObject.prototype.toUrlSlug = function () {
         return this.localeCode.toLowerCase();
     };
+    /**
+     * @returns Only the language part of the code without culture/region part: `nl`, `en`, `fr`
+     */
     LocaleObject.prototype.toNeutralLanguageCode = function () {
         var _a = __read(this.localeCode.split('-'), 1), language = _a[0];
         return language;
     };
+    /**
+     * @returns Only the culture/regtion part without the language part: `be`, `us`, `fr`
+     */
     LocaleObject.prototype.toRegionCode = function () {
         var _a = __read(this.localeCode.split('-'), 2), language = _a[0], region = _a[1];
         if (!region) {
@@ -69,6 +89,9 @@ var LocaleObject = /** @class */ (function () {
         }
         return region.toUpperCase();
     };
+    /**
+     * Check if two LocaleObject instances are representing the same locale code.
+     */
     LocaleObject.prototype.isEqual = function (anotherLocale) {
         return anotherLocale.toHyphenCode() === this.localeCode;
     };

package/build/intl/localeObject.js.map

@@ -1 +1 @@
-{"version":3,"file":"localeObject.js","sourceRoot":"","sources":["../../src/intl/localeObject.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA,gEAA0C;AAE1C;IAOI,sBAAoB,UAAkB;QAClC,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE;YAChC,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;SACpD;QAEK,IAAA,KAAA,OAAqB,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,IAAA,EAAzC,QAAQ,QAAA,EAAE,MAAM,QAAyB,CAAC;QAEjD,IAAI,MAAM,EAAE;YACR,IAAI,CAAC,UAAU,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SAChE;aAAM;YACH,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC;SAC9B;IACL,CAAC;IAED;;;;;;OAMG;IACW,wBAAW,GAAzB,UAA0B,UAAkB;QACxC,IAAM,aAAa,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjE,IAAM,SAAS,GAAG,sBAAY,CAAC,IAAI,CAAC,UAAC,IAAI,IAAK,OAAA,IAAI,KAAK,aAAa,EAAtB,CAAsB,CAAC,CAAC;QAEtE,IAAI,CAAC,SAAS,EAAE;YACZ,MAAM,IAAI,KAAK,CAAC,8CAAsC,aAAa,OAAG,CAAC,CAAC;SAC3E;QAED,OAAO,IAAI,YAAY,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAEM,mCAAY,GAAnB;QACI,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IAEM,uCAAgB,GAAvB;QACI,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IAEM,gCAAS,GAAhB;QACI,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;IACzC,CAAC;IAEM,4CAAqB,GAA5B;QACU,IAAA,KAAA,OAAa,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,IAAA,EAAtC,QAAQ,QAA8B,CAAC;QAE9C,OAAO,QAAQ,CAAC;IACpB,CAAC;IAEM,mCAAY,GAAnB;QACU,IAAA,KAAA,OAAqB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,IAAA,EAA9C,QAAQ,QAAA,EAAE,MAAM,QAA8B,CAAC;QAEtD,IAAI,CAAC,MAAM,EAAE;YACT,OAAO,QAAQ,CAAC,WAAW,EAAE,CAAC;SACjC;QAED,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;IAChC,CAAC;IAEM,8BAAO,GAAd,UAAe,aAA2B;QACtC,OAAO,aAAa,CAAC,YAAY,EAAE,KAAK,IAAI,CAAC,UAAU,CAAC;IAC5D,CAAC;IACL,mBAAC;AAAD,CAAC,AAtED,IAsEC;AAtEY,oCAAY"}
+{"version":3,"file":"localeObject.js","sourceRoot":"","sources":["../../src/intl/localeObject.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA,gEAA0C;AAE1C;;;;GAIG;AACH;IAOI,sBAAoB,UAAkB;QAClC,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE;YAChC,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;SACpD;QAEK,IAAA,KAAA,OAAqB,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,IAAA,EAAzC,QAAQ,QAAA,EAAE,MAAM,QAAyB,CAAC;QAEjD,IAAI,MAAM,EAAE;YACR,IAAI,CAAC,UAAU,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SAChE;aAAM;YACH,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC;SAC9B;IACL,CAAC;IAED;;;;;;OAMG;IACW,wBAAW,GAAzB,UAA0B,UAAkB;QACxC,IAAM,aAAa,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjE,IAAM,SAAS,GAAG,sBAAY,CAAC,IAAI,CAAC,UAAC,IAAI,IAAK,OAAA,IAAI,KAAK,aAAa,EAAtB,CAAsB,CAAC,CAAC;QAEtE,IAAI,CAAC,SAAS,EAAE;YACZ,MAAM,IAAI,KAAK,CAAC,8CAAsC,aAAa,OAAG,CAAC,CAAC;SAC3E;QAED,OAAO,IAAI,YAAY,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACI,mCAAY,GAAnB;QACI,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IAED;;OAEG;IACI,uCAAgB,GAAvB;QACI,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACI,gCAAS,GAAhB;QACI,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;IACzC,CAAC;IAED;;OAEG;IACI,4CAAqB,GAA5B;QACU,IAAA,KAAA,OAAa,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,IAAA,EAAtC,QAAQ,QAA8B,CAAC;QAE9C,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED;;OAEG;IACI,mCAAY,GAAnB;QACU,IAAA,KAAA,OAAqB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,IAAA,EAA9C,QAAQ,QAAA,EAAE,MAAM,QAA8B,CAAC;QAEtD,IAAI,CAAC,MAAM,EAAE;YACT,OAAO,QAAQ,CAAC,WAAW,EAAE,CAAC;SACjC;QAED,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;IAChC,CAAC;IAED;;OAEG;IACI,8BAAO,GAAd,UAAe,aAA2B;QACtC,OAAO,aAAa,CAAC,YAAY,EAAE,KAAK,IAAI,CAAC,UAAU,CAAC;IAC5D,CAAC;IACL,mBAAC;AAAD,CAAC,AAxFD,IAwFC;AAxFY,oCAAY"}

package/build/newsroom-context/context.d.ts

@@ -3,19 +3,56 @@ import type { PropsWithChildren } from 'react';
 import type { AlgoliaSettings } from '../data-fetching';
 import { LocaleObject } from '../intl';
 export interface NewsroomContextType {
+    /**
+     * Basic newsroom information: newsroom logos, settings, etc.
+     */
     newsroom: Newsroom;
+    /**
+     * Contact information of the newsroom in the default language, usually displayed in the "About" section
+     */
     companyInformation: NewsroomCompanyInformation;
+    /**
+     * List of all categories enabled on the newsroom
+     */
     categories: Category[];
+    /**
+     * Optional: Contacts set up to be displayed on the newsroom home page.
+     * Will only be loaded if `loadHomepageContacts` option of `getNewsroomServerSideProps` is set to `true`.
+     */
     contacts?: NewsroomContact[];
+    /**
+     * Optional: Refers to a currently selected category when navigated to `/category/[slug]` page.
+     */
     currentCategory?: Category;
+    /**
+     * Optional: Refers to a currently selected story when navigated to `/[slug]` page.
+     */
     currentStory?: ExtendedStory;
+    /**
+     * List of currently enabled newsroom languages, as well as company information translated for each language
+     */
     languages: NewsroomLanguageSettings[];
+    /**
+     * Currently chosen locale
+     */
     locale: LocaleObject;
-    themePreset: NewsroomThemePreset;
+    /**
+     * Theme settings as set in the Prezly app.
+     * You need to provide `PREZLY_THEME_UUID` in environment variables in order for the preset to be loaded.
+     * Only applicable to themes hosted on the Prezly infrastructure.
+     */
+    themePreset: NewsroomThemePreset | null;
+    /**
+     * Environment variables required for Algolia search to work.
+     */
     algoliaSettings: AlgoliaSettings;
 }
 export interface NewsroomContextProps extends Omit<NewsroomContextType, 'locale'> {
     localeCode: string;
 }
 export declare const NewsroomContext: import("react").Context<NewsroomContextType | undefined>;
+/**
+ * This context provides common Newsroom information retrieved by `getNewsroomServerSideProps` helper.
+ * Please refer to the `NewsroomContextType` definition for more info on what's exposed from the context.
+ */
 export declare function NewsroomContextProvider({ categories, contacts, newsroom, currentCategory, currentStory, companyInformation, languages, localeCode, themePreset, algoliaSettings, children, }: PropsWithChildren<NewsroomContextProps>): JSX.Element;

package/build/newsroom-context/context.js

@@ -16,6 +16,10 @@ var jsx_runtime_1 = require("react/jsx-runtime");
 var react_1 = require("react");
 var intl_1 = require("../intl");
 exports.NewsroomContext = (0, react_1.createContext)(undefined);
+/**
+ * This context provides common Newsroom information retrieved by `getNewsroomServerSideProps` helper.
+ * Please refer to the `NewsroomContextType` definition for more info on what's exposed from the context.
+ */
 function NewsroomContextProvider(_a) {
     var categories = _a.categories, contacts = _a.contacts, newsroom = _a.newsroom, currentCategory = _a.currentCategory, currentStory = _a.currentStory, companyInformation = _a.companyInformation, languages = _a.languages, localeCode = _a.localeCode, themePreset = _a.themePreset, algoliaSettings = _a.algoliaSettings, children = _a.children;
     var locale = (0, react_1.useMemo)(function () { return intl_1.LocaleObject.fromAnyCode(localeCode || intl_1.DEFAULT_LOCALE); }, [localeCode]);

package/build/newsroom-context/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/newsroom-context/context.tsx"],"names":[],"mappings":";;;;;;;;;;;;;;;AAUA,+BAA+C;AAG/C,gCAAuD;AAmB1C,QAAA,eAAe,GAAG,IAAA,qBAAa,EAAkC,SAAS,CAAC,CAAC;AAEzF,SAAgB,uBAAuB,CAAC,EAYE;QAXtC,UAAU,gBAAA,EACV,QAAQ,cAAA,EACR,QAAQ,cAAA,EACR,eAAe,qBAAA,EACf,YAAY,kBAAA,EACZ,kBAAkB,wBAAA,EAClB,SAAS,eAAA,EACT,UAAU,gBAAA,EACV,WAAW,iBAAA,EACX,eAAe,qBAAA,EACf,QAAQ,cAAA;IAER,IAAM,MAAM,GAAG,IAAA,eAAO,EAClB,cAAM,OAAA,mBAAY,CAAC,WAAW,CAAC,UAAU,IAAI,qBAAc,CAAC,EAAtD,CAAsD,EAC5D,CAAC,UAAU,CAAC,CACf,CAAC;IAEF,OAAO,CACH,uBAAC,uBAAe,CAAC,QAAQ,aACrB,KAAK,EAAE;YACH,UAAU,YAAA;YACV,QAAQ,UAAA;YACR,QAAQ,UAAA;YACR,eAAe,iBAAA;YACf,YAAY,cAAA;YACZ,kBAAkB,oBAAA;YAClB,SAAS,WAAA;YACT,MAAM,QAAA;YACN,WAAW,aAAA;YACX,eAAe,iBAAA;SAClB,gBAEA,QAAQ,YACc,CAC9B,CAAC;AACN,CAAC;AApCD,0DAoCC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/newsroom-context/context.tsx"],"names":[],"mappings":";;;;;;;;;;;;;;;AAUA,+BAA+C;AAG/C,gCAAuD;AAoD1C,QAAA,eAAe,GAAG,IAAA,qBAAa,EAAkC,SAAS,CAAC,CAAC;AAEzF;;;GAGG;AACH,SAAgB,uBAAuB,CAAC,EAYE;QAXtC,UAAU,gBAAA,EACV,QAAQ,cAAA,EACR,QAAQ,cAAA,EACR,eAAe,qBAAA,EACf,YAAY,kBAAA,EACZ,kBAAkB,wBAAA,EAClB,SAAS,eAAA,EACT,UAAU,gBAAA,EACV,WAAW,iBAAA,EACX,eAAe,qBAAA,EACf,QAAQ,cAAA;IAER,IAAM,MAAM,GAAG,IAAA,eAAO,EAClB,cAAM,OAAA,mBAAY,CAAC,WAAW,CAAC,UAAU,IAAI,qBAAc,CAAC,EAAtD,CAAsD,EAC5D,CAAC,UAAU,CAAC,CACf,CAAC;IAEF,OAAO,CACH,uBAAC,uBAAe,CAAC,QAAQ,aACrB,KAAK,EAAE;YACH,UAAU,YAAA;YACV,QAAQ,UAAA;YACR,QAAQ,UAAA;YACR,eAAe,iBAAA;YACf,YAAY,cAAA;YACZ,kBAAkB,oBAAA;YAClB,SAAS,WAAA;YACT,MAAM,QAAA;YACN,WAAW,aAAA;YACX,eAAe,iBAAA;SAClB,gBAEA,QAAQ,YACc,CAC9B,CAAC;AACN,CAAC;AApCD,0DAoCC"}

package/build/newsroom-context/hooks/useGetLinkLocaleSlug.js

@@ -6,7 +6,12 @@ var data_fetching_1 = require("../../data-fetching");
 var intl_1 = require("../../intl");
 var useCurrentLocale_1 = require("./useCurrentLocale");
 var useLanguages_1 = require("./useLanguages");
-// Determine correct locale slug for the link (trying to shorten the locale code if possible)
+/**
+ * Determines correct locale slug for the link (trying to shorten the locale code if possible).
+ * E.g. if newsroom has a single locale for Dutch (`nl_BE`), it will be shortened to `nl`.
+ * If there are more than one locale with the same language part, a full locale code will be used instead.
+ * `false` means that a default locale should be used (no locale in URL required).
+ */
 function getLinkLocaleSlug(languages, locale) {
     var shortestLocaleCode = (0, data_fetching_1.getShortestLocaleCode)(languages, locale);
     // When navigating to default language, we don't append the locale to the URL.

package/build/newsroom-context/hooks/useGetLinkLocaleSlug.js.map

@@ -1 +1 @@
-{"version":3,"file":"useGetLinkLocaleSlug.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useGetLinkLocaleSlug.ts"],"names":[],"mappings":";;;AACA,+BAAoC;AAEpC,qDAA4D;AAC5D,mCAA0C;AAE1C,uDAAsD;AACtD,+CAA8C;AAE9C,6FAA6F;AAC7F,SAAS,iBAAiB,CACtB,SAAqC,EACrC,MAAoB;IAEpB,IAAM,kBAAkB,GAAG,IAAA,qCAAqB,EAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACpE,8EAA8E;IAC9E,IAAI,CAAC,kBAAkB,EAAE;QACrB,OAAO,kBAAkB,CAAC;KAC7B;IAED,OAAO,mBAAY,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,SAAS,EAAE,CAAC;AACpE,CAAC;AAED,SAAgB,oBAAoB;IAChC,IAAM,aAAa,GAAG,IAAA,mCAAgB,GAAE,CAAC;IACzC,IAAM,SAAS,GAAG,IAAA,2BAAY,GAAE,CAAC;IAEjC,8DAA8D;IAC9D,OAAO,IAAA,mBAAW,EACd,UAAC,MAAqB,IAAK,OAAA,iBAAiB,CAAC,SAAS,EAAE,MAAM,IAAI,aAAa,CAAC,EAArD,CAAqD,EAChF,CAAC,SAAS,EAAE,aAAa,CAAC,CAC7B,CAAC;AACN,CAAC;AATD,oDASC"}
+{"version":3,"file":"useGetLinkLocaleSlug.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useGetLinkLocaleSlug.ts"],"names":[],"mappings":";;;AACA,+BAAoC;AAEpC,qDAA4D;AAC5D,mCAA0C;AAE1C,uDAAsD;AACtD,+CAA8C;AAE9C;;;;;GAKG;AACH,SAAS,iBAAiB,CACtB,SAAqC,EACrC,MAAoB;IAEpB,IAAM,kBAAkB,GAAG,IAAA,qCAAqB,EAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACpE,8EAA8E;IAC9E,IAAI,CAAC,kBAAkB,EAAE;QACrB,OAAO,kBAAkB,CAAC;KAC7B;IAED,OAAO,mBAAY,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,SAAS,EAAE,CAAC;AACpE,CAAC;AAED,SAAgB,oBAAoB;IAChC,IAAM,aAAa,GAAG,IAAA,mCAAgB,GAAE,CAAC;IACzC,IAAM,SAAS,GAAG,IAAA,2BAAY,GAAE,CAAC;IAEjC,8DAA8D;IAC9D,OAAO,IAAA,mBAAW,EACd,UAAC,MAAqB,IAAK,OAAA,iBAAiB,CAAC,SAAS,EAAE,MAAM,IAAI,aAAa,CAAC,EAArD,CAAqD,EAChF,CAAC,SAAS,EAAE,aAAa,CAAC,CAC7B,CAAC;AACN,CAAC;AATD,oDASC"}

package/build/newsroom-context/hooks/useGetTranslationUrl.d.ts

@@ -1,2 +1,6 @@
 import type { LocaleObject } from '../../intl';
+/**
+ * This hook returns a function that is meant to be used in language pickers and alternate locales list for the pages.
+ * `noFallback` parameter is useful for alternate language links in the `head` section of the document (so that there are no unwanted links to the homepage).
+ */
 export declare function useGetTranslationUrl(): (locale: LocaleObject, noFallback?: boolean | undefined) => string;

package/build/newsroom-context/hooks/useGetTranslationUrl.js

@@ -6,7 +6,12 @@ var react_1 = require("react");
 var data_fetching_1 = require("../../data-fetching");
 var useCurrentCategory_1 = require("./useCurrentCategory");
 var useCurrentStory_1 = require("./useCurrentStory");
-// Determine correct URL for translated stories/categories with a fallback to homepage
+/**
+ * Determine correct URL for translated stories/categories with a fallback to homepage.
+ * E.g. if a story has a translation, the function will return the localized slug URL.
+ * If there is no translation for the story, it will return the index page URL (`/`),
+ * or empty string, if `noFallback` is set to `true` (this is useful for alternate locale links).
+ */
 function getTranslationUrl(locale, path, currentCategory, currentStory, noFallback) {
     if (currentCategory) {
         if ((0, data_fetching_1.getCategoryHasTranslation)(currentCategory, locale)) {
@@ -33,6 +38,10 @@ function getTranslationUrl(locale, path, currentCategory, currentStory, noFallba
     }
     return path;
 }
+/**
+ * This hook returns a function that is meant to be used in language pickers and alternate locales list for the pages.
+ * `noFallback` parameter is useful for alternate language links in the `head` section of the document (so that there are no unwanted links to the homepage).
+ */
 function useGetTranslationUrl() {
     var asPath = (0, router_1.useRouter)().asPath;
     var currentCategory = (0, useCurrentCategory_1.useCurrentCategory)();

package/build/newsroom-context/hooks/useGetTranslationUrl.js.map

@@ -1 +1 @@
-{"version":3,"file":"useGetTranslationUrl.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useGetTranslationUrl.ts"],"names":[],"mappings":";;;AACA,sCAAwC;AACxC,+BAAoC;AAEpC,qDAAgF;AAGhF,2DAA0D;AAC1D,qDAAoD;AAEpD,sFAAsF;AACtF,SAAS,iBAAiB,CACtB,MAAoB,EACpB,IAAY,EACZ,eAA0B,EAC1B,YAA4B,EAC5B,UAAoB;IAEpB,IAAI,eAAe,EAAE;QACjB,IAAI,IAAA,yCAAyB,EAAC,eAAe,EAAE,MAAM,CAAC,EAAE;YACpD,OAAO,IAAA,8BAAc,EAAC,eAAe,EAAE,MAAM,CAAC,CAAC;SAClD;QAED,IAAI,UAAU,EAAE;YACZ,OAAO,EAAE,CAAC;SACb;QAED,OAAO,GAAG,CAAC;KACd;IAED,IAAM,UAAU,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;IAE7C,IAAI,YAAY,IAAI,YAAY,CAAC,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE;QAC5D,IAAM,eAAe,GAAG,YAAY,CAAC,YAAY,CAAC,IAAI,CAClD,UAAC,EAAW;gBAAT,OAAO,aAAA;YAAO,OAAA,OAAO,CAAC,MAAM,KAAK,UAAU;QAA7B,CAA6B,CACjD,CAAC;QACF,IAAI,eAAe,EAAE;YACjB,OAAO,WAAI,eAAe,CAAC,IAAI,CAAE,CAAC;SACrC;QAED,IAAI,UAAU,EAAE;YACZ,OAAO,EAAE,CAAC;SACb;QAED,OAAO,GAAG,CAAC;KACd;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,SAAgB,oBAAoB;IACxB,IAAA,MAAM,GAAK,IAAA,kBAAS,GAAE,OAAhB,CAAiB;IAC/B,IAAM,eAAe,GAAG,IAAA,uCAAkB,GAAE,CAAC;IAC7C,IAAM,YAAY,GAAG,IAAA,iCAAe,GAAE,CAAC;IAEvC,OAAO,IAAA,mBAAW,EACd,UAAC,MAAoB,EAAE,UAAoB;QACvC,OAAA,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,CAAC;IAA5E,CAA4E,EAChF,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,CAAC,CAC1C,CAAC;AACN,CAAC;AAVD,oDAUC"}
+{"version":3,"file":"useGetTranslationUrl.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useGetTranslationUrl.ts"],"names":[],"mappings":";;;AACA,sCAAwC;AACxC,+BAAoC;AAEpC,qDAAgF;AAGhF,2DAA0D;AAC1D,qDAAoD;AAEpD;;;;;GAKG;AACH,SAAS,iBAAiB,CACtB,MAAoB,EACpB,IAAY,EACZ,eAA0B,EAC1B,YAA4B,EAC5B,UAAoB;IAEpB,IAAI,eAAe,EAAE;QACjB,IAAI,IAAA,yCAAyB,EAAC,eAAe,EAAE,MAAM,CAAC,EAAE;YACpD,OAAO,IAAA,8BAAc,EAAC,eAAe,EAAE,MAAM,CAAC,CAAC;SAClD;QAED,IAAI,UAAU,EAAE;YACZ,OAAO,EAAE,CAAC;SACb;QAED,OAAO,GAAG,CAAC;KACd;IAED,IAAM,UAAU,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;IAE7C,IAAI,YAAY,IAAI,YAAY,CAAC,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE;QAC5D,IAAM,eAAe,GAAG,YAAY,CAAC,YAAY,CAAC,IAAI,CAClD,UAAC,EAAW;gBAAT,OAAO,aAAA;YAAO,OAAA,OAAO,CAAC,MAAM,KAAK,UAAU;QAA7B,CAA6B,CACjD,CAAC;QACF,IAAI,eAAe,EAAE;YACjB,OAAO,WAAI,eAAe,CAAC,IAAI,CAAE,CAAC;SACrC;QAED,IAAI,UAAU,EAAE;YACZ,OAAO,EAAE,CAAC;SACb;QAED,OAAO,GAAG,CAAC;KACd;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAgB,oBAAoB;IACxB,IAAA,MAAM,GAAK,IAAA,kBAAS,GAAE,OAAhB,CAAiB;IAC/B,IAAM,eAAe,GAAG,IAAA,uCAAkB,GAAE,CAAC;IAC7C,IAAM,YAAY,GAAG,IAAA,iCAAe,GAAE,CAAC;IAEvC,OAAO,IAAA,mBAAW,EACd,UAAC,MAAoB,EAAE,UAAoB;QACvC,OAAA,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,CAAC;IAA5E,CAA4E,EAChF,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,CAAC,CAC1C,CAAC;AACN,CAAC;AAVD,oDAUC"}

package/build/types.d.ts

@@ -1,16 +1,29 @@
 import type { CultureRef, ExtraStoryFields, Story } from '@prezly/sdk';
 import type { NewsroomContextProps } from './newsroom-context';
 export interface ServerSidePageProps {
+    /**
+     * Indicates whether the locale requested by the Next application was correctly resolved to an active newsroom locale.
+     * This is used by `processRequest` method to redirect to the default locale if the property is `false`.
+     */
     localeResolved: boolean;
 }
+/**
+ * These are the props returned by the `processRequest` method that are meant to be passed to your `_app` to be injected into the `NewsroomContextProvider`.
+ */
 export interface PageProps {
     newsroomContextProps: NewsroomContextProps;
 }
+/**
+ * Categories in Algolia index are stored in a simplified format, with `slug` and `name` properties already saved in the correct locale for the story search result.
+ */
 export interface AlgoliaCategoryRef {
     id: number;
     name: string;
     slug: string;
 }
+/**
+ * Stories in Algolia index are stored in a simplified format, with only minimal subset of fields.
+ */
 export declare type AlgoliaStory = Pick<Story, 'uuid' | 'slug' | 'title' | 'subtitle'> & Pick<ExtraStoryFields, 'thumbnail_image'> & {
     content_text: string;
     updated_at: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prezly/theme-kit-nextjs",
-  "version": "1.3.3",
+  "version": "1.3.4-0",
   "description": "Data layer and utility library for developing Prezly themes with NextJS",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/src/adapter-nextjs/getNewsroomServerSideProps.ts

@@ -8,6 +8,10 @@ interface Options {
     story?: Story;
 }
 
+/**
+ * Use this function in your `getServerSideProps` page methods to retrieve the data necessary for the NewsroomContextProvider and `processRequest` function.
+ * See README for usage examples.
+ */
 export async function getNewsroomServerSideProps(
     context: GetServerSidePropsContext,
     options: Options = {},

package/src/adapter-nextjs/processRequest.ts

@@ -4,6 +4,15 @@ import { getShortestLocaleCode } from '../data-fetching';
 import { getRedirectToCanonicalLocale, LocaleObject } from '../intl';
 import type { PageProps, ServerSidePageProps } from '../types';
 
+/**
+ * This function combines the props returned from `getNewsroomServerSideProps` and your optional custom props for the page.
+ * It also handles locale redirects, if `canonicalUrl` parameter is provided.
+ * See README for usage examples.
+ *
+ * @param context Next.js context passed to the `getServerSideProps` method of the page
+ * @param props Object containing the return of `getNewsroomServerSideProps` and your optional custom props.
+ * @param canonicalUrl Optional: a canonical URL for the current page without locale part. If provided, locale redirects will be handled by the function.
+ */
 export function processRequest<Props>(
     context: GetServerSidePropsContext,
     props: Props & PageProps & ServerSidePageProps,

package/src/data-fetching/api/PrezlyApi.ts

@@ -49,14 +49,18 @@ export class PrezlyApi {
 
     private readonly newsroomUuid: Newsroom['uuid'];
 
-    constructor(accessToken: string, newsroomUuid: Newsroom['uuid']) {
+    private readonly themeUuid: string | undefined;
+
+    constructor(accessToken: string, newsroomUuid: Newsroom['uuid'], themeUuid?: string) {
         const baseUrl = process.env.API_BASE_URL_OVERRIDE ?? undefined;
         this.sdk = new PrezlySDK({
             accessToken,
             baseUrl,
+            // This returns stories created by legacy version of the editor in a format that can be displayed by the Prezly Content Renderer.
             headers: { 'X-Convert-v1-To-v3': 'true' },
         });
         this.newsroomUuid = newsroomUuid;
+        this.themeUuid = themeUuid;
     }
 
     getStory(uuid: string) {
@@ -77,6 +81,9 @@ export class PrezlyApi {
         return (await this.sdk.newsroomLanguages.list(this.newsroomUuid)).languages;
     }
 
+    /**
+     * Note: this method returns ALL stories from the newsroom. It's intended to be used for sitemaps and not to display actual content.
+     */
     async getAllStories(order: SortOrder = DEFAULT_SORT_ORDER) {
         const sortOrder = getSortByPublishedDate(order);
         const newsroom = await this.getNewsroom();
@@ -195,8 +202,15 @@ export class PrezlyApi {
         return this.sdk.newsroomGalleries.get(this.newsroomUuid, uuid);
     }
 
+    /**
+     * In order to prevent issues with theme preview, we only load the theme preset for a specified theme, and not the currently active one.
+     */
     async getThemePreset() {
-        return this.sdk.newsroomThemes.getActive(this.newsroomUuid);
+        if (this.themeUuid) {
+            return this.sdk.newsroomThemes.get(this.newsroomUuid, this.themeUuid);
+        }
+
+        return null;
     }
 
     async getNewsroomServerSideProps(

package/src/data-fetching/api/getPrezlyApi.ts

@@ -10,7 +10,7 @@ export function getPrezlyApi(req?: IncomingMessage): PrezlyApi {
     }
 
     // `getEnvVariables` handles both cases for envs parsing - .env and request headers
-    const { PREZLY_ACCESS_TOKEN, PREZLY_NEWSROOM_UUID } = getEnvVariables(req);
+    const { PREZLY_ACCESS_TOKEN, PREZLY_NEWSROOM_UUID, PREZLY_THEME_UUID } = getEnvVariables(req);
 
     if (!PREZLY_ACCESS_TOKEN) {
         throw new Error('"PREZLY_ACCESS_TOKEN" is not set in env variables.');
@@ -20,5 +20,5 @@ export function getPrezlyApi(req?: IncomingMessage): PrezlyApi {
         throw new Error('"PREZLY_NEWSROOM_UUID" is not set in env variables.');
     }
 
-    return new PrezlyApi(PREZLY_ACCESS_TOKEN, PREZLY_NEWSROOM_UUID);
+    return new PrezlyApi(PREZLY_ACCESS_TOKEN, PREZLY_NEWSROOM_UUID, PREZLY_THEME_UUID);
 }

package/src/data-fetching/api/languages.ts

@@ -2,10 +2,16 @@ import type { NewsroomLanguageSettings, Story } from '@prezly/sdk';
 
 import { DUMMY_DEFAULT_LOCALE, LocaleObject } from '../../intl';
 
+/**
+ * @returns Language set as default in the Newsroom Settings.
+ */
 export function getDefaultLanguage(languages: NewsroomLanguageSettings[]) {
     return languages.find(({ is_default }) => is_default) || languages[0];
 }
 
+/**
+ * @returns Only languages having at least one published story
+ */
 export function getUsedLanguages(languages: NewsroomLanguageSettings[]) {
     return languages.filter((language) => language.public_stories_count > 0);
 }
@@ -110,6 +116,9 @@ export function getLanguageFromStory(languages: NewsroomLanguageSettings[], stor
     return languages.find(({ code }) => code === storyLocaleCode);
 }
 
+/**
+ * Extracts company information for the selected locale
+ */
 export function getCompanyInformation(languages: NewsroomLanguageSettings[], locale: LocaleObject) {
     const currentLanguage =
         getLanguageByExactLocaleCode(languages, locale) || getDefaultLanguage(languages);

package/src/data-fetching/getAssetsUrl.ts

@@ -1,5 +1,9 @@
 import { ASSETS_URL } from './constants';
 
+/**
+ * @param uuid UUID of the assets hosted on Uploadcare
+ * @returns Full asset URL that can be used as a source for <img>, <video> and <a> tags.
+ */
 export function getAssetsUrl(uuid: string) {
     return `${ASSETS_URL}/${uuid}/`;
 }

package/src/data-fetching/getUploadcareGroupUrl.ts

@@ -1,5 +1,12 @@
 import { ASSETS_URL } from './constants';
 
+/**
+ * This method constructs a URL to download all images in the Gallery as a single archive.
+ *
+ * @param uuid Gallery UUID
+ * @param title Filename for the saved archive. Usually it is the Gallery title.
+ * @returns URL to an archive containing all of the images in the Gallery.
+ */
 export function getUploadcareGroupUrl(uuid: string, title: string) {
     return `${ASSETS_URL}/${uuid}/archive/zip/${encodeURI(title)}.zip`;
 }

package/src/data-fetching/types.ts

@@ -7,6 +7,7 @@ export interface AlgoliaSettings {
 export interface PrezlyNewsroomEnv {
     PREZLY_ACCESS_TOKEN: string;
     PREZLY_NEWSROOM_UUID: string;
+    PREZLY_THEME_UUID?: string;
 }
 
 export interface PrezlyEnv extends PrezlyNewsroomEnv, AlgoliaSettings {}

package/src/intl/lang.ts

@@ -9,14 +9,16 @@ function isOnlyCulture(culture: CultureRef, languages: NewsroomLanguageSettings[
 }
 
 /**
+ * @returns the display name of the locale in its native language
+ *
  * If there's only one culture used in a specific language,
  * we strip the culture name completely.
  *
  * Examples:
  *  - English (Global), Spanish (Spain)
- *      -> English, Spanish
+ *  - -> English, Spanish
  *  - English (Global), English (UK), Spanish (Spain)
- *      -> English (Global), English (UK), Spanish
+ *  - -> English (Global), English (UK), Spanish
  */
 export function getLanguageDisplayName(
     language: NewsroomLanguageSettings,

package/src/intl/locale.ts

@@ -5,8 +5,13 @@ import { stringify } from 'querystring';
 import { LocaleObject } from './localeObject';
 
 export const DEFAULT_LOCALE = 'en';
+// We use pseudo locale used for localization testing, to reliably determine if we need to fallback to the default newsroom language
 export const DUMMY_DEFAULT_LOCALE = 'qps-ploc';
 
+/**
+ * This a list of locales that Prezly has translations for. Each code represents a language file in the `@prezly/themes-intl-messages` package.
+ * See https://github.com/prezly/themes-intl-messages for more info.
+ */
 const SUPPORTED_LOCALES = [
     'af',
     'ar',
@@ -56,6 +61,10 @@ const SUPPORTED_LOCALES = [
     'zh-TW',
 ];
 
+/**
+ * Use this function to determine which translations file you should load from `@prezly/themes-intl-mesages` package.
+ * See https://github.com/prezly/theme-nextjs-bea/blob/main/utils/lang.ts for a usage example.
+ */
 export function getSupportedLocaleIsoCode(locale: LocaleObject): string {
     const localeIsoCode = locale.toHyphenCode();
 

package/src/intl/localeConfig.js

@@ -1,4 +1,8 @@
-// This list is pulled from the main Prezly application. The underscores are replaced with dashes.
+/**
+ * This list is pulled from the main Prezly application. The underscores are replaced with dashes.
+ * Together with permutation performed lower in the code,
+ * the exported list represents all of the possible locale codes that Next.js theme application might accept.
+ */
 const supportedLocales = [
     'af-ZA',
     'ar',
@@ -105,7 +109,7 @@ const supportedLocales = [
 
 const lowercaseLocales = supportedLocales.map((l) => l.toLowerCase());
 
-// Get all permutations for the shorter locale codes supported by Prezly (e.g. short region codes)
+// Get all permutations for the shorter locale codes supported by Prezly (e.g. short region codes and neutral language codes)
 const lowercaseLocalPermutations = Array.from(
     new Set([
         ...lowercaseLocales,

package/src/intl/localeObject.ts

@@ -1,5 +1,10 @@
 import localeConfig from './localeConfig';
 
+/**
+ * This class is created to simplify working with locales and transforming between different locale code formats.
+ * Prezly API uses underscore-codes, while most frontend application tend to use hyphen-codes or slugs.
+ * Note that `fromAnyCode` constructor only accepts locales supported by Prezly backend. See `localeConfig` for reference.
+ */
 export class LocaleObject {
     /**
      * Hyphen-separated locale code.
@@ -39,24 +44,39 @@ export class LocaleObject {
         return new LocaleObject(foundCode);
     }
 
+    /**
+     * @returns Code formatted into hyphen format: `nl-BE`, `en-US`, `fr`, `fil`
+     */
     public toHyphenCode(): string {
         return this.localeCode;
     }
 
+    /**
+     * @returns Code formatted into underscore format, as expected by Prezly API: `nl_BE`, `en_US`, `fr`, `fil`
+     */
     public toUnderscoreCode(): string {
         return this.localeCode.replace('-', '_');
     }
 
+    /**
+     * @returns Code formatted to a URL-friendly lowercase slug format: `nl-be`, `en-us`, `fr`, `fil`
+     */
     public toUrlSlug(): string {
         return this.localeCode.toLowerCase();
     }
 
+    /**
+     * @returns Only the language part of the code without culture/region part: `nl`, `en`, `fr`
+     */
     public toNeutralLanguageCode(): string {
         const [language] = this.localeCode.split('-');
 
         return language;
     }
 
+    /**
+     * @returns Only the culture/regtion part without the language part: `be`, `us`, `fr`
+     */
     public toRegionCode(): string {
         const [language, region] = this.localeCode.split('-');
 
@@ -67,6 +87,9 @@ export class LocaleObject {
         return region.toUpperCase();
     }
 
+    /**
+     * Check if two LocaleObject instances are representing the same locale code.
+     */
     public isEqual(anotherLocale: LocaleObject) {
         return anotherLocale.toHyphenCode() === this.localeCode;
     }

package/src/newsroom-context/context.tsx

@@ -14,15 +14,48 @@ import type { AlgoliaSettings } from '../data-fetching';
 import { DEFAULT_LOCALE, LocaleObject } from '../intl';
 
 export interface NewsroomContextType {
+    /**
+     * Basic newsroom information: newsroom logos, settings, etc.
+     */
     newsroom: Newsroom;
+    /**
+     * Contact information of the newsroom in the default language, usually displayed in the "About" section
+     */
     companyInformation: NewsroomCompanyInformation;
+    /**
+     * List of all categories enabled on the newsroom
+     */
     categories: Category[];
+    /**
+     * Optional: Contacts set up to be displayed on the newsroom home page.
+     * Will only be loaded if `loadHomepageContacts` option of `getNewsroomServerSideProps` is set to `true`.
+     */
     contacts?: NewsroomContact[];
+    /**
+     * Optional: Refers to a currently selected category when navigated to `/category/[slug]` page.
+     */
     currentCategory?: Category;
+    /**
+     * Optional: Refers to a currently selected story when navigated to `/[slug]` page.
+     */
     currentStory?: ExtendedStory;
+    /**
+     * List of currently enabled newsroom languages, as well as company information translated for each language
+     */
     languages: NewsroomLanguageSettings[];
+    /**
+     * Currently chosen locale
+     */
     locale: LocaleObject;
-    themePreset: NewsroomThemePreset;
+    /**
+     * Theme settings as set in the Prezly app.
+     * You need to provide `PREZLY_THEME_UUID` in environment variables in order for the preset to be loaded.
+     * Only applicable to themes hosted on the Prezly infrastructure.
+     */
+    themePreset: NewsroomThemePreset | null;
+    /**
+     * Environment variables required for Algolia search to work.
+     */
     algoliaSettings: AlgoliaSettings;
 }
 
@@ -32,6 +65,10 @@ export interface NewsroomContextProps extends Omit<NewsroomContextType, 'locale'
 
 export const NewsroomContext = createContext<NewsroomContextType | undefined>(undefined);
 
+/**
+ * This context provides common Newsroom information retrieved by `getNewsroomServerSideProps` helper.
+ * Please refer to the `NewsroomContextType` definition for more info on what's exposed from the context.
+ */
 export function NewsroomContextProvider({
     categories,
     contacts,

package/src/newsroom-context/hooks/useGetLinkLocaleSlug.ts

@@ -7,7 +7,12 @@ import { LocaleObject } from '../../intl';
 import { useCurrentLocale } from './useCurrentLocale';
 import { useLanguages } from './useLanguages';
 
-// Determine correct locale slug for the link (trying to shorten the locale code if possible)
+/**
+ * Determines correct locale slug for the link (trying to shorten the locale code if possible).
+ * E.g. if newsroom has a single locale for Dutch (`nl_BE`), it will be shortened to `nl`.
+ * If there are more than one locale with the same language part, a full locale code will be used instead.
+ * `false` means that a default locale should be used (no locale in URL required).
+ */
 function getLinkLocaleSlug(
     languages: NewsroomLanguageSettings[],
     locale: LocaleObject,

package/src/newsroom-context/hooks/useGetTranslationUrl.ts

@@ -8,7 +8,12 @@ import type { LocaleObject } from '../../intl';
 import { useCurrentCategory } from './useCurrentCategory';
 import { useCurrentStory } from './useCurrentStory';
 
-// Determine correct URL for translated stories/categories with a fallback to homepage
+/**
+ * Determine correct URL for translated stories/categories with a fallback to homepage.
+ * E.g. if a story has a translation, the function will return the localized slug URL.
+ * If there is no translation for the story, it will return the index page URL (`/`),
+ * or empty string, if `noFallback` is set to `true` (this is useful for alternate locale links).
+ */
 function getTranslationUrl(
     locale: LocaleObject,
     path: string,
@@ -48,6 +53,10 @@ function getTranslationUrl(
     return path;
 }
 
+/**
+ * This hook returns a function that is meant to be used in language pickers and alternate locales list for the pages.
+ * `noFallback` parameter is useful for alternate language links in the `head` section of the document (so that there are no unwanted links to the homepage).
+ */
 export function useGetTranslationUrl() {
     const { asPath } = useRouter();
     const currentCategory = useCurrentCategory();