@yuva-devlab/ui 1.4.3 → 2.0.0

package/README.md

@@ -1,202 +1,246 @@
 # 📦 @yuva-devlab/ui
 
 [![npm version](https://img.shields.io/npm/v/@yuva-devlab/ui.svg)](https://www.npmjs.com/package/@yuva-devlab/ui)
-[![npm downloads](https://img.shields.io/npm/dm/@yuva-devlab/ui.svg)](https://www.npmjs.com/package/@yuva-devlab/ui)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![React 19](https://img.shields.io/badge/React-19.x-61dafb.svg)](https://react.dev)
+[![TypeScript 6](https://img.shields.io/badge/TypeScript-6.x-3178c6.svg)](https://www.typescriptlang.org)
+[![W3C Cascade Layers](https://img.shields.io/badge/CSS-W3C%20Cascade%20Layers-22c55e.svg)](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer)
 
-> A production-ready, fully-typed React component library built with Vanilla
-> Extract, featuring a natural design system and comprehensive accessibility
-> support.
+> Production-ready, fully-typed React component library engineered for the DevLab ecosystem. Built on accessible Radix UI primitives, powered by OKLCH CSS design tokens (`@yuva-devlab/tokens`), and modular W3C Cascade Layers (`@layer dl-*`).
+
+---
+
+## What's New in v2.0.0
+
+- **Pure Platform CSS Architecture**: Completely eliminated Tailwind CSS runtime and utility dependencies from components. Component styling is strictly governed by W3C Cascade Layers (`@layer dl-base, dl-tokens, dl-components, dl-utilities`), eliminating CSS specificity conflicts and removing build-step plugin overhead.
+- **First-Class Typography Primitives**: Added `<Heading>` and `<Text>` primitives with decoupled semantic HTML tags (`as="h1"`..`as="h6"`, `span`, `div`) and visual scales (`size="display" | "h1".."h6"` and `variant="body-lg" | "body" | "body-sm" | "caption" | "code" | "metric"`).
+- **64+ Accessible UI Primitives**: Expanded catalog with Radix UI accessibility compliance and multi-brand responsiveness.
+- **Upgraded Design Tokens Peer**: Upgraded to `@yuva-devlab/tokens@^2.0.0` with isolated brand extensions and native VS Code autocomplete.
+
+---
 
 ## Features
 
-- 🎨 **Natural Design System** - Organic color palettes inspired by Material
-  Design 3
-- 🔒 **Type-Safe** - Full TypeScript support with comprehensive type definitions
-- 🎭 **Zero-Runtime CSS** - Vanilla Extract compiles styles at build time
-- ♿ **Accessible** - Built on Radix UI primitives with ARIA compliance
-- 🧩 **Polymorphic** - Components support `as` prop for semantic flexibility
-- 🎯 **Tree-Shakeable** - Import only what you need
-- 📦 **Monorepo Architecture** - Clean separation of tokens, primitives, and
-  components
+- 🎨 **Multi-Brand Theme Architecture** - Seamless brand isolation across OrchestrAI, VitalAI, FinAI, Logs, and Portal.
+- 📐 **Dynamic Theme-Driven Sizing** - Automatic adaptation across brand densities (compact telemetry logs, precision finance tables, athletic kinetic scaling).
+- ⚡ **Pure Platform CSS** - Scoped W3C Cascade Layers (`@layer dl-components, dl-layout, dl-utilities`) and semantic design tokens.
+- 🔤 **Typography Primitives** - First-class `<Heading>` and `<Text>` primitives with semantic decoupling.
+- 📐 **Layout & Composition Primitives** - First-class `<Box>`, `<Flex>`, `<Stack>`, `<Grid>`, and `<Container>` primitives.
+- ♿ **Accessible by Default** - Built on Radix UI primitives with complete WAI-ARIA and keyboard navigation compliance.
+- 🧩 **64+ Core UI & Layout Primitives** - Buttons, Calendars, DatePickers, Drawers, Sheets, Sidebars, Menus, Modals, EmptyStates, Layouts, and more.
+- 🔒 **End-to-End Type Safety** - First-class TypeScript definitions with full polymorphic `asChild` and `as` composition support.
+- 📦 **Tree-Shakeable ESM & CJS** - Highly optimized builds producing clean dual artifacts.
+
+---
 
 ## Installation
 
 ```bash
+# pnpm (recommended)
+pnpm add @yuva-devlab/ui @yuva-devlab/tokens lucide-react
+
 # npm
-npm install @yuva-devlab/ui
+npm install @yuva-devlab/ui @yuva-devlab/tokens lucide-react
 
 # yarn
-yarn add @yuva-devlab/ui
-
-# pnpm
-pnpm add @yuva-devlab/ui
+yarn add @yuva-devlab/ui @yuva-devlab/tokens lucide-react
 ```
 
 ### Peer Dependencies
 
+Ensure your project has the required peer dependencies installed:
+
 ```bash
-# npm
-npm install react@^19.2.0 react-dom@^19.2.0
+pnpm add react@^19.0.0 react-dom@^19.0.0 sonner@^2.0.0
+```
 
-# yarn
-yarn add react@^19.2.0 react-dom@^19.2.0
+---
 
-# pnpm
-pnpm add react@^19.2.0 react-dom@^19.2.0
+## Quick Start
+
+### 1. Configure Styles
+
+In your application's root stylesheet (e.g. `globals.css` or `app.css`), establish the W3C Cascade Layer order and import your desired tokens and styles:
+
+```css
+/* 1. Establish W3C Cascade Layer hierarchy */
+@layer dl-base, dl-tokens, dl-components, dl-layout, dl-utilities, dl-app;
+
+/* 2. Import design tokens & brand theme */
+@import "@yuva-devlab/tokens/styles.css";
+@import "@yuva-devlab/tokens/themes/finai.css";
+
+/* 3. Import UI components and layout styles */
+@import "@yuva-devlab/ui/styles.css";
 ```
 
-## Quick Start
+> **Tip:** You can import any theme preset from `@yuva-devlab/tokens/themes/*` (`finai`, `vitalai`, `logs`, `orchestrai`, `portal`).
 
-```tsx
-import { Button, Input, Stack, Container } from "@yuva-devlab/ui";
-import "@yuva-devlab/ui/styles.css";
+### 2. Render Components & Typography Primitives
 
-function App() {
+```tsx
+import {
+  Heading,
+  Text,
+  Button,
+  Card,
+  Badge,
+  Stack,
+  Flex,
+} from "@yuva-devlab/ui";
+import { Sparkles } from "lucide-react";
+
+export default function DashboardCard() {
   return (
-    <Container size="lg">
-      <Stack gap="md">
-        <Input label="Email" placeholder="you@example.com" type="email" />
-        <Button variant="primary" size="md">
-          Sign In
+    <Card>
+      <Stack gap={4}>
+        <Flex justify="between" align="center">
+          {/* Decoupled semantic level and visual scale */}
+          <Heading as="h2" size="h3">
+            DevLab Portfolio
+          </Heading>
+          <Badge variant="default">Active</Badge>
+        </Flex>
+
+        <Text variant="caption">Last updated 5m ago</Text>
+        <Text variant="metric">$1,248,390.50</Text>
+
+        <Button variant="primary">
+          <Sparkles />
+          Execute Transaction
         </Button>
       </Stack>
-    </Container>
+    </Card>
   );
 }
 ```
 
-## Available Components
-
-### Form Components
+---
 
-- **Button** - Primary, secondary, tertiary variants with loading states
-- **Input** - Text input with label, error states, and helper text
+## Typography Primitives
 
-### Typography
+### Heading Component
 
-- **Typography** - Polymorphic text component supporting h1-h6, p, span, etc.
+The `<Heading>` primitive decouples semantic HTML structure (`as`) from visual appearance (`size`):
 
-### Layout Components
+```tsx
+import { Heading } from "@yuva-devlab/ui";
 
-- **Box** - Polymorphic container with spacing utilities
-- **Flex** - Flexbox layout with alignment and gap props
-- **Grid** - CSS Grid layout with responsive columns
-- **Stack** - Vertical/horizontal stacking with consistent spacing
-- **Container** - Responsive max-width wrapper (sm, md, lg, xl, 2xl)
+// Semantic H1 rendered with compact H3 visual appearance
+<Heading as="h1" size="h3">Compact Header</Heading>
 
-### Coming Soon
+// Display heading for landing pages
+<Heading as="h1" size="display">DevLab Cloud</Heading>
+```
 
-- Select (Radix UI based)
-- Switch (Radix UI based)
-- Checkbox (Radix UI based)
-- Radio (Radix UI based)
-- InputNumber
+| Prop    | Type                                                                                    | Default      | Description                                              |
+| :------ | :-------------------------------------------------------------------------------------- | :----------- | :------------------------------------------------------- |
+| `as`    | `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"span"` \| `"div"`         | `"h2"`       | The semantic HTML element rendered to the DOM.           |
+| `size`  | `"display"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"`                 | Matches `as` | The visual typographic scale applied via Cascade Layers. |
+| `color` | `"default"` \| `"muted"` \| `"primary"` \| `"accent"` \| `"destructive"` \| `"success"` | `"default"`  | Semantic text color token.                               |
 
-## Component Examples
+### Text Component
 
-### Button
+The `<Text>` primitive handles body text, captions, inline code, and tabular metric numerals:
 
 ```tsx
-import { Button } from "@yuva-devlab/ui";
+import { Text } from "@yuva-devlab/ui";
+
+<Text variant="body-lg">Large intro body copy</Text>
+<Text variant="body">Standard UI body text</Text>
+<Text variant="body-sm">Small helper description</Text>
+<Text variant="caption">Footnotes and timestamps</Text>
+<Text variant="code">const token = useToken();</Text>
+<Text variant="metric">3,492 req/s</Text>
+```
 
-// Variants
-<Button variant="primary">Primary Action</Button>
-<Button variant="secondary">Secondary Action</Button>
-<Button variant="tertiary">Tertiary Action</Button>
+---
 
-// Sizes
-<Button size="sm">Small</Button>
-<Button size="md">Medium</Button>
-<Button size="lg">Large</Button>
+## Multi-Brand Theming
 
-// States
-<Button loading>Loading...</Button>
-<Button disabled>Disabled</Button>
+DevLab UI supports multi-brand switching at runtime using `data-brand` and `data-theme` HTML attributes:
 
-// Polymorphic
-<Button as="a" href="/home">Link Button</Button>
+```html
+<!-- Switch to FinAI Spacious Theme with Dark Mode -->
+<html data-brand="finai" class="dark">
+  ...
+</html>
 ```
 
-### Layout System
+### Supported Brand Themes
 
-```tsx
-import { Container, Stack, Flex, Box } from "@yuva-devlab/ui";
-
-<Container size="xl">
-  <Stack gap="lg">
-    <Flex align="center" justify="between">
-      <Box p="md">Logo</Box>
-      <Box>Navigation</Box>
-    </Flex>
-
-    <Grid cols={{ base: 1, md: 2, lg: 3 }} gap="md">
-      <Box p="lg">Card 1</Box>
-      <Box p="lg">Card 2</Box>
-      <Box p="lg">Card 3</Box>
-    </Grid>
-  </Stack>
-</Container>;
-```
+| Brand Key    | Theme Name        | Primary Aesthetic         | Token Import                                |
+| :----------- | :---------------- | :------------------------ | :------------------------------------------ |
+| `finai`      | **FinAI**         | High-Finance Emerald      | `@yuva-devlab/tokens/themes/finai.css`      |
+| `vitalai`    | **VitalAI**       | Athletic Volt Kinetic     | `@yuva-devlab/tokens/themes/vitalai.css`    |
+| `logs`       | **DevLab Logs**   | High-Density Matrix Amber | `@yuva-devlab/tokens/themes/logs.css`       |
+| `orchestrai` | **OrchestrAI**    | Midnight Neon Violet      | `@yuva-devlab/tokens/themes/orchestrai.css` |
+| `portal`     | **DevLab Portal** | Enterprise Modern Indigo  | `@yuva-devlab/tokens/themes/portal.css`     |
 
-## Styling & Brand Theming
+---
 
-### 1. Global Styles Setup
+## Component Catalog (64 Components)
 
-Import the UI stylesheet in your root layout:
+### Typography Primitives
 
-```tsx
-import "@yuva-devlab/ui/styles.css";
-```
+- **Heading** - Semantic heading with decoupled visual scale (`display`, `h1`..`h6`).
+- **Text** - Multi-variant typography primitive (`body-lg`, `body`, `body-sm`, `caption`, `code`, `metric`).
 
-Or import specific brand themes directly:
+### Layout & Composition Primitives
 
-```css
-@import "@yuva-devlab/ui/styles.css";
-@import "@yuva-devlab/ui/themes/finai.css";
-```
+- **Box** - Fundamental container with padding, border, radius, shadow, and surface backgrounds.
+- **Flex** - 1D flexbox container (`direction`, `justify`, `align`, `wrap`, `gap`, `inline`).
+- **Stack** - Vertical or horizontal layout flow with token-governed spacing.
+- **Grid** - Responsive 2D grid (`cols`, `gap`, minItemWidth auto-fit).
+- **Container** - Responsive centered layout container with max-width boundaries (`sm` to `2xl`).
+- **AspectRatio**, **Panel**, **Resizable**, **ScrollArea**, **Separator**
 
-### 2. Brand & Theme Provider (`ConfigProvider`)
+### General & Display
 
-Wrap your application with `ConfigProvider` (or `ThemeProvider`) and pass your `brand`:
+- **Button**, **CopyButton**, **Card**, **MetricCard**, **SecretRevealCard**, **Badge**, **StatusBadge**, **StatusChip**, **Skeleton**, **LoadingState**, **EmptyState**
 
-```tsx
-import { ConfigProvider } from "@yuva-devlab/ui";
+### Form & Data Entry
 
-export function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <ConfigProvider brand="finai" defaultTheme="system">
-      {children}
-    </ConfigProvider>
-  );
-}
-```
+- **Input**, **Textarea**, **Checkbox**, **Switch**, **Slider**, **RadioGroup**, **Select**, **SearchableSelect**, **DatePicker**, **Calendar**, **InputOTP**, **Toggle**, **ToggleGroup**, **Form**
 
-The provider sets the appropriate `data-brand` and `data-theme` attributes on `<html>`, instantly activating the scoped design tokens for that brand without loading or exposing styles of other brands!
+### Navigation
 
----
+- **Sidebar**, **NavigationMenu**, **Menubar**, **Breadcrumb**, **Tabs**, **Pagination**
 
-## Development
+### Overlays & Dialogs
 
-```bash
-# Install dependencies
-pnpm install
+- **Dialog**, **AlertDialog**, **ConfirmDialog**, **Drawer**, **Sheet**, **Popover**, **Tooltip**, **HoverCard**, **DropdownMenu**, **ContextMenu**
+
+### Feedback & Display
 
-# Build the library
-pnpm --filter @yuva-devlab/ui build
+- **Alert**, **Progress**, **Toaster** (Sonner integration), **Avatar**, **Table**, **Accordion**, **Collapsible**, **Carousel**, **Chart**, **Command**
 
-# Run tests
-pnpm --filter @yuva-devlab/ui test
+---
+
+## TypeScript & Polymorphic Support
 
-# Type check
-pnpm --filter @yuva-devlab/ui typecheck
+All components export full TypeScript definitions and support polymorphic composition via the `asChild` prop:
+
+```tsx
+import Link from "next/link";
+import { Button } from "@yuva-devlab/ui";
+
+<Button asChild variant="secondary">
+  <Link href="/dashboard">Navigate to Dashboard</Link>
+</Button>;
 ```
 
-## Documentation
+---
+
+## Documentation & Live Previews
 
-- **Storybook**: Run `pnpm dev:docs` to view interactive component documentation
-- **Playground**: Run `pnpm dev:playground` to test components in a live
+Explore the interactive component playground, live documentation, and API references at:
+
+- **Documentation**: [https://github.com/yuvadevlab/devlab-shared](https://github.com/yuvadevlab/devlab-shared)
+- **Repository**: [https://github.com/yuvadevlab/devlab-shared](https://github.com/yuvadevlab/devlab-shared)
+
+---
 
 ## License
 
-MIT © Yuva Devlab
+MIT © [Yuva DevLab](https://github.com/yuvadevlab)

package/dist/components/accordion/accordion.mdx

@@ -0,0 +1,18 @@
+import { Meta, Title, Description, Canvas, Controls } from "@storybook/blocks";
+import * as AccordionStories from "./accordion.stories";
+
+<Meta of={AccordionStories} />
+
+<Title />
+
+# Accordion
+
+Vertically stacked set of interactive headings that each reveal a section of content.
+
+## Default
+
+<Canvas of={AccordionStories.Default} />
+
+## Component Properties
+
+<Controls />

package/dist/components/alert/alert.css

@@ -1,9 +1,9 @@
 .dl-alert {
   position: relative;
   width: 100%;
-  border-radius: var(--radius-lg, 0.5rem);
+  border-radius: var(--radius, 0.5rem);
   border: 1px solid var(--border);
-  padding: 0.875rem 1rem;
+  padding: var(--space-4, 0.875rem) var(--space-5, 1rem);
   font-size: 0.875rem;
   display: grid;
   grid-template-columns: 1fr;

package/dist/components/alert-dialog/alert-dialog.mdx

@@ -0,0 +1,18 @@
+import { Meta, Title, Description, Canvas, Controls } from "@storybook/blocks";
+import * as AlertDialogStories from "./alert-dialog.stories";
+
+<Meta of={AlertDialogStories} />
+
+<Title />
+
+# Alert Dialog
+
+Modal dialog that interrupts the user with important content and expects a confirmation or cancellation action.
+
+## Default
+
+<Canvas of={AlertDialogStories.Default} />
+
+## Component Properties
+
+<Controls />

package/dist/components/aspect-ratio/aspect-ratio.mdx

@@ -0,0 +1,22 @@
+import { Meta, Title, Description, Canvas, Controls } from "@storybook/blocks";
+import * as AspectRatioStories from "./aspect-ratio.stories";
+
+<Meta of={AspectRatioStories} />
+
+<Title />
+
+# Aspect Ratio
+
+Displays content within a desired ratio, preventing layout shifts during asset loading.
+
+## Default (16:9)
+
+<Canvas of={AspectRatioStories.Default} />
+
+## Square (1:1)
+
+<Canvas of={AspectRatioStories.Square} />
+
+## Component Properties
+
+<Controls />

package/dist/components/breadcrumb/breadcrumb.mdx

@@ -0,0 +1,18 @@
+import { Meta, Title, Description, Canvas, Controls } from "@storybook/blocks";
+import * as BreadcrumbStories from "./breadcrumb.stories";
+
+<Meta of={BreadcrumbStories} />
+
+<Title />
+
+# Breadcrumb
+
+Hierarchical navigation trail indicating the current page location within a navigational hierarchy.
+
+## Default
+
+<Canvas of={BreadcrumbStories.Default} />
+
+## Component Properties
+
+<Controls />

package/dist/components/calendar/calendar-nav.css

@@ -0,0 +1,111 @@
+.dl-calendar .rdp-month_caption,
+.dl-calendar .dl-calendar__month-caption {
+  position: relative;
+  display: flex;
+  height: var(--cell-size, 2rem);
+  width: 100%;
+  align-items: center;
+  justify-content: center;
+  padding: 0 var(--cell-size, 2rem);
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: var(--foreground);
+  box-sizing: border-box;
+}
+
+.dl-calendar .rdp-caption_label,
+.dl-calendar .dl-calendar__caption-label {
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: var(--foreground);
+  line-height: 1;
+  user-select: none;
+}
+
+.dl-calendar .dl-calendar__caption-label--interactive {
+  display: flex;
+  height: var(--control-height-sm, 2rem);
+  align-items: center;
+  gap: 0.25rem;
+  border-radius: var(--radius-md, 0.375rem);
+  padding-inline: 0.5rem 0.25rem;
+}
+
+.dl-calendar .dl-calendar__dropdowns {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  justify-content: center;
+  gap: 0.375rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+}
+
+.dl-calendar .dl-calendar__dropdown-root {
+  position: relative;
+  border-radius: var(--radius-md, 0.375rem);
+  border: 1px solid var(--border);
+  box-shadow: var(--shadow-xs, 0 1px 2px 0 rgb(0 0 0 / 0.05));
+}
+
+.dl-calendar .dl-calendar__dropdown {
+  position: absolute;
+  inset: 0;
+  opacity: 0;
+  background: var(--popover);
+  cursor: pointer;
+}
+
+.dl-calendar .rdp-nav,
+.dl-calendar .dl-calendar__nav {
+  position: absolute;
+  top: 0;
+  inset-inline: 0;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  height: var(--cell-size, 2rem);
+  pointer-events: none;
+}
+
+.dl-calendar .rdp-button_previous,
+.dl-calendar .rdp-button_next,
+.dl-calendar .dl-calendar__nav-button {
+  pointer-events: auto;
+  width: var(--cell-size, 2rem) !important;
+  height: var(--cell-size, 2rem) !important;
+  min-width: var(--cell-size, 2rem) !important;
+  padding: 0 !important;
+  display: inline-flex !important;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-md, 0.375rem) !important;
+  border: 1px solid var(--border);
+  background: var(--background);
+  color: var(--muted-foreground);
+  cursor: pointer;
+  user-select: none;
+  transition: all 0.15s ease;
+}
+
+.dl-calendar .rdp-button_previous:hover,
+.dl-calendar .rdp-button_next:hover,
+.dl-calendar .dl-calendar__nav-button:hover {
+  background-color: var(--accent);
+  color: var(--accent-foreground);
+}
+
+.dl-calendar .rdp-button_previous[aria-disabled="true"],
+.dl-calendar .rdp-button_next[aria-disabled="true"] {
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+.dl-calendar .rdp-button_previous svg,
+.dl-calendar .rdp-button_next svg,
+.dl-calendar .dl-calendar__chevron {
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
+}