chore: few fixes on the documentation

Author: aldbr

docs/dev/explanations/web-architecture.md

@@ -36,7 +36,7 @@ Built with [tsup](https://tsup.egoist.dev/) for fast TypeScript compilation. Out
 
 The vanilla DiracX web interface:
 
-- **Framework**: [Next.js 15](https://nextjs.org/) with App Router
+- **Framework**: [Next.js](https://nextjs.org/) with App Router
 - **Output**: Static export (`output: "export"`)
 - **Authentication**: [@axa-fr/react-oidc](https://github.com/AxaFrance/oidc-client)
 - **Testing**: [Cypress](https://www.cypress.io/) for end-to-end tests
@@ -77,7 +77,6 @@ DiracX Web uses [Next.js folder-based routing](https://nextjs.org/docs/app/build
 
 - **Application state**: Managed via React Context (`ApplicationProvider`).
 - **Session storage**: Each application instance writes its state to `<appId>_State` for share/import functionality.
-- **URL encoding**: Dashboard layout is encoded in the URL for sharing.
 
 ## Design system
 

docs/dev/explanations/web-testing.md

@@ -1,57 +1,61 @@
 # Web Testing
 
-DiracX Web uses a layered testing approach to ensure reliability at different levels of the application.
+DiracX Web uses a layered testing strategy where each layer builds on the previous one:
+
+1. **Storybook** illustrates shared and public components that extensions can import
+2. **Jest tests** verify that those stories render correctly and stay up to date
+3. **E2E tests** ensure essential user interactions work end-to-end
 
 ## Testing layers
 
-### Component tests (Jest + React Testing Library)
+### Storybook (visual documentation and component showcase)
 
-Unit and integration tests for individual React components. These tests run in a simulated DOM environment (jsdom) and verify that components render correctly, handle user interactions, and manage state properly.
+[Storybook](https://storybook.js.org/) is the foundation of the testing strategy. Each shared or public component that extensions can import should have a corresponding story. Stories serve as living documentation, showing how components look and behave with different props, states, and edge cases.
 
 ```bash
-npm run test:diracx-web-components
+npm run doc:diracx-web-components
 ```
 
-Tests live alongside their components in `packages/diracx-web-components/test/`.
+Stories live in `packages/diracx-web-components/stories/`.
 
-**When to use**: Testing component rendering, props handling, user interactions, hooks, and context behavior.
+**What to document**: All reusable components exported by `diracx-web-components` — default states, loading/error/empty states, and key variations.
 
-### End-to-end tests (Cypress)
+### Component tests (Jest + React Testing Library)
 
-Full application tests that run in a real browser against a running DiracX backend. These tests simulate real user workflows including authentication, navigation, and data operations.
+Jest tests import and render the Storybook stories using `composeStories()` from `@storybook/react`. This ensures that the stories themselves are valid and that the components they illustrate work correctly. If a story breaks, the corresponding Jest test will catch it.
 
 ```bash
-export DIRACX_URL=<diracx-backend-url>
-npm run --prefix packages/diracx-web test
+npm run test:diracx-web-components
 ```
 
-Tests live in `packages/diracx-web/cypress/`.
+Tests live in `packages/diracx-web-components/test/`.
 
-**When to use**: Testing complete user flows, authentication, API integration, and cross-component interactions.
+**What to test**: That stories render without errors, that key elements are present in the DOM, and that basic interactions (clicks, form inputs) produce the expected results.
 
-### Visual documentation (Storybook)
+### End-to-end tests (Cypress)
 
-While not a testing tool per se, [Storybook](https://storybook.js.org/) serves as a visual verification layer. Each component story acts as a living example that can be visually inspected and interacted with.
+E2E tests run in a real browser against a running DiracX backend. They verify that essential user workflows work correctly across the full stack — authentication, navigation, data display, and user actions.
 
 ```bash
-npm run doc:diracx-web-components
+export DIRACX_URL=<diracx-backend-url>
+npm run --prefix packages/diracx-web test
 ```
 
-Stories live in `packages/diracx-web-components/stories/`.
+Tests live in `packages/diracx-web/test/e2e/`.
 
-**When to use**: Documenting component variations, verifying visual appearance, and enabling manual exploratory testing.
+**What to test**: Critical user flows such as logging in, filtering and sorting data, performing actions on jobs, and verifying that interactive features (e.g., clicking a pie chart slice updates the search bar and table) work end-to-end.
 
-## What to test at each level
+## How the layers connect
 
-| Level | Scope | Speed | Examples |
-|-------|-------|-------|----------|
-| Component (Jest) | Single component or hook | Fast | Button renders correctly, form validates input |
-| E2E (Cypress) | Full user workflow | Slow | User logs in, submits a job, views results |
-| Visual (Storybook) | Component appearance | Manual | Theme variations, responsive layouts |
+| Layer | Purpose | Speed | Depends on |
+|-------|---------|-------|------------|
+| Storybook | Document components for extension developers | Manual | Mocks only |
+| Jest | Verify stories render and behave correctly | Fast | Storybook stories |
+| Cypress | Verify essential user workflows | Slow | Running backend |
 
 ## Guidelines
 
-- Write component tests for all new components and hooks
-- Add Storybook stories for reusable UI components
-- Add E2E tests for critical user workflows
+- Add Storybook stories for all shared/public components exported by `diracx-web-components`
+- Write Jest tests that render the stories via `composeStories()` to keep stories and tests in sync
+- Add E2E tests for critical user workflows and cross-component interactions
 - Use [Jest coverage reports](https://jestjs.io/docs/code-coverage) to identify untested code

docs/dev/tutorials/web-extensions.md

@@ -121,13 +121,13 @@ You can either create a new repository or start from this one to build your Dira
    The output is set to `export` to have a static application.
    Images are left unoptimized because it's not well-supported with a static export.
 
-5. **Add the nginx config** located in the [`config/nginx`](config/nginx/) directory.
+5. **Add the nginx config** located in the [`config/nginx`](https://github.com/DIRACGrid/diracx-web/tree/main/packages/extensions/config/nginx) directory.
    This adjustment ensures that Nginx can correctly handle requests for .html files and fall back appropriately, preventing the `404: Not Found` errors encountered when accessing routes like `/auth`. (see [#57](https://github.com/DIRACGrid/diracx-web/pull/57))
 
 6. **Organize your pages** in the `src/app` app directory.
    The `<DiracXWebProviders>` context is needed by most of the components of `diracx-web-components`, so you should include it in the layouts of your application. Use `<OIDCSecure>` to require authentication on a route. You can also override some default values of certain contexts like `<ApplicationProvider>` for the application list.
    Finally, some components have some personalization options (i.e. the logo URL for the dashboard), check the [Storybook documentation](https://diracgrid.github.io/diracx-web/) to see the props of each component.
-   Check [the app directory](src/app/) in this example to have a reference.
+   Check [the app directory](https://github.com/DIRACGrid/diracx-web/tree/main/packages/extensions/src/app) in this example to have a reference.
 
 ### Architecture
 
@@ -177,12 +177,12 @@ Having a directory dedicated to your extension components will help you keep you
 
 To add new apps to your extension, you can create new components in your extension directory.
 
-[`testApp`](src/gubbins/components/TestApp/testApp.tsx) provides an example of a basic app component and the [Storybook documentation](https://diracgrid.github.io/diracx-web/) showcases all the components you can use from the library in an interactive interface.
+[`testApp`](https://github.com/DIRACGrid/diracx-web/blob/main/packages/extensions/src/gubbins/components/TestApp/testApp.tsx) provides an example of a basic app component and the [Storybook documentation](https://diracgrid.github.io/diracx-web/) showcases all the components you can use from the library in an interactive interface.
 
 It is then pretty easy to add them to DiracX Web by extending the `applicationList` (the list of apps available in DiracX-Web) from `diracx-web-components/components`.
 
 Context providers are used to manage and share global state across the application. You can use the `ApplicationProvider` from `diracx-web-components/contexts` to pass the list of applications to the components that need it.
-It is used in this example in the [(Dashboard) directory's layout.tsx](<src/app/(dashboard)/layout.tsx>) file.
+It is used in this example in the [(Dashboard) directory's layout.tsx](https://github.com/DIRACGrid/diracx-web/blob/main/packages/extensions/src/app/(dashboard)/layout.tsx) file.
 
 If you need more info on Contexts, you can check the [React documentation](https://reactjs.org/docs/context.html).
 
@@ -205,7 +205,7 @@ const newApplicationList = [...applicationList, newApp];
 <ApplicationProvider appList={newApplicationList}>...</ApplicationProvider>;
 ```
 
-In this example, the new App list is defined in a [separate file](src/gubbins/applicationList.ts)
+In this example, the new App list is defined in a [separate file](https://github.com/DIRACGrid/diracx-web/blob/main/packages/extensions/src/gubbins/applicationList.ts)
 
 Feel free to explore and adjust the code to fit your requirements.