growing-panes 0.2.0

package/dist/types-DW8hgJuJ.d.ts

@@ -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 };

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "growing-panes",
+  "version": "0.2.0",
+  "description": "Headless stack-based pane navigation for JavaScript and TypeScript",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts src/react.ts --format esm,cjs --dts --clean --external react",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm typecheck && pnpm test && pnpm build && pnpm site:build",
+    "site:dev": "vite --config vite.config.ts",
+    "site:build": "vite build --config vite.config.ts",
+    "site:preview": "vite preview --config vite.config.ts",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm build && changeset publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jhsu/growing-panes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jhsu/growing-panes/issues"
+  },
+  "homepage": "https://jhsu.github.io/growing-panes/",
+  "keywords": [
+    "headless",
+    "navigation",
+    "panes",
+    "stack",
+    "state-machine"
+  ],
+  "author": "Joseph Hsu",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@11.3.0",
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2"
+  }
+}