physical-quantity 1.3.5 → 1.3.7
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/README.md +259 -216
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,216 +1,259 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
<physical-quantity value="
|
|
115
|
-
<uc-qty value="
|
|
116
|
-
<uc-qty value="
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
<
|
|
123
|
-
<
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
<uc-qty-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
<
|
|
142
|
-
<
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
<
|
|
156
|
-
|
|
157
|
-
</
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
<
|
|
164
|
-
<
|
|
165
|
-
<
|
|
166
|
-
<
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
[
|
|
215
|
-
[
|
|
216
|
-
[
|
|
1
|
+
# physical-quantity
|
|
2
|
+
|
|
3
|
+
Web Components for physical quantities with built-in unit conversion.
|
|
4
|
+
|
|
5
|
+
`physical-quantity` provides lightweight custom HTML elements for displaying and converting quantities directly in the page. It is designed for product specs, technical documentation, engineering content, educational material, and any interface where users benefit from viewing values in the units they already understand.
|
|
6
|
+
|
|
7
|
+
Visitors can switch units inline without leaving the page or opening a separate converter, keeping content compact while still giving readers access to the units they prefer.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
## Why use it
|
|
12
|
+
|
|
13
|
+
- **Built-in unit conversion** directly in the UI
|
|
14
|
+
- **570+ units across 60+ categories**
|
|
15
|
+
- **Works as standard Web Components** with no framework required
|
|
16
|
+
- **Supports single values, pairs, and triplets**
|
|
17
|
+
- **More concise than showing two unit systems side by side, with conversion among most units in the same category**
|
|
18
|
+
- **Easy to embed** in websites, docs, product pages, and CMS content
|
|
19
|
+
|
|
20
|
+
This package is especially useful when your audience spans regions, industries, or disciplines that use different unit systems. Instead of filling the page with duplicate metric and imperial values, you can present one clean quantity component and let each visitor choose from most units in the same category.
|
|
21
|
+
|
|
22
|
+
## Components
|
|
23
|
+
|
|
24
|
+
This package includes three custom elements:
|
|
25
|
+
|
|
26
|
+
### `<uc-qty>` / `<physical-quantity>`
|
|
27
|
+
Displays a single quantity with a value field and a unit selector.
|
|
28
|
+
|
|
29
|
+
### `<uc-qty-pair>`
|
|
30
|
+
Displays two quantities that share the same unit. Useful for:
|
|
31
|
+
- dimensions (`width x height`)
|
|
32
|
+
- coordinate pairs
|
|
33
|
+
- value ranges
|
|
34
|
+
|
|
35
|
+
### `<uc-qty-triplet>`
|
|
36
|
+
Displays three quantities that share the same unit. Useful for:
|
|
37
|
+
- 3D dimensions (`length x width x height`)
|
|
38
|
+
- 3D coordinates
|
|
39
|
+
|
|
40
|
+
## Installation
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npm install physical-quantity
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Quick start
|
|
47
|
+
|
|
48
|
+
This package is designed to be useful with very little setup: include the script, add the custom element, and the quantity becomes unit-aware in the page.
|
|
49
|
+
|
|
50
|
+
### ESM / bundler
|
|
51
|
+
|
|
52
|
+
```html
|
|
53
|
+
<script type="module" src="node_modules/physical-quantity/dist/pq.es.js"></script>
|
|
54
|
+
|
|
55
|
+
<physical-quantity value="25.4" unit="mm"></physical-quantity>
|
|
56
|
+
<uc-qty-pair values="10x20" unit="cm"></uc-qty-pair>
|
|
57
|
+
<uc-qty-triplet values="10x20x30" unit="cm"></uc-qty-triplet>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### CDN
|
|
61
|
+
|
|
62
|
+
```html
|
|
63
|
+
<script src="https://unpkg.com/physical-quantity@latest/dist/pq.umd.js"></script>
|
|
64
|
+
|
|
65
|
+
<physical-quantity value="25.4" unit="mm"></physical-quantity>
|
|
66
|
+
<uc-qty value="2" unit="lbm" decimal-places="2"></uc-qty>
|
|
67
|
+
<uc-qty-pair values="10x20" unit="cm"></uc-qty-pair>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## What it looks like
|
|
71
|
+
|
|
72
|
+
[Watch the demo on YouTube Shorts](https://www.youtube.com/shorts/Cg2H7P_D3fo)⭐ **NEW**
|
|
73
|
+
[Live Demo 0 - primary usages](https://v2-docs.donwen.com/demo/pq-samples-less.html) ⭐ **NEW**
|
|
74
|
+
[Live Demo 1 - technical writing](https://v2-docs.donwen.com/fun-calculations/slingshot-stress-calculation.html)
|
|
75
|
+
[Live Demo 2 - typical product specs](https://v2-docs.donwen.com/demo/products/quik2.html)
|
|
76
|
+
[Live Demo 3 - typical product specs](https://v2-docs.donwen.com/demo/products/motioncanada/gates-a36.html)
|
|
77
|
+
|
|
78
|
+
## Typical use cases
|
|
79
|
+
|
|
80
|
+
These components are most valuable anywhere physical measurements appear in content, specifications, or interfaces that serve users with different unit preferences.
|
|
81
|
+
|
|
82
|
+
### E-commerce product pages
|
|
83
|
+
Show dimensions, weight, power, capacity, and other specifications in a way that international customers can immediately understand.
|
|
84
|
+
|
|
85
|
+
### Technical documentation and manuals
|
|
86
|
+
Let readers switch units without scanning conversion tables or leaving the page.
|
|
87
|
+
|
|
88
|
+
### Scientific and engineering content
|
|
89
|
+
Present measurements in a format that adapts to the reader’s preferred unit system without duplicating values throughout the page.
|
|
90
|
+
|
|
91
|
+
### Educational material
|
|
92
|
+
Help students and learners interact with values in familiar units while reinforcing unit literacy.
|
|
93
|
+
|
|
94
|
+
### Medical and health content
|
|
95
|
+
Support user-friendly presentation of measurements such as kg/lb, °C/°F, ml/oz, and similar values.
|
|
96
|
+
|
|
97
|
+
## Features
|
|
98
|
+
|
|
99
|
+
The package focuses on practical display and conversion rather than forcing users to leave the page for a separate conversion workflow.
|
|
100
|
+
|
|
101
|
+
- **570+ units across 60+ categories** — from common everyday measurements to engineering and scientific quantities such as Flow Rate, Viscosity, Electrical values, Density, Pressure, Temperature, and more
|
|
102
|
+
- Automatic conversion within the same unit category
|
|
103
|
+
- Customizable decimal places
|
|
104
|
+
- Integers displayed without unnecessary trailing decimals
|
|
105
|
+
- Clean, compact UI
|
|
106
|
+
- No framework required
|
|
107
|
+
- Works well for inline specs and structured dimensional data
|
|
108
|
+
|
|
109
|
+
## Usage
|
|
110
|
+
|
|
111
|
+
### Single quantity
|
|
112
|
+
|
|
113
|
+
```html
|
|
114
|
+
<physical-quantity value="25.4" unit="mm" decimal-places="4"></physical-quantity>
|
|
115
|
+
<uc-qty value="2.5" unit="kg" decimal-places="4"></uc-qty>
|
|
116
|
+
<uc-qty value="25.4" unit="mm" show-unit-arrow="false"></uc-qty>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Quantity pair
|
|
120
|
+
|
|
121
|
+
```html
|
|
122
|
+
<uc-qty-pair values="10x20" unit="cm"></uc-qty-pair>
|
|
123
|
+
<uc-qty-pair values="(10, 20)" unit="cm"></uc-qty-pair>
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Quantity triplet
|
|
127
|
+
|
|
128
|
+
```html
|
|
129
|
+
<uc-qty-triplet values="10x20x30" unit="cm"></uc-qty-triplet>
|
|
130
|
+
<uc-qty-triplet values="(10, 20, 30)" unit="cm"></uc-qty-triplet>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### More examples
|
|
134
|
+
|
|
135
|
+
```html
|
|
136
|
+
<physical-quantity value="1500" unit="g"></physical-quantity>
|
|
137
|
+
<physical-quantity value="1500" unit="psf"></physical-quantity>
|
|
138
|
+
<physical-quantity value="800" unit="kg/m³"></physical-quantity>
|
|
139
|
+
<uc-qty value="37.778" unit="°C" show-unit-arrow="false"></uc-qty>
|
|
140
|
+
<uc-qty value="100" unit="°F"></uc-qty>
|
|
141
|
+
<uc-qty value="2'-3" unit="ft-in"></uc-qty>
|
|
142
|
+
<physical-quantity value="2'-3 3/16" unit="ft-in"></physical-quantity>
|
|
143
|
+
<physical-quantity value="10" unit="kgf"></physical-quantity>
|
|
144
|
+
<physical-quantity value="10" unit="Volt"></physical-quantity>
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Rendered example: [Above Rendered in Web Browser](https://v2-docs.donwen.com/demo/pq-samples.html)
|
|
148
|
+
|
|
149
|
+
## Example page
|
|
150
|
+
|
|
151
|
+
```html
|
|
152
|
+
<!DOCTYPE html>
|
|
153
|
+
<html lang="en">
|
|
154
|
+
<head>
|
|
155
|
+
<meta charset="UTF-8">
|
|
156
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
157
|
+
<title>Physical Quantity Component Example</title>
|
|
158
|
+
<script src="https://unpkg.com/physical-quantity@latest/dist/pq.umd.js"></script>
|
|
159
|
+
</head>
|
|
160
|
+
<body>
|
|
161
|
+
<physical-quantity value="25.4" unit="mm"></physical-quantity>
|
|
162
|
+
<uc-qty value="25.4" unit="mm" decimal-places="4"></uc-qty><br>
|
|
163
|
+
<uc-qty-pair values="10x20" unit="cm"></uc-qty-pair><br>
|
|
164
|
+
<uc-qty-pair values="(10, 20)" unit="cm"></uc-qty-pair><br>
|
|
165
|
+
<uc-qty-triplet values="10x20x30" unit="cm"></uc-qty-triplet><br>
|
|
166
|
+
<uc-qty-triplet values="(10, 20, 30)" unit="cm"></uc-qty-triplet><br>
|
|
167
|
+
</body>
|
|
168
|
+
</html>
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Attributes
|
|
172
|
+
|
|
173
|
+
### Common attributes
|
|
174
|
+
|
|
175
|
+
- `value`: initial value for `<physical-quantity>` / `<uc-qty>`
|
|
176
|
+
- `unit`: initial unit
|
|
177
|
+
- `decimal-places`: number of decimal places to display; defaults to `2`
|
|
178
|
+
- `show-unit-arrow`: shows or hides the unit dropdown arrow; defaults to `true`
|
|
179
|
+
|
|
180
|
+
### Pair and triplet attribute
|
|
181
|
+
|
|
182
|
+
- `values`: used by `<uc-qty-pair>` and `<uc-qty-triplet>`
|
|
183
|
+
|
|
184
|
+
Supported formats:
|
|
185
|
+
- dimensions: `AxB` or `AxBxC`
|
|
186
|
+
- tuples: `(A, B)` or `(A, B, C)`
|
|
187
|
+
|
|
188
|
+
### Unit behavior
|
|
189
|
+
|
|
190
|
+
When `unit` is recognized in the supported library, the component enables conversion within that category.
|
|
191
|
+
|
|
192
|
+
When `unit` is not recognized, the value is still displayed, but conversion is not applied.
|
|
193
|
+
|
|
194
|
+
## For website visitors
|
|
195
|
+
|
|
196
|
+
The unit dropdown displays other available units from the same category. Users can switch units directly in the page.
|
|
197
|
+
|
|
198
|
+
## Supported units
|
|
199
|
+
|
|
200
|
+
For the full list of supported units and categories, see the [Units Reference](https://calcslive.com/help/units-reference).
|
|
201
|
+
|
|
202
|
+
> **Missing a unit or category?**
|
|
203
|
+
> Email [don.wen@calcslive.com](mailto:don.wen@calcslive.com) with suggestions.
|
|
204
|
+
|
|
205
|
+
## Use on WordPress
|
|
206
|
+
|
|
207
|
+
The same components are also available through the WordPress plugin [CalcsLive Unit Converter & Sizing Calculator for Product Pages](https://wordpress.org/plugins/calcslive-article-embed/).
|
|
208
|
+
|
|
209
|
+
That gives WordPress users a no-build option via shortcodes:
|
|
210
|
+
|
|
211
|
+
```txt
|
|
212
|
+
[calcslive_qty value="25.4" unit="mm"]
|
|
213
|
+
[calcslive_qty value="2000" unit="g"]
|
|
214
|
+
[calcslive_qty value="2" unit="in"]
|
|
215
|
+
[calcslive_qty_pair values="10x20" unit="cm"]
|
|
216
|
+
[calcslive_qty_pair values="(10, 20)" unit="cm"]
|
|
217
|
+
[calcslive_qty_triplet values="10x20x30)" unit="cm"]
|
|
218
|
+
[calcslive_qty_triplet values="(10, 20, 30)" unit="cm"]
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## Works with
|
|
222
|
+
|
|
223
|
+
- Plain HTML pages
|
|
224
|
+
- Static sites
|
|
225
|
+
- Technical documentation
|
|
226
|
+
- Product pages
|
|
227
|
+
- CMS content
|
|
228
|
+
- WordPress
|
|
229
|
+
- Framework apps that support custom elements
|
|
230
|
+
|
|
231
|
+
## Compatibility notes
|
|
232
|
+
|
|
233
|
+
Because this package is built as Web Components, it works naturally in plain HTML and in projects that can render custom elements.
|
|
234
|
+
|
|
235
|
+
For framework-based apps, the main requirement is that the framework allows custom elements to pass through to the DOM cleanly.
|
|
236
|
+
|
|
237
|
+
## Contributing
|
|
238
|
+
|
|
239
|
+
Contributions, bug reports, feature requests, and unit suggestions are welcome.
|
|
240
|
+
|
|
241
|
+
Please contact the developer for bugs, improvements, or missing units.
|
|
242
|
+
|
|
243
|
+
## Changelog
|
|
244
|
+
|
|
245
|
+
See `CHANGELOG.md` included in the package for version history.
|
|
246
|
+
|
|
247
|
+
## License
|
|
248
|
+
|
|
249
|
+
MIT License. See `LICENSE` for details.
|
|
250
|
+
|
|
251
|
+
## Contact
|
|
252
|
+
|
|
253
|
+
Questions, feedback, bug reports, or unit requests:
|
|
254
|
+
|
|
255
|
+
- Email: don.wen@calcslive.com
|
|
256
|
+
- [AutoCalcs](https://www.donwen.com/)
|
|
257
|
+
- [AutoCalcs Docs and Library](https://v2-docs.donwen.com/)
|
|
258
|
+
- [Demo](https://v2-docs.donwen.com/demo/index.html)
|
|
259
|
+
|
package/package.json
CHANGED