hlmnhkl-ui 0.21.1 → 0.22.0

package/README.md

@@ -60,7 +60,7 @@ Every copied file starts with one line naming hlmnhkl/ui and the MIT licence, so
 - **50 free components**, from Button, Dialog, Select and Table to Toast and Retime, one speed setting for every animation. See [COMPONENTS.md](COMPONENTS.md).
 - **One look, set by tokens.** Every colour, size and timing comes from one file, `tokens.css`. Colour appears only to mean something: good, caution or bad.
 - **Light and dark.** Dark follows the system, or set `data-theme="dark"` on `<html>`.
-- **Accessible.** Keyboard support per the WAI-ARIA patterns, visible focus, screen reader labels, and reduced motion. On touch screens every control gives at least a 44px target, even the small sizes; only the six PIN boxes and the seven calendar days get narrower when the row has no room, about 36px wide on a 320px phone.
+- **Accessible.** Keyboard support per the WAI-ARIA patterns, visible focus, screen reader labels, and reduced motion. On touch screens every control gives at least a 44px target, even the small sizes; only the six PIN boxes and the seven calendar days get narrower when the row has no room, about 36px wide on a 320px phone. CalendarHeatmap's days are small by design, since a year must fit on screen; its month table gives the same numbers at full size.
 - **Small.** React 19 and CSS Modules. No other runtime packages: no animation library, no icon package.
 - **Works in** Vite, Next.js (App Router) and React Router.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hlmnhkl-ui",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "React components in a monochrome style. Copy them into your app with npx hlmnhkl-ui add <name>.",
   "license": "MIT",
   "homepage": "https://ui.hlmnhkl.my",

package/scripts/pro-components.json

@@ -15,6 +15,7 @@
   "ContextMenu",
   "Countdown",
   "CurrencyInput",
+  "DataGrid",
   "DatePicker",
   "DateRangePicker",
   "DescriptionList",
@@ -48,14 +49,18 @@
   "ResizablePanels",
   "RichTextEditor",
   "Route",
+  "ScrollDraft",
+  "ScrollRuler",
   "Sidebar",
   "SignaturePad",
+  "SmoothScroll",
   "SortableList",
   "Sparkline",
   "Stat",
   "Stepper",
   "SwipeActions",
   "TagInput",
+  "TextRise",
   "TimePicker",
   "Timeline",
   "ToggleGroup",

package/src/components/Accordion/Accordion.module.css

@@ -38,7 +38,7 @@
 @media (hover: hover) {
   .trigger:hover:not(:disabled) { background: var(--hl-color-surface-hover); }
 }
-.trigger:disabled { opacity: 0.45; cursor: not-allowed; }
+.trigger:disabled { opacity: var(--hl-disabled-opacity); cursor: not-allowed; }
 
 .trigger:focus-visible {
   outline: none;

package/src/components/AnimatedNumber/AnimatedNumber.module.css

@@ -1,5 +1,6 @@
 .root {
   display: inline-flex;
+  width: fit-content;
   font-variant-numeric: tabular-nums;
   line-height: 1.15;
 }

package/src/components/Badge/Badge.module.css

@@ -1,5 +1,6 @@
 .root {
   display: inline-flex;
+  width: fit-content;
   align-items: center;
   gap: var(--hl-space-2);
   max-width: 100%;

package/src/components/Breadcrumb/Breadcrumb.module.css

@@ -66,6 +66,7 @@
 }
 
 .more {
+  justify-content: center;
   border: 0;
   background: transparent;
   font-size: inherit;
@@ -73,6 +74,11 @@
   letter-spacing: var(--hl-tracking-wide);
 }
 
+/* The dots alone are too narrow to tap. */
+@media (pointer: coarse) {
+  .more { min-width: var(--hl-hit-min); }
+}
+
 @media (hover: hover) {
   .more:hover { color: var(--hl-color-fg); background: var(--hl-color-surface-hover); }
 }

package/src/components/Button/Button.module.css

@@ -2,6 +2,8 @@
   --h: var(--hl-control-h-md);
   position: relative;
   display: inline-grid;
+  /* Its own width in a column layout too; fullWidth (.full) still fills the row. */
+  width: fit-content;
   grid-template-columns: minmax(0, auto);
   place-items: center;
   max-width: 100%;
@@ -55,7 +57,7 @@
 .root:disabled,
 .root[aria-disabled="true"]:not([data-loading]) {
   cursor: not-allowed;
-  opacity: 0.45;
+  opacity: var(--hl-disabled-opacity);
 }
 
 .root[data-loading] {

package/src/components/Checkbox/Checkbox.module.css

@@ -6,7 +6,7 @@
   padding-block: var(--hl-space-4);
 }
 
-.root[data-disabled] { opacity: 0.5; }
+.root[data-disabled] { opacity: var(--hl-disabled-opacity); }
 
 .boxWrap {
   position: relative;

package/src/components/Collapsible/Collapsible.module.css

@@ -29,7 +29,7 @@
   .trigger:hover:not(:disabled) { background: var(--hl-color-surface-hover); }
 }
 .trigger:active:not(:disabled) { transform: scale(var(--hl-press-scale)); }
-.trigger:disabled { opacity: 0.45; cursor: not-allowed; }
+.trigger:disabled { opacity: var(--hl-disabled-opacity); cursor: not-allowed; }
 .trigger:focus-visible { outline: none; box-shadow: var(--hl-focus-ring); }
 
 .label {

package/src/components/CopyButton/CopyButton.module.css

@@ -2,6 +2,7 @@
   --s: var(--hl-control-h-md);
   position: relative;
   display: inline-flex;
+  width: fit-content;
   align-items: center;
   justify-content: center;
   gap: var(--hl-space-3);

package/src/components/FormField/FormField.module.css

@@ -4,7 +4,7 @@
   min-width: 0;
 }
 
-.root[data-disabled] { opacity: 0.6; }
+.root[data-disabled] { opacity: var(--hl-disabled-opacity); }
 
 .label {
   margin-bottom: var(--hl-space-3);

package/src/components/IconButton/IconButton.module.css

@@ -61,7 +61,7 @@
   .root:hover:not(:disabled) .icon { transform: scale(1.08); }
 }
 .root:active:not(:disabled) { transform: scale(var(--hl-press-scale-strong)); transition-duration: var(--hl-motion-instant); }
-.root:disabled { opacity: 0.45; cursor: not-allowed; }
+.root:disabled { opacity: var(--hl-disabled-opacity); cursor: not-allowed; }
 
 @media (hover: hover) {
   .ghost:hover:not(:disabled) { background: var(--hl-color-surface-hover); }

package/src/components/Input/Input.module.css

@@ -64,7 +64,7 @@
 .field[data-disabled] {
   background: var(--hl-color-surface-sunken);
   cursor: not-allowed;
-  opacity: 0.6;
+  opacity: var(--hl-disabled-opacity);
 }
 
 .adorn {

package/src/components/Kbd/Kbd.module.css

@@ -1,5 +1,6 @@
 .root {
   display: inline-flex;
+  width: fit-content;
   align-items: center;
   justify-content: center;
   min-width: var(--hl-kbd-h);

package/src/components/Pagination/Pagination.module.css

@@ -70,7 +70,7 @@
 }
 .btn:active:not(:disabled) { transform: scale(var(--hl-press-scale-strong)); }
 .btn[aria-current="page"] { color: var(--hl-color-accent-fg); }
-.btn:disabled { opacity: 0.35; cursor: not-allowed; }
+.btn:disabled { opacity: var(--hl-disabled-opacity); cursor: not-allowed; }
 .btn:focus-visible { outline: none; box-shadow: var(--hl-focus-ring); }
 
 .edge {

package/src/components/Radio/Radio.module.css

@@ -30,7 +30,7 @@
   padding-block: var(--hl-space-4);
 }
 
-.root[data-disabled] { opacity: 0.5; }
+.root[data-disabled] { opacity: var(--hl-disabled-opacity); }
 
 .circleWrap {
   position: relative;

package/src/components/Retime/Retime.tsx

@@ -48,6 +48,8 @@ export type RetimeProps = {
   size?: 'sm' | 'md'
   /** Text for each speed, so you can translate it. */
   labels?: Partial<RetimeLabels>
+  /** Fills the row, with the speeds sharing it evenly, as in a settings panel. */
+  fullWidth?: boolean
   /** Extra class for the root element. */
   className?: string
 }
@@ -60,6 +62,7 @@ export function Retime({
   remember = true,
   size = 'md',
   labels: labelsProp,
+  fullWidth,
   className,
 }: RetimeProps) {
   const labels = { ...defaultLabels, ...labelsProp }
@@ -106,6 +109,7 @@ export function Retime({
       value={speed}
       onValueChange={(v) => setSpeed(v as RetimeSpeed)}
       options={(['off', 'slower', 'normal', 'faster'] as const).map((s) => ({ value: s, label: labels[s] }))}
+      fullWidth={fullWidth}
       className={className}
     />
   )

package/src/components/SegmentedControl/SegmentedControl.module.css

@@ -1,6 +1,8 @@
 .root {
   position: relative;
   display: inline-flex;
+  /* Its own width in a column layout too; fullWidth (.full) still fills the row. */
+  width: fit-content;
   padding: var(--hl-space-1);
   border: var(--hl-line) solid var(--hl-color-border);
   border-radius: var(--hl-radius-control);
@@ -30,7 +32,9 @@
     width var(--hl-motion-slow) var(--hl-ease-out);
 }
 
+/* Options share any room the track has beyond its own width, so a stretched track never ends in an empty gap. */
 .item {
+  flex: 1 0 auto;
   position: relative;
   display: inline-flex;
   align-items: center;
@@ -71,7 +75,7 @@
 }
 .item:active:not(:disabled) { transform: scale(var(--hl-press-scale)); }
 .item[data-on] { color: var(--hl-color-fg); }
-.item:disabled { opacity: 0.4; cursor: not-allowed; }
+.item:disabled { opacity: var(--hl-disabled-opacity); cursor: not-allowed; }
 
 .item:focus-visible {
   outline: none;

package/src/components/Slider/Slider.module.css

@@ -5,7 +5,7 @@
   min-width: 0;
 }
 
-.root[data-disabled] { opacity: 0.5; }
+.root[data-disabled] { opacity: var(--hl-disabled-opacity); }
 
 .head {
   display: flex;

package/src/components/Switch/Switch.module.css

@@ -10,7 +10,7 @@
   justify-content: space-between;
 }
 
-.root[data-disabled] { opacity: 0.5; }
+.root[data-disabled] { opacity: var(--hl-disabled-opacity); }
 
 .track {
   --w: var(--hl-switch-w);

package/src/components/Tabs/Tabs.module.css

@@ -46,7 +46,7 @@
   .tab:hover:not(:disabled) { color: var(--hl-color-fg); background: var(--hl-color-surface-hover); }
 }
 .tab[aria-selected="true"] { color: var(--hl-color-fg); }
-.tab:disabled { opacity: 0.4; cursor: not-allowed; }
+.tab:disabled { opacity: var(--hl-disabled-opacity); cursor: not-allowed; }
 
 .tab:focus-visible {
   outline: none;

package/src/components/Tag/Tag.module.css

@@ -1,5 +1,6 @@
 .root {
   display: inline-flex;
+  width: fit-content;
   align-items: center;
   max-width: 100%;
   height: var(--hl-control-h-sm);

package/src/internal/focus.ts

@@ -9,6 +9,29 @@ export function focusables(root: HTMLElement): HTMLElement[] {
   )
 }
 
+// Safari, on iPhone and on Mac, does not focus a button when it is tapped or clicked. So the control
+// that opened a layer is often not the focused element; remember the last one pressed instead.
+// Watched from the moment this file loads, since a layer only mounts after the press that opens it.
+let lastPressed: HTMLElement | null = null
+if (typeof document !== 'undefined') {
+  document.addEventListener(
+    'pointerdown',
+    (e) => {
+      lastPressed = (e.target instanceof Element ? e.target.closest<HTMLElement>(FOCUSABLE) : null) ?? null
+    },
+    true,
+  )
+}
+
+// Where focus should go back to: the focused element, unless it is the page or a box around the
+// control that was just pressed. Then that control.
+function returnTarget(): HTMLElement | null {
+  const active = document.activeElement as HTMLElement | null
+  const pressed = lastPressed && lastPressed.isConnected ? lastPressed : null
+  if (pressed && (!active || active === document.body || (active !== pressed && active.contains(pressed)))) return pressed
+  return active
+}
+
 export function useFocusTrap(
   ref: RefObject<HTMLElement | null>,
   active: boolean,
@@ -19,7 +42,7 @@ export function useFocusTrap(
     if (!active) return
     const root = ref.current
     if (!root) return
-    const previous = document.activeElement as HTMLElement | null
+    const previous = returnTarget()
     // Close buttons opt out of first focus, so focus lands on the content or the safe action.
     const list = focusables(root)
     const first = initialFocus?.current ?? list.find((el) => !el.hasAttribute('data-skip-initial-focus')) ?? list[0] ?? root

package/src/internal/icons.tsx

@@ -181,3 +181,4 @@ export const GripIcon = (p: IconProps) => (
     <path d="M5 9h14M5 15h14" />
   </Svg>
 )
+export const FilterIcon = (p: IconProps) => <Svg {...p}><path d="M4.5 6h15l-5.75 7v5.5l-3.5-2V13z" /></Svg>

package/src/internal/scrollFrame.ts

@@ -0,0 +1,224 @@
+import { useEffect, useLayoutEffect, useRef } from 'react'
+import { motionMs, prefersReducedMotion } from './motion'
+
+// One frame loop for every scroll part on the page. It runs only while the page moves, and stops
+// after a moment of stillness; a scroll, a resize or a change in the page's size wakes it again.
+
+/** Where the page is (px) and how fast it moves (px/s, signed). */
+export type ScrollFrame = { y: number; v: number }
+
+/** Reads layout and returns the writes, so every part reads before any part writes. */
+export type ScrollReader = (frame: ScrollFrame) => void | (() => void)
+
+export type ScrollTokens = { ease: number; start: number; end: number; step: number; readEvery: number }
+
+const readers = new Set<{ current: ScrollReader }>()
+let frame: ScrollFrame = { y: 0, v: 0 }
+let last = { y: 0, t: -1 }
+let raf = 0
+let still = 0
+let observer: ResizeObserver | null = null
+let reduce: MediaQueryList | null = null
+let tokens: ScrollTokens | null = null
+
+export function readScrollTokens(): ScrollTokens {
+  const s = getComputedStyle(document.documentElement)
+  const n = (name: string) => parseFloat(s.getPropertyValue(name))
+  return { ease: n('--hl-scroll-ease'), start: n('--hl-draft-start'), end: n('--hl-draft-end'), step: n('--hl-ruler-step'), readEvery: motionMs('fast') }
+}
+
+/** The tokens, read once each time the loop starts or the window changes size. */
+export const scrollTokens = () => (tokens ??= readScrollTokens())
+
+/** Progress from 0 to 1 as an element's top moves from `start` to `end` (shares of the screen height). */
+export function bandProgress(top: number, start: number, end: number) {
+  const p = (start - top / window.innerHeight) / (start - end)
+  return Math.max(0, Math.min(1, p))
+}
+
+function run(f: ScrollFrame) {
+  const writes: Array<() => void> = []
+  readers.forEach((r) => {
+    const w = r.current(f)
+    if (w) writes.push(w)
+  })
+  writes.forEach((w) => w())
+}
+
+function tick(t: number) {
+  const y = window.scrollY
+  // The first frame after a wake only takes its bearings: its time can be earlier than the wake's.
+  let v = frame.v
+  if (last.t >= 0) {
+    v += (((y - last.y) / Math.max(1, t - last.t)) * 1000 - v) * 0.2
+    if (Math.abs(v) < 1) v = 0
+  }
+  const moved = y !== last.y
+  last = { y, t }
+  frame = { y, v }
+  run(frame)
+  still = !moved && v === 0 ? still + 1 : 0
+  raf = still > 30 ? 0 : requestAnimationFrame(tick)
+}
+
+function wake() {
+  still = 0
+  if (raf) return
+  tokens = null
+  last = { y: window.scrollY, t: -1 }
+  raf = requestAnimationFrame(tick)
+}
+
+function onResize() {
+  tokens = null
+  wake()
+}
+
+function start() {
+  window.addEventListener('scroll', wake, { passive: true })
+  window.addEventListener('resize', onResize)
+  // Fonts, pictures or an opened panel can move things without a scroll.
+  observer = new ResizeObserver(wake)
+  observer.observe(document.body)
+  reduce = window.matchMedia('(prefers-reduced-motion: reduce)')
+  reduce.addEventListener('change', wake)
+}
+
+function stop() {
+  window.removeEventListener('scroll', wake)
+  window.removeEventListener('resize', onResize)
+  observer?.disconnect()
+  observer = null
+  reduce?.removeEventListener('change', wake)
+  reduce = null
+  cancelAnimationFrame(raf)
+  raf = 0
+  frame = { y: 0, v: 0 }
+}
+
+/** Calls `read` once on mount and then every frame while the page moves. */
+export function useScrollFrame(read: ScrollReader, active = true) {
+  const ref = useRef(read)
+  useLayoutEffect(() => {
+    ref.current = read
+  })
+  useLayoutEffect(() => {
+    if (!active) return
+    if (!readers.size) start()
+    readers.add(ref)
+    mounting.add(ref)
+    if (mounting.size === 1) queueMicrotask(runMounts)
+    wake()
+    return () => {
+      readers.delete(ref)
+      mounting.delete(ref)
+      if (!readers.size) stop()
+    }
+  }, [active])
+}
+
+// Parts that mount together read once, together, before the first paint, so the page lays out once.
+const mounting = new Set<{ current: ScrollReader }>()
+
+function runMounts() {
+  const writes: Array<() => void> = []
+  const f = { y: window.scrollY, v: frame.v }
+  mounting.forEach((r) => {
+    const w = r.current(f)
+    if (w) writes.push(w)
+  })
+  mounting.clear()
+  writes.forEach((w) => w())
+}
+
+// Weighted wheel scrolling, shared by every SmoothScroll on the page. The last one mounted sets the ease.
+const wheelUsers: Array<{ ease?: number }> = []
+let fine: MediaQueryList | null = null
+const glide = { target: 0, current: 0, set: 0, ease: 1, t0: 0, id: 0 }
+
+const maxScroll = () => document.documentElement.scrollHeight - document.documentElement.clientHeight
+
+const locked = () => document.body.style.overflow === 'hidden'
+
+function step(t: number) {
+  const g = glide
+  // Something else moved the page (a key, the scrollbar, a link), or a dialog locked it: let it lead.
+  if (locked() || Math.abs(window.scrollY - g.set) > 2) {
+    g.id = 0
+    return
+  }
+  // A frame's time can be a little before the wheel event's, so never step backwards.
+  const k = 1 - Math.pow(1 - g.ease, Math.min(4, Math.max(0, t - g.t0) / (1000 / 60)))
+  g.t0 = Math.max(g.t0, t)
+  g.current += (g.target - g.current) * k
+  if (Math.abs(g.target - g.current) < 0.5) g.current = g.target
+  g.set = Math.round(g.current)
+  // Instant, so a page with scroll-behavior: smooth does not ease each step a second time.
+  window.scrollTo({ top: g.set, behavior: 'instant' })
+  g.id = g.current === g.target ? 0 : requestAnimationFrame(step)
+}
+
+function stopGlide() {
+  cancelAnimationFrame(glide.id)
+  glide.id = 0
+}
+
+// The nearest box that can still scroll this way takes the wheel itself, and so does one that keeps
+// its overscroll to itself. The event's path also walks into shadow roots.
+function scrollsInside(path: EventTarget[], dy: number) {
+  for (const el of path) {
+    if (el === document.documentElement) break
+    if (!(el instanceof Element)) continue
+    const cs = getComputedStyle(el)
+    if ((cs.overflowY === 'auto' || cs.overflowY === 'scroll') && el.scrollHeight > el.clientHeight) {
+      if (cs.overscrollBehaviorY !== 'auto') return true
+      if (dy < 0 ? el.scrollTop > 0 : el.scrollTop + el.clientHeight < el.scrollHeight) return true
+    }
+  }
+  return false
+}
+
+function onWheel(e: WheelEvent) {
+  // A dialog or sheet has locked the page: leave it still.
+  if (locked()) return stopGlide()
+  // Pinch zoomed, the wheel pans the zoomed view, so it stays native.
+  if (prefersReducedMotion() || !fine?.matches || (window.visualViewport?.scale ?? 1) > 1) return
+  if (e.ctrlKey || e.defaultPrevented || Math.abs(e.deltaX) > Math.abs(e.deltaY) || scrollsInside(e.composedPath(), e.deltaY)) return
+  e.preventDefault()
+  const g = glide
+  if (!g.id) {
+    g.target = g.current = g.set = window.scrollY
+    g.ease = wheelUsers[wheelUsers.length - 1]?.ease ?? readScrollTokens().ease
+  }
+  const unit = e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? window.innerHeight : 1
+  g.target = Math.max(0, Math.min(maxScroll(), g.target + e.deltaY * unit))
+  if (!g.id) {
+    g.t0 = performance.now()
+    g.id = requestAnimationFrame(step)
+  }
+}
+
+// Any other way of moving the page takes over at once, so a key or the scrollbar never fights a glide.
+const handOver = ['keydown', 'mousedown', 'touchstart'] as const
+
+/** Weighted wheel scrolling for mouse and trackpad while mounted. Keys, the scrollbar and links stay native. */
+export function useSmoothWheel(ease: number | undefined, disabled: boolean) {
+  useEffect(() => {
+    if (disabled) return
+    const user = { ease }
+    if (!wheelUsers.length) {
+      fine = window.matchMedia('(hover: hover) and (pointer: fine)')
+      window.addEventListener('wheel', onWheel, { passive: false })
+      handOver.forEach((t) => window.addEventListener(t, stopGlide, { passive: true }))
+    }
+    wheelUsers.push(user)
+    return () => {
+      wheelUsers.splice(wheelUsers.indexOf(user), 1)
+      if (wheelUsers.length) return
+      window.removeEventListener('wheel', onWheel)
+      handOver.forEach((t) => window.removeEventListener(t, stopGlide))
+      stopGlide()
+      fine = null
+    }
+  }, [ease, disabled])
+}

package/src/tokens.css

@@ -522,7 +522,41 @@
   --hl-countdown-cell: 72px;
   --hl-countdown-cell-sm: 52px;
 
+  /* Data grid: scroll area height, a column's default, smallest and largest width, one keyboard
+     resize step, resize handle hit width (a touch screen widens it to --hl-hit-min), the tallest
+     a filter's checkbox list grows, and the sort order badge */
+  --hl-datagrid-h: 480px;
+  --hl-datagrid-col-w: 160px;
+  --hl-datagrid-col-min: 96px;
+  --hl-datagrid-col-max: 640px;
+  --hl-datagrid-resize-step: 16px;
+  --hl-datagrid-resize-hit: 12px;
+  --hl-datagrid-options-h: 320px;
+  --hl-datagrid-order: 16px;
+
   /* Touch lists: one swipe action's width, and how far a pull must go before it refreshes */
   --hl-swipe-action-w: 80px;
   --hl-pull-distance: 72px;
 }
+
+:root,
+[data-theme="light"] {
+  /* SmoothScroll: the share of the distance left that a wheel glide covers each frame. 1 is native. */
+  --hl-scroll-ease: 0.1;
+  /* ScrollDraft and TextRise: where an element's top starts and ends its progress, as a share of the screen height */
+  --hl-draft-start: 0.85;
+  --hl-draft-end: 0.4;
+  /* TextRise: how many words of the progress each word takes to arrive, and room for descenders in its mask */
+  --hl-rise-span: 3;
+  --hl-rise-room: 0.14em;
+  /* ScrollRuler: its width, and the page pixels between two short ticks (a number every five) */
+  --hl-ruler-w: 48px;
+  --hl-ruler-step: 100px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root,
+  [data-theme] {
+    --hl-scroll-ease: 1;
+  }
+}