@soleil-se/app-util 5.8.0 → 5.8.2

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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.8.2] - 2025-02-14
+
+- Update README and tagging in `package.json`.
+
+## [5.8.1] - 2024-10-28
+
+- Pass props properly to Svelte 5 server render function.
+- Update JSDoc to correct new paths for deprecated functions.
+
 ## [5.8.0] - 2024-10-21
 
 - Restructure rendering function for different Svelte versions.

package/README.md

@@ -1,412 +1,5 @@
+# @soleil-se/app-util
 
-# `@soleil-se/webapp-util@^5.0.0`
+Utility functions for WebApps, RESTApps and Widgets in Sitevision.
 
-Utility functions for WebApps.
-
-[GitHub](https://github.com/soleilit/server-monorepo/tree/master/packages/webapp-util)  
-[NPM](https://www.npmjs.com/package/@soleil-se/webapp-util)
-
-
-
-## Requirements
-
-* Sitevision 9.1.0 or later.  
-* `@soleil-se/sv-app-build@^1.0.0` or `@sitevision/sitevision-scripts@^3.0.0`.
-* WebApps 2 enabled app.
-
-### Manifest
-
-`bundled` needs to be enabled in [WebApp manifest](https://developer.sitevision.se/docs/webapps/webapps-2/manifest) for WebApps 2.
-
-```json
-{
-  "id": "se.soleil.myApp",
-  "version": "1.0.0",
-  "name": "My app",
-  "author": "Soleil AB",
-  "description": "",
-  "helpUrl": "https://soleil.se/support",
-  "type": "WebApp",
-  "bundled": true
-}
-```
-
-## Install
-
-```sh
-> npm install @soleil-se/webapp-util
-> yarn add @soleil-se/webapp-util
-```
-
-:::details Integrity check failed
-If the following error occurs when installing with Yarn run `yarn install --update-checksums`.
-
-```
-Integrity check failed for "@soleil-se/webapp-util" (computed integrity doesn...
-```
-
-:::
-
-## Migration
-
-Migrating from version 4?  
-See [MIGRATION](./MIGRATION.md).
-
-## Common
-
-All imports from base package are available both on the server and client.
-
-### appId : `String`
-
-DOM friendly unique identifier for the WebApp.
-
-```js
-import { appId } from '@soleil-se/webapp-util';
-
-console.log(appId); // For example: 12_682d461b1708a9bb1ea13efd
-```
-
-### isOffline : `Boolean`
-
-If the WebApp is running in offline mode or not.
-
-```js
-import { isOffline } from '@soleil-se/webapp-util';
-
-console.log(isOffline);  // true or false
-```
-
-### isOnline : `Boolean`
-
-If the WebApp is running in online mode or not.
-
-```js
-import { isOnline } from '@soleil-se/webapp-util';
-
-console.log(isOnline); // true or false
-```
-
-### isServer : `Boolean`
-
-If the current code is running on the server.
-
-```js
-import { isServer } from '@soleil-se/webapp-util';
-
-console.log(isServer); // true or false
-```
-
-### isBrowser : `Boolean`
-
-If the current code is running in the browser.
-
-```js
-import { isBrowser } from '@soleil-se/webapp-util';
-
-console.log(isBrowser); // true or false
-```
-
-### getNamespace([prefix]) ⇒ `String`
-
-Get a prefixed namespace unique for app.
-
-**Returns**: `String` - Prefixed namespace.
-
-| Param | Type | Default |
-| --- | --- | --- |
-| [prefix] | `string` | `"'app'"` |
-
-```js
-import { getNamespace } from '@soleil-se/webapp-util';
-
-console.log(getNamespace());
-// For example: app_12_682d461b1708a9bb1ea13efd
-
-console.log(getNamespace('input'));
-// For example: input_12_682d461b1708a9bb1ea13efd
-
-// If the app is in a decoration template the Portlet ID is the same for all instances, so the ID of the decorated node is used as well.
-console.log(getNamespace('decoration'));
-// For example: decoration_10_3871c02f1754f3aa8f9d4eb_12_70c3d424173b4900fc550e1c
-```
-
-### generateId([prefix]) ⇒ `String`
-
-Generate a unique identifier with a random UUID without dashes.
-
-**Returns**: `String` - Unique identifier.
-
-| Param | Type | Default |
-| --- | --- | --- |
-| [prefix] | `string` | `"'id'"` |
-
-```js
-import { generateId } from '@soleil-se/webapp-util';
-
-console.log(generateId());
-// For example: id_550e8400e29b41d4a716446655440000
-
-console.log(generateId('input'));
-// For example: input_550e8400e29b41d4a716446655440000
-
-```
-
-### getRouteUri(route, [query]) ⇒ `String`
-
-Get URI for a route.
-
-**Returns**: `String` - URI for route.
-
-| Param | Type | Description |
-| --- | --- | --- |
-| route | `String` | A route. |
-| query | `Object` | Object with query string parameters |
-
-```js
-import { getRouteUri } from '@soleil-se/webapp-util';
-
-console.log(getRouteUri('/items'));
-// URI structure: /appresource/{pageId}/{portletId}>/items
-```
-
-```js
-import { getRouteUri } from '@soleil-se/webapp-util';
-
-console.log(getRouteUri('/items', { foo: 'bar' }));
-// URI structure: /appresource/{pageId}/{portletId}>/items?foo=bar
-```
-
-### getResourceUri(resource) ⇒ `String`
-
-Get URI for a resource.
-
-**Returns**: `String` - URI for a resource.
-
-| Param | Type | Description |
-| --- | --- | --- |
-| resource | `String` | A resource. |
-
-```js
-import { getResourceUri } from '@soleil-se/webapp-util';
-
-console.log(getResourceUri('/image.png'));
-// URI structure: /webapp-files/<webappname>/<webappversion>/image.png
-```
-
-### getAppProps([key]) ⇒ `*` | `Object`
-
-Get props that are passed to app when rendering.
-
-**Returns**: `*` | `Object` - Value or object.
-
-| Param | Type | Description |
-| --- | --- | --- |
-| [key] | `String` | Key for value. |
-
-```js
-import { getAppProps } from '@soleil-se/webapp-util';
-
-// Get value with key
-const myValue = getAppProps('myValue');
-// Or with destructuring
-const { myValue } = getAppProps();
-```
-
-### stringifyParams(params [, options]) ⇒ `String`
-
-Stringify an object to a query string compatible with Sitevision.
-
-**Returns**: `String` - Stringified parameters.
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| params | `Object` | | Object with parameters to stringify. |
-| [options] | `Object` | `{}` | Options object. |
-| [options.addQueryPrefix] | `Boolean` | `false` | If a leading `?` should be added to the string. |
-
-```js
-import { stringifyParams } from '@soleil-se/webapp-util';
-
-const queryString = stringifyParams({ foo: 'bar', num: 1 });
-// foo=bar&num=1
-
-const queryString = stringifyParams({ foo: 'bar', num: 1 }, { addQueryPrefix: true });
-// ?foo=bar&num=1
-```
-
-### parseParams(url) ⇒ `Object`
-
-Parse an URL, URI or query string to an object containing its query parameters.
-
-**Returns**: `Object` - Parsed parameters.
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| url | `String` | | URL, URI or query string to be parsed, must start with or contain "?" |
-
-```js
-import { parseParams } from '@soleil-se/webapp-util';
-
-const params = parseParams('?foo=bar&arr[]=1&arr[]=2');
-// { foo: 'bar', arr: [1, 2] }
-```
-
-## Client
-
-Following API:s are available in a client context.
-
-### Fetch
-
-Fetch wrapper for calling app routes, rest-api or external resources.
-
-#### fetchJson() => `Promise<Object>`
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| uri | `String` | | URI for resource |
-| [options] | `Object` | `{}` | Options object, two custom options rest is standard [fetch options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options) |
-| [options.params] | `Object` | `{}` | Object with parameters to be appended to the URI |
-| [options.retries] | `Number` | `0` | Number of retries if the request times out. |
-
-**Returns**: `Promise<Object>` - Promise containing parsed JSON-data.  
-**Throws** `Error` - Extended error object with custom properties for `status`, `aborted` and other JSON-data returned by the request.
-
-URI:s starting with `/rest-api`, `/appresource`,  `/edit-app-config` or a protocol, for example `https://` will be left as is.  
-Other URI:s will be converted to match a route in the current app with `getRouteUri`.
-
-Most common usage is getting data from a route in the current app.
-
-```js
-import { fetchJson } from '@soleil-se/webapp-util/client';
-
-async function getItems() {
-  const params = { query: 'foo', start: 0, num: 10 };
-  const result = await fetchJson('/items', { params });
-  console.log(result);
-}
-```
-
-Posting form data.
-
-```js
-import { fetchJson } from '@soleil-se/webapp-util/client';
-
-async function postForm() {
-  const body = new FormData();
-  body.append('name', 'Foo');
-  body.append('mail', 'foo@bar.com');
-
-  const result = await fetchJson('/create', { method: 'POST', body }));
-  console.log(result);
-}
-```
-
-Specify number of retries if a request times out.
-
-```js
-import { fetchJson } from '@soleil-se/webapp-util/client';
-
-async function getItems() {
-  const params = { query: 'foo', start: 0, num: 10 };
-  const result = await fetchJson('/items', { params, retries: 5 });
-  console.log(result);
-}
-```
-
-When searching on input you probably want to abort the ongoing request to avoid weird bugs when
-the first request might be completed after the subsequent one.  
-Pass an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) signal
-in options and abort the ongoing call.
-
-```js
-import { fetchJson } from '@soleil-se/webapp-util/client';
-
-let controller;
-
-async function onInput() {
-  if(controller) controller.abort();
-  controller = new AbortController();
-
-  const params = { query: 'foo' };
-  try {
-    const result = await fetchJson('/search', { params, signal: controller.signal });
-    console.log(result);
-  } catch(e) {
-    // Ignore aborts due to new search.
-    if(e.aborted) return;
-    // Handle error as usual.
-  }
-}
-```
-
-### URL Parameters
-
-Helper functions setting, getting, updating and clearing query parameters in the URL-field.
-
-#### getUrlParams() ⇒ `Object`
-
-Get parameters from the URL-field.
-
-**Returns**: `Object` - Parameters in URL-field.
-
-```js
-import { getUrlParams } from '@soleil-se/webapp-util/client';
-
-const params = getUrlParams();
-```
-
-#### getUrlParam() ⇒ `String|Array[String]`
-
-Get single parameter from the URL-field.
-
-**Returns**: `String|Array[String]` - Parameter value.
-
-```js
-import { getUrlParam } from '@soleil-se/webapp-util/client';
-
-const param = getUrlParam('name');
-```
-
-#### setUrlParams(params)
-
-Set parameters in the URL-field, overwriting other parameters.
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| params | `Object` | | Object with parameters to set in the URL-field. |
-
-```js
-import { setUrlParams } from '@soleil-se/webapp-util/client';
-
-setUrlParams({ foo: 'bar', arr: [1, 2] });
-```
-
-#### updateUrlParams(params)
-
-Update parameters in the URL-field, merging with existing parameters
-
-**Returns**: `String` - Stringified parameters.
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| params | `Object` | | Object with parameters to add to the URL-field. |
-
-```js
-import { updateUrlParams } from '@soleil-se/webapp-util/client';
-
-updateUrlParams({ foo: 'bar', arr: [1, 2] });
-```
-
-#### clearUrlParams()
-
-Clear parameters in the URL-field
-
-```js
-import { clearUrlParams } from '@soleil-se/webapp-util/client';
-
-clearUrlParams();
-```
-
-## Rendering
-
-* [Svelte](./docs/1.svelte.md)
+[Documentation](https://docs.soleil.se/packages/app-util) | [Changelog](https://docs.soleil.se/packages/app-util/changelog)

package/client/svelte/index.js

@@ -3,7 +3,7 @@ import { render as render4 } from './4';
 /**
  * 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/{3|4|5}';`
+ * `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.

package/package.json

@@ -1,19 +1,18 @@
 {
   "name": "@soleil-se/app-util",
-  "version": "5.8.0",
-  "description": "Utility and rendering functions for WebApps.",
+  "version": "5.8.2",
+  "description": "Utility functions for WebApps, RESTApps and Widgets in Sitevision.",
   "main": "./common/index.js",
   "author": "Soleil AB",
-  "license": "UNLICENSED",
+  "license": "UNLICENCED",
   "private": false,
-  "homepage": "https://docs.soleil.se/packages/app-util/",
+  "homepage": "https://docs.soleil.se/packages/app-util",
+  "keywords": ["sitevision", "webapps", "restapps", "widgets", "svelte"],
   "devDependencies": {
     "@sitevision/api": "^2023.9.2",
     "svelte": "^4.2.18"
   },
   "peerDependencies": {
     "@sitevision/api": "*"
-  },
-  "gitHead": "cb815ee398e467bc9440e1b4e98640e12462dd41",
-  "dependencies": {}
-}
+  }
+}

package/server/svelte/5/index.js

@@ -10,6 +10,6 @@ import { setAppProps } from '../../../common';
 export function render(App, props) {
   setAppProps(props);
 
-  const { body } = svelteRender(App, props);
+  const { body } = svelteRender(App, { props });
   return body;
 }

package/server/svelte/index.js

@@ -3,7 +3,7 @@ import { render as render4 } from './4';
 /**
  * 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/{3|4|5}';`
+ * `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.

package/docs/1.svelte.md

@@ -1,112 +0,0 @@
----
-title: Svelte
----
-
-Sitevision supports both server and client side rendering with Svelte.
-
-## index.js
-
-### `render(App, [props])`
-
-`@soleil-api/webapp-util/server/svelte`
-
-Get a HTML string for rendering a universal Svelte application.
-If a client bundle is available the server rendered HTML will be hydrated and not completely re-rendered.
-
-**Returns**: `String` - HTML for rendering a Svelte application.
-
-| Param   | Type     | Default | Description                           |
-|---------|----------|---------|---------------------------------------|
-| [App]   | `Svelte` |         | Svelte app to be rendered.            |
-| [props] | `Object` | `{}`    | Props that will be passed to the app. |
-
-### Universal
-
-Render an app with both server and client code.
-
-```javascript
-// index.js
-import router from '@sitevision/api/common/router';
-import { render } from '@soleil-api/webapp-util/server/svelte';
-
-import App from './App.svelte';
-
-router.get('/', (req, res) => {
-  const props = { foo: 'bar' };
-  const html = render(App, props);
-  res.agnosticRender(html, props);
-});
-```
-
-### SSR
-
-Render an app with only server side code.
-
-```js
-// index.js
-import router from '@sitevision/api/common/router';
-import { render } from '@soleil-api/webapp-util/server/svelte';
-
-import App from './App.svelte';
-
-router.get('/', (req, res) => {
-  const props = { foo: 'bar' };
-  const html = render(App, props);
-  res.send(html);
-});
-```
-
-### CSR
-
-Render an app with only client side code.
-
-```javascript
-// index.js
-import router from '@sitevision/api/common/router';
-
-router.get('/', (req, res) => {
-  const props = { foo: 'bar' };
-  res.agnosticRender('', props)
-});
-```
-
-## main.js
-
-### `render(App, { target, props })`
-
-`@soleil-api/webapp-util/client/svelte`
-
-Renders a client side Svelte application.
-
-**Returns**: `SvelteComponent` - Initialized Svelte component.
-
-| Param              | Type              | Default                  | Description                                                                                                                                                                           |
-|--------------------|-------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| App                | `SvelteComponent` |                          | Svelte app root component.                                                                                                                                                            |
-| [settings]         | `Object`          | `{}`                     | Settings object.                                                                                                                                                                      |
-| [settings.target]  | `Element`         |                          | Target where app should be mounted.                                                                                                                                                   |
-| [settings.props]   | `Object`          |                          | Root component props.                                                                                                                                                                 |
-| [settings.intro]   | `Boolean`         | `false`                  | If true, will play transitions on initial render, rather than waiting for subsequent state changes.                                                                                   |
-| [settings.hydrate] | `Boolean`         | `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. |
-
-```javascript
-// main.js
-import { render } from '@soleil-api/webapp-util/client/svelte';
-import App from './App.svelte';
-
-export default (props, target) => {
-  render(App, { props, target });
-};
-```
-
-Mount the app in another element:
-
-```javascript
-// main.js
-import { render } from '@soleil-api/webapp-util/client/svelte';
-import App from './App.svelte';
-
-export default (props) => {
-  render(App, { props, target: document.querySelector('#mount_app_here') });
-};
-```