@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/skills/nextjs-shadcn/references/shadcn-platform.md

@@ -1,261 +0,0 @@
-# shadcn Platform
-
-The parts of shadcn that are not individual components: which primitive base to
-build on, the CLI verbs worth knowing, and the CSS-level systems (typeset,
-shimmer, scroll-fade).
-
-## Choosing a base (do this first)
-
-shadcn components ship on three primitive libraries: Base UI, Radix, and React
-Aria. **Base UI is the default.** The choice is per-project and set at `init` —
-components installed later inherit it.
-
-```bash
-# Base UI (default)
-yarn dlx shadcn@latest init --template next --base base   --preset <preset> --no-monorepo --no-rtl --yes
-# Radix (legacy projects)
-yarn dlx shadcn@latest init --template next --base radix  --preset <preset> --no-monorepo --no-rtl --yes
-# React Aria
-yarn dlx shadcn@latest init --template next --base aria   --preset <preset> --no-monorepo --no-rtl --yes
-```
-
-| Base | Pick it when |
-|------|-------------|
-| `base` | New projects. Default since July 2026, most actively developed, gets new components first. |
-| `radix` | Existing codebase already on Radix, or a dependency expects Radix primitives. |
-| `aria` | Accessibility/interaction requirements beyond the defaults — React Aria's behavior hooks. |
-
-**Why this matters for generated code:** the same component name has different
-props and sub-components per base. Docs are base-scoped too —
-`ui.shadcn.com/docs/components/base/sidebar` vs `.../radix/sidebar`. Never write
-component code from memory without knowing the project's base.
-
-The difference that bites most often: **Base UI composes through a `render`
-prop, Radix through `asChild`.**
-
-```tsx
-// Base UI (default) — element goes in render, children stay as children
-<SidebarMenuButton render={<Link href="/inbox" />}>
-  <Inbox />
-  <span>Inbox</span>
-</SidebarMenuButton>
-
-// Radix — element wraps the children
-<SidebarMenuButton asChild>
-  <Link href="/inbox">
-    <Inbox />
-    <span>Inbox</span>
-  </Link>
-</SidebarMenuButton>
-```
-
-Read the base from `components.json` (or `shadcn info --json`) before editing an
-existing project.
-
-`migrate radix` does **not** switch a project from Radix to Base UI — it rewrites
-`@radix-ui/react-*` imports to the single `radix-ui` package. Radix → Base UI is
-a component-at-a-time migration driven by the official shadcn skill:
-
-```bash
-yarn dlx skills add shadcn/ui
-# then ask the agent: "migrate accordion to base-ui"
-```
-
-Both libraries stay installed while you work, each component lands in its own
-commit, and every run writes a report to `.migration/<component>.md`.
-
-## CLI verbs beyond `add`
-
-`add` and `init` are the familiar ones. These four are what make the CLI useful
-to an agent:
-
-```bash
-yarn dlx shadcn@latest info --json              # project config: framework, base, tailwind, aliases, installed components
-yarn dlx shadcn@latest docs button              # API reference for a component, resolved to THIS project's base
-yarn dlx shadcn@latest docs button --json       # machine-readable, for piping into context
-yarn dlx shadcn@latest view button card         # inspect registry item source before installing
-yarn dlx shadcn@latest search @shadcn -q chart  # search a registry namespace
-```
-
-**Prefer `shadcn docs <component>` over recalling props from memory or fetching
-`llms.txt`** — it resolves against the project's actual base and version. Use
-`shadcn view` before `add` when you are unsure what a registry item pulls in.
-
-Other verbs: `add <component> --diff` (upstream changes to an installed
-component — the standalone `diff` command is deprecated), `apply <preset>`
-(apply a preset to an existing project; `--only theme,font` for just those
-parts), `preset decode|resolve|url|open` (inspect a preset code), `build`
-(generate registry JSON), `migrate` (`icons`, `rtl`, `radix`), `eject` (inline
-`shadcn/tailwind.css` and drop the `shadcn` dependency).
-
-### `migrate icons`
-
-Swapping icon libraries across a whole project is a single command:
-
-```bash
-yarn dlx shadcn@latest migrate icons --from lucide --to phosphor
-```
-
-## The official shadcn skill
-
-shadcn publishes its own agent skill, which injects live project config
-(`shadcn info --json`) plus the full CLI and registry reference:
-
-```bash
-yarn dlx skills add shadcn/ui
-```
-
-It activates when the project has a `components.json`. It covers CLI mechanics
-and registry authoring — **this skill covers project conventions, architecture,
-and Next.js integration instead.** Install both; don't duplicate CLI reference
-material here.
-
-There is also an MCP server for registry search and install from within the
-editor — wire it into Claude Code with
-`yarn dlx shadcn@latest mcp init --client claude`.
-
-## Typeset — styling rendered markdown
-
-One CSS file you own that styles headings, paragraphs, lists, tables and code
-inside a wrapper class. Replaces hand-written `prose`-style overrides and
-per-context markdown CSS.
-
-**Use it for:** chat message bodies, docs pages, blog posts, LLM-streamed
-markdown — anywhere you render HTML you did not author.
-
-Typeset is **not** part of `init` and has no `add` command. Generate the file in
-the builder at [ui.shadcn.com/typeset](https://ui.shadcn.com/typeset), drop it
-next to your main CSS, and import it after Tailwind:
-
-```css
-/* app/globals.css */
-@import "tailwindcss";
-@import "./typeset.css";
-```
-
-Three variables drive the whole rhythm; everything else derives from them:
-
-```css
-.typeset {
-  --typeset-font-body: inherit;
-  --typeset-font-heading: var(--font-heading);
-  --typeset-font-mono: var(--font-mono);
-  --typeset-size: 1em;      /* base text size */
-  --typeset-leading: 1.75;  /* line-height */
-  --typeset-flow: 1.25em;   /* space between blocks */
-}
-```
-
-Define one preset per context and apply both classes:
-
-```css
-.typeset-docs {
-  --typeset-size: 15px;
-  --typeset-leading: 1.75;
-  --typeset-flow: 1.25em;
-}
-
-.typeset-chat {
-  --typeset-leading: 1.6;
-  --typeset-flow: 1em;   /* tighter — chat bubbles are short */
-}
-```
-
-```tsx
-<div className="typeset typeset-chat">
-  <Response>{message}</Response>
-</div>
-```
-
-It is container-aware (sizes to its container, not just the viewport) and
-**streaming-stable**: appending a new block does not restyle blocks already
-rendered above it. That property is the reason to prefer it over ad-hoc CSS in
-streaming chat UIs.
-
-## Shimmer — loading and processing text
-
-CSS-only animated sweep across text. No component, no JS.
-
-```tsx
-<p className="shimmer text-muted-foreground">Generating response…</p>
-```
-
-| Class | Effect |
-|-------|--------|
-| `shimmer-color-<color>` | Highlight color, e.g. `shimmer-color-blue-500/60` |
-| `shimmer-duration-<ms>` | Sweep speed (default 2000) |
-| `shimmer-spread-<n>` | Width of the highlight band |
-| `shimmer-angle-<deg>` | Tilt (default 20) |
-| `shimmer-once` | Single sweep instead of looping |
-| `shimmer-reverse` | Reverse direction |
-
-Adapts to the element's text color, brightens in dark mode, respects
-`prefers-reduced-motion` and RTL automatically.
-
-**Use shimmer for indeterminate text states** ("Thinking…", "Searching…") and
-`Skeleton` for layout placeholders with known shape. Don't stack both.
-
-## Scroll-fade — soft scroll container edges
-
-Masks the content itself at the edges of a scroll container rather than
-overlaying a gradient, so it works on any background.
-
-```tsx
-<div className="scroll-fade overflow-y-auto">{/* content */}</div>
-```
-
-| Class | Effect |
-|-------|--------|
-| `scroll-fade` / `scroll-fade-y` | Vertical |
-| `scroll-fade-x` | Horizontal |
-| `scroll-fade-t` / `-b` / `-l` / `-r` | Single edge |
-| `scroll-fade-s` / `-e` | Start/end edge (RTL-aware) |
-| `scroll-fade-<n>` | Fade depth on the spacing scale |
-| `scroll-fade-none` | Disable |
-
-Scroll-aware: the top edge stays crisp until you scroll away from it.
-
-Both `shimmer` and `scroll-fade` come from `shadcn/tailwind.css`, which `init`
-wires up. In a project that skipped it:
-
-```css
-@import "tailwindcss";
-@import "shadcn/tailwind.css";
-```
-
-## RTL support
-
-Sidebar and the CSS utilities are RTL-aware. Opt in at init with `--rtl`,
-retrofit an existing project with `migrate rtl`, and pass `dir` on the `Sidebar`
-component. Prefer logical utilities (`ms-`/`me-`, `scroll-fade-s/-e`)
-over physical ones (`ml-`/`mr-`) in any project that might need it.
-
-## Package imports (alias alternative)
-
-Projects may use Node package imports instead of `tsconfig.json` paths:
-
-```json
-// package.json
-{ "imports": { "#components/*": "./src/components/*.tsx", "#lib/*": "./src/lib/*.ts" } }
-```
-
-```tsx
-import { Button } from "#components/ui/button";
-import { cn } from "#lib/utils";
-```
-
-Requires `moduleResolution: "bundler"` and `resolvePackageJsonImports: true`, and
-the matching `aliases` block in `components.json`. The CLI rewrites imports to
-whichever alias style is configured.
-
-**Default to `@/` for new projects.** In an existing project, read
-`components.json` and follow what is already there — never mix both styles.
-
-## Registries
-
-Beyond `@shadcn`, the CLI resolves namespaced registries (`@acme/button`),
-including private and GitHub-hosted ones. If you author a registry with more
-than a few hundred items, implement
-[dynamic search](https://ui.shadcn.com/docs/registry/dynamic-search) so
-`shadcn search` filters server-side instead of downloading the whole catalog.
-Not needed for consuming registries.

package/skills/nextjs-shadcn/references/sidebar.md

@@ -1,274 +0,0 @@
-# Sidebar
-
-shadcn/ui sidebar with nested layouts for dashboard applications.
-
-## Start from a block, not from scratch
-
-Before hand-writing an `AppSidebar`, check whether a block already matches the
-shape you need. A block installs a complete, working sidebar you then edit —
-faster and less error-prone than assembling sub-components by hand.
-
-```bash
-yarn dlx shadcn@latest add sidebar-07
-```
-
-| Block | Shape |
-|-------|-------|
-| `sidebar-01` | Navigation grouped by section (simplest) |
-| `sidebar-02` | Collapsible sections |
-| `sidebar-03` | Submenus |
-| `sidebar-04` | Floating sidebar with submenus |
-| `sidebar-05` | Collapsible submenus |
-| `sidebar-06` | Submenus as dropdowns |
-| `sidebar-07` | Collapses to icons — the common dashboard default |
-| `sidebar-08` | Inset sidebar with secondary navigation |
-| `sidebar-09` | Collapsible nested sidebars |
-| `sidebar-10` | Sidebar in a popover |
-| `sidebar-11` | Collapsible file tree |
-| `sidebar-12` | Sidebar with a calendar |
-| `sidebar-13` | Sidebar in a dialog |
-| `sidebar-14` | Sidebar on the right |
-| `sidebar-15` | Left and right sidebar |
-| `sidebar-16` | Sticky site header |
-
-Preview them at [ui.shadcn.com/blocks/sidebar](https://ui.shadcn.com/blocks/sidebar).
-Use `shadcn view sidebar-07` to read the source before installing.
-
-The patterns below are for when no block fits, or when adapting one.
-
-## Installation
-
-```bash
-yarn dlx shadcn@latest add sidebar
-```
-
-The sidebar API differs between Base UI, Radix and React Aria. Check the
-project's base (`shadcn info --json`) and read
-`shadcn docs sidebar` rather than assuming — the examples below target Base UI,
-the current default. The difference that shows up in every example: Base UI
-composes through a `render` prop (`<SidebarMenuButton render={<Link href="/" />}>`
-with the icon and label as children), where Radix wraps the children in `asChild`.
-
-## Layout Pattern
-
-Use nested layouts with SidebarProvider for persistent sidebar state:
-
-```
-app/
-├── (dashboard)/           # Route group for sidebar pages
-│   ├── layout.tsx         # SidebarProvider + AppSidebar
-│   ├── page.tsx           # Dashboard home
-│   ├── settings/
-│   │   └── page.tsx
-│   └── components/        # Route-specific components
-├── (public)/              # Public routes (no sidebar)
-│   └── login/
-└── layout.tsx             # Root layout
-```
-
-### Dashboard Layout
-
-```tsx
-// app/(dashboard)/layout.tsx
-import { AppSidebar } from "@/components/layout/app-sidebar"
-import {
-  SidebarInset,
-  SidebarProvider,
-} from "@/components/ui/sidebar"
-
-export default function DashboardLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  return (
-    <SidebarProvider>
-      <AppSidebar />
-      <SidebarInset>{children}</SidebarInset>
-    </SidebarProvider>
-  )
-}
-```
-
-### Page Component
-
-Keep pages clean - content only, no layout chrome:
-
-```tsx
-// app/(dashboard)/page.tsx
-import { DocumentWorkspace } from "@/components/workspace/document-workspace"
-import { Suspense } from "react"
-
-export default function DashboardPage() {
-  return (
-    <Suspense fallback={<DashboardSkeleton />}>
-      <DocumentWorkspace />
-    </Suspense>
-  )
-}
-```
-
-## AppSidebar Component
-
-```tsx
-// components/layout/app-sidebar.tsx
-import Link from "next/link"
-import {
-  Sidebar,
-  SidebarContent,
-  SidebarFooter,
-  SidebarGroup,
-  SidebarGroupContent,
-  SidebarGroupLabel,
-  SidebarHeader,
-  SidebarMenu,
-  SidebarMenuButton,
-  SidebarMenuItem,
-  SidebarRail,
-  SidebarSeparator,
-} from "@/components/ui/sidebar"
-import { NAV_GROUPS, FOOTER_NAV_ITEMS } from "./nav"
-
-export function AppSidebar() {
-  return (
-    <Sidebar variant="inset" collapsible="icon">
-      <SidebarHeader>
-        <SidebarMenu>
-          <SidebarMenuItem>
-            <SidebarMenuButton
-              size="lg"
-              render={<Link href="/" className="flex items-center gap-3" />}
-            >
-              <Logo className="size-8" />
-              <span className="text-base font-semibold">App Name</span>
-            </SidebarMenuButton>
-          </SidebarMenuItem>
-        </SidebarMenu>
-      </SidebarHeader>
-
-      <SidebarContent>
-        {NAV_GROUPS.map((group, index) => (
-          <div key={group.title}>
-            <SidebarGroup>
-              <SidebarGroupLabel>{group.title}</SidebarGroupLabel>
-              <SidebarGroupContent>
-                <SidebarMenu>
-                  {group.items.map((item) => (
-                    <SidebarMenuItem key={item.title}>
-                      <SidebarMenuButton render={<Link href={item.href} />}>
-                        <item.icon />
-                        <span>{item.title}</span>
-                      </SidebarMenuButton>
-                    </SidebarMenuItem>
-                  ))}
-                </SidebarMenu>
-              </SidebarGroupContent>
-            </SidebarGroup>
-            {index < NAV_GROUPS.length - 1 && <SidebarSeparator />}
-          </div>
-        ))}
-      </SidebarContent>
-
-      <SidebarFooter>
-        <SidebarSeparator />
-        <SidebarMenu>
-          {FOOTER_NAV_ITEMS.map((item) => (
-            <SidebarMenuItem key={item.title}>
-              <SidebarMenuButton render={<Link href={item.href} />}>
-                <item.icon />
-                <span>{item.title}</span>
-              </SidebarMenuButton>
-            </SidebarMenuItem>
-          ))}
-        </SidebarMenu>
-      </SidebarFooter>
-
-      <SidebarRail />
-    </Sidebar>
-  )
-}
-```
-
-## Navigation Config
-
-Separate navigation data from component:
-
-```tsx
-// components/layout/nav.ts
-import { Home, Settings, Users, HelpCircle } from "lucide-react"
-import type { LucideIcon } from "lucide-react"
-
-interface NavItem {
-  title: string
-  href: string
-  icon: LucideIcon
-}
-
-interface NavGroup {
-  title: string
-  items: NavItem[]
-}
-
-export const NAV_GROUPS: NavGroup[] = [
-  {
-    title: "Main",
-    items: [
-      { title: "Dashboard", href: "/", icon: Home },
-      { title: "Users", href: "/users", icon: Users },
-    ],
-  },
-]
-
-export const FOOTER_NAV_ITEMS: NavItem[] = [
-  { title: "Settings", href: "/settings", icon: Settings },
-  { title: "Help", href: "/help", icon: HelpCircle },
-]
-```
-
-## Sidebar Variants
-
-| Variant | Description |
-|---------|-------------|
-| `sidebar` | Standard sidebar (default) |
-| `inset` | Sidebar with padding, content area has rounded corners |
-| `floating` | Sidebar floats over content |
-
-```tsx
-<Sidebar variant="inset" collapsible="icon">
-```
-
-## Collapsible Options
-
-| Option | Behavior |
-|--------|----------|
-| `icon` | Collapses to icon-only rail |
-| `offcanvas` | Slides completely off-screen |
-| `none` | Not collapsible |
-
-## RTL
-
-`Sidebar` takes a `dir` prop and positions via `data-side` attributes, so
-right-to-left layouts work without JS conditionals — `SidebarTrigger` flips its
-icon automatically. Opt in project-wide at `init` with `--rtl`, or retrofit with
-`shadcn migrate rtl`. In any project that might need RTL, use logical utilities
-(`ms-`/`me-`, `ps-`/`pe-`) instead of `ml-`/`mr-` in sidebar markup.
-
-## Persisting open state
-
-`SidebarProvider` takes `defaultOpen` (uncontrolled) or `open` / `onOpenChange`
-(controlled); width comes from the `--sidebar-width` CSS variable. To keep the
-sidebar's state across reloads without a hydration mismatch, read a cookie in the
-layout Server Component and pass it to `defaultOpen` — don't read it client-side
-in an effect.
-
-For custom triggers, `useSidebar()` exposes `toggleSidebar`, `isMobile`, and the
-mobile-specific `openMobile` / `setOpenMobile`.
-
-## File Structure
-
-```
-components/
-└── layout/
-    ├── app-sidebar.tsx    # Sidebar component
-    └── nav.ts             # Navigation config
-```