@wyattjoh/herdr-ui 0.0.0-stage → 0.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Wyatt Johnson
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/NOTICE.md ADDED
@@ -0,0 +1,15 @@
1
+ # Third-party notices
2
+
3
+ The package's code is MIT-licensed ([LICENSE](LICENSE)). The icons in `assets/icons/` keep these terms:
4
+
5
+ | File | Source |
6
+ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7
+ | `copy.svg` | [Lucide](https://lucide.dev) `copy`, byte copy from `lucide-static@1.74.0` |
8
+ | `globe.svg`, `log-in.svg`, `external-link.svg` | Lucide `globe`, `log-in`, `external-link` (path data identical to `lucide-static@1.74.0`), as bundled by the Tasks Herdr panel |
9
+ | `anchor.svg` | Feather/Lucide `anchor` (geometry identical to `feather-icons@4.29.2` and `lucide-static@0.300.0`, its line drawn as a path), as bundled by the Tasks Herdr panel |
10
+ | `anchor-off.svg` | `anchor.svg` with a diagonal slash, from the Tasks Herdr panel |
11
+ | `pin-filled.svg`, `return.svg` | First-party glyphs from the Tasks Herdr panel in the Lucide style |
12
+
13
+ Lucide is licensed under the ISC License, and the icons it derives from Feather under the MIT License; both texts are in [licenses/lucide.txt](licenses/lucide.txt).
14
+
15
+ Icons referenced through `HERDR_ICONS` (`mods/workspace-chrome/…`, `mods/files/…`) ship with Herdr and are not redistributed here.
package/README.md CHANGED
@@ -1,3 +1,95 @@
1
- # Temporary Holding Version
1
+ # @wyattjoh/herdr-ui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The Tasks Herdr panel's visual system as reusable, domain-neutral pieces for [Herdr](https://herdr.dev) mods: theme tokens and tones, the panel button and toolbar fitting, the frame and top bar, breadcrumbs and the title row, listing cards with collapsible groups, chips, tabs, the menu surface, scroll regions, empty/error/loading blocks, and icons.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ bun add @wyattjoh/herdr-ui
9
+ ```
10
+
11
+ The package ships TypeScript sources and has no runtime dependencies. Its element functions import `gpui-kit`, `gpui-base` and `herdr`, which Herdr provides at runtime, so bundle the mod with Bun and keep all three external:
12
+
13
+ ```sh
14
+ bun build src/main.ts --outfile <stage>/mods/<mod>/main.js --format esm --target bun \
15
+ --external gpui-kit --external gpui-base --external herdr
16
+ ```
17
+
18
+ Typecheck the mod against the declarations Herdr writes into its home (`~/.config/herdr-app/gpui-kit.d.ts` and `herdr.d.ts`), as the consumers already do.
19
+
20
+ ## Entry points
21
+
22
+ | Import | Holds | Imports gpui-kit or herdr |
23
+ | --------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
24
+ | `@wyattjoh/herdr-ui` | everything below plus the element functions | yes, for mod bundles |
25
+ | `@wyattjoh/herdr-ui/pure` | tokens, tones, color helpers, button style and label fitting, menu metrics, icon paths, `RecordScrolls` | no: safe in tests and a Bun-side `tsc` |
26
+ | `@wyattjoh/herdr-ui/assets` | `copyIcons`, for build scripts | no, uses `node:fs`; never import it from a mod |
27
+
28
+ ## Icons
29
+
30
+ Herdr resolves `svg()` paths against its home, so a bundled icon lives at `mods/<mod folder>/<file>`. Copy the icons into the staged folder from the build script, and build paths from the same folder name:
31
+
32
+ ```ts
33
+ // scripts/build.ts
34
+ import { copyIcons } from "@wyattjoh/herdr-ui/assets";
35
+ await copyIcons(join(stage, "mods", "my-panel"));
36
+
37
+ // src/main.ts
38
+ import { panelIcons } from "@wyattjoh/herdr-ui";
39
+ const ICONS = panelIcons("my-panel"); // ICONS.openInBrowser === "mods/my-panel/globe.svg"
40
+ ```
41
+
42
+ `HERDR_ICONS` names icons Herdr ships with its own mods (`mods/workspace-chrome/…`, `mods/files/…`); those are referenced, never copied. Icon licenses are in [NOTICE.md](NOTICE.md).
43
+
44
+ ## Example
45
+
46
+ ```ts
47
+ import { View } from "gpui-kit";
48
+ import { theme } from "herdr";
49
+ import {
50
+ button,
51
+ card,
52
+ cardHeader,
53
+ cardSection,
54
+ groupBlock,
55
+ listRow,
56
+ panelFrame,
57
+ panelIcons,
58
+ toneMap,
59
+ type Theme,
60
+ } from "@wyattjoh/herdr-ui";
61
+
62
+ const ICONS = panelIcons("my-panel");
63
+ const tone = toneMap({ running: "active", passed: "success", failed: "danger" });
64
+
65
+ export default class Panel extends View {
66
+ render() {
67
+ const t = theme() as Theme;
68
+ return panelFrame(t, "my-panel", undefined).child(
69
+ cardSection(
70
+ cardHeader(t, "runs-header", "Runs"),
71
+ card(t, "runs").child(
72
+ groupBlock(t, "runs", {
73
+ id: "runs-passed",
74
+ label: "Passed",
75
+ tone: tone("passed"),
76
+ count: 1,
77
+ rows: [listRow(t, { id: "run-1", label: "#1", title: "Build", onClick: () => {} })],
78
+ rowHeight: 34,
79
+ open: true,
80
+ first: true,
81
+ last: true,
82
+ toggle: () => {},
83
+ }),
84
+ ),
85
+ ),
86
+ );
87
+ }
88
+ }
89
+ ```
90
+
91
+ [examples/gallery/main.ts](examples/gallery/main.ts) uses every piece once.
92
+
93
+ ## Development
94
+
95
+ `bun run check` is the gate: `format:check`, `lint`, `typecheck` (Bun side, then native against an installed Herdr home), `test`, `pack:check` and `mod:check`. See [AGENTS.md](AGENTS.md).
@@ -0,0 +1,4 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
2
+ <circle cx="12" cy="5" r="3" />
3
+ <path d="M12 8v14M5 12H2a10 10 0 0 0 20 0h-3M3 3l18 18" />
4
+ </svg>
@@ -0,0 +1,4 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
2
+ <circle cx="12" cy="5" r="3" />
3
+ <path d="M12 8v14M5 12H2a10 10 0 0 0 20 0h-3" />
4
+ </svg>
@@ -0,0 +1,16 @@
1
+ <!-- @license lucide-static v1.74.0 - ISC -->
2
+ <svg
3
+ class="lucide lucide-copy"
4
+ xmlns="http://www.w3.org/2000/svg"
5
+ width="24"
6
+ height="24"
7
+ viewBox="0 0 24 24"
8
+ fill="none"
9
+ stroke="currentColor"
10
+ stroke-width="2"
11
+ stroke-linecap="round"
12
+ stroke-linejoin="round"
13
+ >
14
+ <rect width="14" height="14" x="8" y="8" rx="2" ry="2" />
15
+ <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
16
+ </svg>
@@ -0,0 +1,5 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
2
+ <path d="M15 3h6v6" />
3
+ <path d="M10 14 21 3" />
4
+ <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
5
+ </svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20M2 12h20"/></svg>
@@ -0,0 +1,5 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
2
+ <path d="m10 17 5-5-5-5" />
3
+ <path d="M15 12H3" />
4
+ <path d="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4" />
5
+ </svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M16 3H8l1 7-3 3v3h12v-3l-3-3 1-7Z" fill="currentColor"/><path d="M12 16v6"/></svg>
@@ -0,0 +1,3 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
2
+ <path d="m9 4-6 6 6 6M3 10h11a7 7 0 0 1 7 7v3" />
3
+ </svg>
@@ -0,0 +1,43 @@
1
+ ISC License
2
+
3
+ Copyright (c) 2026 Lucide Icons and Contributors
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted, provided that the above
7
+ copyright notice and this permission notice appear in all copies.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16
+
17
+ ---
18
+
19
+ The following Lucide icons are derived from the Feather project:
20
+
21
+ airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
22
+
23
+ The MIT License (MIT) (for the icons listed above)
24
+
25
+ Copyright (c) 2013-present Cole Bemis
26
+
27
+ Permission is hereby granted, free of charge, to any person obtaining a copy
28
+ of this software and associated documentation files (the "Software"), to deal
29
+ in the Software without restriction, including without limitation the rights
30
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
31
+ copies of the Software, and to permit persons to whom the Software is
32
+ furnished to do so, subject to the following conditions:
33
+
34
+ The above copyright notice and this permission notice shall be included in all
35
+ copies or substantial portions of the Software.
36
+
37
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
38
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
39
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
40
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
41
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
42
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
43
+ SOFTWARE.
package/package.json CHANGED
@@ -1,6 +1,56 @@
1
1
  {
2
2
  "name": "@wyattjoh/herdr-ui",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "The Tasks panel's visual system for Herdr mods: theme tokens, controls, chrome, listing cards, chips, tabs, menus, scroll regions, state blocks and icons.",
5
+ "keywords": [
6
+ "gpui",
7
+ "gpui-kit",
8
+ "herdr",
9
+ "ui"
10
+ ],
11
+ "homepage": "https://github.com/wyattjoh/herdr-ui#readme",
12
+ "bugs": "https://github.com/wyattjoh/herdr-ui/issues",
13
+ "license": "MIT",
14
+ "author": "Wyatt Johnson",
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/wyattjoh/herdr-ui.git"
18
+ },
19
+ "files": [
20
+ "src/**/*.ts",
21
+ "!src/**/*.test.ts",
22
+ "!src/test/**",
23
+ "assets/icons/*.svg",
24
+ "licenses/*.txt",
25
+ "NOTICE.md"
26
+ ],
27
+ "type": "module",
28
+ "sideEffects": false,
29
+ "exports": {
30
+ ".": "./src/index.ts",
31
+ "./pure": "./src/pure.ts",
32
+ "./assets": "./src/assets.ts",
33
+ "./package.json": "./package.json"
34
+ },
35
+ "publishConfig": {
36
+ "access": "public"
37
+ },
38
+ "scripts": {
39
+ "format": "oxfmt",
40
+ "format:check": "oxfmt --check",
41
+ "lint": "oxlint --deny-warnings",
42
+ "typecheck": "bun scripts/typecheck.ts",
43
+ "typecheck:bun": "tsc --noEmit",
44
+ "test": "bun test src scripts",
45
+ "pack:check": "bun scripts/pack-check.ts",
46
+ "mod:check": "bun scripts/gallery.ts",
47
+ "check": "bun run format:check && bun run lint && bun run typecheck && bun run test && bun run pack:check && bun run mod:check"
48
+ },
49
+ "devDependencies": {
50
+ "@types/bun": "1.4.4",
51
+ "lefthook": "2.2.2",
52
+ "oxfmt": "0.78.0",
53
+ "oxlint": "1.93.0",
54
+ "typescript": "7.0.2"
55
+ }
56
+ }
package/src/assets.ts ADDED
@@ -0,0 +1,33 @@
1
+ // Build-side helper: copies the bundled icons into a mod folder. Uses node:fs, so only build
2
+ // scripts import it (`@wyattjoh/herdr-ui/assets`), never a mod bundle.
3
+ import { copyFile, mkdir } from "node:fs/promises";
4
+ import { join } from "node:path";
5
+ import { fileURLToPath } from "node:url";
6
+ import { BUNDLED_ICONS, type BundledIcon } from "./icons";
7
+
8
+ /**
9
+ * The package's icon folder on disk.
10
+ */
11
+ export const ICONS_DIR: string = fileURLToPath(new URL("../assets/icons/", import.meta.url));
12
+
13
+ /**
14
+ * Copies bundled icons into a staged mod folder, where `bundledIconPaths(<folder name>)` finds
15
+ * them. Herdr's hot reload ignores symlinks, so these are real copies.
16
+ * @param modDir The staged mod folder (`<stage>/mods/<name>`).
17
+ * @param names The icons to copy; all of them by default.
18
+ * @returns The written files' paths.
19
+ */
20
+ export async function copyIcons(
21
+ modDir: string,
22
+ names: readonly BundledIcon[] = Object.keys(BUNDLED_ICONS) as BundledIcon[],
23
+ ): Promise<string[]> {
24
+ await mkdir(modDir, { recursive: true });
25
+ return Promise.all(
26
+ names.map(async (name) => {
27
+ const fileName = BUNDLED_ICONS[name];
28
+ const destination = join(modDir, fileName);
29
+ await copyFile(join(ICONS_DIR, fileName), destination);
30
+ return destination;
31
+ }),
32
+ );
33
+ }
package/src/color.ts ADDED
@@ -0,0 +1,58 @@
1
+ // Color arithmetic on `#` hex theme colors. Pure.
2
+
3
+ /**
4
+ * Parses a hex color.
5
+ * @param color `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`.
6
+ * @returns Its red, green and blue channels (0-255) and alpha (0-1), or undefined when it isn't
7
+ * hex.
8
+ */
9
+ export function hexColor(color: string): readonly [number, number, number, number] | undefined {
10
+ const digits = color.slice(1);
11
+ if (color[0] !== "#" || ![3, 4, 6, 8].includes(digits.length) || /[^\da-f]/i.test(digits))
12
+ return undefined;
13
+ const expanded = digits.length <= 4 ? [...digits].map((digit) => digit + digit).join("") : digits;
14
+ return [
15
+ parseInt(expanded.slice(0, 2), 16),
16
+ parseInt(expanded.slice(2, 4), 16),
17
+ parseInt(expanded.slice(4, 6), 16),
18
+ expanded.length === 8 ? parseInt(expanded.slice(6, 8), 16) / 255 : 1,
19
+ ];
20
+ }
21
+
22
+ /**
23
+ * Resolves the opaque paint a translucent color shows over a backing color.
24
+ * @param canvas The color on top, including its optional alpha.
25
+ * @param surface The paint behind it; only its RGB channels count.
26
+ * @returns Opaque `#rrggbb` when both are hex; otherwise the canvas, or the surface unchanged
27
+ * when the canvas is recognized as fully transparent.
28
+ */
29
+ export function opaqueOver(canvas: string, surface: string): string {
30
+ const foreground = hexColor(canvas);
31
+ const backing = hexColor(surface);
32
+ if (!foreground || !backing) return foreground?.[3] === 0 ? surface : canvas;
33
+ const alpha = foreground[3];
34
+ const channels = backing.slice(0, 3).map((channel, index) =>
35
+ Math.round(foreground[index]! * alpha + channel * (1 - alpha))
36
+ .toString(16)
37
+ .padStart(2, "0"),
38
+ );
39
+ return `#${channels.join("")}`;
40
+ }
41
+
42
+ /**
43
+ * A color with its alpha replaced, for a tinted background behind an icon of the same color.
44
+ * @param color A `#rgb`, `#rrggbb` or `#rrggbbaa` color.
45
+ * @param alpha Two hex digits of alpha, like `"1f"`.
46
+ * @returns `#rrggbb` plus the alpha.
47
+ */
48
+ export function tint(color: string, alpha: string): string {
49
+ const rgb =
50
+ color.length === 4
51
+ ? color
52
+ .slice(1)
53
+ .split("")
54
+ .map((digit) => digit + digit)
55
+ .join("")
56
+ : color.slice(1, 7);
57
+ return `#${rgb}${alpha}`;
58
+ }
package/src/icons.ts ADDED
@@ -0,0 +1,121 @@
1
+ // Icon paths for `svg()`. Herdr resolves an asset path against its home, so a bundled icon is
2
+ // `mods/<mod folder>/<file>`: the consumer's build copies the files in (`copyIcons` from
3
+ // `@wyattjoh/herdr-ui/assets`) and its code builds paths from the same folder name. Herdr's own
4
+ // icons are referenced where they ship. Pure.
5
+
6
+ /**
7
+ * Icons this package ships in `assets/icons/`, by name, as their file names. Each is a Lucide
8
+ * glyph (ISC) or a first-party one drawn in the same style; see NOTICE.md.
9
+ */
10
+ export const BUNDLED_ICONS = {
11
+ copy: "copy.svg",
12
+ globe: "globe.svg",
13
+ logIn: "log-in.svg",
14
+ externalLink: "external-link.svg",
15
+ anchor: "anchor.svg",
16
+ anchorOff: "anchor-off.svg",
17
+ pinFilled: "pin-filled.svg",
18
+ returnTo: "return.svg",
19
+ } as const;
20
+
21
+ /**
22
+ * A bundled icon's name.
23
+ */
24
+ export type BundledIcon = keyof typeof BUNDLED_ICONS;
25
+
26
+ /**
27
+ * Icons Herdr ships with its own mods, as `svg()` paths. They are never copied.
28
+ */
29
+ export const HERDR_ICONS = {
30
+ back: "mods/workspace-chrome/chevron-left.svg",
31
+ terminal: "mods/workspace-chrome/terminal.svg",
32
+ pin: "mods/workspace-chrome/pin.svg",
33
+ pinOff: "mods/workspace-chrome/pin-off.svg",
34
+ search: "mods/workspace-chrome/search.svg",
35
+ check: "mods/workspace-chrome/check.svg",
36
+ circleCheck: "mods/workspace-chrome/circle-check.svg",
37
+ close: "mods/workspace-chrome/x.svg",
38
+ clock: "mods/workspace-chrome/clock.svg",
39
+ minus: "mods/workspace-chrome/minus.svg",
40
+ square: "mods/workspace-chrome/square.svg",
41
+ spinner: "mods/workspace-chrome/spinner.svg",
42
+ gitBranch: "mods/workspace-chrome/git-branch.svg",
43
+ chevronDown: "mods/files/chevron-down.svg",
44
+ chevronRight: "mods/files/chevron-right.svg",
45
+ } as const;
46
+
47
+ const MOD_FOLDER = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
48
+
49
+ /**
50
+ * Checks a mod folder name, the one directory under `<home>/mods/` the consumer installs to.
51
+ * @param modFolder The name.
52
+ * @returns The name.
53
+ * @throws When it is empty or holds a path separator or other character Herdr's mod names don't.
54
+ */
55
+ export function modFolderName(modFolder: string): string {
56
+ if (!MOD_FOLDER.test(modFolder)) throw new Error(`Not a mod folder name: ${modFolder}`);
57
+ return modFolder;
58
+ }
59
+
60
+ /**
61
+ * Every bundled icon's `svg()` path inside a mod folder.
62
+ * @param modFolder The folder the consumer's build copied the icons into.
63
+ * @returns Each icon's path, like `mods/<modFolder>/globe.svg`.
64
+ */
65
+ export function bundledIconPaths(modFolder: string): Record<BundledIcon, string> {
66
+ const folder = modFolderName(modFolder);
67
+ return Object.fromEntries(
68
+ Object.entries(BUNDLED_ICONS).map(([name, fileName]) => [name, `mods/${folder}/${fileName}`]),
69
+ ) as Record<BundledIcon, string>;
70
+ }
71
+
72
+ /**
73
+ * The Tasks panel's control icons by role.
74
+ */
75
+ export type PanelIcons = {
76
+ copy: string;
77
+ openInBrowser: string;
78
+ signIn: string;
79
+ externalLink: string;
80
+ back: string;
81
+ follow: string;
82
+ pin: string;
83
+ pinned: string;
84
+ goPinned: string;
85
+ search: string;
86
+ submit: string;
87
+ cancel: string;
88
+ groupOpen: string;
89
+ groupClosed: string;
90
+ dock: string;
91
+ undock: string;
92
+ spinner: string;
93
+ };
94
+
95
+ /**
96
+ * The Tasks panel's control icons by role, bundled ones resolved in a mod folder.
97
+ * @param modFolder The folder the consumer's build copied the icons into.
98
+ * @returns Each role's `svg()` path.
99
+ */
100
+ export function panelIcons(modFolder: string): PanelIcons {
101
+ const bundled = bundledIconPaths(modFolder);
102
+ return {
103
+ copy: bundled.copy,
104
+ openInBrowser: bundled.globe,
105
+ signIn: bundled.logIn,
106
+ externalLink: bundled.externalLink,
107
+ back: HERDR_ICONS.back,
108
+ follow: HERDR_ICONS.terminal,
109
+ pin: HERDR_ICONS.pin,
110
+ pinned: bundled.pinFilled,
111
+ goPinned: bundled.returnTo,
112
+ search: HERDR_ICONS.search,
113
+ submit: HERDR_ICONS.check,
114
+ cancel: HERDR_ICONS.close,
115
+ groupOpen: HERDR_ICONS.chevronDown,
116
+ groupClosed: HERDR_ICONS.chevronRight,
117
+ dock: bundled.anchor,
118
+ undock: bundled.anchorOff,
119
+ spinner: HERDR_ICONS.spinner,
120
+ };
121
+ }
package/src/index.ts ADDED
@@ -0,0 +1,15 @@
1
+ // The package's mod-facing entry: every pure token and helper, and every element function.
2
+ // Element modules import gpui-kit, gpui-base and herdr types, which Herdr provides at runtime:
3
+ // bundle with `--target bun` and mark all three external.
4
+ export * from "./pure";
5
+ export * from "./ui/cards";
6
+ export * from "./ui/chips";
7
+ export * from "./ui/controls";
8
+ export * from "./ui/crumbs";
9
+ export * from "./ui/document";
10
+ export * from "./ui/frame";
11
+ export * from "./ui/menu";
12
+ export * from "./ui/scroll";
13
+ export * from "./ui/states";
14
+ export * from "./ui/tabs";
15
+ export * from "./ui/theme";
@@ -0,0 +1,117 @@
1
+ // The compact property menu's metrics: Herdr's popup-menu rows and padding, and how a child
2
+ // flyout fits beside its parent. Pure.
3
+
4
+ /**
5
+ * A compact menu's sizes, in px.
6
+ */
7
+ export type MenuMetrics = {
8
+ width: number;
9
+ flyoutWidth: number;
10
+ row: number;
11
+ padding: number;
12
+ /**
13
+ * The parent menu's fixed height.
14
+ */
15
+ height: number;
16
+ inputHeight: number;
17
+ gap: number;
18
+ icon: number;
19
+ /**
20
+ * How many rows a searchable child shows: it must fit inside the parent's height, or native
21
+ * fitting moves parent rows under a stationary pointer and can cycle hover-open and close.
22
+ */
23
+ visibleRows: number;
24
+ };
25
+
26
+ /**
27
+ * Options for {@link menuMetrics}; each defaults to the Tasks panel's Task menu.
28
+ */
29
+ export type MenuMetricsOptions = {
30
+ /**
31
+ * How many rows the parent menu holds.
32
+ */
33
+ rows?: number;
34
+ width?: number;
35
+ flyoutWidth?: number;
36
+ row?: number;
37
+ padding?: number;
38
+ inputHeight?: number;
39
+ gap?: number;
40
+ icon?: number;
41
+ /**
42
+ * Overrides the derived visible-row budget.
43
+ */
44
+ visibleRows?: number;
45
+ };
46
+
47
+ /**
48
+ * Builds a menu's metrics.
49
+ * @param options Sizes that differ from the Task menu's.
50
+ * @returns The metrics, with the parent height and visible-row budget derived.
51
+ */
52
+ export function menuMetrics(options: MenuMetricsOptions = {}): MenuMetrics {
53
+ const {
54
+ rows = 8,
55
+ width = 220,
56
+ flyoutWidth = 240,
57
+ row = 31,
58
+ padding = 5,
59
+ inputHeight = 32,
60
+ gap = 2,
61
+ icon = 14,
62
+ } = options;
63
+ const height = padding * 2 + row * rows;
64
+ return {
65
+ width,
66
+ flyoutWidth,
67
+ row,
68
+ padding,
69
+ height,
70
+ inputHeight,
71
+ gap,
72
+ icon,
73
+ visibleRows: options.visibleRows ?? Math.floor((height - padding * 2 - inputHeight) / row),
74
+ };
75
+ }
76
+
77
+ /**
78
+ * The Tasks panel's Task menu: eight rows, 220px wide, with 240px flyouts.
79
+ */
80
+ export const MENU: MenuMetrics = menuMetrics();
81
+
82
+ /**
83
+ * A choice list's definite viewport height: intrinsic popovers otherwise collapse the body.
84
+ * @param metrics The menu.
85
+ * @param count Filtered choices, or zero for an empty-search note.
86
+ * @param visibleRows The row budget; defaults to the menu's.
87
+ * @returns At least one row, capped at the budget.
88
+ */
89
+ export const choicesHeight = (
90
+ metrics: MenuMetrics,
91
+ count: number,
92
+ visibleRows: number = metrics.visibleRows,
93
+ ): number => Math.min(Math.max(count, 1), visibleRows) * metrics.row;
94
+
95
+ /**
96
+ * Aligns a short child with its parent row, lifting a long child inside the parent's fixed
97
+ * height, so native bottom-edge fitting can't move the parent as the child opens.
98
+ * @param metrics The menu.
99
+ * @param rowIndex The property's row in the parent.
100
+ * @param count Filtered choices, including an empty-search placeholder when zero.
101
+ * @param searchable Whether the child holds a search input.
102
+ * @param visibleRows The child's row budget; defaults to the menu's.
103
+ * @returns The child's top inset.
104
+ */
105
+ export function flyoutTop(
106
+ metrics: MenuMetrics,
107
+ rowIndex: number,
108
+ count: number,
109
+ searchable: boolean,
110
+ visibleRows: number = metrics.visibleRows,
111
+ ): number {
112
+ const childHeight =
113
+ metrics.padding * 2 +
114
+ choicesHeight(metrics, count, visibleRows) +
115
+ (searchable ? metrics.inputHeight : 0);
116
+ return Math.max(0, Math.min(rowIndex * metrics.row, metrics.height - childHeight));
117
+ }
package/src/pure.ts ADDED
@@ -0,0 +1,8 @@
1
+ // Everything in the package that imports neither gpui-kit nor herdr: safe in tests, build
2
+ // scripts and a Bun-side typecheck.
3
+ export * from "./color";
4
+ export * from "./icons";
5
+ export * from "./menu-metrics";
6
+ export * from "./record-scrolls";
7
+ export * from "./tokens";
8
+ export * from "./toolbar";