@toolpath/app-support 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toolpath
+
+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,87 @@
+# Toolpath App Support
+
+`@toolpath/app-support` is the logic a Toolpath application reuses: the
+preferences, contexts and route helpers every application was otherwise going
+to write for itself, and did.
+
+**It renders nothing.** `@toolpath/ui` is the component kit — styling and
+display, the surface documented in
+[Storybook](https://storybook.staging.toolpath.com). This package is the other
+half. Neither depends on the other, and that is the point: a preference read by
+a loader on a server has no business pulling in a Tailwind component kit, and a
+button has no business knowing where a preference is stored.
+
+```
+    @toolpath/tool-support          depends on nothing
+             ↑
+    @toolpath/app-support           the logic          ─┐
+                                                        ├─  your application
+    @toolpath/ui                    the components     ─┘
+```
+
+## Install
+
+```sh
+npm install @toolpath/app-support react react-dom
+```
+
+`react` and `react-dom` are peer dependencies, needed only for the `/react`
+subpath.
+
+## Two entry points
+
+`@toolpath/app-support` imports no React. A preference is read by a loader on a
+server as often as by a component in a browser, so the half that does not need
+React does not import it.
+
+```ts
+import { loadUnit, saveUnit } from '@toolpath/app-support'
+
+const unit = loadUnit(globalThis.localStorage ?? null, 'catalog.unit')
+```
+
+`@toolpath/app-support/react` is the hooks and contexts.
+
+```tsx
+import { useUnit } from '@toolpath/app-support/react'
+
+export const UnitToggle = () => {
+  const [unit, choose] = useUnit('catalog.unit')
+
+  return (
+    <button type="button" onClick={() => choose(unit === 'inches' ? 'millimeters' : 'inches')}>
+      {unit}
+    </button>
+  )
+}
+```
+
+## The unit a person reads in
+
+The unit belongs to the person rather than to the thing being looked at: a
+machinist works in one of them all day and should not set it again after
+opening a report or a catalog.
+
+- **The storage and the key are the caller's.** Passing the storage in is what
+  lets this be called on a server or in a test without a `window`. Taking the
+  key means two applications on one origin hold their own units instead of
+  silently sharing one.
+- **`loadUnit` reads the older `'in'` spelling as well as `'inches'`.** Those
+  values are in people's browsers now, and a reader that accepts only the
+  current spelling moves every inch shop to metric the day it deploys.
+- **`useUnit` opens on millimetres and reads the stored preference on the first
+  effect**, so a server render and its hydration agree instead of flashing the
+  wrong numbers.
+
+The vocabulary is `@toolpath/tool-support`'s `UnitSystem`, which is this
+package's one runtime dependency.
+
+## Where this came from
+
+`loadUnit`, `saveUnit` and `useUnit` shipped in `@toolpath/ui` 0.2.0 and 0.3.0.
+That was the wrong package: the component kit is styling and display, and
+storage policy is neither. They live here from `@toolpath/ui` 1.0.0 onward.
+
+## License
+
+MIT

package/dist/chunk-YPOB3BBR.js

@@ -0,0 +1,13 @@
+// src/unit-preference.ts
+var loadUnit = (storage, key) => {
+  const stored = storage?.getItem(key);
+  return stored === "inches" || stored === "in" ? "inches" : "millimeters";
+};
+var saveUnit = (storage, key, unit) => {
+  storage?.setItem(key, unit);
+};
+
+export {
+  loadUnit,
+  saveUnit
+};

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { UnitSystem } from '@toolpath/tool-support';
+
+/**
+ * The unit a person reads in, remembered between visits.
+ *
+ * It belongs to the person rather than to the thing being looked at: a
+ * machinist works in one of them all day and should not set it again after
+ * opening a report or a catalog.
+ *
+ * The storage is the caller's, so this can be called in a test or on a server
+ * without a `window`, and the key is the caller's too. Two applications on one
+ * origin would otherwise silently share the preference — defensible, but a
+ * decision each application should make rather than inherit from a constant it
+ * cannot see.
+ *
+ * The vocabulary is `@toolpath/tool-support`'s {@link UnitSystem}, imported
+ * rather than restated. Which system a person reads in and which system a
+ * vendor published a tool in are the same two values, and a second spelling of
+ * them is the lookup table that package exists to have removed.
+ */
+/**
+ * The stored unit, defaulting to millimetres — what Toolpath states every
+ * length in.
+ *
+ * **`'in'` is read as well as `'inches'`.** The preference was written under
+ * the short spelling for as long as that was the vocabulary, and those values
+ * are in people's browsers now. A reader that accepts only the current
+ * spelling silently moves every inch shop to metric the day it deploys.
+ */
+declare const loadUnit: (storage: Pick<Storage, "getItem"> | null, key: string) => UnitSystem;
+/** Writes the current spelling. {@link loadUnit} still reads the old one. */
+declare const saveUnit: (storage: Pick<Storage, "setItem"> | null, key: string, unit: UnitSystem) => void;
+
+export { loadUnit, saveUnit };

package/dist/index.js

@@ -0,0 +1,8 @@
+import {
+  loadUnit,
+  saveUnit
+} from "./chunk-YPOB3BBR.js";
+export {
+  loadUnit,
+  saveUnit
+};

package/dist/react/index.d.ts

@@ -0,0 +1,24 @@
+import { UnitSystem } from '@toolpath/tool-support';
+
+/**
+ * The unit a person reads in, as a piece of React state.
+ *
+ * {@link loadUnit} and {@link saveUnit} are the storage; this is the three
+ * lines of React that every consumer of them was otherwise going to write. Two
+ * applications in the Toolpath template had written it, character for
+ * character, differing only in the key — which is the copy this exists to stop
+ * being made a third time.
+ *
+ * **The key is the caller's**, for the reason `unit-preference.ts` gives: two
+ * applications on one origin must be able to hold different units, and that is
+ * a decision each of them makes rather than inherits.
+ *
+ * **Read after mount rather than during render.** A server has no
+ * `localStorage`, so reading one while rendering makes the first paint depend
+ * on a browser that is not there yet — and a value that differed between the
+ * two hydrates as a flash of the wrong numbers. The opening state is therefore
+ * always millimetres, and the stored preference arrives on the first effect.
+ */
+declare const useUnit: (key: string) => [UnitSystem, (next: UnitSystem) => void];
+
+export { useUnit };

package/dist/react/index.js

@@ -0,0 +1,21 @@
+import {
+  loadUnit,
+  saveUnit
+} from "../chunk-YPOB3BBR.js";
+
+// src/react/use-unit.ts
+import { useEffect, useState } from "react";
+var useUnit = (key) => {
+  const [unit, setUnit] = useState("millimeters");
+  useEffect(() => {
+    setUnit(loadUnit(globalThis.localStorage ?? null, key));
+  }, [key]);
+  const choose = (next) => {
+    setUnit(next);
+    saveUnit(globalThis.localStorage ?? null, key, next);
+  };
+  return [unit, choose];
+};
+export {
+  useUnit
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@toolpath/app-support",
+  "version": "0.1.0",
+  "description": "Reusable logic for a Toolpath application: preferences, contexts and route helpers",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toolpath/ui-packages.git",
+    "directory": "packages/app-support"
+  },
+  "homepage": "https://developers.toolpath.com",
+  "bugs": {
+    "url": "https://github.com/toolpath/ui-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts src/react/index.ts --format esm --dts --clean --external react --external react-dom",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@toolpath/tool-support": "workspace:^"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "24.10.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.1",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  }
+}