hlmnhkl-ui 0.25.1 → 0.27.0

package/README.md

@@ -65,7 +65,7 @@ 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.
-- **59 free components**, from Button, Dialog, Select and Table to Toast and Retime, one speed setting for every animation. See [COMPONENTS.md](COMPONENTS.md).
+- **63 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. CalendarHeatmap's days are small by design, since a year must fit on screen; its month table gives the same numbers at full size.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hlmnhkl-ui",
-  "version": "0.25.1",
+  "version": "0.27.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/src/components/Fab/Fab.module.css

@@ -0,0 +1,172 @@
+/* In the thumb zone: the bottom corner of the screen, clear of the home indicator and a notch. */
+.root {
+  position: fixed;
+  bottom: calc(env(safe-area-inset-bottom) + var(--hl-fab-gap));
+  z-index: var(--hl-z-sticky);
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--hl-space-4);
+  pointer-events: none;
+}
+
+.end { right: calc(env(safe-area-inset-right) + var(--hl-fab-gap)); }
+
+.center {
+  left: 50%;
+  align-items: center;
+  translate: -50% 0;
+}
+
+.contained { position: absolute; }
+.contained.end { right: var(--hl-fab-gap); }
+.contained { bottom: var(--hl-fab-gap); }
+
+.fab {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  min-width: var(--hl-fab-size);
+  height: var(--hl-fab-size);
+  padding: 0 calc((var(--hl-fab-size) - var(--hl-icon-md)) / 2);
+  border: 0;
+  border-radius: var(--hl-radius-full);
+  background: var(--hl-color-accent);
+  color: var(--hl-color-accent-fg);
+  box-shadow: var(--hl-shadow-3);
+  font: inherit;
+  font-weight: var(--hl-weight-medium);
+  cursor: pointer;
+  pointer-events: auto;
+  -webkit-tap-highlight-color: transparent;
+  transition:
+    background-color var(--hl-motion-fast) var(--hl-ease-out),
+    scale var(--hl-motion-fast) var(--hl-ease-out);
+}
+
+@media (hover: hover) {
+  .fab:hover { background: var(--hl-color-inverse-hover); }
+}
+
+.fab:active { scale: var(--hl-press-scale); }
+.fab:focus-visible { outline: none; box-shadow: var(--hl-shadow-3), var(--hl-focus-ring); }
+
+.icon {
+  display: grid;
+  place-items: center;
+  flex: none;
+  width: var(--hl-icon-md);
+  height: var(--hl-icon-md);
+  transition: rotate var(--hl-motion-slow) var(--hl-ease-spring);
+}
+
+.icon > svg { width: 100%; height: 100%; }
+
+/* Open: the icon turns a quarter, the way a plus becomes a cross. */
+.root[data-open] .icon { rotate: 45deg; }
+
+/* The label pours away into the icon: its column closes, so the pill shrinks to a circle around the icon. */
+.labelWrap {
+  display: grid;
+  grid-template-columns: 0fr;
+  transition: grid-template-columns var(--hl-motion-slower) var(--hl-ease-in-out);
+}
+
+.fab[data-extended] .labelWrap { grid-template-columns: 1fr; }
+
+.label {
+  min-width: 0;
+  overflow: hidden;
+  padding-inline-start: 0;
+  white-space: nowrap;
+  opacity: 0;
+  transition:
+    opacity var(--hl-motion-base) var(--hl-ease-out),
+    padding var(--hl-motion-slower) var(--hl-ease-in-out);
+}
+
+.fab[data-extended] .label {
+  padding-inline: var(--hl-space-3) var(--hl-space-2);
+  opacity: 1;
+  transition-delay: 0s, 0s;
+}
+
+/* The actions pour up out of the button, the nearest first, each a short step after the last. */
+.actions {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--hl-space-3);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.center .actions { align-items: center; }
+
+.actions li {
+  opacity: 0;
+  translate: 0 var(--hl-shift-md);
+  scale: 0.6;
+  transform-origin: 100% 100%;
+  transition:
+    opacity var(--hl-motion-base) var(--hl-ease-out),
+    translate var(--hl-motion-slow) var(--hl-ease-spring),
+    scale var(--hl-motion-slow) var(--hl-ease-spring);
+}
+
+.center .actions li { transform-origin: 50% 100%; }
+
+.root[data-open] .actions li {
+  opacity: 1;
+  translate: none;
+  scale: 1;
+  transition-delay: calc(var(--i) * var(--hl-motion-stagger) * 2);
+}
+
+.action {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--hl-space-4);
+  min-height: var(--hl-hit-min);
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--hl-color-fg);
+  font: inherit;
+  cursor: pointer;
+  pointer-events: auto;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.actionLabel {
+  padding: var(--hl-space-2) var(--hl-space-4);
+  border-radius: var(--hl-radius-full);
+  background: var(--hl-color-surface);
+  box-shadow: var(--hl-shadow-2);
+  font-size: var(--hl-text-sm);
+  font-weight: var(--hl-weight-medium);
+  white-space: nowrap;
+}
+
+/* Lined up under the button's centre: a smaller circle in the same column. */
+.actionIcon {
+  display: grid;
+  place-items: center;
+  width: var(--hl-hit-min);
+  height: var(--hl-hit-min);
+  margin-inline-end: calc((var(--hl-fab-size) - var(--hl-hit-min)) / 2);
+  border-radius: var(--hl-radius-full);
+  background: var(--hl-color-surface);
+  box-shadow: var(--hl-shadow-2);
+}
+
+.actionIcon > svg { width: var(--hl-icon-sm); height: var(--hl-icon-sm); }
+
+@media (hover: hover) {
+  .action:hover .actionIcon,
+  .action:hover .actionLabel { background: var(--hl-color-surface-hover); }
+}
+
+.action:focus-visible { outline: none; }
+.action:focus-visible .actionIcon { box-shadow: var(--hl-shadow-2), var(--hl-focus-ring); }

package/src/components/Fab/Fab.tsx

@@ -0,0 +1,117 @@
+'use client'
+
+import { useId, useRef, useState, type ReactNode } from 'react'
+import { cx } from '../../internal/cx'
+import { useDismiss } from '../../internal/layers'
+import { useScrollFrame } from '../../internal/scrollFrame'
+import styles from './Fab.module.css'
+
+export type FabAction = {
+  /** Shown beside the action's button and read as its name. */
+  label: string
+  icon: ReactNode
+  onSelect: () => void
+}
+
+export type FabProps = {
+  /** The button's name. Shown as text when extended, and always read by screen readers. */
+  label: string
+  /** The icon in the button, such as a plus. With actions it turns a quarter while they are open. */
+  icon: ReactNode
+  /** Called on tap. With actions, a tap opens them instead. */
+  onClick?: () => void
+  /** Shows the label beside the icon. It pours away into the icon as the page scrolls down, and back on the way up. */
+  extended?: boolean
+  /** A short stack of actions that pours up out of the button when it is tapped. */
+  actions?: FabAction[]
+  /** Where it sits along the bottom of the screen. */
+  position?: 'end' | 'center'
+  /** Sits at the bottom of its nearest positioned parent instead of the screen, for a demo or a panel. */
+  contained?: boolean
+  /** Extra class for the root element. */
+  className?: string
+}
+
+// One main action, floating in the thumb zone at the bottom of the screen.
+export function Fab({ label, icon, onClick, extended = false, actions, position = 'end', contained = false, className }: FabProps) {
+  const id = useId()
+  const rootRef = useRef<HTMLDivElement>(null)
+  const buttonRef = useRef<HTMLButtonElement>(null)
+  const firstRef = useRef<HTMLButtonElement>(null)
+  const [open, setOpen] = useState(false)
+  const [compact, setCompact] = useState(false)
+  const last = useRef<number | null>(null)
+
+  // Extended: down the page it folds to the icon, back up it opens again. It reads the scroll, never a timer.
+  useScrollFrame(
+    () => {
+      const y = window.scrollY
+      const prev = last.current
+      last.current = y
+      if (prev === null || Math.abs(y - prev) < 4) return
+      const next = y > prev && y > 80
+      return () => setCompact(next)
+    },
+    extended,
+  )
+
+  useDismiss(open, [rootRef], (reason) => {
+    setOpen(false)
+    if (reason === 'escape') buttonRef.current?.focus()
+  })
+
+  const hasActions = Boolean(actions?.length)
+  const toggle = () => {
+    if (!hasActions) return onClick?.()
+    const next = !open
+    setOpen(next)
+    if (next) requestAnimationFrame(() => firstRef.current?.focus())
+  }
+
+  return (
+    <div ref={rootRef} className={cx(styles.root, styles[position], contained && styles.contained, className)} data-open={open || undefined}>
+      {hasActions && (
+        <ul id={`${id}-actions`} className={styles.actions} inert={!open}>
+          {actions!.map((a, i) => (
+            <li key={a.label} style={{ ['--i' as string]: actions!.length - 1 - i }}>
+              <button
+                ref={i === 0 ? firstRef : undefined}
+                type="button"
+                className={styles.action}
+                onClick={() => {
+                  setOpen(false)
+                  buttonRef.current?.focus()
+                  a.onSelect()
+                }}
+              >
+                <span className={styles.actionLabel}>{a.label}</span>
+                <span className={styles.actionIcon} aria-hidden="true">
+                  {a.icon}
+                </span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      <button
+        ref={buttonRef}
+        type="button"
+        className={styles.fab}
+        aria-label={extended ? undefined : label}
+        aria-expanded={hasActions ? open : undefined}
+        aria-controls={hasActions ? `${id}-actions` : undefined}
+        data-extended={(extended && !compact) || undefined}
+        onClick={toggle}
+      >
+        <span className={styles.icon} aria-hidden="true">
+          {icon}
+        </span>
+        {extended && (
+          <span className={styles.labelWrap}>
+            <span className={styles.label}>{label}</span>
+          </span>
+        )}
+      </button>
+    </div>
+  )
+}

package/src/components/Fab/index.ts

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

package/src/components/Prose/Prose.module.css

@@ -0,0 +1,115 @@
+/* A line of about 68 characters, the length an eye can follow back to the next line without losing it.
+   :where keeps every rule at zero weight, so a class you add inside always wins. */
+.root {
+  max-width: var(--hl-prose-w);
+  color: var(--hl-color-fg);
+  font-size: var(--hl-text-md);
+  line-height: var(--hl-leading-normal);
+  overflow-wrap: break-word;
+}
+
+.root > :where(:first-child) { margin-top: 0; }
+.root > :where(:last-child) { margin-bottom: 0; }
+
+.root :where(p, ul, ol, blockquote, pre, figure, table, hr) { margin: 0 0 var(--hl-space-6); }
+
+/* A heading sits close to the text it opens and well clear of the text before it. */
+.root :where(h2, h3, h4) {
+  margin: var(--hl-space-10) 0 var(--hl-space-4);
+  font-weight: var(--hl-weight-semibold);
+  letter-spacing: var(--hl-tracking-tight);
+  line-height: var(--hl-leading-tight);
+  text-wrap: balance;
+}
+
+.root :where(h2) { font-size: var(--hl-text-2xl); }
+.root :where(h3) { font-size: var(--hl-text-xl); }
+.root :where(h4) { font-size: var(--hl-text-lg); }
+.root :where(h2, h3, h4) + :where(h3, h4) { margin-top: var(--hl-space-5); }
+
+.root :where(strong) { font-weight: var(--hl-weight-semibold); }
+
+.root :where(a) {
+  color: var(--hl-color-fg);
+  font-weight: var(--hl-weight-medium);
+  text-decoration: underline;
+  text-decoration-color: var(--hl-color-border-strong);
+  text-decoration-thickness: var(--hl-line);
+  text-underline-offset: 0.2em;
+  transition: text-decoration-color var(--hl-motion-fast) var(--hl-ease-out);
+}
+
+@media (hover: hover) {
+  .root :where(a):hover { text-decoration-color: currentColor; }
+}
+
+.root :where(a):focus-visible { outline: none; border-radius: var(--hl-radius-xs); box-shadow: var(--hl-focus-ring); }
+
+.root :where(ul, ol) { padding-left: var(--hl-space-6); }
+.root :where(li) { margin-bottom: var(--hl-space-2); padding-left: var(--hl-space-1); }
+.root :where(li) > :where(ul, ol) { margin: var(--hl-space-2) 0 0; }
+.root :where(li)::marker { color: var(--hl-color-fg-subtle); }
+
+/* A quote sits on a soft panel of its own, not behind a line down its side. */
+.root :where(blockquote) {
+  padding: var(--hl-space-5) var(--hl-space-6);
+  border-radius: var(--hl-radius-md);
+  background: var(--hl-color-surface-sunken);
+  color: var(--hl-color-fg-muted);
+}
+
+.root :where(blockquote) > :where(:last-child) { margin-bottom: 0; }
+
+.root :where(code) {
+  padding: 0.1em 0.35em;
+  border-radius: var(--hl-radius-xs);
+  background: var(--hl-color-surface-sunken);
+  font-family: var(--hl-font-mono);
+  font-size: 0.9em;
+}
+
+.root :where(pre) {
+  overflow-x: auto;
+  padding: var(--hl-space-5);
+  border-radius: var(--hl-radius-md);
+  background: var(--hl-code-bg);
+  color: var(--hl-code-fg);
+  font-size: var(--hl-text-sm);
+  line-height: var(--hl-leading-normal);
+}
+
+.root :where(pre) :where(code) { padding: 0; background: none; font-size: inherit; }
+
+.root :where(img, video) {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--hl-radius-md);
+}
+
+.root :where(figcaption) {
+  margin-top: var(--hl-space-3);
+  color: var(--hl-color-fg-muted);
+  font-size: var(--hl-text-sm);
+}
+
+.root :where(hr) {
+  height: 0;
+  border: 0;
+  border-top: var(--hl-line) solid var(--hl-color-border);
+}
+
+.root :where(table) {
+  display: block;
+  overflow-x: auto;
+  border-collapse: collapse;
+  font-size: var(--hl-text-sm);
+}
+
+.root :where(th, td) {
+  padding: var(--hl-space-3) var(--hl-space-4);
+  border-bottom: var(--hl-line) solid var(--hl-color-border);
+  text-align: left;
+}
+
+.root :where(th) { font-weight: var(--hl-weight-semibold); }

package/src/components/Prose/Prose.tsx

@@ -0,0 +1,14 @@
+import type { ComponentPropsWithRef, ElementType } from 'react'
+import { cx } from '../../internal/cx'
+import styles from './Prose.module.css'
+
+export type ProseProps = {
+  /** The element to render, such as article. */
+  as?: ElementType
+} & ComponentPropsWithRef<'div'>
+
+// Long text written elsewhere, such as Markdown or a CMS: headings, paragraphs, lists, quotes, code and
+// pictures, set for reading. It styles plain HTML inside it, so nothing needs a class.
+export function Prose({ as: Tag = 'div', className, ...rest }: ProseProps) {
+  return <Tag className={cx(styles.root, className)} {...rest} />
+}

package/src/components/Prose/index.ts

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

package/src/components/TableOfContents/TableOfContents.module.css

@@ -0,0 +1,107 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--hl-space-3);
+}
+
+.title {
+  margin: 0 0 var(--hl-space-2);
+  font-size: var(--hl-text-sm);
+  font-weight: var(--hl-weight-semibold);
+  color: var(--hl-color-fg);
+}
+
+/* A strip of frames, one per section, threaded on a faint line through their middles. */
+.list {
+  position: relative;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.list::before {
+  content: "";
+  position: absolute;
+  top: var(--hl-space-6);
+  bottom: var(--hl-space-6);
+  left: calc(var(--hl-space-3) + var(--hl-space-2) - var(--hl-line) / 2);
+  border-left: var(--hl-line) solid var(--hl-color-border);
+}
+
+/* Looks compact but keeps a 44px hit area with an invisible layer. */
+.link {
+  position: relative;
+  display: flex;
+  align-items: baseline;
+  gap: var(--hl-space-4);
+  width: 100%;
+  min-height: var(--hl-control-h-sm);
+  padding: var(--hl-space-2) var(--hl-space-3);
+  border-radius: var(--hl-radius-sm);
+  color: var(--hl-color-fg-muted);
+  font-size: var(--hl-text-sm);
+  line-height: var(--hl-leading-snug);
+  text-decoration: none;
+  transition: color var(--hl-motion-fast) var(--hl-ease-out), background-color var(--hl-motion-fast) var(--hl-ease-out);
+}
+
+.link::after {
+  content: "";
+  position: absolute;
+  inset-inline: 0;
+  inset-block: min(0px, calc((100% - var(--hl-hit-min)) / 2));
+}
+
+@media (hover: hover) {
+  .link:hover { color: var(--hl-color-fg); background: var(--hl-color-surface-hover); }
+}
+
+.link:focus-visible { outline: none; box-shadow: var(--hl-focus-ring); }
+
+/* Each section's frame: open ahead, filled once read, ringed where the reader is. */
+.node {
+  position: relative;
+  z-index: 1;
+  flex: none;
+  width: var(--hl-space-4);
+  height: var(--hl-space-4);
+  translate: 0 calc(var(--hl-space-1) / 2);
+  border: var(--hl-line-thick) solid var(--hl-color-border-strong);
+  border-radius: var(--hl-radius-full);
+  background: var(--hl-color-bg);
+  transition:
+    background-color var(--hl-motion-base) var(--hl-ease-out),
+    border-color var(--hl-motion-base) var(--hl-ease-out),
+    box-shadow var(--hl-motion-base) var(--hl-ease-out);
+}
+
+[data-state="read"] .node { border-color: var(--hl-color-fg-subtle); background: var(--hl-color-fg-subtle); }
+
+[data-state="here"] .link { color: var(--hl-color-fg); font-weight: var(--hl-weight-medium); }
+
+[data-state="here"] .node {
+  border-color: var(--hl-color-fg);
+  background: var(--hl-color-fg);
+  box-shadow: 0 0 0 var(--hl-space-1) var(--hl-color-bg), 0 0 0 calc(var(--hl-space-1) + var(--hl-line-thick)) var(--hl-color-fg);
+}
+
+.toTop {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--hl-space-2);
+  align-self: flex-start;
+  min-height: var(--hl-hit-min);
+  padding-inline: var(--hl-space-3);
+  border-radius: var(--hl-radius-sm);
+  color: var(--hl-color-fg-muted);
+  font-size: var(--hl-text-sm);
+  text-decoration: none;
+}
+
+.toTop > svg { width: var(--hl-icon-sm); height: var(--hl-icon-sm); }
+
+@media (hover: hover) {
+  .toTop:hover { color: var(--hl-color-fg); background: var(--hl-color-surface-hover); }
+}
+
+.toTop:focus-visible { outline: none; box-shadow: var(--hl-focus-ring); }

package/src/components/TableOfContents/TableOfContents.tsx

@@ -0,0 +1,93 @@
+'use client'
+
+import { useEffect, useState, type MouseEvent } from 'react'
+import { cx } from '../../internal/cx'
+import { ArrowUpIcon } from '../../internal/icons'
+import { prefersReducedMotion } from '../../internal/motion'
+import styles from './TableOfContents.module.css'
+
+export type TocItem = {
+  /** The id of the heading on the page. */
+  id: string
+  label: string
+}
+
+export type TableOfContentsProps = {
+  /** The sections, in page order: each heading's id and the text to show for it. */
+  items: TocItem[]
+  /** Heading above the list, also the nav's name. */
+  title?: string
+  /** Adds a way back to the top once the reader has passed the first section. */
+  backToTop?: boolean
+  /** Extra class for the root element. */
+  className?: string
+}
+
+// The sections of a page as links to their headings. Each is a frame on a strip: filled once read, ringed
+// where the reader is, open ahead, so it shows how far through the page they are, not only where.
+export function TableOfContents({ items, title = 'On this page', backToTop = false, className }: TableOfContentsProps) {
+  const [active, setActive] = useState(items[0]?.id)
+
+  // The section being read is the last heading past the top third of the screen.
+  useEffect(() => {
+    const headings = items.map((t) => document.getElementById(t.id)).filter((h): h is HTMLElement => !!h)
+    const update = () => {
+      const line = window.innerHeight / 3
+      let current = headings[0]?.id
+      for (const h of headings) if (h.getBoundingClientRect().top <= line) current = h.id
+      // A short last section never reaches the line, so the bottom of the page selects it.
+      const atBottom = window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2
+      setActive(atBottom ? headings[headings.length - 1]?.id : current)
+    }
+    update()
+    window.addEventListener('scroll', update, { passive: true })
+    window.addEventListener('resize', update)
+    return () => {
+      window.removeEventListener('scroll', update)
+      window.removeEventListener('resize', update)
+    }
+  }, [items])
+
+  const plain = (e: MouseEvent) => e.button === 0 && !e.metaKey && !e.ctrlKey && !e.shiftKey && !e.altKey
+
+  // A plain click scrolls there and keeps one history entry; Cmd-click still opens a new tab.
+  const go = (e: MouseEvent<HTMLAnchorElement>, id: string) => {
+    const heading = document.getElementById(id)
+    if (!plain(e) || !heading) return
+    e.preventDefault()
+    heading.scrollIntoView({ behavior: prefersReducedMotion() ? 'auto' : 'smooth', block: 'start' })
+    if (!heading.hasAttribute('tabindex')) heading.setAttribute('tabindex', '-1')
+    heading.focus({ preventScroll: true })
+    window.history.replaceState(window.history.state, '', `#${id}`)
+  }
+
+  const toTop = (e: MouseEvent<HTMLAnchorElement>) => {
+    if (!plain(e)) return
+    e.preventDefault()
+    window.scrollTo({ top: 0, behavior: prefersReducedMotion() ? 'auto' : 'smooth' })
+    window.history.replaceState(window.history.state, '', window.location.pathname + window.location.search)
+  }
+
+  const at = Math.max(0, items.findIndex((t) => t.id === active))
+  return (
+    <nav className={cx(styles.root, className)} aria-label={title}>
+      <p className={styles.title}>{title}</p>
+      <ol className={styles.list}>
+        {items.map((t, n) => (
+          <li key={t.id} data-state={n < at ? 'read' : n === at ? 'here' : 'ahead'}>
+            <a href={`#${t.id}`} className={styles.link} aria-current={active === t.id ? 'location' : undefined} onClick={(e) => go(e, t.id)}>
+              <span className={styles.node} aria-hidden="true" />
+              {t.label}
+            </a>
+          </li>
+        ))}
+      </ol>
+      {backToTop && at > 0 && (
+        <a href="#" className={styles.toTop} onClick={toTop}>
+          <ArrowUpIcon aria-hidden="true" />
+          Back to top
+        </a>
+      )}
+    </nav>
+  )
+}

package/src/components/TableOfContents/index.ts

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

package/src/components/ThemeToggle/ThemeToggle.module.css

@@ -0,0 +1,21 @@
+/* The sun and the moon share one spot: the one for the other theme turns away and shrinks as the
+   current one turns in. */
+.icon {
+  display: grid;
+  width: 1em;
+  height: 1em;
+}
+
+.sun,
+.moon {
+  grid-area: 1 / 1;
+  width: 100%;
+  height: 100%;
+  transition:
+    transform var(--hl-motion-slower) var(--hl-ease-spring),
+    opacity var(--hl-motion-base) var(--hl-ease-out);
+}
+
+/* Shows the theme the button switches to: the moon in light, the sun in dark. */
+.icon:not([data-theme-shown="dark"]) .sun { opacity: 0; transform: rotate(90deg) scale(0.4); }
+.icon[data-theme-shown="dark"] .moon { opacity: 0; transform: rotate(-90deg) scale(0.4); }

package/src/components/ThemeToggle/ThemeToggle.tsx

@@ -0,0 +1,69 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { MoonIcon, SunIcon } from '../../internal/icons'
+import { IconButton } from '../IconButton'
+import styles from './ThemeToggle.module.css'
+
+export type Theme = 'light' | 'dark'
+
+export type ThemeToggleProps = {
+  /** The theme, when your app keeps it. Leave it out and the toggle sets data-theme on <html> itself. */
+  theme?: Theme
+  /** Called with the new theme on every flip. */
+  onThemeChange?: (theme: Theme) => void
+  /** Where the choice is remembered when the toggle runs the page. Match it in themeScript. */
+  storageKey?: string
+  /** The button's size, the same as IconButton. */
+  size?: 'sm' | 'md' | 'lg'
+  /** Extra class for the button. */
+  className?: string
+}
+
+/** Put in <head>, before the page paints, so a saved dark theme never flashes light first. */
+export const themeScript = (storageKey = 'hl-theme') =>
+  `try{var t=localStorage.getItem(${JSON.stringify(storageKey)});if(t!=='light'&&t!=='dark')t=matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';document.documentElement.dataset.theme=t}catch(e){}`
+
+const pageTheme = (): Theme => (document.documentElement.dataset.theme === 'dark' ? 'dark' : 'light')
+
+// One button that flips between the light and dark theme. The sun turns into the moon and back.
+export function ThemeToggle({ theme: themeProp, onThemeChange, storageKey = 'hl-theme', size = 'sm', className }: ThemeToggleProps) {
+  const controlled = themeProp !== undefined
+  const [own, setOwn] = useState<Theme>('light')
+  const theme = controlled ? themeProp : own
+
+  // Read after mount: the server cannot know the page's theme, and themeScript has already set it.
+  useEffect(() => {
+    if (!controlled) setOwn(pageTheme())
+  }, [controlled])
+
+  const next: Theme = theme === 'dark' ? 'light' : 'dark'
+  const flip = () => {
+    if (!controlled) {
+      document.documentElement.dataset.theme = next
+      try {
+        localStorage.setItem(storageKey, next)
+      } catch {
+        // Not saved, so it lasts only this visit; the theme still changes.
+      }
+      setOwn(next)
+    }
+    onThemeChange?.(next)
+  }
+
+  return (
+    <IconButton
+      label={`Switch to ${next} theme`}
+      variant="secondary"
+      size={size}
+      className={className}
+      onClick={flip}
+      icon={
+        <span className={styles.icon} data-theme-shown={theme}>
+          <SunIcon className={styles.sun} />
+          <MoonIcon className={styles.moon} />
+        </span>
+      }
+    />
+  )
+}

package/src/components/ThemeToggle/index.ts

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

package/src/tokens.css

@@ -72,6 +72,8 @@
   --hl-leading-tight: 1.2;
   --hl-leading-snug: 1.4;
   --hl-leading-normal: 1.6;
+  /* Prose: the longest line of reading text, about the most an eye follows back to the next line */
+  --hl-prose-w: 68ch;
   --hl-weight-regular: 400;
   --hl-weight-medium: 500;
   --hl-weight-semibold: 600;
@@ -166,6 +168,8 @@
   --hl-motion-base: calc(220ms * var(--hl-motion-scale));
   --hl-motion-slow: calc(360ms * var(--hl-motion-scale));
   --hl-motion-slower: calc(600ms * var(--hl-motion-scale));
+  /* Navbar dock: the trip to and from the bottom of the screen, long enough to read as liquid */
+  --hl-motion-pour: calc(760ms * var(--hl-motion-scale));
   --hl-motion-stagger: calc(30ms * var(--hl-motion-scale));
   --hl-motion-delay-tooltip: 400ms;
   --hl-motion-shimmer: 1400ms;
@@ -296,6 +300,7 @@
     --hl-motion-base: 0ms;
     --hl-motion-slow: 0ms;
     --hl-motion-slower: 0ms;
+    --hl-motion-pour: 0ms;
     --hl-motion-stagger: 0ms;
     --hl-motion-shimmer: 0ms;
     --hl-motion-spin: 1600ms;
@@ -378,6 +383,9 @@
   --hl-navbar-h: 64px;
   /* Navbar float: how far the page scrolls while the bar lifts into a floating card */
   --hl-navbar-float-run: 160px;
+  /* Fab: the round button's size, and its gap from the bottom and side of the screen */
+  --hl-fab-size: 56px;
+  --hl-fab-gap: 16px;
   --hl-sidebar-w: 248px;
   --hl-sidebar-w-collapsed: 64px;
   --hl-tabbar-h: 64px;