Skip to content
中文

Behavior and scripts

A stylesheet decides how components look; one script decides how they behave. The script is a single file with no framework or library dependencies, kept at components/bundle.js and shipped with the stylesheet.

How to use it

  • Load the stylesheet, then this script, and that’s all. On load the script finds the components in the page and takes over; for content added later, call Hairline.init(container) once.
  • Behavior is declared through attributes on the markup—no scripting needed. Attributes all start with data-hao-.
  • Without the script, components still look right; they just don’t move. So write markup that holds up static: dialogs and menus carry hidden by default, and the calendar container can hold a static month first.
  • Switches, radios, checkboxes, segmented controls, selects, and accordions ride on native browser controls and never needed a script.

Attributes at a glance

AttributeWhereWhat it does
data-hao-open="id"A buttonOpens that dialog or sheet
data-hao-modal.hao-scrimMarks a true modal layer, covering the full screen
data-hao-closeA button inside a dialogCloses the dialog it sits in
data-hao-initialA button inside a dialogTakes focus when the dialog opens
data-hao-menu="id"A buttonOpens that menu
data-hao-calendar.hao-calRenders a month calendar you can page through
data-hao-toggleFilter chips, bookmarksToggles selected on click
data-hao-chips="single"Container of a filter chip groupOnly one in the group can be selected
data-hao-checkall="group"The “select all” checkboxControls the checkbox group of the same name
data-hao-tip="text"Any elementShows a tooltip on hover or focus
data-hao-toast="text"A buttonPops a toast on click
data-hao-stamp="id"A buttonReplays the stamp inside that container
data-min data-max data-step.hao-stepperRange and step of the stepper

Each component’s notes cover its own details.

What you can call on the script

CallWhat it does
Hairline.init(container)Takes over content added to the page later
Hairline.dialog.open(element), .close()Opens and closes a dialog or sheet
Hairline.menu.open(menu, button), .close()Opens and closes a menu
Hairline.toast(text, options)Pops a toast; options are ok, action, onAction, duration
Hairline.calendar.create(element)Turns a container into a month calendar and returns its control object
Hairline.calendar.lunar(date)Looks up the lunar date for a day
Hairline.calendar.termsSwap in your own solar term data source
Hairline.calendar.sourceSwap in your own lunar calendar data source
Hairline.stamp(container)Replays the stamp

Events

When a component changes, it fires an event on itself; the event bubbles, so you can listen at any level.

EventFired byPayload
hao-open, hao-closeDialogs, sheetsNone
hao-selectMenu itemsNone
hao-changeTabs, the month calendar, filter chips, bookmarks, steppers, ratings, list single-selectThe new value
hao-filesThe upload areaFiles dropped in

What’s done for accessibility

  • Focus management: when a dialog or sheet opens, focus is trapped, the rest of the page is made inert and stops scrolling with it; on close, focus returns to what triggered it. Menus do the same.
  • Keyboard: menus, tabs, the month calendar, ratings, and list single-select implement arrow keys, Home, and End by the usual conventions; overlays add Esc. A grouped control takes a single Tab stop.
  • Semantics: the script fills in the state attributes that matter (expanded, selected, pressed, current date); the month calendar is a full table structure, and every day reads out complete.
  • Announcement: toasts go into a polite live region and never steal focus.
  • Motion: with Reduce Motion on, entrance animations don’t play.

How accurate the calendar data is

  • The lunar calendar uses the browser’s built-in data. Almost every day is right, but the rare day whose new moon falls around midnight can be off by one (in testing, the 2027 Lunar New Year was off by a day).
  • Solar terms use an approximation; odd years can be off by a day, and only 2001 through 2100 are covered.
  • Both leave hooks to swap in authoritative data: Hairline.calendar.source and Hairline.calendar.terms. Any date in a product that can’t be wrong should be swapped.

What’s not done

  • Gestures like pull-to-refresh and the drag-down-to-dismiss sheet.
  • Table sorting and filtering, paged data loading, upload progress: these touch data, so the product using the system wires them up.
  • A scripted replacement for the select panel. Selects always use the native control; on the desktop the stylesheet makes the panel look like the menu, see Select.
  • This script is for the web. In native iOS apps, system controls provide these behaviors.