Skip to content

Commit

Permalink
docs(Link): added README.md for landing (#955)
Browse files Browse the repository at this point in the history
  • Loading branch information
@LakeVostok
LakeVostok authored Sep 2, 2023
1 parent 0be31c9 commit adfc564
Show file tree
Hide file tree
Showing 3 changed files with 220 additions and 27 deletions.
190 changes: 190 additions & 0 deletions src/components/Link/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,190 @@
<!--GITHUB_BLOCK-->

# Link

<!--/GITHUB_BLOCK-->

```tsx
import {Link} from '@gravity-ui/uikit';
```

`Link` - is a part of the text, that, when clicked, takes the user to another part of the page, another page inside the service, or to a page of another external service.

The main difference from the [Button](../Button) is the navigation function. `Link` more often lead to other pages or open new browser tabs.

## Appearance

There can be three types: `normal`(the usual brown), `primary`(black), `secondary`(gray). It is controlled by the `view` property. It is also possible to display visited state using the `visitable` property.

### Normal

The most familiar and well-established pattern of use for users. It is used to visually highlight an element inside a text, table, and as part of navigation. It is used to navigate to pages inside the service and to external sources, including documentation. Also, they are used on error pages and zero states.

<!--LANDING_BLOCK
<ExampleBlock
code={`
<Link view="normal" href="#">Link</Link>
`}>
<UIKit.Link view="normal" href="#">Link</UIKit.Link>
</ExampleBlock>
LANDING_BLOCK-->

<!--GITHUB_BLOCK-->

```tsx
<Link view="normal" href="#">
Link
</Link>
```

<!--/GITHUB_BLOCK-->

### Primary

They are used when it is natively clear to the user that it is possible to interact with an element, but visually using brown `Link` will overload the interface and disrupt the balance of accents on the page.

<!--LANDING_BLOCK
<ExampleBlock
code={`
<Link view="primary" href="#">Link</Link>
`}>
<UIKit.Link view="primary" href="#">Link</UIKit.Link>
</ExampleBlock>
LANDING_BLOCK-->

<!--GITHUB_BLOCK-->

```tsx
<Link view="primary" href="#">
Link
</Link>
```

<!--/GITHUB_BLOCK-->

### Secondary

Like primary `Link`, they are used when it is natively clear to the user that an element can be interacted with, and the need to navigate through them is secondary and affects a small number of scenarios. The main task is not to argue with the accents on the page. It is more often used in bread crumbs or when displaying secondary attributes.

<!--LANDING_BLOCK
<ExampleBlock
code={`
<Link view="secondary" href="#">Link</Link>
`}>
<UIKit.Link view="secondary" href="#">Link</UIKit.Link>
</ExampleBlock>
LANDING_BLOCK-->

<!--GITHUB_BLOCK-->

```tsx
<Link view="secondary" href="#">
Link
</Link>
```

<!--/GITHUB_BLOCK-->

### Visitable

Used to show that the `Link` has already been visited.

<!--LANDING_BLOCK
<ExampleBlock
code={`
<Link href="https://gravity-ui.com/" visitable>Link</Link>
`}>
<UIKit.Link href="https://gravity-ui.com/" visitable>Link</UIKit.Link>
</ExampleBlock>
LANDING_BLOCK-->

<!--GITHUB_BLOCK-->

```tsx
<Link href="https://gravity-ui.com/" visitable>
Link
</Link>
```

<!--/GITHUB_BLOCK-->

## Href

`href` property is optional. If it is absent, then `Link` wil act like `Button`.

<!--LANDING_BLOCK
<ExampleBlock
code={`
<Link href="#">Link with href</Link>
<Link>Link without href</Link>
`}>
<UIKit.Link href="#">Link with href</UIKit.Link>
<UIKit.Link>Link without href</UIKit.Link>
</ExampleBlock>
LANDING_BLOCK-->

<!--GITHUB_BLOCK-->

```tsx
<Link href="#">Link with href</Link>
<Link>Link without href</Link>
```

<!--/GITHUB_BLOCK-->

## Usage

Сan be used as an independent text element, or as part of the text

<!--LANDING_BLOCK
<ExampleBlock
code={`
<Text>
<Link>what roles are active in the service</Link>
</Text>
<Text>
Currently, this role can only be assigned to a <Link>folder</Link> or <Link>cloud</Link>
</Text>
`}>
<UIKit.Text>
<UIKit.Link>what roles are active in the service</UIKit.Link>
</UIKit.Text>
<UIKit.Text>
Currently, this role can only be assigned to a <UIKit.Link>folder</UIKit.Link> or <UIKit.Link>cloud</UIKit.Link>
</UIKit.Text>
</ExampleBlock>
LANDING_BLOCK-->

<!--GITHUB_BLOCK-->

```tsx
<Text>
<Link>what roles are active in the service</Link>
</Text>
<Text>
Currently, this role can only be assigned to a <Link>folder</Link> or <Link>cloud</Link>
</Text>
```

<!--/GITHUB_BLOCK-->

## Properties

| Name | Description | Type | Default |
| :--------- | :-------------------------------------- | :--------------------------------------------------------------------------: | :--------: |
| view | Link appearance | `"normal" \| "primary" \| "secondary"` | `"normal"` |
| visitable | Display css `:visitable` state | `boolean \| undefined` |
| href | HTML `href` attribute | `string \| undefined` |
| target | HTML `target` attribute | `string \| undefined` |
| rel | HTML `rel` attribute | `string \| undefined` |
| title | HTML `title` attribute | `string \| undefined` |
| children | Link content | `React.ReactNode` |
| extraProps | Any additional props | `Record \| undefined` |
| onClick | `click` event handler | `React.MouseEventHandler<HTMLAnchorElement \| HTMLSpanElement> \| undefined` |
| onFocus | `focus` event handler | `React.FocusEventHandler<HTMLAnchorElement \| HTMLSpanElement> \| undefined` |
| onBlur | `blur` event handler | `React.FocusEventHandler<HTMLAnchorElement \| HTMLSpanElement> \| undefined` |
| id | HTML `id` attribute | `string \| undefined` |
| style | HTML `style` attribute | `React.CSSProperties \| undefined` |
| className | HTML `class` attribute | `string \| undefined` |
| qa | HTML `data-qa` attribute, used in tests | `string \| undefined` |
| ref | React ref to Link DOM node | `React.ForwardedRef<HTMLElement> \| undefined` |
13 changes: 8 additions & 5 deletions src/components/Link/__stories__/Link.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ import {Link} from '@gravity-ui/uikit';
- [Normal](#normal)
- [Primary](#primary)
- [Secondary](#secondary)
- [Visitable](#visitable)

[Href](#href)

Expand All @@ -38,7 +39,7 @@ Link - is a part of the text, that, when clicked, takes the user to another part
The main difference from the [Buttons](/docs/components-button) is the navigation function. Links more often lead to other pages or open new browser tabs.

## Appearance
There can be three types: `normal`(the usual blue), `primary`(black), `secondary`(gray). it is controlled by the view property.
There can be three types: `normal`(the usual brown), `primary`(black), `secondary`(gray). it is controlled by the `view` property. It is also possible to display visited state using the `visitable` property.

### Normal
The most familiar and well-established pattern of use for users. It is used to visually highlight an element inside a text, table, and as part of navigation. It is used to navigate to pages inside the service and to external sources, including documentation. Also, they are used on error pages and zero states.
Expand All @@ -58,15 +59,17 @@ Like primary links, they are used when it is natively clear to the user that an
<DocsSource language="tsx" code={LinkExampleViewSecondary.code}/>
<LinkExampleViewSecondary/>

### Visitable
Used to show that the link has already been visited.

<DocsSource language="tsx" code={LinkExampleVisitable.code}/>
<LinkExampleVisitable/>

## Href
`href` property is optional. If it is absent, then Link wil act like Button.
<DocsSource language="tsx" code={LinkExampleHref.code}/>
<LinkExampleHref/>

## Visitable
`visitable` property is optional. Can be `true` or `false`. If `true` the link with `href` attribute will be marked with color when the link is visited.
<LinkExampleVisitable/>

## Usage
Сan be used as an independent text element, or as part of the text
<DocsSource language="tsx" code={LinkExampleUsage.code}/>
Expand Down
44 changes: 22 additions & 22 deletions src/components/Link/__stories__/examples/LinkExampleView/LinkExampleView.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,76 +7,76 @@ import {Text} from '../../../../Text';
export function LinkExampleViewNormal() {
return (
<DocsExample>
<Link view="normal" href="#">
<Link view="normal" href="/">
Link
</Link>
</DocsExample>
);
}
LinkExampleViewNormal.code = `
<Link view="normal" href="#">
<Link view="normal" href="/">
Link
</Link>
`.trim();

export function LinkExampleViewPrimary() {
return (
<DocsExample>
<Link view="primary" href="#">
<Link view="primary" href="/">
Link
</Link>
</DocsExample>
);
}
LinkExampleViewPrimary.code = `
<Link view="primary" href="#">
<Link view="primary" href="/">
Link
</Link>
`.trim();

export function LinkExampleViewSecondary() {
return (
<DocsExample>
<Link view="secondary" href="#">
<Link view="secondary" href="/">
Link
</Link>
</DocsExample>
);
}
LinkExampleViewSecondary.code = `
<Link view="secondary" href="#">
<Link view="secondary" href="/">
Link
</Link>
`.trim();

export function LinkExampleHref() {
export function LinkExampleVisitable() {
return (
<DocsExample>
<Link href="#">Link with href</Link>
<Link>Link without href</Link>
<Link href="/" visitable>
Visitable link
</Link>
<Link href="/" visitable={false}>
Non visitable link
</Link>
</DocsExample>
);
}
LinkExampleHref.code = `
<Link href="#">Link with href</Link>
<Link>Link without href</Link>
LinkExampleVisitable.code = `
<Link href="https://gravity-ui.com/" visitable>Visitable link</Link>
<Link href="https://gravity-ui.com/" visitable={false}>Non visitable link</Link>
`.trim();

export function LinkExampleVisitable() {
export function LinkExampleHref() {
return (
<DocsExample>
<Link href="#" visitable>
Visitable link
</Link>
<Link href="#" visitable={false}>
Non visitable link
</Link>
<Link href="/">Link with href</Link>
<Link>Link without href</Link>
</DocsExample>
);
}
LinkExampleVisitable.code = `
<Link href="#" visitable>Visitable link</Link>
<Link href="#" visitable={false}>Non visitable link</Link>
LinkExampleHref.code = `
<Link href="/">Link with href</Link>
<Link>Link without href</Link>
`.trim();

export function LinkExampleUsage() {
Expand Down

0 comments on commit adfc564

Please sign in to comment.