shelving 1.301.1 → 1.303.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.301.1",
3
+ "version": "1.303.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -21,7 +21,7 @@ export class ColorSchema extends StringSchema {
21
21
  input,
22
22
  max,
23
23
  min: 1,
24
- rows: 1,
24
+ multiline: false,
25
25
  match: COLOR_REGEXP,
26
26
  });
27
27
  }
@@ -25,7 +25,7 @@ export class CurrencyCodeSchema extends StringSchema {
25
25
  ...options,
26
26
  max, // Valid currency code is 3 uppercase letters.
27
27
  min: 3,
28
- rows: 1,
28
+ multiline: false,
29
29
  case: "upper",
30
30
  match: /^[A-Z]{3}$/, // Valid currency code is 3 uppercase letters.
31
31
  });
@@ -31,7 +31,7 @@ export class EmailSchema extends StringSchema {
31
31
  input,
32
32
  max,
33
33
  min: 1,
34
- rows: 1,
34
+ multiline: false,
35
35
  match: R_MATCH,
36
36
  });
37
37
  }
@@ -19,7 +19,7 @@ export class PhoneSchema extends StringSchema {
19
19
  // Valid phone number is 16 digits or fewer (15 numerals with a leading `+` plus).
20
20
  max,
21
21
  min: 1,
22
- rows: 1,
22
+ multiline: false,
23
23
  // Valid phone number is max 16 digits made up of:
24
24
  // - Country code (`+` plus character and 1-3 digits, e.g. `+44` or `+1`).
25
25
  // - Subscriber number (5-12 digits — the Solomon Islands have five-digit phone numbers apparently).
@@ -19,7 +19,7 @@ export class SlugSchema extends StringSchema {
19
19
  ...options,
20
20
  max,
21
21
  min: 1,
22
- rows: 1,
22
+ multiline: false,
23
23
  });
24
24
  }
25
25
  /** Converts the input into a lowercase, hyphen-separated slug (or `""` if nothing usable remains). */
@@ -28,8 +28,13 @@ export interface StringSchemaOptions extends SchemaOptions {
28
28
  */
29
29
  readonly max?: number | undefined;
30
30
  /**
31
- * Number of rows; more than one enables multiline sanitization.
32
- * @default 1
31
+ * Whether the string keeps line breaks (multiline sanitization). An input for it is a `<textarea>` that grows.
32
+ * @default false
33
+ */
34
+ readonly multiline?: boolean | undefined;
35
+ /**
36
+ * Rows a multiline input shows at first. Set `1` for a box that starts one line high, like a chat message. Single-line inputs ignore it.
37
+ * @default `2` when `multiline`, else `1`
33
38
  */
34
39
  readonly rows?: number | undefined;
35
40
  /** Regular expression the sanitized string must match. */
@@ -56,15 +61,16 @@ export declare class StringSchema extends Schema<string> {
56
61
  readonly min: number;
57
62
  readonly max: number;
58
63
  readonly rows: number;
64
+ readonly multiline: boolean;
59
65
  readonly match: RegExp | undefined;
60
66
  readonly case: "upper" | "lower" | undefined;
61
- constructor({ one, min, max, value, rows, match, case: _case, input, ...options }: StringSchemaOptions);
67
+ constructor({ one, min, max, value, multiline, rows, match, case: _case, input, ...options }: StringSchemaOptions);
62
68
  /** Coerce a value to a string, `sanitize()` it, then enforce `match`, `min`, and `max`. */
63
69
  validate(value?: unknown): string;
64
70
  /**
65
71
  * Sanitize the string by removing unwanted characters.
66
72
  *
67
- * - Uses multiline sanitization when `rows` is greater than one, otherwise single-line sanitization.
73
+ * - Uses multiline sanitization when `multiline` is set, otherwise single-line sanitization.
68
74
  * - Applies the configured `case` folding (`"upper"` or `"lower"`) if set.
69
75
  *
70
76
  * @param str String to sanitize.
@@ -14,13 +14,15 @@ export class StringSchema extends Schema {
14
14
  min;
15
15
  max;
16
16
  rows;
17
+ multiline;
17
18
  match;
18
19
  case;
19
- constructor({ one = "string", min = 0, max = Number.POSITIVE_INFINITY, value = "", rows = 1, match, case: _case, input = "text", ...options }) {
20
+ constructor({ one = "string", min = 0, max = Number.POSITIVE_INFINITY, value = "", multiline = false, rows = multiline ? 2 : 1, match, case: _case, input = "text", ...options }) {
20
21
  super({ one, value, ...options });
21
22
  this.min = min;
22
23
  this.max = max;
23
24
  this.rows = rows;
25
+ this.multiline = multiline;
24
26
  this.match = match;
25
27
  this.case = _case;
26
28
  this.input = input;
@@ -45,7 +47,7 @@ export class StringSchema extends Schema {
45
47
  /**
46
48
  * Sanitize the string by removing unwanted characters.
47
49
  *
48
- * - Uses multiline sanitization when `rows` is greater than one, otherwise single-line sanitization.
50
+ * - Uses multiline sanitization when `multiline` is set, otherwise single-line sanitization.
49
51
  * - Applies the configured `case` folding (`"upper"` or `"lower"`) if set.
50
52
  *
51
53
  * @param str String to sanitize.
@@ -54,7 +56,7 @@ export class StringSchema extends Schema {
54
56
  * @see https://shelving.cc/schema/StringSchema/sanitize
55
57
  */
56
58
  sanitize(str) {
57
- const sane = this.rows > 1 ? sanitizeMultilineText(str) : sanitizeText(str);
59
+ const sane = this.multiline ? sanitizeMultilineText(str) : sanitizeText(str);
58
60
  if (this.case === "upper")
59
61
  return sane.toUpperCase();
60
62
  if (this.case === "lower")
@@ -25,7 +25,7 @@ export class URISchema extends StringSchema {
25
25
  input,
26
26
  max,
27
27
  min: 1,
28
- rows: 1,
28
+ multiline: false,
29
29
  });
30
30
  this.schemes = schemes;
31
31
  }
@@ -28,7 +28,7 @@ export class URLSchema extends StringSchema {
28
28
  input,
29
29
  max,
30
30
  min: 1,
31
- rows: 1,
31
+ multiline: false,
32
32
  });
33
33
  this.base = getURL(base)?.href;
34
34
  this.schemes = schemes;
@@ -20,7 +20,7 @@ export class UUIDSchema extends StringSchema {
20
20
  ...rest,
21
21
  max, // 36 chars including hyphens (which get stripped by sanitize for appearances).
22
22
  min: 32,
23
- rows: 1,
23
+ multiline: false,
24
24
  });
25
25
  }
26
26
  /** Normalises the input into a canonical lowercase UUID (or `""` if not a valid UUID). */
@@ -1,12 +1,14 @@
1
1
  import type { ReactElement } from "react";
2
2
  import { type PossibleDate } from "../../util/date.js";
3
+ import { type UnitFormatOptions } from "../../util/format.js";
3
4
  import type { OptionalChildProps } from "../util/props.js";
4
5
  /**
5
6
  * Props for `When`, `Ago`, and `Until` — a `target` date plus an optional `current` reference date and `full` toggle.
7
+ * - Unit format options go straight on the props, e.g. `<Ago target={when} unitDisplay="short" />`. `unitDisplay` defaults to `"narrow"` (e.g. `3h`).
6
8
  *
7
9
  * @see https://shelving.cc/ui/WhenProps
8
10
  */
9
- export interface WhenProps extends OptionalChildProps {
11
+ export interface WhenProps extends OptionalChildProps, Omit<UnitFormatOptions, "one" | "many" | "abbr"> {
10
12
  target: PossibleDate | undefined;
11
13
  /** Reference date the relative time is measured against.
12
14
  * @default "now" */
@@ -14,7 +16,7 @@ export interface WhenProps extends OptionalChildProps {
14
16
  full?: boolean | undefined;
15
17
  }
16
18
  /**
17
- * Relative time — shows a signed string like `in 6d` or `3w ago` wrapped in a `<time>` element carrying the machine-readable date.
19
+ * Relative time — shows a signed string like `in 6d`, `3w ago` or `just now` wrapped in a `<time>` element carrying the machine-readable date.
18
20
  *
19
21
  * @throws {RequiredError} If `target` (or `current`) cannot be coerced to a valid date.
20
22
  * @kind component
@@ -30,7 +32,7 @@ export declare function When(props: WhenProps): ReactElement;
30
32
  export interface AgoProps extends WhenProps {
31
33
  }
32
34
  /**
33
- * Elapsed time — shows an unsigned string like `6d` or `3w` for a past date wrapped in a `<time>` element carrying the machine-readable date.
35
+ * Elapsed time — shows an unsigned string like `3m`, `6mo` or `just now` for a past date wrapped in a `<time>` element carrying the machine-readable date.
34
36
  *
35
37
  * @throws {RequiredError} If `target` (or `current`) cannot be coerced to a valid date.
36
38
  * @kind component
package/ui/inline/When.js CHANGED
@@ -2,16 +2,16 @@ import { jsx as _jsx } from "react/jsx-runtime";
2
2
  import { requireDate } from "../../util/date.js";
3
3
  import { formatAgo, formatUntil, formatWhen, getSecondsAgo } from "../../util/duration.js";
4
4
  import { formatDateTime } from "../../util/format.js";
5
- const _OPTIONS = { unitDisplay: "narrow" };
6
- function _getWhen(formatter, { target: possibleTarget, current: possibleCurrent = "now", full = false, children }, caller) {
5
+ function _getWhen(formatter, { target: possibleTarget, current: possibleCurrent = "now", full = false, children, unitDisplay = "narrow", ...rest }, caller) {
7
6
  const target = requireDate(possibleTarget, caller);
8
7
  const current = requireDate(possibleCurrent, caller);
9
8
  const title = possibleCurrent === "now" ? formatDateTime(target) : `${formatDateTime(target)} to ${formatDateTime(current)}`;
10
- const formatted = children ?? (full ? `${title} (${formatter(target, current, _OPTIONS)})` : formatter(target, current, _OPTIONS));
9
+ const options = { ...rest, unitDisplay };
10
+ const formatted = children ?? (full ? `${title} (${formatter(target, current, options)})` : formatter(target, current, options));
11
11
  return (_jsx("time", { dateTime: possibleCurrent === "now" ? target.toISOString() : `PT${getSecondsAgo(target, current)}S`, title: title, children: formatted }));
12
12
  }
13
13
  /**
14
- * Relative time — shows a signed string like `in 6d` or `3w ago` wrapped in a `<time>` element carrying the machine-readable date.
14
+ * Relative time — shows a signed string like `in 6d`, `3w ago` or `just now` wrapped in a `<time>` element carrying the machine-readable date.
15
15
  *
16
16
  * @throws {RequiredError} If `target` (or `current`) cannot be coerced to a valid date.
17
17
  * @kind component
@@ -22,7 +22,7 @@ export function When(props) {
22
22
  return _getWhen(formatWhen, props, When);
23
23
  }
24
24
  /**
25
- * Elapsed time — shows an unsigned string like `6d` or `3w` for a past date wrapped in a `<time>` element carrying the machine-readable date.
25
+ * Elapsed time — shows an unsigned string like `3m`, `6mo` or `just now` for a past date wrapped in a `<time>` element carrying the machine-readable date.
26
26
  *
27
27
  * @throws {RequiredError} If `target` (or `current`) cannot be coerced to a valid date.
28
28
  * @kind component
@@ -0,0 +1,22 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import { renderToStaticMarkup } from "react-dom/server";
3
+ import { Ago, When } from "shelving/ui";
4
+ import { HOUR, MINUTE, SECOND } from "shelving/util/constants";
5
+
6
+ describe("Ago", () => {
7
+ test("shows narrow units by default", () => {
8
+ expect(renderToStaticMarkup(<Ago target={0} current={HOUR * 3} />)).toContain(">3h<");
9
+ });
10
+ test("takes format options as props", () => {
11
+ expect(renderToStaticMarkup(<Ago target={0} current={HOUR * 3} unitDisplay="short" />)).toContain(">3 hr<");
12
+ });
13
+ test("shows just now under a minute", () => {
14
+ expect(renderToStaticMarkup(<Ago target={0} current={SECOND * 5} />)).toContain(">just now<");
15
+ });
16
+ });
17
+
18
+ describe("When", () => {
19
+ test("takes format options as props", () => {
20
+ expect(renderToStaticMarkup(<When target={0} current={MINUTE * 3} unitDisplay="long" />)).toContain(">3 minutes ago<");
21
+ });
22
+ });
@@ -1,21 +1,20 @@
1
1
  import type { ReactElement } from "react";
2
2
  import { type PossibleDate, requireDate } from "../../util/date.js";
3
3
  import { formatAgo, formatUntil, formatWhen, getSecondsAgo } from "../../util/duration.js";
4
- import { formatDateTime } from "../../util/format.js";
4
+ import { formatDateTime, type UnitFormatOptions } from "../../util/format.js";
5
5
  import type { AnyCaller } from "../../util/function.js";
6
6
  import type { OptionalChildProps } from "../util/props.js";
7
7
 
8
- const _OPTIONS: Intl.NumberFormatOptions = { unitDisplay: "narrow" };
9
-
10
8
  function _getWhen(
11
9
  formatter: typeof formatWhen,
12
- { target: possibleTarget, current: possibleCurrent = "now", full = false, children }: WhenProps,
10
+ { target: possibleTarget, current: possibleCurrent = "now", full = false, children, unitDisplay = "narrow", ...rest }: WhenProps,
13
11
  caller: AnyCaller,
14
12
  ): ReactElement {
15
13
  const target = requireDate(possibleTarget, caller);
16
14
  const current = requireDate(possibleCurrent, caller);
17
15
  const title = possibleCurrent === "now" ? formatDateTime(target) : `${formatDateTime(target)} to ${formatDateTime(current)}`;
18
- const formatted = children ?? (full ? `${title} (${formatter(target, current, _OPTIONS)})` : formatter(target, current, _OPTIONS));
16
+ const options: UnitFormatOptions = { ...rest, unitDisplay };
17
+ const formatted = children ?? (full ? `${title} (${formatter(target, current, options)})` : formatter(target, current, options));
19
18
  return (
20
19
  <time dateTime={possibleCurrent === "now" ? target.toISOString() : `PT${getSecondsAgo(target, current)}S`} title={title}>
21
20
  {formatted}
@@ -25,10 +24,11 @@ function _getWhen(
25
24
 
26
25
  /**
27
26
  * Props for `When`, `Ago`, and `Until` — a `target` date plus an optional `current` reference date and `full` toggle.
27
+ * - Unit format options go straight on the props, e.g. `<Ago target={when} unitDisplay="short" />`. `unitDisplay` defaults to `"narrow"` (e.g. `3h`).
28
28
  *
29
29
  * @see https://shelving.cc/ui/WhenProps
30
30
  */
31
- export interface WhenProps extends OptionalChildProps {
31
+ export interface WhenProps extends OptionalChildProps, Omit<UnitFormatOptions, "one" | "many" | "abbr"> {
32
32
  target: PossibleDate | undefined;
33
33
  /** Reference date the relative time is measured against.
34
34
  * @default "now" */
@@ -37,7 +37,7 @@ export interface WhenProps extends OptionalChildProps {
37
37
  }
38
38
 
39
39
  /**
40
- * Relative time — shows a signed string like `in 6d` or `3w ago` wrapped in a `<time>` element carrying the machine-readable date.
40
+ * Relative time — shows a signed string like `in 6d`, `3w ago` or `just now` wrapped in a `<time>` element carrying the machine-readable date.
41
41
  *
42
42
  * @throws {RequiredError} If `target` (or `current`) cannot be coerced to a valid date.
43
43
  * @kind component
@@ -56,7 +56,7 @@ export function When(props: WhenProps): ReactElement {
56
56
  export interface AgoProps extends WhenProps {}
57
57
 
58
58
  /**
59
- * Elapsed time — shows an unsigned string like `6d` or `3w` for a past date wrapped in a `<time>` element carrying the machine-readable date.
59
+ * Elapsed time — shows an unsigned string like `3m`, `6mo` or `just now` for a past date wrapped in a `<time>` element carrying the machine-readable date.
60
60
  *
61
61
  * @throws {RequiredError} If `target` (or `current`) cannot be coerced to a valid date.
62
62
  * @kind component
@@ -102,10 +102,9 @@
102
102
  overflow-wrap: break-word;
103
103
  field-sizing: content;
104
104
 
105
- /* `field-sizing` ignores `rows`, so set the minimum height from `--input-rows` (set inline from the `rows` prop). */
105
+ /* `field-sizing` ignores `rows`, so set the minimum height from `--input-rows` (set inline from the `rows` prop). Never shorter than a single-line input, so a one-row textarea matches a button with an icon. */
106
106
  min-block-size: calc(
107
- var(--input-rows, 2) *
108
- 1lh +
107
+ max(var(--input-icon-size, var(--size-icon)), var(--input-rows, 2) * 1lh) +
109
108
  2 *
110
109
  var(--input-padding, var(--space-small)) +
111
110
  2 *
@@ -1,6 +1,6 @@
1
1
  import { describe, expect, test } from "bun:test";
2
2
  import type { ReactElement } from "react";
3
- import { DateInput, FileInput, ImageInput, NumberInput, TextInput } from "shelving/ui";
3
+ import { DateInput, FileInput, ImageInput, NumberInput, TextareaInput, TextInput } from "shelving/ui";
4
4
  import { PASSTHROUGH } from "shelving/util/function";
5
5
 
6
6
  /** The props of the rendered element that the tests read. */
@@ -13,7 +13,7 @@ describe("value inputs", () => {
13
13
  // React's `onChange` already fires for each native `input` event, so a second `onInput` handler would call `onValue()` twice.
14
14
  const elements: [string, ReactElement][] = [
15
15
  ["TextInput", TextInput({ name: "x", onValue: PASSTHROUGH })],
16
- ["TextInput (multiline)", TextInput({ name: "x", rows: 3, onValue: PASSTHROUGH })],
16
+ ["TextareaInput", TextareaInput({ name: "x", rows: 3, onValue: PASSTHROUGH })],
17
17
  ["NumberInput", NumberInput({ name: "x", onValue: PASSTHROUGH })],
18
18
  ["DateInput", DateInput({ name: "x", onValue: PASSTHROUGH })],
19
19
  ["FileInput", FileInput({ name: "x", onValue: PASSTHROUGH })],
@@ -31,7 +31,7 @@ export interface SchemaInputProps<T extends Schema, I = never> extends ValueInpu
31
31
  }
32
32
  /**
33
33
  * Show the appropriate input control for a schema, dispatching on the schema's concrete type.
34
- * - Picks `DateInput`, `NumberInput`, choice radios/select, `CheckboxInput`, `TextInput`, `ArrayInput`, `DictionaryInput`, or `DataInput`.
34
+ * - Picks `DateInput`, `NumberInput`, choice radios/select, `CheckboxInput`, `TextInput` or `TextareaInput`, `ArrayInput`, `DictionaryInput`, or `DataInput`.
35
35
  * - `required` defaults to whether the schema is required.
36
36
  *
37
37
  * @returns The matching input element for the schema.
@@ -115,10 +115,11 @@ export declare function BooleanSchemaInput({ schema, value, ...props }: BooleanS
115
115
  export interface StringSchemaInputProps extends SchemaInputProps<StringSchema, unknown> {
116
116
  }
117
117
  /**
118
- * Show a `TextInput` for a `StringSchema`, sanitising and formatting values with the schema.
118
+ * Show a `TextInput` for a `StringSchema`, or a `TextareaInput` when the schema is `multiline`, sanitising and formatting values with the schema.
119
119
  * - Publishes the sanitized value through `onValue`; the schema's `format()` only shapes what the input displays (on first render and on blur).
120
+ * - A `TextareaInput` starts at the schema's `rows` (2 by default for a multiline schema).
120
121
  *
121
- * @returns A `TextInput` element bound to the schema.
122
+ * @returns A `TextInput` or `TextareaInput` element bound to the schema.
122
123
  * @kind component
123
124
  * @example <StringSchemaInput name="email" schema={EMAIL} />
124
125
  * @see https://shelving.cc/ui/StringSchemaInput
@@ -25,6 +25,7 @@ import { DateInput } from "./DateInput.js";
25
25
  import { DictionaryInput } from "./DictionaryInput.js";
26
26
  import { NumberInput } from "./NumberInput.js";
27
27
  import { SelectInput } from "./SelectInput.js";
28
+ import { TextareaInput } from "./TextareaInput.js";
28
29
  import { TextInput } from "./TextInput.js";
29
30
  /**
30
31
  * Whether a schema is required, i.e. not wrapped in an `OptionalSchema` or `NullableSchema`.
@@ -122,16 +123,18 @@ export function BooleanSchemaInput({ schema, value, ...props }) {
122
123
  return _jsx(CheckboxInput, { ...schema, value: !!value, ...props });
123
124
  }
124
125
  /**
125
- * Show a `TextInput` for a `StringSchema`, sanitising and formatting values with the schema.
126
+ * Show a `TextInput` for a `StringSchema`, or a `TextareaInput` when the schema is `multiline`, sanitising and formatting values with the schema.
126
127
  * - Publishes the sanitized value through `onValue`; the schema's `format()` only shapes what the input displays (on first render and on blur).
128
+ * - A `TextareaInput` starts at the schema's `rows` (2 by default for a multiline schema).
127
129
  *
128
- * @returns A `TextInput` element bound to the schema.
130
+ * @returns A `TextInput` or `TextareaInput` element bound to the schema.
129
131
  * @kind component
130
132
  * @example <StringSchemaInput name="email" schema={EMAIL} />
131
133
  * @see https://shelving.cc/ui/StringSchemaInput
132
134
  */
133
135
  export function StringSchemaInput({ schema, value, onValue, ...props }) {
134
- return (_jsx(TextInput, { ...schema, value: getString(value), onValue: str => onValue(str === undefined ? undefined : schema.sanitize(str)), formatter: str => schema.format(schema.sanitize(str)), ...props }));
136
+ const Input = schema.multiline ? TextareaInput : TextInput;
137
+ return (_jsx(Input, { ...schema, value: getString(value), onValue: str => onValue(str === undefined ? undefined : schema.sanitize(str)), formatter: str => schema.format(schema.sanitize(str)), ...props }));
135
138
  }
136
139
  /**
137
140
  * Show an `ArrayInput` for an `ArraySchema`.
@@ -99,6 +99,22 @@ describe("StringSchemaInput", () => {
99
99
  expect(URL_SCHEMA.validate(values[0])).toBe("https://example.com/path");
100
100
  expect(currentTarget.value).toBe("example.com/path");
101
101
  });
102
+ test("renders a one-row textarea when the schema is multiline", () => {
103
+ // `multiline` makes a `<textarea>`, and `rows` sets its first height.
104
+ const schema = new StringSchema({ multiline: true, rows: 1 });
105
+ const html = renderToStaticMarkup(<StringSchemaInput name="text" schema={schema} value="" onValue={PASSTHROUGH} />);
106
+
107
+ expect(html).toContain("<textarea");
108
+ expect(html).toContain('rows="1"');
109
+ });
110
+
111
+ test("renders an input when the schema is not multiline, whatever its rows", () => {
112
+ const schema = new StringSchema({ rows: 3 });
113
+ const html = renderToStaticMarkup(<StringSchemaInput name="text" schema={schema} value="" onValue={PASSTHROUGH} />);
114
+
115
+ expect(html).toContain("<input");
116
+ expect(html).not.toContain("<textarea");
117
+ });
102
118
  });
103
119
 
104
120
  describe("ChoiceSchemaInput", () => {
@@ -29,6 +29,7 @@ import { DictionaryInput } from "./DictionaryInput.js";
29
29
  import type { ValueInputProps } from "./Input.js";
30
30
  import { NumberInput } from "./NumberInput.js";
31
31
  import { SelectInput } from "./SelectInput.js";
32
+ import { TextareaInput } from "./TextareaInput.js";
32
33
  import { TextInput } from "./TextInput.js";
33
34
 
34
35
  /**
@@ -54,7 +55,7 @@ export interface SchemaInputProps<T extends Schema, I = never> extends ValueInpu
54
55
 
55
56
  /**
56
57
  * Show the appropriate input control for a schema, dispatching on the schema's concrete type.
57
- * - Picks `DateInput`, `NumberInput`, choice radios/select, `CheckboxInput`, `TextInput`, `ArrayInput`, `DictionaryInput`, or `DataInput`.
58
+ * - Picks `DateInput`, `NumberInput`, choice radios/select, `CheckboxInput`, `TextInput` or `TextareaInput`, `ArrayInput`, `DictionaryInput`, or `DataInput`.
58
59
  * - `required` defaults to whether the schema is required.
59
60
  *
60
61
  * @returns The matching input element for the schema.
@@ -191,17 +192,19 @@ export function BooleanSchemaInput({ schema, value, ...props }: BooleanSchemaInp
191
192
  export interface StringSchemaInputProps extends SchemaInputProps<StringSchema, unknown> {}
192
193
 
193
194
  /**
194
- * Show a `TextInput` for a `StringSchema`, sanitising and formatting values with the schema.
195
+ * Show a `TextInput` for a `StringSchema`, or a `TextareaInput` when the schema is `multiline`, sanitising and formatting values with the schema.
195
196
  * - Publishes the sanitized value through `onValue`; the schema's `format()` only shapes what the input displays (on first render and on blur).
197
+ * - A `TextareaInput` starts at the schema's `rows` (2 by default for a multiline schema).
196
198
  *
197
- * @returns A `TextInput` element bound to the schema.
199
+ * @returns A `TextInput` or `TextareaInput` element bound to the schema.
198
200
  * @kind component
199
201
  * @example <StringSchemaInput name="email" schema={EMAIL} />
200
202
  * @see https://shelving.cc/ui/StringSchemaInput
201
203
  */
202
204
  export function StringSchemaInput({ schema, value, onValue, ...props }: StringSchemaInputProps): ReactElement {
205
+ const Input = schema.multiline ? TextareaInput : TextInput;
203
206
  return (
204
- <TextInput
207
+ <Input
205
208
  {...schema}
206
209
  value={getString(value)}
207
210
  onValue={str => onValue(str === undefined ? undefined : schema.sanitize(str))}
@@ -1,15 +1,14 @@
1
1
  import type { ReactElement } from "react";
2
2
  import type { StringInputType } from "../../schema/StringSchema.js";
3
3
  import { type InputVariants, type ValueInputProps } from "../input/Input.js";
4
- type TextFormatter = (str: string) => string;
4
+ /** Formats a string for display in a text input. */
5
+ export type TextFormatter = (str: string) => string;
5
6
  /**
6
- * Props for `TextInput`, a single- or multi-line text input bound to a `string` value.
7
+ * Props for `TextInput`, a single-line text input bound to a `string` value.
7
8
  *
8
9
  * @see https://shelving.cc/ui/TextInputProps
9
10
  */
10
11
  export interface TextInputProps extends ValueInputProps<string>, InputVariants {
11
- rows?: number | undefined;
12
- multiline?: boolean;
13
12
  input?: StringInputType;
14
13
  min?: number | undefined;
15
14
  max?: number | undefined;
@@ -17,14 +16,12 @@ export interface TextInputProps extends ValueInputProps<string>, InputVariants {
17
16
  formatter?: TextFormatter | undefined;
18
17
  }
19
18
  /**
20
- * Text input bound to a `string` value, rendered as an `<input>` or a `<textarea>` when `rows > 1`.
19
+ * Single-line text input bound to a `string` value, rendered as an `<input>`. Use `TextareaInput` for multiline text.
21
20
  * - Applies an optional `formatter` on initial display and on blur — the raw typed value is published through `onValue`.
22
- * - Multiline mode auto-grows the textarea to fit its content.
23
21
  *
24
- * @returns A text `<input>` or `<textarea>` element.
22
+ * @returns A text `<input>` element.
25
23
  * @example <TextInput name="name" value={name} onValue={setName} />
26
24
  * @see https://shelving.cc/ui/TextInput
27
25
  */
28
26
  export declare function TextInput({ name, title, placeholder, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
29
- required, disabled, message, value, onValue, input, min, max, rows, formatter, className, ...variants }: TextInputProps): ReactElement;
30
- export {};
27
+ required, disabled, message, value, onValue, input, min, max, formatter, className, ...variants }: TextInputProps): ReactElement;
@@ -4,39 +4,20 @@ import { getInputClass } from "../input/Input.js";
4
4
  import { getClass, getModuleClass } from "../util/css.js";
5
5
  import INPUT_CSS from "./Input.module.css";
6
6
  /**
7
- * Text input bound to a `string` value, rendered as an `<input>` or a `<textarea>` when `rows > 1`.
7
+ * Single-line text input bound to a `string` value, rendered as an `<input>`. Use `TextareaInput` for multiline text.
8
8
  * - Applies an optional `formatter` on initial display and on blur — the raw typed value is published through `onValue`.
9
- * - Multiline mode auto-grows the textarea to fit its content.
10
9
  *
11
- * @returns A text `<input>` or `<textarea>` element.
10
+ * @returns A text `<input>` element.
12
11
  * @example <TextInput name="name" value={name} onValue={setName} />
13
12
  * @see https://shelving.cc/ui/TextInput
14
13
  */
15
14
  export function TextInput({ name, title = "", placeholder = title, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
16
- required = false, disabled = false, message = "", value, onValue, input = "text", min = 0, max = Number.POSITIVE_INFINITY, rows = 1, formatter = PASSTHROUGH, className, ...variants }) {
15
+ required = false, disabled = false, message = "", value, onValue, input = "text", min = 0, max = Number.POSITIVE_INFINITY, formatter = PASSTHROUGH, className, ...variants }) {
17
16
  const onBlur = ({ currentTarget }) => {
18
17
  currentTarget.value = formatter(currentTarget.value);
19
18
  };
20
- if (rows > 1) {
21
- const onChange = (e) => {
22
- onValue?.(e.currentTarget.value);
23
- _resize(e.currentTarget, rows);
24
- };
25
- return (_jsx("textarea", { ref: el => void (el && _resize(el, rows)), name: name, defaultValue: value !== undefined ? formatter(value) : "", minLength: Number.isFinite(min) ? min : 0, maxLength: Number.isFinite(max) ? max : undefined, rows: rows, style: { "--input-rows": rows }, required: required && min > 0, disabled: disabled, placeholder: placeholder || " ", className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "text"), getModuleClass(INPUT_CSS, "multiline"), className), onChange: onChange, onBlur: onBlur, title: message, "aria-invalid": !!message }));
26
- }
27
19
  const onChange = (e) => {
28
20
  onValue?.(e.currentTarget.value);
29
21
  };
30
22
  return (_jsx("input", { name: name, type: input, defaultValue: value !== undefined ? formatter(value) : "", minLength: Number.isFinite(min) ? min : 0, maxLength: Number.isFinite(max) ? max : undefined, required: required && min > 0, disabled: disabled, placeholder: placeholder || " ", className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "text"), className), onChange: onChange, onBlur: onBlur, title: message, "aria-invalid": !!message }));
31
23
  }
32
- /**
33
- * @todo This can be removed when Firefox supports `field-sizing:` in CSS.
34
- * https://caniuse.com/wf-field-sizing
35
- */
36
- function _resize(el, minRows) {
37
- if (el && !CSS.supports("field-sizing", "content")) {
38
- el.rows = minRows;
39
- while (el.scrollHeight > el.clientHeight)
40
- el.rows++;
41
- }
42
- }
@@ -1,20 +1,19 @@
1
- import type { CSSProperties, ReactElement, SyntheticEvent } from "react";
1
+ import type { ReactElement, SyntheticEvent } from "react";
2
2
  import type { StringInputType } from "../../schema/StringSchema.js";
3
3
  import { PASSTHROUGH } from "../../util/function.js";
4
4
  import { getInputClass, type InputVariants, type ValueInputProps } from "../input/Input.js";
5
5
  import { getClass, getModuleClass } from "../util/css.js";
6
6
  import INPUT_CSS from "./Input.module.css";
7
7
 
8
- type TextFormatter = (str: string) => string;
8
+ /** Formats a string for display in a text input. */
9
+ export type TextFormatter = (str: string) => string;
9
10
 
10
11
  /**
11
- * Props for `TextInput`, a single- or multi-line text input bound to a `string` value.
12
+ * Props for `TextInput`, a single-line text input bound to a `string` value.
12
13
  *
13
14
  * @see https://shelving.cc/ui/TextInputProps
14
15
  */
15
16
  export interface TextInputProps extends ValueInputProps<string>, InputVariants {
16
- rows?: number | undefined;
17
- multiline?: boolean;
18
17
  input?: StringInputType;
19
18
  min?: number | undefined;
20
19
  max?: number | undefined;
@@ -23,11 +22,10 @@ export interface TextInputProps extends ValueInputProps<string>, InputVariants {
23
22
  }
24
23
 
25
24
  /**
26
- * Text input bound to a `string` value, rendered as an `<input>` or a `<textarea>` when `rows > 1`.
25
+ * Single-line text input bound to a `string` value, rendered as an `<input>`. Use `TextareaInput` for multiline text.
27
26
  * - Applies an optional `formatter` on initial display and on blur — the raw typed value is published through `onValue`.
28
- * - Multiline mode auto-grows the textarea to fit its content.
29
27
  *
30
- * @returns A text `<input>` or `<textarea>` element.
28
+ * @returns A text `<input>` element.
31
29
  * @example <TextInput name="name" value={name} onValue={setName} />
32
30
  * @see https://shelving.cc/ui/TextInput
33
31
  */
@@ -43,46 +41,16 @@ export function TextInput({
43
41
  input = "text",
44
42
  min = 0,
45
43
  max = Number.POSITIVE_INFINITY,
46
- rows = 1,
47
44
  formatter = PASSTHROUGH,
48
45
  className,
49
46
  ...variants
50
47
  }: TextInputProps): ReactElement {
51
- const onBlur = ({ currentTarget }: SyntheticEvent<HTMLInputElement | HTMLTextAreaElement>) => {
48
+ const onBlur = ({ currentTarget }: SyntheticEvent<HTMLInputElement>) => {
52
49
  currentTarget.value = formatter(currentTarget.value);
53
50
  };
54
-
55
- if (rows > 1) {
56
- const onChange = (e: SyntheticEvent<HTMLTextAreaElement>) => {
57
- onValue?.(e.currentTarget.value);
58
- _resize(e.currentTarget, rows);
59
- };
60
-
61
- return (
62
- <textarea
63
- ref={el => void (el && _resize(el, rows))}
64
- name={name}
65
- defaultValue={value !== undefined ? formatter(value) : ""}
66
- minLength={Number.isFinite(min) ? min : 0}
67
- maxLength={Number.isFinite(max) ? max : undefined}
68
- rows={rows}
69
- style={{ "--input-rows": rows } as CSSProperties}
70
- required={required && min > 0}
71
- disabled={disabled}
72
- placeholder={placeholder || " "}
73
- className={getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "text"), getModuleClass(INPUT_CSS, "multiline"), className)}
74
- onChange={onChange}
75
- onBlur={onBlur}
76
- title={message}
77
- aria-invalid={!!message}
78
- />
79
- );
80
- }
81
-
82
51
  const onChange = (e: SyntheticEvent<HTMLInputElement>) => {
83
52
  onValue?.(e.currentTarget.value);
84
53
  };
85
-
86
54
  return (
87
55
  <input
88
56
  name={name}
@@ -101,14 +69,3 @@ export function TextInput({
101
69
  />
102
70
  );
103
71
  }
104
-
105
- /**
106
- * @todo This can be removed when Firefox supports `field-sizing:` in CSS.
107
- * https://caniuse.com/wf-field-sizing
108
- */
109
- function _resize(el: HTMLTextAreaElement, minRows: number): void {
110
- if (el && !CSS.supports("field-sizing", "content")) {
111
- el.rows = minRows;
112
- while (el.scrollHeight > el.clientHeight) el.rows++;
113
- }
114
- }
@@ -0,0 +1,29 @@
1
+ import type { ReactElement } from "react";
2
+ import { type InputVariants, type ValueInputProps } from "../input/Input.js";
3
+ import type { TextFormatter } from "./TextInput.js";
4
+ /**
5
+ * Props for `TextareaInput`, a multiline text input bound to a `string` value.
6
+ *
7
+ * @see https://shelving.cc/ui/TextareaInputProps
8
+ */
9
+ export interface TextareaInputProps extends ValueInputProps<string>, InputVariants {
10
+ /**
11
+ * Rows the textarea shows at first (its minimum height). It grows to fit its content.
12
+ * @default 2
13
+ */
14
+ rows?: number | undefined;
15
+ min?: number | undefined;
16
+ max?: number | undefined;
17
+ /** Optional formatter — when provided the value is reformatted on blur and when initially displayed (the value published through `onValue` is never formatted). */
18
+ formatter?: TextFormatter | undefined;
19
+ }
20
+ /**
21
+ * Multiline text input bound to a `string` value, rendered as a `<textarea>` that grows to fit its content.
22
+ * - Applies an optional `formatter` on initial display and on blur — the raw typed value is published through `onValue`.
23
+ *
24
+ * @returns A `<textarea>` element.
25
+ * @example <TextareaInput name="bio" rows={4} value={bio} onValue={setBio} />
26
+ * @see https://shelving.cc/ui/TextareaInput
27
+ */
28
+ export declare function TextareaInput({ name, title, placeholder, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
29
+ required, disabled, message, value, onValue, min, max, rows, formatter, className, ...variants }: TextareaInputProps): ReactElement;
@@ -0,0 +1,35 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { PASSTHROUGH } from "../../util/function.js";
3
+ import { getInputClass } from "../input/Input.js";
4
+ import { getClass, getModuleClass } from "../util/css.js";
5
+ import INPUT_CSS from "./Input.module.css";
6
+ /**
7
+ * Multiline text input bound to a `string` value, rendered as a `<textarea>` that grows to fit its content.
8
+ * - Applies an optional `formatter` on initial display and on blur — the raw typed value is published through `onValue`.
9
+ *
10
+ * @returns A `<textarea>` element.
11
+ * @example <TextareaInput name="bio" rows={4} value={bio} onValue={setBio} />
12
+ * @see https://shelving.cc/ui/TextareaInput
13
+ */
14
+ export function TextareaInput({ name, title = "", placeholder = title, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
15
+ required = false, disabled = false, message = "", value, onValue, min = 0, max = Number.POSITIVE_INFINITY, rows = 2, formatter = PASSTHROUGH, className, ...variants }) {
16
+ const onBlur = ({ currentTarget }) => {
17
+ currentTarget.value = formatter(currentTarget.value);
18
+ };
19
+ const onChange = (e) => {
20
+ onValue?.(e.currentTarget.value);
21
+ _resize(e.currentTarget, rows);
22
+ };
23
+ return (_jsx("textarea", { ref: el => void (el && _resize(el, rows)), name: name, defaultValue: value !== undefined ? formatter(value) : "", minLength: Number.isFinite(min) ? min : 0, maxLength: Number.isFinite(max) ? max : undefined, rows: rows, style: { "--input-rows": rows }, required: required && min > 0, disabled: disabled, placeholder: placeholder || " ", className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "text"), getModuleClass(INPUT_CSS, "multiline"), className), onChange: onChange, onBlur: onBlur, title: message, "aria-invalid": !!message }));
24
+ }
25
+ /**
26
+ * @todo This can be removed when Firefox supports `field-sizing:` in CSS.
27
+ * https://caniuse.com/wf-field-sizing
28
+ */
29
+ function _resize(el, minRows) {
30
+ if (el && !CSS.supports("field-sizing", "content")) {
31
+ el.rows = minRows;
32
+ while (el.scrollHeight > el.clientHeight)
33
+ el.rows++;
34
+ }
35
+ }
@@ -0,0 +1,86 @@
1
+ import type { CSSProperties, ReactElement, SyntheticEvent } from "react";
2
+ import { PASSTHROUGH } from "../../util/function.js";
3
+ import { getInputClass, type InputVariants, type ValueInputProps } from "../input/Input.js";
4
+ import { getClass, getModuleClass } from "../util/css.js";
5
+ import INPUT_CSS from "./Input.module.css";
6
+ import type { TextFormatter } from "./TextInput.js";
7
+
8
+ /**
9
+ * Props for `TextareaInput`, a multiline text input bound to a `string` value.
10
+ *
11
+ * @see https://shelving.cc/ui/TextareaInputProps
12
+ */
13
+ export interface TextareaInputProps extends ValueInputProps<string>, InputVariants {
14
+ /**
15
+ * Rows the textarea shows at first (its minimum height). It grows to fit its content.
16
+ * @default 2
17
+ */
18
+ rows?: number | undefined;
19
+ min?: number | undefined;
20
+ max?: number | undefined;
21
+ /** Optional formatter — when provided the value is reformatted on blur and when initially displayed (the value published through `onValue` is never formatted). */
22
+ formatter?: TextFormatter | undefined;
23
+ }
24
+
25
+ /**
26
+ * Multiline text input bound to a `string` value, rendered as a `<textarea>` that grows to fit its content.
27
+ * - Applies an optional `formatter` on initial display and on blur — the raw typed value is published through `onValue`.
28
+ *
29
+ * @returns A `<textarea>` element.
30
+ * @example <TextareaInput name="bio" rows={4} value={bio} onValue={setBio} />
31
+ * @see https://shelving.cc/ui/TextareaInput
32
+ */
33
+ export function TextareaInput({
34
+ name,
35
+ title = "",
36
+ placeholder = title, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
37
+ required = false,
38
+ disabled = false,
39
+ message = "",
40
+ value,
41
+ onValue,
42
+ min = 0,
43
+ max = Number.POSITIVE_INFINITY,
44
+ rows = 2,
45
+ formatter = PASSTHROUGH,
46
+ className,
47
+ ...variants
48
+ }: TextareaInputProps): ReactElement {
49
+ const onBlur = ({ currentTarget }: SyntheticEvent<HTMLTextAreaElement>) => {
50
+ currentTarget.value = formatter(currentTarget.value);
51
+ };
52
+ const onChange = (e: SyntheticEvent<HTMLTextAreaElement>) => {
53
+ onValue?.(e.currentTarget.value);
54
+ _resize(e.currentTarget, rows);
55
+ };
56
+ return (
57
+ <textarea
58
+ ref={el => void (el && _resize(el, rows))}
59
+ name={name}
60
+ defaultValue={value !== undefined ? formatter(value) : ""}
61
+ minLength={Number.isFinite(min) ? min : 0}
62
+ maxLength={Number.isFinite(max) ? max : undefined}
63
+ rows={rows}
64
+ style={{ "--input-rows": rows } as CSSProperties}
65
+ required={required && min > 0}
66
+ disabled={disabled}
67
+ placeholder={placeholder || " "}
68
+ className={getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "text"), getModuleClass(INPUT_CSS, "multiline"), className)}
69
+ onChange={onChange}
70
+ onBlur={onBlur}
71
+ title={message}
72
+ aria-invalid={!!message}
73
+ />
74
+ );
75
+ }
76
+
77
+ /**
78
+ * @todo This can be removed when Firefox supports `field-sizing:` in CSS.
79
+ * https://caniuse.com/wf-field-sizing
80
+ */
81
+ function _resize(el: HTMLTextAreaElement, minRows: number): void {
82
+ if (el && !CSS.supports("field-sizing", "content")) {
83
+ el.rows = minRows;
84
+ while (el.scrollHeight > el.clientHeight) el.rows++;
85
+ }
86
+ }
@@ -21,4 +21,5 @@ export * from "./QueryRadiosInput.js";
21
21
  export * from "./RadioInput.js";
22
22
  export * from "./SchemaInput.js";
23
23
  export * from "./SelectInput.js";
24
+ export * from "./TextareaInput.js";
24
25
  export * from "./TextInput.js";
package/ui/input/index.js CHANGED
@@ -21,4 +21,5 @@ export * from "./QueryRadiosInput.js";
21
21
  export * from "./RadioInput.js";
22
22
  export * from "./SchemaInput.js";
23
23
  export * from "./SelectInput.js";
24
+ export * from "./TextareaInput.js";
24
25
  export * from "./TextInput.js";
package/ui/input/index.ts CHANGED
@@ -21,4 +21,5 @@ export * from "./QueryRadiosInput.js";
21
21
  export * from "./RadioInput.js";
22
22
  export * from "./SchemaInput.js";
23
23
  export * from "./SelectInput.js";
24
+ export * from "./TextareaInput.js";
24
25
  export * from "./TextInput.js";
@@ -310,7 +310,7 @@ export declare function getBestDurationUnit(ms: number): Unit<DurationUnitKey>;
310
310
  /**
311
311
  * Format a compact best-fit description of when a date happens or happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now`
312
312
  * - See `getBestDurationUnit()` for details on how the best-fit unit is chosen.
313
- * - But: anything under 30 seconds will show `just now`, which makes more sense in most UIs.
313
+ * - But: anything under a minute will show `just now`, which makes more sense in most UIs.
314
314
  *
315
315
  * @param target Date the duration is measured to.
316
316
  * @param current Date the duration is measured from (defaults to now).
@@ -335,14 +335,15 @@ export declare function formatWhen(target: PossibleDate, current?: PossibleDate,
335
335
  */
336
336
  export declare function formatUntil(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller?: AnyCaller): string;
337
337
  /**
338
- * Format a compact best-fit description of how long since a date, e.g. `10d` or `2h` or `-1w`
338
+ * Format a compact best-fit description of how long since a date, e.g. `10d` or `2h` or `just now`
339
339
  * - See `getBestDurationUnit()` for details on how the best-fit unit is chosen.
340
+ * - Anything under a minute (either way) shows `just now`.
340
341
  *
341
342
  * @param target Date to count back from.
342
343
  * @param current Date to count to (defaults to now).
343
344
  * @param options Formatting options for the chosen duration unit.
344
345
  * @param caller Function to attribute a thrown error to (defaults to `formatAgo` itself).
345
- * @returns Compact string like `10d` or `2h` (negative if `target` is in the future).
346
+ * @returns Compact string like `10d`, `2h` or `just now` (negative if `target` is in the future).
346
347
  * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
347
348
  * @see https://shelving.cc/util/duration/formatAgo
348
349
  */
package/util/duration.js CHANGED
@@ -380,7 +380,7 @@ export function getBestDurationUnit(ms) {
380
380
  /**
381
381
  * Format a compact best-fit description of when a date happens or happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now`
382
382
  * - See `getBestDurationUnit()` for details on how the best-fit unit is chosen.
383
- * - But: anything under 30 seconds will show `just now`, which makes more sense in most UIs.
383
+ * - But: anything under a minute will show `just now`, which makes more sense in most UIs.
384
384
  *
385
385
  * @param target Date the duration is measured to.
386
386
  * @param current Date the duration is measured from (defaults to now).
@@ -393,10 +393,11 @@ export function getBestDurationUnit(ms) {
393
393
  export function formatWhen(target, current, options, caller = formatWhen) {
394
394
  const ms = getMilliseconds(current, target, caller);
395
395
  const abs = Math.abs(ms);
396
- if (abs < 30 * SECOND)
396
+ if (abs < MINUTE)
397
397
  return "just now";
398
398
  const unit = getBestDurationUnit(ms);
399
- return ms > 0 ? `in ${unit.format(unit.from(abs), options)}` : `${unit.format(unit.from(abs), options)} ago`;
399
+ const str = unit.format(unit.from(abs), options);
400
+ return ms > 0 ? `in ${str}` : `${str} ago`;
400
401
  }
401
402
  /**
402
403
  * Format a compact best-fit description of how long until a date, e.g. `10d` or `2h` or `-1w`
@@ -416,19 +417,22 @@ export function formatUntil(target, current, options, caller = formatUntil) {
416
417
  return unit.format(unit.from(ms), options);
417
418
  }
418
419
  /**
419
- * Format a compact best-fit description of how long since a date, e.g. `10d` or `2h` or `-1w`
420
+ * Format a compact best-fit description of how long since a date, e.g. `10d` or `2h` or `just now`
420
421
  * - See `getBestDurationUnit()` for details on how the best-fit unit is chosen.
422
+ * - Anything under a minute (either way) shows `just now`.
421
423
  *
422
424
  * @param target Date to count back from.
423
425
  * @param current Date to count to (defaults to now).
424
426
  * @param options Formatting options for the chosen duration unit.
425
427
  * @param caller Function to attribute a thrown error to (defaults to `formatAgo` itself).
426
- * @returns Compact string like `10d` or `2h` (negative if `target` is in the future).
428
+ * @returns Compact string like `10d`, `2h` or `just now` (negative if `target` is in the future).
427
429
  * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
428
430
  * @see https://shelving.cc/util/duration/formatAgo
429
431
  */
430
432
  export function formatAgo(target, current, options, caller = formatAgo) {
431
433
  const ms = getMilliseconds(target, current, caller);
434
+ if (Math.abs(ms) < MINUTE)
435
+ return "just now";
432
436
  const unit = getBestDurationUnit(ms);
433
437
  return unit.format(unit.from(ms), options);
434
438
  }