@mhmo91/schmancy 0.8.4 → 0.9.2

package/src/layout/scroll/scroll.ts

@@ -0,0 +1,351 @@
+import { TailwindElement } from '@mixins/index'
+import { css, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import { debounceTime, filter, fromEvent, takeUntil } from 'rxjs'
+
+/**
+ * Custom scroll event interface for the SchmancyScroll component.
+ * Contains detailed information about the scroll state.
+ */
+export interface SchmancyScrollEvent
+	extends CustomEvent<{
+		/** Current scroll position from the top */
+		scrollTop: number
+		/** Total scrollable height of the content */
+		scrollHeight: number
+		/** Visible height of the container */
+		clientHeight: number
+		/** Original scroll event */
+		e: Event
+		/** Current scroll position from the left (for horizontal scrolling) */
+		scrollLeft?: number
+		/** Total scrollable width of the content (for horizontal scrolling) */
+		scrollWidth?: number
+		/** Visible width of the container (for horizontal scrolling) */
+		clientWidth?: number
+	}> {}
+
+/**
+ * Command event interface for controlling SchmancyScroll components
+ */
+export interface SchmancyScrollCommandEvent
+	extends CustomEvent<{
+		/** Target component name */
+		name: string
+		/** Command action to perform */
+		action: 'scrollTo'
+		/** Scroll position for scrollTo action */
+		top: number
+		/** Horizontal scroll position for scrollTo action (optional) */
+		left?: number
+	}> {}
+
+// Augment the HTMLElementEventMap to include our custom events
+declare global {
+	interface HTMLElementEventMap {
+		scroll: SchmancyScrollEvent
+		'schmancy-scroll-command': SchmancyScrollCommandEvent
+	}
+}
+
+/**
+ * A custom scrollable container with enhanced features.
+ *
+ * @fires {SchmancyScrollEvent} scroll - Fired when scrolling occurs (with a configurable debounce)
+ * @slot - Default slot for content to be scrolled
+ * @csspart scroller - The inner scrollable div element
+ *
+ * @example
+ * ```html
+ * <schmancy-scroll hide name="main-content">
+ *   <div>Scrollable content goes here</div>
+ * </schmancy-scroll>
+ * ```
+ *
+ * @example
+ * ```html
+ * <schmancy-scroll direction="horizontal" hide name="image-carousel">
+ *   <div class="flex">
+ *     <img src="image1.jpg" alt="Image 1">
+ *     <img src="image2.jpg" alt="Image 2">
+ *   </div>
+ * </schmancy-scroll>
+ * ```
+ *
+ * @example Programmatic scroll with Lit ref
+ * ```typescript
+ * private scrollRef = createRef<HTMLElement>()
+ *
+ * // In template:
+ * html`<schmancy-scroll ${ref(this.scrollRef)}>...</schmancy-scroll>`
+ *
+ * // Scroll to top (smooth — host has scroll-behavior: smooth):
+ * this.scrollRef.value?.scrollTo({ top: 0 })
+ * ```
+ */
+@customElement('schmancy-scroll')
+export class SchmancyScroll extends TailwindElement(css`
+	:host {
+		/* Flexible sizing for different layout contexts */
+		width: 100%;
+		min-height: 0; /* Allow flex shrinking */
+		flex: 1; /* Grow in flex containers */
+		box-sizing: border-box; /* Ensures proper sizing */
+		display: block;
+		position: relative;
+		scroll-behavior: smooth;
+		overscroll-behavior-x: contain;
+		overscroll-behavior-y: auto;
+	}
+	/* Fallback for non-flex contexts */
+	:host(.explicit-height) {
+		height: 100%;
+		flex: none;
+	}
+	:host([hide]) {
+		-ms-overflow-style: none; /* IE and Edge */
+		scrollbar-width: none; /* Firefox */
+	}
+	:host([hide])::-webkit-scrollbar {
+		display: none; /* Chrome, Safari, and Opera */
+	}
+`) {
+	/**
+	 * Determines whether the scrollbar is hidden.
+	 *
+	 * When `hide` is true, the host element's scrollbars are hidden
+	 * in supported browsers using CSS.
+	 *
+	 * @attr hide
+	 * @example <schmancy-scroll hide></schmancy-scroll>
+	 */
+	@property({ type: Boolean, reflect: true })
+	public hide = false
+
+	/**
+	 * Optional name identifier for the component.
+	 * Used for targeting this specific component with global events.
+	 *
+	 * @attr name
+	 * @example <schmancy-scroll name="main-content"></schmancy-scroll>
+	 */
+	@property({ type: String, reflect: true })
+	public name?: string
+
+	/**
+	 * Direction of scrolling: vertical, horizontal, or both.
+	 * - vertical: Only allows vertical scrolling
+	 * - horizontal: Only allows horizontal scrolling
+	 * - both: Allows both horizontal and vertical scrolling (default)
+	 *
+	 * @attr direction
+	 * @example <schmancy-scroll direction="horizontal"></schmancy-scroll>
+	 */
+	@property({ type: String, reflect: true })
+	public direction: 'vertical' | 'horizontal' | 'both' = 'both'
+
+	/**
+	 * Reference to the scrollable element (the host element itself)
+	 * @public
+	 */
+	get scroller(): HTMLElement {
+		return this
+	}
+
+	/**
+	 * Debounce time in milliseconds for the scroll event.
+	 * Higher values reduce the frequency of scroll events being dispatched.
+	 *
+	 * @attr debounce
+	 * @example <schmancy-scroll debounce="50"></schmancy-scroll>
+	 */
+	@property({ type: Number })
+	public debounce = 10
+
+	/**
+	 * Scrolls the container to the specified position
+	 * @param options - ScrollToOptions or a number representing the top position
+	 * @param top - For backward compatibility, if options is a number, this is treated as "behavior"
+	 */
+	public override scrollTo(options?: ScrollToOptions | number, top?: number): void {
+		if (typeof options === 'number') {
+			super.scrollTo({ top: options, behavior: top ? 'smooth' : 'auto' })
+		} else if (options) {
+			super.scrollTo(options)
+		} else {
+			super.scrollTo({ top: 0, left: 0, behavior: 'auto' })
+		}
+	}
+
+	/**
+	 * Scrolls the container horizontally to the specified position
+	 * @param left - The horizontal position to scroll to (in pixels)
+	 * @param behavior - The scroll behavior ('auto' or 'smooth')
+	 */
+	public scrollToLeft(left: number, behavior: ScrollBehavior = 'auto'): void {
+		super.scrollTo({ left, behavior })
+	}
+
+	/**
+	 * Called when the component is connected to the DOM
+	 * Applies scrolling styles directly to the host element
+	 * @protected
+	 */
+	connectedCallback(): void {
+		super.connectedCallback()
+		this.updateScrollingStyles()
+		this.updateLayoutContext()
+		// Set the part attribute on the host element
+		this.setAttribute('part', 'scroller')
+	}
+
+	/**
+	 * Updates the overflow styles based on the direction property
+	 * @private
+	 */
+	private updateScrollingStyles(): void {
+		// Apply overflow styles based on direction
+		if (this.direction === 'horizontal') {
+			this.style.setProperty('overflow-y', 'hidden')
+			this.style.setProperty('overflow-x', 'auto')
+		} else if (this.direction === 'vertical') {
+			this.style.setProperty('overflow-y', 'auto')
+			this.style.setProperty('overflow-x', 'hidden')
+		} else {
+			// both
+			this.style.setProperty('overflow-y', 'auto')
+			this.style.setProperty('overflow-x', 'auto')
+		}
+	}
+
+	/**
+	 * Updates the layout context based on parent container type
+	 * @private
+	 */
+	private updateLayoutContext(): void {
+		// Use requestAnimationFrame to ensure DOM is fully rendered
+		requestAnimationFrame(() => {
+			// Check if parent is a flex container
+			const parent = this.parentElement
+			if (parent) {
+				const parentStyles = getComputedStyle(parent)
+				const isFlexParent = parentStyles.display === 'flex' || parentStyles.display === 'inline-flex'
+
+				// For debugging - remove in production
+				console.debug('schmancy-scroll parent detection:', {
+					parent: parent.tagName,
+					display: parentStyles.display,
+					isFlexParent,
+				})
+
+				// Apply appropriate class based on parent layout
+				if (isFlexParent) {
+					this.classList.remove('explicit-height')
+				} else {
+					this.classList.add('explicit-height')
+				}
+			} else {
+				// Default to explicit height if no parent
+				this.classList.add('explicit-height')
+			}
+		})
+	}
+
+	/**
+	 * Called when properties change
+	 * @protected
+	 */
+	protected updated(changedProperties: Map<string | number | symbol, unknown>): void {
+		super.updated(changedProperties)
+		// Update styles if direction changes
+		if (changedProperties.has('direction')) {
+			this.updateScrollingStyles()
+		}
+		// Always update layout context in case parent layout changed
+		this.updateLayoutContext()
+	}
+
+	/**
+	 * Called after the component's first update
+	 * Sets up the scroll event listener with debouncing
+	 * @protected
+	 */
+	protected firstUpdated(): void {
+		// Set up scroll event listening with debounce
+		fromEvent(this.scroller, 'scroll', {
+			passive: true,
+		})
+			.pipe(
+				debounceTime(this.debounce),
+				takeUntil(this.disconnecting), // Unsubscribe when the element is destroyed
+			)
+			.subscribe(e => {
+				// Always include the original required properties for backward compatibility
+				const scrollTop = this.scroller.scrollTop
+				const scrollHeight = this.scroller.scrollHeight
+				const clientHeight = this.scroller.clientHeight
+
+				// Include horizontal scroll information as optional properties
+				const scrollLeft = this.scroller.scrollLeft
+				const scrollWidth = this.scroller.scrollWidth
+				const clientWidth = this.scroller.clientWidth
+
+				this.dispatchEvent(
+					new CustomEvent('scroll', {
+						detail: {
+							// Original required properties first
+							scrollTop,
+							scrollHeight,
+							clientHeight,
+							e,
+							// New optional properties last
+							scrollLeft,
+							scrollWidth,
+							clientWidth,
+						},
+						bubbles: true,
+						composed: true,
+					}) as SchmancyScrollEvent,
+				)
+			})
+
+		// Set up global command event listener
+		fromEvent<SchmancyScrollCommandEvent>(window, '@schmancy:scrollTo')
+			.pipe(
+				// Only process events targeting this component by name
+				filter(e => this.name !== undefined && e.detail.name === this.name),
+				takeUntil(this.disconnecting),
+			)
+			.subscribe(e => {
+				if (e.detail.action === 'scrollTo' && typeof e.detail.top === 'number') {
+					const options: ScrollToOptions = {
+						behavior: 'smooth',
+						top: e.detail.top, // Required for backward compatibility
+					}
+
+					// Add optional left position if provided
+					if (typeof e.detail.left === 'number') {
+						options.left = e.detail.left
+					}
+
+					this.scrollTo(options)
+				}
+			})
+	}
+
+	/**
+	 * Renders the component template
+	 * @returns {TemplateResult} The template to render
+	 * @protected
+	 */
+	protected render() {
+		// Only render the slot, all styling is applied to the host
+		return html`<slot></slot>`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-scroll': SchmancyScroll
+	}
+}

package/src/layout/v2/flex.ts

@@ -0,0 +1,243 @@
+import { css, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import Layout from '../layout'
+
+/**
+ * @deprecated Use Tailwind CSS flex classes directly instead of this component.
+ * This component will be removed in a future version.
+ * 
+ * Migration guide:
+ * - Replace <sch-flex> with <div class="flex ...">
+ * - Use Tailwind's flex utilities: flex-row, flex-col, gap-*, items-*, justify-*, etc.
+ * 
+ * Original documentation:
+ * 
+ * SchmancyFlex exposes a flex container with all the Tailwind CSS 4 options:
+ *
+ * - **Display**: By default uses `flex` but can be set to inline using the `inline` property.
+ * - **Flow**: Accepts 'row', 'row-reverse', 'col', 'col-reverse' as well as grid‐like dense variants:
+ *    - Dense variants (`row-dense`, `col-dense`) force wrapping.
+ * - **Wrap**: 'wrap', 'nowrap', or 'wrap-reverse'
+ * - **Align Items**: 'start', 'center', 'end', 'stretch', or 'baseline'
+ * - **Justify Content**: 'start', 'center', 'end', 'between', 'around', or 'evenly'
+ * - **Align Content** (for multi-line flex containers): 'start', 'center', 'end', 'between', 'around', or 'evenly'
+ * - **Gap**: Supports Tailwind’s spacing scale (e.g. 'none', '0', '1', '2', …, '64')
+ */
+@customElement('sch-flex')
+export class SchmancyFlexV2 extends Layout {
+	static styles = [
+		Layout.styles,
+		css`
+			:host {
+				display: block;
+			}
+		`,
+	]
+	// If true, the container will use inline-flex instead of flex.
+	@property({ type: Boolean, reflect: true })
+	inline = false
+
+	/**
+	 * Flow property that determines the flex direction.
+	 * Allowed values:
+	 *  - Standard: 'row', 'row-reverse', 'col', 'col-reverse'
+	 *  - Dense variants: 'row-dense', 'col-dense' (dense implies wrapping)
+	 */
+	@property({ type: String, reflect: true })
+	flow: 'row' | 'row-reverse' | 'col' | 'col-reverse' | 'row-dense' | 'col-dense' = 'row'
+
+	/**
+	 * Flex-wrap options:
+	 *  - 'wrap', 'nowrap', or 'wrap-reverse'
+	 */
+	@property({ type: String, reflect: true })
+	wrap: 'wrap' | 'nowrap' | 'wrap-reverse' = 'wrap'
+
+	/**
+	 * Align-items (vertical alignment of flex items):
+	 *  - 'start', 'center', 'end', 'stretch', or 'baseline'
+	 */
+	@property({ type: String, reflect: true })
+	align: 'start' | 'center' | 'end' | 'stretch' | 'baseline' = 'stretch'
+
+	/**
+	 * Justify-content (horizontal distribution):
+	 *  - 'start', 'center', 'end', 'between', 'around', or 'evenly'
+	 */
+	@property({ type: String, reflect: true })
+	justify: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' = 'start'
+
+	/**
+	 * Align-content (spacing between rows when wrapping):
+	 *  - 'start', 'center', 'end', 'between', 'around', or 'evenly'
+	 */
+	@property({ type: String, reflect: true })
+	content?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'
+
+	/**
+	 * Gap between flex items.
+	 * Options (based on Tailwind CSS 4 spacing scale):
+	 *  - 'none', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '12', '16', '20', '24', '32', '40', '48', '56', or '64'
+	 */
+	@property({ type: String, reflect: true })
+	gap:
+		| 'none'
+		| '0'
+		| '1'
+		| '2'
+		| '3'
+		| '4'
+		| '5'
+		| '6'
+		| '7'
+		| '8'
+		| '9'
+		| '10'
+		| '12'
+		| '16'
+		| '20'
+		| '24'
+		| '32'
+		| '40'
+		| '48'
+		| '56'
+		| '64' = 'none'
+
+	render() {
+		// Determine whether to use inline-flex or flex.
+		const baseDisplay = this.inline ? 'inline-flex' : 'flex'
+
+		// Map the flow property to a flex-direction class.
+		// (Dense variants use the same class as their standard counterparts.)
+		let directionClass = ''
+		switch (this.flow) {
+			case 'row':
+			case 'row-dense':
+				directionClass = 'flex-row'
+				break
+			case 'row-reverse':
+				directionClass = 'flex-row-reverse'
+				break
+			case 'col':
+			case 'col-dense':
+				directionClass = 'flex-col'
+				break
+			case 'col-reverse':
+				directionClass = 'flex-col-reverse'
+				break
+			default:
+				directionClass = 'flex-row'
+		}
+
+		// Dense variants force wrapping regardless of the wrap property.
+		const isDense = this.flow === 'row-dense' || this.flow === 'col-dense'
+		const effectiveWrap = isDense ? 'wrap' : this.wrap
+
+		let wrapClass = ''
+		switch (effectiveWrap) {
+			case 'wrap':
+				wrapClass = 'flex-wrap'
+				break
+			case 'nowrap':
+				wrapClass = 'flex-nowrap'
+				break
+			case 'wrap-reverse':
+				wrapClass = 'flex-wrap-reverse'
+				break
+			default:
+				wrapClass = 'flex-wrap'
+		}
+
+		// Map align-items.
+		let alignClass = ''
+		switch (this.align) {
+			case 'start':
+				alignClass = 'items-start'
+				break
+			case 'center':
+				alignClass = 'items-center'
+				break
+			case 'end':
+				alignClass = 'items-end'
+				break
+			case 'stretch':
+				alignClass = 'items-stretch'
+				break
+			case 'baseline':
+				alignClass = 'items-baseline'
+				break
+			default:
+				alignClass = 'items-stretch'
+		}
+
+		// Map justify-content.
+		let justifyClass = ''
+		switch (this.justify) {
+			case 'start':
+				justifyClass = 'justify-start'
+				break
+			case 'center':
+				justifyClass = 'justify-center'
+				break
+			case 'end':
+				justifyClass = 'justify-end'
+				break
+			case 'between':
+				justifyClass = 'justify-between'
+				break
+			case 'around':
+				justifyClass = 'justify-around'
+				break
+			case 'evenly':
+				justifyClass = 'justify-evenly'
+				break
+			default:
+				justifyClass = 'justify-start'
+		}
+
+		// Map align-content (if provided).
+		let contentClass = ''
+		if (this.content) {
+			switch (this.content) {
+				case 'start':
+					contentClass = 'content-start'
+					break
+				case 'center':
+					contentClass = 'content-center'
+					break
+				case 'end':
+					contentClass = 'content-end'
+					break
+				case 'between':
+					contentClass = 'content-between'
+					break
+				case 'around':
+					contentClass = 'content-around'
+					break
+				case 'evenly':
+					contentClass = 'content-evenly'
+					break
+			}
+		}
+
+		// Map gap value.
+		const gapClass = this.gap === 'none' ? 'gap-0' : `gap-${this.gap}`
+
+		// Build the complete list of classes.
+		const classes = [baseDisplay, directionClass, wrapClass, alignClass, justifyClass, contentClass, gapClass]
+			.filter(Boolean)
+			.join(' ')
+
+		return html`
+			<section class=${classes}>
+				<slot></slot>
+			</section>
+		`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'sch-flex': SchmancyFlexV2
+	}
+}

package/src/layout/v2/grid.ts

@@ -0,0 +1,93 @@
+import { css, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import Layout from '../layout'
+
+@customElement('sch-grid')
+export class SchmancyGridV2 extends Layout {
+	static styles = [
+		Layout.styles,
+		css`
+			:host {
+				display: block;
+			}
+		`,
+	]
+
+	/**
+	 * Display mode: 'grid' or 'inline-grid'.
+	 */
+	@property({ type: String, reflect: true })
+	display: 'grid' | 'inline-grid' = 'grid'
+
+	/**
+	 * Grid template columns.
+	 * Examples: '1', '2', '3', 'none', 'subgrid', '[200px_minmax(900px,_1fr)_100px]'
+	 */
+	@property({ type: String, reflect: true })
+	columns: string = 'none'
+
+	/**
+	 * Grid template rows.
+	 * Examples: '1', '2', '3', 'none', 'subgrid', '[200px_minmax(900px,_1fr)_100px]'
+	 */
+	@property({ type: String, reflect: true })
+	rows: string = 'none'
+
+	/**
+	 * Grid auto flow.
+	 * Options: 'row', 'column', 'dense', 'row-dense', 'column-dense'
+	 */
+	@property({ type: String, reflect: true })
+	flow: 'row' | 'column' | 'dense' | 'row-dense' | 'column-dense' = 'row'
+
+	/**
+	 * Gap between grid items.
+	 * Examples: '0', '1', '2', '4', '8', '16', '32', '64'
+	 */
+	@property({ type: String, reflect: true })
+	gap: string = '0'
+
+	/**
+	 * Gap between columns.
+	 * Overrides the general gap if specified.
+	 */
+	@property({ type: String, reflect: true })
+	gapX?: string
+
+	/**
+	 * Gap between rows.
+	 * Overrides the general gap if specified.
+	 */
+	@property({ type: String, reflect: true })
+	gapY?: string
+
+	/**
+	 * Responsive variants.
+	 * Example: { sm: 'grid-cols-2', md: 'grid-cols-4' }
+	 */
+	@property({ type: Object })
+	responsive: { [key: string]: string } = {}
+
+	render() {
+		const classes = [
+			this.display === 'inline-grid' ? 'inline-grid' : 'grid',
+			this.columns !== 'none' ? `grid-cols-${this.columns}` : '',
+			this.rows !== 'none' ? `grid-rows-${this.rows}` : '',
+			`grid-flow-${this.flow}`,
+			this.gap ? `gap-${this.gap}` : '',
+			this.gapX ? `gap-x-${this.gapX}` : '',
+			this.gapY ? `gap-y-${this.gapY}` : '',
+			...Object.entries(this.responsive).map(([breakpoint, utility]) => `${breakpoint}:${utility}`),
+		]
+			.filter(Boolean)
+			.join(' ')
+
+		return html`<div class="${classes}"><slot></slot></div>`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'sch-grid': SchmancyGridV2
+	}
+}

package/src/layout/v2/index.ts

@@ -0,0 +1 @@
+export * from './flex';