@workday/canvas-kit-docs 5.3.17 → 5.4.0-next.1

package/dist/mdx/preview-react/_examples/examples/SelectWithFormik.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import {useFormik} from 'formik';
+import {Select} from '@workday/canvas-kit-preview-react/select';
+import {
+  FormField,
+  useFormFieldInput,
+  useFormFieldModel,
+} from '@workday/canvas-kit-preview-react/form-field';
+
+export default () => {
+  const formik = useFormik({
+    initialValues: {
+      selectedBook: '',
+    },
+    onSubmit: data => {
+      console.log(data);
+    },
+  });
+
+  const model = useFormFieldModel();
+  const formFieldInputProps = useFormFieldInput(model);
+
+  return (
+    <form onSubmit={formik.handleSubmit}>
+      <FormField orientation="vertical" alignItems="stretch">
+        <FormField.Label>Choose a book</FormField.Label>
+        <Select
+          name="selectedBook"
+          options={bookList}
+          onChange={event => formik.setFieldValue('selectedBook', event.currentTarget.value)}
+          value={formik.values.selectedBook}
+          grow
+          {...formFieldInputProps}
+        />
+      </FormField>
+    </form>
+  );
+};
+
+const bookList = [
+  {label: 'Dessert Person by Claire Saffitz', value: 'dessert person'},
+  {label: 'Elements of Pizza by Ken Forkish', value: 'the elements of pizza'},
+  {label: 'Flour Water Salt Yeast by Ken Forkish', value: 'flour water salt yeast'},
+  {label: 'Mastering Pasta by Marc Verti', value: 'mastering pasta'},
+  {label: 'Patisserie by Christophe Felder', value: 'patisserie'},
+  {label: 'Tartine by Elisabeth Prueitt & Chad Robertson', value: 'tartine'},
+];

package/dist/mdx/preview-react/_examples/examples/TextInputWithFormik.tsx

@@ -0,0 +1,105 @@
+import React from 'react';
+
+import {useFormik} from 'formik';
+import * as yup from 'yup';
+
+import {TextInput} from '@workday/canvas-kit-preview-react/text-input';
+import {HStack, VStack} from '@workday/canvas-kit-labs-react/layout';
+import {IconButton, PrimaryButton} from '@workday/canvas-kit-react/button';
+import {visibleIcon, invisibleIcon} from '@workday/canvas-system-icons-web';
+import {useUniqueId} from '@workday/canvas-kit-react/common';
+
+export default () => {
+  const passwordMinimum = 8;
+  const passwordHint = `Password should be of minimum ${passwordMinimum} characters length`;
+  const emailRequired = 'Email is required';
+  const passwordRequired = 'Password is required';
+
+  const validationSchema = yup.object({
+    email: yup
+      .string()
+      .email('Enter a valid email')
+      .required(emailRequired),
+    password: yup
+      .string()
+      .min(passwordMinimum, passwordHint)
+      .required(passwordRequired),
+  });
+
+  const passwordRef = React.useRef<HTMLInputElement>(null);
+  const [showPassword, setShowPassword] = React.useState(false);
+  const passwordId = useUniqueId();
+
+  const formik = useFormik({
+    initialValues: {
+      email: 'example@baz.com',
+      password: 'foobarbaz',
+    },
+    validationSchema: validationSchema,
+    onSubmit: values => {
+      passwordRef.current.type = 'password';
+
+      // Send data to server
+      setTimeout(() => {
+        alert(JSON.stringify(values, null, 2));
+      }, 0);
+    },
+  });
+
+  return (
+    <form onSubmit={formik.handleSubmit} action=".">
+      <VStack spacing="xs" alignItems="flex-start">
+        <TextInput
+          orientation="vertical"
+          isRequired={true}
+          hasError={formik.touched.email && !!formik.errors.email}
+        >
+          <TextInput.Label>Email</TextInput.Label>
+          <TextInput.Field
+            name="email"
+            autoComplete="username"
+            placeholder="yourName@example.com"
+            onChange={formik.handleChange}
+            onBlur={formik.handleBlur}
+            value={formik.values.email}
+          />
+          <TextInput.Hint>{formik.touched.email && formik.errors.email}</TextInput.Hint>
+        </TextInput>
+        <TextInput
+          orientation="vertical"
+          id={passwordId}
+          hasError={formik.touched.password && !!formik.errors.password}
+          isRequired={true}
+        >
+          <TextInput.Label>Password</TextInput.Label>
+          <HStack spacing="xxs">
+            <TextInput.Field
+              type={showPassword ? 'text' : 'password'}
+              name="password"
+              autoComplete="current-password"
+              ref={passwordRef}
+              onChange={formik.handleChange}
+              onBlur={formik.handleBlur}
+              value={formik.values.password}
+            />
+            <IconButton
+              type="button"
+              icon={showPassword ? invisibleIcon : visibleIcon}
+              aria-label={showPassword ? 'Hide Password' : 'Show Password'}
+              aria-controls={`input-${passwordId}`}
+              onClick={() => {
+                setShowPassword(state => !state);
+                passwordRef.current.focus();
+              }}
+            />
+          </HStack>
+          <TextInput.Hint>
+            {(formik.touched.password && formik.errors.password) || passwordHint}
+          </TextInput.Hint>
+        </TextInput>
+
+        <PrimaryButton type="submit">Submit</PrimaryButton>
+      </VStack>
+    </form>
+  );
+};

package/dist/mdx/preview-react/form-field/FormField.mdx

@@ -0,0 +1,39 @@
+import {Specifications} from '@workday/canvas-kit-docs';
+
+import {FormField} from '@workday/canvas-kit-preview-react/form-field';
+
+import Custom from './examples/Custom';
+import WithSelect from './examples/Select';
+
+
+# Canvas Kit Form Field
+
+FormField allows users to wrap input components to make them accessible. You usually won't want to
+use FormField directly but instead should use the specific component you need, e.g. `TextInput`.
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-preview-react
+```
+
+## Usage
+
+### Customizing With Behavior Hooks Example
+
+If you need full customization you can use the `FormField` behavior hooks to build your own
+solution. It is also easy it work with custom components or third party libraries and get the CKR
+accessibility guarantees by using the `as` prop.
+
+<ExampleCodeBlock code={Custom} />
+
+### Use with Select
+
+For some custom inputs, such as Canvas Kit's `Select`, you won't be able to reliably cast the
+`FormField.Input` with the `as` prop. Instead you'll want to use `FormField`'s hooks for the
+implementation. In the example below, we're using the `useFormFieldModel` hook to hoist the model
+and providing it to the `useFormFieldInput` behavior hook. Then we pass the model to the `FormField`
+component and the input props to `Select`. This connects `Select` to the `FormField` components and
+provides it with all the accessible attributes it needs.
+
+<ExampleCodeBlock code={WithSelect} />

package/dist/mdx/preview-react/form-field/examples/Custom.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import {
+  useFormFieldHint,
+  useFormFieldInput,
+  useFormFieldLabel,
+  useFormFieldModel,
+  useFormFieldOrientation,
+  FormFieldModelContext,
+} from '@workday/canvas-kit-preview-react/form-field';
+import {useModelContext} from '@workday/canvas-kit-react/common';
+import {Stack} from '@workday/canvas-kit-labs-react/layout';
+
+const Label = ({model, children}) => {
+  const localModel = useModelContext(FormFieldModelContext, model);
+  const props = useFormFieldLabel(localModel);
+
+  return (
+    <label {...props}>
+      {children}
+      {model.state.isRequired ? '*' : ''}
+    </label>
+  );
+};
+
+const Hint = ({model, children}) => {
+  const localModel = useModelContext(FormFieldModelContext, model);
+  const props = useFormFieldHint(localModel);
+
+  return <span {...props}>{children}</span>;
+};
+
+const Input = ({model, ...elementProps}) => {
+  const localModel = useModelContext(FormFieldModelContext, model);
+  const props = useFormFieldInput(localModel, elementProps);
+
+  return <input type="text" required={model.state.isRequired ? true : false} {...props} />;
+};
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setValue(event.target.value);
+  };
+
+  const model = useFormFieldModel({isRequired: true});
+
+  const layoutProps = useFormFieldOrientation('vertical');
+
+  return (
+    <Stack {...layoutProps}>
+      <Label model={model}>My Custom Field</Label>
+      <Input model={model} value={value} onChange={handleChange} />
+      <Hint model={model}>You can be anything</Hint>
+    </Stack>
+  );
+};

package/dist/mdx/preview-react/form-field/examples/Select.tsx

@@ -0,0 +1,50 @@
+import * as React from 'react';
+import {
+  FormField,
+  useFormFieldInput,
+  useFormFieldModel,
+} from '@workday/canvas-kit-preview-react/form-field';
+import {Select} from '@workday/canvas-kit-preview-react/select';
+
+export default () => {
+  const [selected, setSelected] = React.useState(wineList[0].value);
+  // Hoist the FormField model so we can pass it to `useFormFieldInput`
+  const model = useFormFieldModel({isRequired: true});
+  // Get all the FormField-related input props to pass to `Select`
+  const formFieldInputProps = useFormFieldInput(model);
+
+  return (
+    <FormField orientation="vertical" model={model}>
+      <FormField.Label>Choose a wine</FormField.Label>
+      <Select
+        options={wineList}
+        value={selected}
+        onChange={event => setSelected(event.currentTarget.value)}
+        {...formFieldInputProps}
+      />
+      <FormField.Hint>When in doubt, go with the Chianti.</FormField.Hint>
+    </FormField>
+  );
+};
+
+export default [
+  {label: 'Beaujolais', value: 'beaujolais'},
+  {label: 'Bordeaux', value: 'bordeaux'},
+  {label: 'Cabernet Sauvignon', value: 'cabernet sauvignon'},
+  {label: 'Champagne', value: 'champagne'},
+  {label: 'Chardonnay', value: 'chardonnay'},
+  {label: 'Chianti', value: 'chianti'},
+  {label: 'Malbec', value: 'malbec'},
+  {label: 'Merlot', value: 'merlot'},
+  {label: 'Pinot Grigio', value: 'pinot grigio'},
+  {label: 'Pinot Gris', value: 'pinot gris'},
+  {label: 'Pinot Noir', value: 'pinot noir'},
+  {label: 'Primitivo', value: 'primitivo'},
+  {label: 'Prosecco', value: 'prosecco'},
+  {label: 'Riesling', value: 'riesling'},
+  {label: 'Rioja', value: 'rioja'},
+  {label: 'Rosé', value: 'rosé'},
+  {label: 'Sauvignon Blanc', value: 'sauvignon blanc'},
+  {label: 'Syrah', value: 'syrah'},
+  {label: 'Zinfandel', value: 'zinfandel'},
+];

package/dist/mdx/preview-react/side-panel/examples/AlwaysOpen.tsx

@@ -19,7 +19,7 @@ export default () => {
   return (
     <Flex height={320}>
       <SidePanel {...panelProps}>
-        <Flex alignItems="center" paddingY="s" paddingX="xs">
+        <Flex alignItems="center" paddingY="s" paddingX="s">
           <AccentIcon css={iconStyles} icon={rocketIcon} />
           <h3
             css={{

package/dist/mdx/preview-react/side-panel/examples/Basic.tsx

@@ -28,7 +28,7 @@ export default () => {
         <SidePanel {...panelProps} onStateTransition={setPanelState}>
           <SidePanel.ToggleButton {...controlProps} />
           {panelState === 'expanded' && (
-            <Flex alignItems="center" paddingY="s" paddingX="xs">
+            <Flex alignItems="center" paddingY="s" paddingX="s">
               <Flex marginInlineEnd="s">
                 <AccentIcon icon={rocketIcon} />
               </Flex>

package/dist/mdx/preview-react/side-panel/examples/ExternalControl.tsx

@@ -27,7 +27,7 @@ export default () => {
         onStateTransition={setPanelState}
       >
         {panelState === 'expanded' && (
-          <Flex alignItems="center" paddingY="s" paddingX="xs">
+          <Flex alignItems="center" paddingY="s" paddingX="s">
             <h3
               css={{
                 ...type.levels.body.large,

package/dist/mdx/preview-react/side-panel/examples/RightOrigin.tsx

@@ -30,7 +30,7 @@ const RightPanel = () => {
     <SidePanel {...panelProps} onStateTransition={setPanelState} origin="right" css={panelStyles}>
       <SidePanel.ToggleButton {...controlProps} />
       {panelState === 'expanded' && (
-        <Flex alignItems="center" justifyContent="flex-end" paddingY="s" paddingX="xs">
+        <Flex alignItems="center" justifyContent="flex-end" paddingY="s" paddingX="s">
           <h3
             css={{
               ...type.levels.body.large,

package/dist/mdx/preview-react/side-panel/examples/Variant.tsx

@@ -26,7 +26,7 @@ export default () => {
         <SidePanel {...panelProps} onStateTransition={setPanelState} variant="alternate">
           <SidePanel.ToggleButton {...controlProps} />
           {panelState === 'expanded' && (
-            <Flex alignItems="center" paddingY="s" paddingX="xs">
+            <Flex alignItems="center" paddingY="s" paddingX="s">
               <h3
                 css={{
                   ...type.levels.body.large,

package/dist/mdx/preview-react/text-area/TextArea.mdx

@@ -0,0 +1,122 @@
+import {Specifications} from '@workday/canvas-kit-docs';
+
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+import Alert from './examples/Alert';
+import Basic from './examples/Basic';
+import Disabled from './examples/Disabled';
+import Error from './examples/Error';
+import Grow from './examples/Grow';
+import LabelPositionVertical from './examples/LabelPositionVertical';
+import LabelPositionHorizontal from './examples/LabelPositionHorizontal';
+import HiddenLabel from './examples/HiddenLabel';
+import Placeholder from './examples/Placeholder';
+import RefForwarding from './examples/RefForwarding';
+import Required from './examples/Required';
+import ResizeConstraints from './examples/ResizeConstraints';
+
+
+# Canvas Kit Text Area
+
+TextArea's allow users to enter and edit multiple lines of text.
+
+[> Workday Design Reference](https://design.workday.com/components/inputs/text-area)
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-preview-react
+```
+
+## Usage
+
+### Basic Example
+
+<ExampleCodeBlock code={Basic} />
+
+### Disabled
+
+Use `TextArea.Field`'s `disabled` prop to prevent users from interacting with the field.
+
+<ExampleCodeBlock code={Disabled} />
+
+### Placeholder
+
+Use `TextArea.Field`'s `placeholder` prop to display a sample of its expected format or value before
+a value has been provided.
+
+<ExampleCodeBlock code={Placeholder} />
+
+### Required
+
+Use `TextArea.Field`'s `isRequired` prop (or use with the `useTextAreaModel` hook) to indicate that
+the field is required. This will also add a red asterisk to `TextArea.Label`.
+
+<ExampleCodeBlock code={Required} />
+
+### Ref Forwarding
+
+`TextArea` supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
+`ref` to its underlying `<textarea>` element.
+
+<ExampleCodeBlock code={RefForwarding} />
+
+### Resize Constraints
+
+Use the `resize` css attribute to restrict resizing of it to certain dimensions.
+
+<ExampleCodeBlock code={ResizeConstraints} />
+
+### Grow
+
+There are lots of ways to accomplish this. The `TextArea.Field` extends from Box so it is easy to
+extend full width, e.g. setting width prop to 100%, or you can set the `alignItems` prop to
+`stretch` on `TextArea`, etc.
+
+<ExampleCodeBlock code={Grow} />
+
+### Label Position
+
+Use the `orientation` property to set `TextArea.Label`'s position. You can override the default
+spacing using the `spacing` prop. Below are examples of both positions:
+
+#### Horizontal
+
+<ExampleCodeBlock code={LabelPositionHorizontal} />
+
+#### Vertical
+
+<ExampleCodeBlock code={LabelPositionVertical} />
+
+### Visually Hiding The Label
+
+If your label is just for screen reader users you can use the `accessibleHide` utility class from
+`@workday/canvas-kit-react/common`. You will likely want to set the `spacing` prop on `TextArea` to
+`zero`.
+
+<ExampleCodeBlock code={HiddenLabel} />
+
+### Error States
+
+Use the `hasError` property from `useTextAreaModel` to set the `TextArea` to the Error state. If you
+have an accompanying hint you can use the `TextArea.Hint` subcomponent.
+
+<ExampleCodeBlock code={Error} />
+
+### Other Visual States
+
+Use the `useThemedRing` hook to change the visual state of the `<textarea>` element.
+
+#### Alert
+
+<ExampleCodeBlock code={Alert} />
+
+## Props
+
+Undocumented props are spread to the underlying `<textarea>` element.
+
+<ArgsTable of={TextArea} />
+
+## Specifications
+
+<Specifications file="TextAreaPreview.spec.ts" name="Text Area" />

package/dist/mdx/preview-react/text-area/examples/Alert.tsx

@@ -0,0 +1,36 @@
+/** @jsx jsx */
+import {jsx} from '@emotion/core';
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+import {useThemedRing} from '@workday/canvas-kit-labs-react/common';
+import {space, colors} from '@workday/canvas-kit-react/tokens';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value.slice(0, 10));
+  };
+
+  const alertStyles = useThemedRing(
+    value.length < 3 ? 'success' : value.length < 7 ? 'alert' : 'error'
+  );
+
+  const hintColor =
+    value.length < 3
+      ? colors.greenApple600
+      : value.length < 7
+      ? colors.cantaloupe600
+      : colors.cinnamon500;
+
+  return (
+    <TextArea orientation="vertical">
+      <TextArea.Label>Add a comment</TextArea.Label>
+      <TextArea.Field css={alertStyles} onChange={handleChange} value={value} />
+      <TextArea.Hint paddingTop={space.xxs}>
+        <strong>Character Limit: </strong>
+        <span css={{color: hintColor}}>{10 - value.length} Left</span>
+      </TextArea.Hint>
+    </TextArea>
+  );
+};

package/dist/mdx/preview-react/text-area/examples/Basic.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation="vertical">
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

package/dist/mdx/preview-react/text-area/examples/Disabled.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation="vertical">
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field disabled onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

package/dist/mdx/preview-react/text-area/examples/Error.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+export default () => {
+  const [value, setValue] = React.useState('four');
+  const [hint, setHint] = React.useState('');
+  const [hasError, setHasError] = React.useState(false);
+
+  const validateInput = (value: string) => {
+    const stringLength = value.length;
+    if (stringLength !== 3) {
+      setHasError(true);
+      const hintStart = 'Word length must be';
+      setHint(stringLength < 3 ? `${hintStart} greater than 2` : `${hintStart} less than 4`);
+    } else {
+      setHasError(false);
+      setHint('');
+    }
+  };
+
+  React.useEffect(() => {
+    validateInput(value);
+    // Only run on load
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    validateInput(event.target.value);
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea hasError={hasError} orientation="vertical">
+      <TextArea.Label>A three letter word</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+      <TextArea.Hint paddingTop={space.xxs}>{hint}</TextArea.Hint>
+    </TextArea>
+  );
+};

package/dist/mdx/preview-react/text-area/examples/Grow.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation="vertical" alignItems="stretch">
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

package/dist/mdx/preview-react/text-area/examples/HiddenLabel.tsx

@@ -0,0 +1,20 @@
+/** @jsx jsx */
+import {jsx} from '@emotion/core';
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+import {accessibleHide} from '@workday/canvas-kit-react/common';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation="vertical" spacing="zero">
+      <TextArea.Label css={{...accessibleHide}}>Email</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

package/dist/mdx/preview-react/text-area/examples/LabelPositionHorizontal.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation="horizontal">
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

package/dist/mdx/preview-react/text-area/examples/LabelPositionVertical.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation="vertical" spacing="xxxs">
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};