@swell/swell-ui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-12
+
+### Added
+
+- The core components: badge, button, card, checkbox, chip, disclosure, divider, input, link, lookup, popover, quantity, radio, select, skeleton, status message, tabs, text, textarea and thumbnail, and `<swell-ui>`, an area of the page with values of its own.
+- Design tokens with defaults, configured from JavaScript with `configure`, `setTheme`, `getConfig` and `onChange`: light and dark themes, areas of the page, and variants of the host's own.
+- The package `@swell/swell-ui`: ES modules with TypeScript declarations, typed React wrappers for React 16.8 and later, of which a bundler keeps only those the host imports, each with its element, type entries for Preact, Solid, Vue and Svelte, editor data for VS Code and JetBrains, the Custom Elements Manifest and the token files.
+- Lazy loading: the entry `@swell/swell-ui` holds the configuration and a loader, and each element loads the first time its tag appears on the page, also inside a shadow root passed to `load`. `load` and `ready`, also on the `SwellUI` global, preload elements and wait for them. The kit the platform serves at `/.swell/ui/v1/index.js` loads an element whose chunk a deploy removed from a fresh copy of its entry.
+- `@swell/swell-ui/elements/<name>`: an entry per element, which defines it eagerly and exports its class.
+- A disabled `<fieldset>` disables every field, select, radio group, quantity, button and chip inside it, which then look as with their own `disabled` attribute; a disabled chip, by its `disabled` attribute or a fieldset, fades its remove button, which takes no focus or press.

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# Swell UI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Web components for Swell checkout, dashboard, apps and storefronts, styled by the host through design tokens.
+
+The components are custom elements (`<swell-button>`, `<swell-input>`, `<swell-checkbox>`, …), so they work with any framework or none. They look finished with no configuration, and each host overrides the design tokens it needs, so the same component looks native in every host.
+
+## Table of Contents
+
+- [Background](#background)
+- [Install](#install)
+- [Usage](#usage)
+- [Loading](#loading)
+- [Frameworks](#frameworks)
+- [Apps and storefronts](#apps-and-storefronts)
+- [Browser support](#browser-support)
+- [API](#api)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Background
+
+Swell apps add their own UI to the checkout and the dashboard, and that UI has to look like the host around it. The kit gives every host and app the same components, and each host configures their look from JavaScript: the values the components share, such as the palette, the font and the corner radius, and the values of single components, with a light and a dark value for any color. [TOKENS.md](TOKENS.md) describes the tokens.
+
+## Install
+
+```sh
+npm install @swell/swell-ui
+```
+
+Import the kit once. Its entry holds the configuration and the loader, which loads each element the first time its tag appears on the page ([Loading](#loading)):
+
+```js
+import { configure } from "@swell/swell-ui";
+```
+
+Every module other than `core` is also an entry of its own, `@swell/swell-ui/<module>`, which defines all of that module's elements at once: `import "@swell/swell-ui/<module>";`.
+
+Without a bundler, a page loads the entry the Swell platform serves as a module script ([Apps and storefronts](#apps-and-storefronts)); the entry also sets the `SwellUI` global.
+
+## Usage
+
+Use the elements in plain markup:
+
+```html
+<swell-button>Continue</swell-button>
+<swell-button variant="secondary">Edit</swell-button>
+<swell-button variant="secondary" appearance="plain" size="small">Cancel</swell-button>
+```
+
+The kit has no icon set. Put your own icon into a component's `start` or `end` slot; an `<svg>` there takes the component's icon size and the current color, so draw it with `currentColor`:
+
+```html
+<swell-input label="Address">
+  <svg slot="start" viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">…</svg>
+</swell-input>
+```
+
+Configure their look from JavaScript. The components follow each call, before or after they render:
+
+```js
+configure({
+  color: { accent: { light: "#0a7c4a", dark: "#3ecf8e" } },
+  components: {
+    button: { border: { radius: "12px" } },
+  },
+  theme: "system",
+});
+```
+
+[TOKENS.md → Configuration](TOKENS.md#configuration) describes the configuration, the theme and the areas of a page that take values of their own, such as an order summary in the brand's colors (`configure(config, id)` and `<swell-ui config="id">`).
+
+## Loading
+
+The entry, `dist/index.js`, holds the loader and the `SwellUI` global, and imports the configuration from a chunk. Each element is a chunk of its own in `dist/chunks/`, with a content hash in its file name, and the code several elements share sits in chunks there too. A page downloads the entry, the configuration and the chunks of the elements it renders.
+
+- The loader watches the document: every kit element on the page when the entry runs, and every one added later, loads its chunk once.
+- Until its chunk loads, a kit element is hidden and keeps its place in the layout. `<swell-ui>` shows its content all along: it renders nothing of its own.
+- A component that renders kit elements in a shadow root of its own passes that root to `load`, which watches it as it watches the document:
+
+  ```js
+  SwellUI.load(this.shadowRoot);
+  ```
+
+- `load(tags)` loads elements before they appear, and `ready(tags)` waits until they are defined; `ready()` waits for every kit element on the page now. Both reject when a chunk can't load.
+
+  ```js
+  import { load, ready } from "@swell/swell-ui";
+
+  load(["swell-button", "swell-input"]);
+  await ready();
+  ```
+
+- `@swell/swell-ui/elements/<name>` defines the element `swell-<name>` as soon as it is imported, and exports its class: a host imports the elements of its first screen this way and leaves the rest to the loader. The React wrappers import their elements the same way.
+
+  ```js
+  import "@swell/swell-ui/elements/button";
+  ```
+
+- In the kit the platform serves ([Apps and storefronts](#apps-and-storefronts)), a chunk that fails to load, such as one a deploy replaced while the page was open, makes the loader import a fresh `index.js` once and load the element from it. An element that doesn't load stays undefined and the loader reports it with `console.error`; the rest of the page keeps working.
+
+## Frameworks
+
+The elements work in any framework, and the package carries the types and editor data for them.
+
+- **React**, from 16.8: use the typed wrappers, which set properties and listen to the elements' events. `@swell/swell-ui/react` holds the wrappers of every module; each wrapper defines its element when it is imported, and a bundler keeps only the wrappers the host imports. A handler takes the element as `event.currentTarget`. As on a native field, `onInput` fires on every change of a field's value and `onChange` once the user commits it.
+
+  ```jsx
+  import { SwellQuantity } from "@swell/swell-ui/react";
+
+  <SwellQuantity aria-label="Quantity" value={count} onChange={(event) => setCount(event.currentTarget.value)} />;
+  ```
+
+- **Preact, Solid, Vue and Svelte**: use the elements by their tags and add the framework's type entry to `compilerOptions.types` in `tsconfig.json`, next to the type packages listed there; it types every element's attributes, properties and events:
+
+  ```json
+  { "compilerOptions": { "types": ["@swell/swell-ui/vue"] } }
+  ```
+
+  The entries are `@swell/swell-ui/preact`, `/solid`, `/vue` and `/svelte`. Vue renders the elements as custom elements when its compiler option `isCustomElement` returns `true` for tags that start with `swell-`.
+- **Editors**: JetBrains IDEs read the package's `web-types.json` by themselves. VS Code reads its custom data from the workspace settings:
+
+  ```json
+  {
+    "html.customData": ["./node_modules/@swell/swell-ui/dist/editors/vscode.html-custom-data.json"],
+    "css.customData": ["./node_modules/@swell/swell-ui/dist/editors/vscode.css-custom-data.json"]
+  }
+  ```
+
+## Apps and storefronts
+
+The Swell platform serves the kit at `/.swell/ui/v1/index.js`, with its chunks next to it; `v1` is the major version. An app's page in a frame of the checkout or the dashboard, and a merchant's storefront, load it as a module script and use the elements by their tags:
+
+```html
+<script type="module" src="/.swell/ui/v1/index.js"></script>
+<swell-text>Total</swell-text>
+```
+
+An app uses the elements directly, or styles its own markup with the global `--swell-*` CSS variables, such as `--swell-color-accent` and `--swell-border-radius`.
+
+## Browser support
+
+Swell UI runs in the browser, in Chrome 125, Firefox 126, Safari 17.5 and later. Importing it on a server throws, so a framework that renders on the server imports the kit in the browser only, such as with `dynamic(() => import(…), { ssr: false })` in Next.js. The components rely on custom states (`:state()`), `light-dark()` colors, the Popover API, constructable stylesheets and `ElementInternals`.
+
+## API
+
+- Components: their attributes, properties, events, slots, parts and states, in the package's `custom-elements.json` (Custom Elements Manifest), generated from the source.
+- The entry's functions, also on the `SwellUI` global: `configure`, `setTheme`, `getConfig`, `onChange` and `version` in [TOKENS.md → Configuration](TOKENS.md#configuration), `load` and `ready` in [Loading](#loading).
+- Tokens and settings: [TOKENS.md](TOKENS.md), the files in [`tokens/`](tokens) and each component's `tokens.json`.
+
+## Contributing
+
+Ask questions in an issue on GitHub. Changes from the Swell team go through pull requests on GitHub. Each pull request keeps the invariants in [ARCHITECTURE.md](ARCHITECTURE.md) and follows [AGENTS.md](AGENTS.md).
+
+A release is published from `main`:
+
+1. In [CHANGELOG.md](CHANGELOG.md), move the entries under `[Unreleased]` to a heading for the new version with its date, and commit.
+2. Bump the version by the rules in [ARCHITECTURE.md → Versioning](ARCHITECTURE.md#versioning): `npm version patch`, `minor` or `major`, which commits and tags it.
+3. Run the full check and pack the package: `npm run release`.
+4. Publish the packed file: `npm publish swell-swell-ui-<version>.tgz`. The package is public on npm (`publishConfig.access`), so apps and storefronts install it without a token.
+5. Push the commit and the tag: `git push --follow-tags`.
+
+The Swell platform serves the kit at `/.swell/ui/v<major>/` from the version of `@swell/swell-ui` that swell-admin depends on, so a release reaches apps and storefronts once swell-admin takes the new version and deploys.
+
+## License
+
+UNLICENSED. © Swell. Internal use only.

package/package.json

@@ -1,6 +1,137 @@
 {
   "name": "@swell/swell-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Web components for Swell checkout, dashboard, apps and storefronts, styled by the host through design tokens.",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/components/core/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./preact": {
+      "types": "./dist/frameworks/preact.d.ts"
+    },
+    "./solid": {
+      "types": "./dist/frameworks/solid.d.ts"
+    },
+    "./vue": {
+      "types": "./dist/frameworks/vue.d.ts"
+    },
+    "./svelte": {
+      "types": "./dist/frameworks/svelte.d.ts"
+    },
+    "./custom-elements.json": "./custom-elements.json",
+    "./resolver.json": "./resolver.json",
+    "./tokens/*": "./tokens/*",
+    "./components/*": "./src/components/*",
+    "./web-types.json": "./dist/editors/web-types.json",
+    "./vscode.html-custom-data.json": "./dist/editors/vscode.html-custom-data.json",
+    "./vscode.css-custom-data.json": "./dist/editors/vscode.css-custom-data.json",
+    "./elements/*": {
+      "types": "./dist/elements/*.d.ts",
+      "default": "./dist/elements/*.js"
+    },
+    "./*": {
+      "types": "./dist/types/components/*/index.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "./dist/*.js",
+    "./dist/elements/*.js",
+    "./dist/chunks/*.js"
+  ],
+  "types": "./dist/types/components/core/index.d.ts",
+  "web-types": "./dist/editors/web-types.json",
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "custom-elements.json",
+    "resolver.json",
+    "tokens",
+    "src/components/**/tokens*.json"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . && stylelint \"src/**/*.css\" --allow-empty-input && prettier --check .",
+    "format": "prettier --write . && eslint --fix . && stylelint \"src/**/*.css\" --fix --allow-empty-input",
+    "test": "vitest run",
+    "tokens": "node scripts/tokens/cli.ts",
+    "build": "vite build && tsc -p tsconfig.build.json && node scripts/package/types.ts && npm run analyze && node scripts/package/editors.ts && node scripts/package/react.ts",
+    "analyze": "cem analyze --config custom-elements-manifest.config.js",
+    "storybook": "npm run analyze && storybook dev -p 6006",
+    "build-storybook": "npm run analyze && storybook build",
+    "check": "npm run tokens -- --check && npm run typecheck && npm run lint && npm test && npm run build && node scripts/package/check.ts",
+    "release": "npm run check && npm pack",
+    "pretypecheck": "npm run analyze",
+    "pretest": "npm run analyze"
+  },
+  "peerDependencies": {
+    "preact": ">=10",
+    "react": ">=16.8",
+    "solid-js": ">=1",
+    "vue": ">=3.5"
+  },
+  "peerDependenciesMeta": {
+    "preact": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "0.11.0",
+    "@eslint/js": "10.0.1",
+    "@storybook/addon-a11y": "10.6.6",
+    "@storybook/addon-docs": "10.6.6",
+    "@storybook/addon-vitest": "10.6.6",
+    "@storybook/web-components-vite": "10.6.6",
+    "@types/node": "22.20.5",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitest/browser": "5.1.0",
+    "@vitest/browser-playwright": "5.1.0",
+    "@wc-toolkit/jsx-types": "1.8.2",
+    "@wc-toolkit/svelte-types": "1.0.3",
+    "@wc-toolkit/vuejs-types": "1.0.3",
+    "custom-element-jet-brains-integration": "1.8.0",
+    "custom-element-vs-code-integration": "1.5.0",
+    "eslint": "10.14.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-storybook": "10.6.6",
+    "eslint-plugin-wc": "3.1.0",
+    "globals": "17.14.0",
+    "lit": "3.3.3",
+    "playwright": "1.65.0",
+    "prettier": "3.9.10",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "storybook": "10.6.6",
+    "stylelint": "18.0.0",
+    "stylelint-config-standard": "41.0.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.72.1",
+    "vite": "8.3.6",
+    "vitest": "5.1.0"
+  },
+  "customElements": "custom-elements.json"
+}

package/resolver.json

@@ -0,0 +1,111 @@
+{
+  "name": "Swell UI",
+  "version": "2025.10",
+  "description": "Swell UI token contract: global groups and components, then the theme.",
+  "sets": {
+    "global": {
+      "description": "Global groups.",
+      "sources": [
+        {
+          "$ref": "tokens/color.json"
+        },
+        {
+          "$ref": "tokens/font.json"
+        },
+        {
+          "$ref": "tokens/border.json"
+        },
+        {
+          "$ref": "tokens/focus.json"
+        },
+        {
+          "$ref": "tokens/motion.json"
+        },
+        {
+          "$ref": "tokens/control.json"
+        },
+        {
+          "$ref": "tokens/field.json"
+        },
+        {
+          "$ref": "tokens/overlay.json"
+        }
+      ]
+    },
+    "components": {
+      "description": "Components.",
+      "sources": [
+        {
+          "$ref": "src/components/core/text/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/link/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/button/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/checkbox/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/radio/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/status/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/badge/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/chip/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/thumbnail/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/card/tokens.json"
+        },
+        {
+          "$ref": "src/components/core/tabs/tokens.json"
+        }
+      ]
+    }
+  },
+  "modifiers": {
+    "theme": {
+      "description": "Light or dark theme. Light values are in the base files.",
+      "contexts": {
+        "light": [],
+        "dark": [
+          {
+            "$ref": "tokens/color.dark.json"
+          },
+          {
+            "$ref": "tokens/field.dark.json"
+          },
+          {
+            "$ref": "src/components/core/button/tokens.dark.json"
+          },
+          {
+            "$ref": "src/components/core/radio/tokens.dark.json"
+          },
+          {
+            "$ref": "src/components/core/status/tokens.dark.json"
+          }
+        ]
+      },
+      "default": "light"
+    }
+  },
+  "resolutionOrder": [
+    {
+      "$ref": "#/sets/global"
+    },
+    {
+      "$ref": "#/sets/components"
+    },
+    {
+      "$ref": "#/modifiers/theme"
+    }
+  ]
+}

package/src/components/core/badge/tokens.json

@@ -0,0 +1,152 @@
+{
+  "badge": {
+    "$description": "Badges: short labels and counts that are text only. The appearance lays the palette out: filled uses background and foreground, without a border; outline uses border and accent on a transparent background.",
+    "$extensions": {
+      "is.swell.ui": {
+        "attributes": {
+          "size": ["xsmall", "small", "large", "xlarge"]
+        },
+        "settings": {
+          "appearance": {
+            "description": "How badges are drawn when the element has no appearance attribute.",
+            "values": ["filled", "outline"],
+            "default": "outline"
+          }
+        },
+        "variants": true
+      }
+    },
+    "height": {
+      "$type": "dimension",
+      "$value": {
+        "value": 24,
+        "unit": "px"
+      },
+      "$description": "Height and least width of medium badges."
+    },
+    "font": {
+      "size": {
+        "$type": "dimension",
+        "$value": "{font.footnote.size}",
+        "$description": "Font size of medium badges."
+      },
+      "weight": {
+        "$type": "fontWeight",
+        "$value": "{font.strong.weight}",
+        "$description": "Font weight of medium badges."
+      }
+    },
+    "xsmall": {
+      "height": {
+        "$type": "dimension",
+        "$value": {
+          "value": 16,
+          "unit": "px"
+        },
+        "$description": "Height and least width of extra small badges, such as a count on an icon."
+      },
+      "font": {
+        "size": {
+          "$type": "dimension",
+          "$value": {
+            "value": 10,
+            "unit": "px"
+          },
+          "$description": "Font size of extra small badges."
+        },
+        "weight": {
+          "$type": "fontWeight",
+          "$value": "{font.bold.weight}",
+          "$description": "Font weight of extra small badges."
+        }
+      }
+    },
+    "small": {
+      "height": {
+        "$type": "dimension",
+        "$value": {
+          "value": 20,
+          "unit": "px"
+        },
+        "$description": "Height and least width of small badges, such as a count."
+      },
+      "font": {
+        "size": {
+          "$type": "dimension",
+          "$value": {
+            "value": 11,
+            "unit": "px"
+          },
+          "$description": "Font size of small badges."
+        },
+        "weight": {
+          "$type": "fontWeight",
+          "$value": "{font.bold.weight}",
+          "$description": "Font weight of small badges."
+        }
+      }
+    },
+    "large": {
+      "height": {
+        "$type": "dimension",
+        "$value": {
+          "value": 28,
+          "unit": "px"
+        },
+        "$description": "Height and least width of large badges."
+      },
+      "font": {
+        "size": {
+          "$type": "dimension",
+          "$value": {
+            "value": 13,
+            "unit": "px"
+          },
+          "$description": "Font size of large badges."
+        }
+      }
+    },
+    "xlarge": {
+      "height": {
+        "$type": "dimension",
+        "$value": {
+          "value": 32,
+          "unit": "px"
+        },
+        "$description": "Height and least width of extra large badges."
+      },
+      "font": {
+        "size": {
+          "$type": "dimension",
+          "$value": {
+            "value": 14,
+            "unit": "px"
+          },
+          "$description": "Font size of extra large badges."
+        }
+      }
+    },
+    "color": {
+      "background": {
+        "$type": "color",
+        "$value": "{color.foreground}",
+        "$description": "Fill of filled primary badges, such as a count."
+      },
+      "foreground": {
+        "$type": "color",
+        "$value": "{color.background}",
+        "$description": "Text of filled primary badges."
+      },
+      "border": {
+        "$type": "color",
+        "$value": "{color.border}",
+        "$description": "Border of outline primary badges."
+      },
+      "accent": {
+        "$type": "color",
+        "$value": "{color.foreground}",
+        "$description": "Text of outline primary badges."
+      }
+    }
+  }
+}

package/src/components/core/button/tokens.dark.json

@@ -0,0 +1,16 @@
+{
+  "button": {
+    "$description": "Dark theme values of button.",
+    "color": {
+      "shadow": {
+        "$type": "color",
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [0.3569, 0.549, 1],
+          "hex": "#5b8cff",
+          "alpha": 0.6
+        }
+      }
+    }
+  }
+}