@iyulab/modern-app 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.21.0] - 2026-09-17
+
+### Added
+
+- **`translate()` — a reactive translation directive**, exported from `@iyulab/modern-app`. It is
+  bound to the i18next instance `app.load({ i18n })` initializes and re-renders its part when the
+  language changes, when resources arrive later, and once i18next finishes initializing (until then
+  it renders an empty string rather than the key). A disconnected template stops listening and
+  catches up when reconnected. Sidebar item labels already accept a directive result, so
+  `label: translate('nav::home')` now works without a third-party package; the documentation
+  previously pointed to `lit-i18n` for this. Migrating is an import swap plus dropping
+  `initLitI18n` from `i18n.plugins`.
+
+### Fixed
+
+- **A collapsed sidebar no longer leaves translated items without an accessible name.** In the
+  collapsed state the item label was removed with `hidden`, which also removes it from the
+  accessibility tree; an `aria-label` was substituted only when the label was a plain string, so an
+  item labelled with a directive was announced with no name. The label is now hidden visually and
+  stays in the accessibility tree, so it names the link, button or group whatever its type. Items
+  no longer carry an `aria-label` in the collapsed state.
+
 ## [0.20.1] - 2026-09-17
 
 ### Fixed

package/README.md

@@ -113,8 +113,8 @@ await app.load({
 app.i18n.t('common::greeting');
 app.i18n.changeLanguage('ko');
 
-// Reactive translations in Lit templates
-import { translate } from 'lit-i18n';
+// Reactive translations in Lit templates — and in shell labels
+import { translate } from '@iyulab/modern-app';
 html`<p>${translate('common::greeting')}</p>`;
 ```
 
@@ -263,7 +263,7 @@ contrast likewise comes from that package's tokens.
 | [layout.md](./docs/layout.md) | Sidebar layout, all menu item types, responsive behaviour |
 | [theme.md](./docs/theme.md) | Theme init, runtime switching, token layers, shell surface tokens |
 | [notifications.md](./docs/notifications.md) | Toast methods and options |
-| [i18n.md](./docs/i18n.md) | i18next setup, plugins, lit-i18n usage |
+| [i18n.md](./docs/i18n.md) | i18next setup, plugins, the `translate()` directive |
 | [configuration.md](./docs/configuration.md) | Full TypeScript interface reference |
 
 ## License

package/dist/components/SidebarButton.js

@@ -3,11 +3,11 @@ import t from "../_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorate.js
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { DEFAULT_NAV_ICON as r } from "../internals/nav-icon.js";
 import { styles as i } from "./SidebarButton.styles.js";
-import { html as a, nothing as o } from "lit";
-import { customElement as s, property as c } from "lit/decorators.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";
 //#region src/components/SidebarButton.ts
-var l = class extends n {
+var c = class extends n {
 	constructor(...e) {
 		super(...e), this.compact = !1;
 	}
@@ -15,24 +15,23 @@ var l = class extends n {
 		this.styles = [super.styles, i];
 	}
 	render() {
-		let e = this.compact && typeof this.label == "string" ? this.label : o;
 		return a`
-      <button part="base" ?compact=${this.compact} aria-label=${e}>
+      <button part="base" ?compact=${this.compact}>
         <u-icon part="icon"
           .lib=${this.lib}
           .name=${this.icon}
           .fallback=${r}
         ></u-icon>
-        <span part="label" ?hidden=${this.compact}>
+        <span part="label" ?compact=${this.compact}>
           ${this.label}
         </span>
       </button>
     `;
 	}
 };
-t([c({
+t([s({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Object)], l.prototype, "compact", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "icon", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "lib", void 0), t([c({ type: String }), e("design:type", Object)], l.prototype, "label", void 0), l = t([s("u-sidebar-button")], l);
+}), 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);
 //#endregion
-export { l as SidebarButton };
+export { c as SidebarButton };

package/dist/components/SidebarButton.styles.js

@@ -55,6 +55,22 @@ var t = e`
     overflow: hidden;
     text-overflow: ellipsis;
   }
+
+  /*
+   * 접힌 상태의 라벨 - 시각적으로만 숨긴다. 접근성 트리에는 남아 항목의 이름이 된다
+   * (hidden 은 트리에서도 빼서 이름 없는 항목을 만들었다). 절대배치라 flex 배치와 gap 에 끼지 않는다.
+   */
+  [part~='label'][compact] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
 `;
 //#endregion
 export { t as styles };

package/dist/components/SidebarGroup.js

@@ -4,11 +4,11 @@ import { StyledElement as n } from "../internals/StyledElement.js";
 import { DEFAULT_NAV_ICON as r } from "../internals/nav-icon.js";
 import { SidebarLink as i } from "./SidebarLink.js";
 import { styles as a } from "./SidebarGroup.styles.js";
-import { html as o, nothing as s } from "lit";
-import { customElement as c, property as l } from "lit/decorators.js";
+import { html as o } from "lit";
+import { customElement as s, property as c } from "lit/decorators.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
 //#region src/components/SidebarGroup.ts
-var u = class extends n {
+var l = class extends n {
 	constructor(...e) {
 		super(...e), this.compact = !1, this.selected = !1, this.collapsed = !0, this.handleButtonClick = (e) => {
 			this.compact ? ((this.shadowRoot?.querySelector("slot")?.assignedElements({ flatten: !0 }).find((e) => e instanceof i))?.renderRoot.querySelector("u-link"))?.click() : this.collapsed = !this.collapsed;
@@ -18,12 +18,10 @@ var u = class extends n {
 		this.styles = [super.styles, a];
 	}
 	render() {
-		let e = this.compact && typeof this.label == "string" ? this.label : s;
 		return o`
       <button part="header"
         ?compact=${this.compact}
         ?selected=${this.selected}
-        aria-label=${e}
         @click=${this.handleButtonClick}>
         <!--
           ⚠ ?hidden 을 걸지 않는다. 접힌 상태에서는 라벨과 캐럿이 모두 숨으므로,
@@ -36,7 +34,7 @@ var u = class extends n {
           .name=${this.icon}
           .fallback=${r}
         ></u-icon>
-        <span class="label" part="label" ?hidden=${this.compact}>
+        <span class="label" part="label" ?compact=${this.compact}>
           ${this.label}
         </span>
         <u-icon class="caret" part="caret" ?hidden=${this.compact}
@@ -53,15 +51,15 @@ var u = class extends n {
     `;
 	}
 };
-t([l({
+t([c({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Boolean)], u.prototype, "compact", void 0), t([l({
+}), e("design:type", Boolean)], l.prototype, "compact", void 0), t([c({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Boolean)], u.prototype, "selected", void 0), t([l({
+}), e("design:type", Boolean)], l.prototype, "selected", void 0), t([c({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Boolean)], u.prototype, "collapsed", 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), u = t([c("u-sidebar-group")], u);
+}), e("design:type", Boolean)], l.prototype, "collapsed", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "icon", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "lib", void 0), t([c({ type: String }), e("design:type", Object)], l.prototype, "label", void 0), l = t([s("u-sidebar-group")], l);
 //#endregion
-export { u as SidebarGroup };
+export { l as SidebarGroup };

package/dist/components/SidebarGroup.styles.js

@@ -93,6 +93,22 @@ var t = e`
     height: 0;
     opacity: 0;
   }
+
+  /*
+   * 접힌 상태의 라벨 - 시각적으로만 숨긴다. 접근성 트리에는 남아 항목의 이름이 된다
+   * (hidden 은 트리에서도 빼서 이름 없는 항목을 만들었다). 절대배치라 flex 배치와 gap 에 끼지 않는다.
+   */
+  [part~='label'][compact] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
 `;
 //#endregion
 export { t as styles };

package/dist/components/SidebarLink.js

@@ -15,14 +15,12 @@ var l = class extends n {
 		this.styles = [super.styles, i];
 	}
 	render() {
-		let e = this.compact && typeof this.label == "string" ? this.label : o;
 		return a`
       <u-link
         .href=${this.href || "#"}
         .navigate=${this.navigate}
         .target=${this.target}
         aria-current=${this.selected ? "page" : o}
-        aria-label=${e}
       >
         <div class="container" part="base" ?compact=${this.compact}>
           <u-icon part="icon"
@@ -30,7 +28,7 @@ var l = class extends n {
             .name=${this.icon}
             .fallback=${r}
           ></u-icon>
-          <span part="label" ?hidden=${this.compact}>
+          <span part="label" ?compact=${this.compact}>
             ${this.label}
           </span>
         </div>

package/dist/components/SidebarLink.styles.js

@@ -69,6 +69,22 @@ var t = e`
     overflow: hidden;
     text-overflow: ellipsis;
   }
+
+  /*
+   * 접힌 상태의 라벨 - 시각적으로만 숨긴다. 접근성 트리에는 남아 항목의 이름이 된다
+   * (hidden 은 트리에서도 빼서 이름 없는 항목을 만들었다). 절대배치라 flex 배치와 gap 에 끼지 않는다.
+   */
+  [part~='label'][compact] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
 `;
 //#endregion
 export { t as styles };

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { ActionBar } from './components/ActionBar.js';
 export { MasterDetailLayout } from './components/MasterDetailLayout.js';
 export { Wizard } from './components/Wizard.js';
 export type { WizardStep, WizardStepState, WizardStepChangeDetail } from './components/Wizard.js';
+export { translate } from './translate.js';
 export { registerLocale, setDefaultLocale, getLocaleStrings, getDefaultLocale, } from './internals/locale.js';
 export type { ModernAppLocaleStrings } from './internals/locale.js';
 export { ScreenObserver } from './internals/ScreenObserver.js';

package/dist/index.js

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

package/dist/translate.d.ts

@@ -0,0 +1,39 @@
+import { AsyncDirective } from 'lit/async-directive.js';
+import { TOptions } from 'i18next';
+/**
+ * `app.load({ i18n })` 가 초기화하는 i18next 에 붙는 반응형 번역 디렉티브.
+ *
+ * ★**왜 이 패키지가 갖는가**: i18next 를 초기화하고(`app.load`) 노출하는(`app.i18n`) 것이 이미 이
+ *   패키지이고, 셸 설정의 `label` 은 `string | DirectiveResult` 로 **디렉티브를 받도록** 설계돼 있다.
+ *   그런데 그 디렉티브가 없어서 소비자는 서드파티를 따로 들여와야 했다 — 이미 소유한 개념의
+ *   프리미티브를 내놓지 않은 자리다.
+ *
+ * ★**구독은 Lit 의 연결 수명 주기로 관리한다** — `disconnected()` 에서 풀고 `reconnected()` 에서 다시
+ *   붙으며 그 사이의 변경을 따라잡는다. 주기적으로 끊긴 파트를 훑는 레지스트리가 필요 없다.
+ *
+ * 갱신 계기는 셋이다: 언어 변경 · 나중에 도착한 리소스(백엔드가 네임스페이스를 늦게 싣는 경우) ·
+ * 초기화 완료(셸 설정은 초기화 **전에** 만들어진다 — 그때는 빈 문자열을 그린다. 키를 그리면
+ * 번역 전 키가 화면에 잠깐 비친다).
+ *
+ * @example
+ * ```ts
+ * import { translate } from '@iyulab/modern-app';
+ * html`<h1>${translate('common::title')}</h1>`;
+ * app.load({ layout: { type: 'sidebar', main: [{ type: 'link', label: translate('nav::home'), href: '/' }] } });
+ * ```
+ */
+declare class TranslateDirective extends AsyncDirective {
+    private keys;
+    private options?;
+    private subscribed;
+    render(keys: string | string[], options?: TOptions): string;
+    protected disconnected(): void;
+    protected reconnected(): void;
+    private translate;
+    private readonly refresh;
+    private subscribe;
+    private unsubscribe;
+}
+/** 현재 언어의 번역을 그리고, 언어·리소스가 바뀌면 그 자리를 다시 그린다. */
+export declare const translate: (keys: string | string[], options?: TOptions | undefined) => import('lit-html/directive.js').DirectiveResult<typeof TranslateDirective>;
+export {};

package/dist/translate.js

@@ -0,0 +1,31 @@
+import e from "i18next";
+import { AsyncDirective as t, directive as n } from "lit/async-directive.js";
+var r = n(class extends t {
+	constructor(...e) {
+		super(...e), this.keys = "", this.subscribed = !1, this.refresh = () => {
+			this.setValue(this.translate());
+		};
+	}
+	render(e, t) {
+		return this.keys = e, this.options = t, this.isConnected && this.subscribe(), this.translate();
+	}
+	disconnected() {
+		this.unsubscribe();
+	}
+	reconnected() {
+		this.subscribe(), this.refresh();
+	}
+	translate() {
+		if (!e.isInitialized) return "";
+		let t = e.t(this.keys, this.options);
+		return typeof t == "string" ? t : "";
+	}
+	subscribe() {
+		this.subscribed || (this.subscribed = !0, e.on("languageChanged", this.refresh), e.on("initialized", this.refresh), e.store?.on("added", this.refresh));
+	}
+	unsubscribe() {
+		this.subscribed && (this.subscribed = !1, e.off("languageChanged", this.refresh), e.off("initialized", this.refresh), e.store?.off("added", this.refresh));
+	}
+});
+//#endregion
+export { r as translate };

package/package.json

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

package/skills/modern-app/SKILL.md

@@ -131,11 +131,14 @@ await app.load({
 app.i18n.t('namespace::key');
 ```
 
-Use in Lit templates with `lit-i18n`:
+Use in Lit templates — and as a sidebar item `label` — with the `translate()` directive. It
+re-renders when the language changes or resources arrive, and renders an empty string until i18next
+is initialized:
 
 ```typescript
-import { translate } from 'lit-i18n';
+import { translate } from '@iyulab/modern-app';
 html`<p>${translate('namespace::greeting')}</p>`;
+// layout: { main: [{ type: 'link', label: translate('nav::home'), href: '/' }] }
 ```
 
 ---