utils/web_ui

@kuhyx/web-ui

The shared token + component layer for kuhy's web apps — the web counterpart to ~/src/utils/design_system (Dart). Owns the frozen palette, the spacing/radius/type scales, and the components that were each reimplemented in two or more repos.

Consumers import the tokens rather than transcribing the token table by hand. Source of truth for the values is ~/src/utils/unified-design-system/DOCS-tokens.md; this package is its executable form for the web.

Install

// package.json — pnpm only, see "Why the &path: suffix" below.
"dependencies": {
  "@kuhyx/web-ui": "github:kuhyx/utils#web_ui-v0.5.0&path:/web_ui"
}

Astro is the only supported framework (peerDependencies.astro >=7.4.0).

---
// Layout / page frontmatter
import RangeSlider from "@kuhyx/web-ui/RangeSlider.astro";
import "@kuhyx/web-ui/tokens.css";        // once, in the shared layout
import "@kuhyx/web-ui/range-slider.css";  // only if you use RangeSlider
---
<RangeSlider label="Stars" />
<script>
  import "@kuhyx/web-ui/range-slider";    // registers <range-slider>
  const slider = document.querySelector("range-slider");
  slider.values = [0, 0, 3, 40, 900];     // ascending distribution
  slider.format = (value) => `${value} stars`;
  slider.addEventListener("change", (event) => {
    const { lo, hi } = event.detail;      // bubbles; raw values, lo <= hi
  });
</script>

Pure helpers (fuzzyMatch, quantileValue, ...) come from import { fuzzyMatch } from "@kuhyx/web-ui";. That entry point touches no DOM, so it is safe in frontmatter.

Why the &path:/web_ui suffix

utils is a monorepo with no root package.json, and npm cannot install from a subdirectory of a git repo — github:user/repo#tag clones the root, looks for package.json there, and fails with ENOENT (verified against npm 11.16). pnpm supports the subdirectory via &path:/<dir>, which is why both consumers are pnpm. This is the only difference from the Dart (git: {url, ref, path}) and Python (#subdirectory=) conventions the rest of utils follows.

Why dist/ is committed, and why .astro ships as source

tsc cannot emit .astro, so src/RangeSlider.astro ships as it is and Astro compiles it from the dependency. Everything TypeScript ships prebuilt: the tag carries dist/ (ESM + .d.ts, .ts specifiers rewritten to .js), and the .astro file imports ../dist/..., never the .ts source. pnpm build before tagging, always — a tag whose dist/ is stale ships old code to every consumer with no error.

What's here

Export	Notes
tokens.css	The :root block: palette, spacing, radius, type, shadows, focus ring. Also sets :focus-visible globally.
RangeSlider.astro	Server-rendered shell for <range-slider>. Props: values, lo, hi, label, format (server-side, first paint of the head only). Its <script> registers the element.
range-slider	The custom element. values and format properties, lo / hi / label attributes, bubbling change event with { lo, hi }. Adopts the server markup, or builds it in plain HTML.
range-slider.css	Its styling, entirely in tokens.
quantile.ts helpers	nth, clamp01, quantileValue, valueQuantile, fractionFromPointer.
stepped-value.ts helpers	keyTarget, steppedValue.
fuzzyMatch	Case-insensitive subsequence match.

The element writes lo / hi itself on every change, so it works without any wiring; set the attributes from outside to override it (e.g. a URL-hash restore). With fewer than two values the slider stays hidden. values set before the element upgrades is picked up on connect.

The categorical ramp

--cat-1 … --cat-6 are for charts, tags and category dots — N mutually distinguishable colours with no inherent meaning. Never use them for semantic state; --success/--warning/--danger own that.

They deliberately leave the warm wedge the rest of the palette sits in, because hue separation is the whole point of a categorical scale. The values were chosen by search under a ≥20 CIE ΔE floor across normal vision and deuteranopia, protanopia and tritanopia, ≥3:1 contrast on both backgrounds, and a monotonic lightness staircase so the ramp survives greyscale. Re-run the proof with python3 ~/src/utils/unified-design-system/scripts/ramp_check.py — it exits non-zero if an edit breaks any of it. A seventh hue is not available: the best candidate reaches only ΔE 17.9. Group the tail into "other" instead.

fractionFromPointer is deliberately pure geometry: it makes the slider's behaviour testable without layout, which jsdom does not implement.

<range-slider> is keyboard-operable

Both donor copies were pointer-only. The design system requires that every action be reachable with the keyboard alone, and a role="slider" that ignores arrow keys is an ARIA role that lies — so the shared version adds:

Key	Effect
← ↓ / → ↑	Step to the next distinct value
PageDown / PageUp	Step ten distinct values
Home / End	Jump to the distribution's bounds

Set label and format to get the built-in head (name + value readout); omit them for a bare track when the caller draws its own chrome, as dufs-cloud's SizeRange/DurationRange wrappers do.

Stepping targets the next distinct value, not the next index. Real distributions are lumpy — ~1500 of awesome-mcp-explorer's ~2981 star counts are 0 — and an index step inside a run of equal values moves the index while leaving the value, the thumb and the filter untouched. That reads as a dead arrow key, and jsdom's evenly-spaced fixtures do not catch it.

Development

pnpm install
pnpm test       # vitest (jsdom for the element, AstroContainer for the .astro markup)
pnpm coverage   # 100% branches/functions/lines/statements, enforced
pnpm lint       # tsc --noEmit && eslint && astro check
pnpm build      # tsc -b + copy CSS into dist/

The 100% bar matches Phase 1's design_system: a shared layer two repos depend on does not get to be the least-tested code in the tree.

Releasing

pnpm test && pnpm build
git add web_ui && git commit -m "web_ui: <what changed>"
git tag web_ui-v<major>.<minor>.<patch> && git push origin main --tags

Then bump the tag in each consumer's package.json and re-run pnpm install.