@fvc/utils 3.0.2 → 3.0.3-next-d4799a7fa99a8ef4e7e8adfc3793fd349346277e

package/CHANGELOG.md

@@ -0,0 +1,288 @@
+# @fvc/utils
+
+## 3.0.3-next-d4799a7fa99a8ef4e7e8adfc3793fd349346277e
+
+### Patch Changes
+
+- 51a1a4c: Include `CHANGELOG.md` inside every published `@fvc/*` tarball.
+
+  Until this patch, `packages/<pkg>/package.json#files` only declared
+  `dist/lib/index.js`, `dist/lib/<pkg>`, and `package.json`, which
+  meant `npm pack` skipped the package's `CHANGELOG.md` even though
+  it is generated by Changesets at release time and lives at the
+  package root. Consumers had no way to read the changelog after
+  installing the package — they had to visit GitLab.
+
+  This patch adds `"CHANGELOG.md"` to every publishable package's
+  `files` array, including the scaffolder template
+  (`codegen/templates/component/package.json.hbs`) so new packages
+  inherit the setting from day one. After this ships, running
+  `npm view @fvc/<pkg>@<latest>` returns a tarball whose manifest
+  includes `CHANGELOG.md`, and `cat node_modules/@fvc/<pkg>/CHANGELOG.md`
+  on the consumer side returns the changelog content directly.
+
+  No component source changes. This is metadata-only, but it is a
+  patch bump on every package because the published-tarball contents
+  change — a deliberately conservative semver choice for a release
+  that materially affects what consumers receive on `npm install`.
+
+## 3.0.2
+
+### Patch Changes
+
+- e601138: readme changes
+- cd80d11: readme and keywords file
+
+## 3.0.2-rc.1
+
+### Patch Changes
+
+- e601138: readme changes
+
+## 3.0.2-rc.0
+
+### Patch Changes
+
+- cd80d11: readme and keywords file
+
+## 3.0.1
+
+### Patch Changes
+
+- f176af2: Clean up stale pre-release suffix from @fvc/\* peer dependency ranges
+
+  The v3.0.0 release shipped to npm with peer dependency ranges still
+  carrying the `-rc.0` pre-release suffix from the release branch's
+  pre-mode bump. Concretely, `@fvc/card@3.0.0`'s manifest on npm
+  @latest declared:
+
+  ```json
+  "peerDependencies": {
+    "@fvc/utils": "^3.0.0-rc.0",
+    "@fvc/typography": "^3.0.0-rc.0"
+  }
+  ```
+
+  Root cause is the interaction between Changesets' exit-mode behaviour
+  and the `onlyUpdatePeerDependentsWhenOutOfRange` experimental flag,
+  which we had set to `true`. Inside `@changesets/apply-release-plan`'s
+  `shouldUpdateDependencyBasedOnConfig`:
+
+  ```js
+  if (!semverSatisfies(release.version, depVersionRange)) {
+    // out of range → always update
+    return true;
+  }
+  if (depType === 'peerDependencies') {
+    shouldUpdate = !onlyUpdatePeerDependentsWhenOutOfRange;
+  }
+  ```
+
+  In exit mode `utils` goes from `3.0.0-rc.0` to `3.0.0`. The
+  peer-range `^3.0.0-rc.0` still semver-satisfies `3.0.0` (rc.0 sorts
+  before stable per semver), so the `out-of-range` branch is skipped.
+  With the flag set to `true`, `shouldUpdate` collapses to `false`
+  and peer ranges are intentionally left untouched. The package then
+  ships to @latest with a stale pre-release range.
+
+  This is not a Changesets bug — the library is correctly honouring
+  its configured behaviour — but the combination is wrong for our
+  monorepo's lifecycle. This patch:
+  1. Removes the `___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH`
+     block from `.changeset/config.json`, restoring Changesets' default
+     behaviour of updating internal peer-dep ranges on every bump of
+     the peer package. This eliminates the stale-suffix path
+     permanently: every future release of `@fvc/utils` (or any other
+     internal peer) will refresh its dependents' peer ranges
+     deterministically.
+  2. Patch-bumps every package whose peer-deps need to be refreshed
+     on `@latest`: `utils` (driver of the cascade), plus `card`,
+     `input`, `provider`, and `typography` (the four packages whose
+     on-disk peer ranges still carry the `-rc.0` suffix from the
+     v3.0.0 cycle). When `prepare:latest` runs `bunx changeset
+version` against this changeset under the new config, the
+     pre-release suffix is rewritten away as part of the normal
+     peer-range update path.
+
+  Trade-off accepted: every future bump of an internal peer (utils
+  in particular) will trigger a peer-range refresh in its dependents.
+  At our current scale (~5 internal-peer relationships) this is a
+  non-issue and produces tighter peer pinning, which is desirable for
+  a controlled monorepo. The alternative — a custom CI sanitiser
+  script — would have been a permanent workaround for a config we
+  were never supposed to set in the first place.
+
+  No source code in any package changes.
+
+## 3.0.0
+
+### Major Changes
+
+- f3dcc20: Synthetic release-flow validation for the v3.0.0 cycle
+
+  Exercise the new master-side `prepare:latest` job end-to-end, with
+  emphasis on:
+  - The `changeset pre exit` step (the pre.json mode flip) on master,
+    which only fires when the merged release branch carries a
+    `pre.json` in `mode: "pre"`.
+  - The `changeset version` step in exit mode, which is supposed to
+    strip the `-rc.X` suffix from each affected package's `version`
+    field and from internal `@fvc/*` peer dependency ranges (the
+    latter is the Faz 2 candidate — this test will tell us whether
+    a sanitiser step is needed in `prepare:latest`).
+  - The peer-dependency cascade triggered by an out-of-range major
+    bump. `@fvc/utils` going from `2.0.0` to `3.0.0` is out of range
+    for every `^2.0.0` peer dep on it, so Changesets'
+    `onlyUpdatePeerDependentsWhenOutOfRange` flag should propagate
+    the major to every package that lists `@fvc/utils` as a peer.
+
+  No public API of `@fvc/utils` changes in this commit. The marker
+  comment in `packages/utils/src/index.ts` exists solely to satisfy
+  the `changeset:required` gate (which trips on `packages/**`
+  changes) and to provide a real, reviewable file change to
+  accompany the changeset.
+
+## 3.0.0-rc.0
+
+### Major Changes
+
+- f3dcc20: Synthetic release-flow validation for the v3.0.0 cycle
+
+  Exercise the new master-side `prepare:latest` job end-to-end, with
+  emphasis on:
+  - The `changeset pre exit` step (the pre.json mode flip) on master,
+    which only fires when the merged release branch carries a
+    `pre.json` in `mode: "pre"`.
+  - The `changeset version` step in exit mode, which is supposed to
+    strip the `-rc.X` suffix from each affected package's `version`
+    field and from internal `@fvc/*` peer dependency ranges (the
+    latter is the Faz 2 candidate — this test will tell us whether
+    a sanitiser step is needed in `prepare:latest`).
+  - The peer-dependency cascade triggered by an out-of-range major
+    bump. `@fvc/utils` going from `2.0.0` to `3.0.0` is out of range
+    for every `^2.0.0` peer dep on it, so Changesets'
+    `onlyUpdatePeerDependentsWhenOutOfRange` flag should propagate
+    the major to every package that lists `@fvc/utils` as a peer.
+
+  No public API of `@fvc/utils` changes in this commit. The marker
+  comment in `packages/utils/src/index.ts` exists solely to satisfy
+  the `changeset:required` gate (which trips on `packages/**`
+  changes) and to provide a real, reviewable file change to
+  accompany the changeset.
+
+## 2.0.0
+
+### Major Changes
+
+- 45936ec: **BREAKING**: `clamp` now accepts a single options object instead of three
+  positional arguments.
+
+  **Why**: Named arguments remove the "which order are min and max in?"
+  guessing that positional calls require, and the new exported `ClampOptions`
+  type gives consumers a stable surface to extend (e.g. for future
+  `precision`, `inclusive`, or unit options) without another breaking change
+  later. Positional signatures are also harder to read at call sites where
+  all three arguments are numeric literals.
+
+  **Migration**: replace every positional call with an options-object call.
+
+  ```ts
+  // Before
+  import { clamp } from '@fvc/utils';
+
+  clamp(5, 0, 10); // -> 5
+  clamp(-100, -10, 10); // -> -10
+  clamp(15, 0, 10); // -> 10
+
+  // After
+  import { clamp } from '@fvc/utils';
+
+  clamp({ value: 5, min: 0, max: 10 }); // -> 5
+  clamp({ value: -100, min: -10, max: 10 }); // -> -10
+  clamp({ value: 15, min: 0, max: 10 }); // -> 10
+  ```
+
+  If you wrap `clamp` in a helper, the new `ClampOptions` type is exported
+  from `@fvc/utils` for the wrapper's argument type:
+
+  ```ts
+  import { clamp, type ClampOptions } from '@fvc/utils';
+
+  export const clampOpacity = (value: number): number =>
+    clamp({ value, min: 0, max: 1 });
+
+  export const wrapClamp = (opts: ClampOptions): number => clamp(opts);
+  ```
+
+  Throw behaviour is unchanged: passing `min > max` still throws
+  `Error("clamp: min cannot be greater than max")`.
+
+### Minor Changes
+
+- 0d71f57: Add clamp utility that constrains a number between a minimum and maximum bound
+
+### Patch Changes
+
+- e0a3c27: Tighten isNumeric type safety: explicit boolean return, null/undefined guard, no as cast
+- 2f5263f: Add explicit return type annotation to cssVarResolver for type safety
+
+## 2.0.0-rc.1
+
+### Patch Changes
+
+- 2f5263f: Add explicit return type annotation to cssVarResolver for type safety
+
+## 2.0.0-rc.0
+
+### Major Changes
+
+- 45936ec: **BREAKING**: `clamp` now accepts a single options object instead of three
+  positional arguments.
+
+  **Why**: Named arguments remove the "which order are min and max in?"
+  guessing that positional calls require, and the new exported `ClampOptions`
+  type gives consumers a stable surface to extend (e.g. for future
+  `precision`, `inclusive`, or unit options) without another breaking change
+  later. Positional signatures are also harder to read at call sites where
+  all three arguments are numeric literals.
+
+  **Migration**: replace every positional call with an options-object call.
+
+  ```ts
+  // Before
+  import { clamp } from '@fvc/utils';
+
+  clamp(5, 0, 10); // -> 5
+  clamp(-100, -10, 10); // -> -10
+  clamp(15, 0, 10); // -> 10
+
+  // After
+  import { clamp } from '@fvc/utils';
+
+  clamp({ value: 5, min: 0, max: 10 }); // -> 5
+  clamp({ value: -100, min: -10, max: 10 }); // -> -10
+  clamp({ value: 15, min: 0, max: 10 }); // -> 10
+  ```
+
+  If you wrap `clamp` in a helper, the new `ClampOptions` type is exported
+  from `@fvc/utils` for the wrapper's argument type:
+
+  ```ts
+  import { clamp, type ClampOptions } from '@fvc/utils';
+
+  export const clampOpacity = (value: number): number =>
+    clamp({ value, min: 0, max: 1 });
+
+  export const wrapClamp = (opts: ClampOptions): number => clamp(opts);
+  ```
+
+  Throw behaviour is unchanged: passing `min > max` still throws
+  `Error("clamp: min cannot be greater than max")`.
+
+### Minor Changes
+
+- 0d71f57: Add clamp utility that constrains a number between a minimum and maximum bound
+
+### Patch Changes
+
+- e0a3c27: Tighten isNumeric type safety: explicit boolean return, null/undefined guard, no as cast

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fvc/utils",
-  "version": "3.0.2",
+  "version": "3.0.3-next-d4799a7fa99a8ef4e7e8adfc3793fd349346277e",
   "main": "./dist/lib/index.js",
   "types": "./dist/lib/utils/src/index.d.ts",
   "exports": {
@@ -13,7 +13,8 @@
   "files": [
     "dist/lib/index.js",
     "dist/lib/utils",
-    "package.json"
+    "package.json",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "rollup -c ./rollup.config.mjs",