hlmnhkl-ui 0.34.0 → 0.35.1

package/README.md

@@ -65,7 +65,8 @@ Setup for other tools: [MCP server](https://ui.hlmnhkl.my/mcp).
 ## What you get
 
 - **The source, not a package.** The command copies plain files into your app. Change anything; there is no update to wait for.
-- **68 free components**, from Button, Dialog, Select and Table to Toast and Retime, one speed setting for every animation. See [COMPONENTS.md](COMPONENTS.md).
+- **71 free components**, from Button, Dialog, Select and Table to Toast and Retime, one speed setting for every animation. See [COMPONENTS.md](COMPONENTS.md).
+- **Controls that feel made by hand.** Dial, RulerScrubber and PickerWheel are drawn onto their marks like a magnet, glide after a flick without flying past, and settle without a bounce. Sheet rests at set heights, HoldToConfirm burns a line round its edge, SwipeDeck throws its cards and SplitFlap flips like a station board.
 - **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. CalendarHeatmap's days are small by design, since a year must fit on screen; its month table gives the same numbers at full size.
@@ -74,7 +75,7 @@ Setup for other tools: [MCP server](https://ui.hlmnhkl.my/mcp).
 
 ## Pro
 
-72 more components (such as DataGrid, Calendar, Chart, KanbanBoard and Combobox), page blocks, full templates and brand themes are coming as hlmnhkl/ui Pro. You can see them on the [docs site](https://ui.hlmnhkl.my).
+76 more components (such as DataGrid, Calendar, Chart, KanbanBoard, Combobox and WeekSchedule), page blocks, full templates and brand themes are coming as hlmnhkl/ui Pro. You can see them on the [docs site](https://ui.hlmnhkl.my).
 
 ## Licence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hlmnhkl-ui",
-  "version": "0.34.0",
+  "version": "0.35.1",
   "description": "React components in black, white and grey with one blue accent. Copy them into your app with npx hlmnhkl-ui add <name>.",
   "license": "MIT",
   "homepage": "https://ui.hlmnhkl.my",
@@ -25,7 +25,8 @@
   ],
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
-    "add": "node scripts/add.js"
+    "add": "node scripts/add.js",
+    "prepublishOnly": "node scripts/check-publish.mjs"
   },
   "devDependencies": {
     "@types/react": "^19.3.0",

package/scripts/add.js

@@ -41,6 +41,17 @@ const KINDS = [
   { key: 'theme', plural: 'Themes', folder: 'themes', pro: true, single: true },
 ].map((k) => ({ ...k, dir: join(SRC, k.folder) }))
 
+// The import lines as they read from the app's entry file. A folder inside src/ is written
+// relative to src/ (Vite, Next and most setups keep the entry there), so it can be pasted as is.
+function fromEntry(folder, both = true) {
+  const clean = folder.replace(/^\.\//, '').replace(/\/$/, '')
+  const inSrc = clean.startsWith('src/')
+  const rel = inSrc ? clean.slice(4) : clean
+  const where = inSrc ? 'in your entry file inside src/ (for example src/main.tsx):' : 'in a file at your project root:'
+  const lines = [`import './${rel}/tokens.css'`, ...(both ? [`import './${rel}/base.css'`] : [])]
+  return `${where}\n${lines.map((l) => `       ${l}`).join('\n')}`
+}
+
 function fail(message, usage = true) {
   console.error(`Error: ${message}`)
   if (usage) console.error(`\n${USAGE}`)
@@ -352,7 +363,7 @@ function runInit(opts) {
     if (!opts.dryRun) writeFileSync(config, `${JSON.stringify({ to: folder }, null, 2)}\n`)
     console.log(`  ${CONFIG}: added, so later commands put files in ${folder}`)
   }
-  console.log(`\nNext:\n  1. Import both once at your app root, tokens first:\n       import './${folder.replace(/^\.\//, '')}/tokens.css'\n       import './${folder.replace(/^\.\//, '')}/base.css'`)
+  console.log(`\nNext:\n  1. Import both once, tokens first, ${fromEntry(folder)}`)
   console.log(`  2. Add your first component: npx hlmnhkl-ui add button`)
   console.log(`  See everything there is: npx hlmnhkl-ui list, or ${SITE}`)
 }
@@ -417,7 +428,7 @@ function runAdd(opts) {
     for (const s of skipped) console.log(`  ${s}`)
     if (skipped.some((s) => /^(tokens|base)\.css /.test(s))) console.log('  tokens.css and base.css are never replaced, so your theme edits stay.')
   }
-  if (tokensNew) console.log(`Next: import ${join(opts.to || readConfig()?.to || DEFAULT_TO, 'tokens.css')} once at your app root (or run init).`)
+  if (tokensNew) console.log(`Next: import tokens.css once ${fromEntry(opts.to || readConfig()?.to || DEFAULT_TO, false)} (or run init).`)
   if (items.some((i) => i.kind === 'theme')) console.log('Themes: import each one after tokens.css, then set data-theme-brand or data-density on <html>.')
 }
 

package/src/components/LivePill/LivePill.module.css

@@ -0,0 +1,191 @@
+.root {
+  /* The row is the pill plus the card's inner padding, so the label keeps its pixels as the card grows round it. */
+  --pill-pad: calc(var(--hl-space-6) - (var(--hl-hit-min) - var(--hl-text-sm) * var(--hl-leading-normal)) / 2);
+  position: relative;
+  inline-size: 100%;
+  max-inline-size: var(--hl-panel-w-sm);
+  block-size: var(--pill-row, calc(var(--hl-hit-min) + var(--pill-pad)));
+  /* Only the pill takes taps; the clear row either side of it lets them through to the page. */
+  pointer-events: none;
+}
+
+.root[data-fixed] {
+  position: fixed;
+  z-index: var(--hl-z-sticky);
+  inset-inline: var(--hl-space-5);
+  inline-size: auto;
+  margin-inline: auto;
+}
+
+.root[data-fixed][data-placement='bottom'] {
+  bottom: calc(var(--hl-space-5) + env(safe-area-inset-bottom));
+}
+
+.root[data-fixed][data-placement='top'] {
+  top: calc(var(--hl-space-5) + env(safe-area-inset-top));
+}
+
+.shell {
+  --pill-bg: var(--hl-color-surface-sunken);
+  --pill-fg: var(--hl-color-fg);
+  --pill-muted: var(--hl-color-fg-muted);
+  --pill-line: var(--hl-color-border);
+  --pill-key: var(--hl-color-border-strong);
+  --pill-fill: var(--hl-color-inverse);
+  --pill-fill-fg: var(--hl-color-inverse-fg);
+  position: absolute;
+  inset-inline: 0;
+  display: flex;
+  flex-direction: column;
+  border-radius: var(--hl-radius-sheet);
+  background: var(--pill-bg);
+  color: var(--pill-fg);
+  box-shadow: inset 0 0 0 var(--hl-line) var(--pill-key);
+  pointer-events: auto;
+  clip-path: var(--pill-shut);
+}
+
+.shell[data-tone='ink'] {
+  --pill-bg: var(--hl-color-inverse);
+  --pill-fg: var(--hl-color-inverse-fg);
+  --pill-muted: color-mix(in srgb, var(--pill-fg) 62%, var(--pill-bg));
+  --pill-line: color-mix(in srgb, var(--pill-fg) 18%, var(--pill-bg));
+  --pill-key: transparent;
+  --pill-fill: var(--hl-color-surface);
+  --pill-fill-fg: var(--hl-color-fg);
+}
+
+/* Shut, it closes fast and falls away. Open, the surface pours out of the pill on the liquid curve. */
+.shell[data-measured] {
+  transition: clip-path var(--hl-motion-fast) var(--hl-ease-in);
+}
+
+.shell[data-open] {
+  z-index: 1;
+  clip-path: inset(0 0 0 0 round var(--hl-radius-sheet));
+  transition: clip-path var(--hl-motion-liquid) var(--hl-ease-liquid);
+}
+
+/* Before it is measured (the first paint of a server page), only the pill's words show. */
+.shell:not([data-measured]):not([data-open]) {
+  visibility: hidden;
+}
+
+.shell:not([data-measured]):not([data-open]) .button {
+  visibility: visible;
+}
+
+.root[data-placement='bottom'] .shell {
+  bottom: 0;
+  flex-direction: column-reverse;
+}
+
+.root[data-placement='top'] .shell {
+  top: 0;
+}
+
+.row {
+  display: flex;
+  justify-content: center;
+}
+
+.root[data-placement='bottom'] .row {
+  padding-block-end: var(--pill-pad);
+}
+
+.root[data-placement='top'] .row {
+  padding-block-start: var(--pill-pad);
+}
+
+.button {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  min-block-size: var(--hl-hit-min);
+  max-inline-size: 100%;
+  padding: 0;
+  border: 0;
+  border-radius: var(--hl-radius-full);
+  background: transparent;
+  color: inherit;
+  box-shadow: inset 0 0 0 var(--hl-line) var(--pill-key);
+  font: inherit;
+  font-size: var(--hl-text-sm);
+  font-weight: var(--hl-weight-semibold);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+  overflow: clip;
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+  transition: box-shadow var(--hl-motion-fast) var(--hl-ease-out);
+}
+
+.button:focus-visible {
+  outline: var(--hl-line-focus) solid var(--hl-color-accent);
+  outline-offset: calc(var(--hl-line-focus) * -2);
+}
+
+/* Open, the pill stops being a chip: its outline goes, and its words read as the card's last row. */
+.shell[data-open] .button {
+  box-shadow: inset 0 0 0 var(--hl-line) transparent;
+}
+
+.stack {
+  display: grid;
+}
+
+.face {
+  grid-area: 1 / 1;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--hl-space-3);
+  block-size: var(--hl-hit-min);
+  padding-inline: var(--hl-space-5);
+}
+
+.face svg {
+  flex: none;
+  font-size: var(--hl-icon-md);
+}
+
+/* The pill as its own progress bar: words under the fill turn to the fill's own ink. */
+.over {
+  background: var(--pill-fill);
+  color: var(--pill-fill-fg);
+  clip-path: inset(0 calc(100% - var(--p) * 100%) 0 0);
+  transition:
+    clip-path var(--hl-motion-slow) var(--hl-ease-out),
+    opacity var(--hl-motion-fast) var(--hl-ease-out);
+}
+
+.over:dir(rtl) {
+  clip-path: inset(0 0 0 calc(100% - var(--p) * 100%));
+}
+
+.shell[data-open] .over {
+  opacity: 0;
+}
+
+.body {
+  padding: var(--hl-space-2) var(--hl-space-6) var(--hl-space-6);
+  opacity: 0;
+  transition: opacity var(--hl-motion-instant) var(--hl-ease-in);
+}
+
+.root[data-placement='bottom'] .body {
+  padding: var(--hl-space-6) var(--hl-space-6) var(--hl-space-2);
+}
+
+.shell[data-open] .body {
+  opacity: 1;
+  transition: opacity var(--hl-motion-base) var(--hl-ease-out) var(--hl-motion-fast);
+}
+
+.sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}

package/src/components/LivePill/LivePill.tsx

@@ -0,0 +1,181 @@
+'use client'
+
+import { useEffect, useLayoutEffect, useRef, useState, type ComponentPropsWithRef, type CSSProperties, type ReactNode } from 'react'
+import { cx } from '../../internal/cx'
+import { motionMs } from '../../internal/motion'
+import { useControllable } from '../../internal/useControllable'
+import styles from './LivePill.module.css'
+
+export type LivePillProps = Omit<ComponentPropsWithRef<'div'>, 'children' | 'title'> & {
+  /** Screen reader name of the pill, the whole state in words, such as "Map download, 63%". */
+  label: string
+  /** What the small pill shows, such as an icon, a word and a number. It stays on its spot when the pill opens. */
+  compact: ReactNode
+  /** What the open card shows above (or below) the pill's own row. */
+  children: ReactNode
+  /** Whether it is open, when you control it. */
+  open?: boolean
+  /** Starting open state when you do not control it. */
+  defaultOpen?: boolean
+  /** Called with the new open state. */
+  onOpenChange?: (open: boolean) => void
+  /** Where it sits. At the bottom it is in thumb reach and grows up; at the top it grows down. */
+  placement?: 'bottom' | 'top'
+  /** Pins it to the screen edge, clear of the safe area. Leave off to place it yourself. */
+  fixed?: boolean
+  /** From 0 to 1: the pill fills from its start like a progress bar, and its words change ink under the fill. */
+  progress?: number
+  /** "paper" is a light pill with an outline; "ink" is a solid dark one. */
+  tone?: 'paper' | 'ink'
+  /** News for screen readers, said once each time it changes, such as "Download paused". Never a ticking number. */
+  news?: string
+  /** News that opens the pill by itself, such as "Rider is at your door". Said once, and the pill shrinks back after alertMs. */
+  alert?: string
+  /** How long an alert keeps it open, in ms. A hand or focus on the pill holds it open. */
+  alertMs?: number
+}
+
+// What the pill can hand focus to when it closes from a tap outside, so a tap on another control keeps it.
+const TAKES_FOCUS = 'a[href], button, input, select, textarea, label, [tabindex]:not([tabindex="-1"])'
+
+export function LivePill({
+  label,
+  compact,
+  children,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  placement = 'bottom',
+  fixed = false,
+  progress,
+  tone = 'paper',
+  news,
+  alert,
+  alertMs = 5000,
+  className,
+  style,
+  ...rest
+}: LivePillProps) {
+  const [open, setOpen] = useControllable(openProp, defaultOpen, onOpenChange)
+  const shell = useRef<HTMLDivElement>(null)
+  const button = useRef<HTMLButtonElement>(null)
+  const [shut, setShut] = useState<string>()
+  const [rowH, setRowH] = useState<number>()
+  const [byAlert, setByAlert] = useState(false)
+  const [held, setHeld] = useState(false)
+  const [said, setSaid] = useState('')
+  const lastNews = useRef(news)
+  const lastAlert = useRef(alert)
+
+  // Shut, the card is cut back to the button's own box, so the pill grows out of its own spot.
+  useLayoutEffect(() => {
+    const sh = shell.current
+    const b = button.current
+    if (!sh || !b) return
+    const measure = () => {
+      const right = sh.offsetWidth - b.offsetLeft - b.offsetWidth
+      const bottom = sh.offsetHeight - b.offsetTop - b.offsetHeight
+      setShut(`inset(${b.offsetTop}px ${right}px ${bottom}px ${b.offsetLeft}px round ${b.offsetHeight / 2}px)`)
+      const row = b.parentElement as HTMLElement
+      setRowH(row.offsetHeight)
+    }
+    measure()
+    const ro = new ResizeObserver(measure)
+    ro.observe(sh)
+    ro.observe(b)
+    return () => ro.disconnect()
+  }, [])
+
+  useEffect(() => {
+    if (news === lastNews.current) return
+    lastNews.current = news
+    if (news) setSaid(news)
+  }, [news])
+
+  useEffect(() => {
+    if (alert === lastAlert.current) return
+    lastAlert.current = alert
+    if (!alert) return
+    setSaid(alert)
+    // Only a card the alert opened shrinks back by itself; one the person opened stays.
+    if (open) return
+    setByAlert(true)
+    setOpen(true)
+  }, [alert, setOpen])
+
+  const close = (refocus: boolean) => {
+    setByAlert(false)
+    setOpen(false)
+    if (refocus) button.current?.focus({ preventScroll: true })
+  }
+  const focusInside = () => !!shell.current?.contains(document.activeElement) && document.activeElement !== button.current
+
+  useEffect(() => {
+    if (!open) {
+      setByAlert(false)
+      return
+    }
+    const outside = (e: PointerEvent) => {
+      const target = e.target instanceof Element ? e.target : null
+      if (!target || shell.current?.contains(target)) return
+      const inside = focusInside()
+      close(false)
+      if (inside && !target.closest(TAKES_FOCUS)) window.setTimeout(() => button.current?.focus({ preventScroll: true }))
+    }
+    document.addEventListener('pointerdown', outside)
+    return () => document.removeEventListener('pointerdown', outside)
+  }, [open])
+
+  useEffect(() => {
+    if (!open || !byAlert || held) return
+    const t = window.setTimeout(() => close(focusInside()), Math.max(alertMs, motionMs('liquid')))
+    return () => window.clearTimeout(t)
+  }, [open, byAlert, held, alertMs])
+
+  const p = progress === undefined ? undefined : Math.min(1, Math.max(0, progress))
+  const vars = { '--pill-shut': shut, '--pill-row': rowH === undefined ? undefined : `${rowH}px`, '--p': p, ...style } as CSSProperties
+
+  return (
+    <div className={cx(styles.root, className)} data-placement={placement} data-fixed={fixed || undefined} style={vars} {...rest}>
+      <div
+        ref={shell}
+        className={styles.shell}
+        data-open={open || undefined}
+        data-measured={shut ? '' : undefined}
+        data-tone={tone}
+        onKeyDown={(e) => {
+          if (e.key !== 'Escape' || !open) return
+          e.stopPropagation()
+          close(true)
+        }}
+        onPointerEnter={() => setHeld(true)}
+        onPointerLeave={() => setHeld(false)}
+        onFocus={() => setHeld(true)}
+        onBlur={(e) => {
+          if (!e.currentTarget.contains(e.relatedTarget as Node)) setHeld(false)
+        }}
+      >
+        <div className={styles.row}>
+          <button ref={button} type="button" className={styles.button} data-fill={p === undefined ? undefined : ''} aria-expanded={open} aria-label={label} onClick={() => (open ? close(false) : setOpen(true))}>
+            {p === undefined ? (
+              <span className={styles.face}>{compact}</span>
+            ) : (
+              <span className={styles.stack}>
+                <span className={styles.face}>{compact}</span>
+                <span className={cx(styles.face, styles.over)} aria-hidden="true">
+                  {compact}
+                </span>
+              </span>
+            )}
+          </button>
+        </div>
+        <div className={styles.body} inert={!open} aria-hidden={!open || undefined}>
+          {children}
+        </div>
+      </div>
+      <span className={styles.sr} role="status" aria-live="polite" aria-atomic="true">
+        {said}
+      </span>
+    </div>
+  )
+}

package/src/components/LivePill/index.ts

@@ -0,0 +1 @@
+export * from './LivePill'

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

@@ -109,6 +109,10 @@
 /* Segments touch, so the box itself is the 44px target. The floor sits on the content, so the
    overflow check still sees the natural width, and tight mode shrinks no further than 44px. */
 @media (pointer: coarse) {
+  .item,
+  .sm .item {
+    min-height: var(--hl-hit-min);
+  }
   .text,
   .icon:only-child {
     min-width: calc(var(--hl-hit-min) - var(--pad) * 2);

package/src/components/SplitFlap/SplitFlap.module.css

@@ -0,0 +1,107 @@
+.root {
+  display: inline-flex;
+  vertical-align: middle;
+  font-size: var(--hl-text-xl);
+  font-weight: var(--hl-weight-semibold);
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+}
+
+.root[data-size='sm'] {
+  font-size: var(--hl-text-md);
+}
+
+.root[data-size='lg'] {
+  font-size: var(--hl-text-4xl);
+}
+
+.sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+.board {
+  display: inline-flex;
+  gap: var(--hl-space-1);
+  border-radius: var(--hl-radius-xs);
+}
+
+.root[data-size='lg'] .board {
+  gap: var(--hl-space-2);
+}
+
+.cell {
+  position: relative;
+  display: block;
+  inline-size: var(--hl-flap-w);
+  block-size: var(--hl-flap-h);
+  perspective: calc(var(--hl-flap-h) * 3);
+  color: var(--hl-color-fg);
+}
+
+/* Two halves with a hairline seam between them, where the page shows through. */
+.top,
+.bottom,
+.front,
+.back {
+  position: absolute;
+  inset-inline: 0;
+  block-size: calc(50% - var(--hl-line) / 2);
+  overflow: hidden;
+}
+
+.top,
+.front {
+  top: 0;
+  border-radius: var(--hl-radius-xs) var(--hl-radius-xs) 0 0;
+  background: var(--hl-flap-top);
+}
+
+.bottom,
+.back {
+  bottom: 0;
+  border-radius: 0 0 var(--hl-radius-xs) var(--hl-radius-xs);
+  background: var(--hl-flap-bottom);
+}
+
+.glyph {
+  position: absolute;
+  inset-inline: 0;
+  top: 0;
+  block-size: var(--hl-flap-h);
+  line-height: var(--hl-flap-h);
+  text-align: center;
+}
+
+.bottom .glyph,
+.back .glyph {
+  top: auto;
+  bottom: 0;
+}
+
+/* The falling flap turns on the seam, so after half a turn its back lies over the bottom half. */
+.flap {
+  position: absolute;
+  inset-inline: 0;
+  top: 0;
+  z-index: 1;
+  block-size: calc(50% - var(--hl-line) / 2);
+  transform-origin: 50% calc(100% + var(--hl-line) / 2);
+  transform-style: preserve-3d;
+}
+
+.front,
+.back {
+  block-size: 100%;
+  backface-visibility: hidden;
+}
+
+.back {
+  top: 0;
+  bottom: auto;
+  transform: rotateX(180deg);
+}