@linagora/twake-react-new-version 0.0.0-stage → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,21 @@
1
+ ## @linagora/twake-react-new-version [1.1.1](https://github.com/linagora/twake-libs/compare/@linagora/twake-react-new-version@1.1.0...@linagora/twake-react-new-version@1.1.1) (2026-11-16)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * **twake-react-new-version:** Describe the optional illustration ([#66](https://github.com/linagora/twake-libs/issues/66)) ([08cb0ac](https://github.com/linagora/twake-libs/commit/08cb0ac0a9b43d699e9825d8452469d11f123448))
7
+
8
+ # @linagora/twake-react-new-version [1.1.0](https://github.com/linagora/twake-libs/compare/@linagora/twake-react-new-version@1.0.0...@linagora/twake-react-new-version@1.1.0) (2026-11-16)
9
+
10
+
11
+ ### Features
12
+
13
+ * **twake-react-new-version:** Illustration banner and centred text ([#65](https://github.com/linagora/twake-libs/issues/65)) ([ee83d0d](https://github.com/linagora/twake-libs/commit/ee83d0dd604a26f87cd0625927451b705acf2605))
14
+
15
+ # @linagora/twake-react-new-version 1.0.0 (2026-11-13)
16
+
17
+
18
+ ### Features
19
+
20
+ * **twake-react-new-version:** Offer a reload when a newer build is served ([b2f3f64](https://github.com/linagora/twake-libs/commit/b2f3f644536635a5b303f0e27f1f0a911336188f))
21
+ * **twake-react-new-version:** Read the build the server serves ([fb73480](https://github.com/linagora/twake-libs/commit/fb734805a670d7fd43f10e97a29895c8606f665e))
package/README.md CHANGED
@@ -1,3 +1,75 @@
1
- # Temporary Holding Version
1
+ # twake-react-new-version
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Tells the user of a Twake application that the server now serves a newer build than the one running in the tab, and offers to reload the page.
4
+
5
+ ## Requirements
6
+
7
+ You need to use Node 24+
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ npm install @linagora/twake-react-new-version
13
+ ```
14
+
15
+ `@linagora/twake-mui`, `twake-i18n`, `react` and `react-dom` are peer dependencies.
16
+
17
+ ## What the app serves
18
+
19
+ Each build has its own id (the commit in CI, for instance). The app:
20
+
21
+ - writes it in the bundle, so the running tab knows its own build;
22
+ - serves it at `/version.json` as `{ "build": "<id>" }`, with `Cache-Control: no-store`.
23
+
24
+ The id must be in the bundle, not read at runtime from a file served next to it: during a rollout a tab may get the bundle of the old server and that file from the new one, and would never be offered a reload.
25
+
26
+ ## Usage
27
+
28
+ Mount the dialog once, under the app's `I18n` and `TwakeMuiThemeProvider`:
29
+
30
+ ```tsx
31
+ import { NewVersionDialog } from '@linagora/twake-react-new-version'
32
+
33
+ const AppVersion = (): React.ReactElement => (
34
+ <NewVersionDialog running={BUILD_ID} appName="Twake Mail" />
35
+ )
36
+ ```
37
+
38
+ When a lazy chunk fails to load, the usual sign of a tab older than the served build, ask for a check at once:
39
+
40
+ ```ts
41
+ import { requestVersionCheck } from '@linagora/twake-react-new-version'
42
+
43
+ const ComposerForm = lazy(() =>
44
+ import('./ComposerForm').catch((error: unknown) => {
45
+ requestVersionCheck()
46
+ throw error
47
+ })
48
+ )
49
+ ```
50
+
51
+ ### When it checks
52
+
53
+ Every 10 minutes, when the tab gets the focus, becomes visible again or comes back online, and on `requestVersionCheck()`. One check at a time, and at most one every 30 seconds but the ones `requestVersionCheck()` asks for: a framed app gets the focus at each click of its host. Never at mount: the page just loaded is the served build. An error, the network, or an answer that is not that JSON (a dev server answers `index.html`) is no new build.
54
+
55
+ ### What the user sees
56
+
57
+ A dialog titled « What's new in <appName> », with the text « An update just arrived. Reload to get it. », centred, and « Not now » and « Reload » side by side, centred. With `image`, a banner above the title shows the illustration. « Not now », Escape or a click outside decline that build for the life of the tab: the dialog comes back only for a build not declined yet, so a rollback to a declined build is not offered again.
58
+
59
+ ### Props
60
+
61
+ - `running`: the build id of this bundle
62
+ - `appName`: the name shown in the text, such as `Twake Mail`
63
+ - `fetchServed()`: reads the served build id, `fetchServedBuild` by default
64
+ - `reload()`: `window.location.reload` by default
65
+ - `intervalMs`: time between two checks, 10 minutes by default
66
+ - `image`: URL of a decorative illustration (`alt=""`), drawn centred in a full-width banner about 130 px high at the top of the dialog, `object-fit: contain`, cut at the bottom of the banner if taller; no banner without it
67
+ - `imageBackground`: CSS colour of the banner, the theme's light primary colour by default (light and dark)
68
+
69
+ ### Texts
70
+
71
+ `en`, `fr`, `de`, `es`, `it`, `ru` and `vi`, added to the app's `I18n` under `twakeNewVersion`; English for any other language.
72
+
73
+ ### Detection alone
74
+
75
+ `fetchServedBuild(url = '/version.json')` and `isNewBuild(running, served)` are exported for an app that wants another surface than the dialog.
@@ -0,0 +1,21 @@
1
+ import React from 'react';
2
+ export interface NewVersionDialogProps {
3
+ /** The build id of this bundle, the one `/version.json` names once served */
4
+ running: string;
5
+ /** The name shown in the text, such as `Twake Mail` */
6
+ appName: string;
7
+ fetchServed?: () => Promise<string | null>;
8
+ reload?: () => void;
9
+ intervalMs?: number;
10
+ /** URL of a decorative illustration, drawn in a banner at the top */
11
+ image?: string;
12
+ /** CSS colour of the banner, the theme's light primary by default */
13
+ imageBackground?: string;
14
+ }
15
+ /**
16
+ * « New version available »: offers a reload to a tab that runs an older
17
+ * build than the served one. « Not now », Escape or a click outside decline
18
+ * that build for the life of the tab: the dialog comes back only for a build
19
+ * not declined yet. Mount it once, under the app's `I18n` and twake-mui theme
20
+ */
21
+ export declare const NewVersionDialog: ({ running, appName, fetchServed, reload, intervalMs, image, imageBackground }: NewVersionDialogProps) => React.ReactElement;
@@ -0,0 +1,125 @@
1
+ import React, { useEffect, useId, useRef, useState } from 'react';
2
+ import { Box, Button, Dialog, DialogActions, DialogContent, DialogContentText, DialogTitle } from '@linagora/twake-mui';
3
+ import { useExtendI18n, useI18n } from 'twake-i18n';
4
+ import de from './locales/de.json';
5
+ import en from './locales/en.json';
6
+ import es from './locales/es.json';
7
+ import fr from './locales/fr.json';
8
+ import it from './locales/it.json';
9
+ import ru from './locales/ru.json';
10
+ import vi from './locales/vi.json';
11
+ import { CHECK_VERSION_EVENT, fetchServedBuild, isNewBuild } from './version';
12
+ const locales = { de, en, es, fr, it, ru, vi };
13
+ const MINUTE = 60000;
14
+ const MIN_GAP_MS = 30000;
15
+ /**
16
+ * Runs `check` every `intervalMs`, and whenever the tab may have missed a
17
+ * deployment: it gets the focus, becomes visible again, comes back online, or
18
+ * the app asks for it (`requestVersionCheck`). Not at mount: the page just
19
+ * loaded is the served build. One check at a time, and at most one per
20
+ * `MIN_GAP_MS` but the ones the app asks for: a framed app gets the focus at
21
+ * each click of its host
22
+ */
23
+ const useVersionChecks = (check, intervalMs) => {
24
+ // The listeners stay in place while `check` changes with each render
25
+ const latestCheck = useRef(check);
26
+ latestCheck.current = check;
27
+ // Refs, not effect locals: the guard holds when `intervalMs` changes
28
+ const isRunning = useRef(false);
29
+ const lastRun = useRef(-Infinity);
30
+ useEffect(() => {
31
+ const run = (isAsked = false) => {
32
+ const now = Date.now();
33
+ if (isRunning.current)
34
+ return;
35
+ if (!isAsked && now - lastRun.current < MIN_GAP_MS)
36
+ return;
37
+ isRunning.current = true;
38
+ lastRun.current = now;
39
+ void latestCheck.current().finally(() => {
40
+ isRunning.current = false;
41
+ });
42
+ };
43
+ const onEvent = () => run();
44
+ const onAsked = () => run(true);
45
+ const onVisible = () => {
46
+ if (document.visibilityState === 'visible')
47
+ run();
48
+ };
49
+ const timer = window.setInterval(onEvent, intervalMs);
50
+ const events = ['focus', 'online'];
51
+ events.forEach(name => window.addEventListener(name, onEvent));
52
+ window.addEventListener(CHECK_VERSION_EVENT, onAsked);
53
+ document.addEventListener('visibilitychange', onVisible);
54
+ return () => {
55
+ window.clearInterval(timer);
56
+ events.forEach(name => window.removeEventListener(name, onEvent));
57
+ window.removeEventListener(CHECK_VERSION_EVENT, onAsked);
58
+ document.removeEventListener('visibilitychange', onVisible);
59
+ };
60
+ }, [intervalMs]);
61
+ };
62
+ /**
63
+ * Decorative banner at the top of the dialog. The small dialog of twake-mui
64
+ * pads its paper by 8 px on each side below `lg`: the banner cancels that
65
+ * margin there, to reach the edges of the paper (which clips it to its rounded
66
+ * corners). The image is taller than the banner (120%) and anchored at its top,
67
+ * so its bottom is cut. Without `background`, the tint is the light primary,
68
+ * a dimmed primary in the dark scheme where the light one glares
69
+ */
70
+ const Banner = ({ image, background }) => (React.createElement(Box, { sx: theme => ({
71
+ height: 130,
72
+ overflow: 'hidden',
73
+ display: 'flex',
74
+ justifyContent: 'center',
75
+ alignItems: 'flex-start',
76
+ [theme.breakpoints.down('lg')]: { marginInline: -1 },
77
+ backgroundColor: background ??
78
+ theme.vars?.palette.primary.light ??
79
+ theme.palette.primary.light,
80
+ ...(background === undefined &&
81
+ theme.applyStyles('dark', {
82
+ backgroundColor: theme.alpha(theme.vars?.palette.primary.main ?? theme.palette.primary.main, 0.16)
83
+ }))
84
+ }) },
85
+ React.createElement("img", { src: image, alt: "", "aria-hidden": true, style: {
86
+ height: '120%',
87
+ marginTop: 6,
88
+ flexShrink: 0,
89
+ objectFit: 'contain'
90
+ } })));
91
+ /**
92
+ * « New version available »: offers a reload to a tab that runs an older
93
+ * build than the served one. « Not now », Escape or a click outside decline
94
+ * that build for the life of the tab: the dialog comes back only for a build
95
+ * not declined yet. Mount it once, under the app's `I18n` and twake-mui theme
96
+ */
97
+ export const NewVersionDialog = ({ running, appName, fetchServed = fetchServedBuild, reload = () => window.location.reload(), intervalMs = 10 * MINUTE, image, imageBackground }) => {
98
+ const { t, lang } = useI18n();
99
+ useExtendI18n({ [lang]: locales[lang] ?? locales.en });
100
+ const titleId = useId();
101
+ const [offered, setOffered] = useState(null);
102
+ // Read only in events, never drawn: a ref, not state
103
+ const declined = useRef(new Set());
104
+ useVersionChecks(async () => {
105
+ if (offered !== null)
106
+ return;
107
+ const served = await fetchServed().catch(() => null);
108
+ if (isNewBuild(running, served) && !declined.current.has(served)) {
109
+ setOffered(served);
110
+ }
111
+ }, intervalMs);
112
+ const notNow = () => {
113
+ if (offered !== null)
114
+ declined.current.add(offered);
115
+ setOffered(null);
116
+ };
117
+ return (React.createElement(Dialog, { open: offered !== null, onClose: notNow, size: "small", "aria-labelledby": titleId, "data-testid": "new-version-dialog" },
118
+ image !== undefined && (React.createElement(Banner, { image: image, background: imageBackground })),
119
+ React.createElement(DialogTitle, { id: titleId, sx: { textAlign: 'center' } }, t('twakeNewVersion.title').replace('%{appName}', appName)),
120
+ React.createElement(DialogContent, null,
121
+ React.createElement(DialogContentText, { sx: { textAlign: 'center' } }, t('twakeNewVersion.body').replace('%{appName}', appName))),
122
+ React.createElement(DialogActions, { sx: { justifyContent: 'center' } },
123
+ React.createElement(Button, { variant: "outlined", "data-testid": "new-version-not-now", onClick: notNow }, t('twakeNewVersion.notNow')),
124
+ React.createElement(Button, { variant: "contained", color: "primary", "data-testid": "new-version-reload", onClick: reload }, t('twakeNewVersion.reload')))));
125
+ };
@@ -0,0 +1,2 @@
1
+ export { NewVersionDialog, type NewVersionDialogProps } from './NewVersionDialog';
2
+ export { CHECK_VERSION_EVENT, fetchServedBuild, isNewBuild, requestVersionCheck } from './version';
package/dist/index.js ADDED
@@ -0,0 +1,2 @@
1
+ export { NewVersionDialog } from './NewVersionDialog';
2
+ export { CHECK_VERSION_EVENT, fetchServedBuild, isNewBuild, requestVersionCheck } from './version';
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Neues in %{appName}",
4
+ "body": "Ein Update ist gerade eingetroffen. Laden Sie neu, um es zu erhalten.",
5
+ "reload": "Neu laden",
6
+ "notNow": "Nicht jetzt"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "What's new in %{appName}",
4
+ "body": "An update just arrived. Reload to get it.",
5
+ "reload": "Reload",
6
+ "notNow": "Not now"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Novedades de %{appName}",
4
+ "body": "Acaba de llegar una actualización. Recarga para obtenerla.",
5
+ "reload": "Recargar",
6
+ "notNow": "Ahora no"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Du nouveau dans %{appName}",
4
+ "body": "Une mise à jour vient d'arriver. Rechargez pour en profiter.",
5
+ "reload": "Recharger",
6
+ "notNow": "Pas maintenant"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Novità di %{appName}",
4
+ "body": "È appena arrivato un aggiornamento. Ricarica per ottenerlo.",
5
+ "reload": "Ricarica",
6
+ "notNow": "Non ora"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Что нового в %{appName}",
4
+ "body": "Только что вышло обновление. Перезагрузите, чтобы получить его.",
5
+ "reload": "Перезагрузить",
6
+ "notNow": "Не сейчас"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Có gì mới trong %{appName}",
4
+ "body": "Vừa có bản cập nhật. Tải lại để nhận.",
5
+ "reload": "Tải lại",
6
+ "notNow": "Để sau"
7
+ }
8
+ }
@@ -0,0 +1,15 @@
1
+ /** The window event that asks the dialog to check the served build at once */
2
+ export declare const CHECK_VERSION_EVENT = "twake:check-version";
3
+ /**
4
+ * Asks for a check now: call it when a lazy chunk fails to load, the usual
5
+ * sign of a tab running an older build than the served one
6
+ */
7
+ export declare const requestVersionCheck: () => void;
8
+ /**
9
+ * The id of the build the server serves now, read in `{ "build": "…" }`.
10
+ * Null when it cannot tell: an error, the network, or a page that is not that
11
+ * JSON (a dev server answers index.html for any path)
12
+ */
13
+ export declare const fetchServedBuild: (url?: string, fetchFn?: typeof fetch) => Promise<string | null>;
14
+ /** True when the server serves a build other than the one running here */
15
+ export declare const isNewBuild: (running: string, served: string | null) => served is string;
@@ -0,0 +1,29 @@
1
+ /** The window event that asks the dialog to check the served build at once */
2
+ export const CHECK_VERSION_EVENT = 'twake:check-version';
3
+ /**
4
+ * Asks for a check now: call it when a lazy chunk fails to load, the usual
5
+ * sign of a tab running an older build than the served one
6
+ */
7
+ export const requestVersionCheck = () => {
8
+ window.dispatchEvent(new Event(CHECK_VERSION_EVENT));
9
+ };
10
+ /**
11
+ * The id of the build the server serves now, read in `{ "build": "…" }`.
12
+ * Null when it cannot tell: an error, the network, or a page that is not that
13
+ * JSON (a dev server answers index.html for any path)
14
+ */
15
+ export const fetchServedBuild = async (url = '/version.json', fetchFn = fetch) => {
16
+ try {
17
+ const response = await fetchFn(url, { cache: 'no-store' });
18
+ if (!response.ok)
19
+ return null;
20
+ const body = await response.json();
21
+ const build = body?.build;
22
+ return typeof build === 'string' && build !== '' ? build : null;
23
+ }
24
+ catch {
25
+ return null;
26
+ }
27
+ };
28
+ /** True when the server serves a build other than the one running here */
29
+ export const isNewBuild = (running, served) => served !== null && served !== '' && served !== running;
package/package.json CHANGED
@@ -1,6 +1,64 @@
1
1
  {
2
2
  "name": "@linagora/twake-react-new-version",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "type": "module",
4
+ "version": "1.1.1",
5
+ "description": "Tells the user of a Twake application that a new version is served, and offers a reload in a dialog with an optional illustration",
6
+ "author": "Twake",
7
+ "license": "MIT",
8
+ "engines": {
9
+ "node": "24.x"
10
+ },
11
+ "repository": {
12
+ "type": "git",
13
+ "url": "https://github.com/linagora/twake-libs.git",
14
+ "directory": "packages/twake-react-new-version"
15
+ },
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js",
20
+ "default": "./dist/index.js"
21
+ }
22
+ },
23
+ "main": "dist/index.js",
24
+ "types": "dist/index.d.ts",
25
+ "files": [
26
+ "dist",
27
+ "CHANGELOG.md",
28
+ "README.md"
29
+ ],
30
+ "publishConfig": {
31
+ "access": "public"
32
+ },
33
+ "scripts": {
34
+ "build": "tsc -b tsconfig.build.json",
35
+ "start": "tsc -b tsconfig.build.json --watch",
36
+ "test": "vitest run",
37
+ "clean": "rm -rf dist"
38
+ },
39
+ "peerDependencies": {
40
+ "@linagora/twake-mui": ">=10.0.0",
41
+ "react": "^18 || ^19",
42
+ "react-dom": "^18 || ^19",
43
+ "twake-i18n": ">=0.6.0"
44
+ },
45
+ "devDependencies": {
46
+ "@emotion/react": "^11.14.0",
47
+ "@emotion/styled": "^11.14.0",
48
+ "@linagora/twake-icons": "^2.13.0",
49
+ "@linagora/twake-mui": "^10.3.0",
50
+ "@mui/lab": "^9.0.0-beta.6",
51
+ "@mui/material": "^9.4.0",
52
+ "@testing-library/jest-dom": "^6.6.3",
53
+ "@testing-library/react": "^16.3.0",
54
+ "@testing-library/user-event": "^14.6.1",
55
+ "@types/react": "^18.3.0",
56
+ "@types/react-dom": "^18.3.0",
57
+ "cozy-tsconfig": "^2.0.0",
58
+ "jsdom": "^26.1.0",
59
+ "react": "^18.3.0",
60
+ "react-dom": "^18.3.0",
61
+ "twake-i18n": "^0.6.0",
62
+ "vitest": "5.0.1"
63
+ }
64
+ }