@reinvented/design 0.4.0 → 1.1.0

package/skills/blocks/data-viz.md

@@ -0,0 +1,92 @@
+# Data Visualization Blocks
+
+This document covers composite UI blocks designed for Metric Cards, KPIs, and Financial Tickers.
+
+## When to use Blocks vs Primitives
+
+Use these blocks whenever the user needs a dashboard-like view of numbers, metrics, or live data feeds. DO NOT build KPI cards manually using raw `<Card>` or `<p>` elements. These data-viz blocks handle responsive column reflowing and strict trend color mapping (e.g., green for positive, red for negative).
+
+## 1. KpiCard
+
+The `KpiCard` block is the fundamental building block of any dashboard.
+
+### Anatomy
+```tsx
+// React Component
+import { Users, DollarSign, Activity } from 'lucide-react'
+import { KpiCard, StatGrid } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <StatGrid :columns="3">
+    <KpiCard 
+      title="Total Revenue" 
+      metric="$45,231.89" 
+      :trend="20.1" 
+      trendLabel="from last month"
+      :icon="DollarSign" 
+    />
+    <KpiCard 
+      title="Active Users" 
+      metric="+2350" 
+      :trend="180.1" 
+      trendLabel="from last month"
+      :icon="Users" 
+    />
+    <KpiCard 
+      title="Server Load" 
+      metric="84%" 
+      :trend="-4.3" 
+      trendLabel="from last hour"
+      :icon="Activity" 
+    />
+  </StatGrid>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `metric` is the massive string (e.g., "$12,000", "42%"). Do NOT pass numbers here; format the string first.
+- `trend` expects a Number (e.g., `20.5`, `-4.2`, `0`). The card automatically mounts a `TrendingUp` or `TrendingDown` icon and applies `text-emerald-500` or `text-rose-500` accordingly.
+- `icon` is a raw Vue component import (typically from `lucide-react`).
+
+## 2. StatGrid
+
+The `StatGrid` block intelligently mounts KPI cards in a responsive CSS Grid.
+
+### Anatomy
+*(See KpiCard anatomy for typical usage)*
+
+### Usage Rules
+- Takes an optional `columns` prop (`2`, `3`, or `4`). Defaults to `3`.
+- Automatically responds to mobile by stacking into a single column.
+
+## 3. FinancialTicker
+
+The `FinancialTicker` block models a live-data feed typically seen in trading, crypto, or forex interfaces.
+
+### Anatomy
+```tsx
+// React Component
+import { FinancialTicker } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <div className="flex items-center gap-6 overflow-x-auto whitespace-nowrap p-4 border bg-background/50 rounded-xl">
+    <FinancialTicker symbol="AAPL" price="$174.22" :change="1.45" :changePercent="0.84" />
+    <FinancialTicker symbol="MSFT" price="$412.01" :change="-3.12" :changePercent="-0.75" />
+    <FinancialTicker symbol="NVDA" price="$892.50" :change="42.10" :changePercent="4.95" />
+  </div>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- It automatically handles the `<TrendingUp/Down>` colors on both the text and the micro-badge based on whether `change` is positive or negative.
+- Wrapping the tickers in a scrolling flex container is recommended.

package/skills/blocks/ecommerce.md

@@ -0,0 +1,126 @@
+# E-Commerce & Catalog Blocks
+
+This document covers composite UI blocks designed for Product Catalogs, Marketplaces, and SaaS Pricing grids.
+
+## When to use Blocks vs Primitives
+
+Use these blocks whenever the app requires displaying products, selling software tiers, or aggregating user review scores. DO NOT build these specific data structures from scratch (e.g. manually aligning stars or creating pricing card borders). These blocks provide structural layout and state interactions.
+
+## 1. ProductCard
+
+The `ProductCard` block is highly versatile for grid-based inventory displays. It automatically handles hover transforms and image aspect ratios.
+
+### Anatomy
+```tsx
+// React Component
+import { Button } from '@reinvented/design'
+import { Badge } from '@reinvented/design'
+import { Plus } from 'lucide-react'
+import { 
+  ProductCard, 
+  ProductCardImage, 
+  ProductCardContent, 
+  ProductCardPrice 
+} from '@reinvented/design'
+import { RatingStars } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <ProductCard className="w-[300px]">
+    <ProductCardImage src="/products/headphones.jpg" alt="Wireless Headphones">
+      <Badge className="absolute top-3 right-3 bg-red-500">Sale -20%</Badge>
+    </ProductCardImage>
+    
+    <ProductCardContent>
+      <div className="flex justify-between items-start">
+        <div>
+          <h3 className="font-bold text-lg leading-tight">Pro Audio Max</h3>
+          <p className="text-sm text-muted-foreground mt-1">Over-ear active noise cancelling</p>
+        </div>
+      </div>
+      
+      <div className="mt-2 flex items-center gap-2">
+        <RatingStars :rating="4.5" />
+        <span className="text-xs text-muted-foreground">(128)</span>
+      </div>
+      
+      <div className="mt-4 flex items-end justify-between">
+        <ProductCardPrice price="$199.00" originalPrice="$249.00" />
+        <Button size="icon" className="h-8 w-8 rounded-full">
+          <Plus className="h-4 w-4" />
+        </Button>
+      </div>
+    </ProductCardContent>
+  </ProductCard>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- The outer `ProductCard` wraps a standard Shadcn `Card`.
+- `ProductCardImage` forces a standard `4/3` aspect ratio, handling crop and scale-on-hover logic. It accepts slots (for absolute badges/buttons).
+- Build the inner grid using Flexbox classes within `ProductCardContent`.
+
+## 2. PricingTier
+
+The `PricingTier` block models a classic SaaS or tier-based billing card. It includes built-in highlight mechanics for "Most Popular" selections.
+
+### Anatomy
+```tsx
+// React Component
+import { Button } from '@reinvented/design'
+import { 
+  PricingTier, 
+  PricingHeader, 
+  PricingFeatureList 
+} from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <div className="grid md:grid-cols-3 gap-8 max-w-5xl mx-auto py-8">
+    <!-- Standard Tier -->
+    <PricingTier>
+      <PricingHeader 
+        title="Starter" 
+        description="For small hobby teams"
+        price="$15" 
+        period="/mo"
+      />
+      <PricingFeatureList :features="['Up to 3 users', 'Basic analytics', '24hr Support response']">
+        <Button variant="outline" className="w-full mt-6">Get Started</Button>
+      </PricingFeatureList>
+    </PricingTier>
+
+    <!-- Featured Tier -->
+    <PricingTier featured>
+      <PricingHeader 
+        title="Professional" 
+        description="Everything you need to scale"
+        price="$49" 
+        period="/mo"
+      />
+      <PricingFeatureList :features="['Unlimited users', 'Advanced analytics', '1hr Support response', 'Custom domain']">
+        <Button className="w-full mt-6">Start Free Trial</Button>
+      </PricingFeatureList>
+    </PricingTier>
+  </div>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `PricingTier` cards should be placed side-by-side in a responsive Grid.
+- To emphasize a specific tier (usually the middle option), simply attach the Boolean `featured` prop to `<PricingTier>`. It will automatically add a primary border, a top "Most Popular" badge, and scale it up slightly via z-index.
+- Place a CTA `<Button>` inside the `PricingFeatureList` slot; it will append below the checked rows.
+
+## 3. RatingSummary
+
+The `RatingStars` component handles iterative star loop rendering with half-star parsing based on a numeric average.
+- It takes a `rating` (Number) and an optional `max` (Number, default 5).
+- It handles rendering visually accurate Lucide star shapes internally without manual `v-for` boilerplate.

package/skills/blocks/feedback.md

@@ -0,0 +1,97 @@
+# Feedback & Status Blocks
+
+This document covers composite UI blocks designed for Error Boundaries, Empty States, and 404 screens.
+
+## When to use Blocks vs Primitives
+
+Use these blocks anytime dynamic data fails to load or no data exists yet. DO NOT render blank screens or generic `<div>No data</div>` text. These blocks apply the design system's standardized alerting colors and fallback illustrations to keep the user oriented.
+
+## 1. EmptyState
+
+The `EmptyState` block provides a unified placeholder whenever a list, table, or grid has zero items to display.
+
+### Anatomy
+```tsx
+// React Component
+import { EmptyState } from '@reinvented/design'
+import { FolderOpen } from 'lucide-react'
+
+
+export default function Component() {
+  return (
+    <>
+  <EmptyState 
+    title="No projects found"
+    description="Get started by creating a new project to organize your team's work."
+    :icon="FolderOpen"
+    actionLabel="Create Project"
+    @action="openCreateModal"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Natively bound within a dashed border layout (`border-dashed bg-muted/20`) to visually communicate "placeholder".
+- The `actionLabel` will automatically render a primary `<Button>` centered at the bottom, emitting an `@action` event when clicked. Leave `actionLabel` undefined to render a read-only empty state.
+- `icon` accepts a raw Vue component import (typically from `lucide-react`).
+
+## 2. ErrorState
+
+The `ErrorState` block provides a visually defensive error boundary layout.
+
+### Anatomy
+```tsx
+// React Component
+import { ErrorState } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <ErrorState 
+    title="Failed to load metrics"
+    description="The analytics backend is currently unreachable. Our team has been notified."
+    retryLabel="Refresh Data"
+    @retry="fetchMetrics"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Natively forces the background, borders, and icon ring into `rose-500` shades. The icon is permanently locked to `<AlertTriangle>`.
+- Emits a `@retry` event intended fully to hook into async reloading functions.
+
+## 3. NotFoundState
+
+A massive structural page intended for explicit 404 views.
+
+### Anatomy
+```tsx
+// React Component
+import { NotFoundState } from '@reinvented/design'
+import { useRouter } from 'react-router-dom'
+
+const router = useRouter()
+
+
+export default function Component() {
+  return (
+    <>
+  <NotFoundState 
+    title="Page not found"
+    description="The workspace or document you are trying to view does not exist or you lack permissions."
+    @back="router.back()"
+    @home="router.push('/')"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- This block is designed to take over the entire content area of a layout. It features a massive `404` background typography watermark layered elegantly behind a Search icon.
+- It forces two standard button events: `@back` and `@home`. This provides optimal wayfinding for stranded users without forcing the developer to rebuild standard routing logic.

package/skills/blocks/filtering.md

@@ -0,0 +1,127 @@
+# Filtering & Search Blocks
+
+This document covers composite UI blocks designed for Advanced Search Bars, Faceted Filtering, and iterating Search Results.
+
+## When to use Blocks vs Primitives
+
+Use these blocks anytime the app requires complex querying, e-commerce catalog filtering, or dense search results. DO NOT build heavy filtering sidebars using raw `<Accordion>` and raw `<ScrollArea>` components independently. These blocks resolve fixed heights and desktop/mobile splitting.
+
+## 1. FilterBar
+
+The `FilterBar` establishes the core horizontal header for a search experience.
+
+### Anatomy
+```tsx
+// React Component
+import { FilterBar } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <FilterBar 
+    placeholder="Search repositories..."
+    :activeFilters="[
+      { key: 'lang', label: 'Language: TypeScript' },
+      { key: 'status', label: 'Status: Public' }
+    ]"
+    :resultsCount="42"
+    @removeFilter="(f) => handleRemove(f)"
+    @clearFilters="clearAll"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Composes a `<Search>` prepended `<Input>` along with a flexible appended `#controls` slot for mounting "Filter" buttons.
+- Iterates `activeFilters` as interactive tags natively containing `<X>` dismiss icons. Emits `@removeFilter` passing back the exact object clicked.
+- Displays a `resultsCount` subtle label on the bottom-left if provided.
+
+## 2. FacetedSidebar
+
+The `FacetedSidebar` is a vertical panel layout designed to stick to the left-hand side of desktop layouts (and often placed in a Drawer on mobile).
+
+### Anatomy
+```tsx
+// React Component
+import { FacetedSidebar, FacetedGroup } from '@reinvented/design'
+import { Checkbox } from '@reinvented/design'
+import { Label } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <FacetedSidebar title="Filters">
+    <FacetedGroup title="Category" defaultExpanded>
+      <div className="flex items-center space-x-2">
+        <Checkbox id="cat-design" />
+        <Label for="cat-design">Design Systems</Label>
+      </div>
+      <div className="flex items-center space-x-2">
+        <Checkbox id="cat-web" />
+        <Label for="cat-web">Web Development</Label>
+      </div>
+    </FacetedGroup>
+    
+    <FacetedGroup title="Status">
+      <div className="flex items-center space-x-2">
+        <Checkbox id="st-active" />
+        <Label for="st-active">Active</Label>
+      </div>
+    </FacetedGroup>
+  </FacetedSidebar>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Natively locks `w-full md:w-64` and utilizes a `<ScrollArea>` so the container does not infinitely push the footer down the page as filters expand.
+- Uses `FacetedGroup` internally which binds native Shadcn `<Collapsible>` components, creating smooth, staggered dropdown groupings.
+
+## 3. SearchResultItem
+
+The `SearchResultItem` block creates perfectly aligned horizontal list cards optimized for scanning queries.
+
+### Anatomy
+```tsx
+// React Component
+import { SearchResultItem } from '@reinvented/design'
+import { Star, GitCommit } from 'lucide-react'
+
+
+export default function Component() {
+  return (
+    <>
+  <SearchResultItem 
+    title="reinvented/design-system"
+    subtitle="Updated 2 days ago"
+    description="The core Vue implementation of the Reinvented UI capabilities perfectly layered over Shadcn components."
+    tag="Public"
+    url="/repo/ri-design"
+    image="/repo-cover.png"
+  >
+    <template #meta>
+      <div className="flex items-center gap-1">
+        <Star className="h-3 w-3" /> 1.2k
+      </div>
+      <div className="flex items-center gap-1">
+        <GitCommit className="h-3 w-3" /> 452 Commits
+      </div>
+        </>
+  )
+}
+  </SearchResultItem>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Wraps the `title` natively in an `<a>` tag pointing to `url`.
+- Uses defensive CSS (`line-clamp-2 md:line-clamp-3`) on the description so extreme string lengths do not randomly snap layouts.
+- Replaces the `<Avatar>` norm with a distinct `<image>` square thumbnail representing posts, products, or apps.
+- Features a flexible `#meta` slot at the bottom specifically tuned for micro-stats (stars, forks, dates, views) using small text.

package/skills/blocks/marketing.md

@@ -0,0 +1,136 @@
+# Marketing & Landing Blocks
+
+This document covers composite UI blocks designed for Public Websites, Landing Pages, and Conversion Funnels.
+
+## When to use Blocks vs Primitives
+
+Use these blocks anytime the simulated app requires an unauthenticated, public-facing view meant to drive sign-ups. DO NOT build marketing layouts using raw cards or padding grids. Marketing requires immense vertical rhythm, massive typography, and specific semantic HTML structures (`<section>`, `<article>`) which these blocks provide out-of-the-box.
+
+## 1. HeroSection
+
+The `HeroSection` powers the massive header that users see immediately upon visiting a landing page.
+
+### Anatomy
+```tsx
+// React Component
+import { HeroSection } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <HeroSection 
+    badge="New Version 2.0"
+    title="Build better AI agents, faster than ever."
+    description="The complete design system tailored for autonomous LLM coding and generative UI workflows."
+    primaryAction="Start Building For Free"
+    secondaryAction="Read The Documentation"
+    image="/hero-dashboard.webp"
+    @primary="handleSignup"
+    @secondary="handleDocs"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Integrates a built-in abstract background aesthetic using a subtle dot-matrix grid and a blurred `primary` radial glow out of the box.
+- The `image` is passed as a string. It automatically wraps in a massively shadowed `max-w-6xl` rounded frame floating below the typography. It completely hides itself on mobile.
+- `title` is heavily tuned for desktop `text-7xl` scaling.
+
+## 2. FeatureGrid
+
+The `FeatureGrid` is a robust section used to highlight three to four core selling points.
+
+### Anatomy
+```tsx
+// React Component
+import { FeatureGrid } from '@reinvented/design'
+import { Rocket, Shield, Zap } from 'lucide-react'
+
+
+export default function Component() {
+  return (
+    <>
+  <section className="container py-24 mx-auto px-6">
+    <h2 className="text-3xl font-bold mb-12 text-center">Why choose us?</h2>
+    
+    <FeatureGrid 
+      :columns="3"
+      :features="[
+        { title: 'Blazing Fast', description: 'Runs natively on modern engines.', icon: Zap },
+        { title: 'Secure', description: 'Enterprise-grade endpoints.', icon: Shield },
+        { title: 'Scalable', description: 'Deploy across the globe.', icon: Rocket }
+      ]"
+    />
+  </section>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Pass an array of `features` objects. The component seamlessly maps the `icon` into a heavily styled `primary/10` nested rounded-box.
+- Control the breakpoint math natively by passing `columns` (2, 3, or 4).
+
+## 3. TestimonialCard
+
+The `TestimonialCard` creates a distinct quote-box designed for social proof layouts.
+
+### Anatomy
+```tsx
+// React Component
+import { TestimonialCard } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <TestimonialCard 
+    quote="This system completely changed how our AI agents output Vue components. Flawless execution every time."
+    name="Jane Doe"
+    role="Lead Developer"
+    company="Acme Corp"
+    avatar="/avatar.jpg"
+    :rating="5"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Uses a muted inset background (`bg-muted/30`) by default, popping to `/50` on hover.
+- Passing a `rating` integer automatically generates SVG Star icons using `currentColor`.
+
+## 4. CtaBlock
+
+The `CtaBlock` (Call-to-Action) is the final, massive layout trigger typically placed at the bottom of a marketing page.
+
+### Anatomy
+```tsx
+// React Component
+import { CtaBlock } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <div className="container mx-auto px-4 py-12">
+    <CtaBlock 
+      title="Ready to dive in?"
+      description="Join thousands of developers building the next generation of software."
+      primaryAction="Get Started to 100% Free"
+      secondaryAction="Talk to Sales"
+    />
+  </div>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Reverses the color hierarchy entirely. The container assumes `bg-primary` natively and forces all text to `text-primary-foreground`.
+- Contains a massive SVG ambient pattern injected silently into the right edge of the bounding box.
+- The `primaryAction` button automatically swaps to a `variant="secondary"` style to maintain high contrast against the `primary` background container.

package/skills/blocks/media.md

@@ -0,0 +1,102 @@
+# Media & Realtime Blocks
+
+This document covers composite UI blocks designed for Audio/Video players and Realtime Voice/Video calls. 
+
+## When to use Blocks vs Primitives
+
+Use these blocks whenever the user needs a video player, an audio player, or a call interface. DO NOT build media players or call controls from scratch using raw `<Button>` or `<Slider>` elements, as aligning the components correctly to standard media expectations is complex and error-prone. These blocks provide strict layout, spacing, and state alignments.
+
+## 1. MediaPlayer
+
+The `MediaPlayer` block is a composite for rendering audio or video playback along with proper scrubbers and controls.
+
+### Anatomy
+```tsx
+// React Component
+import { Play, Pause, Volume2, Maximize } from 'lucide-react'
+import { Button } from '@reinvented/design'
+import { 
+  MediaPlayer, 
+  MediaPlayerVideo, 
+  MediaPlayerControls, 
+  MediaPlayerScrubber 
+} from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <MediaPlayer className="max-w-2xl">
+    <MediaPlayerVideo poster="/placeholders/video-cover.jpg" />
+    <MediaPlayerControls>
+      <MediaPlayerScrubber :defaultValue="[30]" currentTime="1:24" totalTime="4:30" />
+      <div className="flex items-center justify-between mt-1 text-foreground">
+        <div className="flex items-center gap-2">
+          <Button size="icon" variant="ghost" className="h-8 w-8 rounded-full">
+            <Play className="h-4 w-4" />
+          </Button>
+          <Button size="icon" variant="ghost" className="h-8 w-8 rounded-full">
+            <Volume2 className="h-4 w-4" />
+          </Button>
+        </div>
+        <Button size="icon" variant="ghost" className="h-8 w-8 rounded-full">
+          <Maximize className="h-4 w-4" />
+        </Button>
+      </div>
+    </MediaPlayerControls>
+  </MediaPlayer>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `MediaPlayer` acts as a rounded container (usually black).
+- `MediaPlayerVideo` expects a `poster` prop. If it's an audio player, omit `MediaPlayerVideo` entirely or replace it with a smaller visualization area.
+- `MediaPlayerControls` houses the scrubber and timeline action buttons.
+- `MediaPlayerScrubber` requires `defaultValue`, `currentTime`, and `totalTime` strings.
+
+## 2. CallControls
+
+The `CallControls` block provides standard realtime conferencing actions (Mic, Video, Screen Share, Hang Up).
+
+### Anatomy
+```tsx
+// React Component
+import { Mic, MicOff, Video, PhoneOff, MonitorUp } from 'lucide-react'
+import { 
+  CallControls, 
+  CallControlButton 
+} from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <CallControls>
+    <CallControlButton tooltip="Mute Microphone" active>
+      <Mic className="h-5 w-5" />
+    </CallControlButton>
+    
+    <CallControlButton tooltip="Stop Video">
+      <Video className="h-5 w-5" />
+    </CallControlButton>
+
+    <CallControlButton tooltip="Share Screen">
+      <MonitorUp className="h-5 w-5" />
+    </CallControlButton>
+
+    <CallControlButton tooltip="Leave Call" destructive>
+      <PhoneOff className="h-5 w-5" />
+    </CallControlButton>
+  </CallControls>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Place `CallControls` inside a relative container where you can center them either via Flexbox or absolute positioning (e.g. `absolute bottom-6 left-1/2 -translate-x-1/2`).
+- Use the `active` prop on `CallControlButton` to represent toggled-on states (e.g., Mic enabled vs Mic muted).
+- Use `destructive` for high-severity actions like ending a call.
+- Always provide a `tooltip` string for accessibility.