@dtlvmw/react 0.0.1

package/guidelines/Guidelines.md

@@ -0,0 +1,53 @@
+# Clarity Design System — React Components for Figma MAKE
+
+This package provides React components for the Clarity Design System. Components are split into two tiers:
+
+## Tier 1: CSS-Only Components (this section)
+
+Pure React components that use Clarity CSS classes on standard HTML elements. **No Angular runtime required.** These are lightweight and have zero JavaScript framework overhead beyond React itself.
+
+## Tier 2: Angular Element Components
+
+Complex interactive components (Datagrid, Tree View, Stepper, etc.) backed by `@angular/elements`. These import the actual Angular component logic as web components. See the `tier2/` guidelines folder.
+
+## Setup
+
+```tsx
+// 1. Import Clarity CSS (required for all components)
+import '@dtlvmw/ui/clr-ui.min.css';
+
+// 2. Import React components
+import { Button, Alert, Card, Modal, Wizard, WizardPage, CdsIcon } from '@dtlvmw/react';
+
+// 3. For Tier 2 components only — import the elements bundle
+// import '@dtlvmw/elements';
+```
+
+## Tier 1 Components (CSS-Only)
+
+| Component | Description |
+|-----------|-------------|
+| **Button** | Action trigger — solid, outline, link styles |
+| **Alert** | Notification banners — info, success, warning, danger |
+| **Badge** | Numeric/status indicators |
+| **Label** | Categorization tags with colors |
+| **Card** | Content containers with header, body, footer |
+| **Modal** | Overlay dialogs with backdrop |
+| **Input** | Text input with label and validation states |
+| **Select** | Dropdown select |
+| **Checkbox** | Binary toggle |
+| **Toggle** | Switch-style toggle |
+| **Tabs** | Tabbed navigation with panels |
+| **Dropdown** | Action menu (CSS-based open/close) |
+| **Accordion** | Collapsible content panels |
+| **Spinner** | Loading indicator |
+| **ProgressBar** | Determinate/indeterminate progress |
+| **Timeline** | Horizontal/vertical step sequence |
+| **StackView** | Expandable key-value blocks |
+| **Header** | App header with nav and branding |
+| **Table** | Styled data table |
+| **Login** | Login page layout |
+| **Wizard** | Multi-step modal wizard with composable pages |
+| **CdsIcon** | Pure React SVG icon (reads from Clarity icon registry) |
+
+See individual component guidelines in the `components/` folder for detailed API reference and usage examples.

package/guidelines/components/accordion.md

@@ -0,0 +1,109 @@
+# Accordion
+
+Collapsible content panels for organizing sections of content.
+
+## HTML/CSS Template
+
+```html
+<div class="clr-accordion">
+  <!-- Open panel -->
+  <div class="clr-accordion-panel">
+    <div class="clr-accordion-panel-open">
+      <div class="clr-accordion-header">
+        <button type="button" class="clr-accordion-header-button" aria-expanded="true">
+          <span class="clr-accordion-status">
+            <cds-icon shape="angle" direction="right" class="clr-accordion-angle"></cds-icon>
+          </span>
+          <span class="clr-accordion-title">Panel 1</span>
+        </button>
+      </div>
+      <div role="region" class="clr-accordion-content-region">
+        <div class="clr-accordion-content">
+          <div class="clr-accordion-inner-content">
+            Panel 1 content goes here.
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Closed panel -->
+  <div class="clr-accordion-panel">
+    <div class="clr-accordion-panel-closed">
+      <div class="clr-accordion-header">
+        <button type="button" class="clr-accordion-header-button" aria-expanded="false">
+          <span class="clr-accordion-status">
+            <cds-icon shape="angle" direction="right" class="clr-accordion-angle"></cds-icon>
+          </span>
+          <span class="clr-accordion-title">Panel 2</span>
+        </button>
+      </div>
+    </div>
+  </div>
+
+  <!-- Disabled panel -->
+  <div class="clr-accordion-panel clr-accordion-panel-disabled">
+    <div class="clr-accordion-panel-closed">
+      <div class="clr-accordion-header">
+        <button type="button" class="clr-accordion-header-button" disabled>
+          <span class="clr-accordion-status">
+            <cds-icon shape="angle" direction="right" class="clr-accordion-angle"></cds-icon>
+          </span>
+          <span class="clr-accordion-title">Disabled Panel</span>
+        </button>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `clr-accordion` | Accordion container (required) |
+| `clr-accordion-panel` | Panel wrapper |
+| `clr-accordion-panel-open` | Open state wrapper |
+| `clr-accordion-panel-closed` | Closed state wrapper |
+| `clr-accordion-panel-disabled` | Disabled panel |
+| `clr-accordion-header` | Header container |
+| `clr-accordion-header-button` | Clickable header button |
+| `clr-accordion-status` | Icon container |
+| `clr-accordion-angle` | Chevron icon |
+| `clr-accordion-title` | Panel title text |
+| `clr-accordion-content-region` | Content wrapper (visible when open) |
+| `clr-accordion-content` | Content inner wrapper |
+| `clr-accordion-inner-content` | Innermost content |
+
+## React Component
+
+```tsx
+import { Accordion, AccordionPanel } from '@dtlvmw/react';
+```
+
+### AccordionPanel Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `panelOpen` | `boolean` | — | Whether the panel is expanded |
+| `disabled` | `boolean` | — | Disables the panel |
+| `title` | `ReactNode` | — | Panel header text |
+| `onToggle` | `() => void` | — | Called when header is clicked |
+
+### Example
+
+```tsx
+const [open, setOpen] = useState<number | null>(0);
+
+<Accordion>
+  <AccordionPanel title="Section 1" panelOpen={open === 0} onToggle={() => setOpen(open === 0 ? null : 0)}>
+    Content for section 1.
+  </AccordionPanel>
+  <AccordionPanel title="Section 2" panelOpen={open === 1} onToggle={() => setOpen(open === 1 ? null : 1)}>
+    Content for section 2.
+  </AccordionPanel>
+  <AccordionPanel title="Disabled" disabled>
+    Cannot open this.
+  </AccordionPanel>
+</Accordion>
+```

package/guidelines/components/alert.md

@@ -0,0 +1,107 @@
+# Alert
+
+Notification banners for displaying contextual messages.
+
+## HTML/CSS Template
+
+```html
+<!-- Info alert (default) -->
+<div class="alert alert-info">
+  <div class="alert-items">
+    <div class="alert-item static">
+      <div class="alert-icon-wrapper">
+        <cds-icon class="alert-icon" shape="info-circle"></cds-icon>
+      </div>
+      <div class="alert-text">This is an info alert.</div>
+    </div>
+  </div>
+  <button type="button" class="close">
+    <cds-icon shape="times"></cds-icon>
+  </button>
+</div>
+
+<!-- Danger alert, small, not closable -->
+<div class="alert alert-danger alert-sm">
+  <div class="alert-items">
+    <div class="alert-item static">
+      <div class="alert-icon-wrapper">
+        <cds-icon class="alert-icon" shape="exclamation-circle"></cds-icon>
+      </div>
+      <div class="alert-text">Error occurred.</div>
+    </div>
+  </div>
+</div>
+
+<!-- App-level alert -->
+<div class="alert alert-warning alert-app-level">
+  <div class="alert-items">
+    <div class="alert-item static">
+      <div class="alert-icon-wrapper">
+        <cds-icon class="alert-icon" shape="exclamation-triangle"></cds-icon>
+      </div>
+      <div class="alert-text">Maintenance scheduled.</div>
+    </div>
+  </div>
+</div>
+
+<!-- Lightweight alert -->
+<div class="alert alert-success alert-lightweight">
+  <div class="alert-items">
+    <div class="alert-item static">
+      <div class="alert-icon-wrapper">
+        <cds-icon class="alert-icon" shape="check-circle"></cds-icon>
+      </div>
+      <div class="alert-text">Operation succeeded.</div>
+    </div>
+  </div>
+</div>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `alert` | Base class (required) |
+| `alert-info` | Blue info style |
+| `alert-success` | Green success style |
+| `alert-warning` | Yellow warning style |
+| `alert-danger` | Red danger style |
+| `alert-sm` | Compact size |
+| `alert-lightweight` | Lightweight style (no background) |
+| `alert-app-level` | Full-width app-level banner |
+
+### Icon Mapping
+
+| Alert Type | Icon Shape |
+|------------|------------|
+| `info` | `info-circle` |
+| `success` | `check-circle` |
+| `warning` | `exclamation-triangle` |
+| `danger` | `exclamation-circle` |
+
+## React Component
+
+```tsx
+import { Alert } from '@dtlvmw/react';
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `alertType` | `'info' \| 'warning' \| 'danger' \| 'success'` | `'info'` | Alert color/type |
+| `closable` | `boolean` | `true` | Shows close button |
+| `small` | `boolean` | — | Compact size |
+| `lightweight` | `boolean` | — | Lightweight style |
+| `appLevel` | `boolean` | — | App-level banner |
+| `onClose` | `() => void` | — | Called when close button clicked |
+
+### Examples
+
+```tsx
+<Alert alertType="info">This is informational.</Alert>
+<Alert alertType="danger" closable={false}>Critical error.</Alert>
+<Alert alertType="success" small>Saved!</Alert>
+<Alert alertType="warning" appLevel>Maintenance window tonight.</Alert>
+<Alert alertType="info" lightweight>Subtle notification.</Alert>
+```

package/guidelines/components/badge-label.md

@@ -0,0 +1,100 @@
+# Badge & Label
+
+## Badge
+
+Numeric or status indicators.
+
+### HTML/CSS Template
+
+```html
+<span class="badge">42</span>
+<span class="badge badge-info">Info</span>
+<span class="badge badge-success">3</span>
+<span class="badge badge-warning">!</span>
+<span class="badge badge-danger">9</span>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `badge` | Base class (required) |
+| `badge-info` | Blue badge |
+| `badge-success` | Green badge |
+| `badge-warning` | Yellow badge |
+| `badge-danger` | Red badge |
+| `badge-gray` | Gray badge |
+| `badge-orange` | Orange badge |
+| `badge-purple` | Purple badge |
+
+### React Component
+
+```tsx
+import { Badge } from '@dtlvmw/react';
+
+<Badge>42</Badge>
+<Badge color="success">3</Badge>
+<Badge color="danger">9</Badge>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `'info' \| 'success' \| 'warning' \| 'danger' \| 'gray' \| ...` | — | Badge color |
+
+---
+
+## Label
+
+Categorization tags with colors and states.
+
+### HTML/CSS Template
+
+```html
+<span class="label">Default</span>
+<span class="label label-info">Info</span>
+<span class="label label-success solid">Solid Success</span>
+<span class="label label-warning clickable">Clickable</span>
+<span class="label label-danger disabled">Disabled</span>
+
+<!-- Label with badge -->
+<span class="label label-info">
+  Category <span class="badge">5</span>
+</span>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `label` | Base class (required) |
+| `label-info` | Blue label |
+| `label-success` | Green label |
+| `label-warning` | Yellow label |
+| `label-danger` | Red label |
+| `solid` | Solid background fill |
+| `clickable` | Hover/click styling |
+| `disabled` | Muted disabled state |
+
+### React Component
+
+```tsx
+import { Label } from '@dtlvmw/react';
+
+<Label color="info">Status</Label>
+<Label color="success" labelType="solid">Active</Label>
+<Label color="danger" clickable>Remove</Label>
+<Label color="info" badgeText="5">Category</Label>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `'info' \| 'success' \| 'warning' \| 'danger' \| ...` | — | Color variant |
+| `labelType` | `'solid' \| 'outlined'` | — | Fill style |
+| `clickable` | `boolean` | — | Clickable appearance |
+| `disabled` | `boolean` | — | Disabled state |
+| `text` | `string` | — | Label text (alternative to children) |
+| `badgeText` | `string` | — | Badge text inside the label |

package/guidelines/components/breadcrumbs.md

@@ -0,0 +1,45 @@
+# Breadcrumbs
+
+Navigation breadcrumbs for showing page hierarchy.
+
+## HTML/CSS Template
+
+```html
+<nav class="clr-breadcrumb" aria-label="Breadcrumbs">
+  <ol>
+    <li><a href="#">Home</a></li>
+    <li><a href="#">Settings</a></li>
+    <li><span aria-current="page">Profile</span></li>
+  </ol>
+</nav>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `clr-breadcrumb` | Container `nav` element (required) |
+
+## React Component
+
+```tsx
+import { Breadcrumbs } from '@dtlvmw/react';
+
+<Breadcrumbs
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Settings', href: '/settings' },
+    { label: 'Profile', active: true },
+  ]}
+  onItemClick={(item) => navigate(item.href)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `BreadcrumbItem[]` | `[]` | Breadcrumb items |
+| `onItemClick` | `(item) => void` | — | Click handler |
+
+**BreadcrumbItem**: `{ label: string; href?: string; active?: boolean }`

package/guidelines/components/button.md

@@ -0,0 +1,77 @@
+# Button
+
+Action trigger component with multiple visual styles and states.
+
+## HTML/CSS Template
+
+```html
+<!-- Primary solid -->
+<button class="btn btn-primary">Primary</button>
+
+<!-- Success outline -->
+<button class="btn btn-success-outline">Success</button>
+
+<!-- Link style -->
+<button class="btn btn-link">Link</button>
+
+<!-- Small -->
+<button class="btn btn-primary btn-sm">Small</button>
+
+<!-- Block (full width) -->
+<button class="btn btn-primary btn-block">Full Width</button>
+
+<!-- Loading -->
+<button class="btn btn-primary btn-loading" disabled>
+  <span class="spinner spinner-inline"></span>
+  Saving...
+</button>
+
+<!-- Disabled -->
+<button class="btn btn-primary" disabled>Disabled</button>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `btn` | Base button class (required) |
+| `btn-primary` | Blue primary button |
+| `btn-success` | Green success button |
+| `btn-warning` | Yellow warning button |
+| `btn-danger` | Red danger button |
+| `btn-primary-outline` | Primary outline variant |
+| `btn-success-outline` | Success outline variant |
+| `btn-warning-outline` | Warning outline variant |
+| `btn-danger-outline` | Danger outline variant |
+| `btn-link` | Link-style button |
+| `btn-sm` | Small size |
+| `btn-block` | Full-width block layout |
+| `btn-loading` | Loading state (add spinner inside) |
+
+## React Component
+
+```tsx
+import { Button } from '@dtlvmw/react';
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `btnType` | `'primary' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | Color variant |
+| `btnStyle` | `'solid' \| 'outline' \| 'link'` | `'solid'` | Visual style |
+| `size` | `'default' \| 'sm'` | — | Size variant |
+| `disabled` | `boolean` | — | Disabled state |
+| `block` | `boolean` | — | Full-width button |
+| `loading` | `boolean` | — | Shows inline spinner, disables button |
+
+### Examples
+
+```tsx
+<Button btnType="primary">Save</Button>
+<Button btnType="danger" btnStyle="outline">Delete</Button>
+<Button btnStyle="link">Cancel</Button>
+<Button size="sm">Small</Button>
+<Button loading>Saving...</Button>
+<Button block>Full Width</Button>
+```

package/guidelines/components/card.md

@@ -0,0 +1,78 @@
+# Card
+
+Content containers with header, body, and footer sections.
+
+## HTML/CSS Template
+
+```html
+<div class="card">
+  <div class="card-header">Card Title</div>
+  <div class="card-block">
+    <div class="card-title">Section Title</div>
+    <div class="card-text">Card body content goes here.</div>
+  </div>
+  <div class="card-footer">
+    <button class="btn btn-sm btn-link">Action 1</button>
+    <button class="btn btn-sm btn-link">Action 2</button>
+  </div>
+</div>
+
+<!-- Clickable card -->
+<div class="card clickable">
+  <div class="card-block">
+    <div class="card-text">Click me</div>
+  </div>
+</div>
+
+<!-- Card with image -->
+<div class="card">
+  <div class="card-img">
+    <img src="image.jpg" alt="Card image" />
+  </div>
+  <div class="card-block">
+    <div class="card-text">Image card content.</div>
+  </div>
+</div>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `card` | Base card container (required) |
+| `card-header` | Card header section |
+| `card-block` | Card body container |
+| `card-title` | Title inside card-block |
+| `card-text` | Text content inside card-block |
+| `card-footer` | Footer with actions |
+| `card-img` | Image container |
+| `clickable` | Adds hover effect |
+
+## React Component
+
+```tsx
+import { Card, CardHeader, CardBlock, CardTitle, CardText, CardFooter } from '@dtlvmw/react';
+
+<Card>
+  <CardHeader>My Card</CardHeader>
+  <CardBlock>
+    <CardTitle>Section</CardTitle>
+    <CardText>Content goes here.</CardText>
+  </CardBlock>
+  <CardFooter>
+    <button className="btn btn-sm btn-link">Action</button>
+  </CardFooter>
+</Card>
+
+<Card clickable>
+  <CardBlock>
+    <CardText>Clickable card</CardText>
+  </CardBlock>
+</Card>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `clickable` | `boolean` | — | Adds hover effect |

package/guidelines/components/dropdown.md

@@ -0,0 +1,75 @@
+# Dropdown
+
+Action menu with trigger button, items, headers, and dividers.
+
+## HTML/CSS Template
+
+```html
+<!-- Closed dropdown -->
+<div class="dropdown">
+  <button class="dropdown-toggle btn btn-link">
+    Dropdown <cds-icon shape="angle" direction="down"></cds-icon>
+  </button>
+  <div class="dropdown-menu">
+    <div class="dropdown-header">Group 1</div>
+    <button class="dropdown-item">Action 1</button>
+    <button class="dropdown-item">Action 2</button>
+    <div class="dropdown-divider"></div>
+    <button class="dropdown-item">Action 3</button>
+  </div>
+</div>
+
+<!-- Open dropdown — add .open class -->
+<div class="dropdown open">
+  ...
+</div>
+
+<!-- Position variants — add to .dropdown -->
+<!-- bottom-left (default), bottom-right, top-left, top-right -->
+<div class="dropdown open bottom-right">
+  ...
+</div>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `dropdown` | Container (required) |
+| `open` | Shows the dropdown menu |
+| `dropdown-toggle` | Trigger button |
+| `dropdown-menu` | Menu container |
+| `dropdown-header` | Group header text |
+| `dropdown-item` | Menu item button |
+| `dropdown-divider` | Separator line |
+| `bottom-left` | Position (default) |
+| `bottom-right` | Position |
+| `top-left` | Position |
+| `top-right` | Position |
+
+## React Component
+
+```tsx
+import { Dropdown, DropdownTrigger, DropdownMenu, DropdownItem, DropdownDivider, DropdownHeader } from '@dtlvmw/react';
+```
+
+### Props
+
+**Dropdown**: `open?: boolean`, `position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'`, `onOpenChange?: (open: boolean) => void`
+
+### Example
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Dropdown open={open} onOpenChange={setOpen}>
+  <DropdownTrigger onClick={() => setOpen(!open)}>Actions</DropdownTrigger>
+  <DropdownMenu>
+    <DropdownHeader>Management</DropdownHeader>
+    <DropdownItem onClick={() => console.log('edit')}>Edit</DropdownItem>
+    <DropdownItem onClick={() => console.log('delete')}>Delete</DropdownItem>
+    <DropdownDivider />
+    <DropdownItem>Archive</DropdownItem>
+  </DropdownMenu>
+</Dropdown>
+```