@edvisor/product-language 0.1.1 → 0.3.0

package/src/lib/components/input-field/storybook/input-field.stories.mdx

@@ -0,0 +1,113 @@
+import { Canvas, Meta, Story } from '@storybook/addon-docs';
+import { Card, SpaceBetween } from '@components'
+import { Playground } from 'storybook-addon-jarle-monaco'
+import { InputField } from '../input-field'
+import { PlainHTMLFormExample, ReactFormHookExample, SimpleInputExample, AllDressedExample, OuterLabelExample, IconExample, ControlsExample, StepperExample, InnerLabelExample } from './components'
+
+<Meta title="Components/input-field"/>
+
+# Input Field
+
+An Input Field is a component that users can type into. It has a range of options and supports several text formats including numbers.
+
+### Table of Contents
+1. [Familiar HTML Input API](#familiar-html-input-api)
+2. [Slots and sub-components](#slots-and-sub-components)
+
+<div id='familiar-html-input-api'/>
+
+## Familiar HTML input API
+
+The input field is a drop-in replacement for the common HTML input element. It accepts all of the usual props for such an element. As you can see in the code sample below, you can simple use InputField the same way as you could a normal HTML input field. It has a few additional properties which can be used to style the component.
+
+The available optional properties are as follows, try them out in the editable code sample below!
+
+| Prop       | Type      | Description                                                              |
+| ---------- | --------- | ------------------------------------------------------------------------ |
+| `prefix?`  | `string`  | add a small text before the input                                        |
+| `suffix?`  | `string`  | add a small text after the input                                         |
+| `label?`   | `string`  | a label to be displayed inside the input element, above the input itself |
+| `invalid?` | `boolean` | indicate that the input is invalid                                       |
+
+<PlainHTMLFormExample />
+
+Notice that in this example (and only this example) we are using HTML's native "constraint validation API" to detect and display errors. Doing this involves watching the `onInvalid` event, and setting the invalid flag on the input if it fires.
+
+### `props.label`
+
+Passing a label will add a name inside the input field, above where the input will appear. This is a fancy new way people like to do inputs, and we might be adopting this style, so for now the examples will mostly all have inner labels.
+
+<InnerLabelExample />
+
+### Managing State
+
+Because the input field can be used just like a regular HTML input, you can use common state-management libraries. For example, we used react-form-hook to implement the following code sample. Try it out!
+
+<ReactFormHookExample />
+
+
+### Simple Input API
+
+The input-field module also exposes a set of components with more stream-lined APIs for implementing common UIs. These can be used instead of the base `InputField`` when you don't need all the bells and whistles of a raw HTML input, or when you aren't in the context of a form and just want to manage state with useState. The main motivation for providing these is to give the user a simple "string goes in, string comes out" API, so that they do not need to deal with HTML events.
+
+These simple components obey the following API. In addition they have all the same optional properties described above:
+
+| Prop        | Type                  | Description                                                                       |
+| ----------- | --------------------- | --------------------------------------------------------------------------------- |
+| `value`     | `T`                   | The value of the controlled input                                                 |
+| `onChange`  | `(change: T) => void` | Called when the value changes                                                     |
+| `required?` | `boolean`             | Passed to the inner HTML element, renders an * (asterisk) next to the inner-label |
+
+<SimpleInputExample />
+
+<div id='slots-and-sub-components'/>
+
+## Slots and sub-components
+
+Using a combination of slots, sub-components, and the optional properties described above, it is possible to customize the components quite a bit. The available components include:
+
+| Slot                  | Type    | Description                                                                                       |
+| --------------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `InputField.Icon`     | Slot    | Places the children before the input, children should be small                                    |
+| `InputField.Controls` | Slot    | Places the children after the input, children should be small                                     |
+| `InputField.Label`    | Wrapper | A wrapper for the input field that renders labels, help text, and error messages around the input |
+
+### `InputField.Icon`
+
+The `Icon` slot provides a convenient way to add a small icon (typically 20 x 20 pixel) to the left of the input, before the prefix. In the examples below we are using a grey circle as our example "icon" because the icons were not ready at the time of this writing, and the prefix is set to a 🍺.
+
+<IconExample />
+
+### `InputField.Controls`
+
+The `Controls` slot is used to add a small icon or other component to the right side of the input, after the suffix. This is useful for adding steppers to number inputs, or a little grey X that clears the input when clicked. You can supply anything you like, but the intention is for this element to be clickable. In this example, the suffix is set to a 🍺 and notice that it is lined up with the input and prefix on the left-side, _not_ the controls on the right-side.
+
+<ControlsExample />
+
+### `InputField.Label`
+
+The `Label` sub-component is used to wrap the `InputField` component. It provides the eponymous "label" for the wrapped input element, as an outer later. It is also used to provide additional label adjacent texts such as help text and error messages. Since we have begun to adopt an inner labelling system, this outer label will primarily be used to provide help text and errors. Since it is an HTML label element, you can click on any of these labels to focus the input.
+
+The Label's API is given below.
+
+| Prop        | Type                    | Description                                                      |
+| ----------- | ----------------------- | ---------------------------------------------------------------- |
+| `label?`    | `string`                | The primary label, title, or "name" of the wrapped input element |
+| `helpText?` | `string`                | A string of help text to be displayed below the input            |
+| `errors?`   | `{ message: string }[]` | An array of error messages to be displayed below the input.      |
+
+Also note that the example below uses `InputText.Label` rather than `InputField.Label`. All of the sub-components and slots available on the `InputField` are also available on the simple inputs, unless otherwise mentioned.
+
+<OuterLabelExample />
+
+### `InputNumber.Stepper`
+
+Not mentioned in the general API above, but worthy of note, the stepper is such a common control for number inputs that we have provided it as a sub-component of the `InputNumber` simple input. It can be dropped into any input, not only the `InputNumber`, as you can see in the example below.
+
+<StepperExample />
+
+### All Dressed
+
+Finally, just for fun, here is an example of an input with everything! Never actually do this, it's awful.
+
+<AllDressedExample />

package/src/lib/components/layout/flex.tsx

@@ -0,0 +1,22 @@
+import styled from 'styled-components'
+import { is } from '@helpers'
+
+export const Flex = styled.div<{ column?: boolean, center?: boolean }>`
+  display: flex;
+  ${({ center }) => is(center) ? 'align-items: center;' : '' }
+  flex-direction: ${({ column }) => is(column) ? 'column' : 'row'}
+`
+
+export const SpaceBetween = styled(Flex)`
+  justify-content: space-between;
+`
+
+export const SpaceAround = styled(Flex)`
+  justify-content: space-around;
+`
+
+export const Center = styled(Flex)`
+  align-items: center;
+  justify-content: space-around;
+`
+

package/src/lib/components/layout/grid-layout.tsx

@@ -0,0 +1,40 @@
+import styled from 'styled-components'
+import { isDefined } from '@helpers'
+
+interface IGridLayoutGeneratorProps {
+  columns?: number
+  rows?: number
+  columnGutter?: number
+  rowGutter?: number
+}
+
+const DEFAULT: IGridLayoutGeneratorProps = {
+  columns: 12,
+  columnGutter: 24,
+  rowGutter: 24,
+}
+
+export function gridLayoutGenerator (props: IGridLayoutGeneratorProps = {}) {
+  const options = {
+    ...DEFAULT,
+    ...props,
+  }
+
+  const Grid = styled.div`
+    display: grid;
+    grid-template-columns: repeat(${options.columns}, 1fr);
+    ${isDefined(options.rows) 
+      ? `grid-template-rows: repeat(${options.rows}, 1fr);` 
+      : ''}
+    grid-column-gap: ${options.columnGutter}px;
+    grid-row-gap: ${options.rowGutter}px;
+  `
+
+  const Cell = styled.div`
+  `
+
+  return {
+    Grid,
+    Cell,
+  }
+}

package/src/lib/components/layout/index.ts

@@ -0,0 +1,3 @@
+export * from './left-right-layout'
+export * from './flex'
+export * from './grid-layout'

package/src/lib/components/layout/left-right-layout.tsx

@@ -0,0 +1,67 @@
+import { Margin } from '@foundations'
+import { FC, PropsWithChildren } from '@helpers'
+import { Body, Heading3 } from 'components/typography'
+import styled from 'styled-components'
+
+interface ILeftRightLayoutGeneratorProps {
+  columns?: number
+  columnGutter?: number
+  rowGutter?: number
+}
+
+const DEFAULT: ILeftRightLayoutGeneratorProps = {
+  columns: 12,
+  columnGutter: 24,
+  rowGutter: 0,
+}
+
+export function leftRightLayoutGenerator (layoutProps: ILeftRightLayoutGeneratorProps = {}) {
+  const options = {
+    ...DEFAULT,
+    ...layoutProps,
+  }
+
+  const LayoutFrame = styled.div`
+    display: grid;
+    grid-template-columns: repeat(${options.columns}, 1fr);
+    grid-column-gap: ${options.columnGutter}px;
+    grid-row-gap: ${options.rowGutter}px;
+  `
+
+  const Left = styled.div`
+    grid-column: 1 / span 4;
+    grid-row: third-line / 4;
+  `
+
+  const Right = styled.div`
+    grid-column: 5 / span 8;
+    grid-row: third-line / 4;
+  `
+
+  const Slots = {
+    Left,
+    Right,
+    HeadingText: styled(Heading3)`
+      margin-bottom: ${Margin.m};
+    `,
+    HelpText: styled(Body).attrs({ subdued: true })``,
+    BodyText: Body,
+  }
+  
+  const Layout: FC<PropsWithChildren, typeof Slots> = (props) => {
+    return <LayoutFrame>{props.children}</LayoutFrame>
+  }
+
+  Layout.Left = Left
+  Layout.Right = Right
+  Layout.HeadingText = Slots.HeadingText 
+  Layout.BodyText = Slots.BodyText
+  Layout.HelpText = Slots.HelpText
+
+  return {
+    LeftRightLayout: Layout,
+    Layout,
+    Left,
+    Right,
+  }
+}

package/src/lib/components/link/index.ts

@@ -0,0 +1 @@
+export * from './link'

package/src/lib/components/link/link.test.tsx

@@ -0,0 +1,29 @@
+import { render, screen } from '@testing-library/react'
+import { Link } from '.'
+import { Interactive } from '@foundations'
+
+describe('Link', () => {
+  it('should render the component Link with default color', async () => {
+    render(
+      <Link label="Edvisor" aria-label="red" href="https://app.edvisor.io/" />
+    )
+    expect(screen.getByRole('link')).toBeInTheDocument()
+    expect(screen.getByText('Edvisor')).toBeInTheDocument()
+    expect(screen.getByRole('link')).toHaveStyle(`color: ${Interactive.Default.Default}`)
+  })
+  it('should render the component Link with subtle color', async () => {
+    render(<Link href="https://app.edvisor.io/" label="Edvisor" subtle />)
+    expect(screen.getByRole('link')).toBeInTheDocument()
+    expect(screen.getByText('Edvisor')).toBeInTheDocument()
+    expect(screen.getByRole('link')).toHaveStyle(`color: ${Interactive.Subtle.Default}`)
+  })
+  it('should render the component Link with disabled color even if it has default or subtle attributes color', async () => {
+    render(
+      <Link subtle disabled label="Edvisor" href="https://app.edvisor.io/" />
+    )
+
+    expect(screen.getByRole('link')).toBeInTheDocument()
+    expect(screen.getByText('Edvisor')).toBeInTheDocument()
+    expect(screen.getByRole('link')).toHaveStyle(`color: ${Interactive.Default.Disabled}`)
+  })
+})

package/src/lib/components/link/link.tsx

@@ -0,0 +1,56 @@
+import styled from 'styled-components'
+import { AnchorHTMLAttributes } from 'react'
+import { FC, is } from '@helpers'
+import { Interactive } from '@foundations'
+
+export const HTMLAnchor = styled.a<{disabled: boolean, initialColor: string, interactionColor: string}>`
+  color: ${({ initialColor }) => initialColor};
+  pointer-events: ${({ disabled }) => disabled ? 'none' : 'auto' };
+  &:hover{
+    text-decoration: none;
+    color: ${({ interactionColor }) => interactionColor};
+  }
+  &:active{
+    text-decoration: underline;
+  }
+`
+
+interface ILinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  label: string;
+  subtle?: boolean
+  disabled?: boolean
+}
+
+export const Link: FC<ILinkProps> = (props) => {
+
+  const { label, disabled = false, subtle, ...rest } = props
+  const initialColor = getInitialColor(props)
+  const interactionColor = getInteractionColor(props)
+
+  return (
+    <HTMLAnchor 
+      {...rest}
+      disabled={disabled}
+      initialColor={initialColor} 
+      interactionColor={interactionColor}
+    >
+      {label}
+    </HTMLAnchor>
+  )
+}
+
+function getInitialColor ({ subtle, disabled }: ILinkProps) {
+  if (is(disabled)) {
+    return Interactive.Default.Disabled
+  }
+
+  return is(subtle)
+    ? Interactive.Subtle.Default
+    : Interactive.Default.Default
+}
+
+function getInteractionColor ({ subtle }: ILinkProps) {
+  return is(subtle)
+    ? Interactive.Subtle.Hover
+    : Interactive.Default.Hover
+}

package/src/lib/components/link/storybook/link.stories.mdx

@@ -0,0 +1,52 @@
+import { Canvas, Meta } from '@storybook/addon-docs';
+import { Link } from '../link'
+import { Button } from '../../molecules/button'
+import { Body } from '../../typography'
+
+
+<Meta title="Components/Link" />
+
+# Link
+
+Links are navigational actions that take users to another place. They can appear within or directly following a sentence. Links should not to be mistaken with a Plain Button which are used for actions that aren’t related to navigation.
+  
+
+## How to use it
+The Link component is an extension of HTML <b><a\></b> tag, but its use is limited to textual anchors.
+
+## Default
+
+The Link component with default behavior and styles
+<Canvas>
+<Body>
+  <Link href="https://app.edvisor.io/" target="_blank" label="Edvisor" /> is the number 1 student recruitment software
+</Body>
+</Canvas>
+
+## Subtle
+The Link component with subtle behavior and styles
+<Canvas>
+<Body>
+  Streamline the way you sell education with <Link subtle href="https://app.edvisor.io/" target="_blank" label="Edvisor" />, the best student recruitment software.
+</Body>
+</Canvas>
+
+## Disabled
+
+A disabled Link prevents user interaction.
+<Canvas>
+<Body>
+  Education with <Link subtle disabled href="https://app.edvisor.io/" target="_blank" label="Edvisor" /> is the best.
+</Body>
+</Canvas>
+
+## API
+
+Extends `HTMLAttributes<HTMLAnchorElement>`. Check the documentation <Link href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement" target="_blank" label="here"/>.
+
+| Prop        | Type      | Description               |
+| ----------- | --------- | --------------------------|
+| `label`     | `string`  | the text used as anchor   | 
+| `default?`  | `boolean` | default styling           |
+| `subtle?`   | `boolean` | subtle styling            |
+| `disabled?` | `boolean` | prevents user interaciton |

package/src/lib/components/molecules/avatar/avatar-size-flags.tsx

@@ -0,0 +1,55 @@
+// this file was generated, but it is safe to modify
+import { bitwiseOr, MappedEnum, RequireOnlyOne, PropsWithChildren } from '@helpers'
+import { Label, Body, Display } from 'components/typography'
+
+const enum AvatarSize {
+  small = 1,
+  medium = 2,
+  large = 4,
+}
+
+type AvatarSizes<T> = MappedEnum<typeof AvatarSize, T>
+
+function toAvatarSize(n: number): AvatarSize {
+  switch (n) {
+    case AvatarSize.small:
+      return AvatarSize.small
+    case AvatarSize.medium:
+      return AvatarSize.medium
+    case AvatarSize.large:
+      return AvatarSize.large
+    default:
+      return AvatarSize.medium
+  }
+}
+
+const AvatarSizeValues = {
+  [AvatarSize.small]: '32px',
+  [AvatarSize.medium]: '40px',
+  [AvatarSize.large]: '60px',
+}
+
+const AvatarSizeNodes = {
+  [AvatarSize.small]: Label,
+  [AvatarSize.medium]: Body,
+  [AvatarSize.large]: Display,
+}
+
+export type AvatarSizeProps = Partial<RequireOnlyOne<AvatarSizes<boolean>>> &
+  PropsWithChildren
+
+export function getValuesBySize(props: AvatarSizeProps): string {
+  return AvatarSizeValues[
+    toAvatarSize(
+      bitwiseOr([props.small, props.medium, props.large])
+    )
+  ]
+}
+
+export function getNodeToRenderText(props: AvatarSizeProps): React.ElementType {
+  return AvatarSizeNodes[
+    toAvatarSize(
+      bitwiseOr([props.small, props.medium, props.large])
+    )
+  ]
+}

package/src/lib/components/molecules/avatar/avatar.test.tsx

@@ -0,0 +1,114 @@
+import {render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { Avatar } from './index'
+
+describe('Avatar Tests', () => {
+  describe('Avatar Tests', () => {
+    it('should render the acronym name from user', async () => {
+      render(
+        <Avatar
+          name="Some Full Name"
+          small
+        />
+      )
+
+      expect(screen.getByText('SN')).toBeInTheDocument()
+      expect(screen.queryByRole('img')).not.toBeInTheDocument()
+      expect(screen.queryByText('Some Full Name')).not.toBeInTheDocument()
+    })
+    it('should render the acronym name with just two parts of name', async () => {
+      render(
+        <Avatar
+          name="Some Name"
+          small
+        />
+      )
+
+      expect(screen.getByText('SN')).toBeInTheDocument()
+    })
+    it('should render the acronym name with just one parts of name', async () => {
+      render(
+        <Avatar
+          name="Name"
+          small
+        />
+      )
+
+      expect(screen.getByText('N')).toBeInTheDocument()
+    })
+    it('should not render the acronym with empty name', async () => {
+      render(
+        <Avatar
+          name=""
+          small
+        />
+      )
+      expect(screen.queryByText('Name')).not.toBeInTheDocument()
+    })
+  })
+
+  it('should render the image from user', async () => {
+    render(
+      <Avatar
+        name="Some Full Name"
+        imageUrl='https://blog.edvisor.io/hubfs/Edvisor%20Smi.png'
+      />
+    )
+
+    expect(screen.queryByText('SN')).not.toBeInTheDocument()
+    expect(screen.queryByText('Some Full Name')).not.toBeInTheDocument()
+    expect(screen.getByRole('img')).toBeInTheDocument()
+  })
+
+  it('should not have accessibility issues', async () => {
+    const { container } = render(
+      <Avatar
+        name="Some Full Name"
+        small
+      />
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  describe('withLabel behavior Tests', () => {
+    it('should render the full name and the acronym name from user', async () => {
+      render(
+        <Avatar
+          name="Some Full Name"
+          withLabel
+        />
+      )
+
+      expect(screen.queryByRole('img')).not.toBeInTheDocument()
+      expect(screen.getByText('SN')).toBeInTheDocument()
+      expect(screen.getByText('Some Full Name')).toBeInTheDocument()
+    })
+
+    it('should render the full name and the user image', async () => {
+      render(
+        <Avatar
+          name="Some Full Name"
+          imageUrl='https://blog.edvisor.io/hubfs/Edvisor%20Smi.png'
+          withLabel
+        />
+      )
+
+      expect(screen.queryByText('SN')).not.toBeInTheDocument()
+      expect(screen.getByText('Some Full Name')).toBeInTheDocument()
+      expect(screen.getByRole('img')).toBeInTheDocument()
+    })
+
+    it('should not have accessibility issues', async () => {
+      const { container } = render(
+        <Avatar
+          name="Some Full Name"
+          imageUrl='https://blog.edvisor.io/hubfs/Edvisor%20Smi.png'
+          withLabel
+        />
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
+})

package/src/lib/components/molecules/avatar/avatar.tsx

@@ -0,0 +1,80 @@
+import styled from 'styled-components'
+import { FC, isDefined, isNil, Nothing } from '@helpers'
+import { Margin, Surface } from '@foundations'
+import { SpaceAround } from '../../layout/'
+import { AvatarSizeProps, getValuesBySize, getNodeToRenderText } from './avatar-size-flags'
+import { Label } from 'components/typography'
+
+const Container = styled(SpaceAround)`
+  align-items: center;
+`
+
+const Circle = styled.div<{ size: string }>`
+  width: ${({ size }) => size};
+  height: ${({ size }) => size};
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: space-around;
+  background: ${Surface.Neutral.Default};
+`
+
+const Image = styled.img`
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+`
+
+const FullName = styled(Label)`
+  margin-left: ${Margin.xs};
+`
+interface IAvatarProps {
+  name: string;
+  imageUrl?: string;
+  imageLabel?: string;
+  withLabel?: boolean;
+  className?: string
+}
+type IProps = IAvatarProps & AvatarSizeProps
+
+const isFirstOrLast = (el: string,
+  index: number,
+  items: Array<string>): boolean =>
+    isDefined(el) && index === 0 || index === items.length - 1
+
+const getInitial = (text: string): string => isNil(text)
+  ? ''
+  : text.charAt(0)
+
+
+const getInitialsFromName = (name: string): string =>  {
+  const allNames = name.trim().split(' ')
+  const initials = allNames
+    .filter(isFirstOrLast)
+    .map(getInitial)
+    .join('')
+
+  return initials
+}
+
+export const Avatar: FC<IProps> = (props) => {
+  const {name, imageUrl, withLabel, imageLabel = `${name} avatar` } = props
+  const size = getValuesBySize(props)
+  const Text = getNodeToRenderText(props)
+
+  if (!isDefined(name)) {
+    return <Nothing />
+  }
+
+  return (
+    <Container className={props.className}>
+      <Circle size={size}>
+        { isDefined(imageUrl)
+         ? <Image src={imageUrl} alt={imageLabel}/>
+         : <Text>{getInitialsFromName(name)}</Text>
+        }
+      </Circle>
+      { isDefined(withLabel) && <FullName>{name}</FullName> }
+    </Container>
+  )
+}

package/src/lib/components/molecules/avatar/index.tsx

@@ -0,0 +1 @@
+export * from './avatar'