@kaizen/components 1.42.5 → 1.42.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "1.42.5",
+  "version": "1.42.6",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",

package/src/Tag/_docs/Tag.mdx

@@ -1,4 +1,5 @@
 import { Canvas, Controls , Meta } from "@storybook/blocks"
+import { InlineNotification } from "~components/Notification"
 import { ResourceLinks, KAIOInstallation } from "~storybook/components"
 import * as TagStories from "./Tag.stories"
 
@@ -13,6 +14,12 @@ import * as TagStories from "./Tag.stories"
   className="!mb-8"
 />
 
+
+<InlineNotification type="cautionary" persistent>
+  {`This version of the Tag will soon be deprecated and will be removed in the next major release.
+  Import Tag from "@kaizen/components/future" for the latest version and veiw our migration guide in the Future folder` }
+</InlineNotification>
+
 <KAIOInstallation exportNames="Tag" />
 
 ## Overview
@@ -59,7 +66,7 @@ An Avatar can be added in two ways, either by importing the `<Avatar />` compone
 <Canvas of={TagStories.ProfileWithAvatarProps} />
 
 ### Dismissable
-<Canvas of={TagStories.Dismissable} />
+<Canvas of={TagStories.Dismissible} />
 
 ### TruncateWidth
 A pixel width which sets a limit for when the text starts to truncate.

package/src/Tag/_docs/Tag.stories.tsx

@@ -137,7 +137,7 @@ export const ProfileWithAvatarProps: Story = {
   },
 }
 
-export const Dismissable: Story = {
+export const Dismissible: Story = {
   args: {
     dismissible: true,
     onDismiss: () => alert("Dismissed"),

package/src/TitleBlockZen/TitleBlockZen.module.scss

@@ -550,6 +550,25 @@ $tab-container-height-medium-and-small-collapsed: 0;
     text-decoration: underline;
   }
 
+  &:focus {
+    outline: none;
+
+    &::after {
+      $focus-ring-offset: calc(
+        (-2 * #{$border-focus-ring-border-width}) - #{$border-focus-ring-border-width}
+      );
+
+      content: "";
+      position: absolute;
+      background: transparent;
+      border-color: $color-blue-200;
+      border-radius: 50%;
+      border-width: $border-focus-ring-border-width;
+      border-style: $border-focus-ring-border-style;
+      inset: $focus-ring-offset;
+    }
+  }
+
   @media only screen and (max-width: $breadcrumb-breakpoint-width) {
     position: relative;
 

package/src/TitleBlockZen/_docs/TitleBlockZen.stories.tsx

@@ -2,6 +2,7 @@ import React from "react"
 import { Meta, StoryObj } from "@storybook/react"
 import { assetUrl } from "@kaizen/hosted-assets"
 import { AddIcon, StarOnIcon } from "~components/Icon"
+import { StickerSheet } from "~storybook/components/StickerSheet"
 import { NavigationTab, TitleBlockZen } from "../index"
 
 const SECONDARY_ACTIONS = [
@@ -97,76 +98,38 @@ export const Playground: Story = {
   },
 }
 
-// export const WithBadge: Story = {
-//   render: args => {
-//     const [badgeCount, setBadgeCount] = React.useState(1)
-//     return (
-//       <TitleBlockZen
-//         {...args}
-//         primaryAction={{
-//           label: "Click Me",
-//           icon: <ArrowForwardIcon role="presentation" />,
-//           iconPosition: "end",
-//           href: "#",
-//           onClick: () => setBadgeCount(b => b + 1),
-//           badge: {
-//             text: String(badgeCount),
-//             animateChange: true,
-//           },
-//         }}
-//         defaultAction={{
-//           label: "Default link",
-//           onClick: () => setBadgeCount(b => b + 1),
-//           href: "#",
-//         }}
-//       />
-//     )
-//   },
-// }
-
-// export const WithAvatarProps: Story = {
-//   args: {
-//     avatar: {
-//       avatarSrc: assetUrl("site/empty-state.png"),
-//       fullName: "Blanca Wheeler",
-//     },
-//   },
-// }
-
-// export const WithDefaultTag: Story = {
-//   args: {
-//     surveyStatus: { text: "Due July 8, 2030", status: "default" },
-//   },
-// }
-
-// export const WithMenuButton: Story = {
-//   args: {
-//     primaryAction: {
-//       label: "Menu button",
-//       menuItems: [
-//         {
-//           action: "#",
-//           label: "Item 1",
-//         },
-//         {
-//           action: () => alert("Item 2 clicked"),
-//           label: "Item 2",
-//         },
-//         {
-//           action: "#",
-//           label: "Item 3",
-//         },
-//       ],
-//     },
-//   },
-// }
-
-// export const Subtitle: Story = {
-//   args: {
-//     subtitle: (
-//       <Text variant="body">
-//         This is a <a href="/">link</a>
-//       </Text>
-//     ),
-//   },
-// }
+export const StickerSheetDefault: Story = {
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: "shown",
+      },
+    },
+    pseudo: {
+      hover: [
+        '#tab-hover-example [class^="TitleBlockZen-TitleBlockZen-module__navigationTabsList"] li:nth-child(2) a',
+        '#Breadcrumbs-hover-example [class^="TitleBlockZen-TitleBlockZen-module__breadcrumb"]',
+      ],
+      focus: [
+        '#tab-focus-example [class^="TitleBlockZen-TitleBlockZen-module__navigationTabsList"] li:nth-child(2) a',
+        '#Breadcrumbs-focus-example [class^="TitleBlockZen-TitleBlockZen-module__breadcrumb"]',
+      ],
+    },
+  },
+  render: args => (
+    <StickerSheet>
+      <StickerSheet.Row rowTitle="Tab hover">
+        <TitleBlockZen {...args} id="tab-hover-example" />
+      </StickerSheet.Row>
+      <StickerSheet.Row rowTitle="Tab focus">
+        <TitleBlockZen {...args} id="tab-focus-example" />
+      </StickerSheet.Row>
+      <StickerSheet.Row rowTitle="Breadcrumbs hover">
+        <TitleBlockZen {...args} id="Breadcrumbs-hover-example" />
+      </StickerSheet.Row>
+      <StickerSheet.Row rowTitle="Breadcrumbs focus">
+        <TitleBlockZen {...args} id="Breadcrumbs-focus-example" />
+      </StickerSheet.Row>
+    </StickerSheet>
+  ),
+}

package/src/TitleBlockZen/subcomponents/NavigationTabs.module.scss

@@ -59,13 +59,16 @@
     margin: 0;
   }
 
-  &.active {
+  $active-tab-marker-height: 5px;
+
+  &.active,
+  &:focus {
     color: $color-white;
 
     &::before {
       content: "";
       display: block;
-      height: 5px;
+      height: $active-tab-marker-height;
       position: absolute;
       top: 0;
       left: 0;
@@ -82,6 +85,34 @@
       }
     }
   }
+
+  &:focus {
+    outline: none;
+
+    &::before {
+      background-color: $color-blue-200;
+    }
+
+    &::after {
+      $focus-ring-offset: calc((-1 * #{$border-focus-ring-border-width}));
+
+      content: "";
+      position: absolute;
+      background: transparent;
+      border-color: $color-blue-200;
+      border-radius: 0 0 $border-focus-ring-border-radius
+        $border-focus-ring-border-radius;
+      border-width: $border-focus-ring-border-width;
+      border-style: $border-focus-ring-border-style;
+      inset: 0 $focus-ring-offset $active-tab-marker-height $focus-ring-offset;
+
+      @include title-block-medium-and-small {
+        border-radius: $border-focus-ring-border-radius
+          $border-focus-ring-border-radius 0 0;
+        inset: $active-tab-marker-height $focus-ring-offset 0 $focus-ring-offset;
+      }
+    }
+  }
 }
 
 .linkAnchor.lightBackground {

package/src/__future__/Tag/Tag/_docs/Tag-migration-guide.mdx

@@ -0,0 +1,172 @@
+import { Canvas, Meta } from "@storybook/blocks"
+import * as LegacyTagStories from "../../../../Tag/_docs/Tag.stories"
+import * as TagMigrationStories from "./Tag-migration-guide.stories"
+
+<Meta of={TagMigrationStories} />
+
+# Future Tag migration guide
+
+A brief guide on how and why to migrate from Kaizen's current `Tag` to the `future` release.
+
+## Why the change?
+
+Tag was rebuilt to allow for greater composability as the number of cases for a distinct Tags could not be solved through the use of `variant` without impacting the developer experience for existing users. The flexibility of `Tag` content as `children` also addresses several accessibility issues that the original could not solve intuitively.
+
+## Component and API changes at a glance
+
+There were a number key changes between current and future `Tag` to achieve the flexibility we were aiming to provide, we've listed these below but also go into further detail in the [migration examples](/docs/components-tag-future-migration-guide--migrationguide#migration-examples).
+
+- `variant` prop has been removed
+  - This has been superseded by a combination of the `color` and `icon` prop
+- `inline` prop and the default `margin` on all Tags has been removed.
+  - This can be directly controlled through `classNameOverride` or a `flex-gap` on the container.
+- `size` has been removed and all tags are the same size.
+- `truncationWidth` has been removed as child content.
+- `dismissible` prop has been removed.
+  - A `DismissibleTag` component is now available in its place.
+- `Avatar` and all child content must now be composed by the consumer.
+  - This offers a greater degree of flexibility to ensure that the right accessible context can be provided to the end user.
+
+
+## Migration examples
+
+The following are example of migrating from previously available props to the composable solution.
+
+### Status
+
+With the `variant` prop there are four values associated with statuses:  `statusLive`, `statusDraft`, `statusClosed`, `statusAction`.
+
+For the most part these can all be replaced with the use of the `color` prop, with exception to the `live` status.
+
+#### Before
+
+<Canvas of={LegacyTagStories.Status} />
+
+
+#### After
+
+<Canvas of={TagMigrationStories.StatusMigration} sourceState="shown"/>
+
+While the `LiveIcon` is exported from `@kaizen/components` the current `Tag` uses an animated implementation, which is not exported directly from Kaizen. As an interim solution, you can use the following Story's code snippet to create a `LiveIconComponent`. This can then be passed into the future `Tag` as `Children`.
+
+<Canvas of={TagMigrationStories.LiveIconComponentStory} sourceState="hidden"/>
+
+### Validation
+
+Following the same pattern as status, `validationPositive`, `validationInformative`, `validationNegative`, `validationCautionary` can all be replace with the `color` and `icon` prop.
+
+Note: because the icons convey meaning, they should have an accessible label that provides context to the `Tag`. A contextual `aria-label` and role of `img` addresses one of the [accessibility issues](https://github.com/cultureamp/kaizen-discourse/issues/102) with the current `Tag`.
+
+#### Before
+
+<Canvas of={LegacyTagStories.Validation} />
+
+#### After
+
+<Canvas of={TagMigrationStories.ValidationMigration} sourceState="shown"/>
+
+
+Note: When using the `icon` prop, the icon's color will be determined by the `color` value that has been set. This is to ensure that an accessible contrast ratio is achieved.
+
+Any Icons added as a child of future `Tag` will need to set their own colors and ensure the right contrast ratio is achieved.
+
+### Sentiment
+
+While migration of any `Tag` using, `sentimentPositive`, `sentimentNeutral` or `sentimentNegative` is relatively straight forward using the `color` prop, `sentimentNone` does not align to any Kaizen's [semantic colors](https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3064857902/Color).
+
+#### Before
+
+<Canvas of={LegacyTagStories.Sentiments} />
+
+#### After
+
+<Canvas of={TagMigrationStories.SentimentsMigration} sourceState="shown"/>
+
+If required, you could use `classNameOverride` to implement the same UI. It is important that any override of the default styles still meets minimum contrast ratios to ensure the component is accessible.
+
+<Canvas of={TagMigrationStories.SentimentNone} />
+
+This is also a good time to stop and check if this change is necessary. If there is an opportunity remove older styles that are no longer available, this can help to reduce inconsistencies across the platform. As always, check in with your designer to see if any new option can be used in its place.
+
+
+### Dismissible
+
+The `dismissible` prop is no longer available in the future `Tag` component. We have split the dismissible functionality into the [RemovableTag](/docs/components-tag-future-removabletag--docs).
+
+This increases the hit box for the dismiss button and makes the `ariaLabel` in the `removeButtonProps` a required prop. This offers a more accessible experience for user and address one of the standing [accessibility issues](https://github.com/cultureamp/kaizen-discourse/issues/101) with the legacy `Tag`.
+
+#### Before
+
+<Canvas of={LegacyTagStories.Dismissible} />
+
+#### After
+
+<Canvas of={TagMigrationStories.DismissibleMigration} sourceState="shown"/>
+
+Remember that when handling dismiss (or any destructive action), a user's focus should not be lost on the page.
+
+
+### Avatars
+
+Avatars are no longer provided directly to the `Tag` as a prop. Instead they will be passed in as children.
+
+#### Before
+
+<Canvas of={LegacyTagStories.ProfileWithAvatarProps} />
+
+#### After
+
+<Canvas of={TagMigrationStories.AvatarMigration} sourceState="shown"/>
+
+
+Note: The use of `ps-4` (or `padding-inline-start`) in the `classNameOverride` is to override the default spacing at start of the `Tag`. This will ensure the Avatar can contour the border radius of the `Tag`.
+
+#### Dismissible Avatars
+
+Following a similar pattern to the above, you can use the `RemovableTag` with an `Avatar` and plain text as its `children` to achieve a dismissible version.
+
+<Canvas of={TagMigrationStories.AvatarRemovableMigration} />
+
+### Inline
+
+Originally the `Tag` was built with the assumption that it would always required spacing at the end. This necessitated the need for the `inline` prop to remove the margin from end when it was not required.
+
+In future `Tag` this has been removed so consumers can now control spacing with CSS properties like `gap` or `margin-inline`.
+
+#### Before
+
+<Canvas of={LegacyTagStories.Inline} />
+
+#### After
+
+<Canvas of={TagMigrationStories.InlineMigration} sourceState="shown"/>
+
+To simplify this example we have avoided DOM elements such as `ul` and `li`. In production, lists should be used if you are rendering a group of `Tag`s.
+
+
+### truncationWidth
+
+While the current Tag controls truncation via the `truncationWidth` prop, which set a `max-width` of inner text via inline styles, we have chosen not to adopt this in the future `Tag` as it presents a risk of violating accessibility standards. While truncation can still be achieved in future `Tag` via Tailwind or DOM manipulation, it is important to call out out this as a accessibility concern.
+
+#### Before
+
+<Canvas of={LegacyTagStories.Truncate} />
+
+Where truncation often fails WCAG's success criteria is in [1.4.4](https://www.w3.org/WAI/WCAG21/Techniques/failures/F69) or [1.3.1](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html). The crux of the issue is that removing content with an ellipsis may lead to a loss of context for visual users. While `aria` labels can support those that use assistive technologies, they are not enough to resolve this issue for sighted users.
+
+The recommendation from WCAG is that any truncated content comes with the functionality to visually revealing its full content. This can be accessible either via focus or some form of activation - like an `onClick` to reveal. Based on this, our recommendation is to avoid truncation unless necessary.
+
+### Size
+
+The two sizes for tag have been remove in favour of a default size in between `medium` and `small`. The `small` specifically was removed due to the reduced hit radius for the dismissible button and poor compatibility with avatars and icon.
+
+`classNameOverride` can be leveraged to add padding and modify properties but should be done with caution to reduce inconsistencies in the platform and reduce the risk of accessibility violations.
+
+
+#### Before
+
+<Canvas of={LegacyTagStories.Sizes} />
+
+#### After
+
+<Canvas of={TagMigrationStories.SizesMigration} sourceState="shown"/>