@jahia/javascript-modules-library 0.5.5 → 0.6.0

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

@@ -5,6 +5,27 @@
  *
  * @returns The component to be hydrated in the browser
  */
+export declare function HydrateInBrowser<T, U>(props: Readonly<{
+    /** The React component. */
+    child: React.ComponentType<{
+        children: U;
+    } & T>;
+    /**
+     * The React component props, these props will be serialized/deserialized to be usable server
+     * and client side. The serialization is done using
+     * [devalue](https://www.npmjs.com/package/devalue) allowing most standard JS types, including
+     * `Set` and `Map`.
+     */
+    props: Omit<T & React.JSX.IntrinsicAttributes, "children">;
+    children: U;
+}>): React.JSX.Element;
+export declare function HydrateInBrowser<U>(props: Readonly<{
+    /** The React component. */
+    child: React.ComponentType<{
+        children: U;
+    }>;
+    children: U;
+}>): React.JSX.Element;
 export declare function HydrateInBrowser<T>(props: Readonly<{
     /** The React component. */
     child: React.ComponentType<T>;

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/components/render/RenderInBrowser.d.ts

@@ -14,8 +14,10 @@ export declare function RenderInBrowser<T>(props: Readonly<{
      * `Set` and `Map`.
      */
     props: T & React.JSX.IntrinsicAttributes;
+    children?: React.ReactNode;
 }>): React.JSX.Element;
 export declare function RenderInBrowser(props: Readonly<{
     /** The React component */
     child: React.ComponentType;
+    children?: React.ReactNode;
 }>): React.JSX.Element;

package/dist/core/server/components/render/internal/InBrowser.d.ts

@@ -1,6 +1,7 @@
-declare function InBrowser<T>({ child: Child, props, ssr, }: Readonly<{
+declare function InBrowser<T>({ child: Child, props, ssr, children, }: Readonly<{
     child: React.ComponentType<T>;
     props: T & React.JSX.IntrinsicAttributes;
     ssr?: boolean;
+    children?: React.ReactNode;
 }>): React.JSX.Element;
 export default InBrowser;

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 { 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;

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[];