@easemate/web-kit 0.3.1 → 0.3.3

package/README.md

@@ -48,6 +48,10 @@ A modern, framework-agnostic UI kit of web components for building animation con
 - [Configuration](#configuration)
   - [initWebKit Options](#initwebkit-options)
   - [Theme Configuration](#theme-configuration)
+    - [Custom Theme Registration](#custom-theme-registration)
+    - [Theme Inheritance](#theme-inheritance)
+    - [Creating a Theme from Scratch](#creating-a-theme-from-scratch)
+    - [Theme Utilities](#theme-utilities)
   - [Font Configuration](#font-configuration)
   - [Lazy Loading](#lazy-loading)
   - [Component Replacement](#component-replacement)
@@ -62,6 +66,8 @@ A modern, framework-agnostic UI kit of web components for building animation con
   - [State API](#state-api)
 - [Accessibility](#accessibility)
 - [SSR Support](#ssr-support)
+- [Links](#links)
+- [Authors](#authors)
 - [License](#license)
 
 ---
@@ -182,7 +188,11 @@ The library provides first-class React integration via `@easemate/web-kit/react`
 
 ### JSX Types
 
-Importing `@easemate/web-kit/react` automatically adds JSX types for all `ease-*` custom elements:
+Importing `@easemate/web-kit/react` automatically adds JSX types for all `ease-*` custom elements, including:
+- All control components (`ease-slider`, `ease-toggle`, `ease-input`, etc.)
+- Layout components (`ease-panel`, `ease-state`, `ease-field`, etc.)
+- Advanced components (`ease-curve`, `ease-code`, `ease-monitor-fps`, etc.)
+- All icon components (`ease-icon-settings`, `ease-icon-bezier`, etc.)
 
 ```tsx
 import '@easemate/web-kit/react';
@@ -193,12 +203,26 @@ import '@easemate/web-kit/react';
 </ease-panel>
 ```
 
-You can also import just the JSX types separately:
+You can also import just the JSX types separately (useful for type-only imports):
 
 ```tsx
 import '@easemate/web-kit/react/jsx';
 ```
 
+The types include proper ref types for accessing component methods:
+
+```tsx
+import type { StateElement, PanelElement } from '@easemate/web-kit/react';
+
+const stateRef = useRef<StateElement>(null);
+const panelRef = useRef<PanelElement>(null);
+
+// Access typed methods
+stateRef.current?.get('volume');
+stateRef.current?.reset();
+panelRef.current?.setActiveTab(1);
+```
+
 ### Basic Setup
 
 ```tsx
@@ -458,13 +482,39 @@ const handleChange = createEventHandler<ControlChangeEvent>((e) => {
 
 ### Icons
 
-All icon components follow the pattern `<ease-icon-*>`:
-
-- `ease-icon-settings`, `ease-icon-dots`, `ease-icon-plus`, `ease-icon-minus`
-- `ease-icon-check`, `ease-icon-chevron`, `ease-icon-code`
-- `ease-icon-bezier`, `ease-icon-bezier-*` (bezier tools)
-- `ease-icon-anchor-add`, `ease-icon-anchor-remove`
-- And more...
+All icon components follow the pattern `<ease-icon-*>`. All icons are typed in JSX when importing `@easemate/web-kit/react`.
+
+**Interface Icons:**
+| Tag | Description |
+|-----|-------------|
+| `ease-icon-settings` | Settings gear icon |
+| `ease-icon-dots` | Three dots / more menu icon |
+| `ease-icon-plus` | Plus / add icon |
+| `ease-icon-minus` | Minus / remove icon |
+| `ease-icon-check` | Checkmark icon |
+| `ease-icon-code` | Code brackets icon |
+| `ease-icon-picker` | Eyedropper picker icon |
+| `ease-icon-mention` | @ mention icon |
+| `ease-icon-arrow-up` | Up arrow icon |
+| `ease-icon-arrows-vertical` | Vertical arrows icon |
+| `ease-icon-circle-arrow-left` | Left arrow in circle |
+| `ease-icon-circle-arrow-right` | Right arrow in circle |
+| `ease-icon-anchor-add` | Add anchor point |
+| `ease-icon-anchor-remove` | Remove anchor point |
+| `ease-icon-bezier` | Bezier curve icon |
+| `ease-icon-bezier-angle` | Bezier angle tool |
+| `ease-icon-bezier-distribute` | Distribute bezier points |
+| `ease-icon-bezier-length` | Bezier length tool |
+| `ease-icon-bezier-mirror` | Mirror bezier handles |
+
+**Animation Icons:**
+| Tag | Description |
+|-----|-------------|
+| `ease-icon-chevron` | Animated chevron (expands/collapses) |
+| `ease-icon-clear` | Animated clear/X icon |
+| `ease-icon-grid` | Animated grid icon |
+| `ease-icon-loading` | Animated loading spinner |
+| `ease-icon-snap` | Animated snap indicator |
 
 ---
 
@@ -785,12 +835,18 @@ interface ThemeModeConfig {
   dark: ThemeInput;
   persist?: { key: string }; // Coming soon
 }
+```
 
-// Custom theme registration
+#### Custom Theme Registration
+
+Register custom themes using `registerTheme()`. No TypeScript declaration files needed - custom theme names are fully supported:
+
+```typescript
 import { initWebKit, registerTheme } from '@easemate/web-kit';
 
+// Register a custom theme - returns a typed theme ref
 const brandTheme = registerTheme('brand', {
-  base: 'default', // Inherit from default
+  base: 'default', // Inherit from built-in theme ('default' or 'dark')
   config: {
     typography: {
       fontFamily: '"Inter", system-ui, sans-serif'
@@ -802,7 +858,99 @@ const brandTheme = registerTheme('brand', {
   }
 });
 
+// Use the theme ref (type-safe)
 initWebKit({ theme: brandTheme });
+
+// Or use the string name directly (also works!)
+initWebKit({ theme: 'brand' });
+```
+
+#### Theme Inheritance
+
+Themes can extend other themes using the `base` option:
+
+```typescript
+// Create a base brand theme
+const brandBase = registerTheme('brand-base', {
+  base: 'default',
+  config: {
+    typography: { fontFamily: '"Inter", sans-serif' },
+    vars: { '--ease-panel-radius': '16px' }
+  }
+});
+
+// Create variants that extend brand-base
+const brandLight = registerTheme('brand-light', {
+  base: brandBase, // Can use theme ref or string name
+  config: {
+    colors: {
+      gray: { 900: 'oklab(98% 0 0)', 0: 'oklab(20% 0 0)' }
+    },
+    vars: { '--ease-panel-background': 'white' }
+  }
+});
+
+const brandDark = registerTheme('brand-dark', {
+  base: 'brand-base', // String name works too
+  config: {
+    vars: { '--ease-panel-background': 'var(--color-gray-1000)' }
+  }
+});
+
+// Use with theme mode switching
+initWebKit({
+  theme: {
+    mode: 'system',
+    light: brandLight,
+    dark: brandDark
+  }
+});
+```
+
+#### Creating a Theme from Scratch
+
+Use `base: null` to create a theme without inheriting defaults:
+
+```typescript
+const minimalTheme = registerTheme('minimal', {
+  base: null, // Start fresh, no inheritance
+  config: {
+    colors: {
+      gray: { 900: '#f5f5f5', 0: '#171717' },
+      blue: { 500: '#3b82f6' }
+    },
+    vars: {
+      '--ease-panel-background': 'white',
+      '--ease-panel-border-color': '#e5e5e5'
+    }
+  }
+});
+```
+
+#### Theme Utilities
+
+```typescript
+import { 
+  registerTheme, 
+  getTheme, 
+  hasTheme, 
+  getThemeNames,
+  themeRef 
+} from '@easemate/web-kit';
+
+// Check if a theme exists
+if (hasTheme('brand')) {
+  console.log('Brand theme is registered');
+}
+
+// Get all registered theme names
+const themes = getThemeNames(); // ['default', 'dark', 'brand', ...]
+
+// Get resolved theme config (with inheritance applied)
+const config = getTheme('brand');
+
+// Get a theme ref for an already-registered theme
+const ref = themeRef('brand');
 ```
 
 ### Font Configuration
@@ -958,14 +1106,14 @@ interface WebKitController {
 
 | Export | Description |
 |--------|-------------|
-| `@easemate/web-kit` | Main entry (initWebKit + theme + types) |
-| `@easemate/web-kit/react` | React hooks, utilities, and JSX types |
-| `@easemate/web-kit/react/jsx` | JSX type augmentation only |
-| `@easemate/web-kit/register` | Side-effect registration (all components) |
-| `@easemate/web-kit/elements` | UI components only |
-| `@easemate/web-kit/decorators` | Component decorators |
-| `@easemate/web-kit/theme` | Theming utilities |
-| `@easemate/web-kit/utils` | Utility functions |
+| `@easemate/web-kit` | Main entry: `initWebKit()`, theme utilities, and all types |
+| `@easemate/web-kit/react` | React hooks (`useWebKit`, `useEaseState`), provider, event utilities, and JSX types |
+| `@easemate/web-kit/react/jsx` | JSX type augmentation only (for TypeScript) |
+| `@easemate/web-kit/register` | Side-effect import that registers all components (SSR-safe) |
+| `@easemate/web-kit/elements` | Individual element classes (`Button`, `Slider`, `Panel`, etc.) |
+| `@easemate/web-kit/decorators` | `@Component`, `@Prop`, `@Watch`, `@Listen`, `@Query` decorators |
+| `@easemate/web-kit/theme` | Theme API: `applyTheme`, `createTheme`, `mergeTheme`, `registerTheme` |
+| `@easemate/web-kit/utils` | Template helpers: `classMap`, `styleMap`, `when`, `repeat`, etc. |
 
 ### Panel API
 
@@ -1105,6 +1253,42 @@ const { ready, theme } = useWebKitContext();
 
 ---
 
+## Links
+
+- [Website](https://ease.dev)
+- [Demo](https://ease.zip)
+- [𝕏](https://x.com/@easemate)
+- [GitHub](https://github.com/easemate)
+- [npm](https://www.npmjs.com/package/@easemate/web-kit)
+
+## Authors
+
+<p><strong>Aaron Iker</strong></p>
+<p valign="center">
+  <a href="https://x.com/aaroniker">
+    <img valign="top" src="https://img.shields.io/badge/@aaroniker-black?style=flat-square&logo=x" alt="X">
+  </a>
+  <span valign="center">&nbsp; • &nbsp;</span>
+  <a href="https://github.com/aaroniker">
+    <img valign="top" src="https://img.shields.io/badge/GitHub-aaroniker-black?style=flat-square&logo=github" alt="GitHub">
+  </a>
+  <span valign="center">&nbsp; • &nbsp;</span>
+  <a href="https://www.linkedin.com/in/aaron-iker-15606897/">
+    <img valign="top" src="https://img.shields.io/badge/LinkedIn-aaroniker-blue?style=flat-square&logo=linkedin" alt="LinkedIn">
+  </a>
+</p>
+
+<p><strong>Jakub Antalik</strong></p>
+<p valign="center">
+  <a href="https://x.com/jakubantalik">
+    <img valign="top" src="https://img.shields.io/badge/@jakubantalik-black?style=flat-square&logo=x" alt="X">
+  </a>
+  <span valign="center">&nbsp; • &nbsp;</span>
+  <a href="https://www.linkedin.com/in/jakubantalik/">
+    <img valign="top" src="https://img.shields.io/badge/LinkedIn-jakubantalik-blue?style=flat-square&logo=linkedin" alt="LinkedIn">
+  </a>
+</p>
+
 ## License
 
 MIT © [Aaron Iker](https://github.com/aaroniker)