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

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

@@ -7,21 +7,55 @@ import type {
     NewsroomLanguageSettings,
     NewsroomThemePreset,
 } from '@prezly/sdk';
-import { createContext, FunctionComponent, useMemo } from 'react';
+import type { PropsWithChildren } from 'react';
+import { createContext, useMemo } from 'react';
 
 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;
 }
 
@@ -31,7 +65,11 @@ export interface NewsroomContextProps extends Omit<NewsroomContextType, 'locale'
 
 export const NewsroomContext = createContext<NewsroomContextType | undefined>(undefined);
 
-export const NewsroomContextProvider: FunctionComponent<NewsroomContextProps> = ({
+/**
+ * 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,
     newsroom,
@@ -43,7 +81,7 @@ export const NewsroomContextProvider: FunctionComponent<NewsroomContextProps> =
     themePreset,
     algoliaSettings,
     children,
-}) => {
+}: PropsWithChildren<NewsroomContextProps>) {
     const locale = useMemo(
         () => LocaleObject.fromAnyCode(localeCode || DEFAULT_LOCALE),
         [localeCode],
@@ -67,4 +105,4 @@ export const NewsroomContextProvider: FunctionComponent<NewsroomContextProps> =
             {children}
         </NewsroomContext.Provider>
     );
-};
+}

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

@@ -1,7 +1,7 @@
 import { useNewsroomContext } from './useNewsroomContext';
 
-export const useAlgoliaSettings = () => {
+export function useAlgoliaSettings() {
     const context = useNewsroomContext();
 
     return context.algoliaSettings;
-};
+}

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

@@ -1,7 +1,7 @@
 import { useNewsroomContext } from './useNewsroomContext';
 
-export const useCategories = () => {
+export function useCategories() {
     const context = useNewsroomContext();
 
     return context.categories;
-};
+}

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

@@ -1,7 +1,7 @@
 import { useNewsroomContext } from './useNewsroomContext';
 
-export const useCompanyInformation = () => {
+export function useCompanyInformation() {
     const context = useNewsroomContext();
 
     return context.companyInformation;
-};
+}

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

@@ -1,7 +1,7 @@
 import { useNewsroomContext } from './useNewsroomContext';
 
-export const useCurrentCategory = () => {
+export function useCurrentCategory() {
     const context = useNewsroomContext();
 
     return context.currentCategory;
-};
+}

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

@@ -1,7 +1,7 @@
 import { useNewsroomContext } from './useNewsroomContext';
 
-export const useCurrentLocale = () => {
+export function useCurrentLocale() {
     const context = useNewsroomContext();
 
     return context.locale;
-};
+}

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

@@ -1,7 +1,7 @@
 import { useNewsroomContext } from './useNewsroomContext';
 
-export const useCurrentStory = () => {
+export function useCurrentStory() {
     const context = useNewsroomContext();
 
     return context.currentStory;
-};
+}

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

@@ -3,12 +3,17 @@ import { useRouter } from 'next/router';
 import { useCallback } from 'react';
 
 import { getCategoryHasTranslation, getCategoryUrl } from '../../data-fetching';
-import { LocaleObject } from '../../intl';
+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();

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

@@ -1,7 +1,7 @@
 import { useNewsroomContext } from './useNewsroomContext';
 
-export const useLanguages = () => {
+export function useLanguages() {
     const context = useNewsroomContext();
 
     return context.languages;
-};
+}

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

@@ -1,7 +1,7 @@
 import { useNewsroomContext } from './useNewsroomContext';
 
-export const useNewsroom = () => {
+export function useNewsroom() {
     const context = useNewsroomContext();
 
     return context.newsroom;
-};
+}

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

@@ -1,8 +1,9 @@
 import { useContext } from 'react';
 
-import { NewsroomContext, NewsroomContextType } from '../context';
+import type { NewsroomContextType } from '../context';
+import { NewsroomContext } from '../context';
 
-export const useNewsroomContext = () => {
+export 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
     const newsroomContext: NewsroomContextType | undefined = useContext(NewsroomContext);
@@ -11,4 +12,4 @@ export const useNewsroomContext = () => {
     }
 
     return newsroomContext;
-};
+}

package/src/types.ts

@@ -1,22 +1,34 @@
-// TODO: Re-arrange the types to make them isolated to respective libs where possible
 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 type AlgoliaStory = Pick<Story, 'uuid' | 'slug' | 'title' | 'subtitle'> &
     Pick<ExtraStoryFields, 'thumbnail_image'> & {
         content_text: string;