@loadbare/widgets 0.10.1 → 0.11.1

package/skills/loadbare-widgets/references/lb-table.md

@@ -0,0 +1,173 @@
+# `lb-table`
+
+A wrapper for HTML Table, supplying the `<table>` itself.
+
+Apply the `lb-query` attribute to name the query.  Write three `<template>`s
+inside the tag: one marked `lb-exp-template="head"` for the heading row, one
+unmarked for the row, or a group template holding it, and optionally one
+marked `lb-exp-template="ghost"` for a ghost row and one marked
+`lb-exp-template="foot"` for the footer.  The query's order places the
+rows.
+
+Provide `exp-caption`.
+
+```html
+<lb-table lb-query="ledger" exp-caption="Ledger">
+  <template lb-exp-template="head">
+    <tr><th>Date</th><th>Amount</th></tr>
+  </template>
+  <template lb-group>
+    <tr><th colspan="2" lb-column="month"></th></tr>
+    <template>
+      <tr><td lb-column="date"></td><td lb-column="amount"></td></tr>
+    </template>
+  </template>
+  <template lb-exp-template="foot">
+    <tr><td>Total</td><td lb-sum="amount"></td></tr>
+  </template>
+</lb-table>
+```
+
+Each part goes in a `<template>` because a `<thead>` or `<tr>` written
+directly inside the tag is thrown away by the HTML parser.
+
+## Status
+
+Barebones starter to prove out the publish/consume chain and identify necessary
+improvements through iterative use.
+
+## Parameters
+
+| Parameter     | Fills                |
+| ------------- | -------------------- |
+| `exp-caption` | the `<caption>` text |
+
+## Attributes
+
+| Attribute   | On                               | Names                              |
+| ----------- | -------------------------------- | ---------------------------------- |
+| `lb-query`  | the element itself               | the query whose rows fill the body |
+| `lb-group`  | a template holding the row template | a group, one per run of the order's leading term |
+| `lb-order`  | the element itself               | the choice holding the user's order |
+| `lb-filter` | the element itself               | the columns the user's choices filter |
+| `lb-column` | elements inside the row template | the column each element shows      |
+
+The server declares the query's key and its order.
+
+## Order and groups
+
+The hub places the rows by the query's order and builds its groups.  An
+edit from a control in a row, or from the ghost row, leaves the rows where
+they stand until the user asks for the order; a button with
+`commandfor` naming the table's `id` and `command="--lb-sort"` does that.
+The rows land in the table's one `<tbody>`, and a `<tbody>` cannot hold another,
+so a group here is a heading row with its rows after it.  For a `<tbody>` per
+group, write a plain `<table lb-query>` whose group template is the
+`<tbody>`.
+
+`lb-order` and `lb-filter` work on `lb-table` as on any element carrying
+`lb-query`: the user's order replaces the query's, and a row the user's
+filter does not pass is hidden.
+
+## The order on the heading
+
+The heading of the column the rows are sorted by carries a triangle, up for
+ascending and down for descending, and `aria-sort`, read from the
+`lb-query-order` the hub stamps on the table.  Only the order's leading term
+is shown.  A heading's column is the `lb-column` in the cell
+at the same position in the row template, on the cell or inside it.  A cell
+naming no column, or several, gives its heading none.
+
+While rows stand out of order, the triangle carries `data-unsorted`, and a
+click on its heading places them again, as `--lb-sort` does, keeping the
+direction.
+
+With `lb-order` on the table, a click on the sorted heading reverses the
+order, and a click on another heading sorts by its column, ascending.  The
+widget writes the order to the column of `lb-choices` that `lb-order`
+names.  Without `lb-order` there is nowhere to write one, and only the
+re-sort answers a click.  There is no click back to the server's order.
+
+A heading that takes a click carries `data-sortable`.
+
+None of this shows on a grouped table, nor when the order's leading column
+has no heading.  There, a button with `commandfor` and `--lb-sort` does the
+re-sort.
+
+The package ships `lb-table.css`: the triangle turns amber and circled
+while rows stand out of order, and the first cell of a row carrying
+`lb-row-unsorted` is marked on its leading edge.  The application's own
+stylesheet comes after it and overrides any of it.
+
+## Filtering by selection
+
+Text selected in a cell filters the table by that cell's column, when the
+cell's `lb-column` is one the table's `lb-filter` names.  On mouse-up the
+widget writes the filter to that column of `lb-choices`, replacing whatever
+it held, and clears the selection.  Where the selection lies in the cell's
+text picks the operator:
+
+| Selected               | Filter |
+| ---------------------- | ------ |
+| the whole text         | `=`    |
+| from its start         | `^=`   |
+| up to its end          | `$=`   |
+| anywhere else          | `*=`   |
+
+A control naming the same column of `lb-choices` shows the filter and
+clears it.
+
+```html
+<div lb-query="lb-choices">
+  <lb-input lb-column="payee" lb-request="lb-row-update" exp-label="Payee"></lb-input>
+</div>
+
+<lb-table lb-query="ledger" lb-filter="payee" exp-caption="Ledger">
+  ...
+</lb-table>
+```
+
+A selection reaching across two cells, or into a cell whose column the
+table does not filter, is left alone.
+
+## The ghost row
+
+The `ghost` template is a blank row for entering a new one, in a `<tbody>` of
+its own between the rows and the footer.  It is not a live row: the hub never
+reconciles it and never counts it, and lands on whatever in it names a query.
+
+```html
+<template lb-exp-template="ghost">
+  <tr>
+    <td><lb-input lb-column="name" exp-label="Name"></lb-input></td>
+    <td><button lb-request="lb-row-insert">Save</button></td>
+  </tr>
+</template>
+```
+
+A `<form>` cannot wrap a `<tr>`, so the widget makes one outside the table
+and joins the row's controls and buttons to it with the `form` attribute.  A
+button carrying `lb-row-insert` submits that form, the hub gathers what the
+form owns, and resets it once the insert succeeds.  The widget then puts the
+cursor back in the row's first control.  A refused insert leaves the cursor
+where it was.
+
+## Scrolling
+
+After rows land, the widget scrolls into view the row the page's own request
+created, or moved by changing a column the order reads.
+
+## The footer
+
+The footer is an ordinary part of the page, not a row from the table's query.
+An aggregate there covers every row showing.  A figure that is not a sum of the rows,
+such as a budget, is a `<tr>` with its own `lb-query`, a query of kind
+`row` declared on the server like any other.
+
+## Styling an empty table
+
+`lb-table` carries `lb-query-row-count` with the number of rows showing, for a
+stylesheet to read.
+
+For rows with no table of their own, write the row template inside any element
+that carries `lb-query`.

package/skills/loadbare-widgets/references/lb-tel.md

@@ -0,0 +1,32 @@
+# `lb-tel`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A phone number shown as written, as a `tel:` link.  Not a control: write
+`lb-column` on the tag, and the hub lands the column on it and never gathers
+it.
+
+```html
+<lb-tel lb-column="phone"></lb-tel>
+```
+
+It takes no parameters.  To edit the number, use
+`<lb-input exp-type="tel">`.
+
+## The value
+
+The link's text is the value as it arrived.  Its `href` keeps a leading `+`
+and the digits, and drops everything else, so `(555) 123-4567` dials
+`tel:5551234567`.
+
+An extension written after `x`, `ext`, `ext.` or `extension` goes in the
+`href` as `;ext=`, so `555-123-4567 x89` dials `tel:5551234567;ext=89`.
+
+A value with no digits shows as it arrived, with no `href`.  Null shows
+nothing.
+
+## Styling
+
+The definition is an `<a>`, with no `href` while there is nothing to dial,
+so `lb-tel a:not([href])` selects a number that is no link.  The hub stamps
+the tag with `lb-column-value`, the value as it arrived.

package/skills/loadbare-widgets/references/lb-unknown-page.md

@@ -0,0 +1,43 @@
+# `lb-unknown-page`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+The chrome's dialog for a URL that names no page.  Write it once, inside
+`<lb-hub>`, and the hub opens it whenever no page's stub matches the path.
+
+```html
+<lb-hub>
+  <nav>
+    <a href="/" lb-url-link>Home</a>
+    <a href="/about" lb-url-link>About</a>
+  </nav>
+  <main></main>
+  <lb-unknown-page></lb-unknown-page>
+</lb-hub>
+```
+
+## Parameters
+
+| Parameter         | Fills                                 |
+| ----------------- | ------------------------------------- |
+| `exp-button-text` | the text of the button that closes it |
+
+Leaving `exp-button-text` off labels the button `OK`.
+
+## Binding
+
+The definition supplies its own binding: a `<dialog lb-url-unknown>` carrying
+`lb-query="lb-url"`, the query the hub serves and lands on every page load.
+
+| Column    | Holds                    |
+| --------- | ------------------------ |
+| `lb-path` | the path the browser has |
+
+The widget shows the path.  The dialog opens only when no page matches, so
+there is no page label to show.
+
+## Inside the hub
+
+The hub finds the dialog inside its own subtree and nowhere else, so the tag
+goes inside `<lb-hub>`.  The chrome reference of the loadbare-app skill shows
+the same dialog written by hand in `chrome.html`.