@workday/canvas-kit-docs 11.0.0-alpha.671-next.0 → 11.0.0-alpha.693-next.0

package/dist/mdx/preview-react/_examples/examples/Table/WithSortableColumnHeaders.tsx

@@ -0,0 +1,213 @@
+import React from 'react';
+
+import {createComponent} from '@workday/canvas-kit-react/common';
+import {Table} from '@workday/canvas-kit-preview-react/table';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {TertiaryButton} from '@workday/canvas-kit-react/button';
+import {Text} from '@workday/canvas-kit-react/text';
+import {sortDownIcon, sortUpIcon} from '@workday/canvas-system-icons-web';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+interface CountryData {
+  country: string;
+  capital: string;
+  population: number;
+}
+
+const countryData: CountryData[] = [
+  {country: 'Australia', capital: 'Canberra', population: 25690000},
+  {country: 'Bahamas', capital: 'Nassau', population: 407906},
+  {country: 'Canada', capital: 'Ottawa', population: 38250000},
+  {country: 'Fiji', capital: 'Suva', population: 924610},
+  {country: 'Ghana', capital: 'Accra', population: 32830000},
+  {country: 'Hong Kong', capital: 'City of Victoria', population: 7413000},
+  {country: 'India', capital: 'New Delhi', population: 1408000000},
+  {country: 'Ireland', capital: 'Dublin', population: 5033000},
+  {country: 'Jamaica', capital: 'Kingston', population: 2828000},
+  {country: 'Kenya', capital: 'Nairobi', population: 53010000},
+  {country: 'Micronesia', capital: 'Palikir', population: 113131},
+  {country: 'New Zealand', capital: 'Wellington', population: 5123000},
+  {country: 'Philippines', capital: 'Manila', population: 113900000},
+  {country: 'Puerto Rico', capital: 'San Juan', population: 3264000},
+  {country: 'Samoa', capital: 'Apia', population: 218764},
+  {country: 'Singapore', capital: 'Singapore', population: 5454000},
+  {country: 'Tanzania', capital: 'Dodoma', population: 63590000},
+  {country: 'United Kingdom', capital: 'London', population: 67330000},
+  {country: 'United States', capital: 'Washington, D.C.', population: 331900000},
+  {country: 'Zimbabwe', capital: 'Harare', population: 15990000},
+];
+
+type SortOrder = 'ascending' | 'descending' | 'none';
+
+interface HeaderRowState {
+  column1SortDirection: SortOrder;
+  column2SortDirection: SortOrder;
+  column3SortDirection: SortOrder;
+}
+
+interface HeaderRowAction {
+  column: 'Country' | 'Capital' | 'Population';
+  payload: CountryData[];
+}
+
+const initialHeaderRowState: HeaderRowState = {
+  column1SortDirection: 'none',
+  column2SortDirection: 'none',
+  column3SortDirection: 'none',
+};
+
+/**
+ * Given the current sort order, return the next sort order
+ */
+function getNextSortOrder(sortOrder: SortOrder) {
+  return sortOrder === 'ascending' ? 'descending' : 'ascending';
+}
+
+function headerRowReducer(state: HeaderRowState, action: HeaderRowAction): HeaderRowState {
+  switch (action.column) {
+    case 'Country':
+      if (state.column1SortDirection === 'ascending') {
+        action.payload.sort((a, b) => b.country.localeCompare(a.country));
+      } else {
+        action.payload.sort((a, b) => a.country.localeCompare(b.country));
+      }
+
+      return {
+        ...initialHeaderRowState,
+        column1SortDirection: getNextSortOrder(state.column1SortDirection),
+      };
+
+    case 'Capital':
+      if (state.column2SortDirection === 'ascending') {
+        action.payload.sort((a, b) => b.capital.localeCompare(a.capital));
+      } else {
+        action.payload.sort((a, b) => a.capital.localeCompare(b.capital));
+      }
+
+      return {
+        ...initialHeaderRowState,
+        column2SortDirection: getNextSortOrder(state.column2SortDirection),
+      };
+
+    case 'Population':
+      if (state.column3SortDirection === 'ascending') {
+        action.payload.sort((a, b) => b.population - a.population);
+      } else {
+        action.payload.sort();
+      }
+
+      return {
+        ...initialHeaderRowState,
+        column3SortDirection: getNextSortOrder(state.column3SortDirection),
+      };
+
+    default:
+      return initialHeaderRowState;
+  }
+}
+
+interface SortableColumnHeaderProps {
+  label: string;
+  onSortAction: (label: string) => void;
+  children?: React.ReactNode;
+  sortOrder: SortOrder;
+}
+
+const getSortIcon = (sortOrder?: SortOrder) => {
+  if (sortOrder === 'ascending') {
+    return sortUpIcon;
+  } else if (sortOrder === 'descending') {
+    return sortDownIcon;
+  } else {
+    return undefined;
+  }
+};
+
+export default createComponent('th')({
+  displayName: 'SortableColumnHeader',
+  Component: (
+    {label, sortOrder, onSortAction, children, ...elemProps}: SortableColumnHeaderProps,
+    ref
+  ) => {
+    return (
+      <Table.Header ref={ref} scope="col" aria-sort={sortOrder} {...elemProps}>
+        <Tooltip type="describe" title={`Sort ${getNextSortOrder(sortOrder)}`}>
+          <TertiaryButton
+            icon={getSortIcon(sortOrder)}
+            iconPosition="end"
+            onClick={() => onSortAction(label)}
+          >
+            {children}
+          </TertiaryButton>
+        </Tooltip>
+      </Table.Header>
+    );
+  },
+});
+
+const textStyles = createStyles({
+  paddingInlineStart: system.space.x3,
+});
+
+export default () => {
+  const [headerRowState, headerRowDispatch] = React.useReducer(
+    headerRowReducer,
+    initialHeaderRowState
+  );
+
+  function sortColumnHandler(columnName) {
+    headerRowDispatch({
+      column: columnName,
+      payload: countryData,
+    });
+  }
+
+  return (
+    <Table maxHeight="40rem">
+      <Table.Caption>Population Listed by Country (2021)</Table.Caption>
+      <Table.Head>
+        <Table.Row>
+          <SortableColumnHeader
+            label="Country"
+            sortOrder={headerRowState.column1SortDirection as SortOrder}
+            onSortAction={sortColumnHandler}
+          >
+            Country
+          </SortableColumnHeader>
+          <SortableColumnHeader
+            label="Capital"
+            sortOrder={headerRowState.column2SortDirection as SortOrder}
+            onSortAction={sortColumnHandler}
+          >
+            Capital
+          </SortableColumnHeader>
+          <SortableColumnHeader
+            label="Population"
+            sortOrder={headerRowState.column3SortDirection as SortOrder}
+            onSortAction={sortColumnHandler}
+          >
+            Population
+          </SortableColumnHeader>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        {countryData.map(item => {
+          return (
+            <Table.Row key={item.country}>
+              <Table.Header scope="row">
+                <Text cs={textStyles}>{item.country}</Text>
+              </Table.Header>
+              <Table.Cell>
+                <Text cs={textStyles}>{item.capital}</Text>
+              </Table.Cell>
+              <Table.Cell>
+                <Text cs={textStyles}>{item.population.toLocaleString()}</Text>
+              </Table.Cell>
+            </Table.Row>
+          );
+        })}
+      </Table.Body>
+    </Table>
+  );
+};

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

@@ -20,26 +20,28 @@ export default () => {
     expanded ? 'expanded' : 'collapsed'
   );
 
+  const expandedContent = (
+    <Flex alignItems="center" paddingY="s" paddingX="s">
+      <Flex marginInlineEnd="s">
+        <AccentIcon icon={rocketIcon} />
+      </Flex>
+      <Text as="h3" typeLevel="body.large" color="licorice500" fontWeight="bold" {...labelProps}>
+        Tasks Panel
+      </Text>
+    </Flex>
+  );
+
   return (
     <CanvasProvider theme={{canvas: {direction}}}>
       <Flex height={320}>
         <SidePanel {...panelProps} onStateTransition={setPanelState}>
           <SidePanel.ToggleButton {...controlProps} />
-          {panelState === 'expanded' && (
-            <Flex alignItems="center" paddingY="s" paddingX="s">
-              <Flex marginInlineEnd="s">
-                <AccentIcon icon={rocketIcon} />
-              </Flex>
-              <Text
-                as="h3"
-                typeLevel="body.large"
-                color="licorice500"
-                fontWeight="bold"
-                {...labelProps}
-              >
-                Tasks Panel
-              </Text>
-            </Flex>
+          {panelState === 'expanded' ? (
+            expandedContent
+          ) : (
+            <Text hidden {...labelProps}>
+              Tasks Panel
+            </Text>
           )}
         </SidePanel>
         <Flex

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

@@ -21,21 +21,23 @@ const RightPanel = () => {
     expanded ? 'expanded' : 'collapsed'
   );
 
+  const expandedContent = (
+    <Flex alignItems="center" justifyContent="flex-end" paddingY="s" paddingX="s">
+      <Text as="h3" typeLevel="body.large" color="licorice500" fontWeight="bold" {...labelProps}>
+        Tasks Panel
+      </Text>
+    </Flex>
+  );
+
   return (
     <StyledSidePanel {...panelProps} onStateTransition={setPanelState} origin="right">
       <SidePanel.ToggleButton {...controlProps} />
-      {panelState === 'expanded' && (
-        <Flex alignItems="center" justifyContent="flex-end" paddingY="s" paddingX="s">
-          <Text
-            as="h3"
-            typeLevel="body.large"
-            color="licorice500"
-            fontWeight="bold"
-            {...labelProps}
-          >
-            Tasks Panel
-          </Text>
-        </Flex>
+      {panelState === 'expanded' ? (
+        expandedContent
+      ) : (
+        <Text hidden {...labelProps}>
+          Tasks Panel
+        </Text>
       )}
     </StyledSidePanel>
   );

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

@@ -18,23 +18,25 @@ export default () => {
     expanded ? 'expanded' : 'collapsed'
   );
 
+  const expandedContent = (
+    <Flex alignItems="center" paddingY="s" paddingX="s">
+      <Text as="h3" typeLevel="body.large" color="licorice500" fontWeight="bold" {...labelProps}>
+        Alternate Panel
+      </Text>
+    </Flex>
+  );
+
   return (
     <CanvasProvider theme={{canvas: {direction}}}>
       <Flex height={320} backgroundColor="soap100">
         <SidePanel {...panelProps} onStateTransition={setPanelState} variant="alternate">
           <SidePanel.ToggleButton {...controlProps} />
-          {panelState === 'expanded' && (
-            <Flex alignItems="center" paddingY="s" paddingX="s">
-              <Text
-                as="h3"
-                typeLevel="body.large"
-                color="licorice500"
-                fontWeight="bold"
-                {...labelProps}
-              >
-                Alternate Panel
-              </Text>
-            </Flex>
+          {panelState === 'expanded' ? (
+            expandedContent
+          ) : (
+            <Text hidden {...labelProps}>
+              Tasks Panel
+            </Text>
           )}
         </SidePanel>
         <Flex

package/dist/mdx/preview-react/table/Table.mdx

@@ -1,9 +1,10 @@
-import {SymbolDoc, Specifications} from '@workday/canvas-kit-docs';
+import {SymbolDoc} from '@workday/canvas-kit-docs';
 import {Table} from '@workday/canvas-kit-preview-react/table';
 // Examples
 import Basic from './examples/Basic';
 import BasicWithHeading from './examples/BasicWithHeading';
 import FixedColumn from './examples/FixedColumn';
+import RightToLeft from './examples/RightToLeft';
 
 
 # Canvas Kit Table
@@ -29,6 +30,12 @@ customization of the title/heading of their table.
 
 <ExampleCodeBlock code={BasicWithHeading} />
 
+### Right to Left
+
+Table supports right-to-left languages when specified in the CanvasProvider theme.
+
+<ExampleCodeBlock code={RightToLeft} />
+
 ### Example with Caption
 
 Users are free to use a `caption` instead of a heading. A `caption` is not required but it is good
@@ -46,6 +53,14 @@ Users may add styles to the `Table.Header` to render a fixed column. The example
 
 <ExampleCodeBlock code={FixedColumn} />
 
+### Advanced
+
+You can also find several advanced Table examples in our Storybook Examples section.
+
+- [Expandable Rows](/docs/examples-tables-advanced--expandable-rows)
+- [Selectable Rows ](/docs/examples-tables-advanced--selectable-rows)
+- [Sortable Column Headers](/docs/examples-tables-advanced--sortable-column-headers)
+
 ## Component API
 
 <SymbolDoc name="Table" fileName="/preview-react/" />

package/dist/mdx/preview-react/table/examples/RightToLeft.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+
+import {Table} from '@workday/canvas-kit-preview-react/table';
+import {CanvasProvider, ContentDirection} from '@workday/canvas-kit-react/common';
+
+export default () => {
+  return (
+    <CanvasProvider theme={{canvas: {direction: ContentDirection.RTL}}}>
+      <Table>
+        <Table.Caption>משקאות קפה וגדלים</Table.Caption>
+        <Table.Head>
+          <Table.Row>
+            <Table.Header scope="col" backgroundColor="soap100">
+              מַשׁקֶה
+            </Table.Header>
+            <Table.Header scope="col" backgroundColor="soap100">
+              גודל
+            </Table.Header>
+          </Table.Row>
+        </Table.Head>
+        <Table.Body>
+          <Table.Row>
+            <Table.Cell>אספרסו</Table.Cell>
+            <Table.Cell>1 גר</Table.Cell>
+          </Table.Row>
+          <Table.Row>
+            <Table.Cell>מקיאטו</Table.Cell>
+            <Table.Cell>2 גרם אספרסו</Table.Cell>
+          </Table.Row>
+          <Table.Row>
+            <Table.Cell>גזירה</Table.Cell>
+            <Table.Cell>2 גרם אספרסו, 1 גרם חלב מוקצף</Table.Cell>
+          </Table.Row>
+        </Table.Body>
+      </Table>
+    </CanvasProvider>
+  );
+};

package/dist/mdx/react/select/Select.mdx

@@ -15,6 +15,9 @@ import Required from './examples/Required';
 import MenuHeight from './examples/MenuHeight';
 import HoistedModel from './examples/HoistedModel';
 import RefForwarding from './examples/RefForwarding';
+import FetchingDynamicItems from './examples/FetchingDynamicItems';
+import Placeholder from './examples/Placeholder';
+import InitialSelectedItem from './examples/InitialSelectedItem';
 
 
 # Canvas Kit Select
@@ -86,6 +89,10 @@ and provides direct access to its `state` and `events` outside of the `Select` c
 In this example, we set up external observation of the model state and create an external button to
 trigger an event to change the selected item.
 
+**Note: If your array of objects uses an `id` property and a `text` property there is no need to use
+the helper functions of `getId` or `getTextValue`. The collection system and the `Select` use these
+properties by default for keyboard navigation and selected the `id` based on the item clicked.**
+
 <ExampleCodeBlock code={HoistedModel} />
 
 ### Label Position Horizontal
@@ -199,18 +206,43 @@ Use the error state when the selection is no longer valid.
 
 <ExampleCodeBlock code={Error} />
 
+### Initial Selected Item
+
+You can set `initialSelectedIds` to the value that you want initially selected.
+
+<ExampleCodeBlock code={InitialSelectedItem} />
+
+### Placeholder
+
+You can change the placeholder text by passing in a string value to the `placeholder` attribute on
+the `Select.Input`.
+
+<ExampleCodeBlock code={Placeholder} />
+
+### Fetching Dynamic Items
+
+It's common to load items from a server call. Hoisting the `model` and setting your items on state
+allows you to pass those items to your `model`. You can leverage React state to set your items on
+load as well as displaying a placeholder indicating when items are loaded.
+
+**Note: In this case we need to use `getId` and `getTextValue` because our data doesn't have the
+properties of `id` or `text`. Using these helper functions sets the `serverId` to be `id` and
+`label` to be `text`.**
+
+<ExampleCodeBlock code={FetchingDynamicItems} />
+
 ### Complex
 
-When registering items in an array of objects, it's common to have an `id` that is different than
-the text value displayed in the UI. Typically, this `id` is used to send to the server. Use the `id`
-value to set the `data-id` property on `Select.Item` to ensure proper keyboard handling and
-type-ahead.
+When registering items in an array of objects, it's common to have the text that is displayed to the user be
+different than an id. In this example, `serverId` and `label` properties need to be remapped to
+`id` and `text` hence the usage of `getId` and `getTextValue`. If your object has the properties
+`text` and `id`, there would be no need for this.
 
 <ExampleCodeBlock code={Complex} />
 
-By default, the identifier and text value are `id` and `text` properties respectively. If your data
-object for each item is different, provide a `getId` or `getTextValue` function to the model config.
-For example:
+**Note: By default, the identifier and text value are `id` and `text` properties respectively. If
+your data object for each item is different, provide a `getId` or `getTextValue` function to the
+model config. For example:**
 
 ```jsx
 const items = [
@@ -225,6 +257,49 @@ const items = [
 </Select>;
 ```
 
+### When to use `getId`, or `getTextValue`
+
+- `getId`: This is an optional function to return the id of an item. If not provided, the default
+  function will return the `id` property from the object of each item. If you did not provide
+  `items`, do not override this function. Instead provide static
+  items via JSX. the list will create an internal array of items where `id` is the only property and
+  the default `getId` will return the desired result. **Note: If your array of objects has a
+  different property for `id`, like `serverId`, use this function to set the id.**
+
+  ```tsx
+  const options = [{text: 'Pizza', serverId: 'pizza-1'}, {text: 'Cheeseburger', serverId: 'cheeseburger'}]
+  <Select items={options} getId={(item) => item.serverId}>
+    <FormField label="Your Label">
+      <Select.Input onChange={e => handleChange(e)} id="contact-select" />
+      <Select.Popper>
+        <Select.Card>
+          <Select.List>{item => <Select.Item>{item.text}</Select.Item>}</Select.List>
+        </Select.Card>
+      </Select.Popper>
+    </FormField>
+  </Select>
+  ```
+
+- `getTextValue`: Optional function to return the text representation of an item. If not provided,
+  the default function will return the `text` property of the object of each item or an empty string
+  if there is no `text` property. If you did not provide `items`, do not override this function.
+  **Note: If your array of objects has a different property for `text`, like `label`, use this
+  function to set the text.**
+
+  ```tsx
+  const options = [{label: 'Pizza', id: 'pizza-1'}, {label: 'Cheeseburger', id: 'cheeseburger'}]
+  <Select items={options} getTextValue={(item) => item.label}>
+    <FormField label="Your Label">
+      <Select.Input onChange={e => handleChange(e)} id="contact-select" />
+      <Select.Popper>
+        <Select.Card>
+          <Select.List>{item => <Select.Item>{item.label}</Select.Item>}</Select.List>
+        </Select.Card>
+      </Select.Popper>
+    </FormField>
+  </Select>
+  ```
+
 ## Component API
 
 <SymbolDoc name="Select" fileName="/react/" />

package/dist/mdx/react/select/examples/Basic.tsx

@@ -24,7 +24,7 @@ export default () => {
       <Select items={options}>
         <FormField>
           <FormField.Label>Contact</FormField.Label>
-          <FormField.Input as={Select.Input} onChange={e => handleChange(e)} />
+          <FormField.Input as={Select.Input} onChange={handleChange} />
           <Select.Popper>
             <Select.Card>
               <Select.List>

package/dist/mdx/react/select/examples/Complex.tsx

@@ -4,14 +4,14 @@ import {Select} from '@workday/canvas-kit-react/select';
 import {Flex} from '@workday/canvas-kit-react/layout';
 
 const options = [
-  {id: 'email', text: 'E-mail'},
-  {id: 'phone', text: 'Phone'},
-  {id: 'fax', text: 'Fax'},
-  {id: 'mail', text: 'Mail'},
-  {id: 'mobile', text: 'Mobile Phone'},
+  {serverId: 'email', label: 'E-mail'},
+  {serverId: 'phone', label: 'Phone'},
+  {serverId: 'fax', label: 'Fax'},
+  {serverId: 'mail', label: 'Mail'},
+  {serverId: 'mobile', label: 'Mobile Phone'},
   {
-    id: 'oasis',
-    text: 'The Ontologically Anthropocentric Sensory Immersive Simulation',
+    serverId: 'oasis',
+    label: 'The Ontologically Anthropocentric Sensory Immersive Simulation',
   },
 ];
 
@@ -20,24 +20,19 @@ export default () => {
   const [id, setId] = React.useState('');
 
   const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
-    setValue(event.target.value);
-  };
-
-  const handleSelect = ({id}: {id: string}) => {
-    setId(id);
+    setId(event.target.value);
+    setValue(options.find(item => item.serverId === event.target.value)!.label);
   };
 
   return (
     <Flex flexDirection="column">
-      <Select items={options} onSelect={handleSelect}>
+      <Select items={options} getId={item => item.serverId} getTextValue={item => item.label}>
         <FormField>
           <FormField.Label>Contact</FormField.Label>
           <FormField.Input as={Select.Input} onChange={e => handleChange(e)} />
           <Select.Popper>
             <Select.Card>
-              <Select.List>
-                {item => <Select.Item data-id={item.id}>{item.text}</Select.Item>}
-              </Select.List>
+              <Select.List>{item => <Select.Item>{item.label}</Select.Item>}</Select.List>
             </Select.Card>
           </Select.Popper>
         </FormField>