@ciromaciel/dashboard-kit 1.0.0

package/src/components/HoldToConfirm.jsx

@@ -0,0 +1,151 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { ActionIcon, Box, Button, RingProgress, Text, Tooltip } from '@mantine/core'
+
+const HOLD_MS = 3000
+const TICK_MS = 50
+
+/**
+ * Confirmation by holding, not by dialog.
+ *
+ * An "are you sure?" gets answered on autopilot — the finger is already on its
+ * way to OK before the eye reads. Holding requires continuous intent and stays
+ * reversible until the last instant: letting go cancels.
+ *
+ * Spec (§Destructive action): holdMs 3000 · tickMs 50 · RingProgress thickness 2
+ * over the icon · cancels on onMouseUp/onMouseLeave/onTouchEnd.
+ *
+ * ACCESSIBILITY — the spec records this as an "open requirement": the original
+ * pattern only responded to mouse and touch, which made deletion inaccessible
+ * from the keyboard. Here the same gesture exists on a held Space/Enter: keydown
+ * starts it (ignoring the OS autorepeat), keyup cancels. Same duration, same
+ * reversibility, same feedback.
+ */
+function useHold(onConfirm, holdMs) {
+    const [progress, setProgress] = useState(0)
+    const timer = useRef(null)
+    const holding = useRef(false)
+
+    const stop = useCallback(() => {
+        if (timer.current) clearInterval(timer.current)
+        timer.current = null
+        holding.current = false
+        setProgress(0)
+    }, [])
+
+    const start = useCallback(() => {
+        // The keyboard's autorepeat fires keydown continuously: without this
+        // guard, each repeat would restart the count and the hold would never
+        // complete.
+        if (holding.current) return
+        holding.current = true
+
+        const startedAt = performance.now()
+        timer.current = setInterval(() => {
+            const pct = Math.min(100, ((performance.now() - startedAt) / holdMs) * 100)
+            setProgress(pct)
+            if (pct >= 100) {
+                stop()
+                onConfirm()
+            }
+        }, TICK_MS)
+    }, [holdMs, onConfirm, stop])
+
+    // If the component leaves the screen mid-hold, the interval dies with it.
+    useEffect(() => stop, [stop])
+
+    return { progress, start, stop }
+}
+
+/** Handlers shared by both variants: pointer, touch and keyboard. */
+function holdHandlers(start, stop, disabled) {
+    if (disabled) return {}
+    return {
+        onMouseDown: start,
+        onMouseUp: stop,
+        onMouseLeave: stop,
+        onTouchStart: start,
+        onTouchEnd: stop,
+        onTouchCancel: stop,
+        onKeyDown: e => {
+            if (e.key === ' ' || e.key === 'Enter') {
+                e.preventDefault()
+                start()
+            }
+        },
+        onKeyUp: e => {
+            if (e.key === ' ' || e.key === 'Enter') stop()
+        },
+        onBlur: stop,
+    }
+}
+
+/**
+ * Icon variant — for inside tables and lists, where text doesn't fit.
+ * The ring grows over the icon itself.
+ */
+export function HoldToConfirmIcon({ icon, label, onConfirm, disabled, color = 'red.6', holdMs = HOLD_MS }) {
+    const { progress, start, stop } = useHold(onConfirm, holdMs)
+    const active = progress > 0
+
+    return (
+        <Tooltip label={label}>
+            <Box
+                pos="relative"
+                display="flex"
+                style={{ alignItems: 'center', justifyContent: 'center' }}
+            >
+                {active && (
+                    <RingProgress
+                        size={34}
+                        thickness={2}
+                        sections={[{ value: progress, color }]}
+                        pos="absolute"
+                        style={{ pointerEvents: 'none' }}
+                        aria-hidden
+                    />
+                )}
+                <ActionIcon
+                    color={active ? color : 'gray'}
+                    aria-label={label}
+                    disabled={disabled}
+                    {...holdHandlers(start, stop, disabled)}
+                >
+                    {icon}
+                </ActionIcon>
+            </Box>
+        </Tooltip>
+    )
+}
+
+/**
+ * Text variant with a countdown — for forms and modals, where the button needs
+ * to say what is going to happen and how much is left.
+ */
+export function HoldToConfirmButton({ children, holdingLabel, onConfirm, disabled, loading, leftSection, holdMs = HOLD_MS, ...props }) {
+    const { progress, start, stop } = useHold(onConfirm, holdMs)
+    const active = progress > 0
+    const remaining = Math.ceil(((100 - progress) / 100) * (holdMs / 1000))
+
+    return (
+        <Button
+            color="red.6"
+            disabled={disabled}
+            loading={loading}
+            leftSection={leftSection}
+            {...holdHandlers(start, stop, disabled || loading)}
+            {...props}
+        >
+            {active ? (
+                <Text
+                    c="gray.6"
+                    span
+                    inherit
+                >
+                    {holdingLabel} {remaining}s
+                </Text>
+            ) : (
+                children
+            )}
+        </Button>
+    )
+}

package/src/components/ListSkeleton.jsx

@@ -0,0 +1,55 @@
+import { Box, Skeleton, Stack } from '@mantine/core'
+
+/**
+ * A forma da lista de recursos enquanto ela não chegou.
+ *
+ * Seis cópias, e a única diferença entre elas era o nome — `ListSkeleton` em
+ * cinco, `ListaEsqueleto` no que ainda não tinha migrado para inglês.
+ *
+ * As LARGURAS SÃO IRREGULARES de propósito. Barras do mesmo tamanho leem como
+ * uma tabela vazia; larguras diferentes leem como texto que ainda não chegou —
+ * que é a verdade. O ciclo de seis valores evita o padrão visível que três ou
+ * quatro produziriam numa lista longa.
+ *
+ * `aria-hidden` porque não há o que anunciar: um leitor de tela lendo seis
+ * caixas vazias atrapalha em vez de informar. Quem depende dele recebe o
+ * conteúdo quando ele existir.
+ */
+export function ListSkeleton({ rows = 4 }) {
+    const widths = ['62%', '48%', '71%', '55%', '66%', '43%']
+
+    return (
+        <Stack
+            gap={2}
+            w="100%"
+            aria-hidden
+        >
+            {Array.from({ length: rows }).map((_, i) => (
+                <Box
+                    key={i}
+                    w="100%"
+                    px={12}
+                    py={8}
+                    style={{
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'flex-start',
+                        gap: 10,
+                    }}
+                >
+                    <Skeleton
+                        h={18}
+                        w={18}
+                        radius={0}
+                        style={{ flex: 'none' }}
+                    />
+                    <Skeleton
+                        h={10}
+                        w={widths[i % widths.length]}
+                        radius={0}
+                    />
+                </Box>
+            ))}
+        </Stack>
+    )
+}

package/src/components/MenuItem.jsx

@@ -0,0 +1,56 @@
+import { UnstyledButton, Text } from '@mantine/core'
+
+/**
+ * A linha de um menu — ícone à esquerda, rótulo, fundo no hover.
+ *
+ * VEIO DE SETE CÓPIAS BYTE-IDÊNTICAS.
+ *
+ * Este é o caso mais limpo de duplicação da stack: o mesmo `md5` em seis
+ * painéis, e o sétimo (Monitors) diferindo APENAS por aspas duplas — um arquivo
+ * que escapou do Prettier da casa. Trinta e seis linhas, sete vezes, sem uma
+ * decisão de produto no meio.
+ *
+ * O hover é escrito no DOM em vez de CSS porque a linha vive dentro de um
+ * `Popover` do Mantine, que monta fora da árvore de estilos do painel — uma
+ * classe declarada no CSS do produto não o alcança.
+ *
+ * @param {Function} icon    Componente de ícone (tabler). Recebe `size` e `stroke`.
+ * @param {string}   label   O que a pessoa lê.
+ * @param {Function} onClick O que acontece no clique.
+ */
+export function MenuItem({ icon: Icon, label, onClick }) {
+    return (
+        <UnstyledButton
+            onClick={onClick}
+            px={10}
+            py={8}
+            style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: 10,
+                width: '100%',
+                borderRadius: 0,
+                transition: 'background 120ms ease',
+            }}
+            onMouseEnter={e => {
+                e.currentTarget.style.background = 'var(--mantine-color-gray-1)'
+            }}
+            onMouseLeave={e => {
+                e.currentTarget.style.background = 'transparent'
+            }}
+        >
+            <Icon
+                size={16}
+                stroke={1.5}
+                style={{ flex: 'none', color: 'var(--mantine-color-gray-5)' }}
+            />
+            <Text
+                fz={13}
+                fw={500}
+                c="gray.9"
+            >
+                {label}
+            </Text>
+        </UnstyledButton>
+    )
+}

package/src/components/Metric.jsx

@@ -0,0 +1,178 @@
+import { Box, Group, Skeleton, Text } from '@mantine/core'
+
+/**
+ * A number, its label and the note that makes it verifiable.
+ *
+ * LAW 5, and it is the reason this component exists instead of a big <Text>:
+ * 'big metric without a note' is one of the spec's blockers. A bare '99,4%'
+ * doesn't say over what period, measured by whom, across how many samples — and
+ * an uptime dashboard that asserts without backing is advertising, not
+ * instrumentation.
+ *
+ * The `note` is neither decoration nor a tooltip: it is the lowest rung of the
+ * hierarchy (12px, gray.6) and lives right against the number, always visible.
+ *
+ * NULL NEVER BECOMES ZERO. The manager returns `null` for 'we didn't measure'
+ * and a number for 'we measured'. An em dash is the only honest answer to the
+ * first case — 100% uptime on a monitor that never ran would be the worst lie
+ * this product can tell, and it would show up exactly where trust is highest.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * THIS COMPONENT IS THE SUPERSET OF SIX COPIES, NOT A SEVENTH
+ *
+ * Before it existed here, the same block lived six times over: `MetricStrip` in
+ * storage, payments, functions, hoster and messages, plus an inline
+ * `MetricBlock` in the auth Overview. The extraction found three divergences
+ * that were NOT styling, and all three went against the first version of this
+ * file:
+ *
+ *   1. THE LABEL COMES AFTER THE NUMBER. All six put the label below; the first
+ *      version here put it above. With the label on top, the eye reads
+ *      "USUÁRIOS" before "1.204" — and the number stops being the first impact,
+ *      which is exactly what this screen exists to produce.
+ *
+ *   2. `unit` IS CONTENT, not ornament. The Hoster's age formatter returns
+ *      `{ value: '3', unit: 'h' }`; without the baseline-aligned suffix, "3
+ *      hours ago" becomes "3". A number without its unit isn't a smaller
+ *      number: it's a different one.
+ *
+ *   3. `loading` SWAPS THE NUMBER FOR A SKELETON, and the note goes with it.
+ *      The note says WHERE the number came from; without the number it is a
+ *      loose claim about data nobody read. The label stays — it names the
+ *      metric, and that is true before the answer arrives.
+ *
+ * @param {string}  label    - The metric's name. Sits BELOW the number.
+ * @param {*}       value    - The number. `null`/`undefined` become an em dash.
+ * @param {string}  unit     - Baseline-aligned suffix ('h', 'GB', '%').
+ * @param {string}  note     - Where the number came from. Law 5.
+ * @param {string}  hint     - Synonym for `note`. The five local `MetricStrip`
+ *                             copies called this field `hint` in 46 places, and
+ *                             a component that only reads `note` would erase
+ *                             all 46 SILENTLY — which is literally the bug the
+ *                             Storage had (it passed `sub`, the strip read
+ *                             `hint`, and three notes never rendered).
+ *                             Accepting both names costs one line; discovering
+ *                             the erasure costs a production screen lying until
+ *                             someone notices.
+ * @param {number}  delta    - Change against the previous period, in %.
+ * @param {boolean} loading  - Swaps number and note for a skeleton.
+ * @param {string}  size     - 'xl' on the account picture; everything else follows.
+ */
+export function Metric({ label, value, unit, note, hint, delta, deltaSuffix = '%', betterWhenLower = false, loading = false, size = 'md' }) {
+    // `hint` is the name the five panels already used; `note` wins if both arrive.
+    const caption = note ?? hint
+
+    const hasDelta = !loading && delta != null && Number.isFinite(delta) && delta !== 0
+
+    /*
+     * THE CHROMATIC EXCEPTION ONLY MARKS WHAT GOT WORSE, and the default is
+     * `false` because most metrics in the stack improve by going up (users,
+     * deploys, revenue). The auth painted ANY rise neutral and any drop gray —
+     * inheriting that `betterWhenLower = true` would have painted "users grew
+     * 12%" as an alert across five dashboards at once.
+     *
+     * An improvement doesn't get a color: it doesn't ask for action.
+     */
+    const worsened = betterWhenLower ? delta > 0 : delta < 0
+
+    /*
+     * `xl` is the size of the account picture, and it is RESPONSIVE out of
+     * necessity: 64px on a phone overflows the line and breaks "1.204" in half.
+     *
+     * The six dashboards had already converged on desktop 64 on their own, with
+     * two scales to get there — `{base:40, sm:56, md:64}` in two of them and
+     * `{base:48, sm:64}` in three. The difference never had a reason, only
+     * copying. We keep the 48 base (the 40 was cramped for no reason) with the
+     * intermediate step from the ones that had three.
+     *
+     * The other sizes serve where the metric ACCOMPANIES something else: next
+     * to a table, inside a detail card. There, competing with the content would
+     * be noise.
+     */
+    const fz = size === 'xl' ? { base: 48, sm: 56, md: 64 } : size === 'lg' ? 36 : size === 'sm' ? 20 : 28
+
+    return (
+        <Box miw={0}>
+            {loading ? (
+                <Skeleton
+                    h={size === 'xl' ? 48 : 28}
+                    w="60%"
+                    radius={0}
+                />
+            ) : (
+                <Group
+                    gap={4}
+                    align="baseline"
+                    wrap="nowrap"
+                >
+                    <Text
+                        fz={fz}
+                        fw={900}
+                        c="gray.9"
+                        lh={1}
+                        ls="-0.04em"
+                        style={{ overflowWrap: 'anywhere' }}
+                    >
+                        {value ?? '—'}
+                    </Text>
+
+                    {unit && (
+                        <Text
+                            fz={20}
+                            fw={700}
+                            c="dimmed"
+                            lh={1}
+                        >
+                            {unit}
+                        </Text>
+                    )}
+                </Group>
+            )}
+
+            <Text
+                fz={11}
+                fw={800}
+                c="gray.4"
+                tt="uppercase"
+                ls="1.5px"
+                lh={1.4}
+                mt={12}
+            >
+                {label}
+            </Text>
+
+            {!loading && (caption || hasDelta) && (
+                <Group
+                    gap={6}
+                    mt={4}
+                    wrap="nowrap"
+                    align="baseline"
+                >
+                    {hasDelta && (
+                        <Text
+                            fz={11}
+                            fw={800}
+                            c={worsened ? 'red.6' : 'gray.9'}
+                            lh={1.5}
+                        >
+                            {delta > 0 ? '+' : ''}
+                            {delta}
+                            {deltaSuffix}
+                        </Text>
+                    )}
+
+                    {caption && (
+                        <Text
+                            fz={12}
+                            fw={500}
+                            c="gray.6"
+                            lh={1.5}
+                        >
+                            {caption}
+                        </Text>
+                    )}
+                </Group>
+            )}
+        </Box>
+    )
+}

package/src/components/MoreResults.jsx

@@ -0,0 +1,137 @@
+import { useEffect, useRef } from 'react'
+import { Box, Button, Group, Loader, Text } from '@mantine/core'
+
+/**
+ * The footer of a paginated list: loads the next page when you reach the end.
+ *
+ * Infinite scroll WITH A BUTTON, not one or the other. The
+ * `IntersectionObserver` makes the common case happen on its own — whoever
+ * scrolls to the end gets more rows without asking. The button sits below it
+ * because pure infinite scroll leaves out anyone navigating by keyboard (there
+ * is no way to 'scroll to the observer' with Tab), anyone using a screen reader
+ * (the silent load is not announced), and anyone on a window tall enough that
+ * the sentinel never leaves the viewport.
+ *
+ * Both trigger the SAME function. The button is not a fallback that appears
+ * when the observer fails: it is always visible, always operable, and the
+ * observer merely anticipates the click when the finger is already scrolling.
+ *
+ * `rootMargin: 200px` fires the load before the footer appears: requesting the
+ * page only when the sentinel enters the screen guarantees the user ALWAYS sees
+ * the emptiness before the rows. 200px is roughly two table rows — enough time
+ * for the response to arrive during the scroll movement.
+ *
+ * Why we did not replace this with numbered pagination: in a monitoring list the
+ * question is 'what is broken?', and the answer is ordered by severity. Numbered
+ * pages make sense when there is a stable index to return to ('page 4 of the
+ * results'); here the order changes every 30s cycle, and 'page 4' is nowhere.
+ * What the person wants is to keep scrolling down.
+ *
+ * THE NOUN COMES BY PROP. This component was born in Monitors and carried a
+ * literal "monitor"/"monitores" in the end-of-list sentence — which made the
+ * Payments email log announce "25 monitores · fim da lista". It is the same
+ * class of error as the Wordmark without `name`: a component promoted to the kit
+ * carrying along a word that belonged to the product it came from.
+ *
+ * The interface is English; the words it renders are the product's Portuguese
+ * copy, and the pluralization rule below is Portuguese grammar on purpose.
+ *
+ * @param {string} noun       - Singular ("envio", "monitor").
+ * @param {string} pluralNoun - Plural. Defaults to `noun` + "s", which covers
+ *                              the regular Portuguese case; whoever has an
+ *                              irregular plural passes their own.
+ */
+export function MoreResults({ loading, hasMore, onLoadMore, shown, total, noun = 'item', pluralNoun }) {
+    const plural = pluralNoun ?? `${noun}s`
+    const sentinel = useRef(null)
+
+    useEffect(() => {
+        const target = sentinel.current
+        // Without `hasMore` there is nothing to observe; without
+        // `IntersectionObserver` (old browser, test environment) the button
+        // keeps working.
+        if (!target || !hasMore || typeof IntersectionObserver === 'undefined') return
+
+        const obs = new IntersectionObserver(
+            entries => {
+                if (entries[0]?.isIntersecting) onLoadMore()
+            },
+            { rootMargin: '200px' },
+        )
+
+        obs.observe(target)
+        return () => obs.disconnect()
+    }, [hasMore, onLoadMore])
+
+    // End of the list: silence would be ambiguous — 'it's over' or 'is it loading?'.
+    if (!hasMore) {
+        if (!total || shown < 20) return null
+        return (
+            <Box
+                py={16}
+                ta="center"
+                style={{ borderTop: 'var(--rlg-border)' }}
+            >
+                <Text
+                    fz={11}
+                    fw={800}
+                    c="gray.4"
+                    tt="uppercase"
+                    ls="1.5px"
+                >
+                    {total} {total === 1 ? noun : plural} · fim da lista
+                </Text>
+            </Box>
+        )
+    }
+
+    return (
+        <Box
+            ref={sentinel}
+            py={16}
+            style={{ borderTop: 'var(--rlg-border)' }}
+        >
+            <Group
+                justify="center"
+                gap={12}
+            >
+                {loading ? (
+                    <>
+                        <Loader size={16} />
+                        <Text
+                            fz={11}
+                            fw={800}
+                            c="gray.4"
+                            tt="uppercase"
+                            ls="1.5px"
+                            /* `aria-live` because a scroll-triggered load has no
+                               focus: without this, a screen reader would not know
+                               the list had grown. */
+                            aria-live="polite"
+                        >
+                            Carregando
+                        </Text>
+                    </>
+                ) : (
+                    <Button
+                        variant="default"
+                        size="xs"
+                        onClick={onLoadMore}
+                    >
+                        Carregar mais
+                    </Button>
+                )}
+
+                <Text
+                    fz={11}
+                    fw={800}
+                    c="gray.4"
+                    tt="uppercase"
+                    ls="1.5px"
+                >
+                    {shown} de {total}
+                </Text>
+            </Group>
+        </Box>
+    )
+}

package/src/components/NavItem.jsx

@@ -0,0 +1,57 @@
+import { NavLink } from '@mantine/core'
+
+/**
+ * Um item da navegação lateral.
+ *
+ * VEIO DE SETE CÓPIAS, E O SUPERSET É MENOR QUE A MAIOR DELAS.
+ *
+ * As sete assinaturas divergiam só no que cada painel precisou acrescentar:
+ * `muted` (payments, auth), `disabled` (auth), e `collapsed` (seis). As três
+ * primeiras entram aqui; a última NÃO.
+ *
+ * POR QUE `collapsed` FICOU DE FORA
+ *
+ * Nenhum painel colapsa a coluna. Os seis declaram `const [collapsed] =
+ * useState(false)` e descartam o setter — não existe um `setCollapsed` na
+ * stack inteira, e o toggle do Auth está comentado. Eram 262 ocorrências de um
+ * estado que nunca muda, mantendo vivos um ramo de largura, um de padding, um
+ * de alinhamento e um `<Tooltip>` inteiro que nunca aparece.
+ *
+ * Se um dia a coluna colapsar de verdade, o lugar de tratar isso é aqui, uma
+ * vez — não em seis arquivos que precisam concordar.
+ *
+ * @param {Function} icon     Componente de ícone (tabler).
+ * @param {string}   label    O que a pessoa lê.
+ * @param {boolean}  active   Item da rota atual. Engrossa o rótulo.
+ * @param {boolean}  muted    Secundário: ícone e texto em cinza. Para a nav de conta.
+ * @param {boolean}  disabled Sem alvo ainda (no Auth, antes de escolher a aplicação).
+ * @param {Function} onClick  Ignorado quando `disabled`.
+ */
+export function NavItem({ icon: Icon, label, active, muted, disabled, onClick }) {
+    return (
+        <NavLink
+            onClick={disabled ? undefined : onClick}
+            disabled={disabled}
+            active={active}
+            variant="filled"
+            color="gray.9"
+            label={label}
+            w="100%"
+            px={12}
+            py={9}
+            bdrs="0"
+            leftSection={
+                <Icon
+                    size={18}
+                    stroke={1.5}
+                    style={muted ? { color: 'var(--mantine-color-gray-5)' } : undefined}
+                />
+            }
+            styles={{
+                root: { justifyContent: 'flex-start' },
+                section: { marginInlineEnd: 12 },
+                label: { fontSize: 13, fontWeight: active ? 800 : 500, color: muted ? 'var(--mantine-color-gray-6)' : undefined },
+            }}
+        />
+    )
+}