@dr.pogodin/react-utils 1.25.5 → 1.26.0

package/src/shared/components/Checkbox/index.tsx

@@ -0,0 +1,71 @@
+import PT from 'prop-types';
+
+import themed, { type Theme } from '@dr.pogodin/react-themes';
+
+import defaultTheme from './theme.scss';
+
+type PropT = {
+  checked?: boolean;
+  label?: string;
+  onChange?: React.ChangeEventHandler<HTMLInputElement>;
+  theme: Theme & {
+    checkbox?: string;
+    container?: string
+    label?: string;
+  };
+};
+
+const Checkbox: React.FunctionComponent<PropT> = ({
+  checked,
+  label,
+  onChange,
+  theme,
+}) => (
+  <div className={theme.container}>
+    { label === undefined ? null : <p className={theme.label}>{label}</p> }
+    <input
+      checked={checked}
+      className={theme.checkbox}
+      onChange={onChange}
+      type="checkbox"
+    />
+  </div>
+);
+
+/**
+ * Checkbox component theme: a map of
+ * CSS classes to append to its elements:
+ * @prop [checkbox] to the underlying checkbox `<input>` element.
+ * @prop [container] to the root checkbox element.
+ * @prop [label] to the checkbox label element.
+ */
+const ThemedCheckbox = themed(Checkbox, 'Checkbox', [
+  'checkbox',
+  'container',
+  'label',
+], defaultTheme);
+
+/**
+ * The `<Checkbox>` component implements themeable checkboxes.
+ * @param [props] Component properties.
+ * @param [props.checked] Checkbox value.
+ * @param [props.label] Checkbox label.
+ * @param [props.onChange] State change handler.
+ * @param [props.theme] _Ad hoc_ theme.
+ * @param [props....]
+ * [Other properties of themeable components](https://www.npmjs.com/package/@dr.pogodin/react-themes#themed-component-properties).
+ */
+Checkbox.propTypes = {
+  checked: PT.bool,
+  label: PT.string,
+  onChange: PT.func,
+  theme: ThemedCheckbox.themeType.isRequired,
+};
+
+Checkbox.defaultProps = {
+  checked: undefined,
+  label: undefined,
+  onChange: undefined,
+};
+
+export default ThemedCheckbox;

package/src/shared/components/Checkbox/theme.scss

@@ -0,0 +1,43 @@
+*,
+.context,
+.ad.hoc {
+  &.checkbox {
+    appearance: none;
+    background: white;
+    border: 1px solid gray;
+    border-radius: 0.3em;
+    cursor: pointer;
+    font: inherit;
+    height: 1.5em;
+    outline: none;
+    margin: 0;
+    width: 1.5em;
+
+    &:checked {
+      &::after {
+        background: black;
+        border-radius: 0.3em;
+        content: "";
+        display: block;
+        height: 1em;
+        margin: 0.2em;
+        width: 1em;
+      }
+    }
+
+    &:focus {
+      border-color: blue;
+      box-shadow: 0 0 3px 1px lightblue;
+    }
+  }
+
+  &.container {
+    align-items: center;
+    display: inline-flex;
+    margin: 0.1em;
+  }
+
+  &.label {
+    margin: 0 0.6em 0 1.5em;
+  }
+}

package/src/shared/components/Dropdown/index.tsx

@@ -0,0 +1,144 @@
+import PT from 'prop-types';
+
+import themed, { type Theme } from '@dr.pogodin/react-themes';
+
+import defaultTheme from './theme.scss';
+
+type DropdownOptionT = {
+  name?: string | null;
+  value: string;
+};
+
+type PropsT = {
+  filter?: (item: DropdownOptionT | string) => boolean;
+  label?: string;
+  onChange?: React.ChangeEventHandler<HTMLSelectElement>;
+  options?: Array<DropdownOptionT | string>;
+  theme: Theme & {
+    arrow?: string;
+    container?: string;
+    hiddenOption?: string;
+    label?: string;
+    option?: string;
+    select?: string;
+  };
+  value?: string;
+};
+
+/**
+ * Implements a themeable dropdown list. Internally it is rendered with help of
+ * the standard HTML `<select>` element, thus the styling support is somewhat
+ * limited.
+ * @param [props] Component properties.
+ * @param [props.filter] Options filter function. If provided, only
+ * those elements of `options` list will be used by the dropdown, for which this
+ * filter returns `true`.
+ * @param [props.label] Dropdown label.
+ * @param [props.onChange] Selection event handler.
+ * @param [props.options=[]] Array of dropdown
+ * options. For string elements the option value and name will be the same.
+ * It is allowed to mix DropdownOption and string elements in the same option
+ * list.
+ * @param [props.theme] _Ad hoc_ theme.
+ * @param [props.value] Currently selected value.
+ * @param [props....]
+ * [Other theming properties](https://www.npmjs.com/package/@dr.pogodin/react-themes#themed-component-properties)
+ */
+const Dropdown: React.FunctionComponent<PropsT> = ({
+  filter,
+  label,
+  onChange,
+  options = [],
+  theme,
+  value,
+}) => {
+  let isValidValue = false;
+  const optionElements = [];
+
+  for (let i = 0; i < options.length; ++i) {
+    const option = options[i];
+    if (!filter || filter(option)) {
+      let optionValue: string;
+      let optionName: string;
+      if (typeof option === 'string') {
+        optionName = option;
+        optionValue = option;
+      } else {
+        optionName = option.name || option.value;
+        optionValue = option.value;
+      }
+      isValidValue ||= optionValue === value;
+      optionElements.push(
+        <option className={theme.option} key={optionValue} value={optionValue}>
+          {optionName}
+        </option>,
+      );
+    }
+  }
+
+  // NOTE: This element represents the current `value` when it does not match
+  // any valid option. In Chrome, and some other browsers, we are able to hide
+  // it from the opened dropdown; in others, e.g. Safari, the best we can do is
+  // to show it as disabled.
+  const hiddenOption = isValidValue ? null : (
+    <option
+      disabled
+      className={theme.hiddenOption}
+      key="__reactUtilsHiddenOption"
+      value={value}
+    >
+      {value}
+    </option>
+  );
+
+  return (
+    <div className={theme.container}>
+      { label === undefined ? null : <p className={theme.label}>{label}</p> }
+      <select
+        className={theme.select}
+        onChange={onChange}
+        value={value}
+      >
+        {hiddenOption}
+        {optionElements}
+      </select>
+      <div className={theme.arrow}>▼</div>
+    </div>
+  );
+};
+
+const ThemedDropdown = themed(Dropdown, 'Dropdown', [
+  'arrow',
+  'container',
+  'hiddenOption',
+  'label',
+  'option',
+  'select',
+], defaultTheme);
+
+Dropdown.propTypes = {
+  filter: PT.func,
+  label: PT.string,
+  onChange: PT.func,
+  options: PT.arrayOf(
+    PT.oneOfType([
+      PT.shape({
+        name: PT.string,
+        value: PT.string.isRequired,
+      }),
+      PT.string,
+    ]).isRequired,
+  ),
+  theme: ThemedDropdown.themeType.isRequired,
+  value: PT.string,
+};
+
+Dropdown.defaultProps = {
+  filter: undefined,
+  label: undefined,
+  onChange: undefined,
+  options: [],
+  value: '',
+};
+
+export default ThemedDropdown;

package/src/shared/components/Dropdown/theme.scss

@@ -0,0 +1,63 @@
+@import "styles/mixins";
+
+*,
+.context,
+.ad.hoc {
+  &.arrow {
+    background-image: linear-gradient(to top, lightgray, white 50%, white);
+    border: 1px solid gray;
+    border-radius: 0 0.3em 0.3em 0;
+    padding: 0.3em 0.6em;
+    pointer-events: none;
+    position: absolute;
+    right: 0;
+  }
+
+  &.container {
+    align-items: center;
+    display: inline-flex;
+    margin: 0.1em;
+    position: relative;
+  }
+
+  :active + &.arrow {
+    background-image: linear-gradient(to bottom, lightgray, white 50%, white);
+    border-bottom-right-radius: 0;
+  }
+
+  :focus + &.arrow {
+    border-color: blue;
+    border-left-color: gray;
+  }
+
+  &.label {
+    margin: 0 0.6em 0 1.5em;
+  }
+
+  &.option { /* Empty style */ }
+  &.hiddenOption { display: none; }
+
+  &.select {
+    appearance: none;
+    background: white;
+    border: 1px solid gray;
+    border-radius: 0.3em;
+    color: inherit;
+    cursor: pointer;
+    display: inline-block;
+    font: inherit;
+    outline: none;
+    padding: 0.3em 3.3em calc(0.3em + 1px) 1.2em;
+
+    &:active {
+      background: white;
+      border-bottom-left-radius: 0;
+      border-bottom-right-radius: 0;
+    }
+
+    &:focus {
+      border-color: blue;
+      box-shadow: 0 0 3px 1px lightblue;
+    }
+  }
+}

package/src/shared/components/GenericLink/index.tsx

@@ -0,0 +1,157 @@
+/* global window */
+
+import PT from 'prop-types';
+import { type ReactNode } from 'react';
+
+import { type Link, type NavLink } from 'react-router-dom';
+
+import './style.scss';
+
+type ToT = Parameters<typeof Link>[0]['to'];
+
+interface LinkI {}
+
+export type PropsT = {
+  children?: ReactNode;
+  className?: string;
+  disabled?: boolean;
+  enforceA?: boolean;
+  keepScrollPosition?: boolean;
+  onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+  onMouseDown?: React.MouseEventHandler<HTMLAnchorElement>;
+  openNewTab?: boolean;
+  replace?: boolean;
+  routerLinkType: LinkI;
+  to?: ToT;
+};
+
+/**
+ * The `<Link>` component, and almost identical `<NavLink>` component, are
+ * auxiliary wrappers around
+ * [React Router](https://github.com/ReactTraining/react-router)'s
+ * `<Link>` and `<NavLink>` components; they help to handle external and
+ * internal links in uniform manner.
+ *
+ * @param [props] Component properties.
+ * @param [props.className] CSS classes to apply to the link.
+ * @param [props.disabled] Disables the link.
+ * @param [props.enforceA] `true` enforces rendering of the link as
+ * a simple `<a>` element.
+ * @param [props.keepScrollPosition] If `true`, and the link is
+ * rendered as a React Router's component, it won't reset the viewport scrolling
+ * position to the origin when clicked.
+ * @param [props.onClick] Event handler to trigger upon click.
+ * @param [props.onMouseDown] Event handler to trigger on MouseDown
+ * event.
+ * @param [props.openNewTab] If `true` the link opens in a new tab.
+ * @param [props.replace] When `true`, the link will replace current
+ * entry in the history stack instead of adding a new one.
+ * @param [props.to] Link URL.
+ * @param [props.activeClassName] **`<NavLink>`** only: CSS class(es)
+ * to apply to rendered link when it is active.
+ * @param [props.activeStyle] **`<NavLink>`** only: CSS styles
+ * to apply to the rendered link when it is active.
+ * @param [props.exact] **`<NavLink>`** only: if `true`, the active
+ * class/style will only be applied if the location is matched exactly.
+ * @param [props.isActive] **`<NavLink>`** only: Add extra
+ * logic for determining whether the link is active. This should be used if you
+ * want to do more than verify that the link’s pathname matches the current URL
+ * pathname.
+ * @param [props.location] **`<NavLink>`** only: `isActive` compares
+ * current history location (usually the current browser URL). To compare to
+ * a different location, a custom `location` can be passed.
+ * @param [props.strict] **`<NavLink>`** only: . When `true`, trailing
+ * slash on a location’s pathname will be taken into consideration when
+ * determining if the location matches the current URL. See the `<Route strict>`
+ * documentation for more information.
+ */
+const GenericLink: React.FunctionComponent<PropsT> = ({
+  children,
+  className,
+  disabled,
+  enforceA,
+  keepScrollPosition,
+  onClick,
+  onMouseDown,
+  openNewTab,
+  replace,
+  routerLinkType,
+  to,
+  ...rest
+}) => {
+  /* Renders Link as <a> element if:
+   * - It is opted explicitely by `enforceA` prop;
+   * - It should be opened in a new tab;
+   * - It is an absolte URL (starts with http:// or https://);
+   * - It is anchor link (starts with #). */
+  if (disabled || enforceA || openNewTab || (to as string)?.match(/^(#|(https?|mailto):)/)) {
+    return (
+      <a
+        className={className}
+        // TODO: This requires a fix: disabled is not really an attribute of <a>
+        // tag, thus for disabled option we rather should render a plain text
+        // styled as a link.
+        // disabled={disabled}
+        href={to as string}
+        onClick={disabled ? (e) => e.preventDefault() : onClick}
+        onMouseDown={disabled ? (e) => e.preventDefault() : onMouseDown}
+        rel="noopener noreferrer"
+        styleName="link"
+        target={openNewTab ? '_blank' : ''}
+      >
+        {children}
+      </a>
+    );
+  }
+
+  const L = routerLinkType as typeof NavLink;
+
+  return (
+    <L
+      className={className}
+      // disabled
+      onMouseDown={onMouseDown}
+      replace={replace}
+      to={to!}
+      onClick={(e: React.MouseEvent<HTMLAnchorElement>) => {
+        // Executes the user-provided event handler, if any.
+        if (onClick) onClick(e);
+
+        // By default, clicking the link scrolls the page to beginning.
+        if (!keepScrollPosition) window.scroll(0, 0);
+      }}
+      {...rest} // eslint-disable-line react/jsx-props-no-spreading
+    >
+      {children}
+    </L>
+  );
+};
+
+GenericLink.defaultProps = {
+  children: null,
+  className: '',
+  disabled: false,
+  enforceA: false,
+  keepScrollPosition: false,
+  onClick: undefined,
+  onMouseDown: undefined,
+  openNewTab: false,
+  replace: false,
+  to: '',
+};
+
+GenericLink.propTypes = {
+  children: PT.node,
+  className: PT.string,
+  disabled: PT.bool,
+  enforceA: PT.bool,
+  keepScrollPosition: PT.bool,
+  onClick: PT.func,
+  onMouseDown: PT.func,
+  openNewTab: PT.bool,
+  replace: PT.bool,
+  routerLinkType: PT.elementType.isRequired,
+  to: PT.oneOfType([PT.object, PT.string]),
+};
+
+export default GenericLink;

package/src/shared/components/GenericLink/style.scss

@@ -0,0 +1,3 @@
+.link[disabled] {
+  cursor: not-allowed;
+}

package/src/shared/components/Input/index.tsx

@@ -0,0 +1,59 @@
+import PT from 'prop-types';
+import { forwardRef } from 'react';
+
+import themed, { type Theme } from '@dr.pogodin/react-themes';
+
+import defaultTheme from './theme.scss';
+
+type PropsT = React.InputHTMLAttributes<HTMLInputElement> & {
+  label?: string;
+  theme: Theme & {
+    container?: string;
+    input?: string;
+    label?: string;
+  };
+};
+
+/**
+ * Themeable input field, based on the standard HTML `<input>` element.
+ * @param [props]
+ * @param [props.label] Input label.
+ * @param [props.theme] _Ad hoc_ theme.
+ * @param [props...] [Other theming properties](https://www.npmjs.com/package/@dr.pogodin/react-themes#themed-component-properties)
+ * @param [props...] Any other properties are passed to the underlying
+ * `<input>` element.
+ */
+const Input = forwardRef<HTMLInputElement, PropsT>((
+  {
+    label,
+    theme,
+    ...rest
+  }: PropsT,
+  ref,
+) => (
+  <span className={theme.container}>
+    { label === undefined ? null : <p className={theme.label}>{label}</p> }
+    <input
+      className={theme.input}
+      ref={ref}
+      {...rest} // eslint-disable-line react/jsx-props-no-spreading
+    />
+  </span>
+));
+
+const ThemedInput = themed(Input, 'Input', [
+  'container',
+  'input',
+  'label',
+], defaultTheme);
+
+Input.propTypes = {
+  label: PT.string,
+  theme: ThemedInput.themeType.isRequired,
+};
+
+Input.defaultProps = {
+  label: undefined,
+};
+
+export default ThemedInput;

package/src/shared/components/Input/theme.scss

@@ -0,0 +1,27 @@
+*,
+.context,
+.ad.hoc {
+  &.container {
+    align-items: center;
+    display: inline-flex;
+    margin: 0.1em;
+  }
+
+  &.input {
+    border: 1px solid gray;
+    border-radius: 0.3em;
+    cursor: text;
+    font: inherit;
+    outline: none;
+    padding: 0.3em 0.3em calc(0.3em + 1px);
+
+    &:focus {
+      border-color: blue;
+      box-shadow: 0 0 3px 1px lightblue;
+    }
+  }
+
+  &.label {
+    margin: 0 0.6em 0 1.5em;
+  }
+}

package/src/shared/components/Link.tsx

@@ -0,0 +1,21 @@
+/**
+ * The Link wraps around React Router's Link component, to automatically replace
+ * it by the regular <a> element when:
+ * - The target reference points to another domain;
+ * - User opts to open the reference in a new tab;
+ * - User explicitely opts to use <a>.
+ */
+
+import { Link as RrLink } from 'react-router-dom';
+
+import GenericLink, { type PropsT as GenericLinkPropsT } from './GenericLink';
+
+type PropsT = Omit<GenericLinkPropsT, 'routerLinkType'>;
+
+const Link: React.FunctionComponent<PropsT> = (props) => (
+  /* eslint-disable react/jsx-props-no-spreading */
+  <GenericLink {...props} routerLinkType={RrLink} />
+  /* eslint-enable react/jsx-props-no-spreading */
+);
+
+export default Link;