@petrarca/sonnet-ui 0.3.0 → 0.4.1

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>>;
@@ -619,6 +654,61 @@ interface EntityTableProps<TRow extends RowData> {
 }
 declare function EntityTable<TRow extends RowData>(props: EntityTableProps<TRow>): React__default.ReactElement;
 
+/**
+ * PropertyList — read-only display of a record's properties as a stacked list.
+ *
+ * Layout matches the established graph node/edge cards: an uppercase muted key
+ * label above each value, values rendered by {@link PropertyValue}. Optional
+ * per-property schema refines value rendering (schema is NOT required).
+ *
+ * Shared by the graph view's node/edge cards and the table inspector so all
+ * property displays look identical.
+ */
+
+interface PropertyListProps {
+    /** Property name -> value. */
+    properties: Record<string, unknown>;
+    /** Optional property name -> schema, to refine value rendering. */
+    propertySchemas?: Record<string, JsonSchemaProperty>;
+    /** Show a "PROPERTIES" section header. Default false. */
+    showHeader?: boolean;
+    /** Click value to copy it to the clipboard. Default true. */
+    copyable?: boolean;
+    /** Message when there are no properties. Default "No properties". */
+    emptyLabel?: string;
+    className?: string;
+}
+declare function PropertyList({ properties, propertySchemas, showHeader, copyable, emptyLabel, className, }: PropertyListProps): React__default.ReactElement;
+
+/**
+ * PropertyValue — read-only, type-aware rendering of a single property value.
+ *
+ * Reliable model (matches graph-explorer best practice): render by the actual
+ * VALUE TYPE, never by guessing string contents.
+ *   - object / array  -> collapsed summary that expands to a JSON tree (bounded box)
+ *   - long string     -> clamped to a few lines with a "Show more" toggle
+ *   - scalar          -> inline text
+ *   - boolean         -> true/false (or schema boolean cell)
+ *   - array of scalars-> comma list
+ *
+ * Schema is OPTIONAL and only REFINES rendering when present:
+ *   - x-ui-cell / inferred type/format (date, datetime, boolean, number)
+ *   - x-ui-cell: "json" forces a JSON tree even for a string value
+ * A plain string is treated as text by default — it is NOT auto-parsed as
+ * JSON (avoids fragile, surprising behaviour). Schema is the only signal that
+ * turns a JSON-looking string into a tree.
+ */
+
+interface PropertyValueProps {
+    value: unknown;
+    /** Optional schema for this property; refines rendering when present. */
+    schema?: JsonSchemaProperty;
+    className?: string;
+    /** Strings longer than this clamp with a "Show more" toggle. */
+    clampChars?: number;
+}
+declare function PropertyValue({ value, schema, className, clampChars, }: PropertyValueProps): React__default.ReactElement;
+
 /**
  * EntitySelect -- async searchable single-select for entity references.
  *
@@ -990,4 +1080,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, PropertyList, type PropertyListProps, PropertyValue, type PropertyValueProps, 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 };