# Card ## Кратко `Card` — контейнер-поверхность для сгруппированного содержимого: панелей настроек, блоков дашборда и встроенных сводок. Это поверхность для раскладки и группировки, а не примитив обратной связи или статуса. ## Импорты ```tsx import { Card, type CardProps, type CardSize, type CardAppearance, } from '@vega-ui/react'; ``` ## Экспортируемые типы - `CardProps` - `CardSize` - `CardAppearance` ## Базовое использование ```tsx import { Button, Card, Heading, Text } from '@vega-ui/react'; const features = ['Up to 25 members', '100 GB of storage', 'Priority email support', 'SAML single sign-on']; export default function BasicUsage() { return ( Team $12 per member / month ); } ``` ## Варианты - Размеры: `sm`, `md`, `lg` - Оформление: `outline`, `transparent` - Композиция: `article` по умолчанию или `asChild` ## Пограничные случаи - `Card` — поверхность раскладки, а не семантическая замена заголовков или разделов. - Прозрачные карточки работают, только когда контраст уже даёт родительская поверхность. - Внутренние отступы по-прежнему определяет раскладка дочерних элементов. - Если интерфейс пытается сообщить статус или срочность, а не сгруппировать содержимое, обычно понятнее подходят `Alert` или `Badge`. ## Частые ошибки - Ожидать, что `Card` автоматически обеспечит все внутренние отступы раскладки. - Использовать прозрачные карточки на визуально шумных фонах. - Передавать иерархию только через оформление карточки. ## Примеры ### Базовый #### Базовый: тарифный план `Card` рендерит `article`, доступное имя которого берётся из заголовка через `aria-labelledby`. Содержимое выстраивается в колонку, а отступы между дочерними элементами задаёт `gap` на карточке. ```tsx import { Button, Card, Heading, Text } from '@vega-ui/react'; const features = ['Up to 25 members', '100 GB of storage', 'Priority email support', 'SAML single sign-on']; export default function BasicUsage() { return ( Team $12 per member / month ); } ``` #### Базовый: вся карточка — ссылка С `asChild` стили карточки переходят на ``, и вся поверхность становится одной ссылкой с одним доступным именем. Содержимое такой карточки должно быть неинтерактивным: без кнопок и вложенных ссылок. ```tsx import { Card, Heading, Text } from '@vega-ui/react'; import './examples.css'; const destinations = [ { href: '#billing', title: 'Billing', description: 'Plan, invoices and payment methods.' }, { href: '#members', title: 'Members', description: '18 members, 3 pending invitations.' }, { href: '#security', title: 'Security', description: 'Two-factor authentication, sessions and SSO.' }, ]; export default function LinkCards() { return ( ); } ``` ### Контролируемый/с состоянием #### Контролируемый/с состоянием: карточка метрики с обновлением Значение, время обновления и флаг загрузки хранятся в состоянии. Во время обновления карточка получает `aria-busy`, у спиннера своё доступное имя, а кнопка отключена. ```tsx import { useState } from 'react'; import { Button, Card, Heading, Spinner, Text } from '@vega-ui/react'; const formatter = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }); export default function MetricsCard() { const [revenue, setRevenue] = useState(48210.4); const [updatedAt, setUpdatedAt] = useState('09:00'); const [loading, setLoading] = useState(false); const refresh = () => { setLoading(true); setTimeout(() => { const now = new Date(); setRevenue((current) => current + Math.round(Math.random() * 90000) / 100); setUpdatedAt(now.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', hour12: false })); setLoading(false); }, 900); }; return ( Revenue this month
{formatter.format(revenue)} {loading && }
Updated at {updatedAt} ); } ``` ### Форма/интеграция #### Форма/интеграция: карточка и есть форма `asChild` рендерит карточку как `
` с доступным именем из заголовка. Значения читаются через `FormData` при отправке, нативные `required` и `pattern` проверяют поля, а сброс очищает сообщение о статусе. ```tsx import { FormEvent, useState } from 'react'; import { Button, Card, Heading, Label, Text, TextField, TextFieldInput } from '@vega-ui/react'; export default function SettingsFormCard() { const [saved, setSaved] = useState(''); const submit = (event: FormEvent) => { event.preventDefault(); const data = new FormData(event.currentTarget); setSaved(`Saved “${data.get('workspace')}” at ${data.get('slug')}.vega.app`); }; return ( setSaved('')}>
Workspace Shown in invitations and in the browser tab.
{saved}
); } ``` ### Раскладка/оверлей #### Раскладка/оверлей: адаптивная сетка с выровненными действиями `auto-fill` с `minmax(min(220px, 100%), 1fr)` даёт столько колонок, сколько помещается, и не вызывает переполнения на телефонах. Строки сетки растягивают карточки до одной высоты, а `margin-block-start: auto` прижимает кнопки к низу независимо от длины текста. ```tsx import { Button, Card, Heading, Text } from '@vega-ui/react'; const integrations = [ { id: 'slack', name: 'Slack', description: 'Post deployment and incident updates to channels.' }, { id: 'github', name: 'GitHub', description: 'Link pull requests to releases and show build status on every commit, including drafts and forks.' }, { id: 'pagerduty', name: 'PagerDuty Incident Response Orchestration', description: 'Page the on-call engineer.' }, ]; export default function ResponsiveGrid() { return (
{integrations.map((integration) => ( {integration.name} {integration.description} ))}
); } ``` ### Ошибка #### Ошибка: данные не загрузились Карточка сохраняет заголовок и объясняет сбой в области `role='alert'` с действием повтора. Повтор показывает состояние загрузки перед появлением данных. ```tsx import { useState } from 'react'; import { Button, Card, Heading, Spinner, Text } from '@vega-ui/react'; type State = 'failed' | 'loading' | 'loaded'; export default function LoadErrorCard() { const [state, setState] = useState('failed'); const retry = () => { setState('loading'); setTimeout(() => setState('loaded'), 900); }; return ( API usage {state === 'loading' && } {state === 'failed' && (
Usage could not be loaded: the metrics service timed out.
)} {state === 'loaded' && ( 1.82 M of 2 M requests used this month )} ); } ``` ### Отключённый #### Отключённый: данные только для чтения для не-владельцев У `Card` нет собственного отключённого состояния. `
` внутри карточки отключает все поля сразу, а объяснение связано через `aria-describedby`. ```tsx import { Card, Heading, Label, Text, TextField, TextFieldInput } from '@vega-ui/react'; export default function ReadOnlyBilling() { return (
Billing contact Only workspace owners can change billing details. Ask Maria Chen to update them.
); } ``` ### Пограничный случай #### Пограничный случай: пустое состояние и сотни элементов Одна и та же карточка справляется и с нулём, и с 240 элементами. Пустое состояние объясняет, что делать дальше; длинный список прокручивается внутри карточки, а область прокрутки фокусируема и имеет имя, чтобы её можно было прокрутить с клавиатуры. ```tsx import { useState } from 'react'; import { Button, Card, Heading, Text } from '@vega-ui/react'; const allKeys = Array.from({ length: 240 }, (_, index) => `sk_live_${String(index + 1).padStart(4, '0')}`); export default function EmptyAndMany() { const [keys, setKeys] = useState([]); const toggle = () => { if (keys.length === 0) { setKeys(allKeys); return; } setKeys([]); }; return (
API keys ({keys.length})
{keys.length === 0 && ( No API keys yet. Create one to call the API from your servers. )} {keys.length > 0 && (
    {keys.map((key) => (
  • {key}
    • ))}
)} ); } ``` ## Анатомия ### Обзор `Card` — единый контейнер-поверхность для группировки без публичных дочерних частей. Его анатомия — одна корневая поверхность плюс заголовки, основной текст, метрики или действия, которые размещает потребитель. ### Обязательные части #### `Card` Обязательна. Владеет оформлением поверхности, внутренними отступами и необязательным полиморфным рендером через `asChild`. ### Необязательные части `Card` не предоставляет публичных дочерних частей. ### Порядок композиции 1. `Card` 2. заголовок, текст, действия или дочерние элементы раскладки ### Допустимые варианты композиции ```tsx import { Button, Card, Heading, Text } from '@vega-ui/react'; const features = ['Up to 25 members', '100 GB of storage', 'Priority email support', 'SAML single sign-on']; export default function BasicUsage() { return ( Team $12 per member / month
    {features.map((feature) => (
  • {feature}
    • ))}
); } ``` ### Недопустимые варианты композиции #### Карточка как единственная семантическая структура Поверхность не должна заменять заголовки, ориентиры или настоящую иерархию содержимого. #### Прозрачная карточка на низкоконтрастном фоне Сгруппированное содержимое может полностью потерять визуальное отделение.