@petrarca/sonnet-ui 0.5.0 → 0.7.0

package/README.md

@@ -1,25 +1,29 @@
 # @petrarca/sonnet-ui
 
-UI primitives and data components for the Petrarca Sonnet component library.
+The component layer of the Petrarca Sonnet component library. It ships three
+kinds of thing: a stylesheet of design tokens, a Tailwind preset that maps
+those tokens onto utility classes, and React components.
 
-## What's included
+## What it provides
 
-**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.
+**Primitives.** Buttons, badges, cards, dialogs, sheets, popovers, dropdowns,
+tabs, selects, tooltips, steppers, scroll areas, resize handles and the rest of
+the building blocks, most of them wrapping Radix.
 
-**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`)
+**Data components.** `EntityTable` renders a collection from a schema with
+pagination, row actions and pluggable cell renderers. `SearchInput` produces a
+`FilterExpr` in simple, multi-field or faceted mode. `EntitySelect` is an async
+typeahead over an injected fetcher, `EntityTree` and `TreeView` cover
+hierarchies, and `PropertyList` covers read-only display.
 
-**Design tokens** — Shipped as `styles.css` and `tailwind-preset.js`.
+**Date and time inputs.** Locale-aware date, time and datetime controls with a
+calendar, built on the parsing and formatting layer in `sonnet-core`.
 
----
+**A JSON editor.** CodeMirror with validation and JSON-Pointer-constrained
+editable regions, on its own subpath so the dependency is opt-in.
+
+**Design tokens.** `styles.css` and `tailwind-preset.js`, the two files every
+other `@petrarca/sonnet-*` package renders through.
 
 ## Install
 
@@ -27,44 +31,30 @@ more.
 pnpm add @petrarca/sonnet-ui @petrarca/sonnet-core
 ```
 
-Peer dependencies: `react >=19`, `react-dom >=19`, `tailwindcss >=3`,
-`tailwindcss-animate`, `@tailwindcss/typography`.
-
----
-
-## Setup
-
-### CSS
+| Peer | Range | Needed for |
+|---|---|---|
+| `react`, `react-dom` | `>=19` | Everything |
+| `tailwindcss` | `>=3` | The preset and every component class |
+| `tailwindcss-animate` | `>=1` | Enter and exit animations on overlays |
+| `@tailwindcss/typography` | `>=0.5` | Add the plugin to your Tailwind config |
+| `@uiw/react-codemirror` | `>=4` | The `./json-editor` subpath only |
+| `@codemirror/state`, `@codemirror/view`, `@codemirror/lang-json` | `>=6` | The `./json-editor` subpath only |
 
-Import `styles.css` in your app's global CSS. It provides design tokens
-(light + dark), base resets, heading utilities, and typography classes.
+You do not declare any `@radix-ui/*` package yourself. Radix is a regular
+dependency and arrives transitively
+([ADR-0002](../../docs/adr/0002-radix-is-a-dependency-not-a-peer.md)).
 
-```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; }
-```
+## Usage
 
-Override any token after the import for white-labeling:
+Import the stylesheet and the preset, then use the components.
 
 ```css
+/* src/index.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
+// tailwind.config.js
 module.exports = {
   presets: [require("@petrarca/sonnet-ui/tailwind-preset")],
   content: [
@@ -75,30 +65,39 @@ module.exports = {
 };
 ```
 
----
-
-## Design tokens
-
-All tokens are CSS custom properties (HSL triplets). Key semantic tokens:
+```tsx
+import { Badge, Button, Card, CardContent } from "@petrarca/sonnet-ui";
+
+export function WidgetCard() {
+  return (
+    <Card>
+      <CardContent className="flex items-center gap-2">
+        <Badge badgeColor="green">active</Badge>
+        <Button size="sm">Create</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
 
-| 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 |
+The second content glob and the app-level layout CSS are the two steps most
+often missed. [Getting started](docs/usage/getting-started.md) covers both, and
+the token reference is in [theming](docs/usage/theming.md).
 
-See `DESIGN.md` at the repo root for the full token reference.
+## Documentation
 
----
+- [Usage guides](docs/usage/index.md) -- setup, theming,
+  [primitives](docs/usage/primitives.md),
+  [EntityTable](docs/usage/entity-table.md),
+  [SearchInput](docs/usage/search-input.md),
+  [trees and selects](docs/usage/trees-and-selects.md),
+  [date and time inputs](docs/usage/date-and-time-inputs.md) and the
+  [JSON editor](docs/usage/json-editor.md).
+- [Design docs](docs/design/index.md) -- the token architecture and the
+  reasoning behind the data components.
+- [Workspace documentation](../../docs/README.md) -- the design language, the
+  design system and the architecture decision records.
 
 ## License
 
-See [LICENSE.md](../../LICENSE.md).
+Apache 2.0. See [LICENSE.md](../../LICENSE.md).

package/dist/index.d.ts

@@ -9,6 +9,8 @@ import * as CollapsiblePrimitive from '@radix-ui/react-collapsible';
 import * as DialogPrimitive from '@radix-ui/react-dialog';
 import { DialogProps } from '@radix-ui/react-dialog';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+import { DatePrecision, TimeGranularity, PageResult } from '@petrarca/sonnet-core';
+import * as SelectPrimitive from '@radix-ui/react-select';
 import * as LabelPrimitive from '@radix-ui/react-label';
 import * as PopoverPrimitive from '@radix-ui/react-popover';
 import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
@@ -17,7 +19,6 @@ import * as TabsPrimitive from '@radix-ui/react-tabs';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 import { RowData, PaginationState, OnChangeFn } from '@tanstack/react-table';
 export { PaginationState } from '@tanstack/react-table';
-import { PageResult } from '@petrarca/sonnet-core';
 import { UISchema, JsonSchemaProperty, JsonSchema } from '@petrarca/sonnet-core/schema';
 import { EntitySelectMode } from '@petrarca/sonnet-core/hooks';
 import { EntityOptionFetcher, EntityOption } from '@petrarca/sonnet-core/entityOptions';
@@ -228,6 +229,144 @@ declare const DropdownMenuShortcut: {
 
 declare const Input: React$1.ForwardRefExoticComponent<Omit<React$1.DetailedHTMLProps<React$1.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & React$1.RefAttributes<HTMLInputElement>>;
 
+/** Renders a field-level error message below an input. */
+declare function InputError({ error, }: {
+    error: string | undefined;
+}): React$1.ReactElement | null;
+
+/**
+ * DateInput -- text input with a calendar popover for a single date.
+ *
+ * The value is a partial ISO 8601 date string -- `"YYYY"`, `"YYYY-MM"`, or
+ * `"YYYY-MM-DD"` depending on `precision`. Typed entry is parsed leniently
+ * (see {@link parseDate}); `"t"`, `"today"`, or `"."` enter the current date;
+ * calendar selection drills down to the terminal precision. Empty value emits "".
+ */
+
+interface DateInputProps {
+    /** Partial ISO date string (`YYYY`, `YYYY-MM`, or `YYYY-MM-DD`), or "". */
+    value?: string;
+    /** Called with the new partial ISO date string, or "" when cleared. */
+    onChange: (value: string) => void;
+    /** Selection precision. Default `"day"`. */
+    precision?: DatePrecision;
+    /** BCP-47 locale override for display/parsing. Defaults to the app locale. */
+    locale?: string;
+    id?: string;
+    name?: string;
+    placeholder?: string;
+    required?: boolean;
+    disabled?: boolean;
+    error?: string;
+    className?: string;
+    onBlur?: () => void;
+}
+declare function DateInput({ value, onChange, precision, locale, id, name, placeholder, required, disabled, error, className, onBlur, }: DateInputProps): React$1.ReactElement;
+
+/**
+ * Calendar -- month/year/decade grid for selecting a single day.
+ *
+ * A controlled, dependency-light calendar operating on native `Date`. Renders
+ * three drill-down views (days, months, years) with header navigation. Styling
+ * uses semantic design tokens only.
+ */
+
+interface CalendarProps {
+    /** Currently selected day, or null. */
+    value: Date | null;
+    /** Called when the user picks a date at the terminal precision. */
+    onSelect: (date: Date) => void;
+    /** Month shown when no value is selected. Defaults to today. */
+    defaultViewDate?: Date;
+    /**
+     * Precision at which selection completes: `"year"` stops on the years view,
+     * `"month"` on the months view, `"day"` on the days view (default).
+     */
+    precision?: DatePrecision;
+    /** BCP-47 locale for month/weekday labels and week-start. */
+    locale?: string;
+}
+declare function Calendar({ value, onSelect, defaultViewDate, precision, locale, }: CalendarProps): React$1.ReactElement;
+
+/**
+ * TimeInput -- text input for a zone-free time of day.
+ *
+ * The value is a normalized ISO time string -- `"HH:mm"` (minute granularity,
+ * default) or `"HH:mm:ss"` (second granularity). A time of day carries no date
+ * and no timezone (Temporal.PlainTime); consumers that need an instant combine
+ * it with a date and zone at persistence time. Typed entry is parsed leniently
+ * (see {@link parseTime}); `"n"`, `"now"`, or `"."` enter the current time.
+ * Empty value emits "".
+ */
+
+interface TimeInputProps {
+    /** Normalized ISO time string (`"HH:mm"` or `"HH:mm:ss"`), or "". */
+    value?: string;
+    /** Called with the new normalized ISO time string, or "" when cleared. */
+    onChange: (value: string) => void;
+    /** Time granularity. Default `"minute"`. */
+    granularity?: TimeGranularity;
+    id?: string;
+    name?: string;
+    placeholder?: string;
+    required?: boolean;
+    disabled?: boolean;
+    error?: string;
+    className?: string;
+    onBlur?: () => void;
+}
+declare function TimeInput({ value, onChange, granularity, id, name, placeholder, required, disabled, error, className, onBlur, }: TimeInputProps): React$1.ReactElement;
+
+/**
+ * DateTimeInput -- combined date + time entry for a plain wall-clock datetime.
+ *
+ * The value is a plain wall-clock ISO string `"YYYY-MM-DDTHH:mm[:ss]"` with no
+ * timezone (Temporal.PlainDateTime). Timezone is intentionally not part of the
+ * input: a wall-clock datetime means "this local time", and resolving it to an
+ * absolute instant (UTC) is the consumer's responsibility at persistence time.
+ *
+ * The optional `timeZone` prop is a pass-through context value (e.g. a clinic's
+ * zone supplied programmatically) shown as a hint -- it is never applied to the
+ * value and is never entered by the user. Cross-zone apps that need an explicit
+ * zone picker should compose one separately.
+ *
+ * Composes {@link DateInput} (day precision) and {@link TimeInput}.
+ */
+
+interface DateTimeInputProps {
+    /** Plain wall-clock ISO datetime `"YYYY-MM-DDTHH:mm[:ss]"`, or "". */
+    value?: string;
+    /** Called with the new plain wall-clock ISO datetime, or "" when cleared. */
+    onChange: (value: string) => void;
+    /** Time granularity. Default `"minute"`. */
+    granularity?: TimeGranularity;
+    /**
+     * Optional timezone context (IANA id, e.g. `"Europe/Berlin"`). Shown as a
+     * hint only; never applied to the value and never user-entered.
+     */
+    timeZone?: string;
+    /** BCP-47 locale override for the date part. Defaults to the app locale. */
+    locale?: string;
+    idPrefix?: string;
+    required?: boolean;
+    disabled?: boolean;
+    error?: string;
+    className?: string;
+    onBlur?: () => void;
+}
+declare function DateTimeInput({ value, onChange, granularity, timeZone, locale, idPrefix, required, disabled, error, className, onBlur, }: DateTimeInputProps): React$1.ReactElement;
+
+declare const Select: React$1.FC<SelectPrimitive.SelectProps>;
+declare const SelectGroup: React$1.ForwardRefExoticComponent<SelectPrimitive.SelectGroupProps & React$1.RefAttributes<HTMLDivElement>>;
+declare const SelectValue: React$1.ForwardRefExoticComponent<SelectPrimitive.SelectValueProps & React$1.RefAttributes<HTMLSpanElement>>;
+declare const SelectTrigger: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectTriggerProps & React$1.RefAttributes<HTMLButtonElement>, "ref"> & React$1.RefAttributes<HTMLButtonElement>>;
+declare const SelectScrollUpButton: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectScrollUpButtonProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+declare const SelectScrollDownButton: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectScrollDownButtonProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+declare const SelectContent: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectContentProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+declare const SelectLabel: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectLabelProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+declare const SelectItem: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectItemProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+declare const SelectSeparator: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectSeparatorProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+
 declare function InputGroup({ className, ...props }: React$1.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
 declare const inputGroupAddonVariants: (props?: ({
     align?: "inline-start" | "inline-end" | "block-start" | "block-end" | null | undefined;
@@ -568,8 +707,19 @@ type TableUiSchema = Record<string, UISchema & {
         label?: string;
     };
 }> & {
+    /**
+     * Table-level options. Reserved for sorting and a sticky header; **neither is
+     * implemented yet**, so setting these has no effect today. Kept declared
+     * because both are intended features -- see the design doc.
+     *
+     * Note this key is unrelated to the `x-ui-globalOptions` of a form UISchema,
+     * which carries `UISchemaOptions` and does work. The two share a name and
+     * nothing else.
+     */
     "x-ui-globalOptions"?: {
+        /** Planned. Sorting is not wired up in EntityTable yet; this has no effect. */
         sortable?: boolean;
+        /** Planned. No sticky positioning is applied yet; this has no effect. */
         stickyHeader?: boolean;
     };
 };
@@ -738,6 +888,16 @@ interface EntityTableProps<TRow extends RowData> {
     showChevron?: boolean;
     selectionMode?: boolean;
     onSelectionChange?: (selectedRows: TRow[]) => void;
+    /**
+     * Stable identity for a row, used to key the selection.
+     *
+     * Without it the selection is keyed by row position, so it means "the rows
+     * currently in these slots" and cannot survive paging or refiltering -- the
+     * table clears it whenever `data` changes to keep that safe. Supply this and
+     * the selection is keyed by identity instead: it survives a page change, and
+     * a bulk action can span pages.
+     */
+    getRowId?: (row: TRow) => string;
     pagination?: PaginationState;
     onPaginationChange?: OnChangeFn<PaginationState>;
     rowActions?: RowAction<TRow>[];
@@ -1086,6 +1246,9 @@ type SearchWidget = React.ComponentType<SearchWidgetProps>;
 /** Registry mapping widget names to their implementations. */
 type SearchWidgetRegistry = Record<string, SearchWidget>;
 
+/** Default search widget registry. Consumers extend this via the widgets prop. */
+declare const DEFAULT_SEARCH_WIDGETS: SearchWidgetRegistry;
+
 /**
  * SearchInput -- controlled search and filter input with chip display.
  *
@@ -1190,4 +1353,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, IconButton, type IconButtonProps, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, Label, Popover, PopoverContent, PopoverTrigger, PropertyList, type PropertyListLayout, 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, TabsSeparator, 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, Calendar, type CalendarProps, 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, DEFAULT_SEARCH_WIDGETS, DateInput, type DateInputProps, DateTimeInput, type DateTimeInputProps, 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, IconButton, type IconButtonProps, Input, InputError, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, Label, Popover, PopoverContent, PopoverTrigger, PropertyList, type PropertyListLayout, type PropertyListProps, PropertyValue, type PropertyValueProps, ResizeHandle, type ResizeHandleProps, type ResolvedColumn, type RowAction, ScrollArea, ScrollBar, SearchInput, type SearchInputProps, type SearchMode, type SearchWidget, type SearchWidgetProps, type SearchWidgetRegistry, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, 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, TabsSeparator, TabsTrigger, Textarea, TimeInput, type TimeInputProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TreeNode, TreeView, type TreeViewHandle, type TreeViewProps, badgeVariants, buttonVariants, createRenderer, useStore as useStepper };