@tpzdsp/next-toolkit 2.5.1 → 3.0.0

package/src/components/Select/Select.tsx

@@ -0,0 +1,291 @@
+'use client';
+
+import { useId } from 'react';
+
+import { LuChevronDown, LuLoaderCircle, LuX } from 'react-icons/lu';
+import type {
+  ClassNamesConfig,
+  ClearIndicatorProps,
+  ContainerProps,
+  DropdownIndicatorProps,
+  GroupBase,
+  GroupHeadingProps,
+  InputProps,
+  LoadingIndicatorProps,
+  MultiValueProps,
+  OnChangeValue,
+  Props as ReactSelectProps,
+} from 'react-select';
+import { components, default as ReactSelect } from 'react-select';
+
+import { cn } from '../../utils/components';
+import { Separator } from '../Separator/Separator';
+
+export type SelectTagsPlacement = 'inline' | 'below';
+
+export type SelectProps<
+  Option = unknown,
+  IsMulti extends boolean = false,
+  Group extends GroupBase<Option> = GroupBase<Option>,
+> = Omit<ReactSelectProps<Option, IsMulti, Group>, 'className'> & {
+  invalid?: boolean;
+  /** Where selected values render for a multi-select. `below` keeps the control a fixed
+   *  height and lists selected values underneath instead of as inline chips. */
+  tagsPlacement?: SelectTagsPlacement;
+  /** Suppresses the built-in loading spinner in the indicators area, for callers that
+   *  render their own loading state elsewhere (e.g. a fixed-width InputSuffix) instead
+   *  of having the indicators container grow/shrink as it mounts and unmounts. */
+  hideLoadingIndicator?: boolean;
+  /** react-select's own Props type doesn't declare aria-describedby at all (only
+   *  aria-errormessage/invalid/label/labelledby/live), and renderInput() computes its own
+   *  hardcoded value for the real input (pointing at its internal live-region/placeholder),
+   *  overwriting anything already there. Declaring it explicitly here is what makes this
+   *  actually work: the Input override below reads it back out of selectProps (react-select's
+   *  untouched copy of everything passed to Select) and merges it alongside react-select's
+   *  own separately-computed value, rather than it being silently dropped. */
+  'aria-describedby'?: string;
+};
+
+const buildClassNames = <Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
+  invalid: boolean,
+  userClassNames?: ClassNamesConfig<Option, IsMulti, Group>,
+): ClassNamesConfig<Option, IsMulti, Group> => ({
+  container: (props) => cn('cn-select-container', userClassNames?.container?.(props)),
+  control: (props) =>
+    cn(
+      'cn-select-control',
+      props.isFocused && 'cn-select-control-focused',
+      invalid && !props.isFocused && 'cn-select-control-invalid',
+      props.isDisabled && 'cn-select-control-disabled',
+      userClassNames?.control?.(props),
+    ),
+  valueContainer: (props) =>
+    cn(
+      'cn-select-value-container',
+      props.isMulti && 'cn-select-value-container-multi',
+      userClassNames?.valueContainer?.(props),
+    ),
+  singleValue: (props) => cn('cn-select-single-value', userClassNames?.singleValue?.(props)),
+  placeholder: (props) => cn('cn-select-placeholder', userClassNames?.placeholder?.(props)),
+  input: (props) => cn('cn-select-input', userClassNames?.input?.(props)),
+  indicatorsContainer: (props) =>
+    cn('cn-select-indicators', userClassNames?.indicatorsContainer?.(props)),
+  indicatorSeparator: () => 'hidden',
+  dropdownIndicator: (props) =>
+    cn(
+      'cn-select-dropdown-indicator',
+      props.selectProps.menuIsOpen && 'cn-select-dropdown-indicator-open',
+      userClassNames?.dropdownIndicator?.(props),
+    ),
+  clearIndicator: (props) =>
+    cn('cn-select-clear-indicator', userClassNames?.clearIndicator?.(props)),
+  loadingIndicator: (props) =>
+    cn('cn-select-loading-indicator', userClassNames?.loadingIndicator?.(props)),
+  menu: (props) => cn('cn-select-menu', userClassNames?.menu?.(props)),
+  menuList: (props) => cn('cn-select-menu-list', userClassNames?.menuList?.(props)),
+  option: (props) =>
+    cn(
+      'cn-select-option',
+      props.isFocused && !props.isSelected && 'cn-select-option-focused',
+      props.isSelected && 'cn-select-option-selected',
+      props.isDisabled && 'cn-select-option-disabled',
+      userClassNames?.option?.(props),
+    ),
+  noOptionsMessage: (props) =>
+    cn('cn-select-no-options', userClassNames?.noOptionsMessage?.(props)),
+  multiValue: (props) => cn('cn-select-multi-value', userClassNames?.multiValue?.(props)),
+  multiValueLabel: (props) =>
+    cn('cn-select-multi-value-label', userClassNames?.multiValueLabel?.(props)),
+  multiValueRemove: (props) =>
+    cn('cn-select-multi-value-remove', userClassNames?.multiValueRemove?.(props)),
+  group: (props) => cn('cn-select-group', userClassNames?.group?.(props)),
+  groupHeading: (props) => cn('cn-select-group-heading', userClassNames?.groupHeading?.(props)),
+});
+
+const DropdownIndicator = <Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
+  props: DropdownIndicatorProps<Option, IsMulti, Group>,
+) => (
+  <LuChevronDown
+    className={props.getClassNames('dropdownIndicator', props)}
+    strokeWidth={2.5}
+    aria-hidden
+  />
+);
+
+const ClearIndicator = <Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
+  props: ClearIndicatorProps<Option, IsMulti, Group>,
+) => (
+  <components.ClearIndicator {...props}>
+    <LuX className="w-full h-full" strokeWidth={2.5} aria-hidden />
+  </components.ClearIndicator>
+);
+
+const LoadingIndicator = <Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
+  props: LoadingIndicatorProps<Option, IsMulti, Group>,
+) => (
+  <LuLoaderCircle
+    className={cn(props.getClassNames('loadingIndicator', props), 'animate-spin')}
+    aria-hidden
+  />
+);
+
+// react-select's own renderInput() computes its own aria-describedby (pointing
+// at its internal live-region or placeholder element) and spreads it onto the
+// real <input> last, after any of its own props, so it always wins over
+// whatever Select was originally given, see SelectProps['aria-describedby'].
+// selectProps is react-select's own full, unfiltered instance props object
+// though, still holding that original untouched value, so it survives there
+// and can be merged back in, just needs a cast, react-select's own Props type
+// doesn't declare aria-describedby at all (unlike its aria-invalid/label/etc,
+// which it does forward as-is, no merging needed for those).
+const Input = <Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
+  props: InputProps<Option, IsMulti, Group>,
+) => {
+  const external = (props.selectProps as { 'aria-describedby'?: string })['aria-describedby'];
+  const ariaDescribedBy = [props['aria-describedby'], external].filter(Boolean).join(' ');
+
+  return <components.Input {...props} aria-describedby={ariaDescribedBy || undefined} />;
+};
+
+const GroupHeading = <Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
+  props: GroupHeadingProps<Option, IsMulti, Group>,
+) => <Separator className={props.getClassNames('groupHeading', props)}>{props.children}</Separator>;
+
+const MultiValue = <Option, IsMulti extends boolean, Group extends GroupBase<Option>>({
+  removeProps,
+  isDisabled,
+  selectProps,
+  data,
+}: MultiValueProps<Option, IsMulti, Group>) => {
+  const label = selectProps.getOptionLabel(data);
+
+  return (
+    <button
+      type="button"
+      className="cn-select-multi-value"
+      aria-label={`Remove ${label}`}
+      disabled={isDisabled}
+      onClick={removeProps.onClick as unknown as React.MouseEventHandler<HTMLButtonElement>}
+      onMouseDown={removeProps.onMouseDown as unknown as React.MouseEventHandler<HTMLButtonElement>}
+      onTouchEnd={removeProps.onTouchEnd as unknown as React.TouchEventHandler<HTMLButtonElement>}
+    >
+      {label}
+      <LuX aria-hidden className="cn-select-multi-value-remove" strokeWidth={2.5} />
+    </button>
+  );
+};
+
+const HiddenMultiValue = () => null;
+
+const HiddenLoadingIndicator = () => null;
+
+const SelectContainerWithTagsBelow = <
+  Option,
+  IsMulti extends boolean,
+  Group extends GroupBase<Option>,
+>(
+  props: ContainerProps<Option, IsMulti, Group>,
+) => {
+  const { children, selectProps, getValue, hasValue } = props;
+  const { getOptionLabel, getOptionValue, onChange, name, isDisabled } = selectProps;
+
+  const handleRemove = (option: Option) => {
+    const candidate = getOptionValue(option);
+    const newValue = getValue().filter((item) => getOptionValue(item) !== candidate);
+
+    onChange(newValue as OnChangeValue<Option, IsMulti>, {
+      action: 'remove-value',
+      removedValue: option,
+      name,
+    });
+  };
+
+  return (
+    <components.SelectContainer {...props}>
+      {children}
+
+      {hasValue ? (
+        <div className="cn-select-tags">
+          {getValue().map((option) => (
+            <button
+              key={getOptionValue(option)}
+              type="button"
+              className="cn-select-tag"
+              aria-label={`Remove ${getOptionLabel(option)}`}
+              disabled={isDisabled}
+              onClick={() => handleRemove(option)}
+            >
+              {getOptionLabel(option)}
+              <LuX aria-hidden className="cn-select-multi-value-remove" strokeWidth={2.5} />
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </components.SelectContainer>
+  );
+};
+
+export const Select = <
+  Option = unknown,
+  IsMulti extends boolean = false,
+  Group extends GroupBase<Option> = GroupBase<Option>,
+>({
+  classNames: userClassNames,
+  styles: userStyles,
+  invalid = false,
+  isMulti,
+  tagsPlacement = 'inline',
+  hideLoadingIndicator = false,
+  ...props
+}: SelectProps<Option, IsMulti, Group>) => {
+  const instanceId = useId();
+  const showTagsBelow = isMulti && tagsPlacement === 'below';
+
+  return (
+    <ReactSelect
+      menuPortalTarget={typeof document !== 'undefined' ? document.body : null}
+      menuPosition="fixed"
+      tabSelectsValue={false}
+      {...props}
+      isMulti={isMulti}
+      instanceId={instanceId}
+      unstyled
+      aria-invalid={invalid ? 'true' : undefined}
+      styles={{
+        ...userStyles,
+        // react-select injects outline: 0 !important and transition via Emotion
+        // on the control div even in unstyled mode. By returning an empty object
+        // (not spreading base) we prevent that class from being generated, so
+        // our CSS classes can set outline freely without needing !important.
+        control: (_, controlProps) => ({
+          ...userStyles?.control?.({}, controlProps),
+        }),
+        // Removes the `pointer-events: none` style.
+        container: (_, containerProps) => ({
+          ...userStyles?.container?.({}, containerProps),
+        }),
+        // react-select renders the portal wrapper itself with an inline
+        // style, a separate element from .cn-select-menu (which already
+        // has cn-z-overlay), so it isn't reachable via our own CSS classes
+        // and has to independently match that same value (999999) here, or
+        // this outer wrapper's z-index is what actually determines stacking
+        // against unrelated high z-index content elsewhere on the page.
+        menuPortal: (base, portalProps) => ({
+          ...base,
+          zIndex: 999999,
+          ...userStyles?.menuPortal?.(base, portalProps),
+        }),
+      }}
+      classNames={buildClassNames<Option, IsMulti, Group>(invalid, userClassNames)}
+      components={{
+        Input,
+        DropdownIndicator,
+        ClearIndicator,
+        LoadingIndicator: hideLoadingIndicator ? HiddenLoadingIndicator : LoadingIndicator,
+        MultiValue: showTagsBelow ? HiddenMultiValue : MultiValue,
+        GroupHeading,
+        ...(showTagsBelow ? { SelectContainer: SelectContainerWithTagsBelow } : {}),
+      }}
+    />
+  );
+};

package/src/components/Select/SelectSkeleton.stories.tsx

@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Select } from './Select';
+import { SelectSkeleton } from './SelectSkeleton';
+
+const meta: Meta<typeof SelectSkeleton> = {
+  title: 'Components/Select/Skeleton',
+  component: SelectSkeleton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Placeholder for a Select while its options are loading. Reuses cn-select-container/control/value-container/indicators directly, so its dimensions always match the real control exactly, no layout shift when it swaps in.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SelectSkeleton>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="w-64">
+      <SelectSkeleton />
+    </div>
+  ),
+};
+
+export const SideBySide: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'The skeleton and the real control line up exactly, same height, border, padding.',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex gap-gds-4">
+      <div className="w-64">
+        <SelectSkeleton />
+      </div>
+
+      <div className="w-64">
+        <Select options={[{ value: 'a', label: 'Option A' }]} placeholder="Select an option" />
+      </div>
+    </div>
+  ),
+};

package/src/components/Select/SelectSkeleton.tsx

@@ -0,0 +1,23 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+import { Skeleton } from '../Skeleton/Skeleton';
+
+export type SelectSkeletonProps = ComponentProps<'div'> & {
+  /** Explicitly disallow children, a skeleton is a placeholder shape, not a content wrapper. */
+  children?: never;
+};
+
+export const SelectSkeleton = ({ className, ...props }: SelectSkeletonProps) => (
+  <div aria-hidden className={cn('cn-select-container', className)} {...props}>
+    <div className="cn-select-control">
+      <div className="cn-select-value-container">
+        <Skeleton className="cn-select-skeleton-value" />
+      </div>
+
+      <div className="cn-select-indicators">
+        <Skeleton className="cn-select-skeleton-indicator" />
+      </div>
+    </div>
+  </div>
+);

package/src/components/Separator/Separator.css

@@ -0,0 +1,41 @@
+@layer components {
+  /*
+    MARK: Separator
+    GDS section break using the divider colour.
+    No external margin. Spacing belongs to the surrounding layout.
+
+    Vertical separators require a flex parent to get natural height via
+    align-self: stretch. Without one, set an explicit height on the separator.
+  */
+  .cn-separator {
+    @apply relative flex items-center justify-center;
+  }
+
+  .cn-separator[data-orientation='horizontal'] {
+    @apply w-full max-h-px;
+  }
+
+  .cn-separator[data-orientation='vertical'] {
+    @apply self-stretch flex-col max-w-px;
+  }
+
+  /* MARK: Line */
+
+  .cn-separator-line {
+    @apply absolute shrink-0 bg-divider border-none;
+  }
+
+  .cn-separator-line[data-orientation='horizontal'] {
+    @apply w-full top-1/2 -translate-y-1/2 h-px;
+  }
+
+  .cn-separator-line[data-orientation='vertical'] {
+    @apply h-full left-1/2 -translate-x-1/2 w-px;
+  }
+
+  /* MARK: Content */
+
+  .cn-separator-content {
+    @apply relative z-10;
+  }
+}

package/src/components/Separator/Separator.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Separator } from './Separator';
+
+const meta: Meta<typeof Separator> = {
+  title: 'Components/Separator',
+  component: Separator,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Use Separator to visually divide content sections in layouts and forms.',
+      },
+    },
+  },
+  argTypes: {
+    orientation: {
+      control: { type: 'radio' },
+      options: ['horizontal', 'vertical'],
+    },
+    decorative: { control: 'boolean' },
+  },
+  args: {
+    orientation: 'horizontal',
+    decorative: true,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Separator>;
+
+export const Horizontal: Story = {};
+
+export const Vertical: Story = {
+  args: {
+    orientation: 'vertical',
+    decorative: false,
+    // hardcode height for example otherwise it will collapse to 0px
+    style: { height: '50px' },
+  },
+};
+
+export const WithText: Story = {
+  args: {
+    orientation: 'horizontal',
+    children: 'Section Title',
+  },
+};
+
+export const InlineExample: Story = {
+  // Vertical separators can't have children.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ children, ...args }) => (
+    <div className="flex h-24 items-center gap-3">
+      <span>Left content</span>
+
+      <Separator {...args} orientation="vertical" decorative={false} />
+
+      <span>Right content</span>
+    </div>
+  ),
+};

package/src/components/Separator/Separator.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import type { ComponentProps, ReactNode } from 'react';
+
+import { Separator as SeparatorPrimitive } from 'radix-ui';
+
+import { cn } from '../../utils/components';
+import { Chip } from '../Chip/Chip';
+
+type HorizontalSeparatorProps = ComponentProps<typeof SeparatorPrimitive.Root> & {
+  orientation?: 'horizontal';
+  children?: ReactNode;
+};
+
+type VerticalSeparatorProps = ComponentProps<typeof SeparatorPrimitive.Root> & {
+  orientation: 'vertical';
+  children?: never;
+};
+
+export type SeparatorProps = HorizontalSeparatorProps | VerticalSeparatorProps;
+
+export const Separator = ({
+  className,
+  orientation,
+  decorative = true,
+  children,
+  ...props
+}: SeparatorProps) => (
+  <div {...props} className={cn('cn-separator', className)} data-orientation={orientation}>
+    <SeparatorPrimitive.Root
+      data-slot="separator"
+      decorative={decorative}
+      orientation={orientation}
+      className="cn-separator-line"
+    />
+    {children && (
+      <Chip className="cn-separator-content" appearance="neutral" size="sm">
+        {children}
+      </Chip>
+    )}
+  </div>
+);

package/src/components/Sidebar/ResizableSidebar.tsx

@@ -0,0 +1,118 @@
+'use client';
+
+import { useLayoutEffect, useRef, useState, type ComponentProps } from 'react';
+
+import { usePanelRef } from 'react-resizable-panels';
+
+import { useSidebar } from './Sidebar';
+import { cn } from '../../utils/components';
+import { ResizableHandle, ResizablePanel } from '../Resizable/Resizable';
+
+export type ResizableSidebarProps = Omit<
+  ComponentProps<typeof ResizablePanel>,
+  'panelRef' | 'onResize' | 'collapsible'
+>;
+
+export const ResizableSidebar = ({
+  className,
+  defaultSize = '16rem',
+  minSize = '12rem',
+  collapsedSize = 0,
+  ...props
+}: ResizableSidebarProps) => {
+  const { open, setOpen } = useSidebar();
+  const panelRef = usePanelRef();
+  const isFirstRender = useRef(true);
+
+  // Captured once and never recomputed. Panel's own registration (and the
+  // "most recent size" expand() restores) depends on this prop, so passing
+  // a value that changes every time `open` toggles corrupts that memory,
+  // reopening lands back on this value instead of wherever the user last
+  // dragged to before closing.
+  const [initialSize] = useState(() => (open ? defaultSize : collapsedSize));
+
+  // Skip the very first run: ResizableSidebar commits before its parent
+  // ResizablePanelGroup finishes registering itself, so calling expand() or
+  // collapse() here on mount throws ("Group not found"). defaultSize below
+  // already renders the correct initial state, so this effect only needs to
+  // handle `open` changing after mount, by which point the group is stable.
+  //
+  // The only drag-driven `open` change left is closing (handleResize below
+  // sets it): ResizableSidebarHandle disables itself while closed, so a drag
+  // can never produce the reverse (open) transition. collapse() here is a
+  // harmless no-op for that case, the panel's already exactly at
+  // collapsedSize by the time the drag triggers it.
+  useLayoutEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+
+      return;
+    }
+
+    // expand()/collapse() throw if this panel's ResizablePanelGroup isn't
+    // currently registered (react-resizable-panels keeps a module-level
+    // registry, looked up by id on every call, not a stable reference). The
+    // isFirstRender guard above only covers this component's own first
+    // commit; a Next.js route transition can still unmount/remount the whole
+    // group+panel tree, or briefly leave it unregistered, independently of
+    // that. There's nothing to sync in that instant, the panel already
+    // renders at the correct size once mounted, so swallow it rather than
+    // crashing the page.
+    try {
+      if (open) {
+        panelRef.current?.expand();
+      } else {
+        panelRef.current?.collapse();
+      }
+    } catch {
+      // no-op, see comment above
+    }
+  }, [open, panelRef]);
+
+  const handleResize = () => {
+    const collapsed = panelRef.current?.isCollapsed() ?? false;
+
+    // Dragging the handle closed doesn't go through the trigger, so sync
+    // `open` back here to keep it (and the trigger button) accurate.
+    if (collapsed === open) {
+      setOpen(!collapsed);
+    }
+  };
+
+  return (
+    <ResizablePanel
+      panelRef={panelRef}
+      collapsible
+      defaultSize={initialSize}
+      minSize={minSize}
+      collapsedSize={collapsedSize}
+      onResize={handleResize}
+      // Matches Sidebar's own <aside inert={...}>: at 0 width the panel is
+      // still reachable by Tab unless explicitly made inert.
+      inert={open ? undefined : true}
+      className={cn('cn-resizable-sidebar', className)}
+      {...props}
+    />
+  );
+};
+
+export type ResizableSidebarHandleProps = ComponentProps<typeof ResizableHandle>;
+
+// react-resizable-panels won't drag a collapsible panel open again from a
+// fully collapsed (0) size unless the gesture crosses roughly the halfway
+// point to minSize, and arrow keys move in increments far too small to ever
+// cross it, so a collapsed ResizableSidebar's handle would look broken rather
+// than draggable if it stayed visible. Disabling it hides it entirely (see
+// [data-separator='disabled'] in Resizable.css) and stops it responding to
+// input, while still rendering the same mounted Separator: actually removing
+// it from the tree while closed (an earlier version of this returned null)
+// broke react-resizable-panels' own Group, unmounting/remounting a Separator
+// confuses its internal pointer-listener bookkeeping, throwing
+// "object that is not, or is no longer, usable" the next time you tried to
+// drag anything in the group. `disabled` still lets a consumer force-disable
+// it while open, for reasons unrelated to the collapsed state.
+export const ResizableSidebarHandle = ({ disabled, ...props }: ResizableSidebarHandleProps) => {
+  const { open } = useSidebar();
+
+  return <ResizableHandle disabled={disabled ?? !open} {...props} />;
+};