@startinblox/boilerplate 5.0.0 → 6.0.0

package/.gitlab-ci.yml

@@ -37,7 +37,7 @@ prepare:
 test:
   stage: test
   image: 
-    name: cypress/included:15.9.0
+    name: cypress/included:15.10.0
     entrypoint: [""]
   before_script:
     - npm ci --cache .npm --prefer-offline

package/AGENTS.md

@@ -0,0 +1,518 @@
+# AGENTS.md
+
+This file contains guidelines for agentic coding assistants working in this repository.
+
+If the file `scripts/init.js` exists, ask the user to run `npm run init` first.
+
+## Commands
+
+### Build & Development
+
+- `npm run build` - Build production bundle (includes lit-localize build)
+- `npm run watch` - Development server with hot reload
+- `npm run serve` - Preview production build locally
+
+### Testing (Cypress)
+
+- `npm run cy:run` - Run all Cypress component tests
+- `npm run cy:open` - Open Cypress interactive test runner
+- **Single test**: Run specific test by filtering with `--spec` (e.g., `npm run cy:run -- --spec "cypress/component/solid-boilerplate.cy.ts"`)
+
+### Linting & Formatting
+
+- `npx biome check .` - Check code for issues
+- `npx biome check . --write` - Auto-fix linting issues and format code
+
+### Storybook
+
+- `npm run storybook` - Start Storybook dev server (port 6006)
+- `npm run build-storybook` - Build static Storybook
+
+### Localization
+
+- `npm run locale:extract` - Extract translatable strings to XLIFF files
+- `npm run locale:build` - Build localization for production
+
+**Important**: Always run `npm run locale:build` before building for production. The build commands (`npm run build`, `npm run build-storybook`) also run this automatically.
+
+## Code Style Guidelines
+
+### Formatting (Biome.js)
+
+- Use Biome.js for all formatting and linting
+- 2-space indentation (no tabs)
+- Double quotes for strings
+- Semicolons required at end of statements
+- Imports are auto-organized (run `npx biome check . --write` to organize)
+
+### TypeScript
+
+- Strict mode enabled in tsconfig.json
+- Use type annotations explicitly (no inferrable types rule)
+- `any` type is allowed but avoid when possible
+- Define types in `src/component.d.ts` for shared types
+
+### Component Conventions
+
+#### Naming
+
+- Web component element names: kebab-case (e.g., `solid-boilerplate`)
+- Class names: PascalCase (e.g., `SolidBoilerplate`)
+- Properties/attributes: kebab-case in HTML (e.g., `data-src`), camelCase in JS (e.g., `dataSrc`)
+- Private methods: prefix with `_` (e.g., `_afterAttach`, `_navigate`)
+
+#### Lit Decorators
+
+- `@customElement("element-name")` - Define web component
+- `@property({ attribute: "data-src", reflect: true })` - Public attributes that reflect to DOM
+- `@property({ attribute: false, type: Object })` - For object properties (no attribute reflection)
+- `@state()` - Private reactive state
+- `@localized()` - For components using i18n (from @lit/localize)
+
+Properties can have default values:
+
+```typescript
+@property({ attribute: "header", type: String })
+header?: string = "Default Header";
+```
+
+#### Event Handlers
+
+All event handlers should prevent default behavior:
+
+```typescript
+_handleEvent(e: Event) {
+  e.preventDefault();
+  // handler logic
+}
+```
+
+#### Component Base Classes
+
+This boilerplate provides three base component classes with different capabilities:
+
+##### ComponentObjectHandler
+
+Use for components that display **a single resource**. Simplest base class with minimal overhead.
+
+```typescript
+import { ComponentObjectHandler } from "@helpers";
+
+@customElement("my-card")
+export class MyCard extends ComponentObjectHandler {
+  @property({ attribute: false, type: Object })
+  object: Resource = { "@id": "" };
+
+  render() {
+    return html`<div>${this.object.name}</div>`;
+  }
+}
+```
+
+**Features:**
+
+- Single `object` property
+- `isType(type)` method to check object type
+
+**When to use:**
+
+- Displaying a single item/detail view
+- Is used within another OrbitComponent
+- No data fetching required (object is passed in as property)
+
+**Example components:** `<sample-object>`, `<user-card>`, `<some-item>`
+
+##### ComponentObjectsHandler
+
+Use for components that display **an array/collection of resources**.
+
+```typescript
+import { ComponentObjectsHandler } from "@helpers";
+
+@customElement("my-list")
+export class MyList extends ComponentObjectsHandler {
+  @property({ attribute: false })
+  objects?: Resource[] = [];
+
+  render() {
+    return html`<ul>
+      ${this.objects?.map((obj) => html`<li>${obj.name}</li>`)}
+    </ul>`;
+  }
+}
+```
+
+**Features:**
+
+- `objects` property (array of resources)
+- `hasType(type)` method to check if any object has a specific type
+
+**When to use:**
+
+- Displaying a list/grid of items
+- Is used within another OrbitComponent
+- No data fetching required (objects are passed in as property)
+
+**Example components:** `<sample-objects>`, `<card-grid>`, `<item-list>`
+
+##### OrbitComponent
+
+Use for components that need **Orbit integration and data fetching**. Extends `ComponentObjectsHandler` with full Orbit features.
+
+```typescript
+import * as utils from "@helpers";
+
+@customElement("my-component")
+export class MyComponent extends utils.OrbitComponent {
+  // Required: define expected properties
+  cherryPickedProperties: PropertiesPicker[] = [
+    { key: "name", value: "name" },
+  ];
+
+  // Optional: setup cache invalidation
+  async _afterAttach() {
+    super._afterAttach();
+    utils.setupCacheInvalidation(this, {
+      keywords: ["some-keyword"],
+    });
+
+    // Get references to other Orbit components
+    this.someComponent = this.orbit?.getComponent("some-component");
+    // Can then be accessed with this.someComponent.instance
+
+    return Promise.resolve();
+  }
+
+  // Optional: transform responses, supports nested cherry-picking
+  async _responseAdaptator(response: Resource): Promise<Resource> {
+    if (response?._originalResource?.hasType("some:Type")) {
+      response.nestedObjects = await Promise.all(
+        (await response._originalResource["ldp:contains"]).map((item) => {
+          return this._getProxyValue(item["@id"], false, [
+            { key: "name", value: "name" },
+            { key: "updated_at", value: "updated_at", cast: formatDate },
+            { key: "items", value: "items", expand: true, cast: (arr) => sort(arr, "name") },
+          ]);
+        }),
+      );
+    }
+    return Promise.resolve(response);
+  }
+
+  // Use Lit Task for async data fetching with error handling
+  _getResource = new Task(this, {
+    task: async ([dataSrc, objSrc]) => {
+      // Check gatekeeper conditions
+      if (
+        !dataSrc ||
+        !this.orbit ||
+        (!this.noRouter &&
+          this.route &&
+          this.currentRoute &&
+          !this.route.startsWith(this.currentRoute))
+      )
+        return;
+
+      // Wait for dependent components
+      if (!this.someComponent.instance?.ready) {
+        await new Promise((resolve) => {
+          this.someComponent.instance?.addEventListener("component-ready", () => resolve(true));
+        });
+      }
+
+      // Fetch and cache data
+      if (!this.hasCachedDatas || this.oldDataSrc !== dataSrc) {
+        if (!dataSrc) return;
+        // _getProxyValue methods takes an URL to a JSONLD or a Resource and handle conversion by itself
+        this.objects = (await this._getProxyValue(dataSrc)) as Resource[];
+        this.hasCachedDatas = true;
+      }
+
+      if (this.oldDataSrc !== dataSrc) {
+        this.oldDataSrc = dataSrc;
+      }
+
+      // Find specific object if objSrc provided
+      if (objSrc) {
+        this.object = this.objects.find((obj: Resource) => obj["@id"] === objSrc);
+      }
+
+      return sort(this.objects, "name", "asc");
+    },
+    args: () => [
+      this.defaultDataSrc,
+      this.dataSrc,
+      this.caching,
+      this.currentRoute,
+    ],
+  });
+
+  // Event handlers always prevent default
+  _handleEvent(e: Event) {
+    e.preventDefault();
+    // handler logic
+  }
+
+  // Render with gatekeeper pattern
+  render() {
+    return (
+      this.gatekeeper() ||
+      this._getResource.render({
+        pending: () => html`<solid-loader></solid-loader>`,
+        error: (e) => {
+          console.warn("[my-component] Task error:", e);
+          return nothing;
+        },
+        complete: (datas) => html`
+          <div>
+            ${this.object
+                ? html`<detail-component .object=${this.object}></detail-component>`
+                : datas
+                  ? html`<list-component .objects=${datas}></list-component>`
+                  : html`No data available`}
+          </div>
+        `,
+      })
+    );
+  }
+}
+```
+
+**Features:**
+
+- Inherits from `ComponentObjectsHandler` (has `objects` and `object` properties)
+- `cherryPickedProperties` for declarative data fetching
+- `_getProxyValue(url)` method to fetch and transform resources
+- `_responseAdaptator(response)` for custom response transformations
+- `gatekeeper()` for route-aware rendering optimization
+- `orbit` property with Orbit integration
+- `route`, `defaultDataSrc`, `dataSrc` properties for routing
+- Cache invalidation via `setupCacheInvalidation()`
+- Both `hasType()` and `isType()` methods
+
+**When to use:**
+
+- Need to fetch data from a URL (`data-src`)
+- Need caching and automatic updates
+- Need routing awareness
+- Need to interact with other Orbit components
+- Both single object and list display scenarios
+
+**Example components:** `<solid-xyz>`, `<project-list>`, `<user-profile>` (when fetching from URL)
+
+**Decision Tree:**
+
+```
+Is called from another OrbitComponent and does not fetch new data?
+  ├─ Yes ──> Display single object?
+  │          ├─ Yes ──> ComponentObjectHandler
+  │          └─ No  ──> ComponentObjectsHandler (list)
+  │
+  └─ No ──> OrbitComponent
+               (named solid-xyz, with all Orbit features)
+```
+
+**Typical Pattern:**
+
+```html
+<!-- OrbitComponent fetches data and passes to handlers -->
+<solid-awesome-component data-src="https://localhost:8000/datas">
+  <!-- Renders either detail or list view -->
+</solid-awesome-component>
+
+<!-- Inside awesome-component render -->
+<my-list .objects=${datas} @clicked=${this._openModal}></my-list>
+<my-detail .object=${this.object} @close=${this._closeModal}></my-detail>
+```
+
+#### Style Import
+
+Import SCSS files inline using `?inline` query parameter:
+
+```typescript
+import ComponentStyle from "@styles/component.scss?inline";
+
+static styles = css`
+  ${unsafeCSS(ComponentStyle)}
+`;
+```
+
+Alternatively, use inline CSS directly:
+
+```typescript
+static styles = css`
+  .modal {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background-color: rgba(0, 2, 49, 0.2);
+    z-index: 9999;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+  }
+`;
+```
+
+### Helper Functions
+
+- `utils.sort(arr, key, order)` - Sort arrays (supports nested keys, numbers, strings, dates)
+- `utils.formatDate(date)` - Format dates using Intl
+- `utils.filterGenerator` - Create filter functions
+- `utils.uniq()` - Generate unique IDs
+- `utils.requestNavigation(route, resource)` - Navigation wrapper
+- `utils.setupCacheInvalidation(component, { keywords })` - Setup cache invalidation on save events
+
+### Navigation Patterns
+
+Use `requestNavigation` for programmatic navigation:
+
+```typescript
+// Navigate to route with a resource ID
+requestNavigation(this.route, resource["@id"]);
+
+// Navigate without resource
+requestNavigation(this.orbit.getComponent("another-component")?.route);
+```
+
+For route-based navigation with rdf-type matching:
+
+```typescript
+const rdfType = e.detail["@type"]?.at(-1) ?? e.detail["@type"];
+if (rdfType) {
+  const compatibleComponents = window.orbit?.components?.filter(
+    (c) => c?.routeAttributes?.["rdf-type"] === rdfType,
+  );
+  if (compatibleComponents?.[0]?.route) {
+    requestNavigation(compatibleComponents[0]?.route, e.detail["@id"]);
+  }
+}
+```
+
+### Conditional Attributes
+
+Use `nothing` for conditional attributes (e.g., to avoid `disabled="false"`):
+
+```typescript
+<some-button
+  type="primary"
+  disabled=${!this.someOtherComponent?.route || nothing}
+  label=${msg("Create new")}
+></some-button>
+```
+
+This pattern prevents invalid HTML like `disabled="false"`.
+
+### i18n
+
+Use `msg()` from `@lit/localize` for static strings:
+
+```typescript
+import { msg, str } from "@lit/localize";
+
+@localized()
+export class MyComponent extends LitElement {
+  render() {
+    return html`<button label=${msg("Click me")}></button>`;
+  }
+}
+```
+
+Use `str()` for strings with embedded variables:
+
+```typescript
+return html`${msg(str`Hello ${this.name}`)}`;
+```
+
+Add `@localized()` decorator when using `msg()` or `str()` to ensure reactivity.
+
+### Cherry-Picked Properties Pattern
+
+Define expected resource properties:
+
+```typescript
+cherryPickedProperties: PropertiesPicker[] = [
+  { key: "name", value: "name" }, // Simple property
+  { key: "project", value: "projectId", cast: (r) => r["@id"] }, // Cast value
+  { key: "project", value: "project", expand: true }, // Expand nested object
+];
+```
+
+Advanced pattern with helper functions in cast:
+
+```typescript
+cherryPickedProperties: PropertiesPicker[] = [
+  { key: "created_at", value: "created_at", cast: formatDate },
+  { key: "updated_at", value: "updated_at", cast: formatDate },
+  { key: "name", value: "name" },
+  {
+    key: "categories",
+    value: "categories",
+    expand: true,
+    cast: (c: Resource[]) => sort(c, "name"),
+  },
+];
+```
+
+### Error Handling
+
+- Try-catch in async methods, log errors in dev mode only:
+
+```typescript
+try {
+  // code
+} catch (e) {
+  if (import.meta.env.DEV) console.error(e);
+}
+```
+
+### File Structure
+
+- `src/components/` - Web component implementations
+- `src/helpers/` - Utility functions and base classes
+- `src/styles/` - SCSS stylesheets
+- `src/mocks/` - Mock data for testing
+- `cypress/component/` - Component tests (.cy.ts files)
+- `stories/` - Storybook stories (.stories.ts files)
+
+### Orbit Integration
+
+- Import `@src/initializer` before `@customElement` decorator if component will be used in Orbit
+- Use `gatekeeper()` method to prevent unnecessary renders
+- Check `this.orbit` exists before using Orbit features
+- Get references to other Orbit components via `this.orbit?.getComponent("component-name")`
+- Wait for component readiness using `addEventListener` on component's ready event:
+
+```typescript
+if (!this.someComponent.ready) {
+  await new Promise((resolve) => {
+    this.someComponent.addEventListener("ready", () => resolve(true));
+  });
+}
+```
+
+### Testing
+
+- Tests use Cypress with `cypress-ct-lit` framework
+- Import `/src/index.ts` in `cypress/support/component.ts`
+- Use `cy.mount(html\`<component-name></component-name>\`)` pattern
+- Test files named `*.cy.ts` in `cypress/component/`
+
+### Commit Messages
+
+Follow conventional commits pattern seen in repo:
+
+- `major:` - Breaking changes
+- `minor:` - New features, non-breaking changes
+- `fix:` - Bug fixes
+- `chore:` - Maintenance tasks
+
+### Important Notes
+
+- This is a **library**, not an app - no default index.html
+- Use Storybook for development, not a dev server with HTML files
+- Always run linting (`npx biome check . --write`) before committing
+- Build fails without locale build - ensure localization is extracted and built for production
+- Avoid blind copy-paste from boilerplate - understand each file's purpose

package/README.md

@@ -1,5 +1,7 @@
 # Startin'blox components repository boilerplate
 
+See [Creating a New Component Repository](#creating-a-new-component-repository) to quick-start a new component repository from this boilerplate.
+
 ## Introduction
 
 This repository provides a boilerplate for developing Startin'blox web components. It streamlines the creation and deployment of web components, whether used standalone or integrated within the Startin'blox ecosystem (Lit, Startin'blox Core, Store, Router, and Orbit). The primary objective is to enable developers to concentrate on web component logic by abstracting common complexities and providing essential functionalities out-of-the-box.
@@ -75,38 +77,29 @@ For production usage, components can be served via a CDN like JSDelivr or self-h
 
 To initialize a new component repository from this boilerplate:
 
-1. **Clone this repository:**
+1. **Create a new repository:**
+    Create a new repository on [git.startinblox.com/components](https://git.startinblox.com/components/).
+
+2. **Clone this repository:**
 
     ```bash
     git clone https://git.startinblox.com/components/solid-boilerplate.git your-new-component-name
     cd your-new-component-name
     ```
 
-2. **Rename the `origin` remote to `upstream`:**
+3. **Execute the initialization script:**
 
     ```bash
-    git remote rename origin upstream
+    npm install
+    npm run init
     ```
 
-3. **Update project details:**
-    Modify the `name`, `description`, and `repository.url` fields in [`package.json`](package.json) to reflect your new component.
-
-4. **Initial commit:**
-    Commit the changes with a `major: Initial commit` message.
-
-5. **Create a new repository:**
-    Create a new repository on [git.startinblox.com/components](https://git.startinblox.com/components/).
+4. **Follow pose-initialization script instructions**
 
-6. **Add the new repository as the `origin` remote:**
-
-    ```bash
-    git remote add origin https://git.startinblox.com/components/your-component-name.git
-    ```
-
-7. **Configure Gitlab settings:**
+5. **Configure Gitlab settings:**
     Set up branch protection rules, enforce FF merge only, and configure cloning instead of fetching in your new repository's Gitlab settings.
 
-8. **Push to `origin master`:**
+6. **Push to `origin master`:**
 
     ```bash
     git push -u origin master
@@ -188,6 +181,10 @@ async _afterAttach() {
 * `_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.
 
+**Events:**
+
+* `component-ready`: Dispatched after the component is attached to the DOM and fully initialized. The event detail includes the component configuration.
+
 `OrbitComponent` inherits methods from `ObjectsHandler`.
 
 ### `ObjectsHandler` methods

package/biome.json

@@ -1,6 +1,6 @@
 {
   "root": false,
-  "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.14/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",