npm - coles-solid-library - Versions diffs - 0.3.5 → 0.3.7 - Mend

coles-solid-library 0.3.5 → 0.3.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/USAGE.html +784 -0
package/dist/components/Form/formGroup.d.ts +9 -1
package/dist/components/Form/formHelp/models.d.ts +8 -11
package/dist/components/Form/formHelp/validators.d.ts +4 -0
package/dist/components/Form/useFormFieldBinding.d.ts +14 -0
package/dist/index.esm.js +186 -65
package/package.json +3 -2

package/USAGE.html ADDED Viewed

@@ -0,0 +1,784 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Cole's Solid Library – Usage Guide</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <style>
+    :root {
+      font-family: system-ui,-apple-system,'Segoe UI',Roboto,Ubuntu,sans-serif;
+      --bg: #121212;
+      --fg: #f5f5f5;
+      --accent: #9e6fd8;
+      --border: #2d2d2d;
+      --code-bg: #1e1e1e;
+      --code-border: #333;
+      --radius: 8px;
+      --green: #4CAF50;
+    }
+  html { scroll-behavior:smooth; }
+  body { margin:0; background:var(--bg); color:var(--fg); line-height:1.55; }
+    a { color: var(--accent); }
+    h1,h2,h3 { line-height:1.2; font-weight:600; }
+    h1 { margin-top:0; font-size:clamp(1.9rem,4vw,2.6rem); }
+    h2 { margin-top:3rem; border-top:1px solid var(--border); padding-top:2rem; }
+    h3 { margin-top:2rem; }
+    p,ul,ol,pre,blockquote { max-width: 900px; }
+    pre { background:var(--code-bg); padding:1rem; border:1px solid var(--code-border); overflow:auto; border-radius:var(--radius); }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace; font-size:.9rem; }
+    /* Layout */
+    .layout { display:flex; min-height:100vh; }
+    .sidebar { width:260px; flex-shrink:0; border-right:1px solid var(--border); padding:1rem 1.1rem 3rem; position:sticky; top:0; align-self:flex-start; max-height:100vh; overflow:auto; background:#141414; }
+    .sidebar .logo { font-size:1rem; font-weight:600; margin:0 0 .75rem; letter-spacing:.5px; }
+    .sidebar nav ul { list-style:none; margin:0; padding:0; }
+    .sidebar nav li { margin:.15rem 0; }
+    .sidebar nav li.h2 { margin-top:.65rem; }
+    .sidebar nav a { display:block; text-decoration:none; font-size:.78rem; padding:.4rem .55rem; border-radius:6px; color:var(--fg); border:1px solid transparent; }
+    .sidebar nav a:hover { background:var(--code-bg); }
+    .sidebar nav a.active { background:var(--accent); color:#fff; }
+    .sidebar nav li.h3 a { padding-left:1.25rem; font-size:.72rem; opacity:.85; }
+    .nav-toggle { display:none; background:var(--code-bg); border:1px solid var(--border); color:var(--fg); padding:.45rem .7rem; font-size:.75rem; border-radius:6px; cursor:pointer; }
+    .nav-group { margin-top:1rem; }
+    main { flex:1; padding:2rem clamp(1rem,4vw,3.5rem) 4rem; min-width:0; }
+    .skip-link { position:absolute; left:-999px; top:auto; width:1px; height:1px; overflow:hidden; }
+    .skip-link:focus { left:0; top:0; width:auto; height:auto; background:var(--accent); color:#000; padding:.5rem 1rem; z-index:1000; }
+    @media (max-width: 900px) {
+      .layout { flex-direction:column; }
+      .sidebar { position:relative; width:100%; max-height:none; border-right:none; border-bottom:1px solid var(--border); padding-bottom:1rem; }
+      .nav-toggle { display:inline-block; margin:.25rem 0 .5rem; }
+      .sidebar nav.collapsed { display:none; }
+      .sidebar nav a.active { background:var(--code-bg); color:var(--accent); }
+    }
+    .badge { display:inline-block; background:var(--green); color:#000; padding:0 .5rem; border-radius:4px; font-size:.7rem; letter-spacing:.5px; font-weight:600; vertical-align:middle; }
+    table.comp { border-collapse:collapse; margin:1rem 0; }
+    table.comp th, table.comp td { border:1px solid var(--border); padding:.5rem .75rem; font-size:.85rem; text-align:left; }
+    table.comp th { background:#1b1b1b; }
+  table.api { border-collapse:collapse; margin:1rem 0 2.25rem; width:100%; max-width:950px; }
+  table.api th, table.api td { border:1px solid var(--border); padding:.45rem .6rem; font-size:.75rem; text-align:left; vertical-align:top; }
+  table.api th { background:#202020; font-size:.65rem; letter-spacing:.5px; text-transform:uppercase; }
+  .req { color:#ffb347; font-weight:600; }
+  .deprecated { text-decoration:line-through; opacity:.5; }
+    details { background:#1b1b1b; border:1px solid var(--border); border-radius:var(--radius); padding:.75rem 1rem; }
+    details + details { margin-top:.75rem; }
+    summary { cursor:pointer; font-weight:600; }
+    .grid { display:grid; gap:1.25rem; grid-template-columns:repeat(auto-fill,minmax(260px,1fr)); margin:1rem 0 2rem; }
+    .card { border:1px solid var(--border); border-radius:var(--radius); padding:1rem 1rem 1.25rem; background:#181818; }
+    .card h3 { margin-top:0; font-size:1.05rem; }
+    footer { margin-top:4rem; font-size:.75rem; opacity:.65; }
+  </style>
+</head>
+<body>
+  <a href="#intro" class="skip-link">Skip to content</a>
+  <div class="layout">
+    <aside class="sidebar">
+      <div class="logo">Cole's Solid Library</div>
+      <button class="nav-toggle" aria-expanded="false" aria-controls="sidebar-nav">☰ Navigation</button>
+      <nav id="sidebar-nav" aria-label="Documentation" class="collapsed"></nav>
+      <noscript>
+        <nav aria-label="Documentation (No Script Fallback)">
+          <ul>
+            <li><a href="#intro">Intro</a></li>
+            <li><a href="#install">Installation</a></li>
+            <li><a href="#theming">Theming</a></li>
+            <li><a href="#components">Core Components (Glance)</a></li>
+            <li><a href="#layout-containers">Layout & Containers</a></li>
+            <li><a href="#buttons">Button</a></li>
+            <li><a href="#inputs-textarea">Input & TextArea</a></li>
+            <li><a href="#select">Select</a></li>
+            <li><a href="#menu">Menu</a></li>
+            <li><a href="#tabs">TabBar</a></li>
+            <li><a href="#carousel">Carousel</a></li>
+            <li><a href="#chips">Chip / Chipbar</a></li>
+            <li><a href="#modal">Modal</a></li>
+            <li><a href="#expansion">Expansion Panel</a></li>
+            <li><a href="#snackbar-ref">Snackbar</a></li>
+            <li><a href="#icon">Icon</a></li>
+            <li><a href="#radio-checkbox">Radio & Checkbox</a></li>
+            <li><a href="#tablev2-ref">TableV2</a></li>
+            <li><a href="#styling-patterns">Styling Patterns</a></li>
+            <li><a href="#forms">Forms</a></li>
+            <li><a href="#utilities">Utilities</a></li>
+            <li><a href="#accessibility">Accessibility</a></li>
+            <li><a href="#troubleshooting">Troubleshooting</a></li>
+            <li><a href="#example-app">Example App</a></li>
+            <li><a href="#tokens">Theme Tokens</a></li>
+            <li><a href="#roadmap">Roadmap</a></li>
+          </ul>
+        </nav>
+      </noscript>
+    </aside>
+    <main>
+    <h1 id="intro">Cole's Solid Library <span class="badge">Guide</span></h1>
+    <p>This HTML file ships with the npm package (see <code>USAGE.html</code>) and gives you an offline quick-start & reference for the component APIs, theming, and advanced patterns (TableV2, forms, dropdown rows, etc.).</p>
+    <h2 id="install">1. Installation & Peer Deps</h2>
+    <p>Install the library plus required peer dependencies (<code>solid-js</code> + <code>sass</code>):</p>
+    <pre><code>npm install coles-solid-library solid-js sass
+# or
+pnpm add coles-solid-library solid-js sass
+</code></pre>
+    <p>Create a Solid project first if you don't have one:</p>
+    <pre><code>npx degit solidjs/templates/ts my-app
+cd my-app
+</code></pre>
+    <h2 id="theming">2. Theming</h2>
+    <ol>
+      <li>At the top of your global stylesheet (e.g. <code>src/index.scss</code>):
+      <pre><code>@use 'coles-solid-library/themes/themes.scss';</code></pre></li>
+      <li>Call <code>addTheme()</code> early in your app (defaults to <code>dark</code>):
+      <pre><code>import { addTheme } from 'coles-solid-library';
+addTheme('dark'); // or 'light'
+</code></pre></li>
+    </ol>
+    <p>You can re-run <code>addTheme('light')</code> reactively (inside an effect) to toggle themes. Components rely on the <code>data-theme</code> attribute set on <code>&lt;body&gt;</code>.</p>
+    <h2 id="components">3. Core Components (At a Glance)</h2>
+    <div class="grid">
+      <div class="card"><h3>Button</h3><pre><code>import { Button } from 'coles-solid-library';
+&lt;Button theme="primary" onClick={...}&gt;Go&lt;/Button&gt;</code></pre></div>
+      <div class="card"><h3>Input / TextArea</h3><pre><code>import { Input, TextArea } from 'coles-solid-library';
+&lt;Input placeholder="Email" /&gt;</code></pre></div>
+      <div class="card"><h3>Checkbox / Radio</h3><pre><code>import { Checkbox, RadioGroup, Radio } from '...';</code></pre></div>
+      <div class="card"><h3>Select</h3><pre><code>import { Select, Option } from '...';</code></pre></div>
+      <div class="card"><h3>Snackbar</h3><pre><code>import { Snackbar } from '...';</code></pre></div>
+      <div class="card"><h3>Container / Body</h3><pre><code>import { Container, Body } from '...';</code></pre></div>
+      <div class="card"><h3>Icons</h3><pre><code>import { Icon } from '...';
+&lt;Icon name="camera" /&gt;</code></pre></div>
+  <div class="card"><h3>ExpansionPanel / Modal</h3><pre><code>import { ExpansionPanel, Modal } from 'coles-solid-library';</code></pre></div>
+    </div>
+    <h2 id="reference">4. Component & Feature Reference</h2>
+    <p>This section enumerates all exports from <code>src/index.ts</code> with usage notes, common props, and patterns. Only public-facing behavior is listed; internal context / style containers are omitted unless needed for composition.</p>
+  <h3 id="layout-containers">4.1 Layout & Containers</h3>
+    <ul>
+      <li><strong>Container</strong> – Provides themed surface/background. Props: <code>theme?: 'surface' | 'primary' | 'secondary' | 'container'</code>, standard HTML div props. Use to wrap content that requires consistent padding or contrasting backdrop.</li>
+  <li><strong>Body</strong> – Content wrapper (ComponentBody) that applies internal spacing & typography defaults on a surface. Prop: <code>style?: 'primary' | 'accent' | 'tertiary'</code> (currently decorative).</li>
+    </ul>
+    <pre><code>import { Container, Body } from 'coles-solid-library';
+&lt;Container theme="surface" style={{ padding: '1rem' }}&gt;
+  &lt;Body&gt;Any content here&lt;/Body&gt;
+&lt;/Container&gt;</code></pre>
+    <table class="api"><tr><th>Component</th><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>Container</td><td>theme<span class="req">*</span></td><td><code>'primary' | 'primaryVariant' | 'secondary' | 'secondaryVariant' | 'background' | 'surface' | 'surfaceVariant' | 'container' | 'error'</code></td><td>Background / color role.</td><td>n/a</td></tr>
+      <tr><td>Container</td><td>class/style/...div</td><td>native</td><td>Forwarded attributes.</td><td>-</td></tr>
+      <tr><td>Body</td><td>class/style/...div</td><td>native</td><td>Wrapper with default spacing.</td><td>-</td></tr>
+    </table>
+  <h3 id="buttons">4.2 Buttons</h3>
+    <pre><code>&lt;Button
+  theme="primary"            // color role: primary | secondary | surface | container
+  borderTheme="primary"      // optional border color role
+  disabled
+  onClick={(e) =&gt; {}}
+&gt;Click Me&lt;/Button&gt;</code></pre>
+    <p>Styling: theme tokens map to CSS variables like <code>--primary-color</code>. Prefer using <code>theme</code> rather than custom class names for consistent theming. Pass <code>class</code>/<code>style</code> for bespoke tweaks.</p>
+    <table class="api"><tr><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>theme</td><td><code>ThemeVariables (excludes header/subheader)</code></td><td>Visual color role.</td><td><code>container</code></td></tr>
+      <tr><td>borderTheme</td><td><code>ThemeVariables | 'none'</code></td><td>Border color role mapping.</td><td><code>'none'</code></td></tr>
+      <tr><td>transparent</td><td><code>boolean</code></td><td>Removes background for subtle styling.</td><td>false</td></tr>
+      <tr><td>disabled</td><td><code>boolean</code></td><td>Native disabled state.</td><td>false</td></tr>
+      <tr><td>onClick</td><td><code>(e) =&gt; void</code></td><td>Click handler.</td><td>-</td></tr>
+      <tr><td>...button</td><td>native</td><td>Any other HTML button attributes.</td><td>-</td></tr>
+    </table>
+  <h3 id="inputs-textarea">4.3 Inputs & TextArea</h3>
+    <pre><code>const [name, setName] = createSignal("");
+const [desc, setDesc] = createSignal("");
+&lt;Input
+  value={name()}
+  placeholder="Name"
+  onChange={e =&gt; setName(e.currentTarget.value)}
+/&gt;
+&lt;TextArea
+  text={desc}
+  setText={setDesc}
+  rows={4}
+  placeholder="Description"
+/&gt;</code></pre>
+    <p><strong>Input:</strong> controlled via <code>value</code> (or form context) and <code>onChange</code>. <strong>TextArea:</strong> uses a signal pair <code>text</code>/<code>setText</code> instead of a <code>value</code> prop and auto-grows with content. Wrap in <code>FormField</code> for legend float + error sync.</p>
+  <p><small><strong>Notes:</strong> (1) <code>onChange</code> for <code>Input</code> is invoked after internal form sync (if inside a FormField) so reading form state inside the handler reflects the new value. (2) An <code>Input</code> with <code>type="checkbox"</code> is coerced to text internally for styling; prefer the dedicated <code>Checkbox</code> component for semantics. (3) Required indicator logic appends an asterisk to placeholders when the parent FormField marks the control as required.</small></p>
+    <table class="api"><tr><th>Component</th><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>Input</td><td>value</td><td><code>string</code></td><td>Controlled value (overrides form context).</td><td>-</td></tr>
+      <tr><td>Input</td><td>onChange</td><td><code>(e) =&gt; void</code></td><td>Change handler (after form sync).</td><td>-</td></tr>
+      <tr><td>Input</td><td>placeholder</td><td><code>string</code></td><td>Hint text (required indicator appended).</td><td>-</td></tr>
+      <tr><td>Input</td><td>tooltip</td><td><code>string</code></td><td>Title attribute tooltip.</td><td>-</td></tr>
+      <tr><td>Input</td><td>transparent</td><td><code>boolean</code></td><td>Alternate visual style.</td><td>false</td></tr>
+      <tr><td>Input</td><td>type</td><td><code>string</code></td><td>Input type (checkbox coerced to text internally).</td><td>text</td></tr>
+  <tr><td>TextArea</td><td>text<span class="req">*</span></td><td><code>() =&gt; string</code></td><td>Accessor signal.</td><td>n/a</td></tr>
+  <tr><td>TextArea</td><td>setText<span class="req">*</span></td><td><code>(v:string)=&gt;void</code></td><td>Setter signal.</td><td>n/a</td></tr>
+  <tr><td>TextArea</td><td>rows</td><td><code>number</code></td><td>Initial visual row hint (auto-resizes).</td><td>3</td></tr>
+  <tr><td>TextArea</td><td>minSize</td><td><code>{ height?: number; width?: number }</code></td><td>Minimum auto-size bounds.</td><td>-</td></tr>
+  <tr><td>TextArea</td><td>transparent</td><td><code>boolean</code></td><td>Alt style (no background).</td><td>false</td></tr>
+      <tr><td>Both</td><td>class/style/...input</td><td>native</td><td>Forwarded attributes & ARIA.</td><td>-</td></tr>
+    </table>
+  <h3 id="form-system">4.4 Form System</h3>
+  <p>Full documentation moved to <strong>Section 6 (Forms API)</strong> to keep everything in a single place. See that section for creation, validators, FormArray usage, async validation, binding helpers, and patterns.</p>
+  <h3 id="field-error">4.5 FieldError (ColeError) Registration</h3>
+    <p><code>&lt;FieldError errorName="required"&gt;Message&lt;/FieldError&gt;</code> (alias of <code>ColeError</code>) registers an error display element with the surrounding <code>FormField</code>. It does not render inline itself; the FormField decides which registered errors to project (e.g. hide <code>minLength</code> while <code>required</code> fails).</p>
+    <table class="api"><tr><th>Prop</th><th>Type</th><th>Description</th></tr>
+      <tr><td>errorName</td><td><code>string</code></td><td>Validator error key to register.</td></tr>
+      <tr><td>children</td><td><code>JSX.Element</code></td><td>Content shown when this error is active & selected by FormField.</td></tr>
+    </table>
+  <h3 id="select">4.6 Select Component (Single & Multi)</h3>
+    <pre><code>&lt;Select multiple placeholder="Pick" value={values()} onChange={setValues}&gt;
+  &lt;Option value="a"&gt;Alpha&lt;/Option&gt;
+  &lt;Option value="b"&gt;Beta&lt;/Option&gt;
+&lt;/Select&gt;</code></pre>
+    <p><strong>Features:</strong> positioning logic clamps inside viewport; flips above if insufficient space. Multi-select toggles items; consumer tracks selected list via <code>onChange</code> or controlled value (depending on implementation). Provided tests assert viewport constraints.</p>
+    <table class="api"><tr><th>Component</th><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>Select</td><td>multiple</td><td><code>boolean</code></td><td>Enable multi selection.</td><td>false</td></tr>
+      <tr><td>Select</td><td>value</td><td><code>T | T[]</code></td><td>Controlled selected value(s).</td><td>-</td></tr>
+      <tr><td>Select</td><td>defaultValue</td><td><code>T | T[]</code></td><td>Initial uncontrolled selection.</td><td>-</td></tr>
+      <tr><td>Select</td><td>onChange</td><td><code>(val) =&gt; void</code></td><td>Fires on selection state change (may fire on mount).</td><td>-</td></tr>
+      <tr><td>Select</td><td>onSelect</td><td><code>(val) =&gt; void</code></td><td>User interaction selection callback.</td><td>-</td></tr>
+      <tr><td>Select</td><td>placeholder</td><td><code>string</code></td><td>Trigger placeholder text.</td><td>"Select..."</td></tr>
+  <tr><td>Select</td><td>renderValue</td><td><code>(val) =&gt; JSX</code></td><td>Custom render of current value(s).</td><td>-</td></tr>
+  <tr><td>Select</td><td>dropdownClass</td><td><code>string</code></td><td>Class for dropdown portal element.</td><td>-</td></tr>
+  <tr><td>Select</td><td>transparent</td><td><code>boolean</code></td><td>Transparent trigger style.</td><td>false</td></tr>
+  <tr><td>Select</td><td>tooltip</td><td><code>string</code></td><td>Title attribute tooltip.</td><td>-</td></tr>
+  <tr><td>Select</td><td>id</td><td><code>string</code></td><td>DOM id (anchor / tests).</td><td>-</td></tr>
+  <tr><td>Option</td><td>value</td><td><code>T</code></td><td>Option value token.</td><td>n/a</td></tr>
+  <tr><td>Option</td><td>children</td><td><code>JSX</code></td><td>Displayed label (fallback <code>String(value)</code>).</td><td>-</td></tr>
+  <tr><td>Option</td><td>class</td><td><code>string</code></td><td>Custom class.</td><td>-</td></tr>
+    </table>
+  <h3 id="menu">4.7 Menu & Dropdown</h3>
+    <pre><code>const [open, setOpen] = createSignal(false);
+let anchor!: HTMLButtonElement;
+&lt;button ref={anchor} onClick={() =&gt; setOpen(o =&gt; !o)}&gt;Open Menu&lt;/button&gt;
+&lt;Menu anchorElement={() =&gt; anchor} show={[open, setOpen]} position="left"&gt;
+  &lt;MenuItem onClick={() =&gt; console.log('Action')}&gt;Action&lt;/MenuItem&gt;
+  &lt;MenuDropdown header={() =&gt; &lt;span&gt;More&lt;/span&gt;}&gt;
+    &lt;MenuItem onClick={() =&gt; console.log('Nested')}&gt;Nested 1&lt;/MenuItem&gt;
+  &lt;/MenuDropdown&gt;
+&lt;/Menu&gt;</code></pre>
+    <p>Anchor the menu to a DOM element via <code>anchorElement</code>. Visibility is controlled by the <code>show</code> pair. Use <code>MenuDropdown</code> for nested lists (internal toggle state). Items fire native <code>onClick</code>.</p>
+    <table class="api"><tr><th>Component</th><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>Menu</td><td>anchorElement</td><td><code>()=&gt;HTMLElement|undefined</code></td><td>Anchor reference.</td><td>n/a</td></tr>
+      <tr><td>Menu</td><td>show</td><td><code>[()=&gt;boolean,(b:boolean)=&gt;void]</code></td><td>Visibility signal pair.</td><td>n/a</td></tr>
+      <tr><td>Menu</td><td>position</td><td><code>'left'|'center'|'right'</code></td><td>Horizontal alignment.</td><td>'left'</td></tr>
+      <tr><td>Menu</td><td>areaExclusionRefs</td><td><code>Accessor&lt;HTMLElement|undefined&gt;[]</code></td><td>Extra elements ignored for outside clicks.</td><td>-</td></tr>
+      <tr><td>Menu</td><td>submenu</td><td><code>boolean</code></td><td><em>Internal</em> flag for nested menus (omit in user code).</td><td>false</td></tr>
+      <tr><td>MenuDropdown</td><td>header</td><td><code>() =&gt; JSX</code></td><td>Header renderer (with toggle button + icon).</td><td>-</td></tr>
+      <tr><td>MenuItem</td><td>onClick</td><td><code>(e:MouseEvent)=&gt;void</code></td><td>Selection/action handler.</td><td>-</td></tr>
+    </table>
+    <p><small>Note: Source folder for Carousel is spelled <code>Carosel</code>; public export is <code>Carousel</code>.</small></p>
+  <h3 id="tabs">4.8 TabBar</h3>
+    <pre><code>const [tab, setTab] = createSignal(0);
+&lt;TabBar
+  tabs={['Home','Settings']}
+  activeTab={tab()}
+  onTabChange={(label,i) =&gt; setTab(i)}
+  tabPosition="stretch"
+/&gt;</code></pre>
+  <p>Indicator animates to the active tab. Use <code>tabPosition</code> for distribution and <code>noRail</code> to hide the baseline. Accessibility: ensure the root element has <code>role="tablist"</code>, each tab has <code>role="tab"</code> + <code>aria-selected</code>, and panels (if any) have <code>role="tabpanel"</code> with <code>aria-labelledby</code> pointing to the tab id.</p>
+    <table class="api"><tr><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>tabs</td><td><code>string[]</code></td><td>Tab labels.</td><td>[]</td></tr>
+      <tr><td>activeTab</td><td><code>number</code></td><td>Active index.</td><td>0</td></tr>
+      <tr><td>onTabChange</td><td><code>(label:string,index:number)=&gt;void</code></td><td>Selection callback.</td><td>-</td></tr>
+      <tr><td>tabPosition</td><td><code>'start'|'center'|'end'|'stretch'</code></td><td>Alignment mode.</td><td>'stretch'</td></tr>
+      <tr><td>noRail</td><td><code>boolean</code></td><td>Hide baseline rail.</td><td>false</td></tr>
+      <tr><td>indicatorClass</td><td><code>string</code></td><td>Extra class for indicator.</td><td>-</td></tr>
+      <tr><td>colors</td><td><code>{ text?; activeText?; background?; indicator? }</code></td><td>Color overrides.</td><td>-</td></tr>
+      <tr><td>size</td><td><code>{ height?; fontSize?; indicatorHeight? }</code></td><td>Dimension overrides.</td><td>-</td></tr>
+      <tr><td>animationTiming</td><td><code>string</code></td><td>Transition timing.</td><td>CSS default</td></tr>
+    </table>
+  <h3 id="carousel">4.9 Carousel</h3>
+    <pre><code>const slides = [
+  { name: 'One', element: &lt;div&gt;First&lt;/div&gt; },
+  { name: 'Two', element: &lt;div&gt;Second&lt;/div&gt; }
+];
+&lt;Carousel elements={slides} startingIndex={0} /&gt;</code></pre>
+  <p>Supports either an <code>elements</code> array or direct children. Control externally via <code>currentIndex</code> pair if you need programmatic navigation. No built-in autoplay props (prior docs were speculative). Accessibility tips: if you add autoplay externally, provide a pause button, update an <code>aria-live="polite"</code> region on slide change, and consider <code>aria-roledescription="carousel"</code>.</p>
+    <table class="api"><tr><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>elements</td><td><code>{ name:string; element:JSX }[]</code></td><td>Slide list (alternative to children).</td><td>-</td></tr>
+      <tr><td>children</td><td><code>JSX | JSX[]</code></td><td>Slide elements.</td><td>-</td></tr>
+      <tr><td>startingIndex</td><td><code>number</code></td><td>Initial slide index.</td><td>0</td></tr>
+      <tr><td>currentIndex</td><td><code>[()=&gt;number,(n:number)=&gt;void]</code></td><td>External control pair.</td><td>-</td></tr>
+      <tr><td>notFoundName</td><td><code>string</code></td><td>Fallback token for empty state.</td><td>Elements</td></tr>
+    </table>
+  <h3 id="chips">4.10 Chip & Chipbar</h3>
+  <pre><code>&lt;Chip value="Tag" remove={() =&gt; console.log('remove')} /&gt;
+&lt;Chipbar chips={() =&gt; chips()} setChips={setChips} /&gt;</code></pre>
+  <p><strong>Chip:</strong> Displays (optional <code>key:</code> prefix + value). Use <code>remove</code> to show a removal button. <strong>Chipbar:</strong> Horizontal scroll area with optional clear button when using reactive <code>chips</code>.</p>
+    <table class="api"><tr><th>Component</th><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>Chip</td><td>value</td><td><code>string</code></td><td>Displayed value.</td><td>n/a</td></tr>
+  <tr><td>Chip</td><td>key</td><td><code>string</code></td><td>Optional visible prefix label (not a framework diffing key).</td><td>-</td></tr>
+      <tr><td>Chip</td><td>remove</td><td><code>() =&gt; any</code></td><td>Show remove button & handler.</td><td>-</td></tr>
+      <tr><td>Chip</td><td>onClick</td><td><code>(e) =&gt; any</code></td><td>Selection / action click.</td><td>-</td></tr>
+      <tr><td>Chipbar</td><td>chips</td><td><code>() =&gt; ChipType[]</code></td><td>Reactive chips (variant 1).</td><td>-</td></tr>
+      <tr><td>Chipbar</td><td>setChips</td><td><code>Setter&lt;ChipType[]&gt;</code></td><td>Mutator for chips.</td><td>-</td></tr>
+      <tr><td>Chipbar</td><td>children</td><td><code>JSX | JSX[]</code></td><td>Manual Chip nodes (variant 2).</td><td>-</td></tr>
+      <tr><td>Chipbar</td><td>clearAll</td><td><code>Setter&lt;any[]&gt;</code></td><td>Clear provided children variant.</td><td>-</td></tr>
+    </table>
+  <h3 id="modal">4.11 Modal</h3>
+  <pre><code>const modal = createSignal(false);
+&lt;Button onClick={() =&gt; modal[1](true)}&gt;Open&lt;/Button&gt;
+&lt;Modal title="Dialog" show={modal} /&gt;</code></pre>
+  <p>Export name: <code>Modal</code>. Controlled by a signal pair passed to <code>show</code>. Backdrop clicks close via global window manager logic.</p>
+    <table class="api"><tr><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>title</td><td><code>string</code></td><td>Heading text.</td><td>"Modal"</td></tr>
+      <tr><td>show</td><td><code>[Accessor&lt;boolean&gt;, Setter&lt;boolean&gt;]</code></td><td>Signal pair controlling visibility.</td><td>n/a</td></tr>
+      <tr><td>width/height</td><td><code>string</code></td><td>Explicit dimensions (responsive fallback otherwise).</td><td>-</td></tr>
+      <tr><td>translate</td><td><code>{ x?: string; y?: string }</code></td><td>Offsets for custom positioning.</td><td>-</td></tr>
+      <tr><td>styleType</td><td><code>'primary' | 'accent' | 'tertiary'</code></td><td>Theme style variant.</td><td>primary</td></tr>
+      <tr><td>children</td><td><code>JSX</code></td><td>Dialog body.</td><td>-</td></tr>
+    </table>
+  <h3 id="expansion">4.12 Expansion Panel</h3>
+  <pre><code>&lt;ExpansionPanel startOpen&gt;{[ &lt;div&gt;Header&lt;/div&gt;, &lt;div&gt;Body&lt;/div&gt; ]}&lt;/ExpansionPanel&gt;</code></pre>
+    <p>Use for accordions. Nest multiple expansions for sections. Maintain heading hierarchy externally.</p>
+    <table class="api"><tr><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>children</td><td><code>[JSX, JSX]</code></td><td>[header, body] content array.</td><td>n/a</td></tr>
+      <tr><td>startOpen</td><td><code>boolean</code></td><td>Initial expanded state.</td><td>false</td></tr>
+      <tr><td>extraLogic</td><td><code>() =&gt; void</code></td><td>Callback invoked on toggle.</td><td>-</td></tr>
+      <tr><td>arrowSize</td><td><code>{ width: string; height: string }</code></td><td>Chevron dimensions.</td><td>-</td></tr>
+    </table>
+  <h3 id="snackbar-ref">4.13 Snackbar</h3>
+  <pre><code>addSnackbar({ message: 'Saved!', severity: 'success', closeTimeout: 3000 });
+&lt;SnackbarController /&gt;</code></pre>
+  <p>Imperative queue; render controller once. Individual Snackbar component isn't part of public API.</p>
+    <table class="api"><tr><th>Export</th><th>Signature / Props</th><th>Description</th></tr>
+      <tr><td><code>addSnackbar</code></td><td><code>(snack: { message: string; severity?: 'error' | 'warning' | 'info' | 'success'; closeTimeout?: number })</code></td><td>Enqueue snackbar.</td></tr>
+      <tr><td><code>SnackbarController</code></td><td>Component</td><td>Renders active snackbars (Portal).</td></tr>
+    </table>
+  <h3 id="icon">4.14 Icon</h3>
+  <pre><code>&lt;Icon name="camera" size="large" variant="rounded" color="#fff" /&gt;</code></pre>
+  <p>Dynamically imports Material Symbols SVG. Re-colors via <code>currentColor</code>; set inline <code>color</code> or inherit from parent.</p>
+    <table class="api"><tr><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>name</td><td><code>string</code></td><td>Material symbol name.</td><td>n/a</td></tr>
+      <tr><td>size</td><td><code>number | 'small' | 'medium' | 'large'</code></td><td>Pixel size or preset.</td><td>24</td></tr>
+      <tr><td>variant</td><td><code>'outlined' | 'rounded' | 'sharp'</code></td><td>Icon style folder.</td><td>'outlined'</td></tr>
+      <tr><td>color</td><td><code>string</code></td><td>CSS color (maps to <code>fill</code> via currentColor).</td><td><code>currentColor</code></td></tr>
+      <tr><td>onClick/onPointerDown</td><td><code>fn</code></td><td>Interaction handlers.</td><td>-</td></tr>
+    </table>
+  <h3 id="radio-checkbox">4.15 Radio & Checkbox</h3>
+    <pre><code>&lt;RadioGroup value={choice()} onChange={setChoice}&gt;
+  &lt;Radio value="a" label="Option A" /&gt;
+  &lt;Radio value="b" label="Option B" /&gt;
+&lt;/RadioGroup&gt;
+&lt;Checkbox checked={flag()} onChange={e =&gt; setFlag(e.currentTarget.checked)} label="Enable" /&gt;</code></pre>
+    <p>RadioGroup enforces single selection; pass controlled <code>value</code>. For validation integrate with FormField.</p>
+    <table class="api"><tr><th>Component</th><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+  <tr><td>RadioGroup</td><td>name</td><td><code>string</code></td><td>Group name (auto-generated if omitted).</td><td>generated</td></tr>
+  <tr><td>RadioGroup</td><td>label</td><td><code>string</code></td><td>Visible group label.</td><td>-</td></tr>
+  <tr><td>RadioGroup</td><td>ariaLabel</td><td><code>string</code></td><td>Aria label if no visible label.</td><td>-</td></tr>
+  <tr><td>RadioGroup</td><td>value</td><td><code>string | number</code></td><td>Controlled selection.</td><td>-</td></tr>
+      <tr><td>RadioGroup</td><td>defaultValue</td><td><code>string | number</code></td><td>Initial uncontrolled value.</td><td>-</td></tr>
+      <tr><td>RadioGroup</td><td>onChange</td><td><code>(val) =&gt; void</code></td><td>Selection callback.</td><td>-</td></tr>
+      <tr><td>RadioGroup</td><td>disabled</td><td><code>boolean</code></td><td>Disable group.</td><td>false</td></tr>
+      <tr><td>Radio</td><td>value</td><td><code>string | number</code></td><td>Value token.</td><td>n/a</td></tr>
+      <tr><td>Radio</td><td>label</td><td><code>string | JSX</code></td><td>Visible label.</td><td>-</td></tr>
+  <tr><td>Radio</td><td>ariaLabel</td><td><code>string</code></td><td>Accessible label when visual label omitted.</td><td>-</td></tr>
+  <tr><td>Radio</td><td>checked/defaultChecked</td><td><code>boolean</code></td><td>Controlled / uncontrolled initial state (standalone).</td><td>false</td></tr>
+      <tr><td>Radio</td><td>onChange</td><td><code>(val) =&gt; void</code></td><td>Standalone change handler.</td><td>-</td></tr>
+      <tr><td>Checkbox</td><td>checked/defaultChecked</td><td><code>boolean</code></td><td>Controlled / uncontrolled state.</td><td>false</td></tr>
+      <tr><td>Checkbox</td><td>onChange</td><td><code>(checked:boolean) =&gt; void</code></td><td>Change handler.</td><td>-</td></tr>
+  <tr><td>Checkbox</td><td>label</td><td><code>string | JSX</code></td><td>Visible label.</td><td>-</td></tr>
+  <tr><td>Checkbox</td><td>ariaLabel</td><td><code>string</code></td><td>Aria label if no visible label.</td><td>-</td></tr>
+    </table>
+  <h3 id="tablev2-ref">4.16 TableV2 (Overview)</h3>
+    <p>See dedicated section for registration model, dropdown rows, error fallbacks, dynamic columns, and styling via style containers.</p>
+    <table class="api"><tr><th>Component</th><th>Key Props</th><th>Description</th></tr>
+      <tr><td>Table</td><td><code>data, columns, getRowKey?, onCellError?, otherStyles?</code></td><td>Root orchestrator.</td></tr>
+      <tr><td>Row</td><td><code>rowNumber?, header?, footer?, isDropHeader?, isDropRow?, onClick?</code></td><td>Defines logical row & dropdown semantics.</td></tr>
+      <tr><td>Column</td><td><code>name</code></td><td>Column context for Header/Cell registration.</td></tr>
+      <tr><td>Header</td><td><code>rowNumber?</code></td><td>Header cell content.</td></tr>
+      <tr><td>Cell</td><td><code>rowNumber?, footer?, header?</code></td><td>Body/footer/header cell renderer.</td></tr>
+    </table>
+  <h3 id="styling-patterns">4.17 Styling Patterns</h3>
+    <ul>
+      <li>Prefer theming props (<code>theme</code>, <code>borderTheme</code>) over manual hex values.</li>
+      <li>Extend appearance via <code>class</code>/<code>style</code>; SCSS modules intentionally scoped.</li>
+      <li>Avoid relying on underlying generated class names—they are not part of the public API.</li>
+    </ul>
+  <h2 id="tablev2">5. TableV2 (Advanced)</h2>
+    <p>The table system uses contextual self‑registration. You declare <code>&lt;Column/&gt;</code>, <code>&lt;Header/&gt;</code>, <code>&lt;Cell/&gt;</code>, and <code>&lt;Row/&gt;</code> children; the library assembles the final DOM table. Rows & columns register by name + index.</p>
+  <h3 id="tablev2-basic">Basic Example</h3>
+    <pre><code>import { Table, Column, Header, Cell, Row, Container, addTheme } from 'coles-solid-library';
+import { createSignal } from 'solid-js';
+const [people] = createSignal([
+  { name: 'John', age: 23 },
+  { name: 'Jane', age: 24 }
+]);
+addTheme();
+&lt;Container theme="surface"&gt;
+  &lt;Table data={people} columns={['name','age']}&gt;
+    &lt;Column name="name"&gt;
+      &lt;Header&gt;Name&lt;/Header&gt;
+      &lt;Cell&gt;{p =&gt; p.name}&lt;/Cell&gt;
+    &lt;/Column&gt;
+    &lt;Column name="age"&gt;
+      &lt;Header&gt;Age&lt;/Header&gt;
+      &lt;Cell&gt;{p =&gt; p.age}&lt;/Cell&gt;
+    &lt;/Column&gt;
+    &lt;Row header /&gt;   {/* header row */}
+    &lt;Row /&gt;          {/* body row */}
+    &lt;Row footer /&gt;   {/* footer row (optional) */}
+  &lt;/Table&gt;
+&lt;/Container&gt;</code></pre>
+  <h3 id="tablev2-dropdown">Dropdown Rows</h3>
+    <p>Create paired logical rows: a toggle row (<code>&lt;Row isDropHeader rowNumber={1} /&gt;</code>) and a content row (<code>&lt;Row isDropRow rowNumber={2} /&gt;</code>). Do <strong>not</strong> add the <code>header</code> prop to the toggle row; it must be a body row so the library can attach dropdown metadata. Place exactly one <code>&lt;Cell&gt;</code> for the content row (usually in the first declared column); it will automatically span all columns when rendered open.</p>
+    <pre><code>&lt;Row isDropHeader rowNumber={1} /&gt;
+&lt;Row isDropRow rowNumber={2} /&gt;
+&lt;Column name="name"&gt;
+  &lt;Header&gt;Name&lt;/Header&gt;
+  &lt;Cell rowNumber={1}&gt;{p =&gt; p.name}&lt;/Cell&gt;
+  &lt;Cell rowNumber={2}&gt;{p =&gt; &lt;div class="details"&gt;More about {p.name}&lt;/div&gt;}&lt;/Cell&gt;
+&lt;/Column&gt;
+&lt;Column name="age"&gt;
+  &lt;Header&gt;Age&lt;/Header&gt;
+  &lt;Cell rowNumber={1}&gt;{p =&gt; p.age}&lt;/Cell&gt;
+&lt;/Column&gt;</code></pre>
+    <p>The toggle row receives <code>role="button"</code> and <code>aria-expanded</code>. Open state is tracked per data item; supply <code>getRowKey</code> if your data reorders so expansion persists.</p>
+  <h3 id="tablev2-dynamic-columns">Dynamic Columns</h3>
+    <p>When the <code>columns</code> prop changes, internal column styles reset. Ensure reactive <code>name</code> props in <code>&lt;Column name={col()} /&gt;</code> match the array entry exactly.</p>
+  <h3 id="tablev2-errors">Error Handling</h3>
+    <p>Cell renderer exceptions are caught; a fallback <code>&lt;span role="alert"&gt;Error&lt;/span&gt;</code> is rendered unless you supply <code>onCellError</code>.</p>
+    <pre><code>&lt;Table ... onCellError={(err,{column,row,dataIndex}) =&gt; &lt;em&gt;Bad cell&lt;/em&gt;} /&gt;</code></pre>
+  <h3 id="tablev2-styling">Styling Hooks</h3>
+  <p>Use <code>otherStyles</code> for section elements (<code>thead/tbody/tfoot/colGroup</code>) and <code>class/style</code> directly on <code>&lt;Table&gt;</code>. Per-column, row, and cell styles are registered through their respective components and can include arbitrary native attributes via the internal <code>all</code> bag (e.g., data attributes).</p>
+  <h3 id="tablev2-api">API Summary</h3>
+    <table class="api"><tr><th>Component</th><th>Prop</th><th>Type</th><th>Description</th><th>Default</th></tr>
+      <tr><td>Table</td><td>data</td><td><code>Accessor&lt;T[]&gt;</code></td><td>Reactive data source.</td><td>n/a</td></tr>
+      <tr><td>Table</td><td>setData</td><td><code>Setter&lt;T[]&gt;</code></td><td>Optional mutator used by internal operations.</td><td>-</td></tr>
+      <tr><td>Table</td><td>columns</td><td><code>string[]</code></td><td>Declared order & keys.</td><td>n/a</td></tr>
+      <tr><td>Table</td><td>getRowKey</td><td><code>(item:T,i:number)=&gt;string|number</code></td><td>Stable key for dropdown retention.</td><td>index</td></tr>
+      <tr><td>Table</td><td>onCellError</td><td><code>(err,ctx) =&gt; JSX | void</code></td><td>Custom cell exception fallback.</td><td>default alert span</td></tr>
+      <tr><td>Row</td><td>header/footer</td><td><code>boolean</code></td><td>Mark structural rows.</td><td>false</td></tr>
+      <tr><td>Row</td><td>isDropHeader</td><td><code>boolean</code></td><td>Toggles dropdown open state when clicked.</td><td>false</td></tr>
+      <tr><td>Row</td><td>isDropRow</td><td><code>boolean</code></td><td>Marks dropdown content row.</td><td>false</td></tr>
+      <tr><td>Row</td><td>rowNumber</td><td><code>number</code></td><td>1-based logical grouping index.</td><td>1</td></tr>
+      <tr><td>Cell</td><td>footer/header</td><td><code>boolean</code></td><td>Cell context (footer/header/body).</td><td>false</td></tr>
+      <tr><td>Cell</td><td>rowNumber</td><td><code>number</code></td><td>Assign to specific logical row.</td><td>1</td></tr>
+    </table>
+  <h2 id="forms">6. Forms API</h2>
+    <p>The form stack combines: <code>FormGroup</code> (state + validation), <code>FormArray</code> (dynamic collections), <code>Validators</code>, <code>&lt;Form&gt;</code> (context + submit), <code>&lt;FormField&gt;</code> (floating legend + error projection), <code>&lt;ColeError&gt;</code> (error registration), and hook <code>useFormFieldBinding</code> for manual field wiring.</p>
+  <h3 id="forms-full-example">Full Example</h3>
+    <pre><code>import { Form, FormGroup, FormArray, Validators, FormField, ColeError, Input, Select, Option, Button } from 'coles-solid-library';
+interface UserForm {
+  name: string;
+  email: string;
+  tags: string[];
+  pets: { name: string }[];
+  agree: boolean;
+}
+const minOnePet = Validators.custom<any>('minOne', (a: any[]) => Array.isArray(a) && a.length >= 1);
+const form = new FormGroup<UserForm>({
+  name: ['', [Validators.Required, Validators.minLength(3)]],
+  email: ['', [Validators.Email]],
+  tags: [[] as any, [Validators.custom<string[]>('minOneTag', v => v.length > 0) as any]],
+  pets: new FormArray<{ name: string }>([[], [minOnePet as any]]),
+  agree: [false as any, [Validators.custom<boolean>('mustAgree', v => v === true) as any]]
+});
+<Form data={form} onSubmit={(vals) => console.log('submit', vals)}>
+  <FormField name="Name" formName="name">
+    <ColeError errorName="required">Name required</ColeError>
+    <ColeError errorName="minLength">Min length 3</ColeError>
+    <Input />
+  </FormField>
+  <FormField name="Email" formName="email">
+    <ColeError errorName="email">Invalid email</ColeError>
+    <Input type="email" />
+  </FormField>
+  <FormField name="Tags" formName="tags">
+    <ColeError errorName="minOneTag">Pick at least one</ColeError>
+    <Select multiple placeholder="Tags">
+      <Option value="x">X</Option>
+      <Option value="y">Y</Option>
+    </Select>
+  </FormField>
+  <FormField name="Agree" formName="agree">
+    <ColeError errorName="mustAgree">You must agree</ColeError>
+    <Input type="checkbox" onChange={e => form.set('agree', (e.currentTarget as any).checked as any)} />
+  </FormField>
+  <Button type="submit" theme="primary">Save</Button>
+</Form></code></pre>
+  <h3 id="forms-errors">Error Projection & Priority</h3>
+    <p>Register each potential error with <code>&lt;ColeError errorName="key"&gt;</code>. When <code>required</code> fails, length validators (<code>minLength</code>/<code>maxLength</code>) are hidden until required passes.</p>
+  <h3 id="forms-meta">Field Meta</h3>
+    <p><code>form.getMeta(field)</code> returns <code>{ touched, dirty, initialValue }</code>. These flags update automatically when you call <code>set()</code>. Use for UX (e.g., show helper text only after touch).</p>
+  <h3 id="forms-binding">Manual Binding (Without FormField)</h3>
+  <pre><code>import { useFormFieldBinding } from 'coles-solid-library';
+const binding = useFormFieldBinding&lt;UserForm,'name'&gt;('name');
+&lt;input value={binding.value()} onInput={e =&gt; binding.setValue(e.currentTarget.value)} /&gt;
+{binding.hasError() &amp;&amp; binding.errors().map(e =&gt; e.key).join(',')}
+</code></pre>
+  <h3 id="forms-formarray">FormArray Quick Start</h3>
+    <pre><code>interface Pet { name: string }
+const pets = new FormArray<Pet>([[], [Validators.custom<any>('minOne', a => a.length >= 1) as any]]);
+const fg = new FormGroup<{ pets: Pet[] }>({ pets });
+fg.validate('pets'); // false initially
+fg.addToArray('pets', ['name', []] as any, { name: 'Fido' });
+fg.validate('pets'); // true now
+fg.removeFromArray('pets', 0);</code></pre>
+    <p><strong>Item Shape:</strong> Adding to a FormArray requires a control definition tuple: <code>['propName', validators[]]</code>. Provide an object value with those props.</p>
+  <h3 id="forms-async">Async Validators</h3>
+    <p>Create via <code>Validators.asyncCustom('key', asyncFn, hide?)</code>. <code>validate()</code> is optimistic for async; call <code>await validateAsync()</code> to finalize.</p>
+  <h3 id="forms-validation-flow">Validation Flow</h3>
+    <pre><code>const syncOk = form.validate();
+const asyncOk = syncOk && await form.validateAsync();
+if (asyncOk) doSubmit();</code></pre>
+  <h3 id="forms-patterns">Common Patterns</h3>
+    <ul>
+      <li>Blur-driven validation via <code>FormField</code>'s outside click detection.</li>
+      <li>Programmatic: <code>form.validate('field')</code> returns boolean.</li>
+      <li>Dynamic rules: <code>form.addValidator('name', Validators.maxLength(20))</code>.</li>
+      <li>Reset: <code>form.reset()</code> clears errors + meta + restores initial values.</li>
+      <li>Array item access: <code>form.getArrayItem('pets', 0)</code>.</li>
+    </ul>
+  <h3 id="forms-api-ref">API Reference</h3>
+    <table class="api"><tr><th>Entity</th><th>Key Members / Props</th><th>Description</th></tr>
+      <tr><td>FormGroup&lt;T&gt;</td><td><code>get/getR/set/reset/validate/validateAsync/addValidator/removeValidator/addToArray/removeFromArray/getErrors/hasError/hasValidator/getMeta/getArrayItem/markTouched/markDirty/setError</code></td><td>Root form state + validation engine.</td></tr>
+      <tr><td>FormArray&lt;T&gt;</td><td><code>get/getAt/getProperty/set/setAt/setProperty/add/remove/replace/validate/validateCurrent/hasError/hasValidator/getErrors/getErrorsAt</code></td><td>Dynamic object array with array + control validators.</td></tr>
+      <tr><td>Validators</td><td><code>Required/Email/minLength/maxLength/pattern/custom/asyncCustom</code></td><td>Validator factories; <code>hide</code> predicate suppresses an error.</td></tr>
+      <tr><td>&lt;Form&gt;</td><td><code>data</code>, <code>onSubmit</code></td><td>Context provider + submit orchestration (sync validate).</td></tr>
+      <tr><td>&lt;FormField&gt;</td><td><code>name</code>, <code>formName</code>, <code>required?</code>, others</td><td>Floating legend, focus, error projection region.</td></tr>
+      <tr><td>&lt;ColeError&gt;</td><td><code>errorName</code></td><td>Registers error display element for key.</td></tr>
+      <tr><td>useFormFieldBinding</td><td><code>(key)</code> =&gt; binding object</td><td>Manual binding to a control.</td></tr>
+    </table>
+  <!-- Duplicate Snackbar section removed; see 4.13 -->
+  <h2 id="utilities">8. Utilities</h2>
+    <table class="comp">
+      <tr><th>Function</th><th>Description</th></tr>
+      <tr><td><code>addTheme(theme?)</code></td><td>Set <code>data-theme</code> on <code>body</code> ('dark' default)</td></tr>
+      <tr><td><code>Clone(obj, maintainFunctions?)</code></td><td>Deep clone with cycle, Date, RegExp support</td></tr>
+      <tr><td><code>CloneStore(val)</code></td><td>Structured clone of unwrapped store</td></tr>
+      <tr><td><code>isNullish(v)</code></td><td><code>null | undefined</code> guard</td></tr>
+  <tr><td><code>isMobile()</code></td><td>User agent based mobile heuristic</td></tr>
+  <tr><td><code>useEventSignal()</code></td><td>Create signal sourced from DOM events</td></tr>
+  <tr><td><code>useClickOutside()</code></td><td>Pointer-down outside of referenced elements</td></tr>
+  <tr><td><code>getMouse()</code></td><td>Returns accessor for latest mouse coords</td></tr>
+    </table>
+    <table class="api"><tr><th>Function</th><th>Signature</th><th>Description</th><th>Notes</th></tr>
+      <tr><td>addTheme</td><td><code>(theme?: 'dark' | 'light') =&gt; void</code></td><td>Applies theme via <code>data-theme</code>.</td><td>Call early; re-call to switch.</td></tr>
+      <tr><td>Clone</td><td><code>(obj:any, maintainFunctions?:boolean) =&gt; any</code></td><td>Deep clone supporting Dates, RegExp, cycles.</td><td>Functions optionally copied by ref.</td></tr>
+      <tr><td>CloneStore</td><td><code>(val:any) =&gt; any</code></td><td>Structured clone tailored to store values.</td><td>Preserves primitives/arrays/objects.</td></tr>
+      <tr><td>isNullish</td><td><code>(v:any) =&gt; v is null | undefined</code></td><td>Null / undefined guard.</td><td>Use early returns.</td></tr>
+  <tr><td>isMobile</td><td><code>() =&gt; boolean</code></td><td>User-agent heuristic for mobile.</td><td>Not 100% reliable.</td></tr>
+  <tr><td>useEventSignal</td><td><code>(type, initial, triggerFn, ref?) =&gt; Accessor&lt;T&gt;</code></td><td>Create reactive event-driven signal.</td><td>Auto cleans listeners.</td></tr>
+  <tr><td>useClickOutside</td><td><code>(refs[], cb) =&gt; void</code></td><td>Callback on outside pointerdown.</td><td>Use multiple refs.</td></tr>
+  <tr><td>getMouse</td><td><code>() =&gt; () =&gt; { x:number; y:number }</code></td><td>Mouse position accessor factory.</td><td>Call returned fn inside effect.</td></tr>
+    </table>
+  <h2 id="accessibility">9. Accessibility Notes</h2>
+    <ul>
+      <li>Table dropdown headers use <code>role="button"</code> + <code>aria-expanded</code>.</li>
+      <li>Dropdown content cell has <code>role="region"</code> + <code>aria-hidden</code> reflecting open state.</li>
+      <li>Error cells render with <code>role="alert"</code>.</li>
+    </ul>
+  <h2 id="troubleshooting">10. Troubleshooting</h2>
+    <details open>
+      <summary>Table cells not rendering?</summary>
+      <p>Ensure the <code>Column name</code> matches the string in the <code>columns</code> array and that a corresponding <code>&lt;Row /&gt;</code> is declared.</p>
+    </details>
+    <details>
+      <summary>Theme not applying?</summary>
+      <p>Confirm you imported <code>@use 'coles-solid-library/themes/themes.scss'</code> before calling <code>addTheme()</code>.</p>
+    </details>
+    <details>
+      <summary>Dropdown rows all expand together</summary>
+      <p>Provide a stable <code>getRowKey</code> when data order can change; default key is index.</p>
+    </details>
+  <h2 id="example-app">11. Example App Snippet</h2>
+    <pre><code>import { createSignal } from 'solid-js';
+import { addTheme, Container, Table, Column, Header, Cell, Row, Button } from 'coles-solid-library';
+addTheme();
+const [data, setData] = createSignal([{ name:'John', age:23 }, { name:'Jane', age:24 }]);
+export const App = () =&gt; (
+  &lt;Container theme="surface" style={{ padding: '1rem' }}&gt;
+    &lt;Button theme="primary" onClick={() =&gt; setData(d =&gt; [...d, { name:'New', age:30 }])}&gt;Add&lt;/Button&gt;
+    &lt;Table data={data} columns={['name','age']}&gt;
+      &lt;Column name="name"&gt;
+        &lt;Header&gt;Name&lt;/Header&gt;
+        &lt;Cell&gt;{p =&gt; p.name}&lt;/Cell&gt;
+      &lt;/Column&gt;
+      &lt;Column name="age"&gt;
+        &lt;Header&gt;Age&lt;/Header&gt;
+        &lt;Cell&gt;{p =&gt; p.age}&lt;/Cell&gt;
+      &lt;/Column&gt;
+      &lt;Row header /&gt;
+      &lt;Row /&gt;
+    &lt;/Table&gt;
+  &lt;/Container&gt;
+);</code></pre>
+    <h2 id="tokens">12. Theme Tokens & CSS Variables</h2>
+    <p>The SCSS theme file emits CSS variables on <code>:root</code> and <code>[data-theme]</code> contexts. Common tokens:</p>
+    <ul>
+  <li><code>--primary-color</code>, <code>--secondary-color</code>, their <code>-variant</code> counterparts.</li>
+      <li>Surface roles: <code>--surface-color</code>, <code>--surface-color-variant</code>, <code>--container-color</code>.</li>
+      <li>On colors: <code>--on-primary-color</code>, <code>--on-surface-color</code>, etc.</li>
+      <li>Typography: <code>--font-size-h1</code> .. <code>--font-size-small</code>, <code>--font-family</code>.</li>
+      <li>Spacing: <code>--spacing-1..4</code>, Radii: <code>--border-radius-* </code>.</li>
+      <li>Shadows: <code>--shadow-elevation-1..3</code>.</li>
+    </ul>
+    <pre><code>.customCard { background: var(--surface-color); color: var(--on-surface-color); }
+.primaryText { color: var(--primary-color); }
+.lowEmphasis { opacity: var(--text-emphasis-medium); }</code></pre>
+  <h2 id="roadmap">13. Future Enhancements (Roadmap Ideas)</h2>
+    <ul>
+      <li>ARIA audits & automated a11y tests.</li>
+      <li>Composable theme augmentation (user-provided palettes).</li>
+      <li>TableV2: column resizing & virtualization.</li>
+      <li>Form async validation state indicators (pending spinners).</li>
+    </ul>
+    <footer>
+      <p>MIT License. This guide is bundled for convenience. For latest updates see the project README / repository. Contributions & PRs welcome.</p>
+    </footer>
+    </main>
+  </div>
+  <script>
+  (function(){
+    const sidebarNav = document.getElementById('sidebar-nav');
+    if(!sidebarNav) return;
+    const structure = [
+      { id:'intro', label:'Intro' },
+      { id:'install', label:'Installation' },
+      { id:'theming', label:'Theming' },
+      { id:'components', label:'Core Components (Glance)' },
+      { id:'layout-containers', label:'Layout & Containers' },
+      { id:'buttons', label:'Button' },
+      { id:'inputs-textarea', label:'Input & TextArea' },
+      { id:'select', label:'Select' },
+      { id:'menu', label:'Menu' },
+      { id:'tabs', label:'TabBar' },
+      { id:'carousel', label:'Carousel' },
+      { id:'chips', label:'Chip / Chipbar' },
+      { id:'modal', label:'Modal' },
+      { id:'expansion', label:'Expansion Panel' },
+      { id:'snackbar-ref', label:'Snackbar' },
+      { id:'icon', label:'Icon' },
+      { id:'radio-checkbox', label:'Radio & Checkbox' },
+      { id:'tablev2-ref', label:'TableV2 (Overview)', children:[
+        { id:'tablev2-basic', label:'Basic' },
+        { id:'tablev2-dropdown', label:'Dropdown Rows' },
+        { id:'tablev2-dynamic-columns', label:'Dynamic Columns' },
+        { id:'tablev2-errors', label:'Error Handling' },
+        { id:'tablev2-styling', label:'Styling' },
+        { id:'tablev2-api', label:'API Summary' },
+      ]},
+      { id:'tablev2', label:'TableV2 (Advanced)' },
+      { id:'styling-patterns', label:'Styling Patterns' },
+      { id:'forms', label:'Forms', children:[
+        { id:'forms-full-example', label:'Full Example' },
+        { id:'forms-errors', label:'Errors' },
+        { id:'forms-meta', label:'Meta' },
+        { id:'forms-binding', label:'Binding' },
+        { id:'forms-formarray', label:'FormArray' },
+        { id:'forms-async', label:'Async' },
+        { id:'forms-validation-flow', label:'Validation Flow' },
+        { id:'forms-patterns', label:'Patterns' },
+        { id:'forms-api-ref', label:'API Ref' },
+      ]},
+      { id:'utilities', label:'Utilities' },
+      { id:'accessibility', label:'Accessibility' },
+      { id:'troubleshooting', label:'Troubleshooting' },
+      { id:'example-app', label:'Example App' },
+      { id:'tokens', label:'Theme Tokens' },
+      { id:'roadmap', label:'Roadmap' }
+    ];
+    const buildList = (items, level=0) => {
+      const ul = document.createElement('ul');
+      items.forEach(item => {
+        const li = document.createElement('li');
+        li.className = level === 0 ? 'h2' : 'h3';
+        const a = document.createElement('a');
+        a.href = '#' + item.id;
+        a.textContent = item.label;
+        li.appendChild(a);
+        if(item.children) li.appendChild(buildList(item.children, level+1));
+        ul.appendChild(li);
+      });
+      return ul;
+    };
+    sidebarNav.innerHTML = '';
+    sidebarNav.appendChild(buildList(structure));
+    const allIds = []; const collect = arr => arr.forEach(i => { allIds.push(i.id); if(i.children) collect(i.children); }); collect(structure);
+    const linkMap = new Map();
+    sidebarNav.querySelectorAll('a').forEach(a => linkMap.set(a.getAttribute('href').slice(1), a));
+    const activate = (id) => {
+      sidebarNav.querySelectorAll('a.active').forEach(a => { a.classList.remove('active'); a.removeAttribute('aria-current'); });
+      const link = linkMap.get(id);
+      if(link){
+        link.classList.add('active');
+        link.setAttribute('aria-current','true');
+        let parent = link.parentElement?.parentElement?.closest('li');
+        while(parent){
+          const anchor = parent.querySelector(':scope > a');
+          if(anchor) anchor.classList.add('active');
+          parent = parent.parentElement?.closest('li');
+        }
+      }
+    };
+    const observer = new IntersectionObserver(entries => {
+      const visible = entries.filter(e => e.isIntersecting).sort((a,b)=> a.boundingClientRect.top - b.boundingClientRect.top);
+      if(visible.length){ activate(visible[0].target.id); }
+    }, { rootMargin:'0px 0px -65% 0px', threshold:0.1 });
+    allIds.forEach(id => { const el = document.getElementById(id); if(el) observer.observe(el); });
+    const toggleBtn = document.querySelector('.nav-toggle');
+    if(toggleBtn){
+      toggleBtn.addEventListener('click', () => {
+        const collapsed = sidebarNav.classList.toggle('collapsed');
+        toggleBtn.setAttribute('aria-expanded', String(!collapsed));
+      });
+    }
+    const mq = window.matchMedia('(min-width: 901px)');
+    if(mq.matches) sidebarNav.classList.remove('collapsed');
+  })();
+  </script>
+</body>
+</html>