@engenty/wizards 0.9.0 → 0.9.1

package/dist/openui/index.d.ts

@@ -52,6 +52,9 @@ declare interface BrandView {
     theme: RunTheme;
 }
 
+/** The effects the wizard's card draws itself, when the host turns them on: CSS inside the card. */
+export declare const CARD_EFFECTS: readonly ["glow", "pattern"];
+
 /** A choice drawn as a card, as the runner gets it. */
 declare interface CardOption {
     value: string;
@@ -132,6 +135,11 @@ declare interface ConnectorOption {
     hint?: string;
 }
 
+/** The Halloween costumes a wizard's engenty can wear. Same list as the web app's engenty figures. */
+declare const ENGENTY_COSTUMES: readonly ["witch", "devil", "bat", "pumpkin"];
+
+declare type EngentyCostume = (typeof ENGENTY_COSTUMES)[number];
+
 declare type FieldShape = LeafShape | ListShape | ScoreShape | TableShape;
 
 declare type Format = (typeof FORMATS)[number];
@@ -211,6 +219,7 @@ declare interface LoginAsk extends AskBase {
 
 declare interface MascotProps {
     kind: string;
+    costume?: EngentyCostume;
     size?: number;
     fluffy?: boolean;
 }
@@ -525,6 +534,7 @@ declare const NOTES_EN: {
         readonly other: "A page can have at most {count} characters.";
     };
     readonly chooseFileUpTo: "Choose a file of {mb} MB or less.";
+    readonly fontSourceNoFont: "{family} needs a font file of the space: choose a .woff2 from the assets.";
     readonly roomMostFiles: {
         readonly one: "There’s room for at most {count} file here.";
         readonly other: "There’s room for at most {count} files here.";
@@ -577,6 +587,14 @@ declare interface RunEvent {
     asset?: string | null;
 }
 
+/** A brand font as a run page loads it: from our copy of its file, or from the space's website. */
+declare interface RunFontFace {
+    family: string;
+    /** Ours (`/api/public/fonts/…`) or the website's: the font file or a stylesheet that holds it. */
+    url: string;
+    stylesheet: boolean;
+}
+
 /** A line of `RUN_NOTES` with what goes into its gaps. */
 declare interface RunNote {
     code: RunNoteCode;
@@ -606,7 +624,10 @@ declare interface RunSource {
 
 declare type RunStatus = "waiting_input" | "running" | "done" | "failed" | "cancelled";
 
-/** How a wizard's pages look, taken from its space's brand (`runTheme`). Null: the runner's own. */
+/**
+ * How a wizard's pages look: its space's brand (`runTheme`) with the wizard's own style on top
+ * (`themedLook`). Null: the runner's own.
+ */
 declare interface RunTheme {
     /** Buttons and marks. */
     accent: string | null;
@@ -617,8 +638,22 @@ declare interface RunTheme {
     /** Typefaces as CSS names them. */
     display: string | null;
     body: string | null;
+    /** The brand fonts of the two typefaces that have a source: the page loads them from there. */
+    faces: RunFontFace[];
     /** The brand stands on a dark ground. */
     dark: boolean;
+    /** The theme has only dark or only light pages: the person's own setting does not change it. */
+    pinned: boolean;
+    /** The theme's colours for light and for dark pages; the page takes those of what it shows. */
+    modes: {
+        light: ThemeColours | null;
+        dark: ThemeColours | null;
+    } | null;
+    /** Which of the two the pages show while the person has not chosen. */
+    prefer: "light" | "dark" | null;
+    shape: ThemeShape | null;
+    /** Effects from the runner's library (`THEME_EFFECTS`); names it does not know are skipped. */
+    effects: ThemeEffect[];
 }
 
 /** How a run in the viewer's language shows. */
@@ -637,7 +672,7 @@ declare interface RunView {
     id: string;
     status: RunStatus;
     mode: "test" | "live";
-    wizard: Pick<WizardDefinition, "title" | "description" | "avatar" | "intro">;
+    wizard: Pick<WizardDefinition, "title" | "description" | "avatar" | "costume" | "intro">;
     /** The language the wizard speaks, by its code: what is read aloud, and in which voice. */
     lang: string;
     /**
@@ -1621,6 +1656,39 @@ declare type TextShape = Named & {
     long?: boolean;
 };
 
+declare type ThemeColours = z.infer<typeof themeColoursSchema>;
+
+declare const themeColoursSchema: z.ZodObject<{
+    accent: z.ZodOptional<z.ZodString>;
+    background: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+declare type ThemeEffect = z.infer<typeof themeEffectSchema>;
+
+declare const themeEffectSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$catchall<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+
+declare type ThemeShape = z.infer<typeof themeShapeSchema>;
+
+declare const themeShapeSchema: z.ZodObject<{
+    radius: z.ZodOptional<z.ZodEnum<{
+        round: "round";
+        sharp: "sharp";
+        soft: "soft";
+    }>>;
+    cards: z.ZodOptional<z.ZodEnum<{
+        glass: "glass";
+        outline: "outline";
+        solid: "solid";
+    }>>;
+    headings: z.ZodOptional<z.ZodEnum<{
+        normal: "normal";
+        uppercase: "uppercase";
+    }>>;
+}, z.core.$strip>;
+
 /**
  * One run, live: the runtime's stream of the whole view, plus the commands a person gives. The
  * same as the studio's `useRun` (apps/web/src/runner/useRun.ts), on the runner's own client, so
@@ -1654,6 +1722,29 @@ export declare interface WizardInfo {
     fields: PublicField[];
 }
 
+/**
+ * A theme's values as props for the runner's element: colours, fonts by family and the corner
+ * radius as `--wizard-*` variables, how cards and headings look as data attributes, and of the
+ * effects only those the host turns on and the card can draw. A brand font is named by its
+ * family; the host loads it.
+ */
+export declare function wizardLook(look: RunTheme, options?: WizardLookOptions): WizardLookProps;
+
+export declare interface WizardLookOptions {
+    /** Light or dark, as the host shows; else what the theme prefers. A theme with only one keeps it. */
+    mode?: "light" | "dark";
+    /** The effects the host turns on (`CARD_EFFECTS`); none unless given. */
+    effects?: readonly string[];
+}
+
+/** What goes on the element with `.engenty-runner`: CSS variables and data attributes. */
+export declare interface WizardLookProps {
+    style: Record<string, string>;
+    "data-cards"?: string;
+    "data-headings"?: string;
+    "data-effects"?: string;
+}
+
 export declare type WizardProps = z.infer<typeof wizardProps>;
 
 export declare const wizardProps: z.ZodObject<{
@@ -1681,6 +1772,12 @@ declare const wizardSchema: z.ZodObject<{
         tower: "tower";
         wedge: "wedge";
     }>>;
+    costume: z.ZodOptional<z.ZodEnum<{
+        bat: "bat";
+        devil: "devil";
+        pumpkin: "pumpkin";
+        witch: "witch";
+    }>>;
     intro: z.ZodOptional<z.ZodString>;
     lang: z.ZodOptional<z.ZodString>;
     lists: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -1829,6 +1926,7 @@ declare const wizardSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    themes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
@@ -2510,6 +2608,16 @@ export declare interface WizardsConfig {
     lang?: Lang;
     /** The wizard's mascot above its pages; a plain dot in the wizard's colour unless given. */
     Mascot?: (props: MascotProps) => React.ReactNode;
+    /**
+     * The wizard's look here: `host` (your page's own `--wizard-*` variables, nothing of the
+     * wizard's), `brand`, `default` or the id of a theme the wizard offers. Unless given, or one the
+     * wizard does not offer: its first theme.
+     */
+    theme?: string;
+    /** Light or dark, as your page shows; else what the theme prefers. */
+    mode?: "light" | "dark";
+    /** The effects of the wizard's theme the card may draw (`CARD_EFFECTS`); none unless given. */
+    effects?: readonly string[];
 }
 
 /** The component as a prompt sees it: the same name and props, nothing to draw. */