@mhmo91/schmancy 0.9.16 → 0.9.18

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":"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"}
+{"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.16",
+	"version": "0.9.18",
 	"description": "UI library build with web components",
 	"main": "./dist/index.js",
 	"customElements": "custom-elements.json",

package/src/breadcrumb/breadcrumb.ts

@@ -3,10 +3,17 @@ import { css, html } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 
 /**
- * Breadcrumb navigation container. Wraps a list of `schmancy-breadcrumb-item`
- * elements with the correct ARIA landmark and semantics.
+ * Breadcrumb trail — navigation history from root to current page. Renders schmancy-breadcrumb-item children with separators between.
  *
  * @element schmancy-breadcrumb
+ * @summary Use for deep hierarchical navigation (file explorer paths, e-commerce category chains, admin settings trees). Last item is styled as the current page automatically.
+ * @example
+ * <schmancy-breadcrumb separator="›">
+ *   <schmancy-breadcrumb-item href="/">Home</schmancy-breadcrumb-item>
+ *   <schmancy-breadcrumb-item href="/docs">Docs</schmancy-breadcrumb-item>
+ *   <schmancy-breadcrumb-item>Getting started</schmancy-breadcrumb-item>
+ * </schmancy-breadcrumb>
+ * @platform nav - Styled `<nav aria-label="Breadcrumb">`. Degrades to a plain nav if the tag never registers.
  * @slot - Default slot for `<schmancy-breadcrumb-item>` children.
  * @attr separator - Character or string rendered between items. Default `/`.
  * @csspart separator - The separator element.
@@ -69,10 +76,13 @@ export class SchmancyBreadcrumb extends TailwindElement(css`
 }
 
 /**
- * Individual breadcrumb item. Renders as a link when `href` is provided,
- * otherwise as a plain span (represents the current page).
+ * Single segment in a schmancy-breadcrumb trail — a link when `href` is set, or a plain span (the current page) when omitted.
  *
  * @element schmancy-breadcrumb-item
+ * @summary Always nested inside schmancy-breadcrumb. Omit `href` on the current page — it gets aria-current="page" automatically.
+ * @example
+ * <schmancy-breadcrumb-item href="/products">Products</schmancy-breadcrumb-item>
+ * @platform a - Renders an `<a>` or `<span>` depending on href. Degrades to a plain anchor/span if the tag never registers.
  * @slot - Label content.
  * @attr href - If set, renders as an anchor.
  * @attr current - Marks as `aria-current="page"`.

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/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/dialog/dialog.component.ts

@@ -10,28 +10,28 @@ import { DialogBase } from './dialog-base.mixin'
 import { DialogHereMorty, DialogWhereAreYouRicky, DialogWhereAreYouRickyEvent } from './dialog-events'
 
 /**
- * Unified dialog component that handles both content-only and confirm modes.
+ * Modal dialog — content-only (just a styled panel) or confirm mode (title + message + confirm/cancel buttons). Prefer the imperative `$dialog` service for most use cases; use the element directly only when you want a declaratively-positioned dialog.
  *
  * @element schmancy-dialog
+ * @summary Blocks interaction with the rest of the page until dismissed. For quick confirmations, prefer `$dialog.confirm({ ... })` over this element. For arbitrary dialog content driven imperatively, prefer `$dialog.component(MyComponent)`.
+ * @platform dialog close - Positioned overlay in light DOM. Degrades to a styled `<dialog>` if the tag never registers — loses custom animations but keeps focus trap + ESC close.
  * @slot default - Content slot for dialog body (used in content mode)
  * @slot content - Named slot for custom content in confirm mode
+ * @fires confirm - In confirm mode, when the confirm button is clicked.
+ * @fires cancel - In confirm mode, when the cancel button or ESC is activated.
  *
  * @example Content mode (no buttons):
- * ```html
  * <schmancy-dialog>
  *   <my-custom-content></my-custom-content>
  * </schmancy-dialog>
- * ```
  *
  * @example Confirm mode (with buttons):
- * ```html
  * <schmancy-dialog
- *   title="Confirm Action"
- *   message="Are you sure?"
- *   confirm-text="Yes"
- *   cancel-text="No"
+ *   title="Delete item?"
+ *   message="This action cannot be undone."
+ *   confirm-text="Delete"
+ *   cancel-text="Keep"
  * ></schmancy-dialog>
- * ```
  */
 @customElement('schmancy-dialog')
 export class SchmancyDialog extends DialogBase(

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/dropdown/dropdown-component.ts

@@ -5,9 +5,21 @@ import { customElement, property, query, queryAssignedElements, state } from 'li
 import { filter, fromEvent, takeUntil, Subscription } from 'rxjs'
 
 /**
- * A dropdown component that displays content when triggered.
+ * Anchored floating dropdown — a generic "show this content relative to that trigger" primitive. Unlike schmancy-menu (which uses the dialog service and is list-shaped), dropdown is a low-level popover anchored with Floating UI. Use when you want a custom-shaped overlay tied to a specific trigger element without the menu semantics.
  *
  * @element schmancy-dropdown
+ * @summary Prefer schmancy-menu for action lists, schmancy-autocomplete for type-ahead, schmancy-tooltip for hover hints. Reach for schmancy-dropdown when none of those fit — custom filters, color pickers, inline forms anchored to a trigger.
+ * @example
+ * <schmancy-dropdown>
+ *   <schmancy-button slot="trigger">Filters</schmancy-button>
+ *   <schmancy-dropdown-content>
+ *     <schmancy-form>…</schmancy-form>
+ *   </schmancy-dropdown-content>
+ * </schmancy-dropdown>
+ * @platform div - Anchored via Floating UI (autoUpdate, flip, shift). Degrades to inline content if the tag never registers — loses positioning but content stays accessible.
+ * @attr open - Boolean; whether the dropdown is visible.
+ * @fires open - When the dropdown opens.
+ * @fires close - When the dropdown closes.
  * @slot trigger - The element that triggers the dropdown
  * @slot - Default slot for the dropdown content
  */

package/src/dropdown/dropdown-content.ts

@@ -3,12 +3,20 @@ import { css, html } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 
 /**
- * Content container for the schmancy-dropdown component.
+ * Content panel for a schmancy-dropdown — a styled positioned surface. Always nested inside schmancy-dropdown and placed alongside the trigger slot.
  *
  * @element schmancy-dropdown-content
+ * @summary Nest this inside schmancy-dropdown (not in the trigger slot). Use the `content` CSS part to customize backgrounds / shadows / padding without shadow-root piercing.
+ * @example
+ * <schmancy-dropdown>
+ *   <schmancy-button slot="trigger">Open</schmancy-button>
+ *   <schmancy-dropdown-content>
+ *     Panel contents…
+ *   </schmancy-dropdown-content>
+ * </schmancy-dropdown>
+ * @platform div - Positioned panel with theme-aware styling. Degrades to an inline div if the tag never registers.
  * @slot - Default slot for dropdown content.
- * @csspart content - The inner wrapper element; style to override panel
- *   backgrounds, shadows, padding, or borders without shadow-root piercing.
+ * @csspart content - The inner wrapper element; style to override panel backgrounds, shadows, padding, or borders without shadow-root piercing.
  */
 @customElement('schmancy-dropdown-content')
 export class SchmancyDropdownContent extends TailwindElement(css`

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/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/list/list-item.ts

@@ -6,7 +6,17 @@ import { css, html } from 'lit'
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js'
 
 /**
+ * Single row in a schmancy-list — supports leading icon/avatar, main content, trailing actions. Clickable via click event, or used as a schmancy-menu-item's visual base.
+ *
  * @element schmancy-list-item
+ * @summary Prefer nesting inside schmancy-list for consistent spacing/surface. Use `href` to make the row a navigation target (renders as `<a>`), or a click handler for in-app actions.
+ * @example
+ * <schmancy-list-item href="/profile">
+ *   <schmancy-icon slot="leading">person</schmancy-icon>
+ *   Profile
+ *   <schmancy-icon slot="trailing">chevron_right</schmancy-icon>
+ * </schmancy-list-item>
+ * @platform li click - Styled `<li>` or `<a>` depending on `href`. Degrades to a plain list item if the tag never registers.
  * @slot leading - leading content
  * @slot trailing - trailing content
  * @slot - default content

package/src/list/list.ts

@@ -7,19 +7,18 @@ import { customElement, property } from 'lit/decorators.js'
 import { SchmancyListTypeContext } from './context'
 
 /**
- * `<schmancy-list>` component.
- *
- * A list component that wraps its content within a customizable surface.
- * It allows you to set the surface type and fill style, and can optionally
- * enable scrolling behavior by delegating the scroller attribute to the surface.
+ * Wrapped list container — holds schmancy-list-item children on a themed surface. Optionally scrollable.
  *
  * @element schmancy-list
- * @slot - The default slot for list items.
- *
+ * @summary Use for vertical lists of similarly-shaped items: settings entries, menu items, contact lists, notification lists. Pair with schmancy-list-item children.
  * @example
  * <schmancy-list surface="container" scroller>
- *   <schmancy-list-item>List Item 1</schmancy-list-item>
+ *   <schmancy-list-item>First</schmancy-list-item>
+ *   <schmancy-list-item>Second</schmancy-list-item>
+ *   <schmancy-list-item>Third</schmancy-list-item>
  * </schmancy-list>
+ * @platform ul - Styled list container. Degrades to a plain ul/div if the tag never registers.
+ * @slot - The default slot for list items.
  */
 @customElement('schmancy-list')
 export class List extends TailwindElement(css`

package/src/menu/menu-item.ts

@@ -3,6 +3,19 @@ import { css, html } from 'lit'
 import { customElement } from 'lit/decorators.js'
 import { $dialog } from '../dialog/dialog-service'
 
+/**
+ * Single item inside a schmancy-menu. Auto-dismisses the menu dialog on click — attach your action handler to `@click` and it just works.
+ *
+ * @element schmancy-menu-item
+ * @summary Always nested inside schmancy-menu. The click handler runs before the dialog closes, so `@click=${() => doThing()}` is the full pattern.
+ * @example
+ * <schmancy-menu-item @click=${() => archive()}>
+ *   <schmancy-icon slot="leading">archive</schmancy-icon>
+ *   Archive
+ * </schmancy-menu-item>
+ * @platform menuitem click - Wraps schmancy-list-item with auto-dismiss. Degrades to a styled `<button role="menuitem">` if the tag never registers.
+ * @slot - The item label and optional icons.
+ */
 @customElement('schmancy-menu-item')
 export default class SchmancyMenuItem extends $LitElement(css`
 	:host {

package/src/menu/menu.ts

@@ -4,31 +4,19 @@ import { customElement, query } from 'lit/decorators.js'
 import { $dialog } from '../dialog/dialog-service'
 
 /**
- * Menu Component
+ * Floating menu — a trigger button + a list of schmancy-menu-item children that open as a positioned dialog on click.
  *
- * CRITICAL: The dialog ONLY renders the raw menu items passed via the default slot.
- * NO <ul> wrapper, NO classes, NO additional markup in the dialog call.
- * The dialog service handles positioning and display - we just pass the pure content.
- *
- * @example Basic menu with auto-dismiss
- * ```typescript
+ * @element schmancy-menu
+ * @summary Use for dropdown menus attached to a button or icon — "More actions", "Account", row overflow menus in tables. Clicking a schmancy-menu-item inside auto-dismisses; custom components slotted inside must call `$dialog.dismiss()` themselves.
+ * @example
  * <schmancy-menu>
- *   <schmancy-button slot="trigger">Actions</schmancy-button>
- *   <schmancy-menu-item @click=${() => editItem()}>Edit</schmancy-menu-item>
- *   <schmancy-menu-item @click=${() => deleteItem()}>Delete</schmancy-menu-item>
+ *   <schmancy-icon-button slot="trigger" aria-label="Actions">
+ *     <schmancy-icon>more_vert</schmancy-icon>
+ *   </schmancy-icon-button>
+ *   <schmancy-menu-item @click=${() => edit()}>Edit</schmancy-menu-item>
+ *   <schmancy-menu-item @click=${() => remove()}>Delete</schmancy-menu-item>
  * </schmancy-menu>
- * ```
- * Note: Dialog auto-dismisses when schmancy-menu-item is clicked
- *
- * @example Custom component (manual dismiss)
- * ```typescript
- * <schmancy-menu>
- *   <schmancy-icon-button slot="trigger">settings</schmancy-icon-button>
- *   <my-settings-form @submit=${() => $dialog.dismiss()}></my-settings-form>
- * </schmancy-menu>
- * ```
- * Note: Custom components must call $dialog.dismiss() manually
- *
+ * @platform menu close - Trigger + floating listbox dialog. Degrades to a native `<select>` or inline list if the tag never registers.
  * @slot trigger - Button to open menu (new naming)
  * @slot button - Button to open menu (backward compatible)
  * @slot default - Menu items or any custom component to display in dialog

package/src/nav-drawer/appbar.ts

@@ -3,7 +3,18 @@ import { css, html } from 'lit'
 import { customElement } from 'lit/decorators.js'
 
 /**
+ * Top app bar region inside schmancy-nav-drawer — the horizontal strip above the content area that typically holds the page title, hamburger trigger, and contextual actions.
+ *
  * @element schmancy-nav-drawer-appbar
+ * @summary Always nested inside schmancy-nav-drawer. Holds the page-level title + top-right actions. On mobile, the drawer's hamburger button renders inside this region.
+ * @example
+ * <schmancy-nav-drawer-appbar>
+ *   <schmancy-typography type="title" token="lg">Dashboard</schmancy-typography>
+ *   <schmancy-icon-button slot="trailing" aria-label="Notifications">
+ *     <schmancy-icon>notifications</schmancy-icon>
+ *   </schmancy-icon-button>
+ * </schmancy-nav-drawer-appbar>
+ * @platform header - Styled horizontal bar. Degrades to a plain header element if the tag never registers.
  * @slot - The default slot
  */
 @customElement('schmancy-nav-drawer-appbar')

package/src/nav-drawer/content.ts

@@ -3,6 +3,17 @@ import { css, html } from 'lit'
 import { customElement } from 'lit/decorators.js'
 import { fromEvent, takeUntil } from 'rxjs'
 
+/**
+ * Main content region inside schmancy-nav-drawer — typically hosts the router outlet or the page's body content.
+ *
+ * @element schmancy-nav-drawer-content
+ * @summary Always nested inside schmancy-nav-drawer. Scrollable by default; propagates scroll events up so the drawer can collapse app-bar on scroll.
+ * @example
+ * <schmancy-nav-drawer-content>
+ *   <schmancy-area name="main"></schmancy-area>
+ * </schmancy-nav-drawer-content>
+ * @platform main scroll - Scrollable `<main>`. Degrades to a plain scrollable div if the tag never registers.
+ */
 @customElement('schmancy-nav-drawer-content')
 export class SchmancyNavigationDrawerContent extends $LitElement(css`
 	:host {

package/src/nav-drawer/drawer.ts

@@ -12,8 +12,23 @@ import {
 } from './context'
 
 /**
+ * Responsive navigation drawer — a left sidebar that becomes a hamburger-triggered modal overlay on narrow viewports. Composes schmancy-nav-drawer-navbar (the nav rail), schmancy-nav-drawer-appbar (the top bar), and schmancy-nav-drawer-content (the main region).
+ *
  * @element schmancy-nav-drawer
+ * @summary The app-shell layout primitive. Wrap your whole app in this when you want "persistent sidebar on desktop, drawer on mobile" behavior. Mode auto-switches at the breakpoint.
+ * @example
+ * <schmancy-nav-drawer>
+ *   <schmancy-nav-drawer-navbar>
+ *     <!-- nav items, typically schmancy-list-item links -->
+ *   </schmancy-nav-drawer-navbar>
+ *   <schmancy-nav-drawer-appbar>App title</schmancy-nav-drawer-appbar>
+ *   <schmancy-nav-drawer-content>
+ *     <!-- router outlet / page content -->
+ *   </schmancy-nav-drawer-content>
+ * </schmancy-nav-drawer>
+ * @platform div - Flex layout with viewport-width mode switching. Degrades to a stack of plain divs if the tag never registers.
  * @slot - The content slot
+ * @fires schmancy-drawer-state - When the drawer open/close state changes on mobile.
  */
 @customElement('schmancy-nav-drawer')
 export class SchmancyNavigationDrawer extends $LitElement(css`

package/src/nav-drawer/navbar.ts

@@ -16,6 +16,20 @@ const OVERLAY_ANIM_DURATION_OPEN = 200
 const OVERLAY_ANIM_DURATION_CLOSE = 150
 const NAV_ANIM_DURATION = 200
 
+/**
+ * Sidebar region inside schmancy-nav-drawer — the persistent-on-desktop / modal-on-mobile nav rail.
+ *
+ * @element schmancy-nav-drawer-navbar
+ * @summary Always nested inside schmancy-nav-drawer. On desktop: pinned left sidebar. On mobile: modal overlay triggered by the hamburger button in schmancy-nav-drawer-appbar.
+ * @example
+ * <schmancy-nav-drawer-navbar>
+ *   <schmancy-list>
+ *     <schmancy-list-item href="/dashboard">Dashboard</schmancy-list-item>
+ *     <schmancy-list-item href="/settings">Settings</schmancy-list-item>
+ *   </schmancy-list>
+ * </schmancy-nav-drawer-navbar>
+ * @platform nav - Sidebar `<nav>` with responsive open/close behavior. Degrades to a plain sidebar div if the tag never registers.
+ */
 @customElement('schmancy-nav-drawer-navbar')
 export class SchmancyNavigationDrawerSidebar extends $LitElement() {
 	// Consume context values. Renamed from "state" to "drawerState" to avoid confusion.

package/src/navigation-bar/navigation-bar-item.ts

@@ -7,12 +7,11 @@ import { BehaviorSubject, fromEvent, merge, timer } from 'rxjs'
 import { takeUntil, tap, filter } from 'rxjs/operators'
 
 /**
- * `<schmancy-navigation-bar-item>` component
- *
- * Individual navigation item for use within a navigation bar.
- * Represents a single destination with an icon and optional label following Material Design 3 specifications.
+ * Single destination inside schmancy-navigation-bar — an icon + optional label representing one primary app destination.
  *
  * @element schmancy-navigation-bar-item
+ * @summary Always nested inside schmancy-navigation-bar. Use `icon` attr for a Material Symbols glyph or slot=icon for custom content.
+ * @platform button click - Styled navigation target. Degrades to a plain `<button>` if the tag never registers.
  * @slot icon - Slot for custom icon content
  * @slot - Default slot for custom content
  *

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

@@ -15,17 +15,11 @@ const NAV_BAR_HEIGHT = 80
 const MOBILE_BREAKPOINT = '(max-width: 767px)'
 
 /**
- * `<schmancy-navigation-bar>` component
- *
- * A horizontal navigation component following Material Design 3 specifications.
- * Navigation bars provide access to between 3-7 primary destinations.
- * Automatically hides in fullscreen mode when triggered via schmancyTheme.next({ fullscreen: true }).
- *
- * **IMPORTANT**: This component includes `z-10` by default (consistent with navigation-rail).
- * The consumer is responsible for positioning the navigation bar in their layout.
- * For typical bottom-fixed positioning, add: `class="fixed bottom-0 left-0 right-0"`.
+ * Bottom navigation bar — Material Design 3 horizontal nav for mobile primary destinations (3–7 items). Auto-hides in fullscreen mode.
  *
  * @element schmancy-navigation-bar
+ * @summary Use for mobile primary navigation (home, search, favorites, settings). For persistent desktop nav, prefer schmancy-navigation-rail or schmancy-nav-drawer. Consumer is responsible for fixed-bottom positioning via class.
+ * @platform nav - Styled horizontal nav with schmancy-navigation-bar-item children. Degrades to a plain flex container if the tag never registers.
  * @slot - Default slot for navigation bar items
  *
  * @fires navigation-change - When an item is selected