feat(docs): add more docs and components (#8111)

* feat(docs): add vkui-docs-theme component + minimal doc * fix: review notes * feat(docs): add more docs and components * fix: clean up * fix review notes + design review * chore: remove old merge files
VKCOM · Jan 17, 2025 · caa1e30 · caa1e30
1 parent d5e207b
commit caa1e30
Show file tree

Hide file tree

Showing 23 changed files with 722 additions and 148 deletions.
diff --git a/packages/vkui-docs-theme/src/components/Sidebar/Accordion/Accordion.module.css b/packages/vkui-docs-theme/src/components/Sidebar/Accordion/Accordion.module.css
@@ -0,0 +1,4 @@
+.icon {
+  padding-inline: var(--vkui--spacing_size_xs);
+  padding-block: var(--vkui--spacing_size_s);
+}
diff --git a/packages/vkui-docs-theme/src/components/Sidebar/Accordion/Accordion.tsx b/packages/vkui-docs-theme/src/components/Sidebar/Accordion/Accordion.tsx
@@ -9,23 +9,29 @@ 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;
   title: string;
 }
 
+interface AccordionSummaryProps
+  extends Pick<AccordionProps, 'title' | 'className' | 'icon'>,
+    Pick<AccordionProps, 'onChange'> {}
+
 function AccordionSummary({
   title,
   className,
   icon: Icon,
+  onChange,
   ...restProps
-}: Pick<AccordionProps, 'title' | 'className' | 'icon'>) {
-  const { expanded, labelId, contentId, onChange } = React.useContext(AccordionContext);
+}: AccordionSummaryProps) {
+  const { expanded, labelId, contentId } = React.useContext(AccordionContext);
 
   return (
     <Tappable
@@ -35,22 +41,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>
   );

diff --git a/packages/vkui-docs-theme/src/components/Sidebar/Menu/Menu.tsx b/packages/vkui-docs-theme/src/components/Sidebar/Menu/Menu.tsx
@@ -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 {

diff --git a/packages/vkui-docs-theme/src/mdx/Code/Code.module.css b/packages/vkui-docs-theme/src/mdx/Code/Code.module.css
@@ -30,3 +30,13 @@ pre .root {
   /* 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);
+}
diff --git a/packages/vkui-docs-theme/src/mdx/index.module.css b/packages/vkui-docs-theme/src/mdx/index.module.css
@@ -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);
 }

diff --git a/packages/vkui-docs-theme/src/mdx/index.tsx b/packages/vkui-docs-theme/src/mdx/index.tsx
@@ -17,7 +17,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} />,

diff --git a/packages/vkui-docs-theme/styles/global.css b/packages/vkui-docs-theme/styles/global.css
@@ -11,7 +11,6 @@
   -webkit-tap-highlight-color: transparent;
 }
 
-ol,
 ul,
 menu {
   list-style: none;

diff --git a/website/pages/overview/about.mdx b/website/pages/overview/about.mdx
@@ -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).
+Мы стремимся сделать нашу библиотеку ещё лучше, всегда готовы выслушать вас и учесть ваши замечания.
diff --git a/website/pages/overview/adaptivity.mdx b/website/pages/overview/adaptivity.mdx
@@ -3,87 +3,76 @@
 
 Одно из ключевых преимуществ VKUI - адаптивность.
 Библиотека предоставляет шаблоны для различных устройств,
-а также позволяет большинству компонентов адаптировать под разные размеры.
+а также позволяет большинству компонентов адаптироваться под разные размеры.
 Отображение кнопок, элементов форм и других компонентов зависит от наличия мыши, высоты и ширины экрана.
 В этой статье мы покажем, как сделать отзывчивый интерфейс.
 
 </Overview>
 
-## Шаг 1
+## Шаг 1. Обертка [`AdaptivityProvider`](#/AdaptivityProvider)
 
-Для начала оберните ваше приложение в [`AdaptivityProvider`](#/AdaptivityProvider).
-
-```jsx static
-import * as React from 'react';
-import { createRoot } from 'react-dom/client';
-import { ConfigProvider, AdaptivityProvider, AppRoot } from '@vkontakte/vkui';
-import '@vkontakte/vkui/dist/vkui.css';
+Для начала убедитесь, что ваше приложение обернуто в обязательный провайдер [`AdaptivityProvider`](#/AdaptivityProvider):
 
+```jsx {4,6}
 function App() {
   return (
     <ConfigProvider>
       <AdaptivityProvider>
-        <AppRoot>...</AppRoot>
+        <AppRoot>{/* ... */}</AppRoot>
       </AdaptivityProvider>
     </ConfigProvider>
   );
 }
-
-const container = document.getElementById('root');
-const root = createRoot(container); // createRoot(container!) if you use TypeScript
-root.render(<App />);
 ```
 
-## Шаг 2
+## Шаг 2. Добавление контента
 
 Добавьте [`SplitLayout`](#/SplitLayout) и хотя бы один [`SplitCol`](#/SplitCol).
 
-- **SplitLayout** — компонент-обертка для отрисовки макета с
-  одной или несколькими колонками.
+- **SplitLayout** — компонент-обертка для отрисовки макета с одной или несколькими колонками.
 - **SplitCol** — компонент для отрисовки колонки.
 
-```jsx static
-// ...
-
+```jsx {2-3,9-26}
 function App() {
+  const platform = usePlatform();
+  const isVKCOM = platform === 'vkcom';
+
   return (
     <ConfigProvider>
       <AdaptivityProvider>
         <AppRoot>
           <SplitLayout>
-            <SplitCol width={280}>
-              <SideCol />
+            <SplitCol fixed width={280} maxWidth={280}>
+              <Panel>
+                {!isVKCOM && <PanelHeader />}
+                <Group>
+                  <Placeholder>Дополнительный контент</Placeholder>
+                </Group>
+              </Panel>
             </SplitCol>
-            <SplitCol>
-              <MainScreens />
+            <SplitCol width="100%" maxWidth="560px" stretchedOnMobile autoSpaced>
+              <Panel>
+                <PanelHeader>Panel Header</PanelHeader>
+                <Group>
+                  <Placeholder>Главный контент</Placeholder>
+                </Group>
+              </Panel>
             </SplitCol>
           </SplitLayout>
         </AppRoot>
       </AdaptivityProvider>
     </ConfigProvider>
   );
 }
-
-const MainScreens = () => {
-  return (
-    <View activePanel="profile">
-      <Panel id="profile">Profile</Panel>
-    </View>
-  );
-};
-
-const SideCol = () => {
-  return <Panel id="nav">Navigation</Panel>;
-};
 ```
 
-## Шаг 3
+## Шаг 3. Применение хука для адаптивности
 
-Почти готово. Теперь необходимо уведомить приложение о том, что левая колонка нужна только на больших экранах.
-Для этого мы должны использовать хук useAdaptivityConditionalRender в наших компонентах.
+Теперь необходимо уведомить приложение о том, что левая колонка нужна только на больших экранах.
+Для этого мы должны использовать хук `useAdaptivityConditionalRender` в наших компонентах.
 Ниже будет представлен пример использования этого хука, а затем будет дано объяснение его работы.
 
-```jsx static
+```jsx {4,8-17}
 function App() {
   const platform = usePlatform();
   const isVKCOM = platform === 'vkcom';
@@ -93,29 +82,38 @@ function App() {
 
   <SplitLayout header={!isVKCOM && <PanelHeader delimiter="none" />}>
     {viewWidth.tabletPlus && (
-      <SplitCol width={280} className={viewWidth.tabletPlus.className}>
-        <Panel id="nav">Navigation</Panel>
+      <SplitCol fixed width={280} maxWidth={280} className={viewWidth.tabletPlus.className}>
+        {/* ... */}
       </SplitCol>
     )}
-    <SplitCol autoSpaced>
-      <View activePanel="profile">
-        <Panel id="profile">Profile</Panel>
-      </View>
+    <SplitCol width="100%" maxWidth="560px" stretchedOnMobile autoSpaced>
+      {/* ... */}
     </SplitCol>
   </SplitLayout>;
   // ...
 }
 ```
 
-`useAdaptivityConditionalRender` возвращает параметры адаптивности (см. **Технические детали**), каждый из которых имеет
+`useAdaptivityConditionalRender` возвращает параметры адаптивности (см. [Технические детали](#tech)), каждый из которых имеет
 дополнительную мета-информацию. В зависимости от того, что мы передали в `AdaptivityProvider`, значение у каждого отдельного параметра адаптивности
 может быть двух типов:
 
 - `false` – мы строго задали какой-то из параметров адаптивности в `AdaptivityProvider`.
 
+<Callout>
+Например, при `<AdaptivityProvider viewWidth={ViewWidth.MOBILE}>` значение `viewWidth.tabletPlus` будет `false`,
+т.к. мы говорим, что у нас всегда мобильный вид.
+</Callout>
+
 - `{ className: string }` – CSS селектор, который на основе CSS Media Query будет переключать видимость вашего
   элемента. В данном случае в `AdaptivityProvider` не передавали соответствующий параметр адаптивности.
 
+<Callout>
+При значение `{ className: "..." }` видимость элемента управляется через `display: none` – отсюда можно сделать вывод,
+что элемент будет всегда рендерится как в **Virtual DOM**, так и в **DOM**.
+
+</Callout>
+
 ## Требования для адаптивности
 
 - Свойство `SplitLayout.header` нужно для создания сквозной шапки, когда интерфейс состоит из нескольких колонок (или одной центрированной)
@@ -161,7 +159,7 @@ const App = () => {
 В нашем примере внутри `<ModalRoot />` и `<ModalPage />` используется `useAdaptivityWithJSMediaQueries()` для
 переключения компонентов на мобильный или десктопный виды.
 
-## Технические детали
+## Технические детали [#tech]
 
 Адаптивность базируется на четырёх свойствах:
 

diff --git a/website/pages/overview/advanced/_meta.tsx b/website/pages/overview/advanced/_meta.tsx
@@ -0,0 +1,17 @@
+export default {
+  'helpers': {
+    title: 'Утилиты',
+  },
+  'unstable': {
+    title: 'Нестабильные компоненты',
+  },
+  'css-modules': {
+    title: 'CSS Modules',
+  },
+  'customize': {
+    title: 'Кастомизация',
+  },
+  'ssr': {
+    title: 'Серверный рендеринг',
+  },
+};
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,7 +11,6 @@ @@
       -webkit-tap-highlight-color: transparent;
     }
-    ol,
     ul,
     menu {
       list-style: none;
@@ Expand Down @@