Skip to content

Commit 4071507

Browse files
ryuwdryuwd
authored
Merge pull request #470 from aldbr/more-diracx-web-doc
docs: adapt docs with current diracx/diracx-chart documentation
2 parents 41d6d1b + 2456baf commit 4071507

17 files changed

Lines changed: 326 additions & 124 deletions

docs/admin/explanations/manage_web_release.md renamed to docs/admin/explanations/manage-web-release.md

File renamed without changes.

‎docs/admin/how-to/deploy_web_instance.md‎

Lines changed: 0 additions & 45 deletions
This file was deleted.

‎docs/dev/explanations/web-architecture.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Web Architecture
2+
3+
DiracX Web is organized as a monorepo using [npm workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces). Local packages are resolved from their workspace versions rather than the npm registry.
4+
5+
```mermaid
6+
---
7+
config:
8+
layout: elk
9+
---
10+
flowchart TD
11+
subgraph monorepo["Monorepo"]
12+
components["diracx-web-components"]
13+
web["diracx-web"]
14+
extensions["extensions (gubbins)"]
15+
end
16+
web -. uses .-> components
17+
extensions -. uses .-> components
18+
components -- published on --> npm["npm registry"]
19+
community["Community extensions"] -. uses .-> npm
20+
```
21+
22+
## Packages
23+
24+
### diracx-web-components
25+
26+
The shared component library, published to npm as `@dirac-grid/diracx-web-components`. It provides:
27+
28+
- **UI components** — Reusable React components built with [Material UI (MUI)](https://mui.com/)
29+
- **Contexts** — React context providers for state management (authentication, application list, theme)
30+
- **Hooks** — Custom React hooks encapsulating reusable logic
31+
- **Types** — TypeScript type definitions
32+
33+
Built with [tsup](https://tsup.egoist.dev/) for fast TypeScript compilation. Outputs to `dist/` with ESM and type declarations. Documented with [Storybook](https://storybook.js.org/), published at [diracgrid.github.io/diracx-web](https://diracgrid.github.io/diracx-web/). Tested with [Jest](https://jestjs.io/) + [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/).
34+
35+
### diracx-web
36+
37+
The vanilla DiracX web interface:
38+
39+
- **Framework**: [Next.js 15](https://nextjs.org/) with App Router
40+
- **Output**: Static export (`output: "export"`)
41+
- **Authentication**: [@axa-fr/react-oidc](https://github.com/AxaFrance/oidc-client)
42+
- **Testing**: [Cypress](https://www.cypress.io/) for end-to-end tests
43+
- **Serving**: Nginx in production (Docker image)
44+
45+
### extensions (gubbins)
46+
47+
Reference example of a custom DiracX web extension. Demonstrates how to extend the application list, add custom components, and deploy as a standalone project. Same Next.js setup as `diracx-web`.
48+
49+
## Key directories
50+
51+
| Path | Description |
52+
|---|---|
53+
| `packages/diracx-web-components/src/components/` | Reusable UI components |
54+
| `packages/diracx-web-components/src/contexts/` | React contexts for state management |
55+
| `packages/diracx-web-components/src/hooks/` | Custom React hooks |
56+
| `packages/diracx-web-components/src/types/` | TypeScript type definitions |
57+
| `packages/diracx-web/src/app/` | Next.js App Router pages and layouts |
58+
| `packages/extensions/src/` | Extension source (gubbins example) |
59+
60+
## Build pipeline
61+
62+
- **Component library**: `tsup` compiles TypeScript to `dist/` with ESM and type declarations.
63+
- **Next.js app**: `next build` exports static HTML/JS/CSS via `output: "export"`.
64+
- **Development**: `npm run dev` starts Next.js in dev mode. The `transpilePackages` config in `next.config.js` allows Next.js to watch and rebuild changes in `diracx-web-components` source directly — no manual rebuild needed.
65+
- **Production / extensions**: Components are consumed from the published `@dirac-grid/diracx-web-components` npm package.
66+
67+
## Routing
68+
69+
DiracX Web uses [Next.js folder-based routing](https://nextjs.org/docs/app/building-your-application/routing):
70+
71+
- `src/app/(dashboard)/` — Main dashboard (parentheses are ignored in the route, so this is the root URL).
72+
- `src/app/auth/` — Authentication pages, served at `/auth`.
73+
- `page.tsx` files define the UI for a route.
74+
- `layout.tsx` files define shared UI for a segment and its children.
75+
76+
## State management
77+
78+
- **Application state**: Managed via React Context (`ApplicationProvider`).
79+
- **Session storage**: Each application instance writes its state to `<appId>_State` for share/import functionality.
80+
- **URL encoding**: Dashboard layout is encoded in the URL for sharing.
81+
82+
## Design system
83+
84+
DiracX Web uses [Material UI (MUI)](https://mui.com/) as its design system. Components should follow MUI patterns and use the MUI theme for consistent styling.

‎docs/dev/explanations/web-testing.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Web Testing
2+
3+
DiracX Web uses a layered testing approach to ensure reliability at different levels of the application.
4+
5+
## Testing layers
6+
7+
### Component tests (Jest + React Testing Library)
8+
9+
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.
10+
11+
```bash
12+
npm run test:diracx-web-components
13+
```
14+
15+
Tests live alongside their components in `packages/diracx-web-components/test/`.
16+
17+
**When to use**: Testing component rendering, props handling, user interactions, hooks, and context behavior.
18+
19+
### End-to-end tests (Cypress)
20+
21+
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.
22+
23+
```bash
24+
export DIRACX_URL=<diracx-backend-url>
25+
npm run --prefix packages/diracx-web test
26+
```
27+
28+
Tests live in `packages/diracx-web/cypress/`.
29+
30+
**When to use**: Testing complete user flows, authentication, API integration, and cross-component interactions.
31+
32+
### Visual documentation (Storybook)
33+
34+
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.
35+
36+
```bash
37+
npm run doc:diracx-web-components
38+
```
39+
40+
Stories live in `packages/diracx-web-components/stories/`.
41+
42+
**When to use**: Documenting component variations, verifying visual appearance, and enabling manual exploratory testing.
43+
44+
## What to test at each level
45+
46+
| Level | Scope | Speed | Examples |
47+
|-------|-------|-------|----------|
48+
| Component (Jest) | Single component or hook | Fast | Button renders correctly, form validates input |
49+
| E2E (Cypress) | Full user workflow | Slow | User logs in, submits a job, views results |
50+
| Visual (Storybook) | Component appearance | Manual | Theme variations, responsive layouts |
51+
52+
## Guidelines
53+
54+
- Write component tests for all new components and hooks
55+
- Add Storybook stories for reusable UI components
56+
- Add E2E tests for critical user workflows
57+
- Use [Jest coverage reports](https://jestjs.io/docs/code-coverage) to identify untested code

docs/dev/how-to/contribute_to_web.md renamed to docs/dev/how-to/contribute-to-web.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Contributing to DiracX-Web
22

3-
*Requirements: [Setup Environment](setup_web_environment.md)*
3+
*Requirements: [Setup Environment](setup-web-environment.md)*
44

55
=== "Documentation"
66

@@ -29,7 +29,7 @@
2929
If you create an export function or component in `diracx-web-components`, you must add it to the `index.ts` file and run `npm run build` inside `packages/diracx-web-components` to ensure the pre-commit hook passes.
3030

3131
!!! warning
32-
Don't forget to update the `packages/extensions` code if you integrate breaking changes in the `diracx-web-components` library. See [Managing the extension](manage_web_extension.md) for further details.
32+
Don't forget to update the `packages/extensions` code if you integrate breaking changes in the `diracx-web-components` library. See [Managing the extension](manage-web-extension.md) for further details.
3333

3434
!!! note "Pre-commit Hooks"
3535
`Husky` is configured to run as a pre-commit script, executing tasks such as linting staged files to maintain code consistency with the codebase.

docs/dev/how-to/create_web_application.md renamed to docs/dev/how-to/create-web-application.md

File renamed without changes.

docs/dev/how-to/manage_web_extension.md renamed to docs/dev/how-to/manage-web-extension.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,12 @@ npm run --prefix packages/extensions test
8383

8484
!!! tip
8585
Like `diracx-web`, `gubbins-web` does automatically reflect changes made in `diracx-web-components`. This means that while running `gubbins` using `diracx-charts/run_demo.sh`, any modifications to `diracx-web-components` will also be applied to `gubbins`.
86+
87+
## Deploying an extension as a standalone
88+
89+
By default, the `gubbins` extension is part of a monorepo and uses a local version of `diracx-web-components`. This setup is not representative of a standalone extension configuration.
90+
91+
To deploy gubbins as a standalone package:
92+
93+
- **Isolate the `packages/extensions` directory:** Copy the content of `packages/extensions` to a new repository or directory outside the monorepo.
94+
- **Update Configuration:** Adjust relevant variables to align with a standalone setup. Review the gubbins-test GitHub Action workflow for required changes.

docs/dev/how-to/setup_web_environment.md renamed to docs/dev/how-to/setup-web-environment.md

File renamed without changes.

‎docs/dev/how-to/use-the-demo/web.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Accessing DiracX Web in the demo
2+
3+
This guide explains how to access the DiracX Web interface when running the demo environment via `run_demo.sh`.
4+
5+
## Finding the web URL
6+
7+
When you start the demo with `run_demo.sh`, the script outputs the URLs for all services. Look for the web interface URL in the output:
8+
9+
```
10+
DiracX Web is available at: https://...
11+
```
12+
13+
The URL is also available via the environment variables sourced by the demo setup.
14+
15+
## Logging in
16+
17+
1. Open the web URL in your browser.
18+
2. You will be redirected to the authentication page.
19+
3. Use the demo credentials provided in the `run_demo.sh` output to log in.
20+
4. After successful authentication, you will be redirected to the dashboard.
21+
22+
## Navigating the dashboard
23+
24+
The dashboard provides access to all available DiracX Web applications:
25+
26+
- **Job Monitor** — Search, filter, and manage jobs
27+
- **Application management** — Add, organize, and share application instances
28+
29+
Use the left sidebar to switch between applications. You can add new application instances and organize them into groups.
30+
31+
For more details on using specific features, see the [User Guide](../../../user/how-to/index.md).

‎docs/dev/reference/web-arch.md‎

Lines changed: 0 additions & 74 deletions
This file was deleted.

0 commit comments

Comments
 (0)