@bluealba/pae-ui-react-core 3.0.2-develop-1171

package/LICENSE

@@ -0,0 +1,134 @@
+Required Notice: Copyright Blue Alba LLC 2025 (https://bluealba.com)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you
+must agree to them as both strict obligations and
+conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the
+software that would otherwise infringe the licensor's
+copyright in it for any permitted purpose. However,
+you may only distribute the software according to
+[Distribution License](#distribution-license) and make
+changes or new works based on the software according to
+[Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or
+the URL for them above, as well as copies of any plain-text
+lines beginning with `Required Notice:` that the licensor
+provided with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software
+that covers patent claims the licensor can license, as well
+as patent claims that the licensor becomes able to license.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization, or
+government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms, including any portion of the
+software.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,368 @@
+# PAE - UI React Core
+
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=alert_status&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=bugs&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=code_smells&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=coverage&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=duplicated_lines_density&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=ncloc&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=reliability_rating&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=security_rating&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=sqale_index&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=sqale_rating&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=bluealba_pae-react-utils&metric=vulnerabilities&token=171e950fb2dac9f76dc3deaf0bda73068df11647)](https://sonarcloud.io/summary/new_code?id=bluealba_pae-react-utils)
+
+Core PAE library for PAE microfrontend applications.
+It exposes PAE functionality in the form of react elements such as hooks, components, etc. which provide cross-cutting
+concerns such as Authentication (Impersonation), Authorization, Service Interaction, Monitoring, etc.
+
+# Usage
+
+## Initialize your Microfrontend
+
+A PAE microfrontend must be created by calling the `initiliazeMicroFrontend()` function (not although you could directly create a SingleSPA application
+that will tied you to SPA and you won't be able to use all the functionality of this PAE library).
+
+```jsx
+import React from "react";
+import ReactDOMClient from "react-dom/client";
+import { initializeMicroFrontend } from "@bluealba/pae-ui-react-core";
+import Root from "./root.component";
+
+export const { bootstrap, mount, unmount } = initializeMicroFrontend({
+  React,
+  ReactDOMClient,
+  rootComponent: Root,
+  errorBoundary(err) {
+    console.error(err);
+    return (
+      <div>
+        <h1>Something went wrong</h1>
+        <p>{err.message}</p>
+      </div>
+    );
+  }
+});
+```
+
+The most important part here is that you specify your `rootComponent` of your app and a way to handle errors locally.
+
+## Utility Functions
+
+### navigateTo() utility function
+
+Use this function to navigate to a different url. This function is a wrapper around the `single-spa` `navigateToURL` function
+
+```typescript jsx
+import { navigateTo } from '@bluealba/pae-ui-react-core';
+
+navigateTo('/path/to/another/module');
+```
+
+## Hooks
+
+PAE provides the following hooks to access data and interact with PAE services.
+
+### useAuth
+
+Retrieve the current user information as well as a method to check authorization access.
+
+```jsx
+import { useAuth } from '@bluealba/pae-ui-react-core';
+
+const TestComponent = () => {
+    const { authUser, hasAccess } = useAuth();
+    return (
+        <div>
+            <h1>{authUser.displayName}</h1> {/* e.g: John Doe */}
+            <p>{authUser.username}</p> {/* e.g: johndoe */}
+            <p>{authUser.familyName}</p> {/* e.g: Doe */}
+            <p>{authUser.givenName}</p> {/* e.g: John */}
+            <p>{authUser.initials}</p> {/* e.g: JD */}
+            <p>{hasAccess('operation1', 'operation2')}</p>
+        </div>
+    );
+};
+```
+
+### useCatalog
+
+Use this hook to get access to the current ecosystem applications and modules catalog
+
+```jsx
+import { useCatalog } from '@bluealba/pae-ui-react-core';
+
+const TestComponent = () => {
+    const { catalog } = useCatalog();
+    return (
+        <div>
+        {catalog.map((item) => (
+            <div key={item.name}>
+                <h1>{item.name}</h1>
+                <p>{item.version}</p>
+            </div>
+        ))}
+        </div>
+    );
+};
+```
+
+### useServiceInvoker
+
+Use this service to make a request to a PAE microservice. This way you don't need to know under which path it is exposed
+by the system (gateway). And you just need to know the service/module full name.
+It returns a function that is fully compatible with the `fetch` function
+
+```typescript jsx
+const invoker = useServiceInvoker("@acme/my-wheather-service");
+
+return (
+    <button onClick={() => invoker('/get-temperature', { method: 'GET' })}>Load</button>
+)
+```
+
+Internally this hook uses the catalog to resolve the service full URL (there is also a `useServiceBaseUrl` hook)
+
+### useTrackEvent
+
+Use this service to track Application Usage Events. This is the frontend API to PAE Habits Service.
+
+```typescript jsx
+const trackEvent = useTrackEvent();
+
+const trackClickEvent = useCallback(async e => {
+    await trackEvent("button-click-app2", {
+      buttonText: e.target.innerText
+    });
+  },
+  [trackEvent]
+  );
+
+return (
+    <button onClick={trackClickEvent}>Click Me</button>
+)
+```
+
+The `trackEvent()` function receives the name of the event and a custom payload that can be anything you want.
+PAE will automatically store this event with contextual information such as: the current User, the Module that triggered
+this event and its version and the associated Application (if the module has one), together with timestamps.
+
+Alternatively you can also use `useTrackEvents()` (plural) hook to publish more than one event in a single call.
+
+## Authorization
+
+In order to render a piece of JSX conditionally based on authorization there are two ways to do this.
+ * using the `useAuth()` hook: which is more "manual" but powerful
+ * using the `<Authorized>` component
+
+### useAuth()
+
+With this hook you get the current user and a utility function `hasAccess()`
+
+```typescript jsx
+const MyComponent = () => {
+  const { authUser, hasAccess } = useAuth();
+  return (
+      <div>
+        {hasAccess('operation1', 'operation2') && (
+            <div>access granted</div>
+        )}
+      </div>
+  )      
+}
+```
+
+### `<Authorized>` component (recommended)
+
+This component only renders the children content if the user has the specified operations
+
+```typescript jsx
+const MyComponent = () => {
+  return (
+      <Authorized operations={['create-entity', 'update-entity']}>
+        <SectionContent>
+          <p>You have access to this section</p>
+        </SectionContent>
+      </Authorized>
+  )
+}
+```
+If it has no access then nothing is rendered.
+
+There's also an optional property `forbiddenContent` with which you can specify the content to be displayed in case the user has no grant on the operations.
+
+This prop is overloaded and you can pass different content.
+ * The name of a React component
+ * A render function
+ * A straight JSX content
+ 
+For example a render function
+
+```typescript jsx
+// passing a React component
+<Authorized operations={['create-entity', 'update-entity']} forbiddenContent={ForbiddenComponent}>
+  <SectionContent>
+    <p>You have access to this section</p>
+  </SectionContent>
+</Authorized>
+
+// passing a render prop function
+<Authorized operations={['create-entity', 'update-entity']} forbiddenContent={({ operations }) => <ForbiddenComponent operations={operations} />}>
+  <SectionContent>
+    <p>You have access to this section</p>
+  </SectionContent>
+</Authorized>
+
+// passing content directly
+<Authorized operations={['create-entity', 'update-entity']} forbiddenContent={<div>Section not allowed</div>}>
+  <SectionContent>
+    <p>You have access to this section</p>
+  </SectionContent>
+</Authorized>
+```
+
+
+## Extension Points
+
+They allow UI modules to declare points such as React components that can be later replaced by another value/component
+from another UI module dynamically.
+
+### Declaring an extension point
+There are two ways for a MF to declare an extension point that can be later extended by other MFs. Internally they both the the same thing, it is just a matter of a different flavor of API.
+
+ * `<ExtensionPoint>` component: useful to declare an extension point inline within a JSX
+ * `extensionPoint()` HOC (high-order component): useful to make a whole component replaceable as an extension point.
+
+#### Declaring an extension point inline with ExtensionPoint component
+
+In any component’s JSX you can declare an extension point, like a “slot” to be extended by other MFs.
+
+```typescript jsx
+const MyComponent = () => {
+  return (
+    <div>
+      Hello <ExtensionPoint name="Greeting" />
+    </div>
+  )
+}
+```
+
+This will create an extension point that is scoped to the current module with the given name. For example `my-module::Greeting`
+
+You can include children elements that will be the fallback/default content in case nobody extends this extension point
+
+```typescript jsx
+const MyComponent = () => {
+  return (
+    <div>
+      Hello <ExtensionPoint name="Greeting"> World </ExtensionPoint>
+    </div>
+  )
+}
+```
+
+#### Declaring a component as an extension point with the HOC
+There’s another common case where you want a whole component to be “replaceable” completely as an extension point. In this case you can use the `extensionPoint(component)` HOC as a shortcut to void creating a wrapper component just for this.
+
+For example the `pae-shell-ui` (or any MF) declares a React component to be an “extension point” by simply using a new `pae-ui-react-core` HOC wrapping the component that is the menu
+
+```typescript jsx
+const MenuApplicationSelector: React.FC = () => {
+  // regular react component
+}
+
+// the displayName becomes the extension point name by inference (it can be set manual optionally in the hoc call)
+MenuApplicationSelector.displayName = 'ApplicationSelector';
+
+// here we are wrapping the component using the HOC which makes it an extension point
+export default extensionPoint(MenuApplicationSelector);
+```
+
+If no-one is extending the point the the component will be rendered. If someone extends it then this component won’t be mounted at all, and it will be replaced by the extending component.
+
+### Extending an Extension Point
+
+Then another MF can extend that point in two different ways:
+
+ * `ExtendExtensionPoint`: Using a built-in component rendering the content inline
+ * `useExtendExtensionPoint`: using a hook which allows more programmatic control
+
+We will see both options below:
+
+#### Using the ExtendExtensionPoint component
+
+With a React Component provided by pae-ui-react-core
+
+```typescript jsx
+// somewhere in your MF DOM
+<ExtendExtensionPoint module="@bluealba/pae-shell-ui" point="ApplicationSelector">
+  Hello <strong>World</strong> From an Extension!
+</ExtendExtensionPoint>
+```
+
+#### Using the useExtendExtensionPoint hook
+
+Or more "manually" using the useExtendExtensionPoint hook
+
+```typescript jsx
+const Root = () => {
+  // register the extension
+  useExtendExtensionPoint('@bluealba/pae-shell-ui', 'ApplicationSelector', CustomApplicationMenu)
+  
+  return <div> your app content here </div>
+}
+```
+
+In both cases the extension follows the regular React lifecycle ! Meaning that when the component that called the hook/included the extension component gets unmounted, then the extension point gets un-registered dynamically.
+Then this means that components are extended / disengaged  dynamically.
+
+# Library Development
+
+This section is for PAE platform developers or anyone that wants to make changes to this repository.
+This Library is one of the "client facing" API for PAE. Meaning that it is the API that exposes all PAE behavior to 
+microfrontends for different customers and projects. 
+Because of this we must be very careful with changes in terms of backward compatibility. This is the first layer of 
+integration. Some projects might be using different versions of PAE and this library.
+
+Therefore we should try to reduce the number of non-backwards compatible changes !!
+
+## Development Process and Releasing
+
+To make modifications and have them automatically picked while working locally you should run
+
+```bash
+npm run build-and-publish:watch
+```
+Just make sure that you have the `pae-orchestrator-service` cloned as a sibling folder to this repo.
+
+The following content describes what happens under the hood.
+The cycle goes like this:
+* Create feature branches to work in a feature
+* Eventually merge them into `develop` branch. This will build but not publish any package
+* Once you reached a point where you want to publish a new release. Bump the version to the target version you want to publish and create a PR to `main`
+* Once merged into main the pipeline will automatically build and publish the version to NPMjs public repository.
+
+Now there are 2 more steps to follow in order to start using this published version (next sections)
+
+### Update PAE Orchestrator
+
+In the PAE architecture the orchestrator is the one that automatically includes this library in runtime for all
+applications. It has its own locally cached bundle js of this library.
+To update it you must
+
+* Edit the `build/libs/build-libs.mjs` file in `pae-orchestrator-service` to update the "shared-libraries" entry with the version you just published
+* Run `npm run build:libs` in the orchestrator so that it fetches this new version and caches it
+* Merge to develop to create a new build/image of the orchestrator
+* Apply it to any environment / product you want
+
+### Projects Microfrontends
+
+Every microfrontend includes this library as a `devDependency` so that Typescript can use it for type checking.
+Then once built this is not included, because the orchestrator includes it in runtime (think of it as a dynamically
+linked library).
+Nevertheless this means that in order to catch errors and be consistent each microfrontend dependency must match
+the same version of this lib as the orchestrator has for its specific product.
+
+So once you release a new version of this lib and update the orchestrator to use it. When you bump the orchestrator
+version for a particular product, you should be going through all your microfrontends and update the devDependency
+to match the released version.