@molecule/app-stage-timeline-solid 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 +175 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,182 @@
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.740Z
7
+ -->
8
+
1
9
  # @molecule/app-stage-timeline-solid
2
10
 
3
- Multi-stage horizontal progress timeline with current marker — onboarding, applicant tracking, kanban status flow
11
+ Solid 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 `StageTimeline` and `statusOf` — the Solid counterpart of
16
+ `@molecule/app-stage-timeline-react`, with the same props (React names) and
17
+ 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.
4
22
 
23
+ ## Quick Start
24
+
25
+ ```tsx
26
+ import { StageTimeline } from '@molecule/app-stage-timeline-solid'
27
+
28
+ ;<StageTimeline
29
+ currentIndex={2}
30
+ stages={[
31
+ { id: 'applied', label: 'Applied' },
32
+ { id: 'screen', label: 'Phone Screen' },
33
+ { id: 'onsite', label: 'On-site' },
34
+ { id: 'offer', label: 'Offer' },
35
+ ]}
36
+ />
5
37
  ```
6
- npm install @molecule/app-stage-timeline-solid
38
+
39
+ ## Type
40
+
41
+ `feature`
42
+
43
+ ## Installation
44
+
45
+ ```bash
46
+ npm install @molecule/app-stage-timeline-solid @molecule/app-i18n @molecule/app-solid @molecule/app-ui @molecule/app-ui-solid solid-js
7
47
  ```
8
48
 
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.
49
+ ## API
50
+
51
+ ### Interfaces
52
+
53
+ #### `StageTimelineStage`
54
+
55
+ A single stage on the timeline.
56
+
57
+ ```typescript
58
+ interface StageTimelineStage {
59
+ /** Stable id (used as the render key + `data-stage-id`). */
60
+ id: string
61
+ /** Stage label (e.g. "Applied", "Phone Screen", "Offer"). */
62
+ label: JSX.Element
63
+ /** Optional secondary line (timestamp, owner, etc.). */
64
+ subtitle?: JSX.Element
65
+ /** Optional click handler. */
66
+ onClick?: () => void
67
+ }
68
+ ```
69
+
70
+ #### `StageTimelineProps`
71
+
72
+ Props for {@link StageTimeline}.
73
+
74
+ ```typescript
75
+ interface StageTimelineProps {
76
+ /** Ordered stages to render, left-to-right. */
77
+ stages: StageTimelineStage[]
78
+ /**
79
+ * Index of the **current** stage (0-based). Stages before this index
80
+ * are rendered as `completed`; stages after are rendered as `upcoming`.
81
+ * Pass `-1` to render every stage as upcoming (e.g. before kickoff).
82
+ * Pass `stages.length` to render every stage as completed (process done).
83
+ */
84
+ currentIndex: number
85
+ /** `data-mol-id` attribute for AI-agent selectors. */
86
+ dataMolId?: string
87
+ /** Extra classes appended via the ClassMap `cn()` helper. */
88
+ className?: string
89
+ }
90
+ ```
91
+
92
+ ### Types
93
+
94
+ #### `StageStatus`
95
+
96
+ Per-stage rendering state.
97
+
98
+ ```typescript
99
+ type StageStatus = 'completed' | 'current' | 'upcoming'
100
+ ```
101
+
102
+ ### Functions
103
+
104
+ #### `statusOf(i, currentIndex)`
105
+
106
+ Resolve a stage's rendering status given its index and the current index.
107
+
108
+ ```typescript
109
+ function statusOf(i: number, currentIndex: number): StageStatus
110
+ ```
111
+
112
+ - `i` — Zero-based stage index.
113
+ - `currentIndex` — Index of the current stage (`-1` = none, `len` = all done).
114
+
115
+ **Returns:** The rendering status for stage `i`.
116
+
117
+ #### `StageTimeline(props)`
118
+
119
+ Multi-stage horizontal progress timeline with a current-stage marker.
120
+ Each stage renders as a labeled circle on a connecting rail; completed
121
+ stages fill in, the current stage gets a highlighted ring, and upcoming
122
+ stages stay outlined.
123
+
124
+ React keys each stage by its `id`, so a re-passed or re-ordered stage list
125
+ keeps the rendered markers per id. Solid's `For` keys by reference, so the
126
+ rows are keyed through stable per-id records: the record for an id is created
127
+ once and reused, while the stage's content reads the CURRENT stage for that
128
+ id reactively.
129
+
130
+ ```typescript
131
+ function StageTimeline(props: StageTimelineProps): JSX.Element
132
+ ```
133
+
134
+ - `props` — Component props (see {@link StageTimelineProps}).
135
+
136
+ **Returns:** The rendered timeline.
137
+
138
+ ## Injection Notes
139
+
140
+ ### Requirements
141
+
142
+ Peer dependencies:
143
+
144
+ - `@molecule/app-i18n` ^1.0.1
145
+ - `@molecule/app-solid` ^3.5.0
146
+ - `@molecule/app-ui` ^1.0.1
147
+ - `@molecule/app-ui-solid` ^1.1.0
148
+ - `solid-js` ^1.8.0
149
+
150
+ ### Runtime Dependencies
151
+
152
+ - `@molecule/app-i18n`
153
+ - `@molecule/app-solid`
154
+ - `@molecule/app-ui`
155
+ - `@molecule/app-ui-solid`
156
+ - `solid-js`
157
+
158
+ - Must render inside the app's i18n provider and with a ClassMap bond
159
+ wired (`useTranslation()` / `getClassMap()` throw otherwise).
160
+ - Colors are read from `--mol-color-primary`, `--mol-color-on-primary`,
161
+ `--mol-color-primary-container`, `--mol-color-outline`,
162
+ `--mol-color-surface(-variant)`, `--mol-color-on-surface(-variant)`
163
+ CSS custom properties with hardcoded light-theme fallbacks
164
+ (blue #3366ff, black-alpha grays). Define those `--mol-color-*`
165
+ variables in your theme (both light and dark) or the timeline stays
166
+ default-blue and looks wrong in dark mode.
167
+ - `currentIndex` semantics: stages before it render completed, after
168
+ it upcoming; pass `-1` for "not started" and `stages.length` for
169
+ "all done".
170
+ - Stage dots render as buttons but are disabled unless that stage has
171
+ an `onClick`.
172
+ - Labels and subtitles are JSX values, as React's `ReactNode` fields are.
173
+ - Stages are keyed by `id` through stable per-id records (Solid's `For`
174
+ keys by reference), so a re-passed or re-ordered list keeps each marker's
175
+ DOM the way React's `key` does.
176
+ - This is the horizontal stage/pipeline marker; for a vertical
177
+ ordered-step list use `@molecule/app-status-timeline-solid`, and for
178
+ wizard/checkout progress chrome use `@molecule/app-stepper-solid`.
179
+
180
+ ## Translations
10
181
 
11
- License: Apache-2.0
182
+ 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-solid",
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-solid",
6
6
  "type": "module",
@@ -54,9 +54,9 @@
54
54
  "@molecule/app-framework-conformance": "0.0.0",
55
55
  "@molecule/app-i18n": "1.2.2",
56
56
  "@molecule/app-icons": "1.0.4",
57
- "@molecule/app-solid": "3.7.2",
58
- "@molecule/app-ui": "1.4.0",
59
- "@molecule/app-ui-solid": "1.1.5",
57
+ "@molecule/app-solid": "3.9.0",
58
+ "@molecule/app-ui": "1.5.0",
59
+ "@molecule/app-ui-solid": "1.2.1",
60
60
  "@molecule/app-ui-tailwind": "1.3.0",
61
61
  "@testing-library/dom": "10.4.2",
62
62
  "@types/node": "26.6.5",