@prezly/theme-kit-nextjs 1.3.1 → 1.4.0

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

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useLanguages = void 0;
 var useNewsroomContext_1 = require("./useNewsroomContext");
-var useLanguages = function () {
+function useLanguages() {
     var context = (0, useNewsroomContext_1.useNewsroomContext)();
     return context.languages;
-};
+}
 exports.useLanguages = useLanguages;
 //# sourceMappingURL=useLanguages.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"useLanguages.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useLanguages.ts"],"names":[],"mappings":";;;AAAA,2DAA0D;AAEnD,IAAM,YAAY,GAAG;IACxB,IAAM,OAAO,GAAG,IAAA,uCAAkB,GAAE,CAAC;IAErC,OAAO,OAAO,CAAC,SAAS,CAAC;AAC7B,CAAC,CAAC;AAJW,QAAA,YAAY,gBAIvB"}
+{"version":3,"file":"useLanguages.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useLanguages.ts"],"names":[],"mappings":";;;AAAA,2DAA0D;AAE1D,SAAgB,YAAY;IACxB,IAAM,OAAO,GAAG,IAAA,uCAAkB,GAAE,CAAC;IAErC,OAAO,OAAO,CAAC,SAAS,CAAC;AAC7B,CAAC;AAJD,oCAIC"}

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

@@ -1 +1 @@
-export declare const useNewsroom: () => import("@prezly/sdk").Newsroom;
+export declare function useNewsroom(): import("@prezly/sdk").Newsroom;

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

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useNewsroom = void 0;
 var useNewsroomContext_1 = require("./useNewsroomContext");
-var useNewsroom = function () {
+function useNewsroom() {
     var context = (0, useNewsroomContext_1.useNewsroomContext)();
     return context.newsroom;
-};
+}
 exports.useNewsroom = useNewsroom;
 //# sourceMappingURL=useNewsroom.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"useNewsroom.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useNewsroom.ts"],"names":[],"mappings":";;;AAAA,2DAA0D;AAEnD,IAAM,WAAW,GAAG;IACvB,IAAM,OAAO,GAAG,IAAA,uCAAkB,GAAE,CAAC;IAErC,OAAO,OAAO,CAAC,QAAQ,CAAC;AAC5B,CAAC,CAAC;AAJW,QAAA,WAAW,eAItB"}
+{"version":3,"file":"useNewsroom.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useNewsroom.ts"],"names":[],"mappings":";;;AAAA,2DAA0D;AAE1D,SAAgB,WAAW;IACvB,IAAM,OAAO,GAAG,IAAA,uCAAkB,GAAE,CAAC;IAErC,OAAO,OAAO,CAAC,QAAQ,CAAC;AAC5B,CAAC;AAJD,kCAIC"}

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

@@ -1,2 +1,2 @@
-import { NewsroomContextType } from '../context';
-export declare const useNewsroomContext: () => NewsroomContextType;
+import type { NewsroomContextType } from '../context';
+export declare function useNewsroomContext(): NewsroomContextType;

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

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useNewsroomContext = void 0;
 var react_1 = require("react");
 var context_1 = require("../context");
-var useNewsroomContext = function () {
+function useNewsroomContext() {
     // TS Compiler is having a hard time figuring this type implicitly, so we have to set it explicitly
     // See https://github.com/microsoft/TypeScript/issues/5711#issuecomment-340283439
     var newsroomContext = (0, react_1.useContext)(context_1.NewsroomContext);
@@ -11,6 +11,6 @@ var useNewsroomContext = function () {
         throw new Error('No `NewsroomContextProvider` found when calling `useNewsroomContext`');
     }
     return newsroomContext;
-};
+}
 exports.useNewsroomContext = useNewsroomContext;
 //# sourceMappingURL=useNewsroomContext.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"useNewsroomContext.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useNewsroomContext.ts"],"names":[],"mappings":";;;AAAA,+BAAmC;AAEnC,sCAAkE;AAE3D,IAAM,kBAAkB,GAAG;IAC9B,mGAAmG;IACnG,iFAAiF;IACjF,IAAM,eAAe,GAAoC,IAAA,kBAAU,EAAC,yBAAe,CAAC,CAAC;IACrF,IAAI,CAAC,eAAe,EAAE;QAClB,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;KAC3F;IAED,OAAO,eAAe,CAAC;AAC3B,CAAC,CAAC;AATW,QAAA,kBAAkB,sBAS7B"}
+{"version":3,"file":"useNewsroomContext.js","sourceRoot":"","sources":["../../../src/newsroom-context/hooks/useNewsroomContext.ts"],"names":[],"mappings":";;;AAAA,+BAAmC;AAGnC,sCAA6C;AAE7C,SAAgB,kBAAkB;IAC9B,mGAAmG;IACnG,iFAAiF;IACjF,IAAM,eAAe,GAAoC,IAAA,kBAAU,EAAC,yBAAe,CAAC,CAAC;IACrF,IAAI,CAAC,eAAe,EAAE;QAClB,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;KAC3F;IAED,OAAO,eAAe,CAAC;AAC3B,CAAC;AATD,gDASC"}

package/build/types.d.ts

@@ -1,16 +1,29 @@
 import type { CultureRef, ExtraStoryFields, Story } from '@prezly/sdk';
-import { NewsroomContextProps } from './newsroom-context';
+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.1",
+  "version": "1.4.0",
   "description": "Data layer and utility library for developing Prezly themes with NextJS",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -52,20 +52,12 @@
     "parse-data-url": "^4.0.1"
   },
   "devDependencies": {
+    "@prezly/eslint-config": "^4.0.0",
     "@types/node": "^17.0.13",
     "@types/parse-data-url": "^3.0.0",
     "@types/react": "^17.0.38",
     "@types/react-dom": "^17.0.11",
     "eslint": "^8.8.0",
-    "eslint-config-airbnb": "^19.0.4",
-    "eslint-config-airbnb-typescript": "^16.1.0",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-import-resolver-typescript": "^2.5.0",
-    "eslint-plugin-import": "^2.25.4",
-    "eslint-plugin-prettier": "^4.0.0",
-    "eslint-plugin-react": "^7.28.0",
-    "eslint-plugin-react-hooks": "^4.3.0",
-    "eslint-plugin-sort-export-all": "^1.2.1",
     "np": "^7.6.0",
     "prettier": "^2.5.1",
     "rimraf": "^3.0.2",

package/src/adapter-nextjs/getNewsroomServerSideProps.ts

@@ -1,11 +1,17 @@
+import type { Story } from '@prezly/sdk';
 import type { GetServerSidePropsContext } from 'next';
 
 import { getPrezlyApi } from '../data-fetching';
 
 interface Options {
     loadHomepageContacts?: boolean;
+    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 = {},
@@ -13,7 +19,7 @@ export async function getNewsroomServerSideProps(
     const { req: request, locale } = context;
 
     const api = getPrezlyApi(request);
-    const serverSideProps = await api.getNewsroomServerSideProps(request, locale);
+    const serverSideProps = await api.getNewsroomServerSideProps(request, locale, options.story);
 
     if (options.loadHomepageContacts) {
         serverSideProps.newsroomContextProps.contacts = await api.getNewsroomContacts();

package/src/adapter-nextjs/processRequest.ts

@@ -2,8 +2,17 @@ import type { GetServerSidePropsContext, GetServerSidePropsResult } from 'next';
 
 import { getShortestLocaleCode } from '../data-fetching';
 import { getRedirectToCanonicalLocale, LocaleObject } from '../intl';
-import { PageProps, ServerSidePageProps } from '../types';
+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

@@ -1,14 +1,15 @@
-import PrezlySDK, {
+import type {
     Category,
     ExtraStoryFields,
     Newsroom,
     NewsroomLanguageSettings,
     Story,
 } from '@prezly/sdk';
+import PrezlySDK from '@prezly/sdk';
 import type { IncomingMessage } from 'http';
 
 import { LocaleObject } from '../../intl';
-import { PageProps, ServerSidePageProps } from '../../types';
+import type { PageProps, ServerSidePageProps } from '../../types';
 import { DEFAULT_PAGE_SIZE } from '../constants';
 import { getAlgoliaSettings } from '../lib/getAlgoliaSettings';
 
@@ -48,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) {
@@ -76,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();
@@ -194,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

@@ -4,13 +4,13 @@ import { getEnvVariables } from '../lib/getEnvVariables';
 
 import { PrezlyApi } from './PrezlyApi';
 
-export const getPrezlyApi = (req?: IncomingMessage): PrezlyApi => {
-    if (process.browser) {
+export function getPrezlyApi(req?: IncomingMessage): PrezlyApi {
+    if (typeof window !== 'undefined') {
         throw new Error('"getPrezlyApi" should only be used on back-end side.');
     }
 
     // `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 const 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/api/queries.ts

@@ -8,15 +8,17 @@ const publishedAndPublic = [
     { visibility: { $in: ['public'] } },
 ];
 
-export const getSlugQuery = (newsroomUuid: string, slug: string) => ({
-    $and: [
-        { 'newsroom.uuid': { $in: [newsroomUuid] } },
-        { slug: { $eq: slug } },
-        ...publishedAndAccessible,
-    ],
-});
-
-export const getStoriesQuery = (newsroomUuid: string, categoryId?: number, localeCode?: string) => {
+export function getSlugQuery(newsroomUuid: string, slug: string) {
+    return {
+        $and: [
+            { 'newsroom.uuid': { $in: [newsroomUuid] } },
+            { slug: { $eq: slug } },
+            ...publishedAndAccessible,
+        ],
+    };
+}
+
+export function getStoriesQuery(newsroomUuid: string, categoryId?: number, localeCode?: string) {
     const query: any = {
         $and: [...publishedAndPublic, { 'newsroom.uuid': { $in: [newsroomUuid] } }],
     };
@@ -30,15 +32,20 @@ export const getStoriesQuery = (newsroomUuid: string, categoryId?: number, local
     }
 
     return query;
-};
+}
 
-export const getSortByPublishedDate = (order: 'asc' | 'desc') =>
-    order === 'desc' ? '-published_at' : 'published_at';
+export function getSortByPublishedDate(order: 'asc' | 'desc') {
+    return order === 'desc' ? '-published_at' : 'published_at';
+}
 
-export const getGalleriesQuery = () => ({
-    $and: [{ status: { $eq: 'public' } }, { images_number: { $gt: 0 } }],
-});
+export function getGalleriesQuery() {
+    return {
+        $and: [{ status: { $eq: 'public' } }, { images_number: { $gt: 0 } }],
+    };
+}
 
-export const getContactsQuery = () => ({
-    $and: [{ is_featured: { $eq: true } }],
-});
+export function getContactsQuery() {
+    return {
+        $and: [{ is_featured: { $eq: true } }],
+    };
+}

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/getLocalizedCategoryData.ts

@@ -1,7 +1,7 @@
 import type { Category } from '@prezly/sdk';
 
-import { LocaleObject } from '../intl';
-import { AlgoliaCategoryRef } from '../types';
+import type { LocaleObject } from '../intl';
+import type { AlgoliaCategoryRef } from '../types';
 
 function isAlgoliaCategory(
     category: Category | AlgoliaCategoryRef,

package/src/data-fetching/getPrivacyPortalUrl.ts

@@ -1,6 +1,6 @@
 import type { Newsroom } from '@prezly/sdk';
 
-import { LocaleObject } from '../intl';
+import type { LocaleObject } from '../intl';
 
 type PrivacyPortalUrlOptions = {
     email?: string;

package/src/data-fetching/getStoryPublicationDate.tsx

@@ -1,6 +1,6 @@
 import type { Story } from '@prezly/sdk';
 
-import { AlgoliaStory } from '../types';
+import type { AlgoliaStory } from '../types';
 
 export function getStoryPublicationDate(story: Story | AlgoliaStory): Date | null {
     const { published_at } = story;

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/lib/getAlgoliaSettings.ts

@@ -1,11 +1,11 @@
 import type { IncomingMessage } from 'http';
 
-import { AlgoliaSettings } from '../types';
+import type { AlgoliaSettings } from '../types';
 
 import { getEnvVariables } from './getEnvVariables';
 
-export const getAlgoliaSettings = (req?: IncomingMessage): AlgoliaSettings => {
-    if (process.browser) {
+export function getAlgoliaSettings(req?: IncomingMessage): AlgoliaSettings {
+    if (typeof window !== 'undefined') {
         throw new Error('"getAlgoliaSettings" should only be used on back-end side.');
     }
 
@@ -26,4 +26,4 @@ export const getAlgoliaSettings = (req?: IncomingMessage): AlgoliaSettings => {
         ALGOLIA_APP_ID,
         ALGOLIA_INDEX,
     };
-};
+}

package/src/data-fetching/lib/getEnvVariables.ts

@@ -3,7 +3,7 @@ import parseDataUrl from 'parse-data-url';
 
 import type { PrezlyEnv } from '../types';
 
-const decodeJson = (json: string): Record<string, any> => {
+function decodeJson(json: string): Record<string, any> {
     try {
         const decoded = JSON.parse(json);
         if (decoded && typeof decoded === 'object') {
@@ -13,9 +13,9 @@ const decodeJson = (json: string): Record<string, any> => {
         // passthru
     }
     return {};
-};
+}
 
-const decodeHttpEnv = (header: string): Record<string, any> => {
+function decodeHttpEnv(header: string): Record<string, any> {
     if (header.startsWith('data:')) {
         const parsed = parseDataUrl(header);
         if (parsed && parsed.contentType === 'application/json') {
@@ -25,10 +25,10 @@ const decodeHttpEnv = (header: string): Record<string, any> => {
         return {}; // unsupported data-uri
     }
     return decodeJson(header);
-};
+}
 
-export const getEnvVariables = (req?: IncomingMessage): PrezlyEnv => {
-    if (process.browser) {
+export function getEnvVariables(req?: IncomingMessage): PrezlyEnv {
+    if (typeof window !== 'undefined') {
         throw new Error('"getEnvVariables" should only be used on back-end side.');
     }
 
@@ -41,4 +41,4 @@ export const getEnvVariables = (req?: IncomingMessage): PrezlyEnv => {
     }
 
     return { ...process.env };
-};
+}

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

@@ -1,4 +1,4 @@
-import { CultureRef, NewsroomLanguageSettings } from '@prezly/sdk';
+import type { CultureRef, NewsroomLanguageSettings } from '@prezly/sdk';
 
 function isOnlyCulture(culture: CultureRef, languages: NewsroomLanguageSettings[]): boolean {
     const numberOfLanguages = languages.filter(
@@ -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

@@ -1,11 +1,17 @@
 import type { Redirect } from 'next';
-import { ParsedUrlQuery, stringify } from 'querystring';
+import type { ParsedUrlQuery } from 'querystring';
+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',
@@ -55,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',
@@ -33,6 +37,7 @@ const supportedLocales = [
     'en-IE',
     'en-IL',
     'en-IN',
+    'en-JM',
     'en-JP',
     'en-KH',
     'en-KR',
@@ -104,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;
     }