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

package/dist/templates/starter-game/ui/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>
+    );
+}

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

@@ -0,0 +1,49 @@
+import { ToggleButton, ToggleButtonGroup } from '@mui/material';
+import { useUserInterfaceCallbacks, useUserInterfaceThemePreference } from '@seriousgaming/sdk/ui';
+import { useTranslation } from 'react-i18next';
+
+const OPTIONS = [
+    { value: 'light', glyph: '☀' },
+    { value: 'dark', glyph: '☾' },
+    { value: 'system', glyph: 'A' },
+] as const;
+
+/**
+ * Light, dark, or whatever the device says.
+ *
+ * The preference is the host's, not this surface's: `setThemePreference` tells
+ * the host, the host decides, and the new palette comes back through
+ * `useUserInterfaceTheme` like any other state. So the whole session follows,
+ * including the facilitator's screen and the chrome around this frame, rather
+ * than one iframe going dark on its own.
+ */
+export default function ThemeToggle() {
+    const preference = useUserInterfaceThemePreference();
+    const { setThemePreference } = useUserInterfaceCallbacks();
+    const { t } = useTranslation();
+
+    return (
+        <ToggleButtonGroup
+            size="small"
+            exclusive
+            value={preference}
+            aria-label={t('theme.label')}
+            onChange={(_, next) => {
+                // Null when the pressed button was already selected. Keeping the
+                // current value means the control never lands in no state at all.
+                if (next) setThemePreference(next);
+            }}
+        >
+            {OPTIONS.map((option) => (
+                <ToggleButton
+                    key={option.value}
+                    value={option.value}
+                    aria-label={t(`theme.${option.value}`)}
+                    sx={{ px: 1.25, py: 0.25, lineHeight: 1 }}
+                >
+                    {option.glyph}
+                </ToggleButton>
+            ))}
+        </ToggleButtonGroup>
+    );
+}

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

@@ -0,0 +1,179 @@
+import {
+    createMockParticipant,
+    mergingSetData,
+    renderUserInterface,
+} from '@seriousgaming/sdk/ui/testing';
+import { fireEvent, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Context } from '../types';
+import './i18n';
+import { baseSettings, baseContext } from './test-helpers';
+import TodayPanel from './TodayPanel';
+
+const ada = createMockParticipant({ id: 'participant-1', name: 'Ada' });
+
+const setSlider = (name: string, value: number) => {
+    const slider = screen.getByRole('slider', { name });
+    fireEvent.change(slider, { target: { value: String(value) } });
+    // The row writes on release, not on every frame of a drag.
+    fireEvent.mouseUp(slider);
+};
+
+describe('changing how many to make', () => {
+    it('sends only the item that changed', () => {
+        const setData = vi.fn();
+        renderUserInterface(<TodayPanel />, {
+            data: baseContext,
+            settings: baseSettings,
+            participant: ada,
+            setData,
+        });
+
+        fireEvent.click(screen.getByRole('button', { name: 'Make more Iced tea' }));
+
+        // Only `icedtea`. Never the whole `Make` map: that would re-send the
+        // lemonade and the cookies from a snapshot that may already be stale.
+        expect(setData).toHaveBeenCalledWith({ plan: { Make: { icedtea: 25 } } });
+    });
+
+    it('nudges by the configured step', () => {
+        const setData = vi.fn();
+        renderUserInterface(<TodayPanel />, {
+            data: baseContext,
+            settings: { ...baseSettings, ui: { ...baseSettings.ui, Step: 1 } },
+            participant: ada,
+            setData,
+        });
+
+        fireEvent.click(screen.getByRole('button', { name: 'Make less Lemonade' }));
+
+        expect(setData).toHaveBeenCalledWith({ plan: { Make: { lemonade: 39 } } });
+    });
+
+    /**
+     * The whole reason the plan is a map keyed by item rather than three fields
+     * on one object. This harness merges the way the host does, so a payload
+     * that reached too wide would show up here as a team-mate's number being
+     * undone.
+     */
+    it('leaves the items somebody else is looking after alone', () => {
+        let data: Context = baseContext;
+        const setData = mergingSetData<Context>((update) => {
+            data = update(data);
+        });
+
+        renderUserInterface(<TodayPanel />, {
+            data,
+            settings: baseSettings,
+            participant: ada,
+            setData,
+        });
+
+        // Grace has just taken the cookies to 30, and it has landed.
+        data = { ...data, plan: { Make: { ...data.plan.Make, cookies: 30 } } };
+
+        // Ada, who never saw that, changes her own item.
+        setSlider('Lemonade', 55);
+
+        expect(data.plan.Make).toEqual({ lemonade: 55, icedtea: 20, cookies: 30 });
+    });
+
+    it('writes the number the slider was left on', () => {
+        const setData = vi.fn();
+        renderUserInterface(<TodayPanel />, {
+            data: baseContext,
+            settings: baseSettings,
+            participant: ada,
+            setData,
+        });
+
+        setSlider('Lemonade', 70);
+
+        expect(setData).toHaveBeenLastCalledWith({ plan: { Make: { lemonade: 70 } } });
+    });
+});
+
+describe('the stall’s capacity', () => {
+    it('says how much room is left', () => {
+        renderUserInterface(<TodayPanel />, {
+            data: baseContext,
+            settings: baseSettings,
+            participant: ada,
+        });
+
+        expect(screen.getByTestId('capacity')).toHaveTextContent('70 of 120');
+        expect(screen.getByText(/Room for 50 more/)).toBeInTheDocument();
+    });
+
+    // A merged plan can exceed the stall even though no one write did, so the
+    // surface has to be able to render that state rather than assume it away.
+    it('says so when the plan is over what the stall can make', () => {
+        renderUserInterface(<TodayPanel />, {
+            data: {
+                ...baseContext,
+                plan: { Make: { lemonade: 90, icedtea: 40, cookies: 20 } },
+            },
+            settings: baseSettings,
+            participant: ada,
+        });
+
+        expect(screen.getByTestId('capacity')).toHaveTextContent('150 of 120');
+        expect(screen.getByText(/30 more than the stall can make/)).toBeInTheDocument();
+    });
+});
+
+describe('the menu', () => {
+    it('lists in the order the game gave, not whatever order the keys arrived in', () => {
+        renderUserInterface(<TodayPanel />, {
+            data: baseContext,
+            settings: baseSettings,
+            participant: ada,
+        });
+
+        const names = screen
+            .getAllByRole('slider')
+            .map((slider) => slider.getAttribute('aria-label'));
+        expect(names).toEqual(['Lemonade', 'Iced tea', 'Cookies']);
+    });
+
+    it('marks the item this participant looks after', () => {
+        renderUserInterface(<TodayPanel />, {
+            data: {
+                ...baseContext,
+                roles: { LooksAfter: { 'participant-1': 'cookies' } },
+            },
+            settings: baseSettings,
+            participant: ada,
+        });
+
+        expect(screen.getByTestId('make-cookies')).toHaveTextContent('Yours');
+        expect(screen.getByTestId('make-lemonade')).not.toHaveTextContent('Yours');
+    });
+
+    it('shows what each one earns and costs, and what today looks like', () => {
+        renderUserInterface(<TodayPanel />, {
+            data: baseContext,
+            settings: baseSettings,
+            participant: ada,
+        });
+
+        expect(screen.getByTestId('make-lemonade')).toHaveTextContent(
+            '£0.50 each, costs £0.15 to make. About 72 people will want one today.'
+        );
+    });
+});
+
+describe('observing', () => {
+    it('says so, and offers nothing to change', () => {
+        renderUserInterface(<TodayPanel />, {
+            data: baseContext,
+            settings: baseSettings,
+            viewerRole: 'observer',
+        });
+
+        expect(screen.getByText(/watching this stall/)).toBeInTheDocument();
+        expect(screen.getByRole('slider', { name: 'Lemonade' })).toBeDisabled();
+        expect(screen.getByRole('button', { name: 'Make more Lemonade' })).toBeDisabled();
+    });
+});

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

@@ -0,0 +1,92 @@
+import { Alert, Chip, LinearProgress, Stack, Typography } from '@mui/material';
+import { useUserInterfaceData, useUserInterfaceParticipant } from '@seriousgaming/sdk/ui';
+import { useTranslation } from 'react-i18next';
+
+import type { Settings, Context } from '../types';
+import MakeRow from './MakeRow';
+import { menuOf, totalPlanned } from './menu';
+import Section from './Section';
+import { useWrite } from './writes';
+
+/**
+ * What the stall is making today.
+ *
+ * The only screen that writes, and it writes one key per line of the menu. Two
+ * people changing two different things write two different keys, and the host's
+ * merge keeps both: no locks, no turn-taking, and nothing to explain to the
+ * room. The capacity they share is the one thing that can still go wrong, and
+ * `validators/capacity` is what catches it.
+ */
+export default function TodayPanel() {
+    const { data, settings, setData } = useUserInterfaceData<Context, Settings>();
+    const participant = useUserInterfaceParticipant();
+    const { run, pending } = useWrite();
+    const { t } = useTranslation();
+
+    const menu = menuOf(settings.menu);
+    const planned = totalPlanned(data.plan.Make);
+    const room = settings.menu.Capacity - planned;
+    const yours = participant ? data.roles.LooksAfter[participant.id] : undefined;
+
+    const setCount = (id: string, next: number) => {
+        // Only this item's key. Never `{ ...data.plan.Make, [id]: next }`: that
+        // re-sends every other item from a snapshot that may already be stale,
+        // and would undo whatever a team-mate changed a moment ago.
+        void run(() => setData({ plan: { Make: { [id]: next } } }), `make:${id}`);
+    };
+
+    return (
+        <Section
+            title={t('today.title')}
+            hint={t(`weather.${data.weather.Today}`)}
+            action={
+                <Chip
+                    color={room < 0 ? 'error' : room === 0 ? 'success' : 'default'}
+                    label={t('today.capacity', { planned, capacity: settings.menu.Capacity })}
+                    data-testid="capacity"
+                />
+            }
+        >
+            <LinearProgress
+                variant="determinate"
+                color={room < 0 ? 'error' : 'primary'}
+                value={Math.min(100, (planned / Math.max(1, settings.menu.Capacity)) * 100)}
+                sx={{ mb: 3 }}
+            />
+
+            {!participant && (
+                <Alert severity="info" sx={{ mb: 3 }}>
+                    {t('today.observing')}
+                </Alert>
+            )}
+
+            <Stack spacing={3}>
+                {menu.map(({ id, item }) => (
+                    <MakeRow
+                        key={id}
+                        id={id}
+                        item={item}
+                        value={data.plan.Make[id] ?? 0}
+                        expected={data.weather.Expected[id] ?? 0}
+                        // One item can fill the stall on its own, so the cap on
+                        // a single row is the stall's. The rule about the total
+                        // is the validator's, because only the merged plan
+                        // shows it.
+                        max={settings.menu.Capacity}
+                        step={settings.ui.Step}
+                        currencySymbol={settings.ui.CurrencySymbol}
+                        yours={yours === id}
+                        disabled={!participant || pending}
+                        onChange={(next) => setCount(id, next)}
+                    />
+                ))}
+            </Stack>
+
+            <Typography variant="body2" color="text.secondary" sx={{ mt: 3 }}>
+                {room < 0
+                    ? t('today.over', { over: -room })
+                    : t('today.room', { room, capacity: settings.menu.Capacity })}
+            </Typography>
+        </Section>
+    );
+}

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

@@ -0,0 +1,142 @@
+import {
+    Alert,
+    Box,
+    Stack,
+    Table,
+    TableBody,
+    TableCell,
+    TableHead,
+    TableRow,
+    Typography,
+} from '@mui/material';
+import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import { useTranslation } from 'react-i18next';
+
+import type { Settings, Context } from '../types';
+import { count, money } from './format';
+import { menuOf } from './menu';
+import Section from './Section';
+
+function Stat({
+    id,
+    label,
+    value,
+    tone,
+}: {
+    id: string;
+    label: string;
+    value: string;
+    tone?: 'good' | 'bad';
+}) {
+    return (
+        <Box sx={{ minWidth: 110 }} data-testid={`stat-${id}`}>
+            <Typography variant="overline" color="text.secondary" component="p">
+                {label}
+            </Typography>
+            <Typography
+                variant="h6"
+                component="p"
+                sx={{ fontVariantNumeric: 'tabular-nums' }}
+                color={tone === 'good' ? 'success.main' : tone === 'bad' ? 'error.main' : undefined}
+            >
+                {value}
+            </Typography>
+        </Box>
+    );
+}
+
+/** How the last day actually went, item by item. */
+export default function YesterdayPanel() {
+    const { data, settings } = useUserInterfaceData<Context, Settings>();
+    const { t } = useTranslation();
+    const symbol = settings.ui.CurrencySymbol;
+    const results = data.results;
+
+    if (results.Day === 0) {
+        return (
+            <Section title={t('yesterday.title')} hint={t('yesterday.none')}>
+                <Alert severity="info">{t('yesterday.firstDay')}</Alert>
+            </Section>
+        );
+    }
+
+    const pouredAway = Object.values(results.Lines).reduce((sum, l) => sum + l.PouredAway, 0);
+    const turnedAway = Object.values(results.Lines).reduce((sum, l) => sum + l.TurnedAway, 0);
+
+    return (
+        <Section
+            title={t('yesterday.title')}
+            hint={t('yesterday.on', {
+                day: results.Day,
+                weather: t(`weather.${results.Weather}Short`),
+            })}
+        >
+            <Stack direction="row" spacing={3} useFlexGap sx={{ flexWrap: 'wrap', mb: 3 }}>
+                <Stat
+                    id="takings"
+                    label={t('yesterday.takings')}
+                    value={money(symbol, results.Takings)}
+                />
+                <Stat
+                    id="spent"
+                    label={t('yesterday.spent')}
+                    value={money(symbol, results.Spent)}
+                />
+                <Stat
+                    id="profit"
+                    label={t('yesterday.profit')}
+                    value={money(symbol, results.Profit)}
+                    tone={results.Profit >= 0 ? 'good' : 'bad'}
+                />
+                <Stat
+                    id="purse"
+                    label={t('yesterday.purse')}
+                    value={money(symbol, results.Purse)}
+                />
+                <Stat
+                    id="pouredaway"
+                    label={t('yesterday.pouredAway')}
+                    value={count(pouredAway)}
+                    tone={pouredAway > 0 ? 'bad' : undefined}
+                />
+                <Stat
+                    id="turnedaway"
+                    label={t('yesterday.turnedAway')}
+                    value={count(turnedAway)}
+                    tone={turnedAway > 0 ? 'bad' : undefined}
+                />
+            </Stack>
+
+            <Box sx={{ overflowX: 'auto' }}>
+                <Table size="small">
+                    <TableHead>
+                        <TableRow>
+                            <TableCell>{t('yesterday.item')}</TableCell>
+                            <TableCell align="right">{t('yesterday.made')}</TableCell>
+                            <TableCell align="right">{t('yesterday.wanted')}</TableCell>
+                            <TableCell align="right">{t('yesterday.sold')}</TableCell>
+                            <TableCell align="right">{t('yesterday.pouredAway')}</TableCell>
+                            <TableCell align="right">{t('yesterday.turnedAway')}</TableCell>
+                        </TableRow>
+                    </TableHead>
+                    <TableBody>
+                        {menuOf(settings.menu).map(({ id, item }) => {
+                            const line = results.Lines[id];
+                            if (!line) return null;
+                            return (
+                                <TableRow key={id} data-testid={`line-${id}`}>
+                                    <TableCell>{item.Name}</TableCell>
+                                    <TableCell align="right">{count(line.Made)}</TableCell>
+                                    <TableCell align="right">{count(line.Wanted)}</TableCell>
+                                    <TableCell align="right">{count(line.Sold)}</TableCell>
+                                    <TableCell align="right">{count(line.PouredAway)}</TableCell>
+                                    <TableCell align="right">{count(line.TurnedAway)}</TableCell>
+                                </TableRow>
+                            );
+                        })}
+                    </TableBody>
+                </Table>
+            </Box>
+        </Section>
+    );
+}

package/dist/templates/starter-game/ui/src/format.ts

@@ -0,0 +1,12 @@
+/**
+ * Display helpers shared by the panels.
+ *
+ * Money is held in pence everywhere, so the sums stay in whole numbers and
+ * nothing accumulates a rounding error over ten days. It becomes pounds here,
+ * at the edge, and nowhere else.
+ */
+
+export const money = (symbol: string, pence: number) =>
+    `${pence < 0 ? '-' : ''}${symbol}${(Math.abs(pence) / 100).toFixed(2)}`;
+
+export const count = (value: number) => Math.round(value).toLocaleString();

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

@@ -0,0 +1,95 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+/**
+ * Every string on the surface lives here, including the ones nobody expects to
+ * translate. A game that reaches a second locale by hunting for hard-coded
+ * strings finds about two thirds of them.
+ *
+ * The host tells the surface which locale the session is in, and `main.tsx`
+ * hands that to i18next. Adding a locale is a key in `resources` plus an entry
+ * in `supportedLocales` in the manifest.
+ */
+const resources = {
+    en: {
+        translation: {
+            shell: {
+                untitledTeam: 'Your stall',
+                looksAfter: 'You look after the {{item}}',
+                day: 'Day {{day}}',
+                processing: 'The day is being played out',
+                briefing: 'Notice',
+                writeFailed: 'That did not reach the stall. Try again.',
+                weekOver: 'The week is over. Nothing left to open.',
+                countedNextDay: 'The day turned as you changed that, so it counts for day {{day}}.',
+            },
+            weather: {
+                sunny: 'Sunny today. It is going to be busy.',
+                cloudy: 'Cloudy today. An ordinary sort of day.',
+                rainy: 'Rain today. Not many people about.',
+                sunnyShort: 'Sunny',
+                cloudyShort: 'Cloudy',
+                rainyShort: 'Rainy',
+            },
+            day: {
+                making: 'Making {{planned}} of a possible {{capacity}}',
+                ready: 'Open up, and day {{day}} plays out',
+                tooMany: 'Take something off before you open up',
+                nothing: 'Decide what to make first',
+                open: 'Open the stall',
+            },
+            today: {
+                title: 'What shall we make today?',
+                capacity: '{{planned}} of {{capacity}}',
+                room: 'Room for {{room}} more. The stall can make {{capacity}} things in a day.',
+                over: 'That is {{over}} more than the stall can make. Somebody needs to take some off.',
+                observing: 'You are watching this stall rather than working on it.',
+            },
+            make: {
+                yours: 'Yours',
+                line: '{{price}} each, costs {{cost}} to make. About {{expected}} people will want one today.',
+                more: 'Make more {{name}}',
+                fewer: 'Make less {{name}}',
+            },
+            yesterday: {
+                title: 'How yesterday went',
+                on: 'Day {{day}}, {{weather}}',
+                none: 'Nothing sold yet',
+                firstDay: 'Set your numbers, and the stall opens when the facilitator says so.',
+                item: 'Item',
+                made: 'Made',
+                wanted: 'Wanted',
+                sold: 'Sold',
+                pouredAway: 'Poured away',
+                turnedAway: 'Turned away',
+                takings: 'Took',
+                spent: 'Spent',
+                profit: 'Made',
+                purse: 'In the jar',
+            },
+            history: {
+                title: 'Every day so far',
+                hint: 'What you made, what people wanted, and what was left.',
+                day: 'Day',
+                weather: 'Weather',
+            },
+            theme: {
+                label: 'Light or dark',
+                light: 'Light',
+                dark: 'Dark',
+                system: 'Match my device',
+            },
+        },
+    },
+};
+
+i18n.use(initReactI18next).init({
+    resources,
+    lng: 'en',
+    fallbackLng: 'en',
+    interpolation: {
+        escapeValue: false,
+    },
+});
+
+export default i18n;

package/dist/templates/starter-game/ui/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/ui/src/menu.ts

@@ -0,0 +1,18 @@
+import type { Context, MenuItem, Settings } from '../types';
+
+export type MenuRow = { id: string; item: MenuItem };
+
+/**
+ * The menu, in the order the game gave it.
+ *
+ * Every screen lists the items the same way round. Sorting on a declared
+ * `Order` rather than trusting object key order means a menu that arrives from
+ * a scenario, or through JSON, still reads the same.
+ */
+export const menuOf = (menu: Settings['menu']): MenuRow[] =>
+    Object.entries(menu.Menu)
+        .map(([id, item]) => ({ id, item }))
+        .sort((a, b) => a.item.Order - b.item.Order);
+
+export const totalPlanned = (make: Context['plan']['Make']) =>
+    Object.values(make).reduce((sum, value) => sum + value, 0);