@enonic/nextjs-adapter 5.0.0-beta.1 → 5.0.0-beta.3

package/README.md

@@ -27,7 +27,7 @@ import {fetchContent} from "@enonic/nextjs-adapter/server";
 import MainView from "@enonic/nextjs-adapter/views/MainView"
 
 // ...
-const props = await fetchContent({
+const props = await fetchContent(path, {
     contentPath: '/content/path',
     locale: 'en',
 });
@@ -44,13 +44,13 @@ They are available at `@enonic/nextjs-adapter/server`
 
 <br/>
 
-#### <a id="fetch-content"></a>`fetchContent(context: Context) => Promise<FetchContentResult>`
+#### <a id="fetch-content"></a>`fetchContent(contentPath: string | string[], context: Context) => Promise<FetchContentResult>`
 
 Fetches the content/component by path with component queries optimization, page structure as well as runtime info calculation. This is the
 main method for querying content.
 
-| Argument  | Description       |
-|-----------|-------------------|
+| Argument | Description       |
+|----------|-------------------|
 | `context` | Execution context |
 
 Usage:
@@ -85,22 +85,28 @@ type FetchContentResult = {
 
 <br/>
 
-#### <a id="fetch-guillotine"></a>`fetchGuillotine(contentApiUrl: string, options?: FetchOptions) => Promise<GuillotineResult>`
+#### <a id="fetch-guillotine"></a>`fetchGuillotine(apiUrl: string, mapping: LocaleMapping, options?: FetchOptions) => Promise<GuillotineResult>`
 
 Makes a custom request to Guillotine. Used by [fetchContent()](#fetch-content) method.
 
-| Argument        | Description                                     |
-|-----------------|-------------------------------------------------|
-| `contentApiUrl` | Guillotine API URL                              |
-| `options`       | Request and Next.js config options _(Optional)_ |
+| Argument  | Description                                       |
+|-----------|---------------------------------------------------|
+| `apiUrl`  | Guillotine API URL                                |
+| `mapping` | [Mapping](#locale-mapping-type) locale to project |
+| `options` | Request and Next.js config options _(Optional)_   |
 
 Usage:
 
 ```tsx
 import {fetchGuillotine} from '@enonic/nextjs-adapter/server';
+import {getLocaleMapping} from '@enonic/nextjs-adapter';
 
 const apiUrl = 'http://domain:8000/graphql/api';
 
+const mapping = getLocaleMapping({
+    contentPath: '/current/content/path',
+});
+
 const body = {
     query: 'qraphql query as string',
     variables: {
@@ -122,7 +128,7 @@ const opts = {
     }
 };
 
-const result = fetchGuillotine(apiUrl, opts);
+const result = fetchGuillotine(apiUrl, mapping, opts);
 ```
 
 Response type:
@@ -139,22 +145,28 @@ type GuillotineResult = {
 
 <br/>
 
-#### `fetchFromApi(apiUrl: string, options?: FetchOptions) => Promise<GuillotineResponseJson>`
+#### `fetchFromApi(apiUrl: string, mapping: LocaleMapping, options?: FetchOptions) => Promise<GuillotineResponseJson>`
 
 Makes custom third-party service request. Used by the [fetchGuillotine()](#fetch-guillotine) method.
 
-| Argument  | Description                                     |
-|-----------|-------------------------------------------------|
-| `apiUrl`  | Service API URL                                 |
-| `options` | Request and Next.js config options _(Optional)_ |
+| Argument  | Description                                       |
+|-----------|---------------------------------------------------|
+| `apiUrl`  | Service API URL                                   |
+| `mapping` | [Mapping](#locale-mapping-type) locale to project |
+| `options` | Request and Next.js config options _(Optional)_   |
 
 Usage:
 
 ```tsx
 import {fetchFromApi} from '@enonic/nextjs-adapter/server';
+import {getLocaleMapping} from '@enonic/nextjs-adapter';
 
 const apiUrl = 'http://domain:8000/graphql/api';
 
+const mapping = getLocaleMapping({
+    contentPath: '/current/content/path',
+});
+
 const body = {
     query: 'qraphql query as string',
     variables: {
@@ -176,22 +188,22 @@ const opts = {
     }
 };
 
-const result = fetchFromApi(apiUrl, opts);
+const result = fetchFromApi(apiUrl, mapping, opts);
 ```
 
 <br/>
 
-#### <a id="fetch-paths-for-all-locales"></a>
-`fetchContentPathsForAllLocales(query?: string, countPerLocale?: number) => Promise<ContentPathItem[]>`
+#### <a id="fetch-paths-for-all-locales"></a>`fetchContentPathsForAllLocales(path: string, query?: string, count?: number) => Promise<ContentPathItem[]>`
 
 Loads all content paths for all locales. Generally used for static site generation.
 
-| Argument         | Description                                               |
-|------------------|-----------------------------------------------------------|
-| `query`          | Custom GraphQL query _(Optional)_ *                       |
-| `countPerLocale` | Max result count per locale _(Optional, defaults to 999)_ |
+| Argument | Description                                       |
+|----------|---------------------------------------------------|
+| `path`   | Root content path                                 |
+| `query`  | Request and Next.js config options _(Optional)_ * |
+| `count`  | Max result count _(Optional, defaults to 999)_    |
 
-&ast; Default query gets up to `countPerLocale` results, sorts them by `modifiedTime` and excludes following content types:
+&ast; Default query gets up to `count` results, sorts them by `modifiedTime` and excludes following content types:
 
 ```
 "base:shortcut", 
@@ -206,21 +218,22 @@ Usage:
 ```tsx
 import {fetchContentPathsForAllLocales} from '@enonic/nextjs-adapter/server';
 
-const contentPaths = fetchContentPathsForAllLocales('custom graphql query', 1001);
+const contentPaths = fetchContentPathsForLocale('/site-name', 'custom graphql query', 1001);
 ```
 
 <br/>
 
-#### `fetchContentPathsForLocale(mapping: LocaleMapping, query?: string, count?: number) => Promise<ContentPathItem[]>`
+#### `fetchContentPathsForLocale(path: string, mapping: LocaleMapping, query?: string, count?: number) => Promise<ContentPathItem[]>`
 
 Loads all content paths for the current locale. Generally used for static site generation.
 Used by [fetchContentPathsForAllLocales()](#fetch-paths-for-all-locales)
 
-| Argument  | Description                                                                           |
-|-----------|---------------------------------------------------------------------------------------|
-| `mapping` | [Mapping](#locale-mapping-type) locale to project                                     |
-| `query`   | Custom GraphQL query _(Optional, [default value here](#fetch-paths-for-all-locales))_ |
-| `count`   | Max result count _(Optional, defaults to 999)_                                        |
+| Argument  | Description                                                                                         |
+|-----------|-----------------------------------------------------------------------------------------------------|
+| `path`    | Root content path                                                                                   |
+| `mapping` | [Mapping](#locale-mapping-type) locale to project                                                   |
+| `query`   | Request and Next.js config options _(Optional, [default value here](#fetch-paths-for-all-locales))_ |
+| `count`   | Max result count _(Optional, defaults to 999)_                                                      |
 
 Usage:
 
@@ -232,7 +245,7 @@ const mapping = getLocaleMapping({
     contentPath: '/current/content/path',
 });
 
-const contentPaths = fetchContentPathsForLocale(mapping, 'custom graphql query', 1001);
+const contentPaths = fetchContentPathsForLocale('/', mapping, 'custom graphql query', 1001);
 ```
 
 <br/>
@@ -326,6 +339,29 @@ const urlRelativeToViewer = getUrl('/some/content/url', meta);
 
 <br/>
 
+#### <a id="get-asset"></a>`getAsset(url: string, meta: MetaData) => string`
+
+Converts a local asset URL to relative one for current viewer (Next.js/Enonic XP). It doesn't append locales unlike the [getUrl()](#get-url).
+
+> **INFO:** For your URLs to work both in Enonic XP and Next.js you need to:
+> 1. Use relative URL to local asset
+> 2. Wrap them with `getAsset()` function in the views
+
+| Argument | Description                                             |
+|----------|---------------------------------------------------------|
+| `url`    | asset URL you want to transform                         |
+| `meta`   | Runtime data returned by [fetchContent](#fetch-content) |
+
+Usage:
+
+```tsx
+import {getAsset} from '@enonic/nextjs-adapter';
+
+const urlRelativeToViewer = getAsset('/some/asset/url', meta);
+```
+
+<br/>
+
 #### <a id="rich-text-query"></a>`richTextQuery(fieldName: string) => string`
 
 This is a utility function for querying for `RichTextData` needed for [RichTextView](#rich-text-view). It creates a graphql query string for
@@ -355,8 +391,7 @@ const query = `query($path:ID!){
 
 #### `validateData(props: FetchContentResult) => void`
 
-Utility method to validate data returned by [fetchContent()](#fetch-content) method. Throws an error or calls Next.js `notFound()` if data
-is invalid. Also prevents shortcut content types from being rendered in preview/edit modes.
+Utility method to validate data returned by [fetchContent()](#fetch-content) method. Throws an error or notFound() if data is invalid. Also prevents shortcut content types from being rendered in preview/edit modes.
 
 | Argument | Description                 |
 |----------|-----------------------------|
@@ -368,7 +403,7 @@ Usage:
 import {fetchContent} from '@enonic/nextjs-adapter/server';
 import {validateData} from '@enonic/nextjs-adapter';
 
-const data = await fetchContent({
+const data = fetchContent({
     contentPath: '/path/to/content',
     locale: 'en',
 });
@@ -378,71 +413,6 @@ validateData(data);
 
 <br/>
 
-#### <a id="get-content-branch"></a>`getContentBranch(context?: Context) => string`
-
-Resolves the Enonic XP branch (`master` or `draft`) for the current request based on its render mode.
-Returns `master` for `LIVE` and `NEXT` render modes, and `draft` otherwise (e.g. `EDIT`, `PREVIEW`, `INLINE`).
-
-| Argument  | Description                   |
-|-----------|-------------------------------|
-| `context` | `Context` object _(Optional)_ |
-
-Usage:
-
-```tsx
-import {getContentBranch} from '@enonic/nextjs-adapter';
-
-const branch = getContentBranch({
-    contentPath: '/current/content/path',
-    locale: 'en',
-});
-```
-
-<br/>
-
-#### <a id="encrypt-params"></a>`encryptParams(params: Record<string, any>, secret: string) => string`
-
-Symmetrically encrypts a params object into a base64url string using AES-256-GCM. The `secret` is hashed with SHA-256
-to derive the key, so any string length works. Pair with [decryptParams()](#decrypt-params) to read the value back.
-
-| Argument | Description                                     |
-|----------|-------------------------------------------------|
-| `params` | Plain object to encrypt                         |
-| `secret` | Secret string used to derive the encryption key |
-
-Usage:
-
-```tsx
-import {encryptParams} from '@enonic/nextjs-adapter';
-
-const blob = encryptParams({userId: '123', role: 'editor'}, process.env.ENONIC_API_TOKEN);
-```
-
-<br/>
-
-#### <a id="decrypt-params"></a>`decryptParams(blob: string, secret: string) => Record<string, any> | null`
-
-Decrypts a base64url string produced by [encryptParams()](#encrypt-params). Returns `null` if the input is malformed,
-tampered with, or was encrypted with a different secret.
-
-| Argument | Description                                  |
-|----------|----------------------------------------------|
-| `blob`   | Base64url string produced by `encryptParams` |
-| `secret` | Same secret used during encryption           |
-
-Usage:
-
-```tsx
-import {decryptParams} from '@enonic/nextjs-adapter';
-
-const params = decryptParams(blob, process.env.ENONIC_API_TOKEN);
-if (params) {
-    // use params.userId, params.role, ...
-}
-```
-
-<br/>
-
 ### `ComponentRegistry`
 
 Registry containing definitions of all components (i.e. pages, parts, layouts, macros, etc. ). It is used in the runtime by `nextjs-adapter`
@@ -465,12 +435,9 @@ import {ComponentRegistry} from '@enonic/nextjs-adapter';
 
 const query = {
     query: 'graphql query',
-    variables: ({path, siteKey, branch, project}, context, config) => {
+    variables: (path, context, config) => {
         return {
-            path: path + '/some/processing',
-            siteKey,
-            branch,
-            project,
+            path: path + '/some/processing'
         };
     }
 }
@@ -487,17 +454,6 @@ Gets the common query definition.
 <a id="query-def"></a>Response type:
 
 ```tsx
-interface GlobalVariables {
-    path: string;
-    siteKey: string;
-    branch: string;
-    project: string;
-}
-
-type QueryGetter = (vars: GlobalVariables, context?: Context, config?: any) => string;
-
-type VariablesGetter = (vars: GlobalVariables, context?: Context, config?: any) => GlobalVariables & Record<string, any>;
-
 type SelectedQueryMaybeVariablesFunc =
     string |
     QueryGetter |
@@ -548,17 +504,17 @@ interface ComponentDefinition {
 
 <br/>
 
-#### `static addMacro(name: string, obj: ComponentDefinitionParams): void`
+#### `static addMacro(name: string, obj: ComponentDefinition): void`
 
-#### `static addPart(name: string, obj: ComponentDefinitionParams): void`
+#### `static addPart(name: string, obj: ComponentDefinition): void`
 
-#### `static addLayout(name: string, obj: ComponentDefinitionParams): void`
+#### `static addLayout(name: string, obj: ComponentDefinition): void`
 
-#### `static addPage(name: string, obj: ComponentDefinitionParams): void`
+#### `static addCPage(name: string, obj: ComponentDefinition): void`
 
-#### `static addContentType(name: string, obj: ComponentDefinitionParams): void`
+#### `static addContentType(name: string, obj: ComponentDefinition): void`
 
-#### `static addComponent(name: string, obj: ComponentDefinitionParams): void`
+#### `static addComponent(name: string, obj: ComponentDefinition): void`
 
 Saves the component definition in ComponentRegistry by name.
 
@@ -614,19 +570,19 @@ Response type: [component definition](#comp-def)
 
 <br/>
 
-#### `static getMacros(): [string, ComponentDefinition][]`
+#### `static getMacros(): ComponentDefinition[]`
 
-#### `static getParts(): [string, ComponentDefinition][]`
+#### `static getParts(): ComponentDefinition[]`
 
-#### `static getLayouts(): [string, ComponentDefinition][]`
+#### `static getLayouts(): ComponentDefinition[]`
 
-#### `static getPages(): [string, ComponentDefinition][]`
+#### `static getPages(): ComponentDefinition[]`
 
-#### `static getContentTypes(): [string, ComponentDefinition][]`
+#### `static getContentTypes(): ComponentDefinition[]`
 
-#### `static getComponents(): [string, ComponentDefinition][]`
+#### `static getComponents(): ComponentDefinition[]`
 
-Gets all component entries (`[name, definition]` tuples) stored in ComponentRegistry.
+Gets all component definitions stored in ComponentRegistry.
 
 > **NOTE:** Read [addComponent](#add-comp) note before using `getComponents`.
 
@@ -638,7 +594,7 @@ import {ComponentRegistry} from '@enonic/nextjs-adapter';
 const macros = ComponentRegistry.getMacros();
 ```
 
-Response type: list of `[name, ComponentDefinition]` tuples — see [component definition](#comp-def).
+Response type: List of [component definitions](#comp-def)
 
 <br/>
 
@@ -653,7 +609,7 @@ Helper singleton for processing URLs.
 Processes the absolute URL to become relative for the current viewer, while keeping in mind Next.js assets and Enonic XP binary content
 links
 
-> **NOTE:** There is a convenience alias to this function called [getUrl()](#get-url)
+> **NOTE:** There are convenience aliases to this function called [getUrl()](#get-url) and [getAsset()](#get-asset)
 
 | Argument     | Description                                                                  |
 |--------------|------------------------------------------------------------------------------|
@@ -691,6 +647,26 @@ const url = UrlProcessor.processSrcSet('<srcset value>', meta);
 
 <br/>
 
+#### `static setSiteKey(key: string): void`
+
+> **DEPRECATED:** It is automatically done by `nextjs-adapter` now and have no effect.
+
+Sets the site key value that is needed for correct absolute URL processing.
+
+| Argument | Description |
+|----------|-------------|
+| `key`    | Site key    |
+
+Usage:
+
+```tsx
+import {UrlProcessor} from '@enonic/nextjs-adapter';
+
+UrlProcessor.setSiteKey('<site key>');
+```
+
+<br/>
+
 #### `static isMediaLink(ref: string, linkData: LinkData[]): boolean`
 
 Checks if link data array contains link with provided ref. Positive result means that this is a link to Enonic XP content.
@@ -808,7 +784,7 @@ const mapping = getLocaleMappingByLocale('en', true);
 
 <br/>
 
-#### `getRequestLocaleInfo(context: Context): LocaleInfo`
+#### `getRequestLocaleInfo(context: Context): LocaleMapping`
 
 Attempts to get the locale info from the request. Along with that it also returns the default locale and all configured locales.
 
@@ -927,9 +903,9 @@ There is also a number of utility constants and functions available at `@enonic/
 
 <br/>
 
-All of the following are exported from `@enonic/nextjs-adapter`:
-
 ```tsx
+import {CATCH_ALL} from './constants';
+
 IS_DEV_MODE;                // True if current mode == development
 
 APP_NAME;                   // Name of the app defined in .env files
@@ -977,9 +953,10 @@ enum XP_COMPONENT_TYPE {    // Enum for XP component types
 
 // Sanitizes text according to graphql naming spec http://spec.graphql.org/October2021/#sec-Names
 const sanitizeGraphqlName = (text: string) => string;
-```
 
-See also: [getContentBranch](#get-content-branch), [encryptParams](#encrypt-params), [decryptParams](#decrypt-params).
+// Returns full content api URL with current project and branch appended
+const getContentApiUrl = (context: Context) => string;
+```
 
 ### Views
 
@@ -1002,13 +979,10 @@ Usage:
 
 ```tsx
 import MainView from '@enonic/nextjs-adapter/views/MainView';
-import {fetchContent} from '@enonic/nextjs-adapter/server';
+import fetchContent from '@enonic/nextjs-adapter';
 
 export async function getServerSideProps(context: Context) {
-    const props = await fetchContent({
-        contentPath: '/content/path',
-        locale: 'en',
-    });
+    const props = fetchContent('/content/path', context);
     return {
         props
     }
@@ -1019,37 +993,37 @@ export default MainView;
 
 <br/>
 
-#### `<StaticContent condition={true} element="div">`
+#### `<StaticContent condition="true" tag="div">`
 
 Tag for disabling client side hydration if the condition is true. This will remove interactivity from children.
 
 | Argument           | Type      | Description                        |
 |--------------------|-----------|------------------------------------|
 | `condition = true` | `Boolean` | Condition to trigger static output |
-| `element = 'div'`  | `String`  | Html tag to use for static output  |
+| `tag = 'div'`      | `String`  | Html tag to use for static output  |
 
 Usage:
 
 ```tsx
 import StaticContent from '@enonic/nextjs-adapter/views/StaticContent';
 
-<StaticContent condition={true} element="div"> ...child elements... </StaticContent>
+<StaticContent condition={true} tag="div"> ...child elements... </StaticContent>
 ```
 
 <br/>
 
-#### <a id="rich-text-view"></a>
-`<RichTextView className="css-class" tag="section" data={data} meta={meta} customReplacer={customReplacerFn}>`
+#### <a id="rich-text-view"></a>`<RichTextView className="css-class" tag="section" data={data} meta={meta}, renderMacroInEditMode="true", customReplacer={customReplacerFn}>`
 
 Tag for displaying contents of html area input types. Takes care of processing macros, URLs and images inside.
 
-| Argument         | Type           | Description                                                                                       |
-|------------------|----------------|---------------------------------------------------------------------------------------------------|
-| `data`           | `RichTextData` | Rich text data                                                                                    |
-| `meta`           | `MetaData`     | Runtime data returned by fetchContent method.                                                     |
-| `customReplacer` | `Replacer`     | Function to do custom element processing. Not invoked for image, link and macro nodes. _Optional_ |
-| `className`      | `String`       | Class name to add to the root html element. _Optional_                                            |
-| `tag = 'div'`    | `String`       | Html tag to use as a root                                                                         |
+| Argument                       | Type           | Description                                                                                       |
+|--------------------------------|----------------|---------------------------------------------------------------------------------------------------|
+| `data`                         | `RichTextData` | Rich text data                                                                                    |
+| `meta`                         | `MetaData`     | Runtime data returned by fetchContent method.                                                     |
+| `customReplacer`               | `Replacer`     | Function to do custom element processing. Not invoked for image, link and macro nodes. _Optional_ |
+| `className`                    | `String`       | Class name to add to the root html element. _Optional_                                            |
+| `renderMacroInEditMode = true` | `boolean`      | Flag passed to macros telling if they should render themselves in edit mode                       |
+| `tag = 'div'`                  | `String`       | Html tag to use as a root                                                                         |
 
 > **TIP!** There is a utility function [richTextQuery(fieldName)](#rich-text-query) generating part of the graphql query to
 > obtain `RichTextData` for html area input types.
@@ -1059,7 +1033,7 @@ Usage:
 ```tsx
 import RichTextView from '@enonic/nextjs-adapter/views/RichTextView';
 
-<RichTextView data={richTextData} meta={meta} tag="section" className="rich-text-view"></RichTextView>
+<RichTextView data={richTextData} meta={meta} tag="section" className="rich-text-view" renderMacroInEditMode="false"></RichTextView>
 ```
 
 <br/>
@@ -1079,7 +1053,7 @@ All necessary data can be acquired by running [fetchContent()](#fetch-content)
 Usage:
 
 ```tsx
-import Regions from '@enonic/nextjs-adapter/views/Region';
+import StaticContent from '@enonic/nextjs-adapter/views/StaticContent';
 
-<Regions page={page} meta={meta} name="main" common={common}/>
+<StaticContent condition={true} tag="div"> ...child elements... </StaticContent>
 ```

package/dist/common/UrlProcessor.d.ts

@@ -7,13 +7,19 @@ export declare class UrlProcessor {
     static LINK_ATTR: string;
     static MACRO_ATTR: string;
     private static IMG_ATMT_REGEXP;
+    private static endSlashPattern;
+    private static startSlashPattern;
+    private static localhostPattern;
     static process(url: string, meta: MetaData, serverSide?: boolean, isResource?: boolean): string;
-    private static normalizeBaseUrl;
+    static setSiteKey(key: string): void;
     static isMediaLink(ref: string, linkData: LinkData[]): boolean;
     static isContentImage(ref: string, imageData: ImageData[]): boolean;
     static processSrcSet(srcset: string, meta: MetaData): string;
+    private static stripApiUrl;
     private static isAttachmentUrl;
     private static startsWithHash;
-    private static isAbsolute;
+    private static isRelative;
+    private static getApiUrl;
 }
 export declare function getUrl(url: string, meta: MetaData): string;
+export declare function getAsset(url: string, meta: MetaData): string;