@jahia/javascript-modules-library 0.3.0 → 0.5.1

package/README.md

@@ -1,35 +1,36 @@
 # javascript-modules-library
-Javascript Library for NPM Javascript Module Engine
+
+Javascript Library for Javascript Module Engine
 
 ## Generated types
 
 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 
+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.
 
 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:
 
-1. Change to the project directory :
+1.  Change to the project directory :
 
     `cd types/generated`
 
-2. Launch the script that will clone the java-ts-bind repository and build it from source code (it has never been released) :
+2.  Launch the script that will clone the java-ts-bind repository and build it from source code (it has never been released) :
 
     `./build.sh`
 
-3. Update the classes and methods declared in [types/generated/package.json](types/generated/package.json) in case you added/removed classes or methods.
+3.  Update the classes and methods declared in [types/generated/package.json](types/generated/package.json) in case you added/removed classes or methods.
 
-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 :
+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 :
 
-    `./generate.sh`
+        `./generate.sh`
 
 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.
 
-Once completed, the generated types will be in the following directory : 
+Once completed, the generated types will be in the following directory :
 
     types/generated/build/types

package/bin/jahia-deploy.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import dotenv from "dotenv";
+import { execSync } from "node:child_process";
+import path from "node:path";
+
+dotenv.config();
+
+const deployMethod = process.env.JAHIA_DEPLOY_METHOD;
+
+const packageFilePath = path.resolve("dist/package.tgz");
+
+if (deployMethod === "curl") {
+  console.log("Deploying URL curl to Jahia bundles REST API...");
+  console.log(
+    execSync(
+      `curl -s --user ${process.env.JAHIA_USER} --form bundle=@${packageFilePath} --form start=true ${process.env.JAHIA_HOST}/modules/api/bundles`,
+      { encoding: "utf8" },
+    ),
+  );
+} else {
+  console.log("Deploying using Docker copy...");
+  console.log(
+    execSync(`docker cp ${packageFilePath} ${process.env.JAHIA_DOCKER_NAME}:/var/jahia/modules`, {
+      encoding: "utf8",
+    }),
+  );
+}

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

@@ -0,0 +1,39 @@
+import type React from "react";
+/**
+ * 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<{
+    /** The name of the area. */
+    name?: string;
+    /** The view to use for the area. */
+    areaView?: string;
+    /** The allowed types for the area. */
+    allowedTypes?: 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.
+     *
+     * @default true
+     */
+    editable?: boolean;
+    /** Ancestor level for absolute area - 0 is Home page, 1 first sub-pages, ... */
+    level?: number;
+    /**
+     * Content type to be used to create the area
+     *
+     * @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 */
+    parameters?: Record<string, unknown>;
+}>): React.JSX.Element;

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

@@ -0,0 +1,47 @@
+import type { JSX } from "react";
+/**
+ * Generates add content buttons for a content object
+ *
+ * @returns The add content buttons.
+ */
+export declare function AddContentButtons(props: Readonly<{
+    /** The node types to add. */
+    nodeTypes?: string[];
+    /**
+     * The child name.
+     *
+     * @default *
+     */
+    childName?: string;
+    /**
+     * If true, the edit check will be performed.
+     *
+     * @default false
+     */
+    editCheck?: boolean;
+}>): JSX.Element;
+/**
+ * Change nodeTypes="type1 type2 type3" to nodeTypes={["type1", "type2", "type3"]}
+ *
+ * @deprecated
+ */
+export declare function AddContentButtons(props: Readonly<{
+    /**
+     * Change nodeTypes="type1 type2 type3" to nodeTypes={["type1", "type2", "type3"]}
+     *
+     * @deprecated
+     */
+    nodeTypes?: string;
+    /**
+     * The child name.
+     *
+     * @default *
+     */
+    childName?: string;
+    /**
+     * If true, the edit check will be performed.
+     *
+     * @default false
+     */
+    editCheck?: boolean;
+}>): JSX.Element;

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

@@ -0,0 +1,63 @@
+import type { JSX } from "react";
+/**
+ * Adds a resources to the head tag of the HTML page.
+ *
+ * @returns A React element that renders a script or link tag.
+ */
+export declare function AddResources(props: Readonly<{
+    /**
+     * If true, the resource will be inserted into the document. Typically used for on-demand
+     * loading of resources.
+     */
+    insert?: boolean;
+    /**
+     * If true, the resource will be loaded asynchronously. For scripts, this means the script will
+     * be executed as soon as it's available, without blocking the rest of the page.
+     */
+    async?: boolean;
+    /**
+     * If true, the resource will be deferred, i.e., loaded after the document has been parsed. For
+     * scripts, this means the script will not be executed until after the page has loaded.
+     */
+    defer?: boolean;
+    /**
+     * The type of the resource. This could be 'javascript' for .js files, 'css' for .css files,
+     * etc.
+     */
+    type?: "javascript" | "css";
+    /** The path to the resource file, relative to the module. */
+    resources?: string;
+    /** Inline HTML that markup will be considered as resource. */
+    inlineResource?: string;
+    /**
+     * The title of the resource. This is typically not used for scripts or stylesheets, but may be
+     * used for other types of resources.
+     */
+    title?: string;
+    /**
+     * A unique key for the resource. This could be used to prevent duplicate resources from being
+     * added to the document.
+     */
+    key?: string;
+    /**
+     * The HTML tag where the resource should be added. This could be 'head' for resources that
+     * should be added to the <head> tag, 'body' for resources that should be added to the <body>
+     * tag, etc.
+     */
+    targetTag?: "head" | "body";
+    /**
+     * The relationship of the resource to the document. This is typically 'stylesheet' for CSS
+     * files.
+     */
+    rel?: string;
+    /**
+     * The media for which the resource is intended. This is typically used for CSS files, with
+     * values like 'screen', 'print', etc.
+     */
+    media?: string;
+    /**
+     * A condition that must be met for the resource to be loaded. This could be used for
+     * conditional comments in IE, for example.
+     */
+    condition?: string;
+}>): JSX.Element;

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

@@ -0,0 +1,37 @@
+import type { JSX } from "react";
+/**
+ * Generates an area in which editors may insert content objects.
+ *
+ * @returns The Area component
+ */
+export declare function Area({ name, areaView, allowedTypes, numberOfItems, subNodesView, path, editable, areaAsSubNode, areaType, parameters, }: Readonly<{
+    /** The name of the area. */
+    name?: string;
+    /** The view to use for the area. */
+    areaView?: string;
+    /** The allowed types for the area. */
+    allowedTypes?: 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.
+     *
+     * @default true
+     */
+    editable?: boolean;
+    /** Allow area to be stored as a subnode */
+    areaAsSubNode?: boolean;
+    /**
+     * Content type to be used to create the area
+     *
+     * @default jnt:contentList
+     */
+    areaType?: string;
+    /** The parameters to pass to the area */
+    parameters?: Record<string, unknown>;
+}>): JSX.Element;

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

@@ -0,0 +1,22 @@
+/**
+ * Will render the given React component server side and hydrate it in the browser to make it
+ * dynamic. Be careful, the component will not have access to the
+ * '@jahia/javascript-modules-library' library from the browser.
+ *
+ * @returns The component to be hydrated in the browser
+ */
+export declare function HydrateInBrowser<T>(props: Readonly<{
+    /** The React component. */
+    child: React.ComponentType<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: T & React.JSX.IntrinsicAttributes;
+}>): React.JSX.Element;
+export declare function HydrateInBrowser(props: Readonly<{
+    /** The React component. */
+    child: React.ComponentType;
+}>): React.JSX.Element;

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

@@ -0,0 +1,31 @@
+import type { JCRNodeWrapper } from "org.jahia.services.content";
+/**
+ * Render a content node
+ *
+ * @returns The rendered output of the view for the specified content
+ */
+export declare function Render({ content, node, path, editable, advanceRenderingConfig, templateType, view, parameters, }: Readonly<{
+    /** The content node to render */
+    content?: unknown;
+    /** The node to render */
+    node?: JCRNodeWrapper;
+    /** The path to render */
+    path?: string;
+    /**
+     * If the content should be editable
+     *
+     * @default true
+     */
+    editable?: boolean;
+    /**
+     * Specifies if we should render a node or simply include a view. Acceptable values are : none,
+     * INCLUDE or OPTION
+     */
+    advanceRenderingConfig?: "INCLUDE" | "OPTION";
+    /** The template type to use (html, json, ...) */
+    templateType?: string;
+    /** The name of the view variant to use */
+    view?: string;
+    /** The parameters to pass to the view */
+    parameters?: unknown;
+}>): React.JSX.Element;

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

@@ -0,0 +1,21 @@
+/**
+ * Will render the given React component in the browser. Be careful, the component will not have
+ * access to the '@jahia/javascript-modules-library' library from the browser.
+ *
+ * @returns The component to be rendered in the browser
+ */
+export declare function RenderInBrowser<T>(props: Readonly<{
+    /** The React component */
+    child: React.ComponentType<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: T & React.JSX.IntrinsicAttributes;
+}>): React.JSX.Element;
+export declare function RenderInBrowser(props: Readonly<{
+    /** The React component */
+    child: React.ComponentType;
+}>): React.JSX.Element;

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

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

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

@@ -0,0 +1,9 @@
+import { JahiaComponent } from "./jahiaComponent";
+/**
+ * Using this function provides autocomplete on the jahiaComponent properties.
+ *
+ * @deprecated Use `jahiaComponent()` instead to define and register a component.
+ * @param jahiaComponent - An object containing the Jahia component to define.
+ * @returns The jahiaComponent object.
+ */
+export declare function defineJahiaComponent(jahiaComponent: JahiaComponent): JahiaComponent;

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

@@ -0,0 +1,28 @@
+import type { JSX } from "react";
+import { type ServerContext } from "../hooks/useServerContext.js";
+export interface JahiaComponent {
+    /** The ID of the component (autogenerated but can be overridden) */
+    id?: string;
+    /**
+     * The name of the component.
+     *
+     * @default "default"
+     */
+    name?: string;
+    /** The display name of the component (in jahia's UI), optional. */
+    displayName?: string;
+    /** The type of the component. */
+    componentType: "template" | "view";
+    /** The content node type the component applies to. */
+    nodeType: string;
+    /** Properties to add on the component, optional. */
+    properties?: Record<string, string>;
+}
+/**
+ * Defines and registers a Jahia component into the global registry as a view.
+ *
+ * @param id The ID of the component (autogenerated but can be overridden)
+ * @param definitions The definitions of the component
+ * @param Component The component to register
+ */
+export declare const jahiaComponent: <T extends (props: never, context: ServerContext) => JSX.Element>({ id, ...definitions }: JahiaComponent, Component: T) => T;

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

@@ -0,0 +1,11 @@
+import type { JahiaComponent } from "./jahiaComponent";
+/**
+ * Registers Jahia components into the global registry as views
+ *
+ * @deprecated Use `jahiaComponent()` instead to define and register a component.
+ * @param jahiaComponents An object containing the jahia components to register
+ */
+export declare function registerJahiaComponents(jahiaComponents: Record<string | number | symbol, {
+    (): React.JSX.Element;
+    jahiaComponent: JahiaComponent;
+}>): void;

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

@@ -0,0 +1,17 @@
+import type { GraphQLFormattedError } from "graphql";
+/**
+ * Execute a GraphQL query synchronously
+ *
+ * @returns The result of the query
+ */
+export declare const useGQLQuery: ({ query, variables, operationName, }: {
+    /** The GraphQL query to execute */
+    query: string;
+    /** The variables to use for the query */
+    variables?: Record<string, unknown>;
+    /** The operation name to use for the query */
+    operationName?: string;
+}) => {
+    data: any;
+    errors?: GraphQLFormattedError[];
+};

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

@@ -0,0 +1,10 @@
+import type { Node } from "javax.jcr";
+/**
+ * Execute a JCR query
+ *
+ * @returns The result of the query
+ */
+export declare const useJCRQuery: ({ query, }: {
+    /** The JCR query to execute. */
+    query: string;
+}) => Node[];

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

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import type { RenderContext, Resource } from "org.jahia.services.render";
+import type { JCRNodeWrapper } 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
+ */
+export interface ServerContext {
+    /**
+     * 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: RenderContext;
+    /**
+     * The current resource being rendered, which is a combination of the current node and its
+     * template/view information
+     */
+    currentResource: Resource;
+    /** The current JCR node being rendered */
+    currentNode: JCRNodeWrapper;
+    /** The main JCR node being rendered, which is the root node of the current page */
+    mainNode: JCRNodeWrapper;
+    /** The OSGi bundle key of the current module being rendered */
+    bundleKey: string;
+}
+/**
+ * Returns the current server context
+ *
+ * @returns The server context
+ */
+export declare function useServerContext(): ServerContext;
+export declare function ServerContextProvider({ renderContext, currentResource, currentNode, mainNode, bundleKey, children, }: ServerContext & {
+    readonly children: ReactNode;
+}): React.JSX.Element;

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

@@ -0,0 +1,52 @@
+interface UrlBuilderType {
+    /**
+     * Builds a static URL for an asset.
+     *
+     * @returns The built URL.
+     */
+    buildStaticUrl(props: {
+        /** The path of the asset */
+        assetPath: string;
+        /**
+         * The name of the module used as prefix for the URL. If not provided, the current module is
+         * used.
+         */
+        moduleName?: string;
+        /** The parameters to append to the URL */
+        parameters?: Record<string, string>;
+    }): string;
+    /**
+     * Builds a URL for a JCR node.
+     *
+     * @returns {string} The built URL.
+     */
+    buildNodeUrl(props: {
+        /** The path of JCR node */
+        nodePath: string;
+        /** The extension to use to build the URL */
+        extension?: string;
+        /** The language to use to build the URL */
+        language?: string;
+        /** The mode to use to build the URL ('edit', 'preview', 'live') */
+        mode?: "edit" | "preview" | "live";
+        /** The parameters to append to the URL */
+        parameters?: Record<string, string>;
+    }): string;
+    /**
+     * Builds an HTML fragment URL for a JCR node.
+     *
+     * @returns {string} The built URL.
+     */
+    buildHtmlFragmentUrl(props: {
+        /** The path of JCR node */
+        nodePath: string;
+        /** The language to use to build the URL */
+        language?: string;
+        /** The mode to use to build the URL ('edit', 'preview', 'live') */
+        mode?: "edit" | "preview" | "live";
+        /** The parameters to append to the URL */
+        parameters?: Record<string, string>;
+    }): string;
+}
+export declare function useUrlBuilder(): UrlBuilderType;
+export {};

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

@@ -0,0 +1,14 @@
+import type { Node } from "javax.jcr";
+import type { JCRNodeWrapper } from "org.jahia.services.content";
+/**
+ * Returns an array of child nodes of a given node.
+ *
+ * @param node The node to get the child nodes from.
+ * @param limit The maximum number of nodes to return (-1 to return all nodes, but be careful with
+ *   this as it can be very slow and memory consuming, it's better to use a reasonable limit and use
+ *   pagination if needed)
+ * @param offset The offset to start from
+ * @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[];

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

@@ -0,0 +1,14 @@
+import type { JCRNodeWrapper, JCRSessionWrapper } from "org.jahia.services.content";
+/**
+ * Returns a node from a path or identifier
+ *
+ * @param session - The JCR session.
+ * @returns The node.
+ */
+export declare function getNodeFromPathOrId(props: {
+    /** The node identifier */
+    identifier: string;
+} | {
+    /** The node path */
+    path: string;
+}, session: JCRSessionWrapper): JCRNodeWrapper | null;

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

@@ -0,0 +1,9 @@
+import type { JCRNodeWrapper } from "org.jahia.services.content";
+/**
+ * Extracts the properties from a node
+ *
+ * @param node The node on which to extract the properties
+ * @param props The name of the properties to extract
+ * @returns An object containing the property values
+ */
+export declare function getNodeProps(node: JCRNodeWrapper, props: string[]): Record<string, any>;

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

@@ -0,0 +1,14 @@
+import type { Node } from "javax.jcr";
+import type { JCRSessionWrapper } from "org.jahia.services.content";
+/**
+ * Execute a JCR SQL2 query and return the result as an array of nodes
+ *
+ * @param session The JCR session to use
+ * @param query The JCR SQL2 query to execute
+ * @param limit The maximum number of nodes to return (-1 to return all nodes, but be careful with
+ *   this as it can be very slow and memory consuming, it's better to use a reasonable limit and use
+ *   pagination if needed)
+ * @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[];

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

@@ -0,0 +1,25 @@
+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 '#'
+ *
+ * @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 */
+    parameters?: Record<string, string>;
+    /** The mode to use to build the URL */
+    mode?: string;
+    /** The language to use to build the URL */
+    language?: string;
+    /** The extension to use to build the URL */
+    extension?: string;
+}, renderContext: RenderContext, currentResource: Resource): string;

package/dist/globals.d.ts

@@ -0,0 +1,47 @@
+/** The global declarations, where top-level objects are exposed to server-side scripts */
+declare global {
+  import type { Bundle } from "org.osgi.framework";
+
+  /**
+   * Exposed only during the server-side initial script registration process, not available during
+   * rendering
+   */
+  export const bundle: Bundle;
+}
+
+/**
+ * This module is used for internal compilation of the project. It should not be used directly in
+ * your code.
+ */
+declare module "virtual:jahia-server" {
+  import type {
+    ConfigHelper,
+    GQLHelper,
+    OSGiHelper,
+    RegistryHelper,
+    RenderHelper,
+  } from "org.jahia.modules.javascript.modules.engine.js.server";
+  /**
+   * A set of helpers that provide common functionality provided by Jahia for Javascript server-side
+   * rendering
+   */
+  const server: {
+    /** This helper provides access to OSGi configuration */
+    config: ConfigHelper;
+    /** 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 */
+    osgi: OSGiHelper;
+    /**
+     * This helper provides access to Jahia's registry API, to register new UI objects or retrieving
+     * existing ones
+     */
+    registry: RegistryHelper;
+    /**
+     * This helper provides rendering functions such as registering page resources, adding cache
+     * dependencies or rendering components
+     */
+    render: RenderHelper;
+  };
+  export default server;
+}