From 59abdfb645dc0f36c857a92389897179494fe330 Mon Sep 17 00:00:00 2001 From: Titouan Mathis Date: Wed, 26 Aug 2026 19:05:00 +0200 Subject: [PATCH 1/2] docs(v4): ship the documentation site 123 pages on the packages/docs theme, written against DESIGN.md and RATIONALE.md with every signature verified against src/ or the built declarations: the guide, the full Base API, one page per service, decorator, registry helper and context function, and the utils reference by category. The site lives inside the v4 package rather than beside packages/docs: its VitePress, Tailwind and twoslash dependencies are v4 devDependencies and its scripts hang off @studiometa/js-toolkit-v4, so packages/* in the workspaces glob needs no change. Samples are twoslash-checked, which caught four claims that were wrong: on methods get no automatic parameter typing; @on checks an annotation rather than replacing it; only @on's class form carries the payload type, since a string is just a string to the type system; and an intermediate class must annotate `static config: BaseConfig` or its inferred literal type breaks every subclass that adds an option. packages/v4/docs/** joins the relaxed oxlint override beside test/ and scripts/, since the strict type-aware block for packages/v4/**/*.ts flags the copied VitePress theme. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_012ioM9dGKVhexCv4NLUcbA7 --- .gitignore | 2 + .oxlintrc.json | 3 +- README.md | 15 +- package-lock.json | 44 +- package.json | 3 + packages/v4/docs/.vitepress/config.ts | 345 ++++++++++++++++ .../.vitepress/theme/components/Loader.vue | 31 ++ .../theme/components/PreviewIframe.vue | 67 ++++ .../theme/composables/useAllLinks.ts | 81 ++++ .../theme/composables/useObserver.ts | 38 ++ packages/v4/docs/.vitepress/theme/index.ts | 13 + packages/v4/docs/.vitepress/theme/styles.css | 65 +++ packages/v4/docs/api/configuration.md | 176 ++++++++ packages/v4/docs/api/context/createContext.md | 47 +++ packages/v4/docs/api/context/createGroup.md | 69 ++++ packages/v4/docs/api/context/index.md | 73 ++++ packages/v4/docs/api/context/injectContext.md | 62 +++ .../v4/docs/api/context/injectContextSync.md | 48 +++ .../v4/docs/api/context/provideContext.md | 65 +++ .../v4/docs/api/context/provideRootContext.md | 44 ++ packages/v4/docs/api/context/signal.md | 88 ++++ .../v4/docs/api/context/subscribeContext.md | 73 ++++ packages/v4/docs/api/decorators/children.md | 97 +++++ packages/v4/docs/api/decorators/component.md | 79 ++++ packages/v4/docs/api/decorators/index.md | 43 ++ packages/v4/docs/api/decorators/inject.md | 79 ++++ packages/v4/docs/api/decorators/on.md | 159 ++++++++ packages/v4/docs/api/decorators/provide.md | 83 ++++ packages/v4/docs/api/decorators/read-write.md | 97 +++++ .../v4/docs/api/diagnostics/DIAGNOSTICS.md | 142 +++++++ packages/v4/docs/api/diagnostics/EVENTS.md | 47 +++ packages/v4/docs/api/diagnostics/index.md | 60 +++ .../docs/api/diagnostics/reportDiagnostic.md | 68 ++++ packages/v4/docs/api/diagnostics/warn.md | 55 +++ packages/v4/docs/api/dom/breakpoints.md | 85 ++++ packages/v4/docs/api/dom/domUpdate.md | 72 ++++ packages/v4/docs/api/dom/emitExtendable.md | 70 ++++ packages/v4/docs/api/dom/index.md | 26 ++ packages/v4/docs/api/dom/swap.md | 110 +++++ .../docs/api/dom/watchAttributeNamespace.md | 98 +++++ packages/v4/docs/api/dom/watchAttributes.md | 59 +++ packages/v4/docs/api/dom/whenDOMSettled.md | 42 ++ packages/v4/docs/api/html/data-component.md | 107 +++++ packages/v4/docs/api/html/data-mount.md | 71 ++++ packages/v4/docs/api/html/data-option.md | 108 +++++ packages/v4/docs/api/html/data-ref.md | 65 +++ packages/v4/docs/api/html/index.md | 32 ++ packages/v4/docs/api/index.md | 77 ++++ packages/v4/docs/api/instance-events.md | 78 ++++ packages/v4/docs/api/instance-methods.md | 276 +++++++++++++ packages/v4/docs/api/instance-properties.md | 92 +++++ packages/v4/docs/api/methods-hooks-events.md | 155 ++++++++ .../v4/docs/api/methods-hooks-lifecycle.md | 95 +++++ packages/v4/docs/api/methods-hooks-options.md | 100 +++++ .../v4/docs/api/methods-hooks-services.md | 170 ++++++++ .../v4/docs/api/registry/defineManifest.md | 57 +++ packages/v4/docs/api/registry/fromMetaGlob.md | 33 ++ .../docs/api/registry/fromWebpackContext.md | 37 ++ packages/v4/docs/api/registry/getInstance.md | 54 +++ packages/v4/docs/api/registry/getInstances.md | 49 +++ .../docs/api/registry/getMountedInstances.md | 40 ++ .../api/registry/getUnmountedInstances.md | 47 +++ packages/v4/docs/api/registry/index.md | 51 +++ .../v4/docs/api/registry/registerComponent.md | 96 +++++ .../docs/api/registry/registerComponents.md | 38 ++ .../v4/docs/api/registry/registerManifest.md | 72 ++++ .../v4/docs/api/scheduler/defaultScheduler.md | 109 +++++ packages/v4/docs/api/scheduler/index.md | 27 ++ packages/v4/docs/api/scheduler/nextFrame.md | 32 ++ .../v4/docs/api/scheduler/viewTransition.md | 54 +++ .../v4/docs/api/services/createService.md | 98 +++++ .../docs/api/services/createServiceMixin.md | 83 ++++ packages/v4/docs/api/services/index.md | 96 +++++ packages/v4/docs/api/services/mixins.md | 154 +++++++ packages/v4/docs/api/services/perTarget.md | 66 +++ packages/v4/docs/api/services/toggle.md | 82 ++++ packages/v4/docs/api/services/until.md | 45 +++ .../v4/docs/api/services/useBreakpoint.md | 43 ++ packages/v4/docs/api/services/useDrag.md | 121 ++++++ packages/v4/docs/api/services/useInView.md | 65 +++ packages/v4/docs/api/services/useKey.md | 107 +++++ .../v4/docs/api/services/useMediaQuery.md | 46 +++ packages/v4/docs/api/services/useMutation.md | 70 ++++ packages/v4/docs/api/services/usePointer.md | 93 +++++ .../api/services/usePrefersReducedMotion.md | 43 ++ packages/v4/docs/api/services/useRaf.md | 94 +++++ packages/v4/docs/api/services/useResize.md | 61 +++ packages/v4/docs/api/services/useScroll.md | 90 +++++ .../v4/docs/api/services/useScrollProgress.md | 89 +++++ .../v4/docs/api/services/useWindowScroll.md | 26 ++ .../v4/docs/api/services/useWindowSize.md | 26 ++ packages/v4/docs/api/storage/createStorage.md | 131 ++++++ packages/v4/docs/api/storage/index.md | 33 ++ packages/v4/docs/api/storage/presets.md | 59 +++ packages/v4/docs/api/storage/providers.md | 113 ++++++ packages/v4/docs/api/test/index.md | 218 ++++++++++ .../docs/guide/concepts/attribute-grammar.md | 95 +++++ .../v4/docs/guide/concepts/mutation-engine.md | 73 ++++ packages/v4/docs/guide/concepts/philosophy.md | 80 ++++ .../v4/docs/guide/concepts/the-registry.md | 112 ++++++ .../docs/guide/going-further/autoloading.md | 106 +++++ .../going-further/handling-diagnostics.md | 110 +++++ .../guide/going-further/mount-strategies.md | 98 +++++ .../guide/going-further/scheduling-work.md | 132 ++++++ .../docs/guide/going-further/sharing-state.md | 234 +++++++++++ .../guide/going-further/swapping-content.md | 96 +++++ .../guide/going-further/testing-components.md | 141 +++++++ .../guide/going-further/typing-components.md | 204 ++++++++++ .../guide/going-further/using-decorators.md | 175 ++++++++ .../docs/guide/going-further/using-storage.md | 131 ++++++ packages/v4/docs/guide/index.md | 168 ++++++++ .../docs/guide/introduction/installation.md | 130 ++++++ .../guide/introduction/lifecycle-hooks.md | 183 +++++++++ .../guide/introduction/managing-components.md | 237 +++++++++++ .../guide/introduction/managing-options.md | 242 +++++++++++ .../docs/guide/introduction/managing-refs.md | 181 +++++++++ .../docs/guide/introduction/using-services.md | 227 +++++++++++ .../guide/introduction/working-with-events.md | 260 ++++++++++++ packages/v4/docs/guide/migration/v3-to-v4.md | 375 ++++++++++++++++++ packages/v4/docs/index.md | 39 ++ packages/v4/docs/public/logo.png | Bin 0 -> 2800 bytes packages/v4/docs/utils/css.md | 89 +++++ packages/v4/docs/utils/dom.md | 59 +++ packages/v4/docs/utils/easings.md | 74 ++++ packages/v4/docs/utils/focus.md | 74 ++++ packages/v4/docs/utils/history.md | 67 ++++ packages/v4/docs/utils/index.md | 55 +++ packages/v4/docs/utils/is.md | 56 +++ packages/v4/docs/utils/load.md | 51 +++ packages/v4/docs/utils/math.md | 95 +++++ packages/v4/docs/utils/motion.md | 170 ++++++++ packages/v4/docs/utils/objects.md | 68 ++++ packages/v4/docs/utils/scroll.md | 122 ++++++ packages/v4/docs/utils/strings.md | 81 ++++ packages/v4/docs/utils/timing.md | 101 +++++ packages/v4/docs/utils/transitions.md | 107 +++++ packages/v4/docs/vite.config.ts | 7 + packages/v4/package.json | 9 + 138 files changed, 12479 insertions(+), 32 deletions(-) create mode 100644 packages/v4/docs/.vitepress/config.ts create mode 100644 packages/v4/docs/.vitepress/theme/components/Loader.vue create mode 100644 packages/v4/docs/.vitepress/theme/components/PreviewIframe.vue create mode 100644 packages/v4/docs/.vitepress/theme/composables/useAllLinks.ts create mode 100644 packages/v4/docs/.vitepress/theme/composables/useObserver.ts create mode 100644 packages/v4/docs/.vitepress/theme/index.ts create mode 100644 packages/v4/docs/.vitepress/theme/styles.css create mode 100644 packages/v4/docs/api/configuration.md create mode 100644 packages/v4/docs/api/context/createContext.md create mode 100644 packages/v4/docs/api/context/createGroup.md create mode 100644 packages/v4/docs/api/context/index.md create mode 100644 packages/v4/docs/api/context/injectContext.md create mode 100644 packages/v4/docs/api/context/injectContextSync.md create mode 100644 packages/v4/docs/api/context/provideContext.md create mode 100644 packages/v4/docs/api/context/provideRootContext.md create mode 100644 packages/v4/docs/api/context/signal.md create mode 100644 packages/v4/docs/api/context/subscribeContext.md create mode 100644 packages/v4/docs/api/decorators/children.md create mode 100644 packages/v4/docs/api/decorators/component.md create mode 100644 packages/v4/docs/api/decorators/index.md create mode 100644 packages/v4/docs/api/decorators/inject.md create mode 100644 packages/v4/docs/api/decorators/on.md create mode 100644 packages/v4/docs/api/decorators/provide.md create mode 100644 packages/v4/docs/api/decorators/read-write.md create mode 100644 packages/v4/docs/api/diagnostics/DIAGNOSTICS.md create mode 100644 packages/v4/docs/api/diagnostics/EVENTS.md create mode 100644 packages/v4/docs/api/diagnostics/index.md create mode 100644 packages/v4/docs/api/diagnostics/reportDiagnostic.md create mode 100644 packages/v4/docs/api/diagnostics/warn.md create mode 100644 packages/v4/docs/api/dom/breakpoints.md create mode 100644 packages/v4/docs/api/dom/domUpdate.md create mode 100644 packages/v4/docs/api/dom/emitExtendable.md create mode 100644 packages/v4/docs/api/dom/index.md create mode 100644 packages/v4/docs/api/dom/swap.md create mode 100644 packages/v4/docs/api/dom/watchAttributeNamespace.md create mode 100644 packages/v4/docs/api/dom/watchAttributes.md create mode 100644 packages/v4/docs/api/dom/whenDOMSettled.md create mode 100644 packages/v4/docs/api/html/data-component.md create mode 100644 packages/v4/docs/api/html/data-mount.md create mode 100644 packages/v4/docs/api/html/data-option.md create mode 100644 packages/v4/docs/api/html/data-ref.md create mode 100644 packages/v4/docs/api/html/index.md create mode 100644 packages/v4/docs/api/index.md create mode 100644 packages/v4/docs/api/instance-events.md create mode 100644 packages/v4/docs/api/instance-methods.md create mode 100644 packages/v4/docs/api/instance-properties.md create mode 100644 packages/v4/docs/api/methods-hooks-events.md create mode 100644 packages/v4/docs/api/methods-hooks-lifecycle.md create mode 100644 packages/v4/docs/api/methods-hooks-options.md create mode 100644 packages/v4/docs/api/methods-hooks-services.md create mode 100644 packages/v4/docs/api/registry/defineManifest.md create mode 100644 packages/v4/docs/api/registry/fromMetaGlob.md create mode 100644 packages/v4/docs/api/registry/fromWebpackContext.md create mode 100644 packages/v4/docs/api/registry/getInstance.md create mode 100644 packages/v4/docs/api/registry/getInstances.md create mode 100644 packages/v4/docs/api/registry/getMountedInstances.md create mode 100644 packages/v4/docs/api/registry/getUnmountedInstances.md create mode 100644 packages/v4/docs/api/registry/index.md create mode 100644 packages/v4/docs/api/registry/registerComponent.md create mode 100644 packages/v4/docs/api/registry/registerComponents.md create mode 100644 packages/v4/docs/api/registry/registerManifest.md create mode 100644 packages/v4/docs/api/scheduler/defaultScheduler.md create mode 100644 packages/v4/docs/api/scheduler/index.md create mode 100644 packages/v4/docs/api/scheduler/nextFrame.md create mode 100644 packages/v4/docs/api/scheduler/viewTransition.md create mode 100644 packages/v4/docs/api/services/createService.md create mode 100644 packages/v4/docs/api/services/createServiceMixin.md create mode 100644 packages/v4/docs/api/services/index.md create mode 100644 packages/v4/docs/api/services/mixins.md create mode 100644 packages/v4/docs/api/services/perTarget.md create mode 100644 packages/v4/docs/api/services/toggle.md create mode 100644 packages/v4/docs/api/services/until.md create mode 100644 packages/v4/docs/api/services/useBreakpoint.md create mode 100644 packages/v4/docs/api/services/useDrag.md create mode 100644 packages/v4/docs/api/services/useInView.md create mode 100644 packages/v4/docs/api/services/useKey.md create mode 100644 packages/v4/docs/api/services/useMediaQuery.md create mode 100644 packages/v4/docs/api/services/useMutation.md create mode 100644 packages/v4/docs/api/services/usePointer.md create mode 100644 packages/v4/docs/api/services/usePrefersReducedMotion.md create mode 100644 packages/v4/docs/api/services/useRaf.md create mode 100644 packages/v4/docs/api/services/useResize.md create mode 100644 packages/v4/docs/api/services/useScroll.md create mode 100644 packages/v4/docs/api/services/useScrollProgress.md create mode 100644 packages/v4/docs/api/services/useWindowScroll.md create mode 100644 packages/v4/docs/api/services/useWindowSize.md create mode 100644 packages/v4/docs/api/storage/createStorage.md create mode 100644 packages/v4/docs/api/storage/index.md create mode 100644 packages/v4/docs/api/storage/presets.md create mode 100644 packages/v4/docs/api/storage/providers.md create mode 100644 packages/v4/docs/api/test/index.md create mode 100644 packages/v4/docs/guide/concepts/attribute-grammar.md create mode 100644 packages/v4/docs/guide/concepts/mutation-engine.md create mode 100644 packages/v4/docs/guide/concepts/philosophy.md create mode 100644 packages/v4/docs/guide/concepts/the-registry.md create mode 100644 packages/v4/docs/guide/going-further/autoloading.md create mode 100644 packages/v4/docs/guide/going-further/handling-diagnostics.md create mode 100644 packages/v4/docs/guide/going-further/mount-strategies.md create mode 100644 packages/v4/docs/guide/going-further/scheduling-work.md create mode 100644 packages/v4/docs/guide/going-further/sharing-state.md create mode 100644 packages/v4/docs/guide/going-further/swapping-content.md create mode 100644 packages/v4/docs/guide/going-further/testing-components.md create mode 100644 packages/v4/docs/guide/going-further/typing-components.md create mode 100644 packages/v4/docs/guide/going-further/using-decorators.md create mode 100644 packages/v4/docs/guide/going-further/using-storage.md create mode 100644 packages/v4/docs/guide/index.md create mode 100644 packages/v4/docs/guide/introduction/installation.md create mode 100644 packages/v4/docs/guide/introduction/lifecycle-hooks.md create mode 100644 packages/v4/docs/guide/introduction/managing-components.md create mode 100644 packages/v4/docs/guide/introduction/managing-options.md create mode 100644 packages/v4/docs/guide/introduction/managing-refs.md create mode 100644 packages/v4/docs/guide/introduction/using-services.md create mode 100644 packages/v4/docs/guide/introduction/working-with-events.md create mode 100644 packages/v4/docs/guide/migration/v3-to-v4.md create mode 100644 packages/v4/docs/index.md create mode 100644 packages/v4/docs/public/logo.png create mode 100644 packages/v4/docs/utils/css.md create mode 100644 packages/v4/docs/utils/dom.md create mode 100644 packages/v4/docs/utils/easings.md create mode 100644 packages/v4/docs/utils/focus.md create mode 100644 packages/v4/docs/utils/history.md create mode 100644 packages/v4/docs/utils/index.md create mode 100644 packages/v4/docs/utils/is.md create mode 100644 packages/v4/docs/utils/load.md create mode 100644 packages/v4/docs/utils/math.md create mode 100644 packages/v4/docs/utils/motion.md create mode 100644 packages/v4/docs/utils/objects.md create mode 100644 packages/v4/docs/utils/scroll.md create mode 100644 packages/v4/docs/utils/strings.md create mode 100644 packages/v4/docs/utils/timing.md create mode 100644 packages/v4/docs/utils/transitions.md create mode 100644 packages/v4/docs/vite.config.ts diff --git a/.gitignore b/.gitignore index 907afb4a8..f02dfddd8 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,8 @@ packages/demo/dist/ .bench-report.json /packages/docs/.vitepress/cache /packages/docs/.vitepress/dist +/packages/v4/docs/.vitepress/cache +/packages/v4/docs/.vitepress/dist coverage/ /full.d.ts /index.d.ts diff --git a/.oxlintrc.json b/.oxlintrc.json index a8fde06f4..539e01f2e 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -114,7 +114,8 @@ "**/*.bench.ts", "**/__benchmarks__/**", "packages/v4/test/**", - "packages/v4/scripts/**" + "packages/v4/scripts/**", + "packages/v4/docs/**" ], "rules": { "complexity": "off", diff --git a/README.md b/README.md index 4eaa17e82..55f1c1ce2 100644 --- a/README.md +++ b/README.md @@ -53,13 +53,14 @@ Visit [js-toolkit.studiometa.dev](https://js-toolkit.studiometa.dev) to learn mo ## Packages -| Package | Description | -| ------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| [`@studiometa/js-toolkit`](./packages/js-toolkit/) | The framework and its utility functions. | -| [`@studiometa/eslint-plugin-js-toolkit`](./packages/eslint-plugin/) | Oxlint/ESLint rules enforcing the framework's best practices. | -| [`packages/v4`](./packages/v4/) | The v4 prototype, private and not published. | -| [`packages/docs`](./packages/docs/) | Sources of [js-toolkit.studiometa.dev](https://js-toolkit.studiometa.dev). | -| [`packages/demo`](./packages/demo/) | A playground application used during development. | +| Package | Description | +| ------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| [`@studiometa/js-toolkit`](./packages/js-toolkit/) | The framework and its utility functions. | +| [`@studiometa/eslint-plugin-js-toolkit`](./packages/eslint-plugin/) | Oxlint/ESLint rules enforcing the framework's best practices. | +| [`packages/v4`](./packages/v4/) | The v4 prototype, private and not published. | +| [`packages/docs`](./packages/docs/) | Sources of [js-toolkit.studiometa.dev](https://js-toolkit.studiometa.dev). | +| [`packages/v4/docs`](./packages/v4/docs/) | Sources of [js-toolkit-v4.studiometa.dev](https://js-toolkit-v4.studiometa.dev). | +| [`packages/demo`](./packages/demo/) | A playground application used during development. | ## Installation diff --git a/package-lock.json b/package-lock.json index d441558f8..af72a70c6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -5386,6 +5386,20 @@ "url": "https://github.com/sponsors/eemeli" } }, + "node_modules/@studiometa/tailwind-config": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@studiometa/tailwind-config/-/tailwind-config-3.0.0.tgz", + "integrity": "sha512-SauwUlgEcptxMMyy1TGL7Xod22654RncBT6whdefvUbgYw/46tnnXLDKVJ9vDb1QylWVkSxBUAUHzTov2AM9KQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "postcss": "^8.5.6", + "tailwindcss": "^4.1.16" + } + }, "node_modules/@studiometa/ui": { "version": "1.7.0", "resolved": "https://registry.npmjs.org/@studiometa/ui/-/ui-1.7.0.tgz", @@ -24784,18 +24798,6 @@ "tailwindcss": "4.2.4" } }, - "packages/demo/node_modules/@studiometa/tailwind-config": { - "version": "3.0.0", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=20.0.0" - }, - "peerDependencies": { - "postcss": "^8.5.6", - "tailwindcss": "^4.1.16" - } - }, "packages/demo/node_modules/@studiometa/webpack-config-preset-tailwindcss-4": { "version": "6.4.0", "dev": true, @@ -24827,18 +24829,6 @@ "vitepress-plugin-llms": "1.12.0" } }, - "packages/docs/node_modules/@studiometa/tailwind-config": { - "version": "3.0.0", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=20.0.0" - }, - "peerDependencies": { - "postcss": "^8.5.6", - "tailwindcss": "^4.1.16" - } - }, "packages/eslint-plugin": { "name": "@studiometa/eslint-plugin-js-toolkit", "version": "3.9.0", @@ -24883,13 +24873,19 @@ }, "devDependencies": { "@rollup/plugin-swc": "^0.4.1", + "@shikijs/vitepress-twoslash": "4.0.2", + "@studiometa/tailwind-config": "3.0.0", "@swc/core": "^1.15.47", + "@tailwindcss/vite": "4.2.2", "@vitest/browser": "4.1.10", "@vitest/browser-playwright": "4.1.10", "fast-glob": "3.3.3", "playwright": "^1.50.0", + "tailwindcss": "4.2.2", "tsdown": "0.22.14", "vite": "8.2.1", + "vitepress": "2.0.0-alpha.19", + "vitepress-plugin-llms": "1.12.0", "vitest": "4.1.10" } } diff --git a/package.json b/package.json index fd2839b87..a2b33a1d3 100644 --- a/package.json +++ b/package.json @@ -14,6 +14,9 @@ "docs:dev": "npm run dev --workspace=@studiometa/js-toolkit-docs", "docs:build": "npm run build --workspace=@studiometa/js-toolkit-docs", "docs:preview": "npm run preview --workspace=@studiometa/js-toolkit-docs", + "docs:v4:dev": "npm run docs:dev -w @studiometa/js-toolkit-v4", + "docs:v4:build": "npm run docs:build -w @studiometa/js-toolkit-v4", + "docs:v4:preview": "npm run docs:preview -w @studiometa/js-toolkit-v4", "build": "npm run build:js-toolkit && npm run build:v4 && npm run build:eslint-plugin", "build:js-toolkit": "npm run build -w @studiometa/js-toolkit", "build:v4": "npm run build -w @studiometa/js-toolkit-v4", diff --git a/packages/v4/docs/.vitepress/config.ts b/packages/v4/docs/.vitepress/config.ts new file mode 100644 index 000000000..431cd017e --- /dev/null +++ b/packages/v4/docs/.vitepress/config.ts @@ -0,0 +1,345 @@ +import { defineConfig } from 'vitepress'; +import { createTwoslashWithInlineCache } from '@shikijs/vitepress-twoslash/cache-inline'; + +const withTwoslashInlineCache = createTwoslashWithInlineCache(); + +export default withTwoslashInlineCache( + defineConfig({ + vite: { + build: { + chunkSizeWarningLimit: 600, + }, + }, + lang: 'en-US', + title: '@studiometa/js-toolkit v4', + description: + 'v4 of the JS Toolkit by Studio Meta: one registry, one mutation engine and one scheduler behind a data-attributes driven micro-framework.', + lastUpdated: true, + head: [['link', { rel: 'icon', type: 'image/x-icon', href: '/logo.png' }]], + markdown: { + // Explicitly load these languages for types hightlighting + languages: ['js', 'jsx', 'ts', 'tsx', 'bash', 'html'], + }, + themeConfig: { + outline: 'deep', + repo: 'studiometa/js-toolkit', + docsDir: 'packages/v4/docs', + lastUpdated: { + text: 'Last updated', + }, + editLinks: true, + editLinkText: 'Edit this page on GitHub', + sidebarDepth: 3, + footer: { + message: 'MIT Licensed', + copyright: 'Copyright © 2020–present Studio Meta', + }, + search: { + provider: 'local', + }, + socialLinks: [{ icon: 'github', link: 'https://github.com/studiometa/js-toolkit' }], + nav: [ + { text: 'Guide', link: '/guide/' }, + { text: 'API Reference', link: '/api/' }, + { text: 'Utils Reference', link: '/utils/' }, + { text: 'Concepts', link: '/guide/concepts/philosophy.html' }, + { + text: `v4`, + items: [ + { text: 'Migrating from v3', link: '/guide/migration/v3-to-v4.html' }, + { + text: 'Design document', + link: 'https://github.com/studiometa/js-toolkit/blob/main/packages/v4/DESIGN.md', + }, + { + text: 'Rationale', + link: 'https://github.com/studiometa/js-toolkit/blob/main/packages/v4/RATIONALE.md', + }, + { text: 'v3.x documentation', link: 'https://js-toolkit.studiometa.dev/' }, + ], + }, + ], + sidebar: { + '/guide/': getGuideSidebar(), + '/api/html/': getApiSidebar({ expanded: 'html' }), + '/api/registry/': getApiSidebar({ expanded: 'registry' }), + '/api/context/': getApiSidebar({ expanded: 'context' }), + '/api/services/': getApiSidebar({ expanded: 'services' }), + '/api/decorators/': getApiSidebar({ expanded: 'decorators' }), + '/api/scheduler/': getApiSidebar({ expanded: 'scheduler' }), + '/api/dom/': getApiSidebar({ expanded: 'dom' }), + '/api/storage/': getApiSidebar({ expanded: 'storage' }), + '/api/diagnostics/': getApiSidebar({ expanded: 'diagnostics' }), + '/api/test/': getApiSidebar({ expanded: 'test' }), + '/api/': getApiSidebar({ expanded: 'api' }), + '/utils/': getUtilsSidebar(), + }, + }, + }), +); + +function getGuideSidebar() { + return [ + { text: 'Getting Started', link: '/guide/' }, + { text: 'Installation', link: '/guide/introduction/installation.html' }, + { text: 'Components', link: '/guide/introduction/managing-components.html' }, + { text: 'Refs', link: '/guide/introduction/managing-refs.html' }, + { text: 'Options', link: '/guide/introduction/managing-options.html' }, + { text: 'Lifecycle', link: '/guide/introduction/lifecycle-hooks.html' }, + { text: 'Events', link: '/guide/introduction/working-with-events.html' }, + { text: 'Services', link: '/guide/introduction/using-services.html' }, + { + text: 'Going further', + collapsed: false, + items: [ + { text: 'Mount strategies', link: '/guide/going-further/mount-strategies.html' }, + { text: 'Autoloading', link: '/guide/going-further/autoloading.html' }, + { text: 'Shared state', link: '/guide/going-further/sharing-state.html' }, + { text: 'Decorators', link: '/guide/going-further/using-decorators.html' }, + { text: 'The scheduler', link: '/guide/going-further/scheduling-work.html' }, + { text: 'Swapping content', link: '/guide/going-further/swapping-content.html' }, + { text: 'Storage', link: '/guide/going-further/using-storage.html' }, + { text: 'Diagnostics', link: '/guide/going-further/handling-diagnostics.html' }, + { text: 'Testing', link: '/guide/going-further/testing-components.html' }, + { + text: 'TypeScript', + link: '/guide/going-further/typing-components.html', + keywords: ['types', 'typings', 'typescript', 'jsdoc'], + }, + ], + }, + { + text: 'Concepts', + collapsed: false, + items: [ + { text: 'Philosophy', link: '/guide/concepts/philosophy.html' }, + { text: 'The registry', link: '/guide/concepts/the-registry.html' }, + { text: 'The attribute grammar', link: '/guide/concepts/attribute-grammar.html' }, + { text: 'The mutation engine', link: '/guide/concepts/mutation-engine.html' }, + ], + }, + { + text: 'Migration', + collapsed: false, + items: [{ text: 'v3 → v4', link: '/guide/migration/v3-to-v4.html' }], + }, + ]; +} + +function getApiSidebar({ expanded = 'api' } = {}) { + return [ + { + text: 'Base class', + link: '/api/', + collapsed: expanded !== 'api', + items: getBaseSidebar(), + }, + { + text: 'HTML', + link: '/api/html/', + collapsed: expanded !== 'html', + items: getHtmlSidebar(), + }, + { + text: 'Registry', + link: '/api/registry/', + collapsed: expanded !== 'registry', + items: getRegistrySidebar(), + }, + { + text: 'Shared state', + link: '/api/context/', + collapsed: expanded !== 'context', + items: getContextSidebar(), + }, + { + text: 'Services', + link: '/api/services/', + collapsed: expanded !== 'services', + items: getServicesSidebar(), + }, + { + text: 'Decorators', + link: '/api/decorators/', + collapsed: expanded !== 'decorators', + items: getDecoratorsSidebar(), + }, + { + text: 'Scheduler', + link: '/api/scheduler/', + collapsed: expanded !== 'scheduler', + items: getSchedulerSidebar(), + }, + { + text: 'DOM', + link: '/api/dom/', + collapsed: expanded !== 'dom', + items: getDomSidebar(), + }, + { + text: 'Storage', + link: '/api/storage/', + collapsed: expanded !== 'storage', + items: getStorageSidebar(), + }, + { + text: 'Diagnostics', + link: '/api/diagnostics/', + collapsed: expanded !== 'diagnostics', + items: getDiagnosticsSidebar(), + }, + { + text: 'Testing', + link: '/api/test/', + collapsed: expanded !== 'test', + items: getTestSidebar(), + }, + ]; +} + +function getBaseSidebar() { + return [ + { text: 'Configuration', link: '/api/configuration.html' }, + { text: 'Lifecycle hooks', link: '/api/methods-hooks-lifecycle.html' }, + { text: 'Options hooks', link: '/api/methods-hooks-options.html' }, + { text: 'Events hooks', link: '/api/methods-hooks-events.html' }, + { text: 'Services hooks', link: '/api/methods-hooks-services.html' }, + { text: 'Instance properties', link: '/api/instance-properties.html' }, + { text: 'Instance methods', link: '/api/instance-methods.html' }, + { text: 'Instance events', link: '/api/instance-events.html' }, + ]; +} + +function getHtmlSidebar() { + return [ + { text: 'data-component', link: '/api/html/data-component.html' }, + { text: 'data-mount', link: '/api/html/data-mount.html' }, + { text: 'data-ref', link: '/api/html/data-ref.html' }, + { text: 'data-option-<​name>', link: '/api/html/data-option.html' }, + ]; +} + +function getRegistrySidebar() { + return [ + { text: 'registerComponent', link: '/api/registry/registerComponent.html' }, + { text: 'registerComponents', link: '/api/registry/registerComponents.html' }, + { text: 'registerManifest', link: '/api/registry/registerManifest.html' }, + { text: 'defineManifest', link: '/api/registry/defineManifest.html' }, + { text: 'fromMetaGlob', link: '/api/registry/fromMetaGlob.html' }, + { text: 'fromWebpackContext', link: '/api/registry/fromWebpackContext.html' }, + { text: 'getInstance', link: '/api/registry/getInstance.html' }, + { text: 'getInstances', link: '/api/registry/getInstances.html' }, + { text: 'getMountedInstances', link: '/api/registry/getMountedInstances.html' }, + { text: 'getUnmountedInstances', link: '/api/registry/getUnmountedInstances.html' }, + ]; +} + +function getContextSidebar() { + return [ + { text: 'createContext', link: '/api/context/createContext.html' }, + { text: 'signal', link: '/api/context/signal.html' }, + { text: 'provideContext', link: '/api/context/provideContext.html' }, + { text: 'provideRootContext', link: '/api/context/provideRootContext.html' }, + { text: 'injectContext', link: '/api/context/injectContext.html' }, + { text: 'injectContextSync', link: '/api/context/injectContextSync.html' }, + { text: 'subscribeContext', link: '/api/context/subscribeContext.html' }, + { text: 'createGroup', link: '/api/context/createGroup.html' }, + ]; +} + +function getServicesSidebar() { + return [ + { text: 'useRaf', link: '/api/services/useRaf.html' }, + { text: 'useScroll', link: '/api/services/useScroll.html' }, + { text: 'useWindowScroll', link: '/api/services/useWindowScroll.html' }, + { text: 'useScrollProgress', link: '/api/services/useScrollProgress.html' }, + { text: 'useResize', link: '/api/services/useResize.html' }, + { text: 'useWindowSize', link: '/api/services/useWindowSize.html' }, + { text: 'usePointer', link: '/api/services/usePointer.html' }, + { text: 'useDrag', link: '/api/services/useDrag.html' }, + { text: 'useKey', link: '/api/services/useKey.html' }, + { text: 'useInView', link: '/api/services/useInView.html' }, + { text: 'useMutation', link: '/api/services/useMutation.html' }, + { text: 'useBreakpoint', link: '/api/services/useBreakpoint.html' }, + { text: 'useMediaQuery', link: '/api/services/useMediaQuery.html' }, + { text: 'usePrefersReducedMotion', link: '/api/services/usePrefersReducedMotion.html' }, + { text: 'Mixins (with*)', link: '/api/services/mixins.html' }, + { text: 'createService', link: '/api/services/createService.html' }, + { text: 'createServiceMixin', link: '/api/services/createServiceMixin.html' }, + { text: 'perTarget', link: '/api/services/perTarget.html' }, + { text: 'toggle', link: '/api/services/toggle.html' }, + { text: 'until', link: '/api/services/until.html' }, + ]; +} + +function getDecoratorsSidebar() { + return [ + { text: '@component', link: '/api/decorators/component.html' }, + { text: '@on', link: '/api/decorators/on.html' }, + { text: '@provide', link: '/api/decorators/provide.html' }, + { text: '@inject', link: '/api/decorators/inject.html' }, + { text: '@children', link: '/api/decorators/children.html' }, + { text: '@read / @write', link: '/api/decorators/read-write.html' }, + ]; +} + +function getSchedulerSidebar() { + return [ + { text: 'defaultScheduler', link: '/api/scheduler/defaultScheduler.html' }, + { text: 'nextFrame', link: '/api/scheduler/nextFrame.html' }, + { text: 'viewTransition', link: '/api/scheduler/viewTransition.html' }, + ]; +} + +function getDomSidebar() { + return [ + { text: 'swap', link: '/api/dom/swap.html' }, + { text: 'domUpdate', link: '/api/dom/domUpdate.html' }, + { text: 'emitExtendable', link: '/api/dom/emitExtendable.html' }, + { text: 'watchAttributes', link: '/api/dom/watchAttributes.html' }, + { text: 'watchAttributeNamespace', link: '/api/dom/watchAttributeNamespace.html' }, + { text: 'whenDOMSettled', link: '/api/dom/whenDOMSettled.html' }, + { text: 'Breakpoints', link: '/api/dom/breakpoints.html' }, + ]; +} + +function getStorageSidebar() { + return [ + { text: 'createStorage', link: '/api/storage/createStorage.html' }, + { text: 'Presets', link: '/api/storage/presets.html' }, + { text: 'Providers', link: '/api/storage/providers.html' }, + ]; +} + +function getDiagnosticsSidebar() { + return [ + { text: 'EVENTS', link: '/api/diagnostics/EVENTS.html' }, + { text: 'DIAGNOSTICS', link: '/api/diagnostics/DIAGNOSTICS.html' }, + { text: 'reportDiagnostic', link: '/api/diagnostics/reportDiagnostic.html' }, + { text: 'warn', link: '/api/diagnostics/warn.html' }, + ]; +} + +function getTestSidebar() { + return [{ text: 'Test helpers', link: '/api/test/' }]; +} + +function getUtilsSidebar() { + return [ + { text: 'Overview', link: '/utils/' }, + { text: 'Type guards', link: '/utils/is.html' }, + { text: 'Strings', link: '/utils/strings.html' }, + { text: 'Math', link: '/utils/math.html' }, + { text: 'Easings', link: '/utils/easings.html' }, + { text: 'Motion', link: '/utils/motion.html' }, + { text: 'CSS', link: '/utils/css.html' }, + { text: 'Transitions', link: '/utils/transitions.html' }, + { text: 'DOM', link: '/utils/dom.html' }, + { text: 'Focus', link: '/utils/focus.html' }, + { text: 'Scroll', link: '/utils/scroll.html' }, + { text: 'History', link: '/utils/history.html' }, + { text: 'Loading', link: '/utils/load.html' }, + { text: 'Timing', link: '/utils/timing.html' }, + { text: 'Objects & random', link: '/utils/objects.html' }, + ]; +} diff --git a/packages/v4/docs/.vitepress/theme/components/Loader.vue b/packages/v4/docs/.vitepress/theme/components/Loader.vue new file mode 100644 index 000000000..68076ea6b --- /dev/null +++ b/packages/v4/docs/.vitepress/theme/components/Loader.vue @@ -0,0 +1,31 @@ + diff --git a/packages/v4/docs/.vitepress/theme/components/PreviewIframe.vue b/packages/v4/docs/.vitepress/theme/components/PreviewIframe.vue new file mode 100644 index 000000000..3270cfebd --- /dev/null +++ b/packages/v4/docs/.vitepress/theme/components/PreviewIframe.vue @@ -0,0 +1,67 @@ + + +