clarify the difference between attributes and properties (#3856)

* clarify diff attribute props * cosmetics * added v2.14 release notes * added example snippets * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * Update docs/luigi-compound-container-api.md Co-authored-by: Johannes Doberer <[email protected]> * review changes * added an example * added examples * Update container/typings/LuigiCompoundContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Update container/typings/LuigiContainer.svelte.d.ts Co-authored-by: Johannes Doberer <[email protected]> * Apply suggestions from code review Co-authored-by: Johannes Doberer <[email protected]> * Added examples in both files --------- Co-authored-by: Johannes Doberer <[email protected]>
SAP · Nov 5, 2024 · 374c003 · 374c003
1 parent 62c6939
commit 374c003
Show file tree

Hide file tree

Showing 5 changed files with 520 additions and 12 deletions.
diff --git a/container/typings/LuigiCompoundContainer.svelte.d.ts b/container/typings/LuigiCompoundContainer.svelte.d.ts
@@ -7,95 +7,140 @@ export declare interface WebComponentSettings {
 export default class LuigiCompoundContainer extends HTMLElement {
   /**
    * The URL used for the renderer.
+   * 
+   * @example <luigi-container viewurl="/index.html"></luigi-container>
+   * @example myContainer.viewurl = "/index.html"
    */
   viewurl: string;
 
   /**
    * The configuration for the compound microfrontend.
    * Take a look at the [compound parameter](https://docs.luigi-project.io/docs/navigation-parameters-reference/?section=compound) for details.
    * @since 1.0.0
-   *
+   * 
+   * @example renderer = { use: 'grid', config: { columns: '1fr 1fr 1fr 2fr', layouts: [{maxWidth: 600, columns: '1fr', gap: 0, ...}]}};
+   * children = [{ viewUrl: '/main.js', context: { label: 'WC', ...}, layoutConfig: {column: '1 / -1', ...}, eventListeners: [{ source: 'input1', ...}}]}];
+   * myContainer.compoundConfig = { renderer, children };
    */
   compoundConfig: Object;
 
   /**
    * If set to true defers from initializing the microfronted automatically. In that case init() can be used.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" defer-init></luigi-container>
+   * @example myContainer.deferInit = true
    */
   deferInit: boolean;
 
   /**
    *
    * The locale to be passed to the compound micro frontend.
    * @since NEXT_RELEASE_CONTAINER
+   * 
+   * @example <luigi-container locale="en_us"></luigi-container>
+   * @example myContainer.locale = "en_us"
    */
   locale: string;
 
   /**
    * The parameters to be passed to the compound micro frontend. Will not be passed to the compound children.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" node-params='{"node":"param"}'></luigi-container>
+   * @example myContainer.nodeParams = {foo: bar}
    */
   nodeParams: Object;
 
   /**
    * If set to true, the Luigi compound container webcomponent will not use the shadow DOM for rendering.
    * @since 1.2.0
+   * 
+   * @example <luigi-container viewurl="/index.html" no-shadow></luigi-container>
+   * @example myContainer.noShadow = true
    */
   noShadow: boolean;
 
   /**
    * The search parameters to be passed to the compound micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" search-params='{"search":"param"}'></luigi-container>
+   * @example myContainer.searchParams = {foo: bar}
    */
   searchParams: Object;
 
   /**
    * The path parameters to be passed to the compound micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" path-params='{"path":"param"}'></luigi-container>
+   * @example myContainer.pathParams = {foo: "bar"}
    */
   pathParams: Object;
 
   /**
    * The stringified context to be passed to the compound microfrontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewUrl="/index.html" context='{"label": "Dashboard"}'></luigi-container>
+   * @example myContainer.context = {label: "Dashboard"}
    */
   context: string;
 
   /**
    * The clientPermissions to be passed to the compound micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" client-permissions='{"permission": "adminGroup"}'></luigi-container>
+   * @example myContainer.clientPermissions = {permission: "adminGroup"}
    */
   clientPermissions: Object;
 
   /**
    * The user settings to be passed to the compound micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" user-settings='{"language": "de", "theme":"sap_horizon"}'></luigi-container>
+   * @example myContainer.userSettings = {language: 'de', theme: 'sap_horizon'}
    */
   userSettings: Object;
 
   /**
    * The anchor value to be passed to the compound micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" anchor='#foo'></luigi-container>
+   * @example myContainer.anchor = '#foo'
    */
   anchor: string;
 
   /**
    * The document title value to be passed to the compound micro frontend.
    * @since 1.2.0
+   * 
+   * @example <luigi-container viewurl="/index.html" document-title='Luigi App'></luigi-container>
+   * @example myContainer.documentTitle = 'Luigi App'
    */
   documentTitle: string;
 
   /**
    * The hasBack value to be passed to the compound micro frontend.
    * It indicates that there is one or more preserved views. Useful when you need to show a back button.
    * @since 1.2.0
+   * 
+   * @example <luigi-container viewurl="/index.html" has-back></luigi-container>
+   * @example myContainer.hasBack = true
    */
-  hasBack: string;
+  hasBack: boolean;
 
   /**
    * The dirty status value to be passed to the compound micro frontend.
    * It's used to indicate that there are unsaved changes when navigating away.
    * @since 1.2.0
+   * 
+   * @example <luigi-container viewurl="/index.html" dirty-status></luigi-container>
+   * @example myContainer.dirtyStatus = true
    */
   dirtyStatus: boolean;
 
@@ -107,24 +152,38 @@ export default class LuigiCompoundContainer extends HTMLElement {
    * @param {string} WebComponentSettings.tagName: tag name where web component is added to DOM.
    * @param {string} string must be a stringified JSON object from type `WebComponentSettings`.
    * @since 1.0.0
+   * 
+   * @example <luigi-container webcomponent="{ type: 'module', selfRegistered: true, tagName: 'my-webcomponent'}"></luigi-container>
+   * @example myContainer.webcomponent = { type: 'module', selfRegistered: true, tagName: 'my-webcomponent'}
    */
   webcomponent: boolean | WebComponentSettings | string;
 
   /**
    * If set to true, skips handshake and ready event is fired immediately.
    * @since NEXT_RELEASE_CONTAINER
+   * 
+   * @example <luigi-container viewurl="/index.html" skipInitCheck></luigi-container>
+   * @example myContainer.skipInitCheck = true
    */
   skipInitCheck: boolean;
 
   /**
    * The list of active feature toggles to be passed to the compound microfrontend.
    * @since NEXT_RELEASE_CONTAINER
+   * 
+   * 
+   * @example <luigi-container viewUrl="/index.html" active-feature-toggle-list='["enable-foo", "allow-bar"]'></luigi-container>
+   * @example myContainer.activeFeatureToggleList = ["enable-foo", "allow-bar"]
    */
   activeFeatureToggleList: string[];
 
   /**
    * The theme to be passed to the compound microfrontend.
    * @since NEXT_RELEASE_CONTAINER
+   * 
+   * 
+   * @example <luigi-container viewUrl="/index.html" theme='sap_horizon'></luigi-container>
+   * @example myContainer.theme = 'sap_horizon'
    */
   theme: string;
 

diff --git a/container/typings/LuigiContainer.svelte.d.ts b/container/typings/LuigiContainer.svelte.d.ts
@@ -8,24 +8,37 @@ export default class LuigiContainer extends HTMLElement {
   /**
    * The URL of the microfrontend to be rendered
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html"></luigi-container>
+   * @example myContainer.viewurl = "/index.html"
    */
   viewurl: string;
 
   /**
    * If set to true defers from initializing the microfronted automatically. In that case init() can be used
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" defer-init></luigi-container>
+   * @example myContainer.deferInit = true
    */
   deferInit: boolean;
 
   /**
    * The stringified context object to be passed to the microfrontend
    * @since 1.0.0
+   * 
+   * 
+   * @example <luigi-container viewUrl="/index.html" context='{"label": "Dashboard"}'></luigi-container>
+   * @example myContainer.context = {label: "Dashboard"}
    */
   context: string;
 
   /**
    * Label information for the microfrontend
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewUrl="/index.html" label="Dashboard"></luigi-container>
+   * @example myContainer.label = "Dashboard"
    */
   label: string;
 
@@ -50,85 +63,123 @@ export default class LuigiContainer extends HTMLElement {
    * The advantage of this line of code is: you don't have to specify a tag name, thus avoiding the duplication of self-defined tag names.
    * </br>
    * @since 1.0.0
+   * @example <luigi-container webcomponent="{ type: 'module', selfRegistered: true, tagName: 'my-webcomponent'}"></luigi-container>
+   * @example myContainer.webcomponent = { type: 'module', selfRegistered: true, tagName: 'my-webcomponent'}
    */
   webcomponent: boolean | WebComponentSettings | string;
 
   /**
    * The locale to be passed to the web-component-based micro frontend
    * @since 1.0.0
+   * 
+   * @example <luigi-container locale="en_us"></luigi-container>
+   * @example myContainer.locale = "en_us"
    */
   locale: string;
 
   /**
    * The theme to be passed to the  web-component-based micro frontend
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" theme='sap_horizon'></luigi-container>
+   * @example myContainer.theme = 'sap_horizon'
    */
   theme: string;
 
   /**
    * The list of active feature toggles to be passed to the web-component-based micro frontend
    * @since 1.0.0
+   * 
+   * @example myContainer.activeFeatureToggleList = ["enable-foo", "allow-bar"]
+   * @example <luigi-container viewurl="/index.html" active-feature-toggle-list='["enable-foo", "allow-bar"]'></luigi-container>
    */
   activeFeatureToggleList: string[];
 
   /**
    * If set to true, skips third party cookie check
    * @since NEXT_RELEASE_CONTAINER
+   * 
+   * @example <luigi-container viewurl="/index.html" skipCookieCheck></luigi-container>
+   * @example myContainer.skipCookieCheck = true
    */
-  skipCookieCheck: 'false' | 'true';
+  skipCookieCheck: boolean;
 
   /**
    * If set to true, skips handshake and ready event is fired immediately
    * @since 1.0.0
+   * TODO: https://developer.mozilla.org/en-US/docs/Glossary/Boolean/HTML says booleans should not use "true"/"false", find a consistent style for our docs.
+   * @example <luigi-container viewurl="/index.html" skipInitCheck></luigi-container>
+   * @example myContainer.skipInitCheck = true
    */
   skipInitCheck: boolean;
 
   /**
    * The parameters to be passed to the web-component-based micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" node-params='{"node":"param"}'></luigi-container>
+   * @example myContainer.nodeParams = {foo: bar}
    */
   nodeParams: Object;
 
   /**
    * If set to true, the Luigi container webcomponent will not use the shadow DOM for rendering.
    * @since 1.2.0
+   * 
+   * @example <luigi-container viewurl="/index.html" no-shadow></luigi-container>
+   * @example myContainer.noShadow = true
    */
   noShadow: boolean;
 
   /**
    * The search parameters to be passed to the web-component-based micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" search-params='{"search":"param"}'></luigi-container>
+   * @example myContainer.searchParams = {foo: bar}
    */
   searchParams: Object;
 
   /**
    * The path parameters to be passed to the web-component-based micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" path-params='{"path":"param"}'></luigi-container>
+   * @example myContainer.pathParams = {foo: "bar"}
    */
   pathParams: Object;
 
   /**
    * The clientPermissions to be passed to the web-component-based micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" client-permissions='{"permission": "adminGroup"}'></luigi-container>
+   * @example myContainer.clientPermissions = {permission: "adminGroup"}
    */
   clientPermissions: Object;
 
   /**
    * The user settings to be passed to the web-component-based micro frontend
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" user-settings='{"language": "de", "theme":"sap_horizon"}'></luigi-container>
+   * @example myContainer.userSettings = {language: 'de', theme: 'sap_horizon'}
    */
   userSettings: Object;
 
   /**
    * The anchor value to be passed to the web-component-based micro frontend.
    * @since 1.0.0
+   * 
+   * @example <luigi-container viewurl="/index.html" anchor='#foo'></luigi-container>
+   * @example myContainer.anchor = '#foo'
    */
   anchor: string;
 
   /**
    * The list of rules for the content in the iframe, managed by the HTML `allow` attribute.
    * You can use one or more rules by adding them to the array, for example allowRules: ["microphone", "camera"].
-   * @example <luigi-container viewUrl="/index.html" allow-rules='["microphone", "camera"]'></luigi-container>
+   * @example <luigi-container viewurl="/index.html" allow-rules='["microphone", "camera"]'></luigi-container>
    * @example containerElement.allowRules = ['microphone', 'camera']
    * @since 1.2.0
    */
@@ -137,7 +188,7 @@ export default class LuigiContainer extends HTMLElement {
   /**
    * The list of rules for the content in the iframe, managed by the HTML `sandbox` attribute.
    * You can use one or more rules by adding them to the array, for example sandboxRules: ["allow-scripts", "allow-same-origin"].
-   * @example <luigi-container viewUrl="/index.html" sandbox-rules='["allow-scripts", "allow-same-origin"]'></luigi-container>
+   * @example <luigi-container viewurl="/index.html" sandbox-rules='["allow-scripts", "allow-same-origin"]'></luigi-container>
    * @example containerElement.sandboxRules = ['allow-modals', 'allow-popups']
    * @since 1.2.0
    */
@@ -146,20 +197,29 @@ export default class LuigiContainer extends HTMLElement {
   /**
    * The document title value to be passed to the web-component-based micro frontend.
    * @since 1.2.0
+   * 
+   * @example <luigi-container viewurl="/index.html" document-title='Luigi App'></luigi-container>
+   * @example myContainer.documentTitle = 'Luigi App'
    */
   documentTitle: string;
 
   /**
    * The hasBack value to be passed to the web-component-based micro frontend.
    * It indicates that there is one or more preserved views. Useful when you need to show a back button.
    * @since 1.2.0
+   * 
+   * @example <luigi-container viewurl="/index.html" has-back></luigi-container>
+   * @example myContainer.hasBack = true
    */
-  hasBack: string;
+  hasBack: boolean;
 
   /**
    * The dirty status value to be passed to the web-component-based micro frontend.
    * It's used to indicate that there are unsaved changes when navigating away.
    * @since 1.2.0
+   * 
+   * @example <luigi-container viewurl="/index.html" dirty-status></luigi-container>
+   * @example myContainer.dirtyStatus = true
    */
   dirtyStatus: boolean;