@molecule/app-stage-timeline-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 +375 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,382 @@
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:25.461Z
7
+ -->
8
+
1
9
  # @molecule/app-stage-timeline-angular
2
10
 
3
- Multi-stage horizontal progress timeline with current marker — onboarding, applicant tracking, kanban status flow
11
+ Angular multi-stage horizontal progress timeline with a current-stage marker.
12
+ Used by employee-onboarding, applicant-tracking, kanban-board status
13
+ flows, and order-fulfillment progress trackers.
14
+
15
+ Exports `<div mol-stage-timeline>` and `statusOf` — the Angular counterpart
16
+ of `@molecule/app-stage-timeline-react`, with the same props (React names)
17
+ and the same DOM for the same input.
18
+
19
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
20
+ > It is written to be read by coding agents as much as by people, and is generated from this
21
+ > package's source — edit `src/index.ts` JSDoc, not this file.
22
+
23
+ ## Quick Start
24
+
25
+ ```ts
26
+ import { Component } from '@angular/core'
27
+ import { StageTimeline } from '@molecule/app-stage-timeline-angular'
28
+
29
+ @Component({
30
+ selector: 'app-hiring',
31
+ standalone: true,
32
+ imports: [StageTimeline],
33
+ template: `<div mol-stage-timeline [stages]="stages" [currentIndex]="2"></div>`,
34
+ })
35
+ export class HiringPage {
36
+ stages = [
37
+ { id: 'applied', label: 'Applied' },
38
+ { id: 'screen', label: 'Phone Screen' },
39
+ { id: 'onsite', label: 'On-site' },
40
+ { id: 'offer', label: 'Offer' },
41
+ ]
42
+ }
43
+ ```
44
+
45
+ ## Type
46
+
47
+ `feature`
48
+
49
+ ## Installation
50
+
51
+ ```bash
52
+ npm install @molecule/app-stage-timeline-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-i18n @molecule/app-ui @molecule/app-ui-angular
53
+ ```
54
+
55
+ ## API
56
+
57
+ ### Interfaces
58
+
59
+ #### `StageTimelineStage`
60
+
61
+ A single stage on the timeline.
62
+
63
+ ```typescript
64
+ interface StageTimelineStage {
65
+ /** Stable id (used as the render key + `data-stage-id`). */
66
+ id: string
67
+ /** Stage label: a template reference (a node), or text. */
68
+ label: string | number | TemplateRef<unknown>
69
+ /** Optional secondary line (timestamp, owner, etc.): a template reference, or text. */
70
+ subtitle?: string | number | TemplateRef<unknown>
71
+ /** Optional click handler. */
72
+ onClick?: () => void
73
+ }
74
+ ```
75
+
76
+ #### `StageTimelineProps`
77
+
78
+ Props accepted by {@link StageTimeline} — the same props
79
+ `@molecule/app-stage-timeline-react` accepts. Node-valued stage fields
80
+ (`label`, `subtitle`) are template references in Angular (an input cannot
81
+ carry a node), or plain text.
82
+
83
+ ```typescript
84
+ interface StageTimelineProps {
85
+ /** Ordered stages to render, left-to-right. */
86
+ stages: StageTimelineStage[]
87
+ /**
88
+ * Index of the **current** stage (0-based). Stages before this index
89
+ * are rendered as `completed`; stages after are rendered as `upcoming`.
90
+ * Pass `-1` to render every stage as upcoming (e.g. before kickoff).
91
+ * Pass `stages.length` to render every stage as completed (process done).
92
+ */
93
+ currentIndex: number
94
+ /** `data-mol-id` attribute for AI-agent selectors. */
95
+ dataMolId?: string
96
+ /** Extra classes appended via the ClassMap `cn()` helper. */
97
+ className?: string
98
+ }
99
+ ```
100
+
101
+ ### Types
102
+
103
+ #### `StageStatus`
104
+
105
+ Per-stage rendering state.
106
+
107
+ ```typescript
108
+ type StageStatus = 'completed' | 'current' | 'upcoming'
109
+ ```
110
+
111
+ ### Classes
112
+
113
+ #### `StageTimeline`
114
+
115
+ StageTimeline component.
116
+
117
+ Multi-stage horizontal progress timeline with a current-stage marker. The
118
+ host IS the root `<div>` (`div[mol-stage-timeline]`), matching React's root
119
+ exactly: `role="list"` + the accessible label on the host, the connector rail
120
+ and one marker per stage inside it. Node-valued stage fields (`label`,
121
+ `subtitle`) are `ng-template` references rendered through
122
+ {@link NgTemplateOutlet}; string / number fields render as text.
123
+
124
+ ```typescript
125
+ @Component({
126
+ selector: 'div[mol-stage-timeline]',
127
+ standalone: true,
128
+ imports: [NgTemplateOutlet],
129
+ inputs: ['stages', 'currentIndex', 'dataMolId', 'className'],
130
+ host: {
131
+ role: 'list',
132
+ '[class]': 'classes()',
133
+ '[attr.data-mol-id]': "dataMolId ?? 'stage-timeline'",
134
+ '[attr.aria-label]': 'groupLabel()',
135
+ '[style]': 'rootStyle()',
136
+ },
137
+ // prettier-ignore
138
+ template: `
139
+ @if (stages.length > 0) {
140
+ <div aria-hidden="true" [style]="railStyle()" data-mol-id="stage-timeline-rail"><div style="position: absolute; inset: 0px; background: var(--mol-color-surface-variant, rgba(0,0,0,0.12))"></div><div data-mol-id="stage-timeline-rail-fill" [style]="fillStyle()"></div></div>
141
+ @for (stage of stages; track stage.id; let i = $index) {
142
+ <div role="listitem" [attr.data-stage-id]="stage.id" [attr.data-stage-status]="statusOfIndex(i)" data-mol-id="stage-timeline-stage" [attr.aria-current]="isCurrent(i) ? 'step' : null" [attr.aria-label]="stageAria(stage, i)" [style]="stageWrapperStyle()">
143
+ <button type="button" (click)="handleClick(stage, $event)" [disabled]="!stage.onClick" [attr.aria-label]="stageAria(stage, i)" data-mol-id="stage-timeline-dot" [style]="dotStyle(stage, i)">{{ dotText(i) }}</button>
144
+ <span [class]="labelClasses(i)" data-mol-id="stage-timeline-label" [style]="labelStyle(i)">@if (isTemplate(stage.label)) {<ng-container [ngTemplateOutlet]="templateOf(stage.label)"></ng-container>}@else {{{ textOf(stage.label) }}}</span>
145
+ @if (stage.subtitle) {
146
+ <span [class]="subtitleClasses()" data-mol-id="stage-timeline-subtitle" style="text-align: center; color: var(--mol-color-on-surface-variant, #888)">@if (isTemplate(stage.subtitle)) {<ng-container [ngTemplateOutlet]="templateOf(stage.subtitle)"></ng-container>}@else {{{ textOf(stage.subtitle) }}}</span>
147
+ }
148
+ </div>
149
+ }
150
+ }
151
+ `,
152
+ })
153
+ export class StageTimeline {
154
+ /** Ordered stages to render, left-to-right. */
155
+ stages: StageTimelineStage[] = []
156
+ currentIndex = 0
157
+ /** `data-mol-id` attribute for AI-agent selectors. */
158
+ dataMolId?: string
159
+ /** Extra classes appended via the ClassMap `cn()` helper. */
160
+ className?: string
161
+
162
+ /** The i18n handle (locale-reactive), read in an injection context. */
163
+ private readonly i18n = useTranslation()
4
164
 
165
+ /** The current class map. */
166
+ cm(): UIClassMap {
167
+ return getClassMap()
168
+ }
169
+
170
+ /** Computes the root's class list. */
171
+ classes(): string {
172
+ return this.cm().cn(this.className)
173
+ }
174
+
175
+ /** The root's accessible label. */
176
+ groupLabel(): string {
177
+ return this.i18n.t('stageTimeline.group', {}, { defaultValue: 'Stage timeline' })
178
+ }
179
+
180
+ /** The root's inline style — the grid geometry has no ClassMap resolver — or no style at all for an empty stage list (React's early return). */
181
+ rootStyle(): string {
182
+ if (this.stages.length === 0) return ''
183
+ return `position: relative; display: grid; grid-template-columns: repeat(${this.stages.length}, minmax(0, 1fr)); align-items: start`
184
+ }
185
+
186
+ /** The connector rail's inline style (hidden behind the dots). */
187
+ railStyle(): string {
188
+ const inset = `${(0.5 / this.stages.length) * 100}%`
189
+ return `position: absolute; top: 14px; left: ${inset}; right: ${inset}; height: 2px; pointer-events: none`
190
+ }
191
+
192
+ /** The rail's filled portion: how full it should be (0–100%). */
193
+ fillStyle(): string {
194
+ const denom = Math.max(1, this.stages.length - 1)
195
+ const fillRatio = Math.max(0, Math.min(1, this.currentIndex / denom))
196
+ return `position: absolute; top: 0px; bottom: 0px; left: 0px; width: ${
197
+ fillRatio * 100
198
+ }%; background: var(--mol-color-primary, #3366ff); transition: width 200ms ease`
199
+ }
200
+
201
+ /** A stage's rendering status. */
202
+ statusOfIndex(i: number): StageStatus {
203
+ return statusOf(i, this.currentIndex)
204
+ }
205
+
206
+ /** Whether a stage is the current one. */
207
+ isCurrent(i: number): boolean {
208
+ return this.statusOfIndex(i) === 'current'
209
+ }
210
+
211
+ /** Whether a stage is completed. */
212
+ isCompleted(i: number): boolean {
213
+ return this.statusOfIndex(i) === 'completed'
214
+ }
215
+
216
+ /** The marker's text: a tick for a completed stage, its position otherwise. */
217
+ dotText(i: number): string {
218
+ return this.isCompleted(i) ? '✓' : String(i + 1)
219
+ }
220
+
221
+ /** The stage's accessible label, built from React's i18n key and default message (only a plain string label is carried into it). */
222
+ stageAria(stage: StageTimelineStage, i: number): string {
223
+ return this.i18n.t(
224
+ 'stageTimeline.stage',
225
+ {
226
+ label: typeof stage.label === 'string' ? stage.label : '',
227
+ index: i + 1,
228
+ total: this.stages.length,
229
+ status: this.statusOfIndex(i),
230
+ },
231
+ { defaultValue: 'Stage {{index}} of {{total}}: {{label}} ({{status}})' },
232
+ )
233
+ }
234
+
235
+ /** The wrapper column's inline style. */
236
+ stageWrapperStyle(): string {
237
+ return 'position: relative; z-index: 1; display: flex; flex-direction: column; align-items: center; gap: 6px; min-width: 0px'
238
+ }
239
+
240
+ /** The dot's inline style — geometry and status colors have no ClassMap resolver, and every color is a `--mol-color-*` token. */
241
+ dotStyle(stage: StageTimelineStage, i: number): string {
242
+ const completed = this.isCompleted(i)
243
+ const current = this.isCurrent(i)
244
+ const parts = [
245
+ 'width: 28px',
246
+ 'height: 28px',
247
+ 'border-radius: 50%',
248
+ `border: 2px solid ${
249
+ completed || current
250
+ ? 'var(--mol-color-primary, #3366ff)'
251
+ : 'var(--mol-color-outline, rgba(0,0,0,0.25))'
252
+ }`,
253
+ `background: ${
254
+ completed
255
+ ? 'var(--mol-color-primary, #3366ff)'
256
+ : current
257
+ ? 'var(--mol-color-primary-container, rgba(51,102,255,0.18))'
258
+ : 'var(--mol-color-surface, transparent)'
259
+ }`,
260
+ `color: ${completed ? 'var(--mol-color-on-primary, #fff)' : 'inherit'}`,
261
+ 'display: inline-flex',
262
+ 'align-items: center',
263
+ 'justify-content: center',
264
+ 'font-size: 14px',
265
+ 'font-weight: 700',
266
+ `cursor: ${stage.onClick ? 'pointer' : 'default'}`,
267
+ ]
268
+ if (current)
269
+ parts.push('box-shadow: 0 0 0 4px var(--mol-color-primary-container, rgba(51,102,255,0.18))')
270
+ parts.push('transition: box-shadow 200ms ease, background 200ms ease')
271
+ // React merges `{ ...dotStyle, padding: 0 }` onto the button.
272
+ parts.push('padding: 0px')
273
+ return parts.join('; ')
274
+ }
275
+
276
+ /** The label span's class list. */
277
+ labelClasses(i: number): string {
278
+ const cm = this.cm()
279
+ return cm.cn(cm.textSize('xs'), cm.fontWeight(this.isCurrent(i) ? 'semibold' : 'normal'))
280
+ }
281
+
282
+ /** The label span's inline style. */
283
+ labelStyle(i: number): string {
284
+ const color = this.isCurrent(i)
285
+ ? 'var(--mol-color-primary, #3366ff)'
286
+ : this.isCompleted(i)
287
+ ? 'var(--mol-color-on-surface, inherit)'
288
+ : 'var(--mol-color-on-surface-variant, #666)'
289
+ return `text-align: center; color: ${color}`
290
+ }
291
+
292
+ /** The subtitle span's class list. */
293
+ subtitleClasses(): string {
294
+ return this.cm().textSize('xs')
295
+ }
296
+
297
+ /** Calls a stage's own click handler with the native event, as React's `onClick={stage.onClick}` does. */
298
+ handleClick(stage: StageTimelineStage, event: Event): void {
299
+ const onClick = stage.onClick as ((event: Event) => void) | undefined
300
+ onClick?.(event)
301
+ }
302
+
303
+ /** Whether a stage field holds a node (an `ng-template` reference) rather than text. */
304
+ isTemplate(value: unknown): value is TemplateRef<unknown> {
305
+ return value instanceof TemplateRef
306
+ }
307
+
308
+ /** Narrows a value to an embedded template. */
309
+ templateOf(value: unknown): TemplateRef<unknown> | null {
310
+ return value instanceof TemplateRef ? value : null
311
+ }
312
+
313
+ /** The text a stage field renders (React renders strings and numbers as text). */
314
+ textOf(value: unknown): string {
315
+ return typeof value === 'string' || typeof value === 'number' ? String(value) : ''
316
+ }
317
+ }
5
318
  ```
6
- npm install @molecule/app-stage-timeline-angular
319
+
320
+ _(Member comments are shortened to their first sentence, and the longest is left out to fit; the full declaration is in `node_modules/@molecule/app-stage-timeline-angular/dist/stage-timeline.component.d.ts`.)_
321
+
322
+ ### Functions
323
+
324
+ #### `statusOf(i, currentIndex)`
325
+
326
+ Resolve a stage's rendering status given its index and the current index.
327
+
328
+ ```typescript
329
+ function statusOf(i: number, currentIndex: number): StageStatus
7
330
  ```
8
331
 
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.
332
+ - `i` — Zero-based stage index.
333
+ - `currentIndex` — Index of the current stage (`-1` = none, `len` = all done).
334
+
335
+ **Returns:** The rendering status for stage `i`.
336
+
337
+ ## Injection Notes
338
+
339
+ ### Requirements
340
+
341
+ Peer dependencies:
342
+
343
+ - `@angular/common` ^22.0.0
344
+ - `@angular/core` ^22.0.0
345
+ - `@angular/platform-browser` ^22.0.0
346
+ - `@molecule/app-angular` ^3.5.0
347
+ - `@molecule/app-i18n` ^1.0.1
348
+ - `@molecule/app-ui` ^1.0.1
349
+ - `@molecule/app-ui-angular` ^1.1.0
350
+
351
+ ### Runtime Dependencies
352
+
353
+ - `@angular/common`
354
+ - `@angular/core`
355
+ - `@angular/platform-browser`
356
+ - `@molecule/app-angular`
357
+ - `@molecule/app-i18n`
358
+ - `@molecule/app-ui`
359
+ - `@molecule/app-ui-angular`
360
+
361
+ - Must render inside the app's i18n provider and with a ClassMap bond
362
+ wired (`useTranslation()` / `getClassMap()` throw otherwise).
363
+ - Colors are read from `--mol-color-primary`, `--mol-color-on-primary`,
364
+ `--mol-color-primary-container`, `--mol-color-outline`,
365
+ `--mol-color-surface(-variant)`, `--mol-color-on-surface(-variant)`
366
+ CSS custom properties with hardcoded light-theme fallbacks
367
+ (blue #3366ff, black-alpha grays). Define those `--mol-color-*`
368
+ variables in your theme (both light and dark) or the timeline stays
369
+ default-blue and looks wrong in dark mode.
370
+ - `currentIndex` semantics: stages before it render completed, after
371
+ it upcoming; pass `-1` for "not started" and `stages.length` for
372
+ "all done".
373
+ - Stage dots render as buttons but are disabled unless that stage has
374
+ an `onClick`.
375
+ - Node-valued stage fields (`label`, `subtitle`) are `ng-template`
376
+ references or plain text, as React's `ReactNode` fields are.
377
+ - Stages are tracked by `id` (`@for (… ; track stage.id)`), so a re-passed
378
+ or re-ordered list keeps each marker's DOM the way React's `key` does.
379
+
380
+ ## Translations
10
381
 
11
- License: Apache-2.0
382
+ Translation strings are provided by `@molecule/app-locales-stage-timeline`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-stage-timeline-angular",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Multi-stage horizontal progress timeline with current marker — onboarding, applicant tracking, kanban status flow",
5
5
  "homepage": "https://www.molecule.dev/packages/app-stage-timeline-angular",
6
6
  "type": "module",
@@ -58,12 +58,12 @@
58
58
  "@angular/compiler-cli": "22.2.3",
59
59
  "@angular/core": "22.2.3",
60
60
  "@angular/platform-browser": "22.2.3",
61
- "@molecule/app-angular": "3.7.2",
61
+ "@molecule/app-angular": "3.9.0",
62
62
  "@molecule/app-framework-conformance": "0.0.0",
63
63
  "@molecule/app-i18n": "1.2.2",
64
64
  "@molecule/app-icons": "1.0.4",
65
- "@molecule/app-ui": "1.4.0",
66
- "@molecule/app-ui-angular": "1.2.1",
65
+ "@molecule/app-ui": "1.5.0",
66
+ "@molecule/app-ui-angular": "1.3.1",
67
67
  "@molecule/app-ui-tailwind": "1.3.0",
68
68
  "@testing-library/dom": "10.4.2",
69
69
  "@types/node": "26.6.5",