feat/tokenized-gradients: wip new gradient helper function

docs/docs.d.ts

@@ -2,3 +2,9 @@ declare module '*.svg' {
 	const content: any;
 	export default content;
 }
+
+declare module '*.md' {
+	const content: any;
+	export default content;
+}
+

docs/src/App.tsx

@@ -2,13 +2,63 @@ import '@vkontakte/vkui/dist/vkui.css';
 import './styles/index.css';
 
 import React, { FC } from 'react';
+import {
+	createBrowserRouter,
+	RouterProvider,
+  } from "react-router-dom";
 
 import Main from '@/components/layouts/Main';
 import Tokens from '@/pages/Tokens';
+import { Articles } from './pages/Articles';
+
+import articleNewTheme from "./articles/NewTheme.md";
+import articleTokenHelpers from "./articles/TokenHelpers.md";
+
+const articles = [
+	{
+		title: "Темы",
+	},
+	{
+		slug: "new-theme",
+		title: "Создание новой темы для проекта",
+		contents: articleNewTheme,
+	},
+	{
+		title: "Токены",
+	},
+	{
+		slug: "token-helpers",
+		title: "Хелпер-функции",
+		contents: articleTokenHelpers,
+	},
+];
+
+const router = createBrowserRouter([
+	{
+		path: "/",
+		element: <Tokens />,
+	},
+	{
+		path: "/articles",
+		element: <Articles items={articles} />
+	},
+	...articles
+		.filter((article) => !!article.slug)
+		.map((article) => (
+			{
+				path: `/articles/${article.slug}`,
+				element: <Articles items={articles} contentsHtml={article.contents}/>
+			}
+		)),
+]);
+
+router.subscribe(() => {
+	window.scrollTo(0, 0);
+});
 
 const App: FC = () => (
 	<Main>
-		<Tokens />
+		<RouterProvider router={router} />
 	</Main>
 );
 

docs/articles/new-theme/INDEX.md → docs/src/articles/NewTheme.md

@@ -1,4 +1,4 @@
-# Создание новой темы для вашего проекта
+# Создание новой темы для проекта
 
 Если вы хотите использовать токены VKUI не только в связке с основной библиотекой, но и в
 произвольной вёрстке, у вас может возникнуть потребность расширения стандартного набора.
@@ -14,7 +14,7 @@
 
 Прежде, чем заводить свою тему, вам нужно ответить для себя на следующий вопрос:
 
-_Какая из базовых тем будет являться основной для вашего проекта?_
+### Какая из базовых тем будет являться основной для вашего проекта?
 
 Выбор базовой темы влияет на внешний вид вашего проекта в тех местах, которые вы не поправите
 в своей теме.

docs/src/articles/TokenHelpers.md

@@ -0,0 +1,211 @@
+# Хелпер-функции для токенов
+Значения токенов бывают разные. Большинство токенов можно выразить либо числом (размеры), либо строкой (цвета, шрифты и прочее).
+
+Но иногда для правильной записи значений базовых типов недостаточно. Бывавет так, что в значении токена нужно сослаться
+на другой токен, или сгенерировать значение токена по набору правил.
+
+Для этих целей в пакете `@vkontakte/vkui-tokens` предусмотрены **функции-хелперы**. Они выполняются на этапе
+сборки темы и позволяют управлять тем, какие значения попадут в итоговые файлы.
+
+ 
+
+## `alias`
+Функция выполняет подстановку значения другого токена.
+
+Будьте осторожны с указанием токенов, которые сами являются ссылками.
+Неправильно указанный токен может привезти к переполнению стека и крешу сборки!
+
+### Интерфейс
+```typescript
+function alias<T extends ThemeDescription>(token: string): TokenFunction<T>;
+```
+
+### Параметры
+* **token** &mdash; Имя токена. Можно использовать токены из текущей темы либо из всех тем, от которой наследуется текущая.
+
+### Пример
+Исходный файл темы:
+
+```typescript
+import { ParadigmThemeDescription } from '@/interfaces/namespaces/paradigm';
+import { lightTheme } from '@/themeDescriptions/base/paradigm';
+import { alias } from '@/build/helpers/tokenHelpers';
+
+export const myCustomTheme: ParadigmThemeDescription = {
+	...lightTheme,
+    sizeArrow: alias('sizeArrowPromo'),
+    sizeArrowPromo: {
+        regular: 8,
+    },
+};
+```
+
+Итоговый файл с темой:
+
+```css
+:root {
+    /* ... */
+    --vkui--size_arrow--regular: 8px;
+    --vkui--size_arrow_promo--regular: 8px;
+    /* ... */
+}
+```
+
+&nbsp;
+
+## `namedAlias`
+Функция создаёт именованый алиас &mdash; runtime-ссылку на другой токен темы выполняет подстановку
+fallback-значения этого токена.
+
+Будьте осторожны с указанием токенов, которые сами являются ссылками.
+Неправильно указанный токен может привезти к переполнению стека и крешу сборки!
+
+### Интерфейс
+```typescript
+function namedAlias<T extends ThemeDescription>(token: string): NamedTokenFunction<T>
+```
+
+### Параметры
+* **token** &mdash; Имя токена. Можно использовать токены из текущей темы либо из всех тем, от которой наследуется текущая.
+
+### Пример
+Исходный файл темы:
+
+```typescript
+import { ParadigmThemeDescription } from '@/interfaces/namespaces/paradigm';
+import { lightTheme } from '@/themeDescriptions/base/paradigm';
+import { namedAlias } from '@/build/helpers/tokenHelpers';
+
+export const myCustomTheme: ParadigmThemeDescription = {
+	...lightTheme,
+    sizeArrow: namedAlias('sizeArrowPromo'),
+    sizeArrowPromo: {
+        regular: 8,
+    },
+};
+```
+
+Итоговый файл с темой:
+
+```css
+:root {
+    /* ... */
+    --vkui--size_arrow--regular: var(--vkui--size_arrow_promo--regular, 8px);
+    --vkui--size_arrow_promo--regular: 8px;
+    /* ... */
+}
+```
+
+&nbsp;
+
+## `staticRef`
+Функция создаёт runtime-ссылку на другой токен темы.
+
+### Интерфейс
+```typescript
+function staticRef<T>(value: Token<T, any>): T;
+```
+
+### Параметры
+* **token** &mdash; Имя токена. Можно использовать любые токены, которые находятся в контексте страницы.
+
+### Пример
+Исходный файл темы:
+
+```typescript
+import { ParadigmThemeDescription } from '@/interfaces/namespaces/paradigm';
+import { lightTheme } from '@/themeDescriptions/base/paradigm';
+import { staticRef } from '@/build/helpers/tokenHelpers';
+
+export const myCustomTheme: ParadigmThemeDescription = {
+	...lightTheme,
+    sizeArrow: staticRef('sizeArrowPromo'),
+    sizeArrowPromo: {
+        regular: 8,
+    },
+};
+```
+
+Итоговый файл с темой:
+
+```css
+:root {
+    /* ... */
+    --vkui--size_arrow--regular: var(--vkui--size_arrow_promo--regular);
+    --vkui--size_arrow_promo--regular: 8px;
+    /* ... */
+}
+```
+
+&nbsp;
+
+## `gradient`
+Функция создаёт градиент из одного или нескольких цветов.
+
+Если передан один цвет, система сборки сгенериурет градиент из указанного цвета в прозрачный. При этом
+градиент будет построен по точкам, указанным в файле `opacityMap.json`.
+
+Если передано два и более цветов, будет сгенерирован градиент между этими цветами с равномерной расстановкой точек.
+
+### Интерфейс
+```typescript
+export function gradient<T extends ThemeDescription> (
+	...stops: (Property.Color | NamedTokenFunction<T>)[]
+): TokenFunction<T>;
+```
+
+### Параметры
+* **stops** &mdash; Список точек градиента. Можно использовать цвета в строковом формате (rgba, hex) и именованые
+  алиасы, созданные с помощью хелпера `namedAlias`.
+
+### Пример
+Исходный файл темы:
+
+```typescript
+import { ParadigmThemeDescription } from '@/interfaces/namespaces/paradigm';
+import { lightTheme } from '@/themeDescriptions/base/paradigm';
+import { gradient, namedAlias } from '@/build/helpers/tokenHelpers';
+
+export const myCustomTheme: ParadigmThemeDescription = {
+	...lightTheme,
+    colorIconPrimary: 'rgba(64, 64, 64, 1)',
+    gradient: gradient(namedAlias('colorIconPrimary'), 'rgba(32, 32, 32, 1)'),
+};
+```
+
+Итоговый файл с темой:
+
+```css
+:root {
+    /* ... */
+    --vkui--color_icon_primary: rgba(64, 64, 64, 1);
+    --vkui--gradient: var(--vkui--color_icon_primary, rgba(64, 64, 64, 1)) 0%, rgba(32, 32, 32, 1) 100%;
+    /* ... */
+}
+```
+
+```json
+{
+    "gradient": {
+        "gradient": [
+            {
+                "color": "rgba(64, 64, 64, 1)",
+                "token": "colorIconPrimary",
+                "step": 0,
+                "alpha": 1
+            },
+            {
+                "color": "rgba(32, 32, 32, 1)",
+                "token": "colorIconPrimary",
+                "step": 1,
+                "alpha": 1
+            }
+        ]
+    },
+    "other": {
+        "colorIconPrimary": {
+            "normal": "rgba(64, 64, 64, 1)"
+        }
+    }
+}
+```

docs/src/components/layouts/shared/AsideMenu/AsideMenu.tsx

@@ -0,0 +1,48 @@
+import { Card, Spacing, Title } from '@vkontakte/vkui';
+import * as React from 'react';
+import { Link } from 'react-router-dom';
+
+export interface AsideMenuItem {
+    slug?: string;
+    title: string;
+}
+
+export interface AsideMenuProps {
+    items?: AsideMenuItem[];
+}
+
+const defaultItems: AsideMenuItem[] = [];
+
+export function AsideMenu(props: AsideMenuProps) {
+    const items = props.items ?? defaultItems;
+
+    return (
+        <aside className="aside-menu">
+            <Card mode="shadow" className="aside-menu_card">
+                <Title level="2" className="aside-menu_title">Разделы</Title>
+                <Spacing size={8}/>
+
+                {items.map((item) => {
+                    if (item.slug) {
+                        return (
+                            <div className="aside-menu-item" key={item.title}>
+                                <Link to={`/articles/${item.slug}`}>{item.title}</Link>
+                            </div>
+                        );
+                    } else {
+                        return (
+                            <React.Fragment key={item.title}>
+                                <Spacing size={20}/>
+                                <Title level="3">{item.title}</Title>
+                                <Spacing size={8}/>
+                            </React.Fragment>
+                        )
+                    }
+                })}
+
+                <Spacing size={32}/>
+                <Link to="/">← К таблице токенов</Link>
+            </Card>
+        </aside>
+    );
+}

docs/src/components/pages/Tokens/TokensHeader.tsx

@@ -1,5 +1,6 @@
-import { Icon16Linked } from '@vkontakte/icons';
+import { Icon16Linked, Icon16HelpOutline } from '@vkontakte/icons';
 import { Link, Title, useAdaptivityWithJSMediaQueries } from '@vkontakte/vkui';
+import { Link as RouterLink } from 'react-router-dom';
 import clsx from 'clsx';
 import React, { FC } from 'react';
 
@@ -42,6 +43,14 @@ const TokensHeader: FC = () => {
 						{version.text}
 					</Link>
 				</div>
+				<div className="flex items-center" style={styles.linkContainer}>
+					<Icon16HelpOutline  style={{ color: '#99A2AD', marginRight: 6 }}/>
+					<RouterLink to="/articles/new-theme" style={{textDecoration: 'none'}}>
+						<Link>
+							Документация
+						</Link>
+					</RouterLink>
+				</div>
 				<div className="flex items-center" style={styles.linkContainer}>
 					<Icon16Linked style={{ color: '#99A2AD', marginRight: 6 }} />
 					<Link href="https://github.com/VKCOM/vkui-tokens" target="_blank">