@tasteee/zest 0.1.0 → 0.3.0

package/README.md

@@ -1,204 +1,113 @@
-# @tasteee/zest
-
-> ⚠️ **Pre-release — do not consume yet.** Zest is under active development
-> and published for early testing only. APIs, tag names, attributes, and
-> design tokens may change without notice between versions. Don't depend on
-> it in production until 1.0.
-
-A gorgeous, dark-themed, fully-featured, framework-agnostic web component
-library — 135+ custom elements covering layout, forms, overlays, navigation,
-data display, and more. Use it in plain HTML, React, Vue, Svelte, Solid, or
-anywhere else custom elements work (which is everywhere).
-
-Zest is built with [Atomico](https://atomicojs.dev) and ships as a **single
-self-contained ESM bundle with zero runtime dependencies** — Atomico and the
-syntax-highlighting libraries are bundled in at build time. There is no
-peer-dependency dance, no plugin, no framework adapter, and no per-component
-imports to manage.
-
-## Install
-
-```sh
-npm install @tasteee/zest
-# or: pnpm add @tasteee/zest
-```
-
-## Two imports, that's it
-
-```js
-import '@tasteee/zest'          // registers every <z-*> element
-import '@tasteee/zest/ink.css'  // design tokens: CSS custom properties + fonts
-```
-
-- **`@tasteee/zest`** is a side-effect import. It calls
-  `customElements.define(...)` for every element — after that, `<z-button>`,
-  `<z-dialog>`, `<z-stack>`, etc. just work as HTML tags. Each component
-  carries its own encapsulated styles in its shadow DOM, so nothing leaks in
-  or out.
-
-- **`@tasteee/zest/ink.css`** defines the document-level design tokens
-  (colors, spacing, typography custom properties) that the components read via
-  `var(--token)`, and loads the DM Sans / DM Mono fonts.
-
-## A taste
-
-Everything is just HTML. Attributes follow one consistent grammar across the
-whole library: `tone` picks the color family, `kind` picks the visual
-treatment, `size` picks the scale, and boolean states are `is-*` flags.
-
-```html
-<z-button tone="primary">Save</z-button>
-<z-button tone="danger" kind="outline">Delete</z-button>
-<z-button kind="ghost" size="small">Cancel</z-button>
-<z-button tone="primary" is-loading>Saving…</z-button>
-```
-
-Layout is declarative — no wrapper CSS required. `gap` and the `inset*` props
-take a size token (`2xs` `xs` `sm` `md` `lg` `xl` `2xl`…) or any CSS length:
-
-```html
-<z-stack gap="md">
-  <z-card>One</z-card>
-  <z-card>Two</z-card>
-</z-stack>
-
-<z-stack is-row gap="sm" aligns-y="center" aligns-x="between">
-  <z-text weight="bold">Left</z-text>
-  <z-badge tone="success" label="Right"></z-badge>
-</z-stack>
-```
-
-Overlays build on the platform. `z-dialog` wraps the native `<dialog>`
-element, so focus trapping, Esc-to-close, and top-layer stacking come for
-free — wire it up entirely in markup with slots:
-
-```html
-<z-dialog heading="Edit profile" description="Update your details.">
-  <z-button slot="trigger">Edit</z-button>
-
-  <z-input placeholder="Name"></z-input>
-
-  <div slot="footer">
-    <z-button kind="outline" tone="neutral">Cancel</z-button>
-    <z-button tone="primary">Save</z-button>
-  </div>
-</z-dialog>
-```
-
-Form controls emit `change` events with the value in `event.detail`. Rich
-data (like option lists) is passed as a property:
-
-```html
-<z-select placeholder="Pick a fruit"></z-select>
-<z-switch is-checked></z-switch>
-<z-input placeholder="Email" type="email" is-required></z-input>
-```
-
-```js
-const select = document.querySelector('z-select')
-select.options = [
-  { value: 'apple', label: 'Apple' },
-  { value: 'pear', label: 'Pear' }
-]
-select.addEventListener('change', (e) => console.log(e.detail.value))
-```
-
-## Features
-
-- **Framework-agnostic** — custom elements work natively in every framework
-  and in plain HTML. No adapters, no wrappers.
-- **Zero runtime dependencies** — one bundled ESM file; nothing else lands in
-  your `node_modules` graph.
-- **One consistent API grammar** — `tone` / `kind` / `size` / `is-*` mean the
-  same thing on every component, so learning one component teaches you all of
-  them.
-- **A real design system** — a shared token scale (colors, spacing,
-  typography) drives every component via CSS custom properties, so overriding
-  a token restyles the whole library.
-- **Platform-first** — dialogs use `<dialog>`, popovers and menus follow
-  native focus and keyboard conventions (arrow keys, Enter/Space, Esc).
-- **Shadow DOM encapsulation** — component styles can't collide with your
-  app's CSS, and vice versa.
-- **TypeScript + editor tooling** — ships `.d.ts` declarations and a
-  [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest)
-  (`custom-elements.json`), so editors that read the manifest autocomplete
-  tag names and attributes.
-
-## Using it everywhere
-
-### React
-
-```jsx
-import '@tasteee/zest'
-import '@tasteee/zest/ink.css'
-
-export function App() {
-  return (
-    <z-button tone="primary" onClick={() => console.log('clicked')}>
-      Click me
-    </z-button>
-  )
-}
-```
-
-### Plain HTML
-
-The bundle is ESM, so the script tag must be `type="module"`:
-
-```html
-<link rel="stylesheet" href="/node_modules/@tasteee/zest/dist/ink.css" />
-<script type="module" src="/node_modules/@tasteee/zest/dist/zest.js"></script>
-
-<z-button tone="primary">Click me</z-button>
-```
-
-### From a CDN (no build step at all)
-
-```html
-<link rel="stylesheet" href="https://esm.sh/@tasteee/zest/ink.css" />
-<script type="module" src="https://esm.sh/@tasteee/zest"></script>
-
-<z-button tone="primary">Click me</z-button>
-```
-
-## Components
-
-Foundation `z-box` `z-text` `z-card` `z-line` `z-separator` ·
-Layout `z-stack` `z-grid` `z-cluster` `z-center` `z-container` `z-section`
-`z-surface` `z-scroll` `z-spacer` ·
-Actions `z-button` `z-button-group` `z-toggle` `z-toggle-group` `z-link` ·
-Forms `z-input` `z-textarea` `z-checkbox` `z-switch` `z-radio` `z-radio-group`
-`z-slider` `z-select` `z-combobox` `z-color-picker` `z-input-otp` ·
-Data display `z-badge` `z-avatar` `z-progress` `z-skeleton` `z-table`
-`z-pagination` `z-stat` ·
-Navigation `z-breadcrumbs` `z-tabs` `z-collapsible` `z-accordion` `z-menu`
-`z-nav-menu` `z-sidebar` ·
-Overlays `z-tooltip` `z-popover` `z-hover-card` `z-dialog` `z-alert-dialog`
-`z-alert` `z-sheet` `z-drawer` `z-context-menu` `z-toast` `z-command` ·
-Specialized `z-empty-state` `z-scroll-area` `z-code-block` `z-post-meta`
-`z-carousel` `z-chart` `z-terminal` `z-piano-roll` `z-pattern-roll`
-
-…and many more. Every component has a doc page in [`docs/`](./docs) with
-examples, attribute tables, and event references.
-
-## Local development
-
-```sh
-pnpm install
-pnpm dev      # rebuilds dist/ on change (vite build --watch)
-pnpm build    # dist/zest.js + dist/ink.css + dist/*.d.ts + custom-elements.json
-```
-
-## Publishing
-
-Run from this directory (`packages/zest`):
-
-```sh
-npm publish
-# prepublishOnly runs the full build automatically
-# publishConfig.access is "public"
-```
-
-## License
-
-MIT
+# @tasteee/zest
+
+A gorgeous, dark theme, fully-featured, framework-agnostic web component library.Use it in in plain HTML, React, Vue, Svelte, or anywhere else.
+
+The components are built with [Atomico](https://atomicojs.dev) and ship as a
+single self-contained bundle with **zero runtime dependencies** (Atomico and the
+syntax-highlighting deps are bundled in at build time).
+
+## Install
+
+```sh
+npm install @tasteee/zest
+# or: pnpm add @tasteee/zest
+```
+
+## Usage
+
+```js
+import '@tasteee/zest'          // registers every <z-*> element
+import '@tasteee/zest/ink.css'  // design tokens: CSS custom properties + fonts
+```
+
+- **`@tasteee/zest`** runs the side-effectful registration. Importing it calls
+  `customElements.define(...)` for all elements. There's nothing else to wire
+  up. Each component carries its own encapsulated styles inside its shadow DOM.
+
+- **`@tasteee/zest/ink.css`** defines the document-level design tokens (colors,
+  spacing, typography custom properties) that the components read via
+  `var(--token)`. It also loads the DM Sans / DM Mono fonts from Google Fonts.
+
+TODO: Make it so fonts can be opted into, rather than automatic.
+
+### React
+
+```jsx
+import '@tasteee/zest'
+import '@tasteee/zest/ink.css'
+
+export function App() {
+  return (
+    <z-button kind="primary" onClick={() => console.log('clicked')}>
+      Click me
+    </z-button>
+  )
+}
+```
+
+### Plain HTML
+
+(script must be `type="module"` since the bundle is ESM)
+
+```html
+<link rel="stylesheet" href="/node_modules/@tasteee/zest/dist/ink.css" />
+<script type="module" src="/node_modules/@tasteee/zest/dist/zest.js"></script>
+<z-button kind="primary">Click me</z-button>
+```
+
+### From a CDN (no build step)
+
+A CDN resolves the package name for you, so here you can use it directly:
+
+```html
+<link rel="stylesheet" href="https://esm.sh/@tasteee/zest/ink.css" />
+<script type="module" src="https://esm.sh/@tasteee/zest"></script>
+
+<z-button kind="primary">Click me</z-button>
+```
+
+## TypeScript & editor support
+
+The package ships type declarations (`dist/index.d.ts`) and a
+[Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest)
+at `custom-elements.json` (referenced via the `customElements` field in
+`package.json`). Editors and tools that read the manifest get tag-name and
+attribute autocompletion for the `<z-*>` elements.
+
+## Components
+
+Foundation `z-box` `z-text` `z-card` `z-line` `z-separator` ·
+Layout `z-stack` `z-grid` `z-cluster` `z-center` `z-container` `z-section`
+`z-surface` `z-scroll` `z-spacer` ·
+Actions `z-button` `z-button-group` `z-toggle` `z-toggle-group` `z-link` ·
+Forms `z-input` `z-textarea` `z-checkbox` `z-switch` `z-radio` `z-radio-group`
+`z-slider` `z-select` `z-combobox` `z-color-picker` `z-input-otp` ·
+Data display `z-badge` `z-avatar` `z-progress` `z-skeleton` `z-table`
+`z-pagination` `z-stat` ·
+Navigation `z-breadcrumbs` `z-tabs` `z-collapsible` `z-accordion` `z-menu`
+`z-nav-menu` `z-sidebar` ·
+Overlays `z-tooltip` `z-popover` `z-hover-card` `z-dialog` `z-alert-dialog`
+`z-alert` `z-sheet` `z-drawer` `z-context-menu` `z-toast` `z-command` ·
+Specialized `z-empty-state` `z-scroll-area` `z-code-block` `z-post-meta`
+`z-carousel` `z-chart`
+
+## Local development
+
+```sh
+pnpm install
+pnpm dev      # rebuilds dist/ on change (vite build --watch)
+pnpm build    # dist/zest.js + dist/ink.css + dist/*.d.ts + custom-elements.json
+```
+
+## Publishing
+
+```sh
+pnpm build
+npm publish
+# prepublishOnly runs the build
+# publishConfig.access is "public"
+```
+
+## License
+
+MIT