@thorprovider/storefront 0.3.1

package/skills/json-render-shadcn/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: shadcn
+description: Pre-built shadcn/ui components for json-render. Use when working with @json-render/shadcn, adding standard UI components to a catalog, or building web UIs with Radix UI + Tailwind CSS components.
+---
+
+# @json-render/shadcn
+
+Pre-built shadcn/ui component definitions and implementations for json-render. Provides 36 components built on Radix UI + Tailwind CSS.
+
+## Two Entry Points
+
+| Entry Point | Exports | Use For |
+|-------------|---------|---------|
+| `@json-render/shadcn/catalog` | `shadcnComponentDefinitions` | Catalog schemas (no React dependency, safe for server) |
+| `@json-render/shadcn` | `shadcnComponents` | React implementations |
+
+## Usage Pattern
+
+Pick the components you need from the standard definitions. Do not spread all definitions -- explicitly select what your app uses:
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
+import { defineRegistry } from "@json-render/react";
+import { shadcnComponents } from "@json-render/shadcn";
+
+// Catalog: pick definitions
+const catalog = defineCatalog(schema, {
+  components: {
+    Card: shadcnComponentDefinitions.Card,
+    Stack: shadcnComponentDefinitions.Stack,
+    Heading: shadcnComponentDefinitions.Heading,
+    Button: shadcnComponentDefinitions.Button,
+    Input: shadcnComponentDefinitions.Input,
+  },
+  actions: {},
+});
+
+// Registry: pick matching implementations
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Stack: shadcnComponents.Stack,
+    Heading: shadcnComponents.Heading,
+    Button: shadcnComponents.Button,
+    Input: shadcnComponents.Input,
+  },
+});
+```
+
+> State actions (`setState`, `pushState`, `removeState`) are built into the React schema and handled by `ActionProvider` automatically. No need to declare them.
+
+## Extending with Custom Components
+
+Add custom components alongside standard ones:
+
+```typescript
+const catalog = defineCatalog(schema, {
+  components: {
+    // Standard
+    Card: shadcnComponentDefinitions.Card,
+    Stack: shadcnComponentDefinitions.Stack,
+
+    // Custom
+    Metric: {
+      props: z.object({
+        label: z.string(),
+        value: z.string(),
+        trend: z.enum(["up", "down", "neutral"]).nullable(),
+      }),
+      description: "KPI metric display",
+    },
+  },
+  actions: {},
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Stack: shadcnComponents.Stack,
+    Metric: ({ props }) => <div>{props.label}: {props.value}</div>,
+  },
+});
+```
+
+## Available Components
+
+### Layout
+- **Card** - Container with optional title, description, maxWidth, centered
+- **Stack** - Flex container with direction, gap, align, justify
+- **Grid** - Grid layout with columns (number) and gap
+- **Separator** - Visual divider with orientation
+
+### Navigation
+- **Tabs** - Tabbed navigation with tabs array, defaultValue, value
+- **Accordion** - Collapsible sections with items array and type (single/multiple)
+- **Collapsible** - Single collapsible section with title
+- **Pagination** - Page navigation with totalPages and page
+
+### Overlay
+- **Dialog** - Modal dialog with title, description, openPath
+- **Drawer** - Bottom drawer with title, description, openPath
+- **Tooltip** - Hover tooltip with content and text
+- **Popover** - Click-triggered popover with trigger and content
+- **DropdownMenu** - Dropdown with label and items array
+
+### Content
+- **Heading** - Heading text with level (h1-h4)
+- **Text** - Paragraph with variant (body, caption, muted, lead, code)
+- **Image** - Image with alt, width, height
+- **Avatar** - User avatar with src, name, size
+- **Badge** - Status badge with text and variant (default, secondary, destructive, outline)
+- **Alert** - Alert banner with title, message, type (success, warning, info, error)
+- **Carousel** - Scrollable carousel with items array
+- **Table** - Data table with columns (string[]) and rows (string[][])
+
+### Feedback
+- **Progress** - Progress bar with value, max, label
+- **Skeleton** - Loading placeholder with width, height, rounded
+- **Spinner** - Loading spinner with size and label
+
+### Input
+- **Button** - Button with label, variant (primary, secondary, danger), disabled
+- **Link** - Anchor link with label and href
+- **Input** - Text input with label, name, type, placeholder, value, checks
+- **Textarea** - Multi-line input with label, name, placeholder, rows, value, checks
+- **Select** - Dropdown select with label, name, options (string[]), value, checks
+- **Checkbox** - Checkbox with label, name, checked, checks, validateOn
+- **Radio** - Radio group with label, name, options (string[]), value, checks, validateOn
+- **Switch** - Toggle switch with label, name, checked, checks, validateOn
+- **Slider** - Range slider with label, min, max, step, value
+- **Toggle** - Toggle button with label, pressed, variant
+- **ToggleGroup** - Group of toggles with items, type, value
+- **ButtonGroup** - Button group with buttons array and selected
+
+## Built-in Actions (from `@json-render/react`)
+
+These are built into the React schema and handled by `ActionProvider` automatically. They appear in prompts without needing to be declared in the catalog.
+
+- **setState** - Set a value at a state path (`{ statePath, value }`)
+- **pushState** - Push a value onto an array (`{ statePath, value, clearStatePath? }`)
+- **removeState** - Remove an array item by index (`{ statePath, index }`)
+- **validateForm** - Validate all fields, write `{ valid, errors }` to state (`{ statePath? }`)
+
+## Validation Timing (`validateOn`)
+
+All form components support `validateOn` to control when validation runs:
+- `"change"` — validate on every input change (default for Select, Checkbox, Radio, Switch)
+- `"blur"` — validate when field loses focus (default for Input, Textarea)
+- `"submit"` — validate only on form submission
+
+## Important Notes
+
+- The `/catalog` entry point has no React dependency -- use it for server-side prompt generation
+- Components use Tailwind CSS classes -- your app must have Tailwind configured
+- Component implementations use bundled shadcn/ui primitives (not your app's `components/ui/`)
+- All form inputs support `checks` for validation (type + message pairs) and `validateOn` for timing
+- Events: inputs emit `change`/`submit`/`focus`/`blur`; buttons emit `press`; selects emit `change`/`select`

package/skills/json-render-solid/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: solid
+description: SolidJS renderer for json-render. Use when building @json-render/solid catalogs/registries, wiring Renderer providers, implementing bindings/actions, or troubleshooting Solid-specific reactivity patterns.
+---
+
+# @json-render/solid
+
+`@json-render/solid` renders json-render specs into Solid component trees with fine-grained reactivity.
+
+## Quick Start
+
+```tsx
+import { Renderer, JSONUIProvider } from "@json-render/solid";
+import type { Spec } from "@json-render/solid";
+import { registry } from "./registry";
+
+export function App(props: { spec: Spec | null }) {
+  return (
+    <JSONUIProvider registry={registry} initialState={{}}>
+      <Renderer spec={props.spec} registry={registry} />
+    </JSONUIProvider>
+  );
+}
+```
+
+## Create a Catalog
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/solid/schema";
+import { z } from "zod";
+
+export const catalog = defineCatalog(schema, {
+  components: {
+    Button: {
+      props: z.object({
+        label: z.string(),
+        variant: z.enum(["primary", "secondary"]).nullable(),
+      }),
+      description: "Clickable button",
+    },
+    Card: {
+      props: z.object({ title: z.string() }),
+      description: "Card container",
+    },
+  },
+  actions: {
+    submit: { description: "Submit data" },
+  },
+});
+```
+
+## Define Components
+
+Components receive `ComponentRenderProps` from the renderer:
+
+```ts
+interface ComponentRenderProps<P = Record<string, unknown>> {
+  element: UIElement<string, P>;
+  children?: JSX.Element;
+  emit: (event: string) => void;
+  on: (event: string) => EventHandle;
+  bindings?: Record<string, string>;
+  loading?: boolean;
+}
+```
+
+Example:
+
+```tsx
+import type { BaseComponentProps } from "@json-render/solid";
+
+export function Button(props: BaseComponentProps<{ label: string }>) {
+  return (
+    <button onClick={() => props.emit("press")}>{props.props.label}</button>
+  );
+}
+```
+
+## Create a Registry
+
+```typescript
+import { defineRegistry } from "@json-render/solid";
+import { catalog } from "./catalog";
+import { Card } from "./Card";
+import { Button } from "./Button";
+
+const { registry, handlers, executeAction } = defineRegistry(catalog, {
+  components: {
+    Card,
+    Button,
+  },
+  actions: {
+    submit: async (params, setState, state) => {
+      // custom action logic
+    },
+  },
+});
+```
+
+## Spec Structure
+
+```json
+{
+  "root": "card1",
+  "elements": {
+    "card1": {
+      "type": "Card",
+      "props": { "title": "Hello" },
+      "children": ["btn1"]
+    },
+    "btn1": {
+      "type": "Button",
+      "props": { "label": "Click me" },
+      "on": {
+        "press": { "action": "submit" }
+      }
+    }
+  }
+}
+```
+
+## Providers
+
+- `StateProvider`: state model read/write and controlled mode via `store`
+- `VisibilityProvider`: evaluates `visible` conditions
+- `ValidationProvider`: field validation + `validateForm` integration
+- `ActionProvider`: runs built-in and custom actions
+- `JSONUIProvider`: combined provider wrapper
+
+## Hooks
+
+- `useStateStore`, `useStateValue`, `useStateBinding`
+- `useVisibility`, `useIsVisible`
+- `useActions`, `useAction`
+- `useValidation`, `useOptionalValidation`, `useFieldValidation`
+- `useBoundProp`
+- `useUIStream`, `useChatUI`
+
+## Built-in Actions
+
+Handled automatically by `ActionProvider`:
+
+- `setState`
+- `pushState`
+- `removeState`
+- `validateForm`
+
+## Dynamic Props and Bindings
+
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` inside an enclosing repeat.
+
+Supported expression forms include:
+
+- `{"$state": "/path"}`
+- `{"$bindState": "/path"}`
+- `{"$bindItem": "field"}`
+- `{"$template": "Hi ${/user/name}"}`
+- `{"$computed": "fn", "args": {...}}`
+- `{"$cond": <condition>, "$then": <value>, "$else": <value>}`
+
+Use `useBoundProp` in components for writable bound values:
+
+```tsx
+import { useBoundProp } from "@json-render/solid";
+
+function Input(props: BaseComponentProps<{ value?: string }>) {
+  const [value, setValue] = useBoundProp(
+    props.props.value,
+    props.bindings?.value,
+  );
+  return (
+    <input
+      value={String(value() ?? "")}
+      onInput={(e) => setValue(e.currentTarget.value)}
+    />
+  );
+}
+```
+
+`useStateValue`, `useStateBinding`, and the `state` / `errors` / `isValid` fields from `useFieldValidation` are reactive accessors in Solid. Call them as functions inside JSX, `createMemo`, or `createEffect`.
+
+## Solid Reactivity Rules
+
+- Do not destructure component props in function signatures when values need to stay reactive.
+- Keep changing reads inside JSX expressions, `createMemo`, or `createEffect`.
+- Context values are exposed through getter-based objects so consumers always observe live signals.
+
+## Streaming UI
+
+```tsx
+import { useUIStream, Renderer } from "@json-render/solid";
+
+const stream = useUIStream({ api: "/api/generate-ui" });
+await stream.send("Create a support dashboard");
+
+<Renderer
+  spec={stream.spec}
+  registry={registry}
+  loading={stream.isStreaming}
+/>;
+```
+
+Use `useChatUI` for chat + UI generation flows.