@hyphen/hyphen-components 2.9.0

package/src/components/TimePicker/TimePicker.tsx

@@ -0,0 +1,83 @@
+import React, { FC } from 'react';
+import { SelectInput, SelectInputProps } from '../SelectInput/SelectInput';
+
+export type TimePickerProps = Omit<SelectInputProps, 'options'> & {
+  /**
+   * Options to govern the display of the option labels in the select.
+   * This is a direct passthrough to the second argument of JS `toLocaleTimeString`.
+   * [More](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString)
+   */
+  dateDisplayOptions?: Intl.DateTimeFormatOptions;
+  /**
+   * End hour and minute
+   */
+  endTime?: { hour: number; minute: number };
+  /**
+   * Interval of displayed times (in seconds). Defaults to 900 seconds (15 minutes).
+   */
+  interval?: number;
+  /**
+   * Locale(s) to be passed down in order to format the label values in the select.
+   * This corresponds to the first argument of JS `toLocaleTimeString`.
+   * [More](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString)
+   */
+  locales?: string | string[];
+  /**
+   * Start hour and minute
+   */
+  startTime?: { hour: number; minute: number };
+};
+
+export const TimePicker: FC<TimePickerProps> = ({
+  id,
+  name,
+  label,
+  onChange,
+  value,
+  dateDisplayOptions = { hour: '2-digit', minute: '2-digit' },
+  endTime = undefined,
+  interval = 900,
+  locales = 'en-US',
+  placeholder = 'HH:MM',
+  startTime = undefined,
+  ...restProps
+}) => {
+  const generateTimes = () => {
+    const first = new Date();
+    first.setHours(startTime?.hour || 0, startTime?.minute || 0, 0, 0);
+
+    const last = new Date();
+    last.setHours(
+      endTime?.hour || first.getHours() + 24,
+      endTime?.minute || 0,
+      0,
+      0
+    );
+
+    const timeOptions = [];
+    const currentTime: Date = new Date(first);
+
+    while (currentTime < last) {
+      timeOptions.push({
+        value: currentTime.toISOString(),
+        label: currentTime.toLocaleTimeString(locales, dateDisplayOptions),
+      });
+      currentTime.setSeconds(first.getSeconds() + interval);
+    }
+
+    return timeOptions;
+  };
+
+  return (
+    <SelectInput
+      {...restProps}
+      id={id}
+      name={name}
+      label={label}
+      onChange={onChange}
+      options={generateTimes()}
+      placeholder={placeholder}
+      value={value}
+    />
+  );
+};

package/src/components/TimePickerNative/TimePickerNative.mdx

@@ -0,0 +1,67 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/blocks';
+import { TimePickerNative } from './TimePickerNative';
+import * as Stories from './TimePickerNative.stories';
+
+<Meta of={Stories} />
+
+# TimePickerNative
+
+Use a TimePickerNative when you want users to select from a list of a available times agnostic of date.
+
+_NOTE:_ This component is abstracted from the [SelectInputNative](?path=/docs/components-selectinputnative-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:_ The value returned will always be a JS ISO date string, like this: `2016-07-13T18:46:01.933Z`.
+
+## Props
+
+<ArgTypes of={TimePickerNative} />
+
+## 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} />
+
+## 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/TimePickerNative/TimePickerNative.stories.tsx

@@ -0,0 +1,151 @@
+import type { Meta } from '@storybook/react';
+import React, { ChangeEvent, useState } from 'react';
+import { TimePickerNative } from './TimePickerNative';
+import { Box } from '../Box/Box';
+
+const meta: Meta<typeof TimePickerNative> = {
+  title: 'Components/TimePickerNative',
+  component: TimePickerNative,
+  parameters: {
+    controls: { hideNoControlsWarning: true },
+  },
+};
+
+export default meta;
+
+export const Default = () => {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Box>
+      <TimePickerNative
+        id="defaultTimePickerNative"
+        name="defaultTimePickerNative"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          console.log(event.target.value);
+          setValue(event.target.value);
+        }}
+        label="Pick a Time"
+        value={value}
+      />
+    </Box>
+  );
+};
+
+export const WithASpecificInterval = () => {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Box>
+      <TimePickerNative
+        id="intervalTimePickerNative"
+        name="intervalTimePickerNative"
+        onChange={(event: ChangeEvent<HTMLInputElement>) =>
+          setValue(event.target.value)
+        }
+        value={value}
+        label="Pick a Time"
+        interval={3600}
+      />
+    </Box>
+  );
+};
+
+export const WithMinAndMaxTimes = () => {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Box>
+      <TimePickerNative
+        id="startEnd"
+        name="startEnd"
+        onChange={(event: ChangeEvent<HTMLInputElement>) =>
+          setValue(event.target.value)
+        }
+        value={value}
+        label="Pick a Time"
+        startTime={{ hour: 9, minute: 0 }}
+        endTime={{ hour: 15, minute: 31 }}
+      />
+    </Box>
+  );
+};
+
+export const WithCustomDateDisplay = () => {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Box>
+      <TimePickerNative
+        id="customDate"
+        name="customDate"
+        onChange={(event: ChangeEvent<HTMLInputElement>) =>
+          setValue(event.target.value)
+        }
+        value={value}
+        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 HelpText = () => {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Box>
+      <TimePickerNative
+        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 | null>(null);
+  const [value1, setValue1] = useState<string | null>(null);
+  const [value2, setValue2] = useState<string | null>(null);
+  return (
+    <Box gap="md">
+      <TimePickerNative
+        id="smTimePickerNative"
+        name="smTimePickerNative"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          setValue(event.target.value);
+        }}
+        label="Small"
+        value={value}
+        size="sm"
+      />
+      <TimePickerNative
+        id="mdTimePickerNative"
+        name="mdTimePickerNative"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          setValue1(event.target.value);
+        }}
+        label="Medium"
+        value={value1}
+        size="md"
+      />
+      <TimePickerNative
+        id="lgTimePickerNative"
+        name="lgTimePickerNative"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          setValue2(event.target.value);
+        }}
+        label="Large"
+        value={value2}
+        size="lg"
+      />
+    </Box>
+  );
+};

package/src/components/TimePickerNative/TimePickerNative.test.tsx

@@ -0,0 +1,117 @@
+import React from 'react';
+import { screen, render, fireEvent } from '@testing-library/react';
+import { TimePickerNative } from './TimePickerNative';
+
+describe('TimePickerNative', () => {
+  describe('Default', () => {
+    it('Renders a TimePickerNative (select) with default props', () => {
+      render(
+        <TimePickerNative
+          name="timePicker"
+          id="timePicker"
+          onChange={() => null}
+          value={null}
+          label="Select Time"
+        />
+      );
+
+      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(
+        <TimePickerNative
+          name="timePicker"
+          id="timePicker"
+          onChange={() => null}
+          value={null}
+          label="Select Time"
+          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(
+        <TimePickerNative
+          name="timePicker"
+          id="timePicker"
+          onChange={() => null}
+          value={null}
+          label="Select Time"
+          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();
+      });
+    });
+  });
+
+  describe('Callback Handling', () => {
+    it('it fires an onchange callback with the correct value', async () => {
+      const mockedHandleChange = jest.fn(() => {}); // eslint-disable-line
+
+      render(
+        <TimePickerNative
+          name="timePicker"
+          id="timePicker"
+          onChange={mockedHandleChange}
+          value={null}
+          label="Select Time"
+          dateDisplayOptions={{ hour12: false }}
+          startTime={{ hour: 13, minute: 0 }}
+          endTime={{ hour: 15, minute: 1 }}
+          interval={3600}
+        />
+      );
+
+      const timePicker = screen.getByLabelText('Select Time');
+
+      fireEvent.change(timePicker, { target: { value: 'hello' } });
+
+      expect(mockedHandleChange).toBeCalledTimes(1);
+    });
+  });
+});

package/src/components/TimePickerNative/TimePickerNative.tsx

@@ -0,0 +1,93 @@
+import React, { FC } from 'react';
+import {
+  SelectInputNative,
+  SelectInputNativeProps,
+} from '../SelectInputNative/SelectInputNative';
+
+export interface TimePickerNativeProps
+  extends Omit<SelectInputNativeProps, 'options'> {
+  /**
+   * Options to govern the display of the option labels in the select.
+   * This is a direct passthrough to the second argument of JS `toLocaleTimeString`.
+   * [More](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString)
+   */
+  dateDisplayOptions?: Intl.DateTimeFormatOptions;
+  /**
+   * End hour and minute
+   */
+  endTime?: { hour: number; minute: number };
+  /**
+   * Interval of displayed times (in seconds). Defaults to 900 seconds (15 minutes).
+   */
+  interval?: number;
+  /**
+   * Locale(s) to be passed down in order to format the label values in the select.
+   * This corresponds to the first argument of JS `toLocaleTimeString`.
+   * [More](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString)
+   */
+  locales?: string | string[];
+  /**
+   * Start hour and minute
+   */
+  startTime?: { hour: number; minute: number };
+  /**
+   *  Should be ISO timestamp as returned by `onChange`, and matching value of option object.
+   */
+  value: SelectInputNativeProps['value'];
+}
+
+export const TimePickerNative: FC<TimePickerNativeProps> = ({
+  id,
+  name,
+  label,
+  onChange,
+  value,
+  dateDisplayOptions = { hour: '2-digit', minute: '2-digit' },
+  endTime = undefined,
+  interval = 900,
+  locales = 'en-US',
+  placeholder = 'HH:MM',
+  startTime = undefined,
+  ...restProps
+}) => {
+  const generateTimes = () => {
+    const first = new Date();
+    first.setHours(startTime?.hour || 0, startTime?.minute || 0, 0, 0);
+
+    const last = new Date();
+    last.setHours(
+      endTime?.hour || first.getHours() + 24,
+      endTime?.minute || 0,
+      0,
+      0
+    );
+
+    const timeOptions = [];
+    const currentTime: Date = new Date(first);
+
+    while (currentTime < last) {
+      timeOptions.push({
+        value: currentTime.toISOString(),
+        label: currentTime.toLocaleTimeString(locales, dateDisplayOptions),
+      });
+      currentTime.setSeconds(first.getSeconds() + interval);
+    }
+
+    return timeOptions;
+  };
+
+  const options = generateTimes();
+
+  return (
+    <SelectInputNative
+      {...restProps}
+      id={id}
+      name={name}
+      label={label}
+      onChange={onChange}
+      options={options}
+      placeholder={placeholder}
+      value={value}
+    />
+  );
+};

package/src/components/Toast/Toast.mdx

@@ -0,0 +1,134 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/blocks';
+import { ToastContainer } from './';
+import * as Stories from './Toast.stories';
+
+<Meta of={Stories} />
+
+<ToastContainer />
+
+# Toast
+
+Use a toast to communicate non-critical information or feedback to a user about the result of an action.
+Typically you'd reserve toasts for non-essential notifications, since they are meant to disappear automatically
+under normal circumstances.
+
+## Usage Guidelines
+
+- Keep messages short. Typically if a toast results in a multiline message, than it is too long.
+- Avoid adding actions inside of a toast. If you include an action (other than dismiss) in a toast,
+  try and have that action available somewhere else on the page.
+  E.G: a `retry` action can also be triggered by re-submitting a form.
+- The main exception that makes for a useful toast action is an `undo` button, which is unlikely to make sense
+  in most pages, but is a great escape hatch for a user that wants to take back an action.
+
+### Toast or Alert or Modal?
+
+When to use Toast:
+
+- Confirmations, success messages, and simple notifications
+- Non-critical errors that are relevant in the moment and do not need to interrupt the user experience, such as "No internet connection"
+
+When not to use Toast:
+
+- Do not use toasts for error messages. Instead, use [Alert](?path=/docs/components-alert-overview--default-story) to prominently inform users of persistent errors.
+- Do not use toasts as a blocking alert or interstitial (i.e. restrict or contextualize user actions). In these
+  cases, use a [Modal](?path=/docs/components-modal-overview--default-story).
+
+## Content Guidelines
+
+Keep the contents of a toast as short as possible by placing only the most important information in it. Toasts are meant to unobtrusively provide non-critical information or feedback. In general, toast messages should be:
+
+- Short and affirmative
+- Written in a pattern of noun + verb, such as "File saved" or "Role added".
+
+<Canvas isExpanded of={Stories.Example} />
+
+## Required Setup
+
+1. Include the `<ToastContainer />` in your React app. (at the highest possible level of the DOM tree);
+2. Create a toast anywhere in your app `toast('Hello')`.
+
+**NOTE:** All examples of this page exclusively showcase step 2 above, as the ToastContainer is added globally on the page.
+
+### Example
+
+```jsx
+// App.jsx
+import { ToastContainer } from '@hyphen/hyphen-components';
+
+export const App = () => {
+  <MyAppContainer>
+    <ToastContainer {/* custom props */} />
+    {/* Routes, other providers, etc */}
+  </MyAppContainer>
+};
+
+// SomeAppPage.jsx
+import { toast } from '@palmetto/palmetto-components';
+
+export const SomeAppPage = () => {
+  <button onClick={() => toast('Hello')}>
+    gimme a toast
+  </button>
+}
+```
+
+## Props (for `<ToastContainer />`)
+
+<ArgTypes of={ToastContainer} />
+
+## Toast Options
+
+```jsx
+// Example
+toast('my toast', { duration: 3000, position: 'top-center' });
+```
+
+<Canvas of={Stories.Column} />
+
+### Position
+
+<Canvas isExpanded of={Stories.Position} />
+### Duration
+
+We've included sensible defaults for the duration of a toast before it disappears, but if you require custom duration, follow these guidelines:
+
+1. Error toasts should likely stay on the screen
+   longer than success toasts, since they are arguably more important.
+2. Toasts with actions, should stay on screen for at least 10 seconds.
+3. async toasts with loading states should always included success and failure conditions,
+   to avoid an infinite spinner.
+
+<Canvas isExpanded of={Stories.Duration} />
+
+### Dismissible (or lack thereof)
+
+By default, toasts are dismissible since they
+should not hinder the user experience, but we still wish to provide a quick and easy
+escape hatch, should a user want to clear it out of their view.
+
+In cases where you'd like the toast to remain for a set amount of time
+without the user being able to clear it, you can use `canDismiss: false`.
+
+<Canvas isExpanded of={Stories.NotDismissible} />
+
+### Programmatic Dismiss
+
+In some cases you'll want to be able to dismiss a toast programmatically based on some other condition in the business logic.
+For these cases, you can use `toast.dismiss`.
+
+<Canvas isExpanded of={Stories.ProgrammaticDismiss} />
+
+### Compact
+
+Use the `isCompact` prop for a toast the uses less screen real estate.
+
+<Canvas isExpanded of={Stories.Compact} />
+
+### Toast Types
+
+To give toasts an additional visual indication of feedback, `success`, `loading`, and `error` types add a contextual icon to the toast message.
+
+<Canvas isExpanded of={Stories.BasicTypes} />
+
+<Canvas isExpanded of={Stories.AdvancedTypes} />