> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Components

> Reusable UI components and utilities for the Tuturuuu platform

This section contains documentation for reusable components and utilities used across the Tuturuuu platform.

## Available Components

### WorkspaceWrapper

A standardized component for handling workspace ID resolution and validation across the application.

The canonical implementation is shared from `packages/ui` at
`packages/ui/src/components/ui/custom/workspace-wrapper.tsx` and is imported as
`@tuturuuu/ui/custom/workspace-wrapper`. `apps/web/src/components/workspace-wrapper.tsx`
is a thin re-export kept for backward compatibility with existing imports.

* [WorkspaceWrapper Guide](./workspace-wrapper) - Complete documentation with examples
* [Quick Reference](./workspace-wrapper-quick-reference) - Quick reference guide

## Component Guidelines

### When to Create a Component

Create a new component when:

1. **Reusability**: The code is used in 2+ places
2. **Complexity**: The logic is complex enough to warrant separation
3. **Testing**: The component needs isolated testing
4. **Maintenance**: The component has specific maintenance requirements

### Where Components Live

Components belong in the narrowest home that fits their reuse:

* **Shared / reusable components** (used across apps) live in `packages/ui` under
  `packages/ui/src/components/ui/custom/`. For example, `WorkspaceWrapper` lives at
  `packages/ui/src/components/ui/custom/workspace-wrapper.tsx` and is imported via
  `@tuturuuu/ui/custom/workspace-wrapper`.
* **App-specific components** live in that app's `components/` directory
  (for example `apps/web/src/components/`).
* When a shared component is promoted to `packages/ui`, keep the old app path stable
  with a thin re-export so existing imports keep working — as
  `apps/web/src/components/workspace-wrapper.tsx` does for `WorkspaceWrapper`.

There is no enforced per-component folder scaffold. Most components are a single file
(co-located types and small hooks are fine inline); split into multiple files only when
size or complexity warrants it. Per the repo guidelines, split files over \~400 LOC and
components/widgets over \~200 LOC, and keep import paths stable with thin re-exports when
callers depend on them. Colocated tests live in `__tests__/` directories next to the code.

### Documentation Requirements

Each component must include:

1. **Purpose**: What the component does
2. **Props**: Complete API reference
3. **Examples**: Real-world usage examples
4. **Migration Guide**: If replacing existing patterns
5. **Best Practices**: Usage guidelines

### Naming Conventions

* **Components**: PascalCase (`WorkspaceWrapper`)
* **Files**: kebab-case (`workspace-wrapper.mdx`)
* **Props**: camelCase (`params`)
* **Types**: PascalCase with descriptive suffixes (`WorkspaceWrapperProps`)

## Contributing

When adding new components:

1. Create the component in the narrowest home that fits its reuse — `packages/ui` for
   shared/reusable components, or the app's `components/` directory for app-specific ones
2. Add comprehensive documentation
3. Include TypeScript types
4. Add tests
5. Update this overview page
6. Follow the established patterns

## Examples

See the [Examples Library](/learn/examples/overview) for practical implementation examples of all components.