pulsoicon-core 5.2.1 → 6.0.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.
Files changed (2) hide show
  1. package/README.md +17 -304
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -2,17 +2,15 @@
2
2
  <img src="https://raw.githubusercontent.com/CityPulso/PulsoIcon/main/logo.png" alt="PulsoIcon" width="160" />
3
3
  </p>
4
4
 
5
- <h1 align="center">PulsoIcon</h1>
5
+ <h1 align="center">pulsoicon-core</h1>
6
6
 
7
7
  <p align="center">
8
- <strong>9955 animated icons. Every one has its own motion.</strong><br />
9
- A drop-in replacement for lucide-react icons that comes alive on hover, also for Vue, Svelte, Jetpack Compose and SwiftUI.
8
+ <strong>9955 animated icons. Every one has its own motion.</strong>
10
9
  </p>
11
10
 
12
11
  <p align="center">
13
- <a href="https://www.npmjs.com/package/pulsoicon"><img src="https://img.shields.io/npm/v/pulsoicon?color=f2552c" alt="npm version" /></a>
14
- <a href="https://www.npmjs.com/package/pulsoicon"><img src="https://img.shields.io/npm/dm/pulsoicon?color=f2552c" alt="npm downloads" /></a>
15
- <a href="./LICENSE"><img src="https://img.shields.io/npm/l/pulsoicon?color=f2552c" alt="license" /></a>
12
+ <a href="https://www.npmjs.com/package/pulsoicon-core"><img src="https://img.shields.io/npm/v/pulsoicon-core?color=f2552c" alt="npm version" /></a>
13
+ <a href="https://github.com/CityPulso/PulsoIcon/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/pulsoicon-core?color=f2552c" alt="license" /></a>
16
14
  </p>
17
15
 
18
16
  ---
@@ -21,308 +19,23 @@
21
19
  <img src="https://raw.githubusercontent.com/CityPulso/PulsoIcon/main/PulsoIcon_README_Loop.gif" alt="PulsoIcon icons animating on hover" width="720" />
22
20
  </p>
23
21
 
24
- A bell rings. A calendar lifts its rings. A trash can opens its lid. A clock's hand goes round.
22
+ The data every PulsoIcon package is built from: the 9955 icons (their shapes and the motion of each shape), the 35 motion recipes, the solid drawings and the other names icons answer to. It has no framework in it.
25
23
 
26
- PulsoIcon gives every icon a motion written for that icon, not one effect stamped on all of them. At rest each icon is a clean 24×24 icon; it plays when someone hovers or focuses the button, link or tab it sits in.
24
+ **You normally don't install this package yourself.** `pulsoicon-react`, `pulsoicon-vue` and `pulsoicon-svelte` depend on it and install it for you. Use it directly to build PulsoIcon for another framework, or to read the icon data.
27
25
 
28
- Every one of the 9955 motions is written for this set. About 3,700 icons are drawn here, including the line-art brand logos; the rest build on the shapes of [Lucide](https://lucide.dev), [Tabler Icons](https://tabler.io/icons) and [Iconoir](https://iconoir.com), which are credited in [LICENSE](https://github.com/CityPulso/PulsoIcon/blob/main/LICENSE).
26
+ ## What is in it
29
27
 
30
- ## Why PulsoIcon
28
+ | Import | What |
29
+ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | `pulsoicon-core` | Types (`IconData`, `IconNode`, `IconMotion`, …), `RECIPES` / `RECIPE_NAMES`, `ALIASES`, `solidNodes()` and the path geometry helpers |
31
+ | `pulsoicon-core/icons/<name>` | One icon's data, e.g. `import { Bell } from "pulsoicon-core/icons/bell"` |
32
+ | `pulsoicon-core/all` | Every icon's data by kebab-case name (`ICONS`, `ICON_NAMES`) |
33
+ | `pulsoicon-core/names` | Every icon name, without loading any icon |
34
+ | `pulsoicon-core/frame` | `iconFrame(data, options)`: the resting `<svg>` as a plain element tree, exactly what the React package renders |
35
+ | `pulsoicon-core/dom` | `playIcon(svg, frame, options)`: plays an icon rendered from that tree with [Motion](https://motion.dev)'s `animate()` (Motion is then needed as a peer dependency) |
31
36
 
32
- - **9955 icons, each with its own motion**:
33
- - **About 3,700 drawn for this set**: about 2,770 line-art brand logos (CityPulso, GitHub, Slack, Spotify, OpenAI, Claude, TikTok, VS Code, Google Drive, …, most drawn after the logos collected by [Simple Icons](https://simpleicons.org)) and around 900 other icons, including lowercase a–z, animals, sports, 3D tools and icons drawn after [Phosphor](https://phosphoricons.com).
34
- - **Built on open icon sets**: all 2020 [Lucide](https://lucide.dev) icons (as of 1.68), plus the shapes of [Tabler Icons](https://tabler.io/icons) (3.50, including 264 brand logos) and [Iconoir](https://iconoir.com) (7.12).
35
- - **3042 brand logos** in all.
36
- - **Switch in one line**: same component names as lucide-react (`Calendar`, `CalendarIcon`, aliases such as `AlertCircle`) and the same props. Usually you only change the import.
37
- - **Ships only what you use**: every icon is its own module and the package is side-effect free, so bundlers keep the icons you import and drop the rest. Three icons add about 12 kB before minification.
38
- - **Plays where people point**: hover or focus anywhere on a button, link, label, tab or menu item and its icon plays.
39
- - **Respects reduced motion**: nothing moves when the system asks for less motion.
40
- - **Two dependencies**: React and [Motion](https://motion.dev).
41
-
42
- ## Install
43
-
44
- ```bash
45
- npm install pulsoicon
46
- ```
47
-
48
- Works with React 18 or newer. [Motion](https://motion.dev) (12 or newer) is installed for you; if your app already uses Motion, PulsoIcon shares that copy.
49
-
50
- The same icons, props and motion are also available for [Vue, Svelte, Android and iOS](#other-platforms).
51
-
52
- ## Quick start
53
-
54
- ```tsx
55
- import { Bell, Calendar, Trash2 } from "pulsoicon";
56
-
57
- export function Toolbar() {
58
- return (
59
- <>
60
- <button>
61
- <Bell size={20} /> Notifications
62
- </button>
63
- <button>
64
- <Calendar /> Schedule
65
- </button>
66
- <button>
67
- <Trash2 color="crimson" strokeWidth={1.5} /> Delete
68
- </button>
69
- </>
70
- );
71
- }
72
- ```
73
-
74
- Hover a button and its icon plays.
75
-
76
- ### Coming from lucide-react
77
-
78
- ```diff
79
- - import { Bell, Calendar, Trash2 } from "lucide-react";
80
- + import { Bell, Calendar, Trash2 } from "pulsoicon";
81
- ```
82
-
83
- Icon components and their props work the same. Lucide's helpers (`createLucideIcon`, `LucideProvider`, the `icons` object) are not included.
84
-
85
- ### Coming from Tabler
86
-
87
- Tabler icon names work too, without the `Icon` prefix: `IconMoodSad` is `MoodSad`, `IconHome` is `Home`, `IconBrandGithub` is `BrandGithub`. Where Lucide already has the icon, the Tabler name points to it (`Home` is `House`), and Tabler families follow Lucide's naming (`HomeDollar` is `HouseDollar`, `PhotoEdit` is `ImageEdit`).
88
-
89
- ## Props
90
-
91
- | Prop | Type | Default | Description |
92
- |---|---|---|---|
93
- | `size` | `number \| string` | `24` | Width and height |
94
- | `color` | `string` | `currentColor` | Stroke colour, and fill colour when `solid` |
95
- | `strokeWidth` | `number \| string` | `2` | Stroke width on the 24-unit grid |
96
- | `absoluteStrokeWidth` | `boolean` | `false` | Keep the stroke the same number of pixels at any size |
97
- | `solid` | `boolean` | `false` | Filled icon instead of outline (see [Solid icons](#solid-icons)) |
98
- | `animated` | `boolean` | `true` | `false` makes the icon fully static: nothing plays it, not even the ref or `play` |
99
- | `autoAnimated` | `boolean` | `true` | Play the built-in hover / focus trigger. `false` turns that off; the ref and `play` still work |
100
- | `play` | `boolean` | | `true` plays the motion, `false` returns to rest. Works with or without `autoAnimated` |
101
-
102
- `autoAnimated` and `play` only exist while the icon can animate, so TypeScript rejects `<Bell animated={false} play />`. Wrapper components that drop a prop should use the exported `DistributiveOmit<IconProps, "size">` instead of `Omit`, which would lose that check.
103
-
104
- Any other SVG attribute (`className`, `style`, `aria-label`, …) is passed to the `<svg>`. Icons render with `aria-hidden="true"`; give the surrounding button or link a label.
105
-
106
- ## When the animation plays
107
-
108
- An icon plays when the pointer enters, or focus moves into, its closest `button`, `a`, `label`, `summary`, `[role="button"]`, `[role="link"]`, `[role="tab"]` or `[role="menuitem"]`. If there is none, the icon plays on its own hover.
109
-
110
- Any other element can become the trigger with `data-icon-trigger`:
111
-
112
- ```tsx
113
- <div className="card" data-icon-trigger>
114
- <MapPin /> 3 venues near you
115
- </div>
116
- ```
117
-
118
- ### Play from code
119
-
120
- Every icon forwards a ref with `startAnimation()` and `stopAnimation()`. Both return a promise that resolves when the motion has finished, so you can `await check.current?.startAnimation()` before moving on. Set `autoAnimated={false}` when only your code should decide when it plays:
121
-
122
- ```tsx
123
- import { useRef } from "react";
124
- import { Check, type IconHandle } from "pulsoicon";
125
-
126
- function SaveButton() {
127
- const check = useRef<IconHandle>(null);
128
- return (
129
- <button onClick={() => check.current?.startAnimation()}>
130
- <Check autoAnimated={false} ref={check} /> Save
131
- </button>
132
- );
133
- }
134
- ```
135
-
136
- Or drive it from state with `play`. The motion starts when `play` turns `true` and returns to rest when it turns `false`:
137
-
138
- ```tsx
139
- <Bell autoAnimated={false} play={hasNewMessage} />
140
- ```
141
-
142
- `animated={false}` keeps an icon completely still; the ref and `play` do nothing.
143
-
144
- ## Solid icons
145
-
146
- `solid` draws the filled version of an icon, in `color`:
147
-
148
- ```tsx
149
- <Heart solid color="crimson" />
150
- ```
151
-
152
- About 1,700 icons have a filled drawing taken from the [Tabler](https://tabler.io/icons) filled set or the [Phosphor](https://phosphoricons.com) fill weight. Their source file has a `solid` list and a "Solid from …" comment. The other icons fill their closed outline shapes and cut their inner lines out of the fill, so the details stay visible. Motions that draw a stroke on (`draw`, `redraw`, …) pop in instead on filled shapes.
153
-
154
- ## Other platforms
155
-
156
- Every package draws the same 9955 icons with the same motion, from the same source. The props have the same names, defaults and meaning as in React. One version number covers them all.
157
-
158
- | Platform | Install | Package |
159
- |---|---|---|
160
- | React | `npm install pulsoicon` | [pulsoicon](https://www.npmjs.com/package/pulsoicon) |
161
- | Vue 3.5+ | `npm install pulsoicon-vue` | [pulsoicon-vue](https://www.npmjs.com/package/pulsoicon-vue) |
162
- | Svelte 5 | `npm install pulsoicon-svelte` | [pulsoicon-svelte](https://www.npmjs.com/package/pulsoicon-svelte) |
163
- | Android (Jetpack Compose) | `implementation("com.citypulso:pulsoicon:<version>")` | Maven Central |
164
- | iOS / macOS (SwiftUI) | `.package(url: "https://github.com/CityPulso/PulsoIcon.git", from: "<version>")` | Swift Package Manager |
165
-
166
- ### Vue
167
-
168
- ```vue
169
- <script setup lang="ts">
170
- import { ref } from "vue";
171
- import { Bell, Check, type IconHandle } from "pulsoicon-vue";
172
-
173
- const check = ref<IconHandle>();
174
- </script>
175
-
176
- <template>
177
- <button><Bell :size="20" /> Notifications</button>
178
- <button @click="check?.startAnimation()"><Check ref="check" :auto-animated="false" /> Save</button>
179
- </template>
180
- ```
181
-
182
- ### Svelte
183
-
184
- ```svelte
185
- <script lang="ts">
186
- import { Bell, Check } from "pulsoicon-svelte";
187
-
188
- let check: ReturnType<typeof Check>;
189
- </script>
190
-
191
- <button><Bell size={20} /> Notifications</button>
192
- <button onclick={() => check.startAnimation()}><Check bind:this={check} autoAnimated={false} /> Save</button>
193
- ```
194
-
195
- Vue and Svelte render exactly the same `<svg>` as React and play it with [Motion](https://motion.dev)'s `animate()`. They take `class` and `style` like any element.
196
-
197
- ### Android (Jetpack Compose)
198
-
199
- ```kotlin
200
- import com.citypulso.pulsoicon.PulsoIcon
201
- import com.citypulso.pulsoicon.PulsoIcons
202
- import com.citypulso.pulsoicon.icons.Bell
203
-
204
- val interactions = remember { MutableInteractionSource() }
205
- IconButton(onClick = { /* … */ }, interactionSource = interactions) {
206
- PulsoIcon(PulsoIcons.Bell, contentDescription = "Notifications", interactionSource = interactions)
207
- }
208
- ```
209
-
210
- The icon plays when the control whose `interactionSource` you pass is pressed, hovered or focused (Compose has no "closest interactive ancestor", so it is passed in). `color` defaults to `LocalContentColor`. Play from code with `play = true`, or with `rememberPulsoIconHandle()` passed as `handle` and its suspending `startAnimation()` / `stopAnimation()`. `PulsoIcons.byKey("bell")` looks an icon up by its stored key. Unused icons are removed by R8.
211
-
212
- ### iOS and macOS (SwiftUI)
213
-
214
- ```swift
215
- import PulsoIcon
216
-
217
- Button { /* … */ } label: {
218
- Label { Text("Notifications") } icon: { PulsoIconView(.bell, size: 20, play: hasNewMessage) }
219
- }
220
- ```
221
-
222
- Names start lowercase (`.bell`, `.aArrowDown`, `.bellIcon`). `color` defaults to the foreground style. A pointer hovering the icon plays it; for taps use `play` or a `PulsoIconHandle` (`await handle.startAnimation()`). `PulsoIcon.byKey("bell")` looks an icon up by its stored key. Nothing moves with Reduce Motion on.
223
-
224
- ## Finding icons
225
-
226
- ### Other names
227
-
228
- Icons also answer to the names other icon sets use: `Gear` is `Settings`, `Magnifier` is `Search`, `Cart` is `ShoppingCart`, `World` is `Globe`, `DotsHorizontal` is `Ellipsis`, and so on. Every icon is also exported with an `Icon` suffix (`BellIcon`).
229
-
230
- ### Brand logos
231
-
232
- Brand icons start with `Brand` (`BrandGithub`, `BrandSlack`, `BrandOpenai`, …). The brands added up to 3.1 are also exported without the prefix (`Github`, `Slack`); the ones added in 4.0 only with it, because many brand names are ordinary words. They are simplified line drawings made for this set, most of the newer ones drawn after the logos collected by [Simple Icons](https://simpleicons.org).
233
-
234
- All product names, logos and brands are the property of their respective owners and are used here only to refer to those products or services. Their use does not imply endorsement. Follow each brand's own guidelines when you use its logo.
235
-
236
- ### All icons at once
237
-
238
- For icon pickers and galleries, `pulsoicon/all` exports every icon by its kebab-case name. It pulls in all 9955 icons, so use it only where you need the full set:
239
-
240
- ```tsx
241
- import { ICON_NAMES, ICONS } from "pulsoicon/all";
242
-
243
- const Icon = ICONS["party-popper"];
244
- ```
245
-
246
- One icon can also be imported by path: `import { Calendar } from "pulsoicon/icons/calendar"`. To list the names without loading any icon (to build a picker that loads icons on demand), use `pulsoicon/names`:
247
-
248
- ```tsx
249
- import { ICON_NAMES, type IconName } from "pulsoicon/names";
250
-
251
- const load = (name: IconName) => import(`pulsoicon/icons/${name}`);
252
- ```
253
-
254
- ## Styling
255
-
256
- Each icon renders `<svg class="pulsoicon pulsoicon-<name>">`, so CSS can target every icon or a single one:
257
-
258
- ```css
259
- .pulsoicon {
260
- vertical-align: -0.125em;
261
- }
262
-
263
- .pulsoicon-bell {
264
- color: #f2552c;
265
- }
266
- ```
267
-
268
- ## Report a wrong icon
269
-
270
- If an icon is drawn wrong, a brand logo doesn't match the real one, or a motion looks off, please email
271
- **citypulso@gmail.com** with the icon name (for example `brand-avianca`) and, if you can, a screenshot or a link
272
- to the correct logo. Issues on GitHub are welcome too.
273
-
274
- ## Contributing
275
-
276
- ```bash
277
- npm install
278
- npm run gen # writes every platform's icon files from packages/core
279
- npm run preview # gallery of every icon at http://localhost:10205
280
- npm test
281
- npm run build
282
- ```
283
-
284
- Each icon is one data file in `packages/core/src/icons/<name>.ts`, shared by every platform: the shapes of the icon and, for each shape, an optional motion (`r` recipe from `packages/core/src/recipes.ts`, `d` delay, `x`/`y` direction, `a` amplitude, `o` pivot point on the 24×24 grid). Edit that file to change how an icon moves, then run `npm run gen`. Other names live in `packages/core/src/aliases.ts`.
285
-
286
- | Folder | What |
287
- |---|---|
288
- | `packages/core` | `pulsoicon-core`: the icons, recipes, solid drawings and the framework-free player |
289
- | `packages/react`, `packages/vue`, `packages/svelte` | The web packages; their icon files are generated |
290
- | `kotlin/` | The Android library (Gradle); `icons/` is generated and committed |
291
- | `swift/` and `Package.swift` | The Swift package; `Icons/` is generated and committed |
292
-
293
- The Kotlin and Swift recipes are written by hand; their tests check them against `packages/core` (`kotlin/`: `./gradlew :pulsoicon:testDebugUnitTest`; Swift: `swift test`). `npm run test:browser` plays icons in Chromium through React, Vue and Svelte side by side and checks that they move the same.
294
-
295
- ### Releasing
296
-
297
- `package.json` at the root holds the one version of every package. `npm run set-version -- 5.3.0` sets it everywhere; push that to `main` and CI publishes the npm packages and the Maven artifact that are not out yet, then tags `5.3.0` for Swift Package Manager.
37
+ `pulsoicon-vue` and `pulsoicon-svelte` are each a thin component around `iconFrame` and `playIcon`; [their source](https://github.com/CityPulso/PulsoIcon/tree/main/packages) shows how to wrap them.
298
38
 
299
39
  ## License
300
40
 
301
- PulsoIcon is open source under the [ISC license](https://github.com/CityPulso/PulsoIcon/blob/main/LICENSE) © CityPulso.
302
-
303
- ### What is ours, and what comes from other icon sets
304
-
305
- | Part | Origin |
306
- |---|---|
307
- | Every animation (how each icon moves) | Written for PulsoIcon |
308
- | Runtime code (`createIcon`, triggers, motion recipes) | Written for PulsoIcon |
309
- | About 3,700 icons, including about 2,770 line-art brand logos | Drawn for PulsoIcon |
310
- | Shapes of the 2020 Lucide icons | Based on [Lucide](https://lucide.dev) (ISC; some derived from Feather, MIT) |
311
- | Shapes of the icons marked "Adapted from Tabler Icons" | Based on [Tabler Icons](https://tabler.io/icons) (MIT) |
312
- | Shapes of the icons marked "Adapted from Iconoir" | Based on [Iconoir](https://iconoir.com) (MIT) |
313
- | Five icons marked "Adapted from Hugeicons" | Adapted from [Hugeicons](https://hugeicons.com) (MIT) |
314
- | Icons marked "Drawn after Phosphor Icons" | Redrawn after [Phosphor](https://phosphoricons.com) shapes (MIT) |
315
- | Solid shapes marked "Solid from Tabler Icons" / "Solid from Phosphor Icons" | Taken from the Tabler filled set and the Phosphor fill weight (MIT) |
316
- | Brand icons marked "Drawn after Simple Icons" | Drawn after the logos collected by [Simple Icons](https://simpleicons.org) (CC0) |
317
-
318
- Icons based on or drawn after Tabler Icons, Iconoir, Hugeicons, Phosphor or Simple Icons name their source in a comment at the top of their file; the Lucide icons keep their Lucide names. The full license texts are in [LICENSE](https://github.com/CityPulso/PulsoIcon/blob/main/LICENSE).
319
-
320
- ### Using PulsoIcon in your project
321
-
322
- You may use PulsoIcon freely, including in commercial and closed-source products. The one condition, from ISC and the MIT licenses of the sets above, is the notice:
323
-
324
- - **If you ship PulsoIcon** (in an app, a website bundle, a template or a library of your own), include PulsoIcon's [LICENSE](https://github.com/CityPulso/PulsoIcon/blob/main/LICENSE) file with it, for example on your "open-source licenses" or "third-party notices" page or in a `THIRD_PARTY_NOTICES` file. It already contains the notices of Lucide, Tabler Icons, Iconoir, Hugeicons and Phosphor.
325
- - **If you copy or modify icons** from PulsoIcon into your own set, keep the source comment at the top of each file, and keep the LICENSE notices.
326
- - You don't have to credit PulsoIcon inside your product's interface, although a link is always appreciated.
327
-
328
- Brand logos are trademarks of their owners. Using a brand icon doesn't imply endorsement, and you should follow each brand's own guidelines.
41
+ ISC © CityPulso. Some icon shapes come from Lucide, Tabler Icons, Iconoir, Hugeicons and Phosphor; see [LICENSE](https://github.com/CityPulso/PulsoIcon/blob/main/LICENSE) and the [repository README](https://github.com/CityPulso/PulsoIcon#license).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pulsoicon-core",
3
- "version": "5.2.1",
4
- "description": "Framework-free data and motion for PulsoIcon: 9955 icons, their per-shape motion recipes and the solid drawings. Used by pulsoicon (React), pulsoicon-vue and pulsoicon-svelte.",
3
+ "version": "6.0.1",
4
+ "description": "Framework-free data and motion for PulsoIcon: 9955 icons, their per-shape motion recipes and the solid drawings. Used by pulsoicon-react, pulsoicon-vue and pulsoicon-svelte.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "license": "ISC",