chore: add comprehensive documentation
All checks were successful
armco-org/font-spot/pipeline/head This commit was not built
All checks were successful
armco-org/font-spot/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:
95
README.md
95
README.md
@@ -1 +1,94 @@
|
||||
# Armco Template for the tech stack: React, TS, Dart Sass, Redux Tookkit, react-redux, react browser routing, TS based plop generator
|
||||
# @armco/font-spot
|
||||
|
||||
> Font Browser UI for Armco Platform
|
||||
|
||||
font-spot is a React-based font browser that provides browsing, searching, and previewing capabilities for fonts served by ArmoryStatic.
|
||||
|
||||
## Features
|
||||
|
||||
- **Font Grid**: Visual font browser with live preview
|
||||
- **Search**: Text search with debounce
|
||||
- **Pagination**: Page-based navigation
|
||||
- **Live Preview**: Fonts render in their own typeface
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pnpm add @armco/font-spot
|
||||
```
|
||||
|
||||
## Peer Dependencies
|
||||
|
||||
```json
|
||||
{
|
||||
"@armco/components": "^0.0.60",
|
||||
"@armco/configs": "^0.0.11",
|
||||
"@armco/types": "^0.0.18",
|
||||
"@armco/utils": "^0.0.29",
|
||||
"react": "^18.2.0",
|
||||
"react-dom": "^18.2.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```tsx
|
||||
import Fonts from "@armco/font-spot"
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<div className="h-100">
|
||||
<Fonts />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Exported Components
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `Fonts` | Main font browser container |
|
||||
| `FontsList` | Font grid with search and pagination |
|
||||
| `FontTile` | Individual font preview card |
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Start development server
|
||||
pnpm dev
|
||||
|
||||
# Build library
|
||||
pnpm build
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── Fonts.tsx # Main container
|
||||
├── FontsList.tsx # Font grid
|
||||
├── FontTile.tsx # Font card
|
||||
└── types.ts # TypeScript types
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. On mount, fetches font list from ArmoryStatic `/font/page` endpoint
|
||||
2. Response includes font names and `@font-face` CSS rules
|
||||
3. CSS is injected into document head as `<style>` element
|
||||
4. Each font tile displays the font name in its own typeface
|
||||
|
||||
## 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
|
||||
|
||||
234
docs/DEBT.md
Normal file
234
docs/DEBT.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# font-spot - Technical Debt Register
|
||||
|
||||
## 🔴 Critical (Must Fix Before Production)
|
||||
|
||||
### 1. Console.error in Production Code
|
||||
**Location:** `src/FontsList.tsx` (Line ~50)
|
||||
**Issue:** Error logged to console
|
||||
```typescript
|
||||
.catch((error) => {
|
||||
console.error(error)
|
||||
setLoading(false)
|
||||
})
|
||||
```
|
||||
**Risk:** Pollutes browser console, exposes internal errors
|
||||
**Resolution:** Replace with proper error handling UI
|
||||
**Effort:** Low (1-2 hours)
|
||||
|
||||
---
|
||||
|
||||
### 2. No Error State or User Feedback
|
||||
**Location:** `src/FontsList.tsx`
|
||||
**Issue:** API errors silently swallowed, user sees no feedback
|
||||
**Current behavior:** Loading stops, empty grid shown
|
||||
**Risk:** Poor user experience, silent failures
|
||||
**Resolution:** Add error state and error message component
|
||||
**Effort:** Low (2-3 hours)
|
||||
|
||||
---
|
||||
|
||||
### 3. Memory Leak: Style Elements Not Cleaned Up
|
||||
**Location:** `src/FontsList.tsx` (Lines ~42-47)
|
||||
**Issue:** New `<style>` element appended on every fetch
|
||||
```typescript
|
||||
const styleElement = document.createElement("style")
|
||||
styleElement.type = "text/css"
|
||||
styleElement.appendChild(document.createTextNode(content.returnFontGroups))
|
||||
document.head.appendChild(styleElement)
|
||||
```
|
||||
**Risk:** Multiple style elements accumulate, causing memory leak
|
||||
**Resolution:** Track and replace previous style element or use ID
|
||||
**Effort:** Low (1-2 hours)
|
||||
|
||||
---
|
||||
|
||||
## 🟠 High Priority
|
||||
|
||||
### 4. Compact Toggle Non-Functional
|
||||
**Location:** `src/FontsList.tsx` (Lines ~85-89)
|
||||
**Issue:** Toggle exists but does nothing
|
||||
```tsx
|
||||
<Toggle
|
||||
onChange={() => { }}
|
||||
toggleOnName="Compact"
|
||||
toggleOffName="Compact"
|
||||
/>
|
||||
```
|
||||
**Risk:** Misleading UI, broken user expectation
|
||||
**Resolution:** Implement compact view or remove toggle
|
||||
**Effort:** Medium (4-6 hours)
|
||||
|
||||
---
|
||||
|
||||
### 5. Upload Button Non-Functional
|
||||
**Location:** `src/FontsList.tsx` (Lines ~80-84)
|
||||
**Issue:** Upload button has no handler
|
||||
```tsx
|
||||
<Button
|
||||
content="Upload"
|
||||
variant={ArButtonVariants.SUCCESS}
|
||||
// No onClick
|
||||
/>
|
||||
```
|
||||
**Risk:** Broken user expectation
|
||||
**Resolution:** Implement upload or remove button
|
||||
**Effort:** High (16+ hours to implement fully)
|
||||
|
||||
---
|
||||
|
||||
### 6. Commented Code
|
||||
**Location:** `src/FontsList.tsx` (Lines ~100-110, 130-135)
|
||||
**Issue:** Dead commented code left in file
|
||||
```typescript
|
||||
// fonts
|
||||
// ? fonts.map(
|
||||
// (font): SearchItem => ({
|
||||
// label: font.name,
|
||||
// data: font,
|
||||
// }),
|
||||
// )
|
||||
// : []
|
||||
|
||||
// trigger={ArPageTriggers.SCROLL}
|
||||
// dataFetcher={(load, count) =>
|
||||
// fetchIconsPage(load, count, {}, setIcons, setPage, setLoading)
|
||||
// }
|
||||
```
|
||||
**Risk:** Code confusion, references wrong function name (`fetchIconsPage`)
|
||||
**Resolution:** Remove or complete implementation
|
||||
**Effort:** Low (30 minutes)
|
||||
|
||||
---
|
||||
|
||||
### 7. Search Autocomplete Disabled
|
||||
**Location:** `src/FontsList.tsx` (Line ~100)
|
||||
**Issue:** Search items hardcoded to empty array
|
||||
```typescript
|
||||
items={[]}
|
||||
```
|
||||
**Risk:** Inconsistent UX compared to icon-spot
|
||||
**Resolution:** Enable font name suggestions
|
||||
**Effort:** Low (2-3 hours)
|
||||
|
||||
---
|
||||
|
||||
## 🟡 Medium Priority
|
||||
|
||||
### 8. No Unit Tests
|
||||
**Issue:** 0% test coverage
|
||||
**Files needing tests:**
|
||||
- `FontsList.tsx` - Fetch logic, pagination
|
||||
- `FontTile.tsx` - Rendering
|
||||
|
||||
**Resolution:** Add Vitest tests
|
||||
**Effort:** Medium (8-12 hours)
|
||||
|
||||
---
|
||||
|
||||
### 9. Inconsistent Initial Fetch Sizes
|
||||
**Location:** `src/FontsList.tsx`
|
||||
**Issue:** Different page sizes for initial vs search
|
||||
```typescript
|
||||
// Initial load
|
||||
fetchFontsPage(30, 0, filters, ...)
|
||||
|
||||
// On search
|
||||
fetchFontsPage(200, 0, filters, ...)
|
||||
```
|
||||
**Risk:** Inconsistent behavior
|
||||
**Resolution:** Use consistent pagination logic
|
||||
**Effort:** Low (1-2 hours)
|
||||
|
||||
---
|
||||
|
||||
### 10. Missing TypeScript Strictness
|
||||
**Location:** `src/types.ts`
|
||||
**Issue:** Props interfaces too minimal
|
||||
```typescript
|
||||
export interface FontTileProps {
|
||||
font: string // Should include optional handlers
|
||||
}
|
||||
```
|
||||
**Resolution:** Add onClick, onFavorite, etc.
|
||||
**Effort:** Low (1-2 hours)
|
||||
|
||||
---
|
||||
|
||||
### 11. No Loading Skeleton
|
||||
**Issue:** Only spinner shown during load
|
||||
**Current:** Full-page loader
|
||||
**Resolution:** Add skeleton tiles matching grid layout
|
||||
**Effort:** Low (2-3 hours)
|
||||
|
||||
---
|
||||
|
||||
### 12. No Font Detail View
|
||||
**Issue:** Clicking font tile does nothing useful
|
||||
**Current:** Cursor pointer but no action
|
||||
**Resolution:** Navigate to detail page or open modal
|
||||
**Effort:** Medium (8-12 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. Duplicate Background-Color in SCSS
|
||||
**Location:** `src/FontsList.component.scss`
|
||||
**Issue:** Duplicate property
|
||||
```scss
|
||||
.ar-FontsList__header-search-upload {
|
||||
background-color: var(--ar-bg); // ← First
|
||||
color: var(--ar-colora);
|
||||
background-color: var(--ar-bg-base); // ← Duplicate
|
||||
}
|
||||
```
|
||||
**Resolution:** Remove duplicate
|
||||
**Effort:** Low (5 minutes)
|
||||
|
||||
---
|
||||
|
||||
### 15. Missing key Prop
|
||||
**Location:** `src/FontsList.tsx` (Line ~120)
|
||||
**Issue:** React key warning
|
||||
```tsx
|
||||
{(page as Array<string>).map((font) => (
|
||||
<FontTile font={font} /> // Missing key={font}
|
||||
))}
|
||||
```
|
||||
**Resolution:** Add key prop
|
||||
**Effort:** Low (5 minutes)
|
||||
|
||||
---
|
||||
|
||||
### 16. Fixed Tile Size
|
||||
**Location:** `src/FontTile.component.scss`
|
||||
**Issue:** Hardcoded 8rem × 8rem size
|
||||
**Resolution:** Make configurable via props
|
||||
**Effort:** Low (1-2 hours)
|
||||
|
||||
---
|
||||
|
||||
## Debt Resolution Priority Matrix
|
||||
|
||||
| Priority | Items | Total Effort |
|
||||
|----------|-------|--------------|
|
||||
| 🔴 Critical | 3 items | 4-7 hours |
|
||||
| 🟠 High | 4 items | 23-28 hours |
|
||||
| 🟡 Medium | 5 items | 20-31 hours |
|
||||
| 🟢 Low | 4 items | 5-8 hours |
|
||||
|
||||
**Recommended Sprint 1 Focus:**
|
||||
1. Fix style element memory leak
|
||||
2. Add error state and user feedback
|
||||
3. Remove console.error
|
||||
4. Add missing key prop
|
||||
5. Remove or implement compact toggle
|
||||
6. Remove commented code
|
||||
175
docs/DESIGN.md
Normal file
175
docs/DESIGN.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# font-spot - Design Documentation
|
||||
|
||||
## Component Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ font-spot Application │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Fonts.tsx │ │
|
||||
│ │ (Container Component) │ │
|
||||
│ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Main (Layout) │ │ │
|
||||
│ │ │ from @armco/shared-components │ │ │
|
||||
│ │ └───────────────────────────────┬──────────────────────────────────────┘ │ │
|
||||
│ └──────────────────────────────────┼─────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ FontsList.tsx │ │
|
||||
│ │ (List Component) │ │
|
||||
│ │ │ │
|
||||
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Header Section │ │ │
|
||||
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │
|
||||
│ │ │ │ Upload │ │ Toggle │ │ SearchField │ │ │ │
|
||||
│ │ │ │ Button │ │ (Compact) │ │ │ │ │ │
|
||||
│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │
|
||||
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Font Tile Container │ │ │
|
||||
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │
|
||||
│ │ │ │ FontTile │ │ FontTile │ │ FontTile │ │ FontTile │ │ FontTile │ │ │ │
|
||||
│ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │
|
||||
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Pagination │ │ │
|
||||
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: Font Loading
|
||||
|
||||
```
|
||||
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||
│ Component │────▶│ API Call │────▶│ ArmoryStatic │
|
||||
│ Mount │ │ get() │ │ Backend │
|
||||
└───────────────┘ └───────────────┘ └───────┬───────┘
|
||||
│
|
||||
┌──────────────────────────────┘
|
||||
▼
|
||||
┌───────────────────────────────────────────────┐
|
||||
│ Response Processing │
|
||||
│ 1. Parse JSON body │
|
||||
│ 2. Extract fontNames[] │
|
||||
│ 3. Extract returnFontGroups (CSS) │
|
||||
└───────────────────┬───────────────────────────┘
|
||||
│
|
||||
┌───────────────────┴───────────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐
|
||||
│ Create <style>│ │ setFonts() │
|
||||
│ element with │ │ setPage() │
|
||||
│ @font-face │ │ │
|
||||
└───────┬───────┘ └───────┬───────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐
|
||||
│ Append to │ │ Render │
|
||||
│ document.head │ │ FontTile x N │
|
||||
└───────────────┘ └───────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: Search
|
||||
|
||||
```
|
||||
User types in SearchField
|
||||
│
|
||||
▼ (debounce 1000ms)
|
||||
┌─────────────────┐
|
||||
│ setSearchText() │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ useEffect │────▶│ fetchFontsPage │
|
||||
│ (searchText) │ │ with filter │
|
||||
└─────────────────┘ └────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Update fonts │
|
||||
│ Update page │
|
||||
│ Inject CSS │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature Completion Matrix
|
||||
|
||||
| Feature | Status | What's Done | What's Pending | Potential Additions |
|
||||
|---------|--------|-------------|----------------|---------------------|
|
||||
| **Font Grid** | ✅ Complete | Display with live preview | - | Configurable tile size |
|
||||
| **Search** | ✅ Complete | Debounced text search | - | Fuzzy matching |
|
||||
| **Pagination** | ✅ Complete | Page controls | Scroll pagination | Infinite scroll |
|
||||
| **Compact View** | ❌ Stub | Toggle UI exists | Toggle logic | Grid layout change |
|
||||
| **Upload** | ❌ Stub | Button exists | Upload flow | Font validation |
|
||||
| **Font Preview** | ⚠️ Basic | Font name in font | Sample text | Full specimen |
|
||||
| **Font Details** | ❌ Missing | - | Detail page | Styles, weights, glyphs |
|
||||
| **Font Download** | ❌ Missing | - | Download link | Format selection |
|
||||
| **Favorites** | ❌ Missing | - | Everything | Persistence |
|
||||
| **Categories** | ❌ Missing | - | Category API | Sidebar filter |
|
||||
| **Font Styles** | ❌ Missing | - | Style variants | Weight/style selector |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
font-spot/
|
||||
├── src/
|
||||
│ ├── Fonts.tsx # Main container
|
||||
│ ├── FontsList.tsx # Font grid with pagination
|
||||
│ ├── FontsList.component.scss # Grid styles
|
||||
│ ├── FontTile.tsx # Font preview card
|
||||
│ ├── FontTile.component.scss # Card styles
|
||||
│ ├── types.ts # TypeScript types
|
||||
│ ├── Test.tsx # Development test
|
||||
│ ├── react-app-env.d.ts # React types
|
||||
│ └── vite-env.d.ts # Vite types
|
||||
│
|
||||
├── build-tools/
|
||||
│ └── build.sh # Build script
|
||||
│
|
||||
├── vite.config.ts # Library build config
|
||||
├── vite-dev.config.ts # Dev server config
|
||||
├── vite-run.config.ts # Standalone run config
|
||||
├── tsconfig.json # TypeScript config
|
||||
└── package.json # Package definition
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Props Summary
|
||||
|
||||
| Component | Props |
|
||||
|-----------|-------|
|
||||
| `Fonts` | None (self-contained) |
|
||||
| `FontsList` | `classes?` |
|
||||
| `FontTile` | `font: string` |
|
||||
|
||||
---
|
||||
|
||||
## State Management
|
||||
|
||||
Unlike icon-spot, font-spot uses **local component state only**:
|
||||
|
||||
```typescript
|
||||
// FontsList.tsx state
|
||||
const [searchText, setSearchText] = useState<string>()
|
||||
const [fonts, setFonts] = useState<ArrayType>() // All fonts
|
||||
const [page, setPage] = useState<ArrayType>() // Current page
|
||||
const [loading, setLoading] = useState<boolean>()
|
||||
```
|
||||
|
||||
No Redux store is required for font-spot.
|
||||
234
docs/READINESS.md
Normal file
234
docs/READINESS.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# font-spot - Production Readiness Checklist
|
||||
|
||||
## Overview
|
||||
|
||||
This document tracks production readiness for font-spot as a standalone application and as an npm package consumed by other Armco applications.
|
||||
|
||||
---
|
||||
|
||||
## 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 | ✅ | React, armco libs externalized |
|
||||
| Source Maps | ❌ | Not generated |
|
||||
| Bundle Size Analysis | ❌ | Not configured |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Enable source maps for debugging
|
||||
- [ ] Add bundle size monitoring
|
||||
|
||||
---
|
||||
|
||||
## 2. Code Quality
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| TypeScript Strict Mode | ⚠️ | Minimal types |
|
||||
| ESLint Configured | ✅ | Via eslintConfig in package.json |
|
||||
| Prettier Configured | ✅ | Using prettier-config-nick |
|
||||
| No Console Statements | ❌ | console.error in code |
|
||||
| Error Boundaries | ❌ | No error boundaries |
|
||||
| PropTypes/Type Safety | ⚠️ | Basic types only |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Remove console.error statements
|
||||
- [ ] Add error handling
|
||||
- [ ] Enhance TypeScript types
|
||||
|
||||
---
|
||||
|
||||
## 3. Testing
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Unit Tests | ❌ | 0% coverage |
|
||||
| Component Tests | ❌ | No tests |
|
||||
| Integration Tests | ❌ | No tests |
|
||||
| Visual Regression | ❌ | No Storybook |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Add Vitest configuration
|
||||
- [ ] Write component tests
|
||||
- [ ] Consider Storybook setup
|
||||
|
||||
---
|
||||
|
||||
## 4. Accessibility
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Semantic HTML | ⚠️ | Basic div structure |
|
||||
| ARIA Labels | ❌ | Missing |
|
||||
| Keyboard Navigation | ❌ | Not implemented |
|
||||
| Screen Reader Testing | ❌ | Not tested |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Add ARIA labels
|
||||
- [ ] Implement keyboard navigation for grid
|
||||
- [ ] Test with screen reader
|
||||
|
||||
---
|
||||
|
||||
## 5. Performance
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Lazy Loading | ❌ | Not implemented |
|
||||
| Virtual Scrolling | ❌ | All fonts rendered |
|
||||
| Memoization | ❌ | No useMemo/useCallback |
|
||||
| Memory Leaks | 🔴 | Style elements accumulate |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Fix style element memory leak
|
||||
- [ ] Implement virtual scrolling
|
||||
- [ ] Add React.memo to FontTile
|
||||
|
||||
---
|
||||
|
||||
## 6. Error Handling
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| API Error Handling | ❌ | Errors swallowed |
|
||||
| User Error Messages | ❌ | No error UI |
|
||||
| Retry Logic | ❌ | No retry |
|
||||
| Loading States | ⚠️ | Basic spinner |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Add error state to component
|
||||
- [ ] Display error messages to user
|
||||
- [ ] Add retry button
|
||||
|
||||
---
|
||||
|
||||
## 7. Features Completeness
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Font Grid | ✅ | Working |
|
||||
| Search | ✅ | Working |
|
||||
| Pagination | ✅ | Working |
|
||||
| Compact View | ❌ | UI only, not functional |
|
||||
| Upload | ❌ | Button only |
|
||||
| Font Details | ❌ | Not implemented |
|
||||
| Download | ❌ | Not implemented |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Remove non-functional UI elements
|
||||
- [ ] Or implement missing features
|
||||
|
||||
---
|
||||
|
||||
## 8. Documentation
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| README | ✅ | Comprehensive docs added |
|
||||
| API Documentation | ❌ | None |
|
||||
| Usage Examples | ✅ | Provided in README |
|
||||
| Changelog | ❌ | Not maintained |
|
||||
|
||||
### Actions Required:
|
||||
- [x] ~~Write comprehensive README~~ ✅ DONE
|
||||
- [ ] Add JSDoc comments
|
||||
- [ ] Maintain CHANGELOG.md
|
||||
|
||||
---
|
||||
|
||||
## 9. Security
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| XSS Prevention | ⚠️ | Dynamic CSS injection |
|
||||
| Dependency Audit | ⚠️ | Needs npm audit |
|
||||
| CORS Handling | ⚠️ | Backend configured |
|
||||
|
||||
### Actions Required:
|
||||
- [ ] Validate CSS content before injection
|
||||
- [ ] Run npm audit fix
|
||||
|
||||
---
|
||||
|
||||
## Production Readiness Score
|
||||
|
||||
| Category | Score | Max |
|
||||
|----------|-------|-----|
|
||||
| Build & Packaging | 5 | 8 |
|
||||
| Code Quality | 2 | 6 |
|
||||
| Testing | 0 | 4 |
|
||||
| Accessibility | 0.5 | 4 |
|
||||
| Performance | 0 | 4 |
|
||||
| Error Handling | 0.5 | 4 |
|
||||
| Features | 3 | 7 |
|
||||
| Documentation | 0 | 4 |
|
||||
| Security | 1 | 3 |
|
||||
| **Total** | **12** | **44** |
|
||||
|
||||
**Readiness Level: 27% - NOT READY FOR PRODUCTION**
|
||||
|
||||
---
|
||||
|
||||
## Minimum Viable Production Checklist
|
||||
|
||||
### Week 1: Critical Fixes
|
||||
- [ ] Fix style element memory leak
|
||||
- [ ] Add error state and user feedback
|
||||
- [ ] Remove console.error
|
||||
- [ ] Add missing React key prop
|
||||
|
||||
### Week 2: UI Cleanup
|
||||
- [ ] Remove non-functional compact toggle
|
||||
- [ ] Remove non-functional upload button
|
||||
- [ ] Or implement them
|
||||
- [ ] Remove commented code
|
||||
|
||||
### Week 3: UX Improvements
|
||||
- [ ] Add loading skeletons
|
||||
- [ ] Enable search autocomplete
|
||||
- [ ] Add font click action
|
||||
|
||||
### Week 4: Documentation & Testing
|
||||
- [ ] Update README
|
||||
- [ ] Add basic component tests
|
||||
- [ ] Run npm audit
|
||||
|
||||
---
|
||||
|
||||
## Package Consumption Checklist
|
||||
|
||||
For apps consuming `@armco/font-spot`:
|
||||
|
||||
| Requirement | Provided |
|
||||
|-------------|----------|
|
||||
| Peer dependencies documented | ✅ |
|
||||
| Type definitions | ✅ |
|
||||
| CSS bundled | ✅ |
|
||||
| Tree-shakeable | ✅ |
|
||||
| No Redux required | ✅ |
|
||||
| No Router required | ✅ |
|
||||
|
||||
### Integration Requirements:
|
||||
1. Configure ArmoryStatic API endpoint in environment
|
||||
2. Ensure `@armco/configs` has STATIC_HOST configured
|
||||
3. Include in React application tree
|
||||
|
||||
---
|
||||
|
||||
## Comparison with icon-spot
|
||||
|
||||
| Aspect | font-spot | icon-spot |
|
||||
|--------|-----------|-----------|
|
||||
| Components | 3 | 12+ |
|
||||
| Redux | No | Yes |
|
||||
| Features | Basic | Extensive |
|
||||
| Test Coverage | 0% | 0% |
|
||||
| Readiness | 27% | 25% |
|
||||
| Complexity | Low | High |
|
||||
|
||||
font-spot is simpler and requires less setup, but also has fewer features.
|
||||
174
docs/SPECS.md
Normal file
174
docs/SPECS.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# font-spot - Feature Specifications
|
||||
|
||||
## Overview
|
||||
|
||||
**font-spot** is a React-based font browser application for the Armco platform. It provides a visual interface for browsing, searching, and previewing fonts served by the ArmoryStatic backend.
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Component | Technology | Version |
|
||||
|-----------|------------|---------|
|
||||
| UI Framework | React | 18/19 |
|
||||
| Build Tool | Vite | 7.x |
|
||||
| Styling | SCSS (Dart Sass) | 1.x |
|
||||
| Language | TypeScript | 5.x |
|
||||
| Package Format | ESM + CJS | - |
|
||||
|
||||
---
|
||||
|
||||
## Exported Components
|
||||
|
||||
| Component | Description | Export Path |
|
||||
|-----------|-------------|-------------|
|
||||
| `Fonts` | Main font browser container | `@armco/font-spot` (default) |
|
||||
| `FontsList` | Font grid with search and pagination | `@armco/font-spot/FontsList` |
|
||||
| `FontTile` | Individual font preview card | `@armco/font-spot/FontTile` |
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### 1. Font Browser (`Fonts.tsx` → `FontsList.tsx`)
|
||||
|
||||
**Description:** Grid view for browsing all available fonts with live preview
|
||||
|
||||
**Capabilities:**
|
||||
- Paginated font grid (30 fonts initial, 200 on search)
|
||||
- Dynamic @font-face injection
|
||||
- Text search with debounce (1 second)
|
||||
- Compact view toggle (UI only)
|
||||
- Pagination controls
|
||||
|
||||
**API Integration:**
|
||||
- `GET /font/page?pageSize=30&from=0` - Fetch fonts page
|
||||
|
||||
**Response Processing:**
|
||||
1. Parse JSON response containing `fontNames` and `returnFontGroups`
|
||||
2. Inject `returnFontGroups` as `<style>` element into document head
|
||||
3. Display font names in grid with applied font-family
|
||||
|
||||
---
|
||||
|
||||
### 2. Font Tile (`FontTile.tsx`)
|
||||
|
||||
**Description:** Individual font preview card
|
||||
|
||||
**Display:**
|
||||
- 8rem × 8rem fixed size card
|
||||
- Font name displayed in that font's typeface
|
||||
- Border with hover cursor
|
||||
|
||||
**Props:**
|
||||
```typescript
|
||||
interface FontTileProps {
|
||||
font: string // Font family name
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Search Functionality
|
||||
|
||||
**Description:** Real-time font search
|
||||
|
||||
**Behavior:**
|
||||
- Debounced input (1000ms delay)
|
||||
- Triggers new API call with `search` parameter
|
||||
- Updates grid with filtered results
|
||||
|
||||
---
|
||||
|
||||
### 4. Pagination
|
||||
|
||||
**Description:** Page-based navigation
|
||||
|
||||
**Configuration:**
|
||||
- Max pills to show: 5
|
||||
- Initial page size: 30
|
||||
- Search page size: 200
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints Used
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/font/page` | Paginated font list |
|
||||
|
||||
**Query Parameters:**
|
||||
- `pageSize` - Number of fonts per page
|
||||
- `from` - Starting index
|
||||
- `search` - Text filter (optional)
|
||||
|
||||
**Response Format:**
|
||||
```json
|
||||
{
|
||||
"fontNames": ["Roboto", "Open Sans", ...],
|
||||
"returnFontGroups": "@font-face { ... }"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Peer Dependencies
|
||||
|
||||
```json
|
||||
{
|
||||
"@armco/components": "^0.0.60",
|
||||
"@armco/configs": "^0.0.11",
|
||||
"@armco/types": "^0.0.18",
|
||||
"@armco/utils": "^0.0.29",
|
||||
"react": "^18.2.0",
|
||||
"react-dom": "^18.2.0",
|
||||
"react-redux": "^8.0.1",
|
||||
"react-router-dom": "^6.13.0"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Output
|
||||
|
||||
```
|
||||
build/
|
||||
├── cjs/ # CommonJS modules
|
||||
│ └── Fonts.js # Main entry
|
||||
├── es/ # ES modules
|
||||
│ └── Fonts.js # Main entry
|
||||
└── types/ # TypeScript declarations
|
||||
└── Fonts.d.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Styling
|
||||
|
||||
### CSS Variables Used
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `--ar-bg` | Background color |
|
||||
| `--ar-bg-base` | Base background |
|
||||
| `--ar-color` | Text color |
|
||||
| `--ar-colora` | Alternate text color |
|
||||
|
||||
### BEM Naming
|
||||
|
||||
- `.ar-Fonts` - Root container
|
||||
- `.ar-FontsList` - List container
|
||||
- `.ar-FontsList__header-search-upload` - Header section
|
||||
- `.ar-FontsList__font-tile-container` - Grid container
|
||||
- `.ar-FontTile` - Individual tile
|
||||
|
||||
---
|
||||
|
||||
## Configuration Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `vite.config.ts` | Library build configuration |
|
||||
| `vite-dev.config.ts` | Development server |
|
||||
| `vite-run.config.ts` | Standalone run mode |
|
||||
| `tsconfig.json` | TypeScript configuration |
|
||||
Reference in New Issue
Block a user