polaris-vue-elements 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,11 +6,51 @@ All notable changes to `polaris-vue-elements` are documented here. The format is
6
6
  minor releases may include breaking changes, which are always called out below.
7
7
 
8
8
  Wrapper and type changes follow `@shopify/polaris-types`, whose major version matches the
9
- [Polaris CDN](https://polaris-vue.vict0r.net/guide/quirks)
9
+ [Polaris CDN](https://polaris-vue-elements.dev/guide/quirks)
10
10
  major your app loads (`polaris-1.js`, `polaris-2.js`, …).
11
11
 
12
12
  ## [Unreleased]
13
13
 
14
+ ## [0.5.0] - 2026-11-09
15
+
16
+ Still generated from `@shopify/polaris-types` 2.0.0. No changes to the components.
17
+
18
+ ### Added
19
+
20
+ - `polaris-vue-elements/tokens.css` and `polaris-vue-elements/tokens.json`: the Polaris
21
+ CSS variables (`--p-color-*`, `--p-space-*`, `--p-border-radius-*`, …) for your app's
22
+ own layout CSS, extracted from the Polaris runtime with the build hash removed from
23
+ the names. Unofficial: values follow the CDN, and a daily job opens a pull request
24
+ when they change. Includes the `admin-next` theme, which applies under the class the
25
+ runtime puts on `<html>`.
26
+ See [CSS variables](https://polaris-vue-elements.dev/guide/css-variables).
27
+ - Docs: a "Best practices" section on 50 component pages, before the example. Each is
28
+ our own summary of Shopify's guidance for that component, with Vue snippets, and links
29
+ to the full section on shopify.dev. Components Shopify publishes no guidance for have
30
+ none.
31
+ - Docs: the whole site in Vietnamese, Korean, Simplified Chinese, Japanese, German, French,
32
+ Spanish, Hindi and Brazilian Portuguese (`/vi/`, `/ko/`, `/zh/`, `/ja/`, `/de/`, `/fr/`,
33
+ `/es/`, `/hi/`, `/pt/`), including every component page and Shopify's prop and slot
34
+ descriptions, with hreflang links between the languages.
35
+ - Docs: a redesigned homepage, a frosted-glass nav bar, a back-to-top button and thin,
36
+ rounded scrollbars.
37
+
38
+ ### Changed
39
+
40
+ - `sideEffects` in `package.json` is now `["*.css"]` instead of `false`, so bundlers keep
41
+ `import 'polaris-vue-elements/tokens.css'`. JavaScript still tree-shakes as before.
42
+
43
+ ## [0.4.2] - 2026-10-30
44
+
45
+ Still generated from `@shopify/polaris-types` 2.0.0. No changes to the components.
46
+
47
+ ### Changed
48
+
49
+ - The docs moved to [polaris-vue-elements.dev](https://polaris-vue-elements.dev). The old
50
+ `polaris-vue.vict0r.net` links redirect there. The package `homepage` now points to the new
51
+ domain, and the npm description and keywords mention Shopify apps.
52
+ - New guide: [Build a Shopify embedded app with Vue 3](https://polaris-vue-elements.dev/guide/shopify-embedded-app).
53
+
14
54
  ## [0.4.1] - 2026-10-29
15
55
 
16
56
  Still generated from `@shopify/polaris-types` 2.0.0.
@@ -107,7 +147,9 @@ Initial release: typed Vue 3 wrappers for the 59 Shopify Polaris web components
107
147
  `showOverlay()` / `hideOverlay()` / `toggleOverlay()`).
108
148
  - ESM build with bundled type declarations; `vue` ^3.5 as a peer dependency.
109
149
 
110
- [Unreleased]: https://github.com/HQCuong/polaris-vue/compare/v0.4.1...HEAD
150
+ [Unreleased]: https://github.com/HQCuong/polaris-vue/compare/v0.5.0...HEAD
151
+ [0.5.0]: https://github.com/HQCuong/polaris-vue/compare/v0.4.2...v0.5.0
152
+ [0.4.2]: https://github.com/HQCuong/polaris-vue/compare/v0.4.1...v0.4.2
111
153
  [0.4.1]: https://github.com/HQCuong/polaris-vue/compare/v0.4.0...v0.4.1
112
154
  [0.4.0]: https://github.com/HQCuong/polaris-vue/compare/v0.3.0...v0.4.0
113
155
  [0.3.0]: https://github.com/HQCuong/polaris-vue/compare/v0.2.0...v0.3.0
package/README.md CHANGED
@@ -1,15 +1,41 @@
1
- # polaris-vue-elements
1
+ <div align="center">
2
2
 
3
- Typed Vue 3 wrapper components for [Shopify Polaris web components](https://shopify.dev/docs/api/app-home/web-components) — the `s-*` custom elements used to build Shopify App Home (embedded admin) apps.
3
+ <sub>**English** | [Tiếng Việt](./i18n/vi/README.md) | [한국어](./i18n/ko/README.md) | [简体中文](./i18n/zh/README.md) | [日本語](./i18n/ja/README.md) | [Deutsch](./i18n/de/README.md) | [Français](./i18n/fr/README.md) | [Español](./i18n/es/README.md) | [हिन्दी](./i18n/hi/README.md) | [Português (Brasil)](./i18n/pt/README.md)</sub>
4
4
 
5
- **📖 Documentation: [polaris-vue.vict0r.net](https://polaris-vue.vict0r.net/)** — guides, known quirks, and live examples for all 62 components.
5
+ <br>
6
6
 
7
- The Polaris runtime itself is loaded from Shopify's CDN (the `polaris-2.js` stable channel receives compatible updates automatically). This library gives you an idiomatic, fully typed Vue surface on top of it:
7
+ <a href="https://polaris-vue-elements.dev/">
8
+ <img src="https://polaris-vue-elements.dev/og.png" alt="polaris-vue-elements: typed Vue 3 wrappers for Shopify Polaris web components" width="720">
9
+ </a>
8
10
 
9
- - **Typed props & events for all 62 components**, generated from Shopify's official Custom Elements Manifest (`@shopify/polaris-types`) — union-typed props like `variant`, autocomplete in templates, typed `@click`/`@aftershow` listeners.
10
- - **`v-model` on 17 form components** (`STextField`, `SCheckbox`, `SSelect`, `SChoiceList`, …) with the correct property/event pair for each.
11
- - **Imperative overlay control** — `SModal` exposes a typed `$el` (`ModalElement`) so `modal.value?.$el.showOverlay()` type-checks, alongside Polaris's declarative `commandFor`/`command` pattern.
12
- - **Degrades gracefully, never blocks** — unknown props pass through via `$attrs`, user-provided slots are forwarded verbatim, and brand-new Polaris components can always be used as raw `s-*` tags. A stale wrapper means missing types for new features, never broken existing ones.
11
+ <br>
12
+ <br>
13
+
14
+ [![npm version](https://img.shields.io/npm/v/polaris-vue-elements?color=008060&label=npm)](https://www.npmjs.com/package/polaris-vue-elements)
15
+ [![npm downloads](https://img.shields.io/npm/dm/polaris-vue-elements?color=008060)](https://www.npmjs.com/package/polaris-vue-elements)
16
+ [![CI](https://github.com/HQCuong/polaris-vue/actions/workflows/ci.yml/badge.svg)](https://github.com/HQCuong/polaris-vue/actions/workflows/ci.yml)
17
+ [![License: MIT](https://img.shields.io/npm/l/polaris-vue-elements?color=008060)](./LICENSE)
18
+
19
+ **[Documentation](https://polaris-vue-elements.dev/)** ·
20
+ [Getting started](https://polaris-vue-elements.dev/guide/getting-started) ·
21
+ [Components](https://polaris-vue-elements.dev/components/) ·
22
+ [Embedded app guide](https://polaris-vue-elements.dev/guide/shopify-embedded-app) ·
23
+ [Changelog](./CHANGELOG.md)
24
+
25
+ </div>
26
+
27
+ ---
28
+
29
+ Typed Vue 3 wrapper components for [Shopify Polaris web components](https://shopify.dev/docs/api/app-home/web-components): the `s-*` custom elements used to build Shopify App Home (embedded admin) apps.
30
+
31
+ The Polaris runtime itself loads from Shopify's CDN (the `polaris-2.js` stable channel receives compatible updates automatically). This library gives you an idiomatic, fully typed Vue surface on top of it.
32
+
33
+ ## Features
34
+
35
+ - **Typed props and events for all 62 components**, generated from Shopify's official Custom Elements Manifest (`@shopify/polaris-types`): union-typed props like `variant`, autocomplete in templates, typed `@click` / `@aftershow` listeners.
36
+ - **`v-model` on 17 form components** (`STextField`, `SCheckbox`, `SSelect`, `SChoiceList`, …), each mapped to its correct property/event pair.
37
+ - **Imperative overlay control.** `SModal` exposes a typed `$el` (`ModalElement`), so `modal.value?.$el.showOverlay()` type-checks, alongside Polaris's declarative `commandFor` / `command` pattern.
38
+ - **Degrades gracefully, never blocks.** Unknown props pass through via `$attrs`, slots are forwarded verbatim, and brand-new Polaris components can always be used as raw `s-*` tags. A stale wrapper means missing types for new features, never broken existing ones.
13
39
 
14
40
  ## Installation
15
41
 
@@ -21,15 +47,13 @@ Vue `^3.5` is a peer dependency.
21
47
 
22
48
  ### Runtime setup (required)
23
49
 
24
- The wrappers are presentational only — your host app must load the Polaris runtime from Shopify's CDN, and tell Vue that `s-*` tags are custom elements:
50
+ The wrappers are presentational only. Your host app loads the Polaris runtime from Shopify's CDN and tells Vue that `s-*` tags are custom elements:
25
51
 
26
52
  ```html
27
53
  <!-- index.html -->
28
54
  <script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script>
29
55
  ```
30
56
 
31
- `polaris-2.js` is Shopify's stable channel and brings the admin's new visual design. Apps still on `polaris-1.js` keep working — 2.0's component API is the same as 1.1 apart from a few additions. See [Polaris 2.0 and the new admin design](https://polaris-vue.vict0r.net/guide/getting-started#polaris-2-0-and-the-new-admin-design).
32
-
33
57
  ```ts
34
58
  // vite.config.ts
35
59
  vue({
@@ -41,7 +65,9 @@ vue({
41
65
  })
42
66
  ```
43
67
 
44
- ### Quick start
68
+ > **Note:** `polaris-2.js` is Shopify's stable channel and brings the admin's new visual design. Apps still on `polaris-1.js` keep working: 2.0's component API is the same as 1.1 apart from a few additions. See [Polaris 2.0 and the new admin design](https://polaris-vue-elements.dev/guide/getting-started#polaris-2-0-and-the-new-admin-design).
69
+
70
+ ## Quick start
45
71
 
46
72
  ```vue
47
73
  <script setup lang="ts">
@@ -57,11 +83,21 @@ const name = ref('')
57
83
  </template>
58
84
  ```
59
85
 
60
- Prefer writing Polaris's own `<s-button>` tags? Add `"types": ["polaris-vue-elements/elements"]` to your `tsconfig.json` and Volar / `vue-tsc` type-check raw `<s-*>` tags too (types only; `v-model` stays wrapper-only). See [Typing raw `<s-*>` tags](https://polaris-vue.vict0r.net/guide/getting-started#_7-typing-raw-s-tags-optional).
86
+ > **Tip:** prefer writing Polaris's own `<s-button>` tags? Add `"types": ["polaris-vue-elements/elements"]` to your `tsconfig.json`, and Volar / `vue-tsc` type-check raw `<s-*>` tags too (types only; `v-model` stays wrapper-only). See [Typing raw `<s-*>` tags](https://polaris-vue-elements.dev/guide/getting-started#_7-typing-raw-s-tags-optional).
87
+
88
+ ## Documentation
89
+
90
+ Everything lives at **[polaris-vue-elements.dev](https://polaris-vue-elements.dev/)**:
61
91
 
62
- Full documentation — guides, known quirks, and generated reference pages with live examples for all 62 components — is at **[polaris-vue.vict0r.net](https://polaris-vue.vict0r.net/)** (source in `docs/`, `npm run docs:dev` to run locally).
92
+ - [Getting started](https://polaris-vue-elements.dev/guide/getting-started): setup, `v-model`, overlays and typed raw tags.
93
+ - [Build a Shopify embedded app with Vue 3](https://polaris-vue-elements.dev/guide/shopify-embedded-app): App Bridge, authenticated `fetch`, navigation and the save bar.
94
+ - [Known quirks](https://polaris-vue-elements.dev/guide/quirks): Polaris behaviors verified in a real browser.
95
+ - [CSS variables](https://polaris-vue-elements.dev/guide/css-variables): Polaris design tokens (`--p-color-*`, `--p-space-*`, …) as an importable `polaris-vue-elements/tokens.css` for your own layout CSS.
96
+ - [Component reference](https://polaris-vue-elements.dev/components/): props, events, slots, best practices and live examples for all 62 components.
63
97
 
64
- ## Architecture
98
+ The site's source is in [`docs/`](./docs); run it locally with `npm run docs:dev`.
99
+
100
+ ## How it works
65
101
 
66
102
  Everything derivable from Shopify's manifest is machine-generated; human judgment lives in one small file.
67
103
 
@@ -74,7 +110,10 @@ src/lib/runtime/ ← createWrapper: one generic factory for all 62 comp
74
110
  src/lib/overrides.ts ← hand-written: v-model mappings only
75
111
  ```
76
112
 
77
- When Shopify ships a new Polaris version:
113
+ Drift-guard tests make forgetting impossible: CI fails if generated code is stale, if a manifest component lacks a wrapper, or if a new form-like component is missing a v-model override. A scheduled workflow ([`sync-polaris.yml`](.github/workflows/sync-polaris.yml)) opens a sync PR automatically when a new `@shopify/polaris-types` is published.
114
+
115
+ <details>
116
+ <summary><strong>Updating to a new Polaris version by hand</strong></summary>
78
117
 
79
118
  ```sh
80
119
  npm update @shopify/polaris-types
@@ -83,7 +122,7 @@ npm run docs:generate # regenerate component reference docs
83
122
  git diff # review, then note API changes in CHANGELOG.md
84
123
  ```
85
124
 
86
- Drift-guard tests make forgetting impossible: CI fails if generated code is stale, if a manifest component lacks a wrapper, or if a new form-like component is missing a v-model override. A scheduled GitHub Actions workflow (`sync-polaris.yml`) opens a sync PR automatically when a new `@shopify/polaris-types` is published.
125
+ </details>
87
126
 
88
127
  ## Development
89
128
 
@@ -101,16 +140,21 @@ npm run build:lib # build the publishable package into dist/
101
140
 
102
141
  ## Contributing
103
142
 
104
- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, ground rules and the pre-PR checklist.
143
+ Bug reports, docs fixes and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, ground rules and the pre-PR checklist, and the [Code of Conduct](./CODE_OF_CONDUCT.md). To report a vulnerability, see [SECURITY.md](./SECURITY.md).
105
144
 
106
145
  ## Releasing
107
146
 
108
- Releases are cut from `main` by pushing a version tag; [`release.yml`](.github/workflows/release.yml) does the rest (checks, `npm publish` with provenance via npm Trusted Publishing, and a GitHub Release whose notes come from `CHANGELOG.md`).
147
+ Releases are cut from `main` by pushing a version tag. [`release.yml`](.github/workflows/release.yml) does the rest: checks, `npm publish` with provenance via npm Trusted Publishing, and a GitHub Release whose notes come from `CHANGELOG.md`.
148
+
149
+ <details>
150
+ <summary><strong>Release steps (maintainers)</strong></summary>
109
151
 
110
152
  1. In [`CHANGELOG.md`](./CHANGELOG.md), move the `## [Unreleased]` entries under a new `## [x.y.z] - YYYY-MM-DD` heading and update the compare links at the bottom. The polaris-types sync PRs record new/removed components there automatically; add prop, slot and icon changes by hand (removals are breaking).
111
153
  2. `npm version x.y.z --no-git-tag-version`, commit both files, and push to `main`.
112
154
  3. `git tag vx.y.z && git push origin vx.y.z`. Tags with a pre-release suffix (e.g. `v0.3.0-rc.0`) publish under the `next` dist-tag.
113
155
 
156
+ </details>
157
+
114
158
  ## License
115
159
 
116
- [MIT](./LICENSE)
160
+ [MIT](./LICENSE). Not affiliated with or endorsed by Shopify.
package/package.json CHANGED
@@ -1,18 +1,24 @@
1
1
  {
2
2
  "name": "polaris-vue-elements",
3
- "version": "0.4.1",
4
- "description": "Typed Vue 3 wrapper components for Shopify Polaris web components.",
3
+ "version": "0.5.0",
4
+ "description": "Typed Vue 3 components for Shopify Polaris web components — build Shopify app UIs (App Home) in Vue with props, events and v-model.",
5
5
  "license": "MIT",
6
- "homepage": "https://polaris-vue.vict0r.net",
6
+ "homepage": "https://polaris-vue-elements.dev",
7
7
  "repository": {
8
8
  "type": "git",
9
9
  "url": "git+https://github.com/HQCuong/polaris-vue.git"
10
10
  },
11
11
  "keywords": [
12
12
  "shopify",
13
+ "shopify-app",
14
+ "shopify-polaris",
13
15
  "polaris",
16
+ "app-home",
14
17
  "web-components",
18
+ "custom-elements",
15
19
  "vue",
20
+ "vue3",
21
+ "typescript",
16
22
  "wrapper"
17
23
  ],
18
24
  "type": "module",
@@ -26,13 +32,19 @@
26
32
  },
27
33
  "./elements": {
28
34
  "types": "./dist/generated/elements.d.ts"
29
- }
35
+ },
36
+ "./tokens.css": "./tokens/tokens.css",
37
+ "./tokens.json": "./tokens/tokens.json"
30
38
  },
31
39
  "files": [
32
40
  "dist",
41
+ "tokens/tokens.css",
42
+ "tokens/tokens.json",
33
43
  "CHANGELOG.md"
34
44
  ],
35
- "sideEffects": false,
45
+ "sideEffects": [
46
+ "*.css"
47
+ ],
36
48
  "simple-git-hooks": {
37
49
  "pre-push": "npm run check"
38
50
  },
@@ -63,7 +75,7 @@
63
75
  "devDependencies": {
64
76
  "@shopify/polaris-types": "^2.0.0",
65
77
  "@tsconfig/node24": "^24.0.4",
66
- "@types/jsdom": "^28.0.3",
78
+ "@types/jsdom": "^30.0.0",
67
79
  "@types/node": "^24.13.3",
68
80
  "@vitejs/plugin-vue": "^6.0.8",
69
81
  "@vitest/eslint-plugin": "^1.6.23",
@@ -72,19 +84,20 @@
72
84
  "@vue/tsconfig": "^0.9.1",
73
85
  "eslint": "^10.7.0",
74
86
  "eslint-config-prettier": "^10.1.8",
75
- "eslint-plugin-oxlint": "~1.79.0",
76
- "eslint-plugin-vue": "~10.9.2",
87
+ "eslint-plugin-oxlint": "~1.90.0",
88
+ "eslint-plugin-vue": "~10.12.0",
77
89
  "jiti": "^2.7.0",
78
- "jsdom": "^29.1.1",
90
+ "jsdom": "^30.1.3",
79
91
  "npm-run-all2": "^9.0.2",
80
92
  "oxfmt": "^0.75.0",
81
- "oxlint": "~1.79.0",
93
+ "oxlint": "~1.90.0",
94
+ "postcss": "^8.5.32",
82
95
  "simple-git-hooks": "^2.13.1",
83
96
  "typescript": "~6.0.0",
84
97
  "vite": "^8.1.5",
85
98
  "vite-plugin-vue-devtools": "^8.1.5",
86
99
  "vitepress": "^1.6.4",
87
- "vitest": "^4.1.10",
100
+ "vitest": "^5.0.5",
88
101
  "vue": "^3.5.40",
89
102
  "vue-eslint-parser": "^10.4.1",
90
103
  "vue-tsc": "^3.3.7"
@@ -102,6 +115,10 @@
102
115
  "overrides": {
103
116
  "vitepress": {
104
117
  "vite": "^6.4.5"
118
+ },
119
+ "minimatch@>=7.0.0 <11.0.1": "^11.0.1",
120
+ "js-beautify": {
121
+ "glob": "^14.0.2"
105
122
  }
106
123
  }
107
124
  }