@splunk/react-ui 5.0.0 → 5.2.0

package/types/src/Clickable/docs/examples/Disabled.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Disabled
+ * @description Prevents user from activating the component and adds disabled styling. If set to dimmed, the component is able to receive focus. If set to disabled, the component is unable to receive focus (as a result of setting the html disabled attribute). The default behavior when disabled={true} is "dimmed".
+ */
 declare function Disabled(): React.JSX.Element;
 export default Disabled;

package/types/src/Code/Code.d.ts

@@ -20,24 +20,40 @@ interface CodePropsBase {
      * In cases where `language` is not valid `Code` will use this value as the fallback for `language`.
      */
     languageFallback?: CodeSupportedLanguages;
+    /**
+     * Accepts a comma separated list of line numbers or line number ranges to highlight.
+     * example: `2,4-5` will highlight lines 2, 4 and 5.
+     */
+    lineHighlights?: string;
+    /**
+     * Optional start number when showLineNumbers is true.
+     */
+    lineNumberStart?: number;
     /**
      * Displays the indent guideline.
      */
     showIndentGuide?: boolean;
+    /**
+     * Displays line numbers.
+     */
+    showLineNumbers?: boolean;
     /**
      * Inserts code content into the code block.
      */
     value?: string;
 }
 type CodeProps = ComponentProps<CodePropsBase, 'pre'>;
-declare function Code({ elementRef, indentChars, language, languageFallback, showIndentGuide, value, ...otherProps }: CodeProps): React.JSX.Element;
+declare function Code({ elementRef, indentChars, language, languageFallback, lineHighlights, lineNumberStart, showIndentGuide, showLineNumbers, value, ...otherProps }: CodeProps): React.JSX.Element;
 declare namespace Code {
     var propTypes: {
         elementRef: PropTypes.Requireable<object>;
         indentChars: PropTypes.Requireable<number>;
         language: PropTypes.Requireable<string>;
         languageFallback: PropTypes.Requireable<string>;
+        lineHighlights: PropTypes.Requireable<string>;
+        lineNumberStart: PropTypes.Requireable<number>;
         showIndentGuide: PropTypes.Requireable<boolean>;
+        showLineNumbers: PropTypes.Requireable<boolean>;
         value: PropTypes.Requireable<string>;
     };
 }

package/types/src/Code/LineHighlights.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+interface LineHighlightProps {
+    highlight: string;
+    width: number;
+}
+type Ranges = [number, number][];
+declare const parseHighlightLines: (highlight: string) => Ranges;
+declare const getLineNumbersArray: (ranges: Ranges) => number[];
+declare const LineHighlights: React.FC<LineHighlightProps>;
+export default LineHighlights;
+export { parseHighlightLines, getLineNumbersArray };

package/types/src/Code/LineNumbers.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+interface LineNumbersProps {
+    value?: string;
+}
+declare function LineNumbers({ value }: LineNumbersProps): React.JSX.Element;
+export default LineNumbers;

package/types/src/Code/docs/examples/Default.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Default Javascript
+ */
 declare function Default(): React.JSX.Element;
 export default Default;

package/types/src/Code/docs/examples/HideIndent.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Without indent guideline
+ * @description Use the showIndentGuide prop to remove the indent guideline.
+ */
 declare function HideIndent(): React.JSX.Element;
 export default HideIndent;

package/types/src/Code/docs/examples/Language.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Non-Javascript syntax highlighting
+ * @description Use the language prop to apply appropriate syntax highlighting.
+ */
 declare function Language(): React.JSX.Element;
 export default Language;

package/types/src/Code/docs/examples/LineHighlights.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+/**
+ * @name With line highlighting
+ * @description Use the lineHighlights prop to pass the lines that should be highlighted.
+ */
+declare function LineHighlights(): React.JSX.Element;
+export default LineHighlights;

package/types/src/Code/docs/examples/LineNumbers.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+/**
+ * @name With line numbers
+ * @description Use the showLineNumbers prop to show line numbers.
+ */
+declare function LineNumbers(): React.JSX.Element;
+export default LineNumbers;

package/types/src/Code/docs/examples/LineNumbersCustomStart.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+/**
+ * @name With line numbers and custom start
+ * @description Use the lineNumberStart prop to pass a custom number to start from.
+ */
+declare function LineNumbersCustomStart(): React.JSX.Element;
+export default LineNumbersCustomStart;

package/types/src/CollapsiblePanel/docs/examples/Actions.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Actions
+ * @description Adding clickable items in the header.
+ */
 declare function Actions(): React.JSX.Element;
 export default Actions;

package/types/src/CollapsiblePanel/docs/examples/BasicControlled.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Controlled
+ */
 declare function BasicControlled(): React.JSX.Element;
 export default BasicControlled;

package/types/src/CollapsiblePanel/docs/examples/BasicUncontrolled.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Uncontrolled
+ */
 declare function BasicUncontrolled(): React.JSX.Element;
 export default BasicUncontrolled;

package/types/src/CollapsiblePanel/docs/examples/Disabled.d.ts

@@ -1,3 +1,10 @@
 import React from 'react';
+/**
+ * @name Disabled
+ * @description If a CollapsiblePanel is passed disabled the default behavior is to render as "dimmed".
+ * This ensures the panel is still discoverable and can receive focus, but cannot be activated by the user.
+ * Actions that are passed are not disabled within a dimmed panel.
+ * If necessary, a CollapsiblePanel can be completely disabled by setting disabled="disabled".
+ */
 declare function Dimmed(): React.JSX.Element;
 export default Dimmed;

package/types/src/CollapsiblePanel/docs/examples/MultiControlled.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Multiple controlled
+ */
 declare function MultiControlled(): React.JSX.Element;
 export default MultiControlled;

package/types/src/CollapsiblePanel/docs/examples/MultiUncontrolled.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Multiple uncontrolled
+ */
 declare function MultiUncontrolled(): React.JSX.Element;
 export default MultiUncontrolled;

package/types/src/CollapsiblePanel/docs/examples/SingleOpenPanelGroupControlled.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name SingleOpenPanelGroup controlled
+ * @description Expands and collapses only one panel at a time. Note: the open prop on individual Panels is ignored when SingleOpenPanelGroup is used.
+ */
 declare function SingleOpenPanelGroupControlled(): React.JSX.Element;
 export default SingleOpenPanelGroupControlled;

package/types/src/CollapsiblePanel/docs/examples/SingleOpenPanelGroupInset.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name SingleOpenPanelGroup inset
+ * @description Inset adds padding to the Collapsible Panel.
+ */
 declare function SingleOpenPanelGroupInset(): React.JSX.Element;
 export default SingleOpenPanelGroupInset;

package/types/src/CollapsiblePanel/docs/examples/SingleOpenPanelGroupUncontrolled.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name SingleOpenPanelGroup uncontrolled
+ * @description Expands and collapses only one panel at a time. Takes a defaultOpenPanelId prop.
+ */
 declare function SingleOpenPanelGroupUncontrolled(): React.JSX.Element;
 export default SingleOpenPanelGroupUncontrolled;

package/types/src/CollapsiblePanel/docs/examples/Subtle.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Subtle
+ * @description Use appearance="subtle" when you need a Collapsible Panel that has less visual weight.
+ */
 declare function Subtle(): React.JSX.Element;
 export default Subtle;

package/types/src/Color/docs/examples/Controlled.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Controlled
+ */
 declare function Controlled(): React.JSX.Element;
 export default Controlled;

package/types/src/Color/docs/examples/CustomizedPalette.d.ts

@@ -1,2 +1,6 @@
 import React from 'react';
+/**
+ * @name Customized palette
+ * @description Color has defaultPalette exported which can be modified.
+ */
 export default function CustomizedPalette(): React.JSX.Element;

package/types/src/Color/docs/examples/HideInput.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Hide input
+ * @description Color without hex value text input. The input will still appear inside the dropdown when opened.
+ */
 declare function HideInput(): React.JSX.Element;
 export default HideInput;

package/types/src/Color/docs/examples/Null.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name N/A
+ * @description Including N/A in the palette is supported. Put this option at the start or end of the palette. Selecting N/A will return null.
+ */
 declare function Null(): React.JSX.Element;
 export default Null;

package/types/src/Color/docs/examples/ThemeVariables.d.ts

@@ -1,2 +1,6 @@
 import React from 'react';
+/**
+ * @name Theme variables
+ * @description Variables from @splunk/themes can be used to set Color values, such as defaultValue.
+ */
 export default function ThemeVariables(): React.JSX.Element;

package/types/src/Color/docs/examples/Transparent.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Transparent
+ * @description Including transparent in the palette is supported. Put this option at the start or end of the palette.
+ */
 declare function Transparent(): React.JSX.Element;
 export default Transparent;

package/types/src/Color/docs/examples/Uncontrolled.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Uncontrolled
+ */
 declare function Uncontrolled(): React.JSX.Element;
 export default Uncontrolled;

package/types/src/ColumnLayout/docs/examples/AlignItems.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Align items
+ * @description By default, the Columns grow vertically to fill the available space. The values for this property are the same as flexbox's align-items property.
+ */
 declare function AlignItems(): React.JSX.Element;
 export default AlignItems;

package/types/src/ColumnLayout/docs/examples/Basic.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Columns and spans
+ * @description The span property can be set to vary the width of the Columns. The spans must add up to 12. The Columns are colored for this example.
+ */
 declare function Basic(): React.JSX.Element;
 export default Basic;

package/types/src/ColumnLayout/docs/examples/Dividers.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Dividers
+ * @description Column Layout can show different types of dividers.
+ */
 declare function Dividers(): React.JSX.Element;
 export default Dividers;

package/types/src/ColumnLayout/docs/examples/Gutters.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Gutters
+ * @description Column Layout spaces Rows and Columns with gutters, but these can be removed or changed.
+ */
 declare function Gutters(): React.JSX.Element;
 export default Gutters;

package/types/src/ComboBox/docs/examples/Controlled.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Controlled value
+ * @description Typically, the value is controlled.
+ */
 declare function Controlled(): React.JSX.Element;
 export default Controlled;

package/types/src/ComboBox/docs/examples/Fetching.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Fetching
+ * @description You can populate the Options from a server. Here, that behavior is simulated. This simplified example only matches the start of the label. The matchRange prop can be set manually to reflect the matching algorithm used to filter the results. Otherwise matching text is not shown.
+ */
 declare function Fetching(): React.JSX.Element;
 export default Fetching;

package/types/src/ComboBox/docs/examples/Headings.d.ts

@@ -1,2 +1,5 @@
 import React from 'react';
+/**
+ * @name Headings
+ */
 export default function Headings(): React.JSX.Element;

package/types/src/ComboBox/docs/examples/Label.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Label
+ * @description label can be used in addition to value when needed, similar to Select. label will be used for matching and must be a string.
+ */
 declare function Label(): React.JSX.Element;
 export default Label;

package/types/src/ComboBox/docs/examples/Uncontrolled.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Uncontrolled
+ * @description This is a basic example in which data management and filtering are handled internally.
+ */
 declare function Uncontrolled(): React.JSX.Element;
 export default Uncontrolled;

package/types/src/ControlGroup/docs/examples/Basic.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Default appearance
+ * @description By default, the label appears above and the control fills the available width.
+ */
 declare function Basic(): React.JSX.Element;
 export default Basic;

package/types/src/ControlGroup/docs/examples/CustomizedLabelTarget.d.ts

@@ -1,5 +1,9 @@
 import React, { Component } from 'react';
 import { SwitchClickHandler } from '@splunk/react-ui/Switch';
+/**
+ * @name Customized label target
+ * @description Change the focus/activation target that should be linked to the label.
+ */
 declare class CustomizedLabelTarget extends Component<object, {
     values: number[];
 }> {

package/types/src/ControlGroup/docs/examples/Error.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Error
+ * @description Most form controls have their own error property. It is recommended to supply an error message so the user understands what the problem is and how to fix it.
+ */
 declare function Error(): React.JSX.Element;
 export default Error;

package/types/src/ControlGroup/docs/examples/HelpWithErrorText.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Help and error text
+ * @description Help and error text can appear at the same time.
+ */
 declare function HelpWithErrorText(): React.JSX.Element;
 export default HelpWithErrorText;

package/types/src/ControlGroup/docs/examples/HelpWithLinks.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Help text with a link.
+ * @description Help text may contain links or other content.
+ */
 declare function HelpWithLinks(): React.JSX.Element;
 export default HelpWithLinks;

package/types/src/ControlGroup/docs/examples/LabelLeft.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Labels to the left
+ * @description Alternately, labels can be placed to the left of the control.
+ */
 declare function LabelLeft(): React.JSX.Element;
 export default LabelLeft;

package/types/src/ControlGroup/docs/examples/LayoutFill.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Fill layout
+ * @description Fill layout will put space between the controls.
+ */
 declare function LayoutFill(): React.JSX.Element;
 export default LayoutFill;

package/types/src/ControlGroup/docs/examples/LayoutFillJoin.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Fill and join layout
+ * @description The controls will fill the space and will be joined together.
+ */
 declare function LayoutFillJoin(): React.JSX.Element;
 export default LayoutFillJoin;

package/types/src/ControlGroup/docs/examples/LayoutNone.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name No layout
+ * @description Removing the layout will allow controls to control their own size and wrap onto multiple lines. This should usually be used for Date, Number and Switch controls. Setting the control to inline, adjusting spacing, and/or setting a width may be necessary.
+ */
 declare function LayoutNone(): React.JSX.Element;
 export default LayoutNone;

package/types/src/ControlGroup/docs/examples/Required.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Required
+ * @description The required property will set the required attribute on each child component and add an asterisk before the label.
+ */
 declare function Required(): React.JSX.Element;
 export default Required;

package/types/src/Date/Date.d.ts

@@ -17,6 +17,10 @@ type DateFocusHandler = (event: React.FocusEvent<HTMLInputElement>, data: {
     value: string;
 }) => void;
 interface DatePropsBase {
+    /**
+     * Include an "X" button to clear the value.
+     */
+    canClear?: boolean;
     /** Default date to display. Set this instead of value to make the Date uncontrolled. */
     defaultValue?: string;
     /**
@@ -89,9 +93,10 @@ interface DatePropsBaseUncontrolled extends DatePropsBase {
 }
 type DateProps = ComponentProps<DatePropsBaseControlled | DatePropsBaseUncontrolled, 'div'>;
 declare const validateValue: (value: string | undefined) => void;
-declare function Date({ defaultValue, disabled, elementRef, highlightToday, inline, inputOnly, locale, name, onChange, onClick, onFocus, onKeyDown, value: valueProp, ...otherProps }: DateProps): React.JSX.Element;
+declare function Date({ canClear, defaultValue, disabled, elementRef, highlightToday, inline, inputOnly, locale, name, onChange, onClick, onFocus, onKeyDown, value: valueProp, ...otherProps }: DateProps): React.JSX.Element;
 declare namespace Date {
     var propTypes: {
+        canClear: PropTypes.Requireable<boolean>;
         defaultValue: PropTypes.Requireable<string>;
         describedBy: PropTypes.Requireable<string>;
         disabled: PropTypes.Requireable<boolean>;

package/types/src/Date/docs/examples/Basic.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Uncontrolled
+ */
 declare function Basic(): React.JSX.Element;
 export default Basic;

package/types/src/Date/docs/examples/Controlled.d.ts

@@ -1,5 +1,8 @@
 import React, { Component } from 'react';
 import { DateChangeHandler } from '@splunk/react-ui/Date';
+/**
+ * @name Controlled
+ */
 declare class Controlled extends Component<object, {
     value: string;
 }> {

package/types/src/Date/docs/examples/CustomDate.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Locale
+ * @description Setting locale is recommended. Otherwise, en_US will always be used.
+ */
 declare function CustomDate(): React.JSX.Element;
 export default CustomDate;

package/types/src/Date/docs/examples/Disabled.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Disabled
+ */
 declare function Disabled(): React.JSX.Element;
 export default Disabled;

package/types/src/Date/docs/examples/Error.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Error
+ */
 declare function Error(): React.JSX.Element;
 export default Error;

package/types/src/Date/docs/examples/HighlightToday.d.ts

@@ -1,5 +1,9 @@
 import React, { Component } from 'react';
 import { DateChangeHandler } from '@splunk/react-ui/Date';
+/**
+ * @name Highlight today
+ * @description Highlight today's day.
+ */
 declare class HighlightToday extends Component<object, {
     value: string;
 }> {

package/types/src/Date/docs/examples/WithoutCalendar.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Without calendar
+ * @description Example with input only Date.
+ */
 declare function WithoutCalendar(): React.JSX.Element;
 export default WithoutCalendar;

package/types/src/DefinitionList/DefinitionList.d.ts

@@ -5,27 +5,45 @@ import Term from './Term';
 import { ComponentProps } from '../utils/types';
 interface DefinitionListPropsBase {
     children?: React.ReactNode;
+    /**
+     * Defines the width of the `Description`.
+     * Can be set to a specific pixel or string value. If not specified, will fill to take up available space.
+     */
+    descriptionWidth?: string;
     /**
      * A React ref which is set to the DOM element when the component mounts and null when it unmounts.
      */
     elementRef?: React.Ref<HTMLDListElement>;
     /**
-     * Defines the width of an item on the list.
+     * Sets the layout style for the definition list.
+     *
+     * - `fixed`: The `Term` uses a fixed width. The `Description` fills remaining available space.
+     * - `auto`: Both `Term` and `Description` size proportionally based on their container, taking an equal portion of available space.
+     * `fixed` layout is the current default. In the next major version, this prop will default to `auto`.
      */
-    termWidth?: string;
+    layout?: 'fixed' | 'auto';
     /**
      * Sets the character used to separate key-value pair.
      */
-    separatorCharacter?: '.' | string;
+    separatorCharacter?: string;
+    /**
+     * Defines the width of the `Term`.
+     * Can be set to a specific pixel or string value.
+     * The default value is ignored when layout="auto"
+     */
+    termWidth?: string;
 }
 type DefinitionListProps = ComponentProps<DefinitionListPropsBase, 'dl'>;
-declare function DefinitionList({ children, elementRef, termWidth, separatorCharacter, ...otherProps }: DefinitionListProps): React.JSX.Element;
+declare function DefinitionList({ children, descriptionWidth, elementRef, layout, // TODO (SUI-8077): Change the default layout to `auto`.
+separatorCharacter, termWidth, ...otherProps }: DefinitionListProps): React.JSX.Element;
 declare namespace DefinitionList {
     var propTypes: {
         children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        descriptionWidth: PropTypes.Requireable<string>;
         elementRef: PropTypes.Requireable<object>;
+        layout: PropTypes.Requireable<string>;
+        separatorCharacter: PropTypes.Requireable<string>;
         termWidth: PropTypes.Requireable<string>;
-        separatorCharacter: PropTypes.Requireable<string | PropTypes.Requireable<string>>;
     };
     var Description: typeof import("./Description").default;
     var Term: typeof import("./Term").default;

package/types/src/DefinitionList/DefinitionListContext.d.ts

@@ -1,4 +1,6 @@
 interface DefinitionListContextValue {
+    descriptionWidth?: string;
+    layout: 'fixed' | 'auto';
     separatorCharacter?: '.' | string;
     termWidth?: string;
 }

package/types/src/DefinitionList/docs/examples/Basic.d.ts

@@ -1,3 +1,6 @@
 import React from 'react';
+/**
+ * @name Basic
+ */
 declare function Basic(): React.JSX.Element;
 export default Basic;

package/types/src/DefinitionList/docs/examples/CustomizedWidths.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+/**
+ * @name Customized widths
+ * @description The term widths and description widths can be set to a specific pixel or string value.
+ */
+declare function CustomizedWidths(): React.JSX.Element;
+export default CustomizedWidths;

package/types/src/DefinitionList/docs/examples/EmptyDescription.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name Empty description
+ * @description Use a character and screen reader content to indicate when a description does not have a value. When there is not a better choice based on the context, use a hyphen to indicate the missing value with corresponding screen reader content.
+ */
 declare function EmptyDescription(): React.JSX.Element;
 export default EmptyDescription;

package/types/src/DefinitionList/docs/examples/WithSeparator.d.ts

@@ -1,3 +1,7 @@
 import React from 'react';
+/**
+ * @name With separator
+ * @description Sets the character used to separate key-value pair
+ */
 declare function WithSeparator(): React.JSX.Element;
 export default WithSeparator;