@apliteni/apliteni-ui 0.77.0 → 0.79.0

package/guidelines/file-drop.md

@@ -0,0 +1,87 @@
+# File drop
+
+## Spend one row at rest
+
+<!-- rule: one-row -->
+
+**Rule:** At rest, a file drop is one row: the button that opens the picker and the accepted types beside it.
+
+**Why:** A tall box holds the page's best space open for a file that arrives once a month.
+
+**Do:** Put an Upload button and “PDF or CSV, up to 10 MB” on one line above the list they feed.
+
+**Don't:** Draw a tall dashed box with a glyph, an invitation and a button stacked inside it.
+
+**Except:** A page whose whole purpose is receiving one file may use the field-sized picker, which carries a label of its own.
+
+## Paint the target only while a file is over it
+
+<!-- rule: on-drag -->
+
+**Rule:** Show the drop target while a file is over the region that accepts it, and nowhere else.
+
+**Why:** A target drawn before there is a file to catch covers content the reader still needs.
+
+**Do:** Cover the panel that accepts the file the moment the file crosses it.
+
+**Don't:** Cover the whole window when one panel accepts the file.
+
+## Keep the file in the row it arrived in
+
+<!-- rule: in-the-row -->
+
+**Rule:** After the drop, the file's name, size and progress take the place the button was in, with remove on the name's line.
+
+**Why:** A row that changes in place keeps the page still while the file uploads.
+
+**Do:** Give the name a line with remove at its end, put the size under it, and run the progress track the full width below both.
+
+**Don't:** Push the list down with a progress card, or open a dialog over the page.
+
+## Fail in place
+
+<!-- rule: failure -->
+
+**Rule:** A refused file keeps its place, says what it did wrong under its name, and offers Retry beside Remove.
+
+**Why:** A row that drops the file sends the reader back to choosing one. The reason is the one string here that has to be read in full, so it gets a line rather than a share of one.
+
+**Do:** Keep the name on its line and say “Larger than 10 MB” under it, with Retry.
+
+**Don't:** Replace the row with “Upload failed”, losing both the file and the retry.
+
+## Offer a button, not only a drag
+
+<!-- rule: button-path -->
+
+**Rule:** Give the reader a button that opens the picker, and let dragging be the shortcut.
+
+**Why:** A keyboard cannot drag a file.
+
+**Do:** Make the Upload button the control, reachable by keyboard and showing the focus ring.
+
+**Don't:** Write “Drag a file here” with nothing to press.
+
+## State the limits once
+
+<!-- rule: limits-once -->
+
+**Rule:** Name the accepted types and the size limit once, beside the button, in the product's own words.
+
+**Why:** Repeated limits teach the reader to skip them.
+
+**Do:** Write “PDF or CSV, up to 10 MB” beside the button, and let a failure say what this file did wrong.
+
+**Don't:** Repeat the limits under the button, in a tooltip and again in the error.
+
+## Choose the row, the region or the dialog
+
+<!-- rule: which-shape -->
+
+**Rule:** Use a row where the file joins a list on the page, a region when one panel owns the file, and a dialog only when the upload needs answers of its own.
+
+**Why:** A dialog that asks nothing is one more thing to dismiss. The rule picks between three containers, so a drawing would show one of them and not the choice.
+
+**Do:** Take a statement into the row under the statements it joins, and a replacement logo into the panel that shows it.
+
+**Don't:** Open a dialog for one file that the row behind it could have taken.

package/package.json

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

package/react/README.md

@@ -493,6 +493,34 @@ places a decorative kit glyph with `icon` — the same glyph names `Button` and
 `onFileChange`. Use `accept` and `hint` to describe allowed file types and size.
 Your application must validate files before upload.
 
+## File drop
+
+`FileDrop` is the compact drop: one row with the button that opens the picker and
+the accepted types beside it, and a drop target painted only while a file is over
+the region. Use it where a file joins a list on the page; use `FileField` where a
+labelled, field-sized picker belongs. The guideline page states when to use a row,
+a region or a dialog.
+
+```tsx
+<FileDrop note="PDF or CSV, up to 10 MB" accept=".pdf,.csv"
+  file={upload} onFile={send} onRemove={clear} onRetry={send} />
+```
+
+Your application owns the upload and supplies the `file` it is holding: the
+name, the `size` already written for a reader, `progress` while it uploads, and
+the `error` when it failed. A file with no `status` is uploading, so a file
+handed over before the request starts never reads as uploaded. A status the row
+draws shows a mark and a word; where you give `progress` the track says it
+instead, and the word goes to the track's accessible name. The file reads as a
+stack: the name on top with the actions at its end, the size — or the failure
+message — under it, and the track the full width below. No tier takes a second
+line. The name truncates its stem and keeps its extension, with the whole name in
+a `title`, and nothing is hidden or moved at any width. `Remove` is the icon-only
+`x`, named by `removeLabel`; `Retry` keeps its word. Both appear only when you
+handle them. Children render above the row, inside the region the target covers;
+pass `dragging` to drive that target from a parent. `accept` filters the system
+picker only — validate type and size yourself.
+
 Use `Field` when an existing labelled control needs the kit frame. Spread its
 render-prop attributes onto one labelable control, and apply the existing control
 class and invalid styling as appropriate:
@@ -672,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%;
@@ -82,6 +83,14 @@
   .ui-table__act .ui-btn + .ui-btn {
     margin-inline-start: var(--tap-gap) !important;
   }
+  .ui-drop__row {
+    --tap-clear-y: var(--tap-gap);
+  }
+  .ui-drop__actions {
+    gap: var(--tap-gap) !important;
+    --tap-clear-x: var(--tap-gap);
+    --tap-clear-y: var(--tap-gap);
+  }
   .ui-table__act {
     --tap-clear-x: var(--tap-gap);
     --tap-clear-y: 0px;
@@ -101,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;
@@ -276,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;
@@ -498,6 +682,129 @@
   cursor: not-allowed;
 }
 
+/* ../src/styles/file-drop.css */
+.ui-drop {
+  position: relative;
+}
+.ui-drop > * + .ui-drop__row {
+  margin-top: var(--space-3);
+}
+.ui-drop__row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  min-height: var(--space-8);
+  gap: var(--space-2) var(--space-3);
+  font-size: var(--text-sm);
+  color: var(--text);
+  overflow-wrap: anywhere;
+}
+.ui-drop__note {
+  margin: 0;
+}
+.ui-drop__file {
+  display: grid;
+  flex: 1 1 auto;
+  gap: var(--space-2);
+  min-width: 0;
+}
+.ui-drop__line {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 0;
+}
+.ui-drop__name {
+  display: flex;
+  flex: 1 1 auto;
+  min-width: var(--space-10);
+  color: var(--strong);
+  font-weight: var(--weight-medium);
+}
+.ui-drop__stem {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.ui-drop__ext {
+  flex: none;
+}
+.ui-drop__facts {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 0;
+}
+.ui-drop__size {
+  flex: none;
+  white-space: nowrap;
+}
+.ui-drop__word {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 0 1 auto;
+  min-width: 0;
+}
+.ui-drop__state {
+  display: inline-flex;
+  flex: 0 1 auto;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+.ui-drop__state svg {
+  width: 16px;
+  height: 16px;
+  flex: none;
+  stroke-width: 2.4;
+}
+.ui-drop__error {
+  color: var(--pink);
+}
+.ui-drop__actions {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: var(--space-2);
+  margin-left: auto;
+}
+.ui-drop__bar {
+  display: block;
+  width: 100%;
+  height: 6px;
+  border-radius: var(--radius-pill);
+  background: var(--surface-2);
+  overflow: hidden;
+}
+.ui-drop__bar span {
+  display: block;
+  height: 100%;
+  background: var(--accent);
+}
+.ui-drop__target {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--space-3);
+  border: 1px dashed var(--accent);
+  border-radius: var(--radius-md);
+  background: var(--surface);
+  color: var(--strong);
+  font-size: var(--text-sm);
+  text-align: center;
+}
+.ui-drop.is-disabled .ui-drop__row {
+  color: var(--disabled-ink);
+}
+.ui-drop.is-disabled .ui-drop__name {
+  color: var(--disabled-ink);
+}
+
 /* src/Toast.css */
 .rx-toast-stack {
   position: fixed;