@molecule/app-sidebar-layout-angular 0.0.1-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +434 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,441 @@
1
+ <!--
2
+ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
+ Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
+ Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
+ To change this document, edit the module-level JSDoc in src/index.ts.
6
+ Generated: 2026-11-21T12:47:19.070Z
7
+ -->
8
+
1
9
  # @molecule/app-sidebar-layout-angular
2
10
 
3
- Vertical sidebar app shell: brand block + vertical NavLinks + user-menu slot, with a router outlet for nested routes
11
+ Angular vertical sidebar app shell layout — the counterpart of
12
+ `@molecule/app-sidebar-layout-react`: the same props and the same DOM for the
13
+ same input.
14
+
15
+ Exports `<SidebarLayout>` plus the `SidebarLayoutProps` and `SidebarNavItem`
16
+ types — fixed-width left sidebar with brand link, vertical nav links, and
17
+ bottom user-menu / theme-toggle slots; the main area on the right scrolls and
18
+ renders the routed page.
19
+
20
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
21
+ > It is written to be read by coding agents as much as by people, and is generated from this
22
+ > package's source — edit `src/index.ts` JSDoc, not this file.
23
+
24
+ ## Quick Start
25
+
26
+ ```ts
27
+ import { Component } from '@angular/core'
28
+ import { SidebarLayout } from '@molecule/app-sidebar-layout-angular'
29
+
30
+ const NAV = [
31
+ { key: 'dashboard', to: '/dashboard', icon: 'dashboard', label: 'Dashboard' },
32
+ { key: 'projects', to: '/projects', icon: 'folder', label: 'Projects' },
33
+ { key: 'settings', to: '/settings', icon: 'settings', label: 'Settings' },
34
+ ]
35
+
36
+ @Component({
37
+ selector: 'app-shell',
38
+ standalone: true,
39
+ imports: [SidebarLayout],
40
+ template: `
41
+ <div mol-sidebar-layout [appName]="'Acme App'" [navItems]="NAV">
42
+ <app-user-menu slot="userMenu" />
43
+ <router-outlet />
44
+ </div>
45
+ `,
46
+ })
47
+ export class Shell {
48
+ readonly NAV = NAV
49
+ }
50
+ ```
51
+
52
+ ## Type
53
+
54
+ `feature`
55
+
56
+ ## Installation
57
+
58
+ ```bash
59
+ npm install @molecule/app-sidebar-layout-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-ui @molecule/app-ui-angular
60
+ ```
61
+
62
+ ## API
63
+
64
+ ### Interfaces
65
+
66
+ #### `SidebarNavItem`
67
+
68
+ Describes a single item in the sidebar's vertical navigation list.
4
69
 
70
+ ```typescript
71
+ interface SidebarNavItem {
72
+ /** Route path the link goes to. */
73
+ to: string
74
+ /** Stable key — used for list tracking and i18n key suffix. */
75
+ key: string
76
+ /** Material symbol icon name. */
77
+ icon?: string
78
+ /** Visible label. Apps that route this through `t(...)` should pass the resolved string. */
79
+ label: string
80
+ }
5
81
  ```
6
- npm install @molecule/app-sidebar-layout-angular
82
+
83
+ #### `SidebarLayoutProps`
84
+
85
+ Props accepted by {@link SidebarLayout} — the same props
86
+ `@molecule/app-sidebar-layout-react` accepts. Node props (`userMenu`,
87
+ `themeToggle`, `children`) are projected content in Angular (an input cannot
88
+ carry a node), so they are typed `unknown`: pass them in the host template,
89
+ not as values.
90
+
91
+ ```typescript
92
+ interface SidebarLayoutProps {
93
+ /** Brand text shown at the top of the sidebar (typically the app name). */
94
+ appName: string
95
+ /** Path the brand link navigates to. Defaults to `'/'`. */
96
+ logoTo?: string
97
+ /** Vertical nav items rendered in the sidebar. */
98
+ navItems: ReadonlyArray<SidebarNavItem>
99
+ /** Bottom slot (typically a user menu), projected as `[slot=userMenu]` content. */
100
+ userMenu?: unknown
101
+ /** Optional slot next to the user menu, projected as `[slot=themeToggle]` content. */
102
+ themeToggle?: unknown
103
+ /**
104
+ * Aria-label for the primary `<nav>`. Overrides the translated default
105
+ * (`sidebarLayout.aria.primaryNavigation`, English `'Primary navigation'`);
106
+ * prop > `t()` > default.
107
+ */
108
+ navAriaLabel?: string
109
+ /**
110
+ * Sidebar width — a stack-agnostic preset (`'sm'` | `'md'` | `'lg'`) or an
111
+ * exact pixel `number`. Applied via inline style. Defaults to `'md'` (240px).
112
+ */
113
+ sidebarWidth?: SidebarWidth
114
+ /**
115
+ * Legacy sidebar-width prop retained only for backward compatibility: a
116
+ * `w-<n>` value is PARSED to a pixel width and applied via inline style
117
+ * (never re-emitted as a class). `sidebarWidth` takes precedence.
118
+ *
119
+ * @deprecated Use {@link SidebarLayoutProps.sidebarWidth} instead.
120
+ */
121
+ sidebarWidthClass?: string
122
+ /** Extra classes on the outer wrapper. */
123
+ className?: string
124
+ /** `data-mol-id` for AI-agent selectors. */
125
+ dataMolId?: string
126
+ /** The routed page body, projected as the element's default content. */
127
+ children?: unknown
128
+ }
129
+ ```
130
+
131
+ ### Types
132
+
133
+ #### `SidebarWidth`
134
+
135
+ Semantic sidebar width. Mapped to a fixed pixel width internally and applied
136
+ via inline style (a width is one of the "specific values" a styling-agnostic
137
+ ClassMap cannot express as a swappable token) so the sidebar renders the same
138
+ regardless of which ClassMap bond is active — no Tailwind width utility leaks
139
+ into consumer code.
140
+
141
+ - `sm` → 208px, `md` → 240px (default), `lg` → 256px.
142
+ - Pass a raw `number` for an exact pixel width.
143
+
144
+ ```typescript
145
+ type SidebarWidth = 'sm' | 'md' | 'lg' | number
146
+ ```
147
+
148
+ ### Classes
149
+
150
+ #### `SidebarLayout`
151
+
152
+ SidebarLayout component.
153
+
154
+ Fixed-width left sidebar with brand link + vertical router links + bottom
155
+ user-menu / theme-toggle slots, and the `<main>` holding the routed page
156
+ body. The host IS the outer `<div>` (`div[mol-sidebar-layout]`), matching
157
+ React's root exactly. The page body is projected as the element's default
158
+ content (React renders its router's `<Outlet />` in the `<main>`); the bottom
159
+ slots are projected as `[slot=userMenu]` / `[slot=themeToggle]` content.
160
+
161
+ The sidebar WIDTH is the one value a styling-agnostic ClassMap can't express,
162
+ so it is applied via inline style from `sidebarWidth`; active-nav
163
+ highlighting picks the longest prefix-match of the current path, and
164
+ same-path links get a `#top` fragment appended. `label` is rendered as-is:
165
+ pass an already-translated string.
166
+
167
+ ```typescript
168
+ @Component({
169
+ selector: 'div[mol-sidebar-layout]',
170
+ standalone: true,
171
+ imports: [Link],
172
+ inputs: [
173
+ 'appName',
174
+ 'logoTo',
175
+ 'navItems',
176
+ 'navAriaLabel',
177
+ 'sidebarWidth',
178
+ 'sidebarWidthClass',
179
+ 'className',
180
+ 'dataMolId',
181
+ ],
182
+ host: {
183
+ '[class]': 'classes()',
184
+ '[attr.data-mol-id]': 'dataMolId ?? null',
185
+ },
186
+ // prettier-ignore
187
+ template: `<aside [class]="asideClasses()" [style.width.px]="widthPx()"><a [molLink]="logoPath()" [class]="brandClasses()">{{ appName }}</a><nav [class]="navClasses()" [attr.aria-label]="navLabel()">@for (item of navItems; track item.key) {<a [molLink]="itemPath(item)" [attr.data-mol-id]="'nav-' + item.key" [attr.aria-current]="isActive(item) ? 'page' : null" [class]="itemClasses(item)">@if (item.icon) {<span [class]="iconClasses()" aria-hidden="true">{{ item.icon }}</span>}<span>{{ item.label }}</span></a>}</nav><div #bottom [class]="bottomClasses()"><span #placeholder aria-hidden="true"></span><span #userSlot data-parity-unwrap style="display: contents"><ng-content select="[slot=userMenu]"></ng-content></span><span #themeSlot data-parity-unwrap style="display: contents"><ng-content select="[slot=themeToggle]"></ng-content></span></div></aside><main [class]="mainClasses()" [style.min-width.px]="0"><ng-content></ng-content></main>`,
188
+ })
189
+ export class SidebarLayout implements AfterViewInit, AfterViewChecked, DoCheck, OnDestroy {
190
+ /** Brand text shown at the top of the sidebar (typically the app name). */
191
+ appName = ''
192
+ /** Path the brand link navigates to (defaults to `'/'` at read time). */
193
+ logoTo?: string
194
+ /** Vertical nav items rendered in the sidebar. */
195
+ navItems: ReadonlyArray<SidebarNavItem> = []
196
+ /** Aria-label for the primary `<nav>`. */
197
+ navAriaLabel?: string
198
+ /** Sidebar width preset or explicit pixel number (defaults to `'md'` at read time). */
199
+ sidebarWidth?: string | number
200
+ /** Deprecated Tailwind width utility, parsed to pixels (never emitted as a class). */
201
+ sidebarWidthClass?: string
202
+ /** Extra classes on the outer wrapper. */
203
+ className?: string
204
+ /** `data-mol-id` for AI-agent selectors. */
205
+ dataMolId?: string
206
+
207
+ /** The projected bottom-slot container (detached when both slots are absent). */
208
+ @ViewChild('bottom') private bottom?: ElementRef<HTMLElement>
209
+ /** The placeholder `<span>` React renders while the user menu is absent. */
210
+ @ViewChild('placeholder') private placeholder?: ElementRef<HTMLElement>
211
+ /** The `[slot=userMenu]` projection capture point. */
212
+ @ViewChild('userSlot') private userSlot?: ElementRef<HTMLElement>
213
+ /** The `[slot=themeToggle]` projection capture point. */
214
+ @ViewChild('themeSlot') private themeSlot?: ElementRef<HTMLElement>
215
+
216
+ private readonly router = useRouterInstance()
217
+
218
+ private readonly i18n = useTranslation()
219
+
220
+ /** The current location, kept current so active items follow navigation. */
221
+ private readonly location = signal(this.router.getLocation())
222
+
223
+ private readonly stop = this.router.subscribe(() => this.location.set(this.router.getLocation()))
224
+
225
+ private readonly guard = new SlotGuard(inject(Renderer2))
226
+
227
+ /** Stops listening to the router when the component goes away. */
228
+ ngOnDestroy(): void {
229
+ this.stop()
230
+ }
231
+
232
+ /**
233
+ * The current class map.
234
+ * @returns The UIClassMap.
235
+ */
236
+ cm(): UIClassMap {
237
+ return getClassMap()
238
+ }
239
+
240
+ /** Computes the wrapper class list. */
241
+ classes(): string {
242
+ return this.cm().cn(this.cm().pageShell, this.cm().page, this.className)
243
+ }
244
+
245
+ /** Computes the sidebar's class list. */
246
+ asideClasses(): string {
247
+ const cm = this.cm()
248
+ return cm.cn(cm.sp('p', 4), cm.shrink0, cm.flex({ direction: 'col' }), cm.surface, cm.borderR)
249
+ }
250
+
251
+ /** The inline sidebar width, in pixels. */
252
+ widthPx(): number {
253
+ return resolveSidebarWidthPx(this.sidebarWidth, this.sidebarWidthClass)
254
+ }
255
+
256
+ /** Computes the brand link class list. */
257
+ brandClasses(): string {
258
+ const cm = this.cm()
259
+ return cm.cn(cm.textSize('xl'), cm.fontWeight('bold'), cm.sp('mb', 6), cm.displayBlock)
260
+ }
261
+
262
+ /** Computes the nav class list. */
263
+ navClasses(): string {
264
+ return this.cm().cn(this.cm().flex1, this.cm().stack(1))
265
+ }
266
+
267
+ /** The nav region's accessible name: an explicit `navAriaLabel` wins, otherwise the translated default (the inline English keeps the DOM identical until a locale… */
268
+ navLabel(): string {
269
+ return (
270
+ this.navAriaLabel ??
271
+ this.i18n.t('sidebarLayout.aria.primaryNavigation', undefined, {
272
+ defaultValue: 'Primary navigation',
273
+ })
274
+ )
275
+ }
276
+
277
+ /**
278
+ * The brand link destination (React's default parameter).
279
+ * @returns The link target.
280
+ */
281
+ logoPath(): string {
282
+ return this.samePathTarget(this.logoTo ?? '/')
283
+ }
284
+
285
+ /** One nav item's link destination. */
286
+ itemPath(item: SidebarNavItem): string {
287
+ return this.samePathTarget(item.to)
288
+ }
289
+
290
+ /** Computes the icon span class list. */
291
+ iconClasses(): string {
292
+ return this.cm().cn(this.cm().iconGlyphFont)
293
+ }
294
+
295
+ /**
296
+ * Computes the bottom-slot container class list.
297
+ * @returns The class string.
298
+ */
299
+ bottomClasses(): string {
300
+ const cm = this.cm()
301
+ return cm.cn(
302
+ cm.sp('pt', 4),
303
+ cm.flex({ align: 'center', justify: 'between', gap: 'sm' }),
304
+ cm.borderT,
305
+ )
306
+ }
307
+
308
+ /**
309
+ * Computes the main content area class list.
310
+ * @returns The class string.
311
+ */
312
+ mainClasses(): string {
313
+ return this.cm().cn(this.cm().pageShellContent)
314
+ }
315
+
316
+ /** The key of the nav item whose `to` is the longest prefix-match of the current pathname. */
317
+ activeKey(): string | null {
318
+ const pathname = this.location().pathname
319
+ return this.navItems.reduce<string | null>((bestKey, item) => {
320
+ const isMatch = pathname === item.to || pathname.startsWith(`${item.to}/`)
321
+ if (!isMatch) return bestKey
322
+ if (bestKey === null) return item.key
323
+ const best = this.navItems.find((i) => i.key === bestKey)
324
+ return best && item.to.length > best.to.length ? item.key : bestKey
325
+ }, null)
326
+ }
327
+
328
+ /** Whether one nav item is the active one at the current location. */
329
+ isActive(item: SidebarNavItem): boolean {
330
+ return item.key === this.activeKey()
331
+ }
332
+
333
+ /** Computes the class list of one nav link: the shared nav-item treatment plus the active or idle variant. */
334
+ itemClasses(item: SidebarNavItem): string {
335
+ const cm = this.cm()
336
+ return cm.cn(
337
+ cm.flex({ align: 'center', gap: 'sm' }),
338
+ cm.sp('px', 3),
339
+ cm.sp('py', 2),
340
+ cm.textSize('sm'),
341
+ cm.fontWeight('medium'),
342
+ cm.roundedFull,
343
+ this.isActive(item)
344
+ ? cm.cn(cm.bgPrimaryContainer, cm.textOnPrimaryContainer)
345
+ : cm.cn(cm.textMuted, cm.link),
346
+ )
347
+ }
348
+
349
+ /** Appends `#top` when `to` is the current path, so a same-route click still produces an observable URL change. */
350
+ private samePathTarget(to: string): string {
351
+ const pathname = this.location().pathname
352
+ const samePath = pathname === to || pathname + '/' === to
353
+ if (!samePath) return to
354
+ return `${to.replace(/\/$/, '') || '/'}#top`
355
+ }
356
+
357
+ /**
358
+ * Reconciles the projected bottom slots against React's branch once the view
359
+ * queries resolve.
360
+ */
361
+ ngAfterViewInit(): void {
362
+ this.reconcile()
363
+ }
364
+
365
+ /**
366
+ * Re-reconciles on later passes, so a change to the projected content swaps
367
+ * the branch the way React does.
368
+ */
369
+ ngDoCheck(): void {
370
+ this.reconcile()
371
+ }
372
+
373
+ /** Re-reconciles after each view update. */
374
+ ngAfterViewChecked(): void {
375
+ this.reconcile()
376
+ }
377
+
378
+ /** Applies React's condition: the bottom container renders only when a slot exists, and the placeholder `<span>` renders only while the user menu is absent and th… */
379
+ private reconcile(): void {
380
+ const user = this.userSlot?.nativeElement
381
+ const theme = this.themeSlot?.nativeElement
382
+ const hasUser = hasNodes(user)
383
+ const hasTheme = hasNodes(theme)
384
+ this.guard.toggle(this.bottom?.nativeElement, hasUser || hasTheme)
385
+ this.guard.toggle(this.placeholder?.nativeElement, !hasUser && hasTheme)
386
+ }
387
+ }
7
388
  ```
8
389
 
9
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
390
+ _(The 14 longest member comments are shortened to their first sentence to fit; the full declaration is in `node_modules/@molecule/app-sidebar-layout-angular/dist/sidebar-layout.component.d.ts`.)_
391
+
392
+ ## Injection Notes
393
+
394
+ ### Requirements
395
+
396
+ Peer dependencies:
397
+
398
+ - `@angular/common` ^22.0.0
399
+ - `@angular/core` ^22.0.0
400
+ - `@angular/platform-browser` ^22.0.0
401
+ - `@molecule/app-angular` ^3.6.0
402
+ - `@molecule/app-ui` ^1.3.11
403
+ - `@molecule/app-ui-angular` ^1.1.0
404
+
405
+ ### Runtime Dependencies
406
+
407
+ - `@angular/common`
408
+ - `@angular/core`
409
+ - `@angular/platform-browser`
410
+ - `@molecule/app-angular`
411
+ - `@molecule/app-ui`
412
+ - `@molecule/app-ui-angular`
413
+
414
+ - Router required: reads the current location and renders router links, so
415
+ it must be mounted inside the molecule router provider (the app shell
416
+ does that at startup).
417
+ - Node props are projected content: the bottom slots are selected by
418
+ `[slot=userMenu]` / `[slot=themeToggle]`, everything else lands in the main
419
+ container as the default projection (React's `<Outlet />`).
420
+ - Fully ClassMap-driven: every layout/surface/border/text/state class is
421
+ resolved through `getClassMap()` (`cm.pageShell`, `cm.page`, `cm.surface`,
422
+ `cm.borderR`, …), so swapping the ClassMap bond restyles the whole shell.
423
+ The sidebar WIDTH is applied via inline style from `sidebarWidth`
424
+ (`'sm'`|`'md'`|`'lg'`|pixel `number`); the old `sidebarWidthClass` prop is
425
+ `@deprecated` — parsed to pixels, never re-emitted as a class.
426
+ - `icon` values are Material Symbols ligature names rendered with the
427
+ `material-symbols-outlined` font class — the one documented icon-font
428
+ exception. Without the font loaded, the raw icon name shows as text.
429
+ - Active-nav highlighting picks the longest prefix-match of the current
430
+ path; same-path links get a `#top` fragment appended.
431
+ - `navAriaLabel` overrides the translated nav region name; without it the
432
+ label comes from `t('sidebarLayout.aria.primaryNavigation')` (English
433
+ default `'Primary navigation'`), so it follows a locale switch through its
434
+ companion locale bond (`@molecule/app-locales-sidebar-layout`). Nav item
435
+ `label`s stay plain caller strings — translate them upstream.
436
+ - Requires a bonded ClassMap. Sibling: `@molecule/app-shell-layout-angular`
437
+ is the top header/footer shell (router-free).
438
+
439
+ ## Translations
10
440
 
11
- License: Apache-2.0
441
+ Translation strings are provided by `@molecule/app-locales-sidebar-layout`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-sidebar-layout-angular",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Vertical sidebar app shell: brand block + vertical NavLinks + user-menu slot, with a router outlet for nested routes",
5
5
  "homepage": "https://www.molecule.dev/packages/app-sidebar-layout-angular",
6
6
  "type": "module",
@@ -56,12 +56,12 @@
56
56
  "@angular/compiler-cli": "22.2.3",
57
57
  "@angular/core": "22.2.3",
58
58
  "@angular/platform-browser": "22.2.3",
59
- "@molecule/app-angular": "3.7.2",
59
+ "@molecule/app-angular": "3.9.0",
60
60
  "@molecule/app-framework-conformance": "0.0.0",
61
61
  "@molecule/app-i18n": "1.2.2",
62
62
  "@molecule/app-icons": "1.0.4",
63
- "@molecule/app-ui": "1.4.0",
64
- "@molecule/app-ui-angular": "1.2.1",
63
+ "@molecule/app-ui": "1.5.0",
64
+ "@molecule/app-ui-angular": "1.3.1",
65
65
  "@types/node": "26.6.5",
66
66
  "jsdom": "30.1.3",
67
67
  "rxjs": "7.8.2",