@dr.pogodin/react-utils 1.25.6 → 1.26.0

package/src/shared/components/MetaTags.tsx

@@ -0,0 +1,170 @@
+import PT from 'prop-types';
+import { type ReactNode, createContext, useMemo } from 'react';
+import { Helmet } from 'react-helmet';
+
+type PropsT = {
+  children?: ReactNode;
+  description: string;
+  image?: string;
+  siteName?: string;
+  socialDescription?: string;
+  socialTitle?: string;
+  title: string;
+  url?: string;
+};
+
+const Context = createContext<PropsT>({
+  description: '',
+  title: '',
+});
+
+/**
+ * The `<MetaTags>` component is an auxiliary wrapper around `react-helmet`,
+ * which helps to inject meta tags (page title, a brief content description,
+ * and social media thumbnails) into generated pages.
+ *
+ * When `<MetaTags>` are nested within the app's component tree, meta tags
+ * content injected by components encountered down the tree overrides tags
+ * injected by previously encountered `<MetaTags>` components.
+ *
+ * **Children:** `<MetaTags>` children, if any, are rendered at the component's
+ * location. The context passes down all meta tag properties of parent
+ * `<MetaTag>` instances. These properties can fetched within children
+ * hierarchy in the following way, thus facilitating tags modification by
+ * children:
+ * ```jsx
+ * import { useContext } from 'react';
+ * import { MetaTags } from '@dr.pogodin/react-utils';
+ * export default function SampleComponent() {
+ *   const { title, description, ...rest } = useContext(MetaTags.Context);
+ *   // Do something with these props here, e.g. prefix the page title with
+ *   // the component name:
+ *   return (
+ *     <MetaTags title={`Sample component - ${title}`} />
+ *   );
+ * }
+ * ```
+ * @param [props]
+ * @param [props.description] Page description to use in
+ * the `description` meta tag, and as a default description of Open Graph Tags.
+ * @param [props.image] The absolute URL of thumbnail image to use
+ * in Open Graph Tags (`twitter:image`, and `og:image`). By default these tags
+ * are not injected.
+ *
+ * **BEWARE:** It must be a complete, absolute URL, including the correct
+ * website domain and HTTP schema.
+ *
+ * @param [props.siteName]: The site name to use in `twitter:site`,
+ * and `og:sitename` tags. By default these tags are not injected.
+ *
+ * @param [props.socialDescription] The site description to use in
+ * `twitter:description` and `og:description` meta tags. By default the value of
+ * `description` prop is used.
+ * @param [props.socialTitle] The page title to use in
+ * `twitter:title`, `og:title`, and `og:image:alt` tags. By default the value of
+ * `title` prop is used. Also the `og:image:alt` tag is only injected if `image`
+ * prop is present.
+ *
+ * @param props.title: The page name to use in the `<title>` tag.
+ * It is also used as the default value of `socialTitle` prop.
+ *
+ * @param [props.url] The page URL to use in `og:url` tag.
+ * By default the tag is not injected.
+ */
+const MetaTags: React.FunctionComponent<PropsT> & {
+  Context: React.Context<PropsT>;
+} = ({
+  children,
+  description,
+  image,
+  siteName,
+  socialDescription,
+  socialTitle,
+  title,
+  url,
+}) => {
+  const socTitle = socialTitle || title;
+  const socDesc = socialDescription || description;
+
+  const context = useMemo(() => ({
+    description,
+    image,
+    siteName,
+    socialDescription,
+    socialTitle,
+    title,
+    url,
+  }), [
+    description,
+    image,
+    siteName,
+    socialDescription,
+    socialTitle,
+    title,
+    url,
+  ]);
+
+  return (
+    <>
+      <Helmet>
+        {/* General tags. */}
+        <title>
+          {title}
+        </title>
+        <meta name="description" content={description} />
+
+        {/* Twitter cards. */}
+        <meta name="twitter:card" content="summary_large_image" />
+        <meta name="twitter:title" content={socTitle} />
+        <meta name="twitter:description" content={socDesc} />
+        { image ? <meta name="twitter:image" content={image} /> : null }
+        {
+          siteName ? (
+            <meta name="twitter:site" content={`@${siteName}`} />
+          ) : null
+        }
+
+        {/* Open Graph data. */}
+        <meta name="og:title" content={socTitle} />
+        { image ? <meta name="og:image" content={image} /> : null }
+        { image ? <meta name="og:image:alt" content={socTitle} /> : null }
+        <meta name="og:description" content={socDesc} />
+        {
+          siteName ? (<meta name="og:sitename" content={siteName} />) : null
+        }
+        { url ? (<meta name="og:url" content={url} />) : null }
+      </Helmet>
+      {
+        children ? (
+          <Context.Provider value={context}>
+            {children}
+          </Context.Provider>
+        ) : null
+      }
+    </>
+  );
+};
+
+MetaTags.Context = Context;
+
+MetaTags.defaultProps = {
+  children: null,
+  image: '',
+  siteName: '',
+  socialDescription: '',
+  socialTitle: '',
+  url: '',
+};
+
+MetaTags.propTypes = {
+  children: PT.node,
+  description: PT.string.isRequired,
+  image: PT.string,
+  siteName: PT.string,
+  socialDescription: PT.string,
+  socialTitle: PT.string,
+  title: PT.string.isRequired,
+  url: PT.string,
+};
+
+export default MetaTags;

package/src/shared/components/Modal/base-theme.scss

@@ -0,0 +1,38 @@
+@import "styles/mixins";
+
+*,
+.context,
+.ad.hoc {
+  &.overlay {
+    background: #eee;
+    height: 100%;
+    left: 0;
+    opacity: 0.8;
+    position: fixed;
+    top: 0;
+    width: 100%;
+    z-index: 998;
+
+    &:focus { outline: none; }
+  }
+
+  &.container {
+    background: #fff;
+    box-shadow: 0 0 14px 1px rgba(38 38 40 / 15%);
+    border-radius: 4;
+    max-height: 95vh;
+    max-width: $screen-md;
+    overflow: hidden;
+    padding: 0.6em 1.2em;
+    width: 480px;
+    position: fixed;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    z-index: 999;
+
+    @include xs-to-lg {
+      max-width: 95vw;
+    }
+  }
+}

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

@@ -0,0 +1,144 @@
+/* global document */
+
+import { noop } from 'lodash';
+
+import {
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import ReactDom from 'react-dom';
+import PT from 'prop-types';
+import themed, { type Theme } from '@dr.pogodin/react-themes';
+
+import baseTheme from './base-theme.scss';
+import './styles.scss';
+
+type PropsT = {
+  children?: ReactNode;
+  onCancel?: () => void;
+  theme: Theme & {
+    container?: string;
+    overlay?: string;
+  };
+};
+
+/**
+ * The `<Modal>` component implements a simple themeable modal window, wrapped
+ * into the default theme. `<BaseModal>` exposes the base non-themed component.
+ * **Children:** Component children are rendered as the modal content.
+ * @param {object} props Component properties. Beside props documented below,
+ *  [Other theming properties](https://www.npmjs.com/package/@dr.pogodin/react-themes#themed-component-properties) are supported as well.
+ * @param {function} [props.onCancel] The callback to trigger when user
+ * clicks outside the modal, or presses Escape. It is expected to hide the
+ * modal.
+ * @param {ModalTheme} [props.theme] _Ad hoc_ theme.
+ */
+const BaseModal: React.FunctionComponent<PropsT> = ({
+  children,
+  onCancel,
+  theme,
+}) => {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const overlayRef = useRef<HTMLDivElement | null>(null);
+  const [portal, setPortal] = useState<HTMLDivElement>();
+
+  useEffect(() => {
+    const p = document.createElement('div');
+    document.body.classList.add('scrolling-disabled-by-modal');
+    document.body.appendChild(p);
+    setPortal(p);
+    return () => {
+      document.body.classList.remove('scrolling-disabled-by-modal');
+      document.body.removeChild(p);
+    };
+  }, []);
+
+  const focusLast = useMemo(() => (
+    <div
+      onFocus={() => {
+        const elems = containerRef.current?.querySelectorAll('*') as NodeListOf<HTMLElement>;
+        for (let i = elems.length - 1; i >= 0; --i) {
+          elems[i].focus();
+          if (document.activeElement === elems[i]) return;
+        }
+        overlayRef.current?.focus();
+      }}
+      /* eslint-disable jsx-a11y/no-noninteractive-tabindex */
+      tabIndex={0}
+      /* eslint-enable jsx-a11y/no-noninteractive-tabindex */
+    />
+  ), []);
+
+  return portal ? ReactDom.createPortal(
+    (
+      <>
+        {focusLast}
+        <div
+          aria-label="Cancel"
+          className={theme.overlay}
+          onClick={() => onCancel && onCancel()}
+          onKeyDown={(e) => {
+            if (e.key === 'Escape' && onCancel) onCancel();
+          }}
+          ref={(node) => {
+            if (node && node !== overlayRef.current) {
+              overlayRef.current = node;
+              node.focus();
+            }
+          }}
+          role="button"
+          tabIndex={0}
+        />
+        <div
+          aria-modal="true"
+          className={theme.container}
+          onWheel={(event) => event.stopPropagation()}
+          ref={containerRef}
+          role="dialog"
+        >
+          {children}
+        </div>
+        <div
+          onFocus={() => {
+            overlayRef.current?.focus();
+          }}
+          /* eslint-disable jsx-a11y/no-noninteractive-tabindex */
+          tabIndex={0}
+          /* eslint-enable jsx-a11y/no-noninteractive-tabindex */
+        />
+        {focusLast}
+      </>
+    ),
+    portal,
+  ) : null;
+};
+
+const ThemedModal = themed(
+  BaseModal,
+  'Modal',
+  [
+    'container',
+    'overlay',
+  ],
+  baseTheme,
+);
+
+BaseModal.propTypes = {
+  onCancel: PT.func,
+  children: PT.node,
+  theme: ThemedModal.themeType.isRequired,
+};
+
+BaseModal.defaultProps = {
+  onCancel: noop,
+  children: null,
+};
+
+export default ThemedModal;
+
+/* Non-themed version of the Modal. */
+export { BaseModal };

package/src/shared/components/Modal/styles.scss

@@ -0,0 +1,5 @@
+:global {
+  body.scrolling-disabled-by-modal {
+    overflow: hidden;
+  }
+}

package/src/shared/components/NavLink.tsx

@@ -0,0 +1,13 @@
+import { NavLink as RrNavLink } from 'react-router-dom';
+
+import GenericLink, { type PropsT as GenericLinkPropsT } from './GenericLink';
+
+type PropsT = Omit<GenericLinkPropsT, 'routerLinkType'>;
+
+const NavLink: React.FunctionComponent<PropsT> = (props) => (
+  /* eslint-disable react/jsx-props-no-spreading */
+  <GenericLink {...props} routerLinkType={RrNavLink} />
+  /* eslint-enable react/jsx-props-no-spreading */
+);
+
+export default NavLink;

package/src/shared/components/PageLayout/base-theme.scss

@@ -0,0 +1,30 @@
+/**
+ * Base theme: symmetric 3-columns layout, with the center column occupying all
+ * screen up to mid screen size. For larger screen sizes the main column is
+ * limited by the mid screen size, and the free space is filled with side
+ * columns on left and right.
+ */
+
+@import "styles/mixins";
+
+*,
+.context,
+.ad.hoc {
+  &.container {
+    display: flex;
+    min-height: 100vh;
+    overflow: hidden;
+    width: 100%;
+  }
+
+  &.mainPanel {
+    overflow: hidden;
+    padding: 1.2em;
+    width: $screen-md;
+  }
+
+  &.sidePanel {
+    flex: 1;
+    overflow: hidden;
+  }
+}

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

@@ -0,0 +1,76 @@
+import PT from 'prop-types';
+import type { ReactNode } from 'react';
+
+import themed, { type Theme } from '@dr.pogodin/react-themes';
+
+import baseTheme from './base-theme.scss';
+
+type PropsT = {
+  children?: ReactNode;
+  leftSidePanelContent?: ReactNode;
+  rightSidePanelContent?: ReactNode;
+  theme: Theme & {
+    container?: string;
+    mainPanel?: string;
+    sidePanel?: string;
+    leftSidePanel?: string;
+    rightSidePanel?: string;
+  };
+};
+
+/**
+ * Simple and themeable page layout. It keeps the main content centered in
+ * a column of limited width, which fills entire viewport on small screens
+ * (under `$screen-md = 1024px` size). At larger screens the column keeps
+ * `$screen-md` size, and it is centered at the page, surrounded by side
+ * panels, where additional content can be displayed.
+ *
+ * **Children:** Component children are rendered as the content of main panel.
+ * @param {object} [props] Component properties.
+ * @param {Node} [props.leftSidePanelContent] The content for left side panel.
+ * @param {Node} [props.rightSidePanelContent] The content for right side panel.
+ * @param {PageLayoutTheme} [props.theme] _Ad hoc_ theme.
+ * @param {...any} [props....]
+ * [Other theming properties](https://www.npmjs.com/package/@dr.pogodin/react-themes#themed-component-properties)
+ */
+const PageLayout: React.FunctionComponent<PropsT> = ({
+  children,
+  leftSidePanelContent,
+  rightSidePanelContent,
+  theme,
+}) => (
+  <div className={theme.container}>
+    <div className={[theme.sidePanel, theme.leftSidePanel].join(' ')}>
+      {leftSidePanelContent}
+    </div>
+    <div className={theme.mainPanel}>
+      {children}
+    </div>
+    <div className={[theme.sidePanel, theme.rightSidePanel].join(' ')}>
+      {rightSidePanelContent}
+    </div>
+  </div>
+);
+
+const ThemedPageLayout = themed(PageLayout, 'PageLayout', [
+  'container',
+  'leftSidePanel',
+  'mainPanel',
+  'rightSidePanel',
+  'sidePanel',
+], baseTheme);
+
+PageLayout.propTypes = {
+  children: PT.node,
+  leftSidePanelContent: PT.node,
+  rightSidePanelContent: PT.node,
+  theme: ThemedPageLayout.themeType.isRequired,
+};
+
+PageLayout.defaultProps = {
+  children: null,
+  leftSidePanelContent: null,
+  rightSidePanelContent: null,
+};
+
+export default ThemedPageLayout;

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

@@ -0,0 +1,84 @@
+import PT from 'prop-types';
+import { type ReactNode } from 'react';
+
+import './style.scss';
+
+type PropsT = {
+  children?: ReactNode;
+  className?: string;
+  ratio?: `${number}:${number}`,
+};
+
+/**
+ * The `<ScalableRect>` component implements container keeping given aspect
+ * ratio, while its width is altered.
+ *
+ * **Children:** Component children are rendered as the component's content.
+ * @param {object} props
+ * @param {string} [props.className] CSS class for component container.
+ * @param {string} [props.ratio=1:1] Ratio of the rendered rectangle sides,
+ * in `W:H` form.
+ */
+const ScalableRect: React.FunctionComponent<PropsT> = ({
+  children,
+  className,
+  ratio,
+}) => {
+  const aux = ratio!.split(':');
+  const paddingBottom = `${(100 * parseFloat(aux[1])) / parseFloat(aux[0])}%`;
+
+  /* NOTE: In case the following code looks strange to you, mind that we want to
+   * allow the user to set custom styles on this component. If user passes in a
+   * "className" prop (possibly "styleName", but that one is converted to
+   * "className" by Babel just before being passed into this component), it
+   * should not interfere with the sizing behavior, thus we need an extra <div>
+   * level in this component; however, if user does not need a custom styling,
+   * we can save one level of HTML code, so we do it. */
+  const rect = (
+    <div
+      style={{ paddingBottom }}
+      styleName="container"
+    >
+      <div styleName="wrapper">
+        {children}
+      </div>
+    </div>
+  );
+  return className ? (
+    <div className={className}>
+      {rect}
+    </div>
+  ) : rect;
+};
+
+ScalableRect.defaultProps = {
+  children: null,
+  className: undefined,
+  ratio: '1:1',
+};
+
+ScalableRect.propTypes = {
+  children: PT.node,
+  className: PT.string,
+  ratio: (props, name) => {
+    const ratio = props[name];
+
+    // "ratio" prop is not required (defaults "1:1").
+    if (ratio === undefined) return null;
+
+    // If given, "ratio" must be a string.
+    if (typeof ratio !== 'string') {
+      return Error('"ratio" prop must be a string');
+    }
+
+    // If given, "ratio" must have "H:W" format.
+    if (!ratio.match(/\d\.\d+/)) {
+      return Error('"ratio" prop must have "H:W" format');
+    }
+
+    // Everything looks right.
+    return null;
+  },
+};
+
+export default ScalableRect;

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

@@ -0,0 +1,10 @@
+.container {
+  position: relative;
+  width: 100%;
+}
+
+.wrapper {
+  height: 100%;
+  position: absolute;
+  width: 100%;
+}

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

@@ -0,0 +1,43 @@
+import themed, { type Theme } from '@dr.pogodin/react-themes';
+
+import defaultTheme from './theme.scss';
+
+type PropsT = {
+  theme: Theme & {
+    container?: string;
+    circle?: string;
+  };
+};
+
+/**
+ * Throbber is an "action in progress" indicator, which renders
+ * three bouncing circles as a simple pending activity indicator,
+ * and can be further themed to a certain degree.
+ * @param {object} [props] Component properties.
+ * @param {ThrobberTheme} [props.theme] _Ad hoc_ theme.
+ * @param {...any} [props....]
+ * [Other theming properties](https://www.npmjs.com/package/@dr.pogodin/react-themes#themed-component-properties)
+ */
+const Throbber: React.FunctionComponent<PropsT> = ({ theme }) => (
+  <span className={theme.container} styleName="container">
+    <span className={theme.circle} styleName="circle" />
+    <span className={theme.circle} styleName="circle" />
+    <span className={theme.circle} styleName="circle" />
+  </span>
+);
+
+const ThemedThrobber = themed(
+  Throbber,
+  'Throbber',
+  [
+    'circle',
+    'container',
+  ],
+  defaultTheme,
+);
+
+Throbber.propTypes = {
+  theme: ThemedThrobber.themeType.isRequired,
+};
+
+export default ThemedThrobber;

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

@@ -0,0 +1,26 @@
+*,
+.context,
+.ad.hoc {
+  &.container {
+    display: inline-block;
+  }
+
+  &.circle {
+    @keyframes bouncing {
+      from { top: -0.3em; }
+      to { top: 0.3em; }
+    }
+
+    animation: bouncing 0.4s ease-in infinite alternate;
+    background: black;
+    border-radius: 0.3em;
+    display: inline-block;
+    height: 0.6em;
+    margin: 0 0.1em;
+    position: relative;
+    width: 0.6em;
+
+    &:first-child { animation-delay: -0.2s; }
+    &:last-child { animation-delay: 0.2s; }
+  }
+}