@supersoniks/concorde 5.1.1 → 5.1.3

package/docs/hubs/form-components.html

@@ -0,0 +1,404 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/hubs/form-components.html" data-doc-id="hubs/form-components">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Concorde form components — Concorde by Supersoniks</title>
+  <meta name="description" content="Hub for form UI: sonic-input, sonic-select, sonic-checkbox, sonic-submit, formDataProvider, FormElement.">
+  <meta name="keywords" content="form, FormElement, formDataProvider, sonic-input, sonic-select, sonic-checkbox, sonic-submit">
+  <meta name="concorde-doc-id" content="hubs/form-components">
+  <link rel="canonical" href="https://concorde.supersoniks.org/hubs/form-components.html">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde documentation — Concorde form components</strong>. Hub for form UI: sonic-input, sonic-select, sonic-checkbox, sonic-submit, formDataProvider, FormElement. <span>Doc ID: <code>hubs/form-components</code>. Keywords: form, FormElement, formDataProvider, sonic-input, sonic-select, sonic-checkbox, sonic-submit. URL: <a href="https://concorde.supersoniks.org/hubs/form-components.html">https://concorde.supersoniks.org/hubs/form-components.html</a>.</span></p>
+      <section id="core-components-ui-form-checkbox-checkbox" data-doc-id="core/components/ui/form/checkbox/checkbox">
+  <h2><a href="/core/components/ui/form/checkbox">Checkbox</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/ui/form/checkbox/checkbox</code> · <a href="/core/components/ui/form/checkbox">full page</a></p>
+  <p>sonic-checkbox is a styled checkbox that writes its value into form data. Give it a name and a formDataProvider (on the field or an ancestor); checkboxes sharing a name build an array of the checked v</p>
+  <pre class="doc-excerpt">Checkbox
+
+sonic-checkbox is a styled checkbox that writes its value into form data. Give it a name and a formDataProvider (on the field or an ancestor); checkboxes sharing a name build an array of the checked values. Label goes in the default slot or label, helper text in the description slot.
+
+Basic example
+
+      Notify me of gate changes
+       One message per change, no spam.
+
+Size
+
+With no size, the checkbox follows md (1rem).
+
+       2xs
+       xs
+       sm
+       Default
+       lg
+       xl
+       2xl
+
+Checked and disabled
+
+checked sets the initial state. disabled blocks interaction and dims the control.
+
+       Checked
+       Disabled
+       Disabled and checked
+       I accept the  terms
+
+Form binding
+
+Checkboxes with the same name under one formDataProvider store an array of the checked values. Initial state is read from that data, so a value already present checks the matching box. See Data flow.
+
+       Extra baggage
+       Meal
+       Lounge access
+       Selected:
+
+Single value
+
+unique stores a single value instead of an array: checking one box unchecks the others with the same name, and the checked box can be unchecked again (value null). radio does the same but cann</pre>
+</section>
+<section id="core-components-ui-form-fieldset-fieldset" data-doc-id="core/components/ui/form/fieldset/fieldset">
+  <h2><a href="/core/components/ui/form/fieldset">Fieldset</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/ui/form/fieldset/fieldset</code> · <a href="/core/components/ui/form/fieldset">full page</a></p>
+  <p>sonic-fieldset groups related form controls in a bordered container rendered as a native &lt;fieldset&gt;. Put fields in the default slot and title the group with a slotted sonic-legend or with the label an</p>
+  <pre class="doc-excerpt">Fieldset
+
+sonic-fieldset groups related form controls in a bordered container rendered as a native  . Put fields in the default slot and title the group with a slotted sonic-legend or with the label and description shorthand. Pair the body with sonic-form-layout for responsive columns.
+
+Basic example
+
+Variant
+
+With no variant, the fieldset is default (bordered). ghost and shadow hide the border; shadow adds --sc-shadow-lg.
+
+Tight
+
+tight removes horizontal padding, side borders and rounding, for a flat strip inside a parent.
+
+Legend
+
+sonic-legend takes label and description, or custom markup in its default slot with sonic-legend-description for the secondary line. iconName adds a leading sonic-icon. label and description are rendered as HTML: pass trusted content only.
+
+          Custom title in the default slot
+           Description via sonic-legend-description
+
+Shorthand legend
+
+When label is set on sonic-fieldset, it renders the sonic-legend itself and forwards description · iconName · iconLibrary · iconPrefix. Do not also slot a sonic-legend, or the group gets two titles.
+
+Legend actions
+
+slot=&quot;suffix&quot; on sonic-legend aligns menus or icon buttons to the end of the title row.
+
+ </pre>
+</section>
+<section id="core-components-ui-form-form-actions-form-actions" data-doc-id="core/components/ui/form/form-actions/form-actions">
+  <h2><a href="/core/components/ui/form/form-actions">Form actions</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/ui/form/form-actions/form-actions</code> · <a href="/core/components/ui/form/form-actions">full page</a></p>
+  <p>sonic-form-actions lays out form footer controls (submit, cancel) in a wrapping flex row with a 0.3rem gap. Place it inside sonic-form-layout, where it spans the full width, or at the end of any block</p>
+  <pre class="doc-excerpt">Form actions
+
+sonic-form-actions lays out form footer controls (submit, cancel) in a wrapping flex row with a 0.3rem gap. Place it inside sonic-form-layout, where it spans the full width, or at the end of any block. Use justify and direction to arrange the controls.
+
+Basic example
+
+With no attributes, actions align to the start of the row.
+
+              Check in
+              Cancel
+
+Justify
+
+justify is the CSS justify-content of the row (default flex-start). Use flex-end for dialog-style footers or center for toolbars.
+
+              Submit
+              Cancel
+
+Direction
+
+direction is the CSS flex-direction (default row). row-reverse swaps the visual order but keeps the DOM and focus order.
+
+              Submit
+              Cancel
+
+Mixed controls
+
+Any content can be slotted, such as a vertical sonic-divider. The default alignItems (center) keeps items of different heights aligned.
+
+            Previous step
+
+            Next step
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| direction | row (default) · column · row-reverse · column-reverse | CSS flex-direction of the row |
+| justify | CSS justify-content value (default flex-start) </pre>
+</section>
+<section id="core-components-ui-form-form-layout-form-layout" data-doc-id="core/components/ui/form/form-layout/form-layout">
+  <h2><a href="/core/components/ui/form/form-layout">Form layout</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/ui/form/form-layout/form-layout</code> · <a href="/core/components/ui/form/form-layout">full page</a></p>
+  <p>sonic-form-layout arranges slotted form controls in a responsive grid. Short fields (sonic-input · sonic-select) sit two per row when the host is wider than 440px; every other child spans the full wid</p>
+  <pre class="doc-excerpt">Form layout
+
+sonic-form-layout arranges slotted form controls in a responsive grid. Short fields (sonic-input · sonic-select) sit two per row when the host is wider than 440px; every other child spans the full width. It has no attributes: wrap the body of a form or sonic-fieldset with it.
+
+Basic example
+
+           — Select —
+           Prefer not to say
+           Male
+           Female
+
+         Add priority boarding
+         Subscribe to newsletter
+
+          I accept the
+           terms and conditions
+
+           Confirm passenger
+
+Responsive columns
+
+The column count depends on the host width, not the viewport: two columns above 440px, one below. When the layout holds exactly one short field, it stays single-column so the field does not sit in half an empty row.
+
+         Narrow host
+
+         Wide host
+
+Full-width children
+
+Any child that is not a short field spans the full row: sonic-textarea · sonic-checkbox · sonic-switch · sonic-divider · sonic-form-actions and plain elements. Slotted dividers lose their vertical margin to match the grid gap, and sonic-submit uses display: contents so its button joins the grid directly.
+
+         Send
+
+Custom column wrapper
+
+Add the clas</pre>
+</section>
+<section id="core-components-ui-form-input-input" data-doc-id="core/components/ui/form/input/input">
+  <h2><a href="/core/components/ui/form/input">Input</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/ui/form/input/input</code> · <a href="/core/components/ui/form/input">full page</a></p>
+  <p>sonic-input wraps a native &lt;input&gt; with a label, a description, prefix and suffix slots and Concorde sizes. Native attributes (type, placeholder, pattern, min, max, …) are passed through. Bind the val</p>
+  <pre class="doc-excerpt">Input
+
+sonic-input wraps a native   with a label, a description, prefix and suffix slots and Concorde sizes. Native attributes (type, placeholder, pattern, min, max, …) are passed through. Bind the value to a store with formDataProvider and name, set on the field or on an ancestor.
+
+Basic example
+
+Type
+
+With no type, the input is text. Text-like types (email, password, date, number, color, search, …) are supported; radio, checkbox and range have dedicated components. password adds a visibility toggle.
+
+Size and status
+
+With no size, the input uses the base scale. status colors the field; it defaults to default.
+
+Validation
+
+required, pattern, minlength and the native type rules are checked by the browser. Feedback styles apply once the field is touched (after blur).
+
+Prefix and suffix
+
+Slotted content sits outside the field by default. Set inlineContent to draw it inside; clicking it then focuses the input unless disableInlineContentFocus is set.
+
+         4 max
+
+Form data
+
+Fields sharing the same formDataProvider and name stay in sync. The attribute is looked up on ancestors, so set it once on a wrapper.
+
+sameValueAs sets pattern to the value of another field in the same store, fo</pre>
+</section>
+<section id="core-components-ui-form-radio-radio" data-doc-id="core/components/ui/form/radio/radio">
+  <h2><a href="/core/components/ui/form/radio">Radio</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/ui/form/radio/radio</code> · <a href="/core/components/ui/form/radio">full page</a></p>
+  <p>sonic-radio is a round Checkbox in radio mode: radios sharing a name under one formDataProvider store a single value, and a checked radio cannot be unchecked by a click. Label goes in the default slot</p>
+  <pre class="doc-excerpt">Radio
+
+sonic-radio is a round Checkbox in radio mode: radios sharing a name under one formDataProvider store a single value, and a checked radio cannot be unchecked by a click. Label goes in the default slot or label, helper text in the description slot.
+
+Basic example
+
+       Window
+       Aisle
+       Seat:
+
+Size
+
+With no size, the radio follows md (1rem).
+
+       2xs
+       xs
+       sm
+       Default
+       lg
+       xl
+       2xl
+
+Checked and disabled
+
+checked sets the initial state. disabled blocks interaction and dims the control.
+
+       Checked
+       Disabled
+       Disabled and checked
+       I accept the  terms
+
+Filtering a list
+
+The radio group writes one status value to the store used as dataFilterProvider by a sonic-queue. See Checkbox for the multi-value version.
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| name | string | Key in the form data (dot notation supported) |
+| value | string | Value stored when checked |
+| formDataProvider | string | Form data id; inherited from the closest ancestor when omitted |
+| checked | boolean | Initial checked state |
+| unsetOnDisconnect | boolean | Removes the value from the data wh</pre>
+</section>
+<section id="core-components-ui-form-select-select" data-doc-id="core/components/ui/form/select/select">
+  <h2><a href="/core/components/ui/form/select">Select</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/ui/form/select/select</code> · <a href="/core/components/ui/form/select">full page</a></p>
+  <p>sonic-select wraps a native &lt;select&gt; with a label, a description, prefix and suffix slots and Concorde sizes. Options come from child &lt;option&gt; tags or from the options attribute (JSON). Bind the value</p>
+  <pre class="doc-excerpt">Select
+
+sonic-select wraps a native   with a label, a description, prefix and suffix slots and Concorde sizes. Options come from child   tags or from the options attribute (JSON). Bind the value to a store with formDataProvider and name, set on the field or on an ancestor.
+
+Basic example
+
+       No selection
+       Economy
+       Premium
+       Business
+       First
+
+Options
+
+options takes an array of objects; valueKey (default value) and wordingKey (default wording) name the keys to read. An option with selected sets the initial value; with no value and nothing selected, the first option is used.
+
+Size and status
+
+With no size, the select uses the base scale. status colors the field; it defaults to default.
+
+        2xs
+        xs
+        sm
+        default
+        lg
+        xl
+        2xl
+        success
+        error
+        warning
+        info
+        primary
+        disabled
+
+Filtering a list
+
+name=&quot;direction&quot; writes to the store used as dataFilterProvider by a sonic-queue, which sends it as ?direction= to the mock API: switch between departures and arrivals.
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| name | string | Key in th</pre>
+</section>
+<section id="core-components-ui-form-switch-switch" data-doc-id="core/components/ui/form/switch/switch">
+  <h2><a href="/core/components/ui/form/switch">Switch</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/ui/form/switch/switch</code> · <a href="/core/components/ui/form/switch">full page</a></p>
+  <p>sonic-switch is a toggle-styled Checkbox in unique mode: when on, it stores its value under name in the formDataProvider data; when off, it stores null. Switches sharing a name behave as one choice, s</p>
+  <pre class="doc-excerpt">Switch
+
+sonic-switch is a toggle-styled Checkbox in unique mode: when on, it stores its value under name in the formDataProvider data; when off, it stores null. Switches sharing a name behave as one choice, so give independent switches distinct names. Label goes in the default slot or label, helper text in the description slot.
+
+Basic example
+
+        Notifications
+         Get an alert when your gate changes.
+
+       Value:
+
+Size
+
+With no size, the switch follows md (1rem).
+
+       2xs
+       xs
+       sm
+       Default
+       lg
+       xl
+       2xl
+
+Checked and disabled
+
+checked sets the initial state. disabled blocks interaction and dims the control.
+
+       Checked
+       Disabled
+       Disabled and checked
+       I accept the  terms
+
+Filtering a list
+
+On, the switch writes status=delayed to the store used as dataFilterProvider by a sonic-queue; off, it writes null and the filter is dropped.
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| name | string | Key in the form data (dot notation supported) |
+| value | string | Value stored when on |
+| formDataProvider | string | Form data id; inherited from the closest ancestor when omitte</pre>
+</section>
+<section id="core-components-ui-form-textarea-textarea" data-doc-id="core/components/ui/form/textarea/textarea">
+  <h2><a href="/core/components/ui/form/textarea">Textarea</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/ui/form/textarea/textarea</code> · <a href="/core/components/ui/form/textarea">full page</a></p>
+  <p>sonic-textarea wraps a native &lt;textarea&gt; with a label, a description and Concorde sizes. Native attributes (rows, cols, maxlength, wrap, …) are passed through. Bind the value to a store with formDataP</p>
+  <pre class="doc-excerpt">Textarea
+
+sonic-textarea wraps a native   with a label, a description and Concorde sizes. Native attributes (rows, cols, maxlength, wrap, …) are passed through. Bind the value to a store with formDataProvider and name, set on the field or on an ancestor.
+
+Basic example
+
+Rows and resize
+
+rows sets the visible height. With no resize, the user can resize vertically only.
+
+Size and status
+
+With no size, the textarea uses md. status colors the field; it defaults to default.
+
+Validation
+
+required, minlength and maxlength are checked by the browser. Feedback styles apply once the field is touched (after blur).
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| name | string | Key in the form store (dot notation allowed) |
+| value | string | Initial value |
+| formDataProvider | string | Store id; inherited from the closest ancestor |
+| label | string (HTML) | Label; or use the label slot |
+| description | string (HTML) | Help text under the field; or use the description slot |
+| placeholder | string | Native placeholder |
+| size | 2xs … 2xl (default md) | Typography and padding |
+| status | default · success · error · warning · info | Field color |
+</pre>
+</section>
+    </article>
+  </main>
+</body>
+</html>