@molecule/app-empty-state-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 +625 -2
- package/dist/cta-card.component.d.ts +148 -0
- package/dist/cta-card.component.d.ts.map +1 -0
- package/dist/cta-card.component.js +384 -0
- package/dist/cta-card.component.js.map +1 -0
- package/dist/empty-state.component.d.ts +134 -0
- package/dist/empty-state.component.d.ts.map +1 -0
- package/dist/empty-state.component.js +324 -0
- package/dist/empty-state.component.js.map +1 -0
- package/dist/index.d.ts +65 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +65 -0
- package/dist/index.js.map +1 -0
- package/dist/slot-dom.d.ts +56 -0
- package/dist/slot-dom.d.ts.map +1 -0
- package/dist/slot-dom.js +104 -0
- package/dist/slot-dom.js.map +1 -0
- package/dist/types.d.ts +70 -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,626 @@
|
|
|
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-16T11:08:24.488Z
|
|
7
|
+
-->
|
|
2
8
|
|
|
3
|
-
|
|
9
|
+
# @molecule/app-empty-state-angular
|
|
10
|
+
|
|
11
|
+
Angular empty-state and CTA-card primitives — the counterpart of
|
|
12
|
+
`@molecule/app-empty-state-react`: the same props and the same DOM for the
|
|
13
|
+
same input.
|
|
14
|
+
|
|
15
|
+
Exports:
|
|
16
|
+
|
|
17
|
+
- `<EmptyState>` — centred icon + title + description + action for lists,
|
|
18
|
+
feeds, boards, or tables that have no rows to render yet.
|
|
19
|
+
- `<CtaCard>` — horizontal or vertical promotional card for "next-step"
|
|
20
|
+
actions inside a page body.
|
|
21
|
+
|
|
22
|
+
Both components accept a `className` input so apps can layer per-brand
|
|
23
|
+
accent chrome (dashed borders, gradient CTAs, tinted backgrounds) on
|
|
24
|
+
top of the structural layout.
|
|
25
|
+
|
|
26
|
+
A selected list view passes `view={emptyByView[selection]}`. Each entry pairs
|
|
27
|
+
its translated `title`, optional `description`, and required `action` element.
|
|
28
|
+
Keep those entries beside the view definitions so a personal or filtered list
|
|
29
|
+
does not reuse the whole collection's empty message. The action can be a router
|
|
30
|
+
link to another view or a button that clears filters. General empty states keep
|
|
31
|
+
the existing `title` and optional `action` props.
|
|
32
|
+
|
|
33
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
34
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
35
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
36
|
+
|
|
37
|
+
## Quick Start
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
import { Component } from '@angular/core'
|
|
41
|
+
import { RouterLink } from '@angular/router'
|
|
42
|
+
import { CtaCard, EmptyState } from '@molecule/app-empty-state-angular'
|
|
43
|
+
import { Button, Icon } from '@molecule/app-ui-angular'
|
|
44
|
+
|
|
45
|
+
@Component({
|
|
46
|
+
selector: 'app-messages-empty',
|
|
47
|
+
standalone: true,
|
|
48
|
+
imports: [EmptyState, Icon, RouterLink],
|
|
49
|
+
template: `
|
|
50
|
+
<section mol-empty-state [title]="t('messages.empty.title')">
|
|
51
|
+
<icon slot="icon" name="mail" [size]="40" />
|
|
52
|
+
<p slot="description">{{ t('messages.empty.description') }}</p>
|
|
53
|
+
<a slot="action" routerLink="/compose">Send one</a>
|
|
54
|
+
</section>
|
|
55
|
+
`,
|
|
56
|
+
})
|
|
57
|
+
export class MessagesEmpty {}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Type
|
|
61
|
+
|
|
62
|
+
`feature`
|
|
63
|
+
|
|
64
|
+
## Installation
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
npm install @molecule/app-empty-state-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-ui @molecule/app-ui-angular
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## API
|
|
71
|
+
|
|
72
|
+
### Interfaces
|
|
73
|
+
|
|
74
|
+
#### `EmptyStateProps`
|
|
75
|
+
|
|
76
|
+
Props accepted by {@link EmptyState} — the same props
|
|
77
|
+
`@molecule/app-empty-state-react` accepts. Node props are an input (a string,
|
|
78
|
+
or a `TemplateRef` for a node value) or projected content: `icon`, `title`,
|
|
79
|
+
`description` and `action` are selected by `[slot=icon]`, `[slot=title]`,
|
|
80
|
+
`[slot=description]` and `[slot=action]`.
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
interface EmptyStateProps {
|
|
84
|
+
/** Visual — an icon node as a `TemplateRef`, or `[slot=icon]` projected content. */
|
|
85
|
+
icon?: unknown
|
|
86
|
+
/** Primary heading for a general, unselected collection. */
|
|
87
|
+
title?: unknown
|
|
88
|
+
/** Supporting description shown below the heading. */
|
|
89
|
+
description?: unknown
|
|
90
|
+
/** Optional action for a general empty state. */
|
|
91
|
+
action?: unknown
|
|
92
|
+
/**
|
|
93
|
+
* The selected view's translated message and required recovery element, kept
|
|
94
|
+
* together so a filtered or personal list never reuses the whole
|
|
95
|
+
* collection's empty message. Replaces `title`, `description` and `action`
|
|
96
|
+
* when given.
|
|
97
|
+
*/
|
|
98
|
+
view?: {
|
|
99
|
+
/** The selected view's translated heading. */
|
|
100
|
+
title: unknown
|
|
101
|
+
/** The selected view's supporting description. */
|
|
102
|
+
description?: unknown
|
|
103
|
+
/** The selected view's recovery element — a `TemplateRef` holding a router link or a button. */
|
|
104
|
+
action: unknown
|
|
105
|
+
}
|
|
106
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
107
|
+
dataMolId?: string
|
|
108
|
+
/** Override outer wrapper classes (for per-app dashed-border, background, padding, etc.). */
|
|
109
|
+
className?: string
|
|
110
|
+
/** Override the icon-badge wrapper classes. */
|
|
111
|
+
iconWrapperClassName?: string
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
#### `CtaCardProps`
|
|
116
|
+
|
|
117
|
+
Props accepted by {@link CtaCard} — the same props
|
|
118
|
+
`@molecule/app-empty-state-react` accepts. Node props are an input (a string,
|
|
119
|
+
or a `TemplateRef` for a node value) or projected content: `eyebrow`,
|
|
120
|
+
`title`, `description`, `action` and `media` are selected by
|
|
121
|
+
`[slot=eyebrow]`, `[slot=title]`, `[slot=description]`, `[slot=action]` and
|
|
122
|
+
`[slot=media]`.
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
interface CtaCardProps {
|
|
126
|
+
/** Optional small eyebrow line above the title — a string, a `TemplateRef`, or `[slot=eyebrow]`. */
|
|
127
|
+
eyebrow?: unknown
|
|
128
|
+
/** Primary heading — a string, a `TemplateRef`, or `[slot=title]`. */
|
|
129
|
+
title?: unknown
|
|
130
|
+
/** Supporting copy — a string, a `TemplateRef`, or `[slot=description]`. */
|
|
131
|
+
description?: unknown
|
|
132
|
+
/** Primary call-to-action — a string, a `TemplateRef`, or `[slot=action]`. */
|
|
133
|
+
action?: unknown
|
|
134
|
+
/** Optional visual / illustration — a `TemplateRef`, or `[slot=media]`. */
|
|
135
|
+
media?: unknown
|
|
136
|
+
/** `'horizontal'` renders media beside text; `'vertical'` stacks them. Defaults to `'vertical'`. */
|
|
137
|
+
layout?: 'vertical' | 'horizontal'
|
|
138
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
139
|
+
dataMolId?: string
|
|
140
|
+
/** Override outer wrapper classes. */
|
|
141
|
+
className?: string
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Classes
|
|
146
|
+
|
|
147
|
+
#### `CtaCard`
|
|
148
|
+
|
|
149
|
+
A "soft sell" card used to promote a next-step action inside a page body
|
|
150
|
+
(e.g., "Connect your bank", "Invite teammates").
|
|
151
|
+
|
|
152
|
+
Differs from `<EmptyState>` in being positioned in a list of cards rather
|
|
153
|
+
than filling the void. Supports a horizontal layout with the media slot
|
|
154
|
+
beside the text.
|
|
155
|
+
|
|
156
|
+
The host IS the outer `<section>` (`section[mol-cta-card]`), matching React's
|
|
157
|
+
root exactly. Node props are an input (a string, or a `TemplateRef`) or
|
|
158
|
+
projected content: `[slot=eyebrow]`, `[slot=title]`, `[slot=description]`,
|
|
159
|
+
`[slot=action]` and `[slot=media]`.
|
|
160
|
+
|
|
161
|
+
This is the Angular counterpart of `@molecule/app-empty-state-react`'s
|
|
162
|
+
`CtaCard`.
|
|
163
|
+
|
|
164
|
+
```typescript
|
|
165
|
+
@Component({
|
|
166
|
+
selector: 'section[mol-cta-card]',
|
|
167
|
+
standalone: true,
|
|
168
|
+
imports: [NgTemplateOutlet],
|
|
169
|
+
inputs: [
|
|
170
|
+
'eyebrow',
|
|
171
|
+
'title',
|
|
172
|
+
'description',
|
|
173
|
+
'action',
|
|
174
|
+
'media',
|
|
175
|
+
'layout',
|
|
176
|
+
'dataMolId',
|
|
177
|
+
'className',
|
|
178
|
+
],
|
|
179
|
+
host: {
|
|
180
|
+
'[class]': 'classes()',
|
|
181
|
+
'[attr.data-mol-id]': 'dataMolId ?? null',
|
|
182
|
+
},
|
|
183
|
+
// prettier-ignore
|
|
184
|
+
template: `<div #mediaEl [class]="mediaClasses()">@if (templateOf(media); as tpl) {<ng-container [ngTemplateOutlet]="tpl" />} @else if (textOf(media); as t) {{{ t }}}<ng-content select="[slot=media]"></ng-content></div><div [class]="bodyClasses()"><div #eyebrowEl [class]="eyebrowClasses()">@if (templateOf(eyebrow); as tpl) {<ng-container [ngTemplateOutlet]="tpl" />} @else if (textOf(eyebrow); as t) {{{ t }}}<ng-content select="[slot=eyebrow]"></ng-content></div><h3 [class]="titleClasses()">@if (templateOf(title); as tpl) {<ng-container [ngTemplateOutlet]="tpl" />} @else if (textOf(title); as t) {{{ t }}}<ng-content select="[slot=title]"></ng-content></h3><p #descriptionEl>@if (templateOf(description); as tpl) {<ng-container [ngTemplateOutlet]="tpl" />} @else if (textOf(description); as t) {{{ t }}}<ng-content select="[slot=description]"></ng-content></p><div #actionEl [class]="actionClasses()">@if (templateOf(action); as tpl) {<ng-container [ngTemplateOutlet]="tpl" />} @else if (textOf(action); as t) {{{ t }}}<ng-content select="[slot=action]"></ng-content></div></div>`,
|
|
185
|
+
})
|
|
186
|
+
export class CtaCard implements AfterViewInit, DoCheck {
|
|
187
|
+
/** Optional small eyebrow line above the title — a string, a `TemplateRef`, or `[slot=eyebrow]`. */
|
|
188
|
+
eyebrow?: unknown
|
|
189
|
+
/** Primary heading — a string, a `TemplateRef`, or `[slot=title]`. */
|
|
190
|
+
title?: unknown
|
|
191
|
+
/** Supporting copy — a string, a `TemplateRef`, or `[slot=description]`. */
|
|
192
|
+
description?: unknown
|
|
193
|
+
/** Primary call-to-action — a string, a `TemplateRef`, or `[slot=action]`. */
|
|
194
|
+
action?: unknown
|
|
195
|
+
/** Optional visual / illustration — a `TemplateRef`, or `[slot=media]`. */
|
|
196
|
+
media?: unknown
|
|
197
|
+
/** `'horizontal'` renders media beside text; `'vertical'` stacks them. Defaults to `'vertical'`. */
|
|
198
|
+
layout?: CtaCardProps['layout']
|
|
199
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
200
|
+
dataMolId?: string
|
|
201
|
+
/** Override outer wrapper classes. */
|
|
202
|
+
className?: string
|
|
203
|
+
|
|
204
|
+
/** The optional media wrapper (the projected media lands here). */
|
|
205
|
+
@ViewChild('mediaEl') private mediaEl?: ElementRef<HTMLElement>
|
|
206
|
+
/** The optional eyebrow wrapper (the projected eyebrow lands here). */
|
|
207
|
+
@ViewChild('eyebrowEl') private eyebrowEl?: ElementRef<HTMLElement>
|
|
208
|
+
/** The optional description paragraph (the projected description lands here). */
|
|
209
|
+
@ViewChild('descriptionEl') private descriptionEl?: ElementRef<HTMLElement>
|
|
210
|
+
/** The optional action wrapper (the projected action lands here). */
|
|
211
|
+
@ViewChild('actionEl') private actionEl?: ElementRef<HTMLElement>
|
|
212
|
+
|
|
213
|
+
/** The host element (the outer `<section>`). */
|
|
214
|
+
private readonly host = inject(ElementRef<HTMLElement>)
|
|
215
|
+
/** The DOM renderer, for the wrapper attach/detach. */
|
|
216
|
+
private readonly renderer: Renderer2 = inject(RendererFactory2).createRenderer(null, null)
|
|
217
|
+
/** Reconciles the optional wrappers against React's DOM. */
|
|
218
|
+
private readonly guard = new SlotGuard(this.host, this.renderer)
|
|
219
|
+
/** Whether a `[slot=media]` projection landed. */
|
|
220
|
+
private readonly mediaProjected = signal(false)
|
|
221
|
+
/** Whether a `[slot=eyebrow]` projection landed. */
|
|
222
|
+
private readonly eyebrowProjected = signal(false)
|
|
223
|
+
/** Whether a `[slot=description]` projection landed. */
|
|
224
|
+
private readonly descriptionProjected = signal(false)
|
|
225
|
+
/** Whether a `[slot=action]` projection landed. */
|
|
226
|
+
private readonly actionProjected = signal(false)
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* The current class map.
|
|
230
|
+
* @returns The UIClassMap.
|
|
231
|
+
*/
|
|
232
|
+
cm(): UIClassMap {
|
|
233
|
+
return getClassMap()
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* The layout direction (React's `layout === 'horizontal' ? 'row' : 'col'`).
|
|
238
|
+
* @returns True for the horizontal layout.
|
|
239
|
+
*/
|
|
240
|
+
horizontal(): boolean {
|
|
241
|
+
return this.layout === 'horizontal'
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/**
|
|
245
|
+
* The host's class list (React's root `<section>` classes).
|
|
246
|
+
* @returns The class string.
|
|
247
|
+
*/
|
|
248
|
+
classes(): string {
|
|
249
|
+
const cm = this.cm()
|
|
250
|
+
return cm.cn(
|
|
251
|
+
cm.flex({
|
|
252
|
+
direction: this.horizontal() ? 'row' : 'col',
|
|
253
|
+
align: this.horizontal() ? 'center' : 'stretch',
|
|
254
|
+
gap: 'md',
|
|
255
|
+
}),
|
|
256
|
+
cm.sp('p', 6),
|
|
257
|
+
this.className,
|
|
258
|
+
)
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/**
|
|
262
|
+
* The media wrapper's class list.
|
|
263
|
+
* @returns The class string.
|
|
264
|
+
*/
|
|
265
|
+
mediaClasses(): string {
|
|
266
|
+
return this.cm().cn(this.cm().shrink0)
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* The text column's class list.
|
|
271
|
+
* @returns The class string.
|
|
272
|
+
*/
|
|
273
|
+
bodyClasses(): string {
|
|
274
|
+
const cm = this.cm()
|
|
275
|
+
return cm.cn(cm.flex1, cm.stack(2))
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/**
|
|
279
|
+
* The eyebrow's class list.
|
|
280
|
+
* @returns The class string.
|
|
281
|
+
*/
|
|
282
|
+
eyebrowClasses(): string {
|
|
283
|
+
const cm = this.cm()
|
|
284
|
+
return cm.cn(cm.textSize('xs'), cm.fontWeight('semibold'))
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/**
|
|
288
|
+
* The heading's class list.
|
|
289
|
+
* @returns The class string.
|
|
290
|
+
*/
|
|
291
|
+
titleClasses(): string {
|
|
292
|
+
const cm = this.cm()
|
|
293
|
+
return cm.cn(cm.textSize('xl'), cm.fontWeight('bold'))
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/**
|
|
297
|
+
* The action wrapper's class list.
|
|
298
|
+
* @returns The class string.
|
|
299
|
+
*/
|
|
300
|
+
actionClasses(): string {
|
|
301
|
+
return this.cm().sp('mt', 2)
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* A node value as a template, when the caller passed one.
|
|
306
|
+
* @param value - The prop value.
|
|
307
|
+
* @returns The template, or null for text.
|
|
308
|
+
*/
|
|
309
|
+
templateOf(value: unknown): TemplateRef<unknown> | null {
|
|
310
|
+
return isTemplate(value) ? value : null
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/**
|
|
314
|
+
* A node value as text, when the caller passed one.
|
|
315
|
+
* @param value - The prop value.
|
|
316
|
+
* @returns The text, or null for a template.
|
|
317
|
+
*/
|
|
318
|
+
textOf(value: unknown): string | null {
|
|
319
|
+
return textOf(value)
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/**
|
|
323
|
+
* Whether the media wrapper renders.
|
|
324
|
+
* @returns True when a media node or a projected media is present.
|
|
325
|
+
*/
|
|
326
|
+
showMedia(): boolean {
|
|
327
|
+
return this.media != null || this.mediaProjected()
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/**
|
|
331
|
+
* Whether the eyebrow renders.
|
|
332
|
+
* @returns True when an eyebrow node or a projected eyebrow is present.
|
|
333
|
+
*/
|
|
334
|
+
showEyebrow(): boolean {
|
|
335
|
+
return this.eyebrow != null || this.eyebrowProjected()
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
/**
|
|
339
|
+
* Whether the description renders.
|
|
340
|
+
* @returns True when a description node or a projected description is present.
|
|
341
|
+
*/
|
|
342
|
+
showDescription(): boolean {
|
|
343
|
+
return this.description != null || this.descriptionProjected()
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/**
|
|
347
|
+
* Whether the action renders.
|
|
348
|
+
* @returns True when an action node or a projected action is present.
|
|
349
|
+
*/
|
|
350
|
+
showAction(): boolean {
|
|
351
|
+
return this.action != null || this.actionProjected()
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
/**
|
|
355
|
+
* Reads the projected capture points and reconciles the optional wrappers.
|
|
356
|
+
*/
|
|
357
|
+
reconcile(): void {
|
|
358
|
+
const media = this.mediaEl?.nativeElement
|
|
359
|
+
if (media) this.mediaProjected.set(hasNodes(media))
|
|
360
|
+
const eyebrow = this.eyebrowEl?.nativeElement
|
|
361
|
+
if (eyebrow) this.eyebrowProjected.set(hasNodes(eyebrow))
|
|
362
|
+
const description = this.descriptionEl?.nativeElement
|
|
363
|
+
if (description) this.descriptionProjected.set(hasNodes(description))
|
|
364
|
+
const action = this.actionEl?.nativeElement
|
|
365
|
+
if (action) this.actionProjected.set(hasNodes(action))
|
|
366
|
+
this.guard.toggle(media, this.showMedia())
|
|
367
|
+
this.guard.toggle(eyebrow, this.showEyebrow())
|
|
368
|
+
this.guard.toggle(description, this.showDescription())
|
|
369
|
+
this.guard.toggle(action, this.showAction())
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
/** Reconciles the wrappers once the view (and its projections) exist. */
|
|
373
|
+
ngAfterViewInit(): void {
|
|
374
|
+
this.reconcile()
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
/** Reconciles the wrappers after input writes, as React re-renders on a prop change. */
|
|
378
|
+
ngDoCheck(): void {
|
|
379
|
+
this.reconcile()
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
#### `EmptyState`
|
|
385
|
+
|
|
386
|
+
Generic centred empty-state panel for lists, feeds, boards, and tables.
|
|
387
|
+
|
|
388
|
+
Renders a vertical stack of [icon, title, description, action]. Typography
|
|
389
|
+
and spacing come from the wired ClassMap; per-app accent chrome (dashed
|
|
390
|
+
borders, tinted backgrounds, gradient CTAs) is passed via `className` on the
|
|
391
|
+
outer element.
|
|
392
|
+
|
|
393
|
+
The host IS the outer `<section>` (`section[mol-empty-state]`), matching
|
|
394
|
+
React's root exactly. Node props are an input (a string, or a `TemplateRef`)
|
|
395
|
+
or projected content: `[slot=icon]`, `[slot=title]`, `[slot=description]` and
|
|
396
|
+
`[slot=action]`.
|
|
397
|
+
|
|
398
|
+
This is the Angular counterpart of `@molecule/app-empty-state-react`.
|
|
399
|
+
|
|
400
|
+
```typescript
|
|
401
|
+
@Component({
|
|
402
|
+
selector: 'section[mol-empty-state]',
|
|
403
|
+
standalone: true,
|
|
404
|
+
imports: [NgTemplateOutlet],
|
|
405
|
+
inputs: [
|
|
406
|
+
'icon',
|
|
407
|
+
'title',
|
|
408
|
+
'description',
|
|
409
|
+
'action',
|
|
410
|
+
'view',
|
|
411
|
+
'dataMolId',
|
|
412
|
+
'className',
|
|
413
|
+
'iconWrapperClassName',
|
|
414
|
+
],
|
|
415
|
+
host: {
|
|
416
|
+
'[class]': 'classes()',
|
|
417
|
+
'[attr.data-mol-id]': 'dataMolId ?? null',
|
|
418
|
+
},
|
|
419
|
+
// prettier-ignore
|
|
420
|
+
template: `<div #iconEl [class]="iconWrapperClasses()">@if (templateOf(icon); as tpl) {<ng-container [ngTemplateOutlet]="tpl" />} @else if (textOf(icon); as t) {{{ t }}}<ng-content select="[slot=icon]"></ng-content></div><h3 [class]="titleClasses()">@if (templateOf(content().title); as tpl) {<ng-container [ngTemplateOutlet]="tpl" />} @else if (textOf(content().title); as t) {{{ t }}}<ng-content select="[slot=title]"></ng-content></h3><p #descriptionEl [class]="descriptionClasses()">@if (templateOf(content().description); as tpl) {<ng-container [ngTemplateOutlet]="tpl" />} @else if (textOf(content().description); as t) {{{ t }}}<ng-content select="[slot=description]"></ng-content></p><div #actionEl data-parity-unwrap>@if (templateOf(content().action); as tpl) {<ng-container [ngTemplateOutlet]="tpl" />} @else if (textOf(content().action); as t) {{{ t }}}<ng-content select="[slot=action]"></ng-content></div>`,
|
|
421
|
+
})
|
|
422
|
+
export class EmptyState implements AfterViewInit, DoCheck {
|
|
423
|
+
/** Visual — an icon node as a `TemplateRef`, a string, or `[slot=icon]` content. */
|
|
424
|
+
icon?: unknown
|
|
425
|
+
/** Primary heading for a general, unselected collection. */
|
|
426
|
+
title?: unknown
|
|
427
|
+
/** Supporting description shown below the heading. */
|
|
428
|
+
description?: unknown
|
|
429
|
+
/** Optional action for a general empty state. */
|
|
430
|
+
action?: unknown
|
|
431
|
+
/** The selected view's translated message and required recovery element. */
|
|
432
|
+
view?: EmptyStateProps['view']
|
|
433
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
434
|
+
dataMolId?: string
|
|
435
|
+
/** Override outer wrapper classes (for per-app dashed-border, background, padding, etc.). */
|
|
436
|
+
className?: string
|
|
437
|
+
/** Override the icon-badge wrapper classes. */
|
|
438
|
+
iconWrapperClassName?: string
|
|
439
|
+
|
|
440
|
+
/** The optional icon badge (the projected icon lands here). */
|
|
441
|
+
@ViewChild('iconEl') private iconEl?: ElementRef<HTMLElement>
|
|
442
|
+
/** The optional description paragraph (the projected description lands here). */
|
|
443
|
+
@ViewChild('descriptionEl') private descriptionEl?: ElementRef<HTMLElement>
|
|
444
|
+
/** The action's capture point (the projected action lands here). */
|
|
445
|
+
@ViewChild('actionEl') private actionEl?: ElementRef<HTMLElement>
|
|
446
|
+
|
|
447
|
+
/** The host element (the outer `<section>`). */
|
|
448
|
+
private readonly host = inject(ElementRef<HTMLElement>)
|
|
449
|
+
/** The DOM renderer, for the wrapper attach/detach. */
|
|
450
|
+
private readonly renderer: Renderer2 = inject(RendererFactory2).createRenderer(null, null)
|
|
451
|
+
/** Reconciles the optional wrappers against React's DOM. */
|
|
452
|
+
private readonly guard = new SlotGuard(this.host, this.renderer)
|
|
453
|
+
/** Whether a `[slot=icon]` projection landed. */
|
|
454
|
+
private readonly iconProjected = signal(false)
|
|
455
|
+
/** Whether a `[slot=description]` projection landed. */
|
|
456
|
+
private readonly descriptionProjected = signal(false)
|
|
457
|
+
/** Whether a `[slot=action]` projection landed. */
|
|
458
|
+
private readonly actionProjected = signal(false)
|
|
459
|
+
|
|
460
|
+
/**
|
|
461
|
+
* The current class map.
|
|
462
|
+
* @returns The UIClassMap.
|
|
463
|
+
*/
|
|
464
|
+
cm(): UIClassMap {
|
|
465
|
+
return getClassMap()
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
/**
|
|
469
|
+
* The host's class list (React's root `<section>` classes).
|
|
470
|
+
* @returns The class string.
|
|
471
|
+
*/
|
|
472
|
+
classes(): string {
|
|
473
|
+
const cm = this.cm()
|
|
474
|
+
return cm.cn(
|
|
475
|
+
cm.flex({ direction: 'col', align: 'center', justify: 'center' }),
|
|
476
|
+
cm.textCenter,
|
|
477
|
+
cm.sp('p', 12),
|
|
478
|
+
this.className,
|
|
479
|
+
)
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
/**
|
|
483
|
+
* The icon badge's class list.
|
|
484
|
+
* @returns The class string.
|
|
485
|
+
*/
|
|
486
|
+
iconWrapperClasses(): string {
|
|
487
|
+
const cm = this.cm()
|
|
488
|
+
return cm.cn(
|
|
489
|
+
cm.w(20),
|
|
490
|
+
cm.h(20),
|
|
491
|
+
cm.roundedFull,
|
|
492
|
+
cm.flex({ align: 'center', justify: 'center' }),
|
|
493
|
+
cm.sp('mb', 6),
|
|
494
|
+
this.iconWrapperClassName,
|
|
495
|
+
)
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
/**
|
|
499
|
+
* The heading's class list.
|
|
500
|
+
* @returns The class string.
|
|
501
|
+
*/
|
|
502
|
+
titleClasses(): string {
|
|
503
|
+
const cm = this.cm()
|
|
504
|
+
return cm.cn(cm.textSize('2xl'), cm.fontWeight('bold'), cm.sp('mb', 2))
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
/**
|
|
508
|
+
* The description paragraph's class list (React's `mb` follows a present action).
|
|
509
|
+
* @returns The class string.
|
|
510
|
+
*/
|
|
511
|
+
descriptionClasses(): string {
|
|
512
|
+
const cm = this.cm()
|
|
513
|
+
return cm.cn(cm.maxW('md'), cm.sp('mb', this.showAction() ? 6 : 0))
|
|
514
|
+
}
|
|
515
|
+
|
|
516
|
+
/**
|
|
517
|
+
* The message to render: the selected view, or the general props.
|
|
518
|
+
* @returns The title, description and action nodes.
|
|
519
|
+
*/
|
|
520
|
+
content(): { title?: unknown; description?: unknown; action?: unknown } {
|
|
521
|
+
return this.view ?? { title: this.title, description: this.description, action: this.action }
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
/**
|
|
525
|
+
* A node value as a template, when the caller passed one.
|
|
526
|
+
* @param value - The prop value.
|
|
527
|
+
* @returns The template, or null for text.
|
|
528
|
+
*/
|
|
529
|
+
templateOf(value: unknown): TemplateRef<unknown> | null {
|
|
530
|
+
return isTemplate(value) ? value : null
|
|
531
|
+
}
|
|
532
|
+
|
|
533
|
+
/**
|
|
534
|
+
* A node value as text, when the caller passed one.
|
|
535
|
+
* @param value - The prop value.
|
|
536
|
+
* @returns The text, or null for a template.
|
|
537
|
+
*/
|
|
538
|
+
textOf(value: unknown): string | null {
|
|
539
|
+
return textOf(value)
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
/**
|
|
543
|
+
* Whether the icon badge renders.
|
|
544
|
+
* @returns True when an icon text/template input or a projected icon is present.
|
|
545
|
+
*/
|
|
546
|
+
showIcon(): boolean {
|
|
547
|
+
return textOf(this.icon) !== null || this.templateOf(this.icon) !== null || this.iconProjected()
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
/**
|
|
551
|
+
* Whether the description paragraph renders.
|
|
552
|
+
* @returns True when a description content node or a projected description is present.
|
|
553
|
+
*/
|
|
554
|
+
showDescription(): boolean {
|
|
555
|
+
return this.content().description != null || this.descriptionProjected()
|
|
556
|
+
}
|
|
557
|
+
|
|
558
|
+
/**
|
|
559
|
+
* Whether the action renders (React's truthiness check on `content.action`).
|
|
560
|
+
* @returns True when an action content node or a projected action is present.
|
|
561
|
+
*/
|
|
562
|
+
showAction(): boolean {
|
|
563
|
+
return this.content().action != null || this.actionProjected()
|
|
564
|
+
}
|
|
565
|
+
|
|
566
|
+
/**
|
|
567
|
+
* Reads the projected capture points and reconciles the optional wrappers.
|
|
568
|
+
*/
|
|
569
|
+
reconcile(): void {
|
|
570
|
+
const icon = this.iconEl?.nativeElement
|
|
571
|
+
if (icon) this.iconProjected.set(hasNodes(icon))
|
|
572
|
+
const description = this.descriptionEl?.nativeElement
|
|
573
|
+
if (description) this.descriptionProjected.set(hasNodes(description))
|
|
574
|
+
const action = this.actionEl?.nativeElement
|
|
575
|
+
if (action) this.actionProjected.set(hasNodes(action))
|
|
576
|
+
this.guard.toggle(this.iconEl?.nativeElement, this.showIcon())
|
|
577
|
+
this.guard.toggle(this.descriptionEl?.nativeElement, this.showDescription())
|
|
578
|
+
}
|
|
579
|
+
|
|
580
|
+
/** Reconciles the wrappers once the view (and its projections) exist. */
|
|
581
|
+
ngAfterViewInit(): void {
|
|
582
|
+
this.reconcile()
|
|
583
|
+
}
|
|
584
|
+
|
|
585
|
+
/** Reconciles the wrappers after input writes, as React re-renders on a prop change. */
|
|
586
|
+
ngDoCheck(): void {
|
|
587
|
+
this.reconcile()
|
|
588
|
+
}
|
|
589
|
+
}
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
## Injection Notes
|
|
593
|
+
|
|
594
|
+
### Requirements
|
|
595
|
+
|
|
596
|
+
Peer dependencies:
|
|
597
|
+
|
|
598
|
+
- `@angular/common` ^22.0.0
|
|
599
|
+
- `@angular/core` ^22.0.0
|
|
600
|
+
- `@angular/platform-browser` ^22.0.0
|
|
601
|
+
- `@molecule/app-angular` ^3.5.0
|
|
602
|
+
- `@molecule/app-ui` ^1.0.1
|
|
603
|
+
- `@molecule/app-ui-angular` ^1.1.0
|
|
604
|
+
|
|
605
|
+
### Runtime Dependencies
|
|
606
|
+
|
|
607
|
+
- `@angular/common`
|
|
608
|
+
- `@angular/core`
|
|
609
|
+
- `@angular/platform-browser`
|
|
610
|
+
- `@molecule/app-angular`
|
|
611
|
+
- `@molecule/app-ui`
|
|
612
|
+
- `@molecule/app-ui-angular`
|
|
613
|
+
|
|
614
|
+
- **Name collision:** `@molecule/app-ui-angular` also exports an
|
|
615
|
+
`EmptyState` (the ClassMap-token variant driven by `cm.emptyState*`).
|
|
616
|
+
Use THAT one for plain framework-styled empty states; use THIS
|
|
617
|
+
package when you want the circular icon badge
|
|
618
|
+
(`iconWrapperClassName`), per-brand chrome via `className`, a
|
|
619
|
+
`dataMolId`, or the companion `<CtaCard>`. If you import both
|
|
620
|
+
packages, alias one import to avoid the clash.
|
|
621
|
+
- All text arrives via props — translate with your `t()` calls; this
|
|
622
|
+
package has no locale bond of its own.
|
|
623
|
+
- Styling resolves through `getClassMap()` — requires a wired ClassMap
|
|
624
|
+
bond (standard molecule app setup).
|
|
625
|
+
- Node props are inputs (a string, or a `TemplateRef`) or projected
|
|
626
|
+
content selected by `[slot=<name>]`; components accept either.
|