@soleil-se/app-util 5.8.3 → 5.9.0

package/CHANGELOG.md

@@ -7,6 +7,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.9.0] - 2025-03-17
+
+- Add `idPrefix` when rendering Svelte on the server to avoid conflicts with other apps.
+- Add type definitions.
+
 ## [5.8.3] - 2025-02-14
 
 - Update license.

package/client/fetch-json/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Fetches JSON data from a specified URI.
+ * URI:s starting with `/rest-api`, `/appresource`, `/edit-app-config` or a protocol, for example
+ * `https://` will be left as is. Other URI:s willbe converted to match a route in the current app
+ * with `getRouteUri`.
+ *
+ * @param {string} uri - The URI to fetch JSON data from.
+ * @param {object} options - The options for the fetch request, see <https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters>.
+ * @param {string} options.method - The HTTP method to use in the request.
+ * @param {object} options.params - The parameters to be included in the request URL.
+ * @param {object} options.body - The body to include in the request.
+ * @param {number} options.retries - The number of retries to attempt in case of a timeout error.
+ * @param {object} options.headers - The headers to be included in the request.
+ * @returns {Promise<object>} A promise that resolves to the JSON response.
+ * @throws {Error} If the response is not successful or cannot be parsed as JSON.
+ */
+export default function fetchJson(uri: string, options?: {
+    method: string;
+    params: object;
+    body: object;
+    retries: number;
+    headers: object;
+}): Promise<object>;

package/client/fetch-json/index.js

@@ -55,6 +55,14 @@ function getWidgetOptions(options) {
   };
 }
 
+/**
+ * @typedef {Object} ExtensionOptions
+ * @property {Object<string,any>} params - The parameters to be included in the request URL.
+ * @property {number} retries - The number of retries to attempt in case of a timeout error.
+ *
+ * @typedef {RequestInit & ExtensionOptions} Options
+ */
+
 /**
  * Fetches JSON data from a specified URI.
  * URI:s starting with `/rest-api`, `/appresource`, `/edit-app-config` or a protocol, for example
@@ -62,13 +70,13 @@ function getWidgetOptions(options) {
  * with `getRouteUri`.
  *
  * @param {string} uri - The URI to fetch JSON data from.
- * @param {object} options - The options for the fetch request, see <https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters>.
+ * @param {Options} options - The options for the fetch request with some extensions.
  * @param {string} options.method - The HTTP method to use in the request.
  * @param {object} options.params - The parameters to be included in the request URL.
  * @param {object} options.body - The body to include in the request.
  * @param {number} options.retries - The number of retries to attempt in case of a timeout error.
  * @param {object} options.headers - The headers to be included in the request.
- * @returns {Promise<object>} A promise that resolves to the JSON response.
+ * @returns {Promise<Object>} A promise that resolves to the JSON response.
  * @throws {Error} If the response is not successful or cannot be parsed as JSON.
  */
 export default function fetchJson(uri, options = {}) {

package/client/index.d.ts

@@ -0,0 +1,2 @@
+export { default as fetchJson } from "./fetch-json";
+export { getUrlParam, getUrlParams, setUrlParams, updateUrlParams, clearUrlParams } from "./url-params";

package/client/svelte/3/index.d.ts

@@ -0,0 +1 @@
+export { render } from "../4";

package/client/svelte/4/index.d.ts

@@ -0,0 +1,21 @@
+/** @typedef {import('svelte').SvelteComponent} Component */
+/**
+ * Renders a client side Svelte application.
+ * @param {Component} App Svelte app root component.
+ * @param {object} [settings={}] Settings object.
+ * @param {string} [settings.target] Target where app should be mounted.
+ * @param {string} [settings.props] Root component props.
+ * @param {boolean} [settings.hydrate=target.hasChildNodes()] Instructs Svelte to upgrade existing
+ * DOM (usually from server-side rendering) rather than creating new elements. By default the app
+ * will hydrate when the target has any child nodes.
+ * @param {boolean} [settings.intro=false] If true, will play transitions on initial render,
+ * rather than waiting for subsequent state changes.
+ * @return {Component} Initialized Svelte component.
+ */
+export function render(App: Component, { target, props, intro, hydrate, }?: {
+    target?: string;
+    props?: string;
+    hydrate?: boolean;
+    intro?: boolean;
+}): Component;
+export type Component = import('svelte').SvelteComponent;

package/client/svelte/4/index.js

@@ -1,8 +1,8 @@
 import { setAppProps } from '../../../common';
-
+/** @typedef {import('svelte').SvelteComponent} Component */
 /**
  * Renders a client side Svelte application.
- * @param {import('svelte').SvelteComponent} App Svelte app root component.
+ * @param {Component} App Svelte app root component.
  * @param {object} [settings={}] Settings object.
  * @param {string} [settings.target] Target where app should be mounted.
  * @param {string} [settings.props] Root component props.
@@ -11,7 +11,7 @@ import { setAppProps } from '../../../common';
  * will hydrate when the target has any child nodes.
  * @param {boolean} [settings.intro=false] If true, will play transitions on initial render,
  * rather than waiting for subsequent state changes.
- * @return {import('svelte').SvelteComponent} Initialized Svelte component.
+ * @return {Component} Initialized Svelte component.
  */
 export function render(App, {
   target,

package/client/svelte/5/index.d.ts

@@ -0,0 +1,20 @@
+/** @typedef {import('svelte').Component} Component */
+/**
+ * Renders a client side Svelte application.
+ * @param {Component} App Svelte app root component.
+ * @param {object} [settings={}] Settings object.
+ * @param {string} [settings.target] Target where app should be mounted.
+ * @param {string} [settings.props] Root component props.
+ * @param {boolean} [settings.hydrate=target.hasChildNodes()] Instructs Svelte to upgrade existing
+ * DOM (usually from server-side rendering) rather than creating new elements. By default the app
+ * will hydrate when the target has any child nodes.
+ * @param {boolean} [settings.intro=false] If true, will play transitions on initial render,
+ * rather than waiting for subsequent state changes.
+ */
+export function render(App: Component, { target, props, hydrate, intro, }?: {
+    target?: string;
+    props?: string;
+    hydrate?: boolean;
+    intro?: boolean;
+}): void;
+export type Component = import('svelte').Component;

package/client/svelte/5/index.js

@@ -3,9 +3,11 @@ import { mount as svelteMount, hydrate as svelteHydrate } from 'svelte';
 
 import { setAppProps } from '../../../common';
 
+/** @typedef {import('svelte').Component} Component */
+
 /**
  * Renders a client side Svelte application.
- * @param {import('svelte').Component} App Svelte app root component.
+ * @param {Component} App Svelte app root component.
  * @param {object} [settings={}] Settings object.
  * @param {string} [settings.target] Target where app should be mounted.
  * @param {string} [settings.props] Root component props.

package/client/svelte/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Renders a client side Svelte 3 or 4 application.
+ * @deprecated Use rendering function for specific Svelte version instead.
+ * `import { render } from '@soleil-api/webapp-util/client/svelte/{3|4|5}';`
+ * @param {import('svelte').SvelteComponent} App Svelte app root component.
+ * @param {object} [settings={}] Settings object.
+ * @param {string} [settings.target] Target where app should be mounted.
+ * @param {string} [settings.props] Root component props.
+ * @param {boolean} [settings.hydrate=target.hasChildNodes()] Instructs Svelte to upgrade existing
+ * DOM (usually from server-side rendering) rather than creating new elements. By default the app
+ * will hydrate when the target has any child nodes.
+ * @param {boolean} [settings.intro=false] If true, will play transitions on initial render,
+ * rather than waiting for subsequent state changes.
+ * @return {import('svelte').SvelteComponent} Initialized Svelte component.
+ */
+export function render(App: import('svelte').SvelteComponent, settings?: {
+    target?: string;
+    props?: string;
+    hydrate?: boolean;
+    intro?: boolean;
+}): import('svelte').SvelteComponent;

package/client/url-params/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Set query parameters in the url-field.
+ * @param {Object} obj - Values to be set.
+ * @param {Object} [options] Optional options.
+ * @param {Boolean} [options.scoped = false] If parameter keys should be scoped to current app.
+ */
+export function setUrlParams(params: any): void;
+/**
+ * Get query parameter from the url-field.
+ */
+export function getUrlParam(key: any): any;
+/**
+ * Get query parameters from the url-field.
+ */
+export function getUrlParams(): {};
+/**
+ * Clear query parameters in the url-field.
+ */
+export function clearUrlParams(): void;
+/**
+ * Updates query parameters in the url-field.
+ * @param {Object} params - Values to be updated.
+ */
+export function updateUrlParams(params: any): void;
+declare namespace _default {
+    export { getUrlParam };
+    export { setUrlParams };
+    export { getUrlParams };
+    export { clearUrlParams };
+    export { updateUrlParams };
+}
+export default _default;

package/common/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Get a prefixed namespace unique for app.
+ * @param {string} [prefix='app']
+ * @return {string} - Prefixed namespace.
+ */
+export function getNamespace(prefix?: string): string;
+/**
+ * Generate a unique identifier with a random UUID without dashes.
+ * @param {string} prefix Prefix for the identifier.
+ * @returns {string} Unique identifier.
+ */
+export function generateId(prefix?: string): string;
+/**
+ * Stringify an object to a query string compatible with Sitevision.
+ * @param {Object} params Object with parameters to stringify.
+ * @param {Object} [options] Optional options.
+ * @param {Boolean} [options.addQueryPrefix = false] If a leading ? should be added to the string.
+ * @returns Stringified parameters.
+ */
+export function stringifyParams(params?: any, { addQueryPrefix }?: {
+    addQueryPrefix?: boolean;
+}): string;
+/**
+ * Parse an URL or URI to an object containing its query parameters.
+ * @param {String} url URL or URI to be parsed, must start with or contain "?".
+ * @returns Object with parsed parameters.
+ */
+export function parseParams(url?: string): {};
+/**
+ * Get URI for a route, same as `getStandaloneUrl` in Sitevision router.
+ * @param {string} route A route.
+ * @param {object} params Query parameters.
+ * @returns {string} URI for route.
+ */
+export function getRouteUri(route?: string, params?: object): string;
+/**
+ * Get URI for a view, same as `getUrl` in Sitevision router.
+ * @deprecated Not used in WebApps 2.
+ * @param {string} route A route.
+ * @returns {string} URI for view.
+ */
+export function getViewUri(route?: string, params?: any): string;
+/**
+ * Get URI for a resource.
+ * @param {string} resource A resource.
+ * @returns {string} URI for a resource.
+ */
+export function getResourceUri(resource?: string): string;
+export function setAppProps(data: any): void;
+/**
+ * Get appData value or object that is passed to app when rendering.
+ * @export
+ * @param {string} [key] - Key for value.
+ * @return {*|object} - Value or object.
+ */
+export function getAppProps(key?: string): any | object;
+/**
+ * If the current code is running on the server.
+ * @constant {boolean}
+ */
+export const isServer: any;
+/**
+ * If the current code is running in the browser.
+ * @constant {boolean}
+ */
+export const isBrowser: boolean;
+/**
+ * DOM friendly unique identifier for the WebApp.
+ * @constant {string}
+ */
+export const appId: string;
+/**
+ * If the WebApp is running in offline mode or not.
+ * @constant {boolean}
+ */
+export const isOffline: boolean;
+/**
+ * If the WebApp is running in online mode or not.
+ * @constant {boolean}
+ */
+export const isOnline: boolean;

package/common/legacy/getRouteUri.d.ts

@@ -0,0 +1 @@
+export default function getRouteUri(route: any): string;

package/common/server/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Require a module natively.
+ * @param {string} module
+ * @returns any
+ */
+export function nativeRequire(module: string): any;

package/package.json

@@ -1,18 +1,28 @@
 {
   "name": "@soleil-se/app-util",
-  "version": "5.8.3",
+  "version": "5.9.0",
   "description": "Utility functions for WebApps, RESTApps and Widgets in Sitevision.",
   "main": "./common/index.js",
   "author": "Soleil AB",
   "license": "UNLICENSED",
   "private": false,
+  "type": "module",
   "homepage": "https://docs.soleil.se/packages/app-util",
-  "keywords": ["sitevision", "webapps", "restapps", "widgets", "svelte"],
+  "keywords": [
+    "sitevision",
+    "webapps",
+    "restapps",
+    "widgets",
+    "svelte"
+  ],
   "devDependencies": {
-    "@sitevision/api": "^2023.9.2",
-    "svelte": "^4.2.18"
+    "@sitevision/api": "^2025.1.2",
+    "svelte": "^5.22.6"
   },
   "peerDependencies": {
     "@sitevision/api": "*"
+  },
+  "scripts": {
+    "create-type-definitions": "node ../../utils/createTypeDefinitions.js ./common/index.js;./ ./client/index.js ./client/svelte/index.js ./client/svelte/3/index.js ./client/svelte/4/index.js ./client/svelte/5/index.js ./server/index.js ./server/svelte/index.js ./server/svelte/3/index.js ./server/svelte/4/index.js ./server/svelte/5/index.js"
   }
 }

package/server/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Require a module natively.
+ * @param {string} module
+ * @returns any
+ */
+export function nativeRequire(module: string): any;

package/server/index.js

@@ -1,5 +1,10 @@
 /* Make native requires work with @sitevision/sitevision-scripts that uses Webpack */
 /* eslint-disable camelcase, no-undef, import/no-dynamic-require, global-require */
+/**
+ * Require a module natively.
+ * @param {string} module
+ * @returns any
+ */
 export function nativeRequire(module) {
   if (typeof __non_webpack_require__ !== 'undefined') return __non_webpack_require__(module);
   return require(module);

package/server/svelte/3/index.d.ts

@@ -0,0 +1 @@
+export { render } from "../4";

package/server/svelte/4/index.d.ts

@@ -0,0 +1,9 @@
+/** @typedef {import('svelte').SvelteComponent} Component */
+/**
+ * Returns HTML for a server rendered Svelte app.
+ * @param {Component} App Svelte component that is root of app.
+ * @param {object} props Props passed to root component.
+ * @return {string} HTML for the server rendered app.
+ */
+export function render(App: Component, props: object): string;
+export type Component = import('svelte').SvelteComponent;

package/server/svelte/4/index.js

@@ -1,8 +1,8 @@
 import { setAppProps } from '../../../common';
-
+/** @typedef {import('svelte').SvelteComponent} Component */
 /**
  * Returns HTML for a server rendered Svelte app.
- * @param {import('svelte').SvelteComponent} App Svelte component that is root of app.
+ * @param {Component} App Svelte component that is root of app.
  * @param {object} props Props passed to root component.
  * @return {string} HTML for the server rendered app.
  */

package/server/svelte/5/index.d.ts

@@ -0,0 +1,9 @@
+/** @typedef {import('svelte').Component} Component */
+/**
+ * Returns HTML for a server rendered Svelte app.
+ * @param {Component} App Svelte component that is root of app.
+ * @param {object} props Props passed to root component.
+ * @return {string} HTML for the server rendered app.
+ */
+export function render(App: Component, props: object): string;
+export type Component = import('svelte').Component;

package/server/svelte/5/index.js

@@ -1,15 +1,19 @@
 import { render as svelteRender } from 'svelte/server';
-import { setAppProps } from '../../../common';
+import { appId, setAppProps } from '../../../common';
 
+/** @typedef {import('svelte').Component} Component */
 /**
  * Returns HTML for a server rendered Svelte app.
- * @param {import('svelte').Component} App Svelte component that is root of app.
+ * @param {Component} App Svelte component that is root of app.
  * @param {object} props Props passed to root component.
  * @return {string} HTML for the server rendered app.
  */
 export function render(App, props) {
   setAppProps(props);
 
-  const { body } = svelteRender(App, { props });
+  const { body } = svelteRender(App, {
+    props,
+    idPrefix: `app${appId}`,
+  });
   return body;
 }

package/server/svelte/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns HTML for a server rendered Svelte 3 or 4 app.
+ * @deprecated Use rendering function for specific Svelte version instead.
+ * `import { render } from '@soleil-api/webapp-util/server/svelte/{3|4|5}';`
+ * @param {import('svelte').SvelteComponent} App Svelte component that is root of app.
+ * @param {object} props Props passed to root component.
+ * @return {string} HTML for the server rendered app.
+ */
+export function render(App: import('svelte').SvelteComponent, props: object): string;