feat(core)!: API-design consistency pass — v7.0.0#205
Open
childrentime wants to merge 1 commit into
Open
Conversation
Audited all 112 hook signatures against The Little Manual of API Design
(/papers/api-design). Fixes the public-API defects it surfaced and adds an
authoritative spec so new hooks don't drift.
Breaking (renames/reorders only — no behavior change):
- useWindowsFocus -> useWindowFocus: the published export carried a stray
"s" (concept is "window focus"). Its `defauleValue` param -> `defaultValue`.
A shipped typo is locked forever (manual §3.8, the SHStripMneumonic story).
- useCookie(key, options?, defaultValue?) -> useCookie(key, defaultValue?, options?):
options was in the middle, inconsistent with useLocalStorage/useSessionStorage
and a "hard to misuse" trap — a string passed in the useLocalStorage shape was
silently typed as CookieAttributes (manual §4.2 / §2.3).
- useScrollIntoView / useSticky: first param `targetElement` -> `target`, matching
the 20 other DOM-target hooks (manual §4.2). Positional callers unaffected.
Non-breaking:
- Fixed JSDoc typos in editor autocomplete: usePreferredDark, usePreferredLanguages,
useRafFn, useCookie ("defaule"/"immediatly"/"incase").
Docs:
- New .claude/api-design.md — the public-signature contract (parameter order,
naming incl. default* vs initial*, return shape, SSR defaults), with the manual's
guidelines mapped to concrete repo rules and a list of grandfathered deviations
(Value/State suffix drift, useElementSize tuple vs useWindowSize object,
useFavicon trailing positionals, useSticky mid-positional config). Wired into
CLAUDE.md, .claude/README.md, knowledge-base.md, and the new-hook skill.
- Updated website-astro hook docs (en/zh-Hans/zh-Hant) and the browser-tab-ux blog
posts to the new names/argument order.
Tests: 59 suites / 305 tests green; eslint clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Audited all 112 hook signatures against The Little Manual of API Design (Blanchette / Trolltech, mirrored at
/papers/api-design). This fixes the public-API defects it surfaced and adds an authoritative spec so new hooks don't drift.Per semver this is a major (7.0.0) — the fixes are renames/reorders of published API. All changes are mechanical with no behavior change.
Breaking changes
useWindowsFocus→useWindowFocus(+ paramdefauleValue→defaultValue)SHStripMneumonicstory); §4.4 no typosimport { useWindowFocus } from '@reactuses/core'useCookie(key, options?, defaultValue?)→useCookie(key, defaultValue?, options?)useLocalStorage/useSessionStorage; a string in theuseLocalStorageshape was silently typed asCookieAttributesuseCookie('t', 'guest', { path: '/' })useScrollIntoView/useSticky: first paramtargetElement→targetNon-breaking
usePreferredDark,usePreferredLanguages,useRafFn,useCookie(defaule/immediatly/incase).New:
.claude/api-design.mdThe public-signature contract — parameter order (
(subject, …, options?)), naming (incl. the intentionaldefault*SSR-fallback vsinitial*mutable-seed distinction — deliberately not flattened, per §4.3 false consistency), return shape (tuple vs object), and SSR defaults. The manual's 12 guidelines are mapped to concrete repo rules, plus a grandfathered-deviations table for issues that need a deliberate decision rather than churn:Value/Statesuffix drift (defaultState×5, someinitialState) — param-name only, non-breaking, converge incrementallyuseElementSize→[w, h]tuple vsuseWindowSize→{ width, height }object — return-shape change, needs a major-version calluseFavicon(href, baseUrl, rel)trailing bare positionals;useStickyrequired mid-positional configWired into
CLAUDE.md,.claude/README.md,.claude/knowledge-base.md, and thenew-hookskill so the convention is enforced going forward.Also updated
website-astrohook docs (en / zh-Hans / zh-Hant) + the browser-tab-ux blog posts → new names / argument order.packages/corebumped to7.0.0; changelog entry with migration notes.Verification
jest— 59 suites / 305 tests pass (incl.useCookiewith reordered args)eslintclean on changed fileswebsite-docusaurussite left untouched (history / archived).🤖 Generated with Claude Code