@tasteee/zest 0.1.0

package/README.md

@@ -0,0 +1,204 @@
+# @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