@marktiderman/genesis-core 2.15.0 → 2.16.1

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.
Files changed (49) hide show
  1. package/dist/{aggregate-y-qqJioF.d.ts → aggregate-Y5IJ5aPn.d.ts} +1 -1
  2. package/dist/{chunk-TKK7D2ZT.js → chunk-ALLWIK62.js} +3 -3
  3. package/dist/{chunk-TKK7D2ZT.js.map → chunk-ALLWIK62.js.map} +1 -1
  4. package/dist/{chunk-JTRRAVR4.js → chunk-APFXV6FZ.js} +18 -12
  5. package/dist/chunk-APFXV6FZ.js.map +1 -0
  6. package/dist/chunk-BDPRWVFW.js +17 -0
  7. package/dist/chunk-BDPRWVFW.js.map +1 -0
  8. package/dist/{chunk-JFHRSG6G.js → chunk-FXPODKCK.js} +3 -3
  9. package/dist/{chunk-JFHRSG6G.js.map → chunk-FXPODKCK.js.map} +1 -1
  10. package/dist/{chunk-YZV3Z6ZA.js → chunk-SQLM5CIJ.js} +3 -3
  11. package/dist/{chunk-YZV3Z6ZA.js.map → chunk-SQLM5CIJ.js.map} +1 -1
  12. package/dist/{chunk-NZP7YQHS.js → chunk-ZYOJWU62.js} +4 -4
  13. package/dist/{chunk-NZP7YQHS.js.map → chunk-ZYOJWU62.js.map} +1 -1
  14. package/dist/csv.d.ts +1 -1
  15. package/dist/form-types.d.ts +1 -1
  16. package/dist/headless/index.d.ts +334 -0
  17. package/dist/headless/index.js +490 -0
  18. package/dist/headless/index.js.map +1 -0
  19. package/dist/hooks/index.d.ts +3 -3
  20. package/dist/hooks/index.js +11 -10
  21. package/dist/hooks/mutation-mode.d.ts +1 -1
  22. package/dist/hooks/related-keys.d.ts +1 -1
  23. package/dist/hooks/use-aggregate.d.ts +2 -2
  24. package/dist/hooks/use-capabilities.d.ts +1 -1
  25. package/dist/hooks/use-draft.js +2 -2
  26. package/dist/hooks/use-infinite-resource.d.ts +1 -1
  27. package/dist/hooks/use-link-options.d.ts +1 -1
  28. package/dist/hooks/use-live.d.ts +1 -1
  29. package/dist/hooks/use-one.d.ts +1 -1
  30. package/dist/hooks/use-relation-label.d.ts +1 -1
  31. package/dist/hooks/use-resource-form.d.ts +1 -1
  32. package/dist/hooks/use-resource-form.js +3 -3
  33. package/dist/hooks/use-resource.d.ts +1 -1
  34. package/dist/hooks/use-resource.js +3 -3
  35. package/dist/hooks/use-write.d.ts +1 -1
  36. package/dist/index.d.ts +6 -6
  37. package/dist/index.js +12 -11
  38. package/dist/index.js.map +1 -1
  39. package/dist/provider/index.d.ts +5 -5
  40. package/dist/resource-view/index.d.ts +1 -1
  41. package/dist/schema/index.d.ts +3 -3
  42. package/dist/testing/index.d.ts +2 -2
  43. package/dist/{types-D4Bi_Iq8.d.ts → types-BriIV4e_.d.ts} +2 -0
  44. package/dist/{workspaces-BKhloJPK.d.ts → workspaces-CxpiFu2-.d.ts} +9 -1
  45. package/dist/workspaces.d.ts +1 -1
  46. package/dist/workspaces.js +2 -1
  47. package/dist/{write-outcome-CHPT7Slm.d.ts → write-outcome-CkQXgtJq.d.ts} +1 -1
  48. package/package.json +14 -4
  49. package/dist/chunk-JTRRAVR4.js.map +0 -1
@@ -0,0 +1,334 @@
1
+ import { R as ResourceFormFieldDef } from '../types-BriIV4e_.js';
2
+ import { Day } from '../dates.js';
3
+
4
+ /**
5
+ * `value` kept inside `min` and `max` (either may be left out). `NaN` reads as 0 (then clamped),
6
+ * so a field never shows "NaN". A `min` above `max` is a caller's mistake and throws a RangeError
7
+ * rather than picking one end silently.
8
+ */
9
+ declare function clampNumber(value: number, min?: number, max?: number): number;
10
+ /**
11
+ * `value` on the grid of `step`s counted from `min` (min 1, step 2: 1, 3, 5…), inside `min` and
12
+ * `max`. A step of 0 or less, or one that isn't finite, only clamps.
13
+ */
14
+ declare function snapToStep(value: number, step: number, min: number, max: number): number;
15
+ interface NumberStepOptions {
16
+ min?: number | undefined;
17
+ max?: number | undefined;
18
+ /** Default 1. */
19
+ step?: number | undefined;
20
+ }
21
+ /** One press of a stepper: `value` moved by `step` up (`1`) or down (`-1`), kept inside the range. */
22
+ declare function stepNumber(value: number, direction: 1 | -1, options?: NumberStepOptions): number;
23
+ /** Whether a stepper's down (`-1`) or up (`1`) button can move `value`. */
24
+ declare function canStepNumber(value: number, direction: 1 | -1, options?: NumberStepOptions): boolean;
25
+ interface ParseNumberOptions {
26
+ /**
27
+ * The locale whose marks the text uses (`"de-DE"`: "1.234,5"). Its group and decimal marks are
28
+ * read from `Intl.NumberFormat`. Without one, the marks are worked out from the text.
29
+ */
30
+ locale?: string | undefined;
31
+ }
32
+ /**
33
+ * A number as typed: "1.5", "-3", "1,234" and "1,234.5" (commas group thousands), "1,5" and
34
+ * "1.234,5" (a comma as the decimal mark), "1 000" and "1'000". Anything else (an empty field,
35
+ * "abc", "1.2.3", "1 5") is `null`, so the field keeps its value instead of becoming NaN. Only
36
+ * ASCII digits are read ("١٢٣" is `null`).
37
+ *
38
+ * A run of spaces (no-break and narrow ones too) or apostrophes (' and ’) is a group mark, read
39
+ * like any other: only between whole groups of three in the whole part ("1 000,25", "1’234.5";
40
+ * not "1 5" or "12 34,5"), with at most one "," or "." after it as the decimal mark.
41
+ *
42
+ * Without a `locale`, the last of "." and "," is the decimal mark when both appear; a mark that
43
+ * appears more than once groups thousands; one comma followed by exactly three digits groups
44
+ * thousands ("1,234" is 1234), any other single comma is the decimal mark ("1,5", "0,125").
45
+ * Pass `locale` to read the text with that locale's marks instead, as strictly.
46
+ */
47
+ declare function parseNumberInput(text: string, options?: ParseNumberOptions): number | null;
48
+ interface NumberDraftOptions {
49
+ min?: number | undefined;
50
+ max?: number | undefined;
51
+ /** Decimal places the field keeps. A typed number with more is passed on only when it is committed, rounded. */
52
+ precision?: number | undefined;
53
+ locale?: string | undefined;
54
+ }
55
+ /**
56
+ * What a number field does with its text as it is typed. `value` is the number it reads (`null`
57
+ * while it isn't one: "", "-", "1."), and `ready` whether to pass it on now: inside `min` and
58
+ * `max`, within `precision`, and not text that may still be a thousands group ("1,2" and "1,23",
59
+ * with no `locale`, may be on the way to "1,234"). Anything not ready is passed on when the field
60
+ * is left, through `commitNumberDraft`, so typing "1" on the way to "15" with `min` 10 never
61
+ * sends 10, and typing "1,234" never sends 1.2.
62
+ */
63
+ declare function readNumberDraft(text: string, options?: NumberDraftOptions): {
64
+ value: number | null;
65
+ ready: boolean;
66
+ };
67
+ /**
68
+ * The number a field keeps when it is left: what's typed, rounded to `precision` and clamped to
69
+ * `min` and `max`, so what is stored is what the field then shows. `null` when the text isn't a number.
70
+ */
71
+ declare function commitNumberDraft(text: string, options?: NumberDraftOptions): number | null;
72
+ /**
73
+ * Where two thumbs of a range slider may go: each snapped, the low one never past the high one.
74
+ * `moving` says which thumb the person moved, so it stops at the other instead of pushing it.
75
+ */
76
+ declare function clampRange(value: readonly [number, number], options: {
77
+ min: number;
78
+ max: number;
79
+ step?: number | undefined;
80
+ moving?: 0 | 1 | undefined;
81
+ }): [number, number];
82
+
83
+ /** Whether every word of `query` appears in one of `texts` (an empty query matches everything). */
84
+ declare function matchesQuery(texts: string | readonly (string | null | undefined)[], query: string): boolean;
85
+ /** An option a combobox lists: what it stores, what it shows, and a second line. */
86
+ interface ComboboxOption<T = string> {
87
+ value: T;
88
+ label: string;
89
+ description?: string | undefined;
90
+ disabled?: boolean | undefined;
91
+ }
92
+ /** The options whose label or description matches `query`, in the order given. */
93
+ declare function filterOptions<O extends {
94
+ label: string;
95
+ description?: string | undefined;
96
+ }>(options: readonly O[], query: string): O[];
97
+
98
+ /** `items` with the one at `from` moved to `to` (both from 0, `to` counted after it is taken out). */
99
+ declare function moveItem<T>(items: readonly T[], from: number, to: number): T[];
100
+ /**
101
+ * The index a dragged item lands on: its start index plus how far it was dragged, in whole rows
102
+ * (`offset` over `rowSize`), kept inside the list.
103
+ */
104
+ declare function dropIndex(start: number, offset: number, rowSize: number, total: number): number;
105
+ /**
106
+ * A move's words for a screen reader, from a template with `{name}`, `{n}` (the new position,
107
+ * from 1) and `{total}`: "Week 1 moved to position 3 of 5."
108
+ */
109
+ declare function movedAnnouncement(name: string, to: number, total: number, template?: string): string;
110
+
111
+ /** A time of day: hours 0-23, minutes 0-59. */
112
+ interface TimeOfDay {
113
+ hours: number;
114
+ minutes: number;
115
+ }
116
+ /**
117
+ * A time as typed: "14:30", "2:30 pm", "2pm", "1430", "9.05". `null` when it isn't one, so the
118
+ * field keeps its last good value.
119
+ */
120
+ declare function parseTimeOfDay(text: string): TimeOfDay | null;
121
+ /** "14:30" (24-hour, the stored form and an `<input type="time">`'s value). */
122
+ declare function timeToValue(time: TimeOfDay): string;
123
+ /** A time shown to a person: "2:30 PM" with `hour12`, else "14:30". */
124
+ declare function formatTimeOfDay(time: TimeOfDay, options?: {
125
+ hour12?: boolean | undefined;
126
+ }): string;
127
+ /** The time of day a Date holds, on the device's clock. */
128
+ declare function timeOfDate(date: Date): TimeOfDay;
129
+ /** `date` with its time of day set (seconds cleared), on the device's clock. */
130
+ declare function withTimeOfDay(date: Date, time: TimeOfDay): Date;
131
+ /** Every time from 00:00 in steps of `minutes` (default 30), for a picker's list. */
132
+ declare function timeSlots(minutes?: number): TimeOfDay[];
133
+
134
+ /** The two colour schemes a chart's series can name a colour for. */
135
+ type ChartScheme = "light" | "dark";
136
+ /**
137
+ * One series of a chart config: its label, and a colour for both schemes (`color`) or one per
138
+ * scheme (`theme`). The web's `ChartConfig` is a record of these.
139
+ */
140
+ interface ChartSeriesConfig<Label = unknown> {
141
+ label?: Label;
142
+ color?: string | undefined;
143
+ theme?: Partial<Record<ChartScheme, string>> | undefined;
144
+ }
145
+ /** A series' colour in a scheme: its `theme` colour for the scheme, else `color`. */
146
+ declare function chartSeriesColor(series: Pick<ChartSeriesConfig, "color" | "theme"> | undefined, scheme: ChartScheme): string | undefined;
147
+ /**
148
+ * The design token a colour names, when it is one of the chart tokens: `"var(--chart-2)"`,
149
+ * `"hsl(var(--chart-2))"` and `"chart-2"` are all `"chart-2"`. A literal colour is `undefined`.
150
+ */
151
+ declare function chartTokenOf(color: string | undefined): `chart-${number}` | undefined;
152
+ /** The default token for the `index`th series: chart-1 to chart-5, then round again. */
153
+ declare function defaultChartToken(index: number): `chart-${number}`;
154
+ /**
155
+ * The value axis for `keys` over `rows`: from 0 (or the lowest value, when below 0) to the
156
+ * highest, widened to round ticks.
157
+ */
158
+ declare function chartDomain(rows: readonly Record<string, unknown>[], keys: readonly string[], options?: {
159
+ ticks?: number | undefined;
160
+ stacked?: boolean | undefined;
161
+ }): {
162
+ min: number;
163
+ max: number;
164
+ ticks: number[];
165
+ };
166
+ /** Where `value` falls on an axis `size` long (0 at `min`, `size` at `max`). */
167
+ declare function chartPosition(value: number, domain: {
168
+ min: number;
169
+ max: number;
170
+ }, size: number): number;
171
+ /**
172
+ * What a screen reader hears for a chart, since it can't see the bars: each series and its
173
+ * values, "Visitors: Jan 120, Feb 140. Signups: Jan 12, Feb 18."
174
+ */
175
+ declare function chartSummary(rows: readonly Record<string, unknown>[], xKey: string, series: readonly {
176
+ key: string;
177
+ label: string;
178
+ }[], format?: (value: number) => string): string;
179
+
180
+ /** Digits only, the usual SMS and authenticator code. */
181
+ declare const OTP_PATTERN_DIGITS = "^\\d+$";
182
+ /** A pasted or autofilled code without the spaces, dashes and dots it is often grouped with ("123-456"). */
183
+ declare function stripOtpSeparators(text: string): string;
184
+ /**
185
+ * What a code field keeps of `text`: separators stripped, cut to `length` characters, and only
186
+ * when the whole code then matches `pattern`. `null` means it doesn't, and the field keeps the
187
+ * code it had (input-otp refuses such a change the same way).
188
+ */
189
+ declare function sanitizeOtp(text: string, length: number, pattern?: string): string | null;
190
+ /** One box of a code: its character, and whether the caret is in it. */
191
+ interface OtpSlot {
192
+ char: string | null;
193
+ isActive: boolean;
194
+ }
195
+ /** The boxes for `value`: each character in its box, and the caret in the first empty one (or the last). */
196
+ declare function otpSlots(value: string, length: number, focused: boolean): OtpSlot[];
197
+ /** Whether every box is filled: the moment to submit. */
198
+ declare function otpComplete(value: string, length: number): boolean;
199
+
200
+ /** Whether a repeating group with `count` items may add one, and may remove one. */
201
+ declare function fieldArrayLimits(count: number, field: Pick<ResourceFormFieldDef, "arrayMin" | "arrayMax">): {
202
+ canAdd: boolean;
203
+ canRemove: boolean;
204
+ };
205
+ /**
206
+ * The add button's words for a group: "Add Contact" for "Contacts", "Add Address" for
207
+ * "Addresses", "Add Status" for "Status". The field's `arrayItemLabel` (its one item's name)
208
+ * wins over the guess, for a plural English doesn't make with an "s".
209
+ */
210
+ declare function fieldArrayAddLabel(label: string, itemLabel?: string | undefined): string;
211
+ /** A wizard step's fields, in the form's order, without those hidden for these values. */
212
+ declare function wizardStepFields<F extends Pick<ResourceFormFieldDef, "key" | "visible">>(fields: readonly F[], stepFields: readonly string[], values: Record<string, unknown>): F[];
213
+ /** The progress line over a wizard, from `useWizard()`'s state: "Step 2 of 4" and its `progress` as a percent. */
214
+ declare function wizardProgressLabel(wizard: {
215
+ currentStep: number;
216
+ totalSteps: number;
217
+ progress: number;
218
+ }): {
219
+ step: string;
220
+ percent: string;
221
+ };
222
+ /** Default most a file may weigh: 10 MB. */
223
+ declare const DEFAULT_MAX_FILE_SIZE: number;
224
+ /** A file's size in words: "512 B", "1.5 KB", "3.2 MB". */
225
+ declare function formatFileSize(bytes: number): string;
226
+ /** What an upload field needs to know about a picked file, on either platform. */
227
+ interface PickedFileInfo {
228
+ name: string;
229
+ /** MIME type, e.g. "image/png". Empty when unknown. */
230
+ type?: string | undefined;
231
+ /** Bytes, when known. */
232
+ size?: number | undefined;
233
+ }
234
+ /**
235
+ * Why `file` can't be added, in words, or `null` when it can: too heavy for `maxSize`, or not a
236
+ * type `accept` lists.
237
+ */
238
+ declare function fileProblem(file: PickedFileInfo, options: {
239
+ accept?: string | undefined;
240
+ maxSize?: number | undefined;
241
+ }): string | null;
242
+ /** An upload field's `accept`: the field's, else images for an image field. */
243
+ declare function fieldAccept(field: Pick<ResourceFormFieldDef, "accept" | "type">): string | undefined;
244
+
245
+ /** A stat's change: "+12% vs last week", and whether it went up. */
246
+ declare function formatTrend(trend: {
247
+ value: number;
248
+ label: string;
249
+ }): {
250
+ text: string;
251
+ positive: boolean;
252
+ };
253
+ /** The goal and task statuses StatusBadge draws. */
254
+ type StatusBadgeStatus = "onTrack" | "atRisk" | "offTrack" | "done" | "blocked" | "inProgress";
255
+ /** Each status's tone: the tint both platforms draw it in. */
256
+ declare const STATUS_BADGE_TONES: Readonly<Record<StatusBadgeStatus, "success" | "warning" | "info" | "danger">>;
257
+ /** A status in words, for a badge with no children: "On track", "In progress". */
258
+ declare function statusBadgeLabel(status: StatusBadgeStatus): string;
259
+ /** Where a step is in a stepper, from the current one. */
260
+ type StepState = "complete" | "current" | "upcoming";
261
+ /** The state of step `index` when `current` is the step the person is on. */
262
+ declare function stepState(index: number, current: number): StepState;
263
+ /**
264
+ * The day group a notification goes under: "Upcoming" for a later day (scheduled, or a clock
265
+ * that runs ahead), then "Today", "Yesterday" and "Earlier".
266
+ */
267
+ type NotificationDayBucket = "Upcoming" | "Today" | "Yesterday" | "Earlier";
268
+ /** The day groups in the order a list shows them. */
269
+ declare const NOTIFICATION_DAY_BUCKETS: readonly NotificationDayBucket[];
270
+ interface NotificationClock {
271
+ /** The moment the groups count from. Default now. */
272
+ now?: Date | undefined;
273
+ /**
274
+ * The zone whose days are counted (an IANA name, "Europe/Paris"). Default the device's. A
275
+ * server rendering the list passes the person's zone, or its days won't be theirs.
276
+ */
277
+ timeZone?: string | undefined;
278
+ }
279
+ /** Which day group `timestamp` belongs to, counted in calendar days on `timeZone`'s clock. */
280
+ declare function notificationDayBucket(timestamp: string | Date, clock?: NotificationClock): NotificationDayBucket;
281
+ /**
282
+ * Notifications under day headings (Upcoming, Today, Yesterday, Earlier), in that order, each
283
+ * keeping the order given. Empty groups are left out.
284
+ */
285
+ declare function groupNotificationsByDay<N extends {
286
+ timestamp: string | Date;
287
+ }>(items: readonly N[], clock?: NotificationClock): {
288
+ title: NotificationDayBucket;
289
+ data: N[];
290
+ }[];
291
+ /** Where a custom view is: the states Genesis draws, then `ready` for the app's own. */
292
+ type CustomViewStatus = "loading" | "error" | "empty" | "ready";
293
+ /** A custom view's state from its query: an error first, then the first load, then no rows. */
294
+ declare function customViewStatus(query: {
295
+ error: unknown;
296
+ loading: boolean;
297
+ empty: boolean;
298
+ }): CustomViewStatus;
299
+
300
+ /** The slide a scroll `offset` rests on, for slides `pageSize` wide, kept inside `count`. */
301
+ declare function carouselIndex(offset: number, pageSize: number, count: number): number;
302
+ /** The scroll offset that shows slide `index`. */
303
+ declare function carouselOffset(index: number, pageSize: number): number;
304
+
305
+ /** A Date's calendar day on the device's clock (a picker's dates are the person's own days). */
306
+ declare function dayOfDate(date: Date): Day;
307
+ /** A calendar day as a Date at local midnight. */
308
+ declare function dateOfDay(day: Day): Date;
309
+ /**
310
+ * The weeks a month's grid shows: whole weeks, from `weekStartsOn` (0 Sunday to 6 Saturday;
311
+ * default 1, Monday, as genesis-core's `startOfWeek` and `monthGridRange`). Any other
312
+ * `weekStartsOn` throws a RangeError, as `weekdayDays` does.
313
+ */
314
+ declare function monthWeeks(month: Day, weekStartsOn?: number): Day[][];
315
+ /** Whether `day` is inside a range, both ends included (an open end takes nothing past the other). */
316
+ declare function dayInRange(day: Day, range: {
317
+ from?: Day | undefined;
318
+ to?: Day | undefined;
319
+ }): boolean;
320
+ /** A range after picking `day`: a new start, or the end once the start is set (swapped if earlier). */
321
+ declare function pickRangeDay(range: {
322
+ from?: Day | undefined;
323
+ to?: Day | undefined;
324
+ } | undefined, day: Day): {
325
+ from: Day;
326
+ to?: Day;
327
+ };
328
+ /**
329
+ * The seven weekday dates of a week starting `weekStartsOn`, for the grid's header: the same
330
+ * default (1, Monday) and the same RangeError outside 0 to 6 as `monthWeeks`.
331
+ */
332
+ declare function weekdayDays(weekStartsOn?: number): Day[];
333
+
334
+ export { type ChartScheme, type ChartSeriesConfig, type ComboboxOption, type CustomViewStatus, DEFAULT_MAX_FILE_SIZE, NOTIFICATION_DAY_BUCKETS, type NotificationClock, type NotificationDayBucket, type NumberDraftOptions, type NumberStepOptions, OTP_PATTERN_DIGITS, type OtpSlot, type ParseNumberOptions, type PickedFileInfo, STATUS_BADGE_TONES, type StatusBadgeStatus, type StepState, type TimeOfDay, canStepNumber, carouselIndex, carouselOffset, chartDomain, chartPosition, chartSeriesColor, chartSummary, chartTokenOf, clampNumber, clampRange, commitNumberDraft, customViewStatus, dateOfDay, dayInRange, dayOfDate, defaultChartToken, dropIndex, fieldAccept, fieldArrayAddLabel, fieldArrayLimits, fileProblem, filterOptions, formatFileSize, formatTimeOfDay, formatTrend, groupNotificationsByDay, matchesQuery, monthWeeks, moveItem, movedAnnouncement, notificationDayBucket, otpComplete, otpSlots, parseNumberInput, parseTimeOfDay, pickRangeDay, readNumberDraft, sanitizeOtp, snapToStep, statusBadgeLabel, stepNumber, stepState, stripOtpSeparators, timeOfDate, timeSlots, timeToValue, weekdayDays, withTimeOfDay, wizardProgressLabel, wizardStepFields };