@corensystem/coren-ui 1.0.0-next.20260924.75108.887a9c2

package/skills/core-ui-data-table/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: core-ui-data-table
+description: >
+  DataTable from @core/core-ui/data-table with @tanstack/react-table
+  ColumnDef. Sorting, text filtering via searchKey, pagination, column
+  visibility toggle. Expandable detail rows (renderSubComponent +
+  getRowCanExpand). Tree/nested rows (getSubRows + getSubRows). Collapsible
+  row groups (DataTableRowGroup). Indented tree cells (DataTableTreeCell).
+  Sort header button (DataTableColumnHeader). Load when building any table view.
+metadata:
+  type: core
+  library: core
+  library_version: "0.0.1"
+sources:
+  - "core/Core:packages/components/src/data-table.tsx"
+---
+
+# @core/core-ui — Data Table
+
+## Setup
+
+```tsx
+import {DataTable, DataTableColumnHeader} from "@core/core-ui/data-table";
+import type {ColumnDef} from "@tanstack/react-table";
+
+interface Worker {
+	id: string;
+	name: string;
+	trade: string;
+	status: "active" | "idle";
+}
+
+const columns: ColumnDef<Worker>[] = [
+	{
+		accessorKey: "name",
+		header: ({column}) => <DataTableColumnHeader column={column} title="Name" />,
+	},
+	{
+		accessorKey: "trade",
+		header: "Trade",
+	},
+	{
+		accessorKey: "status",
+		header: "Status",
+		cell: ({row}) => <span>{row.getValue("status")}</span>,
+	},
+];
+
+export function WorkersTable({data}: {data: Worker[]}) {
+	return <DataTable columns={columns} data={data} searchKey="name" searchPlaceholder="Filter by name..." />;
+}
+```
+
+## Core Patterns
+
+### Expandable detail panel (renderSubComponent)
+
+```tsx
+import {DataTable, DataTableDetailPanel} from "@core/core-ui/data-table";
+
+<DataTable
+	columns={columns}
+	data={data}
+	getRowCanExpand={() => true}
+	renderSubComponent={({row}) => (
+		<DataTableDetailPanel>
+			<p>Worker ID: {row.original.id}</p>
+			<p>Trade: {row.original.trade}</p>
+		</DataTableDetailPanel>
+	)}
+/>;
+```
+
+### Tree / nested rows (getSubRows)
+
+```tsx
+interface Zone {
+	id: string;
+	name: string;
+	children?: Zone[];
+}
+
+const treeColumns: ColumnDef<Zone>[] = [
+	{
+		accessorKey: "name",
+		header: "Zone",
+		cell: ({row}) => <DataTableTreeCell row={row}>{row.getValue("name")}</DataTableTreeCell>,
+	},
+];
+
+<DataTable columns={treeColumns} data={zones} getSubRows={(row) => row.children} expandAllByDefault={true} />;
+```
+
+### Collapsible row groups (DataTableRowGroup)
+
+Use inside a custom `TableBody` when rows need section grouping with
+collapse/expand. `DataTableRowGroup` renders as a `<Collapsible>` wrapping
+`TableRow` children:
+
+```tsx
+import {DataTableRowGroup} from "@core/core-ui/data-table";
+import {TableRow, TableCell} from "@core/core-ui/table";
+
+// Render inside a table body, not via DataTable directly
+<DataTableRowGroup title="Zone A" colSpan={columns.length} defaultOpen={true}>
+	{zoneARows.map((row) => (
+		<TableRow key={row.id}>
+			<TableCell>{row.name}</TableCell>
+		</TableRow>
+	))}
+</DataTableRowGroup>;
+```
+
+### Controlling page size and visibility defaults
+
+```tsx
+<DataTable
+	columns={columns}
+	data={data}
+	pageSize={25}
+	showPagination={true}
+	showColumnToggle={true}
+	showSelectedCount={false}
+/>
+```
+
+## Common Mistakes
+
+### HIGH searchKey does not match any column accessorKey
+
+Wrong:
+
+```tsx
+const columns: ColumnDef<Worker>[] = [{accessorKey: "name", header: "Name"}];
+
+<DataTable columns={columns} data={data} searchKey="fullName" />;
+// "fullName" doesn't match "name" — filter input renders but does nothing
+```
+
+Correct:
+
+```tsx
+<DataTable columns={columns} data={data} searchKey="name" />
+// Must exactly match the accessorKey or the column's id
+```
+
+`DataTable` calls `table.getColumn(searchKey)` — if no column matches, the
+column is `undefined`. The filter input renders and accepts input but
+`setFilterValue` is never called. No error or warning is thrown.
+
+Source: `packages/components/src/data-table.tsx:108`
+
+---
+
+### MEDIUM Using renderSubComponent without getRowCanExpand
+
+Wrong:
+
+```tsx
+<DataTable
+	columns={columns}
+	data={data}
+	renderSubComponent={({row}) => <Detail row={row} />}
+	// getRowCanExpand missing — rows can never expand
+/>
+```
+
+Correct:
+
+```tsx
+<DataTable
+	columns={columns}
+	data={data}
+	getRowCanExpand={() => true}
+	renderSubComponent={({row}) => <Detail row={row} />}
+/>
+```
+
+`renderSubComponent` is only rendered when `row.getIsExpanded()` is true.
+Without `getRowCanExpand` returning `true`, rows cannot be expanded — there is
+no expand button and the sub-component is silently never rendered.
+
+Source: `packages/components/src/data-table.tsx:171`
+
+---
+
+### MEDIUM Using both getSubRows and renderSubComponent simultaneously
+
+Wrong:
+
+```tsx
+<DataTable
+	data={zones}
+	getSubRows={(row) => row.children} // tree mode
+	renderSubComponent={({row}) => <Detail />} // detail panel mode
+/>
+```
+
+Correct:
+
+```tsx
+// Use getSubRows for hierarchical tree data (children rendered as nested rows)
+<DataTable data={zones} getSubRows={(row) => row.children} />
+
+// Use renderSubComponent for expand-to-detail (full-width panel below the row)
+<DataTable data={items} getRowCanExpand={() => true} renderSubComponent={...} />
+```
+
+Using both simultaneously causes double rendering: child rows from the tree
+model AND a detail panel appear when a row is expanded, producing duplicate
+content with no error.
+
+Source: `packages/components/src/data-table.tsx:40`
+
+---
+
+### MEDIUM DataTableTreeCell used without getSubRows on the table
+
+Wrong:
+
+```tsx
+// Using DataTableTreeCell but no getSubRows — row.depth is always 0
+const columns: ColumnDef<Item>[] = [
+	{
+		accessorKey: "name",
+		cell: ({row}) => <DataTableTreeCell row={row}>{row.getValue("name")}</DataTableTreeCell>,
+	},
+];
+<DataTable columns={columns} data={flatData} />;
+```
+
+Correct:
+
+```tsx
+// DataTableTreeCell only produces meaningful indentation with nested rows
+<DataTable columns={treeColumns} data={nestedData} getSubRows={(row) => row.children} />
+```
+
+`DataTableTreeCell` indents by `row.depth * 1.5rem`. With flat data and no
+`getSubRows`, depth is always 0 and the cell renders a placeholder expand
+button with no expand capability — the UI looks broken.
+
+Source: `packages/components/src/data-table.tsx:350`

package/skills/core-ui-forms/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: core-ui-forms
+description: >
+  Building validated forms with @core/core-ui/form, react-hook-form, zod,
+  and @hookform/resolvers/zod. Form/FormField/FormItem/FormLabel/FormControl/
+  FormDescription/FormMessage composition. useForm with zodResolver wiring.
+  Field registration via render prop. Inline error display. Load when building
+  any form that requires validation with react-hook-form.
+metadata:
+  type: core
+  library: core
+  library_version: "0.0.1"
+sources:
+  - "core/Core:packages/components/src/form.tsx"
+  - "core/Core:packages/components/package.json"
+---
+
+# @core/core-ui — Forms & Validation
+
+## Install
+
+`react-hook-form` is an optional **peer** of `@core/core-ui`, not a dependency —
+`Form` and `FormField` read your form state through React context, so they have to bind
+to _your_ copy of the library. `@hookform/resolvers` is yours too; core-ui never imports it.
+
+```bash
+pnpm add react-hook-form @hookform/resolvers zod
+```
+
+core-ui accepts `react-hook-form@>=7.46`. Pick a `@hookform/resolvers` line whose own peer
+range covers the version you install — current `5.x` wants `react-hook-form@^7.55`, so on
+`7.46 … 7.54` use `@hookform/resolvers@^3` (or upgrade `react-hook-form`). If the two
+disagree, your package manager says so at install time.
+
+## Setup
+
+```tsx
+import {useForm} from "react-hook-form";
+import {zodResolver} from "@hookform/resolvers/zod";
+import {z} from "zod";
+import {Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage} from "@core/core-ui/form";
+import {Input} from "@core/core-ui/input";
+import {Button} from "@core/core-ui/button";
+
+const schema = z.object({
+	email: z.string().email("Invalid email address"),
+	name: z.string().min(2, "Name must be at least 2 characters"),
+});
+
+type FormValues = z.infer<typeof schema>;
+
+export function ProfileForm() {
+	const form = useForm<FormValues>({
+		resolver: zodResolver(schema),
+		defaultValues: {email: "", name: ""},
+	});
+
+	function onSubmit(values: FormValues) {
+		console.log(values);
+	}
+
+	return (
+		<Form {...form}>
+			<form onSubmit={form.handleSubmit(onSubmit)} className="wwc:space-y-6">
+				<FormField
+					control={form.control}
+					name="email"
+					render={({field}) => (
+						<FormItem>
+							<FormLabel>Email</FormLabel>
+							<FormControl>
+								<Input placeholder="you@example.com" {...field} />
+							</FormControl>
+							<FormDescription>Your work email address.</FormDescription>
+							<FormMessage />
+						</FormItem>
+					)}
+				/>
+				<FormField
+					control={form.control}
+					name="name"
+					render={({field}) => (
+						<FormItem>
+							<FormLabel>Name</FormLabel>
+							<FormControl>
+								<Input placeholder="Full name" {...field} />
+							</FormControl>
+							<FormMessage />
+						</FormItem>
+					)}
+				/>
+				<Button type="submit" loading={form.formState.isSubmitting}>
+					Save
+				</Button>
+			</form>
+		</Form>
+	);
+}
+```
+
+## Core Patterns
+
+### Select field with FormControl
+
+```tsx
+import {Select, SelectTrigger, SelectValue, SelectContent, SelectItem} from "@core/core-ui/select";
+
+<FormField
+	control={form.control}
+	name="role"
+	render={({field}) => (
+		<FormItem>
+			<FormLabel>Role</FormLabel>
+			<Select onValueChange={field.onChange} defaultValue={field.value}>
+				<FormControl>
+					<SelectTrigger>
+						<SelectValue placeholder="Select a role" />
+					</SelectTrigger>
+				</FormControl>
+				<SelectContent>
+					<SelectItem value="admin">Admin</SelectItem>
+					<SelectItem value="viewer">Viewer</SelectItem>
+				</SelectContent>
+			</Select>
+			<FormMessage />
+		</FormItem>
+	)}
+/>;
+```
+
+### Checkbox field
+
+```tsx
+import {Checkbox} from "@core/core-ui/checkbox";
+
+<FormField
+	control={form.control}
+	name="acceptTerms"
+	render={({field}) => (
+		<FormItem className="wwc:flex wwc:items-start wwc:space-x-3 wwc:space-y-0">
+			<FormControl>
+				<Checkbox checked={field.value} onCheckedChange={field.onChange} />
+			</FormControl>
+			<FormLabel>Accept terms and conditions</FormLabel>
+			<FormMessage />
+		</FormItem>
+	)}
+/>;
+```
+
+### Accessing field state for conditional UI
+
+```tsx
+import {useFormField} from "@core/core-ui/form";
+
+// Inside a custom field component rendered within FormItem
+function CustomInput() {
+	const {error, formItemId} = useFormField();
+	return <input id={formItemId} className={error ? "wwc:border-destructive" : "wwc:border-input"} />;
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Missing Form (FormProvider) wrapper
+
+Wrong:
+
+```tsx
+// No <Form> wrapper — react-hook-form context missing
+<form onSubmit={form.handleSubmit(onSubmit)}>
+  <FormField control={form.control} name="email" render={...} />
+</form>
+```
+
+Correct:
+
+```tsx
+<Form {...form}>
+  <form onSubmit={form.handleSubmit(onSubmit)}>
+    <FormField control={form.control} name="email" render={...} />
+  </form>
+</Form>
+```
+
+`Form` is `FormProvider` from react-hook-form. `useFormContext()` inside
+`FormField` throws if `FormProvider` is not an ancestor. The error is a runtime
+throw, not a TypeScript error.
+
+Source: `packages/components/src/form.tsx:17`
+
+---
+
+### HIGH FormControl outside FormItem loses id and aria wiring
+
+Wrong:
+
+```tsx
+<FormField
+	control={form.control}
+	name="email"
+	render={({field}) => (
+		// FormItem is missing
+		<FormControl>
+			<Input {...field} />
+		</FormControl>
+	)}
+/>
+```
+
+Correct:
+
+```tsx
+<FormField
+	control={form.control}
+	name="email"
+	render={({field}) => (
+		<FormItem>
+			<FormLabel>Email</FormLabel>
+			<FormControl>
+				<Input {...field} />
+			</FormControl>
+			<FormMessage />
+		</FormItem>
+	)}
+/>
+```
+
+`FormControl` reads `FormItemContext` (set by `FormItem`) for the `id` used to
+wire `htmlFor`, `aria-describedby`, and `aria-invalid`. Without `FormItem`,
+all three become undefined strings — the form still works but accessibility
+and error styling break silently.
+
+Source: `packages/components/src/form.tsx:43`
+
+---
+
+### HIGH Importing Form components from react-hook-form directly
+
+Wrong:
+
+```tsx
+import {FormProvider, Controller} from "react-hook-form";
+```
+
+Correct:
+
+```tsx
+import {Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage} from "@core/core-ui/form";
+```
+
+`@core/core-ui/form` wraps react-hook-form with styled components and
+context plumbing. Using the raw react-hook-form primitives bypasses label
+styling, error class injection (`text-destructive`), and `aria-invalid` wiring.
+
+Source: `packages/components/src/form.tsx:137`
+
+---
+
+### MEDIUM Spreading field onto a controlled component that uses onValueChange
+
+Wrong:
+
+```tsx
+// Select expects onValueChange, not onChange
+<Select {...field}>
+```
+
+Correct:
+
+```tsx
+<Select onValueChange={field.onChange} defaultValue={field.value}>
+	<FormControl>
+		<SelectTrigger>
+			<SelectValue />
+		</SelectTrigger>
+	</FormControl>
+</Select>
+```
+
+Radix UI `Select`, `Switch`, `Checkbox` and `RadioGroup` use `onValueChange`
+or `onCheckedChange` rather than the native `onChange`. Spreading `field`
+directly passes `onChange` which these components ignore.
+
+Source: `packages/components/src/form.tsx`
+
+---
+
+See also: `@core/core-ui/field` — a simpler `Field` component for cases that do not need full react-hook-form validation