# pi-shadcn Full Context

> A TanStack Start template for publishing a shadcn-compatible registry.

This file expands the Markdown pages listed in https://pi-shadcn.vercel.app/llms.txt. Use https://pi-shadcn.vercel.app/registry.json for the machine-readable shadcn registry index.

---

URL: https://pi-shadcn.vercel.app/docs.md

Publish installable registry items with public docs from the same workspace.

# Introduction

Publish installable registry items with public docs from the same workspace.

This registry publishes copy-and-paste components, blocks, hooks, files, themes, styles, fonts, bases, and universal items that can be installed with the shadcn CLI.

Use the docs in this section to set up the registry, customize the site, and publish your own items.

<Callout title="Authoring model">
  Registry docs live in `registry/docs`. Installable source lives in `registry/items`. You can
  update any of these files freely (or completely delete them!)
</Callout>


---

URL: https://pi-shadcn.vercel.app/docs/installation.md

Install and run the registry template locally.

# Installation

Install and run the registry template locally.

After forking the template, install dependencies with [Vite+](https://viteplus.dev/guide/) and start the local docs app.

```sh
vp install
vp dev
```

Open the local URL from Vite+ to preview your docs, registry catalog, and install pages.

## Customize the Registry

Update `registry/config.ts` before publishing your fork. This file controls the public registry identity, namespace, description, homepage, repository URL, and generated install URLs.

## Add Registry Items

Scaffold new installable items under `registry/items/**` with the starter script.

```sh
bun --bun ./scripts/new.ts --type registry:ui --name example-card --description "A compact card component."
```

You can also run `bun --bun ./scripts/new.ts` for an interactive prompt. Use `--target` for `registry:page`, `registry:file`, custom alias installs such as `@ui/ai/prompt-input.tsx`, or targeted `registry:item` files.

The scaffold creates the item source, `_registry.mdx` metadata and usage docs, and an optional `_preview.tsx` preview. Public documentation pages live directly in `registry/docs/`.

## Verify Changes

Run the registry doctor after item changes, check the files you touched, and build before publishing.

```sh
bun --bun ./scripts/doctor.ts
vp check --fix <touched-file>
vp build
```

## Deploy to Cloudflare Pages

The build prerenders the registry site into `dist/client`, including `/registry.json`,
`/r/registry.json`, every `/r/<name>.json` item, the home page, docs pages, Markdown pages,
`llms.txt`, and `sitemap.xml`. Cloudflare Pages can serve that directory directly without a
Worker runtime.

Use these Cloudflare Pages settings:

```text
Build command: bun run build
Build output directory: dist/client
```

For manual deployment:

```sh
bun run build
bunx wrangler pages deploy dist/client
```

Static deployments should install registry items from the explicit `/r/<name>.json` URLs.

## Protect the Home Page

Static Pages deployments cannot use a private key from application code for real access control.
Protect the home page with Cloudflare Access instead:

```text
Application type: Self-hosted
Application domain: <your-pages-domain>
Path: /
Policy: Allow your team, email list, or identity provider group
```

Keep registry JSON routes such as `/registry.json` and `/r/*` outside that Access rule if they
should stay installable by the shadcn CLI.


---

URL: https://pi-shadcn.vercel.app/docs/registry.md

Scaffold and author installable registry items under registry/items.

# Registry

Scaffold and author installable registry items under registry/items.

Registry items live under `registry/items/**` and can be installed by shadcn-compatible CLIs. Start new items with the scaffold command so the folder, `_registry.mdx`, source file, metadata, and generated registry JSON paths follow the template conventions.

```sh
bun --bun ./scripts/new.ts --type registry:ui --name example-card --description "A compact card component."
```

Or, run the command without flags if you want an interactive prompt (recommended).

```sh
bun --bun ./scripts/new.ts
```

<Callout title="Requires Bun">
  [Make sure Bun is installed before running these scripts.](https://bun.com/)
</Callout>

## Item Types

Choose the registry type from what the item installs:

| Type                 | Use For                                   | Folder                         |
| -------------------- | ----------------------------------------- | ------------------------------ |
| `registry:ui`        | Shadcn-style UI components                | `registry/items/components/**` |
| `registry:component` | Components outside `components/ui`        | `registry/items/components/**` |
| `registry:block`     | Larger composed UI patterns               | `registry/items/blocks/**`     |
| `registry:hook`      | React hooks                               | `registry/items/hooks/**`      |
| `registry:lib`       | Utility or helper modules                 | `registry/items/lib/**`        |
| `registry:page`      | App page files with explicit targets      | `registry/items/pages/**`      |
| `registry:file`      | Other files with explicit install targets | `registry/items/files/**`      |
| `registry:style`     | Style-level CSS and dependency metadata   | `registry/items/styles/**`     |
| `registry:theme`     | Theme CSS variables                       | `registry/items/themes/**`     |
| `registry:font`      | Font metadata                             | `registry/items/fonts/**`      |
| `registry:base`      | Design system base configuration          | `registry/items/bases/**`      |
| `registry:item`      | Universal or metadata-only items          | `registry/items/items/**`      |

The scaffold creates each item in its own folder:

```text
registry/items/components/example-card/
  _registry.mdx
  _preview.tsx
  example-card.tsx
```

## CLI Flags

Use flags for agent-friendly and CI-friendly scaffolding:

```sh
bun --bun ./scripts/new.ts --type registry:block --name stats-panel --description "A metrics panel with reusable sample data."
bun --bun ./scripts/new.ts --type registry:ui --name prompt-input --description "An AI prompt input." --target @ui/ai/prompt-input.tsx
bun --bun ./scripts/new.ts --type registry:page --name dashboard-page --description "A starter dashboard page." --target app/dashboard/page.tsx
bun --bun ./scripts/new.ts --type registry:file --name chart-theme --description "Shared chart theme tokens." --target styles/chart-theme.css --file-extension css
bun --bun ./scripts/new.ts --type registry:font --name font-inter --description "Inter font metadata." --font-family "'Inter Variable', sans-serif" --font-import Inter --font-variable=--font-sans
```

Supported flags:

- `--type`: registry item type. Defaults to `registry:ui`.
- `--name`: required kebab-case item name.
- `--title`: optional public title. Defaults from the name.
- `--description`: required public description.
- `--target`: required for `registry:page` and `registry:file`; optional for source-backed items that need a custom install path, including shadcn target placeholders like `@ui/ai/prompt-input.tsx`.
- `--file-extension`: for `registry:file` and targeted `registry:item`; defaults to `ts`.
- `--font-family`, `--font-import`, `--font-variable`: required for noninteractive `registry:font` scaffolds.

Use `bun --bun ./scripts/new.ts --help` to print the full usage.

## Authoring

Use `_registry.mdx` for public metadata and usage docs. Put the optional named `Preview` export in `_preview.tsx`. Keep both files private to authoring; never list them in `files`.

For one-file `registry:ui` items, the catalog infers `<item-name>.tsx`. Hooks, libs, blocks, pages, target paths, and multi-file items should list `files` explicitly. Metadata-only styles, themes, fonts, bases, and universal items can omit `files`.

List authored source files with paths relative to the item `_registry.mdx` file. The catalog automatically emits `files[].target` placeholders such as `@ui/<name>.tsx`, `@components/<name>.tsx`, `@hooks/<name>.ts`, and `@lib/<name>.ts` for file types that should install through the user's `components.json` aliases. Use explicit `target` values for `registry:page`, `registry:file`, and nested alias installs like `@ui/ai/prompt-input.tsx`; do not add `registry/items/**` prefixes or a separate `sourcePath` field.

Use `localRegistryDependencies` for dependencies on other local registry items.

After editing an item, run `vp check --fix` on touched files and `bun --bun ./scripts/doctor.ts`. Run `vp build` when registry docs, routes, JSON output, catalog loading, or source loading changed.


---

URL: https://pi-shadcn.vercel.app/docs/agents.md

Give AI coding tools the right context for using and authoring this registry.

# Agents

Give AI coding tools the right context for using and authoring this registry.

This template is designed to work well with coding agents and LLM-powered tools. It exposes Markdown-first routes for reading context, and it ships an installable Agent Skill for authoring registry items correctly.

## Install the Registry Skill

Install the pi-shadcn registry authoring skill from the repository:

```sh
npx skills add donotlb/pi-shadcn --skill shadcn-registry
```

Forks can install the same skill from their own repository:

```sh
npx skills add <owner>/<repo> --skill shadcn-registry
```

After installing the skill, ask for registry work directly:

- "add a button component to the registry"
- "adapt this modal from my app into a reusable registry component"
- "add a reusable hook to the registry"
- "turn this dashboard section into a registry block"

The skill covers all public registry item types, previews, usage docs, dependency metadata, and the scaffold command for creating new items non-interactively.

## Point Agents At Markdown

The generated [`/llms.txt`](/llms.txt) route gives AI tools a compact map of the docs, registry catalog, and item pages.

Use [`/llms-full.txt`](/llms-full.txt) when a tool needs expanded context with generated Markdown content inlined.

Every docs page, the registry catalog, and each registry item also has a Markdown route:

- [`/docs.md`](/docs.md)
- [`/docs/agents.md`](/docs/agents.md)
- [`/registry.md`](/registry.md)
- [`/components/example-card.md`](/components/example-card.md)

Inspired by [Fumadocs](https://www.fumadocs.dev/docs/headless/utils/negotiation), "human" permalinks support Markdown content negotiation too. AI clients can request `text/markdown`, `text/x-markdown`, or `text/plain` in the `Accept` header on pages like [`/docs`](/docs) or [`/components/example-card`](/components/example-card) and receive Markdown without changing URLs.

Static Cloudflare Pages deployments should use the explicit `.md` routes above, because static hosts cannot negotiate Markdown and HTML from the same URL by request headers.

## Recommended Agent Workflow

For registry authoring tasks, agents should:

1. Read `AGENTS.md`, this docs section, and `/llms.txt` or `/llms-full.txt` for project context.
2. Use the `shadcn-registry` skill when available.
3. Scaffold new items with `bun --bun ./scripts/new.ts --type <type> --name <kebab-name> --description "<description>"`.
4. Add `--target` for `registry:page`, `registry:file`, custom alias installs like `@ui/ai/<file>.tsx`, and targeted `registry:item` files; use `--file-extension` for `registry:file` and targeted `registry:item` files.
5. Edit the generated source, `_registry.mdx`, and `_preview.tsx` with usage docs, previews, and dependency metadata.
6. Run `vp check --fix` on touched files, `bun --bun ./scripts/doctor.ts`, and `vp build` before handoff when docs, routes, registry JSON, catalog loading, or source loading changed.


---

URL: https://pi-shadcn.vercel.app/docs/cli.md

Install items from this registry with the shadcn CLI.

# CLI

Install items from this registry with the shadcn CLI.

Install a registry item with the command shown on its docs page.

```sh
npx shadcn@latest add https://pi-shadcn.vercel.app/r/example-card.json
```

The command that's displayed uses the `homepage` value from `registry/config.ts` for the base URL.

When deployed with a server runtime, human-facing item pages can also work with the shadcn CLI through content negotiation. For example, a browser can view [`/components/example-card`](/components/example-card), while the CLI receives the installable item JSON from the same URL:

```sh
npx shadcn@latest add https://pi-shadcn.vercel.app/components/example-card
```

For static Cloudflare Pages deployments, use the explicit `/r/<name>.json` URLs instead. Static hosts cannot choose JSON or HTML from the same URL based on request headers.

Use the package manager selector on item pages to switch between npm, pnpm, yarn, bun, vite+, and deno commands.


---

URL: https://pi-shadcn.vercel.app/docs/theming.md

Customize the docs shell and published components with your own design tokens.

# Theming

Customize the docs shell and published components with your own design tokens.

The docs app uses the local shadcn configuration in `components.json` and the global theme in `src/styles.css`.

Published registry items are independent from the docs shell. Put installable component source in `registry/items/**`, and include any required CSS, dependencies, or registry dependencies in the item frontmatter.

Use semantic tokens such as `background`, `foreground`, `primary`, `muted`, and `border` so installed components remain easy to customize.


---

URL: https://pi-shadcn.vercel.app/docs/changelog.md

Track user-facing changes to this registry.

# Changelog

Track user-facing changes to this registry.

Use this page to publish notable registry updates, new items, breaking changes, and migration notes.

## v1.0.1: April 21, 2026

- Fixed the pointer cursor when hovering `Button` components.


---

URL: https://pi-shadcn.vercel.app/components.md

Installable UI primitives and components.

# Components

Installable UI primitives and components.

- [Example Card](https://pi-shadcn.vercel.app/components/example-card): A compact card component that demonstrates shadcn registry dependencies.
- [Overlay Scroll Container](https://pi-shadcn.vercel.app/components/overlay-scroll-container): A responsive scroll container that uses native overflow on touch devices and overlay scrollbars on desktop.


---

URL: https://pi-shadcn.vercel.app/components/example-card.md

A compact card component that demonstrates shadcn registry dependencies.

# Example Card

A compact card component that demonstrates shadcn registry dependencies.

## Installation

```bash
npx shadcn@latest add https://pi-shadcn.vercel.app/r/example-card.json
```

[Registry JSON](https://pi-shadcn.vercel.app/r/example-card.json)

## Preview

```tsx
import { ExampleCard } from "@/components/ui/example-card";

export function Preview() {
  return <ExampleCard />;
}
```


## Source

### ui/example-card.tsx

```tsx
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";

type ExampleCardProps = {
  title?: string;
  description?: string;
  status?: string;
};

function ExampleCard({
  title = "Ready to publish",
  description = "Use this component as a small, installable starter item.",
  status = "Template",
}: ExampleCardProps) {
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <div className="flex items-center justify-between gap-3">
          <CardTitle>{title}</CardTitle>
          <Badge variant="secondary">{status}</Badge>
        </div>
        <CardDescription>{description}</CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-sm text-muted-foreground">
          Replace this example with a component from your own registry.
        </p>
      </CardContent>
      <CardFooter>
        <Button className="w-full">Open docs</Button>
      </CardFooter>
    </Card>
  );
}

export { ExampleCard, type ExampleCardProps };
```



## Usage

Use the card anywhere you need a compact content summary with a title, description, status badge,
and action.

```tsx
import { ExampleCard } from "@/components/ui/example-card";

<ExampleCard title="Hello" description="world!" />
```


---

URL: https://pi-shadcn.vercel.app/components/overlay-scroll-container.md

A responsive scroll container that uses native overflow on touch devices and overlay scrollbars on desktop.

# Overlay Scroll Container

A responsive scroll container that uses native overflow on touch devices and overlay scrollbars on desktop.

## Installation

```bash
npx shadcn@latest add https://pi-shadcn.vercel.app/r/overlay-scroll-container.json
```

[Registry JSON](https://pi-shadcn.vercel.app/r/overlay-scroll-container.json)

## Preview

```tsx
import { OverlayScrollContainer } from "@/components/overlay-scroll-container";

export function Preview() {
  return (
    <OverlayScrollContainer className="h-64 w-full max-w-md rounded-lg border bg-card p-4">
      <div className="space-y-3">
        {Array.from({ length: 16 }, (_, index) => (
          <div key={index} className="rounded-md border bg-background px-3 py-2 text-sm">
            Scroll row {index + 1}
          </div>
        ))}
      </div>
    </OverlayScrollContainer>
  );
}
```


## Source

### overlay-scroll-container.tsx

```tsx
"use client";

import type { PartialOptions } from "overlayscrollbars";
import { OverlayScrollbarsComponent } from "overlayscrollbars-react";
import * as React from "react";

import { cn } from "@/lib/utils";

// eslint-disable-next-line import/no-unassigned-import
import "overlayscrollbars/styles/overlayscrollbars.css";

const COARSE_POINTER_QUERY = "(pointer: coarse)";
const SMALL_VIEWPORT_QUERY = "(max-width: 768px)";

function detectMobileViewport() {
  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
    return false;
  }

  return (
    window.matchMedia(COARSE_POINTER_QUERY).matches ||
    window.matchMedia(SMALL_VIEWPORT_QUERY).matches
  );
}

function subscribeToMobileViewport(onStoreChange: () => void) {
  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
    return () => {};
  }

  const coarsePointerMedia = window.matchMedia(COARSE_POINTER_QUERY);
  const smallViewportMedia = window.matchMedia(SMALL_VIEWPORT_QUERY);

  coarsePointerMedia.addEventListener("change", onStoreChange);
  smallViewportMedia.addEventListener("change", onStoreChange);

  return () => {
    coarsePointerMedia.removeEventListener("change", onStoreChange);
    smallViewportMedia.removeEventListener("change", onStoreChange);
  };
}

function useMobileViewport() {
  return React.useSyncExternalStore(subscribeToMobileViewport, detectMobileViewport, () => false);
}

export interface OverlayScrollContainerProps extends React.ComponentPropsWithoutRef<"div"> {
  element?: React.ElementType;
  enabled?: boolean;
  defer?: boolean;
  options?: PartialOptions | false | null;
  nativeOverflowClassName?: string;
}

export function OverlayScrollContainer({
  element = "div",
  className,
  enabled = true,
  defer = true,
  options,
  nativeOverflowClassName = "overflow-auto",
  children,
  ...props
}: OverlayScrollContainerProps) {
  const isMobile = useMobileViewport();
  const shouldEnable = enabled && !isMobile;
  const Element = element;

  if (!shouldEnable) {
    return (
      <Element className={cn(nativeOverflowClassName, className)} {...props}>
        {children}
      </Element>
    );
  }

  return (
    <OverlayScrollbarsComponent
      element={element}
      defer={defer}
      options={options ?? undefined}
      className={cn(className)}
      {...props}
    >
      {children}
    </OverlayScrollbarsComponent>
  );
}
```



## Usage

A responsive scroll container that uses native overflow on touch devices and overlay scrollbars on desktop.

```tsx
import { OverlayScrollContainer } from "@/components/overlay-scroll-container";
```


---

URL: https://pi-shadcn.vercel.app/blocks.md

Composed templates and larger UI sections.

# Blocks

Composed templates and larger UI sections.

- [Auth](https://pi-shadcn.vercel.app/blocks/auth): Authentication form blocks for email/password and email one-time-code flows.
- [Loading Screen](https://pi-shadcn.vercel.app/blocks/loading-screen): A full-screen branded loading overlay with progress and a minimum dwell time.
- [Offset Pagination](https://pi-shadcn.vercel.app/blocks/offset-pagination): An offset-based pagination bar with page-size controls and reusable state helpers.
- [Stats Panel](https://pi-shadcn.vercel.app/blocks/stats-panel): A simple multi-file block with a component and local data helper.
- [Workbench App Shell](https://pi-shadcn.vercel.app/blocks/workbench-app-shell): A resizable workbench application shell with sidebar, topbar, split view, right panel, and settings primitives.


---

URL: https://pi-shadcn.vercel.app/blocks/auth.md

Authentication form blocks for email/password and email one-time-code flows.

# Auth

Authentication form blocks for email/password and email one-time-code flows.

## Installation

```bash
npx shadcn@latest add https://pi-shadcn.vercel.app/r/auth.json
```

[Registry JSON](https://pi-shadcn.vercel.app/r/auth.json)

## Preview

```tsx
import { useState } from "react";

import { AuthEmailPasswordBlock, AuthPageShell, AuthTermsFooter, GoogleProviderIcon } from "@/components/auth/index";

export function Preview() {
  const [email, setEmail] = useState("name@company.com");
  const [password, setPassword] = useState("");

  return (
    <div className="w-full overflow-hidden rounded-lg border bg-background">
      <AuthPageShell
        mode="signin"
        brandName="Pi"
        logo={<DemoLogo />}
        title="Welcome back"
        description="Sign in to continue managing your workspace."
        switchAction={<button className="text-sm font-medium">Create account</button>}
        footer={<AuthTermsFooter brandName="Pi" />}
        className="min-h-[560px]"
      >
        <AuthEmailPasswordBlock
          mode="signin"
          email={email}
          password={password}
          providers={[
            {
              id: "google",
              label: "Continue with Google",
              icon: <GoogleProviderIcon className="size-5" />,
              onClick: () => undefined,
            },
          ]}
          onEmailChange={setEmail}
          onPasswordChange={setPassword}
          onSubmit={() => undefined}
          onForgotPassword={() => undefined}
          onUseOtp={() => undefined}
        />
      </AuthPageShell>
    </div>
  );
}

function DemoLogo() {
  return (
    <div className="flex size-12 items-center justify-center rounded-xl bg-[#171717] font-mono text-sm font-bold text-white">
      PI
    </div>
  );
}
```


## Source

### auth.tsx

```tsx
"use client";

import { ArrowLeftIcon } from "lucide-react";
import type { FormEvent, ReactNode } from "react";

import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { cn } from "@/lib/utils";

import type { AuthEmailOtpLabels, AuthEmailPasswordLabels } from "@/components/auth/labels";
import { AUTH_EMAIL_OTP_DEFAULT_LABELS, AUTH_EMAIL_PASSWORD_DEFAULT_LABELS } from "@/components/auth/labels";

export type AuthMode = "signin" | "signup";
export type AuthStep = "email" | "otp";

export interface AuthProviderAction {
  id: string;
  label: string;
  icon?: ReactNode;
  onClick: () => void | Promise<void>;
  disabled?: boolean;
}

export interface AuthPageShellProps {
  mode: AuthMode;
  brandName: string;
  logo: ReactNode;
  title: string;
  description: string;
  switchAction: ReactNode;
  footer?: ReactNode;
  children: ReactNode;
  className?: string;
}

export interface AuthEmailOtpBlockProps {
  mode: AuthMode;
  step: AuthStep;
  email: string;
  otp: string;
  maskedEmail?: string;
  emailPlaceholder?: string;
  isSubmitting?: boolean;
  isResending?: boolean;
  resendLabel?: string;
  canResend?: boolean;
  error?: string | null;
  providers?: AuthProviderAction[];
  /** Override any user-facing copy. Unspecified fields fall back to English. */
  labels?: Partial<AuthEmailOtpLabels>;
  onEmailChange: (value: string) => void;
  onOtpChange: (value: string) => void;
  onEmailSubmit: () => void | Promise<void>;
  onOtpSubmit: () => void | Promise<void>;
  onBackToEmail: () => void;
  onResend: () => void | Promise<void>;
  className?: string;
}

export function AuthPageShell({
  mode,
  brandName,
  logo,
  title,
  description,
  switchAction,
  footer,
  children,
  className,
}: AuthPageShellProps) {
  return (
    <main
      data-auth-mode={mode}
      className={cn(
        "relative flex min-h-dvh flex-col bg-[#fafafa] px-5 py-5 text-[#171717]",
        "supports-[padding:max(0px)]:px-[max(1.25rem,env(safe-area-inset-left))]",
        className,
      )}
    >
      <header className="flex min-h-8 shrink-0 items-center justify-end gap-4">
        {switchAction}
      </header>

      <section className="flex min-h-0 flex-1 items-center justify-center py-12 md:py-16">
        <div className="w-full max-w-[392px]">
          <div className="mb-7 flex flex-col items-center text-center">
            <div className="mb-5 flex items-center justify-center" aria-label={brandName}>
              {logo}
            </div>
            <h1 className="text-3xl font-semibold tracking-normal text-balance">{title}</h1>
            <p className="mt-3 max-w-[340px] text-base leading-6 text-pretty text-[#3f3f46]">
              {description}
            </p>
          </div>
          {children}
        </div>
      </section>

      {footer && (
        <footer className="shrink-0 pb-1 text-center text-xs leading-5 text-pretty text-[#5f5f66]">
          {footer}
        </footer>
      )}
    </main>
  );
}

export function AuthEmailOtpBlock({
  mode,
  step,
  email,
  otp,
  maskedEmail,
  emailPlaceholder = "name@work-email.com",
  isSubmitting,
  isResending,
  resendLabel = "Resend code",
  canResend = true,
  error,
  providers = [],
  labels,
  onEmailChange,
  onOtpChange,
  onEmailSubmit,
  onOtpSubmit,
  onBackToEmail,
  onResend,
  className,
}: AuthEmailOtpBlockProps) {
  const l = { ...AUTH_EMAIL_OTP_DEFAULT_LABELS, ...labels };

  const handleEmailSubmit = (event: FormEvent) => {
    event.preventDefault();
    void onEmailSubmit();
  };

  const handleOtpSubmit = (event: FormEvent) => {
    event.preventDefault();
    void onOtpSubmit();
  };

  return (
    <div className={cn("space-y-7", className)}>
      {error && (
        <div
          role="alert"
          className="rounded-md border border-red-200 bg-red-50 px-3 py-2 text-sm leading-5 text-red-700"
        >
          {error}
        </div>
      )}

      {step === "email" ? (
        <form onSubmit={handleEmailSubmit} className="space-y-3">
          <Input
            type="email"
            inputMode="email"
            autoComplete="email"
            placeholder={emailPlaceholder}
            value={email}
            onChange={(event) => onEmailChange(event.target.value)}
            disabled={isSubmitting}
            required
            className="h-[46px] rounded-md border-[#dedede] bg-white px-4 text-base shadow-[0_1px_1px_rgba(0,0,0,0.02)] placeholder:text-[#8a8a8a] focus-visible:ring-2"
            aria-label={l.emailAriaLabel}
          />
          <Button
            type="submit"
            disabled={isSubmitting}
            className="h-[46px] w-full rounded-md bg-[#171717] text-base font-semibold text-white hover:bg-[#2a2a2a]"
          >
            {isSubmitting ? l.sendingCode : l.continueWithEmail}
          </Button>
        </form>
      ) : (
        <form onSubmit={handleOtpSubmit} className="space-y-4">
          <div className="space-y-2 text-center">
            <p className="text-sm leading-5 text-[#52525b]">
              {l.otpSentTo}{" "}
              <span className="font-medium text-[#171717]">{maskedEmail || email}</span>
            </p>
            <button
              type="button"
              onClick={onBackToEmail}
              disabled={isSubmitting}
              className="inline-flex items-center gap-1 text-sm font-medium text-[#171717] underline-offset-4 hover:underline disabled:opacity-50"
            >
              <ArrowLeftIcon className="size-3.5" />
              {l.changeEmail}
            </button>
          </div>

          <Input
            type="text"
            inputMode="numeric"
            autoComplete="one-time-code"
            maxLength={6}
            pattern="[0-9]*"
            placeholder="000000"
            value={otp}
            onChange={(event) => onOtpChange(event.target.value)}
            disabled={isSubmitting}
            required
            className="h-[56px] rounded-md border-[#dedede] bg-white px-4 text-center font-mono text-2xl tracking-[0.34em] shadow-[0_1px_1px_rgba(0,0,0,0.02)] placeholder:tracking-normal placeholder:text-[#8a8a8a] focus-visible:ring-2"
            aria-label={l.codeAriaLabel}
          />

          <Button
            type="submit"
            disabled={isSubmitting}
            className="h-[46px] w-full rounded-md bg-[#171717] text-base font-semibold text-white hover:bg-[#2a2a2a]"
          >
            {isSubmitting ? l.verifying : mode === "signup" ? l.createAccount : l.signIn}
          </Button>

          <button
            type="button"
            onClick={() => void onResend()}
            disabled={!canResend || isSubmitting || isResending}
            className="w-full text-center text-sm font-medium text-[#171717] disabled:cursor-not-allowed disabled:text-[#8a8a8a]"
          >
            {isResending ? l.sending : resendLabel}
          </button>
        </form>
      )}

      {step === "email" && providers.length > 0 && (
        <>
          <div className="h-px bg-[#e7e7e7]" />
          <AuthProviderList providers={providers} disabled={isSubmitting} />
        </>
      )}
    </div>
  );
}

export interface AuthEmailPasswordBlockProps {
  mode: AuthMode;
  email: string;
  password: string;
  emailPlaceholder?: string;
  isSubmitting?: boolean;
  /** Sign-up only: shown after a successful registration that needs verification. */
  notice?: string | null;
  error?: string | null;
  providers?: AuthProviderAction[];
  /** Override any user-facing copy. Unspecified fields fall back to English. */
  labels?: Partial<AuthEmailPasswordLabels>;
  onEmailChange: (value: string) => void;
  onPasswordChange: (value: string) => void;
  onSubmit: () => void | Promise<void>;
  /** Sign-in only: navigate to the forgot-password flow. */
  onForgotPassword?: () => void;
  /** Switch to the email one-time-code flow. */
  onUseOtp?: () => void;
  className?: string;
}

export function AuthEmailPasswordBlock({
  mode,
  email,
  password,
  emailPlaceholder = "name@work-email.com",
  isSubmitting,
  notice,
  error,
  providers = [],
  labels,
  onEmailChange,
  onPasswordChange,
  onSubmit,
  onForgotPassword,
  onUseOtp,
  className,
}: AuthEmailPasswordBlockProps) {
  const l = { ...AUTH_EMAIL_PASSWORD_DEFAULT_LABELS, ...labels };
  const isSignUp = mode === "signup";

  const handleSubmit = (event: FormEvent) => {
    event.preventDefault();
    void onSubmit();
  };

  return (
    <div className={cn("space-y-7", className)}>
      {notice && (
        <div
          role="status"
          className="rounded-md border border-emerald-200 bg-emerald-50 px-3 py-2 text-sm leading-5 text-emerald-700"
        >
          {notice}
        </div>
      )}

      {error && (
        <div
          role="alert"
          className="rounded-md border border-red-200 bg-red-50 px-3 py-2 text-sm leading-5 text-red-700"
        >
          {error}
        </div>
      )}

      <form onSubmit={handleSubmit} className="space-y-3">
        <Input
          type="email"
          inputMode="email"
          autoComplete="email"
          placeholder={emailPlaceholder}
          value={email}
          onChange={(event) => onEmailChange(event.target.value)}
          disabled={isSubmitting}
          required
          className="h-[46px] rounded-md border-[#dedede] bg-white px-4 text-base shadow-[0_1px_1px_rgba(0,0,0,0.02)] placeholder:text-[#8a8a8a] focus-visible:ring-2"
          aria-label={l.emailAriaLabel}
        />
        <Input
          type="password"
          autoComplete={isSignUp ? "new-password" : "current-password"}
          placeholder={l.passwordPlaceholder}
          value={password}
          onChange={(event) => onPasswordChange(event.target.value)}
          disabled={isSubmitting}
          required
          className="h-[46px] rounded-md border-[#dedede] bg-white px-4 text-base shadow-[0_1px_1px_rgba(0,0,0,0.02)] placeholder:text-[#8a8a8a] focus-visible:ring-2"
          aria-label={l.passwordAriaLabel}
        />

        {!isSignUp && onForgotPassword && (
          <div className="flex justify-end">
            <button
              type="button"
              onClick={onForgotPassword}
              disabled={isSubmitting}
              className="text-sm font-medium text-[#171717] underline-offset-4 hover:underline disabled:opacity-50"
            >
              {l.forgotPassword}
            </button>
          </div>
        )}

        <Button
          type="submit"
          disabled={isSubmitting}
          className="h-[46px] w-full rounded-md bg-[#171717] text-base font-semibold text-white hover:bg-[#2a2a2a]"
        >
          {isSubmitting
            ? isSignUp
              ? l.creatingAccount
              : l.signingIn
            : isSignUp
              ? l.createAccount
              : l.signIn}
        </Button>
      </form>

      {onUseOtp && (
        <button
          type="button"
          onClick={onUseOtp}
          disabled={isSubmitting}
          className="w-full text-center text-sm font-medium text-[#171717] underline-offset-4 hover:underline disabled:opacity-50"
        >
          {l.useOtp}
        </button>
      )}

      {providers.length > 0 && (
        <>
          <div className="h-px bg-[#e7e7e7]" />
          <AuthProviderList providers={providers} disabled={isSubmitting} />
        </>
      )}
    </div>
  );
}

export function AuthProviderList({
  providers,
  disabled,
}: {
  providers: AuthProviderAction[];
  disabled?: boolean;
}) {
  return (
    <div className="space-y-3">
      {providers.map((provider) => (
        <button
          key={provider.id}
          type="button"
          onClick={() => void provider.onClick()}
          disabled={disabled || provider.disabled}
          className="relative flex h-[46px] w-full items-center justify-center rounded-md border border-[#dedede] bg-white px-4 text-base font-semibold text-[#252525] shadow-[0_1px_1px_rgba(0,0,0,0.02)] transition-colors hover:bg-[#f7f7f7] disabled:cursor-not-allowed disabled:opacity-50"
        >
          {provider.icon && (
            <span className="absolute left-6 flex size-5 items-center justify-center">
              {provider.icon}
            </span>
          )}
          <span>{provider.label}</span>
        </button>
      ))}
    </div>
  );
}

export function AuthTermsFooter({
  brandName,
  termsHref = "/terms",
  privacyHref = "/privacy",
}: {
  brandName: string;
  termsHref?: string;
  privacyHref?: string;
}) {
  return (
    <p>
      By proceeding, you agree to creating a {brandName} account subject to our{" "}
      <a className="font-medium text-[#171717] hover:underline" href={termsHref}>
        Terms of Service
      </a>{" "}
      and{" "}
      <a className="font-medium text-[#171717] hover:underline" href={privacyHref}>
        Privacy Policy
      </a>
      .
    </p>
  );
}

export function GoogleProviderIcon({ className }: { className?: string }) {
  return (
    <svg
      className={className}
      viewBox="0 0 24 24"
      xmlns="http://www.w3.org/2000/svg"
      aria-hidden="true"
    >
      <path
        d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"
        fill="#4285F4"
      />
      <path
        d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
        fill="#34A853"
      />
      <path
        d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
        fill="#FBBC05"
      />
      <path
        d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
        fill="#EA4335"
      />
    </svg>
  );
}
```


### auth-labels.ts

```ts
/**
 * User-facing copy for the auth blocks. Every field has an English default, so
 * the blocks render standalone; consumers override these (e.g. with their i18n
 * library) by passing a partial `labels` object. The blocks stay i18n-agnostic —
 * they never import a translation library.
 *
 * These live in their own module (not alongside the components) so the component
 * file only exports components, keeping React Fast Refresh happy.
 */

export interface AuthEmailOtpLabels {
  continueWithEmail: string;
  sendingCode: string;
  /** Lead-in shown before the (separately styled) masked email. */
  otpSentTo: string;
  changeEmail: string;
  verifying: string;
  createAccount: string;
  signIn: string;
  sending: string;
  emailAriaLabel: string;
  codeAriaLabel: string;
}

export const AUTH_EMAIL_OTP_DEFAULT_LABELS: AuthEmailOtpLabels = {
  continueWithEmail: "Continue with Email",
  sendingCode: "Sending code...",
  otpSentTo: "Enter the code sent to",
  changeEmail: "Change email",
  verifying: "Verifying...",
  createAccount: "Create account",
  signIn: "Sign in",
  sending: "Sending...",
  emailAriaLabel: "Email address",
  codeAriaLabel: "Verification code",
};

export interface AuthEmailPasswordLabels {
  passwordPlaceholder: string;
  forgotPassword: string;
  creatingAccount: string;
  signingIn: string;
  createAccount: string;
  signIn: string;
  useOtp: string;
  emailAriaLabel: string;
  passwordAriaLabel: string;
}

export const AUTH_EMAIL_PASSWORD_DEFAULT_LABELS: AuthEmailPasswordLabels = {
  passwordPlaceholder: "Password",
  forgotPassword: "Forgot password?",
  creatingAccount: "Creating account...",
  signingIn: "Signing in...",
  createAccount: "Create account",
  signIn: "Sign in",
  useOtp: "Use a verification code instead",
  emailAriaLabel: "Email address",
  passwordAriaLabel: "Password",
};
```



## Usage

Authentication form blocks for email/password and email one-time-code flows.

```tsx
import { AuthEmailPasswordBlock, AuthPageShell } from "@/components/auth";
```


---

URL: https://pi-shadcn.vercel.app/blocks/loading-screen.md

A full-screen branded loading overlay with progress and a minimum dwell time.

# Loading Screen

A full-screen branded loading overlay with progress and a minimum dwell time.

## Installation

```bash
npx shadcn@latest add https://pi-shadcn.vercel.app/r/loading-screen.json
```

[Registry JSON](https://pi-shadcn.vercel.app/r/loading-screen.json)

## Preview

```tsx
import { LoadingScreen } from "@/components/loading-screen";

export function Preview() {
  return (
    <div className="relative h-80 w-full overflow-hidden rounded-lg border bg-background">
      <div className="flex h-full items-center justify-center text-sm text-muted-foreground">
        Revealed content
      </div>
      <LoadingScreen
        ready={false}
        progress={68}
        position="absolute"
        logo={<DemoLogo />}
        text="Preparing workspace..."
      />
    </div>
  );
}

function DemoLogo() {
  return (
    <div
      className="flex size-16 items-center justify-center rounded-xl bg-primary font-mono text-lg font-bold text-primary-foreground"
      aria-hidden="true"
    >
      PI
    </div>
  );
}
```


## Source

### loading-screen.tsx

```tsx
"use client";

import type { CSSProperties, ReactNode } from "react";
import { useEffect, useRef, useState } from "react";

import { cn } from "@/lib/utils";

export interface LoadingScreenProps {
  /**
   * Flip to `true` once the real work behind the screen has finished. The screen
   * still honors `minDuration` first, then completes the progress bar and fades
   * out — so a fast load never produces a jarring flash.
   */
  ready: boolean;
  /** Brand mark rendered above the progress bar. */
  logo?: ReactNode;
  /** Caption shown beneath the progress bar. */
  text?: ReactNode;
  /**
   * Controlled progress, 0–100. Omit to let the screen auto-ease toward
   * completion, which is the common case when real progress isn't measurable.
   */
  progress?: number;
  /**
   * Minimum time, in ms, to stay visible even if `ready` is already `true`.
   * @default 1200
   */
  minDuration?: number;
  /**
   * Fade-out transition duration, in ms.
   * @default 600
   */
  fadeDuration?: number;
  /** Fired once the fade-out has finished and the screen has fully left. */
  onDone?: () => void;
  /**
   * Positioning mode for the overlay.
   * @default "fixed"
   */
  position?: "fixed" | "absolute";
  className?: string;
}

type Phase = "visible" | "leaving" | "gone";

/**
 * A full-screen branded loading overlay with a logo, progress bar and caption.
 *
 * It owns its own lifecycle: it stays up until `ready` is `true` *and* at least
 * `minDuration` has elapsed, then fades out and unmounts itself (rendering
 * `null`). To restart it for a new load — e.g. navigating between resources —
 * give it a changing `key` so React remounts it.
 */
export function LoadingScreen({
  ready,
  logo,
  text,
  progress,
  minDuration = 1200,
  fadeDuration = 600,
  onDone,
  position = "fixed",
  className,
}: LoadingScreenProps) {
  const [phase, setPhase] = useState<Phase>("visible");
  // Anchored once per mount; restart by remounting with a new `key`.
  const [startedAt] = useState(() => Date.now());

  // Keep the latest callback without re-running the fade-out timer effect.
  const onDoneRef = useRef(onDone);
  onDoneRef.current = onDone;

  // Once data is ready, hold for the remaining dwell time, then start leaving.
  useEffect(() => {
    if (phase !== "visible" || !ready) return undefined;
    const remaining = Math.max(0, minDuration - (Date.now() - startedAt));
    const timer = setTimeout(setPhase, remaining, "leaving");
    return () => clearTimeout(timer);
  }, [phase, ready, minDuration, startedAt]);

  // Unmount only after the fade-out transition has finished.
  useEffect(() => {
    if (phase !== "leaving") return undefined;
    const timer = setTimeout(() => {
      setPhase("gone");
      onDoneRef.current?.();
    }, fadeDuration);
    return () => clearTimeout(timer);
  }, [phase, fadeDuration]);

  const isControlled = progress != null;
  const easedProgress = useEasedProgress(!isControlled && phase !== "gone", phase !== "visible");
  const displayProgress = Math.min(100, Math.max(0, isControlled ? progress : easedProgress));

  if (phase === "gone") return null;

  const isLeaving = phase === "leaving";

  return (
    <div
      className={cn(
        position === "fixed" ? "fixed" : "absolute",
        "inset-0 z-50 flex flex-col items-center justify-center bg-background transition-opacity ease-out",
        isLeaving ? "pointer-events-none opacity-0" : "opacity-100",
        className,
      )}
      style={{ transitionDuration: `${fadeDuration}ms` } satisfies CSSProperties}
      role="status"
      aria-busy={!isLeaving}
      aria-hidden={isLeaving}
    >
      <div className="relative flex flex-col items-center gap-8">
        {logo != null && (
          <div className="relative">
            <span
              className="absolute -inset-5 animate-[pi-loading-breathe_3.2s_ease-in-out_infinite] rounded-[2rem] bg-primary/10 blur-xl motion-reduce:animate-none"
              aria-hidden
            />
            <div className="relative animate-[pi-loading-breathe_3.2s_ease-in-out_infinite] motion-reduce:animate-none">
              {logo}
            </div>
          </div>
        )}

        <div className="flex flex-col items-center gap-3.5">
          <div className="relative h-1 w-44 overflow-hidden rounded-full bg-muted">
            <div
              className="relative h-full overflow-hidden rounded-full bg-primary transition-[width] duration-200 ease-out"
              style={{ width: `${displayProgress}%` }}
            >
              <span
                className="absolute inset-y-0 -left-1/2 w-1/2 animate-[pi-loading-fill-sweep_1.1s_ease-in-out_infinite] bg-[linear-gradient(90deg,transparent,rgba(255,255,255,0.42),transparent)] motion-reduce:hidden"
                aria-hidden
              />
              <span
                className="absolute top-1/2 right-0 size-1.5 translate-x-1/2 -translate-y-1/2 animate-[pi-loading-pulse_900ms_ease-in-out_infinite] rounded-full bg-primary shadow-[0_0_10px_rgba(25,23,19,0.35)] motion-reduce:hidden"
                aria-hidden
              />
            </div>
            <span className="absolute inset-0 animate-[pi-loading-sweep_2.4s_ease-in-out_infinite] bg-[linear-gradient(90deg,transparent,rgba(255,255,255,0.55),transparent)] motion-reduce:animate-none" />
          </div>

          {text != null && <p className="text-xs text-muted-foreground">{text}</p>}
        </div>
      </div>
    </div>
  );
}

// Eases a progress value toward 92% while loading, then to 100% on completion,
// so the bar feels like it's doing real work rather than ticking a fixed clock.
function useEasedProgress(active: boolean, complete: boolean) {
  const [value, setValue] = useState(8);

  useEffect(() => {
    if (!active) return undefined;
    let running = true;
    let frame = 0;
    const tick = () => {
      let reached = false;
      setValue((prev) => {
        const target = complete ? 100 : 92;
        const next = prev + (target - prev) * 0.045;
        if (Math.abs(target - next) < 0.4) {
          reached = true;
          return target;
        }
        return next;
      });
      if (running && !reached) frame = requestAnimationFrame(tick);
    };
    frame = requestAnimationFrame(tick);
    return () => {
      running = false;
      cancelAnimationFrame(frame);
    };
  }, [active, complete]);

  return value;
}
```



## Usage

A full-screen branded loading overlay with progress and a minimum dwell time.

```tsx
import { LoadingScreen } from "@/components/loading-screen";
```


---

URL: https://pi-shadcn.vercel.app/blocks/offset-pagination.md

An offset-based pagination bar with page-size controls and reusable state helpers.

# Offset Pagination

An offset-based pagination bar with page-size controls and reusable state helpers.

## Installation

```bash
npx shadcn@latest add https://pi-shadcn.vercel.app/r/offset-pagination.json
```

[Registry JSON](https://pi-shadcn.vercel.app/r/offset-pagination.json)

## Preview

```tsx
import { useState } from "react";

import { OffsetPaginationBar } from "@/components/offset-pagination/offset-pagination-bar";
import { getOffsetPaginationState } from "@/components/offset-pagination/utils";

export function Preview() {
  const [limit, setLimit] = useState(20);
  const [offset, setOffset] = useState(40);
  const pagination = getOffsetPaginationState({ limit, offset, total: 248 });

  return (
    <OffsetPaginationBar
      className="w-full max-w-2xl rounded-lg border bg-card p-3"
      pagination={pagination}
      onPrevious={() => setOffset(pagination.previousOffset)}
      onNext={() => setOffset(pagination.nextOffset)}
      onLimitChange={(nextLimit) => {
        setLimit(nextLimit);
        setOffset(0);
      }}
    />
  );
}
```


## Source

### offset-pagination.ts

```ts
export { OffsetPaginationBar } from "@/components/offset-pagination/offset-pagination-bar";
export type { OffsetPaginationBarProps } from "@/components/offset-pagination/offset-pagination-bar";
export * from "@/components/offset-pagination/utils";
```


### offset-pagination-bar.tsx

```tsx
"use client";

import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
import type * as React from "react";

import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

import type { OffsetPaginationLabels, OffsetPaginationState } from "@/components/offset-pagination/utils";
import { OFFSET_PAGINATION_DEFAULT_LABELS } from "@/components/offset-pagination/utils";

const DEFAULT_PAGE_SIZE_OPTIONS = [20, 50, 100];

export interface OffsetPaginationBarProps {
  pagination: OffsetPaginationState;
  onPrevious: () => void;
  onNext: () => void;
  onLimitChange: (limit: number) => void;
  pageSizeOptions?: number[];
  /** Override any user-facing copy. Unspecified fields fall back to English. */
  labels?: Partial<OffsetPaginationLabels>;
  className?: string;
}

export function OffsetPaginationBar({
  pagination,
  onPrevious,
  onNext,
  onLimitChange,
  pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
  labels,
  className,
}: OffsetPaginationBarProps) {
  const l = { ...OFFSET_PAGINATION_DEFAULT_LABELS, ...labels };
  return (
    <div className={cn("flex items-center justify-between gap-4", className)}>
      <p className="text-sm text-muted-foreground tabular-nums">
        {pagination.total.toLocaleString()} {l.results}
      </p>

      <div className="flex items-center gap-2">
        <Button
          variant="outline"
          size="sm"
          disabled={!pagination.hasPreviousPage}
          onClick={onPrevious}
        >
          <ChevronLeftIcon />
          {l.previous}
        </Button>

        <span className="min-w-[5rem] text-center text-xs text-muted-foreground tabular-nums">
          {l.page} {pagination.page} / {pagination.totalPages}
        </span>

        <Button variant="outline" size="sm" disabled={!pagination.hasNextPage} onClick={onNext}>
          {l.next}
          <ChevronRightIcon />
        </Button>

        <div className="mx-1 h-4 w-px shrink-0 bg-border" />

        <select
          className="h-8 rounded-lg border border-input bg-background px-2.5 text-xs text-foreground"
          value={String(pagination.limit)}
          onChange={(e: React.ChangeEvent<HTMLSelectElement>) =>
            onLimitChange(Number(e.target.value))
          }
          aria-label={l.rowsPerPage}
        >
          {pageSizeOptions.map((n) => (
            <option key={n} value={String(n)}>
              {n} {l.perPage}
            </option>
          ))}
        </select>
      </div>
    </div>
  );
}
```


### offset-pagination-utils.ts

```ts
export interface OffsetPaginationSearch {
  limit: number;
  offset: number;
}

export interface OffsetPaginationConfig {
  defaultLimit?: number;
  maxLimit?: number;
  defaultOffset?: number;
}

export interface OffsetPaginationState extends OffsetPaginationSearch {
  page: number;
  total: number;
  totalPages: number;
  hasNextPage: boolean;
  hasPreviousPage: boolean;
  previousOffset: number;
  nextOffset: number;
}

/**
 * User-facing copy for `OffsetPaginationBar`. Every field has an English default
 * so the bar renders standalone; consumers override via `labels` (e.g. to
 * translate). The block stays i18n-agnostic and never imports a translation
 * library.
 */
export interface OffsetPaginationLabels {
  /** Trailing noun after the total count, e.g. "1,024 results". */
  results: string;
  /** Lead-in before the page numbers, e.g. "Page 2 / 9". */
  page: string;
  previous: string;
  next: string;
  /** Suffix in the page-size options, e.g. "20 / page". */
  perPage: string;
  rowsPerPage: string;
}

export const OFFSET_PAGINATION_DEFAULT_LABELS: OffsetPaginationLabels = {
  results: "results",
  page: "Page",
  previous: "Previous",
  next: "Next",
  perPage: "/ page",
  rowsPerPage: "Rows per page",
};

const DEFAULT_LIMIT = 20;
const MAX_LIMIT = 100;
const DEFAULT_OFFSET = 0;

export function parsePositiveInt(value: unknown, defaultValue: number): number {
  const n = Number(value);
  if (!Number.isFinite(n) || n < 1) return defaultValue;
  return Math.floor(n);
}

export function parseNonNegativeInt(value: unknown, defaultValue: number): number {
  const n = Number(value);
  if (!Number.isFinite(n) || n < 0) return defaultValue;
  return Math.floor(n);
}

export function parseOffsetPaginationSearch(
  search: Record<string, unknown>,
  config: OffsetPaginationConfig = {},
): OffsetPaginationSearch {
  const defaultLimit = config.defaultLimit ?? DEFAULT_LIMIT;
  const maxLimit = config.maxLimit ?? MAX_LIMIT;
  const defaultOffset = config.defaultOffset ?? DEFAULT_OFFSET;

  return {
    limit: Math.min(parsePositiveInt(search.limit, defaultLimit), maxLimit),
    offset: parseNonNegativeInt(search.offset, defaultOffset),
  };
}

export function createOffsetPaginationSearch(
  limit = DEFAULT_LIMIT,
  offset = DEFAULT_OFFSET,
): OffsetPaginationSearch {
  return { limit, offset };
}

export function updateOffsetPaginationSearch<T extends OffsetPaginationSearch>(
  prev: T,
  next: Partial<T>,
  options: { resetOffset?: boolean } = {},
): T {
  const merged = { ...prev, ...next };
  return {
    ...merged,
    offset: options.resetOffset === false ? (next.offset ?? prev.offset) : DEFAULT_OFFSET,
  };
}

export function getOffsetPaginationState(input: {
  limit: number;
  offset: number;
  total?: number;
  hasNextPage?: boolean;
}): OffsetPaginationState {
  const total = Math.max(0, input.total ?? 0);
  const totalPages = Math.max(1, Math.ceil(total / input.limit));
  const page = Math.min(Math.floor(input.offset / input.limit) + 1, totalPages);
  const hasPreviousPage = input.offset > 0;
  const hasNextPage = input.hasNextPage ?? page < totalPages;

  return {
    limit: input.limit,
    offset: input.offset,
    page,
    total,
    totalPages,
    hasNextPage,
    hasPreviousPage,
    previousOffset: Math.max(0, input.offset - input.limit),
    nextOffset: input.offset + input.limit,
  };
}
```



## Usage

An offset-based pagination bar with page-size controls and reusable state helpers.

```tsx
import { OffsetPaginationBar, getOffsetPaginationState } from "@/components/offset-pagination";
```


---

URL: https://pi-shadcn.vercel.app/blocks/stats-panel.md

A simple multi-file block with a component and local data helper.

# Stats Panel

A simple multi-file block with a component and local data helper.

## Installation

```bash
npx shadcn@latest add https://pi-shadcn.vercel.app/r/stats-panel.json
```

[Registry JSON](https://pi-shadcn.vercel.app/r/stats-panel.json)

## Preview

```tsx
import { StatsPanel } from "@/components/stats-panel";

export function Preview() {
  return <StatsPanel />;
}
```


## Source

### components/stats-panel.tsx

```tsx
import { Badge } from "@/components/ui/badge";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";

import { ExampleCard } from "@/components/ui/example-card";
import { stats } from "@/lib/stats-data";

function StatsPanel() {
  return (
    <div className="grid w-full max-w-3xl gap-4 md:grid-cols-[1fr_1.2fr]">
      <ExampleCard
        title="Registry starter"
        description="Compose local registry items with shadcn dependencies."
        status="Block"
      />
      <Card>
        <CardHeader>
          <CardTitle>Registry health</CardTitle>
        </CardHeader>
        <CardContent className="grid gap-3">
          {stats.map((stat) => (
            <div
              key={stat.label}
              className="flex items-center justify-between gap-4 rounded-md border p-3"
            >
              <div className="flex flex-col gap-1">
                <span className="text-sm font-medium">{stat.label}</span>
                <span className="text-sm text-muted-foreground">{stat.detail}</span>
              </div>
              <Badge variant="secondary">{stat.value}</Badge>
            </div>
          ))}
        </CardContent>
      </Card>
    </div>
  );
}

export { StatsPanel };
```


### lib/stats-data.ts

```ts
type Stat = {
  label: string;
  value: string;
  detail: string;
};

const stats: Stat[] = [
  {
    label: "Components",
    value: "12",
    detail: "Ready to publish",
  },
  {
    label: "Blocks",
    value: "3",
    detail: "Documented examples",
  },
  {
    label: "Schema",
    value: "100%",
    detail: "Validated output",
  },
];

export { stats, type Stat };
```



## Usage

Use the panel as a dashboard summary block. It installs the component and the local data helper
together, plus its local `example-card` dependency.

```tsx
import { StatsPanel } from "@/components/stats-panel";

<StatsPanel />
```


---

URL: https://pi-shadcn.vercel.app/blocks/workbench-app-shell.md

A resizable workbench application shell with sidebar, topbar, split view, right panel, and settings primitives.

# Workbench App Shell

A resizable workbench application shell with sidebar, topbar, split view, right panel, and settings primitives.

## Installation

```bash
npx shadcn@latest add https://pi-shadcn.vercel.app/r/workbench-app-shell.json
```

[Registry JSON](https://pi-shadcn.vercel.app/r/workbench-app-shell.json)

## Preview

```tsx
import { WorkbenchAppShellDemo } from "@/stories/registry/workbench-app-shell-demo";

export function Preview() {
  return (
    <div className="h-[640px] w-full overflow-hidden rounded-lg border">
      <WorkbenchAppShellDemo />
    </div>
  );
}
```


## Source

### workbench-app-shell.tsx

```tsx
"use client";

export { AppShellLayout } from "@/components/workbench-app-shell/app-shell-layout";
export type { AppShellLayoutProps } from "@/components/workbench-app-shell/app-shell-layout";
export { AppShellRoot } from "@/components/workbench-app-shell/app-shell-root";
export type { AppShellRootProps } from "@/components/workbench-app-shell/app-shell-root";
export { CommandHint, CommandHintText } from "@/components/workbench-app-shell/command-hint";
export { ContentBody, ContentHeader, MainContent, ShellContentScroll } from "@/components/workbench-app-shell/main-content";
export { RightPanel, RightPanelBody, RightPanelCloseButton, RightPanelHeader } from "@/components/workbench-app-shell/right-panel";
export {
  SettingsContent,
  SettingsNav,
  SettingsNavGroup,
  SettingsNavGroupTitle,
  SettingsNavItem,
  SettingsSection,
  SettingsSectionDescription,
  SettingsSectionTitle,
  SettingsShell,
} from "@/components/workbench-app-shell/settings-shell";
export type { SettingsNavItemProps } from "@/components/workbench-app-shell/settings-shell";
export { ShellNavModelView } from "@/components/workbench-app-shell/shell-nav-model";
export type { ShellNavModelViewProps } from "@/components/workbench-app-shell/shell-nav-model";
export {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarHeader,
  SidebarHeaderBack,
  SidebarItem,
  SidebarItemBadge,
  SidebarItemIcon,
  SidebarItemLabel,
  SidebarSection,
  SidebarSectionTitle,
} from "@/components/workbench-app-shell/sidebar";
export type { SidebarHeaderBackProps, SidebarItemProps } from "@/components/workbench-app-shell/sidebar";
export { SplitView } from "@/components/workbench-app-shell/split-view";
export type { SplitViewProps } from "@/components/workbench-app-shell/split-view";
export {
  Topbar,
  TopbarActions,
  TopbarBreadcrumbs,
  TopbarRightPanelToggle,
  TopbarSidebarToggle,
  TopbarTitle,
  TopbarViewTabs,
} from "@/components/workbench-app-shell/topbar";
export type { ShellNavItem, ShellNavModel, ShellNavSection } from "@/components/workbench-app-shell/types";
export { WorkbenchRoot, useWorkbenchContext } from "@/components/workbench-app-shell/workbench-context";
export type { WorkbenchContextValue, WorkbenchRootProps } from "@/components/workbench-app-shell/workbench-context";
```


### app-shell-layout.tsx

```tsx
"use client";

import * as React from "react";

import { Sheet, SheetContent } from "@/components/ui/sheet";
import { cn } from "@/lib/utils";

import { SplitView } from "@/components/workbench-app-shell/split-view";
import { useWorkbenchContext } from "@/components/workbench-app-shell/workbench-context";

export interface AppShellLayoutProps {
  sidebar?: React.ReactNode;
  topbar?: React.ReactNode;
  children?: React.ReactNode;
  rightPanel?: React.ReactNode;
  appearance?: "default" | "island";
  className?: string;
  contentClassName?: string;
  rightPanelWidth?: number;
}

function clamp(value: number, min: number, max: number) {
  return Math.min(max, Math.max(min, value));
}

export function AppShellLayout({
  sidebar,
  topbar,
  children,
  rightPanel,
  appearance = "default",
  className,
  contentClassName,
  rightPanelWidth = 320,
}: AppShellLayoutProps) {
  const {
    sidebarCollapsed,
    sidebarSize,
    setSidebarSize,
    sidebarMinSize,
    sidebarMaxSize,
    sidebarMobileOpen,
    setSidebarMobileOpen,
    rightPanelMobileOpen,
    setRightPanelMobileOpen,
  } = useWorkbenchContext();

  const handleSidebarResizeStart = React.useCallback(
    (event: React.PointerEvent<HTMLDivElement>) => {
      event.preventDefault();
      const startX = event.clientX;
      const startSize = sidebarSize;

      const handlePointerMove = (moveEvent: PointerEvent) => {
        const delta = moveEvent.clientX - startX;
        setSidebarSize(clamp(startSize + delta, sidebarMinSize, sidebarMaxSize));
      };

      const stopResize = () => {
        window.removeEventListener("pointermove", handlePointerMove);
        window.removeEventListener("pointerup", stopResize);
      };

      window.addEventListener("pointermove", handlePointerMove);
      window.addEventListener("pointerup", stopResize);
    },
    [setSidebarSize, sidebarMaxSize, sidebarMinSize, sidebarSize],
  );

  const isIsland = appearance === "island";

  return (
    <div className={cn("flex h-full w-full overflow-hidden", isIsland && "bg-sidebar", className)}>
      {sidebar && !sidebarCollapsed && (
        <>
          <aside
            className={cn(
              "hidden h-full shrink-0 md:flex",
              isIsland ? "bg-transparent" : "bg-sidebar",
            )}
            style={{ width: `${sidebarSize}px` }}
            data-collapsed="false"
          >
            {sidebar}
          </aside>
          <div
            role="separator"
            aria-label="Resize sidebar"
            aria-orientation="vertical"
            aria-valuemin={sidebarMinSize}
            aria-valuemax={sidebarMaxSize}
            aria-valuenow={sidebarSize}
            tabIndex={0}
            onPointerDown={handleSidebarResizeStart}
            onKeyDown={(event) => {
              if (event.key === "ArrowLeft") {
                setSidebarSize((size) => clamp(size - 12, sidebarMinSize, sidebarMaxSize));
              }
              if (event.key === "ArrowRight") {
                setSidebarSize((size) => clamp(size + 12, sidebarMinSize, sidebarMaxSize));
              }
            }}
            className="group relative hidden w-px cursor-col-resize items-stretch justify-center py-4 md:flex"
          >
            <div className="h-full w-px bg-border/80 opacity-70 transition-[opacity,background-color,box-shadow] duration-150 group-hover:bg-foreground/40 group-hover:opacity-100 group-hover:shadow-[0_0_0_1px_hsl(var(--foreground)/0.2)] group-focus-visible:bg-foreground/40 group-focus-visible:opacity-100 group-focus-visible:shadow-[0_0_0_1px_hsl(var(--foreground)/0.2)]" />
          </div>
        </>
      )}

      <section
        className={cn(
          "flex min-w-0 flex-1 flex-col",
          isIsland && "m-2 min-h-0",
          !sidebarCollapsed && "ml-0",
          contentClassName,
        )}
      >
        <div
          className={cn(
            "flex min-h-0 min-w-0 flex-1 flex-col",
            isIsland && "overflow-hidden rounded-lg border bg-background shadow-sm",
          )}
        >
          {topbar}
          <SplitView rightPanel={rightPanel} rightPanelWidth={rightPanelWidth}>
            {children}
          </SplitView>
        </div>
      </section>

      {sidebar && (
        <Sheet open={sidebarMobileOpen} onOpenChange={setSidebarMobileOpen}>
          <SheetContent
            side="left"
            className="w-[min(20rem,85vw)] border-r p-0 md:hidden"
            showCloseButton={false}
          >
            <div className="flex h-full min-h-0 flex-col bg-sidebar">{sidebar}</div>
          </SheetContent>
        </Sheet>
      )}

      {rightPanel && (
        <Sheet open={rightPanelMobileOpen} onOpenChange={setRightPanelMobileOpen}>
          <SheetContent
            side="right"
            className="w-[min(24rem,92vw)] border-l p-0 md:hidden"
            showCloseButton={false}
          >
            <div className="flex h-full min-h-0 flex-col bg-background">{rightPanel}</div>
          </SheetContent>
        </Sheet>
      )}
    </div>
  );
}
```


### app-shell-root.tsx

```tsx
"use client";

import { cva } from "class-variance-authority";

import { cn } from "@/lib/utils";

import type { WorkbenchRootProps } from "@/components/workbench-app-shell/workbench-context";
import { WorkbenchRoot } from "@/components/workbench-app-shell/workbench-context";

const shellRootVariants = cva("h-dvh w-full bg-background text-foreground", {
  variants: {
    density: {
      compact: "text-sm",
      comfortable: "text-sm",
      spacious: "text-base",
    },
    shape: {
      workbench: "",
      linear: "[--shell-border-radius:--spacing(2)] [--shell-gap:--spacing(2)]",
      notion: "[--shell-border-radius:--spacing(1)] [--shell-gap:--spacing(1)]",
    },
  },
  defaultVariants: {
    density: "comfortable",
    shape: "workbench",
  },
});

export interface AppShellRootProps extends WorkbenchRootProps {
  className?: string;
  density?: "compact" | "comfortable" | "spacious";
  shape?: "workbench" | "linear" | "notion";
}

export function AppShellRoot({ children, className, density, shape, ...props }: AppShellRootProps) {
  return (
    <WorkbenchRoot {...props}>
      <div className={cn(shellRootVariants({ density, shape }), className)}>{children}</div>
    </WorkbenchRoot>
  );
}
```


### command-hint.tsx

```tsx
"use client";

import type * as React from "react";

import { cn } from "@/lib/utils";

export function CommandHint({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      className={cn("inline-flex items-center gap-1.5 text-xs text-muted-foreground", className)}
      {...props}
    />
  );
}

export function CommandHintText({ className, ...props }: React.ComponentProps<"span">) {
  return <span className={cn("truncate", className)} {...props} />;
}
```


### main-content.tsx

```tsx
"use client";

import type * as React from "react";

import { cn } from "@/lib/utils";

import { OverlayScrollContainer } from "@/components/overlay-scroll-container";

export function MainContent({ className, ...props }: React.ComponentProps<"section">) {
  return <section className={cn("flex min-h-0 min-w-0 flex-1 flex-col", className)} {...props} />;
}

export function ContentHeader({ className, ...props }: React.ComponentProps<"header">) {
  return <header className={cn("border-b px-4 py-2", className)} {...props} />;
}

export function ShellContentScroll({ className, ...props }: React.ComponentPropsWithoutRef<"div">) {
  return <OverlayScrollContainer className={cn("min-h-0 flex-1", className)} {...props} />;
}

export function ContentBody({ className, ...props }: React.ComponentPropsWithoutRef<"div">) {
  return <ShellContentScroll className={cn("p-4", className)} {...props} />;
}
```


### right-panel.tsx

```tsx
"use client";

import { XIcon } from "lucide-react";
import type * as React from "react";

import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

import { OverlayScrollContainer } from "@/components/overlay-scroll-container";
import { useWorkbenchContext } from "@/components/workbench-app-shell/workbench-context";

export function RightPanel({ className, ...props }: React.ComponentProps<"aside">) {
  return <aside className={cn("flex h-full min-h-0 flex-col", className)} {...props} />;
}

export function RightPanelHeader({ className, ...props }: React.ComponentProps<"header">) {
  return (
    <header className={cn("flex items-center gap-2 border-b px-3 py-2", className)} {...props} />
  );
}

export function RightPanelBody({ className, ...props }: React.ComponentProps<"div">) {
  return <OverlayScrollContainer className={cn("min-h-0 flex-1 p-3", className)} {...props} />;
}

export function RightPanelCloseButton({
  className,
  onClick,
  ...props
}: React.ComponentProps<typeof Button>) {
  const { setRightPanelOpen, setRightPanelMobileOpen } = useWorkbenchContext();

  return (
    <Button
      variant="ghost"
      size="icon-sm"
      aria-label="Close right panel"
      className={cn("ml-auto", className)}
      {...props}
      onClick={(event) => {
        onClick?.(event);
        setRightPanelOpen(false);
        setRightPanelMobileOpen(false);
      }}
    >
      <XIcon />
    </Button>
  );
}
```


### settings-shell.tsx

```tsx
"use client";

import type * as React from "react";

import { cn } from "@/lib/utils";

import { OverlayScrollContainer } from "@/components/overlay-scroll-container";

export function SettingsShell({ className, ...props }: React.ComponentProps<"section">) {
  return (
    <section
      className={cn("flex h-full min-h-0 min-w-0 flex-col md:flex-row", className)}
      {...props}
    />
  );
}

export function SettingsNav({ className, ...props }: React.ComponentProps<"nav">) {
  return (
    <OverlayScrollContainer
      element="nav"
      className={cn("h-full border-b p-3 md:w-60 md:shrink-0 md:border-r md:border-b-0", className)}
      {...props}
    />
  );
}

export function SettingsNavGroup({ className, ...props }: React.ComponentProps<"section">) {
  return <section className={cn("mb-4 last:mb-0", className)} {...props} />;
}

export function SettingsNavGroupTitle({
  className,
  children,
  ...props
}: React.ComponentProps<"h3">) {
  return (
    <h3
      className={cn("px-2 pb-1.5 text-xs font-medium text-muted-foreground", className)}
      {...props}
    >
      {children}
    </h3>
  );
}

export interface SettingsNavItemProps extends React.ComponentProps<"button"> {
  active?: boolean;
}

export function SettingsNavItem({ active, className, ...props }: SettingsNavItemProps) {
  return (
    <button
      type="button"
      className={cn(
        "flex w-full items-center rounded-lg px-2 py-1.5 text-left text-sm transition-colors",
        active
          ? "bg-muted font-medium text-foreground"
          : "text-muted-foreground hover:bg-muted/70 hover:text-foreground",
        className,
      )}
      {...props}
    />
  );
}

export function SettingsContent({ className, ...props }: React.ComponentProps<"main">) {
  return (
    <OverlayScrollContainer
      element="main"
      className={cn("h-full min-h-0 flex-1 p-4 md:p-6", className)}
      {...props}
    />
  );
}

export function SettingsSection({ className, ...props }: React.ComponentProps<"section">) {
  return <section className={cn("space-y-3 rounded-xl border p-4", className)} {...props} />;
}

export function SettingsSectionTitle({
  className,
  children,
  ...props
}: React.ComponentProps<"h2">) {
  return (
    <h2 className={cn("text-sm font-semibold", className)} {...props}>
      {children}
    </h2>
  );
}

export function SettingsSectionDescription({ className, ...props }: React.ComponentProps<"p">) {
  return <p className={cn("text-sm text-pretty text-muted-foreground", className)} {...props} />;
}
```


### shell-nav-model.tsx

```tsx
"use client";

import type * as React from "react";

import {
  SidebarItem,
  SidebarItemBadge,
  SidebarItemIcon,
  SidebarItemLabel,
  SidebarSection,
  SidebarSectionTitle,
} from "@/components/workbench-app-shell/sidebar";
import type { ShellNavItem, ShellNavModel } from "@/components/workbench-app-shell/types";

export interface ShellNavModelViewProps {
  model: ShellNavModel;
  renderItem?: (item: ShellNavItem) => React.ReactNode;
}

export function ShellNavModelView({ model, renderItem }: ShellNavModelViewProps) {
  return model.sections.map((section) => (
    <SidebarSection key={section.id}>
      {section.title && <SidebarSectionTitle>{section.title}</SidebarSectionTitle>}
      <div className="space-y-1">
        {section.items.map((item) => (
          <div key={item.id}>
            {renderItem ? (
              renderItem(item)
            ) : (
              <SidebarItem
                active={item.active}
                disabled={item.disabled}
                onClick={item.onSelect}
                tooltip={item.label}
                aria-disabled={item.disabled ? true : undefined}
              >
                {item.icon && <SidebarItemIcon>{item.icon}</SidebarItemIcon>}
                <SidebarItemLabel>{item.label}</SidebarItemLabel>
                {item.badge && <SidebarItemBadge>{item.badge}</SidebarItemBadge>}
              </SidebarItem>
            )}
          </div>
        ))}
      </div>
    </SidebarSection>
  ));
}
```


### sidebar.tsx

```tsx
"use client";

import { mergeProps } from "@base-ui/react/merge-props";
import { useRender } from "@base-ui/react/use-render";
import { cva } from "class-variance-authority";
import { ChevronLeftIcon } from "lucide-react";
import type * as React from "react";

import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
import { cn } from "@/lib/utils";

import { OverlayScrollContainer } from "@/components/overlay-scroll-container";
import { useWorkbenchContext } from "@/components/workbench-app-shell/workbench-context";

const sidebarItemVariants = cva(
  "group/item flex w-full items-center gap-2 rounded-lg px-2 py-1.5 text-sm transition-colors outline-none",
  {
    variants: {
      active: {
        true: "bg-sidebar-accent text-sidebar-accent-foreground",
        false:
          "text-sidebar-foreground/80 hover:bg-sidebar-accent/70 hover:text-sidebar-accent-foreground",
      },
      disabled: {
        true: "pointer-events-none opacity-50",
        false: "",
      },
    },
  },
);

export function Sidebar({ className, ...props }: React.ComponentProps<"aside">) {
  const { sidebarCollapsed } = useWorkbenchContext();

  return (
    <aside
      className={cn("flex h-full min-h-0 w-full flex-col", className)}
      data-collapsed={sidebarCollapsed ? "true" : "false"}
      {...props}
    />
  );
}

export function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div className={cn("p-2", className)} {...props} />;
}

export function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <OverlayScrollContainer
      nativeOverflowClassName="overflow-y-auto"
      className={cn("min-h-0 flex-1 p-2", className)}
      {...props}
    />
  );
}

export function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
  return <div className={cn("mt-auto p-2", className)} {...props} />;
}

export function SidebarSection({ className, ...props }: React.ComponentProps<"section">) {
  return <section className={cn("mb-4 last:mb-0", className)} {...props} />;
}

export function SidebarSectionTitle({ className, children, ...props }: React.ComponentProps<"h3">) {
  return (
    <h3
      className={cn("px-2 pb-1.5 text-xs font-medium text-sidebar-foreground/60", className)}
      {...props}
    >
      {children}
    </h3>
  );
}

export interface SidebarItemProps
  extends React.ComponentProps<"button">, useRender.ComponentProps<"button"> {
  active?: boolean;
  tooltip?: React.ReactNode;
}

export function SidebarItem({
  render,
  className,
  active = false,
  disabled,
  tooltip,
  children,
  ...props
}: SidebarItemProps) {
  const { sidebarCollapsed } = useWorkbenchContext();
  const itemNode = useRender({
    defaultTagName: "button",
    render,
    props: mergeProps(
      {
        type: "button",
        className: cn(sidebarItemVariants({ active, disabled }), className),
        disabled,
        children,
      },
      props,
    ),
    state: {
      active,
      disabled,
      slot: "sidebar-item",
    },
  });

  if (!tooltip || !sidebarCollapsed) {
    return itemNode;
  }

  return (
    <Tooltip>
      <TooltipTrigger render={itemNode} />
      <TooltipContent side="right" sideOffset={6}>
        {tooltip}
      </TooltipContent>
    </Tooltip>
  );
}

export function SidebarItemIcon({ className, ...props }: React.ComponentProps<"span">) {
  return <span className={cn("size-4 shrink-0 [&_svg]:size-4", className)} {...props} />;
}

export function SidebarItemLabel({ className, ...props }: React.ComponentProps<"span">) {
  return <span className={cn("truncate", className)} {...props} />;
}

export function SidebarItemBadge({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      className={cn(
        "ml-auto rounded bg-sidebar-primary/10 px-1.5 py-0.5 text-[11px] font-medium tabular-nums",
        className,
      )}
      {...props}
    />
  );
}

export interface SidebarHeaderBackProps
  extends React.ComponentProps<"button">, useRender.ComponentProps<"button"> {
  label?: React.ReactNode;
}

export function SidebarHeaderBack({
  render,
  className,
  label = "Back to app",
  ...props
}: SidebarHeaderBackProps) {
  return useRender({
    defaultTagName: "button",
    render,
    props: mergeProps(
      {
        type: "button",
        className: cn(
          "inline-flex h-8 items-center gap-1.5 rounded-md px-2 text-sm text-muted-foreground transition-colors hover:text-foreground",
          className,
        ),
        children: (
          <>
            <ChevronLeftIcon className="size-4" />
            <span>{label}</span>
          </>
        ),
      },
      props,
    ),
    state: {
      slot: "sidebar-header-back",
    },
  });
}
```


### split-view.tsx

```tsx
"use client";

import * as React from "react";

import { cn } from "@/lib/utils";

import { useWorkbenchContext } from "@/components/workbench-app-shell/workbench-context";

export interface SplitViewProps {
  children: React.ReactNode;
  rightPanel?: React.ReactNode;
  rightPanelOpen?: boolean;
  onRightPanelOpenChange?: (open: boolean) => void;
  rightPanelWidth?: number;
  className?: string;
  closeOnEscape?: boolean;
}

export function SplitView({
  children,
  rightPanel,
  rightPanelOpen,
  onRightPanelOpenChange,
  rightPanelWidth = 320,
  className,
  closeOnEscape = true,
}: SplitViewProps) {
  const { rightPanelOpen: contextPanelOpen, setRightPanelOpen } = useWorkbenchContext();

  const open = rightPanelOpen ?? contextPanelOpen;
  const setOpen = onRightPanelOpenChange ?? setRightPanelOpen;

  React.useEffect(() => {
    if (!closeOnEscape || !open) {
      return undefined;
    }

    const handleKeyDown = (event: KeyboardEvent) => {
      if (event.key === "Escape") {
        setOpen(false);
      }
    };

    window.addEventListener("keydown", handleKeyDown);
    return () => window.removeEventListener("keydown", handleKeyDown);
  }, [closeOnEscape, open, setOpen]);

  return (
    <div className={cn("flex min-h-0 min-w-0 flex-1", className)}>
      <main className="flex min-w-0 flex-1 flex-col">{children}</main>

      {rightPanel && open && (
        <aside
          className="hidden shrink-0 border-l bg-background md:block"
          style={{ width: `${rightPanelWidth}px` }}
        >
          {rightPanel}
        </aside>
      )}
    </div>
  );
}
```


### topbar.tsx

```tsx
"use client";

import { MenuIcon, PanelLeftIcon, PanelRightIcon } from "lucide-react";
import type * as React from "react";

import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

import { useWorkbenchContext } from "@/components/workbench-app-shell/workbench-context";

export function Topbar({ className, ...props }: React.ComponentProps<"header">) {
  return (
    <header
      className={cn("flex h-12 shrink-0 items-center gap-2 border-b px-3", className)}
      {...props}
    />
  );
}

export function TopbarSidebarToggle({
  className,
  onClick,
  ...props
}: React.ComponentProps<typeof Button>) {
  const { sidebarCollapsed, setSidebarCollapsed, setSidebarMobileOpen } = useWorkbenchContext();

  return (
    <>
      <Button
        variant="ghost"
        size="icon-sm"
        aria-label="Toggle sidebar"
        className={cn("hidden md:inline-flex", className)}
        {...props}
        onClick={(event) => {
          onClick?.(event);
          setSidebarCollapsed(!sidebarCollapsed);
        }}
      >
        <PanelLeftIcon />
      </Button>
      <Button
        variant="ghost"
        size="icon-sm"
        aria-label="Open sidebar"
        className={cn("inline-flex md:hidden", className)}
        {...props}
        onClick={(event) => {
          onClick?.(event);
          setSidebarMobileOpen(true);
        }}
      >
        <MenuIcon />
      </Button>
    </>
  );
}

export function TopbarRightPanelToggle({
  className,
  onClick,
  ...props
}: React.ComponentProps<typeof Button>) {
  const { rightPanelOpen, setRightPanelOpen, setRightPanelMobileOpen } = useWorkbenchContext();

  return (
    <>
      <Button
        variant="ghost"
        size="icon-sm"
        aria-label="Toggle right panel"
        className={cn("hidden md:inline-flex", className)}
        {...props}
        onClick={(event) => {
          onClick?.(event);
          setRightPanelOpen(!rightPanelOpen);
        }}
      >
        <PanelRightIcon />
      </Button>
      <Button
        variant="ghost"
        size="icon-sm"
        aria-label="Open right panel"
        className={cn("inline-flex md:hidden", className)}
        {...props}
        onClick={(event) => {
          onClick?.(event);
          setRightPanelMobileOpen(true);
        }}
      >
        <PanelRightIcon />
      </Button>
    </>
  );
}

export function TopbarTitle({ className, children, ...props }: React.ComponentProps<"h1">) {
  return (
    <h1 className={cn("truncate text-sm font-semibold", className)} {...props}>
      {children}
    </h1>
  );
}

export function TopbarBreadcrumbs({ className, ...props }: React.ComponentProps<"nav">) {
  return (
    <nav
      className={cn("flex items-center gap-1.5 text-xs text-muted-foreground", className)}
      {...props}
    />
  );
}

export function TopbarViewTabs({ className, ...props }: React.ComponentProps<"div">) {
  return <div className={cn("ml-2 hidden items-center gap-1.5 md:flex", className)} {...props} />;
}

export function TopbarActions({ className, ...props }: React.ComponentProps<"div">) {
  return <div className={cn("ml-auto flex items-center gap-1.5", className)} {...props} />;
}
```


### types.ts

```ts
import type * as React from "react";

export interface ShellNavItem {
  id: string;
  label: string;
  to?: string;
  icon?: React.ReactNode;
  badge?: React.ReactNode;
  shortcut?: string;
  disabled?: boolean;
  active?: boolean;
  onSelect?: () => void;
}

export interface ShellNavSection {
  id: string;
  title?: string;
  items: ShellNavItem[];
}

export interface ShellNavModel {
  sections: ShellNavSection[];
}
```


### use-controllable-state.ts

```ts
import * as React from "react";

export interface UseControllableStateOptions<T> {
  value?: T;
  defaultValue: T;
  onChange?: (nextValue: T) => void;
}

export function useControllableState<T>({
  value,
  defaultValue,
  onChange,
}: UseControllableStateOptions<T>) {
  const [internalValue, setInternalValue] = React.useState(defaultValue);
  const isControlled = value !== undefined;
  const currentValue = isControlled ? value : internalValue;
  const valueRef = React.useRef(currentValue);

  React.useEffect(() => {
    valueRef.current = currentValue;
  }, [currentValue]);

  const setValue = React.useCallback(
    (nextValue: T | ((prev: T) => T)) => {
      const prevValue = valueRef.current;
      const resolvedValue = isStateUpdater(nextValue) ? nextValue(prevValue) : nextValue;

      valueRef.current = resolvedValue;

      if (!isControlled) {
        setInternalValue(resolvedValue);
      }

      onChange?.(resolvedValue);
    },
    [isControlled, onChange],
  );

  return [currentValue, setValue] as const;
}

function isStateUpdater<T>(value: T | ((prev: T) => T)): value is (prev: T) => T {
  return typeof value === "function";
}
```


### workbench-context.tsx

```tsx
"use client";

import * as React from "react";

import { useControllableState } from "@/components/workbench-app-shell/use-controllable-state";

export interface WorkbenchRootProps {
  children: React.ReactNode;
  sidebarCollapsed?: boolean;
  defaultSidebarCollapsed?: boolean;
  onSidebarCollapsedChange?: (collapsed: boolean) => void;
  sidebarSize?: number;
  defaultSidebarSize?: number;
  onSidebarSizeChange?: (size: number) => void;
  sidebarMinSize?: number;
  sidebarMaxSize?: number;
  sidebarMobileOpen?: boolean;
  defaultSidebarMobileOpen?: boolean;
  onSidebarMobileOpenChange?: (open: boolean) => void;
  rightPanelOpen?: boolean;
  defaultRightPanelOpen?: boolean;
  onRightPanelOpenChange?: (open: boolean) => void;
  rightPanelMobileOpen?: boolean;
  defaultRightPanelMobileOpen?: boolean;
  onRightPanelMobileOpenChange?: (open: boolean) => void;
}

export interface WorkbenchContextValue {
  sidebarCollapsed: boolean;
  setSidebarCollapsed: (collapsed: boolean | ((prev: boolean) => boolean)) => void;
  sidebarSize: number;
  setSidebarSize: (size: number | ((prev: number) => number)) => void;
  sidebarMinSize: number;
  sidebarMaxSize: number;
  sidebarMobileOpen: boolean;
  setSidebarMobileOpen: (open: boolean | ((prev: boolean) => boolean)) => void;
  rightPanelOpen: boolean;
  setRightPanelOpen: (open: boolean | ((prev: boolean) => boolean)) => void;
  rightPanelMobileOpen: boolean;
  setRightPanelMobileOpen: (open: boolean | ((prev: boolean) => boolean)) => void;
}

const WorkbenchContext = React.createContext<WorkbenchContextValue | null>(null);

export function WorkbenchRoot({
  children,
  sidebarCollapsed,
  defaultSidebarCollapsed = false,
  onSidebarCollapsedChange,
  sidebarSize,
  defaultSidebarSize = 272,
  onSidebarSizeChange,
  sidebarMinSize = 220,
  sidebarMaxSize = 360,
  sidebarMobileOpen,
  defaultSidebarMobileOpen = false,
  onSidebarMobileOpenChange,
  rightPanelOpen,
  defaultRightPanelOpen = false,
  onRightPanelOpenChange,
  rightPanelMobileOpen,
  defaultRightPanelMobileOpen = false,
  onRightPanelMobileOpenChange,
}: WorkbenchRootProps) {
  const [collapsed, setCollapsed] = useControllableState({
    value: sidebarCollapsed,
    defaultValue: defaultSidebarCollapsed,
    onChange: onSidebarCollapsedChange,
  });

  const [mobileSidebarOpen, setMobileSidebarOpen] = useControllableState({
    value: sidebarMobileOpen,
    defaultValue: defaultSidebarMobileOpen,
    onChange: onSidebarMobileOpenChange,
  });

  const [resolvedSidebarSize, setResolvedSidebarSize] = useControllableState({
    value: sidebarSize,
    defaultValue: defaultSidebarSize,
    onChange: onSidebarSizeChange,
  });

  const [panelOpen, setPanelOpen] = useControllableState({
    value: rightPanelOpen,
    defaultValue: defaultRightPanelOpen,
    onChange: onRightPanelOpenChange,
  });

  const [mobilePanelOpen, setMobilePanelOpen] = useControllableState({
    value: rightPanelMobileOpen,
    defaultValue: defaultRightPanelMobileOpen,
    onChange: onRightPanelMobileOpenChange,
  });

  const value = React.useMemo<WorkbenchContextValue>(
    () => ({
      sidebarCollapsed: collapsed,
      setSidebarCollapsed: setCollapsed,
      sidebarSize: resolvedSidebarSize,
      setSidebarSize: setResolvedSidebarSize,
      sidebarMinSize,
      sidebarMaxSize,
      sidebarMobileOpen: mobileSidebarOpen,
      setSidebarMobileOpen: setMobileSidebarOpen,
      rightPanelOpen: panelOpen,
      setRightPanelOpen: setPanelOpen,
      rightPanelMobileOpen: mobilePanelOpen,
      setRightPanelMobileOpen: setMobilePanelOpen,
    }),
    [
      collapsed,
      mobilePanelOpen,
      mobileSidebarOpen,
      panelOpen,
      resolvedSidebarSize,
      setCollapsed,
      setMobilePanelOpen,
      setMobileSidebarOpen,
      setPanelOpen,
      setResolvedSidebarSize,
      sidebarMaxSize,
      sidebarMinSize,
    ],
  );

  return <WorkbenchContext value={value}>{children}</WorkbenchContext>;
}

// eslint-disable-next-line react-refresh/only-export-components
export function useWorkbenchContext() {
  const context = React.use(WorkbenchContext);
  if (!context) {
    throw new Error("useWorkbenchContext must be used within WorkbenchRoot");
  }

  return context;
}
```



## Usage

A resizable workbench application shell with sidebar, topbar, split view, right panel, and settings primitives.

```tsx
import { AppShellLayout, AppShellRoot } from "@/components/workbench-app-shell";
```


---

URL: https://pi-shadcn.vercel.app/utilities.md

Hooks, libraries, pages, files, themes, fonts, bases, styles, and other items.

# Utilities

Hooks, libraries, pages, files, themes, fonts, bases, styles, and other items.

- [useCopyToClipboard](https://pi-shadcn.vercel.app/utilities/use-copy-to-clipboard): A small hook that copies text and tracks the latest copy result.


---

URL: https://pi-shadcn.vercel.app/utilities/use-copy-to-clipboard.md

A small hook that copies text and tracks the latest copy result.

# useCopyToClipboard

A small hook that copies text and tracks the latest copy result.

## Installation

```bash
npx shadcn@latest add https://pi-shadcn.vercel.app/r/use-copy-to-clipboard.json
```

[Registry JSON](https://pi-shadcn.vercel.app/r/use-copy-to-clipboard.json)

## Preview

```tsx
import { Button } from "@/components/ui/button";

import { useCopyToClipboard } from "@/hooks/use-copy-to-clipboard";

export function Preview() {
  const copyState = useCopyToClipboard();
  const copyValue = "npx shadcn@latest add https://example.com/r/example-card.json";

  return (
    <div className="flex flex-col items-center gap-3 text-center">
      <Button onClick={() => void copyState.copy(copyValue)}>Copy example command</Button>
      <p className="text-sm text-muted-foreground">
        {copyState.status === "copied" ? "Copied to clipboard." : "Ready to copy."}
      </p>
    </div>
  );
}
```


## Source

### hooks/use-copy-to-clipboard.ts

```ts
"use client";

import * as React from "react";

type CopyState =
  | {
      status: "idle";
      value: null;
      error: null;
    }
  | {
      status: "copied";
      value: string;
      error: null;
    }
  | {
      status: "error";
      value: null;
      error: Error;
    };

function useCopyToClipboard() {
  const [state, setState] = React.useState<CopyState>({
    status: "idle",
    value: null,
    error: null,
  });

  const copy = React.useCallback(async (value: string) => {
    try {
      await navigator.clipboard.writeText(value);
      setState({ status: "copied", value, error: null });
      return true;
    } catch (error) {
      const copyError = error instanceof Error ? error : new Error("Copy failed.");

      setState({ status: "error", value: null, error: copyError });
      return false;
    }
  }, []);

  const reset = React.useCallback(() => {
    setState({ status: "idle", value: null, error: null });
  }, []);

  return { ...state, copy, reset };
}

export { useCopyToClipboard, type CopyState };
```



## Usage

Call `copy` with the text you want to place on the clipboard. The hook exposes the latest copy
status so your UI can respond after the operation completes.

```tsx
import { useCopyToClipboard } from "@/hooks/use-copy-to-clipboard";

export function CopyButton() {
  const copyState = useCopyToClipboard();

  return (
    <button onClick={() => void copyState.copy("Copied from my app")}>
      {copyState.status === "copied" ? "Copied" : "Copy"}
    </button>
  );
}
```