@ciromaciel/dashboard-kit 1.0.0

package/src/hooks/usePaginatedList.js

@@ -0,0 +1,206 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/**
+ * A server-backed list, one page at a time.
+ *
+ * THIS HOOK IS THE GENERALIZATION OF `useMonitorsPaginated`, and it exists
+ * because the four decisions below cannot be deduced by reading the code — they
+ * were found by measuring. Every screen that paginated on its own would have to
+ * rediscover all four, and the first three fail silently.
+ *
+ * 1. SEARCH, FILTER AND ORDER GO TO THE SERVER. Without that, paginating BREAKS
+ *    search: a client-side search over the loaded page says "no results" for an
+ *    item that exists on page 3 — worse than having no search at all, because it
+ *    looks like an answer. Changing any of the three returns to the first page;
+ *    keeping the offset would show an empty list with "23 results" at the top.
+ *
+ * 2. THE RELOAD BRINGS BACK WHAT IS ALREADY ON SCREEN, not just the first page.
+ *    Someone who scrolled to the fourth page and watches the periodic cycle
+ *    return 50 rows has lost both their place and their work. `offset: 0` with
+ *    the accumulated size is a larger request in bytes, and the only one that
+ *    preserves position.
+ *
+ * 3. `loadingMore` IS SEPARATE FROM `loading`. The first keeps the table on
+ *    screen with a loading footer; the second swaps everything for a skeleton.
+ *    A single flag would make the whole list flash on every new page.
+ *
+ * 4. THE IN-FLIGHT RESPONSE IS INVALIDATED BY GENERATION, not by
+ *    AbortController. Typing fast fires N searches, and the slow response to the
+ *    first can arrive after the fifth — the classic race. A counter that only
+ *    accepts the response of the current generation solves it without requiring
+ *    the server to understand cancellation.
+ *
+ * THE SYNCHRONOUS LOCK (`fetchingMore`) deserves its own note: `loadingMore` is
+ * React state and only takes effect after render, but the `IntersectionObserver`
+ * in `MoreResults` fires several times within the same frame while the scroll
+ * runs. Measured: every page was requested TWICE — seven requests for four
+ * pages. A `ref` changes at the very instant of the call, so the second attempt
+ * in the same frame already finds the lock closed.
+ *
+ * @param {function} fetchPage - `({ limit, offset }) => Promise<{items, page}>`.
+ *                               The contract envelope; see `collection()` in
+ *                               `@ciromaciel/contract`.
+ * @param {array}    deps      - What, when changed, returns to the first page:
+ *                               search, filter, order. Same as a `useEffect`
+ *                               dependency array.
+ * @param {number}   size      - Items per page.
+ * @param {number}   intervalMs - Periodic reload. `0` disables it.
+ * @param {function} pace      - `(items) => ms`, to speed up the reload while
+ *                               work is in progress. Monitors returns 4s while
+ *                               some row is auditing and 30s at rest: an audit
+ *                               lasts about a minute, and without this the row
+ *                               spends half a minute showing the stale state
+ *                               AFTER it has finished.
+ */
+export function usePaginatedList({ fetchPage, deps = [], size = 50, intervalMs = 0, pace } = {}) {
+    const [items, setItems] = useState([])
+    const [loading, setLoading] = useState(true)
+    const [loadingMore, setLoadingMore] = useState(false)
+    const [error, setError] = useState(null)
+    const [total, setTotal] = useState(0)
+    const [hasMore, setHasMore] = useState(false)
+    /*
+     * THE REST OF THE BODY, outside `items` and `page`.
+     *
+     * The contract puts at the ROOT whatever is context about the set rather
+     * than pagination: Monitors' per-state `counts`, Hoster's `activeDeployId`,
+     * Storage's blob `cursor`. Without exposing that, every panel needing one of
+     * them would have to keep its own copy of this hook — which is exactly the
+     * situation it came to undo.
+     */
+    const [extra, setExtra] = useState(null)
+
+    const alive = useRef(true)
+    const generation = useRef(0)
+    const loaded = useRef(0)
+    const fetchingMore = useRef(false)
+
+    // `fetchPage` is usually a fresh arrow on every render. Held in a ref, it
+    // stays out of the dependencies — otherwise the effect would restart on
+    // every render and the list would fetch the first page forever.
+    const fetchPageRef = useRef(fetchPage)
+    fetchPageRef.current = fetchPage
+
+    const requestPage = useCallback(
+        async ({ offset, limit = size, mode }) => {
+            const mine = ++generation.current
+
+            if (mode === 'more') setLoadingMore(true)
+            else if (mode === 'replace') setLoading(true)
+
+            try {
+                const r = await fetchPageRef.current({ limit, offset })
+                if (!alive.current || mine !== generation.current) return
+
+                const list = r?.items ?? []
+                const append = offset > 0 && mode === 'more'
+
+                setItems(previous => (append ? [...previous, ...list] : list))
+                loaded.current = append ? loaded.current + list.length : list.length
+
+                setTotal(r?.page?.total ?? list.length)
+                setHasMore(Boolean(r?.page?.hasMore))
+
+                // Anything that is neither `items` nor `page` is context about the set.
+                const { items: _i, page: _p, ...rest } = r ?? {}
+                setExtra(Object.keys(rest).length ? rest : null)
+
+                setError(null)
+            } catch (e) {
+                if (alive.current && mine === generation.current) setError(e?.message ?? String(e))
+            } finally {
+                // The lock ALWAYS opens, including when the response is discarded by
+                // generation — stuck, infinite scroll simply stops working.
+                if (mode === 'more') fetchingMore.current = false
+                if (alive.current && mine === generation.current) {
+                    setLoading(false)
+                    setLoadingMore(false)
+                }
+            }
+        },
+        [size],
+    )
+
+    const loadMore = useCallback(() => {
+        if (fetchingMore.current || loading || !hasMore) return
+        fetchingMore.current = true
+        requestPage({ offset: loaded.current, mode: 'more' })
+    }, [requestPage, loading, hasMore])
+
+    /** Reloads what is on screen, preserving the scroll position (decision 2). */
+    const reload = useCallback(() => requestPage({ offset: 0, limit: Math.max(loaded.current, size), mode: 'silent' }), [requestPage, size])
+
+    /*
+     * The trigger goes through a `setTimeout(0)` rather than straight into the
+     * effect body. `requestPage` calls `setLoading(true)` synchronously, and a
+     * setState in the effect body chains an extra render on every keystroke in
+     * the search box. Scheduled, the loading state lands after the commit — and
+     * the `clearTimeout` cancels the search for a term the user has already
+     * replaced, before it even leaves.
+     */
+    useEffect(() => {
+        alive.current = true
+        loaded.current = 0
+        fetchingMore.current = false
+
+        /*
+         * THE GENERATION IS INCREMENTED HERE, and not only inside `requestPage`.
+         *
+         * The `setTimeout(0)` below defers the request until after the commit.
+         * Without this increment, changing the search during an in-flight
+         * response played out like this: the cleanup cancelled the new
+         * generation's timer BEFORE it existed, the slow response from the old
+         * generation arrived, found the counter unchanged — and won. The list
+         * ended up showing the result for the term the user had already
+         * replaced.
+         *
+         * Invalidating at the moment of the CHANGE, not at the moment of the
+         * request, is what closes that window: any earlier response is already
+         * born stale.
+         */
+        generation.current++
+
+        const t = setTimeout(() => requestPage({ offset: 0, mode: 'replace' }), 0)
+        return () => {
+            clearTimeout(t)
+            alive.current = false
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [requestPage, ...deps])
+
+    /*
+     * THE PACE FOLLOWS WHAT IS HAPPENING.
+     *
+     * A fixed interval is right at rest, but wrong while work is in progress:
+     * during a long-running operation the row can spend half a minute showing
+     * the stale state AFTER it has finished. `pace` lets the product decide —
+     * and it returns to the resting interval on its own.
+     */
+    const cadence = pace?.(items) || intervalMs
+
+    useEffect(() => {
+        if (!cadence) return
+        const t = setInterval(reload, cadence)
+        return () => clearInterval(t)
+    }, [reload, cadence])
+
+    return { items, loading, loadingMore, error, total, hasMore, extra, loadMore, reload }
+}
+
+/**
+ * Waits for the user to stop typing before going to the network.
+ *
+ * A client-side search does not need this — it is not worth delaying the
+ * response to the keyboard in order to filter an in-memory array. A SERVER
+ * search does: every keystroke would be a request, and 300 ms is the interval at
+ * which the person typing perceives no wait but the server receives one search
+ * instead of ten.
+ */
+export function useDebounce(value, ms = 300) {
+    const [delayed, setDelayed] = useState(value)
+    useEffect(() => {
+        const t = setTimeout(() => setDelayed(value), ms)
+        return () => clearTimeout(t)
+    }, [value, ms])
+    return delayed
+}

package/src/index.js

@@ -0,0 +1,99 @@
+// ============================================================================
+// @ciromaciel/dashboard-kit — what the seven dashboards share
+// ============================================================================
+//
+// The websites already had `@ciromaciel/components-kit`. The DASHBOARDS had
+// nothing: each one kept its own copy of the table, the loading state, the
+// empty state and the destructive confirmation — 4,624 duplicated lines across
+// four of them, plus seven copies of `AuthLoader`.
+//
+// THE ADMISSION CRITERION
+//
+// What goes in here is what is THE SAME across the dashboards. What belongs to
+// a product stays out: the Monitors status light, its boot skeleton, the
+// Payments currency rule. The dividing line is simple — if a dashboard had to
+// change the component to serve its product, the component isn't everyone's
+// yet.
+//
+// WHAT THE EXTRACTION FOUND
+//
+// Four components were byte-for-byte identical across four dashboards. Three
+// had two variants, and in each case the divergence was EVOLUTION, not drift:
+// the Hoster added `quietSelection` to the table with the reasoning written
+// down, Monitors fixed a `<div>` inside a `<p>` that the browser was tearing
+// apart. The kit kept the superset in each case — no dashboard loses behavior
+// by adopting it.
+//
+// `Wordmark` was the one genuine exception: the four copies diverged because
+// the product name was a literal in the JSX, and changing one word forced you
+// to maintain the whole file. Here it comes in as a prop.
+//
+// WHY THERE IS NO BUILD
+//
+// The package publishes source. All seven dashboards are Vite, which compiles
+// JSX from a dependency without ceremony — and a build step would only exist to
+// produce what the consumer already knows how to produce. One less moving part
+// to break.
+
+import './tokens.css'
+
+export { DataTable } from './components/DataTable'
+export { templateFor, ROW_PADDING, HEAD_PADDING } from './components/table-grid'
+export { TableSkeleton } from './components/TableSkeleton'
+export { EmptyState } from './components/EmptyState'
+export { SectionCard, Field, FieldStacked, CardActions } from './components/SectionCard'
+export { PageHeader } from './components/PageHeader'
+
+// ── The billing banner ───────────────────────────────────────────────────
+// Freeze, do not disconnect: it warns, it never blocks. It takes the state
+// from `usePlanNotice(product)` in `@ciromaciel/payments-react` and paints it —
+// the kit does not know the Payments' address.
+export { PlanBanner } from './components/PlanBanner'
+export { HoldToConfirmIcon, HoldToConfirmButton } from './components/HoldToConfirm'
+
+// ── The destructive modal ────────────────────────────────────────────────
+// The top of the escalation: reversible → hold → this. An audit found fifteen
+// of them across the seven panels and no two alike, so the shape lives here
+// now. `design-system/10-modal-de-exclusao.md` says why.
+export { DeleteModal, deleteTitleScale } from './components/DeleteModal'
+export { ZenLabel } from './components/ZenLabel'
+export { notify } from './components/notify'
+export { NOTIFICATIONS_PROPS, NOTIFY_DESCRIPTION_CSS, notificationTheme } from './components/notify-theme'
+export { Wordmark } from './components/Wordmark'
+export { SupportModal, HealthRow, useHealthCheck } from './components/SupportModal'
+export { AuthLoader } from './components/AuthLoader'
+export { AuthScreen } from './components/AuthScreen'
+export { Terminal, TerminalOutput } from './components/Terminal'
+export { useExclusiveModal } from './hooks/useExclusiveModal'
+
+// ── The sidebar's pieces ─────────────────────────────────────────────────
+// Extracted after measuring: `MenuItem` was byte-identical in seven panels
+// (the seventh differing only by quote style), and `NavItem`/`GroupLabel`
+// differed by one optional prop each.
+export { MenuItem } from './components/MenuItem'
+export { NavItem } from './components/NavItem'
+export { GroupLabel } from './components/GroupLabel'
+export { ResourceItem } from './components/ResourceItem'
+export { ActiveResource } from './components/ActiveResource'
+export { ListSkeleton } from './components/ListSkeleton'
+export { DashboardFrame, SIDEBAR_WIDTH } from './components/DashboardFrame'
+export { SidebarShell } from './components/SidebarShell'
+export { AUTH_LABELS, AUTH_TEXTS } from './auth-labels'
+export { CardSkeleton } from './components/CardSkeleton'
+export { MoreResults } from './components/MoreResults'
+export { TableToolbar } from './components/TableToolbar'
+
+// ── The paginated list ───────────────────────────────────────────────────
+// The hook and the footer travel together: `usePaginatedList` holds the four
+// decisions you can't infer from reading the code, and `MoreResults` is the
+// only surface that triggers them. See the hook's header.
+export { usePaginatedList, useDebounce } from './hooks/usePaginatedList'
+
+// ── The screen ───────────────────────────────────────────────────────────
+// `Metric` and `CommandCenter` aren't just components: they are the pattern for
+// the first screen. Each dashboard used to call its own something different —
+// "Visão geral", "Painel", "Agendamentos" — and none of those names says what
+// the screen does. See the header of `CommandCenter.jsx` for the three laws it
+// carries.
+export { Metric } from './components/Metric'
+export { CommandCenter } from './components/CommandCenter'

package/src/tokens.css

@@ -0,0 +1,47 @@
+/*
+ * THE TOKENS THE KIT USES AND CANNOT ASSUME EXIST.
+ *
+ * Six components in this package draw a hairline with `var(--rlg-border)` — the
+ * table, its header, the skeleton, the search, the pagination footer and the
+ * Command Center's metrics band. The variable was born in each dashboard's CSS,
+ * and six of the seven defined it. The seventh (the Auth) didn't — and there the
+ * migrated table would have rendered WITH NO HAIRLINE AT ALL: header, rows and
+ * search flush against each other, with no build error and no console warning,
+ * because a `var()` with no value and no fallback simply doesn't apply the
+ * property.
+ *
+ * A package that requires a token to draw correctly has to ship that token's
+ * default value. `@property` doesn't work here (the value is a border
+ * shorthand), and repeating the fallback across the 13 call sites would be
+ * thirteen places to diverge.
+ *
+ * This is a FLOOR, not a lock: any dashboard's `:root` beats this declaration by
+ * cascade order — the product's CSS is imported afterwards.
+ */
+:root {
+    --rlg-border: 1px solid var(--mantine-color-gray-2);
+
+    /*
+     * O filete dentro do Terminal, sobre fundo escuro. Nasceu literal em cinco
+     * cópias e virou token no Hoster; o piso fica aqui para que o componente
+     * não dependa de cada painel declarar a variável.
+     */
+    --rlg-terminal-rule: rgba(255, 255, 255, 0.08);
+
+    /*
+     * The system's only green, used by the SupportModal's status light.
+     *
+     * Five panels declared it with this same value; Auth and Storage did not —
+     * and those are exactly the two that did not yet have the modal. Without
+     * this floor the "No ar" dot would render WITH NO COLOUR at all in those
+     * two: a `var()` with no value and no fallback does not apply the property,
+     * and there is no build error and no console warning. It is the same defect
+     * as the hairline described above.
+     *
+     * It lives outside the gray ramp because this is not the success of an
+     * ACTION (that is gray.9 + IconCheck): it is the measured state of an
+     * external system. The rule that keeps the exception honest is that the
+     * colour never appears without the word beside it.
+     */
+    --rlg-status-up: #16a34a;
+}