chore: add comprehensive documentation
All checks were successful
armco-org/components-viewer/pipeline/head This commit was not built
All checks were successful
armco-org/components-viewer/pipeline/head This commit was not built
- Add docs/SPECS.md, DESIGN.md, DEBT.md, READINESS.md - Update README.md with comprehensive documentation
This commit is contained in:
129
README.md
129
README.md
@@ -1 +1,128 @@
|
||||
# Armco Template for the tech stack: React, TS, Dart Sass, Redux Tookkit, react-redux, react browser routing, TS based plop generator
|
||||
# @armco/components-viewer
|
||||
|
||||
> Component Development & Testing Environment for Armco Design System
|
||||
|
||||
components-viewer is a React-based playground for exploring, testing, and developing components in the Armco design system. It provides live preview, prop editing, and theme switching capabilities.
|
||||
|
||||
## Features
|
||||
|
||||
- **Component Explorer**: Hierarchical tree navigation of all components
|
||||
- **Live Preview**: Real-time component rendering with error boundaries
|
||||
- **Prop Editing**: Dynamic controls for component props
|
||||
- **Theme Toggle**: Light/Dark theme switching
|
||||
- **URL State**: Shareable URLs with component and prop state
|
||||
- **Drag & Drop**: Drag components from tree (react-dnd)
|
||||
- **Library Loading**: Load external component libraries
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pnpm add @armco/components-viewer
|
||||
```
|
||||
|
||||
## Peer Dependencies
|
||||
|
||||
```json
|
||||
{
|
||||
"@armco/components": "^0.0.60",
|
||||
"@armco/configs": "^0.0.11",
|
||||
"@armco/types": "^0.0.18",
|
||||
"@armco/utils": "^0.0.29",
|
||||
"@reduxjs/toolkit": "^1.8.1",
|
||||
"react": "^18.2.0",
|
||||
"react-bootstrap": "^2.7.4",
|
||||
"react-dnd": ">=16.0.0",
|
||||
"react-dnd-html5-backend": ">=16.0.0",
|
||||
"react-dnd-touch-backend": ">=16.0.0",
|
||||
"react-redux": "^8.0.1",
|
||||
"react-router-dom": "^6.13.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```tsx
|
||||
import ComponentsViewer from "@armco/components-viewer"
|
||||
import { BrowserRouter } from "react-router-dom"
|
||||
import { ArProvider } from "@armco/utils/providers"
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<BrowserRouter>
|
||||
<ArProvider>
|
||||
<ComponentsViewer />
|
||||
</ArProvider>
|
||||
</BrowserRouter>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## URL Structure
|
||||
|
||||
Components are accessible via URL:
|
||||
```
|
||||
/components/Button?size=large&variant=primary
|
||||
```
|
||||
|
||||
This makes component states shareable and bookmarkable.
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Start development server
|
||||
pnpm dev
|
||||
|
||||
# Build library
|
||||
pnpm build
|
||||
|
||||
# Run tests
|
||||
pnpm test
|
||||
|
||||
# Generate new component
|
||||
pnpm generate
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── ComponentsViewer.tsx # Main container
|
||||
├── ComponentList.tsx # Tree navigation
|
||||
├── Editor.tsx # Preview workspace
|
||||
├── components.ts # Component configs
|
||||
├── dummies.tsx # Test data
|
||||
├── helper.ts # Utilities
|
||||
└── types.ts # TypeScript types
|
||||
```
|
||||
|
||||
## Adding New Components
|
||||
|
||||
Edit `src/components.ts` to add component configurations:
|
||||
|
||||
```typescript
|
||||
{
|
||||
name: "MyComponent",
|
||||
props: ["size", "variant"],
|
||||
variants: {
|
||||
size: ["small", "medium", "large"],
|
||||
variant: ["primary", "secondary"],
|
||||
},
|
||||
uses: [
|
||||
{ name: "Button", hierarchy: "ATOMS" },
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- [SPECS.md](docs/SPECS.md) - Feature specifications
|
||||
- [DESIGN.md](docs/DESIGN.md) - Architecture diagrams
|
||||
- [DEBT.md](docs/DEBT.md) - Technical debt register
|
||||
- [READINESS.md](docs/READINESS.md) - Production checklist
|
||||
|
||||
## License
|
||||
|
||||
ISC
|
||||
|
||||
244
docs/DEBT.md
Normal file
244
docs/DEBT.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# components-viewer - Technical Debt Register
|
||||
|
||||
## 🔴 Critical (Must Fix Before Production)
|
||||
|
||||
### 1. Massive Component Configuration File
|
||||
**Location:** `src/components.ts`
|
||||
**Issue:** 1167+ line monolithic file
|
||||
**Risk:** Unmaintainable, hard to update, merge conflicts
|
||||
**Resolution:** Split by category or use dynamic loading
|
||||
**Effort:** Medium (4-6 hours)
|
||||
|
||||
---
|
||||
|
||||
### 2. TypeScript `any` Types
|
||||
**Locations:** Multiple files
|
||||
| File | Line | Issue |
|
||||
|------|------|-------|
|
||||
| `ComponentList.tsx` | 12 | `Components: any` |
|
||||
| `Editor.tsx` | 19 | `Components: { [key: string]: any }` |
|
||||
| `helper.ts` | 34 | `item: any` |
|
||||
| `dummies.tsx` | 17 | `DUMMIES: { [key: string]: { [key: string]: any } }` |
|
||||
|
||||
**Risk:** No type safety, runtime errors possible
|
||||
**Resolution:** Define proper component types
|
||||
**Effort:** Medium (6-8 hours)
|
||||
|
||||
---
|
||||
|
||||
### 3. ESLint Disable Comments
|
||||
**Locations:** Various
|
||||
| File | Issue |
|
||||
|------|-------|
|
||||
| `Editor.tsx` | `eslint-disable-next-line react-hooks/exhaustive-deps` (2x) |
|
||||
|
||||
**Risk:** Potential stale closure bugs
|
||||
**Resolution:** Fix dependency arrays properly
|
||||
**Effort:** Low (2-3 hours)
|
||||
|
||||
---
|
||||
|
||||
## 🟠 High Priority
|
||||
|
||||
### 4. CDN Script Loading Without Error Handling
|
||||
**Location:** `src/ComponentList.tsx` (Lines ~26-40)
|
||||
**Issue:** External library loading via CDN with minimal error handling
|
||||
```typescript
|
||||
loadScript(
|
||||
"https://cdnjs.cloudflare.com/ajax/libs/antd/5.21.4/antd.min.js",
|
||||
"andtd", // Typo: should be "antd"
|
||||
)
|
||||
```
|
||||
**Risks:**
|
||||
- CDN failures break application
|
||||
- CORS issues
|
||||
- Version pinning to CDN
|
||||
- Typo in global variable name ("andtd")
|
||||
|
||||
**Resolution:** Add proper error handling, fallbacks
|
||||
**Effort:** Medium (4-6 hours)
|
||||
|
||||
---
|
||||
|
||||
### 5. TODO Comment in Production Code
|
||||
**Location:** `src/ComponentList.tsx` (Line ~48)
|
||||
```typescript
|
||||
// TODO: Test code
|
||||
useEffect(() => loadComponents("@armco/components"), [])
|
||||
```
|
||||
**Risk:** Unclear if intentional or leftover test code
|
||||
**Resolution:** Document or refactor
|
||||
**Effort:** Low (1 hour)
|
||||
|
||||
---
|
||||
|
||||
### 6. Hardcoded Library List
|
||||
**Location:** `src/ComponentList.tsx` (Lines ~14-35)
|
||||
**Issue:** Supported libraries hardcoded in component
|
||||
```typescript
|
||||
const LIBS: { [key: string]: () => Promise<any> } = {
|
||||
"@armco/components": () => import("@armco/components"),
|
||||
antd: () => loadScript(...),
|
||||
// etc
|
||||
}
|
||||
```
|
||||
**Resolution:** Move to configuration file
|
||||
**Effort:** Low (2-3 hours)
|
||||
|
||||
---
|
||||
|
||||
### 7. No Unit Tests
|
||||
**Issue:** 0% test coverage
|
||||
**Files needing tests:**
|
||||
- `helper.ts` - `findComponentDescription()`, `adaptToTreeFromComponentConfig()`
|
||||
- `ComponentList.tsx` - Library loading logic
|
||||
- `Editor.tsx` - Prop parsing logic
|
||||
|
||||
**Resolution:** Add Vitest tests
|
||||
**Effort:** High (16-24 hours)
|
||||
|
||||
---
|
||||
|
||||
## 🟡 Medium Priority
|
||||
|
||||
### 8. TypeScript Ignore Comment
|
||||
**Location:** `src/Editor.tsx` (Line ~50)
|
||||
```typescript
|
||||
// @ts-ignore
|
||||
backgroundImage: background ? `url(${background})` : "",
|
||||
```
|
||||
**Risk:** Type error suppressed
|
||||
**Resolution:** Fix type definition
|
||||
**Effort:** Low (1 hour)
|
||||
|
||||
---
|
||||
|
||||
### 9. Prop Parsing Catches All Errors
|
||||
**Location:** `src/Editor.tsx` (Lines ~35-41)
|
||||
```typescript
|
||||
try {
|
||||
parsedComponentprops[key] = JSON.parse(componentProps[key] as string)
|
||||
} catch {
|
||||
parsedComponentprops[key] = componentProps[key]
|
||||
}
|
||||
```
|
||||
**Risk:** Silent JSON parse failures
|
||||
**Resolution:** Log parse errors, add validation
|
||||
**Effort:** Low (1-2 hours)
|
||||
|
||||
---
|
||||
|
||||
### 10. Inline Styles
|
||||
**Locations:** Multiple
|
||||
| File | Lines |
|
||||
|------|-------|
|
||||
| `dummies.tsx` | Multiple inline style objects |
|
||||
| `Editor.tsx` | Dynamic backgroundImage |
|
||||
|
||||
**Risk:** Not themeable, harder to maintain
|
||||
**Resolution:** Move to SCSS with CSS variables
|
||||
**Effort:** Medium (4-6 hours)
|
||||
|
||||
---
|
||||
|
||||
### 11. Missing Accessibility
|
||||
**Issue:** No ARIA labels, keyboard navigation incomplete
|
||||
| Component | Issue |
|
||||
|-----------|-------|
|
||||
| `TreeList` navigation | Keyboard not tested |
|
||||
| `Editor` dropdowns | No labels |
|
||||
| `FrameContent` | No landmarks |
|
||||
|
||||
**Resolution:** Add ARIA attributes
|
||||
**Effort:** Medium (6-8 hours)
|
||||
|
||||
---
|
||||
|
||||
### 12. Large Number of Dependencies
|
||||
**Location:** `package.json`
|
||||
**Issue:** 10+ direct dependencies + many peer dependencies
|
||||
```json
|
||||
"@lottiefiles/react-lottie-player",
|
||||
"@tanstack/react-table",
|
||||
"bootstrap",
|
||||
"d3",
|
||||
"highcharts",
|
||||
"highlight.js",
|
||||
"lottie-react",
|
||||
"lottie-web",
|
||||
"moment"
|
||||
```
|
||||
**Risk:** Large bundle size, dependency conflicts
|
||||
**Resolution:** Evaluate necessity, lazy load
|
||||
**Effort:** High (12-16 hours)
|
||||
|
||||
---
|
||||
|
||||
## 🟢 Low Priority
|
||||
|
||||
### 13. Outdated README
|
||||
**Location:** `README.md`
|
||||
**Issue:** Single line, no documentation
|
||||
**Resolution:** Update with proper documentation
|
||||
**Effort:** Low (2-3 hours)
|
||||
|
||||
---
|
||||
|
||||
### 14. Unused Navigator Mock
|
||||
**Location:** `src/dummies.tsx` (Lines ~5-13)
|
||||
```typescript
|
||||
const tnsNavigator: AppNavigatorDataType | undefined = {...}
|
||||
```
|
||||
**Issue:** Only partially used in `Tiles` dummy
|
||||
**Resolution:** Clean up or expand usage
|
||||
**Effort:** Low (1 hour)
|
||||
|
||||
---
|
||||
|
||||
### 15. Inconsistent Import Styles
|
||||
**Locations:** Various
|
||||
```typescript
|
||||
// Mixed patterns:
|
||||
import * as components from "@armco/shared-components"
|
||||
import { ErrorBoundary, Main, Modal } from "@armco/shared-components"
|
||||
```
|
||||
**Resolution:** Standardize import style
|
||||
**Effort:** Low (1-2 hours)
|
||||
|
||||
---
|
||||
|
||||
### 16. Editor SCSS Minimal
|
||||
**Location:** `src/Editor.scss`
|
||||
**Issue:** Very minimal styling (likely more inline)
|
||||
**Resolution:** Consolidate styles to SCSS
|
||||
**Effort:** Low (2-3 hours)
|
||||
|
||||
---
|
||||
|
||||
### 17. Version Pinning on CDN Scripts
|
||||
**Location:** `src/ComponentList.tsx`
|
||||
**Issue:** Specific versions in CDN URLs
|
||||
```typescript
|
||||
"https://cdnjs.cloudflare.com/ajax/libs/antd/5.21.4/antd.min.js"
|
||||
```
|
||||
**Risk:** Outdated versions, manual updates required
|
||||
**Resolution:** Use unpkg or dynamic version
|
||||
**Effort:** Low (2-3 hours)
|
||||
|
||||
---
|
||||
|
||||
## Debt Resolution Priority Matrix
|
||||
|
||||
| Priority | Items | Total Effort |
|
||||
|----------|-------|--------------|
|
||||
| 🔴 Critical | 3 items | 12-17 hours |
|
||||
| 🟠 High | 4 items | 23-34 hours |
|
||||
| 🟡 Medium | 5 items | 18-24 hours |
|
||||
| 🟢 Low | 5 items | 8-12 hours |
|
||||
|
||||
**Recommended Sprint 1 Focus:**
|
||||
1. Fix TypeScript any types in core files
|
||||
2. Fix ESLint disable comments
|
||||
3. Add error handling to CDN loading
|
||||
4. Fix "andtd" typo
|
||||
5. Remove TODO comment or document
|
||||
271
docs/DESIGN.md
Normal file
271
docs/DESIGN.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# components-viewer - Design Documentation
|
||||
|
||||
## Component Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ components-viewer Application │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ ComponentsViewer.tsx │ │
|
||||
│ │ (Main Container) │ │
|
||||
│ │ │ │
|
||||
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ DndProvider (react-dnd) │ │ │
|
||||
│ │ │ HTML5Backend (desktop) / TouchBackend (mobile) │ │ │
|
||||
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Main (Layout) │ │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ │ ┌──────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │ │ │
|
||||
│ │ │ │ Drawer │ │ Main Content │ │ Right Panel │ │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ │ ComponentList│ │ Editor │ │ (dynamic via │ │ │ │
|
||||
│ │ │ │ │ │ │ │ usePanelContent│ │ │ │
|
||||
│ │ │ │ ┌────────┐ │ │ ┌──────────────┐ │ │ │ │ │ │
|
||||
│ │ │ │ │TreeList│ │ │ │ Prop Tools │ │ │ │ │ │ │
|
||||
│ │ │ │ │ │ │ │ ├──────────────┤ │ │ │ │ │ │
|
||||
│ │ │ │ │ ├ Atom │ │ │ │ FrameContent │ │ │ │ │ │ │
|
||||
│ │ │ │ │ ├ Mol │ │ │ │ ┌────────┐ │ │ │ │ │ │ │
|
||||
│ │ │ │ │ └ Comp │ │ │ │ │Component│ │ │ │ │ │ │ │
|
||||
│ │ │ │ └────────┘ │ │ │ │ Preview │ │ │ │ │ │ │ │
|
||||
│ │ │ │ │ │ │ └────────┘ │ │ │ │ │ │ │
|
||||
│ │ │ └──────────────┘ │ └──────────────┘ │ └──────────────────┘ │ │ │
|
||||
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Modal (Overlay) │ │ │
|
||||
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: Component Selection
|
||||
|
||||
```
|
||||
User clicks TreeList item
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│handleComponent │
|
||||
│Select() │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ stringifyUrl() │────▶│ navigate() │
|
||||
│ Build URL with │ │ Update location │
|
||||
│ component+props │ │ │
|
||||
└─────────────────┘ └────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ useEffect on │
|
||||
│ location │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ findComponent │
|
||||
│ Description() │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ setSelectedComp │
|
||||
│ Definition() │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ FrameContent │
|
||||
│ renders comp │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: Prop Editing
|
||||
|
||||
```
|
||||
User selects dropdown/toggle
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ updateProps() │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ Create new │────▶│ stringifyUrl() │
|
||||
│ props object │ │ Build URL │
|
||||
└─────────────────┘ └────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ navigate() │
|
||||
│ location.search│
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼ (triggers useEffect)
|
||||
┌─────────────────┐
|
||||
│ Parse props │
|
||||
│ from URL │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Re-render with │
|
||||
│ new props │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: Library Loading
|
||||
|
||||
```
|
||||
User enters library name
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ loadComponents()│
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Check LIBS map │
|
||||
│ for loader fn │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────┴────┐
|
||||
▼ ▼
|
||||
┌────────┐ ┌────────────┐
|
||||
│import()│ │loadScript()│
|
||||
│ (npm) │ │ (CDN) │
|
||||
└───┬────┘ └─────┬──────┘
|
||||
│ │
|
||||
└─────┬──────┘
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Object.keys() │
|
||||
│ Get component │
|
||||
│ names │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ adaptToTree...()│
|
||||
│ Build tree data │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ setComponents() │
|
||||
│ Render TreeList │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature Completion Matrix
|
||||
|
||||
| Feature | Status | What's Done | What's Pending | Potential Additions |
|
||||
|---------|--------|-------------|----------------|---------------------|
|
||||
| **Component Tree** | ✅ Complete | Hierarchical navigation | - | Search/filter |
|
||||
| **Live Preview** | ✅ Complete | Component rendering | - | Multiple viewports |
|
||||
| **Prop Editing** | ✅ Complete | Dropdowns, toggles | - | All prop types |
|
||||
| **URL State** | ✅ Complete | Shareable URLs | - | Deep linking |
|
||||
| **Theme Toggle** | ✅ Complete | Light/Dark switch | - | Custom themes |
|
||||
| **Drag & Drop** | ✅ Complete | TreeList items | - | Drop zones |
|
||||
| **Error Boundary** | ✅ Complete | Crash protection | - | Error reporting |
|
||||
| **Tooltip Preview** | ✅ Complete | Hover preview | - | Larger preview |
|
||||
| **External Libs** | ⚠️ Partial | CDN loading | Error handling | More libraries |
|
||||
| **HOC Testing** | ✅ Complete | Children rendering | - | Slot customization |
|
||||
| **Background Test** | ✅ Complete | Image backgrounds | - | Color picker |
|
||||
| **Component Docs** | ❌ Missing | - | Inline documentation | JSDoc rendering |
|
||||
| **Code View** | ❌ Missing | - | Show JSX code | Copy to clipboard |
|
||||
| **Responsive Test** | ❌ Missing | - | Viewport simulation | Device presets |
|
||||
| **Storybook Export** | ❌ Missing | - | Stories generation | MDX export |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
components-viewer/
|
||||
├── src/
|
||||
│ ├── index.tsx # React entry point
|
||||
│ ├── ComponentsViewer.tsx # Main container
|
||||
│ ├── ComponentList.tsx # TreeList navigation
|
||||
│ ├── Editor.tsx # Preview workspace
|
||||
│ ├── Editor.scss # Editor styles
|
||||
│ ├── components.ts # Component configs (1167 lines)
|
||||
│ ├── dummies.tsx # Test data/children
|
||||
│ ├── helper.ts # Utility functions
|
||||
│ ├── types.ts # TypeScript types
|
||||
│ ├── types.d.ts # Type declarations
|
||||
│ ├── utils.ts # Additional utilities
|
||||
│ ├── react-app-env.d.ts # React types
|
||||
│ └── vite-env.d.ts # Vite types
|
||||
│
|
||||
├── build-tools/ # Build scripts
|
||||
│
|
||||
├── vite.config.ts # Library build
|
||||
├── vite-dev.config.ts # Dev server
|
||||
├── tsconfig.json # TypeScript config
|
||||
├── analyticsrc.json # Analytics config
|
||||
└── package.json # Package definition
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Configuration Schema
|
||||
|
||||
```typescript
|
||||
// Example from components.ts
|
||||
{
|
||||
name: "Button",
|
||||
props: ["size", "variant", "icon"],
|
||||
variants: {
|
||||
size: ["xsmall", "small", "medium", "large"],
|
||||
variant: [
|
||||
"primary", "secondary", "tertiary",
|
||||
"danger", "warning", "success",
|
||||
"info", "dark", "light",
|
||||
"link", "link-native", "link-hover"
|
||||
],
|
||||
content: ["Click me"],
|
||||
preIcon: ["io.IoMdHelp", "fa.FaSearch"],
|
||||
postIcon: ["io.IoMdHelp", "fa.FaCheckSquare"],
|
||||
splitOptions: [true, false],
|
||||
},
|
||||
uses: [
|
||||
{ name: "List", hierarchy: "ATOMS" },
|
||||
{ name: "PopoverV2", hierarchy: "ATOMS" },
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## State Management
|
||||
|
||||
components-viewer uses **local component state** primarily:
|
||||
|
||||
```typescript
|
||||
// ComponentList state
|
||||
const [components, setComponents] = useState<Array<string>>()
|
||||
|
||||
// Editor state
|
||||
const [selectedComponentDefinition, setSelectedComponentDefinition] =
|
||||
useState<FrameContentDefinition>()
|
||||
|
||||
// Theme (from context)
|
||||
const { theme, setTheme } = useTheme()
|
||||
```
|
||||
|
||||
URL acts as source of truth for component selection and props.
|
||||
234
docs/READINESS.md
Normal file
234
docs/READINESS.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# components-viewer - Production Readiness Checklist
|
||||
|
||||
## Overview
|
||||
|
||||
This document tracks production readiness for components-viewer as a component development tool and documentation platform for the Armco design system.
|
||||
|
||||
---
|
||||
|
||||
## 1. Build & Packaging
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| ESM Build | ✅ | `build/es/` output |
|
||||
| CJS Build | ✅ | `build/cjs/` output |
|
||||
| Type Definitions | ✅ | `build/types/` output |
|
||||
| CSS Injection | ✅ | Using `vite-plugin-lib-inject-css` |
|
||||
| Tree Shaking | ✅ | Configured in rollup |
|
||||
| External Dependencies | ✅ | Peer deps externalized |
|
||||
| Source Maps | ❌ | Not generated |
|
||||
| Bundle Size Analysis | ❌ | Not configured |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Enable source maps
|
||||
- [ ] Add bundle analysis to CI
|
||||
- [ ] Evaluate bundle size (many dependencies)
|
||||
|
||||
---
|
||||
|
||||
## 2. Code Quality
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| TypeScript Strict Mode | ⚠️ | Many `any` types |
|
||||
| ESLint Configured | ✅ | Via eslintConfig |
|
||||
| Prettier Configured | ✅ | Via prettier-config-nick |
|
||||
| No Console Statements | ✅ | No console.log found |
|
||||
| Error Boundaries | ✅ | Wrapping component previews |
|
||||
| PropTypes/Type Safety | ⚠️ | Some types missing |
|
||||
| ESLint Disable Comments | ❌ | Present in Editor.tsx |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Remove TypeScript `any` types
|
||||
- [ ] Fix ESLint disable comments
|
||||
- [ ] Add strict TypeScript mode
|
||||
|
||||
---
|
||||
|
||||
## 3. Testing
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Unit Tests | ❌ | 0% coverage |
|
||||
| Component Tests | ❌ | No tests |
|
||||
| Integration Tests | ❌ | No tests |
|
||||
| Visual Regression | ❌ | No Storybook self-tests |
|
||||
| Vitest Configured | ✅ | vitest in devDependencies |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Write tests for helper functions
|
||||
- [ ] Write tests for Editor prop parsing
|
||||
- [ ] Add component render tests
|
||||
|
||||
---
|
||||
|
||||
## 4. Accessibility
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Semantic HTML | ⚠️ | Basic structure |
|
||||
| ARIA Labels | ❌ | Missing throughout |
|
||||
| Keyboard Navigation | ⚠️ | TreeList partial |
|
||||
| Focus Management | ❌ | Not implemented |
|
||||
| Screen Reader Testing | ❌ | Not tested |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Add ARIA labels to interactive elements
|
||||
- [ ] Test keyboard navigation
|
||||
- [ ] Add skip links
|
||||
|
||||
---
|
||||
|
||||
## 5. Performance
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Code Splitting | ⚠️ | All components in one chunk |
|
||||
| Lazy Loading | ❌ | Components loaded eagerly |
|
||||
| Bundle Size | ⚠️ | Large due to many deps |
|
||||
| Memoization | ❌ | Minimal use |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Lazy load external libraries
|
||||
- [ ] Memoize component previews
|
||||
- [ ] Split component configs by category
|
||||
|
||||
---
|
||||
|
||||
## 6. Error Handling
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Error Boundaries | ✅ | Wrapping component preview |
|
||||
| CDN Load Errors | ❌ | No user feedback |
|
||||
| Component Errors | ✅ | Caught by boundary |
|
||||
| Network Errors | ❌ | No handling |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Add error UI for CDN failures
|
||||
- [ ] Add retry mechanism for external libs
|
||||
|
||||
---
|
||||
|
||||
## 7. Features Completeness
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Component Tree | ✅ | Working |
|
||||
| Live Preview | ✅ | Working |
|
||||
| Prop Editing | ✅ | Working |
|
||||
| Theme Toggle | ✅ | Working |
|
||||
| URL State | ✅ | Shareable URLs |
|
||||
| Drag & Drop | ✅ | Working |
|
||||
| External Libraries | ⚠️ | Limited, error-prone |
|
||||
| Documentation View | ❌ | Not implemented |
|
||||
| Code View | ❌ | Not implemented |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Improve external library loading
|
||||
- [ ] Add component documentation view
|
||||
- [ ] Add code snippet view
|
||||
|
||||
---
|
||||
|
||||
## 8. Documentation
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| README | ✅ | Comprehensive docs added |
|
||||
| API Documentation | ❌ | None |
|
||||
| Component Docs | ⚠️ | In components.ts (not rendered) |
|
||||
| Usage Examples | ✅ | Provided in README |
|
||||
| Changelog | ❌ | Not maintained |
|
||||
|
||||
### Actions Required:
|
||||
- [x] ~~Write comprehensive README~~ ✅ DONE
|
||||
- [ ] Add inline documentation rendering
|
||||
- [ ] Maintain CHANGELOG.md
|
||||
|
||||
---
|
||||
|
||||
## 9. Security
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| CDN Script Security | ⚠️ | No SRI hashes |
|
||||
| XSS Prevention | ⚠️ | Dynamic component rendering |
|
||||
| Dependency Audit | ⚠️ | Many dependencies |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Add SRI hashes to CDN scripts
|
||||
- [ ] Run npm audit fix
|
||||
- [ ] Review component rendering for XSS
|
||||
|
||||
---
|
||||
|
||||
## Production Readiness Score
|
||||
|
||||
| Category | Score | Max |
|
||||
|----------|-------|-----|
|
||||
| Build & Packaging | 5 | 8 |
|
||||
| Code Quality | 3 | 7 |
|
||||
| Testing | 0.5 | 5 |
|
||||
| Accessibility | 1 | 5 |
|
||||
| Performance | 1 | 5 |
|
||||
| Error Handling | 2 | 4 |
|
||||
| Features | 6 | 9 |
|
||||
| Documentation | 0.5 | 5 |
|
||||
| Security | 1 | 3 |
|
||||
| **Total** | **20** | **51** |
|
||||
|
||||
**Readiness Level: 39% - NOT READY FOR PRODUCTION**
|
||||
|
||||
---
|
||||
|
||||
## Minimum Viable Production Checklist
|
||||
|
||||
### Week 1: Critical Fixes
|
||||
- [ ] Fix TypeScript `any` types
|
||||
- [ ] Fix ESLint disable comments
|
||||
- [ ] Add CDN error handling
|
||||
- [ ] Fix "andtd" typo
|
||||
|
||||
### Week 2: Stability
|
||||
- [ ] Add unit tests for helpers
|
||||
- [ ] Improve CDN loading reliability
|
||||
- [ ] Add loading states for external libs
|
||||
|
||||
### Week 3: UX Improvements
|
||||
- [ ] Add error UI for failed loads
|
||||
- [ ] Add component search/filter
|
||||
- [ ] Improve TreeList keyboard navigation
|
||||
|
||||
### Week 4: Documentation
|
||||
- [ ] Update README
|
||||
- [ ] Add inline component docs view
|
||||
- [ ] Add code snippet display
|
||||
|
||||
---
|
||||
|
||||
## Use Case Evaluation
|
||||
|
||||
### Intended Uses
|
||||
|
||||
| Use Case | Readiness |
|
||||
|----------|-----------|
|
||||
| Internal component development | ✅ Ready |
|
||||
| Design system documentation | ⚠️ Partial |
|
||||
| Component showcase | ✅ Ready |
|
||||
| External library testing | ⚠️ Unreliable |
|
||||
| Production deployment | ❌ Not ready |
|
||||
|
||||
### Comparison with Alternatives
|
||||
|
||||
| Feature | components-viewer | Storybook | Docz |
|
||||
|---------|-------------------|-----------|------|
|
||||
| Live Preview | ✅ | ✅ | ✅ |
|
||||
| Prop Controls | ✅ | ✅ | ⚠️ |
|
||||
| Documentation | ❌ | ✅ | ✅ |
|
||||
| Addons | ❌ | ✅ | ⚠️ |
|
||||
| Setup Complexity | Low | High | Medium |
|
||||
| Bundle Size | Medium | Large | Small |
|
||||
|
||||
components-viewer is suitable for internal use and component development,
|
||||
but lacks documentation features for a production design system site.
|
||||
235
docs/SPECS.md
Normal file
235
docs/SPECS.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# components-viewer - Feature Specifications
|
||||
|
||||
## Overview
|
||||
|
||||
**components-viewer** is a React-based component development and testing environment for the Armco design system. It provides an interactive playground for viewing, testing, and exploring components with live prop editing, theme switching, and drag-and-drop support.
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Component | Technology | Version |
|
||||
|-----------|------------|---------|
|
||||
| UI Framework | React | 18/19 |
|
||||
| State Management | Redux Toolkit | 2.x |
|
||||
| Routing | react-router-dom | 6/7.x |
|
||||
| Build Tool | Vite | 7.x |
|
||||
| Styling | SCSS (Dart Sass) | 1.x |
|
||||
| Language | TypeScript | 5.x |
|
||||
| Drag & Drop | react-dnd | 16.x |
|
||||
| Charting | Highcharts | 11.x |
|
||||
| Animations | Lottie | 2.x/5.x |
|
||||
| Syntax Highlighting | highlight.js | 11.x |
|
||||
|
||||
---
|
||||
|
||||
## Exported Components
|
||||
|
||||
| Component | Description | Export Path |
|
||||
|-----------|-------------|-------------|
|
||||
| `ComponentsViewer` | Main application container | `@armco/components-viewer` (default) |
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### 1. Component Viewer (`ComponentsViewer.tsx`)
|
||||
|
||||
**Description:** Main container providing the component exploration environment
|
||||
|
||||
**Layout:**
|
||||
- Left drawer: Component list (TreeList)
|
||||
- Main content: Component editor/preview
|
||||
- Right panel: Additional content (via usePanelContent hook)
|
||||
- Modal: Dialog overlay
|
||||
|
||||
**Key Features:**
|
||||
- DndProvider wrapping for drag-and-drop
|
||||
- Mobile/Desktop backend detection
|
||||
- Error boundaries for safe rendering
|
||||
|
||||
---
|
||||
|
||||
### 2. Component List (`ComponentList.tsx`)
|
||||
|
||||
**Description:** Hierarchical tree view of available components
|
||||
|
||||
**Features:**
|
||||
- TreeList navigation with expandable nodes
|
||||
- Component variants as child nodes
|
||||
- Library input for loading external libs
|
||||
- Drag-and-drop items
|
||||
- Custom tooltips with live component preview
|
||||
|
||||
**Library Loading:**
|
||||
- `@armco/components` - Default library
|
||||
- `antd` - Via CDN
|
||||
- `material` - Via CDN
|
||||
- `ng-bootstrap` - Via CDN
|
||||
- `react-bootstrap` - Via CDN
|
||||
|
||||
---
|
||||
|
||||
### 3. Editor (`Editor.tsx`)
|
||||
|
||||
**Description:** Component preview and prop editing workspace
|
||||
|
||||
**Features:**
|
||||
- Live component rendering
|
||||
- URL-based prop state (query params)
|
||||
- Variant dropdown selectors
|
||||
- Boolean prop toggles
|
||||
- Theme switcher (Light/Dark)
|
||||
- Background image support for testing
|
||||
- HOC children rendering
|
||||
|
||||
**Prop Editing:**
|
||||
- Dropdowns for enumerated variants
|
||||
- Toggles for boolean props
|
||||
- URL synchronization for shareable states
|
||||
|
||||
---
|
||||
|
||||
### 4. Component Configuration (`components.ts`)
|
||||
|
||||
**Description:** 1167+ line configuration file defining all testable components
|
||||
|
||||
**Configuration Per Component:**
|
||||
```typescript
|
||||
interface ComponentDescription {
|
||||
name: string // Component name
|
||||
type?: string // "HOC" for wrapper components
|
||||
children?: string[] // Child slots for HOCs
|
||||
props?: string[] // Configurable props
|
||||
variants?: { // Prop value options
|
||||
[prop: string]: (string | boolean | number)[]
|
||||
}
|
||||
test?: object // Test-specific data
|
||||
uses?: Array<{ // Component dependencies
|
||||
name: string
|
||||
hierarchy: string
|
||||
}>
|
||||
}
|
||||
```
|
||||
|
||||
**Configured Components (Partial List):**
|
||||
- Accordion, AdvancedColorPicker, Alert, Avatar
|
||||
- Badge, Breadcrumb, Button
|
||||
- Calendar, Carousel, Checkbox, ColorPicker, ContextMenu
|
||||
- DateInput, DatePicker, DateRangePicker
|
||||
- Dropdown, Toggle, Modal, Popover
|
||||
- Table, TreeList, Pagination
|
||||
- Charts (ArViz), Loaders, and many more
|
||||
|
||||
---
|
||||
|
||||
### 5. Dummy Data (`dummies.tsx`)
|
||||
|
||||
**Description:** Mock data for component testing
|
||||
|
||||
**Provided Dummies:**
|
||||
- `Accordion` - Sample accordion data
|
||||
- `ArViz` - Chart data points
|
||||
- `Tiles` - Navigation data
|
||||
- `ProductDescriptionTile` - Product info
|
||||
|
||||
**Child Dummies:**
|
||||
- `bg` - Background div
|
||||
- `content` - Popover content slot
|
||||
- `popover` - Popover slot
|
||||
- `list` - Grid list items
|
||||
- `anchor` - Button anchor
|
||||
|
||||
---
|
||||
|
||||
## Route Structure
|
||||
|
||||
| Route Pattern | Description |
|
||||
|---------------|-------------|
|
||||
| `/components/:componentName` | View specific component |
|
||||
| `/components/:componentName?prop1=value` | With prop overrides |
|
||||
|
||||
---
|
||||
|
||||
## Peer Dependencies
|
||||
|
||||
```json
|
||||
{
|
||||
"@armco/components": "^0.0.60",
|
||||
"@armco/configs": "^0.0.11",
|
||||
"@armco/types": "^0.0.18",
|
||||
"@armco/utils": "^0.0.29",
|
||||
"@reduxjs/toolkit": "^1.8.1",
|
||||
"react": "^18.2.0",
|
||||
"react-bootstrap": "^2.7.4",
|
||||
"react-dnd": ">=16.0.0",
|
||||
"react-dnd-html5-backend": ">=16.0.0",
|
||||
"react-dnd-touch-backend": ">=16.0.0",
|
||||
"react-draggable": "^4.4.6",
|
||||
"react-redux": "^8.0.1",
|
||||
"react-resizable": "^3.0.5",
|
||||
"react-router-dom": "^6.13.0",
|
||||
"resize-observer-polyfill": "^1.5.1"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Direct Dependencies
|
||||
|
||||
```json
|
||||
{
|
||||
"@lottiefiles/react-lottie-player": "^3.5.3",
|
||||
"@tanstack/react-table": "^8.21.2",
|
||||
"bootstrap": "^5.3.8",
|
||||
"d3": "^7.9.0",
|
||||
"highcharts": "^11.2.0",
|
||||
"highcharts-react-official": "^3.2.1",
|
||||
"highlight.js": "^11.8.0",
|
||||
"lottie-react": "^2.4.0",
|
||||
"lottie-web": "^5.12.2",
|
||||
"moment": "^2.29.4"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Output
|
||||
|
||||
```
|
||||
build/
|
||||
├── cjs/ # CommonJS modules
|
||||
│ └── ComponentsViewer.js # Main entry
|
||||
├── es/ # ES modules
|
||||
│ └── ComponentsViewer.js # Main entry
|
||||
└── types/ # TypeScript declarations
|
||||
└── ComponentsViewer.d.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scripts
|
||||
|
||||
| Script | Description |
|
||||
|--------|-------------|
|
||||
| `pnpm dev` | Start development server |
|
||||
| `pnpm start` | Start production server |
|
||||
| `pnpm build` | Build for deployment |
|
||||
| `pnpm test` | Run Vitest tests |
|
||||
| `pnpm lint` | Run ESLint |
|
||||
| `pnpm generate` | Run Plop generators |
|
||||
| `pnpm atom` | Generate atom component |
|
||||
| `pnpm molecule` | Generate molecule component |
|
||||
| `pnpm component` | Generate component |
|
||||
| `pnpm page` | Generate page |
|
||||
|
||||
---
|
||||
|
||||
## Configuration Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `vite.config.ts` | Library build configuration |
|
||||
| `vite-dev.config.ts` | Development server |
|
||||
| `tsconfig.json` | TypeScript configuration |
|
||||
| `analyticsrc.json` | Analytics configuration |
|
||||
Reference in New Issue
Block a user