noob-components/claude.md

# noob-components

## Project Overview

A Vue 3 component library built with TypeScript and Vite, providing reusable UI components and composables for management applications. The library extends Element Plus with custom components, layouts, and utilities.

## Technology Stack

- **Framework**: Vue 3 (Composition API)
- **Language**: TypeScript
- **Build Tool**: Vite
- **Base UI Library**: Element Plus
- **Styling**: SCSS with scoped styles
- **State Management**: Vuex (for consuming applications)
- **Internationalization**: vue3-i18n
- **Package Manager**: npm/bun

## Project Structure

```
noob-components/
├── packages/
│   ├── base/          # Base UI components
│   │   ├── data/      # Data display components (ListTable, etc.)
│   │   ├── item/      # Form input components (Input, Select, DateTime, etc.)
│   │   └── layout/    # Layout components
│   ├── manage/        # Management-specific components
│   │   ├── common/    # Common components (login forms, etc.)
│   │   └── router/    # Router layout components (index.vue, zhuBeiDong.vue)
│   └── app.ts         # Main export file
├── plugs/
│   ├── composables/   # Vue composables
│   │   ├── useListTable.ts    # Table data management
│   │   ├── useModifyForm.ts   # Form modification logic
│   │   └── ...
│   ├── http/          # HTTP utilities and API client
│   ├── element/       # Element Plus utilities
│   └── utils/         # General utilities
├── dist/              # Build output
│   ├── noob-mengyxu.js
│   ├── noob-mengyxu.css
│   └── style.css
└── vite.config.ts     # Vite configuration
```

## Key Components

### Router Layouts (`packages/manage/router/`)

Two main layout components for management applications:

- **index.vue**: Standard layout with horizontal/vertical menu support
- **zhuBeiDong.vue**: Alternative layout with specific styling

Both components:
- Provide app structure with header, aside, and main content areas
- Support theme switching (via `state.style`)
- Support size adjustments (via `state.size`)
- Handle user authentication checks
- Use **scoped CSS** with `:deep()` for child component styling

### Login Components (`packages/manage/common/`)

- **login2.vue**: Login form with vertical layout (labels above inputs)

### Data Components (`packages/base/data/`)

- **list-table.vue**: Table component with pagination, sorting, filtering
  - Uses TypeScript interface-based props
  - Integrates with `useListTable` composable
  - Supports Element Plus table features

### Form Components (`packages/base/item/`)

- **input.vue**: Text input wrapper
- **select.vue**: Select dropdown wrapper
- **datetime.vue**: Date/time picker wrapper
- **modify-form.vue**: Form modification component

All form components:
- Support `.full` class for 100% width
- Have default constrained width via `.form-item`
- Use scoped styles

## Key Composables

### useListTable (`plugs/composables/useListTable.ts`)

Manages table data with pagination and filtering.

**Important implementation details:**
- Uses `deepCopy(toRaw(example))` to avoid infinite reactivity loops
- Automatically manages pagination params (`page`, `size`)
- Supports both array and paginated response (`{ data: [], total: N }`)
- Has `disableAutoQuery` option to disable automatic queries

**Interface:**
```typescript
interface TableColumn {
  code: string;           // Property path (supports nested like "task.name")
  name?: string;          // Display name
  i18n?: string;          // i18n key
  type?: string;          // Column type
  width?: string | number;
  fixed?: boolean | 'left' | 'right';
  align?: 'left' | 'center' | 'right';
  slot?: boolean;         // Use custom slot
  dict?: string;          // Dictionary for value mapping
  timestamp?: boolean;    // Format as timestamp
  filesize?: boolean;     // Format as file size
}
```

### useModifyForm (`plugs/composables/useModifyForm.ts`)

Manages form state for add/edit operations.

## Styling Conventions

### CSS Scoping

- **Router components** (`index.vue`, `zhuBeiDong.vue`):
  - Split into unscoped (for `body`) and scoped blocks
  - Use `:deep()` for child components from library
  - Example: `:deep(.head-icon)`, `:deep(.el-input)`

- **Form components** (`input.vue`, `select.vue`, etc.):
  - Use scoped styles
  - Support `.full` class to override width

### CSS Variables Binding

Components use `v-bind()` to bind Vuex state to CSS:
```scss
color: v-bind("state.style.color");
background-color: v-bind("state.style.bodyBg");
font-size: v-bind("state.size.fontSize");
height: v-bind("state.size.headHeight");
```

### State Structure

```typescript
state.style = {
  color: string;
  bodyBg: string;
  headBg: string;
  itemBg: string;
  selectionBg: string;
  selectionColor: string;
}

state.size = {
  fontSize: string;
  headHeight: string;
  asideWidth: string;
  mainHeight: string;
  tableHeight: string;
  headIconSize: string;
  size: 'small' | 'default' | 'large';
}
```

## Build Configuration

### Library Build (`vite.config.ts`)

- Entry: `packages/app.ts`
- Output: `dist/noob-mengyxu.js` and `dist/noob-mengyxu.css`
- CSS is extracted separately (not injected into JS)
- Vue is externalized (peer dependency)

### Development Workflow

1. **Local development with linking:**
   ```bash
   bun link
   cd ../s6a_manage
   bun link noob-mengyxu
   ```

2. **Important**: When using `bun link`, JS/templates load from source but CSS loads from `dist/`
   - After CSS changes, must rebuild: `npm run build:lib`

## Common Issues and Solutions

### Issue: CSS Conflicts from Multiple Router Components

**Problem**: Multiple unscoped CSS rules causing variable conflicts

**Solution**:
- Use scoped styles with `:deep()` for child elements
- Split into unscoped (body only) and scoped blocks

### Issue: Infinite Loop in useListTable with deepCopy

**Problem**: `deepCopy(example)` inside `watchEffect` establishes reactive dependencies

**Solution**: Use `deepCopy(toRaw(example))` for deep non-reactive clone

### Issue: Form Input Width Issues

**Problem**: `.form-item` class collision between components

**Solution**:
- Add `.full { width: 100%; }` to base components
- Remove conflicting styles from router components
- Use `:deep()` when needed to style library components

### Issue: Header Icons Not Styled

**Problem**: After scoping, library components don't have scoped attribute

**Solution**: Change `.head-icon` to `:deep(.head-icon)` in router components

## TypeScript Conventions

- Use interface-based prop definitions: `defineProps<Props>()`
- Use `withDefaults()` for default values
- Prefer `undefined` over `null` for optional props (simplifies types)
- Use `() => []` or `() => ({})` for array/object defaults

## Exports

Main export file: `packages/app.ts`

Exports are organized into modules:
- `Element`: Element Plus utilities
- `NoobHead`: Header components
- `NoobInput`, `NoobButton`, etc.: Form components
- `ListTable`, `ModifyForm`: Data components
- `Api`: HTTP client
- `Styles`, `Size`: Theme utilities
- Composables: `useListTable`, `useModifyForm`, etc.

## Recent Changes

1. **TypeScript Conversion**: Converted list-table.vue to interface-based props
2. **CSS Scoping**: Fixed conflicts by scoping router component styles
3. **Reactivity Fix**: Changed to `deepCopy(toRaw(example))` in useListTable
4. **Form Layout**: Fixed login form to use vertical layout (labels above inputs)
5. **Pagination**: Fixed handling of paginated responses `{ data: [], total: N }`

## Dependencies

Key dependencies:
- `vue`: ^3.x
- `element-plus`: UI library
- `vue3-i18n`: Internationalization
- `vuex`: State management (for consumers)
- `axios`: HTTP client
- `js-md5`: Password hashing
- `@vueuse/core`: Vue utilities
- `lodash-es`: Utility functions