@easemate/web-kit 0.3.2 → 0.3.4

package/README.md

@@ -41,6 +41,7 @@ A modern, framework-agnostic UI kit of web components for building animation con
 - [Usage Examples](#usage-examples)
   - [Basic Controls](#basic-controls)
   - [Panel Component](#panel-component)
+  - [Folder Component](#folder-component)
   - [State Component](#state-component)
   - [Combined Panel + State](#combined-panel--state)
   - [JavaScript Integration](#javascript-integration)
@@ -63,9 +64,12 @@ A modern, framework-agnostic UI kit of web components for building animation con
   - [Controller API](#controller-api)
   - [Package Exports](#package-exports)
   - [Panel API](#panel-api)
+  - [Folder API](#folder-api)
   - [State API](#state-api)
 - [Accessibility](#accessibility)
 - [SSR Support](#ssr-support)
+- [Links](#links)
+- [Authors](#authors)
 - [License](#license)
 
 ---
@@ -186,7 +190,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';
@@ -197,12 +205,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
@@ -324,8 +346,7 @@ function AnimationControls() {
   );
 
   return (
-    <ease-panel ref={panelRef}>
-      <span slot="headline">Animation</span>
+    <ease-panel ref={panelRef} headline="Animation">
       <ease-state ref={stateRef}>
         <ease-field label="Duration">
           <ease-slider name="duration" value="1" min="0" max="5" step="0.1" />
@@ -444,6 +465,7 @@ const handleChange = createEventHandler<ControlChangeEvent>((e) => {
 | Component | Tag | Description |
 |-----------|-----|-------------|
 | Panel | `<ease-panel>` | Visual container with tabs, header, and footer |
+| Folder | `<ease-folder>` | Collapsible container for grouping controls |
 | State | `<ease-state>` | State aggregator for controls (no visual styling) |
 | Field | `<ease-field>` | Label + control wrapper |
 | Button | `<ease-button>` | Action button |
@@ -462,13 +484,40 @@ 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-folder` | Animated folder open/close icon |
+| `ease-icon-grid` | Animated grid icon |
+| `ease-icon-loading` | Animated loading spinner |
+| `ease-icon-snap` | Animated snap indicator |
 
 ---
 
@@ -490,15 +539,14 @@ The `<ease-panel>` component provides the visual container with optional tabs, h
 
 ```html
 <!-- Simple panel with headline -->
-<ease-panel>
-  <span slot="headline">Settings</span>
+<ease-panel headline="Settings">
   <div>
     <!-- Your content here -->
   </div>
 </ease-panel>
 
 <!-- Panel with tabs -->
-<ease-panel active-tab="0">
+<ease-panel headline="Animation" active-tab="0">
   <div slot="tab-general" data-tab-label="General">
     <!-- General settings -->
   </div>
@@ -508,8 +556,7 @@ The `<ease-panel>` component provides the visual container with optional tabs, h
 </ease-panel>
 
 <!-- Panel with header actions -->
-<ease-panel>
-  <span slot="headline">Controls</span>
+<ease-panel headline="Controls">
   <button slot="actions" title="Settings">
     <ease-icon-settings></ease-icon-settings>
   </button>
@@ -520,6 +567,40 @@ The `<ease-panel>` component provides the visual container with optional tabs, h
     <ease-button>Save</ease-button>
   </div>
 </ease-panel>
+
+<!-- Panel with max-height (scrollable) -->
+<ease-panel headline="Scrollable Panel" max-height="250px">
+  <!-- Content will scroll when it exceeds 250px -->
+</ease-panel>
+```
+
+### Folder Component
+
+The `<ease-folder>` component provides a collapsible container for grouping controls. Click the header to toggle open/closed.
+
+```html
+<!-- Basic folder (closed by default) -->
+<ease-folder headline="Transform">
+  <ease-field label="X">
+    <ease-number-input name="x" value="0"></ease-number-input>
+  </ease-field>
+  <ease-field label="Y">
+    <ease-number-input name="y" value="0"></ease-number-input>
+  </ease-field>
+</ease-folder>
+
+<!-- Open folder -->
+<ease-folder open headline="Appearance">
+  <ease-field label="Color">
+    <ease-color-input name="color" value="#3b82f6"></ease-color-input>
+  </ease-field>
+</ease-folder>
+
+<!-- Folder with max-height (scrollable with fade masks) -->
+<ease-folder headline="Animation" max-height="150px">
+  <!-- Many fields here will scroll with fade effect -->
+</ease-folder>
+
 ```
 
 ### State Component
@@ -549,9 +630,7 @@ The `<ease-state>` component aggregates state from child controls. It can be use
 For a complete control panel experience, combine `<ease-panel>` with `<ease-state>`:
 
 ```html
-<ease-panel>
-  <span slot="headline">Animation Controls</span>
-  
+<ease-panel headline="Animation Controls">
   <button slot="actions" title="Reset">
     <ease-icon-minus></ease-icon-minus>
   </button>
@@ -585,7 +664,7 @@ For a complete control panel experience, combine `<ease-panel>` with `<ease-stat
 When using tabs with state, place the `<ease-state>` inside each tab:
 
 ```html
-<ease-panel active-tab="0">
+<ease-panel headline="Animation" active-tab="0">
   <button slot="actions" title="Reset">
     <ease-icon-minus></ease-icon-minus>
   </button>
@@ -1028,12 +1107,12 @@ setThemeName('light', { colorScheme: 'light' });
 | Category | Variables |
 |----------|-----------|
 | Typography | `--ease-font-family`, `--ease-font-mono`, `--ease-font-size`, `--ease-line-height` |
-| Panel | `--ease-panel-max-width`, `--ease-panel-padding`, `--ease-panel-radius`, `--ease-panel-background`, `--ease-panel-border-color`, `--ease-panel-shadow` |
-| Panel Title | `--ease-panel-title-font-size`, `--ease-panel-title-font-weight`, `--ease-panel-title-line-height`, `--ease-panel-title-color` |
-| Panel Tabs | `--ease-panel-tab-font-size`, `--ease-panel-tab-font-weight`, `--ease-panel-tab-line-height`, `--ease-panel-tab-color`, `--ease-panel-tab-color-hover`, `--ease-panel-tab-color-active`, `--ease-panel-tab-background-active`, `--ease-panel-tab-radius` |
+| Panel | `--ease-panel-max-width`, `--ease-panel-padding`, `--ease-panel-radius`, `--ease-panel-background`, `--ease-panel-border-color`, `--ease-panel-shadow`, `--ease-panel-gap`, `--ease-panel-header-spacing`, `--ease-panel-fade-size` |
+| Panel Title | `--ease-panel-title-font-size`, `--ease-panel-title-font-weight`, `--ease-panel-title-color` |
+| Panel Tabs | `--ease-panel-tab-font-size`, `--ease-panel-tab-font-weight`, `--ease-panel-tab-color`, `--ease-panel-tab-color-hover`, `--ease-panel-tab-color-active`, `--ease-panel-tab-background-active`, `--ease-panel-tab-radius` |
 | Panel Actions | `--ease-panel-action-icon-size` |
 | Panel Footer | `--ease-panel-footer-padding` |
-| Panel Transitions | `--ease-panel-transition-duration`, `--ease-panel-transition-easing` |
+| Folder | `--ease-folder-padding`, `--ease-folder-radius`, `--ease-folder-border-color`, `--ease-folder-background`, `--ease-folder-shadow`, `--ease-folder-gap`, `--ease-folder-title-font-size`, `--ease-folder-title-font-weight`, `--ease-folder-title-color`, `--ease-folder-icon-color`, `--ease-folder-chevron-color`, `--ease-folder-chevron-color-hover`, `--ease-folder-fade-size` |
 | Field | `--ease-field-label-width`, `--ease-field-column-gap`, `--ease-field-row-gap` |
 | Controls | Each control exposes `--ease-<component>-*` tokens |
 
@@ -1060,14 +1139,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
 
@@ -1077,7 +1156,9 @@ The `<ease-panel>` component provides the visual container.
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
+| `headline` | `string \| null` | `null` | Panel title text displayed in the header |
 | `activeTab` | `number` | `0` | Zero-based index of the active tab |
+| `maxHeight` | `string \| null` | `null` | Maximum height for scrollable content (e.g., "250px") |
 
 #### Methods
 
@@ -1089,7 +1170,6 @@ The `<ease-panel>` component provides the visual container.
 
 | Slot | Description |
 |------|-------------|
-| `headline` | Panel title text (hidden when tabs are present) |
 | `actions` | Header action buttons, links, or dropdowns |
 | (default) | Main content area (used when no tabs) |
 | `tab-{id}` | Tab panel content (use `data-tab-label` for display name) |
@@ -1106,7 +1186,8 @@ The `<ease-panel>` component provides the visual container.
 | `tab` | Individual tab button |
 | `actions` | Actions container |
 | `content` | Content wrapper (handles height animations) |
-| `body` | Inner body container |
+| `body` | Inner body container (scrollable when max-height is set) |
+| `items` | Grid container for slotted content |
 | `tab-panel` | Individual tab panel |
 | `footer` | Footer container |
 
@@ -1124,6 +1205,59 @@ interface TabChangeEventDetail {
 }
 ```
 
+### Folder API
+
+The `<ease-folder>` component provides a collapsible container for grouping controls.
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `headline` | `string \| null` | `null` | Folder title text displayed in the header |
+| `open` | `boolean` | `false` | Whether the folder is expanded |
+| `maxHeight` | `string \| null` | `null` | Maximum height for scrollable content (e.g., "150px") |
+
+#### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `toggle` | `() => void` | Toggle the folder open/closed state |
+
+#### Slots
+
+| Slot | Description |
+|------|-------------|
+| (default) | Folder content (fields and controls) |
+
+#### CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `section` | Outer container |
+| `header` | Clickable header row |
+| `icon` | Folder icon |
+| `headline` | Title element |
+| `chevron` | Chevron icon (toggle indicator) |
+| `content` | Content wrapper (handles height animations) |
+| `body` | Inner body container (scrollable when max-height is set) |
+
+#### Events
+
+| Event | Detail Type | Description |
+|-------|-------------|-------------|
+| `folder-toggle` | `FolderToggleEventDetail` | Fired when the folder is opened or closed |
+
+```typescript
+interface FolderToggleEventDetail {
+  open: boolean;             // Whether the folder is now open
+  event: Event;              // Original event
+}
+```
+
+#### Scrollable Content
+
+When `max-height` is set, the folder content becomes scrollable with fade gradient masks at the top and bottom edges. The masks automatically appear/disappear based on scroll position using scroll-driven animations.
+
 ### State API
 
 The `<ease-state>` component provides state management for controls.
@@ -1207,6 +1341,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)

package/build/decorators.cjs

@@ -29,7 +29,7 @@ __export(decorators_exports, {
 });
 module.exports = __toCommonJS(decorators_exports);
 
-// swc:/home/runner/work/web-kit/web-kit/packages/core/src/decorators/Component.ts
+// swc:/Users/aaroniker/Documents/GitHub/ease/web-kit/packages/core/src/decorators/Component.ts
 var import_lit_html = require("lit-html");
 var styleCache = /* @__PURE__ */ new Map();
 var normalizeTemplate = (template) => {
@@ -163,7 +163,7 @@ var Component = (options) => (Base, _context) => {
   return Decorated;
 };
 
-// swc:/home/runner/work/web-kit/web-kit/packages/core/src/decorators/Listen.ts
+// swc:/Users/aaroniker/Documents/GitHub/ease/web-kit/packages/core/src/decorators/Listen.ts
 var lifecycleHooks = {
   connectedCallback: /* @__PURE__ */ new WeakMap(),
   disconnectedCallback: /* @__PURE__ */ new WeakMap()
@@ -309,7 +309,7 @@ function Listen(eventName, selectorOrOptions) {
   };
 }
 
-// swc:/home/runner/work/web-kit/web-kit/packages/core/src/utils/dismiss-controller.ts
+// swc:/Users/aaroniker/Documents/GitHub/ease/web-kit/packages/core/src/utils/dismiss-controller.ts
 var DismissController = class {
   #onDismiss;
   #context;
@@ -460,7 +460,7 @@ var disconnectOutsideClickHandles = (host) => {
   });
 };
 
-// swc:/home/runner/work/web-kit/web-kit/packages/core/src/decorators/OutsideClick.ts
+// swc:/Users/aaroniker/Documents/GitHub/ease/web-kit/packages/core/src/decorators/OutsideClick.ts
 var lifecycleApplied = /* @__PURE__ */ new WeakSet();
 var wrapMethod = (host, name, hook, callHookFirst = false) => {
   const original = host[name];
@@ -518,7 +518,7 @@ function OutsideClick(options = {}) {
   };
 }
 
-// swc:/home/runner/work/web-kit/web-kit/packages/core/src/decorators/Prop.ts
+// swc:/Users/aaroniker/Documents/GitHub/ease/web-kit/packages/core/src/decorators/Prop.ts
 var renderQueue = /* @__PURE__ */ new WeakMap();
 var cleanupRegistry2 = /* @__PURE__ */ new WeakMap();
 var observerRegistry = /* @__PURE__ */ new WeakMap();
@@ -783,7 +783,7 @@ function Prop(options = {}) {
   };
 }
 
-// swc:/home/runner/work/web-kit/web-kit/packages/core/src/decorators/Query.ts
+// swc:/Users/aaroniker/Documents/GitHub/ease/web-kit/packages/core/src/decorators/Query.ts
 var defaultOptions = {
   all: false,
   closest: false,
@@ -859,7 +859,7 @@ function Query(selector, userOptions) {
   return createQueryDecorator(selector, merged);
 }
 
-// swc:/home/runner/work/web-kit/web-kit/packages/core/src/decorators/Watch.ts
+// swc:/Users/aaroniker/Documents/GitHub/ease/web-kit/packages/core/src/decorators/Watch.ts
 var renderQueue2 = /* @__PURE__ */ new WeakMap();
 var scheduleRender2 = (instance) => {
   if (typeof instance.requestRender === "function") {