@dreamworld/dw-chip-select 1.1.4 → 1.1.5-migrate-circleci-to-github-actions.1

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.
@@ -0,0 +1,58 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+ - 'feature/**'
8
+
9
+ concurrency:
10
+ group: release-${{ github.ref }}
11
+ cancel-in-progress: false
12
+
13
+ permissions:
14
+ contents: write # push release tags and create GitHub releases
15
+ issues: write # comment on issues resolved by a release
16
+ pull-requests: write # comment on pull requests included in a release
17
+
18
+ jobs:
19
+ release-snapshot:
20
+ if: startsWith(github.ref, 'refs/heads/feature/')
21
+ runs-on: ubuntu-latest
22
+ steps:
23
+ - uses: actions/checkout@v4
24
+ with:
25
+ fetch-depth: 0 # semantic-release needs full history and tags
26
+ - uses: actions/setup-node@v4
27
+ with:
28
+ node-version: lts/*
29
+ cache: yarn
30
+ - run: yarn install --frozen-lockfile --non-interactive
31
+ - name: Deploy
32
+ env:
33
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
34
+ NPM_TOKEN: ${{ secrets.SNAPSHOT_NPM_TOKEN }}
35
+ NPM_PACKAGE_SCOPE: ${{ secrets.NPM_PACKAGE_SCOPE }}
36
+ NPM_SNAPSHOT_REPO: ${{ secrets.NPM_SNAPSHOT_REPO }}
37
+ run: |
38
+ npm config set "${NPM_PACKAGE_SCOPE}:registry" "${NPM_SNAPSHOT_REPO}"
39
+ npx semantic-release
40
+
41
+ release:
42
+ if: github.ref == 'refs/heads/main'
43
+ runs-on: ubuntu-latest
44
+ steps:
45
+ - uses: actions/checkout@v4
46
+ with:
47
+ fetch-depth: 0 # semantic-release needs full history and tags
48
+ - uses: actions/setup-node@v4
49
+ with:
50
+ node-version: lts/*
51
+ cache: yarn
52
+ - run: yarn install --frozen-lockfile --non-interactive
53
+ - run: echo "Running release job"
54
+ - name: Deploy
55
+ env:
56
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
57
+ NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
58
+ run: npx semantic-release
package/README.md CHANGED
@@ -1,3 +1,258 @@
1
1
  # `<dw-chip-select>` [![Published on npm](https://img.shields.io/npm/v/@dreamworld/dw-chip-select.svg)](https://www.npmjs.com/package/@dreamworld/dw-chip-select)
2
2
 
3
- Chips are compact elements that represent an input, attribute, or action.
3
+ Compact, interactive chip elements that allow users to filter, choose, or input values — built as LitElement-based web components.
4
+
5
+ ---
6
+
7
+ ## 1. User Guide
8
+
9
+ ### Installation & Setup
10
+
11
+ ```bash
12
+ yarn add @dreamworld/dw-chip-select
13
+ ```
14
+
15
+ Import the component module (registers both `<dw-chip-select>` and `<dw-chip>` custom elements):
16
+
17
+ ```javascript
18
+ import "@dreamworld/dw-chip-select";
19
+ ```
20
+
21
+ Load Material Icons font (required for the leading checkmark icon in filter chips):
22
+
23
+ ```html
24
+ <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Material+Icons&display=block&display=swap">
25
+ ```
26
+
27
+ ---
28
+
29
+ ### Basic Usage
30
+
31
+ #### Filter chip (multi-select)
32
+
33
+ ```html
34
+ <dw-chip-select
35
+ label="Status"
36
+ .items=${["Active", "Inactive", "Pending"]}
37
+ .value=${["Active"]}
38
+ @change=${(e) => console.log(e.detail)}
39
+ ></dw-chip-select>
40
+ ```
41
+
42
+ #### Choice chip (single-select) with object items
43
+
44
+ ```html
45
+ <dw-chip-select
46
+ type="choice"
47
+ label="Payment Type"
48
+ .items=${[{ name: "RECEIPT", label: "Receipt" }, { name: "PAYMENT", label: "Payment" }]}
49
+ .valueExpression=${"name"}
50
+ .valueTextProvider=${(item) => item.label}
51
+ @change=${(e) => console.log(e.detail)}
52
+ ></dw-chip-select>
53
+ ```
54
+
55
+ #### Shimmer / loading state
56
+
57
+ When `items` is `undefined` (not yet loaded), the component automatically renders a shimmer placeholder row:
58
+
59
+ ```html
60
+ <!-- items not yet set → shows shimmer chips -->
61
+ <dw-chip-select label="Loading..."></dw-chip-select>
62
+ ```
63
+
64
+ ---
65
+
66
+ ### API Reference
67
+
68
+ #### `<dw-chip-select>`
69
+
70
+ ##### Properties / Attributes
71
+
72
+ | Name | Type | Default | Required | Description |
73
+ |------|------|---------|----------|-------------|
74
+ | `type` | `String` | `"filter"` | No | Chip selection mode. One of `"filter"` (multi-select), `"choice"` (single-select), `"input"` (reserved, no toggle logic implemented). |
75
+ | `items` | `Array` | `undefined` | No | List of selectable item data. When `undefined`, shimmer placeholders are rendered. When an empty array, nothing is rendered. |
76
+ | `value` | `Array\|Object` | `undefined` | No | Current selection. Array of values for `filter` type; single value object for `choice` type. Values are compared using `valueEquator`. |
77
+ | `label` | `String` | `undefined` | No | Text label rendered above the chip row. |
78
+ | `valueTextProvider` | `Function` | `(item) => item` | No | Given an item from `items`, returns the display string for the chip. |
79
+ | `valueProvider` | `Function` | `undefined` | No | Given an item from `items`, returns the value stored in `value`. Mutually exclusive with `valueExpression`; `valueExpression` takes precedence when both are set. |
80
+ | `valueExpression` | `String` | `undefined` | No | Property key used to extract the value from each item object (e.g., `"id"`). Overrides `valueProvider` when both are provided. |
81
+ | `chipDisabledProvider` | `Function` | `undefined` | No | Given an item, returns `true` if that chip should be disabled. |
82
+ | `valueEquator` | `Function` | `(v1, v2) => v1 === v2` | No | Custom equality function used to determine whether two values are the same. Receives `(v1, v2)`, must return a `Boolean`. |
83
+ | `name` | `String` | `undefined` | No | Sets the `name` attribute for browser autofill purposes only. |
84
+
85
+ ##### Events
86
+
87
+ | Event | `detail` type | Description |
88
+ |-------|--------------|-------------|
89
+ | `change` | `Array` (filter) or `Object` (choice) | Fired after a chip is toggled and the value has actually changed (deep equality check via `lodash-es/isEqual`). `detail` is the new `value`. |
90
+
91
+ ---
92
+
93
+ #### `<dw-chip>` (sub-component)
94
+
95
+ `<dw-chip>` is rendered internally by `<dw-chip-select>` but can also be used standalone.
96
+
97
+ ##### Properties / Attributes
98
+
99
+ | Name | Type | Default | Reflect | Description |
100
+ |------|------|---------|---------|-------------|
101
+ | `type` | `String` | `"filter"` | Yes | Chip variant. `"filter"` shows a leading checkmark icon when selected; `"choice"` and `"input"` do not. |
102
+ | `value` | `String` | `undefined` | No | Text displayed inside the chip. |
103
+ | `selected` | `Boolean` | `false` | No | Whether the chip is in selected state. |
104
+ | `activated` | `Boolean` | `false` | No | Whether the chip has keyboard-activated focus styling (via `dw-ripple`). |
105
+ | `disabled` | `Boolean` | `false` | No | When `true`, the chip has `opacity: 0.5` and `pointer-events: none` (applied by the parent `<dw-chip-select>`). |
106
+ | `icon` | `String` | `"done"` | No | Material icon name shown as leading icon in `filter` type when selected. |
107
+ | `shimmer` | `Boolean` | `false` | No | When `true`, replaces chip content with an animated shimmer placeholder. |
108
+
109
+ ##### CSS Custom Properties
110
+
111
+ | Property | Default | Description |
112
+ |----------|---------|-------------|
113
+ | `--dw-chip-height` | `32px` | Height of the chip and base for border-radius calculation. |
114
+ | `--dw-chip-select-shimmer-gradiant` | `linear-gradient(to right, #f1efef, #f9f8f8, #e7e5e5)` | Background gradient for shimmer placeholders. |
115
+ | `--mdc-theme-primary` | `#02afcd` | Color applied to selected chip text and leading icon. |
116
+ | `--mdc-theme-divider-color` | `rgba(0, 0, 0, 0.12)` | Border color of unselected chips. |
117
+ | `--mdc-theme-text-secondary-on-surface` | `rgba(0, 0, 0, 0.6)` | Color of the label text above the chip row. |
118
+
119
+ ---
120
+
121
+ ### Configuration Options
122
+
123
+ #### `ChipTypes` constant (`utils.js`)
124
+
125
+ ```javascript
126
+ import { ChipTypes } from "@dreamworld/dw-chip-select/utils.js";
127
+ // ChipTypes.filter → "filter"
128
+ // ChipTypes.choice → "choice"
129
+ // ChipTypes.input → "input"
130
+ ```
131
+
132
+ #### Keyboard Navigation
133
+
134
+ When `<dw-chip-select>` is focused, the following keys are active:
135
+
136
+ | Key | Action |
137
+ |-----|--------|
138
+ | `ArrowRight` / `ArrowDown` | Move activation to next chip (wraps around) |
139
+ | `ArrowLeft` / `ArrowUp` | Move activation to previous chip (wraps around) |
140
+ | `Enter` / `Space` | Toggle the currently activated chip |
141
+
142
+ Focus via mouse click does not move activation to index 0; focus via keyboard (`Tab`) sets activation to index 0.
143
+
144
+ ---
145
+
146
+ ### Advanced Usage
147
+
148
+ #### Object items with `valueExpression`
149
+
150
+ When items are objects, use `valueExpression` to specify the key whose value is stored in `value`, and `valueTextProvider` to control the display label:
151
+
152
+ ```javascript
153
+ const items = [
154
+ { name: "RECEIPT", label: "Receipt" },
155
+ { name: "PAYMENT", label: "Payment" },
156
+ ];
157
+
158
+ html`
159
+ <dw-chip-select
160
+ type="choice"
161
+ .items=${items}
162
+ .valueExpression=${"name"}
163
+ .valueTextProvider=${(item) => item.label}
164
+ @change=${(e) => console.log(e.detail)} <!-- e.detail = "RECEIPT" or "PAYMENT" -->
165
+ ></dw-chip-select>
166
+ `;
167
+ ```
168
+
169
+ #### Object items with `valueProvider`
170
+
171
+ `valueProvider` is a function alternative to `valueExpression`. Note: `valueExpression` takes precedence if both are set.
172
+
173
+ ```javascript
174
+ html`
175
+ <dw-chip-select
176
+ .items=${items}
177
+ .valueProvider=${(item) => item.name}
178
+ .valueTextProvider=${(item) => item.label}
179
+ ></dw-chip-select>
180
+ `;
181
+ ```
182
+
183
+ #### Conditional chip disabling
184
+
185
+ ```javascript
186
+ html`
187
+ <dw-chip-select
188
+ .items=${items}
189
+ .chipDisabledProvider=${(item) => item.name === "PAYMENT"}
190
+ ></dw-chip-select>
191
+ `;
192
+ ```
193
+
194
+ #### Custom value equality
195
+
196
+ Use `valueEquator` when items are objects compared by identity rather than reference:
197
+
198
+ ```javascript
199
+ html`
200
+ <dw-chip-select
201
+ .items=${items}
202
+ .valueEquator=${(v1, v2) => v1?.id === v2?.id}
203
+ ></dw-chip-select>
204
+ `;
205
+ ```
206
+
207
+ #### Pre-selected value (filter type)
208
+
209
+ The `value` prop must be an array for `filter` type. Values in the array must match what `valueProvider`/`valueExpression` extracts (or the raw item if neither is set):
210
+
211
+ ```javascript
212
+ // items = ["India", "Norway", "Chile"] (string array, no valueExpression)
213
+ html`<dw-chip-select .items=${items} .value=${["India", "Norway"]}></dw-chip-select>`;
214
+ ```
215
+
216
+ ---
217
+
218
+ ## 2. Developer Guide / Architecture
219
+
220
+ ### Architecture Overview
221
+
222
+ The library consists of two LitElement custom elements with a clear orchestrator/leaf separation:
223
+
224
+ ```
225
+ <dw-chip-select> ← Orchestrator
226
+ └── <dw-chip> × N ← Leaf (one per item)
227
+ └── <dw-ripple> ← Visual feedback
228
+ └── <dw-icon> ← Leading checkmark (filter type only)
229
+ ```
230
+
231
+ #### `DwChipSelect` — Orchestrator (`dw-chip-select.js`)
232
+
233
+ - **Reactive properties** declare the public API; Lit schedules re-renders on change.
234
+ - **`repeat()` directive** is used for keyed rendering of the chip list, enabling efficient DOM diffing.
235
+ - **Value provider resolution** (`#_computeValueProvider`) runs in `willUpdate` whenever `valueProvider` or `valueExpression` changes, computing a unified `_valueProvider` function. Priority: `valueExpression` > `valueProvider` > identity function.
236
+ - **Selection logic** in `_onChipToggle`:
237
+ - `filter`: clones `value` array via `lodash-es/cloneDeep`, splices or appends; dispatches `change` only if `lodash-es/isEqual` detects a difference.
238
+ - `choice`: sets `value` to the single extracted item; only dispatches when item was not already selected.
239
+ - The `value` prop is never mutated in place — a new array/object reference is always produced.
240
+ - **Keyboard management**: A `window`-level `keydown` listener (attached/detached via `connectedCallback`/`disconnectedCallback`) guards on `this.focused`. Arrow keys move `_activatedIndex` with wraparound modulo. Enter/Space triggers `_onChipToggle` on the activated item.
241
+ - **Focus tracking**: `focusin`/`focusout` listeners on the host set `focused` and manage `_activatedIndex`. Mouse-initiated focus (`mousedown` flag) skips auto-activation of index 0.
242
+
243
+ #### `DwChip` — Leaf (`dw-chip.js`)
244
+
245
+ - Renders a `<dw-ripple>` for visual press/activation feedback.
246
+ - For `filter` type, renders a `<dw-icon>` with `@lit-labs/motion`'s `animate()` directive, producing an animated width transition (`hide`/`show` CSS classes) as the chip is selected/deselected.
247
+ - `shimmer` prop short-circuits the entire render to a styled placeholder `<div>`.
248
+ - `type` attribute is reflected to allow CSS attribute selectors (`[type="filter"]`).
249
+
250
+ #### Design Patterns
251
+
252
+ | Pattern | Location | Description |
253
+ |---------|----------|-------------|
254
+ | Compound component | `dw-chip-select` + `dw-chip` | Parent manages state; children are purely presentational. |
255
+ | Provider functions | `valueProvider`, `valueTextProvider`, `chipDisabledProvider`, `valueEquator` | Strategy pattern — callers inject behavior without subclassing. |
256
+ | Immutable value updates | `_onChipToggle` | `cloneDeep` + `isEqual` ensures no external mutation and no spurious `change` events. |
257
+ | Animated CSS class swap | `dw-chip._renderLeadingIcon` | `classMap` + `animate()` drives the icon show/hide transition declaratively. |
258
+ | Shimmer / skeleton loading | `items === undefined` branch | Renders fixed-count placeholder chips via `Array(2).fill({})` until data arrives. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dreamworld/dw-chip-select",
3
- "version": "1.1.4",
3
+ "version": "1.1.5-migrate-circleci-to-github-actions.1",
4
4
  "description": "Chips are compact elements that represent an input, attribute, or action.",
5
5
  "main": "dw-chip-select.js",
6
6
  "scripts": {
@@ -1,41 +0,0 @@
1
- version: 2
2
- jobs:
3
- release-snapshot:
4
- docker:
5
- - image: circleci/node:lts
6
- steps:
7
- - checkout
8
- - run: yarn install --frozen-lockfile --non-interactive
9
- - run:
10
- name: Deploy
11
- command: |
12
- export NPM_TOKEN=${SNAPSHOT_NPM_TOKEN}
13
- npm config set ${NPM_PACKAGE_SCOPE}:registry ${NPM_SNAPSHOT_REPO}
14
- npx semantic-release
15
- release:
16
- docker:
17
- - image: circleci/node:lts
18
- steps:
19
- - checkout
20
- - run: yarn install --frozen-lockfile --non-interactive
21
- - run: echo "Running release job"
22
- - run:
23
- name: Deploy
24
- command: npx semantic-release
25
-
26
- workflows:
27
- version: 2
28
- release:
29
- jobs:
30
- - release-snapshot:
31
- context: Dreamworld
32
- filters:
33
- branches:
34
- only:
35
- - /^feature\/.+$/
36
- - release:
37
- context: Dreamworld
38
- filters:
39
- branches:
40
- only:
41
- - main