@iyulab/modern-app 0.33.3 → 0.34.1

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## [0.34.1] - 2026-10-05
+
+### Fixed
+
+- **The sidebar footer was cut off when the menu was longer than the screen** and the shell's parent
+  had no height of its own (a custom `root`, or `SidebarLayout` mounted from React). The shell is
+  capped at the viewport, but the sidebar took `height: 100%`, which cannot resolve against a cap, so
+  it grew to the menu's length and the shell clipped the footer out of reach. The sidebar now takes
+  the shell's height, the menu scrolls inside `part="sidebar-main"`, and the footer stays at the
+  bottom — in the default, slim, drawer and mobile states.
+
+### Documentation
+
+- The layout guide now says that a custom `root` also keeps the browser's default body margin, and
+  shows `:where(body) { margin: 0; }` next to the height rule.
+
+## [0.34.0] - 2026-10-05
+
+### Added
+
+- **Press targets follow `--u-target-size`** (`@iyulab/components` 2.0). When it is set, sidebar links,
+  buttons and group headers, the page header's back link, the shell logo and wizard steps are at least
+  that size (the logo image and the back link keep their visible size and layout). Unset, nothing changes.
+- **`routerMode` in `app.load()`** — `'hash'` puts the route after `#` (`/app/#/orders/7`), so refreshes and
+  deep links work on a static host with no server fallback. Forwarded to `@iyulab/router`'s `mode`
+  (router 0.18.0); the default stays `'history'`.
+- **`eyebrow` on `u-page-header`** — a small line above the title for the menu group or the parent
+  path, on the overline step. A `slot="eyebrow"` replaces the text when it needs links (a breadcrumb).
+  The row takes no space when neither is given (`part="eyebrow"`).
+- **`description` on `u-group-box`** — one line under the title saying what the box holds or what
+  its numbers are based on, at caption size in the weak text color (`part="description"`). A
+  description alone opens the header, like `title`.
+- **`--app-sidebar-active-icon-color` and `--app-sidebar-active-indicator-color`** (with
+  `--app-sidebar-active-indicator-width`, default `3px`) — a shell with a light active background
+  can color only the active icon and draw a bar on the start edge of the active menu, instead of
+  filling the whole item. Defaults keep today's look: the icon follows `--app-sidebar-active-fg` and
+  the bar matches the active background.
+- **`count` on sidebar links, and `app.setNavCount(href, value)`** — a link can show the work waiting
+  behind it at the end of the item (`part="count"`, tabular figures). Set it in the item config or
+  change it while the app runs; `undefined` clears it. In the compact sidebar it stays in the
+  accessible name and is hidden visually.
+- **Shell size tokens** — `--app-main-padding` (32px), `--app-sidebar-item-radius` (8px),
+  `--app-sidebar-item-gap` (12px), `--app-sidebar-item-padding` (8px 12px),
+  `--app-sidebar-icon-size` (20px), `--app-sidebar-active-shadow` and
+  `--app-sidebar-active-shadow-hover`. A theme can now set a denser navigation or a flat current item
+  without reaching into the shadow DOM. Defaults keep today's look.
+
+### Changed
+
+- 🔴**Requires `@iyulab/components` 2.0.** Internal buttons (the shell's sidebar toggler and
+  overlay close, the master-detail close, the wizard's back button) use the 2.0 `appearance` vocabulary
+  (`appearance="plain"`, was `variant="ghost"`); with a 1.x components they render as solid buttons.
+- **The routed page sits on `--u-canvas-bg-color`** (new in `@iyulab/components` 2.0 — the
+  application background), not on `--u-bg-color`, which is the surface components paint their own
+  face with. With the built-in defaults the page is a near-white `#FAFAFA`; cards and tables on it
+  keep their white surface.
+- **`u-group-box` is a card like `u-card`**: `--u-panel-bg-color` face, `--u-border-color` line,
+  `--u-radius-xl` corners (was the chrome tint `--u-bg-color-raised`, a weak line and `2xl`). The page
+  now sits on the canvas, so a card no longer needs a tint to stand apart from it.
+- **Sidebar section title and subtitle read role tokens** (`--u-txt-color-weak` · `--u-txt-color-weaker`)
+  instead of the neutral palette, so a theme reaches them. Same values with the built-in defaults.
+- **`u-page-header`'s `subtitle` reads at body size** (was caption). It is the screen's one-line
+  description; at caption size it read as a footnote under a 26px title. Color stays
+  `--u-txt-color-weak`.
+
 ## [0.33.3] - 2026-10-05
 
 ### Fixed

package/dist/App.d.ts

@@ -35,6 +35,17 @@ declare class App {
     unload(): void;
     /** 페이지 이동 */
     navigate(path: string): void;
+    /**
+     * Sets the count shown on a sidebar link — the work waiting behind it — without rebuilding the
+     * layout. `href` is the link's `href` as configured; `undefined` clears it (and falls back to the
+     * item's static `count`, if any).
+     *
+     * ```ts
+     * app.setNavCount('/reviews', 12);
+     * app.setNavCount('/reviews', undefined);
+     * ```
+     */
+    setNavCount(href: string, value: number | string | undefined): void;
     /** 공지 메시지 */
     notice(message: string, options?: NotificationOptions): Promise<void>;
     /** 정보 메시지 */

package/dist/App.js

@@ -68,6 +68,7 @@ var l = class o {
 		this._layout.appendChild(s), this._router = new n({
 			root: this._layout,
 			basepath: a.basepath,
+			mode: a.routerMode,
 			routes: a.routes,
 			fallback: a.fallback,
 			enter: a.enter,
@@ -81,6 +82,12 @@ var l = class o {
 	navigate(e) {
 		this._router?.go(e);
 	}
+	setNavCount(e, t) {
+		let n = this._layout;
+		if (!n || !("counts" in n)) return;
+		let r = { ...n.counts };
+		t === void 0 ? delete r[e] : r[e] = t, n.counts = r;
+	}
 	async notice(e, t) {
 		await a.notice(e, { ...t });
 	}

package/dist/components/ActionBar.d.ts

@@ -11,8 +11,8 @@ type ElementParts = 'host' | 'danger' | 'main';
  *
  * ```html
  * <u-action-bar sticky>
- *   <u-button slot="danger" color="danger" variant="ghost">삭제</u-button>
- *   <u-button variant="ghost">취소</u-button>
+ *   <u-button slot="danger" color="danger" appearance="plain">삭제</u-button>
+ *   <u-button appearance="plain">취소</u-button>
  *   <u-button color="primary">저장</u-button>
  * </u-action-bar>
  * ```

package/dist/components/GroupBox.d.ts

@@ -1,6 +1,6 @@
 import { StyledElement } from '../internals/StyledElement.js';
 import { default as React } from 'react';
-type ElementParts = 'host' | 'header' | 'title' | 'meta' | 'actions' | 'body';
+type ElementParts = 'host' | 'header' | 'title' | 'meta' | 'description' | 'actions' | 'body';
 /** 제목 단계 — 페이지 제목(h1)은 `u-page-header` 몫이라 2 부터다. */
 export type GroupBoxLevel = 2 | 3 | 4 | 5 | 6;
 /**
@@ -18,7 +18,7 @@ export type GroupBoxLevel = 2 | 3 | 4 | 5 | 6;
  * </u-group-box>
  * ```
  *
- * 오버라이드: `part`(host·header·title·meta·actions·body) + slot 치환.
+ * 오버라이드: `part`(host·header·title·meta·description·actions·body) + slot 치환.
  * `divider` 속성으로 제목과 본문 사이 구분선을 켠다(기본 꺼짐 — 선이 많으면 화면이 시끄럽다).
  */
 export declare class GroupBox extends StyledElement<ElementParts> {
@@ -33,6 +33,12 @@ export declare class GroupBox extends StyledElement<ElementParts> {
      * without a `title`: it describes the title.
      */
     meta?: string;
+    /**
+     * One line under the title saying what the box holds or what its numbers are based on
+     * (`Prices are per unit, VAT excluded`). Caption size, weak color — it explains the title
+     * without competing with it. Opens the header on its own, like `title`.
+     */
+    description?: string;
     /** 제목과 본문 사이에 구분선을 넣는다. */
     divider: boolean;
     /** 본문 여백을 없앤다 — 표를 카드 가장자리까지 붙일 때. */
@@ -69,6 +75,7 @@ declare module 'react' {
                 flush?: boolean;
                 level?: GroupBoxLevel;
                 meta?: string;
+                description?: string;
             };
         }
     }

package/dist/components/GroupBox.js

@@ -3,17 +3,17 @@ 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 { styles as i } from "./GroupBox.styles.js";
-import { html as a } from "lit";
-import { customElement as o, property as s, state as c } from "lit/decorators.js";
-import { html as l, literal as u } from "lit/static-html.js";
+import { html as a, nothing as o } from "lit";
+import { customElement as s, property as c, state as l } from "lit/decorators.js";
+import { html as u, literal as d } from "lit/static-html.js";
 //#region src/components/GroupBox.ts
-var d = {
-	2: u`h2`,
-	3: u`h3`,
-	4: u`h4`,
-	5: u`h5`,
-	6: u`h6`
-}, f = class extends n {
+var f = {
+	2: d`h2`,
+	3: d`h3`,
+	4: d`h4`,
+	5: d`h5`,
+	6: d`h6`
+}, p = class extends n {
 	constructor(...e) {
 		super(...e), this.title = "", this.divider = !1, this.flush = !1, this.level = 3, this.hasActions = !1;
 	}
@@ -21,10 +21,13 @@ var d = {
 		this.styles = [super.styles, i];
 	}
 	render() {
-		let e = !!this.title || this.hasActions;
+		let e = !!this.title || !!this.description || this.hasActions;
 		return a`
       <div class="header ${this.divider ? "divider" : ""} ${e ? "" : "empty"}" part="header">
-        ${l`<${d[this.level] ?? d[3]} class="title" part="title">${this.title}${this.title && this.meta ? a` <span class="meta" part="meta">${this.meta}</span>` : ""}</${d[this.level] ?? d[3]}>`}
+        <div class="titles">
+          ${u`<${f[this.level] ?? f[3]} class="title" part="title">${this.title}${this.title && this.meta ? a` <span class="meta" part="meta">${this.meta}</span>` : ""}</${f[this.level] ?? f[3]}>`}
+          ${this.description ? a`<p class="description" part="description">${this.description}</p>` : o}
+        </div>
         <div class="actions ${this.hasActions ? "" : "empty"}" part="actions">
           <slot name="actions"
             @slotchange=${(e) => this.hasActions = r(e.target)}
@@ -35,9 +38,9 @@ var d = {
     `;
 	}
 };
-t([s({ type: String }), e("design:type", Object)], f.prototype, "title", void 0), t([s({ type: String }), e("design:type", String)], f.prototype, "meta", void 0), t([s({ type: Boolean }), e("design:type", Object)], f.prototype, "divider", void 0), t([s({ type: Boolean }), e("design:type", Object)], f.prototype, "flush", void 0), t([s({
+t([c({ type: String }), e("design:type", Object)], p.prototype, "title", void 0), t([c({ type: String }), e("design:type", String)], p.prototype, "meta", void 0), t([c({ type: String }), e("design:type", String)], p.prototype, "description", void 0), t([c({ type: Boolean }), e("design:type", Object)], p.prototype, "divider", void 0), t([c({ type: Boolean }), e("design:type", Object)], p.prototype, "flush", void 0), t([c({
 	type: Number,
 	reflect: !0
-}), e("design:type", Object)], f.prototype, "level", void 0), t([c(), e("design:type", Object)], f.prototype, "hasActions", void 0), f = t([o("u-group-box")], f);
+}), e("design:type", Object)], p.prototype, "level", void 0), t([l(), e("design:type", Object)], p.prototype, "hasActions", void 0), p = t([s("u-group-box")], p);
 //#endregion
-export { f as GroupBox };
+export { p as GroupBox };

package/dist/components/GroupBox.styles.js

@@ -7,10 +7,12 @@ var t = e`
        사이드바가 열린 1280px 화면의 좁은 본문에서도, 넓은 본문을 가진 태블릿에서도
        같은 판단을 하려면 기준이 자기 폭이어야 한다. */
     container-type: inline-size;
-    background-color: var(--u-bg-color-raised, #FAFAFA);
-    border: 1px solid var(--u-border-color-weak, #EEEEEE);
-    /* 면(surface) 단 — 컨트롤과 같은 반경을 쓰면 큰 사각형이 각져 보인다. */
-    border-radius: var(--u-radius-2xl, 12px);
+    /* 카드 = 떠 있는 컨테이너(--u-panel-bg-color) — u-card 와 같은 면·반경·선이다.
+       페이지는 --u-canvas-bg-color 위에 있으므로 카드는 바탕보다 한 단 밝은 면으로 선다
+       (종전에는 페이지가 흰색이라 카드를 크롬 틴트 --u-bg-color-raised 로 칠해 구분했다). */
+    background-color: var(--u-panel-bg-color, #FFFFFF);
+    border: 1px solid var(--u-border-color, #E0E0E0);
+    border-radius: var(--u-radius-xl, 8px);
     box-shadow: var(--u-shadow-sm, 0 1px 3px rgba(0, 0, 0, 0.08), 0 1px 1px rgba(0, 0, 0, 0.04));
   }
 
@@ -32,9 +34,17 @@ var t = e`
     border-bottom: 1px solid var(--u-border-color-weak, #EEEEEE);
   }
 
+  /* 제목과 설명 한 줄을 세로로 묶는다 — 액션은 그 오른쪽에 선다. */
+  .titles {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--u-space-3xs, 2px);
+  }
+
   .title {
     margin: 0;
-    flex: 1 1 auto;
     min-width: 0;
     font-size: var(--u-text-subtitle-size, 16px);
     font-weight: var(--u-text-subtitle-weight, 600);
@@ -51,6 +61,19 @@ var t = e`
     font-variant-numeric: tabular-nums;
   }
 
+  .description {
+    margin: 0;
+    font-size: var(--u-text-caption-size, 12px);
+    font-weight: var(--u-text-caption-weight, 400);
+    line-height: var(--u-text-caption-leading, 1.5);
+    color: var(--u-txt-color-weak, #616161);
+  }
+
+  /* 제목 없이 설명만 있으면 빈 헤딩이 자리를 잡지 않는다. */
+  .title:empty {
+    display: none;
+  }
+
   .actions {
     flex: 0 0 auto;
     display: flex;

package/dist/components/MasterDetailLayout.js

@@ -39,7 +39,7 @@ var u = class extends n {
       <div class="master ${this.hasDetail ? "covered" : ""}" part="master"><slot></slot></div>
       <div class="divider ${this.hasDetail ? "" : "empty"}" part="divider"></div>
       <div class="detail ${this.hasDetail ? "" : "empty"}" part="detail">
-        <u-button class="detail-close" part="detail-close" variant="ghost"
+        <u-button class="detail-close" part="detail-close" appearance="plain"
           aria-label=${r(this.locale || void 0).detailClose}
           @click=${this.handleDetailClose}
         >

package/dist/components/PageHeader.d.ts

@@ -1,6 +1,6 @@
 import { StyledElement } from '../internals/StyledElement.js';
 import { default as React } from 'react';
-type ElementParts = 'host' | 'back' | 'heading' | 'title' | 'subtitle' | 'status' | 'actions';
+type ElementParts = 'host' | 'back' | 'heading' | 'eyebrow' | 'title' | 'subtitle' | 'status' | 'actions';
 /**
  * 페이지 헤더 — 모든 LOB 화면 최상단의 같은 골격.
  *
@@ -10,21 +10,29 @@ type ElementParts = 'host' | 'back' | 'heading' | 'title' | 'subtitle' | 'status
  *   하나로 만들어지지 않았다"* 로 읽힌다.
  *
  * ```html
- * <u-page-header title="주문 G-2026-I-0629" subtitle="2026-02-24 접수" back="/orders">
+ * <u-page-header eyebrow="주문 관리" title="주문 G-2026-I-0629" subtitle="2026-02-24 접수" back="/orders">
  *   <span slot="status"><!-- 배지 --></span>
  *   <span slot="actions"><!-- 버튼 --></span>
  * </u-page-header>
  * ```
  *
- * 오버라이드: `part`(host·back·heading·title·subtitle·status·actions) + slot 치환.
+ * 오버라이드: `part`(host·back·heading·eyebrow·title·subtitle·status·actions) + slot 치환.
  * 값은 전부 토큰을 경유한다 — 리터럴을 두면 소비자가 밀도를 바꿀 수 없다.
  */
 export declare class PageHeader extends StyledElement<ElementParts> {
     static styles: import('lit').CSSResultGroup[];
     /** 페이지 제목. 타입 스케일의 `display` 단을 쓴다. */
     title: string;
-    /** 제목 아래 보조 설명. 없으면 렌더하지 않는다. */
+    /**
+     * 제목 아래 한 줄 설명 — 이 화면이 무엇을 하는지, 숫자가 무엇을 기준으로 하는지. 없으면 렌더하지 않는다.
+     * 본문 단(`body`)을 한 단 옅은 색으로 쓴다 — 캡션 단이면 설명이 아니라 각주로 읽힌다.
+     */
     subtitle?: string;
+    /**
+     * 제목 위 위치 표시 — 메뉴 그룹 이름이나 상위 경로. `overline` 단.
+     * 링크가 필요하면(브레드크럼) 같은 이름의 슬롯(`slot="eyebrow"`)을 쓴다 — 슬롯이 이 문자열을 대신한다.
+     */
+    eyebrow?: string;
     /**
      * 뒤로가기 링크 주소. 주면 제목 왼쪽에 `← 목록` 형태로 나온다.
      * ⚠텍스트는 `backLabel` 또는 locale 레지스트리로 바꾼다.
@@ -42,6 +50,7 @@ export declare class PageHeader extends StyledElement<ElementParts> {
      * 슬롯 배정 상태. ★CSS 로는 알 수 없다 — `<slot>` 자신이 자식이라 `:has(*)` 가
      * 항상 참이다(실브라우저로 확인). 빈 배지 자리가 남으면 제목 위치가 화면마다 달라진다.
      */
+    private hasEyebrow;
     private hasStatus;
     private hasActions;
     render(): import('lit-html').TemplateResult<1>;
@@ -57,6 +66,7 @@ declare module 'react' {
             'u-page-header': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
                 title?: string;
                 subtitle?: string;
+                eyebrow?: string;
                 back?: string;
                 'back-label'?: string;
                 locale?: string;

package/dist/components/PageHeader.js

@@ -9,7 +9,7 @@ import { customElement as c, property as l, state as u } from "lit/decorators.js
 //#region src/components/PageHeader.ts
 var d = class extends n {
 	constructor(...e) {
-		super(...e), this.title = "", this.backLabel = "", this.locale = "", this.hasStatus = !1, this.hasActions = !1;
+		super(...e), this.title = "", this.backLabel = "", this.locale = "", this.hasEyebrow = !1, this.hasStatus = !1, this.hasActions = !1;
 	}
 	static {
 		this.styles = [super.styles, a];
@@ -18,6 +18,11 @@ var d = class extends n {
 		return o`
       ${this.back ? o`<a class="back" part="back" href=${this.back}>${this.backLabel || r(this.locale || void 0).back}</a>` : s}
       <div class="heading" part="heading">
+        <div class="eyebrow ${this.eyebrow || this.hasEyebrow ? "" : "empty"}" part="eyebrow">
+          <slot name="eyebrow"
+            @slotchange=${(e) => this.hasEyebrow = i(e.target)}
+          >${this.eyebrow ?? s}</slot>
+        </div>
         <div class="title-row">
           <h1 class="title" part="title">${this.title}</h1>
           <span class="status ${this.hasStatus ? "" : "empty"}" part="status">
@@ -36,9 +41,9 @@ var d = class extends n {
     `;
 	}
 };
-t([l({ type: String }), e("design:type", Object)], d.prototype, "title", void 0), t([l({ type: String }), e("design:type", String)], d.prototype, "subtitle", void 0), t([l({ type: String }), e("design:type", String)], d.prototype, "back", void 0), t([l({
+t([l({ type: String }), e("design:type", Object)], d.prototype, "title", void 0), t([l({ type: String }), e("design:type", String)], d.prototype, "subtitle", void 0), t([l({ type: String }), e("design:type", String)], d.prototype, "eyebrow", void 0), t([l({ type: String }), e("design:type", String)], d.prototype, "back", void 0), t([l({
 	type: String,
 	attribute: "back-label"
-}), e("design:type", Object)], d.prototype, "backLabel", void 0), t([l({ type: String }), e("design:type", Object)], d.prototype, "locale", void 0), t([u(), e("design:type", Object)], d.prototype, "hasStatus", void 0), t([u(), e("design:type", Object)], d.prototype, "hasActions", void 0), d = t([c("u-page-header")], d);
+}), e("design:type", Object)], d.prototype, "backLabel", void 0), t([l({ type: String }), e("design:type", Object)], d.prototype, "locale", void 0), t([u(), e("design:type", Object)], d.prototype, "hasEyebrow", void 0), t([u(), e("design:type", Object)], d.prototype, "hasStatus", void 0), t([u(), e("design:type", Object)], d.prototype, "hasActions", void 0), d = t([c("u-page-header")], d);
 //#endregion
 export { d as PageHeader };

package/dist/components/PageHeader.styles.js

@@ -34,12 +34,28 @@ var t = e`
 
   .subtitle {
     margin: var(--u-space-2xs, 4px) 0 0;
-    font-size: var(--u-text-caption-size, 12px);
-    font-weight: var(--u-text-caption-weight, 400);
-    line-height: var(--u-text-caption-leading, 1.5);
+    font-size: var(--u-text-body-size, 14px);
+    font-weight: var(--u-text-body-weight, 400);
+    line-height: var(--u-text-body-leading, 1.6);
     color: var(--u-txt-color-weak, #616161);
   }
 
+  /* 제목 위 위치 표시 — 제목보다 네 단 작고 옅다. 링크(브레드크럼)는 상속받은 색으로 선다. */
+  .eyebrow {
+    margin: 0 0 var(--u-space-2xs, 4px);
+    font-size: var(--u-text-overline-size, 11px);
+    font-weight: var(--u-text-overline-weight, 700);
+    line-height: var(--u-text-overline-leading, 1.45);
+    letter-spacing: var(--u-text-overline-tracking, 0.06em);
+    color: var(--u-txt-color-weak, #616161);
+  }
+  .eyebrow ::slotted(*) {
+    color: inherit;
+  }
+  .eyebrow.empty {
+    display: none;
+  }
+
   .back {
     flex: 0 0 auto;
     align-self: center;
@@ -52,9 +68,11 @@ var t = e`
        ⚠고정 패딩(4px)이면 안 된다: line-height: normal 의 높이는 글꼴 메트릭이 정해서 글꼴에 따라 17px(→25)도
        15px(→23)도 된다. 줄 상자가 이미 24px 이상이면 패딩은 0 이다. */
     display: inline-block;
-    --_back-pad: max(0px, calc((24px - 1lh) / 2));
+    /* 호스트 하한(--u-target-size)이 있으면 24px 대신 그 값까지 — 폭도 그 값 이상. */
+    --_back-pad: max(0px, calc((max(24px, var(--u-target-size, 0px)) - 1lh) / 2));
     padding-block: var(--_back-pad);
     margin-block: calc(-1 * var(--_back-pad));
+    min-width: var(--u-target-size, 0px);
   }
   .back::before {
     content: '←';

package/dist/components/SidebarButton.styles.js

@@ -28,6 +28,8 @@ var t = e`
     justify-content: flex-start;
     gap: 12px;
     padding: 8px 12px;
+    /* 호스트 하한(--u-target-size, 미설정 = 0) — 상자는 border-box(기반 스타일)라 여백을 포함한다. */
+    min-height: var(--u-target-size, 0px);
   }
   button[compact] {
     justify-content: center;

package/dist/components/SidebarGroup.styles.js

@@ -19,6 +19,8 @@ var t = e`
     justify-content: space-between;
     gap: 12px;
     padding: 8px 12px;
+    /* 호스트 하한(--u-target-size, 미설정 = 0) — 상자는 border-box(기반 스타일)라 여백을 포함한다. */
+    min-height: var(--u-target-size, 0px);
     background-color: transparent;
     border: none;
     border-radius: 8px;

package/dist/components/SidebarLink.d.ts

@@ -1,7 +1,7 @@
 import { DirectiveResult } from 'lit/directive.js';
 import { StyledElement, StyleMap } from '../internals/StyledElement.js';
 import { SidebarPermissionGuard } from '../layouts/SidebarPermission.js';
-type ElementParts = 'host' | 'base' | 'icon' | 'label';
+type ElementParts = 'host' | 'base' | 'icon' | 'label' | 'count';
 /** 링크 항목 디폴트 타입 */
 export interface SidebarLinkConfig extends SidebarPermissionGuard {
     type: 'link';
@@ -30,6 +30,14 @@ export interface SidebarLinkConfig extends SidebarPermissionGuard {
      * 다른 문서로」를 표현할 수 없다. 그것이 종전에 유일한 탈출구였고, 그래서 부족했다.
      */
     target?: '_self' | '_blank';
+    /**
+     * A count shown at the end of the item — work waiting behind it (items to review, unpaid
+     * invoices). Omit it, or pass `undefined`, for items with nothing waiting; show numbers only
+     * where they ask for action, or the sidebar turns into a dashboard.
+     *
+     * The value can also be set later without rebuilding the layout: `app.setNavCount(href, n)`.
+     */
+    count?: number | string;
 }
 /**
  * SidebarLink 컴포넌트는 계층형 네비게이션 아이템을 표시합니다.
@@ -55,6 +63,8 @@ export declare class SidebarLink extends StyledElement<ElementParts> {
     navigate?: 'router' | 'document';
     /** 앵커 target — 새 탭으로 열 때 */
     target?: '_self' | '_blank';
+    /** 항목 끝의 건수 — 처리할 일이 있을 때만. `undefined`·빈 문자열이면 그리지 않는다. */
+    count?: number | string;
     render(): import('lit-html').TemplateResult<1>;
 }
 export {};

package/dist/components/SidebarLink.js

@@ -33,6 +33,7 @@ var u = class extends n {
           <span part="label" ?compact=${this.compact}>
             ${this.label}
           </span>
+          ${this.count === void 0 || this.count === null || this.count === "" ? s : o`<span class="count" part="count" ?compact=${this.compact}>${this.count}</span>`}
           ${this.target === "_blank" ? o`<span class="new-tab-hint">${r().opensInNewTab}</span>` : s}
         </div>
       </u-link>
@@ -42,6 +43,6 @@ var u = class extends n {
 t([l({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Object)], u.prototype, "selected", void 0), t([l({ type: Boolean }), e("design:type", Object)], u.prototype, "compact", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "icon", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "lib", void 0), t([l({ type: String }), e("design:type", Object)], u.prototype, "label", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "href", void 0), t([l({ type: String }), e("design:type", Object)], u.prototype, "pattern", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "navigate", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "target", void 0), u = t([c("u-sidebar-link")], u);
+}), e("design:type", Object)], u.prototype, "selected", void 0), t([l({ type: Boolean }), e("design:type", Object)], u.prototype, "compact", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "icon", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "lib", void 0), t([l({ type: String }), e("design:type", Object)], u.prototype, "label", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "href", void 0), t([l({ type: String }), e("design:type", Object)], u.prototype, "pattern", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "navigate", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "target", void 0), t([l(), e("design:type", Object)], u.prototype, "count", void 0), u = t([c("u-sidebar-link")], u);
 //#endregion
 export { u as SidebarLink };

package/dist/components/SidebarLink.styles.js

@@ -11,7 +11,7 @@ var t = e`
     display: block;
     color: var(--app-sidebar-fg, var(--u-txt-color, #212121));
     background-color: transparent;
-    border-radius: 8px;
+    border-radius: var(--app-sidebar-item-radius, 8px);
     transition: all var(--u-duration-normal, 220ms) ease;
     cursor: pointer;
   }
@@ -22,21 +22,25 @@ var t = e`
   :host([selected]) {
     color: var(--app-sidebar-active-fg, var(--u-txt-color-inverse, #FFFFFF));
     background-color: var(--link-active-bg);
-    box-shadow: 0 1px 3px var(--u-shadow-color-weak, rgba(0, 0, 0, 0.08));
+    box-shadow: var(--app-sidebar-active-shadow, 0 1px 3px var(--u-shadow-color-weak, rgba(0, 0, 0, 0.08)));
   }
   :host([selected]:hover) {
     color: var(--app-sidebar-active-fg, var(--u-txt-color-inverse, #FFFFFF));
     background-color: color-mix(in srgb, var(--link-active-bg) 85%, black);
-    box-shadow: 0 2px 6px var(--u-shadow-color-normal, rgba(0, 0, 0, 0.12));
+    box-shadow: var(--app-sidebar-active-shadow-hover, 0 2px 6px var(--u-shadow-color-normal, rgba(0, 0, 0, 0.12)));
   }
   
   .container {
+    position: relative;
     display: flex;
     flex-direction: row;
     align-items: center;
     justify-content: flex-start;
-    gap: 12px;
-    padding: 8px 12px;
+    gap: var(--app-sidebar-item-gap, 12px);
+    padding: var(--app-sidebar-item-padding, 8px 12px);
+    /* 호스트 하한(--u-target-size, 미설정 = 0). */
+    box-sizing: border-box;
+    min-height: var(--u-target-size, 0px);
   }
   .container[compact] {
     justify-content: center;
@@ -47,12 +51,24 @@ var t = e`
   u-icon {
     flex-shrink: 0;
     color: var(--link-icon-color, inherit);
-    font-size: 20px;
+    font-size: var(--app-sidebar-icon-size, 20px);
   }
   /* Selected always wins over any consumer-supplied --link-icon-color — a
    * high-contrast icon on the active background matters more than a brand tint. */
   :host([selected]) u-icon {
-    color: var(--app-sidebar-active-fg, var(--u-txt-color-inverse, #FFFFFF));
+    color: var(--app-sidebar-active-icon-color, var(--app-sidebar-active-fg, var(--u-txt-color-inverse, #FFFFFF)));
+  }
+
+  /* 활성 표시 막대 — 시작 변(좌→우 언어에서 왼쪽). 기본 색은 활성 면과 같아 보이지 않는다(기본 외형 불변).
+     밝은 활성 면처럼 면 색만으로 현재 위치를 말하지 않는 셸이 위치를 한 번 더 표시하는 자리다. */
+  :host([selected]) .container::before {
+    content: '';
+    position: absolute;
+    inset-block: 6px;
+    inset-inline-start: 0;
+    width: var(--app-sidebar-active-indicator-width, 3px);
+    border-radius: var(--u-radius-pill, 9999px);
+    background: var(--app-sidebar-active-indicator-color, var(--app-sidebar-active-bg, var(--u-primary-color, #1976D2)));
   }
 
   /*
@@ -87,6 +103,26 @@ var t = e`
     white-space: nowrap;
     border: 0;
   }
+
+  /* 건수 — 라벨 끝, 숫자는 표 숫자처럼 자릿수가 흔들리지 않게. 접힌 사이드바에서는 라벨처럼
+     시각적으로만 숨긴다(접근 가능한 이름에는 남는다). */
+  .count {
+    flex: none;
+    margin-inline-start: auto;
+    font-size: var(--u-text-overline-size, 11px);
+    font-weight: var(--u-text-caption-weight, 400);
+    font-variant-numeric: tabular-nums;
+    opacity: 0.8;
+  }
+  .count[compact] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
 `;
 //#endregion
 export { t as styles };

package/dist/components/SidebarSection.styles.js

@@ -14,19 +14,16 @@ var t = e`
     padding: 8px 12px 4px;
   }
 
-  /* ⚠아래 두 색만 팔레트를 직접 읽는다 — 시맨틱 토큰으로 옮기면 대비가 무너지기 때문이다.
-     섹션 제목·부제는 본문(neutral-800)보다 약한 3단 위계를 이루는데, 역할 층의 보조
-     텍스트 단은 --u-txt-color-weak 하나뿐이고 그 값은 흰 배경에서 2.68:1 이라
-     WCAG AA(4.5:1)에 미달한다. 현행 두 값은 6.19:1 · 4.61:1 로 통과한다.
-     ⇒ 역할 층에 AA 를 넘는 보조 텍스트 단이 생기면 그때 옮긴다. */
+  /* 섹션 제목·부제는 본문보다 약한 두 단이다 — 제목 = 보조 글자(--u-txt-color-weak),
+     부제 = 3단 글자(--u-txt-color-weaker, components 2.0). 종전에는 역할 층에 AA 를 넘는
+     3단이 없어 팔레트(neutral-700/600)를 직접 읽었고, 그래서 테마가 이 두 줄에 닿지 않았다. */
   /*
-   * ★크기·굵기·자간은 스케일의 단으로 옮겼다(용도 배정). 위 주석은 **색**에
-   *   대한 것이고 그대로 유효하다: 두 색은 여전히 팔레트를 직접 읽는다.
+   * ★크기·굵기·자간은 스케일의 단으로 옮겼다(용도 배정).
    * ⚠ overline 에 대문자 변환을 붙이지 않는다 — 이 줄에 ellipsis 가 있어 잘림이 늘고,
    *   섹션 이름은 소비자가 쓴 글자다(CJK 에는 효과도 없다).
    */
   .title {
-    color: var(--u-neutral-700, #616161);
+    color: var(--u-txt-color-weak, #616161);
     font-size: var(--u-text-overline-size, 11px);
     font-weight: var(--u-text-overline-weight, 700);
     line-height: var(--u-text-overline-leading, 1.45);
@@ -37,7 +34,7 @@ var t = e`
   }
 
   .subtitle {
-    color: var(--u-neutral-600, #757575);
+    color: var(--u-txt-color-weaker, #757575);
     font-size: var(--u-text-caption-size, 12px);
     font-weight: var(--u-text-caption-weight, 400);
     line-height: var(--u-text-caption-leading, 1.5);

package/dist/components/Wizard.js

@@ -92,7 +92,7 @@ var u = class extends n {
         </div>
         <div class="actions" part="actions">
           <slot name="actions">
-            <u-button variant="ghost" ?disabled=${this.active === 0} @click=${() => this.back()}>
+            <u-button appearance="plain" ?disabled=${this.active === 0} @click=${() => this.back()}>
               ${e.wizardBack}
             </u-button>
             ${t ? o : a`

package/dist/components/Wizard.styles.js

@@ -39,6 +39,8 @@ var t = e`
     background: none;
     border: none;
     padding: var(--u-space-2xs, 4px) 0;
+    /* 호스트 하한(--u-target-size, 미설정 = 0). */
+    min-height: var(--u-target-size, 0px);
     font: inherit;
     color: var(--u-txt-color-weak, #616161);
     cursor: pointer;

package/dist/layouts/SidebarLayout.d.ts

@@ -9,6 +9,11 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     state: SidebarState;
     /** 사이드바 레이아웃 설정 */
     config?: SidebarLayoutConfig;
+    /**
+     * Live counts for link items, keyed by the item's `href` — overrides the static `count` of the
+     * item config. Set through `app.setNavCount(href, value)`; assigning a new object re-renders.
+     */
+    counts: Record<string, number | string | undefined>;
     /** 크롬 문자열(토글 버튼 접근성 라벨 등) 로케일 — 이 요소만 다른 언어로 쓸 때. 비우면 `Locale` 의 활성 로케일 */
     locale: string;
     progressBarEl: UProgressBar;

package/dist/layouts/SidebarLayout.js

@@ -59,7 +59,7 @@ var j = class extends i {
 		C = this;
 	}
 	constructor(...t) {
-		super(...t), this.state = "default", 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.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 = () => {
 			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 = () => {
@@ -171,7 +171,7 @@ var j = class extends i {
         <span class="title">
           ${this.config.title}
         </span>
-        <u-button class="toggler" variant="ghost"
+        <u-button class="toggler" appearance="plain"
           aria-label=${a(this.locale || void 0).toggleMobileMenu}
           @click=${this.handleToggleButtonClick}>
           <u-icon
@@ -189,7 +189,7 @@ var j = class extends i {
           <span class="title" ?hidden=${this.state === "slim"}>
             ${this.config.title}
           </span>
-          <u-button class="toggler" variant="ghost"
+          <u-button class="toggler" appearance="plain"
             aria-label=${a(this.locale || void 0).toggleSidebar}
             @click=${this.handleToggleButtonClick}>
             <u-icon
@@ -227,7 +227,7 @@ var j = class extends i {
         </main>
 
         <div class="overlay ${this.hasOverlay ? "" : "empty"}" part="overlay">
-          <u-button class="overlay-close" part="overlay-close" variant="ghost"
+          <u-button class="overlay-close" part="overlay-close" appearance="plain"
             aria-label=${a(this.locale || void 0).detailClose}
             @click=${this.handleOverlayClose}>
             <u-icon lib=${this.icon("lib")} name=${this.icon("overlayClose")}></u-icon>
@@ -272,6 +272,7 @@ var j = class extends i {
           .pattern="${e.pattern}"
           .navigate="${e.navigate}"
           .target="${e.target}"
+          .count=${e.href in this.counts ? this.counts[e.href] : e.count}
           .styles="${e.styles}"
         ></u-sidebar-link>
       `;
@@ -377,6 +378,6 @@ var j = class extends i {
 r([f({
 	type: String,
 	reflect: !0
-}), n("design:type", Object)], j.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], j.prototype, "config", void 0), r([f({ type: String }), n("design:type", Object)], j.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", S === void 0 ? Object : S)], j.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], j.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], j.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], j.prototype, "context", void 0), j = C = r([d("u-sidebar-layout")], j);
+}), n("design:type", Object)], j.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], j.prototype, "config", void 0), r([f({ type: Object }), n("design:type", typeof Record > "u" ? Object : Record)], j.prototype, "counts", void 0), r([f({ type: String }), n("design:type", Object)], j.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", S === void 0 ? Object : S)], j.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], j.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], j.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], j.prototype, "context", void 0), j = C = r([d("u-sidebar-layout")], j);
 //#endregion
 export { j as SidebarLayout };

package/dist/layouts/SidebarLayout.styles.js

@@ -32,6 +32,12 @@ var t = e`
     height: 24px;
     width: auto;
     object-fit: contain;
+    /* 호스트 하한(--u-target-size) — 그림은 24px 그대로, 누르는 상자만 여백으로 넓히고 같은 만큼 되돌려 배치는 그대로.
+       미설정이면 여백 0(종전). */
+    --_logo-pad: max(0px, calc((var(--u-target-size, 0px) - 24px) / 2));
+    box-sizing: content-box;
+    padding: var(--_logo-pad);
+    margin: calc(-1 * var(--_logo-pad));
   }
   /* 로고를 감싼 링크 — 인라인 기준선 여백이 생기지 않게 로고 상자에 딱 맞춘다. */
   .logo-link {
@@ -58,14 +64,14 @@ var t = e`
   }
 
   /*
-   * 토글러의 "테두리·배경 없음"은 마크업의 variant="ghost" 가 낸다.
+   * 토글러의 "테두리·배경 없음"은 마크업의 appearance="plain" 이 낸다.
    *
    * ★여기에 border/background 를 적는 것으로는 부족했다 — 이 규칙은 <u-button> **호스트**에만
    *   닿고, 테두리를 실제로 그리는 것은 그 섀도 루트 안의 <button> 이다(solid 기본값이
    *   --btn-border-color: var(--btn-color) 로 그린다). 호스트만 재면 0px 이라 보이지도 않았다.
    *   variant 를 명시해 컴포넌트가 스스로 투명하게 그리도록 한다.
    *
-   * color: inherit 는 유지한다 — 헤더 색을 따라가게 하려는 의도이고 ghost 의 기본 전경
+   * color: inherit 는 유지한다 — 헤더 색을 따라가게 하려는 의도이고 plain 의 기본 전경
    * (--u-txt-color)보다 이 레이아웃의 뜻이 앞선다.
    */
   .toggler {
@@ -114,7 +120,12 @@ var t = e`
     flex-direction: column;
     justify-content: space-between;
     gap: 8px;
-    height: 100%;
+    /* 높이는 백분율이 아니라 flex 의 stretch 로 받는다 — 셸의 높이가 «부모의 확정 높이» 가 아니라
+       max-height 상한에서 나오면 height: 100% 는 풀리지 않아(auto) 사이드바가 메뉴 길이로 커지고,
+       셸의 overflow: hidden 이 아래쪽 계정 영역을 잘라 닿을 수 없게 된다. 늘어난 항목의 높이는
+       그 경우에도 셸의 (상한으로 잘린) 높이다. .main-region 과 같은 해법이다. 떠 있는 상태
+       (modal · mobile*)는 절대배치라 top/bottom 으로 채운다. */
+    min-height: 0;
     /* --u-panel-bg-color 가 아니라 --u-bg-color-raised — 사이드바는 카드·메뉴류의
        "떠 있는 패널"이 아니라 상시 크롬이고, 그 구분이 정확히 두 토큰이 갈리는 지점이다
        (light.css 293~298행 참조). 미설정 시 페이지(--u-bg-color)와 같은 흰색으로 앉아
@@ -140,11 +151,13 @@ var t = e`
     width: var(--app-sidebar-width, 260px);
     position: absolute;
     top: 0;
+    bottom: 0;
     left: 0;
   }
   .sidebar[state="mobile"] {
     position: absolute;
     top: 0;
+    bottom: 0;
     left: 0;
     right: 0;
     transform: translateY(-100%);
@@ -152,6 +165,7 @@ var t = e`
   .sidebar[state="mobile-open"] {
     position: absolute;
     top: 0;
+    bottom: 0;
     left: 0;
     right: 0;
     transform: translateY(0);
@@ -188,6 +202,8 @@ var t = e`
   /* Sidebar Main Menu */
   .sidebar-main {
     flex: 1;
+    /* 열 방향 flex 항목의 자동 최소 높이는 내용 길이다 — 0 으로 풀어야 남는 높이 안에서 스크롤한다. */
+    min-height: 0;
     display: flex;
     flex-direction: column;
     gap: 4px;
@@ -237,12 +253,14 @@ var t = e`
     flex-direction: column;
   }
 
+  /* The page sits on the canvas (the application background), not on a surface: cards and tables
+     placed on it keep \`--u-bg-color\` as their own face. */
   .main {
     position: relative;
     flex: 1 1 auto;
     min-height: 0;
-    padding: var(--u-space-3xl, 32px);
-    background: var(--u-bg-color, #FFFFFF);
+    padding: var(--app-main-padding, var(--u-space-3xl, 32px));
+    background: var(--u-canvas-bg-color, #F5F5F5);
     overflow: auto;
     outline: none;
   }

package/dist/react/ActionBar.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { ActionBar as ActionBarElement } from '@iyulab/modern-app/dist/components/ActionBar.js';
 
+type ActionBarOwnProps = Omit<ActionBarElement, keyof HTMLElement>;
+
 export declare const ActionBar: React.ForwardRefExoticComponent<
-  Omit<Partial<ActionBarElement>, keyof React.HTMLAttributes<ActionBarElement>>
-    & Omit<React.HTMLAttributes<ActionBarElement>, never>
+  Partial<Omit<ActionBarElement, Exclude<keyof React.HTMLAttributes<ActionBarElement>, keyof ActionBarOwnProps>>>
+    & Omit<React.HTMLAttributes<ActionBarElement>, keyof ActionBarOwnProps | never>
     & React.RefAttributes<ActionBarElement>
     & {
   }

package/dist/react/EmptyState.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { EmptyState as EmptyStateElement } from '@iyulab/modern-app/dist/components/EmptyState.js';
 
+type EmptyStateOwnProps = Omit<EmptyStateElement, keyof HTMLElement>;
+
 export declare const EmptyState: React.ForwardRefExoticComponent<
-  Omit<Partial<EmptyStateElement>, keyof React.HTMLAttributes<EmptyStateElement>>
-    & Omit<React.HTMLAttributes<EmptyStateElement>, never>
+  Partial<Omit<EmptyStateElement, Exclude<keyof React.HTMLAttributes<EmptyStateElement>, keyof EmptyStateOwnProps>>>
+    & Omit<React.HTMLAttributes<EmptyStateElement>, keyof EmptyStateOwnProps | never>
     & React.RefAttributes<EmptyStateElement>
     & {
   }

package/dist/react/GroupBox.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { GroupBox as GroupBoxElement } from '@iyulab/modern-app/dist/components/GroupBox.js';
 
+type GroupBoxOwnProps = Omit<GroupBoxElement, keyof HTMLElement>;
+
 export declare const GroupBox: React.ForwardRefExoticComponent<
-  Omit<Partial<GroupBoxElement>, keyof React.HTMLAttributes<GroupBoxElement>>
-    & Omit<React.HTMLAttributes<GroupBoxElement>, never>
+  Partial<Omit<GroupBoxElement, Exclude<keyof React.HTMLAttributes<GroupBoxElement>, keyof GroupBoxOwnProps>>>
+    & Omit<React.HTMLAttributes<GroupBoxElement>, keyof GroupBoxOwnProps | never>
     & React.RefAttributes<GroupBoxElement>
     & {
   }

package/dist/react/InfoField.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { InfoField as InfoFieldElement } from '@iyulab/modern-app/dist/components/InfoField.js';
 
+type InfoFieldOwnProps = Omit<InfoFieldElement, keyof HTMLElement>;
+
 export declare const InfoField: React.ForwardRefExoticComponent<
-  Omit<Partial<InfoFieldElement>, keyof React.HTMLAttributes<InfoFieldElement>>
-    & Omit<React.HTMLAttributes<InfoFieldElement>, never>
+  Partial<Omit<InfoFieldElement, Exclude<keyof React.HTMLAttributes<InfoFieldElement>, keyof InfoFieldOwnProps>>>
+    & Omit<React.HTMLAttributes<InfoFieldElement>, keyof InfoFieldOwnProps | never>
     & React.RefAttributes<InfoFieldElement>
     & {
   }

package/dist/react/InfoSection.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { InfoSection as InfoSectionElement } from '@iyulab/modern-app/dist/components/InfoSection.js';
 
+type InfoSectionOwnProps = Omit<InfoSectionElement, keyof HTMLElement>;
+
 export declare const InfoSection: React.ForwardRefExoticComponent<
-  Omit<Partial<InfoSectionElement>, keyof React.HTMLAttributes<InfoSectionElement>>
-    & Omit<React.HTMLAttributes<InfoSectionElement>, never>
+  Partial<Omit<InfoSectionElement, Exclude<keyof React.HTMLAttributes<InfoSectionElement>, keyof InfoSectionOwnProps>>>
+    & Omit<React.HTMLAttributes<InfoSectionElement>, keyof InfoSectionOwnProps | never>
     & React.RefAttributes<InfoSectionElement>
     & {
   }

package/dist/react/MasterDetailLayout.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { MasterDetailLayout as MasterDetailLayoutElement } from '@iyulab/modern-app/dist/components/MasterDetailLayout.js';
 
+type MasterDetailLayoutOwnProps = Omit<MasterDetailLayoutElement, keyof HTMLElement>;
+
 export declare const MasterDetailLayout: React.ForwardRefExoticComponent<
-  Omit<Partial<MasterDetailLayoutElement>, keyof React.HTMLAttributes<MasterDetailLayoutElement>>
-    & Omit<React.HTMLAttributes<MasterDetailLayoutElement>, 'onDetailClose'>
+  Partial<Omit<MasterDetailLayoutElement, Exclude<keyof React.HTMLAttributes<MasterDetailLayoutElement>, keyof MasterDetailLayoutOwnProps>>>
+    & Omit<React.HTMLAttributes<MasterDetailLayoutElement>, keyof MasterDetailLayoutOwnProps | 'onDetailClose'>
     & React.RefAttributes<MasterDetailLayoutElement>
     & {
   onDetailClose?: (event: CustomEvent) => void;

package/dist/react/PageHeader.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { PageHeader as PageHeaderElement } from '@iyulab/modern-app/dist/components/PageHeader.js';
 
+type PageHeaderOwnProps = Omit<PageHeaderElement, keyof HTMLElement>;
+
 export declare const PageHeader: React.ForwardRefExoticComponent<
-  Omit<Partial<PageHeaderElement>, keyof React.HTMLAttributes<PageHeaderElement>>
-    & Omit<React.HTMLAttributes<PageHeaderElement>, never>
+  Partial<Omit<PageHeaderElement, Exclude<keyof React.HTMLAttributes<PageHeaderElement>, keyof PageHeaderOwnProps>>>
+    & Omit<React.HTMLAttributes<PageHeaderElement>, keyof PageHeaderOwnProps | never>
     & React.RefAttributes<PageHeaderElement>
     & {
   }

package/dist/react/SidebarButton.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { SidebarButton as SidebarButtonElement } from '@iyulab/modern-app/dist/components/SidebarButton.js';
 
+type SidebarButtonOwnProps = Omit<SidebarButtonElement, keyof HTMLElement>;
+
 export declare const SidebarButton: React.ForwardRefExoticComponent<
-  Omit<Partial<SidebarButtonElement>, keyof React.HTMLAttributes<SidebarButtonElement>>
-    & Omit<React.HTMLAttributes<SidebarButtonElement>, never>
+  Partial<Omit<SidebarButtonElement, Exclude<keyof React.HTMLAttributes<SidebarButtonElement>, keyof SidebarButtonOwnProps>>>
+    & Omit<React.HTMLAttributes<SidebarButtonElement>, keyof SidebarButtonOwnProps | never>
     & React.RefAttributes<SidebarButtonElement>
     & {
   }

package/dist/types/AppConfigs.d.ts

@@ -33,6 +33,13 @@ export interface AppConfig {
      * @default '/'
      */
     basepath?: string;
+    /**
+     * 라우트를 주소의 어디에서 읽는가 — `@iyulab/router` 의 `mode` 로 그대로 전달된다.
+     * - `'history'`: 경로(`/app/orders/7`). 서버가 앱의 모든 경로에 같은 문서를 돌려줘야 새로고침·딥링크가 동작한다.
+     * - `'hash'`: `#` 뒤(`/app/#/orders/7`). 정적 호스팅에서 서버 설정 없이 딥링크가 동작한다.
+     * @default 'history'
+     */
+    routerMode?: 'history' | 'hash';
     /**
      * 현재 애플리케이션의 기본 아이콘 경로 설정
      * @default '/assets/icons/'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.33.3",
+  "version": "0.34.1",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -50,6 +50,7 @@
   },
   "scripts": {
     "preversion": "node -e \"if(require('fs').existsSync('../../scripts/preversion-check.mjs'))require('child_process').execFileSync('node',['../../scripts/preversion-check.mjs'],{stdio:'inherit'})\"",
+    "pretest": "node -e \"if(require('fs').existsSync('../../scripts/sibling-dist-check.js'))require('child_process').execFileSync('node',['../../scripts/sibling-dist-check.js'],{stdio:'inherit'})\"",
     "test": "vitest run",
     "test:watch": "vitest",
     "start": "vite",
@@ -59,12 +60,12 @@
     "test:react-types": "tsc -p tsconfig.react-smoke.json"
   },
   "dependencies": {
-    "@iyulab/router": "^0.17.0",
+    "@iyulab/router": "^0.19.0",
     "i18next": "^26.3.6",
     "lit": "^3.3.3"
   },
   "peerDependencies": {
-    "@iyulab/components": ">=1.49.0",
+    "@iyulab/components": ">=2.0.0",
     "@lit/react": "^1.0.8",
     "react": "^18.0.0 || ^19.0.0"
   },
@@ -77,7 +78,7 @@
     }
   },
   "devDependencies": {
-    "@iyulab/components": ">=1.49.0",
+    "@iyulab/components": ">=2.0.0",
     "@lit/react": "^1.0.8",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.14",

package/skills/modern-app/SKILL.md

@@ -4,7 +4,6 @@ description: Client-side SPA framework built on Lit Element. Bootstraps an appli
 license: MIT
 metadata:
   author: iyulab
-  version: "0.3.4"
 compatibility: Designed for Lit Element / TypeScript projects. Requires @iyulab/modern-app.
 ---
 

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

@@ -10,6 +10,9 @@ interface AppConfig {
   /** Base path for all routes. Default: '/' */
   basepath?: string;
 
+  /** Where the route lives: 'history' = the path, 'hash' = after `#` (static hosting, no server fallback). Default: 'history' */
+  routerMode?: 'history' | 'hash';
+
   /** Base URL for icon assets. Default: '/assets/icons/' */
   iconBasepath?: string;
 

package/skills/modern-app/references/components/action-bar.md

@@ -7,8 +7,8 @@ destructive ones separated on the trailing edge.
 
 ```html
 <u-action-bar sticky>
-  <u-button variant="solid">Save</u-button>
-  <u-button variant="outline">Cancel</u-button>
+  <u-button appearance="solid">Save</u-button>
+  <u-button appearance="outlined">Cancel</u-button>
   <u-button slot="danger" color="danger">Delete</u-button>
 </u-action-bar>
 ```

package/skills/modern-app/references/components/group-box.md

@@ -31,6 +31,7 @@ a left edge without any consumer CSS.
 |----------|------|---------|---------|-------------|
 | `title` | `string` | `''` | | Header title |
 | `meta` | `string` | — | | Secondary text after the title — a count, progress or short status (`3 items`, `2/5 done`), one step below the title: body size and weight, weak color, tabular figures. It sits inside the heading, so the heading's accessible name includes it. Not drawn without `title` |
+| `description` | `string` | — | | One line under the title — what the box holds or what its numbers are based on. Caption size, weak color. Opens the header on its own |
 | `divider` | `boolean` | `false` | | Rule between header and body. Off by default — many rules make a screen noisy |
 | `flush` | `boolean` | `false` | | Remove body padding, for tables and lists that draw their own edges |
 | `level` | `2|3|4|5|6` | `3` | ✓ | Heading level of the title in the document outline. Set `2` for a box directly under `u-page-header` (the page's `h1`), so the outline does not skip a level. Semantics only — the title looks the same at every level |
@@ -41,6 +42,7 @@ a left edge without any consumer CSS.
 |------|-------------|
 | `header` · `title` · `actions` | Header row |
 | `meta` | Secondary text inside the title |
+| `description` | One-line description under the title |
 | `body` | Body wrapper |
 
 ## CSS Custom Properties
@@ -52,6 +54,7 @@ a left edge without any consumer CSS.
 | `--u-text-subtitle-leading` | Title line height |
 | `--u-text-subtitle-tracking` | Title letter spacing |
 | `--u-text-body-size` / `--u-text-body-weight` / `--u-txt-color-weak` | `meta` size, weight and color |
+| `--u-text-caption-size` / `-weight` / `-leading` | `description` typography |
 | `--u-bg-color-raised` | Surface background |
 | `--u-border-color-weak` | Border and header divider color |
 | `--u-radius-2xl` | Corner radius |

package/skills/modern-app/references/components/page-header.md

@@ -2,15 +2,15 @@
 
 **Tag:** `u-page-header`
 
-The same skeleton at the top of every LOB screen: optional back link, title, subtitle,
-a status slot, and an actions slot.
+The same skeleton at the top of every LOB screen: optional back link, an eyebrow (menu group or
+breadcrumb), title, a one-line description, a status slot, and an actions slot.
 
 Hand-rolling this per screen is where a product stops looking like one product — title sizes
 drift, action alignment goes slightly off, and the narrow-viewport rule gets forgotten on the
 screens nobody opens.
 
 ```html
-<u-page-header title="Order G-2026-I-0629" subtitle="Received 2026-02-24" back="/orders">
+<u-page-header eyebrow="Sales" title="Order G-2026-I-0629" subtitle="Received 2026-02-24" back="/orders">
   <span slot="status"><u-tag color="success">Confirmed</u-tag></span>
   <span slot="actions"><u-button>Edit</u-button></span>
 </u-page-header>
@@ -20,6 +20,7 @@ screens nobody opens.
 
 | Name | Description |
 |------|-------------|
+| `eyebrow` | Replaces the `eyebrow` text — e.g. breadcrumb links |
 | `status` | Badge or tag beside the title |
 | `actions` | Buttons on the trailing edge |
 
@@ -28,7 +29,8 @@ screens nobody opens.
 | Property | Type | Default | Reflect | Description |
 |----------|------|---------|---------|-------------|
 | `title` | `string` | `''` | | Page title |
-| `subtitle` | `string` | — | | Secondary line under the title |
+| `subtitle` | `string` | — | | One-line description under the title — what the screen is for. Body size, weak color |
+| `eyebrow` | `string` | — | | Small line above the title — the menu group or parent path. Overline step; the `eyebrow` slot replaces it |
 | `back` | `string` | — | | Back-link href; renders a back affordance before the title |
 | `backLabel` | `string` | `''` | | Back-link text (`back-label`). Empty falls back to the locale registry, then English |
 | `locale` | `string` | `''` | | Locale tag override for built-in strings |
@@ -38,7 +40,8 @@ screens nobody opens.
 | Part | Description |
 |------|-------------|
 | `back` | Back link |
-| `heading` | Title + subtitle wrapper |
+| `heading` | Eyebrow + title + subtitle wrapper |
+| `eyebrow` | Eyebrow row (hidden when empty) |
 | `title` · `subtitle` | Text elements |
 | `status` · `actions` | Slot wrappers |
 
@@ -48,14 +51,15 @@ screens nobody opens.
 |----------|-------------|
 | `--u-text-display-size` / `-weight` / `-leading` / `-tracking` | Title typography |
 | `--u-txt-color` | Title color |
-| `--u-text-caption-size` / `-weight` / `-leading` | Subtitle typography |
-| `--u-txt-color-weak` | Subtitle color |
+| `--u-text-body-size` / `-weight` / `-leading` | Subtitle typography |
+| `--u-text-overline-size` / `-weight` / `-leading` / `-tracking` | Eyebrow typography |
+| `--u-txt-color-weak` | Subtitle and eyebrow color |
 | `--u-link-txt-color` | Back-link color |
 | `--u-text-label-size` / `-weight` | Back-link typography |
 | `--u-space-2xl` | Host bottom margin |
 | `--u-space-md` | Row gap (heading vs. actions) |
 | `--u-space-sm` | Title-row and actions internal gap |
-| `--u-space-2xs` | Title-to-subtitle spacing |
+| `--u-space-2xs` | Eyebrow-to-title and title-to-subtitle spacing |
 | `--u-space-3xs` | Back-arrow-to-label spacing |
 
 ⚠ Built-in strings default to **English**, with Korean built in — choose the language with

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

@@ -61,7 +61,9 @@ interface SidebarLinkConfig {
   navigate?: 'router' | 'document';
   /** Anchor target. Use for opening in a new tab. */
   target?: '_self' | '_blank';
-  styles?: StyleMap<'host' | 'base' | 'icon' | 'label'>;
+  /** Work waiting behind the item, shown at its end. Change it at runtime with app.setNavCount(href, n). */
+  count?: number | string;
+  styles?: StyleMap<'host' | 'base' | 'icon' | 'label' | 'count'>;
 }
 ```
 
@@ -87,6 +89,21 @@ highlighting still works, and it can live inside a section or group. `target: '_
 is available too, but it is not a substitute — it forces a new tab, so same-tab
 navigation to another document needs `navigate`.
 
+#### Counts — work waiting behind an item
+
+A link can end with a count: items to review, unpaid invoices. Show numbers only where
+they ask for action, or the sidebar turns into a dashboard.
+
+```typescript
+{ type: 'link', icon: 'inbox', label: 'Reviews', href: '/reviews', count: 12 }
+
+// later, without rebuilding the layout — `undefined` clears it
+app.setNavCount('/reviews', 3);
+```
+
+The count is `part="count"`; in the compact sidebar it stays in the link's accessible
+name and is hidden visually.
+
 ---
 
 ### `SidebarGroupConfig` — `type: 'group'`
@@ -285,11 +302,14 @@ rule of your own wins.
 
 ⚠ **A custom `root` receives no styling.** Hand it a container with no height of its own and
 `height: 100%` has nothing to resolve against: the shell renders at whatever its own chrome
-resolves to (measured: about 133px) instead of filling the screen — with no error and nothing in
-the console. (With a long screen the shell grows to the viewport cap instead, so the
-symptom only shows on short screens.) Give that container a height — for screen only, so printing is not cut at one page:
+resolves to (measured: about 133px) instead of filling the screen — no error, only a
+development-mode console warning when it is shorter than 200px. (With a long screen the shell grows
+to the viewport cap instead, so the symptom only shows on short screens.) The body margin is not
+removed either, so the browser's default 8px stays around the shell. Give that container a height —
+for screen only, so printing is not cut at one page — and clear the margin:
 
 ```css
+:where(body) { margin: 0; }
 @media screen {
   #app { height: 100vh; }   /* or 100%, inside an already-constrained ancestor */
 }