@startinblox/boilerplate 3.0.2 → 3.0.3

package/README.md

@@ -1,85 +1,248 @@
-# Boilerplate
+# Startin'blox components repository boilerplate
 
-## Table of Contents
+## Introduction
 
-1. [Introduction](#introduction)
-2. [Installation](#installation)
-3. [Development](#development)
-4. [Tests](#tests)
-5. [Storybook](#storybook)
-6. [Build](#build)
-7. [License](#license)
+This repository provides a boilerplate for developing Startin'blox web components. It streamlines the creation and deployment of web components, whether used independently or integrated with the Startin'blox ecosystem, including Lit, Startin'blox Core, Startin'blox Store, Startin'blox Router, and Startin'blox Orbit. The primary objective is to enable developers to concentrate on web component logic by abstracting common complexities and providing out-of-the-box functionalities.
 
-## Introduction
+## Features
 
-This is a boilerplate of startin'blox component.
+This boilerplate includes:
 
-## Installation
+* **Localization:** Compatibility with platforms like Weblate, powered by [`@lit/localize`](https://www.npmjs.com/package/@lit/localize).
+* **Data Management:** A comprehensive wrapper around the Startin'blox Store for simplified property handling (RDF or named).
+* **Component Awareness:** Mechanisms to manage race conditions and inheritance across external components.
+* **Helper Utilities:** Functions for data reactivity, filtering, and sorting.
+* **Development Tools:**
+  * **Storybook:** For component documentation and isolated development, reducing the need for a heavy local environment.
+  * **Cypress:** For component testing.
+  * **Unpluggin Icons:** Access to a vast library of icons from [Iconify](https://icon-sets.iconify.design/).
+  * **Lit Integration:** Pre-made component classes to accelerate development.
+  * **Vite-powered:** Typescript, SASS, PostCSS, Autoprefixer... Focus on your component logic, not the build process.
 
-```bash
-npm install
-```
+## Getting started
 
-## Development
+### Creating a new components repository
 
-```bash
-npm run watch
-```
+To initialize a new component repository from this boilerplate:
 
-## Tests
+1. Clone this repository.
+2. Rename the `origin` remote to `upstream`:
 
-```bash
-npm run cy:run
-```
+    ```bash
+    git remote rename origin upstream
+    ```
 
-or
+3. Update the `name`, `description`, and `repository.url` fields in [`package.json`](package.json).
+4. Commit the changes with a `major: Initial commit` message.
+5. Create a new repository on [git.startinblox.com/components](https://git.startinblox.com/components/).
+6. Add the new repository as the `origin` remote:
 
-```bash
-npm run cy:open
+    ```bash
+    git remote add origin https://git.startinblox.com/components/your-component-name.git
+    ```
+
+7. Configure Gitlab settings (branch protection rules, FF merge only, clone instead of fetch).
+8. Push to `origin master`.
+
+For production usage, components can be served via a CDN like JSDelivr or self-hosted.
+
+```html
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@startinblox/core@latest/dist/store.js"></script>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/your-component-name@latest"></script>
+  <!-- ... -->
+  <your-component-1 data-src="..."></your-component-1>
+  <your-component-2>Hello World!</your-component-2>
+  <!-- etc. -->
 ```
 
-## Storybook
+### Installation
+
+To set up the local development environment with Storybook:
 
 ```bash
+npm install
 npm run storybook
 ```
 
-## Build
+## Development environment
 
-```bash
-npm run build
+This boilerplate is designed as a **library** for multiple web components and intentionally **does not include** a default `index.html` file.
+
+**Storybook** is the primary development environment for isolated component development and documentation. **Cypress** is integrated for component testing.
+
+For components intended to be packaged within the broader Startin'blox environment, integrating with a local Orbit instance is recommended.
+
+### Updating from the boilerplate
+
+To keep your component repository synchronized with updates from this boilerplate:
+
+1. Ensure `upstream` is configured to point to this boilerplate's repository.
+2. Pull changes from the boilerplate's `upstream`:
+
+    ```bash
+    git pull upstream master
+    ```
+
+3. Resolve any merge conflicts. Changes outside the boilerplate's core code should merge smoothly.
+4. Push the updates to `origin master`.
+
+## Core Concepts
+
+### Pre-made component classes
+
+* `OrbitComponent`: A component designed to display or handle a Resource or Container, optionally extending its functionality for Orbit integration.
+* `ObjectsHandler`: A component for rendering an array of objects, typically used within an `OrbitComponent` to display a Container.
+* `ObjectHandler`: A component for rendering a single object, commonly used within an `OrbitComponent` or `ObjectsHandler` to display a Resource.
+
+### Store reactivity
+
+* `setupCacheInvalidation`: Invalidates the store cache and updates the component when a `save` event occurs for resources listed by specified attributes and keywords.
+* `setupOnResourceReady`: Invalidates the store cache and updates the component upon a `resourceReady` event, independent of attributes.
+* `setupOnSaveReset`: Resets form values by calling the `_setValue` method (which must be custom-implemented) on a `save` event containing specified keywords.
+
+Custom cache invalidation methods can be added:
+
+```javascript
+async _afterAttach() {
+  this._subscriptions.add(["name-of-the-event", (e) => {
+    // Logic to execute when `name-of-the-event` occurs
+  }]);
+  // Ensure event deduplication before re-subscribing
+  this._subscribe();
+  // _afterAttach expects a Promise, you can reject on error
+  return Promise.resolve();
+}
 ```
 
-## Localization
+### `OrbitComponent` default attributes and methods
 
-This project uses [`@lit/localize`](https://www.npmjs.com/package/@lit/localize) for internationalization.
+**Attributes:**
 
-### Extracting strings
+* `defaultDataSrc`: (Optional) Used within Lit Tasks to track the original data source when the component's `dataSrc` is rewritten.
+* `dataSrc`: (Optional) Specifies the resource to display within a Lit Task.
+* `nestedField`: (Optional) Requires manual handling within a Lit Task.
+* `uniq`: (Optional) Allows multiple instances of the component within the same DOM.
+* `route`: (Optional) Enables router-awareness, preventing rendering/updating when the current route does not match expectations.
+* `cherryPickedProperties`: (Required) An array describing the expected RDF or named properties for the component.
 
-To extract strings for translation, run:
+**Methods:**
 
-```bash
-npm run locale:extract
+* `render`: A Lit method; refer to Lit documentation. Should return a Lit Task or `nothing`.
+* `_afterAttach`: An asynchronous method called after the component is attached to the DOM and fully initialized. Expects a resolved or rejected Promise.
+* `_navigate(e)`: Facilitates navigation using the router and predefined attributes within a `render` method.
+* `_getProxyValue(dataSrc)`: An asynchronous method typically called within a Lit Task. It retrieves data based on `cherryPickedProperties`, is recursive by default, and allows `cherryPickedProperties` to be overridden.
+* `_responseAdaptator(res)`: An asynchronous method called before `_getProxyValue` returns its result, allowing for response adaptation (e.g., prefixing a `name` property based on `type`).
+* `gatekeeper`: A pre-written method for components intended to operate exclusively within Orbit, simplifying gatekeeping logic.
+
+`OrbitComponent` inherits methods from `ObjectsHandler`.
+
+### `ObjectsHandler` methods
+
+* `hasType(type)`: Checks if any object within `this.objects` shares the requested type, returning a boolean.
+* `renderTemplateWhenWith(property, callback)`: Renders the `callback` if the specified property (or properties) is present. Nested arrays enable `OR` testing, while `AND` testing is implicit. Example: `[["name", "shortname"], "description"]` returns the callback if (`name` OR `shortname`) AND `description` are present.
+
+### `ObjectHandler` methods
+
+* `isType(type)`: Checks if the object shares the requested type, returning a boolean.
+* `renderTemplateWhenWith`: Functions identically to the `ObjectsHandler` method but applies to a single object.
+
+### Available helpers
+
+The `src/helpers` directory contains various utilities:
+
+* `datas`:
+  * `dataBuilder`: For creating mock data.
+  * `filterGenerator`: For seamless object filtering using `filterObjectByX` methods.
+  * `sort`: A general-purpose sorting method.
+* `ui`:
+  * `formatDate`: For date formatting using native `Intl` methods.
+  * `lipsum`: For configuring mock word, sentence, or paragraph generation.
+* `utils`:
+  * `requestNavigation`: A wrapper around the Startin'blox Router for JavaScript-based navigation.
+  * `uniq`: A unique ID generator.
+
+### `cherryPickedProperties` explained
+
+The `cherryPickedProperties` array within an `OrbitComponent` defines the properties expected by the component. Each entry can have up to four attributes:
+
+* `key`: The original property name or RDF.
+* `value`: The name this property will have within the component.
+* `cast`: A callback function (e.g., `formatDate` helper) to transform the property's value.
+* `expand`: If `true`, and the property contains a Resource or Container, it will be recursively expanded using the same `cherryPickedProperties`. Exercise caution with circular dependencies; `_responseAdaptator` is often more suitable for such cases, allowing `_getProxyValue` to be called with `recursive=False` or different `cherryPickedProperties`. Defaults to `false`.
+
+**Example:**
+
+```typescript
+  cherryPickedProperties: PropertiesPicker[] = [
+    { key: "name", value: "name" },
+    // Using the project property two times: One with a cast to keep its @id, and one expanded giving complete access to its datas
+    { key: "project", value: "projectId", cast: (r) => r["@id"] },
+    // This will expand the `project` property, using the same cherryPickedProperties, so it'll contain any `project.name`, `project.project` and `project.description`
+    { key: "project", value: "project", expand: true },
+    { key: "description", value: "description" },
+    // In any case, the `_originalResource`, the `@id`, `@context` and `@type` will be fetched and accessible
+  ];
 ```
 
-This command will generate XLIFF files in the `locales` directory.
+## Development workflow
+
+### Localization
 
-### Changing locale
+This project utilizes [`@lit/localize`](https://www.npmjs.com/package/@lit/localize) for internationalization.
 
-To change the locale, run:
+1. Configure [`lit-localize.json`](lit-localize.json), specifically the `targetLocales` key.
+2. Run `npm run locale:extract` to generate initial localization files.
+3. Execute `npm run locale:extract` to update localization files whenever `str` or `msg` methods from Lit Localize are used. XLIFF files will be generated in the `locales` directory.
+4. Before production deployment, run `npm run locale:build` to generate built localization files.
+
+To change the locale at runtime within an application:
 
 ```javascript
 window.setLocale.map((setLocale) => setLocale("your-lang-code"));
 ```
 
-### Getting current locale
-
-To get the current locale, run:
+To retrieve the current locale:
 
 ```javascript
 window.getLocale.map((locale) => console.log(locale));
 ```
 
+### Testing
+
+```bash
+# Run all tests
+npm run cy:run
+# Open Cypress's interface
+npm run cy:open
+```
+
+### Building for production
+
+```bash
+# Generate localization files
+npm run locale:build
+# Generate Storybook documentation
+npm run build-storybook
+# Build the component repository
+npm run build
+```
+
+## Orbit integration
+
+Components built with this boilerplate are designed to work seamlessly with Orbit without requiring specific configurations.
+
+To prevent potential race conditions, include `import @src/initializer;` at the top of your component's file, before the `@customElement` declaration.
+
+Application performance can be optimized by utilizing the `gatekeeper` method within your `OrbitComponent`'s render methods.
+
+Note that without a complete Orbit environment, interactions with external components (e.g., route management, component deduplication, global localization, conditional component display) may be limited.
+
+## Best practices
+
+Adhere to general web component usage rules, as outlined by [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) or the [webcomponents.org guideline](https://www.webcomponents.org/introduction).
+
+Tailor web components to their expected application environment. Features like the gatekeeper and localization usage should be standard practice, not exceptions. This approach ensures components are efficient and integrate effectively with the broader application and other components.
+
 ## License
 
 [MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startinblox/boilerplate",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Startin'blox Boilerplate",
   "main": "dist/index.js",
   "type": "module",