@hyphen/hyphen-components 2.9.0

package/src/components/TextareaInputInset/TextareaInputInset.tsx

@@ -0,0 +1,213 @@
+import React, {
+  ChangeEvent,
+  forwardRef,
+  FocusEvent,
+  ForwardRefExoticComponent,
+  ReactNode,
+  HTMLProps,
+  InputHTMLAttributes,
+} from 'react';
+import classNames from 'classnames';
+import { ResponsiveProp } from '../../types';
+import { generateResponsiveClasses } from '../../lib/generateResponsiveClasses';
+
+import { Box, BoxProps } from '../Box/Box';
+import { HelpText } from '../HelpText/HelpText';
+import { getAutoCompleteValue } from '../../lib/getAutoCompleteValue';
+import styles from './TextareaInputInset.module.scss';
+import { InputValidationMessage } from '../InputValidationMessage/InputValidationMessage';
+
+export type TextareaInputInsetSize = 'md' | 'lg';
+export interface TextareaInputInsetProps {
+  /**
+   * The input's id attribute. Used to programmatically tie the input with its label.
+   */
+  id: string;
+  /**
+   * Custom content to be displayed above the input. If the label is hidden, will be used to set aria-label attribute.
+   */
+  label: string;
+  /**
+   * Callback function to call on change event.
+   */
+  onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+  /**
+   * The text value of the input. Required since our Input is a controlled component.
+   */
+  value: InputHTMLAttributes<HTMLInputElement>['value'];
+  /**
+   * Automatically focus the input when the page is loaded.
+   */
+  autoFocus?: boolean;
+  /**
+   * Custom class to be added to standard input classes.
+   */
+  className?: string;
+  /**
+   * Mark the input field as invalid and display a validation message.
+   * Pass a string or node to render a validation message below the input.
+   */
+  error?: ReactNode;
+  /**
+   * Additional clarifying text to help describe the input
+   */
+  helpText?: ReactNode;
+  /**
+   * Props passed directly to the input element of the component
+   */
+  inputProps?: BoxProps & HTMLProps<HTMLInputElement>;
+  /**
+   * The input's disabled attribute
+   */
+  isDisabled?: boolean;
+  /**
+   * The required and aria-required attributes on the input
+   */
+  isRequired?: boolean;
+  /**
+   * The input's 'maxlength' attribute.
+   * NOTE: initializing the input with a value longer than the desired maxlength will not trim this value.
+   */
+  maxLength?: number;
+  /**
+   * The input's 'name' attribute.
+   */
+  name?: string;
+  /**
+   * Callback function to call on blur event.
+   */
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
+  /**
+   * Callback function to call on focus event.
+   */
+  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+  /**
+   * The input placeholder attribute.
+   */
+  placeholder?: string;
+  /**
+   * An input helper rendered before the input field value
+   */
+  prefix?: ReactNode;
+  /**
+   * Visual indicator that the field is required, that gets appended to the label
+   */
+  requiredIndicator?: ReactNode;
+  /**
+   * Textarea resize behavior
+   */
+  resize?: 'vertical' | 'horizontal' | 'none' | 'both';
+  /**
+   * number of visible text lines for the control.
+   */
+  rows?: number;
+  /**
+   * The size of the text input.
+   */
+  size?: TextareaInputInsetSize | ResponsiveProp<TextareaInputInsetSize>;
+  /**
+   * An input helper rendered after the input field value
+   */
+  suffix?: ReactNode;
+  /**
+   * The input 'type' value. Defaults to type 'text'.
+   */
+  type?: InputHTMLAttributes<HTMLInputElement>['type'];
+  /**
+   * Additional props to be spread to rendered element
+   */
+  [x: string]: any; // eslint-disable-line
+}
+
+export const TextareaInputInset: ForwardRefExoticComponent<TextareaInputInsetProps> =
+  forwardRef<HTMLDivElement, TextareaInputInsetProps>(
+    (
+      {
+        id,
+        label,
+        onChange,
+        value,
+        autoComplete = false,
+        autoFocus = false,
+        className,
+        error = false,
+        helpText,
+        inputProps = {},
+        isDisabled = false,
+        isRequired = false,
+        maxLength = undefined,
+        name = '',
+        onBlur = undefined,
+        onFocus = undefined,
+        placeholder = ' ',
+        requiredIndicator = ' *',
+        resize = 'vertical',
+        rows = 5,
+        size = 'md',
+        type = 'text',
+      },
+      ref
+    ) => {
+      const responsiveClasses = generateResponsiveClasses('size', size);
+
+      const inputWrapperClasses = classNames(
+        'hyphen-components__variables__form-control',
+        styles['text-input-wrapper'],
+        ...responsiveClasses.map((c) => styles[c]),
+        {
+          [styles.disabled]: isDisabled,
+        }
+      );
+
+      const computedInputProps: TextareaInputInsetProps['inputProps'] = {
+        ...inputProps, // These are spread first so that we don't have top level props overwritten by the user.
+        'aria-required': isRequired,
+        'aria-invalid': !!error,
+        'aria-label': label,
+        'aria-labelledby': label ? `${id}Label` : undefined,
+        autoComplete: getAutoCompleteValue(autoComplete),
+        autoFocus,
+        className: classNames(styles[`textarea-resize-${resize}`], {
+          [styles.error]: error,
+        }),
+        disabled: isDisabled,
+        id,
+        maxLength,
+        name,
+        onBlur,
+        onChange,
+        onFocus,
+        placeholder,
+        required: isRequired,
+        rows,
+        type,
+        value,
+      };
+
+      return (
+        <Box width="100" ref={ref} className={className}>
+          <Box
+            display="block"
+            position="relative"
+            className={inputWrapperClasses}
+          >
+            <Box as="textarea" {...computedInputProps} />
+            <label
+              htmlFor={id}
+              className={styles['text-input-label']}
+              id={`${id}Label`}
+            >
+              {label}
+              {isRequired && requiredIndicator && (
+                <span>{requiredIndicator}</span>
+              )}
+            </label>
+          </Box>
+          {helpText && <HelpText>{helpText}</HelpText>}
+          {error && error !== true && (
+            <InputValidationMessage>{error}</InputValidationMessage>
+          )}
+        </Box>
+      );
+    }
+  );

package/src/components/ThemeProvider/ThemeProvider.mdx

@@ -0,0 +1,11 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/blocks';
+import { ThemeProvider } from './ThemeProvider';
+import * as Stories from './ThemeProvider.stories';
+
+<Meta of={Stories} />
+
+# ThemeProvider
+
+Allow users to set the theme for the entire application by adding the `ThemeProvider` to the root of the application.
+
+<Canvas of={Stories.BasicUsage} />

package/src/components/ThemeProvider/ThemeProvider.stories.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { ThemeProvider } from './ThemeProvider';
+import type { Meta } from '@storybook/react';
+import { Box } from '../Box/Box';
+import { RadioGroup } from '../RadioGroup/RadioGroup';
+import { useTheme, Theme } from './ThemeProvider';
+
+const meta: Meta<typeof ThemeProvider> = {
+  title: 'Providers/ThemeProvider',
+  component: ThemeProvider,
+};
+
+export default meta;
+
+export const BasicUsage = () =>
+  (() => {
+    const App = () => {
+      const { theme, setTheme } = useTheme();
+
+      const options = [
+        {
+          id: 'light',
+          value: 'light',
+          label: 'Light',
+        },
+        {
+          id: 'dark',
+          value: 'dark',
+          label: 'Dark',
+        },
+        {
+          id: 'system',
+          value: 'system',
+          label: 'System',
+        },
+      ];
+
+      return (
+        <Box gap="md" background="secondary" padding="xl" color="base">
+          <p>Theme: {theme}</p>
+
+          <RadioGroup
+            name="SelectTheme"
+            value={theme}
+            onChange={(event) => setTheme(event.target.value as Theme)}
+            options={options}
+          />
+        </Box>
+      );
+    };
+    return (
+      <ThemeProvider defaultTheme="light" storageKey="hyphen-ui-theme">
+        <App />
+      </ThemeProvider>
+    );
+  })();

package/src/components/ThemeProvider/ThemeProvider.tsx

@@ -0,0 +1,75 @@
+import React, { createContext, useState, useEffect, useContext } from 'react';
+
+export type Theme = 'dark' | 'light' | 'system';
+
+type ThemeProviderProps = {
+  children: React.ReactNode;
+  defaultTheme?: Theme;
+  storageKey?: string;
+};
+
+type ThemeProviderState = {
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+};
+
+const initialState: ThemeProviderState = {
+  theme: 'system',
+  setTheme: () => null,
+};
+
+const ThemeProviderContext = createContext<ThemeProviderState>(initialState);
+
+export function ThemeProvider({
+  children,
+  defaultTheme = 'system',
+  storageKey = 'hyphen-ui-theme',
+  ...props
+}: ThemeProviderProps) {
+  const [theme, setTheme] = useState<Theme>(
+    () => (localStorage.getItem(storageKey) as Theme) || defaultTheme
+  );
+
+  useEffect(() => {
+    const root = window.document.documentElement;
+
+    root.classList.remove('light', 'dark');
+
+    if (theme === 'system') {
+      const systemTheme = window.matchMedia('(prefers-color-scheme: dark)')
+        .matches
+        ? 'dark'
+        : 'light';
+
+      root.classList.add(systemTheme);
+      return;
+    }
+
+    root.classList.add(theme);
+  }, [theme]);
+
+  const value = {
+    theme,
+    setTheme: (theme: Theme) => {
+      localStorage.setItem(storageKey, theme);
+      setTheme(theme);
+    },
+  };
+
+  return (
+    <ThemeProviderContext.Provider {...props} value={value}>
+      {children}
+    </ThemeProviderContext.Provider>
+  );
+}
+
+export const useTheme = () => {
+  const context = useContext(ThemeProviderContext);
+
+  if (context === undefined)
+    throw new Error(
+      'useTheme must be used within a ThemeProvider. Be sure your App is wrapped in ThemeProvider.'
+    );
+
+  return context;
+};

package/src/components/TimePicker/TimePicker.mdx

@@ -0,0 +1,75 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/blocks';
+import { TimePicker } from './TimePicker';
+import * as Stories from './TimePicker.stories';
+
+<Meta of={Stories} />
+
+# TimePicker
+
+Use a TimePicker when you want users to select from a list of a available times agnostic of date.
+
+_NOTE:_ This component is abstracted from the [SelectInput](?path=/docs/components-selectinput-overview--default-story)
+and as such includes the same underlying props interface with an added method for generating the time options automatically.
+
+_ABOUT TIME FORMAT:_ While the `value` prop technically returns `{ label: string; value: string; }` the value returned will always
+be a JS ISO date string, like this: `2016-07-13T18:46:01.933Z`.
+
+## Props
+
+<ArgTypes of={TimePicker} />
+
+## Default
+
+<Canvas of={Stories.Default} />
+
+## With A Specific Interval
+
+Pass an `interval` (seconds) value to determine how many times get generated as options.
+The example below uses `3600` --> 1 Hour Intervals
+
+<Canvas of={Stories.WithASpecificInterval} />
+
+## With Min and Max Times
+
+You can determine the range of times to be shown by capping the start and end times.
+Use `startTime` and `endTime` for this. The expected values for `hour` and `minute` properties
+are `0-24` and `0-60` respectively.
+
+IMPORTANT: `startTime` is inclusive, and `endTime` is exclusive. This is to avoid
+the options showing the startTime twice when using a 24-hour cycle.
+
+See example below where we want to show 15 minute increments starting at 9:00AM and ending at 3:30PM.
+
+<Canvas of={Stories.WithMinAndMaxTimes} />
+
+## With Custom Date Display
+
+The labels for the dropdwon options are governed by JS `toLocaleTimeString`, and as such
+options are available to customize these.
+
+NOTE: that the option values are always returned as ISO strings regardless of the label display option.
+
+The example below is shown in military (24-hour) time.
+
+<Canvas of={Stories.WithCustomDateDisplay} />
+
+## With Open Menu
+
+The menu can be rendered open with the `menuIsOpen` prop. We do this here to confirm option generation
+via our UI visual snapshot testing (Chromatic).
+
+<Canvas of={Stories.WithOpenMenu} />
+
+## Help Text
+
+<Canvas of={Stories.HelpText} />
+
+## Sizes
+
+Set the size of the input to `sm`, `md` or `lg`. `md` is the default size.
+
+<Canvas of={Stories.Sizes} />
+
+## Component Design Tokens
+
+This component shares component design tokens with all form controls. For a complete list of tokens, see the [Theming Form Controls documentation](/docs/theming-form-controls--custom-theme-form).

package/src/components/TimePicker/TimePicker.stories.tsx

@@ -0,0 +1,149 @@
+import type { Meta } from '@storybook/react';
+import React, { ChangeEvent, useState } from 'react';
+import { TimePicker } from './TimePicker';
+import { Box } from '../Box/Box';
+
+const meta: Meta<typeof TimePicker> = {
+  title: 'Components/TimePicker',
+  component: TimePicker,
+  parameters: {
+    controls: { hideNoControlsWarning: true },
+  },
+};
+
+export default meta;
+
+export const Default = () => {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Box height="360px">
+      <TimePicker
+        id="defaultTimePicker"
+        name="defaultTimePicker"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          setValue(event.target.value);
+        }}
+        label="Pick a Time"
+        value={value}
+      />
+    </Box>
+  );
+};
+
+export const WithASpecificInterval = () => (
+  <Box height="360px">
+    <TimePicker
+      id="intervalTimePicker"
+      name="intervalTimePicker"
+      onChange={() => {}}
+      label="Pick a Time"
+      interval={3600}
+    />
+  </Box>
+);
+
+export const WithMinAndMaxTimes = () => (
+  <Box height="360px">
+    <TimePicker
+      id="startEnd"
+      name="startEnd"
+      onChange={() => {}}
+      label="Pick a Time"
+      startTime={{ hour: 9, minute: 0 }}
+      endTime={{ hour: 15, minute: 31 }}
+    />
+  </Box>
+);
+
+export const WithCustomDateDisplay = () => (
+  <Box height="360px">
+    <TimePicker
+      id="customDate"
+      name="customDate"
+      onChange={() => {}}
+      label="Pick a Time"
+      startTime={{ hour: 9, minute: 0 }}
+      endTime={{ hour: 15, minute: 31 }}
+      dateDisplayOptions={{ hour12: false, hour: '2-digit', minute: '2-digit' }}
+    />
+  </Box>
+);
+
+export const WithOpenMenu = () => {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Box height="260px">
+      <TimePicker
+        id="openMenu"
+        name="openMenu"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          setValue(event.target.value);
+        }}
+        label="Pick a Time"
+        value={value}
+        menuIsOpen
+        interval={3600}
+        startTime={{ hour: 9, minute: 0 }}
+        endTime={{ hour: 13, minute: 1 }}
+      />
+    </Box>
+  );
+};
+
+export const HelpText = () => {
+  const [value, setValue] = useState<string>('');
+  return (
+    <Box height="360px">
+      <TimePicker
+        id="helpText"
+        name="helpText"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          setValue(event.target.value);
+        }}
+        label="Pick a Time"
+        value={value}
+        helpText="pick a time, any time..."
+      />
+    </Box>
+  );
+};
+
+export const Sizes = () => {
+  const [value, setValue] = useState<string>();
+  const [value1, setValue1] = useState<string>();
+  const [value2, setValue2] = useState<string>();
+  return (
+    <Box gap="md" height="360px">
+      <TimePicker
+        id="smTimePicker"
+        name="smTimePicker"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          setValue(event.target.value);
+        }}
+        label="Small"
+        value={value}
+        size="sm"
+      />
+      <TimePicker
+        id="mdTimePicker"
+        name="mdTimePicker"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          setValue1(event.target.value);
+        }}
+        label="Medium"
+        value={value1}
+        size="md"
+      />
+      <TimePicker
+        id="lgTimePicker"
+        name="lgTimePicker"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          setValue2(event.target.value);
+        }}
+        label="Large"
+        value={value2}
+        size="lg"
+      />
+    </Box>
+  );
+};

package/src/components/TimePicker/TimePicker.test.tsx

@@ -0,0 +1,97 @@
+import React from 'react';
+import { screen, render } from '@testing-library/react';
+import { TimePicker } from './TimePicker';
+
+describe('TimePicker', () => {
+  describe('Default', () => {
+    it('Renders a TimePicker (select) with default props', () => {
+      render(
+        <TimePicker
+          name="timePicker"
+          id="timePicker"
+          onChange={() => null}
+          value={null}
+          label="Select Time"
+          menuIsOpen
+          maxMenuHeight={2000}
+        />
+      );
+
+      const timePicker = screen.getByLabelText('Select Time');
+
+      const expectedTimes = [
+        '12:00 AM',
+        '12:15 AM',
+        '12:30 AM',
+        '12:45 AM',
+        '01:00 AM',
+        '01:15 AM',
+      ];
+      expect(timePicker).toBeInTheDocument();
+      expectedTimes.forEach((time) => {
+        expect(screen.queryByText(time)).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe('Min/Max & Interval', () => {
+    it('Renders correct options based on interval and start end times.', () => {
+      render(
+        <TimePicker
+          name="timePicker"
+          id="timePicker"
+          onChange={() => null}
+          value={null}
+          label="Select Time"
+          menuIsOpen
+          maxMenuHeight={2000}
+          interval={3600}
+          startTime={{ hour: 9, minute: 0 }}
+          endTime={{ hour: 12, minute: 0 }}
+        />
+      );
+
+      const timePicker = screen.getByLabelText('Select Time');
+
+      const expectedTimes = ['09:00 AM', '10:00 AM', '11:00 AM'];
+
+      const notExpected = ['12:00 PM', '12:45 AM', '01:00 AM', '01:15 AM'];
+      expect(timePicker).toBeInTheDocument();
+      expectedTimes.forEach((time) => {
+        expect(screen.queryByText(time)).toBeInTheDocument();
+      });
+
+      notExpected.forEach((time) => {
+        expect(screen.queryByText(time)).toBe(null);
+      });
+    });
+  });
+
+  describe('Custom Date Display', () => {
+    it('renders the times based on the options provided', () => {
+      render(
+        <TimePicker
+          name="timePicker"
+          id="timePicker"
+          onChange={() => null}
+          value={null}
+          label="Select Time"
+          menuIsOpen
+          maxMenuHeight={2000}
+          dateDisplayOptions={{ hour12: false }}
+          startTime={{ hour: 13, minute: 0 }}
+          endTime={{ hour: 15, minute: 1 }}
+          interval={3600}
+        />
+      );
+
+      const timePicker = screen.getByLabelText('Select Time');
+
+      const expectedTimes = ['13:00:00', '14:00:00', '15:00:00'];
+      expect(timePicker).toBeInTheDocument();
+      expectedTimes.forEach((time) => {
+        expect(screen.queryByText(time)).toBeInTheDocument();
+      });
+    });
+  });
+});