@andrewcyuan/focusgrid 0.1.0 → 0.2.1

package/README.md

@@ -1,7 +1,12 @@
 # Focusgrid
 
-Resizable panes with keyboard navigation. Core owns layout and commands; DOM handles focus and resizing; React renders the computed tree.
+Create tmux-like, resizable-pane layouts. Use the included React bindings (reocmmended) or write your own bindings to the `focusgrid/core` and `focusgrid/dom` packages!
 
+You can put any react component in the panes using the `renderPane` prop and support all basic layout actions: resize, split, delete, swap, move focus.
+
+The react bindings are also dependent on [shortcut-engine](https://www.npmjs.com/package/@andrewcyuan/shortcut-engine) for out-of-the-box keyboard support.
+
+**Example usage**
 ```tsx
 import { useState } from "react";
 import { FocusGridDomController } from "@andrewcyuan/focusgrid/dom";
@@ -28,12 +33,39 @@ export function App() {
 }
 ```
 
-Give the grid's parent a height. An optional `keymap` replaces the default bindings, including when empty.
+**Customizing Focusgrid**
+Focusgrid can be easily customized. It can be the surface in which you create your entire webapp. Here are some ways you can customize it.
+
+- Define the grid's width and height. When these change, panes are scaled proportionally (not the left-shrinks-first strategy that `tmux` uses)
+- Replace the keybinds by passing `keymap`
+- Directly hit the API by using controller commands: `splitActive`, `removeActive`, `focusAdjacent`, `swapAdjacent`, and `resizeActive`. `focus(paneId)` only syncs active-pane state; `focusAdjacent(direction)` also requests DOM focus.
+- Read layout with `getLayout()`/`useControllerLayout(controller)` (React version). You can also directly mutate the layout, although using the API is probably easier and safer.
+- To write your own frontend framework binding, use `getPane`, `getContainerSize`, and `getSplitSizes` for specific queries, and `subscribe` for changes.
+
+
+**Styling**
 
-Default shortcuts: Ctrl+B, then `%` / `"` to split, `x` to close, arrows to focus, Shift+arrows to swap, or H/J/K/L to resize. The [playground](../../apps/playground/src/keymap.ts) uses its own tmux bindings.
+The optional `@andrewcyuan/focusgrid/react/styles.css` stylesheet uses zero-specificity `:where(...)` selectors. Ordinary class selectors override its defaults regardless of stylesheet order, including active, hover, and focus-visible states; no extra parent selector or `!important` is needed.
 
-Use controller commands: `splitActive`, `removeActive`, `focusAdjacent`, `swapAdjacent`, and `resizeActive`. `focus(paneId)` only syncs active-pane state; `focusAdjacent(direction)` also requests DOM focus. Apps own editor focus restoration and window activation.
+Set these inherited variables on your grid or an ancestor to customize the default colors:
+
+| Variable | Default | Applies to |
+| --- | --- | --- |
+| `--focusgrid-focus-color` | `#4d8dff` | Active pane outline |
+| `--focusgrid-handle-idle-color` | `transparent` | Idle resize handle |
+| `--focusgrid-handle-color` | `rgb(77 141 255 / 35%)` | Hovered or focus-visible resize handle |
+
+```css
+.myGrid {
+  --focusgrid-handle-idle-color: #555;
+  --focusgrid-handle-color: #aaa;
+}
+
+.FocusgridPaneView { outline: none; }
+.FocusgridResizeHandle { background: #555; }
+.FocusgridResizeHandle:hover { background: #aaa; }
+```
 
-Read layout with `getLayout()` or React's `useControllerLayout(controller)`; treat it as read-only. Use `getPane`, `getContainerSize`, and `getSplitSizes` for specific queries, and `subscribe` for changes.
+Pane and handle positions and dimensions still come from inline styles computed by the layout controller; the zero-specificity defaults do not change that geometry.
 
-Without React, construct `FocusGridController(props, domController)` from `/core` and attach your renderer with `mountFocusGrid(root, controller, domController)` from `/dom`; it returns cleanup. Core requires only `domController.focus(paneId): boolean`.
+Made by [Andrew Yuan](https://andrewcyuan.com)

package/dist/dom/index.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("@andrewcyuan/focusgrid/core");
 //#region dom/src/controller.ts
 /** Attach the renderer root; pane elements are resolved only when focus is requested. */
 var FocusGridDomController = class {

package/dist/dom/index.d.cts

@@ -1,164 +1,5 @@
-//#region core/src/layout/types.d.ts
-type PaneId = string;
-type NodeId = string;
-type Orientation = "horizontal" | "vertical";
-declare const cardinalDirections: readonly ["left", "right", "up", "down"];
-type CardinalDirection = (typeof cardinalDirections)[number];
-declare enum PaneCommandCapability {
-  ResizeX = "canResizeX",
-  ResizeY = "canResizeY",
-  Remove = "canRemove",
-  SplitHorizontal = "canSplitHorizontal",
-  SplitVertical = "canSplitVertical",
-  SwapX = "canSwapX",
-  SwapY = "canSwapY",
-  Focus = "canFocus"
-}
-type PaneCommandCapabilityInput = Partial<Record<PaneCommandCapability, boolean>>;
-type PaneNode = {
-  kind: "pane";
-  id: NodeId;
-  paneId: PaneId;
-} & PaneCommandCapabilityInput;
-type SplitNode = {
-  kind: "split";
-  id: NodeId;
-  orientation: Orientation;
-  children: LayoutNode[];
-  sizes: number[];
-  lastFocusedChildId?: NodeId;
-};
-type LayoutNode = PaneNode | SplitNode;
-type Rect = {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-};
-type ComputedPane = {
-  paneId: PaneId;
-  nodeId: NodeId;
-  rect: Rect;
-  active: boolean;
-};
-type ComputedHandle = {
-  id: string;
-  splitId: NodeId;
-  index: number;
-  rect: Rect;
-  direction: Orientation;
-};
-type ComputedNode = {
-  kind: "pane";
-  pane: ComputedPane;
-} | {
-  kind: "split";
-  orientation: Orientation;
-  children: ComputedNode[];
-  handles: ComputedHandle[];
-};
-type ComputedLayout = {
-  root: ComputedNode;
-  rectByNodeId: Map<NodeId, Rect>;
-  panes: ComputedPane[];
-  handles: ComputedHandle[];
-};
-type FocusGridControllerState = {
-  root: LayoutNode;
-  activePaneId: PaneId | null;
-  container: {
-    width: number;
-    height: number;
-  };
-};
-//#endregion
-//#region core/src/controller.d.ts
-interface DomController {
-  focus(paneId: PaneId): boolean;
-}
-type Listener = (next: FocusGridControllerState, previous: FocusGridControllerState) => void;
-type PaneLayoutChangeEvent = {
-  pane: ComputedPane;
-  previousPane: ComputedPane;
-  controller: FocusGridController;
-};
-type PaneCloseEvent = {
-  paneId: PaneId;
-  previousPane: ComputedPane;
-  controller: FocusGridController;
-};
-type PaneEventHandlers = {
-  onPaneLayoutChange?: (event: PaneLayoutChangeEvent) => void;
-  onPaneClose?: (event: PaneCloseEvent) => void;
-};
-type PaneDefaults = PaneCommandCapabilityInput;
-type FocusGridControllerProps = FocusGridControllerState & {
-  paneDefaults?: PaneDefaults;
-  minWidth?: number;
-  minHeight?: number;
-  directionalFocusOverflow?: boolean;
-};
-type SplitPaneOptions = Partial<Omit<PaneNode, "kind" | "id" | "paneId">> & {
-  side: CardinalDirection;
-  newPaneId?: PaneId;
-  newPaneNodeId?: NodeId;
-  splitId?: NodeId;
-  preserveActivePane?: boolean;
-};
-type ResizePaneOptions = {
-  direction: CardinalDirection;
-  deltaPx: number;
-};
-type ResizeHandleOptions = {
-  index: number;
-  deltaPx: number;
-  snapshotSizes?: number[];
-};
-declare class FocusGridController {
-  private readonly domController;
-  readonly minWidth: number;
-  readonly minHeight: number;
-  readonly directionalFocusOverflow: boolean;
-  private currentState;
-  private cachedLayout;
-  private readonly paneDefaults;
-  private readonly listeners;
-  constructor({
-    paneDefaults,
-    minWidth,
-    minHeight,
-    directionalFocusOverflow,
-    ...state
-  }: FocusGridControllerProps, domController: DomController);
-  /** Computed render data; stable until the next committed change. */
-  getLayout(): ComputedLayout;
-  getPane(paneId: PaneId): PaneNode | null;
-  getContainerSize(): {
-    width: number;
-    height: number;
-  };
-  getSplitSizes(splitId: NodeId): number[] | null;
-  splitActive(side: CardinalDirection): PaneId | null;
-  removeActive(): boolean;
-  focusAdjacent(direction: CardinalDirection): boolean;
-  swapAdjacent(direction: CardinalDirection): boolean;
-  resizeActive(direction: CardinalDirection, deltaPx: number): boolean;
-  split(paneNodeId: NodeId, props: SplitPaneOptions): PaneId | null;
-  remove(paneId: PaneId): boolean;
-  swap(firstPaneId: PaneId, secondPaneId: PaneId): boolean;
-  resize(paneId: PaneId, props: ResizePaneOptions): boolean;
-  resizeHandle(splitId: NodeId, props: ResizeHandleOptions): boolean;
-  focus(paneId: PaneId): boolean;
-  updatePane(paneId: PaneId, patch: Partial<Omit<PaneNode, "kind" | "id" | "paneId">>): boolean;
-  setContainerSize(width: number, height: number): boolean;
-  private commit;
-  subscribePaneEvents({
-    onPaneLayoutChange,
-    onPaneClose
-  }: PaneEventHandlers): () => void;
-  subscribe(listener: Listener): () => void;
-}
-//#endregion
+import { DomController, FocusGridController, PaneId } from "@andrewcyuan/focusgrid/core";
+
 //#region dom/src/controller.d.ts
 /** Attach the renderer root; pane elements are resolved only when focus is requested. */
 declare class FocusGridDomController implements DomController {

package/dist/dom/index.d.ts

@@ -1,164 +1,5 @@
-//#region core/src/layout/types.d.ts
-type PaneId = string;
-type NodeId = string;
-type Orientation = "horizontal" | "vertical";
-declare const cardinalDirections: readonly ["left", "right", "up", "down"];
-type CardinalDirection = (typeof cardinalDirections)[number];
-declare enum PaneCommandCapability {
-  ResizeX = "canResizeX",
-  ResizeY = "canResizeY",
-  Remove = "canRemove",
-  SplitHorizontal = "canSplitHorizontal",
-  SplitVertical = "canSplitVertical",
-  SwapX = "canSwapX",
-  SwapY = "canSwapY",
-  Focus = "canFocus"
-}
-type PaneCommandCapabilityInput = Partial<Record<PaneCommandCapability, boolean>>;
-type PaneNode = {
-  kind: "pane";
-  id: NodeId;
-  paneId: PaneId;
-} & PaneCommandCapabilityInput;
-type SplitNode = {
-  kind: "split";
-  id: NodeId;
-  orientation: Orientation;
-  children: LayoutNode[];
-  sizes: number[];
-  lastFocusedChildId?: NodeId;
-};
-type LayoutNode = PaneNode | SplitNode;
-type Rect = {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-};
-type ComputedPane = {
-  paneId: PaneId;
-  nodeId: NodeId;
-  rect: Rect;
-  active: boolean;
-};
-type ComputedHandle = {
-  id: string;
-  splitId: NodeId;
-  index: number;
-  rect: Rect;
-  direction: Orientation;
-};
-type ComputedNode = {
-  kind: "pane";
-  pane: ComputedPane;
-} | {
-  kind: "split";
-  orientation: Orientation;
-  children: ComputedNode[];
-  handles: ComputedHandle[];
-};
-type ComputedLayout = {
-  root: ComputedNode;
-  rectByNodeId: Map<NodeId, Rect>;
-  panes: ComputedPane[];
-  handles: ComputedHandle[];
-};
-type FocusGridControllerState = {
-  root: LayoutNode;
-  activePaneId: PaneId | null;
-  container: {
-    width: number;
-    height: number;
-  };
-};
-//#endregion
-//#region core/src/controller.d.ts
-interface DomController {
-  focus(paneId: PaneId): boolean;
-}
-type Listener = (next: FocusGridControllerState, previous: FocusGridControllerState) => void;
-type PaneLayoutChangeEvent = {
-  pane: ComputedPane;
-  previousPane: ComputedPane;
-  controller: FocusGridController;
-};
-type PaneCloseEvent = {
-  paneId: PaneId;
-  previousPane: ComputedPane;
-  controller: FocusGridController;
-};
-type PaneEventHandlers = {
-  onPaneLayoutChange?: (event: PaneLayoutChangeEvent) => void;
-  onPaneClose?: (event: PaneCloseEvent) => void;
-};
-type PaneDefaults = PaneCommandCapabilityInput;
-type FocusGridControllerProps = FocusGridControllerState & {
-  paneDefaults?: PaneDefaults;
-  minWidth?: number;
-  minHeight?: number;
-  directionalFocusOverflow?: boolean;
-};
-type SplitPaneOptions = Partial<Omit<PaneNode, "kind" | "id" | "paneId">> & {
-  side: CardinalDirection;
-  newPaneId?: PaneId;
-  newPaneNodeId?: NodeId;
-  splitId?: NodeId;
-  preserveActivePane?: boolean;
-};
-type ResizePaneOptions = {
-  direction: CardinalDirection;
-  deltaPx: number;
-};
-type ResizeHandleOptions = {
-  index: number;
-  deltaPx: number;
-  snapshotSizes?: number[];
-};
-declare class FocusGridController {
-  private readonly domController;
-  readonly minWidth: number;
-  readonly minHeight: number;
-  readonly directionalFocusOverflow: boolean;
-  private currentState;
-  private cachedLayout;
-  private readonly paneDefaults;
-  private readonly listeners;
-  constructor({
-    paneDefaults,
-    minWidth,
-    minHeight,
-    directionalFocusOverflow,
-    ...state
-  }: FocusGridControllerProps, domController: DomController);
-  /** Computed render data; stable until the next committed change. */
-  getLayout(): ComputedLayout;
-  getPane(paneId: PaneId): PaneNode | null;
-  getContainerSize(): {
-    width: number;
-    height: number;
-  };
-  getSplitSizes(splitId: NodeId): number[] | null;
-  splitActive(side: CardinalDirection): PaneId | null;
-  removeActive(): boolean;
-  focusAdjacent(direction: CardinalDirection): boolean;
-  swapAdjacent(direction: CardinalDirection): boolean;
-  resizeActive(direction: CardinalDirection, deltaPx: number): boolean;
-  split(paneNodeId: NodeId, props: SplitPaneOptions): PaneId | null;
-  remove(paneId: PaneId): boolean;
-  swap(firstPaneId: PaneId, secondPaneId: PaneId): boolean;
-  resize(paneId: PaneId, props: ResizePaneOptions): boolean;
-  resizeHandle(splitId: NodeId, props: ResizeHandleOptions): boolean;
-  focus(paneId: PaneId): boolean;
-  updatePane(paneId: PaneId, patch: Partial<Omit<PaneNode, "kind" | "id" | "paneId">>): boolean;
-  setContainerSize(width: number, height: number): boolean;
-  private commit;
-  subscribePaneEvents({
-    onPaneLayoutChange,
-    onPaneClose
-  }: PaneEventHandlers): () => void;
-  subscribe(listener: Listener): () => void;
-}
-//#endregion
+import { DomController, FocusGridController, PaneId } from "@andrewcyuan/focusgrid/core";
+
 //#region dom/src/controller.d.ts
 /** Attach the renderer root; pane elements are resolved only when focus is requested. */
 declare class FocusGridDomController implements DomController {

package/dist/dom/index.js

@@ -1,3 +1,4 @@
+import "@andrewcyuan/focusgrid/core";
 //#region dom/src/controller.ts
 /** Attach the renderer root; pane elements are resolved only when focus is requested. */
 var FocusGridDomController = class {