@renge-ui/react 1.0.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.
Files changed (8) hide show
  1. package/README.md +230 -0
  2. package/dist/index.d.mts +245 -0
  3. package/dist/index.d.ts +245 -0
  4. package/dist/index.js +1404 -0
  5. package/dist/index.js.map +1 -0
  6. package/dist/index.mjs +1349 -0
  7. package/dist/index.mjs.map +1 -0
  8. package/package.json +44 -0
package/README.md ADDED
@@ -0,0 +1,230 @@
1
+ # @renge-ui/react
2
+
3
+ React component primitives for the Renge design system. Components consume `@renge-ui/tokens` CSS custom properties via inline styles — no CSS-in-JS runtime, no class names.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pnpm add @renge-ui/react
9
+ ```
10
+
11
+ ## Setup
12
+
13
+ Wrap your app in `RengeProvider`. It injects the generated CSS variables into `<head>` automatically.
14
+
15
+ ```tsx
16
+ import { RengeProvider } from '@renge-ui/react';
17
+
18
+ function App() {
19
+ return (
20
+ <RengeProvider config={{ profile: 'ocean' }}>
21
+ <YourApp />
22
+ </RengeProvider>
23
+ );
24
+ }
25
+ ```
26
+
27
+ ### Provider Props
28
+
29
+ | Prop | Type | Default | Description |
30
+ |------|------|---------|-------------|
31
+ | `config` | `RengeThemeConfig` | `{}` | Theme configuration (see `@renge-ui/tokens`) |
32
+ | `injectCSS` | `boolean` | `true` | Inject CSS into `<head>`. Set `false` for SSR or manual injection. |
33
+
34
+ ---
35
+
36
+ ## Hooks
37
+
38
+ ### `useRenge()`
39
+
40
+ Returns the current theme and profile from context. Must be used inside `RengeProvider`.
41
+
42
+ ```tsx
43
+ const { theme, profile } = useRenge();
44
+ // theme.vars['--renge-color-accent']
45
+ // theme.css → full CSS string
46
+ // profile → 'ocean' | 'earth' | 'twilight'
47
+ ```
48
+
49
+ ### `useRengeTheme(config?)`
50
+
51
+ Creates a theme without a provider — useful for SSR or static export.
52
+
53
+ ```tsx
54
+ const theme = useRengeTheme({ profile: 'twilight' });
55
+ // Inject theme.css server-side, or pass to a <style> tag
56
+ ```
57
+
58
+ ---
59
+
60
+ ## Components
61
+
62
+ All components use `forwardRef`, accept all standard HTML props for their underlying element, and allow style overrides via the `style` prop. Most support a polymorphic `as` prop to change the rendered element.
63
+
64
+ ### `Stack`
65
+
66
+ Flexbox layout container.
67
+
68
+ ```tsx
69
+ <Stack gap="4" direction="horizontal" align="center" justify="between">
70
+ <Button>Left</Button>
71
+ <Button>Right</Button>
72
+ </Stack>
73
+ ```
74
+
75
+ | Prop | Type | Default |
76
+ |------|------|---------|
77
+ | `gap` | `'0'–'10'` | `'3'` |
78
+ | `direction` | `'vertical' \| 'horizontal'` | `'vertical'` |
79
+ | `align` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` |
80
+ | `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around'` | `'start'` |
81
+ | `as` | `ElementType` | `'div'` |
82
+
83
+ ### `Grid`
84
+
85
+ CSS Grid layout container.
86
+
87
+ ```tsx
88
+ <Grid columns={3} gap="4">
89
+ <Card>One</Card>
90
+ <Card>Two</Card>
91
+ <Card>Three</Card>
92
+ </Grid>
93
+ ```
94
+
95
+ | Prop | Type | Default |
96
+ |------|------|---------|
97
+ | `columns` | `number \| string` | `1` |
98
+ | `rows` | `number \| string` | — |
99
+ | `gap` | `'0'–'6'` | `'3'` |
100
+ | `gapX` | `'0'–'6'` | — |
101
+ | `gapY` | `'0'–'6'` | — |
102
+ | `align` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` |
103
+ | `justify` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` |
104
+
105
+ ### `Text`
106
+
107
+ Inline or block text with token-driven sizing.
108
+
109
+ ```tsx
110
+ <Text size="lg" weight="medium" color="fg-subtle">
111
+ Caption text
112
+ </Text>
113
+ ```
114
+
115
+ | Prop | Type | Default |
116
+ |------|------|---------|
117
+ | `size` | `'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'` | `'base'` |
118
+ | `color` | `'fg' \| 'fg-subtle' \| 'fg-muted' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'fg'` |
119
+ | `weight` | `'normal' \| 'medium' \| 'semibold' \| 'bold'` | `'normal'` |
120
+ | `align` | `'left' \| 'center' \| 'right'` | — |
121
+ | `as` | `ElementType` | `'span'` |
122
+
123
+ ### `Heading`
124
+
125
+ Semantic heading with automatic size defaults per level.
126
+
127
+ ```tsx
128
+ <Heading level={1}>Page Title</Heading>
129
+ <Heading level={3} size="2xl">Override size</Heading>
130
+ ```
131
+
132
+ | Prop | Type | Default |
133
+ |------|------|---------|
134
+ | `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` |
135
+ | `size` | `'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'` | auto (level-based) |
136
+ | `color` | `'fg' \| 'fg-subtle' \| 'accent'` | `'fg'` |
137
+
138
+ Default sizes by level: h1→3xl, h2→2xl, h3→xl, h4–h6→lg.
139
+
140
+ ### `Card`
141
+
142
+ Content container with three visual variants.
143
+
144
+ ```tsx
145
+ <Card variant="outlined" padding="5" radius="3">
146
+ Content
147
+ </Card>
148
+ ```
149
+
150
+ | Prop | Type | Default |
151
+ |------|------|---------|
152
+ | `variant` | `'elevated' \| 'outlined' \| 'filled'` | `'elevated'` |
153
+ | `padding` | `'0'–'6'` | `'4'` |
154
+ | `radius` | `'none' \| '1'–'5' \| 'full'` | `'3'` |
155
+
156
+ ### `Button`
157
+
158
+ ```tsx
159
+ <Button variant="outline" colorScheme="danger" size="sm">
160
+ Delete
161
+ </Button>
162
+ ```
163
+
164
+ | Prop | Type | Default |
165
+ |------|------|---------|
166
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |
167
+ | `variant` | `'solid' \| 'outline' \| 'ghost'` | `'solid'` |
168
+ | `colorScheme` | `'accent' \| 'danger' \| 'success'` | `'accent'` |
169
+ | `fullWidth` | `boolean` | `false` |
170
+
171
+ ### `Divider`
172
+
173
+ ```tsx
174
+ <Divider spacing="5" />
175
+ <Divider orientation="vertical" color="border" />
176
+ ```
177
+
178
+ | Prop | Type | Default |
179
+ |------|------|---------|
180
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
181
+ | `spacing` | `'0'–'6'` | `'3'` |
182
+ | `color` | `'border' \| 'border-subtle'` | `'border-subtle'` |
183
+
184
+ ### `Section`
185
+
186
+ Page section with max-width constraint and auto-centering.
187
+
188
+ ```tsx
189
+ <Section maxWidth="lg" paddingY="8">
190
+ <Heading>Welcome</Heading>
191
+ </Section>
192
+ ```
193
+
194
+ | Prop | Type | Default |
195
+ |------|------|---------|
196
+ | `maxWidth` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' \| 'none'` | `'lg'` |
197
+ | `padding` | `'0'–'8'` | — |
198
+ | `paddingX` | `'0'–'8'` | `'4'` |
199
+ | `paddingY` | `'0'–'8'` | `'6'` |
200
+ | `center` | `boolean` | `true` |
201
+ | `as` | `ElementType` | `'section'` |
202
+
203
+ ---
204
+
205
+ ## SSR / Static Export
206
+
207
+ Use `injectCSS={false}` and inject the CSS string server-side:
208
+
209
+ ```tsx
210
+ import { createRengeTheme } from '@renge-ui/tokens';
211
+
212
+ // Server
213
+ const theme = createRengeTheme({ profile: 'ocean' });
214
+ // Embed theme.css in your HTML <head>
215
+
216
+ // Client
217
+ <RengeProvider config={{ profile: 'ocean' }} injectCSS={false}>
218
+ <App />
219
+ </RengeProvider>
220
+ ```
221
+
222
+ ---
223
+
224
+ ## Development
225
+
226
+ ```bash
227
+ pnpm build # compile to dist/
228
+ pnpm dev # watch mode
229
+ pnpm typecheck # tsc --noEmit
230
+ ```
package/dist/index.d.mts ADDED
@@ -0,0 +1,245 @@
1
+ import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import * as react from 'react';
3
+ import { ReactNode, ElementType, ComponentPropsWithoutRef } from 'react';
4
+ import { RengeTheme, RengeThemeConfig, AnimationName } from '@renge-ui/tokens';
5
+ export { ANIMATION_NAMES, AnimationName, FIBONACCI, GOLDEN_ANGLE, PHI, ProfileMode, ProfileName, ProfileVariant, RengeTheme, RengeThemeConfig, createRengeTheme } from '@renge-ui/tokens';
6
+
7
+ interface RengeContextValue {
8
+ theme: RengeTheme;
9
+ profile: string;
10
+ }
11
+
12
+ declare function useRenge(): RengeContextValue;
13
+
14
+ interface RengeProviderProps {
15
+ children: ReactNode;
16
+ config?: RengeThemeConfig;
17
+ /** Inject theme CSS into document <head>. Default: true */
18
+ injectCSS?: boolean;
19
+ }
20
+ declare function RengeProvider({ children, config: { baseUnit, typeBase, scaleRatio, profile, variance, varianceSeed, includeReset, selector, }, injectCSS, }: RengeProviderProps): react_jsx_runtime.JSX.Element;
21
+ /** Access raw theme without a provider — for SSR or static export. */
22
+ declare function useRengeTheme(config?: RengeThemeConfig): RengeTheme;
23
+
24
+ type SpaceKey$5 = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10';
25
+ interface StackOwnProps {
26
+ gap?: SpaceKey$5;
27
+ direction?: 'vertical' | 'horizontal';
28
+ align?: 'start' | 'center' | 'end' | 'stretch';
29
+ justify?: 'start' | 'center' | 'end' | 'between' | 'around';
30
+ as?: ElementType;
31
+ }
32
+ declare const Stack: react.ForwardRefExoticComponent<StackOwnProps & Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof StackOwnProps> & react.RefAttributes<HTMLDivElement>>;
33
+
34
+ type SpaceKey$4 = '0' | '1' | '2' | '3' | '4' | '5' | '6';
35
+ interface GridProps extends ComponentPropsWithoutRef<'div'> {
36
+ columns?: number | string;
37
+ rows?: number | string;
38
+ gap?: SpaceKey$4;
39
+ gapX?: SpaceKey$4;
40
+ gapY?: SpaceKey$4;
41
+ align?: 'start' | 'center' | 'end' | 'stretch';
42
+ justify?: 'start' | 'center' | 'end' | 'stretch';
43
+ }
44
+ declare const Grid: react.ForwardRefExoticComponent<GridProps & react.RefAttributes<HTMLDivElement>>;
45
+
46
+ type SizeKey$2 = 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
47
+ type ColorKey = 'fg' | 'fg-subtle' | 'fg-muted' | 'accent' | 'success' | 'warning' | 'danger';
48
+ interface TextOwnProps {
49
+ size?: SizeKey$2;
50
+ color?: ColorKey;
51
+ weight?: 'normal' | 'medium' | 'semibold' | 'bold';
52
+ align?: 'left' | 'center' | 'right';
53
+ animation?: AnimationName;
54
+ as?: ElementType;
55
+ }
56
+ declare const Text: react.ForwardRefExoticComponent<TextOwnProps & Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref">, keyof TextOwnProps> & react.RefAttributes<HTMLSpanElement>>;
57
+
58
+ type Level = 1 | 2 | 3 | 4 | 5 | 6;
59
+ type SizeKey$1 = 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
60
+ interface HeadingProps extends Omit<ComponentPropsWithoutRef<'h1'>, 'color'> {
61
+ level?: Level;
62
+ size?: SizeKey$1;
63
+ color?: 'fg' | 'fg-subtle' | 'accent';
64
+ animation?: AnimationName;
65
+ }
66
+ declare const Heading: react.ForwardRefExoticComponent<HeadingProps & react.RefAttributes<HTMLHeadingElement>>;
67
+
68
+ type SpaceKey$3 = '0' | '1' | '2' | '3' | '4' | '5' | '6';
69
+ type RadiusKey = 'none' | '1' | '2' | '3' | '4' | '5' | 'full';
70
+ interface CardProps extends ComponentPropsWithoutRef<'div'> {
71
+ padding?: SpaceKey$3;
72
+ radius?: RadiusKey;
73
+ variant?: 'elevated' | 'outlined' | 'filled';
74
+ animation?: AnimationName;
75
+ }
76
+ declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLDivElement>>;
77
+
78
+ type SizeKey = 'sm' | 'md' | 'lg';
79
+ type Variant = 'solid' | 'outline' | 'ghost';
80
+ type ColorScheme = 'accent' | 'danger' | 'success';
81
+ interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
82
+ size?: SizeKey;
83
+ variant?: Variant;
84
+ colorScheme?: ColorScheme;
85
+ fullWidth?: boolean;
86
+ animation?: AnimationName;
87
+ }
88
+ declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
89
+
90
+ type SpaceKey$2 = '0' | '1' | '2' | '3' | '4' | '5' | '6';
91
+ interface DividerProps extends ComponentPropsWithoutRef<'hr'> {
92
+ orientation?: 'horizontal' | 'vertical';
93
+ spacing?: SpaceKey$2;
94
+ color?: 'border' | 'border-subtle';
95
+ }
96
+ declare const Divider: react.ForwardRefExoticComponent<DividerProps & react.RefAttributes<HTMLHRElement>>;
97
+
98
+ type SpaceKey$1 = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8';
99
+ interface SectionOwnProps {
100
+ padding?: SpaceKey$1;
101
+ paddingX?: SpaceKey$1;
102
+ paddingY?: SpaceKey$1;
103
+ maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | 'full' | 'none';
104
+ center?: boolean;
105
+ animation?: AnimationName;
106
+ as?: ElementType;
107
+ }
108
+ declare const Section: react.ForwardRefExoticComponent<SectionOwnProps & Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLElement>, HTMLElement>, "ref">, keyof SectionOwnProps> & react.RefAttributes<HTMLElement>>;
109
+
110
+ type BadgeVariant = 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'neutral';
111
+ type BadgeSize = 'sm' | 'md' | 'lg';
112
+ interface BadgeProps extends ComponentPropsWithoutRef<'span'> {
113
+ variant?: BadgeVariant;
114
+ size?: BadgeSize;
115
+ }
116
+ declare const Badge: react.ForwardRefExoticComponent<BadgeProps & react.RefAttributes<HTMLSpanElement>>;
117
+
118
+ type AvatarSize = '1' | '2' | '3' | '4' | '5';
119
+ type AvatarShape = 'circle' | 'square';
120
+ interface AvatarProps extends ComponentPropsWithoutRef<'div'> {
121
+ src?: string;
122
+ alt?: string;
123
+ initials?: string;
124
+ size?: AvatarSize;
125
+ shape?: AvatarShape;
126
+ }
127
+ declare const Avatar: react.ForwardRefExoticComponent<AvatarProps & react.RefAttributes<HTMLDivElement>>;
128
+
129
+ type SpinnerSize = 'sm' | 'md' | 'lg';
130
+ type SpinnerColor = 'accent' | 'fg' | 'fg-muted';
131
+ interface SpinnerProps extends ComponentPropsWithoutRef<'span'> {
132
+ size?: SpinnerSize;
133
+ color?: SpinnerColor;
134
+ label?: string;
135
+ }
136
+ declare const Spinner: react.ForwardRefExoticComponent<SpinnerProps & react.RefAttributes<HTMLSpanElement>>;
137
+
138
+ type ProgressColor = 'accent' | 'success' | 'warning' | 'danger';
139
+ type ProgressSize = 'sm' | 'md' | 'lg';
140
+ interface ProgressProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
141
+ value: number;
142
+ color?: ProgressColor;
143
+ size?: ProgressSize;
144
+ radius?: 'none' | 'full';
145
+ label?: string;
146
+ }
147
+ declare const Progress: react.ForwardRefExoticComponent<ProgressProps & react.RefAttributes<HTMLDivElement>>;
148
+
149
+ type InputSize = 'sm' | 'md' | 'lg';
150
+ type InputState = 'default' | 'error' | 'success';
151
+ interface InputProps extends Omit<ComponentPropsWithoutRef<'input'>, 'size'> {
152
+ size?: InputSize;
153
+ state?: InputState;
154
+ fullWidth?: boolean;
155
+ }
156
+ declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
157
+
158
+ type ChipVariant = 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'neutral';
159
+ interface ChipProps extends ComponentPropsWithoutRef<'span'> {
160
+ variant?: ChipVariant;
161
+ onDismiss?: () => void;
162
+ }
163
+ declare const Chip: react.ForwardRefExoticComponent<ChipProps & react.RefAttributes<HTMLSpanElement>>;
164
+
165
+ type AlertStatus = 'info' | 'success' | 'warning' | 'danger';
166
+ interface AlertProps extends ComponentPropsWithoutRef<'div'> {
167
+ status?: AlertStatus;
168
+ title?: string;
169
+ }
170
+ declare const Alert: react.ForwardRefExoticComponent<AlertProps & react.RefAttributes<HTMLDivElement>>;
171
+
172
+ interface FormFieldProps extends ComponentPropsWithoutRef<'div'> {
173
+ label: string;
174
+ htmlFor?: string;
175
+ helperText?: string;
176
+ errorText?: string;
177
+ required?: boolean;
178
+ }
179
+ declare const FormField: react.ForwardRefExoticComponent<FormFieldProps & react.RefAttributes<HTMLDivElement>>;
180
+
181
+ type TrendDirection = 'up' | 'down' | 'neutral';
182
+ interface StatProps extends ComponentPropsWithoutRef<'div'> {
183
+ value: string | number;
184
+ label: string;
185
+ trend?: TrendDirection;
186
+ trendValue?: string;
187
+ caption?: string;
188
+ }
189
+ declare const Stat: react.ForwardRefExoticComponent<StatProps & react.RefAttributes<HTMLDivElement>>;
190
+
191
+ type SpaceKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8';
192
+ interface NavbarProps extends ComponentPropsWithoutRef<'nav'> {
193
+ sticky?: boolean;
194
+ border?: boolean;
195
+ height?: string;
196
+ paddingX?: SpaceKey;
197
+ }
198
+ declare const Navbar: react.ForwardRefExoticComponent<NavbarProps & react.RefAttributes<HTMLElement>>;
199
+
200
+ type EnergyRingSize = "sm" | "md" | "lg" | "xl";
201
+ type EnergyRingRate = "rest" | "active" | "fire";
202
+ type EnergyRingColor = "accent" | "success" | "warning" | "danger";
203
+ interface EnergyRingProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
204
+ /** Energy level 0–100 */
205
+ value: number;
206
+ size?: EnergyRingSize;
207
+ /** Color channel — maps to semantic token */
208
+ color?: EnergyRingColor;
209
+ /** Whether to animate a breathing pulse */
210
+ pulse?: boolean;
211
+ /** Pulse speed — rest=slow, active=medium, fire=fast */
212
+ rate?: EnergyRingRate;
213
+ /** Center label. Defaults to "{value}%" */
214
+ label?: string | null;
215
+ }
216
+ declare const EnergyRing: react.ForwardRefExoticComponent<EnergyRingProps & react.RefAttributes<HTMLDivElement>>;
217
+
218
+ type PulseRate = "rest" | "active" | "fire";
219
+ type PulseColor = "accent" | "success" | "warning" | "danger" | "fg-muted";
220
+ type PulseSize = "sm" | "md" | "lg";
221
+ interface PulseProps extends ComponentPropsWithoutRef<"span"> {
222
+ /** Energy rate — determines breath speed */
223
+ rate?: PulseRate;
224
+ color?: PulseColor;
225
+ size?: PulseSize;
226
+ /** Show expanding ripple ring */
227
+ ripple?: boolean;
228
+ }
229
+ declare const Pulse: react.ForwardRefExoticComponent<PulseProps & react.RefAttributes<HTMLSpanElement>>;
230
+
231
+ type FlowEnergy = "void" | "rest" | "active" | "fire";
232
+ type FlowColor = "accent" | "fg-muted" | "fg-subtle";
233
+ interface FlowFieldProps extends ComponentPropsWithoutRef<"div"> {
234
+ /** Total dot count at full energy. Actual count scales with energy. */
235
+ count?: number;
236
+ /** Size of the field container in px */
237
+ size?: number;
238
+ /** Energy level — controls density, opacity, and pulse rate */
239
+ energy?: FlowEnergy;
240
+ /** Color channel */
241
+ color?: FlowColor;
242
+ }
243
+ declare const FlowField: react.ForwardRefExoticComponent<FlowFieldProps & react.RefAttributes<HTMLDivElement>>;
244
+
245
+ export { Alert, type AlertProps, type AlertStatus, Avatar, type AvatarProps, type AvatarShape, type AvatarSize, Badge, type BadgeProps, type BadgeSize, type BadgeVariant, Button, Card, Chip, type ChipProps, type ChipVariant, Divider, EnergyRing, type EnergyRingColor, type EnergyRingProps, type EnergyRingRate, type EnergyRingSize, type FlowColor, type FlowEnergy, FlowField, type FlowFieldProps, FormField, type FormFieldProps, Grid, Heading, Input, type InputProps, type InputSize, type InputState, Navbar, type NavbarProps, Progress, type ProgressColor, type ProgressProps, type ProgressSize, Pulse, type PulseColor, type PulseProps, type PulseRate, type PulseSize, RengeProvider, type RengeProviderProps, Section, Spinner, type SpinnerColor, type SpinnerProps, type SpinnerSize, Stack, Stat, type StatProps, Text, type TrendDirection, useRenge, useRengeTheme };