@vaneui/ui 0.2.1-alpha.20250813194307.2bb87da → 0.2.1-alpha.20250820170702.e0272da

package/README.md

@@ -2,11 +2,65 @@
 
 [![npm version](https://img.shields.io/npm/v/%40vaneui/ui.svg?style=flat)](https://www.npmjs.com/package/%40vaneui/ui)
 
-VaneUI is a React + TypeScript component library powered by Tailwind CSS. It uses a boolean-prop API for variants (size, appearance, shape, layout, typography, etc.) and a flexible theme system so you can set defaults, add extra classes, or programmatically override styles.
+VaneUI helps you build beautiful, consistent UIs faster by turning common design decisions into expressive, readable boolean props. Instead of memorizing property names and values, you compose intent: `primary`, `lg`, `outline`, `rounded`. The result is cleaner code, fewer decisions per component, and a smoother path from wireframe to production.
 
-- Boolean prop API: <Button primary lg pill> instead of stringly typed props
-- ThemeProvider with defaults (themeDefaults), extra classes (extraClasses), and programmatic override (themeOverride)
-- Built CSS you can import directly (no Tailwind setup required to consume)
+## How VaneUI works
+
+At its core, VaneUI maps boolean props to thoughtfully curated CSS classes. You write the JSX using booleans like this:
+
+```tsx
+<Button primary lg pill filled>
+  Get started
+</Button>
+```
+The component resolves those booleans to semantic styles:
+- `primary` → semantic color token
+- `lg` → size scale for paddings, border radius, typography size
+- `pill` → shape preset
+- `filled` → variant preset
+
+Tailwind classes and CSS variables power the final styles:
+- Tailwind utilities for performance and composability
+- CSS variables for theming and per-app overrides
+- Each CSS class can be changed using ThemeProvider
+- Each component has a customizable set of default values for boolean props
+
+You can always mix in your own Tailwind classes via className to fine‑tune any edge case:
+```tsx
+<Button primary lg pill filled className="hover:opacity-80">
+  Get started
+</Button>
+```
+
+## Traditional approach vs VaneUI
+
+Instead of writing verbose prop configurations, VaneUI uses intuitive boolean props that make your code cleaner and more readable:
+
+```tsx
+// Traditional approach
+<Button appearance="primary" size="lg" variant="filled" />
+
+// VaneUI approach  
+<Button primary lg filled />
+```
+
+## Prop combinations
+
+Boolean props can be combined naturally to create the exact styling you need:
+
+```tsx
+<Button primary lg pill shadow>
+  Large primary pill button with shadow
+</Button>
+
+<Card secondary padding border rounded>
+  Secondary card with padding, border and rounded corners
+</Card>
+
+<Stack column itemsCenter>
+  Vertical stack with gap and centered items
+</Stack>
+```
 
 ## Installation
 
@@ -53,6 +107,67 @@ export default function App() {
 }
 ```
 
+## Every Class is Customizable
+
+Behind each boolean prop are carefully crafted CSS classes that you can completely override.
+
+### CSS Variables
+
+You can customize the VaneUI by overriding the CSS variables:
+
+```css
+:root {
+  --text-color-primary: #8b5cf6;      /* Primary text color */
+  --ui-border-radius-md: 1rem;        /* Medium UI radius */
+}
+```
+
+### Tailwind Overrides
+
+Each component can be changed by using the regular Tailwind CSS classes:
+
+```tsx
+<Button primary className="bg-purple-600 hover:bg-purple-700">
+  Custom Primary
+</Button>
+```
+
+### Theme Overrides
+
+You can set up default values of all boolean props by providing `themeDefaults` in ThemeProvider:
+
+```tsx
+const defaults: ThemeDefaults = {
+  button: {
+    pill: true,
+    lg: true,
+  },
+};
+
+return (
+  <ThemeProvider themeDefaults={defaults}>
+    <Button>This button is large and pill-shaped</Button>
+  </ThemeProvider>
+);
+```
+
+You can change default CSS classes of all components by providing `themeOverride` in ThemeProvider:
+
+```tsx
+const overrideFunc = (theme: ThemeProps) => {
+  theme.button.themes.appearance.text.outline.default.base = 'text-blue-200';
+  theme.button.themes.appearance.text.outline.default.hover = 'hover:text-blue-700';
+  theme.button.themes.appearance.text.outline.default.active = 'active:text-blue-900';
+  return theme;
+};
+
+return (
+  <ThemeProvider themeOverride={overrideFunc}>
+    <Button>This button has blue colors</Button>
+  </ThemeProvider>
+);
+```
+
 ## Theming
 
 All components work out of the box with defaults. For deeper customization, wrap your app with ThemeProvider.
@@ -91,12 +206,12 @@ export function App() {
 ## Boolean Props Model
 
 Each component exposes optional boolean props generated from category keys. Common examples:
-- Size: xs, sm, md, lg, xl
-- Appearance: default, primary, secondary, tertiary, accent, success, danger, warning, info, transparent
-- Variant: filled, outline
-- Shape: pill, rounded, sharp
-- Typography: sans, serif, mono, thin…black, italic/notItalic, underline/lineThrough/overline, uppercase/lowercase/capitalize
-- Layout: gap/noGap, inline/block/flex/grid, justify*, items*, padding/noPadding, shadow/noShadow, ring/noRing
+- Size: `xs`, `sm`, `md`, `lg`, `xl`
+- Appearance: `default`, `primary`, `secondary`, `tertiary`, `accent`, `success`, `danger`, `warning`, `info`, `transparent`
+- Variant: `filled`, `outline`
+- Shape: `pill`, `rounded`, `sharp`
+- Typography: `sans`, `serif`, `mono`, `thin`…`black`, `italic`/`notItalic`, `underline`/`lineThrough`/`overline`, `uppercase`/`lowercase`/`capitalize`
+- Layout: `gap`/`noGap`, `inline`/`block`/`flex`/`grid`, `justify*`, `items*`, `padding`/`noPadding`, `shadow`/`noShadow`, `ring`/`noRing`
 
 Only the categories relevant to a component are used. The theme maps these booleans to Tailwind utility classes.
 

package/dist/components/ui/theme/appearance/genericVariantTheme.d.ts

@@ -10,6 +10,7 @@ export declare class GenericVariantTheme<T extends BaseTheme> extends BaseTheme
     getClasses(extractedKeys: CategoryProps): string[];
     static createUIElementTextTheme(): GenericVariantTheme<AppearanceTheme>;
     static createUIElementShadowTheme(): GenericVariantTheme<ShadowAppearanceTheme>;
+    static createLayoutShadowTheme(): GenericVariantTheme<ShadowAppearanceTheme>;
     static createBorderAppearanceTheme(): GenericVariantTheme<AppearanceTheme>;
     static createUIElementBorderTheme(): GenericVariantTheme<AppearanceTheme>;
     static createUIElementRingTheme(): GenericVariantTheme<AppearanceTheme>;

package/dist/components/ui/theme/appearance/shadowAppearanceTheme.d.ts

@@ -5,7 +5,9 @@ export interface ShadowAppearanceTheme extends Record<AppearanceKey, Record<Size
 }
 export declare class ShadowAppearanceTheme extends BaseTheme {
     private static readonly defaultShadow;
+    private static readonly layoutShadow;
     constructor(initial?: Partial<Record<AppearanceKey, Record<SizeKey, Record<ModeKey, string>> | null>>);
     getClasses(extractedKeys: CategoryProps): string[];
     static createTheme(src?: Partial<Record<AppearanceKey, Record<SizeKey, Record<ModeKey, string>> | null>>): ShadowAppearanceTheme;
+    static createLayoutTheme(src?: Partial<Record<AppearanceKey, Record<SizeKey, Record<ModeKey, string>> | null>>): ShadowAppearanceTheme;
 }

package/dist/components/ui/theme/common/ComponentTheme.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { BaseTheme } from "./baseTheme";
-import type { ComponentCategoryKey } from "../../props";
+import { ComponentCategoryKey } from "../../props";
 import { HideTheme } from "../layout/hideTheme";
 import { ItemsTheme } from "../layout/itemsTheme";
 import { JustifyTheme } from "../layout/justifyTheme";
@@ -52,7 +52,7 @@ export declare class ComponentTheme<P extends ComponentProps, TTheme extends obj
     readonly base: string;
     readonly themes: TTheme;
     defaults: Partial<P>;
-    extraClasses: Record<string, string>;
+    extraClasses: Partial<Record<keyof P, string>>;
     private readonly categories;
     private readonly tagFunction?;
     constructor(tag: React.ElementType, base: string, themes: DeepPartial<TTheme>, defaults: Partial<P> | undefined, categories: readonly ComponentCategoryKey[], tagFunction?: (props: P, defaults: Partial<P>) => React.ElementType);

package/dist/components/ui/theme/defaults.d.ts

@@ -0,0 +1,5 @@
+import { ThemeDefaults } from '../../themeContext';
+/**
+ * Default props for all components using the existing ThemeDefaults type
+ */
+export declare const themeDefaults: ThemeDefaults;

package/dist/index.d.ts

@@ -10,4 +10,5 @@ export { Section, Container, Col, Row, Stack, Grid2, Grid3, Grid4, Card } from "
 export { Text, Title, Link, List, ListItem, SectionTitle, PageTitle } from "./components/ui/typography";
 export { COMPONENT, ComponentKeys, ComponentCategories, type ComponentKey, } from "./components/ui/props/keys";
 export { ThemeProvider, useTheme, defaultTheme, type ThemeProps, type ThemeDefaults, type ThemeExtraClasses, type ThemeProviderProps, type PartialTheme, } from './components/themeContext';
+export { themeDefaults } from './components/ui/theme/defaults';
 export * from "./components/ui/props/index";