@iyulab/modern-app 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.37.0] - 2026-10-06
+
+### Added
+
+- **`u-timeline` and `u-timeline-item` — a status or activity history** for detail screens ("what
+  happened, and when"). Each entry is a marker on a rail, a `heading`, a `datetime` rendered as
+  `<time datetime>` and formatted for the active locale (a date alone as that calendar day, a
+  date-time with its time; the `time` slot replaces the text), and an optional body. `color` takes the
+  role colours of `u-tag`/`u-badge` — the marker is drawn with the role's fill, the colour on it and its
+  strong step as an edge, so a warning marker still shows on the page — and `icon` draws inside it. The
+  list is announced as a list. Parts: `rail` · `marker` · `line` · `content` · `header` · `heading` ·
+  `time` · `body`; knobs `--app-timeline-rail-width` and `--app-timeline-marker-size`.
+
 ## [0.36.0] - 2026-10-06
 
 ### Added

package/dist/components/MasterDetailLayout.js

@@ -6,8 +6,8 @@ import { slotHasContent as i } from "../internals/slotted.js";
 import { styles as a } from "./MasterDetailLayout.styles.js";
 import { html as o } from "lit";
 import { customElement as s, property as c, state as l } from "lit/decorators.js";
-import "@iyulab/components/dist/components/button/UButton.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
+import "@iyulab/components/dist/components/button/UButton.js";
 //#region src/components/MasterDetailLayout.ts
 var u = class extends n {
 	constructor(...e) {

package/dist/components/Timeline.d.ts

@@ -0,0 +1,63 @@
+import { StyledElement } from '../internals/StyledElement.js';
+type TimelineParts = 'host';
+type TimelineItemParts = 'host' | 'rail' | 'marker' | 'line' | 'content' | 'header' | 'heading' | 'time' | 'body';
+/** The role colours `u-tag`/`u-badge` use — the marker's colour. */
+export type TimelineItemColor = 'neutral' | 'primary' | 'info' | 'success' | 'warning' | 'danger';
+/**
+ * A status or activity history — "what happened, and when" on a detail screen (order, ticket,
+ * approval). An ordered list of {@link TimelineItem}s, each a marker on a rail, a heading, a time
+ * and an optional body.
+ *
+ * ```html
+ * <u-timeline>
+ *   <u-timeline-item heading="Paid" datetime="2026-10-06T09:30" color="success" icon="check">
+ *     Bank transfer received.
+ *   </u-timeline-item>
+ *   <u-timeline-item heading="Ordered" datetime="2026-10-05T14:02"></u-timeline-item>
+ * </u-timeline>
+ * ```
+ *
+ * The items are shown in DOM order — put the newest first or last as your screen reads. The host is
+ * a list and each item a list item, so assistive technology announces how many entries there are.
+ */
+export declare class Timeline extends StyledElement<TimelineParts> {
+    static styles: import('lit').CSSResultGroup[];
+    connectedCallback(): void;
+    render(): import('lit-html').TemplateResult<1>;
+}
+/**
+ * One entry of a {@link Timeline}.
+ *
+ * - `heading` names the event ("Shipped"); the `heading` slot takes richer content.
+ * - `datetime` is an ISO date or date-time. It is rendered as `<time datetime>` and formatted for the
+ *   active locale (`Locale`) — a date alone as a date, a date-time with its time. The `time` slot
+ *   replaces the text (a relative "2 hours ago", say); `datetime` still annotates it.
+ * - `color` tints the marker. ⚠Colour is never the only carrier — say the status in `heading` too
+ *   (WCAG 1.4.1). `icon` (and `lib`) draws inside the marker.
+ */
+export declare class TimelineItem extends StyledElement<TimelineItemParts> {
+    static styles: import('lit').CSSResultGroup[];
+    /** What happened. */
+    heading: string;
+    /** When — ISO `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm[:ss]`. */
+    datetime: string;
+    /** Marker colour. Default `neutral`. */
+    color: TimelineItemColor;
+    /** Icon drawn inside the marker. */
+    icon?: string;
+    /** Icon library for `icon`. */
+    lib?: string;
+    /** Body slot assignment — CSS `:has()` cannot see slotted content (`internals/slotted.ts`). */
+    private hasBody;
+    connectedCallback(): void;
+    /** Locale text for `datetime` — the raw value when it is not a date the formatter can read. */
+    private get timeText();
+    render(): import('lit-html').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-timeline': Timeline;
+        'u-timeline-item': TimelineItem;
+    }
+}
+export {};

package/dist/components/Timeline.js

@@ -0,0 +1,68 @@
+import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import { StyledElement as n } from "../internals/StyledElement.js";
+import { slotHasContent as r } from "../internals/slotted.js";
+import { itemStyles as i, styles as a } from "./Timeline.styles.js";
+import { html as o, nothing as s } from "lit";
+import { customElement as c, property as l, state as u } from "lit/decorators.js";
+import { formatDate as d } from "@iyulab/components/dist/utilities/format.js";
+import "@iyulab/components/dist/components/icon/UIcon.js";
+//#region src/components/Timeline.ts
+var f = class extends n {
+	static {
+		this.styles = [super.styles, a];
+	}
+	connectedCallback() {
+		super.connectedCallback(), this.hasAttribute("role") || this.setAttribute("role", "list");
+	}
+	render() {
+		return o`<slot></slot>`;
+	}
+};
+f = t([c("u-timeline")], f);
+var p = class extends n {
+	constructor(...e) {
+		super(...e), this.heading = "", this.datetime = "", this.color = "neutral", this.hasBody = !1;
+	}
+	static {
+		this.styles = [super.styles, i];
+	}
+	connectedCallback() {
+		super.connectedCallback(), this.hasAttribute("role") || this.setAttribute("role", "listitem");
+	}
+	get timeText() {
+		let e = this.datetime.trim();
+		if (!e) return "";
+		if (!e.includes("T")) return d(e, { dateStyle: "medium" });
+		let t = new Date(e);
+		return Number.isNaN(t.getTime()) ? e : d(t, {
+			dateStyle: "medium",
+			timeStyle: "short"
+		});
+	}
+	render() {
+		return o`
+      <div class="rail" part="rail" aria-hidden="true">
+        <span class="marker ${this.icon ? "with-icon" : ""}" part="marker">
+          ${this.icon ? o`<u-icon .lib=${this.lib} .name=${this.icon}></u-icon>` : s}
+        </span>
+        <span class="line" part="line"></span>
+      </div>
+      <div class="content" part="content">
+        <div class="header" part="header">
+          <span class="heading" part="heading"><slot name="heading">${this.heading}</slot></span>
+          ${this.datetime ? o`<time class="time" part="time" datetime=${this.datetime}><slot name="time">${this.timeText}</slot></time>` : o`<span class="time" part="time"><slot name="time"></slot></span>`}
+        </div>
+        <div class="body ${this.hasBody ? "" : "empty"}" part="body">
+          <slot @slotchange=${(e) => this.hasBody = r(e.target)}></slot>
+        </div>
+      </div>
+    `;
+	}
+};
+t([l({ type: String }), e("design:type", Object)], p.prototype, "heading", void 0), t([l({ type: String }), e("design:type", Object)], p.prototype, "datetime", void 0), t([l({
+	type: String,
+	reflect: !0
+}), e("design:type", Object)], p.prototype, "color", void 0), t([l({ type: String }), e("design:type", String)], p.prototype, "icon", void 0), t([l({ type: String }), e("design:type", String)], p.prototype, "lib", void 0), t([u(), e("design:type", Object)], p.prototype, "hasBody", void 0), p = t([c("u-timeline-item")], p);
+//#endregion
+export { f as Timeline, p as TimelineItem };

package/dist/components/Timeline.styles.d.ts

@@ -0,0 +1,2 @@
+export declare const styles: import('lit').CSSResult;
+export declare const itemStyles: import('lit').CSSResult;

package/dist/components/Timeline.styles.js

@@ -0,0 +1,125 @@
+import { css as e } from "lit";
+//#region src/components/Timeline.styles.ts
+var t = e`
+  :host {
+    display: block;
+  }
+`, n = e`
+  :host {
+    display: grid;
+    grid-template-columns: var(--app-timeline-rail-width, 24px) minmax(0, 1fr);
+    column-gap: var(--u-space-md, 12px);
+  }
+
+  /* The rail: a marker, then a line down to the next entry's marker. */
+  .rail {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+  }
+
+  .marker {
+    flex: none;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    width: var(--app-timeline-marker-size, 12px);
+    height: var(--app-timeline-marker-size, 12px);
+    /* Centred on the heading's first line (label size × leading). */
+    margin-top: calc((var(--u-text-label-size, 13px) * var(--u-text-label-leading, 1.5) - var(--app-timeline-marker-size, 12px)) / 2);
+    border-radius: 50%;
+    /* Fill and the colour on it come as a pair (the components contract — warning carries dark text,
+       not white). The edge is the strong step: a yellow fill alone is about 1.4:1 against the page. */
+    background-color: var(--_marker, var(--u-border-color-strong, #BDBDBD));
+    color: var(--_on-marker, var(--u-txt-color, #212121));
+    border: 1px solid var(--_edge, var(--u-border-color-strong, #BDBDBD));
+  }
+  .marker.with-icon {
+    width: var(--app-timeline-rail-width, 24px);
+    height: var(--app-timeline-rail-width, 24px);
+    margin-top: calc((var(--u-text-label-size, 13px) * var(--u-text-label-leading, 1.5) - var(--app-timeline-rail-width, 24px)) / 2);
+    font-size: var(--u-text-caption-size, 12px);
+  }
+
+  :host([color="primary"]) {
+    --_marker: var(--u-primary-color, #1976D2);
+    --_on-marker: var(--u-primary-txt-color, #FFFFFF);
+    --_edge: var(--u-primary-color-strong, #1565C0);
+  }
+  :host([color="info"]) {
+    --_marker: var(--u-info-color, #1976D2);
+    --_on-marker: var(--u-info-txt-color, #FFFFFF);
+    --_edge: var(--u-info-color-strong, #1565C0);
+  }
+  :host([color="success"]) {
+    --_marker: var(--u-success-color, #2E7D32);
+    --_on-marker: var(--u-success-txt-color, #FFFFFF);
+    --_edge: var(--u-success-color-strong, #1B5E20);
+  }
+  :host([color="warning"]) {
+    --_marker: var(--u-warning-color, #FDD835);
+    --_on-marker: var(--u-warning-txt-color, #000000);
+    --_edge: var(--u-warning-color-strong, #8A4A00);
+  }
+  :host([color="danger"]) {
+    --_marker: var(--u-danger-color, #D32F2F);
+    --_on-marker: var(--u-danger-txt-color, #FFFFFF);
+    --_edge: var(--u-danger-color-strong, #C62828);
+  }
+
+  .line {
+    flex: 1 1 auto;
+    min-height: var(--u-space-md, 12px);
+    margin-top: var(--u-space-2xs, 4px);
+    border-left: 1px solid var(--u-border-color, #E0E0E0);
+  }
+  /* The last entry has no next marker to reach. */
+  :host(:last-child) .line {
+    display: none;
+  }
+
+  .content {
+    min-width: 0;
+    padding-bottom: var(--u-space-lg, 16px);
+  }
+  :host(:last-child) .content {
+    padding-bottom: 0;
+  }
+
+  .header {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    column-gap: var(--u-space-sm, 8px);
+  }
+
+  .heading {
+    font-size: var(--u-text-label-size, 13px);
+    line-height: var(--u-text-label-leading, 1.5);
+    font-weight: var(--u-text-label-weight, 600);
+    color: var(--u-txt-color, #212121);
+    overflow-wrap: anywhere;
+  }
+
+  .time {
+    font-size: var(--u-text-caption-size, 12px);
+    color: var(--u-txt-color-weak, #616161);
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+  }
+
+  .body {
+    margin-top: var(--u-space-2xs, 4px);
+    font-size: var(--u-text-body-size, 14px);
+    line-height: var(--u-text-body-leading, 1.6);
+    color: var(--u-txt-color-weak, #616161);
+    overflow-wrap: anywhere;
+  }
+  /* No body content — no gap under the header. */
+  .body.empty {
+    display: none;
+  }
+`;
+//#endregion
+export { n as itemStyles, t as styles };

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export { GroupBox } from './components/GroupBox.js';
 export { InfoSection } from './components/InfoSection.js';
 export { InfoField, isBlank } from './components/InfoField.js';
 export { EmptyState } from './components/EmptyState.js';
+export { Timeline, TimelineItem } from './components/Timeline.js';
+export type { TimelineItemColor } from './components/Timeline.js';
 export { ActionBar } from './components/ActionBar.js';
 export { MasterDetailLayout } from './components/MasterDetailLayout.js';
 export type { MasterDetailLayoutEventMap } from './components/MasterDetailLayout.js';

package/dist/index.js

@@ -7,11 +7,12 @@ import { GroupBox as l } from "./components/GroupBox.js";
 import { InfoSection as u } from "./components/InfoSection.js";
 import { InfoField as d, isBlank as f } from "./components/InfoField.js";
 import { EmptyState as p } from "./components/EmptyState.js";
-import { ActionBar as m } from "./components/ActionBar.js";
-import { MasterDetailLayout as h } from "./components/MasterDetailLayout.js";
-import { Wizard as g } from "./components/Wizard.js";
-import { translate as _ } from "./translate.js";
+import { Timeline as m, TimelineItem as h } from "./components/Timeline.js";
+import { ActionBar as g } from "./components/ActionBar.js";
+import { MasterDetailLayout as _ } from "./components/MasterDetailLayout.js";
+import { Wizard as v } from "./components/Wizard.js";
+import { translate as y } from "./translate.js";
 //#region src/index.ts
-var v = t;
+var b = t;
 //#endregion
-export { m as ActionBar, p as EmptyState, l as GroupBox, d as InfoField, u as InfoSection, h as MasterDetailLayout, c as PageHeader, e as ScreenObserver, g as Wizard, t as app, v as default, n as filterSidebarItems, r as getDefaultLocale, i as getLocaleStrings, f as isBlank, a as modernAppLocale, o as registerLocale, s as setDefaultLocale, _ as translate };
+export { g as ActionBar, p as EmptyState, l as GroupBox, d as InfoField, u as InfoSection, _ as MasterDetailLayout, c as PageHeader, e as ScreenObserver, m as Timeline, h as TimelineItem, v as Wizard, t as app, b as default, n as filterSidebarItems, r as getDefaultLocale, i as getLocaleStrings, f as isBlank, a as modernAppLocale, o as registerLocale, s as setDefaultLocale, y as translate };

package/dist/layouts/SidebarLayout.js

@@ -13,8 +13,8 @@ import "../components/SidebarButton.js";
 import { styles as c } from "./SidebarLayout.styles.js";
 import { html as l, nothing as u } from "lit";
 import { customElement as d, property as f, query as p, state as m } from "lit/decorators.js";
-import "@iyulab/components/dist/components/button/UButton.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
+import "@iyulab/components/dist/components/button/UButton.js";
 import { unsafeHTML as h } from "lit/directives/unsafe-html.js";
 import { repeat as g } from "lit/directives/repeat.js";
 import "@iyulab/components/dist/components/popover/UPopover.js";

package/dist/react/Timeline.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import { Timeline as TimelineElement } from '@iyulab/modern-app/dist/components/Timeline.js';
+
+type TimelineOwnProps = Omit<TimelineElement, keyof HTMLElement>;
+
+export declare const Timeline: React.ForwardRefExoticComponent<
+  Partial<Omit<TimelineElement, Exclude<keyof React.HTMLAttributes<TimelineElement>, keyof TimelineOwnProps>>>
+    & Omit<React.HTMLAttributes<TimelineElement>, keyof TimelineOwnProps | never>
+    & React.RefAttributes<TimelineElement>
+    & {
+  }
+>;
+
+export type TimelineProps = React.ComponentProps<typeof Timeline>;

package/dist/react/Timeline.js

@@ -0,0 +1,10 @@
+import React from 'react';
+import { createComponent } from '@lit/react';
+import { Timeline as TimelineElement } from '@iyulab/modern-app/dist/components/Timeline.js';
+
+export const Timeline = createComponent({
+  react: React,
+  tagName: 'u-timeline',
+  elementClass: TimelineElement,
+  events: {},
+});

package/dist/react/index.d.ts

@@ -1,4 +1,5 @@
 export * from '@iyulab/modern-app/dist/react.js';
+export { Timeline, TimelineProps } from './Timeline';
 export { SidebarButton, SidebarButtonProps } from './SidebarButton';
 export { PageHeader, PageHeaderProps } from './PageHeader';
 export { MasterDetailLayout, MasterDetailLayoutProps } from './MasterDetailLayout';

package/dist/react/index.js

@@ -1,4 +1,5 @@
 export * from '@iyulab/modern-app/dist/react.js';
+export { Timeline } from './Timeline.js';
 export { SidebarButton } from './SidebarButton.js';
 export { PageHeader } from './PageHeader.js';
 export { MasterDetailLayout } from './MasterDetailLayout.js';

package/dist/react.d.ts

@@ -3,6 +3,7 @@ import { EventName } from '@lit/react';
 import { SidebarLayout as SidebarLayoutElement, SidebarLayoutEventMap } from './layouts/SidebarLayout.js';
 import { Wizard as WizardElement, WizardEventMap } from './components/Wizard.js';
 import { GroupBoxLevel } from './components/GroupBox.js';
+import { TimelineItemColor } from './components/Timeline.js';
 import { InfoFieldFormat, InfoFieldSize, InfoFieldTrend, InfoFieldTone } from './components/InfoField.js';
 export { ScreenObserver } from './internals/ScreenObserver.js';
 export type { ScreenSize, ScreenObserverConfig, ScreenResizeEvent } from './internals/ScreenObserver.js';
@@ -69,6 +70,14 @@ declare module 'react' {
             'u-info-section': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
                 min?: number | string;
             };
+            'u-timeline': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+            'u-timeline-item': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+                heading?: string;
+                datetime?: string;
+                color?: TimelineItemColor;
+                icon?: string;
+                lib?: string;
+            };
             'u-master-detail-layout': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
                 'master-size'?: string;
                 'overlay-breakpoint'?: number | string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "keywords": [
     "iyulab",
     "web-framework",

package/skills/modern-app/SKILL.md

@@ -261,6 +261,7 @@ re-assembled per screen — that is where a product stops looking like one produ
 - [`u-info-field`](./references/components/info-field.md) — Read-only label/value pair that keeps "not set" and "zero" distinct
 - [`u-empty-state`](./references/components/empty-state.md) — Empty list or empty search, worded differently because they are different facts
 - [`u-action-bar`](./references/components/action-bar.md) — Closing action row with a separated destructive group
+- [`u-timeline`](./references/components/timeline.md) — Status or activity history: what happened, and when
 
 ---
 

package/skills/modern-app/references/components/timeline.md

@@ -0,0 +1,57 @@
+# u-timeline
+
+**Tags:** `u-timeline` · `u-timeline-item`
+
+A status or activity history on a detail screen — "what happened, and when" (an order moving
+through its states, a ticket's activity, an approval chain). Each entry is a marker on a rail, a
+heading, a time and an optional body.
+
+```html
+<u-timeline>
+  <u-timeline-item heading="Paid" datetime="2026-10-06T09:30" color="success" icon="check">
+    Bank transfer received.
+  </u-timeline-item>
+  <u-timeline-item heading="Shipped" datetime="2026-10-06T15:10" color="primary"></u-timeline-item>
+  <u-timeline-item heading="Ordered" datetime="2026-10-05"></u-timeline-item>
+</u-timeline>
+```
+
+Entries are shown in DOM order — put the newest first or last, as your screen reads. `u-timeline` is
+a list and each entry a list item, so assistive technology announces the count.
+
+⚠ **Colour is never the only carrier.** Say the status in `heading` ("Rejected"), not only with
+`color="danger"` (WCAG 1.4.1). The marker is decorative to assistive technology.
+
+## `u-timeline-item` — Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Body — detail under the heading (who, a note, a link) |
+| `heading` | Replaces the `heading` text with richer content |
+| `time` | Replaces the formatted time text (e.g. a relative "2 hours ago"); `datetime` still annotates it |
+
+## `u-timeline-item` — Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `heading` | `string` | `''` | | What happened |
+| `datetime` | `string` | `''` | | ISO `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm[:ss]`. Rendered as `<time datetime>`, formatted for the active locale — a date alone as a date (never shifted by a time zone), a date-time with its time |
+| `color` | `'neutral'\|'primary'\|'info'\|'success'\|'warning'\|'danger'` | `'neutral'` | ✓ | Marker colour — the role colours of `u-tag`/`u-badge` |
+| `icon` | `string` | — | | Icon drawn inside the marker (the marker grows to hold it) |
+| `lib` | `string` | — | | Icon library for `icon` |
+
+## CSS Parts
+
+| Element | Parts |
+|---------|-------|
+| `u-timeline` | `host` |
+| `u-timeline-item` | `host` · `rail` · `marker` · `line` · `content` · `header` · `heading` · `time` · `body` |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--app-timeline-rail-width` | Rail column width; also the marker size when it holds an icon (default 24px) |
+| `--app-timeline-marker-size` | Plain marker size (default 12px) |
+| `--u-{role}-color` / `-txt-color` / `-color-strong` | Marker fill, the icon colour on it, and its edge |
+| `--u-text-label-*` · `--u-text-caption-*` · `--u-text-body-*` | Heading, time and body typography |