allagroup/alla-allaos-fullstack
Template
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
phaichayon
2026-06-11 12:46:57 +07:00
parent 1993d88306
commit 7a390cf0df
720 changed files with 100919 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

262
.claude/skills/kiranism-shadcn-dashboard/SKILL.md Normal file
View File

@@ -0,0 +1,262 @@
---
name: kiranism-shadcn-dashboard
description: |
Guide for building features, pages, tables, forms, themes, and navigation in this Next.js 16 shadcn dashboard template. Use this skill whenever the user wants to add a new page, create a feature module, build a data table, add a form, configure navigation items, add a theme, set up RBAC access control, or work with the dashboard's patterns and conventions. Also triggers when adding routes under /dashboard, working with Clerk auth/orgs/billing, creating mock APIs, or modifying the sidebar. Even if the user doesn't mention "dashboard" explicitly — if they're adding UI, pages, or features to this project, use this skill.
---
# Dashboard Development Guide
This skill encodes the exact patterns and conventions used in this Next.js 16 + shadcn/ui admin dashboard template. Following these patterns ensures consistency across the codebase.
## Quick Reference: What Goes Where
| Task | Location |
| ---------------- | --------------------------------------------------- |
| New page | `src/app/dashboard/<name>/page.tsx` |
| New feature | `src/features/<name>/components/` |
| Query options | `src/features/<name>/api/queries.ts` |
| Nav item | `src/config/nav-config.ts` |
| Types | `src/types/index.ts` |
| Mock data | `src/constants/mock-api.ts` or `mock-api-<name>.ts` |
| Search params | `src/lib/searchparams.ts` |
| Query client | `src/lib/query-client.ts` |
| Theme CSS | `src/styles/themes/<name>.css` |
| Theme registry | `src/components/themes/theme.config.ts` |
| Custom hook | `src/hooks/` |
| Form components | `src/components/forms/` |
| Table components | `src/components/ui/table/` |
| Icons registry | `src/components/icons.tsx` |
---
## Adding a New Feature (End-to-End)
When a user asks to add a new feature (e.g., "add a users page", "create an orders section"), follow all these steps in order:
1. **Create mock API** in `src/constants/mock-api-<name>.ts`
2. **Create query options** in `src/features/<name>/api/queries.ts`
3. **Create the feature module** in `src/features/<name>/components/`
4. **Create the page route** in `src/app/dashboard/<name>/page.tsx`
5. **Add search params** in `src/lib/searchparams.ts` (if table/filtering needed)
6. **Add navigation** in `src/config/nav-config.ts`
7. **Register icon** in `src/components/icons.tsx` (if new icon needed)
---
## 1. Data Fetching with React Query
The project uses **TanStack React Query** for data fetching with server-side prefetching and client-side cache management. This is the default pattern for all new pages.
### Query Options (`api/queries.ts`)
Define reusable query options shared between server prefetch and client hooks:
```tsx
import { queryOptions } from '@tanstack/react-query';
import { fakeEntities, type Entity } from '@/constants/mock-api-entities';
export type { Entity };
export const entitiesQueryOptions = (filters: { page?: number; limit?: number; search?: string }) =>
queryOptions({
queryKey: ['entities', filters],
queryFn: () => fakeEntities.getEntities(filters)
});
```
### Server Prefetch + Client Hydration (Listing Component)
```tsx
import { HydrationBoundary, dehydrate } from '@tanstack/react-query';
import { getQueryClient } from '@/lib/query-client';
import { searchParamsCache } from '@/lib/searchparams';
import { entitiesQueryOptions } from '../api/queries';
import { EntityTable, EntityTableSkeleton } from './entity-table';
import { Suspense } from 'react';
export default function EntityListingPage() {
const page = searchParamsCache.get('page');
const search = searchParamsCache.get('name');
const pageLimit = searchParamsCache.get('perPage');
const filters = { page, limit: pageLimit, ...(search && { search }) };
const queryClient = getQueryClient();
void queryClient.prefetchQuery(entitiesQueryOptions(filters));
return (
<HydrationBoundary state={dehydrate(queryClient)}>
<Suspense fallback={<EntityTableSkeleton />}>
<EntityTable />
</Suspense>
</HydrationBoundary>
);
}
```
### Client Table Component (`shallow: true` + `useQuery`)
```tsx
'use client';
import { useQuery } from '@tanstack/react-query';
import { parseAsInteger, useQueryState } from 'nuqs';
import { useDataTable } from '@/hooks/use-data-table';
import { entitiesQueryOptions } from '../../api/queries';
import { columns } from './columns';
export function EntityTable() {
const [page] = useQueryState('page', parseAsInteger.withDefault(1));
const [pageSize] = useQueryState('perPage', parseAsInteger.withDefault(10));
const [search] = useQueryState('name');
const filters = { page, limit: pageSize, ...(search && { search }) };
const { data, isLoading } = useQuery(entitiesQueryOptions(filters));
const { table } = useDataTable({
data: data?.items ?? [],
columns,
pageCount: Math.ceil((data?.total_items ?? 0) / pageSize),
shallow: true, // URL changes stay client-side — React Query handles fetching
debounceMs: 500,
initialState: { columnPinning: { right: ['actions'] } }
});
if (isLoading) return <DataTableSkeleton columnCount={5} rowCount={10} filterCount={2} />;
return (
<DataTable table={table}>
<DataTableToolbar table={table} />
</DataTable>
);
}
```
**Key points:**
- `shallow: true` — URL changes stay client-side, React Query fetches on the client
- `shallow: false` — triggers full RSC server navigation (legacy pattern, avoid for new pages)
- First load uses hydrated server-prefetched data (no loading spinner)
- Subsequent pagination/filter changes fetch on the client
- Cached pages/filters load instantly (React Query cache)
### Mutations (Forms)
```tsx
const queryClient = useQueryClient();
const createMutation = useMutation({
mutationFn: (data: Payload) => fakeEntities.createEntity(data),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['entities'] });
toast.success('Created successfully');
router.push('/dashboard/entities');
},
onError: () => toast.error('Failed to create')
});
// In useAppForm onSubmit:
onSubmit: async ({ value }) => {
await createMutation.mutateAsync(payload);
};
```
---
## 2. Page Structure
Pages are **server components** by default. They use `PageContainer` and accept search params as a Promise (Next.js 16 pattern).
```tsx
import PageContainer from '@/components/layout/page-container';
import EntityListingPage from '@/features/entities/components/entity-listing';
import { searchParamsCache } from '@/lib/searchparams';
import type { SearchParams } from 'nuqs/server';
export const metadata = { title: 'Dashboard: Entities' };
type PageProps = { searchParams: Promise<SearchParams> };
export default async function Page(props: PageProps) {
const searchParams = await props.searchParams;
searchParamsCache.parse(searchParams);
return (
<PageContainer
scrollable={false}
pageTitle='Entities'
pageDescription='Manage entities (React Query + nuqs table pattern.)'
>
<EntityListingPage />
</PageContainer>
);
}
```
---
## 3. Data Tables
Tables use TanStack Table v8 with `useDataTable` hook and `nuqs` for URL state.
### Column Definitions
```tsx
export const columns: ColumnDef<YourType>[] = [
{
id: 'name',
accessorKey: 'name',
header: ({ column }) => <DataTableColumnHeader column={column} title='Name' />,
meta: { label: 'Name', placeholder: 'Search...', variant: 'text', icon: Icons.text },
enableColumnFilter: true
},
{
id: 'category',
accessorKey: 'category',
enableColumnFilter: true,
meta: { label: 'Category', variant: 'multiSelect', options: CATEGORY_OPTIONS }
},
{
id: 'actions',
cell: ({ row }) => <CellAction data={row.original} />
}
];
```
### Column Pinning
```tsx
initialState: {
columnPinning: {
right: ['actions'];
}
}
```
**Filter variants**: `text`, `number`, `range`, `date`, `dateRange`, `select`, `multiSelect`, `boolean`
---
## 4. Forms
See `docs/forms.md` for the complete form system. Forms use **TanStack Form + Zod** with `useAppForm` + `useFormFields<T>()` and `useMutation` for submission.
---
## 5. Navigation, Search Params, Icons, Themes
- **Nav**: `src/config/nav-config.ts` — groups with RBAC `access` property
- **Search params**: `src/lib/searchparams.ts` — add new params with `parseAsString`/`parseAsInteger`
- **Icons**: `src/components/icons.tsx` — single source of truth, never import `@tabler/icons-react` directly
- **Themes**: `src/styles/themes/<name>.css` with OKLCH colors, register in `theme.config.ts`
---
## Code Conventions
- **`cn()` for class merging** — never concatenate className strings
- **Server components by default** — only add `'use client'` when needed
- **React Query for data fetching** — `useQuery` + `shallow: true` for tables, `useMutation` for forms
- **nuqs for URL state** — `searchParamsCache` on server, `useQueryState` on client
- **Formatting**: single quotes, JSX single quotes, no trailing comma, 2-space tabs

180
.claude/skills/kiranism-shadcn-dashboard/references/theming-guide.md Normal file
View File

@@ -0,0 +1,180 @@
# Theme Creation Guide
## Table of Contents
1. [Create Theme CSS](#1-create-theme-css)
2. [Import Theme](#2-import-theme)
3. [Register Theme](#3-register-theme)
4. [Add Custom Fonts](#4-add-custom-fonts-optional)
5. [Set as Default](#5-set-as-default-optional)
6. [Required Tokens](#required-tokens)
7. [Color Format Reference](#color-format-reference)
---
## 1. Create Theme CSS
Create `src/styles/themes/<name>.css`:
```css
/* Light mode */
[data-theme='your-theme'] {
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
--card: oklch(...);
--card-foreground: oklch(...);
--popover: oklch(...);
--popover-foreground: oklch(...);
--primary: oklch(...);
--primary-foreground: oklch(...);
--secondary: oklch(...);
--secondary-foreground: oklch(...);
--muted: oklch(...);
--muted-foreground: oklch(...);
--accent: oklch(...);
--accent-foreground: oklch(...);
--destructive: oklch(...);
--destructive-foreground: oklch(...);
--border: oklch(...);
--input: oklch(...);
--ring: oklch(...);
--chart-1: oklch(...);
--chart-2: oklch(...);
--chart-3: oklch(...);
--chart-4: oklch(...);
--chart-5: oklch(...);
--sidebar: oklch(...);
--sidebar-foreground: oklch(...);
--sidebar-primary: oklch(...);
--sidebar-primary-foreground: oklch(...);
--sidebar-accent: oklch(...);
--sidebar-accent-foreground: oklch(...);
--sidebar-border: oklch(...);
--sidebar-ring: oklch(...);
--font-sans: 'Font Name', sans-serif;
--font-mono: 'Mono Font', monospace;
--radius: 0.5rem;
--spacing: 0.25rem;
}
/* Dark mode */
[data-theme='your-theme'].dark {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
/* ... all tokens with dark values */
}
/* Tailwind integration (required) */
[data-theme='your-theme'] {
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
--color-destructive-foreground: var(--destructive-foreground);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
--color-chart-1: var(--chart-1);
--color-chart-2: var(--chart-2);
--color-chart-3: var(--chart-3);
--color-chart-4: var(--chart-4);
--color-chart-5: var(--chart-5);
--color-sidebar: var(--sidebar);
--color-sidebar-foreground: var(--sidebar-foreground);
--color-sidebar-primary: var(--sidebar-primary);
--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
--color-sidebar-accent: var(--sidebar-accent);
--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
--color-sidebar-border: var(--sidebar-border);
--color-sidebar-ring: var(--sidebar-ring);
--font-sans: var(--font-sans);
--font-mono: var(--font-mono);
--font-serif: var(--font-serif);
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
}
}
```
## 2. Import Theme
Add to `src/styles/theme.css`:
```css
@import './themes/your-theme.css';
```
## 3. Register Theme
Add to `THEMES` array in `src/components/themes/theme.config.ts`:
```typescript
{ name: 'Your Theme', value: 'your-theme' }
```
The `value` must exactly match the `data-theme` attribute in your CSS.
## 4. Add Custom Fonts (Optional)
Only if using a Google Font not already loaded.
In `src/components/themes/font.config.ts`:
```typescript
import { Your_Font } from 'next/font/google';
const fontYourName = Your_Font({
subsets: ['latin'],
weight: ['400', '500', '700'],
variable: '--font-your-name'
});
export const fontVariables = cn(
// ... existing fonts
fontYourName.variable
);
```
In your theme CSS, use the font's **display name** (not the CSS variable):
```css
--font-sans: 'Your Font', sans-serif;
```
## 5. Set as Default (Optional)
In `src/components/themes/theme.config.ts`:
```typescript
export const DEFAULT_THEME = 'your-theme';
```
## Required Tokens
Minimum required: `--background`, `--foreground`, `--card` & `--card-foreground`, `--popover` & `--popover-foreground`, `--primary` & `--primary-foreground`, `--secondary` & `--secondary-foreground`, `--muted` & `--muted-foreground`, `--accent` & `--accent-foreground`, `--destructive` & `--destructive-foreground`, `--border`, `--input`, `--ring`, `--radius`.
Optional: `--chart-*`, `--sidebar-*`, `--font-*`, `--shadow-*`, `--tracking-normal`, `--spacing`.
## Color Format Reference
OKLCH: `oklch(lightness chroma hue)`
- Lightness: 0-1 (0=black, 1=white)
- Chroma: 0+ (0=gray, higher=saturated)
- Hue: 0-360 (0=red, 120=green, 240=blue)
See `src/styles/themes/claude.css` for a complete example.