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

@heswell/grid-layout

v5.0.0-alpha.1

Published

VUU Layout Components

Readme

GridLayout

GridLayout renders canonical immutable GridSnapshot state through a per-grid GridController. Applications should use GridLayoutProvider and the schema-v2 GridLayoutDocument persistence API. The mutable model, v1 descriptors, and React-element serialization are compatibility implementation details, not persistence authority.

Versioned persistence

Register a typed settings codec and a separate renderer for every persisted component type:

const settingsCodecs = new GridComponentSettingsRegistry();
settingsCodecs.register("price-tile", {
  version: 1,
  isSettings: isPriceTileSettings,
  encode: (settings) => ({ ok: true, value: settings }),
  decode: (value) =>
    isPriceTileSettings(value)
      ? { ok: true, value }
      : {
          ok: false,
          error: {
            code: "INVALID_PRICE_TILE",
            message: "instrument must be a string",
            path: "$.instrument",
          },
        },
});

const componentRenderers = new GridComponentRendererRegistry();
componentRenderers.register(
  "price-tile",
  isPriceTileSettings,
  (settings, componentId) => (
    <PriceTile id={componentId} instrument={settings.instrument} />
  ),
);

<GridLayoutProvider
  componentRenderers={componentRenderers}
  componentSettings={[
    {
      id: "price-tile-17",
      type: "price-tile",
      settings: { instrument: "VOD.L" },
    },
  ]}
  document={savedDocument}
  settingsCodecs={settingsCodecs}
  onDocumentChange={saveDocument}
  onDocumentError={reportDocumentError}
>
  <GridLayout id="workspace-grid" />
</GridLayoutProvider>;

The plain-JSON envelope has kind: "grid-layout" and version: 2. It stores durable layout IDs, item and component-instance IDs, track strings, item metadata (including wire spelling resizeable), placeholders, ordered stacks and selected tabs, plus versioned typed component settings. Revisions, measurements, drag previews, DOM state, React elements, callbacks, controller instances, and listeners are transient and are never written.

The provider subscribes to committed controller transitions. Initial hydration, previews, rollbacks, rejected/no-op commands, and measured-pixel updates write zero documents; an ordinary semantic commit writes once. Decode, migrations, and all renderer resolution complete before a runtime document replaces the active layout. Unknown component types, unsupported versions, malformed references, failed migrations, and renderer failures report path-aware GridLayoutDocumentError values through onDocumentError and leave the active layout unchanged.

onDocumentChange(document, change) receives the immutable document plus its commit revision, transition kind, and removed component-instance IDs. GridLayoutDocumentController exposes the same current document through getSnapshot() and subscribe() for external-store consumers.

New palette entries use a typed ComponentTemplate:

const template = {
  component: {
    settings: { instrument: "VOD.L" },
    type: "price-tile",
    version: 1,
  },
  label: "Price tile",
} satisfies ComponentTemplate;

Nested providers inherit the nearest template-drag session, while retaining their own document callback and settings scope. Use remapGridLayoutDocumentIds with an application allocator when cloning a saved definition; it remaps grid, item, component, stack, placeholder, and nested document references recursively.

Nested grids must cross the same settings boundary: encode the nested GridLayoutDocument as opaque settings for a registered component type, and render it with its own GridLayoutProvider, grid ID, and controller. An outer vuu-layout or shell document likewise stores the GridLayout document as opaque component settings; its schema must not be merged with the GridLayout schema.

Supported ownership surface

  • GridLayout, GridLayoutItem, GridLayoutProvider
  • immutable GridSnapshot contracts and validation
  • GridController and typed commands
  • encodeGridLayoutDocument / decodeGridLayoutDocument
  • settings codec, renderer, and content registries
  • deliberate drag, palette-template, and stack hooks

Prefer useGridSnapshot, useGridController, and typed dispatch over direct model access.

Legacy compatibility and migration

serializedLayout, SerializedGridLayout, GridLayoutDescriptor, layoutFromJson, and mutable useGridModel are deprecated. Existing imports remain temporarily available, while explicitly named adapters are grouped under GridLayoutLegacyCompatibility. The old provider input is read-only: it may hydrate a descriptor-v1 fixture, but subsequent persistence callbacks emit schema-v2 documents only and never update or serialize React props back into the legacy value.

componentToJson and layoutToJSON remain internal legacy UI-template tools; they must not be used for new GridLayout writes. To migrate a consumer:

  1. Give layout items and component instances stable, independently meaningful IDs.
  2. Define typed JSON settings and a versioned codec for each component type.
  3. Register renderers separately from codecs.
  4. Decode old descriptors only at the compatibility boundary.
  5. Save the next committed state as a v2 document and retain old formats only for backward reads.

Deprecated aliases will remain for a compatibility release and may be removed only after external consumers have migrated.