@n-uf/hypr-tiling 26.7.0

package/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+All notable changes to `@n-uf/hypr-tiling` are documented here.
+
+This package uses calendar-aligned versioning (`YY.M.R`), which cannot signal a
+SemVer "major" bump. **Read the per-release notes below for breaking changes** —
+the version number alone does not flag them.
+
+## 26.7.0 — initial public release
+
+First published release of `@n-uf/hypr-tiling`, a dynamic tiling layout engine
+for React. This entry is the baseline: earlier working versions were never
+published, so the changelog tracks the package from this release forward.
+
+### Entry points
+
+The package exposes three import paths through `package.json#exports`
+(`"sideEffects": false`):
+
+- **`@n-uf/hypr-tiling`** (`.`) — the **public API**. A small, hand-authored
+  facade of explicit named exports (never `export *`); this is the ONLY
+  consumer surface and the one tracked for compatibility.
+- **`@n-uf/hypr-tiling/devtools`** — opt-in observability overlays, on their own
+  entry so a renderer-only consumer never bundles them.
+- **`@n-uf/hypr-tiling/engine`** — a `@beta` escape hatch that re-exports the
+  engine-grade, framework-free internals (layout-tree reducers, low-level tree
+  walkers, keymap and drag-adjacent math) for power users driving the tree
+  headlessly. **No stability guarantees** — it may change or disappear in any
+  release and is kept off the consumer documentation site.
+
+### Public API surface (`.`)
+
+- **`TilingRenderer`** — the layout renderer: controlled layout tree, focus and
+  maximize, drag-and-drop with FLIP animation and self-healing recovery,
+  multi-select grouping (Alt/Opt+G), pane switching, and per-tile accents. A
+  custom `renderTile` receives the clean, debug-free `TilingRenderTileProps`
+  contract (tile payload + pane state flags + interaction handlers) — the
+  drag/drop observability + debug fields are OFF this surface (they route through
+  the internal default pane and `/devtools`).
+- **Custom-pane helper primitives** — optional, unstyled conveniences layered
+  over `renderTile` that encode the pane wiring rules so a custom pane can't get
+  them wrong: `TilingPaneRoot` (`data-leaf-id` root + focus/hover handlers),
+  `TilingDragHandle` (drag pickup + `touch-action: none` + Alt/Opt group toggle),
+  `TilingPaneAction` (action button that stops propagation), and `TilingPaneBody`
+  (renders children only in `render-content` mode). The raw `renderTile` args
+  stay the full escape hatch.
+- **Theming** — `TilingThemeProvider` / `TilingTheme` for token-driven styling.
+- **Layout inspection & mutation** — the layout is a recursive tree of
+  `TilingLayoutNode` (`TilingLeafNode` / `TilingSplitNode` / `TilingGroupNode`).
+  Read it with `queryTilingLayout` (a `TilingLayoutQuery` view: leaf ids, splits,
+  groups, tile order, directional-neighbor lookup). Mutate it declaratively via
+  `onLayoutChange` or imperatively by dispatching a typed `TilingCommand` through
+  the renderer's `TilingCommandHandle` (gated by `isCommandEnabled`). The raw pure
+  reducers (`groupLeaves`, `insertLeafAdjacent`, `updateSplitRatio`, …) are NOT on
+  the public entry — they live on `@n-uf/hypr-tiling/engine`.
+- **Interaction & presets** — `TilingInteractionCapabilities`,
+  `resolveInteractionCapabilities`, `TILING_DASHBOARD_PRESET`, and the theming
+  registry constants. Every interaction is **on by default** and narrowed by
+  passing a partial `interaction` prop; the single opt-IN exception is the group
+  tab strip's dev/demo "show pane body" checkbox
+  (`paneSwitching.showContentToggle`, default `false`), so a consumer that
+  renders its own pane content never surfaces an end-user control that blanks it
+  and panes paint content at rest with no wiring.
+
+### Consumer theming & chrome contract
+
+Every painted pixel is reachable from a consumer-authored `TilingTheme` or
+routed through the consumer `renderTile` — no renderer state paints chrome the
+consumer didn't choose. Defaults stay zero-config (built-in themes,
+`DefaultTilingTile`, the built-in group strip). Concretely:
+
+- **`theme` prop on `TilingRendererProps`** — a full consumer-authored
+  `TilingTheme`; takes precedence over `themeId`. `TilingTheme.id` is open
+  (`TilingThemeId | (string & {})`) so a consumer mints its own theme id;
+  `TILING_THEME_REGISTRY` stays keyed by the closed built-in union, and the
+  built-in theme switcher (`onThemeChange`, typed `TilingThemeId`) remains
+  built-ins-only — consumers running a custom theme simply don't wire it.
+- **`grouping` capability object form** — `boolean | TilingGroupingCapability`
+  (`{ enable?, showGroupTabStrip? }`; bare boolean = `{ enable }`,
+  `showGroupTabStrip` default `true`). `showGroupTabStrip: false` suppresses
+  the built-in per-group tab strip so a consumer paints its own group chrome;
+  keyboard group commands stay live. `paneSwitching.showTabStrip` governs the
+  TOP-LEVEL tab strip only.
+- **`surface` discriminator on `TilingRenderTileProps`**
+  (`TilingRenderSurface`: `"pane" | "drag-ghost" | "drag-cancel"`). The two
+  drag surfaces carry the REAL resolved capability display flags (no mid-drag
+  silhouette pop) with inert no-op handlers; a custom pane that wants different
+  drag chrome branches on `surface`.
+- **`group` context on `TilingRenderTileProps`** —
+  `TilingRenderTileGroupContext | null`, populated for a tabbed group's ACTIVE
+  member: the `TilingGroupMemberView` member list (leaf/tile ids, resolved
+  tile, 1-based `memberNumber`, `isActive`) plus `activateMember` /
+  `removeMember` / `ungroup` callbacks that route through the same internal
+  command router as the built-in strip and the keyboard layer. `null` for
+  loose leaves and drag surfaces.
+- **Cancel fly-back fidelity** — the drag-cancel overlay renders through the
+  consumer `renderTile` (`surface: "drag-cancel"`) when one is supplied, so a
+  custom skin keeps its own chrome for the whole cancel glide; the built-in
+  shell remains the no-`renderTile` fallback.
+- **Hand-authored facade** — 104 public API items. Engine-grade internals are
+  physically layered under `engine/` and reached only through the `.` facade (via
+  `react/`) or the explicit `./engine` entry. An
+  [API Extractor](https://api-extractor.com/) report per entry is checked in
+  (`etc/hypr-tiling{,.devtools,.engine}.api.md`); `pnpm api:check` fails CI if the
+  `.` surface drifts or an unexported type leaks onto it, and an architectural
+  guardrail keeps the `engine/` layer framework-free and blocks deep consumer
+  imports.
+
+### Developer / observability tooling — `@n-uf/hypr-tiling/devtools`
+
+The observability panel, its seed defaults, and the whole debug/observability
+input surface live on a separate `/devtools` subpath, so a renderer-only consumer
+never pulls them into its bundle:
+
+```ts
+import {
+  TilingObservabilityPanel,
+  ANIMATION_CONTROL_DEFAULTS,
+  TilingRenderer, // the observability-instrumented view of the same renderer
+} from "@n-uf/hypr-tiling/devtools";
+```
+
+The renderer's observability inputs — overlay colors
+(`observabilityColors` / `observabilityColorEnables`), the hit-zone / drop-intent
+debug flags, and the `onDropIntentChange` / `onLiveHitLogChange` /
+`onProjectedOverlayCountChange` telemetry hooks — are collected into
+`TilingRendererObservabilityProps` and kept OFF the consumer `TilingRendererProps`
+contract. `/devtools` exports both those props and the observability-typed view of
+the SAME `TilingRenderer` component that accepts them, plus the debug/observability
+snapshot **types** they reference (`TilingDropIntentDebugState`,
+`TilingLiveHitLogState`, `TilingObservabilityColorConfig`, `TilingPaneHitZone*`,
+…). The consumer `.` surface carries none of them.
+
+### Documentation
+
+Guides and a generated API reference are published at
+[hypr-tiling.n-uf.com/docs](https://hypr-tiling.n-uf.com/docs). Every public symbol
+carries TSDoc (coverage enforced in CI), so summaries and examples surface in
+editor hover-docs.
+
+### Tailwind requirement
+
+The package ships no CSS — it emits Tailwind utility classes. Add
+`@n-uf/hypr-tiling` to your Tailwind `content` glob or the renderer is unstyled.
+See the README "Tailwind content requirement" section.

package/README.md

@@ -0,0 +1,242 @@
+<h1 align="center">
+  <img src="../../assets/hypr-tiling-logo-transparent.png" alt="hypr-tiling" width="48" align="center" />
+  @n-uf/hypr-tiling
+</h1>
+<p align="center">Dynamic tiling for React</p>
+
+Dynamic tiling for React: a recursive split-tree renderer for drag/drop,
+resizable, keyboard-controlled panes — inspired by
+[Hyprland](https://hypr.land).
+
+Reach for it when users need to rearrange dense, multi-panel screens at runtime
+— IDE-like tools, trading and operator consoles, analytics dashboards — while
+your app keeps strict, controlled ownership of the layout state.
+
+## Quick links
+
+- Documentation homepage: <https://hypr-tiling.n-uf.com/>
+- Interactive showcase route: <https://hypr-tiling.n-uf.com/showcase>
+- API report index: [`etc/hypr-tiling.api.md`](etc/hypr-tiling.api.md)
+- Repository issues: <https://github.com/n-uf/hypr-tiling/issues>
+
+## Install
+
+```bash
+pnpm add @n-uf/hypr-tiling react react-dom
+```
+
+```bash
+npm install @n-uf/hypr-tiling react react-dom
+```
+
+```bash
+yarn add @n-uf/hypr-tiling react react-dom
+```
+
+`react` and `react-dom` are peer dependencies (version `^19`).
+
+## Compatibility
+
+- React: `^19`
+- React DOM: `^19`
+- Tailwind scanning: required (`content` glob or v4 `@source`)
+- Runtime: browser DOM (React renderer package)
+
+### Tailwind content requirement
+
+This package **ships no CSS**. The renderer styles itself by emitting Tailwind
+utility class strings (via `clsx` + `tailwind-merge`) — those classes only
+resolve to real styles if Tailwind scans this package's built output and
+generates the matching CSS. If you do not register the package in your Tailwind
+`content` glob, the component renders **completely unstyled**.
+
+Add `@n-uf/hypr-tiling` to your Tailwind `content` configuration:
+
+```js
+// tailwind.config.js
+export default {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/@n-uf/hypr-tiling/dist/**/*.{js,mjs}",
+  ],
+  // ...
+};
+```
+
+For Tailwind v4 (CSS-first config), declare the same path as a source in your
+stylesheet:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@n-uf/hypr-tiling/dist/**/*.{js,mjs}";
+```
+
+## Quick start
+
+The renderer is a **controlled component**: you own the layout tree in state and
+apply every change it reports through `onLayoutChange`. Nothing about the layout
+is hidden inside the component — the tree is yours to persist, diff, and restore.
+
+```tsx
+import {
+  TilingRenderer,
+  DEFAULT_TILING_LAYOUT_CONFIG,
+  type TilingLayoutNode,
+  type TilingTile,
+} from "@n-uf/hypr-tiling";
+import { useState } from "react";
+
+const tiles: TilingTile[] = [
+  { id: "a", title: "editor", content: <Editor /> },
+  { id: "b", title: "preview", content: <Preview /> },
+];
+
+const initialLayout: TilingLayoutNode = {
+  kind: "split",
+  id: "root",
+  axis: "vertical",
+  ratio: 0.5,
+  first: { kind: "leaf", id: "l", tileId: "a" },
+  second: { kind: "leaf", id: "r", tileId: "b" },
+};
+
+export function Workspace(): JSX.Element {
+  const [layout, setLayout] = useState<TilingLayoutNode>(initialLayout);
+  return (
+    <TilingRenderer
+      layout={layout}
+      tiles={tiles}
+      config={DEFAULT_TILING_LAYOUT_CONFIG}
+      onLayoutChange={setLayout}
+    />
+  );
+}
+```
+
+## Programmatic layout API
+
+Because you own the layout tree, you can mutate it from your own code — not just
+through drag/keyboard interaction. The package exports a set of pure layout
+reducers (each takes a layout node and returns a new one, never mutating in
+place) as supported public API. Use these to script layout changes, build custom
+commands, or restore persisted arrangements:
+
+| Reducer | Purpose |
+| --- | --- |
+| `findLeafById` | Locate a leaf node within the tree by its id. |
+| `insertLeafAdjacent` | Insert a new leaf next to an existing one along an axis. |
+| `moveLeafToRoot` | Detach a leaf and re-seat it against the layout root. |
+| `moveLeafToSplitContainer` | Move a leaf into a target split container. |
+| `swapLeafTiles` | Exchange the tiles occupying two leaves. |
+| `removeLeafTile` | Remove a leaf and collapse its parent split. |
+| `updateSplitRatio` | Set the ratio of a binary split. |
+| `toggleSplitAxis` | Flip a split between horizontal and vertical. |
+| `setLeafSizing` | Set a leaf's sizing mode (static pixel extent vs. flexible). |
+| `groupLeaves` | Collapse several leaves into one stacked/tabbed group. |
+| `ungroupNode` | Expand a group back into individual leaves. |
+| `collectGroups` | Enumerate the group nodes in a layout. |
+| `isStructurallyValidLayout` | Validate a layout tree's structural invariants. |
+
+All reducers are re-exported from the package root:
+
+```ts
+import {
+  findLeafById,
+  insertLeafAdjacent,
+  swapLeafTiles,
+  isStructurallyValidLayout,
+} from "@n-uf/hypr-tiling";
+```
+
+Other layout-tree helpers are exported for advanced/internal use, but the
+reducers above are the stable, documented surface for application code.
+
+For complete generated API signatures, see
+[`etc/hypr-tiling.api.md`](etc/hypr-tiling.api.md).
+
+## Features
+
+- **Drag/drop rearrange** — Hyprland-style live drag; the move commits on
+  release, resolving to swap, edge-insert, split-container-insert, or
+  group-merge.
+- **Resizable split dividers** — drag dividers, or pin a pane to a measured pixel
+  extent (static) versus ratio-distributed (flexible).
+- **Group / stack tabs** — collapse several leaves into one slot as a stacked
+  group with a tab strip; only the active member renders.
+- **Maximize** — promote any pane to fill the viewport and restore it back.
+- **Keyboard-driven focus** — directional focus, a pane switcher
+  (cycle / jump / overlay), keyboard move-mode, and master/group commands behind
+  a remappable keymap.
+- **Theming engine** — two built-in themes (`neon-terminal`, `clean-flat`),
+  eight accent hues, and live theme switching with no remount.
+- **Self-healing drag recovery** — a frame-deadline backstop, an idle watchdog,
+  transient-style teardown, and a `visibilitychange` reconcile so a drag never
+  strands the tree mid-transition.
+
+## Use cases
+
+hypr-tiling is built for screens where users live across multiple panels and
+rearrange them as the work demands:
+
+- **Dynamic / content sites** — real, SEO-indexable content arranged as tiles
+  instead of a single scroll, with docs living in prerendered panes.
+- **Dashboards** — analytics, metrics, and monitoring consoles where several
+  resizable panes share one screen.
+- **IDE-like tools** — editor, preview, and terminal workspaces a user splits,
+  stacks, and rearranges at runtime.
+- **Trading & operator consoles** — dense, keyboard-driven control surfaces that
+  pack many live panels into a fixed viewport.
+- **Admin & data apps** — table, detail, and activity panes side by side, resized
+  to fit the task at hand.
+- **Observability & log explorers** — query, results, and trace panes rearranged
+  on the fly while chasing an incident.
+- **Web terminals & consoles** — browser-based shells, multiplexed sessions, and
+  live log streams split and resized Hyprland-style — the tiling homage made
+  literal, in the terminal.
+- **Realtime trading terminals** — Bloomberg-style desks: live charts, order
+  books, watchlists, and order entry packed into dense panes that stream and
+  rearrange in realtime.
+
+## Roadmap
+
+Where hypr-tiling is headed. These are **planned** directions, not shipped
+features today — the library currently renders to the DOM and ships a React
+adapter only. The items below describe where the project is going:
+
+- **Framework-agnostic core** — a dependency-free vanilla TypeScript core so the
+  tiling engine runs without any framework: the layout tree, the drag/FLIP state
+  machine, and the self-healing recovery logic decoupled from React, ready to
+  drive any view layer.
+- **First-class adapters for every major framework** — React ships today;
+  planned official adapters for Vue, Svelte, Solid, Angular, and standard Web
+  Components, each a thin binding over the same vanilla core so behavior stays
+  identical across frameworks.
+- **Canvas rendering backend** — an optional canvas / GPU-accelerated render path
+  for very high pane counts and animation-heavy scenes where DOM reflow is the
+  bottleneck; the semantic DOM path stays the default and canvas is opt-in for
+  density.
+- **Rust + WebAssembly core** — porting the hot layout, drag, and geometry math
+  to a Rust → WebAssembly core for deterministic, high-frame-rate behavior,
+  unlocking more window-manager-like UX: virtual workspaces, snap zones,
+  persistent session layouts, fully keyboard-driven tiling, and
+  per-monitor-style multi-viewport arrangements.
+
+## Contributing
+
+hypr-tiling is built in the open and welcomes collaboration — framework
+adapters, rendering backends, bug reports, and ideas from the roadmap above are
+all welcome. To get involved, email
+[metelin@gmail.com](mailto:metelin@gmail.com).
+
+## Links
+
+- Homepage: <https://hypr-tiling.n-uf.com>
+- Showcase: <https://hypr-tiling.n-uf.com/showcase>
+- Repository: <https://github.com/n-uf/hypr-tiling>
+- Issues: <https://github.com/n-uf/hypr-tiling/issues>
+
+## License
+
+Source-available under
+[PolyForm Perimeter 1.0.1](https://polyformproject.org/licenses/perimeter/1.0.1)
+— business use allowed, but no competing product built from this software.