@ciromaciel/dashboard-kit 1.0.0

package/src/components/SidebarShell.jsx

@@ -0,0 +1,271 @@
+import { ActionIcon, Box, ScrollArea, Stack, Text, TextInput } from '@mantine/core'
+import { IconSearch, IconX } from '@tabler/icons-react'
+
+import { GroupLabel } from './GroupLabel'
+import { ListSkeleton } from './ListSkeleton'
+import { NavItem } from './NavItem'
+
+/**
+ * A coluna lateral de um painel, por CONFIGURAÇÃO em vez de por cópia.
+ *
+ * A comparação que originou este componente: `payments` e `messages` tinham 596
+ * de 612 linhas de código IDÊNTICAS (97,4%), e as 16 que diferiam eram o array
+ * de seções, o import de ícones e um identificador traduzido. Os outros cinco
+ * seguiam o mesmo desenho com outros substantivos.
+ *
+ * A FORMA DA COLUNA É UMA SÓ, e ela conta uma história em duas metades:
+ *
+ *   FORA de um recurso — busca, ação de criar, e a lista do que existe.
+ *   DENTRO de um recurso — o nome dele, as seções DELE, e a volta.
+ *
+ * As duas nunca convivem: empilhá-las fazia a coluna rolar e escondia as
+ * seções, que são o motivo de se ter entrado no recurso.
+ *
+ * OS TRÊS SLOTS DE EXTENSÃO existem porque três painéis precisam de algo que os
+ * outros quatro não têm — e cada um é usado UMA vez, que é o teste de "isto é
+ * do produto":
+ *
+ *   `renderGroups`  o Auth tem dois níveis (organização → aplicação) e precisa
+ *                   de cabeçalho de grupo interativo.
+ *   `partition`     o Hoster fatia a lista em Fixados/Recentes/Todos — a única
+ *                   resposta na casa ao problema "dezenove projetos não cabem".
+ *   `footer`        o cartão de usuário, que o Functions monta diferente por
+ *                   causa do modo `dev-user`, sem sessão do Auth.
+ *
+ * A BUSCA APARECE POR LIMIAR, não sempre: com três itens ela é cromo, e o custo
+ * de não tê-la é zero. `searchThreshold: 0` a mantém fixa; `null` a remove (é o
+ * caso do Monitors, que não tem lista).
+ *
+ * Nada de quota entra aqui. O painel resolve o gate e passa `createAllowed`
+ * booleano — a coluna não sabe o que é um plano.
+ */
+export function SidebarShell({
+    // ── fora do recurso ──────────────────────────────────────────────────
+    items = [],
+    loading = false,
+    groupLabel,
+    emptyLabel = 'Nenhum item',
+    emptySearchLabel = 'Nenhum resultado',
+    searchPlaceholder,
+    searchThreshold = 0,
+    searchFields = ['name'],
+    term = '',
+    onTermChange,
+    renderItem,
+    renderGroups,
+    partition,
+    // ── a ação de criar ──────────────────────────────────────────────────
+    createIcon,
+    createLabel,
+    createBlockedLabel,
+    createAllowed = true,
+    onCreate,
+    onCreateBlocked,
+    // ── dentro do recurso ────────────────────────────────────────────────
+    activeResource,
+    backIcon,
+    backLabel,
+    onBack,
+    sections = [],
+    currentSection,
+    onSectionChange,
+    // ── o que fica em volta ──────────────────────────────────────────────
+    header,
+    accountNav,
+    footer,
+    children,
+}) {
+    const busca = term.trim().toLowerCase()
+
+    const filtrados = busca
+        ? items.filter(item =>
+              searchFields.some(campo =>
+                  String(item[campo] ?? '')
+                      .toLowerCase()
+                      .includes(busca),
+              ),
+          )
+        : items
+
+    // `null` remove a busca; `0` a mantém fixa; um número a revela a partir
+    // dali. Quem já digitou continua vendo o campo mesmo que o filtro tenha
+    // reduzido a lista abaixo do limiar — tirá-lo no meio da digitação seria
+    // arrancar o que a pessoa está usando.
+    const mostrarBusca = searchThreshold !== null && !activeResource && (items.length >= searchThreshold || Boolean(term))
+
+    const faixas = partition ? partition(filtrados) : null
+
+    return (
+        <Stack
+            gap={2}
+            h="100%"
+            p="16px 12px"
+            align="stretch"
+            w="100%"
+            style={{ overflow: 'hidden' }}
+        >
+            {header}
+
+            {mostrarBusca && (
+                <Box
+                    px={12}
+                    pb={8}
+                    w="100%"
+                >
+                    <TextInput
+                        value={term}
+                        onChange={e => onTermChange?.(e.currentTarget.value)}
+                        onKeyDown={e => e.key === 'Escape' && onTermChange?.('')}
+                        placeholder={searchPlaceholder}
+                        aria-label={searchPlaceholder}
+                        leftSection={
+                            <IconSearch
+                                size={14}
+                                stroke={1.5}
+                            />
+                        }
+                        rightSection={
+                            term ? (
+                                <ActionIcon
+                                    size="xs"
+                                    color="gray"
+                                    variant="transparent"
+                                    onClick={() => onTermChange?.('')}
+                                    aria-label="Limpar busca"
+                                >
+                                    <IconX
+                                        size={14}
+                                        stroke={1.5}
+                                    />
+                                </ActionIcon>
+                            ) : null
+                        }
+                        styles={{ input: { fontSize: 12, background: 'var(--mantine-color-gray-1)' } }}
+                    />
+                </Box>
+            )}
+
+            {activeResource ? (
+                <NavItem
+                    icon={backIcon}
+                    label={backLabel}
+                    onClick={onBack}
+                />
+            ) : (
+                <>
+                    {/*
+                      Criar fica ANTES da lista: com muitos recursos a lista
+                      rola, e uma ação no fim de uma área de rolagem é uma ação
+                      que se procura.
+
+                      No limite do plano o item NÃO some — ele leva para os
+                      planos. Escondê-lo deixaria o limite invisível, e a pessoa
+                      procuraria o botão em vez de descobrir que precisa de
+                      upgrade.
+                    */}
+                    {onCreate && (
+                        <NavItem
+                            icon={createIcon}
+                            label={createAllowed ? createLabel : createBlockedLabel}
+                            muted={!createAllowed}
+                            onClick={createAllowed ? onCreate : onCreateBlocked}
+                        />
+                    )}
+
+                    {groupLabel && <GroupLabel>{groupLabel}</GroupLabel>}
+                </>
+            )}
+
+            {/*
+              A lista rola sozinha e o resto da coluna fica parado: com muitos
+              recursos, o cartão do usuário continua onde o dedo espera achá-lo.
+
+              `scrollbars="y"` porque a rolagem horizontal não deve existir numa
+              coluna de largura fixa — e ela aparecia, com o conteúdo mais largo
+              ditando a largura da coluna.
+            */}
+            {!activeResource && (
+                <ScrollArea.Autosize
+                    style={{ flex: 1, width: '100%' }}
+                    type="auto"
+                    scrollbars="y"
+                    className="zen-sidebar-scroll"
+                >
+                    <Stack
+                        gap={2}
+                        w="100%"
+                    >
+                        {loading ? (
+                            <ListSkeleton />
+                        ) : filtrados.length === 0 ? (
+                            <Box py={16}>
+                                <Text
+                                    fz={10}
+                                    fw={800}
+                                    c="gray.4"
+                                    tt="uppercase"
+                                    lts="1.5px"
+                                    ta="center"
+                                >
+                                    {term ? emptySearchLabel : emptyLabel}
+                                </Text>
+                            </Box>
+                        ) : renderGroups ? (
+                            renderGroups(filtrados)
+                        ) : faixas ? (
+                            faixas.map(faixa => (
+                                <Box key={faixa.label ?? 'sem-faixa'}>
+                                    {faixa.label && <GroupLabel>{faixa.label}</GroupLabel>}
+                                    {faixa.items.map(renderItem)}
+                                </Box>
+                            ))
+                        ) : (
+                            filtrados.map(renderItem)
+                        )}
+                    </Stack>
+                </ScrollArea.Autosize>
+            )}
+
+            <Stack
+                gap={2}
+                flex={activeResource ? 1 : 'none'}
+                w="100%"
+                align="center"
+            >
+                {activeResource && (
+                    <>
+                        {activeResource}
+                        {sections.map(item => (
+                            <NavItem
+                                key={item.id}
+                                icon={item.icon}
+                                label={item.label}
+                                active={currentSection === item.id}
+                                onClick={() => onSectionChange?.(item)}
+                            />
+                        ))}
+                    </>
+                )}
+            </Stack>
+
+            {accountNav}
+
+            {/*
+              O rodapé é o cartão do usuário: Docs e Suporte vivem dentro do
+              menu dele, junto de Conta e Assinatura. Na coluna, competiriam com
+              a lista — que é o assunto da coluna.
+            */}
+            {footer && (
+                <Box
+                    pt={16}
+                    w="100%"
+                    style={{ borderTop: 'var(--rlg-border)' }}
+                >
+                    {footer}
+                </Box>
+            )}
+
+            {children}
+        </Stack>
+    )
+}

package/src/components/SupportModal.jsx

@@ -0,0 +1,269 @@
+import { useEffect, useState } from 'react'
+import { Box, Button, Group, Modal, ScrollArea, Stack, Text, Title } from '@mantine/core'
+import { IconMail } from '@tabler/icons-react'
+
+import { ZenLabel } from './ZenLabel'
+
+/**
+ * Support — one e-mail, with the technical context already attached, and the
+ * API's real state measured on the spot.
+ *
+ * This modal operates nothing. It convinces you there is someone on the other
+ * side, which is why the display is 36px.
+ *
+ * ONE FORM, NO EXCEPTIONS — a deliberate call, and it costs something.
+ *
+ * Four dashboards carried a copy. Messages and Payments were the same file
+ * except for one string. The other two had diverged, and adopting this drops
+ * what made them different:
+ *
+ *   - Monitors rendered the state through `StatusDot`, its only emitter of
+ *     state colour, with FOUR values (up, degraded, down, no data). Here there
+ *     are three, so "degraded" no longer has its own reading in this modal.
+ *     `StatusDot` stays in charge everywhere else in that dashboard.
+ *   - Hoster ran this modal through `react-i18next` and built its context as a
+ *     padEnd-aligned table. The text is Portuguese literal now, like the other
+ *     six panels.
+ *
+ * The only thing a product still supplies is `contextRows` — the lines that
+ * name ITS resources (a project, a domain, a monitor). Everything else is the
+ * same in all four.
+ *
+ * @param {string}   productName  Names the mail subject: "Suporte · RiLiGar <name>".
+ * @param {string}   apiUrl       The root that gets measured. `GET /` must be public.
+ * @param {string[]} contextRows  Lines appended to the mail body, already formatted.
+ */
+
+const DEFAULT_SUPPORT_EMAIL = 'team@myinfrastructure.click'
+
+/**
+ * Measures the API when the modal opens, and again on every opening — the
+ * state ten minutes ago does not describe the state now.
+ *
+ * `status` leaves 'idle' on the RESPONSE, not before it: writing 'loading' in
+ * the effect body would be a synchronous setState, a cascading render to say
+ * what the absence of a response already says. The status line treats 'idle'
+ * and 'loading' as the same "verificando…".
+ */
+export function useHealthCheck(enabled, apiUrl) {
+    const [health, setHealth] = useState({ status: 'idle' })
+
+    useEffect(() => {
+        if (!enabled || !apiUrl) return
+
+        let cancelled = false
+        const startedAt = performance.now()
+
+        fetch(`${apiUrl}/`, { cache: 'no-store' })
+            .then(response => {
+                const elapsed = Math.round(performance.now() - startedAt)
+                if (cancelled) return
+                if (!response.ok) {
+                    setHealth({ status: 'down', code: response.status, elapsed })
+                    return
+                }
+                setHealth({ status: 'up', elapsed })
+            })
+            .catch(() => {
+                if (cancelled) return
+                setHealth({ status: 'down' })
+            })
+
+        return () => {
+            cancelled = true
+            setHealth({ status: 'idle' })
+        }
+    }, [enabled, apiUrl])
+
+    return health
+}
+
+/**
+ * The status light.
+ *
+ * `--rlg-status-up` is the system's only green, and it exists because this is
+ * NOT the success of an action (that is gray.9 + IconCheck): it is the measured
+ * state of an external system, and it never appears without the word next to
+ * it.
+ */
+export function HealthRow({ health, host }) {
+    const label = health.status === 'up' ? 'No ar' : health.status === 'down' ? 'Sem resposta' : 'Verificando…'
+    const color = health.status === 'up' ? 'var(--rlg-status-up)' : health.status === 'down' ? 'var(--mantine-color-red-6)' : 'var(--mantine-color-gray-4)'
+
+    return (
+        <Group
+            justify="space-between"
+            wrap="nowrap"
+            gap={12}
+            px={{ base: 16, sm: 20 }}
+            py={14}
+            style={{ border: 'var(--rlg-border)', background: 'var(--mantine-color-gray-1)' }}
+        >
+            <Group
+                gap={8}
+                wrap="nowrap"
+                miw={0}
+            >
+                <Box
+                    w={7}
+                    h={7}
+                    style={{ borderRadius: '50%', background: color, flex: 'none' }} // design-system-ignore: semáforo de status
+                />
+                <Text
+                    fz={12}
+                    fw={600}
+                    c="gray.9"
+                    lineClamp={1}
+                >
+                    {label}
+                </Text>
+            </Group>
+            <Text
+                fz={10}
+                fw={800}
+                c="gray.4"
+                ff="monospace"
+                style={{ whiteSpace: 'nowrap' }}
+            >
+                {host}
+                {health.elapsed ? ` · ${health.elapsed}ms` : ''}
+            </Text>
+        </Group>
+    )
+}
+
+export function SupportModal({
+    opened,
+    onClose,
+    productName,
+    apiUrl,
+    contextRows = [],
+    supportEmail = DEFAULT_SUPPORT_EMAIL,
+    label = '+ Suporte',
+    title = 'Fale com quem',
+    titleTail = 'escreveu o código.',
+    description = 'Não há fila nem robô. O e-mail abaixo já vai com o contexto técnico anexado — conta, projeto e o estado da API medido agora.',
+    subject,
+}) {
+    const health = useHealthCheck(opened, apiUrl)
+
+    /*
+     * A warning, not an exception — same posture as `Wordmark`, and for the same
+     * reason. Without `productName` the mail subject reads "Suporte · RiLiGar
+     * undefined"; without `apiUrl` the status line measures nothing and the body
+     * reports "não verificado". Neither breaks the build, and neither shows up
+     * until someone reads the e-mail that arrived.
+     *
+     * Verified by sabotage: removing `productName` from a panel's adapter builds
+     * green and ships the broken subject.
+     */
+    if (typeof console !== 'undefined') {
+        if (!productName) console.warn('[dashboard-kit] <SupportModal> without `productName`: the mail subject reads "Suporte · RiLiGar undefined". Pass `productName`.')
+        if (!apiUrl) console.warn('[dashboard-kit] <SupportModal> without `apiUrl`: nothing is measured and the e-mail reports "não verificado".')
+    }
+
+    /** The host shown on the status line — the domain, without the protocol. */
+    const host = apiUrl?.replace(/^https?:\/\//, '').replace(/\/$/, '')
+
+    const apiState = health.status === 'up' ? `no ar (${health.elapsed}ms)` : health.status === 'down' ? 'sem resposta' : 'não verificado'
+
+    /*
+     * The body goes out already filled in with what always gets asked back.
+     * `contextRows` is what the product adds — it is the only part that differs,
+     * and passing it in beats maintaining four copies of the whole modal.
+     */
+    const body = ['Descreva o que aconteceu:', '', '', '---', ...contextRows, `API: ${host}`, `Estado da API: ${apiState}`, `Navegador: ${navigator.userAgent}`].join('\n')
+
+    const mailSubject = subject ?? `Suporte · RiLiGar ${productName}`
+    const mailto = `mailto:${supportEmail}?subject=${encodeURIComponent(mailSubject)}&body=${encodeURIComponent(body)}`
+
+    return (
+        <Modal
+            opened={opened}
+            onClose={onClose}
+            size={620}
+            padding={0}
+            withCloseButton={false}
+            scrollAreaComponent={ScrollArea.Autosize}
+        >
+            <Stack
+                gap={0}
+                p={{ base: 20, sm: 32 }}
+            >
+                <ZenLabel>{label}</ZenLabel>
+
+                <Title
+                    order={2}
+                    fw={900}
+                    fz={{ base: 26, sm: 36 }}
+                    lh={1.05}
+                    mt={12}
+                    ls="-0.04em"
+                    c="gray.9"
+                >
+                    {title}{' '}
+                    <Text
+                        span
+                        inherit
+                        c="gray.6"
+                    >
+                        {titleTail}
+                    </Text>
+                </Title>
+
+                <Text
+                    fz={14}
+                    c="gray.6"
+                    lh={1.65}
+                    maw={520}
+                    mt={14}
+                >
+                    {description}
+                </Text>
+
+                <Box
+                    mt={28}
+                    pt={24}
+                    style={{ borderTop: 'var(--rlg-border)' }}
+                >
+                    <Stack gap={16}>
+                        <HealthRow
+                            health={health}
+                            host={host}
+                        />
+
+                        <Group gap={8}>
+                            <Button
+                                color="gray.9"
+                                component="a"
+                                href={mailto}
+                                leftSection={
+                                    <IconMail
+                                        size={16}
+                                        stroke={1.5}
+                                    />
+                                }
+                            >
+                                Escrever para o suporte
+                            </Button>
+                            <Button
+                                variant="outline"
+                                color="gray.9"
+                                onClick={onClose}
+                            >
+                                Fechar
+                            </Button>
+                        </Group>
+
+                        <Text
+                            fz={12}
+                            c="gray.5"
+                        >
+                            {supportEmail}
+                        </Text>
+                    </Stack>
+                </Box>
+            </Stack>
+        </Modal>
+    )
+}

package/src/components/TableSkeleton.jsx

@@ -0,0 +1,43 @@
+import { Box, Skeleton } from '@mantine/core'
+import { useMediaQuery } from '@mantine/hooks'
+import { templateFor, ROW_PADDING } from './table-grid'
+
+/**
+ * Skeleton beats spinner: it reproduces the REAL grid of the content, so the
+ * layout doesn't jump when the data arrives (Law 3 — and one of the spec's
+ * blockers: "metric or table without a skeleton shaped like the content").
+ *
+ * That's why it takes the SAME `columns` as the DataTable and derives the
+ * gridTemplateColumns and the padding from them — there is no way for the two
+ * grids to diverge, because they are the same expression.
+ */
+export function TableSkeleton({ columns, rows = 5 }) {
+    const wide = useMediaQuery('(min-width: 48em)', true)
+    const visible = wide ? columns : columns.filter(col => !col.hideBelow)
+    const template = templateFor(visible)
+
+    return Array.from({ length: rows }, (_, i) => (
+        <Box
+            key={i}
+            style={{
+                display: 'grid',
+                gridTemplateColumns: template,
+                gap: 16,
+                alignItems: 'center',
+                padding: ROW_PADDING,
+                borderBottom: i === rows - 1 ? 'none' : 'var(--rlg-border)',
+            }}
+        >
+            {visible.map(col => (
+                <Box key={col.key}>
+                    {col.label || col.skeleton ? (
+                        <Skeleton
+                            height={14}
+                            width={col.skeletonWidth || '60%'}
+                        />
+                    ) : null}
+                </Box>
+            ))}
+        </Box>
+    ))
+}