@excom/content-tabs 0.1.0

package/support/custom-elements.json

@@ -0,0 +1,376 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "content-tabs.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ContentTabs",
+          "customElement": true,
+          "tagName": "content-tabs",
+          "summary": "Tabs / accordion — single, multi, or toggle selection.",
+          "description": "Open state of a `<content-tabs>` group. A tab is its header's `tab-name`, or its index among the group's own headers when unnamed. Nested groups are excluded.",
+          "attributes": [
+            {
+              "name": "tab-type",
+              "type": {
+                "text": "string"
+              },
+              "description": "Selection mode. `single` opens one header at a time (radio-like); `multi` allows any number open at once (accordion); `toggle` is like `single`, but re-clicking the open header closes it.",
+              "fieldName": "tabType",
+              "default": "single",
+              "values": [
+                "single",
+                "multi",
+                "toggle"
+              ]
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "tabType",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Selection mode. `single` opens one header at a time (radio-like); `multi` allows any number open at once (accordion); `toggle` is like `single`, but re-clicking the open header closes it.",
+              "default": "single",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "provision",
+              "type": {
+                "text": "ContentTabsProvision",
+                "expanded": "{ tabType: string | null; openTabs: Array<string | number>; activeTab: string | number | null; }"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Open state: `{ tabType, openTabs, activeTab }`. A tab is its header's `tab-name`, or its index among this group's own headers when unnamed; `activeTab` is the first open one (`null` when none). Set after mount and after every header change (batched with the body sync). Not reflected as an attribute.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "_neutron": {
+            "provisions": [
+              {
+                "name": "provision",
+                "type": {
+                  "text": "ContentTabsProvision",
+                  "expanded": "{ tabType: string | null; openTabs: Array<string | number>; activeTab: string | number | null; }"
+                },
+                "description": "Open state: `{ tabType, openTabs, activeTab }`. A tab is its header's `tab-name`, or its index among this group's own headers when unnamed; `activeTab` is the first open one (`null` when none). Set after mount and after every header change (batched with the body sync). Not reflected as an attribute.",
+                "fieldName": "provision"
+              }
+            ],
+            "listens": [
+              {
+                "name": "content-tabs-header-opened",
+                "description": "Closes sibling headers when `tab-type` is `single` (default) or `toggle`.",
+                "type": {
+                  "text": "ContentTabsHeaderOpenedEvent",
+                  "expanded": "CustomEvent & { type: \"content-tabs-header-opened\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+                }
+              }
+            ],
+            "expectedChildren": [
+              {
+                "relationship": "child",
+                "selector": "content-tabs-header",
+                "required": true,
+                "description": "Clickable tab headers."
+              },
+              {
+                "relationship": "child",
+                "selector": "content-tabs-body",
+                "required": true,
+                "description": "Panels shown / hidden to match their header."
+              }
+            ],
+            "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-tabs",
+                "selectors": [
+                  "content-tabs",
+                  ".tag-content-tabs"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--content-tab--is-open",
+                "selectors": [
+                  "[is-open]",
+                  "[aria-selected=\"true\"]"
+                ],
+                "kind": "state"
+              }
+            ]
+          },
+          "cssProperties": [
+            {
+              "name": "--content-tabs-border-color",
+              "description": "Border color for `.file-tabs` headers / bodies.",
+              "syntax": "<color>",
+              "default": "var(--v-muted-border-color, currentColor)"
+            },
+            {
+              "name": "--content-tabs-border-width",
+              "description": "Border width for `.file-tabs` headers / bodies.",
+              "syntax": "<length>",
+              "default": "var(--v-border-width, 2px)"
+            },
+            {
+              "name": "--content-tabs-color-active",
+              "description": "Text color for the active header in `.underline`.",
+              "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"
+            },
+            {
+              "name": "--content-tabs-body-padding",
+              "description": "Padding for each body in `.file-tabs`.",
+              "syntax": "<length>{1,4}",
+              "default": "var(--v-spacing, 15px)"
+            },
+            {
+              "name": "--content-tabs-active-indicator-height",
+              "description": "Height of the `.file-tabs` active-tab accent bar.",
+              "syntax": "<length>",
+              "default": "2px"
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ContentTabs",
+          "declaration": {
+            "name": "ContentTabs",
+            "module": "content-tabs.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "content-tabs",
+          "declaration": {
+            "name": "ContentTabs",
+            "module": "content-tabs.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "content-tabs-body.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ContentTabsBody",
+          "customElement": true,
+          "tagName": "content-tabs-body",
+          "summary": "Tab panel — visible when its paired header is open.",
+          "description": "Panel paired with a `<content-tabs-header>` — shown when that header is open. Lives inside a `<content-tabs>`.",
+          "attributes": [
+            {
+              "name": "is-open",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Visibility, kept in sync with the paired header's `is-open`. Set directly only if this body is not paired with a header.",
+              "fieldName": "isOpen"
+            },
+            {
+              "name": "tab-name",
+              "type": {
+                "text": "string"
+              },
+              "description": "Pairs this body with the `<content-tabs-header>` sharing the same `tab-name`. Unset headers / bodies pair by position instead.",
+              "fieldName": "tabName"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "isOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Visibility, kept in sync with the paired header's `is-open`. Set directly only if this body is not paired with a header.",
+              "_neutron": {
+                "surface": "hybrid"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "tabName",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Pairs this body with the `<content-tabs-header>` sharing the same `tab-name`. Unset headers / bodies pair by position instead.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "_neutron": {
+            "cssAliases": [
+              {
+                "name": ":--content-tabs-body",
+                "selectors": [
+                  "content-tabs-body",
+                  ".tag-content-tabs-body"
+                ],
+                "kind": "element"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ContentTabsBody",
+          "declaration": {
+            "name": "ContentTabsBody",
+            "module": "content-tabs-body.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "content-tabs-body",
+          "declaration": {
+            "name": "ContentTabsBody",
+            "module": "content-tabs-body.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "content-tabs-header.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ContentTabsHeader",
+          "customElement": true,
+          "tagName": "content-tabs-header",
+          "summary": "Tab header — opens its paired body on click.",
+          "description": "Clickable tab header — lives inside a `<content-tabs>`. Click opens (`single` / `toggle`) or toggles (`multi`) `is-open`, which keeps the paired `<content-tabs-body>` in sync.",
+          "attributes": [
+            {
+              "name": "tab-name",
+              "type": {
+                "text": "string"
+              },
+              "description": "Pairs this header with the `<content-tabs-body>` sharing the same `tab-name`. Unset headers / bodies pair by position instead.",
+              "fieldName": "tabName"
+            },
+            {
+              "name": "is-open",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Open state. Click sets or toggles this depending on the parent's `tab-type`; set it directly to drive the tab programmatically.",
+              "fieldName": "isOpen"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "tabName",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Pairs this header with the `<content-tabs-body>` sharing the same `tab-name`. Unset headers / bodies pair by position instead.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Open state. Click sets or toggles this depending on the parent's `tab-type`; set it directly to drive the tab programmatically.",
+              "_neutron": {
+                "surface": "hybrid"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "content-tabs-header-opened",
+              "description": "Whenever `is-open` is set. The parent `<content-tabs>` listens for this to close sibling headers.",
+              "type": {
+                "text": "ContentTabsHeaderOpenedEvent",
+                "expanded": "CustomEvent & { type: \"content-tabs-header-opened\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "cssAliases": [
+              {
+                "name": ":--content-tabs-header",
+                "selectors": [
+                  "content-tabs-header",
+                  ".tag-content-tabs-header"
+                ],
+                "kind": "element"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ContentTabsHeader",
+          "declaration": {
+            "name": "ContentTabsHeader",
+            "module": "content-tabs-header.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "content-tabs-header",
+          "declaration": {
+            "name": "ContentTabsHeader",
+            "module": "content-tabs-header.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/file-tabs.html

@@ -0,0 +1,6 @@
+<content-tabs class="file-tabs">
+  <content-tabs-header is-open>index.ts</content-tabs-header>
+  <content-tabs-header>utils.ts</content-tabs-header>
+  <content-tabs-body is-open><pre>export const value = 1;</pre></content-tabs-body>
+  <content-tabs-body><pre>export const double = (n) => n * 2;</pre></content-tabs-body>
+</content-tabs>

package/support/demos/multi.html

@@ -0,0 +1,6 @@
+<content-tabs tab-type="multi">
+  <content-tabs-header is-open role="button">Shipping</content-tabs-header>
+  <content-tabs-header role="button">Billing</content-tabs-header>
+  <content-tabs-body is-open><p>Ships in 3-5 business days.</p></content-tabs-body>
+  <content-tabs-body><p>Charged on shipment, not on order.</p></content-tabs-body>
+</content-tabs>

package/support/demos/named.html

@@ -0,0 +1,6 @@
+<content-tabs class="underline">
+  <content-tabs-body tab-name="b"><p>Body B — paired by name, not position.</p></content-tabs-body>
+  <content-tabs-body tab-name="a" is-open><p>Body A — paired by name, not position.</p></content-tabs-body>
+  <content-tabs-header tab-name="a" is-open>A</content-tabs-header>
+  <content-tabs-header tab-name="b">B</content-tabs-header>
+</content-tabs>

package/support/demos/simple.html

@@ -0,0 +1,8 @@
+<content-tabs class="underline">
+  <content-tabs-header is-open>Overview</content-tabs-header>
+  <content-tabs-header>Details</content-tabs-header>
+  <content-tabs-header>Settings</content-tabs-header>
+  <content-tabs-body is-open><p>Overview copy goes here.</p></content-tabs-body>
+  <content-tabs-body><p>Details copy goes here.</p></content-tabs-body>
+  <content-tabs-body><p>Settings copy goes here.</p></content-tabs-body>
+</content-tabs>

package/support/dist-docs/content-tabs-body.md

@@ -0,0 +1,20 @@
+# `<content-tabs-body>`
+
+> Tab panel — visible when its paired header is open.
+
+**Tag:** `<content-tabs-body>`
+
+## API
+
+### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `is-open` | hybrid | `boolean` |  |  | Visibility, kept in sync with the paired header's `is-open`. Set directly only if this body is not paired with a header. |
+| `tab-name` | option | `string` |  |  | Pairs this body with the `<content-tabs-header>` sharing the same `tab-name`. Unset headers / bodies pair by position instead. |
+
+### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--content-tabs-body` | element | `content-tabs-body`, `.tag-content-tabs-body` |  |

package/support/dist-docs/content-tabs-header.md

@@ -0,0 +1,26 @@
+# `<content-tabs-header>`
+
+> Tab header — opens its paired body on click.
+
+**Tag:** `<content-tabs-header>`
+
+## API
+
+### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `tab-name` | option | `string` |  |  | Pairs this header with the `<content-tabs-body>` sharing the same `tab-name`. Unset headers / bodies pair by position instead. |
+| `is-open` | hybrid | `boolean` |  |  | Open state. Click sets or toggles this depending on the parent's `tab-type`; set it directly to drive the tab programmatically. |
+
+### Fires
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `content-tabs-header-opened` | `ContentTabsHeaderOpenedEvent` (`CustomEvent & { type: "content-tabs-header-opened"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Whenever `is-open` is set. The parent `<content-tabs>` listens for this to close sibling headers. |
+
+### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--content-tabs-header` | element | `content-tabs-header`, `.tag-content-tabs-header` |  |

package/support/dist-docs/content-tabs.md

@@ -0,0 +1,183 @@
+# content-tabs
+
+Tabs and accordions — single, multi, or toggle selection, paired by name
+or position.
+
+
+```html
+<content-tabs class="underline">
+  <content-tabs-header is-open>Overview</content-tabs-header>
+  <content-tabs-header>Details</content-tabs-header>
+  <content-tabs-header>Settings</content-tabs-header>
+  <content-tabs-body is-open><p>Overview copy goes here.</p></content-tabs-body>
+  <content-tabs-body><p>Details copy goes here.</p></content-tabs-body>
+  <content-tabs-body><p>Settings copy goes here.</p></content-tabs-body>
+</content-tabs>
+```
+
+
+## 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
+
+
+`@excom/content-tabs` v0.1.0
+
+```bash
+pnpm add @excom/content-tabs
+```
+
+```bash
+npm install @excom/content-tabs
+```
+
+```bash
+yarn add @excom/content-tabs
+```
+
+### Import
+
+```ts
+import "@excom/content-tabs";
+```
+
+
+
+## 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
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `tab-type` | option | `string` | `"single"` | `"single"` \| `"multi"` \| `"toggle"` | Selection mode. `single` opens one header at a time (radio-like); `multi` allows any number open at once (accordion); `toggle` is like `single`, but re-clicking the open header closes it. |
+
+#### Provision
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provision` | `ContentTabsProvision` (`{ tabType: string \| null; openTabs: Array<string \| number>; activeTab: string \| number \| null; }`) | Open state: `{ tabType, openTabs, activeTab }`. A tab is its header's `tab-name`, or its index among this group's own headers when unnamed; `activeTab` is the first open one (`null` when none). Set after mount and after every header change (batched with the body sync). Not reflected as an attribute. |
+
+#### Recognized Elements
+
+| Relationship | Selector | Required | Description |
+| --- | --- | --- | --- |
+| `content-tabs-header` | child | yes | Clickable tab headers. |
+| `content-tabs-body` | child | yes | Panels shown / hidden to match their header. |
+
+#### Listens for
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `content-tabs-header-opened` | `ContentTabsHeaderOpenedEvent` (`CustomEvent & { type: "content-tabs-header-opened"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Closes sibling headers when `tab-type` is `single` (default) or `toggle`. |
+
+#### CSS Custom Properties
+
+| Name | Syntax | Default | Description |
+| --- | --- | --- | --- |
+| `--content-tabs-border-color` | `<color>` | `var(--v-muted-border-color, currentColor)` | Border color for `.file-tabs` headers / bodies. |
+| `--content-tabs-border-width` | `<length>` | `var(--v-border-width, 2px)` | Border width for `.file-tabs` headers / bodies. |
+| `--content-tabs-color-active` | `<color>` | `var(--v-color-primary, inherit)` | Text color for the active header in `.underline`. |
+| `--content-tabs-header-padding` | `<length>{1,4}` | `10px 15px` | Padding for each header. |
+| `--content-tabs-body-padding` | `<length>{1,4}` | `var(--v-spacing, 15px)` | Padding for each body in `.file-tabs`. |
+| `--content-tabs-active-indicator-height` | `<length>` | `2px` | Height of the `.file-tabs` active-tab accent bar. |
+
+#### CSS Classes
+
+| Name | Description |
+| --- | --- |
+| `.file-tabs` | File-explorer look — headers render as bordered folder tabs joined to the active body. |
+| `.underline` | Paper / underline look — the active header gets a bottom accent border instead of a bordered card. |
+
+#### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--content-tabs` | element | `content-tabs`, `.tag-content-tabs` |  |
+| `:--content-tab--is-open` | state | `[is-open]`, `[aria-selected="true"]` |  |
+
+
+
+### Examples
+
+#### File tabs
+
+`.file-tabs` renders each header like a folder tab, joined to its body.
+
+
+```html
+<content-tabs class="file-tabs">
+  <content-tabs-header is-open>index.ts</content-tabs-header>
+  <content-tabs-header>utils.ts</content-tabs-header>
+  <content-tabs-body is-open><pre>export const value = 1;</pre></content-tabs-body>
+  <content-tabs-body><pre>export const double = (n) => n * 2;</pre></content-tabs-body>
+</content-tabs>
+```
+
+
+#### 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.
+
+
+```html
+<content-tabs tab-type="multi">
+  <content-tabs-header is-open role="button">Shipping</content-tabs-header>
+  <content-tabs-header role="button">Billing</content-tabs-header>
+  <content-tabs-body is-open><p>Ships in 3-5 business days.</p></content-tabs-body>
+  <content-tabs-body><p>Charged on shipment, not on order.</p></content-tabs-body>
+</content-tabs>
+```
+
+
+#### Pair by tab-name
+
+Give a header and body matching `tab-name` values to pair them regardless of their order in the DOM.
+
+
+```html
+<content-tabs class="underline">
+  <content-tabs-body tab-name="b"><p>Body B — paired by name, not position.</p></content-tabs-body>
+  <content-tabs-body tab-name="a" is-open><p>Body A — paired by name, not position.</p></content-tabs-body>
+  <content-tabs-header tab-name="a" is-open>A</content-tabs-header>
+  <content-tabs-header tab-name="b">B</content-tabs-header>
+</content-tabs>
+```