[email protected]

This release is a huge milestone for Braid with upgrades occurring across a number of key areas:

Migrate layout components to CSS Gap

With SEEKs Browser Support Policy now enabling adoption of CSS gap, Braid's layout components are now able to lean into the platform directly for its declarative, parent-driven approach to white space management.

The result is on average our experiences receive around a 20% reduction in DOM elements, more performant rendering, better composability without the introduction of intermediary elements and a better debug experience in dev tools.

The key tradeoff is the removal of dividers functionality which is explained further here.

Reduce gutter size in seekJobs theme

The size of the gutter token on the seekJobs theme has been reduced from large (i.e. 32px), to medium (i.e. 24px).
This is a semantic token that runs through many system components, and consumer should perform a visual design audit to ensure experiences are laid out as intended.

Other key changes

• Remove support for React v17.x
• Removal of deprecated features

See full changelog below 👇

Major Changes

• Stack, Inline: Consumers need to render li elements (#1626)

  When setting component to ul or ol on Stack or Inline, consumers need to ensure they render children as li elements.
  Previously Braid owned an intermediate HTML element, ensuring it was an li when required.
  Moving to CSS gap means child elements are no longer being wrapped, requiring consumers to update their child elements to the correct HTML element, e.g. li.

  MIGRATION GUIDE:

   <Stack component="ul">
  -  <Text>Item 1</Text>
  +  <Text component="li">Item 1</Text>
  -  <Text>Item 2</Text>
  +  <Text component="li">Item 2</Text>
   </Stack>

• Autosuggest: Remove deprecated message syntax from suggestions prop (#1626)

  Remove the deprecated message syntax from the suggestions prop in favour of the noSuggestionsMessage prop.

  MIGRATION GUIDE:

   <Autosuggest
     ...
  -  suggestions={{ message: 'No results found' }}
  +  suggestions={[]}
  +  noSuggestionsMessage="No results found"
   />

• Text, Heading: Remove deprecated truncate prop (#1626)

  Remove the deprecated truncate prop in favour of the maxLines prop which accepts a number of lines to truncate the text to.

  MIGRATION GUIDE:

   <Text
  -   truncate
  +   maxLines={1}
   />

• Stack, Tiles: Remove divider support (#1626)

  As part of migrating our layout components to leverage flex gap, the Stack & Tiles components no longer iterate over their children, making dividers no longer feasible to implement centrally.

  While we could have exposed an API to apply this behaviour conditionally, there are edge cases that cannot be handled correctly without consumer-side rendering logic, such as when child components render nothing or a hidden element.

  MIGRATION GUIDE:

  For Stacks with static children you can manually interleave Divider components:

  -<Stack space="..." dividers>
  +<Stack space="...">
     <Component />
  +  <Divider />
     <Component />
  +  <Divider />
     <Component />
   </Stack>

  Or for conditionally rendering children you can return a [React Fragment], including the Divider and child:

  -<Stack space="..." dividers>
  +<Stack space="...">
     <Component />
     {condition ? (
  -    <Component />
  +    <>
  +      <Divider />
  +      <Component />
  +    </>
     ) : null}
   </Stack>

  For Stacks with iterable children you can return a [React Fragment] and conditionally render the Divider component as the first child, before each item (except the first):

  -<Stack space="..." dividers>
  +<Stack space="...">
    {items.map((item, index) => (
  -    <Component>{item}</Component>
  +    <Fragment key={...}>
  +      {index > 0 ? <Divider /> : null}
  +      <Component>{item}</Component>
  +    </Fragment>
    ))}
  </Stack>

  For Tiles the dividers prop was only applied when showing a single column.

  For this you can conditionally render the Divider in a Stack with the same spacing as specified on the Tiles instance, and hide it on breakpoints showing more than one column.

  Here is an example of this with static children:

  -<Tiles space="..." columns={{mobile: 1, tablet: 2}} dividers>
  +<Tiles space="..." columns={{mobile: 1, tablet: 2}}>
      <Component>{item}</Component>
  +   <Stack space="...">
  +     <Hidden above="mobile">
  +       <Divider />
  +     </Hidden>
        <Component>{item}</Component>
  +   </Stack>
  +   <Stack space="...">
  +     <Hidden above="mobile">
  +       <Divider />
  +     </Hidden>
        <Component>{item}</Component>
  +   </Stack>
  </Tiles>

  Here is an example of this with iterable children:

  -<Tiles space="..." columns={{mobile: 1, tablet: 2}} dividers>
  +<Tiles space="..." columns={{mobile: 1, tablet: 2}}>
    {items.map((item, index) => (
  -    <Component>{item}</Component>
  +    <Stack space="..." key={...}>
  +      {index > 0 ? (
  +        <Hidden above="mobile">
  +          <Divider />
  +        </Hidden>
  +      ) : null}
         <Component>{item}</Component>
  +    </Stack>
    ))}
  </Tiles>

• Drop support for React 17.x (#1626)

  To enable Braid to leverage newer React APIs, we are no longer providing support for React v17.x.
  React 18 was released in March 2022 and consumers were encouraged to upgrade to this as part of the Braid v32 release in Feb 2023 (which dropped React 16 support).

  Removing support for React 17 allows us to simplify and streamline a lot of our component APIs, which will have downstream improvements on consumer codebases.

  MIGRATION GUIDE:

  Consumers still on v17 should follow the How to Upgrade to React 18 guide.

  For sku consumers who upgraded to Braid v32 and added the "jsx-runtime workaround for ESM incompatibility", this can now be safely removed from their webpack configuration once updated to React 18:

  // sku.config.ts
  {
    dangerouslySetWebpackConfig: (config) =>
      webpackMerge(config, {
  -      resolve: {
  -        fallback: {
  -          'react/jsx-runtime': require.resolve('react/jsx-runtime'),
  -        },
  -      },
      }),
  }

• Button, ButtonLink: Remove deprecated bleedY prop (#1626)

  Remove the deprecated bleedY prop from the Button and ButtonLink components.
  Consumers should use the bleed prop instead, which bleeds based on the selected variant.

  MIGRATION GUIDE:

   <Button
  -  bleedY
  +  bleed
     {...}
   >
     Button
   </Button>

• Radio: Remove deprecated component (#1626)

  Remove deprecated Radio component in favour of RadioGroup with RadioItem children.

  MIGRATION GUIDE:

  - <Radio checked={checked} onChange={handleOnChange} label="Option" />
  + <RadioGroup
  +   value={value}
  +   onChange={handleOnChange}
  +   label="Options"
  + >
  +   <RadioItem value="1">Option</RadioItem>
  + </RadioGroup>

• Column: Prevent growing when content width specified (#1626)

  Ensure that when a column width is specified, the column does not grow or shrink.
  Only a column with no width specified will fluidly adapt to the available space.

  Fixes a bug when all Column components have a defined width, a column specifying content width would incorrectly grow to consume the available space.

• Hidden: Hide content by default. (#1626)

  Hidden will now hide content if no hidden conditions are specified, i.e. if no above, below, or print props are provided.
  Consumers should review usage of the component without these props to ensure Hidden behaves as expected.

• ButtonIcon: Remove deprecated secondary tone (#1626)

  Remove the deprecated secondary tone from ButtonIcon in favour of providing the tone directly to the Icon itself.

  MIGRATION GUIDE:

   <ButtonIcon
  -  tone="secondary"
  -  icon={<IconAdd />}
  +  icon={<IconAdd tone="secondary" />}
   />

• useColor: Align background tokens with Box and vars (#1626)

  Align the available background tokens between Box, vars, and the useColor Hook.
  Removes the surfaceDark and bodyDark tokens that were mistakenly exposed in the useColor Ho...

@braid-design-system/[email protected]

Major Changes

• Bump Braid peer dependency to v33 (#1628)

[email protected]

Patch Changes

• BraidTestProvider: Provide scrollIntoView stub function for jsdom (#1590)

  Fixes an issue where scrollIntoView is not defined in jsdom, causing tests to fail with the following error:

  Error: Uncaught [TypeError: highlightedItem?.scrollIntoView is not a function]
  

• Autosuggest: Update suggestion group heading design (#1581)

  Updating the design of the suggestion group headings, moving from formAccent to secondary tone, from all caps to provided casing, and from xsmall to small size.

• Text, Heading: Ensure maxLines truncates correctly when used as the direct child of a flex container. (#1580)

• Validate accessible field labels in development (#1591)

  Introduce development-time validation for the label prop on form fields to guard against blank values and guide towards the alternative labelling options that are available.
  This validation helps ensure that all fields are accessible to screen readers and other assistive technologies.

• Spread: Apply content width to children (#1583)

  Align the behaviour of children in Spread to be the same as Inline children.
  This makes their behaviour more predicatable when spreading full width elements, while also ensuring child elements are not stretched vertically.

• Icons: Support rendering inline as child of a flex container (#1585)

[email protected]

Minor Changes

• Autosuggest: Optimise automatic scrolling to selected suggestion by using native browser methods. (#1571)

Patch Changes

• Stack, Tiles: Deprecate dividers prop (#1574)

  In preparation for migrating Braid layout components to use CSS gap, the dividers prop has been deprecated on Stack and Tiles.

  Consumers are encouraged to migrate now in advance of its removal in v33.

  Migration Guide

  See the migration guide for details on how to migrate off the dividers prop.

• Autosuggest: Improve handling of suggestionHighlight prop when set to remaining (#1572)

  Fixes a bug in Autosuggest when using suggestionHighlight prop set to remaining.
  If the input contained multiple words, the highlighted portion would be appended to the end of matching suggestions.

• Divider: Ensure full width in flex container (#1574)

  Ensures the Divider component remains full width when used as a flex child inside a flex container.

@braid-design-system/[email protected]

Minor Changes

• LinkableHeading: Add badge support (#1574)

  EXAMPLE USAGE:

  <LinkableHeading level="3" badge={<Badge tone="caution">Deprecated</Badge>}>
    Heading
  </LinkableHeading>

[email protected]

Patch Changes

• RadioItem: Improve checked visual affordance when disabled (#1564)

  Improve the visual affordance of the checked state when disabled across all themes and colour modes.

• MenuRenderer, OverflowMenu: Limit the menu height (#1567)

  Limit the menu to show a maximum of around 10 items before scrolling (a little less so it's evident there is more to scroll to).

• TextLink: Default to weak inside secondary tone (#1561)

  Align the secondary tone with other non-neutral text tones, making the foreground color of links inherit the tone of the wrapping Text component.

  EXAMPLE USAGE:
  In the following example the TextLink will now follow the secondary tone from the wrapping Text component:

  <Text tone="secondary">
    <TextLink href="#">Link</TextLink>
  </Text>

  Previously this would have retained the default link colour from the theme.

• Standardise disabled & critical state across form fields (#1564)

  Improves the consistency of form fields when combining both disabled and critical tone, which includes:

  • Hiding critical borders
  • Hiding message and not reserving space for it unless explicitly providing the reserveMessageSpace prop.

[email protected]

Minor Changes

• Spread: Add component prop support (#1559)

  Enable support for changing the underlying HTML element of the Spread component.

  EXAMPLE USAGE:

  <Spread component="span">...</Spread>

• Spread: Add data prop support (#1559)

  EXAMPLE USAGE:

  <Spread data={{ test: 123 }}>...</Spread>

[email protected]

Minor Changes

• Column: Add support for hide above/below breakpoint (#1553)

  Introduce new hideAbove and hideBelow props on column for responsively hiding columns across breakpoint.

  These props can be used either separately or in combination to optimise content display across different screen sizes.

  EXAMPLE USAGE:

  <Columns space="small">
    <Column>
      <Placeholder height={60} label="Always visible" />
    </Column>
    <Column hideBelow="tablet">
      <Placeholder height={60} label="Tablet and above" />
    </Column>
    <Column hideAbove="mobile">
      <Placeholder height={60} label="Mobile Only" />
    </Column>
  </Columns>

• Badge: Enable usage inside typographic components (#1547)

  A Badge can now be nested inside typographic components, e.g. Text and Heading, as an inline element alongside text.
  Previously a Badge had to be aligned against text using an Inline component, which would result in the Badge dropping below the text when the copy wrapped.

  EXAMPLE USAGE:

  <Text>
    Lorem ipsum velit in <Badge>amet</Badge>.
  </Text>

• Tabs: Add size support (#1550)

  Introduces the ability to customise the size of the Tab components in the tab list.
  Available sizes are standard (default) and small.

  EXAMPLE USAGE:

  <Tabs size="small">
    <Tab>First tab</Tab>
    <Tab>Second tab</Tab>
    <Tab>Third tab</Tab>
  </Tabs>

• Spread: Add new layout component (#1554)

  Introduce a new layout component, Spread, used to justify content with both an equally distributed and a specified minimum amount of space in between each child.

  EXAMPLE USAGE:

  The Spread component works horizontally by default:

  <Spread space="small" alignY="center">
    <Heading level="4">Heading</Heading>
  
    <OverflowMenu label="Options">
      <MenuItem>First</MenuItem>
      <MenuItem>Second</MenuItem>
    </OverflowMenu>
  </Spread>

  But can be switched to vertical via the direction prop:

  <Spread space="large" direction="vertical">
    <Stack space="small">
      <Heading level="4">Heading</Heading>
      <Text>Text</Text>
    </Stack>
  
    <Text size="small" tone="secondary">
      Date
    </Text>
  </Spread>

Patch Changes

• Move badge slot inside label (#1547)

  Relocate the badge slot inside the label slot enabling the Badge to sit alongside the last word in wrapping lines of text.

[email protected]

Minor Changes

• IconHash: Add component (#1543)

  EXAMPLE USAGE:

  <IconHash />

• Improve internal form field spacing (#1541)

  Refined the spacing between internal elements of form fields to align with the latest spacing guidelines.

  This change impacts the Stack spacing between label and description, the form field itself and the message slots.

• Autosuggest: Add suggestionHighlight prop (#1536)

  Introduces the suggestionHighlight prop, which uses the input value to automatically highlight either the matching or remaining portion of each suggestion.

  EXAMPLE USAGE:

  <Autosuggest suggestionHighlight="matching">

Patch Changes

• Refine the Checkbox, Radio, Toggle & MenuItemCheckbox size (#1541)

  Refines the size of the inline field elements including the RadioItem, Checkbox, Toggle and MenuItemCheckbox components.

  Primarily impacts consumers of the seekJobs theme, seeing a reduction across all sizes.

• Ensure no space above field with undefined label (#1541)

  Fixes an issue where passing undefined as the label to a form field would result in an unwanted space above the field.

• Badge: Ensure label follows correct tone (#1544)

  Ensure that the foreground text of a Badge always follows the correct tone for the background colour.
  Fixes a bug where using a Badge in a List that overrides the default tone would result in the Badge text following the List tone instead of the Badge tone.

• Fix warning in React 18.3.0 when using useToast. (#1534)

• MonthPicker: Reduce space between month and year fields (#1541)

  Reducing the space between month and year fields to improve correlation between the two fields within the greater context of a form.

[email protected]

Minor Changes

• Toggle: Add togglePosition prop (#1509)

  Introduces the togglePosition prop, enabling the toggle to either be leading or trailing its label text.

  EXAMPLE USAGE:

  <Toggle togglePosition="trailing" label="Label" />

• Toggle: Add bleedY prop (#1519)

  Introduces the bleedY prop, enabling vertical bleed for the Toggle component. This removes excess vertical space created by the Toggle input.

  EXAMPLE USAGE:

  <Toggle label="Label" bleedY />

  MIGRATION GUIDE:

  Vertical bleed will become standard for the Toggle component in a future version. Please use the bleedY prop with a value of true and update your layout accordingly.

• Tag: Introduce "addable" support (#1521)

  Tag actions have been extended to now support being “added”.
  A Tag will include a small add icon button when both an onAdd handler and addLabel prop are provided.

  EXAMPLE USAGE:

  <Tag onAdd={() => {...}} addLabel="Add Tag" />

• seekJobs: Use Tahoma for Thai fallback font (#1527)

  Currently in the seekJobs theme, the fallback font for the Thai character set resolves to the default system font which differs by operating system.
  By choosing a deterministic fallback that is available across operating systems, we can use Capsize to improve the alignment with the SEEK Sans web font, and reduce Cumulative Layout Shift for experiences that use Thai.

  Additionally, adding sans-serif as an ultimate fallback in the event that we ever fall all the way through the stack on an obscure operating system.

Patch Changes

• Tag: Add missing click event parameter to onClear prop type (#1516)

• Toggle: Improve label text vertical alignment at small size (#1518)

• Toggle: Remove tick icon & fix antialias haze when selected (#1525)

  Simplying the selected state design by removing the tick icon from the toggle thumb.

  Also fixes the antialias haze that appears around the thumb when selected.