Harmonize structure and update wordings

src/packages/authentication-keycloak/README.md

@@ -1,20 +1,20 @@
 # @open-pioneer/authentication-keycloak
 
-This package provide a plugin for the [authentication package](https://github.com/open-pioneer/trails-core-packages/blob/main/src/packages/authentication/README.md#implementing-an-authentication-plugin) that supports [Keycloak](https://www.keycloak.org/).
+This package provides a [Keycloak](https://www.keycloak.org/) plugin for the [authentication package](https://github.com/open-pioneer/trails-core-packages/blob/main/src/packages/authentication/README.md#implementing-an-authentication-plugin).
 
-The package implements an actual authentication flow using the [Keycloak JavaScript](#https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter) adapter.
-For further Information, how Keycloak works please visit the official documentation of [Keycloak](https://www.keycloak.org/).
-
-> **_NOTE:_** The package only works with the central [authentication package](https://github.com/open-pioneer/trails-core-packages/blob/main/src/packages/authentication/README.md#implementing-an-authentication-plugin).
+The package implements an authentication flow using the [Keycloak JavaScript](#https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter) adapter.
+For more information about Keycloak, see the [Keycloak documentation](https://www.keycloak.org/).
 
 ## Usage
 
 To use the package in your app, first import the `<ForceAuth />` component from the [authentication package](https://github.com/open-pioneer/trails-core-packages/blob/main/src/packages/authentication/README.md#enforcing-authentication) to make sure that only logged in users can use the application.
 
 `ForceAuth` renders its children (your application) if the user is authenticated.
-Otherwise, it redirect the user to the Keycloak authentication provider.
+Otherwise, it redirects the user to the Keycloak authentication provider.
+
+To access the `SessionInfo` for the currently logged in user, use the `useAuthState` hook provided by the authentication package.
 
-To access the `SessionInfo` for the current logged in user, you can use the `useAuthState` hook provided by the authentication package.
+The following example shows a basic implementation of the functions described before:
 
 ```tsx
 // AppUI.tsx
@@ -44,7 +44,7 @@ export function AppUI() {
 ### Keycloak configuration properties
 
 To configure the `authentication-keycloak` package, adjust these properties.
-For more details on the configuration properties, please visit the official documentation [API Reference](https://www.keycloak.org/docs/latest/securing_apps/index.html#api-reference).
+For more details on the configuration properties, visit the [API Reference](https://www.keycloak.org/docs/latest/securing_apps/index.html#api-reference).
 
 | Property            |        Type         |                                                                                                           Description |                                             Default |
 | ------------------- | :-----------------: | --------------------------------------------------------------------------------------------------------------------: | --------------------------------------------------: |
@@ -112,13 +112,13 @@ const element = createCustomElement({
 
 ### Error reporting
 
-In case of an error during authentication (i.e. if the keycloak client lib throws an error during `init`), a notification will be presented to the user via the `NotificationService` (technical details can be found in the developer console).
+In case of an error during authentication (if the Keycloak client library throws an error during `init`), a notification is presented to the user via the `NotificationService` (technical details can be found in the developer console).
 You should therefore embed the `<Notifier />` into your application as well.
 Note that the Notifier should not be nested in `<ForceAuth />`, because it would not be rendered in case of an authentication problem.
 
 ### Accessing the Keycloak token in your application
 
-After a successful login, the Keycloak token can be accessed from the `SessionInfo` of the `AuthService`.
+After a successful login, the Keycloak token can be accessed from the `SessionInfo` of the `AuthService` as in the following sample:
 
 ```ts
 //SampleTokenInterceptor.ts

src/packages/authentication/README.md

@@ -88,7 +88,7 @@ The plugin must implement the `AuthPlugin` TypeScript interface exported by this
 
 -   Implement the `logout()` method: this method is called when the user attempts to end their session.
 
-A simple example is available in this project's `auth-sample`.
+An example is available in this project's `auth-sample`.
 
 ## License
 

src/packages/chakra-integration/README.md

@@ -1,14 +1,13 @@
 # @open-pioneer/chakra-integration
 
-This package integrates [Chakra UI](https://chakra-ui.com/) into Open Pioneer Trails application.
+This package integrates [Chakra UI](https://chakra-ui.com/) into an Open Pioneer Trails application.
 All components are re-exported from `@chakra-ui/react` (sometimes with some modifications).
 All UI packages using the Open Pioneer Trails framework should use this package instead of depending on `@chakra-ui/react` directly.
 
 ## Internals
 
-Some changes are made to complex components such as `Modal`, `Drawer` etc. to support integration
-into a web component's shadow dom.
-See comments in `./Provider.tsx` for more details.
+Some changes are made to complex components such as `Modal`, `Drawer` etc. to support integration into a web component's shadow DOM.
+For more details, see comments in `./Provider.tsx`.
 
 ## License
 

src/packages/core/README.md

@@ -6,7 +6,9 @@ This package contains basic utility functions and classes used in Open Pioneer T
 
 The package exports the `EventEmitter` class that supports emitting and subscribing to user defined events.
 
-## Errors
+## Usage
+
+### Errors
 
 The `Error` class extends JavaScript's global error class with a user defined `id` value that
 can be used to explicitly identify error conditions.
@@ -32,19 +34,19 @@ try {
 const errors = getErrorChain(error);
 ```
 
-## Resources
+### Resources
 
 The `Resource` type exported from this package is used by objects with a destructor.
 All object needing some cleanup action to be called should use the `destroy` method for consistency and easier handling.
 
-## Logger
+### Logger
 
 The 'Logger' class provides a logger for standardized application wide logging.
-The log level is configured globally in the vite.config.js.
+The log level is configured globally in the file `vite.config.js`.
 
 To create a logger instance, call the `createLogger` method.
 It takes a prefix (string) to prepend to each message.
-Use `:` as a separator to encode hierarchical names (e.g. `"some-package:SomeClass"`).
+To encode hierarchical names, use `:` as a separator (for example `"some-package:SomeClass"`).
 
 The logger provides log methods for the following log levels with the following order: DEBUG < INFO < WARN < ERROR.
 

src/packages/http/README.md

@@ -2,9 +2,9 @@
 
 This package provides the `HttpService`, which can be used to request resources over HTTP.
 
-## Quick start
+## Usage
 
-Reference the interface `http.HttpService` from your service:
+To use the HTTP service, reference the interface `http.HttpService` from your service as in the following sample:
 
 ```js
 // build.config.mjs
@@ -23,9 +23,7 @@ export default defineBuildConfig({
 });
 ```
 
-The snippet above will inject the `HttpService` as `httpService`.
-
-Then, from the implementation class of `MyService`, simply call `fetch()` on the service:
+From the implementation class of `MyService`, call `fetch()` on the service:
 
 ```js
 // MyService.js
@@ -41,11 +39,11 @@ export class MyService {
 ```
 
 The signature of the `fetch()` method is compatible to the Browser's global [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) function.
-However, the `HttpService`'s method should always be preferred to take advantage of future features (logging, proxy support, etc.).
+However, the `HttpService`'s method should be preferred to take advantage of future features (such as logging or proxy support).
 
-## Request interceptors
+### Request interceptors
 
-> Note that the request interceptor API is experimental: it may change with a new minor release as a response to feedback.
+> The request interceptor API is experimental: it may change with a new minor release as a response to feedback.
 
 The `HttpService` supports extension via _request interceptors_.
 Request interceptors can modify requests (query parameters, headers, etc.) before they are sent to the server.

src/packages/integration/README.md

@@ -1,16 +1,15 @@
 # @open-pioneer/integration
 
-Provides techniques for the communication between an application (web component) and its embedding site.
+This package provides techniques for the communication between an application (web component) and its embedding site.
 This is useful when the application's web component is embedded into another site.
 
-The package exports the `ApiExtension` interface that can be used to provide API functions
-that can be called from the outer site to trigger actions in the web component.
+The package exports the `ApiExtension` interface that can be used to provide API functions that can be called from the outer site to trigger actions in the web component.
 The ApiExtension support is implemented in the `@open-pioneer/runtime` package.
 
 Additionally, the package contains the `ExternalEventService`,
 which can be used to emit events to the host site from inside the Open Pioneer Trails application.
 
-## Quick start
+## Usage
 
 ### Web component API
 
@@ -57,7 +56,7 @@ export class TextApiExtension implements ApiExtension {
 
 To use the API methods in the surrounding site, call the `when()` method on the app.
 It resolves to the app's API when the application has started.
-Thereupon it is possible to call the provided methods on the returned API instance.
+It is then possible to call the provided methods on the returned API instance.
 
 For example:
 
@@ -81,7 +80,7 @@ For example:
 ```
 
 > Note: The `when()` method is implemented as a method on the custom element class generated by the `createCustomElement()` function in the runtime package.
-> It will be available once the web component has been defined (which is why the example code waits by calling `customElements.whenDefined`).
+> It is available once the web component is defined (which is why the example code waits by calling `customElements.whenDefined`).
 
 ### ExternalEventService
 
@@ -118,7 +117,7 @@ eventService.emitEvent("extent-selected", {
 eventService.emitEvent(new CustomEvent(...));
 ```
 
-The events will be emitted on the application's host node.
+The events are emitted on the application's host node.
 You can subscribe to them from outside the application via `addEventListener`:
 
 ```js

src/packages/local-storage/README.md

@@ -5,9 +5,9 @@ This package provides access to the browser's [local storage](https://developer.
 A single local storage key (configurable, see [Configuration](#configuration)) is used to keep track of the application's persistent data.
 Packages using the `LocalStorageService` can work with arbitrary values (including nested data structures) through a convenient API.
 
-> NOTE: The `LocalStorageService` will read the persistent data from the browser's local storage on application startup.
-> Changes to that data made via the `LocalStorageService` will be reflected in the browser's local storage immediately.
-> Concurrent changes made to the browser's local storage **will not** be reflected by the `LocalStorageService`.
+> NOTE: The `LocalStorageService` reads the persistent data from the browser's local storage on application startup.
+> Changes to that data made via the `LocalStorageService` are reflected in the browser's local storage immediately.
+> Concurrent changes made to the browser's local storage **are not** reflected by the `LocalStorageService`.
 > In other words, there is no two-way synchronization between the two systems while the application is running.
 >
 > You should not attempt to modify the local storage value managed by the `LocalStorageService` (see `storageId` in [Configuration](#configuration)) through the "raw" Browser APIs while the application is running.
@@ -27,14 +27,14 @@ const storageService = ...; // injected
 console.log(storageService.isSupported);
 ```
 
-If local storage is not supported, other methods (such as `get()` and `set()`) will throw an error.
+If local storage is not supported, other methods (such as `get()` and `set()`) throw an error.
 
 ### Reading and writing values
 
 In its most basic form, you can use the `LocalStorageService` similar to a map.
-In the background, changes to the service will always be persisted into local storage.
+In the background, changes to the service are always persisted into local storage.
 
-All keys and values used in the `LocalStorageService` will be serialized to JSON via `JSON.stringify()`.
+All keys and values used in the `LocalStorageService` are serialized to JSON via `JSON.stringify()`.
 Thus, only values supported by JSON can be used.
 
 Example:
@@ -57,11 +57,11 @@ storageService.clear();
 
 You can use the `LocalStorageService` to manage hierarchical data, including objects and arrays (see above).
 _Namespaces_ can help you treat an object as a group of (nested) properties.
-Getting or setting entries in the namespace will update an object behind the scenes.
+Getting or setting entries in the namespace update an object behind the scenes.
 
 To use a namespace, call `getNamespace(key)` on either the `LocalStorageService` or another `LocalStorageNamespace` object.
 The `key` used in `getNamespace(key)` should either already be associated with an object or it should not be set to a value at all.
-If `key` is not yet associated with an existing object, a new empty object will be created.
+If `key` is not yet associated with an existing object, a new empty object is created.
 
 Example:
 
@@ -82,13 +82,13 @@ const namespace = storageService.getNamespace("my-package-name");
 namespace.set("my-state", "some-value-to-save");
 ```
 
-> NOTE: Multiple namespace instances using the same `key` will manipulate the same object and see each other's effects.
+> NOTE: Multiple namespace instances using the same `key` manipulate the same object and see each other's effects.
 
 ### Configuration
 
 | Name        | Type   | Description                                                                                                                                                                                                                   |
 | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `storageId` | String | The key under which the persistent data will be saved. This value should be configured to a reasonably unique value to avoid clashes with other applications at the same origin. Defaults to `trails-state` (with a warning). |
+| `storageId` | String | The key under which the persistent data is saved. This value should be configured to a reasonably unique value to avoid clashes with other applications at the same origin. Defaults to `trails-state` (with a warning). |
 
 ### Implementation notes
 

src/packages/notifier/README.md

@@ -6,7 +6,7 @@ This package allows a developer to emit global notifications from any applicatio
 
 ### Displaying notifications in an application
 
-The `<Notifier />` must be used in your app's UI , otherwise notifications from application components will not be shown. It should be present exactly once.
+The `<Notifier />` must be used in your app's UI , otherwise notifications from application components are not shown. It should be present exactly once.
 
 ```jsx
 import { Notifier } from "@open-pioneer/notifier";
@@ -36,7 +36,7 @@ export interface NotifierProps {
 }
 ```
 
-The implementation of `<Notifier />` is currently based on [Chakra's Toast](https://chakra-ui.com/docs/components/toast).
+The implementation of `<Notifier />` is based on [Chakra's Toast](https://chakra-ui.com/docs/components/toast).
 
 ### Emitting notifications
 

src/packages/react-utils/README.md

@@ -2,7 +2,9 @@
 
 This package provides React utilities that help a developer create applications.
 
-## Titled sections
+## Usage
+
+### Titled sections
 
 Use the `<TitledSection>` and `<SectionHeading>` components instead of raw `hX` HTML tags (such as `<h1>` or `<h2>`).
 This way, the appropriate heading level is determined automatically.
@@ -41,9 +43,9 @@ Example:
 In the preceding example the topmost heading(s) in `TheRestOfYourApplication` start at level 2, and nested headings use increasing levels as usual.
 For more details, see the API documentation.
 
-## Hooks
+### Hooks
 
-### useCommonComponentProps()
+#### useCommonComponentProps()
 
 A helper hook that automatically computes `containerProps`: common properties to set on the topmost container element of a public component.
 
@@ -76,7 +78,7 @@ export const InitialExtent: FC<InitialExtentProps> = forwardRef(function Initial
 });
 ```
 
-### useEvent()
+#### useEvent()
 
 The `useEvent` can be used to obtain a stable event handler function with changing implementation.
 This is useful to avoid re-triggering `useEffect`-hooks when only the event handler changed.