frontend-ui-patterns

name	frontend-ui-patterns
description	Create and update QuickStack frontend pages, React components, forms, dialogs, tables, streaming UI, and Zustand-backed state using the project's established UI conventions. Use when editing frontend files, shadcn/ui composition, react-hook-form + Zod flows, Server Action consumption from client components, or client/server component boundaries.

Frontend UI Patterns

Quick Start

For QuickStack frontend work:

• Use kebab-case filenames.
• Put shadcn/ui primitives in src/components/ui/.
• Put composed UI in src/components/custom/.
• Put frontend hooks, helpers, sockets, and Zustand usage in src/frontend/.
• Co-locate page-specific Server Actions in actions.ts beside the consuming page.

Core Workflow

When creating or updating frontend UI:

• Decide the boundary first: server pages fetch data and check auth; client components handle interaction.
• Build forms with react-hook-form, Zod, shadcn Form, and shared field wrappers.
• Consume Server Actions through Toast.fromAction() or Actions.run(), not direct awaits.
• Prefer Zustand-backed shared dialogs and stores over one-off local global state.
• Use SimpleDataTable for standard tables before building custom table behavior.
• Style with shadcn/ui plus Tailwind utilities and cn().

Boundary Rules

• Use 'use server' for pages and layouts that fetch data or gate authorization.
• Use 'use client' for dialogs, forms, tables, event handlers, and streaming UI.
• Use auth helpers from action-wrapper.utils.ts in server components.

Forms And Actions

• Add route-safe validation with shared or local Zod schemas.
• Map server validation errors back with FormUtils.mapValidationErrorsToForm(...).
• Use SubmitButton for form submits when possible.

State, Dialogs, And Streaming

• Reuse stores in src/frontend/states/zustand.states.ts before adding new ones.
• Use useDialog, useConfirmDialog, and useInputDialog for modal flows.
• Clean up SSE and socket work with AbortController or equivalent effect cleanup.

Reference

See REFERENCE.md for concrete examples covering server/client boundaries, auth helpers, forms, Server Actions, Zustand stores, SimpleDataTable, dialogs, styling, and real-time UI.