@petrarca/sonnet-ui 0.2.0 → 0.4.0

package/README.md

@@ -4,15 +4,22 @@ UI primitives and data components for the Petrarca Sonnet component library.
 
 ## What's included
 
-**UI primitives** -- Tailwind CSS + Radix UI based components following the shadcn pattern: Button, Badge, Card, Dialog, Tabs, Input, Tooltip, Spinner, Stepper, and more.
+**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 components for building data-driven UIs:
-- **EntityTable** -- Schema-driven data 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, edit, drag support
-- **TreeView** -- Generic tree renderer with keyboard navigation
-- **SearchInput** -- Faceted search input with chip-based filters
-- **JsonEditor** -- CodeMirror-based JSON editor with validation highlighting (subpath: `@petrarca/sonnet-ui/json-editor`)
+**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
 
@@ -20,19 +27,78 @@ UI primitives and data components for the Petrarca Sonnet component library.
 pnpm add @petrarca/sonnet-ui @petrarca/sonnet-core
 ```
 
-Peer dependencies: `react`, `react-dom`, `tailwindcss`.
+Peer dependencies: `react >=19`, `react-dom >=19`, `tailwindcss >=3`,
+`tailwindcss-animate`, `@tailwindcss/typography`.
+
+---
+
+## Setup
+
+### CSS
 
-## Tailwind setup
+Import `styles.css` in your app's global CSS. It provides design tokens
+(light + dark), base resets, heading utilities, and typography classes.
 
-Add the package dist to your Tailwind `content` config so component classes are included:
+```css
+/* 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:
+
+```css
+@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.):
 
 ```js
-content: [
-  "./src/**/*.{ts,tsx}",
-  "./node_modules/@petrarca/sonnet-*/dist/**/*.js",
-]
+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
 
-Apache 2.0
+See [LICENSE.md](../../LICENSE.md).

package/dist/index.d.ts

@@ -209,6 +209,41 @@ declare const ScrollBar: React$1.ForwardRefExoticComponent<Omit<ScrollAreaPrimit
 
 declare const Separator: React$1.ForwardRefExoticComponent<Omit<SeparatorPrimitive.SeparatorProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 
+interface ResizeHandleProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Orientation of the handle bar:
+     * - "vertical" (default): a vertical bar separating LEFT/RIGHT panes
+     *   (drag horizontally). Uses `cursor-col-resize`.
+     * - "horizontal": a horizontal bar separating TOP/BOTTOM panes
+     *   (drag vertically). Uses `cursor-row-resize`.
+     */
+    orientation?: "vertical" | "horizontal";
+    /** Length of the centered grip in pixels. Defaults to 48. */
+    gripLength?: number;
+}
+/**
+ * ResizeHandle — a quiet, flat draggable divider between two resizable panes.
+ *
+ * Renders a wide invisible hit-area with a short centered grip (quiet
+ * `bg-border` at rest, `bg-border-strong` on hover), a focus ring, and the
+ * correct `role="separator"` / `aria-orientation` / resize cursor. No
+ * full-height seam line — the adjacent panes own their own edges.
+ *
+ * The consumer owns the resize math: wire `onPointerDown` (and optionally
+ * `onDoubleClick`, `tabIndex`, `aria-valuenow`/min/max) via props.
+ *
+ * @example
+ *   <ResizeHandle
+ *     orientation="vertical"
+ *     aria-valuenow={width}
+ *     aria-valuemin={MIN}
+ *     aria-valuemax={MAX}
+ *     onPointerDown={startResize}
+ *     onDoubleClick={resetWidth}
+ *   />
+ */
+declare const ResizeHandle: React$1.ForwardRefExoticComponent<ResizeHandleProps & React$1.RefAttributes<HTMLDivElement>>;
+
 declare const Sheet: React$1.FC<DialogPrimitive.DialogProps>;
 declare const SheetTrigger: React$1.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & React$1.RefAttributes<HTMLButtonElement>>;
 declare const SheetClose: React$1.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & React$1.RefAttributes<HTMLButtonElement>>;
@@ -990,4 +1025,4 @@ type Props = {
  */
 declare function ClipboardMenu({ onAddItem }: Props): react_jsx_runtime.JSX.Element;
 
-export { Alert, AlertDescription, AlertTitle, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Button, CELL_RENDERERS, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CellRenderer, type CellRendererProps, Checkbox, ClipboardButton, ClipboardItemComponent as ClipboardItem, ClipboardMenu, Collapsible, CollapsibleContent, CollapsibleTrigger, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EntitySelect, type EntitySelectProps, EntityTable, type EntityTableProps, EntityTree, type EntityTreeHandle, type EntityTreeProps, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, Label, Popover, PopoverContent, PopoverTrigger, type ResolvedColumn, type RowAction, ScrollArea, ScrollBar, SearchInput, type SearchMode, Separator, Sheet, SheetBody, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetTitle, SheetTrigger, SimpleGroup, SimpleStack, SimpleTooltip, Skeleton, Spinner, Stepper, StepperContent, StepperDescription, StepperIndicator, StepperItem, StepperList, StepperNext, StepperPrev, type StepperProps, StepperSeparator, StepperTitle, StepperTrigger, type TableUiSchema, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TreeNode, TreeView, type TreeViewHandle, type TreeViewProps, badgeVariants, buttonVariants, createRenderer, useStore as useStepper };
+export { Alert, AlertDescription, AlertTitle, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Button, CELL_RENDERERS, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CellRenderer, type CellRendererProps, Checkbox, ClipboardButton, ClipboardItemComponent as ClipboardItem, ClipboardMenu, Collapsible, CollapsibleContent, CollapsibleTrigger, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EntitySelect, type EntitySelectProps, EntityTable, type EntityTableProps, EntityTree, type EntityTreeHandle, type EntityTreeProps, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, Label, Popover, PopoverContent, PopoverTrigger, ResizeHandle, type ResizeHandleProps, type ResolvedColumn, type RowAction, ScrollArea, ScrollBar, SearchInput, type SearchMode, Separator, Sheet, SheetBody, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetTitle, SheetTrigger, SimpleGroup, SimpleStack, SimpleTooltip, Skeleton, Spinner, Stepper, StepperContent, StepperDescription, StepperIndicator, StepperItem, StepperList, StepperNext, StepperPrev, type StepperProps, StepperSeparator, StepperTitle, StepperTrigger, type TableUiSchema, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TreeNode, TreeView, type TreeViewHandle, type TreeViewProps, badgeVariants, buttonVariants, createRenderer, useStore as useStepper };