@kaizen/components 3.1.6 → 3.3.0

package/src/SingleSelect/SingleSelect.tsx

@@ -1,7 +1,7 @@
 import React, { useEffect, useId, useState } from 'react'
-import { type UseFloatingReturn } from '@floating-ui/react-dom'
 import { useButton } from '@react-aria/button'
 import { HiddenSelect, useSelect } from '@react-aria/select'
+import { mergeRefs } from '@react-aria/utils'
 import { useSelectState, type SelectProps as AriaSelectProps } from '@react-stately/select'
 import { type Key } from '@react-types/shared'
 import classnames from 'classnames'
@@ -32,6 +32,7 @@ export type SingleSelectProps<Option extends SingleSelectOption = SingleSelectOp
    */
   items: SingleSelectItem<Option>[]
   id?: string
+  inputRef?: React.Ref<HTMLButtonElement>
   /**
    * Optional render function that allows custom rendering of the trigger button.
    * The function receives the `selectToggleProps` and a `ref` to be applied
@@ -39,7 +40,7 @@ export type SingleSelectProps<Option extends SingleSelectOption = SingleSelectOp
    */
   trigger?: (
     selectToggleProps: SelectToggleProps & {
-      ref: UseFloatingReturn<HTMLButtonElement>['refs']['setReference']
+      ref: React.Ref<HTMLButtonElement>
     },
   ) => JSX.Element
   /**
@@ -95,6 +96,7 @@ export const SingleSelect = <Option extends SingleSelectOption = SingleSelectOpt
   isDisabled,
   onSelectionChange,
   portalContainerId,
+  inputRef,
   ...restProps
 }: SingleSelectProps<Option>): JSX.Element => {
   const { refs } = useFloating<HTMLButtonElement>()
@@ -153,7 +155,7 @@ export const SingleSelect = <Option extends SingleSelectOption = SingleSelectOpt
     status,
     'isDisabled': triggerProps.isDisabled,
     isReversed,
-    'ref': refs.setReference,
+    'ref': mergeRefs(inputRef, refs.setReference),
     'aria-describedby': classnames(validationMessage && validationId, description && descriptionId),
     'aria-required': isRequired,
   }

package/src/Tabs/_docs/Tabs.spec.stories.tsx

@@ -117,6 +117,45 @@ export const ArrowsShowingAndHidingRTL: Story = {
   },
 }
 
+let scrollIntoViewCalls = 0
+const originalScrollIntoView = HTMLElement.prototype.scrollIntoView
+
+/**
+ * The selected tab must NOT be scrolled into view on mount (KZN-3363) — only when
+ * the selection changes via user interaction. This protects users who render Tabs
+ * below the fold from having the page jump on load.
+ */
+export const ScrollsIntoViewOnSelectionOnly: Story = {
+  name: 'Scrolls into view on selection only',
+  beforeEach: () => {
+    scrollIntoViewCalls = 0
+    HTMLElement.prototype.scrollIntoView = function (): void {
+      scrollIntoViewCalls += 1
+    }
+    return () => {
+      HTMLElement.prototype.scrollIntoView = originalScrollIntoView
+    }
+  },
+  render: (args) => (
+    <div style={{ maxWidth: '500px' }}>
+      <Tabs defaultSelectedKey="one" {...args} />
+    </div>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement.parentElement!)
+
+    await step('No scroll into view on mount', async () => {
+      expect(scrollIntoViewCalls).toBe(0)
+    })
+
+    await step('Scrolls into view when a tab is selected', async () => {
+      const tabFour = await canvas.findByRole('tab', { name: 'Tab 4' })
+      await userEvent.click(tabFour)
+      await waitFor(() => expect(scrollIntoViewCalls).toBeGreaterThan(0))
+    })
+  },
+}
+
 export const AsyncLoaded: Story = {
   render: () => {
     const [selectedKey, setSelectedKey] = useState<Key>(0)

package/src/Tabs/_docs/Tabs.stories.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react'
 import { type Meta, type StoryObj } from '@storybook/react'
-import { Button } from '~components/ButtonV1'
+import { Button } from '~components/Button'
 import { Text } from '~components/Text'
 import { Tab, TabList, TabPanel, Tabs, type Key } from '../index'
 
@@ -82,8 +82,44 @@ export const Controlled: Story = {
             <Text variant="body">Content 2</Text>
           </TabPanel>
         </Tabs>
-        <Button label="Switch to tab 2" onClick={(): void => setSelectedKey('two')} />
+        <Button onClick={(): void => setSelectedKey('two')}>Switch to tab 2</Button>
       </>
     )
   },
 }
+
+/**
+ * When a tab is selected via user interaction, `TabList` scrolls the selected tab
+ * into view within its horizontal strip. It deliberately does *not* do this on
+ * mount — so when `Tabs` render below the fold, landing on the page does not scroll
+ * the tabs into view or jump the page.
+ *
+ * This story pushes the `Tabs` below the fold with a full-viewport spacer. On load
+ * the page stays at the top. Scroll down and select a tab — only then does the
+ * selected tab scroll into view within the strip.
+ */
+export const BelowTheFold: Story = {
+  render: () => (
+    <div style={{ maxWidth: '760px' }}>
+      <div style={{ height: '100dvh' }}>
+        <Text variant="body">Scroll down — the tabs are rendered below the fold.</Text>
+      </div>
+      <Tabs defaultSelectedKey="tab-0">
+        <TabList aria-label="Lorem ipsum tabs">
+          {Array.from({ length: 8 }, (_, i) => (
+            <Tab key={i} id={`tab-${i}`}>
+              Lorem {i + 1}
+            </Tab>
+          ))}
+        </TabList>
+        {Array.from({ length: 8 }, (_, i) => (
+          <TabPanel key={i} id={`tab-${i}`} className="p-24">
+            <Text variant="body">
+              Lorem ipsum dolor sit amet, consectetur adipiscing elit — panel {i + 1}.
+            </Text>
+          </TabPanel>
+        ))}
+      </Tabs>
+    </div>
+  ),
+}

package/src/Tabs/subcomponents/TabList/TabList.tsx

@@ -44,6 +44,7 @@ export const TabList = (props: TabListProps): JSX.Element => {
   const [containerElement, setContainerElement] = useState<HTMLElement | null>()
   const tabListContext = useContext(TabListStateContext)
   const selectedKey = tabListContext?.selectedKey
+  const prevSelectedKey = useRef(selectedKey)
 
   useEffect(() => {
     if (!isDocumentReady) {
@@ -107,7 +108,14 @@ export const TabList = (props: TabListProps): JSX.Element => {
       return
     }
 
-    // Scroll selected tab into view
+    // Only scroll the selected tab into view when the selection actually changes
+    // (i.e. user interaction). Skipping the no-op runs avoids scrolling the page
+    // on mount when the Tabs sit below the fold.
+    if (prevSelectedKey.current === selectedKey) {
+      return
+    }
+    prevSelectedKey.current = selectedKey
+
     containerElement
       ?.querySelector('[role="tab"][data-selected=true]')
       ?.scrollIntoView({ block: 'nearest', inline: 'center' })

package/src/TextArea/TextArea.tsx

@@ -4,7 +4,7 @@ import { type OverrideClassName } from '~components/types/OverrideClassName'
 import styles from './TextArea.module.css'
 
 export type TextAreaProps = {
-  textAreaRef?: React.RefObject<HTMLTextAreaElement>
+  textAreaRef?: React.Ref<HTMLTextAreaElement>
   status?: 'default' | 'error' | 'caution'
   /**
    * Grows the input height as more content is added

package/src/TimeField/TimeField.tsx

@@ -27,6 +27,7 @@ export type TimeFieldProps = {
   value: ValueType | null
   status?: StatusType
   validationMessage?: React.ReactNode
+  inputRef?: React.Ref<HTMLSpanElement>
 } & OverrideClassName<Omit<TimeFieldStateOptions, OmittedTimeFieldProps>>
 
 // This needed to be placed directly below the props because
@@ -49,6 +50,7 @@ const TimeFieldComponent = ({
   validationMessage,
   isDisabled,
   classNameOverride,
+  inputRef,
   ...restProps
 }: TimeFieldProps): JSX.Element => {
   const reactId = useId()
@@ -79,7 +81,7 @@ const TimeFieldComponent = ({
   const hasError = !!validationMessage && status === 'error'
   const descriptionId = hasError ? `${id}-field-message` : undefined
 
-  const inputRef = React.useRef(null)
+  const internalRef = React.useRef<HTMLDivElement>(null)
   const { fieldProps, labelProps } = useTimeField(
     {
       ...restProps,
@@ -88,36 +90,36 @@ const TimeFieldComponent = ({
       'aria-describedby': descriptionId,
     },
     state,
-    inputRef,
+    internalRef,
   )
+  const firstEditableIndex = state.segments.findIndex((s) => s.isEditable)
+
   return (
     <div className={classNameOverride}>
       <Label disabled={state.isDisabled} {...labelProps} classNameOverride={styles.label}>
         {label}
       </Label>
       <div className={styles.wrapper}>
-        {}
         <div
           {...fieldProps}
           id={id}
-          ref={inputRef}
+          ref={internalRef}
           className={classnames(
             styles.input,
             state.isDisabled && styles.isDisabled,
             status === 'error' && styles.error,
           )}
         >
-          {state.segments.map((segment, i) => {
-            return (
-              <TimeSegment
-                key={i}
-                segment={segment}
-                state={state}
-                hasPadding={![8294, 8297].includes(segment.text.charCodeAt(0))}
-                // ^react-aria includes these characters to ensure correct RTL behaviour, but we want to avoid these adding random spacing
-              />
-            )
-          })}
+          {state.segments.map((segment, i) => (
+            <TimeSegment
+              key={i}
+              segment={segment}
+              state={state}
+              inputRef={i === firstEditableIndex ? inputRef : undefined}
+              hasPadding={![8294, 8297].includes(segment.text.charCodeAt(0))}
+              // ^react-aria includes these characters to ensure correct RTL behaviour, but we want to avoid these adding random spacing
+            />
+          ))}
           <div className={styles.focusRing} />
         </div>
       </div>

package/src/TimeField/subcomponents/TimeSegment/TimeSegment.tsx

@@ -1,5 +1,6 @@
 import React from 'react'
 import { useDateSegment } from '@react-aria/datepicker'
+import { mergeRefs } from '@react-aria/utils'
 import { type DateFieldState, type DateSegment } from '@react-stately/datepicker'
 import classnames from 'classnames'
 import { generateSegmentDisplayText } from './utils/generateSegmentDisplayText'
@@ -9,15 +10,17 @@ export type TimeSegmentProps = {
   segment: DateSegment
   state: DateFieldState
   hasPadding?: boolean
+  inputRef?: React.Ref<HTMLSpanElement>
 }
 
 export const TimeSegment = ({
   segment,
   state,
   hasPadding = true,
+  inputRef,
 }: TimeSegmentProps): JSX.Element => {
-  const ref = React.useRef<HTMLDivElement>(null)
-  const { segmentProps } = useDateSegment(segment, state, ref)
+  const internalRef = React.useRef<HTMLSpanElement>(null)
+  const { segmentProps } = useDateSegment(segment, state, internalRef)
 
   // Chrome has a bug where `contenteditable` elements receive focus from external clicks.
   // This (in combination with the invisible character &#8203;) creates boundaries
@@ -28,7 +31,7 @@ export const TimeSegment = ({
       &#8203;
       <span
         {...segmentProps}
-        ref={ref}
+        ref={mergeRefs<HTMLSpanElement>(internalRef, inputRef)}
         className={classnames(
           styles.timeSegment,
           segment.type === 'literal' && styles.literal,