@spawnite/ui 0.1.0-beta.16

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+import { a as LogomarkProps, i as Logomark, n as WordmarkProps, r as platformName, t as Wordmark } from "./public-DMivBp7u.js";
+import { a as Slider, c as Select, d as NumberField, f as NumberFieldProps, i as TextFieldProps, l as SelectOption, n as ToggleProps, o as SliderProps, r as TextField, s as SliderStyle, t as Toggle, u as SelectProps } from "./public-CGV4pFD1.js";
+import { Tooltip, TooltipProps } from "./tooltip.js";
+import { press, springs, tap } from "./motion.js";
+import { CSSProperties, ElementType, HTMLAttributes, ReactNode, Ref } from "react";
+import { LucideIcon } from "lucide-react";
+import { Vector2 } from "three";
+import { HTMLMotionProps } from "motion/react";
+import { QualityLevel } from "@spawnite/schema";
+/** A cooldown a slot shows: the engine's `Cooldown` has this shape.
+ *  @category UI */
+interface ActionCooldown {
+  /** Seconds it runs for, start to end. */
+  seconds: number;
+  /** Seconds left of them. */
+  left: number;
+}
+/** The outline of every button on a bar.
+ *  @category UI */
+export declare enum ActionBarShape {
+  Circle = "circle",
+  Square = "square"
+}
+/** @category UI */
+interface ActionSlot {
+  /** What `onPress` names the slot by. */
+  id: string;
+  /** The accessible name, such as "Bolt". */
+  label: string;
+  /** The key that presses it, as the badge shows it: "1", "E". The game
+   *  binds the key; the bar only shows it, and only where the pointer is
+   *  fine: a phone has no key, so it shows no badge. */
+  hotkey?: string;
+  /** One Icon. */
+  icon: ReactNode;
+  /** The cooldown it runs. Left out, the slot takes a press. */
+  cooldown?: ActionCooldown;
+  /** The cast winding up, in the cooldown's shape: the rim fills over
+   *  it and every other slot dims. The engine's `CastingTrait` gives `left`
+   *  and the ability's `castSeconds` gives `seconds`. */
+  casting?: ActionCooldown;
+  /** Whether the target stands beyond the ability's range: the icon
+   *  tints red. The slot still takes a press. */
+  outOfRange?: boolean;
+  /** The cost she cannot pay, such as `25` for 25 mana: the icon tints
+   *  blue and the button shows it. Left out while she can pay. The slot
+   *  still takes a press, and the rules say why they refuse it. */
+  noResource?: number;
+  /** Draws the slot pressed, as a pointer's press does. Set it while the
+   *  slot's hotkey is held, so a key press shows on the button. */
+  pressed?: boolean;
+  /** Takes no press and draws nothing for it: dim, with no rim, no
+   *  number and no pop. For a lock that is not the slot's own, such as
+   *  the global cooldown another ability started, so the one button the
+   *  player pressed is the one that moves. A `cooldown` shows instead. */
+  locked?: boolean;
+}
+/** @category UI */
+interface ActionBarProps {
+  /** One to four abilities, in key order. A fifth is left out: the arc
+   *  holds four. */
+  slots: readonly ActionSlot[];
+  /** The ability on the arc's centre, drawn larger than the fan. */
+  primary?: ActionSlot;
+  /** The buttons' outline. Left out, a circle. */
+  shape?: ActionBarShape;
+  /** Called once for each press, with the slot's `id`. */
+  onPress: (id: string) => void;
+  /** An override that shows in the diff. */
+  className?: string;
+}
+/** @category UI */
+export declare function ActionBar({ slots, primary, shape, onPress, className }: ActionBarProps): import("react").JSX.Element;
+/** @inline */
+interface BarProps {
+  /** The accessible name, such as "Health". */
+  label: string;
+  /** The current value. The bar clamps it between 0 and `maximum`. */
+  value: number;
+  /** The full value. It must be positive. */
+  maximum: number;
+  /** A CSS colour the fill draws in, such as a resource's. Left out, it
+   *  is the health tone, which a game restyles through its token.
+   *  @defaultValue the `--color-health-fill` token */
+  color?: string;
+  /** How much of the maximum is held back past `value`, such as the mana
+   *  a cast has reserved: drawn after the fill as a lighter band of its
+   *  colour.
+   *  @defaultValue `0` */
+  reserved?: number;
+  /** Reads the value out beside the bar, `12 / 40`, tabular and small.
+   *  @defaultValue `false` */
+  showValue?: boolean;
+  /** The size, and any other override on the track. Left out, the bar
+   *  is `h-2 w-40`.
+   *  @defaultValue `"h-2 w-40"` */
+  className?: string;
+  /** An override per part, over `className` for the track. */
+  classNames?: BarClassNames;
+}
+/** The parts of a Bar a game restyles apart.
+ *  @category UI */
+interface BarClassNames {
+  /** The row around the track and the value, with `showValue`. */
+  root?: string;
+  track?: string;
+  fill?: string;
+  /** The lighter band `reserved` draws. */
+  reserved?: string;
+  /** The `12 / 40` beside the track, with `showValue`. */
+  value?: string;
+}
+/** @category UI */
+export declare function Bar({ label, value, maximum, color, reserved, showValue, className, classNames }: BarProps): import("react").JSX.Element;
+/** The looks a Button comes in. Glass is the default, over the world;
+ *  the other two draw on the menu tokens, so a game that sets its accent
+ *  sets them with it, as Godot's theme overrides reach every button.
+ *  @category UI */
+export declare enum ButtonVariant {
+  /** Glass over the world: the default. */
+  Glass = "glass",
+  /** Filled with the menu accent, with its ink: the one action a screen
+   *  leads with. */
+  Accent = "accent",
+  /** On the menu's pane: a step back or a lesser choice. */
+  Pane = "pane"
+}
+/** @inline */
+interface ButtonProps {
+  /** The look. @defaultValue `ButtonVariant.Glass` */
+  variant?: ButtonVariant;
+  /** Off: dimmed, no press lands, and Tab passes it, as a browser's own
+   *  disabled button. */
+  disabled?: boolean;
+  /** The accessible name, which a button of text takes from its text and
+   *  a button of one icon needs spelled out. */
+  label?: string;
+  /** A toggle's state; off dims the button. Left out by a button that
+   *  holds none: a press that jumps the sun is over when it lands, so
+   *  there is nothing to report. */
+  pressed?: boolean;
+  /** The press. The component does not know what the state becomes: the
+   *  caller owns it, and `pressed` is how it comes back. */
+  onPress: () => void;
+  /** The key that presses it too, which the caller binds, written as
+   *  `aria-keyshortcuts` writes one, such as `"R"` or `"Shift+E"`. A
+   *  screen reader announces it, and the engine's development warning
+   *  knows a player reaches the button while the cursor is captured. */
+  keyShortcuts?: string;
+  /** One icon, or a word or two. */
+  children: ReactNode;
+  /** An override that shows in the diff. */
+  className?: string;
+  /** An override per part, over `className` for the root. */
+  classNames?: ButtonClassNames;
+  /** A style that comes from data, such as an item's rarity colour or a
+   *  place on a grid. A look that is the same every time is a class. */
+  style?: CSSProperties;
+}
+/** The parts of a Button a game restyles apart.
+ *  @category UI */
+interface ButtonClassNames {
+  root?: string;
+  /** The span around the icon or the word. */
+  icon?: string;
+}
+/** @category UI */
+export declare function Button({ variant, disabled, label, pressed, onPress, keyShortcuts, children, className, classNames, style, ref }: ButtonProps & {
+  ref?: Ref<HTMLButtonElement>;
+}): import("react").JSX.Element;
+interface CompletionRingProps {
+  className?: string;
+}
+export declare function CompletionRing({ className }: CompletionRingProps): import("react").JSX.Element;
+declare const levels: {
+  1: string;
+  2: string;
+  3: string;
+  4: string;
+};
+/** @inline */
+interface HeadingProps {
+  /** The outline level: `h1` to `h4`, each with its own size and weight. */
+  level: keyof typeof levels;
+  /** An override that shows in the diff. */
+  className?: string;
+  children: ReactNode;
+}
+/** A title drawn over the world, with Text's white and dark edge.
+ *  @category UI */
+export declare function Heading({ level, className, children }: HeadingProps): import("react").JSX.Element;
+/** The icons a game names without importing anything: a HUD's usual set.
+ *  @category UI */
+type IconName = "arrow-big-down" | "arrow-big-left" | "arrow-big-right" | "arrow-big-up" | "check" | "coins" | "crosshair" | "crown" | "droplet" | "flag" | "flame" | "gem" | "gift" | "heart" | "house" | "key" | "lock" | "map" | "menu" | "moon" | "mic" | "mic-off" | "pause" | "play" | "rotate-ccw" | "settings" | "shield" | "skull" | "snowflake" | "star" | "swords" | "target" | "timer" | "trophy" | "user" | "users" | "volume-2" | "volume-x" | "x" | "zap";
+/** @category UI */
+interface IconProps {
+  /** An icon from the set by its lucide name, such as `"coins"` or
+   *  `"heart"`, where a typo does not compile. Or any other lucide icon,
+   *  imported from `lucide-react` by the game itself. */
+  name: IconName | LucideIcon;
+  /** The accessible name. Left out, the icon is decoration beside text
+   *  that already says what it means, and a screen reader skips it. */
+  label?: string;
+  /** The size, such as `"size-8"`, and any other override. */
+  className?: string;
+}
+/** @category UI */
+export declare function Icon({ name, label, className }: IconProps): import("react").JSX.Element;
+/** @inline */
+interface ImageProps {
+  /** The picture's address, as an import of the file or a path the game
+   *  serves gives it. */
+  src: string;
+  /** What the picture shows, for a screen reader; empty for a picture
+   *  that only decorates, which a screen reader then passes over. */
+  label: string;
+  /** Its size and fit, such as `size-10 object-contain`, and
+   *  `[image-rendering:pixelated]` for pixel art. */
+  className?: string;
+  /** A style that comes from data, such as a place on a grid. */
+  style?: CSSProperties;
+}
+/** A picture from a file, such as an item's sprite. An icon from the
+ *  engine's set is an `Icon`.
+ *  @category UI */
+export declare function Image({ src, label, className, style }: ImageProps): import("react").JSX.Element;
+/** @category UI */
+interface JoystickProps {
+  /** Where the thumb is, on the unit disc: `x` right, `y` up the screen.
+   *  `(0, 0)` while nothing holds it, and on release. A fresh vector each
+   *  time, so the caller may keep one. */
+  onSteer: (direction: Vector2) => void;
+  /** How far past the drawn ring a thumb still catches the stick, in the
+   *  ring's own units. The ring grows to fill it on the grab, which is
+   *  what tells the player what they caught.
+   *  @defaultValue `8` */
+  grabMargin?: number;
+  /** Placement and visibility, such as showing it only on touch
+   *  screens. */
+  className?: string;
+}
+/** @category UI */
+export declare function Joystick({ onSteer, grabMargin, className }: JoystickProps): import("react").JSX.Element;
+interface LoadingRingProps {
+  /** How much has loaded, from 0 to 1. */
+  value: number;
+  className?: string;
+}
+export declare function LoadingRing({ value, className }: LoadingRingProps): import("react").JSX.Element;
+interface MadeWithNoticeProps {
+  /** Where it sits, such as a fixed place on the loading screen. */
+  className?: string;
+}
+/** The licence's Required Notice on screen: one small line, "Made with
+ *  Spawnite", whose name opens spawnite.com in a new tab.
+ *  @category UI */
+export declare function MadeWithNotice({ className }: MadeWithNoticeProps): import("react").JSX.Element;
+/** The `palette` entry a ProgressBar's fill draws in. */
+export declare enum ProgressBarVariant {
+  HealthFill = "healthFill",
+  LoadingBar = "loadingBar"
+}
+interface ProgressBarProps extends Omit<HTMLMotionProps<"div">, "children" | "color"> {
+  /** How full, from 0 to 1. */
+  value: number;
+  variant: ProgressBarVariant;
+  /** A CSS colour the fill draws in, in place of the variant's. */
+  color?: string;
+  /** Drawn over the fill, inside the track's clip. */
+  children?: ReactNode;
+  /** An override on the fill. */
+  fillClassName?: string;
+}
+export declare function ProgressBar({ value, variant, color, className, children, fillClassName, ...rest }: ProgressBarProps): import("react").JSX.Element;
+interface QualityButtonProps {
+  level: QualityLevel;
+  /** Whether the player set a feature row apart from the level, which
+   *  the button names Custom. */
+  custom?: boolean;
+  onPress: () => void;
+}
+export declare function QualityButton({ level, custom, onPress }: QualityButtonProps): import("react").JSX.Element;
+/** @inline */
+interface CounterProps {
+  /** The icon that says what the number is. */
+  icon: IconProps["name"];
+  /** The accessible name, such as "Coins". */
+  label: string;
+  value: number | string;
+  /** The size, the icon's and the number's together.
+   *  @defaultValue `"base"` */
+  size?: keyof typeof sizes$1;
+  /** An override that shows in the diff, on the row. */
+  className?: string;
+  /** An override per part, over `className` for the row. */
+  classNames?: CounterClassNames;
+}
+/** The parts of a Counter a game restyles apart.
+ *  @category UI */
+interface CounterClassNames {
+  root?: string;
+  icon?: string;
+  value?: string;
+}
+declare const sizes$1: {
+  readonly sm: {
+    readonly icon: "size-4";
+    readonly text: "sm";
+  };
+  readonly base: {
+    readonly icon: "size-5";
+    readonly text: "base";
+  };
+  readonly lg: {
+    readonly icon: "size-7";
+    readonly text: "lg";
+  };
+  readonly xl: {
+    readonly icon: "size-8";
+    readonly text: "xl";
+  };
+};
+/** @category UI */
+export declare function Counter({ icon, label, value, size, className, classNames }: CounterProps): import("react").JSX.Element;
+/** @category UI */
+interface TapProps {
+  /** The accessible name. A Tap shows an icon, not text. */
+  label: string;
+  /** Called once for each press. */
+  onTap: () => void;
+  /** Called as the finger or the button that pressed it lets go, slides
+   *  off, or the browser takes the touch: what a held control, a sprint
+   *  or a block, ends on. */
+  onRelease?: () => void;
+  /** One Icon. */
+  children: ReactNode;
+  /** An override that shows in the diff. */
+  className?: string;
+}
+/** @category UI */
+export declare function Tap({ label, onTap, onRelease, children, className }: TapProps): import("react").JSX.Element;
+/** What this puts on whichever element it is given. Naming it is what keeps
+ *  `as` usable: an element type with no props to satisfy resolves every one of
+ *  them to `never`, and no caller can then pass a class. */
+type TextElementProps = Pick<HTMLAttributes<HTMLElement>, "aria-label" | "className" | "style" | "title" | "children">;
+declare const sizes: {
+  xs: string;
+  sm: string;
+  base: string;
+  lg: string;
+  xl: string;
+};
+/** @inline */
+interface TextProps {
+  /** The element to draw. Rows of named values are a list, one value is an
+   *  output, and a span is the fallback for text that is only text. A
+   *  wrapper of this component's own would be an element with nothing to
+   *  say, so the caller's is the one that is drawn.
+   *  @defaultValue `"span"` */
+  as?: ElementType<TextElementProps>;
+  /** The accessible name, where the element the caller chose takes one.
+   *  Spelled as the attribute it becomes, so there is no second name for a
+   *  caller to learn and none for this to quietly drop. */
+  "aria-label"?: string;
+  /** The font size, from Tailwind's scale. Small by default, the size of
+   *  a readout over the world.
+   *  @defaultValue `"sm"` */
+  size?: keyof typeof sizes;
+  /** Draws every digit the same width, so a number that counts does not
+   *  shift the text beside it or the pane around it.
+   *  @defaultValue `false` */
+  tabular?: boolean;
+  /** What the browser shows in a tooltip while the pointer rests on it,
+   *  such as what a stat does. */
+  title?: string;
+  /** An override that shows in the diff. */
+  className?: string;
+  /** A style that comes from data, such as an item's rarity colour or a
+   *  place on a grid. A look that is the same every time is a class. */
+  style?: CSSProperties;
+  children: ReactNode;
+}
+/** @category UI */
+export declare function Text({ as, "aria-label": label, size, tabular, title, className, style, children }: TextProps): import("react").JSX.Element;
+export declare const palette: {
+  readonly healthFill: "bg-health-fill";
+  readonly healthTrack: "bg-health-track";
+  readonly healthLoss: "bg-health-loss";
+  readonly loadingBackground: "bg-loading-background";
+  readonly loadingLabel: "text-loading-label";
+  readonly loadingIndicator: "text-loading-indicator";
+  readonly loadingBar: "bg-loading-bar";
+  readonly errorText: "text-neutral-200";
+  readonly stickRing: "border-stick-ring";
+  readonly stickKnob: "bg-stick-knob";
+  readonly stickKnobShadow: "shadow-black/25";
+  readonly glassSurface: "text-pane-ink bg-pane-surface bg-linear-to-b from-pane-sheen to-pane-sheen-end backdrop-blur-(--blur-pane) backdrop-saturate-[1.7] inset-shadow-[0_1px_0] inset-shadow-pane-edge/70";
+  readonly glassBorder: "border-pane-edge";
+  readonly glassIconEdge: "[filter:drop-shadow(0_0_1px_black)_drop-shadow(0_0_1px_black)]";
+  readonly glassChildIconEdge: "[&_svg]:[filter:drop-shadow(0_0_1px_black)_drop-shadow(0_0_1px_black)]";
+  readonly glassShadow: "shadow-pane-shadow";
+  readonly glassFocusRing: "ring-pane-ink";
+  readonly glassFocusRingOffset: "ring-offset-neutral-950";
+  readonly outlinedText: "text-white [text-shadow:1px_1px_0_black,-1px_1px_0_black,1px_-1px_0_black,-1px_-1px_0_black]";
+  readonly dangerText: "text-danger";
+  readonly fieldBox: "pointer-events-auto h-9 rounded-(--radius-field) border border-menu-edge bg-menu-raised px-2 text-(length:--text-field) text-menu-ink transition-colors hover:border-menu-muted/60 motion-reduce:transition-none disabled:cursor-not-allowed disabled:opacity-40";
+  readonly controlFocusRing: "outline-none focus-visible:ring-2 focus-visible:ring-white/90 focus-visible:ring-offset-2 focus-visible:ring-offset-neutral-950";
+};
+interface PointerGripOptions {
+  /** `HTMLElement` rather than `Element`, because only its event map names
+   *  the pointer events. */
+  host: HTMLElement;
+  /** Defaults to the global window; a test hands in its own. */
+  window?: Window;
+  /** A finger took the control. */
+  onGrab?: (event: PointerEvent) => void;
+  /** The gripping finger moved. */
+  onMove?: (event: PointerEvent) => void;
+  /** The grip ended, whichever way it ended. */
+  onRelease: () => void;
+}
+/** Binds the grip to `host`. Returns the unbind, which also lets go. */
+export declare function gripPointer({ host, window, onGrab, onMove, onRelease }: PointerGripOptions): () => void;
+export declare function trackPageHide(target: Window, hide: () => void): () => void;
+export { type ActionBarProps, type ActionCooldown, type ActionSlot, type BarClassNames, type ButtonClassNames, type ButtonProps, type CounterClassNames, type IconName, type IconProps, type ImageProps, type JoystickProps, Logomark, type LogomarkProps, NumberField, type NumberFieldProps, type PointerGripOptions, Select, type SelectOption, type SelectProps, Slider, type SliderProps, type SliderStyle, type TapProps, TextField, type TextFieldProps, Toggle, type ToggleProps, Tooltip, type TooltipProps, Wordmark, type WordmarkProps, platformName, press, springs, tap };