@avento-space/ts-ui 1.1.1 → 1.2.2

package/README.md

@@ -1,38 +1,22 @@
 # Avento TS UI
 
-**Framework-agnostic, signal-driven UI library for TypeScript.**
+**Web Components UI library — framework-agnostic, signal-driven, tree-shakeable.**
 
-Build reactive user interfaces once and render them anywhere — DOM, SSR, or custom targets — without coupling your components to any specific framework, browser API, or runtime environment.
-
----
-
-## Philosophy
-
-Avento TS UI is built on a strict separation of concerns:
-
-- **Core** — abstract UI model (VNodes), reactive primitives (signals/computed/effects), context, store, lifecycle, and plugin system. Zero platform dependencies.
-- **Render** — generic `Renderer<T, THost>` interface that decouples UI definition from output strategy.
-- **Adapters** — platform-specific renderers (DOM with reconciliation and hydration, SSR with streaming).
-- **Components** — pure functional components consuming `(props, children?) => VNode`, fully portable across all adapters.
-
-No layer depends on the internals of another. The same component function works unchanged in the browser and on the server.
+Build reactive UIs with native web components. Works with any framework (React, Vue, Angular, or vanilla JS) or no framework at all.
 
 ---
 
 ## Features
 
-- **Signal-based reactivity** — fine-grained, dependency-tracked, auto-batched updates
-- **Computed values** — lazy, cached, dependency-aware derived state
-- **Pure functional components** — no classes, no `this`, no hidden state
-- **Pluggable renderers** — DOM (with reconciliation + hydration), SSR (string + streaming)
-- **Context system** — typed provider chain for dependency injection
-- **Immutable store** — subscription-based state management built on signals
-- **Lifecycle hooks** — `onMount`, `onUnmount`, `onUpdate` (enabled by renderer)
-- **Plugin architecture** — named hooks for extensibility (router, devtools, etc.)
-- **Fragment support** — group children without extra DOM nodes
-- **JSX transform** — `jsx`/`jsxs`/`jsxDEV` functions for compiler integration
-- **Strong TypeScript** — full type inference for signals, components, and renderers
-- **Zero runtime dependencies** — only TypeScript
+- **50+ production-ready components** — buttons, modals, tables, forms, overlays, and more
+- **Shadow DOM** — encapsulated styles, no leaks
+- **Signal-based reactivity** — fine-grained updates without virtual DOM
+- **Tree-shakeable** — import only what you use
+- **Framework-agnostic** — use directly as HTML tags or via React wrappers
+- **Accessible** — WAI-ARIA patterns, keyboard navigation, focus management
+- **Icon system** — 3000+ SVG icons built in
+- **Zero dependencies** — only TypeScript
+
 ---
 
 ## Quick Start
@@ -40,235 +24,161 @@ No layer depends on the internals of another. The same component function works
 ### Install
 
 ```bash
-npm install @avento/ts-ui
+npm install @avento-space/ts-ui
 ```
 
-### DOM Rendering
+### Usage (vanilla JS / any framework)
 
 ```typescript
-import { h, signal, computed, effect, mount } from '@avento/ts-ui';
+import { defineComponents } from '@avento-space/ts-ui';
 
-const count = signal(0);
-const doubled = computed(() => count.get() * 2);
+// Register all components (prefix: u-)
+defineComponents();
 
-function App() {
-  return h('div', { class: 'app' }, [
-    h('h1', null, ['Avento Counter']),
-    h('p', null, [`Count: `, count]),
-    h('p', null, [`Doubled: `, doubled]),
-    h('button', { onClick: () => count.set(count.get() + 1) }, ['+']),
-    h('button', { onClick: () => count.set(count.get() - 1) }, ['-']),
-  ]);
-}
+// Components are now available as HTML tags
+```
 
-const renderer = mount(h(App), document.getElementById('root')!);
+```html
+<u-button variant="primary">Click me</u-button>
+<u-modal title="Hello" open>
+  <p>Modal content</p>
+</u-modal>
 ```
 
-Signal values passed directly in `children` or `props` are automatically bound — the DOM updates reactively without re-rendering the entire tree.
+### Usage with React
 
-### SSR Rendering
+```tsx
+import { defineComponents } from '@avento-space/ts-ui';
+import { Button, Modal } from '@avento-space/ts-ui/react';
 
-```typescript
-import { h, renderToString } from '@avento/ts-ui';
+defineComponents();
 
-function Page() {
-  return h('div', { class: 'page' }, [
-    h('h1', null, ['Hello from SSR']),
-    h('p', null, ['This was rendered on the server.']),
-  ]);
+function App() {
+  return (
+    <Button variant="primary" onClick={() => alert('Hi!')}>
+      Click me
+    </Button>
+  );
 }
-
-const html = renderToString(h(Page));
-console.log(html);
-// <div class="page"><h1>Hello from SSR</h1><p>This was rendered on the server.</p></div>
 ```
 
 ---
 
-## Architecture
-
-```
-src/
-├── core/           # VNode, Signal, Component, Context, Store, Lifecycle, Plugin
-├── render/         # Renderer<TOutput,THost> interface + VNode resolver
-├── adapters/       # Platform renderers
-├── adapters/       # Platform renderers
-│   ├── dom/        #   mount(), hydrate(), signal DOM bindings
-│   └── ssr/        #   renderToString(), renderToStream()
-├── components/     # Reusable components (Button, Input, List, Portal)
-├── plugins/        # Router plugin + plugin types
-├── compiler/       # JSX transform (jsx/jsxs/jsxDEV)
-└── devtools/       # VNode inspector, state logger
-```
-
-### Dependency Flow
-
-```
-Components  ──►  Core  ◄──  Plugins
-                    │
-              Render Interface
-                    │
-          ┌──────────┼──────────┐
-          │          │          │
-        DOM        SSR      Custom Adapter
-```
-
-Core never imports from adapters. Adapters import Core. Components import only Core types and the `h` factory.
+## Components
+
+| Component | Tag | Description |
+|-----------|-----|-------------|
+| Accordion | `<u-accordion>` | Collapsible sections |
+| Badge | `<u-badge>` | Status indicators, labels |
+| Box | `<u-box>` | Semantic layout wrapper |
+| Breadcrumb | `<u-breadcrumb>` | Navigation trail |
+| Button | `<u-button>` | Primary, secondary, ghost, danger, link |
+| Calendar | `<u-calendar>` | Date picker |
+| Card | `<u-card>` | Content container with header/footer |
+| Checkbox | `<u-checkbox>` | Toggle option |
+| Collection | `<u-collection>` | Managed item selection |
+| Combobox | `<u-combobox>` | Autocomplete input |
+| CommandPalette | `<u-command-palette>` | ⌘K command menu |
+| Container | `<u-container>` | Max-width layout wrapper |
+| ContextMenu | `<u-context-menu>` | Right-click menu |
+| DataTable | `<u-data-table>` | Sortable, filterable table |
+| DialogRoot | `<u-dialog-root>` | Dialog base behavior |
+| DismissableLayer | `<u-dismissable-layer>` | Click-outside handler |
+| Drawer | `<u-drawer>` | Slide-in panel |
+| Dropdown | `<u-dropdown>` | Menu button |
+| Field | `<u-field>` | Label + input wrapper |
+| FocusManager | `<u-focus-manager>` | Keyboard focus orchestration |
+| FocusScope | `<u-focus-scope>` | Isolated focus zone |
+| FocusTrap | `<u-focus-trap>` | Tab cycle trapping |
+| Form | `<u-form>` | Form validation wrapper |
+| Grid | `<u-grid>` | CSS Grid layout |
+| Hoverable | `<u-hoverable>` | Hover state behavior |
+| Input | `<u-input>` | Text input |
+| KeyboardNavigation | `<u-keyboard-navigation>` | Arrow key navigation |
+| Label | `<u-label>` | Form label |
+| Link | `<u-link>` | Styled anchor |
+| List | `<u-list>` | Keyed list renderer |
+| LiveRegion | `<u-live-region>` | Screen reader announcements |
+| Modal | `<u-modal>` | Dialog overlay |
+| Overlay | `<u-overlay>` | Backdrop layer |
+| Popover | `<u-popover>` | Hover/focus tooltip-like |
+| Popper | `<u-popper>` | Positioning utility |
+| Portal | `<u-portal>` | Teleport to another node |
+| Presence | `<u-presence>` | Mount/unmount animation |
+| Pressable | `<u-pressable>` | Press interaction behavior |
+| RadioGroup | `<u-radio-group>` | Radio button group |
+| RouterView | `<u-router-view>` | Router outlet |
+| Select | `<u-select>` | Native select replacement |
+| Slot | `<u-slot>` | Named slot content |
+| Sortable | `<u-sortable>` | Drag-to-reorder list |
+| Spacer | `<u-spacer>` | Flex spacing utility |
+| Stack / HStack | `<u-stack>` / `<u-hstack>` | Flexbox layouts |
+| Switch | `<u-switch>` | Toggle control |
+| Table | `<u-table>` | Data table |
+| Tabs | `<u-tabs>` | Tabbed interface |
+| Text | `<u-text>` | Typography with size/weight/color |
+| Textarea | `<u-textarea>` | Multi-line input |
+| Toast | `<u-toast>` | Notification popup |
+| TooltipRoot | `<u-tooltip-root>` | Hover tooltip |
+| Transition | `<u-transition>` | CSS transition behavior |
+| Tree | `<u-tree>` | Hierarchical list |
+| VisuallyHidden | `<u-visually-hidden>` | Screen reader-only content |
+| Icon | `<u-icon>` | 3000+ SVG icons |
 
 ---
 
-## Core Concepts
-
-### VNode
+## Styling
 
-The universal UI representation:
+All components use **Shadow DOM** for style encapsulation. Override styles via:
 
-```typescript
-interface VNode {
-  type: string | Component | typeof Fragment;
-  props: Record<string, any> | null;
-  children: VNodeChild[];
-  key?: string | number;
-}
+```css
+/* CSS parts */
+u-button::part(button) { font-weight: 700; }
+u-modal::part(modal-wrapper) { border-radius: 16px; }
 ```
 
-### `h()` — Hyperscript
+Design tokens are available as CSS custom properties:
 
-```typescript
-h('div', { class: 'container' }, [
-  h('h1', null, ['Title']),
-  h('p', null, ['Paragraph with ', signalValue]),
-]);
-```
-
-- `type` — element tag name, component function, or `Fragment`
-- `props` — attributes, properties, event listeners (`onClick`, etc.), signals
-- `children` — VNodes, strings, numbers, booleans, `null`, or signals
-
-### Signals
-
-```typescript
-import { signal, computed, effect, batch, untrack } from '@avento/ts-ui';
-
-const name = signal('World');
-const greeting = computed(() => `Hello, ${name.get()}!`);
-
-effect(() => {
-  console.log(greeting.get()); // logs whenever name changes
-});
-
-batch(() => {
-  name.set('Agnostic');
-  name.set('UI'); // only one notification after batch
-});
-```
-
-### Context
-
-```typescript
-import { createContext, useContext, h, mount } from '@avento/ts-ui';
-
-const Theme = createContext('light');
-
-function Panel() {
-  const theme = useContext(Theme);
-  return h('div', { class: `theme-${theme}` }, ['Themed content']);
+```css
+:root {
+  --u-color-primary: #3b82f6;
+  --u-color-text: #111827;
+  --u-color-text-muted: #4b5563;
+  --u-radius-2xl: 12px;
 }
 ```
 
 ---
 
-## Browser DOM
+## React Wrappers
 
-```typescript
-import { mount } from '@avento/ts-ui';
-
-const instance = mount(h(App), document.getElementById('root')!);
-// instance.render(newVNode) — re-render
-// instance.hydrate(vnode)   — attach to existing DOM
-// instance.destroy()        — unmount and clean up
+```tsx
+import { Button, Modal, Tabs, Text, Badge, Card } from '@avento-space/ts-ui/react';
 ```
 
-Signal values in props or children create direct DOM bindings — only the affected nodes update when the signal changes.
+Each web component has a React wrapper that forwards props and refs.
 
 ---
 
-## Server-Side Rendering
-
-```typescript
-import { renderToString, renderToStream } from '@avento/ts-ui';
+## Icons
 
-// Full document
-const html = renderToString(h(Page));
-
-// Streaming
-for await (const chunk of renderToStream(h(Page))) {
-  res.write(chunk);
-}
+```html
+<u-icon name="heart"></u-icon>
+<u-icon name="settings" size="32" stroke-width="1.5"></u-icon>
 ```
 
-Signals are resolved at render time via `untrack()`. Event handlers and other DOM-only props are omitted from the HTML output.
-
----
-
-## Built-in Components
-
-Avento TS UI provides a set of highly optimized, platform-agnostic UI components:
-
-- **Button**: Custom styled interactive button.
-- **Input**: Reactive text input control with controlled states.
-- **List**: Keyed child element list wrapper.
-- **VirtualList**: Zero-overhead windowed list virtualization (scrolling requires external scroll bindings).
-- **Portal**: Renders children outside the standard DOM hierarchy.
-
-For complete API details and scroll state implementation examples, see the [Components Documentation](docs/components.md).
+3000+ icons available. See the icon registry for all names.
 
 ---
 
-## Plugins
-
-```typescript
-import { registerPlugin, createRouter } from '@avento/ts-ui';
-
-const router = createRouter({ mode: 'history' });
-registerPlugin(router);
-
-router.navigate('/dashboard');
-```
-
-The plugin system uses named hooks. Custom plugins receive a `PluginAPI` to register and invoke hooks.
-
----
-
-## JSX Support
-
-Configure your TypeScript `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "@avento/ts-ui"
-  }
-}
-```
-
-The compiler module exports `jsx`, `jsxs`, and `jsxDEV` for the automatic JSX runtime.
-
----
+## Scripts
 
-## Project Structure
-
-| Layer | Directory | Responsibility |
-|-------|-----------|----------------|
-| Core | `src/core/` | VNode, signals, context, store, lifecycle, plugins |
-| Render | `src/render/` | Renderer interface, VNode resolver |
-| DOM Adapter | `src/adapters/dom/` | mount(), hydrate(), signal bindings |
-| SSR Adapter | `src/adapters/ssr/` | renderToString(), renderToStream() |
-| Components | `src/components/` | Button, Input, List, Portal |
-| Plugins | `src/plugins/` | Router plugin |
-| Compiler | `src/compiler/` | JSX transform functions |
-| DevTools | `src/devtools/` | Inspector, state logger |
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Build with tsup (ESM + .d.ts) |
+| `npm test` | Run vitest |
+| `npm run typecheck` | TypeScript check |
+| `npm run lint` | ESLint |
 
 ---