hp-grid

Drag any hex onto another and it BFS-snaps to the nearest empty axial neighbour. Empty cells are direct drops. Drag is opt-in via the draggable attribute — without it the grid is static and pointerdowns on empty space do nothing.

sm and lg are pointy-top variants of the same shape (lg is ×2 sm). md is the flat-top rotation — sized between sm and lg, sits at a single axial slot, gives a distinct visual "this one's different" against pointy-top neighbours. Spacing in this demo is generous so every cell has clear breathing room; in real use, md and lg cells need 2-3 axial slots of clearance from neighbours since their bbox extends beyond the sm slot footprint.

When to use

Events

hp-grid-move fires immediately on drop (axial coordinates accepted). hp-grid-drop fires after the 90ms snap-back animation completes — use this for "settled" semantics (autosave, server sync). hp-grid-bond / hp-grid-unbond fire when adjacency changes, with the moved + partner atoms in detail. hp-grid-pan fires while the canvas is being panned. With tetherable, hp-grid-tether / hp-grid-untether fire on drag-toggled arcs — covered on the hp-tether page.

Coordinate space

Pointy-top axial coordinates: x = w·(q + r/2), y = w·√3/2·r, where w is the effective cell width (cell − hex-stroke so adjacent strokes share). Move budgets and BFS for occupancy collision use axial Manhattan distance.

• 0.1.0-beta 2026-05-24

  Added

  • <hp-cluster> layout attribute — rosette (default) / honeycomb modes. rosette preserves the canonical 5-hex cross via named slots (centre / top / middle-left / middle-right / bottom). honeycomb accepts N default-slot children: the first child is the centre (axial 0, 0); remaining children fill outward clockwise from north — ring 1 holds 6 positions, ring 2 holds 12 (capped at 19 hexes total in v1). Drag handling stays in <hp-grid> via drag-handle="..."; canonical handle is :first-child for honeycomb mode, [slot='centre'] for rosette. Auto-sizes the host: 2-ring footprint for rosette, 4-ring for honeycomb. Existing rosette usages render unchanged.
  • <hp-grid> pack() public method — runs the FFD bin-pack against the grid's current children. Triggered automatically on first render and on layout attribute changes; consumers can call it manually after dynamic child additions / filters / drags.
  • <hp-grid> recenter() fits content to the viewport. Walks every [q][r] child's per-cell fill mask (data-fill-cells) to compute the visible bbox, picks the zoom that frames the layout with ≤ 1 cell of padding around the outermost hex, then pans the bbox midpoint to viewport centre. Max zoom = 1 (never zooms past native scale). The recenter control button now snaps to "show everything" after any pan / zoom interaction. Replaces the previous reset-to-zoom-1 + pan-to-bbox-midpoint behaviour.
  • <hp-grid> skip-hidden plumbing. pack(), recenter(), and computePanBounds() all skip children carrying the hidden attribute. Filter-controlled visibility (e.g. the showcase components page's search) now plays cleanly with the layout pipeline — hidden clusters don't claim slots, don't drag the fit-bbox off-centre, and don't constrain pan range.
  • <hp-grid layout="spiral"> / layout="rows"> — FFD bin-pack with per-cell occupancy and hex-adjacency gap rule, sharing a common algorithm and differing only in scan order. On first render and on explicit .pack() calls, direct children are sorted by mask size (largest first), then each is placed at the first free position the chosen strategy returns. spiral scans outward from the origin in honeycomb rings — the largest cluster anchors (0, 0), smaller ones nest around it with ≥1-hex gaps, producing a tight roughly-square honeycomb. rows scans row-major with a width cap (10 axial cells half-width) — the layout grows as left-to-right rows that wrap downward, ideal for full-page-width surfaces. Children publish their actual filled hexes via data-fill-cells (space-separated "q,r" pairs); composite elements like <hp-cluster> publish these on slotchange. Children without the attr are treated as a single hex. The gap check uses hex-adjacency (the 6 axial-distance-1 neighbours) — not rectangular 3×3 padding — so non-symmetric cluster shapes leave their empty corners available for neighbours to tuck into. No auto-repack on resize / slotchange — only on explicit .pack() call or layout attribute toggle. Strategy modules live at src/elements/layout/hp-grid/layouts/{spiral,rows}.ts with shared primitives in layouts/index.ts; full unit-test coverage in layouts/{spiral,rows,layout}.test.ts (20+ tests covering hex-adjacency rejection, rect-diagonal acceptance, the layout's compactness bound, the components-page 12-cluster snapshot, and the row-wrap behaviour).
  • <hp-cluster> per-cell fill mask — both layout="rosette" and layout="honeycomb" now publish their actual filled hexes as data-fill-cells="q,r q,r …" host attribute (rosette: 5 fixed positions; honeycomb: first N entries of the fill-order table, derived from child count on slotchange). Bounding-box mirror attrs data-axial-q-min / q-max / r-min / r-max retained alongside for cheap consumers that only care about overall footprint dimensions. Consumed by <hp-grid layout="spiral"> / layout="rows"> for the tight bin-pack — empty bbox corners of non-symmetric cluster shapes (e.g. honeycomb with only NE ring-2 hexes filled) stay available for neighbour clusters to tuck into.
  • Showcase: /components index page switched to <hp-grid layout="rows"> — drops the hand-tuned per-category POSITIONS map; adding or removing categories in sitemap.ts now auto-reflows the cluster grid with a 1-cell gap between every cluster.
  • Showcase: /components index page — full-page-width <hp-grid draggable> filling the main column. Each category renders one <hp-cluster layout="honeycomb" drag-handle=":first-child"> with a centre anchor cell (<hp-cell variant="anchor" filled>) for the category label and one <a>-wrapped action cell per component. Web Awesome-style centred header (title + tagline + filter input), filter input live-filters cells by name substring, clusters whose entire ring filters out auto-hide, and a 300ms debounce kicks off a repack so the layout reflows around just the visible clusters. Sitemap's Components branch gains /components as the branch path so the sidebar heading is itself clickable.

  Changed

  • <hp-cluster> host pointer-events. Host is now pointer-events: none; ::slotted(*) re-enables pointer-events: auto. The cluster's rectangular bbox no longer intercepts pointerdowns through its empty corners — pan drags on the surrounding <hp-grid> reach the host correctly, and at the page bottom-right the cluster bbox no longer overlaps hp-grid's zoom / recenter controls. Only the actual hex cells catch clicks; the drag-handle child is still interactive because the ::slotted rule re-enables pointer-events on every positioned hex.
  • <hp-grid> drag-handle gating. Resolution switched from event.target.closest(selector) to target.querySelector(selector). The closest()-from-event-target approach matched :first-child ancestors transitively — e.g. inside <a><hp-cell></hp-cell></a>, the hp-cell is its <a> parent's first child, so closest() returned it and the drag-handle gate passed even when the click was outside the cluster's actual centre handle. querySelector resolves to the cluster's first matching descendant in DOM order (the actual centre), and the gate checks whether the pointerdown landed on it or one of its descendants.
  • <hp-grid> pan range swaps when content overflows the viewport. Previously, when the layout was bigger than the visible area, the pan-bounds rectangle collapsed to its midpoint — the user could centre the content but couldn't pan to see the overflow. Now, when minX > maxX (or minY > maxY), the two values swap so the legal range covers "child's left edge at viewport's left" through "child's right edge at viewport's right".

  Fixed

  • <hp-grid> recenter no longer clips content larger than the viewport. The previous algorithm reset zoom to 1 and panned to the bbox midpoint — fine if content fit at native scale, but layouts taller than the viewport stayed clipped because zoom never adjusted. The new fit-to-content pass zooms out to frame everything inside the viewport with ≤ 1 cell of padding (capped at zoom = 1).
  • <hp-grid> drag-handle resolution false-positive inside anchor wrappers. With drag-handle=":first-child" on a cluster whose centre cell sat inside <a><hp-cell></hp-cell></a>, the previous event.target.closest(":first-child") walk matched the wrapped hp-cell (it's its parent's first child), so clicking an outer link incorrectly initiated a cluster drag instead of navigating. Resolution now uses the cluster's own querySelector and asserts that the pointer landed inside the resolved handle.