tgui-core 1.4.0 → 1.5.2

package/README.md

@@ -11,11 +11,11 @@ You can view the code on [GitHub](https://github.com/tgstation/tgui-core).
 (assuming you have a tgui folder, navigate to the specific package)
 
 ```sh
-cd tgui/packages/tgui
+cd tgui/packages/{package name}
 yarn add tgui-core
 ```
 
-## Usage
+## Using the components
 
 Now, you can use them like normal TGUI components.
 
@@ -32,6 +32,28 @@ import { Button } from "tgui-core/components";
 import { Box } from "../components";
 ```
 
+## Using the styles
+
+You have two options for importing styles:
+
+### 1. Importing All Styles
+
+To import all styles at once, add the following line to your main Sass file:
+
+```scss
+@use "pkg:tgui-core/styles";
+```
+
+### 2. Importing Individual Styles
+
+To import individual styles, add any of the exported styles to your main Sass file:
+
+```scss
+@use "pkg:tgui-core/styles/components/Button";
+@use "pkg:tgui-core/styles/components/Dialog";
+@use "pkg:tgui-core/styles/components/NoticeBox";
+```
+
 ## License
 
 MIT

package/dist/components/AnimatedNumber.d.ts

@@ -18,6 +18,7 @@ type Props = {
     initial?: number;
 }>;
 /**
+ * ## AnimatedNumber
  * An animated number label. Shows a number, formatted with an optionally
  * provided function, and animates it towards its target value.
  */

package/dist/components/BlockQuote.d.ts

@@ -1,2 +1,7 @@
 import { BoxProps } from './Box';
+/**
+ * ## BlockQuote
+ * Just a block quote, just like this example in markdown:
+ * > Here's an example of a block quote.
+ */
 export declare function BlockQuote(props: BoxProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Box.d.ts

@@ -56,8 +56,7 @@ type DangerDoNotUse = {
     };
 };
 /**
- * # Box
- *
+ * ## Box
  * The Box component serves as a wrapper component for most of the CSS utility
  * needs. It creates a new DOM element, a `<div>` by default that can be changed
  * with the `as` property. Let's say you want to use a `<span>` instead:

package/dist/components/Button.d.ts

@@ -54,7 +54,10 @@ type Props = Partial<{
     /** Align content vertically using flex. Use lineHeight if the height is static. */
     verticalAlignContent: string;
 }> & EllipsisUnion & BoxProps;
-/** Clickable button. Comes with variants. Read more in the documentation. */
+/**
+ * ## Button
+ * Buttons allow users to take actions, and make choices, with a single click.
+ */
 export declare function Button(props: Props): import("react/jsx-runtime").JSX.Element;
 export declare namespace Button {
     var Checkbox: typeof ButtonCheckbox;
@@ -65,14 +68,12 @@ export declare namespace Button {
 type CheckProps = Partial<{
     checked: BooleanLike;
 }> & Props;
-/** Visually toggles between checked and unchecked states. */
 export declare function ButtonCheckbox(props: CheckProps): import("react/jsx-runtime").JSX.Element;
 type ConfirmProps = Partial<{
     confirmColor: string;
     confirmContent: ReactNode;
     confirmIcon: string;
 }> & Props;
-/**  Requires user confirmation before triggering its action. */
 declare function ButtonConfirm(props: ConfirmProps): import("react/jsx-runtime").JSX.Element;
 type InputProps = Partial<{
     currentValue: string;
@@ -82,13 +83,11 @@ type InputProps = Partial<{
     onCommit: (e: any, value: string) => void;
     placeholder: string;
 }> & Props;
-/** Accepts and handles user input. */
 declare function ButtonInput(props: InputProps): import("react/jsx-runtime").JSX.Element;
 type FileProps = {
     accept: string;
     multiple?: boolean;
     onSelectFiles: (files: string | string[]) => void;
 } & Props;
-/**  Accepts file input */
 declare function ButtonFile(props: FileProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/ByondUi.d.ts

@@ -0,0 +1,50 @@
+import { BoxProps } from './Box';
+type SampleByondParams = Partial<{
+    /** Can be auto-generated. */
+    id: string;
+    /**  Defaults to the current window */
+    parent: string;
+    /** The type of control. Read-only. */
+    type: string;
+    /** Text shown in label/button/input. For input controls this setting is only available at runtime. */
+    text: string;
+}>;
+type Props = Partial<{
+    /** An object with parameters, which are directly passed to
+     * the `winset` proc call.
+     *
+     * You can find a full reference of these parameters
+     * in [BYOND controls and parameters guide](https://secure.byond.com/docs/ref/skinparams.html). */
+    params: SampleByondParams & Record<string, any>;
+}> & BoxProps;
+/**
+ * ## ByondUi
+ * Displays a BYOND UI element on top of the browser, and leverages browser's
+ * layout engine to position it just like any other HTML element. It is
+ * especially useful if you want to display a secondary game map in your
+ * interface.
+ *
+ * @example
+ * ```tsx
+ * <ByondUi
+ *   params={{
+ *    id: 'test_button', // optional, can be auto-generated
+ *    parent: 'some_container', // optional, defaults to the current window
+ *    type: 'button',
+ *    text: 'Hello, world!',
+ *   }} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ByondUi
+ *   params={{
+ *    id: 'test_map',
+ *    type: 'map',
+ *   }} />
+ * ```
+ *
+ * It supports a full set of `Box` properties for layout purposes.
+ */
+export declare function ByondUi(props: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ByondUi.js

@@ -1,19 +1,18 @@
-import { jsx as s } from "react/jsx-runtime";
-import { Component as a, createRef as c } from "react";
-import { shallowDiffers as r } from "../common/react.js";
+import { jsx as l } from "react/jsx-runtime";
+import { useRef as f, useEffect as p } from "react";
 import { debounce as m } from "../common/timer.js";
-import { computeBoxProps as l } from "../common/ui.js";
+import { computeBoxProps as w } from "../common/ui.js";
 const o = [];
-function h(t) {
-  const n = o.length;
+function a(t) {
+  const e = o.length;
   o.push(null);
-  const e = t || `byondui_${n}`;
+  const n = t || `byondui_${e}`;
   return {
     render: (i) => {
-      o[n] = e, Byond.winset(e, i);
+      o[e] = n, Byond.winset(n, i);
     },
     unmount: () => {
-      o[n] = null, Byond.winset(e, {
+      o[e] = null, Byond.winset(n, {
         parent: ""
       });
     }
@@ -21,53 +20,42 @@ function h(t) {
 }
 window.addEventListener("beforeunload", () => {
   for (let t = 0; t < o.length; t++) {
-    const n = o[t];
-    typeof n == "string" && (o[t] = null, Byond.winset(n, {
+    const e = o[t];
+    typeof e == "string" && (o[t] = null, Byond.winset(e, {
       parent: ""
     }));
   }
 });
-function u(t) {
-  const n = window.devicePixelRatio ?? 1, e = t.getBoundingClientRect();
+function x(t) {
+  const e = window.devicePixelRatio ?? 1, n = t.getBoundingClientRect();
   return {
-    pos: [e.left * n, e.top * n],
+    pos: [n.left * e, n.top * e],
     size: [
-      (e.right - e.left) * n,
-      (e.bottom - e.top) * n
+      (n.right - n.left) * e,
+      (n.bottom - n.top) * e
     ]
   };
 }
-class U extends a {
-  constructor(n) {
-    var e;
-    super(n), this.containerRef = c(), this.byondUiElement = h((e = n.params) == null ? void 0 : e.id), this.handleResize = m(() => {
-      this.forceUpdate();
-    }, 100);
-  }
-  shouldComponentUpdate(n) {
-    const { params: e = {}, ...i } = this.props, { params: d = {}, ...p } = n;
-    return r(e, d) || r(i, p);
-  }
-  componentDidMount() {
-    window.addEventListener("resize", this.handleResize), this.componentDidUpdate(), this.handleResize();
-  }
-  componentDidUpdate() {
-    const { params: n = {} } = this.props, e = u(this.containerRef.current);
-    this.byondUiElement.render({
+function h(t) {
+  const { params: e, ...n } = t, i = f(null), d = f(a(e == null ? void 0 : e.id));
+  function s() {
+    const c = i.current;
+    if (!c) return;
+    const r = x(c);
+    d.current.render({
       parent: Byond.windowId,
-      ...n,
-      pos: `${e.pos[0]},${e.pos[1]}`,
-      size: `${e.size[0]}x${e.size[1]}`
+      ...e,
+      pos: `${r.pos[0]},${r.pos[1]}`,
+      size: `${r.size[0]}x${r.size[1]}`
     });
   }
-  componentWillUnmount() {
-    window.removeEventListener("resize", this.handleResize), this.byondUiElement.unmount();
-  }
-  render() {
-    const { params: n, ...e } = this.props;
-    return /* @__PURE__ */ s("div", { ref: this.containerRef, ...l(e), children: /* @__PURE__ */ s("div", { style: { minHeight: "22px" } }) });
-  }
+  const u = m(() => {
+    s();
+  }, 100);
+  return p(() => (window.addEventListener("resize", u), s(), () => {
+    window.removeEventListener("resize", u), d.current.unmount();
+  }), []), /* @__PURE__ */ l("div", { ref: i, ...w(n), children: /* @__PURE__ */ l("div", { style: { minHeight: "22px" } }) });
 }
 export {
-  U as ByondUi
+  h as ByondUi
 };

package/dist/components/Collapsible.d.ts

@@ -12,5 +12,11 @@ type Props = Partial<{
     /** Text to display on the button for collapsing */
     title: ReactNode;
 }> & BoxProps;
+/**
+ * ## Collapsible
+ * Displays contents when open, acts as a fluid button when closed.
+ *
+ * Click to toggle, closed by default.
+ */
 export declare function Collapsible(props: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/ColorBox.d.ts

@@ -3,5 +3,13 @@ import { BoxProps } from './Box';
 type Props = {
     content?: ReactNode;
 } & BoxProps;
+/**
+ * ## ColorBox
+ * Displays a 1-character wide colored square. Can be used as a status indicator,
+ * or for visually representing a color.
+ *
+ * If you want to set a background color on an element, use a plain
+ * [Box](https://github.com/tgstation/tgui-core/tree/main/lib/components/Box.tsx) instead.
+ */
 export declare function ColorBox(props: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Dialog.d.ts

@@ -1,8 +1,9 @@
+import { ReactNode } from 'react';
 type DialogProps = {
-    children: any;
+    children: ReactNode;
     height?: string;
     onClose: () => void;
-    title: any;
+    title: ReactNode;
     width?: string;
 };
 export declare function Dialog(props: DialogProps): import("react/jsx-runtime").JSX.Element;
@@ -14,11 +15,4 @@ type DialogButtonProps = {
     onClick: () => void;
 };
 declare function DialogButton(props: DialogButtonProps): import("react/jsx-runtime").JSX.Element;
-type UnsavedChangesDialogProps = {
-    documentName: string;
-    onClose: () => void;
-    onDiscard: () => void;
-    onSave: () => void;
-};
-export declare function UnsavedChangesDialog(props: UnsavedChangesDialogProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Dialog.js

@@ -1,13 +1,13 @@
-import { jsx as o, jsxs as e } from "react/jsx-runtime";
-import { Box as r } from "./Box.js";
-import { Button as s } from "./Button.js";
-function d(i) {
-  const { title: n, onClose: t, children: c, width: l, height: h } = i;
-  return /* @__PURE__ */ o("div", { className: "Dialog", children: /* @__PURE__ */ e(r, { className: "Dialog__content", width: l || "370px", height: h, children: [
-    /* @__PURE__ */ e("div", { className: "Dialog__header", children: [
-      /* @__PURE__ */ o("div", { className: "Dialog__title", children: n }),
-      /* @__PURE__ */ o(r, { mr: 2, children: /* @__PURE__ */ o(
-        s,
+import { jsx as t, jsxs as l } from "react/jsx-runtime";
+import { Box as e } from "./Box.js";
+import { Button as r } from "./Button.js";
+function d(o) {
+  const { title: i, onClose: n, children: c, width: a, height: s } = o;
+  return /* @__PURE__ */ t("div", { className: "Dialog", children: /* @__PURE__ */ l(e, { className: "Dialog__content", width: a || "370px", height: s, children: [
+    /* @__PURE__ */ l("div", { className: "Dialog__header", children: [
+      /* @__PURE__ */ t("div", { className: "Dialog__title", children: i }),
+      /* @__PURE__ */ t(e, { mr: 2, children: /* @__PURE__ */ t(
+        r,
         {
           mr: "-3px",
           width: "26px",
@@ -17,42 +17,26 @@ function d(i) {
           icon: "window-close-o",
           tooltip: "Close",
           tooltipPosition: "bottom-start",
-          onClick: t
+          onClick: n
         }
       ) })
     ] }),
     c
   ] }) });
 }
-function a(i) {
-  const { onClick: n, children: t } = i;
-  return /* @__PURE__ */ o(
-    s,
+function m(o) {
+  const { onClick: i, children: n } = o;
+  return /* @__PURE__ */ t(
+    r,
     {
-      onClick: n,
+      onClick: i,
       className: "Dialog__button",
       verticalAlignContent: "middle",
-      children: t
+      children: n
     }
   );
 }
-d.Button = a;
-function p(i) {
-  const { documentName: n, onSave: t, onDiscard: c, onClose: l } = i;
-  return /* @__PURE__ */ e(d, { title: "Notepad", onClose: l, children: [
-    /* @__PURE__ */ e("div", { className: "Dialog__body", children: [
-      "Do you want to save changes to ",
-      n,
-      "?"
-    ] }),
-    /* @__PURE__ */ e("div", { className: "Dialog__footer", children: [
-      /* @__PURE__ */ o(a, { onClick: t, children: "Save" }),
-      /* @__PURE__ */ o(a, { onClick: c, children: "Don't Save" }),
-      /* @__PURE__ */ o(a, { onClick: l, children: "Cancel" })
-    ] })
-  ] });
-}
+d.Button = m;
 export {
-  d as Dialog,
-  p as UnsavedChangesDialog
+  d as Dialog
 };

package/dist/components/Dimmer.d.ts

@@ -1,2 +1,8 @@
 import { BoxProps } from './Box';
+/**
+ * ## Dimmer
+ * Dims surrounding area to emphasize content placed inside.
+ *
+ * Content is automatically centered inside the dimmer.
+ */
 export declare function Dimmer(props: BoxProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Divider.d.ts

@@ -1,6 +1,15 @@
 type Props = Partial<{
+    /** Removes the line, simply adding a gap. */
     hidden: boolean;
+    /** Rotate the divider to vertical. */
     vertical: boolean;
 }>;
+/**
+ *
+ * ## Dimmer
+ * Dims surrounding area to emphasize content placed inside.
+ *
+ * Content is automatically centered inside the dimmer.
+ */
 export declare function Divider(props: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/DmIcon.d.ts

@@ -25,5 +25,10 @@ type Props = {
     /** Movement state. Default is false */
     movement: any;
 }> & BoxProps;
+/**
+ * ## DmIcon
+ * Displays an icon from the BYOND icon reference map. Requires Byond 515+.
+ * A much faster alternative to base64 icons.
+ */
 export declare function DmIcon(props: Props): string | number | boolean | Iterable<ReactNode> | import("react/jsx-runtime").JSX.Element | null | undefined;
 export {};

package/dist/components/Dropdown.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
 import { BoxProps } from './Box';
-export type DropdownEntry = {
+type DropdownEntry = {
     displayText: ReactNode;
     value: string | number;
 };
@@ -43,5 +43,10 @@ type Props = {
     /** Text to show when nothing has been selected. */
     placeholder: string;
 }> & BoxProps;
+/**
+ * ## Dropdown
+ * A simple dropdown box component. Lets the user select from a list of options
+ * and displays selected entry.
+ */
 export declare function Dropdown(props: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Flex.d.ts

@@ -55,6 +55,38 @@ export type FlexProps = Partial<{
 }> & BoxProps;
 export declare function computeFlexClassName(props: FlexProps): string;
 export declare function computeFlexProps(props: FlexProps): Record<string, any>;
+/**
+ * ## Flex
+ * Quickly manage the layout, alignment, and sizing of grid columns, navigation,
+ * components, and more with a full suite of responsive flexbox utilities.
+ *
+ * If you are new to or unfamiliar with flexbox, we encourage you to read this
+ * [CSS-Tricks flexbox guide](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).
+ *
+ * Consists of two elements: `<Flex>` and `<Flex.Item>`. Both of them provide
+ * the most straight-forward mapping to flex CSS properties as possible.
+ *
+ * One of the most basic usage of flex, is to align certain elements
+ * to the left, and certain elements to the right:
+ *
+ * @example
+ * ```tsx
+ * <Flex>
+ *   <Flex.Item grow>Button description</Flex.Item>
+ *   <Flex.Item>
+ *     <Button>Perform an action</Button>
+ *   </Flex.Item>
+ * </Flex>
+ * ```
+ *
+ * Flex item with `grow` property will grow to take all available empty space,
+ * while flex items without grow will take the minimum amount of space. This
+ * effectively places the last flex item to the very end of the flex container.
+ *
+ * @deprecated - Use
+ * [Stack](https://github.com/tgstation/tgui-core/tree/main/lib/components/Stack.tsx)
+ * where possible.
+ */
 export declare function Flex(props: any): import("react/jsx-runtime").JSX.Element;
 export declare namespace Flex {
     var Item: typeof FlexItem;

package/dist/components/Icon.d.ts

@@ -1,29 +1,29 @@
-import { CSSProperties, ReactNode } from 'react';
 import { BooleanLike } from '../common/react';
 import { BoxProps } from './Box';
 type Props = {
     /** Icon name. See [icon list](https://fontawesome.com/v5/search?o=r&m=free) */
     name: string;
 } & Partial<{
-    /** Custom CSS class. */
-    className: string;
     /** Icon rotation, in degrees. */
     rotation: number;
     /** Icon size. `1` is normal size, `2` is two times bigger. Fractional numbers are supported. */
     size: number;
     /** Whether an icon should be spinning. Good for load indicators. */
     spin: BooleanLike;
-    /** Custom CSS. */
-    style: CSSProperties;
 }> & Omit<BoxProps, 'children'>;
+/**
+ * ## Icon
+ * Renders one of the FontAwesome icons of your choice.
+ *
+ * @example
+ * ```tsx
+ * <Icon name="plus" />
+ * ```
+ * @url https://fontawesome.com/v5/search?o=r&m=free
+ */
 export declare function Icon(props: Props): import("react/jsx-runtime").JSX.Element;
 export declare namespace Icon {
     var Stack: typeof IconStack;
 }
-type IconStackUnique = {
-    children: ReactNode;
-    className?: string;
-};
-export type IconStackProps = IconStackUnique & BoxProps;
-export declare function IconStack(props: IconStackProps): import("react/jsx-runtime").JSX.Element;
+declare function IconStack(props: BoxProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Icon.js

@@ -39,6 +39,5 @@ function g(c) {
 }
 d.Stack = g;
 export {
-  d as Icon,
-  g as IconStack
+  d as Icon
 };

package/dist/components/Image.d.ts

@@ -9,5 +9,13 @@ type Props = Partial<{
     objectFit: 'contain' | 'cover';
     src: string;
 }> & BoxProps;
+/**
+ * ## Image
+ * A wrapper for the `<img>` element.
+ *
+ * By default, it will attempt to fix broken images by fetching them again.
+ *
+ * It will also try to fix blurry images by rendering them pixelated.
+ */
 export declare function Image(props: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/ImageButton.d.ts

@@ -24,7 +24,11 @@ type Props = Partial<{
     children: ReactNode;
     /** Applies a CSS class to the element. */
     className: string;
-    /** Color of the button. See [Button](#button) but without `transparent`. */
+    /**
+     * Color of the button. See
+     * [Button](https://github.com/tgstation/tgui-core/tree/main/lib/components/Button.tsx)
+     * but without `transparent`.
+     */
     color: string;
     /** Makes button disabled and dark red if true. Also disables onClick. */
     disabled: BooleanLike;

package/dist/components/KeyListener.d.ts

@@ -4,5 +4,10 @@ type Props = Partial<{
     onKeyDown: (key: KeyEvent) => void;
     onKeyUp: (key: KeyEvent) => void;
 }>;
+/**
+ * ## KeyListener
+ * A component that listens for keyboard events and calls the provided
+ * callbacks.
+ */
 export declare function KeyListener(props: Props): null;
 export {};

package/dist/components/LabeledControls.d.ts

@@ -1,4 +1,20 @@
 import { FlexProps } from './Flex';
+/**
+ *  ## LabeledControls
+ * LabeledControls is a horizontal grid that is designed to hold various
+ * controls, like [Knobs](https://github.com/tgstation/tgui-core/tree/main/lib/components/Knob.tsx)
+ * or small [Buttons](https://github.com/tgstation/tgui-core/tree/main/lib/components/Button.tsx).
+ *
+ * Every item in this grid is labeled at the bottom.
+ *
+ * @example
+ * ```tsx
+ * <LabeledControls>
+ *   <LabeledControls.Item label="Temperature"><Knob /></LabeledControls.Item>
+ *   <LabeledControls.Item label="Submit"><Button /></LabeledControls.Item>
+ * </LabeledControls>
+ * ```
+ */
 export declare function LabeledControls(props: FlexProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace LabeledControls {
     var Item: typeof LabeledControlsItem;

package/dist/components/LabeledList.d.ts

@@ -1,5 +1,32 @@
 import { PropsWithChildren, ReactNode } from 'react';
 import { BooleanLike } from '../common/react';
+/**
+ * ## LabeledList
+ * LabeledList is a continuous, vertical list of text and other content, where
+ * every item is labeled.
+ *
+ * It works just like a two column table, where first column is labels, and
+ * second column is content.
+ *
+ * @example
+ * ```tsx
+ * <LabeledList>
+ *   <LabeledList.Item label="Item">Content</LabeledList.Item>
+ * </LabeledList>
+ * ```
+ *
+ * If you want to have a button on the right side of an item (for example,
+ * to perform some sort of action), there is a way to do that:
+ *
+ * @example
+ * ```tsx
+ * <LabeledList>
+ *   <LabeledList.Item label="Item" buttons={<Button>Click me!</Button>}>
+ *     Content
+ *   </LabeledList.Item>
+ * </LabeledList>
+ * ```
+ */
 export declare function LabeledList(props: PropsWithChildren): import("react/jsx-runtime").JSX.Element;
 export declare namespace LabeledList {
     var Item: typeof LabeledListItem;