@atlaskit/ds-lib

DSLib

This is an internal package with common functionality used in the Atlassian Design System Team. This package comes with no support and semver guarantees, your app will break if you use this directly!

Installation

yarn add @atlaskit/ds-lib

Utilities

noop()

import noop from '@atlaskit/ds-lib/noop';

noop();

once()

Create a new function that only allows an existing function to be called once.

import once from '@atlaskit/ds-lib/once';

function getGreeting(name: string): string {
	return `Hello ${name}`;
}
const getGreetingOnce = once(getGreeting);

getGreetingOnce('Alex');
// getGreeting called and "Hello Alex" is returned
// "Hello Alex" is put into the cache.
// returns "Hello Alex"

getGreetingOnce('Sam');
// getGreeting is not called
// "Hello Alex" is returned from the cache.

getGreetingOnce('Greg');
// getGreeting is not called
// "Hello Alex" is returned from the cache.

Notes:

• If the onced function throws, then the return value of the function is not cached
• Respects call site context (this) when executing the onced function

warnOnce()

import warnOnce from '@atlaskit/ds-lib/warn-once';

function Component() {
	// Print the warning messagein in the Web console only once per session.
	if (process.env.NODE_ENV !== 'production') {
		warnOnce('This component has been deprecated.');
	}

	return <div>This component has been deprecated</div>;
}

mergeRefs()

import mergeRefs from '@atlaskit/ds-lib/merge-refs';

const Component = forwardRef((props, ref) => {
  const customRef = useRef<HTMLElement | null>(null);

  return (
    // Use the utility function to merge the forwarded ref
    // with the created ref.
    <div ref={mergeRefs[ref, customRef]} />
  );
}

device-check

import { isAppleDevice, isSafari } from '@atlaskit/ds-lib/device-check';
isAppleDevice();
isSafari();

React hooks

useLazyRef()

import useLazyRef from '@atlaskit/ds-lib/use-lazy-ref';

function Component({ onClick }) {
	// Initialize the ref
	const ref = useLazyRef(() => {
		/* Return initial data */
	});

	// Access like a normal ref
	return <button onClick={() => onClick(ref.current)}>Click me!</button>;
}

useControlled()

import useControlled from '@atlaskit/ds-lib/use-controlled';

function ControlledComponent({ value, defaultValue = 0 }) {
	const [uncontrolledState, setUncontrolledState] = useControlled(value, () => defaultValue);
	return <button onClick={() => setUncontrolledState(uncontrolledState + 1)}>Update state</button>;
}

usePreviousValue()

function Component() {
	const [currentValue] = useState(1);
	const previousValue = usePreviousValue(currentValue);

	previousValue; // undefined
	currentValue; // 1

	return null;
}

useStableRef()

function Component({ canShow }: { canShow: () => boolean }) {
	const stableRef = useStableRef({ canShow });

	useEffect(
		() => {
			stableRef.current.canShow();
		},
		// Able to use the last render value of `canShow` without needing
		// to invalidate the effect. Useful for lazy usage of props.
		[],
	);

	return null;
}

useLazyCallback()

import useLazyCallback from '@atlaskit/ds-lib/use-lazy-callback';

function Component() {
	// `callback` always has the same reference.
	const callback = useLazyCallback(() => {
		// Watch out for its stale closure however!
	});

	return null;
}

useStateRef()

import useStateRef from '@atlaskit/ds-lib/use-state-ref';

function Component() {
  const [valueRef, setState] = useStateRef(0);

  // Access the latest value, even inside stale closures.
  console.log(valueRef.current);

  // Update state as you would with use state
  return <div onClick={() => setState(prev => prev + 1)} />;

useScrollbarWidth()

import useScrollbarWidth from '@atlaskit/ds-lib/use-scrollbar-width';

function Component() {
	const scrollbar = useScrollbarWidth();

	return (
		// Use the scrollbar width in your styles/as you wish.
		// The ref should be attached to the scrollable element.
		<div id="container" style={{ padding: scrollbar.width }}>
			<div id="scrollable" ref={scrollbar.ref} />
		</div>
	);
}

useCloseOnEscapePress()

Notice: useCloseOnEscapePress() is deprecated, Please use useCloseOnEscapePress from @atlaskit/layering instead.

import useCloseOnEscapePress from '@atlaskit/ds-lib/use-close-on-escape-press';

// Will callback when escape is pressed
useCloseOnEscapePress({
	onClose: () => {},
	isDisabled: false,
});

useAutoFocus()

import useAutoFocus from '@atlaskit/ds-lib/use-auto-focus';

const elementRef = useRef();
useAutoFocus(elementRef, true);

<div ref={elementRef} />;