@splunk/react-ui 5.7.1 → 5.8.0

package/docs-llm/Date.md

@@ -0,0 +1,270 @@
+# Date
+
+## Overview
+
+
+
+> Image: Illustration of a Date 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
+- When collecting date information from users like birthdays, anniversaries, or events, use a `Date` input component for a user-friendly, consistent experience.
+- When capturing time-sensitive data such as deadlines or bookings, use a `Date` input for consistent, accurate entry.
+- When performing calculations based on dates, such as determining the difference between two dates, `Date` will ensure a consistent format to be processed.
+
+
+
+## When to use another component
+- When the information being collected is not related to dates, use a different type of input component, such as a `Text` input or a `Dropdown` menu.
+- When the date is only being displayed and not collected, use plain text instead.
+- When non-standard date formats are required a custom date input component may be needed.
+
+### Check out
+- [Text][1]
+- [Dropdown][2]
+- [Modal] [3]
+
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Date component or something else
+    A(Is the information an input?) -- Yes --- B(Is the input a date?)
+    B -- Yes --- C(Date)
+    B -- No --- D(Text, Number, other inputs)
+    A -- No --- E(Paragraph)
+```
+
+## Usage
+### Keep input field an appropriate width
+The `Date` input field is fixed width. Avoid resizing the field to prevent creating unnecessary space.
+
+
+
+## Content
+
+### Set locale for regional differences
+Utilize the locale property to specify the language and adjust the date formatting to align with the country’s conventions. The default setting is U.S. English.
+
+### Labels
+Keep labels brief and descriptive, using sentence-style capitalization.
+> Image: The image shows a do-and-don’t comparison between two input field labels. The left image shows a date input field labeled 
+
+
+[1]: ./Text
+[2]: ./Dropdown
+[3]: ./Modal
+
+## Examples
+
+
+### Controlled
+
+```typescript
+import React, { Component } from 'react';
+
+import Date, { DateChangeHandler } from '@splunk/react-ui/Date';
+
+
+class Controlled extends Component<object, { value: string }> {
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            value: '1988-08-24',
+        };
+    }
+
+    handleChange: DateChangeHandler = (e, { value }) => {
+        this.setState({ value });
+    };
+
+    render() {
+        return <Date value={this.state.value} onChange={this.handleChange} />;
+    }
+}
+
+export default Controlled;
+```
+
+
+
+### Uncontrolled
+
+```typescript
+import React from 'react';
+
+import Date from '@splunk/react-ui/Date';
+
+
+function Basic() {
+    return <Date />;
+}
+
+export default Basic;
+```
+
+
+
+### Locale
+
+Setting locale is recommended. Otherwise, en_US will always be used.
+
+```typescript
+import React from 'react';
+
+import Date from '@splunk/react-ui/Date';
+
+
+function CustomDate() {
+    return <Date defaultValue="1988-08-24" locale="ko-KR" />;
+}
+
+export default CustomDate;
+```
+
+
+
+### Highlight Today
+
+Highlight today's day.
+
+```typescript
+import React, { Component } from 'react';
+
+import moment from 'moment';
+
+import Date, { DateChangeHandler } from '@splunk/react-ui/Date';
+
+
+class HighlightToday extends Component<object, { value: string }> {
+    constructor(props: object) {
+        super(props);
+
+        const today = moment().format('YYYY-MM-DD');
+        const lastDayOfMonth = moment().endOf('month').format('YYYY-MM-DD');
+        const firstDayOfMonth = moment().startOf('month').format('YYYY-MM-DD');
+        const tomorrow = moment().add(1, 'day').format('YYYY-MM-DD');
+
+        const selectedDay = today === lastDayOfMonth ? firstDayOfMonth : tomorrow;
+
+        this.state = {
+            value: selectedDay,
+        };
+    }
+
+    handleChange: DateChangeHandler = (e, { value }) => {
+        this.setState({ value });
+    };
+
+    render() {
+        return <Date highlightToday value={this.state.value} onChange={this.handleChange} />;
+    }
+}
+
+export default HighlightToday;
+```
+
+
+
+### Disabled
+
+```typescript
+import React from 'react';
+
+import Date from '@splunk/react-ui/Date';
+
+
+function Disabled() {
+    return <Date disabled defaultValue="1988-08-24" />;
+}
+
+export default Disabled;
+```
+
+
+
+### Error
+
+```typescript
+import React from 'react';
+
+import Date from '@splunk/react-ui/Date';
+
+
+function Error() {
+    return <Date defaultValue="1988-08-24" error />;
+}
+
+export default Error;
+```
+
+
+
+### Without Calendar
+
+Example with input only Date.
+
+```typescript
+import React from 'react';
+
+import Date from '@splunk/react-ui/Date';
+
+
+function WithoutCalendar() {
+    return <Date defaultValue="2022-08-08" inputOnly />;
+}
+
+export default WithoutCalendar;
+```
+
+
+
+
+## API
+
+
+### Date API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| append | boolean | no |  | Append removes rounded borders and the border from the right side. |
+| canClear | boolean | no |  | Include an "X" button to clear the value. |
+| defaultValue | string | no |  | Default date to display. Set this instead of value to make the Date uncontrolled. |
+| describedBy | string | no |  | The id of the description. When placed in a ControlGroup, this automatically set to the ControlGroup's help component. |
+| disabled | boolean | no |  | Add a disabled attribute and prevent clicking. |
+| 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. The border and text will turn red. |
+| highlightToday | boolean | no |  | Highlight today's day. |
+| inline | boolean | no | true | When false, display 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. |
+| inputOnly | boolean | no |  | Whether or not to display the calendar menu. |
+| labelledBy | string | no |  | The id of the label. When placed in a ControlGroup, this automatically set to the ControlGroup's label. |
+| locale | string | no | 'en_US' | Locale set by language and localization specifiers. |
+| 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 | DateBlurHandler | no |  | A callback for when the input loses focus. |
+| onChange | DateChangeHandler | no |  | Return event and data object with date string (in YYYY-MM-DD format) when a date is selected. |
+| onClick | React.MouseEventHandler<HTMLInputElement> | no |  |  |
+| onFocus | DateFocusHandler | no |  |  |
+| onKeyDown | React.KeyboardEventHandler<HTMLInputElement> | no |  |  |
+| prepend | boolean | no |  | Prepend removes rounded borders from the left side. |
+| value | string | no |  | Setting this value makes the property controlled. An onChange callback is required.  The value must be "" or in the format 'YYYY-MM-DD'. To simplify creation of these strings, Date provides a Moment.js formatting string: ``` moment().format(Date.momentFormat); ``` |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| DateBlurHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+| DateChangeHandler | (     event:         \| React.MouseEvent<HTMLButtonElement \| HTMLDivElement>         \| React.KeyboardEvent<HTMLInputElement>         \| React.KeyboardEvent<HTMLDivElement>         \| KeyboardEvent         \| MouseEvent         \| TouchEvent         \| undefined,     data: {         name?: string;         value: string;     } ) => void |  |
+| DateFocusHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+
+
+
+
+

package/docs-llm/Definition List.md

@@ -0,0 +1,278 @@
+# Definition List
+
+## Overview
+
+
+> Image: Illustration of a Definition List component.
+
+
+## When to use this component
+- The information involves a clear relationship, with pairs where each "key" has a specific "value" associated with it. This is ideal for scenarios where users need to quickly understand a direct relationship or attribute.
+- If the user needs to see a comparison or detailed information about specific attributes, a definition list is easy to scan.
+
+## When to use another component
+- Use a List when dealing with multiple similar items, sequential or hierarchical data, or when the data is not paired.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the DefinitionList component or something else
+    A("Does your data have a clear relationship with a key (label) and value(s)?") -- Yes --- B(Definition List)
+    A -- No --- C(List or Paragraph)
+```
+
+### Check out
+- [List][1]
+- [Paragraph][2]
+
+## Usage
+
+### Clear relationships
+Definition List is best at displaying a group of independent key-value pairs. There shouldn’t be a specific relationship between the pairs, such as sequential or hierarchical data.
+
+> Image: Two examples of a Definition List with three key-value pairs. In the first example with heart eyes emoji, the key value pairs are 
+
+
+### Key-value groups
+Key-value relationships do not have to be one-to-one. There can be multiple values for one key label.
+
+> Image: Two examples of Definition List that illustrates key-value groups. In the first example with heart eyes emoji, there is a Definition List with the key-value pair, 
+
+
+### Wrap long values
+Long strings can be wrapped to the next line to ensure users can see the whole content.
+
+> Image: Two examples of Definition list with three key-value pairs. In both examples the Definition List has the key-value pairs, 
+
+
+## Content
+- Follow writing best practices for Definitions Lists outlined in the [Splunk Style Guide][3]
+
+### Mutually exclusive labels
+Each key and value label should be distinct so that users can clearly differentiate between them.
+
+> Image: Two examples that illustrate mutually exclusive labels. In the first example with heart eyes emoji, there is a Definition List with three key-value pairs, 
+
+
+### Be concise
+Use sentence-style capitalization and keep labels concise.
+
+> Image: Two examples of a Definition List with three key-value pairs. In the first example with heart eyes emoji, the key labels are 
+
+
+[1]: ./List
+[2]: ./Paragraph
+[3]: https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Definitionlists
+
+## Examples
+
+
+### Basic
+
+```typescript
+import React from 'react';
+
+import DL, { Term as DT, Description as DD } from '@splunk/react-ui/DefinitionList';
+
+
+function Basic() {
+    return (
+        <DL layout="auto">
+            <DT>Name</DT>
+            <DD>Splunk</DD>
+            <DT>Type</DT>
+            <DD>Public</DD>
+            <DT>Founders</DT>
+            <DD>Michael Baum</DD>
+            <DD>Rob Das</DD>
+            <DD>Erik Swan</DD>
+            <DT>Headquarters</DT>
+            <DD>San Francisco, CA</DD>
+        </DL>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Stacked layout
+
+```typescript
+import React from 'react';
+
+import DL from '@splunk/react-ui/DefinitionList';
+
+
+function StackedLayout() {
+    return (
+        <DL layout="stacked">
+            <DL.Term>Term</DL.Term>
+            <DL.Description>Description</DL.Description>
+            <DL.Term>This is stacked layout.</DL.Term>
+            <DL.Description>Stacked layout places each term above its description.</DL.Description>
+        </DL>
+    );
+}
+
+export default StackedLayout;
+```
+
+
+
+### Customized widths
+
+The term widths and description widths can be set to a specific pixel or string value.
+
+```typescript
+import React from 'react';
+
+import DL from '@splunk/react-ui/DefinitionList';
+
+
+function CustomizedWidths() {
+    return (
+        <DL termWidth="200px" descriptionWidth="100px">
+            <DL.Term>Location</DL.Term>
+            <DL.Description>San Jose, CA</DL.Description>
+            <DL.Term>IP Address</DL.Term>
+            <DL.Description>123.456.0.0</DL.Description>
+            <DL.Term>Device</DL.Term>
+            <DL.Description>MacBook Pro (13-inch, 2020)</DL.Description>
+        </DL>
+    );
+}
+
+export default CustomizedWidths;
+```
+
+
+
+### With separator
+
+Sets the character used to separate key-value pair
+
+```typescript
+import React from 'react';
+
+import DefinitionList, { Term, Description } from '@splunk/react-ui/DefinitionList';
+
+
+function WithSeparator() {
+    return (
+        <DefinitionList layout="auto" separatorCharacter="_">
+            <Term>
+                This is an example of auto layout with a separator. The term content is
+                intentionally long to demonstrate how multi-line terms appear with a separator.
+            </Term>
+            <Description>Description</Description>
+            <Term>Name</Term>
+            <Description>Jon Doe</Description>
+            <Term>Role</Term>
+            <Description>Administrator</Description>
+            <Term>Last login</Term>
+            <Description>Aug 13 2019 5:13 PM</Description>
+            <Term>Location</Term>
+            <Description>Bend, OR</Description>
+        </DefinitionList>
+    );
+}
+
+export default WithSeparator;
+```
+
+
+
+### Empty 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.
+
+```typescript
+import React from 'react';
+
+import DL from '@splunk/react-ui/DefinitionList';
+import ScreenReaderContent from '@splunk/react-ui/ScreenReaderContent';
+
+
+function EmptyDescription() {
+    return (
+        <DL>
+            <DL.Term>Name</DL.Term>
+            <DL.Description>New user</DL.Description>
+            <DL.Term>Last login</DL.Term>
+            <DL.Description>
+                <span aria-hidden="true">-</span>
+                <ScreenReaderContent>No login</ScreenReaderContent>
+            </DL.Description>
+            <DL.Term>Role</DL.Term>
+            <DL.Description>Guest</DL.Description>
+        </DL>
+    );
+}
+
+export default EmptyDescription;
+```
+
+
+
+
+## API
+
+
+### DefinitionList API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| descriptionWidth | string | no |  | 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. This prop is ignored when `layout="stacked"`. |
+| elementRef | React.Ref<HTMLDListElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| layout | 'fixed' \| 'auto' \| 'stacked' | no | 'fixed' | 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. - `stacked`: `Term` is displayed above the `Description`. Custom `termWidth` and `descriptionWidth` are ignored. Both `Term` and `Description` size proportionally.  `fixed` layout is the current default. In the next major version, this prop will default to `auto`. |
+| separatorCharacter | string | no |  | Sets the character used to separate key-value pair. Only supported in `layout="fixed"` and `layout="auto"`. Will not be rendered in `layout="stacked"`. |
+| termWidth | string | no | '120px' | Defines the width of the `Term`. Can be set to a specific pixel or string value. The default value is ignored when `layout="auto"`. This prop is ignored when `layout="stacked"`. |
+
+
+
+### DefinitionList.Term API
+
+Container component for a `DefinitionList` term.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | yes |  |  |
+| elementRef | React.Ref<HTMLElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+
+
+
+### DefinitionList.Description API
+
+Container component for a `DefinitionList` description.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | yes |  |  |
+| elementRef | React.Ref<HTMLElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+
+
+
+
+
+## Accessibility
+
+## Visual Design
+- Color contrast ratio **MUST** be [SC 1.4.3][1]:
+    - &gt= 3:1 for icon and caret (&gt) against page background 
+    - &gt= 4:5:1 for functional text against page background
+
+## Implementation
+- **MUST** use HTML semantics: `<ul>` or `<ol>` with `<li>` child elements, or `<dl>` with `<dt>` and `<dd>` child elements [SC 1.3.1][2]
+
+[1]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+[2]: https://www.w3.org/TR/WCAG21/#info-and-relationships
+
+