feat(docs): add vkui-docs-theme components + minimal doc

packages/vkui-docs-theme/index.ts

@@ -1,2 +1,7 @@
 import Layout from './src/index';
+import type { PartialDocsThemeConfig as DocsThemeConfig } from './src/types';
+
+export { useFetch } from './src/hooks/useFetch';
+export { StorybookIcon, GithubIcon, FigmaIcon } from './src/icons';
+export { type DocsThemeConfig };
 export default Layout;

packages/vkui-docs-theme/src/components/Anchor.tsx

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import { type LinkProps, Link as VKUILink } from '@vkontakte/vkui';
+import NextLink from 'next/link';
+
+const EXTERNAL_HREF_REGEX = /https?:\/\//;
+
+const Link = React.forwardRef<HTMLAnchorElement, LinkProps>((props, ref) => (
+  <VKUILink {...props} getRootRef={ref} />
+));
+Link.displayName = 'VKUILinkWithRef';
+
+export function Anchor({ href = '', children, ...props }: LinkProps) {
+  const newWindow = EXTERNAL_HREF_REGEX.test(href);
+
+  if (newWindow) {
+    return (
+      <Link href={href} target="_blank" rel="noreferrer" {...props}>
+        {children}
+      </Link>
+    );
+  }
+
+  return (
+    <NextLink href={href} {...props} passHref legacyBehavior>
+      <Link>{children}</Link>
+    </NextLink>
+  );
+}

packages/vkui-docs-theme/src/components/Breadcrumbs/Breadcrumbs.module.css

@@ -0,0 +1,25 @@
+.root {
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+}
+
+/* stylelint-disable-next-line selector-max-universal */
+.root > .item:not(:last-child),
+.root > .icon {
+  margin-inline-end: 4px;
+}
+
+.item {
+  color: var(--vkui--color_text_secondary);
+
+  --vkui--color_text_link: var(--vkui--color_text_secondary);
+}
+
+.icon {
+  color: var(--vkui--color_icon_secondary);
+}
+
+.activeItem {
+  color: var(--vkui--color_text_primary);
+}

packages/vkui-docs-theme/src/components/Breadcrumbs/Breadcrumbs.tsx

@@ -0,0 +1,26 @@
+import { Fragment } from 'react';
+import { Icon12ChevronOutline } from '@vkontakte/icons';
+import { classNames, Footnote } from '@vkontakte/vkui';
+import type { Item } from 'nextra/normalize-pages';
+import { Anchor } from '../Anchor';
+import styles from './Breadcrumbs.module.css';
+
+export function Breadcrumbs({ activePath }: { activePath: Item[] }) {
+  return (
+    <div className={styles.root}>
+      {activePath.map((item, index) => {
+        const isLink = !item.children || item.withIndexPage;
+        const isActive = index === activePath.length - 1;
+
+        return (
+          <Fragment key={`${item.route}-${item.name}`}>
+            {index > 0 && <Icon12ChevronOutline aria-hidden className={classNames(styles.icon)} />}
+            <Footnote className={classNames(styles.item, isActive && styles.activeItem)}>
+              {isLink && !isActive ? <Anchor href={item.route}>{item.title}</Anchor> : item.title}
+            </Footnote>
+          </Fragment>
+        );
+      })}
+    </div>
+  );
+}

packages/vkui-docs-theme/src/components/ColorSchemeSwitch.tsx

@@ -0,0 +1,33 @@
+import { Icon20MoonOutline, Icon20SunOutline } from '@vkontakte/icons';
+import { AdaptivityProvider, SegmentedControl, Skeleton } from '@vkontakte/vkui';
+import { useMounted } from 'nextra/hooks';
+import { useColorScheme } from '../contexts';
+
+const options = [
+  { 'value': 'light', 'label': <Icon20SunOutline />, 'aria-label': 'Переключить на светлую тему' },
+  { 'value': 'dark', 'label': <Icon20MoonOutline />, 'aria-label': 'Переключить на тёмную тему' },
+];
+
+const SWITCH_WIDTH = 94;
+
+export function ColorSchemeSwitch() {
+  const { setColorScheme, resolvedColorScheme } = useColorScheme();
+  const mounted = useMounted();
+
+  if (!mounted) {
+    return <Skeleton width={SWITCH_WIDTH} height={36} />;
+  }
+
+  return (
+    <AdaptivityProvider sizeY="compact">
+      <SegmentedControl
+        size="l"
+        style={{ width: SWITCH_WIDTH }}
+        value={resolvedColorScheme}
+        // @ts-expect-error: TS2322 VKUI fix types?
+        onChange={setColorScheme}
+        options={options}
+      />
+    </AdaptivityProvider>
+  );
+}

packages/vkui-docs-theme/src/components/Head.tsx

@@ -0,0 +1,29 @@
+import NextHead from 'next/head';
+import { useMounted } from 'nextra/hooks';
+import { useColorScheme, useThemeConfig } from '../contexts';
+
+export function Head() {
+  const themeConfig = useThemeConfig();
+  const { resolvedColorScheme } = useColorScheme();
+  const mounted = useMounted();
+
+  const head = typeof themeConfig.head === 'function' ? themeConfig.head({}) : themeConfig.head;
+
+  return (
+    <NextHead>
+      {mounted ? (
+        <meta name="theme-color" content={resolvedColorScheme === 'dark' ? '#111' : '#fff'} />
+      ) : (
+        <>
+          <meta name="theme-color" content="#fff" media="(prefers-color-scheme: light)" />
+          <meta name="theme-color" content="#111" media="(prefers-color-scheme: dark)" />
+        </>
+      )}
+      <meta
+        name="viewport"
+        content="width=device-width, initial-scale=1, shrink-to-fit=no, user-scalable=no, viewport-fit=cover"
+      />
+      {head}
+    </NextHead>
+  );
+}

packages/vkui-docs-theme/src/components/NavLinks/NavLinks.module.css

@@ -0,0 +1,38 @@
+.root {
+  display: flex;
+  align-items: center;
+  padding-block-start: var(--vkui--spacing_size_4xl);
+  border-block-start: 1px solid var(--vkui_docs--color_stroke_separator_secondary);
+  margin-block-start: 56px;
+}
+
+.navLinkItem {
+  display: flex;
+  flex-direction: column;
+  color: var(--vkui--color_text_subhead);
+  align-items: flex-end;
+  padding-block: var(--vkui--spacing_size_m);
+  padding-inline: var(--vkui--spacing_size_xl);
+  text-decoration: none;
+}
+
+.navLink {
+  margin-block-start: var(--vkui--spacing_size_s);
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  color: var(--vkui--color_text_primary);
+}
+
+.navLinkItemNext {
+  margin-inline-start: auto;
+  align-items: flex-start;
+}
+
+.navLinkPrevIcon {
+  margin-inline-end: var(--vkui--spacing_size_m);
+}
+
+.navLinkNextIcon {
+  margin-inline-start: var(--vkui--spacing_size_m);
+}

packages/vkui-docs-theme/src/components/NavLinks/NavLinks.tsx

@@ -0,0 +1,69 @@
+import * as React from 'react';
+import { Icon16ChevronLeft, Icon16ChevronOutline } from '@vkontakte/icons';
+import { classNames } from '@vkontakte/vkjs';
+import { Footnote, Headline, Tappable } from '@vkontakte/vkui';
+import NextLink from 'next/link';
+import type { Item } from 'nextra/normalize-pages';
+import { useThemeConfig } from '../../contexts';
+import styles from './NavLinks.module.css';
+
+interface NavLinkProps {
+  currentIndex: number;
+  flatDirectories: Item[];
+}
+
+interface NavLinkItemProps {
+  route: string;
+  children: React.ReactNode;
+  className?: string;
+  type?: 'prev' | 'next';
+}
+
+function NavLinkItem({ type = 'prev', route, children, className }: NavLinkItemProps) {
+  return (
+    <Tappable
+      Component={NextLink}
+      href={route}
+      className={classNames(styles.navLinkItem, className)}
+    >
+      <Footnote>{type === 'next' ? 'Следующая' : 'Предыдущая'}</Footnote>
+      <div className={classNames(styles.navLink)}>{children}</div>
+    </Tappable>
+  );
+}
+
+export function NavLinks({ flatDirectories, currentIndex }: NavLinkProps) {
+  const themeConfig = useThemeConfig();
+  const nav = themeConfig.navigation;
+  const navigation = typeof nav === 'boolean' ? { prev: nav, next: nav } : nav;
+  let prev = navigation.prev && flatDirectories[currentIndex - 1];
+  let next = navigation.next && flatDirectories[currentIndex + 1];
+
+  if (prev && !prev.isUnderCurrentDocsTree) {
+    prev = false;
+  }
+  if (next && !next.isUnderCurrentDocsTree) {
+    next = false;
+  }
+
+  if (!prev && !next) {
+    return null;
+  }
+
+  return (
+    <div className={styles.root}>
+      {prev && (
+        <NavLinkItem route={prev.route}>
+          <Icon16ChevronLeft className={styles.navLinkPrevIcon} aria-hidden />
+          <Headline>{prev.title}</Headline>
+        </NavLinkItem>
+      )}
+      {next && (
+        <NavLinkItem route={next.route} className={styles.navLinkItemNext} type="next">
+          <Headline>{next.title}</Headline>
+          <Icon16ChevronOutline className={styles.navLinkNextIcon} aria-hidden />
+        </NavLinkItem>
+      )}
+    </div>
+  );
+}

packages/vkui-docs-theme/src/components/Navbar/Navbar.module.css

@@ -0,0 +1,102 @@
+.root {
+  position: sticky;
+  inset-block-start: 0;
+  z-index: 20;
+  inline-size: 100%;
+  background-color: transparent;
+  color: var(--vkui--color_text_primary);
+  border-block-end: var(--vkui--size_border--regular) solid
+    var(--vkui_docs--color_stroke_separator_secondary);
+  box-shadow: 0 8px 30px 0 rgba(0, 0, 0, 0.04);
+}
+
+.navbar {
+  display: flex;
+  margin-inline: auto;
+  align-items: center;
+  block-size: var(--vkui_docs--navbar-height);
+  max-inline-size: var(--vkui_docs--max-width);
+  justify-content: space-between;
+  padding-block: var(--vkui--spacing_size_xl);
+  padding-inline: var(--vkui--spacing_size_2xl);
+  background-color: var(--vkui--color_background_content);
+}
+
+@media (--viewWidth-desktopPlus) {
+  .navbar {
+    padding-inline: 40px;
+    padding-block: var(--vkui--spacing_size_4xl);
+  }
+}
+
+.extraContent {
+  display: none;
+}
+
+@media (--viewWidth-desktopPlus) {
+  .extraContent {
+    display: flex;
+    align-items: center;
+  }
+}
+
+/* stylelint-disable-next-line selector-max-universal */
+.extraContent > *:not(:first-child) {
+  margin-inline-start: var(--vkui--spacing_size_m);
+}
+
+.navbarLink {
+  color: var(--vkui--color_text_primary);
+  padding-block: 8px;
+  padding-inline: 16px;
+  text-decoration: none;
+}
+
+.navbarLink:not(:last-child) {
+  margin-inline-end: var(--vkui--spacing_size_m);
+}
+
+.navbarLinkActive {
+  background-color: var(--vkui--color_field_background);
+}
+
+.links {
+  display: none;
+}
+
+@media (--viewWidth-desktopPlus) {
+  .links {
+    display: flex;
+    block-size: 36px;
+    align-items: stretch;
+  }
+}
+
+.separator.separator {
+  color: var(--vkui_docs--color_stroke_separator_secondary);
+  margin-inline-end: var(--vkui--spacing_size_m);
+}
+
+.logoLink {
+  color: var(--vkui--color_text_primary);
+}
+
+@media (--viewWidth-desktopPlus) {
+  .menuButton {
+    display: none;
+  }
+}
+
+.menuIcon {
+  box-sizing: initial;
+}
+
+.search {
+  inline-size: 200px;
+}
+
+@media (--viewWidth-smallTabletMinus) {
+  .search {
+    display: none;
+  }
+}