polaris-vue-elements 0.6.1 → 0.7.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/AGENTS.md +328 -0
- package/CHANGELOG.md +19 -1
- package/README.md +7 -1
- package/package.json +7 -2
package/AGENTS.md
ADDED
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
# polaris-vue-elements: guide for coding agents
|
|
2
|
+
|
|
3
|
+
> Working on this repository itself rather than using the package? Read [CONTRIBUTING.md](https://github.com/HQCuong/polaris-vue/blob/main/CONTRIBUTING.md) instead.
|
|
4
|
+
|
|
5
|
+
This file is for an AI agent writing a Vue 3 app with `polaris-vue-elements`. It ships in
|
|
6
|
+
the npm package (`node_modules/polaris-vue-elements/AGENTS.md`), so it matches the installed
|
|
7
|
+
version. Full docs: <https://polaris-vue-elements.dev>, also as Markdown for agents:
|
|
8
|
+
[`/llms.txt`](https://polaris-vue-elements.dev/llms.txt) (index),
|
|
9
|
+
[`/llms-full.txt`](https://polaris-vue-elements.dev/llms-full.txt) (every page in one file)
|
|
10
|
+
and a `.md` copy of every page (`https://polaris-vue-elements.dev/components/s-button.md`).
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
- Typed Vue 3 wrapper components for Shopify's
|
|
15
|
+
[Polaris web components](https://shopify.dev/docs/api/app-home/web-components), the
|
|
16
|
+
`s-*` custom elements used to build Shopify App Home (embedded admin) apps. It is a
|
|
17
|
+
community project, not made by Shopify.
|
|
18
|
+
- Each wrapper `S<Name>` renders one Polaris element `<s-name>`: `SButton` is `<s-button>`,
|
|
19
|
+
`STextField` is `<s-text-field>`, `SChoiceList` is `<s-choice-list>`. Props, events and
|
|
20
|
+
slots are generated from Shopify's Custom Elements Manifest (`@shopify/polaris-types`).
|
|
21
|
+
- The wrappers are presentational only. The Polaris runtime that defines the elements loads
|
|
22
|
+
from Shopify's CDN; this package does not include it.
|
|
23
|
+
- `polaris-vue-elements/app-bridge` adds Vue counterparts of the `@shopify/app-bridge-react`
|
|
24
|
+
components and hook (beta, see below).
|
|
25
|
+
|
|
26
|
+
Shopify's docs are the source of truth for what each Polaris component does. Shopify's
|
|
27
|
+
examples use React or plain HTML; translate them to the wrappers as described here.
|
|
28
|
+
|
|
29
|
+
## Install
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
npm install polaris-vue-elements
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Peer dependencies: `vue` `^3.5.0`, and optionally `@shopify/app-bridge-types` (only for
|
|
36
|
+
`polaris-vue-elements/app-bridge` and typing the `shopify` global):
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
npm install -D @shopify/app-bridge-types
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Required setup
|
|
43
|
+
|
|
44
|
+
1. Load the Polaris runtime in `index.html`. It registers the `<s-*>` elements globally:
|
|
45
|
+
|
|
46
|
+
```html
|
|
47
|
+
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script>
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`polaris-2.js` is the recommended stable channel. `polaris-2.0.js` pins a release,
|
|
51
|
+
`polaris-1.js` is the previous 1.x channel, and the wrappers work with both majors.
|
|
52
|
+
The runtime updates independently of this package's version.
|
|
53
|
+
|
|
54
|
+
2. Tell Vue's compiler that `s-*` tags are custom elements:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
// vite.config.ts
|
|
58
|
+
vue({
|
|
59
|
+
template: {
|
|
60
|
+
compilerOptions: {
|
|
61
|
+
isCustomElement: (tag) => tag.startsWith('s-'),
|
|
62
|
+
},
|
|
63
|
+
},
|
|
64
|
+
})
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
If you write raw App Bridge `ui-*` tags (`<ui-title-bar>`), use
|
|
68
|
+
`tag.startsWith('s-') || tag.startsWith('ui-')`. The `polaris-vue-elements/app-bridge`
|
|
69
|
+
components do not need it.
|
|
70
|
+
|
|
71
|
+
3. In a Shopify embedded app, also add the App Bridge script and your app's client ID to
|
|
72
|
+
`<head>`:
|
|
73
|
+
|
|
74
|
+
```html
|
|
75
|
+
<meta name="shopify-api-key" content="%VITE_SHOPIFY_API_KEY%" />
|
|
76
|
+
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
|
|
77
|
+
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
App Bridge features only work when the app is opened from the Shopify admin.
|
|
81
|
+
|
|
82
|
+
## Imports
|
|
83
|
+
|
|
84
|
+
| Import | What you get |
|
|
85
|
+
| --- | --- |
|
|
86
|
+
| `polaris-vue-elements` | Every `S*` wrapper, plus types such as `ModalProps` (for `SModal`) |
|
|
87
|
+
| `polaris-vue-elements/app-bridge` | `Modal`, `SaveBar`, `TitleBar`, `AppWindow`, `NavMenu`, `useAppBridge()`, every type from `@shopify/app-bridge-types`, and `ModalProps`, `SaveBarProps`, `AppWindowProps`, `TitleBarProps`, `NavMenuProps` |
|
|
88
|
+
| `polaris-vue-elements/elements` | Types only: types raw `<s-*>` tags in templates (opt in through `tsconfig.json` `types`) |
|
|
89
|
+
| `polaris-vue-elements/app-bridge/elements` | Types only: types raw `ui-modal`, `ui-save-bar`, `ui-title-bar`, `ui-nav-menu`, `s-app-window`, `s-app-nav` |
|
|
90
|
+
| `polaris-vue-elements/tokens.css` | Polaris CSS variables (`--p-color-*`, `--p-space-*`, …) for your own CSS |
|
|
91
|
+
| `polaris-vue-elements/tokens.json` | The same variables as JSON |
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
import { SButton, STextField } from 'polaris-vue-elements'
|
|
95
|
+
import { Modal, TitleBar, useAppBridge } from 'polaris-vue-elements/app-bridge'
|
|
96
|
+
import 'polaris-vue-elements/tokens.css' // once, for example in main.ts
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Both entries export a `ModalProps`; rename one when you import both:
|
|
100
|
+
`import type { ModalProps as AppBridgeModalProps } from 'polaris-vue-elements/app-bridge'`.
|
|
101
|
+
|
|
102
|
+
## Props, events and v-model
|
|
103
|
+
|
|
104
|
+
- Pass props in camelCase, as the reference lists them: `accessibilityLabel`,
|
|
105
|
+
`commandFor`, `inlineSize`. Unknown props and attributes (`class`, `style`, `aria-*`)
|
|
106
|
+
pass through to the element.
|
|
107
|
+
- Bind number-typed props: `:rows="3"`, not `rows="3"`.
|
|
108
|
+
- Events are the element's DOM events, by their lowercase names: `@click`, `@input`,
|
|
109
|
+
`@change`, `@focus`, `@blur`, `@aftershow`, `@afterhide`. The listener gets the DOM
|
|
110
|
+
event; read values from `$event.target`.
|
|
111
|
+
- `v-model` works on the form wrappers listed with a binding in the component list below.
|
|
112
|
+
Each maps to its own property and event: text-like fields bind `value` / `input`,
|
|
113
|
+
`SCheckbox` and `SSwitch` bind `checked` / `change`, `SSelect` binds `value` / `change`,
|
|
114
|
+
`SChoiceList` binds `values` / `change`.
|
|
115
|
+
|
|
116
|
+
```vue
|
|
117
|
+
<STextField v-model="name" label="Name" />
|
|
118
|
+
<!-- is equivalent to -->
|
|
119
|
+
<STextField :value="name" @input="name = $event.target.value" label="Name" />
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
- Named slots use Vue's slot syntax: `<template #primary-action>…</template>`.
|
|
123
|
+
- Raw `<s-*>` tags work too (and are the way to use a Polaris component that has no
|
|
124
|
+
wrapper yet), but have no `v-model`: bind `:value` and listen for `@input` / `@change`.
|
|
125
|
+
|
|
126
|
+
## Overlays
|
|
127
|
+
|
|
128
|
+
`SModal` (and popovers) open declaratively with `commandFor` / `command` on a button, or
|
|
129
|
+
imperatively through the element on a template ref:
|
|
130
|
+
|
|
131
|
+
```vue
|
|
132
|
+
<script setup lang="ts">
|
|
133
|
+
import { useTemplateRef } from 'vue'
|
|
134
|
+
import { SButton, SModal, SText } from 'polaris-vue-elements'
|
|
135
|
+
|
|
136
|
+
const modal = useTemplateRef<InstanceType<typeof SModal>>('modal')
|
|
137
|
+
</script>
|
|
138
|
+
|
|
139
|
+
<template>
|
|
140
|
+
<SButton commandFor="demo-modal" command="--show">Open</SButton>
|
|
141
|
+
<SButton @click="modal?.$el.showOverlay()">Open from code</SButton>
|
|
142
|
+
|
|
143
|
+
<SModal ref="modal" id="demo-modal" heading="Demo modal">
|
|
144
|
+
<SText>Modal content.</SText>
|
|
145
|
+
<template #primary-action>
|
|
146
|
+
<SButton variant="primary" commandFor="demo-modal" command="--hide">Close</SButton>
|
|
147
|
+
</template>
|
|
148
|
+
</SModal>
|
|
149
|
+
</template>
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
In an embedded app, `shopify.modal.show('demo-modal')` / `hide(id)` also control an
|
|
153
|
+
`SModal` by its `id`.
|
|
154
|
+
|
|
155
|
+
## Known quirks
|
|
156
|
+
|
|
157
|
+
Browser-verified behaviors of the Polaris elements
|
|
158
|
+
([details](https://polaris-vue-elements.dev/guide/quirks.md)):
|
|
159
|
+
|
|
160
|
+
1. `SBanner` renders empty without default-slot content; a `heading` alone is not enough.
|
|
161
|
+
2. `SModal`'s `primary-action` slot accepts only one button with `variant="primary"`, and
|
|
162
|
+
`secondary-actions` only buttons with `variant` `secondary` or `auto`. Anything else is
|
|
163
|
+
dropped silently.
|
|
164
|
+
3. Number-typed props must be bound (`:rows="3"`); `vue-tsc` rejects string literals.
|
|
165
|
+
4. Slot assignment happens once, when the element connects. To move a child to another
|
|
166
|
+
named slot, re-create it (`:key` or `v-if`) instead of changing `slot` reactively.
|
|
167
|
+
5. The runtime is versioned on the CDN, separately from this package. A stale wrapper
|
|
168
|
+
lacks types for newer features but does not break; new components work as raw tags.
|
|
169
|
+
|
|
170
|
+
## CSS
|
|
171
|
+
|
|
172
|
+
- Polaris components style themselves inside their shadow roots. Use their props
|
|
173
|
+
(`tone`, `variant`, `padding`, …) to change them; CSS variables cannot restyle them.
|
|
174
|
+
- Prefer `SStack`, `SGrid` and `SBox` for layout; they take Polaris spacing and border
|
|
175
|
+
values as props.
|
|
176
|
+
- For your own elements, import `polaris-vue-elements/tokens.css` and use
|
|
177
|
+
`var(--p-space-400)`, `var(--p-color-bg-surface)` and so on. You need the import inside
|
|
178
|
+
the Shopify admin too: the runtime only defines hashed names. The list is unofficial
|
|
179
|
+
(extracted from the runtime), so a name can change if Shopify renames it.
|
|
180
|
+
|
|
181
|
+
## SSR
|
|
182
|
+
|
|
183
|
+
- The wrappers render the `s-*` element with attribute-mapped props as attributes. Props
|
|
184
|
+
that have no HTML attribute are set as DOM properties after mount, so they are not in
|
|
185
|
+
server-rendered HTML.
|
|
186
|
+
- `useAppBridge()` on the server returns an object that throws when you read any property.
|
|
187
|
+
Call App Bridge APIs from `onMounted()` or event handlers, not during `setup`.
|
|
188
|
+
- `Modal` does not render its content during SSR or before `ui-modal` is defined.
|
|
189
|
+
|
|
190
|
+
## App Bridge (beta)
|
|
191
|
+
|
|
192
|
+
The `polaris-vue-elements/app-bridge` components are new and **have not yet been tested in
|
|
193
|
+
a live Shopify admin**; their API may change in a minor release while in beta. They mirror
|
|
194
|
+
`@shopify/app-bridge-react` 4.3.0 and need only the App Bridge script, not React.
|
|
195
|
+
|
|
196
|
+
| Vue export | Element | Notes |
|
|
197
|
+
| --- | --- | --- |
|
|
198
|
+
| `Modal` | `ui-modal` | `v-model:open`, `@show` / `@hide`; a `TitleBar` child sets its header and footer; `src` loads a route instead |
|
|
199
|
+
| `SaveBar` | `ui-save-bar` | `v-model:open`; the `variant="primary"` button is Save, the one without a variant is Discard |
|
|
200
|
+
| `TitleBar` | `ui-title-bar` | `title` plus `<button>` / `<a>` children |
|
|
201
|
+
| `AppWindow` | `s-app-window` | fullscreen window; `src` is required; `v-model:open` |
|
|
202
|
+
| `NavMenu` | `ui-nav-menu` | the older nav element; Shopify now documents raw `<s-app-nav>` with `<s-link>` children |
|
|
203
|
+
| `useAppBridge()` | the `shopify` global | typed as `ShopifyGlobal` |
|
|
204
|
+
|
|
205
|
+
- Mapping from React: `open={open}` is `v-model:open`, `onShow` / `onHide` are `@show` /
|
|
206
|
+
`@hide`, `children` is the default slot, and a `ref` to the element is a template ref's
|
|
207
|
+
`$el`.
|
|
208
|
+
- Shopify's migration guide describes the current App Bridge elements: `<s-modal>`
|
|
209
|
+
(`SModal`) for inline content, `<s-app-window>` for modals with separate routes, and the
|
|
210
|
+
title bar configured through `<s-page>` (`SPage`) slots. The `ui-*` components mirror
|
|
211
|
+
the elements that `@shopify/app-bridge-react` still provides.
|
|
212
|
+
- The `shopify` global works directly too: `shopify.toast.show('Saved')`,
|
|
213
|
+
`shopify.loading(true)`, `shopify.resourcePicker({ type: 'product' })`.
|
|
214
|
+
- App Bridge adds an ID token to `fetch()` calls to your app's own domain, so a plain
|
|
215
|
+
`fetch('/api/…')` is authenticated. Call `shopify.idToken()` yourself only where that
|
|
216
|
+
does not apply, such as a WebSocket. Validate tokens on your server.
|
|
217
|
+
- A `<form data-save-bar>` shows the admin save bar on unsaved changes without any
|
|
218
|
+
component.
|
|
219
|
+
|
|
220
|
+
## Component reference
|
|
221
|
+
|
|
222
|
+
For one component's props (with types), events, methods and slots, read
|
|
223
|
+
`https://polaris-vue-elements.dev/components/<tag>.md`, for example
|
|
224
|
+
`https://polaris-vue-elements.dev/components/s-text-field.md`. Shopify's own reference is at
|
|
225
|
+
<https://shopify.dev/docs/api/app-home/polaris-web-components>.
|
|
226
|
+
|
|
227
|
+
<!-- BEGIN GENERATED: components -->
|
|
228
|
+
|
|
229
|
+
All 62 wrappers, grouped the way Shopify's reference groups them. Reference for each: `https://polaris-vue-elements.dev/components/<tag>.md`.
|
|
230
|
+
|
|
231
|
+
### Actions
|
|
232
|
+
|
|
233
|
+
| Component | Tag | v-model | What it is |
|
|
234
|
+
| --- | --- | --- | --- |
|
|
235
|
+
| `SButton` | `<s-button>` | | Triggers an action or navigates, with primary, secondary and tertiary variants, icons and a loading state. |
|
|
236
|
+
| `SButtonGroup` | `<s-button-group>` | | Lays out a set of related buttons together, such as a primary action and its secondary actions. |
|
|
237
|
+
| `SClickable` | `<s-clickable>` | | Makes any content clickable as a button or link, without imposing button styling. |
|
|
238
|
+
| `SClickableChip` | `<s-clickable-chip>` | | An interactive chip that can be clicked, followed as a link or removed — useful for filters and applied tags. |
|
|
239
|
+
| `SLink` | `<s-link>` | | A text link that navigates to another page or URL, or runs a command. |
|
|
240
|
+
| `SMenu` | `<s-menu>` | | A list of actions shown in an overlay, opened from a button. |
|
|
241
|
+
| `SPressButton` | `<s-press-button>` | | A toggle button that stays pressed or unpressed, for turning a mode or filter on and off. |
|
|
242
|
+
|
|
243
|
+
### Feedback and status
|
|
244
|
+
|
|
245
|
+
| Component | Tag | v-model | What it is |
|
|
246
|
+
| --- | --- | --- | --- |
|
|
247
|
+
| `SBadge` | `<s-badge>` | | A small label that shows the status of an object, such as an order, payment or fulfillment. |
|
|
248
|
+
| `SBanner` | `<s-banner>` | | A prominent message that surfaces important information, warnings or errors at the top of a page or section. |
|
|
249
|
+
| `SEmptyState` | `<s-empty-state>` | | Explains why a view has no content yet and points merchants to the first action to take. |
|
|
250
|
+
| `SProgress` | `<s-progress>` | | A progress bar that shows how far a task has advanced toward its maximum value. |
|
|
251
|
+
| `SSpinner` | `<s-spinner>` | | An animated indicator that content or an action is loading. |
|
|
252
|
+
|
|
253
|
+
### Forms
|
|
254
|
+
|
|
255
|
+
| Component | Tag | v-model | What it is |
|
|
256
|
+
| --- | --- | --- | --- |
|
|
257
|
+
| `SCheckbox` | `<s-checkbox>` | `checked` / `change` | A single checkbox for a yes/no choice, bound to its checked state with v-model. |
|
|
258
|
+
| `SChoice` | `<s-choice>` | | One option inside a choice list. |
|
|
259
|
+
| `SChoiceList` | `<s-choice-list>` | `values` / `change` | A group of radio buttons or checkboxes for picking one or several options. |
|
|
260
|
+
| `SColorField` | `<s-color-field>` | `value` / `input` | A text input for entering a color value, with an optional alpha channel. |
|
|
261
|
+
| `SColorPicker` | `<s-color-picker>` | `value` / `input` | A visual control for picking a color. |
|
|
262
|
+
| `SDateField` | `<s-date-field>` | `value` / `input` | An input for entering a date. |
|
|
263
|
+
| `SDatePicker` | `<s-date-picker>` | `value` / `input` | A calendar for selecting a single date or a date range. |
|
|
264
|
+
| `SDropZone` | `<s-drop-zone>` | `value` / `input` | A file upload area that accepts files by drag and drop or from a file picker. |
|
|
265
|
+
| `SEmailField` | `<s-email-field>` | `value` / `input` | A text input for email addresses. |
|
|
266
|
+
| `SMoneyField` | `<s-money-field>` | `value` / `input` | A numeric input for monetary amounts. |
|
|
267
|
+
| `SNumberField` | `<s-number-field>` | `value` / `input` | A numeric input with optional minimum, maximum and step. |
|
|
268
|
+
| `SOption` | `<s-option>` | | One option inside a select. |
|
|
269
|
+
| `SOptionGroup` | `<s-option-group>` | | Groups related options inside a select under a shared label. |
|
|
270
|
+
| `SPasswordField` | `<s-password-field>` | `value` / `input` | A text input for passwords that masks what is typed. |
|
|
271
|
+
| `SSearchField` | `<s-search-field>` | `value` / `input` | A text input for search queries. |
|
|
272
|
+
| `SSelect` | `<s-select>` | `value` / `change` | A dropdown for choosing one option from a list. |
|
|
273
|
+
| `SSwitch` | `<s-switch>` | `checked` / `change` | A toggle switch that turns a setting on or off. |
|
|
274
|
+
| `STextArea` | `<s-text-area>` | `value` / `input` | A multi-line text input for longer content such as notes or descriptions. |
|
|
275
|
+
| `STextField` | `<s-text-field>` | `value` / `input` | A single-line text input with label, placeholder, validation error and help text. |
|
|
276
|
+
| `SUrlField` | `<s-url-field>` | `value` / `input` | A text input for web addresses. |
|
|
277
|
+
|
|
278
|
+
### Layout and structure
|
|
279
|
+
|
|
280
|
+
| Component | Tag | v-model | What it is |
|
|
281
|
+
| --- | --- | --- | --- |
|
|
282
|
+
| `SBox` | `<s-box>` | | A generic container for padding, background, border, radius and sizing. |
|
|
283
|
+
| `SDivider` | `<s-divider>` | | A horizontal or vertical line that separates content. |
|
|
284
|
+
| `SGrid` | `<s-grid>` | | A CSS grid container for laying out content in rows and columns. |
|
|
285
|
+
| `SGridItem` | `<s-grid-item>` | | A child of a grid that can span several columns or rows. |
|
|
286
|
+
| `SListItem` | `<s-list-item>` | | One item inside an ordered or unordered list. |
|
|
287
|
+
| `SOrderedList` | `<s-ordered-list>` | | A numbered list. |
|
|
288
|
+
| `SPage` | `<s-page>` | | The top-level page layout, with a heading, page actions and content areas. |
|
|
289
|
+
| `SQueryContainer` | `<s-query-container>` | | Turns an element into a size container so its children can adapt to its width with container queries. |
|
|
290
|
+
| `SScrollBox` | `<s-scroll-box>` | | A container that scrolls its content when it overflows. |
|
|
291
|
+
| `SSection` | `<s-section>` | | Groups related content, with an optional heading, subheading and actions. |
|
|
292
|
+
| `SStack` | `<s-stack>` | | Arranges its children in a row or column with consistent spacing and alignment. |
|
|
293
|
+
| `STable` | `<s-table>` | | A table for structured data, with optional pagination, a loading state and a list layout on small screens. |
|
|
294
|
+
| `STableBody` | `<s-table-body>` | | The body of a table, holding its data rows. |
|
|
295
|
+
| `STableCell` | `<s-table-cell>` | | One cell in a table row. |
|
|
296
|
+
| `STableHeader` | `<s-table-header>` | | One column header in a table. |
|
|
297
|
+
| `STableHeaderRow` | `<s-table-header-row>` | | The row of column headers at the top of a table. |
|
|
298
|
+
| `STableRow` | `<s-table-row>` | | One row of data in a table. |
|
|
299
|
+
| `SUnorderedList` | `<s-unordered-list>` | | A bulleted list. |
|
|
300
|
+
|
|
301
|
+
### Media and visuals
|
|
302
|
+
|
|
303
|
+
| Component | Tag | v-model | What it is |
|
|
304
|
+
| --- | --- | --- | --- |
|
|
305
|
+
| `SAvatar` | `<s-avatar>` | | Shows a person's or business's image, or their initials when there is no image. |
|
|
306
|
+
| `SIcon` | `<s-icon>` | | Displays an icon from the Polaris icon set by name. |
|
|
307
|
+
| `SImage` | `<s-image>` | | Displays an image with control over aspect ratio, fit, borders and lazy loading. |
|
|
308
|
+
| `SThumbnail` | `<s-thumbnail>` | | A small, fixed-size preview image of a product or file. |
|
|
309
|
+
|
|
310
|
+
### Overlays
|
|
311
|
+
|
|
312
|
+
| Component | Tag | v-model | What it is |
|
|
313
|
+
| --- | --- | --- | --- |
|
|
314
|
+
| `SModal` | `<s-modal>` | | A dialog overlay for focused tasks and confirmations, opened by a command or a method call. |
|
|
315
|
+
| `SPopover` | `<s-popover>` | | Floating content anchored to the button that opens it. |
|
|
316
|
+
|
|
317
|
+
### Typography and content
|
|
318
|
+
|
|
319
|
+
| Component | Tag | v-model | What it is |
|
|
320
|
+
| --- | --- | --- | --- |
|
|
321
|
+
| `SChip` | `<s-chip>` | | A static label for a tag or attribute, optionally removable. |
|
|
322
|
+
| `SHeading` | `<s-heading>` | | A heading that titles a page section. |
|
|
323
|
+
| `SNumber` | `<s-number>` | | Displays a number you have already formatted, with typography, tone and color styling. |
|
|
324
|
+
| `SParagraph` | `<s-paragraph>` | | A block of body text. |
|
|
325
|
+
| `SText` | `<s-text>` | | Inline text with tone, weight and emphasis styling. |
|
|
326
|
+
| `STooltip` | `<s-tooltip>` | | A short label that appears when another element is hovered or focused. |
|
|
327
|
+
|
|
328
|
+
<!-- END GENERATED: components -->
|
package/CHANGELOG.md
CHANGED
|
@@ -11,6 +11,23 @@ major your app loads (`polaris-1.js`, `polaris-2.js`, …).
|
|
|
11
11
|
|
|
12
12
|
## [Unreleased]
|
|
13
13
|
|
|
14
|
+
## [0.7.0] - 2026-11-17
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- `AGENTS.md` in the npm package (`node_modules/polaris-vue-elements/AGENTS.md`): a compact
|
|
19
|
+
guide for AI coding agents writing a Vue 3 app with the library, with setup, imports,
|
|
20
|
+
`v-model`, SSR and App Bridge notes, the known quirks and a generated list of every
|
|
21
|
+
component with its tag.
|
|
22
|
+
- Docs: [`/llms.txt`](https://polaris-vue-elements.dev/llms.txt),
|
|
23
|
+
[`/llms-full.txt`](https://polaris-vue-elements.dev/llms-full.txt) and a Markdown copy of
|
|
24
|
+
every English page (`/components/s-button.md`), linked from each page with
|
|
25
|
+
`<link rel="alternate" type="text/markdown">`.
|
|
26
|
+
- Docs: a [Using AI coding agents](https://polaris-vue-elements.dev/guide/ai-agents) guide,
|
|
27
|
+
in all eleven languages.
|
|
28
|
+
- Russian docs ([`/ru/`](https://polaris-vue-elements.dev/ru/)): every page of the site, and
|
|
29
|
+
Russian copies of the README, CONTRIBUTING, SECURITY and CODE_OF_CONDUCT in `i18n/ru/`.
|
|
30
|
+
|
|
14
31
|
## [0.6.1] - 2026-11-16
|
|
15
32
|
|
|
16
33
|
### Changed
|
|
@@ -202,7 +219,8 @@ Initial release: typed Vue 3 wrappers for the 59 Shopify Polaris web components
|
|
|
202
219
|
`showOverlay()` / `hideOverlay()` / `toggleOverlay()`).
|
|
203
220
|
- ESM build with bundled type declarations; `vue` ^3.5 as a peer dependency.
|
|
204
221
|
|
|
205
|
-
[Unreleased]: https://github.com/HQCuong/polaris-vue/compare/v0.
|
|
222
|
+
[Unreleased]: https://github.com/HQCuong/polaris-vue/compare/v0.7.0...HEAD
|
|
223
|
+
[0.7.0]: https://github.com/HQCuong/polaris-vue/compare/v0.6.1...v0.7.0
|
|
206
224
|
[0.6.1]: https://github.com/HQCuong/polaris-vue/compare/v0.6.0...v0.6.1
|
|
207
225
|
[0.6.0]: https://github.com/HQCuong/polaris-vue/compare/v0.5.0...v0.6.0
|
|
208
226
|
[0.5.0]: https://github.com/HQCuong/polaris-vue/compare/v0.4.2...v0.5.0
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
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>
|
|
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) | [Русский](./i18n/ru/README.md)</sub>
|
|
4
4
|
|
|
5
5
|
<br>
|
|
6
6
|
|
|
@@ -98,6 +98,12 @@ Everything lives at **[polaris-vue-elements.dev](https://polaris-vue-elements.de
|
|
|
98
98
|
|
|
99
99
|
The site's source is in [`docs/`](./docs); run it locally with `npm run docs:dev`.
|
|
100
100
|
|
|
101
|
+
## Using with AI coding agents
|
|
102
|
+
|
|
103
|
+
The package ships [`AGENTS.md`](./AGENTS.md), a guide for AI coding agents that write Vue code with this library. After install it is at `node_modules/polaris-vue-elements/AGENTS.md`, so it matches the version you have; point your project's agent instructions at it.
|
|
104
|
+
|
|
105
|
+
The docs are also published as Markdown: [`llms.txt`](https://polaris-vue-elements.dev/llms.txt) (an index), [`llms-full.txt`](https://polaris-vue-elements.dev/llms-full.txt) (every English page in one file) and a `.md` copy of each page, such as [`/components/s-button.md`](https://polaris-vue-elements.dev/components/s-button.md). See [Using polaris-vue-elements with AI agents](https://polaris-vue-elements.dev/guide/ai-agents).
|
|
106
|
+
|
|
101
107
|
## How it works
|
|
102
108
|
|
|
103
109
|
Everything derivable from Shopify's manifest is machine-generated; human judgment lives in one small file.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "polaris-vue-elements",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Typed Vue 3 components for Shopify Polaris web components and App Bridge — build Shopify embedded app UIs (App Home) in Vue with props, events and v-model.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://polaris-vue-elements.dev",
|
|
@@ -50,7 +50,8 @@
|
|
|
50
50
|
"dist",
|
|
51
51
|
"tokens/tokens.css",
|
|
52
52
|
"tokens/tokens.json",
|
|
53
|
-
"CHANGELOG.md"
|
|
53
|
+
"CHANGELOG.md",
|
|
54
|
+
"AGENTS.md"
|
|
54
55
|
],
|
|
55
56
|
"sideEffects": [
|
|
56
57
|
"*.css"
|
|
@@ -114,6 +115,7 @@
|
|
|
114
115
|
"vite": "^8.1.5",
|
|
115
116
|
"vite-plugin-vue-devtools": "^8.1.5",
|
|
116
117
|
"vitepress": "^1.6.4",
|
|
118
|
+
"vitepress-plugin-llms": "1.14.0",
|
|
117
119
|
"vitest": "^5.0.5",
|
|
118
120
|
"vue": "^3.5.40",
|
|
119
121
|
"vue-eslint-parser": "^10.4.1",
|
|
@@ -136,6 +138,9 @@
|
|
|
136
138
|
"minimatch@>=7.0.0 <11.0.1": "^11.0.1",
|
|
137
139
|
"js-beautify": {
|
|
138
140
|
"glob": "^14.0.2"
|
|
141
|
+
},
|
|
142
|
+
"vitepress-plugin-llms": {
|
|
143
|
+
"minimatch": "^11.0.1"
|
|
139
144
|
}
|
|
140
145
|
}
|
|
141
146
|
}
|