npm - @renge-ui/react - Versions diffs - 1.0.0 → 1.0.2 - Mend

@renge-ui/react 1.0.0 → 1.0.2

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 (2) hide show

package/README.md +248 -29
package/package.json +14 -5

package/README.md CHANGED Viewed

@@ -10,14 +10,14 @@ pnpm add @renge-ui/react
 ## Setup
-Wrap your app in `RengeProvider`. It injects the generated CSS variables into `<head>` automatically.
+Wrap your app in `RengeProvider`. It injects the generated CSS variables into `<head>` automatically via `useInsertionEffect`.
 ```tsx
 import { RengeProvider } from '@renge-ui/react';
 function App() {
   return (
-    <RengeProvider config={{ profile: 'ocean' }}>
+    <RengeProvider config={{ profile: 'ocean', mode: 'light' }}>
       <YourApp />
     </RengeProvider>
   );
@@ -37,13 +37,13 @@ function App() {
 ### `useRenge()`
-Returns the current theme and profile from context. Must be used inside `RengeProvider`.
+Returns the current theme and profile from context. Must be inside `RengeProvider`.
 ```tsx
 const { theme, profile } = useRenge();
 // theme.vars['--renge-color-accent']
 // theme.css  → full CSS string
-// profile    → 'ocean' | 'earth' | 'twilight'
+// profile    → 'ocean' | 'earth' | 'twilight' | 'fire' | 'void' | 'leaf'
 ```
 ### `useRengeTheme(config?)`
@@ -51,7 +51,7 @@ const { theme, profile } = useRenge();
 Creates a theme without a provider — useful for SSR or static export.
 ```tsx
-const theme = useRengeTheme({ profile: 'twilight' });
+const theme = useRengeTheme({ profile: 'twilight', mode: 'dark' });
 // Inject theme.css server-side, or pass to a <style> tag
 ```
@@ -59,9 +59,13 @@ const theme = useRengeTheme({ profile: 'twilight' });
 ## Components
-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.
+All components use `forwardRef`, accept all standard HTML props for their underlying element, and allow style overrides via the `style` prop (applied last — overrides always win). Most support a polymorphic `as` prop to change the rendered element.
-### `Stack`
+---
+### Layout
+#### `Stack`
 Flexbox layout container.
@@ -80,7 +84,7 @@ Flexbox layout container.
 | `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around'` | `'start'` |
 | `as` | `ElementType` | `'div'` |
-### `Grid`
+#### `Grid`
 CSS Grid layout container.
@@ -102,7 +106,30 @@ CSS Grid layout container.
 | `align` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` |
 | `justify` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` |
-### `Text`
+#### `Section`
+Page section with max-width constraint and auto-centering.
+```tsx
+<Section maxWidth="lg" paddingY="8">
+  <Heading>Welcome</Heading>
+</Section>
+```
+| Prop | Type | Default |
+|------|------|---------|
+| `maxWidth` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' \| 'none'` | `'lg'` |
+| `padding` | `'0'–'8'` | — |
+| `paddingX` | `'0'–'8'` | `'4'` |
+| `paddingY` | `'0'–'8'` | `'6'` |
+| `center` | `boolean` | `true` |
+| `as` | `ElementType` | `'section'` |
+---
+### Text
+#### `Text`
 Inline or block text with token-driven sizing.
@@ -120,7 +147,7 @@ Inline or block text with token-driven sizing.
 | `align` | `'left' \| 'center' \| 'right'` | — |
 | `as` | `ElementType` | `'span'` |
-### `Heading`
+#### `Heading`
 Semantic heading with automatic size defaults per level.
@@ -135,9 +162,13 @@ Semantic heading with automatic size defaults per level.
 | `size` | `'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'` | auto (level-based) |
 | `color` | `'fg' \| 'fg-subtle' \| 'accent'` | `'fg'` |
-Default sizes by level: h1→3xl, h2→2xl, h3→xl, h4–h6→lg.
+Default sizes: h1→3xl, h2→2xl, h3→xl, h4–h6→lg.
+---
+### Containers
-### `Card`
+#### `Card`
 Content container with three visual variants.
@@ -153,7 +184,11 @@ Content container with three visual variants.
 | `padding` | `'0'–'6'` | `'4'` |
 | `radius` | `'none' \| '1'–'5' \| 'full'` | `'3'` |
-### `Button`
+---
+### Interactive
+#### `Button`
 ```tsx
 <Button variant="outline" colorScheme="danger" size="sm">
@@ -168,7 +203,61 @@ Content container with three visual variants.
 | `colorScheme` | `'accent' \| 'danger' \| 'success'` | `'accent'` |
 | `fullWidth` | `boolean` | `false` |
-### `Divider`
+#### `Input`
+```tsx
+<Input size="md" state="error" fullWidth placeholder="Enter email..." />
+```
+| Prop | Type | Default |
+|------|------|---------|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |
+| `state` | `'default' \| 'error' \| 'success'` | `'default'` |
+| `fullWidth` | `boolean` | `false` |
+Note: `Input` uses `Omit<ComponentPropsWithoutRef<'input'>, 'size'>` to shadow the native `size: number` attribute with the semantic size prop.
+Focus ring is applied via `onFocus`/`onBlur` handlers (inline styles cannot target `:focus-visible`). The outline uses `--renge-color-border-focus`.
+#### `Chip`
+Small inline tag — dismissible or selectable.
+```tsx
+<Chip>Design systems</Chip>
+```
+---
+### Status & Decoration
+#### `Badge`
+Label badge with semantic color variants.
+```tsx
+<Badge variant="success" size="sm">Active</Badge>
+<Badge variant="danger">Deprecated</Badge>
+```
+| Prop | Type | Default |
+|------|------|---------|
+| `variant` | `'accent' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'neutral'` | `'neutral'` |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |
+#### `Alert`
+Alert message with status-driven color.
+```tsx
+<Alert status="warning">Variance is enabled.</Alert>
+```
+| Prop | Type | Default |
+|------|------|---------|
+| `status` | `'success' \| 'warning' \| 'danger' \| 'info'` | `'info'` |
+#### `Divider`
 ```tsx
 <Divider spacing="5" />
@@ -181,24 +270,115 @@ Content container with three visual variants.
 | `spacing` | `'0'–'6'` | `'3'` |
 | `color` | `'border' \| 'border-subtle'` | `'border-subtle'` |
-### `Section`
+#### `Spinner`
-Page section with max-width constraint and auto-centering.
+Loading indicator. Injects `@keyframes rengeSpinnerSpin` once at module load.
 ```tsx
-<Section maxWidth="lg" paddingY="8">
-  <Heading>Welcome</Heading>
-</Section>
+<Spinner size="md" />
 ```
 | Prop | Type | Default |
 |------|------|---------|
-| `maxWidth` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' \| 'none'` | `'lg'` |
-| `padding` | `'0'–'8'` | — |
-| `paddingX` | `'0'–'8'` | `'4'` |
-| `paddingY` | `'0'–'8'` | `'6'` |
-| `center` | `boolean` | `true` |
-| `as` | `ElementType` | `'section'` |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |
+#### `Progress`
+Progress bar.
+```tsx
+<Progress value={65} size="md" />
+```
+| Prop | Type | Default |
+|------|------|---------|
+| `value` | `number` (0–100) | `0` |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |
+#### `Avatar`
+User avatar with size and shape options.
+```tsx
+<Avatar src="/photo.jpg" alt="Vanessa" size="lg" shape="circle" />
+```
+| Prop | Type | Default |
+|------|------|---------|
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
+| `shape` | `'circle' \| 'square'` | `'circle'` |
+---
+### Forms
+#### `FormField`
+Label + input wrapper with consistent spacing.
+```tsx
+<FormField label="Email" required>
+  <Input placeholder="you@example.com" />
+</FormField>
+```
+#### `Stat`
+Metric display with optional trend direction.
+```tsx
+<Stat label="Active users" value="1,284" trend="up" delta="+12%" />
+```
+---
+### Navigation
+#### `Navbar`
+Navigation bar primitive. Handles sticky positioning and border.
+```tsx
+<Navbar sticky border paddingX="5">
+  <Logo />
+  <Stack direction="horizontal" gap="4">
+    <a href="/docs">Docs</a>
+  </Stack>
+</Navbar>
+```
+| Prop | Type | Default |
+|------|------|---------|
+| `sticky` | `boolean` | `false` |
+| `border` | `boolean` | `true` |
+| `height` | `string` | `'56px'` |
+| `paddingX` | `'0'–'8'` | `'5'` |
+---
+### Experimental
+These components are functional but not yet stabilized — APIs may change.
+#### `EnergyRing`
+Animated pulsing ring. Useful for loading states or ambient indicators.
+```tsx
+<EnergyRing size={48} rate="slow" color="accent" />
+```
+#### `Pulse`
+Pulsing animation wrapper.
+```tsx
+<Pulse rate="medium" color="success"><StatusDot /></Pulse>
+```
+#### `FlowField`
+Animated flow-field canvas visualization. Accepts energy intensity and color profile.
 ---
@@ -209,16 +389,55 @@ Use `injectCSS={false}` and inject the CSS string server-side:
 ```tsx
 import { createRengeTheme } from '@renge-ui/tokens';
-// Server
-const theme = createRengeTheme({ profile: 'ocean' });
+// Server — generate CSS for all profiles you need
+const theme = createRengeTheme({ profile: 'ocean', mode: 'light' });
 // Embed theme.css in your HTML <head>
-// Client
-<RengeProvider config={{ profile: 'ocean' }} injectCSS={false}>
+// Client — match profile to avoid re-injecting
+<RengeProvider config={{ profile: 'ocean', mode: 'light' }} injectCSS={false}>
   <App />
 </RengeProvider>
 ```
+For multi-profile support (profile switcher), generate CSS for each profile using `data-profile` attribute selectors and inject all of them at build time. See `apps/lib/tokens.ts` in the monorepo for a reference implementation.
+---
+## Architecture
+Components have no opinions about class names, CSS files, or external stylesheets. Every visual decision is an inline `style` referencing a `--renge-*` CSS custom property. This means:
+- Components work anywhere the token CSS is injected — React, Remix, Next.js, plain HTML.
+- Overrides are always via the `style` prop. No specificity battles.
+- Bundle output contains no CSS. Zero style conflicts with your existing stylesheet.
+The rendering chain is:
+```
+createRengeTheme() → theme.css → injected into <head>
+       ↓
+CSS custom properties on :root
+       ↓
+Components read var(--renge-*) via inline styles
+```
+---
+## Trade-offs
+**No pseudo-class support.** Inline styles cannot target `:hover`, `:focus-visible`, `:disabled`, etc. This is the main limitation of the inline-styles approach. Workarounds:
+- Focus rings use `onFocus`/`onBlur` JS handlers (see `Input`).
+- Hover states are not currently implemented in primitives — add them via the `style` prop + event handlers in your application layer, or override with a CSS class.
+**No class names means no CSS-level overrides.** You can't write `.my-button { ... }` to target a Renge component in a stylesheet. Use the `style` prop or wrap the component and override via a parent selector.
+**`Spinner` injects keyframes at module load** via a module-level DOM insertion. This happens once per import, regardless of how many `Spinner` instances are rendered. It is not part of the Renge theme CSS — it lives outside the token system because CSS custom properties cannot animate `transform`.
+**Single provider scope.** `RengeProvider` sets one theme for the entire subtree. If you need different themes in different parts of the tree, nest multiple `RengeProvider` instances — but note that the outermost provider's `injectCSS` behavior will apply globally unless scoped via the `selector` config option.
+**Experimental components have unstable APIs.** `EnergyRing`, `Pulse`, and `FlowField` are included but not covered by the stability guarantee. Their props will likely change before v1.
 ---
 ## Development

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@renge-ui/react",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "React component primitives for the Renge design system.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -12,23 +12,32 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit"
   },
-  "keywords": ["design-system", "react", "components", "golden-ratio"],
+  "keywords": [
+    "design-system",
+    "react",
+    "components",
+    "golden-ratio"
+  ],
   "author": "Vanessa Martin",
   "license": "MIT",
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/vsm1996/renge-ui"
   },
   "packageManager": "pnpm@10.30.2",
   "dependencies": {
-    "@renge-ui/tokens": "workspace:*"
+    "@renge-ui/tokens": "^1.0.3"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",