JSPM

  • Created
  • Published
  • Downloads 2051
  • Score
    100M100P100Q116351F
  • License MIT

A state machine for a WAI-ARIA compliant window splitter

Package Exports

  • @window-splitter/state

Readme

@window-splitter/state

A state machine for a WAI-ARIA compliant window splitter. This package can be used to build your own window splitter for a framework or even vanilla html/js.

If you're using a framework like React, you should use the framework package instead.

Read the full docs

Install

npm install @window-splitter/state
yarn add @window-splitter/state
pnpm add @window-splitter/state

Usage

This is an example of how to use the machine to create a window splitter. This is very simplified and only shows the basics of how to use the state machine. Actually integrating with a framework would look a lot different.

In a vanilla html/js application you would have something like this:

<div id="group">
  <div id="panel-1">Panel-1</div>
  <div id="resizer-1"></div>
  <div id="panel-2">Panel-2</div>
</div>

And then you would have some javascript to setup the state machine and send events to it.

import {
  groupMachine,
  initializePanel,
  initializePanelHandleData,
} from "@window-splitter/state";

// Setup the state machine
const actor = groupMachine({ groupId: "group" });

// Register the panels with the state machine
actor.send({
  type: "registerPanel",
  data: initializePanel({ id: "panel-1" }),
});
actor.send({
  type: "registerPanelHandle",
  data: initializePanelHandleData({ id: "resizer-1", size: "10px" }),
});
actor.send({
  type: "registerPanel",
  data: initializePanel({ id: "panel-2" }),
});

// Set the size of the group, typically measured in the browser after the initial render
actor.send({ type: "setSize", size: { width: 500, height: 200 } });
// The state machine relies on css grid to calculate the initial sizes of the panels
// This next action would be sent after measuring the initial sizes rendered by the browser
actor.send({
  type: "setActualItemsSize",
  childrenSizes: {
    "panel-1": { width: 245, height: 200 },
    "panel-2": { width: 245, height: 200 },
  },
});

// Send some events to drag a handle
actor.send({ type: "dragHandleStart", handleId: "resizer-1" });
actor.send({
  type: "dragHandle",
  handleId: "resizer-1",
  value: dragHandlePayload({ delta: 10 }),
});
actor.send({ type: "dragHandleEnd", handleId: "resizer-1" });

API

groupMachine

The state machine is exported as groupMachine and can be used to create a window splitter.

groupMachine.input

The context of the state machine is an object with the following shape:

  • orientation: The orientation of the group. This can be either "horizontal" or "vertical"
  • groupId: The id of the group
  • initialItems: An array of items to initialize the group with.

Events

For a full list of events and their payloads see the source code.

  • registerPanel: Register a new panel with the state machine
  • registerDynamicPanel: Register a new panel after the initial render
  • unregisterPanel: Unregister a panel from the state machine
  • registerPanelHandle: Register a new panel handle with the state machine
  • unregisterPanelHandle: Unregister a panel handle from the state machine
  • setSize: Set the size of the group after the initial render
  • setActualItemsSize: Set the size of the group items after the initial render
  • setOrientation: Set the orientation of the group
  • dragHandleStart: Start a drag interaction
  • dragHandle: Update the layout according to how the handle moved
  • dragHandleEnd: End a drag interaction
  • collapsePanel: Collapse a panel
  • expandPanel: Expand a panel
  • setPanelPixelSize: Set the size of a panel in pixels

Utilities

  • buildTemplate - Build the grid template from the item values.
  • getCollapsiblePanelForHandleId - Get the handle closest to the target panel.
  • getGroupSize - Get the size of the group in pixels.
  • getPanelWithId - Get a panel with a particular ID.
  • getUnitPercentageValue - Converts a Unit to a percentage of the group size.
  • getUnitPixelValue - Converts a Unit to a pixel value.
  • initializePanel - Initialize a panel for registration with the state machine.
  • InitializePanelHandleData - Initialize a panel handle for registration with the state machine.
  • isPanelData - Check if the provided item is a panel data object.
  • isPanelHandle - Check if the provided item is a panel handle object.
  • parseUnit - Parse a Unit from a string.
  • prepareSnapshot - For usage with restoring a saved layout state