growing-panes 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# growing-panes
+
+## 0.2.0
+
+### Minor Changes
+
+- 275cd21: Add the initial headless pane stack, state transition API, typed configuration,
+  visibility policies, subscriptions, and navigation manager.
+
+### Patch Changes
+
+- 275cd21: Add manager and pure state-machine examples for the headless core API.
+- 1cfbc05: Add an interactive project site, package homepage metadata, and GitHub Pages
+  deployment workflow.
+- 275cd21: Add a `growing-panes/react` entry point with `usePaneSnapshot` and
+  `useVisiblePanes` hooks.
+- e3b1f35: Remove the legacy AngularJS directive, bundled artifact, and demo application.

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2014 Joseph Hsu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# growing-panes
+
+Headless stack-based pane navigation for JavaScript and TypeScript.
+
+Growing Panes manages pane definitions, navigation state, and the set of panes
+that should be displayed. It does not require a DOM, router, or UI framework.
+
+[View the interactive demo](https://jhsu.github.io/growing-panes/).
+
+## Install
+
+```sh
+pnpm add growing-panes
+```
+
+## Usage
+
+Define the pane types and their navigation relationships:
+
+```ts
+import { createPaneManager, definePaneConfig } from "growing-panes";
+
+type AppPanes = {
+  projects: {
+    params: undefined;
+    meta: { title: string };
+  };
+  project: {
+    params: { projectId: string };
+    meta: { title: string };
+  };
+  task: {
+    params: { taskId: string };
+    meta: { title: string };
+  };
+  preview: {
+    params: { taskId: string };
+    meta: { title: string };
+  };
+};
+
+const config = definePaneConfig<AppPanes>({
+  display: { maxVisible: 2 },
+  panes: {
+    projects: {
+      meta: { title: "Projects" },
+    },
+    project: {
+      canOpenFrom: ["projects"],
+      meta: { title: "Project" },
+    },
+    task: {
+      canOpenFrom: ["project"],
+      meta: { title: "Task" },
+    },
+    preview: {
+      canOpenFrom: ["task"],
+      display: { maxVisible: 3 },
+      meta: { title: "Preview" },
+    },
+  },
+  initialStack: [{ pane: "projects" }],
+});
+
+const panes = createPaneManager(config);
+
+panes.navigate({
+  pane: "project",
+  params: { projectId: "p-123" },
+});
+
+panes.navigate({
+  pane: "task",
+  params: { taskId: "t-456" },
+});
+
+const snapshot = panes.getSnapshot();
+
+snapshot.stack;        // projects, project, task
+snapshot.visiblePanes; // project, task
+snapshot.activePane;   // task
+snapshot.canGoBack;    // true
+
+panes.back();
+```
+
+## Manager API
+
+The manager provides these navigation operations:
+
+- `navigate(target)` appends a pane and makes it active.
+- `back({ steps })` removes panes from the end of the stack.
+- `backTo({ key })` or `backTo({ pane })` selects an existing ancestor.
+- `replace(target)` replaces the active pane.
+- `reset(stack)` replaces the complete stack.
+- `canNavigate(target)` checks a transition without changing state.
+- `subscribe(listener)` observes successful state changes.
+- `dispatch(event)` sends a state-machine event directly.
+
+Snapshots are immutable. `visiblePanes`, `activePane`, and `canGoBack` are
+derived from the stack rather than stored independently.
+
+## Pure state transitions
+
+The core can also be used without the manager wrapper:
+
+```ts
+import { createPaneState, transitionPaneState } from "growing-panes";
+
+const state = createPaneState(config);
+const transition = transitionPaneState(config, state, {
+  type: "navigate",
+  target: {
+    pane: "project",
+    params: { projectId: "p-123" },
+  },
+});
+
+transition.state;
+transition.change;
+```
+
+This reducer-style API is synchronous and deterministic. Data loading, URL
+synchronization, rendering, animations, and focus management belong in
+application code or framework adapters.
+
+## React
+
+React applications can subscribe through the optional `growing-panes/react`
+entry point. Importing the core package does not load React.
+
+```tsx
+import { usePaneSnapshot } from "growing-panes/react";
+
+function PaneContainer({ manager }) {
+  const snapshot = usePaneSnapshot(manager);
+
+  return snapshot.visiblePanes.map((entry) => (
+    <PaneRenderer key={entry.key} entry={entry} />
+  ));
+}
+```
+
+Use `useVisiblePanes(manager)` when only the visible entry list is needed.
+React 18 or newer is required for these hooks.
+
+## Development
+
+```sh
+pnpm install
+pnpm check
+pnpm changeset
+pnpm site:dev
+```
+
+The fuller design discussion is in
+[`docs/core-api-draft.md`](docs/core-api-draft.md).
+
+## Examples
+
+- [`examples/manager.ts`](examples/manager.ts) uses the subscription-based
+  manager API for a projects and tasks flow.
+- [`examples/state-machine.ts`](examples/state-machine.ts) uses the pure
+  transition API for a recursive file browser.

package/dist/index.cjs

@@ -0,0 +1,404 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createPaneManager: () => createPaneManager,
+  createPaneSnapshot: () => createPaneSnapshot,
+  createPaneState: () => createPaneState,
+  definePaneConfig: () => definePaneConfig,
+  transitionPaneState: () => transitionPaneState
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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);
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createPaneManager,
+  createPaneSnapshot,
+  createPaneState,
+  definePaneConfig,
+  transitionPaneState
+});

package/dist/index.d.cts

@@ -0,0 +1,11 @@
+import { P as PaneSchema, a as PaneManagerConfig, b as PaneState, c as PaneSnapshot, D as DefinedPaneConfig, d as PaneEvent, e as PaneTransition, f as PaneManager } from './types-DW8hgJuJ.cjs';
+export { g as PaneBackToTarget, h as PaneChange, i as PaneData, j as PaneDefinition, k as PaneDefinitions, l as PaneDisplayContext, m as PaneEntry, n as PaneEntryFor, o as PaneListener, p as PaneMeta, q as PaneName, r as PaneParams, s as PaneTarget, t as PaneTargetFor } from './types-DW8hgJuJ.cjs';
+
+declare function definePaneConfig<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>): DefinedPaneConfig<Schema>;
+declare function createPaneState<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>): PaneState<Schema>;
+declare function transitionPaneState<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>, state: PaneState<Schema>, event: PaneEvent<Schema>): PaneTransition<Schema>;
+declare function createPaneSnapshot<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>, state: PaneState<Schema>): PaneSnapshot<Schema>;
+
+declare function createPaneManager<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>): PaneManager<Schema>;
+
+export { DefinedPaneConfig, PaneEvent, PaneManager, PaneManagerConfig, PaneSchema, PaneSnapshot, PaneState, PaneTransition, createPaneManager, createPaneSnapshot, createPaneState, definePaneConfig, transitionPaneState };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { P as PaneSchema, a as PaneManagerConfig, b as PaneState, c as PaneSnapshot, D as DefinedPaneConfig, d as PaneEvent, e as PaneTransition, f as PaneManager } from './types-DW8hgJuJ.js';
+export { g as PaneBackToTarget, h as PaneChange, i as PaneData, j as PaneDefinition, k as PaneDefinitions, l as PaneDisplayContext, m as PaneEntry, n as PaneEntryFor, o as PaneListener, p as PaneMeta, q as PaneName, r as PaneParams, s as PaneTarget, t as PaneTargetFor } from './types-DW8hgJuJ.js';
+
+declare function definePaneConfig<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>): DefinedPaneConfig<Schema>;
+declare function createPaneState<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>): PaneState<Schema>;
+declare function transitionPaneState<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>, state: PaneState<Schema>, event: PaneEvent<Schema>): PaneTransition<Schema>;
+declare function createPaneSnapshot<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>, state: PaneState<Schema>): PaneSnapshot<Schema>;
+
+declare function createPaneManager<Schema extends PaneSchema>(config: PaneManagerConfig<Schema>): PaneManager<Schema>;
+
+export { DefinedPaneConfig, PaneEvent, PaneManager, PaneManagerConfig, PaneSchema, PaneSnapshot, PaneState, PaneTransition, createPaneManager, createPaneSnapshot, createPaneState, definePaneConfig, transitionPaneState };