@czi-sds/components 24.0.0 → 24.2.0

package/README.md

@@ -1,6 +1,6 @@
 # `@czi-sds/components`
 
-React component library for the [Science Design System (SDS)](https://sds.czi.design/). Built on **Material UI v9**.
+React component library for the [Science Design System (SDS)](https://chanzuckerberg.github.io/sci-components/). Built on **Material UI v9**.
 
 Full documentation (usage, theming, scripts, contributing) lives in the [repository README](https://github.com/chanzuckerberg/sci-components#readme).
 
@@ -36,7 +36,7 @@ SDS `24.0.0` is a **breaking release** that moves the Material UI peer dependenc
 
 ## Links
 
-- [Design docs (Zeroheight)](https://sds.czi.design/)
+- [Design system documentation](https://chanzuckerberg.github.io/sci-components/)
 - [Full repo docs](https://github.com/chanzuckerberg/sci-components#readme)
 - [npm package](https://www.npmjs.com/package/@czi-sds/components)
 - [Material UI API docs](https://mui.com/)

package/dist/index.cjs.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="react" />
-import { AccordionDetailsProps, AccordionProps as AccordionProps$1, AccordionSummaryProps, AlertProps, AppBarProps, AutocompleteChangeDetails, AutocompleteChangeReason, AutocompleteCloseReason, AutocompleteInputChangeReason, AutocompleteProps as AutocompleteProps$1, AutocompleteRenderInputParams, AutocompleteValue, ButtonGroupProps as ButtonGroupProps$1, ButtonProps as ButtonProps$1, CardMedia, CardMediaProps, CardProps, CheckboxProps as CheckboxProps$1, ChipProps as ChipProps$1, ClickAwayListenerProps, DialogActionsProps as DialogActionsProps$1, DialogContentProps as DialogContentProps$1, DialogProps as DialogProps$1, DialogTitleProps as DialogTitleProps$1, DrawerProps, IconButtonProps as IconButtonProps$1, LinkProps as LinkProps$1, ListItemProps as ListItemProps$1, ListProps as ListProps$1, ListSubheaderProps as ListSubheaderProps$1, MenuItemProps as MenuItemProps$1, MenuProps as MenuProps$1, PaletteMode, PaperProps, PopoverProps as PopoverProps$1, PopperProps, RadioProps as RadioProps$1, SliderProps, SwitchProps, TabProps as TabProps$1, TabsProps as TabsProps$1, TextFieldProps, ToggleButtonGroupProps, TooltipProps as TooltipProps$1 } from "@mui/material";
+import { AccordionDetailsProps, AccordionProps as AccordionProps$1, AccordionSummaryProps, AlertProps, AppBarProps, AutocompleteChangeDetails, AutocompleteChangeReason, AutocompleteCloseReason, AutocompleteInputChangeReason, AutocompleteProps as AutocompleteProps$1, AutocompleteRenderInputParams, AutocompleteValue, ButtonGroupProps as ButtonGroupProps$1, ButtonProps as ButtonProps$1, CardMedia, CardMediaProps, CardProps, CheckboxProps as CheckboxProps$1, ChipProps as ChipProps$1, ClickAwayListenerProps, DialogActionsProps as DialogActionsProps$1, DialogContentProps as DialogContentProps$1, DialogProps as DialogProps$1, DialogTitleProps as DialogTitleProps$1, DrawerProps, IconButtonProps as IconButtonProps$1, LinkProps as LinkProps$1, ListItemProps as ListItemProps$1, ListProps as ListProps$1, ListSubheaderProps as ListSubheaderProps$1, MenuItemProps as MenuItemProps$1, MenuProps as MenuProps$1, PaletteMode, PaperProps, PopoverProps as PopoverProps$1, PopperProps, RadioProps as RadioProps$1, SlideProps, SliderProps, SwitchProps, TabProps as TabProps$1, TabsProps as TabsProps$1, TextFieldProps, ToggleButtonGroupProps, TooltipProps as TooltipProps$1 } from "@mui/material";
 import React$1, { CSSProperties, ComponentType, ElementType, HTMLAttributeAnchorTarget, HTMLAttributes, ReactElement, ReactNode, SyntheticEvent } from "react";
 import { Breakpoints, PaletteOptions, Theme as Theme$1, ThemeOptions, TypographyStyle } from "@mui/material/styles";
 import { SerializedStyles } from "@emotion/react";
@@ -66,6 +66,7 @@ interface BaseColor {
   surfaceSecondary: string;
   surfacePrimaryDark: string;
   surfaceInverse: string;
+  surfaceTertiary: string;
   textPrimary: string;
   textPrimaryOnDark: string;
   textPrimaryInverse: string;
@@ -112,6 +113,7 @@ interface BaseColor {
   borderPrimaryDisabledOnDark: string;
   borderPrimaryDisabledInverse: string;
   borderSecondaryOnDark: string;
+  borderHighlight: string;
   ornamentDisabled: string;
   ornamentDisabledOnDark: string;
   ornamentDisabledInverse: string;
@@ -121,6 +123,7 @@ interface BaseColor {
   ornamentPrimaryInverse: string;
   ornamentSecondary: string;
   ornamentSecondaryOnDark: string;
+  ornamentTertiary: string;
   ornamentSecondaryInverse: string;
   ornamentSecondaryInteraction: string;
   ornamentSecondaryInteractionOnDark: string;
@@ -922,6 +925,19 @@ interface SdsIconWithColor {
 type IconProps<IconName extends keyof IconNameToSizes> = IconExtraProps<IconName> & SdsIconWithColor;
 /**
  * @see https://mui.com/material-ui/icons/#icons
+ *
+ * @deprecated
+ * This component is deprecated and will be removed in a future major version.
+ * SDS icons come from Phosphor now: import the icon you need from
+ * `@phosphor-icons/react`, or from `@czi-sds/icons` for the icons SDS draws
+ * itself. Both take the same props, so the only difference is the import.
+ *
+ * ```tsx
+ * // Before
+ * <Icon sdsIcon="InfoCircle" sdsSize="l" />
+ * // After
+ * <InfoIcon size={24} />
+ * ```
  */
 declare const Icon: import("react").ForwardRefExoticComponent<IconExtraProps<keyof IconNameToSizes> & SdsIconWithColor & import("react").RefAttributes<HTMLDivElement | null>>;
 //#endregion
@@ -1136,23 +1152,25 @@ declare const ButtonDropdown: React$1.ForwardRefExoticComponent<Omit<ButtonDropd
 //#region src/core/ButtonGroup/ButtonGroup.types.d.ts
 interface ButtonGroupProps extends Omit<ButtonGroupProps$1, "variant" | "size"> {
   /**
-   * The background appearance of the button group.
+   * Tells the group which surface it sits on so it can pick colors with enough
+   * contrast.
    * @default "matchBackground"
    */
   backgroundAppearance?: "dark" | "matchBackground";
   /**
-   * The style of the button group.
+   * Style of the button group. Outline is the only value.
    * @default "outline"
    */
   sdsStyle?: "outline";
   /**
-   * The type of the button group that determines the color scheme.
+   * Color scheme applied to every button in the group.
    * @default "primary"
    */
   sdsType?: "primary" | "secondary";
   /**
-   * The size of the button group.
-   * @default "medium"
+   * Size of the group. It is injected into each Button and ButtonToggle child,
+   * so setting size on an individual button has no effect.
+   * @default "large"
    */
   size?: "small" | "medium" | "large";
 }
@@ -1205,6 +1223,10 @@ declare const ButtonIcon: import("react").ForwardRefExoticComponent<Omit<ButtonI
 //#endregion
 //#region src/core/ButtonToggle/ButtonToggle.types.d.ts
 interface ButtonToggleProps extends ButtonProps {
+  /**
+   * Required. The icon displayed within the component. Pass the SDS Icon
+   * component, for example `<Icon sdsIcon="Search" sdsSize="s" />`.
+   */
   startIcon: keyof IconNameToSizes | React.ReactElement<CustomSVGProps>;
   sdsStage?: "on" | "off";
 }
@@ -1318,6 +1340,10 @@ interface CalloutProps {
   hideTitle?: boolean;
   body?: React$1.ReactNode;
   hideBody?: boolean;
+  /**
+   * The same slot as `children`, for callers that would rather pass it as a
+   * prop. Both render when both are given, `children` first.
+   */
   extraContent?: React$1.ReactNode;
   sdsStyle?: CalloutSdsStyleType;
 }
@@ -1339,8 +1365,20 @@ declare const CalloutTitle: {
 interface TooltipExtraProps extends CommonThemeProps {
   arrowOffset?: number;
   followCursor?: boolean;
+  /**
+   * @deprecated Tooltips follow the theme mode and no longer have an inverted
+   * style. This prop is ignored and will be removed in a future release.
+   */
   inverted?: boolean;
+  /**
+   * @deprecated Tooltips follow the theme mode and no longer have an inverted
+   * style. This prop is ignored and will be removed in a future release.
+   */
   sdsStyle?: "dark" | "light";
+  /**
+   * @deprecated Tooltips follow the theme mode and no longer have an inverted
+   * style. This prop is ignored and will be removed in a future release.
+   */
   hasInvertedStyle?: boolean;
   title?: React.ReactNode;
   subtitle?: React.ReactNode;
@@ -1348,6 +1386,9 @@ interface TooltipExtraProps extends CommonThemeProps {
   textAlign?: "left" | "center" | "right";
   componentSlot?: React.ReactNode;
   /**
+   * The popper the tooltip renders into, carrying the arrow's shape and
+   * placement.
+   *
    * (v9): MUI removed the Tooltip `PopperComponent` prop in favor of
    * `slots.popper`. We keep `PopperComponent` as an SDS prop for backward
    * compatibility and map it to `slots.popper` internally.
@@ -1565,7 +1606,19 @@ type InputDropdownProps$1 = InputDropdownProps$2 & {
 /**
  * @see https://mui.com/material-ui/react-button/
  */
-declare const InputDropdown: (props: InputDropdownProps$1) => JSX.Element;
+declare const InputDropdown: import("react").ForwardRefExoticComponent<InputDropdownProps$2 & {
+  classes?: {
+    root?: string | undefined;
+    label?: string | undefined;
+    labelDetailsWrapper?: string | undefined;
+    contentWrapper?: string | undefined;
+    details?: string | undefined;
+    counter?: string | undefined;
+    iconWrapper?: string | undefined;
+    chevronIcon?: string | undefined;
+    minimalDetails?: string | undefined;
+  } | undefined;
+} & import("react").RefAttributes<HTMLButtonElement>>;
 //#endregion
 //#region src/core/Dropdown/index.d.ts
 interface ExtraDropdownProps<T, Multiple extends boolean | undefined, DisableClearable extends boolean | undefined, FreeSolo extends boolean | undefined> {
@@ -1618,6 +1671,10 @@ interface BaseContentCardProps extends CardProps {
   metadataText?: ReactNode;
   boundingBox?: boolean;
   decorativeBorder?: boolean;
+  /**
+   * The content to be displayed inside the card body, including custom
+   * components and ContentCardActions.
+   */
   children?: ReactNode;
   clickableCard?: boolean;
   clickableCardProps?: Partial<ButtonProps & {
@@ -1741,6 +1798,7 @@ declare const Dialog: React$1.ForwardRefExoticComponent<Omit<DialogProps, "ref">
 interface DialogActionsProps extends DialogActionsProps$1 {
   sdsSize?: DialogExtraProps["sdsSize"];
   buttonPosition?: "left" | "right";
+  /** Class name for the actions row. */
   classes?: {
     root?: string;
   };
@@ -1784,6 +1842,7 @@ interface DialogTitleProps extends DialogTitleExtraProps, DialogTitleProps$1 {
   subtitle?: string;
   overline?: string;
   onClose?: () => void;
+  /** Class names for the individual parts of the title block. */
   classes?: {
     root?: string;
     title?: string;
@@ -1844,6 +1903,11 @@ interface CheckboxContentProps extends Omit<CheckboxProps$1, "color" | "defaultC
   intent?: "default" | "negative" | "notice" | "positive";
   label?: React.ReactNode;
   stage?: "checked" | "unchecked" | "indeterminate";
+  /**
+   * Class names for the internal elements: root, labelCaptionContainer, label,
+   * caption, checkbox, checkboxCheckedIcon, checkboxDefaultIcon, and
+   * checkboxIndeterminateIcon.
+   */
   classes?: {
     root?: string;
     labelCaptionContainer?: string;
@@ -1874,7 +1938,17 @@ interface RadioContentProps extends Omit<RadioProps$1, "color" | "defaultChecked
   label?: React$1.ReactNode;
   radioProps?: Partial<RadioProps$1>;
   stage?: "checked" | "unchecked";
+  /**
+   * The value a RadioGroup compares against to decide whether this radio is
+   * selected. It also backs the label and caption element ids, so give every
+   * radio a unique one.
+   */
   value?: string;
+  /**
+   * Class names for the internal elements: root, labelCaptionContainer, label,
+   * caption, radioButton, radioCheckedIcon, radioCheckedIconDot, and
+   * radioDefaultIcon.
+   */
   classes?: {
     root?: string;
     labelCaptionContainer?: string;
@@ -1931,6 +2005,11 @@ declare const InputText: import("react").ForwardRefExoticComponent<(Omit<import(
 //#region src/core/InputToggle/style.d.ts
 interface InputToggleExtraProps extends SwitchProps, CommonThemeProps {
   offLabel?: string;
+  /**
+   * Called whenever the user toggles the component, in either direction. It is
+   * given the event alone: unlike MUI's, it is not passed the new checked
+   * state, which is read from the event's target instead.
+   */
   onChange?(e: React.ChangeEvent): void;
   onLabel?: string;
   width?: number;
@@ -1963,63 +2042,72 @@ declare const IntentMessage: (props: IntentMessageProps) => JSX.Element;
 //#region src/core/Legend/Legend.types.d.ts
 interface LegendItemData {
   /**
-   * Name/label for the legend item
+   * The item's label, and the start of its accessible name. Names need not be
+   * unique, since items are addressed by index.
    */
   name: string;
   /**
-   * Value to display (optional)
+   * Shown after the name when `showValues` is on. Numbers are grouped by
+   * locale; a string is printed as given, for a unit or a percentage.
    */
   value?: number | string;
   /**
-   * Color for the legend icon
-   * Can be overridden by the colors prop in LegendProps
-   * Falls back to gray if not provided
+   * The swatch color. The `colors` palette takes priority over it, and without
+   * either the swatch is the theme's grey.
    */
   color?: string;
   /**
-   * Disable the legend item (prevents all events)
+   * Dims the item and stops it responding to hover or clicks.
    * @default false
    */
   disabled?: boolean;
 }
 interface LegendProps extends HTMLAttributes<HTMLDivElement> {
   /**
-   * Array of legend items to display
+   * The items, drawn in order. Their indices are what selection, hover, and the
+   * callbacks refer to.
    */
   items: LegendItemData[];
   /**
-   * Optional array of colors to assign to items. If not provided or if the array
-   * is shorter than items, will use the color from the item or fall back to gray.
+   * A palette applied by index, taking priority over the color on an item.
+   * Entries past the end of the array fall back to the item's color, then to
+   * grey.
    */
   colors?: string[];
   /**
-   * Callback when mouse enters a legend item
+   * Called when the pointer enters an item. The legend already dims its own
+   * swatches, so this is for driving something outside it, such as a highlight
+   * on the chart.
    */
   onItemMouseEnter?: (item: LegendItemData, index: number) => void;
   /**
-   * Callback when mouse leaves a legend item
+   * Called when the pointer leaves an item.
    */
   onItemMouseLeave?: (item: LegendItemData, index: number) => void;
   /**
-   * Callback when a legend item is clicked
+   * Fires on a click, alongside any selection change rather than instead of it.
    */
   onItemClick?: (item: LegendItemData, index: number) => void;
   /**
-   * Whether to show values in the legend
+   * Draws each item's value beside its name. Items without a value are
+   * unaffected.
    * @default false
    */
   showValues?: boolean;
   /**
-   * Array of selected item indices (controlled component)
+   * Indices of the selected items. The legend is controlled: it draws this and
+   * never changes it.
    */
   selectedIndices?: number[];
   /**
-   * Callback when selection changes
-   * @param selectedIndices Array of selected indices
+   * Called with the next selection when an item is clicked, with that index
+   * toggled. Without it, clicking selects nothing.
    */
   onSelectionChange?: (selectedIndices: number[]) => void;
   /**
-   * External control for hovered index (for bidirectional hover with charts)
+   * Highlights an item from outside, for syncing with a chart. It adds to the
+   * legend's own hover rather than replacing it, and `null` reads as no
+   * external highlight.
    */
   hoveredIndex?: number | null;
 }
@@ -2145,6 +2233,10 @@ type ExtraTagProps = ExtraSmallTagProps | ExtraLargeTagProps;
 //#endregion
 //#region src/core/Tag/index.d.ts
 interface SdsTagProps extends Omit<ChipProps$1, "color"> {
+  /**
+   * The tag's text, and its accessible name. It is cut off with an ellipsis
+   * rather than wrapped, so keep it to a word or two.
+   */
   label: string;
   color?: SdsTagColorType;
 }
@@ -2430,6 +2522,21 @@ interface PanelHeaderCloseProps {
 }
 //#endregion
 //#region src/core/Panel/Panel.types.d.ts
+/**
+ * An overlay Panel slides in on MUI's `Slide`, which takes a `container` to
+ * measure that slide against. MUI types the transition slot against the generic
+ * transition interface, which knows nothing of it, and leaves this interface
+ * open for the component that does — so the prop is declared here.
+ *
+ * A Panel rendered into a box rather than the page needs it. Without one the
+ * slide is measured against the window and the panel spends most of its
+ * animation outside the frame it was given.
+ */
+declare module "@mui/material/Drawer" {
+  interface DrawerTransitionSlotPropsOverrides {
+    container?: SlideProps["container"];
+  }
+}
 interface BasicPanelProps extends Omit<DrawerProps, "variant"> {
   sdsType: "basic";
   position?: "left" | "right";
@@ -2582,7 +2689,13 @@ declare const Tab: React$1.ForwardRefExoticComponent<Omit<TabProps, "ref"> & Rea
 //#endregion
 //#region src/core/TagFilter/index.d.ts
 interface SdsTagFilterProps extends Omit<ChipProps$1, "color" | "variant"> {
+  /** The filter's text. Cut off with an ellipsis when there is not room for it. */
   label: string;
+  /**
+   * Runs when the X is clicked or activated, and when Backspace or Delete is
+   * pressed on the tag. Drop the filter from your state here; the component
+   * does not remove itself.
+   */
   onDelete: React$1.EventHandler<any>;
 }
 type TagFilterProps = SdsTagFilterProps;