npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@sapporta/grid

v0.10.1

Published

Sapporta grid runtime, React grid components, column presets, and lookup primitives.

Readme

@sapporta/grid

@sapporta/grid provides the Sapporta grid runtime, React grid components, column presets, and lookup cache primitives. The package uses @sapporta/ui for generic UI primitives. Application routes and server contracts remain in the host application.

Runtime

GridRuntime contains grid-wide schema, interaction, events, registered levels, and row operations. GridLevelRuntime binds rows, subscriptions, interaction, expansion, writes, and drafts to one GridPath.

Every TreeNode carries a required rowKey. Sapporta uses that key across sorting, filtering, insertion, and removal. makeRowId creates a tagged data row identity from a level path and row key.

import {
  childPath,
  createGridRuntime,
  inMemoryGridDataSource,
  makeRowId,
  type GridSchema,
  type TreeNode,
} from "@sapporta/grid";

const schema = {
  rootLevel: "orders",
  levels: {
    orders: {
      name: "orders",
      rowHeaderColumn: "none",
      columns: [
        {
          id: "status",
          name: "Status",
          renderCell: ({ value }) => String(value ?? ""),
        },
      ],
      options: {},
      childLevels: ["lines"],
    },
    lines: {
      name: "lines",
      rowHeaderColumn: "none",
      columns: [
        {
          id: "quantity",
          name: "Quantity",
          renderCell: ({ value }) => String(value ?? ""),
        },
      ],
      options: {},
      childLevels: [],
    },
  },
} satisfies GridSchema;

const tree = [
  {
    rowKey: "order-42",
    levelName: "orders",
    columns: { status: "open" },
    children: {
      lines: [
        {
          rowKey: "line-1",
          levelName: "lines",
          columns: { quantity: 1 },
        },
      ],
    },
  },
] satisfies TreeNode[];

const localLevel = {
  sortMode: "none",
  filterMode: "none",
  paginationMode: "none",
} as const;

const runtime = createGridRuntime({
  schema,
  dataSource: inMemoryGridDataSource({
    schema,
    tree,
    levels: { orders: localLevel, lines: localLevel },
  }),
});

const root = runtime.root;
const orderId = makeRowId(root.path, "order-42");
root.expand(orderId);

const lines = runtime.level(childPath(root.path, "order-42", "lines"));
const lineId = makeRowId(lines.path, "line-1");
lines.writeCell({ rowId: lineId, colId: "quantity" }, 2);

runtime.registeredLevels() returns every registered level, including retained collapsed levels. runtime.subscribeLevels() reports changes to that set.

Tree levels

A tree level shows rows of one level that refer to each other, such as accounts with a parent_id column. All rows share one header and one set of columns. The hierarchy is shown only in the tree column: each row is indented by its depth, and a row with children has a chevron that expands or collapses it. This is different from childLevels, where an expanded row opens a nested grid of another level with its own header.

A level becomes a tree level when it declares tree. parentKeyField names the field of TreeNode.columns that holds the parent's row key. A null, undefined, or "" value marks a top-level row. withTreeColumn makes a column the tree column: it adds the indentation and the chevron.

import { withTreeColumn, type GridSchema } from "@sapporta/grid";

const schema = {
  rootLevel: "accounts",
  levels: {
    accounts: {
      name: "accounts",
      rowHeaderColumn: "none",
      columns: [
        withTreeColumn({
          id: "name",
          name: "Account",
          renderCell: ({ value }) => String(value ?? ""),
        }),
      ],
      options: {},
      childLevels: [],
      tree: { parentKeyField: "parent_id" },
    },
  },
} satisfies GridSchema;

The source still delivers a flat list, already sorted and filtered. The grid builds the tree from that list, so a sort orders the siblings at every depth. Rows start expanded unless tree.defaultExpanded is false. A row whose parent is not in the list is shown at top level, and a parent loop is cut and reported through onObserverError.

level.tree expands and collapses rows, reads parents and children, and adds a draft child under a row with addChild. The draft's parent-key field is filled in, so committing the draft creates the row under that parent. Collapsing a row moves the cursor out of the hidden rows, and hidden rows leave the row selection. The treeExpansionChanged event reports each expansion change.

addChild fills the parent-key field with the parent's row key, which is a string. When the field holds a typed key, such as a number, set tree.parentKeyValue to read that value from the parent row:

tree: {
  parentKeyField: "parent_id",
  parentKeyValue: (parent) => parent.columns.id,
},

A tree level declares no childLevels. Call validateLevelTree to check a level's tree declaration before you create a runtime.

In a row list with activeRow.keyboard.expansion: "enabled", Right expands a row or moves to its first child, Left collapses a row or moves to its parent, and Space toggles. In a cell grid, Space on the tree column toggles.

A filtered tree must stay connected. The in-memory source keeps each match's ancestors, and by default each match's descendants (treeMatchContext: "ancestors" keeps only the ancestors). A custom source lists ancestors that do not match themselves in LevelSnapshot.treeContextRowKeys. Those rows are marked with data-tree-context and row.tree.context, so they can be styled as context.

State and events

The runtime exposes identity-stable snapshots with matching invalidation subscriptions. runtime.activeRow() returns the current grid-wide active row. runtime.subscribeActiveRow() observes row identity, disappearance, and displayed-value changes.

useGridActiveRow(runtime) adapts that state for a component that owns the provider. Provider descendants can call useGridActiveRow() without an argument.

import {
  GridLevel,
  GridRuntimeProvider,
  rootPath,
  useGridActiveRow,
  type GridRuntime,
} from "@sapporta/grid";

function OrdersGrid({ runtime }: { runtime: GridRuntime }) {
  const activeRow = useGridActiveRow(runtime);

  return (
    <section>
      <GridRuntimeProvider runtime={runtime}>
        <GridLevel path={rootPath(runtime.schema.rootLevel)} />
      </GridRuntimeProvider>
      <output>{String(activeRow?.row.columns.status ?? "")}</output>
    </section>
  );
}

RuntimeArgs.on installs listeners before root-source acquisition. runtime.on(event, listener) installs listeners during the runtime lifetime. Events report discrete commands, outcomes, and defined transitions. rowActivated reports every successful configured row activation. Stored cell and row selection events remain separate from derived selection snapshots.

Advanced composition

@sapporta/grid/advanced provides cursor and controller helpers for custom grid renderers and interaction layers.

import { controllerFor, cursorManagerFor } from "@sapporta/grid/advanced";

const cursors = cursorManagerFor(runtime);
cursors.moveCellCursorTo({
  path: lines.path,
  rowId: lineId,
  colId: "quantity",
});

const controller = controllerFor(runtime, lines.path);
controller.startEdit({ rowId: lineId, colId: "quantity" }, "enter");
controller.cancelEdit();

runtime.dispose();