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

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

@@ -0,0 +1,307 @@
+import {
+    createMockSharedState,
+    createMockTeamState,
+    renderSessionUserInterface,
+    type RenderSessionUserInterfaceOptions,
+} from '@seriousgaming/sdk/ui/testing';
+import { fireEvent, screen, waitFor, within } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { SessionData, Settings, SharedContext, TeamContext } from '../types';
+import App from './App';
+import './i18n';
+
+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 },
+        },
+    },
+    session: { ShowJoinLinks: true, CurrencySymbol: '£' },
+};
+
+const teamContext = (over: Partial<TeamContext> = {}): TeamContext => ({
+    plan: { Make: { lemonade: 40, icedtea: 20 } },
+    results: {
+        Day: 0,
+        Weather: 'sunny',
+        Lines: {},
+        Takings: 0,
+        Spent: 0,
+        Profit: 0,
+        Purse: 0,
+    },
+    roles: { LooksAfter: {} },
+    ...over,
+});
+
+/** A team that traded yesterday and has not touched its numbers since. */
+const traded = (made: { lemonade: number; icedtea: number }, plan = made): TeamContext =>
+    teamContext({
+        plan: { Make: { ...plan } },
+        results: {
+            Day: 1,
+            Weather: 'sunny',
+            Lines: {
+                lemonade: {
+                    Made: made.lemonade,
+                    Wanted: 60,
+                    Sold: made.lemonade,
+                    PouredAway: 0,
+                    TurnedAway: 0,
+                },
+                icedtea: {
+                    Made: made.icedtea,
+                    Wanted: 30,
+                    Sold: made.icedtea,
+                    PouredAway: 0,
+                    TurnedAway: 0,
+                },
+            },
+            Takings: 3200,
+            Spent: 1000,
+            Profit: 2200,
+            Purse: 2200,
+        },
+    });
+
+const sessionMeta = {
+    sessionId: 'session-1',
+    name: 'Tuesday cohort',
+    readOnly: false,
+    waitingRoomOpen: false,
+    joinPin: null,
+};
+
+const links = [
+    {
+        teamId: 'team-1',
+        joinUrl: 'https://example.test/join/one',
+        observeUrl: 'https://example.test/observe/one',
+    },
+    {
+        teamId: 'team-2',
+        joinUrl: 'https://example.test/join/two',
+        observeUrl: 'https://example.test/observe/two',
+    },
+];
+
+const shared: SharedContext = { briefing: { Message: '' } };
+
+const render = (options: RenderSessionUserInterfaceOptions<SessionData> = {}) =>
+    renderSessionUserInterface<SessionData>(<App />, {
+        settings,
+        sessionMeta,
+        teamLinks: links,
+        teams: [
+            { teamId: 'team-1', index: 0, name: 'Bluebird' },
+            { teamId: 'team-2', index: 1, name: 'Kestrel' },
+        ],
+        ...options,
+        // A case names only the half it is about; the other keeps its default.
+        sessionData: {
+            shared: createMockSharedState<SharedContext>({ context: shared }),
+            teams: {
+                'team-1': createMockTeamState<TeamContext>({
+                    context: teamContext(),
+                    completedTicks: 0,
+                }),
+                'team-2': createMockTeamState<TeamContext>({
+                    context: teamContext(),
+                    completedTicks: 2,
+                }),
+            },
+            ...options.sessionData,
+        },
+    });
+
+describe('the stalls table', () => {
+    it('says what each stall is making against what it can make', () => {
+        render();
+
+        expect(screen.getByTestId('team-team-1')).toHaveTextContent('60 of 120');
+    });
+
+    it('counts the day each stall is about to trade', () => {
+        render();
+
+        expect(screen.getByTestId('team-team-2')).toHaveTextContent('3');
+    });
+
+    /**
+     * There is no 'we are ready' button on a player's screen, and adding one
+     * would be a commit step by another name. Comparing today's plan against
+     * what was actually made yesterday answers the same question for free.
+     */
+    it('flags a stall still sitting on yesterday’s numbers', () => {
+        render({
+            sessionData: {
+                teams: {
+                    'team-1': createMockTeamState<TeamContext>({
+                        context: traded({ lemonade: 40, icedtea: 20 }),
+                        completedTicks: 1,
+                    }),
+                    'team-2': createMockTeamState<TeamContext>({
+                        context: traded(
+                            { lemonade: 40, icedtea: 20 },
+                            { lemonade: 55, icedtea: 20 }
+                        ),
+                        completedTicks: 1,
+                    }),
+                },
+            },
+        });
+
+        expect(screen.getByTestId('team-team-1')).toHaveTextContent('Same as yesterday');
+        expect(screen.getByTestId('team-team-2')).toHaveTextContent('Changed');
+        expect(screen.getByText('1 of 2 have changed their numbers today')).toBeInTheDocument();
+    });
+
+    // The stalls open their own days. A facilitator who could run one would end
+    // up running it for a group that had not finished deciding.
+    it('offers no way to run a stall’s day', () => {
+        render();
+
+        expect(screen.queryByRole('button', { name: /Run/ })).not.toBeInTheDocument();
+    });
+
+    it('will not undo a stall that has not traded', () => {
+        render();
+
+        const row = screen.getByTestId('team-team-1');
+        expect(within(row).getByRole('button', { name: 'Undo' })).toBeDisabled();
+    });
+});
+
+describe('getting into a team', () => {
+    /**
+     * Both are one click and both open a tab of their own: a session surface
+     * owns the whole canvas, so navigating this frame would leave the
+     * facilitator with no way back.
+     */
+    it('offers a way to observe a stall without joining it', () => {
+        render();
+
+        const observe = within(screen.getByTestId('team-team-1')).getByRole('link', {
+            name: 'Observe',
+        });
+
+        expect(observe).toHaveAttribute('href', 'https://example.test/observe/one');
+        expect(observe).toHaveAttribute('target', '_blank');
+        expect(observe).toHaveAttribute('rel', expect.stringContaining('noopener'));
+    });
+
+    it('offers a way to join a stall as a player', () => {
+        render();
+
+        const join = within(screen.getByTestId('team-team-2')).getByRole('link', { name: 'Join' });
+
+        expect(join).toHaveAttribute('href', 'https://example.test/join/two');
+        expect(join).toHaveAttribute('target', '_blank');
+    });
+
+    it('copies a join link, for handing out', async () => {
+        const writeText = vi.fn().mockResolvedValue(undefined);
+        Object.assign(navigator, { clipboard: { writeText } });
+        render();
+
+        const row = screen.getByTestId('team-team-1');
+        fireEvent.click(within(row).getByRole('button', { name: /Copy the join link/ }));
+
+        await waitFor(() =>
+            expect(writeText).toHaveBeenCalledWith('https://example.test/join/one')
+        );
+        expect(await within(row).findByText('Copied')).toBeInTheDocument();
+    });
+
+    // Permissions Policy is implemented unevenly, so a button that silently
+    // does nothing is a real outcome to design for.
+    it('shows the link to copy by hand when the clipboard refuses', async () => {
+        const writeText = vi.fn().mockRejectedValue(new Error('blocked'));
+        Object.assign(navigator, { clipboard: { writeText } });
+        render();
+
+        const row = screen.getByTestId('team-team-1');
+        fireEvent.click(within(row).getByRole('button', { name: /Copy the join link/ }));
+
+        expect(await within(row).findByText('https://example.test/join/one')).toBeInTheDocument();
+    });
+
+    it('offers nothing before the host has delivered the links', () => {
+        render({ teamLinks: [] });
+
+        expect(screen.queryByRole('link', { name: 'Observe' })).not.toBeInTheDocument();
+    });
+
+    it('offers nothing when the game turns the links off', () => {
+        render({
+            settings: { ...settings, session: { ...settings.session, ShowJoinLinks: false } },
+        });
+
+        expect(screen.queryByRole('link', { name: 'Join' })).not.toBeInTheDocument();
+    });
+});
+
+describe('the notice', () => {
+    it('is a shared write, so it goes to every stall at once', async () => {
+        const setData = vi.fn().mockResolvedValue(undefined);
+        render({ setData });
+
+        fireEvent.change(screen.getByLabelText('Message'), {
+            target: { value: 'Ten minutes left' },
+        });
+        fireEvent.click(screen.getByRole('button', { name: 'Send' }));
+
+        await waitFor(() =>
+            expect(setData).toHaveBeenCalledWith({ briefing: { Message: 'Ten minutes left' } })
+        );
+    });
+});
+
+describe('host-owned things', () => {
+    it('offers the guide only when the host says it has one', () => {
+        render();
+
+        expect(screen.queryByRole('button', { name: 'Facilitator guide' })).not.toBeInTheDocument();
+    });
+
+    it('asks the host to open the guide', async () => {
+        const openHostOverlay = vi.fn().mockResolvedValue(undefined);
+        render({ hostOverlays: ['facilitator-guide'], callbacks: { openHostOverlay } });
+
+        fireEvent.click(screen.getByRole('button', { name: 'Facilitator guide' }));
+
+        await waitFor(() => expect(openHostOverlay).toHaveBeenCalledWith('facilitator-guide'));
+    });
+
+    it('parks the session through the host rather than a flag of its own', async () => {
+        const setWaitingRoom = vi.fn().mockResolvedValue(undefined);
+        render({ callbacks: { setWaitingRoom } });
+
+        fireEvent.click(screen.getByRole('switch', { name: 'Waiting room' }));
+
+        await waitFor(() => expect(setWaitingRoom).toHaveBeenCalledWith(true));
+    });
+});
+
+describe('a read-only session', () => {
+    it('says why, instead of offering controls the host will refuse', () => {
+        render({
+            sessionMeta: { ...sessionMeta, readOnly: true },
+            sessionData: {
+                teams: {
+                    'team-1': createMockTeamState<TeamContext>({
+                        context: teamContext(),
+                        completedTicks: 1,
+                    }),
+                },
+            },
+            teams: [{ teamId: 'team-1', index: 0, name: 'Bluebird' }],
+        });
+
+        expect(screen.getByText(/read only/)).toBeInTheDocument();
+        expect(screen.getByRole('button', { name: 'Undo' })).toBeDisabled();
+    });
+});

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

@@ -0,0 +1,309 @@
+import {
+    Alert,
+    AppBar,
+    Box,
+    Button,
+    Chip,
+    CssBaseline,
+    Snackbar,
+    Stack,
+    Switch,
+    Table,
+    TableBody,
+    TableCell,
+    TableHead,
+    TableRow,
+    TextField,
+    ThemeProvider,
+    Toolbar,
+    Tooltip,
+    Typography,
+} from '@mui/material';
+import {
+    useSessionUserInterfaceCallbacks,
+    useSessionUserInterfaceData,
+    useSessionUserInterfaceHostOverlays,
+    useSessionUserInterfaceMeta,
+    useSessionUserInterfaceParticipants,
+    useSessionUserInterfaceTeamLinks,
+    useSessionUserInterfaceTeams,
+} from '@seriousgaming/sdk/ui';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { Settings, SessionData, SharedWrites, TeamContext, TeamWrites } from '../types';
+import { money } from './format';
+import Section from './Section';
+import TeamDoor from './TeamDoor';
+import { useAppTheme } from './theme';
+
+/**
+ * The facilitator's whole screen.
+ *
+ * A game that ships a session surface replaces the host's roster page outright,
+ * so everything a facilitator needs during play has to be here: what each stall
+ * is making, whether anyone has touched it today, and a way into any stall's
+ * screen. The stalls run their own days, so this watches rather than drives,
+ * and the two host-owned things it cannot draw itself, the guide and the
+ * waiting room, it asks the host for.
+ */
+function Shell() {
+    const { sessionData, settings, setData } = useSessionUserInterfaceData<
+        SessionData,
+        Settings,
+        SharedWrites,
+        TeamWrites
+    >();
+    const teams = useSessionUserInterfaceTeams();
+    const participants = useSessionUserInterfaceParticipants();
+    const links = useSessionUserInterfaceTeamLinks();
+    const meta = useSessionUserInterfaceMeta();
+    const overlays = useSessionUserInterfaceHostOverlays();
+    const { undoTick, openHostOverlay, setWaitingRoom } = useSessionUserInterfaceCallbacks();
+    const { t } = useTranslation();
+
+    const [refusal, setRefusal] = useState<string | null>(null);
+    const [briefingDraft, setBriefingDraft] = useState<string | null>(null);
+
+    // One value for the session, delivered once, whether or not a team exists.
+    const briefing = sessionData.shared.context.briefing.Message;
+
+    // A denial is terminal, so report it rather than retrying. The alternative
+    // is a control that silently does nothing, which is worse than an error.
+    const attempt = (action: () => Promise<unknown>) => {
+        void action().catch((error: unknown) =>
+            setRefusal(error instanceof Error ? error.message : String(error))
+        );
+    };
+
+    /**
+     * Whether a stall is still sitting on the numbers it traded yesterday.
+     *
+     * There is nothing to press on a player's screen to say 'we are ready', and
+     * adding one would be a commit step by another name. Comparing today's plan
+     * against what was actually made yesterday costs no extra state and answers
+     * the only question a facilitator has before ticking.
+     */
+    const untouched = (team: TeamContext | undefined) => {
+        if (!team) return false;
+        const lines = Object.entries(team.results.Lines);
+        if (lines.length === 0) return false;
+        return lines.every(([id, line]) => (team.plan.Make[id] ?? 0) === line.Made);
+    };
+
+    const movedOn = teams.filter(
+        (team) => !untouched(sessionData.teams[team.teamId]?.context)
+    ).length;
+
+    return (
+        <Box sx={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+            <AppBar position="static" color="default" elevation={0}>
+                <Toolbar sx={{ gap: 2 }}>
+                    <Typography variant="h6" component="h1" sx={{ flexGrow: 1 }} noWrap>
+                        {meta.name}
+                    </Typography>
+
+                    <Tooltip title={t('session.waitingRoomHint')}>
+                        <Stack direction="row" spacing={1} sx={{ alignItems: 'center' }}>
+                            <Typography variant="body2">{t('session.waitingRoom')}</Typography>
+                            <Switch
+                                checked={meta.waitingRoomOpen}
+                                disabled={meta.readOnly}
+                                slotProps={{ input: { 'aria-label': t('session.waitingRoom') } }}
+                                onChange={(event) =>
+                                    attempt(() => setWaitingRoom(event.target.checked))
+                                }
+                            />
+                        </Stack>
+                    </Tooltip>
+
+                    {/* Only for an overlay this host actually offers: a button
+                        for one it does not have is a button that cannot work. */}
+                    {overlays.includes('facilitator-guide') && (
+                        <Button
+                            variant="outlined"
+                            onClick={() => attempt(() => openHostOverlay('facilitator-guide'))}
+                        >
+                            {t('session.guide')}
+                        </Button>
+                    )}
+                </Toolbar>
+            </AppBar>
+
+            <Box sx={{ flex: 1, minHeight: 0, overflowY: 'auto', py: 3 }}>
+                <Stack spacing={3} sx={{ maxWidth: 1200, mx: 'auto', px: 2 }}>
+                    {meta.readOnly && <Alert severity="warning">{t('session.readOnly')}</Alert>}
+
+                    <Section
+                        title={t('session.stalls')}
+                        hint={t('session.movedOn', { movedOn, total: teams.length })}
+                    >
+                        <Box sx={{ overflowX: 'auto' }}>
+                            <Table size="small">
+                                <TableHead>
+                                    <TableRow>
+                                        <TableCell>{t('session.team')}</TableCell>
+                                        <TableCell align="right">{t('session.people')}</TableCell>
+                                        <TableCell align="right">{t('session.day')}</TableCell>
+                                        <TableCell align="right">{t('session.making')}</TableCell>
+                                        <TableCell>{t('session.status')}</TableCell>
+                                        <TableCell align="right">{t('session.purse')}</TableCell>
+                                        <TableCell>{t('session.wayIn')}</TableCell>
+                                        <TableCell align="right">{t('session.controls')}</TableCell>
+                                    </TableRow>
+                                </TableHead>
+                                <TableBody>
+                                    {teams.map((team) => {
+                                        const state = sessionData.teams[team.teamId];
+                                        const context = state?.context;
+                                        const planned = Object.values(
+                                            context?.plan.Make ?? {}
+                                        ).reduce((sum, value) => sum + value, 0);
+                                        const size = participants.filter(
+                                            (person) => person.teamId === team.teamId
+                                        ).length;
+                                        const stale = untouched(context);
+
+                                        return (
+                                            <TableRow
+                                                key={team.teamId}
+                                                data-testid={`team-${team.teamId}`}
+                                            >
+                                                <TableCell>{team.name}</TableCell>
+                                                <TableCell align="right">{size}</TableCell>
+                                                <TableCell align="right">
+                                                    {(state?.completedTicks ?? 0) + 1}
+                                                </TableCell>
+                                                <TableCell
+                                                    align="right"
+                                                    sx={{ fontVariantNumeric: 'tabular-nums' }}
+                                                >
+                                                    {t('session.ofCapacity', {
+                                                        planned,
+                                                        capacity: settings.menu.Capacity,
+                                                    })}
+                                                </TableCell>
+                                                <TableCell>
+                                                    {stale ? (
+                                                        <Chip
+                                                            size="small"
+                                                            variant="outlined"
+                                                            label={t('session.unchanged')}
+                                                        />
+                                                    ) : (
+                                                        <Chip
+                                                            size="small"
+                                                            color="success"
+                                                            label={t('session.changed')}
+                                                        />
+                                                    )}
+                                                </TableCell>
+                                                <TableCell align="right">
+                                                    {money(
+                                                        settings.session.CurrencySymbol,
+                                                        context?.results.Purse ?? 0
+                                                    )}
+                                                </TableCell>
+                                                <TableCell>
+                                                    <TeamDoor
+                                                        links={links.find(
+                                                            (link) => link.teamId === team.teamId
+                                                        )}
+                                                        teamName={team.name}
+                                                        show={settings.session.ShowJoinLinks}
+                                                    />
+                                                </TableCell>
+                                                <TableCell align="right">
+                                                    {/* No way to run a day from
+                                                        here. The stalls open
+                                                        themselves, and a
+                                                        facilitator who could
+                                                        run the day would end up
+                                                        doing it for a group
+                                                        still deciding. Undo
+                                                        stays: taking a day back
+                                                        is a correction, and
+                                                        nobody else can make it. */}
+                                                    <Button
+                                                        size="small"
+                                                        color="inherit"
+                                                        disabled={
+                                                            meta.readOnly ||
+                                                            (state?.completedTicks ?? 0) === 0
+                                                        }
+                                                        onClick={() =>
+                                                            attempt(() => undoTick(team.teamId))
+                                                        }
+                                                    >
+                                                        {t('session.undo')}
+                                                    </Button>
+                                                </TableCell>
+                                            </TableRow>
+                                        );
+                                    })}
+                                </TableBody>
+                            </Table>
+                        </Box>
+                    </Section>
+
+                    <Section title={t('session.notice')} hint={t('session.noticeHint')}>
+                        <Stack direction="row" spacing={1} sx={{ alignItems: 'flex-start' }}>
+                            <TextField
+                                fullWidth
+                                multiline
+                                minRows={2}
+                                size="small"
+                                label={t('session.noticeLabel')}
+                                value={briefingDraft ?? briefing}
+                                disabled={meta.readOnly}
+                                onChange={(event) => setBriefingDraft(event.target.value)}
+                            />
+                            <Button
+                                variant="contained"
+                                disabled={meta.readOnly || briefingDraft === null}
+                                onClick={() => {
+                                    // The one-argument form is a shared write:
+                                    // one value for the whole session, applied
+                                    // to every team at once. Only a session
+                                    // surface may make one, which is what makes
+                                    // a shared capability safe in a game whose
+                                    // teams tick on their own clocks.
+                                    attempt(async () => {
+                                        await setData({
+                                            briefing: { Message: briefingDraft ?? '' },
+                                        });
+                                        setBriefingDraft(null);
+                                    });
+                                }}
+                            >
+                                {t('session.send')}
+                            </Button>
+                        </Stack>
+                    </Section>
+                </Stack>
+            </Box>
+
+            <Snackbar
+                open={refusal !== null}
+                autoHideDuration={8000}
+                onClose={() => setRefusal(null)}
+                anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }}
+            >
+                <Alert severity="error" onClose={() => setRefusal(null)}>
+                    {refusal}
+                </Alert>
+            </Snackbar>
+        </Box>
+    );
+}
+
+export default function App() {
+    const theme = useAppTheme();
+
+    return (
+        <ThemeProvider theme={theme}>
+            <CssBaseline enableColorScheme />
+            <Shell />
+        </ThemeProvider>
+    );
+}

package/dist/templates/starter-game/session/src/Section.tsx

@@ -0,0 +1,37 @@
+import { Box, Card, CardContent, Stack, Typography } from '@mui/material';
+import type { ReactNode } from 'react';
+
+type Props = {
+    title: string;
+    hint?: string;
+    action?: ReactNode;
+    children: ReactNode;
+};
+
+/** One card, one heading, one job. Every panel on this surface is built of these. */
+export default function Section({ title, hint, action, children }: Props) {
+    return (
+        <Card variant="outlined">
+            <CardContent>
+                <Stack
+                    direction="row"
+                    spacing={2}
+                    sx={{ alignItems: 'flex-start', justifyContent: 'space-between' }}
+                >
+                    <Box>
+                        <Typography variant="h6" component="h2">
+                            {title}
+                        </Typography>
+                        {hint && (
+                            <Typography variant="body2" color="text.secondary">
+                                {hint}
+                            </Typography>
+                        )}
+                    </Box>
+                    {action}
+                </Stack>
+                <Box sx={{ mt: 2 }}>{children}</Box>
+            </CardContent>
+        </Card>
+    );
+}