uikit-react-public 0.11.13

package/lib/components/Button/Button.mdx

@@ -0,0 +1,325 @@
+import * as ButtonStories from "./Button.stories";
+import {
+  Meta,
+  Title,
+  Subtitle,
+  Canvas,
+  Controls,
+  ArgTypes,
+} from "@storybook/blocks";
+
+export const usage = {
+  default: `<Button>Default Button</Button>`,
+  primary: `<Button variant='primary'>Primary Button</Button>`,
+  secondary: `<Button variant='secondary'>Secondary Button</Button>`,
+  tertiary: `<Button variant='tertiary'>Tertiary Button</Button>`,
+  destructive: `<Button destructive>Destructive Button</Button>`,
+  destructiveSecondary: `<Button variant='secondary' destructive>Destructive Secondary Button</Button>`,
+  disabled: `<Button disabled>Disabled Button</Button>`,
+  disabledSecondary: `<Button variant='secondary' disabled>Disabled Secondary Button</Button>`,
+  disabledTertiary: `<Button variant='tertiary' disabled>Disabled Tertiary Button</Button>`,
+  withIcon: `<Button icon={<Icon.AlertTriangle />}>Button</Button>`,
+  iconOnly: `<Button icon={<Icon.AlertTriangle />} aria-label='Button description' tooltip='Tooltip' />`,
+  loading: `<Button loading>Loading Button</Button>`,
+  link: `<Button as='a' href='https://www.ucl.ac.uk' target='_blank'>Go to UCL&#39;s website</Button>`,
+  fullWidth: `<Button fullWidth>Full Width Button</Button>`,
+};
+
+<Meta of={ButtonStories} />
+<Title />
+<Subtitle>
+  A polymorphic button component with multiple variants & lots of features
+</Subtitle>
+
+The primary use case for the `<Button>` component is to create a clickable button element on a screen — self-evidently a common UI/UX pattern that doesn't need much additional explanation.
+
+Technically speaking, we mean the <a href='https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button' target='_blank'>native HTML `<button>` element</a>, which accepts click events that can trigger changes in application state.
+
+The `<Button>` component is, therefore, essentially a wrapper for this native `<button>` element, with styling in accordance with UCL Design System guidelines.
+
+Use this component when you want a clear 'button' in your user interface that has an associated '_action_': e.g. 'Submit', 'Save', 'Delete', etc. An 'action' in this context triggers some kind of change in the application state.
+
+- **Design specifications** available in Figma: <a href="https://www.figma.com/design/8Sm5PxWOWJYpYXAzhRzUzt/UCL-Design-System-UI-Kit?node-id=2128-184" target="_blank">UCL Design System UI Kit | Buttons</a>
+- **Component files** located in `lib/component/Button/` in the UIKit-React repository: <a href='https://github.com/ucl-isd/uikit-react/tree/main/lib/components/Button' target='_blank'>ucl-isd/uikit-react | Button</a>
+
+<Canvas source={{ code: usage.default }} />
+
+[Interactive table of props available below.](#props)
+
+## Contents
+
+- [Variants](#variants)
+  - [Primary](#primary)
+  - [Secondary](#secondary)
+  - [Tertiary](#tertiary)
+- [Destructive buttons](#destructive-buttons)
+- [Disabled buttons](#disabled-buttons)
+- [Icons](#icons)
+  - [Icon right](#icon-right)
+  - [Icon only](#icon-only)
+- [Loading Spinner](#loading-spinner)
+- [Polymorphism](#polymorphism)
+- [Full width](#full-width)
+- [Props](#props)
+
+## Variants
+
+The `<Button>` component has three 'variants', which describe <a href='https://www.interaction-design.org/literature/topics/visual-hierarchy' target='_blank'>visual hierarchy</a>:
+
+- **primary** (default)
+- **secondary**
+- **tertiary**
+
+'Primary' buttons are the most obvious, clear, and demand attention from the user. 'Secondary' buttons are less important, and 'tertiary' buttons are the least important.
+
+`variant?: 'primary' | 'secondary' | 'tertiary';`
+
+### Primary
+
+The default variant of the button. The most important or most common actions should use this variant.
+
+<Canvas
+  of={ButtonStories.Primary}
+  sourceState="shown"
+  source={{ code: usage.primary }}
+/>
+
+### Secondary
+
+The secondary variant is used for less important actions. It should be used when the primary action is already clear, and you want to provide an alternative action that is still visible but not as prominent.
+
+You might, for example, use a 'secondary' button that cancels an action, or takes the user on a path away from their most likely current goal.
+
+<Canvas
+  of={ButtonStories.Secondary}
+  sourceState="shown"
+  source={{ code: usage.secondary }}
+/>
+
+## Tertiary
+
+Tertiary buttons add one final layer of diminishing importance. They are used for actions that are less important than the primary and secondary actions.
+
+<Canvas
+  of={ButtonStories.Tertiary}
+  sourceState="shown"
+  source={{ code: usage.tertiary }}
+/>
+
+## Destructive buttons
+
+Actions that delete or remove something from the application should be clearly marked as 'destructive'. This is a UX pattern that makes it clear this action is _not reversible_.
+
+Note that only 'primary' and 'secondary' button variants can be marked as 'destructive'. This is intentional: any action that is destructive should be considered 'important' enough that using a tertiary button is not appropriate.
+
+`destructive?: boolean;`
+
+<Canvas
+  of={ButtonStories.Destructive}
+  sourceState="shown"
+  source={{ code: usage.destructive }}
+/>
+<Canvas
+  of={ButtonStories.DestructiveSecondary}
+  sourceState="shown"
+  source={{ code: usage.destructiveSecondary }}
+/>
+
+## Disabled buttons
+
+A button that *could* be used but is *currently disabled* due to the application's state.
+
+A button in this state **cannot be pressed**, from a technical implementation: click events are not triggered, even if an `onClick` callback prop is passed to the `<Button>`.
+
+_Technical info_: The <a href='https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/disabled' target='_blank'>`disabled` attribute</a> is available on the native `<button>` element. The `<Button>` component simply passes this attribute to the underlying `<button>` element.
+
+All variants of the button can be disabled.
+
+`disabled?: boolean;`
+
+<Canvas
+  of={ButtonStories.Disabled}
+  sourceState="shown"
+  source={{ code: usage.disabled }}
+/>
+<Canvas
+  of={ButtonStories.DisabledSecondary}
+  sourceState="shown"
+  source={{ code: usage.disabledSecondary }}
+/>
+<Canvas
+  of={ButtonStories.DisabledTertiary}
+  sourceState="shown"
+  source={{ code: usage.disabledTertiary }}
+/>
+
+## Icons
+
+Pass an <a href='?path=/docs/components-ready-to-use-icon--documentation' target='_blank'>icon</a> to the `<Button>` via the `icon` prop.
+
+**_Technical note:_** The `icon` prop takes **an actual `<Icon>` component, not an icon name** as a string.
+
+Any icon available in this component can be used — the `<Icon>` component also accepts custom SVG icons.
+
+Specify the position of the icon using the `iconPosition` prop. The default is `left`, and you can also specify `right`.
+
+`icon?: ReactNode;` <br />
+`iconPosition?: 'left' | 'right';`
+
+<Canvas
+  of={ButtonStories.WithIcon}
+  sourceState="shown"
+  source={{ code: usage.withIcon }}
+/>
+
+### Icon right
+
+`iconPosition: 'right'`
+
+```tsx
+<Button icon={<Icon.Upload />} iconPosition='right'>
+  Upload
+</Button>
+```
+
+[Check this component story to see the icon on the right.](?path=/story/components-ready-to-use-button--with-icon&args=iconPosition:right)
+
+### Icon only
+
+To render a `<Button>` that _only_ displays an icon, you can simply not pass in any children. 
+
+<Canvas
+  of={ButtonStories.IconOnly}
+  sourceState="shown"
+  source={{ code: usage.iconOnly }}
+/>
+
+_Background info:_ An HTML element that has no children is known as a '<a href='https://developer.mozilla.org/en-US/docs/Glossary/Void_element' target='_blank'>void element</a>', or an 'empty' element. We must 'self-close' these elements in React using the `/>` syntax: `<Button />`
+
+The component logic checks whether children are provided. An empty string will count as 'not provided'. The width of the `<Button>` is then set according to a single centred icon. 
+
+UIKit-React also [provides an `<IconButton>` component](?path=/docs/components-ready-to-use-iconbutton--documentation), which is simply an `<Icon>` wrapped in a `<button>`. This is a more generic component, without the additional features of the `<Button>` component. If you **only want an icon that is clickable** (it can handle click events via an `onClick` callback prop), just use the `<IconButton>` component, instead.
+
+- **UX recommendation:** Include text to appear on hover via the `tooltip` prop, so users receive a text description alongside the icon: <br />`tooltip='Edit'`
+- **Accessibility recommendation:** Include text to be read by assistive technologies (<a href='https://abilitynet.org.uk/factsheets/introduction-screen-readers' target='_blank'>screen readers</a>) via an `aria-label` prop, so users with visual impairments understand the purpose of the button: <br />`aria-label='Edit item'`
+
+```tsx
+<Button icon={<Icon.Edit />} aria-label="Edit item" tooltip="Edit" />
+```
+
+More information about ARIA labels can be found here:
+
+- {<a
+  href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label"
+  target="\_blank"
+  > aria-label - ARIA | MDN</a>}
+- {<a
+  href="https://www.aditus.io/aria/aria-label"
+  target="\_blank"
+  > aria-label - examples and best practices | Aditus</a>}
+
+## Loading Spinner
+
+Pass a `loading` prop to the `<Button>` to show a [loading Spinner](?path=/docs/components-ready-to-use-spinner--documentation).
+
+The appropriate use case for this is to communicate to the user that an external process is happening and is not yet complete.
+
+We expect the most common example is handling asynchronous requests to servers: a 'Submit' button for a web form that awaits a success response from the server.
+
+Note that the button _cannot be pressed_ while `loading` is `true`. Click events will not be triggered. This is purposefully to prevent users triggering the same action multiple times while waiting.
+
+`loading?: boolean;`
+
+<Canvas
+  of={ButtonStories.Loading}
+  sourceState="shown"
+  source={{ code: usage.loading }}
+/>
+
+_Technical info:_ The `loading` prop would be bound to a stateful variable in the parent component. This 'loading' state is set to `true` when the button is pressed, and set to `false` when the server response is received:
+
+```tsx
+<Button loading={loading}>Submit</Button>
+```
+
+## Polymorphism
+
+We recognise that sometimes buttons are required to be used in a 'link-like' context. For example, instead of triggering a change in application state, the button takes a user to a screen in which this can be done. For flexibility, a different element to the native `<button>` element can be specified via the `as` prop.
+
+This principle is known as '<a href='https://www.freecodecamp.org/news/build-strongly-typed-polymorphic-components-with-react-and-typescript/' target='_blank'>polymorphism</a>' in React.
+
+The `<Button>` component is polymorphic, and we expect developers may want to specify either:
+
+- an anchor `<a>` element
+- a custom routing component (e.g. `Link` from `wouter`)
+
+_We do not expect developers to use the `<Button>` component as a generic wrapper for any HTML element._
+
+The `as` prop supports either a string or a React component. If unspecified, the default is of course the native `<button>` element.
+
+Given we want the button element to be an anchor `<a>`, we provide: `as='a'`.
+
+```tsx
+<Button as="a" href="https://www.ucl.ac.uk">
+  Link
+</Button>
+```
+
+Note we can also add in any other standard HTML attributes that are valid for the `<a>` element, such as `href`, `target`, etc. Particularly, `target='_blank'` usefully **opens the link in a new tab**.
+
+In the example below, the `<Button>` will take you to UCL's website when clicked:
+
+<Canvas
+  of={ButtonStories.Link}
+  sourceState="shown"
+  source={{ code: usage.link }}
+/>
+
+Using a custom routing component, such as <a href='https://github.com/molefrog/wouter?tab=readme-ov-file#link-hrefpath-' target='_blank'>`Link` from `wouter`</a>, we just need to import the component in the current file, then pass it directly to the `as` prop.
+
+```tsx
+import { Link } from "wouter";
+
+// ...
+
+<Button as={Link} to="/">
+  Link
+</Button>;
+```
+
+_Technical note:_ The `disabled` attribute is not natively available on an anchor `<a>` element. To prevent link-like buttons from successfully triggering a redirect on click when the `<Button>` otherwise appears disabled, the `href` attribute of the anchor-button is removed. This has the same effect, and the underlying `<a>` tag will not redirect the user.
+**For custom routing components, this functionality would need to be implemented manually.**
+
+## Full width
+
+A `fullWidth` prop sets the value of the `width` CSS property of the button to `100%`. This tells the button to take up the full width of its parent container — this could otherwise be set via a `className` prop.
+
+We recommend full width buttons be **no more than 350px wide** in practice, and used primarily on mobile devices. 
+
+<div style={{ maxWidth: "350px", margin: "0 auto" }}>
+  <Canvas
+    of={ButtonStories.FullWidth}
+    sourceState="none"
+    source={{ code: usage.fullWidth }}
+  />
+</div>
+
+```tsx
+<Button fullWidth>Full Width Button</Button>
+```
+
+## Props
+
+Full props specification for `<Button>` is below.
+
+Note that `<Button>` makes use of optional 'common' margin props, [as demonstrated in this component story](?path=/story/components-ready-to-use-button--common-margins&args=m:m24).
+
+<Canvas
+  of={ButtonStories.Default}
+  sourceState="hidden"
+  source={{ code: usage.default }}
+/>
+
+You can use the controls below to manipulate the `<Button>` component above.
+
+<Controls />