@mhmo91/schmancy 0.9.23 → 0.9.25

package/src/typography/typography.ts

@@ -1,15 +1,67 @@
 import { TailwindElement } from '@mixins/tailwind.mixin'
-import { css, html } from 'lit'
+import { css, html, type PropertyValues } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 import { createRef, ref } from 'lit/directives/ref.js'
+import { html as staticHtml, literal } from 'lit/static-html.js'
 import { fromEvent } from 'rxjs'
 import { filter, tap, takeUntil } from 'rxjs/operators'
 
+/**
+ * Preset → (type, token) shorthand. Saves the two-decision-per-text-node
+ * fatigue that 50+ typography nodes in a single page cause.
+ */
+export type TypographyPreset =
+	| 'display' | 'display-lg' | 'display-md' | 'display-sm'
+	| 'heading-lg' | 'heading-md' | 'heading-sm'
+	| 'title-lg' | 'title-md' | 'title-sm'
+	| 'body-lg' | 'body-md' | 'body-sm'
+	| 'label-lg' | 'label-md' | 'label-sm'
+	| 'caption'
+
+const PRESET_MAP: Record<TypographyPreset, { type: string; token: string }> = {
+	'display':    { type: 'display',  token: 'lg' },
+	'display-lg': { type: 'display',  token: 'lg' },
+	'display-md': { type: 'display',  token: 'md' },
+	'display-sm': { type: 'display',  token: 'sm' },
+	'heading-lg': { type: 'headline', token: 'lg' },
+	'heading-md': { type: 'headline', token: 'md' },
+	'heading-sm': { type: 'headline', token: 'sm' },
+	'title-lg':   { type: 'title',    token: 'lg' },
+	'title-md':   { type: 'title',    token: 'md' },
+	'title-sm':   { type: 'title',    token: 'sm' },
+	'body-lg':    { type: 'body',     token: 'lg' },
+	'body-md':    { type: 'body',     token: 'md' },
+	'body-sm':    { type: 'body',     token: 'sm' },
+	'label-lg':   { type: 'label',    token: 'lg' },
+	'label-md':   { type: 'label',    token: 'md' },
+	'label-sm':   { type: 'label',    token: 'sm' },
+	'caption':    { type: 'label',    token: 'sm' },
+}
+
+/**
+ * Allowed semantic tag names for the `as` prop. Closed enum so we can
+ * use `literal` template parts safely with `lit/static-html`.
+ */
+export type TypographyTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'div'
+
+const TAG_LITERALS: Record<TypographyTag, ReturnType<typeof literal>> = {
+	h1:   literal`h1`,
+	h2:   literal`h2`,
+	h3:   literal`h3`,
+	h4:   literal`h4`,
+	h5:   literal`h5`,
+	h6:   literal`h6`,
+	p:    literal`p`,
+	span: literal`span`,
+	div:  literal`div`,
+}
+
 // Material Design 3 typography - https://m3.material.io/styles/typography/type-scale-tokens
 
 /**
  * @element schmancy-typography
  * @slot - The text for the typography.
+ * @fires change - When `editable` is true, fires on blur or Enter with `detail.value` set to the new text content. Not fired when `editable` is unset (the default).
  */
 @customElement('schmancy-typography')
 export class SchmancyTypography extends TailwindElement(css`
@@ -302,6 +354,30 @@ export class SchmancyTypography extends TailwindElement(css`
 	@property({ type: String, reflect: true })
 	type: 'display' | 'headline' | 'title' | 'subtitle' | 'body' | 'label' = 'body'
 
+	/**
+	 * Shorthand for picking a (type, token) pair in one go. When set, derives
+	 * `type` and `token` automatically — saves the two-decisions-per-text-node
+	 * fatigue that hits when a single page has 50+ typography nodes.
+	 *
+	 * @attr preset
+	 * @type {TypographyPreset}
+	 * @example <schmancy-typography preset="heading-md">Title</schmancy-typography>
+	 */
+	@property({ type: String, reflect: true })
+	preset?: TypographyPreset
+
+	/**
+	 * Render the slot wrapped in the requested semantic HTML element so screen
+	 * readers expose the right role / heading level. Without `as`, the slot
+	 * sits directly in the shadow root and the host is a generic element.
+	 *
+	 * @attr as
+	 * @type {TypographyTag}
+	 * @example <schmancy-typography preset="heading-md" as="h2">Section</schmancy-typography>
+	 */
+	@property({ type: String, reflect: true })
+	as?: TypographyTag
+
 	/**
 	 * @attr token - The size token.
 	 * @deprecated Prefer using Tailwind responsive text classes for better responsive design.
@@ -352,6 +428,17 @@ export class SchmancyTypography extends TailwindElement(css`
 
 	private _editRef = createRef<HTMLDivElement>()
 
+	protected override willUpdate(changed: PropertyValues): void {
+		super.willUpdate?.(changed)
+		// `preset` shorthand expands to (type, token) so the existing CSS
+		// selectors keep matching without duplicating the size scale.
+		if (changed.has('preset') && this.preset && PRESET_MAP[this.preset]) {
+			const { type, token } = PRESET_MAP[this.preset]
+			this.type = type as typeof this.type
+			this.token = token as typeof this.token
+		}
+	}
+
 	/** Focus and select all text in editable mode */
 	selectAll() {
 		const el = this._editRef.value
@@ -437,6 +524,13 @@ export class SchmancyTypography extends TailwindElement(css`
 				data-placeholder=${this.placeholder ?? ''}
 			></div>`
 		}
+		// `as` wraps the slot in the requested semantic tag so heading levels
+		// land in the accessibility tree. Without `as` the slot is bare and
+		// the host element carries the visual styling only.
+		if (this.as && TAG_LITERALS[this.as]) {
+			const tag = TAG_LITERALS[this.as]
+			return staticHtml`<${tag}><slot></slot></${tag}>`
+		}
 		return html`<slot></slot>`
 	}
 }

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

@@ -1,5 +1,19 @@
 import { RouteComponent } from './route.component';
 declare const SchmancyArea_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Router outlet — renders the active route's component for the named area. Drives the schmancy router via the `area` service.
+ *
+ * @element schmancy-area
+ * @summary Mount once per "addressable region" of the app (typically the main content area). Use the imperative `area.push({ area, component, params })` service to navigate. Multiple named areas can coexist on a page (e.g. main content + a sheet).
+ * @example
+ * <schmancy-area name="main"></schmancy-area>
+ * <script>
+ *   import { area } from '@mhmo91/schmancy';
+ *   area.push({ area: 'main', component: MyDashboardView, params: { id: 42 } });
+ * </script>
+ * @platform div - Routing outlet. Degrades to an empty div if the tag never registers — routing is lost but the page stays accessible.
+ * @fires redirect - When the area resolves a route to a different destination (programmatic redirect). `detail.from` and `detail.to` are the route names.
+ */
 export declare class SchmancyArea extends SchmancyArea_base {
     /**
      * The name of the router outlet

package/types/src/card/card.d.ts

@@ -17,6 +17,7 @@ declare const SchmancyCard_base: import("@mixins/index").Constructor<CustomEleme
  *   </schmancy-card-action>
  * </schmancy-card>
  * @platform div - Styled `<div>`; becomes an `<a>` when `href` is set so the whole card is a single interactive surface. Degrades to a plain div/a if the tag never registers.
+ * @fires schmancy-click - When an interactive card is clicked or activated via keyboard. `detail.value` echoes the card's `type`. Only fires when `interactive` is set.
  */
 export default class SchmancyCard extends SchmancyCard_base {
     protected static shadowRootOptions: {

package/types/src/chips/assist-chip.d.ts

@@ -1,8 +1,17 @@
 import { LitElement } from 'lit';
 declare const SchmancyAssistChip_base: import("../../mixins").Constructor<CustomElementConstructor> & import("../../mixins").Constructor<import("@mixins/tailwind.mixin").ITailwindElementMixin> & import("../../mixins").Constructor<LitElement> & import("../../mixins").Constructor<import("../../mixins").IBaseMixin>;
 /**
- * Assist chip component - prompts user actions like opening calendar events or sharing content
- * Pure Schmancy implementation with Tailwind CSS and RxJS state management
+ * Assist chip — single-tap trigger for a contextual action (open calendar event, share content, jump to related view). Distinct from filter and input chips: assist chips have no selected state; clicking fires `action`.
+ *
+ * @element schmancy-assist-chip
+ * @summary Use for "do this thing" suggestions surfaced in context (next to a date, after a recipient list, near a long description). Pair with schmancy-icon for the leading glyph.
+ * @example
+ * <schmancy-assist-chip @action=${(e) => share(e.detail.value)}>
+ *   <schmancy-icon slot="icon">share</schmancy-icon>
+ *   Share
+ * </schmancy-assist-chip>
+ * @platform button click - Material 3 assist-chip semantics. Degrades to a plain `<button>` if the tag never registers.
+ * @fires action - When the chip is clicked or activated via keyboard. `detail.value` echoes the chip's `value` attribute.
  */
 export declare class SchmancyAssistChip extends SchmancyAssistChip_base {
     /** Value identifier for the chip */

package/types/src/chips/suggestion-chip.d.ts

@@ -1,13 +1,16 @@
 import { LitElement } from 'lit';
 declare const SchmancySuggestionChip_base: import("../../mixins").Constructor<CustomElementConstructor> & import("../../mixins").Constructor<import("@mixins/tailwind.mixin").ITailwindElementMixin> & import("../../mixins").Constructor<LitElement> & import("../../mixins").Constructor<import("../../mixins").IBaseMixin>;
 /**
- * Suggestion chip component - provides contextual recommendations to users
+ * Suggestion chip — single-tap insertion of a recommended value. Distinct from filter chips (no selected state) and assist chips (assist triggers an action; suggestion offers a value the user can pick).
  *
- * IMPORTANT: Suggestion chips do NOT have a selected state. They are designed to
- * provide suggestions and recommendations that trigger actions when clicked.
- * Unlike filter chips, they cannot be toggled on/off.
- *
- * Pure Schmancy implementation with Tailwind CSS and RxJS state management
+ * @element schmancy-suggestion-chip
+ * @summary Use for "would you also like to…" prompts above a search input or below a message thread. Click fires `action` with the chip's `value` so the parent can insert it into a field or trigger a search.
+ * @example
+ * <schmancy-suggestion-chip value="yesterday" @action=${(e) => setRange(e.detail.value)}>
+ *   Yesterday
+ * </schmancy-suggestion-chip>
+ * @platform button click - Material 3 suggestion-chip semantics. Degrades to a plain `<button>` if the tag never registers.
+ * @fires action - When the chip is clicked or activated via keyboard. `detail.value` echoes the chip's `value` attribute.
  */
 export declare class SchmancySuggestionChip extends SchmancySuggestionChip_base {
     /** Value identifier for the chip */

package/types/src/lightbox/lightbox.d.ts

@@ -1,5 +1,16 @@
 import { PropertyValues } from 'lit';
 declare const SchmancyLightbox_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Image lightbox — thumbnail grid that opens to a full-screen viewer on click, with keyboard navigation between images.
+ *
+ * @element schmancy-lightbox
+ * @summary Drop-in for galleries / image lists where each thumbnail should expand to fill the viewport. Pass an `images` array of `{ src, alt, caption? }`.
+ * @example
+ * <schmancy-lightbox .images=${[{ src: '/a.jpg', alt: 'A' }, { src: '/b.jpg', alt: 'B' }]}></schmancy-lightbox>
+ * @platform dialog close - Modal full-screen viewer with keyboard navigation. Degrades to a plain image grid if the tag never registers.
+ * @fires change - When the active image index changes (next/prev). `detail.index` is the new active image's position in the array.
+ * @fires close - When the viewer is dismissed (ESC, backdrop click, close button).
+ */
 export declare class SchmancyLightbox extends SchmancyLightbox_base {
     src: string;
     images: string[];

package/types/src/radio-group/radio-button.d.ts

@@ -10,6 +10,7 @@ declare const RadioButton_base: import("@mixins/index").Constructor<import("@mix
  *   <schmancy-radio-button value="pro" checked>Pro</schmancy-radio-button>
  * </schmancy-radio-group>
  * @platform radio change - Schmancy-skinned `<input type="radio">` semantics. Degrades to native radio if the tag never registers.
+ * @fires radio-button-click - Internal event consumed by the parent schmancy-radio-group; `detail.value` is the clicked button's value. Listen on schmancy-radio-group for the public `change` event instead of subscribing here.
  *
  * @prop {string} name - Name attribute for grouping radio buttons
  * @prop {string} value - Value of this radio button

package/types/src/table/table.d.ts

@@ -17,9 +17,15 @@ export interface RowEventDetail<T> {
 export type SortDirection = 'asc' | 'desc' | null;
 declare const SchmancyDataTable_base: CustomElementConstructor & import("../../mixins").Constructor<import("lit").LitElement> & import("../../mixins").Constructor<import("../../mixins").IBaseMixin>;
 /**
- * SchmancyDataTable is a generic data table component.
- * It supports sorting, filtering, and custom rendering of rows.
+ * Generic data table — typed columns, optional sort, custom renderers per column. Pass `data` (array) and `columns` (TableColumn descriptors).
  *
+ * @element schmancy-table
+ * @summary Use for tabular data where each column has a known shape. Pair with `<schmancy-table-row>` for the per-row interaction surface. Sort by setting `sortable: true` on a column descriptor; the table emits `sort-change` so the parent can re-fetch / re-sort in the data layer if needed.
+ * @example
+ * <schmancy-table .data=${rows} .columns=${[{ name: 'Name', key: 'name' }, { name: 'Status', key: 'status' }]}></schmancy-table>
+ * @platform table - Renders an accessible table with `<lit-virtualizer>` for large datasets. Degrades to a styled `<table>` if the tag never registers.
+ * @fires click - When a data row is activated. `detail.item` is the row's source object, `detail.index` is the position in the data array.
+ * @fires sort-change - When the user toggles a column sort. `detail.column` is the column key, `detail.direction` is `'asc' | 'desc' | null`.
  */
 export declare class SchmancyDataTable<T extends Record<string, any> = any> extends SchmancyDataTable_base {
     columns: TableColumn<T>[];

package/types/src/tree/tree.d.ts

@@ -15,6 +15,7 @@ declare const SchmancyTree_base: import("@mixins/index").Constructor<CustomEleme
  * @platform details toggle - Recursive `<details>`-like disclosure. Degrades to a plain nested list if the tag never registers — loses expand/collapse but stays navigable.
  * @slot root - The root element of the tree
  * @slot - The children of the tree
+ * @fires toggle - When the root toggler or chevron is clicked. Fires before the open state flips; the host's `open` property reflects the new state on the next animation frame.
  */
 export declare class SchmancyTree extends SchmancyTree_base {
     /**

package/types/src/typewriter/typewriter.d.ts

@@ -1,5 +1,17 @@
 import { TemplateResult } from 'lit';
 declare const TypewriterElement_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Typewriter effect — animates text typing/deletion with a cursor. Wraps the TypeIt library, lazy-loaded on first render.
+ *
+ * @element schmancy-typewriter
+ * @summary Drop string content as the default slot or use `<p>` / `<span>` with `cycle="A|B|C"` attribute children for cycling phrases. Set `loop` for infinite cycling, `once` to remember completion across sessions via sessionStorage.
+ * @example
+ * <schmancy-typewriter speed="35" cursor-char="|">
+ *   Hello, world.
+ * </schmancy-typewriter>
+ * @platform span - Animated text container. Degrades to its raw text content if the tag never registers — animation is lost but content stays visible.
+ * @fires typeit-complete - When the animation finishes typing all content. Fires after the final `afterComplete` callback in the underlying TypeIt instance.
+ */
 export declare class TypewriterElement extends TypewriterElement_base {
     /**
      * Typing speed in milliseconds per character.

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

@@ -1,7 +1,19 @@
+import { type PropertyValues } from 'lit';
+/**
+ * Preset → (type, token) shorthand. Saves the two-decision-per-text-node
+ * fatigue that 50+ typography nodes in a single page cause.
+ */
+export type TypographyPreset = 'display' | 'display-lg' | 'display-md' | 'display-sm' | 'heading-lg' | 'heading-md' | 'heading-sm' | 'title-lg' | 'title-md' | 'title-sm' | 'body-lg' | 'body-md' | 'body-sm' | 'label-lg' | 'label-md' | 'label-sm' | 'caption';
+/**
+ * Allowed semantic tag names for the `as` prop. Closed enum so we can
+ * use `literal` template parts safely with `lit/static-html`.
+ */
+export type TypographyTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'div';
 declare const SchmancyTypography_base: import("../../mixins").Constructor<CustomElementConstructor> & import("../../mixins").Constructor<import("@mixins/tailwind.mixin").ITailwindElementMixin> & import("../../mixins").Constructor<import("lit").LitElement> & import("../../mixins").Constructor<import("../../mixins").IBaseMixin>;
 /**
  * @element schmancy-typography
  * @slot - The text for the typography.
+ * @fires change - When `editable` is true, fires on blur or Enter with `detail.value` set to the new text content. Not fired when `editable` is unset (the default).
  */
 export declare class SchmancyTypography extends SchmancyTypography_base {
     static shadowRootOptions: ShadowRootInit;
@@ -11,6 +23,26 @@ export declare class SchmancyTypography extends SchmancyTypography_base {
      * @type {'display' | 'headline' | 'title' | 'subtitle' | 'body' | 'label'}
      */
     type: 'display' | 'headline' | 'title' | 'subtitle' | 'body' | 'label';
+    /**
+     * Shorthand for picking a (type, token) pair in one go. When set, derives
+     * `type` and `token` automatically — saves the two-decisions-per-text-node
+     * fatigue that hits when a single page has 50+ typography nodes.
+     *
+     * @attr preset
+     * @type {TypographyPreset}
+     * @example <schmancy-typography preset="heading-md">Title</schmancy-typography>
+     */
+    preset?: TypographyPreset;
+    /**
+     * Render the slot wrapped in the requested semantic HTML element so screen
+     * readers expose the right role / heading level. Without `as`, the slot
+     * sits directly in the shadow root and the host is a generic element.
+     *
+     * @attr as
+     * @type {TypographyTag}
+     * @example <schmancy-typography preset="heading-md" as="h2">Section</schmancy-typography>
+     */
+    as?: TypographyTag;
     /**
      * @attr token - The size token.
      * @deprecated Prefer using Tailwind responsive text classes for better responsive design.
@@ -49,6 +81,7 @@ export declare class SchmancyTypography extends SchmancyTypography_base {
     /** Placeholder shown when editable and empty */
     placeholder: string;
     private _editRef;
+    protected willUpdate(changed: PropertyValues): void;
     /** Focus and select all text in editable mode */
     selectAll(): void;
     connectedCallback(): void;