@petrarca/sonnet-playground

Playground framework and built-in component demos for the Petrarca Sonnet component library.

What's included

Playground framework — Registry, overview tile grid, and createPlaygroundModule() factory. Wire a playground into any sonnet-shell app with a few lines.

Built-in demos — Pre-built showcase pages for all Sonnet components: Typography, Color Palette, Core UI, Advanced Components, JSON Editor, Forms, Form Components, Form Widgets, Data Components, Graph Visualization, Shell API.

PlaygroundSection — Shared section wrapper (default and card variants) used by all playground pages.

Install

pnpm add @petrarca/sonnet-playground

Peer dependencies: react, react-dom, @petrarca/sonnet-shell, @petrarca/sonnet-ui, @petrarca/sonnet-forms, @petrarca/sonnet-graph.

Basic usage

// src/modules/playground/index.ts
import {
  createPlaygroundRegistry,
  createPlaygroundModule,
} from "@petrarca/sonnet-playground";

const registry = createPlaygroundRegistry();

// Optionally add app-specific pages:
registry.register({
  id: "app.my-page",
  title: "My Page",
  description: "Custom demo page.",
  icon: SomeIcon,
  color: "teal",
  path: "my-page",
  component: React.lazy(() => import("./pages/MyPage")),
  group: "App",
  order: 0,
});

export default createPlaygroundModule(registry);

// src/modules/registry.ts
import { createModuleRegistry } from "@petrarca/sonnet-shell";
import home from "./home";
import playground from "./playground";

export const registry = createModuleRegistry([
  home,
  playground, // pinBottom: true is set automatically by createPlaygroundModule
]);

createPlaygroundModule returns a ShellModule — pass it directly to createModuleRegistry alongside your app's own modules.

Adding app-specific pages

Register your own pages alongside the built-in demos by calling registry.register() before passing the registry to createPlaygroundModule. Pages appear in the overview tile grid grouped under your chosen group label.

// src/modules/playground/index.ts
import { lazy } from "react";
import { Search } from "lucide-react";
import {
  createPlaygroundRegistry,
  createPlaygroundModule,
} from "@petrarca/sonnet-playground";

const registry = createPlaygroundRegistry();

// Register app-specific pages
registry.register({
  id: "app.my-widget",
  title: "My Widget",
  description: "Interactive demo of MyWidget with live configuration.",
  icon: Search,
  color: "teal",
  path: "my-widget",
  component: lazy(() => import("./pages/PlayMyWidget")),
  group: "App Components",  // appears as a group heading in the overview
  order: 0,
});

export default createPlaygroundModule(registry);

Pages are lazy-loaded automatically — wrap the component in React.lazy() as shown above. The framework handles the Suspense boundary.

group is optional. Pages without a group appear under the default group in the overview. Pages with the same group string are grouped together.

Pages subpath

Individual built-in pages are available at @petrarca/sonnet-playground/pages for consumers who want to cherry-pick or re-export them:

import { PlayTypography, PlayColorPalette } from "@petrarca/sonnet-playground/pages";

createPlaygroundModule options

| Option | Type | Default | |---|---|---| | icon | LucideIcon | FlaskConical | | label | string | "Playground" | | basePath | string | "/playground" | | overviewTitle | string | "Developer Playground" | | overviewSubtitle | string | "" | | grouped | boolean | true |

License

See LICENSE.md.