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

package/dist/templates/starter-game/waiting_room/src/App.test.tsx

@@ -0,0 +1,102 @@
+import { MutationError } from '@seriousgaming/sdk/ui';
+import {
+    createMockParticipant,
+    createMockParticipants,
+    renderUserInterface,
+} from '@seriousgaming/sdk/ui/testing';
+import { fireEvent, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Context, Settings } from '../types';
+import App from './App';
+import './i18n';
+
+const baseContext: Context = {
+    roles: { LooksAfter: {} },
+    briefing: { Message: '' },
+};
+
+const settings: Settings = {
+    menu: {
+        Capacity: 120,
+        Menu: {
+            lemonade: { Name: 'Lemonade', Order: 1, Cost: 15, Price: 50 },
+            icedtea: { Name: 'Iced tea', Order: 2, Cost: 20, Price: 60 },
+        },
+    },
+};
+
+const ada = createMockParticipant({ id: 'participant-1', name: 'Ada' });
+
+const render = (options: Parameters<typeof renderUserInterface>[1] = {}) =>
+    renderUserInterface(<App />, { data: baseContext, settings, participant: ada, ...options });
+
+describe('before the session starts', () => {
+    it('says so, rather than showing an empty stall', () => {
+        render({ completedTicks: 0 });
+
+        expect(screen.getByText('Nearly opening time')).toBeInTheDocument();
+    });
+
+    it('lists the team, marking the reader', () => {
+        render({
+            participants: createMockParticipants(2),
+            participant: createMockParticipant({ id: '1', index: 0 }),
+        });
+
+        expect(screen.getByText(/\(you\)/)).toBeInTheDocument();
+    });
+
+    // The hook stores the item's id; the roster shows its name, so nobody has
+    // to know that 'icedtea' means Iced tea.
+    it('shows what the hook put each arrival in charge of', () => {
+        render({
+            data: { ...baseContext, roles: { LooksAfter: { '1': 'icedtea' } } },
+            participants: createMockParticipants(1),
+            participant: createMockParticipant({ id: '1', index: 0 }),
+        });
+
+        expect(screen.getByText('Iced tea')).toBeInTheDocument();
+    });
+});
+
+describe('when the facilitator parks a live session', () => {
+    // The room can be opened at any point, and the two cases need different
+    // words: 'almost ready' is wrong on round five.
+    it('says the session is paused rather than not started', () => {
+        render({ completedTicks: 4 });
+
+        expect(screen.getByText('Closed for a moment')).toBeInTheDocument();
+    });
+
+    it('carries the briefing through', () => {
+        render({ data: { ...baseContext, briefing: { Message: 'Back in five minutes' } } });
+
+        expect(screen.getByText('Back in five minutes')).toBeInTheDocument();
+    });
+});
+
+describe('naming the stall', () => {
+    it('asks the host, which owns the name', async () => {
+        const renameOwnTeam = vi.fn().mockResolvedValue(undefined);
+        render({ callbacks: { renameOwnTeam } });
+
+        fireEvent.change(screen.getByLabelText('Stall name'), { target: { value: 'Bluebird' } });
+        fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+
+        await waitFor(() => expect(renameOwnTeam).toHaveBeenCalledWith('Bluebird'));
+    });
+
+    it('shows the host’s own reason when a name is refused', async () => {
+        const renameOwnTeam = vi
+            .fn()
+            .mockRejectedValue(
+                new MutationError({ kind: 'denied', message: 'A stall name cannot be blank.' })
+            );
+        render({ callbacks: { renameOwnTeam } });
+
+        fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+
+        expect(await screen.findByText('A stall name cannot be blank.')).toBeInTheDocument();
+    });
+});

package/dist/templates/starter-game/waiting_room/src/App.tsx

@@ -0,0 +1,194 @@
+import {
+    Box,
+    Button,
+    Chip,
+    CssBaseline,
+    Divider,
+    Stack,
+    TextField,
+    ThemeProvider,
+    Typography,
+} from '@mui/material';
+import {
+    MutationError,
+    useUserInterfaceOwnTeam,
+    useUserInterfaceOwnTeamJoinLink,
+    useUserInterfaceCallbacks,
+    useUserInterfaceData,
+    useUserInterfaceParticipant,
+    useUserInterfaceParticipants,
+} from '@seriousgaming/sdk/ui';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { Settings, Context } from '../types';
+import { useAppTheme } from './theme';
+
+/**
+ * The holding screen.
+ *
+ * A waiting room is a player surface shown somewhere else, not a reduced one:
+ * the same hooks, the same callbacks, the same protocol. That is why there is
+ * no waiting-room-specific API anywhere in this file.
+ *
+ * Two things are worth knowing while you build one:
+ *
+ * 1. The facilitator can open it at any point, not only before the session
+ *    starts. `completedTicks` tells the two apart: 0 means no day has been
+ *    played, anything higher means a live session has been parked
+ * 2. Opening it does not stop the clock. A game that wants automatic ticks to
+ *    stop while people wait reads `waitingRoomOpen` in its tick controller and
+ *    returns `enabled: false`. This game is facilitator-paced, so there is
+ *    nothing to stop
+ */
+function Shell() {
+    const { data, settings, completedTicks } = useUserInterfaceData<Context, Settings>();
+    const { t } = useTranslation();
+    const ownTeam = useUserInterfaceOwnTeam();
+    const joinLink = useUserInterfaceOwnTeamJoinLink();
+    const { renameOwnTeam } = useUserInterfaceCallbacks();
+    const participants = useUserInterfaceParticipants();
+    const self = useUserInterfaceParticipant();
+
+    const [draftName, setDraftName] = useState('');
+    // The host's own reason, not a flag of ours. It knows whether the name was
+    // blank or too long, and a fixed 'try a shorter one' is wrong half the time.
+    const [refusal, setRefusal] = useState<string | null>(null);
+
+    const briefing = data.briefing.Message;
+    const looksAfter = data.roles.LooksAfter;
+    const roster = [...participants].sort((a, b) => a.index - b.index);
+
+    return (
+        <Box
+            sx={{
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                justifyContent: 'center',
+                gap: 2.5,
+                minHeight: '100vh',
+                p: 4,
+                textAlign: 'center',
+            }}
+        >
+            <Typography variant="h4" component="h1">
+                {completedTicks === 0 ? t('waiting.beforeStart') : t('waiting.paused')}
+            </Typography>
+
+            <Typography variant="body1" color="text.secondary" sx={{ maxWidth: 520 }}>
+                {completedTicks === 0 ? t('waiting.beforeStartHint') : t('waiting.pausedHint')}
+            </Typography>
+
+            {briefing !== '' && (
+                <Typography variant="body2" sx={{ fontStyle: 'italic', maxWidth: 520 }}>
+                    {briefing}
+                </Typography>
+            )}
+
+            <Divider flexItem sx={{ maxWidth: 360, alignSelf: 'center' }} />
+
+            <Typography variant="subtitle1">
+                {ownTeam ? t('waiting.youAre', { team: ownTeam.name }) : t('waiting.noTeamYet')}
+            </Typography>
+
+            {/* The team names itself here, and that name is the team's name
+                everywhere, including the host's own chrome. So this renders
+                `ownTeam.name` rather than what it just sent: the facilitator can
+                be renaming the same team at the same moment. */}
+            <Stack direction="row" spacing={1} sx={{ alignItems: 'flex-start' }}>
+                <TextField
+                    size="small"
+                    label={t('waiting.namePrompt')}
+                    value={draftName}
+                    error={refusal !== null}
+                    helperText={refusal ?? undefined}
+                    onChange={(event) => {
+                        setDraftName(event.target.value);
+                        setRefusal(null);
+                    }}
+                />
+                <Button
+                    variant="contained"
+                    onClick={async () => {
+                        try {
+                            await renameOwnTeam(draftName);
+                            setDraftName('');
+                        } catch (error) {
+                            setRefusal(
+                                error instanceof MutationError
+                                    ? error.message
+                                    : t('waiting.nameFailed')
+                            );
+                        }
+                    }}
+                >
+                    {t('waiting.nameSave')}
+                </Button>
+            </Stack>
+
+            <Box component="ul" sx={{ listStyle: 'none', p: 0, m: 0, display: 'grid', gap: 1 }}>
+                {roster.map((participant) => (
+                    <Box
+                        component="li"
+                        key={participant.id}
+                        sx={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            justifyContent: 'center',
+                            gap: 1,
+                        }}
+                    >
+                        <Box
+                            aria-hidden
+                            sx={{
+                                width: 8,
+                                height: 8,
+                                borderRadius: '50%',
+                                bgcolor: participant.connected ? 'success.main' : 'text.disabled',
+                            }}
+                        />
+                        <Typography variant="body2">
+                            {participant.id === self?.id
+                                ? t('waiting.you', { name: participant.name })
+                                : participant.name}
+                        </Typography>
+                        {looksAfter[participant.id] && (
+                            <Chip
+                                size="small"
+                                label={
+                                    settings.menu.Menu[looksAfter[participant.id] as string]
+                                        ?.Name ?? looksAfter[participant.id]
+                                }
+                            />
+                        )}
+                    </Box>
+                ))}
+            </Box>
+
+            {/* Every player surface receives its own team's join link, so a
+                latecomer joins the team already in front of them rather than
+                waiting for somebody to read a URL out. Null until the host
+                delivers it, so the panel is absent rather than empty. */}
+            {joinLink && (
+                <Box sx={{ display: 'grid', gap: 0.5 }}>
+                    <Typography variant="subtitle2">{t('waiting.joinHeading')}</Typography>
+                    <Typography variant="body2" sx={{ fontFamily: 'monospace' }}>
+                        {joinLink.joinUrl}
+                    </Typography>
+                </Box>
+            )}
+        </Box>
+    );
+}
+
+export default function App() {
+    const theme = useAppTheme();
+
+    return (
+        <ThemeProvider theme={theme}>
+            <CssBaseline enableColorScheme />
+            <Shell />
+        </ThemeProvider>
+    );
+}

package/dist/templates/starter-game/waiting_room/src/i18n.ts

@@ -0,0 +1,33 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+const resources = {
+    en: {
+        translation: {
+            waiting: {
+                beforeStart: 'Nearly opening time',
+                beforeStartHint:
+                    'Give your stall a name while you wait. The facilitator will open up when everyone is here.',
+                paused: 'Closed for a moment',
+                pausedHint:
+                    'Your stall is exactly as you left it. You will be back on your own screen shortly.',
+                youAre: 'You are on {{team}}',
+                noTeamYet: 'Waiting for the facilitator to put you on a stall',
+                namePrompt: 'Stall name',
+                nameSave: 'Save',
+                nameFailed: 'That name was not accepted.',
+                you: '{{name}} (you)',
+                joinHeading: 'Anyone else joining this stall',
+            },
+        },
+    },
+};
+
+i18n.use(initReactI18next).init({
+    resources,
+    lng: 'en',
+    fallbackLng: 'en',
+    interpolation: { escapeValue: false },
+});
+
+export default i18n;

package/dist/templates/starter-game/waiting_room/src/main.tsx

@@ -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 { UserInterfaceWrapper, useUserInterfaceLocale } 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 } = useUserInterfaceLocale();
+
+    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>
+        <UserInterfaceWrapper>
+            <RootWrapper>
+                <App />
+            </RootWrapper>
+        </UserInterfaceWrapper>
+    </StrictMode>
+);

package/dist/templates/starter-game/waiting_room/src/theme.ts

@@ -0,0 +1,45 @@
+import { createTheme } from '@mui/material/styles';
+import { useUserInterfaceTheme } 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 = useUserInterfaceTheme();
+
+    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]);
+};

package/dist/templates/starter-game/waiting_room/types.ts

@@ -0,0 +1,59 @@
+// This file is auto-generated from the waiting room user interface's capability definitions.
+// Do not edit this file directly. It will be regenerated on build.
+
+export interface Context {
+    roles: {
+        /**
+         * Which menu item each participant is in charge of, keyed by participant id. Written by the participantJoin hook, and the reason two people normally edit two different keys.
+         */
+        LooksAfter: {
+            [k: string]: string;
+        };
+    };
+    briefing: {
+        /**
+         * Facilitator note shown on every team's screen. Shared scope: one value for the whole session, written only from the session surface. Session lifetime: an undo or a reset leaves it as the facilitator last wrote it.
+         */
+        Message: string;
+    };
+}
+
+export type CrossTeamContext = Record<string, never>;
+
+export interface Settings {
+    menu: {
+        /**
+         * How many items the stall can make in a day, across the whole menu
+         */
+        Capacity: number;
+        Menu: Menu;
+    };
+}
+/**
+ * What the stall sells, keyed by item id. Money is in pence, so the sums stay in whole numbers. Read by the engine and every surface, so the price on screen and the price in the sums are the same number.
+ */
+export interface Menu {
+    [k: string]: MenuItem;
+}
+export interface MenuItem {
+    /**
+     * What the item is called on every screen
+     */
+    Name: string;
+    /**
+     * Where it sits on the menu, so every screen lists it in the same order. 1 comes first
+     */
+    Order: number;
+    /**
+     * Cost to make one, in pence
+     */
+    Cost: number;
+    /**
+     * Sale price, in pence
+     */
+    Price: number;
+}
+
+import type { WaitingRoomUserInterfaceCallbacks } from '@seriousgaming/sdk';
+
+export type Callbacks = Pick<WaitingRoomUserInterfaceCallbacks, never>;

package/dist/templates/starter-game/waiting_room/waiting_room.sdk.json

@@ -0,0 +1,10 @@
+{
+    "definition": {
+        "reads": ["roles", "briefing"],
+        "settings": ["menu"]
+    },
+    "ui": {
+        "entrypoint": "index.html"
+    },
+    "rootDirectory": "."
+}

package/dist/templates/tick-controller/logic.ts.liquid

@@ -0,0 +1,8 @@
+import { GetTickControllerFunction, intervalTick } from '@seriousgaming/sdk';
+import type { Context, Settings, Callbacks } from './types';
+
+export const GetTickController: GetTickControllerFunction<Context, Settings, Callbacks> = async ({ context, settings, callbacks }) => {
+  // `teams` (always present) lists every team this call covers as { teamId, index, context }.
+  // intervalTick takes milliseconds and validates the cadence against the 30s–7d bounds.
+  return intervalTick(60_000);
+};

package/dist/templates/ui/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/ui/src/App.test.tsx.liquid

@@ -0,0 +1,41 @@
+{% raw %}import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import {
+    UserInterfaceThemeContext,
+    UserInterfaceDataContext,
+} from '@seriousgaming/sdk/ui';
+import { createMockTheme } from '@seriousgaming/sdk/ui/testing';
+import './i18n';
+import App from './App';
+
+// Wrap App with the SDK context providers it needs.
+// These replace the iframe communication that the real app uses — no mocking needed.
+const renderApp = (data = {}, settings = {}) =>
+    render(
+        <UserInterfaceThemeContext.Provider value={createMockTheme()}>
+            <UserInterfaceDataContext.Provider
+                value={{ data, settings, completedTicks: 0, isRoundProcessing: false, setData: vi.fn() }}
+            >
+                <App />
+            </UserInterfaceDataContext.Provider>
+        </UserInterfaceThemeContext.Provider>
+    );
+
+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 userEvent is appropriate here.
+        // For controlled inputs that call setData, use fireEvent.change instead.
+        fireEvent.click(screen.getByRole('button', { name: /increment/i }));
+
+        expect(screen.getByText(/current value: 1/i)).toBeInTheDocument();
+    });
+});{% endraw %}

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

@@ -0,0 +1,103 @@
+import React, { useState } from 'react';
+import {
+    Box,
+    Button,
+    CssBaseline,
+    ThemeProvider,
+    Typography,
+} from '@mui/material';
+import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import { useTranslation } from 'react-i18next';
+import { Context, 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 template includes an example of a counter that reads and writes data.
+By default, it uses local component state. To connect it to the game's
+shared state, follow these steps:
+
+1. Create a capability for the counter:
+   pnpm run sdk new capability '{
+     "definition": {
+       "identifier": "uicounter",
+       "variablesSchema": {
+         "type": "object",
+         "properties": {
+           "value": { "type": "number", "default": 0 }
+         },
+         "required": ["value"],
+         "additionalProperties": false
+       }
+     }
+   }'
+
+2. In your ui.sdk.json, add "uicounter" to the `writes` array.
+
+3. In this file (App.tsx), uncomment the lines related to `useUserInterfaceData`
+   to connect the component to the capability.
+*/
+
+function App() {
+    // const { data, setData } = useUserInterfaceData<Context, Settings>();
+    const { t } = useTranslation();
+    const theme = useAppTheme();
+    const [localCounter, setLocalCounter] = useState(0);
+
+    // This is a local state example.
+    // To connect to game data, comment out the local state above and
+    // uncomment the `useUserInterfaceData` hook and the `counterValue` line below.
+    const counterValue = localCounter;
+    // const counterValue = data.uicounter.value;
+
+    const handleIncrement = () => {
+        // This is a local state update example.
+        setLocalCounter((c) => c + 1);
+
+        // To send data to the game, uncomment the `setData` call below.
+        // setData({
+        //     uicounter: {
+        //         // Spread existing capability data to avoid overwriting other variables
+        //         ...(data.uicounter || {}),
+        //         value: (data.uicounter?.value ?? 0) + 1,
+        //     },
+        // });
+    };
+
+    return (
+        <ThemeProvider theme={theme}>
+            <CssBaseline enableColorScheme />
+            <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;