@fabio.caffarello/react-design-system 4.4.0 → 4.6.0

package/README.md

@@ -120,7 +120,8 @@ Consumers can import from:
 - `@fabio.caffarello/react-design-system/server` — the opt-in server entry (issue #150). Re-exports only the components whose render tree is safe to evaluate inside a React Server Component: presentational primitives (`Text`, `Skeleton`, `Spinner`, `Progress`, `Chip`, `ErrorMessage`, `Info`), layout (`Container`, `Stack`), and structural / informational components (`Breadcrumb`, `Timeline`, `AutocompleteOption`, `DialogHeader`, `DialogFooter`, `DrawerHeader`, `DrawerFooter`, `HeaderActions`, `HeaderNavigation`, `MenuSeparator`, `NavbarSeparator`, `TableCell`). The bundle carries NO `"use client"` directive, so importing from it in a Server Component does NOT cross a client boundary — useful for SEO-critical / first-paint-critical routes where the shell shouldn't ship JS to the client.
 - `@fabio.caffarello/react-design-system/hooks` — the granular public-hooks entry (issue #203). Re-exports only the public hooks (today: `useScrollSpy`) as a tiny standalone client bundle (<1KB) with every dependency external. Use it when a route's client component needs a hook but nothing else from RDS: importing a hook from the main entry pulls the whole pre-bundled barrel into the route's client JS (+277KB minified measured on a Next 16 route), because the single-file `"use client"` bundle is opaque to the consumer bundler's tree-shaking. The same hooks remain available from the main entry for back-compat.
 - `@fabio.caffarello/react-design-system/granular` — the granular client entry (issue #208). The SAME public surface as the default entry, emitted as a `preserveModules` tree (one module per source file, `"use client"` on every module, all deps external). Use it for leaf component imports on size-critical routes: importing one component from the default entry pulls the whole pre-bundled barrel (+264KB minified measured for `Accordion` on a Next 16 route); the same import from `./granular` ships only that component's module graph (~36KB, 13% of the barrel payload — gated in CI). Keep app-wide setup (`AppProvider`/providers) on the default entry: the single bundle preserves provider initialization order by construction.
-- `@fabio.caffarello/react-design-system/styles` — the bundled CSS. Same stylesheet regardless of which JS entry you import.
+- `@fabio.caffarello/react-design-system/styles` — the bundled, Tailwind-**compiled** CSS (resolved tokens + every component class). Same stylesheet regardless of which JS entry you import. For consumers who do **not** run Tailwind: import it and the classes already exist.
+- `@fabio.caffarello/react-design-system/theme` (+ `./theme.css`) — the **raw, uncompiled** `@theme` token source plus the light/dark overrides (issue #234). For consumers who run **Tailwind v4 themselves**: import it and your own Tailwind generates the token utilities (`text-fg-brand`, `bg-surface-brand-strong`, `ring-line-focus`, …) natively, theme-aware, from one source of truth — no re-export bridge. See "Extending the tokens with your own Tailwind" below.
 
 The JS entries can be mixed in one Server Component — `import { Text } from "…/server"; import { Button } from "…"` is the normal pattern. The server entry is purely additive; consumers who never use it see no behavioural change.
 
@@ -145,6 +146,19 @@ export default function Profile() {
 
 Sub-entries (`/primitives`, `/components`, `/tokens`, `/providers`) were removed in Phase 13d — they had been silently broken for external consumers since v1.0.0 because cross-chunk references to `cva` and other shared utilities failed at runtime. A single main entry collapses that class of bug structurally; tree-shaking still works at the named-export level via any modern bundler. The `./server`, `./hooks`, and `./granular` entries sidestep the same regression by each being their OWN independent Vite build with all third-party deps externalised — no chunks are shared between entries, and `./granular`'s preserveModules layout has no extracted chunks at all (source modules map 1:1 to output files).
 
+## Extending the tokens with your own Tailwind
+
+If your app **also** runs Tailwind v4, you can let your own Tailwind generate the design system's token utilities — so `text-fg-brand`, `bg-surface-brand-strong`, `ring-line-focus`, `text-fg-brand/80`, etc. are first-class in your project, theme-aware, with no copied values. Import the **compiled** stylesheet for RDS's own component classes and the **raw** token source for the `@theme`:
+
+```css
+/* your globals.css */
+@import "tailwindcss";
+@import "@fabio.caffarello/react-design-system/styles" layer(rds); /* compiled RDS component classes */
+@import "@fabio.caffarello/react-design-system/theme"; /* raw @theme: your Tailwind builds the token utilities */
+```
+
+`./theme` ships the `@theme` blocks **uncompiled** (not the resolved `@layer theme` output), so your Tailwind reads them and emits the utilities referencing `var(--color-…)` — the light/dark selector overrides in the same file then flip the resolved color at runtime. Do **not** wrap the tokens in a `@theme inline { … }` bridge: `inline` resolves the value at build time and breaks theming (and a self-referential bridge collapses to `transparent` — the bug that motivated this export). Batteries-included consumers who don't run Tailwind keep importing only `./styles` and need none of this.
+
 ## Working with Claude Code
 
 - `.claude/rules/` carries the enforced rules (components, testing, tokens).

package/dist/granular/ui/components/Stat/StatGroup.js

@@ -1,61 +1,76 @@
 "use client";
-var p = Object.defineProperty, u = Object.defineProperties;
-var x = Object.getOwnPropertyDescriptors;
-var e = Object.getOwnPropertySymbols;
-var t = Object.prototype.hasOwnProperty, g = Object.prototype.propertyIsEnumerable;
-var s = (r, d, i) => d in r ? p(r, d, { enumerable: !0, configurable: !0, writable: !0, value: i }) : r[d] = i, c = (r, d) => {
-  for (var i in d || (d = {}))
-    t.call(d, i) && s(r, i, d[i]);
-  if (e)
-    for (var i of e(d))
-      g.call(d, i) && s(r, i, d[i]);
+var b = Object.defineProperty, v = Object.defineProperties;
+var h = Object.getOwnPropertyDescriptors;
+var l = Object.getOwnPropertySymbols;
+var o = Object.prototype.hasOwnProperty, a = Object.prototype.propertyIsEnumerable;
+var t = (r, e, s) => e in r ? b(r, e, { enumerable: !0, configurable: !0, writable: !0, value: s }) : r[e] = s, c = (r, e) => {
+  for (var s in e || (e = {}))
+    o.call(e, s) && t(r, s, e[s]);
+  if (l)
+    for (var s of l(e))
+      a.call(e, s) && t(r, s, e[s]);
   return r;
-}, m = (r, d) => u(r, x(d));
-var n = (r, d) => {
-  var i = {};
-  for (var o in r)
-    t.call(r, o) && d.indexOf(o) < 0 && (i[o] = r[o]);
-  if (r != null && e)
-    for (var o of e(r))
-      d.indexOf(o) < 0 && g.call(r, o) && (i[o] = r[o]);
-  return i;
+}, m = (r, e) => v(r, h(e));
+var n = (r, e) => {
+  var s = {};
+  for (var i in r)
+    o.call(r, i) && e.indexOf(i) < 0 && (s[i] = r[i]);
+  if (r != null && l)
+    for (var i of l(r))
+      e.indexOf(i) < 0 && a.call(r, i) && (s[i] = r[i]);
+  return s;
 };
-import { jsx as b } from "react/jsx-runtime";
-import { getRadiusClass as v } from "../../tokens/radius.js";
-import { cn as C } from "../../utils/cn.js";
+import { jsxs as C, jsx as p } from "react/jsx-runtime";
+import { getRadiusClass as N } from "../../tokens/radius.js";
+import { getSpacingClass as j } from "../../tokens/spacing.js";
+import { cn as g } from "../../utils/cn.js";
 const G = {
   2: "md:grid-cols-2",
   3: "md:grid-cols-3",
   4: "md:grid-cols-4"
 };
-function R(h) {
-  var l = h, {
+function $(S) {
+  var d = S, {
     layout: r = "grid",
-    cols: d = 4,
+    cols: e = 4,
+    floatingBadge: s,
     className: i,
-    children: o
-  } = l, a = n(l, [
+    children: u
+  } = d, f = n(d, [
     "layout",
     "cols",
+    "floatingBadge",
     "className",
     "children"
   ]);
-  const f = r === "grid";
-  return /* @__PURE__ */ b(
+  const x = r === "grid";
+  return /* @__PURE__ */ C(
     "div",
     m(c({
-      className: C(
-        "bg-line-default border border-line-default overflow-hidden gap-px",
-        v("lg"),
-        f ? `grid grid-cols-2 ${G[d]}` : "flex",
+      className: g(
+        "relative",
+        s && j("base", "pt"),
         i
       )
-    }, a), {
-      children: o
+    }, f), {
+      children: [
+        s ? /* @__PURE__ */ p("div", { className: "absolute top-4 left-1/2 -translate-x-1/2 -translate-y-1/2 z-10", children: s }) : null,
+        /* @__PURE__ */ p(
+          "div",
+          {
+            className: g(
+              "bg-line-default border border-line-default overflow-hidden gap-px",
+              N("lg"),
+              x ? `grid grid-cols-2 ${G[e]}` : "flex"
+            ),
+            children: u
+          }
+        )
+      ]
     })
   );
 }
 export {
-  R as StatGroup
+  $ as StatGroup
 };
 //# sourceMappingURL=StatGroup.js.map

package/dist/granular/ui/components/Stat/StatGroup.js.map

@@ -1 +1 @@
-{"version":3,"file":"StatGroup.js","sources":["../../../../../src/ui/components/Stat/StatGroup.tsx"],"sourcesContent":["import { type HTMLAttributes, type ReactNode } from \"react\";\nimport { cn } from \"../../utils\";\nimport { getRadiusClass } from \"../../tokens/radius\";\n\nexport type StatGroupLayout = \"strip\" | \"grid\";\nexport type StatGroupCols = 2 | 3 | 4;\n\nexport interface StatGroupProps extends HTMLAttributes<HTMLDivElement> {\n  /**\n   * `strip` — single horizontal row, no wrap. Each `Stat` shares the row\n   * width via `flex-1`. Use when you guarantee the horizontal space\n   * (hero areas, wide dashboards). On narrow viewports the row does NOT\n   * reflow — choose `grid` if you need responsive collapse.\n   *\n   * `grid` — multi-column grid that reflows. Always 2-up on mobile,\n   * expands to `cols` columns at the `md` breakpoint (768 px) and up.\n   * Five or more children spill to a second row with the divider lines\n   * preserved.\n   *\n   * @default 'grid'\n   */\n  layout?: StatGroupLayout;\n  /**\n   * Desktop column count (≥ 768 px). Only effective in `layout=\"grid\"`;\n   * ignored in `layout=\"strip\"`. Mobile is always 2 columns regardless.\n   *\n   * @default 4\n   */\n  cols?: StatGroupCols;\n  children: ReactNode;\n}\n\n// Tailwind v4 generates `md:grid-cols-N` for N ∈ {2,3,4} statically from\n// the literal class string. The map below ensures the strings exist\n// verbatim in the source so JIT picks them up.\nconst gridColsMd: Record<StatGroupCols, string> = {\n  2: \"md:grid-cols-2\",\n  3: \"md:grid-cols-3\",\n  4: \"md:grid-cols-4\",\n};\n\n/**\n * `StatGroup` — container for one or more `Stat` blocks with 1-px\n * dividers between them.\n *\n * ### Divider technique\n *\n * The container has `bg-line-default` and `gap-px` (1 px); each child\n * `Stat` carries its own `bg-surface-base`. The 1 px of gap exposes the\n * container's background as the divider line, while each cell masks its\n * own area with `bg-surface-base`. Works identically for the strip\n * layout (vertical dividers) and the grid layout (vertical AND\n * horizontal dividers, automatically, as the grid reflows). No separate\n * `Divider` component, no per-cell border logic.\n *\n * The outer ring is `border border-line-default` matching the gap color,\n * with `rounded-lg` and `overflow-hidden` clipping the inner cells to\n * the radius.\n *\n * ### Server-safe\n *\n * Pure presentation — no hooks, no event handlers on the DOM. Ships in\n * `./server` alongside `Stat`.\n *\n * @example\n * ```tsx\n * <StatGroup layout=\"strip\">\n *   <Stat icon={<Users />} value=\"9,4 mil\" label=\"Parlamentares\" align=\"center\" />\n *   <Stat icon={<FileText />} value=\"3,2 mil\" label=\"Proposições\" align=\"center\" />\n *   <Stat icon={<Vote />} value=\"1,1 mil\" label=\"Votações\" align=\"center\" />\n *   <Stat icon={<Clock />} value=\"há 18 dias\" label=\"Última atualização\" align=\"center\" />\n * </StatGroup>\n *\n * <StatGroup layout=\"grid\" cols={4}>\n *   <Stat value=\"87%\" label=\"Alinhamento\" hint=\"últimos 12 m\" tone=\"success\" />\n *   <Stat value={null} label=\"Sem orientação\" hint=\"no período\" />\n *   <Stat value=\"R$ 187.472,95\" label=\"Gastos\" hint=\"no mandato\" />\n *   <Stat value=\"42\" label=\"Votações\" hint=\"no banco\" />\n * </StatGroup>\n * ```\n */\nexport function StatGroup({\n  layout = \"grid\",\n  cols = 4,\n  className,\n  children,\n  ...props\n}: StatGroupProps) {\n  const isGrid = layout === \"grid\";\n\n  return (\n    <div\n      className={cn(\n        \"bg-line-default border border-line-default overflow-hidden gap-px\",\n        getRadiusClass(\"lg\"),\n        isGrid ? `grid grid-cols-2 ${gridColsMd[cols]}` : \"flex\",\n        className,\n      )}\n      {...props}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport default StatGroup;\n"],"names":["gridColsMd","StatGroup","_a","_b","layout","cols","className","children","props","__objRest","isGrid","jsx","__spreadProps","__spreadValues","cn","getRadiusClass"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,MAAMA,IAA4C;AAAA,EAChD,GAAG;AAAA,EACH,GAAG;AAAA,EACH,GAAG;AACL;AA0CO,SAASC,EAAUC,GAMP;AANO,MAAAC,IAAAD,GACxB;AAAA,YAAAE,IAAS;AAAA,IACT,MAAAC,IAAO;AAAA,IACP,WAAAC;AAAA,IACA,UAAAC;AAAA,MAJwBJ,GAKrBK,IAAAC,EALqBN,GAKrB;AAAA,IAJH;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA;AAGA,QAAMO,IAASN,MAAW;AAE1B,SACE,gBAAAO;AAAA,IAAC;AAAA,IAAAC,EAAAC,EAAA;AAAA,MACC,WAAWC;AAAA,QACT;AAAA,QACAC,EAAe,IAAI;AAAA,QACnBL,IAAS,oBAAoBV,EAAWK,CAAI,CAAC,KAAK;AAAA,QAClDC;AAAA,MAAA;AAAA,OAEEE,IAPL;AAAA,MASE,UAAAD;AAAA,IAAA;AAAA,EAAA;AAGP;"}
+{"version":3,"file":"StatGroup.js","sources":["../../../../../src/ui/components/Stat/StatGroup.tsx"],"sourcesContent":["import { type HTMLAttributes, type ReactNode } from \"react\";\nimport { cn } from \"../../utils\";\nimport { getRadiusClass } from \"../../tokens/radius\";\nimport { getSpacingClass } from \"../../tokens/spacing\";\n\nexport type StatGroupLayout = \"strip\" | \"grid\";\nexport type StatGroupCols = 2 | 3 | 4;\n\nexport interface StatGroupProps extends HTMLAttributes<HTMLDivElement> {\n  /**\n   * `strip` — single horizontal row, no wrap. Each `Stat` shares the row\n   * width via `flex-1`. Use when you guarantee the horizontal space\n   * (hero areas, wide dashboards). On narrow viewports the row does NOT\n   * reflow — choose `grid` if you need responsive collapse.\n   *\n   * `grid` — multi-column grid that reflows. Always 2-up on mobile,\n   * expands to `cols` columns at the `md` breakpoint (768 px) and up.\n   * Five or more children spill to a second row with the divider lines\n   * preserved.\n   *\n   * @default 'grid'\n   */\n  layout?: StatGroupLayout;\n  /**\n   * Desktop column count (≥ 768 px). Only effective in `layout=\"grid\"`;\n   * ignored in `layout=\"strip\"`. Mobile is always 2 columns regardless.\n   *\n   * @default 4\n   */\n  cols?: StatGroupCols;\n  /**\n   * Optional slot for a badge that floats centered over the top border of\n   * the container. Use when all metrics in the group share a common\n   * provenance mark (e.g. a trust badge, data-source seal, tier label).\n   *\n   * The slot is intentionally opaque — the consumer supplies any ReactNode\n   * and owns the badge's styling and a11y. `StatGroup` provides only the\n   * positioning, not the badge shape. This is the same convention as the\n   * `kicker` slot in `HeroSection` or the `badge` slot in `PageHeader`.\n   *\n   * ### Layout\n   *\n   * When `floatingBadge` is supplied the outer container gains\n   * `pt-4` (16 px) top padding, which creates a landing zone for the\n   * badge's bottom half while keeping the first stat row clear. The badge\n   * itself is absolutely centred at `top-4 left-1/2`, then shifted up by\n   * `−50%` of its own height so its centre sits on the inner container's\n   * top border. This calibration is accurate for badges up to ~32 px tall\n   * (a standard `Badge` or small `Chip`). If a taller badge is needed,\n   * pass a `className` that increases the top padding to match.\n   *\n   * ### Reading order\n   *\n   * The badge node appears in the DOM **before** the stat cells, so screen\n   * readers encounter it first — \"Fonte oficial, followed by the metrics\" —\n   * which is the correct contextual order.\n   *\n   * @example\n   * ```tsx\n   * import { CheckCircle2 } from \"lucide-react\";\n   * import { Badge } from \"@fabio.caffarello/react-design-system\";\n   *\n   * <StatGroup\n   *   layout=\"strip\"\n   *   floatingBadge={\n   *     <Badge variant=\"success\" size=\"sm\">\n   *       <CheckCircle2 size={10} aria-hidden=\"true\" />\n   *       Fonte oficial\n   *     </Badge>\n   *   }\n   * >\n   *   <Stat icon={<Users />} value=\"726\" label=\"Parlam.\" align=\"center\" />\n   *   <Stat icon={<FileText />} value=\"28,1 mil\" label=\"Proposições\" align=\"center\" />\n   * </StatGroup>\n   * ```\n   */\n  floatingBadge?: ReactNode;\n  children: ReactNode;\n}\n\n// Tailwind v4 generates `md:grid-cols-N` for N ∈ {2,3,4} statically from\n// the literal class string. The map below ensures the strings exist\n// verbatim in the source so JIT picks them up.\nconst gridColsMd: Record<StatGroupCols, string> = {\n  2: \"md:grid-cols-2\",\n  3: \"md:grid-cols-3\",\n  4: \"md:grid-cols-4\",\n};\n\n/**\n * `StatGroup` — container for one or more `Stat` blocks with 1-px\n * dividers between them.\n *\n * ### Divider technique\n *\n * The inner container has `bg-line-default` and `gap-px` (1 px); each\n * child `Stat` carries its own `bg-surface-base`. The 1 px of gap exposes\n * the container's background as the divider line, while each cell masks\n * its own area with `bg-surface-base`. Works identically for the strip\n * layout (vertical dividers) and the grid layout (vertical AND horizontal\n * dividers, automatically, as the grid reflows). No separate `Divider`\n * component, no per-cell border logic.\n *\n * The inner ring is `border border-line-default` matching the gap color,\n * with `rounded-lg` and `overflow-hidden` clipping the inner cells to the\n * radius. The outer wrapper is `relative` so the optional `floatingBadge`\n * can be absolutely positioned over the inner container's top border.\n *\n * ### Server-safe\n *\n * Pure presentation — no hooks, no event handlers on the DOM. Ships in\n * `./server` alongside `Stat`.\n *\n * @example\n * ```tsx\n * <StatGroup layout=\"strip\">\n *   <Stat icon={<Users />} value=\"9,4 mil\" label=\"Parlamentares\" align=\"center\" />\n *   <Stat icon={<FileText />} value=\"3,2 mil\" label=\"Proposições\" align=\"center\" />\n *   <Stat icon={<Vote />} value=\"1,1 mil\" label=\"Votações\" align=\"center\" />\n *   <Stat icon={<Clock />} value=\"há 18 dias\" label=\"Última atualização\" align=\"center\" />\n * </StatGroup>\n *\n * <StatGroup layout=\"grid\" cols={4}>\n *   <Stat value=\"87%\" label=\"Alinhamento\" hint=\"últimos 12 m\" tone=\"success\" />\n *   <Stat value={null} label=\"Sem orientação\" hint=\"no período\" />\n *   <Stat value=\"R$ 187.472,95\" label=\"Gastos\" hint=\"no mandato\" />\n *   <Stat value=\"42\" label=\"Votações\" hint=\"no banco\" />\n * </StatGroup>\n * ```\n */\nexport function StatGroup({\n  layout = \"grid\",\n  cols = 4,\n  floatingBadge,\n  className,\n  children,\n  ...props\n}: StatGroupProps) {\n  const isGrid = layout === \"grid\";\n\n  return (\n    <div\n      className={cn(\n        \"relative\",\n        floatingBadge && getSpacingClass(\"base\", \"pt\"),\n        className,\n      )}\n      {...props}\n    >\n      {floatingBadge ? (\n        <div className=\"absolute top-4 left-1/2 -translate-x-1/2 -translate-y-1/2 z-10\">\n          {floatingBadge}\n        </div>\n      ) : null}\n      <div\n        className={cn(\n          \"bg-line-default border border-line-default overflow-hidden gap-px\",\n          getRadiusClass(\"lg\"),\n          isGrid ? `grid grid-cols-2 ${gridColsMd[cols]}` : \"flex\",\n        )}\n      >\n        {children}\n      </div>\n    </div>\n  );\n}\n\nexport default StatGroup;\n"],"names":["gridColsMd","StatGroup","_a","_b","layout","cols","floatingBadge","className","children","props","__objRest","isGrid","jsxs","__spreadProps","__spreadValues","cn","getSpacingClass","jsx","getRadiusClass"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAmFA,MAAMA,IAA4C;AAAA,EAChD,GAAG;AAAA,EACH,GAAG;AAAA,EACH,GAAG;AACL;AA2CO,SAASC,EAAUC,GAOP;AAPO,MAAAC,IAAAD,GACxB;AAAA,YAAAE,IAAS;AAAA,IACT,MAAAC,IAAO;AAAA,IACP,eAAAC;AAAA,IACA,WAAAC;AAAA,IACA,UAAAC;AAAA,MALwBL,GAMrBM,IAAAC,EANqBP,GAMrB;AAAA,IALH;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA;AAGA,QAAMQ,IAASP,MAAW;AAE1B,SACE,gBAAAQ;AAAA,IAAC;AAAA,IAAAC,EAAAC,EAAA;AAAA,MACC,WAAWC;AAAA,QACT;AAAA,QACAT,KAAiBU,EAAgB,QAAQ,IAAI;AAAA,QAC7CT;AAAA,MAAA;AAAA,OAEEE,IANL;AAAA,MAQE,UAAA;AAAA,QAAAH,IACC,gBAAAW,EAAC,OAAA,EAAI,WAAU,kEACZ,aACH,IACE;AAAA,QACJ,gBAAAA;AAAA,UAAC;AAAA,UAAA;AAAA,YACC,WAAWF;AAAA,cACT;AAAA,cACAG,EAAe,IAAI;AAAA,cACnBP,IAAS,oBAAoBX,EAAWK,CAAI,CAAC,KAAK;AAAA,YAAA;AAAA,YAGnD,UAAAG;AAAA,UAAA;AAAA,QAAA;AAAA,MACH;AAAA,IAAA;AAAA,EAAA;AAGN;"}