Merge pull request #1874 from adevinta/feat/add-link-box-component

feat(link-box): add first iteration

packages/components/link-box/.npmignore

@@ -0,0 +1,2 @@
+src
+**/*.stories.*

packages/components/link-box/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Adevinta ASA.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/components/link-box/README.md

@@ -0,0 +1,13 @@
+# Link Box
+> @spark-ui/link-box
+
+[![storybook](https://img.shields.io/badge/storybook-black?logo=storybook)](https://sparkui.vercel.app/?path=/docs/components-linkbox--docs)
+[![documentation](https://img.shields.io/badge/documentation-black?logo=googledocs)](https://sparkui-adv.vercel.app/docs/components/link-box)
+[![issue](https://img.shields.io/badge/report%20a%20bug-black?logo=openbugbounty&logoColor=red)](https://github.com/adevinta/spark/issues/new?&projects=4&template=bug-report.yml&assignees=&labels=component,link-box)
+[![npm](https://img.shields.io/npm/dt/%40spark-ui/link-box?logo=npm&labelColor=black)](https://www.npmjs.com/package/@spark-ui/link-box)
+
+
+This package is part of the [`@spark-ui`](https://github.com/adevinta/spark) react-js user interface component library project.
+
+[![Issues open](https://img.shields.io/github/issues-search/adevinta/spark?query=is%3Aopen%20label%3Acomponent%20label%3Alink-box&logo=openbugbounty&logoColor=red&label=issues%20open&color=red)](https://github.com/adevinta/spark/issues?q=is%3Aopen+label%3Acomponent+label%3Alink-box)
+[![NPM](https://img.shields.io/npm/l/%40spark-ui%2Flink-box)](https://github.com/adevinta/spark/blob/main/packages/components/link-box/LICENSE.md)

packages/components/link-box/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@spark-ui/link-box",
+  "version": "0.0.0",
+  "description": "Semantic component used to wrap elements (cards, blog posts, articles, etc.) in a link.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "@spark-ui",
+    "react",
+    "component",
+    "accessible",
+    "accessibility",
+    "wai-aria",
+    "aria",
+    "a11y",
+    "link-box"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@spark-ui/slot": "^1.7.0",
+    "class-variance-authority": "0.7.0"
+  },
+  "peerDependencies": {
+    "react": "^16.8 || ^17.0 || ^18.0",
+    "react-dom": "^16.8 || ^17.0 || ^18.0",
+    "tailwindcss": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adevinta/spark.git",
+    "directory": "packages/components/link-box"
+  },
+  "config": {
+    "title": "link-box",
+    "category": "components"
+  },
+  "bugs": {
+    "url": "https://github.com/adevinta/spark/issues?q=is%3Aopen+label%3Autility+label%3Alink-box"
+  },
+  "homepage": "https://sparkui.vercel.app",
+  "license": "MIT"
+}

packages/components/link-box/src/LinkBox.doc.mdx

@@ -0,0 +1,42 @@
+import { Meta, Canvas } from '@storybook/addon-docs'
+import { ArgTypes } from '@storybook/blocks';
+
+import { LinkBox } from '.'
+
+import * as stories from './LinkBox.stories'
+
+<Meta of={stories} />
+
+# LinkBox
+
+Semantic component used to wrap elements (cards, blog posts, articles, etc.) in a link.
+
+## Install
+
+```sh
+npm install @spark-ui/link-box
+```
+
+## Import
+
+```tsx
+import { LinkBox } from "@spark-ui/link-box"
+```
+
+## Props
+
+<ArgTypes of={LinkBox} />
+
+## Usage
+
+### Default
+
+Simply wrapping an entire component in an `a` tag may seem convenient for linking, but it's considered unsemantic and incorrect. This is because the component might include other clickable elements like tags, timestamps, or buttons.
+
+<Canvas of={stories.Default} />
+
+### Nesting
+
+Any nested links and buttons inside `LinkBox` are elevated to the top using `z-index` to ensure proper navigation between links.
+
+<Canvas of={stories.Nesting} />

packages/components/link-box/src/LinkBox.stories.tsx

@@ -0,0 +1,69 @@
+import { Icon } from '@spark-ui/icon'
+import { IconButton } from '@spark-ui/icon-button'
+import { FavoriteOutline } from '@spark-ui/icons/dist/icons/FavoriteOutline'
+import { Meta, StoryFn } from '@storybook/react'
+
+import { LinkBox } from '.'
+
+const meta: Meta<typeof LinkBox> = {
+  title: 'Experimental/LinkBox',
+  component: LinkBox,
+}
+
+export default meta
+
+export const Default: StoryFn = _args => (
+  <div className="max-w-sz-256">
+    <LinkBox className="space-y-md" asChild>
+      <article>
+        <div className="relative aspect-square w-full overflow-hidden rounded-md bg-neutral shadow-md">
+          <img className="size-full" src="https://picsum.photos/200/200" alt="" />
+        </div>
+
+        <div className="space-y-none">
+          <h2>
+            <LinkBox.Overlay className="line-clamp-1 text-headline-2" href="#">
+              Title
+            </LinkBox.Overlay>
+          </h2>
+
+          <p className="line-clamp-2 text-body-1">Description</p>
+        </div>
+      </article>
+    </LinkBox>
+  </div>
+)
+
+export const Nesting: StoryFn = _args => (
+  <div className="max-w-sz-256">
+    <LinkBox className="space-y-md" asChild>
+      <article>
+        <div className="relative aspect-square w-full overflow-hidden rounded-md bg-neutral shadow-md">
+          <img className="size-full" src="https://picsum.photos/200/200" alt="Card image" />
+
+          <div className="absolute bottom-md right-md z-raised">
+            <IconButton shape="pill" aria-label="Like">
+              <Icon>
+                <FavoriteOutline />
+              </Icon>
+            </IconButton>
+          </div>
+        </div>
+
+        <div className="space-y-none">
+          <h2>
+            <LinkBox.Overlay className="line-clamp-1 text-headline-2" href="#">
+              Title
+            </LinkBox.Overlay>
+          </h2>
+
+          <p className="line-clamp-2 text-body-1">Description</p>
+
+          <a className="text-body-2" href="/">
+            Read more
+          </a>
+        </div>
+      </article>
+    </LinkBox>
+  </div>
+)

packages/components/link-box/src/LinkBox.test.tsx

@@ -0,0 +1,24 @@
+import { render, screen, within } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { LinkBox } from '.'
+
+describe('LinkOverlay', () => {
+  it('should render', async () => {
+    render(
+      <LinkBox asChild>
+        <article>
+          <h2>
+            <LinkBox.Overlay href="#">Title</LinkBox.Overlay>
+          </h2>
+        </article>
+      </LinkBox>
+    )
+
+    const el = screen.getByRole('heading', { name: 'Title', level: 2 })
+
+    expect(el).toBeInTheDocument()
+
+    expect(within(el).getByRole('link', { name: 'Title' })).toBeInTheDocument()
+  })
+})

packages/components/link-box/src/LinkBox.tsx

@@ -0,0 +1,27 @@
+import { Slot } from '@spark-ui/slot'
+import { cx } from 'class-variance-authority'
+import { forwardRef } from 'react'
+
+export interface LinkBoxProps extends React.ComponentPropsWithoutRef<'div'> {
+  asChild?: boolean
+}
+
+export const LinkBox = forwardRef<HTMLDivElement, LinkBoxProps>(
+  ({ className, asChild, ...props }, ref) => {
+    const Component = asChild ? Slot : 'div'
+
+    return (
+      <Component
+        ref={ref}
+        data-spark-component="link-box"
+        className={cx(
+          'relative [&_a[href]:not([data-spark-component="link-overlay"])]:relative [&_a[href]:not([data-spark-component="link-overlay"])]:z-raised [&_button]:relative [&_button]:z-raised',
+          className
+        )}
+        {...props}
+      />
+    )
+  }
+)
+
+LinkBox.displayName = 'LinkBox'

packages/components/link-box/src/LinkOverlay.tsx

@@ -0,0 +1,27 @@
+import { Slot } from '@spark-ui/slot'
+import { cx } from 'class-variance-authority'
+import { ComponentPropsWithoutRef, forwardRef } from 'react'
+
+export interface LinkOverlayProps extends ComponentPropsWithoutRef<'a'> {
+  asChild?: boolean
+}
+
+export const LinkOverlay = forwardRef<HTMLAnchorElement, LinkOverlayProps>(
+  ({ className, asChild, ...props }, ref) => {
+    const Component = asChild ? Slot : 'a'
+
+    return (
+      <Component
+        ref={ref}
+        data-spark-component="link-overlay"
+        className={cx(
+          "static before:absolute before:left-none before:top-none before:z-base before:block before:size-full before:content-['']",
+          className
+        )}
+        {...props}
+      />
+    )
+  }
+)
+
+LinkOverlay.displayName = 'LinkBox.Overlay'

packages/components/link-box/src/index.ts

@@ -0,0 +1,14 @@
+import type { FC } from 'react'
+
+import { LinkBox as Root, LinkBoxProps } from './LinkBox'
+import { LinkOverlay } from './LinkOverlay'
+
+export const LinkBox: FC<LinkBoxProps> & {
+  Overlay: typeof LinkOverlay
+} = Object.assign(Root, { Overlay: LinkOverlay })
+
+LinkBox.displayName = 'LinkBox'
+LinkBox.Overlay.displayName = 'LinkBox.Overlay'
+
+export { type LinkBoxProps } from './LinkBox'
+export { type LinkOverlayProps } from './LinkOverlay'

packages/components/link-box/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../../tsconfig.json",
+  "include": ["src/**/*", "../../../global.d.ts"]
+}

packages/components/link-box/vite.config.ts

@@ -0,0 +1,6 @@
+import path from 'path'
+import { getComponentConfiguration } from '../../../config/index'
+
+const { name } = require(path.resolve(__dirname, 'package.json'))
+
+export default getComponentConfiguration(process.cwd(), name)