braid-design-system

Minor Changes

• HiddenVisually: Add support for passing IDs (#757)

  This is useful when mapping a HiddenVisually component to aria-describedby

  EXAMPLE USAGE:

  <HiddenVisually id="my-hidden-desciption">Hidden desciption</HiddenVisually>
  

• Autosuggest: Add translations prop to enable internationalisation (#757)

Patch Changes

• Autosuggest: Improve screen reader experience (#757)

  Add description informing user that suggestions will appear below field. Also, notify users about how many suggestions are available, and about automatic selections.

• TextField, PasswordField, Textarea, Dropdown: Add support for multiple field descriptions (#757)

  Previously, if a custom aria-describedby prop was passed, it would take precedence over the message prop, which also uses aria-describedby. Both descriptions can now be applied at the same time.

Patch Changes

• MenuRenderer, OverflowMenu: Fix circular dependency issue (#761)

Minor Changes

• Add MenuItemDivider component (#751)

  You can now place visual separators between groups of menu items when using OverflowMenu/MenuRenderer.

  EXAMPLE USAGE

  <OverflowMenu label="Options">
    <MenuItem onClick={() => {}}>Button</MenuItem>
    <MenuItemLink href="#">Link</MenuItemLink>
    <MenuItemDivider />
    <MenuItem onClick={() => {}}>Another button</MenuItem>
  </OverflowMenu>
  

• Add MenuItemCheckbox component (#751)

  You can now render checkboxes within OverflowMenu/MenuRenderer elements.

  EXAMPLE USAGE

  <OverflowMenu label="Checklist">
    <MenuItemCheckbox checked={true} onChange={() => {}}>
      Checkbox 1
    </MenuItemCheckbox>
    <MenuItemCheckbox checked={false} onChange={() => {}}>
      Checkbox 2
    </MenuItemCheckbox>
    <MenuItemCheckbox checked={false} onChange={() => {}}>
      Checkbox 3
    </MenuItemCheckbox>
  </OverflowMenu>
  

• Loader: Add support for aria-label (#752)

  Provides a mechanism for consumers to better communicate to assistive technologies what is happening.

  EXAMPLE USAGE:

  <Loader aria-label="Loading search results" />
  

Patch Changes

• Autosuggest: Update to ARIA 1.2 combobox spec (#754)

Minor Changes

• Badge: Add bleedY prop (#743)

  You can now choose to allow the badge’s background colour to bleed out into the surrounding layout, making it easier to align with other elements.

  For example, we can align a badge to a Heading element using an Inline, even though the badge is actually taller than the heading. If we didn’t use the bleedY prop in this case, the badge would introduce unwanted space above and below the heading.

  <Inline alignY="center" space="xsmall">
    <Heading level="4">Heading</Heading>
    <Badge bleedY tone="positive">
      New
    </Badge>
  </Inline>
  

• Add Dialog component (#746)

  Follows the WAI Aria Dialog (Modal) Pattern.

  EXAMPLE USAGE:

  <Fragment>
    <Actions>
      <Button onClick={() => setOpen(true)}>Open dialog</Button>
    </Actions>
  
    <Dialog title="Dialog Example" id={id} open={open} onClose={setOpen}>
      <Placeholder height={100} width="100%" />
    </Dialog>
  </Fragment>
  

  See the documentation for an exhaustive list of features.

Patch Changes

• List, BulletList: Ensure list items are full width (#745)

  Fixes an issue where list content was unable to stretch to the edge of its container. To allow this, we now set the list item container itself to be full width so that content is no longer constrained.

• ContentBlock: Ensure block is full width (#746)

  Fixes an issue where ContentBlocks inside of flex containers would not grow to their defined max-width.

Minor Changes

• Badge: Allow custom title text (#738)

  EXAMPLE USAGE

  <Badge tone="positive" title="3 new jobs">
    3
  </Badge>
  

• Improved server rendering of Tabs (#737)

  Previously, Tab and TabPanel components only showed their content and active states after the first render, which meant server rendering was not ideal. Active Tabs and TabPanel content can now be server rendered. Uncontrolled usages of Tabs should just work.

  For controlled Tabs using the selectedItem prop, you now need to pass the item prop (already on Tab) to TabPanel as well.

  <TabsProvider id="id" selectedItem="second">
    <Tabs label="Test tabs">
      <Tab item="first">The first tab</Tab>
      <Tab item="second">The second tab</Tab>
      <Tab item="third">The third tab</Tab>
    </Tabs>
    <TabPanels>
  -    <TabPanel>
  +    <TabPanel item="first">
        <Placeholder height={200} label="Panel 1" />
      </TabPanel>
  -    <TabPanel>
  +    <TabPanel item="second">
        <Placeholder height={200} label="Panel 2" />
      </TabPanel>
  -    <TabPanel>
  +    <TabPanel item="third">
        <Placeholder height={200} label="Panel 3" />
      </TabPanel>
    </TabPanels>
  </TabsProvider>
  

• ContentBlock: Add support for xsmall & small widths (#735)

  EXAMPLE USAGE

  <ContentBlock width="small">...</ContentBlock>
  

Patch Changes

• OverflowMenu, MenuRenderer: Assert that all child nodes are valid menu items (#731)

  In order to maintain accessibility, we now throw assertion errors in development if any child node within an OverflowMenu or MenuRenderer component is not a MenuItem/MenuItemLink.

Patch Changes

• Loader: Fix rendering issues due to browser rounding errors (#728)

Minor Changes

• Box: Added zIndex prop (#726)

  The following z-index palette is now available on Box:

  Local stacking

  • 0
  • 1
  • 2

  Global stacking

  • "dropdownBackdrop"
  • "dropdown"
  • "sticky"
  • "modalBackdrop"
  • "modal"
  • "notification"

  EXAMPLE USAGE

  <Box position="fixed" zIndex="sticky">
    ...
  </Box>
  

• TabPanels: Add renderInactivePanels prop (#722)

  By default, the children of TabPanel components are only rendered when they are selected. However, in cases where you want to preserve local component state when switching tabs, this behaviour is undesirable. Setting renderInactivePanels will cause the TabPanel children to be rendered even when visually hidden.

  Note: This is not a visual change, the panels will still be hidden from the user.

  e.g.

  <TabsProvider selectedItem={0}>
    <Tabs>
      <Tab>First</Tab>
      <Tab>Second</Tab>
    </Tabs>
    <TabPanels renderInactivePanels>
      <TabPanel>
        <Text>Tab 1</Text>
      </TabPanel>
      <TabPanel>
        {/* This TabPanel is hidden but still in the DOM */}
        <Text>Tab 2</Text>
      </TabPanel>
    </TabPanels>
  </TabsProvider>
  

• Added support for refs on Link (#725)

  Forwarding refs is necessary for certain accessibility patterns (e.g. managing focus states), but the Link component wasn't doing this correctly.

  Please note that, if you're passing a custom linkComponent implementation to BraidProvider, you'll need to ensure that you're using the new makeLinkComponent helper function to forward refs, otherwise any attempt to pass a ref to Link will throw an error.

  MIGRATION GUIDE

  -import { BraidProvider, LinkComponent } from 'braid-design-system';
  +import { BraidProvider, makeLinkComponent } from 'braid-design-system';
  
  -const CustomLink: LinkComponent = ({ href, ...restProps }) =>
  +const CustomLink = makeLinkComponent({ href, ...restProps }, ref) =>
    href[0] === '/' ? (
  -    <ReactRouterLink to={href} {...restProps} />
  +    <ReactRouterLink to={href} {...restProps} ref={ref} />
    ) : (
  -    <a href={href} {...restProps} />
  +    <a href={href} {...restProps} ref={ref} />
    );
  
  export const App = () => (
    <BraidProvider linkComponent={CustomLink} {...rest}>
      ...
    </BraidProvider>
  );
  

• Link: Fixed types for className prop to support the full classnames API (#725)

  You can now pass arrays and objects to the className prop on Link without type errors.

  For example:

  <Link
    href="#"
    className={[
      'someClass',
      ['anotherClass', 'yetAnotherClass'],
      { someConditionalClass: someBoolean },
    ]}
  >
    ...
  </Link>
  

• Added MenuItemLink component (#725)

  You can now render semantic links within menu components, e.g. OverflowMenu, MenuRenderer

  For example:

  <OverflowMenu label="Options">
    <MenuItem onClick={() => {}}>Button</MenuItem>
    <MenuItemLink href="...">Link</MenuItemLink>
  </OverflowMenu>
  

  Note that links are rendered internally using Link. If you want to customise the rendering of these links, you need to provide a custom linkComponent implementation to BraidProvider.

Patch Changes

• Change SEEK Business formAccent token to match Seek ANZ (#718)

Patch Changes

• List, BulletList: Limit width to 100% of parent (#715)

Minor Changes

• Add List component (#710)

  List serves as a replacement for the BulletList and Bullet components which adds the following improvements:

  • Support for numbers and alpha characters as bullets
  • Support for custom start positions in number/alpha lists
  • Rich content support, e.g. list items with multiple paragraphs, nested lists, etc.

  Note: The BulletList and Bullet components have been marked as deprecated and will be removed in an upcoming major release.

  MIGRATION GUIDE

  If you want to migrate from BulletList to List, you can simply replace BulletList with List, and Bullet with Text:

  -<BulletList>
  -  <Bullet>...</Bullet>
  -  <Bullet>...</Bullet>
  -  <Bullet>...</Bullet>
  -</BulletList>
  
  +<List>
  +  <Text>...</Text>
  +  <Text>...</Text>
  +  <Text>...</Text>
  +</List>
  

• TextLink, TextLinkButton, TextLinkRenderer: Default weight prop to "regular" when nested inside secondary text (#714)

  As of v28.13.0, TextLink components that were nested inside secondary text would be "weak" by default, i.e. the same tone as the surrounding text and underlined. In practice, this turned out to be somewhat unpredictable behaviour for consumers. We've now reverted this to the previous behaviour of being "regular" weight by default, i.e. blue and medium font weight.

  Note that, if needed, you can still use the weaker link treatment within secondary text via an explicit prop override:

  <Text tone="secondary">
    The TextLink in this sentence is{' '}
    <TextLink href="..." weight="weak">
      weak.
    </TextLink>
  </Text>
  

Patch Changes

• AccordionItem: Prevent Safari from clipping label text (#712)

Patch Changes

• Throw meaningful error when using 'BraidProvider' in unit tests (#707)

Major Changes

• Improved trimming of white space around text (#696)

  Migrated from our custom Basekick implementation to 🛶 Capsize to more accurately trim the white space around text. This will have subtle white space changes throughout the UI, but will largely just be improvements to the balance of space around text.

  BREAKING CHANGES

  Heading/Text: Removed LEGACY_SPACE

  The _LEGACY_SPACE_ prop was provided to support consumers migrating to v14 when the white space cropping and layout components were originally introduced. This has now been removed to allow us to further improve on our approach.

  Migrating off this prop will require consumers to perform the following steps:

  • Remove the usage of _LEGACY_SPACE_ on a component
  • Conduct a visual review of the impact (component will appear closer to neighbouring elements)
  • Use existing layout components, e.g. Stack, to define/control the reintroduction of the desired space.

  Any issues, please reach out to the team as we are happy to help support consumers in migrating.

  Theme Tokens: Text and Heading definitions

  There have been strutural theme changes for heading and text definitions to support the defining of capHeight in the system. Previously a definition contained size that was the specified font size inclusive of surrounding white space.

  A definition now has capHeight which is representative of the visual height, supporting improved alignment with other elements like, icons etc.

  {
    text: {
      standard: {
        mobile: {
  -        size: 16,
  +        capHeight: 11.43,
          rows: 6
        }
      }
    }
  }
  

  This is not likely to affect consumers, unless these theme values are used explicitly in custom treat files.

  Theme Tokens: Descender and Cap Height scales

  Instead of the calculated values of capHeightScale and decenderHeightScale, a theme now accepts fontMetrics—a structure that represents the metadata from the font itself.

  -const capHeight = 24 * theme.typography.capHeightScale;
  +const capHeight = 24 * (theme.typography.fontMetrics.capHeight / theme.typography.fontMetrics.unitsPerEm);
  

  -const descender = 24 * theme.typography.decenderHeightScale;
  +const descender = 24 * (Math.abs(theme.typography.fontMetrics.descent) / theme.typography.fontMetrics.unitsPerEm);
  

Patch Changes

• Fix type error in Textarea formatRanges (#706)

Minor Changes

• Add Notification icon (#702)

• Add useBreakpoint (#700)

  useBreakpoint will return the breakpoint the browser viewport currently falls within (mobile, tablet or desktop). As this can only be calculated in the browser, the value may also be null. Window resizing is supported.

  Note: Avoid use of this hook where possible. Responsive properties and media queries are a better option in most cases.

Minor Changes

• TextLink, TextLinkButton: Add weight prop, add weak weight variant (#697)

  You can now render links that are underlined while inheriting the tone and weight of its surrounding text.

  EXAMPLE USAGE

  <Text>
    This sentence contains a{' '}
    <TextLink href="..." weight="weak">
      weak TextLink.
    </TextLink>
  </Text>
  

Minor Changes

• seekBusiness theme: Inherit from new apac theme rather than the deprecated seekAnz theme (#694)

  Just like the migration from seekAnz to apac, the visual changes are as follows:

  • The body background has changed from #eeeeee to #f5f6f8.
  • All grey colours now have a hint of blue.
  • Buttons and form fields have decreased in height from 48px to 44px.
  • Border radiuses have increased from 2px to 4px.

  It's possible that your application has custom design elements that depend on these older values in order to look correct. It's also possible that your application is part of a broader user journey that makes use of these older design standards. As a result, a design review is highly recommended.

Patch Changes

• Inline: Prevent overlapping of preceding interactive components (#692)

Minor Changes

• TextLinkButton: Pass click event object to onClick handler (#688)

  The onClick handler was previously called without any arguments. We now pass the click event object through as expected.

Minor Changes

• Button: Add aria-controls and aria-expanded props (#686)

• Add Disclosure component (#686)

  This component serves as a replacement for ToggleContent from SEEK Style Guide.

  SEEK STYLE GUIDE MIGRATION GUIDE

  • ToggleContent has been renamed to Disclosure.
  • The onShowMore prop has been renamed to onToggle.
  • The spacing around the button has changed to follow Braid's layout guidelines. Design review is recommeded.

  -<ToggleContent onShowMore={(expanded) => { ... }} {...rest}>
  +<Disclosure onToggle={(expanded) => { ... }} {...rest}>
  

• TextLinkButton: Add aria-controls, aria-describedby and aria-expanded props (#686)

Minor Changes

• Add TextLinkButton component (#683)

  Allows you to render a semantic button that looks like a TextLink.

  This component renders a native span element with an ARIA role of button so that, unlike a standard button element, text can wrap across multiple lines.

Minor Changes

• Add IconLanguage (#680)