@iyulab/modern-app 0.35.1 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # 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
+
+- **`type: 'menu'` sidebar items — a button that opens a popup menu.** `{ type: 'menu', label, icon,
+  items: [{ label, icon, onClick, disabled }] }`. The shell draws the trigger and the menu together and
+  owns what only it knows: the menu opens beside the sidebar and downwards on the full-width mobile
+  panel; the trigger carries `aria-haspopup="menu"` and `aria-expanded`; opening moves focus into the
+  menu, and Escape or choosing an entry closes it and returns focus to the trigger. Entries take
+  `requirePermission`/`requireAnyPermission`, and a menu left with no entries is dropped.
+- The sidebar config types (`SidebarItem`, `SidebarLinkConfig`, `SidebarMenuConfig`, …, `SidebarState`)
+  are exported from the main entry too — they were only on `/react`, so a TypeScript app without React
+  could not name them.
+
+### Removed (breaking)
+
+- **`SidebarButtonConfig.id`.** It was meant for anchoring a `u-popover` you place outside the layout,
+  but the button renders inside the layout's shadow root, where `for="#id"` never reaches — it never
+  worked. Use `type: 'menu'` for a menu, or `type: 'html'` with the trigger and the popover in one
+  template for any other flyout.
+
 ## [0.35.1] - 2026-10-06
 
 ### Fixed

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/SidebarButton.d.ts

@@ -6,9 +6,6 @@ type ElementParts = 'host' | 'base' | 'icon' | 'label';
 /** 버튼 항목 구성 */
 export interface SidebarButtonConfig extends SidebarPermissionGuard {
     type: 'button';
-    /** 렌더된 `<u-sidebar-button>` 호스트에 그대로 전달된다 — `u-popover[for="#id"]` 같은
-     *  외부 앵커링에 쓴다. */
-    id?: string;
     icon?: string;
     /** `icon`을 어느 등록 라이브러리에서 찾을지. 미지정 시 `u-icon`의 기본 URL 경로로
      *  해석된다(`IconRegistry.register()`로 등록한 이름 있는 세트를 쓰려면 지정해야 함). */
@@ -30,6 +27,12 @@ export declare class SidebarButton extends StyledElement<ElementParts> {
     lib?: string;
     /** 버튼 텍스트 라벨 */
     label?: string | DirectiveResult;
+    /** 이 버튼이 여는 팝업의 종류 — 안쪽 `<button>` 의 `aria-haspopup` 으로 간다(셸의 `type: 'menu'` 트리거). */
+    haspopup?: 'menu';
+    /** 팝업이 열려 있는가 — `haspopup` 과 함께 `aria-expanded` 로 간다. 팝업이 없는 버튼에는 붙이지 않는다. */
+    expanded: boolean;
+    /** 포커스는 안쪽 `<button>` 으로 — 호스트는 포커스를 받지 않는다(팝업을 닫을 때 셸이 이것으로 되돌린다). */
+    focus(options?: FocusOptions): void;
     render(): import('lit-html').TemplateResult<1>;
 }
 export {};

package/dist/components/SidebarButton.js

@@ -6,17 +6,23 @@ import { styles as i } from "./SidebarButton.styles.js";
 import { html as a } from "lit";
 import { customElement as o, property as s } from "lit/decorators.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
+import { ifDefined as c } from "lit/directives/if-defined.js";
 //#region src/components/SidebarButton.ts
-var c = class extends n {
+var l = class extends n {
 	constructor(...e) {
-		super(...e), this.compact = !1;
+		super(...e), this.compact = !1, this.expanded = !1;
 	}
 	static {
 		this.styles = [super.styles, i];
 	}
+	focus(e) {
+		this.renderRoot.querySelector("button")?.focus(e);
+	}
 	render() {
 		return a`
-      <button part="base" ?compact=${this.compact}>
+      <button part="base" ?compact=${this.compact}
+        aria-haspopup=${c(this.haspopup)}
+        aria-expanded=${c(this.haspopup ? String(this.expanded) : void 0)}>
         <u-icon part="icon"
           .lib=${this.lib}
           .name=${this.icon}
@@ -32,6 +38,6 @@ var c = class extends n {
 t([s({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Object)], c.prototype, "compact", void 0), t([s({ type: String }), e("design:type", String)], c.prototype, "icon", void 0), t([s({ type: String }), e("design:type", String)], c.prototype, "lib", void 0), t([s({ type: String }), e("design:type", Object)], c.prototype, "label", void 0), c = t([o("u-sidebar-button")], c);
+}), e("design:type", Object)], l.prototype, "compact", void 0), t([s({ type: String }), e("design:type", String)], l.prototype, "icon", void 0), t([s({ type: String }), e("design:type", String)], l.prototype, "lib", void 0), t([s({ type: String }), e("design:type", Object)], l.prototype, "label", void 0), t([s({ type: String }), e("design:type", String)], l.prototype, "haspopup", void 0), t([s({ type: Boolean }), e("design:type", Object)], l.prototype, "expanded", void 0), l = t([o("u-sidebar-button")], l);
 //#endregion
-export { c as SidebarButton };
+export { l as SidebarButton };

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

@@ -3,7 +3,7 @@ export type * from './types/AppConfigs';
 export type * from './types/AppOptions';
 export type * from './types/AuthConfig';
 export type { SidebarPermissionGuard } from './layouts/SidebarPermission';
-export type { SidebarIconsConfig } from './layouts/SidebarLayout.types';
+export type { SidebarIconsConfig, SidebarLayoutConfig, SidebarItem, SidebarLogoConfig, SidebarLinkConfig, SidebarSectionConfig, SidebarGroupConfig, SidebarButtonConfig, SidebarMenuConfig, SidebarMenuItemConfig, SidebarHtmlConfig, SidebarState, } from './layouts/SidebarLayout.types';
 export type { SidebarLayoutEventMap } from './layouts/SidebarLayout.js';
 export { filterSidebarItems } from './layouts/filterSidebarItems.js';
 export { PageHeader } from './components/PageHeader.js';
@@ -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.d.ts

@@ -19,6 +19,11 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     progressBarEl: UProgressBar;
     /** overlay 슬롯 배정 상태 — CSS `:has()`로는 알 수 없다(`internals/slotted.ts` 참조). */
     private hasOverlay;
+    /** 열린 `type: 'menu'` 팝업의 트리거 id — 트리거의 `aria-expanded` 가 읽는다. */
+    private openMenu;
+    /** `type: 'menu'` 항목마다 고정된 트리거 id — 팝오버의 `for` 가 같은 섀도 루트 안에서 찾는다. */
+    private readonly menuIds;
+    private static menuSeq;
     /** notice 슬롯 배정 상태 — 비었으면 스택 자체가 자리를 차지하지 않는다. */
     private hasNotice;
     /**
@@ -57,6 +62,19 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     private readonly unsizedWarnKey;
     private warnIfUnsized;
     render(): typeof nothing | import('lit-html').TemplateResult<1>;
+    /**
+     * `type: 'menu'` — 트리거와 팝업을 **같은 섀도 루트** 에 함께 그린다(팝오버의 `for` 는 섀도 경계를 넘지 못한다 —
+     * 종전 `SidebarButtonConfig.id` 가 약속하고 지키지 못한 자리). 배치는 셸 상태가 정한다: 모바일 패널은 화면 폭을
+     * 거의 다 차지해 옆에 자리가 없으므로 아래로, 그 밖에는 사이드바 옆으로.
+     */
+    private renderMenu;
+    /** 항목을 고르면 그 동작을 부르고 닫는다 — 포커스는 닫힘 처리(`handleMenuHide`)가 트리거로 되돌린다. */
+    private handleMenuPick;
+    /**
+     * 닫힐 때 포커스가 팝업 안에 있었다면 트리거로 돌린다(APG 메뉴 버튼 — Escape · 항목 선택). 바깥을 눌러 닫힌
+     * 경우에는 포커스가 이미 그 바깥 자리로 갔으므로 건드리지 않는다.
+     */
+    private handleMenuHide;
     /** 사이드바 아이템 렌더링 */
     private renderItem;
     /** 현재 경로와 패턴 매칭 여부 확인 */

package/dist/layouts/SidebarLayout.js

@@ -13,24 +13,26 @@ 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 { ifDefined as _ } from "lit/directives/if-defined.js";
-import { createDevWarner as v } from "@iyulab/components/dist/utilities/devWarning.js";
-import { isFocusCandidate as y, querySelectorDeep as b } from "@iyulab/components/dist/utilities/elements.js";
-import { OverlayManager as x } from "@iyulab/components/dist/utilities/OverlayManager.js";
-import { UProgressBar as S } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
+import "@iyulab/components/dist/components/popover/UPopover.js";
+import "@iyulab/components/dist/components/menu/UMenu.js";
+import "@iyulab/components/dist/components/menu-item/UMenuItem.js";
+import { createDevWarner as _ } from "@iyulab/components/dist/utilities/devWarning.js";
+import { isFocusCandidate as v, querySelectorDeep as y } from "@iyulab/components/dist/utilities/elements.js";
+import { OverlayManager as b } from "@iyulab/components/dist/utilities/OverlayManager.js";
+import { UProgressBar as x } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
 //#region src/layouts/SidebarLayout.ts
-var C, w = v("@iyulab/modern-app"), T = 0;
-function E(e) {
+var S, C = _("@iyulab/modern-app"), w = 0;
+function T(e) {
 	let t = e.tagName;
 	if (t === "INPUT" || t === "TEXTAREA" || t === "SELECT" || e.isContentEditable) return !0;
 	let n = e.getAttribute("role");
 	return n === "textbox" || n === "searchbox" || n === "combobox" || n === "spinbutton";
 }
-var D = /* @__PURE__ */ new Set([
+var E = /* @__PURE__ */ new Set([
 	"button",
 	"link",
 	"checkbox",
@@ -43,27 +45,27 @@ var D = /* @__PURE__ */ new Set([
 	"tab",
 	"treeitem"
 ]);
-function O(e) {
+function D(e) {
 	let t = e.tagName;
-	return t === "BUTTON" || t === "SUMMARY" || t === "A" && e.hasAttribute("href") ? !0 : D.has(e.getAttribute("role") ?? "");
+	return t === "BUTTON" || t === "SUMMARY" || t === "A" && e.hasAttribute("href") ? !0 : E.has(e.getAttribute("role") ?? "");
 }
-function k(e) {
+function O(e) {
 	let t = getComputedStyle(e);
 	return (t.overflowY === "auto" || t.overflowY === "scroll") && e.scrollHeight > e.clientHeight;
 }
-function A(e, t) {
+function k(e, t) {
 	for (let n of e) if (n instanceof HTMLElement) {
-		if (k(n)) return n === t;
+		if (O(n)) return n === t;
 		if (n === t) break;
 	}
 	return !0;
 }
-function j() {
+function A() {
 	let e = document.activeElement;
 	for (; e?.shadowRoot?.activeElement;) e = e.shadowRoot.activeElement;
 	return e;
 }
-function M(e, t) {
+function j(e, t) {
 	let n = t;
 	for (; n;) {
 		if (n === e) return !0;
@@ -71,12 +73,12 @@ function M(e, t) {
 	}
 	return !1;
 }
-var N = class extends i {
+var M = class extends i {
 	static {
-		C = this;
+		S = this;
 	}
 	constructor(...t) {
-		super(...t), this.state = "default", this.counts = {}, this.locale = "", this.hasOverlay = !1, this.hasNotice = !1, this.overlayTrigger = null, this.internals = typeof this.attachInternals == "function" ? this.attachInternals() : void 0, this.context = null, this.unsizedWarnKey = `unsized:${++T}`, this.isMatchedLink = (e) => !this.context || !e ? !1 : (e = typeof e == "string" ? new URLPattern(e, window.location.origin) : e, e.test(this.context.path, window.location.origin)), this.handleToggleButtonClick = () => {
+		super(...t), this.state = "default", this.counts = {}, this.locale = "", this.hasOverlay = !1, this.openMenu = null, this.menuIds = /* @__PURE__ */ new WeakMap(), this.hasNotice = !1, this.overlayTrigger = null, this.internals = typeof this.attachInternals == "function" ? this.attachInternals() : void 0, this.context = null, this.unsizedWarnKey = `unsized:${++w}`, this.isMatchedLink = (e) => !this.context || !e ? !1 : (e = typeof e == "string" ? new URLPattern(e, window.location.origin) : e, e.test(this.context.path, window.location.origin)), this.handleToggleButtonClick = () => {
 			let t = this.screenSize ?? e.screen ?? "large";
 			t === "large" ? this.state = this.state === "default" ? "slim" : "default" : t === "medium" ? this.state = this.state === "slim" ? "modal" : "slim" : t === "small" ? this.state = this.state === "mobile" ? "mobile-open" : "mobile" : console.warn("Unknown screen size:", t);
 		}, this.handleBackdropClick = () => {
@@ -102,7 +104,7 @@ var N = class extends i {
 		}, this.handleOverlaySlotChange = (e) => {
 			let t = o(e.target);
 			if (t && !this.hasOverlay) {
-				let e = j();
+				let e = A();
 				this.overlayTrigger = e && e !== document.body ? e : null;
 			}
 			this.hasOverlay = t;
@@ -116,9 +118,9 @@ var N = class extends i {
 		}, this._handleMainKeydown = (e) => {
 			if (e.defaultPrevented) return;
 			let t = e.composedPath()[0];
-			if (t instanceof HTMLElement && E(t) || e.key === " " && t instanceof HTMLElement && O(t)) return;
+			if (t instanceof HTMLElement && T(t) || e.key === " " && t instanceof HTMLElement && D(t)) return;
 			let n = this.shadowRoot?.querySelector(".main");
-			if (!n || !A(e.composedPath(), n)) return;
+			if (!n || !k(e.composedPath(), n)) return;
 			let r = n.clientHeight;
 			switch (e.key) {
 				case " ":
@@ -151,6 +153,9 @@ var N = class extends i {
 	static {
 		this.styles = [super.styles, c];
 	}
+	static {
+		this.menuSeq = 0;
+	}
 	get mainElement() {
 		return this.shadowRoot?.querySelector(".main") ?? null;
 	}
@@ -158,13 +163,13 @@ var N = class extends i {
 		super.connectedCallback(), window.addEventListener("route-begin", this.handleRouteBegin), window.addEventListener("route-done", this.handleRouteDone), window.addEventListener("route-progress", this.handleRouteProgress), window.addEventListener("route-error", this.handleRouteError), window.addEventListener("screen-resize", this.handleScreenResize);
 	}
 	disconnectedCallback() {
-		window.removeEventListener("route-begin", this.handleRouteBegin), window.removeEventListener("route-done", this.handleRouteDone), window.removeEventListener("route-progress", this.handleRouteProgress), window.removeEventListener("route-error", this.handleRouteError), window.removeEventListener("screen-resize", this.handleScreenResize), x.closeLayer(this), super.disconnectedCallback();
+		window.removeEventListener("route-begin", this.handleRouteBegin), window.removeEventListener("route-done", this.handleRouteDone), window.removeEventListener("route-progress", this.handleRouteProgress), window.removeEventListener("route-error", this.handleRouteError), window.removeEventListener("screen-resize", this.handleScreenResize), b.closeLayer(this), super.disconnectedCallback();
 	}
 	willUpdate(e) {
 		super.willUpdate(e), e.has("config") && (this.styles = this.config?.styles);
 	}
 	updated(e) {
-		super.updated(e), e.has("hasOverlay") && (this.internals?.states?.[this.hasOverlay ? "add" : "delete"]("overlay"), this.hasOverlay ? (x.openLayer(this, this.handleOverlayEscape), this.focusOverlay()) : e.get("hasOverlay") === !0 && (x.closeLayer(this), this.restoreOverlayFocus()));
+		super.updated(e), e.has("hasOverlay") && (this.internals?.states?.[this.hasOverlay ? "add" : "delete"]("overlay"), this.hasOverlay ? (b.openLayer(this, this.handleOverlayEscape), this.focusOverlay()) : e.get("hasOverlay") === !0 && (b.closeLayer(this), this.restoreOverlayFocus()));
 	}
 	firstUpdated(e) {
 		super.firstUpdated(e), this.warnIfUnsized();
@@ -173,7 +178,7 @@ var N = class extends i {
 		process.env.NODE_ENV !== "production" && requestAnimationFrame(() => {
 			if (!this.isConnected) return;
 			let e = this.getBoundingClientRect().height;
-			e >= 200 || w(this.unsizedWarnKey, `u-sidebar-layout is only ${Math.round(e)}px tall — its height: 100% found no sized ancestor, so the shell sits at its own chrome height and the route area has almost no room. Give the root element a height (e.g. #app { height: 100vh } — app.load() does this for document.body).`);
+			e >= 200 || C(this.unsizedWarnKey, `u-sidebar-layout is only ${Math.round(e)}px tall — its height: 100% found no sized ancestor, so the shell sits at its own chrome height and the route area has almost no room. Give the root element a height (e.g. #app { height: 100vh } — app.load() does this for document.body).`);
 		});
 	}
 	render() {
@@ -260,6 +265,46 @@ var N = class extends i {
       ></div>
     ` : u;
 	}
+	renderMenu(e) {
+		let t = this.menuIds.get(e);
+		t || (t = `u-sidebar-menu-${++S.menuSeq}`, this.menuIds.set(e, t));
+		let n = t, r = this.state === "mobile" || this.state === "mobile-open" ? "bottom-start" : "right-start";
+		return l`
+      <u-sidebar-button
+        id=${n}
+        haspopup="menu"
+        .expanded=${this.openMenu === n}
+        ?compact=${this.state === "slim"}
+        .icon="${e.icon}"
+        .lib="${e.lib}"
+        .label="${e.label}"
+      ></u-sidebar-button>
+      <u-popover for="#${n}" placement=${r} autofocus
+        @show=${() => {
+			this.openMenu = n;
+		}}
+        @hide=${(e) => this.handleMenuHide(e, n)}
+        @pick=${(t) => this.handleMenuPick(t, e)}>
+        <u-menu>
+          ${g(e.items, (e, t) => t, (e, t) => l`
+            <u-menu-item value=${String(t)} ?disabled=${e.disabled === !0}>
+              ${e.icon ? l`<u-icon slot="prefix" .lib=${e.lib} .name=${e.icon}></u-icon>` : u}
+              ${e.label}
+            </u-menu-item>
+          `)}
+        </u-menu>
+      </u-popover>
+    `;
+	}
+	handleMenuPick(e, t) {
+		let n = t.items[Number(e.detail.value)];
+		n && !n.disabled && (e.currentTarget.hide(), n.onClick?.(e));
+	}
+	handleMenuHide(e, t) {
+		this.openMenu === t && (this.openMenu = null);
+		let n = e.currentTarget, r = A();
+		r && j(n, r) && this.shadowRoot?.querySelector(`#${t}`)?.focus();
+	}
 	renderItem(e) {
 		if (!e) return u;
 		if (e.type === "html") {
@@ -268,7 +313,6 @@ var N = class extends i {
 		}
 		if (e.type === "button") return l`
         <u-sidebar-button
-          id=${_(e.id)}
           ?compact=${this.state === "slim"}
           .icon="${e.icon}"
           .lib="${e.lib}"
@@ -277,6 +321,7 @@ var N = class extends i {
           @click="${e.onClick}"
         ></u-sidebar-button>
       `;
+		if (e.type === "menu") return this.renderMenu(e);
 		if (e.type === "link") {
 			let t = this.isMatchedLink(e.pattern || e.href);
 			return l`
@@ -331,7 +376,7 @@ var N = class extends i {
 		};
 	}
 	icon(e) {
-		return this.config?.icons?.[e] ?? C.DEFAULT_ICONS[e];
+		return this.config?.icons?.[e] ?? S.DEFAULT_ICONS[e];
 	}
 	renderLogo() {
 		let e = this.config?.logo, t = this.config?.title ?? "Home";
@@ -368,14 +413,14 @@ var N = class extends i {
 	async focusRoute(e) {
 		let t = this.routeContent();
 		if (await Promise.all(t.map((e) => e.updateComplete)), this.hasOverlay || !e.isConnected) return;
-		let n = j();
-		n && t.some((e) => M(e, n)) || this.focusContentStart(t, e);
+		let n = A();
+		n && t.some((e) => j(e, n)) || this.focusContentStart(t, e);
 	}
 	focusContentStart(e, t) {
-		let n = b(e, "[autofocus]", y);
+		let n = y(e, "[autofocus]", v);
 		n?.focus();
-		let r = j();
-		n && r && M(n, r) || t.focus({ preventScroll: !0 });
+		let r = A();
+		n && r && j(n, r) || t.focus({ preventScroll: !0 });
 	}
 	overlayPanels() {
 		return (this.shadowRoot?.querySelector("slot[name=\"overlay\"]"))?.assignedElements({ flatten: !0 }) ?? [];
@@ -383,19 +428,19 @@ var N = class extends i {
 	async focusOverlay() {
 		let e = this.overlayPanels();
 		if (await Promise.all(e.map((e) => e.updateComplete)), !this.hasOverlay) return;
-		let t = j();
-		t && e.some((e) => M(e, t)) || (b(e, "[autofocus]", y) ?? b(e, "input, select, textarea, u-input, u-textarea, u-select, u-checkbox, u-radio, u-switch, u-slider", y) ?? this.shadowRoot?.querySelector(".overlay-close"))?.focus();
+		let t = A();
+		t && e.some((e) => j(e, t)) || (y(e, "[autofocus]", v) ?? y(e, "input, select, textarea, u-input, u-textarea, u-select, u-checkbox, u-radio, u-switch, u-slider", v) ?? this.shadowRoot?.querySelector(".overlay-close"))?.focus();
 	}
 	restoreOverlayFocus() {
 		let e = this.overlayTrigger;
 		this.overlayTrigger = null;
-		let t = j();
+		let t = A();
 		t && t !== document.body || (e?.isConnected ? e.focus() : this.mainElement?.focus({ preventScroll: !0 }));
 	}
 };
 r([f({
 	type: String,
 	reflect: !0
-}), n("design:type", Object)], N.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], N.prototype, "config", void 0), r([f({ type: Object }), n("design:type", typeof Record > "u" ? Object : Record)], N.prototype, "counts", void 0), r([f({ type: String }), n("design:type", Object)], N.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", S === void 0 ? Object : S)], N.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], N.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], N.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], N.prototype, "context", void 0), N = C = r([d("u-sidebar-layout")], N);
+}), n("design:type", Object)], M.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], M.prototype, "config", void 0), r([f({ type: Object }), n("design:type", typeof Record > "u" ? Object : Record)], M.prototype, "counts", void 0), r([f({ type: String }), n("design:type", Object)], M.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", x === void 0 ? Object : x)], M.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], M.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], M.prototype, "openMenu", void 0), r([m(), n("design:type", Object)], M.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], M.prototype, "context", void 0), M = S = r([d("u-sidebar-layout")], M);
 //#endregion
-export { N as SidebarLayout };
+export { M as SidebarLayout };

package/dist/layouts/SidebarLayout.types.d.ts

@@ -1,4 +1,5 @@
 import { TemplateResult } from 'lit';
+import { DirectiveResult } from 'lit/directive.js';
 import { RouteContext } from '@iyulab/router';
 import { StyleMap } from '../internals/StyledElement';
 import { SidebarLinkConfig } from '../components/SidebarLink';
@@ -58,8 +59,33 @@ export interface SidebarLogoImage {
 export type SidebarLogoRenderer = (state: SidebarState) => TemplateResult<1> | HTMLElement | string;
 /** 최상단 앱 로고 설정: 아이콘명(문자열, 기존 동작) | 이미지 | 커스텀 렌더 함수 */
 export type SidebarLogoConfig = string | SidebarLogoImage | SidebarLogoRenderer;
-/** union: section | group | link | button */
-export type SidebarItem = (SidebarLinkConfig | SidebarSectionConfig | SidebarGroupConfig | SidebarButtonConfig | SidebarHtmlConfig);
+/** One entry of a `type: 'menu'` popup. */
+export interface SidebarMenuItemConfig extends SidebarPermissionGuard {
+    label: string | DirectiveResult;
+    icon?: string;
+    /** Icon library for `icon` (see `SidebarButtonConfig.lib`). */
+    lib?: string;
+    disabled?: boolean;
+    /** Runs when the entry is chosen (click, Enter or Space). The menu closes and focus returns to its trigger. */
+    onClick?: (event?: Event) => void;
+}
+/**
+ * A sidebar button that opens a popup menu — the flyout counterpart of `type: 'group'` (which expands in
+ * place). The shell draws the trigger and the menu together and owns what only it knows: the menu opens
+ * sideways beside the sidebar and downwards when the sidebar is the full-width mobile panel. It sets
+ * `aria-haspopup`/`aria-expanded` on the trigger, moves focus into the menu when it opens, and returns
+ * focus to the trigger on Escape or after an entry is chosen.
+ */
+export interface SidebarMenuConfig extends SidebarPermissionGuard {
+    type: 'menu';
+    /** The trigger's label — also its accessible name when the sidebar is slim. */
+    label: string | DirectiveResult;
+    icon?: string;
+    lib?: string;
+    items: SidebarMenuItemConfig[];
+}
+/** union: section | group | link | button | menu | html */
+export type SidebarItem = (SidebarLinkConfig | SidebarSectionConfig | SidebarGroupConfig | SidebarButtonConfig | SidebarMenuConfig | SidebarHtmlConfig);
 /** 사이드바 레이아웃 전체 설정 */
 export interface SidebarLayoutConfig {
     type: 'sidebar';

package/dist/layouts/filterSidebarItems.d.ts

@@ -4,6 +4,7 @@ import { SidebarItem } from './SidebarLayout.types';
  *
  * - 각 항목의 `requirePermission`/`requireAnyPermission` 를 `hasPermission` 으로 검사해 탈락 항목 제거.
  * - `section`/`group` 은 자식(`items`)을 재귀 필터하고, **자식이 모두 걸러지면 컨테이너째 제거**한다.
+ * - `menu` 는 팝업 항목(`items`)을 같은 가드로 거르고, 남는 항목이 없으면 트리거째 제거한다.
  * - `hasPermission` 이 없으면(undefined) 원본을 그대로 반환한다(필터링 없음).
  *
  * 원본 배열/항목을 변형하지 않고 새 배열/얕은 복제본을 반환한다(순수).

package/dist/layouts/filterSidebarItems.js

@@ -13,6 +13,13 @@ function t(n, r) {
 				...r,
 				items: e
 			});
+		} else if (r.type === "menu") {
+			let t = r.items.filter((t) => e(t, i));
+			if (t.length === 0) continue;
+			a.push({
+				...r,
+				items: t
+			});
 		} else a.push(r);
 	}
 	return a;

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';
@@ -27,7 +28,7 @@ export declare const Wizard: import('@lit/react').ReactWebComponent<WizardElemen
 }>;
 export type WizardProps = React.ComponentProps<typeof Wizard>;
 export type { SidebarLayoutElement, WizardElement };
-export type { SidebarLayoutConfig, SidebarItem, SidebarLogoConfig, SidebarLinkConfig, SidebarSectionConfig, SidebarGroupConfig, SidebarButtonConfig, SidebarHtmlConfig, } from './layouts/SidebarLayout.types.js';
+export type { SidebarLayoutConfig, SidebarItem, SidebarLogoConfig, SidebarLinkConfig, SidebarSectionConfig, SidebarGroupConfig, SidebarButtonConfig, SidebarMenuConfig, SidebarMenuItemConfig, SidebarHtmlConfig, } from './layouts/SidebarLayout.types.js';
 export type { WizardStep, WizardStepState, WizardStepChangeDetail } from './components/Wizard.js';
 declare module 'react' {
     namespace JSX {
@@ -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.35.1",
+  "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 |

package/skills/modern-app/references/layout.md

@@ -176,7 +176,6 @@ Action button — triggers a callback instead of navigating.
 ```typescript
 interface SidebarButtonConfig {
   type: 'button';
-  id?: string;
   icon?: string;
   lib?: string;
   label: string | DirectiveResult;
@@ -191,11 +190,54 @@ Example:
 { type: 'button', icon: 'logout', label: 'Sign Out', onClick: () => auth.signOut() }
 ```
 
-`id` is passed straight through to the rendered `<u-sidebar-button>` host. **It does not enable
-anchoring a `u-popover` you place outside the layout** — the button lives inside
-`<u-sidebar-layout>`'s own shadow root, and `querySelector`/`for="#id"` never crosses a shadow
-boundary. If you need a popover anchored to a sidebar item, use `type: 'html'` and assemble both
-inside the same template — see [popup-style submenus](#popup-style-submenus-u-popover) below.
+For a button that opens a menu, use `type: 'menu'` below — not a button plus your own popover.
+
+---
+
+### `SidebarMenuConfig` — `type: 'menu'`
+
+A sidebar button that opens a popup menu — the flyout counterpart of `type: 'group'` (which expands
+in place).
+
+```typescript
+interface SidebarMenuConfig {
+  type: 'menu';
+  label: string | DirectiveResult;   // the trigger's label (its accessible name when slim)
+  icon?: string;
+  lib?: string;
+  items: SidebarMenuItemConfig[];
+}
+
+interface SidebarMenuItemConfig {
+  label: string | DirectiveResult;
+  icon?: string;
+  lib?: string;
+  disabled?: boolean;
+  onClick?: (event?: Event) => void;   // runs when chosen; the menu closes
+}
+```
+
+Example:
+
+```typescript
+{
+  type: 'menu', icon: 'three-dots', label: 'More',
+  items: [
+    { icon: 'download', label: 'Export', onClick: () => exportAll() },
+    { icon: 'gear', label: 'Settings', onClick: () => app.navigate('/settings') },
+  ],
+}
+```
+
+The shell owns what only it knows:
+
+- **Placement** — beside the sidebar, and downwards when the sidebar is the full-width mobile panel
+  (`mobile`/`mobile-open`), where there is no room beside it.
+- **Keyboard and focus** — the trigger carries `aria-haspopup="menu"` and `aria-expanded`; opening
+  moves focus to the first entry; Escape or choosing an entry closes the menu and returns focus to
+  the trigger.
+- **Permissions** — each entry takes `requirePermission`/`requireAnyPermission`; with
+  `hasPermission` set, a menu left with no entries is dropped.
 
 ---
 
@@ -229,41 +271,24 @@ Example:
 
 ---
 
-### Popup-style submenus (`u-popover`)
+### A custom flyout (`type: 'html'`)
 
-For a submenu that flies out from a sidebar item (rather than expanding in place like
-`SidebarGroupConfig`), assemble a `u-popover` and its trigger together inside a single
-`type: 'html'` item — both then live in the sidebar layout's own shadow root, which is required
-for `for="#id"` anchoring to resolve (see the `id` note above).
+`type: 'menu'` covers a list of actions. For anything else that flies out of the sidebar (a form, a
+card), assemble the trigger and a `u-popover` inside one `type: 'html'` item — both must live in the
+sidebar's shadow root, because `for="#id"` never crosses a shadow boundary.
 
 ```typescript
 {
   type: 'html',
-  render: (state) => html`
-    <u-sidebar-button id="more-trigger" icon="three-dots" label="More"></u-sidebar-button>
-    <u-popover for="#more-trigger" placement=${state.startsWith('mobile') ? 'bottom-start' : 'right-start'}>
-      <u-menu>
-        <u-menu-item @click=${doA}>Action A</u-menu-item>
-        <u-menu-item @click=${doB}>Action B</u-menu-item>
-      </u-menu>
-    </u-popover>
+  render: () => html`
+    <u-sidebar-button id="quick-note" icon="pencil" label="Note"></u-sidebar-button>
+    <u-popover for="#quick-note" placement="right-start">…</u-popover>
   `,
 }
 ```
 
-**A fixed `placement` is safe as of `@iyulab/components@1.37.1`.** On `mobile`/`mobile-open`
-the sidebar widens to occupy nearly the full screen, so a sideways placement (`right-start`,
-the natural desktop flyout) has room on neither side. `flip()` now falls back **across the**
-**axis** in exactly that case, landing the popover vertically instead of off-screen.
-
-⚠ Against an older `components` it did render off-screen and invisible — `flip()` only ever
-considered the opposite side on the same axis, found no room there either, and gave up. If you
-pin below `1.37.1`, keep choosing `placement` from `state` as the snippet above does.
-
-Choosing from `state` is still reasonable when you want to *decide* the direction rather than
-let `flip()` pick it. Either way this is not a `strategy="absolute"` vs `"fixed"` distinction —
-switching strategy changes nothing. Both behaviours are pinned in
-`tests/browser/sidebar-popover-submenu.browser.test.ts`.
+A fixed sideways `placement` stays on screen on the mobile panel as of `@iyulab/components@1.37.1`
+(`flip()` falls back across the axis); `tests/browser/sidebar-popover-submenu.browser.test.ts` pins it.
 
 ---