@jahia/javascript-modules-library 0.5.6 → 0.6.1

package/README.md

@@ -1,36 +1,229 @@
-# javascript-modules-library
+# @jahia/javascript-modules-library
 
-Javascript Library for Javascript Module Engine
+This library exposes common types and utility functions for JavaScript modules running in a Jahia environment. It exposes the following APIs:
 
-## Generated types
+## Rendering components
 
-This library contains types generated from Java source code. The types are generated using a tool called java-ts-bind
-that was forked here : https://github.com/Jahia/java-ts-bind/tree/finer-excludes . You don't need to checkout this
-repository as the scripts will automatically do that for you but we mention it in case you need to make modifications
-to it.
+### `RenderInBrowser`
 
-By default, the generated types are committed in this project, but if you need to rebuild/update them, you can do so by
-using the following steps:
+This component is used to render a React component in the browser. It is used to render a component in the browser, skipping the server-side rendering step. Provided children, if any, will be rendered on the server and replaced by the component in the browser.
 
-1.  Change to the project directory :
+```tsx
+<RenderInBrowser child={MyComponent} props={{ foo: "bar" }}>
+  <div>Loading...</div>
+</RenderInBrowser>
+```
 
-    `cd types/generated`
+### `HydrateInBrowser`
 
-2.  Launch the script that will clone the java-ts-bind repository and build it from source code (it has never been released) :
+This component is used to hydrate a React component in the browser. It will be rendered on the server then hydrated in the browser. Provided children, if any, will be children of the component.
 
-    `./build.sh`
+```tsx
+<HydrateInBrowser child={MyComponent} props={{ foo: "bar" }}>
+  <div>I'm a child of MyComponent</div>
+</HydrateInBrowser>
+```
 
-3.  Update the classes and methods declared in [types/generated/package.json](types/generated/package.json) in case you added/removed classes or methods.
+### `Render`
 
-4.  Launch the script that will download all the required source code and JARs for the type generation and that will
-    also compile the source to generated the required symbols JARs. Then it will generate the types, and finally apply
-    some post-processing to the generated types to make usable :
+This component renders a Jahia component out of a node or a JS object.
 
-        `./generate.sh`
+```tsx
+// Render a JCR node
+<Render node={node} />
 
-Note that the generation will take some time on the initial build as it needs to download all the required source code
-and JARs, and build the projects from the source code.
+// Render a JS object
+<Render content={{ nodeType: "ns:nodeType" }}>
+```
 
-Once completed, the generated types will be in the following directory :
+### `RenderChild`
 
-    types/generated/build/types
+This component renders a child node of the current node. It's a thin wrapper around `Render` and `AddContentButtons`.
+
+```tsx
+<RenderChild name="child" />
+```
+
+### `RenderChildren`
+
+This component renders all children of the current node. It's a thin wrapper around `Render`, `getChildNodes` and `AddContentButtons`.
+
+```tsx
+<RenderChildren />
+```
+
+## Components
+
+### `AbsoluteArea`
+
+This component creates an absolute area in the page. It's an area of user-contributable content, child of the node of your choice.
+
+```tsx
+<AbsoluteArea name="footer" parent={renderContext.getSite().getHome()} />
+```
+
+### `Area`
+
+This component creates an area in the page. It's an area of user-contributable content that is local to the page where it is present.
+
+```tsx
+<Area name="main" />
+```
+
+### `AddContentButtons`
+
+This component renders a set of buttons to add content to the current node.
+
+```tsx
+<AddContentButtons />
+```
+
+### `AddResources`
+
+This component adds resources to the page, making sure they are loaded only once and insert them at the desired position.
+
+```tsx
+<AddResources type="css" resources="styles.css" />
+```
+
+## Declaration and registration
+
+### `jahiaComponent`
+
+This function is used to declare a Jahia component. It takes a component definition as first argument, and a React component as second argument.
+
+```tsx
+jahiaComponent(
+  {
+    componentType: "view",
+    nodeType: "ns:hello",
+  },
+  ({ name }: { name: string }) => {
+    return <h1>Hello {name}!</h1>;
+  },
+);
+```
+
+The first argument of the component function is an object containing the JCR properties of the node being rendered. The server context is passed as the second argument. See `useServerContext` for more information.
+
+## Hooks
+
+### `useGQLQuery`
+
+This hook is used to execute a GraphQL query on the current Jahia instance.
+
+```tsx
+const { data, errors } = useGQLQuery({
+  query: /* GraphQL */ `
+    query MyQuery($workspace: Workspace!) {
+      jcr(workspace: $workspace) {
+        workspace
+      }
+    }
+  `,
+  variables: {
+    workspace: "LIVE",
+  },
+});
+```
+
+### `useJCRQuery`
+
+This hook is used to execute a JCR query on the current Jahia instance.
+
+```tsx
+const pages = useJCRQuery({ query: "SELECT * FROM [jnt:page]" });
+```
+
+### `useServerContext`
+
+This hook is used to access the server context, which contains information about the current node, page, and rendering context.
+
+```tsx
+const {
+  /**
+   * Jahia's rendering context, it provides access to all kinds of context information, such as the
+   * current request, response, user, mode, mainResource and more
+   */
+  renderContext,
+  /**
+   * The current resource being rendered, which is a combination of the current node and its
+   * template/view information
+   */
+  currentResource,
+  /** The current JCR node being rendered */
+  currentNode,
+  /** The main JCR node being rendered, which is the root node of the current page */
+  mainNode,
+  /** The OSGi bundle key of the current module being rendered */
+  bundleKey,
+} = useServerContext();
+```
+
+You do not need to use this hook when rendering a component with `jahiaComponent`, as the server context is passed as the second argument of the component function.
+
+## JCR utils
+
+### `getChildNodes`
+
+This function is used to get the child nodes of a JCR node.
+
+```tsx
+const children = getChildNodes(node, limit, offset, filter);
+```
+
+### `getNodeProps`
+
+This function is used to get the properties of a JCR node.
+
+```tsx
+const { title, description } = getNodeProps(node, ["title", "description"]);
+```
+
+### `getNodesByJCRQuery`
+
+This function is used to get nodes by a JCR query.
+
+```tsx
+const pages = getNodesByJCRQuery(session, "SELECT * FROM [jnt:page]", limit, offset);
+```
+
+## URL builder
+
+### `buildEndpointUrl`
+
+This function transforms a path to an endpoint into a full URL.
+
+```tsx
+const dashboard = buildEndpointUrl("/jahia/dashboard");
+```
+
+### `buildNodeUrl`
+
+This function transforms a JCR node into a full URL to the node.
+
+```tsx
+const home = buildNodeUrl(renderContext.getSite().getHome().getNode());
+```
+
+### `buildModuleFileUrl`
+
+This function transforms a path to a file in the module into a full URL.
+
+```tsx
+const styles = buildModuleFileUrl("dist/styles.css");
+```
+
+## Java server API
+
+### `server`
+
+This variable provides access to the Java server API.
+
+```tsx
+const bundle = server.osgi.getBundle(bundleKey);
+```
+
+## Remarks
+
+This module does not contain actual implementations of the components and hooks. All accesses to `@jahia/javascript-modules-engine` must be replaced by `javascriptModulesLibraryBuilder.getSharedLibrary('@jahia/javascript-modules-engine')` in the final bundle. This is done automatically during the build process if you use [@jahia/vite-plugin](https://www.npmjs.com/package/@jahia/vite-plugin).

package/dist/core/server/components/AbsoluteArea.d.ts

@@ -1,39 +1,64 @@
 import type React from "react";
+import type { JCRNodeWrapper } from "org.jahia.services.content";
 /**
  * Generates an absolute area in which editors may insert content objects.
  *
  * @returns The AbsoluteArea component
  */
-export declare function AbsoluteArea({ name, areaView, allowedTypes, numberOfItems, subNodesView, path, editable, level, areaType, limitedAbsoluteAreaEdit, parameters, }: Readonly<{
+export declare function AbsoluteArea({ name, parent, areaView, view, allowedTypes, allowedNodeTypes, numberOfItems, readOnly, areaType, nodeType, parameters, }: Readonly<{
     /** The name of the area. */
-    name?: string;
-    /** The view to use for the area. */
+    name: string;
+    /**
+     * Parent node where the area is stored in the JCR. Can be anywhere in the JCR. The parent node
+     * must exist.
+     */
+    parent: JCRNodeWrapper;
+    /**
+     * The view to use for the area.
+     *
+     * @deprecated Use {@link #view} instead
+     */
     areaView?: string;
-    /** The allowed types for the area. */
+    /** The view to use for the area. */
+    view?: string;
+    /**
+     * The allowed types for the area.
+     *
+     * @deprecated Use {@link #allowedNodeTypes} instead
+     */
     allowedTypes?: string[];
+    /** The allowed types for the area. */
+    allowedNodeTypes?: string[];
     /** The number of items to display in the area. */
     numberOfItems?: number;
-    /** The view to use for the subnodes. */
-    subNodesView?: string;
-    /** Relative (to the current node) or absolute path to the node to include. */
-    path?: string;
     /**
-     * Enables or disables edition of this content in edit mode. Mainly used for absolute or
-     * references.
+     * Makes the area read-only.
+     *
+     * - When set to `false` (default), the area is editable on all pages.
+     * - When set to `true`, the area is read-only on all pages.
+     * - When set to `"children"`, the area is read-only on all pages except the one containing its
+     *   node.
      *
-     * @default true
+     * @default false
      */
-    editable?: boolean;
-    /** Ancestor level for absolute area - 0 is Home page, 1 first sub-pages, ... */
-    level?: number;
+    readOnly?: boolean | "children";
     /**
-     * Content type to be used to create the area
+     * Node type to be used to create the area (if the node does not exist yet)
      *
+     * @deprecated Use {@link #nodeType} instead
      * @default jnt:contentList
      */
     areaType?: string;
-    /** Is the absolute area editable everywhere or only on the page containing its node. */
-    limitedAbsoluteAreaEdit?: boolean;
-    /** The parameters to pass to the absolute area */
+    /**
+     * Node type to be used to create the area (if the node does not exist yet)
+     *
+     * @default jnt:contentList
+     */
+    nodeType?: string;
+    /**
+     * Map of custom parameters that can be passed to the backend engine for advanced logic.
+     *
+     * @deprecated Not recommended
+     */
     parameters?: Record<string, unknown>;
 }>): React.JSX.Element;

package/dist/core/server/components/AddResources.d.ts

@@ -24,7 +24,7 @@ export declare function AddResources(props: Readonly<{
      * The type of the resource. This could be 'javascript' for .js files, 'css' for .css files,
      * etc.
      */
-    type?: "javascript" | "css";
+    type?: "javascript" | "css" | "inline";
     /** The path to the resource file, relative to the module. */
     resources?: string;
     /** Inline HTML that markup will be considered as resource. */

package/dist/core/server/components/Area.d.ts

@@ -4,34 +4,50 @@ import type { JSX } from "react";
  *
  * @returns The Area component
  */
-export declare function Area({ name, areaView, allowedTypes, numberOfItems, subNodesView, path, editable, areaAsSubNode, areaType, parameters, }: Readonly<{
+export declare function Area({ name, areaView, view, allowedTypes, allowedNodeTypes, numberOfItems, readOnly, areaType, nodeType, parameters, }: Readonly<{
     /** The name of the area. */
-    name?: string;
-    /** The view to use for the area. */
+    name: string;
+    /**
+     * The view to use for the area.
+     *
+     * @deprecated Use {@link #view} instead
+     */
     areaView?: string;
-    /** The allowed types for the area. */
+    /** The view to use for the area. */
+    view?: string;
+    /**
+     * The allowed types for the area.
+     *
+     * @deprecated Use {@link #allowedNodeTypes} instead
+     */
     allowedTypes?: string[];
+    /** The allowed types for the area. */
+    allowedNodeTypes?: string[];
     /** The number of items to display in the area. */
     numberOfItems?: number;
-    /** The view to use for the subnodes. */
-    subNodesView?: string;
-    /** Relative (to the current node) or absolute path to the node to include. */
-    path?: string;
     /**
-     * Enables or disables edition of this content in edit mode. Mainly used for absolute or
-     * references.
+     * Makes the area read-only.
      *
-     * @default true
+     * @default false
      */
-    editable?: boolean;
-    /** Allow area to be stored as a subnode */
-    areaAsSubNode?: boolean;
+    readOnly?: boolean;
     /**
-     * Content type to be used to create the area
+     * Node type to be used to create the area (if the node does not exist yet)
      *
+     * @deprecated Use {@link #nodeType} instead
      * @default jnt:contentList
      */
     areaType?: string;
-    /** The parameters to pass to the area */
+    /**
+     * Node type to be used to create the area (if the node does not exist yet)
+     *
+     * @default jnt:contentList
+     */
+    nodeType?: string;
+    /**
+     * Map of custom parameters that can be passed to the backend engine for advanced logic.
+     *
+     * @deprecated Not recommended
+     */
     parameters?: Record<string, unknown>;
 }>): JSX.Element;

package/dist/core/server/components/render/HydrateInBrowser.d.ts

@@ -16,7 +16,7 @@ export declare function HydrateInBrowser<T, U>(props: Readonly<{
      * [devalue](https://www.npmjs.com/package/devalue) allowing most standard JS types, including
      * `Set` and `Map`.
      */
-    props: Omit<T & React.JSX.IntrinsicAttributes, 'children'>;
+    props: Omit<T & React.JSX.IntrinsicAttributes, "children">;
     children: U;
 }>): React.JSX.Element;
 export declare function HydrateInBrowser<U>(props: Readonly<{

package/dist/core/server/components/render/Render.d.ts

@@ -4,7 +4,7 @@ import type { JCRNodeWrapper } from "org.jahia.services.content";
  *
  * @returns The rendered output of the view for the specified content
  */
-export declare function Render({ content, node, path, editable, advanceRenderingConfig, templateType, view, parameters, }: Readonly<{
+export declare function Render({ content, node, path, readOnly, advanceRenderingConfig, templateType, view, parameters, }: Readonly<{
     /** The content node to render */
     content?: unknown;
     /** The node to render */
@@ -12,11 +12,11 @@ export declare function Render({ content, node, path, editable, advanceRendering
     /** The path to render */
     path?: string;
     /**
-     * If the content should be editable
+     * Makes the child read-only.
      *
-     * @default true
+     * @default false
      */
-    editable?: boolean;
+    readOnly?: boolean;
     /**
      * Specifies if we should render a node or simply include a view. Acceptable values are : none,
      * INCLUDE or OPTION

package/dist/core/server/components/render/RenderChild.d.ts

@@ -0,0 +1,16 @@
+import type { JSX } from "react";
+/**
+ * Renders a child of the current node, designated by its name.
+ *
+ * If the child node does not exist, it will display the "Add content" buttons.
+ */
+export declare function RenderChild({ name, view, }: {
+    /**
+     * The name of the child node to render.
+     *
+     * In the CND file, it's what's after the `+` in the child node definition: `+ name (type)`.
+     */
+    name: string;
+    /** View to use when rendering the child. */
+    view?: string | undefined;
+}): JSX.Element;

package/dist/core/server/components/render/RenderChildren.d.ts

@@ -0,0 +1,33 @@
+import type { JSX } from "react";
+import type { JCRNodeWrapper } from "org.jahia.services.content";
+/** Renders the children of the current node, and "Add content" buttons afterwards. */
+export declare function RenderChildren({ view, pagination, filter, }: {
+    /** View to use when rendering the children. */
+    view?: string | undefined;
+    /**
+     * Pagination parameters:
+     *
+     * - `{ count: number; start?: number }` to specify the number of children to display and the
+     *   starting index (defaults to 0).
+     * - `{ count: number; page: number }` to specify the number of children to display and the page
+     *   number.
+     *
+     * If not provided, all children will be displayed.
+     */
+    pagination?: {
+        count: number;
+        start?: number;
+    } | {
+        count: number;
+        page: number;
+    };
+    /**
+     * Filter to apply to the children:
+     *
+     * - A string to filter by node type.
+     * - A function to filter by custom logic.
+     *
+     * @default "jnt:content"
+     */
+    filter?: string | ((node: JCRNodeWrapper) => boolean);
+}): JSX.Element;

package/dist/core/server/framework/jahiaComponent.d.ts

@@ -15,6 +15,13 @@ export interface JahiaComponent {
     componentType: "template" | "view";
     /** The content node type the component applies to. */
     nodeType: string;
+    /**
+     * The priority of the components in case multiple templates/views are applicable to a given
+     * resource. The component with the highest priority has precedence over the other components.
+     *
+     * @default 0
+     */
+    priority?: number;
     /** Properties to add on the component, optional. */
     properties?: Record<string, string>;
 }

package/dist/core/server/hooks/useServerContext.d.ts

@@ -1,6 +1,6 @@
-import { type ReactNode } from "react";
+import { type ReactNode, type JSX } from "react";
 import type { RenderContext, Resource } from "org.jahia.services.render";
-import type { JCRNodeWrapper } from "org.jahia.services.content";
+import type { JCRNodeWrapper, JCRSessionWrapper } from "org.jahia.services.content";
 /**
  * A context object that gives access to the underlying Jahia Java objects that are part of the
  * current rendering context
@@ -20,6 +20,8 @@ export interface ServerContext {
     currentNode: JCRNodeWrapper;
     /** The main JCR node being rendered, which is the root node of the current page */
     mainNode: JCRNodeWrapper;
+    /** The JCR Session of the current user in its current language * */
+    jcrSession: JCRSessionWrapper;
     /** The OSGi bundle key of the current module being rendered */
     bundleKey: string;
 }
@@ -29,6 +31,6 @@ export interface ServerContext {
  * @returns The server context
  */
 export declare function useServerContext(): ServerContext;
-export declare function ServerContextProvider({ renderContext, currentResource, currentNode, mainNode, bundleKey, children, }: ServerContext & {
+export declare function ServerContextProvider({ renderContext, currentResource, currentNode, mainNode, jcrSession, bundleKey, children, }: ServerContext & {
     readonly children: ReactNode;
-}): React.JSX.Element;
+}): JSX.Element;

package/dist/core/server/utils/i18n.d.ts

@@ -0,0 +1,11 @@
+import type { Locale } from "java.util";
+import type { RenderContext } from "org.jahia.services.render";
+/**
+ * Returns the locales available on the site, as a record of language code (e.g. en_US) to locale
+ * object.
+ *
+ * If not provided, the `renderContext` is taken from the current server context.
+ */
+export declare function getSiteLocales({ renderContext }?: {
+    renderContext: RenderContext;
+}): Record<string, Locale>;

package/dist/core/server/utils/jcr/getChildNodes.d.ts

@@ -1,4 +1,3 @@
-import type { Node } from "javax.jcr";
 import type { JCRNodeWrapper } from "org.jahia.services.content";
 /**
  * Returns an array of child nodes of a given node.
@@ -11,4 +10,4 @@ import type { JCRNodeWrapper } from "org.jahia.services.content";
  * @param filter A function to filter the nodes to be returned.
  * @returns An array of child nodes.
  */
-export declare function getChildNodes(node: JCRNodeWrapper, limit: number, offset?: number, filter?: ((node: Node) => boolean) | undefined): Node[];
+export declare function getChildNodes(node: JCRNodeWrapper, limit?: number | undefined, offset?: number, filter?: ((node: JCRNodeWrapper) => boolean) | undefined): JCRNodeWrapper[];

package/dist/core/server/utils/jcr/getNodesByJCRQuery.d.ts

@@ -11,4 +11,4 @@ import type { JCRSessionWrapper } from "org.jahia.services.content";
  * @param offset The offset to start from
  * @returns An array containing the nodes returned by the query
  */
-export declare function getNodesByJCRQuery(session: JCRSessionWrapper, query: string, limit: number, offset?: number): Node[];
+export declare function getNodesByJCRQuery(session: JCRSessionWrapper, query: string, limit?: number | undefined, offset?: number): Node[];

package/dist/core/server/utils/urlBuilder/urlBuilder.d.ts

@@ -1,25 +1,62 @@
+import type { JCRNodeWrapper } from "org.jahia.services.content";
 import type { RenderContext, Resource } from "org.jahia.services.render";
 /** Initialize the registry with default url builders */
 export declare function initUrlBuilder(): void;
 /**
- * Provide URL generation for contents/files If parameters are not valid, or if a node couldn't be
- * found, it will log an warning and return '#'
+ * Generate a Jahia url for the provided node.
  *
- * @param renderContext The current renderContext
- * @param currentResource The current resource
  * @returns The final URL
  */
-export declare function buildUrl(props: {
-    /** The path of the resource to build the URL for */
-    value?: string;
-    /** The path of the resource to build the URL for */
-    path?: string;
-    /** The parameters to append to the URL */
+export declare function buildNodeUrl(
+/** The node to build the URL for */
+node: JCRNodeWrapper, config?: {
+    /** The querystring parameters to append to the URL */
     parameters?: Record<string, string>;
-    /** The mode to use to build the URL */
-    mode?: string;
-    /** The language to use to build the URL */
+    /**
+     * The mode to use to build the URL. Defines the mode or override the one provided by the
+     * renderContext.
+     */
+    mode?: "edit" | "preview" | "live";
+    /**
+     * The language to use to build the URL. Defines the languages or overrides the one provided by
+     * the current resource
+     */
     language?: string;
-    /** The extension to use to build the URL */
+    /**
+     * The extension to use to build the URL. Defines the extension or overrides the one provided by
+     * the current resource
+     */
     extension?: string;
-}, renderContext: RenderContext, currentResource: Resource): string;
+}, context?: {
+    /** Provided in react context, but you need to provide one otherwise. * */
+    renderContext?: RenderContext;
+    /** Provided in react context, you need to provide one otherwise. * */
+    currentResource?: Resource;
+}): string;
+/**
+ * Build a URL for a file in a module. Note that to be accessible, the folder that contains the file
+ * must be part of the jahia.static-resources in package.json.
+ *
+ * The URL must not be absolute (start with a / or a protocol).
+ */
+export declare function buildModuleFileUrl(
+/** Relative path of the file from the module's root (examples: css/my.css, images/myImage.webp) */
+filePath: string, config?: {
+    /** Defines a custom module name to access its files */
+    moduleName?: string;
+    /** Querystring parameters to append to the URL */
+    parameters?: Record<string, string>;
+}, context?: {
+    /** Provided in react context, you need to provide one (or the module name) otherwise. */
+    renderContext?: RenderContext;
+}): string;
+/** Build an url for any endpoint on the server (/cms/*, /graphql, ect). */
+export declare function buildEndpointUrl(
+/** Endpoint to call */
+endpoint: string, config?: {
+    /** Querystring parameters to append to the URL */
+    parameters?: Record<string, string>;
+}, context?: {
+    /** Provided in react context, you need to provide one otherwise. */
+    renderContext?: RenderContext;
+}): string;

package/dist/globals.d.ts

@@ -17,6 +17,7 @@ declare module "virtual:jahia-server" {
   import type {
     ConfigHelper,
     GQLHelper,
+    JcrHelper,
     OSGiHelper,
     RegistryHelper,
     RenderHelper,
@@ -28,6 +29,8 @@ declare module "virtual:jahia-server" {
   const server: {
     /** This helper provides access to OSGi configuration */
     config: ConfigHelper;
+    /** This helper allows to perform JCR operations */
+    jcr: JcrHelper;
     /** This helper provides access Jahia's GraphQL API, to execute queries and mutations */
     gql: GQLHelper;
     /** This helper provides access to OSGi bundle for resource loading and service access */