@apliteni/apliteni-ui 0.55.0 → 0.56.0

package/package.json

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

package/react/README.md

@@ -385,8 +385,20 @@ uses its normal opening focus.
 
 `Timeline` displays a record’s events in the order provided. Pass events from oldest
 to newest, with stable IDs, machine-readable `dateTime` values, and formatted
-`timestamp` text.
-Descriptions should say what changed and to where.
+`timestamp` text. Place Timeline on a page or card reading surface, never a grey
+fill; the standalone stories compose it inside `Card`.
+Descriptions should say what changed and to where. Optional `kind` accepts
+`person`, `rule`, or `reversal` (`TimelineEventKind`); these show the kit’s user,
+bolt, or refresh glyph in a 20px ring. The last event is newest and its ring is
+filled, using the danger colour for a reversal. Events without a kind keep their
+dot. Mixed histories mute older dots; older reversal glyphs keep danger ink.
+
+Initial history stays still, including history loaded into an empty list.
+New IDs added to a non-empty history enter with the kit’s slide-up motion (400ms)
+and marker scale-in (250ms, delayed 60ms). Existing IDs stay still when reordered
+or edited. Reduced motion disables the entrance. Optional `relativeTimestamp`
+(such as "just now") appears beside the absolute stamp only on the newest row,
+in accent ink. The caller updates this text; Timeline does not run a clock.
 
 ```tsx
 <Timeline aria-label="Record history" events={[
@@ -400,11 +412,9 @@ Descriptions should say what changed and to where.
 
 Omit `undo` for read-only events. For a reversible batch, pass
 `undo: { label: 'Undo batch DEMO-12', onUndo }`. The app checks permissions,
-asks for confirmation when the batch affects finalized records, reverses the
-entire batch, and adds a new event. Timeline only calls `onUndo`; it does not
+reverses the entire batch, and adds a new event without a confirmation dialog. Timeline only calls `onUndo`; it does not
 modify history.
-Import both the kit CSS and React CSS. The Privileged story shows confirmation
-and a reversing event.
+Import both the kit CSS and React CSS. The Privileged story shows Undo adding a reversing event.
 
 ## Fields
 

package/react/dist/index.css

@@ -189,8 +189,7 @@
 .ui-timeline__event:last-child::before {
   display: none;
 }
-.ui-timeline__event::after {
-  content: "";
+.ui-timeline__marker {
   position: absolute;
   inset-inline-start: 0;
   inset-block-start: calc(0.75em - var(--space-2) / 2);
@@ -214,6 +213,10 @@
 .ui-timeline__meta {
   font-size: var(--text-xs);
 }
+.ui-timeline__relative {
+  color: var(--accent);
+  font-size: var(--text-xs);
+}
 .ui-timeline__description {
   margin: var(--space-1) 0;
 }
@@ -224,6 +227,55 @@
 .ui-timeline__undo:focus-visible {
   color: var(--pink);
 }
+.ui-timeline--kinds .ui-timeline__event {
+  padding-inline-start: var(--space-8);
+}
+.ui-timeline--kinds .ui-timeline__event::before {
+  inset-inline-start: calc(var(--space-5) / 2);
+}
+.ui-timeline--kinds .ui-timeline__marker {
+  inset-inline-start: calc((var(--space-5) - var(--space-2)) / 2);
+  background: var(--muted);
+}
+.ui-timeline--kinds .ui-timeline__event:last-child .ui-timeline__marker {
+  background: var(--accent);
+}
+.ui-timeline--kinds .ui-timeline__marker--kind {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  inset-inline-start: 0;
+  inset-block-start: calc(0.75em - var(--space-5) / 2);
+  width: var(--space-5);
+  height: var(--space-5);
+  border: 1px solid var(--muted);
+  background: var(--surface);
+  color: var(--muted);
+}
+.ui-timeline--kinds .ui-timeline__marker--reversal {
+  color: var(--pink);
+}
+.ui-timeline__marker--kind svg {
+  width: var(--space-3);
+  height: var(--space-3);
+}
+.ui-timeline--kinds .ui-timeline__event:last-child .ui-timeline__marker--kind {
+  border-color: var(--accent-strong);
+  background: var(--accent-strong);
+  color: var(--accent-contrast);
+}
+.ui-timeline--kinds .ui-timeline__event:last-child .ui-timeline__marker--reversal {
+  border-color: var(--pink);
+  background: var(--pink);
+  color: var(--danger-contrast);
+}
+.ui-timeline__event.is-entering {
+  --m-dist: var(--space-2);
+  animation: m-slide-up var(--dur-slow) var(--ease-out) both;
+}
+.ui-timeline__marker.is-entering {
+  animation: m-scale-in var(--dur-med) var(--ease-out) var(--delay-1) both;
+}
 
 /* ../src/styles/input.css */
 .ui-field {

package/react/dist/index.d.ts

@@ -498,11 +498,14 @@ type TabsProps = {
 };
 declare function Tabs({ items, value, onChange, label }: TabsProps): react.JSX.Element;
 
+type TimelineEventKind = 'person' | 'rule' | 'reversal';
 type TimelineEvent = {
     id: string;
+    kind?: TimelineEventKind;
     actor: string;
     dateTime: string;
     timestamp: string;
+    relativeTimestamp?: string;
     description: string;
     meta?: ReactNode;
     undo?: {
@@ -608,4 +611,4 @@ declare function ThemeToggle({ labelled }: ThemeToggleProps): react.JSX.Element;
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, RowIdentity, type RowIdentityProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineProps, Toast, type ToastNotice, type ToastProps, sortTableRows, useToast };
+export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, RowIdentity, type RowIdentityProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, sortTableRows, useToast };

package/react/dist/index.js

@@ -1890,23 +1890,57 @@ function Tabs({ items, value, onChange, label }) {
 }
 
 // src/Timeline.tsx
+import { useEffect as useEffect7, useRef as useRef12 } from "react";
+import { playEntrance as playEntrance2, prefersReducedMotion } from "@apliteni/apliteni-ui/motion";
 import { jsx as jsx22, jsxs as jsxs18 } from "react/jsx-runtime";
+var kindIcons = { person: "user", rule: "bolt", reversal: "refresh" };
 function Timeline({ events, className, ...rest }) {
-  return /* @__PURE__ */ jsx22("ol", { ...rest, role: "list", className: ["ui-timeline", className].filter(Boolean).join(" "), children: events.map((event) => /* @__PURE__ */ jsxs18("li", { className: "ui-timeline__event", children: [
-    /* @__PURE__ */ jsxs18("div", { className: "ui-timeline__head", children: [
-      /* @__PURE__ */ jsx22("span", { className: "ui-timeline__actor", children: event.actor }),
-      /* @__PURE__ */ jsx22("time", { dateTime: event.dateTime, children: event.timestamp })
-    ] }),
-    /* @__PURE__ */ jsx22("p", { className: "ui-timeline__description", children: event.description }),
-    (event.meta != null || event.undo) && /* @__PURE__ */ jsxs18("div", { className: "ui-timeline__meta", children: [
-      event.meta != null && /* @__PURE__ */ jsx22("span", { children: event.meta }),
-      event.undo && /* @__PURE__ */ jsx22(Button, { variant: "ghost", size: "xs", className: "ui-btn ui-btn--ghost ui-btn--xs ui-timeline__undo", "aria-label": event.undo.label, onClick: event.undo.onUndo, children: "Undo" })
-    ] })
-  ] }, event.id)) });
+  const previousIds = useRef12(new Set(events.map((event) => event.id)));
+  const rows = useRef12(/* @__PURE__ */ new Map());
+  useEffect7(() => {
+    if (previousIds.current.size > 0 && !prefersReducedMotion()) {
+      for (const event of events) {
+        if (previousIds.current.has(event.id)) continue;
+        const row = rows.current.get(event.id);
+        if (!row) continue;
+        playEntrance2(row);
+        playEntrance2(row.querySelector(".ui-timeline__marker"));
+      }
+    }
+    previousIds.current = new Set(events.map((event) => event.id));
+  }, [events]);
+  return /* @__PURE__ */ jsx22("ol", { ...rest, role: "list", className: ["ui-timeline", events.some((event) => event.kind) && "ui-timeline--kinds", className].filter(Boolean).join(" "), children: events.map((event, index) => /* @__PURE__ */ jsxs18(
+    "li",
+    {
+      className: "ui-timeline__event",
+      ref: (row) => {
+        if (row) rows.current.set(event.id, row);
+        else rows.current.delete(event.id);
+      },
+      children: [
+        /* @__PURE__ */ jsx22("span", { "aria-hidden": "true", className: [
+          "ui-timeline__marker",
+          event.kind && "ui-timeline__marker--kind",
+          event.kind === "reversal" && "ui-timeline__marker--reversal"
+        ].filter(Boolean).join(" "), children: event.kind && /* @__PURE__ */ jsx22(Icon, { name: kindIcons[event.kind] }) }),
+        /* @__PURE__ */ jsxs18("div", { className: "ui-timeline__head", children: [
+          /* @__PURE__ */ jsx22("span", { className: "ui-timeline__actor", children: event.actor }),
+          /* @__PURE__ */ jsx22("time", { dateTime: event.dateTime, children: event.timestamp }),
+          index === events.length - 1 && event.relativeTimestamp && /* @__PURE__ */ jsx22("span", { className: "ui-timeline__relative", children: event.relativeTimestamp })
+        ] }),
+        /* @__PURE__ */ jsx22("p", { className: "ui-timeline__description", children: event.description }),
+        (event.meta != null || event.undo) && /* @__PURE__ */ jsxs18("div", { className: "ui-timeline__meta", children: [
+          event.meta != null && /* @__PURE__ */ jsx22("span", { children: event.meta }),
+          event.undo && /* @__PURE__ */ jsx22(Button, { variant: "ghost", size: "xs", className: "ui-btn ui-btn--ghost ui-btn--xs ui-timeline__undo", "aria-label": event.undo.label, onClick: event.undo.onUndo, children: "Undo" })
+        ] })
+      ]
+    },
+    event.id
+  )) });
 }
 
 // src/Field.tsx
-import { useEffect as useEffect7, useId as useId8, useRef as useRef12, useState as useState7 } from "react";
+import { useEffect as useEffect8, useId as useId8, useRef as useRef13, useState as useState7 } from "react";
 import { esc, icon as icon4 } from "@apliteni/apliteni-ui";
 import { jsx as jsx23, jsxs as jsxs19 } from "react/jsx-runtime";
 function Frame({ id, label, hint, error, required, children }) {
@@ -1978,10 +2012,10 @@ function SelectField({ label, hint, error, required, className = "", children, .
 }
 function FileField({ label, hint, error, required, disabled, onFileChange, className = "", ...props }) {
   const id = useId8();
-  const input = useRef12(null);
+  const input = useRef13(null);
   const [file, setFile] = useState7(null);
   const [dragging, setDragging] = useState7(false);
-  useEffect7(() => {
+  useEffect8(() => {
     const form = input.current?.form;
     const reset = () => {
       setFile(null);
@@ -2040,7 +2074,7 @@ function FileField({ label, hint, error, required, disabled, onFileChange, class
 }
 
 // src/Toast.tsx
-import { createContext as createContext2, useCallback as useCallback3, useContext as useContext2, useEffect as useEffect8, useRef as useRef13, useState as useState8 } from "react";
+import { createContext as createContext2, useCallback as useCallback3, useContext as useContext2, useEffect as useEffect9, useRef as useRef14, useState as useState8 } from "react";
 import { createPortal as createPortal4 } from "react-dom";
 import { jsx as jsx24, jsxs as jsxs20 } from "react/jsx-runtime";
 var Context = createContext2(null);
@@ -2051,10 +2085,10 @@ function useToast() {
   return push;
 }
 function Notice({ notice, remove }) {
-  const root = useRef13(null);
+  const root = useRef14(null);
   const [leaving2, setLeaving] = useState8(false);
-  const dismissed = useRef13(false);
-  const remaining = useRef13(5e3);
+  const dismissed = useRef14(false);
+  const remaining = useRef14(5e3);
   const [hovered, setHovered] = useState8(false);
   const [focused, setFocused] = useState8(false);
   const paused = hovered || focused;
@@ -2065,7 +2099,7 @@ function Notice({ notice, remove }) {
     if (typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches) remove();
     else setLeaving(true);
   }, [remove]);
-  useEffect8(() => {
+  useEffect9(() => {
     if (leaving2) {
       const element = root.current;
       const finish = (event) => {
@@ -2079,7 +2113,7 @@ function Notice({ notice, remove }) {
       };
     }
   }, [leaving2, remove]);
-  useEffect8(() => {
+  useEffect9(() => {
     if (leaving2 || notice.action || paused) return;
     const started = Date.now();
     const timer = setTimeout(dismiss, remaining.current);
@@ -2137,7 +2171,7 @@ function Notice({ notice, remove }) {
 }
 function Toast({ children }) {
   const [entries, setEntries] = useState8([]);
-  const nextId = useRef13(0);
+  const nextId = useRef14(0);
   const push = useCallback3((notice) => {
     const id = nextId.current++;
     const remove = () => setEntries((current) => current.filter((entry) => entry.id !== id));
@@ -2153,7 +2187,7 @@ function Toast({ children }) {
 }
 
 // src/AppShell.tsx
-import { useEffect as useEffect9, useId as useId9, useState as useState9 } from "react";
+import { useEffect as useEffect10, useId as useId9, useState as useState9 } from "react";
 import { applyTheme, paletteHotkey, prism, railCollapsed, themeIcon, themeName } from "@apliteni/apliteni-ui";
 import { Fragment as Fragment7, jsx as jsx25, jsxs as jsxs21 } from "react/jsx-runtime";
 var path = (value) => value.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
@@ -2183,14 +2217,14 @@ function AppShell({
   const [theme, setTheme] = useState9("dark");
   const current = path(pathname);
   const active = sections.filter((section) => current === path(section.href) || path(section.href) !== "/" && current.startsWith(`${path(section.href)}/`)).sort((a, b) => path(b.href).length - path(a.href).length)[0];
-  useEffect9(() => {
+  useEffect10(() => {
     setCollapsed(railCollapsed() ?? defaultCollapsed);
   }, [defaultCollapsed]);
-  useEffect9(() => {
+  useEffect10(() => {
     setMore(false);
     setSearch(false);
   }, [pathname]);
-  useEffect9(() => {
+  useEffect10(() => {
     const root = document.documentElement;
     const sync2 = () => setTheme(root.getAttribute("data-theme") === "light" ? "light" : "dark");
     sync2();
@@ -2198,7 +2232,7 @@ function AppShell({
     observer.observe(root, { attributes: true, attributeFilter: ["data-theme"] });
     return () => observer.disconnect();
   }, []);
-  useEffect9(() => {
+  useEffect10(() => {
     const hotkey = (event) => {
       if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey || event.key.toLowerCase() !== "k") return;
       const target = event.target;