@kaizen/components 3.3.15 → 3.3.16

package/dist/types/TitleBlock/types.d.ts

@@ -16,6 +16,11 @@ import { type NavigationTabProps } from './subcomponents/NavigationTabs';
 export type TitleBlockProps = {
     children?: React.ReactNode;
     title: string;
+    /**
+     * `light` is the recommended variant for new implementations. Leaving `variant`
+     * unset falls back to the default purple background.
+     *
+     */
     variant?: TitleBlockVariant;
     breadcrumb?: TitleBlockBreadcrumbType;
     avatar?: JSX.Element | TitleBlockAvatarProps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "3.3.15",
+  "version": "3.3.16",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",
@@ -103,7 +103,7 @@
     "lodash.debounce": "^4.0.8",
     "nanobus": "^4.5.0",
     "prosemirror-commands": "^1.7.2",
-    "prosemirror-history": "^1.5.0",
+    "prosemirror-history": "^1.5.1",
     "prosemirror-inputrules": "^1.5.1",
     "prosemirror-keymap": "^1.2.3",
     "prosemirror-model": "^1.25.12",
@@ -130,7 +130,7 @@
   },
   "devDependencies": {
     "@cultureamp/frontend-apis": "13.3.0",
-    "@cultureamp/i18n-react-intl": "^4.6.5",
+    "@cultureamp/i18n-react-intl": "^4.6.6",
     "@cultureamp/package-bundler": "^4.1.1",
     "@svgr/rollup": "^8.1.0",
     "@testing-library/dom": "^10.4.2",
@@ -149,21 +149,21 @@
     "postcss": "^8.5.28",
     "postcss-cli": "^11.0.1",
     "postcss-import": "^16.2.0",
-    "postcss-preset-env": "^11.5.4",
+    "postcss-preset-env": "^11.6.0",
     "postcss-scss": "^4.0.9",
     "query-string": "^9.5.1",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "react-highlight": "^0.15.0",
     "react-intl": "^10.2.2",
-    "rollup": "^4.63.5",
+    "rollup": "^4.64.0",
     "sass": "1.79.6",
     "serialize-query-params": "^2.0.4",
     "svgo": "^4.1.0",
     "ts-patch": "^3.3.0",
     "tslib": "^2.8.1",
     "tsx": "^4.23.15",
-    "@kaizen/design-tokens": "11.0.19"
+    "@kaizen/design-tokens": "11.0.20"
   },
   "devDependenciesComments": {
     "sass": "Prevent deprecation warnings introduced in 1.80 as we plan to move away from sass",

package/src/TitleBlock/_docs/TitleBlock--api-specification.mdx

@@ -17,14 +17,15 @@ import * as TitleBlockStories from './TitleBlock.stories'
 
 `TitleBlock` A consistent pattern to allow users to navigate and complete tasks easily.
 
-<Canvas of={TitleBlockStories.Playground} />
+<Canvas of={TitleBlockStories.LightVariant} />
 
 ## Props
 
 <Controls
-  of={TitleBlockStories.Playground}
+  of={TitleBlockStories.LightVariant}
   include={[
     'avatar',
+    //TODO: note as depreication per https://cultureamp.atlassian.net/browse/KZN-4538
     'breadcrumb',
     'defaultAction',
     'handleHamburgerClick',
@@ -32,13 +33,30 @@ import * as TitleBlockStories from './TitleBlock.stories'
     'primaryAction',
     'secondaryActions',
     'secondaryOverflowMenuItems',
+    'sticky',
     'surveyStatus',
     'title',
+    'variant',
   ]}
 />
 
 ## Options
 
+### variant
+
+```
+variant?: 'light' | 'admin' | 'education'
+```
+
+Controls the TitleBlock's background and text colour. `light`
+is the recommended value. Without passing it, the UI renders as the default
+purple variant. See
+[Usage Guidelines](/docs/components-titleblock-usage-guidelines--docs)
+for the full guidance.
+
+If you're rendering `NavigationTab`s alongside the TitleBlock, set the same
+`variant` on each tab. Tabs don't inherit from the TitleBlock.
+
 ### primaryAction
 
 The primary action (the "main" button in the top right) can either be a Button,
@@ -66,6 +84,18 @@ If you want it to be a Menu, pass in this object of type `MenuGroup`:
 Using the `label`, the Title Block will render a Button with a chevron icon and your `menuItems` will appear
 in the dropdown menu when you click it. (`MenuItemProps` is a type imported from the `Menu` component.)
 
+### defaultAction
+
+```
+type DefaultActionProps = TitleBlockButtonProps | TitleBlockCustomButtonProps
+```
+
+Renders a Button immediately to the left of `primaryAction`, in the same top
+row. Pass the Button's props as an object, same as `primaryAction`.
+
+Unlike `primaryAction`, `defaultAction` **can't be a menu group** There's no
+dropdown variant of the default action, so passing `menuItems` is invalid. It can take a `badge`, but the badge only renders on the full-width button: at tablet and ≤360px widths the default action collapses into a menu item and the badge isn't shown.
+
 ### secondaryActions & secondaryOverflowMenuItems
 
 Secondary Actions sit below the Primary Actions, and consist of

package/src/TitleBlock/_docs/TitleBlock--usage-guidelines.mdx

@@ -1,5 +1,6 @@
-import { Canvas, DocsStory, Meta, Controls } from '@storybook/blocks'
-import { ResourceLinks, KAIOInstallation, DosAndDonts, DoOrDont } from '~storybook/components'
+import { Canvas, DocsStory, Meta, Controls, Unstyled } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation } from '~storybook/components'
+import { InlineNotification } from '~components/Notification'
 import * as TitleBlockStories from './TitleBlock.stories'
 
 <Meta title="Components/TitleBlock/Usage Guidelines" />
@@ -18,31 +19,106 @@ import * as TitleBlockStories from './TitleBlock.stories'
 
 A consistent pattern to allow users to navigate and complete tasks easily.
 
-<Canvas of={TitleBlockStories.Playground} />
+<Canvas of={TitleBlockStories.LightVariant} sourceState="hidden" />
 
 <Controls
-  of={TitleBlockStories.Playground}
-  include={['avatar', 'defaultAction', 'navigationTabs', 'primaryAction', 'title']}
+  of={TitleBlockStories.LightVariant}
+  include={[
+    'avatar',
+    'defaultAction',
+    'navigationTabs',
+    'primaryAction',
+    'sticky',
+    'title',
+    'variant',
+  ]}
 />
 
-## Examples
+## Variants
+
+<Unstyled>
+  <InlineNotification persistent variant="cautionary">
+    {
+      <>
+        <strong>
+          Passing <code>variant="light"</code> is the ongoing recommendation.
+        </strong>{' '}
+        When a variant isn't passed, TitleBlock falls back to the default purple variant.
+      </>
+    }
+  </InlineNotification>
+</Unstyled>
+
+### Light (recommended)
+
+<Canvas of={TitleBlockStories.LightVariant} sourceState="hidden" />
+
+**If you're using navigation tabs, set `variant="light"` on each
+`NavigationTab`** Tabs don't inherit the variant from the TitleBlock. set
+it in both places, or the tabs keep their purple background.
+
+```tsx
+<TitleBlock
+  variant="light"
+  title="Page title"
+  navigationTabs={[
+    <NavigationTab key="1" variant="light" text="Label" href="#" active />,
+    <NavigationTab key="2" variant="light" text="Label" href="#" />,
+  ]}
+/>
+```
 
-### Viewports
+### Default (purple)
 
-<Canvas of={TitleBlockStories.Viewports} />
+Shown for recognition only. Don't reach for this on new surfaces.
 
-### Long titles
+<Canvas of={TitleBlockStories.Playground} sourceState="hidden" />
+
+## Sticky behavior
+
+Setting `sticky` pins the TitleBlock's top strip to the top of its scroll
+container as the page scrolls, instead of letting it scroll away. Full
+mechanism, structure, and code for reserving space above the strip (for
+example, a banner) are covered in the
+[Sticky Banner guide](/docs/components-titleblock-sticky-banner--docs).
+
+**If your surface is adding Coach, turn `sticky` on.** A pinned top strip is a
+requirement when the header carries a Coach button.
+
+### Coach button placement
 
-<Canvas of={TitleBlockStories.HasLongTitle} />
+For teams adding Coach to a surface that already has a primary Call to action CTA:
 
-### Light Variant
+- **Coach is the primary action.** Pass it as `primaryAction`.
+- **Demote the existing primary CTA to `defaultAction`.** This is the slot
+  that renders immediately to the left of `primaryAction`, in the same top
+  row. Don't use `secondaryActions` or `secondaryOverflowMenuItems` for this.
+  Those render in a separate row below, alongside the navigation tabs, not
+  next to the primary and default actions.
+
+  TitleBlock predates current naming conventions, so `defaultAction` is
+  its term for what a modern component would call a secondary action: a
+  non-primary button rendered next to the primary one.
+
+- **Coach sits furthest right**, closest to the side panel. TitleBlock is
+  props-based and its action slots aren't reorderable, so passing Coach as
+  `primaryAction` gives you this placement automatically.
+
+## Examples
+
+### Long titles
 
-<Canvas of={TitleBlockStories.LightVariant} />
+<Canvas of={TitleBlockStories.HasLongTitleLightVariant} sourceState="hidden" />
 
-### Admin Variant
+### Default action limitations
 
-<Canvas of={TitleBlockStories.AdminVariant} />
+`primaryAction` and `defaultAction` both render in the top row, but they don't
+accept the same props:
 
-### Education Variant
+- **`defaultAction` accepts a `badge`.** Pass `badge: { text: '3' }` alongside
+  the label. It reaches the underlying button, so you also get its optional
+  `variant` and `reversed` fields.
+- **`defaultAction` can't be a dropdown.** Only `primaryAction` accepts a menu
+  group (`{ label, menuItems }`) and renders a button that opens a menu.
 
-<Canvas of={TitleBlockStories.EducationVariant} />
+<Canvas of={TitleBlockStories.WithDefaultActionBadge} sourceState="hidden" />

package/src/TitleBlock/_docs/TitleBlock.stories.tsx

@@ -30,6 +30,15 @@ const SECONDARY_ACTIONS = [
   },
 ]
 
+const LIGHT_NAVIGATION_TABS = [
+  <NavigationTab key="1" variant="light" text="Label" href="#" active />,
+  <NavigationTab key="2" variant="light" text="Label" href="#" />,
+  <NavigationTab key="3" variant="light" text="Label" href="#" />,
+  <NavigationTab key="4" variant="light" text="Label" href="#" />,
+  <NavigationTab key="5" variant="light" text="Label" href="#" />,
+  <NavigationTab key="6" variant="light" text="Label" href="#" />,
+]
+
 const viewports = {
   viewports: {
     default: {
@@ -181,12 +190,6 @@ export const Playground: Story = {
   },
 }
 
-export const Viewports: Story = {
-  parameters: {
-    viewport: viewports,
-    chromatic: chromaticViewports,
-  },
-}
 export const WithTabNavigation: Story = {
   parameters: {
     viewport: viewports,
@@ -222,6 +225,18 @@ export const HasLongTitle: Story = {
   args: { title: 'A long title with over thirty characters' },
 }
 
+export const HasLongTitleLightVariant: Story = {
+  parameters: {
+    viewport: viewports,
+    chromatic: { disable: true },
+  },
+  args: {
+    variant: 'light',
+    title: 'A long title with over thirty characters',
+    navigationTabs: LIGHT_NAVIGATION_TABS,
+  },
+}
+
 export const LightVariant: Story = {
   parameters: {
     docs: {
@@ -235,14 +250,7 @@ export const LightVariant: Story = {
   args: {
     variant: 'light',
     title: 'Light TitleBlock',
-    navigationTabs: [
-      <NavigationTab key="1" variant="light" text="Label" href="#" active />,
-      <NavigationTab key="2" variant="light" text="Label" href="#" />,
-      <NavigationTab key="3" variant="light" text="Label" href="#" />,
-      <NavigationTab key="4" variant="light" text="Label" href="#" />,
-      <NavigationTab key="5" variant="light" text="Label" href="#" />,
-      <NavigationTab key="6" variant="light" text="Label" href="#" />,
-    ],
+    navigationTabs: LIGHT_NAVIGATION_TABS,
   },
 }
 
@@ -725,6 +733,34 @@ export const WithOnlySecondaryActions: Story = {
   },
 }
 
+export const WithDefaultActionBadge: Story = {
+  parameters: {
+    viewport: viewports,
+    chromatic: { disable: true },
+  },
+  args: {
+    variant: 'light',
+    title: 'Goals',
+    surveyStatus: undefined,
+    avatar: undefined,
+    breadcrumb: undefined,
+    secondaryActions: undefined,
+    secondaryOverflowMenuItems: undefined,
+    // Badge is supported: it passes through to the underlying button.
+    defaultAction: {
+      label: 'View drafts',
+      href: '#',
+      badge: { text: '3' },
+    },
+    // Only the primary action can be a menu group (label + menuItems).
+    primaryAction: {
+      label: 'Create goal',
+      menuItems: [{ label: 'Create a single goal' }, { label: 'Bulk create goals' }],
+    },
+    navigationTabs: LIGHT_NAVIGATION_TABS,
+  },
+}
+
 export const StickyTopStripInScrollableContainer: Story = {
   name: 'Sticker Sheet (Sticky Top Strip In Scrollable Container)',
   parameters: {

package/src/TitleBlock/types.ts

@@ -17,6 +17,11 @@ import { type NavigationTabProps } from './subcomponents/NavigationTabs'
 export type TitleBlockProps = {
   children?: React.ReactNode
   title: string
+  /**
+   * `light` is the recommended variant for new implementations. Leaving `variant`
+   * unset falls back to the default purple background.
+   *
+   */
   variant?: TitleBlockVariant
   breadcrumb?: TitleBlockBreadcrumbType
   avatar?: JSX.Element | TitleBlockAvatarProps