@atlaskit/focus-ring 0.2.7 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @atlaskit/focus-ring
 
+## 1.0.0
+
+### Major Changes
+
+- [`3e1a93c6b67`](https://bitbucket.org/atlassian/atlassian-frontend/commits/3e1a93c6b67) - Releases FocusRing to v1.
+
+### Minor Changes
+
+- [`63b8679585b`](https://bitbucket.org/atlassian/atlassian-frontend/commits/63b8679585b) - Adds an additional prop `focus` to the `FocusRing` to allow the component to also be controlled. This prop is designed to be used in conjunction with a complementary hook; `useFocusRing`.
+
 ## 0.2.7
 
 ### Patch Changes

package/dist/cjs/focus-ring.js

@@ -13,18 +13,18 @@ var _colors = require("@atlaskit/theme/colors");
 
 /** @jsx jsx */
 var BORDER_WIDTH = 2;
-var focusOutsideStyles = {
-  outlineOffset: BORDER_WIDTH,
-  outline: "".concat(BORDER_WIDTH, "px solid ").concat("var(--ds-border-focused, ".concat(_colors.B100, ")"))
-};
+var baseFocusOutsideStyles = (0, _core.css)({
+  outline: "".concat(BORDER_WIDTH, "px solid ").concat("var(--ds-border-focused, ".concat(_colors.B100, ")")),
+  outlineOffset: BORDER_WIDTH
+});
 var baseInsetStyles = (0, _core.css)({
   boxShadow: "inset 0px 0px 0px ".concat(BORDER_WIDTH, "px ").concat("var(--ds-border-focused, ".concat(_colors.B100, ")")),
   outline: 'none'
 });
 var focusRingStyles = (0, _core.css)({
-  '&:focus-visible': focusOutsideStyles,
+  '&:focus-visible': baseFocusOutsideStyles,
   '@supports not selector(*:focus-visible)': {
-    '&:focus': focusOutsideStyles
+    '&:focus': baseFocusOutsideStyles
   },
   '@media screen and (forced-colors: active), screen and (-ms-high-contrast: active)': {
     '&:focus-visible': {
@@ -65,16 +65,21 @@ var insetFocusRingStyles = (0, _core.css)({
 
 var FocusRing = function FocusRing(_ref) {
   var children = _ref.children,
-      isInset = _ref.isInset;
+      isInset = _ref.isInset,
+      focus = _ref.focus;
+  var controlledStyles = isInset ? baseInsetStyles : baseFocusOutsideStyles;
+  var uncontrolledStyles = isInset ? insetFocusRingStyles : focusRingStyles;
+  var focusCls = typeof focus === 'undefined' ? uncontrolledStyles : focus === 'on' && controlledStyles;
   return (0, _core.jsx)(_core.ClassNames, null, function (_ref2) {
     var css = _ref2.css,
         cx = _ref2.cx;
-    return _react.Children.only(
+    return _react.Children.only( // This may look unwieldy but means we skip applying styles / cloning if no className is applicable
+    focusCls ?
     /*#__PURE__*/
     // eslint-disable-next-line @repo/internal/react/no-clone-element
     (0, _react.cloneElement)(children, {
-      className: cx([css(isInset ? insetFocusRingStyles : focusRingStyles), children && children.props.className])
-    }));
+      className: cx([css(focusCls), children.props.className])
+    }) : children);
   });
 };
 

package/dist/cjs/index.js

@@ -11,5 +11,13 @@ Object.defineProperty(exports, "default", {
     return _focusRing.default;
   }
 });
+Object.defineProperty(exports, "useFocusRing", {
+  enumerable: true,
+  get: function get() {
+    return _useFocusRing.default;
+  }
+});
+
+var _focusRing = _interopRequireDefault(require("./focus-ring"));
 
-var _focusRing = _interopRequireDefault(require("./focus-ring"));
+var _useFocusRing = _interopRequireDefault(require("./use-focus-ring"));

package/dist/cjs/use-focus-ring.js

@@ -0,0 +1,65 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+
+var _react = require("react");
+
+/**
+ * __Use focus ring__
+ *
+ * The `useFocusRing` hook is designed to manage focus for the `FocusRing` in cases where the `FocusRing`'s visual application
+ * and the element that takes focus, differ. See the `focus` prop of `FocusRing` for more information.
+ *
+ * @example
+ * ```jsx
+ * import VisuallyHidden from '@atlaskit/visuall-hidden';
+ * import FocusRing, { useFocusRing } from '@atlaskit/focus-ring';
+ *
+ * const InteractiveComponent = () => {
+ *  const { focusState, focusProps } = useFocusRing();
+ *
+ *  return (
+ *    <div>
+ *      <VisuallHidden>
+ *        <input {...focusProps} />
+ *      </VisuallyHidden>
+ *      <FocusRing focus={focusState}>
+ *        <div role="button">Hello</div>
+ *      </FocusRing>
+ *    </div>
+ *  );
+ *
+ * }
+ * ```
+ */
+var useFocusRing = function useFocusRing() {
+  var initialState = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'off';
+
+  var _useState = (0, _react.useState)(initialState),
+      _useState2 = (0, _slicedToArray2.default)(_useState, 2),
+      focusState = _useState2[0],
+      setFocusState = _useState2[1];
+
+  var focusProps = (0, _react.useRef)({
+    onFocus: function onFocus() {
+      return setFocusState('on');
+    },
+    onBlur: function onBlur() {
+      return setFocusState('off');
+    }
+  });
+  return {
+    focusState: focusState,
+    focusProps: focusProps.current
+  };
+};
+
+var _default = useFocusRing;
+exports.default = _default;

package/dist/cjs/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/focus-ring",
-	"version": "0.2.7",
+	"version": "1.0.0",
 	"sideEffects": false
 }

package/dist/es2019/focus-ring.js

@@ -3,18 +3,18 @@ import { Children, cloneElement } from 'react';
 import { ClassNames, css, jsx } from '@emotion/core';
 import { B100 } from '@atlaskit/theme/colors';
 const BORDER_WIDTH = 2;
-const focusOutsideStyles = {
-  outlineOffset: BORDER_WIDTH,
-  outline: `${BORDER_WIDTH}px solid ${`var(--ds-border-focused, ${B100})`}`
-};
+const baseFocusOutsideStyles = css({
+  outline: `${BORDER_WIDTH}px solid ${`var(--ds-border-focused, ${B100})`}`,
+  outlineOffset: BORDER_WIDTH
+});
 const baseInsetStyles = css({
   boxShadow: `inset 0px 0px 0px ${BORDER_WIDTH}px ${`var(--ds-border-focused, ${B100})`}`,
   outline: 'none'
 });
 const focusRingStyles = css({
-  '&:focus-visible': focusOutsideStyles,
+  '&:focus-visible': baseFocusOutsideStyles,
   '@supports not selector(*:focus-visible)': {
-    '&:focus': focusOutsideStyles
+    '&:focus': baseFocusOutsideStyles
   },
   '@media screen and (forced-colors: active), screen and (-ms-high-contrast: active)': {
     '&:focus-visible': {
@@ -55,15 +55,22 @@ const insetFocusRingStyles = css({
 
 const FocusRing = ({
   children,
-  isInset
-}) => jsx(ClassNames, null, ({
-  css,
-  cx
-}) => Children.only(
-/*#__PURE__*/
-// eslint-disable-next-line @repo/internal/react/no-clone-element
-cloneElement(children, {
-  className: cx([css(isInset ? insetFocusRingStyles : focusRingStyles), children && children.props.className])
-})));
+  isInset,
+  focus
+}) => {
+  const controlledStyles = isInset ? baseInsetStyles : baseFocusOutsideStyles;
+  const uncontrolledStyles = isInset ? insetFocusRingStyles : focusRingStyles;
+  const focusCls = typeof focus === 'undefined' ? uncontrolledStyles : focus === 'on' && controlledStyles;
+  return jsx(ClassNames, null, ({
+    css,
+    cx
+  }) => Children.only( // This may look unwieldy but means we skip applying styles / cloning if no className is applicable
+  focusCls ?
+  /*#__PURE__*/
+  // eslint-disable-next-line @repo/internal/react/no-clone-element
+  cloneElement(children, {
+    className: cx([css(focusCls), children.props.className])
+  }) : children));
+};
 
 export default FocusRing;

package/dist/es2019/index.js

@@ -1 +1,2 @@
-export { default } from './focus-ring';
+export { default } from './focus-ring';
+export { default as useFocusRing } from './use-focus-ring';

package/dist/es2019/use-focus-ring.js

@@ -0,0 +1,43 @@
+import { useRef, useState } from 'react';
+
+/**
+ * __Use focus ring__
+ *
+ * The `useFocusRing` hook is designed to manage focus for the `FocusRing` in cases where the `FocusRing`'s visual application
+ * and the element that takes focus, differ. See the `focus` prop of `FocusRing` for more information.
+ *
+ * @example
+ * ```jsx
+ * import VisuallyHidden from '@atlaskit/visuall-hidden';
+ * import FocusRing, { useFocusRing } from '@atlaskit/focus-ring';
+ *
+ * const InteractiveComponent = () => {
+ *  const { focusState, focusProps } = useFocusRing();
+ *
+ *  return (
+ *    <div>
+ *      <VisuallHidden>
+ *        <input {...focusProps} />
+ *      </VisuallyHidden>
+ *      <FocusRing focus={focusState}>
+ *        <div role="button">Hello</div>
+ *      </FocusRing>
+ *    </div>
+ *  );
+ *
+ * }
+ * ```
+ */
+const useFocusRing = (initialState = 'off') => {
+  const [focusState, setFocusState] = useState(initialState);
+  const focusProps = useRef({
+    onFocus: () => setFocusState('on'),
+    onBlur: () => setFocusState('off')
+  });
+  return {
+    focusState,
+    focusProps: focusProps.current
+  };
+};
+
+export default useFocusRing;

package/dist/es2019/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/focus-ring",
-	"version": "0.2.7",
+	"version": "1.0.0",
 	"sideEffects": false
 }

package/dist/esm/focus-ring.js

@@ -3,18 +3,18 @@ import { Children, cloneElement } from 'react';
 import { ClassNames, css, jsx } from '@emotion/core';
 import { B100 } from '@atlaskit/theme/colors';
 var BORDER_WIDTH = 2;
-var focusOutsideStyles = {
-  outlineOffset: BORDER_WIDTH,
-  outline: "".concat(BORDER_WIDTH, "px solid ").concat("var(--ds-border-focused, ".concat(B100, ")"))
-};
+var baseFocusOutsideStyles = css({
+  outline: "".concat(BORDER_WIDTH, "px solid ").concat("var(--ds-border-focused, ".concat(B100, ")")),
+  outlineOffset: BORDER_WIDTH
+});
 var baseInsetStyles = css({
   boxShadow: "inset 0px 0px 0px ".concat(BORDER_WIDTH, "px ").concat("var(--ds-border-focused, ".concat(B100, ")")),
   outline: 'none'
 });
 var focusRingStyles = css({
-  '&:focus-visible': focusOutsideStyles,
+  '&:focus-visible': baseFocusOutsideStyles,
   '@supports not selector(*:focus-visible)': {
-    '&:focus': focusOutsideStyles
+    '&:focus': baseFocusOutsideStyles
   },
   '@media screen and (forced-colors: active), screen and (-ms-high-contrast: active)': {
     '&:focus-visible': {
@@ -55,16 +55,21 @@ var insetFocusRingStyles = css({
 
 var FocusRing = function FocusRing(_ref) {
   var children = _ref.children,
-      isInset = _ref.isInset;
+      isInset = _ref.isInset,
+      focus = _ref.focus;
+  var controlledStyles = isInset ? baseInsetStyles : baseFocusOutsideStyles;
+  var uncontrolledStyles = isInset ? insetFocusRingStyles : focusRingStyles;
+  var focusCls = typeof focus === 'undefined' ? uncontrolledStyles : focus === 'on' && controlledStyles;
   return jsx(ClassNames, null, function (_ref2) {
     var css = _ref2.css,
         cx = _ref2.cx;
-    return Children.only(
+    return Children.only( // This may look unwieldy but means we skip applying styles / cloning if no className is applicable
+    focusCls ?
     /*#__PURE__*/
     // eslint-disable-next-line @repo/internal/react/no-clone-element
     cloneElement(children, {
-      className: cx([css(isInset ? insetFocusRingStyles : focusRingStyles), children && children.props.className])
-    }));
+      className: cx([css(focusCls), children.props.className])
+    }) : children);
   });
 };
 

package/dist/esm/index.js

@@ -1 +1,2 @@
-export { default } from './focus-ring';
+export { default } from './focus-ring';
+export { default as useFocusRing } from './use-focus-ring';

package/dist/esm/use-focus-ring.js

@@ -0,0 +1,54 @@
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
+import { useRef, useState } from 'react';
+
+/**
+ * __Use focus ring__
+ *
+ * The `useFocusRing` hook is designed to manage focus for the `FocusRing` in cases where the `FocusRing`'s visual application
+ * and the element that takes focus, differ. See the `focus` prop of `FocusRing` for more information.
+ *
+ * @example
+ * ```jsx
+ * import VisuallyHidden from '@atlaskit/visuall-hidden';
+ * import FocusRing, { useFocusRing } from '@atlaskit/focus-ring';
+ *
+ * const InteractiveComponent = () => {
+ *  const { focusState, focusProps } = useFocusRing();
+ *
+ *  return (
+ *    <div>
+ *      <VisuallHidden>
+ *        <input {...focusProps} />
+ *      </VisuallyHidden>
+ *      <FocusRing focus={focusState}>
+ *        <div role="button">Hello</div>
+ *      </FocusRing>
+ *    </div>
+ *  );
+ *
+ * }
+ * ```
+ */
+var useFocusRing = function useFocusRing() {
+  var initialState = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'off';
+
+  var _useState = useState(initialState),
+      _useState2 = _slicedToArray(_useState, 2),
+      focusState = _useState2[0],
+      setFocusState = _useState2[1];
+
+  var focusProps = useRef({
+    onFocus: function onFocus() {
+      return setFocusState('on');
+    },
+    onBlur: function onBlur() {
+      return setFocusState('off');
+    }
+  });
+  return {
+    focusState: focusState,
+    focusProps: focusProps.current
+  };
+};
+
+export default useFocusRing;

package/dist/esm/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/focus-ring",
-	"version": "0.2.7",
+	"version": "1.0.0",
 	"sideEffects": false
 }

package/dist/types/index.d.ts

@@ -1 +1,3 @@
 export { default } from './focus-ring';
+export { default as useFocusRing } from './use-focus-ring';
+export type { FocusRingProps, FocusEventHandlers, FocusState } from './types';

package/dist/types/types.d.ts

@@ -1,5 +1,16 @@
-import type { ReactElement } from 'react';
-export declare type FocusRingProps = {
+import type { FocusEventHandler, ReactElement } from 'react';
+export interface FocusEventHandlers {
+    onFocus: FocusEventHandler;
+    onBlur: FocusEventHandler;
+}
+export declare type FocusState = 'on' | 'off';
+export interface FocusRingProps {
+    /**
+     * Makes the `FocusRing` a controlled component (opting out of native focus behavior). The focus ring
+     * will apply the visual focus indicator when the `focus` prop is set to `on`. This prop should be used
+     * in conjunction with `useFocusRing`.
+     */
+    focus?: FocusState;
     /**
      * Controls whether the focus ring should be applied around or within the composed element.
      */
@@ -8,4 +19,4 @@ export declare type FocusRingProps = {
      * The focusable element to be rendered within the `FocusRing`.
      */
     children: ReactElement;
-};
+}

package/dist/types/use-focus-ring.d.ts

@@ -0,0 +1,34 @@
+import type { FocusEventHandlers, FocusState } from './types';
+/**
+ * __Use focus ring__
+ *
+ * The `useFocusRing` hook is designed to manage focus for the `FocusRing` in cases where the `FocusRing`'s visual application
+ * and the element that takes focus, differ. See the `focus` prop of `FocusRing` for more information.
+ *
+ * @example
+ * ```jsx
+ * import VisuallyHidden from '@atlaskit/visuall-hidden';
+ * import FocusRing, { useFocusRing } from '@atlaskit/focus-ring';
+ *
+ * const InteractiveComponent = () => {
+ *  const { focusState, focusProps } = useFocusRing();
+ *
+ *  return (
+ *    <div>
+ *      <VisuallHidden>
+ *        <input {...focusProps} />
+ *      </VisuallyHidden>
+ *      <FocusRing focus={focusState}>
+ *        <div role="button">Hello</div>
+ *      </FocusRing>
+ *    </div>
+ *  );
+ *
+ * }
+ * ```
+ */
+declare const useFocusRing: (initialState?: FocusState) => {
+    readonly focusState: FocusState;
+    readonly focusProps: FocusEventHandlers;
+};
+export default useFocusRing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/focus-ring",
-  "version": "0.2.7",
+  "version": "1.0.0",
   "description": "A focus ring is used to indicate the currently focused item.",
   "author": "Atlassian Pty Ltd",
   "license": "Apache-2.0",
@@ -9,9 +9,9 @@
   },
   "atlassian": {
     "team": "Design System Team",
-    "releaseModel": "continuous",
+    "releaseModel": "scheduled",
     "website": {
-      "name": "FocusRing"
+      "name": "Focus ring"
     }
   },
   "repository": "https://bitbucket.org/atlassian/atlassian-frontend",
@@ -36,10 +36,11 @@
   "devDependencies": {
     "@atlaskit/button": "^16.1.2",
     "@atlaskit/docs": "*",
-    "@atlaskit/progress-indicator": "^9.1.0",
+    "@atlaskit/progress-indicator": "^9.2.0",
     "@atlaskit/ssr": "*",
     "@atlaskit/textfield": "^5.1.2",
     "@atlaskit/visual-regression": "*",
+    "@atlaskit/visually-hidden": "^1.0.0",
     "@atlaskit/webdriver-runner": "*",
     "@atlassian/atlassian-frontend-prettier-config-1.0.0": "npm:@atlassian/atlassian-frontend-prettier-config@1.0.0",
     "@testing-library/react": "^8.0.1",