Components

Home-UI ships 48 hui-* elements and one stylesheet. The inventory, and what is deliberately left to the host, is UI-CONTRACT-003.

The pages here are grouped with the vocabulary of atomic design. The split describes how much of a host’s page an element accounts for, not how the source happens to be arranged. An element changes group only when its role changes, and its URL moves with it.

• Atoms are the controls a page is spelled from: a button, an input, a checkbox. Each does one thing - holds a value, or triggers an action - and none is built from another Home-UI element.
• Molecules bind a few atoms into one small unit: a field with its label and its error, a search box with its clear button, a date picker with its calendar. They own a gesture or a piece of form furniture the host would otherwise wire itself.
• Organisms are the larger, self-contained regions a page is assembled from: a dialog, a data table, a sidebar, a carousel. They still hold no application state - the host does - but they own enough structure to be a landmark on a page.
• Charts sit outside the three. The data-visualisation elements ship in their own file (ENH-009), and a reader looking for a chart looks for the word.

Atoms

• hui-button A button in the nova treatment, with shadcn's variant and size API. It carries no form value of its own; type="submit" and type="reset" drive the surrounding form.
• hui-checkbox A form-associated checkbox in the nova treatment. An unchecked box submits nothing at all, exactly like a native checkbox, and indeterminate draws a mixed state until the next toggle.
• hui-input A form-associated single-line text control. The native input lives in the shadow root and the host submits the value through ElementInternals, so it serialises with the enclosing form exactly as a native input would.
• hui-input-otp A one-time-code control of several single-character cells that join into one submitted value. Typing advances to the next cell and pasting distributes the code from the focused cell onward.
• hui-slider A form-associated range slider built on native range inputs, so the keyboard behaviour and accessibility semantics come from the platform. In range mode a second input submits one joined low,high value under a single name.
• hui-switch A binary switch sharing the checkbox wire format, so an off switch submits nothing and an on switch submits its value. It reports role="switch" so assistive technology announces it as a switch rather than a checkbox.
• hui-textarea A form-associated multi-line text control. It submits through ElementInternals like hui-input, and the optional auto-resize keeps the field as tall as its content.
• hui-toggle A pressed-state button. On its own it toggles a visual pressed state and carries no form value; given a name, it serialises its value while pressed, like a checkbox.

Molecules

• hui-accordion A disclosure list with one shared keyboard behaviour. A collapsible single-item accordion is shadcn's Collapsible, so there is no separate component.
• hui-button-group A layout-only wrapper that arranges slotted buttons in a row or a column with one shared rounded outline. It owns no value and is not form-associated.
• hui-calendar A role="grid" month view whose value is an ISO date. The pure date arithmetic lives in a shared module and Intl supplies the month and weekday names, so the host's locale is honoured.
• hui-combobox A select whose text input filters the options the host rendered, locally and without fetching. Remote filtering stays the host's job; use hui-search-field when the host wants an event per keystroke.
• hui-date-picker A form-associated text input with a calendar in a popover. Typing an ISO date and picking a day produce the same value, and what is submitted is always ISO whatever the display locale.
• hui-field A light-DOM wrapper that wires a rendered label, description and error to one control. It has no shadow root and no focus of its own, and it re-wires through a MutationObserver so an HTMX swap that adds an error message is picked up automatically.
• hui-listbox A standalone list over option rows the server rendered: a cursor the keys move, and a selection that is single, multiple with Shift ranges, or none. The options’ aria-selected is the selection, so a swap that writes different rows selected is the whole update.
• hui-pagination Renders real <a href> links, so a host drives navigation with hx-get and the control still works without JavaScript. It owns only the page window, never the rows or counts.
• hui-popover The general anchored, non-modal overlay: a trigger slot and a panel that is a native popover in the top layer, so light dismiss and Escape come from the platform. It is the base the dropdown menu, select and combobox are built on.
• hui-qr-code Encodes its value as a QR code and draws it as one SVG path, dark modules on a white tile whatever the theme. A phone camera reads dark on light far more reliably than the reverse, so the code is deliberately not themed.
• hui-radio-group A form-associated radio group. The host renders the items and marks them with role="radio"; the group owns the value, keeps exactly one item in the tab order and moves both focus and selection with the arrow keys.
• hui-search-field A text input with a search icon and a clear control, form-associated so it submits like any other field. It owns no suggestions; a host drives an hx-get from its input event.
• hui-select A listbox in a native popover that submits under one name, exactly as a native <select> would. It combines the overlay layer with ElementInternals, is the base for hui-combobox, and takes a selection="multiple" mode and declared option groups.
• hui-tabs A single tab stop with roving tabindex, arrow movement, Home and End, and the choice of automatic or manual activation. Tabs and panels are light-DOM children the Go host rendered, so HTMX can swap panel content in place. With navigation it becomes a landmark of real links whose current one is the server's aria-current="page".
• hui-theme-toggle An optional enhancement that writes the light or dark class on the document root and remembers the choice in localStorage. It is the only element in the library that touches the root element, so a host that pins the theme server-side simply does not load it.
• hui-toggle-group A segmented control over slotted hui-toggle items, or with spacing a row of separate chips. Single mode holds one value and multiple mode holds several, with the group doing the FormData work as one repeated field.
• hui-tooltip A popover that opens on hover after a delay and, always, on keyboard focus. A plain tooltip labels its trigger; the richer form can be moved into and reached by keyboard.
• hui-tree A tree view over nested items the server rendered: indentation, expand and collapse, the tree’s arrow keys and children the host loads on demand. The items’ aria-expanded and aria-selected are the state, so a swap is the whole update.
• hui-waveform Draws audio levels as a row of mirrored, rounded bars on a canvas: levels the server analysed, an idle processing animation, or the live level of a MediaStream the host hands it. The element never asks for a microphone.

Organisms

• hui-app-shell The frame of an application page: a header, navigation down one side, the main area, an optional aside and a status bar, each scrolling on its own inside the height it is given. It adds a skip control and F6 between the regions and panels, and holds no state.
• hui-carousel A labelled region of slides the host rendered, moved by CSS scroll snapping, with real previous and next controls. Autoplay is off unless asked for.
• hui-command A modal command palette: a search input over a filtered, grouped listbox. Selecting a command emits hui-select and the host decides what it means, because authorisation and side effects are server-owned.
• hui-confirm-action Wraps a server-rendered action and asks for confirmation before letting it through. An accepted click passes on untouched; a declined one is stopped before any host or HTMX handler sees it.
• hui-data-grid A data grid over a JSON child the server writes. In client mode it sorts, filters, pages and selects in the browser; in server mode it sends the same query - one JSON form field - and draws the rows the host swaps back. Cells are formatted by column type or filled from the host’s own templates.
• hui-dialog A modal panel on the native <dialog>, so the top layer, backdrop, inert page behind and Escape come from the platform. One primitive absorbs Dialog, Sheet and Drawer through side, and Alert Dialog through alert.
• hui-dropdown-menu A popover with menu semantics: a single tab stop, arrow and type-ahead navigation, and selection. trigger="contextmenu" absorbs shadcn's Context Menu, opening the same menu on right-click.
• hui-menubar An application menu bar: one tab stop across a row of hui-dropdown-menu children, with left and right moving between menus while one is open.
• hui-navigation-menu A list of real links, optionally with dropdown panels, where the current item is the server’s aria-current and the open panel is the reader’s.
• hui-panel A titled pane: a heading and the host’s actions in a header row, a body that scrolls on its own, and an optional footer. It is a region named by its heading, takes an accent while focus is inside it, and shows a busy bar while its content is on its way.
• hui-path A path bar like the Windows Explorer address bar. Each hui-path-node the server renders is a label, a link back to that level, a menu to switch to a sibling or a popover of the host’s own content, and a chevron can open a node’s children. The trail folds or becomes one menu when it does not fit, and editable lets the reader type a path.
• hui-path-node One node of a hui-path. What it is follows from what the server puts in it - text, a link, a hui-dropdown-menu or a hui-popover - and a menu or popover in slot="children" makes its chevron a button.
• hui-resizable A group of panes with draggable, keyboard-operable separators. The sizes are viewer-owned, reflected as an attribute and announced, never stored.
• hui-sidebar A collapsible application sidebar. The reader owns whether it is collapsed, the server persists and re-renders it, and the element never stores anything.
• hui-table A light-DOM behaviour element wrapped around a <table> the server rendered. It adds a tri-state selection column, sort headers that announce aria-sort, and a sticky header - and never reorders a row.
• hui-toast A fixed live-region container that the host appends messages to, owning only politeness and timing. It auto-dismisses, pausing while hovered or focused, and keeps the newest few.

Charts

• hui-area-chart A curve with its area filled beneath, drawn in SVG from the server's JSON: one series or several, overlapping or stacked, solid or in a gradient. The curves are d3-shape's, as Recharts', so a monotone or natural line matches shadcn's to the control point.
• hui-bar-chart Bars drawn in SVG from data the server writes into a <script type="application/json"> child: one series or several, side by side or stacked, rising or running across. Geometry follows Recharts, which shadcn's charts are drawn with, so widths and gaps match its to the pixel.
• hui-line-chart The area chart's drawing without the fill: one line per series, with optional dots at every point. bare turns it into a sparkline for a table row, which still carries its name and its data table.
• hui-pie-chart A pie, or with inner-radius a donut with its total in the hole, one slice per row. The defaults are Recharts', which shadcn's examples keep: from three o'clock, counter-clockwise, 80 percent of the room. The shadcn reference's savings ring is this element, clockwise from the top.
• hui-radial-chart Radial bars: one ring per row, the first innermost, each sweeping in proportion to its value, optionally over a muted track. A single row is a progress ring.