@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/docs/src/core/components/ui/table/table.md

@@ -0,0 +1,431 @@
+# Table
+
+**`sonic-table`** lays out tabular data with composable **`sonic-tr`** / **`sonic-th`** / **`sonic-td`** children. The root applies shared typography via **`size`**, scrolls horizontally when content overflows, and optionally caps height with **`maxHeight`**. Pair with **`sonic-thead`** and **`sonic-tbody`** for structure and with **`sonic-list`** to render fetched rows.
+
+## Basic example
+
+A header row plus body rows is enough for static tables; **`sonic-thead`** / **`sonic-tbody`** are optional for simple layouts.
+
+<sonic-code>
+  <template>
+    <sonic-table>
+      <sonic-tr>
+        <sonic-th>Id</sonic-th>
+        <sonic-th>Name</sonic-th>
+        <sonic-th>Email</sonic-th>
+      </sonic-tr>
+      <sonic-tr>
+        <sonic-td>1</sonic-td>
+        <sonic-td>George Bluth</sonic-td>
+        <sonic-td>george.bluth@reqres.in</sonic-td>
+      </sonic-tr>
+      <sonic-tr>
+        <sonic-td>2</sonic-td>
+        <sonic-td>Janet Weaver</sonic-td>
+        <sonic-td>janet.weaver@reqres.in</sonic-td>
+      </sonic-tr>
+      <sonic-tr>
+        <sonic-td>3</sonic-td>
+        <sonic-td>Emma Wong</sonic-td>
+        <sonic-td>emma.wong@reqres.in</sonic-td>
+      </sonic-tr>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## List and fetch
+
+Place **`sonic-list`** inside **`sonic-tbody`** so each item template renders a **`sonic-tr`**. **`sonic-list`** sets row metadata (`even` / `odd` / `last`) on **`sonic-tr`** for striping and borders.
+
+<sonic-code>
+  <template>
+    <sonic-table>
+      <sonic-thead>
+        <sonic-tr>
+          <sonic-th>Id</sonic-th>
+          <sonic-th>Name</sonic-th>
+          <sonic-th>Email</sonic-th>
+        </sonic-tr>
+      </sonic-thead>
+      <sonic-tbody>
+        <sonic-list debug fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
+          <template>
+            <sonic-tr>
+              <sonic-td data-bind ::inner-html="$id"></sonic-td>
+              <sonic-td data-bind ::inner-html="$first_name <b>$last_name</b>"></sonic-td>
+              <sonic-td data-bind ::inner-html="$email"></sonic-td>
+            </sonic-tr>
+          </template>
+        </sonic-list>
+      </sonic-tbody>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## Size
+
+Default font size is **`md`** (omit **`size`**). Sizes follow the shared scale (`2xs` … `2xl`).
+
+<sonic-code>
+  <template>
+    <div class="grid grid-cols-4 gap-3">
+      <sonic-table size="2xs" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">2xs</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="xs" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">xs</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="sm" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">sm</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="md" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">md</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">default</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="lg" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">lg</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="xl" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">xl</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="2xl" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">2xl</sonic-td></sonic-tr>
+      </sonic-table>
+    </div>
+  </template>
+</sonic-code>
+
+## Bordered
+
+Set **`bordered`** on **`sonic-table`** for an outer frame and horizontal rules between rows.
+
+<sonic-code>
+  <template>
+    <sonic-table bordered>
+      <sonic-thead>
+        <sonic-tr>
+          <sonic-th>Id</sonic-th>
+          <sonic-th>Name</sonic-th>
+          <sonic-th>Email</sonic-th>
+        </sonic-tr>
+      </sonic-thead>
+      <sonic-tbody>
+        <sonic-tr>
+          <sonic-td>1</sonic-td>
+          <sonic-td>George Bluth</sonic-td>
+          <sonic-td>george.bluth@reqres.in</sonic-td>
+        </sonic-tr>
+        <sonic-tr>
+          <sonic-td>2</sonic-td>
+          <sonic-td>Janet Weaver</sonic-td>
+          <sonic-td>janet.weaver@reqres.in</sonic-td>
+        </sonic-tr>
+        <sonic-tr>
+          <sonic-td>3</sonic-td>
+          <sonic-td>Emma Wong</sonic-td>
+          <sonic-td>emma.wong@reqres.in</sonic-td>
+        </sonic-tr>
+      </sonic-tbody>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## Max height
+
+**`maxHeight`** applies to the scroll container (for example `8rem`), so the body scrolls vertically while the table can still scroll horizontally.
+
+<sonic-code>
+  <template>
+    <sonic-table maxHeight="8rem">
+      <sonic-thead>
+        <sonic-tr>
+          <sonic-th>Id</sonic-th>
+          <sonic-th>Name</sonic-th>
+          <sonic-th>Email</sonic-th>
+        </sonic-tr>
+      </sonic-thead>
+      <sonic-tbody>
+        <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
+          <template>
+            <sonic-tr>
+              <sonic-td data-bind ::inner-html="$id"></sonic-td>
+              <sonic-td data-bind ::inner-html="$first_name <b>$last_name</b>"></sonic-td>
+              <sonic-td data-bind ::inner-html="$email"></sonic-td>
+            </sonic-tr>
+          </template>
+        </sonic-list>
+      </sonic-tbody>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## Type
+
+Set **`type`** on **`sonic-th`** / **`sonic-td`** / **`sonic-tr`** for semantic text color (`primary` · `info` · `success` · `warning` · `danger` · `neutral` · `default`).
+
+<sonic-code>
+  <template>
+    <sonic-table bordered>
+      <sonic-tr>
+        <sonic-th type="info">Attribute type set on</sonic-th>
+        <sonic-th type="info">sonic-th</sonic-th>
+      </sonic-tr>
+      <sonic-tr>
+        <sonic-td type="danger">Attribute type set on</sonic-td>
+        <sonic-td type="danger">sonic-td</sonic-td>
+      </sonic-tr>
+      <sonic-tr type="success">
+        <sonic-td>Attribute type set on</sonic-td>
+        <sonic-td>sonic-tr</sonic-td>
+      </sonic-tr>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## Colspan and rowspan
+
+Use **`colSpan`** and **`rowSpan`** on **`sonic-th`** or **`sonic-td`** (maps to `colspan` / `rowspan` on the cell).
+
+<sonic-code>
+  <template>
+    <sonic-table>
+      <sonic-tbody>
+        <sonic-tr>
+          <sonic-td colspan="2" class="bg-info text-neutral-0">colspan: 2</sonic-td>
+          <sonic-td>cell</sonic-td>
+        </sonic-tr>
+        <sonic-tr>
+          <sonic-td>cell</sonic-td>
+          <sonic-td>cell</sonic-td>
+          <sonic-td rowspan="2" class="bg-success text-neutral-0">rowspan: 2</sonic-td>
+        </sonic-tr>
+        <sonic-tr>
+          <sonic-td>cell</sonic-td>
+          <sonic-td>cell</sonic-td>
+        </sonic-tr>
+      </sonic-tbody>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## Cell alignment and width
+
+**`align`** sets horizontal alignment (`left` · `center` · `right`). **`minWidth`** / **`maxWidth`** / **`width`** set inline dimensions on the cell. **`vAlign`** is available on **`sonic-td`** only.
+
+<sonic-code>
+  <template>
+    <sonic-table bordered>
+      <sonic-thead>
+        <sonic-tr>
+          <sonic-th width="7rem">align</sonic-th>
+          <sonic-th minWidth="20rem">minWidth</sonic-th>
+          <sonic-th>maxWidth</sonic-th>
+          <sonic-th>width</sonic-th>
+        </sonic-tr>
+      </sonic-thead>
+      <sonic-tbody>
+        <sonic-tr>
+          <sonic-td align="left">Left</sonic-td>
+          <sonic-td>20rem</sonic-td>
+          <sonic-td>5rem</sonic-td>
+          <sonic-td>15rem</sonic-td>
+        </sonic-tr>
+        <sonic-tr>
+          <sonic-td align="center">center</sonic-td>
+          <sonic-td>20rem</sonic-td>
+          <sonic-td maxWidth="5rem">5rem</sonic-td>
+          <sonic-td>15rem</sonic-td>
+        </sonic-tr>
+        <sonic-tr>
+          <sonic-td align="right">right</sonic-td>
+          <sonic-td>20rem</sonic-td>
+          <sonic-td maxWidth="5rem">5rem — Lorem ipsum dolor</sonic-td>
+          <sonic-td width="60rem">15rem — Lorem ipsum dolor sit amet, consectetur adipiscing elit.</sonic-td>
+        </sonic-tr>
+      </sonic-tbody>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## Responsive layout
+
+Tables scroll horizontally by default when columns exceed the viewport. Use **`minWidth`** on wide columns to preserve readable line length.
+
+<sonic-code>
+  <template>
+    <sonic-table bordered>
+      <sonic-thead>
+        <sonic-tr>
+          <sonic-th>Id</sonic-th>
+          <sonic-th>Name</sonic-th>
+          <sonic-th>Email</sonic-th>
+          <sonic-th>Comment</sonic-th>
+        </sonic-tr>
+      </sonic-thead>
+      <sonic-tbody>
+        <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
+          <template>
+            <sonic-tr>
+              <sonic-td data-bind ::inner-html="$id"></sonic-td>
+              <sonic-td minWidth="10rem" data-bind ::inner-html="$first_name <b>$last_name</b>"></sonic-td>
+              <sonic-td data-bind ::inner-html="$email"></sonic-td>
+              <sonic-td minWidth="40rem">
+                Phasellus suscipit vulputate lacus, in tempor turpis aliquam vel. Nunc eleifend, velit id ultrices elementum, ipsum felis porttitor dui, id laoreet diam nulla sed urna.
+              </sonic-td>
+            </sonic-tr>
+          </template>
+        </sonic-list>
+      </sonic-tbody>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## Sticky header and caption
+
+**`sonic-th`** uses `position: sticky` with `top: 0` inside the table. For page-level sticky headers, set **`noCustomScroll`** on **`sonic-table`** and position **`sonic-thead`** (for example `class="sticky top-16"`). Add **`sonic-caption`** for a table title below the grid.
+
+<sonic-code>
+  <template>
+    <sonic-table bordered noCustomScroll>
+      <sonic-thead class="sticky top-16">
+        <sonic-tr>
+          <sonic-th minWidth="max(20ch,12rem)">Company</sonic-th>
+          <sonic-th type="success">Contact</sonic-th>
+          <sonic-th>Country</sonic-th>
+          <sonic-th align="center">Quantity</sonic-th>
+          <sonic-th align="right">Price</sonic-th>
+          <sonic-th></sonic-th>
+        </sonic-tr>
+      </sonic-thead>
+      <sonic-tbody>
+        <sonic-tr>
+          <sonic-td>Alfreds Futterkiste</sonic-td>
+          <sonic-td>Maria Anders</sonic-td>
+          <sonic-td>Germany</sonic-td>
+          <sonic-td align="center">2</sonic-td>
+          <sonic-td align="right">40€</sonic-td>
+          <sonic-td align="right">
+            <sonic-button shape="circle" variant="outline" size="sm">
+              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon>
+            </sonic-button>
+          </sonic-td>
+        </sonic-tr>
+        <sonic-tr>
+          <sonic-td>Centro comercial Moctezuma</sonic-td>
+          <sonic-td colspan="2" align="center" class="text-center text-neutral-400">no information yet</sonic-td>
+          <sonic-td align="center">3</sonic-td>
+          <sonic-td align="right">40€</sonic-td>
+          <sonic-td align="right">
+            <sonic-button shape="circle" variant="outline" size="sm">
+              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon>
+            </sonic-button>
+          </sonic-td>
+        </sonic-tr>
+        <sonic-tr type="warning">
+          <sonic-td>Laughing Bacchus Winecellars</sonic-td>
+          <sonic-td>Yoshi Tannamuri</sonic-td>
+          <sonic-td>Canada</sonic-td>
+          <sonic-td align="center">0</sonic-td>
+          <sonic-td align="right">40€</sonic-td>
+          <sonic-td align="right">
+            <sonic-button shape="circle" variant="outline" size="sm">
+              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon>
+            </sonic-button>
+          </sonic-td>
+        </sonic-tr>
+        <sonic-tr>
+          <sonic-td>Magazzini Alimentari Riuniti</sonic-td>
+          <sonic-td>Giovanni Rovelli</sonic-td>
+          <sonic-td type="danger">Italy</sonic-td>
+          <sonic-td align="center">20</sonic-td>
+          <sonic-td align="right">40€</sonic-td>
+          <sonic-td align="right">
+            <sonic-button shape="circle" variant="outline" size="sm">
+              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon>
+            </sonic-button>
+          </sonic-td>
+        </sonic-tr>
+      </sonic-tbody>
+      <sonic-caption>Table caption</sonic-caption>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## API reference
+
+### `sonic-table`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `size` | `2xs` · `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `inherit` (default `md`) | Scales table font size via shared size tokens |
+| `bordered` | boolean | Outer border and row dividers |
+| `noCustomScroll` | boolean | Disables custom scrollbar styling on the horizontal scroll container |
+| `rounded` | boolean | Reflected on the host; no default table styles |
+| `maxHeight` | CSS length | Max height on the scroll container; enables vertical scrolling |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Table sections and rows (`sonic-thead`, `sonic-tbody`, `sonic-tr`, …) |
+
+### `sonic-thead` · `sonic-tbody` · `sonic-tfoot`
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Row elements (`sonic-tr`) |
+
+`sonic-tbody` wraps slotted rows in a native `<tbody>` and applies zebra / hover backgrounds to **`sonic-tr`** children.
+
+### `sonic-caption`
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Caption text rendered as `table-caption` |
+
+### `sonic-tr`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `default` · `primary` · `info` · `success` · `warning` · `danger` · `neutral` | Semantic text color for the row |
+| `even` | boolean | Striping background; usually set by **`sonic-list`** metadata |
+| `odd` | boolean | Alternate striping background; usually set by **`sonic-list`** |
+| `last` | boolean | Removes bottom cell border on the last row when **`bordered`** |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Header or data cells (`sonic-th` / `sonic-td`) |
+
+### `sonic-th`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `default` · `primary` · `info` · `success` · `warning` · `danger` · `neutral` | Semantic text color |
+| `align` | `left` · `center` · `right` | Horizontal text alignment |
+| `colSpan` | number | Column span |
+| `rowSpan` | number | Row span |
+| `minWidth` | CSS length | Minimum cell width |
+| `maxWidth` | CSS length | Maximum cell width |
+| `width` | CSS length | Cell width |
+| `noBorder` | boolean | Removes the bottom border under the header cell |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Header label content |
+
+### `sonic-td`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `default` · `primary` · `info` · `success` · `warning` · `danger` · `neutral` | Semantic text color |
+| `align` | `left` · `center` · `right` | Horizontal text alignment |
+| `vAlign` | CSS `vertical-align` value | Vertical alignment |
+| `colSpan` | number | Column span |
+| `rowSpan` | number | Row span |
+| `minWidth` | CSS length | Minimum cell width |
+| `maxWidth` | CSS length | Maximum cell width |
+| `width` | CSS length | Cell width |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Cell content |

package/docs/src/core/components/ui/theme/theme.md

@@ -0,0 +1,122 @@
+# Theme
+
+**`sonic-theme`** wraps a Concorde UI: it registers **`--sc-*`** design tokens and provides the default slot for your app. With no **`theme`** attribute (or **`theme="custom"`**), only shared primitives and your overrides apply—built-in **`light`** / **`dark`** / **`auto`** palettes are opt-in. Set **`color`** and **`font`** when the host should carry base text and typography; add Tailwind **`bg-base`** and **`block`** (or **`min-h-screen`**) on the tag for a full surface fill. **Popovers**, **modals**, and **toasts** mount under the nearest connected theme (see [Pop container](#pop-container)). Import **`@supersoniks/concorde/theme`** once at the app entry. For the full public token list and brand overrides, see [Customization](#docs/_getting-started/theming.md/theming).
+
+## Basic example
+
+Wrap interactive components so tokens and overlays resolve from one root.
+
+<sonic-code>
+  <template>
+    <sonic-theme color font class="block bg-base p-6 rounded-lg">
+      <sonic-button type="primary">Save changes</sonic-button>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Theme mode
+
+**Default:** omit **`theme`** or set **`theme="custom"`**. The host loads core tokens (`--sc-rounded`, shadows, form defaults, …) and any **`--sc-*`** you set; it does **not** apply the built-in light or dark palette.
+
+Set **`theme`** to **`light`** or **`dark`** for Concorde’s preset palettes. Set **`theme="auto"`** to follow **`prefers-color-scheme`** (light palette until the OS prefers dark).
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4 md:grid-cols-2">
+      <sonic-theme theme="light" color font class="block bg-base p-4 rounded-md border border-neutral-200">
+        <p class="text-sm mb-3 opacity-80">theme="light"</p>
+        <div class="flex flex-wrap gap-2">
+          <sonic-badge type="primary">Primary</sonic-badge>
+          <sonic-badge type="success">Success</sonic-badge>
+          <sonic-badge type="danger">Danger</sonic-badge>
+        </div>
+      </sonic-theme>
+      <sonic-theme theme="dark" color font class="block bg-base p-4 rounded-md">
+        <p class="text-sm mb-3 opacity-80">theme="dark"</p>
+        <div class="flex flex-wrap gap-2">
+          <sonic-badge type="primary">Primary</sonic-badge>
+          <sonic-badge type="success">Success</sonic-badge>
+          <sonic-badge type="danger">Danger</sonic-badge>
+        </div>
+      </sonic-theme>
+    </div>
+  </template>
+</sonic-code>
+
+## Presentation
+
+**`color`** sets text from **`--sc-base-content`**. **`font`** applies **`--sc-font-family-base`**, **`--sc-font-weight-base`**, and **`--sc-font-style-base`**. For the page or shell background, use **`bg-base`** on **`sonic-theme`** (maps to **`--sc-base`** in Tailwind) with **`block`** so the host paints the surface. Components keep their own fallbacks when **`color`** / **`font`** are omitted.
+
+<sonic-code>
+  <template>
+    <sonic-theme theme="light" color font class="block bg-base p-6 min-h-[8rem] rounded-lg">
+      <p>Body copy inherits base content color and font from the theme host.</p>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Custom tokens
+
+Override **primitives** on **`sonic-theme`** (or **`:root`** / a project stylesheet). Derived radii, shadows, and control rounding are computed from tokens such as **`--sc-rounded`**—avoid copying long lists of internal variables unless you have a specific need.
+
+<sonic-code>
+  <template>
+    <sonic-theme
+      theme="custom"
+      color
+      font
+      class="block bg-base p-6 rounded-lg"
+      style="--sc-primary: #353429; --sc-rounded: 0.25rem;"
+    >
+      <sonic-button type="primary">Brand primary</sonic-button>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Pop container
+
+**`Theme.getPopContainer()`** returns the last connected **`sonic-theme`**, or **`document.body`** if none is connected. When a theme disconnects, the previous connected instance is adopted. Imperative **`Modal.create()`** and declarative **`sonic-modal`** use the same container.
+
+<sonic-code>
+  <template>
+    <sonic-theme theme="light" color font class="block bg-base p-4 rounded-lg">
+      <sonic-button onclick="document.getElementById('themePopModal').show()">
+        Open modal
+      </sonic-button>
+      <sonic-modal id="themePopModal">
+        <sonic-modal-title>Mounted on theme</sonic-modal-title>
+        <sonic-modal-content>
+          This dialog is appended under the nearest sonic-theme pop container.
+        </sonic-modal-content>
+        <sonic-modal-actions>
+          <sonic-button hideModal>Close</sonic-button>
+        </sonic-modal-actions>
+      </sonic-modal>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Embedded iframes
+
+On connect, the theme publishes resolved **`--sc-*`** values and linked font stylesheet URLs (Google Fonts / Adobe Fonts) to the **`sonic-theme`** data channel and **`postMessage`**s them to same-page iframes. Iframes can request a refresh by posting **`{ type: "GetSonicTheme" }`**.
+
+<sonic-code language="javascript">
+  <template>
+// Inside the iframe — ask the parent theme to rebroadcast tokens
+window.parent.postMessage({ type: "GetSonicTheme" }, "*");
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `theme` | omitted · `custom` (default) · `light` · `dark` · `auto` | Omitted or `custom`: core tokens and your `--sc-*` only. `light` / `dark`: fixed presets. `auto`: presets follow `prefers-color-scheme` |
+| `color` | boolean | Host text color uses `--sc-base-content` |
+| `font` | boolean | Host font uses `--sc-font-family-base` and related base weight/style tokens |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Application markup and Concorde components |
+
+Surface background: Tailwind **`bg-base`** on **`sonic-theme`** (requires Concorde Tailwind color **`base`** → **`--sc-base`**).