@mhmo91/schmancy 0.5.46 → 0.6.1

package/readme.md

@@ -1,93 +1,306 @@
 # Schmancy UI Library
 
-Schmancy is a UI library built as web components, designed to provide a collection of reusable and customizable UI elements for modern web applications. It offers an uncomplicated implementation of Material Design 3 (M3), with minor deviations, utilizing [lit.dev](https://lit.dev/) and [Tailwind CSS](https://tailwindcss.com/), and employs [Vite](https://vitejs.dev/) as the build process.
+[![npm version](https://img.shields.io/npm/v/@mhmo91/schmancy.svg)](https://www.npmjs.com/package/@mhmo91/schmancy)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Features
+Schmancy is a modern, production-ready UI component library built as web components. It provides an elegant implementation of Material Design 3 (M3) with minimal deviations, powered by [Lit](https://lit.dev/), [Tailwind CSS](https://tailwindcss.com/), and [RxJS](https://rxjs.dev/).
 
-- **Web Components**: Built using the Web Components standard, ensuring encapsulation and reusability across different projects.
-- **Material Design 3**: Adheres to M3 guidelines, providing a modern and cohesive design language.
-- **Customizable**: Easily style and configure components to match your application's design requirements.
-- **Lightweight**: Minimal dependencies to keep your application performant.
+**Built for developers who value:** Simplicity, type safety, reactive patterns, and accessibility.
+
+## Key Features
+
+- **🧩 Web Components Standard** - Framework-agnostic, works with React, Vue, Angular, or vanilla JS
+- **🎨 Material Design 3** - Modern, cohesive design language with full theming support
+- **⚡ Reactive & Type-Safe** - Built with TypeScript and RxJS for predictable state management
+- **♿ Accessible by Default** - ARIA support, keyboard navigation, and screen reader compatibility
+- **🎯 Tree-Shakeable** - Import only what you need for optimal bundle size
+- **🛠️ Developer-Friendly** - Comprehensive TypeScript types and AI-assisted documentation
 
 ## Installation
 
-To install Schmancy
-use yarn:
-```bash
-yarn add @mhmo91/schmancy
-```
-use npm:
+### Using npm
+
 ```bash
 npm install @mhmo91/schmancy
 ```
 
-
-Alternatively, if you're using Yarn:
+### Using yarn
 
 ```bash
 yarn add @mhmo91/schmancy
 ```
 
-## Usage
+### Peer Dependencies
 
-After installation, you can import and use Schmancy components in your project.
+Schmancy requires Lit and Tailwind CSS as peer dependencies:
+
+```bash
+npm install lit tailwindcss
+```
 
-### Importing All Components
+## Quick Start
 
-To import all components:
+### Import All Components
 
 ```javascript
 import '@mhmo91/schmancy'
 ```
 
-This will make all Schmancy components available for use in your application.
+This makes all Schmancy components available throughout your application.
 
-### Importing Individual Components
+### Import Individual Components
 
-To import a specific component, such as the `schmancy-button`:
+For better tree-shaking and smaller bundle sizes:
 
 ```javascript
 import '@mhmo91/schmancy/button'
+import '@mhmo91/schmancy/input'
+import '@mhmo91/schmancy/select'
 ```
 
-This will load only the `schmancy-button` component, which can be used as follows:
+### Basic Usage
 
 ```html
-<schmancy-button>Click Me</schmancy-button>
-```
+<!-- Buttons with variants -->
+<schmancy-button variant="filled">Primary Action</schmancy-button>
+<schmancy-button variant="outlined">Secondary Action</schmancy-button>
+
+<!-- Form inputs with validation -->
+<schmancy-input
+  label="Email"
+  type="email"
+  required
+  placeholder="you@example.com"
+></schmancy-input>
 
-_Note: Replace `'button'` with the desired component name to import other components individually._
+<!-- Select with options -->
+<schmancy-select label="Choose an option" value="option1">
+  <schmancy-option value="option1">Option 1</schmancy-option>
+  <schmancy-option value="option2">Option 2</schmancy-option>
+</schmancy-select>
+
+<!-- Surfaces with elevation -->
+<schmancy-surface elevation="2" rounded="all" class="p-6">
+  <schmancy-typography type="headline" token="md">Card Title</schmancy-typography>
+  <schmancy-typography type="body" token="md">Card content goes here</schmancy-typography>
+</schmancy-surface>
+```
 
 ## Documentation
 
-For detailed documentation and examples, please visit the [Schmancy Wiki](https://github.com/mhmo91/schmancy/wiki).
-
-Below is a table linking to each component’s documentation on the GitHub Wiki:
-
-| Component                 | Description                     | Documentation                                                                                     |
-| ------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `schmancy-area`           | Area component                  | [Wiki - schmancy-area](https://github.com/mhmo91/schmancy/wiki/schmancy-area)                     |
-| `schmancy-typewriter`     | Typewriter component            | [Wiki - schmancy-area](https://github.com/mhmo91/schmancy/wiki/schmancy-typewriter)               |
-| `schmancy-autocomplete`   | Autocomplete field              | [Wiki - schmancy-autocomplete](https://github.com/mhmo91/schmancy/wiki/schmancy-autocomplete)     |
-| `schmancy-busy`           | Loading/busy indicator          | [Wiki - schmancy-busy](https://github.com/mhmo91/schmancy/wiki/schmancy-busy)                     |
-| `schmancy-button`         | Customizable button             | [Wiki - schmancy-button](https://github.com/mhmo91/schmancy/wiki/schmancy-button)                 |
-| `schmancy-card`           | Card for content display        | [Wiki - schmancy-card](https://github.com/mhmo91/schmancy/wiki/schmancy-card)                     |
-| `schmancy-checkbox`       | Checkbox component              | [Wiki - schmancy-checkbox](https://github.com/mhmo91/schmancy/wiki/schmancy-checkbox)             |
-| `schmancy-chips`          | Chips for display or selection  | [Wiki - schmancy-chips](https://github.com/mhmo91/schmancy/wiki/schmancy-chips)                   |
-| `schmancy-content-drawer` | Collapsible drawer component    | [Wiki - schmancy-content-drawer](https://github.com/mhmo91/schmancy/wiki/schmancy-content-drawer) |
-| `schmancy-divider`        | Divider for separating sections | [Wiki - schmancy-divider](https://github.com/mhmo91/schmancy/wiki/schmancy-divider)               |
-| `schmancy-form`           | Form component                  | [Wiki - schmancy-form](https://github.com/mhmo91/schmancy/wiki/schmancy-form)                     |
-| `schmancy-icons`          | Icon set                        | [Wiki - schmancy-icons](https://github.com/mhmo91/schmancy/wiki/schmancy-icons)                   |
-| `schmancy-input`          | Input field component           | [Wiki - schmancy-input](https://github.com/mhmo91/schmancy/wiki/schmancy-input)                   |
-| `schmancy-layout`         | Layout utility                  | [Wiki - schmancy-layout](https://github.com/mhmo91/schmancy/wiki/schmancy-layout)                 |
-| `schmancy-list`           | List component                  | [Wiki - schmancy-list](https://github.com/mhmo91/schmancy/wiki/schmancy-list)                     |
-| `schmancy-menu`           | Menu component                  | [Wiki - schmancy-menu](https://github.com/mhmo91/schmancy/wiki/schmancy-menu)                     |
-| `schmancy-nav-drawer`     | Navigation drawer               | [Wiki - schmancy-nav-drawer](https://github.com/mhmo91/schmancy/wiki/schmancy-nav-drawer)         |
-| `schmancy-notification`   | Notification component          | [Wiki - schmancy-notification](https://github.com/mhmo91/schmancy/wiki/schmancy-notification)     |
-| `schmancy-option`         | Option selector                 | [Wiki - schmancy-option](https://github.com/mhmo91/schmancy/wiki/schmancy-option)                 |
-| `schmancy-radio-group`    | Radio button group              | [Wiki - schmancy-radio-group](https://github.com/mhmo91/schmancy/wiki/schmancy-radio-group)       |
-| `schmancy-select`         | Select dropdown                 | [Wiki - schmancy-select](https://github.com/mhmo91/schmancy/wiki/schmancy-select)                 |
-| `schmancy-sheet`          | Sheet component                 | [Wiki - schmancy-sheet](https://github.com/mhmo91/schmancy/wiki/schmancy-sheet)                   |
-| `schmancy-surface`        | Surface element                 | [Wiki - schmancy-surface](https://github.com/mhmo91/schmancy/wiki/schmancy-surface)               |
-| `schmancy-table`          | Table component                 | [Wiki - schmancy-table](https://github.com/mhmo91/schmancy/wiki/schmancy-table)                   |
-| `schmancy-tabs`           | Tabbed navigation               | [Wiki - schmancy-tabs](https://github.com/mhmo91/schmancy/wiki/schmancy-tabs)                     |
+### 📚 User Documentation
+
+- **[GitHub Wiki](https://github.com/mhmo91/schmancy/wiki)** - Comprehensive guides, examples, and API reference
+- **[Component Demos](https://schmancy-demo.netlify.app)** - Interactive examples and live playground
+
+### 🤖 AI-Assisted Development
+
+The `/ai/` directory contains concise reference documentation optimized for AI assistants and LLM-based tools:
+
+- **[AI Documentation Index](./ai/index.md)** - Overview and quick reference
+- **[Component Relationships](./ai/component-relationships.md)** - How components work together
+- **[Documentation Template](./ai/template.md)** - Contribution guidelines
+
+#### Component References
+
+<details>
+<summary><strong>Core Components</strong></summary>
+
+- [Animated Text](./ai/animated-text.md) - Animated text effects
+- [Autocomplete](./ai/autocomplete.md) - Searchable input with suggestions
+- [Avatar](./ai/avatar.md) - User profile images
+- [Badge](./ai/badge.md) - Status indicators
+- [Button](./ai/button.md) - Action buttons
+- [Busy/Spinner](./ai/busy.md) - Loading indicators
+- [Card](./ai/card.md) - Content containers
+- [Checkbox](./ai/checkbox.md) - Checkable inputs
+- [Chips](./ai/chips.md) - Compact selection elements
+- [Progress](./ai/progress.md) - Progress indicators
+</details>
+
+<details>
+<summary><strong>Form Elements</strong></summary>
+
+- [Form](./ai/form.md) - Form containers with validation
+- [Input](./ai/input.md) - Text input fields
+- [Option](./ai/option.md) - Select/autocomplete options
+- [Radio Group](./ai/radio-group.md) - Radio button groups
+- [Select](./ai/select.md) - Dropdown selection
+- [Textarea](./ai/textarea.md) - Multi-line text input
+- [Payment Card Form](./ai/payment-card-form.md) - Credit card input
+</details>
+
+<details>
+<summary><strong>Layout & Navigation</strong></summary>
+
+- [Area](./ai/area.md) - Routing system
+- [Content Drawer](./ai/content-drawer.md) - Sliding panels
+- [Details](./ai/details.md) - Expandable content
+- [Divider](./ai/divider.md) - Visual separators
+- [Layout](./ai/layout.md) - Layout utilities (deprecated)
+- [Navigation Bar](./ai/navigation-bar.md) - Bottom navigation
+- [Navigation Bar Item](./ai/navigation-bar-item.md) - Navigation items
+- [Navigation Rail](./ai/navigation-rail.md) - Side navigation
+- [Nav Drawer](./ai/nav-drawer.md) - Navigation drawer
+- [Sheet](./ai/sheet.md) - Bottom/side sheets
+- [Tabs](./ai/tabs.md) - Tabbed interfaces
+</details>
+
+<details>
+<summary><strong>Feedback & Overlays</strong></summary>
+
+- [Dialog](./ai/dialog.md) - Modal dialogs
+- [Dropdown](./ai/dropdown.md) - Floating dropdowns
+- [Menu](./ai/menu.md) - Context menus
+- [Notification](./ai/notification.md) - Toast notifications
+- [Tooltip](./ai/tooltip.md) - Contextual help
+</details>
+
+<details>
+<summary><strong>Data Display</strong></summary>
+
+- [List](./ai/list.md) - Interactive lists
+- [Table](./ai/table.md) - Data tables
+- [Tree](./ai/tree.md) - Hierarchical views
+- [Slider](./ai/slider.md) - Content carousels
+- [Steps](./ai/steps.md) - Step indicators
+</details>
+
+<details>
+<summary><strong>Utilities & Advanced</strong></summary>
+
+- [Code Highlight](./ai/code-highlight.md) - Syntax highlighting
+- [Context](./ai/context.md) - Context API
+- [Countries](./ai/countries.md) - Country selector
+- [Date Range](./ai/date-range.md) - Date range picker
+- [Date Range Inline](./ai/date-range-inline.md) - Inline date picker
+- [Delay](./ai/delay.md) - Delayed rendering
+- [Directives](./ai/directives.md) - Lit directives
+- [Icons](./ai/icons.md) - Material icons
+- [Mailbox](./ai/mailbox.md) - Message inbox
+- [Map](./ai/map.md) - Map integration
+- [Store](./ai/store.md) - State management
+- [Surface](./ai/surface.md) - Elevation system
+- [Teleport](./ai/teleport.md) - FLIP animations
+- [Theme](./ai/theme.md) - Theming system
+- [Theme Button](./ai/theme-button.md) - Theme switcher
+- [Timezone](./ai/timezone.md) - Timezone selector
+- [Typography](./ai/typography.md) - Text styling
+- [Typewriter](./ai/typewriter.md) - Typing animations
+- [Boat](./ai/boat.md) - Advanced layout system
+</details>
+
+### 👨‍💻 Developer Guidelines
+
+If you're contributing to or extending Schmancy, read these essential guides:
+
+- **[CLAUDE.md](./CLAUDE.md)** - Project structure and development workflow
+- **[src/CLAUDE.md](./src/CLAUDE.md)** - Library component patterns and architecture
+- **[demo/CLAUDE.md](./demo/CLAUDE.md)** - Demo creation and testing patterns
+
+## Component Overview
+
+### Core Categories
+
+| Category | Components | Use Cases |
+|----------|-----------|-----------|
+| **Buttons & Actions** | Button, Icon Button, FAB | User interactions, form submissions |
+| **Form Inputs** | Input, Textarea, Select, Autocomplete, Checkbox, Radio Group | Data collection, user preferences |
+| **Navigation** | Tabs, Nav Drawer, Navigation Bar, Area Router | App navigation, content organization |
+| **Feedback** | Dialog, Notification, Tooltip, Progress, Busy | User feedback, loading states |
+| **Layout** | Surface, Card, Divider, Content Drawer | Content structure, visual hierarchy |
+| **Data Display** | Table, List, Tree, Typography | Data presentation, content display |
+| **Advanced** | Theme System, Store, Context API | Theming, state management |
+
+### Architecture Highlights
+
+- **$LitElement Mixin** - Base class providing reactive cleanup, classMap, styleMap, and component discovery
+- **RxJS Integration** - Built-in reactive patterns with automatic cleanup via `takeUntil(this.disconnecting)`
+- **Context System** - Type-safe state management with `@select` decorator and compound selectors
+- **Theme System** - Material Design 3 theming with CSS custom properties and Tailwind integration
+- **Accessibility First** - ARIA attributes, keyboard navigation, and screen reader support built-in
+
+## Development
+
+### Running the Demo Site
+
+```bash
+yarn dev
+```
+
+This starts the development server with live reload at `http://localhost:5173`.
+
+### Building the Library
+
+```bash
+yarn build
+```
+
+Compiles TypeScript and bundles the library to `/dist`.
+
+### Running Tests
+
+```bash
+yarn test          # Run tests once
+yarn test:watch    # Watch mode
+yarn test:ui       # Interactive UI
+yarn test:coverage # With coverage report
+```
+
+### Project Structure
+
+```
+schmancy/
+├── src/              # Library source code
+│   ├── Button/       # Component directories
+│   ├── Input/
+│   └── ...
+├── demo/             # Demo site
+│   └── src/
+│       └── features/ # Component demos
+├── ai/               # AI reference docs
+├── types/            # TypeScript definitions
+└── dist/             # Build output
+```
+
+## Contributing
+
+We welcome contributions! Please:
+
+1. Read the [developer guidelines](./CLAUDE.md)
+2. Check existing [issues](https://github.com/mhmo91/schmancy/issues)
+3. Follow the established patterns in [src/CLAUDE.md](./src/CLAUDE.md)
+4. Add demos following [demo/CLAUDE.md](./demo/CLAUDE.md)
+5. Ensure tests pass and types are correct
+6. Submit a pull request
+
+## Browser Support
+
+Schmancy supports all modern browsers that implement the Web Components standard:
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) file for details.
+
+## Credits
+
+Built with:
+- [Lit](https://lit.dev/) - Efficient web components
+- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS
+- [RxJS](https://rxjs.dev/) - Reactive programming
+- [Material Design 3](https://m3.material.io/) - Design system
+
+## Links
+
+- **npm Package**: [@mhmo91/schmancy](https://www.npmjs.com/package/@mhmo91/schmancy)
+- **GitHub Repository**: [mhmo91/schmancy](https://github.com/mhmo91/schmancy)
+- **Issue Tracker**: [GitHub Issues](https://github.com/mhmo91/schmancy/issues)
+- **Documentation Wiki**: [GitHub Wiki](https://github.com/mhmo91/schmancy/wiki)
+
+---
+
+Made with ❤️ by [@mhmo91](https://github.com/mhmo91)

package/types/src/area/router.types.d.ts

@@ -1,6 +1,10 @@
 import { LazyComponent } from './lazy';
+/**
+ * Component type accepted by area router, drawer, and sheet services
+ */
+export type ComponentType = CustomElementConstructor | string | HTMLElement | LazyComponent<any>;
 export type RouteAction = {
-    component: CustomElementConstructor | string | HTMLElement | LazyComponent<any>;
+    component: ComponentType;
     area: string;
     state?: Record<string, unknown>;
     params?: Record<string, unknown>;

package/types/src/content-drawer/drawer.service.d.ts

@@ -1,5 +1,6 @@
+import { ComponentType } from '../area/router.types';
 type TRef = Element | Window;
-type TRenderRequest = HTMLElement;
+type TRenderRequest = ComponentType;
 export type TRenderCustomEvent = CustomEvent<{
     component: TRenderRequest;
     title?: string;
@@ -7,9 +8,6 @@ export type TRenderCustomEvent = CustomEvent<{
     params?: Record<string, unknown>;
     props?: Record<string, unknown>;
 }>;
-type ComponentType = string | HTMLElement | (() => HTMLElement) | (() => Promise<{
-    default: any;
-}>);
 export type DrawerPushOptions = {
     component: ComponentType;
     state?: Record<string, unknown>;
@@ -18,14 +16,12 @@ export type DrawerPushOptions = {
 };
 declare class DrawerService {
     private $drawer;
-    private lastComponent;
     constructor();
     private dispatchToggleEvent;
     private dispatchRenderEvent;
     dimiss(ref: TRef): void;
     render(ref: TRef, component: TRenderRequest, title?: string): void;
     private handlePush;
-    private resolveComponent;
     /**
      * Push a component to the content drawer
      * @param options - Component configuration object with optional state/params/props

package/types/src/mailbox/email-editor.d.ts

@@ -1,5 +1,5 @@
-import type { EmailAttachment, EmailComposeConfig, EmailTemplate } from './types';
 import './email-layout-selector';
+import type { EmailAttachment, EmailComposeConfig, EmailTemplate } from './types';
 declare const SchmancyEmailEditor_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
  * Email editor component with rich text formatting and file attachments

package/types/src/navigation-bar/navigation-bar.d.ts

@@ -3,21 +3,35 @@ declare const SchmancyNavigationBar_base: import("../../mixins").Constructor<Cus
  * `<schmancy-navigation-bar>` component
  *
  * A horizontal navigation component following Material Design 3 specifications.
- * Navigation bars provide access to between 3-7 primary destinations, fixed at the bottom of the viewport.
+ * Navigation bars provide access to between 3-7 primary destinations.
  * Automatically hides in fullscreen mode when triggered via schmancyTheme.next({ fullscreen: true }).
  *
+ * **IMPORTANT**: This component does not apply positioning by default. The consumer is responsible
+ * for positioning the navigation bar in their layout. For typical bottom-fixed positioning, add:
+ * `class="fixed bottom-0 left-0 right-0 z-10"` or similar CSS to position the component.
+ *
  * @element schmancy-navigation-bar
  * @slot - Default slot for navigation bar items
  *
  * @fires navigation-change - When an item is selected
  *
  * @example
- * <schmancy-navigation-bar activeIndex="0">
+ * <!-- Fixed at bottom (typical usage) -->
+ * <schmancy-navigation-bar activeIndex="0" class="fixed bottom-0 left-0 right-0 z-10">
  *   <schmancy-navigation-bar-item icon="home" label="Home"></schmancy-navigation-bar-item>
  *   <schmancy-navigation-bar-item icon="search" label="Search"></schmancy-navigation-bar-item>
  *   <schmancy-navigation-bar-item icon="favorite" label="Favorites"></schmancy-navigation-bar-item>
  *   <schmancy-navigation-bar-item icon="settings" label="Settings"></schmancy-navigation-bar-item>
  * </schmancy-navigation-bar>
+ *
+ * @example
+ * <!-- Within a container (demo/mockup usage) -->
+ * <div class="flex flex-col h-screen">
+ *   <main class="flex-1">Content</main>
+ *   <schmancy-navigation-bar activeIndex="0">
+ *     <schmancy-navigation-bar-item icon="home" label="Home"></schmancy-navigation-bar-item>
+ *   </schmancy-navigation-bar>
+ * </div>
  */
 export declare class SchmancyNavigationBar extends SchmancyNavigationBar_base {
     /**

package/types/src/sheet/sheet.service.d.ts

@@ -1,19 +1,17 @@
 import { Subject } from 'rxjs';
+import { ComponentType } from '../area/router.types';
 import SchmancySheet from './sheet';
 export declare enum SchmancySheetPosition {
     Side = "side",
     Bottom = "bottom"
 }
 export type SheetConfig = {
-    component: HTMLElement;
+    component: ComponentType;
     uid?: string;
     position?: SchmancySheetPosition;
     persist?: boolean;
     close?: () => void;
     lock?: boolean;
-    handleHistory?: boolean;
-    title?: string;
-    header?: 'hidden' | 'visible';
     onBeforeOpen?: (component: HTMLElement) => void;
     onAfterOpen?: (component: HTMLElement) => void;
 };
@@ -31,7 +29,6 @@ declare class BottomSheetService {
     bottomSheet: Subject<SheetConfig>;
     $dismiss: Subject<string>;
     private activeSheets;
-    private sheetComponents;
     private popStateListenerActive;
     constructor();
     /**
@@ -62,12 +59,6 @@ declare class BottomSheetService {
      * Close all open sheets
      */
     closeAll(): void;
-    /**
-     * Gets the component instance for a given sheet
-     * @param uid - The unique identifier of the sheet
-     * @returns The component instance, or undefined if not found
-     */
-    getComponent<T extends HTMLElement = HTMLElement>(uid: string): T | undefined;
 }
 export declare const sheet: BottomSheetService;
 export {};