@splunk/react-ui 5.7.1 → 5.9.0

package/docs-llm/Notifications.md

@@ -0,0 +1,46 @@
+# Notifications
+
+## Overview
+
+# Notifications
+
+Notifications help users understand what happened, what needs attention, and what to do next.
+
+There are two notification components in Splunk UI:
+- [Message](./Message) is used for inline, contextual feedback near the content it refers to.
+- [Message Bar](./MessageBar) is used for page-level or system-level communication.
+
+These components use standardized icons and [`notificationColors` design tokens](../themes/variables#notification-colors) to communicate consistent tone and urgency, so users can quickly understand what to expect.
+
+## Toast Notifications (Deprecated)
+
+Toast notifications are **deprecated** and should not be used for new experiences.
+Even with careful implementation, this pattern still creates significant accessibility and usability barriers.
+
+Use persistent, user-dismissible notifications instead:
+- Use [Message](./Message) for inline, contextual feedback.
+- Use [Message Bar](./MessageBar) for page-level or system-level communication.
+
+### Migration Guide
+
+Review the CRUD Blueprint sections for [Create confirmation](../../DesignSystem/Blueprints/CRUD/Create#3-confirmation), [Update confirmation](../../DesignSystem/Blueprints/CRUD/Update#3-confirmation) and [Delete feedback](../../DesignSystem/Blueprints/CRUD/Delete#3-feedback) for guidance on scenarios where the toast pattern may have previously been used.
+
+Below are suggestions for how to migrate common scenarios:
+
+| Current Toast Pattern | Recommended Alternative | Reason |
+|---|---|---|
+| Success message after form submission | Message Bar at top of page, or inline Message next to changed element | Persistent confirmation is visible to all users regardless of timing |
+| Error feedback | Inline Message in form field, or Message Bar at top | Direct association with the error source helps users understand and fix the problem |
+| Temporary status updates | Message Bar for page-level updates, or Message for task-level updates | Clear scope and persistent visibility ensure all users receive the information |
+| Real-time alerts | Message Bar with optional dismiss action | Ensures users see critical information before it's dismissed |
+
+### Further Reading
+
+Below are additional resources to understand the issues with toast patterns:
+
+- [GitHub Primer: Accessible Notifications and Messages](https://primer.style/accessibility/patterns/accessible-notifications-and-messages/#toasts)
+- [Defining Toast Messages (Adrian Roselli)](https://adrianroselli.com/2020/01/defining-toast-messages.html)
+- [A Toast to an Accessible Toast... to Notifications (Scott O'Hara)](https://www.scottohara.me/blog/2019/07/08/a-toast-to-a11y-toasts.html)
+- [The Problem with Toast Messages and What to Do Instead (Adam Silver)](https://adamsilver.io/blog/the-problem-with-toast-messages-and-what-to-do-instead/)
+
+

package/docs-llm/Number.md

@@ -0,0 +1,298 @@
+# Number
+
+## Overview
+
+
+
+> Image: Illustration of a number component
+
+
+<Message appearance="fill" type="info">
+    <div>All data entry components should be wrapped in a <Link to="ControlGroup">Control Group</Link> to provide a label, error states, and help or error text, ensuring an accessible experience for all users.</div>
+</Message>
+
+
+
+## When to use this component
+- The user only needs to input numeric values.
+- Increasing or decreasing by small values only requires a few clicks.
+
+
+## When to use another component
+- Large value changes are expected.
+- Exact values need to be specified within a wide range.
+- Consider the `Slider` component for inputs that aren’t precise.
+- Consider `Text` or `Text Area` for inputs that are a mix of numbers and text
+- For a predetermined list of values the user can select from, use `Select`.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Number component or something else
+    A(Is the input solely numerical?) -- Yes --- B(Is the number input from a predetermined range?)
+    B -- Yes --- C(Slider)
+    B -- No --- D(Is the number input from a predetermined list?)
+    D -- Yes --- E(Select)
+    D -- No --- F(Number)
+    A -- No --- G(Text/Text Area)
+```
+
+### Check out
+- [Slider][1]
+- [Text][2]
+- [Text Area] [3]
+- [Select][4]
+
+## Behaviors
+### Locale
+Number inputs can automatically convert periods to commas for decimal places based on the user's regional settings.
+
+## Usage
+### Avoid placeholder text
+Placeholder text presents a number of visual and cognitive issues; it is best to avoid using it. Placeholder does not replace a label. [Splunk Style Guide placeholder guidelines][5]
+
+> Image: Image showing a comparison between two number input fields and ways to show placeholders. The correct version on the left shows a number input field with the placeholder text displayed underneath the input field, providing clear contextual information. The incorrect version shows a number input field with the placeholder text inside the input field, which could be mistaken for user input.
+
+
+### Adjust width to support longest values
+Adjust the width to accommodate the anticipated input length, ensuring it is sufficiently wide to support the longest expected values. Avoid extending Number across the entire width of large viewports to maintain usability and readability.
+
+> Image: Image showing a comparison between two number input fields and widths based on content. The correct version of the left shows a number input field with a reasonable width that accommodates the longest expected values, ensuring a clean and efficient design. The incorrect version shows a number input field that is excessively long, wasting space and making the design look unbalanced.
+
+
+
+## Content guidelines
+
+### Use descriptive labels
+The required labels on top of the number input field should be descriptive to ensure users do not type in additional text along with the number. They should still champion brevity and use sentence-case capitalization.
+
+> Image: Image showing a comparison between two number input fields for price. The correct example includes the currency denotated in the label, while the incorrect example requires the user to enter the currency symbol inside the number input field.
+
+
+[1]: ./Slider
+[2]: ./Text
+[3]: ./TextArea
+[4]: ./Select
+[5]: https://docs.splunk.com/Documentation/StyleGuide/drafts/StyleGuide/UIGuidelines#Placeholder_text
+
+## Examples
+
+
+### Controlled
+
+Number requires a value prop and an onChange callback to update the value prop for most use cases. Set value to null.
+
+```typescript
+import React, { Component } from 'react';
+
+import Number, { NumberChangeHandler } from '@splunk/react-ui/Number';
+
+
+class Basic extends Component<object, { value?: number }> {
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            value: undefined, // default empty
+        };
+    }
+
+    handleChange: NumberChangeHandler = (e, { value }) => {
+        this.setState({ value });
+    };
+
+    render() {
+        return <Number value={this.state.value} onChange={this.handleChange} inline />;
+    }
+}
+
+export default Basic;
+```
+
+
+
+### Uncontrolled
+
+Alternately, Number can be uncontrolled and optionally provided a defaultValue. The onChange callback still fires. The value prop cannot be set or updated externally.
+
+```typescript
+import React from 'react';
+
+import Number from '@splunk/react-ui/Number';
+
+
+function Uncontrolled() {
+    return <Number inline />;
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Limits
+
+Number accepts min, max, step, and roundTo props.
+
+```typescript
+import React, { Component } from 'react';
+
+import Number, { NumberChangeHandler } from '@splunk/react-ui/Number';
+
+
+class Limits extends Component<object, { value?: number }> {
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            value: undefined, // default empty
+        };
+    }
+
+    handleChange: NumberChangeHandler = (e, { value }) => {
+        this.setState({ value });
+    };
+
+    render() {
+        return (
+            <Number
+                value={this.state.value}
+                max={10}
+                min={-10}
+                roundTo={1}
+                step={0.1}
+                onChange={this.handleChange}
+                inline
+            />
+        );
+    }
+}
+
+export default Limits;
+```
+
+
+
+### Locale
+
+A locale can be included which may change the decimal separator to a comma.
+
+```typescript
+import React, { Component } from 'react';
+
+import Number, { NumberChangeHandler } from '@splunk/react-ui/Number';
+
+
+class Locale extends Component<object, { value?: number }> {
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            value: 2.4,
+        };
+    }
+
+    handleChange: NumberChangeHandler = (e, { value }) => {
+        this.setState({ value });
+    };
+
+    render() {
+        return (
+            <Number
+                locale="fr-FR"
+                step={0.15}
+                value={this.state.value}
+                onChange={this.handleChange}
+                inline
+            />
+        );
+    }
+}
+
+export default Locale;
+```
+
+
+
+### Error
+
+```typescript
+import React from 'react';
+
+import Number from '@splunk/react-ui/Number';
+
+
+function NumberError() {
+    return <Number error defaultValue={2020} inline />;
+}
+export default NumberError;
+```
+
+
+
+### Disabled
+
+```typescript
+import React from 'react';
+
+import Number from '@splunk/react-ui/Number';
+
+
+function Disabled() {
+    return <Number disabled defaultValue={2020} inline />;
+}
+
+export default Disabled;
+```
+
+
+
+
+## API
+
+
+### Number API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| append | boolean | no |  | Append removes the rounded borders and the border from the right side and moves the increment and decrement buttons to the left. |
+| children | React.ReactNode | no |  |  |
+| defaultValue | number | no |  | Set this property instead of value to make the value uncontrolled. |
+| describedBy | string | no |  | The id of the description. When placed in a ControlGroup, this is automatically set to the ControlGroup's help component. |
+| disabled | boolean | no |  | Determines if the input is editable. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts, and null when it unmounts. |
+| error | boolean | no |  | Highlight the field as having an error. |
+| hideStepButtons | boolean | no |  | Hides the increment and decrement step buttons if true. |
+| inline | boolean | no |  | When false, displays as inline-block with the default width. |
+| inputId | string | no |  | An id for the input, which may be necessary for accessibility, such as for aria attributes. |
+| inputRef | React.Ref<HTMLInputElement> | no |  | A React ref which is set to the text input element when the component mounts, and null when it unmounts. |
+| labelledBy | string | no |  | The id of the label. When placed in a ControlGroup, this is automatically set to the ControlGroup's label. |
+| locale | string | no | 'en-US' | The locale determines the decimal separator. Supported locale formats are: `xx`, `xx-XX`, and `xx_XX`. |
+| max | number | no |  | The largest allowable value. |
+| min | number | no |  | The smallest allowable value. |
+| name | string | no |  | The name is returned with onChange events, which can be used to identify the control when multiple controls share an onChange callback. |
+| onBlur | NumberBlurHandler | no |  | A callback for when the input loses focus. |
+| onChange | NumberChangeHandler | no |  | This is equivalent to onInput which is called on keydown, paste, and so on. If value is set, this callback is required. This must set the value prop to retain the change. |
+| onClick | React.MouseEventHandler<HTMLInputElement> | no |  | A callback for when the input is clicked. This will only trigger when the textbox itself is clicked and will not trigger for other parts of the component such as the step buttons. |
+| onFocus | NumberFocusHandler | no |  | A callback for when the input takes focus. |
+| onKeyDown | React.KeyboardEventHandler<HTMLInputElement> | no |  | A keydown callback can be used to prevent a certain input by utilizing the event argument. |
+| onKeyUp | React.KeyboardEventHandler<HTMLDivElement> | no |  | A keyup callback. |
+| onSelect | React.ReactEventHandler<HTMLInputElement> | no |  | A callback for when the user selects text. |
+| prepend | boolean | no |  | Prepend removes rounded borders from the left side. This cannot be used in combination with append. |
+| roundTo | number | no | 5 | The number of decimal places for rounding. Set to zero to limit input to integers. Negative numbers are supported. For instance, -2 will round to the nearest hundred. |
+| step | number | no | 1 | The amount of increment and decrement applied by the buttons and arrow keys. |
+| value | number | no |  | The contents of the input. Setting this value makes the property controlled. A callback is required. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| NumberBlurHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+| NumberChangeHandler | (     event:         \| React.ChangeEvent<HTMLInputElement>         \| React.KeyboardEvent<HTMLInputElement>         \| React.MouseEvent<HTMLAnchorElement \| HTMLButtonElement \| HTMLSpanElement>,     data: {         name?: string;         value?: number;         reason: 'input' \| 'stepButton';     } ) => void |  |
+| NumberFocusHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+
+
+
+
+