@adia-ai/web-components 0.8.6 → 0.8.7

package/patterns/layout/layout.examples.html

@@ -0,0 +1,365 @@
+<header>
+    <div>
+      <h1>Layout</h1>
+      <div data-actions>
+        <tag-ui size="sm">col-ui</tag-ui>
+        <tag-ui size="sm">row-ui</tag-ui>
+        <tag-ui size="sm">grid-ui</tag-ui>
+        <tag-ui size="sm">stack-ui</tag-ui>
+      </div>
+    </div>
+    <p>Layout primitives — flex columns, flex rows, CSS grids, and stacked overlays — each with consistent gap, alignment, and justification controls.</p>
+  </header>
+
+
+<section data-section data-property="col">
+  <h2 variant="section">col-ui</h2>
+  <p data-note>Flex column. Children stack vertically with a consistent gap.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label='gap="xs"'>
+      <col-ui data-chunk="layout-col-xs" gap="xs">
+        <block-ui>Item one</block-ui>
+        <block-ui>Item two</block-ui>
+        <block-ui>Item three</block-ui>
+      </col-ui>
+      </div>
+    <div data-artifact-item data-artifact-label='gap="sm"'>
+      <col-ui data-chunk="layout-col-1" gap="sm">
+        <block-ui>Item one</block-ui>
+        <block-ui>Item two</block-ui>
+        <block-ui>Item three</block-ui>
+      </col-ui>
+      </div>
+    <div data-artifact-item data-artifact-label='gap="md"'>
+      <col-ui data-chunk="layout-col-2" gap="md">
+        <block-ui>Item one</block-ui>
+        <block-ui>Item two</block-ui>
+        <block-ui>Item three</block-ui>
+      </col-ui>
+      </div>
+    <div data-artifact-item data-artifact-label='gap="lg"'>
+      <col-ui data-chunk="layout-col-3" gap="lg">
+        <block-ui>Item one</block-ui>
+        <block-ui>Item two</block-ui>
+        <block-ui>Item three</block-ui>
+      </col-ui>
+      </div>
+    <div data-artifact-item data-artifact-label='gap="xl"'>
+      <col-ui data-chunk="layout-col-xl" gap="xl">
+        <block-ui>Item one</block-ui>
+        <block-ui>Item two</block-ui>
+        <block-ui>Item three</block-ui>
+      </col-ui>
+      </div>
+  </div>
+</section>
+
+<section data-section data-property="row">
+  <h2 variant="section">row-ui</h2>
+  <p data-note>Flex row. Children lay out horizontally.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label='gap="sm"'>
+      <row-ui data-chunk="layout-row-1" gap="sm">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+        <block-ui>C</block-ui>
+      </row-ui>
+      </div>
+    <div data-artifact-item data-artifact-label='gap="lg"'>
+      <row-ui data-chunk="layout-row-2" gap="lg">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+        <block-ui>C</block-ui>
+      </row-ui>
+      </div>
+  </div>
+</section>
+
+<section data-section data-property="justify">
+  <h2 variant="section">justify</h2>
+  <p data-note>Main-axis distribution. One of start, center, end, space-between, space-around.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="start">
+      <row-ui data-chunk="layout-justify-start" justify="start">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+      </row-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="center">
+      <row-ui data-chunk="layout-justify-center" justify="center">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+      </row-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="end">
+      <row-ui data-chunk="layout-justify-end" justify="end">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+      </row-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="space-between">
+      <row-ui data-chunk="layout-justify-space-between" justify="space-between">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+      </row-ui>
+      </div>
+  </div>
+</section>
+
+<section data-section data-property="align">
+  <h2 variant="section">align</h2>
+  <p data-note>Cross-axis alignment. One of start, center, end, stretch, baseline (row only).</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="start">
+      <row-ui data-chunk="layout-align-start" align="start" style="height:80px;">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+      </row-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="center">
+      <row-ui data-chunk="layout-align-center" align="center" style="height:80px;">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+      </row-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="end">
+      <row-ui data-chunk="layout-align-end" align="end" style="height:80px;">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+      </row-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="stretch">
+      <row-ui data-chunk="layout-align-stretch" align="stretch" style="height:80px;">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+      </row-ui>
+      </div>
+  </div>
+</section>
+
+<section data-section data-property="wrap">
+  <h2 variant="section">wrap</h2>
+  <p data-note>Allow row children to wrap onto additional lines when they overflow.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="wrap">
+      <row-ui data-chunk="layout-wrap" wrap gap="sm" style="max-width:240px;">
+        <block-ui>One</block-ui>
+        <block-ui>Two</block-ui>
+        <block-ui>Three</block-ui>
+        <block-ui>Four</block-ui>
+        <block-ui>Five</block-ui>
+      </row-ui>
+      </div>
+  </div>
+</section>
+
+<section data-section data-property="grid">
+  <h2 variant="section">grid-ui</h2>
+  <p data-note>CSS grid with a fixed column count or responsive auto-fill / auto-fit.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label='columns="2"'>
+      <grid-ui data-chunk="layout-grid-1" columns="2" gap="sm">
+        <block-ui>1</block-ui>
+        <block-ui>2</block-ui>
+        <block-ui>3</block-ui>
+        <block-ui>4</block-ui>
+      </grid-ui>
+      </div>
+    <div data-artifact-item data-artifact-label='columns="3"'>
+      <grid-ui data-chunk="layout-grid-2" columns="3" gap="sm">
+        <block-ui>1</block-ui>
+        <block-ui>2</block-ui>
+        <block-ui>3</block-ui>
+        <block-ui>4</block-ui>
+        <block-ui>5</block-ui>
+        <block-ui>6</block-ui>
+      </grid-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="auto-fill">
+      <grid-ui data-chunk="layout-grid-auto-fill" columns="auto-fill" gap="sm">
+        <block-ui>A</block-ui>
+        <block-ui>B</block-ui>
+        <block-ui>C</block-ui>
+        <block-ui>D</block-ui>
+      </grid-ui>
+      </div>
+  </div>
+</section>
+
+<section data-section data-property="stack">
+  <h2 variant="section">stack-ui</h2>
+  <p data-note>Overlay children in the same cell. Use align to position them within the stack.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="center">
+      <stack-ui data-chunk="layout-stack-center" align="center">
+        <avatar-ui text="AB" size="lg"></avatar-ui>
+        <badge-ui text="3" size="sm" variant="danger"></badge-ui>
+      </stack-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="top-right">
+      <stack-ui data-chunk="layout-stack-top-right" align="top-right">
+        <avatar-ui text="AB" size="lg"></avatar-ui>
+        <badge-ui text="3" size="sm" variant="danger"></badge-ui>
+      </stack-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="bottom-left">
+      <stack-ui data-chunk="layout-stack-bottom-left" align="bottom-left">
+        <avatar-ui text="AB" size="lg"></avatar-ui>
+        <badge-ui text="3" size="sm" variant="danger"></badge-ui>
+      </stack-ui>
+      </div>
+  </div>
+</section>
+
+<section data-section data-property="combinations">
+  <h2 variant="section">Combinations</h2>
+  <p data-note>Nested layouts composing a typical card-style region.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="col + row + grid">
+      <col-ui data-chunk="layout-combo" gap="md" style="max-width:320px;">
+        <row-ui justify="space-between">
+          <block-ui>Title</block-ui>
+          <block-ui>Action</block-ui>
+        </row-ui>
+        <grid-ui columns="2" gap="sm">
+          <block-ui>Stat A</block-ui>
+          <block-ui>Stat B</block-ui>
+          <block-ui>Stat C</block-ui>
+          <block-ui>Stat D</block-ui>
+        </grid-ui>
+      </col-ui>
+      </div>
+  </div>
+</section>
+
+<section data-section data-property="edge-cases">
+  <h2 variant="section">Edge Cases</h2>
+  <p data-note>Boundary conditions.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="empty">
+      <col-ui data-chunk="layout-edge-empty"></col-ui>
+      </div>
+    <div data-artifact-item data-artifact-label="single child">
+      <row-ui data-chunk="layout-edge-single-child">
+        <block-ui>Only child</block-ui>
+      </row-ui>
+      </div>
+    <div data-artifact-item data-artifact-label='gap="0"'>
+      <grid-ui data-chunk="layout-edge-3" columns="1" gap="0">
+        <block-ui>No gap</block-ui>
+        <block-ui>No gap</block-ui>
+      </grid-ui>
+      </div>
+  </div>
+</section>
+
+<!-- ═══════════════════════════════════════════════════════════
+     API Reference
+     ═══════════════════════════════════════════════════════════ -->
+
+<section data-section data-property="usage">
+  <h2 variant="section">Usage</h2>
+  <code-ui language="html">&lt;col-ui gap="md"&gt;
+  &lt;row-ui justify="space-between"&gt;
+    &lt;div&gt;Title&lt;/div&gt;
+    &lt;div&gt;Action&lt;/div&gt;
+  &lt;/row-ui&gt;
+  &lt;grid-ui columns="3" gap="sm"&gt;...&lt;/grid-ui&gt;
+&lt;/col-ui&gt;</code-ui>
+</section>
+
+<section data-section data-api="properties">
+  <h2 variant="section">Properties</h2>
+  <p><strong>col-ui</strong></p>
+  <table>
+    <thead><tr><th>Property</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td>justify</td><td>String</td><td><code>'start'</code></td><td>Main-axis distribution. <code>start</code>, <code>center</code>, <code>end</code>, <code>space-between</code>, <code>space-around</code>.</td></tr>
+      <tr><td>align</td><td>String</td><td><code>'stretch'</code></td><td>Cross-axis alignment. <code>start</code>, <code>center</code>, <code>end</code>, <code>stretch</code>.</td></tr>
+      <tr><td>gap</td><td>String</td><td><code>'md'</code></td><td>Space between children. Named <code>xs</code>–<code>xl</code> (parametric, via <code>--a-gap-k</code>) or integer rung <code>0</code>–<code>16</code>; at k=1 they coincide (md=3).</td></tr>
+    </tbody>
+  </table>
+  <p><strong>row-ui</strong></p>
+  <table>
+    <thead><tr><th>Property</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td>justify</td><td>String</td><td><code>'start'</code></td><td>Main-axis distribution.</td></tr>
+      <tr><td>align</td><td>String</td><td><code>'center'</code></td><td>Cross-axis alignment. Adds <code>baseline</code>.</td></tr>
+      <tr><td>gap</td><td>String</td><td><code>'md'</code></td><td>Space between children. Named <code>xs</code>–<code>xl</code> or integer <code>0</code>–<code>16</code> (same grammar as col-ui).</td></tr>
+      <tr><td>wrap</td><td>Boolean</td><td><code>false</code></td><td>Allow children to wrap onto additional lines.</td></tr>
+    </tbody>
+  </table>
+  <p><strong>grid-ui</strong></p>
+  <table>
+    <thead><tr><th>Property</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td>columns</td><td>String</td><td><code>'3'</code></td><td>Column count (<code>1</code>–<code>6</code>) or responsive preset (<code>auto-fill</code>, <code>auto-fit</code>).</td></tr>
+      <tr><td>gap</td><td>String</td><td><code>'md'</code></td><td>Space between rows and columns. Named <code>xs</code>–<code>xl</code> or integer <code>0</code>–<code>16</code>.</td></tr>
+      <tr><td>column-gap</td><td>String</td><td><code>''</code></td><td>Override column gap independently.</td></tr>
+      <tr><td>row-gap</td><td>String</td><td><code>''</code></td><td>Override row gap independently.</td></tr>
+    </tbody>
+  </table>
+  <p><strong>stack-ui</strong></p>
+  <table>
+    <thead><tr><th>Property</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td>align</td><td>String</td><td><code>'center'</code></td><td>Positioning of overlaid children. <code>center</code>, <code>top</code>, <code>bottom</code>, <code>left</code>, <code>right</code>, <code>top-left</code>, <code>top-right</code>, <code>bottom-left</code>, <code>bottom-right</code>.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section data-api="events">
+  <h2 variant="section">Events</h2>
+  <p>None.</p>
+</section>
+
+<section data-section data-api="tokens">
+  <h2 variant="section">CSS Tokens</h2>
+  <p><strong>col-ui</strong></p>
+  <table>
+    <thead><tr><th>Token</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td>--col-gap</td><td>var(--a-space-3)</td><td>Gap between children.</td></tr>
+      <tr><td>--col-justify</td><td>flex-start</td><td>Main-axis distribution.</td></tr>
+      <tr><td>--col-align</td><td>stretch</td><td>Cross-axis alignment.</td></tr>
+    </tbody>
+  </table>
+  <p><strong>row-ui</strong></p>
+  <table>
+    <thead><tr><th>Token</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td>--row-gap</td><td>var(--a-space-3)</td><td>Gap between children.</td></tr>
+      <tr><td>--row-justify</td><td>flex-start</td><td>Main-axis distribution.</td></tr>
+      <tr><td>--row-align</td><td>center</td><td>Cross-axis alignment.</td></tr>
+    </tbody>
+  </table>
+  <p><strong>grid-ui</strong></p>
+  <table>
+    <thead><tr><th>Token</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td>--grid-columns</td><td>3</td><td>Number of columns.</td></tr>
+      <tr><td>--grid-gap</td><td>var(--a-space-3)</td><td>Default row and column gap.</td></tr>
+      <tr><td>--grid-column-gap</td><td>var(--grid-gap)</td><td>Column-only gap override.</td></tr>
+      <tr><td>--grid-row-gap</td><td>var(--grid-gap)</td><td>Row-only gap override.</td></tr>
+    </tbody>
+  </table>
+  <p><strong>stack-ui</strong></p>
+  <table>
+    <thead><tr><th>Token</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td>--stack-align</td><td>center</td><td>place-items value for overlaid children.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section data-property="rules">
+  <h2 variant="section">Authoring rules</h2>
+  <ul>
+    <li><strong>Never emit inline flex CSS.</strong> Always use <code>&lt;row-ui gap="N"&gt;</code> and <code>&lt;col-ui gap="N"&gt;</code> instead of <code>style="display:flex; gap:16px"</code>. The gap value is a unitless integer mapping to <code>--a-space-N</code> and responds to <code>--a-density</code> automatically.</li>
+    <li><strong>Gap values are not pixel values.</strong> <code>gap="4"</code> means <code>--a-space-4</code> (16px at default density), not 4px. Use the spacing scale, not raw numbers.</li>
+    <li><strong>Use <code>grid-ui</code> for fixed column counts</strong> and <code>row-ui wrap</code> for wrapping collections. Use <code>grid-ui columns="1 2@sm 4@lg"</code> for responsive grids rather than multiple hidden elements.</li>
+    <li><strong>Prefer <code>wrap-at="bp"</code> over always-on <code>wrap</code></strong> for toolbars and action rows. <code>wrap-at="sm"</code> keeps the row single-line on desktop while allowing natural wrapping on mobile.</li>
+    <li><strong>Don't use Tailwind-style utility classes.</strong> AdiaUI does not include Tailwind or Bootstrap. Every layout need has a corresponding primitive — reach for the component, not a class.</li>
+    <li><strong>Don't nest <code>row-ui</code> inside <code>col-ui</code></strong> when <code>grid-ui</code> would express the same layout in one element with less nesting. Nested flex containers are harder to reason about at breakpoints.</li>
+  </ul>
+</section>

package/patterns/layout/layout.html

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Layout (pattern) — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.css">
+
+  <!-- Component CSS — primitives this pattern composes -->
+  <link rel="stylesheet" href="../../components/block/block.css">
+  <link rel="stylesheet" href="../../components/code/code.css">
+  <link rel="stylesheet" href="../../components/col/col.css">
+  <link rel="stylesheet" href="../../components/grid/grid.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/stack/stack.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/block/block.js"></script>
+  <script type="module" src="../../components/code/code.js"></script>
+  <script type="module" src="../../components/col/col.js"></script>
+  <script type="module" src="../../components/grid/grid.js"></script>
+  <script type="module" src="../../components/row/row.js"></script>
+  <script type="module" src="../../components/stack/stack.js"></script>
+  <script type="module" src="../../components/tag/tag.js"></script>
+
+  <style>
+    :where(html, body) { margin: 0; min-height: 100vh; background: var(--md-sys-color-neutral-background); color: var(--md-sys-color-neutral-on-surface); font-family: var(--a-font-family); }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./layout.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load layout.examples.html — ${err.message}</p>`;
+      console.error('[layout.html]', err);
+    }
+  </script>
+
+</body>
+</html>