Introduce Segment Picker (#107)

* Introduce Segment Picker

* new variables

* Improvements

* lint fix

* Add forwardRef and css layers

* add event object to onChange

* Add segment picker item docs

* Introduce shape validation

Author: piotrblaszczyk

packages/ui/src/components/segment-picker/border-radius-size.module.css

@@ -0,0 +1,53 @@
+:root {
+  --ax-public-segment-picker-border-radius-extra-large: var(
+    --ax-token-radius-seg-picker-xl
+  );
+  --ax-public-segment-picker-border-radius-large: var(
+    --ax-token-radius-seg-picker-l
+  );
+  --ax-public-segment-picker-border-radius-medium: var(
+    --ax-token-radius-seg-picker-m
+  );
+  --ax-public-segment-picker-border-radius-small: var(
+    --ax-token-radius-seg-picker-s
+  );
+  --ax-public-segment-picker-border-radius-extra-small: var(
+    --ax-token-radius-seg-picker-xs
+  );
+  --ax-public-segment-picker-border-radius-xx-small: var(
+    --ax-token-radius-seg-picker-xxs
+  );
+  --ax-public-segment-picker-border-radius-xxx-small: var(
+    --ax-token-radius-seg-picker-xxxs
+  );
+}
+
+@layer ui.component {
+  .extra-large {
+    border-radius: var(--ax-public-segment-picker-border-radius-extra-large);
+  }
+
+  .large {
+    border-radius: var(--ax-public-segment-picker-border-radius-large);
+  }
+
+  .medium {
+    border-radius: var(--ax-public-segment-picker-border-radius-medium);
+  }
+
+  .small {
+    border-radius: var(--ax-public-segment-picker-border-radius-small);
+  }
+
+  .extra-small {
+    border-radius: var(--ax-public-segment-picker-border-radius-extra-small);
+  }
+
+  .xx-small {
+    border-radius: var(--ax-public-segment-picker-border-radius-xx-small);
+  }
+
+  .xxx-small {
+    border-radius: var(--ax-public-segment-picker-border-radius-xxx-small);
+  }
+}

packages/ui/src/components/segment-picker/item/segment-picker-item-shape.module.css

@@ -0,0 +1,6 @@
+@layer ui.component {
+  .item:not(.circle),
+  div:has(.item:not(.circle)) {
+    width: 100%;
+  }
+}

packages/ui/src/components/segment-picker/item/segment-picker-item.tsx

@@ -0,0 +1,71 @@
+import clsx from 'clsx';
+import itemShapeStyles from './segment-picker-item-shape.module.css';
+
+import { NavLabelButtonProps } from '@ui/components/button/nav-button/nav-label-button/nav-label-button';
+import { NavIconButtonProps } from '@ui/components/button/nav-button/nav-icon-button/nav-icon-button';
+import { NavIconLabelButtonProps } from '@ui/components/button/nav-button/nav-icon-label-button/nav-icon-label-button';
+import {
+  hasStringChildrenOnly,
+  hasIconChildrenOnly,
+  hasChildrenWithStringAndIcons,
+} from '@ui/components/button/guards';
+import { NavButton } from '@ui/components/button/nav-button/nav-button';
+import { MouseEventHandler, useContext } from 'react';
+import { BaseButtonProps } from '../../button/types';
+import { SegmentPickerContext } from '../utils/context';
+
+export type SegmentPickerItemProps = BaseButtonProps & {
+  value: string;
+} & (
+    | Pick<NavLabelButtonProps, 'children'>
+    | Pick<NavIconButtonProps, 'children'>
+    | Pick<NavIconLabelButtonProps, 'children'>
+  );
+
+/**
+ * A single item in the SegmentPicker, rendered as a NavButton under the hood.
+ *
+ * Automatically receives size and shape from SegmentPicker context.
+ * Must be used only within a SegmentPicker component.
+ *
+ * Determines which NavButton variant to render based on its children
+ * (label only, icon only, or icon + label).
+ */
+export function Item({
+  children,
+  value,
+  ...buttonProps
+}: SegmentPickerItemProps) {
+  const context = useContext(SegmentPickerContext);
+
+  if (!context) {
+    throw new Error('SegmentPicker.Item must be used within a SegmentPicker');
+  }
+
+  const { selectedValue, onSelect, shape, ...other } = context;
+
+  const props = {
+    className: clsx(itemShapeStyles['item'], itemShapeStyles[shape || '']),
+    isSelected: selectedValue === value,
+    onClick: (event: MouseEventHandler<HTMLButtonElement>) =>
+      onSelect(event, value),
+    shape,
+    children,
+    ...other,
+    ...buttonProps,
+  };
+
+  if (hasStringChildrenOnly<NavLabelButtonProps>(props)) {
+    return <NavButton {...props} />;
+  }
+
+  if (hasIconChildrenOnly<NavIconButtonProps>(props)) {
+    return <NavButton {...props} />;
+  }
+
+  if (hasChildrenWithStringAndIcons<NavIconLabelButtonProps>(props)) {
+    return <NavButton {...props} />;
+  }
+
+  return null;
+}

packages/ui/src/components/segment-picker/segment-picker.module.css

@@ -0,0 +1,27 @@
+:root {
+  --ax-public-segment-picker-gap: var(--ax-token-spacing-seg-picker-gap);
+  --ax-public-segment-picker-padding: var(--ax-token-spacing-seg-picker-pad);
+  --ax-public-segment-picker-background-color: var(--ax-ui-bg-tertiary-default);
+  --ax-public-segment-picker-circle-border-radius: var(
+    --ax-token-radius-button-round
+  );
+}
+
+@layer ui.component {
+  .container {
+    display: flex;
+    gap: var(--ax-public-segment-picker-gap);
+    padding: var(--ax-public-segment-picker-padding);
+
+    background-color: var(--ax-public-segment-picker-background-color);
+
+    &.circle {
+      border-radius: var(--ax-public-segment-picker-circle-border-radius);
+      width: fit-content;
+    }
+
+    &:not(.circle) {
+      width: 100%;
+    }
+  }
+}

packages/ui/src/components/segment-picker/segment-picker.tsx

@@ -0,0 +1,85 @@
+import clsx from 'clsx';
+import styles from './segment-picker.module.css';
+import borderRadiusStyles from './border-radius-size.module.css';
+
+import {
+  useState,
+  ReactElement,
+  forwardRef,
+  ForwardRefExoticComponent,
+  MouseEventHandler,
+} from 'react';
+import { Size } from '@ui/shared/types/size';
+import { Shape } from '@ui/components/button/types';
+import { SegmentPickerItemProps, Item } from './item/segment-picker-item';
+import { getValidShape } from './utils/get-valid-shape';
+import { SegmentPickerContext } from './utils/context';
+
+type SegmentPickerProps = {
+  children: ReactElement<SegmentPickerItemProps, typeof Item>[];
+  value: string;
+  size?: Size;
+  /**
+   * Controls the shape of the SegmentPicker and its items.
+   * (default) -Items stretch to fill the container equally.
+   * 'circle' - Items fit tightly around their content to maintain a circular shape.
+   * Only supported when items contain icons only.
+   */
+  shape?: Shape;
+  className?: string;
+  onChange?: (
+    event: MouseEventHandler<HTMLButtonElement>,
+    value: string,
+  ) => void;
+};
+
+type SegmentPickerComponent = ForwardRefExoticComponent<
+  SegmentPickerProps & React.RefAttributes<HTMLDivElement>
+> & {
+  Item: typeof Item;
+};
+
+export const SegmentPicker = forwardRef<HTMLDivElement, SegmentPickerProps>(
+  (
+    { children, value, size = 'medium', shape = '', className, onChange },
+    ref,
+  ) => {
+    const validShape = getValidShape(shape, children);
+    const [selectedValue, setSelectedValue] = useState<string | null>(
+      value || null,
+    );
+
+    const handleSelect = (
+      event: React.MouseEventHandler<HTMLButtonElement>,
+      newValue: string,
+    ) => {
+      setSelectedValue(newValue);
+      onChange?.(event, newValue);
+    };
+
+    return (
+      <SegmentPickerContext.Provider
+        value={{
+          selectedValue,
+          onSelect: handleSelect,
+          size,
+          shape: validShape,
+        }}
+      >
+        <div
+          ref={ref}
+          className={clsx(
+            styles['container'],
+            styles[validShape],
+            borderRadiusStyles[size],
+            className,
+          )}
+        >
+          {children}
+        </div>
+      </SegmentPickerContext.Provider>
+    );
+  },
+) as SegmentPickerComponent;
+
+SegmentPicker.Item = Item;

packages/ui/src/components/segment-picker/utils/context.ts

@@ -0,0 +1,16 @@
+import { createContext, MouseEventHandler } from 'react';
+import { Shape } from '@ui/components/button/types';
+import { Size } from '@ui/shared/types/size';
+
+type SegmentPickerContextType = {
+  selectedValue: string | null;
+  onSelect: (
+    event: MouseEventHandler<HTMLButtonElement>,
+    value: string,
+  ) => void;
+  size?: Size;
+  shape?: Shape;
+};
+
+export const SegmentPickerContext =
+  createContext<SegmentPickerContextType | null>(null);

packages/ui/src/components/segment-picker/utils/get-valid-shape.ts

@@ -0,0 +1,26 @@
+import { hasIconChildrenOnly } from '../../button/guards';
+import { Shape } from '@ui/components/button/types';
+import { ReactElement } from 'react';
+import { Item, SegmentPickerItemProps } from '../item/segment-picker-item';
+
+export function getValidShape(
+  shape: Shape,
+  items: ReactElement<SegmentPickerItemProps, typeof Item>[],
+): Shape {
+  if (shape !== 'circle') {
+    return shape;
+  }
+
+  const everyItemHasOnlyIcon = items.every((item) =>
+    hasIconChildrenOnly({ children: item.props.children }),
+  );
+
+  if (!everyItemHasOnlyIcon) {
+    console.warn(
+      '[SegmentPicker] The "circle" shape can only be used when all SegmentPicker.Item components contain icon-only children.',
+    );
+    return '';
+  }
+
+  return shape;
+}

packages/ui/src/index.ts

@@ -49,6 +49,8 @@ export * from './components/separator/separator';
 
 export * from './components/status/status';
 
+export * from './components/segment-picker/segment-picker';
+
 // Types
 export * from './components/button/regular-button/types';
 export * from './components/date-picker/types';

packages/ui/src/shared/types/size.ts

@@ -6,6 +6,5 @@ export const SIZES = [
   'medium',
   'large',
   'extra-large',
-  'xx-large',
 ] as const;
 export type Size = (typeof SIZES)[number];

packages/website/docs/authored/ui/segment-picker/segment-picker-docs.tsx

@@ -0,0 +1,37 @@
+import { ComponentPage } from '@site/src/components/component-utils/component-page/component-page';
+import exampleCode from '!!raw-loader!@site/docs/code-examples/segment-picker.example.tsx';
+import { ComponentProp, toPropMap } from '@site/docs/utils/to-prop-map';
+import { SIZES } from '@synergycodes/axiom';
+
+export function SegmentPickerDocs() {
+  const props: Record<string, ComponentProp> = {
+    size: {
+      defaultValue: 'medium',
+      unionValues: SIZES,
+    },
+    children: {
+      required: true,
+      unionValues: ['ReactElement<SegmentPickerItemProps>[]'],
+    },
+    onChange: {
+      unionValues: [
+        '(event: MouseEventHandler<HTMLButtonElement>, value: string) => void',
+      ],
+    },
+  };
+
+  return (
+    <ComponentPage
+      cssPaths={[
+        'components/segment-picker/segment-picker.module.css',
+        'components/segment-picker/border-radius-size.module.css',
+        'components/segment-picker/item/segment-picker-item-shape.module.css',
+      ]}
+      componentPath="components/segment-picker/segment-picker.tsx"
+      exampleCode={exampleCode}
+      hardcodedData={{
+        props: toPropMap(props),
+      }}
+    />
+  );
+}