@kaizen/components 1.46.0 → 1.47.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "1.46.0",
+  "version": "1.47.1",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",
@@ -70,7 +70,6 @@
     "react-select": "^5.8.0",
     "react-textfit": "^1.1.1",
     "resize-observer-polyfill": "^1.5.1",
-    "tslib": "^2.6.2",
     "use-debounce": "^10.0.0",
     "uuid": "^9.0.1",
     "@kaizen/hosted-assets": "2.0.3"
@@ -82,35 +81,28 @@
     "@babel/plugin-transform-react-pure-annotations": "^7.24.1",
     "@cultureamp/frontend-apis": "^9.5.0",
     "@cultureamp/i18n-react-intl": "^2.5.6",
-    "@rollup/plugin-alias": "^5.1.0",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-typescript": "^11.1.6",
     "@types/lodash.debounce": "^4.0.9",
     "@types/react-dom": "^18.3.0",
     "@types/react-textfit": "^1.1.4",
     "@types/uuid": "^9.0.8",
     "agadoo": "^3.0.0",
     "autoprefixer": "^10.4.19",
-    "babel-plugin-pure-static-props": "^0.2.0",
-    "concat-cli": "^4.0.0",
     "query-string": "^9.0.0",
     "react-intl": "^6.6.6",
     "rollup": "^4.17.2",
-    "rollup-plugin-dts": "^6.1.0",
-    "rollup-plugin-ignore": "^1.0.10",
-    "rollup-plugin-node-externals": "^7.1.2",
-    "rollup-plugin-postcss": "^4.0.2",
     "sass": "^1.76.0",
     "serialize-query-params": "^2.0.2",
     "svgo": "^3.2.0",
     "ts-jest": "^29.1.2",
-    "ts-node": "^10.9.2",
-    "ts-patch": "^3.1.2",
-    "typescript-transform-paths": "^3.4.7",
-    "@kaizen/tailwind": "1.2.6",
-    "@kaizen/design-tokens": "10.3.20"
+    "tslib": "^2.6.2",
+    "tsx": "^4.10.2",
+    "@kaizen/package-bundler": "1.0.0",
+    "@kaizen/design-tokens": "10.4.0"
+  },
+  "devDependenciesComments": {
+    "postcss": "Installed in root",
+    "postcss-cli": "Installed in root",
+    "postcss-preset-env": "Installed in root"
   },
   "peerDependencies": {
     "@cultureamp/i18n-react-intl": "^2.5.6",
@@ -118,19 +110,12 @@
     "react-intl": "^6.6.6"
   },
   "scripts": {
-    "build": "pnpm clean && pnpm prepublishOnly",
+    "build": "pnpm package-bundler build-shared-ui && pnpm build:global-styles",
+    "build:global-styles": "postcss ./styles/global.css --output dist/styles.css",
+    "clean": "rm -rf dist",
     "test": "FORCE_COLOR=1 jest",
     "test:ci": "pnpm test -- --ci",
     "test:treeshake": "agadoo ./dist/esm/index.mjs",
-    "clean": "rimraf dist",
-    "build:components": "rollup -c && pnpm build:types",
-    "build:styles": "postcss styles/global.css --output dist/global.css",
-    "build:types": "tspc --project tsconfig.types.json",
-    "compile": "tsc",
-    "dist:clean": "rm ./dist/global.css ./dist/raw-styles.css",
-    "dist:combine-styles": "concat-cli -f ./dist/*.css ./dist/esm/*.css -o ./dist/raw-styles.css",
-    "dist:postcss": "postcss dist/raw-styles.css --output dist/styles.css",
-    "postBuild": "pnpm dist:combine-styles && pnpm dist:postcss",
     "update-icons": "./src/Icon/bin/update-icons.sh",
     "i18n:extract": "pnpm i18n-extract"
   }

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

@@ -115,6 +115,20 @@ export const StickerSheetDefault: Story = {
         '#Breadcrumbs-focus-example [class^="TitleBlockZen-TitleBlockZen-module__breadcrumb"]',
       ],
     },
+    a11y: {
+      config: {
+        rules: [
+          {
+            id: "color-contrast", // false positive from animate in on the breadcrumbs
+            enabled: false,
+          },
+          {
+            id: "landmark-unique", // false positive from having multiple TitleBlocks on a page
+            enabled: false,
+          },
+        ],
+      },
+    },
   },
   render: args => (
     <StickerSheet>

package/src/Tooltip/_docs/Tooltip.mdx

@@ -61,3 +61,73 @@ Again, try to keep the contents of your children as simple as possible, ideally
 
 When your direct child is not semantic, you will get a console warning like this:
 `<Tooltip /> is not directly wrapping a semantic element, screen reader users will not be able to access the tooltip info.`
+
+
+### Tooltips, Kaizen components and avoiding common pitfalls
+
+While technically any Kaizen component can be wrapped by a `Tooltip`, as called out previously, only those with [accessible roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) like `button`, `link` or `heading`, will be readable to assistive technologies.
+
+We've created some guidance below with the most common cases for `Tooltip` and how to ensure the additional context is read to the user.
+
+#### Button and IconButton
+
+<Canvas of={TooltipStories.ButtonsWithTooltip} />
+
+While Kaizen buttons are compatible with `Tooltip`, caution is advised when using the custom `component` render prop.
+
+```JSX
+  <Tooltip text="Contact customer support.">
+    <Button
+      {...buttonProps}
+      component={() => (
+        // The most immediate child is a `div`, which has no `role`.
+        <div>
+          <button type="button">
+            Help
+          </button>
+        </div>
+      )}
+    />
+  </Tooltip>
+```
+
+In the example above, the `div` in now the direct descendant of `Tooltip`, therefore will no longer be accessible to assistive technologies.
+
+#### ButtonGroup
+
+The `Tooltip` component must wrap the children of `ButtonGroup` to be accessible to screen readers.
+
+<Canvas of={TooltipStories.ButtonGroupWithTooltip} />
+
+#### Table headers and tooltips
+
+While the composable `Tooltip` is not exposed in the Kaizen `Table`, it is important to call out that the `tooltipInfo` prop in `TableHeaderRowCell` must also have an `onClick` or `href` to be announced to assistive technologies.
+
+<Canvas of={TooltipStories.TableHeadersWithTooltips} />
+
+Without either of these, the `Tooltip` content will not be readable to keyboard users or assistive technologies.
+
+#### Tags
+
+Seen in the example below simple `Tag`s with plain text as `children` will not accessible to keyboard users or assistive technologies as it's direct descendant is a `div` with no semantic `role`.
+
+<Canvas of={TooltipStories.TagWithHoverOnlyTooltip}  />
+
+While `Tooltip` should be avoided if there are no interactive states within the `Tag`, internal elements like buttons or links can be wrapped in a `Tooltip` component to add necessary context.
+
+<Canvas of={TooltipStories.TagWithTooltip} />
+
+The [future Tag](?path=/docs/components-tag-future--docs#overview) offers a composable solution for those needing to add more context to an interactive `Tag`.
+
+#### Form components and tooltips
+
+While a `Tooltip` can seem like a natural pairing when space is a commodity, form elements still require a concise label that is _ideally_ visible (See MDN's guide on [Tooltip best practices](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role#best_practices)).
+
+<Canvas of={TooltipStories.CheckboxFieldTooltip} />
+
+In the example above, the `Tooltip` content `"Select all users"` is accessible to screen readers via keyboard navigation, however will not be announced when the input receives focus. This a limitation of `CheckboxField` and form components where the immediate `children` of `Tooltip` is a wrapper.
+
+<Canvas of={TooltipStories.CheckboxFieldWithDescriptionTooltip} />
+
+In these instances, `aria-describedby` can be leveraged to provide a description to the input.
+

package/src/Tooltip/_docs/Tooltip.stories.tsx

@@ -1,9 +1,18 @@
 import React from "react"
 import { Meta, StoryObj } from "@storybook/react"
-import { Button } from "~components/Button"
-import { InformationIcon } from "~components/Icon"
-import { Tag } from "~components/Tag"
+import { Button, IconButton } from "~components/Button"
+import { ButtonGroup } from "~components/ButtonGroup"
+import { CheckboxField } from "~components/Checkbox"
+import { FilterButtonBase } from "~components/Filter/FilterButton/subcomponents/FilterButtonBase"
+import { InformationIcon, RemoveLinkIcon, QuestionIcon } from "~components/Icon"
+import {
+  TableContainer,
+  TableHeader,
+  TableHeaderRowCell,
+  TableRow,
+} from "~components/Table"
 import { Text } from "~components/Text"
+import { Tag } from "~components/__future__"
 import { Tooltip } from "../index"
 
 const meta = {
@@ -12,6 +21,16 @@ const meta = {
   args: {
     text: "Example tooltip text.",
   },
+  decorators: [
+    Story => (
+      <div className="flex mt-[60px] gap-12">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: "centered",
+  },
 } satisfies Meta<typeof Tooltip>
 
 export default meta
@@ -31,19 +50,6 @@ export const Playground: Story = {
       <Button label="Hover or focus me" />
     </Tooltip>
   ),
-  decorators: [
-    Story => (
-      <div
-        style={{
-          marginTop: "100px",
-          display: "flex",
-          justifyContent: "center",
-        }}
-      >
-        <Story />
-      </div>
-    ),
-  ],
 }
 
 export const OverflowScroll: Story = {
@@ -143,3 +149,160 @@ export const OverflowScroll: Story = {
     </>
   ),
 }
+
+export const ButtonsWithTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: args => (
+    <>
+      <Tooltip {...args} text="Contact customer support.">
+        <Button label="Help" icon={<QuestionIcon role="presentation" />} />
+      </Tooltip>
+      <Tooltip {...args} text="Remove the link from current selection.">
+        <IconButton
+          label="Remove link"
+          icon={<RemoveLinkIcon role="presentation" />}
+        />
+      </Tooltip>
+    </>
+  ),
+}
+
+export const ButtonGroupWithTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: args => (
+    <>
+      <ButtonGroup>
+        <Tooltip {...args} text="Sort by first">
+          <FilterButtonBase>First</FilterButtonBase>
+        </Tooltip>
+        <Tooltip {...args} text="Sort by last">
+          <FilterButtonBase>Last</FilterButtonBase>
+        </Tooltip>
+      </ButtonGroup>
+    </>
+  ),
+}
+
+export const TableHeadersWithTooltips: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <>
+      <TableContainer>
+        <TableHeader>
+          <TableRow>
+            <TableHeaderRowCell
+              labelText="Resources"
+              sorting="descending"
+              width={3 / 12}
+              onClick={(): void => undefined}
+              tooltipInfo="Sort Resources by descending"
+            />
+            <TableHeaderRowCell
+              labelText="Supplementary"
+              width={3 / 12}
+              onClick={(): void => undefined}
+              sorting="ascending"
+              tooltipInfo="Sort Supplementary by ascending"
+            />
+            <TableHeaderRowCell labelText="Date" width={3 / 12} />
+            <TableHeaderRowCell labelText="Price" width={3 / 12} />
+          </TableRow>
+        </TableHeader>
+      </TableContainer>
+    </>
+  ),
+}
+
+export const TagWithHoverOnlyTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <Tooltip text="John Jonson Johnington the Third">
+      <Tag>John Jonson Jo...</Tag>
+    </Tooltip>
+  ),
+}
+
+export const TagWithTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <Tag>
+      <Tooltip text="Visit John Jonson's profile">
+        <a className="text-inherit font no-underline" href="#John">
+          John Jonson
+        </a>
+      </Tooltip>
+    </Tag>
+  ),
+}
+
+export const TagWithCheckboxField: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <>
+      <Tooltip text="Select all users">
+        <CheckboxField labelText="Users" id="sb-checkbox-tooltip--id" />
+      </Tooltip>
+    </>
+  ),
+}
+
+export const CheckboxFieldTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <>
+      <Tooltip text="Select all users">
+        <CheckboxField labelText="Users" id="sb-checkbox-tooltip--id" />
+      </Tooltip>
+    </>
+  ),
+}
+
+export const CheckboxFieldWithDescriptionTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <>
+      <Tooltip text="Select all users">
+        <CheckboxField
+          labelText="Users"
+          id="sb-checkbox-tooltip--id"
+          aria-describedby="sb-checkbox-description--id"
+        />
+        <span id="sb-checkbox-description--id" className="sr-only">
+          Select all users
+        </span>
+      </Tooltip>
+    </>
+  ),
+}