@platned/ui 0.7.0 → 0.7.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, HTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, RefObject, ReactElement, Ref, AnchorHTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, Component, ErrorInfo } from 'react';
+import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, HTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, ChangeEventHandler, RefObject, ReactElement, Ref, AnchorHTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, Component, ErrorInfo } from 'react';
 import { ClassValue } from 'clsx';
 import { Column, Table as Table$1, ColumnDef, RowData, SortingState, ColumnFiltersState, PaginationState, VisibilityState, RowSelectionState, TableOptions } from '@tanstack/react-table';
 export { CellContext, ColumnDef, ColumnFiltersState, Column as DataTableColumn, Table as DataTableInstance, HeaderContext, PaginationState, Row, RowSelectionState, SortingState, VisibilityState, createColumnHelper } from '@tanstack/react-table';
@@ -339,22 +339,54 @@ interface SelectProps extends SelectControlProps {
  */
 declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLButtonElement>>;
 
-interface DatePickerProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+interface DatePickerProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type' | 'value' | 'defaultValue'> {
     label?: string;
     description?: string;
     /** Red border + message shown below the control. Also sets `aria-invalid`. */
     error?: string;
     hint?: string;
     size?: InputSize;
-}
-/**
- * A native `<input type="date">`.
- *
- * The `::-webkit-calendar-picker-indicator` styling below is Chromium-only — on Firefox
- * and Safari the native affordance differs, so the drawn `CalendarIcon` sits alongside
- * whatever the platform renders rather than replacing it. That is a known limitation of
- * this component, not a bug to paper over: for a real month grid, range selection, locale
- * control or min/max navigation, use `Calendar` and `DateField` instead.
+    /** The selected date as an ISO `YYYY-MM-DD` string, `''` for none. Controlled. */
+    value?: string;
+    /** Initial ISO date when uncontrolled. */
+    defaultValue?: string;
+    /**
+     * Called with a real change event from the underlying date input, so
+     * `onChange={(e) => set(e.target.value)}` keeps working; `e.target.value` is the ISO date.
+     */
+    onChange?: ChangeEventHandler<HTMLInputElement>;
+    /** The new ISO date. New in 0.7.1; an alternative to reading `onChange`'s event. */
+    onValueChange?: (value: string) => void;
+    /** Shown when there is no date. Default "Pick a date". */
+    placeholder?: string;
+    /** BCP 47 tag for the shown date and the calendar. Default: the browser's. */
+    locale?: string;
+    /** 0 = Sunday, 1 = Monday. Default `1`. */
+    weekStartsOn?: 0 | 1;
+    /** `dropdown` (default) puts month and year selects in the calendar header. */
+    captionLayout?: 'label' | 'dropdown';
+    /** First year in the year select. Default `min`'s year, else 100 years ago. */
+    startYear?: number;
+    /** Last year in the year select. Default `max`'s year, else 10 years ahead. */
+    endYear?: number;
+}
+/**
+ * A date field that opens the library's `Calendar` in a `Popover`, the shape of shadcn/ui's
+ * Date Picker. Rebuilt in 0.7.1: through 0.7.0 it was a native `<input type="date">`, whose
+ * picker is the browser's own and differs in Chromium, Firefox and Safari (Firefox draws its
+ * own button inside the field and cannot be restyled), so it never matched `Calendar`.
+ *
+ * - The trigger is a `role="combobox"` button with `aria-haspopup="dialog"`, named by the label
+ *   and then the date ("Start date 22 Oct 2026"); unlike a plain button, that role carries the
+ *   `aria-required` and `aria-invalid` that `Field` supplies.
+ * - Opening moves focus into the calendar grid, on the selected date or today. Picking a date
+ *   closes the popover and returns focus to the trigger; Escape closes it without a change.
+ * - The month and year selects (`captionLayout="dropdown"`, the default) reach a far-away date
+ *   in two choices instead of a PageUp per month.
+ * - A real, invisible `<input type="date">` keeps the old contract: it carries `name`, `value`,
+ *   `min`, `max` and `required` for forms and native validation, the forwarded ref points at
+ *   it, and `onChange` receives its genuine change event. When validation focuses it, focus is
+ *   handed to the trigger.
  */
 declare const DatePicker: react.ForwardRefExoticComponent<DatePickerProps & react.RefAttributes<HTMLInputElement>>;
 
@@ -1253,6 +1285,17 @@ interface CalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'>
     locale?: string;
     /** Names the grid. Default `Calendar`. */
     label?: string;
+    /**
+     * `label` (default) shows the month as text between the arrows. `dropdown` replaces it with
+     * month and year selects, for dates far from today (a date of birth, a start date years ago),
+     * which would otherwise take a dozen PageUp presses a year to reach. Same name and behaviour
+     * as shadcn/react-day-picker's `captionLayout="dropdown"`. New in 0.7.1.
+     */
+    captionLayout?: 'label' | 'dropdown';
+    /** First year in the year select. Default `min`'s year, else 100 years ago. */
+    startYear?: number;
+    /** Last year in the year select. Default `max`'s year, else 10 years ahead. */
+    endYear?: number;
 }
 /**
  * Month grid. Matches Figma's `Calendar`, `Calendar Button`
@@ -1270,11 +1313,12 @@ interface CalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'>
  *   42 individually tabbable buttons takes 42 presses to get past.
  * - **Arrows cross month boundaries.** Pressing Left on the 1st moves to the previous
  *   month's last day and pages the view, rather than dead-ending.
- * - **PageUp/PageDown** move by month, **Home/End** to the start/end of the week.
+ * - **PageUp/PageDown** move by month, **Shift+PageUp/PageDown** by year, **Home/End** to the
+ *   start/end of the week.
  * - Each day's accessible name is the full date, not the number — "14" tells a screen
  *   reader user nothing.
  */
-declare function Calendar({ mode, value, range, onSelect, onRangeChange, defaultMonth, min, max, isDateDisabled, weekStartsOn, locale, label, className, ...rest }: CalendarProps): react.JSX.Element;
+declare function Calendar({ mode, value, range, onSelect, onRangeChange, defaultMonth, min, max, isDateDisabled, weekStartsOn, locale, label, captionLayout, startYear, endYear, className, ...rest }: CalendarProps): react.JSX.Element;
 
 type InputGroupAlign = 'inline-start' | 'inline-end' | 'block-start' | 'block-end';
 interface InputGroupProps extends HTMLAttributes<HTMLDivElement> {
@@ -1547,6 +1591,8 @@ interface PopoverContentProps extends HTMLAttributes<HTMLDivElement> {
     label?: string;
     /** Where to portal the panel. Defaults to the enclosing dialog, else `document.body`. */
     container?: HTMLElement | null;
+    /** Radix's open auto-focus hook: `preventDefault()` and focus something else, e.g. a calendar's selected day. */
+    onOpenAutoFocus?: (event: Event) => void;
 }
 declare const PopoverContent: react.ForwardRefExoticComponent<PopoverContentProps & react.RefAttributes<HTMLDivElement>>;
 /** Closes the enclosing popover, e.g. an "Apply" or "Cancel" button. New in 0.7.0. */
@@ -4325,6 +4371,12 @@ interface TableProps extends HTMLAttributes<HTMLTableElement> {
     density?: TableDensity;
     /** Equal-width columns driven by `<colgroup>`, matching `DataTable`. Default `false`. */
     fixed?: boolean;
+    /**
+     * Cap the height (px number or CSS length) and scroll the body inside it. Pair with
+     * `<TableHead sticky>` to keep the header row in view. The wrapper becomes a focusable region
+     * named by `label`, so the keyboard can scroll it. New in 0.7.1.
+     */
+    maxHeight?: number | string;
 }
 declare const Table: react.ForwardRefExoticComponent<TableProps & react.RefAttributes<HTMLTableElement>>;
 interface TableCaptionProps extends HTMLAttributes<HTMLTableCaptionElement> {
@@ -4479,7 +4531,12 @@ interface TableCellProgressProps {
     size?: TableCellSize;
     className?: string;
 }
-/** Mini progress bar with a percentage label below. */
+/**
+ * Mini progress bar with its percentage at the end. The bar fills whatever width the cell gives
+ * it, as shadcn's Progress (`w-full`), Ant Design's line Progress and MUI's LinearProgress do:
+ * through 0.7.0 it was a fixed 48 / 64px, which left most of a wide column, or of a card field in
+ * the responsive layout, empty. `size` now sets the bar's thickness (4 / 6px).
+ */
 declare function TableCellProgress({ percent, tone, size, className, }: TableCellProgressProps): react.JSX.Element;
 
 type DataTableColumnAlign = 'start' | 'center' | 'end';
@@ -4627,6 +4684,13 @@ interface DataTableProps<TData, TValue = unknown> {
     responsive?: boolean | {
         breakpoint?: number;
     };
+    /**
+     * Cap the table's height (px number or any CSS length) and scroll the body inside it, with the
+     * header row pinned. Works with horizontal scrolling and sticky columns, and caps the card list
+     * in the responsive layout. The pattern of MUI's `TableContainer` + `stickyHeader` and Ant
+     * Design's `scroll.y`. New in 0.7.1.
+     */
+    maxHeight?: number | string;
     manual?: DataTableManual;
     /** Controlled state. Any key you pass is controlled; the rest stay internal. */
     state?: Partial<DataTableState>;
@@ -4662,7 +4726,7 @@ interface DataTableProps<TData, TValue = unknown> {
  * while loading, a polite announcement of the result count after a search, keyboard row
  * activation, and named selection checkboxes.
  */
-declare function DataTable<TData, TValue = unknown>({ columns, data, getRowId, label, caption, searchable, columnVisibility: showColumnMenu, pagination: paginated, pageSize, pageSizeOptions, enableRowSelection, onSelectionChange, getRowLabel, onRowClick, getRowHref, renderRowLink, getRowTone, getRowDimmed, loading, loadingRows, error, onRetry, empty, toolbar, footer, density, align, responsive, manual, state, onSortingChange, onGlobalFilterChange, onColumnFiltersChange, onPaginationChange, onColumnVisibilityChange, onRowSelectionChange, tableOptions, className, }: DataTableProps<TData, TValue>): react.JSX.Element;
+declare function DataTable<TData, TValue = unknown>({ columns, data, getRowId, label, caption, searchable, columnVisibility: showColumnMenu, pagination: paginated, pageSize, pageSizeOptions, enableRowSelection, onSelectionChange, getRowLabel, onRowClick, getRowHref, renderRowLink, getRowTone, getRowDimmed, loading, loadingRows, error, onRetry, empty, toolbar, footer, density, align, responsive, maxHeight, manual, state, onSortingChange, onGlobalFilterChange, onColumnFiltersChange, onPaginationChange, onColumnVisibilityChange, onRowSelectionChange, tableOptions, className, }: DataTableProps<TData, TValue>): react.JSX.Element;
 
 /**
  * Tracks an element's rendered content-box width. New in 0.7.0, from SCIC.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, HTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, RefObject, ReactElement, Ref, AnchorHTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, Component, ErrorInfo } from 'react';
+import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, HTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, ChangeEventHandler, RefObject, ReactElement, Ref, AnchorHTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, Component, ErrorInfo } from 'react';
 import { ClassValue } from 'clsx';
 import { Column, Table as Table$1, ColumnDef, RowData, SortingState, ColumnFiltersState, PaginationState, VisibilityState, RowSelectionState, TableOptions } from '@tanstack/react-table';
 export { CellContext, ColumnDef, ColumnFiltersState, Column as DataTableColumn, Table as DataTableInstance, HeaderContext, PaginationState, Row, RowSelectionState, SortingState, VisibilityState, createColumnHelper } from '@tanstack/react-table';
@@ -339,22 +339,54 @@ interface SelectProps extends SelectControlProps {
  */
 declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLButtonElement>>;
 
-interface DatePickerProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+interface DatePickerProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type' | 'value' | 'defaultValue'> {
     label?: string;
     description?: string;
     /** Red border + message shown below the control. Also sets `aria-invalid`. */
     error?: string;
     hint?: string;
     size?: InputSize;
-}
-/**
- * A native `<input type="date">`.
- *
- * The `::-webkit-calendar-picker-indicator` styling below is Chromium-only — on Firefox
- * and Safari the native affordance differs, so the drawn `CalendarIcon` sits alongside
- * whatever the platform renders rather than replacing it. That is a known limitation of
- * this component, not a bug to paper over: for a real month grid, range selection, locale
- * control or min/max navigation, use `Calendar` and `DateField` instead.
+    /** The selected date as an ISO `YYYY-MM-DD` string, `''` for none. Controlled. */
+    value?: string;
+    /** Initial ISO date when uncontrolled. */
+    defaultValue?: string;
+    /**
+     * Called with a real change event from the underlying date input, so
+     * `onChange={(e) => set(e.target.value)}` keeps working; `e.target.value` is the ISO date.
+     */
+    onChange?: ChangeEventHandler<HTMLInputElement>;
+    /** The new ISO date. New in 0.7.1; an alternative to reading `onChange`'s event. */
+    onValueChange?: (value: string) => void;
+    /** Shown when there is no date. Default "Pick a date". */
+    placeholder?: string;
+    /** BCP 47 tag for the shown date and the calendar. Default: the browser's. */
+    locale?: string;
+    /** 0 = Sunday, 1 = Monday. Default `1`. */
+    weekStartsOn?: 0 | 1;
+    /** `dropdown` (default) puts month and year selects in the calendar header. */
+    captionLayout?: 'label' | 'dropdown';
+    /** First year in the year select. Default `min`'s year, else 100 years ago. */
+    startYear?: number;
+    /** Last year in the year select. Default `max`'s year, else 10 years ahead. */
+    endYear?: number;
+}
+/**
+ * A date field that opens the library's `Calendar` in a `Popover`, the shape of shadcn/ui's
+ * Date Picker. Rebuilt in 0.7.1: through 0.7.0 it was a native `<input type="date">`, whose
+ * picker is the browser's own and differs in Chromium, Firefox and Safari (Firefox draws its
+ * own button inside the field and cannot be restyled), so it never matched `Calendar`.
+ *
+ * - The trigger is a `role="combobox"` button with `aria-haspopup="dialog"`, named by the label
+ *   and then the date ("Start date 22 Oct 2026"); unlike a plain button, that role carries the
+ *   `aria-required` and `aria-invalid` that `Field` supplies.
+ * - Opening moves focus into the calendar grid, on the selected date or today. Picking a date
+ *   closes the popover and returns focus to the trigger; Escape closes it without a change.
+ * - The month and year selects (`captionLayout="dropdown"`, the default) reach a far-away date
+ *   in two choices instead of a PageUp per month.
+ * - A real, invisible `<input type="date">` keeps the old contract: it carries `name`, `value`,
+ *   `min`, `max` and `required` for forms and native validation, the forwarded ref points at
+ *   it, and `onChange` receives its genuine change event. When validation focuses it, focus is
+ *   handed to the trigger.
  */
 declare const DatePicker: react.ForwardRefExoticComponent<DatePickerProps & react.RefAttributes<HTMLInputElement>>;
 
@@ -1253,6 +1285,17 @@ interface CalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'>
     locale?: string;
     /** Names the grid. Default `Calendar`. */
     label?: string;
+    /**
+     * `label` (default) shows the month as text between the arrows. `dropdown` replaces it with
+     * month and year selects, for dates far from today (a date of birth, a start date years ago),
+     * which would otherwise take a dozen PageUp presses a year to reach. Same name and behaviour
+     * as shadcn/react-day-picker's `captionLayout="dropdown"`. New in 0.7.1.
+     */
+    captionLayout?: 'label' | 'dropdown';
+    /** First year in the year select. Default `min`'s year, else 100 years ago. */
+    startYear?: number;
+    /** Last year in the year select. Default `max`'s year, else 10 years ahead. */
+    endYear?: number;
 }
 /**
  * Month grid. Matches Figma's `Calendar`, `Calendar Button`
@@ -1270,11 +1313,12 @@ interface CalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'>
  *   42 individually tabbable buttons takes 42 presses to get past.
  * - **Arrows cross month boundaries.** Pressing Left on the 1st moves to the previous
  *   month's last day and pages the view, rather than dead-ending.
- * - **PageUp/PageDown** move by month, **Home/End** to the start/end of the week.
+ * - **PageUp/PageDown** move by month, **Shift+PageUp/PageDown** by year, **Home/End** to the
+ *   start/end of the week.
  * - Each day's accessible name is the full date, not the number — "14" tells a screen
  *   reader user nothing.
  */
-declare function Calendar({ mode, value, range, onSelect, onRangeChange, defaultMonth, min, max, isDateDisabled, weekStartsOn, locale, label, className, ...rest }: CalendarProps): react.JSX.Element;
+declare function Calendar({ mode, value, range, onSelect, onRangeChange, defaultMonth, min, max, isDateDisabled, weekStartsOn, locale, label, captionLayout, startYear, endYear, className, ...rest }: CalendarProps): react.JSX.Element;
 
 type InputGroupAlign = 'inline-start' | 'inline-end' | 'block-start' | 'block-end';
 interface InputGroupProps extends HTMLAttributes<HTMLDivElement> {
@@ -1547,6 +1591,8 @@ interface PopoverContentProps extends HTMLAttributes<HTMLDivElement> {
     label?: string;
     /** Where to portal the panel. Defaults to the enclosing dialog, else `document.body`. */
     container?: HTMLElement | null;
+    /** Radix's open auto-focus hook: `preventDefault()` and focus something else, e.g. a calendar's selected day. */
+    onOpenAutoFocus?: (event: Event) => void;
 }
 declare const PopoverContent: react.ForwardRefExoticComponent<PopoverContentProps & react.RefAttributes<HTMLDivElement>>;
 /** Closes the enclosing popover, e.g. an "Apply" or "Cancel" button. New in 0.7.0. */
@@ -4325,6 +4371,12 @@ interface TableProps extends HTMLAttributes<HTMLTableElement> {
     density?: TableDensity;
     /** Equal-width columns driven by `<colgroup>`, matching `DataTable`. Default `false`. */
     fixed?: boolean;
+    /**
+     * Cap the height (px number or CSS length) and scroll the body inside it. Pair with
+     * `<TableHead sticky>` to keep the header row in view. The wrapper becomes a focusable region
+     * named by `label`, so the keyboard can scroll it. New in 0.7.1.
+     */
+    maxHeight?: number | string;
 }
 declare const Table: react.ForwardRefExoticComponent<TableProps & react.RefAttributes<HTMLTableElement>>;
 interface TableCaptionProps extends HTMLAttributes<HTMLTableCaptionElement> {
@@ -4479,7 +4531,12 @@ interface TableCellProgressProps {
     size?: TableCellSize;
     className?: string;
 }
-/** Mini progress bar with a percentage label below. */
+/**
+ * Mini progress bar with its percentage at the end. The bar fills whatever width the cell gives
+ * it, as shadcn's Progress (`w-full`), Ant Design's line Progress and MUI's LinearProgress do:
+ * through 0.7.0 it was a fixed 48 / 64px, which left most of a wide column, or of a card field in
+ * the responsive layout, empty. `size` now sets the bar's thickness (4 / 6px).
+ */
 declare function TableCellProgress({ percent, tone, size, className, }: TableCellProgressProps): react.JSX.Element;
 
 type DataTableColumnAlign = 'start' | 'center' | 'end';
@@ -4627,6 +4684,13 @@ interface DataTableProps<TData, TValue = unknown> {
     responsive?: boolean | {
         breakpoint?: number;
     };
+    /**
+     * Cap the table's height (px number or any CSS length) and scroll the body inside it, with the
+     * header row pinned. Works with horizontal scrolling and sticky columns, and caps the card list
+     * in the responsive layout. The pattern of MUI's `TableContainer` + `stickyHeader` and Ant
+     * Design's `scroll.y`. New in 0.7.1.
+     */
+    maxHeight?: number | string;
     manual?: DataTableManual;
     /** Controlled state. Any key you pass is controlled; the rest stay internal. */
     state?: Partial<DataTableState>;
@@ -4662,7 +4726,7 @@ interface DataTableProps<TData, TValue = unknown> {
  * while loading, a polite announcement of the result count after a search, keyboard row
  * activation, and named selection checkboxes.
  */
-declare function DataTable<TData, TValue = unknown>({ columns, data, getRowId, label, caption, searchable, columnVisibility: showColumnMenu, pagination: paginated, pageSize, pageSizeOptions, enableRowSelection, onSelectionChange, getRowLabel, onRowClick, getRowHref, renderRowLink, getRowTone, getRowDimmed, loading, loadingRows, error, onRetry, empty, toolbar, footer, density, align, responsive, manual, state, onSortingChange, onGlobalFilterChange, onColumnFiltersChange, onPaginationChange, onColumnVisibilityChange, onRowSelectionChange, tableOptions, className, }: DataTableProps<TData, TValue>): react.JSX.Element;
+declare function DataTable<TData, TValue = unknown>({ columns, data, getRowId, label, caption, searchable, columnVisibility: showColumnMenu, pagination: paginated, pageSize, pageSizeOptions, enableRowSelection, onSelectionChange, getRowLabel, onRowClick, getRowHref, renderRowLink, getRowTone, getRowDimmed, loading, loadingRows, error, onRetry, empty, toolbar, footer, density, align, responsive, maxHeight, manual, state, onSortingChange, onGlobalFilterChange, onColumnFiltersChange, onPaginationChange, onColumnVisibilityChange, onRowSelectionChange, tableOptions, className, }: DataTableProps<TData, TValue>): react.JSX.Element;
 
 /**
  * Tracks an element's rendered content-box width. New in 0.7.0, from SCIC.