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

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

@@ -0,0 +1,96 @@
+import { Button, Stack, Tooltip, Typography } from '@mui/material';
+import type { TeamLinks } from '@seriousgaming/sdk/ui';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+type Props = {
+    links: TeamLinks | undefined;
+    teamName: string;
+    show: boolean;
+};
+
+/**
+ * The two ways a facilitator gets into a stall: observing, and joining.
+ *
+ * Both are one click. Reading a URL out of a table and typing it into another
+ * tab is the thing a facilitator actually does half a dozen times a session,
+ * and it is the slowest part of running one.
+ *
+ * `target="_blank"` rather than navigating this frame: a session surface owns
+ * the whole canvas, and replacing it with a player's screen would leave the
+ * facilitator with no way back. The host grants `allow-popups` and
+ * `allow-popups-to-escape-sandbox` for exactly this.
+ *
+ * The two links are not the same kind of thing, and the labels say so.
+ * Observing admits nobody: an observer has no participant record and no
+ * presence, so the stall never sees a fourth person appear. Joining is a real
+ * seat at a real stall, which is what you want when you are showing somebody
+ * how it works and not what you want when you are checking on them.
+ */
+export default function TeamDoor({ links, teamName, show }: Props) {
+    const { t } = useTranslation();
+    const [copied, setCopied] = useState(false);
+    const [reveal, setReveal] = useState(false);
+
+    // Empty until the host delivers them, which is one frame rather than never.
+    if (!links || !show) {
+        return null;
+    }
+
+    const copyJoinLink = async () => {
+        // Feature-detected: `clipboard-write` is delegated to this frame, but
+        // Permissions Policy is implemented unevenly and a browser may gate the
+        // write on a gesture it does not think it had. Falling back to showing
+        // the URL is worse than copying and better than a button that does
+        // nothing.
+        try {
+            await navigator.clipboard.writeText(links.joinUrl);
+            setCopied(true);
+            setReveal(false);
+        } catch {
+            setReveal(true);
+        }
+    };
+
+    return (
+        <Stack spacing={0.5}>
+            <Stack direction="row" spacing={1}>
+                <Button
+                    size="small"
+                    variant="outlined"
+                    component="a"
+                    href={links.observeUrl}
+                    target="_blank"
+                    rel="noopener"
+                >
+                    {t('door.observe')}
+                </Button>
+                <Button
+                    size="small"
+                    component="a"
+                    href={links.joinUrl}
+                    target="_blank"
+                    rel="noopener"
+                >
+                    {t('door.join')}
+                </Button>
+                <Tooltip title={t('door.copyHint', { team: teamName })}>
+                    <Button
+                        size="small"
+                        color="inherit"
+                        aria-label={t('door.copy', { team: teamName })}
+                        onClick={() => void copyJoinLink()}
+                        onMouseLeave={() => setCopied(false)}
+                    >
+                        {copied ? t('door.copied') : t('door.copyShort')}
+                    </Button>
+                </Tooltip>
+            </Stack>
+            {reveal && (
+                <Typography variant="caption" sx={{ fontFamily: 'monospace', userSelect: 'all' }}>
+                    {links.joinUrl}
+                </Typography>
+            )}
+        </Stack>
+    );
+}

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

@@ -0,0 +1,8 @@
+/** Display helpers shared by the panels, so one round of a number is decided once. */
+
+export const money = (prefix: string, value: number) =>
+    `${value < 0 ? '-' : ''}${prefix}${Math.abs(Math.round(value)).toLocaleString()}`;
+
+export const percent = (fraction: number) => `${Math.round(fraction * 100)}%`;
+
+export const units = (value: number) => Math.round(value).toLocaleString();

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

@@ -0,0 +1,51 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+const resources = {
+    en: {
+        translation: {
+            session: {
+                waitingRoom: 'Waiting room',
+                waitingRoomHint:
+                    'Holds every player on the holding screen. Nothing about the session changes, so you can park it for a discussion and pick up where the stalls were.',
+                guide: 'Facilitator guide',
+                readOnly: 'This session is read only, so the controls below will be refused.',
+                stalls: 'Stalls',
+                movedOn: '{{movedOn}} of {{total}} have changed their numbers today',
+                team: 'Stall',
+                people: 'People',
+                day: 'Day',
+                making: 'Making',
+                ofCapacity: '{{planned}} of {{capacity}}',
+                status: 'Today',
+                purse: 'In the jar',
+                wayIn: 'Way in',
+                controls: '',
+                unchanged: 'Same as yesterday',
+                changed: 'Changed',
+                undo: 'Undo',
+                notice: 'Notice to the room',
+                noticeHint: 'One note, shown on every stall’s screen and in the waiting room.',
+                noticeLabel: 'Message',
+                send: 'Send',
+            },
+            door: {
+                observe: 'Observe',
+                join: 'Join',
+                copy: 'Copy the join link for {{team}}',
+                copyShort: 'Copy link',
+                copyHint: 'Copy {{team}}’s join link, to hand out or put on a slide',
+                copied: 'Copied',
+            },
+        },
+    },
+};
+
+i18n.use(initReactI18next).init({
+    resources,
+    lng: 'en',
+    fallbackLng: 'en',
+    interpolation: { escapeValue: false },
+});
+
+export default i18n;

package/dist/templates/starter-game/session/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 { SessionUserInterfaceWrapper, useSessionUserInterfaceLocale } from '@seriousgaming/sdk/ui';
+
+import './i18n';
+import i18n from 'i18next';
+import React, { StrictMode, useEffect } from 'react';
+import { createRoot } from 'react-dom/client';
+import { prefixer } from 'stylis';
+
+import App from './App';
+
+// Create RTL cache
+const cacheRtl = createCache({
+    key: 'muirtl',
+    stylisPlugins: [prefixer, rtlPlugin],
+});
+
+const cacheLtr = createCache({
+    key: 'muiltr',
+});
+
+// Wrapper component to sync locale with i18next and setup RTL
+function RootWrapper({ children }: { children: React.ReactNode }) {
+    const { locale } = useSessionUserInterfaceLocale();
+
+    useEffect(() => {
+        const i18nextLocale = locale.split('-')[0];
+        i18n.changeLanguage(i18nextLocale);
+    }, [locale]);
+
+    const isRtl = i18n.dir(locale.split('-')[0]) === 'rtl';
+
+    return <CacheProvider value={isRtl ? cacheRtl : cacheLtr}>{children}</CacheProvider>;
+}
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <SessionUserInterfaceWrapper>
+            <RootWrapper>
+                <App />
+            </RootWrapper>
+        </SessionUserInterfaceWrapper>
+    </StrictMode>
+);

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

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

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

@@ -0,0 +1,135 @@
+// This file is auto-generated from the session user interface's capability definitions.
+// Do not edit this file directly. It will be regenerated on build.
+
+export interface Context {
+    plan: {
+        /**
+         * How many of each menu item to make today, keyed by item id. Keyed rather than a flat set of fields so that two people changing two different items write different keys, and the host's merge keeps both.
+         */
+        Make: {
+            [k: string]: number;
+        };
+    };
+    results: {
+        /**
+         * The day these results are for
+         */
+        Day: number;
+        /**
+         * What the weather actually did
+         */
+        Weather: string;
+        /**
+         * What happened to each menu item, keyed by item id
+         */
+        Lines: {
+            [k: string]: DayLine;
+        };
+        /**
+         * Money in, in pence
+         */
+        Takings: number;
+        /**
+         * Cost of everything made, in pence
+         */
+        Spent: number;
+        /**
+         * Takings less spend, in pence
+         */
+        Profit: number;
+        /**
+         * Everything made so far, in pence
+         */
+        Purse: number;
+    };
+    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 interface DayLine {
+    Made: number;
+    /**
+     * How many people asked for one
+     */
+    Wanted: number;
+    Sold: number;
+    /**
+     * Made and not sold
+     */
+    PouredAway: number;
+    /**
+     * Asked for and not available
+     */
+    TurnedAway: number;
+}
+
+export type TeamContext = Pick<Context, 'plan' | 'results' | 'roles'>;
+
+export type SharedContext = Pick<Context, 'briefing'>;
+
+export type SharedWrites = Pick<Context, 'briefing'>;
+
+export type TeamWrites = Record<string, never>;
+
+import type { SessionData as SurfaceSessionData } from '@seriousgaming/sdk/ui';
+
+export type SessionData = SurfaceSessionData<TeamContext, SharedContext>;
+
+export interface Settings {
+    menu: {
+        /**
+         * How many items the stall can make in a day, across the whole menu
+         */
+        Capacity: number;
+        Menu: Menu;
+    };
+    session: {
+        /**
+         * Whether the session surface offers the per-team join and observe links
+         */
+        ShowJoinLinks: boolean;
+        /**
+         * Symbol for money on the session surface. Prices are the same numbers whichever symbol is shown
+         */
+        CurrencySymbol: '£' | '$' | '€';
+    };
+}
+/**
+ * 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 { SessionUserInterfaceCallbacks } from '@seriousgaming/sdk';
+
+export type Callbacks = Pick<SessionUserInterfaceCallbacks, never>;

package/dist/templates/starter-game/settings/engine/settings.sdk.json

@@ -0,0 +1,50 @@
+{
+    "definition": {
+        "settingsSchema": {
+            "type": "object",
+            "properties": {
+                "UsualDemand": {
+                    "title": "Usual demand",
+                    "description": "How many people want each menu item on an ordinary cloudy day, keyed by item id. Kept apart from the menu because only the engine reads it: a surface that could see it would be showing the answer. An item on the menu with no entry here has no custom at all, so its forecast reads 0 and nobody buys one.",
+                    "type": "object",
+                    "default": {
+                        "lemonade": 55,
+                        "icedtea": 30,
+                        "cookies": 20
+                    },
+                    "additionalProperties": {
+                        "type": "integer",
+                        "description": "People a day who want this item when it is cloudy",
+                        "minimum": 0,
+                        "maximum": 1000
+                    }
+                },
+                "SunnyPull": {
+                    "title": "Sunny day pull",
+                    "description": "How much busier a sunny day is than a cloudy one, as a multiplier on usual demand. 1.3 brings 30% more people",
+                    "type": "number",
+                    "default": 1.3,
+                    "minimum": 0,
+                    "maximum": 5
+                },
+                "RainyPull": {
+                    "title": "Rainy day pull",
+                    "description": "How much quieter a rainy day is than a cloudy one, as a multiplier on usual demand. 0.65 brings 35% fewer people, and above 1 makes rain busier",
+                    "type": "number",
+                    "default": 0.65,
+                    "minimum": 0,
+                    "maximum": 5
+                },
+                "Variation": {
+                    "title": "Day-to-day variation",
+                    "description": "How far a day can land either side of its forecast, as a fraction. 0.2 lands within 20% of it, and 0 makes every forecast exact",
+                    "type": "number",
+                    "default": 0.2,
+                    "minimum": 0,
+                    "maximum": 1
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+}

package/dist/templates/starter-game/settings/menu/settings.sdk.json

@@ -0,0 +1,78 @@
+{
+    "definition": {
+        "settingsSchema": {
+            "type": "object",
+            "properties": {
+                "Capacity": {
+                    "title": "Daily capacity",
+                    "description": "How many items the stall can make in a day, across the whole menu",
+                    "type": "integer",
+                    "default": 120,
+                    "minimum": 1,
+                    "maximum": 1000
+                },
+                "Menu": {
+                    "title": "Menu",
+                    "description": "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.",
+                    "type": "object",
+                    "default": {
+                        "lemonade": {
+                            "Name": "Lemonade",
+                            "Order": 1,
+                            "Cost": 15,
+                            "Price": 50
+                        },
+                        "icedtea": {
+                            "Name": "Iced tea",
+                            "Order": 2,
+                            "Cost": 20,
+                            "Price": 60
+                        },
+                        "cookies": {
+                            "Name": "Cookies",
+                            "Order": 3,
+                            "Cost": 25,
+                            "Price": 70
+                        }
+                    },
+                    "additionalProperties": {
+                        "title": "MenuItem",
+                        "type": "object",
+                        "properties": {
+                            "Name": {
+                                "title": "Name",
+                                "description": "What the item is called on every screen",
+                                "type": "string",
+                                "minLength": 1,
+                                "maxLength": 40
+                            },
+                            "Order": {
+                                "title": "Menu position",
+                                "description": "Where it sits on the menu, so every screen lists it in the same order. 1 comes first",
+                                "type": "integer",
+                                "minimum": 1
+                            },
+                            "Cost": {
+                                "title": "Cost",
+                                "description": "Cost to make one, in pence",
+                                "type": "integer",
+                                "minimum": 0,
+                                "maximum": 10000
+                            },
+                            "Price": {
+                                "title": "Price",
+                                "description": "Sale price, in pence",
+                                "type": "integer",
+                                "minimum": 0,
+                                "maximum": 10000
+                            }
+                        },
+                        "required": ["Name", "Order", "Cost", "Price"],
+                        "additionalProperties": false
+                    }
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+}

package/dist/templates/starter-game/settings/session/settings.sdk.json

@@ -0,0 +1,23 @@
+{
+    "definition": {
+        "settingsSchema": {
+            "type": "object",
+            "properties": {
+                "ShowJoinLinks": {
+                    "title": "Show join links",
+                    "description": "Whether the session surface offers the per-team join and observe links",
+                    "type": "boolean",
+                    "default": true
+                },
+                "CurrencySymbol": {
+                    "title": "Currency symbol",
+                    "description": "Symbol for money on the session surface. Prices are the same numbers whichever symbol is shown",
+                    "type": "string",
+                    "default": "£",
+                    "enum": ["£", "$", "€"]
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+}

package/dist/templates/starter-game/settings/ui/settings.sdk.json

@@ -0,0 +1,25 @@
+{
+    "definition": {
+        "settingsSchema": {
+            "type": "object",
+            "properties": {
+                "Step": {
+                    "title": "Slider step",
+                    "description": "How many items each nudge of a slider adds to or takes off the plan",
+                    "type": "integer",
+                    "default": 5,
+                    "minimum": 1,
+                    "maximum": 50
+                },
+                "CurrencySymbol": {
+                    "title": "Currency symbol",
+                    "description": "Symbol for money on the participant surface. Prices are the same numbers whichever symbol is shown",
+                    "type": "string",
+                    "default": "£",
+                    "enum": ["£", "$", "€"]
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+}

package/dist/templates/starter-game/test-setup.ts

@@ -0,0 +1,7 @@
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
+
+// RTL does not auto-detect Vitest without globals mode enabled,
+// so we explicitly clean up the DOM after each test.
+afterEach(cleanup);