@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/templates/scenario_editor/src/App.test.tsx.liquid

@@ -0,0 +1,30 @@
+{% raw %}import { renderSettingsEditor } from '@seriousgaming/sdk/ui/testing';
+import { screen, fireEvent } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+
+import { defaultSettings } from '../defaults';
+import './i18n';
+import App from './App';
+
+// renderSettingsEditor supplies the SDK context providers App needs, in place
+// of the iframe channel the real screen uses: no mocking needed.
+const renderApp = () => renderSettingsEditor(<App />, { settings: defaultSettings });
+
+describe('App', () => {
+    it('renders the welcome message', () => {
+        renderApp();
+        expect(screen.getByText(/welcome/i)).toBeInTheDocument();
+    });
+
+    it('increments the counter on button click', () => {
+        renderApp();
+
+        expect(screen.getByText(/current value: 0/i)).toBeInTheDocument();
+
+        // The counter uses local state, so fireEvent.click is appropriate here.
+        // For controlled inputs that call updateSettings, use fireEvent.change.
+        fireEvent.click(screen.getByRole('button', { name: /increment/i }));
+
+        expect(screen.getByText(/current value: 1/i)).toBeInTheDocument();
+    });
+});{% endraw %}

package/dist/templates/scenario_editor/src/App.tsx.liquid

@@ -0,0 +1,95 @@
+import { Box, Button, CssBaseline, GlobalStyles, ThemeProvider, Typography } from '@mui/material';
+import { useSettingsEditor } from '@seriousgaming/sdk/ui';
+import React, { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { Settings } from '../types';
+import { useAppTheme } from './theme';
+
+/*
+This UI requires the following dependencies:
+- @mui/material
+- @emotion/react
+- @emotion/styled
+- stylis
+- @mui/stylis-plugin-rtl
+- @fontsource-variable/roboto-mono
+- @fontsource-variable/work-sans
+- i18next
+- react-i18next
+
+Make sure to install them in your project, e.g.:
+pnpm add @mui/material @emotion/react @emotion/styled stylis @mui/stylis-plugin-rtl @fontsource-variable/roboto-mono @fontsource-variable/work-sans i18next react-i18next
+*/
+
+/*
+This is the game's scenario editor: where a facilitator or author builds a new
+scenario for the game, at any time and with no session running. The host saves
+what it edits as a scenario; the screen itself has no save button to provide.
+It includes an example counter that uses local component state. To connect it
+to the game's settings:
+
+1. In scenario_editor/scenario_editor.sdk.json, list the settings resources
+   this screen edits in `configures`, e.g. "configures": ["demand"]. The
+   settings it reads and writes are keyed by those identifiers.
+
+2. In this file (App.tsx), uncomment the lines related to `useSettingsEditor`.
+*/
+
+/**
+ * This surface is embedded in the host's page, so it leaves the ground to the
+ * host: a surface painting its own background reads as a panel bolted on rather
+ * than part of the page, and never quite matches. Paint cards and panels, which
+ * are meant to look raised, not the page.
+ */
+const TRANSPARENT_BODY = { body: { backgroundColor: 'transparent' } };
+
+function App() {
+    // const { settings, updateSettings } = useSettingsEditor<Settings>();
+    const { t } = useTranslation();
+    const theme = useAppTheme();
+    const [localCounter, setLocalCounter] = useState(0);
+
+    // This is a local state example.
+    // To connect to the settings, comment out the local state above and
+    // uncomment the `useSettingsEditor` hook and the `counterValue` line below.
+    const counterValue = localCounter;
+    // const counterValue = settings.demand?.someField;
+
+    const handleIncrement = () => {
+        // This is a local state update example.
+        setLocalCounter((c) => c + 1);
+
+        // To change a setting, uncomment the `updateSettings` call below. Only
+        // what changed reaches the host.
+        // void updateSettings({
+        //     demand: {
+        //         ...settings.demand,
+        //         someField: (settings.demand?.someField ?? 0) + 1,
+        //     },
+        // });
+    };
+
+    return (
+        <ThemeProvider theme={theme}>
+            <CssBaseline enableColorScheme />
+            <GlobalStyles styles={TRANSPARENT_BODY} />
+            <Box>
+                <Typography variant="body1">{t('welcomeMessage')}</Typography>
+                <Typography variant="body2" color="text.secondary">
+                    {t('dataExample')}
+                </Typography>
+                <Typography variant="h6" component="p">
+                    {t('currentValue', { value: counterValue })}
+                </Typography>
+                <Box>
+                    <Button variant="contained" onClick={handleIncrement}>
+                        {t('updateButton')}
+                    </Button>
+                </Box>
+            </Box>
+        </ThemeProvider>
+    );
+}
+
+export default App;

package/dist/templates/scenario_editor/src/i18n.ts.liquid

@@ -0,0 +1,44 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+// Translation resources
+const resources = {
+    en: {
+        translation: {
+            greeting: 'Hello, World!',
+            welcomeMessage: 'Welcome to the scenario editor for this game.',
+            dataExample: 'Choose the settings this scenario plays with.',
+            currentValue: 'Current value: {% raw %}{{value}}{% endraw %}',
+            updateButton: 'Increment Value',
+        },
+    },
+    it: {
+        translation: {
+            greeting: 'Ciao, mondo!',
+            welcomeMessage: 'Benvenuto nell\'editor di scenari di questo gioco.',
+            dataExample: 'Scegli le impostazioni di questo scenario.',
+            currentValue: 'Valore corrente: {% raw %}{{value}}{% endraw %}',
+            updateButton: 'Incrementa valore',
+        },
+    },
+    ar: {
+        translation: {
+            greeting: 'أهلاً بالعالم!',
+            welcomeMessage: 'مرحبًا بك في محرر السيناريوهات لهذه اللعبة.',
+            dataExample: 'اختر إعدادات هذا السيناريو.',
+            currentValue: 'القيمة الحالية: {% raw %}{{value}}{% endraw %}',
+            updateButton: 'زيادة القيمة',
+        },
+    },
+};
+
+i18n.use(initReactI18next).init({
+    resources,
+    lng: 'en', // default language
+    fallbackLng: 'en',
+    interpolation: {
+        escapeValue: false, // React already escapes
+    },
+});
+
+export default i18n;

package/dist/templates/session/src/App.test.tsx.liquid

@@ -0,0 +1,60 @@
+{% raw %}import {
+    createMockSharedState,
+    createMockTeamState,
+    renderSessionUserInterface,
+} from '@seriousgaming/sdk/ui/testing';
+import { fireEvent, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { SessionData, SharedContext, TeamContext } from '../types';
+import './i18n';
+import App from './App';
+
+const mockTimer = {
+    enabled: false,
+    paused: false,
+    nextTickAt: null,
+    intervalMs: null,
+    pausedAt: null,
+    pausedMs: 0,
+    scheduleStartedAt: null,
+    extendedMs: 0,
+};
+
+const teams = [
+    { teamId: 'team-1', index: 0, name: 'Team 1' },
+    { teamId: 'team-2', index: 1, name: 'Team 2' },
+];
+
+// `createMockTeamState` and `createMockSharedState` fill in the fields a test
+// rarely cares about, `revision` included. Typed with the generated contexts,
+// a team fixture can hold only that team's own capabilities: one carrying a
+// shared capability fails to compile, as the surface would never see it there.
+const sessionData: SessionData = {
+    shared: createMockSharedState<SharedContext>(),
+    teams: {
+        'team-1': createMockTeamState<TeamContext>({ completedTicks: 3, timer: mockTimer }),
+        'team-2': createMockTeamState<TeamContext>({ completedTicks: 5, timer: mockTimer }),
+    },
+};
+
+describe('App', () => {
+    it('lists every team with its tick', () => {
+        renderSessionUserInterface<SessionData>(<App />, { sessionData, teams });
+        expect(screen.getByText('Team 1')).toBeInTheDocument();
+        expect(screen.getByText('Team 2')).toBeInTheDocument();
+        expect(screen.getByText('3')).toBeInTheDocument();
+        expect(screen.getByText('5')).toBeInTheDocument();
+    });
+
+    it('drives the whole session with the control buttons', () => {
+        const callbacks = { requestTick: vi.fn(), undoTick: vi.fn(), resetGame: vi.fn() };
+        renderSessionUserInterface<SessionData>(<App />, { sessionData, teams, callbacks });
+        fireEvent.click(screen.getByRole('button', { name: /next tick/i }));
+        fireEvent.click(screen.getByRole('button', { name: /undo/i }));
+        fireEvent.click(screen.getByRole('button', { name: /reset/i }));
+        expect(callbacks.requestTick).toHaveBeenCalled();
+        expect(callbacks.undoTick).toHaveBeenCalled();
+        expect(callbacks.resetGame).toHaveBeenCalled();
+    });
+});{% endraw %}

package/dist/templates/session/src/App.tsx.liquid

@@ -0,0 +1,128 @@
+{% raw %}import {
+    useSessionUserInterfaceCallbacks,
+    useSessionUserInterfaceData,
+    useSessionUserInterfaceTeams,
+    type TeamInfo,
+} from '@seriousgaming/sdk/ui';
+import {
+    Box,
+    Button,
+    Card,
+    Chip,
+    CssBaseline,
+    GlobalStyles,
+    Stack,
+    Table,
+    TableBody,
+    TableCell,
+    TableHead,
+    TableRow,
+    ThemeProvider,
+    Typography,
+} from '@mui/material';
+import { useTranslation } from 'react-i18next';
+
+import type { Settings, SessionData, SharedWrites, TeamWrites } from '../types';
+import { useAppTheme } from './theme';
+
+// Requires the dependencies that `package new` installs (@mui/material, i18next,
+// and friends). See the user-interfaces guide if any are missing.
+
+// Manage-session user interfaces run in the facilitator view and see every
+// team in the session. Declare the capabilities to read in this UI's `reads`
+// array and run `pnpm run sdk generate`: the generated `SessionData` then types
+// `sessionData.teams[teamId].context` with each team's own capabilities, and
+// `sessionData.shared.context` with the shared ones, which arrive once for the
+// session rather than inside every team. `SharedWrites` and `TeamWrites` type
+// the two forms of `setData` against what this UI declares in `writes`.
+
+/**
+ * This surface is embedded in the host's page, so it leaves the ground to the
+ * host: a surface painting its own background reads as a panel bolted on rather
+ * than part of the page, and never quite matches. Paint cards and panels, which
+ * are meant to look raised, not the page.
+ */
+const TRANSPARENT_BODY = { body: { backgroundColor: 'transparent' } };
+
+function App() {
+    const { sessionData } = useSessionUserInterfaceData<
+        SessionData,
+        Settings,
+        SharedWrites,
+        TeamWrites
+    >();
+    const teams = useSessionUserInterfaceTeams();
+    const { requestTick, undoTick, resetGame } = useSessionUserInterfaceCallbacks();
+    const { t } = useTranslation();
+    const theme = useAppTheme();
+
+    return (
+        <ThemeProvider theme={theme}>
+            <CssBaseline enableColorScheme />
+            <GlobalStyles styles={TRANSPARENT_BODY} />
+            <Box
+                sx={{
+                    minHeight: '100vh',
+                    '@supports (height: 100dvh)': {
+                        minHeight: '100dvh',
+                    },
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    p: 2,
+                }}
+            >
+                <Card
+                    variant="outlined"
+                    sx={{ width: '100%', maxWidth: 560, p: 4, textAlign: 'center' }}
+                >
+                    <Typography variant="h5" component="h1" gutterBottom>
+                        {t('title')}
+                    </Typography>
+                    <Chip label={t('role')} color="info" size="small" sx={{ mb: 2 }} />
+                    <Table size="small" sx={{ mb: 3 }}>
+                        <TableHead>
+                            <TableRow>
+                                <TableCell>{t('teamHeader')}</TableCell>
+                                <TableCell align="right">{t('tickHeader')}</TableCell>
+                            </TableRow>
+                        </TableHead>
+                        <TableBody>
+                            {teams.length === 0 ? (
+                                <TableRow>
+                                    <TableCell colSpan={2} sx={{ color: 'text.secondary' }}>
+                                        {t('noTeams')}
+                                    </TableCell>
+                                </TableRow>
+                            ) : (
+                                teams.map((team: TeamInfo) => (
+                                    <TableRow key={team.teamId}>
+                                        <TableCell component="th" scope="row">
+                                            {team.name}
+                                        </TableCell>
+                                        <TableCell align="right">
+                                            {sessionData.teams[team.teamId]?.completedTicks ?? '—'}
+                                        </TableCell>
+                                    </TableRow>
+                                ))
+                            )}
+                        </TableBody>
+                    </Table>
+                    <Stack direction="row" spacing={1} sx={{ justifyContent: 'center' }}>
+                        <Button variant="contained" onClick={() => requestTick()}>
+                            {t('nextTickAll')}
+                        </Button>
+                        <Button variant="outlined" onClick={() => undoTick()}>
+                            {t('undoAll')}
+                        </Button>
+                        <Button variant="outlined" color="error" onClick={() => resetGame()}>
+                            {t('resetAll')}
+                        </Button>
+                    </Stack>
+                </Card>
+            </Box>
+        </ThemeProvider>
+    );
+}
+
+export default App;{% endraw %}

package/dist/templates/session/src/i18n.ts.liquid

@@ -0,0 +1,53 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+// Translation resources
+const resources = {
+    en: {
+        translation: {
+            title: '{{ name }}',
+            role: 'Facilitator · session',
+            teamHeader: 'Team',
+            tickHeader: 'Tick',
+            noTeams: 'No teams yet. Start the game to see team data.',
+            nextTickAll: 'Next tick (all)',
+            undoAll: 'Undo (all)',
+            resetAll: 'Reset (all)',
+        },
+    },
+    it: {
+        translation: {
+            title: '{{ name }}',
+            role: 'Facilitatore · sessione',
+            teamHeader: 'Squadra',
+            tickHeader: 'Tick',
+            noTeams: 'Nessuna squadra. Avvia la partita per vedere i dati delle squadre.',
+            nextTickAll: 'Prossimo tick (tutte)',
+            undoAll: 'Annulla (tutte)',
+            resetAll: 'Reimposta (tutte)',
+        },
+    },
+    ar: {
+        translation: {
+            title: '{{ name }}',
+            role: 'الميسّر · الجلسة',
+            teamHeader: 'الفريق',
+            tickHeader: 'الدورة',
+            noTeams: 'لا توجد فرق بعد. ابدأ اللعبة لرؤية بيانات الفرق.',
+            nextTickAll: 'الدورة التالية (الكل)',
+            undoAll: 'تراجع (الكل)',
+            resetAll: 'إعادة تعيين (الكل)',
+        },
+    },
+};
+
+i18n.use(initReactI18next).init({
+    resources,
+    lng: 'en', // default language
+    fallbackLng: 'en',
+    interpolation: {
+        escapeValue: false, // React already escapes
+    },
+});
+
+export default i18n;

package/dist/templates/session/src/main.tsx.liquid

@@ -0,0 +1,48 @@
+import createCache from '@emotion/cache';
+import { CacheProvider } from '@emotion/react';
+import '@fontsource-variable/roboto-mono';
+import '@fontsource-variable/work-sans';
+import rtlPlugin from '@mui/stylis-plugin-rtl';
+import { SessionUserInterfaceWrapper, useSessionUserInterfaceLocale } from '@seriousgaming/sdk/ui';
+
+import './i18n';
+import i18n from 'i18next';
+import React, { StrictMode, useEffect } from 'react';
+import { createRoot } from 'react-dom/client';
+import { prefixer } from 'stylis';
+
+import App from './App';
+
+// Create RTL cache
+const cacheRtl = createCache({
+    key: 'muirtl',
+    stylisPlugins: [prefixer, rtlPlugin],
+});
+
+const cacheLtr = createCache({
+    key: 'muiltr',
+});
+
+// Wrapper component to sync locale with i18next and setup RTL
+function RootWrapper({ children }: { children: React.ReactNode }) {
+    const { locale } = useSessionUserInterfaceLocale();
+
+    useEffect(() => {
+        const i18nextLocale = locale.split('-')[0];
+        i18n.changeLanguage(i18nextLocale);
+    }, [locale]);
+
+    const isRtl = i18n.dir(locale.split('-')[0]) === 'rtl';
+
+    return <CacheProvider value={isRtl ? cacheRtl : cacheLtr}>{children}</CacheProvider>;
+}
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <SessionUserInterfaceWrapper>
+            <RootWrapper>
+                <App />
+            </RootWrapper>
+        </SessionUserInterfaceWrapper>
+    </StrictMode>
+);

package/dist/templates/session/src/theme.ts.liquid

@@ -0,0 +1,46 @@
+{% raw %}import { createTheme } from '@mui/material/styles';
+import { useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
+import { useMemo } from 'react';
+
+/**
+ * The host owns the palette, the game owns the typography and the component
+ * shapes. Reading `theme.mode` rather than the browser's preference is what
+ * keeps a participant's screen and the facilitator's looking like one product.
+ */
+export const useAppTheme = () => {
+    const theme = useSessionUserInterfaceTheme();
+
+    return useMemo(() => {
+        const colors = theme.mode === 'light' ? theme.light : theme.dark;
+        return createTheme({
+            palette: {
+                mode: theme.mode,
+                primary: { main: colors.primary, contrastText: colors.contrastText.primary },
+                secondary: { main: colors.secondary, contrastText: colors.contrastText.secondary },
+                success: { main: colors.success, contrastText: colors.contrastText.success },
+                error: { main: colors.error, contrastText: colors.contrastText.error },
+                warning: { main: colors.warning, contrastText: colors.contrastText.warning },
+                info: { main: colors.info, contrastText: colors.contrastText.info },
+            },
+            shape: { borderRadius: 10 },
+            components: {
+                MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
+                MuiTab: {
+                    styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
+                },
+                MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
+                MuiTableCell: {
+                    styleOverrides: {
+                        head: {
+                            fontSize: '0.75rem',
+                            fontWeight: 700,
+                            letterSpacing: '0.07em',
+                            textTransform: 'uppercase',
+                        },
+                    },
+                },
+            },
+        });
+    }, [theme]);
+};
+{% endraw %}

package/dist/templates/settings-editor/index.html.liquid

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>{{ name }}</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="./src/main.tsx"></script>
+    </body>
+</html>

package/dist/templates/settings-editor/src/main.tsx.liquid

@@ -0,0 +1,48 @@
+import createCache from '@emotion/cache';
+import { CacheProvider } from '@emotion/react';
+import '@fontsource-variable/roboto-mono';
+import '@fontsource-variable/work-sans';
+import rtlPlugin from '@mui/stylis-plugin-rtl';
+import { SettingsEditorWrapper, useSettingsEditorLocale } from '@seriousgaming/sdk/ui';
+
+import './i18n';
+import i18n from 'i18next';
+import React, { StrictMode, useEffect } from 'react';
+import { createRoot } from 'react-dom/client';
+import { prefixer } from 'stylis';
+
+import App from './App';
+
+// Create RTL cache
+const cacheRtl = createCache({
+    key: 'muirtl',
+    stylisPlugins: [prefixer, rtlPlugin],
+});
+
+const cacheLtr = createCache({
+    key: 'muiltr',
+});
+
+// Wrapper component to sync locale with i18next and setup RTL
+function RootWrapper({ children }: { children: React.ReactNode }) {
+    const { locale } = useSettingsEditorLocale();
+
+    useEffect(() => {
+        const i18nextLocale = locale.split('-')[0];
+        i18n.changeLanguage(i18nextLocale);
+    }, [locale]);
+
+    const isRtl = i18n.dir(locale.split('-')[0]) === 'rtl';
+
+    return <CacheProvider value={isRtl ? cacheRtl : cacheLtr}>{children}</CacheProvider>;
+}
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <SettingsEditorWrapper>
+            <RootWrapper>
+                <App />
+            </RootWrapper>
+        </SettingsEditorWrapper>
+    </StrictMode>
+);

package/dist/templates/settings-editor/src/theme.ts.liquid

@@ -0,0 +1,24 @@
+import { createTheme } from '@mui/material/styles';
+import { useSettingsEditorTheme } from '@seriousgaming/sdk/ui';
+import { useMemo } from 'react';
+
+export const useAppTheme = () => {
+    const theme = useSettingsEditorTheme();
+
+    const appTheme = useMemo(() => {
+        const themeColors = theme.mode === 'light' ? theme.light : theme.dark;
+        return createTheme({
+            palette: {
+                mode: theme.mode,
+                primary: { main: themeColors.primary, contrastText: themeColors.contrastText.primary },
+                secondary: { main: themeColors.secondary, contrastText: themeColors.contrastText.secondary },
+                success: { main: themeColors.success, contrastText: themeColors.contrastText.success },
+                error: { main: themeColors.error, contrastText: themeColors.contrastText.error },
+                warning: { main: themeColors.warning, contrastText: themeColors.contrastText.warning },
+                info: { main: themeColors.info, contrastText: themeColors.contrastText.info },
+            },
+        });
+    }, [theme]);
+
+    return appTheme;
+};

package/dist/templates/setup/src/App.test.tsx.liquid

@@ -0,0 +1,39 @@
+{% raw %}import { renderSettingsEditor } from '@seriousgaming/sdk/ui/testing';
+import { screen, fireEvent } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+
+import { defaultSettings } from '../defaults';
+import './i18n';
+import App from './App';
+
+// renderSettingsEditor supplies the SDK context providers App needs, in place
+// of the iframe channel the real screen uses: no mocking needed.
+const renderApp = () => renderSettingsEditor(<App />, { settings: defaultSettings });
+
+describe('App', () => {
+    it('renders the welcome message', () => {
+        renderApp();
+        expect(screen.getByText(/welcome/i)).toBeInTheDocument();
+    });
+
+    it('increments the counter on button click', () => {
+        renderApp();
+
+        expect(screen.getByText(/current value: 0/i)).toBeInTheDocument();
+
+        // The counter uses local state, so fireEvent.click is appropriate here.
+        // For controlled inputs that call updateSettings, use fireEvent.change.
+        fireEvent.click(screen.getByRole('button', { name: /increment/i }));
+
+        expect(screen.getByText(/current value: 1/i)).toBeInTheDocument();
+    });
+
+    it('asks the host to start the session', () => {
+        const requestPlay = vi.fn();
+        renderSettingsEditor(<App />, { settings: defaultSettings, callbacks: { requestPlay } });
+
+        fireEvent.click(screen.getByRole('button', { name: /start/i }));
+
+        expect(requestPlay).toHaveBeenCalledOnce();
+    });
+});{% endraw %}