@dtlvmw/react 0.0.1

package/guidelines/components/tabs.md

@@ -0,0 +1,70 @@
+# Tabs
+
+Tabbed navigation with content panels.
+
+## HTML/CSS Template
+
+```html
+<!-- Horizontal tabs -->
+<ul class="nav" role="tablist">
+  <li role="presentation" class="nav-item">
+    <button class="btn btn-link nav-link active" role="tab" aria-selected="true">Tab 1</button>
+  </li>
+  <li role="presentation" class="nav-item">
+    <button class="btn btn-link nav-link" role="tab" aria-selected="false">Tab 2</button>
+  </li>
+  <li role="presentation" class="nav-item">
+    <button class="btn btn-link nav-link" role="tab" disabled>Disabled</button>
+  </li>
+</ul>
+<section class="tab-content active" role="tabpanel">
+  Content for Tab 1
+</section>
+
+<!-- Vertical tabs — wrap in a container with .nav-tabs-vertical -->
+<div class="nav-tabs-vertical">
+  <ul class="nav" role="tablist">...</ul>
+  <section class="tab-content active" role="tabpanel">...</section>
+</div>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `nav` | Tab list container (required on `ul`) |
+| `nav-item` | Tab item wrapper (`li`) |
+| `nav-link` | Tab button/link |
+| `active` | Active tab indicator (on `nav-link` and `tab-content`) |
+| `tab-content` | Tab panel content |
+| `nav-tabs-vertical` | Vertical tab layout wrapper |
+
+## React Component
+
+```tsx
+import { Tabs, TabList, Tab, TabPanel } from '@dtlvmw/react';
+```
+
+### Props
+
+**Tabs**: `vertical?: boolean`
+
+**Tab**: `active?: boolean`, `disabled?: boolean`
+
+**TabPanel**: `active?: boolean`
+
+### Example
+
+```tsx
+const [active, setActive] = useState(0);
+
+<Tabs>
+  <TabList>
+    <Tab active={active === 0} onClick={() => setActive(0)}>Dashboard</Tab>
+    <Tab active={active === 1} onClick={() => setActive(1)}>Settings</Tab>
+    <Tab disabled>Reports</Tab>
+  </TabList>
+  <TabPanel active={active === 0}>Dashboard content</TabPanel>
+  <TabPanel active={active === 1}>Settings content</TabPanel>
+</Tabs>
+```

package/guidelines/components/timeline.md

@@ -0,0 +1,87 @@
+# Timeline
+
+Horizontal or vertical step sequence for showing progress through a workflow.
+
+## HTML/CSS Template
+
+```html
+<!-- Horizontal timeline -->
+<div class="clr-timeline" role="list">
+  <div class="clr-timeline-step" role="listitem">
+    <div class="clr-timeline-step-header">11:59 am</div>
+    <cds-icon shape="success-standard" status="success"></cds-icon>
+    <div class="clr-timeline-step-body">
+      <div class="clr-timeline-step-title">Completed</div>
+      <div class="clr-timeline-step-description">Step 1 done.</div>
+    </div>
+  </div>
+  <div class="clr-timeline-step" role="listitem">
+    <div class="clr-timeline-step-header">12:00 pm</div>
+    <cds-icon shape="dot-circle" status="info"></cds-icon>
+    <div class="clr-timeline-step-body">
+      <div class="clr-timeline-step-title">Current</div>
+      <div class="clr-timeline-step-description">In progress.</div>
+    </div>
+  </div>
+  <div class="clr-timeline-step" role="listitem">
+    <div class="clr-timeline-step-header">12:30 pm</div>
+    <!-- Processing: use spinner instead of icon -->
+    <span class="spinner spinner-md" aria-label="In progress"></span>
+    <div class="clr-timeline-step-body">
+      <div class="clr-timeline-step-title">Processing</div>
+      <div class="clr-timeline-step-description">Working...</div>
+    </div>
+  </div>
+  <div class="clr-timeline-step" role="listitem">
+    <div class="clr-timeline-step-header">1:00 pm</div>
+    <cds-icon shape="circle"></cds-icon>
+    <div class="clr-timeline-step-body">
+      <div class="clr-timeline-step-title">Not Started</div>
+    </div>
+  </div>
+</div>
+
+<!-- Vertical timeline -->
+<div class="clr-timeline clr-timeline-vertical" role="list">
+  ...
+</div>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `clr-timeline` | Container (required) |
+| `clr-timeline-vertical` | Vertical layout |
+| `clr-timeline-step` | Step item |
+| `clr-timeline-step-header` | Timestamp/header |
+| `clr-timeline-step-body` | Step content |
+| `clr-timeline-step-title` | Step title |
+| `clr-timeline-step-description` | Step description |
+
+### Step State Icons
+
+| State | Icon |
+|-------|------|
+| Not started | `<cds-icon shape="circle">` |
+| Current | `<cds-icon shape="dot-circle" status="info">` |
+| Processing | `<span class="spinner spinner-md">` |
+| Success | `<cds-icon shape="success-standard" status="success">` |
+| Error | `<cds-icon shape="error-standard" status="danger">` |
+
+## React Component
+
+```tsx
+import { Timeline, TimelineStep } from '@dtlvmw/react';
+
+<Timeline>
+  <TimelineStep state="success" header="11:59 am" title="Completed" description="Step 1 done." />
+  <TimelineStep state="current" header="12:00 pm" title="Current" description="In progress." />
+  <TimelineStep state="processing" header="12:30 pm" title="Processing" description="Working..." />
+  <TimelineStep state="not-started" header="1:00 pm" title="Not Started" />
+</Timeline>
+
+<Timeline vertical>
+  ...
+</Timeline>
+```

package/guidelines/components/wizard.md

@@ -0,0 +1,160 @@
+# Wizard
+
+Multi-step modal wizard for guided workflows.
+
+## HTML/CSS Template
+
+```html
+<div class="clr-wizard wizard-lg">
+  <div class="modal">
+    <div class="modal-dialog modal-lg" role="dialog" aria-modal="true">
+      <div class="modal-content-wrapper">
+        <!-- Step Nav -->
+        <div class="modal-nav clr-wizard-stepnav-wrapper" role="region">
+          <div class="clr-wizard-title" role="heading" aria-level="1">Wizard Title</div>
+          <div class="clr-wizard-stepnav">
+            <nav aria-label="Wizard steps">
+              <ol class="clr-wizard-stepnav-list">
+                <li class="clr-wizard-stepnav-item active" aria-current="step">
+                  <button type="button" class="btn btn-link clr-wizard-stepnav-link">
+                    <span class="clr-wizard-stepnav-link-title">Step 1</span>
+                  </button>
+                </li>
+                <li class="clr-wizard-stepnav-item">
+                  <button type="button" class="btn btn-link clr-wizard-stepnav-link" disabled>
+                    <span class="clr-wizard-stepnav-link-title">Step 2</span>
+                  </button>
+                </li>
+              </ol>
+            </nav>
+          </div>
+        </div>
+
+        <!-- Content -->
+        <div class="modal-content">
+          <div class="modal-body-wrapper">
+            <div class="modal-body">
+              <main class="clr-wizard-content">
+                <div class="clr-wizard-page active">Page content here.</div>
+              </main>
+            </div>
+          </div>
+
+          <!-- Footer -->
+          <div class="modal-footer clr-wizard-footer">
+            <div class="clr-wizard-footer-buttons">
+              <div class="clr-wizard-footer-buttons-wrapper">
+                <div class="clr-wizard-btn-wrapper">
+                  <button type="button" class="btn clr-wizard-btn btn-link clr-wizard-btn--tertiary">Cancel</button>
+                </div>
+                <div class="clr-wizard-btn-wrapper">
+                  <button type="button" class="btn clr-wizard-btn btn-primary clr-wizard-btn--primary">Next</button>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+    <div class="modal-backdrop" aria-hidden="true"></div>
+  </div>
+</div>
+```
+
+### CSS Classes
+
+| Class | Description |
+|-------|-------------|
+| `clr-wizard` | Wizard container (required) |
+| `wizard-md`, `wizard-lg`, `wizard-xl` | Size variants |
+| `clr-wizard-title` | Title in the step nav sidebar |
+| `clr-wizard-stepnav-wrapper` | Step nav sidebar container |
+| `clr-wizard-stepnav-list` | Ordered list of steps |
+| `clr-wizard-stepnav-item` | Individual step item |
+| `clr-wizard-stepnav-item active` | Currently active step |
+| `clr-wizard-stepnav-item complete` | Completed step |
+| `clr-wizard-stepnav-item disabled` | Disabled/unreachable step |
+| `clr-wizard-stepnav-link` | Clickable step button |
+| `clr-wizard-content` | Page content area |
+| `clr-wizard-page` | Individual page container |
+| `clr-wizard-page active` | Visible page |
+| `clr-wizard-footer` | Footer with navigation buttons |
+| `clr-wizard-btn--tertiary` | Cancel button style |
+| `clr-wizard-btn--secondary` | Back button style |
+| `clr-wizard-btn--primary` | Next/Finish button style |
+
+## React Component
+
+```tsx
+import { Wizard, WizardPage } from '@dtlvmw/react';
+```
+
+### Wizard Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | — | Controls visibility |
+| `title` | `string` | `'Wizard'` | Wizard title in step nav |
+| `size` | `'md' \| 'lg' \| 'xl'` | `'lg'` | Wizard size |
+| `closable` | `boolean` | `true` | Show close button |
+| `onFinish` | `() => void` | — | Called when Finish is clicked |
+| `onCancel` | `() => void` | — | Called when Cancel or close is clicked |
+
+### WizardPage Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Step title (shown in nav) |
+| `nextDisabled` | `boolean` | — | Disables the Next/Finish button |
+
+### Example
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Button onClick={() => setOpen(true)}>Open Wizard</Button>
+
+<Wizard
+  open={open}
+  title="Setup Wizard"
+  size="lg"
+  onFinish={() => { console.log('done'); setOpen(false); }}
+  onCancel={() => setOpen(false)}
+>
+  <WizardPage title="User Info">
+    <Input label="Full Name" placeholder="Enter your name" />
+    <Input label="Email" placeholder="Enter your email" />
+  </WizardPage>
+  <WizardPage title="Preferences">
+    <Checkbox label="Enable notifications" />
+    <Select label="Theme">
+      <option>Light</option>
+      <option>Dark</option>
+    </Select>
+  </WizardPage>
+  <WizardPage title="Review">
+    <p>Please review your settings and click Finish.</p>
+  </WizardPage>
+</Wizard>
+```
+
+### Composability
+
+`WizardPage` children accept arbitrary React JSX. Nest any Tier 1 or Tier 2 component as page content:
+
+```tsx
+<WizardPage title="Data">
+  <Datagrid columns={cols} data={rows} />
+</WizardPage>
+
+<WizardPage title="Steps">
+  <Stepper steps={stepDefs} />
+</WizardPage>
+```
+
+### Navigation
+
+- Navigation between pages is managed automatically.
+- Users can click completed steps in the step nav to go back.
+- The Next button is disabled when `nextDisabled` is set on the current page.
+- Pressing Escape closes the wizard (when `closable` is true).

package/guidelines/design-tokens/colors.md

@@ -0,0 +1,21 @@
+# Colors
+
+Clarity uses CSS custom properties for theming. The default theme provides these semantic colors:
+
+## Status Colors
+- `--clr-color-action-600` — Primary blue
+- `--clr-color-success-700` — Green for success states
+- `--clr-color-warning-900` — Yellow/orange for warnings
+- `--clr-color-danger-700` — Red for errors and danger
+
+## Component Colors
+Components accept a `color` or `btnType` prop with these values:
+- `primary` (default) — Blue
+- `success` — Green
+- `warning` — Orange/Yellow
+- `danger` — Red
+
+## Badge/Label Colors
+Additional named colors for badges and labels:
+- `info`, `success`, `warning`, `danger`
+- `gray`, `blue`, `light-blue`, `orange`, `purple`

package/guidelines/design-tokens/spacing.md

@@ -0,0 +1,15 @@
+# Spacing
+
+Clarity uses a 6px base spacing unit. Components handle internal spacing automatically.
+
+## Common Spacing Values
+- `4px` — Tight spacing (within compact elements)
+- `6px` — Base unit
+- `12px` — Standard gap between inline elements
+- `24px` — Section spacing
+- `48px` — Large section spacing
+
+## Layout
+- Use `display: flex` with `gap` for component spacing
+- Cards: Use `16px` gap between cards
+- Form controls: Spaced automatically by Clarity CSS

package/guidelines/design-tokens/typography.md

@@ -0,0 +1,11 @@
+# Typography
+
+Clarity uses the Metropolis font family. Components inherit typography from the global CSS.
+
+## Headings
+- `h1` through `h6` are styled by Clarity CSS
+- Modal titles should use `<h3 className="modal-title">`
+
+## Body Text
+- Default body font size is 14px (0.7rem in Clarity's rem scale)
+- Use `.p1` through `.p8` utility classes for different text sizes

package/guidelines/overview-components.md

@@ -0,0 +1,48 @@
+# Component Overview
+
+## Tier 1: CSS-Only Components
+
+These components use Clarity CSS classes on standard HTML elements. No Angular runtime is required. They are pure React components.
+
+| Component | File | Key CSS Classes |
+|-----------|------|----------------|
+| Button | `button/Button.tsx` | `.btn`, `.btn-primary`, `.btn-*-outline`, `.btn-link` |
+| Alert | `alert/Alert.tsx` | `.alert`, `.alert-info`, `.alert-sm`, `.alert-lightweight` |
+| Badge | `badge/Badge.tsx` | `.badge`, `.badge-info`, `.badge-success` |
+| Label | `label/Label.tsx` | `.label`, `.label-info`, `.solid`, `.clickable` |
+| Card | `card/Card.tsx` | `.card`, `.card-header`, `.card-block`, `.card-footer` |
+| Modal | `modal/Modal.tsx` | `.modal`, `.modal-dialog`, `.modal-body`, `.modal-backdrop` |
+| Input | `input/Input.tsx` | `.clr-form-control`, `.clr-input-wrapper`, `.clr-input` |
+| Select | `select/Select.tsx` | `.clr-select-wrapper`, `.clr-select` |
+| Checkbox | `checkbox/Checkbox.tsx` | `.clr-checkbox-wrapper`, `.clr-checkbox` |
+| Toggle | `toggle/Toggle.tsx` | `.clr-toggle-wrapper`, `.clr-toggle` |
+| Tabs | `tabs/Tabs.tsx` | `.nav`, `.nav-item`, `.nav-link`, `.tab-content` |
+| Dropdown | `dropdown/Dropdown.tsx` | `.dropdown`, `.dropdown-menu`, `.dropdown-item` |
+| Accordion | `accordion/Accordion.tsx` | `.clr-accordion`, `.clr-accordion-panel` |
+| Spinner | `spinner/Spinner.tsx` | `.spinner`, `.spinner-sm`, `.spinner-inline` |
+| ProgressBar | `progress/ProgressBar.tsx` | `.progress`, `.compact`, `.labeled` |
+| Timeline | `timeline/Timeline.tsx` | `.clr-timeline`, `.clr-timeline-step` |
+| StackView | `stack-view/StackView.tsx` | `.stack-view`, `.stack-block` |
+| Header | `header/Header.tsx` | `.header`, `.branding`, `.header-nav` |
+| Table | `table/Table.tsx` | `.table`, `.table-compact`, `.table-noborder` |
+| Login | `login/Login.tsx` | `.login-wrapper`, `.login` |
+| Wizard | `wizard/Wizard.tsx` | `.clr-wizard`, `.clr-wizard-stepnav`, `.clr-wizard-page` |
+| CdsIcon | `internal/CdsIcon.tsx` | Inline SVG — reads from Clarity icon registry |
+
+## Tier 2: Angular Element Components
+
+These components wrap actual Angular components via `@angular/elements`. They require the `@dtlvmw/elements` bundle to be imported.
+
+| Component | Custom Element | Description |
+|-----------|---------------|-------------|
+| Datagrid | `<clr-wc-datagrid>` | Full-featured data grid with sorting, filtering, pagination |
+| Tree View | `<clr-wc-tree>` | Recursive tree with keyboard navigation |
+| Stepper | `<clr-wc-stepper>` | Form-integrated step flow |
+| Datepicker | `<clr-wc-datepicker>` | Calendar date picker |
+| Date Range Picker | `<clr-wc-date-range-picker>` | Date range selector |
+| Combobox | `<clr-wc-combobox>` | Autocomplete select |
+| Signpost | `<clr-wc-signpost>` | Positioned info popover |
+| Tooltip | `<clr-wc-tooltip>` | Hover tooltip |
+| Dropdown (Angular) | `<clr-wc-dropdown-angular>` | Keyboard-navigable dropdown |
+| Vertical Nav | `<clr-wc-vertical-nav>` | Collapsible side navigation |
+| Breadcrumbs | `<clr-wc-breadcrumbs>` | Navigation breadcrumbs |

package/guidelines/tier2/combobox.md

@@ -0,0 +1,48 @@
+# Combobox (Tier 2 — Angular Element)
+
+Autocomplete dropdown with filtering. Wraps `ClrCombobox`.
+
+## React Component
+
+```tsx
+import { Combobox } from '@dtlvmw/react';
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Input label |
+| `placeholder` | `string` | — | Input placeholder |
+| `options` | `ComboboxOption[]` | `[]` | Available options |
+| `selected` | `string` | — | Currently selected value |
+| `onSelectionChange` | `(value: string) => void` | — | Selection callback |
+
+### ComboboxOption
+
+```ts
+interface ComboboxOption {
+  value: string;
+  label: string;
+}
+```
+
+### Example
+
+```tsx
+const options = [
+  { value: 'us', label: 'United States' },
+  { value: 'ca', label: 'Canada' },
+  { value: 'uk', label: 'United Kingdom' },
+];
+
+const [country, setCountry] = useState('');
+
+<Combobox
+  label="Country"
+  placeholder="Search countries..."
+  options={options}
+  selected={country}
+  onSelectionChange={setCountry}
+/>
+```

package/guidelines/tier2/datagrid.md

@@ -0,0 +1,62 @@
+# Datagrid (Tier 2 — Angular Element)
+
+Full-featured data grid with sorting, filtering, and pagination. Wraps the actual `ClrDatagrid` Angular component.
+
+## React Component
+
+```tsx
+import '@dtlvmw/elements'; // once in entry point
+import { Datagrid } from '@dtlvmw/react';
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `DatagridColumn[]` | `[]` | Column definitions |
+| `data` | `any[]` | `[]` | Row data |
+| `loading` | `boolean` | — | Shows loading state |
+| `paginate` | `boolean` | — | Enable pagination |
+| `pageSize` | `number` | `10` | Items per page |
+| `onRefresh` | `(state) => void` | — | Grid state change callback |
+| `onSelectedChange` | `(selected) => void` | — | Selection change callback |
+
+### DatagridColumn
+
+```ts
+interface DatagridColumn {
+  field: string;     // Property key in data objects
+  label: string;     // Column header text
+  sortable?: boolean;
+  filterable?: boolean;
+}
+```
+
+### Example
+
+```tsx
+const columns = [
+  { field: 'name', label: 'Name', sortable: true, filterable: true },
+  { field: 'role', label: 'Role', sortable: true },
+  { field: 'status', label: 'Status' },
+];
+
+const data = [
+  { name: 'Alice', role: 'Admin', status: 'Active' },
+  { name: 'Bob', role: 'User', status: 'Inactive' },
+  { name: 'Carol', role: 'Editor', status: 'Active' },
+];
+
+<Datagrid columns={columns} data={data} paginate pageSize={10} />
+```
+
+### Web Component Usage
+
+```html
+<clr-wc-datagrid
+  columns='[{"field":"name","label":"Name","sortable":true}]'
+  data='[{"name":"Alice","role":"Admin"}]'
+  paginate
+  page-size="10"
+></clr-wc-datagrid>
+```

package/guidelines/tier2/datepicker.md

@@ -0,0 +1,26 @@
+# Datepicker (Tier 2 — Angular Element)
+
+Calendar date picker with popover. Wraps `ClrDateContainer` + `clrDate`.
+
+## React Component
+
+```tsx
+import { Datepicker } from '@dtlvmw/react';
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Input label |
+| `value` | `string` | — | Date value |
+| `placeholder` | `string` | `'MM/DD/YYYY'` | Input placeholder |
+| `onChange` | `(value: string) => void` | — | Value change callback |
+
+### Example
+
+```tsx
+const [date, setDate] = useState('');
+
+<Datepicker label="Start Date" value={date} onChange={setDate} />
+```

package/guidelines/tier2/overview.md

@@ -0,0 +1,69 @@
+# Tier 2: Angular Element Components
+
+These components wrap actual Clarity Angular components via `@angular/elements`. They contain complex interactive logic (sorting, filtering, pagination, keyboard navigation, popover positioning, etc.) that cannot be replicated with CSS alone.
+
+## Setup
+
+```tsx
+// 1. Import Clarity CSS
+import '@dtlvmw/ui/clr-ui.min.css';
+
+// 2. Import Angular Elements bundle (registers all custom elements)
+import '@dtlvmw/elements';
+
+// 3. Import React wrappers
+import { Datagrid, TreeView, Stepper } from '@dtlvmw/react';
+```
+
+The `@dtlvmw/elements` import bootstraps the Angular runtime and registers all Tier 2 web components. It only needs to be imported once in your application's entry point.
+
+## Bundle Size Note
+
+The Angular Elements bundle includes the Angular runtime (~200-300 KB gzipped). Only import it if you need Tier 2 components. Tier 1 CSS-only components have zero Angular overhead.
+
+## Available Tier 2 Components
+
+| Component | Custom Element | React Wrapper | Description |
+|-----------|---------------|---------------|-------------|
+| Datagrid | `<clr-wc-datagrid>` | `<Datagrid>` | Full-featured data grid |
+| Tree View | `<clr-wc-tree>` | `<TreeView>` | Recursive tree with selection |
+| Stepper | `<clr-wc-stepper>` | `<Stepper>` | Form-integrated step flow |
+| Datepicker | `<clr-wc-datepicker>` | `<Datepicker>` | Calendar date picker |
+| Date Range Picker | `<clr-wc-date-range-picker>` | `<DateRangePicker>` | Date range selector |
+| Combobox | `<clr-wc-combobox>` | `<Combobox>` | Autocomplete select |
+| Signpost | `<clr-wc-signpost>` | `<Signpost>` | Positioned info popover |
+| Tooltip | `<clr-wc-tooltip>` | `<Tooltip>` | Hover tooltip |
+| Dropdown (Angular) | `<clr-wc-dropdown-angular>` | `<DropdownAngular>` | Keyboard-navigable dropdown |
+| Vertical Nav | `<clr-wc-vertical-nav>` | `<VerticalNav>` | Collapsible side navigation |
+| Breadcrumbs | `<clr-wc-breadcrumbs>` | `<Breadcrumbs>` | Navigation breadcrumbs |
+
+## Data Passing
+
+Complex data (arrays, objects) is passed to web components as JSON strings. The React wrappers handle this serialization automatically:
+
+```tsx
+// React wrapper handles JSON.stringify internally
+<Datagrid
+  columns={[{ field: 'name', label: 'Name', sortable: true }]}
+  data={[{ name: 'John' }]}
+/>
+
+// Equivalent raw web component usage
+<clr-wc-datagrid
+  columns='[{"field":"name","label":"Name","sortable":true}]'
+  data='[{"name":"John"}]'
+/>
+```
+
+## Event Handling
+
+Events from web components are dispatched as `CustomEvent`. The React wrappers listen for these and call your callback props:
+
+```tsx
+<Datagrid
+  columns={columns}
+  data={data}
+  onRefresh={(state) => console.log('Grid refresh:', state)}
+  onSelectedChange={(selected) => console.log('Selected:', selected)}
+/>
+```