@startinblox/components-ds4go 2.3.0 → 3.0.0

package/.gitlab-ci.yml

@@ -36,13 +36,19 @@ prepare:
 
 test:
   stage: test
-  image: 
-    name: cypress/included:15.9.0
+  image:
+    name: cypress/included:15.10.0
     entrypoint: [""]
   before_script:
     - npm ci --cache .npm --prefer-offline
   script:
     - npm run cy:run
+  artifacts:
+    when: on_failure
+    paths:
+      - cypress/screenshots/
+      - cypress/videos/
+    expire_in: 7 days
   except:
     - tags
   tags:

package/AGENTS.md

@@ -0,0 +1,516 @@
+# AGENTS.md
+
+This file contains guidelines for agentic coding assistants working in this repository.
+
+## 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`
+
+### 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
+
+The boilerplate this is based on 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/cypress/component/no-component-test.cy.ts

@@ -0,0 +1,9 @@
+import { html } from "lit";
+
+describe("no test", () => {
+  it("be ready for testing", () => {
+    cy.mount(html`<div></div>`);
+
+    cy.get("div").should("exist");
+  });
+});