Skip to content

Commit cadbebc

Browse files
author
R. S. Doiel
committed
added summary documentation for each web component
1 parent 42a8c45 commit cadbebc

17 files changed

+398
-43
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@
44
bin
55
dist
66
scratch
7+
deno.*

‎CSVTextarea.html‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
<!DOCTYPE html>
2+
<html lang="en-US">
3+
<head>
4+
<title>CL-web-components</title>
5+
<link rel="stylesheet" href="/css/site.css">
6+
</head>
7+
<body>
8+
<nav>
9+
<ul>
10+
<li><a href="/">Home</a></li>
11+
<li><a href="index.html">README</a></li>
12+
<li><a href="LICENSE">LICENSE</a></li>
13+
<li><a href="user_manual.html">User Manual</a></li>
14+
<li><a href="INSTALL.html">INSTALL</a></li>
15+
<li><a href="about.html">About</a></li>
16+
<li><a href="search.html">Search</a></li>
17+
<li><a href="https://github.com/caltechlibrary/CL-web-components">GitHub</a></li>
18+
</ul>
19+
</nav>
20+
<section>
21+
<h1 id="csvtextarea">CSVTextarea</h1>
22+
<p>This is a web component intended to wrap a textarea where people
23+
would enter CSV encoded text. By wrapping the textarea element we
24+
provide a fallback should JavaScript be unavailable.</p>
25+
<h2 id="overview">Overview</h2>
26+
<p>The <code>CSVTextarea</code> web component is designed to create an
27+
interactive table from CSV data, allowing users to edit the data
28+
directly in the table. It supports features like appending rows,
29+
cleaning up empty rows, and converting table data to and from CSV
30+
format.</p>
31+
<h2 id="key-features">Key Features</h2>
32+
<ul>
33+
<li><strong>CSV Parsing</strong>: Automatically parses CSV data into a
34+
table format.</li>
35+
<li><strong>Editable Table</strong>: Allows users to edit table cells
36+
directly.</li>
37+
<li><strong>Row Management</strong>: Provides functionality to append
38+
rows and clean up empty rows.</li>
39+
<li><strong>Autocomplete</strong>: Supports autocomplete for table cells
40+
using <code>&lt;datalist&gt;</code> elements.</li>
41+
<li><strong>Event Handling</strong>: Dispatches custom events for cell
42+
changes and focus.</li>
43+
</ul>
44+
<h2 id="attributes">Attributes</h2>
45+
<ul>
46+
<li><strong><code>column-headings</code></strong>: A comma-separated
47+
string of column headings for the table.</li>
48+
<li><strong><code>id</code></strong>: Sets the ID of the component.</li>
49+
<li><strong><code>class</code></strong>: Sets the class of the
50+
component.</li>
51+
<li><strong><code>caption</code></strong>: Sets a caption for the
52+
table.</li>
53+
<li><strong><code>text</code></strong>: Sets the initial text content of
54+
the table.</li>
55+
<li><strong><code>placeholder</code></strong>: Sets the placeholder text
56+
for input fields in the table.</li>
57+
<li><strong><code>css-href</code></strong>: Links to an external CSS
58+
file for styling.</li>
59+
<li><strong><code>debug</code></strong>: Enables debug mode, which logs
60+
additional information to the console.</li>
61+
<li><strong><code>title</code></strong>: Sets a title for the help
62+
icon.</li>
63+
<li><strong><code>help-description</code></strong>: Sets a description
64+
for the help icon.</li>
65+
</ul>
66+
<h2 id="usage">Usage</h2>
67+
<ol type="1">
68+
<li><p><strong>Include the Component</strong>: Ensure the component’s
69+
JavaScript file is included in your HTML.</p></li>
70+
<li><p><strong>HTML Structure</strong>: Use the
71+
<code>&lt;csv-textarea&gt;</code> tag and include a
72+
<code>&lt;textarea&gt;</code> with CSV data inside it.</p></li>
73+
</ol>
74+
<h2 id="example">Example</h2>
75+
<p>Here’s an example of how to use the <code>CSVTextarea</code>
76+
component in an HTML file:</p>
77+
<div class="sourceCode" id="cb1"><pre
78+
class="sourceCode html"><code class="sourceCode html"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;!DOCTYPE</span> html<span class="dt">&gt;</span></span>
79+
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;</span><span class="kw">html</span><span class="ot"> lang</span><span class="op">=</span><span class="st">&quot;en&quot;</span><span class="dt">&gt;</span></span>
80+
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;</span><span class="kw">head</span><span class="dt">&gt;</span></span>
81+
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">meta</span><span class="ot"> charset</span><span class="op">=</span><span class="st">&quot;UTF-8&quot;</span><span class="dt">&gt;</span></span>
82+
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">meta</span><span class="ot"> name</span><span class="op">=</span><span class="st">&quot;viewport&quot;</span><span class="ot"> content</span><span class="op">=</span><span class="st">&quot;width=device-width, initial-scale=1.0&quot;</span><span class="dt">&gt;</span></span>
83+
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">title</span><span class="dt">&gt;</span>CSVTextarea Component Example<span class="dt">&lt;/</span><span class="kw">title</span><span class="dt">&gt;</span></span>
84+
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">script</span><span class="ot"> type=</span><span class="st">&quot;module&quot;</span><span class="ot"> src</span><span class="op">=</span><span class="st">&quot;path/to/your/csvtextarea.js&quot;</span><span class="dt">&gt;&lt;/</span><span class="kw">script</span><span class="dt">&gt;</span></span>
85+
<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;/</span><span class="kw">head</span><span class="dt">&gt;</span></span>
86+
<span id="cb1-9"><a href="#cb1-9" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;</span><span class="kw">body</span><span class="dt">&gt;</span></span>
87+
<span id="cb1-10"><a href="#cb1-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">csv-textarea</span><span class="ot"> column-headings</span><span class="op">=</span><span class="st">&quot;Name,Age,City&quot;</span><span class="ot"> debug</span><span class="dt">&gt;</span></span>
88+
<span id="cb1-11"><a href="#cb1-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">textarea</span><span class="dt">&gt;</span></span>
89+
<span id="cb1-12"><a href="#cb1-12" aria-hidden="true" tabindex="-1"></a> John Doe,30,New York</span>
90+
<span id="cb1-13"><a href="#cb1-13" aria-hidden="true" tabindex="-1"></a> Jane Smith,25,Los Angeles</span>
91+
<span id="cb1-14"><a href="#cb1-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;/</span><span class="kw">textarea</span><span class="dt">&gt;</span></span>
92+
<span id="cb1-15"><a href="#cb1-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;/</span><span class="kw">csv-textarea</span><span class="dt">&gt;</span></span>
93+
<span id="cb1-16"><a href="#cb1-16" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;/</span><span class="kw">body</span><span class="dt">&gt;</span></span>
94+
<span id="cb1-17"><a href="#cb1-17" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;/</span><span class="kw">html</span><span class="dt">&gt;</span></span></code></pre></div>
95+
<h2 id="explanation">Explanation</h2>
96+
<ul>
97+
<li><strong>Component Tag</strong>: The
98+
<code>&lt;csv-textarea&gt;</code> tag is used to define the
99+
component.</li>
100+
<li><strong>Column Headings</strong>: The <code>column-headings</code>
101+
attribute specifies the headings for the table columns.</li>
102+
<li><strong>Debug Mode</strong>: The <code>debug</code> attribute
103+
enables debug mode, which logs additional information to the
104+
console.</li>
105+
<li><strong>Textarea</strong>: The <code>&lt;textarea&gt;</code> inside
106+
the component contains the initial CSV data.</li>
107+
</ul>
108+
<h2 id="customization">Customization</h2>
109+
<ul>
110+
<li><strong>Styling</strong>: You can customize the styles by modifying
111+
the CSS in the <code>initializeComponent</code> method or by linking to
112+
an external CSS file using the <code>css-href</code> attribute.</li>
113+
<li><strong>Autocomplete</strong>: Use <code>&lt;datalist&gt;</code>
114+
elements to provide autocomplete options for table cells.</li>
115+
<li><strong>Event Listeners</strong>: Customize event listeners in the
116+
<code>setupEventListeners</code> method to handle specific
117+
interactions.</li>
118+
</ul>
119+
<h2 id="conclusion">Conclusion</h2>
120+
<p>The <code>CSVTextarea</code> component simplifies the creation of
121+
editable tables from CSV data, making it easier to manage and interact
122+
with tabular data in web applications. By following the usage guidelines
123+
and customizing as needed, you can integrate this component into your
124+
web projects seamlessly.</p>
125+
</section>
126+
</body>
127+
</html>

‎CSVTextarea.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
2+
# CSVTextarea
3+
4+
This is a web component intended to wrap a textarea where people would enter CSV encoded text. By wrapping the textarea element we provide a fallback should JavaScript be unavailable.
5+
6+
## Overview
7+
8+
The `CSVTextarea` web component is designed to create an interactive table from CSV data, allowing users to edit the data directly in the table. It supports features like appending rows, cleaning up empty rows, and converting table data to and from CSV format.
9+
10+
## Key Features
11+
12+
- **CSV Parsing**: Automatically parses CSV data into a table format.
13+
- **Editable Table**: Allows users to edit table cells directly.
14+
- **Row Management**: Provides functionality to append rows and clean up empty rows.
15+
- **Autocomplete**: Supports autocomplete for table cells using `<datalist>` elements.
16+
- **Event Handling**: Dispatches custom events for cell changes and focus.
17+
18+
## Attributes
19+
20+
- **`column-headings`**: A comma-separated string of column headings for the table.
21+
- **`id`**: Sets the ID of the component.
22+
- **`class`**: Sets the class of the component.
23+
- **`caption`**: Sets a caption for the table.
24+
- **`text`**: Sets the initial text content of the table.
25+
- **`placeholder`**: Sets the placeholder text for input fields in the table.
26+
- **`css-href`**: Links to an external CSS file for styling.
27+
- **`debug`**: Enables debug mode, which logs additional information to the console.
28+
- **`title`**: Sets a title for the help icon.
29+
- **`help-description`**: Sets a description for the help icon.
30+
31+
## Usage
32+
33+
1. **Include the Component**: Ensure the component's JavaScript file is included in your HTML.
34+
35+
2. **HTML Structure**: Use the `<csv-textarea>` tag and include a `<textarea>` with CSV data inside it.
36+
37+
## Example
38+
39+
Here's an example of how to use the `CSVTextarea` component in an HTML file:
40+
41+
```html
42+
<!DOCTYPE html>
43+
<html lang="en">
44+
<head>
45+
<meta charset="UTF-8">
46+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
47+
<title>CSVTextarea Component Example</title>
48+
<script type="module" src="path/to/your/csvtextarea.js"></script>
49+
</head>
50+
<body>
51+
<csv-textarea column-headings="Name,Age,City" debug>
52+
<textarea>
53+
John Doe,30,New York
54+
Jane Smith,25,Los Angeles
55+
</textarea>
56+
</csv-textarea>
57+
</body>
58+
</html>
59+
```
60+
61+
## Explanation
62+
63+
- **Component Tag**: The `<csv-textarea>` tag is used to define the component.
64+
- **Column Headings**: The `column-headings` attribute specifies the headings for the table columns.
65+
- **Debug Mode**: The `debug` attribute enables debug mode, which logs additional information to the console.
66+
- **Textarea**: The `<textarea>` inside the component contains the initial CSV data.
67+
68+
## Customization
69+
70+
- **Styling**: You can customize the styles by modifying the CSS in the `initializeComponent` method or by linking to an external CSS file using the `css-href` attribute.
71+
- **Autocomplete**: Use `<datalist>` elements to provide autocomplete options for table cells.
72+
- **Event Listeners**: Customize event listeners in the `setupEventListeners` method to handle specific interactions.
73+
74+
## Conclusion
75+
76+
The `CSVTextarea` component simplifies the creation of editable tables from CSV data, making it easier to manage and interact with tabular data in web applications. By following the usage guidelines and customizing as needed, you can integrate this component into your web projects seamlessly.

‎a_to_z_ul.html‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<!DOCTYPE html>
2+
<html lang="en-US">
3+
<head>
4+
<title>CL-web-components</title>
5+
<link rel="stylesheet" href="/css/site.css">
6+
</head>
7+
<body>
8+
<nav>
9+
<ul>
10+
<li><a href="/">Home</a></li>
11+
<li><a href="index.html">README</a></li>
12+
<li><a href="LICENSE">LICENSE</a></li>
13+
<li><a href="user_manual.html">User Manual</a></li>
14+
<li><a href="INSTALL.html">INSTALL</a></li>
15+
<li><a href="about.html">About</a></li>
16+
<li><a href="search.html">Search</a></li>
17+
<li><a href="https://github.com/caltechlibrary/CL-web-components">GitHub</a></li>
18+
</ul>
19+
</nav>
20+
<section>
21+
<h1 id="atozul">AtoZUL</h1>
22+
<p>This is a web component targeting simple A to Z lists derived from UL
23+
lists. It wraps an innerHTML that contains a UL list as the fallback if
24+
JavaScript is unavailable.</p>
25+
<h3 id="overview">Overview</h3>
26+
<p>The <code>AToZUL</code> web component is designed to create an
27+
alphabetical menu from a list of items. It organizes the items into
28+
sections based on their initial letter and provides navigation between
29+
these sections.</p>
30+
<h3 id="key-features">Key Features</h3>
31+
<ul>
32+
<li><strong>Alphabetical Menu</strong>: Automatically generates a menu
33+
with links to each letter section.</li>
34+
<li><strong>Section Navigation</strong>: Allows smooth scrolling to each
35+
section when a menu item is clicked.</li>
36+
<li><strong>Back to Menu</strong>: Optionally displays a “Back to Menu”
37+
link when the <code>long</code> attribute is present.</li>
38+
</ul>
39+
<h3 id="attributes">Attributes</h3>
40+
<ul>
41+
<li><strong><code>long</code></strong>: When this attribute is present,
42+
a “Back to Menu” link is displayed at the end of each section.</li>
43+
</ul>
44+
<h3 id="usage">Usage</h3>
45+
<ol type="1">
46+
<li><p><strong>Include the Component</strong>: Ensure the component’s
47+
JavaScript file is included in your HTML.</p></li>
48+
<li><p><strong>HTML Structure</strong>: Use the
49+
<code>&lt;a-to-z-ul&gt;</code> tag and include a <code>&lt;ul&gt;</code>
50+
with <code>&lt;li&gt;</code> items inside it.</p></li>
51+
</ol>
52+
<h3 id="example">Example</h3>
53+
<p>Here’s an example of how to use the <code>AToZUL</code> component in
54+
an HTML file:</p>
55+
<div class="sourceCode" id="cb1"><pre
56+
class="sourceCode html"><code class="sourceCode html"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;!DOCTYPE</span> html<span class="dt">&gt;</span></span>
57+
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;</span><span class="kw">html</span><span class="ot"> lang</span><span class="op">=</span><span class="st">&quot;en&quot;</span><span class="dt">&gt;</span></span>
58+
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;</span><span class="kw">head</span><span class="dt">&gt;</span></span>
59+
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">meta</span><span class="ot"> charset</span><span class="op">=</span><span class="st">&quot;UTF-8&quot;</span><span class="dt">&gt;</span></span>
60+
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">meta</span><span class="ot"> name</span><span class="op">=</span><span class="st">&quot;viewport&quot;</span><span class="ot"> content</span><span class="op">=</span><span class="st">&quot;width=device-width, initial-scale=1.0&quot;</span><span class="dt">&gt;</span></span>
61+
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">title</span><span class="dt">&gt;</span>AToZUL Component Example<span class="dt">&lt;/</span><span class="kw">title</span><span class="dt">&gt;</span></span>
62+
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">script</span><span class="ot"> type=</span><span class="st">&quot;module&quot;</span><span class="ot"> src</span><span class="op">=</span><span class="st">&quot;path/to/your/component.js&quot;</span><span class="dt">&gt;&lt;/</span><span class="kw">script</span><span class="dt">&gt;</span></span>
63+
<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;/</span><span class="kw">head</span><span class="dt">&gt;</span></span>
64+
<span id="cb1-9"><a href="#cb1-9" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;</span><span class="kw">body</span><span class="dt">&gt;</span></span>
65+
<span id="cb1-10"><a href="#cb1-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">a-to-z-ul</span><span class="ot"> long</span><span class="dt">&gt;</span></span>
66+
<span id="cb1-11"><a href="#cb1-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">ul</span><span class="dt">&gt;</span></span>
67+
<span id="cb1-12"><a href="#cb1-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">li</span><span class="dt">&gt;</span>Apple<span class="dt">&lt;/</span><span class="kw">li</span><span class="dt">&gt;</span></span>
68+
<span id="cb1-13"><a href="#cb1-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">li</span><span class="dt">&gt;</span>Banana<span class="dt">&lt;/</span><span class="kw">li</span><span class="dt">&gt;</span></span>
69+
<span id="cb1-14"><a href="#cb1-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">li</span><span class="dt">&gt;</span>Cherry<span class="dt">&lt;/</span><span class="kw">li</span><span class="dt">&gt;</span></span>
70+
<span id="cb1-15"><a href="#cb1-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">li</span><span class="dt">&gt;</span>Date<span class="dt">&lt;/</span><span class="kw">li</span><span class="dt">&gt;</span></span>
71+
<span id="cb1-16"><a href="#cb1-16" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;</span><span class="kw">li</span><span class="dt">&gt;</span>Elderberry<span class="dt">&lt;/</span><span class="kw">li</span><span class="dt">&gt;</span></span>
72+
<span id="cb1-17"><a href="#cb1-17" aria-hidden="true" tabindex="-1"></a> <span class="co">&lt;!-- Add more items as needed --&gt;</span></span>
73+
<span id="cb1-18"><a href="#cb1-18" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;/</span><span class="kw">ul</span><span class="dt">&gt;</span></span>
74+
<span id="cb1-19"><a href="#cb1-19" aria-hidden="true" tabindex="-1"></a> <span class="dt">&lt;/</span><span class="kw">a-to-z-ul</span><span class="dt">&gt;</span></span>
75+
<span id="cb1-20"><a href="#cb1-20" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;/</span><span class="kw">body</span><span class="dt">&gt;</span></span>
76+
<span id="cb1-21"><a href="#cb1-21" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;/</span><span class="kw">html</span><span class="dt">&gt;</span></span></code></pre></div>
77+
<h3 id="explanation">Explanation</h3>
78+
<ul>
79+
<li><strong>Component Tag</strong>: The <code>&lt;a-to-z-ul&gt;</code>
80+
tag is used to define the component.</li>
81+
<li><strong>List Items</strong>: The <code>&lt;ul&gt;</code> inside the
82+
component contains the items to be organized alphabetically.</li>
83+
<li><strong><code>long</code> Attribute</strong>: Adding the
84+
<code>long</code> attribute will display a “Back to Menu” link.</li>
85+
</ul>
86+
<h3 id="customization">Customization</h3>
87+
<ul>
88+
<li><strong>Styling</strong>: You can customize the styles within the
89+
component’s shadow DOM by modifying the CSS in the <code>render</code>
90+
method.</li>
91+
<li><strong>Behavior</strong>: The <code>scrollToSection</code> method
92+
can be adjusted to change the scrolling behavior or offset.</li>
93+
</ul>
94+
<h3 id="conclusion">Conclusion</h3>
95+
<p>The <code>AToZUL</code> component simplifies the creation of
96+
alphabetical navigation menus, making it easier to organize and navigate
97+
large lists of items. By following the usage guidelines and customizing
98+
as needed, you can integrate this component into your web projects
99+
seamlessly.</p>
100+
</section>
101+
</body>
102+
</html>

0 commit comments

Comments
 (0)