@petrarca/sonnet-ui

UI primitives and data components for the Petrarca Sonnet component library.

What's included

UI primitives — Tailwind + Radix UI components: Button, Badge, Card, Dialog, Tabs, Input, Textarea, Checkbox, Label, Tooltip, Spinner, Avatar, Separator, Stepper, ResizeHandle (draggable divider for resizable panes), and more.

Data components — Higher-level data-driven UI:

• EntityTable — Schema-driven table with pagination, row actions, custom cell renderers
• EntitySelect — Async searchable select with typeahead, backed by a fetcher API
• EntityTree — Hierarchical tree browser with search and edit support
• TreeView — Generic accessible tree with keyboard navigation and row selection
• SearchInput — Faceted search input with chip-based filters (simple, searchFields, faceted modes)
• JsonEditor — CodeMirror JSON editor with validation (subpath: @petrarca/sonnet-ui/json-editor)

Design tokens — Shipped as styles.css and tailwind-preset.js.

Install

pnpm add @petrarca/sonnet-ui @petrarca/sonnet-core

Peer dependencies: react >=19, react-dom >=19, tailwindcss >=3, tailwindcss-animate, @tailwindcss/typography.

Setup

CSS

Import styles.css in your app's global CSS. It provides design tokens (light + dark), base resets, heading utilities, and typography classes.

/* index.css */
@import "@petrarca/sonnet-ui/styles.css";

/* Shell layout — add below the import (app-level, not provided by the library) */
html, body, #root { height: 100%; }
#root { display: flex; flex-direction: column; overflow: hidden; }
body { min-height: 100vh; overflow: hidden; }

Override any token after the import for white-labeling:

@import "@petrarca/sonnet-ui/styles.css";

:root {
  --primary: 210 80% 40%;  /* custom brand color */
}

Tailwind

Use the preset in tailwind.config.js. It maps all design tokens to Tailwind utility classes (bg-primary, text-muted-foreground, border-border, etc.):

module.exports = {
  presets: [require("@petrarca/sonnet-ui/tailwind-preset")],
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@petrarca/sonnet-*/dist/**/*.js",
  ],
  plugins: [require("tailwindcss-animate"), require("@tailwindcss/typography")],
};

Design tokens

All tokens are CSS custom properties (HSL triplets). Key semantic tokens:

| Token | Role | |---|---| | --background / --foreground | Page surface / primary text | | --card / --card-foreground | Card surface / text | | --primary / --primary-foreground | Brand action color | | --destructive | Error / danger | | --muted / --muted-foreground | Quiet surface / secondary text | | --tertiary-foreground | Tertiary text (timestamps, helpers) | | --faint-foreground | Ghost text (annotations, disabled) | | --border / --border-subtle / --border-strong | 3-tier border system | | --state-hover / --state-selected | Interaction state backgrounds | | --ring | Focus ring | | --radius | Base border radius |

See DESIGN.md at the repo root for the full token reference.

License

See LICENSE.md.