@substrate-system/select 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,168 @@
+# Big Time Public License
+
+Version 2.0.2
+
+<https://bigtimelicense.com/versions/2.0.2>
+
+## Purpose
+
+These terms let you use and share this software for noncommercial purposes
+and in small business for free, while also guaranteeing that paid licenses
+for big businesses will be available on fair, reasonable, and
+nondiscriminatory terms.
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as
+both strict obligations and conditions to all your licenses.
+
+## Noncommercial Purposes
+
+You may use the software for any noncommercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of
+public knowledge, personal study, private entertainment, hobby projects,
+amateur pursuits, or religious observance, without any anticipated
+commercial application, count as use for noncommercial purposes.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public
+research organization, public safety or health organization, environmental
+protection organization, or government institution counts as use for
+noncommercial purposes, regardless of the source of funding or obligations
+resulting from the funding.
+
+## Small Business
+
+You may use the software for the benefit of your company if it meets all
+these criteria:
+
+1.  had fewer than 20 total individuals working as employees and
+    independent contractors at all times during the last tax year
+
+2.  earned less than $1,000,000 total revenue in the last tax year
+
+3.  received less than $1,000,000 total debt, equity, and other investment
+    in the last five tax years, counting investment in predecessor
+    companies that reorganized into, merged with, or spun out your company
+
+All dollar figures are United States dollars as of 2019.  Adjust for them
+inflation according to the United States Bureau of Labor Statistics'
+consumer price index for all urban consumers, United States city average,
+for all items, not seasonally adjusted, with 1982–1984=100 reference base.
+
+## Big Business
+
+You may use the software for the benefit of your company:
+
+1.  for 128 days after your company stops qualifying under
+    [Small Business](#small-business)
+
+2.  indefinitely, if the licensor or their legal successor does not offer
+fair, reasonable, and nondiscriminatory terms for a commercial license for
+the software within 32 days of [written request](#how-to-request) and
+negotiate in good faith to conclude a deal
+
+## How to Request
+
+If this software includes an address for the licensor or an agent of the
+licensor in a standard place, such as in documentation, software package
+metadata, or an "about" page or screen, try to request a fair commercial
+license at that address.  If this package includes both online and offline
+addresses, try online before offline.  If you can't deliver a request that
+way, or this software doesn't include any addressees, spend one hour online
+researching an address, recording all your searches and inquiries as you
+go, and try any addresses that you find.  If you can't find any addresses,
+or if those addresses also fail, that counts as failure to offer a fair
+commercial license by the licensor under [Big Business](#big-business).
+
+## Fair, Reasonable, and Nondiscriminatory Terms
+
+Fair, reasonable, and nondiscriminatory terms may license the software
+perpetually or for a term, and may or may not cover new versions of the
+software.  If the licensor advertises license terms and a pricing structure
+for generally available commercial licenses, the licensor proposes license
+terms and a price as advertised, and a customer not affiliated with the
+licensor has bought a commercial license for the software on substantially
+equivalent terms in the past year, the proposal is fair, reasonable, and
+nondiscriminatory.
+
+## Copyright License
+
+The licensor grants you a copyright license to do everything with the
+software that would otherwise infringe the licensor's copyright in it for
+any purpose allowed by these terms.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software
+from you also gets a copy of these terms or the URL for them above, as well
+as copies of any plain-text lines beginning with `Required Notice:` that
+the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Nick Thomas (https://nichoth.com)
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers
+patent claims the licensor can license, or becomes able to license, that
+you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms
+do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses
+to anyone else, or prevent the licensor from granting licenses to anyone
+else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to
+infringement of any patent, your patent license for the software granted
+under these terms ends immediately. If your company makes such a claim,
+your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of
+these terms, or done anything with the software not covered by your
+licenses, your licenses can nonetheless continue if you come into full
+compliance with these terms, and take practical steps to correct past
+violations, within 32 days of receiving notice.  Otherwise, all your
+licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty
+or condition, and the licensor will not be liable to you for any damages
+arising out of these terms or the use or nature of the software, under any
+kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and
+the **software** is the software the licensor makes available under these
+terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control
+over, are under the control of, or are under common control with that
+organization.  **Control** means ownership of substantially all the assets
+of an entity, or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software
+under these terms.
+
+**Use** means anything you do with the software requiring one of your
+licenses.
+

package/README.md

@@ -1,3 +1,313 @@
-# Temporary Holding Version
+# substrate-select
+![tests](https://github.com/substrate-system/select/actions/workflows/nodejs.yml/badge.svg)
+[![types](https://img.shields.io/npm/types/@substrate-system/select?style=flat-square)](README.md)
+[![module](https://img.shields.io/badge/module-ESM%2FCJS-blue?style=flat-square)](README.md)
+[![install size](https://flat.badgen.net/packagephobia/install/@substrate-system/select?cache-control=no-cache)](https://packagephobia.com/result?p=@substrate-system/select)
+[![GZip size](https://flat.badgen.net/bundlephobia/minzip/@substrate-system/select)](https://bundlephobia.com/package/@substrate-system/select)
+[![semantic versioning](https://img.shields.io/badge/semver-2.0.0-blue?logo=semver&style=flat-square)](https://semver.org/)
+[![Common Changelog](https://nichoth.github.io/badge/common-changelog.svg)](./CHANGELOG.md)
+[![license](https://img.shields.io/badge/license-Big_Time-blue?style=flat-square)](LICENSE)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+
+A native `<select>` with a consistent, themeable look. Write ordinary
+`<option>` and `<optgroup>` children; the component builds a real
+`<select>` around them, so forms, keyboard use, and accessibility work
+the way the browser already does them.
+
+[See a live demo](https://substrate-system.github.io/select/)
+
+<details><summary><h2>Contents</h2></summary>
+
+<!-- toc -->
+
+- [Install](#install)
+- [Example](#example)
+  * [htm and Preact](#htm-and-preact)
+- [API](#api)
+  * [ESM](#esm)
+  * [Common JS](#common-js)
+  * [Attributes](#attributes)
+  * [Options](#options)
+  * [Properties](#properties)
+  * [Events](#events)
+  * [Forms](#forms)
+- [CSS](#css)
+  * [Import CSS](#import-css)
+  * [Tokens](#tokens)
+  * [Browser support](#browser-support)
+  * [Avoid a flash of undefined content](#avoid-a-flash-of-undefined-content)
+- [Use](#use)
+  * [JS](#js)
+  * [HTML](#html)
+  * [pre-built](#pre-built)
+
+<!-- tocstop -->
+
+</details>
+
+## Install
+
+```sh
+npm i -S @substrate-system/select
+```
+
+## Example
+
+```html
+<form>
+    <substrate-select label="Fruit" name="fruit" required>
+        <option value="">Choose a fruit</option>
+        <optgroup label="Citrus">
+            <option value="lemon">Lemon</option>
+            <option value="orange" selected>Orange</option>
+        </optgroup>
+        <option value="apple">Apple</option>
+    </substrate-select>
+</form>
+
+<script type="module">
+    import { SubstrateSelect } from '@substrate-system/select'
+
+    const el = document.querySelector('substrate-select')
+    el.on('change', ev => console.log(ev.detail.value))
+</script>
+```
+
+### htm and Preact
+
+Preact sets `value` as a property, because the element defines one.
+
+```js
+import { html } from 'htm/preact'
+import '@substrate-system/select'
+
+function FruitPicker ({ fruit, onChange }) {
+    return html`<substrate-select
+        label="Fruit"
+        name="fruit"
+        value=${fruit}
+        onsubstrate-select:change=${ev => onChange(ev.detail.value)}
+    >
+        <option value="lemon">Lemon</option>
+        <option value="apple">Apple</option>
+    </substrate-select>`
+}
+```
+
+## API
+
+This exposes ESM and common JS via
+[package.json `exports` field](https://nodejs.org/api/packages.html#exports).
+
+### ESM
+```js
+import { SubstrateSelect } from '@substrate-system/select'
+```
+
+Importing the module registers the `<substrate-select>` element.
+
+### Common JS
+```js
+require('@substrate-system/select')
+```
+
+### Attributes
+
+| Attribute | Behavior |
+|-----------|----------|
+| `label` | Renders a `<label>` for the select. Changing it updates the label in place; removing it removes the label. |
+| `name`, `disabled`, `required`, `autocomplete`, `form` | Copied to the inner select and kept on the host. |
+| `id` | Moved to the inner select and removed from the host. A generated id is used when absent. |
+| `aria-*` | Moved to the inner select and removed from the host. |
+
+`multiple` and `size` are not supported (listbox mode is only
+styleable in Chromium). Setting or removing `id` or an `aria-*`
+attribute on the host after upgrade updates the inner select, so a
+framework can toggle `aria-invalid` or `aria-describedby` for error
+messages. Removing `id` falls back to the generated id.
+
+At first render every `aria-*` attribute moves. After that, a newly set
+`aria-*` attribute moves only if it is listed in the exported
+`ARIA_ATTRIBUTES` array. Removing any `aria-*` attribute from the host
+removes it from the select.
+
+### Options
+
+Authored `<option>` and `<optgroup>` children are moved into the select
+on first connect, and options appended to the host later are moved to
+the end of the select. Other children present at first connect are
+dropped; non-option children appended later are left in place.
+
+A framework that later inserts a node relative to a moved option may
+fail, because that option is no longer a child of the host. Manage
+dynamic option lists through `el.select`.
+
+### Properties
+
+- `value` -- read or write the selected value. A value set before the
+  element renders is held until an option with that value exists,
+  whether it is appended to the host or added through `el.select`, then
+  selected, unless a later `value` set or a user pick replaces it.
+  Before render, `value` returns the waiting value. Once rendered, the
+  select starts with no selection while the value waits (`value` is
+  `""`), even if an option was authored `selected`; options added
+  after that follow the browser's usual selection rules.
+  Options appended to the host in the same tick are moved in before a
+  new value is applied. After render, setting a value with no matching
+  option leaves `""`.
+- `select` -- the inner `HTMLSelectElement`, or `null` before the first
+  render.
+- `label`, `name`, `disabled`, `required` -- reflect the attributes of
+  the same name.
+
+### Events
+
+Native `change` and `input` events bubble from the inner select
+unchanged. On `change` the element also emits `substrate-select:change`
+with `detail: { value:string }` (`SubstrateSelectChangeDetail`).
+
+```js
+el.addEventListener(SubstrateSelect.event('change'), ev => {
+    console.log(ev.detail.value)
+})
+// or
+el.on('change', ev => console.log(ev.detail.value))
+```
+
+Setting `el.value` from code fires neither event, like a native select.
+
+### Forms
+
+The select is a light-DOM descendant of the enclosing `<form>`, so
+submission and `FormData` include it with no extra work.
+
+
+## CSS
+
+### Import CSS
+
+```js
+import '@substrate-system/select/css'
+```
+
+Or minified:
+```js
+import '@substrate-system/select/min/css'
+```
+
+### Tokens
+
+The first eight tokens fall back to a shared `--substrate-*` variable,
+then to a default. The last three have only a default.
+
+| Token | Falls back to | Default |
+|-------|---------------|---------|
+| `--substrate-select-text` | `--substrate-text` | `black` |
+| `--substrate-select-surface` | `--substrate-surface` | `white` |
+| `--substrate-select-border` | `--substrate-border` | `#9b9b9b` |
+| `--substrate-select-accent` | `--substrate-accent` | `#2563eb` |
+| `--substrate-select-focus` | `--substrate-focus` | `#2563eb` |
+| `--substrate-select-focus-width` | `--substrate-focus-width` | `2px` |
+| `--substrate-select-focus-offset` | `--substrate-focus-offset` | `2px` |
+| `--substrate-select-radius` | `--substrate-radius` | `0` |
+| `--substrate-select-option-hover` | none | `#f3f4f6` |
+| `--substrate-select-checked` | none | `#1d4ed8` |
+| `--substrate-select-shadow` | none | `0 4px 12px #21212114` |
+
+`--substrate-select-checked` colors the chosen option's text in the
+picker. It does not follow the accent, so set it too when you change
+the accent (`--substrate-select-accent` or `--substrate-accent`).
+
+```css
+substrate-select {
+    --substrate-select-accent: rebeccapurple;
+    --substrate-select-checked: rebeccapurple;
+}
+```
+
+### Browser support
+
+The baseline (outlined trigger, chevron, focus and hover states) works
+in every browser. Where `appearance: base-select` is supported, the
+picker is styled too: a rotating chevron, a checkmark on the chosen
+option, and an open transition, which respects reduced motion. Today
+that is Chromium (Chrome and Edge 135+). Safari 27 support is announced
+but unconfirmed in stable, and Firefox has it only behind flags.
+Elsewhere the browser's native picker opens.
+
+### Avoid a flash of undefined content
+
+The stylesheet hides `substrate-select` until the browser has defined
+it, so you do not see unstyled markup while the JS loads.
+
+That only covers this one element. If your page uses several custom
+elements, hide the whole page until they are all ready, and reveal it
+once:
+
+```html
+<html class="reduce-fouce">
+```
+
+```css
+html.reduce-fouce { opacity: 0; }
+```
+
+```js
+await Promise.race([
+    Promise.allSettled([
+        customElements.whenDefined('substrate-select')
+    ]),
+    // reveal anyway after two seconds
+    new Promise(resolve => { setTimeout(resolve, 2000) })
+])
+
+document.documentElement.classList.remove('reduce-fouce')
+```
+
+Keep the timeout, and add a `<noscript>` override. Without both, a
+component that fails to define leaves the page blank:
+
+```html
+<noscript>
+    <style>html.reduce-fouce { opacity: 1 !important; }</style>
+</noscript>
+```
+
+## Use
+This calls the global function `customElements.define`. Just import, then use
+the tag in your HTML.
+
+### JS
+```js
+import '@substrate-system/select'
+```
+
+### HTML
+```html
+<substrate-select label="Size" name="size">
+    <option value="s">Small</option>
+    <option value="l">Large</option>
+</substrate-select>
+```
+
+### pre-built
+
+This package exposes minified JS and CSS files too. Copy them to a location that is
+accessible to your web server, then link to them in HTML.
+
+#### copy
+```sh
+cp ./node_modules/@substrate-system/select/dist/index.min.js ./public/substrate-select.min.js
+cp ./node_modules/@substrate-system/select/dist/index.min.css ./public/substrate-select.css
+```
+
+#### HTML
+```html
+<head>
+    <link rel="stylesheet" href="./substrate-select.css">
+</head>
+<body>
+    <!-- ... -->
+    <script type="module" src="./substrate-select.min.js"></script>
+</body>
+```