@mhmo91/schmancy 0.9.15 → 0.9.17

package/dist/tree.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"tree.cjs","names":[],"sources":["../src/tree/tree.ts"],"sourcesContent":["import { TailwindElement } from '@mixins/index'\nimport { css, html } from 'lit'\nimport { customElement, property, query } from 'lit/decorators.js'\nimport { fromEvent, merge, switchMap, takeUntil, tap, zip } from 'rxjs'\n\n/**\n * @element schmancy-tree\n * @slot root - The root element of the tree\n * @slot - The children of the tree\n */\n@customElement('schmancy-tree')\nexport class SchmancyTree extends TailwindElement(css`\n\t:host {\n\t\tdisplay: block;\n\t\tposition: relative;\n\t\tbackground-color: initial;\n\t}\n\t::slotted([slot='root']) {\n\t\twidth: 100%;\n\t\ttext-align: left;\n\t}\n\t::slotted([slot='root'] + *) {\n\t\tmargin-top: 0.5rem;\n\t}\n`) {\n\t/**\n\t * Whether the tree’s children are visible\n\t */\n\t@property({ type: Boolean }) open = false\n\n\t@query('#toggler') toggler!: HTMLSlotElement\n\t@query('slot:not([name=\"root\"])') defaultSlot!: HTMLSlotElement\n\n\t// Since it's actually a <schmancy-button>, use HTMLElement or a custom type\n\t@query('#chevron') chevron!: HTMLElement\n\n\tprivate readonly _a11yId = `schmancy-tree-${Math.random().toString(36).slice(2, 10)}`\n\tprivate get _contentId() { return `${this._a11yId}-content` }\n\n\t/** ElementInternals — broadcasts `:state(open)` for consumer CSS. */\n\tprivate readonly _internals: ElementInternals | undefined = (() => {\n\t\ttry { return this.attachInternals() } catch { return undefined }\n\t})()\n\n\tupdated(changed: Map<string, unknown>) {\n\t\tsuper.updated?.(changed)\n\t\tif (changed.has('open')) {\n\t\t\tif (this.open) this._internals?.states.add('open')\n\t\t\telse this._internals?.states.delete('open')\n\t\t}\n\t}\n\n\tfirstUpdated() {\n\t\t// Hide or show the slot initially based on `open`\n\t\tif (!this.open) {\n\t\t\tthis.defaultSlot.hidden = true\n\t\t}\n\n\t\t// Root toggler\n\t\tconst toggleClick$ = fromEvent<MouseEvent>(this.toggler, 'click').pipe(\n\t\t\ttakeUntil(this.disconnecting),\n\t\t\ttap(e => {\n\t\t\t\te.preventDefault()\n\t\t\t\te.stopPropagation()\n\t\t\t\tthis.dispatchEvent(new CustomEvent('toggle', { bubbles: false, composed: true }))\n\t\t\t}),\n\t\t)\n\n\t\t// Chevron (the schmancy-button) click\n\t\tconst chevronClick$ = fromEvent<MouseEvent>(this.chevron, 'click')\n\n\t\tmerge(toggleClick$, chevronClick$)\n\t\t\t.pipe(\n\t\t\t\tswitchMap(() => {\n\t\t\t\t\t// 1. Animate the chevron rotation\n\t\t\t\t\t//    If `open` is true, rotate from 180 -> 0; if false, from 0 -> 180\n\t\t\t\t\tconst fromDeg = this.open ? 180 : 0\n\t\t\t\t\tconst toDeg = this.open ? 0 : 180\n\t\t\t\t\tconst chevronAnimation = this.chevron.animate(\n\t\t\t\t\t\t[{ transform: `rotate(${fromDeg}deg)` }, { transform: `rotate(${toDeg}deg)` }],\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tduration: 150,\n\t\t\t\t\t\t\teasing: 'ease-in',\n\t\t\t\t\t\t\tfill: 'forwards',\n\t\t\t\t\t\t},\n\t\t\t\t\t)\n\n\t\t\t\t\t// 2. Animate the slot’s height + opacity\n\t\t\t\t\tif (!this.open) {\n\t\t\t\t\t\t// We are about to open, so remove `hidden` to measure scrollHeight\n\t\t\t\t\t\tthis.defaultSlot.hidden = false\n\t\t\t\t\t}\n\n\t\t\t\t\tconst fromOpacity = this.open ? 1 : 0\n\t\t\t\t\tconst toOpacity = this.open ? 0 : 1\n\n\t\t\t\t\tconst slotAnimation = this.defaultSlot.animate([{ opacity: fromOpacity }, { opacity: toOpacity }], {\n\t\t\t\t\t\tduration: 150,\n\t\t\t\t\t\teasing: 'ease-out',\n\t\t\t\t\t\tfill: 'forwards',\n\t\t\t\t\t})\n\n\t\t\t\t\t// Hide the slot if we just closed it\n\t\t\t\t\tslotAnimation.onfinish = () => {\n\t\t\t\t\t\tif (this.open) {\n\t\t\t\t\t\t\tthis.defaultSlot.hidden = true\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tthis.defaultSlot.style.height = 'auto'\n\t\t\t\t\t\t\tthis.defaultSlot.style.opacity = '1'\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\n\t\t\t\t\t// Return an Observable that completes when both animations finish\n\t\t\t\t\treturn zip(fromEvent(chevronAnimation, 'finish'), fromEvent(slotAnimation, 'finish')).pipe(\n\t\t\t\t\t\ttakeUntil(this.disconnecting),\n\t\t\t\t\t)\n\t\t\t\t}),\n\t\t\t\ttap(() => {\n\t\t\t\t\t// Flip the open state\n\t\t\t\t\tthis.open = !this.open\n\t\t\t\t}),\n\t\t\t\ttakeUntil(this.disconnecting),\n\t\t\t)\n\t\t\t.subscribe()\n\t}\n\n\trender() {\n\t\treturn html`\n\t\t\t<div class=\"flex content-center items-center justify-between\">\n\t\t\t\t<!-- Root toggler content -->\n\t\t\t\t<slot id=\"toggler\" name=\"root\"></slot>\n\n\t\t\t\t<!-- The chevron or arrow symbol -->\n\t\t\t\t<!-- Stop propagation on the schmancy-button itself just to avoid double triggers -->\n\t\t\t\t<schmancy-button\n\t\t\t\t\tslot=\"trailing\"\n\t\t\t\t\tid=\"chevron\"\n\t\t\t\t\taria-expanded=${this.open ? 'true' : 'false'}\n\t\t\t\t\taria-controls=${this._contentId}\n\t\t\t\t\taria-label=${this.open ? 'Collapse' : 'Expand'}\n\t\t\t\t\t@click=${(e: Event) => e.stopPropagation()}\n\t\t\t\t>\n\t\t\t\t\t⌅\n\t\t\t\t</schmancy-button>\n\t\t\t</div>\n\n\t\t\t<!-- The default slot: tree children -->\n\t\t\t<slot id=${this._contentId}></slot>\n\t\t`\n\t}\n}\n\ndeclare global {\n\tinterface HTMLElementTagNameMap {\n\t\t'schmancy-tree': SchmancyTree\n\t}\n}\n"],"mappings":"uRAWO,IAAA,EAAA,cAA2B,EAAA,EAAgB,EAAA,GAAG;;;;;;;;;;;;;4CAiBhB,EAAA,KAAA,QAQT,iBAAiB,KAAK,QAAA,CAAS,SAAS,GAAA,CAAI,MAAM,EAAG,GAAA,GAAA,KAAA,gBAAA,CAK/E,GAAA,CAAM,OAAO,KAAK,iBAAA,MAAA,CAA4B,WAAA,CAJ/C,IAAA,YAAY,CAAe,MAAO,GAAG,KAAK,QAAA,UAO1C,QAAQ,EAAA,CACP,MAAM,UAAU,EAAA,CACZ,EAAQ,IAAI,OAAA,GACX,KAAK,KAAM,KAAK,YAAY,OAAO,IAAI,OAAA,CACtC,KAAK,YAAY,OAAO,OAAO,OAAA,EAItC,cAAA,CAEM,KAAK,OACT,KAAK,YAAY,OAAA,CAAS,IAgB3B,EAAA,EAAA,QAAA,EAAA,EAAA,WAZ2C,KAAK,QAAS,QAAA,CAAS,MAAA,EAAA,EAAA,WACvD,KAAK,cAAA,EAAc,EAAA,EAAA,KACzB,GAAA,CACH,EAAE,gBAAA,CACF,EAAE,iBAAA,CACF,KAAK,cAAc,IAAI,YAAY,SAAU,CAAE,QAAA,CAAS,EAAO,SAAA,CAAU,EAAA,CAAA,CAAA,EAAA,CAAA,EAOrE,EAAA,EAAA,WAFsC,KAAK,QAAS,QAAA,CAAA,CAGxD,MAAA,EAAA,EAAA,eAAA,CAIC,IAAM,EAAU,KAAK,KAAO,IAAM,EAC5B,EAAQ,KAAK,KAAO,EAAI,IACxB,EAAmB,KAAK,QAAQ,QACrC,CAAC,CAAE,UAAW,UAAU,EAAA,MAAA,CAAiB,CAAE,UAAW,UAAU,EAAA,MAAA,CAAA,CAChE,CACC,SAAU,IACV,OAAQ,UACR,KAAM,WAAA,CAAA,CAKH,KAAK,OAET,KAAK,YAAY,OAAA,CAAS,GAG3B,IAAM,EAAc,QAAK,KACnB,EAAY,OAAK,KAEjB,EAAgB,KAAK,YAAY,QAAQ,CAAC,CAAE,QAAS,EAAA,CAAe,CAAE,QAAS,EAAA,CAAA,CAAc,CAClG,SAAU,IACV,OAAQ,WACR,KAAM,WAAA,CAAA,CAcP,MAVA,GAAc,aAAA,CACT,KAAK,KACR,KAAK,YAAY,OAAA,CAAS,GAE1B,KAAK,YAAY,MAAM,OAAS,OAChC,KAAK,YAAY,MAAM,QAAU,OAKnC,EAAA,EAAA,MAAA,EAAA,EAAA,WAAqB,EAAkB,SAAA,EAAS,EAAA,EAAA,WAAY,EAAe,SAAA,CAAA,CAAW,MAAA,EAAA,EAAA,WAC3E,KAAK,cAAA,CAAA,EAAA,EAEf,EAAA,EAAA,SAAA,CAGD,KAAK,KAAA,CAAQ,KAAK,MAAA,EACjB,EAAA,EAAA,WACQ,KAAK,cAAA,CAAA,CAEf,WAAA,CAGH,QAAA,CACC,MAAO,GAAA,IAAI;;;;;;;;;;qBAUQ,KAAK,KAAO,OAAS,QAAA;qBACrB,KAAK,WAAA;kBACR,KAAK,KAAO,WAAa,SAAA;cAC5B,GAAa,EAAE,iBAAA,CAAA;;;;;;;cAOhB,KAAK,WAAA;0BAvHR,CAAE,KAAM,QAAA,CAAA,CAAA,CAAU,EAAA,UAAA,OAAA,IAAA,GAAA,CAAA,EAAA,EAAA,EAAA,EAAA,EAAA,OAErB,WAAA,CAAA,CAAW,EAAA,UAAA,UAAA,IAAA,GAAA,CAAA,EAAA,EAAA,EAAA,EAAA,EAAA,OACX,0BAAA,CAAA,CAA0B,EAAA,UAAA,cAAA,IAAA,GAAA,CAAA,EAAA,EAAA,EAAA,EAAA,EAAA,OAG1B,WAAA,CAAA,CAAW,EAAA,UAAA,UAAA,IAAA,GAAA,CAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,eAxBJ,gBAAA,CAAA,CAAgB,EAAA,CAAA,OAAA,eAAA,QAAA,eAAA,CAAA,WAAA,CAAA,EAAA,IAAA,UAAA,CAAA,OAAA,GAAA,CAAA"}
+{"version":3,"file":"tree.cjs","names":[],"sources":["../src/tree/tree.ts"],"sourcesContent":["import { TailwindElement } from '@mixins/index'\nimport { css, html } from 'lit'\nimport { customElement, property, query } from 'lit/decorators.js'\nimport { fromEvent, merge, switchMap, takeUntil, tap, zip } from 'rxjs'\n\n/**\n * Expandable tree node — a recursive disclosure widget. One root slot, one default slot for child nodes. Each node can itself contain schmancy-tree children.\n *\n * @element schmancy-tree\n * @summary Use for hierarchical navigation / file-explorer layouts. Each level is a schmancy-tree with a `root` slot (the parent label) and default slot (the children, which may be more schmancy-trees).\n * @example\n * <schmancy-tree>\n *   <schmancy-list-item slot=\"root\">src/</schmancy-list-item>\n *   <schmancy-tree>\n *     <schmancy-list-item slot=\"root\">components/</schmancy-list-item>\n *     <schmancy-list-item>button.ts</schmancy-list-item>\n *   </schmancy-tree>\n * </schmancy-tree>\n * @platform details toggle - Recursive `<details>`-like disclosure. Degrades to a plain nested list if the tag never registers — loses expand/collapse but stays navigable.\n * @slot root - The root element of the tree\n * @slot - The children of the tree\n */\n@customElement('schmancy-tree')\nexport class SchmancyTree extends TailwindElement(css`\n\t:host {\n\t\tdisplay: block;\n\t\tposition: relative;\n\t\tbackground-color: initial;\n\t}\n\t::slotted([slot='root']) {\n\t\twidth: 100%;\n\t\ttext-align: left;\n\t}\n\t::slotted([slot='root'] + *) {\n\t\tmargin-top: 0.5rem;\n\t}\n`) {\n\t/**\n\t * Whether the tree’s children are visible\n\t */\n\t@property({ type: Boolean }) open = false\n\n\t@query('#toggler') toggler!: HTMLSlotElement\n\t@query('slot:not([name=\"root\"])') defaultSlot!: HTMLSlotElement\n\n\t// Since it's actually a <schmancy-button>, use HTMLElement or a custom type\n\t@query('#chevron') chevron!: HTMLElement\n\n\tprivate readonly _a11yId = `schmancy-tree-${Math.random().toString(36).slice(2, 10)}`\n\tprivate get _contentId() { return `${this._a11yId}-content` }\n\n\t/** ElementInternals — broadcasts `:state(open)` for consumer CSS. */\n\tprivate readonly _internals: ElementInternals | undefined = (() => {\n\t\ttry { return this.attachInternals() } catch { return undefined }\n\t})()\n\n\tupdated(changed: Map<string, unknown>) {\n\t\tsuper.updated?.(changed)\n\t\tif (changed.has('open')) {\n\t\t\tif (this.open) this._internals?.states.add('open')\n\t\t\telse this._internals?.states.delete('open')\n\t\t}\n\t}\n\n\tfirstUpdated() {\n\t\t// Hide or show the slot initially based on `open`\n\t\tif (!this.open) {\n\t\t\tthis.defaultSlot.hidden = true\n\t\t}\n\n\t\t// Root toggler\n\t\tconst toggleClick$ = fromEvent<MouseEvent>(this.toggler, 'click').pipe(\n\t\t\ttakeUntil(this.disconnecting),\n\t\t\ttap(e => {\n\t\t\t\te.preventDefault()\n\t\t\t\te.stopPropagation()\n\t\t\t\tthis.dispatchEvent(new CustomEvent('toggle', { bubbles: false, composed: true }))\n\t\t\t}),\n\t\t)\n\n\t\t// Chevron (the schmancy-button) click\n\t\tconst chevronClick$ = fromEvent<MouseEvent>(this.chevron, 'click')\n\n\t\tmerge(toggleClick$, chevronClick$)\n\t\t\t.pipe(\n\t\t\t\tswitchMap(() => {\n\t\t\t\t\t// 1. Animate the chevron rotation\n\t\t\t\t\t//    If `open` is true, rotate from 180 -> 0; if false, from 0 -> 180\n\t\t\t\t\tconst fromDeg = this.open ? 180 : 0\n\t\t\t\t\tconst toDeg = this.open ? 0 : 180\n\t\t\t\t\tconst chevronAnimation = this.chevron.animate(\n\t\t\t\t\t\t[{ transform: `rotate(${fromDeg}deg)` }, { transform: `rotate(${toDeg}deg)` }],\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tduration: 150,\n\t\t\t\t\t\t\teasing: 'ease-in',\n\t\t\t\t\t\t\tfill: 'forwards',\n\t\t\t\t\t\t},\n\t\t\t\t\t)\n\n\t\t\t\t\t// 2. Animate the slot’s height + opacity\n\t\t\t\t\tif (!this.open) {\n\t\t\t\t\t\t// We are about to open, so remove `hidden` to measure scrollHeight\n\t\t\t\t\t\tthis.defaultSlot.hidden = false\n\t\t\t\t\t}\n\n\t\t\t\t\tconst fromOpacity = this.open ? 1 : 0\n\t\t\t\t\tconst toOpacity = this.open ? 0 : 1\n\n\t\t\t\t\tconst slotAnimation = this.defaultSlot.animate([{ opacity: fromOpacity }, { opacity: toOpacity }], {\n\t\t\t\t\t\tduration: 150,\n\t\t\t\t\t\teasing: 'ease-out',\n\t\t\t\t\t\tfill: 'forwards',\n\t\t\t\t\t})\n\n\t\t\t\t\t// Hide the slot if we just closed it\n\t\t\t\t\tslotAnimation.onfinish = () => {\n\t\t\t\t\t\tif (this.open) {\n\t\t\t\t\t\t\tthis.defaultSlot.hidden = true\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tthis.defaultSlot.style.height = 'auto'\n\t\t\t\t\t\t\tthis.defaultSlot.style.opacity = '1'\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\n\t\t\t\t\t// Return an Observable that completes when both animations finish\n\t\t\t\t\treturn zip(fromEvent(chevronAnimation, 'finish'), fromEvent(slotAnimation, 'finish')).pipe(\n\t\t\t\t\t\ttakeUntil(this.disconnecting),\n\t\t\t\t\t)\n\t\t\t\t}),\n\t\t\t\ttap(() => {\n\t\t\t\t\t// Flip the open state\n\t\t\t\t\tthis.open = !this.open\n\t\t\t\t}),\n\t\t\t\ttakeUntil(this.disconnecting),\n\t\t\t)\n\t\t\t.subscribe()\n\t}\n\n\trender() {\n\t\treturn html`\n\t\t\t<div class=\"flex content-center items-center justify-between\">\n\t\t\t\t<!-- Root toggler content -->\n\t\t\t\t<slot id=\"toggler\" name=\"root\"></slot>\n\n\t\t\t\t<!-- The chevron or arrow symbol -->\n\t\t\t\t<!-- Stop propagation on the schmancy-button itself just to avoid double triggers -->\n\t\t\t\t<schmancy-button\n\t\t\t\t\tslot=\"trailing\"\n\t\t\t\t\tid=\"chevron\"\n\t\t\t\t\taria-expanded=${this.open ? 'true' : 'false'}\n\t\t\t\t\taria-controls=${this._contentId}\n\t\t\t\t\taria-label=${this.open ? 'Collapse' : 'Expand'}\n\t\t\t\t\t@click=${(e: Event) => e.stopPropagation()}\n\t\t\t\t>\n\t\t\t\t\t⌅\n\t\t\t\t</schmancy-button>\n\t\t\t</div>\n\n\t\t\t<!-- The default slot: tree children -->\n\t\t\t<slot id=${this._contentId}></slot>\n\t\t`\n\t}\n}\n\ndeclare global {\n\tinterface HTMLElementTagNameMap {\n\t\t'schmancy-tree': SchmancyTree\n\t}\n}\n"],"mappings":"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"}

package/dist/tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"tree.js","names":[],"sources":["../src/tree/tree.ts"],"sourcesContent":["import { TailwindElement } from '@mixins/index'\nimport { css, html } from 'lit'\nimport { customElement, property, query } from 'lit/decorators.js'\nimport { fromEvent, merge, switchMap, takeUntil, tap, zip } from 'rxjs'\n\n/**\n * @element schmancy-tree\n * @slot root - The root element of the tree\n * @slot - The children of the tree\n */\n@customElement('schmancy-tree')\nexport class SchmancyTree extends TailwindElement(css`\n\t:host {\n\t\tdisplay: block;\n\t\tposition: relative;\n\t\tbackground-color: initial;\n\t}\n\t::slotted([slot='root']) {\n\t\twidth: 100%;\n\t\ttext-align: left;\n\t}\n\t::slotted([slot='root'] + *) {\n\t\tmargin-top: 0.5rem;\n\t}\n`) {\n\t/**\n\t * Whether the tree’s children are visible\n\t */\n\t@property({ type: Boolean }) open = false\n\n\t@query('#toggler') toggler!: HTMLSlotElement\n\t@query('slot:not([name=\"root\"])') defaultSlot!: HTMLSlotElement\n\n\t// Since it's actually a <schmancy-button>, use HTMLElement or a custom type\n\t@query('#chevron') chevron!: HTMLElement\n\n\tprivate readonly _a11yId = `schmancy-tree-${Math.random().toString(36).slice(2, 10)}`\n\tprivate get _contentId() { return `${this._a11yId}-content` }\n\n\t/** ElementInternals — broadcasts `:state(open)` for consumer CSS. */\n\tprivate readonly _internals: ElementInternals | undefined = (() => {\n\t\ttry { return this.attachInternals() } catch { return undefined }\n\t})()\n\n\tupdated(changed: Map<string, unknown>) {\n\t\tsuper.updated?.(changed)\n\t\tif (changed.has('open')) {\n\t\t\tif (this.open) this._internals?.states.add('open')\n\t\t\telse this._internals?.states.delete('open')\n\t\t}\n\t}\n\n\tfirstUpdated() {\n\t\t// Hide or show the slot initially based on `open`\n\t\tif (!this.open) {\n\t\t\tthis.defaultSlot.hidden = true\n\t\t}\n\n\t\t// Root toggler\n\t\tconst toggleClick$ = fromEvent<MouseEvent>(this.toggler, 'click').pipe(\n\t\t\ttakeUntil(this.disconnecting),\n\t\t\ttap(e => {\n\t\t\t\te.preventDefault()\n\t\t\t\te.stopPropagation()\n\t\t\t\tthis.dispatchEvent(new CustomEvent('toggle', { bubbles: false, composed: true }))\n\t\t\t}),\n\t\t)\n\n\t\t// Chevron (the schmancy-button) click\n\t\tconst chevronClick$ = fromEvent<MouseEvent>(this.chevron, 'click')\n\n\t\tmerge(toggleClick$, chevronClick$)\n\t\t\t.pipe(\n\t\t\t\tswitchMap(() => {\n\t\t\t\t\t// 1. Animate the chevron rotation\n\t\t\t\t\t//    If `open` is true, rotate from 180 -> 0; if false, from 0 -> 180\n\t\t\t\t\tconst fromDeg = this.open ? 180 : 0\n\t\t\t\t\tconst toDeg = this.open ? 0 : 180\n\t\t\t\t\tconst chevronAnimation = this.chevron.animate(\n\t\t\t\t\t\t[{ transform: `rotate(${fromDeg}deg)` }, { transform: `rotate(${toDeg}deg)` }],\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tduration: 150,\n\t\t\t\t\t\t\teasing: 'ease-in',\n\t\t\t\t\t\t\tfill: 'forwards',\n\t\t\t\t\t\t},\n\t\t\t\t\t)\n\n\t\t\t\t\t// 2. Animate the slot’s height + opacity\n\t\t\t\t\tif (!this.open) {\n\t\t\t\t\t\t// We are about to open, so remove `hidden` to measure scrollHeight\n\t\t\t\t\t\tthis.defaultSlot.hidden = false\n\t\t\t\t\t}\n\n\t\t\t\t\tconst fromOpacity = this.open ? 1 : 0\n\t\t\t\t\tconst toOpacity = this.open ? 0 : 1\n\n\t\t\t\t\tconst slotAnimation = this.defaultSlot.animate([{ opacity: fromOpacity }, { opacity: toOpacity }], {\n\t\t\t\t\t\tduration: 150,\n\t\t\t\t\t\teasing: 'ease-out',\n\t\t\t\t\t\tfill: 'forwards',\n\t\t\t\t\t})\n\n\t\t\t\t\t// Hide the slot if we just closed it\n\t\t\t\t\tslotAnimation.onfinish = () => {\n\t\t\t\t\t\tif (this.open) {\n\t\t\t\t\t\t\tthis.defaultSlot.hidden = true\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tthis.defaultSlot.style.height = 'auto'\n\t\t\t\t\t\t\tthis.defaultSlot.style.opacity = '1'\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\n\t\t\t\t\t// Return an Observable that completes when both animations finish\n\t\t\t\t\treturn zip(fromEvent(chevronAnimation, 'finish'), fromEvent(slotAnimation, 'finish')).pipe(\n\t\t\t\t\t\ttakeUntil(this.disconnecting),\n\t\t\t\t\t)\n\t\t\t\t}),\n\t\t\t\ttap(() => {\n\t\t\t\t\t// Flip the open state\n\t\t\t\t\tthis.open = !this.open\n\t\t\t\t}),\n\t\t\t\ttakeUntil(this.disconnecting),\n\t\t\t)\n\t\t\t.subscribe()\n\t}\n\n\trender() {\n\t\treturn html`\n\t\t\t<div class=\"flex content-center items-center justify-between\">\n\t\t\t\t<!-- Root toggler content -->\n\t\t\t\t<slot id=\"toggler\" name=\"root\"></slot>\n\n\t\t\t\t<!-- The chevron or arrow symbol -->\n\t\t\t\t<!-- Stop propagation on the schmancy-button itself just to avoid double triggers -->\n\t\t\t\t<schmancy-button\n\t\t\t\t\tslot=\"trailing\"\n\t\t\t\t\tid=\"chevron\"\n\t\t\t\t\taria-expanded=${this.open ? 'true' : 'false'}\n\t\t\t\t\taria-controls=${this._contentId}\n\t\t\t\t\taria-label=${this.open ? 'Collapse' : 'Expand'}\n\t\t\t\t\t@click=${(e: Event) => e.stopPropagation()}\n\t\t\t\t>\n\t\t\t\t\t⌅\n\t\t\t\t</schmancy-button>\n\t\t\t</div>\n\n\t\t\t<!-- The default slot: tree children -->\n\t\t\t<slot id=${this._contentId}></slot>\n\t\t`\n\t}\n}\n\ndeclare global {\n\tinterface HTMLElementTagNameMap {\n\t\t'schmancy-tree': SchmancyTree\n\t}\n}\n"],"mappings":";;;;;;AAWO,IAAA,IAAA,cAA2B,EAAgB,CAAG;;;;;;;;;;;;;;;4BAiBhB,GAAA,KAAA,UAQT,iBAAiB,KAAK,QAAA,CAAS,SAAS,GAAA,CAAI,MAAM,GAAG,GAAA,IAAA,KAAA,oBAAA;AAK/E,OAAA;AAAM,WAAO,KAAK,iBAAA;WAAA;AAA4B;;MAAA;;CAJ/C,IAAA,aAAY;AAAe,SAAO,GAAG,KAAK,QAAA;;CAO1C,QAAQ,GAAA;AACP,QAAM,UAAU,EAAA,EACZ,EAAQ,IAAI,OAAA,KACX,KAAK,OAAM,KAAK,YAAY,OAAO,IAAI,OAAA,GACtC,KAAK,YAAY,OAAO,OAAO,OAAA;;CAItC,eAAA;AAEM,OAAK,SACT,KAAK,YAAY,SAAA,CAAS,IAgB3B,EAZqB,EAAsB,KAAK,SAAS,QAAA,CAAS,KACjE,EAAU,KAAK,cAAA,EACf,GAAI,MAAA;AACH,KAAE,gBAAA,EACF,EAAE,iBAAA,EACF,KAAK,cAAc,IAAI,YAAY,UAAU;IAAE,SAAA,CAAS;IAAO,UAAA,CAAU;IAAA,CAAA,CAAA;IAAA,CAAA,EAKrD,EAAsB,KAAK,SAAS,QAAA,CAAA,CAGxD,KACA,QAAA;GAGC,IAAM,IAAU,KAAK,OAAO,MAAM,GAC5B,IAAQ,KAAK,OAAO,IAAI,KACxB,IAAmB,KAAK,QAAQ,QACrC,CAAC,EAAE,WAAW,UAAU,EAAA,OAAA,EAAiB,EAAE,WAAW,UAAU,EAAA,OAAA,CAAA,EAChE;IACC,UAAU;IACV,QAAQ;IACR,MAAM;IAAA,CAAA;AAKH,QAAK,SAET,KAAK,YAAY,SAAA,CAAS;GAG3B,IAAM,IAAc,QAAK,MACnB,IAAY,OAAK,MAEjB,IAAgB,KAAK,YAAY,QAAQ,CAAC,EAAE,SAAS,GAAA,EAAe,EAAE,SAAS,GAAA,CAAA,EAAc;IAClG,UAAU;IACV,QAAQ;IACR,MAAM;IAAA,CAAA;AAcP,UAVA,EAAc,iBAAA;AACT,SAAK,OACR,KAAK,YAAY,SAAA,CAAS,KAE1B,KAAK,YAAY,MAAM,SAAS,QAChC,KAAK,YAAY,MAAM,UAAU;MAK5B,EAAI,EAAU,GAAkB,SAAA,EAAW,EAAU,GAAe,SAAA,CAAA,CAAW,KACrF,EAAU,KAAK,cAAA,CAAA;IAAA,EAGjB,QAAA;AAEC,QAAK,OAAA,CAAQ,KAAK;IAAA,EAEnB,EAAU,KAAK,cAAA,CAAA,CAEf,WAAA;;CAGH,SAAA;AACC,SAAO,CAAI;;;;;;;;;;qBAUQ,KAAK,OAAO,SAAS,QAAA;qBACrB,KAAK,WAAA;kBACR,KAAK,OAAO,aAAa,SAAA;eAC5B,MAAa,EAAE,iBAAA,CAAA;;;;;;;cAOhB,KAAK,WAAA;;;;GAvHjB,EAAS,EAAE,MAAM,SAAA,CAAA,CAAA,EAAU,EAAA,WAAA,QAAA,KAAA,EAAA,EAAA,EAAA,CAE3B,EAAM,WAAA,CAAA,EAAW,EAAA,WAAA,WAAA,KAAA,EAAA,EAAA,EAAA,CACjB,EAAM,4BAAA,CAAA,EAA0B,EAAA,WAAA,eAAA,KAAA,EAAA,EAAA,EAAA,CAGhC,EAAM,WAAA,CAAA,EAAW,EAAA,WAAA,WAAA,KAAA,EAAA,EAAA,IAAA,EAAA,CAxBlB,EAAc,gBAAA,CAAA,EAAgB,EAAA;AAAA,SAAA,KAAA"}
+{"version":3,"file":"tree.js","names":[],"sources":["../src/tree/tree.ts"],"sourcesContent":["import { TailwindElement } from '@mixins/index'\nimport { css, html } from 'lit'\nimport { customElement, property, query } from 'lit/decorators.js'\nimport { fromEvent, merge, switchMap, takeUntil, tap, zip } from 'rxjs'\n\n/**\n * Expandable tree node — a recursive disclosure widget. One root slot, one default slot for child nodes. Each node can itself contain schmancy-tree children.\n *\n * @element schmancy-tree\n * @summary Use for hierarchical navigation / file-explorer layouts. Each level is a schmancy-tree with a `root` slot (the parent label) and default slot (the children, which may be more schmancy-trees).\n * @example\n * <schmancy-tree>\n *   <schmancy-list-item slot=\"root\">src/</schmancy-list-item>\n *   <schmancy-tree>\n *     <schmancy-list-item slot=\"root\">components/</schmancy-list-item>\n *     <schmancy-list-item>button.ts</schmancy-list-item>\n *   </schmancy-tree>\n * </schmancy-tree>\n * @platform details toggle - Recursive `<details>`-like disclosure. Degrades to a plain nested list if the tag never registers — loses expand/collapse but stays navigable.\n * @slot root - The root element of the tree\n * @slot - The children of the tree\n */\n@customElement('schmancy-tree')\nexport class SchmancyTree extends TailwindElement(css`\n\t:host {\n\t\tdisplay: block;\n\t\tposition: relative;\n\t\tbackground-color: initial;\n\t}\n\t::slotted([slot='root']) {\n\t\twidth: 100%;\n\t\ttext-align: left;\n\t}\n\t::slotted([slot='root'] + *) {\n\t\tmargin-top: 0.5rem;\n\t}\n`) {\n\t/**\n\t * Whether the tree’s children are visible\n\t */\n\t@property({ type: Boolean }) open = false\n\n\t@query('#toggler') toggler!: HTMLSlotElement\n\t@query('slot:not([name=\"root\"])') defaultSlot!: HTMLSlotElement\n\n\t// Since it's actually a <schmancy-button>, use HTMLElement or a custom type\n\t@query('#chevron') chevron!: HTMLElement\n\n\tprivate readonly _a11yId = `schmancy-tree-${Math.random().toString(36).slice(2, 10)}`\n\tprivate get _contentId() { return `${this._a11yId}-content` }\n\n\t/** ElementInternals — broadcasts `:state(open)` for consumer CSS. */\n\tprivate readonly _internals: ElementInternals | undefined = (() => {\n\t\ttry { return this.attachInternals() } catch { return undefined }\n\t})()\n\n\tupdated(changed: Map<string, unknown>) {\n\t\tsuper.updated?.(changed)\n\t\tif (changed.has('open')) {\n\t\t\tif (this.open) this._internals?.states.add('open')\n\t\t\telse this._internals?.states.delete('open')\n\t\t}\n\t}\n\n\tfirstUpdated() {\n\t\t// Hide or show the slot initially based on `open`\n\t\tif (!this.open) {\n\t\t\tthis.defaultSlot.hidden = true\n\t\t}\n\n\t\t// Root toggler\n\t\tconst toggleClick$ = fromEvent<MouseEvent>(this.toggler, 'click').pipe(\n\t\t\ttakeUntil(this.disconnecting),\n\t\t\ttap(e => {\n\t\t\t\te.preventDefault()\n\t\t\t\te.stopPropagation()\n\t\t\t\tthis.dispatchEvent(new CustomEvent('toggle', { bubbles: false, composed: true }))\n\t\t\t}),\n\t\t)\n\n\t\t// Chevron (the schmancy-button) click\n\t\tconst chevronClick$ = fromEvent<MouseEvent>(this.chevron, 'click')\n\n\t\tmerge(toggleClick$, chevronClick$)\n\t\t\t.pipe(\n\t\t\t\tswitchMap(() => {\n\t\t\t\t\t// 1. Animate the chevron rotation\n\t\t\t\t\t//    If `open` is true, rotate from 180 -> 0; if false, from 0 -> 180\n\t\t\t\t\tconst fromDeg = this.open ? 180 : 0\n\t\t\t\t\tconst toDeg = this.open ? 0 : 180\n\t\t\t\t\tconst chevronAnimation = this.chevron.animate(\n\t\t\t\t\t\t[{ transform: `rotate(${fromDeg}deg)` }, { transform: `rotate(${toDeg}deg)` }],\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tduration: 150,\n\t\t\t\t\t\t\teasing: 'ease-in',\n\t\t\t\t\t\t\tfill: 'forwards',\n\t\t\t\t\t\t},\n\t\t\t\t\t)\n\n\t\t\t\t\t// 2. Animate the slot’s height + opacity\n\t\t\t\t\tif (!this.open) {\n\t\t\t\t\t\t// We are about to open, so remove `hidden` to measure scrollHeight\n\t\t\t\t\t\tthis.defaultSlot.hidden = false\n\t\t\t\t\t}\n\n\t\t\t\t\tconst fromOpacity = this.open ? 1 : 0\n\t\t\t\t\tconst toOpacity = this.open ? 0 : 1\n\n\t\t\t\t\tconst slotAnimation = this.defaultSlot.animate([{ opacity: fromOpacity }, { opacity: toOpacity }], {\n\t\t\t\t\t\tduration: 150,\n\t\t\t\t\t\teasing: 'ease-out',\n\t\t\t\t\t\tfill: 'forwards',\n\t\t\t\t\t})\n\n\t\t\t\t\t// Hide the slot if we just closed it\n\t\t\t\t\tslotAnimation.onfinish = () => {\n\t\t\t\t\t\tif (this.open) {\n\t\t\t\t\t\t\tthis.defaultSlot.hidden = true\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tthis.defaultSlot.style.height = 'auto'\n\t\t\t\t\t\t\tthis.defaultSlot.style.opacity = '1'\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\n\t\t\t\t\t// Return an Observable that completes when both animations finish\n\t\t\t\t\treturn zip(fromEvent(chevronAnimation, 'finish'), fromEvent(slotAnimation, 'finish')).pipe(\n\t\t\t\t\t\ttakeUntil(this.disconnecting),\n\t\t\t\t\t)\n\t\t\t\t}),\n\t\t\t\ttap(() => {\n\t\t\t\t\t// Flip the open state\n\t\t\t\t\tthis.open = !this.open\n\t\t\t\t}),\n\t\t\t\ttakeUntil(this.disconnecting),\n\t\t\t)\n\t\t\t.subscribe()\n\t}\n\n\trender() {\n\t\treturn html`\n\t\t\t<div class=\"flex content-center items-center justify-between\">\n\t\t\t\t<!-- Root toggler content -->\n\t\t\t\t<slot id=\"toggler\" name=\"root\"></slot>\n\n\t\t\t\t<!-- The chevron or arrow symbol -->\n\t\t\t\t<!-- Stop propagation on the schmancy-button itself just to avoid double triggers -->\n\t\t\t\t<schmancy-button\n\t\t\t\t\tslot=\"trailing\"\n\t\t\t\t\tid=\"chevron\"\n\t\t\t\t\taria-expanded=${this.open ? 'true' : 'false'}\n\t\t\t\t\taria-controls=${this._contentId}\n\t\t\t\t\taria-label=${this.open ? 'Collapse' : 'Expand'}\n\t\t\t\t\t@click=${(e: Event) => e.stopPropagation()}\n\t\t\t\t>\n\t\t\t\t\t⌅\n\t\t\t\t</schmancy-button>\n\t\t\t</div>\n\n\t\t\t<!-- The default slot: tree children -->\n\t\t\t<slot id=${this._contentId}></slot>\n\t\t`\n\t}\n}\n\ndeclare global {\n\tinterface HTMLElementTagNameMap {\n\t\t'schmancy-tree': SchmancyTree\n\t}\n}\n"],"mappings":";;;;;;AAuBO,IAAA,IAAA,cAA2B,EAAgB,CAAG;;;;;;;;;;;;;;;4BAiBhB,GAAA,KAAA,UAQT,iBAAiB,KAAK,QAAA,CAAS,SAAS,GAAA,CAAI,MAAM,GAAG,GAAA,IAAA,KAAA,oBAAA;AAK/E,OAAA;AAAM,WAAO,KAAK,iBAAA;WAAA;AAA4B;;MAAA;;CAJ/C,IAAA,aAAY;AAAe,SAAO,GAAG,KAAK,QAAA;;CAO1C,QAAQ,GAAA;AACP,QAAM,UAAU,EAAA,EACZ,EAAQ,IAAI,OAAA,KACX,KAAK,OAAM,KAAK,YAAY,OAAO,IAAI,OAAA,GACtC,KAAK,YAAY,OAAO,OAAO,OAAA;;CAItC,eAAA;AAEM,OAAK,SACT,KAAK,YAAY,SAAA,CAAS,IAgB3B,EAZqB,EAAsB,KAAK,SAAS,QAAA,CAAS,KACjE,EAAU,KAAK,cAAA,EACf,GAAI,MAAA;AACH,KAAE,gBAAA,EACF,EAAE,iBAAA,EACF,KAAK,cAAc,IAAI,YAAY,UAAU;IAAE,SAAA,CAAS;IAAO,UAAA,CAAU;IAAA,CAAA,CAAA;IAAA,CAAA,EAKrD,EAAsB,KAAK,SAAS,QAAA,CAAA,CAGxD,KACA,QAAA;GAGC,IAAM,IAAU,KAAK,OAAO,MAAM,GAC5B,IAAQ,KAAK,OAAO,IAAI,KACxB,IAAmB,KAAK,QAAQ,QACrC,CAAC,EAAE,WAAW,UAAU,EAAA,OAAA,EAAiB,EAAE,WAAW,UAAU,EAAA,OAAA,CAAA,EAChE;IACC,UAAU;IACV,QAAQ;IACR,MAAM;IAAA,CAAA;AAKH,QAAK,SAET,KAAK,YAAY,SAAA,CAAS;GAG3B,IAAM,IAAc,QAAK,MACnB,IAAY,OAAK,MAEjB,IAAgB,KAAK,YAAY,QAAQ,CAAC,EAAE,SAAS,GAAA,EAAe,EAAE,SAAS,GAAA,CAAA,EAAc;IAClG,UAAU;IACV,QAAQ;IACR,MAAM;IAAA,CAAA;AAcP,UAVA,EAAc,iBAAA;AACT,SAAK,OACR,KAAK,YAAY,SAAA,CAAS,KAE1B,KAAK,YAAY,MAAM,SAAS,QAChC,KAAK,YAAY,MAAM,UAAU;MAK5B,EAAI,EAAU,GAAkB,SAAA,EAAW,EAAU,GAAe,SAAA,CAAA,CAAW,KACrF,EAAU,KAAK,cAAA,CAAA;IAAA,EAGjB,QAAA;AAEC,QAAK,OAAA,CAAQ,KAAK;IAAA,EAEnB,EAAU,KAAK,cAAA,CAAA,CAEf,WAAA;;CAGH,SAAA;AACC,SAAO,CAAI;;;;;;;;;;qBAUQ,KAAK,OAAO,SAAS,QAAA;qBACrB,KAAK,WAAA;kBACR,KAAK,OAAO,aAAa,SAAA;eAC5B,MAAa,EAAE,iBAAA,CAAA;;;;;;;cAOhB,KAAK,WAAA;;;;GAvHjB,EAAS,EAAE,MAAM,SAAA,CAAA,CAAA,EAAU,EAAA,WAAA,QAAA,KAAA,EAAA,EAAA,EAAA,CAE3B,EAAM,WAAA,CAAA,EAAW,EAAA,WAAA,WAAA,KAAA,EAAA,EAAA,EAAA,CACjB,EAAM,4BAAA,CAAA,EAA0B,EAAA,WAAA,eAAA,KAAA,EAAA,EAAA,EAAA,CAGhC,EAAM,WAAA,CAAA,EAAW,EAAA,WAAA,WAAA,KAAA,EAAA,EAAA,IAAA,EAAA,CAxBlB,EAAc,gBAAA,CAAA,EAAgB,EAAA;AAAA,SAAA,KAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mhmo91/schmancy",
-	"version": "0.9.15",
+	"version": "0.9.17",
 	"description": "UI library build with web components",
 	"main": "./dist/index.js",
 	"customElements": "custom-elements.json",

package/src/autocomplete/autocomplete.ts

@@ -36,7 +36,18 @@ interface FilteredOption {
 }
 
 /**
- * Autocomplete input component with filtering and multi-select support.
+ * Combobox with type-ahead filtering over a list of `<schmancy-option>` children. Single or multi-select. Form-associated.
+ *
+ * @element schmancy-autocomplete
+ * @summary Use when users need to pick from a known list of options but the list is too long for a plain select dropdown. Prefer schmancy-select for short static lists.
+ * @example
+ * <schmancy-autocomplete name="country" label="Country" placeholder="Start typing…">
+ *   <schmancy-option value="US">United States</schmancy-option>
+ *   <schmancy-option value="CA">Canada</schmancy-option>
+ *   <schmancy-option value="GB">United Kingdom</schmancy-option>
+ * </schmancy-autocomplete>
+ * @platform combobox change - Composed of a schmancy-input + a floating listbox populated from `<schmancy-option>` children. Multi-select renders selections as schmancy-input-chip chips. Degrades to a datalist-backed native input if the tag never registers.
+ * @fires change - `SchmancyAutocompleteChangeEvent` with `{ value }` (single) or `{ value, values }` (multi).
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} label - Label text displayed above the input

package/src/button/button.ts

@@ -16,8 +16,13 @@ export type ButtonVariant = 'elevated' | 'filled' | 'filled tonal' | 'tonal' | '
 export type ButtonColor = 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info' | 'neutral'
 
 /**
- * A button component.
+ * Material Design button — primary interactive surface for triggering actions or navigation.
  * @element schmancy-button
+ * @summary Trigger actions or navigate. Form-associated; participates in native form submission.
+ * @example
+ * <schmancy-button variant="filled" @click=${() => save()}>Save</schmancy-button>
+ * <schmancy-button variant="outlined" href="/next">Continue</schmancy-button>
+ * @platform button click - Schmancy-skinned native `<button type="submit">`. When `href` is set, degrades to `<a href="…">`. Falls back to plain `<button>` styled with Tailwind if the tag never registers.
  * @slot - The default slot.
  * @slot prefix - The prefix slot.
  * @slot suffix - The suffix slot.

package/src/button/icon-button.ts

@@ -7,8 +7,14 @@ import { magnetic } from '../directives/magnetic'
 import { ButtonVariant } from './button'
 
 /**
- * An icon button component.
+ * Icon-only button for toolbar actions, close affordances, or overflow menus.
  * @element schmancy-icon-button
+ * @summary Compact round/square button wrapping a single icon glyph. Form-associated like schmancy-button.
+ * @example
+ * <schmancy-icon-button aria-label="Close" @click=${() => close()}>
+ *   <schmancy-icon>close</schmancy-icon>
+ * </schmancy-icon-button>
+ * @platform button click - Schmancy-skinned native `<button>` (or `<a>` when `href` is set). aria-label is required for a11y because there's no text content.
  * @slot - The default slot (usually an icon or glyph).
  * @csspart base - The underlying native `<button>` (or `<a>` when `href` is set).
  */

package/src/card/actions.ts

@@ -3,7 +3,16 @@ import { css, html } from 'lit'
 import { customElement } from 'lit/decorators.js'
 
 /**
+ * Action row of a schmancy-card — holds the card's buttons / links (typically aligned bottom-right).
+ *
  * @element schmancy-card-action
+ * @summary Always nested inside schmancy-card. Holds the primary + secondary CTAs for the card.
+ * @example
+ * <schmancy-card-action>
+ *   <schmancy-button variant="text">Cancel</schmancy-button>
+ *   <schmancy-button variant="filled">Save</schmancy-button>
+ * </schmancy-card-action>
+ * @platform div - Styled flex container. Degrades to a plain div if the tag never registers.
  * @slot - The content of the action
  */
 @customElement('schmancy-card-action')

package/src/card/card.ts

@@ -4,6 +4,24 @@ import { customElement, property, state } from 'lit/decorators.js'
 import { cursorGlow } from '../directives/cursor-glow'
 import { ifDefined } from 'lit/directives/if-defined.js'
 
+/**
+ * Material Design card — a surface-level container for grouping related content with media / content / actions slots.
+ *
+ * @element schmancy-card
+ * @summary Use for discrete pieces of content that appear in a list (a product, a note, a message). Combine with schmancy-card-media / schmancy-card-content / schmancy-card-action children.
+ * @example
+ * <schmancy-card type="elevated" href="/items/42">
+ *   <schmancy-card-media src="/thumb.jpg" alt="Thumbnail"></schmancy-card-media>
+ *   <schmancy-card-content>
+ *     <h3>Title</h3>
+ *     <p>One-line description of the card's content.</p>
+ *   </schmancy-card-content>
+ *   <schmancy-card-action>
+ *     <schmancy-button variant="text">Open</schmancy-button>
+ *   </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.
+ */
 @customElement('schmancy-card')
 export default class SchmancyCard extends TailwindElement(css`
 	:host {

package/src/card/content.ts

@@ -3,7 +3,16 @@ import { css, html } from 'lit'
 import { customElement } from 'lit/decorators.js'
 
 /**
+ * Content region of a schmancy-card — holds the card's headline, supporting text, and inline controls.
+ *
  * @element schmancy-card-content
+ * @summary Always nested inside schmancy-card. The padded content block between the media and action rows.
+ * @example
+ * <schmancy-card-content>
+ *   <h3>Card title</h3>
+ *   <p>Supporting text that describes the card's subject.</p>
+ * </schmancy-card-content>
+ * @platform div - Styled `<div>` with padding. Degrades to a plain div if the tag never registers.
  */
 @customElement('schmancy-card-content')
 export default class SchmancyCardContent extends TailwindElement(css`

package/src/card/media.ts

@@ -3,7 +3,13 @@ import { css, html } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 
 /**
+ * Media region of a schmancy-card — the image / thumbnail at the top of the card.
+ *
  * @element schmancy-card-media
+ * @summary Always nested inside schmancy-card. Pass `src` + `alt` props or slot an `<img>` / `<video>` for custom media.
+ * @example
+ * <schmancy-card-media src="/thumb.jpg" alt="Product photo"></schmancy-card-media>
+ * @platform img - Renders an `<img>` (or wraps a slotted media element). Degrades to a styled `<img>` if the tag never registers.
  */
 @customElement('schmancy-card-media')
 export default class SchmancyCardMedia extends TailwindElement(css`

package/src/checkbox/checkbox.ts

@@ -9,9 +9,15 @@ export type schmancyCheckBoxChangeEvent = CustomEvent<{
 }>
 
 /**
+ * Binary checkbox for multi-select or boolean form fields. Wraps Material Web's `<md-checkbox>`; form-associated.
+ *
  * @element schmancy-checkbox
+ * @summary Use for "select many from a list" or any boolean that's part of a form submission. Prefer schmancy-switch for immediate-effect toggles.
+ * @example
+ * <schmancy-checkbox name="tos" required>I accept the terms</schmancy-checkbox>
+ * @platform checkbox change - Wraps `<md-checkbox>` from `@material/web`. Degrades to styled native `<input type="checkbox">` if the tag never registers.
  * @slot - The label for the checkbox.
- * @fires valueChange - Event fired when the checkbox value changes.
+ * @fires valueChange - `CustomEvent<{ value: boolean }>` when the checkbox is toggled.
  **/
 
 @customElement('schmancy-checkbox')

package/src/chips/chips.ts

@@ -7,6 +7,20 @@ import { fullWidth } from '../directives/layout'
 import type { FilterChipChangeEvent as SchmancyChipChangeEvent } from './filter-chip'
 import { SchmancyFilterChip as SchmancyChip } from './filter-chip'
 
+/**
+ * Filter-chip group — container for selectable `<schmancy-chip>` children. Single or multi-select.
+ *
+ * @element schmancy-chips
+ * @summary Use for filtering or choosing from 2–8 mutually-visible options ("Status: active / paused / archived"). Prefer schmancy-select when the list gets long or vertical.
+ * @example
+ * <schmancy-chips multi @change=${(e) => this.filters = e.detail.values}>
+ *   <schmancy-chip value="active">Active</schmancy-chip>
+ *   <schmancy-chip value="paused">Paused</schmancy-chip>
+ *   <schmancy-chip value="archived">Archived</schmancy-chip>
+ * </schmancy-chips>
+ * @platform chip-group change - No direct native equivalent. Degrades to a styled schmancy-select with similar semantics if the tag never registers.
+ * @fires change - `CustomEvent<{ value: string }>` (single) or `{ values: string[] }` (multi).
+ */
 @customElement('schmancy-chips')
 export default class SchmancyChips extends $LitElement(
 

package/src/chips/input-chip.ts

@@ -6,7 +6,7 @@ import { BehaviorSubject, combineLatest } from 'rxjs'
 import { map, takeUntil, tap } from 'rxjs/operators'
 
 /**
- * Input chip component - represents user-provided information that can be removed.
+ * Input chip — displays user-provided information (tags, recipients, filters) that can be removed but not toggled.
  *
  * IMPORTANT: Per Material Design 3 specification, input chips do NOT have selected state.
  * They represent discrete pieces of user input (like entered tags, selections from lists, etc.)
@@ -18,15 +18,15 @@ import { map, takeUntil, tap } from 'rxjs/operators'
  * - Tags or keywords entered by the user
  * - Selected items from a multi-select dropdown
  *
- * @fires click - Optional click event on chip body (value)
- * @fires remove - Dispatched when remove button is clicked (value)
- *
+ * @element schmancy-input-chip
+ * @summary Removable pill that represents a single user input value. No selected state — use schmancy-chip (filter chip) for toggleable options.
  * @example
- * ```html
  * <schmancy-input-chip value="john@example.com" avatar="/avatars/john.jpg">
  *   John Doe
  * </schmancy-input-chip>
- * ```
+ * @platform chip remove - No native equivalent. Composed of a labeled pill + close button. Degrades to a styled `<span>` with a trailing close `<button>` if the tag never registers.
+ * @fires click - Optional click event on chip body (value)
+ * @fires remove - Dispatched when remove button is clicked (value)
  */
 @customElement('schmancy-input-chip')
 export class SchmancyInputChip extends TailwindElement(css`

package/src/details/details.ts

@@ -9,6 +9,18 @@ import { distinctUntilChanged, filter, take, takeUntil, tap } from 'rxjs/operato
 import { SPRING_SNAPPY } from '../utils/animation.js'
 import { reducedMotion$ } from '../directives/reduced-motion'
 
+/**
+ * Expandable disclosure panel — a styled `<details>` / `<summary>` pair with animated expand + overlay options.
+ *
+ * @element schmancy-details
+ * @summary Use for progressive-disclosure content: FAQs, collapsible settings sections, accordion-style lists. Prefer schmancy-expand for full-page accordions where only one section can be open at a time.
+ * @example
+ * <schmancy-details summary="Shipping details">
+ *   <p>Order ships in 2 business days.</p>
+ * </schmancy-details>
+ * @platform details toggle - Wraps native `<details>`/`<summary>`. Degrades to the native element if the tag never registers — same keyboard accessibility, just no animation.
+ * @fires toggle - When the open state changes (bubbles from the native `<details>`).
+ */
 @customElement('schmancy-details')
 export default class SchmancyDetails extends SurfaceMixin(
 	TailwindElement(css`

package/src/divider/divider.ts

@@ -3,6 +3,17 @@ import { $LitElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 
+/**
+ * Thin horizontal (or vertical) separator rule between sections of content.
+ *
+ * @element schmancy-divider
+ * @summary Semantic separator between groups — list items, menu sections, content blocks. Uses outline theme token.
+ * @example
+ * <schmancy-list-item>First</schmancy-list-item>
+ * <schmancy-divider></schmancy-divider>
+ * <schmancy-list-item>Second</schmancy-list-item>
+ * @platform hr - Styled horizontal rule. Degrades to a native `<hr>` if the tag never registers.
+ */
 @customElement('schmancy-divider')
 export default class SchmancyDivider extends $LitElement(css`
 	:host {

package/src/expand/expand-root.component.ts

@@ -7,6 +7,18 @@ import { SPRING_SMOOTH } from '../utils/animation.js'
 import { reducedMotion$ } from '../directives/reduced-motion'
 import '../surface/surface.js'
 
+/**
+ * Container for schmancy-expand children — coordinates mutual-exclusion so only one child is open at a time. Also renders the portal panel that the active child expands into.
+ *
+ * @element schmancy-expand-root
+ * @summary Always wrap a group of schmancy-expand children. Without a root, each schmancy-expand behaves independently (which is usually not what you want — prefer schmancy-details for that).
+ * @example
+ * <schmancy-expand-root>
+ *   <schmancy-expand summary="Step 1">…</schmancy-expand>
+ *   <schmancy-expand summary="Step 2">…</schmancy-expand>
+ * </schmancy-expand-root>
+ * @platform div - Coordinating wrapper. Degrades to a plain div if the tag never registers — children fall back to independent `<details>` behavior.
+ */
 @customElement('schmancy-expand-root')
 export class SchmancyExpandRoot extends SurfaceMixin(TailwindElement(css`
 	:host {

package/src/expand/expand.component.ts

@@ -12,6 +12,20 @@ import { SchmancyExpandRoot } from './expand-root.component.js'
 /** Dispatch this event on window to close whichever schmancy-expand is currently open */
 export const SCHMANCY_EXPAND_REQUEST_CLOSE = 'schmancy-expand-request-close'
 
+/**
+ * Accordion-style section — expands on click, coordinates with siblings via schmancy-expand-root to close any sibling when a new one opens. Only one schmancy-expand can be open at a time within the same root.
+ *
+ * @element schmancy-expand
+ * @summary Use for grouped progressive-disclosure where only one section should be open at a time. Prefer schmancy-details when sections should be independent.
+ * @example
+ * <schmancy-expand-root>
+ *   <schmancy-expand summary="Billing">Billing form…</schmancy-expand>
+ *   <schmancy-expand summary="Shipping">Shipping form…</schmancy-expand>
+ *   <schmancy-expand summary="Review">Order review…</schmancy-expand>
+ * </schmancy-expand-root>
+ * @platform details toggle - Schmancy-skinned accordion section. Degrades to `<details>` if the tag never registers — loses mutual-exclusion behavior but stays functional.
+ * @fires toggle - When the open state changes.
+ */
 @customElement('schmancy-expand')
 export default class SchmancyExpand extends TailwindElement(css`
 	:host {

package/src/extra/countries/countries.ts

@@ -6,6 +6,16 @@ import { repeat } from 'lit/directives/repeat.js'
 import countriesData from './countries.data'
 import SchmancyAutocomplete from '@schmancy/autocomplete/autocomplete'
 
+/**
+ * Country picker — type-ahead autocomplete over the ISO 3166-1 country list. Form-associated.
+ *
+ * @element schmancy-select-countries
+ * @summary Drop-in replacement for schmancy-autocomplete when the options are specifically "every country". Pre-seeds the list from countries.data.
+ * @example
+ * <schmancy-select-countries name="country" label="Shipping country" required></schmancy-select-countries>
+ * @platform combobox change - Composes schmancy-autocomplete with a static options list. Value is the 2-letter ISO code.
+ * @fires change - `SchmancyAutocompleteChangeEvent` with `{ value: string }` (the ISO code).
+ */
 @customElement('schmancy-select-countries')
 export class SchmancyCountriesSelect extends $LitElement(css`
 	:host {

package/src/extra/timezone/timezone.ts

@@ -6,7 +6,14 @@ import timezonesData from './timezones.data'
 import SchmancyAutocomplete from '@schmancy/autocomplete/autocomplete'
 
 /**
- * Timezone selector component with autocomplete filtering.
+ * Timezone picker — type-ahead autocomplete over the IANA tz database. Form-associated.
+ *
+ * @element schmancy-select-timezones
+ * @summary Drop-in replacement for schmancy-autocomplete when the options are IANA timezone names. Value is the IANA identifier ("America/Los_Angeles").
+ * @example
+ * <schmancy-select-timezones name="tz" label="Timezone" value="America/New_York"></schmancy-select-timezones>
+ * @platform combobox change - Composes schmancy-autocomplete with a static IANA timezones list.
+ * @fires change - `SchmancyAutocompleteChangeEvent` with `{ value: string }` (the IANA tz name).
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} value - Selected timezone value

package/src/form/form.ts

@@ -1,8 +1,7 @@
 import { customElement } from 'lit/decorators.js'
 
 /**
- * A thin ergonomic wrapper around a native `<form>` element. Its children are
- * reparented into a `<form>` element in light DOM on connection, so:
+ * Ergonomic wrapper around a native `<form>`. Children are reparented into a light-DOM `<form>` on connection so form-associated custom elements resolve `internals.form` via native DOM ancestry.
  *
  * - Form-associated custom elements (FACE) resolve their `internals.form`
  *   correctly via native DOM ancestry.
@@ -18,6 +17,14 @@ import { customElement } from 'lit/decorators.js'
  * lifting is the platform's.
  *
  * @element schmancy-form
+ * @summary Always wrap form-associated schmancy components in schmancy-form (or a native `<form>`) so `new FormData(form)` just works.
+ * @example
+ * <schmancy-form @submit=${(e) => console.log(Object.fromEntries(e.detail))}>
+ *   <schmancy-input name="email" type="email" required></schmancy-input>
+ *   <schmancy-input name="password" type="password" required></schmancy-input>
+ *   <schmancy-button type="submit" variant="filled">Sign in</schmancy-button>
+ * </schmancy-form>
+ * @platform form submit - Light-DOM native `<form>` element. Degrades to a `<form>` if the tag never registers — same semantics, just no CustomEvent translation.
  * @fires submit - `CustomEvent<FormData>` emitted when the form is submitted.
  * @fires reset - Emitted after the underlying form resets.
  */

package/src/input/input.ts

@@ -43,11 +43,18 @@ export type SchmancyInputEnterEvent = CustomEvent<EventDetails>
 export type InputSize = 'xxs' | 'xs' | 'sm' | 'md' | 'lg'
 
 /**
- * Enhanced version of the SchmancyInput component with improved form integration
- * and compatibility with legacy API.
+ * Single-line text input — the primary form-text primitive. Form-associated via ElementInternals, so it participates in native `<form>` submission, validation, and reset without additional wiring.
  *
- * This component uses the native form association API and maintains parity with
- * native input behaviors while providing a stylish, accessible interface.
+ * @element schmancy-input
+ * @summary Text input with Material Design styling, native form integration, and RxJS-debounced input/change/enter events.
+ * @example
+ * <schmancy-form @submit=${onSubmit}>
+ *   <schmancy-input name="email" type="email" label="Email" required></schmancy-input>
+ * </schmancy-form>
+ * @platform input change - Schmancy-skinned native `<input>`. Degrades to `<input class="…">` styled via Tailwind if the tag never registers.
+ * @fires input - `CustomEvent<{value: string}>` on every keystroke.
+ * @fires change - `CustomEvent<{value: string}>` on blur/change.
+ * @fires enter - `CustomEvent<{value: string}>` when user presses Enter.
  *
  * @prop {string} name - Name attribute for form submission (inherited from FormFieldMixin)
  * @prop {string} label - Label text for the form field (inherited from FormFieldMixin)

package/src/layout/scroll/scroll.ts

@@ -49,7 +49,11 @@ declare global {
 }
 
 /**
- * A custom scrollable container with enhanced features.
+ * Scrollable container with debounced scroll events, horizontal/vertical direction, optional hidden scrollbar, and programmatic scrollTo via command events or refs.
+ *
+ * @element schmancy-scroll
+ * @summary Use anywhere you'd reach for `overflow: auto` but also need debounced scroll events (for sticky headers, scroll spies, virtualization triggers) or the ability to drive scroll from elsewhere in the app by dispatching a schmancy-scroll-command event.
+ * @platform div - Styled scrollable `<div>`. Degrades to a plain scrollable div if the tag never registers — loses the debounced scroll event and the command-bus integration.
  *
  * @fires {SchmancyScrollEvent} scroll - Fired when scrolling occurs (with a configurable debounce)
  * @slot - Default slot for content to be scrolled

package/src/page/page.ts

@@ -8,20 +8,17 @@ import { theme } from '../theme/theme.service'
 import { fromResizeObserver } from '../directives/layout'
 
 /**
- * Native mobile-like page container.
- * Prevents double-tap zoom, pull-to-refresh, rubber-banding.
- * Automatically fills remaining viewport height.
+ * Mobile-first page container — fills remaining viewport height, suppresses double-tap zoom / pull-to-refresh / rubber-banding. Lays children in a CSS grid whose row template is `rows`.
  *
  * @element schmancy-page
- *
+ * @summary The root of any app view — wraps header / main / footer children in a full-viewport grid. Use rows="auto_1fr_auto" to make the middle child scroll while header/footer stay pinned.
  * @example
- * html`
- *   <schmancy-page rows="1fr_2fr_auto">
- *     <header>App Bar</header>
- *     <main>Scrollable content</main>
- *     <footer>Navigation</footer>
- *   </schmancy-page>
- * `
+ * <schmancy-page rows="auto_1fr_auto">
+ *   <schmancy-nav-drawer-appbar>Title</schmancy-nav-drawer-appbar>
+ *   <main>Scrollable content</main>
+ *   <schmancy-navigation-bar></schmancy-navigation-bar>
+ * </schmancy-page>
+ * @platform div - Full-height CSS-grid container. Degrades to a plain div if the tag never registers — children still flow vertically but without the height fill and gesture suppression.
  */
 @customElement('schmancy-page')
 export class SchmancyPage extends $LitElement(css`

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

@@ -5,7 +5,16 @@ import { FormFieldMixin } from '../../mixins/formField.mixin'
 import { fromEvent, takeUntil } from 'rxjs'
 
 /**
- * Radio button component for use within radio groups.
+ * Single radio button — always rendered as a child of `<schmancy-radio-group>`, never standalone.
+ *
+ * @element schmancy-radio-button
+ * @summary Low-level primitive. Use schmancy-radio-group and pass `.options` for the common path; only instantiate schmancy-radio-button directly when you need per-button custom rendering.
+ * @example
+ * <schmancy-radio-group name="plan">
+ *   <schmancy-radio-button value="free">Free</schmancy-radio-button>
+ *   <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.
  *
  * @prop {string} name - Name attribute for grouping radio buttons
  * @prop {string} value - Value of this radio button

package/src/radio-group/radio-group.ts

@@ -13,6 +13,24 @@ export type SchmancyRadioGroupOption = {
 export type SchmancyRadioGroupChangeEvent = CustomEvent<{
 	value: string
 }>
+/**
+ * Radio-button group — single-select from a static list of mutually-exclusive options. Form-associated.
+ *
+ * @element schmancy-radio-group
+ * @summary Use for 2–5 mutually-exclusive options where all should stay visible ("Shipping: standard / express / overnight"). Prefer schmancy-select when the list grows.
+ * @example
+ * <schmancy-radio-group
+ *   name="shipping"
+ *   label="Shipping"
+ *   .options=${[
+ *     { label: 'Standard (5 days)', value: 'standard' },
+ *     { label: 'Express (2 days)', value: 'express' },
+ *     { label: 'Overnight', value: 'overnight' },
+ *   ]}
+ * ></schmancy-radio-group>
+ * @platform radiogroup change - Renders schmancy-radio-button children. Degrades to a fieldset with native `<input type="radio" name="…">` siblings if the tag never registers.
+ * @fires change - `SchmancyRadioGroupChangeEvent` with the selected `value`.
+ */
 @customElement('schmancy-radio-group')
 export class RadioGroup extends FormFieldMixin(TailwindElement(style)) {
 	@property({ type: String }) override label = ''

package/src/select/select.ts

@@ -15,7 +15,18 @@ export type SchmancySelectChangeEvent = CustomEvent<{
 }>
 
 /**
- * Select dropdown component with single and multi-select support.
+ * Dropdown selector — single or multi-select from a list of `<schmancy-option>` children. Form-associated.
+ *
+ * @element schmancy-select
+ * @summary Material Design dropdown with type-to-filter, keyboard nav, single or multi-select. Options are declared as `<schmancy-option>` children; value / values props sync with selection.
+ * @example
+ * <schmancy-select name="priority" label="Priority" value="medium">
+ *   <schmancy-option value="low">Low</schmancy-option>
+ *   <schmancy-option value="medium">Medium</schmancy-option>
+ *   <schmancy-option value="high">High</schmancy-option>
+ * </schmancy-select>
+ * @platform select change - Floating-UI-positioned listbox. Degrades to native `<select>` styled via Tailwind if the tag never registers, though multi-select UX is lost.
+ * @fires change - `SchmancySelectChangeEvent` with `{ value }` (single) or `{ value: string[] }` (multi).
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} label - Label text displayed above the select

package/src/surface/surface.ts

@@ -11,22 +11,16 @@ export const SchmancySurfaceTypeContext = createContext<TSurfaceColor>('surface'
 export type { SchmancySurfaceFill, SchmancySurfaceRounded, SchmancySurfaceElevation } from '@mixins/surface.mixin'
 
 /**
- * `<schmancy-surface>` component
- *
- * This component renders a styled container that adapts its dimensions based on the `fill` property.
- * It supports various rounding options, elevation levels, and applies background and text color classes
- * based on the specified surface variant. Additionally, when the `scroller` property is true, the component
- * enables internal scrolling by applying overflow and scroll-behavior styles.
- *
- * SurfaceMixin automatically provides surfaceStyles CSS.
+ * Themed container — the root surface primitive. Sets background, text color, rounding, elevation, and (optionally) internal scroll. Provides a `SchmancySurfaceTypeContext` so descendants can adapt to the enclosing surface variant.
  *
  * @element schmancy-surface
- * @slot - Default slot for projecting child content.
- *
+ * @summary Wrap a region of a page when you need it to pick up theme tokens (background + on-color + elevation). Nest surfaces to express Material Design's hierarchical color stacking.
  * @example
  * <schmancy-surface fill="all" rounded="all" elevation="3" type="surfaceBright" scroller>
  *   <p>Your scrollable content here</p>
  * </schmancy-surface>
+ * @platform div - Styled `<div>` with theme-driven background/color/elevation. Degrades to a plain `<div>` if the tag never registers — text stays readable, just loses theming.
+ * @slot - Default slot for projecting child content.
  */
 @customElement('schmancy-surface')
 export class SchmancySurface extends SurfaceMixin(

package/src/switch/switch.ts

@@ -5,12 +5,15 @@ import { customElement, property } from 'lit/decorators.js'
 export type SchmancySwitchChangeEvent = CustomEvent<{ value: boolean }>
 
 /**
- * Binary on/off control. Form-associated, keyboard-accessible, semantically a
- * switch (ARIA role="switch"). Distinct from `schmancy-checkbox`: a switch
- * represents an immediate state change, a checkbox represents a selection in
- * a form to be submitted.
+ * Binary on/off control with immediate effect. Form-associated, keyboard-accessible, semantically a switch (ARIA role="switch"). Distinct from `schmancy-checkbox`: a switch represents an immediate state change, a checkbox represents a selection in a form to be submitted.
  *
  * @element schmancy-switch
+ * @summary Use when flipping the control takes effect right away (e.g. "Dark mode", "Enable notifications"). Prefer schmancy-checkbox for form submissions.
+ * @example
+ * <schmancy-switch ?checked=${this.darkMode} @change=${(e) => this.darkMode = e.detail.value}>
+ *   Dark mode
+ * </schmancy-switch>
+ * @platform switch change - Accessible native `<button role="switch" aria-checked>` under the hood. No native HTML element exists; falls back to a styled checkbox if the tag never registers.
  * @fires change - `CustomEvent<{ value: boolean }>` when the state changes.
  * @attr checked - Initial checked state (also reflected via `value`).
  * @attr disabled - Disables interaction.