@unitedstatespowersquadrons/components 1.0.0

package/.github/workflows/main.yml

@@ -0,0 +1,33 @@
+name: 'Components Library'
+on:
+  push:
+    paths:
+      - '**.ts'
+      - '**.tsx'
+      - 'eslint.config.mjs'
+      - '**.yml'
+      - '**.json'
+    branches:
+      - 'main'
+      - '**'
+  workflow_dispatch:
+
+jobs:
+  eslint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+      - name: Install Packages
+        run: yarn
+      - name: Run Eslint
+        run: yarn run eslint
+  tsc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+      - name: Install Packages
+        run: yarn
+      - name: Run TSC
+        run: yarn run tsc

package/ActionButton.tsx

@@ -0,0 +1,126 @@
+import React from "react";
+import { createUseStyles } from "react-jss";
+import classNames from "classnames";
+import { ButtonColorName } from "./Colors";
+import FontAwesomeIcon, { FontAwesomeProps } from "./FontAwesomeIcon";
+import Styles from "./Styles";
+import BaseActionButton from "./BaseActionButton";
+import { HrefProps, MethodProps, OnClickProps } from "./types";
+
+const useStyles = createUseStyles({
+  big: { ...Styles.bigText },
+  blueColored: { ...Styles.colorizeButton("blue") },
+  blueGray: { ...Styles.blue },
+  button: { ...Styles.button },
+  grayColored: { ...Styles.colorizeButton("gray") },
+  grayGray: { ...Styles.gray },
+  greenColored: { ...Styles.colorizeButton("green") },
+  greenGray: { ...Styles.green },
+  noMargin: { marginTop: "0" },
+  orangeColored: { ...Styles.colorizeButton("orange") },
+  orangeGray: { ...Styles.orange },
+  purpleColored: { ...Styles.colorizeButton("purple") },
+  purpleGray: { ...Styles.purple },
+  redColored: { ...Styles.colorizeButton("red") },
+  redGray: { ...Styles.red },
+  small: { fontSize: "0.8em" },
+  subText: {
+    fontSize: "0.75em",
+    marginLeft: "0.75em",
+  },
+});
+
+export interface CoreActionButtonProps extends FontAwesomeProps {
+  className?: string | undefined;
+  color: ButtonColorName;
+  grayMode?: boolean | undefined;
+  id?: string;
+  size?: "big" | "mediumWithMargin" | "medium" | "small" | undefined;
+  subtext?: string;
+  text: string;
+  title?: string | undefined;
+}
+
+export interface ActionButtonHrefProps extends CoreActionButtonProps, HrefProps {}
+export interface ActionButtonMethodProps extends CoreActionButtonProps, MethodProps {}
+export interface ActionButtonOnClickProps extends CoreActionButtonProps, OnClickProps {}
+
+export type ActionButtonProps =
+  | ActionButtonHrefProps
+  | ActionButtonMethodProps
+  | ActionButtonOnClickProps;
+
+const ActionButton = (props: ActionButtonProps) => {
+  const { className, color, fa, grayMode, icon, id, mode, size, style, subtext, text, title } = props;
+  const classes = useStyles();
+
+  const colorClassName = classes[`${color}${grayMode ? "Gray" : "Colored"}`];
+
+  const sizeClassName = () => {
+    switch (size) {
+    case "big": return classes.big;
+    case "mediumWithMargin": return "";
+    case "medium": return classes.noMargin;
+    case "small": return classNames(classes.small, classes.noMargin);
+    default: return classes.big;
+    }
+  };
+
+  const buttonContents = () => {
+    return(
+      <>
+        <FontAwesomeIcon icon={icon} fa={fa} mode={mode} style={style} />
+        <span>{text}</span>
+        {subtext && <small className={classes.subText}>({subtext})</small>}
+      </>
+    );
+  };
+
+  if ("onClick" in props) {
+    const { confirm, onClick } = props;
+
+    return(
+      <BaseActionButton
+        className={classNames(classes.button, colorClassName, sizeClassName(), className)}
+        id={id}
+        onClick={onClick}
+        title={title}
+        confirm={confirm}
+      >
+        {buttonContents()}
+      </BaseActionButton>
+    );
+  } else if ("method" in props) {
+    const { confirm, href, method } = props;
+
+    return(
+      <BaseActionButton
+        className={classNames(classes.button, colorClassName, sizeClassName(), className)}
+        href={href}
+        id={id}
+        method={method}
+        title={title}
+        confirm={confirm}
+      >
+        {buttonContents()}
+      </BaseActionButton>
+    );
+  } else if ("href" in props) {
+    const { href } = props;
+
+    return(
+      <BaseActionButton
+        className={classNames(classes.button, colorClassName, sizeClassName(), className)}
+        href={href}
+        id={id}
+        title={title}
+      >
+        {buttonContents()}
+      </BaseActionButton>
+    );
+  } else {
+    throw new Error("Invalid ActionButton configuration: must specify props: onClick | (href & method?)");
+  }
+};
+
+export default ActionButton;

package/BaseActionButton.tsx

@@ -0,0 +1,126 @@
+import React, { useRef } from "react";
+import { createUseStyles } from "react-jss";
+import classNames from "classnames";
+import { HrefProps, MethodProps, OnClickHandler, OnClickProps } from "./types";
+import { getCsrfTokenHeader } from "./railsFetchJson";
+
+const useStyles = createUseStyles({
+  button: {
+    background: "none",
+    border: "none",
+    padding: "0",
+  },
+});
+
+interface CoreBaseActionButtonProps {
+  children?: React.ReactNode;
+  className?: string | undefined;
+  id?: string | undefined;
+  title?: string | undefined;
+}
+
+export interface BaseActionButtonHrefProps extends CoreBaseActionButtonProps, HrefProps {}
+export interface BaseActionButtonMethodProps extends CoreBaseActionButtonProps, MethodProps {}
+export interface BaseActionButtonOnClickProps extends CoreBaseActionButtonProps, OnClickProps {}
+
+export type BaseActionButtonProps =
+  | BaseActionButtonHrefProps
+  | BaseActionButtonMethodProps
+  | BaseActionButtonOnClickProps;
+
+const BaseActionButton = (props: BaseActionButtonProps) => {
+  const { children, className, id, title } = props;
+  const classes = useStyles();
+
+  const formRef = useRef<HTMLFormElement>(null);
+
+  if ("onClick" in props) {
+    const { onClick } = props;
+
+    const getConfirmation = () => !props.confirm || confirm(props.confirm);
+
+    const wrappedOnClick: OnClickHandler = event => {
+      event.preventDefault();
+
+      if (getConfirmation()) onClick(event);
+    };
+
+    return(
+      <button
+        type="button"
+        id={id}
+        className={classNames("action-button", classes.button, className)}
+        onClick={wrappedOnClick}
+        title={title}
+      >
+        {children}
+      </button>
+    );
+  } else if ("method" in props) {
+    const { href, method } = props;
+
+    const getConfirmation = () => !props.confirm || confirm(props.confirm);
+
+    const form = () => {
+      if (!method) return;
+
+      return(
+        <form action={href} method="POST" ref={formRef}>
+          <input type="hidden" name="authenticity_token" value={getCsrfTokenHeader()} />
+          <input type="hidden" name="_method" value={method.toUpperCase()} />
+        </form>
+      );
+    };
+
+    const submitForm: OnClickHandler = event => {
+      event.preventDefault();
+
+      if (!getConfirmation()) return;
+
+      const methodForm = formRef.current;
+
+      if (methodForm) methodForm.submit();
+    };
+
+    return(
+      <>
+        {form()}
+        <button
+          type="button"
+          id={id}
+          className={classNames("action-button", classes.button, className)}
+          onClick={submitForm}
+          title={title}
+        >
+          {children}
+        </button>
+      </>
+    );
+  } else if ("href" in props) {
+    const { href, newTab } = props;
+
+    const onClick = () => {
+      if (newTab) {
+        open(href, "_blank");
+      } else {
+        location.href = href;
+      }
+    };
+
+    return(
+      <button
+        type="button"
+        onClick={onClick}
+        id={id}
+        className={classNames("action-button", classes.button, className)}
+        title={title}
+      >
+        {children}
+      </button>
+    );
+  } else {
+    throw new Error("Invalid BaseActionButton configuration: must specify props: onClick | (href & method?)");
+  }
+};
+
+export default BaseActionButton;

package/Colors.tsx

@@ -0,0 +1,124 @@
+const baseColors = {
+  blue: "blue", // #0000FF
+  green: "darkgreen", // #006400
+  orange: "#CC6600",
+  purple: "#6600CC",
+  red: "darkred", // #8B0000
+};
+
+const hoverColors = {
+  blue: "#0000CC",
+  green: "#003300",
+  orange: "#99CC00",
+  purple: "#330099",
+  red: "#660000",
+};
+
+const shades = {
+  _0: "black",
+  _1: "#111111",
+  _2: "#222222",
+  _3: "#333333",
+  _4: "#444444",
+  _5: "#555555",
+  _6: "#666666",
+  _7: "#777777",
+  _8: "#888888",
+  _9: "#999999",
+  _a: "#AAAAAA",
+  _b: "#BBBBBB",
+  _c: "#CCCCCC",
+  _d: "#DDDDDD",
+  _e: "#EEEEEE",
+  _f: "#FFFFFF",
+};
+
+type HexChar =
+  | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
+  | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f";
+const shade = (value: number | `${HexChar}${HexChar}`) => {
+  const validateNumber = () => {
+    if (typeof value !== "number") { return; }
+    if (value < 0 || value > 255) { throw new Error(`Shade out of bounds: ${value}`); }
+  };
+
+  const validateString = () => {
+    if (typeof value !== "string") { return; }
+    if (value.length !== 2) { throw new Error(`Shade too long: "${value}"`); }
+    if (/[^0-9a-fA-F]/.exec(value)) { throw new Error(`Shade out of bounds: "${value}"`); }
+  };
+
+  validateNumber();
+  validateString();
+
+  const hex = value.toString(16).padStart(2, "0");
+
+  return `#${hex.repeat(3)}`;
+};
+
+/* eslint-disable sort-keys */
+const shadesLegacy = {
+  black: shades._0,
+  darkGray: shades._3,
+  mediumGray: shades._5,
+  gray: shades._6,
+  lightGray: shades._9,
+  veryLightGray: shades._c,
+  paleGray: shades._e,
+};
+/* eslint-enable sort-keys */
+
+export type ButtonColorName =
+  | "blue"
+  | "gray"
+  | "green"
+  | "orange"
+  | "purple"
+  | "red";
+
+const specificColors = {
+  answer: {
+    highlighted: "#EEFFFF",
+    selected: "#99FFFF",
+  },
+  button: {
+    background: {
+      hover: {
+        blue: "#5588EE",
+        gray: "#BBBBBB",
+        green: "#55BB55",
+        orange: "#EE8833",
+        purple: "#8844EE",
+        red: "#CC6666",
+      },
+      normal: {
+        blue: "#6699FF",
+        gray: shadesLegacy.veryLightGray,
+        green: "#66CC66",
+        orange: "#FF9944",
+        purple: "#9955FF",
+        red: "#DD7777",
+      },
+    },
+    border: "gray",
+    shadow: "#AAAAAA",
+  },
+  exam: {
+    dragging: "#00CCCC",
+    instructions: {
+      other: "#FFEEEE",
+      selected: "#EEEEFF",
+    },
+  },
+};
+
+const Colors = {
+  ...baseColors,
+  hover: { ...hoverColors },
+  shade,
+  shades,
+  ...shadesLegacy,
+  ...specificColors,
+};
+
+export default Colors;

package/FontAwesomeIcon.tsx

@@ -0,0 +1,33 @@
+import React from "react";
+import { createUseStyles } from "react-jss";
+import classNames from "classnames";
+
+export interface FontAwesomeProps {
+  css?: string | undefined;
+  fa?: string | undefined;
+  icon: string;
+  mode?: "classic" | "duotone" | "sharp" | "sharp-duotone" | undefined;
+  style?: "solid" | "regular" | "light" | "thin" | "brands" | "kit" | undefined;
+}
+
+const useStyles = createUseStyles({
+  icon: {
+    padding: "0.25em 0.5em",
+  },
+});
+
+const FontAwesomeIcon = (props: FontAwesomeProps) => {
+  const { css, fa, icon, mode, style } = props;
+  const classes = useStyles();
+  const faClasses = fa?.split(" ").map(c => `fa-${c}`) || [];
+
+  return (
+    <i
+      className={classNames(
+        classes.icon, `fa-${style || "solid"}`, `fa-${mode || "classic"}`, `fa-${icon}`, css, ...faClasses
+      )}
+    />
+  );
+};
+
+export default FontAwesomeIcon;

package/IconButton.tsx

@@ -0,0 +1,87 @@
+import React from "react";
+import { createUseStyles } from "react-jss";
+import classNames from "classnames";
+import FontAwesomeIcon, { FontAwesomeProps } from "./FontAwesomeIcon";
+import BaseActionButton from "./BaseActionButton";
+import { HrefProps, MethodProps, OnClickProps } from "./types";
+import Styles from "./Styles";
+
+const useStyles = createUseStyles({
+  icon: {
+    ...Styles.blue,
+    cursor: "pointer",
+    fontSize: "1.1em",
+  },
+});
+
+interface CoreIconProps extends FontAwesomeProps {
+  className?: string;
+  id?: string | undefined;
+  title: string;
+}
+
+export interface IconButtonHrefProps extends CoreIconProps, HrefProps {}
+export interface IconButtonMethodProps extends CoreIconProps, MethodProps {}
+export interface IconButtonOnClickProps extends CoreIconProps, OnClickProps {}
+
+export type IconButtonProps =
+  | IconButtonHrefProps
+  | IconButtonMethodProps
+  | IconButtonOnClickProps;
+
+const IconButton = (props: IconButtonProps) => {
+  const { className, fa, icon, id, mode, style, title } = props;
+  const classes = useStyles();
+
+  const configuredIcon = <FontAwesomeIcon icon={icon} fa={fa} mode={mode} style={style} css={className} />;
+
+  const combinedClassName = classNames(classes.icon, className);
+
+  if ("onClick" in props) {
+    const { confirm, onClick } = props;
+
+    return(
+      <BaseActionButton
+        className={combinedClassName}
+        id={id}
+        onClick={onClick}
+        title={title}
+        confirm={confirm}
+      >
+        {configuredIcon}
+      </BaseActionButton>
+    );
+  } else if ("method" in props) {
+    const { confirm, href, method } = props;
+
+    return(
+      <BaseActionButton
+        className={combinedClassName}
+        href={href}
+        id={id}
+        method={method}
+        title={title}
+        confirm={confirm}
+      >
+        {configuredIcon}
+      </BaseActionButton>
+    );
+  } else if ("href" in props) {
+    const { href } = props;
+
+    return(
+      <BaseActionButton
+        className={combinedClassName}
+        href={href}
+        id={id}
+        title={title}
+      >
+        {configuredIcon}
+      </BaseActionButton>
+    );
+  } else {
+    throw new Error("Invalid IconButton configuration: must specify props: onClick | (href & method?)");
+  }
+};
+
+export default IconButton;

package/Readme.md

@@ -0,0 +1,25 @@
+# USPS React Components Library
+
+[![Testing Status](https://github.com/unitedstatespowersquadrons/components/actions/workflows/main.yml/badge.svg)](https://github.com/unitedstatespowersquadrons/components/actions)
+
+## Usage
+
+```ts
+import * from "@unitedstatespowersquadrons/components";
+```
+
+## Developer Setup
+
+Install dependencies with
+
+```sh
+yarn
+```
+
+## Toasts
+
+More detailed information is available for [Toasts](Toasts/Readme.md) usage.
+
+## Automated Testing
+
+GitHub Actions will automatically run `eslint` and `tsc` on branch pushes.

package/SelectionIconButton.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+import { createUseStyles } from "react-jss";
+import classNames from "classnames";
+import IconButton, { IconButtonOnClickProps } from "./IconButton";
+
+const useStyles = createUseStyles({
+  icon: { cursor: "pointer" },
+});
+
+interface Props extends Omit<IconButtonOnClickProps, "icon"> {
+  id?: string;
+  selected: boolean;
+}
+
+const SelectionIconButton = (props: Props) => {
+  const { id, onClick, selected } = props;
+  const classes = useStyles();
+
+  const title = selected ? "Remove Selection" : "Add Selection";
+  const icon = selected ? "square-minus" : "square-plus";
+  const className = selected ? "red" : "green";
+
+  return(
+    <IconButton
+      icon={icon}
+      id={id}
+      onClick={onClick}
+      title={title}
+      className={classNames(classes.icon, className)}
+      mode="duotone"
+    />
+  );
+};
+
+export default SelectionIconButton;

package/StripedTable/Body.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { createUseStyles } from "react-jss";
+import TableStyles from "./TableStyles";
+
+const useStyles = createUseStyles({
+  tbody: TableStyles.tbody,
+});
+
+interface Props {
+  children: React.ReactNode;
+}
+
+const Body = (props: Props) => {
+  const { children } = props;
+  const classes = useStyles();
+
+  return(
+    <tbody className={classes.tbody}>{children}</tbody>
+  );
+};
+
+export default Body;

package/StripedTable/Foot.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { createUseStyles } from "react-jss";
+import TableStyles from "./TableStyles";
+
+const useStyles = createUseStyles({
+  tfoot: TableStyles.tfoot,
+});
+
+interface Props {
+  children: React.ReactNode;
+}
+
+const Head = (props: Props) => {
+  const { children } = props;
+  const classes = useStyles();
+
+  return(
+    <tfoot className={classes.tfoot}>{children}</tfoot>
+  );
+};
+
+export default Head;

package/StripedTable/Head.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { createUseStyles } from "react-jss";
+import TableStyles from "./TableStyles";
+
+const useStyles = createUseStyles({
+  thead: TableStyles.thead,
+});
+
+interface Props {
+  children: React.ReactNode;
+}
+
+const Head = (props: Props) => {
+  const { children } = props;
+  const classes = useStyles();
+
+  return(
+    <thead className={classes.thead}>{children}</thead>
+  );
+};
+
+export default Head;

package/StripedTable/Table.tsx

@@ -0,0 +1,27 @@
+import React from "react";
+import { createUseStyles } from "react-jss";
+import classNames from "classnames";
+import TableStyles from "./TableStyles";
+
+const useStyles = createUseStyles({
+  table: TableStyles.table,
+});
+
+interface Props {
+  children: React.ReactNode;
+  className?: string;
+  id?: string;
+}
+
+const Table = (props: Props) => {
+  const { children, className, id } = props;
+  const classes = useStyles();
+
+  return(
+    <table id={id} className={classNames(className, classes.table)}>
+      {children}
+    </table>
+  );
+};
+
+export default Table;