@splunk/react-ui 5.7.0 → 5.8.0

package/docs-llm/Screen Reader Content.md

@@ -0,0 +1,73 @@
+# Screen Reader Content
+
+## Examples
+
+
+### Basic
+
+Click 'Show Code' to view the hidden Screen Reader Content.
+
+```typescript
+import React from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import ScreenReaderContent from '@splunk/react-ui/ScreenReaderContent';
+
+
+function Basic() {
+    return (
+        <Button>
+            Learn more <ScreenReaderContent>about advanced search options</ScreenReaderContent>
+        </Button>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Skip-link
+
+```typescript
+import React from 'react';
+
+import styled from 'styled-components';
+
+import Link from '@splunk/react-ui/Link';
+import { mixins } from '@splunk/themes';
+
+const StyledLink = styled(Link)`
+    ${mixins.skipLink()}
+`;
+
+
+function SkipLink() {
+    return <StyledLink to="#main">Skip navigation</StyledLink>;
+}
+
+export default SkipLink;
+```
+
+
+
+
+## API
+
+
+### ScreenReaderContent API
+
+The screen reader text is used to wrap content that
+is only accessible through screen readers.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | yes |  |  |
+| elementRef | React.Ref<HTMLSpanElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+
+
+
+
+

package/docs-llm/Scroll Container Context.md

@@ -0,0 +1,155 @@
+# Scroll Container Context
+
+## Examples
+
+
+### Provider
+
+A Dropdown inside a custom Scroll Container. The Dropdown (when open) scrolls with the custom container, not the window.
+
+```typescript
+import React, { useCallback, useState } from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import Dropdown from '@splunk/react-ui/Dropdown';
+import P from '@splunk/react-ui/Paragraph';
+import { ScrollContainerProvider } from '@splunk/react-ui/ScrollContainerContext';
+
+
+function Provider() {
+    const [scrollContainer, setScrollContainer] = useState<HTMLDivElement | null>();
+    const scrollContainerRef = useCallback((el: HTMLDivElement | null) => {
+        setScrollContainer(el);
+    }, []);
+
+    const toggle = <Button label="Open dropdown in custom container" isMenu />;
+    return (
+        <div
+            ref={scrollContainerRef}
+            style={{
+                border: '1px dashed #ccc',
+                height: '100px',
+                width: '500px',
+                margin: '20px 20px 0px 0px',
+                padding: '30px 20px 10px 20px',
+                overflow: 'scroll',
+            }}
+        >
+            <ScrollContainerProvider value={scrollContainer}>
+                <Dropdown retainFocus toggle={toggle}>
+                    <P style={{ padding: 20, maxWidth: 300 }}>
+                        This dropdown is inside a custom scroll container.
+                    </P>
+                </Dropdown>
+                <P style={{ marginTop: 20 }}>Scroll to see more content.</P>
+                <P>Additional content for demonstration.</P>
+            </ScrollContainerProvider>
+        </div>
+    );
+}
+
+export default Provider;
+```
+
+
+
+### measureProgress
+
+```typescript
+import React, { useCallback, useContext, useEffect, useState } from 'react';
+
+import P from '@splunk/react-ui/Paragraph';
+import {
+    ScrollContainerContext,
+    ScrollContainerProvider,
+} from '@splunk/react-ui/ScrollContainerContext';
+
+type Container = Document | HTMLElement | Window;
+
+function measureProgress(scrollContainer: Container): number {
+    const measureEl =
+        scrollContainer instanceof HTMLElement ? scrollContainer : document.documentElement;
+    const height = measureEl.scrollHeight - measureEl.clientHeight;
+    const elasticProgress = height === 0 ? 0 : measureEl.scrollTop / height;
+    const progress = Math.min(Math.max(elasticProgress, 0), 1);
+    return Math.round(progress * 100);
+}
+
+
+function ScrollProgress() {
+    const scrollContainer: Document | HTMLElement | Window =
+        useContext(ScrollContainerContext) || window;
+    const [progress, setProgress] = useState(0);
+
+    const updateProgress = useCallback(() => {
+        setProgress(measureProgress(scrollContainer));
+    }, [scrollContainer]);
+
+    useEffect(updateProgress, [scrollContainer, updateProgress]);
+
+    useEffect(() => {
+        scrollContainer.addEventListener('scroll', updateProgress);
+
+        return () => {
+            scrollContainer.removeEventListener('scroll', updateProgress);
+        };
+    }, [scrollContainer, updateProgress]);
+
+    return <P>Scroll progress: {progress}%</P>;
+}
+
+function Consumer() {
+    const [scrollContainer, setScrollContainer] = useState<HTMLDivElement | null>();
+    const scrollContainerRef = useCallback((el: HTMLDivElement | null) => {
+        setScrollContainer(el);
+    }, []);
+
+    return (
+        <>
+            <ScrollContainerProvider value={scrollContainer}>
+                <ScrollProgress />
+            </ScrollContainerProvider>
+            <div
+                ref={scrollContainerRef}
+                style={{
+                    border: '1px dashed #ccc',
+                    height: '100px',
+                    width: '500px',
+                    margin: '20px 20px 0px 0px',
+                    padding: '30px 20px 10px 20px',
+                    overflow: 'scroll',
+                }}
+            >
+                <ScrollContainerProvider value={scrollContainer}>
+                    <P>This is the first paragraph in the scroll container.</P>
+                    <P>This is the second paragraph in the scroll container.</P>
+                    <P>This is the third paragraph in the scroll container.</P>
+                    <P>This is the fourth paragraph in the scroll container.</P>
+                    <P>This is the fifth paragraph in the scroll container.</P>
+                </ScrollContainerProvider>
+            </div>
+        </>
+    );
+}
+
+export default Consumer;
+```
+
+
+
+
+## API
+
+import React from 'react';
+
+import UtilAPI from '@splunk/react-docs/UtilAPI';
+
+import docs from '!!@splunk/jsdoc-loader!@splunk/react-ui/ScrollContainerContext/ScrollContainerContext';
+
+function DevelopSection() {
+    return [<UtilAPI key="ScrollContainerContext" docs={docs} />];
+}
+
+export default DevelopSection;
+
+

package/docs-llm/Scroll.md

@@ -0,0 +1,152 @@
+# Scroll
+
+## Examples
+
+
+### Controlled
+
+The controlled method must be used to set the Scroll position.
+
+```typescript
+import React, { Component } from 'react';
+
+import { times } from 'lodash';
+
+import Button from '@splunk/react-ui/Button';
+import Layout from '@splunk/react-ui/Layout';
+import P from '@splunk/react-ui/Paragraph';
+import Scroll from '@splunk/react-ui/Scroll';
+
+
+class Basic extends Component<object, { top?: number }> {
+    private scrollEl: Element | null = null;
+
+    constructor(props: object) {
+        super(props);
+        this.state = {};
+    }
+
+    handleClickDown = () => {
+        if (this.scrollEl) {
+            this.setState({
+                top: this.scrollEl.scrollTop + 200,
+            });
+        }
+    };
+
+    handleClickUp = () => {
+        if (this.scrollEl) {
+            this.setState({
+                top: this.scrollEl.scrollTop - 200,
+            });
+        }
+    };
+
+    handleScrollComplete = () => {
+        this.setState({
+            top: undefined,
+        });
+    };
+
+    handleScrollElMount = (el: Element | null) => {
+        this.scrollEl = el;
+    };
+
+    render() {
+        const styles = {
+            border: '1px solid #ccc',
+            height: '400px',
+            width: '400px',
+            marginTop: '20px',
+        };
+
+        return (
+            <div>
+                <Layout>
+                    <Button label="Scroll down" onClick={this.handleClickDown} />
+                    <Button label="Scroll up" onClick={this.handleClickUp} />
+                </Layout>
+
+                <Scroll
+                    elementRef={this.handleScrollElMount}
+                    style={styles}
+                    top={this.state.top}
+                    onScrollComplete={this.handleScrollComplete}
+                    tagName="article"
+                >
+                    {times(15, (i) => (
+                        <P key={i}>
+                            This is a scrollable paragraph. Add more content to see the scroll
+                            effect.
+                        </P>
+                    ))}
+                </Scroll>
+            </div>
+        );
+    }
+}
+
+export default Basic;
+```
+
+
+
+### Uncontrolled with Scroll Propagation
+
+The uncontrolled approach is useful for stopping propagation of the Scroll. Here, scrolling with the mouse wheel over the container does not scroll the window.
+
+```typescript
+import React from 'react';
+
+import { times } from 'lodash';
+
+import P from '@splunk/react-ui/Paragraph';
+import Scroll from '@splunk/react-ui/Scroll';
+
+
+function Uncontrolled() {
+    const styles = {
+        border: '1px solid #ccc',
+        height: '400px',
+        width: '400px',
+    };
+
+    return (
+        <Scroll stopScrollPropagation style={styles}>
+            {times(15, (i) => (
+                <P key={i}>
+                    This is a scrollable paragraph. Add more content to see the scroll effect.
+                </P>
+            ))}
+        </Scroll>
+    );
+}
+
+export default Uncontrolled;
+```
+
+
+
+
+## API
+
+
+### Scroll API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| elementRef | React.Ref<Element> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| left | number | no |  | Set this to animate to a specific scroll position. Remove this property onScrollComplete to restore control to the user. |
+| onScroll | React.UIEventHandler<Element> | no |  | A callback for when the scroll position changes. |
+| onScrollComplete | () => void | no |  | A callback for when an animated update completes. Ensure the animate prop is set back to false and restore control to the user. |
+| stopScrollPropagation | boolean \| 'window' | no |  | Prevent mouseWheel events from scrolling the page or other containers. 'window' only stops the window from scrolling by removing the scroll bars, which has better performance but can affect layout. |
+| tagName | unknown | no | 'div' |  |
+| top | number | no |  | Set this to animate to a specific scroll position. Remove this property onScrollComplete to restore control to the user. |
+
+
+
+
+