@mhmo91/schmancy 0.8.6 → 0.9.3

package/types/src/typography/typography.d.ts

@@ -4,6 +4,7 @@ declare const SchmancyTypography_base: import("../../mixins").Constructor<Custom
  * @slot - The text for the typography.
  */
 export declare class SchmancyTypography extends SchmancyTypography_base {
+    static shadowRootOptions: ShadowRootInit;
     /**
      * @attr type - The type of the typography.
      * @default 'body'
@@ -11,11 +12,14 @@ export declare class SchmancyTypography extends SchmancyTypography_base {
      */
     type: 'display' | 'headline' | 'title' | 'subtitle' | 'body' | 'label';
     /**
-     * @attr token - The token of the typography.
+     * @attr token - The size token.
+     * @deprecated Prefer using Tailwind responsive text classes for better responsive design.
+     * Set token="" and use class="text-sm md:text-base lg:text-lg" instead.
+     * Example: <schmancy-typography type="display" token="" class="text-2xl sm:text-3xl md:text-4xl">
      * @default 'md'
-     * @type {'xs' | 'sm' | 'md' | 'lg' | 'xl'}
+     * @type {'xs' | 'sm' | 'md' | 'lg' | 'xl' | ''}
      */
-    token: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    token: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '';
     /**
      * @attr
      * @default inherit
@@ -38,6 +42,16 @@ export declare class SchmancyTypography extends SchmancyTypography_base {
      */
     transform: 'uppercase' | 'lowercase' | 'capitalize' | 'normal' | undefined;
     maxLines: 1 | 2 | 3 | 4 | 5 | 6 | undefined;
+    /** When true, the element becomes contenteditable and dispatches 'change' events on blur/Enter */
+    editable: boolean;
+    /** The text value when in editable mode. Set via property binding: .value=${...} */
+    value: string;
+    /** Placeholder shown when editable and empty */
+    placeholder: string;
+    private _editRef;
+    /** Focus and select all text in editable mode */
+    selectAll(): void;
+    connectedCallback(): void;
     protected updated(changedProperties: Map<string, unknown>): void;
     protected render(): unknown;
 }

package/types/src/utils/animation.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Blackbird Animation System
+ *
+ * A comprehensive animation system using spring physics for natural,
+ * organic motion. Named after the smooth, arcing flight patterns of birds.
+ *
+ * Features:
+ * - Spring physics via CSS linear() (88% browser support)
+ * - Cubic-bezier fallbacks for older browsers
+ * - Typed interfaces for Web Animations API
+ * - CSS custom properties for Tailwind integration
+ * - Multiple presets: smooth, snappy, bouncy
+ *
+ * @see https://www.joshwcomeau.com/animation/linear-timing-function/
+ * @see https://developer.chrome.com/docs/css-ui/css-linear-easing-function
+ */
+/** Spring configuration parameters */
+export interface SpringConfig {
+    /** Spring stiffness (higher = faster) */
+    stiffness: number;
+    /** Damping ratio (higher = less bounce) */
+    damping: number;
+    /** Mass (higher = slower) */
+    mass: number;
+}
+/** Animation preset with all timing values */
+export interface AnimationPreset {
+    /** Human-readable name */
+    name: string;
+    /** Duration in milliseconds */
+    duration: number;
+    /** CSS linear() easing function (modern browsers) */
+    easing: string;
+    /** Cubic-bezier fallback (all browsers) */
+    easingFallback: string;
+    /** Spring configuration used to generate this preset */
+    spring: SpringConfig;
+}
+/** Keyframe options for Web Animations API */
+export interface BlackbirdKeyframes {
+    /** Starting state */
+    from: Keyframe;
+    /** Ending state */
+    to: Keyframe;
+}
+/** Complete animation configuration */
+export interface BlackbirdAnimation {
+    keyframes: Keyframe[];
+    options: KeyframeAnimationOptions;
+}
+/**
+ * Smooth preset - Apple-style, subtle overshoot
+ * Best for: Details, accordions, content reveals
+ */
+export declare const SPRING_SMOOTH: AnimationPreset;
+/**
+ * Snappy preset - Quick with minimal overshoot
+ * Best for: Buttons, toggles, quick interactions
+ */
+export declare const SPRING_SNAPPY: AnimationPreset;
+/**
+ * Bouncy preset - Playful with noticeable overshoot
+ * Best for: Notifications, celebrations, attention-grabbing
+ */
+export declare const SPRING_BOUNCY: AnimationPreset;
+/**
+ * Gentle preset - Slow, smooth, no overshoot
+ * Best for: Page transitions, modal backgrounds, subtle reveals
+ */
+export declare const SPRING_GENTLE: AnimationPreset;
+/** @deprecated Use SPRING_SMOOTH.easingFallback instead */
+export declare const BLACKBIRD_EASING: string;
+/** Standard easing for smooth transitions */
+export declare const EASE_OUT = "ease-out";
+export declare const EASE_IN = "ease-in";
+/** Standard durations */
+export declare const DURATION_ENTER: number;
+export declare const DURATION_EXIT = 150;
+export declare const DURATION_BACKDROP = 200;
+/**
+ * CSS custom properties for use in stylesheets.
+ * These can be injected into :root or a component's styles.
+ *
+ * @example
+ * ```css
+ * :root {
+ *   ${ANIMATION_CSS_VARS}
+ * }
+ *
+ * .element {
+ *   transition: transform var(--blackbird-duration-smooth) var(--blackbird-easing-smooth);
+ * }
+ * ```
+ */
+export declare const ANIMATION_CSS_VARS: string;
+/**
+ * Get the appropriate easing function based on browser support.
+ * Uses linear() if supported, falls back to cubic-bezier.
+ */
+export declare function getEasing(preset: AnimationPreset): string;
+/**
+ * Check if the browser supports reduced motion preference.
+ */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Create a Web Animations API animation configuration.
+ *
+ * @example
+ * ```ts
+ * const anim = createAnimation(SPRING_SMOOTH, {
+ *   from: { opacity: 0, transform: 'translateY(-16px)' },
+ *   to: { opacity: 1, transform: 'translateY(0)' }
+ * })
+ *
+ * element.animate(anim.keyframes, anim.options)
+ * ```
+ */
+export declare function createAnimation(preset: AnimationPreset, keyframes: BlackbirdKeyframes): BlackbirdAnimation;
+/**
+ * Create a reveal animation (fade in + slide up).
+ * Common pattern for content appearing.
+ */
+export declare function createRevealAnimation(preset?: AnimationPreset, distance?: number): BlackbirdAnimation;
+/**
+ * Create a dismiss animation (fade out + slide up).
+ * Common pattern for content disappearing.
+ */
+export declare function createDismissAnimation(preset?: AnimationPreset, distance?: number): BlackbirdAnimation;
+/**
+ * Create a scale animation (pop in/out).
+ * Common pattern for buttons and interactive elements.
+ */
+export declare function createScaleAnimation(preset?: AnimationPreset, fromScale?: number, toScale?: number): BlackbirdAnimation;
+/**
+ * Tailwind CSS animation utilities configuration.
+ * Import this into your tailwind.config.js to add Blackbird animations.
+ *
+ * @example
+ * ```js
+ * // tailwind.config.js
+ * const { tailwindAnimations } = require('@mhmo91/schmancy/utils/animation')
+ *
+ * module.exports = {
+ *   theme: {
+ *     extend: {
+ *       ...tailwindAnimations
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare const tailwindAnimations: {
+    transitionTimingFunction: {
+        'spring-smooth': string;
+        'spring-snappy': string;
+        'spring-bouncy': string;
+        'spring-gentle': string;
+    };
+    transitionDuration: {
+        'spring-smooth': string;
+        'spring-snappy': string;
+        'spring-bouncy': string;
+        'spring-gentle': string;
+    };
+    keyframes: {
+        'blackbird-reveal': {
+            '0%': {
+                opacity: string;
+                transform: string;
+            };
+            '100%': {
+                opacity: string;
+                transform: string;
+            };
+        };
+        'blackbird-dismiss': {
+            '0%': {
+                opacity: string;
+                transform: string;
+            };
+            '100%': {
+                opacity: string;
+                transform: string;
+            };
+        };
+        'blackbird-scale-in': {
+            '0%': {
+                opacity: string;
+                transform: string;
+            };
+            '100%': {
+                opacity: string;
+                transform: string;
+            };
+        };
+        'blackbird-scale-out': {
+            '0%': {
+                opacity: string;
+                transform: string;
+            };
+            '100%': {
+                opacity: string;
+                transform: string;
+            };
+        };
+        'blackbird-slide-up': {
+            '0%': {
+                transform: string;
+            };
+            '100%': {
+                transform: string;
+            };
+        };
+        'blackbird-slide-down': {
+            '0%': {
+                transform: string;
+            };
+            '100%': {
+                transform: string;
+            };
+        };
+    };
+    animation: {
+        'blackbird-reveal': string;
+        'blackbird-dismiss': string;
+        'blackbird-scale-in': string;
+        'blackbird-scale-out': string;
+        'blackbird-slide-up': string;
+        'blackbird-slide-down': string;
+    };
+};
+/**
+ * CSS string with spring-based grid animation for details/accordions.
+ * Use with grid-template-rows for smooth height animation.
+ *
+ * @example
+ * ```ts
+ * import { css } from 'lit'
+ * import { GRID_ANIMATION_CSS } from '@mhmo91/schmancy'
+ *
+ * static styles = css`
+ *   ${GRID_ANIMATION_CSS}
+ *
+ *   .content {
+ *     display: grid;
+ *     grid-template-rows: 0fr;
+ *   }
+ *   .content[data-open='true'] {
+ *     grid-template-rows: 1fr;
+ *   }
+ * `
+ * ```
+ */
+export declare const GRID_ANIMATION_CSS: string;

package/types/src/utils/index.d.ts

@@ -1,4 +1,6 @@
+export * from './animation.js';
 export * from './hashContent.js';
 export * from './intersection.js';
 export * from './number.js';
+export * from './overlay-stack.js';
 export * from './search.js';

package/types/src/utils/number.d.ts

@@ -1,4 +1,9 @@
 export declare class Numbers {
+    /**
+     * The system locale detected from user's browser/OS settings.
+     * Use this for display formatting. For exports, use explicit locale like 'de-DE'.
+     */
+    readonly systemLocale: string;
     /**
      * Rounds a number to the specified number of decimal places.
      * @param {number} number - The number to round.
@@ -8,10 +13,19 @@ export declare class Numbers {
     roundNumber(number: number, decimalPlaces?: number): number;
     /**
      * Formats a number according to the specified locale and options.
+     * Uses the user's system locale by default for display formatting.
+     *
      * @param {number} number - The number to format.
-     * @param {string} [locale='de-DE'] - The locale string (e.g., 'de-DE' for German).
+     * @param {string} [locale] - The locale string (e.g., 'de-DE'). Defaults to system locale.
      * @param {Intl.NumberFormatOptions} [options={}] - Additional formatting options.
      * @returns {string} - The formatted number as a string.
+     *
+     * @example
+     * // Uses system locale (e.g., user's browser setting)
+     * numbers.formatNumber(1234.56)
+     *
+     * // Explicit locale for exports (bank systems expect German format)
+     * numbers.formatNumber(1234.56, 'de-DE', { useGrouping: false })
      */
     formatNumber(number: number, locale?: string, options?: Intl.NumberFormatOptions): string;
     /**
@@ -23,9 +37,11 @@ export declare class Numbers {
     parseToPureNumber(numberString: string, decimalSeparator?: string): number;
     /**
      * Rounds a number to the specified decimal places and formats it according to the specified locale and options.
+     * Uses the user's system locale by default.
+     *
      * @param {number} number - The number to process.
      * @param {number} [decimalPlaces=2] - The number of decimal places to round to.
-     * @param {string} [locale='de-DE'] - The locale string.
+     * @param {string} [locale] - The locale string. Defaults to system locale.
      * @param {Intl.NumberFormatOptions} [options={}] - Additional formatting options.
      * @returns {string} - The formatted number as a string.
      */

package/types/src/utils/overlay-stack.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Global overlay stack manager for coordinating z-index across dialogs, sheets, and windows.
+ * Each overlay gets a unique, incrementing z-index to ensure proper stacking.
+ *
+ * Two modes:
+ *   Anonymous (dialogs/sheets): getNextZIndex() / release() — fire-and-forget counter
+ *   ID-tracked (windows): assignZIndex(id) / bringToFront(id) / releaseId(id) — per-window stacking
+ */
+declare class OverlayStackManager {
+    private static instance;
+    private counter;
+    private readonly BASE_Z_INDEX;
+    /** ID-tracked z-index assignments for windows */
+    private idMap;
+    private constructor();
+    static getInstance(): OverlayStackManager;
+    /**
+     * Get the next z-index for a new overlay.
+     * Each call increments the counter, so overlays stack in open order.
+     */
+    getNextZIndex(): number;
+    /**
+     * Release a z-index when overlay closes.
+     * When all overlays close, reset counter to avoid unbounded growth.
+     */
+    release(): void;
+    /**
+     * Get current overlay count (for debugging)
+     */
+    get activeCount(): number;
+    /**
+     * Assign a z-index to an ID. If already assigned, returns the existing value.
+     */
+    assignZIndex(id: string): number;
+    /**
+     * Move a tracked ID to the highest z-index (bring to front).
+     * Returns the new z-index.
+     */
+    bringToFront(id: string): number;
+    /**
+     * Release a tracked ID's z-index.
+     */
+    releaseId(id: string): void;
+    /**
+     * Get the z-index for a tracked ID, or undefined if not tracked.
+     */
+    getZIndex(id: string): number | undefined;
+    /**
+     * Get all tracked IDs sorted by z-index (lowest first, front-most last).
+     */
+    getStackOrder(): string[];
+}
+export declare const overlayStack: OverlayStackManager;
+export {};

package/types/src/window/index.d.ts

@@ -0,0 +1,3 @@
+export { default as SchmancyWindow } from './window';
+export { windowManager } from './window-manager';
+export type { WindowBounds, WindowRecord, WindowRegistryState, WindowVisualState, SnapCorner, SnapTarget, } from './window-registry';

package/types/src/window/window-manager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Window Manager — singleton service for multi-window coordination.
+ *
+ * Tracks all schmancy-window instances: positions, z-indices, focus, visual states.
+ * Components register on connectedCallback, unregister on disconnectedCallback.
+ * Focus changes, position updates, and overlap queries all flow through here.
+ *
+ * Follows the ThemeService singleton pattern (theme/theme.service.ts).
+ *
+ * Example:
+ *   windowManager.register('chat-1', bounds, 'bottom-right')
+ *   windowManager.focus('chat-1')  // bumps z-index, updates focusedId
+ *   const overlaps = windowManager.findOverlaps(projectedBounds, 'chat-1')
+ */
+import { Observable } from 'rxjs';
+import type { WindowBounds, WindowRecord, WindowRegistryState, SnapTarget } from './window-registry.js';
+declare class WindowManagerService {
+    private static instance;
+    private readonly _state$;
+    readonly state$: Observable<WindowRegistryState>;
+    private constructor();
+    static getInstance(): WindowManagerService;
+    get windows(): Map<string, WindowRecord>;
+    get focusedId(): string | null;
+    register(id: string, initialBounds: WindowBounds, snapTarget: SnapTarget): void;
+    unregister(id: string): void;
+    updateBounds(id: string, bounds: WindowBounds): void;
+    updateVisualState(id: string, visualState: WindowRecord['visualState']): void;
+    updateOpen(id: string, open: boolean): void;
+    focus(id: string): void;
+    findOverlaps(bounds: WindowBounds, excludeId: string): WindowRecord[];
+    getNeighbors(id: string): WindowRecord[];
+    selectWindow(id: string): Observable<WindowRecord | undefined>;
+    selectFocused(): Observable<string | null>;
+    loadPosition(id: string): {
+        x: number;
+        y: number;
+        anchor: string;
+    } | null;
+    savePosition(id: string, data: {
+        x: number;
+        y: number;
+        anchor: string;
+    }): void;
+    clearPosition(id: string): void;
+    private _updateRecord;
+}
+export declare const windowManager: WindowManagerService;
+export {};

package/types/src/window/window-position.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Window Position — pure functions for overlap resolution, cascade, and snapping.
+ *
+ * All functions are stateless: they take window bounds and viewport dimensions,
+ * return new bounds. No side effects, no DOM access, no subscriptions.
+ *
+ * Example:
+ *   const projected = { left: 100, top: 400, width: 360, height: 500 }
+ *   const neighbors = windowManager.findOverlaps(projected, 'my-id')
+ *   const resolved = resolveOverlap(projected, neighbors, { width: 1440, height: 900 })
+ *   // → { left: 144, top: 444, width: 360, height: 500 } (cascaded away from conflict)
+ */
+import type { WindowBounds, WindowRecord, SnapCorner } from './window-registry.js';
+/** Check if two rectangles overlap (edges touching does NOT count as overlap) */
+export declare function rectsOverlap(a: WindowBounds, b: WindowBounds): boolean;
+/**
+ * Resolve overlap by cascading diagonally until no conflict.
+ * Shifts by (HEAD_HEIGHT, HEAD_HEIGHT) per attempt, clamped to viewport.
+ */
+export declare function resolveOverlap(candidate: WindowBounds, existing: WindowRecord[], viewport: {
+    width: number;
+    height: number;
+}): WindowBounds;
+/**
+ * Snap window bounds to a corner with standard edge gap.
+ */
+export declare function snapToCorner(bounds: WindowBounds, corner: SnapCorner, viewport: {
+    width: number;
+    height: number;
+}, bottomOffset: number): WindowBounds;
+/**
+ * Place a window flush beside a neighbor.
+ */
+export declare function snapToNeighbor(bounds: WindowBounds, neighbor: WindowBounds, side: 'left' | 'right'): WindowBounds;
+/**
+ * Clamp bounds so the window stays fully within the viewport.
+ */
+export declare function clampToViewport(bounds: WindowBounds, viewport: {
+    width: number;
+    height: number;
+}): WindowBounds;
+/**
+ * Convert corner-relative offset (used by the old float) to absolute viewport bounds.
+ */
+export declare function cornerOffsetToAbsolute(corner: SnapCorner, offset: {
+    x: number;
+    y: number;
+}, size: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, bottomOffset: number): WindowBounds;
+/**
+ * Convert absolute viewport bounds back to corner-relative offset.
+ */
+export declare function absoluteToCornerOffset(corner: SnapCorner, bounds: WindowBounds, viewport: {
+    width: number;
+    height: number;
+}, bottomOffset: number): {
+    x: number;
+    y: number;
+};

package/types/src/window/window-registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Window Registry — pure type definitions for the multi-window coordination system.
+ *
+ * Every schmancy-window instance is tracked as a WindowRecord in the registry.
+ * The WindowManager service holds the reactive WindowRegistryState.
+ */
+export type WindowVisualState = 'minimized' | 'normal' | 'maximized';
+export type SnapCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export type SnapTarget = SnapCorner | 'free';
+export interface WindowBounds {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface WindowRecord {
+    id: string;
+    bounds: WindowBounds;
+    visualState: WindowVisualState;
+    zIndex: number;
+    open: boolean;
+    snapTarget: SnapTarget;
+}
+export interface WindowRegistryState {
+    windows: Map<string, WindowRecord>;
+    focusedId: string | null;
+    stackOrder: string[];
+}

package/types/src/window/window.d.ts

@@ -0,0 +1,67 @@
+import type { SnapCorner, WindowVisualState } from './window-registry.js';
+declare const SchmancyWindow_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+export default class SchmancyWindow extends SchmancyWindow_base {
+    id: string;
+    /** Override the expanded panel width (e.g. '320px', '24rem'). Defaults to responsive sizing. */
+    expandedWidth?: string;
+    /** Override the expanded panel height (e.g. '400px', '50vh'). */
+    expandedHeight?: string;
+    /** When true, uses a lower elevation shadow in the collapsed state. */
+    lowered: boolean;
+    /** Corner the window is anchored to. */
+    corner: SnapCorner;
+    /** When true, window can be resized by the user. */
+    resizable: boolean;
+    /** When true, window stays at its dragged position instead of snapping to a corner. */
+    freePosition: boolean;
+    /** Visual state of the window (minimized, normal, maximized). */
+    visualState: WindowVisualState;
+    /** Minimum width in pixels. */
+    minWidth: number;
+    /** Minimum height in pixels. */
+    minHeight: number;
+    /** Whether the body is expanded. */
+    open: boolean;
+    private _currentAnimation?;
+    /** Lazy rendering: body content not in DOM until first expand. */
+    private _hasOpened;
+    /** Whether this window is the focused window in the manager — drives visual ring */
+    private _focused;
+    private _position;
+    private _currentCorner;
+    private _appliedCorner;
+    private _containerRef;
+    private _bodyRef;
+    private _headRef;
+    private get panelWidth();
+    private get isBottomCorner();
+    private get closedClipPath();
+    private get openClipPath();
+    private get elevation();
+    private _applyContainerPosition;
+    private static readonly VALID_CORNERS;
+    private _loadPosition;
+    private _savePosition;
+    private _validateBounds;
+    private _reorientToNearestCorner;
+    private _drag$;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _initDOMState;
+    private _animateOpen;
+    private _animateClose;
+    /** Apply drag visuals directly on DOM refs — avoids full Lit re-render for cursor + opacity */
+    private _applyDragVisuals;
+    private _handleFocus;
+    private _handleHeadKeydown;
+    toggle(): void;
+    expand(): void;
+    close(): void;
+    protected render(): unknown;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'schmancy-window': SchmancyWindow;
+    }
+}
+export {};