growing-panes 0.2.0

package/dist/index.js

@@ -0,0 +1,373 @@
+// src/core.ts
+var DEFAULT_MAX_VISIBLE = 2;
+function assertPositiveInteger(value, label) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+}
+function assertNonNegativeInteger(value, label) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${label} must be a non-negative integer.`);
+  }
+}
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+function resolveConfig(config) {
+  const paneNames = Object.keys(config.panes);
+  if (paneNames.length === 0) {
+    throw new Error("At least one pane definition is required.");
+  }
+  const maxVisible = config.display?.maxVisible ?? DEFAULT_MAX_VISIBLE;
+  assertPositiveInteger(maxVisible, "display.maxVisible");
+  for (const pane of paneNames) {
+    const definition = config.panes[pane];
+    const paneMaxVisible = definition.display?.maxVisible;
+    if (paneMaxVisible !== void 0) {
+      assertPositiveInteger(
+        paneMaxVisible,
+        `panes.${pane}.display.maxVisible`
+      );
+    }
+    for (const parent of definition.canOpenFrom ?? []) {
+      if (!hasOwn(config.panes, parent)) {
+        throw new Error(
+          `Pane "${pane}" references unknown parent pane "${parent}".`
+        );
+      }
+    }
+  }
+  const initialStack = config.initialStack ?? [];
+  const minimumDepth = config.minimumDepth ?? (initialStack.length === 0 ? 0 : 1);
+  assertNonNegativeInteger(minimumDepth, "minimumDepth");
+  if (minimumDepth > initialStack.length) {
+    throw new Error(
+      "minimumDepth cannot be greater than the initial stack length."
+    );
+  }
+  return {
+    panes: config.panes,
+    initialStack,
+    maxVisible,
+    minimumDepth,
+    selectVisiblePanes: config.selectVisiblePanes
+  };
+}
+function definitionFor(config, pane) {
+  if (!hasOwn(config.panes, pane)) {
+    throw new Error(`Unknown pane "${pane}".`);
+  }
+  return config.panes[pane];
+}
+function generatedKey(pane, seed, stack) {
+  const base = `${pane}:${seed}`;
+  let key = base;
+  let suffix = 2;
+  while (stack.some((entry) => entry.key === key)) {
+    key = `${base}:${suffix}`;
+    suffix += 1;
+  }
+  return key;
+}
+function entryFromTarget(target, depth, seed, stack) {
+  const key = target.key ?? generatedKey(target.pane, seed, stack);
+  if (key.length === 0) {
+    throw new Error("Pane keys cannot be empty.");
+  }
+  if (stack.some((entry) => entry.key === key)) {
+    throw new Error(`Duplicate pane key "${key}".`);
+  }
+  return Object.freeze({
+    key,
+    pane: target.pane,
+    params: "params" in target ? target.params : void 0,
+    data: "data" in target ? target.data : void 0,
+    depth
+  });
+}
+function assertCanOpen(config, pane, parent) {
+  const definition = definitionFor(config, pane);
+  const allowedParents = definition.canOpenFrom;
+  if (allowedParents === void 0) {
+    return;
+  }
+  if (parent === void 0 || !allowedParents.includes(parent.pane)) {
+    const from = parent === void 0 ? "an empty stack" : `"${parent.pane}"`;
+    throw new Error(`Pane "${pane}" cannot open from ${from}.`);
+  }
+}
+function buildStack(config, targets, seedOffset) {
+  const stack = [];
+  targets.forEach((target, index) => {
+    definitionFor(config, target.pane);
+    if (index > 0) {
+      assertCanOpen(config, target.pane, stack[index - 1]);
+    }
+    stack.push(
+      entryFromTarget(target, index, seedOffset + index + 1, stack)
+    );
+  });
+  return Object.freeze(stack);
+}
+function freezeState(stack, revision) {
+  return Object.freeze({
+    stack: Object.freeze([...stack]),
+    revision
+  });
+}
+function validateVisiblePanes(stack, selected) {
+  const indexes = selected.map(
+    (selectedEntry) => stack.findIndex((entry) => entry.key === selectedEntry.key)
+  );
+  if (indexes.some((index) => index === -1)) {
+    throw new Error("selectVisiblePanes returned an entry outside the stack.");
+  }
+  if (new Set(indexes).size !== indexes.length) {
+    throw new Error("selectVisiblePanes returned duplicate entries.");
+  }
+  if (indexes.some(
+    (index, position) => position > 0 && index <= indexes[position - 1]
+  )) {
+    throw new Error("selectVisiblePanes must preserve stack order.");
+  }
+  if (stack.length > 0 && !indexes.includes(stack.length - 1)) {
+    throw new Error("selectVisiblePanes must include the active pane.");
+  }
+  return Object.freeze(indexes.map((index) => stack[index]));
+}
+function snapshotFromResolvedConfig(config, state) {
+  const activePane = state.stack.at(-1);
+  const activeDefinition = activePane ? definitionFor(config, activePane.pane) : void 0;
+  const selected = config.selectVisiblePanes ? config.selectVisiblePanes(state.stack, {
+    activeDefinition,
+    definitions: config.panes
+  }) : state.stack.slice(
+    -(activeDefinition?.display?.maxVisible ?? config.maxVisible)
+  );
+  const visiblePanes = validateVisiblePanes(state.stack, selected);
+  return Object.freeze({
+    stack: state.stack,
+    revision: state.revision,
+    visiblePanes,
+    activePane,
+    canGoBack: state.stack.length > config.minimumDepth
+  });
+}
+function transitionWithResolvedConfig(config, state, event) {
+  const nextRevision = state.revision + 1;
+  switch (event.type) {
+    case "navigate": {
+      definitionFor(config, event.target.pane);
+      assertCanOpen(config, event.target.pane, state.stack.at(-1));
+      const added = entryFromTarget(
+        event.target,
+        state.stack.length,
+        nextRevision,
+        state.stack
+      );
+      const nextState = freezeState([...state.stack, added], nextRevision);
+      return {
+        state: nextState,
+        change: Object.freeze({ type: "navigate", added })
+      };
+    }
+    case "back": {
+      const steps = event.steps ?? 1;
+      assertPositiveInteger(steps, "back steps");
+      const removeCount = Math.min(
+        steps,
+        Math.max(0, state.stack.length - config.minimumDepth)
+      );
+      if (removeCount === 0) {
+        return { state, change: void 0 };
+      }
+      const removed = Object.freeze(state.stack.slice(-removeCount));
+      const nextState = freezeState(
+        state.stack.slice(0, -removeCount),
+        nextRevision
+      );
+      return {
+        state: nextState,
+        change: Object.freeze({ type: "back", removed })
+      };
+    }
+    case "back-to": {
+      let index = -1;
+      if (event.target.key !== void 0) {
+        index = state.stack.findIndex(
+          (entry) => entry.key === event.target.key
+        );
+      } else {
+        for (let cursor = state.stack.length - 1; cursor >= 0; cursor -= 1) {
+          if (state.stack[cursor]?.pane === event.target.pane) {
+            index = cursor;
+            break;
+          }
+        }
+      }
+      if (index === -1) {
+        const description = event.target.key !== void 0 ? `key "${event.target.key}"` : `pane "${event.target.pane}"`;
+        throw new Error(
+          `Cannot go back to ${description}; it is not in the stack.`
+        );
+      }
+      if (index + 1 < config.minimumDepth) {
+        throw new Error("Cannot go back below minimumDepth.");
+      }
+      if (index === state.stack.length - 1) {
+        return { state, change: void 0 };
+      }
+      const removed = Object.freeze(state.stack.slice(index + 1));
+      const nextState = freezeState(
+        state.stack.slice(0, index + 1),
+        nextRevision
+      );
+      return {
+        state: nextState,
+        change: Object.freeze({ type: "back-to", removed })
+      };
+    }
+    case "replace": {
+      if (state.stack.length === 0) {
+        throw new Error("Cannot replace a pane in an empty stack.");
+      }
+      definitionFor(config, event.target.pane);
+      const parent = state.stack.at(-2);
+      assertCanOpen(config, event.target.pane, parent);
+      const removed = state.stack.at(-1);
+      const parentStack = state.stack.slice(0, -1);
+      const added = entryFromTarget(
+        event.target,
+        state.stack.length - 1,
+        nextRevision,
+        parentStack
+      );
+      const nextState = freezeState([...parentStack, added], nextRevision);
+      return {
+        state: nextState,
+        change: Object.freeze({ type: "replace", added, removed })
+      };
+    }
+    case "reset": {
+      const targets = event.stack ?? config.initialStack;
+      if (targets.length < config.minimumDepth) {
+        throw new Error("Reset stack cannot be smaller than minimumDepth.");
+      }
+      const added = buildStack(config, targets, nextRevision);
+      const removed = Object.freeze([...state.stack]);
+      if (added.length === state.stack.length && added.every((entry, index) => {
+        const current = state.stack[index];
+        return current?.key === entry.key && current.pane === entry.pane && current.params === entry.params && current.data === entry.data;
+      })) {
+        return { state, change: void 0 };
+      }
+      const nextState = freezeState(added, nextRevision);
+      return {
+        state: nextState,
+        change: Object.freeze({ type: "reset", added, removed })
+      };
+    }
+  }
+}
+function definePaneConfig(config) {
+  return config;
+}
+function createPaneState(config) {
+  const resolved = resolveConfig(config);
+  const stack = buildStack(resolved, resolved.initialStack, 0);
+  return freezeState(stack, 0);
+}
+function transitionPaneState(config, state, event) {
+  return transitionWithResolvedConfig(resolveConfig(config), state, event);
+}
+function createPaneSnapshot(config, state) {
+  return snapshotFromResolvedConfig(resolveConfig(config), state);
+}
+var internal = {
+  resolveConfig,
+  snapshotFromResolvedConfig,
+  transitionWithResolvedConfig
+};
+
+// src/manager.ts
+function createPaneManager(config) {
+  const resolved = internal.resolveConfig(config);
+  let state = createPaneState(config);
+  let snapshot = internal.snapshotFromResolvedConfig(resolved, state);
+  const listeners = /* @__PURE__ */ new Set();
+  const dispatch = (event) => {
+    const transition = internal.transitionWithResolvedConfig(
+      resolved,
+      state,
+      event
+    );
+    if (transition.change === void 0) {
+      return snapshot;
+    }
+    const nextSnapshot = internal.snapshotFromResolvedConfig(
+      resolved,
+      transition.state
+    );
+    state = transition.state;
+    snapshot = nextSnapshot;
+    for (const listener of [...listeners]) {
+      listener(snapshot, transition.change);
+    }
+    return snapshot;
+  };
+  return {
+    getSnapshot() {
+      return snapshot;
+    },
+    getDefinition(pane) {
+      if (!Object.prototype.hasOwnProperty.call(resolved.panes, pane)) {
+        throw new Error(`Unknown pane "${pane}".`);
+      }
+      return resolved.panes[pane];
+    },
+    navigate(target) {
+      return dispatch({ type: "navigate", target });
+    },
+    back(options = {}) {
+      return dispatch(
+        options.steps === void 0 ? { type: "back" } : { type: "back", steps: options.steps }
+      );
+    },
+    backTo(target) {
+      return dispatch({ type: "back-to", target });
+    },
+    replace(target) {
+      return dispatch({ type: "replace", target });
+    },
+    reset(stack) {
+      return dispatch(
+        stack === void 0 ? { type: "reset" } : { type: "reset", stack }
+      );
+    },
+    canNavigate(target) {
+      try {
+        internal.transitionWithResolvedConfig(resolved, state, {
+          type: "navigate",
+          target
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    dispatch,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+export {
+  createPaneManager,
+  createPaneSnapshot,
+  createPaneState,
+  definePaneConfig,
+  transitionPaneState
+};

package/dist/react.cjs

@@ -0,0 +1,42 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react.ts
+var react_exports = {};
+__export(react_exports, {
+  usePaneSnapshot: () => usePaneSnapshot,
+  useVisiblePanes: () => useVisiblePanes
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+function usePaneSnapshot(manager) {
+  return (0, import_react.useSyncExternalStore)(
+    manager.subscribe,
+    manager.getSnapshot,
+    manager.getSnapshot
+  );
+}
+function useVisiblePanes(manager) {
+  return usePaneSnapshot(manager).visiblePanes;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  usePaneSnapshot,
+  useVisiblePanes
+});

package/dist/react.d.cts

@@ -0,0 +1,11 @@
+import { P as PaneSchema, f as PaneManager, c as PaneSnapshot, m as PaneEntry } from './types-DW8hgJuJ.cjs';
+
+/**
+ * Subscribe a React component to a pane manager and return its current
+ * immutable snapshot.
+ */
+declare function usePaneSnapshot<Schema extends PaneSchema>(manager: PaneManager<Schema>): PaneSnapshot<Schema>;
+/** Return the pane entries currently selected by the display policy. */
+declare function useVisiblePanes<Schema extends PaneSchema>(manager: PaneManager<Schema>): readonly PaneEntry<Schema>[];
+
+export { usePaneSnapshot, useVisiblePanes };

package/dist/react.d.ts

@@ -0,0 +1,11 @@
+import { P as PaneSchema, f as PaneManager, c as PaneSnapshot, m as PaneEntry } from './types-DW8hgJuJ.js';
+
+/**
+ * Subscribe a React component to a pane manager and return its current
+ * immutable snapshot.
+ */
+declare function usePaneSnapshot<Schema extends PaneSchema>(manager: PaneManager<Schema>): PaneSnapshot<Schema>;
+/** Return the pane entries currently selected by the display policy. */
+declare function useVisiblePanes<Schema extends PaneSchema>(manager: PaneManager<Schema>): readonly PaneEntry<Schema>[];
+
+export { usePaneSnapshot, useVisiblePanes };

package/dist/react.js

@@ -0,0 +1,16 @@
+// src/react.ts
+import { useSyncExternalStore } from "react";
+function usePaneSnapshot(manager) {
+  return useSyncExternalStore(
+    manager.subscribe,
+    manager.getSnapshot,
+    manager.getSnapshot
+  );
+}
+function useVisiblePanes(manager) {
+  return usePaneSnapshot(manager).visiblePanes;
+}
+export {
+  usePaneSnapshot,
+  useVisiblePanes
+};

package/dist/types-DW8hgJuJ.d.cts

@@ -0,0 +1,131 @@
+type PaneSchema = Record<string, unknown>;
+type PaneName<Schema extends PaneSchema> = Extract<keyof Schema, string>;
+type Field<Definition, Name extends PropertyKey, Fallback> = Definition extends Record<Name, infer Value> ? Value : Fallback;
+type PaneParams<Schema extends PaneSchema, Name extends PaneName<Schema>> = Field<Schema[Name], "params", undefined>;
+type PaneData<Schema extends PaneSchema, Name extends PaneName<Schema>> = Field<Schema[Name], "data", undefined>;
+type PaneMeta<Schema extends PaneSchema, Name extends PaneName<Schema>> = Field<Schema[Name], "meta", unknown>;
+type InputProperty<Name extends PropertyKey, Value> = undefined extends Value ? {
+    [Key in Name]?: Value;
+} : {
+    [Key in Name]: Value;
+};
+type PaneTargetFor<Schema extends PaneSchema, Name extends PaneName<Schema>> = {
+    readonly pane: Name;
+    readonly key?: string;
+} & InputProperty<"params", PaneParams<Schema, Name>> & InputProperty<"data", PaneData<Schema, Name>>;
+type PaneTarget<Schema extends PaneSchema> = {
+    [Name in PaneName<Schema>]: PaneTargetFor<Schema, Name>;
+}[PaneName<Schema>];
+type PaneEntryFor<Schema extends PaneSchema, Name extends PaneName<Schema>> = Readonly<{
+    key: string;
+    pane: Name;
+    params: PaneParams<Schema, Name>;
+    data: PaneData<Schema, Name>;
+    /** Zero-based position in the stack. */
+    depth: number;
+}>;
+type PaneEntry<Schema extends PaneSchema> = {
+    [Name in PaneName<Schema>]: PaneEntryFor<Schema, Name>;
+}[PaneName<Schema>];
+type PaneDefinition<Schema extends PaneSchema, Name extends PaneName<Schema>> = Readonly<{
+    canOpenFrom?: readonly PaneName<Schema>[];
+    display?: Readonly<{
+        maxVisible?: number;
+    }>;
+    meta?: PaneMeta<Schema, Name>;
+}>;
+type PaneDefinitions<Schema extends PaneSchema> = {
+    readonly [Name in PaneName<Schema>]: PaneDefinition<Schema, Name>;
+};
+interface PaneDisplayContext<Schema extends PaneSchema> {
+    readonly activeDefinition: PaneDefinition<Schema, PaneName<Schema>> | undefined;
+    readonly definitions: PaneDefinitions<Schema>;
+}
+interface PaneManagerConfig<Schema extends PaneSchema> {
+    readonly panes: PaneDefinitions<Schema>;
+    readonly initialStack?: readonly PaneTarget<Schema>[];
+    readonly display?: Readonly<{
+        maxVisible?: number;
+    }>;
+    /**
+     * Smallest stack depth reachable with back navigation. Defaults to one when
+     * an initial stack exists, and zero otherwise.
+     */
+    readonly minimumDepth?: number;
+    readonly selectVisiblePanes?: (stack: readonly PaneEntry<Schema>[], context: PaneDisplayContext<Schema>) => readonly PaneEntry<Schema>[];
+}
+interface DefinedPaneConfig<Schema extends PaneSchema> extends PaneManagerConfig<Schema> {
+    /** Carries the schema through inference without creating a runtime field. */
+    readonly __schema?: Schema;
+}
+interface PaneState<Schema extends PaneSchema> {
+    readonly stack: readonly PaneEntry<Schema>[];
+    readonly revision: number;
+}
+interface PaneSnapshot<Schema extends PaneSchema> extends PaneState<Schema> {
+    readonly visiblePanes: readonly PaneEntry<Schema>[];
+    readonly activePane: PaneEntry<Schema> | undefined;
+    readonly canGoBack: boolean;
+}
+type PaneBackToTarget<Schema extends PaneSchema> = Readonly<{
+    key: string;
+    pane?: never;
+}> | Readonly<{
+    pane: PaneName<Schema>;
+    key?: never;
+}>;
+type PaneEvent<Schema extends PaneSchema> = Readonly<{
+    type: "navigate";
+    target: PaneTarget<Schema>;
+}> | Readonly<{
+    type: "back";
+    steps?: number;
+}> | Readonly<{
+    type: "back-to";
+    target: PaneBackToTarget<Schema>;
+}> | Readonly<{
+    type: "replace";
+    target: PaneTarget<Schema>;
+}> | Readonly<{
+    type: "reset";
+    stack?: readonly PaneTarget<Schema>[];
+}>;
+type PaneChange<Schema extends PaneSchema> = Readonly<{
+    type: "navigate";
+    added: PaneEntry<Schema>;
+}> | Readonly<{
+    type: "back";
+    removed: readonly PaneEntry<Schema>[];
+}> | Readonly<{
+    type: "back-to";
+    removed: readonly PaneEntry<Schema>[];
+}> | Readonly<{
+    type: "replace";
+    added: PaneEntry<Schema>;
+    removed: PaneEntry<Schema>;
+}> | Readonly<{
+    type: "reset";
+    added: readonly PaneEntry<Schema>[];
+    removed: readonly PaneEntry<Schema>[];
+}>;
+interface PaneTransition<Schema extends PaneSchema> {
+    readonly state: PaneState<Schema>;
+    readonly change: PaneChange<Schema> | undefined;
+}
+type PaneListener<Schema extends PaneSchema> = (snapshot: PaneSnapshot<Schema>, change: PaneChange<Schema>) => void;
+interface PaneManager<Schema extends PaneSchema> {
+    getSnapshot(): PaneSnapshot<Schema>;
+    getDefinition<Name extends PaneName<Schema>>(pane: Name): PaneDefinition<Schema, Name>;
+    navigate<Name extends PaneName<Schema>>(target: PaneTargetFor<Schema, Name>): PaneSnapshot<Schema>;
+    back(options?: Readonly<{
+        steps?: number;
+    }>): PaneSnapshot<Schema>;
+    backTo(target: PaneBackToTarget<Schema>): PaneSnapshot<Schema>;
+    replace<Name extends PaneName<Schema>>(target: PaneTargetFor<Schema, Name>): PaneSnapshot<Schema>;
+    reset(stack?: readonly PaneTarget<Schema>[]): PaneSnapshot<Schema>;
+    canNavigate<Name extends PaneName<Schema>>(target: PaneTargetFor<Schema, Name>): boolean;
+    dispatch(event: PaneEvent<Schema>): PaneSnapshot<Schema>;
+    subscribe(listener: PaneListener<Schema>): () => void;
+}
+
+export type { DefinedPaneConfig as D, PaneSchema as P, PaneManagerConfig as a, PaneState as b, PaneSnapshot as c, PaneEvent as d, PaneTransition as e, PaneManager as f, PaneBackToTarget as g, PaneChange as h, PaneData as i, PaneDefinition as j, PaneDefinitions as k, PaneDisplayContext as l, PaneEntry as m, PaneEntryFor as n, PaneListener as o, PaneMeta as p, PaneName as q, PaneParams as r, PaneTarget as s, PaneTargetFor as t };