Merge pull request #211 from hypothesis/link-pattern

Add `hyp-link` pattern and `Link` component

src/components/Link.js

@@ -0,0 +1,33 @@
+import classnames from 'classnames';
+
+/**
+ * @typedef {import('preact').ComponentChildren} Children
+ *
+ * @typedef LinkBaseProps
+ * @prop {Children} children
+ * @prop {string} [classes] - Additional CSS classes to apply
+ * @prop {import('preact').Ref<HTMLAnchorElement>} [linkRef] - Optional ref for
+ *   the rendered anchor element
+ */
+
+/**
+ * @typedef {LinkBaseProps & import('preact').JSX.HTMLAttributes<HTMLAnchorElement>} LinkProps
+ */
+
+/**
+ * Style and add some attributes to an anchor (`<a>`) element
+ *
+ * @param {LinkProps} props
+ */
+export function Link({ children, classes = '', linkRef, ...restProps }) {
+  return (
+    <a
+      className={classnames('Hyp-Link', classes)}
+      ref={linkRef}
+      rel="noopener noreferrer"
+      {...restProps}
+    >
+      {children}
+    </a>
+  );
+}

src/components/test/Link-test.js

@@ -0,0 +1,43 @@
+import { mount } from 'enzyme';
+import { createRef } from 'preact';
+
+import { Link } from '../Link';
+
+describe('Link', () => {
+  const createComponent = (props = {}) => {
+    return mount(
+      <Link href="http://www.example.com" {...props}>
+        This is content inside of a Link
+      </Link>
+    );
+  };
+
+  it('renders children with appropriate classnames', () => {
+    const wrapper = createComponent();
+
+    assert.isTrue(wrapper.find('a').first().hasClass('Hyp-Link'));
+  });
+
+  it('applies extra classes', () => {
+    const wrapper = createComponent({ classes: 'foo bar' });
+    assert.deepEqual(
+      [...wrapper.find(`a.Hyp-Link.foo.bar`).getDOMNode().classList.values()],
+      ['Hyp-Link', 'foo', 'bar']
+    );
+  });
+
+  it('passes along a `ref` to the `a` element through `linkRef`', () => {
+    const linkRef = createRef();
+    createComponent({ linkRef });
+
+    assert.instanceOf(linkRef.current, Node);
+  });
+
+  it('adds common `rel` attributes', () => {
+    const wrapper = createComponent();
+    assert.equal(
+      wrapper.find('a').first().getDOMNode().getAttribute('rel'),
+      'noopener noreferrer'
+    );
+  });
+});

src/index.js

@@ -3,6 +3,7 @@ export { IconButton, LabeledButton, LinkButton } from './components/buttons';
 export { LabeledCheckbox, Checkbox } from './components/Checkbox';
 export { Frame, Card, Actions, Scrollbox } from './components/containers';
 export { Dialog } from './components/Dialog';
+export { Link } from './components/Link';
 export { Modal, ConfirmModal } from './components/Modal';
 export { Panel } from './components/Panel';
 export { Spinner } from './components/Spinner';

src/pattern-library/components/LibraryHome.js

@@ -1,3 +1,4 @@
+import { Link } from '../..';
 import Library from './Library';
 
 export default function LibraryHome() {
@@ -30,8 +31,8 @@ export default function LibraryHome() {
 
       <p>
         <strong>Components</strong> are{' '}
-        <a href="https://preactjs.com/">Preact</a> components that are built
-        using underlying <strong>patterns</strong>.
+        <Link href="https://preactjs.com/">Preact</Link> components that are
+        built using underlying <strong>patterns</strong>.
       </p>
     </Library.Page>
   );

src/pattern-library/components/PlaygroundApp.js

@@ -1,6 +1,6 @@
 import classnames from 'classnames';
 
-import { SvgIcon } from '../../components/SvgIcon';
+import { Link, SvgIcon } from '../../';
 
 import { getRoutes } from '../routes';
 import { useRoute } from '../router';
@@ -53,25 +53,25 @@ export default function PlaygroundApp({
     <main className="PlaygroundApp">
       <div className="PlaygroundApp__sidebar">
         <div className="PlaygroundApp__sidebar-home">
-          <a href={baseURL} onClick={e => navigate(e, '/')}>
+          <Link href={baseURL} onClick={e => navigate(e, '/')}>
             <SvgIcon name="logo" />
-          </a>
+          </Link>
         </div>
         {routeGroups.map(rGroup => (
           <div key={rGroup.title}>
             <h2>{rGroup.title}</h2>
             <ul>
               {rGroup.routes.map(({ route, title }) => (
                 <li key={title}>
-                  <a
-                    className={classnames('PlaygroundApp__nav-item', {
+                  <Link
+                    classes={classnames('hyp-link PlaygroundApp__nav-item', {
                       'is-active': activeRoute.route === route,
                     })}
                     href={`${route}`}
                     onClick={e => navigate(e, route)}
                   >
                     {title}
-                  </a>
+                  </Link>
                 </li>
               ))}
             </ul>

src/pattern-library/components/patterns/LinkComponents.js

@@ -0,0 +1,20 @@
+import { Link } from '../../../';
+import Library from '../Library';
+
+export default function LinkComponents() {
+  return (
+    <Library.Page title="Links">
+      <Library.Pattern title="Link">
+        <p>
+          <code>Link</code> components provide some common styling and attribute
+          for anchor (<code>a</code>) elements.
+        </p>
+        <Library.Example>
+          <Library.Demo withSource>
+            <Link href="https://www.example.com">A link to somewhere</Link>
+          </Library.Demo>
+        </Library.Example>
+      </Library.Pattern>
+    </Library.Page>
+  );
+}

src/pattern-library/components/patterns/LinkPatterns.js

@@ -0,0 +1,24 @@
+import Library from '../Library';
+
+export default function LinkPatterns() {
+  return (
+    <Library.Page title="Links">
+      <Library.Pattern title="Link">
+        <p>
+          The link pattern for <code>{'<a>'}</code> tags uses brand red and no
+          underline, as well as a rounded keyboard focus ring.
+        </p>
+        <Library.Example>
+          <Library.Demo withSource>
+            <a className="hyp-link" href="http://www.example.com">
+              This is a link
+            </a>
+            <a className="hyp-link" href="http://www.example.com">
+              This is another link
+            </a>
+          </Library.Demo>
+        </Library.Example>
+      </Library.Pattern>
+    </Library.Page>
+  );
+}

src/pattern-library/routes.js

@@ -5,6 +5,7 @@ import LayoutFoundations from './components/patterns/LayoutFoundations';
 
 import FormPatterns from './components/patterns/FormPatterns';
 import ContainerPatterns from './components/patterns/ContainerPatterns';
+import LinkPatterns from './components/patterns/LinkPatterns';
 import PanelPatterns from './components/patterns/PanelPatterns';
 import SpinnerPatterns from './components/patterns/SpinnerPatterns';
 import TablePatterns from './components/patterns/TablePatterns';
@@ -14,6 +15,7 @@ import ButtonComponents from './components/patterns/ButtonComponents';
 import ContainerComponents from './components/patterns/ContainerComponents';
 import DialogComponents from './components/patterns/DialogComponents';
 import FormComponents from './components/patterns/FormComponents';
+import LinkComponents from './components/patterns/LinkComponents';
 import PanelComponents from './components/patterns/PanelComponents';
 import SpinnerComponents from './components/patterns/SpinnerComponents';
 import TableComponents from './components/patterns/TableComponents';
@@ -63,6 +65,12 @@ const routes = [
     component: FormPatterns,
     group: 'patterns',
   },
+  {
+    route: '/patterns-links',
+    title: 'Links',
+    component: LinkPatterns,
+    group: 'patterns',
+  },
   {
     route: '/patterns-panels',
     title: 'Panels',
@@ -111,6 +119,12 @@ const routes = [
     component: FormComponents,
     group: 'components',
   },
+  {
+    route: '/components-links',
+    title: 'Links',
+    component: LinkComponents,
+    group: 'components',
+  },
   {
     route: '/components-panel',
     title: 'Panel',

styles/base/_elements.scss

@@ -1,32 +1,6 @@
 @use '../mixins/focus';
 @use "../variables" as var;
 
-$-border-radius: var.$border-radius;
-$-color-link: var.$color-link;
-$-color-link--hover: var.$color-link--hover;
-
-// basic standard styling for elements
-// TODO: Evaluate if dependencies on variables can be reduced or eliminated
-a {
-  @include focus.outline-on-keyboard-focus;
-  // Ensure the tag has width in order for :focus styling to render correctly.
-  display: inline-block;
-  color: $-color-link;
-  text-decoration: none;
-  // Give links a radius to allow :focus styling to appear similar to that of buttons
-  border-radius: $-border-radius;
-}
-
-a:active,
-a:focus {
-  text-decoration: none;
-}
-
-a:hover {
-  text-decoration: none;
-  color: $-color-link--hover;
-}
-
 p {
   hyphens: auto;
 

styles/components/Link.scss

@@ -0,0 +1,5 @@
+@use '../mixins/patterns/links';
+
+.Hyp-Link {
+  @include links.link;
+}

styles/index.scss

@@ -6,6 +6,7 @@
 @use './components/Checkbox';
 @use './components/containers';
 @use './components/Dialog';
+@use './components/Link';
 @use './components/Modal';
 @use './components/Panel';
 @use './components/Spinner';

styles/mixins/patterns/_links.scss

@@ -0,0 +1,27 @@
+@use '../../variables' as var;
+
+@use '../focus';
+
+$-border-radius: var.$border-radius;
+$-color-link: var.$color-link;
+$-color-link--hover: var.$color-link--hover;
+
+@mixin link {
+  @include focus.outline-on-keyboard-focus;
+  // Ensure the tag has width in order for :focus styling to render correctly.
+  display: inline-block;
+  color: $-color-link;
+  text-decoration: none;
+  // Give links a radius to allow :focus styling to appear similar to that of buttons
+  border-radius: $-border-radius;
+
+  &:active,
+  &:focus {
+    text-decoration: none;
+  }
+
+  &:hover {
+    text-decoration: none;
+    color: $-color-link--hover;
+  }
+}

styles/patterns/_links.scss

@@ -0,0 +1,5 @@
+@use '../mixins/patterns/links';
+
+.hyp-link {
+  @include links.link;
+}

styles/patterns/index.scss

@@ -1,5 +1,6 @@
 @use 'containers';
 @use 'forms';
+@use 'links';
 @use 'panels';
 @use 'spinners';
 @use 'tables';