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

package/dist/docs/api/deck.md

@@ -0,0 +1,386 @@
+<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/deck`. Edit those, not this file. -->
+
+# `@seriousgaming/deck`
+
+Every export of `@seriousgaming/deck`, with the declaration it is published with. Anything tagged `@internal` is left out: it ships in the declarations, but is not part of the supported API and may change without a major release. For how the pieces fit together, see the [API reference](./index.md) and the guides it links to.
+
+## Functions
+
+### Bullets
+
+A bulleted or numbered list. Exports as an editable PowerPoint list.
+
+```ts
+function Bullets(props: BulletsProps): import('react').JSX.Element;
+```
+
+### Chart
+
+A bar or line chart drawn in the brand's colours.
+
+```ts
+function Chart(props: ChartProps): import('react').JSX.Element;
+```
+
+### Deck
+
+A presentation: one slide at a time, scaled to fit its container, driven by keyboard (see `useDeckKeys`), clicker, click or swipe.
+
+```ts
+function Deck(props: DeckProps): import('react').JSX.Element;
+```
+
+### Heading
+
+A heading in the brand's heading font. Exports as an editable text box.
+
+```ts
+function Heading(props: HeadingProps): import('react').JSX.Element;
+```
+
+### Image
+
+```ts
+function Image(props: ImageProps): import('react').JSX.Element;
+```
+
+### readableOn
+
+Black or white, whichever reads better on `color` (WCAG relative luminance).
+
+```ts
+function readableOn(color: string): string;
+```
+
+### resolveBrand
+
+Fill in whatever a partial brand leaves out from `defaultBrand`.
+
+```ts
+function resolveBrand(brand: Partial<Brand> | undefined): Brand;
+```
+
+### Slide
+
+One slide, laid out on a fixed 1920 by 1080 canvas.
+
+```ts
+function Slide(props: SlideProps): import('react').JSX.Element;
+```
+
+### Step
+
+Content revealed by a click.
+
+```ts
+function Step(props: StepProps): import('react').JSX.Element;
+```
+
+### Table
+
+A table with a branded header row. Exports as an editable PowerPoint table.
+
+```ts
+function Table(props: TableProps): import('react').JSX.Element;
+```
+
+### Text
+
+Body copy. Inline formatting (`<strong>`, `<em>`, styled spans) survives export.
+
+```ts
+function Text(props: TextProps): import('react').JSX.Element;
+```
+
+### useBrand
+
+The deck's resolved brand, for components that draw in its colours.
+
+```ts
+function useBrand(): Brand;
+```
+
+### useDeck
+
+Where the deck is, and how to move it. Only inside a `Deck`.
+
+```ts
+function useDeck(): DeckState;
+```
+
+### useSlide
+
+The slide this component sits on: how far it is built, and whether it is a live or static render. Custom animations read `step` and `mode` from here, and should show their final state whenever `mode` is `static`.
+
+```ts
+function useSlide(): SlideState;
+```
+
+### useStepVisible
+
+Whether click `at` has been reached on this slide, registering it as one of the slide's steps. For a custom animation that wants to build with clicks without wrapping itself in a `Step`.
+
+```ts
+function useStepVisible(at: number): boolean;
+```
+
+## Constants
+
+### ALL_STEPS
+
+A step value meaning 'everything on the slide is shown'.
+
+```ts
+const ALL_STEPS: number;
+```
+
+### defaultBrand
+
+```ts
+const defaultBrand: Brand;
+```
+
+### nativeText
+
+Marks any element of your own as native PowerPoint text, so it exports as an editable text box rather than as part of the slide's picture: `<div {...nativeText}>...</div>`.
+
+```ts
+const nativeText: {
+    readonly 'data-deck-native': 'text';
+};
+```
+
+### SLIDE_HEIGHT
+
+```ts
+const SLIDE_HEIGHT = 1080;
+```
+
+### SLIDE_WIDTH
+
+Every slide is laid out on this canvas and scaled to fit wherever it is shown.
+
+```ts
+const SLIDE_WIDTH = 1920;
+```
+
+## Interfaces
+
+### Brand
+
+What a deck is dressed in.
+
+```ts
+interface Brand {
+    colors: {
+        primary: string;
+        secondary: string;
+        background: string;
+        surface: string;
+        text: string;
+        muted: string;
+    };
+    fonts: {
+        heading: string;
+        body: string;
+    };
+}
+```
+
+### BulletsProps
+
+```ts
+interface BulletsProps extends TextBase {
+    items: ReactNode[];
+    ordered?: boolean;
+    stepped?: boolean;
+    stepFrom?: number;
+    animation?: StepAnimation;
+}
+```
+
+### ChartProps
+
+```ts
+interface ChartProps {
+    type: 'bar' | 'line';
+    categories: string[];
+    series: ChartSeriesInput[];
+    showValues?: boolean;
+    showLegend?: boolean;
+    valueFormat?: ValueFormat;
+    locale?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+```
+
+### ChartSeriesInput
+
+```ts
+interface ChartSeriesInput {
+    name: string;
+    values: (number | null)[];
+    color?: string;
+}
+```
+
+### DeckProps
+
+```ts
+interface DeckProps {
+    children: ReactNode;
+    brand?: Partial<Brand>;
+    title?: string;
+    dir?: 'ltr' | 'rtl';
+    lang?: string;
+    transition?: Transition;
+    controls?: boolean;
+    clickToAdvance?: boolean;
+    exportFormats?: ExportFormat[];
+    startAt?: string | number;
+    rememberAs?: string;
+    onSlideChange?: (slideIndex: number) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+```
+
+### DeckState
+
+```ts
+interface DeckState {
+    slideIndex: number;
+    slideCount: number;
+    step: number;
+    next: () => void;
+    prev: () => void;
+    goTo: (slideIndex: number, step?: number) => void;
+}
+```
+
+### HeadingProps
+
+```ts
+interface HeadingProps extends TextBase {
+    level?: 1 | 2 | 3;
+}
+```
+
+### ImageProps
+
+```ts
+interface ImageProps {
+    src: string;
+    alt: string;
+    fit?: 'contain' | 'cover';
+    className?: string;
+    style?: CSSProperties;
+}
+```
+
+### SlideProps
+
+```ts
+interface SlideProps {
+    children?: ReactNode;
+    transition?: Transition;
+    notes?: string;
+    background?: string;
+    className?: string;
+    style?: CSSProperties;
+    id?: string;
+}
+```
+
+### SlideState
+
+```ts
+interface SlideState {
+    index: number;
+    mode: RenderMode;
+    step: number;
+    isActive: boolean;
+    dir: 'ltr' | 'rtl';
+    registerStep: (at: number) => () => void;
+    registerNotes: (notes: string | undefined) => void;
+    defaultTransition: Transition;
+    direction: 'forward' | 'backward';
+}
+```
+
+### StepProps
+
+```ts
+interface StepProps {
+    at: number;
+    animation?: StepAnimation;
+    children?: ReactNode;
+    as?: ElementType;
+    className?: string;
+    style?: CSSProperties;
+}
+```
+
+### TableProps
+
+```ts
+interface TableProps {
+    columns: ReactNode[];
+    rows: ReactNode[][];
+    align?: ('start' | 'center' | 'end')[];
+    className?: string;
+    style?: CSSProperties;
+}
+```
+
+### TextProps
+
+```ts
+interface TextProps extends TextBase {
+    as?: ElementType;
+    variant?: 'body' | 'lead' | 'caption';
+}
+```
+
+### ValueFormat
+
+```ts
+interface ValueFormat {
+    style?: 'decimal' | 'currency' | 'percent';
+    currency?: string;
+    maximumFractionDigits?: number;
+}
+```
+
+## Types
+
+### ExportFormat
+
+```ts
+type ExportFormat = 'pdf' | 'pptx' | 'png';
+```
+
+### RenderMode
+
+How a slide is being rendered.
+
+```ts
+type RenderMode = 'live' | 'static';
+```
+
+### StepAnimation
+
+How a step appears when it is revealed.
+
+```ts
+type StepAnimation = 'fade' | 'fade-up' | 'fade-left' | 'zoom' | 'blur' | 'none';
+```
+
+### Transition
+
+How a slide arrives when the presenter moves onto it.
+
+```ts
+type Transition = 'none' | 'fade' | 'slide' | 'zoom' | 'rise';
+```

package/dist/docs/api/index.md

@@ -0,0 +1,67 @@
+<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk`, `@seriousgaming/deck` and `@seriousgaming/sdk-tools/client`, and `sdk-tools/docs-partials/api/`. Edit those, not this file. -->
+
+# API reference
+
+Every type, function, hook and component your game imports, one page per entry point. Each page is generated from the published declarations and their documentation, so it always matches the release it ships in.
+
+| Entry point                                                | Exports                                                        |
+| ---------------------------------------------------------- | -------------------------------------------------------------- |
+| [`@seriousgaming/sdk`](./sdk.md)                           | 10 functions, 2 classes, 94 interfaces, 46 types               |
+| [`@seriousgaming/sdk/ui`](./sdk-ui.md)                     | 44 functions, 3 classes, 37 constants, 18 interfaces, 35 types |
+| [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md)     | 11 functions, 6 types                                          |
+| [`@seriousgaming/sdk/testing`](./sdk-testing.md)           | 4 functions, 4 constants, 7 types                              |
+| [`@seriousgaming/sdk/projection`](./sdk-projection.md)     | 1 constant, 8 interfaces, 3 types                              |
+| [`@seriousgaming/sdk/commands`](./sdk-commands.md)         | 3 interfaces, 5 types                                          |
+| [`@seriousgaming/sdk/e2e`](./sdk-e2e.md)                   | 6 functions, 1 constant, 4 interfaces, 5 types                 |
+| [`@seriousgaming/deck`](./deck.md)                         | 15 functions, 5 constants, 14 interfaces, 4 types              |
+| [`@seriousgaming/sdk-tools/client`](./sdk-tools-client.md) | 4 functions, 1 class, 10 interfaces, 11 types                  |
+
+## Which entry point to import from
+
+- **`@seriousgaming/sdk`**: the types logic is written against (`RunFunction`, `InitializationFunction`, `LogicResult`, the endpoint, hook, validator and tick controller signatures, `SignatureCallbacks`, `TimerState`) and the few runtime helpers logic may call
+- **`@seriousgaming/sdk/ui`**: the React wrappers and hooks every surface uses (`useUserInterfaceData`, `useUserInterfaceTimer`, `useViewerStorage`, `useAsset`, `useAssetUrl`, `usePastState` and the rest), plus `MutationError` and `EndpointError`, what a failed write or endpoint call rejects with
+- **`@seriousgaming/sdk/testing`**: `logicArgs` and the offline stub callbacks, for unit-testing logic with no runtime
+- **`@seriousgaming/sdk/ui/testing`**: the harness for component-testing a surface
+- **`@seriousgaming/sdk/e2e`**: the browser-test driver for a running dev server
+- **`@seriousgaming/sdk/commands`** and **`@seriousgaming/sdk/projection`**: the commands a client may send a session, and the shape of the state it reads back (`sdk view --json` and the dev server's `/api/state`)
+- **`@seriousgaming/sdk-tools/client`**: `createTestSession`, which plays a whole game in-process, and `startDevServer`, which starts an isolated dev server for browser tests
+- **`@seriousgaming/deck`**: the slide components and layout primitives a presentation is built from
+
+`@seriousgaming/sdk-tools` also exports `/host` and `/runtime`. They are for people building a runtime that hosts games, not for game authors, their shapes may change in a minor release, and they are not documented here.
+
+## Generated types beside each resource
+
+Most of what a resource imports is not from the SDK at all, but from the `types.ts` the CLI generates beside it from its bundle (and refreshes on `sdk generate`, `sdk build` and every `new` or `update`). The names are the same in every resource:
+
+| Name                                       | What it is                                                                                                        |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `Context`                                  | The capabilities the resource declares in `reads` and `writes`, keyed by capability identifier                    |
+| `TeamContext`, `SharedContext`             | The engine's per-team and shared halves, in a game with shared capabilities                                       |
+| `Settings`                                 | The settings resources it lists in `settings` (or, for `setup` and `scenario_editor`, in `configures`)            |
+| `Callbacks`                                | `LogicCallbacks<...>`: exactly the services it declares in `uses`, and none of the others                         |
+| `Request`, `Response`, `Writes`, `Handler` | An endpoint's request, response, declared writes and handler signature (`Planner` and `Responder` with `actions`) |
+| `Endpoints`                                | On a surface, the typed `callbacks.endpoints` for the endpoints it declares                                       |
+
+The `defaults.ts` beside it exports `defaultContext` and `defaultSettings` (and `defaultTeamContext` and `defaultSharedContext` where they apply), the declared defaults, for use as test fixtures. Write logic as `RunFunction<Context, Settings>` and so on, so the compiler checks it against what the bundle declares: see [Type safety](../guides/type-safety.md).
+
+## Naming conventions
+
+- **Logic signatures** end in `Function` (`RunFunction`, `InitializationFunction`, `HookFunction`, `ValidatorFunction`, `GetTickControllerFunction`), their argument objects in `FunctionArgs`, and an endpoint's in `EndpointHandler` (`EndpointHandler`, `WritingEndpointHandler`, `EffectfulEndpointHandler`)
+- **Arguments** are always one object, whose `meta` is `LogicMeta`, or `RunMeta` and `TeamRunMeta` inside a tick
+- **Results** carry what logic writes under `capabilities`, and paths to remove under `deletes`
+- **Hooks** for surfaces start with `use`, and **errors** end in `Error`
+- **Bundle types** generated from `schema.json` start with `SDK` (`SDKEngine`, `SDKHook`), and the two manifests end in `Manifest`: `PackageManifest` is `seriousgaming.sdk.json` as authored, `ResolvedPackageManifest` the built `seriousgaming.json`
+
+## Where each part is explained
+
+The pages above list every export; the guides explain how they fit together:
+
+- [Engine](../guides/engine.md) for `Init`, `Run` and the tick
+- [Endpoints](../guides/endpoints.md), [Hooks](../guides/hooks.md), [Validators](../guides/validators.md) and [Tick controllers](../guides/tick-controller.md) for the other logic
+- [User interfaces](../guides/ui.md) and [Session UIs](../guides/session.md) for the surface hooks
+- [Testing](../guides/testing.md) and [Engine testing](../guides/engine-testing.md) for `@seriousgaming/sdk/testing`, `@seriousgaming/sdk/ui/testing` and `@seriousgaming/sdk-tools/client`
+- [Presentations](../guides/presentation.md) for `@seriousgaming/deck`
+
+## Versioning
+
+The API version is the SDK package version. A scaffolded game pins a caret range against the release it was created with, so a minor or patch release arrives with `pnpm update`; a major release is a step in the [upgrading guide](../guides/upgrading.md).