From 8a8b6ba71f7f9b078471010d586ec1b07ad28a7a Mon Sep 17 00:00:00 2001 From: mohiit1502 Date: Sun, 4 Jan 2026 20:38:02 +0530 Subject: [PATCH] chore: add comprehensive documentation - Add docs/SPECS.md, DESIGN.md, DEBT.md, READINESS.md - Update README.md with comprehensive documentation --- README.md | 129 +++++++++++++++++++++- docs/DEBT.md | 244 +++++++++++++++++++++++++++++++++++++++++ docs/DESIGN.md | 271 ++++++++++++++++++++++++++++++++++++++++++++++ docs/READINESS.md | 234 +++++++++++++++++++++++++++++++++++++++ docs/SPECS.md | 235 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 1112 insertions(+), 1 deletion(-) create mode 100644 docs/DEBT.md create mode 100644 docs/DESIGN.md create mode 100644 docs/READINESS.md create mode 100644 docs/SPECS.md diff --git a/README.md b/README.md index b24d5e3..eaff764 100644 --- a/README.md +++ b/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 \ No newline at end of file +# @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 ( + + + + + + ) +} +``` + +## 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 diff --git a/docs/DEBT.md b/docs/DEBT.md new file mode 100644 index 0000000..93d2fc8 --- /dev/null +++ b/docs/DEBT.md @@ -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 } = { + "@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 diff --git a/docs/DESIGN.md b/docs/DESIGN.md new file mode 100644 index 0000000..9a28f96 --- /dev/null +++ b/docs/DESIGN.md @@ -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>() + +// Editor state +const [selectedComponentDefinition, setSelectedComponentDefinition] = + useState() + +// Theme (from context) +const { theme, setTheme } = useTheme() +``` + +URL acts as source of truth for component selection and props. diff --git a/docs/READINESS.md b/docs/READINESS.md new file mode 100644 index 0000000..138d49b --- /dev/null +++ b/docs/READINESS.md @@ -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. diff --git a/docs/SPECS.md b/docs/SPECS.md new file mode 100644 index 0000000..1e19ad3 --- /dev/null +++ b/docs/SPECS.md @@ -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 |