@molecule/app-settings-container-angular 0.0.0-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.
- package/LICENSE +202 -0
- package/README.md +747 -2
- package/dist/index.d.ts +87 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +87 -0
- package/dist/index.js.map +1 -0
- package/dist/settings-content.component.d.ts +27 -0
- package/dist/settings-content.component.d.ts.map +1 -0
- package/dist/settings-content.component.js +56 -0
- package/dist/settings-content.component.js.map +1 -0
- package/dist/settings-layout.component.d.ts +59 -0
- package/dist/settings-layout.component.d.ts.map +1 -0
- package/dist/settings-layout.component.js +128 -0
- package/dist/settings-layout.component.js.map +1 -0
- package/dist/settings-section.component.d.ts +130 -0
- package/dist/settings-section.component.d.ts.map +1 -0
- package/dist/settings-section.component.js +303 -0
- package/dist/settings-section.component.js.map +1 -0
- package/dist/settings-sidebar.component.d.ts +110 -0
- package/dist/settings-sidebar.component.d.ts.map +1 -0
- package/dist/settings-sidebar.component.js +270 -0
- package/dist/settings-sidebar.component.js.map +1 -0
- package/dist/slots.d.ts +45 -0
- package/dist/slots.d.ts.map +1 -0
- package/dist/slots.js +55 -0
- package/dist/slots.js.map +1 -0
- package/dist/types.d.ts +89 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +8 -0
- package/dist/types.js.map +1 -0
- package/package.json +69 -4
package/README.md
CHANGED
|
@@ -1,3 +1,748 @@
|
|
|
1
|
-
|
|
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:15.867Z
|
|
7
|
+
-->
|
|
2
8
|
|
|
3
|
-
|
|
9
|
+
# @molecule/app-settings-container-angular
|
|
10
|
+
|
|
11
|
+
Angular Settings-page scaffold (layout chrome only) — the counterpart of
|
|
12
|
+
`@molecule/app-settings-container-react`: the same props and the same DOM
|
|
13
|
+
for the same input.
|
|
14
|
+
|
|
15
|
+
Exports:
|
|
16
|
+
|
|
17
|
+
- `<SettingsLayout>` (`div[mol-settings-layout]`) — two-column [sidebar,
|
|
18
|
+
content] with an optional `[slot=header]` above both.
|
|
19
|
+
- `<SettingsSidebar>` (`nav[mol-settings-sidebar]`) — controlled side-nav
|
|
20
|
+
(`items`, `activeId`, `onSelect`, optional `[slot=footer]`).
|
|
21
|
+
- `<SettingsContent>` (`div[mol-settings-content]`) — stacked wrapper for
|
|
22
|
+
the right column.
|
|
23
|
+
- `<SettingsSection>` (`div[mol-settings-section]`) — Card-wrapped titled
|
|
24
|
+
section (`[slot=title]`, `[slot=description]`, body and
|
|
25
|
+
`[slot=footer]`).
|
|
26
|
+
|
|
27
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
28
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
29
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import { Component } from '@angular/core'
|
|
35
|
+
import {
|
|
36
|
+
SettingsContent,
|
|
37
|
+
SettingsLayout,
|
|
38
|
+
SettingsSection,
|
|
39
|
+
SettingsSidebar,
|
|
40
|
+
} from '@molecule/app-settings-container-angular'
|
|
41
|
+
|
|
42
|
+
@Component({
|
|
43
|
+
selector: 'app-settings-page',
|
|
44
|
+
standalone: true,
|
|
45
|
+
imports: [SettingsLayout, SettingsSidebar, SettingsContent, SettingsSection],
|
|
46
|
+
template: `
|
|
47
|
+
<div mol-settings-layout [dataMolId]="'settings'">
|
|
48
|
+
<h1 slot="header">Settings</h1>
|
|
49
|
+
<nav
|
|
50
|
+
slot="sidebar"
|
|
51
|
+
mol-settings-sidebar
|
|
52
|
+
[items]="nav"
|
|
53
|
+
[activeId]="active"
|
|
54
|
+
[onSelect]="select.bind(this)"
|
|
55
|
+
></nav>
|
|
56
|
+
<div mol-settings-content>
|
|
57
|
+
<div mol-settings-section>
|
|
58
|
+
<strong slot="title">Profile</strong>
|
|
59
|
+
<em slot="description">Update your display name and avatar.</em>
|
|
60
|
+
<p>Form fields go here.</p>
|
|
61
|
+
</div>
|
|
62
|
+
</div>
|
|
63
|
+
</div>
|
|
64
|
+
`,
|
|
65
|
+
})
|
|
66
|
+
export class SettingsPage {
|
|
67
|
+
active = 'profile'
|
|
68
|
+
nav = [
|
|
69
|
+
{ id: 'profile', label: 'Profile' },
|
|
70
|
+
{ id: 'notifications', label: 'Notifications' },
|
|
71
|
+
]
|
|
72
|
+
|
|
73
|
+
select(id: string): void {
|
|
74
|
+
this.active = id
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Type
|
|
80
|
+
|
|
81
|
+
`feature`
|
|
82
|
+
|
|
83
|
+
## Installation
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
npm install @molecule/app-settings-container-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-ui @molecule/app-ui-angular
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## API
|
|
90
|
+
|
|
91
|
+
### Interfaces
|
|
92
|
+
|
|
93
|
+
#### `SettingsLayoutProps`
|
|
94
|
+
|
|
95
|
+
Props accepted by the settings layout — the same props
|
|
96
|
+
`@molecule/app-settings-container-react`'s `SettingsLayout` accepts.
|
|
97
|
+
Node props (`sidebar`, `header`, `children`) are projected content in
|
|
98
|
+
Angular (an input cannot carry a node), so they are typed `unknown`: pass
|
|
99
|
+
them in the host template as `[slot=sidebar]`, `[slot=header]` and default
|
|
100
|
+
content.
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
interface SettingsLayoutProps {
|
|
104
|
+
/** Left-side navigation, projected as `[slot=sidebar]` content. */
|
|
105
|
+
sidebar?: unknown
|
|
106
|
+
/** Main content area, projected as the element's default content. */
|
|
107
|
+
children?: unknown
|
|
108
|
+
/** Optional header, projected as `[slot=header]` content. */
|
|
109
|
+
header?: unknown
|
|
110
|
+
/** Extra classes on the outer wrapper. */
|
|
111
|
+
className?: string
|
|
112
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
113
|
+
dataMolId?: string
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
#### `SettingsContentProps`
|
|
118
|
+
|
|
119
|
+
Props accepted by the content wrapper — the same props React's
|
|
120
|
+
`SettingsContent` accepts. Its only node prop (`children`) is projected
|
|
121
|
+
default content.
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
interface SettingsContentProps {
|
|
125
|
+
/** Active section content, projected as the element's default content. */
|
|
126
|
+
children?: unknown
|
|
127
|
+
/** Extra classes. */
|
|
128
|
+
className?: string
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
#### `SettingsSidebarItem`
|
|
133
|
+
|
|
134
|
+
A single navigable item in the settings sidebar.
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
137
|
+
interface SettingsSidebarItem {
|
|
138
|
+
/** Unique id; the active item is the one whose id equals `activeId`. */
|
|
139
|
+
id: string
|
|
140
|
+
/** Visible label — a projected node template, or plain text. */
|
|
141
|
+
label: unknown
|
|
142
|
+
/** Optional leading icon — a projected node template, or plain text. */
|
|
143
|
+
icon?: unknown
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
#### `SettingsSidebarProps`
|
|
148
|
+
|
|
149
|
+
Props accepted by the settings sidebar — the same props React's
|
|
150
|
+
`SettingsSidebar` accepts. `footer` is projected as `[slot=footer]`
|
|
151
|
+
content, or passed as text.
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
interface SettingsSidebarProps {
|
|
155
|
+
/** Items to render, in order. */
|
|
156
|
+
items: SettingsSidebarItem[]
|
|
157
|
+
/** The id of the active item (controlled — the caller owns it). */
|
|
158
|
+
activeId: string
|
|
159
|
+
/** Called with the clicked item's id. */
|
|
160
|
+
onSelect: (id: string) => void
|
|
161
|
+
/** Optional footer, projected as `[slot=footer]` content or passed as text. */
|
|
162
|
+
footer?: unknown
|
|
163
|
+
/**
|
|
164
|
+
* Accessible name for the `<nav>` region. Overrides the translated /
|
|
165
|
+
* `defaultValue` `'Settings'` (prop > `t()` > default).
|
|
166
|
+
*/
|
|
167
|
+
ariaLabel?: string
|
|
168
|
+
/** Extra classes. */
|
|
169
|
+
className?: string
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
#### `SettingsSectionProps`
|
|
174
|
+
|
|
175
|
+
Props accepted by the settings section — the same props React's
|
|
176
|
+
`SettingsSection` accepts. `title`, `description` and `footer` are node
|
|
177
|
+
props: projected content (`[slot=title]`, `[slot=description]`,
|
|
178
|
+
`[slot=footer]`) or plain text.
|
|
179
|
+
|
|
180
|
+
```typescript
|
|
181
|
+
interface SettingsSectionProps {
|
|
182
|
+
/** Section heading — a projected node template, or plain text. */
|
|
183
|
+
title?: unknown
|
|
184
|
+
/** Optional description under the heading — a projected node template, or plain text. */
|
|
185
|
+
description?: unknown
|
|
186
|
+
/** Section body, projected as the element's default content. */
|
|
187
|
+
children?: unknown
|
|
188
|
+
/** Optional footer row — a projected node template, or plain text. */
|
|
189
|
+
footer?: unknown
|
|
190
|
+
/** Extra classes on the Card. */
|
|
191
|
+
className?: string
|
|
192
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
193
|
+
dataMolId?: string
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### Classes
|
|
198
|
+
|
|
199
|
+
#### `SettingsContent`
|
|
200
|
+
|
|
201
|
+
Wrapper for the right-hand column of the settings layout.
|
|
202
|
+
|
|
203
|
+
Just a vertically-stacked container for one or more settings sections —
|
|
204
|
+
useful as a semantic landmark and for consistent spacing. The host IS the
|
|
205
|
+
`<div>` React renders (`div[mol-settings-content]`); its content is
|
|
206
|
+
projected default content.
|
|
207
|
+
|
|
208
|
+
```typescript
|
|
209
|
+
@Component({
|
|
210
|
+
selector: 'div[mol-settings-content]',
|
|
211
|
+
standalone: true,
|
|
212
|
+
inputs: ['className'],
|
|
213
|
+
host: {
|
|
214
|
+
'[class]': 'classes()',
|
|
215
|
+
},
|
|
216
|
+
template: `<ng-content></ng-content>`,
|
|
217
|
+
})
|
|
218
|
+
export class SettingsContent {
|
|
219
|
+
/** Extra classes. */
|
|
220
|
+
className?: string
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* The current class map.
|
|
224
|
+
* @returns The UIClassMap.
|
|
225
|
+
*/
|
|
226
|
+
cm(): UIClassMap {
|
|
227
|
+
return getClassMap()
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/**
|
|
231
|
+
* The wrapper's class list (React's `cm.cn(cm.stack(6), className)`).
|
|
232
|
+
* @returns The class string.
|
|
233
|
+
*/
|
|
234
|
+
classes(): string {
|
|
235
|
+
return this.cm().cn(this.cm().stack(6), this.className)
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
#### `SettingsLayout`
|
|
241
|
+
|
|
242
|
+
Two-column settings-page scaffold.
|
|
243
|
+
|
|
244
|
+
Sidebar on the left, content on the right, optional (non-sticky) header
|
|
245
|
+
above both. The host IS the outer `<div>` (`div[mol-settings-layout]`),
|
|
246
|
+
matching React's root exactly. Node props are projected content:
|
|
247
|
+
`[slot=header]` lands above the columns, `[slot=sidebar]` inside the
|
|
248
|
+
`<aside>`, and everything else in the main content column.
|
|
249
|
+
|
|
250
|
+
```typescript
|
|
251
|
+
@Component({
|
|
252
|
+
selector: 'div[mol-settings-layout]',
|
|
253
|
+
standalone: true,
|
|
254
|
+
imports: [NgTemplateOutlet],
|
|
255
|
+
inputs: ['header', 'className', 'dataMolId'],
|
|
256
|
+
host: {
|
|
257
|
+
'[class]': 'classes()',
|
|
258
|
+
'[attr.data-mol-id]': 'dataMolId ?? null',
|
|
259
|
+
},
|
|
260
|
+
// prettier-ignore
|
|
261
|
+
template: `<ng-content select="[slot=header]"></ng-content>@if (headerTemplate(); as headerTpl) {<ng-container [ngTemplateOutlet]="headerTpl" />}<div [class]="rowClasses()"><aside [class]="asideClasses()"><ng-content select="[slot=sidebar]"></ng-content></aside><main [class]="mainClasses()"><div [class]="contentClasses()"><ng-content></ng-content></div></main></div>`,
|
|
262
|
+
})
|
|
263
|
+
export class SettingsLayout {
|
|
264
|
+
/** Optional header (breadcrumb, title, save button) — a template or projected `[slot=header]` content. */
|
|
265
|
+
header?: unknown
|
|
266
|
+
/** Extra classes on the outer wrapper. */
|
|
267
|
+
className?: string
|
|
268
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
269
|
+
dataMolId?: string
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* The current class map.
|
|
273
|
+
* @returns The UIClassMap.
|
|
274
|
+
*/
|
|
275
|
+
cm(): UIClassMap {
|
|
276
|
+
return getClassMap()
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* The outer wrapper's class list (React's `cm.cn(cm.stack(4), className)`).
|
|
281
|
+
* @returns The class string.
|
|
282
|
+
*/
|
|
283
|
+
classes(): string {
|
|
284
|
+
return this.cm().cn(this.cm().stack(4), this.className)
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/**
|
|
288
|
+
* The header as a template, when the caller passed a node rather than
|
|
289
|
+
* projected content.
|
|
290
|
+
* @returns The header template, or null.
|
|
291
|
+
*/
|
|
292
|
+
headerTemplate(): TemplateRef<unknown> | null {
|
|
293
|
+
return isTemplate(this.header) ? this.header : null
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/**
|
|
297
|
+
* The column row's class (`cm.flex({ align: 'start', gap: 'lg' })`).
|
|
298
|
+
* @returns The class string.
|
|
299
|
+
*/
|
|
300
|
+
rowClasses(): string {
|
|
301
|
+
return this.cm().flex({ align: 'start', gap: 'lg' })
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* The sidebar column's class (`cm.shrink0`).
|
|
306
|
+
* @returns The class string.
|
|
307
|
+
*/
|
|
308
|
+
asideClasses(): string {
|
|
309
|
+
return this.cm().cn(this.cm().shrink0)
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
/**
|
|
313
|
+
* The content column's class (`cm.flex1`).
|
|
314
|
+
* @returns The class string.
|
|
315
|
+
*/
|
|
316
|
+
mainClasses(): string {
|
|
317
|
+
return this.cm().cn(this.cm().flex1)
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/**
|
|
321
|
+
* The content stack's class (`cm.stack(6)`).
|
|
322
|
+
* @returns The class string.
|
|
323
|
+
*/
|
|
324
|
+
contentClasses(): string {
|
|
325
|
+
return this.cm().cn(this.cm().stack(6))
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
#### `SettingsSection`
|
|
331
|
+
|
|
332
|
+
One configuration section inside a settings page.
|
|
333
|
+
|
|
334
|
+
Card-wrapped, with a title / description header, body content and an
|
|
335
|
+
optional footer action row. The host IS the Card `<div>`
|
|
336
|
+
(`div[mol-settings-section]`), matching React's root exactly: the Card's
|
|
337
|
+
`elevated` variant, `md` padding and the callers' `className` /
|
|
338
|
+
`data-mol-id` are the host's. `title`, `description` and `footer` are
|
|
339
|
+
projected content (`[slot=title]`, `[slot=description]`, `[slot=footer]`)
|
|
340
|
+
or plain text; the optional regions render only when React would render
|
|
341
|
+
them.
|
|
342
|
+
|
|
343
|
+
```typescript
|
|
344
|
+
@Component({
|
|
345
|
+
selector: 'div[mol-settings-section]',
|
|
346
|
+
standalone: true,
|
|
347
|
+
imports: [NgTemplateOutlet],
|
|
348
|
+
inputs: ['title', 'description', 'footer', 'className', 'dataMolId'],
|
|
349
|
+
host: {
|
|
350
|
+
'[class]': 'classes()',
|
|
351
|
+
'[attr.data-mol-id]': 'dataMolId ?? null',
|
|
352
|
+
},
|
|
353
|
+
// prettier-ignore
|
|
354
|
+
template: `<div [class]="innerClasses()"><header [class]="headerClasses()"><h2 [class]="titleClasses()">@if (titleTemplate(); as titleTpl) {<ng-container [ngTemplateOutlet]="titleTpl" />}@else if (hasTitleText()) {<ng-container>{{ textOf(title) }}</ng-container>}<ng-content select="[slot=title]"></ng-content></h2>@if (showDescription()) {<p #descriptionEl [class]="descriptionClasses()">@if (descriptionTemplate(); as descriptionTpl) {<ng-container [ngTemplateOutlet]="descriptionTpl" />}@else if (hasDescriptionText()) {<ng-container>{{ textOf(description) }}</ng-container>}<ng-content select="[slot=description]"></ng-content></p>}</header><div><ng-content></ng-content></div>@if (showFooter()) {<footer #footerEl [class]="footerClasses()">@if (footerTemplate(); as footerTpl) {<ng-container [ngTemplateOutlet]="footerTpl" />}@else if (hasFooterText()) {<ng-container>{{ textOf(footer) }}</ng-container>}<ng-content select="[slot=footer]"></ng-content></footer>}</div>`,
|
|
355
|
+
})
|
|
356
|
+
export class SettingsSection implements AfterViewInit {
|
|
357
|
+
/** Section heading — a projected node template, or plain text. */
|
|
358
|
+
title?: unknown
|
|
359
|
+
/** Optional description under the heading — a projected node template, or plain text. */
|
|
360
|
+
description?: unknown
|
|
361
|
+
/** Section body, projected as the element's default content. */
|
|
362
|
+
children?: unknown
|
|
363
|
+
/** Optional footer row — a projected node template, or plain text. */
|
|
364
|
+
footer?: unknown
|
|
365
|
+
/** Extra classes on the Card. */
|
|
366
|
+
className?: string
|
|
367
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
368
|
+
dataMolId?: string
|
|
369
|
+
|
|
370
|
+
/** The optional description paragraph (projected content lands here; read once). */
|
|
371
|
+
@ViewChild('descriptionEl') private descriptionEl?: ElementRef<HTMLElement>
|
|
372
|
+
/** The optional footer row (projected content lands here; read once). */
|
|
373
|
+
@ViewChild('footerEl') private footerEl?: ElementRef<HTMLElement>
|
|
374
|
+
|
|
375
|
+
/** Whether a `[slot=description]` projection landed (`null`: decided by the text input). */
|
|
376
|
+
private readonly descriptionProjected = signal<boolean | null>(true)
|
|
377
|
+
/** Whether a `[slot=footer]` projection landed (`null`: decided by the text input). */
|
|
378
|
+
private readonly footerProjected = signal<boolean | null>(true)
|
|
379
|
+
|
|
380
|
+
/**
|
|
381
|
+
* Reads the optional regions' first render: when neither a text input nor
|
|
382
|
+
* projected content landed, React would not render the region at all, so the
|
|
383
|
+
* optimistic render is withdrawn.
|
|
384
|
+
*/
|
|
385
|
+
ngAfterViewInit(): void {
|
|
386
|
+
this.descriptionProjected.set(
|
|
387
|
+
this.hasDescriptionText() ? null : hasRenderableContent(this.descriptionEl?.nativeElement),
|
|
388
|
+
)
|
|
389
|
+
this.footerProjected.set(
|
|
390
|
+
this.hasFooterText() ? null : hasRenderableContent(this.footerEl?.nativeElement),
|
|
391
|
+
)
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
/**
|
|
395
|
+
* The current class map.
|
|
396
|
+
* @returns The UIClassMap.
|
|
397
|
+
*/
|
|
398
|
+
cm(): UIClassMap {
|
|
399
|
+
return getClassMap()
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* Renders a text value the way React renders a node string.
|
|
404
|
+
* @param value - The prop value.
|
|
405
|
+
* @returns The text to render, or `''` when there is nothing.
|
|
406
|
+
*/
|
|
407
|
+
textOf(value: unknown): string {
|
|
408
|
+
return value === null || value === undefined ? '' : String(value)
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
/**
|
|
412
|
+
* The host's class list — Card's own computation with React's defaults
|
|
413
|
+
* (`elevated` variant, `md` padding) and the caller's `className`.
|
|
414
|
+
* @returns The class string.
|
|
415
|
+
*/
|
|
416
|
+
classes(): string {
|
|
417
|
+
return this.cm().cn(
|
|
418
|
+
this.cm().card({ variant: 'elevated' }),
|
|
419
|
+
this.cm().cardPadding('md'),
|
|
420
|
+
this.className,
|
|
421
|
+
)
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
/**
|
|
425
|
+
* The body stack's class (`cm.stack(4)`).
|
|
426
|
+
* @returns The class string.
|
|
427
|
+
*/
|
|
428
|
+
innerClasses(): string {
|
|
429
|
+
return this.cm().stack(4)
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
/**
|
|
433
|
+
* The header's class (`cm.stack(1)`).
|
|
434
|
+
* @returns The class string.
|
|
435
|
+
*/
|
|
436
|
+
headerClasses(): string {
|
|
437
|
+
return this.cm().stack(1)
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* The title's class list (`cm.cn(cm.textSize('lg'), cm.fontWeight('semibold'))`).
|
|
442
|
+
* @returns The class string.
|
|
443
|
+
*/
|
|
444
|
+
titleClasses(): string {
|
|
445
|
+
return this.cm().cn(this.cm().textSize('lg'), this.cm().fontWeight('semibold'))
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
/**
|
|
449
|
+
* The description's class (`cm.textSize('sm')`).
|
|
450
|
+
* @returns The class string.
|
|
451
|
+
*/
|
|
452
|
+
descriptionClasses(): string {
|
|
453
|
+
return this.cm().textSize('sm')
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
/**
|
|
457
|
+
* The footer row's class (`cm.flex({ justify: 'end', align: 'center', gap: 'sm' })`).
|
|
458
|
+
* @returns The class string.
|
|
459
|
+
*/
|
|
460
|
+
footerClasses(): string {
|
|
461
|
+
return this.cm().flex({ justify: 'end', align: 'center', gap: 'sm' })
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
/**
|
|
465
|
+
* The title as a template, when the caller passed a node.
|
|
466
|
+
* @returns The title template, or null.
|
|
467
|
+
*/
|
|
468
|
+
titleTemplate(): TemplateRef<unknown> | null {
|
|
469
|
+
return isTemplate(this.title) ? this.title : null
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
/**
|
|
473
|
+
* The description as a template, when the caller passed a node.
|
|
474
|
+
* @returns The description template, or null.
|
|
475
|
+
*/
|
|
476
|
+
descriptionTemplate(): TemplateRef<unknown> | null {
|
|
477
|
+
return isTemplate(this.description) ? this.description : null
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
/**
|
|
481
|
+
* The footer as a template, when the caller passed a node.
|
|
482
|
+
* @returns The footer template, or null.
|
|
483
|
+
*/
|
|
484
|
+
footerTemplate(): TemplateRef<unknown> | null {
|
|
485
|
+
return isTemplate(this.footer) ? this.footer : null
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
/**
|
|
489
|
+
* Whether the title input renders as text (React renders strings and numbers).
|
|
490
|
+
* @returns True when the title is text.
|
|
491
|
+
*/
|
|
492
|
+
hasTitleText(): boolean {
|
|
493
|
+
return typeof this.title === 'string' || typeof this.title === 'number'
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* Whether the description input renders as truthy text (React's `description && …`).
|
|
498
|
+
* @returns True when the description text renders.
|
|
499
|
+
*/
|
|
500
|
+
hasDescriptionText(): boolean {
|
|
501
|
+
return hasText(this.description)
|
|
502
|
+
}
|
|
503
|
+
|
|
504
|
+
/**
|
|
505
|
+
* Whether the footer input renders as truthy text (React's `footer && …`).
|
|
506
|
+
* @returns True when the footer text renders.
|
|
507
|
+
*/
|
|
508
|
+
hasFooterText(): boolean {
|
|
509
|
+
return hasText(this.footer)
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
/**
|
|
513
|
+
* Whether the description paragraph renders: React's `description && …` on
|
|
514
|
+
* the text input, a template, or projected content.
|
|
515
|
+
* @returns True when the paragraph shows.
|
|
516
|
+
*/
|
|
517
|
+
showDescription(): boolean {
|
|
518
|
+
return (
|
|
519
|
+
this.hasDescriptionText() ||
|
|
520
|
+
isTemplate(this.description) ||
|
|
521
|
+
this.descriptionProjected() === true
|
|
522
|
+
)
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
/**
|
|
526
|
+
* Whether the footer row renders: React's `footer && …` on the text input, a
|
|
527
|
+
* template, or projected content.
|
|
528
|
+
* @returns True when the footer shows.
|
|
529
|
+
*/
|
|
530
|
+
showFooter(): boolean {
|
|
531
|
+
return this.hasFooterText() || isTemplate(this.footer) || this.footerProjected() === true
|
|
532
|
+
}
|
|
533
|
+
}
|
|
534
|
+
```
|
|
535
|
+
|
|
536
|
+
#### `SettingsSidebar`
|
|
537
|
+
|
|
538
|
+
Vertical side-nav for settings pages.
|
|
539
|
+
|
|
540
|
+
Controlled — the caller owns `activeId`; every item calls `onSelect` with
|
|
541
|
+
its id. The host IS the `<nav>` (`nav[mol-settings-sidebar]`), matching
|
|
542
|
+
React's root exactly, including the region name: the default `aria-label`
|
|
543
|
+
resolves through `t()` with the `settingsContainer.aria.settings` key, so it
|
|
544
|
+
follows the active locale; `ariaLabel` overrides it. An item's `label` and
|
|
545
|
+
`icon` are projected node templates or plain text; the optional `footer` is
|
|
546
|
+
`[slot=footer]` content or text, and renders only when React would render it.
|
|
547
|
+
|
|
548
|
+
```typescript
|
|
549
|
+
@Component({
|
|
550
|
+
selector: 'nav[mol-settings-sidebar]',
|
|
551
|
+
standalone: true,
|
|
552
|
+
imports: [NgTemplateOutlet],
|
|
553
|
+
inputs: ['items', 'activeId', 'onSelect', 'footer', 'ariaLabel', 'className'],
|
|
554
|
+
host: {
|
|
555
|
+
'[class]': 'classes()',
|
|
556
|
+
'[attr.aria-label]': 'navLabel()',
|
|
557
|
+
},
|
|
558
|
+
// prettier-ignore
|
|
559
|
+
template: `@for (item of items; track item.id) {<button type="button" [attr.aria-current]="item.id === activeId ? 'page' : null" [class]="itemClasses(item)" (click)="select(item)">@if (item.icon != null) {@if (isText(item.icon)) {<ng-container>{{ textOf(item.icon) }}</ng-container>}@else {<ng-container [ngTemplateOutlet]="templateOf(item.icon)" />}}<span>@if (isText(item.label)) {<ng-container>{{ textOf(item.label) }}</ng-container>}@else {<ng-container [ngTemplateOutlet]="templateOf(item.label)" />}</span></button>}@if (showFooter()) {<div #footerEl [class]="footerClasses()">@if (footerTemplate(); as footerTpl) {<ng-container [ngTemplateOutlet]="footerTpl" />}@else if (hasFooterText()) {<ng-container>{{ textOf(footer) }}</ng-container>}<ng-content select="[slot=footer]"></ng-content></div>}`,
|
|
560
|
+
})
|
|
561
|
+
export class SettingsSidebar implements AfterViewInit {
|
|
562
|
+
/** Items to render, in order. */
|
|
563
|
+
items: SettingsSidebarItem[] = []
|
|
564
|
+
/** The id of the active item (controlled — the caller owns it). */
|
|
565
|
+
activeId?: string
|
|
566
|
+
/** Called with the clicked item's id. */
|
|
567
|
+
onSelect?: (id: string) => void
|
|
568
|
+
/** Optional footer — a template, `[slot=footer]` content, or plain text. */
|
|
569
|
+
footer?: unknown
|
|
570
|
+
/** Accessible label override; defaults to `t('settingsContainer.aria.settings', …)`. */
|
|
571
|
+
ariaLabel?: string
|
|
572
|
+
/** Extra classes. */
|
|
573
|
+
className?: string
|
|
574
|
+
|
|
575
|
+
/** The optional footer container (projected content lands here; read once). */
|
|
576
|
+
@ViewChild('footerEl') private footerEl?: ElementRef<HTMLElement>
|
|
577
|
+
|
|
578
|
+
/** Whether a `[slot=footer]` projection landed (`null`: decided by the text input). */
|
|
579
|
+
private readonly footerProjected = signal<boolean | null>(true)
|
|
580
|
+
|
|
581
|
+
/** The i18n provider access (locale-reactive through the notifications signal). */
|
|
582
|
+
private readonly i18n = useTranslation()
|
|
583
|
+
|
|
584
|
+
/**
|
|
585
|
+
* Reads the optional footer's first render: when neither text nor projected
|
|
586
|
+
* content landed, React would not render it at all, so the optimistic render
|
|
587
|
+
* is withdrawn.
|
|
588
|
+
*/
|
|
589
|
+
ngAfterViewInit(): void {
|
|
590
|
+
this.footerProjected.set(
|
|
591
|
+
this.hasFooterText() ? null : hasRenderableContent(this.footerEl?.nativeElement),
|
|
592
|
+
)
|
|
593
|
+
}
|
|
594
|
+
|
|
595
|
+
/**
|
|
596
|
+
* The current class map.
|
|
597
|
+
* @returns The UIClassMap.
|
|
598
|
+
*/
|
|
599
|
+
cm(): UIClassMap {
|
|
600
|
+
return getClassMap()
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
/**
|
|
604
|
+
* Renders a text value the way React renders a node string.
|
|
605
|
+
* @param value - The prop value.
|
|
606
|
+
* @returns The text to render, or `''` when there is nothing.
|
|
607
|
+
*/
|
|
608
|
+
textOf(value: unknown): string {
|
|
609
|
+
return value === null || value === undefined ? '' : String(value)
|
|
610
|
+
}
|
|
611
|
+
|
|
612
|
+
/**
|
|
613
|
+
* Whether a value renders as text (React renders strings and numbers).
|
|
614
|
+
* @param value - The prop value.
|
|
615
|
+
* @returns True when the value renders as text.
|
|
616
|
+
*/
|
|
617
|
+
isText(value: unknown): boolean {
|
|
618
|
+
return isText(value)
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
/**
|
|
622
|
+
* A data value's node template, when it is one.
|
|
623
|
+
* @param value - The prop value.
|
|
624
|
+
* @returns The template, or null.
|
|
625
|
+
*/
|
|
626
|
+
templateOf(value: unknown): TemplateRef<unknown> | null {
|
|
627
|
+
return isTemplate(value) ? value : null
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
/**
|
|
631
|
+
* The nav's class list (React's `cm.cn(cm.stack(1), className)`).
|
|
632
|
+
* @returns The class string.
|
|
633
|
+
*/
|
|
634
|
+
classes(): string {
|
|
635
|
+
return this.cm().cn(this.cm().stack(1), this.className)
|
|
636
|
+
}
|
|
637
|
+
|
|
638
|
+
/**
|
|
639
|
+
* The nav's accessible name (React's
|
|
640
|
+
* `ariaLabel ?? t('settingsContainer.aria.settings', …)`).
|
|
641
|
+
* @returns The label text.
|
|
642
|
+
*/
|
|
643
|
+
navLabel(): string {
|
|
644
|
+
return (
|
|
645
|
+
this.ariaLabel ??
|
|
646
|
+
this.i18n.t('settingsContainer.aria.settings', undefined, { defaultValue: 'Settings' })
|
|
647
|
+
)
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
/**
|
|
651
|
+
* One item's button class list, with React's active/inactive weight branch.
|
|
652
|
+
* @param item - The item.
|
|
653
|
+
* @returns The class string.
|
|
654
|
+
*/
|
|
655
|
+
itemClasses(item: SettingsSidebarItem): string {
|
|
656
|
+
const active = item.id === this.activeId
|
|
657
|
+
return this.cm().cn(
|
|
658
|
+
this.cm().flex({ align: 'center', gap: 'sm' }),
|
|
659
|
+
this.cm().sp('px', 3),
|
|
660
|
+
this.cm().sp('py', 2),
|
|
661
|
+
this.cm().textSize('sm'),
|
|
662
|
+
active ? this.cm().fontWeight('semibold') : this.cm().fontWeight('medium'),
|
|
663
|
+
)
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
/**
|
|
667
|
+
* The footer container's class (`cm.sp('mt', 4)`).
|
|
668
|
+
* @returns The class string.
|
|
669
|
+
*/
|
|
670
|
+
footerClasses(): string {
|
|
671
|
+
return this.cm().sp('mt', 4)
|
|
672
|
+
}
|
|
673
|
+
|
|
674
|
+
/**
|
|
675
|
+
* The footer as a template, when the caller passed a node.
|
|
676
|
+
* @returns The footer template, or null.
|
|
677
|
+
*/
|
|
678
|
+
footerTemplate(): TemplateRef<unknown> | null {
|
|
679
|
+
return isTemplate(this.footer) ? this.footer : null
|
|
680
|
+
}
|
|
681
|
+
|
|
682
|
+
/**
|
|
683
|
+
* Whether the footer input renders as truthy text (React's `footer && …`).
|
|
684
|
+
* @returns True when the footer text renders.
|
|
685
|
+
*/
|
|
686
|
+
hasFooterText(): boolean {
|
|
687
|
+
return hasText(this.footer)
|
|
688
|
+
}
|
|
689
|
+
|
|
690
|
+
/**
|
|
691
|
+
* Whether the footer renders: React's `footer && …` on the text input, a
|
|
692
|
+
* template, or projected content.
|
|
693
|
+
* @returns True when the footer shows.
|
|
694
|
+
*/
|
|
695
|
+
showFooter(): boolean {
|
|
696
|
+
return this.hasFooterText() || isTemplate(this.footer) || this.footerProjected() === true
|
|
697
|
+
}
|
|
698
|
+
|
|
699
|
+
/**
|
|
700
|
+
* Activates an item (React's `onClick={() => onSelect(item.id)}`).
|
|
701
|
+
* @param item - The clicked item.
|
|
702
|
+
*/
|
|
703
|
+
select(item: SettingsSidebarItem): void {
|
|
704
|
+
this.onSelect?.(item.id)
|
|
705
|
+
}
|
|
706
|
+
}
|
|
707
|
+
```
|
|
708
|
+
|
|
709
|
+
## Injection Notes
|
|
710
|
+
|
|
711
|
+
### Requirements
|
|
712
|
+
|
|
713
|
+
Peer dependencies:
|
|
714
|
+
|
|
715
|
+
- `@angular/common` ^22.0.0
|
|
716
|
+
- `@angular/core` ^22.0.0
|
|
717
|
+
- `@angular/platform-browser` ^22.0.0
|
|
718
|
+
- `@molecule/app-angular` ^3.5.0
|
|
719
|
+
- `@molecule/app-ui` ^1.0.1
|
|
720
|
+
- `@molecule/app-ui-angular` ^1.1.0
|
|
721
|
+
|
|
722
|
+
### Runtime Dependencies
|
|
723
|
+
|
|
724
|
+
- `@angular/common`
|
|
725
|
+
- `@angular/core`
|
|
726
|
+
- `@angular/platform-browser`
|
|
727
|
+
- `@molecule/app-angular`
|
|
728
|
+
- `@molecule/app-ui`
|
|
729
|
+
- `@molecule/app-ui-angular`
|
|
730
|
+
|
|
731
|
+
- Node props are projected content: `[slot=header]`, `[slot=sidebar]`,
|
|
732
|
+
`[slot=footer]`, `[slot=title]` and `[slot=description]` — everything
|
|
733
|
+
else lands in the default projection. Text-only values (`title`,
|
|
734
|
+
`description`, `footer`) may also be passed as inputs.
|
|
735
|
+
- The `header` is rendered above the columns but is NOT sticky — apply your
|
|
736
|
+
own sticky positioning if you need it pinned.
|
|
737
|
+
- The two columns do not collapse responsively — swap the sidebar for a
|
|
738
|
+
drawer on small screens yourself.
|
|
739
|
+
- Requires a bonded ClassMap. Labels are your own nodes (translate
|
|
740
|
+
upstream); the sidebar nav's `aria-label="Settings"` is hardcoded English.
|
|
741
|
+
- Don't confuse with `@molecule/app-settings-panel-angular`: that package is
|
|
742
|
+
the batteries-included panel (prebuilt Account/Auth/Billing/… sections
|
|
743
|
+
wired to molecule APIs). THIS package is empty layout chrome for building
|
|
744
|
+
your own settings pages.
|
|
745
|
+
|
|
746
|
+
## Translations
|
|
747
|
+
|
|
748
|
+
Translation strings are provided by `@molecule/app-locales-settings-container`.
|