@nxgt/material 3.25.1 → 3.26.0

package/dist/lib/components/ui/display/change-history/types.d.ts

@@ -0,0 +1,95 @@
+import { ReactNode } from 'react';
+import { Tone } from '../../tones.js';
+import { ResolvedKind } from './kinds.js';
+/** One field that changed in an entry. */
+export type ChangeHistoryChange = {
+    /** The name of what changed ("Status", "Billing plan", "Visibility"). */
+    field: ReactNode;
+    /** The value before. Unset on a field that had none ("Empty" shows). */
+    before?: ReactNode;
+    /** The value after. */
+    after?: ReactNode;
+    /** The app hides the values: only "Hidden" shows, never `before` or `after`. */
+    redacted?: boolean;
+};
+/** How a kind of entry looks. Always shown with its word, never by colour alone. */
+export type ChangeHistoryKind = {
+    /** The word that accompanies the colour ("Archived"). */
+    label: string;
+    /**
+     * What the author did, said after their name ("archived this"). With a verb,
+     * the rail drops the kind badge: the sentence already carries the word.
+     */
+    verb?: string;
+    /** The dot's or the chip's icon; `null` removes it. */
+    icon: ReactNode;
+    tone: Tone;
+    /**
+     * An entry of this kind lists values only (no "before" to compare with,
+     * "N fields set"). Default: true for `created`, false for any other kind.
+     */
+    creation?: boolean;
+};
+/**
+ * What the app passes for `kinds`: a whole new kind, or the parts of a
+ * built-in kind it overrides (`updated: { tone: 'info' }`).
+ */
+export type ChangeHistoryKindOverride = Partial<ChangeHistoryKind>;
+export type ChangeHistoryEntry = {
+    id: string;
+    /** A key of the kinds: `created`, `updated`, `archived`, `restored`, `purged`, `deleted`, or one the app declared. */
+    kind: string;
+    at: Date | string | number;
+    author: {
+        name: string;
+        src?: string;
+    };
+    changes: ChangeHistoryChange[];
+};
+export type ChangeHistoryVariant = 'rail' | 'cards';
+/** What `RailEntry` and `CardEntry` share. */
+export type EntryProps = {
+    entry: ChangeHistoryEntry;
+    kind: ResolvedKind;
+    summary: string;
+    collapseAfter: number;
+    now?: ChangeHistoryEntry['at'];
+    timeZone?: string;
+};
+export type ChangeHistoryProps = {
+    entries: ChangeHistoryEntry[];
+    /** Merged over the built-in kinds (created: success, updated: neutral, archived and restored: warning, purged and deleted: error). */
+    kinds?: Record<string, ChangeHistoryKindOverride>;
+    /** `rail` (default): a thin rail of toned dots. `cards`: a card tinted by kind with a Before/After block. */
+    variant?: ChangeHistoryVariant;
+    /** `day` (default): one heading per day (sticky on the rail), newest first. `none`: one list, in the order given. */
+    groupBy?: 'day' | 'none';
+    /** An entry with more changes than this collapses behind "N fields changed". Default 3. */
+    collapseAfter?: number;
+    /** A slot above the list, for a `Filter` bar. */
+    filter?: ReactNode;
+    loading?: boolean;
+    hasMore?: boolean;
+    onLoadMore?: () => void;
+    /** The count over all pages; the footer says "Showing X of Y". */
+    total?: number;
+    /** Replaces the empty state. */
+    empty?: ReactNode;
+    /**
+     * The reference instant for "Today" and "5 minutes ago". Default: the
+     * clock of the machine that renders, so a server-rendered page can differ
+     * from its hydration: pass `now` (and `timeZone`) from the server.
+     */
+    now?: Date | string | number;
+    /**
+     * An IANA zone (`Europe/Paris`) for the day grouping, the day heading, the
+     * entry summary and the exact time. Default: the machine's zone, so the
+     * server and the browser can disagree: pass the same `now` and `timeZone`
+     * from the server to group and label identically on both.
+     */
+    timeZone?: string;
+    /** The level of the day headings, 2 to 6. Default 3. */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    'aria-label'?: string;
+    className?: string;
+};

package/dist/lib/components/ui/display/change-history/use-entry-summary.d.ts

@@ -0,0 +1,8 @@
+import { ChangeHistoryEntry } from './types.js';
+/**
+ * The accessible summary of an entry, "{kind} by {author}, {date and time}":
+ * "Updated by Ada Lovelace, August 2nd, 2026 4:00 PM", localized (`PPP p`)
+ * and read in `timeZone` when given. An entry without a valid date drops the
+ * date.
+ */
+export declare function useEntrySummary(timeZone?: string): (entry: ChangeHistoryEntry, kindLabel: string) => string;

package/dist/lib/components/ui/display/change-history/zoned.d.ts

@@ -0,0 +1,12 @@
+import { DayInput } from '@nxgt/material-core/day-math';
+/**
+ * The wall clock of an instant in `timeZone`, as a `Date` whose local
+ * getters read it: `wallClock('2026-08-02T23:30:00Z', 'Asia/Tokyo')` is
+ * August 3rd, 08:30 whatever zone the machine runs in. The day maths
+ * (`daysAgo`, `localIsoDay`, `formatDayLabel`) then work on it unchanged, so
+ * a server and a browser group and label the same way. Without a
+ * `timeZone` (or with one `Intl` does not know), the instant itself.
+ */
+export declare function wallClock(value: DayInput, timeZone?: string): Date;
+/** The wall clock as an offset-less ISO string, which date-fns reads as local: `2026-08-03T08:30:00`. */
+export declare function wallIso(value: DayInput, timeZone?: string): string;

package/dist/lib/components/ui/display/day-separator/day-separator.d.ts

@@ -16,6 +16,11 @@ export type DaySeparatorProps = Omit<ComponentProps<'div'>, 'children'> & Varian
     now?: DayInput;
     /** A BCP 47 tag for the date. Default: the provider's language, else `en`. */
     locale?: string;
+    /**
+     * The element it renders. `h2` to `h6` make it a real heading of that
+     * level (the hairlines stay decorative). Default: a `div`.
+     */
+    as?: 'div' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 };
 /**
  * A heading between the days of a message list or a feed: hairlines on
@@ -23,5 +28,5 @@ export type DaySeparatorProps = Omit<ComponentProps<'div'>, 'children'> & Varian
  * the date. `sticky` keeps it at the top of its scroll box while its day
  * scrolls by; `isNewDay(previous, current)` tells where one goes.
  */
-export declare function DaySeparator({ date, label, badge, now, locale, variant, sticky, className, ...props }: DaySeparatorProps): import("react").JSX.Element;
+export declare function DaySeparator({ date, label, badge, now, locale, variant, sticky, as: Tag, className, ...props }: DaySeparatorProps): import("react").JSX.Element;
 export { daySeparatorVariants };

package/dist/lib/components/ui/display/index.d.ts

@@ -6,6 +6,7 @@ export * from './avatar-group/index.js';
 export * from './badge/index.js';
 export * from './barecode/index.js';
 export * from './cards/index.js';
+export * from './change-history/index.js';
 export * from './chip/index.js';
 export * from './code/index.js';
 export * from './count-badge/index.js';

package/dist/lib/components/ui/display/timeline/relative-time.d.ts

@@ -1,7 +1,18 @@
+import { ReactNode, Ref } from 'react';
 import { TimelineTimestamp } from './types.js';
 export type RelativeTimeProps = {
     date: TimelineTimestamp;
     addSuffix?: boolean;
     className?: string;
+    /** The reference instant for "5 minutes ago". Default: now. */
+    now?: TimelineTimestamp;
+    /** Reaches the keyboard (`tabIndex` 0) with a focus ring, so the exact time can show on focus. */
+    focusable?: boolean;
+    /**
+     * Shows the exact time (`PPPP p`, localized) in a tooltip on hover and on
+     * focus; a node replaces that text. Unset: the native `title` stays.
+     */
+    tooltip?: boolean | ReactNode;
+    ref?: Ref<HTMLTimeElement>;
 };
-export declare function RelativeTime({ date, addSuffix, className, }: RelativeTimeProps): import("react").JSX.Element | null;
+export declare function RelativeTime({ date, addSuffix, className, now, focusable, tooltip, ref, }: RelativeTimeProps): import("react").JSX.Element | null;

package/dist/lib/i18n/resources/en/en.d.ts

@@ -1843,6 +1843,42 @@ export declare const en: {
             today: string;
             yesterday: string;
         };
+        history: {
+            label: string;
+            loading: string;
+            "empty-title": string;
+            "empty-description": string;
+            hidden: string;
+            "no-value": string;
+            "changed-to": string;
+            before: string;
+            after: string;
+            value: string;
+            "hide-changes": string;
+            "fields-changed": string;
+            "fields-set": string;
+            "more-names": string;
+            showing: string;
+            "load-more": string;
+            summary: string;
+            "summary-undated": string;
+            kind: {
+                created: string;
+                updated: string;
+                archived: string;
+                restored: string;
+                purged: string;
+                deleted: string;
+            };
+            verb: {
+                created: string;
+                updated: string;
+                archived: string;
+                restored: string;
+                purged: string;
+                deleted: string;
+            };
+        };
         map: {
             "you-are-here": string;
             "zoom-in": string;

package/dist/lib/i18n/resources/en/material.json.d.ts

@@ -1833,6 +1833,42 @@ declare const _default: {
 		"today": "Today",
 		"yesterday": "Yesterday"
 	},
+	"history": {
+		"label": "Change history",
+		"loading": "Loading history",
+		"empty-title": "No history yet",
+		"empty-description": "Changes will appear here.",
+		"hidden": "Hidden",
+		"no-value": "Empty",
+		"changed-to": "changed to",
+		"before": "Before",
+		"after": "After",
+		"value": "Value",
+		"hide-changes": "Hide changes",
+		"fields-changed": "{count, plural, one {# field changed} other {# fields changed}}",
+		"fields-set": "{count, plural, one {# field set} other {# fields set}}",
+		"more-names": "+{count}",
+		"showing": "Showing {shown} of {total}",
+		"load-more": "Load more",
+		"summary": "{kind} by {author}, {date}",
+		"summary-undated": "{kind} by {author}",
+		"kind": {
+			"created": "Created",
+			"updated": "Updated",
+			"archived": "Archived",
+			"restored": "Restored",
+			"purged": "Purged",
+			"deleted": "Deleted"
+		},
+		"verb": {
+			"created": "created this",
+			"updated": "updated {count, plural, one {# field} other {# fields}}",
+			"archived": "archived this",
+			"restored": "restored this",
+			"purged": "purged this",
+			"deleted": "deleted this"
+		}
+	},
 	"map": {
 		"you-are-here": "You are here",
 		"zoom-in": "Zoom in",

package/dist/lib/i18n/resources/fr/fr.d.ts

@@ -1843,6 +1843,42 @@ export declare const fr: {
             today: string;
             yesterday: string;
         };
+        history: {
+            label: string;
+            loading: string;
+            "empty-title": string;
+            "empty-description": string;
+            hidden: string;
+            "no-value": string;
+            "changed-to": string;
+            before: string;
+            after: string;
+            value: string;
+            "hide-changes": string;
+            "fields-changed": string;
+            "fields-set": string;
+            "more-names": string;
+            showing: string;
+            "load-more": string;
+            summary: string;
+            "summary-undated": string;
+            kind: {
+                created: string;
+                updated: string;
+                archived: string;
+                restored: string;
+                purged: string;
+                deleted: string;
+            };
+            verb: {
+                created: string;
+                updated: string;
+                archived: string;
+                restored: string;
+                purged: string;
+                deleted: string;
+            };
+        };
         map: {
             "you-are-here": string;
             "zoom-in": string;

package/dist/lib/i18n/resources/fr/material.json.d.ts

@@ -1833,6 +1833,42 @@ declare const _default: {
 		"today": "Aujourd'hui",
 		"yesterday": "Hier"
 	},
+	"history": {
+		"label": "Historique des modifications",
+		"loading": "Chargement de l'historique",
+		"empty-title": "Aucun historique",
+		"empty-description": "Les modifications apparaîtront ici.",
+		"hidden": "Masqué",
+		"no-value": "Vide",
+		"changed-to": "devient",
+		"before": "Avant",
+		"after": "Après",
+		"value": "Valeur",
+		"hide-changes": "Masquer les modifications",
+		"fields-changed": "{count, plural, one {# champ modifié} other {# champs modifiés}}",
+		"fields-set": "{count, plural, one {# champ renseigné} other {# champs renseignés}}",
+		"more-names": "+{count}",
+		"showing": "{shown} sur {total} affichées",
+		"load-more": "Charger plus",
+		"summary": "{kind} par {author}, {date}",
+		"summary-undated": "{kind} par {author}",
+		"kind": {
+			"created": "Création",
+			"updated": "Modification",
+			"archived": "Archivage",
+			"restored": "Restauration",
+			"purged": "Purge",
+			"deleted": "Suppression"
+		},
+		"verb": {
+			"created": "a créé cet élément",
+			"updated": "a modifié {count, plural, one {# champ} other {# champs}}",
+			"archived": "a archivé cet élément",
+			"restored": "a restauré cet élément",
+			"purged": "a purgé cet élément",
+			"deleted": "a supprimé cet élément"
+		}
+	},
 	"map": {
 		"you-are-here": "Vous êtes ici",
 		"zoom-in": "Zoom avant",

package/dist/lib/i18n/resources/resources.d.ts

@@ -1841,6 +1841,42 @@ export declare const resources: {
                 today: string;
                 yesterday: string;
             };
+            history: {
+                label: string;
+                loading: string;
+                "empty-title": string;
+                "empty-description": string;
+                hidden: string;
+                "no-value": string;
+                "changed-to": string;
+                before: string;
+                after: string;
+                value: string;
+                "hide-changes": string;
+                "fields-changed": string;
+                "fields-set": string;
+                "more-names": string;
+                showing: string;
+                "load-more": string;
+                summary: string;
+                "summary-undated": string;
+                kind: {
+                    created: string;
+                    updated: string;
+                    archived: string;
+                    restored: string;
+                    purged: string;
+                    deleted: string;
+                };
+                verb: {
+                    created: string;
+                    updated: string;
+                    archived: string;
+                    restored: string;
+                    purged: string;
+                    deleted: string;
+                };
+            };
             map: {
                 "you-are-here": string;
                 "zoom-in": string;
@@ -4523,6 +4559,42 @@ export declare const resources: {
                 today: string;
                 yesterday: string;
             };
+            history: {
+                label: string;
+                loading: string;
+                "empty-title": string;
+                "empty-description": string;
+                hidden: string;
+                "no-value": string;
+                "changed-to": string;
+                before: string;
+                after: string;
+                value: string;
+                "hide-changes": string;
+                "fields-changed": string;
+                "fields-set": string;
+                "more-names": string;
+                showing: string;
+                "load-more": string;
+                summary: string;
+                "summary-undated": string;
+                kind: {
+                    created: string;
+                    updated: string;
+                    archived: string;
+                    restored: string;
+                    purged: string;
+                    deleted: string;
+                };
+                verb: {
+                    created: string;
+                    updated: string;
+                    archived: string;
+                    restored: string;
+                    purged: string;
+                    deleted: string;
+                };
+            };
             map: {
                 "you-are-here": string;
                 "zoom-in": string;