@loadbare/widgets 0.10.0 → 0.11.0

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

@@ -0,0 +1,53 @@
+# `lb-picker`
+
+[`lb-options`](./lb-options.md) with the row template built in, for when every
+row is one option and only the column it shows varies.  It takes no
+children.  Options in groups take a group template, which is `lb-options`
+with the page's own templates.
+
+Apply the `lb-query` attribute to name the query, `lb-column` to name the
+column the choice shows and gathers to, and `lb-request` to name the request a
+change issues.
+
+Provide `exp-label` and `exp-column`.
+
+```html
+<lb-picker
+  lb-query="statuses"
+  lb-column="status_id"
+  exp-label="Status"
+  exp-column="label"
+  lb-request="setStatus"
+></lb-picker>
+```
+
+## Status
+
+Barebones starter to prove out the publish/consume chain and identify necessary
+improvements through iterative use.
+
+## Parameters
+
+| Parameter    | Fills                       |
+| ------------ | --------------------------- |
+| `exp-label`  | the visible `<label>` text  |
+| `exp-column` | the column the option shows |
+
+`exp-column` is required.  The server declares the query's key, which
+becomes each option's `value`.
+
+## Attributes
+
+| Attribute    | Names                                      |
+| ------------ | ------------------------------------------ |
+| `lb-query`   | the query whose rows become options        |
+| `lb-column`  | the column the choice shows and gathers to |
+| `lb-request` | the request a change issues                |
+
+## Choosing
+
+The same as [`lb-options`](./lb-options.md): grouping, the key as the option's
+value, the control's `value`, `lb-query-row-count`, and the request on change.
+
+Write `lb-options` and the template instead for a row that needs a second
+element, or an option built from two columns.

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

@@ -0,0 +1,70 @@
+# `lb-select`
+
+A control wrapping an HTML `<select>`, with the `<option>`s written by hand.
+
+Apply the `lb-column` attribute to name the column, and `lb-request` to name the
+request a change issues.
+
+Provide `exp-label`.
+
+```html
+<lb-select lb-column="status" exp-label="Status" lb-request="setStatus">
+  <option value="open">Open</option>
+  <option value="closed">Closed</option>
+</lb-select>
+```
+
+## Status
+
+Barebones starter to prove out the publish/consume chain and identify necessary
+improvements through iterative use.
+
+## Parameters
+
+| Parameter   | Fills                      |
+| ----------- | -------------------------- |
+| `exp-label` | the visible `<label>` text |
+
+## Attributes
+
+| Attribute    | Names                                      |
+| ------------ | ------------------------------------------ |
+| `lb-column`  | the column the select shows and gathers to |
+| `lb-request` | the request a change issues                |
+
+## The control
+
+`lb-select` is a form-associated custom element.  Its `value` property gets
+and sets the value of the `<select>` inside it, and it fires `change` on itself
+when that `<select>` fires `change`.  A form reset selects the option marked
+`selected`, or the first option.  A refusal's message for its column goes to
+the `<select>`, as HTML's own validity.
+
+## Choosing
+
+With `lb-request`, the `lb-select` commits on `change`.  The hub gathers its
+value alone and sends the request with the `query` and `key` of the row around
+it, and `values` holding the chosen option's value under its column.  Declare
+that request on the server, or name `lb-row-update`.
+
+Without `lb-request`, a change commits nothing, and the form or live row around
+the `lb-select` gathers its value.
+
+Inside `lb-query="lb-url"`, `lb-request="lb-row-update"` writes the choice as a
+query parm, and the hub answers with no round trip.
+
+```html
+<div lb-query="lb-url">
+  <lb-select lb-column="status" exp-label="Status" lb-request="lb-row-update">
+    <option value="">All</option>
+    <option value="open">Open</option>
+  </lb-select>
+</div>
+```
+
+While the request is in flight the hub marks the `lb-select` with
+`lb-request-pending`, and on failure with `lb-request-error`.  Both are there
+for a stylesheet to read.
+
+For a `<select>` whose options come from a query, see
+[`lb-options`](./lb-options.md) and [`lb-picker`](./lb-picker.md).

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`.

package/docs/temp-feature-request-lb-table.md

@@ -1,130 +0,0 @@
-# Feature request: `lb-table` for maintenance pages
-
-Temporary.  Written from the rkmedia app, which uses `lb-table` for every
-list it edits (lookup tables with a ghost row, edit-in-place cells,
-drag-to-reorder).  Two things every such page wants and today writes for
-itself, or cannot have.  To be settled here and then folded into
-`lb-table.md` or deleted.
-
-## 1. The order shown on the heading, and re-sorted from it
-
-**Status:** first iteration implemented, as settled below; see
-`lb-table.md`, *The order on the heading*.
-
-**Want:** `lb-table` always marks the heading of the column the rows are
-sorted by with an up or down triangle for the direction.  While the order is
-dirty from the user's edits (`lb-query-unsorted-count` is not 0), the
-triangle changes color.  Clicking the heading sorts by its column.
-
-**Why:** an edit from a control in a row, or from the ghost row, leaves the
-rows where they stand (`lb-table.md`, *Order and groups*).  Every table
-whose order reads a column the user edits needs a re-sort control, so every
-page writes the same markup and CSS.  What rkmedia writes today:
-
-```html
-<div class="list">
-  <button type="button" class="resort" commandfor="workshop-topics-list" command="--lb-sort">Re-sort</button>
-  <lb-table id="workshop-topics-list" lb-query="workshopTopics" exp-caption="Talks and workshops">
-    ...
-  </lb-table>
-</div>
-```
-
-```css
-.resort { visibility: hidden; }
-:has(> [lb-query-unsorted-count]:not([lb-query-unsorted-count="0"])) > .resort { visibility: visible; }
-```
-
-The button cannot go inside the tag, so it needs an `id`, `commandfor` and
-a `:has()` on a wrapper.  Shown with `display` it moves the table; shown
-with `visibility` it leaves a blank strip above every table.
-
-The heading row is always laid out and the widget owns it, so the
-triangle placed there moves nothing, needs no `id` and no page CSS.  The
-hub already knows the order: the server declares it, and `lb-order` names
-the user's.
-
-**Settled:**
-
-- **The triangle is always shown** on the sorted column's heading, clean or
-  dirty.
-- **Dirty is a color change** on the triangle.
-- **Clicking a dirty triangle re-sorts** (`--lb-sort`): it places the rows
-  and clears `lb-row-unsorted`, keeping the direction.  Only a click on a
-  clean triangle reverses.
-- **Clicking another heading sorts by its column**, writing the user's
-  order (`lb-order`).  That places every row and clears `lb-row-unsorted`.
-- **Raw values.**  A column shown formatted sorts by what the query sent,
-  so it must be sent raw or declared in `types` (the reference already says
-  so); worth repeating in `lb-table.md`.
-- **A default style for `tr[lb-row-unsorted]`** (rkmedia marks the first
-  cell's left edge), subtle and overridable, saves every app writing one.
-- **A heading takes its column from the row template.**  The nth heading
-  shows the column of the nth cell of the row template, the `lb-column` in
-  that cell.  The page writes nothing on the `<th>`.  A cell with no
-  `lb-column`, or with several, gives its heading no column, and that
-  heading does not sort.
-- **One column at a time.**  A heading click writes an order of one term.
-  When the order has several terms, the triangle marks the leading term.
-  Sub-sorts are a UI question for later, built on this foundation.
-- **Groups leave all of this out.**  A table with group templates shows no
-  triangle and takes no heading clicks, so none of it triggers there.
-- **Dirty is yellow, circled.**  The triangle turns yellow and gains a
-  circle around it, so the shape says dirty without the color.
-- **No route back to the server's order.**  Once the user sorts by a
-  heading, the user's order stands.
-- **No sort is the opt-out.**  A table with no order shows no triangle and
-  takes no heading clicks.
-
-**Open:**
-
-- **The order's column not shown.**  A drag-to-reorder table orders by a
-  position column no one displays, and a server's order may lead with any
-  column the template leaves out.  No heading carries the triangle, so a
-  dirty order has no re-sort control.  Either the triangle has an
-  always-present fallback, such tables keep a page-written button, or the
-  dirty state cannot arise for them (a drag rewrites positions so no row
-  stands out of order).
-- **Heading clicks without `lb-order`.**  A heading click writes the user's
-  order into the column of `lb-choices` that `lb-order` names.  A table
-  with a server order and no `lb-order` has nowhere to write it: it can
-  show the triangle and re-sort from it, but not sort by another heading.
-  Whether that is the intended reading of "no sort", or the widget
-  supplies a choice of its own.
-
-The first iteration takes the plain reading of both: a table whose order's
-leading column has no heading shows no triangle and keeps a page-written
-button, and a table without `lb-order` shows the triangle and re-sorts
-from it but takes no clicks on other headings.
-
-## 2. Highlight-to-filter that works on edit pages
-
-**Want:** select text in a cell and the table filters to the rows that
-match, on read-only and editable tables alike, and the table shows what it
-is filtered by.
-
-**What exists:** `lb-table.md`, *Filtering by selection*: a selection in a
-cell whose `lb-column` the table's `lb-filter` names becomes that column's
-choice (`=`, `^=`, `$=`, `*=`).
-
-**Gaps:**
-
-- **Inputs.**  The widget reads `getSelection()`, which does not report text
-  selected inside an `<input>` or `<textarea>`.  An editable cell is an
-  input, so on an edit page highlighting never filters.  A control reports
-  its own range (`selectionStart` / `selectionEnd`); the widget could read
-  that when the selection is in one.
-- **Selecting is also editing.**  In an input, selecting text is how you
-  replace it, so filtering on every selection there would fight editing.
-  It needs a gesture that means "filter": a modifier key held on mouse-up,
-  or inputs that are `readonly`.  Which gesture is Loadbare's call.
-- **No indicator.**  Nothing on the table says it is filtered, by what, or
-  offers to clear it; a page must add a control bound to `lb-choices`
-  itself.  With the re-sort on the heading, the caption line is free for
-  this: the active filters with a clear button for each, and rows hidden
-  ("12 of 40 shown").  Open whether the caption line is the place.
-
-## Order of value to rkmedia
-
-1, then 2.  rkmedia has editable ordered tables now, will want heading
-sorts on the first long list, and has no filters yet.