Skip to content

Commit

Permalink
feat(docs): add more docs and components
Browse files Browse the repository at this point in the history
  • Loading branch information
BlackySoul committed Dec 19, 2024
1 parent c4c98b9 commit 039ea4d
Show file tree
Hide file tree
Showing 30 changed files with 820 additions and 158 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
.icon {
background-color: var(--vkui--color_background_secondary--hover);
padding-inline: 4px;
padding-block: 6px;
}
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,11 @@ import {
Accordion as VKUIAccordion,
type AccordionProps as VKUIAccordionProps,
} from '@vkontakte/vkui';
import styles from './Accordion.module.css';

export interface AccordionProps extends Omit<TappableProps, 'onChange'> {
expanded: VKUIAccordionProps['expanded'];
onChange?: VKUIAccordionProps['onChange'];
onChange: (e?: React.MouseEvent<HTMLElement>, toggle?: boolean) => void;
children?: React.ReactNode;
icon?: React.ReactNode;
className?: string;
Expand All @@ -23,9 +24,10 @@ function AccordionSummary({
title,
className,
icon: Icon,
onChange,
...restProps
}: Pick<AccordionProps, 'title' | 'className' | 'icon'>) {
const { expanded, labelId, contentId, onChange } = React.useContext(AccordionContext);
}: Pick<AccordionProps, 'title' | 'className' | 'icon'> & Pick<AccordionProps, 'onChange'>) {
const { expanded, labelId, contentId } = React.useContext(AccordionContext);

return (
<Tappable
Expand All @@ -35,22 +37,24 @@ function AccordionSummary({
aria-controls={contentId}
activeMode="opacity"
hoverMode="opacity"
onClick={() => onChange(!expanded)}
onClick={onChange}
{...restProps}
>
<Flex align="center">
{Icon}
<Paragraph>{title}</Paragraph>
</Flex>
{expanded ? <Icon20ChevronUp /> : <Icon20Dropdown />}
<Tappable className={styles.icon} onClick={(e) => onChange(e, true)}>
{expanded ? <Icon20ChevronUp /> : <Icon20Dropdown />}
</Tappable>
</Tappable>
);
}

export function Accordion({ expanded = false, children, onChange, ...restProps }: AccordionProps) {
return (
<VKUIAccordion expanded={expanded} onChange={onChange}>
<AccordionSummary {...restProps} />
<VKUIAccordion expanded={expanded}>
<AccordionSummary {...restProps} onChange={onChange} />
<VKUIAccordion.Content>{children}</VKUIAccordion.Content>
</VKUIAccordion>
);
Expand Down
8 changes: 6 additions & 2 deletions packages/vkui-docs-theme/src/components/Sidebar/Menu/Menu.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,13 @@ function Folder({ item, icon }: FolderProps) {
),
icon: icon && <MenuItemIcon active={activeRouteInside} Component={icon} />,
expanded: open,
onChange: () => {
onChange: (e, toggle) => {
if (toggle) {
e?.preventDefault();
e?.stopPropagation();
}
if (isLink) {
if (active) {
if (active || toggle) {
// eslint-disable-next-line react-compiler/react-compiler
TreeState[item.route] = !open;
} else {
Expand Down
4 changes: 4 additions & 0 deletions packages/vkui-docs-theme/src/mdx/Callout/Callout.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@

.content {
margin-inline-start: var(--vkui--spacing_size_xl);
display: flex;
align-items: flex-start;
flex-direction: column;
justify-content: center;
}

.root:not(:last-child) {
Expand Down
16 changes: 16 additions & 0 deletions packages/vkui-docs-theme/src/mdx/Code/Code.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@
color: var(--vkui--color_text_primary);
}

/* stylelint-disable-next-line selector-max-type */
pre .root {
display: flex;
flex-direction: column;
}

/* stylelint-disable-next-line selector-max-type */
.root span {
/* stylelint-disable-next-line csstools/value-no-unknown-custom-properties */
Expand All @@ -24,3 +30,13 @@
/* stylelint-disable-next-line csstools/value-no-unknown-custom-properties */
color: var(--shiki-dark);
}

/* stylelint-disable-next-line selector-max-type */
.root > span[data-highlighted-line] {
background-color: rgba(125, 125, 218, 0.1);
}

/* stylelint-disable-next-line selector-max-universal,selector-max-type */
.root > span[data-highlighted-line]:is(html[class~='vkui--vkBase--dark'] *) {
background-color: rgba(90, 90, 197, 0.1);
}
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { classNames, copyTextToClipboard } from '@vkontakte/vkjs';
import { IconButton } from '@vkontakte/vkui';
import styles from './CopyToClipboard.module.css';

interface CopyToClipboardProps extends React.ComponentProps<'button'> {
export interface CopyToClipboardProps extends React.ComponentProps<'button'> {
getValue: () => string;
}

Expand Down
15 changes: 12 additions & 3 deletions packages/vkui-docs-theme/src/mdx/Pre/Pre.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,6 @@
}

.buttons {
position: absolute;
inset-inline-end: var(--vkui--spacing_size_m);
inset-block-start: var(--vkui--spacing_size_m);
display: flex;
color: var(--vkui--color_icon_tertiary);
}
Expand All @@ -32,3 +29,15 @@
.buttons > *:not(:last-child) {
margin-inline-end: var(--vkui--spacing_size_xs);
}

.buttonsAbsolute {
position: absolute;
inset-inline-end: var(--vkui--spacing_size_m);
inset-block-start: var(--vkui--spacing_size_m);
}

.header {
background-color: var(--vkui--color_background_modal);
padding-inline: var(--vkui--spacing_size_4xl) var(--vkui--spacing_size_m);
border-block-end: 1px solid var(--vkui_docs--color_stroke_separator_secondary);
}
28 changes: 20 additions & 8 deletions packages/vkui-docs-theme/src/mdx/Pre/Pre.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import * as React from 'react';
import { classNames } from '@vkontakte/vkjs';
import { CopyToClipboard } from './CopyToClipboard/CopyToClipboard';
import { Flex } from '@vkontakte/vkui';
import { CopyToClipboard, type CopyToClipboardProps } from './CopyToClipboard/CopyToClipboard';
import styles from './Pre.module.css';

interface PreProps extends React.ComponentProps<'pre'> {
Expand All @@ -19,19 +20,30 @@ export function Pre({
}: PreProps) {
const preRef = React.useRef<HTMLPreElement | null>(null);

const getValue = () => preRef.current?.querySelector('code')?.textContent || '';

return (
<div className={styles.root}>
{filename && <div>{filename}</div>}
{filename && (
<Flex className={styles.header} align="center" justify="space-between">
<Flex>{filename}</Flex>
{copy === '' && <CopyButton getValue={getValue} />}
</Flex>
)}
<pre className={classNames(styles.pre, className)} ref={preRef} {...props}>
{children}
</pre>
{copy === '' && (
<div className={classNames(styles.buttons)}>
<CopyToClipboard
getValue={() => preRef.current?.querySelector('code')?.textContent || ''}
/>
</div>
{copy === '' && !filename && (
<CopyButton getValue={getValue} className={styles.buttonsAbsolute} />
)}
</div>
);
}

function CopyButton({ getValue, className }: Pick<CopyToClipboardProps, 'getValue' | 'className'>) {
return (
<div className={classNames(styles.buttons, className)}>
<CopyToClipboard getValue={getValue} />
</div>
);
}
23 changes: 23 additions & 0 deletions packages/vkui-docs-theme/src/mdx/Steps/Steps.module.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
.root {
margin-inline-start: var(--vkui--spacing_size_2xl);
padding-inline-start: var(--vkui--spacing_size_2xl);
border-inline-start: 1px solid var(--vkui_docs--color_stroke_separator_secondary);
}

/* stylelint-disable-next-line selector-max-type */
.root h2 {
counter-increment: steps;
}

/* stylelint-disable-next-line selector-max-type */
.root h2::before {
position: absolute;
block-size: 28px;
inline-size: 28px;
font-size: 16px;
text-align: center;
content: counter(steps);
border-radius: 50%;
margin-inline-start: calc(-2 * var(--vkui--spacing_size_2xl));
background-color: var(--vkui--color_background);
}
10 changes: 10 additions & 0 deletions packages/vkui-docs-theme/src/mdx/Steps/Steps.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import * as React from 'react';
import styles from './Steps.module.css';

interface StepsProps {
children: React.ReactNode;
}

export function Steps({ children }: StepsProps) {
return <div className={styles.root}>{children}</div>;
}
8 changes: 8 additions & 0 deletions packages/vkui-docs-theme/src/mdx/Test.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
/* eslint-disable no-console */
import { HorizontalScroll } from '@vkontakte/vkui';

export function Test() {
// @ts-expect-error: TS2345 fdg
console.log('sdf', HorizontalScroll.__docgenInfo);
return null;
}
5 changes: 5 additions & 0 deletions packages/vkui-docs-theme/src/mdx/index.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,11 @@
padding-inline: var(--vkui--spacing_size_3xl) 0;
}

.ol {
padding-block: var(--vkui--spacing_size_2xl) 0;
padding-inline: var(--vkui--spacing_size_3xl) 0;
}

.li:not(:first-child) {
margin-block-start: var(--vkui--spacing_size_xl);
}
Expand Down
6 changes: 5 additions & 1 deletion packages/vkui-docs-theme/src/mdx/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ import { HeadingLink } from './HeadingLink/HeadingLink';
import { Layout } from './Layout/Layout';
import { Overview } from './Overview/Overview';
import { Pre } from './Pre/Pre';
import { Steps } from './Steps/Steps';
import { Test } from './Test';
import styles from './index.module.css';

const DEFAULT_COMPONENTS: MDXComponents = {
Expand All @@ -17,7 +19,7 @@ const DEFAULT_COMPONENTS: MDXComponents = {
h5: (props) => <HeadingLink tag="h5" {...props} />,
h6: (props) => <HeadingLink tag="h6" {...props} />,
ul: (props) => <ul className={styles.ul} {...props} />,
ol: (props) => <ol {...props} />,
ol: (props) => <ol className={styles.ol} {...props} />,
li: (props) => <li className={styles.li} {...props} />,
blockquote: (props) => <blockquote {...props} />,
hr: (props) => <hr className={styles.hr} {...props} />,
Expand All @@ -28,6 +30,8 @@ const DEFAULT_COMPONENTS: MDXComponents = {
strong: (props) => <strong className={styles.strong} {...props} />,
wrapper: Layout,
Overview,
Steps,
Test,
Callout,
};

Expand Down
1 change: 0 additions & 1 deletion packages/vkui-docs-theme/styles/global.css
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@
-webkit-tap-highlight-color: transparent;
}

ol,
ul,
menu {
list-style: none;
Expand Down
29 changes: 16 additions & 13 deletions website/pages/overview/about.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,23 +19,26 @@

## Об этой документации

### Основа
В верхнем навигационном меню вы можете найти ссылки на ключевые разделы - [Компоненты](/components) и [О системе](/overview/about),
а так же ссылки на документации иконок и токенов.

В этом разделе представлены концептуальные особенности библиотеки. [Режимы подключения](/overview/modes) позволяют узнать о возможностях использования
библиотеки в различных сценариях: автономном, "приложение внутри приложения" и частичном использовании компонентов.
[Структура экранов](/overview/structure) раскрывает принципы навигации в приложении, созданном на основе VKUI.
В разделе "О системе" представлены концептуальные особенности библиотеки. Справа располагается дополнительное подменю, пункты которого структурированы последовательно, начиная с базовых
концепций и заканчивая более сложными аспектами библиотеки. Мы рекомендуем следовать этой последовательности для лучшего понимания функционала **VKUI** и его возможностей.

### Компоненты
В разделе "Компоненты" можно найти все компоненты, доступные для использования,
на каждой странице представлена спецификация и интерактивный пример с возможностью редактирования кода.

В данном разделе представлены свойства и методы каждого компонента.
Практически на каждой странице этого раздела приведен живой пример с возможностью редактирования кода.
Мы надеемся, что эта документация поможет вам эффективно использовать **VKUI** и создавать лучшие пользовательские интерфейсы!

## Сообщить о проблеме
---

## Присоединяйтесь к развитию библиотеки [#contributing]

**VKUI** - опенсор-проект, поэтому вы можете поучаствовать в его развитии, рассказав о найденных ошибках или предложив улучшения,
для этого достаточно создать [issue](https://github.com/VKCOM/VKUI/issues/new/choose) на Github.

Если вы столкнулись с какой‑либо ошибкой в нашей библиотеке или у вас есть предложения по её улучшению, пожалуйста, создайте [issue](https://github.com/VKCOM/VKUI/issues/new/choose).
А если у вас возникли вопросы или вы хотите обсудить особенности библиотеки более подробно, присоединяйтесь к обсуждению в ["Дискуссиях"](https://github.com/VKCOM/VKUI/discussions/categories/q-a). Мы стремимся сделать нашу библиотеку ещё лучше, всегда готовы выслушать вас и учесть ваши замечания.
Хотите внести изменение самостоятельно? Ознакомьтесь с [данным гайдом](https://github.com/VKCOM/VKUI/blob/master/docs/CONTRIBUTING.md), прежде чем делать [pull request](https://github.com/VKCOM/VKUI/pulls).

## Contributing
Если у вас возникли вопросы и вы хотите обсудить особенности библиотеки более подробно, присоединяйтесь к обсуждению в ["Дискуссиях"](https://github.com/VKCOM/VKUI/discussions/categories/q-a).

Мы очень радуемся, когда пользователи библиотеки работают над её улучшением. Для того, чтобы оставить след в
истории, сделайте форк проекта, внесите изменения и отправьте нам [pull request](https://github.com/VKCOM/VKUI/pulls).
Мы стремимся сделать нашу библиотеку ещё лучше, всегда готовы выслушать вас и учесть ваши замечания.
Loading

0 comments on commit 039ea4d

Please sign in to comment.