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

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

@@ -0,0 +1,175 @@
+import {
+    Alert,
+    AppBar,
+    Box,
+    Chip,
+    CssBaseline,
+    LinearProgress,
+    Snackbar,
+    Stack,
+    ThemeProvider,
+    Toolbar,
+    Typography,
+    useMediaQuery,
+    useTheme,
+} from '@mui/material';
+import {
+    useMutationReporter,
+    useUserInterfaceOwnTeam,
+    useUserInterfaceData,
+    useUserInterfaceParticipant,
+    useUserInterfaceValidationRejections,
+} from '@seriousgaming/sdk/ui';
+import { useTranslation } from 'react-i18next';
+
+import type { Settings, Context } from '../types';
+import DayBar from './DayBar';
+import HistoryPanel from './HistoryPanel';
+import { useAppTheme } from './theme';
+import ThemeToggle from './ThemeToggle';
+import TodayPanel from './TodayPanel';
+import { WriteContext } from './writes';
+import YesterdayPanel from './YesterdayPanel';
+
+/** Wide enough for the history table without letting a card run an ultrawide monitor. */
+const CONTENT_MAX_WIDTH = 900;
+
+function Shell() {
+    const { data, settings, completedTicks, isRoundProcessing } = useUserInterfaceData<
+        Context,
+        Settings
+    >();
+    const participant = useUserInterfaceParticipant();
+    const ownTeam = useUserInterfaceOwnTeam();
+    const { rejections, clearRejections } = useUserInterfaceValidationRejections();
+    const reporter = useMutationReporter();
+    const { t } = useTranslation();
+    const theme = useTheme();
+    const compact = useMediaQuery(theme.breakpoints.down('sm'));
+
+    const looksAfter = participant ? data.roles.LooksAfter[participant.id] : undefined;
+    const yourItem = looksAfter ? settings.menu.Menu[looksAfter]?.Name : undefined;
+    const briefing = data.briefing.Message;
+
+    // A validator refusal arrives twice: here as a `validation-rejected`
+    // outcome, and through the rejection channel below, which carries the
+    // validator's own message and is the better thing to show. Rendering both
+    // would put a generic notice on top of a specific one.
+    const unexplained =
+        reporter.failure && reporter.failure.outcome.kind !== 'validation-rejected'
+            ? reporter.failure
+            : null;
+
+    return (
+        <WriteContext.Provider value={reporter}>
+            <Box sx={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+                <AppBar position="static" color="default" elevation={0}>
+                    <Toolbar sx={{ gap: 1 }}>
+                        <Typography variant="h6" component="h1" sx={{ flexGrow: 1 }} noWrap>
+                            {ownTeam?.name ?? t('shell.untitledTeam')}
+                        </Typography>
+                        {yourItem && !compact && (
+                            <Chip size="small" label={t('shell.looksAfter', { item: yourItem })} />
+                        )}
+                        <Chip
+                            size="small"
+                            color="primary"
+                            label={t('shell.day', { day: completedTicks + 1 })}
+                            data-testid="day"
+                        />
+                        <ThemeToggle />
+                    </Toolbar>
+                </AppBar>
+
+                {/* One band per reason the screen is not simply waiting for the
+                    team. Each says which reason it is: a surface that only greys
+                    its controls out reads as having broken. */}
+                {isRoundProcessing && (
+                    <Box sx={{ flex: '0 0 auto' }}>
+                        <Alert square severity="info" sx={{ borderRadius: 0, py: 0.25 }}>
+                            {t('shell.processing')}
+                        </Alert>
+                        <LinearProgress />
+                    </Box>
+                )}
+
+                {briefing !== '' && (
+                    <Alert
+                        square
+                        severity="info"
+                        icon={false}
+                        sx={{ flex: '0 0 auto', borderRadius: 0 }}
+                    >
+                        <Stack direction="row" spacing={1} sx={{ alignItems: 'baseline' }}>
+                            <Typography variant="overline">{t('shell.briefing')}</Typography>
+                            <Typography variant="body2">{briefing}</Typography>
+                        </Stack>
+                    </Alert>
+                )}
+
+                <Box sx={{ flex: 1, minHeight: 0, overflowY: 'auto', py: 3 }}>
+                    <Stack spacing={3} sx={{ maxWidth: CONTENT_MAX_WIDTH, mx: 'auto', px: 2 }}>
+                        <TodayPanel />
+                        <YesterdayPanel />
+                        <HistoryPanel />
+                    </Stack>
+                </Box>
+
+                <DayBar />
+
+                {/* The validator's own message, which is the one that says what
+                    the rule was and who else was changing something. */}
+                <Snackbar
+                    open={rejections.length > 0}
+                    onClose={clearRejections}
+                    autoHideDuration={8000}
+                    anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }}
+                >
+                    <Alert severity="warning" onClose={clearRejections}>
+                        {rejections.map((rejection) => rejection.message).join(' ')}
+                    </Alert>
+                </Snackbar>
+
+                {/* What nothing else reports: denied, tick-failed, conflict, error. */}
+                <Snackbar
+                    open={unexplained !== null}
+                    onClose={reporter.dismiss}
+                    autoHideDuration={8000}
+                    anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }}
+                >
+                    <Alert severity="error" onClose={reporter.dismiss}>
+                        {unexplained?.outcome.kind === 'tick-failed'
+                            ? t('shell.weekOver')
+                            : t('shell.writeFailed')}
+                    </Alert>
+                </Snackbar>
+
+                {/* Not a failure. The change landed, but in the day after the one
+                    they were looking at, and nothing else on screen says so. */}
+                <Snackbar
+                    open={reporter.late !== null}
+                    onClose={reporter.dismiss}
+                    autoHideDuration={8000}
+                    anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }}
+                >
+                    <Alert severity="info" onClose={reporter.dismiss}>
+                        {t('shell.countedNextDay', {
+                            day: (reporter.late?.committedAtTick ?? 0) + 1,
+                        })}
+                    </Alert>
+                </Snackbar>
+            </Box>
+        </WriteContext.Provider>
+    );
+}
+
+export default function App() {
+    const theme = useAppTheme();
+
+    return (
+        <ThemeProvider theme={theme}>
+            <CssBaseline enableColorScheme />
+            <Shell />
+        </ThemeProvider>
+    );
+}

package/dist/templates/starter-game/ui/src/DayBar.test.tsx

@@ -0,0 +1,78 @@
+import { createMockParticipant, renderUserInterface } from '@seriousgaming/sdk/ui/testing';
+import { fireEvent, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import DayBar from './DayBar';
+import './i18n';
+import { baseSettings, baseContext } from './test-helpers';
+
+const ada = createMockParticipant({ id: 'participant-1', name: 'Ada' });
+
+const render = (options: Parameters<typeof renderUserInterface>[1] = {}) =>
+    renderUserInterface(<DayBar />, {
+        data: baseContext,
+        settings: baseSettings,
+        participant: ada,
+        ...options,
+    });
+
+describe('opening the stall', () => {
+    /**
+     * The stalls run their own days. `requestTick` from a player surface
+     * advances that team and nobody else, which is the whole point of
+     * independent teams: a stall that has decided gets on with it instead of
+     * waiting for the room.
+     */
+    it('is the players’ to do, not the facilitator’s', async () => {
+        const requestTick = vi.fn().mockResolvedValue(undefined);
+        render({ callbacks: { requestTick } });
+
+        fireEvent.click(screen.getByTestId('open-stall'));
+
+        await waitFor(() => expect(requestTick).toHaveBeenCalled());
+    });
+
+    it('says which day is about to play out', () => {
+        render({ completedTicks: 4 });
+
+        expect(screen.getByText(/day 5 plays out/)).toBeInTheDocument();
+    });
+
+    it('says what the stall is making, against what it could', () => {
+        render();
+
+        expect(screen.getByText('Making 70 of a possible 120')).toBeInTheDocument();
+    });
+
+    it('will not open a stall that has decided nothing', () => {
+        render({
+            data: { ...baseContext, plan: { Make: { lemonade: 0, icedtea: 0, cookies: 0 } } },
+        });
+
+        expect(screen.getByTestId('open-stall')).toBeDisabled();
+        expect(screen.getByText('Decide what to make first')).toBeInTheDocument();
+    });
+
+    // The engine would happily make 150 things; the game says the stall cannot.
+    // Blocking here is kinder than letting a day play out on a plan the
+    // validator has already been refusing.
+    it('will not open a stall planning more than it can make', () => {
+        render({
+            data: {
+                ...baseContext,
+                plan: { Make: { lemonade: 90, icedtea: 40, cookies: 20 } },
+            },
+        });
+
+        expect(screen.getByTestId('open-stall')).toBeDisabled();
+        expect(screen.getByText('Take something off before you open up')).toBeInTheDocument();
+    });
+
+    // An observer has no participant identity, so there is nothing for the
+    // host to attribute a tick to.
+    it('is not offered to somebody observing', () => {
+        render({ viewerRole: 'observer', participant: null });
+
+        expect(screen.getByTestId('open-stall')).toBeDisabled();
+    });
+});

package/dist/templates/starter-game/ui/src/DayBar.tsx

@@ -0,0 +1,72 @@
+import { Box, Button, Paper, Stack, Typography } from '@mui/material';
+import {
+    useUserInterfaceCallbacks,
+    useUserInterfaceData,
+    useUserInterfaceParticipant,
+} from '@seriousgaming/sdk/ui';
+import { useTranslation } from 'react-i18next';
+
+import type { Settings, Context } from '../types';
+import { totalPlanned } from './menu';
+import { useWrite } from './writes';
+
+/**
+ * The stall opens its own day.
+ *
+ * `requestTick` from a player surface advances that team and nobody else, which
+ * is what independent teams are for: a stall that has made its mind up gets on
+ * with it instead of waiting for the room. The facilitator watches, and can
+ * undo a day, but does not drive the session.
+ *
+ * It is a shared control with no lock on it, which is deliberate. Somebody can
+ * open the stall while a team-mate is still moving a slider, and when that
+ * happens the change lands on the following day rather than being lost: that is
+ * what `reporter.late` reports, and why the notice for it exists.
+ */
+export default function DayBar() {
+    const { data, settings, completedTicks } = useUserInterfaceData<Context, Settings>();
+    const participant = useUserInterfaceParticipant();
+    const { requestTick } = useUserInterfaceCallbacks();
+    const { run, pending } = useWrite();
+    const { t } = useTranslation();
+
+    const planned = totalPlanned(data.plan.Make);
+    const over = planned > settings.menu.Capacity;
+    const empty = planned === 0;
+
+    return (
+        <Paper
+            square
+            elevation={3}
+            sx={{ flex: '0 0 auto', borderTop: 1, borderColor: 'divider', px: 2, py: 1.5 }}
+        >
+            <Stack
+                direction="row"
+                spacing={2}
+                sx={{ alignItems: 'center', justifyContent: 'space-between', mx: 'auto' }}
+            >
+                <Box>
+                    <Typography variant="subtitle2">
+                        {t('day.making', { planned, capacity: settings.menu.Capacity })}
+                    </Typography>
+                    <Typography variant="caption" color="text.secondary">
+                        {over
+                            ? t('day.tooMany')
+                            : empty
+                              ? t('day.nothing')
+                              : t('day.ready', { day: completedTicks + 1 })}
+                    </Typography>
+                </Box>
+                <Button
+                    variant="contained"
+                    size="large"
+                    disabled={!participant || pending || over || empty}
+                    data-testid="open-stall"
+                    onClick={() => void run(() => requestTick(), 'open-stall')}
+                >
+                    {t('day.open')}
+                </Button>
+            </Stack>
+        </Paper>
+    );
+}

package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx

@@ -0,0 +1,74 @@
+import { renderUserInterface } from '@seriousgaming/sdk/ui/testing';
+import { screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Context } from '../types';
+import HistoryPanel from './HistoryPanel';
+import './i18n';
+import { baseSettings, baseContext, playedDay } from './test-helpers';
+
+/** Day `n`'s results, as the round that closed it recorded them. */
+function dayResults(n: number, profit: number): Context['results'] {
+    return { ...playedDay.results, Day: n, Profit: profit, Purse: profit * n };
+}
+
+describe('HistoryPanel', () => {
+    it('shows nothing before the first day has been played', () => {
+        renderUserInterface(<HistoryPanel />, { data: baseContext, settings: baseSettings });
+
+        expect(screen.queryByText('Every day so far')).not.toBeInTheDocument();
+    });
+
+    it('lists the earlier days from the host, and today from live context', async () => {
+        const getPastState = vi.fn(async () => [
+            {
+                teamId: 'team-1',
+                index: 0,
+                name: 'Team 1',
+                tick: 1,
+                recordedAt: 0,
+                complete: false,
+                context: { results: dayResults(1, 100) },
+            },
+            {
+                teamId: 'team-1',
+                index: 0,
+                name: 'Team 1',
+                tick: 2,
+                recordedAt: 0,
+                complete: false,
+                context: { results: dayResults(2, 200) },
+            },
+        ]);
+
+        renderUserInterface(<HistoryPanel />, {
+            data: { ...playedDay, results: dayResults(3, 300) },
+            settings: baseSettings,
+            completedTicks: 3,
+            callbacks: { getPastState: getPastState as never },
+        });
+
+        await waitFor(() => expect(screen.getByTestId('day-1')).toBeInTheDocument());
+        expect(screen.getByTestId('day-2')).toBeInTheDocument();
+        expect(screen.getByTestId('day-3')).toBeInTheDocument();
+        expect(getPastState).toHaveBeenCalledWith({
+            fromTick: 1,
+            toTick: 3,
+            capabilityIds: ['results'],
+        });
+    });
+
+    it('still shows today when the history cannot be read', async () => {
+        renderUserInterface(<HistoryPanel />, {
+            data: { ...playedDay, results: dayResults(2, 200) },
+            settings: baseSettings,
+            completedTicks: 2,
+            callbacks: {
+                getPastState: vi.fn(async () => Promise.reject(new Error('no'))) as never,
+            },
+        });
+
+        await waitFor(() => expect(screen.getByTestId('day-2')).toBeInTheDocument());
+        expect(screen.queryByTestId('day-1')).not.toBeInTheDocument();
+    });
+});

package/dist/templates/starter-game/ui/src/HistoryPanel.tsx

@@ -0,0 +1,120 @@
+import { Box, Table, TableBody, TableCell, TableHead, TableRow, Typography } from '@mui/material';
+import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { Settings, Context } from '../types';
+import { count, money } from './format';
+import Section from './Section';
+
+type DayResults = Context['results'];
+
+/**
+ * Every day the stall has traded, read back from the host's history.
+ *
+ * The engine keeps only today's `results` in context. Each earlier day is in
+ * the round the team closed, which `getPastState` returns, so the table asks
+ * for those and adds today's from live context. Nothing grows in context as
+ * the days go by, which is what keeps a long session cheap.
+ *
+ * The history changes only when a tick commits or is undone, and both change
+ * `completedTicks`, so that is what the fetch waits on.
+ */
+export default function HistoryPanel() {
+    const { data, settings, completedTicks } = useUserInterfaceData<Context, Settings>();
+    const { getPastState } = useUserInterfaceCallbacks();
+    const { t } = useTranslation();
+    const symbol = settings.ui.CurrencySymbol;
+
+    const [past, setPast] = useState<DayResults[]>([]);
+
+    useEffect(() => {
+        if (completedTicks < 2) {
+            setPast([]);
+            return;
+        }
+        let cancelled = false;
+        getPastState<Context>({ fromTick: 1, toTick: completedTicks, capabilityIds: ['results'] })
+            .then((entries) => {
+                if (!cancelled) setPast(entries.map((entry) => entry.context.results));
+            })
+            // History is a nice-to-have on this screen: a failed read leaves the
+            // table showing today alone rather than an error.
+            .catch(() => {
+                if (!cancelled) setPast([]);
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [completedTicks, getPastState]);
+
+    const byDay = new Map<number, DayResults>();
+    for (const results of [...past, data.results]) {
+        if (results.Day > 0) byDay.set(results.Day, results);
+    }
+    const days = [...byDay.values()].sort((a, b) => a.Day - b.Day);
+
+    if (days.length === 0) {
+        return null;
+    }
+
+    const best = Math.max(...days.map((day) => day.Profit));
+
+    return (
+        <Section title={t('history.title')} hint={t('history.hint')}>
+            <Box sx={{ overflowX: 'auto' }}>
+                <Table size="small">
+                    <TableHead>
+                        <TableRow>
+                            <TableCell>{t('history.day')}</TableCell>
+                            <TableCell>{t('history.weather')}</TableCell>
+                            <TableCell align="right">{t('yesterday.made')}</TableCell>
+                            <TableCell align="right">{t('yesterday.sold')}</TableCell>
+                            <TableCell align="right">{t('yesterday.pouredAway')}</TableCell>
+                            <TableCell align="right">{t('yesterday.turnedAway')}</TableCell>
+                            <TableCell align="right">{t('yesterday.profit')}</TableCell>
+                            <TableCell align="right">{t('yesterday.purse')}</TableCell>
+                        </TableRow>
+                    </TableHead>
+                    <TableBody>
+                        {days.map((day) => {
+                            const totals = totalsOf(day);
+                            return (
+                                <TableRow key={day.Day} data-testid={`day-${day.Day}`}>
+                                    <TableCell>{day.Day}</TableCell>
+                                    <TableCell>
+                                        <Typography variant="body2">
+                                            {t(`weather.${day.Weather}Short`)}
+                                        </Typography>
+                                    </TableCell>
+                                    <TableCell align="right">{count(totals.made)}</TableCell>
+                                    <TableCell align="right">{count(totals.sold)}</TableCell>
+                                    <TableCell align="right">{count(totals.pouredAway)}</TableCell>
+                                    <TableCell align="right">{count(totals.turnedAway)}</TableCell>
+                                    <TableCell
+                                        align="right"
+                                        sx={day.Profit === best ? { fontWeight: 700 } : undefined}
+                                    >
+                                        {money(symbol, day.Profit)}
+                                    </TableCell>
+                                    <TableCell align="right">{money(symbol, day.Purse)}</TableCell>
+                                </TableRow>
+                            );
+                        })}
+                    </TableBody>
+                </Table>
+            </Box>
+        </Section>
+    );
+}
+
+/** The day's lines, added up across the menu. */
+function totalsOf(results: DayResults) {
+    const lines = Object.values(results.Lines);
+    return {
+        made: lines.reduce((sum, line) => sum + line.Made, 0),
+        sold: lines.reduce((sum, line) => sum + line.Sold, 0),
+        pouredAway: lines.reduce((sum, line) => sum + line.PouredAway, 0),
+        turnedAway: lines.reduce((sum, line) => sum + line.TurnedAway, 0),
+    };
+}

package/dist/templates/starter-game/ui/src/MakeRow.tsx

@@ -0,0 +1,129 @@
+import { Box, Chip, IconButton, Slider, Stack, Typography } from '@mui/material';
+import { useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { MenuItem } from '../types';
+import { money } from './format';
+
+type Props = {
+    id: string;
+    item: MenuItem;
+    /** What the game currently holds for this item. */
+    value: number;
+    /** Roughly how many people will want one today. */
+    expected: number;
+    max: number;
+    step: number;
+    currencySymbol: string;
+    /** True when this is the item the reader was put in charge of. */
+    yours: boolean;
+    disabled: boolean;
+    onChange: (next: number) => void;
+};
+
+/**
+ * One line of the menu, and the only thing on this screen that writes.
+ *
+ * It writes its own key and nothing else, so the person looking after the iced
+ * tea and the person looking after the cookies never touch the same field. That
+ * is what makes two people working at once safe here, and it is a decision
+ * about the shape of the state rather than anything clever in this file.
+ *
+ * The slider keeps a local value while it is being dragged and writes once, on
+ * release. Writing on every frame of a drag would put fifty messages on the
+ * wire for one decision, and a broadcast arriving mid-drag would fight the
+ * reader's thumb.
+ */
+export default function MakeRow({
+    id,
+    item,
+    value,
+    expected,
+    max,
+    step,
+    currencySymbol,
+    yours,
+    disabled,
+    onChange,
+}: Props) {
+    const { t } = useTranslation();
+    const [dragging, setDragging] = useState(false);
+    const [draft, setDraft] = useState(value);
+    const draggingRef = useRef(dragging);
+    draggingRef.current = dragging;
+
+    // Follow the game except while this reader is mid-drag, so a team-mate's
+    // change to this item still shows up.
+    useEffect(() => {
+        if (!draggingRef.current) setDraft(value);
+    }, [value]);
+
+    const shown = dragging ? draft : value;
+    const nudge = (by: number) => onChange(Math.max(0, Math.min(max, shown + by)));
+
+    return (
+        <Box data-testid={`make-${id}`}>
+            <Stack
+                direction="row"
+                spacing={1}
+                sx={{ alignItems: 'baseline', justifyContent: 'space-between' }}
+            >
+                <Stack direction="row" spacing={1} sx={{ alignItems: 'baseline' }}>
+                    <Typography variant="subtitle1">{item.Name}</Typography>
+                    {yours && <Chip size="small" color="primary" label={t('make.yours')} />}
+                </Stack>
+                <Typography
+                    variant="h5"
+                    sx={{ fontVariantNumeric: 'tabular-nums' }}
+                    data-testid={`made-${id}`}
+                >
+                    {shown}
+                </Typography>
+            </Stack>
+
+            <Typography variant="caption" color="text.secondary" component="p">
+                {t('make.line', {
+                    price: money(currencySymbol, item.Price),
+                    cost: money(currencySymbol, item.Cost),
+                    expected,
+                })}
+            </Typography>
+
+            <Stack direction="row" spacing={1} sx={{ alignItems: 'center' }}>
+                <IconButton
+                    size="small"
+                    aria-label={t('make.fewer', { name: item.Name })}
+                    disabled={disabled || shown === 0}
+                    onClick={() => nudge(-step)}
+                >
+                    <Typography component="span">−</Typography>
+                </IconButton>
+                <Slider
+                    aria-label={item.Name}
+                    value={shown}
+                    min={0}
+                    max={max}
+                    step={1}
+                    disabled={disabled}
+                    valueLabelDisplay="auto"
+                    onChange={(_, next) => {
+                        setDragging(true);
+                        setDraft(next as number);
+                    }}
+                    onChangeCommitted={(_, next) => {
+                        setDragging(false);
+                        onChange(next as number);
+                    }}
+                />
+                <IconButton
+                    size="small"
+                    aria-label={t('make.more', { name: item.Name })}
+                    disabled={disabled || shown >= max}
+                    onClick={() => nudge(step)}
+                >
+                    <Typography component="span">+</Typography>
+                </IconButton>
+            </Stack>
+        </Box>
+    );
+}