@apliteni/apliteni-ui 0.78.0 → 0.80.0

package/guidelines/component-choice.md

@@ -20,7 +20,7 @@
 
 **Why:** A confirm keeps keyboard focus until answered; a callout does not interrupt.
 
-**Except:** Use a content-sized modal for a short form and a drawer for a long form.
+**Except:** Use a content-sized modal or a drawer for a short form, and a page for a long one.
 
 **Do:** Ask “Rotate this token?” in a confirm with “Keep token” and “Rotate token” buttons.
 

package/guidelines/drawer.md

@@ -8,11 +8,25 @@
 
 **Why:** Closing the drawer returns the user to the opened row.
 
-**Do:** Use a drawer for a short filter, a new key, or a reclassification.
+**Do:** Open one for a quick edit, a new key, a filter, or a peek at a row’s detail.
 
-**Don't:** Use it for work needing an address, multiple screens, or steps; use a page instead.
+**Don't:** Open one for a long form, several steps, or a view with its own address and Back.
 
-**Except:** Two-answer questions use confirm. Short forms fit; forms needing steps or more than one screen use a page.
+**Except:** A two-answer question uses confirm, not a drawer.
+
+## Drawer or page
+
+<!-- rule: drawer-or-page -->
+
+**Rule:** Use a page to edit more than one group, and a drawer for one short change.
+
+**Why:** Several groups need room to move between them and check them before saving.
+
+**Do:** Edit the roles and the per-unit switches on a page, under a way back to the list.
+
+**Don't:** Edit the same groups in a drawer, stacked in one narrow panel over the list.
+
+**Except:** Change one field inline, without a panel. A drawer may show groups a reader only reads.
 
 ## Grouped content
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.78.0",
+  "version": "0.80.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -700,3 +700,89 @@ the accent from a checked box.
 <Checkbox label="Full access" type="radio" name="scope" value="full" />
 <Switch label="Email notifications" checked={email} onChange={event => setEmail(event.currentTarget.checked)} />
 ```
+
+## DatePicker
+
+`DatePicker` picks one month (`mode="month"`, the default), a range of months
+(`mode="range"`), one date (`mode="day"`) or a range of dates (`mode="day-range"`). It
+uses the dropdown's own trigger and panel, so it sits beside a `Dropdown` as the same
+control. Periods are ISO strings in the mode's grain: `'2026-08'` for months,
+`'2026-08-14'` for dates. Pass `value`/`onChange` for the single-period modes and
+`range`/`onRangeChange` for the two range modes, or `defaultValue`/`defaultRange` to
+leave the state to the component. Import both the kit CSS and the React CSS.
+
+```tsx
+<DatePicker value={month} onChange={setMonth}
+  min="2025-01" max="2026-12" disabledPeriods={['2026-07']} />
+
+<DatePicker mode="range" range={span} onRangeChange={setSpan}
+  presets={[{ label: 'This year', range: { start: '2026-01', end: '2026-12' } }]} />
+
+<DatePicker mode="day-range" range={span} onRangeChange={setSpan}
+  presets={[{ label: 'This week', range: { start: '2026-09-14', end: '2026-09-20' } }]} />
+```
+
+**The trigger shows the value and nothing else.** There is no field name in front of it:
+"Period: Apr 2026 – Aug 2026" says "period" twice, and the picker has no word to add that
+the value does not already carry. Where the surrounding screen leaves the control
+unexplained, name it with `ariaLabel`, which names the trigger and the panel without
+drawing anything.
+
+**The grid has one tab stop.** The arrows move one period and one row, Home and End go to
+the ends of the row — they never leave the month, so the blank slots a day grid pads its
+first and last weeks with are not somewhere they can take you — Page Up and Page Down
+move a year in the month modes and a month in day mode, Enter and Space pick, and Escape
+closes and returns focus to the trigger. A move past the edge of the shown year or month
+turns the page and keeps the reader on the period they moved to. Each cell's accessible
+name says what the cell is: `selected` for the pick in every mode, plus `range start`,
+`range end` and `in range` in range mode, and `this month` or `today`.
+
+**Bounds hold against your code as well as the reader's.** `min`, `max` and
+`disabledPeriods` are `string`, so a period in the other grain is converted rather than
+dropped: in day mode `min="2026-09"` is 1 September and `max="2026-09"` is the 30th, and
+`disabledPeriods={['2026-09']}` blocks the whole month; in month mode a date means the
+month it falls in. Blocked cells get `aria-disabled` and refuse the press while staying
+focusable. A page step with nowhere to go is disabled.
+
+**A range mode takes a start, then an end**, staying open in between; a second pick above
+or below the first always reads as the same range, so the ends swap rather than
+restarting. `range` and `day-range` differ only in grain — a range may run past the page
+it started on, and the span is painted on both pages.
+`onRangeChange` fires on each end, so `{ start, end: null }` reaches you too. `presets`
+set both ends at once and are held to the same bounds the grid is: a preset that overruns
+them is clamped, one with no overlap at all is disabled, and one whose end lands on a
+blocked period is disabled too rather than quietly moved inwards. A blocked period between
+the two ends is still inside the range you are handed — `{ start, end }` is a pair and
+spans it — and says so in its accessible name; only the tint is withheld, because the
+disabled ink over it cannot be read. To exclude a period, split the range and show two
+pickers.
+
+**Blocked beats every other state in the paint, and the label is struck through.** Block
+the period your own `value` names and the cell goes bare, keeping its place by weight
+rather than wearing the accent fill under disabled ink; the strike is what says
+unavailable before the pointer is anywhere near it. A cell under the pointer takes the
+kit's neutral row hover, so the accent stays on the pick and the span. Its name still
+says `selected` and the gridcell still carries `aria-selected`: it is still your value,
+it just cannot be pressed.
+
+**The period you are in now wears a ring** — hollow for the period you are in, filled for
+the one you chose — and the cell's own name says "this month" or "today". Nothing is drawn
+under the grid to explain it: a key is a second place to read, and these marks are the
+ones a calendar has always drawn. There is no slot for a consumer's own note on a period
+either; a 5px dot can only be read against a key, and a note about a period belongs on the
+surface that shows that period's numbers. The month grid draws its twelve names at one
+length — "Sep", not en-GB's "Sept" — so no cell reads as emphasised; a locale that numbers
+its months keeps its own names.
+
+**Below 560px the panel is a bottom `Drawer`**, so the sheet has the kit's scrim, close
+control and focus trap and the page behind it is inert. Pass `sheet` to force that at any
+width — a host that already knows it is on a phone, or one rendering where no viewport
+can be read, should, because the picker reads the viewport with `matchMedia` and starts
+as the popover until it has.
+
+Pass `today` (a `'YYYY-MM-DD'` date) to fix what the grid calls today — stories and tests
+use it to stay the same whenever they run. `locale` names the months and weekdays,
+`weekStartsOn` sets the first column in day mode, and `align="end"` hangs the panel off
+the trigger's trailing edge. Without `ariaLabel` the trigger's own text is its accessible
+name, so a control reading "17 September 2026" is heard as that rather than as its
+placeholder. The popover stays mounted while closed, and is `inert` while it is.

package/react/dist/index.css

@@ -31,14 +31,15 @@
   --tap-min: 44px;
   --tap-aa: 24px;
   --tap-gap: var(--space-5, 20px);
+  --tap-gap-bordered: calc(var(--tap-min) - var(--tap-aa) + 2px);
   --tap-clear-x: 0px;
   --tap-clear-y: 0px;
 }
 @media (max-width: 560px) and (pointer: coarse) {
-  :where(.ui-seg button, .ui-tabs__tab, .ui-dropdown__trigger, .ui-toast__action, .ui-drawer__close, .ui-snippet__copy, .ui-footer__social) {
+  :where(.ui-seg button, .ui-tabs__tab, .ui-dropdown__trigger, .ui-toast__action, .ui-drawer__close, .ui-snippet__copy, .ui-footer__social, .ui-datepicker__opt) {
     position: relative;
   }
-  :where(.ui-btn, .ui-seg button, .ui-tabs__tab, .ui-dropdown__trigger, .ui-toast__action, .ui-drawer__close, .ui-snippet__copy, .ui-footer__social, .ui-switch)::after {
+  :where(.ui-btn, .ui-seg button, .ui-tabs__tab, .ui-dropdown__trigger, .ui-toast__action, .ui-drawer__close, .ui-snippet__copy, .ui-footer__social, .ui-switch, .ui-datepicker__opt)::after {
     content: "";
     position: absolute;
     left: 50%;
@@ -109,6 +110,19 @@
     row-gap: var(--tap-gap) !important;
     --tap-clear-y: var(--tap-gap);
   }
+  .ui-datepicker__grid {
+    row-gap: var(--tap-gap) !important;
+    --tap-clear-x: var(--space-1, 4px);
+    --tap-clear-y: var(--tap-gap);
+  }
+  .ui-datepicker__head {
+    --tap-clear-x: var(--tap-gap-bordered);
+    --tap-clear-y: var(--tap-gap-bordered);
+  }
+  .ui-datepicker__presets {
+    --tap-clear-x: var(--space-1, 4px);
+    --tap-clear-y: var(--tap-gap-bordered);
+  }
   .ui-footer__socials,
   .ui-drawer__header {
     gap: var(--tap-gap) !important;
@@ -284,6 +298,168 @@
   }
 }
 
+/* src/DatePicker.css */
+.ui-datepicker__panel {
+  --ui-dropdown-pad: var(--space-3);
+  width: max-content;
+  min-width: 0;
+  max-width: 92vw;
+}
+.ui-datepicker__body {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-4);
+}
+.ui-datepicker__calendar {
+  display: grid;
+  gap: var(--space-3);
+}
+.ui-datepicker__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-2);
+}
+.ui-datepicker__caption {
+  font-size: var(--text-sm);
+  font-weight: var(--weight-semibold);
+  color: var(--strong);
+}
+.ui-datepicker__grid {
+  display: grid;
+  gap: var(--space-1);
+}
+.ui-datepicker__row {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: var(--space-1);
+}
+.ui-datepicker__grid.is-days .ui-datepicker__row {
+  grid-template-columns: repeat(7, minmax(0, 1fr));
+}
+.ui-datepicker__weekday {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: var(--text-xs);
+  font-weight: var(--weight-semibold);
+  color: var(--text);
+}
+.ui-datepicker__cell {
+  display: flex;
+}
+.ui-datepicker__opt {
+  position: relative;
+  flex: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 34px;
+  min-height: 34px;
+  padding: var(--space-2);
+  font-size: var(--text-sm);
+  font-weight: var(--weight-medium);
+  font-variant-numeric: tabular-nums;
+  color: var(--text);
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--radius-xs);
+  cursor: pointer;
+  transition:
+    background var(--dur-fast) var(--ease),
+    border-color var(--dur-fast) var(--ease),
+    color var(--dur-fast) var(--ease);
+}
+.ui-datepicker__grid.is-days .ui-datepicker__opt {
+  min-width: 30px;
+}
+.ui-datepicker__opt:hover {
+  outline: 1px solid var(--control-edge);
+  outline-offset: -1px;
+  background: var(--surface);
+  color: var(--strong);
+}
+.ui-datepicker__opt:focus-visible {
+  outline: 2px solid transparent;
+}
+.ui-datepicker__opt.is-inside {
+  background: color-mix(in srgb, var(--accent) 14%, var(--bg-elevated));
+}
+.ui-datepicker__opt.is-selected {
+  background: var(--accent-strong);
+  border-color: var(--accent-strong);
+  color: var(--accent-contrast);
+}
+.ui-datepicker__opt.is-selected:hover {
+  outline-color: transparent;
+  background: var(--accent-strong);
+  color: var(--accent-contrast);
+}
+.ui-datepicker__opt.is-today {
+  border-color: var(--accent);
+}
+.ui-datepicker__opt.is-today:hover {
+  outline-color: transparent;
+}
+.ui-datepicker__opt.is-selected.is-today {
+  border-color: var(--accent-contrast);
+}
+.ui-datepicker__opt.is-disabled {
+  color: var(--disabled-ink-bare);
+  cursor: not-allowed;
+}
+.ui-datepicker__opt.is-disabled .ui-datepicker__num {
+  text-decoration: line-through;
+}
+.ui-datepicker__opt.is-disabled:hover {
+  outline-color: transparent;
+  background: transparent;
+  border-color: transparent;
+  color: var(--disabled-ink-bare);
+}
+.ui-datepicker__opt.is-disabled.is-selected,
+.ui-datepicker__opt.is-disabled.is-selected:hover,
+.ui-datepicker__opt.is-disabled.is-inside,
+.ui-datepicker__opt.is-disabled.is-inside:hover {
+  background: transparent;
+  border-color: transparent;
+  color: var(--disabled-ink-bare);
+}
+.ui-datepicker__opt.is-disabled.is-selected {
+  font-weight: var(--weight-bold);
+}
+.ui-datepicker__opt.is-disabled.is-today,
+.ui-datepicker__opt.is-disabled.is-today:hover {
+  border-color: var(--accent);
+}
+.ui-datepicker__presets {
+  display: grid;
+  align-content: start;
+  gap: var(--space-1);
+  padding: 0 var(--space-3) 0 0;
+  border-inline-end: 1px solid var(--border);
+}
+.ui-datepicker__preset {
+  justify-content: flex-start;
+}
+.ui-datepicker__body.is-sheet {
+  flex-direction: column;
+  align-items: stretch;
+}
+.ui-datepicker__body.is-sheet .ui-datepicker__presets {
+  grid-auto-flow: column;
+  grid-auto-columns: max-content;
+  overflow-x: auto;
+  scroll-padding-inline: var(--space-1);
+  padding: var(--space-3) var(--space-1);
+  border-inline-end: 0;
+  border-block-end: 1px solid var(--border);
+}
+.ui-datepicker__body.is-sheet .ui-datepicker__presets:focus-visible {
+  outline: var(--ring-scroll);
+  outline-offset: var(--ring-scroll-offset);
+}
+
 /* src/KeyValueList.css */
 .ui-kv {
   display: grid;

package/react/dist/index.d.ts

@@ -325,6 +325,69 @@ type DeniedProps = {
 };
 declare function Denied({ title, sub, need, icon, className, children, }: DeniedProps): react.JSX.Element;
 
+/**
+ * `'month'` and `'range'` work in whole months, `'day'` and `'day-range'` in
+ * whole dates. The two range modes behave alike: a start, then an end, with the
+ * days or months between them shown as the span.
+ */
+type DatePickerMode = 'month' | 'range' | 'day' | 'day-range';
+/** Either end may be null while the reader is still picking. */
+type DatePickerRange = {
+    start: string | null;
+    end: string | null;
+};
+type DatePickerPreset = {
+    label: string;
+    range: DatePickerRange;
+};
+type DatePickerProps = {
+    mode?: DatePickerMode;
+    /** `'YYYY-MM'` in month mode, `'YYYY-MM-DD'` in day mode. Controlled. */
+    value?: string | null;
+    /** Where an uncontrolled picker starts. */
+    defaultValue?: string | null;
+    onChange?: (value: string | null) => void;
+    /** Range mode, controlled. */
+    range?: DatePickerRange;
+    defaultRange?: DatePickerRange;
+    /** Fires on each end, so a half-picked range is visible to the host too. */
+    onRangeChange?: (range: DatePickerRange) => void;
+    /** Bounds, inclusive, in the mode's own grain. */
+    min?: string;
+    max?: string;
+    /** Periods that cannot be picked, in the mode's own grain. */
+    disabledPeriods?: readonly string[];
+    /** Range mode: the shortcuts beside the grid. */
+    presets?: readonly DatePickerPreset[];
+    placeholder?: string;
+    /**
+     * Names the trigger and the panel where the screen around them does not.
+     * With a value, the trigger's own text is already its name.
+     */
+    ariaLabel?: string;
+    id?: string;
+    disabled?: boolean;
+    /** The edge the panel hugs. */
+    align?: 'start' | 'end';
+    /** Month and weekday names come from here. */
+    locale?: string;
+    /** 0 is Sunday. Day mode only. */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /** `'YYYY-MM-DD'`. Given one, the grid marks it; stories and tests pass it to stay fixed. */
+    today?: string;
+    /**
+     * Render the sheet rather than the popover whatever the viewport is. Left
+     * out, the picker follows the kit's narrowest step. A host that already knows
+     * it is on a phone — or renders on a server, where no viewport is readable —
+     * says so here.
+     */
+    sheet?: boolean;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+};
+declare function DatePicker({ mode, value, defaultValue, onChange, range, defaultRange, onRangeChange, min, max, disabledPeriods, presets, placeholder, ariaLabel, id, disabled, align, locale, weekStartsOn, today, sheet, open: openProp, defaultOpen, onOpenChange, }: DatePickerProps): react.JSX.Element;
+
 type DropdownBadge = string | {
     text: string;
     tone?: string;
@@ -868,4 +931,4 @@ declare const SidebarNav: react.ForwardRefExoticComponent<Omit<Omit<react.Detail
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };
+export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };