@pumba-ui/ui 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vicente Loyola
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,146 @@
1
- # Temporary Holding Version
1
+ # @pumba-ui/ui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Accessible React components for the Pumba design system.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pnpm add @pumba-ui/ui
9
+ ```
10
+
11
+ `react` and `react-dom` (19 or later) are peer dependencies: your app provides them, so there
12
+ is only one copy of React.
13
+
14
+ ## Quick start
15
+
16
+ Import the styles once, then use the components:
17
+
18
+ ```css
19
+ @import "@pumba-ui/ui/styles.css";
20
+ ```
21
+
22
+ ```tsx
23
+ import { Button, Card } from "@pumba-ui/ui";
24
+
25
+ export function Welcome() {
26
+ return (
27
+ <Card.Root>
28
+ <Card.Content>Ready to go.</Card.Content>
29
+ <Card.Footer>
30
+ <Button>Get started</Button>
31
+ </Card.Footer>
32
+ </Card.Root>
33
+ );
34
+ }
35
+ ```
36
+
37
+ Every component, and every part of a compound component such as `Card.Root`, can be rendered
38
+ straight from a React Server Component (for example, a Next.js page). Each component file ships
39
+ its own `"use client"` directive, so you do not need a wrapper.
40
+
41
+ ## Components
42
+
43
+ `Button`, `Card`, `Badge`, `Input`, `Tabs` and `Dialog`. They accept the native props of the
44
+ element they render, append your `className` to their own, and take a `render` prop to change
45
+ the element they render. The rules every component follows are in
46
+ [`docs/api-conventions.md`](https://github.com/vnloyola/pumba-ui/blob/main/docs/api-conventions.md).
47
+
48
+ ## Styles
49
+
50
+ Import the stylesheet once, in your app's entry CSS or JS:
51
+
52
+ ```css
53
+ @import "@pumba-ui/ui/styles.css";
54
+ ```
55
+
56
+ It contains the tokens (`--pumba-*`), a minimal base and every component's styles. The reset is
57
+ **not** included.
58
+
59
+ It also loads the Figtree and JetBrains Mono variable fonts, which `@pumba-ui/ui` installs as
60
+ dependencies (`@fontsource-variable/*`). Your bundler copies the font files; the browser only
61
+ downloads the subsets (`unicode-range`) the page uses.
62
+
63
+ ### Layers
64
+
65
+ Pumba's CSS lives in layers under the `pumba.*` namespace, declared in this order:
66
+
67
+ ```css
68
+ @layer pumba.reset, pumba.tokens, pumba.base, pumba.components;
69
+ ```
70
+
71
+ `styles.css` starts with that statement. Your CSS outside any layer always wins over Pumba
72
+ without raising specificity.
73
+
74
+ ### Without Tailwind
75
+
76
+ Nothing else is needed. To also use Pumba's reset, import it first:
77
+
78
+ ```css
79
+ @import "@pumba-ui/ui/reset.css";
80
+ @import "@pumba-ui/ui/styles.css";
81
+ ```
82
+
83
+ ### With Tailwind v4
84
+
85
+ Declare the layer order **once, before any import**, with `pumba` between `components` and
86
+ `utilities`. Do not import `reset.css`: Tailwind's preflight already does that job.
87
+
88
+ ```css
89
+ @layer theme, base, components, pumba, utilities;
90
+ @import "tailwindcss";
91
+ @import "@pumba-ui/ui/styles.css";
92
+ ```
93
+
94
+ Tailwind utilities then win over Pumba, and Pumba wins over Tailwind's `base`. Without the
95
+ order statement the result depends on import order and one of the two stops working. See
96
+ section 13 of `docs/api-conventions.md` for the cases tested.
97
+
98
+ ## Theme
99
+
100
+ Colors follow the OS (`prefers-color-scheme`). Set `data-theme="light"` or `data-theme="dark"`
101
+ on `<html>`, or on any element to theme only its subtree.
102
+
103
+ ## For maintainers
104
+
105
+ ### Development
106
+
107
+ ```bash
108
+ pnpm --filter @pumba-ui/ui build # dist/: index.js, .d.ts, styles.css, reset.css
109
+ pnpm --filter @pumba-ui/ui check:package # publint and arethetypeswrong
110
+ ```
111
+
112
+ ### How the package is built
113
+
114
+ Three tools, one job each:
115
+
116
+ - **Vite** builds `src/` into readable ESM with one output file per source module
117
+ (`preserveModules`, `minify: false`; the consumer's bundler minifies). `react`, `react-dom`,
118
+ `lucide-react` and `@base-ui/react` stay external, so the consumer installs each once.
119
+ `emptyOutDir` is off because `dist/` also holds the types and CSS. Each component file
120
+ (`button.tsx`, `card.tsx`…) starts with `"use client"`, because the components call hooks
121
+ (`useRender`, `useRef`). The `index.ts` files do not: they build the compound objects
122
+ (`Card = { Root: CardRoot, … }`) outside the client module, so a Server Component that reads
123
+ `Card.Root` gets a client reference instead of `undefined`. A single bundle with one
124
+ `"use client"` banner cannot do that: the server only sees the `Card` object as an opaque
125
+ reference and cannot read its parts.
126
+ - **`tsc`** emits the declarations (`tsconfig.build.json`, which excludes tests and stories).
127
+ Relative imports in `src` carry the `.js` extension so the emitted types resolve under Node's
128
+ ESM rules.
129
+ - **`scripts/build-css.mjs`** inlines the CSS `@import`s with `postcss-import`, resolving
130
+ `@pumba-ui/tokens/tokens.css` through the package's `exports` map the way a bundler would.
131
+ The `@fontsource-variable/*` imports are left as they are: their CSS points at the font files
132
+ with relative URLs, which only resolve from the package's own folder, so the consumer's
133
+ bundler resolves them.
134
+ The CSS is otherwise left as written, so the layer order statement stays at the top of
135
+ `styles.css` and the files stay readable and unminified.
136
+
137
+ ### Conventions
138
+
139
+ - `src/icons.ts` is the only file that imports `lucide-react`. Components import icons from it,
140
+ so the icon library can change without touching them.
141
+ - Each component's CSS is added to `src/styles/styles.css` with
142
+ `@import url("../<name>/<name>.css") layer(pumba.components);`.
143
+ - `reset.css` is optional and separate from `styles.css`. Tailwind users skip it.
144
+ - Every Pumba stylesheet starts with the layer order, which lives in `src/styles/layers.css`.
145
+ The names sit under `pumba.*` so they never merge with Tailwind's own `base` and `components`
146
+ layers.
@@ -0,0 +1,7 @@
1
+ import type { ComponentProps, ReactElement } from "react";
2
+ export type BadgeProps = ComponentProps<"span"> & {
3
+ variant?: "neutral" | "accent" | "success" | "error" | "warning";
4
+ size?: "sm" | "md";
5
+ render?: ReactElement | ((props: ComponentProps<"span">) => ReactElement);
6
+ };
7
+ export declare function Badge(props: BadgeProps): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
@@ -0,0 +1,19 @@
1
+ "use client";
2
+ import { mergeProps } from "@base-ui/react/merge-props";
3
+ import { useRender } from "@base-ui/react/use-render";
4
+ //#region src/badge/badge.tsx
5
+ function Badge(props) {
6
+ const { variant = "neutral", size = "md", render, ref, ...rest } = props;
7
+ return useRender({
8
+ defaultTagName: "span",
9
+ render,
10
+ ref,
11
+ props: mergeProps({
12
+ className: "pumba-badge",
13
+ "data-variant": variant,
14
+ "data-size": size
15
+ }, rest)
16
+ });
17
+ }
18
+ //#endregion
19
+ export { Badge };
@@ -0,0 +1 @@
1
+ export { Badge, type BadgeProps } from "./badge.js";
@@ -0,0 +1,9 @@
1
+ import type { ComponentProps, ReactElement } from "react";
2
+ export type ButtonProps = ComponentProps<"button"> & {
3
+ variant?: "primary" | "secondary" | "ghost";
4
+ size?: "sm" | "md" | "lg";
5
+ loading?: boolean;
6
+ iconOnly?: boolean;
7
+ render?: ReactElement | ((props: ComponentProps<"button">) => ReactElement);
8
+ };
9
+ export declare function Button(props: ButtonProps): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
@@ -0,0 +1,25 @@
1
+ "use client";
2
+ import { mergeProps } from "@base-ui/react/merge-props";
3
+ import { useRender } from "@base-ui/react/use-render";
4
+ //#region src/button/button.tsx
5
+ function Button(props) {
6
+ const { variant = "primary", size = "md", loading = false, iconOnly = false, disabled = false, render, ref, onClick, ...rest } = props;
7
+ return useRender({
8
+ defaultTagName: "button",
9
+ render,
10
+ ref,
11
+ props: mergeProps({
12
+ className: "pumba-button",
13
+ "data-variant": variant,
14
+ "data-size": size,
15
+ "data-disabled": disabled ? "" : void 0,
16
+ "data-loading": loading ? "" : void 0,
17
+ "data-icon-only": iconOnly ? "" : void 0,
18
+ "aria-busy": loading || void 0,
19
+ disabled,
20
+ onClick: loading ? void 0 : onClick
21
+ }, rest)
22
+ });
23
+ }
24
+ //#endregion
25
+ export { Button };
@@ -0,0 +1 @@
1
+ export { Button, type ButtonProps } from "./button.js";
@@ -0,0 +1,9 @@
1
+ import type { ComponentProps, ReactElement } from "react";
2
+ export type CardProps = ComponentProps<"div"> & {
3
+ render?: ReactElement | ((props: ComponentProps<"div">) => ReactElement);
4
+ };
5
+ declare function CardRoot(props: CardProps): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
6
+ declare function CardHeader(props: CardProps): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
7
+ declare function CardContent(props: CardProps): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
8
+ declare function CardFooter(props: CardProps): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
9
+ export { CardContent, CardFooter, CardHeader, CardRoot };
@@ -0,0 +1,27 @@
1
+ "use client";
2
+ import { mergeProps } from "@base-ui/react/merge-props";
3
+ import { useRender } from "@base-ui/react/use-render";
4
+ //#region src/card/card.tsx
5
+ function usePart(className, props) {
6
+ const { render, ref, ...rest } = props;
7
+ return useRender({
8
+ defaultTagName: "div",
9
+ render,
10
+ ref,
11
+ props: mergeProps({ className }, rest)
12
+ });
13
+ }
14
+ function CardRoot(props) {
15
+ return usePart("pumba-card", props);
16
+ }
17
+ function CardHeader(props) {
18
+ return usePart("pumba-card-header", props);
19
+ }
20
+ function CardContent(props) {
21
+ return usePart("pumba-card-content", props);
22
+ }
23
+ function CardFooter(props) {
24
+ return usePart("pumba-card-footer", props);
25
+ }
26
+ //#endregion
27
+ export { CardContent, CardFooter, CardHeader, CardRoot };
@@ -0,0 +1,8 @@
1
+ import { CardContent, CardFooter, CardHeader, CardRoot } from "./card.js";
2
+ export type { CardProps } from "./card.js";
3
+ export declare const Card: {
4
+ Root: typeof CardRoot;
5
+ Header: typeof CardHeader;
6
+ Content: typeof CardContent;
7
+ Footer: typeof CardFooter;
8
+ };
@@ -0,0 +1,10 @@
1
+ import { CardContent, CardFooter, CardHeader, CardRoot } from "./card.js";
2
+ //#region src/card/index.ts
3
+ var Card = {
4
+ Root: CardRoot,
5
+ Header: CardHeader,
6
+ Content: CardContent,
7
+ Footer: CardFooter
8
+ };
9
+ //#endregion
10
+ export { Card };
@@ -0,0 +1,31 @@
1
+ import { type ComponentProps, type ReactElement, type ReactNode } from "react";
2
+ type Render<Tag extends "div" | "button" | "h2" | "p"> = ReactElement | ((props: ComponentProps<Tag>) => ReactElement);
3
+ export type DialogProps = {
4
+ open?: boolean;
5
+ defaultOpen?: boolean;
6
+ onOpenChange?: (open: boolean) => void;
7
+ children?: ReactNode;
8
+ };
9
+ type ButtonPartProps = ComponentProps<"button"> & {
10
+ nativeButton?: boolean;
11
+ render?: Render<"button">;
12
+ };
13
+ type DialogTriggerProps = ButtonPartProps;
14
+ type DialogContentProps = ComponentProps<"div"> & {
15
+ container?: HTMLElement | null;
16
+ render?: Render<"div">;
17
+ };
18
+ type DialogTitleProps = ComponentProps<"h2"> & {
19
+ render?: Render<"h2">;
20
+ };
21
+ type DialogDescriptionProps = ComponentProps<"p"> & {
22
+ render?: Render<"p">;
23
+ };
24
+ type DialogCloseProps = ButtonPartProps;
25
+ declare function DialogRoot({ onOpenChange, ...rest }: DialogProps): import("react").JSX.Element;
26
+ declare function DialogTrigger({ className, children, render, ...rest }: DialogTriggerProps): import("react").JSX.Element;
27
+ declare function DialogContent({ className, container, children, ref, ...rest }: DialogContentProps): import("react").JSX.Element;
28
+ declare function DialogTitle({ className, ...rest }: DialogTitleProps): import("react").JSX.Element;
29
+ declare function DialogDescription({ className, ...rest }: DialogDescriptionProps): import("react").JSX.Element;
30
+ declare function DialogClose({ className, children, render, ...rest }: DialogCloseProps): import("react").JSX.Element;
31
+ export { DialogClose, DialogContent, DialogDescription, DialogRoot, DialogTitle, DialogTrigger };
@@ -0,0 +1,72 @@
1
+ "use client";
2
+ import { Dialog } from "@base-ui/react/dialog";
3
+ import { isValidElement, useRef } from "react";
4
+ import { jsx, jsxs } from "react/jsx-runtime";
5
+ //#region src/dialog/dialog.tsx
6
+ var FOCUSABLE = "a[href], button:not([disabled]), input:not([disabled]):not([type=\"hidden\"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";
7
+ var setRefs = (...refs) => (node) => {
8
+ for (const ref of refs) if (typeof ref === "function") ref(node);
9
+ else if (ref) ref.current = node;
10
+ };
11
+ var elementFromChild = (children, render) => render === void 0 && isValidElement(children) ? {
12
+ render: children,
13
+ children: children.props.children
14
+ } : {
15
+ render,
16
+ children
17
+ };
18
+ var join = (own, className) => className ? `${own} ${className}` : own;
19
+ function DialogRoot({ onOpenChange, ...rest }) {
20
+ return /* @__PURE__ */ jsx(Dialog.Root, {
21
+ onOpenChange: (open) => onOpenChange?.(open),
22
+ ...rest
23
+ });
24
+ }
25
+ function DialogTrigger({ className, children, render, ...rest }) {
26
+ return /* @__PURE__ */ jsx(Dialog.Trigger, {
27
+ className: join("pumba-dialog-trigger", className),
28
+ ...elementFromChild(children, render),
29
+ ...rest
30
+ });
31
+ }
32
+ function DialogContent({ className, container, children, ref, ...rest }) {
33
+ const popup = useRef(null);
34
+ return /* @__PURE__ */ jsxs(Dialog.Portal, {
35
+ container,
36
+ children: [/* @__PURE__ */ jsx(Dialog.Backdrop, { className: "pumba-dialog-backdrop" }), /* @__PURE__ */ jsx(Dialog.Popup, {
37
+ className: join("pumba-dialog", className),
38
+ ref: setRefs(ref, popup),
39
+ initialFocus: () => {
40
+ const target = popup.current?.querySelector(FOCUSABLE) ?? popup.current;
41
+ target?.focus({ preventScroll: true });
42
+ return document.activeElement === target ? false : null;
43
+ },
44
+ ...rest,
45
+ children: /* @__PURE__ */ jsx("div", {
46
+ className: "pumba-dialog-body",
47
+ children
48
+ })
49
+ })]
50
+ });
51
+ }
52
+ function DialogTitle({ className, ...rest }) {
53
+ return /* @__PURE__ */ jsx(Dialog.Title, {
54
+ className: join("pumba-dialog-title", className),
55
+ ...rest
56
+ });
57
+ }
58
+ function DialogDescription({ className, ...rest }) {
59
+ return /* @__PURE__ */ jsx(Dialog.Description, {
60
+ className: join("pumba-dialog-description", className),
61
+ ...rest
62
+ });
63
+ }
64
+ function DialogClose({ className, children, render, ...rest }) {
65
+ return /* @__PURE__ */ jsx(Dialog.Close, {
66
+ className: join("pumba-dialog-close", className),
67
+ ...elementFromChild(children, render),
68
+ ...rest
69
+ });
70
+ }
71
+ //#endregion
72
+ export { DialogClose, DialogContent, DialogDescription, DialogRoot, DialogTitle, DialogTrigger };
@@ -0,0 +1,10 @@
1
+ import { DialogClose, DialogContent, DialogDescription, DialogRoot, DialogTitle, DialogTrigger } from "./dialog.js";
2
+ export type { DialogProps } from "./dialog.js";
3
+ export declare const Dialog: {
4
+ Root: typeof DialogRoot;
5
+ Trigger: typeof DialogTrigger;
6
+ Content: typeof DialogContent;
7
+ Title: typeof DialogTitle;
8
+ Description: typeof DialogDescription;
9
+ Close: typeof DialogClose;
10
+ };
@@ -0,0 +1,12 @@
1
+ import { DialogClose, DialogContent, DialogDescription, DialogRoot, DialogTitle, DialogTrigger } from "./dialog.js";
2
+ //#region src/dialog/index.ts
3
+ var Dialog = {
4
+ Root: DialogRoot,
5
+ Trigger: DialogTrigger,
6
+ Content: DialogContent,
7
+ Title: DialogTitle,
8
+ Description: DialogDescription,
9
+ Close: DialogClose
10
+ };
11
+ //#endregion
12
+ export { Dialog };
@@ -0,0 +1 @@
1
+ export { ArrowUpRight as ArrowUpRightIcon, Check as CheckIcon, ChevronDown as ChevronDownIcon, Clock as ClockIcon, DollarSign as DollarIcon, Heart as HeartIcon, MapPin as MapPinIcon, Share2 as ShareIcon, ShoppingCart as CartIcon, Sparkles as SparklesIcon, Star as StarIcon, TrendingDown as TrendingDownIcon, TrendingUp as TrendingUpIcon, TriangleAlert as WarningIcon, Users as UsersIcon, X as CloseIcon, } from "lucide-react";
@@ -0,0 +1,6 @@
1
+ export { Badge, type BadgeProps } from "./badge/index.js";
2
+ export { Button, type ButtonProps } from "./button/index.js";
3
+ export { Card, type CardProps } from "./card/index.js";
4
+ export { Dialog, type DialogProps } from "./dialog/index.js";
5
+ export { Input, type InputProps } from "./input/index.js";
6
+ export { Tabs, type TabsProps } from "./tabs/index.js";
package/dist/index.js ADDED
@@ -0,0 +1,7 @@
1
+ import { Badge } from "./badge/badge.js";
2
+ import { Button } from "./button/button.js";
3
+ import { Card } from "./card/index.js";
4
+ import { Dialog } from "./dialog/index.js";
5
+ import { Input } from "./input/input.js";
6
+ import { Tabs } from "./tabs/index.js";
7
+ export { Badge, Button, Card, Dialog, Input, Tabs };
@@ -0,0 +1 @@
1
+ export { Input, type InputProps } from "./input.js";
@@ -0,0 +1,7 @@
1
+ import type { ComponentProps, ReactElement } from "react";
2
+ export type InputProps = Omit<ComponentProps<"input">, "size"> & {
3
+ size?: "sm" | "md" | "lg";
4
+ invalid?: boolean;
5
+ render?: ReactElement | ((props: ComponentProps<"input">) => ReactElement);
6
+ };
7
+ export declare function Input(props: InputProps): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
@@ -0,0 +1,24 @@
1
+ "use client";
2
+ import { mergeProps } from "@base-ui/react/merge-props";
3
+ import { useRender } from "@base-ui/react/use-render";
4
+ //#region src/input/input.tsx
5
+ function Input(props) {
6
+ const { size = "md", invalid = false, render, ref, disabled, readOnly, ...rest } = props;
7
+ return useRender({
8
+ defaultTagName: "input",
9
+ render,
10
+ ref,
11
+ props: mergeProps({
12
+ className: "pumba-input",
13
+ "data-size": size,
14
+ "data-invalid": invalid ? "" : void 0,
15
+ "data-disabled": disabled ? "" : void 0,
16
+ "data-readonly": readOnly ? "" : void 0,
17
+ "aria-invalid": invalid || void 0,
18
+ disabled,
19
+ readOnly
20
+ }, rest)
21
+ });
22
+ }
23
+ //#endregion
24
+ export { Input };
package/dist/reset.css ADDED
@@ -0,0 +1,29 @@
1
+ @layer pumba.reset, pumba.tokens, pumba.base, pumba.components;
2
+ @layer pumba.reset {
3
+ *,
4
+ *::before,
5
+ *::after {
6
+ box-sizing: border-box;
7
+ }
8
+
9
+ * {
10
+ margin: 0;
11
+ }
12
+
13
+ img,
14
+ picture,
15
+ video,
16
+ canvas,
17
+ svg {
18
+ display: block;
19
+ max-width: 100%;
20
+ }
21
+
22
+ input,
23
+ button,
24
+ textarea,
25
+ select {
26
+ font: inherit;
27
+ color: inherit;
28
+ }
29
+ }