busybar-kit 0.2.1 → 1.0.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 viirtualp1
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,148 +1,148 @@
1
- # busybar-kit
2
-
3
- > [!IMPORTANT]
4
- > **Unofficial community project.** Built and maintained by [@viirtualp1](https://github.com/viirtualp1), **not** an official Flipper Devices / BUSY product, and not affiliated with, endorsed by, or supported by them. "BUSY Bar" remains their trademark. For the real hardware and official apps, visit **[busy.app](https://busy.app/)**.
5
-
6
- Shared building blocks for [BUSY Bar](https://busy.bar) apps. Everything here is
7
- app-agnostic: screen geometry, the palette neutrals, formatters, ticker text,
8
- the Bar's error taxonomy, the connection half of a config, and an offline PNG
9
- renderer that draws the same elements the device does.
10
-
11
- It is the common half of [busybar-dota](https://github.com/viirtualp1/busybar-dota),
12
- [busybar-mydota](https://github.com/viirtualp1/busybar-mydota) and
13
- [busybar-livesplit](https://github.com/viirtualp1/busybar-livesplit).
14
-
15
- ```bash
16
- npm install busybar-kit
17
- ```
18
-
19
- `@busy-app/busy-lib` is a peer dependency — the app owns that version.
20
-
21
- ## What is in it
22
-
23
- | Import | What it gives you |
24
- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
25
- | `busybar-kit/device` | `FRONT` / `BACK` screen sizes, `FONT_WIDTH`, `textWidth`, `clipToWidth`, `fittingChars`, `rowY`, `backRowGrid` |
26
- | `busybar-kit/colors` | `BASE_COLORS` — neutrals, chrome, and the transparent value that hides an element |
27
- | `busybar-kit/format` | `formatClock`, `formatGold`, `formatCountdown`, `formatStartTime`, `formatKda`, `formatPercent`, … |
28
- | `busybar-kit/elements` | `AnyElement`, `band()`, `fillWidth()` |
29
- | `busybar-kit/ticker` | `paginate` / `pageAt` / `scrollAt` / `tickerLine`, and `EventTicker` |
30
- | `busybar-kit/errors` | `BarApiError`, `toBarError`, `isLowPriority`, `isClientError`, `isForbidden` |
31
- | `busybar-kit/config` | `loadEnvFile`, `envReader`, `loadBarConfig` |
32
- | `busybar-kit/image` | `ditherToPanel` — a picture, in the back panel's 16 greys |
33
- | `busybar-kit/preview` | `renderFront` / `renderBack` / `Bitmap` — device-accurate PNGs with no hardware |
34
- | `busybar-kit/tsconfig.json`, `busybar-kit/eslint`, `busybar-kit/prettier` | the shared toolchain |
35
- | `busybar-fix-esm` (bin) | rewrites relative imports in `dist/` to carry `.js`, for Node ESM |
36
-
37
- ## Geometry is hardware, not layout
38
-
39
- `FRONT` (72×16) and `BACK` (160×80, with its header rows and 12px grid) are
40
- facts about the device. An app spreads its own named slots on top:
41
-
42
- ```ts
43
- import { FRONT as DEVICE, BACK as DEVICE_BACK } from 'busybar-kit/device';
44
-
45
- export const FRONT = {
46
- ...DEVICE,
47
- topY: 0,
48
- bottomY: 11,
49
- clockWidth: 24,
50
- } as const;
51
- ```
52
-
53
- An app whose header is a different height lays out its own row grid, and reads
54
- rows off that instead of the default:
55
-
56
- ```ts
57
- import { backRowGrid, rowY as gridRowY } from 'busybar-kit/device';
58
-
59
- export const BACK = { ...DEVICE_BACK, ...backRowGrid(16), nameX: 8 } as const;
60
-
61
- export const rowY = (index: number) => gridRowY(index, BACK);
62
- ```
63
-
64
- `clipToWidth` takes the truncation mark as a fourth argument (`'.'` by
65
- default, `'..'` where names are cut often enough to want the emphasis).
66
-
67
- Colours work the same way — `BASE_COLORS` holds what every app needs, and the
68
- app adds its own semantics:
69
-
70
- ```ts
71
- import { BASE_COLORS } from 'busybar-kit/colors';
72
-
73
- export const COLORS = {
74
- ...BASE_COLORS,
75
- radiant: '#3FBF5FFF',
76
- dire: '#E14B3AFF',
77
- } as const;
78
- ```
79
-
80
- ## Config
81
-
82
- `loadBarConfig` resolves which Bar to talk to and over which transport, and
83
- warns about credentials that transport will ignore. That is all it covers —
84
- render cadence and request timeouts are the app's own tempo (a speedrun timer
85
- wants 60ms frames where a match ticker is happy at 200), so they stay in the
86
- app's config with `DEFAULTS` / `LIMITS` as the values worth starting from.
87
-
88
- It hands back the same env reader, so an app's own settings collect their
89
- warnings into one list:
90
-
91
- ```ts
92
- import { loadBarConfig, loadEnvFile } from 'busybar-kit/config';
93
-
94
- loadEnvFile();
95
-
96
- export function loadConfig(env = process.env) {
97
- const warnings: string[] = [];
98
- const { bar, env: read } = loadBarConfig(env, warnings);
99
-
100
- return {
101
- warnings,
102
- config: {
103
- ...bar,
104
- gsiPort: read.number('GSI_PORT', 3080, { min: 1024, max: 65_535 }),
105
- },
106
- };
107
- }
108
- ```
109
-
110
- ## Pictures
111
-
112
- The back panel has 16 greys and quantises whatever you upload to them, so a
113
- photo sent as-is comes back in bands. `ditherToPanel` does the quantising here,
114
- with error diffusion, which leaves every pixel already sitting on a level:
115
-
116
- ```ts
117
- import { ditherToPanel } from 'busybar-kit/image';
118
-
119
- const cover = ditherToPanel(decodedRgba); // 80x80 Bitmap, panel-ready
120
- await bar.AssetsUpload({ application_name: 'app', file: 'art.png', data: cover.toPng() });
121
- ```
122
-
123
- It takes pixels, not files. Which image decoder to pay for is the app's
124
- choice — the kit stays dependency-free.
125
-
126
- `Bitmap.fromRgba` wraps pixels from anywhere, and `bitmap.blit(other, x, y)`
127
- draws one into another: the raster below cannot follow an image element's path,
128
- so a preview composites the picture itself.
129
-
130
- ## Preview
131
-
132
- `renderFront` / `renderBack` rasterise the very element list you send to the
133
- device — a 3×5 pixel font, the same anchoring rules, and the back panel
134
- flattened to the 16 greys the real OLED shows. Useful for screenshots in a
135
- README and for asserting a layout in tests without a Bar on the desk.
136
-
137
- ```ts
138
- import { renderFront } from 'busybar-kit/preview';
139
-
140
- writeFileSync('front.png', renderFront(frontElements(frame)).scale(8).toPng());
141
- ```
142
-
143
- ## Scripts
144
-
145
- ```bash
146
- npm run check # lint + typecheck + test
147
- npm run build # tsc + .js extension fixup
148
- ```
1
+ # busybar-kit
2
+
3
+ > [!IMPORTANT]
4
+ > **Unofficial community project.** Built and maintained by [@viirtualp1](https://github.com/viirtualp1), **not** an official Flipper Devices / BUSY product, and not affiliated with, endorsed by, or supported by them. "BUSY Bar" remains their trademark. For the real hardware and official apps, visit **[busy.app](https://busy.app/)**.
5
+
6
+ Shared building blocks for [BUSY Bar](https://busy.bar) apps. Everything here is
7
+ app-agnostic: screen geometry, the palette neutrals, formatters, ticker text,
8
+ the Bar's error taxonomy, the connection half of a config, and an offline PNG
9
+ renderer that draws the same elements the device does.
10
+
11
+ It is the common half of [busybar-dota](https://github.com/viirtualp1/busybar-dota),
12
+ [busybar-mydota](https://github.com/viirtualp1/busybar-mydota) and
13
+ [busybar-livesplit](https://github.com/viirtualp1/busybar-livesplit).
14
+
15
+ ```bash
16
+ npm install busybar-kit
17
+ ```
18
+
19
+ `@busy-app/busy-lib` is a peer dependency — the app owns that version.
20
+
21
+ ## What is in it
22
+
23
+ | Import | What it gives you |
24
+ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
25
+ | `busybar-kit/device` | `FRONT` / `BACK` screen sizes, `FONT_WIDTH`, `textWidth`, `clipToWidth`, `fittingChars`, `rowY`, `backRowGrid` |
26
+ | `busybar-kit/colors` | `BASE_COLORS` — neutrals, chrome, and the transparent value that hides an element |
27
+ | `busybar-kit/format` | `formatClock`, `formatGold`, `formatCountdown`, `formatStartTime`, `formatKda`, `formatPercent`, … |
28
+ | `busybar-kit/elements` | `AnyElement`, `band()`, `fillWidth()` |
29
+ | `busybar-kit/ticker` | `paginate` / `pageAt` / `scrollAt` / `tickerLine`, and `EventTicker` |
30
+ | `busybar-kit/errors` | `BarApiError`, `toBarError`, `isLowPriority`, `isClientError`, `isForbidden` |
31
+ | `busybar-kit/config` | `loadEnvFile`, `envReader`, `loadBarConfig` |
32
+ | `busybar-kit/image` | `ditherToPanel` — a picture, in the back panel's 16 greys |
33
+ | `busybar-kit/preview` | `renderFront` / `renderBack` / `Bitmap` — device-accurate PNGs with no hardware |
34
+ | `busybar-kit/tsconfig.json`, `busybar-kit/eslint`, `busybar-kit/prettier` | the shared toolchain |
35
+ | `busybar-fix-esm` (bin) | rewrites relative imports in `dist/` to carry `.js`, for Node ESM |
36
+
37
+ ## Geometry is hardware, not layout
38
+
39
+ `FRONT` (72×16) and `BACK` (160×80, with its header rows and 12px grid) are
40
+ facts about the device. An app spreads its own named slots on top:
41
+
42
+ ```ts
43
+ import { FRONT as DEVICE, BACK as DEVICE_BACK } from 'busybar-kit/device';
44
+
45
+ export const FRONT = {
46
+ ...DEVICE,
47
+ topY: 0,
48
+ bottomY: 11,
49
+ clockWidth: 24,
50
+ } as const;
51
+ ```
52
+
53
+ An app whose header is a different height lays out its own row grid, and reads
54
+ rows off that instead of the default:
55
+
56
+ ```ts
57
+ import { backRowGrid, rowY as gridRowY } from 'busybar-kit/device';
58
+
59
+ export const BACK = { ...DEVICE_BACK, ...backRowGrid(16), nameX: 8 } as const;
60
+
61
+ export const rowY = (index: number) => gridRowY(index, BACK);
62
+ ```
63
+
64
+ `clipToWidth` takes the truncation mark as a fourth argument (`'.'` by
65
+ default, `'..'` where names are cut often enough to want the emphasis).
66
+
67
+ Colours work the same way — `BASE_COLORS` holds what every app needs, and the
68
+ app adds its own semantics:
69
+
70
+ ```ts
71
+ import { BASE_COLORS } from 'busybar-kit/colors';
72
+
73
+ export const COLORS = {
74
+ ...BASE_COLORS,
75
+ radiant: '#3FBF5FFF',
76
+ dire: '#E14B3AFF',
77
+ } as const;
78
+ ```
79
+
80
+ ## Config
81
+
82
+ `loadBarConfig` resolves which Bar to talk to and over which transport, and
83
+ warns about credentials that transport will ignore. That is all it covers —
84
+ render cadence and request timeouts are the app's own tempo (a speedrun timer
85
+ wants 60ms frames where a match ticker is happy at 200), so they stay in the
86
+ app's config with `DEFAULTS` / `LIMITS` as the values worth starting from.
87
+
88
+ It hands back the same env reader, so an app's own settings collect their
89
+ warnings into one list:
90
+
91
+ ```ts
92
+ import { loadBarConfig, loadEnvFile } from 'busybar-kit/config';
93
+
94
+ loadEnvFile();
95
+
96
+ export function loadConfig(env = process.env) {
97
+ const warnings: string[] = [];
98
+ const { bar, env: read } = loadBarConfig(env, warnings);
99
+
100
+ return {
101
+ warnings,
102
+ config: {
103
+ ...bar,
104
+ gsiPort: read.number('GSI_PORT', 3080, { min: 1024, max: 65_535 }),
105
+ },
106
+ };
107
+ }
108
+ ```
109
+
110
+ ## Pictures
111
+
112
+ The back panel has 16 greys and quantises whatever you upload to them, so a
113
+ photo sent as-is comes back in bands. `ditherToPanel` does the quantising here,
114
+ with error diffusion, which leaves every pixel already sitting on a level:
115
+
116
+ ```ts
117
+ import { ditherToPanel } from 'busybar-kit/image';
118
+
119
+ const cover = ditherToPanel(decodedRgba); // 80x80 Bitmap, panel-ready
120
+ await bar.AssetsUpload({ application_name: 'app', file: 'art.png', data: cover.toPng() });
121
+ ```
122
+
123
+ It takes pixels, not files. Which image decoder to pay for is the app's
124
+ choice — the kit stays dependency-free.
125
+
126
+ `Bitmap.fromRgba` wraps pixels from anywhere, and `bitmap.blit(other, x, y)`
127
+ draws one into another: the raster below cannot follow an image element's path,
128
+ so a preview composites the picture itself.
129
+
130
+ ## Preview
131
+
132
+ `renderFront` / `renderBack` rasterise the very element list you send to the
133
+ device — a 3×5 pixel font, the same anchoring rules, and the back panel
134
+ flattened to the 16 greys the real OLED shows. Useful for screenshots in a
135
+ README and for asserting a layout in tests without a Bar on the desk.
136
+
137
+ ```ts
138
+ import { renderFront } from 'busybar-kit/preview';
139
+
140
+ writeFileSync('front.png', renderFront(frontElements(frame)).scale(8).toPng());
141
+ ```
142
+
143
+ ## Scripts
144
+
145
+ ```bash
146
+ npm run check # lint + typecheck + test
147
+ npm run build # tsc + .js extension fixup
148
+ ```
package/package.json CHANGED
@@ -1,9 +1,13 @@
1
1
  {
2
2
  "name": "busybar-kit",
3
- "version": "0.2.1",
3
+ "version": "1.0.0",
4
4
  "description": "Shared building blocks for BUSY Bar apps: device geometry, colours, formatters, ticker text, error taxonomy and an offline PNG preview renderer",
5
5
  "author": "viirtualp1",
6
6
  "license": "MIT",
7
+ "bugs": {
8
+ "url": "https://github.com/viirtualp1/busybar-kit/issues"
9
+ },
10
+ "homepage": "https://github.com/viirtualp1/busybar-kit#readme",
7
11
  "type": "module",
8
12
  "repository": {
9
13
  "type": "git",
@@ -34,7 +38,8 @@
34
38
  "dist",
35
39
  "configs",
36
40
  "scripts",
37
- "README.md"
41
+ "README.md",
42
+ "LICENSE"
38
43
  ],
39
44
  "keywords": [
40
45
  "busy-bar",
@@ -1,33 +1,33 @@
1
- #!/usr/bin/env node
2
- import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
3
- import { isAbsolute, join, resolve } from 'node:path';
4
-
5
- // Node's ESM loader wants a real file name; tsc leaves extensionless specifiers.
6
- const argument = process.argv[2] ?? 'dist';
7
- const dist = isAbsolute(argument) ? argument : resolve(process.cwd(), argument);
8
- const EXTENSIONS = /\.(?:js|json|mjs|cjs|node)$/;
9
-
10
- function walk(dir) {
11
- for (const name of readdirSync(dir)) {
12
- const path = join(dir, name);
13
- if (statSync(path).isDirectory()) {
14
- walk(path);
15
- continue;
16
- }
17
- if (!/\.(?:js|d\.ts)$/.test(name)) {
18
- continue;
19
- }
20
-
21
- const source = readFileSync(path, 'utf8');
22
- const next = source.replace(
23
- /(from\s+|import\s*\()(['"])(\.[^'"]+)\2/g,
24
- (match, prefix, quote, spec) =>
25
- EXTENSIONS.test(spec) ? match : `${prefix}${quote}${spec}.js${quote}`,
26
- );
27
- if (next !== source) {
28
- writeFileSync(path, next);
29
- }
30
- }
31
- }
32
-
33
- walk(dist);
1
+ #!/usr/bin/env node
2
+ import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
3
+ import { isAbsolute, join, resolve } from 'node:path';
4
+
5
+ // Node's ESM loader wants a real file name; tsc leaves extensionless specifiers.
6
+ const argument = process.argv[2] ?? 'dist';
7
+ const dist = isAbsolute(argument) ? argument : resolve(process.cwd(), argument);
8
+ const EXTENSIONS = /\.(?:js|json|mjs|cjs|node)$/;
9
+
10
+ function walk(dir) {
11
+ for (const name of readdirSync(dir)) {
12
+ const path = join(dir, name);
13
+ if (statSync(path).isDirectory()) {
14
+ walk(path);
15
+ continue;
16
+ }
17
+ if (!/\.(?:js|d\.ts)$/.test(name)) {
18
+ continue;
19
+ }
20
+
21
+ const source = readFileSync(path, 'utf8');
22
+ const next = source.replace(
23
+ /(from\s+|import\s*\()(['"])(\.[^'"]+)\2/g,
24
+ (match, prefix, quote, spec) =>
25
+ EXTENSIONS.test(spec) ? match : `${prefix}${quote}${spec}.js${quote}`,
26
+ );
27
+ if (next !== source) {
28
+ writeFileSync(path, next);
29
+ }
30
+ }
31
+ }
32
+
33
+ walk(dist);