@unitedstatespowersquadrons/components 1.2.23 → 1.2.25-1

package/ActionButton.tsx

@@ -63,9 +63,24 @@ interface InlineProps {
   inline?: boolean;
 }
 
+/**
+ * Props for a standard link button
+ */
 export interface ActionButtonHrefProps extends CoreActionButtonProps, HrefProps, InlineProps {}
+
+/**
+ * Props for a link button with a form wrapper for HTTP verb requests
+ */
 export interface ActionButtonMethodProps extends CoreActionButtonProps, MethodProps {}
+
+/**
+ * Props for a button with a custom `onClick` handler
+ */
 export interface ActionButtonOnClickProps extends CoreActionButtonProps, OnClickProps {}
+
+/**
+ * Props for a button to submit a form
+ */
 export interface ActionButtonFormProps extends CoreActionButtonProps, FormProps {}
 
 export type ActionButtonProps =
@@ -74,6 +89,12 @@ export type ActionButtonProps =
   | ActionButtonOnClickProps
   | ActionButtonFormProps;
 
+/**
+ * Stylized button with icon and text, for handling dispatch actions, form
+ * submissions, and other general links
+ *
+ * @category Components
+ */
 const ActionButton = (props: ActionButtonProps) => {
   const { className, color, fa, grayMode, icon, id, mode, rightIcon, size, style, subtext, text, title } = props;
   const classes = useStyles();

package/Colors.tsx

@@ -126,6 +126,9 @@ const specificColors = {
   },
 };
 
+/**
+ * Shared JSS color styles
+ */
 const Colors = {
   ...baseColors,
   ...insigniaColors,

package/Flags/Officer.tsx

@@ -9,7 +9,7 @@ type FlagRank =
   | "PDLTC" | "PDC" | "DAIDE" | "DFLT" | "D1LT"
   | "PNFLT" | "PSTFC" | "PRC" | "PVC" | "PCC" | "NAIDE" | "NFLT";
 
-interface Props {
+interface OfficerProps {
   className?: string;
   flag?: string; // FlagRank | jobcode
   format?: "svg" | "png";
@@ -19,7 +19,12 @@ interface Props {
   size?: number | "thumb";
 }
 
-const OfficerFlag = (props: Props) => {
+/**
+ * An officer flag image
+ *
+ * @category Components
+ */
+const OfficerFlag = (props: OfficerProps) => {
   const { className, flag, format, jobcode, insignia, rank, size } = props;
 
   if (!flag && !jobcode && !rank) {

package/Flags/Signal.tsx

@@ -1,13 +1,18 @@
 import React from "react";
 
-interface Props {
+interface SignalProps {
   alt?: string;
   className?: string;
   flag: string;
   format?: "svg" | "png" | undefined;
 }
 
-const SignalFlag = (props: Props) => {
+/**
+ * An individual signal flag image
+ *
+ * @category Components
+ */
+const SignalFlag = (props: SignalProps) => {
   const { alt, className, flag, format } = props;
 
   const special = ["\uE000", "\uE001",   "\uE002",   "\uE003"];

package/Flags/Signals.tsx

@@ -14,7 +14,7 @@ type Size =
   | "vertical"
   | "center";
 
-interface Props {
+interface SignalsProps {
   className?: string;
   format?: "svg" | "png";
   orientation?: Orientation;
@@ -70,7 +70,12 @@ const useStyles = createUseStyles({
   },
 });
 
-const SignalFlags = (props: Props) => {
+/**
+ * A colleciton of signal flag images generated from a string
+ *
+ * @category Components
+ */
+const SignalFlags = (props: SignalsProps) => {
   const { className, format, orientation, size, text, title } = props;
   const classes = useStyles();
 

package/FontAwesomeIcon.tsx

@@ -17,6 +17,12 @@ const useStyles = createUseStyles({
   },
 });
 
+/**
+ * A formatted FontAwesome icon placeholder `<i>` tag, which will be replaced by
+ * the FontAwesome JS with the corresponding SVG
+ *
+ * @category Components
+ */
 const FontAwesomeIcon = (props: FontAwesomeProps) => {
   const { css, fa, icon, mode, style, title } = props;
   const classes = useStyles();

package/IconButton.tsx

@@ -25,8 +25,19 @@ interface CoreIconProps extends FontAwesomeProps {
   title: string;
 }
 
+/**
+ * Props for a standard link button
+ */
 export interface IconButtonHrefProps extends CoreIconProps, HrefProps {}
+
+/**
+ * Props for a link button with a form wrapper for HTTP verb requests
+ */
 export interface IconButtonMethodProps extends CoreIconProps, MethodProps {}
+
+/**
+ * Props for a button with a custom `onClick` handler
+ */
 export interface IconButtonOnClickProps extends CoreIconProps, OnClickProps {}
 
 export type IconButtonProps =
@@ -34,6 +45,12 @@ export type IconButtonProps =
   | IconButtonMethodProps
   | IconButtonOnClickProps;
 
+/**
+ * Stylized icon-only button, for handling dispatch actions, form submissions,
+ * and other general links
+ *
+ * @category Components
+ */
 const IconButton = (props: IconButtonProps) => {
   const { className, fa, icon, id, mode, style, title } = props;
   const classes = useStyles();

package/RailsForm.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 
-interface Props {
+interface RailsFormProps {
   action: string;
   fileUpload?: boolean;
   id?: string;
@@ -8,7 +8,12 @@ interface Props {
   children: React.ReactNode[];
 }
 
-const RailsForm = (props: Props) => {
+/**
+ * A `form` tag that includes the Rails CSRF params
+ *
+ * @category Components
+ */
+const RailsForm = (props: RailsFormProps) => {
   const { action, children, fileUpload, id, method } = props;
 
   const token = document.querySelector("meta[name='csrf-token']");

package/Readme.md

@@ -1,5 +1,6 @@
 # USPS React Components Library
 
+![NPM Version](https://img.shields.io/npm/v/@unitedstatespowersquadrons/components)
 [![Testing Status](https://github.com/unitedstatespowersquadrons/components/actions/workflows/main.yml/badge.svg)](https://github.com/unitedstatespowersquadrons/components/actions)
 
 ## Usage
@@ -46,12 +47,28 @@ More detailed information is available for [Toasts](Toasts/Readme.md) usage.
 
 ## Reducer
 
-To create a reducer, follow the following pattern, follow the pattern described
-in [Reducer/Example](Reducer/Example).
+To create a reducer, follow the pattern described in [Reducer/Example](Reducer/Example).
 
 There is also an example in `appstate.tsx` for if you only need access to app
 state, but do not have any dispatchable events.
 
+## Shared TSC Config
+
+To include the TSC config from this library, create `./tsconfig.json`:
+
+```json
+{
+  "extends": "./node_modules/@unitedstatespowersquadrons/components/tsconfig.json",
+  "exclude": [
+    "**/proto",
+    "node_modules",
+    "public",
+    "vendor",
+    "tmp"
+  ]
+}
+```
+
 ## Automated Testing
 
 GitHub Actions will automatically run `eslint` and `tsc` on branch pushes.

package/Reducer/buildReducer.tsx

@@ -9,6 +9,13 @@ interface InitialAppProps<AppState> {
   children: React.ReactNode;
 }
 
+/**
+ * Construct the exports from a reducer
+ *
+ * @param reducer The specific reducer function for the component
+ * @param handlers Handlers for individual dispatch actions
+ * @returns { AppProvider, useAppCableSubscription, useAppDispatch, useAppState }
+ */
 export default function buildReducer<AppState, AppAction>(
   reducer: (draft: Draft<AppState>, action: AppAction) => void,
   handlers: ReducerHandler<AppAction>[] = []

package/Reducer/buildUnreducibleState.tsx

@@ -5,6 +5,11 @@ interface InitialAppProps<AppState> {
   children: React.ReactNode;
 }
 
+/**
+ * Construct the exports to access appState for a component without a reducer
+ *
+ * @returns { AppProvider, useAppState }
+ */
 export default function buildUnreducibleState<AppState>() {
   const StateContext = createContext<AppState | null>(null);
 

package/SelectionIconButton.tsx

@@ -7,12 +7,17 @@ const useStyles = createUseStyles({
   icon: { cursor: "pointer" },
 });
 
-interface Props extends Omit<IconButtonOnClickProps, "icon"> {
+interface SelectionIconButtonProps extends Omit<IconButtonOnClickProps, "icon"> {
   id?: string;
   selected: boolean;
 }
 
-const SelectionIconButton = (props: Props) => {
+/**
+ * Stylized icon-only button, intended for handling add/remove dispatch actions
+ *
+ * @category Components
+ */
+const SelectionIconButton = (props: SelectionIconButtonProps) => {
   const { id, onClick, selected } = props;
   const classes = useStyles();
 

package/StripedTable/Body.tsx

@@ -6,11 +6,16 @@ const useStyles = createUseStyles({
   tbody: TableStyles.tbody,
 });
 
-interface Props {
+interface BodyProps {
   children: React.ReactNode;
 }
 
-const Body = (props: Props) => {
+/**
+ * Table body with automatic row striping
+ *
+ * @category Components
+ */
+const Body = (props: BodyProps) => {
   const { children } = props;
   const classes = useStyles();
 

package/StripedTable/Foot.tsx

@@ -6,11 +6,16 @@ const useStyles = createUseStyles({
   tfoot: TableStyles.tfoot,
 });
 
-interface Props {
+interface FootProps {
   children: React.ReactNode;
 }
 
-const Head = (props: Props) => {
+/**
+ * Table foot with automatic row striping
+ *
+ * @category Components
+ */
+const Head = (props: FootProps) => {
   const { children } = props;
   const classes = useStyles();
 

package/StripedTable/Head.tsx

@@ -6,11 +6,16 @@ const useStyles = createUseStyles({
   thead: TableStyles.thead,
 });
 
-interface Props {
+interface HeadProps {
   children: React.ReactNode;
 }
 
-const Head = (props: Props) => {
+/**
+ * Table head with automatic row striping
+ *
+ * @category Components
+ */
+const Head = (props: HeadProps) => {
   const { children } = props;
   const classes = useStyles();
 

package/StripedTable/Table.tsx

@@ -10,7 +10,7 @@ const useStyles = createUseStyles({
   tableStripedTbody: TableStyles.tableStripedTbody,
 });
 
-interface Props {
+interface TableProps {
   borderCollapse?: boolean;
   children: React.ReactNode;
   className?: string;
@@ -18,7 +18,12 @@ interface Props {
   stripedTbody?: boolean;
 }
 
-const Table = (props: Props) => {
+/**
+ * Table with automatic row striping
+ *
+ * @category Components
+ */
+const Table = (props: TableProps) => {
   const { borderCollapse, children, className, id, stripedTbody } = props;
   const classes = useStyles();
 

package/StripedTable/TableStyles.ts

@@ -58,6 +58,9 @@ const tableStripedTbody = {
   "& > thead": thead,
 };
 
+/**
+ * Shared JSS styles for striped tables and sections
+ */
 const TableStyles = { table, tableStripedTbody, tbody, tfoot, thead };
 
 export default TableStyles;

package/Styles.tsx

@@ -40,6 +40,9 @@ const colorizeButton = (color: ButtonColorName) => {
   });
 };
 
+/**
+ * Shared JSS styles
+ */
 const Styles = {
   bigText: { fontSize: "1.5em" },
   button: {
@@ -59,6 +62,11 @@ const Styles = {
     textDecoration: "none",
     width: "fit-content",
   },
+  flexColumn: {
+    display: "flex",
+    flexDirection: "column",
+    gap: "0.5em",
+  },
   flexRow: {
     alignItems: "center",
     display: "flex",

package/Toasts/Readme.md

@@ -5,16 +5,15 @@ root components, while supporting app state and reducer dispatching.
 
 ```tsx
 // NewComponent.tsx
+import { Toasts } from "@unitedstatespowersquadrons/components";
 import { useAppState, useAppDispatch } from "./reducer";
-import { createDismissToast, Toasts } from "../shared";
 
 const NewComponent = () => {
   const { toasts } = useAppState();
   const dispatch = useAppDispatch();
-  const dismissToast = createDismissToast(dispatch);
 
   return (
-    <Toasts dismiss={dismissToast} toasts={toasts} />
+    <Toasts dispatch={dispatch} toasts={toasts} />
   );
 };
 
@@ -23,8 +22,7 @@ export default NewComponent;
 
 ```tsx
 // reducer.tsx
-import { Toast, ToastAppAction, ToastProps } from "../shared";
-import { addToast, handleToasts } from "./reducerHelpers";
+import { addToast, handleToasts, Toast, ToastAppAction, ToastProps } from "@unitedstatespowersquadrons/components";
 
 export type AppAction =
   // ...
@@ -73,38 +71,3 @@ function reducer(draft: Draft<AppState>, action: AppAction) {
   // ...
 };
 ```
-
-```tsx
-// reducerHelpers.tsx
-import { Draft } from "immer";
-import { AppState } from "./types";
-import { Toast, ToastProps } from "../shared";
-
-export const handleToasts = (draft: Draft<AppState>, toasts: Toast[]) => {
-  if (toasts.length > 0) {
-    toasts.forEach(toast => addToast(draft, toast));
-  }
-};
-
-export const addToast = (draft: Draft<AppState>, toastOptions: Proto.Shared.Toast) => {
-  const { body, status, timeout, title } = toastOptions;
-
-  const id = draft.toastId = draft.toastId ? draft.toastId + 1 : 1;
-
-  const toast = { body, id, status, timeout, title } as ToastProps;
-
-  if (!draft.toasts) draft.toasts = [];
-
-  // Do not store multiple identical toasts
-  if (draft.toasts.some(t => {
-    return (
-      toast.body === t.body &&
-        toast.status === t.status &&
-        toast.title === t.title
-    );
-  })) return;
-
-  draft.toasts.push(toast);
-};
-
-```

package/Toasts/Toast.tsx

@@ -5,7 +5,7 @@ import { DismissFunc, Toast_Status, ToastProps } from "./types";
 import FontAwesomeIcon from "../FontAwesomeIcon";
 import Styles from "../Styles";
 
-interface Props {
+interface ToastComponentProps {
   dismiss: DismissFunc;
   toast: ToastProps;
 }
@@ -26,7 +26,10 @@ const useStyles = createUseStyles({
     color: "#009900",
   },
   toast: {
-    "@media print, screen and (max-width: 1000px)": { maxWidth: "100%" },
+    "@media print, screen and (max-width: 1000px)": {
+      maxWidth: "100%",
+      width: "auto",
+    },
     animation: "fadeIn 1s",
     backgroundColor: "#EEEEEE",
     border: "thin solid white",
@@ -69,7 +72,12 @@ const useStyles = createUseStyles({
   visible: { opacity: "1" },
 });
 
-const Toast = (props: Props) => {
+/**
+ * An individual toast message
+ *
+ * @category Components
+ */
+const Toast = (props: ToastComponentProps) => {
   const classes = useStyles();
 
   const { dismiss, toast } = props;

package/Toasts/Toasts.tsx

@@ -23,9 +23,9 @@ type Props = DismissProps | DispatchProps;
 const useStyles = createUseStyles({
   toastsContainer: {
     "@media print, screen and (max-width: 1000px)": {
-      fontSize: "0.7em",
-      marginLeft: "0.5em",
-      maxWidth: "100%",
+      fontSize: "1.5em",
+      margin: "0.5em",
+      width: "90vw",
     },
     display: "flex",
     flexDirection: "column",
@@ -38,6 +38,11 @@ const useStyles = createUseStyles({
   },
 });
 
+/**
+ * Container for handling toast messages
+ *
+ * @category Components
+ */
 const Toasts = (props: Props) => {
   const { toasts } = props;
   const classes = useStyles();

package/Toasts/toastHelpers.ts

@@ -2,6 +2,10 @@ import { Draft } from "immer";
 import { Toast, ToastProps, ToastRemoveAppAction } from "./types";
 import { AppStateWithToasts, DispatchFunc } from "../";
 
+/**
+ * Wrap a reducer's dispatch function to create the dismissToast function for a
+ * component
+ */
 export function createDismissToast(dispatch: DispatchFunc<ToastRemoveAppAction>) {
   const dismissToast = (toastId: number) => {
     dispatch({ toastId, type: "dismissToast" });
@@ -12,12 +16,18 @@ export function createDismissToast(dispatch: DispatchFunc<ToastRemoveAppAction>)
   return dismissToast;
 }
 
+/**
+ * Handle toasts received from the server, or generated by an action
+ */
 export function handleToasts<T extends AppStateWithToasts>(draft: Draft<T>, toasts: Toast[]) {
   if (toasts.length > 0) {
     toasts.forEach(toast => addToast(draft, toast));
   }
 }
 
+/**
+ * Add a toast to the current toasts container
+ */
 export function addToast<T extends AppStateWithToasts>(draft: Draft<T>, toastOptions: Toast) {
   const { body, id, status, timeout, title } = toastOptions;
 
@@ -42,6 +52,9 @@ export function addToast<T extends AppStateWithToasts>(draft: Draft<T>, toastOpt
   draft.toasts.push(toast);
 }
 
+/**
+ * Remove a toast from the current toasts container
+ */
 export function removeToast<T extends AppStateWithToasts>(draft: Draft<T>, toast: ToastProps) {
   const beforeToasts: ToastProps[] = [];
   const afterToasts: ToastProps[] = [];
@@ -61,6 +74,10 @@ export function removeToast<T extends AppStateWithToasts>(draft: Draft<T>, toast
   });
 }
 
+/**
+ * Remove a toast from the current toasts container corresponding to a specific
+ * known toastId (usually, a static toast generated by the server)
+ */
 export function removeToastById<T extends AppStateWithToasts>(draft: Draft<T>, toastId: number) {
   const toast = draft.toasts.find(t => t.id === toastId);
 

package/docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

package/docs/assets/hierarchy.js

@@ -0,0 +1 @@
+window.hierarchyData = "eJyVkrFuwyAQht/lZtIWxziWtzRS1KVqh25VBsu+yCiYq4CoQ+R378VDiqJYgoUB7uf7juMCjih4aL5lUYpNdRDg8GiwC5osb19A1dfVtiNCA1/U+vDp6MeDgJO2PTSFqgScneFTbQO6Y9uhf/4vfBrCaLi6M63nCyH4fnVNrm7VMAnYVPeUFEDC3Xw4aNM7tNyjqg/M4k4j2J5s2P6ipxFTGrsvz1WQazk7rGXksCOH2/nJX88hkE0ReZjJtikrISslZK1E8VLMZmU8ipjwxj8jxexhJu0bsMsC/B3DQH0uPkolCtRLAh92Z3R3yjWIY2kKPIcFhT25MZd/y6TAp+kPKrFfRA=="

package/docs/assets/highlight.css

@@ -0,0 +1,99 @@
+:root {
+    --light-hl-0: #AF00DB;
+    --dark-hl-0: #C586C0;
+    --light-hl-1: #000000;
+    --dark-hl-1: #D4D4D4;
+    --light-hl-2: #0000FF;
+    --dark-hl-2: #569CD6;
+    --light-hl-3: #A31515;
+    --dark-hl-3: #CE9178;
+    --light-hl-4: #795E26;
+    --dark-hl-4: #DCDCAA;
+    --light-hl-5: #001080;
+    --dark-hl-5: #9CDCFE;
+    --light-hl-6: #800000;
+    --dark-hl-6: #808080;
+    --light-hl-7: #800000;
+    --dark-hl-7: #569CD6;
+    --light-hl-8: #E50000;
+    --dark-hl-8: #9CDCFE;
+    --light-hl-9: #0000FF;
+    --dark-hl-9: #CE9178;
+    --light-hl-10: #0451A5;
+    --dark-hl-10: #9CDCFE;
+    --light-code-background: #FFFFFF;
+    --dark-code-background: #1E1E1E;
+}
+
+@media (prefers-color-scheme: light) { :root {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
+    --hl-10: var(--light-hl-10);
+    --code-background: var(--light-code-background);
+} }
+
+@media (prefers-color-scheme: dark) { :root {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
+    --hl-10: var(--dark-hl-10);
+    --code-background: var(--dark-code-background);
+} }
+
+:root[data-theme='light'] {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
+    --hl-10: var(--light-hl-10);
+    --code-background: var(--light-code-background);
+}
+
+:root[data-theme='dark'] {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
+    --hl-10: var(--dark-hl-10);
+    --code-background: var(--dark-code-background);
+}
+
+.hl-0 { color: var(--hl-0); }
+.hl-1 { color: var(--hl-1); }
+.hl-2 { color: var(--hl-2); }
+.hl-3 { color: var(--hl-3); }
+.hl-4 { color: var(--hl-4); }
+.hl-5 { color: var(--hl-5); }
+.hl-6 { color: var(--hl-6); }
+.hl-7 { color: var(--hl-7); }
+.hl-8 { color: var(--hl-8); }
+.hl-9 { color: var(--hl-9); }
+.hl-10 { color: var(--hl-10); }
+pre, code { background: var(--code-background); }