@excom/content-tabs 0.1.0

package/support/docs/README.md

@@ -0,0 +1,74 @@
+# content-tabs
+
+Tabs and accordions — single, multi, or toggle selection, paired by name
+or position.
+
+<include-content data-demo="simple"></include-content>
+
+## Features
+
+- **Single / multi / toggle** Radio-like tabs, an accordion, or re-click
+  to close
+- **Pair by name or position** Match headers to bodies with `tab-name`,
+  or by index when unnamed
+- **Isolated nesting** Nested `<content-tabs>` groups never cross-wire
+- **Bindable state** `.provision` is `{ tabType, openTabs, activeTab }` —
+  read the active tab from Quark with `prop("provision")`
+- **Included looks** `.underline` and `.file-tabs` styles ship built in
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Put `<content-tabs-header>` and `<content-tabs-body>` elements inside
+`<content-tabs>`. A header pairs with the body sharing its `tab-name`,
+or by position when both are unnamed.
+
+```html
+<content-tabs class="underline">
+  <content-tabs-header is-open>Overview</content-tabs-header>
+  <content-tabs-header>Details</content-tabs-header>
+  <content-tabs-body is-open><p>Overview copy.</p></content-tabs-body>
+  <content-tabs-body><p>Details copy.</p></content-tabs-body>
+</content-tabs>
+```
+
+The open state is a fact, not just an event: `.provision` holds
+`{ tabType, openTabs, activeTab }`, where a tab is its header's `tab-name`
+(or its index when unnamed) and `activeTab` is the first open one. Quark
+reads it on the group and binds it anywhere below:
+
+```quark
+content-tabs {
+  $tab: prop("provision").activeTab;
+  h2 { content: $tab; }
+}
+```
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### File tabs
+
+`.file-tabs` renders each header like a folder tab, joined to its body.
+
+<include-content data-demo="file-tabs"></include-content>
+
+#### Multi-select accordion
+
+`tab-type="multi"` lets any number of headers stay open — clicking one does not close the others. Also displayed are the tab headers as buttons, if using Valence.css.
+
+Useful for building your own UI toggle systems.
+
+<include-content data-demo="multi"></include-content>
+
+#### Pair by tab-name
+
+Give a header and body matching `tab-name` values to pair them regardless of their order in the DOM.
+
+<include-content data-demo="named"></include-content>

package/support/package-meta.json

@@ -0,0 +1,252 @@
+{
+  "shortName": "content-tabs",
+  "package": {
+    "name": "@excom/content-tabs",
+    "version": "0.1.0",
+    "description": "<content-tabs> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "file-tabs": "<content-tabs class=\"file-tabs\">\n  <content-tabs-header is-open>index.ts</content-tabs-header>\n  <content-tabs-header>utils.ts</content-tabs-header>\n  <content-tabs-body is-open><pre>export const value = 1;</pre></content-tabs-body>\n  <content-tabs-body><pre>export const double = (n) => n * 2;</pre></content-tabs-body>\n</content-tabs>\n",
+    "multi": "<content-tabs tab-type=\"multi\">\n  <content-tabs-header is-open role=\"button\">Shipping</content-tabs-header>\n  <content-tabs-header role=\"button\">Billing</content-tabs-header>\n  <content-tabs-body is-open><p>Ships in 3-5 business days.</p></content-tabs-body>\n  <content-tabs-body><p>Charged on shipment, not on order.</p></content-tabs-body>\n</content-tabs>\n",
+    "named": "<content-tabs class=\"underline\">\n  <content-tabs-body tab-name=\"b\"><p>Body B — paired by name, not position.</p></content-tabs-body>\n  <content-tabs-body tab-name=\"a\" is-open><p>Body A — paired by name, not position.</p></content-tabs-body>\n  <content-tabs-header tab-name=\"a\" is-open>A</content-tabs-header>\n  <content-tabs-header tab-name=\"b\">B</content-tabs-header>\n</content-tabs>\n",
+    "simple": "<content-tabs class=\"underline\">\n  <content-tabs-header is-open>Overview</content-tabs-header>\n  <content-tabs-header>Details</content-tabs-header>\n  <content-tabs-header>Settings</content-tabs-header>\n  <content-tabs-body is-open><p>Overview copy goes here.</p></content-tabs-body>\n  <content-tabs-body><p>Details copy goes here.</p></content-tabs-body>\n  <content-tabs-body><p>Settings copy goes here.</p></content-tabs-body>\n</content-tabs>\n"
+  },
+  "readme": "<h1 id=\"md-content-tabs\">content-tabs</h1>\n<p>Tabs and accordions — single, multi, or toggle selection, paired by name\nor position.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Single / multi / toggle</strong> Radio-like tabs, an accordion, or re-click\nto close</li>\n<li><strong>Pair by name or position</strong> Match headers to bodies with <code>tab-name</code>,\nor by index when unnamed</li>\n<li><strong>Isolated nesting</strong> Nested <code>&lt;content-tabs&gt;</code> groups never cross-wire</li>\n<li><strong>Bindable state</strong> <code>.provision</code> is <code>{ tabType, openTabs, activeTab }</code> —\nread the active tab from Quark with <code>prop(&quot;provision&quot;)</code></li>\n<li><strong>Included looks</strong> <code>.underline</code> and <code>.file-tabs</code> styles ship built in</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Put <code>&lt;content-tabs-header&gt;</code> and <code>&lt;content-tabs-body&gt;</code> elements inside\n<code>&lt;content-tabs&gt;</code>. A header pairs with the body sharing its <code>tab-name</code>,\nor by position when both are unnamed.</p>\n<include-content data-language=\"html\"><template>&lt;content-tabs class=\"underline\"&gt;\n  &lt;content-tabs-header is-open&gt;Overview&lt;/content-tabs-header&gt;\n  &lt;content-tabs-header&gt;Details&lt;/content-tabs-header&gt;\n  &lt;content-tabs-body is-open&gt;&lt;p&gt;Overview copy.&lt;/p&gt;&lt;/content-tabs-body&gt;\n  &lt;content-tabs-body&gt;&lt;p&gt;Details copy.&lt;/p&gt;&lt;/content-tabs-body&gt;\n&lt;/content-tabs&gt;</template></include-content>\n<p>The open state is a fact, not just an event: <code>.provision</code> holds\n<code>{ tabType, openTabs, activeTab }</code>, where a tab is its header&#39;s <code>tab-name</code>\n(or its index when unnamed) and <code>activeTab</code> is the first open one. Quark\nreads it on the group and binds it anywhere below:</p>\n<include-content data-language=\"quark\"><template>content-tabs {\n  $tab: prop(\"provision\").activeTab;\n  h2 { content: $tab; }\n}</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-file-tabs\">File tabs</h4>\n<p><code>.file-tabs</code> renders each header like a folder tab, joined to its body.</p>\n<p><include-content data-demo=\"file-tabs\"></include-content></p>\n<h4 id=\"md-multi-select-accordion\">Multi-select accordion</h4>\n<p><code>tab-type=&quot;multi&quot;</code> lets any number of headers stay open — clicking one does not close the others. Also displayed are the tab headers as buttons, if using Valence.css.</p>\n<p>Useful for building your own UI toggle systems.</p>\n<p><include-content data-demo=\"multi\"></include-content></p>\n<h4 id=\"md-pair-by-tab-name\">Pair by tab-name</h4>\n<p>Give a header and body matching <code>tab-name</code> values to pair them regardless of their order in the DOM.</p>\n<p><include-content data-demo=\"named\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-content-tabs\">content-tabs</h1>\n<p>Tabs and accordions — single, multi, or toggle selection, paired by name\nor position.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Single / multi / toggle</strong> Radio-like tabs, an accordion, or re-click\nto close</li>\n<li><strong>Pair by name or position</strong> Match headers to bodies with <code>tab-name</code>,\nor by index when unnamed</li>\n<li><strong>Isolated nesting</strong> Nested <code>&lt;content-tabs&gt;</code> groups never cross-wire</li>\n<li><strong>Bindable state</strong> <code>.provision</code> is <code>{ tabType, openTabs, activeTab }</code> —\nread the active tab from Quark with <code>prop(&quot;provision&quot;)</code></li>\n<li><strong>Included looks</strong> <code>.underline</code> and <code>.file-tabs</code> styles ship built in</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Put <code>&lt;content-tabs-header&gt;</code> and <code>&lt;content-tabs-body&gt;</code> elements inside\n<code>&lt;content-tabs&gt;</code>. A header pairs with the body sharing its <code>tab-name</code>,\nor by position when both are unnamed.</p>\n<include-content data-language=\"html\"><template>&lt;content-tabs class=\"underline\"&gt;\n  &lt;content-tabs-header is-open&gt;Overview&lt;/content-tabs-header&gt;\n  &lt;content-tabs-header&gt;Details&lt;/content-tabs-header&gt;\n  &lt;content-tabs-body is-open&gt;&lt;p&gt;Overview copy.&lt;/p&gt;&lt;/content-tabs-body&gt;\n  &lt;content-tabs-body&gt;&lt;p&gt;Details copy.&lt;/p&gt;&lt;/content-tabs-body&gt;\n&lt;/content-tabs&gt;</template></include-content>\n<p>The open state is a fact, not just an event: <code>.provision</code> holds\n<code>{ tabType, openTabs, activeTab }</code>, where a tab is its header&#39;s <code>tab-name</code>\n(or its index when unnamed) and <code>activeTab</code> is the first open one. Quark\nreads it on the group and binds it anywhere below:</p>\n<include-content data-language=\"quark\"><template>content-tabs {\n  $tab: prop(\"provision\").activeTab;\n  h2 { content: $tab; }\n}</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-file-tabs\">File tabs</h4>\n<p><code>.file-tabs</code> renders each header like a folder tab, joined to its body.</p>\n<p><include-content data-demo=\"file-tabs\"></include-content></p>\n<h4 id=\"md-multi-select-accordion\">Multi-select accordion</h4>\n<p><code>tab-type=&quot;multi&quot;</code> lets any number of headers stay open — clicking one does not close the others. Also displayed are the tab headers as buttons, if using Valence.css.</p>\n<p>Useful for building your own UI toggle systems.</p>\n<p><include-content data-demo=\"multi\"></include-content></p>\n<h4 id=\"md-pair-by-tab-name\">Pair by tab-name</h4>\n<p>Give a header and body matching <code>tab-name</code> values to pair them regardless of their order in the DOM.</p>\n<p><include-content data-demo=\"named\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/content-tabs",
+    "shortName": "content-tabs",
+    "version": "0.1.0",
+    "description": "<content-tabs> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/content-tabs@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/content-tabs@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/content-tabs"
+    },
+    "imports": {
+      "js": "import \"@excom/content-tabs\";",
+      "css": "@import \"@excom/content-tabs\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/content-tabs\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/content-tabs\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "content-tabs",
+      "summary": "Tabs / accordion — single, multi, or toggle selection.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "tab-type",
+          "type": "string",
+          "description": "Selection mode. <code>single</code> opens one header at a time (radio-like); <code>multi</code> allows any number open at once (accordion); <code>toggle</code> is like <code>single</code>, but re-clicking the open header closes it.",
+          "fieldName": "tabType",
+          "surface": "option",
+          "default": "\"single\"",
+          "values": "\"single\" | \"multi\" | \"toggle\""
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssProperties": [
+        {
+          "name": "--content-tabs-active-indicator-height",
+          "description": "Height of the <code>.file-tabs</code> active-tab accent bar.",
+          "syntax": "<length>",
+          "default": "2px"
+        },
+        {
+          "name": "--content-tabs-body-padding",
+          "description": "Padding for each body in <code>.file-tabs</code>.",
+          "syntax": "<length>{1,4}",
+          "default": "var(--v-spacing, 15px)"
+        },
+        {
+          "name": "--content-tabs-border-color",
+          "description": "Border color for <code>.file-tabs</code> headers / bodies.",
+          "syntax": "<color>",
+          "default": "var(--v-muted-border-color, currentColor)"
+        },
+        {
+          "name": "--content-tabs-border-width",
+          "description": "Border width for <code>.file-tabs</code> headers / bodies.",
+          "syntax": "<length>",
+          "default": "var(--v-border-width, 2px)"
+        },
+        {
+          "name": "--content-tabs-color-active",
+          "description": "Text color for the active header in <code>.underline</code>.",
+          "syntax": "<color>",
+          "default": "var(--v-color-primary, inherit)"
+        },
+        {
+          "name": "--content-tabs-header-padding",
+          "description": "Padding for each header.",
+          "syntax": "<length>{1,4}",
+          "default": "10px 15px"
+        }
+      ],
+      "cssClasses": [
+        {
+          "name": "file-tabs",
+          "description": "File-explorer look — headers render as bordered folder tabs joined to the active body."
+        },
+        {
+          "name": "underline",
+          "description": "Paper / underline look — the active header gets a bottom accent border instead of a bordered card."
+        }
+      ],
+      "cssAliases": [
+        {
+          "name": ":--content-tab--is-open",
+          "selectors": [
+            "[is-open]",
+            "[aria-selected=\"true\"]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--content-tabs",
+          "selectors": [
+            "content-tabs",
+            ".tag-content-tabs"
+          ],
+          "kind": "element",
+          "description": ""
+        }
+      ],
+      "listens": [
+        {
+          "name": "content-tabs-header-opened",
+          "description": "Closes sibling headers when <code>tab-type</code> is <code>single</code> (default) or <code>toggle</code>.",
+          "type": "ContentTabsHeaderOpenedEvent",
+          "typeExpanded": "CustomEvent & { type: \"content-tabs-header-opened\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [
+        {
+          "name": "child:content-tabs-body",
+          "relationship": "child",
+          "selector": "content-tabs-body",
+          "required": true,
+          "description": "Panels shown / hidden to match their header."
+        },
+        {
+          "name": "child:content-tabs-header",
+          "relationship": "child",
+          "selector": "content-tabs-header",
+          "required": true,
+          "description": "Clickable tab headers."
+        }
+      ],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "ContentTabsProvision",
+          "typeExpanded": "{ tabType: string | null; openTabs: Array<string | number>; activeTab: string | number | null; }",
+          "description": "Open state: <code>{ tabType, openTabs, activeTab }</code>. A tab is its header&#39;s <code>tab-name</code>, or its index among this group&#39;s own headers when unnamed; <code>activeTab</code> is the first open one (<code>null</code> when none). Set after mount and after every header change (batched with the body sync). Not reflected as an attribute.",
+          "fieldName": "provision"
+        }
+      ]
+    },
+    {
+      "tag": "content-tabs-body",
+      "summary": "Tab panel — visible when its paired header is open.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "tab-name",
+          "type": "string",
+          "description": "Pairs this body with the <code>&lt;content-tabs-header&gt;</code> sharing the same <code>tab-name</code>. Unset headers / bodies pair by position instead.",
+          "fieldName": "tabName",
+          "surface": "option"
+        },
+        {
+          "name": "is-open",
+          "type": "boolean",
+          "description": "Visibility, kept in sync with the paired header&#39;s <code>is-open</code>. Set directly only if this body is not paired with a header.",
+          "fieldName": "isOpen",
+          "surface": "hybrid"
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [
+        {
+          "name": ":--content-tabs-body",
+          "selectors": [
+            "content-tabs-body",
+            ".tag-content-tabs-body"
+          ],
+          "kind": "element",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    },
+    {
+      "tag": "content-tabs-header",
+      "summary": "Tab header — opens its paired body on click.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "tab-name",
+          "type": "string",
+          "description": "Pairs this header with the <code>&lt;content-tabs-body&gt;</code> sharing the same <code>tab-name</code>. Unset headers / bodies pair by position instead.",
+          "fieldName": "tabName",
+          "surface": "option"
+        },
+        {
+          "name": "is-open",
+          "type": "boolean",
+          "description": "Open state. Click sets or toggles this depending on the parent&#39;s <code>tab-type</code>; set it directly to drive the tab programmatically.",
+          "fieldName": "isOpen",
+          "surface": "hybrid"
+        }
+      ],
+      "events": [
+        {
+          "name": "content-tabs-header-opened",
+          "description": "Whenever <code>is-open</code> is set. The parent <code>&lt;content-tabs&gt;</code> listens for this to close sibling headers.",
+          "type": "ContentTabsHeaderOpenedEvent",
+          "typeExpanded": "CustomEvent & { type: \"content-tabs-header-opened\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [
+        {
+          "name": ":--content-tabs-header",
+          "selectors": [
+            "content-tabs-header",
+            ".tag-content-tabs-header"
+          ],
+          "kind": "element",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}